@hegemonart/get-design-done 1.57.0 → 1.57.2

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() {
@@ -128,8 +129,13 @@ function _firstToken(sql) {
 }
 
 /**
- * Assert that the SQL query is a safe readonly SELECT.
- * Throws with a descriptive message when the first token is denied or not SELECT.
+ * Assert that the SQL query is a safe readonly SELECT (or CTE: WITH ... SELECT).
+ * Throws with a descriptive message when the first token is denied or not SELECT/WITH.
+ *
+ * BUG-11: allow a leading WITH token for CTEs (WITH ... SELECT ...).
+ * The engine-level readonly connection already blocks any write CTE.
+ * We keep blocking all other non-SELECT first tokens.
+ *
  * @param {string} sql
  */
 function _assertReadonly(sql) {
@@ -142,7 +148,8 @@ function _assertReadonly(sql) {
       `query-surface: statement type '${token}' is not allowed (denylist). Only SELECT is permitted.`
     );
   }
-  if (token !== 'SELECT') {
+  // Allow WITH for CTEs (WITH ... SELECT ...) — engine readonly blocks any write CTE.
+  if (token !== 'SELECT' && token !== 'WITH') {
     throw new Error(
       `query-surface: first token '${token}' is not SELECT. Only SELECT queries are permitted.`
     );
@@ -196,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.
 // ---------------------------------------------------------------------------
@@ -241,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}` };
 }
 
 // ---------------------------------------------------------------------------
@@ -276,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) {
@@ -305,10 +355,13 @@ function demigrate(opts = {}) {
  *   3. Invoke migrate-to-sqlite with force:true to rebuild from markdown.
  *   4. Run integrity_check on the new database.
  *
+ * BUG-03/08: recover() is now async — it awaits migrateToSqlite() so that
+ * state.sqlite actually exists before the integrity check is run.
+ *
  * @param {{ projectRoot?: string, dbPath?: string }} [opts]
- * @returns {{ recovered: boolean, message: string, integrity?: boolean }}
+ * @returns {Promise<{ recovered: boolean, message: string, integrity?: boolean }>}
  */
-function recover(opts = {}) {
+async function recover(opts = {}) {
   const backend = _requireBackend();
   if (!backend || backend.BACKEND !== 'sqlite') {
     return {
@@ -321,10 +374,23 @@ 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}` };
     }
@@ -335,7 +401,7 @@ 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.',
     };
   }
