Install SDD: next slice of per-file specs

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CSM4FVUbnP4PJJ9sawMfLb

Author: claude

packages/the-framework/dashboard/components/TicketsPanel.test.SPEC.md

@@ -0,0 +1,11 @@
+What the tests cover: tickets render as one-line rows carrying what has already been done to them, with the summary left to the detail page; the row spells out its priority ("Priority: 8" rather than a bare number), lists its topics, shows a human-readable age, shows the effort and uncertainty a plan recorded, and keeps priority, age and the GitHub link in that order; the list renders in the order it is given rather than re-sorting behind the caller's back; and opening a row identifies the ticket by its filename.
+
+The plan column links a planned ticket to its plan and starts an agent asked to create the plan file beside the ticket when there is none — attended, unlike the other actions. The start column starts an agent asked to work that one ticket and no other, unattended and with the ticket named on it. Both send exactly the wording the buttons stand for, with no second copy of the prompt hidden behind them.
+
+Row controls do not double as navigation: starting work, filtering by a topic, filtering to claimed tickets, and following the GitHub link all leave the row unopened, while clicking the title opens it. A claimed ticket names its holder inline rather than only on hover.
+
+"Update from GitHub" sends the update preset's own text — the same instruction the onboarding checklist sends under that label — unattended, and hands the user to the agent doing the update; a refused start says why and moves the user nowhere. A filled backlog offers the update beside a stamp saying when `tickets/` last caught up, admitting "No record of an import yet" when it does not know; the empty backlog offers exactly one update button and no stamp. A list emptied by filters says how many tickets are hidden and withholds the update, and a panel with no project renders nothing at all.
+
+## Before modifying/creating SPEC.md files
+
+You must always read and respect https://raw.githubusercontent.com/brillout/sdd/refs/heads/main/sdd.md

packages/the-framework/dashboard/lib/profiles.test.SPEC.md

@@ -0,0 +1,11 @@
+What the tests cover: saving devices and hopping between them.
+
+- **Saving** - devices are saved, listed newest first, and dropped again; a device given no name is labelled by its host and port; saving the same machine again refreshes its token instead of adding a second entry; and saved devices survive a page reload because they live in the browser's own storage.
+- **Reading a pasted URL** - the origin and the token are pulled out of the URL a daemon prints, including one with surrounding whitespace or an extra path; a URL with no token yields an empty token; anything that is not a URL is rejected.
+- **Hopping** - the hop URL carries the token, and carries no token when returning to the local machine; it also carries the composer draft, with or without a token, and drops an oversized draft while still connecting; hopping navigates the browser to that URL.
+- **Connected indicator** - a loopback dashboard reads as "Local", a saved machine by its label, and an unsaved one by its bare host.
+- **Returning local** - "Local" goes to the default daemon address until a loopback origin has been remembered, then to the remembered one; a non-loopback origin is never remembered.
+
+## Before modifying/creating SPEC.md files
+
+You must always read and respect https://raw.githubusercontent.com/brillout/sdd/refs/heads/main/sdd.md

packages/the-framework/dashboard/lib/queue-entry.SPEC.md

@@ -0,0 +1,15 @@
+Decides how one agent queue entry reads on screen and where clicking it goes.
+
+Entries are lines of `TODO_AGENTS.md`, so they are markdown, and a ticket queued from the dashboard is written as a link back to its ticket. An entry that starts with a link shows that link's text as its title; anything written after the link is the agent's own note, which is detail for a tooltip rather than for a one-line list that would truncate the title away to make room for it. A link further into the line is part of a sentence rather than the name of the work, so it does not count as the title. An entry with no leading link shows as its own text.
+
+The link's destination decides where the entry points: a target under `tickets/` names a ticket and opens that ticket's page, an absolute web address is kept as an outbound link, and anything else — a plain path inside the repo, say — keeps the title but points nowhere, since the dashboard has no page for it and a dead destination is worse than none.
+
+## Business logic — TL;DR
+
+- **The title is the leading link's text** - so the Overview's card reads as a title rather than as markdown source.
+- **The agent's trailing note is not the title** - it stays out of the one-line entry.
+- **Only a `tickets/` target is a ticket** - a web address is an outbound link; anything else points nowhere.
+
+## Before modifying/creating SPEC.md files
+
+You must always read and respect https://raw.githubusercontent.com/brillout/sdd/refs/heads/main/sdd.md

packages/the-framework/dashboard/lib/queue-entry.test.SPEC.md

@@ -0,0 +1,5 @@
+What the tests cover: how an agent queue entry reads and where it points. A queued ticket shows its title rather than the raw markdown, and names the ticket it links to. An agent's note written after the link is kept out of the title. An entry linking to a web address keeps that address as an outbound link. A link to anything else keeps its title but points nowhere. An entry with no leading link is shown exactly as written, and a link in the middle of a sentence does not become the title.
+
+## Before modifying/creating SPEC.md files
+
+You must always read and respect https://raw.githubusercontent.com/brillout/sdd/refs/heads/main/sdd.md

packages/the-framework/dashboard/lib/use-async.SPEC.md

