docs: make specs/plans git-tracked and transient — retired via git rm at cycle close

docs/specs and docs/plans hold only the active cycle's artefacts: a spec/plan is committed while its cycle is live and git-rm'd in the cycle-close commit (after audit drift-clean), so HEAD shows only in-flight work while git history keeps the full text. No issue-posting, no gitignore branch — git history + the design ledger are the durable record.

Rewrites conventions.md § Lifecycle as the single source of truth; pipeline.md, design.md, README.md, specify, planner, glossary, brainstorm, issue, and the CLAUDE.md fragment follow it. Naming stays NNNN-slug.md (a within-cycle handle; recycling on an emptied directory is fine).

README.md

@@ -112,6 +112,9 @@ skills and documented once in `docs/conventions.md`: spec dir
 `docs/specs`, plan dir `docs/plans`, 4-digit per-directory naming,
 the vocabulary above, standing reading (`CLAUDE.md` + `git log -10`),
 git discipline, Gitea + `closes #N`, and the whole pipeline graph.
+Specs and plans are ephemeral — git-tracked, held only for the active
+cycle, then `git rm`'d at cycle close; git history keeps the record
+(`docs/conventions.md` § Lifecycle).
 
 The handful of facts that genuinely vary per project live in the
 project's own `CLAUDE.md` under `## Skills plugin: project facts`:

brainstorm/SKILL.md

@@ -170,7 +170,7 @@ The production gates live there, not here.
 | "Cycle is small, two iterations, no spec needed" | Iteration count isn't the metric — feature surface is. A two-iter feature touching design-ledger invariants needs a spec; a CLI flag does not. Assess what the feature changes in invariants. |
 | "Three approaches in, none feel right, ship the least bad" | Three unsatisfying approaches usually means the problem is mis-framed. Stop, capture the three approaches and what fails about each in the spec's design notes (or escalate to the user), sleep on it. End-of-day pressure is the worst signal to resolve a design fork. |
 | "User is busy, present my own design without Q&A" | Reactive deference disguised as decisiveness. The Q&A surfaces constraints the user hasn't articulated; skipping it means shipping the user's defaults, not their intent. |
-| "Spec exists from previous cycle, append to it" | New cycle = new spec file. The architect agent reads spec files per cycle; mixing scopes makes drift review unreadable. |
+| "Spec exists from previous cycle, append to it" | The previous cycle's spec was retired at its close (see `../docs/conventions.md` § Lifecycle) — there is nothing to append to. New cycle = new spec file; the architect reads one cycle's spec at a time, and mixing scopes makes drift review unreadable. |
 | "Approaches A, B, C are all bad — proceed with A" | This is exactly the moment to surface "the problem is mis-framed" rather than ratify a known-bad shape into the design ledger. Escalate to the user. |
 
 ## Red Flags — STOP

docs/conventions.md

@@ -27,14 +27,41 @@ These directories are fixed. A project that keeps specs and plans
 elsewhere is the rare exception and states the override in its
 `CLAUDE.md` project facts.
 
+## Lifecycle
+
+`docs/specs/` and `docs/plans/` hold **only the active cycle's
+artefacts** — they are working space, not an archive. A spec or plan is
+valid for the cycle that produces it; its code shapes drift the moment
+the code moves, so a stale one left lying around reads as a live API
+reference and misleads the next agent that opens it.
+
+The two directories stay **git-tracked** — never git-ignored. A
+spec/plan is committed while its cycle is live, and at **cycle close** —
+after `audit` is drift-clean — the orchestrator **retires** it: `git rm`
+the spec and plan in the cycle-close commit. The deletion rides in that
+commit, so at `HEAD` the directories hold only what is still in flight,
+while the full text stays recoverable from git history
+(`git show <rev>:<path>`).
+
+A spec/plan is therefore **transient in the repo**: present for its own
+cycle, gone from `HEAD` afterwards. The durable record of a past cycle
+is the design ledger (where the rationale is lifted during audit) + the
+git history of the spec, plan, and code — never a live file under
+`docs/specs` / `docs/plans`.
+
 ## Naming
 
 Counter-prefixed, per directory: `NNNN-slug.md`, 4-digit
 zero-padded. The counter is per directory, assigned in creation
 order, and stable for the life of the file. New files take the
-next-higher number; deleted files retire their number (numbers are
+next-higher number; `brainstorm` / `specify` / `planner` scan the
-not recycled). `brainstorm` / `specify` / `planner` scan the target
+target directory for the next free number before writing.
-directory for the next free number before writing.
+
+The number is a within-cycle handle, not a stable archival ID.
+Because the directories hold only active artefacts (see § Lifecycle),
+an emptied directory restarts at `0001` and a number freed by a
+retired file may be reused — that recycling is fine, since the durable
+record is git history, not the filename.
 
 The slug separator is `-`.
 

docs/design.md

