@hegemonart/get-design-done 1.31.0 → 1.31.5

package/scripts/lib/jittered-backoff.cjs

@@ -1,112 +1,29 @@
-// scripts/lib/jittered-backoff.cjs
-//
-// Plan 20-14 — jittered exponential backoff primitive.
-//
-// Replaces fixed-interval retry sleeps across the codebase (update-check,
-// watch-authorities, figma probes, connection probes, hook retry loops) with
-// a deterministic, capped, jittered backoff curve.
-//
-// Formula:
-//   base = min(maxMs, baseMs * factor^attempt)
-//   delay = base * (1 + rand(-jitter, +jitter))
-//   clamp to [0, maxMs * (1 + jitter)]
-//
-// The zero-based `attempt` counter gives `baseMs` on the first call, then
-// multiplies by `factor` per attempt up to the cap. Jitter is full-width
-// symmetric (not AWS-style equal/decorrelated) because our consumers are
-// single-threaded retry loops — there's no thundering-herd problem to
-// smooth; the jitter is cosmetic protection against synchronized retries
-// between siblings like the watcher + update-check running at the same
-// session boundary.
+'use strict';
+// scripts/lib/jittered-backoff.cjs — GDD-DEPRECATION-SHIM (Plan 31-5-06, SDK-05, D-02).
 //
-// Defaults (baseMs=100, maxMs=30_000, factor=2, jitter=0.2) yield:
-//   attempt 0 → 80-120ms
-//   attempt 1 → 160-240ms
-//   attempt 2 → 320-480ms
-//   ...
-//   attempt 9 → ~24s-30s (capped)
+// Thin deprecation shim. The real implementation moved to
+// sdk/primitives/jittered-backoff.cjs in Plan 31-5-04 (SDK consolidation).
+// This file is re-created at the OLD path so undocumented EXTERNAL importers
+// (anyone who reached into node_modules/@hegemonart/get-design-done/scripts/
+// lib/jittered-backoff.cjs directly) keep working for one minor grace window.
 //
-// This module is `.cjs` (not `.ts`) per Plan 20-14 D-01 so it can be
-// `require()`d from both the `.ts` runtime (hooks, MCP server) and future
-// `.cjs` CLI invocations without needing `--experimental-strip-types` at
-// every consumer site. Types live in the paired `jittered-backoff.d.cts`.
+// REMOVED IN v1.33.0 (D-02). Grace window: 1.31.5 ships with shims →
+// 1.32.0 still has them → 1.33.0 removes them. Internal callers already use
+// the sdk/ path (Plan 31-5-04/05) — this shim is external-only and 31-5-10's
+// no-stale-internal-refs guard excludes files carrying the GDD-DEPRECATION-SHIM
+// marker above.
 //
