@wemuda/launchrail 1.7.0 → 1.9.0

package/assets/ralph.workflow.js

@@ -1,28 +1,30 @@
 // Managed by Launchrail. Do not hand-edit — `launchrail sync` may replace this file.
-// Override policy per run via args instead, e.g. { width: 1, only: [9, 10] }.
+// Override policy per run via args instead, e.g. { width: 1, only: [9, 10], max: 5 }.
 //
 // 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 launchrail: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 } or just [9, 10]. For a watchable, checkpointed run (or when something is already going wrong), use the launchrail: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). Declare the integration target with { target: "spec/44-mvp" } to consolidate the campaign onto that branch (default branch untouched; release later with one PR) — omit it to merge each ticket 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' },
   ],
 }
 
 // ---------------------------------------------------------------------------
-// Policy — the launchrail:ralph policy block, as code. Override via args.
+// Policy — the launch-ralph policy block, as code. Override via args.
 // ---------------------------------------------------------------------------
 
 // args may arrive as an object ({ only, width, ... }), a bare array of ticket numbers,
@@ -46,10 +48,23 @@ const A = resolveArgs(args)
 const POLICY = {
   // Scope the run to specific ticket numbers ([] = the whole ready frontier).
   only: A.only ?? [],
+  // Stop after this many verified merges (0 = no cap). "The next five": the frontier
+  // decides which five, in dependency order. Batches never exceed the remainder, so a
+  // run has at most `max` merges and leaves the rest of the frontier ready, not parked.
+  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: '' (trunk) merges each ticket PR into the default branch; a branch
+  // name consolidates the whole campaign onto that branch and never touches the default
+  // branch — the run ends by offering ONE release PR target -> default (ADR-0022).
+  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,
@@ -80,12 +95,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',
@@ -141,7 +158,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' },
@@ -158,6 +177,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,
@@ -207,24 +244,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 launchrail: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 launchrail: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.
+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. 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) {
@@ -304,17 +349,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,
@@ -324,7 +391,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
@@ -359,9 +426,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.`,
@@ -380,10 +451,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.') +
-    ` Width ${POLICY.width}, ${POLICY.attempts} attempts per ticket.`,
+    (POLICY.max > 0 ? ` Stopping after ${POLICY.max} verified merge(s).` : '') +
+    ` 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')
@@ -398,16 +473,31 @@ for (const t of tickets) {
   }
 }
 
+const mergedCount = () => [...state.values()].filter((s) => s.status === 'merged').length
+
 let rounds = 0
