@hegemonart/get-design-done 1.57.0 → 1.57.2

package/scripts/lib/apply-reflections/incubator-proposals.cjs

@@ -1,24 +1,23 @@
-// scripts/lib/apply-reflections/incubator-proposals.cjs — Plan 29-05
+// scripts/lib/apply-reflections/incubator-proposals.cjs
 //
 // Incubator-draft proposal class for /gdd:apply-reflections. Consumes drafts
-// authored by scripts/lib/incubator-author.cjs (Plan 29-04) at
+// authored by scripts/lib/incubator-author.cjs at
 // `.design/reflections/incubator/<slug>/` and exposes the 7 actions surfaced
 // in skills/apply-reflections/SKILL.md.
 //
 // Exports: discoverIncubatorDrafts, renderProposal, applyAccept, applyReject,
 //          applyEdit, checkStage1Gate, recordOptIn.
 //
-// Decisions honoured:
-//   * D-01 — checkStage1Gate is read-only; recordOptIn is the sole writer and
-//            only fires on explicit user confirmation. No auto-flip ever.
-//   * D-04 — applyAccept performs the full draft → final-artifact write +
-//            registry append in one call. No intermediate state.
-//   * D-05 — applyAccept calls validateScope from
-//            scripts/validate-incubator-scope.cjs BEFORE any filesystem
-//            mutation. Failure throws; registry and incubator subdir
-//            untouched. Non-bypassable.
-//   * D-12 — DRAFT.md is copied verbatim, so the drafter's `delegate_to: null`
-//            frontmatter survives the promotion.
+// Invariants:
+//   * checkStage1Gate is read-only; recordOptIn is the sole state writer and
+//     only fires on explicit user confirmation. No auto-flip ever.
+//   * applyAccept performs the full draft → final-artifact write + registry
+//     append in one call. No intermediate state.
+//   * applyAccept calls validateScope from
+//     scripts/validate-incubator-scope.cjs BEFORE any filesystem mutation.
+//     Failure throws; registry and incubator subdir untouched. Non-bypassable.
+//   * DRAFT.md is copied verbatim, so the drafter's `delegate_to: null`
+//     frontmatter survives the promotion.
 //
 // Style: CommonJS, zero external deps (node:fs / node:path / node:child_process /
 //        node:os only).
@@ -31,13 +30,14 @@ const child_process = require('node:child_process');
 const os = require('node:os');
 
 const { validateScope } = require('../../validate-incubator-scope.cjs');
+const touchesPatternMiner = require('../touches-pattern-miner.cjs');
 
 // ---  Constants  ---
 
 const DEFAULT_INCUBATOR_DIR = '.design/reflections/incubator';
 const DEFAULT_REGISTRY_PATH = 'reference/registry.json';
 const DEFAULT_GATE_SPEC_PATH = 'reference/capability-gap-stage-gate.md';
-const DEFAULT_STATE_PATH = '.planning/STATE.md';
+const DEFAULT_STATE_PATH = '.design/STATE.md';
 const OPT_IN_HEADING = '## Capability-gap Stage-1 opt-in';
 const OPT_IN_TOKEN_RE = /Stage-1 opt-in|capability.gap.*opt.in|confirmed_by/i;
 
