codeharness 0.7.3 → 0.9.0

package/dist/index.js

@@ -822,6 +822,18 @@ function appendGapId(existingDescription, gapId) {
   return `${existingDescription}
 ${gapId}`;
 }
+function createOrFindIssue(title, gapId, opts) {
+  const issues = listIssues();
+  const existing = findExistingByGapId(gapId, issues);
+  if (existing) {
+    return { issue: existing, created: false };
+  }
+  const issue = createIssue(title, {
+    ...opts,
+    description: appendGapId(opts?.description, gapId)
+  });
+  return { issue, created: true };
+}
 function configureHookCoexistence(dir) {
   const detection = detectBeadsHooks(dir);
   if (!detection.hasHooks) {
@@ -907,6 +919,14 @@ function storyVerificationPatch() {
 - [ ] All acceptance criteria verified with real-world evidence
 - [ ] Test coverage meets target (100%)
 
+### Verification Tags
+
+For each AC, append a verification tag to indicate how it can be verified:
+- \`<!-- verification: cli-verifiable -->\` \u2014 AC can be verified by running CLI commands in a subprocess
+- \`<!-- verification: integration-required -->\` \u2014 AC requires integration testing, multi-system interaction, or manual verification
+
+ACs referencing workflows, sprint planning, user sessions, or external system interactions should be tagged as \`integration-required\`. If no tag is present, a heuristic classifier will attempt to determine verifiability at runtime.
+
 ## Documentation Requirements
 
 - [ ] Relevant AGENTS.md files updated (list modules touched)
@@ -971,9 +991,15 @@ function retroEnforcementPatch() {
 function sprintBeadsPatch() {
   return `## Codeharness Backlog Integration
 
+### Pre-Triage Import Verification
+- [ ] Confirm \`codeharness retro-import\` was run for all completed retrospectives
+- [ ] Confirm \`codeharness github-import\` was run to pull labeled GitHub issues
+- [ ] Verify all sources are reflected in beads before starting triage
+
 ### Beads Issue Status
 - [ ] Run \`bd ready\` to display issues ready for development
 - [ ] Review beads issue counts by status (open, in-progress, done)
+- [ ] Verify issues from all sources are visible: retro (\`[gap:retro:...]\`), GitHub (\`[source:github:...]\`), and manual
 - [ ] Verify no blocked issues without documented reason
 
 ### Sprint Readiness
@@ -981,12 +1007,46 @@ function sprintBeadsPatch() {
 - [ ] Dependencies between stories are reflected in beads deps
 - [ ] Capacity aligns with estimated story complexity`;
 }
+function sprintPlanningRetroPatch() {
+  return `## Retrospective Action Items Review
+
+### Unresolved Action Items from Previous Retrospectives
+
+Before starting sprint planning, review all completed retrospectives for unresolved action items:
+
+1. **Scan for retrospective files:** Look for all \`epic-N-retrospective.md\` files in \`_bmad-output/implementation-artifacts/\`
+2. **Import retro findings to beads:** For each retrospective not yet imported, run \`codeharness retro-import --epic N\` to classify findings and create beads issues with \`[gap:retro:epic-N-item-M]\` gap-ids
+3. **Import GitHub issues to beads:** Run \`codeharness github-import\` to pull labeled issues into beads with \`[source:github:owner/repo#N]\` gap-ids
+4. **Display combined backlog:** Run \`bd ready\` to present the unified backlog containing retro findings, GitHub issues, and manually created issues
+5. **Identify unresolved items:** Filter for action items that are NOT marked as completed/done
+6. **Surface during planning:** Present unresolved items to the team before selecting stories for the sprint
+
+### Source-Aware Backlog Presentation
+
+When presenting the backlog during triage, issues should be identifiable by source:
+
+- **Retro findings** have gap-ids matching \`[gap:retro:...]\` \u2014 originated from retrospective action items
+- **GitHub issues** have gap-ids matching \`[source:github:...]\` \u2014 imported from GitHub via label query
+- **Manual issues** have no gap-id prefix \u2014 created directly in beads
+
+### Integration with Sprint Planning
+
+- [ ] All \`epic-N-retrospective.md\` files scanned for action items
+- [ ] \`codeharness retro-import --epic N\` run for each unimported retrospective
+- [ ] \`codeharness github-import\` run to pull labeled GitHub issues
+- [ ] \`bd ready\` run to display combined backlog from all sources
+- [ ] Unresolved action items listed and reviewed
+- [ ] Relevant action items incorporated into sprint goals or new stories
+- [ ] Recurring issues from multiple retros flagged for systemic fixes
+- [ ] All sources (retro, GitHub, manual) triaged uniformly \u2014 no source left unreviewed`;
+}
 var PATCH_TEMPLATES = {
   "story-verification": storyVerificationPatch,
   "dev-enforcement": devEnforcementPatch,
   "review-enforcement": reviewEnforcementPatch,
   "retro-enforcement": retroEnforcementPatch,
-  "sprint-beads": sprintBeadsPatch
+  "sprint-beads": sprintBeadsPatch,
+  "sprint-retro": sprintPlanningRetroPatch
 };
 
 // src/lib/bmad.ts
@@ -1003,7 +1063,8 @@ var PATCH_TARGETS = {
   "dev-enforcement": "bmm/workflows/4-implementation/dev-story/checklist.md",
   "review-enforcement": "bmm/workflows/4-implementation/code-review/checklist.md",
   "retro-enforcement": "bmm/workflows/4-implementation/retrospective/instructions.md",
-  "sprint-beads": "bmm/workflows/4-implementation/sprint-planning/checklist.md"
+  "sprint-beads": "bmm/workflows/4-implementation/sprint-planning/checklist.md",
+  "sprint-retro": "bmm/workflows/4-implementation/sprint-planning/instructions.md"
 };
 function isBmadInstalled(dir) {
   const bmadDir = join5(dir ?? process.cwd(), "_bmad");
@@ -1064,8 +1125,7 @@ function installBmad(dir) {
   return {
     status: "installed",
     version,
-    patches_applied: [],
-    bmalph_detected: false
+    patches_applied: []
   };
 }
 function applyAllPatches(dir) {
@@ -1288,7 +1348,7 @@ function importStoriesToBeads(stories, opts, beadsFns) {
 }
 
 // src/commands/init.ts
-var HARNESS_VERSION = true ? "0.7.3" : "0.0.0-dev";
+var HARNESS_VERSION = true ? "0.9.0" : "0.0.0-dev";
 function getStackLabel(stack) {
   if (stack === "nodejs") return "Node.js (package.json)";
   if (stack === "python") return "Python";
@@ -2521,6 +2581,29 @@ var DB_KEYWORDS = [
   "sql",
   "table"
 ];
+var INTEGRATION_KEYWORDS = [
+  "sprint planning",
+  "workflow",
+  "run /command",
+  "user session",
+  "multi-step",
+  "external system",
+  "real infrastructure",
+  "integration test",
+  "manual verification"
+];
+function classifyVerifiability(description) {
+  const lower = description.toLowerCase();
+  for (const kw of INTEGRATION_KEYWORDS) {
+    if (lower.includes(kw)) return "integration-required";
+  }
+  return "cli-verifiable";
+}
+var VERIFICATION_TAG_PATTERN = /<!--\s*verification:\s*(cli-verifiable|integration-required)\s*-->/;
+function parseVerificationTag(text) {
+  const match = VERIFICATION_TAG_PATTERN.exec(text);
+  return match ? match[1] : null;
+}
 function classifyAC(description) {
   const lower = description.toLowerCase();
   for (const kw of UI_KEYWORDS) {
@@ -2570,10 +2653,13 @@ function parseStoryACs(storyFilePath) {
     if (currentId !== null && currentDesc.length > 0) {
       const description = currentDesc.join(" ").trim();
       if (description) {
+        const tag = parseVerificationTag(description);
+        const verifiability = tag ?? classifyVerifiability(description);
         acs.push({
           id: currentId,
           description,
-          type: classifyAC(description)
+          type: classifyAC(description),
+          verifiability
         });
       } else {
         warn(`Skipping malformed AC #${currentId}: empty description`);
@@ -2712,6 +2798,62 @@ function getNewestSourceMtime(dir) {
   walk(dir);
   return newest;
 }
+function getSourceFilesInModule(modulePath) {
+  const files = [];
+  function walk(current) {
+    let entries;
+    try {
+      entries = readdirSync2(current);
+    } catch {
+      return;
+    }
+    const dirName = current.split("/").pop() ?? "";
+    if (dirName === "node_modules" || dirName === ".git" || dirName === "__tests__" || dirName === "dist" || dirName === "coverage" || dirName.startsWith(".") && current !== modulePath) return;
+    for (const entry of entries) {
+      const fullPath = join9(current, entry);
+      let stat;
+      try {
+        stat = statSync(fullPath);
+      } catch {
+        continue;
+      }
+      if (stat.isDirectory()) {
+        walk(fullPath);
+      } else if (stat.isFile()) {
+        const ext = getExtension(entry);
+        if (SOURCE_EXTENSIONS.has(ext) && !isTestFile(entry)) {
+          files.push(entry);
+        }
+      }
+    }
+  }
+  walk(modulePath);
+  return files;
+}
+function getMentionedFilesInAgentsMd(agentsPath) {
+  if (!existsSync11(agentsPath)) return [];
+  const content = readFileSync9(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);
+    }
+  }
+  return Array.from(mentioned);
+}
+function checkAgentsMdCompleteness(agentsPath, modulePath) {
+  const sourceFiles = getSourceFilesInModule(modulePath);
+  const mentionedFiles = new Set(getMentionedFilesInAgentsMd(agentsPath));
+  const missing = sourceFiles.filter((f) => !mentionedFiles.has(f));
+  return {
+    complete: missing.length === 0,
+    missing
+  };
+}
 function checkAgentsMdForModule(modulePath, dir) {
   const root = dir ?? process.cwd();
   const fullModulePath = join9(root, modulePath);
@@ -2730,13 +2872,15 @@ function checkAgentsMdForModule(modulePath, dir) {
   }
   const docMtime = statSync(agentsPath).mtime;
   const codeMtime = getNewestSourceMtime(fullModulePath);
-  if (codeMtime !== null && codeMtime.getTime() > docMtime.getTime()) {
+  const { complete, missing } = checkAgentsMdCompleteness(agentsPath, fullModulePath);
+  if (!complete) {
+    const missingList = missing.join(", ");
     return {
       path: relative(root, agentsPath),
       grade: "stale",
       lastModified: docMtime,
       codeLastModified: codeMtime,
-      reason: `AGENTS.md stale for module: ${modulePath}`
+      reason: `AGENTS.md stale for module: ${modulePath} \u2014 missing: ${missingList}`
     };
   }
   return {
@@ -2766,22 +2910,30 @@ function scanDocHealth(dir) {
   if (existsSync11(rootAgentsPath)) {
     if (modules.length > 0) {
       const docMtime = statSync(rootAgentsPath).mtime;
-      let newestCode = null;
+      let allMissing = [];
       let staleModule = "";
+      let newestCode = null;
       for (const mod of modules) {
-        const modMtime = getNewestSourceMtime(join9(root, mod));
+        const fullModPath = join9(root, mod);
+        const modAgentsPath = join9(fullModPath, "AGENTS.md");
+        if (existsSync11(modAgentsPath)) continue;
+        const { missing } = checkAgentsMdCompleteness(rootAgentsPath, fullModPath);
+        if (missing.length > 0 && staleModule === "") {
+          staleModule = mod;
+          allMissing = missing;
+        }
+        const modMtime = getNewestSourceMtime(fullModPath);
         if (modMtime !== null && (newestCode === null || modMtime.getTime() > newestCode.getTime())) {
           newestCode = modMtime;
-          staleModule = mod;
         }
       }
-      if (newestCode !== null && newestCode.getTime() > docMtime.getTime()) {
+      if (allMissing.length > 0) {
         documents.push({
           path: "AGENTS.md",
           grade: "stale",
           lastModified: docMtime,
           codeLastModified: newestCode,
-          reason: `AGENTS.md stale for module: ${staleModule}`
+          reason: `AGENTS.md stale for module: ${staleModule} \u2014 missing: ${allMissing.join(", ")}`
         });
       } else {
         documents.push({
@@ -3137,10 +3289,44 @@ function runShowboatVerify(proofPath) {
     return { passed: false, output: stdout || stderr || message };
   }
 }
-function proofHasContent(proofPath) {
-  if (!existsSync12(proofPath)) return false;
+function validateProofQuality(proofPath) {
+  if (!existsSync12(proofPath)) {
+    return { verified: 0, pending: 0, escalated: 0, total: 0, passed: false };
+  }
   const content = readFileSync10(proofPath, "utf-8");
-  return content.includes("<!-- /showboat exec -->") || content.includes("<!-- showboat image:");
+  const acHeaderPattern = /^## AC \d+:/gm;
+  const matches = [...content.matchAll(acHeaderPattern)];
+  if (matches.length === 0) {
+    return { verified: 0, pending: 0, escalated: 0, total: 0, passed: false };
+  }
+  let verified = 0;
+  let pending = 0;
+  let escalated = 0;
+  for (let i = 0; i < matches.length; i++) {
+    const start = matches[i].index;
+    const end = i + 1 < matches.length ? matches[i + 1].index : content.length;
+    const section = content.slice(start, end);
+    if (section.includes("[ESCALATE]")) {
+      escalated++;
+      continue;
+    }
+    const hasEvidence = section.includes("<!-- /showboat exec -->") || section.includes("<!-- showboat image:") || /```(?:bash|shell)\n[\s\S]*?```\n+```output\n/m.test(section);
+    if (hasEvidence) {
+      verified++;
+    } else {
+      pending++;
+    }
+  }
+  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
+  };
 }
 function updateVerificationState(storyId, result, dir) {
   const { state, body } = readStateWithBody(dir);
@@ -3182,123 +3368,189 @@ function isValidStoryId(storyId) {
   return /^[a-zA-Z0-9_-]+$/.test(storyId);
 }
 function registerVerifyCommand(program) {
-  program.command("verify").description("Run verification pipeline on completed work").requiredOption("--story <id>", "Story ID to verify").action((opts, cmd) => {
+  program.command("verify").description("Run verification pipeline on completed work").option("--story <id>", "Story ID to verify").option("--retro", "Verify retrospective completion for an epic").option("--epic <n>", "Epic number (required with --retro)").action((opts, cmd) => {
     const globalOpts = cmd.optsWithGlobals();
     const isJson = globalOpts.json === true;
-    const storyId = opts.story;
     const root = process.cwd();
-    if (!isValidStoryId(storyId)) {
-      fail(`Invalid story ID: ${storyId}. Story IDs must contain only alphanumeric characters, hyphens, and underscores.`, { json: isJson });
-      process.exitCode = 1;
+    if (opts.retro) {
+      verifyRetro(opts, isJson, root);
       return;
     }
-    const storyFilePath = join11(root, STORY_DIR, `${storyId}.md`);
-    if (!existsSync13(storyFilePath)) {
-      fail(`Story file not found: ${storyFilePath}`, { json: isJson });
+    if (!opts.story) {
+      fail("--story is required when --retro is not set", { json: isJson });
       process.exitCode = 1;
       return;
     }
-    let preconditions;
-    try {
-      preconditions = checkPreconditions(root, storyId);
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      fail(`Precondition check failed: ${message}`, { json: isJson });
-      process.exitCode = 1;
-      return;
+    verifyStory(opts.story, isJson, root);
+  });
+}
+function verifyRetro(opts, isJson, root) {
+  if (!opts.epic) {
+    fail("--epic is required with --retro", { json: isJson });
+    process.exitCode = 1;
+    return;
+  }
+  const epicNum = parseInt(opts.epic, 10);
+  if (isNaN(epicNum) || epicNum < 1) {
+    fail(`Invalid epic number: ${opts.epic}`, { json: isJson });
+    process.exitCode = 1;
+    return;
+  }
+  const retroFile = `epic-${epicNum}-retrospective.md`;
+  const retroPath = join11(root, STORY_DIR, retroFile);
+  if (!existsSync13(retroPath)) {
+    if (isJson) {
+      jsonOutput({ status: "fail", epic: epicNum, retroFile, message: `${retroFile} not found` });
+    } else {
+      fail(`${retroFile} not found`);
     }
-    if (!preconditions.passed) {
-      if (isJson) {
-        jsonOutput({
-          status: "fail",
-          message: "Preconditions not met",
-          failures: preconditions.failures
-        });
-      } else {
-        fail("Preconditions not met:");
-        for (const f of preconditions.failures) {
-          info(`  - ${f}`);
-        }
+    process.exitCode = 1;
+    return;
+  }
+  const retroKey = `epic-${epicNum}-retrospective`;
+  try {
+    updateSprintStatus(retroKey, "done", root);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    warn(`Failed to update sprint status: ${message}`);
+  }
+  if (isJson) {
+    jsonOutput({ status: "ok", epic: epicNum, retroFile: join11(STORY_DIR, retroFile) });
+  } else {
+    ok(`Epic ${epicNum} retrospective: marked done`);
+  }
+}
+function verifyStory(storyId, isJson, root) {
+  if (!isValidStoryId(storyId)) {
+    fail(`Invalid story ID: ${storyId}. Story IDs must contain only alphanumeric characters, hyphens, and underscores.`, { json: isJson });
+    process.exitCode = 1;
+    return;
+  }
+  const storyFilePath = join11(root, STORY_DIR, `${storyId}.md`);
+  if (!existsSync13(storyFilePath)) {
+    fail(`Story file not found: ${storyFilePath}`, { json: isJson });
+    process.exitCode = 1;
+    return;
+  }
+  let preconditions;
+  try {
+    preconditions = checkPreconditions(root, storyId);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    fail(`Precondition check failed: ${message}`, { json: isJson });
+    process.exitCode = 1;
+    return;
+  }
+  if (!preconditions.passed) {
+    if (isJson) {
+      jsonOutput({
+        status: "fail",
+        message: "Preconditions not met",
+        failures: preconditions.failures
+      });
+    } else {
+      fail("Preconditions not met:");
+      for (const f of preconditions.failures) {
+        info(`  - ${f}`);
       }
-      process.exitCode = 1;
-      return;
     }
-    let acs;
-    try {
-      acs = parseStoryACs(storyFilePath);
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      fail(`Failed to parse story file: ${message}`, { json: isJson });
+    process.exitCode = 1;
+    return;
+  }
+  let acs;
+  try {
+    acs = parseStoryACs(storyFilePath);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    fail(`Failed to parse story file: ${message}`, { json: isJson });
+    process.exitCode = 1;
+    return;
+  }
+  const storyTitle = extractStoryTitle(storyFilePath);
+  const expectedProofPath = join11(root, "verification", `${storyId}-proof.md`);
+  const proofPath = existsSync13(expectedProofPath) ? expectedProofPath : createProofDocument(storyId, storyTitle, acs, root);
+  const proofQuality = validateProofQuality(proofPath);
+  if (!proofQuality.passed) {
+    if (isJson) {
+      jsonOutput({
+        status: "fail",
+        message: `Proof quality check failed: ${proofQuality.verified}/${proofQuality.total} ACs verified`,
+        proofQuality: { verified: proofQuality.verified, pending: proofQuality.pending, escalated: proofQuality.escalated, total: proofQuality.total }
+      });
+    } else {
+      fail(`Proof quality check failed: ${proofQuality.verified}/${proofQuality.total} ACs verified`);
+    }
+    process.exitCode = 1;
+    return;
+  }
+  if (proofQuality.escalated > 0) {
+    warn(`Story ${storyId} has ${proofQuality.escalated} ACs requiring integration verification`);
+    info("Run these ACs manually or in a dedicated verification session");
+  }
+  let showboatStatus = "skipped";
+  const showboatResult = runShowboatVerify(proofPath);
+  if (showboatResult.output === "showboat not available") {
+    showboatStatus = "skipped";
+    warn("Showboat not installed \u2014 skipping re-verification");
+  } else {
+    showboatStatus = showboatResult.passed ? "pass" : "fail";
+    if (!showboatResult.passed) {
+      fail(`Showboat verify failed: ${showboatResult.output}`, { json: isJson });
       process.exitCode = 1;
       return;
     }
-    const storyTitle = extractStoryTitle(storyFilePath);
-    const proofPath = createProofDocument(storyId, storyTitle, acs, root);
-    let showboatStatus = "skipped";
-    if (proofHasContent(proofPath)) {
-      const showboatResult = runShowboatVerify(proofPath);
-      if (showboatResult.output === "showboat not available") {
-        showboatStatus = "skipped";
-        warn("Showboat not installed \u2014 skipping re-verification");
-      } else {
-        showboatStatus = showboatResult.passed ? "pass" : "fail";
-        if (!showboatResult.passed) {
-          fail(`Showboat verify failed: ${showboatResult.output}`, { json: isJson });
-          process.exitCode = 1;
-          return;
-        }
-      }
-    }
-    const acsVerified = showboatStatus === "pass";
-    const verifiedCount = acsVerified ? acs.length : 0;
-    const result = {
-      storyId,
-      success: true,
-      totalACs: acs.length,
-      verifiedCount,
-      failedCount: acs.length - verifiedCount,
-      proofPath: `verification/${storyId}-proof.md`,
-      showboatVerifyStatus: showboatStatus,
-      perAC: acs.map((ac) => ({
-        id: ac.id,
-        description: ac.description,
-        verified: acsVerified,
-        evidencePaths: []
-      }))
-    };
-    try {
-      updateVerificationState(storyId, result, root);
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      warn(`Failed to update state: ${message}`);
-    }
-    try {
-      closeBeadsIssue(storyId, root);
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      warn(`Failed to close beads issue: ${message}`);
-    }
-    try {
-      const completedPath = completeExecPlan(storyId, root);
-      if (completedPath) {
-        if (!isJson) {
-          ok(`Exec-plan moved to completed: ${completedPath}`);
-        }
-      } else {
-        if (!isJson) {
-          warn(`No exec-plan found for story: ${storyId}`);
-        }
+  }
+  const result = {
+    storyId,
+    success: true,
+    totalACs: proofQuality.total,
+    verifiedCount: proofQuality.verified,
+    failedCount: proofQuality.pending,
+    escalatedCount: proofQuality.escalated,
+    proofPath: `verification/${storyId}-proof.md`,
+    showboatVerifyStatus: showboatStatus,
+    perAC: acs.map((ac) => ({
+      id: ac.id,
+      description: ac.description,
+      verified: true,
+      evidencePaths: []
+    }))
+  };
+  try {
+    updateVerificationState(storyId, result, root);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    warn(`Failed to update state: ${message}`);
+  }
+  try {
+    closeBeadsIssue(storyId, root);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    warn(`Failed to close beads issue: ${message}`);
+  }
+  try {
+    const completedPath = completeExecPlan(storyId, root);
+    if (completedPath) {
+      if (!isJson) {
+        ok(`Exec-plan moved to completed: ${completedPath}`);
       }
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      warn(`Failed to complete exec-plan: ${message}`);
-    }
-    if (isJson) {
-      jsonOutput(result);
     } else {
-      ok(`Story ${storyId}: verified \u2014 proof at verification/${storyId}-proof.md`);
+      if (!isJson) {
+        warn(`No exec-plan found for story: ${storyId}`);
+      }
     }
-  });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    warn(`Failed to complete exec-plan: ${message}`);
+  }
+  if (isJson) {
+    jsonOutput({
+      ...result,
+      proofQuality: { verified: proofQuality.verified, pending: proofQuality.pending, escalated: proofQuality.escalated, total: proofQuality.total }
+    });
+  } else {
+    ok(`Story ${storyId}: verified \u2014 proof at verification/${storyId}-proof.md`);
+  }
 }
 function extractStoryTitle(filePath) {
   try {
@@ -6085,8 +6337,453 @@ function registerQueryCommand(program) {
   });
 }
 
+// src/commands/retro-import.ts
+import { existsSync as existsSync20, readFileSync as readFileSync16 } from "fs";
+import { join as join19 } from "path";
+
+// src/lib/retro-parser.ts
+var KNOWN_TOOLS = ["showboat", "ralph", "beads", "bmad"];
+function parseRetroActionItems(content) {
+  const lines = content.split("\n");
+  const items = [];
+  let inTable = false;
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!inTable && /^\|\s*#\s*\|\s*Action\s*\|\s*Status\s*\|\s*Notes\s*\|/i.test(trimmed)) {
+      inTable = true;
+      continue;
+    }
+    if (inTable && /^\|[\s\-|]+\|$/.test(trimmed)) {
+      continue;
+    }
+    if (inTable && trimmed.startsWith("|")) {
+      const cells = trimmed.split("|").slice(1, -1).map((c) => c.trim());
+      if (cells.length >= 4) {
+        const number = cells[0];
+        const description = cells[1];
+        const status = cells[2];
+        const notes = cells[3];
+        if (/^[A-Za-z]\d+$/.test(number)) {
+          items.push({ number, description, status, notes });
+        }
+      }
+    }
+    if (inTable && !trimmed.startsWith("|") && trimmed !== "") {
+      inTable = false;
+    }
+  }
+  return items;
+}
+function classifyFinding(item) {
+  const text = item.description.toLowerCase();
+  if (text.includes("harness") || text.includes("codeharness")) {
+    return { type: "harness" };
+  }
+  for (const tool of KNOWN_TOOLS) {
+    if (text.includes(tool)) {
+      return { type: "tool", name: tool };
+    }
+  }
+  return { type: "project" };
+}
+function derivePriority(item) {
+  const statusLower = item.status.toLowerCase();
+  const notesLower = item.notes.toLowerCase();
+  if (statusLower.includes("regressed") || notesLower.includes("urgent") || notesLower.includes("critical")) {
+    return 1;
+  }
+  return 2;
+}
+
+// src/lib/github.ts
+import { execFileSync as execFileSync6 } from "child_process";
+var GitHubError = class extends Error {
+  constructor(command, originalMessage) {
+    super(`GitHub CLI failed: ${originalMessage}. Command: ${command}`);
+    this.command = command;
+    this.originalMessage = originalMessage;
+    this.name = "GitHubError";
+  }
+};
+function isGhAvailable() {
+  try {
+    execFileSync6("which", ["gh"], { stdio: "pipe", timeout: 5e3 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function ghIssueCreate(repo, title, body, labels) {
+  const args = ["issue", "create", "--repo", repo, "--title", title, "--body", body];
+  for (const label of labels) {
+    args.push("--label", label);
+  }
+  args.push("--json", "number,url");
+  const cmdStr = `gh ${args.join(" ")}`;
+  try {
+    const output = execFileSync6("gh", args, {
+      stdio: "pipe",
+      timeout: 3e4
+    });
+    const result = JSON.parse(output.toString().trim());
+    return result;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new GitHubError(cmdStr, message);
+  }
+}
+function ghIssueSearch(repo, query) {
+  const args = ["issue", "list", "--repo", repo, "--search", query, "--state", "all", "--json", "number,title,body,url,labels"];
+  const cmdStr = `gh ${args.join(" ")}`;
+  try {
+    const output = execFileSync6("gh", args, {
+      stdio: "pipe",
+      timeout: 3e4
+    });
+    const text = output.toString().trim();
+    if (!text) return [];
+    return JSON.parse(text);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new GitHubError(cmdStr, message);
+  }
+}
+function findExistingGhIssue(repo, gapId) {
+  try {
+    const issues = ghIssueSearch(repo, gapId);
+    return issues.find((issue) => issue.body?.includes(gapId));
+  } catch {
+    return void 0;
+  }
+}
+function getRepoFromRemote() {
+  try {
+    const output = execFileSync6("git", ["remote", "get-url", "origin"], {
+      stdio: "pipe",
+      timeout: 5e3
+    });
+    const url = output.toString().trim();
+    return parseRepoFromUrl(url);
+  } catch {
+    return void 0;
+  }
+}
+function parseRepoFromUrl(url) {
+  const sshMatch = url.match(/git@[^:]+:([^/]+\/[^/]+?)(?:\.git)?$/);
+  if (sshMatch) return sshMatch[1];
+  const httpsMatch = url.match(/https?:\/\/[^/]+\/([^/]+\/[^/]+?)(?:\.git)?$/);
+  if (httpsMatch) return httpsMatch[1];
+  return void 0;
+}
+function ensureLabels(repo, labels) {
+  for (const label of labels) {
+    try {
+      execFileSync6("gh", ["label", "create", label, "--repo", repo], {
+        stdio: "pipe",
+        timeout: 1e4
+      });
+    } catch {
+    }
+  }
+}
+
+// src/commands/retro-import.ts
+var STORY_DIR2 = "_bmad-output/implementation-artifacts";
+var MAX_TITLE_LENGTH = 120;
+function classificationToString(c) {
+  if (c.type === "tool") {
+    return `tool:${c.name}`;
+  }
+  return c.type;
+}
+function registerRetroImportCommand(program) {
+  program.command("retro-import").description("Import retrospective action items as beads issues").requiredOption("--epic <n>", "Epic number to import action items from").action((opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    const isJson = globalOpts.json === true;
+    const root = process.cwd();
+    const epicNum = parseInt(opts.epic, 10);
+    if (isNaN(epicNum) || epicNum < 1) {
+      fail(`Invalid epic number: ${opts.epic}`, { json: isJson });
+      process.exitCode = 1;
+      return;
+    }
+    const retroFile = `epic-${epicNum}-retrospective.md`;
+    const retroPath = join19(root, STORY_DIR2, retroFile);
+    if (!existsSync20(retroPath)) {
+      fail(`Retro file not found: ${retroFile}`, { json: isJson });
+      process.exitCode = 1;
+      return;
+    }
+    let content;
+    try {
+      content = readFileSync16(retroPath, "utf-8");
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      fail(`Failed to read retro file: ${message}`, { json: isJson });
+      process.exitCode = 1;
+      return;
+    }
+    const items = parseRetroActionItems(content);
+    if (items.length === 0) {
+      if (isJson) {
+        jsonOutput({ imported: 0, skipped: 0, issues: [] });
+      } else {
+        info("No action items found in retro file");
+      }
+      return;
+    }
+    let imported = 0;
+    let skipped = 0;
+    const issues = [];
+    for (const item of items) {
+      const classification = classifyFinding(item);
+      const priority = derivePriority(item);
+      const gapId = buildGapId("retro", `epic-${epicNum}-item-${item.number}`);
+      const title = item.description.length > MAX_TITLE_LENGTH ? item.description.slice(0, MAX_TITLE_LENGTH - 3) + "..." : item.description;
+      const retroContext = `Retro action item ${item.number} from Epic ${epicNum}.
+Status: ${item.status}
+Notes: ${item.notes}
+Classification: ${classificationToString(classification)}`;
+      try {
+        const result = createOrFindIssue(title, gapId, {
+          type: "task",
+          priority,
+          description: retroContext
+        });
+        const issueRecord = {
+          number: item.number,
+          title,
+          gapId,
+          classification: classificationToString(classification),
+          created: result.created,
+          status: item.status,
+          notes: item.notes
+        };
+        issues.push(issueRecord);
+        if (result.created) {
+          imported++;
+          if (!isJson) {
+            ok(`Imported: ${title}`);
+          }
+        } else {
+          skipped++;
+          if (!isJson) {
+            info(`Skipping existing: ${title}`);
+          }
+        }
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        fail(`Failed to import ${item.number}: ${message}`, { json: isJson });
+      }
+    }
+    const githubResult = createGitHubIssues(issues, epicNum, isJson);
+    if (isJson) {
+      jsonOutput({
+        imported,
+        skipped,
+        issues,
+        github: githubResult
+      });
+    }
+  });
+}
+function resolveTargetRepo(classification, targets) {
+  if (targets.length === 0) return void 0;
+  if (classification === "harness") {
+    const explicit = targets.find((t) => t.repo === "iVintik/codeharness");
+    if (explicit) return explicit;
+    const nonAuto = targets.find((t) => t.repo !== "auto");
+    if (nonAuto) return nonAuto;
+    return targets[0];
+  }
+  const auto = targets.find((t) => t.repo === "auto");
+  if (auto) return auto;
+  return targets[0];
+}
+function buildGitHubIssueBody(item, epicNum, projectName) {
+  return `## Retro Action Item ${item.number} \u2014 Epic ${epicNum}
+
+**Source project:** ${projectName}
+**Classification:** ${item.classification}
+**Original status:** ${item.status}
+**Notes:** ${item.notes}
+
+${item.title}
+
+<!-- gap-id: ${item.gapId} -->`;
+}
+function createGitHubIssues(issues, epicNum, isJson) {
+  let targets;
+  try {
+    const state = readState();
+    targets = state.retro_issue_targets;
+  } catch (err) {
+    if (err instanceof StateFileNotFoundError) {
+      if (!isJson) {
+        info("No state file found \u2014 skipping GitHub issues");
+      }
+      return void 0;
+    }
+    if (!isJson) {
+      info("Could not read state file \u2014 skipping GitHub issues");
+    }
+    return void 0;
+  }
+  if (!targets || targets.length === 0) {
+    if (!isJson) {
+      info("No retro_issue_targets configured \u2014 skipping GitHub issues");
+    }
+    return void 0;
+  }
+  if (!isGhAvailable()) {
+    if (!isJson) {
+      warn("gh CLI not available \u2014 skipping GitHub issue creation");
+    }
+    return void 0;
+  }
+  const resolvedAutoRepo = getRepoFromRemote();
+  const result = { created: 0, skipped: 0, errors: 0 };
+  const projectName = resolvedAutoRepo ?? "unknown";
+  for (const item of issues) {
+    const target = resolveTargetRepo(item.classification, targets);
+    if (!target) continue;
+    const repo = target.repo === "auto" ? resolvedAutoRepo : target.repo;
+    if (!repo) {
+      if (!isJson) {
+        warn(`Cannot resolve repo for ${item.number} \u2014 git remote not detected`);
+      }
+      result.errors++;
+      continue;
+    }
+    try {
+      const existing = findExistingGhIssue(repo, item.gapId);
+      if (existing) {
+        if (!isJson) {
+          info(`GitHub issue exists: ${repo}#${existing.number}`);
+        }
+        result.skipped++;
+        continue;
+      }
+      ensureLabels(repo, target.labels);
+      const body = buildGitHubIssueBody(item, epicNum, projectName);
+      const created = ghIssueCreate(repo, item.title, body, target.labels);
+      if (!isJson) {
+        ok(`GitHub issue created: ${repo}#${created.number}`);
+      }
+      result.created++;
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      if (!isJson) {
+        fail(`GitHub issue failed for ${item.number}: ${message}`);
+      }
+      result.errors++;
+    }
+  }
+  return result;
+}
+
+// src/commands/github-import.ts
+var MAX_TITLE_LENGTH2 = 120;
+function mapLabelsToType(labels) {
+  if (!labels) return "task";
+  const names = labels.map((l) => l.name);
+  if (names.includes("bug")) return "bug";
+  if (names.includes("enhancement")) return "story";
+  return "task";
+}
+function mapLabelsToPriority(labels) {
+  if (!labels) return 2;
+  const names = labels.map((l) => l.name);
+  if (names.includes("priority:high")) return 1;
+  if (names.includes("priority:low")) return 3;
+  return 2;
+}
+function registerGithubImportCommand(program) {
+  program.command("github-import").description("Import GitHub issues labeled for sprint planning into beads").option("--repo <owner/repo>", "GitHub repository (auto-detected from git remote if omitted)").option("--label <label>", "GitHub label to filter issues by", "sprint-candidate").action((opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    const isJson = globalOpts.json === true;
+    if (!isGhAvailable()) {
+      fail("gh CLI not found. Install: https://cli.github.com/", { json: isJson });
+      process.exitCode = 1;
+      return;
+    }
+    let repo = opts.repo;
+    if (!repo) {
+      repo = getRepoFromRemote();
+    }
+    if (!repo) {
+      fail("Cannot detect repo. Use --repo owner/repo", { json: isJson });
+      process.exitCode = 1;
+      return;
+    }
+    const label = opts.label;
+    let ghIssues;
+    try {
+      ghIssues = ghIssueSearch(repo, `label:${label}`);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      fail(`Failed to search GitHub issues: ${message}`, { json: isJson });
+      process.exitCode = 1;
+      return;
+    }
+    let imported = 0;
+    let skipped = 0;
+    let errors = 0;
+    const issues = [];
+    for (const ghIssue of ghIssues) {
+      const gapId = buildGapId("source", `github:${repo}#${ghIssue.number}`);
+      const type = mapLabelsToType(ghIssue.labels);
+      const priority = mapLabelsToPriority(ghIssue.labels);
+      const title = ghIssue.title.length > MAX_TITLE_LENGTH2 ? ghIssue.title.slice(0, MAX_TITLE_LENGTH2 - 3) + "..." : ghIssue.title;
+      try {
+        const result = createOrFindIssue(title, gapId, {
+          type,
+          priority,
+          description: ghIssue.body ?? ""
+        });
+        const issueRecord = {
+          number: ghIssue.number,
+          title,
+          gapId,
+          type,
+          created: result.created
+        };
+        issues.push(issueRecord);
+        if (result.created) {
+          imported++;
+          if (!isJson) {
+            ok(`Imported: ${repo}#${ghIssue.number} \u2014 ${title}`);
+          }
+        } else {
+          skipped++;
+          if (!isJson) {
+            info(`Skipping existing: ${repo}#${ghIssue.number} \u2014 ${title}`);
+          }
+        }
+      } catch (err) {
+        errors++;
+        const message = err instanceof Error ? err.message : String(err);
+        fail(`Failed to import ${repo}#${ghIssue.number}: ${message}`, { json: isJson });
+      }
+    }
+    if (errors > 0) {
+      process.exitCode = 1;
+    }
+    if (isJson) {
+      jsonOutput({
+        imported,
+        skipped,
+        errors,
+        issues
+      });
+    } else if (ghIssues.length > 0) {
+      info(`Summary: ${imported} imported, ${skipped} skipped, ${errors} errors`);
+    }
+  });
+}
+
 // src/index.ts
-var VERSION = true ? "0.7.3" : "0.0.0-dev";
+var VERSION = true ? "0.9.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");
@@ -6103,6 +6800,8 @@ function createProgram() {
   registerDocHealthCommand(program);
   registerStackCommand(program);
   registerQueryCommand(program);
+  registerRetroImportCommand(program);
+  registerGithubImportCommand(program);
   return program;
 }
 if (!process.env["VITEST"]) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codeharness",
-  "version": "0.7.3",
+  "version": "0.9.0",
   "type": "module",
   "description": "CLI for codeharness — makes autonomous coding agents produce software that actually works",
   "bin": {