-// No external dependencies; pure Math.random + setTimeout.
-
-'use strict';
-
-/**
- * Default backoff parameters — chosen to cover retry-after-Xms through
- * retry-after-30s with reasonable mid-range distribution.
- */
-const DEFAULTS = Object.freeze({
-  baseMs: 100,
-  maxMs: 30_000,
-  factor: 2,
-  jitter: 0.2,
-});
-
-/**
- * Compute the jittered delay in milliseconds for a given attempt number.
- *
- * @param {number} attempt zero-based attempt counter (0 = first retry)
- * @param {object} [opts]
- * @param {number} [opts.baseMs]  initial delay before any jitter. Default 100.
- * @param {number} [opts.maxMs]   maximum un-jittered base. Default 30_000.
- * @param {number} [opts.factor]  per-attempt multiplier. Default 2.
- * @param {number} [opts.jitter]  symmetric jitter fraction in [0, 1). Default 0.2.
- * @returns {number} delay in ms. Never negative. May exceed `maxMs` by up
- *   to `jitter * maxMs` on the high side.
- *
- * Invariants:
- *  - `delayMs(n, opts) >= 0` for every non-negative `n`.
- *  - `delayMs(n, opts) <= maxMs * (1 + jitter)` for every non-negative `n`.
- *  - The distribution has nonzero stddev whenever `jitter > 0`.
- */
-function delayMs(attempt, opts) {
-  const baseMs = (opts && Number.isFinite(opts.baseMs)) ? opts.baseMs : DEFAULTS.baseMs;
-  const maxMs = (opts && Number.isFinite(opts.maxMs)) ? opts.maxMs : DEFAULTS.maxMs;
-  const factor = (opts && Number.isFinite(opts.factor)) ? opts.factor : DEFAULTS.factor;
-  const jitter = (opts && Number.isFinite(opts.jitter)) ? opts.jitter : DEFAULTS.jitter;
-
-  // Guard against nonsense inputs — callers that pass garbage shouldn't
-  // cause NaN or Infinity to propagate into setTimeout.
-  const a = Math.max(0, Number.isFinite(attempt) ? Math.floor(attempt) : 0);
-  const safeBase = Math.max(0, baseMs);
-  const safeMax = Math.max(safeBase, maxMs);
-  const safeFactor = factor > 0 ? factor : DEFAULTS.factor;
-  // Clamp jitter to [0, 1) — full-range (>=1) would allow negative values
-  // after subtraction, which we want to forbid by invariant.
-  const safeJitter = Math.min(0.999, Math.max(0, jitter));
-
-  // Exponential growth capped at safeMax.
-  // Math.pow with a huge attempt count can overflow to Infinity; the
-  // Math.min picks up safeMax before Infinity escapes.
-  const unjittered = Math.min(safeMax, safeBase * Math.pow(safeFactor, a));
-
-  // Symmetric jitter in [-jitter, +jitter).
-  // Math.random() returns [0, 1); 2r - 1 maps to [-1, 1); scale by jitter.
-  const noise = (Math.random() * 2 - 1) * safeJitter;
-  const delay = unjittered * (1 + noise);
-
-  // Floor at zero (noise could in theory go slightly negative due to FP
-  // precision even with safeJitter < 1, for very small unjittered values).
-  return Math.max(0, delay);
-}
-
-/**
- * Sleep for a jittered backoff interval. Convenience wrapper around
- * `delayMs` + `setTimeout`.
- *
- * @param {number} attempt zero-based attempt counter
- * @param {object} [opts] see {@link delayMs}
- * @returns {Promise<number>} resolves to the actual delay that was applied
- */
-function sleep(attempt, opts) {
-  const ms = delayMs(attempt, opts);
-  return new Promise((resolve) => {
-    setTimeout(() => resolve(ms), ms);
-  });
+// Emits a DeprecationWarning exactly ONCE per process: the module-level
+// `warned` flag plus Node's module cache (this file is evaluated once per
+// process regardless of how many times it is required).
+
+let warned = false;
+if (!warned) {
+  warned = true;
+  process.emitWarning(
+    'scripts/lib/jittered-backoff.cjs is deprecated; import sdk/primitives/jittered-backoff instead. Removed in v1.33.0.',
+    'DeprecationWarning',
+  );
 }
 
-module.exports = { delayMs, sleep, DEFAULTS };
+module.exports = require('../../sdk/primitives/jittered-backoff.cjs');

package/scripts/lib/lockfile.cjs

@@ -1,201 +1,29 @@
-// scripts/lib/lockfile.cjs
-//
-// Plan 20-14 — PID+timestamp sibling lockfile for `.cjs` consumers.
+'use strict';
+// scripts/lib/lockfile.cjs — GDD-DEPRECATION-SHIM (Plan 31-5-06, SDK-05, D-02).
 //
-// Algorithm mirrors scripts/lib/gdd-state/lockfile.ts (Plan 20-01):
-//   Lock path:     `${target}.lock`
-//   Payload:       { pid: number, host: string, acquired_at: ISO8601 }
-//   Acquire:       atomic `writeFileSync(..., { flag: 'wx' })`
-//   Stale rule:    pid dead (ESRCH via `kill(pid, 0)`) OR `acquired_at` older
-//                  than `staleMs` OR unparseable payload
-//   Release:       unlink; ENOENT is not an error; idempotent
+// Thin deprecation shim. The real implementation moved to
+// sdk/primitives/lockfile.cjs in Plan 31-5-04 (SDK consolidation).
+// This file is re-created at the OLD path so undocumented EXTERNAL importers
+// (anyone who reached into node_modules/@hegemonart/get-design-done/scripts/
+// lib/lockfile.cjs directly) keep working for one minor grace window.
 //
-// Windows: AV scanners and file-indexers can hold a file briefly after
-// close. `wx` create may fail with EPERM/EBUSY even when the target is
-// free; we treat these as transient and loop (same code path as EEXIST).
+// REMOVED IN v1.33.0 (D-02). Grace window: 1.31.5 ships with shims →
+// 1.32.0 still has them → 1.33.0 removes them. Internal callers already use
+// the sdk/ path (Plan 31-5-04/05) — this shim is external-only and 31-5-10's
+// no-stale-internal-refs guard excludes files carrying the GDD-DEPRECATION-SHIM
+// marker above.
 //
-// Dependency-cycle note: Plan 20-14's rate-guard + iteration-budget
-// consume this module, and both are required to stay dependency-light so
-// that hooks/budget-enforcer.ts can import them without dragging the
-// gdd-state MCP graph along. Hence this standalone .cjs port instead of
-// calling the .ts version.
-
-'use strict';
-
-const fs = require('node:fs');
-const os = require('node:os');
-
-const DEFAULT_STALE_MS = 60_000;
-const DEFAULT_MAX_WAIT_MS = 5_000;
-const DEFAULT_POLL_MS = 50;
-
-/**
- * Acquire an advisory lock at `${path}.lock`. Returns an idempotent
- * async release function.
- *
- * @param {string} path path being locked (we append `.lock`)
- * @param {object} [opts]
- * @param {number} [opts.staleMs]   ms after which an existing lock is stale. Default 60_000.
- * @param {number} [opts.maxWaitMs] total ms to wait before throwing. Default 5_000.
- * @param {number} [opts.pollMs]    ms between retry attempts. Default 50.
- * @returns {Promise<() => Promise<void>>} release function
- * @throws {Error} with name === 'LockAcquisitionError' when maxWaitMs elapses
- */
-async function acquire(path, opts) {
-  const o = opts || {};
-  const staleMs = Number.isFinite(o.staleMs) ? o.staleMs : DEFAULT_STALE_MS;
-  const maxWaitMs = Number.isFinite(o.maxWaitMs) ? o.maxWaitMs : DEFAULT_MAX_WAIT_MS;
-  const pollMs = Number.isFinite(o.pollMs) ? o.pollMs : DEFAULT_POLL_MS;
-
-  if (staleMs < 0 || maxWaitMs < 0 || pollMs < 0) {
-    throw new Error(
-      `lockfile.acquire: invalid options (staleMs=${staleMs}, maxWaitMs=${maxWaitMs}, pollMs=${pollMs})`,
-    );
-  }
-
-  const lockPath = `${path}.lock`;
-  const payload = JSON.stringify({
-    pid: process.pid,
-    host: os.hostname(),
-    acquired_at: new Date().toISOString(),
-  });
-  const startedAt = Date.now();
-
-  while (true) {
-    try {
-      fs.writeFileSync(lockPath, payload, { flag: 'wx', encoding: 'utf8' });
-      return makeRelease(lockPath);
-    } catch (err) {
-      const code = err && typeof err === 'object' ? err.code : undefined;
-      if (code !== 'EEXIST' && code !== 'EPERM' && code !== 'EBUSY') {
-        throw err;
-      }
-      // Try to read the current holder; if it vanished between EEXIST and
-      // read, loop immediately.
-      const existing = readLockSafe(lockPath);
-      if (existing === null) continue;
-
-      const parsed = parseLock(existing);
-      // Only clear when we're confident the lock is stale: the payload
-      // parses AND the PID/age check says so. An unparseable payload is
-      // treated as fresh — on Windows, AV/indexer can transiently deny
-      // reads (EACCES/EPERM/EBUSY), and clearing under that condition
-      // would let two writers race and lose increments.
-      if (parsed !== null && isStale(parsed, staleMs)) {
-        // Clear stale lock; race-tolerant — if it's already gone we get
-        // ENOENT, no-op.
-        try { fs.unlinkSync(lockPath); } catch { /* ignore */ }
-        continue;
-      }
-
-      if (Date.now() - startedAt >= maxWaitMs) {
-        const e = new Error(
-          `lockfile: failed to acquire ${lockPath} within ${maxWaitMs}ms (held by ${existing})`,
-        );
-        e.name = 'LockAcquisitionError';
-        e.lockPath = lockPath;
-        e.holder = existing;
-        e.waitedMs = Date.now() - startedAt;
-        throw e;
-      }
-      await sleep(pollMs);
-    }
-  }
-}
-
-function makeRelease(lockPath) {
-  let released = false;
-  return async function release() {
-    if (released) return;
-    released = true;
-    try {
-      fs.unlinkSync(lockPath);
-    } catch (err) {
-      const code = err && typeof err === 'object' ? err.code : undefined;
-      if (code === 'ENOENT') return; // idempotent — already gone
-      if (code === 'EPERM' || code === 'EBUSY') {
-        // Windows AV/indexer: retry once.
-        await sleep(50);
-        try {
-          if (fs.existsSync(lockPath)) fs.unlinkSync(lockPath);
-        } catch { /* give up; stale-detection will reclaim */ }
-        return;
-      }
-      // Any other errno: swallow. Best-effort cleanup; stale-age check
-      // will eventually reclaim the lock.
-    }
-  };
-}
-
-function readLockSafe(p) {
-  try {
-    return fs.readFileSync(p, 'utf8');
-  } catch (err) {
-    const code = err && typeof err === 'object' ? err.code : undefined;
-    if (code === 'ENOENT') return null;
-    return '<unreadable>';
-  }
-}
-
-function parseLock(raw) {
-  try {
-    const obj = JSON.parse(raw);
-    if (
-      obj && typeof obj === 'object' &&
-      typeof obj.pid === 'number' &&
-      typeof obj.host === 'string' &&
-      typeof obj.acquired_at === 'string'
-    ) {
-      return obj;
-    }
-    return null;
-  } catch {
-    return null;
-  }
-}
-
-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;
-}
-
-function isPidAlive(pid, host) {
-  if (host !== os.hostname()) return true; // can't introspect other hosts
-  if (pid === process.pid) return true;
-  try {
-    process.kill(pid, 0); // signal 0 = validate, don't deliver
-    return true;
-  } catch (err) {
-    const code = err && typeof err === 'object' ? err.code : undefined;
-    if (code === 'ESRCH') return false;
-    // EPERM / EACCES: process exists but is unsignalable; treat as alive.
-    return true;
-  }
-}
-
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
+// Emits a DeprecationWarning exactly ONCE per process: the module-level
+// `warned` flag plus Node's module cache (this file is evaluated once per
+// process regardless of how many times it is required).
 
