@wemuda/launchrail 1.14.0 → 1.15.0

package/README.md

@@ -60,9 +60,10 @@ From there, the day-to-day driver is not the CLI — it's the **`launch` skill**
 - **`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)
+- **`launch-browser-smoke`** — drives the running app in a real browser to see a just-built change working — one-off, from the shell with `agent-browser`, no test suite and no evidence bundle ([ADR-0034](https://github.com/wemuda/launchrail/blob/master/docs/adr/0034-browser-smoke-one-off-driving.md); with the browser-testing module)
 - **`launch-implement`** — the one door to building: `/launch-implement` drives ready tickets to verified merges through the Ralph loop (a ticket number builds just that one; "the next 5 of spec #2" scopes and caps a run)
 - **`launch-ralph`**, **`launch-ralph-implement`**, **`launch-code-review`**, **`launch-resolving-merge-conflicts`** — the verification-gated loop engine behind that door, installed by `init`
+- **`launch-loop-readiness`** — checks and tunes a repo for the loop: measures the gates, sets the fast per-land gate, parallelizes the e2e specs, shares caches for parallel builders, narrows CI triggers, creates the tracker labels, adds hosted-session setup ([ADR-0033](https://github.com/wemuda/launchrail/blob/master/docs/adr/0033-loop-readiness.md)); `doctor` shows the same findings as warn-only readiness lines
 
 The CLI is the maintenance surface you return to between sessions:
 
@@ -73,7 +74,6 @@ npx @wemuda/launchrail sync                  # apply managed updates + run migra
 npx @wemuda/launchrail add browser-testing   # enable a module
 npx @wemuda/launchrail doctor                # repository and environment checks
 npx @wemuda/launchrail verify                # deterministic verification gate
-npx @wemuda/launchrail smoke                 # scaffold a browser-smoke evidence bundle
 npx @wemuda/launchrail eject <module|file>   # opt out of management (vendor mode: --all)
 ```
 

package/assets/ralph.workflow.js

@@ -30,7 +30,7 @@ export const meta = {
     { title: 'Verify', detail: 'remote ground truth for every claimed land' },
     { title: 'Checkpoint', detail: 'the full gate on the base every N lands, with one bounded repair when red' },
     { title: 'Park', detail: 'comment failure history, label needs-info' },
-    { title: 'Release', detail: 'final full gate and smoke, prune landed branches, the where-it-lives recap' },
+    { title: 'Release', detail: 'final full gate, prune landed branches, the where-it-lives recap' },
   ],
 }
 
