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.

1 files changed, 44 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.