docs: move specs to docs/specs/ with lifecycle-status filenames

Separate the 27 formal specs from working notes. Specs move to docs/specs/, notes stay in docs/design/. Each spec carries its lifecycle in the filename (-spec, -spec-doing, -spec-implemented, -spec-superseded) plus an authoritative ID and STATUS property drawer. The status came from checking each spec against the code, not the doc's own field: 6 implemented, 8 in progress, 12 not started, 1 superseded.

Inbound links become org-id links so future status renames don't break them; code-comment paths repoint to docs/specs/. Working notes, inventories, reviews, and brainstorms stay in docs/design/.

34 files changed, 289 insertions, 28 deletions

diff --git a/docs/design/ai-kb-shared-roam-brainstorm.org b/docs/design/ai-kb-shared-roam-brainstorm.org
index e42e2b006..c2467380b 100644
--- a/docs/design/ai-kb-shared-roam-brainstorm.org
+++ b/docs/design/ai-kb-shared-roam-brainstorm.org
@@ -410,7 +410,7 @@ This layer answers:
 * Possible next task
 
 Convert this brainstorm into a concrete design delta for the existing
-=docs/design/ai-kb.org= and the open =Implement ai-kb= task:
+=docs/specs/ai-kb-spec.org= and the open =Implement ai-kb= task:
 
 - add agent query triggers;
 - specify personal-roam access boundaries;
diff --git a/docs/design/module-inventory.org b/docs/design/module-inventory.org
index 2d4baf81a..eeb824b57 100644
--- a/docs/design/module-inventory.org
+++ b/docs/design/module-inventory.org
@@ -4,7 +4,7 @@
 
 * Purpose
 
