@hegemonart/get-design-done 1.57.1 → 1.57.3

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/scripts/lib/worktree-resolve.cjs

@@ -2,9 +2,9 @@
 /**
  * scripts/lib/worktree-resolve.cjs — Phase 49 (Quick Anti-Slop Floor).
  *
- * Redirect `.design/` and `.planning/` writes to the MAIN repo root when GDD
- * runs inside a git WORKTREE. A worktree has its own ephemeral checkout dir; a
- * naive `process.cwd()`-relative `.design/STATE.md` write would land inside the
+ * Redirect `.design/` writes to the MAIN repo root when GDD runs inside a git
+ * WORKTREE. A worktree has its own ephemeral checkout dir; a naive
+ * `process.cwd()`-relative `.design/STATE.md` write would land inside the
  * throwaway worktree and get lost (or leak) when the worktree is removed. We
  * detect the worktree, resolve the main repo root, and point artifact writes
  * there so state survives across worktree lifecycles.
@@ -167,17 +167,6 @@ function resolveDesignRoot(cwd = process.cwd(), exec) {
   return path.join(resolveRepoRoot(cwd, exec), '.design');
 }
 
-/**
- * Absolute `.planning` root in the MAIN repo (worktree-safe).
- *
- * @param {string} [cwd=process.cwd()]
- * @param {(cmd: string, args: string[]) => string} [exec]
- * @returns {string}
- */
-function resolvePlanningRoot(cwd = process.cwd(), exec) {
-  return path.join(resolveRepoRoot(cwd, exec), '.planning');
-}
-
 /** One-shot guard so the redirect notice prints at most once per process. */
 let NOTICE_EMITTED = false;
 
