From 328ca18a15c4dd14cc4898b483cc6b2681dbf7eb Mon Sep 17 00:00:00 2001 From: Craig Jennings Date: Wed, 1 Jul 2026 23:35:29 -0400 Subject: docs(spec): decompose docs-lifecycle build into phase tasks; flip to DOING MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- docs/specs/2026-07-01-docs-lifecycle-spec.org | 5 ++-- todo.org | 35 +++++++++++++++++++++++++++ 2 files changed, 38 insertions(+), 2 deletions(-) diff --git a/docs/specs/2026-07-01-docs-lifecycle-spec.org b/docs/specs/2026-07-01-docs-lifecycle-spec.org index 148e084..656df7f 100644 --- a/docs/specs/2026-07-01-docs-lifecycle-spec.org +++ b/docs/specs/2026-07-01-docs-lifecycle-spec.org @@ -4,10 +4,11 @@ #+TODO: TODO | DONE #+TODO: DRAFT READY DOING | IMPLEMENTED SUPERSEDED CANCELLED -* READY Docs lifecycle +* DOING Docs lifecycle :PROPERTIES: :ID: 80b0787b-4a60-4c82-8a16-b383d3e3c8f2 :END: +- 2026-07-01 Wed @ 23:34:15 -0400 — READY → DOING: spec-response decomposition ran — build parent in todo.org carries the :SPEC_ID: binding, one task per phase plus the flip-to-IMPLEMENTED task and the manual-testing child. First live exercise of the transition-ownership table. - 2026-07-01 Wed @ 23:22:50 -0400 — DRAFT → READY: Codex re-review found all fourteen review findings closed and no remaining blocking implementation-readiness gaps. - 2026-07-01 Wed @ 22:54:41 -0400 — verify pass on the second responder round: all five fixes held, findings 1-9 unregressed, verdict ready; three minor nits folded in (scoped id-link criterion, untracked-copy cleanup in the recovery recipe, two stale prose spots). Stays DRAFT pending the reviewers' flip. - 2026-07-01 Wed @ 22:46:52 -0400 — second responder pass: all five re-review findings fixed (fourteen of fourteen closed); stays DRAFT — the READY flip belongs to the reviewers this round. @@ -16,7 +17,7 @@ - 2026-07-01 Wed @ 22:13:00 -0400 — drafted from the five decisions settled 2026-06-28 (todo.org "Spec storage location + lifecycle-status convention"). * Metadata -| Status | ready | +| Status | doing | |----------+------------------------------------------------------------------| | Owner | Craig Jennings | |----------+------------------------------------------------------------------| 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. -- cgit v1.2.3