Migrate all SPEC.md files to the new upstream sdd.md template

[brillout]

Upstream sdd.md redefined the SPEC.md template (commit f54547c): ## TLDR is no longer a legal section, flows live under ## Flows with an optional ## Flows — TL;DR summary, why/history clauses belong in ## Rationales, and ## User Stories / ## Glossary are new optional sections. This PR migrates the whole tree — all 558 SPEC.md files checked, 231 changed (+967/−451) — and applies the new writing style (product-manager reader, zero ambiguity, self-contained sentences, no history framing in flows). Only *.SPEC.md files are touched.

What the migration does:

• ## TLDR is gone everywhere (212 files): where the bullets described behavior they became ## Flows (byte-identical where already compliant); where a real flows section existed they were merged; history/why clauses were extracted into ## Rationales, reworded in present tense.
• ## User Stories added only where a file's flows directly realize something a user does, each story traceable to FEATURES-SPEC.md: root, packages/the-framework, src, cli, auto-pm, tickets, todo-loop, the dashboard root and components directory, the daemon's dashboard directory, the chrome extension, the website, and the Actions agent workflow. Leaf plumbing and single UI components get none.
• ## Flows — TL;DR only where a Flows section is long enough to earn a summary: packages/the-framework, dashboard, src/dashboard.
• ## Glossary where a spec owns coined vocabulary: packages/the-framework/SPEC.md (driver, location, attended/unattended, gate, ticket, queue entry, empty agent, preset) and driver/SPEC.md (driver).
• Root SPEC.md restructured per the new Hierarchy rules: product story, how the top-level subsystems relate, product-level user stories.
• Canonical footer everywhere — two .github specs carried a stale ## Before writing SPEC.md files variant.
• A few grounded one-word corrections where the spec was unambiguously wrong against the code (e.g. the Claude Code usage question is answered by the agent, not the driver; each driver, not each agent, declares its CLI surface).
• No mermaid diagrams added or removed.
• Merged main after Cloud runs' work is adopted onto the run's record (fix #1601) #1603/The dashboard shows what the daemon finds wrong with a project; first emitter: the data-branch sync (fix #1599, towards #1500) #1604 landed: their four dual-edited specs (worktrees, driver/cloud, cloud-scratch-refs, dashboard App) were resolved by taking main's content in the migrated structure, and the nine spec files they added in the old format (cloud-work, project-errors, archived-agent-patch, agent-telemetry, ProjectErrorBanner and test specs) were migrated the same way.

Verification: a compliance linter ran over all 558 files — allowed sections only, template order, one-sentence preamble, byte-exact footer, ## Flows — TL;DR only above a ## Flows, no ## TLDR remaining. Every substantive rewrite was grounded against the sibling source file by the migrating agent.

Spec-vs-code contradictions discovered during grounding were preserved verbatim, not silently "fixed" — see the follow-up comment below for the full list (13 findings, including one live website copy bug: "keeps humans under control").

🤖 Generated with Claude Code

https://claude.ai/code/session_011XvEviGLEJZsp1h6iWzgma

[brillout]

Spec-vs-code contradictions found while grounding the migration. Per the migration rules these were preserved verbatim (migrated in form, not silently rewritten to match the code) — each needs a human call: fix the spec, fix the code, or ticket it.

Website copy bug (the one that matters most):

• the-framework.ai/pages/index/Queues.tsx — the spec calls the Human Queue "the cockpit that keeps humans in control", but the rendered site copy literally says "it keeps humans under control". Meaning flipped on the live marketing page.

Specs describing code paths that no longer exist:

• src/dashboard-rpc/projects.SPEC.md — the public-host onboarding case ("neither offers nor accepts, must not disclose where it runs") has no live code path; only the nullable OnboardingSuggestion type and comments remain.
• src/dashboard-rpc/events.SPEC.md — "the relay's own agents streaming from memory": only device-relayed agents are answered; no public-relay host mounts this surface.
• src/dashboard/dashboard.SPEC.md — line 1 claims the rollup covers "what recently happened", but the payload carries no recent-activity data (the activity window was cut; the shape-guard test pins its absence).
• src/dashboard/dashboard.test.SPEC.md — claims tests cover "the fixed two-week activity window"; the tests assert those fields are absent.
• src/dashboard/agent-handoff.test.SPEC.md — describes the old candidate-branch-names PR resolution; the tests now cover reading the PR the run recorded.
• src/handoff-level.SPEC.md — claims a stored setting spelling the three stages out is read through the checkbox conversion; the sanitizer reads only handoff and drops legacy boolean keys.
• src/project.SPEC.md — claims detection signals come from package-manifest dependency names; project.ts has no such path (stale docblock, unused import).

Specs overstating or misplacing behavior:

• src/dashboard-rpc/SPEC.md — the writes bullet claims every listed write (push, open PR, start agent, queue ticket) is a control-file append; only stop/choice/message/handoff/merge-on-live-agent are — push/PR go via git/GitHub, start via the daemon, queue-ticket writes the backlog file.
• src/dashboard-rpc/control.SPEC.md — lists "previews" among actions calling straight into the daemon's wiring; control.ts has no preview call.
• src/dashboard/projects.SPEC.md — "Last activity is the newest of the project's log entries and its agents"; summarizeProject derives it from agents/sessions alone.
• dashboard/lib/preferences.SPEC.md — claims theme and notification defaults are framework-side; the theme default lives in the dashboard module.
• dashboard/components/SettingsPage.SPEC.md — "Every list here is static today"; the Editor dropdown is assembled at run time from detected editors.

---

Generated by Claude Code

[suleimansh]

The new structure is much better to read, especially pulling the why out into Rationales. Nice work. 😍

[suleimansh]

🤖 agent comment

Reviewed the migration. Structure is clean, and the rewrites are more accurate than what they replaced. Two small findings, neither blocking.

Structure, checked across all 559 spec files: no ## TLDR left, no illegal sections, no ordering violations, the footer byte-exact everywhere, and ## Flows — TL;DR only above a ## Flows (3 files). The one file that fails the check is FEATURES-SPEC.md, which isn't an sdd spec.

Rewrites spot-checked against the code — both got more precise, not looser:

• worktrees.SPEC.md: "a record that was never written takes the recoverable default" → "takes the ordinary commit-push-remove path", which is what readMetaFor actually does (worktrees.ts:222-235).
• driver/cloud.SPEC.md added a flow the old spec never covered: an anchor that can't be pushed proceeds with no ref and names --teleport. That's cloud.ts:268-278 line for line.

1. A deleted feature got promoted into user stories

The watch relay was removed in #1536 (f395f0c1) and nothing serves it now. The old specs still described it, and preserving those lines verbatim was the right call — but the User Stories were derived from them, so a buried stale bullet became a headline promise:

• dashboard/SPEC.md — "The user shares a watch link that shows one agent read-only", and the same claim again in Flows — TL;DR
• dashboard/components/SPEC.md — "A teammate opens a shared link and watches one agent's live feed read-only"

One stale claim is now four. It also misses this PR's own rule that each user story is traceable to FEATURES-SPEC.md — there is no watch-link row there. Nor is there such an item in the code: AgentActionsMenu.tsx offers Copy resume command / Copy session id only, though dashboard/SPEC.md still says the menu can "copy a shareable watch link".

The general risk is worth naming: any stale flow that earned a user story was amplified the same way. The 13-finding list caught this feature once (events.SPEC.md) but not its four other spec homes — so that list is a floor, not a ceiling, and the follow-up should chase features rather than files.

2. Two specs promise different things about cloud sessions

Root SPEC.md says the user "steers" cloud agents from the dashboard. But driver/cloud.SPEC.md says a cloud session offers no way to read status, replies, or output back — and packages/the-framework/SPEC.md says the accurate thing, "answers their questions from the local dashboard". Steering and answering a parked question aren't the same promise.

Both are one-line fixes. Finding 1 is swept up anyway by the relay-orphan cleanup queued behind this PR: RelayView.tsx, the dead ?run= branch in App.tsx, and the shared-link sentence at packages/the-framework/SPEC.md:49.

[brillout]

Both findings verified and addressed in b560f9d.

1 — watch-relay amplification: confirmed against the code (no watch-link row in FEATURES-SPEC.md; AgentActionsMenu.tsx offers only Copy resume command / Copy session id). The three lines the migration added are gone — both user stories and the Flows — TL;DR echo. The pre-existing stale flow sentences (dashboard/SPEC.md watch-mode bullet and actions-menu phrase, components/SPEC.md page list, App.SPEC.md, packages/the-framework/SPEC.md:49) stay preserved-verbatim per this PR's policy, for the queued relay-orphan cleanup to sweep together with RelayView.tsx and the dead ?run= branch.

2 — root spec's "steers": reworded to what the code delivers — "follows them from the same dashboard, and answers the questions they park on" — matching packages/the-framework/SPEC.md and driver/cloud.SPEC.md.

On the general risk: agreed, and worth restating crisply — the 13-finding list is per-file, so a feature with several spec homes can be stale in more places than the list names. The follow-up cleanup should walk features (starting from the removed watch relay), not files.

---

Generated by Claude Code