@hegemonart/get-design-done 1.57.1 → 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/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/query-surface.cjs

@@ -46,7 +46,8 @@ function _findPackageRoot(startDir) {
 const PKG_ROOT = _findPackageRoot(__dirname);
 
 // ---------------------------------------------------------------------------
-// Lazy-require state-backend.cjs (Executor A).
+// Lazy-require state-backend.cjs (loaded on first call so optional better-sqlite3
+// binding does not crash module load).
 // ---------------------------------------------------------------------------
 let _backend = null;
 function _requireBackend() {
@@ -65,7 +66,7 @@ function _requireBackend() {
 }
 
 // ---------------------------------------------------------------------------
-// Lazy-require migrate-to-sqlite.cjs (Executor B) - used by recover().
+// Lazy-require migrate-to-sqlite.cjs - used by recover().
 // ---------------------------------------------------------------------------
 let _migrate = null;
 function _requireMigrate() {
@@ -202,6 +203,42 @@ function query(sql, opts = {}) {
   }
 }
 
+// ---------------------------------------------------------------------------
+// _safeBackup(srcPath, bakPath) - H5 backup-guard.
+//
+// Copy srcPath to bakPath, then verify the backup exists AND is non-empty
+// AFTER the copy. Returns true only when the backup is a faithful non-empty
+// copy of the source. Callers MUST check the return value before unlinking
+// the source - the dangerous pattern is `copy → unconditional unlink`, where
+// a silent copy failure (or zero-byte destination) means the unlink deletes
+// the only remaining data.
+//
+// Defensive: never throws. Returns false on any error or empty backup.
+//
+// @param {string} srcPath path to source file (must exist)
+// @param {string} bakPath path for the backup (created/overwritten)
+// @returns {boolean} true iff bakPath exists and is non-empty after copy
+// ---------------------------------------------------------------------------
+
+function _safeBackup(srcPath, bakPath) {
+  try {
+    fs.copyFileSync(srcPath, bakPath);
+  } catch {
+    return false;
+  }
+  // Post-copy verification: the backup must EXIST and be NON-EMPTY.
+  // copyFileSync can silently produce a 0-byte file in some failure modes
+  // (interrupted IO, full disk after open). An empty backup is not a backup;
+  // unlinking the source after one would destroy the data.
+  try {
+    const st = fs.statSync(bakPath);
+    if (!st.isFile() || st.size === 0) return false;
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 // ---------------------------------------------------------------------------
 // rotateBak(dbPath) - shift .bak.0..9, cap at 10.
 // ---------------------------------------------------------------------------
@@ -247,12 +284,10 @@ function backupCycle(opts = {}) {
   }
   rotateBak(dbPath);
   const bak0 = `${dbPath}.bak.0`;
-  try {
-    fs.copyFileSync(dbPath, bak0);
+  if (_safeBackup(dbPath, bak0)) {
     return { backed_up: true, path: bak0 };
-  } catch (err) {
-    return { backed_up: false, message: `backupCycle: copy failed: ${err.message}` };
   }
+  return { backed_up: false, message: `backupCycle: copy failed or backup is empty at ${bak0}` };
 }
 
 // ---------------------------------------------------------------------------
@@ -282,9 +317,18 @@ function demigrate(opts = {}) {
     };
   }
   // Take a backup before removing.
+  // H5 backup-guard: only unlink when the backup is a faithful non-empty copy.
+  // If the copy failed (or produced a 0-byte file), refuse to unlink the source -
+  // we'd be deleting the only remaining data.
   rotateBak(dbPath);
   const bak0 = `${dbPath}.bak.0`;
-  try { fs.copyFileSync(dbPath, bak0); } catch { /* best-effort backup */ }
+  if (!_safeBackup(dbPath, bak0)) {
+    return {
+      demigrated: false,
+      message: `demigrate: refusing to remove ${dbPath} - backup at ${bak0} ` +
+        `is missing or empty after copyFileSync (would lose data).`,
+    };
+  }
   try {
     fs.unlinkSync(dbPath);
   } catch (err) {
@@ -330,10 +374,23 @@ async function recover(opts = {}) {
   const dbPath = opts.dbPath || backend.sqlitePath(opts.projectRoot || process.cwd());
 
   // Step 1: Rotate existing (possibly corrupt) file to .bak.0.
+  // H5 backup-guard: only unlink the source after a verified non-empty backup.
+  // For recover() the source MAY already be corrupt - so an empty/failed backup
+  // is still significant signal. We refuse to unlink when the backup is missing
+  // OR zero bytes, so the operator retains a copy of the corrupt file for
+  // diagnostics. The caller can manually delete and retry once the backup
+  // location is writable.
   if (fs.existsSync(dbPath)) {
     rotateBak(dbPath);
     const bak0 = `${dbPath}.bak.0`;
-    try { fs.copyFileSync(dbPath, bak0); } catch { /* best-effort */ }
+    if (!_safeBackup(dbPath, bak0)) {
+      return {
+        recovered: false,
+        message: `recover: refusing to remove ${dbPath} - backup at ${bak0} ` +
+          `is missing or empty after copyFileSync (would lose corrupt file ` +
+          `before rebuild). Resolve disk/permission issues and retry.`,
+      };
+    }
     try { fs.unlinkSync(dbPath); } catch (err) {
       return { recovered: false, message: `recover: could not remove corrupt ${dbPath}: ${err.message}` };
     }
@@ -344,7 +401,7 @@ async function recover(opts = {}) {
   if (!migrate) {
     return {
       recovered: false,
-      message: 'recover: migrate-to-sqlite.cjs not available (Executor B not yet present). ' +
+      message: 'recover: migrate-to-sqlite.cjs could not be loaded (require failed). ' +
         'Cannot rebuild SQLite from markdown.',
     };
   }
@@ -399,5 +456,6 @@ module.exports = {
   // Expose internals for testing.
   _assertReadonly,
   _firstToken,
+  _safeBackup,
   DENIED_TOKENS,
 };