@connorbritain/roadmap 0.3.0

package/docs/DEPLOYMENT.md

@@ -0,0 +1,195 @@
+# Deploying roadmap — every surface, every config, where secrets live
+
+One rule governs everything on this page:
+
+> **Committed YAML carries configuration. The environment carries secrets. Nothing else exists.**
+> `docs/roadmap/roadmap.yaml` (including `meta.linear`) is committed and shareable — it never contains a credential. API keys live in environment variables only — never in the YAML, never in `.mcp.json`, never in plugin files. There is no hidden per-plugin config store to manage.
+
+## The surfaces at a glance
+
+| Surface | What you get | Install | Credentials come from |
+|---|---|---|---|
+| **CLI** (`roadmap ...`) | Everything: plan/fan/backlog/next/set/linear | `npm install -D @connorbritain/roadmap` | Your shell environment |
+| **Claude Code plugin** | Skills (`/slice /backlog /imagine /prioritize /sync /init /fanout`), 4 agents, SessionStart hook, PR-watch monitor, **and** the MCP server `graph` (16 tools) — one install | `claude plugin install roadmap@roadmap` | Inherited from your shell environment |
+| **Standalone MCP** (no plugin) | Just the 16 `graph` tools in any MCP client | register `scripts/mcp.mjs` (below) | Inherited env, or an `env` block in the client's MCP config |
+| **Codex / other agents** | CLI + MCP + optional local assistant profile | `npm install -D @connorbritain/roadmap` + `roadmap init` | Shell environment |
+| **CI / headless** | CLI (`validate`, `render`, `linear sync`) | `npm ci` in the tool checkout | CI secret store → env var |
+
+A **consuming repo** commits only its own `docs/roadmap/roadmap.yaml` + `backlog.yaml` (and the generated `SLICES.md`/`BACKLOG.md`). The tool itself is installed once per machine. The Linear sync cursor (`.roadmap-linear-state.json`) is per-machine local state — git-ignore it.
+
+## 1 · CLI
+
+```bash
+npm install --save-dev @connorbritain/roadmap
+npx roadmap init
+```
+
+`roadmap` now works from anywhere inside any repo that has `docs/roadmap/roadmap.yaml`. No configuration files beyond the repo's own YAML.
+
+## 2 · Claude Code plugin (the full experience)
+
+```bash
+claude plugin marketplace add ConnorBritain/roadmap    # or a local path
+claude plugin install roadmap@roadmap                  # --scope project to pin per-repo
+```
+
+That single install wires the skills, agents, the SessionStart hook, the PR-watch monitor, **and** the bundled MCP server (`.mcp.json` → server name `graph`, tools `mcp__plugin_roadmap_graph__*`). There is nothing to configure inside the plugin itself.
+
+**How the plugin's MCP server finds your repo:** it walks up from the session's project directory (`CLAUDE_PROJECT_DIR`) to the nearest `docs/roadmap/roadmap.yaml`.
+
+**How it gets credentials:** the spawned server inherits your environment. If `LINEAR_API_KEY` is set at the user level (below), the plugin's Linear tools are authed with zero extra steps.
+
+**Permissions:** in a consuming repo's `.claude/settings.json`, reads are safe to allow; mutators belong on the ask list:
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "mcp__plugin_roadmap_graph__plan", "mcp__plugin_roadmap_graph__ready_wave",
+      "mcp__plugin_roadmap_graph__show", "mcp__plugin_roadmap_graph__validate",
+      "mcp__plugin_roadmap_graph__backlog_list", "mcp__plugin_roadmap_graph__linear_status"
+    ],
+    "ask": [
+      "mcp__plugin_roadmap_graph__set_fields", "mcp__plugin_roadmap_graph__bulk_set",
+      "mcp__plugin_roadmap_graph__backlog_add", "mcp__plugin_roadmap_graph__linear_sync"
+    ]
+  }
+}
+```
+
+## 3 · Standalone MCP (Claude Desktop, other MCP clients, plugin-less Claude Code)
+
+The server is one command: `node <tool-checkout>/scripts/mcp.mjs` (stdio JSON-RPC). Register it wherever your client takes MCP servers.
+
+**Claude Code without the plugin** — in the consuming repo:
+
+```bash
+claude mcp add graph -- node "C:/Users/you/Code/roadmap/scripts/mcp.mjs"
+```
+
+(Repo discovery works because Claude Code runs servers with the project dir available. Don't do this *and* install the plugin — you'd get two servers.)
+
+**Claude Desktop** (`claude_desktop_config.json`) — Desktop has no "current repo", so point the server at one explicitly via the env block. This is also where Desktop users put the Linear key, because GUI apps don't always inherit your shell profile:
+
+```json
+{
+  "mcpServers": {
+    "roadmap-graph": {
+      "command": "node",
+      "args": ["C:/Users/you/Code/roadmap/scripts/mcp.mjs"],
+      "env": {
+        "CLAUDE_PROJECT_DIR": "C:/Users/you/Code/my-app",
+        "LINEAR_API_KEY": "lin_api_..."
+      }
+    }
+  }
+}
+```
+
+> `claude_desktop_config.json` lives in your OS user profile and is never committed — a key here is machine-local, same trust level as an env var. **Never** put a key in a repo's `.mcp.json` or any committed file.
+
+**Codex / anything else:** `npm run mcp` from the tool checkout (set `CODEX_PROJECT_DIR` or run with cwd inside the consuming repo).
+
+## 4 · Linear
+
+**Config** (committed, secret-free) — in the consuming repo's `roadmap.yaml`:
+
+```yaml
+meta:
+  linear:
+    team: ENG                    # push target
+    granularity: slices          # pis | slices | slices+backlog
+    pull: propose                # off | propose | auto
+    watch:                       # optional inbound sources
+      - { team: PUB, project: "Submit an issue", kind: bug, priority: { tier: P3 } }
+```
+
+**Secret** (environment only) — `LINEAR_API_KEY`, a Linear personal API key (Linear → Settings → Security & access → Personal API keys):
+
+| Where | How |
+|---|---|
+| Windows (persistent) | `[Environment]::SetEnvironmentVariable('LINEAR_API_KEY','<key>','User')` then a new shell |
+| macOS / Linux | `echo 'export LINEAR_API_KEY=<key>' >> ~/.zshrc` (or `.bashrc`) |
+| Claude Code plugin / CLI | nothing extra — both inherit the above |
+| Claude Desktop | the `env` block shown in §3 |
+| CI | repo/organization secret → exposed as `LINEAR_API_KEY` on the job |
+
+**Bootstrap sequence** in a consuming repo:
+
+```bash
+roadmap linear auth              # prints the key instructions (never stores anything)
+roadmap linear status --probe    # confirms auth with one viewer query
+roadmap linear setup --team ENG  # queries your teams, writes meta.linear via the validated store
+roadmap linear provision         # labels + standard views + the two guidance texts to paste
+roadmap linear sync --dry        # shows the push plan + pull inbox, writes nothing
+roadmap linear sync              # projects the roadmap; /sync now includes the Linear phase
+```
+
+`provision` also prints the **repo dispatch contract** — paste it into `CLAUDE.md`/`AGENTS.md` so cloud agents delegated a Linear issue (Claude Code coding sessions, Codex, Warp Oz) self-orient from the issue footer.
+
+**Detection is graceful at every state** — the same sentence everywhere (hook, CLI, MCP):
+
+| State | Behavior |
+|---|---|
+| No `meta.linear` | All Linear behavior off; tool is byte-identical to an unwired install |
+| Configured, no key | One advisory line; everything else works; sync errors with the fix |
+| Wired | `/sync` runs the Linear phase; hook reports team/pull/last-sync |
+
+## 5 · Cloud dispatch (Claude Code Routines)
+
+`roadmap dispatch <key>` / `roadmap fan --cloud` fire **Claude Code cloud sessions** directly via the Routines API — no Linear plan required, no local worktrees, bounded only by the firing account's Claude plan (Pro/Max/Team). ⚠ The fire endpoint is **beta** (`experimental-cc-routine-2026-04-01`); shapes may change.
+
+**One-time routine setup (per claude.ai account, per repo):**
+
+1. On claude.ai → **Code → Routines** (claude.ai/code/routines) → New routine.
+2. Point it at the target **GitHub repo** (must be pushed/connected). Saved prompt — keep it generic; the dispatch capsule arrives as the fired text:
+   > You are a roadmap dispatch worker. The trigger message contains a machine capsule naming a slice — follow it exactly: read docs/SLICES.md and docs/roadmap/roadmap.yaml for the named slice, honor its gate, open a PR, never merge, leftovers to the backlog only.
+3. Add an **API trigger** (save the routine first — the endpoint is generated after saving). The modal shows a **URL** (the `trig_…` id is embedded in it, never labeled separately) and a **Generate token** button — the token (`sk-ant-oat01-…`) is shown ONCE; copy it immediately. Use the whole URL as the `trigger` value — the tool accepts either the full URL or the bare `trig_…` id.
+
+**Single-account:** put them in env — `CLAUDE_ROUTINE_TRIGGER` + `CLAUDE_ROUTINE_TOKEN`. Done.
+
+**Multi-account on one workstation** (people swapping `claude /login` on the same OS user): each person creates the same routine under *their own* claude.ai account, and the pairs live in a machine-local **`~/.claude-routines.json`** (never committed; same trust level as env — override the path with `CLAUDE_ROUTINES_FILE`):
+
+```json
+{
+  "connor": {
+    "account": "connor@example.com",
+    "routines": {
+      "default":        { "trigger": "trig_aaa", "token": "sk-ant-oat01-..." },
+      "acme/webapp":    { "trigger": "trig_bbb", "token": "sk-ant-oat01-..." }
+    }
+  },
+  "sam": {
+    "account": "sam@example.com",
+    "routines": { "default": { "trigger": "trig_ccc", "token": "sk-ant-oat01-..." } }
+  }
+}
+```
+
+**Resolution order (the hot-swap):** the env pair wins outright (CI/override) → `CLAUDE_ROUTINE_PROFILE=<name>` pins a profile explicitly → otherwise dispatch reads the **currently-authed claude.ai account** from the CLI's own config (`~/.claude.json → oauthAccount.emailAddress`) and matches it to a profile's `account`. Swap people with `claude /login`; the next dispatch fires on the new person's limits with zero config changes. Within a profile, the repo-specific routine (keyed `owner/repo` from the git remote) wins over `default`. Every miss is an actionable error naming the fix.
+
+When the dispatched slice is also Linear-mapped and `LINEAR_API_KEY` is set, dispatch comments the session URL onto the issue — the board links to the live session. Best-effort: a comment failure never fails the dispatch.
+
+## 6 · Jira (planned — not yet implemented)
+
+Jira support is the designed follow-up and will mirror this layout exactly, so nothing about your deployment changes shape:
+
+```yaml
+meta:
+  jira:                          # PLANNED — does not work yet
+    project: ENG                 # push target project key
+    granularity: slices
+    pull: propose
+```
+
+with secrets in `JIRA_BASE_URL`, `JIRA_EMAIL`, `JIRA_API_TOKEN` (Atlassian API token), and a `roadmap jira status|setup|sync` family. The sync brain is already tracker-neutral; only the field maps and REST transport are Jira-specific. Until it ships, a `meta.jira` block is ignored and `roadmap validate` warns about it — don't add it yet.
+
+**Why direct APIs instead of the Linear/Atlassian MCP servers?** The sync is a deterministic batch program (diffing, batching, cursors, idempotent re-runs) that must run headless from CLI/CI — MCP tools are built for a model in the loop, and the hosted servers authenticate with the *same* credential anyway, so routing through them adds a protocol layer without removing the key. Interactive agent work (chatting about issues, agent delegation from Linear/Jira) is exactly what those hosted MCP servers are for — pushed issues carry a machine footer so agents dispatched from them self-orient with one command.
+
+## 7 · Troubleshooting
+
+- `roadmap linear status` tells you which of the three states you're in and the exact next command.
+- Plugin tools missing in a session → `/mcp` to reconnect, or restart the session after install.
+- Two `graph` servers listed → you both installed the plugin and `claude mcp add`ed it; remove one.
+- `Linear API HTTP 401` → key invalid/expired; re-issue and reset the env var.
+- Upgrading from `slice-roadmap` ≤0.1.x → see README → *Upgrading* (permission allow-lists need rewriting to `mcp__plugin_roadmap_graph__*`).

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@connorbritain/roadmap",
+  "version": "0.3.0",
+  "description": "Roadmap + backlog graph with prioritized, deterministic multi-session fanout. YAML canonical, SLICES.md/BACKLOG.md generated.",
+  "type": "module",
+  "private": false,
+  "author": "Connor England",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ConnorBritain/roadmap.git"
+  },
+  "homepage": "https://github.com/ConnorBritain/roadmap#readme",
+  "engines": {
+    "node": ">=18.15"
+  },
+  "bin": {
+    "roadmap": "scripts/cli.mjs"
+  },
+  "files": [
+    "scripts/",
+    "schema/",
+    "README.md",
+    "docs/DEPLOYMENT.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "cli": "node scripts/cli.mjs",
+    "plan": "node scripts/cli.mjs plan",
+    "show": "node scripts/cli.mjs show",
+    "fan": "node scripts/cli.mjs fan",
+    "cleanup": "node scripts/cli.mjs cleanup",
+    "validate": "node scripts/validate.mjs",
+    "render": "node scripts/render.mjs",
+    "mcp": "node scripts/mcp.mjs",
+    "prepack": "npm test",
+    "watch": "node scripts/watch-prs.mjs",
+    "test": "node scripts/test/run.mjs"
+  },
+  "dependencies": {
+    "yaml": "^2.5.0"
+  }
+}

package/schema/backlog.schema.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/ConnorBritain/roadmap/schema/backlog.schema.json",
+  "title": "roadmap backlog.yaml",
+  "description": "The erratic-work tracker beside the roadmap: follow-ups, bugs, chores, urgent items that surface outside the planned feature/value work. Items are directly launchable (roadmap grab <id>) or promotable into a roadmap sprint (roadmap promote <id> --pi <pi>). BACKLOG.md is generated from this file.",
+  "type": "object",
+  "required": ["meta", "items"],
+  "additionalProperties": false,
+  "properties": {
+    "meta": {
+      "type": "object",
+      "required": ["schema_version"],
+      "additionalProperties": false,
+      "properties": {
+        "schema_version": { "const": 1 }
+      }
+    },
+    "items": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/item" }
+    }
+  },
+  "$defs": {
+    "item": {
+      "type": "object",
+      "required": ["id", "title", "kind", "status"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$", "description": "Stable item slug (auto b1..bN when omitted at add). Becomes the sprint invoke key on promote and the grab branch backlog/<id>." },
+        "title": { "type": "string" },
+        "kind": { "enum": ["bug", "chore", "followup", "urgent", "idea"] },
+        "status": { "enum": ["open", "in_progress", "promoted", "done", "dropped"] },
+        "priority": { "$ref": "roadmap.schema.json#/$defs/priority" },
+        "source": {
+          "type": "object", "additionalProperties": false,
+          "description": "Where this surfaced: the slice that spawned it, an inbound Linear issue, when, and a note",
+          "properties": {
+            "slice": { "type": "string", "description": "Invoke key of the slice this fell out of" },
+            "date": { "type": "string", "description": "ISO date captured" },
+            "note": { "type": "string" },
+            "linear": {
+              "type": "object", "additionalProperties": false,
+              "description": "Origin demarcation for items captured from a watched Linear source — lets /prioritize weight by where work comes from",
+              "properties": {
+                "team": { "type": "string" },
+                "project": { "type": "string" },
+                "issue": { "type": "string" }
+              }
+            }
+          }
+        },
+        "linear": { "type": "string", "description": "Linear issue identifier this item maps to (set on push or on pull-capture)" },
+        "refs": { "type": "array", "items": { "type": "string" }, "description": "Related roadmap slice invoke keys" },
+        "touches": { "type": "array", "items": { "type": "string" }, "description": "Files this item writes (grab uses it for the brief scope)" },
+        "est_sessions": { "type": "number", "minimum": 0 },
+        "gate": { "type": "string", "description": "'default' inherits the roadmap's meta.default_gate" },
+        "prompt": { "type": "string", "description": "Author-stashed pickup instructions, embedded verbatim in the grab kickoff brief" },
+        "dispatch_tier": { "type": "string", "description": "Cloud-dispatch routine tier for this item (e.g. 'fable'). Dispatch resolves routines[\"<owner/repo>#<tier>\"] (or \"default#<tier>\") from ~/.claude-routines.json and THROWS if the tier isn't configured — never a silent fallback to the standard routine. Absent: the standard repo routine. CLI --tier overrides per launch." },
+        "prs": { "type": "array", "items": { "type": "string" } },
+        "completed_on": { "type": "string", "description": "ISO date the item closed (done/dropped)" },
+        "promoted_to": { "type": "string", "description": "pi-id/sprint-id nodeKey written by promote; the back-link to the roadmap" }
+      }
+    }
+  }
+}

package/schema/roadmap.schema.json

@@ -0,0 +1,273 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/ConnorBritain/roadmap/schema/roadmap.schema.json",
+  "title": "roadmap roadmap.yaml",
+  "description": "Canonical roadmap graph: PIs containing sprints, with dependency edges, file-ownership for two-wave detection, session estimates, gates, and per-sprint kickoff briefs. SLICES.md is generated from this file; do not edit the generated markdown.",
+  "type": "object",
+  "required": ["meta", "pis"],
+  "additionalProperties": false,
+  "properties": {
+    "meta": {
+      "type": "object",
+      "required": ["schema_version", "program"],
+      "additionalProperties": false,
+      "properties": {
+        "schema_version": { "const": 1 },
+        "program": { "type": "string", "description": "Active program label, e.g. Q3-PLATFORM" },
+        "north_star": { "type": "string", "description": "Path to the strategy / vision source of truth" },
+        "updated": { "type": "string", "description": "ISO date of last hand-edit" },
+        "default_gate": { "type": "string", "description": "Verification gate inherited by sprints whose gate is 'default' or interpolates {{default}}" },
+        "branch_convention": { "type": "string", "default": "{pi}/{sprint}" },
+        "worktree_root": { "type": "string", "description": "Parent dir for per-sprint worktrees; use a WSL/Linux-fs path, NOT a OneDrive-synced checkout" },
+        "worktree_gb": { "type": "number", "minimum": 0, "description": "Calibration knob for the disk ceiling: GB one worktree really costs (checkout + installs + build litter). Omitted → estimated from the tracked tree's size × 1.3" },
+        "terminal": { "enum": ["warp", "wt", "tmux", "iterm", "background", "print"], "default": "print", "description": "Default terminal adapter for /fanout launches" },
+        "default_concurrency": { "type": "integer", "minimum": 1, "default": 3 },
+        "worker_mode": { "enum": ["plan", "auto", "acceptEdits", "bypassPermissions"], "default": "plan", "description": "Default --permission-mode for launched worker + lead sessions; --worker-mode overrides. 'auto' = auto-approve tool/bash/MCP with safety checks (NOT a bypass); 'plan' = read-only research that gates edits behind plan approval." },
+        "agent_cmd": { "type": "string", "description": "Launch-command template for INTERACTIVE worker/lead sessions — swap the agent (e.g. a codex invocation). Tokens: {mode} = permission mode, {prompt} = the quoted kickoff prompt. Default: 'claude --permission-mode {mode} {prompt}'. Autonomous headless launches stay claude." },
+        "completed_window_days": { "type": "integer", "minimum": 1, "default": 14, "description": "How recently a sprint must have completed to appear in the Recently-completed table" },
+        "base_branch": { "type": "string", "default": "main", "description": "Branch worktrees are cut from + PR base" },
+        "remote": { "type": "string", "default": "origin", "description": "Git remote name for fetch + worktree base ref" },
+        "default_weight": { "enum": ["heavy", "medium", "light"], "description": "Weight assumed for a slice whose gate runner isn't recognized and that touches no code (default light)" },
+        "weight_patterns": {
+          "type": "object", "additionalProperties": false,
+          "description": "Extend the built-in multi-ecosystem runner classifier with repo-specific regexes (case-insensitive strings)",
+          "properties": {
+            "heavy": { "type": "array", "items": { "type": "string" } },
+            "medium": { "type": "array", "items": { "type": "string" } }
+          }
+        },
+        "weight_cost": {
+          "type": "object", "additionalProperties": false,
+          "description": "Override per-class per-session resource cost used by the concurrency recommender",
+          "properties": {
+            "heavy": { "$ref": "#/$defs/cost" },
+            "medium": { "$ref": "#/$defs/cost" },
+            "light": { "$ref": "#/$defs/cost" }
+          }
+        },
+        "initiatives": {
+          "type": "object",
+          "description": "Optional per-initiative Linear styling: maps an initiative NAME (matching a pi.initiative) to its board icon/color, so grouping reads as signal (every Lumen project a WritingAI icon, every Trust project a Shield) instead of the deterministic-but-arbitrary fallback palette. Applied to a declared initiative's projects AND its header; undeclared initiatives keep Linear's default header and use the fallback palette on their projects only.",
+          "additionalProperties": {
+            "type": "object", "additionalProperties": false,
+            "properties": {
+              "icon": { "type": "string", "description": "Linear icon name (e.g. Robot, Shield, Database, WritingAI). Names are a fixed Linear set; an unrecognized one degrades to no icon (color still groups)." },
+              "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "description": "Hex color like #5e6ad2." }
+            }
+          }
+        },
+        "plate": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "The 'My Issues' hopper: an explicit list of slice invoke keys / backlog ids the Linear sync assigns to YOU (assignee), so Linear's My Issues tab = your curated current batch. Presence enables the feature (absent → no assignee projection at all). Active slices / in_progress items are ALWAYS included on top; completed slices auto-drain on sync. Capped for signal by meta.linear.plate_max. Issues we assign carry a 'plate' label so a hand-assignment in Linear is never disturbed."
+        },
+        "linear": {
+          "type": "object", "additionalProperties": false,
+          "required": ["team"],
+          "description": "Optional Linear integration. Absent → all Linear behavior off (byte-identical). Linear is a PROJECTION of this file plus a proposal inbox — the YAML stays canonical. Auth is the LINEAR_API_KEY env var, never stored here.",
+          "properties": {
+            "team": { "type": "string", "description": "Push-target team key (e.g. ENG)" },
+            "granularity": { "enum": ["pis", "slices", "slices+backlog"], "default": "slices", "description": "What projects to Linear: PIs as Projects only, +slices as Issues, +backlog items too. Per-PI override via pi.linear.granularity (ack-gated on conflict)." },
+            "horizon": { "enum": ["all", "near"], "default": "all", "description": "Issue-creation horizon: all = every not-done slice becomes an issue; near = scheduled/optionality slices stay YAML-only (no NEW issues) until promoted, so the board carries only actionable work. Already-mapped issues keep updating either way — never orphaned." },
+            "verbosity": { "enum": ["title", "brief", "full"], "default": "brief", "description": "Issue-description detail. Never copies read-order/prompt; always ends with the machine footer + docs link." },
+            "cycles": { "enum": ["off", "on"], "default": "off", "description": "Mirror the team's ACTIVE Linear cycle from slice status: active+next issues join the current cycle, demoted ones leave it. The cycle IS the elected weekly batch — promotion (scheduled→next) is the planning ritual's job. Requires cycles enabled on the Linear team; converges with Linear's native rollover/auto-add. With cycles on, dispatch/fan refuse out-of-cycle slices without --force." },
+            "cycle_capacity": { "type": "integer", "minimum": 1, "default": 10, "description": "est_sessions the cycle election packs per cycle ('roadmap cycle plan'). Unestimated slices are never silently packed; committed-but-unpriced work is flagged rather than counted as zero." },
+            "history": { "enum": ["off", "window", "full"], "default": "off", "description": "Whether DONE slices project as completed issues (with completedAt = completed_on). off = never (pre-history behavior); window = completed within meta.completed_window_days (default 14); full = all shipped work — what makes a project's progress % real and keeps the record queryable in Linear (auto-archive handles aging). Flipping to full on a large roadmap is a one-time backfill; an interrupted push resumes safely (ids write back incrementally)." },
+            "pull": { "enum": ["off", "propose", "auto"], "default": "off", "description": "Inbound handling: propose = /sync walks the inbox with you; auto = applied directly." },
+            "push_on": { "enum": ["sync", "manual"], "default": "sync", "description": "sync = /sync runs the Linear phase when authed; manual = only 'roadmap linear sync'." },
+            "estimate_max": { "type": "integer", "minimum": 1, "default": 5, "description": "Max value pushed to a slice's native Linear estimate (est_sessions is rounded, then clamped here). Set to your Linear team's estimate scale max — use the 'Linear' scale (1..5; extended adds 6,7) for a direct 1-point=1-session read. validate warns when a slice exceeds it: the signal to split it, not extend." },
+            "plate_max": { "type": "integer", "minimum": 1, "default": 7, "description": "Cap on the EXPLICIT meta.plate list — validate warns above it so Linear's My Issues stays signal (active work adds on top, uncapped)." },
+            "stale_days": { "type": "integer", "minimum": 1, "description": "Staleness threshold (days). Presence enables: committed work (active/next) whose latest journal comment (fallback: issue creation) is older than this gets a 'stale' label on sync, surfaces in the Stale view, and is reviewed FIRST by the cycle election. Basis is journal activity, never issue updatedAt (our own pushes would reset that clock)." },
+            "status_map": { "type": "object", "additionalProperties": { "type": "string" }, "description": "roadmap status → exact Linear workflow-state NAME overrides; unmapped statuses use the state-TYPE defaults (scheduled→backlog, next/blocked/paused/gated→unstarted, active→started, complete→completed). Only active means In Progress; held statuses read Todo + a status:<held> label." },
+            "watch": {
+              "type": "array",
+              "description": "Inbound sources (multiple teams/projects, e.g. a public 'Submit an issue' team). New issues become proposed backlog items carrying source.linear demarcation.",
+              "items": {
+                "type": "object", "additionalProperties": false, "required": ["team"],
+                "properties": {
+                  "team": { "type": "string" },
+                  "project": { "type": "string", "description": "Omit to watch the whole team" },
+                  "capture": { "enum": ["backlog"], "default": "backlog" },
+                  "kind": { "enum": ["bug", "chore", "followup", "urgent", "idea"], "default": "idea" },
+                  "priority": { "$ref": "#/$defs/priority", "description": "Default priority for inbound items = implicit source weighting (the issue's own Linear priority wins when set)" }
+                }
+              }
+            }
+          }
+        },
+        "estimation": {
+          "type": "object", "additionalProperties": false,
+          "description": "Optional agent-time integration: turns calibrated per-slice duration estimates (from the agent-time estimator skill) into projected PI target dates. Absent → estimation off; slices with no `estimate` block simply don't feed the timeline. The shape/risk vocabulary is owned by agent-time (its SHAPES/RISKS tables validate them), not duplicated here.",
+          "properties": {
+            "engine": { "type": "string", "description": "Path to agent-time's estimator.py. Omit to resolve ~/.claude/skills/agent-time-estimator/estimator.py (or $AGENT_TIME_ENGINE)." },
+            "python": { "type": "string", "default": "python3", "description": "Python launcher for the estimator (the IO layer falls back to 'python' when 'python3' is absent)." },
+            "hours_per_day": { "type": "number", "exclusiveMinimum": 0, "default": 6, "description": "Productive agent wall-clock hours per calendar day — the rate that converts rolled-up slice minutes into a calendar span for projected_target_date." },
+            "point": { "enum": ["expected", "high"], "default": "expected", "description": "Which point of the low/expected/high estimate drives the projected date: 'expected' (realistic) or 'high' (under-promise)." },
+            "model": { "type": "string", "default": "opus-4.8", "description": "Model name passed to the estimator (drives its per-model pace + checkpoint horizon)." }
+          }
+        },
+        "discipline": {
+          "type": "object", "additionalProperties": false,
+          "description": "Scope-discipline knobs read by the /sync and /debrief guardrails and the wave scheduler",
+          "properties": {
+            "capture_ratio": { "type": "number", "exclusiveMinimum": 0, "default": 2, "description": "Max (captured backlog items + added sprints) per completed slice per review window before the sprawl warning fires" },
+            "pi_min_slices": { "type": "integer", "minimum": 1, "description": "Composition floor: validate warns (one aggregated line) when a non-complete PI holds fewer slices than this. A PI under ~3 slices is usually a slice wearing a PI's coat — fold it into a sibling or grow it. Absent → off." },
+            "coherence": { "type": "boolean", "default": true, "description": "Wave-packing coherence: prefer finishing started PIs over opening fresh ones (strictly below declared priority). false restores pure priority/status/est ordering." }
+          }
+        },
+        "last_review": {
+          "type": "object", "additionalProperties": false,
+          "required": ["date", "commit"],
+          "description": "The /debrief / /retro anchor: when the human last reviewed, and the roadmap.yaml git rev AT that review (captured before the review's own edits). Written by the skills via Edit+validate.",
+          "properties": {
+            "date": { "type": "string", "description": "ISO date the review closed" },
+            "commit": { "type": "string", "description": "git rev of the previous review's roadmap.yaml state" }
+          }
+        },
+        "links": {
+          "type": "object", "additionalProperties": true,
+          "description": "Optional repo cross-references the renderer links from (all optional; omitted ones are skipped)",
+          "properties": {
+            "narrative": { "type": "string" },
+            "status": { "type": "string" },
+            "tracker": { "type": "string" },
+            "bootstrap": { "type": "string" },
+            "strategy": { "type": "string" }
+          }
+        }
+      }
+    },
+    "pis": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/pi" }
+    }
+  },
+  "$defs": {
+    "cost": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Per-session resource cost for a weight class",
+      "properties": {
+        "ram": { "type": "number", "description": "GB RAM per session" },
+        "cores": { "type": "number", "description": "CPU cores per session" }
+      }
+    },
+    "status": {
+      "enum": ["active", "next", "scheduled", "complete", "blocked", "paused", "gated", "optionality"],
+      "description": "Canonical status. Emoji derived: active 🟢 · next 🟡 · scheduled ⚪ · complete ✅ · blocked 🔴 · paused ⏸️ · gated 🔒 · optionality 🟣"
+    },
+    "pi": {
+      "type": "object",
+      "required": ["id", "title", "status", "sprints"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$", "description": "Stable PI slug; matches the branch-slug and the tracker row" },
+        "title": { "type": "string" },
+        "theme": { "type": "string" },
+        "program_label": { "type": "string", "description": "Display string for the 'PI / program' column when it differs from id (e.g. 'Billing Rewrite P2'). Optional; defaults to the uppercased id." },
+        "status": { "$ref": "#/$defs/status" },
+        "deps": { "type": "array", "items": { "type": "string" }, "description": "PI-level dependencies (PI ids)" },
+        "estimate_weeks": { "type": "string" },
+        "exit_criteria": { "type": "string" },
+        "detail": { "type": "string", "description": "Pointer to the sprint dir / detail doc" },
+        "exec_hint": { "type": ["string", "null"], "description": "Optional human override of the derived exec-plan line; rendered alongside the derived line" },
+        "initiative": { "type": "string", "description": "Groups this PI under a Linear Initiative of this name (the tier above projects). Sync creates the initiative and attaches this PI's project. Several PIs sharing a name group together." },
+        "priority": { "$ref": "#/$defs/priority", "description": "STRATEGIC priority of this bet (not derived from slice heat) → Linear project priority. tier P0=Urgent … P3=Low." },
+        "summary": { "type": "string", "maxLength": 255, "description": "Short one-line subtitle → Linear project description (the ≤255 field the board shows under the title). Authored so it never truncates; when omitted the subtitle is derived from the exit's first sentence and validate warns if that would truncate." },
+        "start_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Start date (YYYY-MM-DD) → Linear project startDate (drives the roadmap timeline). Set it explicitly, or leave blank and the sync auto-stamps it the first time the PI is active (≈ when it was picked up). Explicit always wins." },
+        "target_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Target date (YYYY-MM-DD) → Linear project targetDate. A deliberate commitment date; omit when there's no dated commitment." },
+        "projected_target_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "DERIVED target date (YYYY-MM-DD) computed by 'roadmap estimate timeline' from rolled-up slice estimates — the estimate-driven timeline. Never overwrites an explicit target_date (which always wins); the Linear projection uses target_date || projected_target_date. Recomputed each run; don't hand-author." },
+        "linear": {
+          "type": "object", "additionalProperties": false,
+          "description": "Per-PI Linear override + the pushed-back project id. A granularity or verbosity conflicting with the global requires the yes_linear_override ack at creation; validate warns on stored mismatches.",
+          "properties": {
+            "granularity": { "enum": ["pis", "slices", "slices+backlog"] },
+            "verbosity": { "enum": ["title", "brief", "full"], "description": "Per-PI issue-description detail override — quiet a noisy PI to title, or richen an active one to full, without moving the global." },
+            "project": { "type": "string", "description": "Linear project id — written back by the first push; don't hand-author" }
+          }
+        },
+        "sprints": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/sprint" } }
+      }
+    },
+    "sprint": {
+      "type": "object",
+      "required": ["id", "title", "status", "invoke"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$", "description": "Sprint slug local to its PI, e.g. s1, s3, m1-s2" },
+        "title": { "type": "string" },
+        "status": { "$ref": "#/$defs/status" },
+        "status_label": { "type": "string", "description": "Display override for the status cell (e.g. 'Planned', 'Queued', 'Gated (Connor)', 'Next'); defaults to the capitalized enum" },
+        "invoke": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$", "description": "The /slice invocation key. Stable — renames break references. Unique across the whole file." },
+        "what": { "type": "string", "description": "One-line summary for the At-a-glance table" },
+        "est_sessions": { "type": "number", "minimum": 0, "description": "Focused Claude sessions remaining to clear this sprint (0 when done)" },
+        "shape": { "type": "string", "description": "agent-time task shape (e.g. localized-feature, refactor, migration-schema) — the primary classifier the estimator prices from. One of agent-time's SHAPES; validated there, not enum-checked here (avoids cross-repo vocab drift). Set it (+ optional risks) to make a slice estimable via 'roadmap estimate'." },
+        "risks": { "type": "array", "items": { "type": "string" }, "description": "agent-time risk factors (e.g. external-api, slow-flaky-tests) that skew the estimate right. From agent-time's RISKS vocabulary; validated there." },
+        "estimate": {
+          "type": "object", "additionalProperties": false,
+          "description": "Cached agent-time estimate — written by 'roadmap estimate', read by the timeline rollup. Not hand-authored; refresh with 'roadmap estimate <slice> --force'.",
+          "properties": {
+            "minutes": { "type": "object", "additionalProperties": false, "properties": { "low": { "type": "number" }, "expected": { "type": "number" }, "high": { "type": "number" } }, "description": "Wall-clock estimate (low/expected/high minutes)." },
+            "confidence": { "type": "string", "description": "Estimator confidence label (never 'high' by design)." },
+            "task_id": { "type": "string", "description": "agent-time task id — links this slice to its history record for the calibration log." },
+            "at": { "type": "string", "description": "ISO timestamp the estimate was produced." },
+            "basis": { "type": "string", "description": "Calibration basis (which history bucket + spread the estimate drew on)." }
+          }
+        },
+        "weight": { "enum": ["heavy", "medium", "light"], "description": "Optional override of the inferred resource weight (heavy=dotnet test, medium=build/vitest, light=docs); drives the concurrency recommender" },
+        "deps": { "type": "array", "items": { "type": "string" }, "description": "Dependency edges: sibling sprint id (s2), fully-qualified pi-id/sprint-id, or a PI id (complete-when-all-sprints-complete)" },
+        "touches": { "type": "array", "items": { "type": "string" }, "description": "Files this sprint writes; used to detect shared-file contention (two-wave) in the scheduler" },
+        "owns": { "type": "array", "items": { "type": "string" }, "description": "Dirs/files this sprint exclusively owns" },
+        "gate": { "type": "string", "description": "'default' (inherit meta.default_gate) or a string; {{default}} interpolates meta.default_gate" },
+        "gated_on": { "type": "string", "description": "Name of the human this is gated on; such a node never enters the auto-ready set" },
+        "optional": { "type": "boolean", "default": false },
+        "read_order": { "type": "array", "items": { "type": "string" }, "description": "Ordered docs/sections a session reads to self-orient (markdown link or 'path — note')" },
+        "resume_action": { "type": "string", "description": "The next action; first sentence is the immediate step" },
+        "kickoff_brief": { "type": "string", "description": "'brief' = synthesize from fields; or an inline brief string; or a path to a brief file" },
+        "prs": { "type": "array", "items": { "type": "string" }, "description": "Merged PR refs, e.g. ['#359']" },
+        "completed_on": { "type": "string", "description": "ISO date a sprint flipped to complete (drives the Recently-completed window)" },
+        "track": { "type": "string", "description": "Optional lane label for the three-track partition (e.g. A | B | C). --track filters a fanout to one lane. Omit for an untracked slice." },
+        "execution": { "$ref": "#/$defs/execution" },
+        "priority": { "$ref": "#/$defs/priority" },
+        "prompt": { "type": "string", "description": "Author-stashed pickup instructions, embedded VERBATIM in the synthesized kickoff brief and shown by /slice and roadmap show. Update as new info comes in (set_fields / roadmap set)." },
+        "milestone": { "type": "string", "description": "Optional stage name within the PI's Linear project (e.g. 'harness', 'hardening', 'ship'). Sync creates the distinct milestones per project and attaches this slice's issue — turning a project's flat issue list into legible stages. Project-scoped: the same name under two PIs is two milestones. Opt-in; absent everywhere → no milestone sync." },
+        "dispatch_tier": { "type": "string", "description": "Cloud-dispatch routine tier for this slice (e.g. 'fable' = a routine whose claude.ai model selector is set to the frontier tier). Dispatch resolves routines[\"<owner/repo>#<tier>\"] (or \"default#<tier>\") from ~/.claude-routines.json and THROWS if the tier isn't configured — a frontier slice never silently falls back to the standard routine. Absent: the standard repo routine. CLI --tier overrides per launch." },
+        "linear": { "type": "string", "description": "Linear issue identifier (e.g. ABC-123) this slice maps to — written back by the first push. The {linear} branch_convention token uses it so Linear auto-links the PR." }
+      }
+    },
+    "priority": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Optional prioritization: tier for coarse triage buckets, weight for fine ordering within a tier, reason so agents and humans know why. Sort order is derived (tier asc, weight desc), never stored. Shared by roadmap sprints and backlog items.",
+      "properties": {
+        "tier": { "enum": ["P0", "P1", "P2", "P3"] },
+        "weight": { "type": "number", "minimum": 0, "maximum": 100 },
+        "reason": { "type": "string" }
+      }
+    },
+    "execution": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Per-slice staffing-strategy HINT: how to fan this slice out (topology + suggested LIVE worker count + team composition). All fields optional and backward-compatible — a slice that omits the block behaves exactly as before; the lead chooses by gut. Rendered as an imperative directive so a launched session staffs at the declared topology instead of chronically under-parallelizing.",
+      "properties": {
+        "mode": {
+          "enum": ["solo", "subagents", "dynamic-workflow", "agent-team"],
+          "description": "Fan-out topology. solo = atomic/exploratory/branching-sequential (no fan-out). subagents = scoped sprint, lead-merges + disjoint-file workers (the current default). dynamic-workflow = an in-slice pipeline whose steps depend on each other. agent-team = many genuinely-independent file-clusters + peer coordination (native Agent Teams)."
+        },
+        "concurrency": { "type": "integer", "minimum": 1, "description": "Suggested LIVE worker count" },
+        "min_concurrency": { "type": "integer", "minimum": 1, "description": "Floor — warn/refuse if a run uses fewer on disjoint files. Must be ≤ concurrency when both are set." },
+        "team": { "type": "array", "description": "Team composition; omit for solo. When concurrency is also set, the head-count must agree.", "items": { "$ref": "#/$defs/execRole" } },
+        "rationale": { "type": "string", "description": "Why this topology + count (surfaced verbatim in the directive)" }
+      }
+    },
+    "execRole": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["role"],
+      "properties": {
+        "role": { "enum": ["verifier", "implementer", "reviewer", "researcher", "integrator"] },
+        "count": { "type": "integer", "minimum": 1, "default": 1, "description": "How many of this role (default 1)" }
+      }
+    }
+  }
+}