adam/shoc-backend
1
0
Fork 0
mirror of https://github.com/Sea-Haven-Industries/shoc-backend.git synced 2026-09-30 10:43:13 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1
shoc-backend/AGENTS.md

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