#+TITLE: Docs Lifecycle — Spec #+AUTHOR: Craig Jennings & Claude #+DATE: 2026-07-01 #+TODO: TODO | DONE #+TODO: DRAFT READY DOING | IMPLEMENTED SUPERSEDED CANCELLED * DRAFT Docs lifecycle :PROPERTIES: :ID: 80b0787b-4a60-4c82-8a16-b383d3e3c8f2 :END: - 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 | draft | |----------+------------------------------------------------------------------| | Owner | Craig Jennings | |----------+------------------------------------------------------------------| | Reviewer | Craig Jennings | |----------+------------------------------------------------------------------| | Date | 2026-07-01 | |----------+------------------------------------------------------------------| | Related | [[file:../design/2026-06-15-spec-storage-lifecycle-proposal.org][source proposal]]; todo.org "Spec storage location + | | | lifecycle-status convention" | |----------+------------------------------------------------------------------| * Summary Formal specs and working notes currently share one directory per project, and a spec's lifecycle state (drafted, in progress, shipped, dead) is invisible without opening the file. This spec adopts two coupled conventions — a location split (=docs/specs/= for formal specs, =docs/design/= for notes) and an authoritative in-file status carried by an org TODO keyword on a top-level status heading — plus =org-id= links for rename-safety, a general =docs-lifecycle= rule capturing the shape, and a one-time confirmed retrofit that sorts every project's existing pile. * Problem / Context .emacs.d triaged ~28 design docs and had to run a four-agent sweep reading every spec against the code to reconstruct which had shipped (6 implemented, 8 in progress, 12 not started, 1 superseded). Nothing in the filename, location, or file records the state, so the answer to "what's open?" degrades into "open every file and infer." rulesets has the same shape: 41 files in =docs/design/= of which only 3 carry a formal spec spine, plus two =-spec.org= files misfiled at the =docs/= root. The cost compounds with every doc added, and every project inherits the problem through the shared spec-create workflow. Two forces beyond triage cost: - *Links are load-bearing.* =todo.org= tasks, session archives, and sibling docs link specs by =file:= path. Any convention that renames or moves files on every status change (the filename-suffix approach) breaks those links repeatedly across a cross-linked, template-synced doc set. - *The convention is worthless if legacy docs stay misfiled* (Craig, 2026-06-28). Template sync distributes rules and workflows but cannot perform a one-time per-project migration, so the design must include a reach mechanism that gets each project's existing pile sorted once. * Goals and Non-Goals ** Goals - A directory listing answers "which docs are specs, and what state is each in" without opening files. - Status transitions cost one small in-file edit (keyword + history line + Metadata mirror) — no rename, no link surgery. - Cross-doc spec links survive moves and renames. - The shape is captured once as a general rule (=docs-lifecycle=) so future artifact collections (brainstorm piles, recording queues) can reuse it. - Every existing project's =docs/design/= pile gets sorted exactly once, with human confirmation on each classification. ** Non-Goals - No automation of status flips — the keyword is edited by whoever changes the state (spec-create, spec-review, spec-response, or a human), not by a watcher. - No retroactive rewriting of session archives or git history that reference old paths; only live inbound links (=todo.org=, =notes.org=, docs) are updated by the retrofit. - No new tracking database or index file — the files are the index. ** Scope tiers - v1: the location split, the status-heading convention, the org-id link standard, the =docs-lifecycle= rule, spec-create/spec-review/spec-response updates, the retrofit helper + startup nudge, and the rulesets pilot. - Out of scope: applying the lifecycle shape to non-doc collections (the rule documents the pattern; adopting it elsewhere is per-collection work). - vNext: an org-agenda custom view over =docs/specs/*.org= keyed on the status keywords (nice-to-have once the keywords exist; log to todo.org). * Design ** The location split - =docs/specs/= — formal specs only. A *spec* is a doc proposing a buildable change that carries a =Decisions= section and =Implementation phases= (the spec-create spine). Filenames keep the existing =YYYY-MM-DD--spec.org= shape — the =-spec.org= suffix stays because spec-review's Phase 0 precondition keys on it; only the *status* suffixes from the original proposal are dropped. - =docs/design/= — everything else: brainstorms, inventories, proposals, research notes, frozen source material. Review findings live inside the spec they review (current spec-review behavior), so standalone review files are legacy notes and stay in =docs/design/=. ** The status heading (the authoritative record) Each spec's first element after the file header is a single top-level *status heading* carrying the org TODO keyword: #+begin_example ,#+TODO: TODO | DONE ,#+TODO: DRAFT READY DOING | IMPLEMENTED SUPERSEDED CANCELLED ,* DOING :PROPERTIES: :ID: :END: - #+end_example - *The keyword is authoritative.* The Metadata table's =Status= field mirrors it in lowercase for readers already in the table, and a status transition updates keyword + history line + mirror in the same edit; on disagreement the heading wins. - *Two keyword sequences, no collisions.* The lifecycle sequence *joins* — never replaces — the =TODO | DONE= sequence that the =* Decisions= and =* Review findings= task machinery depends on. The two sequences share no keyword (the old header's =SUPERSEDED CANCELLED= done-states migrate to the lifecycle sequence; a legacy =CANCELLED= decision heading still parses as a done-state there, so =[/]= cookies stay mechanically correct). The retrofit rewrites each legacy header to carry both lines. - *Vocabulary:* =DRAFT= (being written) → =READY= (review passed, buildable) → =DOING= (implementation in progress) → =IMPLEMENTED= / =SUPERSEDED= / =CANCELLED= (terminal). - *Transition ownership — every flip has a named owner:* - =DRAFT= — spec-create stamps it at authoring time. - =DRAFT= → =READY= — spec-review, on a passing gate (keyword + history line + mirror in the review pass). - =READY= → =DOING= — spec-response, when it decomposes the phases into build tasks. - =DOING= → =IMPLEMENTED= — the session that completes the final implementation phase. To make that a tracked obligation rather than a memory, spec-response's phase-to-task breakdown *always emits a final task*: "flip the spec to IMPLEMENTED + history line." Safety net: task-audit's reconcile phase flags any =DOING= spec whose implementation tasks are all closed. This is the mechanism whose absence produced the .emacs.d six-shipped-specs-with-no-record failure; "a human remembers" is explicitly not the design. - =SUPERSEDED= / =CANCELLED= — whoever makes the call, with the reason in the history line. - *Glanceability without opening files:* one grep gives the full board — #+begin_src sh rg -H '^\* (DRAFT|READY|DOING|IMPLEMENTED|SUPERSEDED|CANCELLED) ' docs/specs/ #+end_src and because the keyword sits on a real org heading, an org-agenda view over =docs/specs/= works for free (the vNext item). - *The heading body is the dated status history* — one line per transition (=YYYY-MM-DD Day @ HH:MM:SS -ZZZZ — =), the record a filename could never carry. - Why a dedicated status heading rather than restructuring each spec under one top-level heading: demoting every section in every existing spec is a large, link-hostile rewrite; a prepended heading is additive, retrofittable by script, and leaves the familiar flat section layout untouched. ** Rename-safe links The status heading carries an =:ID:= UUID. Cross-doc references to a spec use =[[id:]]= rather than =file:= paths, so the one move the retrofit performs (and any future move) can't orphan them. =file:= links remain fine for intra-doc anchors and for notes that never move. The KB's existing id-resolution recipe applies: =rg ':ID:[[:space:]]+' docs/=. *Emacs resolution prerequisite (named, .emacs.d-side).* =org-id-locations= only indexes agenda files and files org has visited, so a fresh =:ID:= in =docs/specs/= won't resolve on click in a live Emacs until the id index learns about project docs — via =org-id-extra-files= covering the =docs/specs/= globs, or a periodic =org-id-update-id-locations= run. Without this, id links trade visibly-broken =file:= links for invisible-until-clicked broken ones. The Phase 4 note to .emacs.d carries this ask; until it lands, the =rg= recipe above is the manual fallback. ** The =docs-lifecycle= rule (the generalization) A new =claude-rules/docs-lifecycle.md= captures the reusable shape, with spec-create as the first instance: 1. Separate formal artifacts from working notes by location. 2. Lifecycle state lives *in* the artifact, on a scannable, greppable carrier (an org keyword heading), with a dated history. 3. Links use rename-safe identifiers. 4. A growing collection earns this treatment when "which of these are live?" starts requiring a file-by-file read. ** The retrofit (reach mechanism for existing piles) A synced helper, =.ai/scripts/spec-sort=, run once per project: 1. *Classify* each =docs/**/*.org= outside =docs/specs/= by one predicate: a doc carrying *both* a =Decisions= heading *and* an =Implementation phases= heading is a spec candidate; everything else is a note. (A =Metadata= table alone does not qualify — real counter-case: =docs/design/task-review.org= has a Metadata table and no spine, and is a note.) The heuristic *proposes*; a human confirms every move (classification is a judgment call — Craig, 2026-06-28). 2. *Move* confirmed specs to =docs/specs/=, *renaming to carry the =-spec.org= suffix* when the file lacks it (spec-review's Phase 0 precondition requires it — a retrofitted spec must be reviewable in its new home). Prepend the status heading (keyword proposed from the doc's current Status field or review history; confirmed by the human), assign an =:ID:=, and rewrite the keyword header to the two-sequence form above. 3. *Relink* under an explicit contract: - *Rewritten roots (project-owned):* =todo.org=, =.ai/notes.org=, =docs/**=, =.ai/project-workflows/=, =.ai/project-scripts/=. The rewrite recomputes each link's relative path from the linking file's directory to the new location; links whose target is a spec are additionally offered as =[[id:...]]= conversion. - *Reported, never rewritten:* =.ai/sessions/= archives (frozen history), git history, and synced template paths (=.ai/workflows/=, =.ai/scripts/=, =.ai/protocols.org=) — a downstream edit there is reverted by the next template sync, so the report names the canonical rulesets file that needs the edit instead. - *Supported link shapes:* org =[[file:...]]= links, relative or project-root-anchored, with or without a description. Bare-path mentions in prose or scripts are *reported for manual handling*, never rewritten. - *Safety:* dry-run report is the default; =--apply= writes. After apply, a residue grep for each old path across the rewritten roots must return zero or =spec-sort= exits non-zero naming the residue. Ambiguous cases (two candidates sharing a basename, an unparseable link) are listed and left untouched, and the run exits non-zero until each is resolved or explicitly waived. 4. *Stamp* =:LAST_SPEC_SORT: YYYY-MM-DD= in =.ai/notes.org='s =* Workflow State= section — the same surface as =:LAST_AUDIT:= and =:LAST_INBOX_PROCESS:=, created idempotently (append the section if the file lacks it) exactly as task-audit already does. *The startup nudge — concrete contract.* Phase A's parallel batch gains one read-only probe: #+begin_src bash [ -d docs/design ] && ! grep -qs ':LAST_SPEC_SORT:' .ai/notes.org \ && echo "spec-sort: docs/design present, never sorted" #+end_src Phase C surfaces one line when the probe printed ("this project's docs pile has never been spec-sorted — say 'run spec-sort' to sort it") and stays silent otherwise. Projects without a =docs/design/= never see it; a stamped marker permanently clears it. * Alternatives Considered ** Filename status suffix (=-spec-doing.org=, =-spec-implemented.org=) - Good, because the state is visible in a bare =ls= with no tooling. - Bad, because every transition renames a file in a cross-linked, template-synced doc set — each rename is link surgery or a broken link, and the churn lands in git history and inbound =todo.org= links. - Neutral, because the ls-visibility it buys is matched by the one-line =rg= over status headings. - Rejected 2026-06-28 (Craig chose org-keyword over his earlier filename-suffix lean). ** Status field in the Metadata table only (no keyword) - Good, because the field already exists and needs no new structure. - Bad, because a table cell is neither org-agenda-scannable nor reliably greppable across format drift, and it carries no dated history. - Neutral, because the field stays anyway — as the in-table mirror. ** Relink-helper instead of org-id (keep =file:= links, fix them on every move) - Good, because readers see plain paths. - Bad, because it makes every future move a tooling event, and one missed run silently breaks links — the failure mode is invisible until someone clicks. - Neutral, because the retrofit needs relink logic once regardless; org-id just makes it a one-time need. * Decisions [5/5] All five were settled with Craig on 2026-06-28 (recorded in todo.org; migrated here per that note). ** DONE Location split — adopt - Context: specs and notes share one directory; telling them apart requires opening files. - Decision: =docs/specs/= for formal specs (Decisions + phases spine); =docs/design/= for notes. Documented in spec-create and the docs-lifecycle rule. - Consequences: easier — a listing answers "what's formal"; harder — one-time migration and link updates (the retrofit). ** DONE Status mechanism — org keyword authoritative, no filename suffix - Context: filename suffix vs org keyword; suffix wins =ls= visibility, keyword wins link stability and zero-rename transitions. - Decision: the org TODO keyword on the spec's top status heading is authoritative, mirrored by the Metadata =Status= field. No status suffixes in filenames. - Consequences: easier — a transition is one keyword edit and links never break; harder — glanceability needs the one-line =rg= (or the vNext agenda view) instead of bare =ls=. ** DONE Link safety — org-id for cross-doc spec links - Context: both the migration move and any future rename break =file:= links. - Decision: specs carry =:ID:= UUIDs on the status heading; cross-doc references use =[[id:...]]=. - Consequences: easier — moves are free; harder — following a link outside org needs the =rg ':ID:'= lookup. ** DONE Generalize as a =docs-lifecycle= rule - Context: the shape (in-artifact lifecycle state, formal-vs-notes split, rename-safe links) recurs for any processed-document collection. - Decision: capture it in =claude-rules/docs-lifecycle.md= with spec-create as the first instance. - Consequences: easier — the next collection reuses a decided pattern; harder — the rule must stay honest as the spec instance evolves. ** DONE Retrofit existing files across ALL projects - Context: template sync distributes conventions but cannot perform a per-project one-time migration; legacy piles would stay misfiled forever. - Decision: ship a confirmed classify-move-relink helper (=spec-sort=) plus a startup nudge gated on =:LAST_SPEC_SORT:=; the helper proposes, a human confirms. Pilot on rulesets first. - Consequences: easier — every project converges without manual archaeology; harder — the helper needs real relink logic and tests, and classification stays a judgment call. * Review findings [9/9] Two independent reviews (Codex, 2026-07-01 22:22; a fresh-context Claude agent, 2026-07-01 22:25) converged on =Not ready= with the same worst finding. All nine findings were dispositioned accept and fixed in the responder pass below; each carries its response. ** DONE Org TODO vocabulary drops decision and finding task states :blocking: (Codex; the Claude reviewer found the same, adding that keywords must be unique across sequences so a naive two-line fix collides on =SUPERSEDED=/=CANCELLED=.) The spec's example header replaced the file-level keyword vocabulary, so =TODO=/=DONE= stopped being task states and the =[/]= cookies that gate readiness went vacuous — this file itself was the first casualty. Response: the scheme is now two collision-free sequences — =TODO | DONE= for decisions/findings, =DRAFT READY DOING | IMPLEMENTED SUPERSEDED CANCELLED= for lifecycle (the old header's =SUPERSEDED CANCELLED= done-states migrate to the lifecycle sequence, and a legacy =CANCELLED= decision still parses as a done-state, so cookies stay correct). This file's own header now carries both lines; the Design section documents the two-sequence rule and the retrofit rewrites legacy headers to it. New acceptance criterion: cookies must compute by org, not hand counting. ** DONE Relink behavior is too vague for a safe migration :blocking: (Codex; the Claude reviewer independently flagged the synced-.ai/ slice — a downstream rewrite there is reverted by the next template sync, e.g. =startup.org:154='s reference to a spec candidate.) The retrofit named no scan scope, link-shape list, rewrite rule, residue policy, or dry-run format — the implementer would have had to invent the migration's data-safety contract. Response: the retrofit section now carries the explicit contract: rewritten roots (=todo.org=, =.ai/notes.org=, =docs/**=, project-owned =.ai/= dirs), reported-never-rewritten surfaces (=.ai/sessions/=, git history, synced template paths — with the canonical rulesets file named in the report), supported link shapes (org =file:= links; bare paths report-only), relative-path recomputation, dry-run default with =--apply=, post-apply residue grep gating exit status, and refuse-loudly on ambiguity. ** DONE Sort marker and startup nudge do not name the actual state surface :blocking: (Codex; the Claude reviewer rated the same gap minor — Codex's version was sharper: startup reads =.ai/notes.org=, not a root =notes.org=, and Workflow State may not exist.) Response: the marker is pinned to =.ai/notes.org='s =* Workflow State= (the =:LAST_AUDIT:= / =:LAST_INBOX_PROCESS:= surface), created idempotently as task-audit already does; the Design section now spells the Phase A probe command, its exact fire condition, and the Phase C one-liner. ** DONE Phase order can strand legacy specs behind the new review precondition :blocking: (Codex; the Claude reviewer found the same at medium severity.) Hardening spec-review's path precondition in Phase 1 while piles stay unsorted until Phases 3-4 would make every legacy spec unreviewable in the gap. Response: Phase 1 now carries the compatibility rule — legacy =-spec.org= locations stay reviewable (with a "run spec-sort" nudge) until the project stamps =:LAST_SPEC_SORT:=; the precondition hardens only after. Acceptance criterion 5 updated to match. ** DONE No owner for the DOING → IMPLEMENTED flip :blocking: (Claude reviewer.) spec-create owns =DRAFT= and spec-review owns =DRAFT= → =READY=, but implementation finishes outside the spec trio, and "a human edits it" is the exact mechanism whose failure produced this spec (.emacs.d's six shipped-but-unmarked specs). Response: the Design section now has a transition-ownership table naming an owner for every flip. =READY= → =DOING= belongs to spec-response; =DOING= → =IMPLEMENTED= is a tracked obligation — spec-response's phase-to-task breakdown always emits a final "flip the spec" task — with task-audit's reconcile pass as the safety net (flag any =DOING= spec whose implementation tasks are all closed). Phase 1 includes both workflow edits. ** DONE Classification heuristic is precedence-ambiguous (Claude reviewer.) "Decisions plus phases or Metadata table" reads two ways, and =docs/design/task-review.org= (Metadata table, no spine) classifies differently under each. Response: one predicate now — spec candidate iff the doc carries *both* a =Decisions= heading *and* an =Implementation phases= heading; a Metadata table alone does not qualify. The task-review.org counter-case is cited in the retrofit step. ** DONE spec-sort never renames moved files to the -spec.org suffix (Claude reviewer.) spec-review's Phase 0 hard-requires the suffix, so a retrofitted legacy spec without it would be unreviewable in its new home. Response: retrofit step 2 now renames moved files to carry =-spec.org= when they lack it; the relink pass covers the rename like any move. Acceptance criterion 3 checks the suffix on the re-homed root specs. ** DONE Clicked id: links won't resolve in Craig's Emacs (Claude reviewer.) =org-id-locations= indexes only agenda and visited files, so fresh =:ID:=s in =docs/specs/= are invisible-until-clicked broken — the convention would trade visible link breakage for invisible breakage. Response: named as an explicit .emacs.d-side prerequisite in the Rename-safe-links section (=org-id-extra-files= over =docs/specs/= globs, or periodic =org-id-update-id-locations=), carried in the Phase 4 note to .emacs.d, with the =rg= recipe as the interim fallback. ** DONE Acceptance criterion 2 contradicts the Metadata Status mirror (Claude reviewer.) "Exactly one keyword edit" was irreconcilable with the mandated mirror update. Response: a transition is now defined everywhere as three lines in one file — keyword, history line, mirror — still no rename and no link edits. Goals, Design, and criterion 2 all say the same thing. * Implementation phases ** Phase 1 — Rule + template updates Write =claude-rules/docs-lifecycle.md=. Update spec-create (emit into =docs/specs/=, the two-sequence keyword header, status heading with =:ID:= in the template, transition mechanics), spec-review (path expectation with the compatibility rule below; flipping =DRAFT= → =READY= on a passing review updates keyword + history + mirror), spec-response (owns =READY= → =DOING=, and its phase-to-task breakdown always emits the final "flip to IMPLEMENTED" task), and task-audit (one reconcile bullet: flag a =DOING= spec whose implementation tasks are all closed). *Compatibility rule:* spec-review keeps accepting legacy =-spec.org= locations (=docs/= root, =docs/design/=) until the project's =:LAST_SPEC_SORT:= is stamped, nudging "run spec-sort" when it meets one; only after the stamp does the =docs/specs/= precondition harden. No legacy spec is ever unreviewable during the transition. Tree stays working: new specs land in the new shape; old specs remain reviewable until their project sorts. ** Phase 2 — The =spec-sort= helper Build =.ai/scripts/spec-sort= (classify → confirm → move + prepend status heading + assign =:ID:= → relink inbound references → stamp =:LAST_SPEC_SORT:=), with bats coverage for classification, moving, relinking, idempotence, and the confirm gate. Tree stays working: the script is callable but nothing invokes it yet. ** Phase 3 — Pilot on rulesets Run =spec-sort= against rulesets' own =docs/= (41 design files, 3 spec-spine candidates, 2 stray root specs). Fix what the pilot surfaces before any other project runs it. Tree stays working: moves are confirmed one by one, links updated in the same pass. ** Phase 4 — Startup nudge + broadcast Add the Phase A probe + Phase C nudge line (the concrete contract in the Design retrofit section). Send .emacs.d a note that the convention is live, its ~28-doc pile is ready to sort, and the org-id resolution prerequisite needs a home (=org-id-extra-files= over project =docs/specs/= globs, or a periodic =org-id-update-id-locations=). Tree stays working: the nudge is one read-only line per session until acted on. * Acceptance criteria - [ ] =rg '^\* (DRAFT|READY|DOING|IMPLEMENTED|SUPERSEDED|CANCELLED) ' docs/specs/= lists every rulesets spec with its state, and the answer matches reality. - [ ] A status transition on a spec changes exactly three lines in one file — the keyword, a history line, and the Metadata mirror — with no rename and no link edits. - [ ] Every doc remaining in rulesets =docs/design/= is a note (lacks the Decisions + Implementation-phases spine); both stray =docs/= root specs are re-homed and carry the =-spec.org= suffix. - [ ] All inbound links in the rewritten roots resolve after the pilot, and the post-apply residue grep returns zero. - [ ] The spec's own decision/finding =[/]= cookies compute correctly under the two-sequence keyword header (org, not hand counting). - [ ] spec-create emits new specs into =docs/specs/= in the new shape; spec-review accepts legacy locations until =:LAST_SPEC_SORT:= is stamped and refuses them after. - [ ] A project with an unsorted =docs/design/= gets the startup nudge; one confirmed =spec-sort= run clears it via =:LAST_SPEC_SORT:=. * Readiness dimensions - Data model & ownership: the spec file owns its state; the Metadata mirror is display-only. No external index to drift. - Errors, empty states & failure: =spec-sort= on a project with no =docs/= is a silent no-op; an ambiguous classification is surfaced, never auto-moved; a relink pass that finds zero inbound links is normal. - Security & privacy: N/A because the docs are already in-repo; no new exposure surface. - Observability: the status grep is the dashboard; =spec-sort= prints every proposed move and every rewritten link. - Performance & scale: N/A because collections are tens of files; everything is one-shot or grep-speed. - Reuse & lost opportunities: reuses org TODO keywords, org-id, the existing scheme-header pattern of declared vocabularies, and spec-review's in-file findings convention. - Architecture fit & weak points: weak point is the classification heuristic — mitigated by the confirm gate. The status heading is additive, so old readers of spec files see one extra heading and nothing breaks. - Config surface: none new — one marker line (=:LAST_SPEC_SORT:=) in the existing Workflow State section. - Documentation plan: the docs-lifecycle rule is the documentation; spec-create's template is the worked example. - Dev tooling: =spec-sort= ships with bats tests under the existing glob-discovered suite. - Rollout, compatibility & rollback: additive per project, one project at a time, rulesets first. Rollback of a sort is =git revert= of the pilot commit (moves + relinks are one commit). - External APIs & deps: N/A — plain files, =rg=, =uuidgen=. * Risks, Rabbit Holes, and Drawbacks - *Relink misses an inbound link shape* (org radio links, bare paths in scripts). Dodge: the pilot greps for the old path after moving and fails loudly on any residue. - *Heuristic over-classifies notes as specs.* Dodge: the confirm gate is mandatory; the helper never moves unconfirmed. - *Keyword vocabulary drift* between this spec, the rule, and spec-create's template. Dodge: the rule names the vocabulary once and the others link it. * Testing / Verification / Rollout bats for =spec-sort= (classification, move, relink, idempotence, confirm gate, marker stamp). The pilot run on rulesets is the live verification; the post-move residue grep is the acceptance check. Rollout is per-project via the startup nudge, each run human-confirmed. * References / Appendix - Source proposal: [[file:../design/2026-06-15-spec-storage-lifecycle-proposal.org]] (.emacs.d handoff, 2026-06-15). - Decisions record: todo.org "Spec storage location + lifecycle-status convention" (settled 2026-06-28). - This file is the convention's first resident: it lives in =docs/specs/=, carries the status heading + =:ID:=, and drops the status filename suffix. * Review and iteration history ** 2026-07-01 Wed @ 22:13:00 -0400 — Claude — author - What: initial draft, written from the five pre-ratified decisions. - Why: the queued-specs half of the 2026-06-30 session goal; decisions were settled 2026-06-28 and needed migration into a buildable spec. - Artifacts: todo.org task "Spec storage location + lifecycle-status convention"; source proposal above. ** 2026-07-01 Wed @ 22:22:34 -0400 — Codex — reviewer - What changed or was recommended: rubric =Not ready=. Four blocking findings were added: preserve Org task keywords while adding lifecycle status, make =spec-sort= relinking executable and failure-safe, define the actual =.ai/notes.org= marker/startup-nudge contract, and avoid stranding legacy specs behind a stricter path precondition before retrofit. - Why: current rulesets workflows still depend on =TODO= / =DONE= decision and finding tasks, startup state lives in =.ai/notes.org=, and the repo still contains formal specs outside =docs/specs/= until the migration runs. - Artifacts: Review findings section; current-state checks against =.ai/workflows/spec-create.org=, =.ai/workflows/spec-review.org=, =.ai/workflows/startup.org=, =scripts/sync-check.sh=, and =todo.org=. ** 2026-07-01 Wed @ 22:25:00 -0400 — Claude (fresh-context agent) — reviewer - What: rubric =Not ready=. Independently found Codex's keyword-vocabulary blocker (adding the cross-sequence uniqueness wrinkle) and the stranded-legacy-specs and marker-surface gaps, plus five findings of its own: no owner for the =DOING= → =IMPLEMENTED= flip (blocking), the precedence-ambiguous classification heuristic, the missing =-spec.org= rename in spec-sort, org-id click-resolution in a live Emacs, and the criterion-2/mirror contradiction. - Why: fresh-eyes adversarial pass requested by Craig after his own read found nothing; the two reviews converging on the same worst bug from independent context is the confidence signal. - Artifacts: Review findings section (findings 5-9); spot-checks against real repo files (=docs/design/task-review.org=, the two stray root specs, =startup.org:154=). ** 2026-07-01 Wed @ 22:30:06 -0400 — Claude — responder - What: merged both reviews into one findings ledger (nine findings, all dispositioned accept) and fixed all nine in place: two-sequence keyword header (applied to this file itself), transition-ownership table with the tracked flip-to-IMPLEMENTED task, single classification predicate, the -spec.org rename step, the full relink data-safety contract, the =.ai/notes.org= marker + Phase A/C startup contract, the legacy-location compatibility rule, the org-id Emacs prerequisite, and the three-line transition definition. Acceptance criteria updated to match. - Why: Craig approved fixing all nine ("1", 2026-07-01); none touched the five ratified decisions. - Artifacts: Review findings section (responses inline per finding); the fixed sections themselves.