-/**
- * `fs.renameSync` wrapper that retries once on Windows EPERM/EBUSY/EACCES.
- * AV scanners and the file-indexer can briefly hold a destination open
- * after another process closed it, causing rename to fail even when the
- * advisory lock is correctly held.
- *
- * Mirrors the inline retry in scripts/lib/gdd-state/index.ts mutate().
- */
-async function renameWithRetry(from, to) {
-  try {
-    fs.renameSync(from, to);
-  } catch (err) {
-    const code = err && typeof err === 'object' ? err.code : undefined;
-    if (code !== 'EPERM' && code !== 'EBUSY' && code !== 'EACCES') throw err;
-    await sleep(50);
-    fs.renameSync(from, to);
-  }
+let warned = false;
+if (!warned) {
+  warned = true;
+  process.emitWarning(
+    'scripts/lib/lockfile.cjs is deprecated; import sdk/primitives/lockfile instead. Removed in v1.33.0.',
+    'DeprecationWarning',
+  );
 }
 
-module.exports = { acquire, renameWithRetry };
+module.exports = require('../../sdk/primitives/lockfile.cjs');

package/scripts/lib/logger/index.ts

@@ -29,7 +29,7 @@
 //     process.stderr); the logger contract never propagates event-stream
 //     failures back to the caller.
 
-import { appendEvent } from '../event-stream/index.ts';
+import { appendEvent } from '../../../sdk/event-stream/index.ts';
 import { ConsoleSink, JsonlSink, MultiSink } from './sinks.ts';
 import {
   LEVEL_ORDER,

package/scripts/lib/parallelism-engine/concurrency-tuner.cjs

@@ -59,7 +59,7 @@ function getAppendEvent() {
     // with --experimental-strip-types (or Node 24 built-in TS) can
     // require it. If require fails (e.g., older runtime, missing
     // module), fall through to the no-op.
-    const m = require('../event-stream');
+    const m = require('../../../sdk/event-stream');
     if (m && typeof m.appendEvent === 'function') return m.appendEvent;
   } catch {
     // Swallow — best-effort telemetry. Losing one verdict is

package/scripts/lib/perf-analyzer/index.cjs

@@ -6,7 +6,7 @@
  * `.design/telemetry/trajectories/<cycle>.jsonl` files (agent trace
  * lines per Phase 22).
  *
- * JSONL discipline (same as scripts/lib/event-stream/reader.ts):
+ * JSONL discipline (same as sdk/event-stream/reader.ts):
  *   - One JSON object per line.
  *   - Blank lines / whitespace-only lines ignored silently.
  *   - Malformed lines tolerated — counted in skipped_count, NOT thrown.

package/scripts/lib/pipeline-runner/index.ts

@@ -23,11 +23,11 @@
 //
 // NEVER throws — every failure becomes a `PipelineResult`.
 
-import { appendEvent } from '../event-stream/index.ts';
-import type { BaseEvent } from '../event-stream/index.ts';
+import { appendEvent } from '../../../sdk/event-stream/index.ts';
+import type { BaseEvent } from '../../../sdk/event-stream/index.ts';
 import { getLogger } from '../logger/index.ts';
-import { transition as defaultTransition, TransitionGateFailed } from '../gdd-state/index.ts';
-import { ValidationError } from '../gdd-errors/index.ts';
+import { transition as defaultTransition, TransitionGateFailed } from '../../../sdk/state/index.ts';
+import { ValidationError } from '../../../sdk/errors/index.ts';
 
 import {
   STAGE_ORDER,

package/scripts/lib/pipeline-runner/state-machine.ts

@@ -15,7 +15,7 @@
 //     name is in the set. Unknown stage names in `skipStages` are
 //     tolerated (no-op) — the filter is a membership check.
 
-import { ValidationError } from '../gdd-errors/index.ts';
+import { ValidationError } from '../../../sdk/errors/index.ts';
 import type { Stage } from './types.ts';
 
 /**

package/scripts/lib/prompt-dedup/index.cjs

@@ -27,7 +27,7 @@ const DEFAULT_THRESHOLD = 3;  // D-11 — '>= 3 agents'
  */
 function getAppendEvent() {
   try {
-    const m = require('../event-stream');
+    const m = require('../../../sdk/event-stream');
     if (m && typeof m.appendEvent === 'function') return m.appendEvent;
   } catch { /* swallow — event-stream not on path */ }
   return function noopAppend(_ev) {};

package/scripts/lib/rate-guard.cjs

@@ -20,7 +20,7 @@
 // `resetAt` wins. This matches the D-01 rule in the plan.
 //
 // State-file writes are atomic (temp + rename) and coordinated by
-// scripts/lib/lockfile.cjs so two child processes hitting `ingestHeaders`
+// sdk/primitives/lockfile.cjs so two child processes hitting `ingestHeaders`
 // concurrently can never corrupt the file. The lock is scoped to the
 // state file, not to the provider directory, so different providers can
 // update in parallel.
@@ -30,7 +30,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 
-const { acquire, renameWithRetry } = require('./lockfile.cjs');
+const { acquire, renameWithRetry } = require('../../sdk/primitives/lockfile.cjs');
 
 const STATE_DIR_REL = path.join('.design', 'rate-limits');
 const LOCK_MAX_WAIT_MS = 3_000;

package/scripts/lib/recipe-loader.cjs

@@ -0,0 +1,142 @@
+/**
+ * recipe-loader.cjs — recipes/ scaffold loader (Plan 31-5-03, RECIPE-01 / SC#14).
+ *
+ * The top-level recipes/ directory ships EMPTY of recipes; it is populated
+ * downstream by Phase 32 (skill-trigger recipes), Phase 33.6 (per-provider),
+ * Phase 26 (per-runtime/per-model), and Phase 23.5 (bandit-arm shape). This
+ * module fixes the loading contract those phases build against so each does not
+ * reinvent it. Modelled on Storybloq's src/autonomous/recipes/ loader.ts.
+ *
+ * Contract:
+ *   loadRecipe(name, opts?) -> Recipe
+ *     name : recipe stem; resolves <repoRoot>/recipes/<name>.json
+ *     opts : { recipesDir, schemaPath, fs } — all injectable for tests
+ *     returns : the validated, parsed Recipe object
+ *     throws  : Error('recipe not found: <name>')              if the file is absent
+ *               Error('recipe <name> failed schema validation: …') if invalid
+ *
+ * Cache (SC#14 "caches by SHA"):
+ *   Keyed by name + ':' + sha256(fileBytes). Each call reads the file once to
+ *   compute the content hash; on a HIT (unchanged bytes) it returns the cached
+ *   object WITHOUT re-parsing / re-validating. On a MISS (changed bytes) it
+ *   parses + validates + stores. Keying by content SHA — not just name — means
+ *   an edited recipe is correctly re-validated.
+ *
+ * Empty-dir safety: this module requires cleanly when recipes/ is empty, and a
+ * directory listing of an empty (just-.gitkeep) dir does not throw. loadRecipe
+ * of a missing name throws the clear not-found error — distinct from "the empty
+ * dir is broken" (it is a valid scaffold state).
+ *
+ * Uses the repo's existing `ajv` dependency (package.json "ajv": "^8.18.0") —
+ * no new dependency. The schema is compiled once per schemaPath (singleton).
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const Ajv = require('ajv');
+
+// recipe-loader.cjs lives in scripts/lib/ → two levels up is the repo root.
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const DEFAULT_RECIPES_DIR = path.join(REPO_ROOT, 'recipes');
+const DEFAULT_SCHEMA_PATH = path.join(REPO_ROOT, 'reference', 'schemas', 'recipe.schema.json');
+
+// Ajv 8 CJS: require('ajv') is (or wraps) the constructor.
+const AjvCtor = Ajv.default || Ajv;
+
+// SHA-keyed cache: `name + ':' + sha256(bytes)` → parsed Recipe object.
+const cache = new Map();
+
+// Compiled-validator singletons, keyed by resolved schemaPath. The schema is a
+// small trusted local file, so allErrors:true (full error list → clear message)
+// is safe here — unlike the untrusted-HTTP receiver which fails fast.
+const validators = new Map();
+
+// Test-observability counter: increments once per parse+validate (i.e. per
+// cache MISS). A cache HIT does not bump it. Tests assert on the delta to prove
+// SHA-keyed hit/miss semantics without depending on raw read counts (a hit must
+// still read the file once to hash it).
+let _validations = 0;
+
+/**
+ * Get (compiling once) the validator for a schema path.
+ * @param {string} schemaPath
+ * @param {typeof fs} fsImpl
+ * @returns {import('ajv').ValidateFunction}
+ */
+function getValidator(schemaPath, fsImpl) {
+  const resolved = path.resolve(schemaPath);
+  let validate = validators.get(resolved);
+  if (validate) return validate;
+
+  const schema = JSON.parse(fsImpl.readFileSync(resolved, 'utf8'));
+  const ajv = new AjvCtor({ allErrors: true, strict: false });
+  validate = ajv.compile(schema);
+  validators.set(resolved, validate);
+  return validate;
+}
+
+/**
+ * Load + validate a recipe by name.
+ * @param {string} name - recipe stem; resolves <recipesDir>/<name>.json
+ * @param {{ recipesDir?: string, schemaPath?: string, fs?: typeof fs }} [opts]
+ * @returns {Record<string, unknown>} the validated, parsed Recipe object
+ */
+function loadRecipe(name, opts = {}) {
+  if (typeof name !== 'string' || name.length === 0) {
+    throw new Error('recipe name must be a non-empty string');
+  }
+
+  const fsImpl = opts.fs || fs;
+  const dir = opts.recipesDir || DEFAULT_RECIPES_DIR;
+  const schemaPath = opts.schemaPath || DEFAULT_SCHEMA_PATH;
+  const file = path.join(dir, name + '.json');
+
+  if (!fsImpl.existsSync(file)) {
+    throw new Error('recipe not found: ' + name);
+  }
+
+  // Read once per call to compute the content hash (the cache key).
+  const bytes = fsImpl.readFileSync(file);
+  const sha = crypto.createHash('sha256').update(bytes).digest('hex');
+  const key = name + ':' + sha;
+
+  // Cache HIT: unchanged bytes → return cached object, skip parse + validate.
+  if (cache.has(key)) {
+    return cache.get(key);
+  }
+
+  // Cache MISS: parse + validate + store.
+  let parsed;
+  try {
+    parsed = JSON.parse(bytes.toString('utf8'));
+  } catch (err) {
+    throw new Error('recipe ' + name + ' is not valid JSON: ' + err.message);
+  }
+
+  const validate = getValidator(schemaPath, fsImpl);
+  _validations += 1;
+  const ok = validate(parsed) === true;
+  if (!ok) {
+    throw new Error(
+      'recipe ' + name + ' failed schema validation: ' + JSON.stringify(validate.errors || []),
+    );
+  }
+
+  cache.set(key, parsed);
+  return parsed;
+}
+
+/** Test hook: clear the SHA cache (does not drop compiled validators). */
+function _clearCache() {
+  cache.clear();
+}
+
+/** Test hook: introspect parse+validate counts (one per cache MISS). */
+function _stats() {
+  return { validations: _validations, cacheSize: cache.size };
+}
+
+module.exports = { loadRecipe, _clearCache, _stats };

package/scripts/lib/session-runner/errors.ts

@@ -38,7 +38,7 @@ import {
   OperationFailedError,
   StateConflictError,
   type GDDError,
-} from '../gdd-errors/index.ts';
+} from '../../../sdk/errors/index.ts';
 
 /**
  * Build an absolute path to a repo-root-relative file. We can't use
@@ -68,7 +68,7 @@ const REPO_ROOT = findRepoRoot();
  */
 const nodeRequire = createRequire(join(REPO_ROOT, 'package.json'));
 const transportClassifier = nodeRequire(
-  resolve(REPO_ROOT, 'scripts/lib/error-classifier.cjs'),
+  resolve(REPO_ROOT, 'sdk/primitives/error-classifier.cjs'),
 ) as {
   classify: (err: unknown) => {
     reason: string;
@@ -375,7 +375,7 @@ export function mapSdkError(err: unknown): MappedSdkError {
   }
 
   // 9. Transport-layer classification (ECONNRESET, ETIMEDOUT, etc.).
-  //    Delegate to scripts/lib/error-classifier.cjs which knows the errno
+  //    Delegate to sdk/primitives/error-classifier.cjs which knows the errno
   //    vocabulary. Only trust its `retryable` flag for transient network
   //    classes — other classes were already handled above.
   const classified = transportClassifier.classify(err);

package/scripts/lib/session-runner/index.ts

@@ -26,8 +26,8 @@
 //     (always; payload status mirrors SessionResult.status). Optional
 //     `session.budget_exceeded` emitted when the budget trips.
 
-import { appendEvent } from '../event-stream/index.ts';
-import type { BaseEvent } from '../event-stream/index.ts';
+import { appendEvent } from '../../../sdk/event-stream/index.ts';
+import type { BaseEvent } from '../../../sdk/event-stream/index.ts';
 import { sanitize as defaultSanitize } from '../prompt-sanitizer/index.ts';
 
 import { mapSdkError } from './errors.ts';
@@ -64,7 +64,7 @@ function _findRepoRoot(): string {
 const _REPO_ROOT = _findRepoRoot();
 const _nodeRequire = createRequire(_join(_REPO_ROOT, 'package.json'));
 const jitteredBackoff = _nodeRequire(
-  _resolve(_REPO_ROOT, 'scripts/lib/jittered-backoff.cjs'),
+  _resolve(_REPO_ROOT, 'sdk/primitives/jittered-backoff.cjs'),
 ) as {
   delayMs: (attempt: number, opts?: { baseMs?: number; maxMs?: number; factor?: number; jitter?: number }) => number;
 };

package/scripts/lib/session-runner/transcript.ts

@@ -2,7 +2,7 @@
 // transcript writer for Phase 21 headless Agent SDK sessions
 // (Plan 21-01 Task 4).
 //
-// Design mirrors scripts/lib/event-stream/writer.ts but is scoped to one
+// Design mirrors sdk/event-stream/writer.ts but is scoped to one
 // session per file rather than the global telemetry stream. Each session
 // owns a dedicated `.design/sessions/<ISO>-<stage>.jsonl` file; the
 // filename is stable for the full run and survives retries (retries

package/scripts/lib/tool-scoping/index.ts

@@ -21,7 +21,7 @@
 //   * Plan 21-01 `session-runner`  — computes `allowedTools` for each session.
 //   * Plan 21-05 `pipeline-runner` — picks the correct scope per stage.
 
-import { ValidationError } from '../gdd-errors/index.ts';
+import { ValidationError } from '../../../sdk/errors/index.ts';
 import type { Scope, ScopeInput, ScopeViolation, Stage } from './types.ts';
 import {
   NATIVE_TOOLS,