@hegemonart/get-design-done 1.54.0 → 1.56.0

package/scripts/lib/health-mirror/index.cjs

@@ -8,7 +8,7 @@
 // Surface:
 //   async getHealthChecks(rootDir) → { checks: HealthCheck[] }
 //
-// The 9 checks (in stable order) are:
+// The 10 checks (in stable order) are:
 //   1. claude_md            — CLAUDE.md presence
 //   2. planning_dir         — .planning/ presence
 //   3. design_dir           — .design/ presence
@@ -18,6 +18,7 @@
 //   7. skill_discipline     — using-gdd bootstrap + SessionStart inject (Plan 32-07)
 //   8. harness_freshness    — per-harness last_verified age (Phase 44)
 //   9. stack_addendums      — Phase 54 coverage: N/M detected stacks have addendums
+//  10. dashboard_reachable  — Phase 55: bin/gdd-dashboard on disk + data plane loads
 //
 // Check 5 was added in Plan 30-06 — surfaces the report-issue kill-switch
 // (env or config disable) so users can verify why the command is
@@ -48,6 +49,22 @@
 //                                           inject-using-gdd entry)
 // status: 'ok' when ready, 'warn' otherwise. PURE read-only (rootDir-relative
 // file + JSON inspection only) — NEVER throws, NEVER networks.
+//
+// Check 10 was added in Phase 55 — surfaces whether the GDD dashboard is
+// reachable so a user running /gdd:health knows the `gdd dashboard` entrypoint
+// is wired. GRACEFUL-ABSENT by design (D-8 risk surfacing precedent): the
+// dashboard is an opt-in, read-only surface that also works via file-scrape, so
+// a missing bin or absent data plane is a 'warn' (actionable note), NEVER a
+// hard 'fail'. The status is 'ok' when BOTH the bin/gdd-dashboard trampoline
+// resolves on disk (located via a package-root walk-up — the Phase 53/54 lesson,
+// NEVER a fixed __dirname jump) AND the dashboard data plane module
+// (sdk/dashboard/data/source.cjs) loads + exposes loadDashboardModel. The detail
+// line is one of:
+//   - "dashboard: bin/gdd-dashboard present; data plane ok"
+//   - "dashboard: bin missing"                 (trampoline not on disk)
+//   - "dashboard: data plane unavailable"      (bin present, source.cjs absent)
+//   - "dashboard: bin missing; data plane unavailable"
+// PURE read-only (fs.statSync + a wrapped require) — NEVER throws, NEVER networks.
 
 const fs = require('node:fs');
 const path = require('node:path');
@@ -310,6 +327,39 @@ async function getHealthChecks(rootDir) {
     checks.push({ name: 'stack_addendums', status, detail });
   }
 
+  // 10. dashboard_reachable — Phase 55. GRACEFUL-ABSENT: reports whether the
+  // GDD dashboard entrypoint is wired (bin/gdd-dashboard on disk) AND its data
+  // plane module loads. NEVER 'fail' — a missing bin is a 'warn' note because
+  // the dashboard is opt-in and also works via file-scrape. PURE read-only
+  // (fs.statSync + a wrapped require); NEVER throws, NEVER networks.
+  {
+    let status;
+    let detail;
+    try {
+      const gddRoot = resolveDashboardRoot(rootDir);
+      const binPresent = dashboardBinResolves(gddRoot);
+      const dataPlaneOk = dashboardDataPlaneLoads(gddRoot);
+      if (binPresent && dataPlaneOk) {
+        status = 'ok';
+        detail = 'dashboard: bin/gdd-dashboard present; data plane ok';
+      } else {
+        status = 'warn';
+        if (!binPresent && !dataPlaneOk) {
+          detail = 'dashboard: bin missing; data plane unavailable';
+        } else if (!binPresent) {
+          detail = 'dashboard: bin missing';
+        } else {
+          detail = 'dashboard: data plane unavailable';
+        }
+      }
+    } catch {
+      // Absolute safety net — the health probe must never crash on this check.
+      status = 'warn';
+      detail = 'dashboard: unavailable';
+    }
+    checks.push({ name: 'dashboard_reachable', status, detail });
+  }
+
   return { checks };
 }
 
@@ -402,4 +452,99 @@ function figmaVariablesBlockedLocally(rootDir) {
   }
 }
 
