@hegemonart/get-design-done 1.57.0 → 1.57.2

package/sdk/cli/index.js

@@ -4014,7 +4014,13 @@ function migrationActive(statePath) {
   const backend = _loadBackend();
   if (backend === null || backend.BACKEND !== "sqlite") return false;
   const sqliteSibling = (0, import_node_path4.join)((0, import_node_path4.dirname)(statePath), "state.sqlite");
-  return (0, import_node_fs5.existsSync)(sqliteSibling);
+  if (!(0, import_node_fs5.existsSync)(sqliteSibling)) return false;
+  try {
+    if ((0, import_node_fs5.statSync)(sqliteSibling).isDirectory()) return false;
+  } catch {
+    return false;
+  }
+  return true;
 }
 async function read(path) {
   const raw = (0, import_node_fs5.readFileSync)(path, "utf8");
@@ -8247,6 +8253,14 @@ var VALID_STAGE_NAMES = /* @__PURE__ */ new Set([
   "verify",
   "discuss"
 ]);
+var TOP_LEVEL_COMMANDS_OFTEN_CONFUSED_FOR_STAGES = /* @__PURE__ */ new Set([
+  "audit",
+  "build",
+  "dashboard",
+  "init",
+  "query",
+  "run"
+]);
 async function stageCommand(args, deps = {}) {
   const stdout = deps.stdout ?? process.stdout;
   const stderr = deps.stderr ?? process.stderr;
@@ -8265,6 +8279,12 @@ async function stageCommand(args, deps = {}) {
       `gdd-sdk stage: "${stageName}" is not one of brief|explore|plan|design|verify|discuss
 `
     );
+    if (TOP_LEVEL_COMMANDS_OFTEN_CONFUSED_FOR_STAGES.has(stageName)) {
+      stderr.write(
+        `gdd-sdk stage: did you mean \`gdd-sdk ${stageName}\`? "${stageName}" is a top-level subcommand, not a pipeline stage.
+`
+      );
+    }
     return 3;
   }
   let flags;

package/sdk/dashboard/data/_pkg-root.cjs

@@ -6,8 +6,8 @@
  * resolve a cross-tree sibling via a fixed `__dirname`-relative `../../..`
  * jump, because that breaks the moment a file is copied/moved or the layout
  * shifts. Instead, walk UP from this file's directory until we find the GDD
- * package.json (identified by `name === 'get-design-done'`), and resolve all
- * in-repo siblings relative to that root.
+ * package.json (identified by `name === '@hegemonart/get-design-done'`), and
+ * resolve all in-repo siblings relative to that root.
  *
  * Even though these dashboard `.cjs` files are NOT esbuild-bundled (R8 — the
  * bin trampoline runs them directly so the Phase 53 __dirname-rewrite trap
@@ -23,7 +23,7 @@ let _cachedRoot = null;
 
 /**
  * Walk up from `startDir` looking for the GDD package root. The GDD root is
- * the first ancestor whose package.json declares `name: "get-design-done"`;
+ * the first ancestor whose package.json declares `name: "@hegemonart/get-design-done"`;
  * if no such marker is found (e.g. running from an unusual layout), fall back
  * to the FIRST ancestor that has any package.json, then to `startDir`.
  *
@@ -44,7 +44,7 @@ function findPackageRoot(startDir) {
     }
     if (pkg) {
       if (firstWithPkg === null) firstWithPkg = dir;
-      if (pkg.name === 'get-design-done') return dir;
+      if (pkg.name === '@hegemonart/get-design-done') return dir;
     }
     const parent = path.dirname(dir);
     if (parent === dir) break;

package/sdk/dashboard/data/risk-surface.cjs

@@ -33,15 +33,20 @@
  *   (absent / unknown)  -> default
  */
 
-/** Canonical action → color map (the only colors the Findings pane uses). */
+/**
+ * Canonical action -> color map. Keys are lowercase (matching the emitter's
+ * suggested_action values from events.schema.json: allow/review/
+ * require_confirmation/block). The display label is separate from the key so
+ * the map can do a single case-insensitive lookup.
+ */
 const ACTION_COLOR = Object.freeze({
-  Allow: 'green',
-  Review: 'yellow',
-  RequireConfirmation: 'orange',
-  Block: 'red',
+  allow: 'green',
+  review: 'yellow',
+  require_confirmation: 'orange',
+  block: 'red',
 });
 
-/** The set of recognized suggested-action values (Phase 56 vocabulary). */
+/** The set of recognized suggested-action values (Phase 56 vocabulary, lowercase). */
 const VALID_ACTIONS = Object.freeze(Object.keys(ACTION_COLOR));
 
 /** The blank placeholder row emitted pre-56 (or for malformed/absent input). */
@@ -66,34 +71,64 @@ function finiteOrNull(v) {
 }
 
 /**
- * Map a suggested_action to its display color. Unknown / absent -> 'default'.
+ * Canonicalize a suggested_action to its lowercase snake_case key for lookup.
+ * Handles the emitter's lowercase values (allow/review/require_confirmation/block)
+ * AND legacy CamelCase (Allow/Review/RequireConfirmation/Block) - the CamelCase
+ * 'RequireConfirmation' lowercases to 'requireconfirmation' with no separator, so
+ * map that explicitly to 'require_confirmation'. Returns null for non-strings.
+ * @param {*} action
+ * @returns {string|null}
+ */
+function canonAction(action) {
+  if (typeof action !== 'string') return null;
+  let s = action.trim().toLowerCase().replace(/[\s-]+/g, '_');
+  if (s === 'requireconfirmation') s = 'require_confirmation';
+  return s;
+}
+
+/**
+ * Map a suggested_action to its display color. Case-insensitive so both
+ * 'allow' (emitter) and 'Allow' (legacy) resolve correctly. Unknown / absent -> 'default'.
  * @param {*} action
  * @returns {'green'|'yellow'|'orange'|'red'|'default'}
  */
 function colorForAction(action) {
-  if (typeof action === 'string' && Object.prototype.hasOwnProperty.call(ACTION_COLOR, action)) {
-    return ACTION_COLOR[action];
+  const canon = canonAction(action);
+  if (canon !== null && Object.prototype.hasOwnProperty.call(ACTION_COLOR, canon)) {
+    return ACTION_COLOR[canon];
   }
   return 'default';
 }
 
 /**
- * Surface the risk fields on ONE event/finding. Reads `risk_score`,
- * `confidence`, `suggested_action` WHEN PRESENT; otherwise returns the blank
- * placeholder. PURE; NEVER throws.
+ * Surface the risk fields on ONE event/finding. Accepts either a raw
+ * risk_assessment envelope (with a `.payload` sub-object) OR a bare payload
+ * object. When `.payload` is present it is used as the source of risk fields;
+ * otherwise `item` itself is inspected (bare-payload / legacy path).
  *
- * @param {*} item an event or finding (may be missing the risk fields pre-56)
+ * Reads `risk_score`, `confidence`, `suggested_action` WHEN PRESENT; otherwise
+ * returns the blank placeholder. PURE; NEVER throws.
+ *
+ * @param {*} item an event envelope or bare payload (may be missing risk fields pre-56)
  * @returns {{risk_score:number|null, confidence:number|null,
  *            suggested_action:string|null, color:string}}
  */
 function surfaceRiskOne(item) {
   if (!item || typeof item !== 'object') return blankRow();
 
-  const risk_score = finiteOrNull(item.risk_score);
-  const confidence = finiteOrNull(item.confidence);
-  const rawAction = item.suggested_action;
-  const suggested_action =
-    typeof rawAction === 'string' && VALID_ACTIONS.includes(rawAction) ? rawAction : null;
+  // Normalize: if the caller passed a full event envelope (with .payload), use the payload.
+  const src = (item.payload && typeof item.payload === 'object') ? item.payload : item;
+
+  const risk_score = finiteOrNull(src.risk_score);
+  const confidence = finiteOrNull(src.confidence);
+  const rawAction = src.suggested_action;
+  const canon = canonAction(rawAction);
+  const recognized =
+    canon !== null && Object.prototype.hasOwnProperty.call(ACTION_COLOR, canon);
+  // Preserve the action VERBATIM when recognized: the emitter sends lowercase
+  // (allow/review/require_confirmation/block), legacy callers may send CamelCase,
+  // and either is echoed back unchanged. Unrecognized / absent -> null.
+  const suggested_action = recognized ? rawAction : null;
 
   // Pre-56: when NONE of the risk fields are present, emit the blank placeholder
   // verbatim (color 'default') so the column reads as "not yet scored".
@@ -105,7 +140,7 @@ function surfaceRiskOne(item) {
     risk_score,
     confidence,
     suggested_action,
-    color: colorForAction(suggested_action),
+    color: recognized ? ACTION_COLOR[canon] : 'default',
   };
 }
 

package/sdk/dashboard/tui/index.cjs

@@ -37,6 +37,21 @@ const readline = require('node:readline');
 
 const ansi = require('./ansi.cjs');
 
+// Lazily require the risk-surface helper (same dep-free constraint as the data plane).
+let _surfaceRisk = null;
+function getSurfaceRisk() {
+  if (_surfaceRisk === null) {
+    try {
+      ({ surfaceRisk: _surfaceRisk } = require('../data/risk-surface.cjs'));
+    } catch {
+      // If the module is unavailable for any reason, fall back to a no-op that returns
+      // blank placeholder rows so the column still renders cleanly.
+      _surfaceRisk = () => ({ risk_score: null, confidence: null, suggested_action: null, color: 'default' });
+    }
+  }
+  return _surfaceRisk;
+}
+
 // Lazily require the data plane so `renderFrame` (the pure path) can be imported + unit-tested
 // without paying for the data module's transitive requires. `run` resolves it on demand.
 let _loadDashboardModel = null;
@@ -351,11 +366,22 @@ function bodyFindings(model, inner, scroll) {
   if (tail.length === 0) {
     lines.push('  ' + ansi.color('no events', { dim: true }));
   } else {
+    const surfaceRisk = getSurfaceRisk();
     for (const ev of tail) {
       const name = (ev && (ev.event || ev.type || ev.kind)) || 'event';
-      // Pre-Phase-56: risk/confidence are blank placeholders (D8).
+      // Phase-56+: surface risk/confidence from risk_assessment events.
+      // For pre-56 events that lack risk fields, surfaceRiskOne returns the blank placeholder.
+      const surfaced = (ev && ev.type === 'risk_assessment')
+        ? surfaceRisk(ev)
+        : { risk_score: null, confidence: null, suggested_action: null, color: 'default' };
+      const riskText = surfaced.risk_score !== null
+        ? ansi.color(surfaced.risk_score.toFixed(2), { fg: surfaced.color !== 'default' ? surfaced.color : undefined })
+        : ansi.color('·', { dim: true });
+      const confText = surfaced.confidence !== null
+        ? String(surfaced.confidence.toFixed(2))
+        : ansi.color('·', { dim: true });
       lines.push(ansi.columns(
-        [String(name), ansi.color('·', { dim: true }), ansi.color('·', { dim: true })],
+        [String(name), riskText, confText],
         [Math.max(8, inner - 14), 5, 5],
       ));
     }

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

@@ -1776,7 +1776,13 @@ function migrationActive(statePath) {
   const backend = _loadBackend();
   if (backend === null || backend.BACKEND !== "sqlite") return false;
   const sqliteSibling = (0, import_node_path.join)((0, import_node_path.dirname)(statePath), "state.sqlite");
-  return (0, import_node_fs2.existsSync)(sqliteSibling);
+  if (!(0, import_node_fs2.existsSync)(sqliteSibling)) return false;
+  try {
+    if ((0, import_node_fs2.statSync)(sqliteSibling).isDirectory()) return false;
+  } catch {
+    return false;
+  }
+  return true;
 }
 async function read(path2) {
   const raw = (0, import_node_fs2.readFileSync)(path2, "utf8");

package/sdk/state/index.ts

@@ -33,6 +33,7 @@ import {
   renameSync,
   unlinkSync,
   existsSync,
+  statSync,
 } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
@@ -176,7 +177,16 @@ function migrationActive(statePath: string): boolean {
   const backend = _loadBackend();
   if (backend === null || backend.BACKEND !== 'sqlite') return false;
   const sqliteSibling = join(dirname(statePath), 'state.sqlite');
-  return existsSync(sqliteSibling);
+  if (!existsSync(sqliteSibling)) return false;
+  // BUG-07: a DIRECTORY named state.sqlite would cause existsSync to return true,
+  // and then every mutate() would throw when trying to open it as a database.
+  // Guard: if the path is a directory, treat migration as inactive.
+  try {
+    if (statSync(sqliteSibling).isDirectory()) return false;
+  } catch {
+    return false;
+  }
+  return true;
 }
 
 /**

package/skills/cache-manager/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gdd-cache-manager
-description: "Maintains .design/cache-manifest.json for Layer B explicit cache per D-08. Computes deterministic SHA-256 input-hash from (agent-path + sorted-input-file-paths + input-content-hashes). On spawn: lookup key → return cached blob if within TTL, else miss. On completion: write result + TTL. Consulted by hooks/budget-enforcer.js before every Agent spawn."
+description: "Maintains .design/cache-manifest.json for Layer B explicit cache per D-08. Computes deterministic SHA-256 input-hash from (agent-path + sorted-input-file-paths + input-content-hashes). On spawn: lookup key → return cached blob if within TTL, else miss. On completion: write result + TTL. Consulted by hooks/budget-enforcer.ts before every Agent spawn."
 user-invocable: false
 tools: Read, Bash, Write
 disable-model-invocation: true
@@ -38,11 +38,11 @@ You are the deterministic cache-key computer and cache-manifest writer for the o
 
 ## Deterministic Input-Hash Algorithm
 
-The canonical reference implementation (single source of truth; `hooks/budget-enforcer.js` imports the same primitive via a shared helper) lives in `./cache-policy.md#deterministic-input-hash-algorithm-layer-b` - it documents the JS implementation, the maintainer notes (sorted-unique paths, MISSING-file sentinel, agent-path bust behavior), the manifest shape, and TTL semantics in one place. Conform to the algorithm exactly so the hook and any orchestrator agree byte-for-byte.
+The canonical reference implementation (single source of truth; `hooks/budget-enforcer.ts` imports the same primitive via a shared helper) lives in `./cache-policy.md#deterministic-input-hash-algorithm-layer-b` - it documents the JS implementation, the maintainer notes (sorted-unique paths, MISSING-file sentinel, agent-path bust behavior), the manifest shape, and TTL semantics in one place. Conform to the algorithm exactly so the hook and any orchestrator agree byte-for-byte.
 
 ## Integration Points
 
-- **`hooks/budget-enforcer.js`** (Plan 10.1-01) reads the manifest on every Agent spawn. The hook already calls `cacheLookup(agent, inputHash)` against `.design/cache-manifest.json`. This skill is the authority on how `inputHash` is computed so the hook and any orchestrator agree byte-for-byte.
+- **`hooks/budget-enforcer.ts`** (Plan 10.1-01) reads the manifest on every Agent spawn. The hook already calls `cacheLookup(agent, inputHash)` against `.design/cache-manifest.json`. This skill is the authority on how `inputHash` is computed so the hook and any orchestrator agree byte-for-byte.
 - **Orchestrators** (e.g., `skills/map/`, `skills/discover/`, `skills/plan/`) invoke Phase 1 (compute-key) + Phase 4 (write-result-on-completion) around each Agent spawn they launch. Phase 2 + Phase 3 are executed by the hook.
 - **Warm-cache command** (`skills/warm-cache/SKILL.md`, Task 02) does not touch Layer B - it only primes Anthropic's 5-min prompt cache (Layer A). Do not confuse the two.
 

package/skills/cache-manager/cache-policy.md

@@ -21,7 +21,7 @@ The two layers (D-08):
 
 ## Deterministic Input-Hash Algorithm (Layer B)
 
-The canonical reference implementation (the single source of truth; `hooks/budget-enforcer.js` imports the same primitive via a shared helper):
+The canonical reference implementation (the single source of truth; `hooks/budget-enforcer.ts` imports the same primitive via a shared helper):
 
 ```js
 // Deterministic cache-key primitive (reference implementation)

package/skills/design/SKILL.md

@@ -79,6 +79,25 @@ 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.
 
+## Component Generator Dispatch
+
+If the DESIGN-PLAN has a `task_type: component` task without a matching `src/components/*.tsx`, OR the brief / DESIGN-CONTEXT.md explicitly asks for a new component, AND STATE.md `<connections>` shows a generator connection (`21st-dev: available`, `magic-patterns: available`, `plasmic: available`, `builder-io: available`, or `v0-dev: available`); offer the component-generator opt-in.
+
+```
+Task("design-component-generator", """
+mode: <21st|magic-patterns|plasmic|builder-io|v0-dev>
+component_spec: <DESIGN-PLAN task summary + DESIGN-CONTEXT acceptance criteria>
+required_reading:
+  - .design/STATE.md
+  - .design/DESIGN-PLAN.md
+  - .design/DESIGN-CONTEXT.md
+""")
+```
+
+Sequential (the agent is `parallel-safe: never`). Wait for the agent's `## design-component-generator complete.` marker. Skip silently when no generator connection is available OR no component task is pending. Auto-mode bypasses the prompt; otherwise prompt "Generate component via [tool]? (y/n)" and only spawn on "y".
+
+The dispatch fires AFTER `design-executor` completes the hand-coded plan tasks. The agent's output (component file path + tokens used + provenance) is appended to `.design/DESIGN-SUMMARY.md` as a single `## Generated Components` section so verify can audit it.
+
 <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>

package/skills/explore/SKILL.md

@@ -61,6 +61,16 @@ Run the canonical scan grep/glob inventory (POSIX ERE, preserving PLAT-01/02): c
 - **Project-local skills**: read `./.claude/skills/design-*-conventions.md` -> include in DESIGN-CONTEXT.md `<project_conventions>` (these override defaults).
 - **Global skills**: `~/.claude/gdd/global-skills/*.md` (other than README) -> prepend to `<project_conventions>` under `<global_conventions>` sub-block. Project-local D-XX wins on conflict.
 
+## Step 2.6 - Graph review (gate then reviewer)
+
+Runs only when Step 2's mapper batch + synthesizer produced `.design/context-graph.json`. Skip the whole step if the file is absent (pre-Phase-52 project, or `--skip-scan`).
+
+1. **Gate first (cheap Haiku check).** Spawn `design-context-reviewer-gate` via `Task()` with the classifier signal from Step 2's incremental batching pass: `change_pct` (fingerprint classifier `pct`), `classifier_action` (`SKIP` / `PARTIAL_UPDATE` / `ARCHITECTURE_UPDATE` / `FULL_UPDATE`), and `graph_path: ".design/context-graph.json"`. Gate emits a single-line `{spawn, rationale}` JSON decision then `## GATE COMPLETE`.
+2. **If `spawn: false`**: record `mcp__gdd_state__set_status: "explore_graph_review_skipped"`, log the gate `rationale` (e.g., "project change 3% < 5% threshold"), set telemetry `lazy_skipped: true`. Done - proceed to Step 3.
+3. **If `spawn: true`**: spawn `design-context-reviewer` via `Task()` with `<required_reading>` pointing at `.design/STATE.md`, `.design/context-graph.json`, `reference/design-context-schema.md`, `reference/design-context-tag-vocab.md`. The reviewer runs `scripts/validate-design-context.cjs --json` as the deterministic floor (checks 1/2/3/5) then layers the semantic checks (4/6/7/8/9) and returns the 9-check verdict inline (`APPROVED` or `REJECT`).
+4. **Capture verdict (read-only contract).** The reviewer does NOT write `.design/DESIGN-CONTEXT-REVIEW.md` - it is `reads-only: true, writes: []`. WARN findings surface through `scripts/lib/health-mirror#getHealthChecks` as `status: 'warn'`; a hard-reject maps to `status: 'fail'`. Record the overall verdict via `mcp__gdd_state__set_status: "explore_graph_review_approved"` (or `"_rejected"`).
+5. **On REJECT**: record `mcp__gdd_state__add_blocker` with the reviewer's blocking-issues list verbatim. Do not advance to Step 3 until the synthesizer or the implicated mapper is re-run. On `APPROVED` (with or without WARNs): proceed.
+
 ---
 
 ## Step 3 - Design interview (unless `--skip-interview`)
@@ -80,6 +90,7 @@ Full interview protocol + JSON line schema: `./explore-procedure.md` §Step 3.
 ## Step 4 - Close out explore
 
 - If the synthesizer / mapper batch ran in Step 2: `mcp__gdd_state__update_progress` with `task_progress: "<done>/<total>"`, `status: "explore_mappers_done"`.
+- If Step 2.6 ran the graph review: ensure the verdict status is recorded (`explore_graph_review_approved` / `_rejected` / `_skipped`); on `_rejected` do NOT checkpoint until re-run.
 - `mcp__gdd_state__checkpoint` - bumps `last_checkpoint`.
 - Stage advance to `plan` happens at the next stage's entry (plan owns its own `transition_stage`); do not edit frontmatter directly.
 

package/skills/figma-write/SKILL.md

@@ -34,6 +34,17 @@ Read `.design/STATE.md` and `.design/DESIGN-CONTEXT.md` before dispatching the a
 
 ## Dispatch
 
-<agent>design-figma-writer</agent>
+```
+Task("design-figma-writer", """
+mode: <annotate|tokenize|mappings>
+dry_run: <true|false>
+confirm_shared: <true|false>
+required_reading:
+  - .design/STATE.md
+  - .design/DESIGN-CONTEXT.md
+""")
+```
 
-Pass through all flags and arguments from the invocation to the agent.
+Pass `mode` from the first positional argument; `dry_run` from `--dry-run`;
+`confirm_shared` from `--confirm-shared`. Wait for the agent's completion
+marker before returning.

package/skills/paper-write/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: gdd-paper-write
+description: "Push design decisions from `.design/DESIGN-CONTEXT.md` into the active paper.design canvas by dispatching the `design-paper-writer` agent in one of three modes (annotate / tokenize / roundtrip). Use when the user has completed a design pipeline cycle and wants the decisions reflected in their paper.design canvas. Operates proposal->confirm with `--dry-run`."
+argument-hint: "<annotate|tokenize|roundtrip> [--dry-run]"
+user-invocable: true
+tools: Read, Write, Bash, Grep, Glob
+---
+
+# gdd-paper-write
+
+Dispatches the `design-paper-writer` agent to write design decisions back to the active paper.design canvas. The shared probe pattern (ToolSearch → live call → STATE.md write) and connection handshake are documented at `../../reference/shared-preamble.md#connection-handshake-summary` and `../../connections/paper-design.md`.
+
+## Usage
+
+```
+/get-design-done paper-write <mode> [--dry-run]
+```
+
+Modes:
+- `annotate` - add design decision comments to canvas nodes
+- `tokenize` - sync CSS token values to paper.design node styles
+- `roundtrip` - write implementation status back as text/HTML layers
+
+Flags:
+- `--dry-run` - emit the proposal without executing any paper.design writes
+
+paper.design has no team-library concept, so there is no `--confirm-shared` flag. Every write still requires an explicit `yes` confirmation (unless `--dry-run` is set).
+
+## Prerequisites
+
+1. paper.design MCP registered. Install: `claude mcp add paper-design --transport http https://mcp.paper.design/sse` then restart the session. See `../../connections/paper-design.md` for the full probe pattern and budget rules.
+2. `.design/DESIGN-CONTEXT.md` exists (run `discover` first)
+3. `.design/STATE.md` `<connections>` shows `paper-design: available`. If `not_configured` or `unavailable`, the agent will STOP with a diagnostic.
+
+Budget: the agent tracks `budget_used` in STATE.md `<connections>` and warns when usage reaches 90/100 on the free tier.
+
+## Required Reading
+
+Read `.design/STATE.md` and `.design/DESIGN-CONTEXT.md` before dispatching the agent.
+
+## Dispatch
+
+```
+Task("design-paper-writer", """
+mode: <annotate|tokenize|roundtrip>
+dry_run: <true|false>
+required_reading:
+  - .design/STATE.md
+  - .design/DESIGN-CONTEXT.md
+""")
+```
+
+Pass `mode` from the first positional argument; `dry_run` from `--dry-run`.
+Wait for the agent's completion marker before returning.

package/skills/pencil-write/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: gdd-pencil-write
+description: "Update local `.pen` source files with design decisions from `.design/DESIGN-CONTEXT.md` by dispatching the `design-pencil-writer` agent in one of two modes (annotate / roundtrip). Use when the user has completed a design pipeline cycle and wants the decisions reflected in their `.pen` files. Operates proposal->confirm with `--dry-run`."
+argument-hint: "<annotate|roundtrip> [--dry-run]"
+user-invocable: true
+tools: Read, Write, Bash, Grep, Glob
+---
+
+# gdd-pencil-write
+
+Dispatches the `design-pencil-writer` agent to write design decisions back to `.pen` spec files. Unlike Figma/paper.design, pencil.dev keeps `.pen` YAML specs as the project's git-tracked source of truth; no MCP is required and every write is committed atomically. The probe pattern (file-based, no ToolSearch) and integration contract are documented at `../../connections/pencil-dev.md`.
+
+## Usage
+
+```
+/get-design-done pencil-write <mode> [--dry-run]
+```
+
+Modes:
+- `annotate` - append DESIGN-DEBT findings as comments to the relevant `.pen` files
+- `roundtrip` - update `.pen` spec frontmatter (design-tokens, state) from verified implementation
+
+There is no `tokenize` mode; `.pen` files are source-of-truth specs, not derived artifacts.
+
+Flags:
+- `--dry-run` - emit the proposal without writing or committing any `.pen` changes
+
+## Prerequisites
+
+1. pencil.dev workspace detected; one or more `.pen` files in `cwd` (no MCP install required):
+   ```bash
+   find . -name "*.pen" -not -path "*/node_modules/*" | head -5
+   ```
+2. `.design/DESIGN-CONTEXT.md` exists (run `discover` first). For `annotate` mode, `.design/DESIGN-DEBT.md` is also required. For `roundtrip` mode, `.design/DESIGN-VERIFICATION.md` is also required.
+3. `.design/STATE.md` `<connections>` shows `pencil-dev: available`. If `not_configured`, no `.pen` files were found at probe time; re-run `discover` or `connections` after adding `.pen` specs.
+
+## Required Reading
+
+Read `.design/STATE.md` and `.design/DESIGN-CONTEXT.md` before dispatching the agent.
+
+## Dispatch
+
+```
+Task("design-pencil-writer", """
+mode: <annotate|roundtrip>
+dry_run: <true|false>
+required_reading:
+  - .design/STATE.md
+  - .design/DESIGN-CONTEXT.md
+""")
+```
+
+Pass `mode` from the first positional argument; `dry_run` from `--dry-run`.
+Wait for the agent's completion marker before returning.

package/skills/report-issue/SKILL.md

@@ -15,7 +15,7 @@ If invoked without an error context (the user just typed `/gdd:report-issue` col
 
 ## Steps
 
-0. **Kill-switch** (D-08). Call `isDisabled()` from `scripts/lib/issue-reporter/kill-switch.cjs` FIRST. Either env (`GDD_DISABLE_ISSUE_REPORTER=1`) OR config (`.design/config.json` with `{ "issue_reporter": false }`) makes the command unavailable. Surface the disable line via `getDisableReason()` ('env' wins when both set) and stop. No draft, no triage, no payload. `gsd-health` mirrors the same line for at-a-glance verification.
+0. **Kill-switch** (D-08). Call `isDisabled()` from `scripts/lib/issue-reporter/kill-switch.cjs` FIRST. Either env (`GDD_DISABLE_ISSUE_REPORTER=1`) OR config (`.design/config.json` with `{ "issue_reporter": false }`) makes the command unavailable. Surface the disable line via `getDisableReason()` ('env' wins when both set) and stop. No draft, no triage, no payload. `/gdd:health` mirrors the same line for at-a-glance verification.
 1. **Triage**. Call `matchKnownFailure(errorContext)` from `scripts/lib/issue-reporter/triage-matcher.cjs` (Plan 30-03). If `matched === true` and `--force-report` is NOT set: print the suggested diagnosis + remedy, stop. Do NOT write a draft. (D-07)
 2. **Assemble**. Call `assemble(commandName, errorContext, trajectoryRef?, capabilityGapEvent?)` from `scripts/lib/issue-reporter/payload-assembly.cjs` (Plan 30-02). This layers Phase 22 redact → Phase 30 pseudonymize, computes the fingerprint, and renders bilingual disclaimer + sections.
 3. **Draft**. Call `writeDraft({title, body, fingerprint})` from `scripts/lib/issue-reporter/draft-writer.cjs`. Print the absolute path: `Draft written to .design/issue-drafts/<timestamp>-<fp8>.md`. The file persists across decline - the user keeps their work either way. (D-04)
@@ -48,6 +48,6 @@ Available on `/gdd:report-issue`. Overrides the triage gate (Step 1) but does NO
 - **No `EDITOR` set.** The path is printed; open it in whatever editor you prefer, save, then return to the consent prompt.
 - **Triage matched something irrelevant.** Pass `--force-report` to bypass the gate. Consent is still required.
 - **`gh` not installed (D-10).** After consent, the payload is copied to your clipboard and an issue-template URL is printed. Paste into the URL to file manually. Install `gh` later and the existing draft can be re-submitted.
-- **Command unavailable / disabled (D-08).** Run `gsd-health`. The `issue reporter:` line shows the active disable surface - either `disabled by env (GDD_DISABLE_ISSUE_REPORTER=1)` or `disabled by config (.design/config.json: issue_reporter=false)`. Unset the env var or flip the config key to re-enable.
+- **Command unavailable / disabled (D-08).** Run `/gdd:health`. The `issue reporter:` line shows the active disable surface - either `disabled by env (GDD_DISABLE_ISSUE_REPORTER=1)` or `disabled by config (.design/config.json: issue_reporter=false)`. Unset the env var or flip the config key to re-enable.
 
 See [report-issue-procedure.md](./report-issue-procedure.md) for the full procedure with rationale per decision (D-02, D-03, D-04, D-05, D-07, D-11).

package/skills/router/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.js."
+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
 ---
@@ -9,7 +9,7 @@ tools: Read, Bash, Grep
 
 ## 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.js`) consumes your output on every `Agent` tool call.
+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
 

package/skills/verify/verify-procedure.md

@@ -2,12 +2,11 @@
 name: verify-procedure
 type: meta-rules
 version: 1.0.0
-phase: 28.5
 tags: [verify, procedure, extracted, pipeline-stage, gap-loop, must-have, quality-gate]
 last_updated: 2026-05-18
 ---
 
-Source: extracted from `skills/verify/SKILL.md` (Phase 28.5 rework - D-10 extract-then-link).
+Source: extracted from `skills/verify/SKILL.md` to keep the SKILL focused on the essential workflow.
 The skill's essential workflow stays in `../skills/verify/SKILL.md`; this file holds the
 detail the agent reaches for when executing a specific step (state integration, quality-gate
 decision tree, agent spawn protocols, gap-response loop, must-have flipping).
@@ -28,9 +27,9 @@ methodology, agent prompts, and gap-loop semantics.
 1. `mcp__gdd_state__transition_stage` with `to: "verify"`.
 2. `mcp__gdd_state__get` → snapshot `state`. Read `state.must_haves` - this is the verification checklist; each M-XX starts at `status: pending` and will be flipped to `pass` or `fail` as verification concludes.
 
-#### Step 2.5 - Quality-gate gate (D-08, D-09)
+#### Step 2.5 - Quality-gate gate
 
-Before resume detection, inspect `state.quality_gate` from the same snapshot. The Stage 4.5 quality-gate skill (see `skills/quality-gate/SKILL.md`) writes a single `<run/>` element capturing the most recent run; this step is the verify-side consumer of that result. Three branches, evaluated in order:
+Before resume detection, inspect `state.quality_gate` from the same snapshot. The quality-gate skill (see `skills/quality-gate/SKILL.md`) writes a single `<run/>` element capturing the most recent run; this step is the verify-side consumer of that result. Three branches, evaluated in order:
 
 - **`state.quality_gate?.run?.status === "fail"`** → Refuse to advance. The fix loop in `quality-gate/SKILL.md` Step 4 reached `max_iters` without converging, and the verify stage MUST NOT paper over it. Print a blocker reason that includes the iteration count and the `commands_run` field from the run, then call:
 
@@ -43,9 +42,9 @@ Before resume detection, inspect `state.quality_gate` from the same snapshot. Th
 
   Exit immediately with the failure surface visible to the user. Do NOT call `mcp__gdd_state__update_progress` to open the verify stage; the gate refused entry, so the stage was never opened.
 
-- **`state.quality_gate?.run?.status === "timeout"` OR `=== "skipped"`** → Print a one-line warning naming the status and the `commands_run` value, then continue normally. Per D-07 these are signals, not walls: a slow test suite must not hostage the pipeline, and a project with no detectable quality commands must not block verify entry. The warning surfaces the degraded state without halting.
+- **`state.quality_gate?.run?.status === "timeout"` OR `=== "skipped"`** → Print a one-line warning naming the status and the `commands_run` value, then continue normally. These are signals, not walls: a slow test suite must not hostage the pipeline, and a project with no detectable quality commands must not block verify entry. The warning surfaces the degraded state without halting.
 
-- **`state.quality_gate?.run?.status === "pass"` OR `state.quality_gate === null`** → Continue silently. `pass` is the happy path; `null` means the gate has never been run for this cycle (the user skipped Stage 4.5 entirely, which is permitted - verify only *checks* the gate result, never *runs* the gate itself, per the 25-07 out-of-scope clause).
+- **`state.quality_gate?.run?.status === "pass"` OR `state.quality_gate === null`** → Continue silently. `pass` is the happy path; `null` means the gate has never been run for this cycle (the user skipped the quality-gate stage entirely, which is permitted - verify only *checks* the gate result, never *runs* the gate itself).
 
 This step is a pure read against the snapshot already loaded in Step 2 - no extra MCP call is required.
 
@@ -93,7 +92,7 @@ Step P2 — Live tool call:
 Record the preview probe result via `mcp__gdd_state__probe_connections` (batched with the storybook and chromatic probes below — one call per stage, see "Batched connections write" at the end of this section).
 ```
 
-When `preview: available`, the design-verifier agent runs Phase 4B - Screenshot Evidence to resolve `? VISUAL` heuristic flags with real screenshot evidence. See `agents/design-verifier.md` Phase 4B for the screenshot evidence loop.
+When `preview: available`, the design-verifier agent runs Stage 4B - Screenshot Evidence to resolve `? VISUAL` heuristic flags with real screenshot evidence. See `agents/design-verifier.md` Stage 4B for the screenshot evidence loop.
 
 ### Probe Storybook connection
 
@@ -202,7 +201,7 @@ Initialize iteration counter to 0 (used for fix loop limit in Step 3).
 
 Three agents run in sequence. Each waits for its completion marker before the next is spawned.
 
-**Note on lazy gates (Plan 10.1-04 / D-21):** Each full checker is preceded by a cheap Haiku gate that reads the diff and may return `{spawn: false}` to short-circuit. When gated out, `lazy_skipped: true` is appended to `.design/telemetry/costs.jsonl`. Gates: `design-verifier-gate` (before 1b), `design-integration-checker-gate` (before 1c). `design-context-checker-gate` is wired into `skills/discover/SKILL.md` Step 1.75.
+**Note on lazy gates:** Each full checker is preceded by a cheap Haiku gate that reads the diff and may return `{spawn: false}` to short-circuit. When gated out, `lazy_skipped: true` is appended to `.design/telemetry/costs.jsonl`. Gates: `design-verifier-gate` (before 1b), `design-integration-checker-gate` (before 1c). `design-context-checker-gate` is wired into `skills/discover/SKILL.md` Step 1.75.
 
 ### 1a. Run design-auditor first (retrospective 7-pillar audit)
 
@@ -274,9 +273,9 @@ Task("design-verifier", """
 You are the design-verifier agent. Run the 5-phase verification against completed design work.
 
 DESIGN-AUDIT.md (above) contains a retrospective 7-pillar qualitative audit from design-auditor.
-Read it as supplementary signal — incorporate the priority fix list into your Phase 5 gap analysis
+Read it as supplementary signal — incorporate the priority fix list into your Stage 5 gap analysis
 where relevant. The auditor's 1-4 scores complement your 0-10 category scores; they do not
-replace your Phase 1 category scoring.
+replace your Stage 1 category scoring.
 
 Context:
   auto_mode: <true|false>
@@ -432,7 +431,7 @@ Task("design-fixer", """
 @.design/DESIGN-CONTEXT.md
 </required_reading>
 
-Fix all BLOCKER and MAJOR gaps from ## Phase 5 - Gaps in DESIGN-VERIFICATION.md.
+Fix all BLOCKER and MAJOR gaps from ## Stage 5 - Gaps in DESIGN-VERIFICATION.md.
 For each gap: apply the targeted fix to the file/location in the gap's Location field.
 After each fix, make an atomic commit: fix(design-gap-GNN): [gap title].
 

package/skills/warm-cache/SKILL.md

@@ -62,7 +62,7 @@ Full + filtered command-output examples live in `./../cache-manager/cache-policy
 
 - **Pre-sprint**: `/gdd:warm-cache` is the recommended first line of a `/gdd:discover`, `/gdd:plan`, or `/gdd:verify` sprint. Users type it before the real command, or an orchestrator-level wrapper runs it automatically if `agent-metrics.json` (Plan 10.1-05) indicates the last sprint was > 5 min ago.
 - **`reference/shared-preamble.md`** (authored in Plan 10.1-04) is the essential file for this command - agents import it first per D-17, which makes the first N tokens of every agent's rendered system prompt identical, which is what Anthropic's prompt cache keys on.
-- **No interaction with `hooks/budget-enforcer.js`** - the hook is a PreToolUse gate; warm-cache runs as an ordinary Agent tool call itself and is subject to the hook (each no-op Haiku ping is budgeted and logged like any other spawn). This is intentional: warm-cache's own telemetry rows in `.design/telemetry/costs.jsonl` are the evidence that cache priming happened.
+- **No interaction with `hooks/budget-enforcer.ts`** - the hook is a PreToolUse gate; warm-cache runs as an ordinary Agent tool call itself and is subject to the hook (each no-op Haiku ping is budgeted and logged like any other spawn). This is intentional: warm-cache's own telemetry rows in `.design/telemetry/costs.jsonl` are the evidence that cache priming happened.
 
 ## Cost Model