runcastle 1.4.8 → 1.5.4

package/skills/packs/runcastle/skills/{ideate → feature}/references/preview-starter.html

@@ -16,9 +16,6 @@
   --color-primary:#eceef4;--color-on-primary:#0a0c11;
   --color-accent:#4f8ef7;--color-accent-text:#7aaafa;--color-accent-subtle:#16213a;
   --color-success:#46b67a;--color-warning:#e2a53b;--color-danger:#f06363;--color-danger-subtle:#2a1515;
-  --color-phase-ideation:#ec7cb5;--color-phase-spec:#35c2b8;--color-phase-implementation:#f08a4b;
-  --color-phase-planning:var(--color-phase-spec);--color-phase-building:var(--color-phase-implementation);
-  --color-phase-review:var(--color-accent);--color-phase-shipped:var(--color-success);
   --color-scrim:rgb(0 0 0 / 0.6);
   --font-sans:"Geist Variable","Segoe UI Variable",system-ui,-apple-system,sans-serif;
   --font-mono:"Geist Mono Variable","Cascadia Code",ui-monospace,Consolas,monospace;
@@ -28,11 +25,10 @@
   color-scheme:light;
   --color-canvas:#f4f6f9;--color-surface:#ffffff;--color-surface-raised:#ffffff;--color-surface-hover:#eef1f6;--color-surface-selected:#e4e8f1;--color-surface-inset:#f4f6f9;
   --color-border:#dfe3ec;--color-border-subtle:rgb(22 30 50 / 0.07);--color-border-strong:#cdd2de;
-  --color-text:#161a24;--color-text-secondary:#4c5366;--color-text-tertiary:#5c6377;--color-text-disabled:#a4aab9;--color-icon:#6a7185;
+  --color-text:#161a24;--color-text-secondary:#596075;--color-text-tertiary:#676e82;--color-text-disabled:#a4aab9;--color-icon:#7a8195;
   --color-primary:#161a24;--color-on-primary:#ffffff;
-  --color-accent:#2f6fe4;--color-accent-text:#2463d6;--color-accent-subtle:#ecf2fe;
-  --color-success:#1e8e53;--color-warning:#a86a06;--color-danger:#c42828;--color-danger-subtle:#fdeeee;
-  --color-phase-ideation:#c13d7e;--color-phase-spec:#0b7f78;--color-phase-implementation:#b44f0c;
+  --color-accent:#3a7ef0;--color-accent-text:#2361d4;--color-accent-subtle:#ecf2fe;
+  --color-success:#23955a;--color-warning:#c06e00;--color-danger:#df5050;--color-danger-subtle:#fdeeee;
   --color-scrim:rgb(22 26 36 / 0.28);
 }
 @media (prefers-color-scheme:light){
@@ -40,11 +36,10 @@
     color-scheme:light;
     --color-canvas:#f4f6f9;--color-surface:#ffffff;--color-surface-raised:#ffffff;--color-surface-hover:#eef1f6;--color-surface-selected:#e4e8f1;--color-surface-inset:#f4f6f9;
     --color-border:#dfe3ec;--color-border-subtle:rgb(22 30 50 / 0.07);--color-border-strong:#cdd2de;
-    --color-text:#161a24;--color-text-secondary:#4c5366;--color-text-tertiary:#5c6377;--color-text-disabled:#a4aab9;--color-icon:#6a7185;
+    --color-text:#161a24;--color-text-secondary:#596075;--color-text-tertiary:#676e82;--color-text-disabled:#a4aab9;--color-icon:#7a8195;
     --color-primary:#161a24;--color-on-primary:#ffffff;
-    --color-accent:#2f6fe4;--color-accent-text:#2463d6;--color-accent-subtle:#ecf2fe;
-    --color-success:#1e8e53;--color-warning:#a86a06;--color-danger:#c42828;--color-danger-subtle:#fdeeee;
-    --color-phase-ideation:#c13d7e;--color-phase-spec:#0b7f78;--color-phase-implementation:#b44f0c;
+    --color-accent:#3a7ef0;--color-accent-text:#2361d4;--color-accent-subtle:#ecf2fe;
+    --color-success:#23955a;--color-warning:#c06e00;--color-danger:#df5050;--color-danger-subtle:#fdeeee;
     --color-scrim:rgb(22 26 36 / 0.28);
   }
 }
