mirror of
https://github.com/Sea-Haven-Industries/shoc-backend.git
synced 2026-09-30 09:33:13 +00:00
69 lines
2.9 KiB
Markdown
69 lines
2.9 KiB
Markdown
# 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.
|