@hegemonart/get-design-done 1.59.3 → 1.59.4

package/scripts/skill-templates/review-backlog/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: gdd-review-backlog
+description: "Review parked backlog items and promote any to active cycle todo."
+tools: Read, Write, AskUserQuestion
+disable-model-invocation: true
+---
+
+# {{command_prefix}}review-backlog
+
+**Role:** Walk through parked backlog items and for each ask: promote to this cycle, keep parked, or archive.
+
+## Step 1 - Read backlog
+
+Read `.design/backlog/BACKLOG.md`. Parse each `## <title>` block with its metadata and body. If no parked items, print "No parked backlog items." and stop.
+
+## Step 2 - Loop
+
+For each item with `**Status**: parked`:
+
+Use `AskUserQuestion`:
+```
+Title: <title>
+Added: <date>
+<truncated body>
+
+Promote to this cycle | Keep parked | Archive
+```
+
+## Step 3 - Apply decision
+
+- **Promote**: append `- [ ] [YYYY-MM-DD] <title>` under `## P1 — High` in `.design/TODO.md` (create file from the TODO.md skeleton if missing). Update backlog item status to `**Status**: promoted` + `**Promoted**: YYYY-MM-DD`.
+- **Keep parked**: leave unchanged.
+- **Archive**: update status to `**Status**: archived` + `**Archived**: YYYY-MM-DD`.
+
+Rewrite `.design/backlog/BACKLOG.md` after each decision so crashes preserve progress.
+
+## Output
+
+```
+━━━ Backlog review ━━━
+Reviewed: 5
+Promoted: 2   Kept parked: 2   Archived: 1
+━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## REVIEW-BACKLOG COMPLETE

package/scripts/skill-templates/review-decisions/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: gdd-review-decisions
+description: "Surfaces the async decision-review queue for team mode. Reads .design/reviews/<decision-id>/ entries and reports each decision's state in the proposed → reviewing → approved → locked machine (via scripts/lib/collab/review-queue.cjs), so a team can see what's awaiting review, what's approved, and what's locked. --pending shows only decisions still needing action. Read-only - it reports the queue; it never advances a decision (that's a reviewer's explicit call). Use to run an async design-decision review without a meeting."
+argument-hint: "[<decision-id>] [--pending]"
+user-invocable: true
+tools: Read, Bash, Grep, Glob
+---
+
+# {{command_prefix}}review-decisions
+
+Closes the async-review gap for team mode: design decisions move through an explicit review queue
+instead of being decided in a single operator's head. This skill reports where each decision is.
+**Read-only** - it surfaces state; advancing a decision is a reviewer's explicit action. Contract:
+`../../reference/multi-author-model.md`.
+
+## Invocation
+
+| Command | Behavior |
+|---|---|
+| `{{command_prefix}}review-decisions` | Every decision in the queue, grouped by state. |
+| `{{command_prefix}}review-decisions <decision-id>` | One decision's state + audit trail. |
+| `{{command_prefix}}review-decisions --pending` | Only decisions not yet `locked` (awaiting action). |
+
+## Steps
+
+1. **Find the queue.** List `.design/reviews/*/` (each dir is a `<decision-id>`). No reviews dir →
+   print `review-decisions: no review queue yet (team mode not in use).` and exit.
+2. **Read each entry** (`.design/reviews/<id>/state.json` → `{ id, state, audit }`). Validate the
+   state against `scripts/lib/collab/review-queue.cjs` `STATES`.
+3. **Render** grouped by state: `proposed` / `reviewing` / `approved` / `locked`, each listing the
+   decision id + a one-line summary. For `--pending`, use `review-queue.pending(entries)` to show only
+   non-locked ones. For a single `<decision-id>`, also print its audit trail (transitions + approvers).
+4. **Do not advance.** Reporting only - moving a decision forward (or `{{command_prefix}}unlock-decision`) is the
+   reviewer's explicit call.
+
+## Output
+
+End with:
+
+```
+## REVIEW-DECISIONS COMPLETE
+```

package/scripts/skill-templates/roi/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: gdd-roi
+description: "Shows whether GDD spend actually shipped anything. Joins per-cycle cost (.design/telemetry/costs.jsonl) with what each cycle shipped - commits that SURVIVED in main vs commits that were reverted - and reports cost-per-shipped-commit + a stick rate per cycle. 'Shipped' = a commit surviving >= the window (default 14 days), which catches revert-after-bug-discovery. Markdown table, not a GUI. Read-only - it reads git log + cost telemetry and reports. Use to see which cycles were worth their spend."
+argument-hint: "[--since <date>] [--window-days 14]"
+user-invocable: true
+tools: Read, Bash, Grep, Glob
+---
+
+# {{command_prefix}}roi
+
+Closes the loop on cost: `{{command_prefix}}budget` forecasts *spend*, this shows the *return*. It joins per-cycle
+cost with the commits that actually stuck, so you can see cost-per-shipped-commit and which cycles
+were worth it. **Read-only** - it reads `git log` + cost telemetry and prints a table. Contract +
+the "shipped" definition: `../../reference/cost-governance.md`.
+
+## Invocation
+
+| Command | Behavior |
+|---|---|
+| `{{command_prefix}}roi` | ROI table across all cycles with cost telemetry (14-day stick window). |
+| `{{command_prefix}}roi --since <date>` | Only cycles since `<date>`. |
+| `{{command_prefix}}roi --window-days N` | "Shipped" = a commit surviving ≥ N days (default 14). |
+
+## Steps
+
+1. **Check telemetry exists.** No `.design/telemetry/costs.jsonl` (or zero rows) → print
+   `roi: no cost telemetry yet — run a cycle first.` and exit.
+2. **Per-cycle cost.** Group `est_cost_usd` in `costs.jsonl` by `cycle`.
+3. **Per-cycle shipped / reverted.** For each cycle, use `git log` to count, in that cycle's date
+   range: commits still present in `main` and older than the window = **shipped**; commits that a
+   later `revert` removed (or that were reverted within the window) = **reverted**. (A commit younger
+   than the window is "too new to score" - exclude it, don't count it as shipped.)
+4. **Join + compute** via the pure helper - never hand-compute:
+
+   ```bash
+   node -e '
+     const { computeRoi, roiTableMarkdown } = require("./scripts/lib/budget/roi.cjs");
+     const cycles = JSON.parse(process.argv[1]); // [{cycle,costUsd,commitsShipped,commitsReverted},...]
+     console.log(roiTableMarkdown(computeRoi(cycles)));
+   ' "$CYCLES_JSON"
+   ```
+
+5. **Render** the markdown table (cycle · cost · shipped · reverted · $/shipped · stick rate) plus the
+   TOTAL row. A high `$/shipped` with a low stick rate is the signal that a cycle burned budget
+   without lasting output.
+6. **Do not act.** Reporting only - never revert, re-run, or change budget.
+
+## Output
+
+End with:
+
+```
+## ROI COMPLETE
+```

package/scripts/skill-templates/rollout-status/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: gdd-rollout-status
+description: "Shows where a finished design cycle actually is in production rollout - unrolled / staging-only / canary-N% / prod-100% - by reading the feature-flag service (LaunchDarkly/Statsig/GrowthBook) via the rollout-coordinator. Surfaces STUCK rollouts (a canary that hasn't advanced for N days) and the design_arms outcome weighting. Read-only - GDD never advances or rolls back; it reports and notifies. Use after {{command_prefix}}ship to track the post-merge journey."
+argument-hint: "[<cycle>] [--all] [--stuck]"
+user-invocable: true
+tools: Read, Bash, Grep, Glob, ToolSearch, Task
+---
+
+# {{command_prefix}}rollout-status
+
+Closes the visibility gap after `{{command_prefix}}ship`: a PR merges, but staging → canary → 100% rollout happens outside GDD. This skill reports where each cycle's design actually is in production, by delegating to `agents/rollout-coordinator.md` (which reads the feature-flag service via the Phase 38 connections). **Read-only** - it reports + notifies; it never advances or rolls back a rollout. Contract + the `<rollout_status>` schema: `../../reference/rollout-coordination.md`.
+
+## Invocation
+
+| Command | Behavior |
+|---|---|
+| `{{command_prefix}}rollout-status` | The current cycle's rollout state (from `.design/STATE.md <rollout_status>`, refreshed via the coordinator). |
+| `{{command_prefix}}rollout-status <cycle>` | A specific cycle's rollout state. |
+| `{{command_prefix}}rollout-status --all` | Every cycle with a `<rollout_status>` block - a rollout dashboard. |
+| `{{command_prefix}}rollout-status --stuck` | Only the **stuck** rollouts (partial rollouts that haven't advanced for ≥ the threshold). |
+
+## Steps
+
+1. **Probe the flag service.** Check a flag connection is `available` (`connections/launchdarkly.md` / `statsig.md` / `growthbook.md`). None → print `rollout-status: no flag service configured — connect one via {{command_prefix}}connections.` and exit.
+2. **Delegate to `rollout-coordinator`** (via `Task`): it reads the service, classifies via `scripts/lib/rollout/rollout-status.cjs`, refreshes the `<rollout_status>` block, and reports state + deployed % + stuck.
+3. **Render.** Show each cycle: `state` · `deployed_pct` · `last_changed` · `stuck?`. For `--stuck`, list only stuck cycles with the days-since-change and an advance-or-rollback suggestion.
+4. **Do not act.** Never run a flag-service mutation, advance a canary, or roll back - GDD reports; the human + the flag service decide.
+
+## Output
+
+End with:
+
+```
+## ROLLOUT-STATUS COMPLETE
+```

package/scripts/skill-templates/router/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: gdd-router
+description: "Routes a /gdd command to fast|quick|full path + S|M|L|XL complexity_class and returns {path, complexity_class, model_tier_overrides, resolved_models, estimated_cost_usd, cache_hits}. Deterministic - no model call. Invoked once at command entry before any Agent spawn. Read by hooks/budget-enforcer.ts."
+argument-hint: "<intent-string> [<target-artifacts-csv>]"
+tools: Read, Bash, Grep
+---
+
+# gdd-router
+
+## Role
+
+You are a deterministic routing skill. You do not spawn agents. You read `.design/budget.json`, `reference/model-prices.md`, `.design/cache-manifest.json` (if present), and the agent frontmatter list, then emit a single JSON object describing the planned spawn graph. The budget-enforcer hook (`hooks/budget-enforcer.ts`) consumes your output on every `Agent` tool call.
+
+## Invocation Contract
+
+- **Input**: `intent-string` (e.g., `"run discover stage on greenfield project"`) + optional comma-separated list of target artifacts (files this command will touch).
+- **Output**: a single JSON object to stdout - nothing else on the line, no prose wrapper:
+  ```json
+  {
+    "path": "fast",
+    "complexity_class": "M",
+    "model_tier_overrides": {"design-verifier": "haiku"},
+    "resolved_models": {
+      "design-reflector": "gpt-5",
+      "design-context-checker": "gpt-5-nano",
+      "design-verifier": "gpt-5-nano"
+    },
+    "estimated_cost_usd": 0.034,
+    "cache_hits": ["design-context-builder:abc123"]
+  }
+  ```
+- `path` enum: `fast` (single Haiku + no checkers), `quick` (Sonnet mappers + Haiku verify), `full` (Opus planners + full quality gates). Stays unchanged for back-compat per D-05.
+- `complexity_class` enum: `S | M | L | XL` (Phase 25 / D-04, D-05). Additive to `path` - existing consumers reading only `path` keep working. Mapping is documented in the Path Selection Heuristic table below.
+- `model_tier_overrides` merges agent frontmatter `default-tier` with `.design/budget.json.tier_overrides` - budget.json wins per D-04. Enum stays `opus|sonnet|haiku` for back-compat across all 14 runtimes; consumers that need the **concrete** model name for the active runtime read `resolved_models` instead.
+- `resolved_models` is a per-agent map of concrete model IDs for the runtime in use (Phase 26 / D-07). Keys are agent names; values are runtime-specific model strings (e.g. `"gpt-5"` under codex, `"gemini-2.5-pro"` under gemini, `"claude-opus-4-7"` under claude) or `null` when the resolver can supply no model (missing tier-map row, missing tier on the row). Additive to `model_tier_overrides` - existing consumers reading the tier-name map keep working unchanged; new consumers (budget-enforcer cost computation, cost telemetry, bandit posterior store) read `resolved_models` for runtime-correct cost. See **Runtime-aware model resolution** below for the computation contract.
+- `estimated_cost_usd` is the sum of per-spawn estimates using the D-06 formula and `reference/model-prices.md`.
+- `cache_hits` is a list of `{agent}:{input-hash}` strings that exist in `.design/cache-manifest.json` and are within TTL; emitting a hit lets the hook short-circuit that spawn per D-05.
+
+### Output schema versioning
+
+The router output contract is additive across phases. The current shape (Phase 26, v1.26.0) carries:
+
+| Field | Added in | Status |
+|-------|----------|--------|
+| `path` | v1.10.1 (10.1-01) | stable |
+| `model_tier_overrides` | v1.10.1 (10.1-01) | stable, enum unchanged |
+| `estimated_cost_usd` | v1.10.1 (10.1-01) | stable |
+| `cache_hits` | v1.10.1 (10.1-01) | stable |
+| `complexity_class` | v1.25.0 (25-02) | stable, additive |
+| `resolved_models` | v1.26.0 (26-04) | stable, additive |
+
+Existing consumers reading any subset of the older fields keep working unchanged across these bumps - the schema is a strict superset at every phase boundary. New fields are documented inline in this skill rather than in a separate JSON-schema file (the SKILL is the contract - same convention Phase 25 followed for `complexity_class`).
+
+## Path Selection Heuristic
+
+The router emits `path` (3-tier: `fast|quick|full`, legacy enum, stable for back-compat) AND `complexity_class` (4-tier: `S|M|L|XL`, Phase 25 / D-04 additive). Full mapping table, bucket-assignment signal list, `--dry-run` downgrade rule, and the S-class short-circuit semantics live in `./router-rules.md#path-selection-heuristic`. The S-class short-circuit is essential: when `complexity_class` would be `S`, the router does not run; the deterministic skip list lives in the `{{command_prefix}}*` SKILL.md entry, and the budget-enforcer hook treats "no payload + matching command name" as the S signal.
+
+## Cost Estimation Algorithm
+
+Standard cost-estimation pseudocode (sum over planned spawn graph; per-agent `(in_tok / 1e6) * in_rate + (out_tok / 1e6) * out_rate` using `./reference/model-prices.md`) lives in `./router-rules.md#cost-estimation-algorithm`.
+
+## Runtime-aware model resolution
+
+Computation contract for `resolved_models`, implementation surfaces (`scripts/lib/runtime-detect.cjs` + `scripts/lib/tier-resolver.cjs`), per-agent emission rules (including the JSON-`null` contract), and the Claude-runtime back-compat assertion live in `./router-rules.md#runtime-aware-model-resolution`. Top-line: `model_tier_overrides` keeps its `opus|sonnet|haiku` enum for back-compat; `resolved_models` runs the per-runtime translation additively on top.
+
+## Cache-Hit Detection
+
+Delegate to `skills/cache-manager/SKILL.md` (Plan 10.1-02). The router lists candidate `{agent}:{input-hash}` tuples; the cache-manager confirms freshness against TTL from `budget.json.cache_ttl_seconds`.
+
+## Integration Point
+
+Every `{{command_prefix}}*` SKILL.md's first substantive step is: spawn the router via `Task` or inline invocation; receive the JSON blob; pass it to downstream agents as context so the budget-enforcer hook has the router decision available in tool_input metadata when the first Agent spawn fires.
+
+## Failure Modes
+
+If `.design/budget.json` is missing, assume defaults from `reference/config-schema.md` per D-12. If `reference/model-prices.md` is missing, emit `estimated_cost_usd: null` and log a warning - do not block.
+
+## Emitting capability_gap on unmatched intent
+
+When the router cannot resolve `intent-string` to a known agent (no `description` match, no `default-tier` rule, no path-selection fallback), emit ONE `capability_gap` event with `source: "router"` before returning the conservative-fallback JSON. Feeds Phase 29 Stage-0 telemetry - see `./capability-gap-emitter.md` for the synchronous Node snippet, semantic notes (suggested_kind = `"agent"`, MCP-probe exclusion per D-08, back-compat invariant on router output), and the opaque-extras payload routing through `appendChainEvent`.
+
+## Emitting router_pick on a resolved pick
+
+When the router DID resolve a pick - it has the `path`/`complexity_class`/`resolved_models` decision and is about to return the decision JSON - emit ONE `router_pick` event (`source: "router"`) recording which skill/agent was auto-picked, as the last step before returning. Side-effect only; the output JSON contract is UNCHANGED. Feeds the D-02 under-reached-skill instrument (Phase 33 baselines per-skill pick rates) - see `./router-pick-emitter.md` for the synchronous Node snippet, the 7-field no-PII payload (context_hash only - never the raw prompt), and the opaque-extras routing through `appendChainEvent`.
+
+## Non-Goals
+
+The router does not: (a) make a model call, (b) write files, (c) enforce budget caps (that's the hook's job), (d) learn from history (Phase 11 reflector territory per D-07).
+The router does not author capability-gap CLUSTERS - Stage-0 emit is single-event-per-failure. Aggregation across events is Plan 29-03's reflector pass.

package/scripts/skill-templates/router/capability-gap-emitter.md

@@ -0,0 +1,65 @@
+# gdd-router - capability_gap emitter (Phase 29 / D-02 / D-08)
+
+Co-located reference for `skills/router/SKILL.md` - split out per Phase 28.5
+contract (router SKILL ≤100 lines) and the Phase 28.6 co-location pattern.
+
+## When to emit
+
+If the router cannot resolve `intent-string` to a known agent (no agent's
+`description` field matches, no `default-tier` rule applies, and the fallback
+path-selection table returns nothing meaningful), emit ONE `capability_gap`
+event before returning the conservative-fallback JSON output to the caller.
+
+This feeds Phase 29 Stage-0 telemetry - the reflector pattern-detection pass
+(Plan 29-02) and aggregation (Plan 29-03) read these events from the chain
+file (`.design/gep/events.jsonl`) to surface recurring router-unmatched
+intents as candidate agents in `{{command_prefix}}apply-reflections`.
+
+## Synchronous emitter snippet
+
+Same shape as fast, with `source: "router"`:
+
+```bash
+node -e '
+const { appendChainEvent } = require("./scripts/lib/event-chain.cjs");
+const { createHash, randomUUID } = require("node:crypto");
+const intent = process.env.GDD_INTENT || "";
+const payload = {
+  event_id: randomUUID(),
+  parent_event_id: null,
+  source: "router",
+  context_hash: createHash("sha256").update(intent).digest("hex"),
+  intent_summary: intent.slice(0, 256),
+  suggested_kind: "agent",
+  evidence_refs: [],
+};
+appendChainEvent({
+  agent: "router",
+  outcome: "capability_gap",
+  payload,
+  type: "capability_gap",
+  timestamp: new Date().toISOString(),
+  sessionId: process.env.GDD_SESSION_ID || "router-cli",
+});
+'
+```
+
+## Notes
+
+- `suggested_kind` is `"agent"` because router unmatched intents typically
+  describe multi-step workflows (the unit the router resolves).
+- Router-unmatched is NOT the same as MCP-probe failure (per D-08). If
+  gdd-router returns a fallback because a peer-CLI connection is down, do
+  NOT emit capability_gap - that's a Phase 22 connection-status concern.
+- The emitter is the LAST step before returning the fallback JSON. Router
+  output is unchanged (back-compat per the existing `## Output schema
+  versioning` table in `SKILL.md`); the event is a SIDE EFFECT, not a
+  payload addition.
+- Router output JSON contract is UNCHANGED - back-compat preserved.
+- The 7-field payload flows through `appendChainEvent`'s opaque-extras
+  pattern verbatim; the chain row carries `type`, `timestamp`, `sessionId`,
+  `payload` as opaque extras and is projected back to the events-schema
+  envelope by Plan 29-03 aggregation.
+
+MCP-probe failures (connection down, transport-layer errors) do NOT emit
+`capability_gap` - those are Phase 22 connection-status concerns (D-08).

package/scripts/skill-templates/router/router-pick-emitter.md

@@ -0,0 +1,78 @@
+# gdd-router - router_pick emitter (Phase 32-08 / D-02)
+
+Co-located reference for `skills/router/SKILL.md` - split out per the Phase 28.5
+contract (router SKILL ≤100 lines) and the Phase 28.6 co-location pattern (same
+convention as the sibling `./capability-gap-emitter.md`).
+
+## When to emit
+
+When the router resolves an intent to a concrete pick - i.e. it has selected the
+`path` / `complexity_class` / `resolved_models` decision and is about to return
+its decision JSON - emit ONE `router_pick` event recording WHICH skill/agent it
+auto-picked. Emit exactly once per resolved pick, as the LAST step before
+returning the decision JSON to the caller.
+
+This is the D-02 router_pick instrument: GDD routes by description-match but has
+no record of what the router actually reaches for, so there is no data on
+under-reached skills. Phase 33 reads these events from the chain file
+(`.design/gep/events.jsonl`) to baseline per-skill auto-pick rates (the
+"pick-rate regression" expansion in the ROADMAP).
+
+`router_pick` is NOT `capability_gap`: emit `router_pick` when the router DID
+resolve a pick; emit `capability_gap` (see `./capability-gap-emitter.md`) only
+when it could not resolve the intent at all. They are disjoint surfaces.
+
+## Synchronous emitter snippet
+
+Builds the 7-field `RouterPickPayload` and writes it via `appendChainEvent`.
+The intent is hashed - the raw prompt is NEVER stored (no PII). `picked_skill`,
+`rank`, and `alternatives` come from the router's resolved decision:
+
+```bash
+node -e '
+const { appendChainEvent } = require("./scripts/lib/event-chain.cjs");
+const { createHash, randomUUID } = require("node:crypto");
+const intent = process.env.GDD_INTENT || "";
+const payload = {
+  event_id: randomUUID(),
+  source: "router",
+  picked_skill: process.env.GDD_PICKED_SKILL || "",
+  context_hash: createHash("sha256").update(intent).digest("hex"),
+  rank: Number(process.env.GDD_PICK_RANK || 0),
+  alternatives: (process.env.GDD_ALTERNATIVES || "").split(",").filter(Boolean),
+  ts: new Date().toISOString(),
+};
+appendChainEvent({
+  agent: "router",
+  outcome: "router_pick",
+  payload,
+  type: "router_pick",
+  timestamp: new Date().toISOString(),
+  sessionId: process.env.GDD_SESSION_ID || "router-cli",
+});
+'
+```
+
+`GDD_PICKED_SKILL` is the resolved pick; `GDD_PICK_RANK` is its rank among
+candidates (0 = top pick); `GDD_ALTERNATIVES` is a comma-separated list of the
+OTHER candidate skill/agent names the router considered (names only - no scores,
+no prompt text). `GDD_INTENT` is hashed in-process and is never written to disk.
+
+## Notes
+
+- **No PII**: only `context_hash` (sha256 of the intent) is stored - never the
+  raw prompt or intent string. The `RouterPickPayload` is
+  `additionalProperties: false`, so a stray `raw_prompt` field would be rejected
+  by `events.schema.json` validation. This mirrors `capability_gap`'s hash
+  discipline.
+- **Router output JSON contract is UNCHANGED** - `router_pick` is a SIDE EFFECT,
+  not a new output field. Back-compat is preserved exactly as the existing
+  `## Output schema versioning` table in `SKILL.md` guarantees; the emitter runs
+  AFTER the decision is computed and does not alter the returned blob.
+- The 7-field payload flows through `appendChainEvent`'s opaque-extras pattern
+  verbatim; the chain row carries `type`, `timestamp`, `sessionId`, `payload` as
+  opaque extras and is projected back to the events-schema envelope by Phase 33
+  aggregation (same projection the capability_gap aggregation uses).
+- Validated against the additive `RouterPickPayload` branch (allOf[2]) in
+  `reference/schemas/events.schema.json` - see
+  `test/suite/router-pick-event.test.cjs`.

package/scripts/skill-templates/router/router-rules.md

@@ -0,0 +1,84 @@
+---
+name: router-rules
+type: heuristic
+version: 1.0.0
+phase: 28.5
+tags: [router, path-selection, complexity-class, model-tier, runtime-resolution, cost-estimation]
+last_updated: 2026-05-18
+---
+
+# Router Path-Selection + Runtime Resolution Rules
+
+Extracted from `skills/router/SKILL.md` per Phase 28.5 D-10 (extract-then-link, never delete
+content). The router SKILL keeps its invocation contract, output schema versioning table,
+integration point, and failure modes. The path-selection heuristic tables, the cost
+estimation algorithm, and the runtime-aware model resolution computation contract live
+here so the SKILL stays under the 100-line cap.
+
+## Path Selection Heuristic
+
+The router emits both `path` (legacy 3-tier enum) and `complexity_class` (Phase 25 4-tier enum). The canonical mapping is:
+
+| complexity_class | path | Behavior |
+|------------------|------|----------|
+| `S` | `fast` (short-circuited) | Skip router itself, skip cache-manager, skip telemetry write. Deterministic no-op decision. |
+| `M` | `fast` | Single Haiku + no checkers. |
+| `L` | `quick` | Sonnet mappers + Haiku verify. |
+| `XL` | `full` | Opus planners + full quality gates. Recommends worktree-isolation default + mandatory inter-stage checkpoint + reflector auto-spawn. |
+
+Bucket assignment:
+
+| Signal | complexity_class | path |
+|--------|------------------|------|
+| Command is `{{command_prefix}}help`, `{{command_prefix}}stats`, `{{command_prefix}}note`, `{{command_prefix}}health`, single-Haiku skill | `S` | `fast` (short-circuited - see below) |
+| Command is `{{command_prefix}}scan`, `{{command_prefix}}brief`, `{{command_prefix}}sketch`, `{{command_prefix}}spike`, `{{command_prefix}}fast` | `M` | `fast` |
+| Command spawns exactly one agent (no orchestration), not in S list | `M` | `fast` |
+| Command is `{{command_prefix}}explore`, `{{command_prefix}}discover`, standalone `{{command_prefix}}verify`, standalone `{{command_prefix}}plan` | `L` | `quick` |
+| Command spawns parallel mappers but no planners/auditors (`{{command_prefix}}discover` in `--auto` mode) | `L` | `quick` |
+| Command is `{{command_prefix}}next`, `{{command_prefix}}do`, `{{command_prefix}}autonomous`, end-to-end Brief→Verify, anything spawning planners + auditors + verifiers in series | `XL` | `full` |
+| Command spawns planners, auditors, verifiers, or integration-checkers (`{{command_prefix}}plan`, `{{command_prefix}}verify`, `{{command_prefix}}audit`) and is not standalone | `XL` | `full` |
+| `--dry-run` flag present on any command | downgrade one tier (XL→L→M→S; `path` follows the mapping table) |
+
+### S-class short-circuit
+
+When `complexity_class` would be `S`, the router itself **does not run** for that invocation - the deterministic skip list is encoded in the `{{command_prefix}}*` SKILL.md entry of the matching command. The budget-enforcer hook treats "no router decision payload + matching command name" as the S-class signal and skips enforcement entirely (no telemetry row, no cache lookup, no event emission). When the router *is* invoked explicitly (e.g., debugging) it still emits `complexity_class: "S"` in the JSON for observability, but the runtime path is the no-op.
+
+## Cost Estimation Algorithm
+
+```
+total = 0
+for each agent in planned spawn graph:
+  tier = resolve_tier(agent)   # budget.json tier_overrides > agent frontmatter default-tier
+  (in_tok, out_tok) = token_range_from_size_budget(agent.size_budget)  # from reference/model-prices.md
+  (in_rate, out_rate) = price_from_tier(tier)
+  total += (in_tok / 1e6) * in_rate + (out_tok / 1e6) * out_rate
+return total
+```
+
+## Runtime-aware model resolution
+
+The router emits `resolved_models` alongside `model_tier_overrides` so downstream consumers (budget-enforcer cost computation, Phase 22 cost telemetry, Phase 23.5 bandit posterior store) can read the **concrete model ID** for the active runtime without re-deriving it from the tier name. The resolution is per-agent and additive - `model_tier_overrides` keeps its `opus|sonnet|haiku` enum for back-compat across all 14 runtimes, and `resolved_models` runs the runtime-specific translation on top of it.
+
+Computation contract (per D-07):
+
+```
+runtime = runtimeDetect.detect() ?? 'claude'
+for each agent in planned spawn graph:
+  tier = resolve_tier(agent)                          # same merge as model_tier_overrides
+  resolved_models[agent] = tierResolver.resolve(runtime, tier)
+                                                       # → concrete model string OR null
+```
+
+Implementation surfaces (Phase 26 / Wave A):
+
+- `scripts/lib/runtime-detect.cjs` - `detect() → runtime-id | null`. Reads the same `*_CONFIG_DIR` / `*_HOME` env-vars Phase 24's installer uses (single source of truth in `scripts/lib/install/runtimes.cjs`). Returns `null` when no recognized runtime env-var is set; the router falls back to `'claude'` so the resolver always has a runtime ID to work with.
+- `scripts/lib/tier-resolver.cjs` - `resolve(runtime, tier, opts?) → model | null`. Translates `opus|sonnet|haiku` to the concrete model the runtime understands using the `./runtime-models.md` mapping (Phase 26 / Wave A). Fallback chain (D-04): runtime-specific entry → `claude` row default with `tier_resolution_fallback` event → `null` with `tier_resolution_failed` event. Never throws; `null` is a valid output the consumer must handle.
+
+Per-agent emission rules:
+
+- One key per agent in the planned spawn graph (same key set the cost-estimation loop iterates over). Keys MUST match agent names exactly so consumers can join `resolved_models` against `model_tier_overrides` and the spawn graph by name.
+- Value is the concrete model string returned by `tier-resolver.resolve(runtime, tier)`.
+- When the resolver returns `null` (missing tier-map row, missing tier, garbage input), the value is JSON `null` - NOT omitted, NOT the empty string. Consumers (budget-enforcer, telemetry) MUST handle `null`: typically by skipping the cost row for that spawn and emitting their own diagnostic event, never by crashing.
+- When `complexity_class` is `S` and the router itself short-circuits (see **S-class short-circuit** above), no payload is emitted at all and `resolved_models` does not exist for that invocation - the budget-enforcer's "no router decision payload" branch already handles this case.
+
+Back-compat assertion: a router invocation in a Claude runtime (or any environment where `runtime-detect.detect()` returns `null` and the router falls back to `'claude'`) produces `resolved_models` values that are the canonical Anthropic model IDs (`claude-opus-4-7`, `claude-sonnet-4-6`, `claude-haiku-4-5`) for the corresponding tiers. Pre-Phase-26 consumers that ignore `resolved_models` see the same `model_tier_overrides` they always saw (Plan 26-09 owns the runtime fixture diff that asserts this).

package/scripts/skill-templates/settings/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: gdd-settings
+description: "Manage .design/config.json settings. Subcommands: profile, parallelism, cleanup, show."
+argument-hint: "<profile <name>|parallelism <key> <value>|cleanup|show>"
+tools: Read, Write, AskUserQuestion, Bash, mcp__gdd_state__get, mcp__gdd_state__frontmatter_update
+disable-model-invocation: true
+---
+
+# gdd-settings
+
+Manages `.design/config.json` - the per-project config for model profile and parallelism. See `reference/config-schema.md` for the full schema. This skill also supports patching non-stage STATE.md frontmatter keys (`cycle`, `wave`, custom keys) via `mcp__gdd_state__frontmatter_update`. See **STATE.md frontmatter** below.
+
+## Subcommands
+
+### `show`
+
+Print the current `.design/config.json` contents, nicely formatted. If the file is missing, print the defaults with a note that no config exists yet. Also call `mcp__gdd_state__get` to print the current STATE.md frontmatter keys (cycle, wave, model_profile) alongside config.json for a unified view.
+
+### `profile <name>`
+
+Set `model_profile` to one of `quality`, `balanced`, `budget`. Validate the value; reject anything else with the list of allowed values. Read current config, merge the change, write back. Confirm with the new value.
+
+### `parallelism <key> <value>`
+
+Set one field under `parallelism`. Supported keys and value types:
+
+| Key | Type |
+|---|---|
+| `enabled` | bool (`true`/`false`) |
+| `max_parallel_agents` | int |
+| `min_tasks_to_parallelize` | int |
+| `min_estimated_savings_seconds` | int |
+| `require_disjoint_touches` | bool |
+| `worktree_isolation` | bool |
+
+Validate type; reject otherwise. Read current config, merge, write back. Confirm.
+
+### `cleanup`
+
+Use `AskUserQuestion` to pick one or more cleanup actions, then confirm each before executing:
+
+1. Delete `.design/*.md` artifacts (excludes `config.json`, `STATE.md`, `backlog/`).
+2. Reset `.design/STATE.md` to the template at `reference/STATE-TEMPLATE.md`.
+3. Clear `.design/backlog/` directory contents.
+
+## Config Read/Write Pattern
+
+Always:
+
+1. Read current `.design/config.json` (use defaults below if missing).
+2. Merge the single field being changed - never overwrite unrelated fields.
+3. Write back as pretty JSON (2-space indent, trailing newline).
+
+## STATE.md frontmatter
+
+For any STATE.md frontmatter patch (cycle, wave, or project-custom keys), call `mcp__gdd_state__frontmatter_update({ patch: { <key>: <value> } })`. Do not `Edit` or `Write` STATE.md directly.
+
+**Stage-patch guard:** this skill cannot patch `stage`. If the user attempts to set `stage` here, reject with: "Use {{command_prefix}}brief, {{command_prefix}}explore, etc. for stage transitions. The settings skill is for non-stage frontmatter only." The MCP tool itself rejects `stage` patches with a VALIDATION error (surfaced by `mcp__gdd_state__frontmatter_update`), which this prose surfaces up-front so the user gets a clear message before the tool round-trip.
+
+This surface is STATE.md-only. `.design/config.json` mutations continue to use `Read` + `Write` directly (out of scope for the 11-tool MCP catalog).
+
+## Default Config
+
+If `.design/config.json` does not exist, create it with:
+
+```json
+{
+  "model_profile": "balanced",
+  "parallelism": {
+    "enabled": true,
+    "max_parallel_agents": 5,
+    "min_tasks_to_parallelize": 2,
+    "min_estimated_savings_seconds": 30,
+    "require_disjoint_touches": true,
+    "worktree_isolation": false,
+    "per_stage_override": {}
+  }
+}
+```
+
+## Output
+
+End every invocation with:
+
+```
+## SETTINGS COMPLETE
+```

package/scripts/skill-templates/ship/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: gdd-ship
+description: "Post-verify PR flow - creates a clean PR branch, invokes code review check, and prepares the PR for merge. Activates for requests involving finishing a cycle, packaging design output, or moving work to a pull request."
+argument-hint: "[--title <PR title>] [--draft]"
+tools: Read, Write, Bash, AskUserQuestion, Task
+disable-model-invocation: true
+---
+
+# {{command_prefix}}ship
+
+Closes the verify → merge gap: runs `{{command_prefix}}pr-branch` for a clean branch, assembles a PR body from design artifacts, and creates the PR via `gh`.
+
+## Steps
+
+1. **Pre-flight verify check**: Check that `.design/DESIGN-VERIFICATION.md` exists and shows a pass. If missing or failing, ask: "Verify has not completed / failed. Ship anyway? (yes/no)"
+2. **Clean branch**: Invoke `{{command_prefix}}pr-branch` to produce a branch with only `src/` commits (no `.design/` or `.planning/` noise). Use the resulting branch for the PR.
+3. **PR title**: Use `--title` argument if given, otherwise ask (AskUserQuestion): "PR title?"
+4. **PR body**: Auto-generate from:
+   - Goals section of `.design/DESIGN-PLAN.md`
+   - Summary of `.design/DESIGN-VERIFICATION.md` (per-task pass/fail)
+   - Top-line audit score from `.design/DESIGN-AUDIT.md` if present
+   Format as Markdown with `## Goals`, `## Verification`, `## Audit` sections.
+5. **Create PR**: Run `gh pr create --title "<title>" --body "<body>" [--draft]` via Bash. If `gh` is not installed, print the full body and instruct the user to create the PR manually.
+6. **Print PR URL** on success.
+
+## Do Not
+
+- Do not push to `main`/`master` directly.
+- Do not include `.design/` or `.planning/` files in the PR branch - that is `{{command_prefix}}pr-branch`'s job.
+- Do not skip the verify pre-flight silently - always surface a failure and ask.
+
+## Step 6.5 - PR inline review surface (pr-commenter)
+
+ONLY on the success path - after the PR has been created (Step 5) and its URL printed (Step 6) - spawn `agents/pr-commenter.md` via the `Task` tool to post GDD's verify/audit output **inline** on the new PR: inline review comments on changed lines, Preview/Chromatic before-after screenshot pairs, and the `gdd/design-review` check-run (audit pillar scores + verify pass/fail + a11y). Pass the PR number + `owner/repo` in the Task context.
+
+This is a **degrade-to-noop** surface and MUST NOT fail the ship: if `gh` is unavailable, the `GDD_DISABLE_PR_COMMENTER` kill-switch (env or `.design/config.json`) is set, or the agent errors, the ship still succeeds (pr-commenter prints the bodies for manual paste). Skip this step entirely if PR creation failed in Step 5. The posting contract (gh-api shapes, check-run payload, redaction, branch-protection setup) lives in `reference/pr-review-integration.md`.
+
+## Step 7 - Update notice (post-closeout surface)
+
+ONLY on the success path - after the PR has been created and the URL has been printed - emit the plugin-update banner. If PR creation failed earlier, skip this step (do not suggest upgrades in the middle of a PR-creation failure).
+
+```bash
+[ -f .design/update-available.md ] && cat .design/update-available.md
+```
+
+Written by `hooks/update-check.sh`; suppressed mid-pipeline and when the latest release is dismissed.
+
+## SHIP COMPLETE