@@ -343,13 +409,16 @@ function recover(opts = {}) {
   let migrateResult = null;
   try {
     if (typeof migrate.migrateToSqlite === 'function') {
-      migrateResult = migrate.migrateToSqlite({
+      // BUG-03/08: await the async migrateToSqlite so state.sqlite is written before
+      // the integrity check below. Without await, recover() returned before the DB
+      // existed, causing integrity:false on every call.
+      migrateResult = await migrate.migrateToSqlite({
         projectRoot: opts.projectRoot,
         dbPath,
         force: true,
       });
     } else if (typeof migrate.migrate === 'function') {
-      migrateResult = migrate.migrate({ projectRoot: opts.projectRoot, dbPath, force: true });
+      migrateResult = await migrate.migrate({ projectRoot: opts.projectRoot, dbPath, force: true });
     } else {
       return { recovered: false, message: 'recover: migrate-to-sqlite.cjs has no recognized export.' };
     }
@@ -387,5 +456,6 @@ module.exports = {
   // Expose internals for testing.
   _assertReadonly,
   _firstToken,
+  _safeBackup,
   DENIED_TOKENS,
 };

package/scripts/lib/state/render-markdown.cjs

@@ -376,21 +376,33 @@ function renderStateMarkdown(db, cycle_id, sdk) {
   }
 
   // --- blockers raw_body ---
-  // Only unresolved blockers go in the STATE.md <blockers> block.
+  // activeBlockers is used both for raw_bodies reconstruction and the blockers state array below.
   const activeBlockers = blockerRows.filter((r) => !r.resolved_at);
-  if (activeBlockers.length > 0) {
-    const lines = activeBlockers.map((row) => {
-      // ALWAYS prefer raw_line for blockers (date-format hazard).
-      if (row.raw_line) return row.raw_line;
-      return canonicalBlocker({ stage: row.stage || '', date: row.date || '', text: row.body_md || '' });
-    });
-    raw_bodies.blockers = lines.join('\n');
-  } else if ('blockers' in blockGaps) {
-    raw_bodies.blockers = blockRawBodies['blockers'] !== undefined
-      ? blockRawBodies['blockers']
-      : '';
-  } else if (blockRawBodies['blockers'] !== undefined) {
-    raw_bodies.blockers = blockRawBodies['blockers'];
+
+  // BUG-09: when _block_meta stores a non-null raw_body for 'blockers', emit it
+  // verbatim (like unstructured blocks). This preserves comment lines inside
+  // <blockers> that would otherwise be silently dropped when rebuilding from rows.
+  //
+  // Fall through to row-reconstruction only when raw_body is absent (null), which
+  // happens after an appendBlocker() call that doesn't update _block_meta.raw_body.
+  const blockersRawBody = blockRawBodies['blockers'];
+  if (blockersRawBody !== undefined && blockersRawBody !== null) {
+    // Verbatim round-trip: emit stored raw_body (preserves comments).
+    raw_bodies.blockers = blockersRawBody;
+  } else {
+    // Reconstruct from rows (no stored raw_body).
+    // Only unresolved blockers go in the STATE.md <blockers> block.
+    if (activeBlockers.length > 0) {
+      const lines = activeBlockers.map((row) => {
+        // ALWAYS prefer raw_line for blockers (date-format hazard).
+        if (row.raw_line) return row.raw_line;
+        return canonicalBlocker({ stage: row.stage || '', date: row.date || '', text: row.body_md || '' });
+      });
+      raw_bodies.blockers = lines.join('\n');
+    } else if ('blockers' in blockGaps) {
+      raw_bodies.blockers = '';
+    }
+    // If no blockGaps entry for blockers, raw_bodies.blockers stays null (block omitted).
   }
 
   // --- unstructured blocks: verbatim from _block_meta.raw_body ---

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()
@@ -56,7 +56,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;
@@ -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() {
@@ -198,12 +198,12 @@ function _onDiskSha(statePath) {
  * If they differ, the user has hand-edited STATE.md since the last SQLite write.
  * In that case, run a mini-migration (upsert SQLite from markdown) before proceeding.
  *
- * This is called BEFORE the db.transaction() so it can be async.
+ * This is ASYNC - must be awaited before entering the db.transaction().
  *
  * @param {import('better-sqlite3').Database} db
  * @param {string} statePath absolute path to STATE.md
  */
-function _applyFreshnessGuard(db, statePath) {
+async function _applyFreshnessGuard(db, statePath) {
   try {
     const onDisk = _onDiskSha(statePath);
     if (onDisk === null) return; // STATE.md doesn't exist yet - skip
@@ -211,20 +211,21 @@ function _applyFreshnessGuard(db, statePath) {
     const stored = metaRow ? metaRow.value : null;
     if (stored === onDisk) return; // No drift - proceed normally
     // Drift detected: user hand-edited STATE.md.
-    // Run mini-migration to upsert SQLite from the current markdown state.
+    // Run mini-migration (upsertOnly) to fold the hand-edit into SQLite before
+    // proceeding with the intended mutation.
     const migrate = _requireMigrate();
     if (migrate && typeof migrate.migrateToSqlite === 'function') {
       try {
-        // migrateToSqlite is async but we handle it best-effort here.
-        // For the freshness guard we do a best-effort synchronous approach:
-        // if the module is loaded, call it. If it's async we can't await here
-        // (this is called outside the transaction but may be called from sync context).
-        // The mini-migration is best-effort.
+        // Close db first if needed - migrateToSqlite opens its own connection.
+        // We pass the resolved projectRoot (dirname of .design/STATE.md's parent).
+        const projectRoot = path.resolve(path.dirname(statePath), '..');
+        await migrate.migrateToSqlite({ statePath, projectRoot, force: true, upsertOnly: true });
       } catch {
         // Migration failed - log and continue rather than blocking the write.
+        // Still update the sha to prevent infinite re-triggering.
       }
     }
-    // Update stored sha to prevent re-triggering on every call even if migrate fails.
+    // Update stored sha to reflect the current on-disk content.
     db.prepare('INSERT OR REPLACE INTO _meta(key, value) VALUES (?, ?)').run('last_render_sha256', onDisk);
   } catch {
     /* Freshness guard must never break a write path */
@@ -279,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();
 }
@@ -326,8 +327,12 @@ async function appendDecision(decision, opts = {}) {
   const statePath = _statePath(opts.projectRoot);
   const db = openStateDb(dbPath);
   try {
-    _applyFreshnessGuard(db, statePath);
+    await _applyFreshnessGuard(db, statePath);
     const cycleId = decision.cycleId || _currentCycleId(db);
+    // BUG-10: if no cycle is active, skip rather than inserting cycle_id=null (NOT NULL throw).
+    if (!cycleId) {
+      return { backend: 'sqlite', skipped: true, reason: 'no active cycle_id - call setPosition first' };
+    }
     _dualWrite(db, statePath, cycleId, () => {
       db.prepare(`
         INSERT INTO decisions
@@ -349,6 +354,17 @@ async function appendDecision(decision, opts = {}) {
         decision.rawLine || null,
         decision.createdAt || new Date().toISOString(),
       );
+      // BUG-05: populate decisions_fts so FTS5 queries return 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(decision.id);
+        db.prepare(`INSERT INTO decisions_fts (id, body_md, tags) VALUES (?, ?, ?)`).run(
+          decision.id,
+          decision.bodyMd || '',
+          decision.tags ? JSON.stringify(decision.tags) : null,
+        );
+      } catch { /* FTS5 table absent in no-fts5 build - skip */ }
     }, sdk);
     return { backend: 'sqlite', id: decision.id };
   } finally {
@@ -373,16 +389,21 @@ function getDecisions(opts = {}) {
   if (BACKEND !== 'sqlite') {
     return [];
   }
-  const dbPath = _resolveDbPath(opts);
-  const db = openStateDb(dbPath, { readonly: true });
+  // BUG-06: wrap in try/catch — openStateDb(readonly) throws on a missing file.
   try {
-    const cycleId = opts.cycleId || _currentCycleId(db);
-    if (!cycleId) return [];
-    return db.prepare(
-      'SELECT * FROM decisions WHERE cycle_id = ? ORDER BY ordinal ASC'
-    ).all(cycleId);
-  } finally {
-    db.close();
+    const dbPath = _resolveDbPath(opts);
+    const db = openStateDb(dbPath, { readonly: true });
+    try {
+      const cycleId = opts.cycleId || _currentCycleId(db);
+      if (!cycleId) return [];
+      return db.prepare(
+        'SELECT * FROM decisions WHERE cycle_id = ? ORDER BY ordinal ASC'
+      ).all(cycleId);
+    } finally {
+      db.close();
+    }
+  } catch {
+    return [];
   }
 }
 
@@ -408,7 +429,7 @@ async function appendBlocker(blocker, opts = {}) {
   const statePath = _statePath(opts.projectRoot);
   const db = openStateDb(dbPath);
   try {
-    _applyFreshnessGuard(db, statePath);
+    await _applyFreshnessGuard(db, statePath);
     const cycleId = blocker.cycleId || _currentCycleId(db);
     let rowid = null;
     _dualWrite(db, statePath, cycleId, () => {
@@ -447,21 +468,26 @@ function getBlockers(opts = {}) {
   if (BACKEND !== 'sqlite') {
     return [];
   }
-  const dbPath = _resolveDbPath(opts);
-  const db = openStateDb(dbPath, { readonly: true });
+  // BUG-06: wrap in try/catch — openStateDb(readonly) throws on a missing file.
   try {
-    const cycleId = opts.cycleId || _currentCycleId(db);
-    if (!cycleId) return [];
-    if (opts.includeResolved) {
+    const dbPath = _resolveDbPath(opts);
+    const db = openStateDb(dbPath, { readonly: true });
+    try {
+      const cycleId = opts.cycleId || _currentCycleId(db);
+      if (!cycleId) return [];
+      if (opts.includeResolved) {
+        return db.prepare(
+          'SELECT * FROM blockers WHERE cycle_id = ? ORDER BY ordinal ASC'
+        ).all(cycleId);
+      }
       return db.prepare(
-        'SELECT * FROM blockers WHERE cycle_id = ? ORDER BY ordinal ASC'
+        'SELECT * FROM blockers WHERE cycle_id = ? AND resolved_at IS NULL ORDER BY ordinal ASC'
       ).all(cycleId);
+    } finally {
+      db.close();
     }
-    return db.prepare(
-      'SELECT * FROM blockers WHERE cycle_id = ? AND resolved_at IS NULL ORDER BY ordinal ASC'
-    ).all(cycleId);
-  } finally {
-    db.close();
+  } catch {
+    return [];
   }
 }
 
@@ -488,7 +514,7 @@ async function setPosition(position, opts = {}) {
   const statePath = _statePath(opts.projectRoot);
   const db = openStateDb(dbPath);
   try {
-    _applyFreshnessGuard(db, statePath);
+    await _applyFreshnessGuard(db, statePath);
     _dualWrite(db, statePath, position.cycleId, () => {
       db.prepare(`
         INSERT INTO state_position
@@ -535,17 +561,22 @@ function getPosition(opts = {}) {
   if (BACKEND !== 'sqlite') {
     return null;
   }
-  const dbPath = _resolveDbPath(opts);
-  const db = openStateDb(dbPath, { readonly: true });
+  // BUG-06: wrap in try/catch — openStateDb(readonly) throws on a missing file.
   try {
-    if (opts.cycleId) {
-      return db.prepare('SELECT * FROM state_position WHERE cycle_id = ?').get(opts.cycleId) || null;
+    const dbPath = _resolveDbPath(opts);
+    const db = openStateDb(dbPath, { readonly: true });
+    try {
+      if (opts.cycleId) {
+        return db.prepare('SELECT * FROM state_position WHERE cycle_id = ?').get(opts.cycleId) || null;
+      }
+      return db.prepare(
+        'SELECT * FROM state_position ORDER BY updated_at DESC LIMIT 1'
+      ).get() || null;
+    } finally {
+      db.close();
     }
-    return db.prepare(
-      'SELECT * FROM state_position ORDER BY updated_at DESC LIMIT 1'
-    ).get() || null;
-  } finally {
-    db.close();
+  } catch {
+    return null;
   }
 }
 
@@ -623,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.
+ *
+ * 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.
  *
- * @param {{ statePath?: string, dbPath?: string, projectRoot?: string,
- *           dryRun?: boolean, upsertOnly?: boolean }} [migrateOpts]
- * @returns {{ migrated: boolean, backend: string, message?: string }}
+ * @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,
@@ -648,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,
@@ -668,13 +741,13 @@ function migrate(migrateOpts = {}) {
 }
 
 // ---------------------------------------------------------------------------
-// render - lazy delegate to render-markdown.cjs (Executor C).
+// render - lazy delegate to render-markdown.cjs.
 // ---------------------------------------------------------------------------
 
 /**
  * Re-render STATE.md from SQLite state (reverse of migration).
- * Delegates to ./render-markdown.cjs (created by Executor C).
- * If that module is not yet present, logs a clear message and returns null.
+ * Delegates to ./render-markdown.cjs.
+ * If that module cannot be loaded, returns null silently.
  *
  * @param {string} [projectRoot]
  * @returns {Promise<string|null>} rendered markdown string, or null if unavailable

package/sdk/cli/commands/stage.ts

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