@hegemonart/get-design-done 1.31.5 → 1.32.0

package/.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "Get Design Done — 5-stage agent-orchestrated design pipeline with 9 connections, handoff-first workflow, bidirectional Figma write-back, 22+ specialized agents, queryable knowledge layer (intel store, dependency analysis, learnings extraction), and a self-improvement loop (reflector, frontmatter + budget feedback, global-skills layer). v1.20.0 ships the SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream, and resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) for rate-limit + 429 + context-overflow recovery. Full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows) and release automation (auto-tag + GitHub Release + release-time smoke test).",
-    "version": "1.31.5"
+    "version": "1.32.0"
   },
   "plugins": [
     {
       "name": "get-design-done",
       "source": "./",
       "description": "Agent-orchestrated 5-stage design pipeline: Brief → Explore → Plan → Design → Verify. 22+ specialized agents, 9 connections (Figma, Refero, Preview, Storybook, Chromatic, Figma Writer, Graphify, Pinterest, Claude Design), Claude Design handoff, bidirectional Figma write-back, and a queryable intel store (.design/intel/) for dependency and learnings queries. Standalone commands: style, darkmode, compare, figma-write, graphify, handoff, analyze-dependencies, skill-manifest, extract-learnings. Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, and anti-pattern catalog. Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows) and release automation. Optimization layer (v1.0.4.1, retroactive): gdd-router + gdd-cache-manager skills, PreToolUse budget-enforcer hook, tier-aware agent frontmatter, lazy checker gates, streaming synthesizer, /gdd:warm-cache + /gdd:optimize commands, and cost telemetry at .design/telemetry/costs.jsonl — targeting 50-70% per-task token-cost reduction with no quality-floor regression. v1.20.0 SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream at .design/telemetry/events.jsonl, resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) with rate-limit + 429 + context-overflow recovery, and TypeScript toolchain.",
-      "version": "1.31.5",
+      "version": "1.32.0",
       "author": {
         "name": "hegemonart"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "get-design-done",
   "short_name": "gdd",
-  "version": "1.31.5",
+  "version": "1.32.0",
   "description": "Agent-orchestrated 5-stage design pipeline: Brief → Explore → Plan → Design → Verify. 22+ specialized agents, 9 connections (Figma, Refero, Preview, Storybook, Chromatic, Figma Writer, Graphify, Pinterest, Claude Design), handoff-first workflow via Claude Design bundles, bidirectional Figma write-back (annotations, Code Connect), queryable intel store (`.design/intel/`) for O(1) design surface lookups, and self-improvement loop (reflector agent, frontmatter + budget feedback, global-skills layer at `~/.claude/gdd/global-skills/`). Standalone commands: style, darkmode, compare, figma-write, graphify, handoff, analyze-dependencies, skill-manifest, extract-learnings, reflect, apply-reflections. Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, and anti-pattern catalog. Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows, lint + schema + frontmatter + stale-ref + shellcheck + gitleaks + injection-scan + blocking size-budget) and release automation (auto-tag + GitHub Release + release-time smoke test). Optimization layer (v1.0.4.1, retroactive): gdd-router + gdd-cache-manager skills, PreToolUse budget-enforcer hook, tier-aware agent frontmatter, lazy checker gates, streaming synthesizer, /gdd:warm-cache + /gdd:optimize commands, and cost telemetry at .design/telemetry/costs.jsonl — targeting 50-70% per-task token-cost reduction with no quality-floor regression. v1.20.0 SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream at .design/telemetry/events.jsonl, resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) with rate-limit + 429 + context-overflow recovery, and TypeScript toolchain. v1.27.7 ships gdd-mcp (Phase 27.7): 12 read-only MCP tools for sub-3s priming. v1.28.0 (Phase 28): Foundational References Tier 2 — 5 new reference files (color-theory, composition, proportion-systems, i18n, contrast-advanced), 2 verifier i18n probes + 1 explore i18n-readiness probe, 12 additive cross-link insertions across 10 existing references, 2 orthogonal audit-scoring lens-tags (composition_alignment + i18n_readiness).",
   "author": {
     "name": "hegemonart",

package/CHANGELOG.md

@@ -4,6 +4,37 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [1.32.0] - 2026-05-30
+
+### Phase 32 — Skill Auto-Trigger Discipline + Defensive Guardrails
+
+Closes the auto-trigger gap between GDD's 70+ skills and the harness's description-match skill-discovery layer. GDD had zero forcing functions — agents consulted skills opportunistically, not disciplinedly. This release ports the skill-discipline **mechanism** (not content) from [`obra/superpowers`](https://github.com/obra/superpowers) (MIT): a SessionStart-injected bootstrap contract, defensive guardrails at every stage transition, and two lightweight skill-discovery instruments that feed Phase 33's behavioral A/B. 9 plans across Waves A–C.
+
+### Added
+
+- **`using-gdd` SessionStart bootstrap (the forcing function GDD lacked).** A new `skills/using-gdd/SKILL.md` discipline contract — the **1%-rule** ("if you think there is even a 1% chance a skill applies, you ABSOLUTELY MUST invoke it"), a ≥10-row **red-flags table** (Thought → Reality), a skill-priority order (Process → Implementation → Audit), an instruction-priority precedence (user CLAUDE.md > GDD skill > defaults), and the GDD pipeline flow. Carries `disable-model-invocation: true` (it is injected, not model-invoked) and a pure-trigger description (no `<what>` clause, per superpowers' shortcut finding — proof-by-implementation; Phase 28.5's description-format validator stays open pending Phase 33's A/B evidence).
+- **Per-harness SessionStart inject emitter.** `hooks/inject-using-gdd.sh` is a single polyglot script that reads `using-gdd` and emits it as the host harness's SessionStart `additionalContext` shape — Cursor (`additional_context`), Claude Code (`hookSpecificOutput.additionalContext`), and SDK-standard (top-level `additionalContext`) branches via env-var detection, with a pure-bash JSON escaper (no jq/python dependency). A `hooks/run-hook.cmd` polyglot Windows wrapper and a 5th `hooks/hooks.json` SessionStart entry (matcher `startup|clear|compact`) wire it in.
+- **`<SUBAGENT-STOP>` no-cascade structural guarantee.** The inject is wired ONLY under the SessionStart hook event; subagent spawns do not fire SessionStart, so the bootstrap contract cannot cascade into a subagent's context. The `using-gdd` body opens with a `<SUBAGENT-STOP>` tag. (Structural guarantee here; the behavioral proof under pressure is deferred to Phase 33.)
+- **`<HARD-GATE>` at the 5 stage transitions.** `skills/{brief,explore,plan,design,verify}/SKILL.md` each gain a `<HARD-GATE>` block that refuses to advance the pipeline until the stage's required artifact (`.design/BRIEF.md`, `DESIGN.md` + `DESIGN-CONTEXT.md`, etc.) exists and is approved — reading the artifact path from `.design/STATE.md` when a project uses a custom location.
+- **Rationalization tables in the 7 stage-orchestrator skills.** `brief / explore / plan / design / verify / discuss / audit` each carry a `| Thought | Reality |` rationalization table (≥6 rows) that names the common "skip the stage" justifications and rebuts each.
+- **Inline self-review blocks** in `brief` and `plan` (the 2 spec-producing transitions) — a 4-line inline checklist (Phase 28.5 progressive-disclosure: a short check belongs at the transition surface, not behind a skill-discovery hop).
+- **Portable discipline blocks** in `AGENTS.md` + `GEMINI.md` so non-Claude-Code harnesses (Codex, Gemini, etc.) inherit the same skill-discipline contract.
+- **`router_pick` skill-discovery telemetry** — a new `router_pick` event in `reference/schemas/events.schema.json` plus an emit point (`skills/router/router-pick-emitter.md`). Records a sha256 `context_hash` (never the raw intent — no PII) so Phase 33 can measure which skill the router actually selected.
+- **`lint-skill-descriptions.cjs` drift detector** — a maintainer/CI script (not shipped to npm) that flags any skill whose one-line `description:` is stale while its body changed ≥3 times since (the D-02 heuristic).
+- **`gdd-health` `skill_discipline` check (#7).** `scripts/lib/health-mirror/index.cjs` gains a 7th read-only check reporting `skill-discipline: ready` (using-gdd present AND `hooks.json` SessionStart wires the inject), `skill-discipline: missing using-gdd`, or `skill-discipline: hook not wired`. Documented in `skills/health/SKILL.md`.
+
+### Attribution
+
+- **Mechanism ported from [`obra/superpowers`](https://github.com/obra/superpowers) (MIT).** Three artifacts: the SessionStart hook-script structure, the 1%-rule + red-flags-table format, and the defensive-guardrail patterns (`<HARD-GATE>` / `<SUBAGENT-STOP>` / rationalization-table). See `NOTICE`. We port the MECHANISM, not the content — GDD's skills, gates, and tables are GDD-specific.
+
+### Notes
+
+- The pure-trigger `using-gdd` description ships as **proof-by-implementation** of superpowers' shortcut finding (a `<what>`-clause can make agents follow the description summary instead of reading the body). The counterfactual A/B description test and the pressure-scenario behavior runner are **deferred to Phase 33** (D-02); Phase 32 ships the `router_pick` events + drift-lint instruments that Phase 33 consumes. Phase 28.5's global description-format validator regex stays open until that evidence lands.
+- 4 stage skills (`brief`, `explore`, `plan`, `verify`) sit in the validator's advisory **warn** band (≥100 lines) after gaining the mandatory discipline blocks — well under the **block** threshold (250). Accepted by design: the gates + tables are the deliverable.
+- 6-manifest lockstep at **v1.32.0** (`package.json` + `.claude-plugin/plugin.json` + `.claude-plugin/marketplace.json` (metadata.version + plugins[0].version) + `.cursor-plugin/plugin.json` + `.codex-plugin/plugin.json`).
+
+---
+
 ## [1.31.5] - 2026-05-29
 
 ### Phase 31.5 — Repo Structure Consolidation

package/NOTICE

@@ -211,14 +211,52 @@ See `.planning/phases/30.6-graphify-self-ownership/` for full phase
 documentation including the 10 architectural decisions (D-01 through D-10)
 and the migration of the 8 dispatching callsites to native `bin/gdd-graph`.
 
+──────────────────────────────────────────────────────────────────────────────
+Phase 32 — Skill Auto-Trigger Discipline + Defensive Guardrails (v1.32.0, 2026-05-30)
+──────────────────────────────────────────────────────────────────────────────
+
+The skill-discipline layer shipped in v1.32.0 ports the MECHANISM (not the
+content) from:
+
+  obra/superpowers (https://github.com/obra/superpowers)
+  License: MIT
+
+GDD had 70+ skills and zero forcing functions; superpowers ships exactly one
+(`using-superpowers` SessionStart inject) plus the `<HARD-GATE>` /
+`<SUBAGENT-STOP>` / rationalization-table guardrail patterns, and reliably
+auto-triggers its skills. We re-derive the mechanism in GDD's own runtime and
+skill set; the skill bodies, gates, tables, and pipeline flow are GDD-specific.
+Three ported artifacts:
+
+  hooks/inject-using-gdd.sh
+    └─ SessionStart hook-script structure adapted from superpowers'
+       `using-superpowers` inject: one polyglot script, env-var branch per
+       harness, pure-bash escape_for_json (no jq/python dependency).
+
+  skills/using-gdd/SKILL.md
+    └─ The 1%-rule ("even a 1% chance a skill applies → invoke it") + the
+       red-flags `| Thought | Reality |` table format adapted from
+       superpowers' using-superpowers discipline contract. GDD content:
+       GDD pipeline stages, skill-priority order, instruction-priority.
+
+  skills/{brief,explore,plan,design,verify,discuss,audit}/SKILL.md
+    └─ The defensive-guardrail patterns — `<HARD-GATE>` (refuse to advance a
+       stage without its artifact), `<SUBAGENT-STOP>` (no-cascade into
+       subagents), and the rationalization-table pattern — adapted from
+       superpowers. The specific gates, artifact paths, and table rows are
+       GDD-specific.
+
+The mechanism is the contribution being attributed; the discipline content is
+original to get-design-done.
+
 ────────────────────────────────────────────────────────────────────────
 
 Note on the broader codebase: get-design-done as a whole is licensed under
 the MIT License (see LICENSE). The Apache 2.0 attribution above applies
 specifically to the cc-multi-cli-derived files listed under the Phase 27
-block. The MIT attributions under Phase 28.5 and Phase 28.7 cover content
-adapted from mattpocock/skills (MIT) and gsd-build/get-shit-done (MIT)
-respectively — the MIT-to-MIT re-licensing is straightforward and the
-attributions above provide the required source citation. The MIT and
-Apache 2.0 licenses are compatible — see
+block. The MIT attributions under Phase 28.5, Phase 28.7, and Phase 32 cover
+content/mechanism adapted from mattpocock/skills (MIT), gsd-build/get-shit-done
+(MIT), and obra/superpowers (MIT) respectively — the MIT-to-MIT re-licensing is
+straightforward and the attributions above provide the required source
+citation. The MIT and Apache 2.0 licenses are compatible — see
 https://www.apache.org/legal/resolved.html#category-a.

package/README.md

@@ -276,6 +276,18 @@ node scripts/lib/figma-extract/digest.cjs --raw <cache>/raw/<key> --out .design/
 
 See [`skills/figma-extract/SKILL.md`](skills/figma-extract/SKILL.md) and [`figma-plugin/README.md`](figma-plugin/README.md) for the full flow.
 
+### Skill discipline bootstrap (v1.32.0+)
+
+GDD ships 70+ skills, but a description-match skill router consults them opportunistically — easy to skip a stage under pressure. v1.32.0 adds the forcing function GDD lacked, porting the skill-discipline **mechanism** (not content) from [`obra/superpowers`](https://github.com/obra/superpowers) (MIT):
+
+- **SessionStart inject.** A `using-gdd` bootstrap contract is injected at every session start / `/clear` / compact (`hooks/inject-using-gdd.sh`, per-harness: Cursor / Claude Code / SDK). It carries the **1%-rule** ("even a 1% chance a skill applies → invoke it"), a red-flags `Thought → Reality` table, and the skill-priority + instruction-priority order — so the agent is primed to find the right skill before it acts.
+- **`<HARD-GATE>` at every stage transition.** Brief / Explore / Plan / Design / Verify each refuse to advance until the stage's artifact exists and is approved — no free-handing a stage.
+- **Rationalization tables** in all 7 stage skills name the common "skip it" justifications and rebut each; **inline self-review** blocks gate the brief and plan specs.
+- **`<SUBAGENT-STOP>` no-cascade.** The inject fires only on SessionStart, so the bootstrap never cascades into spawned subagents.
+- **Portable + health-aware.** `AGENTS.md` + `GEMINI.md` carry the same discipline block for non-Claude-Code harnesses, and `/gdd:health` reports a `skill-discipline` readiness line.
+
+See [`skills/using-gdd/SKILL.md`](skills/using-gdd/SKILL.md) and the `NOTICE` attribution for details.
+
 
 ## How It Works
 

package/SKILL.md

@@ -243,6 +243,10 @@ If `$ARGUMENTS` is a stage or command name — invoke it directly, no state chec
 /gdd:sketch-wrap-up  → Skill("get-design-done:gdd-sketch-wrap-up")
 /gdd:spike           → Skill("get-design-done:gdd-spike")
 /gdd:spike-wrap-up   → Skill("get-design-done:gdd-spike-wrap-up")
+# --- Bootstrap (not slash-routed) ---
+# using-gdd → injected at SessionStart by hooks/inject-using-gdd.sh
+#   (disable-model-invocation: true). The skill-discipline contract;
+#   not a user-invoked command — see skills/using-gdd/SKILL.md.
 ```
 
 Pass remaining arguments through: `/gdd:explore --skip-interview` → `Skill("get-design-done:gdd-explore", "--skip-interview")`.

package/hooks/hooks.json

@@ -32,6 +32,15 @@
             "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gdd-sessionstart-recap.js\""
           }
         ]
+      },
+      {
+        "matcher": "startup|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/inject-using-gdd.sh\""
+          }
+        ]
       }
     ],
     "PreToolUse": [

package/hooks/inject-using-gdd.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# hooks/inject-using-gdd.sh — SessionStart per-harness context injector (D-07).
+#
+# The forcing function GDD lacked: on every session start / /clear / compact this
+# reads skills/using-gdd/SKILL.md (the bootstrap discipline contract) and emits it
+# as the host harness's SessionStart "additionalContext" shape so the agent is
+# primed with the 1%-rule + red-flags + skill-priority before it acts.
+#
+# Ported MECHANISM (not content) from obra/superpowers (MIT): one polyglot script,
+# env-var branch, pure-bash escape_for_json (no jq/python dependency). See NOTICE.
+#
+# Three emitted shapes (ONE JSON object on stdout, nothing else):
+#   Cursor       (CURSOR_PLUGIN_ROOT set)        -> {"additional_context": "<escaped>"}
+#   Claude Code  (CLAUDE_PLUGIN_ROOT set, no Cursor)
+#                                                -> {"hookSpecificOutput":
+#                                                     {"hookEventName":"SessionStart",
+#                                                      "additionalContext":"<escaped>"}}
+#   SDK-standard (neither; e.g. COPILOT_CLI)     -> {"additionalContext": "<escaped>"}
+#
+# Branch order: check Cursor BEFORE Claude Code — a Cursor session may also export
+# CLAUDE_PLUGIN_ROOT, and Cursor's own var must win.
+#
+# NO-CASCADE (D-06): this script is wired ONLY under the SessionStart hook event in
+# hooks/hooks.json. Subagent spawns do not fire SessionStart, so the inject cannot
+# cascade into a subagent's context. (Structural guarantee; behavioral proof = P33.)
+
+set -u
+
+# --- Resolve the plugin root so we can locate skills/using-gdd/SKILL.md ---------
+# Prefer the harness-provided roots; fall back to this script's parent dir so the
+# emitter is runnable straight from hooks/ in tests and in bare shells.
+SELF_DIR="$(cd "$(dirname "$0")" && pwd)"
+ROOT="${CURSOR_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-${SELF_DIR}/..}}"
+ROOT="${ROOT//\\//}"  # normalize Windows backslashes to forward slashes
+SKILL="${ROOT}/skills/using-gdd/SKILL.md"
+
+# Defensive: if the skill file is missing we must STILL emit a syntactically valid
+# JSON object (an empty additionalContext) so the SessionStart pipeline never
+# breaks on a partial install. Never crash the session start.
+if [[ -r "${SKILL}" ]]; then
+  CONTENT="$(cat "${SKILL}")"
+else
+  CONTENT=""
+fi
+
+# --- escape_for_json (superpowers pattern; pure bash param-substitution) --------
+# Order matters: backslash FIRST (so escapes we add next aren't re-escaped), then
+# double-quote, then the control chars newline / tab / carriage-return. Emits the
+# value WITH surrounding double-quotes so callers can splice it directly.
+escape_for_json() {
+  local s="$1"
+  s="${s//\\/\\\\}"   # \  -> \\
+  s="${s//\"/\\\"}"   # "  -> \"
+  s="${s//$'\t'/\\t}" # tab -> \t
+  s="${s//$'\r'/\\r}" # CR  -> \r
+  s="${s//$'\n'/\\n}" # LF  -> \n  (do last: newlines are the record separator)
+  printf '"%s"' "$s"
+}
+
+ESCAPED="$(escape_for_json "${CONTENT}")"
+
+# --- Branch on harness env vars and emit the matching single JSON object --------
+if [[ -n "${CURSOR_PLUGIN_ROOT:-}" ]]; then
+  # Cursor: top-level additional_context.
+  printf '{"additional_context": %s}\n' "${ESCAPED}"
+elif [[ -n "${CLAUDE_PLUGIN_ROOT:-}" ]]; then
+  # Claude Code: hookSpecificOutput envelope (mirrors hooks/gdd-decision-injector.js).
+  printf '{"hookSpecificOutput": {"hookEventName": "SessionStart", "additionalContext": %s}}\n' "${ESCAPED}"
+else
+  # SDK-standard (COPILOT_CLI or none): top-level additionalContext.
+  printf '{"additionalContext": %s}\n' "${ESCAPED}"
+fi

package/hooks/run-hook.cmd

@@ -0,0 +1,35 @@
+@echo off
+REM hooks/run-hook.cmd — Windows polyglot wrapper that invokes a GDD .sh hook
+REM through bash.
+REM
+REM Workaround for Claude Code's Windows auto-bash bug: CC can mis-handle a
+REM SessionStart `command` that points directly at a `.sh` file on Windows
+REM shells. This .cmd shim locates bash and runs the script explicitly, so the
+REM SessionStart inject (hooks/inject-using-gdd.sh) fires on Windows too.
+REM
+REM Usage:  run-hook.cmd <script-name.sh> [args...]
+REM Default (no arg): inject-using-gdd.sh — the SessionStart using-gdd injector.
+REM The host harness's env (CLAUDE_PLUGIN_ROOT / CURSOR_PLUGIN_ROOT / COPILOT_CLI)
+REM is inherited by bash and drives the emitter's per-harness branch.
+setlocal
+
+REM Script to run, relative to this .cmd's own directory (%~dp0 ends with a backslash).
+set "HOOK_SCRIPT=%~1"
+if "%HOOK_SCRIPT%"=="" set "HOOK_SCRIPT=inject-using-gdd.sh"
+if not "%~1"=="" shift
+
+set "HOOK_PATH=%~dp0%HOOK_SCRIPT%"
+
+REM Prefer bash on PATH; fall back to a typical Git-for-Windows install location.
+where bash >nul 2>nul
+if %ERRORLEVEL%==0 (
+  bash "%HOOK_PATH%" %*
+) else if exist "%ProgramFiles%\Git\bin\bash.exe" (
+  "%ProgramFiles%\Git\bin\bash.exe" "%HOOK_PATH%" %*
+) else (
+  REM No bash available: emit a valid empty SDK-shape JSON object so the
+  REM SessionStart pipeline still receives parseable output and never breaks.
+  echo {"additionalContext": ""}
+)
+
+endlocal

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.31.5",
+  "version": "1.32.0",
   "description": "A design-quality pipeline for AI coding agents: brief, plan, implement, and verify UI work against your design system.",
   "author": "Hegemon",
   "homepage": "https://github.com/hegemonart/get-design-done",

package/reference/schemas/events.schema.json

@@ -10,7 +10,7 @@
     "type": {
       "type": "string",
       "minLength": 1,
-      "description": "Free-form event type identifier. Pre-registered seeds: state.mutation, state.transition, stage.entered, stage.exited, hook.fired, error, capability_gap."
+      "description": "Free-form event type identifier. Pre-registered seeds: state.mutation, state.transition, stage.entered, stage.exited, hook.fired, error, capability_gap, kfm-candidate, router_pick."
     },
     "timestamp": {
       "type": "string",
@@ -181,6 +181,57 @@
         }
       },
       "description": "Phase 30.5-03 D-06 kfm-candidate payload — 7 fields, additionalProperties: false. Validated when the envelope's type === 'kfm-candidate' via the allOf[1] conditional."
+    },
+    "RouterPickPayload": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "event_id",
+        "source",
+        "picked_skill",
+        "context_hash",
+        "rank",
+        "alternatives",
+        "ts"
+      ],
+      "properties": {
+        "event_id": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
+          "description": "UUIDv4 identifying this router_pick event. Stable across emit + read cycles."
+        },
+        "source": {
+          "type": "string",
+          "const": "router",
+          "description": "Phase 32-08 D-02 — the router_pick event class is emitted EXCLUSIVELY by the gdd-router skill at its resolved-pick point. No other producer is authorised."
+        },
+        "picked_skill": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The skill or agent the router auto-picked for this intent. Phase 33 baselines per-skill auto-pick rates from this field (pick-rate regression)."
+        },
+        "context_hash": {
+          "type": "string",
+          "minLength": 1,
+          "description": "sha256 of the intent/context that drove the pick — NEVER the raw prompt (no PII, mirrors CapabilityGapPayload.context_hash discipline). Used by Phase 33 aggregation to cluster picks for the same context."
+        },
+        "rank": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Rank of the picked_skill among the candidates considered (0 = top pick). Lets Phase 33 distinguish confident top picks from close calls."
+        },
+        "alternatives": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Other candidate skill/agent names the router considered (names only — no scores, no prompt text). May be empty when the router had a single match. Surfaces which skills the router weighs but does not reach for."
+        },
+        "ts": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO-8601 timestamp of the pick emission."
+        }
+      },
+      "description": "Phase 32-08 D-02 router_pick payload — 7 fields, additionalProperties: false, NO PII (context_hash only). Records which skill the router auto-picked per intent — the instrument that surfaces under-reached skills. Validated when the envelope's type === 'router_pick' via the allOf[2] conditional."
     }
   },
   "allOf": [
@@ -205,6 +256,17 @@
           "payload": { "$ref": "#/definitions/KfmCandidatePayload" }
         }
       }
+    },
+    {
+      "if": {
+        "properties": { "type": { "const": "router_pick" } },
+        "required": ["type"]
+      },
+      "then": {
+        "properties": {
+          "payload": { "$ref": "#/definitions/RouterPickPayload" }
+        }
+      }
     }
   ]
 }

package/scripts/lib/health-mirror/index.cjs

@@ -8,13 +8,14 @@
 // Surface:
 //   async getHealthChecks(rootDir) → { checks: HealthCheck[] }
 //
-// The 6 checks (in stable order) are:
+// The 7 checks (in stable order) are:
 //   1. claude_md            — CLAUDE.md presence
 //   2. planning_dir         — .planning/ presence
 //   3. design_dir           — .design/ presence
 //   4. package_json         — package.json present AND parseable
 //   5. issue_reporter       — kill-switch state (Plan 30-06 / D-08)
 //   6. figma_extract        — extract readiness + Free-tier signal (Plan 31-09)
+//   7. skill_discipline     — using-gdd bootstrap + SessionStart inject (Plan 32-07)
 //
 // Check 5 was added in Plan 30-06 — surfaces the report-issue kill-switch
 // (env or config disable) so users can verify why the command is
@@ -34,6 +35,17 @@
 // logged, or placed in the detail. The Free-tier state is derived from a LOCAL
 // signal only (a prior pull's _meta.json recording a 403/skip on the Variables
 // endpoint) — never a live network call (health-mirror is pure read-only).
+//
+// Check 7 was added in Plan 32-07 — surfaces whether the skill-discipline
+// bootstrap (Phase 32) is live so a user can confirm the using-gdd SessionStart
+// inject is wired. The detail line is one of three exact strings:
+//   - "skill-discipline: ready"            (using-gdd present AND hooks.json
+//                                           SessionStart wires inject-using-gdd.sh)
+//   - "skill-discipline: missing using-gdd" (skills/using-gdd/SKILL.md absent)
+//   - "skill-discipline: hook not wired"    (skill present but no SessionStart
+//                                           inject-using-gdd entry)
+// status: 'ok' when ready, 'warn' otherwise. PURE read-only (rootDir-relative
+// file + JSON inspection only) — NEVER throws, NEVER networks.
 
 const fs = require('node:fs');
 const path = require('node:path');
@@ -174,9 +186,75 @@ async function getHealthChecks(rootDir) {
     checks.push({ name: 'figma_extract', status, detail });
   }
 
+  // 7. skill_discipline — using-gdd bootstrap + SessionStart inject (Plan 32-07).
+  // Reports exactly one of three states. PURE read-only: file existence +
+  // hooks.json JSON inspection only. NEVER throws, NEVER networks (every read
+  // is wrapped defensively like the figma_extract check above).
+  {
+    const skillPresent = fileExists(
+      path.join(rootDir, 'skills', 'using-gdd', 'SKILL.md')
+    );
+    const hookWired = skillPresent && sessionStartWiresInject(rootDir);
+
+    let detail;
+    let status;
+    if (!skillPresent) {
+      detail = 'skill-discipline: missing using-gdd';
+      status = 'warn';
+    } else if (!hookWired) {
+      detail = 'skill-discipline: hook not wired';
+      status = 'warn';
+    } else {
+      detail = 'skill-discipline: ready';
+      status = 'ok';
+    }
+    checks.push({ name: 'skill_discipline', status, detail });
+  }
+
   return { checks };
 }
 
+/**
+ * Does hooks/hooks.json wire the inject-using-gdd SessionStart entry?
+ * PURE read-only JSON inspection. Defensive: a missing/garbage hooks.json or an
+ * unexpected shape returns false (→ "hook not wired") rather than throwing — the
+ * health probe must never crash on this check. NEVER networks.
+ *
+ * @param {string} rootDir project root passed to getHealthChecks
+ * @returns {boolean} true iff a SessionStart hook command references inject-using-gdd
+ */
+function sessionStartWiresInject(rootDir) {
+  try {
+    const p = path.join(rootDir, 'hooks', 'hooks.json');
+    let hooks;
+    try {
+      hooks = JSON.parse(fs.readFileSync(p, 'utf8'));
+    } catch {
+      return false; // missing/garbage hooks.json → not wired
+    }
+    const sessionStart =
+      hooks && hooks.hooks && Array.isArray(hooks.hooks.SessionStart)
+        ? hooks.hooks.SessionStart
+        : [];
+    for (const entry of sessionStart) {
+      const inner = entry && Array.isArray(entry.hooks) ? entry.hooks : [];
+      for (const h of inner) {
+        if (
+          h &&
+          typeof h.command === 'string' &&
+          /inject-using-gdd/.test(h.command)
+        ) {
+          return true;
+        }
+      }
+    }
+    return false;
+  } catch {
+    // Absolute safety net — never crash the health probe on this check.
+    return false;
+  }
+}
+
 /**
  * Free-tier signal (LOCAL only — never a network call). The raw-pull stage
  * (scripts/lib/figma-extract/pull.cjs) writes a _meta.json per file key under

package/sdk/mcp/gdd-mcp/server.js

@@ -251,8 +251,50 @@ var require_health_mirror = __commonJS({
         }
         checks.push({ name: "figma_extract", status, detail });
       }
+      {
+        const skillPresent = fileExists(
+          path.join(rootDir, "skills", "using-gdd", "SKILL.md")
+        );
+        const hookWired = skillPresent && sessionStartWiresInject(rootDir);
+        let detail;
+        let status;
+        if (!skillPresent) {
+          detail = "skill-discipline: missing using-gdd";
+          status = "warn";
+        } else if (!hookWired) {
+          detail = "skill-discipline: hook not wired";
+          status = "warn";
+        } else {
+          detail = "skill-discipline: ready";
+          status = "ok";
+        }
+        checks.push({ name: "skill_discipline", status, detail });
+      }
       return { checks };
     }
+    function sessionStartWiresInject(rootDir) {
+      try {
+        const p = path.join(rootDir, "hooks", "hooks.json");
+        let hooks;
+        try {
+          hooks = JSON.parse(fs.readFileSync(p, "utf8"));
+        } catch {
+          return false;
+        }
+        const sessionStart = hooks && hooks.hooks && Array.isArray(hooks.hooks.SessionStart) ? hooks.hooks.SessionStart : [];
+        for (const entry of sessionStart) {
+          const inner = entry && Array.isArray(entry.hooks) ? entry.hooks : [];
+          for (const h of inner) {
+            if (h && typeof h.command === "string" && /inject-using-gdd/.test(h.command)) {
+              return true;
+            }
+          }
+        }
+        return false;
+      } catch {
+        return false;
+      }
+    }
     function figmaVariablesBlockedLocally(rootDir) {
       try {
         const rawRoot = path.join(rootDir, ".figma-extract-cache", "raw");

package/skills/audit/SKILL.md

@@ -63,4 +63,17 @@ After the consolidated audit summary has been printed (and any reflection-propos
 
 Written by `hooks/update-check.sh`; suppressed mid-pipeline and when the latest release is dismissed.
 
+## Rationalizations — Thought to Reality
+
+The excuses an agent reaches for to skip or thin out an audit, and the drift each one misses:
+
+| Thought | Reality |
+|---------|---------|
+| "The audit passed last cycle, I can skip it this cycle." | Per-cycle audit catches drift the prior pass couldn't see; a skipped review is exactly where regressions accumulate unnoticed. |
+| "`--quick` is fine, integration isn't the concern here." | Dropping the integration-checker hides orphaned decisions — wiring breaks even when the 6-pillar score looks healthy. |
+| "I can eyeball the scores instead of spawning the auditor." | The auditor's rubric scores six pillars consistently; an eyeballed review drifts toward whatever the agent already believes. |
+| "Reflection proposals are optional polish, skip the reflector." | The reflector turns this cycle's learnings into next-cycle improvements; skipping it lets the same mistakes repeat. |
+| "I'll modify the source while I'm in here fixing findings." | Audit is read-only by contract; editing source mid-audit invalidates the very scores you're producing. |
+| "Retroactive mode is overkill for a finished cycle." | Retroactive verification is the only check on tasks that shipped without per-task verify — skipping it leaves a completed cycle unaudited. |
+
 ## AUDIT COMPLETE

package/skills/brief/SKILL.md

@@ -92,4 +92,29 @@ Next: @get-design-done explore
 ━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
+## Spec self-review (before transition)
+
+Run this final spec-quality pass over `.design/BRIEF.md` before the brief→explore transition:
+- Placeholder scan: no TBD / TODO / `<placeholder>` / lorem left in the artifact.
+- Internal consistency: sections don't contradict each other.
+- Scope check: nothing in the artifact exceeds (or silently drops) the agreed scope.
+- Ambiguity check: every requirement/decision is specific enough to act on without a follow-up question.
+
+<HARD-GATE>
+Do NOT transition to explore (or invoke `/gdd:explore`) until the brief artifact (default `.design/BRIEF.md`) is committed AND the user has approved it. If this project uses a custom `.design` location, read the artifact path from `.design/STATE.md` rather than assuming the default.
+</HARD-GATE>
+
+## Rationalizations — Thought to Reality
+
+The excuses an agent invents to skip or shortcut the brief, and what each one actually costs the cycle:
+
+| Thought | Reality |
+|---------|---------|
+| "This brief is too simple to need a problem statement." | Skip the brief = guess at requirements, then redesign mid-design when the real problem surfaces. |
+| "The user told me what to build, I can skip the interview." | Unasked constraints (a11y, brand, stack) become rework — the five questions exist because each one has blown a past cycle. |
+| "I'll capture success metrics later in verify." | Verify has nothing to check against; an un-metricked brief produces an un-verifiable cycle. |
+| "Scope is obvious, I don't need an in/out line." | Undeclared scope is scope creep waiting to happen — the explore scan widens to fill the vacuum. |
+| "I can answer all five questions for the user from context." | AskUserQuestion one-at-a-time exists because batched/assumed answers smuggle in wrong premises that compound downstream. |
+| "STATE.md bootstrap can wait." | Every later MCP mutation requires STATE.md to exist; skipping the bootstrap hard-blocks explore on entry. |
+
 ## BRIEF COMPLETE

package/skills/design/SKILL.md

@@ -78,4 +78,21 @@ Print the `=== Design stage complete ===` summary (tasks complete/total, deviati
 
 After all tasks finish, if STATE.md `<connections>` has `figma: available`, offer the user the figma-write opt-in prompt (modes: annotate / tokenize / mappings, with optional `--dry-run`). Spawn `design-figma-writer` with the selected mode on "yes"; skip silently on "no". NEVER auto-run without confirmation. Full prompt + dispatch logic: `./design-procedure.md` §Figma Write Dispatch.
 
+<HARD-GATE>
+Do NOT transition to verify (or invoke `/gdd:verify`) until `.design/DESIGN-SUMMARY.md` is committed. If this project uses a custom `.design` location, read the artifact path from `.design/STATE.md` rather than assuming the default.
+</HARD-GATE>
+
+## Rationalizations — Thought to Reality
+
+The excuses an agent uses to cut corners during design implementation, and the cost of each:
+
+| Thought | Reality |
+|---------|---------|
+| "I can skip planning for this small task and just implement it." | Plan-skipped tasks blow scope per cycle telemetry; the gate is for the typical case, not the exception. |
+| "These two tasks touch nearby files but I'll run them in parallel anyway." | Overlapping `Touches:` in a parallel batch produce merge conflicts that silently drop one task's work — split into sequential sub-waves. |
+| "Hardcoding this value is faster than wiring the token." | A hardcoded value is a stub the verifier catches as drift from the design tokens; you pay for it twice. |
+| "I'll emit the `.stories.tsx` stub later when Storybook is back up." | The CSF stub must land with the component or the next cycle's visual-regression scope misses it entirely. |
+| "This deviation is minor, I won't record a blocker." | An unrecorded deviation can't be resolved by a follow-up task, so it leaks into verify as an unexplained gap. |
+| "Auto-mode means I can ignore the wave checkpoints." | Auto-mode skips prompts, not the wave structure; ignoring wave order still corrupts dependent-task ordering. |
+
 ## DESIGN COMPLETE

package/skills/discuss/SKILL.md

@@ -80,4 +80,17 @@ Cycle: <name or "default">
 - Do not run the interview yourself — always spawn the agent.
 - Do not touch files outside `.design/`.
 
+## Rationalizations — Thought to Reality
+
+The shortcuts an agent takes during a discuss session, and what each one costs the decision record:
+
+| Thought | Reality |
+|---------|---------|
+| "I'll ask all eight questions at once to save time." | Batched questions overwhelm the user; one-at-a-time keeps each decision clean and prevents coupled answers. |
+| "I can run the interview inline instead of spawning the discussant." | The skill's contract is to always spawn the agent — running it yourself skips the discussant's mode handling and D-XX numbering. |
+| "This answer is good enough, I'll record it as a decision without follow-up." | A vague answer ("modern", "clean") recorded as a D-XX locks in an undecided premise; reject and re-ask once. |
+| "I'll batch all the new D-XX entries into STATE.md at the end." | Decisions written atomically per answer survive an interrupted session; batching loses everything if the session drops. |
+| "The glossary term can wait until I write the summary." | CONTEXT.md is written immediately per term — a deferred glossary entry is a naming inconsistency the next cycle inherits. |
+| "Every decision this session is worth an ADR." | ADRs require all three criteria (hard-to-reverse, surprising, real-tradeoff); auto-promoting routine choices buries the genuinely load-bearing ones. |
+
 ## DISCUSS COMMAND COMPLETE

package/skills/explore/SKILL.md

@@ -85,4 +85,21 @@ Full interview protocol + JSON line schema: `./explore-procedure.md` §Step 3.
 
 Print: "=== Explore complete ===\nSaved: .design/DESIGN.md, .design/DESIGN-DEBT.md, .design/DESIGN-CONTEXT.md\nNext: @get-design-done plan".
 
+<HARD-GATE>
+Do NOT transition to plan (or invoke `/gdd:plan`) until BOTH `.design/DESIGN.md` AND `.design/DESIGN-CONTEXT.md` are committed AND the user has approved them. If this project uses a custom `.design` location, read the artifact paths from `.design/STATE.md` rather than assuming the default.
+</HARD-GATE>
+
+## Rationalizations — Thought to Reality
+
+The shortcut excuses an agent reaches for during explore, and the drift each one introduces:
+
+| Thought | Reality |
+|---------|---------|
+| "I already know this codebase, I can skip the inventory scan." | An unscanned codebase hides the tokens/components you'll duplicate — the grep pass exists to stop you reinventing what's there. |
+| "The six connection probes are noise, I'll assume Figma is off." | A skipped probe means a wrong connection assumption silently breaks the design stage's tool dispatch. |
+| "`--skip-interview` is fine, the brief covered it." | The interview locks the gray areas the brief left fuzzy; skipping it ships undecided D-XX into planning. |
+| "I'll batch all the interview questions to save round-trips." | Batched questions overwhelm the user and smuggle in coupled assumptions — one-at-a-time keeps each decision clean. |
+| "DESIGN-DEBT.md is optional, the scan was clean enough." | Unrecorded debt resurfaces as an unexplained constraint three stages later with no provenance. |
+| "Prior sketches and project conventions don't apply this cycle." | Ignored conventions get overridden by defaults, producing inconsistency the audit will flag against the rest of the system. |
+
 ## EXPLORE COMPLETE

package/skills/health/SKILL.md

@@ -63,6 +63,12 @@ After the health table, the `gdd_health` MCP surface (`scripts/lib/health-mirror
 
 Token PRESENCE only is detected (D-10) — the token value is never read, logged, or shown. The Free-tier signal is read from the local raw-pull cache only; no network call is made.
 
+## Skill-discipline bootstrap (skill_discipline)
+
+The `gdd_health` MCP surface also reports a `skill_discipline` check (Phase 32) confirming the using-gdd SessionStart bootstrap is live — detail is one of three exact strings:
+- `skill-discipline: ready` — `skills/using-gdd/SKILL.md` exists AND `hooks/hooks.json` SessionStart wires `inject-using-gdd.sh` (status `ok`).
+- `skill-discipline: missing using-gdd` (skill absent) or `skill-discipline: hook not wired` (skill present, no SessionStart inject) — both `warn`.
+
 ## Check MCP registration (gdd-mcp)
 
 After the health table, inspect whether `gdd-mcp` (Phase 27.7+) is registered with any installed harness and render a one-line status row. Dismissable via `.design/config.json#mcp_nudge=false`. Non-blocking: failure paths render `MCP server: unknown` rather than crash. Full detection procedure (dismissal check, detection via `scripts/lib/install/mcp-register.cjs`, row rendering for claude/codex/both/neither, fallback) lives in `./health-mcp-detection.md`.

package/skills/plan/SKILL.md

@@ -77,4 +77,29 @@ The next stage (design) calls `mcp__gdd_state__transition_stage` on entry — th
 
 Print: plan tasks (N waves, M total tasks), files written (`.design/DESIGN-PLAN.md`, plus `.design/DESIGN-RESEARCH.md` if research ran), next step `/get-design-done:design`.
 
+## Spec self-review (before transition)
+
+Run this final spec-quality pass over `.design/DESIGN-PLAN.md` before the plan→design transition:
+- Placeholder scan: no TBD / TODO / `<placeholder>` / lorem left in the artifact.
+- Internal consistency: sections don't contradict each other.
+- Scope check: nothing in the artifact exceeds (or silently drops) the agreed scope.
+- Ambiguity check: every requirement/decision is specific enough to act on without a follow-up question.
+
+<HARD-GATE>
+Do NOT transition to design (or invoke `/gdd:design`) until `.design/DESIGN-PLAN.md` is committed AND the user has approved it. If this project uses a custom `.design` location, read the artifact path from `.design/STATE.md` rather than assuming the default.
+</HARD-GATE>
+
+## Rationalizations — Thought to Reality
+
+The reasons an agent gives to skip planning or rush DESIGN-PLAN.md, and what each one costs:
+
+| Thought | Reality |
+|---------|---------|
+| "This change is small, I can design straight from DESIGN-CONTEXT.md." | Plan-skipped tasks blow scope per cycle telemetry; the plan gate is for the typical case, not the exception you think you're in. |
+| "Pattern mapping is brownfield ceremony, I'll skip it." | Step 1.5 is mandatory because an unmapped brownfield is where the executor silently re-implements an existing pattern. |
+| "The plan-checker will just rubber-stamp it, skip the spawn." | The checker's 5 dimensions (coverage, wave order, must-have derivation) catch the gaps you can't see in your own plan. |
+| "I'll let the planner infer wave ordering at design time." | Unordered waves serialize work that could parallelize — or worse, run dependent tasks concurrently and corrupt the tree. |
+| "Research is overkill for this scope." | The complexity heuristic exists precisely because agents under-estimate scope; skipping research on a 3+-scope domain guarantees a mid-design surprise. |
+| "I can record decisions in DESIGN-PLAN.md prose instead of D-XX." | Prose decisions never reach STATE.md, so verify's integration-checker can't trace them and flags them orphaned. |
+
 ## PLAN COMPLETE

package/skills/router/SKILL.md

@@ -79,6 +79,10 @@ If `.design/budget.json` is missing, assume defaults from `reference/config-sche
 
 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).

package/skills/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/skills/using-gdd/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: using-gdd
+description: "Use when starting any GDD session — establishes how to find and apply GDD skills."
+disable-model-invocation: true
+---
+<SUBAGENT-STOP>
+
+# Using GDD
+
+This is the bootstrap discipline contract for every Get Design Done session. Read it
+first; it tells you how to find and apply the right GDD skill before you act.
+
+## The 1% rule
+
+**If you think there is even a 1% chance a skill might apply, you ABSOLUTELY MUST invoke the skill.**
+
+In GDD, almost every request maps to a pipeline stage — brief, explore, plan, design,
+verify — or to a cross-cutting skill (discuss, audit, style, darkmode). When in doubt,
+search for and read the skill's body. The cost of reading a skill is trivial; the cost of
+free-handing a stage is rework, scope creep, and a broken pipeline state.
+
+## Red flags — Thought → Reality
+
+When you catch yourself thinking any of the following, STOP and check for a skill.
+
+| Thought | Reality |
+| --- | --- |
+| This is just a simple design question. | Questions are tasks. Check for a skill. |
+| I'll just tweak the CSS directly. | Token changes go through the pipeline — check /gdd:design. |
+| I already know the codebase, skip explore. | Explore probes connections you haven't re-checked this cycle. |
+| This change is too small to plan. | Plan-skipped tasks blow scope per cycle telemetry. Run /gdd:plan. |
+| I can write the brief later. | No brief means no shared problem statement — /gdd:brief comes first. |
+| The user clearly wants X, I'll skip discuss. | Ambiguity hides here. /gdd:discuss surfaces the real constraint. |
+| I'll verify by eyeballing it. | Verification is a stage with criteria — run /gdd:verify, don't guess. |
+| It's obviously a dark-mode tweak. | Color-scheme work has its own skill — check /gdd:darkmode. |
+| Let me just compare these two designs quickly. | Comparison is an audit task — /gdd:compare has the rubric. |
+| This is a one-off, no skill needed. | "One-off" is the most common rationalization in the telemetry. Check anyway. |
+| I'll refactor the style tokens by hand. | /gdd:style owns token edits so the pipeline stays consistent. |
+| The audit can wait until after I ship. | An un-audited cycle is an unverified cycle — /gdd:audit before close. |
+
+## Skill priority order
+
+When more than one skill could apply, resolve in this order:
+
+1. **Process** — brief / explore / discuss. Establish the problem and context first.
+2. **Implementation** — design / style / darkmode. Only after process is settled.
+3. **Audit** — verify / compare / audit. Close the loop before declaring done.
+
+Never run an Implementation skill before the Process skills that gate it have produced
+their artifact. Never declare a cycle complete without an Audit skill.
+
+## Instruction priority
+
+When instructions conflict, obey this precedence (highest first):
+
+1. **The user's CLAUDE.md** — project- and user-level directives always win.
+2. **GDD skills** — the skill body is the source of truth for how a stage runs.
+3. **Defaults** — your own general training and habits come last.
+
+If a GDD skill contradicts the user's CLAUDE.md, the CLAUDE.md wins and you flag the
+conflict. If your instinct contradicts a GDD skill, the skill wins.
+
+## GDD pipeline flow
+
+The core flow is **Brief → Explore → Plan → Design → Verify**, with branch points:
+
+- **Brief** captures the problem (`/gdd:brief`). Branch: a rough idea can sketch or spike
+  off the brief before exploration; a changed problem loops back via `--re-brief`.
+- **Explore** scans the codebase and connections (`/gdd:explore`) — even on a familiar
+  repo, because connections drift each cycle.
+- **Plan** decomposes work into tasks (`/gdd:plan`). Skipping it is the top cause of scope
+  blow-up; small tasks still get a plan.
+- **Design** implements (`/gdd:design`, with `/gdd:style` and `/gdd:darkmode` as
+  implementation peers). Implementation never runs ahead of an approved plan.
+- **Verify** checks against criteria (`/gdd:verify`), then `/gdd:audit` / `/gdd:compare`
+  close the loop. On pass the cycle completes; on fail it loops back to the failing stage.
+
+`/gdd:discuss` runs alongside any stage to resolve ambiguity before it propagates.

package/skills/verify/SKILL.md

@@ -93,4 +93,21 @@ Full prompts + branching: `./verify-procedure.md` §Step 3.
 
 Print the `=== Verify complete ===` summary (status, gap counts, agent paths, next-step suggestion) from `./verify-procedure.md` §After Completion.
 
+<HARD-GATE>
+Do NOT mark the cycle complete until the user has reviewed `.design/DESIGN-VERIFICATION.md`. If this project uses a custom `.design` location, read the artifact path from `.design/STATE.md` rather than assuming the default.
+</HARD-GATE>
+
+## Rationalizations — Thought to Reality
+
+The reasons an agent gives to skip or weaken verification, and what each one lets through:
+
+| Thought | Reality |
+|---------|---------|
+| "The implementation looks right, I can skip the verifier spawn." | Skipping verification ships unchecked must-haves; the 5-phase verifier exists to catch what "looks right" misses. |
+| "The integration-checker is redundant with the auditor." | The auditor scores quality; the integration-checker proves each D-XX is actually wired — an orphaned decision passes the audit but fails the product. |
+| "These gaps are minor, I'll accept-as-is without a blocker." | Accept-as-is without recording the unresolved gaps erases the trail; the next cycle re-discovers them from scratch. |
+| "The quality gate timed out, I'll treat that as a pass." | Timeout is a signal, not a pass — masking it lets a genuinely failing gate slip through to ship. |
+| "I'll loop the fixer a fourth time to clear the last gap." | The 3-iteration cap exists because a gap surviving three fixes is a design problem, not a code problem — save and escalate. |
+| "Post-handoff bundles don't need the faithfulness check." | Skipping the handoff-faithfulness section means a divergence from the source design ships unflagged. |
+
 ## VERIFY COMPLETE