+/**
+ * Walk UP from `startDir` to the GDD package root (the first ancestor whose
+ * package.json `name` is the GDD package). This mirrors the Phase 53/54 lesson
+ * (sdk/dashboard/data/_pkg-root.cjs): NEVER resolve a cross-tree sibling via a
+ * fixed __dirname-relative jump. The shipped package name is scoped
+ * ("@hegemonart/get-design-done"); dev/self-host/fixture roots may use the bare
+ * "get-design-done" — both match. Bounded climb; defensive. Returns null if no
+ * GDD root marker is found.
+ *
+ * @param {string} startDir
+ * @returns {string|null} absolute package-root dir, or null
+ */
+function findGddPackageRoot(startDir) {
+  try {
+    let dir = path.resolve(startDir);
+    for (let i = 0; i < 12; i++) {
+      try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+        if (pkg && typeof pkg.name === 'string') {
+          if (pkg.name === 'get-design-done' || /\/get-design-done$/.test(pkg.name)) {
+            return dir;
+          }
+        }
+      } catch {
+        // no/garbage package.json at this level — keep climbing
+      }
+      const parent = path.dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve the AUTHORITATIVE GDD package root for the dashboard probe, given the
+ * project root being health-checked. Resolution (D-7 walk-up, never a fixed
+ * __dirname jump):
+ *   - If `rootDir` itself sits inside a GDD checkout (dev / self-host / a
+ *     hermetic fixture that declares the GDD name), THAT root is authoritative —
+ *     its own bin/ + sdk/dashboard/ are the truth. No cross-root fallback (so a
+ *     fixture is hermetic + deterministic regardless of the shipped tree).
+ *   - Otherwise `rootDir` is an unrelated CONSUMER project (no GDD marker); the
+ *     dashboard ships alongside THIS module, so walk up from __dirname.
+ * Returns null only if neither resolves (degrades the check to 'warn').
+ *
+ * @param {string} rootDir project root passed to getHealthChecks
+ * @returns {string|null}
+ */
+function resolveDashboardRoot(rootDir) {
+  const fromRoot = findGddPackageRoot(rootDir);
+  if (fromRoot) return fromRoot;
+  return findGddPackageRoot(__dirname);
+}
+
+/**
+ * Does the bin/gdd-dashboard trampoline resolve on disk under the authoritative
+ * GDD root? (Phase 55, check 10.) `fs.statSync` follows symlinks, so an npm
+ * bin-linked trampoline (a symlink resolving to a file) counts as present. PURE
+ * read-only; NEVER throws.
+ *
+ * @param {string} gddRoot authoritative GDD root (or null)
+ * @returns {boolean} true iff bin/gdd-dashboard is present on disk
+ */
+function dashboardBinResolves(gddRoot) {
+  if (!gddRoot) return false;
+  try {
+    return fs.statSync(path.join(gddRoot, 'bin', 'gdd-dashboard')).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Does the dashboard data plane module load + expose loadDashboardModel under
+ * the authoritative GDD root? (Phase 55, check 10.) The data plane is
+ * sdk/dashboard/data/source.cjs (R1 — the in-process shared-lib read surface the
+ * dashboard renders). A missing module or a require error degrades to false
+ * (→ 'warn'), NEVER throws.
+ *
+ * @param {string} gddRoot authoritative GDD root (or null)
+ * @returns {boolean} true iff source.cjs loads and exports loadDashboardModel
+ */
+function dashboardDataPlaneLoads(gddRoot) {
+  if (!gddRoot) return false;
+  try {
+    const mod = require(path.join(gddRoot, 'sdk', 'dashboard', 'data', 'source.cjs'));
+    return !!(mod && typeof mod.loadDashboardModel === 'function');
+  } catch {
+    return false;
+  }
+}
+
 module.exports = { getHealthChecks };

package/scripts/lib/manifest/skills.json

@@ -319,6 +319,14 @@
       "user_invocable": true,
       "tools": "Read, Bash, Grep, Write"
     },
+    {
+      "name": "override",
+      "description": "Escalation surface for a risk-blocked action or a fact-force gate. Use when the Phase 56 risk gate blocked a writer action (suggested_action=block) and a reviewer has signed off, or when the first-write fact-force gate is holding a file you have legitimately reviewed. Activates for requests involving overriding a blocked edit, approving a high-risk change, or clearing a fact-force hold on a path.",
+      "argument_hint": "<finding-id | factforce <path>> [--approver <who>] [--reason <text>]",
+      "user_invocable": true,
+      "tools": "Read, Write, Bash, Grep, Glob",
+      "registered_in_phase": "56"
+    },
     {
       "name": "pause",
       "description": "Write a numbered checkpoint so work can resume in a new session without re-running completed stages.",

package/scripts/lib/risk/calibration.cjs

@@ -0,0 +1,385 @@
+'use strict';
+/**
+ * scripts/lib/risk/calibration.cjs — Phase 56 (CAL-01) per-agent risk
+ * calibration + the bandit reward bridge.
+ *
+ * The risk scorer (scripts/lib/risk/compute-risk.cjs) is a STATIC table-driven
+ * model — it cannot learn that a particular writer agent chronically under- or
+ * over-scores its own actions. This module is the feedback layer: it records
+ * per-agent outcomes in a rolling-50 window, derives three calibration
+ * statistics, flags drift, and feeds a reward signal into the Phase 23.5
+ * Thompson-sampling bandit (scripts/lib/bandit-router.cjs) so the adaptive
+ * router can react to a mis-calibrated agent over time.
+ *
+ * Persistence:
+ *   .design/telemetry/calibration.json
+ *     {
+ *       schema_version: '56.0',
+ *       generated_at:   ISO,
+ *       agents: {
+ *         "<agent>": {
+ *           window: [ { risk, accepted, user_undo, post_apply_correct }, … ≤50 ],
+ *           mean_risk_emitted:      number,  // mean(window.risk)
+ *           override_rate:          number,  // P(rejected OR undone)
+ *           post_apply_correctness: number   // P(correct | applied)
+ *         }, …
+ *       }
+ *     }
+ *   Atomic .tmp + rename (mirrors instinct-store.save / ds-arms.save). The
+ *   `.design/` tree is gitignored + worktree-local (R5).
+ *
+ * Purity contract:
+ *   - detectDrift + riskReward are PURE (no I/O, no Date.now / Math.random;
+ *     the DRIFT thresholds are frozen). Deterministic for the suite.
+ *   - updateCalibration reads/writes the FS, but only via the injected
+ *     `{root}` (or `file`) so tests run hermetically under a tmpdir. The only
+ *     non-determinism is `generated_at` (an ISO stamp), which callers can pin
+ *     via opts.now.
+ *   - recordRiskOutcome calls bandit-router.update BEST-EFFORT — it never
+ *     throws (a telemetry write must never break a hook / agent turn).
+ *
+ * Zero new dependency. CommonJS to match the scripts/lib/ siblings.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const SCHEMA_VERSION = '56.0';
+const DEFAULT_CALIBRATION_PATH = '.design/telemetry/calibration.json';
+
+/** Rolling window length (CAL-01): keep the last 50 outcomes per agent. */
+const WINDOW_SIZE = 50;
+
+/**
+ * Drift thresholds (frozen). detectDrift compares the rolling stats against
+ * these bands:
+ *   under_scoring — the agent emits LOW risk yet the user overrides OFTEN:
+ *                   the scores are too tame (false sense of safety).
+ *   over_scoring  — the agent emits HIGH risk yet applied actions are almost
+ *                   always correct AND the user rarely overrides: the scores
+ *                   are too alarmist (friction without payoff).
+ */
+const DRIFT = Object.freeze({
+  under_scoring: Object.freeze({ mean_risk_max: 0.35, override_rate_min: 0.30 }),
+  over_scoring: Object.freeze({
+    mean_risk_min: 0.65,
+    correctness_min: 0.90,
+    override_rate_max: 0.10,
+  }),
+});
+
+/**
+ * Clamp to [0, 1]. Non-finite -> 0 (matches compute-risk.clamp01 semantics).
+ * @param {number} n
+ * @returns {number}
+ */
+function clamp01(n) {
+  if (typeof n !== 'number' || Number.isNaN(n)) return 0;
+  if (n < 0) return 0;
+  if (n > 1) return 1;
+  return n;
+}
+
+/**
+ * Resolve the on-disk calibration file, honouring an absolute override.
+ * Accepts `{ file }` (explicit path) or `{ root }` / `{ baseDir }` (a project
+ * root under which DEFAULT_CALIBRATION_PATH is resolved).
+ * @param {{file?:string, root?:string, baseDir?:string}} [opts]
+ * @returns {{file:string, dir:string}}
+ */
+function paths(opts = {}) {
+  let file;
+  if (opts.file) {
+    file = path.isAbsolute(opts.file)
+      ? opts.file
+      : path.resolve(opts.root ?? opts.baseDir ?? process.cwd(), opts.file);
+  } else {
+    file = path.resolve(opts.root ?? opts.baseDir ?? process.cwd(), DEFAULT_CALIBRATION_PATH);
+  }
+  return { file, dir: path.dirname(file) };
+}
+
+/**
+ * Load the calibration store, or a fresh envelope when absent/corrupt.
+ * @param {{file?:string, root?:string, baseDir?:string}} [opts]
+ * @returns {{schema_version:string, generated_at?:string, agents:object}}
+ */
+function load(opts = {}) {
+  const { file } = paths(opts);
+  if (!fs.existsSync(file)) {
+    return { schema_version: SCHEMA_VERSION, agents: {} };
+  }
+  try {
+    const data = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (!data || typeof data !== 'object' || typeof data.agents !== 'object' || data.agents === null) {
+      return { schema_version: SCHEMA_VERSION, agents: {} };
+    }
+    return data;
+  } catch {
+    return { schema_version: SCHEMA_VERSION, agents: {} };
+  }
+}
+
+/**
+ * Persist the calibration store atomically (.tmp + rename).
+ * @param {object} store
+ * @param {{file?:string, root?:string, baseDir?:string, now?:string|Date}} [opts]
+ * @returns {string} absolute path written
+ */
+function save(store, opts = {}) {
+  const { file, dir } = paths(opts);
+  fs.mkdirSync(dir, { recursive: true });
+  store.schema_version = SCHEMA_VERSION;
+  store.generated_at =
+    opts.now instanceof Date
+      ? opts.now.toISOString()
+      : typeof opts.now === 'string'
+        ? opts.now
+        : new Date().toISOString();
+  const tmp = file + '.tmp';
+  fs.writeFileSync(tmp, JSON.stringify(store, null, 2) + '\n');
+  fs.renameSync(tmp, file);
+  return file;
+}
+
+/**
+ * Coerce a raw outcome into the canonical window record. Unknown / missing
+ * fields degrade safely:
+ *   risk               -> clamp01(number), default 0
+ *   accepted           -> boolean (default true — an action that produced an
+ *                         outcome without an explicit reject is treated as
+ *                         applied)
+ *   user_undo          -> boolean (default false)
+ *   post_apply_correct -> boolean | null (null = "not yet known"; only counts
+ *                         toward post_apply_correctness once resolved)
+ * @param {object} record
+ * @returns {{risk:number, accepted:boolean, user_undo:boolean, post_apply_correct:(boolean|null)}}
+ */
+function normalizeRecord(record) {
+  const r = record && typeof record === 'object' ? record : {};
+  return {
+    risk: clamp01(typeof r.risk === 'number' ? r.risk : 0),
+    accepted: r.accepted === undefined ? true : Boolean(r.accepted),
+    user_undo: Boolean(r.user_undo),
+    post_apply_correct:
+      r.post_apply_correct === undefined || r.post_apply_correct === null
+        ? null
+        : Boolean(r.post_apply_correct),
+  };
+}
+
+/**
+ * Recompute the three rolling statistics over a window of normalized records.
+ *
+ *   mean_risk_emitted      = mean(risk)                           (0 when empty)
+ *   override_rate          = P(!accepted OR user_undo)            (0 when empty)
+ *   post_apply_correctness = P(post_apply_correct | applied)      (1 when no
+ *       resolved applied records — an agent with no known-bad applied actions
+ *       reads as fully correct; this is the conservative direction for the
+ *       over_scoring drift gate, which additionally requires high mean risk +
+ *       low override, so an empty window never spuriously trips it)
+ *
+ * @param {Array} window  normalized records
+ * @returns {{mean_risk_emitted:number, override_rate:number, post_apply_correctness:number}}
+ */
+function computeStats(window) {
+  const w = Array.isArray(window) ? window : [];
+  const n = w.length;
+  if (n === 0) {
+    return { mean_risk_emitted: 0, override_rate: 0, post_apply_correctness: 1 };
+  }
+  let riskSum = 0;
+  let overrides = 0;
+  let appliedResolved = 0;
+  let appliedCorrect = 0;
+  for (const rec of w) {
+    riskSum += rec.risk;
+    const overridden = !rec.accepted || rec.user_undo;
+    if (overridden) overrides += 1;
+    // "applied" = accepted AND not undone. Only resolved (non-null) correctness
+    // signals count toward the correctness rate.
+    const applied = rec.accepted && !rec.user_undo;
+    if (applied && rec.post_apply_correct !== null) {
+      appliedResolved += 1;
+      if (rec.post_apply_correct === true) appliedCorrect += 1;
+    }
+  }
+  return {
+    mean_risk_emitted: riskSum / n,
+    override_rate: overrides / n,
+    post_apply_correctness: appliedResolved === 0 ? 1 : appliedCorrect / appliedResolved,
+  };
+}
+
+/**
+ * Record one risk outcome for `agent`, append to its rolling-50 window, drop
+ * the oldest beyond 50, recompute the three statistics, and persist atomically.
+ *
+ * @param {string} agent   the writer agent the assessment scored (e.g. 'design-fixer')
+ * @param {{risk?:number, accepted?:boolean, user_undo?:boolean, post_apply_correct?:boolean}} record
+ * @param {{file?:string, root?:string, baseDir?:string, now?:string|Date}} [opts]
+ * @returns {{agent:string, stats:{mean_risk_emitted:number, override_rate:number, post_apply_correctness:number}, windowSize:number, path:string}}
+ */
+function updateCalibration(agent, record, opts = {}) {
+  if (typeof agent !== 'string' || agent.length === 0) {
+    throw new TypeError('updateCalibration: agent (non-empty string) required');
+  }
+  const store = load(opts);
+  if (!store.agents || typeof store.agents !== 'object') store.agents = {};
+
+  const prev = store.agents[agent];
+  const prevWindow =
+    prev && Array.isArray(prev.window) ? prev.window.map(normalizeRecord) : [];
+
+  prevWindow.push(normalizeRecord(record));
+  // Keep only the last WINDOW_SIZE entries (rolling window).
+  const window =
+    prevWindow.length > WINDOW_SIZE ? prevWindow.slice(prevWindow.length - WINDOW_SIZE) : prevWindow;
+
+  const stats = computeStats(window);
+  store.agents[agent] = {
+    window,
+    mean_risk_emitted: stats.mean_risk_emitted,
+    override_rate: stats.override_rate,
+    post_apply_correctness: stats.post_apply_correctness,
+  };
+
+  const written = save(store, opts);
+  return { agent, stats, windowSize: window.length, path: written };
+}
+
+/**
+ * Classify calibration drift from an agent's rolling stats. PURE.
+ *
+ *   under_scoring: mean_risk_emitted < 0.35  &&  override_rate > 0.30
+ *   over_scoring:  mean_risk_emitted > 0.65  &&  post_apply_correctness > 0.90
+ *                  &&  override_rate < 0.10
+ *   else:          'none'
+ *
+ * under_scoring is checked first; the two bands are mutually exclusive by
+ * construction (mean-risk bands do not overlap) but the explicit order makes
+ * the contract unambiguous.
+ *
+ * @param {{mean_risk_emitted?:number, override_rate?:number, post_apply_correctness?:number}} stats
+ * @param {object} [cfg]  defaults to the frozen DRIFT thresholds
+ * @returns {'under_scoring'|'over_scoring'|'none'}
+ */
+function detectDrift(stats, cfg = DRIFT) {
+  const s = stats && typeof stats === 'object' ? stats : {};
+  const mean = typeof s.mean_risk_emitted === 'number' ? s.mean_risk_emitted : 0;
+  const override = typeof s.override_rate === 'number' ? s.override_rate : 0;
+  const correct = typeof s.post_apply_correctness === 'number' ? s.post_apply_correctness : 0;
+
+  const under = cfg && cfg.under_scoring ? cfg.under_scoring : DRIFT.under_scoring;
+  const over = cfg && cfg.over_scoring ? cfg.over_scoring : DRIFT.over_scoring;
+
+  if (mean < under.mean_risk_max && override > under.override_rate_min) {
+    return 'under_scoring';
+  }
+  if (
+    mean > over.mean_risk_min &&
+    correct > over.correctness_min &&
+    override < over.override_rate_max
+  ) {
+    return 'over_scoring';
+  }
+  return 'none';
+}
+
+/**
+ * Map a single risk outcome to a bandit reward in [0, 1]. PURE.
+ *
+ * Contract (mirrors the Phase 23.5 lexicographic shape — correctness first):
+ *   - rejected (accepted === false) OR undone (user_undo === true) -> 0
+ *     (the user vetoed the action; no credit regardless of risk).
+ *   - otherwise -> clamp01(1 - 0.5 * risk)
+ *     (an accepted, not-undone action earns a reward that decays linearly with
+ *     the risk it carried: a confident low-risk accept ≈ 1.0; a high-risk
+ *     accept still earns partial credit ≈ 0.5 because the user did keep it).
+ *
+ * Examples (the calibration suite pins these):
+ *   {accepted:true,  risk:0.2}                 -> 0.9
+ *   {accepted:false, risk:0.2}                 -> 0
+ *   {accepted:true,  risk:0.9}                 -> 0.55
+ *   {accepted:true,  risk:0.0, user_undo:true} -> 0
+ *
+ * @param {{accepted?:boolean, risk?:number, user_undo?:boolean}} input
+ * @returns {number} reward in [0, 1]
+ */
+function riskReward(input) {
+  const i = input && typeof input === 'object' ? input : {};
+  // An explicit reject, or any user_undo, zeroes the reward.
+  if (i.accepted === false) return 0;
+  if (i.user_undo === true) return 0;
+  const risk = clamp01(typeof i.risk === 'number' ? i.risk : 0);
+  return clamp01(1 - 0.5 * risk);
+}
+
+/**
+ * Thin best-effort bridge: compute the risk reward for an outcome and feed it
+ * into the Thompson-sampling bandit (scripts/lib/bandit-router.cjs update()).
+ *
+ * NEVER throws — a telemetry/learning write must not break the hook or agent
+ * turn that triggered it. On any failure (bandit module absent, bad input,
+ * FS error) it returns `{ recorded:false, reason }` and swallows the error.
+ *
+ * The bandit's update() needs `(agent, bin, tier, reward)`. The caller supplies
+ * the routing context it used (bin = touches-size bin, tier = model tier). When
+ * a context field is missing we DO NOT guess — we skip the bandit write and
+ * report it, because writing to the wrong arm would corrupt the posterior.
+ *
+ * @param {{
+ *   agent: string,
+ *   bin?: string,
+ *   tier?: string,
+ *   accepted?: boolean,
+ *   risk?: number,
+ *   user_undo?: boolean,
+ *   bandit?: object,            // injectable for tests (defaults to require'd module)
+ *   root?: string, baseDir?: string, posteriorPath?: string,
+ * }} input
+ * @returns {{recorded:boolean, reward:number, reason?:string}}
+ */
+function recordRiskOutcome(input) {
+  const reward = riskReward(input || {});
+  try {
+    const i = input && typeof input === 'object' ? input : {};
+    if (typeof i.agent !== 'string' || i.agent.length === 0) {
+      return { recorded: false, reward, reason: 'agent required for bandit update' };
+    }
+    if (typeof i.bin !== 'string' || i.bin.length === 0 || typeof i.tier !== 'string' || i.tier.length === 0) {
+      // Without a routing context we cannot address an arm — skip cleanly.
+      return { recorded: false, reward, reason: 'bin+tier required for bandit update' };
+    }
+    // Lazy require so a missing/breaking bandit module degrades to best-effort.
+    const bandit = i.bandit || require('../bandit-router.cjs');
+    bandit.update({
+      agent: i.agent,
+      bin: i.bin,
+      tier: i.tier,
+      reward,
+      baseDir: i.baseDir ?? i.root,
+      posteriorPath: i.posteriorPath,
+    });
+    return { recorded: true, reward };
+  } catch (err) {
+    return { recorded: false, reward, reason: err && err.message ? err.message : String(err) };
+  }
+}
+
+module.exports = {
+  updateCalibration,
+  detectDrift,
+  riskReward,
+  recordRiskOutcome,
+  // Exposed for tests + sibling reuse.
+  computeStats,
+  normalizeRecord,
+  load,
+  save,
+  clamp01,
+  DRIFT,
+  WINDOW_SIZE,
+  SCHEMA_VERSION,
+  DEFAULT_CALIBRATION_PATH,
+};