+let maxReached = false
 while (rounds < POLICY.maxRounds) {
   if (budget.total && budget.remaining() < POLICY.reserve) {
     log(`token budget at reserve (${Math.round(budget.remaining() / 1000)}k left) — stopping before a new round`)
     break
   }
+  // The cap counts verified merges only — a failed or deferred dispatch frees its slot
+  // for a different ticket next round. Capping the batch at the remainder means even a
+  // fully successful round cannot overshoot.
+  const capLeft = POLICY.max > 0 ? POLICY.max - mergedCount() : Infinity
+  if (capLeft <= 0) {
+    maxReached = true
+    log(`cap reached: ${POLICY.max} verified merge(s) — stopping; the rest of the frontier stays ready`)
+    break
+  }
   const ready = frontier(tickets, closedBefore)
   if (ready.length === 0) break
   rounds += 1
-  const batch = ready.slice(0, POLICY.width)
+  // 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)
@@ -471,16 +561,25 @@ const release = await agent(
 2. Run the verification gate: npx @wemuda/launchrail verify. Report the actual exit code.
 ${
     pre.browserTesting && merged.length > 0
-      ? `3. The browser-testing module is enabled: start the app (node scripts/dev.mjs --background), scaffold an evidence bundle (npx @wemuda/launchrail smoke), and drive the smoke journeys from docs/testing/smoke-journeys.md per the launchrail:browser-smoke skill. Report the bundle path. A journey you could not complete is a failure, never a pass.`
+      ? `3. The browser-testing module is enabled: start the app (node scripts/dev.mjs --background), scaffold an evidence bundle (npx @wemuda/launchrail smoke), and drive the smoke journeys from docs/testing/smoke-journeys.md per the launch-browser-smoke skill. Report the bundle path. A journey you could not complete is a failure, never a pass.`
       : ''
   }
 verified means: the verification gate exited 0${pre.browserTesting && merged.length > 0 ? ' AND no smoke journey failed' : ''}.`,
   { 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/NOTICE.md

@@ -0,0 +1,41 @@
+# Attribution
+
+The skills in this directory are Launchrail's own — one complete, `launch-`
+prefixed workflow (ADR-0020), managed by `launchrail sync`.
+
+Several of them absorb methodology and contain text derived from
+[Matt Pocock's skills](https://github.com/mattpocock/skills), used and adapted
+under the MIT License reproduced below:
+
+- `launch-research`, `launch-grill` (including its `domain-modeling.md` and
+  `CONTEXT-FORMAT.md`), `launch-wayfinder`, `launch-spec`, `launch-tickets`,
+  `launch-code-review`
+
+The same applies to the issue-tracker and domain-doc files Launchrail seeds
+into `docs/agents/`. Each derived file carries its own derivation note. If
+Launchrail is useful to you, the inspiration credit belongs upstream — see the
+Launchrail README's Credits section.
+
+---
+
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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

@@ -0,0 +1,67 @@
+---
+name: launch
+description: The planning conductor and single entry point to the Launchrail loop. Detects how far a project has moved from idea toward release — setup, vision, visual exploration, discovery, grill, research, ADRs, spec, design validation, tickets — then runs or routes to the stage that owns the next step, and hands implementation to /launch-implement. Once the foundation exists it also sizes each new feature (large / semi / small) and routes the planning subset that size needs. Use to start or continue the workflow, ask what stage a project is at, size a new feature, or jump straight to a named stage.
+---
+
+# Launch — the loop conductor
+
+One command for the whole rail. You are the **conductor**, not a stage: find where the project sits, then run or hand off to the skill that owns the next step. Every stage has exactly one owner; [`workflow.md`](workflow.md) is the contract for who owns what and for the conductor rules — compose owners by name, gate on committed artifacts, prepare handoffs for user-typed stages, keep detection read-only. Follow those rules; this file only tells you how to route.
+
+## 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.
+
+| # | Stage | Owner (invoke / run) | Done when |
+|---|---|---|---|
+| 0 | Setup | `npx @wemuda/launchrail init` | Manifest + lockfile committed; `doctor` green (`docs/agents/` is seeded by init) |
+| 1 | Vision | `launch-vision-creation` — via `launch-project-alignment` when `origin: existing` | `docs/vision.md` exists and is real (not the bare template) |
+| 2 | Visual exploration | Claude Design | Exploration artifacts linked from `docs/vision.md` |
+| 3 | Discovery | `launch-discovery` | Landscape map committed under `docs/research/` (`discovery-*.md`) |
+| 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/` |
+| 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 |
+| 11 | Verification | `npx @wemuda/launchrail verify` · `launch-browser-smoke` | The gate is green; smoke evidence where behavior is user-facing |
+| 12 | Release | The project's release setup | The release is cut |
+
+† User-typed (`disable-model-invocation`): prepare the handoff — inputs committed, exact fully-argumented command handed over, resume when the artifact lands (see the conductor rules). Never call one and get refused, and never reverse-engineer it.
+
+`deep-research` = stages 3 → 4 → 5 as one arc: discovery widens the option space, the grill narrows it, research de-risks what survives. The workflow doc's stage notes carry the judgment calls for stages 3, 4, 8, and 10.
+
+## Sizing the next feature
+
+Once the foundation exists (a real vision, ADRs beyond the template) and the user brings **one new feature**, the frontier question changes from "what stage is next" to "how much planning does this feature deserve." Size it — propose with your reasoning, let the user correct you; they see scope the artifacts don't show:
+
+| Size | Looks like | Planning path |
+|---|---|---|
+| **Large** | A new subsystem or cross-cutting change; real unknowns; decisions worth an ADR | discovery *(new tech territory only)* → `launch-wayfinder` → grill → `launch-spec` → design validation → `launch-tickets` |
+| **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`.
+
+## 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.
+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.
+
+## Stage keywords
+
+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.
+- `feature` / `size` — size a described feature (recommend a path; route on request).
+
+Unrecognized keyword → show this list and ask.
+
+## Mode calibration
+
+`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.

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

@@ -0,0 +1,77 @@
+# The Launchrail core workflow
+
+How a project moves from idea to verified, released software through committed artifacts. The rail is one complete, self-contained skill set — every stage owner is a Launchrail `launch-*` skill, written to the rail's artifact contract ([ADR-0020](https://github.com/wemuda/launchrail/blob/master/docs/adr/0020-independent-skill-set.md); several absorb methodology from [Matt Pocock's skills](https://github.com/mattpocock/skills), credited in `NOTICE.md`). The stage table below is the contract for which skill owns which stage and what artifact it must leave behind, and the conductor rules further down are the contract for how the `launch` conductor (and any agent working the rail) behaves between stages.
+
+## Running it
+
+Two commands cover the whole rail:
+
+- **`/launch`** — plan. It detects which stage the project has reached from its committed artifacts and runs or routes to that stage's owner; it takes a stage name (`vision`, `discovery`, `design-validation`, …) to jump straight there, and it sizes each new feature once the foundation exists ([ADR-0009](https://github.com/wemuda/launchrail/blob/master/docs/adr/0009-launch-orchestrator-skill.md), [ADR-0018](https://github.com/wemuda/launchrail/blob/master/docs/adr/0018-implement-front-door.md)).
+- **`/launch-implement`** — build. The single entry point for stage 10: it drives ready tickets to verified merges through the project's selected loop — the whole frontier, a spec's tickets, the next N ("max 5"), or one ticket at a time.
+
+## Prerequisites
+
+- The repository is initialized (`npx @wemuda/launchrail init`) and healthy (`npx @wemuda/launchrail doctor`). Init writes the workflow skills, the implementation loop's materials, *and* the `docs/agents/` configuration (issue-tracker conventions and domain-doc rules, seeded from the manifest's answers) — there is no separate install or setup step on the golden path.
+
+## Stages
+
+| # | Stage | Tool | Input | Committed artifact |
+|---|---|---|---|---|
+| 1 | Vision | Launchrail `vision-creation` skill | The idea, the user | `docs/vision.md` |
+| 2 | Visual exploration | Claude Design | Vision | Exploration artifacts (linked from the vision) |
+| 3 | Discovery research | Launchrail `discovery` skill (composes `launch-research`) | Vision + intended stack | Landscape/options map in `docs/research/` (`discovery-*.md`) |
+| 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/` |
+| 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 |
+| 11 | Verification | `npx @wemuda/launchrail verify` · Launchrail `browser-smoke` skill | Merged work | The gate green; smoke evidence where behavior is user-facing |
+| 12 | Release | The project's release setup | Verified base | The release cut |
+
+† **User-typed by design** — `disable-model-invocation`: only the user can start these. `launch-wayfinder`/`launch-spec` and `launch-tickets` publish to the tracker; `/launch-implement` spawns agents and merges PRs. A conductor prepares the handoff instead of calling them — see the conductor rules.
+
+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)).
+- **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.
+- **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.
+
+## Sizing the work in the delivery loop
+
+The stages above take a fresh project to its first release. After that, the delivery loop repeats once per feature, and `launch` sizes each feature so its planning depth matches the work ([ADR-0014](https://github.com/wemuda/launchrail/blob/master/docs/adr/0014-start-feature-conductor.md), folded into `launch` by [ADR-0018](https://github.com/wemuda/launchrail/blob/master/docs/adr/0018-implement-front-door.md)):
+
+- **Large feature** — discovery when it opens new tech territory, `launch-wayfinder` to break it down, a grill, `launch-spec`, design validation, then `launch-tickets`.
+- **Semi feature** — a grill, `launch-spec`, optionally design validation, then `launch-tickets`.
+- **Small feature** — a grill straight to `launch-tickets`.
+
+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.
+
+## 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.
+
+## Conductor rules
+
+The contract for `launch`, `/launch-implement`, and any agent driving the rail. The conductors execute these rules; this document owns them.
+
+- **One owner per stage, invoked by name.** Every stage has exactly one owning skill. Invoke it by name; do not paraphrase, wrap, re-prompt, or re-derive its work inline — the skill is the only place its stage's behavior lives.
+- **Artifacts gate stages, not chat memory.** A stage is done only when its committed artifact exists; detect by reading the repository, and when a signal is ambiguous (a template-only vision, an abandoned spec draft), ask rather than assume. Detection and sizing are read-only — every write happens inside the stage owner.
+- **User-typed stages get a prepared handoff, never reverse-engineering.** A `disable-model-invocation` refusal is the cue to hand over, not to reproduce the skill's work by hand or grep vendored skill files. A prepared handoff is three moves: confirm the stage's input artifacts are committed; hand the user the exact, fully-argumented command naming those inputs (a bare `/skill` sends it re-deriving what your inputs already settle — arguments that point at committed inputs are parameters, not paraphrase); pick up automatically once the stage's artifact lands.
+- **The grill feeds research.** Run the grill before technical research and hand research the grill's surviving constraints as its brief.
+- **`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
+
+The manifest's `mode` calibrates rigor, not stage order:
+
+- `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.
+
+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-browser-smoke/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: launch-browser-smoke
+description: Drive the running app through its defined smoke journeys in a real browser and produce a Launchrail evidence bundle. Use when user-facing work needs verification beyond deterministic tests, when the user asks to smoke-test the app, or before declaring user-facing work done in a project with the browser-testing module enabled (.launchrail.yml modules.browser-testing).
+---
+
+# Browser smoke testing
+
+Drive the real application through its user journeys in a browser and record evidence. Agentic smoke testing supplements deterministic tests — it never replaces them, and it never substitutes assertion for evidence.
+
+## Preconditions
+
+1. `.launchrail.yml` has `modules.browser-testing: true`. If not, stop and suggest `npx @wemuda/launchrail add browser-testing`.
+2. Deterministic checks pass first: run `node scripts/verify.mjs`. If verify fails, fix that before smoke testing — smoke runs on top of a green build.
+3. The app is running. Start it with `node scripts/dev.mjs` (use `--background` in cloud or CI sessions; logs land in `.launchrail/state/dev.log`). In a fresh clone, run `node scripts/setup.mjs` first.
+
+## Run contract
+
+1. **Collect the journeys.** Read `docs/testing/smoke-journeys.md` (sections headed `## Journey:`) plus any journeys defined in the ticket or spec under verification. Each journey has a start point, steps, and verify checks.
+2. **Scaffold the evidence bundle.** Run `npx @wemuda/launchrail smoke` (add `--url <url>` for a preview environment). It confirms the app responds and creates `artifacts/verification/<run-id>/` containing `meta.json`, a `summary.md` skeleton, and `screenshots/` + `traces/` directories. If it reports the app unreachable, start the app — do not skip the journey.
+3. **Drive each journey in a real browser** — Playwright MCP, browser tools, or a Playwright script, whichever is available. The browser-testing module seeds a Playwright MCP server (`.mcp.json`); approve it once in Claude Code to drive the browser interactively, or fall back to a Playwright script in headless CI. Follow the steps as a user would: click, type, navigate. Try realistic variations and obvious edge cases, and watch the console and network panel as you go.
+4. **Capture evidence while testing, not afterwards:**
+   - Screenshots of each key state → `screenshots/`
+   - Console errors and warnings → `console.log`
+   - Failed or unexpected requests → `network-errors.json`
+   - Playwright traces where available → `traces/`
+5. **Apply the standard checks to every journey:**
+   - No uncaught console errors
+   - No failed API requests
+   - The success state is visible
+   - Data remains after refresh
+
+## When you find a real bug
+
+1. Record the precise reproduction in the evidence bundle.
+2. Add or update a deterministic test that fails on the bug.
+3. Fix the bug.
+4. Prove the deterministic test passes.
+5. Re-run the affected journey.
+6. Keep the trace or screenshot that shows the failure.
+
+This turns exploratory findings into permanent regression coverage instead of forgotten discoveries.
+
+## Completing the run
+
+- Fill in `summary.md` completely: journey outcomes, standard checks, evidence references, deviations, newly added tests, remaining blockers. Check only boxes you actually verified.
+- Record any deviation from the spec or design in `deviations.md` next to the summary.
+- A journey you could not complete is a failure or a blocker, never a pass.
+- Never mark a journey passed while it has unexplained console or network errors.
+- The committed record is `summary.md`, `deviations.md`, and `meta.json`; bulky evidence stays local or becomes a CI artifact.