@@ -93,8 +93,8 @@ const POLICY = {
   // counts as a real failure.
   resyncs: A.resyncs ?? 2,
   // Run the FULL verification gate on the base after this many lands (0 = only at release).
-  // Every land already passed the fast gate on the merged tree; the full suite (browser
-  // journeys included) is paid once per checkpoint instead of once per ticket, and a red
+  // Every land already passed the fast gate on the merged tree; the full suite (e2e
+  // specs included) is paid once per checkpoint instead of once per ticket, and a red
   // checkpoint has at most this many suspects.
   checkpointEvery: A.checkpointEvery ?? 5,
   // A sha the caller vouches for: a previous run verified the base green at exactly this
@@ -153,7 +153,6 @@ const PREFLIGHT_SCHEMA = {
       items: { type: 'string' },
       description: 'other verbatim local commands (typecheck, lint, unit tests) implementers should use',
     },
-    browserTesting: { type: 'boolean', description: '.launchrail.yml modules.browser-testing' },
     pushedBranches: {
       type: 'array',
       items: {
@@ -299,7 +298,6 @@ const RELEASE_SCHEMA = {
   properties: {
     verified: { type: 'boolean', description: 'the full verification gate is green on the final base (run now, or already proven at this exact tip)' },
     headSha: { type: 'string' },
-    smokeBundle: { type: 'string', description: 'path of the smoke evidence bundle, when one was produced' },
     prunedBranches: { type: 'array', items: { type: 'string' }, description: 'the landed ralph/* branches deleted from the remote' },
     summary: { type: 'string' },
     failures: { type: 'array', items: { type: 'string' } },
@@ -316,7 +314,7 @@ Architecture decisions: read the registry index (docs/adr/README.md) and open on
 Tracker access from this environment: ${pre.trackerAccess}
 Blocking edges live on tickets as "Blocked by: #n" lines.
 Verbatim local commands: install: ${pre.installCommand}${pre.localCommands.length > 0 ? ` ; ${pre.localCommands.join(' ; ')}` : ''}
-Two gates. The FAST gate is ${pre.fastGateCommand} — run it before every hand-off; it must exit 0. The FULL gate (${pre.verifyCommand}) belongs to the loop, which runs it on the base at its checkpoints — do not spend your turn on the whole suite; run only the slow test files your change touches (a browser journey you edited).
+Two gates. The FAST gate is ${pre.fastGateCommand} — run it before every hand-off; it must exit 0. The FULL gate (${pre.verifyCommand}) belongs to the loop, which runs it on the base at its checkpoints — do not spend your turn on the whole suite; run only the slow test files your change touches (an e2e spec you edited).
 Several implementers share this machine — run single test files while iterating and save full runs for the gate.`
 }
 
@@ -339,7 +337,7 @@ Implement ticket #${ticket.number} ("${ticket.title}") through to a pushed, fast
 ${retry}${resyncNote}
 Steps, in order:
 1. Dependency gate: before anything else, confirm every ticket on this ticket's "Blocked by" line is CLOSED with its work landed on ${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). 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.
+2. Read the ticket and everything it links (spec sections, ADRs, designs). 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 and push immediately. ${adopt} From here on the pushed branch is your checkpoint: commit and push after every green step (a passing test slice, a finished subtask) — a session that dies keeps everything up to its last push, and its successor resumes from there instead of rebuilding. The pushes are also the loop's liveness signal.
 5. Implement by invoking the launch-ralph-implement skill — it owns the per-ticket contract: TDD, commit-and-push cadence, the fast gate, browser smoke for user-facing changes, self-review via launch-code-review, commit conventions.
@@ -404,7 +402,7 @@ Failures: ${(cp.failures ?? []).join(' | ') || cp.summary}
 
 Repair the base through to a pushed, green branch:
 1. Branch from a fresh fetch and push at once: \`git fetch origin ${pre.base} && git checkout -b ralph/repair-${k}-<short-slug> origin/${pre.base} && git push -u origin HEAD\`. Never check out ${pre.base} itself in this worktree.
-2. Reproduce the failure — the failing test files first, the full gate if needed — and find the root cause among the listed landings (\`git log ${cp.greenSha || ''}..${cp.headSha}\`): an integration break between two tickets, a migration-number collision, a journey a landing invalidated. Fix it properly; regenerate colliding migrations with the project's migration tool.
+2. Reproduce the failure — the failing test files first, the full gate if needed — and find the root cause among the listed landings (\`git log ${cp.greenSha || ''}..${cp.headSha}\`): an integration break between two tickets, a migration-number collision, an e2e spec a landing invalidated. Fix it properly; regenerate colliding migrations with the project's migration tool.
 3. Make the fast gate green, then the FULL gate (${pre.verifyCommand}) green — this repair lands under the full gate. Self-review via the launch-code-review skill, commit conventionally, push after every green step.
 4. Hand off: report status "ready" with branch, headSha, and a commitTitle like "fix(<scope>): <what>". Then STOP — the loop lands it. Never push to ${pre.base} yourself.
 Report "failed" with the one fact a human must know if the base cannot be repaired without losing behavior.
@@ -418,20 +416,15 @@ function releasePrompt(pre, opts) {
     : opts.needsGate
       ? `2. Run the install command (${pre.installCommand}), then the FULL verification gate: ${pre.verifyCommand}. Report the actual exit code.`
       : `2. The full gate already passed at exactly this tip (${opts.greenSha}) during the run — report verified: true without re-running it, unless the tip you synced differs, in which case run ${pre.verifyCommand}.`
-  const smokeStep =
-    !opts.baseRed && opts.smoke
-      ? `
-3. The browser-testing module is enabled and tickets landed: 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.`
-      : ''
   const pruneStep =
     opts.prune.length > 0
       ? `
-4. Prune the remote branches of the verified-landed tickets, and ONLY these: ${opts.prune.join(', ')} (\`git push origin --delete <branch>\` each; a branch already gone is fine). Never delete any other branch. Report prunedBranches.`
+3. Prune the remote branches of the verified-landed tickets, and ONLY these: ${opts.prune.join(', ')} (\`git push origin --delete <branch>\` each; a branch already gone is fine). Never delete any other branch. Report prunedBranches.`
       : ''
   return `Release verification for a finished Ralph loop run, in THIS checkout. Fix nothing.
 1. Sync a fresh ${pre.base} (\`git fetch origin ${pre.base}\`, \`git checkout ${pre.base}\`, \`git merge --ff-only origin/${pre.base}\`) and record its head sha.
-${gateStep}${smokeStep}${pruneStep}
-verified means: the full verification gate is green on the final base${!opts.baseRed && opts.smoke ? ' AND no smoke journey failed' : ''}.`
+${gateStep}${pruneStep}
+verified means: the full verification gate is green on the final base.`
 }
 
 const graphPrompt = (pre) => `List the open, ready tickets for a Ralph loop run. Change nothing on the tracker.
@@ -943,7 +936,6 @@ const release = await agent(
     baseRedReason,
     needsGate: baseTip !== lastGreenSha,
     greenSha: lastGreenSha,
-    smoke: Boolean(pre.browserTesting) && landed.length > 0,
     prune: landed.map((s) => s.branch).filter(Boolean),
   }),
   { label: 'release-verification', phase: 'Release', schema: RELEASE_SCHEMA },

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

@@ -15,7 +15,7 @@ Read `.launchrail.yml` (`origin`, `modules`, `issueTracker`) first — it is the
 
 | # | Stage | Owner (invoke / run) | Done when |
 |---|---|---|---|
-| 0 | Setup | `npx @wemuda/launchrail init` | Manifest + lockfile committed; `doctor` green (`docs/agents/` is seeded by init) |
+| 0 | Setup | `npx @wemuda/launchrail init`; then `launch-loop-readiness` to tune the repo for the implementation loop (optional — recommended once for an existing codebase) | Manifest + lockfile committed; `doctor` green (`docs/agents/` is seeded by init) — its `ralph …` readiness lines are advice, never a gate |
 | 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`) |
@@ -26,7 +26,7 @@ Read `.launchrail.yml` (`origin`, `modules`, `issueTracker`) first — it is the
 | 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 |
+| 11 | Verification | `npx @wemuda/launchrail verify` · `launch-browser-smoke` | The gate is green; user-facing behavior seen working in a real browser |
 | 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.
@@ -50,7 +50,7 @@ A feature that arrives **design-first** — a dropped zip or folder of Claude De
 ## 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 the vision's non-goals record as deliberately skipped. `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). When `doctor` warns on its `ralph …` readiness lines (fast gate, e2e specs, CI triggers, hosted setup, commands), offer `launch-loop-readiness` once — it measures and tunes the repo for the loop — and move on; readiness never gates the rail. 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 — with the banner.** Render the rail banner for the position you detected, then say 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 — call the Skill tool with its 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. **Close every transition with the banner.** When a stage finishes or a handoff is prepared, re-render the banner — the just-closed artifact under Done, the next mover under Now, the `➤` line carrying the one next action (the exact fully-argumented command when the stage is user-typed). Add a sentence on what the next stage does and whether it's optional here, and that any stage is reachable by keyword — a bare stage name reads as a turnstile; explain, don't gate.
@@ -61,7 +61,7 @@ Case-insensitive direct jumps:
 
 - `status` / `where` — render the rail banner for the detected position (with the evidence) 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 · `handoff` / `design-handoff` — the design→code on-ramp (`launch-design-handoff`).
+- `setup` / `init` — 0 · `readiness` / `tune` / `optimize` — `launch-loop-readiness` · `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.

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

@@ -51,6 +51,7 @@ A planning session (a grill, a wayfinder ticket, an interview) closes with the b
 ## 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.
+- Before the first `/launch-implement` on an existing codebase, `launch-loop-readiness` (stage 0, optional) measures the verification gates and tunes the repository for the implementation loop — a fast per-land gate, parallel e2e specs, shared caches for parallel builders, CI triggers, tracker labels, hosted-session setup, verbatim commands ([ADR-0033](https://github.com/wemuda/launchrail/blob/master/docs/adr/0033-loop-readiness.md)). `doctor`'s `ralph …` readiness lines say when it is worth running; they warn, never fail.
 
 ## Stages
 
@@ -66,7 +67,7 @@ A planning session (a grill, a wayfinder ticket, an interview) closes with the b
 | 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 |
+| 11 | Verification | `npx @wemuda/launchrail verify` · `launch-browser-smoke` | Merged work | The gate green; user-facing behavior seen working in a real browser |
 | 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.
@@ -77,7 +78,7 @@ Stage notes:
 - **Stage 4 converges far enough to build, not exhaustively.** The grill's stopping rule is build-safety — the decisions the next slice depends on are locked or safely defaulted — never an empty question tree: product design is generative, and "everything answered before implementation" is not a reachable state ([ADR-0029](https://github.com/wemuda/launchrail/blob/master/docs/adr/0029-planning-interaction-contract.md)). "Nothing silently assumed" still holds, but it means every open question is *labeled and parked*, not answered. And 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 --fast` gating every land and the full `launchrail verify` (+ browser smoke where enabled) at the loop's checkpoints and release ([ADR-0032](https://github.com/wemuda/launchrail/blob/master/docs/adr/0032-ralph-lean-local-gate-loop.md)).
+- **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 --fast` gating every land, the full `launchrail verify` at the loop's checkpoints and release, and — where the browser-testing module is enabled — each implementer's one-off browser smoke of its user-facing ticket ([ADR-0034](https://github.com/wemuda/launchrail/blob/master/docs/adr/0034-browser-smoke-one-off-driving.md)) ([ADR-0032](https://github.com/wemuda/launchrail/blob/master/docs/adr/0032-ralph-lean-local-gate-loop.md)).
 
 ## Sizing the work in the delivery loop
 

package/assets/skills/launchrail/launch-browser-smoke/SKILL.md

@@ -1,49 +1,45 @@
 ---
 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).
+description: Drive the running app in a real browser to see a just-built change working — a one-off, agent-driven check of the feature, not a test suite and not an evidence bundle. Use before declaring user-facing work done when .launchrail.yml has modules.browser-testing enabled, or when the user asks to smoke-test or click through the app.
 ---
 
-# Browser smoke testing
+# Browser smoke — see the change working
 
-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.
+A browser smoke is you driving the real stack in a real browser to check that what you just built looks right and works. It is **one-off**: it lives for this change and ends in a verdict, not in a test file, a journeys catalogue, or a committed report ([ADR-0034](https://github.com/wemuda/launchrail/blob/master/docs/adr/0034-browser-smoke-one-off-driving.md)). Deterministic coverage is the other lane — `npx @wemuda/launchrail verify` with the unit command and the thin Playwright e2e specs — and a smoke never grows it by accident.
 
 ## 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.
+2. The fast gate is green: `npx @wemuda/launchrail verify --fast`. A smoke runs on top of a green build; a red one is fixed first.
+3. The app runs from **this** worktree: `node scripts/dev.mjs --background` (in a fresh clone, `node scripts/setup.mjs` first). Other builders may share the machine — pass `--port <n>` with a port nobody else uses. The script writes the URL to `.launchrail/state/dev.url` and the pid to `.launchrail/state/dev.pid`; read the URL from there rather than assuming `testing.appUrl`.
+4. The driver is `agent-browser`, installed by `scripts/setup.mjs`: `npx agent-browser --version` must answer. If it does not, run setup; if it still cannot install, use the fallback below.
+
+## The run
+
+1. **Decide what to check.** From the ticket's acceptance criteria and your diff, write three to six steps for *this change*: where to start, what to click or type, what must be visible at the end. They live in your head and your handoff — never in a repository file.
+2. **Drive them, one session per ticket.** `export AGENT_BROWSER_SESSION=<branch-or-ticket>` keeps your browser apart from other builders'. Then, from the shell:
+   - `npx agent-browser open <url>` — start on the page the change lives on.
+   - `npx agent-browser snapshot -i` — the interactive elements with refs (`@e1`, `@e2`, …).
+   - `npx agent-browser click @e3`, `fill @e5 "text"`, `type`, `press Enter` — act as a user would.
+   - `npx agent-browser wait --load networkidle`, `wait --text "Saved"`, `wait <selector>` — **after every action that triggers a request or opens a modal, wait before the next snapshot**; a snapshot taken too early is the usual false failure.
+   - `npx agent-browser screenshot <path>` — and look at the image yourself (open it with the Read tool). Layout, copy, empty states, and wrong-but-rendering are what a script cannot judge; that judgment is the point of this lane.
+   - `npx agent-browser errors`, `console`, `network requests` — after each step, not only at the end.
+3. **Click around beyond the happy path.** The obvious wrong input, the empty state, a reload, the back button. You are looking for what the ticket did not spell out.
+4. **The standard checks, every time:** no uncaught exceptions, no failed requests, the success state visible in a screenshot you looked at, the data still there after a reload.
+5. **Design:** compare the screen to a design only when the ticket or spec names one (a `docs/design/` handoff, a mockup). Never invent a comparison.
+
+## When something is wrong
+
+1. Fix it.
+2. Add the regression test at the **cheapest seam that would have caught it** — a unit or integration test first. A new Playwright spec under `tests/e2e/` only when the ticket asks for one or the behavior exists only in a real browser; the e2e lane stays thin, and a smoke never becomes a spec by default.
+3. Re-drive the steps that failed.
+
+## Done
+
+- `npx agent-browser close`, and stop the app you started: `kill $(cat .launchrail/state/dev.pid)`.
+- Your handoff states, in a few lines, what you drove and what you saw — that is the record. Nothing is committed for the smoke: no journeys file, no `artifacts/` bundle, no screenshots in the repo.
+- A smoke you could not drive is a failure, not a pass. Never report one you did not run.
+
+## Fallback — no driver
+
+If `agent-browser` cannot be installed here, write a throwaway `playwright-core` script under `.launchrail/state/` (gitignored) that drives the same steps and prints what it saw, and run it with the project's Playwright. It stays there — it never moves under `tests/`, and it is no substitute for looking at the screenshots.

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

@@ -24,7 +24,7 @@ From `.launchrail.yml`: `issueTracker` and the `testing` commands. From the argu
 
 ## Step 2 — Repair setup, don't gatekeep
 
-If the loop's materials are missing — `modules.ralph` off in the manifest, or `.claude/workflows/ralph.js` absent — run `npx @wemuda/launchrail sync` (additive and idempotent; its migration installs them) and say what it did. Never answer the user's "build this" with "first go run a command" for anything this skill can run itself. What you cannot repair, report precisely: no tracker configured (`issueTracker: none`), or an empty verification contract (no `testing` commands — `verify` fails on an empty contract and the loop refuses a start it cannot gate). An unset `testing.checkCommand` is not a gap — the fast gate falls back to the unit command — but say once that naming a quicker lint/typecheck/unit gate there makes every land cheaper.
+If the loop's materials are missing — `modules.ralph` off in the manifest, or `.claude/workflows/ralph.js` absent — run `npx @wemuda/launchrail sync` (additive and idempotent; its migration installs them) and say what it did. Never answer the user's "build this" with "first go run a command" for anything this skill can run itself. What you cannot repair, report precisely: no tracker configured (`issueTracker: none`), or an empty verification contract (no `testing` commands — `verify` fails on an empty contract and the loop refuses a start it cannot gate). An unset `testing.checkCommand` is not a gap — the fast gate falls back to the unit command — but when `doctor` warns on its `ralph …` readiness lines (fast gate, e2e specs, CI triggers, hosted setup, commands), say once that `/launch-loop-readiness` measures and fixes them, and proceed; readiness never gates a build.
 
 ## Step 3 — Route by scope
 
@@ -33,7 +33,7 @@ If the loop's materials are missing — `modules.ralph` off in the manifest, or
 **One ticket:** build it here, watchable, under the same contract a Ralph dispatch carries (kept textually parallel with `launch-ralph` — change one, change both). A single ticket has nothing to consolidate, so its base is the **default branch** and its one CI-gated PR merges there — consolidation-by-default is a multi-ticket policy (use a different base only if the user names one, or the session pins a designated branch — then that is the base). Two deliberate divergences from a loop dispatch: a single ticket's PR *is* the review checkpoint, so it keeps the PR and its cloud CI, and you are the session, not a subagent, so you run that merge gate yourself — waiting on CI here is fine:
 
 1. **Dependency gate:** every ticket on the `Blocked by:` line is closed with its work merged. An open blocker stops you before any code — name it and offer to build it first.
-2. Read the ticket and everything it links (spec sections, ADRs, journeys), plus `AGENTS.md`/`CLAUDE.md`.
+2. Read the ticket and everything it links (spec sections, ADRs, designs), plus `AGENTS.md`/`CLAUDE.md`.
 3. Label the ticket `ralph:building`; branch `ralph/<n>-<short-slug>` from a fresh sync of the base resolved above.
 4. Implement by calling the Skill tool with **`launch-ralph-implement`** — it owns TDD, the push cadence, the gates (the full `verify` before a PR of your own), browser smoke for user-facing changes, self-review, and commit conventions. Never paraphrase it inline.
 5. Pre-PR sync: merge the latest base; resolve conflicts by calling the Skill tool with `launch-resolving-merge-conflicts`; re-run the gate if anything changed.
@@ -44,6 +44,6 @@ If the loop's materials are missing — `modules.ralph` off in the manifest, or
 ## Ground rules
 
 - **Only the user starts this.** Conductors and other skills hand over the command (`/launch-implement`); they never invoke it. The engines behind it inherit the same rule — reaching them through this door *is* the explicit user start.
-- **Nothing is done until the gates are green** — `npx @wemuda/launchrail verify --fast` on every land, the full `npx @wemuda/launchrail verify` at the loop's checkpoints and once more on the final base when a run ends (and before a single ticket's PR). Where `modules.browser-testing` is enabled and the change is user-facing, a `launch-browser-smoke` journey is part of done.
+- **Nothing is done until the gates are green** — `npx @wemuda/launchrail verify --fast` on every land, the full `npx @wemuda/launchrail verify` at the loop's checkpoints and once more on the final base when a run ends (and before a single ticket's PR). Where `modules.browser-testing` is enabled and the change is user-facing, a `launch-browser-smoke` run — the change seen working in a real browser — is part of done.
 - **Report evidence, not assertions:** landing commits (PR numbers in single-ticket mode), issues closed, checkpoint and verify outcomes — and what was held, parked, or punted, with why.
 - **Every loop run ends with the campaign recap** (the `launch-ralph` close-out): where the work lives — target branch and head SHA — the ticket → landing-commit table, held, parked, and stuck tickets, punted follow-ups in one list, and the single next step. By default that step is *offering* the one release PR `<target> → <default>` (where cloud CI runs, once), opened only when the user says so; in the opt-in trunk mode it is nothing — every ticket is already live on the default branch. Under the recap, render the rail banner ([`workflow.md`](../launch/workflow.md)'s phase view) — Build done for this scope, verification/release as what remains — so even the build door closes with "where we are and where we're going".

package/assets/skills/launchrail/launch-loop-readiness/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: launch-loop-readiness
+description: Check and tune a repository for the implementation loop — measure the verification gates, then set the fast per-land gate, parallelize the e2e specs, share caches for parallel builders, narrow CI triggers, create the tracker labels, add hosted-session setup, and document the verbatim commands. Measured first, applied with one confirmation, never a gate on the rail. Run once before the first /launch-implement on an existing codebase, or whenever doctor's `ralph …` readiness lines warn.
+---
+
+# Loop readiness — tune the repo for the implementation loop
+
+The Ralph loop is only as fast as the repository lets it be. Every land runs the fast gate, every fifth land runs the full gate, every builder starts in a fresh worktree, every push can wake a CI runner, and a hosted session starts from an empty container. A repo tuned for humans typing `pnpm test` once an hour wastes tokens and wall-clock when three fresh-context builders hammer it all night. This skill measures that waste and removes it — without weakening a single test.
+
+It is advice, never a gate: `/launch-implement` runs whether or not this skill ever ran. `npx @wemuda/launchrail doctor` shows the same findings as warn-only `ralph …` lines; this skill is where they get fixed with numbers behind them.
+
+## Contract
+
+- **Measure before proposing.** Every finding carries a number — seconds cold, seconds warm, e2e spec count — from a run you made, not an estimate.
+- **Propose in impact order, with the expected saving**, then apply everything reversible in **one confirmation round** (the interaction contract in [`workflow.md`](../launch/workflow.md): reversible implementation details are yours, the user confirms only what touches their testing methodology — which e2e specs stay serial, what CI still runs).
+- **Never weaken coverage.** No deleted, skipped, or loosened tests; no lowered assertions; latency-sensitive e2e specs stay serial. Speed comes from tiering, parallelism, caching, and not running the same suite twice.
+- **Idempotent.** Re-running on a tuned repo reports "ready" and changes nothing.
+- **One commit** at the end, in the project's convention (`chore: tune the repo for the implementation loop`), listing what changed.
+
+## Step 1 — Inventory (read-only)
+
+1. `npx @wemuda/launchrail doctor` — collect every `ralph …` line; they are the deterministic half of this checklist.
+2. `.launchrail.yml` `testing.*` (unit, check, e2e, dev) and `AGENTS.md`'s Commands section: which commands exist verbatim, which are missing.
+3. The package manager and its install command (frozen-lockfile form); the scripts (`test`, `lint`, `typecheck`, `build`, `check`); the monorepo tool (turbo, nx, workspaces) and its cache configuration; the test runners and their configs (vitest/jest workers and cache, Playwright `workers`, `fullyParallel`, `projects`, `retries`).
+4. CI: every workflow's triggers and jobs; whether the required check is the same command the loop runs locally.
+5. Data: the migration tool and its generate/renumber command; whether tests need a database, ports, or external services, and how they isolate per run.
+6. Tracker: the labels the loop uses (`ready-for-agent`, `ralph:building`, `needs-info`, `spec`) exist — check with the tracker tools named in `docs/agents/issue-tracker.md`.
+7. `.claude/settings.json`: hooks (the Ralph guard, any `SessionStart`), permissions; the seeded `scripts/setup.mjs` when the browser-testing module is on.
+
+## Step 2 — Measure
+
+Run, and time, in this order — twice each, so cold and warm are both known:
+
+- `npx @wemuda/launchrail verify --fast` (the per-land gate).
+- `npx @wemuda/launchrail verify` (the checkpoint and release gate); note the per-package breakdown the runner prints and, with e2e specs, their count and their share of the time.
+- The install command in a fresh worktree (`git worktree add ../readiness-probe HEAD`, install, then remove it) — what every builder pays before its first test.
+
+Write the numbers down; they anchor every proposal and the closing card.
+
+## Step 3 — The catalogue
+
+Work through these; each names the check, the fix, and why it matters to the loop.
+
+1. **The fast gate** — `testing.checkCommand` unset, or slower than ~2 minutes warm. Set it to lint + typecheck + the unit suites without e2e specs (on turbo: `turbo run lint typecheck test --filter=!<web-package>` plus the web package's unit runner). Every land and every hand-off runs this; the e2e specs move to the checkpoints.
+2. **E2e specs** — a global `workers: 1` or `fullyParallel: false`. Split: a `serial` Playwright project holding the latency-asserting specs (matched by directory or a `@serial` tag) and a `parallel` project for the rest; run them as two invocations from the e2e command (`playwright test --project=parallel --workers=4 && playwright test --project=serial --workers=1`). Which specs are latency-sensitive is the user's call — ask with the list in hand. Target: the full suite in a fraction of its serial time with identical assertions.
+3. **Caches for parallel builders** — each builder starts in a fresh worktree with an empty cache. Enable the monorepo tool's shared cache: turbo remote cache, or `TURBO_CACHE_DIR` pointing at a path outside the worktree (persist it for hosted sessions via `$CLAUDE_ENV_FILE` in the SessionStart hook); a shared vitest `cacheDir`; the package manager's content-addressable store (pnpm has one by default). Unchanged packages then cost nothing at the builder's gate and at the lander's.
+4. **CI triggers** — a workflow that runs on every push. The loop pushes `ralph/*` on every green step and the integration branch on every land; each would start a run nobody waits on. Trigger on `pull_request` and pushes to the default branch only, and add a `concurrency` group with `cancel-in-progress` so a release PR's re-pushes do not queue behind each other. Cloud CI runs once, on the release PR — make sure the required check there is the same full gate the loop ran at release.
+5. **Tracker labels** — create any of `ready-for-agent`, `ralph:building`, `needs-info`, `spec` that are missing, with the descriptions from `docs/agents/issue-tracker.md`. A run refuses or mislabels without them.
+6. **Hosted-session setup** — no `SessionStart` hook. Hosted sessions (Claude Code on the web) start from a fresh container: add `.claude/hooks/session-start.sh` that exits early unless `$CLAUDE_CODE_REMOTE` is `true`, runs the install command, and — with the browser-testing module — `node scripts/setup.mjs` so the pinned browser build is present (a version mismatch here is a preflight refusal in the field). Register it additively under `hooks.SessionStart` in `.claude/settings.json` (merge; the Ralph guard's `PreToolUse` entry stays). Synchronous first; offer async mode only if the user wants faster session starts. Validate it once with `CLAUDE_CODE_REMOTE=true` before committing.
+7. **Verbatim commands** — `AGENTS.md`'s Commands section still holds the seeded TODO, or lacks any of install, fast gate, full gate, dev, and the migration generate/renumber command. Builders and the pre-land sync read these verbatim; fill them in from the inventory, and mirror the test ones into `.launchrail.yml` `testing.*`.
+8. **Test isolation for parallel builders** — fixed ports, a shared database or schema, temp files at fixed paths. Three builders run the suites at once on one machine: use ephemeral ports (`0`), per-run database names or schemas, and `os.tmpdir()`-based paths. A flake that only appears at width 3 is this.
+9. **Worktree hygiene** — configs or scripts that assume the checkout path (absolute paths, `..` walks out of the repo), generated files that are not ignored, install steps that write outside the repo. Builders work in `git worktree`s; anything path-bound breaks there first.
+10. **Unattended runs** — remind, once, that an unattended run launches in a non-prompting permission mode (the guard hook warns at launch), and that any MCP or CLI the loop needs (the tracker tools) must be reachable from the session that launches it.
+
+## Step 4 — Confirm, apply, re-measure
+
+Present the proposals as one list — finding, fix, expected saving — and ask one round of at most three questions, only about what needs the user's judgment (which e2e specs stay serial; whether CI may be narrowed; anything touching production or secrets). Then apply everything approved, run `doctor` again, re-run the Step 2 timings, and commit.
+
+## Step 5 — The readiness card
+
+Close with a card the user can act on without scrolling back:
+
+```
+Loop readiness — <project>
+Fast gate:   <before> → <after> (warm <n>s) · <command>
+Full gate:   <before> → <after> · e2e specs <n> (<parallel>/<serial>)
+Builder cold start: install <n>s · first fast gate <n>s
+Changed:  <one line per change, with the file>
+Left for you: <anything that needs a human — secrets, remote cache login, CI settings>
+```
+
+Then hand back: when reached through `launch`, close with the rail banner from [`workflow.md`](../launch/workflow.md) — stage 0 under Done, the next stage under Now.
+
+## What this skill does not do
+
+- It never starts the loop, and never blocks it — `/launch-implement` runs without it.
+- It never touches product artifacts (vision, specs, tickets) or the managed Launchrail files.
+- It never deletes, skips, or weakens a test, and never lowers an assertion to buy speed.
+- It never changes what CI verifies, only when it runs; a project's required checks stay required.

package/assets/skills/launchrail/launch-project-alignment/SKILL.md

@@ -39,7 +39,7 @@ How each Launchrail artifact shows up in an existing project, and what to do:
 | Architecture decisions (`docs/adr/`) | ADRs beyond the template; or de-facto decisions in code/docs | Note stage 6 as largely satisfied | Note as a gap; capture load-bearing existing decisions as ADRs later |
 | MVP spec (`docs/specs/`) | Spec docs, PRDs, design docs | Note stage 7 as partial/satisfied | Real gap — owned by the spec stage |
 | Tickets | The tracker in `.launchrail.yml` (issues/backlog) | Note stage 9 as partial | Real gap — owned by `launch-tickets` |
-| Verification | Test suite, CI config, Playwright | Wire `testing` commands in `.launchrail.yml`; note stage 11 partial | Note as a gap |
+| Verification | Test suite, CI config, Playwright | Wire `testing` commands in `.launchrail.yml`; note stage 11 partial; recommend `launch-loop-readiness` before the first `/launch-implement` — it measures the gates and tunes the repo for the loop | Note as a gap |
 
 ## What this skill does not do
 

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

@@ -58,7 +58,7 @@ Sync → compute frontier → keep *width* builders busy → land each finished
 Each implementer prompt is self-contained — assume it knows nothing about this session or the other implementers. It carries: the ticket number and title, the verbatim commands (install, fast gate, full gate), how to reach the tracker from this environment, which branch is the base (the integration target), any pushed branch to adopt, and these seven steps:
 
 1. **Dependency gate:** before anything else, confirm every ticket on the `Blocked by` line is closed with its work landed on the base. If any blocker is still open, do not build on a missing dependency — report "blocked" naming the open blocker, and stop. A deferral, not a failure; the loop retries after the blocker lands.
-2. Read the ticket and everything it links (spec sections, ADRs, journeys), plus `AGENTS.md`/`CLAUDE.md`. 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. If the ticket is already closed, report "already-done" and stop.
+2. Read the ticket and everything it links (spec sections, ADRs, designs), plus `AGENTS.md`/`CLAUDE.md`. 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. If the ticket is already closed, report "already-done" and stop.
 3. Label the ticket `ralph:building` so a lost session leaves a trace.
 4. **Branch and push immediately.** Adopt a pushed `ralph/<n>-*` branch when one exists (fetch it, continue from its last commit — never start over); otherwise branch from a fresh fetch of the base — `git checkout -b ralph/<n>-<short-slug> origin/<base>`, never a checkout of the base itself in the worktree — and push at once. From then on **commit and push after every green step**: the pushed branch is the checkpoint a lost session resumes from and the loop's liveness signal.
 5. Implement by calling the Skill tool with **`launch-ralph-implement`** — it owns TDD, the commit-and-push cadence, the fast gate, browser smoke for user-facing changes, self-review via `launch-code-review`, and commit conventions. Name the skill; do not paraphrase it.
@@ -81,7 +81,7 @@ A conflict, a gate that only fails on the merged tree, or a stale remote hands t
 
 ## Checkpoints and the repair
 
-After every `checkpointEvery` lands (default 5) — and always at release — run the **full gate** on the synced base, in the same checkout, with no land interleaved. Green → the base tip is proven; note the sha. Red → dispatch exactly one **repair** implementer with the failures and the tickets landed since the last green base; it branches `ralph/repair-*` from the base, fixes the root cause (an integration break between two tickets, a migration-number collision, a journey a landing invalidated), makes the fast *and* full gates green, pushes, and hands off; land it under the full gate. Landed → green again, carry on. Not landed → the base is red: stop landing, hold finished tickets on their branches, and end the run unverified naming the failure. A failure that reproduces on the base at preflight is systemic — stop the run before it starts.
+After every `checkpointEvery` lands (default 5) — and always at release — run the **full gate** on the synced base, in the same checkout, with no land interleaved. Green → the base tip is proven; note the sha. Red → dispatch exactly one **repair** implementer with the failures and the tickets landed since the last green base; it branches `ralph/repair-*` from the base, fixes the root cause (an integration break between two tickets, a migration-number collision, an e2e spec a landing invalidated), makes the fast *and* full gates green, pushes, and hands off; land it under the full gate. Landed → green again, carry on. Not landed → the base is red: stop landing, hold finished tickets on their branches, and end the run unverified naming the failure. A failure that reproduces on the base at preflight is systemic — stop the run before it starts.
 
 Every dispatch — retries, re-syncs, repairs included — also carries these two clauses verbatim:
 
@@ -117,9 +117,8 @@ When the Ralph loop runs as the `ralph` workflow instead of through this skill,
 When the frontier drains (or the cap, the build backstop, a red base, or a stop condition hits):
 
 1. Sync a fresh base and run `npx @wemuda/launchrail verify` — unless the last green checkpoint already proved this exact tip. **The loop may not report success while this fails** — report "unverified" with the failures instead; a red base is unverified by definition.
-2. If `.launchrail.yml` has `modules.browser-testing: true` and any landed ticket changed user-facing behavior, dispatch one smoke run per the `launch-browser-smoke` skill and reference its evidence bundle (`artifacts/verification/<run-id>/`).
-3. Prune the remote `ralph/*` branches of the verified-landed tickets — only those; held and parked branches stay.
-4. Report the campaign recap — it must let the user act without scrolling back:
+2. Prune the remote `ralph/*` branches of the verified-landed tickets — only those; held and parked branches stay.
+3. Report the campaign recap — it must let the user act without scrolling back:
    - **Where the work lives:** the integration target and its head SHA; in consolidation mode, say explicitly that the default branch is untouched.
    - The ticket → landing-commit table; held tickets with their branches; parked tickets with their failure histories; stuck tickets and what blocks them; the checkpoint verdicts.
    - Follow-ups and operator steps implementers punted, gathered into one list.
@@ -131,7 +130,7 @@ When the frontier drains (or the cap, the build backstop, a red base, or a stop
 - Fresh context per dispatch, per retry, per re-sync. No exceptions.
 - One integration target and one engine per run, declared in the pre-launch echo and restated once in the close-out recap — never in between.
 - Never implement, review, or repair code in the orchestrator session — dispatch instead. Landing is bookkeeping, not repair; a red gate is handed back, never fixed by the lander.
-- Name the skills (`launch-ralph-implement`, `launch-resolving-merge-conflicts`, `launch-browser-smoke`); never paraphrase their contents into a prompt.
+- Name the skills (`launch-ralph-implement`, `launch-resolving-merge-conflicts`); never paraphrase their contents into a prompt. The browser smoke is each implementer's, inside `launch-ralph-implement` — the loop dispatches no smoke run of its own.
 - Blocking edges are parsed from the verbatim `Blocked by` line, by you — never resolved by a model in between.
 - Nothing counts as landed until the remote says so; nothing counts as done until the full gate is green on the final base.
 - A deferral is not a failure; a re-sync is not an attempt; a failure is never silently retried without its summary.

package/assets/skills/launchrail/launch-ralph-implement/SKILL.md

@@ -7,12 +7,12 @@ description: Implement a single ticket end to end under the Launchrail completio
 
 The per-ticket implementation contract. Ralph dispatches name this skill so the contract lives in one place — every implementer, on every run, gets the same one.
 
-1. **Read before coding.** The ticket, every artifact it links (spec sections, ADRs, smoke journeys), and `AGENTS.md`/`CLAUDE.md`. The commands you run come from `.launchrail.yml` (`testing.*`) and `AGENTS.md`, verbatim.
+1. **Read before coding.** The ticket, every artifact it links (spec sections, ADRs, designs), and `AGENTS.md`/`CLAUDE.md`. The commands you run come from `.launchrail.yml` (`testing.*`) and `AGENTS.md`, verbatim.
 2. **Push early, push often.** Your branch is pushed before you write a line, and you **commit and push after every green step** — a passing test slice, a finished subtask. The pushed branch is the checkpoint a lost session resumes from (a successor adopts it at its last commit instead of rebuilding) and the loop's liveness signal. Work that is not on the remote does not exist to the next session. Never push to the base branch and never open a PR from inside a loop dispatch — the loop lands your branch.
 3. **TDD at the seams the ticket names.** Write the failing test first where the ticket or spec defines behavior. Typecheck and run single test files as you go; save whole-suite runs for the gate — the machine may be shared with other implementers.
-4. **The gate — tiered.** Before you hand off, `npx @wemuda/launchrail verify --fast` (the fast gate: `testing.checkCommand`, else the unit command) must exit 0 on your branch. Inside a Ralph dispatch that is your gate: the loop runs it again on the merged tree before pushing the base, and runs the full `npx @wemuda/launchrail verify` (browser journeys included) at its checkpoints — so do not spend your turn on the whole suite; run only the slow test files your change touches (a journey you edited). Outside the loop (single-ticket mode, a PR of your own), the full `npx @wemuda/launchrail verify` must exit 0 before the PR. Never delete, skip, or weaken a test to get there; if a test is genuinely wrong, fix it deliberately and say so in the commit message.
-5. **User-facing behavior, with `modules.browser-testing` enabled:** update or add the affected journey in `docs/testing/smoke-journeys.md` and drive it per the `launch-browser-smoke` skill. A journey you could not complete is a failure, not a pass.
+4. **The gate — tiered.** Before you hand off, `npx @wemuda/launchrail verify --fast` (the fast gate: `testing.checkCommand`, else the unit command) must exit 0 on your branch. Inside a Ralph dispatch that is your gate: the loop runs it again on the merged tree before pushing the base, and runs the full `npx @wemuda/launchrail verify` (e2e specs included) at its checkpoints — so do not spend your turn on the whole suite; run only the slow test files your change touches (an e2e spec you edited). Outside the loop (single-ticket mode, a PR of your own), the full `npx @wemuda/launchrail verify` must exit 0 before the PR. Never delete, skip, or weaken a test to get there; if a test is genuinely wrong, fix it deliberately and say so in the commit message.
+5. **User-facing behavior, with `modules.browser-testing` enabled:** drive the change in a real browser per the `launch-browser-smoke` skill — a one-off check of what you built, its steps taken from the ticket's acceptance criteria, ending in your handoff's few lines on what you drove and saw. No journeys file, no evidence bundle, no spec written from it; a regression test for anything it finds goes at the cheapest seam that catches it. A smoke you could not drive is a failure, not a pass.
 6. **Self-review:** call the Skill tool with `launch-code-review` on the result and fix what it finds before handing off.
-7. **Commit to the current branch** following the project's commit conventions (Conventional Commits when `.launchrail.yml` says so); the loop squashes your branch onto the base, so also hand it a Conventional Commit title for that squash. Update any artifact the change invalidates (spec, ADR, journey) in the same change.
+7. **Commit to the current branch** following the project's commit conventions (Conventional Commits when `.launchrail.yml` says so); the loop squashes your branch onto the base, so also hand it a Conventional Commit title for that squash. Update any artifact the change invalidates (spec, ADR, design note) in the same change.
 
-Done means: the gate is green, the review found nothing unaddressed, the branch is pushed, and the evidence (test output, journey results) exists — not that the code "should work".
+Done means: the gate is green, the review found nothing unaddressed, the branch is pushed, and the evidence (test output, the smoke's verdict) exists — not that the code "should work".

package/dist/commands/add.js

@@ -1,7 +1,7 @@
 import { readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import * as p from "@clack/prompts";
-import { BROWSER_TESTING_MODULE, browserTestingFiles } from "../lib/browser-testing.js";
+import { BROWSER_DRIVER_PACKAGE, BROWSER_TESTING_MODULE, browserTestingFiles } from "../lib/browser-testing.js";
 import { applyRalphGuardHook, CLAUDE_SETTINGS_PATH, planRalphGuardHook, } from "../lib/claudeSettings.js";
 import { detectRepo } from "../lib/detect.js";
 import { emptyLockfile, readLockfile, writeLockfile } from "../lib/lockfile.js";
@@ -24,7 +24,6 @@ function defaultAnswers(manifest, detection) {
         appUrl: manifest.testing.appUrl ?? "http://localhost:3000",
         devCommand: manifest.testing.devCommand ?? (detection.devScript ? `${pm} run dev` : null),
         e2eCommand: manifest.testing.e2eCommand ?? "npx playwright test",
-        smokeCommand: manifest.testing.smokeCommand ?? "node scripts/smoke.mjs",
     };
 }
 async function interview(defaults) {
@@ -43,10 +42,6 @@ async function interview(defaults) {
             message: "Deterministic browser-test command",
             initialValue: defaults.e2eCommand,
         }),
-        smokeCommand: () => p.text({
-            message: "Smoke entry command",
-            initialValue: defaults.smokeCommand,
-        }),
     }, {
         onCancel: () => {
             p.cancel("Cancelled — nothing was written.");
@@ -57,7 +52,6 @@ async function interview(defaults) {
         appUrl: answers.appUrl.trim() || defaults.appUrl,
         devCommand: answers.devCommand.trim() === "" ? null : answers.devCommand.trim(),
         e2eCommand: answers.e2eCommand.trim() || defaults.e2eCommand,
-        smokeCommand: answers.smokeCommand.trim() || defaults.smokeCommand,
     };
 }
 function planBrowserTesting(parsed, detection, answers) {
@@ -70,11 +64,13 @@ function planBrowserTesting(parsed, detection, answers) {
     if (detection.playwrightConfigFile) {
         notes.push(`Existing ${detection.playwrightConfigFile} detected — keeping it; no config or baseline spec seeded.`);
     }
-    const nextSteps = ["Run `node scripts/setup.mjs` — installs @playwright/test and browser binaries."];
+    const nextSteps = [
+        `Run \`node scripts/setup.mjs\` — installs @playwright/test, ${BROWSER_DRIVER_PACKAGE} (the browser smoke's driver) and their browsers.`,
+    ];
     if (!answers.devCommand) {
         nextSteps.push("Set the dev command: edit scripts/dev.mjs (DEV_COMMAND) and testing.devCommand in .launchrail.yml.");
     }
-    nextSteps.push("Review the seeded files — they are yours: playwright config, tests/e2e/, docs/testing/smoke-journeys.md, .mcp.json.", "In Claude Code, approve the seeded Playwright MCP (.mcp.json) for agent-driven browser journeys; where no MCP is available (e.g. headless CI), the seeded Playwright scripts still run.", "Verify: `node scripts/verify.mjs`, then `npx @wemuda/launchrail smoke` with the app running.");
+    nextSteps.push("Review the seeded files — they are yours: playwright config, tests/e2e/baseline.spec.ts, scripts/.", "Verify: `node scripts/verify.mjs` runs the deterministic gate (unit + the e2e baseline).", "Browser smoke: after building user-facing behavior, the launch-browser-smoke skill drives the running app with agent-browser — a one-off check of the change, not a test suite (ADR-0034).");
     return {
         manifest,
         testing: { ...answers },
@@ -107,7 +103,7 @@ function planRalph(parsed) {
             "Produce tickets with explicit `Blocked by: #n` edges and the ready-for-agent label (launch-tickets, stage 9 of the workflow).",
             "Start building: /launch-implement in Claude Code drives the ready tickets to verified merges (add a ticket number to build just one).",
             "For an unattended run, launch in a non-prompting permission mode (bypass/autonomous) — a guard hook warns if you start Ralph in an interactive mode, since one benign prompt can stall a walk-away run.",
-            "Name a fast gate as testing.checkCommand in .launchrail.yml (lint + typecheck + quick unit tests) — the loop runs `verify --fast` before every land and the full `verify` at its checkpoints; without it the fast gate is the unit command.",
+            "Tune the repo for the loop: run /launch-loop-readiness in Claude Code — it measures the gates, sets testing.checkCommand (the fast per-land gate; without it the fast gate is the unit command), parallelizes the e2e specs, narrows CI triggers, creates the tracker labels, and adds hosted-session setup. `doctor` shows the same readiness lines.",
             "Start with width 1 until a few tickets have landed cleanly, then widen.",
         ],
     };