From b163637008996031f5a16d4703d384209c4ace76 Mon Sep 17 00:00:00 2001 From: Craig Jennings Date: Wed, 1 Jul 2026 22:52:25 -0400 Subject: docs(spec): fix the five re-review findings in the docs-lifecycle spec Canonical placement contract for every synced artifact of the feature; a :SPEC_ID: property binds a spec to its build parent so task-audit can police DOING specs by the parent's keyword; spec-sort --apply gains a fail-safe contract (clean-tree preflight, validate-then-write from a recorded plan, named recovery); id-link conversion is staged behind the executable .emacs.d id-index mechanism so no unclickable-link window exists; status confirmation is evidence-based with terminal states requiring a stated reason. Status stays DRAFT pending reviewer sign-off. --- todo.org | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'todo.org') diff --git a/todo.org b/todo.org index 2e7f66b..4449470 100644 --- a/todo.org +++ b/todo.org @@ -389,6 +389,12 @@ Review findings live in [[file:docs/specs/2026-07-01-docs-lifecycle-spec.org::*R *** 2026-07-01 Wed @ 22:30:06 -0400 Second review merged + responder pass — all nine findings fixed A fresh-context Claude reviewer independently rated the draft Not ready, converging on Codex's keyword-vocabulary blocker (adding the cross-sequence uniqueness wrinkle) and contributing five unique findings — the biggest: nobody owned the DOING→IMPLEMENTED flip, the exact mechanism whose failure produced this spec. Craig approved fixing all nine. Fixed in place: two-sequence collision-free keyword header (dogfooded in the spec's own header; org now computes the [5/5] and [9/9] cookies — verified in batch), transition-ownership table incl. spec-response's mandatory flip-to-IMPLEMENTED task + task-audit safety net, single classification predicate (Decisions AND Implementation phases), the -spec.org rename step, the full relink data-safety contract (rewritten roots / report-only surfaces / dry-run default / residue-grep gate), the =.ai/notes.org= marker + Phase A probe + Phase C nudge contract, the legacy-location compatibility rule, the org-id Emacs-resolution prerequisite for .emacs.d, and the three-line transition definition. Ledger + per-finding responses in the spec's Review findings section. Status stays DRAFT pending Craig's READY flip. +*** 2026-07-01 Wed @ 22:41:33 -0400 Codex spec-review rerun — Not ready +Fresh review after the response/READY flip added five new blocking findings in [[file:docs/specs/2026-07-01-docs-lifecycle-spec.org::*Review findings][the spec]] and demoted the spec back to DRAFT. Remaining blockers: shared helper/workflow edits must name the canonical =claude-templates/.ai/= + mirror sync contract; task-audit needs an explicit spec-to-task binding before it can police =DOING= specs; =spec-sort --apply= needs a failure-safe/rollback contract; the org-id Emacs prerequisite must be executable before link conversion; and lifecycle status confirmation must be evidence-based so the retrofit does not encode stale reality. + +*** 2026-07-01 Wed @ 22:46:52 -0400 Second responder pass — all fourteen findings closed +Fixed Codex's five re-review findings: the canonical-placement contract now opens the retrofit section (helper + tests + workflow edits land in claude-templates first, sync-check --fix propagates, sync-check-clean is an acceptance criterion); spec-response stamps a =:SPEC_ID:= property on the build parent, and task-audit's query checks that parent's keyword — which dissolves the flip-task chicken-and-egg; =--apply= got the fail-safe contract (clean-tree preflight, validate-then-write from a recorded plan, named recovery recipe); id-link conversion is staged (pilot rewrites =file:= links only; =id:= conversion is a follow-up gated on the concrete .emacs.d id-index mechanism — Craig picked this fork); and status confirmation is evidence-based (evidence panel, conservative non-terminal default, terminal states need a stated reason). Also de-cookified bracket tokens in prose that org's cookie updater would mangle. Status stays DRAFT; the READY flip belongs to the reviewers this round — verify pass dispatched. + *** 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