@@ -89,6 +84,12 @@ button{font:inherit;color:inherit;background:none;border:0;padding:0;cursor:poin
 /* the framed panel a mocked screen sits in; inside it, use the project's own styling */
 .screen{border:1px solid var(--color-border);border-radius:var(--radius-lg);overflow:hidden;background:var(--color-surface);position:relative}
 
+/* a screen designed in design mode: a name, one line, and a button that opens it in the app's design panel */
+.designed{display:grid;gap:6px;justify-items:start;padding:12px 14px;border:1px solid var(--color-border);border-left:2px solid var(--color-accent);border-radius:var(--radius-md);background:var(--color-surface-raised)}
+.designed p{color:var(--color-text-secondary)}
+.designed button[data-open-design]{height:28px;padding:0 12px;border-radius:var(--radius-md);background:var(--color-accent-subtle);color:var(--color-accent-text);font-weight:500}
+.designed button[data-open-design]:hover{background:var(--color-accent);color:#fff}
+
 /* decided / left out / under the hood */
 .dlist{border-top:1px solid var(--color-border-subtle);margin-top:12px}
 .dlist details{border-bottom:1px solid var(--color-border-subtle)}
@@ -135,7 +136,7 @@ button{font:inherit;color:inherit;background:none;border:0;padding:0;cursor:poin
 <header id="what">
   <h1>[Feature title]</h1>
   <p class="lede">[One or two sentences: what this feature is, in the human's words.]</p>
-  <div class="meta"><span>Lap 1</span><span><span data-dcount></span> decisions</span><span class="mono">docs/features/[slug]/preview.html</span></div>
+  <div class="meta"><span><span data-dcount></span> decisions</span><span class="mono">docs/features/[slug]/preview.html</span></div>
   <nav class="jump" aria-label="Parts of this preview">
     <a href="#show">The show</a><a href="#decided">Decided <b data-dcount></b></a><a href="#left-out">Left out</a><a href="#hood">Under the hood</a>
   </nav>
@@ -152,7 +153,10 @@ button{font:inherit;color:inherit;background:none;border:0;padding:0;cursor:poin
        inside a .screen panel, wrapped in a screen block.
 
        Example screen block (copy it, rename it in kebab case, uncomment the
-       panel; delete it if the show has no screen):
+       panel; delete it if the show has no screen). A screen designed in design
+       mode gets a designed-screen entry instead of a mock; see preview.md:
+       <div class="designed"><h3>Name</h3><p>What is real, what is sample.</p>
+       <button data-open-design="/preview/path">Open in design</button></div>
   -->
 <!-- screen:example-name -->
 <!--
@@ -174,8 +178,8 @@ button{font:inherit;color:inherit;background:none;border:0;padding:0;cursor:poin
 <section id="left-out">
   <h2>What is left out</h2>
   <div class="out2">
-    <div><h3>Later laps</h3><ul>
-      <li><i class="dot"></i>[Deferred to a later lap]</li>
+    <div><h3>Later</h3><ul>
+      <li><i class="dot"></i>[Deferred to a backlog feature]</li>
     </ul></div>
     <div><h3>Not this feature</h3><ul>
       <li><i class="dot"></i>[Out of scope]</li>
@@ -250,13 +254,19 @@ button{font:inherit;color:inherit;background:none;border:0;padding:0;cursor:poin
 
   // a pin opens its decision; in-page links scroll by script, because hash
   // navigation is unreliable inside the app's sandboxed frame
-  function go(el) { el.scrollIntoView({ behavior: 'smooth', block: 'center' }) }
+  function reveal(el) { el.scrollIntoView({ behavior: 'smooth', block: 'center' }) }
   document.addEventListener('click', function (e) {
+    // Open in design: the app listens for exactly this message and opens the design panel
+    var od = e.target.closest('[data-open-design]')
+    if (od) {
+      parent.postMessage({ type: 'runcastle:open-design', path: od.dataset.openDesign }, '*')
+      return
+    }
     var pin = e.target.closest('a.pin[data-d]')
     if (pin) {
       e.preventDefault()
       var d = $('#d' + pin.dataset.d)
-      d.open = true; go(d); d.classList.add('flash')
+      d.open = true; reveal(d); d.classList.add('flash')
       setTimeout(function () { d.classList.remove('flash') }, 1400)
       return
     }

package/skills/packs/runcastle/skills/{ideate → feature}/references/preview.md

@@ -1,12 +1,36 @@
 # The plan preview — the page the human looks at
 
-Load this when the decisions are locked and the preview step (§3 of the ideate
-skill) arrives, or when a decision edit at planning means the preview has to be
-redrawn. Otherwise it costs this conversation nothing.
+Load this when the decisions are settled and you are about to show the human
+the plan, or when a decision edit means the preview has to be redrawn.
+Otherwise it costs this conversation nothing.
 
 The preview is the one page the human reads the feature by. They confirm the
 plan by looking at it, and when tired it is the only thing they read before
-Burn. Draw it for that reader.
+they say yes to the first round. Draw it for that reader.
+
+## Show it, then get the yes
+
+1. **Draw it** from `./preview-starter.html`, following the rules below.
+2. **Check it against `decisions.md`** (the self-check at the end). Fix the
+   preview before anyone sees it.
+3. **Show it**: `show_panel({ view: 'plan' })` opens it beside the chat. Tell
+   the human what you propose — tickets and rounds, or work you will do
+   yourself — and ask for their explicit yes. Then wait for the answer.
+4. **A correction is a decision edit plus a redraw.** Edit the decision in
+   `decisions.md` and redraw the preview in the same move, then ask them to
+   look again.
+
+With no human present, steps 1 and 2 are the whole of this; `./planning-alone.md`
+says how that run asks for the yes.
+
+**Never skip the preview on your own judgement** — not because the feature is
+small, not because the grill went quickly. A small feature gets a small
+preview. **If the human says to skip it**, write no file. The yes is still
+needed.
+
+**The redraw rule.** Any later edit to `decisions.md` updates `preview.html` in
+the same move, before anything else, while the plan is still being agreed or
+built.
 
 ## The file
 
@@ -30,13 +54,14 @@ Burn. Draw it for that reader.
    title, with the reason available on demand (the starter's `D` list builds
    this). Where a decision is visible in the show, pin its number on that spot:
    `<a class="pin" data-d="3">3</a>`.
-   **A self-planned feature** (§1a of the ideate skill) opens this part with a
+   **A self-planned feature** (`./planning-alone.md`) opens this part with a
    **Check first** group of at most five decisions, the ones the planner picked.
    Each entry shows the decision's number and title, its alternative, and why it
    is uncertain (the starter's `C` list builds this). The remaining decisions
    follow in the list, each showing that it was assumed (a third element on its
    `D` entry). **A grilled feature has neither**: no group and no assumed marks.
-4. **What is left out.** Out of scope, and anything deferred to a later lap.
+4. **What is left out.** Out of scope, and under **Later** anything deferred
+   to a backlog feature.
 5. **Under the hood.** The technical shape for a reader who wants it,
    **collapsed by default**, drawn where it can be.
 
@@ -65,10 +90,41 @@ Each screen in the show is a **screen block**: the lines between two markers,
 ```
 
 with `<name>` in kebab case and unique in the file. A ticket that builds that
-screen names the block, and its burn agent reads only those lines — so put
+screen names the block, and its worker reads only those lines — so put
 everything the screen needs to be understood between the markers, and nothing
 else. Delete the starter's `example-name` block if the show has no screen.
 
+## Designed screens
+
+A screen designed in design mode (`./design.md`) is **not mocked
+again**. Its place in the show is a **designed-screen entry**:
+
+- its name;
+- one line saying what is real and what is sample data;
+- an **Open in design** button: `<button data-open-design="/preview/path">Open in design</button>`,
+  where the value is the preview page's path on the design server. The starter
+  wires it; the app answers by opening the design panel at that path, starting
+  the server first if needed.
+
+Wrap the entry in a screen block, but put no markup in it. The block names the
+**committed component file and the preview page path**, so the ticket that
+connects the screen has something to point at. Use the starter's `.designed`
+entry:
+
+```html
+<!-- screen:invoice-list -->
+<div class="designed">
+  <h3>Invoice list</h3>
+  <p>Layout and states are real components; the rows are sample data.</p>
+  <p class="mono">src/components/InvoiceList.tsx · preview /preview/invoice-list</p>
+  <button data-open-design="/preview/invoice-list">Open in design</button>
+</div>
+<!-- /screen:invoice-list -->
+```
+
+Hand mocks remain for screens nobody designed live, for server-built pages and
+for native mobile, which design mode cannot preview.
+
 ## Inline only
 
 **Styles, scripts and images are inline. The file makes no network request** —
@@ -77,7 +133,8 @@ or inline SVG. This is enforced, not a preference: the app renders the preview
 in a sandboxed frame that runs scripts and refuses every fetch, external image
 and font, form post and popup. Anything hosted elsewhere simply does not load.
 In-page links scroll by script (the starter does this), because hash navigation
-is unreliable inside that frame.
+is unreliable inside that frame. The Open in design button posts a message to
+the app, which is not a request, so it stays within this rule.
 
 ## Sizing
 
@@ -95,4 +152,6 @@ minute for a small feature, a few minutes for a large one.**
   For a grilled feature, `C` is empty and no decision is marked.
 - Every pin points at the decision the spot actually shows.
 - The five parts are in order; **Under the hood** is closed.
+- Every screen designed in design mode is a designed-screen entry that names its
+  committed component and preview page, not a redrawn mock.
 - The file is still fully inline.

package/skills/packs/runcastle/skills/feature/references/rounds.md

@@ -0,0 +1,91 @@
+# Running rounds
+
+Load this when you are about to dispatch a round, or you have just been woken by
+one coming back.
+
+A round is how workers build: each gets one ticket, a clean sandbox and the full
+brief, and works on its own branch that lands on the feature branch. You
+dispatch it, you are woken when it comes back, you check what it did, and you
+plan the next move.
+
+Start the first round only after the human's explicit yes in chat, and ask again
+before any round the agreed plan did not settle (SKILL.md, "The human's yes").
+
+## What you run on
+
+`get_feature_context` carries:
+
+- `rounds` — every round so far, numbered from 1: the tickets it held, how it ended, its gates.
+- `latestReady` — your newest ready declaration, if any.
+- `driveActive` — the human is test-driving this feature right now.
+- `stopped` — the human pressed Stop and has not replied since.
+- `waitingReason` — why the feature is waiting on the human, if it is.
+- `burnConcurrency` — how many workers the project runs at once.
+
+## Plan a round
+
+1. **Write the tickets** with `emit_tickets`, or reshape pending ones with
+   `update_ticket` / `cancel_ticket`, following `./tickets.md`. Then **dispatch**
+   with `dispatch_round({ seqs })`, naming exactly the pending tickets this round
+   covers. Tickets you do not name wait for a later round. A ticket may stay
+   blocked by tickets that landed or were cancelled in an earlier round: those
+   count as satisfied. A blocker that is still pending or failed must be named
+   in the same round.
+2. **Every worker task names its deliverable and how it is checked.** A worker
+   with no stated check reports success on its own terms. Say what is built and
+   what proves it: the test that goes green, the command that passes, the screen
+   that shows it.
+3. **Keep the round to `burnConcurrency` workers or fewer.** A soft cap: workers
+   past it only queue, and a wider round has more to reconcile when it returns.
+4. **Contract first when the work spans layers.** When workers on different
+   layers must agree on a shape — types, an API, a schema — make one ticket land
+   that contract in code and make the others `blockedBy` it in the same round.
+   **Contracts live in code, never in a doc**: workers trust the code.
+5. **UI work names the design references.** A ticket that touches UI tells its
+   worker which design docs to follow — the project's own design system docs and
+   any design references in this feature's docs — and asks it to plan the
+   screen, build it, then critique it against those docs with screenshots.
+
+Workers do not talk to each other or to you. They report through their digests,
+their ticket status and their commits. A worker that finds the contract wrong
+stops and says so in its digest; reconciling it is your job, between rounds.
+
+## When a round comes back
+
+You are woken with the round's outcome, each ticket's status, the verify-gate
+result, any review findings and where the digests are.
+
+1. **Trust the record over the prose.** Ticket status, the gates and the commits
+   are what happened; a digest is a worker's account of it. Read each digest
+   with `get_ticket({ seq })`, and where the two disagree, believe the record.
+2. **Reconcile.** Did a worker report the contract wrong, or change something
+   another relied on? Did a decision turn out wrong? Fix the contract in code,
+   amend `decisions.md` and `spec.md` when what was decided changed, and update
+   the pending tickets. A contract reported wrong is a reason to re-plan.
+3. **Handle review findings.** A finding stays open until you resolve it: fix it
+   in a round or yourself, or dismiss it and say why.
+4. **Decide the next move**:
+   - small leftovers → fix them yourself;
+   - more work, or a failed ticket to retry → plan the next round;
+   - a question only the human can answer → ask it in chat and call `wait_for_you({ why })`;
+   - the feature does what the plan says → run the checks and declare ready (SKILL.md, "Ready for the human").
+
+A failed round is just what came back. Re-plan, retry or fix it yourself.
+`declare_ready` warns when the last round had failures; pass that on.
+
+## While and after the human drives
+
+Never dispatch while the feature is being driven (`driveActive`). Your own
+commits wait until the drive stops. When the human reports back, follow
+SKILL.md, "After a drive"; when you are satisfied again, declare ready with a
+new scenario.
+
+## What the server refuses
+
+`dispatch_round` is refused, with the reason, for a draft or shipped feature,
+while a round is already running, while the human is driving this feature, and
+after the human pressed Stop until they have replied. It is also refused when a
+ticket you name is blocked by a ticket outside the round that is still pending
+or failed (or does not exist): the refusal lists each such edge, and the fix is
+to name that blocker in the round too. `stop_round` stops the running round;
+work that already landed stays.

package/skills/packs/runcastle/skills/feature/references/spec.md

@@ -0,0 +1,54 @@
+# Writing the spec
+
+Load this once what the feature does is settled — whether you will build it
+yourself or hand it to workers — or when a later decision changes what
+`spec.md` says.
+
+The spec is synthesis, not an interview: write it from the conversation and
+`docs/features/<slug>/decisions.md`. Do not re-ask the human anything that is
+settled.
+
+## Process
+
+1. **Load state.** `mcp__runcastle__get_feature_context` for the decisions and
+   any existing `spec.md` (this may be a rewrite). Read any canonical doc listed
+   in `notInlined` before writing a word. Explore the codebase for its current
+   state if you have not already; use the project's domain vocabulary and
+   respect any ADRs in the area you touch.
+
+2. **Sketch the seams** — the public boundaries the feature will be tested at.
+   Prefer *existing* seams to new ones; use the *highest* seam possible; the
+   fewer across the codebase, the better — the ideal is one. If new seams are
+   needed, propose them at the highest point you can. They flow straight into
+   the tickets and the tests, so get them right here.
+
+3. **Write `docs/features/<slug>/spec.md`** with exactly these sections:
+
+   ```markdown
+   # <Feature title>
+
+   ## Problem
+   The problem the user faces, from the user's perspective.
+
+   ## Approach
+   The solution from the user's perspective, then the shape of it: modules built/modified, their interfaces, schema/API/contract decisions, key interactions. Prose, not a file-by-file plan.
+
+   ## Seams
+   The interfaces to test at (from step 2) — each named, with what it lets you observe. Flag which are existing vs. new.
+
+   ## Out of scope
+   What this feature explicitly does not cover, including scope parked as backlog features.
+
+   ## Open questions
+   Anything still unresolved or deliberately deferred.
+   ```
+
+   Do **not** hardcode file paths or code snippets — they go stale. Exception:
+   when the conversation produced a snippet that pins a decision more precisely
+   than prose can (a state machine, a reducer, a schema, a type shape), inline
+   the decision-rich parts and say where it came from.
+
+4. **Commit it** with the decisions it was written from, as a docs commit.
+
+When a later decision changes what the feature does, amend the affected
+sections in place rather than appending.

package/skills/packs/runcastle/skills/feature/references/tickets.md

@@ -0,0 +1,229 @@
+<!-- Forked from Matt Pocock's to-tickets skill, via https://github.com/mattpocock/skills, 2026-07-14, adapted for runcastle -->
+
+# Writing tickets
+
+Load this when work is worth handing to sandboxed workers and you are about to
+write, reshape or cancel tickets.
+
+Break the work into **tickets** — vertical slices, each cutting end-to-end
+through every layer it needs, each big enough to be worth a whole agent session
+and small enough to finish inside one — and emit them with
+`mcp__runcastle__emit_tickets`. Synthesize from `spec.md` and the conversation.
+The feature's existing tickets come as summary rows in `get_feature_context`;
+`mcp__runcastle__get_ticket({ seq })` holds one ticket's context, acceptance
+criteria and digest.
+
+## The one thing that makes a runcastle ticket different
+
+Each ticket is executed by a **single fresh agent, alone, in a sandbox, with
+~100k tokens and NO way to ask a follow-up question.** It sees only what you put
+in the ticket plus the code already in the repo. So — *inverting* the usual
+"avoid file paths, they go stale" rule — the ticket's `context` field **must be
+concrete and self-sufficient**: name the files to touch, the existing patterns
+to copy, the type/schema shapes, the gotchas, the commands to run and verify
+with. A ticket that assumes the agent can ask "where does X live?" is a broken
+ticket. Over-specify context; under-specify nothing.
+
+## The second thing: a ticket costs ~10 minutes before it does any work — and pays it twice if it overruns
+
+That fresh agent is fresh *every time*. Each ticket gets its own container: cold
+build, a full dependency install (measured 70–507s, ~2.5 min average), then an
+agent that re-reads the spec, the docs digest, and every file your `context`
+names — reading the repo was 16% of all agent time across 42 measured attempts.
+**This overhead is paid per ticket and is the same whether the ticket is twenty
+lines or a day's work.** Splitting one coherent piece of work into three tickets
+triples it, and adds two seams where a new agent has to reconstruct what the
+previous one had just finished learning.
+
+But that meter runs both ways. A ticket too big to finish in one pass gets no
+cheap second wind: an iteration is not a retry (ADR-0008) — the container is
+rebuilt, the install runs again, and a brand-new agent re-reads everything from
+the last commit, having lost every conclusion its predecessor reached.
+
+So size a ticket to **earn its container and still land in one pass**:
+substantial, with room left at the end for the tests, the self-review and the
+commits. Fine-grained slicing belongs *inside* a ticket, as the
+`acceptanceCriteria` list: the worker goes red→green one criterion at a time and
+commits each green slice, so one ticket with six criteria orients once; six
+one-criterion tickets orient six times.
+
+Expect a **handful of substantial tickets** for a feature — roughly 4–8, each
+worth a session. A dozen thin ones means you sliced by layer or by file, not by
+behaviour. Two or three giant ones means you will pay back the containers you
+saved, with interest, when they overrun.
+
+## 1. Draft vertical slices
+
+<vertical-slice-rules>
+- Each slice cuts a narrow but COMPLETE path through every layer it needs (schema, API, UI, tests) — vertical, NOT a horizontal slice of one layer.
+- A completed slice is demoable or verifiable on its own.
+- Each slice is worth one fresh ~100k-token agent session working alone and **lands inside it** — leave room for the orientation at the front and the tests, self-review and commits at the back.
+- **Merge when a merge test holds.** Two drafts are one ticket if they touch the same files, share a type or module, or the second one's first act would be re-reading what the first just wrote. Same for the obvious siblings of one behaviour: create/edit/delete of a resource, an endpoint and the UI that calls it, code and the tests that cover it.
+- **Split only for a real reason:** (a) a genuine gate — the later work cannot be written until the earlier work's interface exists; (b) the combined work would not land in one session; (c) a prefactor, which is its own slice done first ("make the change easy, then make the easy change"); (d) parallel width, under the rule below; (e) the wide-refactor sequence below.
+- **Not reasons to split:** one ticket per file, layer, endpoint or component; keeping each ticket easy; keeping diffs small; separating tests from the code they test.
+- **Parallelism pays when the halves are file-disjoint.** Tickets with no blocking edge burn concurrently, each on its own temp branch, landing one at a time (ADR-0002) — so two substantial slices touching *different* files buy real wall-clock. Two touching the *same* files race to land, and the loser fails on a merge conflict: that width costs a re-burn. Overlapping files → merge.
+</vertical-slice-rules>
+
+Give each ticket its **blocking edges** — the tickets that must finish before it
+can start. The field is required: a ticket with no blockers gets an empty array.
+
+<review-ticket>
+**A review ticket, when you choose to run one.** Whether a batch gets a review
+is your call (SKILL.md, "Review is your call"). When it does, add **one** ticket
+with `kind: "review"`, blocked by every implementation ticket whose work it
+checks. It is not a slice: it is the brief for the agent that exercises the
+*integrated* work on the feature branch and reports what it finds as findings.
+Its `goal` says what to verify and its `acceptanceCriteria` are the things to
+check off, one per behaviour worth confirming — the review agent walks them in
+order. `emit_tickets` refuses a ticket *titled* like a review but carrying
+another kind: set the kind (or retitle it) and re-emit.
+
+The review agent works in **exactly one of two modes**, never both — a browser
+**Drive** of the app against your acceptance criteria, or **Gates**: the
+project's verify commands plus a two-axis read of the diff. Reviews that
+attempted both ran long or died having delivered neither.
+
+Make the choice obvious. Prescribe a walkthrough only when there is genuinely a
+surface to walk, in plain prose ("open the settings flow, add a project, check
+the empty state"), and write the `acceptanceCriteria` as the steps of that walk.
+When the work changed nothing a human could drive — prompt contracts, docs, an
+internal refactor, a backend-only change — say so in the ticket, and write
+criteria the gates-and-diff read can check off.
+
+**Say what to walk, never which mode.** A review ticket never directs the agent
+to Gates — no "Mode: Gates", no "skip the drive" — and the mode is the review
+agent's call from the surface you describe. Least of all give as the reason that
+the change "isn't deployed or installed yet": the drive boots **the branch** —
+the project's drive setup points it at the checkout's own code, migrations and
+assets precisely so a branch is visible in its own drive. A review ticket once
+prescribed Gates on exactly that reasoning, and a UI feature reached the human
+without ever being driven. If the state to check does not exist yet in a fresh
+drive, the `acceptanceCriteria` say how to produce it inside the drive, as far as
+the project's drive instructions allow, and then what to check.
+
+The review agent never edits code, so its ticket needs no `seams` beyond the
+surface it exercises, and finding bugs is a *successful* review. Its digest
+carries a prose summary of what landed, which the Review view leads with, so
+`goal` asks for the verification, not for the summary.
+</review-ticket>
+
+<parallelism-budget>
+**Budget the parallelism explicitly, before you emit.** A round runs up to
+`burnConcurrency` tickets at once (from `get_feature_context`), but a ticket
+cannot start until every ticket in its `blockedBy` has landed, so a round's
+wall-clock is set by its **critical path**: the longest chain of blocking edges.
+A chain of N tickets is N sequential sandboxes however wide the pool is.
+Measured at `burnConcurrency: 3`, three consecutive batches whose tickets each
+chained end to end came in at **1.09x, 1.16x and 1.00x** — the width was there
+and never spent.
+
+So, after slicing, **say it out loud in the session**:
+
+- the **critical path** — the longest chain of implementation tickets, named in order, and its length;
+- **how many tickets can run at once**, against this project's `burnConcurrency`;
+- whether that clears the bar: T implementation tickets at concurrency C want a chain no longer than roughly **T / C**.
+
+**When it does not clear the bar, reslice.** **A blocking edge is true only when
+the later ticket reads the earlier one's output**: a file it writes, a type or
+interface it defines, a schema it migrates, a stub it fills. "Related", "same
+area", "logical reading order" are not blocking edges — drop them. Where the
+edge is real, merge the two into one ticket, or pull the shared foundation
+forward into the blocker so everything else goes wide behind it.
+
+A review ticket is the tail by definition: measure the critical path over the
+implementation tickets and add it. Width only counts if it lands: parallel
+tickets touching the same files collide on landing.
+</parallelism-budget>
+
+<ship-a-scenario>
+**Ship a scenario when the state is hard to reach.** A scenario is a project
+command under `.runcastle/scenarios/` that seeds a state and prints the URL to
+land on, so a test drive starts where the feature is instead of on a blank app.
+Read `get_feature_context`'s `scenarios` field — `{ setUp, runnerConfigured,
+scenarios, fixtures }` — before you decide anything.
+
+**When `setUp` is true**, ask of each ticket: will the person driving this have
+to build state by hand to see it — an account, a cart with an expired coupon?
+
+- If yes, give the implementation ticket that builds that state an acceptance criterion: "Ship `.runcastle/scenarios/<group>/<name>.<ext>` that seeds <state> (reusing `_fixtures`) and prints `ENTRY_URL=<where>`". Name the fixtures it should reuse. When the change is an API call, the criterion also ships a sibling `.http` file at the same path with the request, and the scenario prints `TOKEN=` when the call is authenticated.
+- Name that scenario in the review ticket's `context`, if there is one, so the reviewer replays it rather than improvising the setup; and use it as the `scenario` you declare ready with.
+- Copy changes and settings toggles get none. A scenario earns its place only where reaching the state is the chore.
+- The worker writes and typechecks the scenario but cannot run it — a sandbox has no drive.
+
+**When `setUp` is false**, card nothing about scenarios. Tell the human once
+that ＋ New scenario in a test drive sets scenarios up for this project.
+</ship-a-scenario>
+
+<wide-refactor-exception>
+A **wide refactor** — one mechanical change (rename a column, retype a shared symbol) whose blast radius breaks thousands of call sites at once — cannot land green as a vertical slice. Sequence it **expand → migrate → contract**. Expand: add the new form beside the old so nothing breaks (one ticket). Migrate: move call sites over in batches sized by blast radius (per package/dir), each a ticket blocked by the expand, green throughout because the old form still exists. Contract: delete the old form once no caller remains, blocked by every migrate batch. If even the batches cannot stay green alone, let them all block a final integrate-and-verify ticket — green is promised only there.
+</wide-refactor-exception>
+
+<preview-screen-block>
+When the feature has a `preview.html` and a ticket **builds a screen that appears in it as a screen block**, point that ticket at **one named screen block**, never the file. Its **context** names the path (`docs/features/<slug>/preview.html`) and the block name, and tells the worker to find the two markers, `<!-- screen:<name> -->` and `<!-- /screen:<name> -->`, and **read only the lines between them**. Say plainly that the block shows the approved look and behaviour and **is not the implementation**: build it with the project's real components and never copy the mock's markup. **Never tell a worker to read the whole file.**
+
+A ticket with no screen does not mention the preview.
+
+A **designed-screen block** holds no mock. It names a component committed in design mode and its preview page. Point the ticket at that component file and that preview page path, not at markup.
+</preview-screen-block>
+
+<connect-designed-screens>
+A ticket that wires a **designed screen** (one committed in design mode, `design: …` commits on the feature branch) names the committed component and its preview page in its `context`, and says plainly that **the look is approved**. Its job is to **connect, never restyle**:
+
+- swap the sample data for real data (queries, API calls);
+- add the behaviour the design left out;
+- change markup only where the wiring needs it.
+
+When wiring forces a visible change (a field the design lacked, say), the worker calls it out in its digest.
+</connect-designed-screens>
+
+## 2. Build each ticket to the schema
+
+Emit an array of `TicketInput`. Number them from 1 in the array in **dependency
+order (blockers first)**; `blockedBy` holds those numbers.
+
+Each ticket:
+- **title** — `{group}: {task}`, in the domain vocabulary: `Checkout: apply the coupon at payment`.
+- **goal** — the end-to-end behaviour this ticket makes work, from the user's/caller's perspective. Not a layer list.
+- **context** — everything the sandboxed agent needs and cannot ask for: file paths, patterns to follow, type/schema shapes, gotchas, how to run and verify. Be concrete.
+- **acceptanceCriteria** — `string[]`, each independently *verifiable* (a behaviour you can observe, a command that passes). Four to eight on a substantial ticket is right; a list running well past that will not land in one pass.
+- **seams** — `string[]`, the public interfaces to test at (from the spec's Seams; prefer existing, prefer the highest, prefer one).
+- **blockedBy** — `number[]`, **required**, only true gates; `[]` when there are none.
+- **kind** — `"implementation"` (the default, omit it) or `"review"`.
+- **model** — optional, and usually omitted. See below.
+
+### Assigning a model (only from the annotated roster)
+
+`get_feature_context` returns `annotatedModels`: `{ id, runtime, note }` for the
+models the human wrote a use-case note against. That list is the *entire* set
+of ids you may use.
+
+- **Empty list → never set `model`.**
+- **Non-empty → set it only where a note plainly fits the ticket.** Unset is the good default.
+- **Never invent an id**, and never write one not in `annotatedModels` — the store rejects it and the whole batch fails to emit.
+
+## 3. Self-check, then emit
+
+Check yourself, in this order:
+
+1. **Can any two of these be one ticket?** Take them pair by pair; merging changes the rest.
+2. **Would any one overrun?** Split it where its files stop overlapping.
+3. Is each survivor a demoable vertical slice, worth a session?
+4. Are the blocking edges minimal and true? State the critical path and the width against `burnConcurrency`, and reslice if the chain runs longer than roughly total / concurrency. Do independent tickets touch different files?
+5. Is every `context` self-sufficient for an agent that cannot ask?
+6. If you chose a review, is there exactly one `kind: "review"` ticket, blocked by the work it checks?
+7. If `scenarios.setUp`, does every ticket that builds hard-to-reach state ship a scenario for it?
+
+Then `mcp__runcastle__emit_tickets({ tickets: [...] })` — **emit the array; do
+NOT write ticket files.** It returns `{ stored, ids }`, logs the timeline event
+itself, and opens the **Work** view beside the chat. Emit the **whole batch,
+fully enriched, in one call**; never emit placeholder contexts to enrich
+afterwards — a round dispatched mid-enrichment burns workers on placeholders.
+
+## Reshaping tickets later
+
+When something changes after tickets exist, walk the ticket list against it:
+
+- Stale but still needed → `update_ticket({ id, ...changed fields })` (pending or failed only).
+- No longer needed → `cancel_ticket({ id, reason })` (pending or failed only).
+- New work → `emit_tickets` again; tickets accumulate on the feature.
+- Landed work now wrong → a NEW ticket that corrects it. Never touch landed or running tickets.