codeharness 0.22.0 → 0.22.1

package/dist/index.js

@@ -1941,7 +1941,7 @@ async function scaffoldDocs(opts) {
 }
 
 // src/modules/infra/init-project.ts
-var HARNESS_VERSION = true ? "0.22.0" : "0.0.0-dev";
+var HARNESS_VERSION = true ? "0.22.1" : "0.0.0-dev";
 function failResult(opts, error) {
   return {
     status: "fail",
@@ -2808,6 +2808,7 @@ function Header({ info: info2 }) {
     info2.storyKey,
     " \u2014 ",
     info2.phase,
+    info2.elapsed ? ` | ${info2.elapsed}` : "",
     " | Sprint: ",
     info2.done,
     "/",
@@ -2858,6 +2859,51 @@ function truncateToWidth(text, maxWidth) {
   }
   return result;
 }
+var STATUS_SYMBOLS = {
+  "done": "\u2713",
+  "in-progress": "\u25C6",
+  "pending": "\u25CB",
+  "failed": "\u2717",
+  "blocked": "\u2715"
+};
+function StoryBreakdown({ stories }) {
+  if (stories.length === 0) return null;
+  const groups = {};
+  for (const s of stories) {
+    if (!groups[s.status]) groups[s.status] = [];
+    groups[s.status].push(s.key);
+  }
+  const fmt = (keys, status) => keys.map((k) => `${k} ${STATUS_SYMBOLS[status]}`).join("  ");
+  const parts = [];
+  if (groups["done"]?.length) {
+    parts.push(`Done: ${fmt(groups["done"], "done")}`);
+  }
+  if (groups["in-progress"]?.length) {
+    parts.push(`This: ${fmt(groups["in-progress"], "in-progress")}`);
+  }
+  if (groups["pending"]?.length) {
+    parts.push(`Next: ${fmt(groups["pending"], "pending")}`);
+  }
+  if (groups["failed"]?.length) {
+    parts.push(`Failed: ${fmt(groups["failed"], "failed")}`);
+  }
+  if (groups["blocked"]?.length) {
+    parts.push(`Blocked: ${fmt(groups["blocked"], "blocked")}`);
+  }
+  return /* @__PURE__ */ jsx(Text, { children: parts.join(" | ") });
+}
+var MESSAGE_PREFIX = {
+  ok: "[OK]",
+  warn: "[WARN]",
+  fail: "[FAIL]"
+};
+function StoryMessages({ messages }) {
+  if (messages.length === 0) return null;
+  return /* @__PURE__ */ jsx(Box, { flexDirection: "column", children: messages.map((msg, i) => /* @__PURE__ */ jsxs(Box, { flexDirection: "column", children: [
+    /* @__PURE__ */ jsx(Text, { children: `${MESSAGE_PREFIX[msg.type]} Story ${msg.key}: ${msg.message}` }),
+    msg.details?.map((d, j) => /* @__PURE__ */ jsx(Text, { children: `  \u2514 ${d}` }, j))
+  ] }, i)) });
+}
 function RetryNotice({ info: info2 }) {
   return /* @__PURE__ */ jsxs(Text, { children: [
     "\u23F3 API retry ",
@@ -2872,6 +2918,8 @@ function App({
 }) {
   return /* @__PURE__ */ jsxs(Box, { flexDirection: "column", children: [
     /* @__PURE__ */ jsx(Header, { info: state.sprintInfo }),
+    /* @__PURE__ */ jsx(StoryBreakdown, { stories: state.stories }),
+    /* @__PURE__ */ jsx(StoryMessages, { messages: state.messages }),
     /* @__PURE__ */ jsx(CompletedTools, { tools: state.completedTools }),
     state.activeTool && /* @__PURE__ */ jsx(ActiveTool, { name: state.activeTool.name }),
     state.lastThought && /* @__PURE__ */ jsx(LastThought, { text: state.lastThought }),
@@ -2886,6 +2934,10 @@ var noopHandle = {
   },
   updateSprintState() {
   },
+  updateStories() {
+  },
+  addMessage() {
+  },
   cleanup() {
   }
 };
@@ -2896,6 +2948,8 @@ function startRenderer(options) {
   }
   let state = {
     sprintInfo: options?.sprintState ?? null,
+    stories: [],
+    messages: [],
     completedTools: [],
     activeTool: null,
     activeToolArgs: "",
@@ -2978,7 +3032,17 @@ function startRenderer(options) {
     state.sprintInfo = sprintState ?? null;
     rerender();
   }
-  return { update, updateSprintState, cleanup };
+  function updateStories(stories) {
+    if (cleaned) return;
+    state.stories = [...stories];
+    rerender();
+  }
+  function addMessage(msg) {
+    if (cleaned) return;
+    state.messages = [...state.messages, msg];
+    rerender();
+  }
+  return { update, updateSprintState, updateStories, addMessage, cleanup };
 }
 
 // src/modules/sprint/state.ts
@@ -3864,21 +3928,8 @@ function clearRunProgress2() {
   return clearRunProgress();
 }
 
-// src/commands/run.ts
-var SPRINT_STATUS_REL = "_bmad-output/implementation-artifacts/sprint-status.yaml";
+// src/lib/run-helpers.ts
 var STORY_KEY_PATTERN = /^\d+-\d+-/;
-function resolveRalphPath() {
-  const currentFile = fileURLToPath2(import.meta.url);
-  const currentDir = dirname4(currentFile);
-  let root = dirname4(currentDir);
-  if (root.endsWith("/src") || root.endsWith("\\src")) {
-    root = dirname4(root);
-  }
-  return join13(root, "ralph", "ralph.sh");
-}
-function resolvePluginDir() {
-  return join13(process.cwd(), ".claude");
-}
 function countStories(statuses) {
   let total = 0;
   let ready = 0;
@@ -3919,6 +3970,108 @@ function buildSpawnArgs(opts) {
   }
   return args;
 }
+function formatElapsed(ms) {
+  const totalMinutes = Math.max(0, Math.floor(ms / 6e4));
+  const hours = Math.floor(totalMinutes / 60);
+  const minutes = totalMinutes % 60;
+  if (hours > 0) {
+    return `${hours}h${minutes}m`;
+  }
+  return `${totalMinutes}m`;
+}
+function mapSprintStatus(status) {
+  switch (status) {
+    case "done":
+      return "done";
+    case "in-progress":
+    case "review":
+    case "verifying":
+      return "in-progress";
+    case "backlog":
+    case "ready-for-dev":
+      return "pending";
+    case "failed":
+      return "failed";
+    case "blocked":
+    case "exhausted":
+      return "blocked";
+    default:
+      return "pending";
+  }
+}
+function mapSprintStatuses(statuses) {
+  const entries = [];
+  for (const [key, status] of Object.entries(statuses)) {
+    if (!STORY_KEY_PATTERN.test(key)) continue;
+    if (status === "optional") continue;
+    entries.push({ key, status: mapSprintStatus(status) });
+  }
+  return entries;
+}
+var ANSI_ESCAPE = /\x1b\[[0-9;]*m/g;
+var TIMESTAMP_PREFIX = /^\[[\d-]+\s[\d:]+\]\s*/;
+var SUCCESS_STORY = /\[SUCCESS\]\s+Story\s+([\w-]+):\s+DONE(.*)/;
+var WARN_STORY_RETRY = /\[WARN\]\s+Story\s+([\w-]+)\s+exceeded retry limit/;
+var WARN_STORY_RETRYING = /\[WARN\]\s+Story\s+([\w-]+)\s+.*retry\s+(\d+)\/(\d+)/;
+var ERROR_LINE = /\[ERROR\]\s+(.+)/;
+function parseRalphMessage(rawLine) {
+  const clean = rawLine.replace(ANSI_ESCAPE, "").replace(TIMESTAMP_PREFIX, "").trim();
+  if (clean.length === 0) return null;
+  const success = SUCCESS_STORY.exec(clean);
+  if (success) {
+    const key = success[1];
+    const rest = success[2].trim().replace(/^—\s*/, "");
+    return {
+      type: "ok",
+      key,
+      message: rest ? `DONE \u2014 ${rest}` : "DONE"
+    };
+  }
+  const retryExceeded = WARN_STORY_RETRY.exec(clean);
+  if (retryExceeded) {
+    return {
+      type: "fail",
+      key: retryExceeded[1],
+      message: "exceeded retry limit"
+    };
+  }
+  const retrying = WARN_STORY_RETRYING.exec(clean);
+  if (retrying) {
+    return {
+      type: "warn",
+      key: retrying[1],
+      message: `retry ${retrying[2]}/${retrying[3]}`
+    };
+  }
+  const errorMatch = ERROR_LINE.exec(clean);
+  if (errorMatch) {
+    const keyMatch = errorMatch[1].match(/Story\s+([\w-]+)/);
+    if (keyMatch) {
+      return {
+        type: "fail",
+        key: keyMatch[1],
+        message: errorMatch[1].trim()
+      };
+    }
+    return null;
+  }
+  return null;
+}
+
+// src/commands/run.ts
+var SPRINT_STATUS_REL = "_bmad-output/implementation-artifacts/sprint-status.yaml";
+function resolveRalphPath() {
+  const currentFile = fileURLToPath2(import.meta.url);
+  const currentDir = dirname4(currentFile);
+  let root = dirname4(currentDir);
+  if (root.endsWith("/src") || root.endsWith("\\src")) {
+    root = dirname4(root);
+  }
+  return join13(root, "ralph", "ralph.sh");
+}
+function resolvePluginDir() {
+  return join13(process.cwd(), ".claude");
+}
 function registerRunCommand(program) {
   program.command("run").description("Execute the autonomous coding loop").option("--max-iterations <n>", "Maximum loop iterations", "50").option("--timeout <seconds>", "Total loop timeout in seconds", "43200").option("--iteration-timeout <minutes>", "Per-iteration timeout in minutes", "30").option("--quiet", "Suppress terminal output (background mode)", false).option("--calls <n>", "Max API calls per hour", "100").option("--max-story-retries <n>", "Max retries per story before flagging", "10").option("--reset", "Clear retry counters, flagged stories, and circuit breaker before starting", false).action(async (options, cmd) => {
     const globalOpts = cmd.optsWithGlobals();
@@ -3999,6 +4152,7 @@ function registerRunCommand(program) {
     const quiet = options.quiet;
     const rendererHandle = startRenderer({ quiet });
     let sprintStateInterval = null;
+    const sessionStartTime = Date.now();
     try {
       const initialState = getSprintState2();
       if (initialState.success) {
@@ -4007,17 +4161,23 @@ function registerRunCommand(program) {
           storyKey: s.run.currentStory ?? "",
           phase: s.run.currentPhase ?? "",
           done: s.sprint.done,
-          total: s.sprint.total
+          total: s.sprint.total,
+          elapsed: formatElapsed(Date.now() - sessionStartTime)
         };
         rendererHandle.updateSprintState(sprintInfo);
       }
+      const initialStatuses = readSprintStatus(projectDir);
+      const initialStories = mapSprintStatuses(initialStatuses);
+      if (initialStories.length > 0) {
+        rendererHandle.updateStories(initialStories);
+      }
       const child = spawn("bash", args, {
         stdio: quiet ? "ignore" : ["inherit", "pipe", "pipe"],
         cwd: projectDir,
         env
       });
       if (!quiet && child.stdout && child.stderr) {
-        const makeLineHandler = () => {
+        const makeLineHandler = (opts) => {
           let partial = "";
           const decoder = new StringDecoder("utf8");
           return (data) => {
@@ -4030,11 +4190,17 @@ function registerRunCommand(program) {
               if (event) {
                 rendererHandle.update(event);
               }
+              if (opts?.parseRalph) {
+                const msg = parseRalphMessage(line);
+                if (msg) {
+                  rendererHandle.addMessage(msg);
+                }
+              }
             }
           };
         };
         child.stdout.on("data", makeLineHandler());
-        child.stderr.on("data", makeLineHandler());
+        child.stderr.on("data", makeLineHandler({ parseRalph: true }));
         sprintStateInterval = setInterval(() => {
           try {
             const stateResult = getSprintState2();
@@ -4044,10 +4210,14 @@ function registerRunCommand(program) {
                 storyKey: s.run.currentStory ?? "",
                 phase: s.run.currentPhase ?? "",
                 done: s.sprint.done,
-                total: s.sprint.total
+                total: s.sprint.total,
+                elapsed: formatElapsed(Date.now() - sessionStartTime)
               };
               rendererHandle.updateSprintState(sprintInfo);
             }
+            const currentStatuses = readSprintStatus(projectDir);
+            const storyEntries = mapSprintStatuses(currentStatuses);
+            rendererHandle.updateStories(storyEntries);
           } catch {
           }
         }, 5e3);
@@ -4121,7 +4291,7 @@ function registerRunCommand(program) {
 
 // src/commands/verify.ts
 import { existsSync as existsSync25, readFileSync as readFileSync23 } from "fs";
-import { join as join21 } from "path";
+import { join as join22 } from "path";
 
 // src/modules/verify/index.ts
 import { readFileSync as readFileSync22 } from "fs";
@@ -5174,6 +5344,121 @@ function parseObservabilityGaps(proofContent) {
 // src/modules/observability/analyzer.ts
 import { execFileSync as execFileSync8 } from "child_process";
 import { join as join16 } from "path";
+var DEFAULT_RULES_DIR = "patches/observability/";
+var DEFAULT_TIMEOUT = 6e4;
+var FUNCTION_NO_LOG_RULE = "function-no-debug-log";
+var CATCH_WITHOUT_LOGGING_RULE = "catch-without-logging";
+var ERROR_PATH_NO_LOG_RULE = "error-path-no-log";
+function matchesRule(gapType, ruleName) {
+  return gapType === ruleName || gapType.endsWith(`.${ruleName}`);
+}
+function analyze(projectDir, config) {
+  if (!projectDir || typeof projectDir !== "string") {
+    return fail2("projectDir is required and must be a non-empty string");
+  }
+  const tool = config?.tool ?? "semgrep";
+  if (tool !== "semgrep") {
+    return fail2(`Unsupported analyzer tool: ${tool}`);
+  }
+  if (!checkSemgrepInstalled()) {
+    return ok2({
+      tool: "semgrep",
+      gaps: [],
+      summary: {
+        totalFunctions: 0,
+        functionsWithLogs: 0,
+        errorHandlersWithoutLogs: 0,
+        coveragePercent: 0,
+        levelDistribution: {}
+      },
+      skipped: true,
+      skipReason: "static analysis skipped -- install semgrep"
+    });
+  }
+  const rulesDir = config?.rulesDir ?? DEFAULT_RULES_DIR;
+  const timeout = config?.timeout ?? DEFAULT_TIMEOUT;
+  const fullRulesDir = join16(projectDir, rulesDir);
+  const rawResult = runSemgrep(projectDir, fullRulesDir, timeout);
+  if (!rawResult.success) {
+    return fail2(rawResult.error);
+  }
+  const gaps = parseSemgrepOutput(rawResult.data);
+  const summaryOpts = config?.totalFunctions != null ? { totalFunctions: config.totalFunctions } : void 0;
+  const summary = computeSummary(gaps, summaryOpts);
+  return ok2({
+    tool: "semgrep",
+    gaps,
+    summary
+  });
+}
+function checkSemgrepInstalled() {
+  try {
+    execFileSync8("semgrep", ["--version"], {
+      encoding: "utf-8",
+      timeout: 5e3,
+      stdio: "pipe"
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function runSemgrep(projectDir, rulesDir, timeout = DEFAULT_TIMEOUT) {
+  try {
+    const stdout = execFileSync8(
+      "semgrep",
+      ["scan", "--config", rulesDir, "--json", projectDir],
+      { encoding: "utf-8", timeout, stdio: ["pipe", "pipe", "pipe"] }
+    );
+    const parsed = JSON.parse(stdout);
+    if (typeof parsed !== "object" || parsed === null || !Array.isArray(parsed.results)) {
+      return fail2("Semgrep scan returned invalid JSON: missing results array");
+    }
+    return ok2(parsed);
+  } catch (error) {
+    return fail2(`Semgrep scan failed: ${String(error)}`);
+  }
+}
+function parseSemgrepOutput(raw) {
+  if (!raw.results || !Array.isArray(raw.results)) {
+    return [];
+  }
+  return raw.results.map((r) => ({
+    file: r.path,
+    line: r.start.line,
+    type: r.check_id,
+    description: r.extra.message,
+    severity: normalizeSeverity(r.extra.severity)
+  }));
+}
+function computeSummary(gaps, opts) {
+  const functionsWithoutLogs = gaps.filter(
+    (g) => matchesRule(g.type, FUNCTION_NO_LOG_RULE)
+  ).length;
+  const errorHandlersWithoutLogs = gaps.filter(
+    (g) => matchesRule(g.type, CATCH_WITHOUT_LOGGING_RULE) || matchesRule(g.type, ERROR_PATH_NO_LOG_RULE)
+  ).length;
+  const totalFunctions = opts?.totalFunctions ?? functionsWithoutLogs;
+  const functionsWithLogs = totalFunctions - functionsWithoutLogs;
+  const coveragePercent = totalFunctions === 0 ? 100 : Math.round(functionsWithLogs / totalFunctions * 100 * 100) / 100;
+  const levelDistribution = {};
+  for (const gap2 of gaps) {
+    levelDistribution[gap2.severity] = (levelDistribution[gap2.severity] ?? 0) + 1;
+  }
+  return {
+    totalFunctions,
+    functionsWithLogs,
+    errorHandlersWithoutLogs,
+    coveragePercent,
+    levelDistribution
+  };
+}
+function normalizeSeverity(severity) {
+  const lower = severity.toLowerCase();
+  if (lower === "error") return "error";
+  if (lower === "warning") return "warning";
+  return "info";
+}
 
 // src/modules/observability/coverage.ts
 import { readFileSync as readFileSync18, writeFileSync as writeFileSync12, renameSync as renameSync2, existsSync as existsSync21 } from "fs";
@@ -5306,6 +5591,167 @@ function checkObservabilityCoverageGate(projectDir, overrides) {
   return ok2({ passed, staticResult, runtimeResult, gapSummary });
 }
 
+// src/modules/observability/runtime-validator.ts
+import { execSync as execSync3 } from "child_process";
+import { readdirSync as readdirSync4, statSync as statSync2 } from "fs";
+import { join as join19 } from "path";
+var DEFAULT_CONFIG = {
+  testCommand: "npm test",
+  otlpEndpoint: "http://localhost:4318",
+  queryEndpoint: "http://localhost:9428",
+  timeoutMs: 12e4
+};
+var HEALTH_TIMEOUT_MS = 3e3;
+var QUERY_TIMEOUT_MS = 3e4;
+async function validateRuntime(projectDir, config) {
+  if (!projectDir || typeof projectDir !== "string") {
+    return fail2("projectDir is required and must be a non-empty string");
+  }
+  const cfg = { ...DEFAULT_CONFIG, ...config };
+  if (/[;&|`$(){}!#]/.test(cfg.testCommand)) {
+    return fail2(`testCommand contains disallowed shell metacharacters: ${cfg.testCommand}`);
+  }
+  const healthy = await checkBackendHealth(cfg.queryEndpoint);
+  if (!healthy) {
+    const modules2 = discoverModules(projectDir);
+    const entries2 = modules2.map((m) => ({
+      moduleName: m,
+      telemetryDetected: false,
+      eventCount: 0
+    }));
+    return ok2({
+      entries: entries2,
+      totalModules: modules2.length,
+      modulesWithTelemetry: 0,
+      coveragePercent: 0,
+      skipped: true,
+      skipReason: "runtime validation skipped -- observability stack not available"
+    });
+  }
+  const startTime = (/* @__PURE__ */ new Date()).toISOString();
+  try {
+    execSync3(cfg.testCommand, {
+      cwd: projectDir,
+      timeout: cfg.timeoutMs,
+      env: {
+        ...process.env,
+        OTEL_EXPORTER_OTLP_ENDPOINT: cfg.otlpEndpoint
+      },
+      stdio: "pipe"
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return fail2(`Test command failed: ${msg}`);
+  }
+  const endTime = (/* @__PURE__ */ new Date()).toISOString();
+  const eventsResult = await queryTelemetryEvents(cfg.queryEndpoint, startTime, endTime);
+  if (!eventsResult.success) {
+    return fail2(eventsResult.error);
+  }
+  const modules = discoverModules(projectDir);
+  const entries = mapEventsToModules(eventsResult.data, projectDir, modules);
+  const modulesWithTelemetry = entries.filter((e) => e.telemetryDetected).length;
+  const totalModules = entries.length;
+  const coveragePercent = totalModules === 0 ? 0 : modulesWithTelemetry / totalModules * 100;
+  return ok2({
+    entries,
+    totalModules,
+    modulesWithTelemetry,
+    coveragePercent,
+    skipped: false
+  });
+}
+async function checkBackendHealth(queryEndpoint) {
+  try {
+    const response = await fetch(`${queryEndpoint}/health`, {
+      signal: AbortSignal.timeout(HEALTH_TIMEOUT_MS)
+    });
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
+async function queryTelemetryEvents(queryEndpoint, startTime, endTime) {
+  let url;
+  try {
+    url = new URL("/select/logsql/query", queryEndpoint);
+  } catch {
+    return fail2(`Invalid queryEndpoint URL: ${queryEndpoint}`);
+  }
+  url.searchParams.set("query", "*");
+  url.searchParams.set("start", startTime);
+  url.searchParams.set("end", endTime);
+  url.searchParams.set("limit", "1000");
+  try {
+    const response = await fetch(url.toString(), {
+      signal: AbortSignal.timeout(QUERY_TIMEOUT_MS)
+    });
+    if (!response.ok) {
+      return fail2(`VictoriaLogs returned ${response.status}`);
+    }
+    const text = await response.text();
+    const events = parseLogEvents(text);
+    return ok2(events);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return fail2(`Failed to query telemetry events: ${msg}`);
+  }
+}
+function mapEventsToModules(events, projectDir, modules) {
+  void projectDir;
+  const moduleList = modules ?? [];
+  const moduleCounts = /* @__PURE__ */ new Map();
+  for (const mod of moduleList) {
+    moduleCounts.set(mod, 0);
+  }
+  for (const event of events) {
+    for (const mod of moduleList) {
+      if (event.source.includes(mod) || event.message.includes(mod)) {
+        moduleCounts.set(mod, (moduleCounts.get(mod) ?? 0) + 1);
+      }
+    }
+  }
+  return moduleList.map((mod) => {
+    const count = moduleCounts.get(mod) ?? 0;
+    return {
+      moduleName: mod,
+      telemetryDetected: count > 0,
+      eventCount: count
+    };
+  });
+}
+function discoverModules(projectDir) {
+  const srcDir = join19(projectDir, "src");
+  try {
+    return readdirSync4(srcDir).filter((name) => {
+      try {
+        return statSync2(join19(srcDir, name)).isDirectory();
+      } catch {
+        return false;
+      }
+    });
+  } catch {
+    return [];
+  }
+}
+function parseLogEvents(text) {
+  if (!text.trim()) return [];
+  const lines = text.trim().split("\n");
+  const events = [];
+  for (const line of lines) {
+    try {
+      const raw = JSON.parse(line);
+      events.push({
+        timestamp: String(raw._time ?? raw.timestamp ?? ""),
+        message: String(raw._msg ?? raw.message ?? ""),
+        source: String(raw.source ?? raw._source ?? raw.service ?? "")
+      });
+    } catch {
+    }
+  }
+  return events;
+}
+
 // src/modules/verify/browser.ts
 import { execFileSync as execFileSync9 } from "child_process";
 import { existsSync as existsSync23, readFileSync as readFileSync20 } from "fs";
@@ -5945,9 +6391,9 @@ function getACById(id) {
 }
 
 // src/modules/verify/validation-runner.ts
-import { execSync as execSync3 } from "child_process";
+import { execSync as execSync4 } from "child_process";
 import { writeFileSync as writeFileSync14, mkdirSync as mkdirSync7 } from "fs";
-import { join as join19, dirname as dirname5 } from "path";
+import { join as join20, dirname as dirname5 } from "path";
 var MAX_VALIDATION_ATTEMPTS = 10;
 var AC_COMMAND_TIMEOUT_MS = 3e4;
 var VAL_KEY_PREFIX = "val-";
@@ -6019,7 +6465,7 @@ function executeValidationAC(ac) {
     }
     const startTime = Date.now();
     try {
-      const output = execSync3(ac.command, {
+      const output = execSync4(ac.command, {
         timeout: AC_COMMAND_TIMEOUT_MS,
         encoding: "utf-8",
         stdio: ["pipe", "pipe", "pipe"]
@@ -6056,7 +6502,7 @@ function executeValidationAC(ac) {
 function createFixStory(ac, error) {
   try {
     const storyKey = `val-fix-${ac.id}`;
-    const storyPath = join19(
+    const storyPath = join20(
       process.cwd(),
       "_bmad-output",
       "implementation-artifacts",
@@ -6159,7 +6605,7 @@ function processValidationResult(acId, result) {
 }
 
 // src/modules/dev/orchestrator.ts
-import { execFileSync as execFileSync10, execSync as execSync4 } from "child_process";
+import { execFileSync as execFileSync10, execSync as execSync5 } from "child_process";
 var DEFAULT_TIMEOUT_MS = 15e5;
 var MAX_OUTPUT_LINES = 200;
 var GIT_TIMEOUT_MS2 = 5e3;
@@ -6172,17 +6618,17 @@ function truncateOutput(output, maxLines) {
 }
 function captureFilesChanged() {
   try {
-    const unstaged = execSync4("git diff --name-only", {
+    const unstaged = execSync5("git diff --name-only", {
       timeout: GIT_TIMEOUT_MS2,
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"]
     }).trim();
-    const staged = execSync4("git diff --cached --name-only", {
+    const staged = execSync5("git diff --cached --name-only", {
       timeout: GIT_TIMEOUT_MS2,
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"]
     }).trim();
-    const untracked = execSync4("git ls-files --others --exclude-standard", {
+    const untracked = execSync5("git ls-files --others --exclude-standard", {
       timeout: GIT_TIMEOUT_MS2,
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"]
@@ -6426,8 +6872,8 @@ function runValidationCycle() {
 
 // src/modules/verify/env.ts
 import { execFileSync as execFileSync11 } from "child_process";
-import { existsSync as existsSync24, mkdirSync as mkdirSync8, readdirSync as readdirSync4, readFileSync as readFileSync21, cpSync, rmSync, statSync as statSync2 } from "fs";
-import { join as join20, basename as basename4 } from "path";
+import { existsSync as existsSync24, mkdirSync as mkdirSync8, readdirSync as readdirSync5, readFileSync as readFileSync21, cpSync, rmSync, statSync as statSync3 } from "fs";
+import { join as join21, basename as basename4 } from "path";
 import { createHash } from "crypto";
 var IMAGE_TAG = "codeharness-verify";
 var STORY_DIR = "_bmad-output/implementation-artifacts";
@@ -6440,7 +6886,7 @@ function isValidStoryKey(storyKey) {
   return /^[a-zA-Z0-9_-]+$/.test(storyKey);
 }
 function computeDistHash(projectDir) {
-  const distDir = join20(projectDir, "dist");
+  const distDir = join21(projectDir, "dist");
   if (!existsSync24(distDir)) return null;
   const hash = createHash("sha256");
   const files = collectFiles(distDir).sort();
@@ -6452,8 +6898,8 @@ function computeDistHash(projectDir) {
 }
 function collectFiles(dir) {
   const results = [];
-  for (const entry of readdirSync4(dir, { withFileTypes: true })) {
-    const fullPath = join20(dir, entry.name);
+  for (const entry of readdirSync5(dir, { withFileTypes: true })) {
+    const fullPath = join21(dir, entry.name);
     if (entry.isDirectory()) {
       results.push(...collectFiles(fullPath));
     } else {
@@ -6483,7 +6929,7 @@ function detectProjectType(projectDir) {
   const stack = detectStack(projectDir);
   if (stack === "nodejs") return "nodejs";
   if (stack === "python") return "python";
-  if (existsSync24(join20(projectDir, ".claude-plugin", "plugin.json"))) return "plugin";
+  if (existsSync24(join21(projectDir, ".claude-plugin", "plugin.json"))) return "plugin";
   return "generic";
 }
 function buildVerifyImage(options = {}) {
@@ -6527,12 +6973,12 @@ function buildNodeImage(projectDir) {
   const lastLine = packOutput.split("\n").pop()?.trim();
   if (!lastLine) throw new Error("npm pack produced no output \u2014 cannot determine tarball filename.");
   const tarballName = basename4(lastLine);
-  const tarballPath = join20("/tmp", tarballName);
-  const buildContext = join20("/tmp", `codeharness-verify-build-${Date.now()}`);
+  const tarballPath = join21("/tmp", tarballName);
+  const buildContext = join21("/tmp", `codeharness-verify-build-${Date.now()}`);
   mkdirSync8(buildContext, { recursive: true });
   try {
-    cpSync(tarballPath, join20(buildContext, tarballName));
-    cpSync(resolveDockerfileTemplate(projectDir), join20(buildContext, "Dockerfile"));
+    cpSync(tarballPath, join21(buildContext, tarballName));
+    cpSync(resolveDockerfileTemplate(projectDir), join21(buildContext, "Dockerfile"));
     execFileSync11("docker", ["build", "-t", IMAGE_TAG, "--build-arg", `TARBALL=${tarballName}`, "."], {
       cwd: buildContext,
       stdio: "pipe",
@@ -6544,17 +6990,17 @@ function buildNodeImage(projectDir) {
   }
 }
 function buildPythonImage(projectDir) {
-  const distDir = join20(projectDir, "dist");
-  const distFiles = readdirSync4(distDir).filter((f) => f.endsWith(".tar.gz") || f.endsWith(".whl"));
+  const distDir = join21(projectDir, "dist");
+  const distFiles = readdirSync5(distDir).filter((f) => f.endsWith(".tar.gz") || f.endsWith(".whl"));
   if (distFiles.length === 0) {
     throw new Error("No distribution files found in dist/. Run your build command first (e.g., python -m build).");
   }
   const distFile = distFiles.filter((f) => f.endsWith(".tar.gz"))[0] ?? distFiles[0];
-  const buildContext = join20("/tmp", `codeharness-verify-build-${Date.now()}`);
+  const buildContext = join21("/tmp", `codeharness-verify-build-${Date.now()}`);
   mkdirSync8(buildContext, { recursive: true });
   try {
-    cpSync(join20(distDir, distFile), join20(buildContext, distFile));
-    cpSync(resolveDockerfileTemplate(projectDir), join20(buildContext, "Dockerfile"));
+    cpSync(join21(distDir, distFile), join21(buildContext, distFile));
+    cpSync(resolveDockerfileTemplate(projectDir), join21(buildContext, "Dockerfile"));
     execFileSync11("docker", ["build", "-t", IMAGE_TAG, "--build-arg", `TARBALL=${distFile}`, "."], {
       cwd: buildContext,
       stdio: "pipe",
@@ -6569,19 +7015,19 @@ function prepareVerifyWorkspace(storyKey, projectDir) {
   if (!isValidStoryKey(storyKey)) {
     throw new Error(`Invalid story key: ${storyKey}. Keys must contain only alphanumeric characters, hyphens, and underscores.`);
   }
-  const storyFile = join20(root, STORY_DIR, `${storyKey}.md`);
+  const storyFile = join21(root, STORY_DIR, `${storyKey}.md`);
   if (!existsSync24(storyFile)) throw new Error(`Story file not found: ${storyFile}`);
   const workspace = `${TEMP_PREFIX}${storyKey}`;
   if (existsSync24(workspace)) rmSync(workspace, { recursive: true, force: true });
   mkdirSync8(workspace, { recursive: true });
-  cpSync(storyFile, join20(workspace, "story.md"));
-  const readmePath = join20(root, "README.md");
-  if (existsSync24(readmePath)) cpSync(readmePath, join20(workspace, "README.md"));
-  const docsDir = join20(root, "docs");
-  if (existsSync24(docsDir) && statSync2(docsDir).isDirectory()) {
-    cpSync(docsDir, join20(workspace, "docs"), { recursive: true });
-  }
-  mkdirSync8(join20(workspace, "verification"), { recursive: true });
+  cpSync(storyFile, join21(workspace, "story.md"));
+  const readmePath = join21(root, "README.md");
+  if (existsSync24(readmePath)) cpSync(readmePath, join21(workspace, "README.md"));
+  const docsDir = join21(root, "docs");
+  if (existsSync24(docsDir) && statSync3(docsDir).isDirectory()) {
+    cpSync(docsDir, join21(workspace, "docs"), { recursive: true });
+  }
+  mkdirSync8(join21(workspace, "verification"), { recursive: true });
   return workspace;
 }
 function checkVerifyEnv() {
@@ -6634,18 +7080,18 @@ function cleanupVerifyEnv(storyKey) {
   }
 }
 function buildPluginImage(projectDir) {
-  const buildContext = join20("/tmp", `codeharness-verify-build-${Date.now()}`);
+  const buildContext = join21("/tmp", `codeharness-verify-build-${Date.now()}`);
   mkdirSync8(buildContext, { recursive: true });
   try {
-    const pluginDir = join20(projectDir, ".claude-plugin");
-    cpSync(pluginDir, join20(buildContext, ".claude-plugin"), { recursive: true });
+    const pluginDir = join21(projectDir, ".claude-plugin");
+    cpSync(pluginDir, join21(buildContext, ".claude-plugin"), { recursive: true });
     for (const dir of ["commands", "hooks", "knowledge", "skills"]) {
-      const src = join20(projectDir, dir);
-      if (existsSync24(src) && statSync2(src).isDirectory()) {
-        cpSync(src, join20(buildContext, dir), { recursive: true });
+      const src = join21(projectDir, dir);
+      if (existsSync24(src) && statSync3(src).isDirectory()) {
+        cpSync(src, join21(buildContext, dir), { recursive: true });
       }
     }
-    cpSync(resolveDockerfileTemplate(projectDir, "generic"), join20(buildContext, "Dockerfile"));
+    cpSync(resolveDockerfileTemplate(projectDir, "generic"), join21(buildContext, "Dockerfile"));
     execFileSync11("docker", ["build", "-t", IMAGE_TAG, "."], {
       cwd: buildContext,
       stdio: "pipe",
@@ -6656,10 +7102,10 @@ function buildPluginImage(projectDir) {
   }
 }
 function buildGenericImage(projectDir) {
-  const buildContext = join20("/tmp", `codeharness-verify-build-${Date.now()}`);
+  const buildContext = join21("/tmp", `codeharness-verify-build-${Date.now()}`);
   mkdirSync8(buildContext, { recursive: true });
   try {
-    cpSync(resolveDockerfileTemplate(projectDir, "generic"), join20(buildContext, "Dockerfile"));
+    cpSync(resolveDockerfileTemplate(projectDir, "generic"), join21(buildContext, "Dockerfile"));
     execFileSync11("docker", ["build", "-t", IMAGE_TAG, "."], {
       cwd: buildContext,
       stdio: "pipe",
@@ -6671,10 +7117,10 @@ function buildGenericImage(projectDir) {
 }
 function resolveDockerfileTemplate(projectDir, variant) {
   const filename = variant === "generic" ? "Dockerfile.verify.generic" : "Dockerfile.verify";
-  const local = join20(projectDir, "templates", filename);
+  const local = join21(projectDir, "templates", filename);
   if (existsSync24(local)) return local;
   const pkgDir = new URL("../../", import.meta.url).pathname;
-  const pkg = join20(pkgDir, "templates", filename);
+  const pkg = join21(pkgDir, "templates", filename);
   if (existsSync24(pkg)) return pkg;
   throw new Error(`${filename} not found. Ensure templates/${filename} exists.`);
 }
@@ -6703,6 +7149,17 @@ function getImageSize(tag) {
   }
 }
 
+// src/modules/verify/index.ts
+function parseProof(path) {
+  try {
+    const quality = validateProofQuality(path);
+    return ok2(quality);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return fail2(message);
+  }
+}
+
 // src/commands/verify.ts
 var STORY_DIR2 = "_bmad-output/implementation-artifacts";
 function isValidStoryId(storyId) {
@@ -6739,7 +7196,7 @@ function verifyRetro(opts, isJson, root) {
     return;
   }
   const retroFile = `epic-${epicNum}-retrospective.md`;
-  const retroPath = join21(root, STORY_DIR2, retroFile);
+  const retroPath = join22(root, STORY_DIR2, retroFile);
   if (!existsSync25(retroPath)) {
     if (isJson) {
       jsonOutput({ status: "fail", epic: epicNum, retroFile, message: `${retroFile} not found` });
@@ -6757,7 +7214,7 @@ function verifyRetro(opts, isJson, root) {
     warn(`Failed to update sprint status: ${message}`);
   }
   if (isJson) {
-    jsonOutput({ status: "ok", epic: epicNum, retroFile: join21(STORY_DIR2, retroFile) });
+    jsonOutput({ status: "ok", epic: epicNum, retroFile: join22(STORY_DIR2, retroFile) });
   } else {
     ok(`Epic ${epicNum} retrospective: marked done`);
   }
@@ -6768,7 +7225,7 @@ function verifyStory(storyId, isJson, root) {
     process.exitCode = 1;
     return;
   }
-  const readmePath = join21(root, "README.md");
+  const readmePath = join22(root, "README.md");
   if (!existsSync25(readmePath)) {
     if (isJson) {
       jsonOutput({ status: "fail", message: "No README.md found \u2014 verification requires user documentation" });
@@ -6778,7 +7235,7 @@ function verifyStory(storyId, isJson, root) {
     process.exitCode = 1;
     return;
   }
-  const storyFilePath = join21(root, STORY_DIR2, `${storyId}.md`);
+  const storyFilePath = join22(root, STORY_DIR2, `${storyId}.md`);
   if (!existsSync25(storyFilePath)) {
     fail(`Story file not found: ${storyFilePath}`, { json: isJson });
     process.exitCode = 1;
@@ -6819,7 +7276,7 @@ function verifyStory(storyId, isJson, root) {
     return;
   }
   const storyTitle = extractStoryTitle(storyFilePath);
-  const expectedProofPath = join21(root, "verification", `${storyId}-proof.md`);
+  const expectedProofPath = join22(root, "verification", `${storyId}-proof.md`);
   const proofPath = existsSync25(expectedProofPath) ? expectedProofPath : createProofDocument(storyId, storyTitle, acs, root);
   const proofQuality = validateProofQuality(proofPath);
   if (!proofQuality.passed) {
@@ -6935,13 +7392,13 @@ function extractStoryTitle(filePath) {
 
 // src/lib/onboard-checks.ts
 import { existsSync as existsSync27 } from "fs";
-import { join as join23, dirname as dirname6 } from "path";
+import { join as join24, dirname as dirname6 } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
 
 // src/lib/coverage.ts
-import { execSync as execSync5 } from "child_process";
+import { execSync as execSync6 } from "child_process";
 import { existsSync as existsSync26, readFileSync as readFileSync24 } from "fs";
-import { join as join22 } from "path";
+import { join as join23 } from "path";
 function detectCoverageTool(dir) {
   const baseDir = dir ?? process.cwd();
   const stateHint = getStateToolHint(baseDir);
@@ -6964,8 +7421,8 @@ function getStateToolHint(dir) {
   }
 }
 function detectNodeCoverageTool(dir, stateHint) {
-  const hasVitestConfig = existsSync26(join22(dir, "vitest.config.ts")) || existsSync26(join22(dir, "vitest.config.js"));
-  const pkgPath = join22(dir, "package.json");
+  const hasVitestConfig = existsSync26(join23(dir, "vitest.config.ts")) || existsSync26(join23(dir, "vitest.config.js"));
+  const pkgPath = join23(dir, "package.json");
   let hasVitestCoverageV8 = false;
   let hasVitestCoverageIstanbul = false;
   let hasC8 = false;
@@ -7026,7 +7483,7 @@ function getNodeTestCommand(scripts, runner) {
   return "npm test";
 }
 function detectPythonCoverageTool(dir) {
-  const reqPath = join22(dir, "requirements.txt");
+  const reqPath = join23(dir, "requirements.txt");
   if (existsSync26(reqPath)) {
     try {
       const content = readFileSync24(reqPath, "utf-8");
@@ -7040,7 +7497,7 @@ function detectPythonCoverageTool(dir) {
     } catch {
     }
   }
-  const pyprojectPath = join22(dir, "pyproject.toml");
+  const pyprojectPath = join23(dir, "pyproject.toml");
   if (existsSync26(pyprojectPath)) {
     try {
       const content = readFileSync24(pyprojectPath, "utf-8");
@@ -7073,7 +7530,7 @@ function runCoverage(dir) {
   let rawOutput = "";
   let testsPassed = true;
   try {
-    rawOutput = execSync5(toolInfo.runCommand, {
+    rawOutput = execSync6(toolInfo.runCommand, {
       cwd: baseDir,
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"],
@@ -7133,7 +7590,7 @@ function parseVitestCoverage(dir) {
   }
 }
 function parsePythonCoverage(dir) {
-  const reportPath = join22(dir, "coverage.json");
+  const reportPath = join23(dir, "coverage.json");
   if (!existsSync26(reportPath)) {
     warn("Coverage report not found at coverage.json");
     return 0;
@@ -7270,8 +7727,8 @@ function checkPerFileCoverage(floor, dir) {
 }
 function findCoverageSummary(dir) {
   const candidates = [
-    join22(dir, "coverage", "coverage-summary.json"),
-    join22(dir, "src", "coverage", "coverage-summary.json")
+    join23(dir, "coverage", "coverage-summary.json"),
+    join23(dir, "src", "coverage", "coverage-summary.json")
   ];
   for (const p of candidates) {
     if (existsSync26(p)) return p;
@@ -7307,7 +7764,7 @@ function checkBmadInstalled(dir) {
 function checkHooksRegistered(dir) {
   const __filename = fileURLToPath3(import.meta.url);
   const __dirname2 = dirname6(__filename);
-  const hooksPath = join23(__dirname2, "..", "..", "hooks", "hooks.json");
+  const hooksPath = join24(__dirname2, "..", "..", "hooks", "hooks.json");
   return { ok: existsSync27(hooksPath) };
 }
 function runPreconditions(dir) {
@@ -7348,7 +7805,7 @@ function findVerificationGaps(dir) {
   for (const [key, status] of Object.entries(statuses)) {
     if (status !== "done") continue;
     if (!STORY_KEY_PATTERN2.test(key)) continue;
-    const proofPath = join23(root, "verification", `${key}-proof.md`);
+    const proofPath = join24(root, "verification", `${key}-proof.md`);
     if (!existsSync27(proofPath)) {
       unverified.push(key);
     }
@@ -8061,16 +8518,16 @@ function getBeadsData() {
 }
 
 // src/commands/onboard.ts
-import { join as join27 } from "path";
+import { join as join28 } from "path";
 
 // src/lib/scanner.ts
 import {
   existsSync as existsSync28,
-  readdirSync as readdirSync5,
+  readdirSync as readdirSync6,
   readFileSync as readFileSync25,
-  statSync as statSync3
+  statSync as statSync4
 } from "fs";
-import { join as join24, relative as relative2 } from "path";
+import { join as join25, relative as relative2 } from "path";
 var SOURCE_EXTENSIONS2 = /* @__PURE__ */ new Set([".ts", ".js", ".py"]);
 var DEFAULT_MIN_MODULE_SIZE = 3;
 function getExtension2(filename) {
@@ -8088,17 +8545,17 @@ function countSourceFiles(dir) {
   function walk(current) {
     let entries;
     try {
-      entries = readdirSync5(current);
+      entries = readdirSync6(current);
     } catch {
       return;
     }
     for (const entry of entries) {
       if (isSkippedDir(entry)) continue;
       if (entry.startsWith(".") && current !== dir) continue;
-      const fullPath = join24(current, entry);
+      const fullPath = join25(current, entry);
       let stat;
       try {
-        stat = statSync3(fullPath);
+        stat = statSync4(fullPath);
       } catch {
         continue;
       }
@@ -8118,22 +8575,22 @@ function countSourceFiles(dir) {
   return count;
 }
 function countModuleFiles(modulePath, rootDir) {
-  const fullModulePath = join24(rootDir, modulePath);
+  const fullModulePath = join25(rootDir, modulePath);
   let sourceFiles = 0;
   let testFiles = 0;
   function walk(current) {
     let entries;
     try {
-      entries = readdirSync5(current);
+      entries = readdirSync6(current);
     } catch {
       return;
     }
     for (const entry of entries) {
       if (isSkippedDir(entry)) continue;
-      const fullPath = join24(current, entry);
+      const fullPath = join25(current, entry);
       let stat;
       try {
-        stat = statSync3(fullPath);
+        stat = statSync4(fullPath);
       } catch {
         continue;
       }
@@ -8155,7 +8612,7 @@ function countModuleFiles(modulePath, rootDir) {
   return { sourceFiles, testFiles };
 }
 function detectArtifacts(dir) {
-  const bmadPath = join24(dir, "_bmad");
+  const bmadPath = join25(dir, "_bmad");
   const hasBmad = existsSync28(bmadPath);
   return {
     hasBmad,
@@ -8238,7 +8695,7 @@ function readPerFileCoverage(dir, format) {
   return null;
 }
 function readVitestPerFileCoverage(dir) {
-  const reportPath = join24(dir, "coverage", "coverage-summary.json");
+  const reportPath = join25(dir, "coverage", "coverage-summary.json");
   if (!existsSync28(reportPath)) return null;
   try {
     const report = JSON.parse(readFileSync25(reportPath, "utf-8"));
@@ -8253,7 +8710,7 @@ function readVitestPerFileCoverage(dir) {
   }
 }
 function readPythonPerFileCoverage(dir) {
-  const reportPath = join24(dir, "coverage.json");
+  const reportPath = join25(dir, "coverage.json");
   if (!existsSync28(reportPath)) return null;
   try {
     const report = JSON.parse(readFileSync25(reportPath, "utf-8"));
@@ -8272,12 +8729,12 @@ function auditDocumentation(dir) {
   const root = dir ?? process.cwd();
   const documents = [];
   for (const docName of AUDIT_DOCUMENTS) {
-    const docPath = join24(root, docName);
+    const docPath = join25(root, docName);
     if (!existsSync28(docPath)) {
       documents.push({ name: docName, grade: "missing", path: null });
       continue;
     }
-    const srcDir = join24(root, "src");
+    const srcDir = join25(root, "src");
     const codeDir = existsSync28(srcDir) ? srcDir : root;
     const stale = isDocStale(docPath, codeDir);
     documents.push({
@@ -8286,10 +8743,10 @@ function auditDocumentation(dir) {
       path: docName
     });
   }
-  const docsDir = join24(root, "docs");
+  const docsDir = join25(root, "docs");
   if (existsSync28(docsDir)) {
     try {
-      const stat = statSync3(docsDir);
+      const stat = statSync4(docsDir);
       if (stat.isDirectory()) {
         documents.push({ name: "docs/", grade: "present", path: "docs/" });
       }
@@ -8299,9 +8756,9 @@ function auditDocumentation(dir) {
   } else {
     documents.push({ name: "docs/", grade: "missing", path: null });
   }
-  const indexPath = join24(root, "docs", "index.md");
+  const indexPath = join25(root, "docs", "index.md");
   if (existsSync28(indexPath)) {
-    const srcDir = join24(root, "src");
+    const srcDir = join25(root, "src");
     const indexCodeDir = existsSync28(srcDir) ? srcDir : root;
     const indexStale = isDocStale(indexPath, indexCodeDir);
     documents.push({
@@ -8320,7 +8777,7 @@ function auditDocumentation(dir) {
 // src/lib/epic-generator.ts
 import { createInterface } from "readline";
 import { existsSync as existsSync29, mkdirSync as mkdirSync9, writeFileSync as writeFileSync15 } from "fs";
-import { dirname as dirname7, join as join25 } from "path";
+import { dirname as dirname7, join as join26 } from "path";
 var PRIORITY_BY_TYPE = {
   observability: 1,
   coverage: 2,
@@ -8358,7 +8815,7 @@ function generateOnboardingEpic(scan, coverage, audit, rootDir) {
     storyNum++;
   }
   for (const mod of scan.modules) {
-    const agentsPath = join25(root, mod.path, "AGENTS.md");
+    const agentsPath = join26(root, mod.path, "AGENTS.md");
     if (!existsSync29(agentsPath)) {
       stories.push({
         key: `0.${storyNum}`,
@@ -8558,23 +9015,23 @@ function getGapIdFromTitle(title) {
 
 // src/lib/scan-cache.ts
 import { existsSync as existsSync30, mkdirSync as mkdirSync10, readFileSync as readFileSync26, writeFileSync as writeFileSync16 } from "fs";
-import { join as join26 } from "path";
+import { join as join27 } from "path";
 var CACHE_DIR = ".harness";
 var CACHE_FILE = "last-onboard-scan.json";
 var DEFAULT_MAX_AGE_MS = 864e5;
 function saveScanCache(entry, dir) {
   try {
     const root = dir ?? process.cwd();
-    const cacheDir = join26(root, CACHE_DIR);
+    const cacheDir = join27(root, CACHE_DIR);
     mkdirSync10(cacheDir, { recursive: true });
-    const cachePath = join26(cacheDir, CACHE_FILE);
+    const cachePath = join27(cacheDir, CACHE_FILE);
     writeFileSync16(cachePath, JSON.stringify(entry, null, 2), "utf-8");
   } catch {
   }
 }
 function loadScanCache(dir) {
   const root = dir ?? process.cwd();
-  const cachePath = join26(root, CACHE_DIR, CACHE_FILE);
+  const cachePath = join27(root, CACHE_DIR, CACHE_FILE);
   if (!existsSync30(cachePath)) {
     return null;
   }
@@ -8752,7 +9209,7 @@ function registerOnboardCommand(program) {
     }
     coverage = lastCoverageResult ?? runCoverageAnalysis(scan);
     audit = lastAuditResult ?? runAudit();
-    const epicPath = join27(process.cwd(), "ralph", "onboarding-epic.md");
+    const epicPath = join28(process.cwd(), "ralph", "onboarding-epic.md");
     const epic = generateOnboardingEpic(scan, coverage, audit);
     mergeExtendedGaps(epic);
     if (!isFull) {
@@ -8825,7 +9282,7 @@ function registerOnboardCommand(program) {
       coverage,
       audit
     });
-    const epicPath = join27(process.cwd(), "ralph", "onboarding-epic.md");
+    const epicPath = join28(process.cwd(), "ralph", "onboarding-epic.md");
     const epic = generateOnboardingEpic(scan, coverage, audit);
     mergeExtendedGaps(epic);
     if (!isFull) {
@@ -8934,7 +9391,7 @@ function printEpicOutput(epic) {
 
 // src/commands/teardown.ts
 import { existsSync as existsSync31, unlinkSync as unlinkSync2, readFileSync as readFileSync27, writeFileSync as writeFileSync17, rmSync as rmSync2 } from "fs";
-import { join as join28 } from "path";
+import { join as join29 } from "path";
 function buildDefaultResult() {
   return {
     status: "ok",
@@ -9037,7 +9494,7 @@ function registerTeardownCommand(program) {
           info("Docker stack: not running, skipping");
         }
       }
-      const composeFilePath = join28(projectDir, composeFile);
+      const composeFilePath = join29(projectDir, composeFile);
       if (existsSync31(composeFilePath)) {
         unlinkSync2(composeFilePath);
         result.removed.push(composeFile);
@@ -9045,7 +9502,7 @@ function registerTeardownCommand(program) {
           ok(`Removed: ${composeFile}`);
         }
       }
-      const otelConfigPath = join28(projectDir, "otel-collector-config.yaml");
+      const otelConfigPath = join29(projectDir, "otel-collector-config.yaml");
       if (existsSync31(otelConfigPath)) {
         unlinkSync2(otelConfigPath);
         result.removed.push("otel-collector-config.yaml");
@@ -9056,7 +9513,7 @@ function registerTeardownCommand(program) {
     }
     let patchesRemoved = 0;
     for (const [patchName, relativePath] of Object.entries(PATCH_TARGETS)) {
-      const filePath = join28(projectDir, "_bmad", relativePath);
+      const filePath = join29(projectDir, "_bmad", relativePath);
       if (!existsSync31(filePath)) {
         continue;
       }
@@ -9077,7 +9534,7 @@ function registerTeardownCommand(program) {
       }
     }
     if (state.otlp?.enabled && state.stack === "nodejs") {
-      const pkgPath = join28(projectDir, "package.json");
+      const pkgPath = join29(projectDir, "package.json");
       if (existsSync31(pkgPath)) {
         try {
           const raw = readFileSync27(pkgPath, "utf-8");
@@ -9120,7 +9577,7 @@ function registerTeardownCommand(program) {
         }
       }
     }
-    const harnessDir = join28(projectDir, ".harness");
+    const harnessDir = join29(projectDir, ".harness");
     if (existsSync31(harnessDir)) {
       rmSync2(harnessDir, { recursive: true, force: true });
       result.removed.push(".harness/");
@@ -9874,7 +10331,7 @@ function registerQueryCommand(program) {
 
 // src/commands/retro-import.ts
 import { existsSync as existsSync32, readFileSync as readFileSync28 } from "fs";
-import { join as join29 } from "path";
+import { join as join30 } from "path";
 
 // src/lib/retro-parser.ts
 var KNOWN_TOOLS = ["showboat", "ralph", "beads", "bmad"];
@@ -10043,7 +10500,7 @@ function registerRetroImportCommand(program) {
       return;
     }
     const retroFile = `epic-${epicNum}-retrospective.md`;
-    const retroPath = join29(root, STORY_DIR3, retroFile);
+    const retroPath = join30(root, STORY_DIR3, retroFile);
     if (!existsSync32(retroPath)) {
       fail(`Retro file not found: ${retroFile}`, { json: isJson });
       process.exitCode = 1;
@@ -10432,19 +10889,19 @@ function registerVerifyEnvCommand(program) {
 }
 
 // src/commands/retry.ts
-import { join as join31 } from "path";
+import { join as join32 } from "path";
 
 // src/lib/retry-state.ts
 import { existsSync as existsSync33, readFileSync as readFileSync29, writeFileSync as writeFileSync18 } from "fs";
-import { join as join30 } from "path";
+import { join as join31 } from "path";
 var RETRIES_FILE = ".story_retries";
 var FLAGGED_FILE = ".flagged_stories";
 var LINE_PATTERN = /^([^=]+)=(\d+)$/;
 function retriesPath(dir) {
-  return join30(dir, RETRIES_FILE);
+  return join31(dir, RETRIES_FILE);
 }
 function flaggedPath(dir) {
-  return join30(dir, FLAGGED_FILE);
+  return join31(dir, FLAGGED_FILE);
 }
 function readRetries(dir) {
   const filePath = retriesPath(dir);
@@ -10516,7 +10973,7 @@ function registerRetryCommand(program) {
   program.command("retry").description("Manage retry state for stories").option("--reset", "Clear retry counters and flagged stories").option("--story <key>", "Target a specific story key (used with --reset or --status)").option("--status", "Show retry status for all stories").action((_options, cmd) => {
     const opts = cmd.optsWithGlobals();
     const isJson = opts.json === true;
-    const dir = join31(process.cwd(), RALPH_SUBDIR);
+    const dir = join32(process.cwd(), RALPH_SUBDIR);
     if (opts.story && !isValidStoryKey3(opts.story)) {
       if (isJson) {
         jsonOutput({ status: "fail", message: `Invalid story key: ${opts.story}` });
@@ -10914,8 +11371,435 @@ function registerObservabilityGateCommand(program) {
   });
 }
 
+// src/modules/audit/dimensions.ts
+import { existsSync as existsSync34, readFileSync as readFileSync30, readdirSync as readdirSync7 } from "fs";
+import { join as join33 } from "path";
+function gap(dimension, description, suggestedFix) {
+  return { dimension, description, suggestedFix };
+}
+function dimOk(name, status, metric, gaps = []) {
+  return ok2({ name, status, metric, gaps });
+}
+function dimCatch(name, err) {
+  const msg = err instanceof Error ? err.message : String(err);
+  return dimOk(name, "warn", "error", [gap(name, `${name} check failed: ${msg}`, `Check ${name} configuration`)]);
+}
+function worstStatus(...statuses) {
+  if (statuses.includes("fail")) return "fail";
+  if (statuses.includes("warn")) return "warn";
+  return "pass";
+}
+async function checkObservability(projectDir) {
+  try {
+    const gaps = [];
+    let sStatus = "pass", sMetric = "";
+    const sr = analyze(projectDir);
+    if (isOk(sr)) {
+      const d = sr.data;
+      if (d.skipped) {
+        sStatus = "warn";
+        sMetric = `static: skipped (${d.skipReason ?? "unknown"})`;
+        gaps.push(gap("observability", `Static analysis skipped: ${d.skipReason ?? "Semgrep not installed"}`, "Install Semgrep: pip install semgrep"));
+      } else {
+        const n = d.gaps.length;
+        sMetric = `static: ${n} gap${n !== 1 ? "s" : ""}`;
+        if (n > 0) {
+          sStatus = "warn";
+          for (const g of d.gaps) gaps.push(gap("observability", `${g.file}:${g.line} \u2014 ${g.message}`, g.fix ?? "Add observability instrumentation"));
+        }
+      }
+    } else {
+      sStatus = "warn";
+      sMetric = "static: skipped (analysis failed)";
+      gaps.push(gap("observability", `Static analysis failed: ${sr.error}`, "Check Semgrep installation and rules configuration"));
+    }
+    let rStatus = "pass", rMetric = "";
+    try {
+      const rr = await validateRuntime(projectDir);
+      if (isOk(rr)) {
+        const d = rr.data;
+        if (d.skipped) {
+          rStatus = "warn";
+          rMetric = `runtime: skipped (${d.skipReason ?? "unknown"})`;
+          gaps.push(gap("observability", `Runtime validation skipped: ${d.skipReason ?? "backend unreachable"}`, "Start the observability stack: codeharness stack up"));
+        } else {
+          rMetric = `runtime: ${d.coveragePercent}%`;
+          if (d.coveragePercent < 50) {
+            rStatus = "warn";
+            gaps.push(gap("observability", `Runtime coverage low: ${d.coveragePercent}%`, "Add telemetry instrumentation to more modules"));
+          }
+        }
+      } else {
+        rStatus = "warn";
+        rMetric = "runtime: skipped (validation failed)";
+        gaps.push(gap("observability", `Runtime validation failed: ${rr.error}`, "Ensure observability backend is running"));
+      }
+    } catch {
+      rStatus = "warn";
+      rMetric = "runtime: skipped (error)";
+      gaps.push(gap("observability", "Runtime validation threw an unexpected error", "Check observability stack health"));
+    }
+    return dimOk("observability", worstStatus(sStatus, rStatus), `${sMetric}, ${rMetric}`, gaps);
+  } catch (err) {
+    return dimCatch("observability", err);
+  }
+}
+function checkTesting(projectDir) {
+  try {
+    const r = checkOnlyCoverage(projectDir);
+    if (!r.success) return dimOk("testing", "warn", "no coverage data", [gap("testing", "No coverage tool detected or coverage data unavailable", "Run tests with coverage: npm run test:coverage")]);
+    const pct = r.coveragePercent;
+    const gaps = [];
+    let status = "pass";
+    if (pct < 50) {
+      status = "fail";
+      gaps.push(gap("testing", `Test coverage critically low: ${pct}%`, "Add unit tests to increase coverage above 50%"));
+    } else if (pct < 80) {
+      status = "warn";
+      gaps.push(gap("testing", `Test coverage below target: ${pct}%`, "Add tests to reach 80% coverage target"));
+    }
+    return dimOk("testing", status, `${pct}%`, gaps);
+  } catch (err) {
+    return dimCatch("testing", err);
+  }
+}
+function checkDocumentation(projectDir) {
+  try {
+    const report = scanDocHealth(projectDir);
+    const gaps = [];
+    const { fresh, stale, missing } = report.summary;
+    let status = "pass";
+    if (missing > 0) {
+      status = "fail";
+      for (const doc of report.documents) if (doc.grade === "missing") gaps.push(gap("documentation", `Missing: ${doc.path} \u2014 ${doc.reason}`, `Create ${doc.path}`));
+    }
+    if (stale > 0) {
+      if (status !== "fail") status = "warn";
+      for (const doc of report.documents) if (doc.grade === "stale") gaps.push(gap("documentation", `Stale: ${doc.path} \u2014 ${doc.reason}`, `Update ${doc.path} to reflect current code`));
+    }
+    return dimOk("documentation", status, `${fresh} fresh, ${stale} stale, ${missing} missing`, gaps);
+  } catch (err) {
+    return dimCatch("documentation", err);
+  }
+}
+function checkVerification(projectDir) {
+  try {
+    const gaps = [];
+    const sprintPath = join33(projectDir, "_bmad-output", "implementation-artifacts", "sprint-status.yaml");
+    if (!existsSync34(sprintPath)) return dimOk("verification", "warn", "no sprint data", [gap("verification", "No sprint-status.yaml found", "Run sprint planning to create sprint status")]);
+    const vDir = join33(projectDir, "verification");
+    let proofCount = 0, totalChecked = 0;
+    if (existsSync34(vDir)) {
+      for (const file of readdirSafe(vDir)) {
+        if (!file.endsWith("-proof.md")) continue;
+        totalChecked++;
+        const r = parseProof(join33(vDir, file));
+        if (isOk(r) && r.data.passed) {
+          proofCount++;
+        } else {
+          gaps.push(gap("verification", `Story ${file.replace("-proof.md", "")} proof incomplete or failing`, `Run codeharness verify ${file.replace("-proof.md", "")}`));
+        }
+      }
+    }
+    let status = "pass";
+    if (totalChecked === 0) {
+      status = "warn";
+      gaps.push(gap("verification", "No verification proofs found", "Run codeharness verify for completed stories"));
+    } else if (proofCount < totalChecked) {
+      status = "warn";
+    }
+    return dimOk("verification", status, totalChecked > 0 ? `${proofCount}/${totalChecked} verified` : "no proofs", gaps);
+  } catch (err) {
+    return dimCatch("verification", err);
+  }
+}
+function checkInfrastructure(projectDir) {
+  try {
+    const dfPath = join33(projectDir, "Dockerfile");
+    if (!existsSync34(dfPath)) return dimOk("infrastructure", "fail", "no Dockerfile", [gap("infrastructure", "No Dockerfile found", "Create a Dockerfile for containerized deployment")]);
+    let content;
+    try {
+      content = readFileSync30(dfPath, "utf-8");
+    } catch {
+      return dimOk("infrastructure", "warn", "Dockerfile unreadable", [gap("infrastructure", "Dockerfile exists but could not be read", "Check Dockerfile permissions")]);
+    }
+    const fromLines = content.split("\n").filter((l) => /^\s*FROM\s+/i.test(l));
+    if (fromLines.length === 0) return dimOk("infrastructure", "fail", "invalid Dockerfile", [gap("infrastructure", "Dockerfile has no FROM instruction", "Add a FROM instruction with a pinned base image")]);
+    const gaps = [];
+    let hasUnpinned = false;
+    for (const line of fromLines) {
+      const ref = line.replace(/^\s*FROM\s+/i, "").split(/\s+/)[0];
+      if (ref.endsWith(":latest")) {
+        hasUnpinned = true;
+        gaps.push(gap("infrastructure", `Unpinned base image: ${ref}`, `Pin ${ref} to a specific version tag`));
+      } else if (!ref.includes(":") && !ref.includes("@")) {
+        hasUnpinned = true;
+        gaps.push(gap("infrastructure", `Unpinned base image (no tag): ${ref}`, `Pin ${ref} to a specific version tag (e.g., ${ref}:22-slim)`));
+      }
+    }
+    const status = hasUnpinned ? "warn" : "pass";
+    const metric = hasUnpinned ? `Dockerfile exists (${gaps.length} issue${gaps.length !== 1 ? "s" : ""})` : "Dockerfile valid";
+    return dimOk("infrastructure", status, metric, gaps);
+  } catch (err) {
+    return dimCatch("infrastructure", err);
+  }
+}
+function readdirSafe(dir) {
+  try {
+    return readdirSync7(dir);
+  } catch {
+    return [];
+  }
+}
+
+// src/modules/audit/report.ts
+var STATUS_PREFIX = {
+  pass: "[OK]",
+  fail: "[FAIL]",
+  warn: "[WARN]"
+};
+function formatAuditHuman(result) {
+  const lines = [];
+  for (const dimension of Object.values(result.dimensions)) {
+    const prefix = STATUS_PREFIX[dimension.status] ?? "[WARN]";
+    lines.push(`${prefix} ${dimension.name}: ${dimension.metric}`);
+    for (const gap2 of dimension.gaps) {
+      lines.push(`  [WARN] ${gap2.description} -- fix: ${gap2.suggestedFix}`);
+    }
+  }
+  const overallPrefix = STATUS_PREFIX[result.overallStatus] ?? "[WARN]";
+  lines.push("");
+  lines.push(
+    `${overallPrefix} Audit complete: ${result.gapCount} gap${result.gapCount !== 1 ? "s" : ""} found (${result.durationMs}ms)`
+  );
+  return lines;
+}
+function formatAuditJson(result) {
+  return result;
+}
+
+// src/modules/audit/fix-generator.ts
+import { existsSync as existsSync35, writeFileSync as writeFileSync19, mkdirSync as mkdirSync11 } from "fs";
+import { join as join34, dirname as dirname8 } from "path";
+function buildStoryKey(gap2, index) {
+  const safeDimension = gap2.dimension.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "");
+  return `audit-fix-${safeDimension}-${index}`;
+}
+function buildStoryMarkdown(gap2, key) {
+  return [
+    `# Fix: ${gap2.dimension} \u2014 ${gap2.description}`,
+    "",
+    "Status: backlog",
+    "",
+    "## Story",
+    "",
+    `As an operator, I need ${gap2.description} fixed so that audit compliance improves.`,
+    "",
+    "## Acceptance Criteria",
+    "",
+    `1. **Given** ${gap2.description}, **When** the fix is applied, **Then** ${gap2.suggestedFix}.`,
+    "",
+    "## Dev Notes",
+    "",
+    "This is an auto-generated fix story created by `codeharness audit --fix`.",
+    `**Audit Gap:** ${gap2.dimension}: ${gap2.description}`,
+    `**Suggested Fix:** ${gap2.suggestedFix}`,
+    ""
+  ].join("\n");
+}
+function generateFixStories(auditResult) {
+  try {
+    const stories = [];
+    let created = 0;
+    let skipped = 0;
+    const artifactsDir = join34(
+      process.cwd(),
+      "_bmad-output",
+      "implementation-artifacts"
+    );
+    for (const dimension of Object.values(auditResult.dimensions)) {
+      for (let i = 0; i < dimension.gaps.length; i++) {
+        const gap2 = dimension.gaps[i];
+        const key = buildStoryKey(gap2, i + 1);
+        const filePath = join34(artifactsDir, `${key}.md`);
+        if (existsSync35(filePath)) {
+          stories.push({
+            key,
+            filePath,
+            gap: gap2,
+            skipped: true,
+            skipReason: "Story file already exists"
+          });
+          skipped++;
+          continue;
+        }
+        const markdown = buildStoryMarkdown(gap2, key);
+        mkdirSync11(dirname8(filePath), { recursive: true });
+        writeFileSync19(filePath, markdown, "utf-8");
+        stories.push({ key, filePath, gap: gap2, skipped: false });
+        created++;
+      }
+    }
+    return ok2({ stories, created, skipped });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return fail2(`Failed to generate fix stories: ${msg}`);
+  }
+}
+function addFixStoriesToState(stories) {
+  const newStories = stories.filter((s) => !s.skipped);
+  if (newStories.length === 0) {
+    return ok2(void 0);
+  }
+  const stateResult = getSprintState2();
+  if (!stateResult.success) {
+    return fail2(stateResult.error);
+  }
+  const current = stateResult.data;
+  const updatedStories = { ...current.stories };
+  for (const story of newStories) {
+    updatedStories[story.key] = {
+      status: "backlog",
+      attempts: 0,
+      lastAttempt: null,
+      lastError: null,
+      proofPath: null,
+      acResults: null
+    };
+  }
+  const updatedSprint = computeSprintCounts2(updatedStories);
+  return writeStateAtomic2({
+    ...current,
+    sprint: updatedSprint,
+    stories: updatedStories
+  });
+}
+
+// src/modules/audit/index.ts
+async function runAudit2(projectDir) {
+  const start = performance.now();
+  const [
+    obsResult,
+    testResult,
+    docResult,
+    verifyResult,
+    infraResult
+  ] = await Promise.all([
+    checkObservability(projectDir),
+    Promise.resolve(checkTesting(projectDir)),
+    Promise.resolve(checkDocumentation(projectDir)),
+    Promise.resolve(checkVerification(projectDir)),
+    Promise.resolve(checkInfrastructure(projectDir))
+  ]);
+  const dimensions = {};
+  const allResults = [obsResult, testResult, docResult, verifyResult, infraResult];
+  for (const result of allResults) {
+    if (result.success) {
+      dimensions[result.data.name] = result.data;
+    }
+  }
+  const statuses = Object.values(dimensions).map((d) => d.status);
+  const overallStatus = computeOverallStatus(statuses);
+  const gapCount = Object.values(dimensions).reduce((sum, d) => sum + d.gaps.length, 0);
+  const durationMs = Math.round(performance.now() - start);
+  return ok2({ dimensions, overallStatus, gapCount, durationMs });
+}
+function computeOverallStatus(statuses) {
+  if (statuses.includes("fail")) return "fail";
+  if (statuses.includes("warn")) return "warn";
+  return "pass";
+}
+
+// src/commands/audit.ts
+function registerAuditCommand(program) {
+  program.command("audit").description("Check all compliance dimensions and report project health").option("--json", "Output in machine-readable JSON format").option("--fix", "Generate fix stories for every gap found").action(async (opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    const isJson = opts.json === true || globalOpts.json === true;
+    const isFix = opts.fix === true;
+    const preconditions = runPreconditions();
+    if (!preconditions.canProceed) {
+      if (isJson) {
+        jsonOutput({
+          status: "fail",
+          message: "Harness not initialized -- run codeharness init first"
+        });
+      } else {
+        fail("Harness not initialized -- run codeharness init first");
+      }
+      process.exitCode = 1;
+      return;
+    }
+    const result = await runAudit2(process.cwd());
+    if (!result.success) {
+      if (isJson) {
+        jsonOutput({ status: "fail", message: result.error });
+      } else {
+        fail(result.error);
+      }
+      process.exitCode = 1;
+      return;
+    }
+    let fixStories;
+    let fixStateError;
+    if (isFix) {
+      if (result.data.gapCount === 0) {
+        if (!isJson) {
+          ok("No gaps found -- nothing to fix");
+        }
+      } else {
+        const fixResult = generateFixStories(result.data);
+        fixStories = fixResult;
+        if (fixResult.success) {
+          const stateResult = addFixStoriesToState(fixResult.data.stories);
+          if (!stateResult.success) {
+            fixStateError = stateResult.error;
+            if (!isJson) {
+              fail(`Failed to update sprint state: ${stateResult.error}`);
+            }
+          }
+          if (!isJson) {
+            info(`Generated ${fixResult.data.created} fix stories (${fixResult.data.skipped} skipped)`);
+          }
+        } else if (!isJson) {
+          fail(fixResult.error);
+        }
+      }
+    }
+    if (isJson) {
+      const jsonData = formatAuditJson(result.data);
+      if (isFix) {
+        if (result.data.gapCount === 0) {
+          jsonData.fixStories = [];
+        } else if (fixStories && fixStories.success) {
+          jsonData.fixStories = fixStories.data.stories.map((s) => ({
+            key: s.key,
+            filePath: s.filePath,
+            gap: s.gap,
+            ...s.skipped ? { skipped: true } : {}
+          }));
+          if (fixStateError) {
+            jsonData.fixStateError = fixStateError;
+          }
+        } else if (fixStories && !fixStories.success) {
+          jsonData.fixStories = [];
+          jsonData.fixError = fixStories.error;
+        }
+      }
+      jsonOutput(jsonData);
+    } else if (!isFix || result.data.gapCount > 0) {
+      const lines = formatAuditHuman(result.data);
+      for (const line of lines) {
+        console.log(line);
+      }
+    }
+    if (result.data.overallStatus === "fail") {
+      process.exitCode = 1;
+    }
+  });
+}
+
 // src/index.ts
-var VERSION = true ? "0.22.0" : "0.0.0-dev";
+var VERSION = true ? "0.22.1" : "0.0.0-dev";
 function createProgram() {
   const program = new Command();
   program.name("codeharness").description("Makes autonomous coding agents produce software that actually works").version(VERSION).option("--json", "Output in machine-readable JSON format");
@@ -10941,6 +11825,7 @@ function createProgram() {
   registerValidateCommand(program);
   registerProgressCommand(program);
   registerObservabilityGateCommand(program);
+  registerAuditCommand(program);
   return program;
 }
 if (!process.env["VITEST"]) {