Re-voice SPEC.md files to the user-story axis of the current sdd.md

[brillout]

The #1609 migration made the tree structurally compliant with upstream sdd.md but kept the corpus's system-mechanics narration. Upstream's current revision is explicit about the axis this PR fixes: "explain everything from the perspective of user stories", for a technical product manager reader — proficient in engineering, but who has never read this codebase. All 221 specs with content sections were re-voiced (one-liners are exempt by the template): 193 files changed, +986/−407, in 16 commits.

What the pass changes:

• Flows open from the user's side. Bullets that narrated internals ("Removing a checkout commits whatever it is still holding…") now lead with the user action or user-visible effect ("When the user removes a checkout (or the sweep reclaims one), the work is made recoverable first: …") before the mechanism.
• User Stories wherever behavior is user-visible — plain "The user …" sentences, each traceable to FEATURES-SPEC.md or the file's own code; ~60 specs gained or re-voiced a User Stories section. Pure plumbing keeps bird's-view framing and names the surfaced effect; no stories were invented.
• Self-containedness. Coined terms a spec doesn't own are replaced with plain words or glossed inline at first use ("the data branch (tf-data, the shared branch where agent records are archived)"); owned vocabulary lives in that spec's Glossary — the flagship spec's glossary grows agent, composer, routine, handoff, and quota week.
• Observable first. Mechanics with no stated consequence lead with what the reader relies on, or move to Rationales when they carry a constraint.
• De-densified. Two-read sentences split, one idea per sentence; "you" re-voiced to "the user"; the technical register stays (the new persona allows it) — only this-codebase knowledge is out.
• Direct mapping preserved. Rewording never changes a claim; every sharpened sentence was verified against the sibling source first, and contradictions were preserved and reported rather than silently fixed.

Calibration: SPEC.md (root), src/worktrees.SPEC.md, and src/driver/cloud.SPEC.md were re-voiced by hand first and served as exemplars for the fifteen batch agents.

Verification: the structural spec linter is green over all 557 SPEC.md files (allowed sections, template order, one-sentence preamble, byte-exact footer); the branch touches no code files.

The grounding surfaced ~30 spec-vs-code findings — including one likely code bug (the keyed-watcher warm-up flood) and twelve stale claims in the flagship spec alone (mostly #1582 data-branch drift) — all preserved verbatim in this PR and listed in the follow-up comment below, ready for a fix round like #1611 once this lands.

🤖 Generated with Claude Code

https://claude.ai/code/session_011XvEviGLEJZsp1h6iWzgma

[brillout]

Spec-vs-code findings from the style pass's grounding. Per the pass's rules every claim below is preserved in this PR (re-voiced in form, never silently corrected) — each needs a call: fix the spec, fix the code, or ticket it. Grouped by kind:

Likely code bug:

• src/dashboard/keyed-watcher.ts — the spec promises "whatever already existed when the daemon started is never announced", but a failed first poll is caught into [], SeenTracker.observe([]) still flips warmedUp, and the next successful poll announces every pre-existing item as new (lines 25–30, 68–70). Discord/needs-you watchers can flood on a slow boot.

Flagship spec (packages/the-framework/SPEC.md) — twelve stale claims, mostly #1582 data-branch drift:

1. "Running the CLI in any registered repo finds it" — no daemon discovery exists (dropped by the TL;DR rebuild, reported here).
2. "repo-root queue file" — the queue lives on the tf-data branch, not the repo root.
3. "the daemon promotes that one file back into the project checkout" — retired entries go via serialized data-branch writes; nothing is promoted.
4. "the agent drains its queue file … check it off" — the check-off is the framework's, not the agent's.
5. "An entry stays claimed while its agent is live or its PR is open" — durable claims are ticket .lock.md files; ticketless entries have only an in-memory pin with a documented double-assign window.
6. The refill rotation omits its first job (updateTickets — in FEATURES-SPEC.md too).
7. "worktrees whose branch merged are removed" — the criterion is work-on-remote, not merge.
8. "commits those archives after an idle window … skipping while someone holds the index" — archives copy to the data branch at close; no idle window exists.
9. "seeds the project log" — install.ts seeds no log (cli.SPEC.md and src/SPEC.md assert one too).
10. The spending slider feeds only the unattended start gate; no user-work quota gate exists to "loosen", nothing "parks" on quota, and the default line is boundary + cushion.
11. "guards against a busy project" — only a duplicate of the same checkout is refused; worktree agents run concurrently, uncapped.
12. "A per-repo config file records which preset and switches" — config.ts parses only handoff/vanilla/transparent; no preset key.

Quota/budget drift (the E1 removal):

• src/agent.SPEC.md — "budget and quota stops hold even when nothing runs after the opening turn" vs code: "Nothing stops a session for spending — that is decided before it starts".
• src/agent-telemetry.SPEC.md — claims a quota-pause ending class and unreadable-quota carry-on; no quota logic remains in the file.
• src/agent.test.SPEC.md — claims coverage of "budget and quota stops with resume notes"; zero such tests.

Stale UI claims:

• AgentActionBar.SPEC.md — enumerates five exclusive states; agentStatusPill also emits "publishing…".
• DiscordDialogs.SPEC.md — claims two dialogs; exactly one exists (the webhook) — the component's header comment is stale the same way.
• NotificationsMenu.SPEC.md — places the bell in the shell header; it renders only in the sidebar's utility footer — component comment stale too.
• components/SPEC.md — the right rail's "project history" tab was removed in Simplification review, all 35 approved proposals, and the work queue drained #1536; only files/views/browser/docs remain.
• dashboard/lib/agent-option-rows.SPEC.md — "Transparent … disables every option below it": the publish-ladder rows stay enabled and the handoff rung is still sent.
• StartAgentForm.SPEC.md — claims disabled repo auto-merge "makes an armed merge land immediately"; the CI watch merges on green locally instead.

Daemon/RPC mismatches:

• dashboard-rpc/control.SPEC.md — claims delete "saves the work as a commit" (delete discards; only remove commits first) and that the publish lock covers merge (the merge path takes no lock and commits nothing).
• src/discord-credentials-store.SPEC.md — "the two Discord credentials": exactly one exists (webhook); the code's own header comment repeats the stale "two".
• src/preflight.SPEC.md — "run once, by the dashboard" corrected in-place to the pre-spawn framing (dashboard warning and daemon per-start guard both run it).
• dashboard-rpc/preferences.SPEC.md — "presets are committed into the repo" re-voiced to "saved into the repo" (no git commit happens) — veto if "committed" was intended as a promise.

Coverage gaps:

• prompts/SPEC.md — lists 4 presets; prompts/presets/ holds 6 more (all in FEATURES-SPEC.md), and data_branch_protocol.md has no flow at all.
• FEATURES-SPEC.md — post-merge follow-ups say "maintainability / security / readability"; the prompt queues only the first two.

Minor wording:

• src/SPEC.md line 1 "a reviewed pull request" vs its own "Nothing reviews the work" — true both ways (the human reviews, the pipeline doesn't); one word ("for human review") would disambiguate.
• src/e2e/harness.SPEC.md — isolation is per story-file process, not per world.
• src/auto-pm.SPEC.md — calls the queue's data-branch move "planned"; it happened (Save data in special branch the-framework_data #1582).

Happy to run the fix round once this PR lands, same shape as #1611.

---

Generated by Claude Code

[brillout]

I love the user stories, it's a really nice context anchoring.

[brillout]

@suleimansh Let me know if you want further improvements (e.g. I can let Claude make another pass of improvements). One thing that didn't work is mermaid, it didn't create any, not sure why, I think it's okay.