@@ -193,7 +182,7 @@ let NOTICE_EMITTED = false;
 function noticeOnce(targetRoot, write) {
   if (NOTICE_EMITTED) return false;
   NOTICE_EMITTED = true;
-  const line = `worktree detected -> .design/.planning redirected to ${targetRoot}\n`;
+  const line = `worktree detected -> .design redirected to ${targetRoot}\n`;
   try {
     if (typeof write === 'function') {
       write(line);
@@ -215,7 +204,6 @@ module.exports = {
   isWorktree,
   resolveRepoRoot,
   resolveDesignRoot,
-  resolvePlanningRoot,
   noticeOnce,
   _resetNoticeForTests,
 };

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/README.md

@@ -0,0 +1,46 @@
+# `source/skills/` - Canonical Skill BODY Source
+
+This directory is the **canonical home for skill body content**. Every `SKILL.md` under
+`source/skills/<slug>/` is the editable truth: the per-skill prose, examples, procedure files,
+and any sibling docs (`*-procedure.md`, `*-rules.md`, emitters, etc.) live here.
+
+`skills/` (the sibling at the repo root) is a **built artifact**, regenerated from this directory
+by `npm run build:skills`. Do not hand-edit `skills/<slug>/SKILL.md` - your edit will be wiped on
+the next build and the CI drift gate (`build:skills:check`) will fail.
+
+## Source-of-truth split (what lives where)
+
+| Concern | Source of truth | How it reaches `skills/` |
+|---|---|---|
+| **Body content** (everything below the frontmatter) | `source/skills/<slug>/SKILL.md` | `scripts/build-skills.cjs` walks `source/skills/`, applies per-harness placeholder substitution, writes to `skills/` |
+| **Universal frontmatter** (`name`, `description`, `argument-hint`, `tools`, `user-invocable`, `disable-model-invocation`) | `scripts/lib/manifest/skills.json` | `scripts/generate-skill-frontmatter.cjs` writes the managed block into `source/skills/<slug>/SKILL.md`, then `build:skills` copies it onward |
+| **Non-managed frontmatter** (e.g. `color`, `model`, custom keys) | `source/skills/<slug>/SKILL.md` itself (preserved verbatim) | carried through both generators unchanged |
+
+The forward direction is **`skills.json` -> `source/skills/` -> `skills/`**.
+Treat that direction as canonical; the `--extract` mode of `generate-skill-frontmatter.cjs` exists
+only to seed the manifest from current sources when reconciling drift.
+
+## Editing protocol
+
+1. **Edit body** -> modify `source/skills/<slug>/SKILL.md` (anything below the frontmatter delimiter).
+2. **Edit universal frontmatter** -> modify `scripts/lib/manifest/skills.json`, then run
+   `npm run generate:skill-frontmatter`.
+3. **Edit non-managed frontmatter** -> modify `source/skills/<slug>/SKILL.md` directly; the generator
+   preserves it.
+4. **Regenerate the built surface** -> `npm run build:skills`. This rewrites `skills/<slug>/SKILL.md`
+   byte-for-byte.
+5. **Verify no drift** -> `npm run build:skills:check` (CI gate) and `npm run generate:skill-frontmatter:check`.
+
+## What npm ships
+
+`package.json` `files` lists `skills/` (the built surface); `source/skills/` is repo-only and is
+**not** distributed via npm. Users running `npm install @hegemonart/get-design-done` get the
+compiled skills; only contributors editing this repo touch `source/skills/`.
+
+## Cross-references
+
+- `scripts/build-skills.cjs` - the multi-harness orchestrator that compiles this directory.
+- `scripts/lib/build/factory.cjs` - the pure transformer applied per-harness.
+- `scripts/lib/manifest/README.md` - explains why `skills.json` is the universal-frontmatter SoT.
+- `scripts/generate-skill-frontmatter.cjs` - manifest -> source-frontmatter generator (with
+  `--check` drift gate and `--extract` reverse mode).

package/skills/bootstrap-ds/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gdd-bootstrap-ds
-description: "Bootstraps a design system for a GREENFIELD project that has none - no Figma, no tokens, no component library. Takes a brand input (primary color + optional secondary + tone tags + target framework) and emits a coherent OKLCH token system (color tints, modular type scale, 4pt/8pt spacing, radius + motion defaults) in 3 variants to pick from, then scaffolds proof components (button/input/card). Use at the start of a brand-new project, or when /gdd:discover finds no existing design system. Never invents a brand; never overwrites an existing DS."
+description: "Bootstraps a design system for a GREENFIELD project that has none - no Figma, no tokens, no component library. Takes a brand input (primary color + optional secondary + tone tags + target framework) and emits a coherent OKLCH token system (color tints, modular type scale, 4pt/8pt spacing, radius + motion defaults) in 3 variants to pick from, then scaffolds proof components (button/input/card). Use at the start of a brand-new project, or when /gdd:explore finds no existing design system. Never invents a brand; never overwrites an existing DS."
 argument-hint: "[--primary <color>] [--secondary <color>] [--tone <tags>] [--framework web|native-ios|native-android|flutter]"
 user-invocable: true
 tools: Read, Write, Bash, Glob, Grep, AskUserQuestion, Task

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/compare/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gdd-compare
-description: "Compute the delta between the `DESIGN.md` baseline (from scan) and the `DESIGN-VERIFICATION.md` result (from verify), reporting per-category score delta, anti-pattern delta (resolved vs new), must-have pass/fail change, and design drift (regressions without covering tasks in `DESIGN-PLAN.md`). Use after `verify` to measure whether a design pipeline cycle actually improved the design. Writes `.design/COMPARE-REPORT.md`. Activates for requests involving diffing a design baseline against verification output, or a before-after design delta."
+description: "Compute the delta between the `DESIGN.md` baseline (from explore) and the `DESIGN-VERIFICATION.md` result (from verify), reporting per-category score delta, anti-pattern delta (resolved vs new), must-have pass/fail change, and design drift (regressions without covering tasks in `DESIGN-PLAN.md`). Use after `verify` to measure whether a design pipeline cycle actually improved the design. Writes `.design/COMPARE-REPORT.md`. Activates for requests involving diffing a design baseline against verification output, or a before-after design delta."
 argument-hint: ""
 user-invocable: true
 ---

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/new-cycle/SKILL.md

@@ -7,7 +7,7 @@ tools: Read, Write, AskUserQuestion
 
 # /gdd:new-cycle
 
-The cycle is the hierarchical unit above individual pipeline runs: **Cycle > Pipeline run > Wave > Task**. Each cycle has a goal, tracks its own decisions, and can span many pipeline runs. See `./milestone-completeness-rubric.md` §"Cycle level" for what counts as cycle completion (used by `/gdd:complete-cycle` to close the cycle).
+The cycle is the hierarchical unit above individual pipeline runs: **Cycle > Pipeline run > Wave > Task**. Each cycle has a goal, tracks its own decisions, and can span many pipeline runs. `/gdd:complete-cycle` closes the cycle once goals are met and a retrospective is captured.
 
 ## Steps
 

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/peer-cli-customize/SKILL.md

@@ -79,7 +79,6 @@ See `./../peer-cli-add/peer-cli-protocol.md` §"Edge cases" for: rewire-to-unmat
 - `scripts/validate-frontmatter.ts` (Plan 27-06) - `delegate_to` validation.
 - `scripts/lib/peer-cli/registry.cjs` (Plan 27-05) - capability matrix.
 - `skills/peer-cli-add/SKILL.md` - for adding a NEW peer (this skill rewires among existing peers).
-- `.planning/phases/27-peer-cli-delegation/CONTEXT.md` D-06 - decision lineage.
 
 ## Record
 

package/skills/peers/SKILL.md

@@ -85,7 +85,7 @@ The table IS the output. No follow-up prose. Users act on it: `(opt-in disabled)
 
 - `./../peer-cli-add/peer-cli-protocol.md` - ACP/ASP handshake + adapter scaffold (procedure ref shared with peer-cli-add/customize).
 - `./reference/peer-cli-capabilities.md` (Plan 27-05) - full capability matrix doc.
-- `scripts/lib/peer-cli/registry.cjs` (Plan 27-05), `scripts/lib/install/runtimes.cjs` (Plan 27-11), `skills/peer-cli-customize/SKILL.md`, `skills/peer-cli-add/SKILL.md`, `.planning/phases/27-peer-cli-delegation/CONTEXT.md` D-10.
+- `scripts/lib/peer-cli/registry.cjs` (Plan 27-05), `scripts/lib/install/runtimes.cjs` (Plan 27-11), `skills/peer-cli-customize/SKILL.md`, `skills/peer-cli-add/SKILL.md`.
 
 ## Record
 

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/reflect/procedures/capability-gap-scan.md

@@ -117,4 +117,3 @@ npm test
 - `reference/schemas/events.schema.json` - the `capability_gap` event class shipped by Plan 29-01 (the 7-field shape + `TrajectoryRef` definition).
 - `scripts/lib/event-chain.cjs` - `appendChainEvent` (the real emitter API; 29-01 did NOT ship a separate helper file).
 - `scripts/lib/bandit-router.cjs` - Phase 23.5 posterior file producer (the source for scan #2).
-- `.planning/phases/29-capability-gap-self-authoring/CONTEXT.md` - phase decisions (D-02 7-field shape, D-07 hash-pinning, D-08 MCP carve-out, D-11 tmpdir tests).

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/report-issue/report-issue-procedure.md

@@ -117,4 +117,3 @@ Body is written to a tmp file to avoid arg-length and shell-escaping. URL parsed
 - [SKILL.md](./SKILL.md) - entry contract.
 - `reference/pseudonymization-rules.md` - full R1..R8 rule catalog (Plan 30-01).
 - `reference/known-failure-modes.md` - triage catalogue (Plan 30-03).
-- `.planning/phases/30-issue-reporter/CONTEXT.md` - phase decisions D-01..D-15.