codeharness 0.13.0 → 0.16.0

package/dist/index.js

@@ -13,13 +13,13 @@ import {
   startSharedStack,
   stopCollectorOnly,
   stopSharedStack
-} from "./chunk-7ZD2ZNDU.js";
+} from "./chunk-CVXXI3N6.js";
 
 // src/index.ts
 import { Command } from "commander";
 
 // src/commands/init.ts
-import { existsSync as existsSync6 } from "fs";
+import { existsSync as existsSync6, readFileSync as readFileSync6 } from "fs";
 import { join as join6, basename as basename2 } from "path";
 
 // src/lib/output.ts
@@ -1347,8 +1347,75 @@ function importStoriesToBeads(stories, opts, beadsFns) {
   return results;
 }
 
+// src/templates/readme.ts
+function readmeTemplate(config) {
+  const { projectName, stack, cliHelpOutput } = config;
+  const installCommand = getInstallCommand(stack);
+  const firstRunCommand = "codeharness init";
+  const exampleUsage = "codeharness status";
+  const lines = [
+    `# ${projectName}`,
+    "",
+    "## Quick Start",
+    "",
+    "```bash",
+    `# Install`,
+    installCommand,
+    "",
+    "# Initialize the project",
+    firstRunCommand,
+    "",
+    "# Check project status",
+    exampleUsage,
+    "```",
+    "",
+    "## Installation",
+    "",
+    "```bash",
+    installCommand,
+    "```",
+    "",
+    "## Usage",
+    "",
+    `After installation, initialize ${projectName} in your project directory:`,
+    "",
+    "```bash",
+    "codeharness init",
+    "```",
+    "",
+    "This sets up the harness with stack detection, observability, and documentation scaffolding.",
+    "",
+    "## CLI Reference",
+    "",
+    "```",
+    cliHelpOutput.trimEnd(),
+    "```",
+    ""
+  ];
+  return lines.join("\n");
+}
+function getInstallCommand(stack) {
+  if (stack === "python") {
+    return "pip install codeharness";
+  }
+  return "npm install -g codeharness";
+}
+
 // src/commands/init.ts
-var HARNESS_VERSION = true ? "0.13.0" : "0.0.0-dev";
+var HARNESS_VERSION = true ? "0.16.0" : "0.0.0-dev";
+function getProjectName(projectDir) {
+  try {
+    const pkgPath = join6(projectDir, "package.json");
+    if (existsSync6(pkgPath)) {
+      const pkg = JSON.parse(readFileSync6(pkgPath, "utf-8"));
+      if (pkg.name && typeof pkg.name === "string") {
+        return pkg.name;
+      }
+    }
+  } catch {
+  }
+  return basename2(projectDir);
+}
 function getStackLabel(stack) {
   if (stack === "nodejs") return "Node.js (package.json)";
   if (stack === "python") return "Python";
@@ -1445,7 +1512,8 @@ function registerInitCommand(program) {
       },
       documentation: {
         agents_md: "created",
-        docs_scaffold: "created"
+        docs_scaffold: "created",
+        readme: "created"
       }
     };
     const statePath = getStatePath(projectDir);