@@ -94,7 +94,7 @@ function discoverIncubatorDrafts(options) {
   const drafts = [];
   for (const ent of entries) {
     if (!ent.isDirectory()) continue;
-    if (ent.name === 'archive') continue; // D-06: archived drafts not surfaced
+    if (ent.name === 'archive') continue; // archived drafts not surfaced
 
     const slugDir = path.join(incubatorDir, ent.name);
     const manifestPath = path.join(slugDir, 'manifest.json');
@@ -199,15 +199,15 @@ function renderUnifiedDiff(oldText, newText) {
   return out.join('\n');
 }
 
-// ---  applyAccept (D-04 + D-05)  ---
+// ---  applyAccept  ---
 
 /**
- * Promote draft → final artifact + registry entry in one call (D-04).
+ * Promote draft → final artifact + registry entry in one call.
  *
- * Order: validateScope (D-05; throws → no writes) → read DRAFT.md →
+ * Order: validateScope (throws → no writes) → read DRAFT.md →
  * [dryRun: return intent] → mkdirp parent → atomic-write target →
  * append-and-atomic-write registry → fs.rm incubator subdir last
- * (so partial failure leaves draft retryable — T-29.05-04).
+ * (so partial failure leaves draft retryable).
  */
 function applyAccept(draft, options) {
   const o = options || {};
@@ -217,7 +217,7 @@ function applyAccept(draft, options) {
     : path.join(repoRoot, o.registryPath || DEFAULT_REGISTRY_PATH);
   const dryRun = !!o.dryRun;
 
-  // Step 1 — D-05 scope guard. THROWS on failure; registry untouched.
+  // Step 1 — scope guard. THROWS on failure; registry untouched.
   validateScope(draft.target_path, { repoRoot });
 
   const draftBody = fs.readFileSync(draft.draft_path, 'utf8');
@@ -275,7 +275,7 @@ function appendRegistryEntry(registryPath, kind, entry) {
     throw new Error(`[incubator-proposals] registry root must be an object: ${registryPath}`);
   }
 
-  // Phase 14.5 self-authoring shape: { agents: [...], skills: [...] }.
+  // Self-authoring registry shape: { agents: [...], skills: [...] }.
   // Initialize missing arrays additively so we never clobber another schema's data.
   if (kind === 'agent') {
     if (!Array.isArray(registry.agents)) registry.agents = [];
@@ -356,10 +356,10 @@ function applyEdit(draft, options) {
   }
 }
 
-// ---  checkStage1Gate (D-01: read-only)  ---
+// ---  checkStage1Gate (read-only)  ---
 
 /**
- * Read-only Stage-1 gate inspection (D-01).
+ * Read-only Stage-1 gate inspection.
  *   thresholdMet  = count(registry entries with origin === 'incubator') ≥ K
  *   optInRecorded = state file contains an opt-in token
  *   summary       = human-readable one-liner
@@ -404,7 +404,7 @@ function checkStage1Gate(options) {
 /**
  * Pull `K` out of capability-gap-stage-gate.md. The doc encodes K as a row
  * in a markdown table:  `| K | 3 | Minimum number of stable clusters... |`.
- * If absent or unparseable, fall back to 3 (Phase 29 D-03 default).
+ * If absent or unparseable, fall back to 3 (the documented default).
  */
 function readK(gateSpecPath) {
   const src = safeReadFileSync(gateSpecPath);
@@ -415,12 +415,12 @@ function readK(gateSpecPath) {
   return Number.isFinite(v) && v > 0 ? v : 3;
 }
 
-// ---  recordOptIn (D-01: explicit-only)  ---
+// ---  recordOptIn (explicit-only)  ---
 
 /**
  * Persist the user's explicit Stage-1 opt-in to STATE.md. Idempotent.
  * IMPORTANT: this is the SOLE state writer in this module. Only invoke after
- * explicit user confirmation in the apply-reflections UX (D-01).
+ * explicit user confirmation in the apply-reflections UX.
  */
 function recordOptIn(options) {
   const o = options || {};
@@ -442,10 +442,41 @@ function recordOptIn(options) {
   return { optInRecorded: true, at, confirmedBy };
 }
 
+// ---  Touches-pattern proposals (Batch D D8 wire)  ---
+//
+// Surfaces recurring `Touches:` signatures across archived task files as
+// auto-crystallization proposals alongside the incubator drafts. The miner
+// is opt-in via `proposalsRoot` arg (defaults to the touches-pattern-miner
+// default location); when no archive exists yet, returns an empty list.
+
+function discoverTouchesPatternProposals(opts = {}) {
+  const cwd = opts.cwd || process.cwd();
+  const cycleDir = path.join(cwd, opts.cycleDir || touchesPatternMiner.DEFAULT_CYCLE_DIR);
+  if (!fs.existsSync(cycleDir)) return [];
+  try {
+    const mined = touchesPatternMiner.mine({
+      cycleDir,
+      minTasks: opts.minTasks,
+      minCycles: opts.minCycles,
+    });
+    if (!Array.isArray(mined) || mined.length === 0) return [];
+    return mined.map((pattern, i) => ({
+      type: 'touches-pattern',
+      id: `touches-pattern-${i + 1}`,
+      pattern,
+      summary: pattern.signature || pattern.canonical || `Pattern #${i + 1}`,
+    }));
+  } catch (_err) {
+    // Miner is best-effort — never block apply-reflections on its failure.
+    return [];
+  }
+}
+
 // ---  Exports  ---
 
 module.exports = {
   discoverIncubatorDrafts,
+  discoverTouchesPatternProposals,
   renderProposal,
   applyAccept,
   applyReject,

package/scripts/lib/design-search.cjs

@@ -124,14 +124,32 @@ function reindex(projectRoot) {
   db.close();
 }
 
+/**
+ * Re-wrap each whitespace/OR-delimited term in FTS5 double-quote escaping so
+ * that tokens containing `.`, `/`, `-`, or other punctuation that the trigram
+ * tokenizer treats as illegal bare-term characters are accepted as quoted
+ * phrase queries. This matches the pattern used in instinct-store.cjs.
+ *
+ * Examples:
+ *   "heuristics.md OR reference/heuristics.md"
+ *     -> '"heuristics.md" OR "reference/heuristics.md"'
+ *   "color tokens"
+ *     -> '"color" OR "tokens"'
+ */
+function _quoteFts5Query(rawQuery) {
+  const terms = rawQuery.split(/\s+OR\s+|\s+/).filter(Boolean);
+  return terms.map(t => '"' + t.replace(/"/g, '""') + '"').join(' OR ');
+}
+
 function _searchFts5(query, projectRoot, limit) {
   const dbPath = _dbPath(projectRoot);
   if (!fs.existsSync(dbPath)) reindex(projectRoot);
   const db = new Database(dbPath, { readonly: true });
   try {
+    const matchExpr = _quoteFts5Query(query);
     const rows = db.prepare(
       `SELECT file, line, text FROM docs WHERE docs MATCH ? ORDER BY rank LIMIT ?`
-    ).all(query, limit);
+    ).all(matchExpr, limit);
     return rows.map(r => ({ file: r.file, line: r.line, text: r.text }));
   } finally {
     db.close();
@@ -203,4 +221,4 @@ function search(query, projectRoot, opts = {}) {
   return _searchNode(query, projectRoot, limit);
 }
 
-module.exports = { search, reindex, backendName };
+module.exports = { search, reindex, backendName, _quoteFts5Query };

package/scripts/lib/install/converters/codex-plugin.cjs

@@ -306,9 +306,12 @@ function buildManifest(sources) {
     category,
     capabilities: ['Read', 'Write'],
     websiteURL: homepage || '',
+    // Codex uses /gdd- prefix uniformly (not /gdd: like Claude Code).
+    // Both lines use the same prefix to avoid the documented inconsistency
+    // (audit P1 #4 — committed manifest had mixed /gdd: and $gdd-).
     defaultPrompt: [
-      'Run /gdd:brief to start a design cycle.',
-      'Use $gdd-explore to audit a screen.',
+      'Run /gdd-brief to start a design cycle.',
+      'Run /gdd-explore to audit a screen.',
     ],
     brandColor: '#10A37F',
   };

package/scripts/lib/install/converters/cursor.cjs

@@ -24,6 +24,26 @@
  *
  * Pure / side-effect-free: no fs, no env, no path. `convert` is a
  * deterministic string → string transform.
+ *
+ * KNOWN LIMITATION — sibling .md files (audit batch H6, 2026-06-04):
+ *   The Cursor install drops ONLY `skills/<name>/SKILL.md`. Sibling
+ *   `.md` files living next to SKILL.md (e.g. `discover-procedure.md`,
+ *   `explore-procedure.md`, `cache-policy.md`) are NOT enumerated by
+ *   `runtime-artifact-layout.cjs#skillsKind` and therefore NOT installed.
+ *   Source SKILL.md files reference siblings via relative paths
+ *   (e.g. `./discover-procedure.md`); on Cursor those links resolve to
+ *   nothing.
+ *
+ *   This is a systemic limitation of the current `multi-artifact`
+ *   pipeline, not a Cursor-specific bug — it affects every runtime that
+ *   uses `skillsKind` (claude global, cursor, codex, copilot, antigravity,
+ *   windsurf, augment, trae, qwen, codebuddy). Fix requires extending the
+ *   StagedArtifact contract to emit multiple files per skill (one
+ *   SKILL.md + N siblings), updating `computeDestPath`, the foreign-file
+ *   detection in `detectMultiArtifactInstalled`, and the uninstall
+ *   enumeration in `uninstallMultiArtifact`. Tracked as a follow-up
+ *   beyond batch H6 scope. See `connections/cursor.md` for user-facing
+ *   guidance.
  */
 
 const shared = require('./shared.cjs');

package/scripts/lib/issue-reporter/report-flow.cjs

@@ -120,7 +120,7 @@ async function runReportFlow(args) {
       submitted: false,
       reason: 'disabled',
       surface: reason, // 'env' | 'config'
-      message: `/gdd:report-issue is disabled by ${reasonMsg}. Run \`gsd-health\` to see the active disable surface.`,
+      message: `/gdd:report-issue is disabled by ${reasonMsg}. Run \`/gdd:health\` to see the active disable surface.`,
     };
   }
 

package/scripts/lib/manifest/skills.json

@@ -18,7 +18,10 @@
       "name": "apply-reflections",
       "description": "Review and selectively apply proposals from .design/reflections/<cycle-slug>.md. Diffs each proposal, prompts user to accept/skip/edit, then writes changes.",
       "argument_hint": "[--cycle <slug>] [--filter <FRONTMATTER|REFERENCE|BUDGET|QUESTION|GLOBAL-SKILL>] [--dry-run]",
-      "tools": "Read, Write, Edit, Bash, Glob"
+      "tools": "Read, Write, Edit, Bash, Glob",
+      "composes_with": [
+        "audit"
+      ]
     },
     {
       "name": "audit",
@@ -50,6 +53,9 @@
       "description": "Stage 1 of 5 design intake that captures problem statement, audience, constraints, success metrics, and scope into .design/BRIEF.md, and bootstraps .design/STATE.md if missing. Use when starting a new design cycle and before {{command_prefix}}explore. Activates for requests involving capturing a problem statement, defining audience and constraints, or starting a new design brief.",
       "argument_hint": "[--re-brief to redo intake on existing project]",
       "tools": "Read, Write, AskUserQuestion, mcp__gdd_state__frontmatter_update, mcp__gdd_state__set_status, mcp__gdd_state__update_progress, mcp__gdd_state__get",
+      "composes_with": [
+        "explore"
+      ],
       "next_skills": [
         "explore"
       ]
@@ -63,7 +69,7 @@
     },
     {
       "name": "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
@@ -78,13 +84,19 @@
       "name": "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.",
       "argument_hint": "",
-      "user_invocable": true
+      "user_invocable": true,
+      "composes_with": [
+        "verify"
+      ]
     },
     {
       "name": "complete-cycle",
       "description": "Cycle closeout command that marks CYCLES.md entry complete, archives pipeline artifacts to .design/archive/cycle-N/, generates EXPERIENCE.md, rebuilds the search index, and resets STATE.md. Use when a design cycle has shipped and you're ready to start the next one.",
       "argument_hint": "[<retrospective note>]",
-      "tools": "Read, Write, Bash, AskUserQuestion"
+      "tools": "Read, Write, Bash, AskUserQuestion",
+      "composes_with": [
+        "audit"
+      ]
     },
     {
       "name": "connections",
@@ -112,7 +124,10 @@
       "name": "darkmode",
       "description": "Audit a project's dark mode implementation - detects architecture (CSS custom props, Tailwind `dark:` prefix, or JS class toggle), runs architecture-specific contrast / token-override / anti-pattern / meta-property checks, and writes a prioritized fix list to `.design/DARKMODE-AUDIT.md`. Use when the user wants to verify dark mode quality without re-running the full design pipeline. Read-only - no score writeback to `DESIGN.md`. Activates for requests involving auditing dark mode, checking dark-theme contrast, or dark-mode anti-patterns.",
       "argument_hint": "",
-      "user_invocable": true
+      "user_invocable": true,
+      "composes_with": [
+        "audit"
+      ]
     },
     {
       "name": "debug",
@@ -127,6 +142,11 @@
       "argument_hint": "[--auto] [--parallel] [--variants N]",
       "user_invocable": true,
       "tools": "Read, Write, Bash, Grep, Glob, Task, AskUserQuestion, mcp__gdd_state__get, mcp__gdd_state__transition_stage, mcp__gdd_state__update_progress, mcp__gdd_state__set_status, mcp__gdd_state__add_blocker, mcp__gdd_state__resolve_blocker, mcp__gdd_state__checkpoint",
+      "composes_with": [
+        "figma-write",
+        "paper-write",
+        "pencil-write"
+      ],
       "next_skills": [
         "verify"
       ]
@@ -136,13 +156,19 @@
       "frontmatter_name": "discover",
       "description": "Stage 1.5 of 4 orchestrator that probes Figma / Refero / Pinterest connections, spawns design-context-builder (auto-detect + interview) and (via lazy gate) design-context-checker (6-dimension validator), producing .design/DESIGN-CONTEXT.md. Use after {{command_prefix}}scan when a fast-path context build is wanted instead of the full {{command_prefix}}explore. Activates for requests involving detecting an existing design system, inventorying tokens and components, or onboarding a brownfield repo.",
       "argument_hint": "[--auto] [--incremental] [--full]",
-      "user_invocable": true
+      "user_invocable": true,
+      "composes_with": [
+        "explore"
+      ]
     },
     {
       "name": "discuss",
       "description": "Adaptive design interview command that spawns design-discussant in normal / --all / --spec mode to gather decisions via one-question-at-a-time AskUserQuestion, writing D-XX entries to STATE.md <decisions>. Use when locking design decisions outside the main pipeline or backfilling missing context.",
       "argument_hint": "[topic] [--all] [--spec] [--cycle <name>]",
-      "tools": "Read, Write, Task"
+      "tools": "Read, Write, Task",
+      "composes_with": [
+        "list-assumptions"
+      ]
     },
     {
       "name": "do",
@@ -155,6 +181,11 @@
       "description": "Stage 2 of 5 - unified exploration merging inventory grep + design interview. Probes 6 connections, scans the codebase, conducts the AskUserQuestion interview, and writes .design/DESIGN.md + DESIGN-DEBT.md + DESIGN-CONTEXT.md. Use after {{command_prefix}}brief to map the existing system and lock decisions before planning. Activates for requests involving researching design direction, gathering references, or exploring visual options.",
       "argument_hint": "[--skip-interview] [--skip-scan] [--incremental] [--full]",
       "tools": "Read, Write, Bash, Grep, Glob, Task, AskUserQuestion, mcp__gdd_state__get, mcp__gdd_state__transition_stage, mcp__gdd_state__probe_connections, mcp__gdd_state__update_progress, mcp__gdd_state__set_status, mcp__gdd_state__add_blocker, mcp__gdd_state__checkpoint, mcp__gdd_state__add_decision",
+      "composes_with": [
+        "discuss",
+        "list-assumptions",
+        "sketch"
+      ],
       "next_skills": [
         "plan"
       ]
@@ -272,13 +303,19 @@
       "name": "new-cycle",
       "description": "Start a new design cycle. Creates cycle scope in STATE.md, initializes .design/CYCLES.md entry. Each cycle has its own goal and tracks its own decisions/tasks/pipeline runs.",
       "argument_hint": "[<goal>]",
-      "tools": "Read, Write, AskUserQuestion"
+      "tools": "Read, Write, AskUserQuestion",
+      "composes_with": [
+        "brief"
+      ]
     },
     {
       "name": "new-project",
       "description": "Initialize a new get-design-done project. Gathers project context, creates PROJECT.md and STATE.md, initializes first cycle. Run once per project before any pipeline stage.",
       "argument_hint": "[--name <project-name>]",
       "tools": "Read, Write, AskUserQuestion, Bash, Glob",
+      "composes_with": [
+        "brief"
+      ],
       "next_skills": [
         "brief"
       ]
@@ -327,6 +364,20 @@
       "tools": "Read, Write, Bash, Grep, Glob",
       "registered_in_phase": "56"
     },
+    {
+      "name": "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"
+    },
+    {
+      "name": "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"
+    },
     {
       "name": "pause",
       "description": "Write a numbered checkpoint so work can resume in a new session without re-running completed stages.",
@@ -480,7 +531,7 @@
     },
     {
       "name": "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"
     },
@@ -489,7 +540,10 @@
       "frontmatter_name": "scan",
       "description": "Pre-pipeline initializer that maps an existing repo's design system (colors, typography, spacing, components, tokens), runs the anti-pattern audit, scores the 7 weighted categories, and writes DESIGN.md + .design/DESIGN-DEBT.md. Use when starting work in any new or existing repo before {{command_prefix}}discover. Activates for requests involving a fast read-only anti-pattern sweep, a quick design lint, or spotting slop without a full audit.",
       "argument_hint": "[--quick] [--full]",
-      "user_invocable": true
+      "user_invocable": true,
+      "composes_with": [
+        "explore"
+      ]
     },
     {
       "name": "settings",
@@ -503,13 +557,19 @@
       "description": "Post-verify PR flow - creates a clean PR branch, invokes code review check, and prepares the PR for merge. Activates for requests involving finishing a cycle, packaging design output, or moving work to a pull request.",
       "argument_hint": "[--title <PR title>] [--draft]",
       "tools": "Read, Write, Bash, AskUserQuestion, Task",
-      "disable_model_invocation": true
+      "disable_model_invocation": true,
+      "composes_with": [
+        "pr-branch"
+      ]
     },
     {
       "name": "sketch",
       "description": "Multi-variant HTML design exploration that creates .design/sketches/<slug>/ with N standalone variants (default 3), browser-openable directly via file:// without a build step. Use when answering 'what could this look like?' before committing to a direction.",
       "argument_hint": "[topic] [--variants N] [--quick]",
-      "tools": "Read, Write, AskUserQuestion, Bash"
+      "tools": "Read, Write, AskUserQuestion, Bash",
+      "composes_with": [
+        "sketch-wrap-up"
+      ]
     },
     {
       "name": "sketch-wrap-up",
@@ -526,7 +586,10 @@
       "name": "spike",
       "description": "Timeboxed feasibility experiment that creates .design/spikes/<slug>/ with HYPOTHESIS.md, success/failure criteria, scratch/ subdirectory, and a default 60-minute timebox. Use when answering 'can this work?' before betting design or implementation effort on a risky approach.",
       "argument_hint": "[hypothesis] [--timebox <minutes>]",
-      "tools": "Read, Write, Bash, AskUserQuestion"
+      "tools": "Read, Write, Bash, AskUserQuestion",
+      "composes_with": [
+        "spike-wrap-up"
+      ]
     },
     {
       "name": "spike-wrap-up",
@@ -631,6 +694,10 @@
       "argument_hint": "[--auto] [--post-handoff]",
       "user_invocable": true,
       "tools": "mcp__gdd_state__get, mcp__gdd_state__transition_stage, mcp__gdd_state__add_must_have, mcp__gdd_state__add_blocker, mcp__gdd_state__resolve_blocker, mcp__gdd_state__update_progress, mcp__gdd_state__set_status, mcp__gdd_state__checkpoint, mcp__gdd_state__probe_connections",
+      "composes_with": [
+        "audit",
+        "debug"
+      ],
       "next_skills": [
         "ship"
       ]

package/scripts/lib/state/migrate-to-sqlite.cjs

@@ -47,7 +47,7 @@ function findPackageRoot(startDir) {
     try { pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8')); } catch { pkg = null; }
     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;
@@ -214,19 +214,24 @@ function buildDryRunDiff(ops) {
  * Migrate .design/STATE.md (and supplementary stores) into the SQLite database.
  *
  * @param {object} opts
- * @param {string} [opts.projectRoot]  - project root dir (defaults to cwd / env)
- * @param {boolean} [opts.dryRun=false] - wrap writes in BEGIN/ROLLBACK + print diff
- * @param {boolean} [opts.force=false]  - same as --migrate-state flag; required to actually write
+ * @param {string} [opts.projectRoot]    - project root dir (defaults to cwd / env)
+ * @param {string} [opts.statePath]      - explicit path to STATE.md (overrides projectRoot lookup)
+ * @param {boolean} [opts.dryRun=false]  - wrap writes in BEGIN/ROLLBACK + print diff
+ * @param {boolean} [opts.force=false]   - same as --migrate-state flag; required to actually write
+ * @param {boolean} [opts.upsertOnly=false] - re-parse markdown and UPSERT without wiping unrelated rows
+ *                                            (used by the R8 freshness guard to fold hand-edits into SQLite)
  * @returns {Promise<{migrated:boolean, tables:object, dryRun:boolean, skipped:boolean, reason:string}>}
  */
 async function migrateToSqlite(opts = {}) {
-  const { dryRun = false, force = false } = opts;
+  const { dryRun = false, force = false, upsertOnly = false } = opts;
+  // upsertOnly implies force (it's always an internal call, not user-facing opt-in).
+  const effectiveForce = force || upsertOnly;
   const projectRoot = resolveProjectRoot(opts.projectRoot);
 
   // Opt-in guard: --migrate-state / force required.
   // This fires first (before the SQLite probe) so the message is consistent
   // regardless of whether better-sqlite3 is installed.
-  if (!force) {
+  if (!effectiveForce) {
     const notice =
       'Migration is opt-in in v1.57.0. Re-run with --migrate-state to proceed.';
     return {
@@ -254,7 +259,7 @@ async function migrateToSqlite(opts = {}) {
   }
 
   // Read STATE.md.
-  const statePath = path.join(projectRoot, '.design', 'STATE.md');
+  const statePath = opts.statePath || path.join(projectRoot, '.design', 'STATE.md');
   if (!fs.existsSync(statePath)) {
     return {
       migrated: false,
@@ -440,9 +445,20 @@ async function migrateToSqlite(opts = {}) {
       );
       counts.decisions++;
       ops.push({ action: 'upsert', table: 'decisions', id: d.id, fields: { status: d.status, body_md: d.text, raw_line: rawLine } });
+      // BUG-05: populate FTS5 table so queryDecisions returns hits.
+      // FTS5 virtual tables do not support ON CONFLICT — use DELETE + INSERT pattern.
+      // Guard: if FTS5 tables are absent (no-fts5 build), skip without throwing.
+      try {
+        db.prepare('DELETE FROM decisions_fts WHERE id = ?').run(d.id);
+        db.prepare('INSERT INTO decisions_fts (id, body_md, tags) VALUES (?, ?, ?)').run(d.id, d.text, null);
+      } catch { /* FTS5 table absent - skip */ }
     }
 
     // --- blockers ---
+    // BUG-02: DELETE existing rows for this cycle_id before re-inserting to prevent duplication.
+    // The blockers table uses AUTOINCREMENT PK with no natural-key ON CONFLICT, so
+    // re-running migrate without this delete would DUPLICATE every blocker row.
+    db.prepare('DELETE FROM blockers WHERE cycle_id = ?').run(cycleId);
     for (let i = 0; i < blockers.length; i++) {
       const b = blockers[i];
       const rawLine = `[${b.stage}] [${b.date}]: ${b.text}`;