-Living per-module inventory for the [[file:init-load-graph.org][init.el load-graph refactor]]. The
+Living per-module inventory for the [[id:e1fd137e-e164-42f4-a658-f4d32fbe3228][init.el load-graph refactor]]. The
 spec's module-category table is the seed; this file is the per-module truth as
 each module is inspected and classified. A module moves from [[*Pending
 classification][Pending classification]] into [[*Classified modules][Classified
diff --git a/docs/design/music-config-without-emms-review.org b/docs/design/music-config-without-emms-review.org
index 67ef0d1b8..1aae670d6 100644
--- a/docs/design/music-config-without-emms-review.org
+++ b/docs/design/music-config-without-emms-review.org
@@ -3,7 +3,7 @@
 #+DATE: 2026-05-15
 #+OPTIONS: toc:nil num:nil
 
-Spec reviewed: =docs/design/music-config-without-emms.org=
+Spec reviewed: =docs/specs/music-config-without-emms-spec.org=
 Third pass.  This review answers the single question: is the spec in
 shape to start =/start-work= against?
 
diff --git a/docs/design/signal-client-review.org b/docs/design/signal-client-review.org
index 34b4bbda4..7e8a73e91 100644
--- a/docs/design/signal-client-review.org
+++ b/docs/design/signal-client-review.org
@@ -5,7 +5,7 @@
 * Scope reviewed
 
 - =.ai/workflows/spec-review.org=.
-- =docs/design/signal-client.org=, including the base design, open-question dispositions, initiate-message workflow, architecture additions, accepted caveats, test plan, scope summary, and readiness rubric.
+- =docs/specs/signal-client-spec-doing.org=, including the base design, open-question dispositions, initiate-message workflow, architecture additions, accepted caveats, test plan, scope summary, and readiness rubric.
 - =modules/signal-config.el=, including =cj/signal--parse-contacts=, notify-suppression helpers, private config loading, and current =use-package signel= wiring.
 - =~/code/signel/signel.el=, including =signel-start=, =signel--send-rpc=, =signel--dispatch=, =signel--handle-error=, =signel--handle-receive=, =signel--insert-msg=, =signel--insert-system-msg=, =signel--send-input=, =signel-chat=, and dashboard commands.
 - =tests/test-signal-config.el=, covering contact parsing and notify-suppression helpers.
diff --git a/docs/design/utility-inventory.org b/docs/design/utility-inventory.org
index cf4c13bd3..8438a5924 100644
--- a/docs/design/utility-inventory.org
+++ b/docs/design/utility-inventory.org
@@ -4,7 +4,7 @@
 
 * Status
 
-Living inventory. Phase 1 of [[file:utility-consolidation.org][utility-consolidation.org]]. Records the current state of helpers identified in the spec's Candidate Extraction Table plus any new candidates discovered during module walkthroughs. Decisions become concrete tasks in =todo.org= for Phase 2+.
+Living inventory. Phase 1 of [[id:fc2e3926-b4a1-4b45-92eb-20841e13f655][utility-consolidation-spec-doing.org]]. Records the current state of helpers identified in the spec's Candidate Extraction Table plus any new candidates discovered during module walkthroughs. Decisions become concrete tasks in =todo.org= for Phase 2+.
 
 * Scope
 
@@ -82,7 +82,7 @@ Caller counts in the inventory below reflect grep results from 2026-05-10. The c
 
 | Symbol | File | Vis | Deps | Side effects | Proposed home / name | Callers (modules) | Tests | Pri | Decision | Rationale |
 |--------+------+-----+------+--------------+----------------------+-------------------+-------+-----+----------+-----------|
-| =cj/modeline-vc-cache-*= helpers (key/get/put/clear/valid-p) | =modeline-config.el:108-140= | private | buffer-local vars | mutates buffer-local state | =cj-cache.el= / =cj/cache-valid-p=, =cj/cache-get=, =cj/cache-put=, =cj/cache-clear= | 1 (within file) | =test-modeline-config-vc-cache.el= | Medium | Defer | Good pattern, but variable-local cache shape differs from the agenda/refile caches. Needs design before extraction. Spec calls out a Phase 5 design addendum at =docs/design/cache-helper-design.org=. |
+| =cj/modeline-vc-cache-*= helpers (key/get/put/clear/valid-p) | =modeline-config.el:108-140= | private | buffer-local vars | mutates buffer-local state | =cj-cache.el= / =cj/cache-valid-p=, =cj/cache-get=, =cj/cache-put=, =cj/cache-clear= | 1 (within file) | =test-modeline-config-vc-cache.el= | Medium | Defer | Good pattern, but variable-local cache shape differs from the agenda/refile caches. Needs design before extraction. Spec calls out a Phase 5 design addendum at =docs/specs/cache-helper-design-spec-implemented.org=. |
 | agenda/refile cache vars and build flags | =org-agenda-config.el=, =org-refile-config.el= | n/a | timers, file scans | scans filesystem, sets vars | =cj-cache.el= / =cj/cache-value-or-rebuild= | 2 | none | Medium | Defer | TTL/build/invalidate lifecycle; higher risk than the modeline cache. Same Phase 5 work. |
 
 ** Logging / Warnings
@@ -144,7 +144,7 @@ These become =todo.org= entries (or update existing ones) as Phase 2 starts.
 
 ** Deferred (track in =todo.org= but no commit yet)
 
-- Cache abstraction (modeline + agenda/refile) -- needs Phase 5 design addendum at =docs/design/cache-helper-design.org=.
+- Cache abstraction (modeline + agenda/refile) -- needs Phase 5 design addendum at =docs/specs/cache-helper-design-spec-implemented.org=.
 - =cj/--open-with-is-launcher-p= -- move when external-open ownership is finalized.
 - =cj/log-silently= rename -- low value; do during incidental =system-lib= work.
 - HTML/text helpers (=strip-html=, =clean-text=) -- defer until a second consumer.
diff --git a/docs/design/ai-kb.org b/docs/specs/ai-kb-spec.org
index 22a9cb9cf..fbd35ca55 100644
--- a/docs/design/ai-kb.org
+++ b/docs/specs/ai-kb-spec.org
@@ -1,3 +1,7 @@
+:PROPERTIES:
+:ID:       03742426-35ce-41c5-aed7-d4e248e91833
+:STATUS:   not-started
+:END:
 #+TITLE: Design: AI Knowledge Base (ai-kb)
 #+AUTHOR: Craig Jennings
 #+DATE: 2026-05-24
diff --git a/docs/design/ai-vterm.org b/docs/specs/ai-vterm-spec-superseded.org
index 99526b632..0b6bfb86c 100644
--- a/docs/design/ai-vterm.org
+++ b/docs/specs/ai-vterm-spec-superseded.org
@@ -1,3 +1,7 @@
+:PROPERTIES:
+:ID:       3abd0270-e87c-42b7-9b3a-ef60300db99d
+:STATUS:   superseded
+:END:
 #+TITLE: Design: ai-vterm — in-Emacs Claude launcher
 #+AUTHOR: Craig Jennings
 #+DATE: 2026-05-07
diff --git a/docs/design/cache-helper-design.org b/docs/specs/cache-helper-design-spec-implemented.org
index 5de0f348c..27c818dcb 100644
--- a/docs/design/cache-helper-design.org
+++ b/docs/specs/cache-helper-design-spec-implemented.org
@@ -1,10 +1,14 @@
+:PROPERTIES:
+:ID:       647c5101-21c2-47bb-aaa7-72c757f45fb7
+:STATUS:   implemented
+:END:
 #+TITLE: Cache Helper Design Addendum
 #+AUTHOR: Craig Jennings
 #+DATE: 2026-05-10
 
 * Status
 
-Phase 5 design addendum to [[file:utility-consolidation.org][utility-consolidation.org]]. Specifies the cache API to extract before any code moves.
+Phase 5 design addendum to [[id:fc2e3926-b4a1-4b45-92eb-20841e13f655][utility-consolidation-spec-doing.org]]. Specifies the cache API to extract before any code moves.
 
 * Problem
 
diff --git a/docs/design/company-to-corfu-migration.org b/docs/specs/company-to-corfu-migration-spec.org
index 55da081c8..a7b059a3b 100644
--- a/docs/design/company-to-corfu-migration.org
+++ b/docs/specs/company-to-corfu-migration-spec.org
@@ -1,3 +1,7 @@
+:PROPERTIES:
+:ID:       68733ba2-37a7-4a7b-bfaa-b845d82ff1e7
+:STATUS:   not-started
+:END:
 #+TITLE: Design: Migrate from Company to Corfu (with prescient integration)
 #+AUTHOR: Craig Jennings
 #+DATE: 2026-05-15
diff --git a/docs/design/coverage.org b/docs/specs/coverage-spec-implemented.org
index acd8b4c43..65734fb3d 100644
--- a/docs/design/coverage.org
+++ b/docs/specs/coverage-spec-implemented.org
@@ -1,3 +1,7 @@
+:PROPERTIES:
+:ID:       7d7f4486-fad7-4f0a-bd9a-775bd4cd8f7e
+:STATUS:   implemented
+:END:
 #+TITLE: Design: Coverage Reporting
 #+AUTHOR: Craig Jennings
 #+DATE: 2026-04-22
diff --git a/docs/design/debug-profiling.org b/docs/specs/debug-profiling-spec.org
index 3f5792501..5961071b8 100644
--- a/docs/design/debug-profiling.org
+++ b/docs/specs/debug-profiling-spec.org
@@ -1,3 +1,7 @@
+:PROPERTIES:
+:ID:       c713b431-ae14-498d-aba9-b84d52f981b6
+:STATUS:   not-started
+:END:
 #+TITLE: Design: debug-profiling.el module
 #+AUTHOR: Craig Jennings
 #+DATE: 2026-04-26
diff --git a/docs/design/dev-setup-project.org b/docs/specs/dev-setup-project-spec.org
index 280b015b2..5d64f368f 100644
--- a/docs/design/dev-setup-project.org
+++ b/docs/specs/dev-setup-project-spec.org
@@ -1,3 +1,7 @@
+:PROPERTIES:
+:ID:       596fce5d-1bab-46e7-8567-d4a2e0923091
+:STATUS:   not-started
+:END:
 #+TITLE: Design: cj/dev-setup-project
 #+AUTHOR: Craig Jennings
 #+DATE: 2026-04-22
diff --git a/docs/design/dupre-clear-theme.org b/docs/specs/dupre-clear-theme-spec.org
index 3b88a7d0f..9594eb3d9 100644
--- a/docs/design/dupre-clear-theme.org
+++ b/docs/specs/dupre-clear-theme-spec.org
@@ -1,3 +1,7 @@
+:PROPERTIES:
+:ID:       20df7f50-4759-47ba-9782-8dd25a2e173e
+:STATUS:   not-started
+:END:
 #+TITLE: dupre-clear — a contrast-first AAA sibling theme
 #+AUTHOR: Craig Jennings
 #+DATE: 2026-06-07
diff --git a/docs/design/face-font-diagnostic-popup-spec.org b/docs/specs/face-font-diagnostic-popup-spec.org
index be83a31ab..bbd67e92d 100644
--- a/docs/design/face-font-diagnostic-popup-spec.org
+++ b/docs/specs/face-font-diagnostic-popup-spec.org
@@ -1,3 +1,7 @@
+:PROPERTIES:
+:ID:       98f065cf-8bd5-46a0-ac24-da94d66855ad
+:STATUS:   not-started
+:END:
 #+TITLE: Face and Font Diagnostic Popup — Spec
 #+AUTHOR: Craig Jennings
 #+DATE: 2026-06-14
@@ -5,7 +9,7 @@
 
 * Metadata
 
-| Status   | draft                                             |
+| Status   | not-started                                             |
 |----------+---------------------------------------------------|
 | Owner    | Craig Jennings                                    |
 |----------+---------------------------------------------------|
diff --git a/docs/design/flycheck-modeline-customization.org b/docs/specs/flycheck-modeline-customization-spec-implemented.org
index 25e2c7854..59567be60 100644
--- a/docs/design/flycheck-modeline-customization.org
+++ b/docs/specs/flycheck-modeline-customization-spec-implemented.org
@@ -1,3 +1,7 @@
+:PROPERTIES:
+:ID:       76979608-956e-474f-90a8-8d0c958101a0
+:STATUS:   implemented
+:END:
 #+TITLE: Design: Flycheck modeline customization
 #+AUTHOR: Craig Jennings
 #+DATE: 2026-05-15
diff --git a/docs/design/gloss.org b/docs/specs/gloss-spec-doing.org
index 04efc38bf..320b83ebf 100644
--- a/docs/design/gloss.org
+++ b/docs/specs/gloss-spec-doing.org
@@ -1,3 +1,7 @@
+:PROPERTIES:
+:ID:       295f9969-ccef-4df9-945b-9e08d8069daf
+:STATUS:   doing
+:END:
 #+TITLE: Design — gloss (Glossary Lookup with Online-Sourced Selection)
 #+DATE: 2026-04-28
 #+STATUS: Draft
diff --git a/docs/design/gptel-gh-tool.org b/docs/specs/gptel-gh-tool-spec.org
index a9ba22bb1..80ecc0ab6 100644
--- a/docs/design/gptel-gh-tool.org
+++ b/docs/specs/gptel-gh-tool-spec.org
@@ -1,3 +1,7 @@
+:PROPERTIES:
+:ID:       a124dd0f-1f40-4533-aeb8-595d93e20865
+:STATUS:   not-started
+:END:
 #+TITLE: Design: Wrap the gh CLI as a GPTel tool
 #+AUTHOR: Craig Jennings
 #+DATE: 2026-05-16
@@ -1052,7 +1056,7 @@ Items intentionally deferred:
 - [[file:gptel-agentic-tool-ideas.org][gptel-agentic-tool-ideas.org]] -- broader agentic-tool design;
   =gh= sits alongside the MCP integration as the
   collaboration tier.
-- [[file:mcp-el-gptel-integration.org][mcp-el-gptel-integration.org]] -- sibling design; same
+- [[id:b4c274c5-8572-4a7b-b657-d315712bd6af][mcp-el-gptel-integration-spec-doing.org]] -- sibling design; same
   confirm-on-write pattern for safety.
 - [[https://cli.github.com/manual/][gh CLI manual]] -- subcommand reference.
 - =gh --version 2.92.0= help output -- verified flag semantics
diff --git a/docs/design/gptel-git-tools-magit-backend.org b/docs/specs/gptel-git-tools-magit-backend-spec.org
index 94fbb0cec..bd84b0595 100644
--- a/docs/design/gptel-git-tools-magit-backend.org
+++ b/docs/specs/gptel-git-tools-magit-backend-spec.org
@@ -1,3 +1,7 @@
+:PROPERTIES:
+:ID:       bd47c9a8-aae1-4a3d-ad5b-b8767f2fd580
+:STATUS:   not-started
+:END:
 #+TITLE: Design: gptel git tools on a magit backend
 #+AUTHOR: Craig Jennings
 #+DATE: 2026-05-16
diff --git a/docs/design/gptel-network-tools.org b/docs/specs/gptel-network-tools-spec.org
index aae2cc2a8..c28d54694 100644
--- a/docs/design/gptel-network-tools.org
+++ b/docs/specs/gptel-network-tools-spec.org
@@ -1,3 +1,7 @@
+:PROPERTIES:
+:ID:       6388588c-dac2-4c52-97ad-2343ba1443fc
+:STATUS:   not-started
+:END:
 #+TITLE: Design: gptel network tools
 #+AUTHOR: Craig Jennings
 #+DATE: 2026-05-16
@@ -7,7 +11,7 @@
 
 Draft.  Brainstorm output captured from a =/brainstorm= session on
 2026-05-16.  Sibling to
-=docs/design/gptel-git-tools-magit-backend.org= and the broader theme
+=docs/specs/gptel-git-tools-magit-backend-spec.org= and the broader theme
 hierarchy under =** TODO [#B] GPTel Tool Work= in =todo.org=.
 
 The conventional vs tail-sample exploration covered three categories
diff --git a/docs/design/init-load-graph.org b/docs/specs/init-load-graph-spec-doing.org
index 3db2fe854..05dd9e0a3 100644
--- a/docs/design/init-load-graph.org
+++ b/docs/specs/init-load-graph-spec-doing.org
@@ -1,3 +1,7 @@
+:PROPERTIES:
+:ID:       e1fd137e-e164-42f4-a658-f4d32fbe3228
+:STATUS:   doing
+:END:
 #+TITLE: Design: Untangle the init.el Load Graph
 #+AUTHOR: Craig Jennings
 #+DATE: 2026-05-04
@@ -174,7 +178,7 @@ Foundation modules should be able to load in batch mode without package,
 network, timer, or UI-package side effects.
 
 Adding a new Layer 1 module requires a coordinated update to the
-=system-lib.el= dependency budget in [[file:utility-consolidation.org][utility-consolidation.org]].
+=system-lib.el= dependency budget in [[id:fc2e3926-b4a1-4b45-92eb-20841e13f655][utility-consolidation-spec-doing.org]].
 
 Topic libraries introduced by the utility project join Layer 1 only when their
 first consumer is foundation-eager. Otherwise they are Layer 2 and loaded by an
@@ -391,7 +395,7 @@ Worked example:
 ;; Runtime requires: user-constants, seq, subr-x.
 ;; Direct test load: yes (batch-safe; private config is optional).
 ;;
-;; See also: docs/design/init-load-graph.org, tests/test-calendar-sync.el.
+;; See also: docs/specs/init-load-graph-spec-doing.org, tests/test-calendar-sync.el.
 ;;
 ;;; Code:
 #+end_src
@@ -448,7 +452,7 @@ Inventory rules:
 - Every module required by =init.el= must be represented before Phase 2 starts.
 - Discoveries during later phases update the inventory.
 - This inventory is independent from the helper inventory owned by
-  [[file:utility-consolidation.org][utility-consolidation.org]].
+  [[id:fc2e3926-b4a1-4b45-92eb-20841e13f655][utility-consolidation-spec-doing.org]].
 
 Exit criteria:
 
@@ -643,7 +647,7 @@ rollback shapes.
 This sibling project can run beside Phase 2. When explicit-dependency work finds
 a generic duplicated helper, the sibling project owns the extraction commit when
 the helper is in scope for that project. See
-[[file:utility-consolidation.org][utility-consolidation.org]] for candidate
+[[id:fc2e3926-b4a1-4b45-92eb-20841e13f655][utility-consolidation-spec-doing.org]] for candidate
 helpers, naming rules, dependency budgets, migration phases, and test policy.
 
 * Testing Strategy
diff --git a/docs/design/keybinding-console-safety-spec.org b/docs/specs/keybinding-console-safety-spec-doing.org
index d06c5a279..4a1dec813 100644
--- a/docs/design/keybinding-console-safety-spec.org
+++ b/docs/specs/keybinding-console-safety-spec-doing.org
@@ -1,9 +1,13 @@
+:PROPERTIES:
+:ID:       540bf06b-16b8-46c6-b459-c40d1b9c795d
+:STATUS:   doing
+:END:
 #+TITLE: Keymap Consolidation — Spec
 #+AUTHOR: Craig Jennings
 #+DATE: 2026-06-12
 
 * Metadata
-| Status   | draft                                                              |
+| Status   | doing                                                              |
 |----------+--------------------------------------------------------------------|
 | Owner    | Craig Jennings                                                     |
 |----------+--------------------------------------------------------------------|
@@ -890,7 +894,7 @@ translation block being retired). =C-l= appears only minibuffer-local in
 - Why: a touched key family broke in GUI and is dead in console; the fix path is
   cross-cutting (18 keys, a translation layer to retire, a console-safety
   architecture) with real trade-offs, so it clears the spec bar.
-- Artifacts: docs/design/keybinding-console-safety-spec.org; supersedes the
+- Artifacts: docs/specs/keybinding-console-safety-spec-doing.org; supersedes the
   pre-template draft docs/design/keybinding-console-safety.org.
 ** 2026-06-12 Fri @ 18:30:30 -0500 — Craig Jennings — review response
 - What: processed Craig's four review comments. Recorded his first-choice
diff --git a/docs/design/mcp-el-gptel-integration.org b/docs/specs/mcp-el-gptel-integration-spec-doing.org
index 6bac77c54..f22e91959 100644
--- a/docs/design/mcp-el-gptel-integration.org
+++ b/docs/specs/mcp-el-gptel-integration-spec-doing.org
@@ -1,3 +1,7 @@
+:PROPERTIES:
+:ID:       b4c274c5-8572-4a7b-b657-d315712bd6af
+:STATUS:   doing
+:END:
 #+TITLE: Design: Wire mcp.el into GPTel for MCP server access
 #+AUTHOR: Craig Jennings
 #+DATE: 2026-05-16
@@ -1420,7 +1424,7 @@ C= so existing GPTel keys aren't disturbed (rev 3).
 - [[file:gptel-tools-shortlist.org][gptel-tools-shortlist.org]] -- local-tools shortlist; MCP servers
   slot in as the "external" tier.
 - [[file:gptel-agentic-tool-ideas.org][gptel-agentic-tool-ideas.org]] -- broader agentic-tool design.
-- [[file:gptel-gh-tool.org][gptel-gh-tool.org]] -- sibling design; same confirm-on-write
+- [[id:a124dd0f-1f40-4533-aeb8-595d93e20865][gptel-gh-tool-spec.org]] -- sibling design; same confirm-on-write
   pattern.
 - [[https://github.com/lizqwerscott/mcp.el][lizqwerscott/mcp.el]] -- upstream.
 - [[https://github.com/lizqwerscott/gptel-mcp.el][lizqwerscott/gptel-mcp.el]] -- considered and declined; see §
diff --git a/docs/design/messenger-unification-spec.org b/docs/specs/messenger-unification-spec.org
index 7e8780300..f8d3b4734 100644
--- a/docs/design/messenger-unification-spec.org
+++ b/docs/specs/messenger-unification-spec.org
@@ -1,3 +1,7 @@
+:PROPERTIES:
+:ID:       4bfc2011-8ffc-4765-8886-91df12141171
+:STATUS:   not-started
+:END:
 #+TITLE: Messenger Unification — Shared Window Placement and Key Conventions
 #+AUTHOR: Craig Jennings & Claude
 #+DATE: 2026-06-11
diff --git a/docs/design/music-config-without-emms.org b/docs/specs/music-config-without-emms-spec.org
index 929423df6..32fd67367 100644
--- a/docs/design/music-config-without-emms.org
+++ b/docs/specs/music-config-without-emms-spec.org
@@ -1,3 +1,7 @@
+:PROPERTIES:
+:ID:       423bc355-18d3-4e39-9e7a-f768b865d95b
+:STATUS:   not-started
+:END:
 #+TITLE: Design: music-config Without EMMS
 #+AUTHOR: Craig Jennings
 #+DATE: 2026-05-15
diff --git a/docs/design/org-faces-spec.org b/docs/specs/org-faces-spec-implemented.org
index c81880270..c88559061 100644
--- a/docs/design/org-faces-spec.org
+++ b/docs/specs/org-faces-spec-implemented.org
@@ -1,10 +1,14 @@
+:PROPERTIES:
+:ID:       35578114-8c29-43af-97a2-fdfea01a802e
+:STATUS:   implemented
+:END:
 #+TITLE: Org Header-Row Faces — Spec
 #+AUTHOR: Craig Jennings
 #+DATE: 2026-06-15
 #+TODO: TODO | DONE SUPERSEDED CANCELLED
 
 * Metadata
-| Status   | draft                                                          |
+| Status   | implemented                                                          |
 |----------+----------------------------------------------------------------|
 | Owner    | Craig Jennings                                                 |
 |----------+----------------------------------------------------------------|
diff --git a/docs/design/signal-client.org b/docs/specs/signal-client-spec-doing.org
index ef946b80c..beee0acf1 100644
--- a/docs/design/signal-client.org
+++ b/docs/specs/signal-client-spec-doing.org
@@ -1,3 +1,7 @@
+:PROPERTIES:
+:ID:       0cabd6ee-c458-47b5-a8af-3ee054b25821
+:STATUS:   doing
+:END:
 #+TITLE: Design: Signal client in Emacs (forked signel)
 #+DATE: 2026-05-26
 #+STATUS: Draft
diff --git a/docs/design/theme-studio-package-faces-spec.org b/docs/specs/theme-studio-package-faces-spec-doing.org
index 7f00b3279..566f34db0 100644
--- a/docs/design/theme-studio-package-faces-spec.org
+++ b/docs/specs/theme-studio-package-faces-spec-doing.org
@@ -1,3 +1,7 @@
+:PROPERTIES:
+:ID:       8f37a1fd-cfd3-4b25-92e5-772468092bdc
+:STATUS:   doing
+:END:
 #+TITLE: theme-studio — package faces (tier 3), starting with org-mode
 #+AUTHOR: Craig Jennings
 #+DATE: 2026-06-07
diff --git a/docs/design/theme-studio-perceptual-color-metrics-spec.org b/docs/specs/theme-studio-perceptual-color-metrics-spec-implemented.org
index 7e7dedb22..57a4c70bc 100644
--- a/docs/design/theme-studio-perceptual-color-metrics-spec.org
+++ b/docs/specs/theme-studio-perceptual-color-metrics-spec-implemented.org
@@ -1,3 +1,7 @@
+:PROPERTIES:
+:ID:       15db8ae3-fc14-49f3-9ed5-d5ff59790904
+:STATUS:   implemented
+:END:
 #+TITLE: theme-studio — perceptual color metrics (OKLCH, APCA, ΔE)
 #+AUTHOR: Craig Jennings
 #+DATE: 2026-06-08
diff --git a/docs/design/theme-studio-seeding-engine-spec.org b/docs/specs/theme-studio-seeding-engine-spec-doing.org
index bcbf43db4..baf9f5b01 100644
--- a/docs/design/theme-studio-seeding-engine-spec.org
+++ b/docs/specs/theme-studio-seeding-engine-spec-doing.org
@@ -1,3 +1,7 @@
+:PROPERTIES:
+:ID:       b70b37f2-37df-4c8e-ac2f-1f20d12e33dd
+:STATUS:   doing
+:END:
 #+TITLE: theme-studio — seeding engine (role table to guide-correct defaults)
 #+AUTHOR: Craig Jennings
 #+DATE: 2026-06-08
@@ -313,7 +317,7 @@ response resolved; everything else was woven into the body as written.
   budget this engine executes.
 - =scripts/theme-studio/generate.py= — =CATS=, =UI_FACES=/=UIMAP=, =APPS= /
   =seedPkgmap=, =exportObj= (the target shape).
-- =docs/design/theme-studio-perceptual-color-metrics-spec.org= — the
+- =docs/specs/theme-studio-perceptual-color-metrics-spec-implemented.org= — the
   =colormath.js= core that v1 OKLCH shade generation uses.
 
 * Review and iteration history
diff --git a/docs/specs/theme-studio-structured-output-spec.org b/docs/specs/theme-studio-structured-output-spec.org
new file mode 100644
index 000000000..ad189b7eb
--- /dev/null
+++ b/docs/specs/theme-studio-structured-output-spec.org
@@ -0,0 +1,157 @@
+:PROPERTIES:
+:ID:       eaac7707-ed05-43df-9e51-b17c1d672531
+:STATUS:   not-started
+:END:
+#+TITLE: Theme-Studio Structured Theme Output — Spec
+#+AUTHOR: Craig Jennings
+#+DATE: 2026-06-15
+#+TODO: TODO | DONE SUPERSEDED CANCELLED
+
+* Metadata
+| Status   | not-started                                                          |
+|----------+----------------------------------------------------------------|
+| Owner    | Craig Jennings                                                 |
+|----------+----------------------------------------------------------------|
+| Reviewer | Craig Jennings                                                 |
+|----------+----------------------------------------------------------------|
+| Related  | [[file:../../todo.org][todo.org: theme-studio output + dupre retirement]]      |
+|----------+----------------------------------------------------------------|
+
+* Summary
+
+Replace build-theme.el's flat deftheme (literal hex on every face) with a structured two-file output: a palette file naming each color, and a theme file whose face assignments reference the palette through a binding. A hue change becomes one edit that propagates to every face on that color, the output reads meaningfully, and the same assignments paired with a different palette make a variant. The hand-authored dupre theme is retired in the same effort: it survives only as the fallback and a structural reference now that a theme-studio export (WIP) is the active theme.
+
+* Problem / Context
+
+build-theme.el converts a theme-studio theme.json into a deftheme, and it does so flat: one =custom-theme-set-faces= with a literal hex per face and no color layer above it (the converter's own header says "Do not hand-edit; re-run the converter"). It is faithful but unreadable, and a single hue change touches every face that used that color, scattered across the file. The structure that made the hand-authored dupre theme maintainable — a palette of named colors, faces referencing those names, organized by category — is discarded at generation time.
+
+dupre carried that structure in a three-file split (theme / palette / faces), and that structure was the value. But it is theme-specific source the user no longer wants to hand-maintain. WIP, a theme-studio export, is already the active theme (=persist/emacs-theme= reads "WIP"); dupre is now only =fallback-theme-name= and a reference. theme.json already carries a named palette — a list of =[hex name family]= triples — so the data needed to generate a structured theme already exists; only the converter throws it away.
+
+The driver: make generated themes inherit dupre's structural virtues in a generated-appropriate shape, and remove dupre.
+
+* Goals and Non-Goals
+
+** Goals
+- build-theme emits two files: =NAME-palette.el= (named colors) and =NAME-theme.el= (deftheme entry plus assignments that reference palette names).
+- A hue change is one edit in theme.json's palette, re-exported, and reaches every face on that color.
+- Assignments are separable from palette, so a palette swap yields a variant theme.
+- Faces are grouped and commented by tier (default, syntax, ui, packages) for readability.
+- Output stays one-way generated (do-not-hand-edit banner); theme.json is canonical.
+- dupre is removed: the three theme files and its test deleted, =fallback-theme-name= moved to a built-in, references and comments updated.
+
+** Non-Goals
+- No semantic-role layer (accent/err/keyword → palette) in v1 — deferred, but the format leaves room for it.
+- No OKLCH ramps, perceptual palette renaming, or auto light/dark variants.
+- No change to theme-studio's editing UI.
+- Not changing the theme-studio model: the palette already exists in theme.json; v1 reads it, it does not redesign it.
+
+** Scope tiers
+- v1: build-theme two-file structured output; the palette file from theme.json's palette list; face assignments referencing palette names via a binding, one-off hexes left literal; tier organization; regenerate the active theme in the new format; retire dupre and move the fallback.
+- vNext: a semantic-role layer; per-face palette-name carriage in theme-studio (preserve intent when two roles share a hex); palette-swap variant tooling.
+
+* Design
+
+** For the user
+Tune in theme-studio and export, as today. The generated theme is now two files. The palette file lists every named color once. The theme file maps each face to a color by name, grouped by area (syntax, UI, packages) so it reads like a description of the theme rather than a hex dump. To shift a hue, change it in theme-studio and re-export; every face on that color moves together. The same theme file paired with a different palette file is a variant — the lineage that took distinguished to dupre, made explicit.
+
+** For the implementer
+build-theme/--render splits into two emitters fed by the parsed theme.json:
+- Palette emitter: from theme.json's =palette= list of =[hex name family]=, write =NAME-palette.el= — a =defconst NAME-palette= (or a set of named constants) mapping name to hex, optionally grouped by family with section comments, ending in =(provide 'NAME-palette)=.
+- Theme emitter: write =NAME-theme.el= — the =deftheme=, =(require 'NAME-palette)=, then =custom-theme-set-faces= wrapped in a binding over the palette names (a =let= built from the palette, mirroring dupre-with-colors) so face specs reference names. Each face's stored hex is reverse-mapped to a palette name by exact match; a hex absent from the palette stays a literal string. Faces grouped by tier with comments. End =(provide-theme 'NAME)=.
+Both files carry the generated/do-not-hand-edit banner. =NAME-theme.el= requires =NAME-palette.el=, so the themes directory must be on the load path at theme-load time (the existing dupre arrangement already does this for the themes dir).
+
+* Alternatives Considered
+
+** Keep the flat per-face-hex output
+- Good: no converter change; the output is trivially correct.
+- Bad: unreadable, and a hue change is scattered across every face — the maintainability problem this spec exists to fix.
+- Neutral: it is generated, so "unreadable" matters only when a human reads or hand-tweaks it, which the structured format is meant to enable.
+
+** Three-file split (theme / palette / faces), exactly like dupre
+- Good: maximal separation; the deftheme boilerplate is isolated.
+- Bad: a generated theme's deftheme wrapper is a few lines — a third file is more ceremony than generated output needs.
+- Neutral: could become warranted in vNext if the assignments file grows unwieldy.
+
+** Carry a palette-name reference per face in theme.json (no reverse-map)
+- Good: preserves the designer's intended name even when two roles share a hex.
+- Bad: a theme-studio model and export change, larger than v1; the reverse-map gets the same readable output from data that already exists.
+- Neutral: the better long-term design; logged as vNext.
+
+* Decisions [6/6]
+
+** DONE Two-file output shape
+- Context: an Emacs theme needs =NAME-theme.el= for discovery; the palette wants to be independently swappable.
+- Decision: Two files — =NAME-palette.el= (named colors) and =NAME-theme.el= (deftheme entry plus assignments). The assignments ride with the deftheme rather than getting a third file.
+- Consequences: easier — palette swaps for variants, one place to retune hues, less ceremony than dupre's three files; harder — the theme file still mixes deftheme boilerplate with assignments.
+
+** DONE Faces reference the palette via a binding
+- Context: faces must name colors, not inline hex, for the one-edit-propagates property.
+- Decision: The theme file wraps =custom-theme-set-faces= in a =let= over the palette names (mirroring dupre-with-colors) and face specs reference the names.
+- Consequences: easier — readable specs, single source of color truth; harder — the converter must build the binding and reverse-map face hexes to names.
+
+** DONE Derive the palette layer by reverse-mapping face hex to palette names
+- Context: theme.json stores resolved hex per face but already carries a named palette list (=[hex name family]=).
+- Decision: build-theme reads the palette list to emit the palette file and reverse-maps each face's hex to a palette name by exact match; a hex with no palette entry stays a literal string.
+- Consequences: easier — no theme-studio model change, uses data that already exists; harder — a hex shared by two intended roles collapses to one name (intent loss), which per-face name carriage would fix in vNext.
+
+** DONE Semantic-role layer deferred
+- Context: dupre had roles (accent/err/keyword → palette) above the palette; the user may want them later.
+- Decision: No role layer in v1. The format keeps the palette binding so a role binding can slot above it later without reshaping the output.
+- Consequences: easier — smaller v1, fewer indirection layers to reason about; harder — role intent is not captured yet, so a role rename is a vNext addition.
+
+** DONE Retire dupre, move the fallback to a built-in
+- Context: WIP (a theme-studio export) is already active; dupre is only =fallback-theme-name= and a reference; the fallback has no further fallback, so it must be guaranteed present.
+- Decision: Delete the three dupre files and =test-dupre-theme.el=; set =fallback-theme-name= to "modus-vivendi" (built-in, always available); update the persistence/commands tests and the stale comments in auto-dim-config.el and org-config.el.
+- Consequences: easier — removes hand-maintained theme source, retires the four already-failing dupre palette tests; harder — the fallback loses chosen dimming colors (acceptable for a rare last resort), and dupre's look survives only in git and in WIP's lineage.
+
+** DONE Generated files stay one-way; theme.json is canonical
+- Context: the current converter already declares its output do-not-hand-edit.
+- Decision: Both generated files keep the generated banner; hue changes and palette swaps happen in theme-studio (or by generating from another theme.json), not by editing the output.
+- Consequences: easier — no source-of-truth ambiguity, regeneration is always safe; harder — a quick hand-tweak to the palette file is overwritten on the next export, so experiments route through theme-studio.
+
+* Implementation phases
+
+** Phase 1 — palette emitter
+Emit =NAME-palette.el= from theme.json's palette list: name→hex constants (grouped by family with comments), =(provide 'NAME-palette)=, generated banner. Done when the palette file loads and exposes every named color.
+
+** Phase 2 — theme emitter with palette references
+Rewrite build-theme/--render to emit =NAME-theme.el=: deftheme, require the palette, =custom-theme-set-faces= inside a =let= over the palette, face specs referencing names (reverse-mapped from hex; literals for one-offs), tier grouping and comments, =provide-theme=. Done when a theme.json round-trips to a loading theme whose faces render identically to the old flat output. Update test-build-theme.el to the two-file shape.
+
+** Phase 3 — regenerate the active theme
+Regenerate WIP (the active theme) in the new format via deploy-wip; confirm it loads and looks unchanged in the live daemon. Done when the round-trip lands with no visible difference.
+
+** Phase 4 — retire dupre
+Set =fallback-theme-name= to "modus-vivendi"; update test-ui-theme-commands.el and test-ui-theme-persistence.el; fix the stale comments in auto-dim-config.el and org-config.el; delete themes/dupre-theme.el, dupre-palette.el, dupre-faces.el and tests/test-dupre-theme.el. Done when the suite is green, startup uses WIP, and the fallback resolves to modus-vivendi. (Independent of Phases 1-3 — can land first since WIP is already active in the old format.)
+
+* Acceptance criteria
+- [ ] build-theme produces =NAME-palette.el= and =NAME-theme.el= for a given theme.json.
+- [ ] The generated theme loads and its faces render identically to the prior flat output for the same theme.json.
+- [ ] Changing one palette color in theme.json and re-exporting updates every face that used it.
+- [ ] The palette file names every distinct palette color; one-off face hexes remain literal.
+- [ ] dupre's files and test are gone; startup uses WIP; =fallback-theme-name= resolves to a present theme; suite green.
+
+* Readiness dimensions
+- Data model & ownership: theme.json (theme-studio) is canonical; the palette list is the color source; build-theme owns the generated files; both are one-way output.
+- Errors, empty states & failure: a face hex absent from the palette falls back to a literal — no failure, just an unnamed color. A missing palette file fails the theme load loudly (require error) rather than silently mis-coloring.
+- Security & privacy: N/A — color data only.
+- Observability: the live theme and theme-studio preview are the visible surface; a wrong reverse-map shows as a wrong color.
+- Performance & scale: N/A — tens of colors, ~150 faces, generated once per export.
+- Reuse & lost opportunities: rides the existing palette list and build-theme tiers; sets up palette-swap variants and a future role layer.
+- Architecture fit & weak points: mirrors dupre's proven palette/faces separation. Weak point is the hex→name reverse-map collapsing shared hexes — bounded by leaving one-offs literal and deferring name carriage to vNext.
+- Config surface: =fallback-theme-name= changes value; the themes load-path must include the generated palette file.
+- Documentation plan: the generated banner plus this spec; no user-facing docs.
+- Dev tooling: existing =make theme-studio-theme=, =deploy-wip=, and the build-theme test suite cover build and round-trip.
+- Rollout, compatibility & rollback: Phase 4 (dupre removal) is independent and reversible via git; Phases 1-3 change only generated output, rollback is reverting build-theme. The active theme (WIP) keeps working in the old format until regenerated.
+- External APIs & deps: =deftheme=, =custom-theme-set-faces=, =provide-theme=, =custom-theme-load-path= — all standard; modus-vivendi is built in.
+
+* Risks, Rabbit Holes, and Drawbacks
+- Reverse-map ambiguity: one hex, several intended roles, collapses to one name. Dodge: leave one-offs literal; defer per-face name carriage to vNext.
+- Identical render is the bar: the structured output must produce the same face attributes as the flat output. Dodge: a converter test that diffs resolved face specs old-vs-new for a fixture theme.json.
+- Load-path for the palette file: =NAME-theme.el= requiring =NAME-palette.el= needs the themes dir on the path at load time. Dodge: reuse dupre's existing arrangement.
+- Scope creep into the role layer or OKLCH work. Dodge: both are explicit Non-Goals / vNext.
+
+* Review and iteration history
+** 2026-06-15 Mon — Craig — author
+- What: initial draft.
+- Why: the dupre retirement turned into a question of what shape theme-studio's generated themes should take; the palette-vs-flat format, the file split, and the reverse-map approach are real trade-offs worth settling before touching build-theme.el.
+- Artifacts: scripts/theme-studio/build-theme.el (current flat renderer), scripts/theme-studio/theme.json (palette list already present), themes/dupre-* (the structural reference being retired).
diff --git a/docs/design/utility-consolidation.org b/docs/specs/utility-consolidation-spec-doing.org
index b84283804..b0a5fe2bd 100644
--- a/docs/design/utility-consolidation.org
+++ b/docs/specs/utility-consolidation-spec-doing.org
@@ -1,3 +1,7 @@
+:PROPERTIES:
+:ID:       fc2e3926-b4a1-4b45-92eb-20841e13f655
+:STATUS:   doing
+:END:
 #+TITLE: Design: Consolidate Shared Utility Helpers
 #+AUTHOR: Craig Jennings
 #+DATE: 2026-05-04
@@ -6,7 +10,7 @@
 
 Draft. Specification only. No helper extraction is part of this document.
 
-This is the sibling project to [[file:init-load-graph.org][Untangle the init.el Load Graph]]. The load-graph
+This is the sibling project to [[id:e1fd137e-e164-42f4-a658-f4d32fbe3228][Untangle the init.el Load Graph]]. The load-graph
 project decides when modules load and what dependencies they declare. This
 project decides which module should own reusable helper behavior.
 
@@ -291,7 +295,7 @@ Worked =system-lib.el= header:
 ;;   Private helpers rename without alias when all call sites change in the
 ;;   same commit.
 ;;
-;; See also: docs/design/utility-consolidation.org for design rationale.
+;; See also: docs/specs/utility-consolidation-spec-doing.org for design rationale.
 ;;
 ;;; Code:
 #+end_src
@@ -328,7 +332,7 @@ Load shape:
 - =cj-cache.el= follows the first real cache consumer's layer, likely Layer 2 if
   modeline/agenda/refile remain eager or near-eager.
 - Coordinate every new topic library with
-  [[file:init-load-graph.org][init-load-graph.org]] before migrating its first consumer.
+  [[id:e1fd137e-e164-42f4-a658-f4d32fbe3228][init-load-graph-spec-doing.org]] before migrating its first consumer.
 
 * Naming Rules
 
@@ -781,7 +785,7 @@ Recommendation:
   design addendum proves the API can drive the alignment.
 - Then decide whether modeline's buffer-local cache can use the same library or
   should remain specialized.
-- Phase 5 step 1 produces =docs/design/cache-helper-design.org=. Until that
+- Phase 5 step 1 produces =docs/specs/cache-helper-design-spec-implemented.org=. Until that
   file exists, =cj-cache.el= must not be created. The addendum is the
   prerequisite for any cache extraction commit.
 
@@ -902,7 +906,7 @@ Inventory artifact:
 - Treat the inventory as living documentation. Cleared high-priority candidates
   may move to Phase 2 before the whole inventory is complete.
 - This inventory is independent from the module-shape inventory maintained by
-  [[file:init-load-graph.org][init-load-graph.org]]. The two projects may walk the same files, but they
+  [[id:e1fd137e-e164-42f4-a658-f4d32fbe3228][init-load-graph-spec-doing.org]]. The two projects may walk the same files, but they
   record different facts in separate artifacts.
 
 For each helper record:
diff --git a/docs/design/vterm-to-ghostel-migration-spec.org b/docs/specs/vterm-to-ghostel-migration-spec-implemented.org
index 5974445ad..1be4fe227 100644
--- a/docs/design/vterm-to-ghostel-migration-spec.org
+++ b/docs/specs/vterm-to-ghostel-migration-spec-implemented.org
@@ -1,3 +1,7 @@
+:PROPERTIES:
+:ID:       b54c94a0-d762-4b41-afd7-cf5593ce6675
+:STATUS:   implemented
+:END:
 #+TITLE: Migration: vterm → ghostel (single terminal engine)
 #+AUTHOR: Craig Jennings
 #+DATE: 2026-06-04
@@ -171,7 +175,7 @@ Audited file set.
 
 ** Docs (active references only — historical notes stay)
 - =todo.org= current task link (already updated to this -spec path).
-- =docs/design/module-inventory.org=, =docs/design/init-load-graph.org= —
+- =docs/design/module-inventory.org=, =docs/specs/init-load-graph-spec-doing.org= —
   update active =vterm-config= / =ai-vterm= references to the new names.
 
 ** Tests (~35 files)
diff --git a/docs/theme-studio-palette-generator-spec.org b/docs/theme-studio-palette-generator-spec.org
index 8139f3d95..fca76b9c1 100644
--- a/docs/theme-studio-palette-generator-spec.org
+++ b/docs/theme-studio-palette-generator-spec.org
@@ -272,7 +272,7 @@ Use the existing Theme Studio test stack:
 
 * References / Appendix
 - [[file:design/theme-studio-color-harmony.org][theme-studio color harmony explainer]]
-- [[file:design/theme-studio-perceptual-color-metrics-spec.org][perceptual color metrics spec]]
+- [[id:15db8ae3-fc14-49f3-9ed5-d5ff59790904][perceptual color metrics spec]]
 - [[file:theme-studio-palette-ramps-spec.org][palette ramps and contrast safety spec]]
 - [[file:theme-studio-palette-columns-spec.org][palette columns spec]]
 - [[file:../todo.org::*theme-studio import organization workflow needs a spec][import organization task]]
diff --git a/docs/theme-studio-semantic-theme-architecture-spec.org b/docs/theme-studio-semantic-theme-architecture-spec.org
index 2fa318efb..25bafe9ea 100644
--- a/docs/theme-studio-semantic-theme-architecture-spec.org
+++ b/docs/theme-studio-semantic-theme-architecture-spec.org
@@ -253,7 +253,7 @@ Rollout should keep the current flat output path as the default and add a separa
 - Modus Themes source: [[https://github.com/protesilaos/modus-themes][github.com/protesilaos/modus-themes]]
 - Current converter: [[file:../scripts/theme-studio/build-theme.el][scripts/theme-studio/build-theme.el]]
 - Current Theme Studio README: [[file:../scripts/theme-studio/README.md][scripts/theme-studio/README.md]]
-- Package-face model spec: [[file:design/theme-studio-package-faces-spec.org][theme-studio-package-faces-spec.org]]
+- Package-face model spec: [[id:8f37a1fd-cfd3-4b25-92e5-772468092bdc][theme-studio-package-faces-spec-doing.org]]
 
 * Review and iteration history
 ** 2026-06-14 Sunday @ 14:37:00 -0500 -- Craig -- author