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
+32 -26
View File
@@ -268,10 +268,10 @@ it as a target, not verified fact.
### Step 3 — Write the spec
Path: under `docs/specs`, named per the fixed naming convention —
`NNNN-slug.md`, 4-digit per-directory counter (see
`docs/conventions.md`). Determine the next free number by scanning the
directory.
Path: under `docs/specs`, named `slug.md` per the fixed naming
convention (see `docs/conventions.md` § Naming) — a short kebab-case
topic slug, no numeric prefix. The directory is git-ignored; the spec is
created there and never `git add`'d.
Structure:
@@ -377,22 +377,23 @@ spec file; nothing slips between it and the commit.
Outside `/boss` the signature is the user's; under `/boss` it is the
Step-5 `grounding-check` `PASS` (the `/boss` subsection below).
The spec sits in the working tree as an unstaged file. Tell the user:
The spec sits in the working tree as a git-ignored working file. Tell
the user:
> Spec written to `<path>` (uncommitted). Please review it and let me
> know if you want changes before we start the implementation plan.
> The orchestrator will commit it once you approve.
> Spec written to `<path>` (git-ignored, never committed). Please review
> it and let me know if you want changes before we start the
> implementation plan.
Wait for the user's response. If they request changes, edit the file
in place (still uncommitted), **re-run Step 4 AND re-dispatch Step 5**
in place, **re-run Step 4 AND re-dispatch Step 5**
(the previous PASS report no longer covers the edited bytes), then
return here. Only proceed after approval AND a fresh Step 5 PASS.
The orchestrator commits the approved spec after sign-off (suggested
commit subject: `spec: <cycle> <topic>`). The skill does not perform
the commit itself. The spec is an ephemeral active-cycle artefact: it
lives in the repo only for its own cycle and is `git rm`'d at cycle
close (see `docs/conventions.md` § Lifecycle).
The spec is **never committed**: it is a git-ignored active-cycle working
file that lives on disk only for its own cycle and is shell-`rm`'d at
cycle close by `audit` (see `docs/conventions.md` § Lifecycle). The
durable record of its design intent is the design ledger, lifted during
audit — not the spec file.
**In `/boss` (autonomous):** `specify` is dispatched autonomously — it
is bounded (no interview), so there is no user at this gate to take the
@@ -404,11 +405,13 @@ adversarial panel**, no objective-gates-then-panel staging, no
self-correction loop; those were retired in favour of decide-upstream +
recover-downstream (baseline tag `pre-autosign-rework`).
- On a Step-5 **`PASS`**: commit the spec yourself (subject `spec:
<cycle> <topic> (boss-signed)`), fire the auto-sign notify (see `boss`
§ Notifications — it names the capability in user terms and states the
plan is proceeding and a reply vetoes), then proceed to Step 7. No
pause.
- On a Step-5 **`PASS`**: the spec is signed by the PASS — leave it as a
git-ignored working file (never committed). Record the autonomous sign
on the run's reference issue (a decision-log comment: which capability,
that the `grounding-check` PASS was the signature, that no human
signed), fire the auto-sign notify (see `boss` § Notifications — it
names the capability in user terms and states the plan is proceeding
and a reply vetoes), then proceed to Step 7. No pause.
- On a Step-5 no-override **`BLOCK`** or **`INFRA_ERROR`**: there is no
human to override it, so it routes to the human sign-off pause — a
problem-state notify ("spec X needs your sign-off") — exactly as the
@@ -435,13 +438,16 @@ leaning. This is a *tool it reaches for*, not a gate it must clear: the
lens returns a finding, the orchestrator decides. Carrier and lenses are
defined in `agents/spec-skeptic.md`.
**Auto-sign commits on `main` are forward-only — with one `/boss`
exception.** A later user veto is normally a forward correction (revert /
revised spec / `git checkout` of downstream work). The `/boss` rollback
sandbox is the exception: within an autonomous run the orchestrator may
hard-reset its own *unpushed* autonomous commits back toward (never
below) the session anchor when it has run into a dead end — its own work
only. See `boss` § Direction freedom for the exact boundary.
**Auto-signed CODE commits on `main` are forward-only — with one `/boss`
exception.** The spec itself is never a commit (it is a git-ignored
working file), so a later user veto is a forward correction: shell-`rm`
(or edit) the git-ignored spec, and `git revert` / `git checkout` only
the downstream **code** it produced. The `/boss` rollback sandbox is the
exception: within an autonomous run the orchestrator may hard-reset its
own *unpushed* autonomous code commits back toward (never below) the
session anchor when it has run into a dead end — its own work only, and
it shell-`rm`s the git-ignored spec/plan of the abandoned line. See
`boss` § Direction freedom for the exact boundary.
### Step 7 — Hand off to `planner`