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
+8 -9
View File
@@ -16,8 +16,9 @@ into bites small enough that a subagent can execute one in
2-5 minutes without making judgement calls outside its remit.
Plans live under `docs/plans` with the fixed name shape
`NNNN-slug.md` — a 4-digit counter per directory (see
`docs/conventions.md`). The header references the parent spec. The plan
`slug.md` — a short kebab-case topic slug, no numeric prefix (see
`docs/conventions.md` § Naming). `docs/plans` is git-ignored; the plan
is a working file, never committed. The header references the parent spec. The plan
decomposes work into tasks; each task is the unit of review
(spec-compliance and quality gates inside `implement`), not
the unit of commit. Commits are an orchestrator-only decision
@@ -226,16 +227,14 @@ Fix issues inline.
### Step 6 — Hand off
The plan sits in the working tree as an unstaged file under
The plan sits in the working tree as a git-ignored working file under
`docs/plans`. Hand off to `implement` with: path to the
plan file + optional task focus ("only Tasks 1-3 this run").
The orchestrator commits the plan when handing it forward
(suggested commit subject: `plan: <iteration> <subject>`).
The planner skill does not perform the commit itself. Like the spec,
the plan is an ephemeral active-cycle artefact: committed for its own
cycle and `git rm`'d at cycle close (see `docs/conventions.md`
§ Lifecycle).
The plan is **never committed**. Like the spec, it is a git-ignored
active-cycle working file: present on disk for its own cycle and
shell-`rm`'d alongside the spec at cycle close by `audit` (see
`docs/conventions.md` § Lifecycle).
## Handoff Contract