docs: revise and ratify the no-approvals speedrun specHEADmain

Recast the speedrun eligibility criteria as checkable gates, not adjectives: dropped the task-size gate so large tasks decompose into per-commit chunks, replaced the act-vs-file rule with a four-item defer checklist keyed on whether the failing test is writable from the task text, and added a pre-flight step that front-loads a run's decisions so it proceeds unattended after. Define :solo: and :quick: precisely enough to enforce in task-review and task-audit.

Also record the spec storage and lifecycle-status decision (org-keyword authoritative, drop the filename suffix) and the requirement to retrofit existing docs across projects.

1 files changed, 12 insertions, 11 deletions

diff --git a/todo.org b/todo.org
index 0dca59d..3361dab 100644
--- a/todo.org
+++ b/todo.org
@@ -381,22 +381,23 @@ 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.
+We handle the task in priority order. Mechanism decided 2026-06-28; migrates into the spec when built.
 
-*** 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.
+*** Decisions (settled 2026-06-28 — migrate into the spec when built)
+1. *Location split — adopt.* =docs/specs/= for formal specs, =docs/design/= for notes (brainstorms, inventories, reviews). A spec is a doc proposing a buildable change with a Decisions section and phases; everything else is a note. Document in spec-create and the docs-lifecycle rule.
+2. *Status mechanism — org-keyword authoritative.* The spec's =#+TODO:= state on its top heading is authoritative (specs already carry =#+TODO: TODO | DONE SUPERSEDED CANCELLED=), mirrored in a =Status= field in the Metadata table. Drop the filename suffix entirely — it's redundant with the Status field and adds rename churn across a cross-linked, template-synced doc set. (Craig 2026-06-28, choosing org-keyword over his earlier filename-suffix lean.)
+3. *Link safety — adopt =org-id= ([[id:...]]) for cross-doc spec links.* Decouples link stability from the status mechanism; good hygiene regardless.
+4. *Generalize.* Capture the shape (lifecycle state authoritative-in-artifact, formal-vs-notes split, rename-safe links) as a general =docs-lifecycle= convention in =claude-rules/=, with spec-create as the first instance.
+5. *Retrofit existing files across ALL projects* (Craig 2026-06-28). The convention is worthless if legacy docs stay misfiled — every project's existing =docs/design/= pile (the ~28 in .emacs.d that surfaced this) must be sorted: formal specs move to =docs/specs/=, notes stay in =docs/design/=, inbound =file:= links updated. This is a one-time per-project migration that template sync can't perform, so the spec must design the reach mechanism. Proposed shape: a synced classify-and-move helper under =.ai/scripts/= (heuristic: a doc with a Decisions section + phases/Metadata is a spec) that proposes moves for confirmation and relinks, plus a startup nudge gated on a per-project =:LAST_SPEC_SORT:= marker so each project runs it once. Classification is a judgment call — the helper proposes, a human confirms.
 
-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.
+Follow-up once built: update spec-create to emit into =docs/specs/= with the org-keyword status; write the =docs-lifecycle= rule; ship the retrofit helper + startup nudge; retrofit rulesets' own =docs/design/= first as the pilot; send a note if .emacs.d should pilot before generalizing.
 
-** DOING [#C] "fix speedrun" cross-project autonomous-batch mode :feature:spec:
+** DOING [#C] No-approvals speedrun — cross-project autonomous-batch mode :feature:spec:
 :PROPERTIES:
 :CREATED: [2026-06-15 Mon]
 :LAST_REVIEWED: 2026-06-24
 :END:
-A named mode for coding projects: Craig names an ordered task set and says "fix speedrun"; the set is worked autonomously, each task held to the full quality bar (TDD red→green, =/review-code=, =/voice= on the commit) and committed + pushed as its own logical commit, with a VERIFY filed instead of guessing on anything underspecified, and an end-of-set page listing completed + remaining tasks. Surfaced by .emacs.d from a 2026-06-15 theme-studio session where the shape worked. Source proposal: [[file:docs/design/2026-06-15-fix-speedrun-workflow-proposal.org]] (.emacs.d handoff 2026-06-15). Build via =spec-create= when worked; we handle the task in priority order.
+A named mode for coding projects: Craig names an ordered task set and says "speedrun" / "no approvals speedrun"; the set is worked autonomously, each task held to the full quality bar (TDD red→green, =/review-code=, =/voice= on the commit) and committed + pushed as its own logical commit, with all needed quick decisions gathered in one pre-flight Q&A (answer or "skip this") and a VERIFY filed for anything underspecified or needing deliberation, plus an end-of-set page listing completed + remaining + skipped tasks. Task size is not a gate — large tasks decompose into per-commit chunks. Surfaced by .emacs.d from a 2026-06-15 theme-studio session where the shape worked. Source proposal: [[file:docs/design/2026-06-15-fix-speedrun-workflow-proposal.org]] (.emacs.d handoff 2026-06-15). Build via =spec-create= when worked; we handle the task in priority order.
 
 Skeptical-review read (open design questions to resolve in the spec, not settled here):
 - *Is it a new workflow or a documented preset?* The proposal frames it as no-approvals + always-push session modes plus an end page. Decide whether it needs its own workflow file or is mostly documentation of a preset over the two existing modes.
@@ -410,8 +411,8 @@ Craig's "your call" (2026-06-16) answered in [[file:docs/design/2026-06-16-auton
 - *Paging:* end-of-set only, via =notify ... --persist= (reconciled past the removed page-signal wrapper).
 - *Auto-pull vs explicit list:* both — explicit list for the preset, tag/priority query for the loop.
 - *Effectiveness measurement (the trial Craig asked for):* the spec designs a per-task JSONL metrics log (=.ai/metrics/work-the-backlog.jsonl=), a corrections-in-next-session signal, and a periodic synthesis step that writes =:agent:metrics:= org-roam articles for later review — the "gather data + create org-roam articles" loop.
-*** VERIFY Review the autonomous-batch execution spec
-Review [[file:docs/design/2026-06-16-autonomous-batch-execution-spec.org]] (covers both this and Phase E) and ratify (or adjust) its six open decisions. Implementation-ready once no decision is still TODO.
+*** 2026-06-29 Mon @ 03:48:09 -0400 Ratified the autonomous-batch execution spec
+Craig ratified all eight decisions in [[file:docs/design/2026-06-16-autonomous-batch-execution-spec.org]] (revised this session — size gate removed, crisp four-item defer checklist, =:solo:= / =:quick:= definitions + task-review/audit enforcement, speedrun pre-flight Q&A). Spec Status → ready; implementation-ready across Phase 0–6. Decisions grew from six to eight during the revision.
 
 ** TODO [#C] ntfy phone channel as general two-way agent-comms :feature:spec:
 :PROPERTIES: