From 09b880e1058549b0aa9751b81129d87b25372cee Mon Sep 17 00:00:00 2001 From: Craig Jennings Date: Wed, 1 Jul 2026 22:35:00 -0400 Subject: docs(spec): fix all nine dual-review findings in the docs-lifecycle spec MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two independent reviews converged on the same blocker: the lifecycle keyword line replaced TODO/DONE, silently breaking the decision-task cookies — the spec's own [5/5] was hand-faked. The header is now two collision-free sequences and org computes the cookies. Also fixed: every status flip has a named owner (spec-response emits a tracked flip-to-IMPLEMENTED task, task-audit reconciles as the safety net), one classification predicate, spec-sort renames to -spec.org, an explicit relink data-safety contract, the .ai/notes.org marker + startup probe contract, a legacy-location grace rule so no spec is unreviewable mid-transition, the org-id resolution prerequisite, and the three-line transition definition. --- todo.org | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'todo.org') diff --git a/todo.org b/todo.org index cfb5e5e..2e7f66b 100644 --- a/todo.org +++ b/todo.org @@ -383,6 +383,15 @@ Follow-up once built: update spec-create to emit into =docs/specs/= with the org *** 2026-07-01 Wed @ 22:13:00 -0400 Spec drafted — first resident of docs/specs/, awaiting review Wrote [[file:docs/specs/2026-07-01-docs-lifecycle-spec.org][the spec]] from the five settled decisions, dogfooding its own conventions: it lives in the new =docs/specs/=, opens with the =* DRAFT Docs lifecycle= status heading (org keyword authoritative, =:ID:= for id-links, dated history in the body), and drops the status filename suffix. It pins the one mechanism the decisions left open — where the keyword lives: a prepended top-level status heading with vocabulary =DRAFT READY DOING | IMPLEMENTED SUPERSEDED CANCELLED=, additive and retrofittable, giving both the one-line =rg= board and free org-agenda scanning. Four build phases: rule + template updates → =spec-sort= helper (classify/confirm/move/relink, bats) → rulesets pilot (41 design files, 3 spec-spine candidates, 2 stray root specs) → startup nudge gated on =:LAST_SPEC_SORT:= + .emacs.d note. Status DRAFT until Craig's review flips it READY. +*** 2026-07-01 Wed @ 22:22:34 -0400 Codex spec-review complete — Not ready +Review findings live in [[file:docs/specs/2026-07-01-docs-lifecycle-spec.org::*Review findings][the spec]]. Four blockers before implementation: the proposed lifecycle =#+TODO:= line drops the =TODO=/=DONE= states needed by Decisions and Review findings cookies; =spec-sort= needs an exact relink/unsupported-residue contract; the sort marker/startup nudge must name the actual =.ai/notes.org= state surface and detection flow; and the stricter =docs/specs/= review precondition must not strand legacy specs before retrofit. + +*** 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. + +*** 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. + ** DOING [#C] No-approvals speedrun — cross-project autonomous-batch mode :feature:spec: :PROPERTIES: :CREATED: [2026-06-15 Mon] -- cgit v1.2.3