mirror of
https://github.com/Sea-Haven-Industries/shoc-backend.git
synced 2026-10-01 12:13:13 +00:00
Adam Moussa
b7b22a8893
The org PR template pre-filled Summary / Validation / Tests / Notes here while REVIEW_AND_PR_FRAMEWORK.md section 8 prescribes Summary / Changes and value / Ticket. A repo template now overrides the org one, and the framework notes the divergence from the org pr-policy workflow, which is not wired in. README.md orients a reader: environments, architecture in one line, project map, local commands, the governance gate, deployment, and a documentation map. Cleanup: TODO.md is removed because Jira owns work status and its items are stale or done. BACKEND_ARCHITECTURE.md is removed as superseded; the two references now point at git history. .env.example loses its BOM and mojibake dashes. .gitattributes keeps its one active rule.
68 lines
2.9 KiB
Markdown
68 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, 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.
|