@wemuda/launchrail 1.6.0 → 1.8.0

package/README.md

@@ -9,7 +9,7 @@
 **An updatable development system for taking a software idea from product intent to a verified release.**
 
 [![CI](https://github.com/wemuda/launchrail/actions/workflows/ci.yml/badge.svg)](https://github.com/wemuda/launchrail/actions/workflows/ci.yml)
-[![Status: pre-release](https://img.shields.io/badge/status-pre--release-orange)](https://github.com/wemuda/launchrail/blob/master/ROADMAP.md)
+[![Release](https://img.shields.io/github/v/release/wemuda/launchrail?label=release&color=2088FF)](https://github.com/wemuda/launchrail/releases)
 [![Node >= 22](https://img.shields.io/badge/node-%E2%89%A522-339933?logo=node.js&logoColor=white)](https://github.com/wemuda/launchrail/blob/master/package.json)
 [![pnpm workspace](https://img.shields.io/badge/pnpm-workspace-F69220?logo=pnpm&logoColor=white)](https://github.com/wemuda/launchrail/blob/master/pnpm-workspace.yaml)
 [![Conventional Commits](https://img.shields.io/badge/commits-conventional-FE5196?logo=conventionalcommits&logoColor=white)](https://github.com/wemuda/launchrail/blob/master/docs/adr/0002-conventional-commits.md)
@@ -18,9 +18,9 @@
 [How it works](#how-it-works) ·
 [Getting started](https://github.com/wemuda/launchrail/blob/master/docs/getting-started.md) ·
 [Using it](#using-it-in-your-project) ·
+[Updating](#updating-a-project) ·
 [Ownership model](#the-ownership-model) ·
 [Repository layout](#repository-layout) ·
-[Roadmap](https://github.com/wemuda/launchrail/blob/master/ROADMAP.md) ·
 [Contributing](#contributing) ·
 [Credits](#credits)
 
@@ -28,21 +28,19 @@
 
 ---
 
-> **Status:** Pre-release. All six roadmap phases are implemented; nothing is published to npm yet.
-
-This repository is the Launchrail **toolchain**: the CLI, Claude Code plugin, templates, and migrations that initialize other repositories and keep them current. It is not an application framework and it does not replace Claude Code, Claude Design, [Matt Pocock's skills](https://github.com/mattpocock/skills), GitHub, Playwright, or a project's chosen stack. It is the shared rail that connects them.
+This repository is the Launchrail **toolchain**: the CLI, the workflow skills (shipped into projects as files), templates, and migrations that initialize other repositories and keep them current. It is not an application framework and it does not replace Claude Code, Claude Design, GitHub, Playwright, or a project's chosen stack. It is the shared rail that connects them.
 
 ## How it works
 
-Launchrail structures development as two movements. The **foundation** runs once per project: it turns an idea into hard constraints and recorded decisions. Then the **delivery loop** takes over — once per feature: size the work and plan it only as deeply as it needs (a small change goes straight from a grill to tickets; a larger one adds `wayfinder`, a spec, and design validation first), then hand the tickets to the **Ralph loop** to implement and verify before going around again for the next feature. Every stage leaves a committed artifact behind, and the next stage starts from that artifact, not from chat memory. The `launch` skill is the single entry point: it reads the committed artifacts, detects where the project is, and routes to the stage's owner.
+Launchrail structures development as two movements. The **foundation** runs once per project: it turns an idea into hard constraints and recorded decisions. Then the **delivery loop** takes over — once per feature: size the work and plan it only as deeply as it needs (a small change goes straight from a grill to tickets; a larger one adds `launch-wayfinder`, a spec, and design validation first), then hand the tickets to the built-in **Ralph loop** to implement and verify before going around again for the next feature. Every stage leaves a committed artifact behind, and the next stage starts from that artifact, not from chat memory. Two commands cover the rail: **`/launch`** plans — it reads the committed artifacts, detects where the project is, and routes to the stage's owner — and **`/launch-implement`** builds, driving ready tickets to verified merges.
 
 <p align="center">
-  <img src="https://github.com/wemuda/launchrail/raw/master/assets/how-launchrail-works.png" alt="How Launchrail works — the foundation runs once per project (Vision → Visual exploration → Complexity grill → Technical research → Architecture decisions); the delivery loop then repeats once per slice (Specify features into tickets → Ralph loop → Verification) before looping back for the next slice." width="880" />
+  <img src="https://github.com/wemuda/launchrail/raw/master/assets/how-launchrail-works.png" alt="How Launchrail works — the foundation runs once per project (Vision → Visual exploration → Discovery research → Complexity grill → Technical research → Architecture decisions); the delivery loop then repeats once per slice (Specify features into tickets → Ralph loop → Verification) before looping back for the next slice." width="880" />
 </p>
 
-Several stages run directly on [Matt Pocock's skills](https://github.com/mattpocock/skills) — see [Credits](#credits). The full stage contract — inputs, artifacts, composition rules, and per-mode rigor — lives in [the workflow doc](https://github.com/wemuda/launchrail/blob/master/plugins/launchrail/docs/workflow.md).
+The skills are Launchrail's own complete, `launch-*` prefixed set ([ADR-0020](https://github.com/wemuda/launchrail/blob/master/docs/adr/0020-independent-skill-set.md)); the methodology of several stages is inspired by [Matt Pocock's skills](https://github.com/mattpocock/skills) — see [Credits](#credits). The full stage contract — inputs, artifacts, composition rules, and per-mode rigor — lives in [the workflow doc](https://github.com/wemuda/launchrail/blob/master/packages/cli/assets/skills/launchrail/launch/workflow.md).
 
-What makes projects **updatable** instead of copy-once-and-rot is the second half of the system: shared capabilities are *subscribed to*, shared standards are *synchronized*, product knowledge stays *locally owned*, and reusable lessons are *deliberately promoted upstream*.
+What makes projects **updatable** instead of copy-once-and-rot is the second half of the system: shared capabilities are *shipped as managed files and kept current on `sync`*, shared standards are *synchronized*, product knowledge stays *locally owned*, and reusable lessons are *deliberately promoted upstream*.
 
 ## Using it in your project
 
@@ -52,14 +50,16 @@ One command sets the rails:
 npx @wemuda/launchrail init
 ```
 
-`init` interviews you (or takes `--yes`), runs `git init` if the directory isn't a repository yet, seeds `AGENTS.md` and ADR conventions without touching existing content, subscribes the repository to the workflow's Claude Code plugins through `.claude/settings.json` — so every collaborator who opens the project in Claude Code gets the same skills — and, when the `claude` CLI is on your PATH, installs those plugins for you on the spot — Launchrail's own and Matt Pocock's skills ([ADR-0011](https://github.com/wemuda/launchrail/blob/master/docs/adr/0011-init-installs-plugin-via-claude-cli.md)). Adopting an existing project is a first-class path: your files are kept, and a `CLAUDE.md` you already have is additively wired to the workflow imports rather than replaced ([ADR-0012](https://github.com/wemuda/launchrail/blob/master/docs/adr/0012-init-wires-imports-into-existing-claude-md.md)). The interview asks whether the project is new or existing and records it as the manifest's `origin`; for an existing project, `launch` takes an **alignment on-ramp** — inferring a draft vision from the code, interviewing only the gaps, and inventorying your existing design system — instead of starting from a blank vision ([ADR-0013](https://github.com/wemuda/launchrail/blob/master/docs/adr/0013-existing-project-alignment.md)).
+`init` interviews you (or takes `--yes`), runs `git init` if the directory isn't a repository yet, seeds `AGENTS.md` and ADR conventions without touching existing content, and writes the workflow's skills into `.claude/skills/` as managed files — so every collaborator, and every session whether cloud or local, gets the same skills with no plugin to install, on any agent that reads the repo ([ADR-0019](https://github.com/wemuda/launchrail/blob/master/docs/adr/0019-vendor-skills-retire-plugin.md)). Adopting an existing project is a first-class path: your files are kept, and a `CLAUDE.md` you already have is additively wired to the workflow imports rather than replaced ([ADR-0012](https://github.com/wemuda/launchrail/blob/master/docs/adr/0012-init-wires-imports-into-existing-claude-md.md)). The interview asks whether the project is new or existing and records it as the manifest's `origin`; for an existing project, `launch` takes an **alignment on-ramp** — inferring a draft vision from the code, interviewing only the gaps, and inventorying your existing design system — instead of starting from a blank vision ([ADR-0013](https://github.com/wemuda/launchrail/blob/master/docs/adr/0013-existing-project-alignment.md)).
 
-From there, the day-to-day driver is not the CLI — it's the **`launch` skill** inside Claude Code: open the project and run `/launchrail:launch`. Invoke it (or just ask "what's next?") and it reads your committed artifacts, works out where the project is — no vision yet, mid-grill, spec validated, tickets ready — and runs or routes to the next stage's owner. Give it a stage name (`launch design-validation`) to jump straight there. The plugin carries the rest of the workflow too:
+From there, the day-to-day driver is not the CLI — it's the **`launch` skill** inside Claude Code: open the project and run `/launch`. Invoke it (or just ask "what's next?") and it reads your committed artifacts, works out where the project is — no vision yet, mid-grill, spec validated, tickets ready — and runs or routes to the next stage's owner. Give it a stage name (`launch design-validation`) to jump straight there. The skills carry the rest of the workflow too:
 
-- **`project-alignment`** — the on-ramp for an existing codebase: infer a vision from the code, interview only the gaps, inventory the design system, then join the loop
-- **`vision-creation`** and **`design-validation`** — the Launchrail-owned stages of the pipeline
-- **`browser-smoke`** — drives a real browser journey and leaves a traceable evidence bundle (with the browser-testing module)
-- **`ralph`**, **`ralph-implement`**, **`resolving-merge-conflicts`** — the verification-gated implementation loop (with the ralph module)
+- **`launch-project-alignment`** — the on-ramp for an existing codebase: infer a vision from the code, interview only the gaps, inventory the design system, then join the loop
+- **`launch-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-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`
 
 The CLI is the maintenance surface you return to between sessions:
 
@@ -67,7 +67,7 @@ The CLI is the maintenance surface you return to between sessions:
 npx @wemuda/launchrail status                # versions, drift, pending migrations
 npx @wemuda/launchrail diff                  # preview upstream changes
 npx @wemuda/launchrail sync                  # apply managed updates + run migrations
-npx @wemuda/launchrail add browser-testing   # enable a module (also: add ralph)
+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
@@ -76,6 +76,24 @@ npx @wemuda/launchrail eject <module|file>   # opt out of management (vendor mod
 
 Initialized projects carry two files: `.launchrail.yml` (configuration) and `.launchrail-lock.json` (versions, checksums, applied migrations; committed to the repo). Full walkthrough: [docs/getting-started.md](https://github.com/wemuda/launchrail/blob/master/docs/getting-started.md). Committed, unedited example of what `init` produces: [examples/hello-launchrail](https://github.com/wemuda/launchrail/tree/master/examples/hello-launchrail).
 
+## Updating a project
+
+New Launchrail release out? Two steps, from the project root:
+
+**1. Sync the project files** — applies the release's managed files (the workflow skills included) and migrations; your own files are never touched:
+
+```bash
+npx -y @wemuda/launchrail@latest sync
+```
+
+**2. Commit the result:**
+
+```bash
+git add -A && git commit -m "chore: sync launchrail"
+```
+
+Done — the skills update *with* the files in one `sync` (no separate plugin step, and teammates just `git pull`), and the next `/launch` runs with everything the release added (the [CHANGELOG](https://github.com/wemuda/launchrail/blob/master/CHANGELOG.md) says what that is). Keep the `@latest`: `npx` caches, and a stale cached CLI reports "everything up to date" against old templates. Want to see the changes before applying? `npx -y @wemuda/launchrail@latest diff` — read-only, like `status` and `sync --dry-run`. The why and the edge cases — ordering, conflicts, migrations — live in [docs/getting-started.md](https://github.com/wemuda/launchrail/blob/master/docs/getting-started.md#updating-to-a-new-release).
+
 ## The ownership model
 
 Every file Launchrail touches in a consuming project belongs to exactly one class — and no feature is allowed to blur the lines:
@@ -95,10 +113,7 @@ launchrail/
 ├── assets/                  # Logo and other repo media
 ├── packages/
 │   └── cli/                 # @wemuda/launchrail — the npx entry point
-├── plugins/
-│   └── launchrail/          # Claude Code plugin (skills, commands, agents, hooks)
-├── .claude-plugin/
-│   └── marketplace.json     # Claude Code plugin marketplace manifest
+│       └── assets/skills/   # The workflow skills: launchrail/ (the complete launch-* set) + NOTICE.md (attribution)
 ├── templates/               # Files seeded into consuming projects (added as built)
 ├── examples/
 │   └── hello-launchrail/    # Committed, unedited output of `launchrail init` on a tiny app
@@ -120,9 +135,9 @@ pnpm build
 pnpm --filter @wemuda/launchrail exec launchrail --help
 ```
 
-## Roadmap
+## Status
 
-See [ROADMAP.md](https://github.com/wemuda/launchrail/blob/master/ROADMAP.md), a living checklist of what exists, what's in progress, and what's missing. All six phases — `init` + `doctor`, the core workflow plugin, browser testing, Ralph orchestration, the sync engine, and open-source readiness — are implemented and covered by 164 tests. The Ralph loop has run for real against a Wemuda project, and its lessons are folded back into the toolchain (ADR-0010). What stands between here and a first release: the dogfood case study on a real project and flipping on the npm publish.
+The toolchain is stable and versioned. The full surface — `init`/`doctor`, the workflow skills, browser testing, the Ralph loop, and the sync engine — is covered by the test suite, including integration tests against real temporary Git repositories. Releases are automated: Conventional Commits drive release-please, and the changelog is generated from the commit history ([ADR-0008](https://github.com/wemuda/launchrail/blob/master/docs/adr/0008-release-automation.md), [docs/releasing.md](https://github.com/wemuda/launchrail/blob/master/docs/releasing.md)). The CLI is published to npm as [`@wemuda/launchrail`](https://www.npmjs.com/package/@wemuda/launchrail). Shipped history lives in [CHANGELOG.md](https://github.com/wemuda/launchrail/blob/master/CHANGELOG.md).
 
 ## Contributing
 
@@ -135,7 +150,7 @@ See [CONTRIBUTING.md](https://github.com/wemuda/launchrail/blob/master/CONTRIBUT
 
 ## Credits
 
-Launchrail doesn't reinvent a workflow — it composes one, and much of that workflow is [**Matt Pocock**](https://www.mattpocock.com/)'s. Four stages of the pipeline (complexity grill, technical research, MVP specification, tickets) run directly on his [`skills`](https://github.com/mattpocock/skills) repository — `grill-with-docs`, the research skill, `wayfinder`/`to-spec`, and `to-tickets`. Launchrail exists to wire those skills into a repo cleanly and keep them updatable, not to replace them.
+Launchrail's skill set is its own, but much of its methodology traces to [**Matt Pocock**](https://www.mattpocock.com/). The grill, research, wayfinding, spec, ticket, and code-review stages absorb the shape — and, in places, the MIT-licensed text — of his [`skills`](https://github.com/mattpocock/skills) repository ([ADR-0020](https://github.com/wemuda/launchrail/blob/master/docs/adr/0020-independent-skill-set.md)); the derived skills carry the attribution in `NOTICE.md`, and upstream is monitored so improvements there keep informing the rail.
 
 If Launchrail is useful to you, the credit belongs upstream first: star [`mattpocock/skills`](https://github.com/mattpocock/skills), watch [Matt's YouTube channel](https://www.youtube.com/@mattpocockuk), follow [@mattpocockuk on X](https://x.com/mattpocockuk), and check out [AI Hero](https://www.aihero.dev/).
 

package/assets/agents-docs/domain.md

@@ -0,0 +1,59 @@
+<!--
+  Seeded by `launchrail init`. This file is yours — edit it freely; Launchrail never overwrites it.
+  Contains text derived from Matt Pocock's skills (MIT): https://github.com/mattpocock/skills
+-->
+
+# Domain Docs
+
+How the workflow skills should consume this repo's domain documentation when exploring the codebase.
+
+## Before exploring, read these
+
+- **`CONTEXT.md`** at the repo root, or
+- **`CONTEXT-MAP.md`** at the repo root if it exists — it points at one `CONTEXT.md` per context. Read each one relevant to the topic.
+- **`docs/adr/`** — read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.
+
+If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `launch-grill` skill's domain-modeling discipline creates them lazily when terms or decisions actually get resolved.
+
+## File structure
+
+Single-context repo (most repos):
+
+```
+/
+├── CONTEXT.md
+├── docs/adr/
+│   ├── 0000-template.md
+│   ├── 0001-event-sourced-orders.md
+│   └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+Multi-context repo (presence of `CONTEXT-MAP.md` at the root):
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/adr/                          ← system-wide decisions
+└── src/
+    ├── ordering/
+    │   ├── CONTEXT.md
+    │   └── docs/adr/                  ← context-specific decisions
+    └── billing/
+        ├── CONTEXT.md
+        └── docs/adr/
+```
+
+ADRs use the project's own format — copy `docs/adr/0000-template.md` and number sequentially (`NNNN-short-slug.md`).
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.
+
+If the concept you need isn't in the glossary yet, that's a signal — either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for the next grill session).
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
+
+> _Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…_

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

@@ -0,0 +1,51 @@
+<!--
+  Seeded by `launchrail init` from `.launchrail.yml` (issueTracker: github).
+  This file is yours — edit it freely; Launchrail never overwrites it.
+  Contains text derived from Matt Pocock's skills (MIT): https://github.com/mattpocock/skills
+-->
+
+# Issue tracker: GitHub
+
+Issues and specs for this repo live as GitHub issues. Use the `gh` CLI for all operations.
+
+## Conventions
+
+- **Create an issue**: `gh issue create --title "..." --body "..."`. Use a heredoc for multi-line bodies.
+- **Read an issue**: `gh issue view <number> --comments`, filtering comments by `jq` and also fetching labels.
+- **List issues**: `gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'` with appropriate `--label` and `--state` filters.
+- **Comment on an issue**: `gh issue comment <number> --body "..."`
+- **Apply / remove labels**: `gh issue edit <number> --add-label "..."` / `--remove-label "..."`
+- **Close**: `gh issue close <number> --comment "..."`
+
+Infer the repo from `git remote -v` — `gh` does this automatically when run inside a clone.
+
+GitHub shares one number space across issues and PRs, so a bare `#42` may be either — resolve with `gh pr view 42` and fall back to `gh issue view 42`.
+
+## Labels
+
+The Launchrail workflow's label vocabulary — the skills quote these exact strings:
+
+- **`ready-for-agent`** — an implementable ticket the implementation loop may pick up. Only tickets wear it; the loop's frontier is computed from this label alone and cannot tell prose from work.
+- **`needs-info`** — a parked ticket, carrying its failure history; a human unblocks it.
+- **`spec`** — a spec or research note published to the tracker. Never `ready-for-agent`.
+- **`ralph:building`** — claimed by an implementer; removed when its PR merges.
+- **`wayfinder:map`** / **`wayfinder:<type>`** — a wayfinder map and its decision tickets (see below).
+
+## When a skill says "publish to the issue tracker"
+
+Create a GitHub issue.
+
+## When a skill says "fetch the relevant ticket"
+
+Run `gh issue view <number> --comments`.
+
+## Wayfinding operations
+
+Used by `launch-wayfinder`. The **map** is a single issue with **child** issues as tickets.
+
+- **Map**: a single issue labelled `wayfinder:map`, holding the Notes / Decisions-so-far / Fog body. `gh issue create --label wayfinder:map`.
+- **Child ticket**: an issue linked to the map as a GitHub sub-issue (`gh api` on the sub-issues endpoint). Where sub-issues aren't enabled, add the child to a task list in the map body and put `Part of #<map>` at the top of the child body. Labels: `wayfinder:<type>` (`research`/`prototype`/`grilling`/`task`). Once claimed, the ticket is assigned to the driving dev.
+- **Blocking**: GitHub's **native issue dependencies** — the canonical, UI-visible representation. Add an edge with `gh api --method POST repos/<owner>/<repo>/issues/<child>/dependencies/blocked_by -F issue_id=<blocker-db-id>`, where `<blocker-db-id>` is the blocker's numeric **database id** (`gh api repos/<owner>/<repo>/issues/<n> --jq .id`, _not_ the `#number` or `node_id`). GitHub reports `issue_dependencies_summary.blocked_by` (open blockers only — the live gate). Where dependencies aren't available, fall back to a `Blocked by: #<n>, #<n>` line at the top of the child body. A ticket is unblocked when every blocker is closed.
+- **Frontier query**: list the map's open children (`gh issue list --state open`, scoped to the map's sub-issues / task list), drop any with an open blocker (`issue_dependencies_summary.blocked_by > 0`, or an open issue in the `Blocked by` line) or an assignee; first in map order wins.
+- **Claim**: `gh issue edit <n> --add-assignee @me` — the session's first write.
+- **Resolve**: `gh issue comment <n> --body "<answer>"`, then `gh issue close <n>`, then append a context pointer (gist + link) to the map's Decisions-so-far.

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

@@ -0,0 +1,52 @@
+<!--
+  Seeded by `launchrail init` from `.launchrail.yml` (issueTracker: gitlab).
+  This file is yours — edit it freely; Launchrail never overwrites it.
+  Contains text derived from Matt Pocock's skills (MIT): https://github.com/mattpocock/skills
+-->
+
+# Issue tracker: GitLab
+
+Issues and specs for this repo live as GitLab issues. Use the [`glab`](https://gitlab.com/gitlab-org/cli) CLI for all operations.
+
+## Conventions
+
+- **Create an issue**: `glab issue create --title "..." --description "..."`. Use a heredoc for multi-line descriptions. Pass `--description -` to open an editor.
+- **Read an issue**: `glab issue view <number> --comments`. Use `-F json` for machine-readable output.
+- **List issues**: `glab issue list -F json` with appropriate `--label` filters.
+- **Comment on an issue**: `glab issue note <number> --message "..."`. GitLab calls comments "notes".
+- **Apply / remove labels**: `glab issue update <number> --label "..."` / `--unlabel "..."`. Multiple labels can be comma-separated or by repeating the flag.
+- **Close**: `glab issue close <number>`. `glab issue close` does not accept a closing comment, so post the explanation first with `glab issue note <number> --message "..."`, then close.
+- **Merge requests**: GitLab calls PRs "merge requests". Use `glab mr create`, `glab mr view`, `glab mr note`, etc. — the same shape as `gh pr ...` with `mr` in place of `pr` and `note`/`--message` in place of `comment`/`--body`.
+
+Infer the repo from `git remote -v` — `glab` does this automatically when run inside a clone.
+
+Unlike GitHub, GitLab numbers issues and MRs separately, so `#42` is unambiguous once you know which surface is meant.
+
+## Labels
+
+The Launchrail workflow's label vocabulary — the skills quote these exact strings:
+
+- **`ready-for-agent`** — an implementable ticket the implementation loop may pick up. Only tickets wear it; the loop's frontier is computed from this label alone and cannot tell prose from work.
+- **`needs-info`** — a parked ticket, carrying its failure history; a human unblocks it.
+- **`spec`** — a spec or research note published to the tracker. Never `ready-for-agent`.
+- **`ralph:building`** — claimed by an implementer; removed when its MR merges.
+- **`wayfinder:map`** / **`wayfinder:<type>`** — a wayfinder map and its decision tickets (see below).
+
+## When a skill says "publish to the issue tracker"
+
+Create a GitLab issue.
+
+## When a skill says "fetch the relevant ticket"
+
+Run `glab issue view <number> --comments`.
+
+## Wayfinding operations
+
+Used by `launch-wayfinder`. The **map** is a single issue with **child** issues as tickets.
+
+- **Map**: a single issue labelled `wayfinder:map`, holding the Notes / Decisions-so-far / Fog body. `glab issue create --label wayfinder:map`. (On GitLab tiers with native epics, an epic may hold the map instead; a labelled issue works everywhere.)
+- **Child ticket**: an issue carrying `Part of #<map>` at the top of its description and labels `wayfinder:<type>` (`research`/`prototype`/`grilling`/`task`). Once claimed, the ticket is assigned to the driving dev.
+- **Blocking**: GitLab's **native blocking link** — the canonical, UI-visible representation. Add it with the `/blocked_by #<n>` quick action, posted as a note (`glab issue note <child> --message "/blocked_by #<blocker>"`). Native blocking links are a Premium/Ultimate feature; on the free tier (or where unavailable) fall back to a `Blocked by: #<n>, #<n>` line at the top of the description. A ticket is unblocked when every blocker is closed.
+- **Frontier query**: `glab issue list -F json` scoped to the map's children, drop any with an open blocker — a native `blocked_by` link to an open issue (`glab api projects/:id/issues/:iid/links`), or an open issue in the `Blocked by` line — or an assignee; first in map order wins.
+- **Claim**: `glab issue update <n> --assignee @me` — the session's first write.
+- **Resolve**: `glab issue note <n> --message "<answer>"`, then `glab issue close <n>`, then append a context pointer (gist + link) to the map's Decisions-so-far.

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

@@ -0,0 +1,52 @@
+<!--
+  Seeded by `launchrail init` from `.launchrail.yml` (issueTracker: linear).
+  This file is yours — edit it freely; Launchrail never overwrites it.
+-->
+
+# Issue tracker: Linear
+
+Issues and specs for this repo live in Linear. Use the **Linear MCP server's tools** when the session has them (tool names like `mcp__Linear__save_issue`, `mcp__Linear__list_issues`); otherwise say so and hand the operation to the user rather than guessing at an API.
+
+Fill in the team/project so agents don't have to ask:
+
+- **Team**: _(e.g. `ENG` — the team whose backlog this repo's tickets live in)_
+- **Project**: _(optional — a Linear project to attach workflow-created issues to)_
+
+## Conventions
+
+- **Create an issue**: `save_issue` with title, markdown description, team, and labels.
+- **Read an issue**: `get_issue` (by identifier like `ENG-123`), plus `list_comments` for the discussion.
+- **List issues**: `list_issues` filtered by label and state.
+- **Comment on an issue**: `save_comment`.
+- **Apply / remove labels**: update the issue's labels via `save_issue`; create missing labels with `create_issue_label` once, not per issue.
+- **Close**: set the issue's state to Done via `save_issue`, with a closing comment first.
+- **Issue ↔ PR linkage**: reference the Linear identifier (e.g. `ENG-123`) in the branch name or PR title so Linear's GitHub integration links and auto-closes it; if the integration isn't set up, close the issue explicitly after the merge.
+
+## Labels
+
+The Launchrail workflow's label vocabulary — the skills quote these exact strings:
+
+- **`ready-for-agent`** — an implementable ticket the implementation loop may pick up. Only tickets wear it; the loop's frontier is computed from this label alone and cannot tell prose from work.
+- **`needs-info`** — a parked ticket, carrying its failure history; a human unblocks it.
+- **`spec`** — a spec or research note published to the tracker. Never `ready-for-agent`.
+- **`ralph:building`** — claimed by an implementer; removed when its PR merges.
+- **`wayfinder:map`** / **`wayfinder:<type>`** — a wayfinder map and its decision tickets (see below).
+
+## When a skill says "publish to the issue tracker"
+
+Create a Linear issue in the team above.
+
+## When a skill says "fetch the relevant ticket"
+
+Fetch the issue by its identifier (`ENG-123`) including comments.
+
+## Wayfinding operations
+
+Used by `launch-wayfinder`. The **map** is a single issue with **child** issues as tickets.
+
+- **Map**: a single issue labelled `wayfinder:map`, holding the Notes / Decisions-so-far / Fog body.
+- **Child ticket**: a **sub-issue** of the map (Linear's native parent/child), labelled `wayfinder:<type>` (`research`/`prototype`/`grilling`/`task`). Once claimed, the ticket is assigned to the driving dev.
+- **Blocking**: Linear's **native "blocked by" relation** — the canonical, UI-visible representation. A ticket is unblocked when every blocking issue is Done.
+- **Frontier query**: list the map's open sub-issues, drop any with an open blocking relation or an assignee; first in map order wins.
+- **Claim**: assign the issue to yourself — the session's first write.
+- **Resolve**: post the answer as a comment, move the issue to Done, then append a context pointer (gist + link) to the map's Decisions-so-far.

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

@@ -0,0 +1,45 @@
+<!--
+  Seeded by `launchrail init` from `.launchrail.yml` (issueTracker: local).
+  This file is yours — edit it freely; Launchrail never overwrites it.
+  Contains text derived from Matt Pocock's skills (MIT): https://github.com/mattpocock/skills
+-->
+
+# Issue tracker: Local Markdown
+
+Issues and specs for this repo live as markdown files in `.scratch/`.
+
+## Conventions
+
+- One feature per directory: `.scratch/<feature-slug>/`
+- The spec is committed under `docs/specs/` (the rail's stage-7 artifact); `.scratch/<feature-slug>/spec.md` may hold a working copy
+- Implementation issues are one file per ticket at `.scratch/<feature-slug>/issues/<NN>-<slug>.md`, numbered from `01` — never a single combined tickets file
+- Ticket state is recorded as a `Status:` line near the top of each issue file, using the label vocabulary below
+- Comments and conversation history append to the bottom of the file under a `## Comments` heading
+
+## Labels
+
+The Launchrail workflow's label vocabulary, written as `Status:` / `Type:` line values — the skills quote these exact strings:
+
+- **`ready-for-agent`** — an implementable ticket the implementation loop may pick up. Only tickets wear it.
+- **`needs-info`** — a parked ticket, carrying its failure history; a human unblocks it.
+- **`spec`** — a spec or research note, never an implementable ticket.
+- **`ralph:building`** — claimed by an implementer; cleared when its work merges.
+
+## When a skill says "publish to the issue tracker"
+
+Create a new file under `.scratch/<feature-slug>/` (creating the directory if needed).
+
+## When a skill says "fetch the relevant ticket"
+
+Read the file at the referenced path. The user will normally pass the path or the issue number directly.
+
+## Wayfinding operations
+
+Used by `launch-wayfinder`. The **map** is a file with one **child** file per ticket.
+
+- **Map**: `.scratch/<effort>/map.md` — the Notes / Decisions-so-far / Fog body.
+- **Child ticket**: `.scratch/<effort>/issues/NN-<slug>.md`, numbered from `01`, with the question in the body. A `Type:` line records the ticket type (`research`/`prototype`/`grilling`/`task`); a `Status:` line records `claimed`/`resolved`.
+- **Blocking**: a `Blocked by: NN, NN` line near the top. A ticket is unblocked when every file it lists is `resolved`.
+- **Frontier**: scan `.scratch/<effort>/issues/` for files that are open, unblocked, and unclaimed; first by number wins.
+- **Claim**: set `Status: claimed` and save before any work.
+- **Resolve**: append the answer under an `## Answer` heading, set `Status: resolved`, then append a context pointer (gist + link) to the map's Decisions-so-far in `map.md`.

package/assets/ralph.permission-guard.py

@@ -0,0 +1,90 @@
+#!/usr/bin/env python3
+"""
+Ralph unattended-launch guard  (PreToolUse hook on the `Workflow` tool).
+
+Launchrail's Ralph loop — the `ralph` workflow at `.claude/workflows/ralph.js`,
+reached through `/launch-implement` — is meant to be launched and then left alone
+for hours while it drives a ticket backlog to merged code. If it is launched
+while the session is in an INTERACTIVE permission mode, a single benign
+permission prompt (e.g. an MCP or Bash tool call the session has not
+pre-approved) can stall the whole run. Once the session sits idle waiting on a
+human who has walked away, an ephemeral cloud container is reclaimed and the run
+dies mid-ticket — leaving a half-finished ticket and starving everything blocked
+behind it.
+
+This hook WARNS (it does not block) when Ralph is launched in a prompting mode,
+so the reminder lands while the user is still at the keyboard and can switch to a
+non-prompting mode (bypass / autonomous) before walking away.
+
+It is a pure guard: it NEVER grants a permission. For anything that is not a
+Ralph `Workflow` launch, and for Ralph launches already in a safe mode, it prints
+nothing and exits 0, leaving normal permission handling completely untouched.
+
+Managed by Launchrail (`launchrail sync` may replace this file). Contract:
+https://code.claude.com/docs/en/hooks  (PreToolUse: reads `permission_mode` /
+`tool_name` / `tool_input`; a `systemMessage` with no `permissionDecision` warns
+the user without changing the decision.)
+"""
+import json
+import sys
+
+# Modes that still raise interactive permission prompts. In any of these, a tool
+# call the session has not pre-approved waits on a human — fatal for an
+# unattended multi-hour run. `acceptEdits` only auto-approves file edits, so
+# MCP/Bash calls still prompt; it belongs here too. The non-prompting family
+# (bypassPermissions / auto / dontAsk) is intentionally absent — those are safe.
+INTERACTIVE_MODES = {"default", "plan", "acceptEdits"}
+
+
+def is_ralph_workflow(tool_name, tool_input):
+    """True only for a launch of the `ralph` workflow (named, inline, or resumed)."""
+    if tool_name != "Workflow" or not isinstance(tool_input, dict):
+        return False
+    if tool_input.get("name") == "ralph":
+        return True
+    # An inline `script` or a `scriptPath` (resume) that points at the ralph script.
+    blob = " ".join(str(tool_input.get(k, "")) for k in ("script", "scriptPath"))
+    return "ralph" in blob.lower()
+
+
+def main():
+    try:
+        data = json.load(sys.stdin)
+    except Exception:
+        sys.exit(0)  # unparseable input → never interfere
+
+    mode = data.get("permission_mode", "")
+    tool_name = data.get("tool_name", "")
+    tool_input = data.get("tool_input", {})
+
+    if not is_ralph_workflow(tool_name, tool_input):
+        sys.exit(0)  # not a Ralph launch → normal handling
+    if mode not in INTERACTIVE_MODES:
+        sys.exit(0)  # already unattended-safe → let it run silently
+
+    warning = (
+        f"⚠ Ralph is launching in '{mode}' permission mode, which still raises "
+        "interactive permission prompts. If you walk away, this run can stall on a single "
+        "benign prompt (e.g. an un-allowlisted MCP or Bash tool call) and the idle container "
+        "may be reclaimed mid-ticket, leaving a half-finished ticket. For an unattended run, "
+        "switch to a non-prompting mode (bypass / autonomous) before leaving. Proceeding anyway."
+    )
+    # Warn-but-allow: surface the message to the user and add context for the
+    # orchestrating agent, but emit NO `permissionDecision`, so the launch
+    # proceeds through normal permission handling.
+    print(json.dumps({
+        "systemMessage": warning,
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "additionalContext": (
+                f"Ralph was launched in an interactive permission mode ('{mode}'). Remind the "
+                "user to switch to a non-prompting mode (bypass/autonomous) if this run is meant "
+                "to be unattended, so it cannot stall on a permission prompt."
+            ),
+        },
+    }))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()