@@ -1458,6 +1526,7 @@ function registerInitCommand(program) {
           result.enforcement = existingState.enforcement;
           result.documentation.agents_md = "exists";
           result.documentation.docs_scaffold = "exists";
+          result.documentation.readme = "exists";
           if (isJson) {
             jsonOutput(result);
           } else {
@@ -1658,10 +1727,35 @@ function registerInitCommand(program) {
     } else {
       result.documentation.docs_scaffold = "exists";
     }
+    const readmePath = join6(projectDir, "README.md");
+    if (!existsSync6(readmePath)) {
+      let cliHelpOutput = "";
+      try {
+        const { execFileSync: execFileSync8 } = await import("child_process");
+        cliHelpOutput = execFileSync8(process.execPath, [process.argv[1], "--help"], {
+          stdio: "pipe",
+          timeout: 1e4
+        }).toString();
+      } catch {
+        cliHelpOutput = "Run: codeharness --help";
+      }
+      const readmeContent = readmeTemplate({
+        projectName: getProjectName(projectDir),
+        stack,
+        cliHelpOutput
+      });
+      generateFile(readmePath, readmeContent);
+      result.documentation.readme = "created";
+    } else {
+      result.documentation.readme = "exists";
+    }
     if (!isJson) {
       if (result.documentation.agents_md === "created" || result.documentation.docs_scaffold === "created") {
         ok("Documentation: AGENTS.md + docs/ scaffold created");
       }
+      if (result.documentation.readme === "created") {
+        ok("Documentation: README.md created");
+      }
     }
     const otlpResult = instrumentProject(projectDir, stack, { json: isJson, appType });
     result.otlp = otlpResult;
@@ -1901,12 +1995,12 @@ function registerBridgeCommand(program) {
 
 // src/commands/run.ts
 import { spawn } from "child_process";
-import { existsSync as existsSync9, mkdirSync as mkdirSync3, readFileSync as readFileSync7, writeFileSync as writeFileSync6 } from "fs";
+import { existsSync as existsSync9, mkdirSync as mkdirSync3, readFileSync as readFileSync8, writeFileSync as writeFileSync6 } from "fs";
 import { join as join8, dirname as dirname2 } from "path";
 import { fileURLToPath } from "url";
 
 // src/lib/beads-sync.ts
-import { existsSync as existsSync8, readFileSync as readFileSync6, writeFileSync as writeFileSync5 } from "fs";
+import { existsSync as existsSync8, readFileSync as readFileSync7, writeFileSync as writeFileSync5 } from "fs";
 import { join as join7 } from "path";
 import { parse as parse2 } from "yaml";
 var BEADS_TO_STORY_STATUS = {
@@ -1941,7 +2035,7 @@ function readStoryFileStatus(filePath) {
   if (!existsSync8(filePath)) {
     return null;
   }
-  const content = readFileSync6(filePath, "utf-8");
+  const content = readFileSync7(filePath, "utf-8");
   const match = content.match(/^Status:\s*(.+)$/m);
   if (!match) {
     return null;
@@ -1949,7 +2043,7 @@ function readStoryFileStatus(filePath) {
   return match[1].trim();
 }
 function updateStoryFileStatus(filePath, newStatus) {
-  const content = readFileSync6(filePath, "utf-8");
+  const content = readFileSync7(filePath, "utf-8");
   const statusRegex = /^Status:\s*.+$/m;
   if (statusRegex.test(content)) {
     const updated = content.replace(statusRegex, `Status: ${newStatus}`);
@@ -1973,7 +2067,7 @@ function readSprintStatus(dir) {
     return {};
   }
   try {
-    const content = readFileSync6(filePath, "utf-8");
+    const content = readFileSync7(filePath, "utf-8");
     const parsed = parse2(content);
     if (!parsed || typeof parsed !== "object") {
       return {};
@@ -1994,7 +2088,7 @@ function updateSprintStatus(storyKey, newStatus, dir) {
     warn(`sprint-status.yaml not found at ${filePath}, skipping update`);
     return;
   }
-  const content = readFileSync6(filePath, "utf-8");
+  const content = readFileSync7(filePath, "utf-8");
   const keyPattern = new RegExp(`^(\\s*${escapeRegExp(storyKey)}:\\s*)\\S+(.*)$`, "m");
   if (!keyPattern.test(content)) {
     return;
@@ -2039,7 +2133,7 @@ function appendOnboardingEpicToSprint(stories, dir) {
   }
   lines.push(`  epic-${epicNum}-retrospective: optional`);
   lines.push("");
-  const content = readFileSync6(filePath, "utf-8");
+  const content = readFileSync7(filePath, "utf-8");
   const updated = content.trimEnd() + "\n" + lines.join("\n");
   writeFileSync5(filePath, updated, "utf-8");
   return { epicNumber: epicNum, storyKeys };
@@ -2452,7 +2546,7 @@ function registerRunCommand(program) {
     let flaggedStories;
     if (existsSync9(flaggedFilePath)) {
       try {
-        const flaggedContent = readFileSync7(flaggedFilePath, "utf-8");
+        const flaggedContent = readFileSync8(flaggedFilePath, "utf-8");
         flaggedStories = flaggedContent.split("\n").filter((s) => s.trim().length > 0);
       } catch {
       }
@@ -2505,7 +2599,7 @@ function registerRunCommand(program) {
         const statusFile = join8(projectDir, "ralph", "status.json");
         if (existsSync9(statusFile)) {
           try {
-            const statusData = JSON.parse(readFileSync7(statusFile, "utf-8"));
+            const statusData = JSON.parse(readFileSync8(statusFile, "utf-8"));
             const finalStatuses = readSprintStatus(projectDir);
             const finalCounts = countStories(finalStatuses);
             jsonOutput({
@@ -2555,11 +2649,11 @@ function registerRunCommand(program) {
 }
 
 // src/commands/verify.ts
-import { existsSync as existsSync13, readFileSync as readFileSync11 } from "fs";
+import { existsSync as existsSync13, readFileSync as readFileSync12 } from "fs";
 import { join as join11 } from "path";
 
 // src/lib/verify-parser.ts
-import { existsSync as existsSync10, readFileSync as readFileSync8 } from "fs";
+import { existsSync as existsSync10, readFileSync as readFileSync9 } from "fs";
 var UI_KEYWORDS = [
   "agent-browser",
   "screenshot",
@@ -2640,7 +2734,7 @@ function parseStoryACs(storyFilePath) {
       `Story file not found: ${storyFilePath}. Ensure the story file exists at the expected path.`
     );
   }
-  const content = readFileSync8(storyFilePath, "utf-8");
+  const content = readFileSync9(storyFilePath, "utf-8");
   const lines = content.split("\n");
   let acSectionStart = -1;
   for (let i = 0; i < lines.length; i++) {
@@ -2701,7 +2795,7 @@ function parseStoryACs(storyFilePath) {
 
 // src/lib/verify.ts
 import { execFileSync as execFileSync5 } from "child_process";
-import { existsSync as existsSync12, mkdirSync as mkdirSync5, readFileSync as readFileSync10, writeFileSync as writeFileSync8 } from "fs";
+import { existsSync as existsSync12, mkdirSync as mkdirSync5, readFileSync as readFileSync11, writeFileSync as writeFileSync8 } from "fs";
 import { join as join10 } from "path";
 
 // src/lib/doc-health.ts
@@ -2709,7 +2803,7 @@ import { execSync } from "child_process";
 import {
   existsSync as existsSync11,
   mkdirSync as mkdirSync4,
-  readFileSync as readFileSync9,
+  readFileSync as readFileSync10,
   readdirSync as readdirSync2,
   statSync,
   unlinkSync,
@@ -2851,15 +2945,15 @@ function getSourceFilesInModule(modulePath) {
 }
 function getMentionedFilesInAgentsMd(agentsPath) {
   if (!existsSync11(agentsPath)) return [];
-  const content = readFileSync9(agentsPath, "utf-8");
+  const content = readFileSync10(agentsPath, "utf-8");
   const mentioned = /* @__PURE__ */ new Set();
   const filenamePattern = /[\w./-]*[\w-]+\.(?:ts|js|py)\b/g;
   let match;
   while ((match = filenamePattern.exec(content)) !== null) {
     const fullMatch = match[0];
-    const basename3 = fullMatch.split("/").pop();
-    if (!isTestFile(basename3)) {
-      mentioned.add(basename3);
+    const basename4 = fullMatch.split("/").pop();
+    if (!isTestFile(basename4)) {
+      mentioned.add(basename4);
     }
   }
   return Array.from(mentioned);
@@ -2913,7 +3007,7 @@ function checkAgentsMdForModule(modulePath, dir) {
 function checkDoNotEditHeaders(docPath) {
   if (!existsSync11(docPath)) return false;
   try {
-    const content = readFileSync9(docPath, "utf-8");
+    const content = readFileSync10(docPath, "utf-8");
     if (content.length === 0) return false;
     return content.trimStart().startsWith(DO_NOT_EDIT_HEADER2);
   } catch {
@@ -2994,7 +3088,7 @@ function scanDocHealth(dir) {
   }
   const indexPath = join9(root, "docs", "index.md");
   if (existsSync11(indexPath)) {
-    const content = readFileSync9(indexPath, "utf-8");
+    const content = readFileSync10(indexPath, "utf-8");
     const hasAbsolutePaths = /https?:\/\/|file:\/\//i.test(content);
     documents.push({
       path: "docs/index.md",
@@ -3056,7 +3150,7 @@ function scanDocHealth(dir) {
 }
 function checkAgentsMdLineCount(filePath, docPath, documents) {
   try {
-    const content = readFileSync9(filePath, "utf-8");
+    const content = readFileSync10(filePath, "utf-8");
     const lineCount = content.split("\n").length;
     if (lineCount > 100) {
       documents.push({
@@ -3144,7 +3238,7 @@ function completeExecPlan(storyId, dir) {
   if (!existsSync11(activePath)) {
     return null;
   }
-  let content = readFileSync9(activePath, "utf-8");
+  let content = readFileSync10(activePath, "utf-8");
   content = content.replace(/^Status:\s*active$/m, "Status: completed");
   const timestamp = (/* @__PURE__ */ new Date()).toISOString();
   content = content.replace(
@@ -3240,6 +3334,70 @@ function showboatProofTemplate(config) {
 }
 
 // src/lib/verify.ts
+function classifyEvidenceCommands(proofContent) {
+  const results = [];
+  const codeBlockPattern = /```(?:bash|shell)\n([\s\S]*?)```/g;
+  for (const match of proofContent.matchAll(codeBlockPattern)) {
+    const block = match[1].trim();
+    const lines = block.split("\n").filter((l) => l.trim().length > 0);
+    for (const line of lines) {
+      const cmd = line.trim();
+      if (!cmd) continue;
+      results.push({ command: cmd, type: classifyCommand(cmd) });
+    }
+  }
+  return results;
+}
+function classifyCommand(cmd) {
+  if (/docker\s+exec\b/.test(cmd)) {
+    return "docker-exec";
+  }
+  if (/curl\b/.test(cmd) && /localhost:(9428|8428|16686)\b/.test(cmd)) {
+    return "observability";
+  }
+  if (/\bgrep\b/.test(cmd) && /\bsrc\//.test(cmd)) {
+    return "grep-src";
+  }
+  return "other";
+}
+function checkBlackBoxEnforcement(proofContent) {
+  const commands = classifyEvidenceCommands(proofContent);
+  const grepSrcCount = commands.filter((c) => c.type === "grep-src").length;
+  const dockerExecCount = commands.filter((c) => c.type === "docker-exec").length;
+  const observabilityCount = commands.filter((c) => c.type === "observability").length;
+  const otherCount = commands.filter((c) => c.type === "other").length;
+  const totalCommands = commands.length;
+  const grepRatio = totalCommands > 0 ? grepSrcCount / totalCommands : 0;
+  const acsMissingDockerExec = [];
+  const acHeaderPattern = /^## AC ?(\d+):/gm;
+  const acMatches = [...proofContent.matchAll(acHeaderPattern)];
+  if (acMatches.length > 0) {
+    for (let i = 0; i < acMatches.length; i++) {
+      const acNum = parseInt(acMatches[i][1], 10);
+      const start = acMatches[i].index;
+      const end = i + 1 < acMatches.length ? acMatches[i + 1].index : proofContent.length;
+      const section = proofContent.slice(start, end);
+      if (section.includes("[ESCALATE]")) continue;
+      const sectionCommands = classifyEvidenceCommands(section);
+      const hasDockerExec = sectionCommands.some((c) => c.type === "docker-exec");
+      if (!hasDockerExec) {
+        acsMissingDockerExec.push(acNum);
+      }
+    }
+  }
+  const grepTooHigh = grepRatio > 0.5;
+  const missingDockerExec = acsMissingDockerExec.length > 0;
+  const hasExtractableCommands = totalCommands > 0;
+  return {
+    blackBoxPass: !hasExtractableCommands || !grepTooHigh && !missingDockerExec,
+    grepSrcCount,
+    dockerExecCount,
+    observabilityCount,
+    otherCount,
+    grepRatio,
+    acsMissingDockerExec
+  };
+}
 function checkPreconditions(dir, storyId) {
   const state = readState(dir);
   const failures = [];
@@ -3309,10 +3467,35 @@ function runShowboatVerify(proofPath) {
   }
 }
 function validateProofQuality(proofPath) {
+  const emptyResult = {
+    verified: 0,
+    pending: 0,
+    escalated: 0,
+    total: 0,
+    passed: false,
+    grepSrcCount: 0,
+    dockerExecCount: 0,
+    observabilityCount: 0,
+    otherCount: 0,
+    blackBoxPass: false
+  };
   if (!existsSync12(proofPath)) {
-    return { verified: 0, pending: 0, escalated: 0, total: 0, passed: false };
+    return emptyResult;
+  }
+  const content = readFileSync11(proofPath, "utf-8");
+  const bbEnforcement = checkBlackBoxEnforcement(content);
+  function buildResult(base) {
+    const basePassed = base.pending === 0 && base.verified > 0;
+    return {
+      ...base,
+      passed: basePassed && bbEnforcement.blackBoxPass,
+      grepSrcCount: bbEnforcement.grepSrcCount,
+      dockerExecCount: bbEnforcement.dockerExecCount,
+      observabilityCount: bbEnforcement.observabilityCount,
+      otherCount: bbEnforcement.otherCount,
+      blackBoxPass: bbEnforcement.blackBoxPass
+    };
   }
-  const content = readFileSync10(proofPath, "utf-8");
   const acHeaderPattern = /^## AC ?(\d+):/gm;
   const matches = [...content.matchAll(acHeaderPattern)];
   let verified = 0;
@@ -3343,7 +3526,41 @@ function validateProofQuality(proofPath) {
       const narrativeMatches = [...content.matchAll(narrativeAcPattern)];
       const narrativeAcNumbers = new Set(narrativeMatches.map((m) => m[1]));
       if (narrativeAcNumbers.size === 0) {
-        return { verified: 0, pending: 0, escalated: 0, total: 0, passed: false };
+        const bulletAcPattern = /^- AC ?(\d+)[^:\n]*:/gm;
+        const bulletMatches = [...content.matchAll(bulletAcPattern)];
+        const bulletAcNumbers = new Set(bulletMatches.map((m) => m[1]));
+        if (bulletAcNumbers.size === 0) {
+          return buildResult({ verified: 0, pending: 0, escalated: 0, total: 0 });
+        }
+        let bVerified = 0;
+        let bPending = 0;
+        let bEscalated = 0;
+        for (const acNum of bulletAcNumbers) {
+          const bulletPattern = new RegExp(`^- AC ?${acNum}[^:\\n]*:(.*)$`, "m");
+          const bulletMatch = content.match(bulletPattern);
+          if (!bulletMatch) {
+            bPending++;
+            continue;
+          }
+          const bulletText = bulletMatch[1].toLowerCase();
+          if (bulletText.includes("n/a") || bulletText.includes("escalat") || bulletText.includes("superseded")) {
+            bEscalated++;
+          } else {
+            bVerified++;
+          }
+        }
+        const hasAnyEvidence = /```output\n/m.test(content);
+        if (!hasAnyEvidence) {
+          bPending += bVerified;
+          bVerified = 0;
+        }
+        const bTotal = bVerified + bPending + bEscalated;
+        return buildResult({
+          verified: bVerified,
+          pending: bPending,
+          escalated: bEscalated,
+          total: bTotal
+        });
       }
       const sortedAcs = narrativeMatches.map((m) => ({ num: m[1], idx: m.index })).filter((v, i, a) => a.findIndex((x) => x.num === v.num) === i).sort((a, b) => a.idx - b.idx);
       for (let i = 0; i < sortedAcs.length; i++) {
@@ -3360,13 +3577,12 @@ function validateProofQuality(proofPath) {
         }
       }
       const narrativeTotal = verified + pending + escalated;
-      return {
+      return buildResult({
         verified,
         pending,
         escalated,
-        total: narrativeTotal,
-        passed: pending === 0 && verified > 0
-      };
+        total: narrativeTotal
+      });
     }
     for (const acNum of acNumbers) {
       const acPattern = new RegExp(`--- AC ?${acNum}:`, "g");
@@ -3389,15 +3605,7 @@ function validateProofQuality(proofPath) {
     }
   }
   const total = verified + pending + escalated;
-  return {
-    verified,
-    pending,
-    escalated,
-    total,
-    // Proof passes when no pending ACs remain and at least one is verified.
-    // Escalated ACs are allowed — they are explicitly acknowledged as unverifiable.
-    passed: pending === 0 && verified > 0
-  };
+  return buildResult({ verified, pending, escalated, total });
 }
 function updateVerificationState(storyId, result, dir) {
   const { state, body } = readStateWithBody(dir);
@@ -3497,6 +3705,16 @@ function verifyStory(storyId, isJson, root) {
     process.exitCode = 1;
     return;
   }
+  const readmePath = join11(root, "README.md");
+  if (!existsSync13(readmePath)) {
+    if (isJson) {
+      jsonOutput({ status: "fail", message: "No README.md found \u2014 verification requires user documentation" });
+    } else {
+      fail("No README.md found \u2014 verification requires user documentation");
+    }
+    process.exitCode = 1;
+    return;
+  }
   const storyFilePath = join11(root, STORY_DIR, `${storyId}.md`);
   if (!existsSync13(storyFilePath)) {
     fail(`Story file not found: ${storyFilePath}`, { json: isJson });
@@ -3566,7 +3784,15 @@ function verifyStory(storyId, isJson, root) {
   } else {
     showboatStatus = showboatResult.passed ? "pass" : "fail";
     if (!showboatResult.passed) {
-      fail(`Showboat verify failed: ${showboatResult.output}`, { json: isJson });
+      if (isJson) {
+        jsonOutput({
+          status: "fail",
+          message: `Showboat verify failed: ${showboatResult.output}`,
+          proofQuality: { verified: proofQuality.verified, pending: proofQuality.pending, escalated: proofQuality.escalated, total: proofQuality.total }
+        });
+      } else {
+        fail(`Showboat verify failed: ${showboatResult.output}`);
+      }
       process.exitCode = 1;
       return;
     }
@@ -3625,7 +3851,7 @@ function verifyStory(storyId, isJson, root) {
 }
 function extractStoryTitle(filePath) {
   try {
-    const content = readFileSync11(filePath, "utf-8");
+    const content = readFileSync12(filePath, "utf-8");
     const match = /^#\s+(.+)$/m.exec(content);
     return match ? match[1] : "Unknown Story";
   } catch {
@@ -3640,7 +3866,7 @@ import { fileURLToPath as fileURLToPath2 } from "url";
 
 // src/lib/coverage.ts
 import { execSync as execSync2 } from "child_process";
-import { existsSync as existsSync14, readFileSync as readFileSync12 } from "fs";
+import { existsSync as existsSync14, readFileSync as readFileSync13 } from "fs";
 import { join as join12 } from "path";
 function detectCoverageTool(dir) {
   const baseDir = dir ?? process.cwd();
@@ -3673,7 +3899,7 @@ function detectNodeCoverageTool(dir, stateHint) {
   let pkgScripts = {};
   if (existsSync14(pkgPath)) {
     try {
-      const pkg = JSON.parse(readFileSync12(pkgPath, "utf-8"));
+      const pkg = JSON.parse(readFileSync13(pkgPath, "utf-8"));
       const allDeps = { ...pkg.dependencies ?? {}, ...pkg.devDependencies ?? {} };
       hasVitestCoverageV8 = "@vitest/coverage-v8" in allDeps;
       hasVitestCoverageIstanbul = "@vitest/coverage-istanbul" in allDeps;
@@ -3729,7 +3955,7 @@ function detectPythonCoverageTool(dir) {
   const reqPath = join12(dir, "requirements.txt");
   if (existsSync14(reqPath)) {
     try {
-      const content = readFileSync12(reqPath, "utf-8");
+      const content = readFileSync13(reqPath, "utf-8");
       if (content.includes("pytest-cov") || content.includes("coverage")) {
         return {
           tool: "coverage.py",
@@ -3743,7 +3969,7 @@ function detectPythonCoverageTool(dir) {
   const pyprojectPath = join12(dir, "pyproject.toml");
   if (existsSync14(pyprojectPath)) {
     try {
-      const content = readFileSync12(pyprojectPath, "utf-8");
+      const content = readFileSync13(pyprojectPath, "utf-8");
       if (content.includes("pytest-cov") || content.includes("coverage")) {
         return {
           tool: "coverage.py",
@@ -3825,7 +4051,7 @@ function parseVitestCoverage(dir) {
     return 0;
   }
   try {
-    const report = JSON.parse(readFileSync12(reportPath, "utf-8"));
+    const report = JSON.parse(readFileSync13(reportPath, "utf-8"));
     return report.total?.statements?.pct ?? 0;
   } catch {
     warn("Failed to parse coverage report");
@@ -3839,7 +4065,7 @@ function parsePythonCoverage(dir) {
     return 0;
   }
   try {
-    const report = JSON.parse(readFileSync12(reportPath, "utf-8"));
+    const report = JSON.parse(readFileSync13(reportPath, "utf-8"));
     return report.totals?.percent_covered ?? 0;
   } catch {
     warn("Failed to parse coverage report");
@@ -3940,7 +4166,7 @@ function checkPerFileCoverage(floor, dir) {
   }
   let report;
   try {
-    report = JSON.parse(readFileSync12(reportPath, "utf-8"));
+    report = JSON.parse(readFileSync13(reportPath, "utf-8"));
   } catch {
     warn("Failed to parse coverage-summary.json");
     return { floor, violations: [], totalFiles: 0 };
@@ -4640,7 +4866,7 @@ import { join as join17 } from "path";
 import {
   existsSync as existsSync16,
   readdirSync as readdirSync3,
-  readFileSync as readFileSync13,
+  readFileSync as readFileSync14,
   statSync as statSync2
 } from "fs";
 import { join as join14, relative as relative2 } from "path";
@@ -4814,7 +5040,7 @@ function readVitestPerFileCoverage(dir) {
   const reportPath = join14(dir, "coverage", "coverage-summary.json");
   if (!existsSync16(reportPath)) return null;
   try {
-    const report = JSON.parse(readFileSync13(reportPath, "utf-8"));
+    const report = JSON.parse(readFileSync14(reportPath, "utf-8"));
     const result = /* @__PURE__ */ new Map();
     for (const [key, value] of Object.entries(report)) {
       if (key === "total") continue;
@@ -4829,7 +5055,7 @@ function readPythonPerFileCoverage(dir) {
   const reportPath = join14(dir, "coverage.json");
   if (!existsSync16(reportPath)) return null;
   try {
-    const report = JSON.parse(readFileSync13(reportPath, "utf-8"));
+    const report = JSON.parse(readFileSync14(reportPath, "utf-8"));
     if (!report.files) return null;
     const result = /* @__PURE__ */ new Map();
     for (const [key, value] of Object.entries(report.files)) {
@@ -4906,6 +5132,18 @@ function generateOnboardingEpic(scan, coverage, audit, rootDir) {
   const root = rootDir ?? process.cwd();
   const stories = [];
   let storyNum = 1;
+  const readmeDoc = audit.documents.find((d) => d.name === "README.md");
+  if (readmeDoc && readmeDoc.grade === "missing") {
+    stories.push({
+      key: `0.${storyNum}`,
+      title: "Create README.md",
+      type: "doc-freshness",
+      acceptanceCriteria: [
+        "**Given** no README.md exists\n**When** the agent runs `codeharness init`\n**Then** README.md is created with project name, installation command, Quick Start section, and CLI reference"
+      ]
+    });
+    storyNum++;
+  }
   const archDoc = audit.documents.find((d) => d.name === "ARCHITECTURE.md");
   if (archDoc && archDoc.grade === "missing") {
     stories.push({
@@ -5079,6 +5317,7 @@ function importOnboardingEpic(epicPath, beadsFns) {
 function getPriorityFromTitle(title) {
   if (title.startsWith("Add test coverage for ")) return PRIORITY_BY_TYPE.coverage;
   if (title.startsWith("Create ") && title.endsWith("AGENTS.md")) return PRIORITY_BY_TYPE["agents-md"];
+  if (title === "Create README.md") return PRIORITY_BY_TYPE["doc-freshness"];
   if (title === "Create ARCHITECTURE.md") return PRIORITY_BY_TYPE.architecture;
   if (title === "Update stale documentation") return PRIORITY_BY_TYPE["doc-freshness"];
   if (title.startsWith("Create verification proof for ")) return PRIORITY_BY_TYPE.verification;
@@ -5094,6 +5333,9 @@ function getGapIdFromTitle(title) {
     const mod = title.slice("Create ".length);
     return `[gap:docs:${mod}]`;
   }
+  if (title === "Create README.md") {
+    return "[gap:docs:README.md]";
+  }
   if (title === "Create ARCHITECTURE.md") {
     return "[gap:docs:ARCHITECTURE.md]";
   }
@@ -5114,7 +5356,7 @@ function getGapIdFromTitle(title) {
 }
 
 // src/lib/scan-cache.ts
-import { existsSync as existsSync18, mkdirSync as mkdirSync7, readFileSync as readFileSync14, writeFileSync as writeFileSync10 } from "fs";
+import { existsSync as existsSync18, mkdirSync as mkdirSync7, readFileSync as readFileSync15, writeFileSync as writeFileSync10 } from "fs";
 import { join as join16 } from "path";
 var CACHE_DIR = ".harness";
 var CACHE_FILE = "last-onboard-scan.json";
@@ -5136,7 +5378,7 @@ function loadScanCache(dir) {
     return null;
   }
   try {
-    const raw = readFileSync14(cachePath, "utf-8");
+    const raw = readFileSync15(cachePath, "utf-8");
     return JSON.parse(raw);
   } catch {
     return null;
@@ -5179,7 +5421,11 @@ function registerOnboardCommand(program) {
     const minModuleSize = parseInt(opts.minModuleSize ?? "3", 10);
     const preconditions = runPreconditions();
     if (!preconditions.canProceed) {
-      fail("Harness not initialized \u2014 run codeharness init first");
+      if (isJson) {
+        jsonOutput({ status: "fail", message: "Harness not initialized \u2014 run codeharness init first" });
+      } else {
+        fail("Harness not initialized \u2014 run codeharness init first");
+      }
       process.exitCode = 1;
       return;
     }
@@ -5208,7 +5454,11 @@ function registerOnboardCommand(program) {
     const minModuleSize = parseInt(opts.minModuleSize ?? "3", 10);
     const preconditions = runPreconditions();
     if (!preconditions.canProceed) {
-      fail("Harness not initialized \u2014 run codeharness init first");
+      if (isJson) {
+        jsonOutput({ status: "fail", message: "Harness not initialized \u2014 run codeharness init first" });
+      } else {
+        fail("Harness not initialized \u2014 run codeharness init first");
+      }
       process.exitCode = 1;
       return;
     }
@@ -5240,7 +5490,11 @@ function registerOnboardCommand(program) {
     const isJson = opts.json === true;
     const preconditions = runPreconditions();
     if (!preconditions.canProceed) {
-      fail("Harness not initialized \u2014 run codeharness init first");
+      if (isJson) {
+        jsonOutput({ status: "fail", message: "Harness not initialized \u2014 run codeharness init first" });
+      } else {
+        fail("Harness not initialized \u2014 run codeharness init first");
+      }
       process.exitCode = 1;
       return;
     }
@@ -5263,7 +5517,11 @@ function registerOnboardCommand(program) {
     const minModuleSize = parseInt(opts.minModuleSize ?? "3", 10);
     const preconditions = runPreconditions();
     if (!preconditions.canProceed) {
-      fail("Harness not initialized \u2014 run codeharness init first");
+      if (isJson) {
+        jsonOutput({ status: "fail", message: "Harness not initialized \u2014 run codeharness init first" });
+      } else {
+        fail("Harness not initialized \u2014 run codeharness init first");
+      }
       process.exitCode = 1;
       return;
     }
@@ -5338,7 +5596,11 @@ function registerOnboardCommand(program) {
     const minModuleSize = parseInt(opts.minModuleSize ?? "3", 10);
     const preconditions = runPreconditions();
     if (!preconditions.canProceed) {
-      fail("Harness not initialized \u2014 run codeharness init first");
+      if (isJson) {
+        jsonOutput({ status: "fail", message: "Harness not initialized \u2014 run codeharness init first" });
+      } else {
+        fail("Harness not initialized \u2014 run codeharness init first");
+      }
       process.exitCode = 1;
       return;
     }
@@ -5470,7 +5732,7 @@ function printEpicOutput(epic) {
 }
 
 // src/commands/teardown.ts
-import { existsSync as existsSync19, unlinkSync as unlinkSync2, readFileSync as readFileSync15, writeFileSync as writeFileSync11, rmSync } from "fs";
+import { existsSync as existsSync19, unlinkSync as unlinkSync2, readFileSync as readFileSync16, writeFileSync as writeFileSync11, rmSync } from "fs";
 import { join as join18 } from "path";
 function buildDefaultResult() {
   return {
@@ -5517,7 +5779,7 @@ function registerTeardownCommand(program) {
     } else if (otlpMode === "remote-routed") {
       if (!options.keepDocker) {
         try {
-          const { stopCollectorOnly: stopCollectorOnly2 } = await import("./docker-CT57JGM7.js");
+          const { stopCollectorOnly: stopCollectorOnly2 } = await import("./docker-6TY2FN43.js");
           stopCollectorOnly2();
           result.docker.stopped = true;
           if (!isJson) {
@@ -5549,7 +5811,7 @@ function registerTeardownCommand(program) {
         info("Shared stack: kept running (other projects may use it)");
       }
     } else if (isLegacyStack) {
-      const { isStackRunning: isStackRunning2, stopStack } = await import("./docker-CT57JGM7.js");
+      const { isStackRunning: isStackRunning2, stopStack } = await import("./docker-6TY2FN43.js");
       let stackRunning = false;
       try {
         stackRunning = isStackRunning2(composeFile);
@@ -5617,7 +5879,7 @@ function registerTeardownCommand(program) {
       const pkgPath = join18(projectDir, "package.json");
       if (existsSync19(pkgPath)) {
         try {
-          const raw = readFileSync15(pkgPath, "utf-8");
+          const raw = readFileSync16(pkgPath, "utf-8");
           const pkg = JSON.parse(raw);
           const scripts = pkg["scripts"];
           if (scripts) {
@@ -5691,6 +5953,7 @@ function registerTeardownCommand(program) {
 import { stringify as stringify3 } from "yaml";
 function registerStateCommand(program) {
   const stateCmd = program.command("state").description("Manage harness state");
+  stateCmd._hidden = true;
   stateCmd.command("show").description("Display full harness state").action((_, cmd) => {
     const opts = cmd.optsWithGlobals();
     try {
@@ -6409,7 +6672,7 @@ function registerQueryCommand(program) {
 }
 
 // src/commands/retro-import.ts
-import { existsSync as existsSync20, readFileSync as readFileSync16 } from "fs";
+import { existsSync as existsSync20, readFileSync as readFileSync17 } from "fs";
 import { join as join19 } from "path";
 
 // src/lib/retro-parser.ts
@@ -6587,7 +6850,7 @@ function registerRetroImportCommand(program) {
     }
     let content;
     try {
-      content = readFileSync16(retroPath, "utf-8");
+      content = readFileSync17(retroPath, "utf-8");
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
       fail(`Failed to read retro file: ${message}`, { json: isJson });
@@ -6853,8 +7116,566 @@ function registerGithubImportCommand(program) {
   });
 }
 
+// src/lib/verify-env.ts
+import { execFileSync as execFileSync7 } from "child_process";
+import { existsSync as existsSync21, mkdirSync as mkdirSync8, readdirSync as readdirSync4, readFileSync as readFileSync18, cpSync, rmSync as rmSync2, statSync as statSync3 } from "fs";
+import { join as join20, basename as basename3 } from "path";
+import { createHash } from "crypto";
+var IMAGE_TAG = "codeharness-verify";
+var STORY_DIR3 = "_bmad-output/implementation-artifacts";
+var TEMP_PREFIX = "/tmp/codeharness-verify-";
+var STATE_KEY_DIST_HASH = "verify_env_dist_hash";
+function isValidStoryKey(storyKey) {
+  if (!storyKey || storyKey.includes("..") || storyKey.includes("/") || storyKey.includes("\\")) {
+    return false;
+  }
+  return /^[a-zA-Z0-9_-]+$/.test(storyKey);
+}
+function computeDistHash(projectDir) {
+  const distDir = join20(projectDir, "dist");
+  if (!existsSync21(distDir)) {
+    return null;
+  }
+  const hash = createHash("sha256");
+  const files = collectFiles(distDir).sort();
+  for (const file of files) {
+    const content = readFileSync18(file);
+    hash.update(file.slice(distDir.length));
+    hash.update(content);
+  }
+  return hash.digest("hex");
+}
+function collectFiles(dir) {
+  const results = [];
+  const entries = readdirSync4(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = join20(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...collectFiles(fullPath));
+    } else {
+      results.push(fullPath);
+    }
+  }
+  return results;
+}
+function getStoredDistHash(projectDir) {
+  try {
+    const { state } = readStateWithBody(projectDir);
+    const raw = state;
+    return raw[STATE_KEY_DIST_HASH] ?? null;
+  } catch {
+    return null;
+  }
+}
+function storeDistHash(projectDir, hash) {
+  try {
+    const { state, body } = readStateWithBody(projectDir);
+    const raw = state;
+    raw[STATE_KEY_DIST_HASH] = hash;
+    writeState(state, projectDir, body);
+  } catch {
+    info("Could not persist dist hash to state file \u2014 cache will not be available until state is initialized");
+  }
+}
+function buildVerifyImage(options = {}) {
+  const projectDir = options.projectDir ?? process.cwd();
+  if (!isDockerAvailable()) {
+    throw new Error("Docker is not available. Install Docker and ensure the daemon is running.");
+  }
+  const stack = detectStack(projectDir);
+  if (!stack) {
+    throw new Error("Cannot detect project stack. Ensure package.json (Node.js) or requirements.txt/pyproject.toml (Python) exists.");
+  }
+  const currentHash = computeDistHash(projectDir);
+  if (!currentHash) {
+    throw new Error("No dist/ directory found. Run your build command first (e.g., npm run build).");
+  }
+  const storedHash = getStoredDistHash(projectDir);
+  if (storedHash === currentHash) {
+    if (dockerImageExists(IMAGE_TAG)) {
+      const imageSize2 = getImageSize(IMAGE_TAG);
+      return { imageTag: IMAGE_TAG, imageSize: imageSize2, buildTimeMs: 0, cached: true };
+    }
+  }
+  const startTime = Date.now();
+  if (stack === "nodejs") {
+    buildNodeImage(projectDir);
+  } else if (stack === "python") {
+    buildPythonImage(projectDir);
+  } else {
+    throw new Error(`Unsupported stack for verify-env: ${stack}`);
+  }
+  const buildTimeMs = Date.now() - startTime;
+  storeDistHash(projectDir, currentHash);
+  const imageSize = getImageSize(IMAGE_TAG);
+  return { imageTag: IMAGE_TAG, imageSize, buildTimeMs, cached: false };
+}
+function buildNodeImage(projectDir) {
+  const packOutput = execFileSync7("npm", ["pack", "--pack-destination", "/tmp"], {
+    cwd: projectDir,
+    stdio: "pipe",
+    timeout: 6e4
+  }).toString().trim();
+  const lastLine = packOutput.split("\n").pop()?.trim();
+  if (!lastLine) {
+    throw new Error("npm pack produced no output \u2014 cannot determine tarball filename.");
+  }
+  const tarballName = basename3(lastLine);
+  const tarballPath = join20("/tmp", tarballName);
+  const buildContext = join20("/tmp", `codeharness-verify-build-${Date.now()}`);
+  mkdirSync8(buildContext, { recursive: true });
+  try {
+    cpSync(tarballPath, join20(buildContext, tarballName));
+    const dockerfileSrc = resolveDockerfileTemplate(projectDir);
+    cpSync(dockerfileSrc, join20(buildContext, "Dockerfile"));
+    execFileSync7("docker", [
+      "build",
+      "-t",
+      IMAGE_TAG,
+      "--build-arg",
+      `TARBALL=${tarballName}`,
+      "."
+    ], {
+      cwd: buildContext,
+      stdio: "pipe",
+      timeout: 12e4
+    });
+  } finally {
+    rmSync2(buildContext, { recursive: true, force: true });
+    rmSync2(tarballPath, { force: true });
+  }
+}
+function buildPythonImage(projectDir) {
+  const distDir = join20(projectDir, "dist");
+  const distFiles = readdirSync4(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()}`);
+  mkdirSync8(buildContext, { recursive: true });
+  try {
+    cpSync(join20(distDir, distFile), join20(buildContext, distFile));
+    const dockerfileSrc = resolveDockerfileTemplate(projectDir);
+    cpSync(dockerfileSrc, join20(buildContext, "Dockerfile"));
+    execFileSync7("docker", [
+      "build",
+      "-t",
+      IMAGE_TAG,
+      "--build-arg",
+      `TARBALL=${distFile}`,
+      "."
+    ], {
+      cwd: buildContext,
+      stdio: "pipe",
+      timeout: 12e4
+    });
+  } finally {
+    rmSync2(buildContext, { recursive: true, force: true });
+  }
+}
+function prepareVerifyWorkspace(storyKey, projectDir) {
+  const root = projectDir ?? process.cwd();
+  if (!isValidStoryKey(storyKey)) {
+    throw new Error(`Invalid story key: ${storyKey}. Keys must contain only alphanumeric characters, hyphens, and underscores.`);
+  }
+  const storyFile = join20(root, STORY_DIR3, `${storyKey}.md`);
+  if (!existsSync21(storyFile)) {
+    throw new Error(`Story file not found: ${storyFile}`);
+  }
+  const workspace = `${TEMP_PREFIX}${storyKey}`;
+  if (existsSync21(workspace)) {
+    rmSync2(workspace, { recursive: true, force: true });
+  }
+  mkdirSync8(workspace, { recursive: true });
+  cpSync(storyFile, join20(workspace, "story.md"));
+  const readmePath = join20(root, "README.md");
+  if (existsSync21(readmePath)) {
+    cpSync(readmePath, join20(workspace, "README.md"));
+  }
+  const docsDir = join20(root, "docs");
+  if (existsSync21(docsDir) && statSync3(docsDir).isDirectory()) {
+    cpSync(docsDir, join20(workspace, "docs"), { recursive: true });
+  }
+  mkdirSync8(join20(workspace, "verification"), { recursive: true });
+  return workspace;
+}
+function checkVerifyEnv() {
+  const result = {
+    imageExists: false,
+    cliWorks: false,
+    otelReachable: false
+  };
+  result.imageExists = dockerImageExists(IMAGE_TAG);
+  if (!result.imageExists) {
+    return result;
+  }
+  try {
+    execFileSync7("docker", ["run", "--rm", IMAGE_TAG, "codeharness", "--version"], {
+      stdio: "pipe",
+      timeout: 3e4
+    });
+    result.cliWorks = true;
+  } catch {
+    result.cliWorks = false;
+  }
+  try {
+    execFileSync7("docker", [
+      "run",
+      "--rm",
+      "--add-host=host.docker.internal:host-gateway",
+      IMAGE_TAG,
+      "curl",
+      "-sf",
+      "--max-time",
+      "5",
+      "http://host.docker.internal:4318/v1/status"
+    ], {
+      stdio: "pipe",
+      timeout: 3e4
+    });
+    result.otelReachable = true;
+  } catch {
+    result.otelReachable = false;
+  }
+  return result;
+}
+function cleanupVerifyEnv(storyKey) {
+  if (!isValidStoryKey(storyKey)) {
+    throw new Error(`Invalid story key: ${storyKey}. Keys must contain only alphanumeric characters, hyphens, and underscores.`);
+  }
+  const workspace = `${TEMP_PREFIX}${storyKey}`;
+  const containerName = `codeharness-verify-${storyKey}`;
+  if (existsSync21(workspace)) {
+    rmSync2(workspace, { recursive: true, force: true });
+  }
+  try {
+    execFileSync7("docker", ["stop", containerName], {
+      stdio: "pipe",
+      timeout: 15e3
+    });
+  } catch {
+  }
+  try {
+    execFileSync7("docker", ["rm", "-f", containerName], {
+      stdio: "pipe",
+      timeout: 15e3
+    });
+  } catch {
+  }
+}
+function resolveDockerfileTemplate(projectDir) {
+  const local = join20(projectDir, "templates", "Dockerfile.verify");
+  if (existsSync21(local)) return local;
+  const pkgDir = new URL("../../", import.meta.url).pathname;
+  const pkg = join20(pkgDir, "templates", "Dockerfile.verify");
+  if (existsSync21(pkg)) return pkg;
+  throw new Error("Dockerfile.verify not found. Ensure templates/Dockerfile.verify exists in the project or installed package.");
+}
+function dockerImageExists(tag) {
+  try {
+    execFileSync7("docker", ["image", "inspect", tag], {
+      stdio: "pipe",
+      timeout: 1e4
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function getImageSize(tag) {
+  try {
+    const output = execFileSync7("docker", ["image", "inspect", tag, "--format", "{{.Size}}"], {
+      stdio: "pipe",
+      timeout: 1e4
+    }).toString().trim();
+    const bytes = parseInt(output, 10);
+    if (isNaN(bytes)) return output;
+    if (bytes >= 1e9) return `${(bytes / 1e9).toFixed(1)}GB`;
+    if (bytes >= 1e6) return `${(bytes / 1e6).toFixed(1)}MB`;
+    if (bytes >= 1e3) return `${(bytes / 1e3).toFixed(1)}KB`;
+    return `${bytes}B`;
+  } catch {
+    return "unknown";
+  }
+}
+
+// src/commands/verify-env.ts
+function registerVerifyEnvCommand(program) {
+  const verifyEnv = program.command("verify-env").description("Manage verification environment (Docker image + clean workspace)");
+  verifyEnv.command("build").description("Build the verification Docker image from project artifacts").action((_opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    const isJson = globalOpts.json === true;
+    try {
+      const result = buildVerifyImage();
+      if (isJson) {
+        jsonOutput({
+          status: "ok",
+          imageTag: result.imageTag,
+          imageSize: result.imageSize,
+          buildTimeMs: result.buildTimeMs,
+          cached: result.cached
+        });
+      } else {
+        if (result.cached) {
+          ok(`Image ${result.imageTag}: up to date (cached)`);
+        } else {
+          ok(`Image ${result.imageTag}: built in ${result.buildTimeMs}ms (${result.imageSize})`);
+        }
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      if (isJson) {
+        jsonOutput({ status: "fail", message });
+      } else {
+        fail(message);
+      }
+      process.exitCode = 1;
+    }
+  });
+  verifyEnv.command("prepare").description("Create a clean temp workspace for verification").requiredOption("--story <key>", "Story key (e.g., 13-1-verification-dockerfile-generator)").action((opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    const isJson = globalOpts.json === true;
+    try {
+      const workspace = prepareVerifyWorkspace(opts.story);
+      if (isJson) {
+        jsonOutput({ status: "ok", workspace, storyKey: opts.story });
+      } else {
+        ok(`Workspace prepared: ${workspace}`);
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      if (isJson) {
+        jsonOutput({ status: "fail", message });
+      } else {
+        fail(message);
+      }
+      process.exitCode = 1;
+    }
+  });
+  verifyEnv.command("check").description("Validate verification environment (image, CLI, observability)").action((_opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    const isJson = globalOpts.json === true;
+    const result = checkVerifyEnv();
+    const allPassed = result.imageExists && result.cliWorks && result.otelReachable;
+    if (isJson) {
+      const jsonResult = {
+        status: allPassed ? "ok" : "fail",
+        imageExists: result.imageExists,
+        cliWorks: result.cliWorks,
+        otelReachable: result.otelReachable
+      };
+      if (result.imageExists && !result.cliWorks) {
+        jsonResult.message = "CLI does not work inside verification container \u2014 build or packaging is broken";
+      }
+      jsonOutput(jsonResult);
+    } else {
+      info(`Image exists: ${result.imageExists ? "yes" : "no"}`);
+      info(`CLI works in container: ${result.cliWorks ? "yes" : "no"}`);
+      info(`OTEL endpoints reachable: ${result.otelReachable ? "yes" : "no"}`);
+      if (allPassed) {
+        ok("Verification environment: ready");
+      } else {
+        fail("Verification environment: not ready");
+        if (!result.imageExists) {
+          info("Run: codeharness verify-env build");
+        }
+        if (result.imageExists && !result.cliWorks) {
+          fail("CLI does not work inside verification container \u2014 build or packaging is broken");
+        }
+        if (!result.otelReachable) {
+          info("Run: codeharness stack start");
+        }
+      }
+    }
+    if (!allPassed) {
+      process.exitCode = 1;
+    }
+  });
+  verifyEnv.command("cleanup").description("Remove temp workspace and stop/remove container for a story").requiredOption("--story <key>", "Story key (e.g., 13-1-verification-dockerfile-generator)").action((opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    const isJson = globalOpts.json === true;
+    try {
+      cleanupVerifyEnv(opts.story);
+      if (isJson) {
+        jsonOutput({ status: "ok", storyKey: opts.story, message: "Cleanup complete" });
+      } else {
+        ok(`Cleanup complete for story: ${opts.story}`);
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      if (isJson) {
+        jsonOutput({ status: "fail", message });
+      } else {
+        fail(message);
+      }
+      process.exitCode = 1;
+    }
+  });
+}
+
+// src/commands/retry.ts
+import { join as join22 } from "path";
+
+// src/lib/retry-state.ts
+import { existsSync as existsSync22, readFileSync as readFileSync19, writeFileSync as writeFileSync12 } from "fs";
+import { join as join21 } from "path";
+var RETRIES_FILE = ".story_retries";
+var FLAGGED_FILE = ".flagged_stories";
+var LINE_PATTERN = /^([^=]+)=(\d+)$/;
+function retriesPath(dir) {
+  return join21(dir, RETRIES_FILE);
+}
+function flaggedPath(dir) {
+  return join21(dir, FLAGGED_FILE);
+}
+function readRetries(dir) {
+  const filePath = retriesPath(dir);
+  if (!existsSync22(filePath)) {
+    return /* @__PURE__ */ new Map();
+  }
+  const raw = readFileSync19(filePath, "utf-8");
+  const result = /* @__PURE__ */ new Map();
+  for (const line of raw.split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed === "") continue;
+    const match = LINE_PATTERN.exec(trimmed);
+    if (!match) {
+      warn(`Ignoring malformed retry line: ${trimmed}`);
+      continue;
+    }
+    const key = match[1];
+    const count = parseInt(match[2], 10);
+    result.set(key, count);
+  }
+  return result;
+}
+function writeRetries(dir, retries) {
+  const filePath = retriesPath(dir);
+  const lines = [];
+  for (const [key, count] of retries) {
+    lines.push(`${key}=${count}`);
+  }
+  writeFileSync12(filePath, lines.length > 0 ? lines.join("\n") + "\n" : "", "utf-8");
+}
+function resetRetry(dir, storyKey) {
+  if (storyKey) {
+    const retries = readRetries(dir);
+    retries.delete(storyKey);
+    writeRetries(dir, retries);
+    removeFlaggedStory(dir, storyKey);
+  } else {
+    writeRetries(dir, /* @__PURE__ */ new Map());
+    writeFlaggedStories(dir, []);
+  }
+}
+function readFlaggedStories(dir) {
+  const filePath = flaggedPath(dir);
+  if (!existsSync22(filePath)) {
+    return [];
+  }
+  const raw = readFileSync19(filePath, "utf-8");
+  return raw.split("\n").map((l) => l.trim()).filter((l) => l !== "");
+}
+function writeFlaggedStories(dir, stories) {
+  const filePath = flaggedPath(dir);
+  writeFileSync12(filePath, stories.length > 0 ? stories.join("\n") + "\n" : "", "utf-8");
+}
+function removeFlaggedStory(dir, key) {
+  const stories = readFlaggedStories(dir);
+  const filtered = stories.filter((s) => s !== key);
+  writeFlaggedStories(dir, filtered);
+}
+
+// src/commands/retry.ts
+var RALPH_SUBDIR = "ralph";
+function isValidStoryKey3(key) {
+  if (!key || key.includes("..") || key.includes("/") || key.includes("\\")) {
+    return false;
+  }
+  return /^[a-zA-Z0-9_-]+$/.test(key);
+}
+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 = join22(process.cwd(), RALPH_SUBDIR);
+    if (opts.story && !isValidStoryKey3(opts.story)) {
+      if (isJson) {
+        jsonOutput({ status: "fail", message: `Invalid story key: ${opts.story}` });
+      } else {
+        warn(`Invalid story key: ${opts.story}`);
+      }
+      process.exitCode = 1;
+      return;
+    }
+    if (opts.reset) {
+      handleReset(dir, opts.story, isJson);
+      return;
+    }
+    if (opts.story && !opts.status) {
+      warn("--story without --reset or --status; showing status for that story");
+    }
+    handleStatus(dir, isJson, opts.story);
+  });
+}
+function handleReset(dir, storyKey, isJson) {
+  if (storyKey) {
+    resetRetry(dir, storyKey);
+    if (isJson) {
+      jsonOutput({ status: "ok", action: "reset", story: storyKey });
+    } else {
+      ok(`Retry counter and flagged status cleared for ${storyKey}`);
+    }
+  } else {
+    resetRetry(dir);
+    if (isJson) {
+      jsonOutput({ status: "ok", action: "reset_all" });
+    } else {
+      ok("All retry counters and flagged stories cleared");
+    }
+  }
+}
+function handleStatus(dir, isJson, filterStory) {
+  const retries = readRetries(dir);
+  const flagged = new Set(readFlaggedStories(dir));
+  if (isJson) {
+    const entries = {};
+    for (const [key, count] of retries) {
+      if (filterStory && key !== filterStory) continue;
+      entries[key] = { count, flagged: flagged.has(key) };
+    }
+    for (const key of flagged) {
+      if (filterStory && key !== filterStory) continue;
+      if (!entries[key]) {
+        entries[key] = { count: 0, flagged: true };
+      }
+    }
+    jsonOutput({ status: "ok", entries });
+    return;
+  }
+  const allKeys = /* @__PURE__ */ new Set([...retries.keys(), ...flagged]);
+  const displayKeys = filterStory ? [...allKeys].filter((k) => k === filterStory) : [...allKeys];
+  if (displayKeys.length === 0) {
+    console.log("No retry entries.");
+    return;
+  }
+  console.log("Story                                  Retries  Flagged");
+  console.log("\u2500".repeat(55));
+  for (const key of displayKeys) {
+    const count = retries.get(key) ?? 0;
+    const isFlagged = flagged.has(key);
+    const paddedKey = key.padEnd(38);
+    const paddedCount = String(count).padStart(4);
+    const flagStr = isFlagged ? "  yes" : "  no";
+    console.log(`${paddedKey} ${paddedCount}${flagStr}`);
+  }
+}
+
 // src/index.ts
-var VERSION = true ? "0.13.0" : "0.0.0-dev";
+var VERSION = true ? "0.16.0" : "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");
@@ -6873,6 +7694,8 @@ function createProgram() {
   registerQueryCommand(program);
   registerRetroImportCommand(program);
   registerGithubImportCommand(program);
+  registerVerifyEnvCommand(program);
+  registerRetryCommand(program);
   return program;
 }
 if (!process.env["VITEST"]) {