@hegemonart/get-design-done 1.57.1 → 1.57.2

package/scripts/lib/state/state-store.cjs

@@ -15,8 +15,8 @@
  *   setPosition(position, opts)     - upsert state_position
  *   getPosition(opts)               - return current position
  *   queryDecisions(ftsQuery, opts)  - FTS5 search over decisions (or JS fallback)
- *   migrate(migrateOpts)            - lazy-require migrate-to-sqlite.cjs (Executor B)
- *   render(projectRoot)             - lazy-require render-markdown.cjs (Executor C)
+ *   migrate(migrateOpts)            - lazy-require migrate-to-sqlite.cjs
+ *   render(projectRoot)             - lazy-require render-markdown.cjs
  *   backendName()                   - return BACKEND string
  *
  * R7 dual-write: every SQLite MUTATION wraps writeStructured() + renderMarkdown()
@@ -103,18 +103,18 @@ async function loadSdk() {
 }
 
 // ---------------------------------------------------------------------------
-// Lazy-require helpers for Executor B and C modules (PINNED names).
-// Do NOT call require() on these at module load - they may not exist yet.
+// Lazy-require helpers for the migrate and render sibling modules (PINNED names).
+// Loaded on first call so a missing better-sqlite3 binding does not crash module load.
 // ---------------------------------------------------------------------------
 
-/** @type {any|null} Cached migrate-to-sqlite module (Executor B). */
+/** @type {any|null} Cached migrate-to-sqlite module. */
 let _migrateModule = null;
-/** @type {any|null} Cached render-markdown module (Executor C). */
+/** @type {any|null} Cached render-markdown module. */
 let _renderModule = null;
 
 /**
- * Lazy-require ./migrate-to-sqlite.cjs (Executor B's module).
- * Returns null if not yet available.
+ * Lazy-require ./migrate-to-sqlite.cjs.
+ * Returns null if the require fails (e.g. better-sqlite3 missing).
  * @returns {any|null}
  */
 function _requireMigrate() {
@@ -128,8 +128,8 @@ function _requireMigrate() {
 }
 
 /**
- * Lazy-require ./render-markdown.cjs (Executor C's module).
- * Returns null if not yet available.
+ * Lazy-require ./render-markdown.cjs.
+ * Returns null if the require fails.
  * @returns {any|null}
  */
 function _requireRender() {
@@ -280,7 +280,7 @@ function _dualWrite(db, statePath, cycleId, writeStructured, sdk) {
       db.prepare('INSERT OR REPLACE INTO _meta(key, value) VALUES (?, ?)').run('last_render_sha256', newSha);
     }
     // If render module not available or sdk not loaded, still write the structured data.
-    // STATE.md will be stale until Executor C's render module is present.
+    // STATE.md will be stale until the render module loads successfully.
   });
   txn();
 }
@@ -654,19 +654,60 @@ function _currentCycleId(db) {
 }
 
 // ---------------------------------------------------------------------------
-// migrate - lazy delegate to migrate-to-sqlite.cjs (Executor B).
+// migrate - async lazy delegate to migrate-to-sqlite.cjs.
 // ---------------------------------------------------------------------------
 
 /**
- * Run migration from markdown STATE.md to SQLite.
- * Delegates to ./migrate-to-sqlite.cjs (created by Executor B).
- * If that module is not yet present, logs a clear message and returns.
+ * Run migration from markdown `.design/STATE.md` to the SQLite state database.
  *
- * @param {{ statePath?: string, dbPath?: string, projectRoot?: string,
- *           dryRun?: boolean, upsertOnly?: boolean }} [migrateOpts]
- * @returns {{ migrated: boolean, backend: string, message?: string }}
+ * This function is the public store-level entry point for the
+ * `--migrate-state` flow. It lazy-loads `./migrate-to-sqlite.cjs` on first call
+ * and delegates to whichever export it exposes (`migrateToSqlite`,
+ * `migrate`, or `migrateState`), in priority order. The underlying
+ * `migrateToSqlite` is itself async (it dynamically imports
+ * `sdk/state/parser.ts` and uses node:fs/promises for IO), so this wrapper
+ * is async and always returns a Promise.
+ *
+ * The function NEVER throws on infrastructure failures:
+ *   - `BACKEND === 'markdown'` (no better-sqlite3) → resolves with
+ *     `{ migrated: false, backend: 'markdown', message: ... }`.
+ *   - `require('./migrate-to-sqlite.cjs')` failed → resolves with
+ *     `{ migrated: false, backend: 'sqlite', message: ... }`.
+ *   - The delegate module loaded but exposes no recognized export → resolves
+ *     with `{ migrated: false, backend: 'sqlite', message: ... }`.
+ *
+ * Errors thrown by the delegate (parser failure, schema mismatch, etc.) are
+ * propagated as a rejected Promise - callers should `await` and handle.
+ *
+ * Idempotent: calling `migrate()` repeatedly on a clean database is safe
+ * (the underlying migration uses `INSERT ... ON CONFLICT ... DO UPDATE`).
+ * Migration is opt-in: the delegate refuses to write unless `force:true` or
+ * the CLI `--migrate-state` flag is set (a notice is returned instead).
+ *
+ * Dual-channel result shapes:
+ *   - markdown floor:   { migrated: false, backend: 'markdown', message }
+ *   - sqlite path:      { migrated: boolean, tables: {...counts}, dryRun,
+ *                         skipped, reason }
+ * The caller MUST inspect `migrated` (the boolean) — never `backend` alone —
+ * to decide whether the operation actually performed writes.
+ *
+ * @async
+ * @param {object} [migrateOpts] options forwarded to the delegate
+ * @param {string} [migrateOpts.statePath]    explicit path to STATE.md
+ * @param {string} [migrateOpts.dbPath]       explicit path to state.sqlite
+ * @param {string} [migrateOpts.projectRoot]  project root for path lookup
+ * @param {boolean} [migrateOpts.dryRun]      wrap writes in BEGIN/ROLLBACK
+ * @param {boolean} [migrateOpts.force]       same as `--migrate-state` flag
+ * @param {boolean} [migrateOpts.upsertOnly]  re-parse + UPSERT without wiping
+ *                                            unrelated rows (used by the R8
+ *                                            freshness guard)
+ * @returns {Promise<{ migrated: boolean, backend?: string, message?: string,
+ *   tables?: object, dryRun?: boolean, skipped?: boolean, reason?: string }>}
+ *   Resolves with the migration result; rejects only on delegate exceptions.
+ * @see migrate-to-sqlite.cjs for the underlying transactional implementation
+ * @see render for the reverse direction (SQLite → STATE.md)
  */
