chore(todo): file spec storage + lifecycle-status proposal as a task

File the .emacs.d spec-storage/lifecycle proposal as a [#C] :spec: task with the recommendation captured in the body, so the design thinking survives until the task is worked in priority order. Move the proposal out of the inbox into docs/design/ as the linked source.

The recommendation leans org-TODO keyword + Status field over a filename suffix for lifecycle status (renames break cross-doc links across a synced doc set), and org-id links either way. Flagged that the keyword lean diverges from the filename-suffix idea, so the mechanism stays an open decision.

2 files changed, 64 insertions, 0 deletions

diff --git a/docs/design/2026-06-15-spec-storage-lifecycle-proposal.org b/docs/design/2026-06-15-spec-storage-lifecycle-proposal.org
new file mode 100644
index 0000000..7dbba72
--- /dev/null
+++ b/docs/design/2026-06-15-spec-storage-lifecycle-proposal.org
@@ -0,0 +1,44 @@
+#+TITLE: Proposal — spec storage location + lifecycle-status convention
+
+* What I'm proposing
+
+Two coupled documentation conventions, surfaced while triaging ~28 design docs in .emacs.d. Both belong in rulesets — the spec-create workflow (=.ai/workflows/spec-create.org=) and likely a new docs-lifecycle rule under =claude-rules/=.
+
+** A. Separate specs from working notes by location
+Today .emacs.d/docs/design/ holds everything in one bucket: formal specs (goals/decisions/phases/acceptance) jumbled with brainstorms, inventories, reviews, and idea-lists. You can't tell specs from notes without opening each file.
+
+Proposal: formal specs live in =docs/specs/=; =docs/design/= keeps working notes, brainstorms, inventories, and reviews. A "spec" is a doc proposing a buildable change with a Decisions section and phases; everything else is a note.
+
+** B. Make a spec's lifecycle status glanceable
+Specs carry no lifecycle status today, so which shipped, which are open, and which are dead is invisible. I had to run a four-agent sweep reading every spec against the code to reconstruct it (6 implemented, 8 in-progress, 12 not-started, 1 superseded). A status convention makes that a one-line scan.
+
+Two parts:
+- Filename suffix (Craig's idea): =<topic>-spec.org= (draft / not-started) → =-spec-doing.org= → =-spec-implemented.org= → =-spec-superseded.org= / =-spec-cancelled.org=. Visible in =ls=, greppable by glob, impossible to forget.
+- Authoritative Status field in the spec's Metadata table, on every spec (retrofit old ones). The filename is the index; the field is the record — it also carries a dated history line a filename can't hold.
+
+* Why
+
+Triage. A collection of specs with no status field and no location split degrades into "open it to find out." The cost compounds with every spec added. The two conventions together make the answer visible from a directory listing.
+
+* Recommendations / refinements
+
+- Pair filename suffix + Status field; the field is authoritative, the filename is the at-a-glance index. Don't let the filename be the only record (it's volatile and loses the why/when).
+- Link safety is the real cost. Both the move to =docs/specs/= and every status rename break =[[file:...]]= links (e.g. todo.org → a spec's Related link). Mitigate one of two ways, and pick one as the standard:
+  - Switch cross-doc links to =org-id= (=[[id:...]]=), which survive moves and renames; or
+  - A helper that moves/renames + relinks inbound references + stamps the Status field + appends a dated history line, run on each transition — so a status change is one command, not manual link surgery.
+- Vocabulary: draft (no suffix) / doing / implemented / superseded / cancelled. An in-progress-but-partial spec is "doing."
+
+* The bigger design choice rulesets should weigh
+
+Filename-encoded status is one option; the other is the org TODO keyword on the spec's top heading. These specs already carry =#+TODO: TODO | DONE SUPERSEDED CANCELLED=, so the top-heading keyword could be the status — scannable via a docs/specs org-agenda view, greppable, and it never breaks a link because the filename stays stable. The tradeoff is ls-visibility (filename wins) versus link-stability and zero-rename transitions (org-keyword wins). Worth deciding deliberately; my lean is filename suffix for the listing-level visibility Craig wants, paired with the Status field, with org-id links to neutralize the rename cost.
+
+* Generalization — a reusable pattern
+
+This is not spec-specific. The shape is: lifecycle state visible in the artifact's name (or location), an authoritative status record inside the artifact, rename-safe linking, and formal artifacts separated from working notes by location. Reach for it whenever triaging a growing collection of processed documents or media — brainstorms, inbox items, working-files, a transcription/recording queue, anything with a draft → in-progress → done/dropped lifecycle. Worth capturing as a general docs-lifecycle convention in claude-rules/, with the spec-create workflow as the first concrete instance.
+
+* Follow-up
+
+- Decide the canonical mechanism (filename suffix vs org-TODO-keyword) and the link-safety standard (org-id vs relink-helper).
+- Update spec-create to emit into =docs/specs/= with a Status field and the chosen status mechanism documented.
+- If you want the relink-helper, it's a natural =.ai/scripts/= addition that downstream projects get via the template sync.
+- Send a note back if you want .emacs.d to pilot the chosen approach before it's generalized.
diff --git a/todo.org b/todo.org
index 0cd0ebe..3ab2430 100644
--- a/todo.org
+++ b/todo.org
@@ -1079,6 +1079,26 @@ Codex ran the spec-review workflow. Outcome: the combined spec is =Not ready= be
 *** 2026-06-12 Fri @ 02:39:38 -0500 Second review after response pass
 Codex re-ran spec-review after the dispositions were folded in. Outcome by arc: Phase 1.5 helper instances =Ready with caveats=; phases 2-5 remain =Not ready= behind the explicit decisions/reverification gate. No new blocking findings for the helper slice. Review file updated in place: [[file:docs/design/2026-05-28-generic-agent-runtime-spec-review.org]].
 
+** TODO [#C] Spec storage location + lifecycle-status convention :spec:
+:PROPERTIES:
+:CREATED: [2026-06-15 Mon]
+: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).
+
+The two conventions:
+- *Location split* — formal specs live in =docs/specs/=; =docs/design/= keeps working notes, brainstorms, inventories, reviews. A spec is a doc proposing a buildable change with a Decisions section and phases; everything else is a note.
+- *Glanceable lifecycle status* — a spec's state (draft / doing / implemented / superseded / cancelled) is visible without opening the file, plus an authoritative in-file record.
+
+Recommendation captured now so the thinking isn't lost; it migrates into the spec when this is worked. We handle the task in priority order.
+
+*** Recommendation (draft — decide when worked, migrate into the spec)
+1. *Location split — adopt.* Low controversy, clear payoff. =docs/specs/= for formal specs, =docs/design/= for notes. Document in spec-create and the docs-lifecycle rule.
+2. *Status mechanism — the real fork.* Two options: filename suffix (=-spec-doing.org=, Craig's idea, ls-visible but every transition is a rename that breaks =[[file:...]]= links) vs the org-TODO keyword on the spec's top heading (specs already carry =#+TODO: TODO | DONE SUPERSEDED CANCELLED=; link-stable, zero-rename, org-agenda-scannable, but not visible in =ls=). My lean is the org-keyword as authoritative + a Status field in the Metadata table, dropping the filename suffix — the suffix is redundant with the Status field and adds rename churn across a heavily cross-linked, template-synced doc set. This diverges from Craig's stated filename-suffix preference, so it's teed up as a decision, not settled. Decide deliberately before building.
+3. *Link safety — adopt =org-id= ([[id:...]]) for cross-doc spec links* regardless of which status mechanism wins. It decouples link stability from the status decision. Mandatory if the filename suffix wins; good hygiene either way. The alternative — a move/rename/relink/stamp helper run on each transition — is only needed if the suffix wins and org-id is rejected.
+4. *Generalize after the mechanism settles.* The shape (lifecycle state in name-or-location, authoritative in-artifact status, rename-safe links, formal-vs-notes split) is reusable beyond specs. Capture it as a general =docs-lifecycle= convention in =claude-rules/= with spec-create as the first instance — but don't generalize an unsettled convention.
+
+Follow-up once decided: update spec-create to emit into =docs/specs/= with the chosen status mechanism; retrofit existing specs; optionally add the relink helper as a =.ai/scripts/= addition (downstream projects get it via template sync); send a note back if .emacs.d should pilot before generalizing.
+
 * Rulesets Resolved
 ** DONE [#C] Fix =cj-scan= false positives on cj fences nested inside other =#+begin_*= blocks :bug:
 CLOSED: [2026-05-15 Fri]