docs(spec): decompose docs-lifecycle build into phase tasks; flip to DOING

The build parent carries the :SPEC_ID: binding, one task per phase plus the id-conversion follow-up, the tracked flip-to-IMPLEMENTED task, and a manual-testing child — the first live exercise of the spec's own transition-ownership table.

1 files changed, 35 insertions, 0 deletions

diff --git a/todo.org b/todo.org
index 9b78482..01d00c9 100644
--- a/todo.org
+++ b/todo.org
@@ -362,6 +362,7 @@ Codex re-ran spec-review after the dispositions were folded in. Outcome by arc:
 :PROPERTIES:
 :CREATED: [2026-06-15 Mon]
 :LAST_REVIEWED: 2026-06-24
+:SPEC_ID: 80b0787b-4a60-4c82-8a16-b383d3e3c8f2
 :END:
 Two coupled documentation conventions for rulesets to adopt, surfaced by .emacs.d while triaging ~28 design docs. Both land in =spec-create= ([[file:.ai/workflows/spec-create.org]]) and likely a new =docs-lifecycle= rule under =claude-rules/=. Source proposal: [[file:docs/design/2026-06-15-spec-storage-lifecycle-proposal.org]] (.emacs.d handoff 2026-06-15).
 
@@ -398,6 +399,40 @@ Fixed Codex's five re-review findings: the canonical-placement contract now open
 *** 2026-07-01 Wed @ 23:22:50 -0400 Codex spec-review rerun — Ready
 Codex re-read the revised [[file:docs/specs/2026-07-01-docs-lifecycle-spec.org][docs lifecycle spec]] after the second responder pass. All fourteen findings are closed, decisions remain [5/5], and the remaining implementation contracts are concrete enough to build and test. Status flipped to READY in the spec; implementation can proceed.
 
+*** 2026-07-01 Wed @ 23:34:15 -0400 Decomposed into build tasks; spec flipped READY → DOING
+spec-response Phase 6 run: this parent now carries the =:SPEC_ID:= binding (the spec's status-heading UUID), the phase tasks below track the build, and the spec's status heading is DOING. Completeness pass done: all ten acceptance criteria have homes across the phase tasks; vNext (org-agenda view) was already filed as the [#D] task below.
+
+*** TODO Phase 1 — docs-lifecycle rule + spec-workflow updates :solo:
+Write claude-rules/docs-lifecycle.md (the generalized shape). Update, canonical-side: spec-create (emit into docs/specs/, two-sequence keyword header + status heading + :ID: in the template, DRAFT stamped at authoring), spec-review (compatibility rule — legacy locations accepted until :LAST_SPEC_SORT: stamped, then docs/specs/ hardens; DRAFT→READY flip = keyword + history + mirror), spec-response (owns READY→DOING at Phase 6; stamps :SPEC_ID: on the build parent; always emits the final flip-to-IMPLEMENTED task), task-audit (reconcile bullet: :SPEC_ID: query flags a DOING spec whose bound parent is closed/archived/missing). Verify: workflow-integrity bats + sync-check clean + make test.
+
+*** TODO Phase 2 — spec-sort helper + bats suite :solo:
+Build claude-templates/.ai/scripts/spec-sort per the spec's retrofit contract: classify (Decisions AND Implementation phases), evidence-based confirm gate, plan + validate before first write, move + rename to -spec.org + status heading + :ID:, relink file: links per the rewritten-roots/report-only contract, clean-worktree preflight (--allow-dirty override), named recovery on mid-apply failure (incl. deleting created untracked copies), residue-grep exit gate, :LAST_SPEC_SORT: stamp. Bats in claude-templates/.ai/scripts/tests/ covering classification, confirm gate, plan validation, move+rename, relink, preflight, forced-failure recovery output, idempotence, marker stamp. Verify: make test green, sync-check clean.
+
+*** TODO Phase 3 — rulesets pilot (interactive)
+Run spec-sort against rulesets' own docs/ with Craig confirming each candidate (~5 spec candidates among 41 design files + 2 stray root specs). Fix what the pilot surfaces. Verify: acceptance criteria 1-6 and 10 — status board matches reality, every remaining docs/design file is a note, re-homed specs carry -spec.org, links resolve, residue grep zero, no id: links in rewritten output.
+
+*** TODO Phase 4 — startup nudge + .emacs.d broadcast :solo:
+Add the Phase A probe + Phase C nudge line to startup.org (canonical). Send .emacs.d the note: convention live, ~28-doc pile ready to sort, and the id-index ask (enumerate docs/specs/*.org into org-id-extra-files under org-id-track-globally, or feed org-id-update-id-locations; verify by clicking a known id link). Verify: probe fires in a fixture project without the marker, silent with it.
+
+*** TODO id-link conversion pass — gated on .emacs.d id-index
+After .emacs.d lands the id-index mechanism (Phase 4's ask) and a clicked id link verifiably resolves, run the conversion pass: rewrite spec-target file: links in the rewritten roots to id: form, per project. Not part of any sort run. Becomes :blocked: with the reciprocal handoff if picked up before .emacs.d delivers.
+
+*** TODO Flip the spec to IMPLEMENTED
+When the final implementation phase completes: flip the spec's status heading DOING → IMPLEMENTED with a dated history line and the Metadata mirror, per the transition-ownership table. This task is the tracked obligation that closes the loop; the parent stays open until it runs.
+
+*** TODO Manual testing and validation :test:
+What we're verifying: the human-eyes half of the acceptance surface.
+
+**** Startup nudge appears and clears
+What we're verifying: the Phase A probe + Phase C nudge fire exactly once per project.
+- Open a session in a project with an unsorted docs/design (before its sort) and read the startup output.
+Expected: one line offering "run spec-sort"; after the pilot stamps :LAST_SPEC_SORT:, the next session shows nothing.
+
+**** Moved-spec links click through in Emacs
+What we're verifying: the pilot's relink pass left todo.org and docs links working for the human reader, not just the residue grep.
+- After the Phase 3 pilot, open todo.org in Emacs and click three links that point at moved specs (including one from a dated log entry).
+Expected: each opens the spec at its new docs/specs/ path.
+
 *** TODO [#D] Docs lifecycle vNext — org-agenda spec-status view :feature:
 Once specs carry lifecycle TODO keywords under =docs/specs/=, add a custom org-agenda view that lists =DRAFT= / =READY= / =DOING= / terminal specs by status. Deferred from [[file:docs/specs/2026-07-01-docs-lifecycle-spec.org][the docs-lifecycle spec]]; not part of v1 because the grep board is sufficient until the status headings exist.