contract

compass:contract

The contract is the single source of truth — the invariant every later step is checked against. A vague contract guarantees drift. Interview until airtight, then write contract.md. (Entry point — no prerequisite gate.)

Read these before you start. They are the standards this stage is held to, and they live in plugins/compass/shared/ so they are the same for every stage that uses them:

• shared/feynman.md — the writing standard for the reader-facing copy this stage produces.

(A standard nobody loads is not a standard. shared/MANIFEST declares who reads each file and doctrine-wired-check.sh proves it — feynman.md sat unread for three releases while its own first line claimed three stages loaded it.)

1. Folder, index, facets

• Create the folder with compass.sh new-build <slug> — never mkdir. It writes <dir>/.compass-format, the stamp that arms mode-gate and redfirst-check. That stamp is deliberately a file the contract stage cannot author: an earlier design used a compass-format: header, the model wrote it, and omitting one line disarmed the gate. A dir made by hand is refused by contract-gate at the first seam.
• Then populate <state-root>/<slug>/ (resolve <state-root> via compass.sh state-root). Write the slug to <state-root>/CURRENT (a non-authoritative hint only — resume disambiguates by worktree, not this file); append to <state-root>/INDEX: <slug> · <goal> · status=draft · facets=<…> · touches=<rough paths, refined by plan>.
• Isolation (REQUIRED iff this build may run in PARALLEL and touches DB schema): declare isolation.db_provision and isolation.db_teardown shell commands that stand up / tear down a per-worktree database (e.g. a fresh Postgres schema, emitting its DATABASE_URL into the worktree's .env.compass). Without this, compass.sh check-db-isolation REFUSES a schema-touching parallel build — concurrent migrations on one shared dev DB corrupt the migration history. Mark N/A for single-build or no-schema builds.
• schema-touching: yes|no (REQUIRED, v0.7.0): a header field declaring whether this build changes DB schema. yes → build/review-build/ship run compass.sh migration-gate (STRICT: a real migration in the deploy's canonical dir must reproduce the schema on a fresh DB; db execute/hand-apply, stray dir, or replay-fail = FAIL). For non-Prisma tools add a ## Migration recipe block (canonical_migrations_dir, migrate_diff_cmd, migrate_deploy_fresh_cmd). no → migration-gate is N/A. Silent omission = the gate refuses to run.
• destructive-backfill: yes|no + env-keys-referenced: <KEY … | none> (+ prod-keys: <KEY …>) — machine-readable prod-safety signals (v0.15.0, REQUIRED for F-RESTORE/F-PARITY): the ship stage's compass.sh restore-point / config-parity HARD STOPs read THESE header fields (not the prose §Rollout/§Security blocks below), so the interview MUST write them. destructive-backfill: yes — a row-rewriting/deleting backfill even when schema-touching: no — makes restore-point demand a confirmed snapshot. env-keys-referenced: names the env keys the change newly references; when it is non-none, prod-keys: names the keys prod declares, and config-parity HARD-STOPs on any referenced key prod lacks. Write destructive-backfill: no + env-keys-referenced: none for the common case — silent omission leaves both gates with no signal, so they N/A-pass: the exact soft-pass this floor exists to kill. A NON-destructive value backfill (populates/adds without deleting) is declared backfill: yes|no; backfill: yes (or destructive-backfill: yes) makes compass.sh backfill-recon-gate (v0.21) require a recorded backfill-recon: count + checksum tie-to-source step before the migration is done.
• schema-pin: <field-schema block-ref | N/A — <reason>> + perf-budget: <p95/peak-mem/cost literals + SLO ranges | N/A — <reason>> — machine-readable data/perf pins (v0.21.0, REQUIRED for INV-SCHEMA-PIN / INV-PERFBUDGET): compass.sh schema-pin-gate / perf-budget-gate ride the contract gate seam and read THESE header lines (guard-first N/A-pass on a missing contract.md or an absent header — legacy contracts stay byte-identical). When schema-touching: yes, the contract MUST carry a filled field-schema block — a markdown table with columns name · type · nullable · unit/enum · example plus an evolution-rules: line (web adds endpoint · method · request · response · status · error-envelope, or cites an existing OpenAPI/Prisma artifact) — or an explicit schema-pin: N/A — <reason> for a non-schema build (the plugin's own contract writes schema-pin: N/A since it changes no runtime schema; the gate then bootstraps clean). When Scale is non-trivial, perf-budget: MUST pin literal p95 latency + peak-mem + cost and attach an SLO healthy-range; a bare perf-budget: N/A (no reason) FAILS — write perf-budget: N/A — <reason> for a trivial-scale build. Also write pii: yes|no (a customer-PII / financial-record surface) and ci: yes|no (the repo runs CI): pii: yes makes compass.sh pii-gate (plan seam) require a compliance/PII: plan line, and ci: yes makes compass.sh green-ci-gate (review-build seam) require a recorded green-CI merge proof — both N/A-pass when the header is no/absent.
• deploy: out-of-scope — <reason> (optional): ship is MANDATORY unless this exact line is present. Without it, a build cannot reach a final state without compass:ship (enforced by lifecycle-audit + the Stop hook).
• Project facets (one OR MORE — composable): web · pipeline · library. A CRM with a data sync is web + pipeline → both facets' sections and verify rungs apply. (touches here is a coarse pre-filter; plan rewrites it with the real file list.)
• Optional budget: token/time ceiling for the whole build (Compass surfaces "approaching budget" rather than grinding silently).
• v0.12/v0.13 headers the interview ALWAYS writes (authoring-time defaults — legacy contracts without them stay byte-identical):
  • post-ship-loop: on (clean 2 / cap 5) for every shipping build (opting out requires post-ship-loop: off — <reason>); with 0+ post-ship-check: <cmd> lines pinning domain checks as commands, and one observation-channel: <facet> = <capture command / viewport spec / digest cmd> line naming HOW the live system gets observed (declare blindness HERE — OAuth-gated/air-gapped — not at ship time). Optional observation: strict-design makes design drift material without a contract cite.
  • cold-critic: on for every web-facet build (2×cold-GO gate at build/review-build; waive only via cold-critic: off — <reason>; optional cold-critic-fallback: human-eyeball for un-screenshotable apps).
  • mode-asked: required (v0.28.0) — ALWAYS write this header. It arms compass.sh mode-gate on the contract gate seam, which then refuses a receipt whose mode line is missing or not marked asked=yes. Legacy contracts have no such header and stay byte-identical (guard-first N/A-pass).
  • intake: co-construct-v1 when the interview below ran interactively; intake: classic when a headless/--auto session had to fall back (an auto session NEVER authors intake.md — F-AUTODEGRADE).
  • program: <program-name> · <phase-id> (v0.22.0, optional) — write it when this build is one phase of a multi-build program (e.g. program: compass-3-phase · build 7a). The ship stage's guarded program-advance and go/resume's next-phase offer read this header; a build with no program: line is byte-inert (standalone). Absent = standalone, no ledger interaction.
  • adds-test: <yes|no> (v0.22.0) — yes when the build adds/changes a test; then the build receipt MUST carry a real red-green: line (the failing test + why it failed BEFORE the fix) which compass.sh redgreen-check requires (empty/placeholder FAILS). no/absent is byte-inert. Optional mutation: <INV-id · file= · break= · red=> recipe lines let compass.sh mutation-check PROVE a guard's test bites.
  • Durability nits (v0.23.0, template defaults — legacy contracts unaffected): every contract carries a ## Glossary (domain terms → plain meaning), an alternatives-considered: line (what else was weighed + why-not — the ADR trace), one-way-door: labels on irreversible steps (so a reader sees what can't be undone), and a RACI: owner line (Responsible / Accountable / Consulted / Informed). Template-presence only — no rejection gate (a contract missing them is not blocked; the interview just always seeds them so a fresh reader gets the context).