@@ -87,6 +87,11 @@ standing reading (`CLAUDE.md` + `git log -10`), git discipline
 (only-orchestrator commits, main sacrosanct), Gitea + `closes #N`,
 and the whole pipeline graph (see `pipeline.md`).
 
+Specs and plans are ephemeral active-cycle artefacts — the two
+directories stay git-tracked and hold only what is in flight; at cycle
+close each is `git rm`'d from the repo, kept only in git history, never
+as a durable file (see `conventions.md` § Lifecycle).
+
 ## Project facts (project-specific)
 
 The handful of facts that genuinely vary per project live in the

docs/pipeline.md

@@ -123,8 +123,9 @@ Hard-gate before plan — the spec-production core and the carrier of the
 "no plan without an approved spec" invariant. Takes a settled design
 (directly from sources, or a ratified design handed over by
 `brainstorm`), applies the feature-acceptance criterion, writes the
-spec to `docs/specs`, runs the `grounding-check` gate, and takes user
+spec to `docs/specs` (an ephemeral active-cycle artefact, git-tracked
-sign-off — with review but no interview. Bounces to `brainstorm` the moment the sources do not
+and `git rm`'d at cycle close — see `conventions.md` § Lifecycle), runs
+the `grounding-check` gate, and takes user sign-off — with review but no interview. Bounces to `brainstorm` the moment the sources do not
 resolve a load-bearing design decision. A core node — the
 spec-production gate before `planner` on every design path.
 
@@ -148,7 +149,8 @@ juror can ratify the resolution instead of blocking for lack of one. See
 ### planner
 
 Hard-gate before implement. Produces a placeholder-free,
-bite-sized implementation plan in `docs/plans`
+bite-sized implementation plan in `docs/plans` (ephemeral, retired
+alongside the spec at cycle close — see `conventions.md` § Lifecycle)
 that the implement skill can execute task-by-task. Dispatches
 the plan-recon agent for read-only file-structure mapping.
 
@@ -188,7 +190,10 @@ review-and-commit discipline; the orchestrator inspects and commits.
 
 Runs at cycle close. Dispatches the architect agent (read-only
 drift review against the design ledger) and the bencher agent
-(regression diagnostics). Reports drift and regress.
+(regression diagnostics). Reports drift and regress. Once it is
+drift-clean, the orchestrator retires the cycle's spec and plan —
+`git rm`'ing them in the cycle-close commit (see `conventions.md`
+§ Lifecycle).
 
 ### debug
 

glossary/SKILL.md

@@ -104,7 +104,9 @@ If the mode is ambiguous, ask once; do not guess.
    project's CLAUDE.md.
 2. **Partition the prose surface into slices** — the readable prose of
    the project: `docs/`, `README.md`, the project's design ledger, if it
-   has one (its CLAUDE.md project facts), the spec directory `docs/specs`.
+   has one (its CLAUDE.md project facts). Exclude `docs/specs` and
+   `docs/plans` — those are ephemeral active-cycle artefacts, not durable
+   prose (see `../docs/conventions.md` § Lifecycle).
    One slice per coherent group, sized so a single agent can sweep it.
 3. **Fan out one `glossary-extractor` per slice.** Dispatch the read-only
    agent (`agents/glossary-extractor.md`) with the carrier: the slice and

issue/SKILL.md

@@ -76,8 +76,7 @@ These apply to every issue, on create and on edit.
    link them.
    - Avoid: "Fixes the regression from the ledger refactor; see the
      spec."
-   - Use: "Fixes the regression behind `#38`; spec at
+   - Use: "Fixes the regression behind `#38`, introduced in `a1b2c3d`."
-     `docs/specs/0004-escaping.md`."
 
 **Language:** title and body are English — an issue is a repo
 artefact mirrored to Gitea ("would it be committed → English", per

planner/SKILL.md

@@ -232,7 +232,10 @@ 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.
+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).
 
 ## Handoff Contract
 

specify/SKILL.md

@@ -362,7 +362,9 @@ 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 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).
 
 **In `/boss` (autonomous):** `specify` is dispatched autonomously —
 it is bounded (no interview). It runs the criterion, parse, and

templates/CLAUDE.md.fragment

@@ -59,6 +59,15 @@ Two rules govern who touches git history and how:
   wrong does land on main, the remedy is a forward-fix commit,
   never a rewind.
 
+## Spec/plan artefacts are ephemeral
+
+`docs/specs/` and `docs/plans/` hold only the active cycle's spec and
+plan, and they stay **git-tracked** — do not git-ignore them. Each is
+committed while its cycle is live and `git rm`'d at cycle close, so it
+is transient in the repo: present for its own cycle, then gone from
+`HEAD` while git history keeps the full text (see
+`~/dev/skills/docs/conventions.md` § Lifecycle).
+
 ## Design rationale ≠ implementation effort
 
 When picking between design options, the rationale must come