@wemuda/launchrail 1.11.0 → 1.12.0

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

@@ -74,6 +74,17 @@ Run `gh issue view <number> --comments`.
 
 The stage-7 spec ([ADR-0025](https://github.com/wemuda/launchrail/blob/master/docs/adr/0025-spec-home-follows-tracker.md)) is itself an issue here — created by `launch-spec`, labelled **`spec`**, never `ready-for-agent`. There is no `docs/specs/` file; the issue is the canonical spec. When `launch-tickets` breaks it down, each ticket is a **GitHub sub-issue of the spec** (`gh api` on the sub-issues endpoint), or carries `Part of #<spec>` at the top of its body where sub-issues aren't enabled. Design validation revises the spec issue in place (its `## Design validation` section lives in the issue body).
 
+## The spec's milestone (rollup view)
+
+The spec issue and its tickets are also bundled under a **GitHub milestone** named for the feature, so the tracker shows one progress rollup — the milestone's bar fills as tickets close. The milestone is a **rollup, not the spec's home**: the `spec`-labelled issue stays canonical ([ADR-0025](https://github.com/wemuda/launchrail/blob/master/docs/adr/0025-spec-home-follows-tracker.md)), and the milestone's description holds only a one-line goal and a link back to that issue.
+
+- **Create it** (`launch-spec`, once per spec): `gh api --method POST repos/{owner}/{repo}/milestones -f title='<feature>' -f description='<one-line goal> — spec: <spec-issue-url>'`. The response's `number` is the milestone id.
+- **Put an issue in it**: pass `--milestone '<feature>'` to `gh issue create`, or `gh issue edit <n> --milestone '<feature>'` after the fact. `launch-spec` adds the spec issue; `launch-tickets` adds every ticket to the same milestone.
+- **Find the milestone a spec already carries** (`launch-tickets`): `gh issue view <spec> --json milestone --jq .milestone.title`.
+- **Progress** is computed by GitHub from closed-vs-open issues — no upkeep.
+
+An issue belongs to at most one milestone, so each ticket rolls up to exactly one spec. Milestones carry no labels and take no part in the implementation loop's frontier — they are purely the human-facing rollup, never a substitute for the `spec` issue or the native sub-issue links.
+
 ## Wayfinding operations
 
 Used by `launch-wayfinder`. The **map** is a single issue with **child** issues as tickets.

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

@@ -44,6 +44,17 @@ Run `glab issue view <number> --comments`.
 
 The stage-7 spec ([ADR-0025](https://github.com/wemuda/launchrail/blob/master/docs/adr/0025-spec-home-follows-tracker.md)) is itself an issue here — created by `launch-spec`, labelled **`spec`**, never `ready-for-agent`. There is no `docs/specs/` file; the issue is the canonical spec. When `launch-tickets` breaks it down, each ticket carries `Part of #<spec>` at the top of its description (on tiers with native epics, the spec may be an epic holding the tickets instead). Design validation revises the spec issue in place (its `## Design validation` section lives in the issue description).
 
+## The spec's milestone (rollup view)
+
+The spec issue and its tickets are also bundled under a **GitLab milestone** named for the feature, so the tracker shows one progress rollup as tickets close. The milestone is a **rollup, not the spec's home**: the `spec`-labelled issue stays canonical ([ADR-0025](https://github.com/wemuda/launchrail/blob/master/docs/adr/0025-spec-home-follows-tracker.md)), and the milestone description holds only a one-line goal and a link back to that issue.
+
+- **Create it** (`launch-spec`, once per spec): a project milestone — `glab api --method POST "projects/:id/milestones" -f title='<feature>' -f description='<one-line goal> — spec: <spec-issue-url>'` (or make it in the GitLab UI). A group-level milestone works too where the feature spans projects.
+- **Put an issue in it**: pass `--milestone '<feature>'` to `glab issue create`, or `glab issue update <n> --milestone '<feature>'` after the fact. `launch-spec` adds the spec issue; `launch-tickets` adds every ticket to the same milestone.
+- **Find the milestone a spec already carries** (`launch-tickets`): `glab issue view <spec> -F json` and read its `milestone`.
+- **Progress** is computed by GitLab from closed-vs-open issues — no upkeep.
+
+An issue belongs to at most one milestone, so each ticket rolls up to exactly one spec. Milestones carry no labels and take no part in the implementation loop's frontier — they are purely the human-facing rollup, never a substitute for the `spec` issue.
+
 ## Wayfinding operations
 
 Used by `launch-wayfinder`. The **map** is a single issue with **child** issues as tickets.

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

@@ -44,6 +44,16 @@ Fetch the issue by its identifier (`ENG-123`) including comments.
 
 The stage-7 spec ([ADR-0025](https://github.com/wemuda/launchrail/blob/master/docs/adr/0025-spec-home-follows-tracker.md)) is itself an issue here — created by `launch-spec`, labelled **`spec`**, never `ready-for-agent`. There is no `docs/specs/` file; the issue is the canonical spec. When `launch-tickets` breaks it down, each ticket is a **sub-issue of the spec** (Linear's native parent/child). Design validation revises the spec issue in place (its `## Design validation` section lives in the issue description).
 
+## The spec's rollup (milestone)
+
+Linear's analog of a milestone is a **project milestone** inside a project — or, if the feature is big enough to stand alone, a **project** of its own. Either way it bundles the spec issue with its tickets so Linear shows one progress rollup for the feature. It is a **rollup, not the spec's home**: the `spec`-labelled issue stays canonical ([ADR-0025](https://github.com/wemuda/launchrail/blob/master/docs/adr/0025-spec-home-follows-tracker.md)).
+
+- **Create it** (`launch-spec`): `save_milestone` for a project milestone named for the feature under the configured project (create the project with `save_project` first if the feature warrants its own).
+- **Attach issues**: set each issue's project / project-milestone via `save_issue` — `launch-spec` for the spec issue, `launch-tickets` for every ticket.
+- **Find the rollup a spec already carries** (`launch-tickets`): read the spec issue's project milestone via `get_issue`.
+
+Linear computes the rollup's progress from its issues' states. If no project is configured (the field above is blank), skip the milestone — a bare Linear issue has nowhere to hang one.
+
 ## Wayfinding operations
 
 Used by `launch-wayfinder`. The **map** is a single issue with **child** issues as tickets.

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

@@ -15,6 +15,7 @@ Issues and specs for this repo live as markdown files in `.scratch/`.
 - 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
+- No milestones: the `.scratch/<feature-slug>/` directory is itself the feature's bundle (spec at `docs/specs/<feature-slug>.md`, tickets alongside), and progress is just how many of its issue files are closed — there is nothing to create when a skill mentions the spec's milestone
 
 ## Labels
 

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

@@ -21,6 +21,8 @@ This skill takes the current conversation context and codebase understanding and
    - **A real tracker (GitHub, GitLab, Linear)** → publish the spec as an issue labeled **`spec`**. That issue is stage 7's canonical artifact — do not also commit a `docs/specs/` file. Never label it `ready-for-agent`: that label marks implementable tickets, the implementation loop computes its frontier from it, and it cannot tell prose from work.
    - **Local mode (`local`, or no tracker)** → commit the spec under `docs/specs/` (`<feature-slug>.md`). There is no external store, so the committed file is the canonical artifact. It is project-owned.
 
+On a real tracker, also bundle the spec under a **milestone** named for the feature: create the milestone, put the spec issue in it, and set its description to a one-line goal plus a link back to the spec issue. That milestone is the rollup `launch-tickets` hangs every ticket on, so the whole feature reads as one progress bar — a *view*, not the spec's home; the `spec`-labelled issue stays canonical. See `docs/agents/issue-tracker.md` for the exact per-tracker commands; local mode has no milestone (the feature's files are its bundle).
+
 The spec then flows on: design validation (stage 8) revises it in place, and `launch-tickets` (stage 9) breaks it into tickets that reference it.
 
 <spec-template>

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

@@ -62,7 +62,7 @@ Iterate until the user approves the breakdown.
 Publish the approved tickets. **How** depends on the tracker configured in `docs/agents/issue-tracker.md` — the tickets are the same either way, only the shape of the blocking edges changes:
 
 - **Local files** → write one file per ticket under `.scratch/<feature-slug>/issues/<NN>-<slug>.md`, numbered from `01` in dependency order (blockers first). Each file's "Blocked by" lists the numbers/titles it depends on. Use the per-ticket file template below — one ticket per file, never a single combined file.
-- **A real issue tracker (GitHub, GitLab, Linear, …)** → publish one issue per ticket in dependency order (blockers first) so each ticket's edges reference real identifiers. Wire every blocking edge and any parent as the tracker's **native relationship** — GitHub/GitLab issue dependencies and sub-issues, Linear's blocked-by and sub-issue relations — the canonical, UI-visible form the implementation loop's frontier reads. The body's `Parent` / `Blocked by` lines then only mirror it, becoming the gate itself only on a tracker that lacks the native relationship. When the spec is itself a `spec`-labeled issue on the tracker ([ADR-0025](https://github.com/wemuda/launchrail/blob/master/docs/adr/0025-spec-home-follows-tracker.md)), it **is** the parent — link each ticket to it through that same native sub-issue relation. `docs/agents/issue-tracker.md` carries the exact per-tracker API. Apply the **`ready-for-agent`** label unless instructed otherwise — the tickets are agent-grabbable by construction. Only tickets wear that label: the spec issue keeps its `spec` label, or the loop will dispatch the document as work.
+- **A real issue tracker (GitHub, GitLab, Linear, …)** → publish one issue per ticket in dependency order (blockers first) so each ticket's edges reference real identifiers. Wire every blocking edge and any parent as the tracker's **native relationship** — GitHub/GitLab issue dependencies and sub-issues, Linear's blocked-by and sub-issue relations — the canonical, UI-visible form the implementation loop's frontier reads. The body's `Parent` / `Blocked by` lines then only mirror it, becoming the gate itself only on a tracker that lacks the native relationship. When the spec is itself a `spec`-labeled issue on the tracker ([ADR-0025](https://github.com/wemuda/launchrail/blob/master/docs/adr/0025-spec-home-follows-tracker.md)), it **is** the parent — link each ticket to it through that same native sub-issue relation. `docs/agents/issue-tracker.md` carries the exact per-tracker API. Apply the **`ready-for-agent`** label unless instructed otherwise — the tickets are agent-grabbable by construction. Only tickets wear that label: the spec issue keeps its `spec` label, or the loop will dispatch the document as work. Assign every ticket to the **same milestone the spec issue carries** — read it off the spec issue (`docs/agents/issue-tracker.md` has the per-tracker command) — so the feature rolls up as one progress bar; a tracker without milestones (local) has nothing to assign.
 
 Work the **frontier**: any ticket whose blockers are all done. For a purely linear chain that means top to bottom.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wemuda/launchrail",
-  "version": "1.11.0",
+  "version": "1.12.0",
   "description": "Launchrail — initialize, inspect, update, and validate repositories using the Launchrail development system.",
   "license": "MIT",
   "type": "module",