Skip to content

SGE Change Protocol ​

Every change in this repo follows the SGE (Specification-Governed Development) 7-step protocol, so code traces back to an approved spec and the audit trail is complete. Scaffolded by /sge:sge-init — tailor the wording to this repo.

The 7 steps ​

  1. LOCATE — find the spec(s) and capability the change serves (docs/features/ / capability model).
  2. READ — start from the generated digest (docs/sge-digest.md, the ≤2K-token default governance read), then read on demand the full spec, its Gherkin acceptance criteria, and dependencies whose scope the change touches. CRITICAL paths (security/auth, migrations, multi-tenant) still take the full read deliberately.
  3. IMPACT — assess blast radius: which specs, capabilities, tests, and downstream repos are affected.
  4. PROPOSE — write the plan (TDD slices) before code.
  5. IMPLEMENT — build with TDD: failing test → minimum code → refactor.
  6. TEST — full quality suite green (lint, type-check, unit/integration/contract, coherence gate).
  7. UPDATE — keep specs, ADRs, and docs in lockstep with the code.

Spec status ​

Each spec's front matter has one status. Move it when the thing it names happens, in the same change.

StatusMeaning
draftNot yet agreed. May be a placeholder that records gates (SPEC-002).
approvedThe Product Owner agreed the scope. Code may be partly or fully built, but the exit test has not passed.
implementedThe Product Owner ran the spec's exit test on real data and it passed (CLAUDE.md "Definition of done").
supersededReplaced by a newer spec, named in the front matter.

docs/ROADMAP.md tracks what is built and what is left under each spec; the status here is only about agreement and the exit test.

Commit trailer (traceability) ​

Every commit must carry exactly one of these trailers — enforced by the commit-msg hook (.githooks/commit-msg, or .husky/commit-msg where this repo uses husky):

  • Spec: SPEC-NNN (or SGD-NNN) — the feature spec this commit implements.
  • SGE-Override: <STEP>; <reason ≥10 chars> — an intentional bypass, for a governance / infra / docs change that maps to no single feature spec. STEP ∈ { LOCATE, READ, IMPACT, PROPOSE, IMPLEMENT, TEST, UPDATE, ALL }. Logged for audit.

The full trailer semantics (when each applies, the one-trailer rule, never --no-verify) are canonically documented in the /sge:commit skill — commit through it and the right trailer is emitted automatically.

Agent-Id: is a separate attribution trailer. /sge:commit adds it only when the session has an agent identity (SGE_AGENT_ID, minted for a spawned agent). An interactive Claude Code session has none, so these commits carry no Agent-Id:. That is expected, not drift, and /sge:sge-align should not count it as a finding here.

Database migrations (expand, then contract) ​

A migration touches production data on the next deploy, and the previous release may be started again on the new schema (ADR 0029). So every schema change follows these rules. The full reasoning is in ADR 0029 and docs/plans/deploy-hardening.md ("Migration rules").

  1. Every migration works with both the current and the previous app. A release may only expand: new tables, nullable columns or columns with a constant default, new indexes, new policies, additive data.
  2. Contract changes wait at least one release, until no deployed code reads the old shape: drop a table or column, rename, change a type, set not null, tighten a constraint (named or not), narrow or change a policy, delete data (including a principal or a grant). Each carries a -- contract: #<issue> line in the file's header comment and runs behind the pre-deploy backup. Dropping a not null loosens a constraint, so it is an expand.
  3. A rename is spread over several releases: add the new one, dual-write, backfill, switch reads, then drop the old one.
  4. Every statement is guarded or idempotent, because every file is re-applied on every deploy: if not exists, if exists, on conflict … do nothing (an alter table [if exists] only with add … if not exists, drop … if exists, alter column … drop not null or enable row level security actions), or one of grant, revoke, alter default privileges, alter table … enable row level security, create or replace function, or a do $$ … $$ block that tests its own condition (reviewed by hand).
  5. Migration files are append-only. Never edit, rename or delete one that has reached main; add a new numbered file.
  6. policies.sql and bootstrap.sql are re-applied on every deploy, so rules 1, 2 and 4 cover them too. A new destructive statement in one of them needs -- contract: #<issue> directly above it. policies.sql drops and re-creates a policy only when it is missing or its definition differs from the file's, so it also repairs a policy that a restored backup brought back with an older body. A changed or removed policy is still a numbered migration, and policies.sql is updated to match. A legacy policy that must stay dropped on a restored database is dropped by a numbered migration too (0009 does this for ledger_write).
  7. Role passwords are set only by migrate-cli, as client-computed SCRAM verifiers, never as a plain literal.
  8. No new migrations while .migration-freeze exists (plan slice 2b to 2c).

pnpm lint:migrations (scripts/check-migrations.ts) checks rules 2, 4, 5, 6 and 8 against origin/main, and verify runs it on every change. Files 0000 to 0008, on main before the lint, are grandfathered for the contract and guard checks. Rules 1 and 3 rest on review and the N-1 check: on a pull request that changes a migration, policies.sql, bootstrap.sql, the migrate or role code or db:setup, the n1-compat job builds the schema from the pull request (pnpm db:setup) and runs origin/main's database tests against it (scripts/n1-compat.sh, issue #74). A red n1-compat means the previous release would break on the new schema: split the change into an expand now and a contract later. The job refuses a branch that is behind origin/main (a local run, or a merge ref older than main), so merge origin/main first.

Enforcement ​

  • commit-msg hook (.githooks/commit-msg) — blocking since 2026-10-03: a commit without a Spec: or SGE-Override: trailer is refused. Each clone runs git config core.hooksPath .githooks once. Commits made on the GitHub web page (merges) never run it. tests/infra/commit-msg-hook.test.ts pins it. Only what git itself writes skips the trailer, judged on the subject line: merges, fixup!, squash!, amend! and reverts. Squash-merged commits on main have no Spec: trailer, so cherry-picking or rewording one needs an SGE-Override (never --no-verify).
  • SGE_ENFORCE=tdd in .claude/settings.json — the SGE plugin's tdd-guard hook refuses an Edit or Write to a production file in Claude Code until the session has shown test evidence. .sge/test-map.yml says what is what:
    • Guarded: src/**/*.ts, src/**/*.sql (migrations, policies), scripts/** code, build/**/*.mjs and the NAS deploy programs under infra/nas/. The Dockerfile is not guarded.
    • Never blocked: documents, JSON and YAML, CI, the commit hook, config files (*.config.ts, *.config.js), the semgrep rules and fixtures, benchmarks, snapshots and everything under tests/.
    • Evidence is editing a file under tests/, running pnpm test, pnpm exec vitest or npx vitest, or a test file already sitting next to the source file (src/foo.test.ts). corepack pnpm … is not recognised as a test run, so use pnpm (run corepack enable once).
    • It is a nudge with teeth, not a hard gate. It sees only Edit and Write: an edit made through a shell command (sed -i, a redirect) or MultiEdit is not checked, and one test edit unblocks every later source edit in that session. The commit hook and verify are what hold.
  • pnpm lint:migrations in verify — blocks a change that breaks the migration rules above.
  • Alignment (/sge:sge-align) is a check you run, not a CI gate. The plugin ships no gate that fits this repo: its coherence and DAG workflows are written for the plugin's own layout, and the plugin treats them as advisory. Run /sge:sge-align at the end of a slice and before a release, and fix what it finds. Whether to add a repo-owned check to verify is open (see docs/sge/questions.md).