adam/shoc-backend
1
0
Fork 0
mirror of https://github.com/Sea-Haven-Industries/shoc-backend.git synced 2026-09-30 03:43:11 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1
shoc-backend/AGENTS.md
Adam Moussa b7b22a8893
chore(repo): add PR template and README, retire stale root files 
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.
2026-09-18 19:05:30 -04:00

2.9 KiB
Raw Blame History

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

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 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.