shoc-backend/AGENTS.md

# AGENTS.md — SeaHaven backend (repo-specific delta)

This file is the **repo-specific delta** for the Seahaven backend. It layers on
top of the operator/workspace agent baseline and does not repeat it. This file
may add stricter backend rules but may never weaken the workspace baseline.

## Canonical governance documents (precedence)

1. `ARCHITECTURE_AND_CODE_QUALITY.md` — *what* the rules mean (canonical).
2. `QUALITY_GATES.md` — *how* rules are enforced (commands + CI mapping).
3. `REVIEW_AND_PR_FRAMEWORK.md` — *who* reviews, in what order, with what
   evidence.

When these conflict with each other, the one that *owns* the topic wins
(meaning → architecture doc; execution → quality gates; process → review
framework). When unsure, ask; do not silently pick.

## Architecture in one line

```text
Controller -> I{Feature}Service -> I{Feature}DataService -> ApplicationDbContext
```

- Controllers depend on `I{Feature}Service` only — never `DbContext`/EF/concrete
  services/data services.
- Business services depend on feature-specific data/query/command interfaces —
  never `DbContext`, never `IConfiguration`, never a generic repository.
- Data services own EF; EF/`DbContext` lives only on the documented
  infrastructure allowlist (data services, `ApplicationDbContext`, migrations,
  Identity/composition, transactions inside data services).
- One commit convention: `SaveChangesAsync(CancellationToken)` inside the owning
  data service is the atomic boundary; explicit transactions stay inside data
  services.
- Tenant scope is server-derived; authorization is enforced at service entry.
- No HTTP response leaks exception/stack/SQL/credential/crypto detail; secrets
  are never logged.

Full detail: `ARCHITECTURE_AND_CODE_QUALITY.md`.

## Running the complete gate (local == CI)

```bash
bash scripts/governance-check.sh
```

The command restores, verifies architecture and changed-file formatting, builds
Release, runs the full test suite, and validates Terraform. CI (`ci.yml`)
calls the same script from the `architecture` job (skipping G4/G5) and
aggregates results as `ci-complete`. See `QUALITY_GATES.md`.

## Hard rules (deviation needs an ADR; no wildcard suppressions)

- EF allowlist, dependency direction, no client exception disclosure,
  server-derived tenant scope, one commit convention, cancellation forwarding
  (verified, not just signed).
- Suppress a single diagnostic with a cited ADR only — never global sweeps.
- See `ARCHITECTURE_AND_CODE_QUALITY.md` §10 for the ADR exception process.

## Do not touch without explicit instruction

- Product behavior, database **migrations**, secrets, dependency versions, and
  files unrelated to the current task.
- The `.ai-config-kit-sidecar-write-scope` marker file is a transient
  authorization artifact — **never commit it**.

## Reporting

State every changed file with a one-line summary. Report each gate as
pass / fail / skipped / not-run with evidence; never infer a pass from silence.