@@ -0,0 +1,15 @@
+The one way every dashboard panel reads from the daemon: ask, hold the answer, and ignore it if the panel has moved on since. A panel either reads once — and again whenever what it is reading about changes — or reads repeatedly on its own cadence.
+
+## Business logic — TL;DR
+
+- **A failed read keeps the last answer** - a daemon restart or a dropped request leaves the panel showing what it last knew instead of blanking; the next attempt usually succeeds, and a failure never surfaces as a crash.
+- **A late answer is discarded** - once the panel has switched to a different project or agent, or gone away entirely, an answer still in flight for the old one is dropped rather than written over the current view. An immediate re-read obeys the same rule.
+- **Nothing to read means nothing is asked** - with no project selected there is no request at all, and the panel simply shows its empty starting state.
+- **Switching clears first** - changing what is being read empties the panel rather than briefly presenting the previous target's data as this one's. A panel may opt out where blanking is worse than staleness: the agent toolbar's header keeps the resolved branch, PR and GitHub link on screen while the next one loads, so navigating between agents updates it in place instead of blanking and popping.
+- **"Not read yet" is not "not there"** - whether a real answer has arrived is tracked separately and only a successful read sets it, so a panel can tell an agent that is genuinely gone from one whose first read is still out, and a daemon hiccup is never mistaken for an answer. It resets whenever the target changes.
+- **An action does not wait for the next tick** - a panel can force an immediate re-read after a local action, instead of leaving the user looking at a stale screen until the cadence comes round.
+- **Repeating stops when the panel does** - a panel that goes away stops asking.
+
+## Before modifying/creating SPEC.md files
+
+You must always read and respect https://raw.githubusercontent.com/brillout/sdd/refs/heads/main/sdd.md

packages/the-framework/dashboard/lib/use-async.test.SPEC.md

@@ -0,0 +1,7 @@
+What the tests cover: a panel shows its empty starting state until the daemon's answer arrives; with nothing to read yet, nothing is asked at all; changing what is being read clears the panel first rather than presenting the previous target's data as this one's, and an answer for the previous target that lands late is dropped; a failed read keeps the last answer instead of blanking it, and never surfaces as a crash.
+
+For panels that read repeatedly: the answer refreshes on the panel's own cadence; refreshing stops once the panel goes away, and an answer still in flight then is never applied; a failed read is survived and the next attempt recovers; and an explicit re-read lands immediately rather than waiting for the next tick.
+
+## Before modifying/creating SPEC.md files
+
+You must always read and respect https://raw.githubusercontent.com/brillout/sdd/refs/heads/main/sdd.md

packages/the-framework/prompts/protocols/SPEC.md

@@ -0,0 +1,58 @@
+The protocols appended to every agent's system channel: how an agent signals to The Framework. They pin the exact shape of an awaited choice, of the session name and the ready-for-merge signal, and they tell an agent what this particular agent can do — whether it has a browser, and whether it can stop to ask at all.
+
+## User story
+
+- The user drives coding agents through The Framework's dashboard: answering their questions, watching them name their work, and merging it when they say it is done. All of that only works if an agent's message can be recognized as a question, a name, or a finished-signal.
+- The user turns on a browser for an agent, or hands a task to a place nothing local can steer. The agent has to be told which of those it is in.
+
+## Glossary
+
+- **system channel** - the standing instructions an agent is given for its whole run, as opposed to the prompt it is asked to work on. The protocols are appended to it.
+
+## Business logic — TL;DR
+
+- **The protocols are the emit contract, not prompt content** - they are appended even when the user has dropped The Framework's built-in system prompt, because without them the agent cannot signal anything.
+- **Awaiting** - one block shape for every question an agent stops to ask, including handing a stuck browser to a human, plus a non-blocking way to show a document.
+- **Signalling** - the non-blocking blocks: the session name, ready for merge, the pull request to open, and an error only the user can fix.
+- **Browser** - added only when this agent has a real browser, telling it so and when to prefer the browser over plain page fetching.
+- **Hands-off** - added only when this agent runs somewhere nothing local can steer, replacing the gates with "decide alone" and requiring everything to land as a pull request.
+- **Order is fixed** - the browser section comes first, then awaiting, then hands-off amending it, and signalling stays last.
+
+## Business logic
+
+### The protocols are the emit contract, not prompt content
+
+#### User story
+
+The user can turn The Framework's built-in system prompt off and still expect the dashboard to show what their agents are doing.
+
+#### Business logic
+
+The protocols describe *how* to signal, never *when* — deciding when to stop and ask, or when work is finished, belongs to the system prompt. Because they are the contract rather than the content, they are appended even when the built-in system prompt has been dropped. The single exception is a fully transparent agent, where there is no framework behavior left to signal to and the whole system channel is empty.
+
+### What each protocol covers
+
+#### User story
+
+See `## User story`.
+
+#### Business logic
+
+- **Awaiting** — how an agent parks at a gate: one block ending the turn, in one shape for an approval, a multi-select, a plan sign-off or handing a stuck browser to a human, carrying which option is safe to take when nobody answers and which option ends the agent instead of resuming it. It also covers pushing a document to the dashboard without stopping.
+- **Signalling** — the blocks an agent emits mid-turn without stopping: the session name it chose, the ready-for-merge declaration, the title and description of the pull request The Framework then opens for it, and errors only the user can fix.
+- **Browser** — added only to an agent that has a real browser: that it has one, that the browser is for what it must see or act on while plain fetching remains better for reading, and that it should stay within one page so the user can watch.
+- **Hands-off** — added only to an agent handed somewhere nothing local can steer: the gates just taught are unavailable, so it takes the most plausible reading and says which assumption it made, and it must land its work as a pull request because the conversation reaches nobody.
+
+### Order is fixed
+
+#### User story
+
+The dashboard shows the user the exact system channel an agent will receive, and two protocols only make sense in relation to another.
+
+#### Business logic
+
+The browser section goes ahead of the rest; the await protocol follows; the hands-off protocol comes immediately after it, because it amends what that protocol just taught — the gates are described and then declared unavailable, which keeps the shape intact for The Framework's parser while telling the agent not to reach for it. The signal protocol is always last in the channel.
+
+## Before modifying/creating SPEC.md files
+
+You must always read and respect https://raw.githubusercontent.com/brillout/sdd/refs/heads/main/sdd.md