mirror of
https://github.com/Sea-Haven-Industries/shoc-backend.git
synced 2026-09-30 08:23:12 +00:00
833fb816ee
* docs(governance): add canonical governance docs, unified quality-gate script, and CI parity - ARCHITECTURE_AND_CODE_QUALITY.md: canonical layering, EF allowlist, transaction/commit convention, cancellation, migrations, error disclosure, Big-O/perf, ADR exceptions (supersedes BACKEND_ARCHITECTURE.md) - QUALITY_GATES.md: gate inventory + pass/fail/skip semantics; local==CI - REVIEW_AND_PR_FRAMEWORK.md: exact-head review, board-backed regression inventory, security/perf evidence, ADR exceptions, no godfile theater - AGENTS.md: repo-specific delta + precedence pointers - scripts/governance-check.sh: unified G1 restore + G2 ArchitectureTests + G3 changed-file format (portable bash) - .github/workflows/architecture-quality.yml: call the same local script - ArchitectureTests.cs: add business-service interface-dependency invariant * fix(governance): make backend gate complete * fix(ci): enforce governance on every pull request
70 lines
3 KiB
Markdown
70 lines
3 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;
|
|
supersedes the older `BACKEND_ARCHITECTURE.md`, which is retained only as
|
|
historical reference).
|
|
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, and runs the full test suite. CI (`architecture-quality` workflow)
|
|
calls the same script. 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.
|