@codexstar/bug-hunter 3.0.0

package/scripts/worktree-harvest.cjs

@@ -0,0 +1,516 @@
+#!/usr/bin/env node
+
+/**
+ * worktree-harvest.cjs — Worktree lifecycle manager for bug-hunter fix pipeline.
+ *
+ * Manages isolated git worktrees for Fixer subagents:
+ *   prepare       → create worktree on the fix branch
+ *   harvest       → validate Fixer commits, detect uncommitted work
+ *   checkout-fix  → return main working tree to the fix branch
+ *   cleanup       → remove a single worktree
+ *   cleanup-all   → remove all worktrees under a directory
+ *   status        → report worktree health
+ *
+ * Design (inspired by Droid Mission Control):
+ *   Workers are process-isolated but commit to the SAME branch.
+ *   The worktree checks out the fix branch directly — no cherry-picking.
+ *   The orchestrator manages the lifecycle: prepare → dispatch → harvest → cleanup.
+ */
+
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function usage() {
+  console.error('Usage:');
+  console.error('  worktree-harvest.cjs prepare     <fixBranch> <worktreeDir>');
+  console.error('  worktree-harvest.cjs harvest      <worktreeDir>');
+  console.error('  worktree-harvest.cjs checkout-fix  <fixBranch>');
+  console.error('  worktree-harvest.cjs cleanup      <worktreeDir>');
+  console.error('  worktree-harvest.cjs cleanup-all   <parentDir>');
+  console.error('  worktree-harvest.cjs status       <worktreeDir>');
+}
+
+function out(obj) {
+  console.log(JSON.stringify(obj, null, 2));
+}
+
+/** Run git with execFileSync — no shell, no injection risk. */
+function git(args, cwd) {
+  const opts = { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] };
+  if (cwd) opts.cwd = cwd;
+  return execFileSync('git', args, opts).trim();
+}
+
+/** Same as git() but returns { ok, output } instead of throwing. */
+function gitSafe(args, cwd) {
+  try {
+    return { ok: true, output: git(args, cwd) };
+  } catch (err) {
+    const stderr = err.stderr ? err.stderr.toString().trim() : '';
+    return { ok: false, output: stderr || (err.message || '').trim() };
+  }
+}
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+const MANIFEST_NAME = '.worktree-manifest.json';
+const HARVEST_NAME = '.harvest-result.json';
+const STALE_AGE_MS = 60 * 60 * 1000; // 1 hour
+
+function manifestPath(worktreeDir) {
+  return path.join(worktreeDir, MANIFEST_NAME);
+}
+
+function harvestPath(worktreeDir) {
+  return path.join(worktreeDir, HARVEST_NAME);
+}
+
+function readJsonFile(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function writeJsonFile(filePath, data) {
+  ensureDir(path.dirname(filePath));
+  fs.writeFileSync(filePath, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
+}
+
+// ---------------------------------------------------------------------------
+// prepare — create worktree on the fix branch
+// ---------------------------------------------------------------------------
+
+function prepare(fixBranch, worktreeDir) {
+  const absDir = path.resolve(worktreeDir);
+
+  // 1. Verify fix branch exists
+  const branchCheck = gitSafe(['rev-parse', '--verify', fixBranch]);
+  if (!branchCheck.ok) {
+    out({ ok: false, error: 'fix-branch-not-found', detail: branchCheck.output });
+    process.exit(1);
+  }
+
+  // 2. If worktreeDir already exists, clean up stale worktree
+  if (fs.existsSync(absDir)) {
+    gitSafe(['worktree', 'remove', absDir, '--force']);
+    if (fs.existsSync(absDir)) {
+      fs.rmSync(absDir, { recursive: true, force: true });
+    }
+    gitSafe(['worktree', 'prune']);
+  }
+
+  // 3. Detach main working tree if it's on the fix branch
+  //    (git won't allow two worktrees on the same branch)
+  const currentBranch = gitSafe(['rev-parse', '--abbrev-ref', 'HEAD']);
+  let detached = false;
+  if (currentBranch.ok && currentBranch.output === fixBranch) {
+    git(['checkout', '--detach']);
+    detached = true;
+  }
+
+  // 4. Create worktree on the fix branch
+  ensureDir(path.dirname(absDir));
+  const addResult = gitSafe(['worktree', 'add', absDir, fixBranch]);
+  if (!addResult.ok) {
+    // Restore branch if we detached
+    if (detached) gitSafe(['checkout', fixBranch]);
+    out({ ok: false, error: 'worktree-add-failed', detail: addResult.output });
+    process.exit(1);
+  }
+
+  // 5. Record pre-harvest HEAD
+  const preHarvestHead = git(['rev-parse', 'HEAD'], absDir);
+
+  // 6. Write manifest
+  const manifest = {
+    fixBranch,
+    preHarvestHead,
+    worktreeDir: absDir,
+    detachedMainTree: detached,
+    createdAtMs: Date.now(),
+    createdAt: new Date().toISOString()
+  };
+  writeJsonFile(manifestPath(absDir), manifest);
+
+  out({
+    ok: true,
+    worktreeDir: absDir,
+    fixBranch,
+    preHarvestHead,
+    detachedMainTree: detached,
+    createdAt: manifest.createdAt
+  });
+}
+
+// ---------------------------------------------------------------------------
+// harvest — validate Fixer commits and detect uncommitted work
+// ---------------------------------------------------------------------------
+
+/** Meta files written into the worktree — excluded from dirty detection. */
+const META_FILES = [MANIFEST_NAME, HARVEST_NAME];
+
+/**
+ * Core harvest logic. Returns the result object or throws on error.
+ * Does NOT call process.exit — safe for internal callers like cleanup-all.
+ */
+function harvestCore(worktreeDir) {
+  const absDir = path.resolve(worktreeDir);
+
+  // 1. Read manifest
+  const manifest = readJsonFile(manifestPath(absDir));
+  if (!manifest) {
+    throw new Error(JSON.stringify({
+      ok: false, error: 'no-manifest', detail: `${manifestPath(absDir)} not found`
+    }));
+  }
+
+  const { preHarvestHead, fixBranch } = manifest;
+
+  // 2. Verify worktree is still on the fix branch
+  const wtBranch = gitSafe(['rev-parse', '--abbrev-ref', 'HEAD'], absDir);
+  if (wtBranch.ok && wtBranch.output !== fixBranch) {
+    const result = {
+      ok: true,
+      error: 'branch-switched',
+      detail: `Fixer switched from ${fixBranch} to ${wtBranch.output}`,
+      commits: [],
+      branchSwitched: true
+    };
+    writeJsonFile(harvestPath(absDir), result);
+    return result;
+  }
+
+  // 3. Find new commits since preHarvestHead
+  const logResult = gitSafe(
+    ['log', '--oneline', '--reverse', `${preHarvestHead}..HEAD`],
+    absDir
+  );
+  const logOutput = logResult.ok ? logResult.output : '';
+  const commitLines = logOutput ? logOutput.split('\n').filter(Boolean) : [];
+
+  // 4. Parse commits
+  const commits = commitLines.map(line => {
+    const spaceIdx = line.indexOf(' ');
+    const hash = line.slice(0, spaceIdx);
+    const message = line.slice(spaceIdx + 1);
+    const bugMatch = message.match(/BUG-(\d+)/);
+    return {
+      hash,
+      message,
+      bugId: bugMatch ? `BUG-${bugMatch[1]}` : null
+    };
+  });
+
+  // 5. Check for uncommitted changes (exclude our own meta files)
+  const statusOutput = gitSafe(['status', '--porcelain'], absDir);
+  const statusLines = statusOutput.ok
+    ? statusOutput.output.split('\n').filter(Boolean)
+    : [];
+  const relevantLines = statusLines.filter(line => {
+    const fileName = line.slice(3); // strip status prefix (e.g. "?? ")
+    return !META_FILES.some(mf => fileName === mf || fileName.endsWith(`/${mf}`));
+  });
+  const dirty = relevantLines.length > 0;
+
+  let uncommittedStashed = false;
+  let stashRef = null;
+
+  if (dirty) {
+    // Stash uncommitted work so it's not lost
+    const stashMsg = `bug-hunter-fixer-uncommitted-${Date.now()}`;
+    gitSafe(['add', '-A'], absDir);
+    const stashResult = gitSafe(['stash', 'push', '-m', stashMsg], absDir);
+    if (stashResult.ok) {
+      uncommittedStashed = true;
+      const stashList = gitSafe(['stash', 'list', '--max-count=1'], absDir);
+      stashRef = stashList.ok ? stashList.output.split(':')[0] : null;
+    }
+  }
+
+  const postHarvestHead = gitSafe(['rev-parse', 'HEAD'], absDir);
+
+  const result = {
+    ok: true,
+    commits,
+    harvestedCount: commits.length,
+    noChanges: commits.length === 0 && !dirty,
+    uncommittedStashed,
+    stashRef,
+    preHarvestHead,
+    postHarvestHead: postHarvestHead.ok ? postHarvestHead.output : null
+  };
+
+  writeJsonFile(harvestPath(absDir), result);
+  return result;
+}
+
+/** CLI-facing harvest — prints result and exits on error. */
+function harvest(worktreeDir) {
+  try {
+    const result = harvestCore(worktreeDir);
+    out(result);
+  } catch (err) {
+    // Error from harvestCore is a JSON string
+    try {
+      const parsed = JSON.parse(err.message);
+      out(parsed);
+    } catch (_) {
+      out({ ok: false, error: 'harvest-failed', detail: err.message });
+    }
+    process.exit(1);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// checkout-fix — return main working tree to the fix branch
+// ---------------------------------------------------------------------------
+
+function checkoutFix(fixBranch) {
+  // Verify no non-main worktrees have this branch checked out
+  const worktreeList = git(['worktree', 'list', '--porcelain']);
+  const entries = worktreeList.split('\n\n').filter(Boolean);
+  const mainWorktree = git(['rev-parse', '--show-toplevel']);
+
+  for (const entry of entries) {
+    const lines = entry.split('\n');
+    const worktreeLine = lines.find(l => l.startsWith('worktree '));
+    const branchLine = lines.find(l => l.startsWith('branch '));
+    if (!branchLine || !worktreeLine) continue;
+
+    const branch = branchLine.replace('branch refs/heads/', '');
+    const wtPath = worktreeLine.replace('worktree ', '');
+
+    if (branch === fixBranch && wtPath !== mainWorktree) {
+      out({
+        ok: false,
+        error: 'worktree-still-active',
+        detail: `Branch ${fixBranch} is checked out in worktree: ${wtPath}`
+      });
+      process.exit(1);
+    }
+  }
+
+  const result = gitSafe(['checkout', fixBranch]);
+  if (!result.ok) {
+    out({ ok: false, error: 'checkout-failed', detail: result.output });
+    process.exit(1);
+  }
+
+  const head = git(['rev-parse', 'HEAD']);
+  out({ ok: true, branch: fixBranch, head });
+}
+
+// ---------------------------------------------------------------------------
+// cleanup — remove a single worktree
+// ---------------------------------------------------------------------------
+
+function cleanup(worktreeDir) {
+  const absDir = path.resolve(worktreeDir);
+
+  if (!fs.existsSync(absDir)) {
+    gitSafe(['worktree', 'prune']);
+    out({ ok: true, removed: false, reason: 'not-found' });
+    return;
+  }
+
+  // If harvest hasn't run yet, run it defensively
+  if (!readJsonFile(harvestPath(absDir))) {
+    try { harvestCore(absDir); } catch (_) { /* best-effort */ }
+  }
+
+  const manifest = readJsonFile(manifestPath(absDir));
+
+  // Remove worktree
+  const removeResult = gitSafe(['worktree', 'remove', absDir, '--force']);
+  if (!removeResult.ok && fs.existsSync(absDir)) {
+    fs.rmSync(absDir, { recursive: true, force: true });
+  }
+
+  gitSafe(['worktree', 'prune']);
+
+  out({
+    ok: true,
+    removed: true,
+    detachedMainTree: manifest ? manifest.detachedMainTree : false
+  });
+}
+
+// ---------------------------------------------------------------------------
+// cleanup-all — remove all worktrees under a parent directory
+// ---------------------------------------------------------------------------
+
+function cleanupAll(parentDir) {
+  const absParent = path.resolve(parentDir);
+
+  if (!fs.existsSync(absParent)) {
+    out({ ok: true, cleaned: 0, entries: [] });
+    return;
+  }
+
+  let entries;
+  try {
+    entries = fs.readdirSync(absParent, { withFileTypes: true })
+      .filter(d => d.isDirectory())
+      .map(d => d.name);
+  } catch (_) {
+    out({ ok: true, cleaned: 0, entries: [] });
+    return;
+  }
+
+  const results = [];
+  for (const name of entries) {
+    const wtDir = path.join(absParent, name);
+    try {
+      // Defensive harvest before cleanup
+      if (!readJsonFile(harvestPath(wtDir))) {
+        try { harvestCore(wtDir); } catch (_) { /* best-effort */ }
+      }
+      gitSafe(['worktree', 'remove', wtDir, '--force']);
+      if (fs.existsSync(wtDir)) {
+        fs.rmSync(wtDir, { recursive: true, force: true });
+      }
+      results.push({ name, removed: true });
+    } catch (err) {
+      results.push({ name, removed: false, error: err.message });
+    }
+  }
+
+  gitSafe(['worktree', 'prune']);
+
+  // Remove parent if empty
+  try {
+    const remaining = fs.readdirSync(absParent);
+    if (remaining.length === 0) fs.rmdirSync(absParent);
+  } catch (_) { /* ignore */ }
+
+  out({ ok: true, cleaned: results.filter(r => r.removed).length, entries: results });
+}
+
+// ---------------------------------------------------------------------------
+// status — report worktree health
+// ---------------------------------------------------------------------------
+
+function statusCmd(worktreeDir) {
+  const absDir = path.resolve(worktreeDir);
+
+  if (!fs.existsSync(absDir)) {
+    out({ ok: true, exists: false });
+    return;
+  }
+
+  const manifest = readJsonFile(manifestPath(absDir));
+  const harvestResult = readJsonFile(harvestPath(absDir));
+  const age = manifest ? Date.now() - manifest.createdAtMs : null;
+  const isStale = age !== null && age > STALE_AGE_MS;
+
+  const statusOutput = gitSafe(['status', '--porcelain'], absDir);
+  const hasUncommitted = statusOutput.ok && statusOutput.output.length > 0;
+
+  let commitCount = 0;
+  if (manifest) {
+    const logResult = gitSafe(
+      ['log', '--oneline', `${manifest.preHarvestHead}..HEAD`],
+      absDir
+    );
+    if (logResult.ok && logResult.output) {
+      commitCount = logResult.output.split('\n').filter(Boolean).length;
+    }
+  }
+
+  const branch = gitSafe(['rev-parse', '--abbrev-ref', 'HEAD'], absDir);
+
+  out({
+    ok: true,
+    exists: true,
+    branch: branch.ok ? branch.output : null,
+    fixBranch: manifest ? manifest.fixBranch : null,
+    ageMs: age,
+    isStale,
+    hasUncommitted,
+    commitCount,
+    harvested: harvestResult !== null,
+    createdAt: manifest ? manifest.createdAt : null
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+function main() {
+  const args = process.argv.slice(2);
+  const command = args[0];
+
+  if (!command) {
+    usage();
+    process.exit(1);
+  }
+
+  switch (command) {
+    case 'prepare':
+      if (!args[1] || !args[2]) {
+        console.error('prepare requires <fixBranch> <worktreeDir>');
+        process.exit(1);
+      }
+      prepare(args[1], args[2]);
+      break;
+
+    case 'harvest':
+      if (!args[1]) {
+        console.error('harvest requires <worktreeDir>');
+        process.exit(1);
+      }
+      harvest(args[1]);
+      break;
+
+    case 'checkout-fix':
+      if (!args[1]) {
+        console.error('checkout-fix requires <fixBranch>');
+        process.exit(1);
+      }
+      checkoutFix(args[1]);
+      break;
+
+    case 'cleanup':
+      if (!args[1]) {
+        console.error('cleanup requires <worktreeDir>');
+        process.exit(1);
+      }
+      cleanup(args[1]);
+      break;
+
+    case 'cleanup-all':
+      if (!args[1]) {
+        console.error('cleanup-all requires <parentDir>');
+        process.exit(1);
+      }
+      cleanupAll(args[1]);
+      break;
+
+    case 'status':
+      if (!args[1]) {
+        console.error('status requires <worktreeDir>');
+        process.exit(1);
+      }
+      statusCmd(args[1]);
+      break;
+
+    default:
+      usage();
+      process.exit(1);
+  }
+}
+
+try {
+  main();
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(message);
+  process.exit(1);
+}

package/templates/subagent-wrapper.md

@@ -0,0 +1,109 @@
+# Subagent Task Wrapper Template
+
+Use this template when dispatching any bug-hunter subagent via the `subagent` or `teams` tool. Fill in the `{VARIABLES}` before dispatch.
+
+The orchestrator (main agent) MUST:
+1. Read the relevant prompt file with the Read tool
+2. Read this template with the Read tool
+3. Fill all `{VARIABLES}` with actual values
+4. Dispatch using the selected `AGENT_BACKEND`
+
+---
+
+## Context
+You are a specialized analysis agent invoked by a bug-hunting pipeline.
+You operate in your own context window. Your work feeds into a multi-phase
+adversarial review process.
+
+## Your Role: {ROLE_NAME}
+
+{ROLE_DESCRIPTION}
+
+## Your System Prompt
+
+---BEGIN SYSTEM PROMPT---
+{PROMPT_CONTENT}
+---END SYSTEM PROMPT---
+
+## Non-negotiable Rules
+
+- **Stay within scope.** Only analyze the files assigned to you below.
+- **Do NOT fix code.** Do NOT add tests. Report findings only.
+- **Do NOT report style issues**, unused imports, missing types, or refactoring ideas.
+- **Do NOT expand scope.** If you find something interesting outside your assigned files, note it in UNTRACED CROSS-REFS but do not investigate.
+- **Be honest about coverage.** If you run out of context reading files, STOP and report partial coverage in FILES SKIPPED. Do not inflate FILES SCANNED.
+- **Use the output format EXACTLY** as specified in your system prompt.
+- **Write output to the specified file.** The orchestrator reads this file for the next phase.
+- **Stop when done.** Do not continue to other phases or offer next-step suggestions.
+- **NEVER run destructive commands** like `rm -rf`.
+
+## Worktree Isolation Rules (Fixer role only)
+
+{WORKTREE_RULES}
+
+If worktree rules are provided above (non-empty), these apply:
+- You are working in an **isolated git worktree**. Your edits cannot affect the user's main working tree.
+- You **MUST** `git add` and `git commit` each fix before you finish. Uncommitted changes will be lost and marked as `FIX_FAILED`.
+- Commit message format: `fix(bug-hunter): BUG-N — [short description]`
+- Do **NOT** call `EnterWorktree` or `ExitWorktree` tools.
+- Do **NOT** run `git checkout`, `git switch`, or `git branch`.
+- If you encounter a git error, report it in your output and stop. Do not attempt recovery.
+
+## Your Assignment
+
+---BEGIN ASSIGNMENT---
+
+**Scan target:** {TARGET_DESCRIPTION}
+
+**SKILL_DIR:** {SKILL_DIR}
+(Use this path for all helper script invocations like `node "$SKILL_DIR/scripts/doc-lookup.cjs"` or the fallback `node "$SKILL_DIR/scripts/context7-api.cjs"`)
+
+**Files to scan (in risk-map order):**
+{FILE_LIST}
+
+**Risk map:**
+{RISK_MAP}
+
+**Tech stack:**
+{TECH_STACK}
+
+**Phase-specific context:**
+{PHASE_SPECIFIC_CONTEXT}
+
+---END ASSIGNMENT---
+
+## Output Requirements
+
+**Write your complete output to:** `{OUTPUT_FILE_PATH}`
+
+Follow the output format specified in your system prompt EXACTLY.
+The orchestrator will read this file to pass your results to the next pipeline phase.
+
+If the file path directory does not exist, create it first:
+```bash
+mkdir -p "$(dirname '{OUTPUT_FILE_PATH}')"
+```
+
+## Completion
+
+When you have finished your analysis:
+1. Write your report to `{OUTPUT_FILE_PATH}`
+2. Output a brief summary to stdout (one paragraph)
+3. Stop. Do not continue to other phases.
+
+---
+
+## Variable Reference (for the orchestrator)
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `{ROLE_NAME}` | Agent role identifier | `hunter`, `skeptic`, `referee`, `recon`, `fixer` |
+| `{ROLE_DESCRIPTION}` | One-line role description | "Bug Hunter — find behavioral bugs in source code" |
+| `{PROMPT_CONTENT}` | Full contents of the prompt .md file | Contents of `prompts/hunter.md` |
+| `{TARGET_DESCRIPTION}` | What is being scanned | "FindCoffee monorepo, packages/auth + packages/order" |
+| `{SKILL_DIR}` | Absolute path to the bug-hunter skill directory | `/Users/codex/.agents/skills/bug-hunter` |
+| `{FILE_LIST}` | Newline-separated file paths in scan order | CRITICAL files first, then HIGH, then MEDIUM |
+| `{RISK_MAP}` | Recon output risk classification | From `.bug-hunter/recon.md` |
+| `{TECH_STACK}` | Framework, auth, DB, key dependencies | "Express + JWT + Prisma + Redis" |
+| `{PHASE_SPECIFIC_CONTEXT}` | Extra context for this phase | For Skeptic: the Hunter findings. For Referee: findings + Skeptic challenges. |
+| `{OUTPUT_FILE_PATH}` | Where to write the output | `.bug-hunter/findings.md` |