-function migrate(migrateOpts = {}) {
+async function migrate(migrateOpts = {}) {
   if (BACKEND !== 'sqlite') {
     return {
       migrated: false,
@@ -679,17 +720,18 @@ function migrate(migrateOpts = {}) {
     return {
       migrated: false,
       backend: 'sqlite',
-      message: 'migrate-to-sqlite.cjs not yet available (Executor B pending)',
+      message: 'migrate-to-sqlite.cjs could not be loaded (require failed)',
     };
   }
+  // Delegate is async; await so callers see the resolved result, not a Promise.
   if (typeof mod.migrateToSqlite === 'function') {
-    return mod.migrateToSqlite(migrateOpts);
+    return await mod.migrateToSqlite(migrateOpts);
   }
   if (typeof mod.migrate === 'function') {
-    return mod.migrate(migrateOpts);
+    return await mod.migrate(migrateOpts);
   }
   if (typeof mod.migrateState === 'function') {
-    return mod.migrateState(migrateOpts);
+    return await mod.migrateState(migrateOpts);
   }
   return {
     migrated: false,
@@ -699,13 +741,13 @@ function migrate(migrateOpts = {}) {
 }
 
 // ---------------------------------------------------------------------------
-// render - lazy delegate to render-markdown.cjs (Executor C).
+// render - lazy delegate to render-markdown.cjs.
 // ---------------------------------------------------------------------------
 
 /**
  * Re-render STATE.md from SQLite state (reverse of migration).
- * Delegates to ./render-markdown.cjs (created by Executor C).
- * If that module is not yet present, logs a clear message and returns null.
+ * Delegates to ./render-markdown.cjs.
+ * If that module cannot be loaded, returns null silently.
  *
  * @param {string} [projectRoot]
  * @returns {Promise<string|null>} rendered markdown string, or null if unavailable

package/sdk/cli/commands/stage.ts

@@ -110,6 +110,18 @@ const VALID_STAGE_NAMES = new Set<string>([
   'discuss',
 ]);
 
+// Names of top-level `gdd-sdk` subcommands that users sometimes try to invoke
+// as stages (e.g. `gdd-sdk stage audit`). When a stage name collides with one,
+// surface a "did you mean" hint pointing at the real invocation.
+const TOP_LEVEL_COMMANDS_OFTEN_CONFUSED_FOR_STAGES = new Set<string>([
+  'audit',
+  'build',
+  'dashboard',
+  'init',
+  'query',
+  'run',
+]);
+
 export async function stageCommand(
   args: ParsedArgs,
   deps: StageCommandDeps = {},
@@ -134,6 +146,11 @@ export async function stageCommand(
     stderr.write(
       `gdd-sdk stage: "${stageName}" is not one of brief|explore|plan|design|verify|discuss\n`,
     );
+    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.\n`,
+      );
+    }
     return 3;
   }
 

package/sdk/cli/index.js

@@ -8253,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;
@@ -8271,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/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