@hegemonart/get-design-done 1.59.6 → 1.59.8

package/sdk/mcp/gdd-mcp/server.js

@@ -2034,7 +2034,7 @@ __export(server_exports, {
 });
 module.exports = __toCommonJS(server_exports);
 var import_node_fs5 = require("node:fs");
-var import_node_path4 = require("node:path");
+var import_node_path5 = require("node:path");
 var import_server = require("@modelcontextprotocol/sdk/server/index.js");
 var import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
 var import_types6 = require("@modelcontextprotocol/sdk/types.js");
@@ -2199,6 +2199,11 @@ function resolveProjectRoot(startCwd = process.cwd()) {
     if ((0, import_node_fs.existsSync)((0, import_node_path.join)(dir, ".design")) || (0, import_node_fs.existsSync)((0, import_node_path.join)(dir, ".planning")) || (0, import_node_fs.existsSync)((0, import_node_path.join)(dir, ".claude-plugin", "plugin.json"))) {
       return dir;
     }
+    if ((0, import_node_fs.existsSync)((0, import_node_path.join)(dir, ".git"))) {
+      throw new Error(
+        `gdd project root not found: hit repo boundary at ${dir} (.git) before any GDD marker, starting from ${startCwd}`
+      );
+    }
     const parent = (0, import_node_path.dirname)(dir);
     if (parent === dir) {
       throw new Error(
@@ -2249,6 +2254,8 @@ __export(gdd_cycle_recap_exports, {
 
 // sdk/state/index.ts
 var import_node_fs2 = require("node:fs");
+var import_node_path2 = require("node:path");
+var import_node_module = require("node:module");
 
 // sdk/state/types.ts
 function isConnectionStatus(value) {
@@ -2950,6 +2957,8 @@ var GATES = Object.freeze({
 });
 
 // sdk/state/index.ts
+var _moduleDir = typeof __dirname !== "undefined" ? __dirname : (0, import_node_path2.dirname)(process.argv[1] || process.cwd());
+var _require = typeof require !== "undefined" ? require : (0, import_node_module.createRequire)(process.argv[1] || process.cwd());
 async function read(path) {
   const raw = (0, import_node_fs2.readFileSync)(path, "utf8");
   return parse(raw).state;
@@ -3017,51 +3026,55 @@ __export(gdd_events_tail_exports, {
 
 // sdk/event-stream/writer.ts
 var import_node_fs3 = require("node:fs");
-var import_node_path2 = require("node:path");
-var import_node_module = require("node:module");
+var import_node_path3 = require("node:path");
+var import_node_module2 = require("node:module");
 function _findRepoRoot() {
-  let dir = process.cwd();
-  for (let i = 0; i < 8; i++) {
-    if ((0, import_node_fs3.existsSync)((0, import_node_path2.join)(dir, "package.json"))) return dir;
-    const parent = (0, import_node_path2.dirname)(dir);
+  return _walkToPackageJson(process.cwd());
+}
+function _walkToPackageJson(startDir) {
+  let dir = startDir;
+  for (let i = 0; i < 12; i++) {
+    if ((0, import_node_fs3.existsSync)((0, import_node_path3.join)(dir, "package.json"))) return dir;
+    const parent = (0, import_node_path3.dirname)(dir);
     if (parent === dir) break;
     dir = parent;
   }
-  return process.cwd();
+  return startDir;
 }
-var _redact;
-try {
-  const _root = _findRepoRoot();
-  const _candidate = (0, import_node_path2.resolve)(_root, "scripts/lib/redact.cjs");
-  if ((0, import_node_fs3.existsSync)(_candidate)) {
-    const _redactRequire = (0, import_node_module.createRequire)((0, import_node_path2.join)(_root, "package.json"));
-    const _mod = _redactRequire(_candidate);
-    _redact = _mod.redact;
-  } else {
-    const _altRoot = (0, import_node_path2.resolve)(_root, "..", "..");
-    const _altCandidate = (0, import_node_path2.resolve)(_altRoot, "scripts/lib/redact.cjs");
-    if ((0, import_node_fs3.existsSync)(_altCandidate)) {
-      const _altRequire = (0, import_node_module.createRequire)((0, import_node_path2.join)(_altRoot, "package.json"));
-      const _altMod = _altRequire(_altCandidate);
-      _redact = _altMod.redact;
-    } else {
-      _redact = (v) => v;
+function _loadRedact() {
+  const candidates = [];
+  const entry = process.argv[1];
+  if (typeof entry === "string" && entry.length > 0) {
+    const entryAbs = (0, import_node_path3.isAbsolute)(entry) ? entry : (0, import_node_path3.resolve)(entry);
+    const entryRoot = _walkToPackageJson((0, import_node_path3.dirname)(entryAbs));
+    candidates.push((0, import_node_path3.resolve)(entryRoot, "scripts/lib/redact.cjs"));
+  }
+  const repoRoot = _findRepoRoot();
+  candidates.push((0, import_node_path3.resolve)(repoRoot, "scripts/lib/redact.cjs"));
+  candidates.push((0, import_node_path3.resolve)(repoRoot, "..", "..", "scripts/lib/redact.cjs"));
+  for (const candidate of candidates) {
+    try {
+      if (!(0, import_node_fs3.existsSync)(candidate)) continue;
+      const req = (0, import_node_module2.createRequire)(candidate);
+      const mod = req(candidate);
+      if (mod && typeof mod.redact === "function") return mod.redact;
+    } catch {
     }
   }
-} catch {
-  _redact = (v) => v;
+  return null;
 }
+var _realRedact = _loadRedact();
 var DEFAULT_EVENTS_PATH = ".design/telemetry/events.jsonl";
 var DEFAULT_MAX_LINE_BYTES = 64 * 1024;
 
 // sdk/event-stream/reader.ts
 var import_node_fs4 = require("node:fs");
-var import_node_path3 = require("node:path");
+var import_node_path4 = require("node:path");
 var import_node_readline = require("node:readline");
 function resolveReadPath(opts) {
   const raw = opts.path ?? DEFAULT_EVENTS_PATH;
-  if ((0, import_node_path3.isAbsolute)(raw)) return raw;
-  return (0, import_node_path3.resolve)(opts.baseDir ?? process.cwd(), raw);
+  if ((0, import_node_path4.isAbsolute)(raw)) return raw;
+  return (0, import_node_path4.resolve)(opts.baseDir ?? process.cwd(), raw);
 }
 async function* readEvents(opts = {}) {
   const path = resolveReadPath(opts);
@@ -3354,16 +3367,16 @@ if (TOOL_COUNT > 13) {
 var SERVER_NAME = "gdd-mcp";
 var SERVER_VERSION = "1.27.7";
 function here() {
-  const expectedRel = (0, import_node_path4.join)("sdk", "mcp", "gdd-mcp");
+  const expectedRel = (0, import_node_path5.join)("sdk", "mcp", "gdd-mcp");
   const entry = process.argv[1];
   if (typeof entry === "string" && entry.length > 0) {
-    const entryDir = (0, import_node_path4.dirname)((0, import_node_path4.resolve)(entry));
-    if ((0, import_node_fs5.existsSync)((0, import_node_path4.join)(entryDir, "tools", "index.ts"))) {
+    const entryDir = (0, import_node_path5.dirname)((0, import_node_path5.resolve)(entry));
+    if ((0, import_node_fs5.existsSync)((0, import_node_path5.join)(entryDir, "tools", "index.ts"))) {
       return entryDir;
     }
   }
-  const candidate = (0, import_node_path4.resolve)(process.cwd(), expectedRel);
-  if ((0, import_node_fs5.existsSync)((0, import_node_path4.join)(candidate, "tools", "index.ts"))) {
+  const candidate = (0, import_node_path5.resolve)(process.cwd(), expectedRel);
+  if ((0, import_node_fs5.existsSync)((0, import_node_path5.join)(candidate, "tools", "index.ts"))) {
     return candidate;
   }
   return candidate;
@@ -3371,7 +3384,7 @@ function here() {
 function loadTools() {
   const baseDir = here();
   return TOOL_MODULES.map((m) => {
-    const absPath = (0, import_node_path4.join)(baseDir, "tools", m.schemaPath);
+    const absPath = (0, import_node_path5.join)(baseDir, "tools", m.schemaPath);
     const raw = (0, import_node_fs5.readFileSync)(absPath, "utf8");
     const parsed = JSON.parse(raw);
     const rawInput = parsed.properties?.input;

package/sdk/mcp/gdd-mcp/tools/shared.ts

@@ -103,9 +103,18 @@ export function resolveSnapshotsDir(): string {
  * is returned verbatim (after path resolution). This is useful for
  * tests and for users who want to pin a project root explicitly.
  *
+ * REPO-BOUNDARY GUARD (audit S8): the upward walk STOPS at the first `.git`
+ * directory it encounters. If a `.git` boundary is hit BEFORE any GDD marker
+ * is found, the walk does NOT continue into the parent repository — that
+ * would let a nested, unrelated checkout resolve to a PARENT repo's
+ * `.design/`/`.planning/`, leaking another project's state into this one
+ * (cross-project info bleed). At a `.git` boundary we check the boundary
+ * directory itself for a marker (a repo root legitimately holds `.design/`),
+ * then treat "no marker at or below this repo root" as not-found.
+ *
  * Throws `Error('gdd project root not found: ...')` when no marker is
- * found before the filesystem root. Callers in tool handlers should
- * catch and forward via `errorResponse()`.
+ * found before either the first `.git` boundary or the filesystem root.
+ * Callers in tool handlers should catch and forward via `errorResponse()`.
  */
 export function resolveProjectRoot(startCwd: string = process.cwd()): string {
   const override = process.env['GDD_PROJECT_ROOT'];
@@ -122,6 +131,15 @@ export function resolveProjectRoot(startCwd: string = process.cwd()): string {
     ) {
       return dir;
     }
+    // S8: a `.git` here marks a repository boundary. We already checked this
+    // directory for a marker above and found none, so do not walk PAST the
+    // repo root into a parent (possibly unrelated) project.
+    if (existsSync(join(dir, '.git'))) {
+      throw new Error(
+        `gdd project root not found: hit repo boundary at ${dir} ` +
+          `(.git) before any GDD marker, starting from ${startCwd}`,
+      );
+    }
     const parent = dirname(dir);
     if (parent === dir) {
       // Reached filesystem root — give up.

package/sdk/mcp/gdd-state/server.js

@@ -197,6 +197,7 @@ __export(get_exports, {
 // sdk/state/index.ts
 var import_node_fs2 = require("node:fs");
 var import_node_path = require("node:path");
+var import_node_module = require("node:module");
 
 // sdk/state/lockfile.ts
 var import_node_fs = require("node:fs");
@@ -263,6 +264,14 @@ async function acquire(path2, opts = {}) {
       }
       const parsed = parseLock(existing);
       if (parsed !== null && isStale(parsed, staleMs)) {
+        const confirm = readLockSafe(lockPath);
+        if (confirm === null) {
+          continue;
+        }
+        if (confirm !== existing) {
+          await sleep(pollMs);
+          continue;
+        }
         try {
           (0, import_node_fs.unlinkSync)(lockPath);
         } catch (delErr) {
@@ -321,10 +330,14 @@ function parseLock(raw) {
   }
 }
 function isStale(payload, staleMs) {
-  if (!isPidAlive(payload.pid, payload.host)) return true;
-  const acquiredAt = Date.parse(payload.acquired_at);
-  if (!Number.isFinite(acquiredAt)) return true;
-  return Date.now() - acquiredAt > staleMs;
+  const pidRecorded = typeof payload.pid === "number" && Number.isInteger(payload.pid) && payload.pid > 0;
+  if (!pidRecorded) {
+    const acquiredAt = Date.parse(payload.acquired_at);
+    if (!Number.isFinite(acquiredAt)) return true;
+    return Date.now() - acquiredAt > staleMs;
+  }
+  if (isPidAlive(payload.pid, payload.host)) return false;
+  return true;
 }
 function isPidAlive(pid, host) {
   if (host !== (0, import_node_os.hostname)()) {
@@ -1731,6 +1744,8 @@ function gateFor(from, to) {
 }
 
 // sdk/state/index.ts
+var _moduleDir = typeof __dirname !== "undefined" ? __dirname : (0, import_node_path.dirname)(process.argv[1] || process.cwd());
+var _require = typeof require !== "undefined" ? require : (0, import_node_module.createRequire)(process.argv[1] || process.cwd());
 function _findPackageRoot(startDir) {
   let dir = (0, import_node_path.resolve)(startDir);
   let firstWithPkg = null;
@@ -1738,7 +1753,7 @@ function _findPackageRoot(startDir) {
     const pkgPath = (0, import_node_path.join)(dir, "package.json");
     if ((0, import_node_fs2.existsSync)(pkgPath)) {
       try {
-        const pkg = require(pkgPath);
+        const pkg = _require(pkgPath);
         if (firstWithPkg === null) firstWithPkg = dir;
         if (pkg.name === "@hegemonart/get-design-done") return dir;
       } catch {
@@ -1755,7 +1770,7 @@ var _backendCache = null;
 function _loadBackend() {
   if (_backendCache !== null) return _backendCache === false ? null : _backendCache;
   try {
-    const pkgRoot = _findPackageRoot(__dirname);
+    const pkgRoot = _findPackageRoot(_moduleDir);
     if (pkgRoot === null) {
       _backendCache = false;
       return null;
@@ -1765,7 +1780,7 @@ function _loadBackend() {
       _backendCache = false;
       return null;
     }
-    _backendCache = require(backendPath);
+    _backendCache = _require(backendPath);
     return _backendCache;
   } catch {
     _backendCache = false;
@@ -1890,20 +1905,47 @@ async function transition(path2, toStage) {
     throw new TransitionGateFailed(toStage, gateResult.blockers);
   }
   const nowIso = (/* @__PURE__ */ new Date()).toISOString();
-  const nextState = await mutate(path2, (s) => {
-    s.frontmatter.stage = toStage;
-    s.frontmatter.last_checkpoint = nowIso;
-    s.position.stage = toStage;
-    s.timestamps[`${toStage}_started_at`] = nowIso;
-    return s;
-  });
-  return { pass: true, blockers: gateResult.blockers, state: nextState };
+  let lockedFailure = null;
+  let lockedBlockers = gateResult.blockers;
+  try {
+    const nextState = await mutate(path2, (s) => {
+      const fromNow = s.position.stage;
+      if (!isStage(fromNow)) {
+        lockedFailure = new TransitionGateFailed(toStage, [
+          `Invalid transition: from="${fromNow}" is not a recognized Stage (changed under lock)`
+        ]);
+        throw lockedFailure;
+      }
+      const gateNow = gateFor(fromNow, toStage);
+      if (gateNow === null) {
+        lockedFailure = new TransitionGateFailed(toStage, [
+          `Invalid transition: ${fromNow} \u2192 ${toStage} (changed under lock)`
+        ]);
+        throw lockedFailure;
+      }
+      const resultNow = gateNow(s);
+      if (!resultNow.pass) {
+        lockedFailure = new TransitionGateFailed(toStage, resultNow.blockers);
+        throw lockedFailure;
+      }
+      lockedBlockers = resultNow.blockers;
+      s.frontmatter.stage = toStage;
+      s.frontmatter.last_checkpoint = nowIso;
+      s.position.stage = toStage;
+      s.timestamps[`${toStage}_started_at`] = nowIso;
+      return s;
+    });
+    return { pass: true, blockers: lockedBlockers, state: nextState };
+  } catch (err) {
+    if (lockedFailure !== null && err === lockedFailure) throw lockedFailure;
+    throw err;
+  }
 }
 
 // sdk/mcp/gdd-state/tools/shared.ts
 var import_node_path3 = __toESM(require("node:path"));
 var import_node_fs4 = require("node:fs");
-var import_node_module2 = require("node:module");
+var import_node_module3 = require("node:module");
 
 // sdk/event-stream/index.ts
 var import_node_os2 = require("node:os");
@@ -1952,40 +1994,64 @@ var EventBus = class extends import_node_events.EventEmitter {
 // sdk/event-stream/writer.ts
 var import_node_fs3 = require("node:fs");
 var import_node_path2 = require("node:path");
-var import_node_module = require("node:module");
+var import_node_module2 = require("node:module");
 function _findRepoRoot() {
-  let dir = process.cwd();
-  for (let i = 0; i < 8; i++) {
+  return _walkToPackageJson(process.cwd());
+}
+function _walkToPackageJson(startDir) {
+  let dir = startDir;
+  for (let i = 0; i < 12; i++) {
     if ((0, import_node_fs3.existsSync)((0, import_node_path2.join)(dir, "package.json"))) return dir;
     const parent = (0, import_node_path2.dirname)(dir);
     if (parent === dir) break;
     dir = parent;
   }
-  return process.cwd();
+  return startDir;
 }
-var _redact;
-try {
-  const _root = _findRepoRoot();
-  const _candidate = (0, import_node_path2.resolve)(_root, "scripts/lib/redact.cjs");
-  if ((0, import_node_fs3.existsSync)(_candidate)) {
-    const _redactRequire = (0, import_node_module.createRequire)((0, import_node_path2.join)(_root, "package.json"));
-    const _mod = _redactRequire(_candidate);
-    _redact = _mod.redact;
-  } else {
-    const _altRoot = (0, import_node_path2.resolve)(_root, "..", "..");
-    const _altCandidate = (0, import_node_path2.resolve)(_altRoot, "scripts/lib/redact.cjs");
-    if ((0, import_node_fs3.existsSync)(_altCandidate)) {
-      const _altRequire = (0, import_node_module.createRequire)((0, import_node_path2.join)(_altRoot, "package.json"));
-      const _altMod = _altRequire(_altCandidate);
-      _redact = _altMod.redact;
-    } else {
-      _redact = (v) => v;
+var _redactWarned = false;
+function _warnRedactUnavailable() {
+  if (_redactWarned) return;
+  _redactWarned = true;
+  try {
+    process.stderr.write(
+      "[event-stream] WARNING: scripts/lib/redact.cjs could not be loaded \u2014 failing CLOSED: event payloads are dropped (envelope-only) to avoid writing unscrubbed secrets. Run the event writer from inside the plugin tree or set the redact lib on PATH to restore full payloads.\n"
+    );
+  } catch {
+  }
+}
+function _loadRedact() {
+  const candidates = [];
+  const entry = process.argv[1];
+  if (typeof entry === "string" && entry.length > 0) {
+    const entryAbs = (0, import_node_path2.isAbsolute)(entry) ? entry : (0, import_node_path2.resolve)(entry);
+    const entryRoot = _walkToPackageJson((0, import_node_path2.dirname)(entryAbs));
+    candidates.push((0, import_node_path2.resolve)(entryRoot, "scripts/lib/redact.cjs"));
+  }
+  const repoRoot = _findRepoRoot();
+  candidates.push((0, import_node_path2.resolve)(repoRoot, "scripts/lib/redact.cjs"));
+  candidates.push((0, import_node_path2.resolve)(repoRoot, "..", "..", "scripts/lib/redact.cjs"));
+  for (const candidate of candidates) {
+    try {
+      if (!(0, import_node_fs3.existsSync)(candidate)) continue;
+      const req = (0, import_node_module2.createRequire)(candidate);
+      const mod = req(candidate);
+      if (mod && typeof mod.redact === "function") return mod.redact;
+    } catch {
     }
   }
-} catch {
-  _redact = (v) => v;
+  return null;
 }
-var redact = _redact;
+var _realRedact = _loadRedact();
+var redact = _realRedact !== null ? _realRedact : (v) => {
+  _warnRedactUnavailable();
+  if (v !== null && typeof v === "object") {
+    const ev = v;
+    const out = { ...ev };
+    out["payload"] = { _redaction_unavailable: true };
+    return out;
+  }
+  return { _redaction_unavailable: true };
+};
 var DEFAULT_EVENTS_PATH = ".design/telemetry/events.jsonl";
 var DEFAULT_MAX_LINE_BYTES = 64 * 1024;
 var EventWriter = class {
@@ -2132,7 +2198,7 @@ var _worktree = (() => {
     const root = _findRepoRoot2();
     const candidate = import_node_path3.default.resolve(root, "scripts/lib/worktree-resolve.cjs");
     if (!(0, import_node_fs4.existsSync)(candidate)) return null;
-    const req = (0, import_node_module2.createRequire)(import_node_path3.default.join(root, "package.json"));
+    const req = (0, import_node_module3.createRequire)(import_node_path3.default.join(root, "package.json"));
     return req(candidate);
   } catch {
     return null;

package/sdk/primitives/lockfile.cjs

@@ -82,8 +82,16 @@ async function acquire(path, opts) {
       // reads (EACCES/EPERM/EBUSY), and clearing under that condition
       // would let two writers race and lose increments.
       if (parsed !== null && isStale(parsed, staleMs)) {
+        // Audit D3 (TOCTOU): confirm the on-disk bytes STILL match the exact
+        // stale payload we just read before unlinking. If a different writer
+        // replaced the lock in the read→unlink window, do NOT unlink (that
+        // would steal a fresh lock); loop and re-evaluate the new holder.
+        const confirm = readLockSafe(lockPath);
+        if (confirm === null) continue; // already gone — race for wx-create
+        if (confirm !== existing) { await sleep(pollMs); continue; }
         // Clear stale lock; race-tolerant — if it's already gone we get
-        // ENOENT, no-op.
+        // ENOENT, no-op. The wx-create below is atomic (O_CREAT|O_EXCL), so
+        // even if two waiters both unlink, only one wins the recreate.
         try { fs.unlinkSync(lockPath); } catch { /* ignore */ }
         continue;
       }
@@ -155,10 +163,23 @@ function parseLock(raw) {
 }
 
 function isStale(payload, staleMs) {
-  if (!isPidAlive(payload.pid, payload.host)) return true;
-  const t = Date.parse(payload.acquired_at);
-  if (!Number.isFinite(t)) return true;
-  return Date.now() - t > staleMs;
+  // Audit D3: PID-liveness is AUTHORITATIVE. A lock whose holder PID is still
+  // alive on this host is NEVER stale, regardless of age — a legitimate
+  // long-running mutation must not have its lock stolen. The age-based
+  // fallback applies ONLY when liveness cannot be confirmed: a dead PID, or a
+  // missing/invalid pid field. (isPidAlive conservatively reports alive for
+  // cross-host and unsignalable holders, so those are also never aged out.)
+  const pidRecorded =
+    typeof payload.pid === 'number' &&
+    Number.isInteger(payload.pid) &&
+    payload.pid > 0;
+  if (!pidRecorded) {
+    const t = Date.parse(payload.acquired_at);
+    if (!Number.isFinite(t)) return true;
+    return Date.now() - t > staleMs;
+  }
+  if (isPidAlive(payload.pid, payload.host)) return false;
+  return true;
 }
 
 function isPidAlive(pid, host) {

package/sdk/state/index.ts

@@ -37,6 +37,33 @@ import {
 } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { createRequire } from 'node:module';
+
+// Audit D1: this .ts compiles to CommonJS via tsc (Node16 module mode), where
+// `import.meta` is FORBIDDEN (error TS1470). But under Node's
+// --experimental-strip-types the same file runs as ESM, where the CommonJS
+// globals `require` and `__dirname` are UNDEFINED -- a bare reference to either
+// THROWS a ReferenceError, so we cannot name them directly. We satisfy BOTH
+// targets by probing with `typeof` (safe in ESM) and falling back to the entry
+// script (`process.argv[1]`) when the CJS globals are absent. This mirrors the
+// process.argv[1] anchoring used by sibling `sdk/event-stream/writer.ts` and
+// avoids `import.meta` entirely.
+//   * `_require` -- a CJS-style require, used to load the optional .cjs backend
+//     (state-backend.cjs) and package.json files. In compiled CJS output the
+//     real `require` is used; under strip-types ESM we synthesize one anchored
+//     on the entry script via createRequire.
+//   * `_moduleDir` -- the walk-up anchor formerly spelled `__dirname`. In
+//     compiled CJS `__dirname` is used; under ESM we derive a directory from
+//     the entry script. Either way `_loadBackend` can resolve the optional
+//     native backend in BOTH compiled and source modes.
+const _moduleDir: string =
+  typeof __dirname !== 'undefined'
+    ? __dirname
+    : dirname(process.argv[1] || process.cwd());
+const _require =
+  typeof require !== 'undefined'
+    ? require
+    : createRequire(process.argv[1] || process.cwd());
 
 import { acquire, acquireSqliteLock } from './lockfile.ts';
 import { parse } from './parser.ts';
@@ -69,8 +96,8 @@ function _findPackageRoot(startDir: string): string | null {
     const pkgPath = join(dir, 'package.json');
     if (existsSync(pkgPath)) {
       try {
-        // eslint-disable-next-line @typescript-eslint/no-require-imports
-        const pkg = require(pkgPath) as { name?: string };
+        // D1: createRequire-bound require (bare `require` is undefined in ESM).
+        const pkg = _require(pkgPath) as { name?: string };
         if (firstWithPkg === null) firstWithPkg = dir;
         if (pkg.name === '@hegemonart/get-design-done') return dir;
       } catch {
@@ -85,9 +112,16 @@ function _findPackageRoot(startDir: string): string | null {
 }
 
 // ---------------------------------------------------------------------------
-// Phase 57: backend probe (loaded once via require, memoized).
-// state-backend.cjs is a CommonJS module; require() works from .ts under
-// Node 22 --experimental-strip-types (only type-erasable syntax is used).
+// Phase 57: backend probe (loaded once via createRequire, memoized).
+// state-backend.cjs is a CommonJS module. Audit D1 correction: a BARE
+// `require()` does NOT work from this .ts under Node's --experimental-strip-
+// types — this module is loaded as ESM, where `require` is undefined and a
+// bare call throws ReferenceError (silently caught below, killing the backend
+// path). We load via `_require` -- the real CJS `require` in compiled output,
+// or a createRequire anchored on the entry script under strip-types ESM --
+// which DOES resolve the optional .cjs backend in both modes. The graceful-null
+// fallback is preserved for the genuinely-absent
+// dependency (e.g. better-sqlite3 not installed).
 // ---------------------------------------------------------------------------
 
 interface StateBackendMod {
@@ -111,12 +145,13 @@ let _backendCache: StateBackendMod | null | false = null;
 function _loadBackend(): StateBackendMod | null {
   if (_backendCache !== null) return _backendCache === false ? null : _backendCache as StateBackendMod;
   try {
-    const pkgRoot = _findPackageRoot(__dirname);
+    const pkgRoot = _findPackageRoot(_moduleDir);
     if (pkgRoot === null) { _backendCache = false; return null; }
     const backendPath = join(pkgRoot, 'scripts', 'lib', 'state', 'state-backend.cjs');
     if (!existsSync(backendPath)) { _backendCache = false; return null; }
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    _backendCache = require(backendPath) as StateBackendMod;
+    // D1: createRequire-bound require so the optional native backend can
+    // actually load from this ESM (.ts strip-types) context.
+    _backendCache = _require(backendPath) as StateBackendMod;
     return _backendCache as StateBackendMod;
   } catch {
     _backendCache = false;
@@ -144,7 +179,7 @@ let _storeCache: StateStoreMod | null | false = null;
 async function _loadStore(): Promise<StateStoreMod | null> {
   if (_storeCache !== null) return _storeCache === false ? null : _storeCache as StateStoreMod;
   try {
-    const pkgRoot = _findPackageRoot(__dirname);
+    const pkgRoot = _findPackageRoot(_moduleDir);
     if (pkgRoot === null) { _storeCache = false; return null; }
     const storePath = join(pkgRoot, 'scripts', 'lib', 'state', 'state-store.cjs');
     if (!existsSync(storePath)) { _storeCache = false; return null; }
@@ -420,12 +455,51 @@ export async function transition(
     throw new TransitionGateFailed(toStage, gateResult.blockers);
   }
   const nowIso: string = new Date().toISOString();
-  const nextState = await mutate(path, (s): ParsedState => {
-    s.frontmatter.stage = toStage;
-    s.frontmatter.last_checkpoint = nowIso;
-    s.position.stage = toStage;
-    s.timestamps[`${toStage}_started_at`] = nowIso;
-    return s;
-  });
-  return { pass: true, blockers: gateResult.blockers, state: nextState };
+  // Audit D4: the gate above was evaluated against a PRE-LOCK read. A
+  // concurrent stage change between that read and the locked mutate could make
+  // the transition invalid (e.g. another writer already advanced the stage, so
+  // `from` is no longer the current stage, or the gate's preconditions no
+  // longer hold). Re-evaluate the gate INSIDE the locked mutate against the
+  // freshly-read `s`, and abort the transition if it no longer holds. The
+  // mutate() lock serializes us against other writers, so this re-check is
+  // race-free: nothing can change `s` between this check and the write.
+  //
+  // We capture the locked re-check failure and re-throw it OUTSIDE mutate so
+  // the caller sees a TransitionGateFailed rather than a generic mutate error.
+  let lockedFailure: TransitionGateFailed | null = null;
+  let lockedBlockers: string[] = gateResult.blockers;
+  try {
+    const nextState = await mutate(path, (s): ParsedState => {
+      const fromNow: string = s.position.stage;
+      if (!isStage(fromNow)) {
+        lockedFailure = new TransitionGateFailed(toStage, [
+          `Invalid transition: from="${fromNow}" is not a recognized Stage (changed under lock)`,
+        ]);
+        throw lockedFailure;
+      }
+      const gateNow = gateFor(fromNow, toStage);
+      if (gateNow === null) {
+        lockedFailure = new TransitionGateFailed(toStage, [
+          `Invalid transition: ${fromNow} → ${toStage} (changed under lock)`,
+        ]);
+        throw lockedFailure;
+      }
+      const resultNow = gateNow(s);
+      if (!resultNow.pass) {
+        lockedFailure = new TransitionGateFailed(toStage, resultNow.blockers);
+        throw lockedFailure;
+      }
+      lockedBlockers = resultNow.blockers;
+      s.frontmatter.stage = toStage;
+      s.frontmatter.last_checkpoint = nowIso;
+      s.position.stage = toStage;
+      s.timestamps[`${toStage}_started_at`] = nowIso;
+      return s;
+    });
+    return { pass: true, blockers: lockedBlockers, state: nextState };
+  } catch (err) {
+    // If the in-lock re-check vetoed, surface the gate failure verbatim.
+    if (lockedFailure !== null && err === lockedFailure) throw lockedFailure;
+    throw err;
+  }
 }