@wemuda/launchrail 1.8.0 → 1.10.0

package/README.md

@@ -38,7 +38,7 @@ Launchrail structures development as two movements. The **foundation** runs once
   <img src="https://github.com/wemuda/launchrail/raw/master/assets/how-launchrail-works.png" alt="How Launchrail works — the foundation runs once per project (Vision → Visual exploration → Discovery research → Complexity grill → Technical research → Architecture decisions); the delivery loop then repeats once per slice (Specify features into tickets → Ralph loop → Verification) before looping back for the next slice." width="880" />
 </p>
 
-The skills are Launchrail's own complete, `launch-*` prefixed set ([ADR-0020](https://github.com/wemuda/launchrail/blob/master/docs/adr/0020-independent-skill-set.md)); the methodology of several stages is inspired by [Matt Pocock's skills](https://github.com/mattpocock/skills) — see [Credits](#credits). The full stage contract — inputs, artifacts, composition rules, and per-mode rigor — lives in [the workflow doc](https://github.com/wemuda/launchrail/blob/master/packages/cli/assets/skills/launchrail/launch/workflow.md).
+The skills are Launchrail's own complete, `launch-*` prefixed set ([ADR-0020](https://github.com/wemuda/launchrail/blob/master/docs/adr/0020-independent-skill-set.md)); the methodology of several stages is inspired by [Matt Pocock's skills](https://github.com/mattpocock/skills) — see [Credits](#credits). The full stage contract — inputs, artifacts, composition rules, and deliberate-skip rules — lives in [the workflow doc](https://github.com/wemuda/launchrail/blob/master/packages/cli/assets/skills/launchrail/launch/workflow.md).
 
 What makes projects **updatable** instead of copy-once-and-rot is the second half of the system: shared capabilities are *shipped as managed files and kept current on `sync`*, shared standards are *synchronized*, product knowledge stays *locally owned*, and reusable lessons are *deliberately promoted upstream*.
 
@@ -55,6 +55,7 @@ npx @wemuda/launchrail init
 From there, the day-to-day driver is not the CLI — it's the **`launch` skill** inside Claude Code: open the project and run `/launch`. Invoke it (or just ask "what's next?") and it reads your committed artifacts, works out where the project is — no vision yet, mid-grill, spec validated, tickets ready — and runs or routes to the next stage's owner. Give it a stage name (`launch design-validation`) to jump straight there. The skills carry the rest of the workflow too:
 
 - **`launch-project-alignment`** — the on-ramp for an existing codebase: infer a vision from the code, interview only the gaps, inventory the design system, then join the loop
+- **`launch-design-handoff`** — the design→code on-ramp: drop a Claude Design export (a zip, a folder, artboards) and it becomes a committed handoff package under `docs/design/` — read against the code and design system, gaps recorded as the grill's agenda — then sized into the loop ([ADR-0024](https://github.com/wemuda/launchrail/blob/master/docs/adr/0024-design-handoff-onramp.md))
 - **`launch-vision-creation`**, **`launch-discovery`**, **`launch-grill`**, **`launch-research`** — vision, then the divergent landscape scan, the grill (the convergent interview that runs both as the foundation's complexity grill and per-feature before speccing, keeping the glossary and ADRs honest as it goes), and primary-source research
 - **`launch-wayfinder`**, **`launch-spec`**, **`launch-tickets`**, **`launch-design-validation`** — break big work into decision maps, synthesize the spec, validate it visually, and cut tracer-bullet tickets with blocking edges
 - **`launch-browser-smoke`** — drives a real browser journey and leaves a traceable evidence bundle (with the browser-testing module)

package/assets/agents-docs/issue-tracker-github.md

@@ -17,7 +17,7 @@ Issues and specs for this repo live as GitHub issues. Use the `gh` CLI for all o
 - **Apply / remove labels**: `gh issue edit <number> --add-label "..."` / `--remove-label "..."`
 - **Close**: `gh issue close <number> --comment "..."`
 
-Infer the repo from `git remote -v` — `gh` does this automatically when run inside a clone.
+Infer the repo from `git remote -v` — `gh` does this automatically when run inside a clone. In `gh api` paths you can write the `{owner}/{repo}` placeholders literally and `gh` fills them from the current clone.
 
 GitHub shares one number space across issues and PRs, so a bare `#42` may be either — resolve with `gh pr view 42` and fall back to `gh issue view 42`.
 
@@ -31,21 +31,56 @@ The Launchrail workflow's label vocabulary — the skills quote these exact stri
 - **`ralph:building`** — claimed by an implementer; removed when its PR merges.
 - **`wayfinder:map`** / **`wayfinder:<type>`** — a wayfinder map and its decision tickets (see below).
 
+## Relationships — native, not prose
+
+GitHub renders issue relationships in its own UI: **blocking dependencies** and **parent/child sub-issues** both show in the issue's sidebar, so the frontier is visible at a glance without opening a body. **These native relationships are the canonical representation — create them, don't just describe them in prose.** A body line is the fallback only where the native relationship isn't available; when the two ever disagree, the native relationship wins.
+
+Both APIs key off an issue's numeric **database id**, _not_ its `#number` and _not_ its GraphQL `node_id`. Resolve it once per issue and reuse it:
+
+```bash
+gh api repos/{owner}/{repo}/issues/<n> --jq .id     # the database id to pass as issue_id / sub_issue_id below
+```
+
+### Blocking (`blocked by`)
+
+- **Add an edge**: `gh api --method POST repos/{owner}/{repo}/issues/<blocked>/dependencies/blocked_by -F issue_id=<blocker-db-id>` — issue `<blocked>` is now blocked by the issue whose database id is `<blocker-db-id>`.
+- **Read the gate**: an issue carries `issue_dependencies_summary.blocked_by`, the count of its still-**open** blockers — `gh api repos/{owner}/{repo}/issues/<n> --jq .issue_dependencies_summary.blocked_by`. `> 0` means blocked; `0` means every blocker is closed and the edge is clear. List them with `gh api repos/{owner}/{repo}/issues/<n>/dependencies/blocked_by`.
+- **Remove an edge**: `gh api --method DELETE repos/{owner}/{repo}/issues/<blocked>/dependencies/blocked_by/<blocker-db-id>`.
+- **Fallback** (dependencies unavailable): a `**Blocked by:** #<n>, #<n>` line at the top of the blocked issue's body. A ticket is unblocked when every blocker it names is closed.
+
+### Parent / child (sub-issues)
+
+- **Link a child**: `gh api --method POST repos/{owner}/{repo}/issues/<parent>/sub_issues -F sub_issue_id=<child-db-id>` — the child now nests under the parent and rolls up in its progress. The child must live in the same repo owner as the parent.
+- **Read**: `gh api repos/{owner}/{repo}/issues/<n>/parent` and `gh api repos/{owner}/{repo}/issues/<n>/sub_issues`.
+- **Fallback** (sub-issues unavailable): a `Part of #<parent>` line at the top of the child body, plus a task list in the parent.
+
+## Issue ↔ PR linkage (Development)
+
+Tie every implementation PR to its ticket so the work closes the loop automatically — this is what fills an issue's **Development** section and closes it on merge:
+
+- Put a **closing keyword** in the PR body — `Closes #<n>` (`Fixes` / `Resolves` work too). GitHub links the PR under the issue's **Development** section, and **merging the PR into the repository's default branch closes the issue**.
+- **Auto-close fires only from the default branch.** A PR merged into a consolidation / integration branch (not the default) still links but does **not** auto-close — close the issue explicitly after the merge (`gh issue close <n>`). Squash-merges can also miss the trigger even on the default branch; read the issue back on the remote and close it explicitly if it's still open.
+- **One ticket, one PR.** Adopt an existing `<n>`-scoped branch or PR rather than opening a second — the linkage should point at a single PR.
+
 ## When a skill says "publish to the issue tracker"
 
-Create a GitHub issue.
+Create a GitHub issue. When the ticket declares blocking edges or a parent, wire them as the **native relationships above** (blocking dependency, sub-issue) — the canonical, UI-visible form the implementation loop's frontier reads — falling back to a body line only where the native relationship isn't available.
 
 ## When a skill says "fetch the relevant ticket"
 
 Run `gh issue view <number> --comments`.
 
+## Specs and their tickets
+
+The stage-7 spec ([ADR-0025](https://github.com/wemuda/launchrail/blob/master/docs/adr/0025-spec-home-follows-tracker.md)) is itself an issue here — created by `launch-spec`, labelled **`spec`**, never `ready-for-agent`. There is no `docs/specs/` file; the issue is the canonical spec. When `launch-tickets` breaks it down, each ticket is a **GitHub sub-issue of the spec** (`gh api` on the sub-issues endpoint), or carries `Part of #<spec>` at the top of its body where sub-issues aren't enabled. Design validation revises the spec issue in place (its `## Design validation` section lives in the issue body).
+
 ## Wayfinding operations
 
 Used by `launch-wayfinder`. The **map** is a single issue with **child** issues as tickets.
 
 - **Map**: a single issue labelled `wayfinder:map`, holding the Notes / Decisions-so-far / Fog body. `gh issue create --label wayfinder:map`.
-- **Child ticket**: an issue linked to the map as a GitHub sub-issue (`gh api` on the sub-issues endpoint). Where sub-issues aren't enabled, add the child to a task list in the map body and put `Part of #<map>` at the top of the child body. Labels: `wayfinder:<type>` (`research`/`prototype`/`grilling`/`task`). Once claimed, the ticket is assigned to the driving dev.
-- **Blocking**: GitHub's **native issue dependencies** — the canonical, UI-visible representation. Add an edge with `gh api --method POST repos/<owner>/<repo>/issues/<child>/dependencies/blocked_by -F issue_id=<blocker-db-id>`, where `<blocker-db-id>` is the blocker's numeric **database id** (`gh api repos/<owner>/<repo>/issues/<n> --jq .id`, _not_ the `#number` or `node_id`). GitHub reports `issue_dependencies_summary.blocked_by` (open blockers only — the live gate). Where dependencies aren't available, fall back to a `Blocked by: #<n>, #<n>` line at the top of the child body. A ticket is unblocked when every blocker is closed.
+- **Child ticket**: an issue linked to the map as a **sub-issue** (see Relationships → Parent / child), labelled `wayfinder:<type>` (`research`/`prototype`/`grilling`/`task`). Where sub-issues aren't enabled, add the child to a task list in the map body and put `Part of #<map>` at the top of the child body. Once claimed, the ticket is assigned to the driving dev.
+- **Blocking**: the native **`blocked by` dependency** from Relationships — the canonical, UI-visible gate; GitHub reports open blockers as `issue_dependencies_summary.blocked_by`. Fall back to a `Blocked by: #<n>` body line only where dependencies aren't available.
 - **Frontier query**: list the map's open children (`gh issue list --state open`, scoped to the map's sub-issues / task list), drop any with an open blocker (`issue_dependencies_summary.blocked_by > 0`, or an open issue in the `Blocked by` line) or an assignee; first in map order wins.
 - **Claim**: `gh issue edit <n> --add-assignee @me` — the session's first write.
 - **Resolve**: `gh issue comment <n> --body "<answer>"`, then `gh issue close <n>`, then append a context pointer (gist + link) to the map's Decisions-so-far.

package/assets/agents-docs/issue-tracker-gitlab.md

@@ -40,6 +40,10 @@ Create a GitLab issue.
 
 Run `glab issue view <number> --comments`.
 
+## Specs and their tickets
+
+The stage-7 spec ([ADR-0025](https://github.com/wemuda/launchrail/blob/master/docs/adr/0025-spec-home-follows-tracker.md)) is itself an issue here — created by `launch-spec`, labelled **`spec`**, never `ready-for-agent`. There is no `docs/specs/` file; the issue is the canonical spec. When `launch-tickets` breaks it down, each ticket carries `Part of #<spec>` at the top of its description (on tiers with native epics, the spec may be an epic holding the tickets instead). Design validation revises the spec issue in place (its `## Design validation` section lives in the issue description).
+
 ## Wayfinding operations
 
 Used by `launch-wayfinder`. The **map** is a single issue with **child** issues as tickets.

package/assets/agents-docs/issue-tracker-linear.md

@@ -40,6 +40,10 @@ Create a Linear issue in the team above.
 
 Fetch the issue by its identifier (`ENG-123`) including comments.
 
+## Specs and their tickets
+
+The stage-7 spec ([ADR-0025](https://github.com/wemuda/launchrail/blob/master/docs/adr/0025-spec-home-follows-tracker.md)) is itself an issue here — created by `launch-spec`, labelled **`spec`**, never `ready-for-agent`. There is no `docs/specs/` file; the issue is the canonical spec. When `launch-tickets` breaks it down, each ticket is a **sub-issue of the spec** (Linear's native parent/child). Design validation revises the spec issue in place (its `## Design validation` section lives in the issue description).
+
 ## Wayfinding operations
 
 Used by `launch-wayfinder`. The **map** is a single issue with **child** issues as tickets.

package/assets/agents-docs/issue-tracker-local.md

@@ -11,7 +11,7 @@ Issues and specs for this repo live as markdown files in `.scratch/`.
 ## Conventions
 
 - One feature per directory: `.scratch/<feature-slug>/`
-- The spec is committed under `docs/specs/` (the rail's stage-7 artifact); `.scratch/<feature-slug>/spec.md` may hold a working copy
+- The spec is committed under `docs/specs/<feature-slug>.md` — the rail's stage-7 artifact and its single home in local mode (there is no external tracker to hold it)
 - Implementation issues are one file per ticket at `.scratch/<feature-slug>/issues/<NN>-<slug>.md`, numbered from `01` — never a single combined tickets file
 - Ticket state is recorded as a `Status:` line near the top of each issue file, using the label vocabulary below
 - Comments and conversation history append to the bottom of the file under a `## Comments` heading

package/assets/ralph.workflow.js

@@ -3,21 +3,23 @@
 //
 // The Ralph loop as a deterministic workflow: the plan, the frontier bookkeeping,
 // and every intermediate report live in script variables — not in any context window —
-// so long or wide runs cannot compact away their own state. The watchable, checkpointed
-// variant of the same loop is the launch-ralph skill; the two share one policy block,
-// and a policy change belongs in both places (ADR-0005, field-revised by ADR-0010).
+// so long or wide runs cannot compact away their own state. This is the engine for
+// every multi-ticket run (ADR-0022); the launch-ralph skill carries the same policy
+// block as the supervisor's contract and the declared-exception watchable mode, and
+// a policy change belongs in both places (ADR-0005, field-revised by ADR-0010, ADR-0022).
 export const meta = {
   name: 'ralph',
   description: 'Autonomous Ralph loop: implement ready tickets with fresh-context subagents, verification-gated',
   whenToUse:
-    'Run the Ralph implementation loop over the ticket backlog when the dependency graph is wide or the run is long. Scope a run via args: { only: [9, 10], width: 2 }, just [9, 10], or { max: 5 } to stop after 5 verified merges ("the next five" — the frontier picks which, in dependency order). Args must be JSON — resolve any natural-language scope to ticket numbers and a cap before launching. For a watchable, checkpointed run (or when something is already going wrong), use the launch-ralph skill instead.',
+    'The engine for any multi-ticket Ralph run. Scope a run via args: { only: [9, 10], width: 2 }, just [9, 10], or { max: 5 } to stop after 5 verified merges ("the next five" — the frontier picks which, in dependency order). The front door consolidates by DEFAULT (ADR-0026): it passes { target: "spec/44-mvp" } to collect the campaign onto that branch (default branch untouched; released later by one offered PR). Omitting target is the explicit trunk opt-in — each ticket merged straight into the default branch. { canary: true } holds width at 1 until the first verified merge. Args must be JSON — resolve any natural-language scope to ticket numbers, a cap, and a target before launching. For a watchable run (an explicit user ask, or a targeted intervention), use the launch-ralph skill instead — and say why.',
   phases: [
-    { title: 'Preflight', detail: 'read project config, sync the base, run the verification gate' },
+    { title: 'Preflight', detail: 'read project config, resolve the integration target, run the verification gate' },
     { title: 'Graph', detail: 'list ready tickets and their blocking edges, verbatim' },
-    { title: 'Build', detail: 'one fresh-context implementer per ticket, merge included' },
+    { title: 'Build', detail: 'one fresh-context implementer per ticket, handing off at PR-open' },
+    { title: 'Gate', detail: 'per-ticket merge gate: CI wait, squash-merge, explicit close' },
     { title: 'Verify', detail: 'remote ground truth for every claimed merge' },
     { title: 'Park', detail: 'comment failure history, label needs-info' },
-    { title: 'Release', detail: 'final verification gate and evidence summary' },
+    { title: 'Release', detail: 'final verification gate and the where-it-lives recap' },
   ],
 }
 
@@ -52,8 +54,19 @@ const POLICY = {
   max: A.max ?? 0,
   // Parallel implementers. Width also caps local build concurrency — several implementers
   // share one machine, and fanning out test runs buys backpressure, not speed. Use 1 until
-  // a run has landed tickets cleanly on this project.
+  // a run has landed tickets cleanly on this project — or pass canary: true, which does it
+  // for you. Tickets that add DB migrations collide on the next migration number when run
+  // in parallel; the pre-PR sync renumbers, but serializing them is cheaper.
   width: A.width ?? 3,
+  // Integration target. The front door consolidates by DEFAULT (ADR-0026): it resolves a
+  // scope-native branch name and passes it here, so the campaign collects on that branch and
+  // the default branch is never touched — the run ends by offering ONE release PR
+  // target -> default. '' is the explicit trunk opt-in: each ticket PR merged straight into
+  // the default branch; a bare launch with no target is therefore trunk mode — non-default.
+  target: A.target ?? '',
+  // Canary: hold width at 1 until the run's first verified merge proves the plumbing
+  // end to end (branch, PR, CI, merge gate, close). For a project's first campaign.
+  canary: A.canary ?? false,
   // Tries per ticket: 1 attempt + 1 retry with a fresh context, then park. Deferrals
   // (a declared blocker had not landed yet) hand their attempt back, capped separately.
   attempts: A.attempts ?? 2,
@@ -84,12 +97,14 @@ where it left off — do not start over. Never open a second PR for the same tic
 const PREFLIGHT_SCHEMA = {
   type: 'object',
   additionalProperties: false,
-  required: ['green', 'base', 'trackerAccess', 'verifyCommand', 'localCommands', 'failures'],
+  required: ['green', 'base', 'defaultBranch', 'trackerAccess', 'verifyCommand', 'localCommands', 'failures'],
   properties: {
     green: { type: 'boolean', description: 'base is synced and the verification gate passed' },
     headSha: { type: 'string', description: 'commit sha the gate ran against' },
     repo: { type: 'string', description: 'owner/name from the git remote, or empty' },
-    base: { type: 'string', description: 'default branch name' },
+    base: { type: 'string', description: "the run's integration base: the declared target branch when one is set, else the default branch" },
+    defaultBranch: { type: 'string', description: 'the repository default branch name' },
+    targetCreated: { type: 'boolean', description: 'true when a declared target branch was missing from the remote and was created from the default branch tip' },
     issueTracker: { type: 'string', description: 'issueTracker from .launchrail.yml (github | linear | none)' },
     trackerAccess: {
       type: 'string',
@@ -145,7 +160,9 @@ const BUILD_SCHEMA = {
   properties: {
     status: {
       type: 'string',
-      enum: ['merged', 'already-done', 'blocked', 'ci-red', 'ci-timeout', 'conflict', 'verify-failed', 'failed'],
+      enum: ['pr-open', 'merged', 'already-done', 'blocked', 'conflict', 'verify-failed', 'failed'],
+      description:
+        '"pr-open" is the normal hand-off (the loop owns CI and merge); "merged" only when an adopted PR turned out to be merged already (idempotency)',
     },
     pr: { type: 'integer', description: 'PR number, when one was opened or adopted' },
     mergeCommit: { type: 'string' },
@@ -162,6 +179,24 @@ const BUILD_SCHEMA = {
   },
 }
 
+const GATE_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['status', 'summary'],
+  properties: {
+    status: {
+      type: 'string',
+      enum: ['merged', 'ci-failed', 'ci-timeout', 'not-mergeable', 'failed'],
+    },
+    mergeCommit: { type: 'string' },
+    issueClosed: { type: 'boolean' },
+    summary: {
+      type: 'string',
+      description: 'on merged: the API facts; on failure: the failing check or conflicting files, enough for a fresh implementer to act on',
+    },
+  },
+}
+
 const VERIFY_SCHEMA = {
   type: 'object',
   additionalProperties: false,
@@ -211,24 +246,32 @@ Start clean: delete the failed ralph/${ticket.number}-* branch first, re-sync th
       : ''
   return `${preamble(pre)}
 
-Implement ticket #${ticket.number} ("${ticket.title}") end to end — merge included. You own it alone; assume no knowledge of any other session. Other implementers are working on other tickets against the same base right now, so ${pre.base} will move under you. That is expected.
+Implement ticket #${ticket.number} ("${ticket.title}") through to an open PR. You own the build alone; assume no knowledge of any other session. Other implementers are working on other tickets against the same base right now, so ${pre.base} will move under you. That is expected.
 ${retry}
 Steps, in order:
 1. Dependency gate: before anything else, confirm every ticket on this ticket's "Blocked by" line is CLOSED with its work merged into ${pre.base}. If any blocker is still open, do NOT build on a missing dependency — report status "blocked", name the open blocker in "failure", and stop. That is a deferral, not a failure; the loop retries you after the blocker lands.
-2. Read the ticket and everything it links (spec sections, ADRs, journeys). Report status "already-done" if it is already closed.
+2. Read the ticket and everything it links (spec sections, ADRs, journeys). If the tracker tool truncates the body (long code spans are a known trigger), fetch the full text by another route — the tracker's search API, the spec file in the repo — and never implement from a truncated ticket. Report status "already-done" if the ticket is already closed.
 3. Label the ticket ralph:building so a lost session leaves a trace.
 4. Branch from a fresh sync of ${pre.base}: ralph/${ticket.number}-<short-slug>.
 5. Implement by invoking the launch-ralph-implement skill — it owns the per-ticket contract: TDD, the verification gate, browser smoke for user-facing changes, self-review via /code-review, commit conventions.
-6. Pre-PR sync: merge the latest ${pre.base} into your branch. Conflicts are ordinary work — resolve them with the launch-resolving-merge-conflicts skill and re-run the verification gate if anything changed.
-7. Open a PR titled from the ticket, with "Closes #${ticket.number}" in the body. Never open a second PR if one already exists — adopt it. Opening against an up-to-date base means CI tests the state that will actually land.
-8. Wait for CI if the repository has it, spacing polls with the Monitor tool or a background sleep — never a foreground sleep, never a busy loop; treat ~20 minutes as the budget and report status "ci-timeout" beyond it. Fix what your branch broke and push. If a failure reproduces on ${pre.base} itself, report "ci-red" and stop — that is systemic, not this ticket's problem.
-9. Immediately before merging, re-sync with ${pre.base} once more (retry up to 3 times if the base keeps moving), then squash-merge. Squash-merge does not reliably fire "Closes" — read the issue back, close it explicitly if it is still open, and remove the ralph:building label. Never push to ${pre.base} directly; the PR is the only door.
+6. Pre-PR sync: merge the latest ${pre.base} into your branch. Conflicts are ordinary work — resolve them with the launch-resolving-merge-conflicts skill. If ${pre.base} gained DB migrations since you branched, regenerate yours to follow them with the project's migration tool — never hand-edit the migration journal. Re-run the verification gate if anything changed.
+7. Open a PR against ${pre.base}, titled from the ticket, with "Closes #${ticket.number}" in the body. Never open a second PR if one already exists — adopt it. Opening against an up-to-date base means CI tests the state that will actually land. Then report status "pr-open" with the PR number and STOP: the CI wait, the merge, and the issue close belong to the loop's merge gate, not to you — a subagent cannot wait on CI (a background sleep will not resume you). Never push to ${pre.base} directly; the PR is the only door.
 
 ${INTEGRITY}
 
 ${IDEMPOTENCY}
 
-Report honestly via the schema: "merged" only after the squash-merge API call succeeded; "blocked" when a declared blocker had not landed; "verify-failed" when the verification gate would not go green; "conflict" when a conflict was too ambiguous to resolve without losing behavior (say which files and why); "ci-red" / "ci-timeout" / "failed" otherwise, with a summary a fresh retry can act on. List deliberately-out-of-scope discoveries in "punted".`
+Report honestly via the schema: "pr-open" once the PR exists against ${pre.base}; "merged" only when an adopted PR turned out to be already merged; "blocked" when a declared blocker had not landed; "verify-failed" when the verification gate would not go green; "conflict" when a conflict was too ambiguous to resolve without losing behavior (say which files and why); "failed" otherwise, with a summary a fresh retry can act on. List deliberately-out-of-scope discoveries in "punted".`
+}
+
+function gatePrompt(pre, ticket, build) {
+  return `You are the merge gate for ticket #${ticket.number}: PR #${build.pr} is open against ${pre.base}.
+Tracker access from this environment: ${pre.trackerAccess}
+You own the CI wait, the squash-merge, and the tracker bookkeeping — and nothing else. You never write code, never push commits, never repair a failing branch; a failing PR is reported, not fixed here.
+1. Wait for CI on the PR, if the repository has it. Space checks with the Monitor tool — NEVER a bare background sleep (it will not resume you) and never a busy loop. Treat ~20 minutes as the budget; beyond it report status "ci-timeout".
+2. CI green (or absent): check mergeability against ${pre.base} — the base may have moved since CI started. Mergeable: squash-merge via the tracker API; if the base moves between check and merge, re-check and retry up to 3 times. A real conflict is status "not-mergeable" — name the conflicting files if the API reports them.
+3. Merged: read issue #${ticket.number} back and close it explicitly if it is still open — "Closes #n" only auto-fires from the default branch${POLICY.target ? ', and this run does not merge there' : ', and squash-merge does not reliably fire it even there'} — then remove the ralph:building label. Report status "merged" with the merge commit sha.
+4. CI failed on the PR: report status "ci-failed" with the failing check and a summary a fresh implementer can act on. Fix nothing.`
 }
 
 function verifyPrompt(pre, ticket, build) {
@@ -308,17 +351,39 @@ async function drive(pre, ticket) {
     s.failures.push(`still blocked after ${s.defers} deferrals: ${build.failure ?? build.summary}`)
     return { ticket, ok: false }
   }
-  if (build.status !== 'merged') {
+  if (build.status !== 'pr-open' && build.status !== 'merged') {
     s.failures.push(`[attempt ${s.attempts}] ${build.status}: ${build.failure ?? build.summary}`)
     return { ticket, ok: false }
   }
   if (!build.pr) {
-    s.failures.push(`[attempt ${s.attempts}] reported merged but returned no PR number`)
+    s.failures.push(`[attempt ${s.attempts}] reported ${build.status} but returned no PR number`)
     return { ticket, ok: false }
   }
+  let mergeCommit = build.mergeCommit
+  if (build.status === 'pr-open') {
+    // The loop owns the merge gate (ADR-0022): an implementer cannot wait on CI (a
+    // subagent's background sleep never resumes it), and a single gate owner keeps
+    // merge ordering sane. A failing gate hands the ticket back as a failed attempt;
+    // the fresh retry adopts the PR via the idempotency clause, repairs, hands off again.
+    const gate = await agent(gatePrompt(pre, ticket, build), {
+      label: `gate:#${ticket.number}`,
+      phase: 'Gate',
+      schema: GATE_SCHEMA,
+      effort: 'low',
+    })
+    if (!gate) {
+      s.failures.push('gate agent died (infrastructure)')
+      return { ticket, ok: false, dead: true }
+    }
+    if (gate.status !== 'merged') {
+      s.failures.push(`[attempt ${s.attempts}] PR #${build.pr} ${gate.status}: ${gate.summary}`)
+      return { ticket, ok: false }
+    }
+    mergeCommit = gate.mergeCommit || mergeCommit
+  }
   // Nothing is trusted from a report — a claimed merge is checked against the remote
   // by a separate, cheap agent with tracker access only.
-  const verdict = await agent(verifyPrompt(pre, ticket, build), {
+  const verdict = await agent(verifyPrompt(pre, ticket, { pr: build.pr, mergeCommit }), {
     label: `verify:#${ticket.number}`,
     phase: 'Verify',
     schema: VERIFY_SCHEMA,
@@ -328,7 +393,7 @@ async function drive(pre, ticket) {
   if (verdict?.merged && verdict.issueClosed) {
     s.status = 'merged'
     s.pr = build.pr
-    s.mergeCommit = verdict.mergeCommit || build.mergeCommit
+    s.mergeCommit = verdict.mergeCommit || mergeCommit
     return { ticket, ok: true }
   }
   // Merged-but-issue-open fails verification too: the retry adopts the merged PR (the
@@ -363,9 +428,13 @@ function frontier(tickets, closedBefore) {
 // ---------------------------------------------------------------------------
 phase('Preflight')
 const pre = await agent(
-  `Preflight for a Ralph loop run in this repository. Fix nothing; report actual state.
+  `Preflight for a Ralph loop run in this repository. Report actual state; fix nothing — the one permitted mutation is creating the declared integration branch in step 2.
 1. Read .launchrail.yml (issueTracker, testing commands, modules) and AGENTS.md (verbatim commands).
-2. Identify the repo (git remote) and the default/base branch; sync it fresh (clean tree). If the base branch does not exist on the remote, report not green and say the base is missing — do not guess another branch.
+2. Identify the repo (git remote) and its default branch; report the default branch name as defaultBranch. ${
+    POLICY.target
+      ? `This run consolidates onto the integration branch "${POLICY.target}" — that branch is the base. If it does not exist on the remote, create it from the default branch's tip (no force; the default branch itself is never touched) and report targetCreated: true. A missing DEFAULT branch is still not green — do not guess.`
+      : `This run merges into the default branch (trunk) — that branch is the base. If it does not exist on the remote, report not green and say the base is missing — do not guess another branch.`
+  } Sync the base fresh (clean tree) and report its name as base.
 3. Determine how the tracker is reachable from THIS environment: check whether the CLI the project docs assume (e.g. gh) is installed; if not, name the concrete substitute available here (e.g. GitHub MCP tools) as an instruction future agents can follow.
 4. Run the project's install command, then the verification gate: npx @wemuda/launchrail verify. Report the actual exit codes, not the reassuring summary line. An empty verification contract failing the gate is a refusal condition, not something to work around.
 green means: base synced AND the verification gate exited 0.`,
@@ -384,11 +453,14 @@ if ((pre.issueTracker ?? 'none') === 'none') {
 phase('Graph')
 log(
   `Base green at ${pre.headSha ?? pre.base} on ${pre.base}. ` +
+    (POLICY.target
+      ? `Consolidating onto ${pre.base}${pre.targetCreated ? ' (created from the default branch tip)' : ''}; ${pre.defaultBranch || 'the default branch'} stays untouched. `
+      : `Trunk mode — each ticket merges into ${pre.base}. `) +
     (POLICY.only.length > 0
       ? `Scoped to ${POLICY.only.map((n) => `#${n}`).join(', ')}.`
       : 'No scope — building the whole ready frontier.') +
     (POLICY.max > 0 ? ` Stopping after ${POLICY.max} verified merge(s).` : '') +
-    ` Width ${POLICY.width}, ${POLICY.attempts} attempts per ticket.`,
+    ` Width ${POLICY.width}${POLICY.canary ? ' (canary: width 1 until the first verified merge)' : ''}, ${POLICY.attempts} attempts per ticket.`,
 )
 let graph = await agent(graphPrompt(pre), { label: 'read-graph', phase: 'Graph', schema: GRAPH_SCHEMA, model: 'haiku', effort: 'low' })
 if (!graph) throw new Error('graph agent died — refusing to start')
@@ -424,7 +496,10 @@ while (rounds < POLICY.maxRounds) {
   const ready = frontier(tickets, closedBefore)
   if (ready.length === 0) break
   rounds += 1
-  const batch = ready.slice(0, Math.min(POLICY.width, capLeft))
+  // Canary: the first verified merge proves the plumbing end to end (branch, PR, CI,
+  // merge gate, explicit close); until it lands, dispatch one ticket at a time.
+  const width = POLICY.canary && mergedCount() === 0 ? 1 : POLICY.width
+  const batch = ready.slice(0, Math.min(width, capLeft))
   log(`round ${rounds}: dispatching ${batch.map((t) => `#${t.number}`).join(', ')} (${ready.length} unblocked)`)
   const results = await parallel(batch.map((t) => () => drive(pre, t)))
   const landed = results.filter((r) => r?.ok)
@@ -495,10 +570,18 @@ verified means: the verification gate exited 0${pre.browserTesting && merged.len
   { label: 'release-verification', phase: 'Release', schema: RELEASE_SCHEMA },
 )
 
+// The recap is part of the contract (ADR-0022): where the work lives and the one
+// next step, as data — the supervisor relays it, never reconstructs it.
+const mode = POLICY.target ? 'consolidation' : 'trunk'
 return {
   rounds,
   verified: release?.verified ?? false,
   maxReached,
+  target: { mode, base: pre.base, defaultBranch: pre.defaultBranch ?? '', headSha: release?.headSha ?? '' },
+  nextStep:
+    mode === 'consolidation'
+      ? `All campaign work is on ${pre.base}; ${pre.defaultBranch || 'the default branch'} is untouched. Release it with one PR ${pre.base} -> ${pre.defaultBranch || 'the default branch'} — offer it, and open it only when the user says so.`
+      : `Every merged ticket is live on ${pre.base}; nothing is left to integrate.`,
   release,
   merged: merged.map((s) => ({ ticket: s.ticket.number, title: s.ticket.title, pr: s.pr, mergeCommit: s.mergeCommit })),
   parked: parked.map((s) => ({ ticket: s.ticket.number, title: s.ticket.title, failures: s.failures })),

package/assets/skills/launchrail/launch/SKILL.md

@@ -9,7 +9,7 @@ One command for the whole rail. You are the **conductor**, not a stage: find whe
 
 ## The stage map
 
-Read `.launchrail.yml` (`mode`, `origin`, `modules`, `issueTracker`) first — it is the source of truth for configuration; `npx @wemuda/launchrail status` for what's installed and current.
+Read `.launchrail.yml` (`origin`, `modules`, `issueTracker`) first — it is the source of truth for configuration; `npx @wemuda/launchrail status` for what's installed and current.
 
 | # | Stage | Owner (invoke / run) | Done when |
 |---|---|---|---|
@@ -20,7 +20,7 @@ Read `.launchrail.yml` (`mode`, `origin`, `modules`, `issueTracker`) first — i
 | 4 | Complexity grill | `launch-grill` | Grill constraints committed under `docs/research/` |
 | 5 | Technical research | `launch-research`, fed the grill constraints | Research notes committed under `docs/research/` |
 | 6 | Architecture decisions | ADRs (`docs/adr/0000-template.md`) | `docs/adr/NNNN-*.md` beyond the template |
-| 7 | MVP specification | `launch-wayfinder` / `launch-spec` † | A spec exists under `docs/specs/` |
+| 7 | MVP specification | `launch-wayfinder` / `launch-spec` † | A spec exists — a `spec`-labeled issue on the tracker, or a `docs/specs/` file in local mode (read `docs/agents/issue-tracker.md`) |
 | 8 | Design validation | `launch-design-validation` (fidelity chosen inside the skill) | The spec carries a `## Design validation` section (a recorded skip counts) |
 | 9 | Tickets | `launch-tickets` † | Tracker has `ready-for-agent` tickets with `Blocked by: #n` edges |
 | 10 | Implementation | `/launch-implement` † — drives the Ralph loop | The ready frontier is drained; PRs merged and verified |
@@ -41,12 +41,14 @@ Once the foundation exists (a real vision, ADRs beyond the template) and the use
 | **Semi** | Self-contained feature, some design surface, a handful of tickets | grill → `launch-spec` → design validation *(optional)* → `launch-tickets` |
 | **Small** | Well-understood change, little or no design surface, one or few tickets | grill → `launch-tickets` |
 
-Judgment calls: the grill here is feature-scoped (same `launch-grill`, narrower brief); discovery earns a place only when the feature opens genuinely new tech territory — a vendor category or storage engine the project hasn't used; design validation is for real UI surface; a genuine architecture decision gets an ADR before tickets. Between two sizes pick the smaller — it's cheaper to add a stage than to over-plan a small change. `mode` calibrates on top: `spike` may drop `launch-spec` and design validation (record the skip); `high-rigor` bumps one notch. Every size ends at `/launch-implement`.
+Judgment calls: the grill here is feature-scoped (same `launch-grill`, narrower brief); discovery earns a place only when the feature opens genuinely new tech territory — a vendor category or storage engine the project hasn't used; design validation is for real UI surface; a genuine architecture decision gets an ADR before tickets. Between two sizes pick the smaller — it's cheaper to add a stage than to over-plan a small change. Every size ends at `/launch-implement`.
+
+A feature that arrives **design-first** — a dropped zip or folder of Claude Design artboards, "here is the prototype of X" — routes through `launch-design-handoff` before sizing: it commits the package under `docs/design/<slug>/` and proposes a size; sizing then consumes its `handoff.md` as the feature brief, the grill takes the doc's open questions as its agenda, the spec cites the package as its UX/UI reference, and design validation usually becomes a recorded skip citing it.
 
 ## Running it
 
 1. **Did the user name a stage or a feature?** A stage keyword (below): sanity-check its inputs exist, offer the earlier stage if one is missing, but honor the jump if they insist — then invoke or hand off and stop. A new feature on a founded project: size it (above) and run the path.
-2. **Otherwise orient, then find the frontier.** A cheap read-only look first: `git status`, current branch, recent commits — is something already in flight for the stage you're about to start? If the tracker is configured and reachable, read the live discussion on relevant tickets and PRs, not just titles; skip what isn't there (orientation sharpens routing, never gates it). Then close stage-0 gaps yourself without asking (init, commit init output, `sync` — it seeds `docs/agents/` too). Walk stages 1 → 12 and stop at the first whose "done when" fails, skipping only what `mode` permits. `origin: existing` with no real vision → route to `launch-project-alignment`, not a blank vision.
+2. **Otherwise orient, then find the frontier.** A cheap read-only look first: `git status`, current branch, recent commits — is something already in flight for the stage you're about to start? If the tracker is configured and reachable, read the live discussion on relevant tickets and PRs, not just titles; skip what isn't there (orientation sharpens routing, never gates it). Then close stage-0 gaps yourself without asking (init, commit init output, `sync` — it seeds `docs/agents/` too). Walk stages 1 → 12 and stop at the first whose "done when" fails, skipping only what the vision's non-goals record as deliberately skipped. `origin: existing` with no real vision → route to `launch-project-alignment`, not a blank vision.
 3. **Confirm the read.** Say where you think the project is and why — which artifacts you found and which you didn't. Ambiguous signals (template-only vision, several specs) are questions, not guesses.
 4. **Route.** Invoke the owner by exact name, or prepare the handoff for a user-typed stage (†). For stage 7, name the authoritative inputs in order; if the stack isn't stood up yet, tell it to name its seams but leave harness mechanics to the foundation work. For stage 10, hand over `/launch-implement` — never start it yourself.
 5. **Leave an explained map.** Current stage, the next one with a sentence on what it does and whether it's optional here, then the rest of the arc to the destination — and that any stage is reachable by keyword. A bare stage name reads as a turnstile; explain, don't gate.
@@ -57,11 +59,11 @@ Case-insensitive direct jumps:
 
 - `status` / `where` — report the detected stage and stop.
 - `next` — detect the frontier and drive it (the default).
-- `setup` / `init` — 0 · `align` / `adopt` — the existing-project on-ramp · `vision` — 1 · `explore` — 2 · `discovery` / `landscape` — 3 · `grill` — 4 · `research` — 5 · `deep-research` — 3→5 · `adr` / `architecture` — 6 · `spec` — 7 · `design-validation` / `validate` — 8 · `tickets` — 9 · `implement` / `build` / `ralph` / `loop` — hand over `/launch-implement` · `verify` / `smoke` — 11 · `release` — 12.
+- `setup` / `init` — 0 · `align` / `adopt` — the existing-project on-ramp · `vision` — 1 · `explore` — 2 · `discovery` / `landscape` — 3 · `grill` — 4 · `research` — 5 · `deep-research` — 3→5 · `adr` / `architecture` — 6 · `spec` — 7 · `design-validation` / `validate` — 8 · `tickets` — 9 · `implement` / `build` / `ralph` / `loop` — hand over `/launch-implement` · `verify` / `smoke` — 11 · `release` — 12 · `handoff` / `design-handoff` — the design→code on-ramp (`launch-design-handoff`).
 - `feature` / `size` — size a described feature (recommend a path; route on request).
 
 Unrecognized keyword → show this list and ask.
 
-## Mode calibration
+## Deliberate skips
 
-`mode` calibrates rigor, not stage order: `spike` may skip stages 2–5 and 8 when the vision's non-goals record it (don't nag); `standard-mvp` skips nothing silently; `high-rigor` skips nothing, wants an ADR per stage-6 decision, and design validation covers error and edge states. When a stage looks skipped, check the vision's non-goals before deciding — and if you can't tell, ask.
+Skip nothing silently. A stage may be skipped only when the vision's non-goals record the skip — then honor it and don't nag. When a stage looks skipped, check the vision's non-goals before deciding — and if you can't tell, ask.

package/assets/skills/launchrail/launch/workflow.md

@@ -23,7 +23,7 @@ Two commands cover the whole rail:
 | 4 | Complexity grill | `launch-grill` | Vision + exploration + discovery | Grill constraints in `docs/research/` |
 | 5 | Technical research | `launch-research` | **Grill constraints** | Research notes in `docs/research/` |
 | 6 | Architecture decisions | ADRs (seeded template) | Research | `docs/adr/NNNN-*.md` |
-| 7 | MVP specification | `launch-wayfinder` / `launch-spec` † | Vision, ADRs, research | `docs/specs/` |
+| 7 | MVP specification | `launch-wayfinder` / `launch-spec` † | Vision, ADRs, research | A `spec`-labeled issue on the tracker (or `docs/specs/` in local mode) ‡ |
 | 8 | Design validation | Launchrail `design-validation` skill | Spec (+ Claude Design at the top fidelity) | Revised spec with `## Design validation` section |
 | 9 | Tickets | `launch-tickets` † | Validated spec | Tickets in the tracker: `ready-for-agent` label, `Blocked by: #n` edges |
 | 10 | Implementation | `/launch-implement` † → the Ralph loop | Ready tickets | PRs merged and verified; the frontier drained |
@@ -34,8 +34,9 @@ Two commands cover the whole rail:
 
 Stage notes:
 
-- **Stages 3 → 4 → 5 are one arc** (`deep-research`): discovery *diverges* — it maps the real option space for the vision's hard parts (all the auth vendors, not one) and never picks winners; the grill *converges* — it narrows that landscape into constraints; research de-risks what survives. Don't collapse discovery into the grill outside `spike` mode: a grill with no discovery narrows whatever stack was assumed upstream, the exact failure discovery exists to prevent ([ADR-0015](https://github.com/wemuda/launchrail/blob/master/docs/adr/0015-discovery-research-stage.md)).
+- **Stages 3 → 4 → 5 are one arc** (`deep-research`): discovery *diverges* — it maps the real option space for the vision's hard parts (all the auth vendors, not one) and never picks winners; the grill *converges* — it narrows that landscape into constraints; research de-risks what survives. Don't collapse discovery into the grill unless the vision's non-goals record the skip: a grill with no discovery narrows whatever stack was assumed upstream, the exact failure discovery exists to prevent ([ADR-0015](https://github.com/wemuda/launchrail/blob/master/docs/adr/0015-discovery-research-stage.md)).
 - **Stage 4 ends in a committed file, always.** `launch-grill` closes its interview by writing the surviving constraints to `docs/research/` — the conversation alone never closes the stage, and the skill treats the committed doc as part of its own contract.
+- **‡ The stage-7 spec's home follows the tracker** ([ADR-0025](https://github.com/wemuda/launchrail/blob/master/docs/adr/0025-spec-home-follows-tracker.md)), exactly as stage-9 tickets do. On a real tracker (GitHub, GitLab, Linear) the spec **is** a `spec`-labeled issue and no `docs/specs/` file is written; in local mode (`local`, or no tracker) it is a committed `docs/specs/<slug>.md` file. Detection is therefore tracker-aware — read `docs/agents/issue-tracker.md` to know where to look. `ready-for-agent` still marks tickets only; the spec issue wears `spec` so the loop never dispatches prose as work.
 - **Stage 8 scales to the spec's design surface** through a fidelity ladder ([ADR-0016](https://github.com/wemuda/launchrail/blob/master/docs/adr/0016-design-validation-fidelity-ladder.md)): recorded skip, flow diagrams, screen mockups, or Claude Design. The level choice lives inside `design-validation` (recommend, user confirms). It exists to catch "specified but wrong on screen" while the finding still costs a spec edit rather than re-cut tickets — that's why it precedes stage 9 and is not stage 11, which checks the *built* product. Even a skip is recorded through the skill, so the gate stays artifact-based.
 - **Stage 10 is one door.** `/launch-implement` drives the Ralph loop ([ADR-0017](https://github.com/wemuda/launchrail/blob/master/docs/adr/0017-implementation-loop-provider.md) as amended by [ADR-0020](https://github.com/wemuda/launchrail/blob/master/docs/adr/0020-independent-skill-set.md)). Launchrail owns both edges of the loop: `ready-for-agent` tickets with `Blocked by: #n` edges in, `launchrail verify` (+ browser smoke where enabled) gating every merge.
 
@@ -49,6 +50,14 @@ The stages above take a fresh project to its first release. After that, the deli
 
 Every size ends the same way: `/launch-implement`, gated by `launchrail verify`. Sizing changes *how many* planning stages a feature needs, never *who owns* them.
 
+A feature may arrive **design-first**: as a Claude Design prototype dropped into the session rather than a described idea. That arrival goes through the design handoff on-ramp (below) before sizing — the committed `handoff.md` then serves as the feature brief sizing consumes.
+
+## Returning from Claude Design
+
+The stages drive Claude Design code→design (stages 2 and 8). The delivery loop also runs the reverse trip: design work done *in* Claude Design — a tweak, the next few pages, a redesign — comes back as files, typically a zip of artboards. The Launchrail `design-handoff` skill owns that arrival ([ADR-0024](https://github.com/wemuda/launchrail/blob/master/docs/adr/0024-design-handoff-onramp.md)): it reads the prototype against the current code and design system, asks only the questions documenting needs, and commits a **handoff package** under `docs/design/<feature-slug>/` — the prototype verbatim plus a distilled `handoff.md`, both project-owned, in the same accumulating `docs/design/` home as earlier handoffs.
+
+From there the normal sizing paths apply, with two design-first twists: the handoff doc's open questions become the feature grill's agenda (the handoff feeds the grill, as the grill feeds research), and the spec cites `docs/design/<feature-slug>/` as its UX/UI reference — so design validation typically becomes a recorded skip citing the package, recorded through the `design-validation` skill as always. Like alignment, this is an on-ramp onto the same rail, not a second workflow; the handoff skill routes and never starts implementation.
+
 ## Adopting an existing project
 
 When `.launchrail.yml` records `origin: existing`, stage 1 is reached through the Launchrail `project-alignment` skill: it inventories what the codebase already has, infers a draft vision from the code, interviews only the gaps, and detects the existing design system as the baseline for stages 2 and 8, then hands to `vision-creation` to commit ([ADR-0013](https://github.com/wemuda/launchrail/blob/master/docs/adr/0013-existing-project-alignment.md)). Alignment is an on-ramp onto the same rail, not a second workflow.
@@ -64,14 +73,10 @@ The contract for `launch`, `/launch-implement`, and any agent driving the rail.
 - **`ready-for-agent` marks tickets, never specs.** The implementation loop's frontier is every open issue wearing that label, and it cannot tell prose from work — a spec or research note published to the tracker takes a different label (e.g. `spec`), or the loop will dispatch the document as work. Relabel before anyone starts the loop.
 - **Implementation is never started unprompted.** Stage 10 belongs to the user: conductors hand over `/launch-implement` and explain; they do not launch it.
 - **Everything the workflow produces is project-owned.** Vision, research, ADRs, specs, tickets — Launchrail tooling never overwrites them.
-- **Setup gaps are action, not conversation.** Known, additive fixes (commit untracked init output, run `init` when the manifest is missing, `sync` when loop materials are absent) get applied and reported; questions are saved for product artifacts, where intent is genuinely unknowable. Init owns installs — never improvise a dependency install from the web.
-
-## Stage-skipping by project mode
+- **Setup gaps are action, not conversation.** Known, additive fixes (commit untracked init output, run `init` when the manifest is missing, `sync` when loop materials are absent, record the project's test command as `testing.unitCommand` in `.launchrail.yml` once a real test runner exists — init detects it where it can and otherwise leaves it null) get applied and reported; questions are saved for product artifacts, where intent is genuinely unknowable. Init owns installs — never improvise a dependency install from the web.
 
-The manifest's `mode` calibrates rigor, not stage order:
+## Stage-skipping
 
-- `spike` — stages 2–5 and 8 may be skipped deliberately; record the skip in the vision's non-goals.
-- `standard-mvp` — the default path; skip nothing silently.
-- `high-rigor` — no skips; ADRs for every stage-6 decision, and design validation covers error and edge states, not just happy paths.
+Skip nothing silently. A stage may be skipped deliberately — a short experiment might drop visual exploration, discovery, research, or design validation — but only when the vision's non-goals record the skip. A recorded skip is honored without nagging.
 
 When a stage looks skipped, check the vision's non-goals before deciding whether it's deliberate — and if you still can't tell, ask.

package/assets/skills/launchrail/launch-design-handoff/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: launch-design-handoff
+description: The design→code on-ramp — take a Claude Design prototype dropped into the session (a .zip export, an extracted folder, artboard/HTML files, or a published canvas link) and turn it into a committed handoff package under docs/design/, read against the current codebase and design system, then route it into the delivery loop — normally a short feature grill, a spec that references the designs, and tickets. Use when the user drops design files or a zip from Claude Design and wants them documented or implemented — "here is the prototype of feature X" — or asks to hand designs back from Claude Design into code.
+---
+
+# Design handoff — from Claude Design back into the loop
+
+The rail drives Claude Design in two places — visual exploration (stage 2) and design validation at the top fidelity (stage 8). The delivery loop also runs the reverse trip: design work happens *in* Claude Design — a tweak, the next few pages, a redesign — and comes back as files. This skill is the **on-ramp for that return trip**: it turns a dropped prototype into a committed, readable handoff package and routes the work into the loop at the right size. It builds nothing itself — it gets the design intent into the repository as an artifact the planning stages can gate on and reference, then hands over.
+
+## Ground rules
+
+- **The package is committed, and everything in it is project-owned.** A dropped zip has no durable link and the session is ephemeral — so unlike stage 8's validation evidence, which stays linked ([ADR-0016](https://github.com/wemuda/launchrail/blob/master/docs/adr/0016-design-validation-fidelity-ladder.md)), a handoff prototype is the input of record for implementation and lands in the repo ([ADR-0024](https://github.com/wemuda/launchrail/blob/master/docs/adr/0024-design-handoff-onramp.md)). Launchrail tooling never rewrites `docs/design/`.
+- **Read the artboards, don't just file them.** Claude Design artboards are self-contained HTML: real layout, spacing, colors, type, and copy. The handoff doc is written from what the files actually say, cross-checked against what the user said the drop is.
+- **Interview only what documenting needs; leave alignment to the grill.** This skill asks just enough to file the package truthfully — scope, intentional-vs-accidental design-system divergence, load-bearing copy. Everything the prototype is silent on (missing states, behavior rules, edge cases) is *recorded as open questions* that become the feature grill's agenda, not interviewed twice.
+- **Design-system deltas are findings, not fixes.** Where the prototype's tokens diverge from the project's existing design system, ask whether that is an intentional restyle or an accident. Never silently normalize the prototype, and never silently fork the design system.
+- **Route, don't build.** The skill ends at a committed package plus a recommended path. Planning stages keep their owners; implementation stays behind the user-typed `/launch-implement`.
+
+## Process
+
+1. **Take intake.** Accept whatever arrived: a `.zip` (unpack in a scratch directory — never straight into the repo), an extracted folder, loose artboard/HTML/image exports, or a published canvas link (export what is reachable; if the session can't reach it, ask for the zip). Strip packaging junk (`__MACOSX/`, `.DS_Store`, editor caches). Confirm scope in one line: which feature this is, and whether it reads as a tweak, new pages, or a redesign.
+2. **Inventory and read.** For each artboard/screen: name it, read its markup, and note layout, components, states shown, and copy. Identify components repeated across screens, and the assets (images, fonts) the screens actually reference — anything shipped but unused stays out of the package and is noted as excluded.
+3. **Diff against the code.** Classify each screen against the current implementation: **new** (no counterpart), **changed** (a counterpart exists — enumerate the deltas: layout, components, tokens, copy), or **context** (unchanged, included for orientation only). Extract the tokens the prototype actually uses (palette, type scale, spacing, radii) and compare them with the project's design-system baseline (theme/tokens/Tailwind config, component library — the baseline `launch-project-alignment` records). Express deltas in the project's vocabulary where one exists.
+4. **Ask the documenting questions.** Settle only what the package can't be filed without: confirm the scope reading, rule on each design-system divergence (intentional or accident), and flag copy that reads load-bearing (is it real or placeholder?). Everything else the prototype doesn't show — empty/loading/error states, responsive behavior, permissions, motion, validation rules — goes into the handoff doc's **Open questions**, addressed to the grill.
+5. **Commit the package** under `docs/design/<feature-slug>/`:
+   - `prototype/` — the design files as received (after the junk strip), verbatim. Never edit an artboard; it is the designer's record.
+   - `handoff.md` — the distilled contract: date and source; scope (tweak / extension / redesign) in a paragraph; the screen inventory (per screen: file, intent, new/changed/context with deltas, states shown, states missing); the component map (prototype component → existing code component, or "new"); token/design-system deltas with the intentional-vs-accident ruling; assets kept and excluded; **Open questions** (the grill's agenda); and the recommended path. Record the precedence rule: implementation follows the prototype for look and layout, `handoff.md` for behavior, states, and everything the pixels don't show.
+
+   One slug per feature; use the same `docs/design/` root as earlier handoffs (visual identity, prior features) so design references accumulate in one place. Iterating on the same feature revises the same slug — replace `prototype/`, revise `handoff.md` in place with a dated revision note — never a blind overwrite of settled answers, and never a second competing package for one feature.
+6. **Route.** Recommend a size with a one-line reason and let the user confirm (sizing is `launch`'s call; this is the on-ramp's proposal):
+   - **Tweak** — token/copy/spacing changes to existing screens → short feature grill → `launch-tickets`, prototype as the visual reference.
+   - **New pages / a feature on the existing system** (the common case) → short feature grill *fed this handoff doc, its open questions as the agenda* → `launch-spec`, naming `docs/design/<feature-slug>/` as the design reference the spec cites for UX/UI → `launch-tickets`. Because the spec is written *from* the prototype, design validation usually becomes a recorded skip citing this package — recorded through `launch-design-validation` as always, so the gate stays artifact-based.
+   - **Redesign / new surface area** → `launch-wayfinder` and the full large-feature path.
+
+   Then hand to `/launch`, naming the committed `handoff.md` as the input. Never start `/launch-implement` yourself — every path ends there by the user's hand. See [`workflow.md`](../launch/workflow.md) for the stage contract.

package/assets/skills/launchrail/launch-design-validation/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: launch-design-validation
-description: Validate an approved spec visually before implementation — at a confirmed fidelity level (recorded skip, flow-diagram artifact, screen-mockup artifact, or Claude Design), feed the findings back into a revised spec, and produce a handoff note for ticket creation. Use when a spec in docs/specs/ is drafted and the user wants design validation, a visual review, or pre-implementation sign-off.
+description: Validate an approved spec visually before implementation — at a confirmed fidelity level (recorded skip, flow-diagram artifact, screen-mockup artifact, or Claude Design), feed the findings back into a revised spec, and produce a handoff note for ticket creation. Use when a spec is drafted (a spec-labeled issue on the tracker, or a docs/specs/ file in local mode) and the user wants design validation, a visual review, or pre-implementation sign-off.
 ---
 
 # Design validation
@@ -30,9 +30,9 @@ Every level answers the same question — does the specified behavior survive co
 
 ## Process
 
-1. **Locate the spec.** Find the spec under `docs/specs/` (ask if there are several). Read it plus `docs/vision.md` and any grill/research artifacts it references, so validation happens against the product's constraints rather than in a vacuum.
+1. **Locate the spec.** Find the spec in its tracker-appropriate home — a `spec`-labeled issue on the tracker, or a file under `docs/specs/` in local mode (read `docs/agents/issue-tracker.md`; ask if there are several). Read it plus `docs/vision.md` and any grill/research artifacts it references, so validation happens against the product's constraints rather than in a vacuum.
 2. **Extract the flows to validate.** From the spec, list the user-facing journeys it implies — entry point, steps, decision points, end state. Confirm the list with the user; three to six flows is the useful range for an MVP.
-3. **Choose the level — recommend, then confirm.** Read the spec's design surface and the manifest's `mode`, recommend one level with a one-line reason, and let the user confirm or override across all four. Mode is **advisory, never a gate**: `spike` leans toward a recorded skip, `high-rigor` leans toward mockups or Claude Design with error and edge states covered — but the user owns the call. Never pick silently.
+3. **Choose the level — recommend, then confirm.** Read the spec's design surface, recommend one level with a one-line reason, and let the user confirm or override across all four. The recommendation is **advisory, never a gate**: little or no design surface leans toward a recorded skip; a large or risky surface leans toward mockups or Claude Design with error and edge states covered — but the user owns the call. Never pick silently.
 4. **Run the level.**
    - **Recorded skip** — go straight to step 7 and write the section as a recorded skip: date, what was assessed, why nothing needed driving.
    - **Flow diagrams** — build one artifact page of flow/state diagrams covering the confirmed flows, including the decision points and terminal states the spec claims.
@@ -41,4 +41,4 @@ Every level answers the same question — does the specified behavior survive co
 5. **Harvest findings.** For each flow record: what the design confirmed, what it contradicted in the spec, and what the spec turned out to be silent on. Ambiguities count as findings. Findings at a low level are also a signal — if the diagrams alone surface deep uncertainty, recommend re-running a flow at a higher level before revising.
 6. **Revise the spec.** Apply the accepted findings to the spec in place. If a finding invalidates an ADR, update or supersede that ADR in the same change. Note rejected findings and why in the handoff note, so the question does not resurface every review.
 7. **Write the handoff note** at the end of the spec (section `## Design validation`) with: date, the level that ran, flows validated, links to the artifact pages / design artifacts, accepted changes, rejected findings with reasons, and open questions. This section is the evidence that validation happened — the ticket stage (`launch-tickets`) reads the spec as validated only if it is present.
-8. **Hand off.** Confirm with the user that the revised spec is approved, commit it (respect the project's commit conventions), and point them at ticket creation as the next stage. See [`workflow.md`](../launch/workflow.md) for the full stage order.
+8. **Hand off.** Confirm with the user that the revised spec is approved, save it in place — commit the file, or update the spec issue on the tracker — respecting the project's commit conventions, and point them at ticket creation as the next stage. See [`workflow.md`](../launch/workflow.md) for the full stage order.