refactor(pipeline): specs/plans are gitignored working files, never committed

Per-cycle specs and plans stop being git-tracked commit-then-git-rm
artefacts and become git-ignored working files: created on disk for the
active cycle, read across sessions from the working tree, and shell-rm'd
at cycle close by audit. Nothing is committed, so there is no
git-history copy — the durable record of a cycle's intent is the design
ledger only, and no durable artefact (code, test, doc, ledger) may cite
a spec/plan by number or path.

- conventions/pipeline/design/README: invert the git-tracked -> git-rm
  -> git-history-recovery model to gitignored -> shell-rm -> ledger-only.
- naming: drop the NNNN file counter; files are slug.md (fieldtest specs
  keep a fieldtest- prefix as the cycle-close discriminator).
- cycle number: separated from the (now-gone) file number, sourced from
  the feat(NNNN)/audit(NNNN) commit subjects, which cycle commits carry.
- specify/planner/fieldtest/fieldtester: no commit step; fieldtest splits
  fixtures (committed as code) from its spec (gitignored), with the
  cross-cycle rule that a fieldtest- spec belongs to the next cycle.
- boss: auto-sign auditability moves from the (boss-signed) commit
  subject to the run's reference issue; rollback reverts only code.
- audit: new Step 5 shell-rm's the cycle spec+plan after the architect
  reads them, sparing fieldtest- specs.

Companion machine config (outside this repo): the global git excludes
(~/.config/git/ignore) gains docs/specs/ and docs/plans/ so the ignore
applies to every project at once.
This commit is contained in:
2026-07-02 11:35:06 +02:00
parent 1a1077b7f7
commit 08bc2aa027
10 changed files with 185 additions and 105 deletions
+26 -1
View File
@@ -51,7 +51,9 @@ For cycle <X>: read the project's design ledger, if it has one
(its CLAUDE.md project facts), walk its contracts;
`git log <prev-close>..HEAD --format=full` for the cycle's
iter and audit commit bodies; `git diff <prev-close>..HEAD`
for the diff; report drift.
for the diff; read the cycle's spec at `docs/specs/<slug>.md`
if one exists (a git-ignored working file — read it from disk,
not git); report drift.
```
Architect produces a prioritised drift list (see
@@ -120,6 +122,29 @@ The orchestrator picks per item:
Red Flags, "about to return clean without having read the diff in
full"; the gate verifies it rather than trusting the status.)
### Step 5 — Discard the cycle's spec and plan
Once the cycle is drift-clean (or the drift is ratified) and the
architect has read the spec, the cycle's spec and plan have served their
purpose. Discard them from the working tree with a plain shell `rm`:
```
rm -f docs/specs/<slug>.md docs/plans/<slug>.md
```
This is a shell delete, NOT `git rm` — the files are git-ignored and were
never committed, so nothing is staged and the audit-close commit carries
only code and ledger changes. **Ordering is load-bearing:** the
architect's read (Step 1) must precede this delete, because a git-ignored
spec has no `git show` recovery once it is gone.
**Spare any `fieldtest-`-prefixed spec.** A `fieldtest-<slug>.md` under
`docs/specs` belongs to the *next* cycle (it is the input to its
`planner`), so it is not this cycle's to discard — leave it for the next
cycle's close. If this cycle is itself a milestone close with no
following `planner`, discard the fieldtest spec too (see
`../fieldtest/SKILL.md`).
## Handoff Contract
`audit` hands to the orchestrator: