@wemuda/launchrail 1.12.0 → 1.14.0

package/README.md

@@ -34,6 +34,8 @@ This repository is the Launchrail **toolchain**: the CLI, the workflow skills (s
 
 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.
 
+You experience the rail as **six phases** — Intent → Exploration → Decisions → Blueprint → Build → Ship — with a fixed **rail banner** rendered at every transition: where you are, what just finished, what happens now, and the one next command. And planning runs under a hard **interaction contract** ([ADR-0029](https://github.com/wemuda/launchrail/blob/master/docs/adr/0029-planning-interaction-contract.md)): every uncertainty is labeled and only the questions that are genuinely yours reach you — at most three per round, about six decisions per session, with a checkpoint every two rounds (continue / prototype / defer / build). Reversible engineering details become recorded agent defaults instead of questions, approved prototypes are treated as decisions rather than feature inventories to trim, and planning stops when the next slice can be built safely — not when every question is answered.
+
 <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 → 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>
@@ -145,7 +147,7 @@ The toolchain is stable and versioned. The full surface — `init`/`doctor`, the
 See [CONTRIBUTING.md](https://github.com/wemuda/launchrail/blob/master/CONTRIBUTING.md). The short version:
 
 - Commits follow [Conventional Commits](https://www.conventionalcommits.org/) (`type(scope): summary`); see [ADR-0002](https://github.com/wemuda/launchrail/blob/master/docs/adr/0002-conventional-commits.md). Releases and the changelog are generated from them ([docs/releasing.md](https://github.com/wemuda/launchrail/blob/master/docs/releasing.md)).
-- Meaningful decisions are recorded as ADRs in [docs/adr/](https://github.com/wemuda/launchrail/tree/master/docs/adr/).
+- Meaningful decisions are recorded as ADRs in [docs/adr/](https://github.com/wemuda/launchrail/tree/master/docs/adr/); the registry index [docs/adr/README.md](https://github.com/wemuda/launchrail/blob/master/docs/adr/README.md) says which are live.
 - The agent operating contract lives in [AGENTS.md](https://github.com/wemuda/launchrail/blob/master/AGENTS.md).
 - Security issues go through [SECURITY.md](https://github.com/wemuda/launchrail/blob/master/SECURITY.md), not public issues.
 

package/assets/agents-docs/domain.md

@@ -11,7 +11,7 @@ How the workflow skills should consume this repo's domain documentation when exp
 
 - **`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.
+- **`docs/adr/README.md`** — the decision registry. Read its index first, then open only the ADRs that touch the area you're about to work in. An ADR records a decision, not the current system — never take one as evidence that a component exists or still works as described; verify against the code. 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.
 
@@ -44,7 +44,7 @@ Multi-context repo (presence of `CONTEXT-MAP.md` at the root):
         └── docs/adr/
 ```
 
-ADRs use the project's own format — copy `docs/adr/0000-template.md` and number sequentially (`NNNN-short-slug.md`).
+ADRs use the project's own format — copy `docs/adr/0000-template.md`, take the next free number (`NNNN-short-slug.md`), and add the record's row to the registry index (`docs/adr/README.md`) in the same commit.
 
 ## Use the glossary's vocabulary
 

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

@@ -28,7 +28,7 @@ The Launchrail workflow's label vocabulary — the skills quote these exact stri
 - **`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.
+- **`ralph:building`** — claimed by an implementer; removed when the loop lands it.
 - **`wayfinder:map`** / **`wayfinder:<type>`** — a wayfinder map and its decision tickets (see below).
 
 ## Relationships — native, not prose

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

@@ -29,7 +29,7 @@ The Launchrail workflow's label vocabulary — the skills quote these exact stri
 - **`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.
+- **`ralph:building`** — claimed by an implementer; removed when the loop lands it.
 - **`wayfinder:map`** / **`wayfinder:<type>`** — a wayfinder map and its decision tickets (see below).
 
 ## When a skill says "publish to the issue tracker"