@codexstar/bug-hunter 3.0.0

package/modes/_dispatch.md

@@ -0,0 +1,121 @@
+# Shared Dispatch Patterns
+
+This file defines how to dispatch each pipeline role (Recon, Hunter, Skeptic, Referee, Fixer) using any `AGENT_BACKEND`. Mode files reference this instead of duplicating dispatch boilerplate.
+
+---
+
+## Dispatch by Backend
+
+### local-sequential
+
+You execute the role yourself:
+
+1. Read the prompt file: `read({ path: "$SKILL_DIR/prompts/<role>.md" })`
+2. If the role needs doc-lookup: also read `$SKILL_DIR/prompts/doc-lookup.md`
+3. **Switch mindset** to the role (important for Skeptic/Referee — genuinely adversarial)
+4. Execute the role's instructions using the Read tool to examine source files
+5. Write output to the role's output file (see Output Files table below)
+
+### subagent
+
+1. Read the prompt file: `read({ path: "$SKILL_DIR/prompts/<role>.md" })`
+2. Read the wrapper template: `read({ path: "$SKILL_DIR/templates/subagent-wrapper.md" })`
+3. Generate payload:
+   ```bash
+   node "$SKILL_DIR/scripts/payload-guard.cjs" generate <role> ".bug-hunter/payloads/<role>-<context>.json"
+   ```
+4. Edit the payload JSON — fill in `skillDir`, `targetFiles`, and role-specific fields
+5. Validate:
+   ```bash
+   node "$SKILL_DIR/scripts/payload-guard.cjs" validate <role> ".bug-hunter/payloads/<role>-<context>.json"
+   ```
+6. Fill the subagent-wrapper template variables:
+   - `{ROLE_NAME}` = role name (see table below)
+   - `{ROLE_DESCRIPTION}` = role description (see table below)
+   - `{PROMPT_CONTENT}` = full contents of the prompt .md file
+   - `{TARGET_DESCRIPTION}` = what is being scanned
+   - `{SKILL_DIR}` = absolute path to skill directory
+   - `{FILE_LIST}` = files in scan order (CRITICAL first)
+   - `{RISK_MAP}` = risk classification from triage or Recon
+   - `{TECH_STACK}` = framework, auth, DB from Recon
+   - `{PHASE_SPECIFIC_CONTEXT}` = role-specific context (see below)
+   - `{OUTPUT_FILE_PATH}` = output file path
+7. Dispatch:
+   ```
+   subagent({ agent: "<role>-agent", task: "<filled template>", output: "<output-path>" })
+   ```
+8. Read the output file after completion
+
+### teams
+
+Same as subagent, but dispatch with:
+```
+teams({ tasks: [{ text: "<filled template>" }], maxTeammates: 1 })
+```
+
+### interactive_shell
+
+```
+interactive_shell({ command: 'pi "<filled task prompt>"', mode: "dispatch" })
+```
+
+---
+
+## Role Reference
+
+| Role | Prompt File | Role Description | Output File | Phase-Specific Context |
+|------|-------------|-----------------|-------------|----------------------|
+| `recon` | `prompts/recon.md` | Reconnaissance agent — map the codebase and classify files by risk | `.bug-hunter/recon.md` | Triage JSON path (if exists) |
+| `hunter` | `prompts/hunter.md` | Bug Hunter — find behavioral bugs in source code | `.bug-hunter/findings.md` | `doc-lookup.md` + risk map + tech stack |
+| `skeptic` | `prompts/skeptic.md` | Skeptic — adversarial review to disprove false positives | `.bug-hunter/skeptic.md` | Hunter findings (compact: bugId, severity, file, lines, claim, evidence, runtimeTrigger) + `doc-lookup.md` |
+| `referee` | `prompts/referee.md` | Referee — impartial final judge of all findings | `.bug-hunter/referee.md` | Hunter findings + Skeptic challenges |
+| `fixer` | `prompts/fixer.md` | Surgical code fixer — implement minimal fixes for confirmed bugs | `.bug-hunter/fix-report.md` | Confirmed bugs from Referee + tech stack + `doc-lookup.md` |
+
+---
+
+## Fixer Dispatch: Worktree Isolation (subagent/teams only)
+
+When `WORKTREE_MODE=true`, the Fixer runs in a managed git worktree for isolation. The orchestrator handles the full lifecycle — the Fixer just edits and commits.
+
+**Key differences from other role dispatches:**
+
+1. The worktree is created by the orchestrator via `worktree-harvest.cjs prepare` BEFORE dispatch.
+2. The Fixer's working directory is set to the worktree's absolute path, not the project root.
+3. The Fixer MUST `git add` + `git commit` each fix (uncommitted work = `FIX_FAILED`).
+4. The orchestrator harvests commits via `worktree-harvest.cjs harvest` AFTER dispatch.
+5. The orchestrator cleans up via `worktree-harvest.cjs cleanup` AFTER harvest.
+
+**CRITICAL — do NOT use `isolation: "worktree"` on the Agent tool:**
+The Agent tool's built-in worktree isolation creates an ephemeral branch and auto-cleans on exit, which loses Fixer commits. We manage worktrees ourselves so the Fixer commits land directly on the fix branch.
+
+**Fixer-specific template variables for `{PHASE_SPECIFIC_CONTEXT}`:**
+- `WORKTREE_DIR: <absolute path to worktree>`
+- `FIX_BRANCH: <branch name>`
+- `COMMIT_FORMAT: fix(bug-hunter): BUG-N — [description]`
+- Worktree isolation rules (see `{WORKTREE_RULES}` in subagent-wrapper.md)
+
+**Lifecycle diagram:**
+```
+Orchestrator                         Fixer (in worktree)
+     |                                     |
+     |-- prepare (worktree-harvest.cjs) -->|
+     |                                     |-- read code
+     |                                     |-- edit files
+     |                                     |-- git add + commit per bug
+     |                                     |-- report done
+     |<-- harvest (worktree-harvest.cjs) --|
+     |-- cleanup (worktree-harvest.cjs)    |
+     |-- verify on fix branch              |
+```
+
+---
+
+## Context Pruning Rules
+
+When passing data between phases, include only what the receiving role needs:
+
+**To Skeptic:** For each bug: BUG-ID, severity, file, lines, claim, evidence, runtimeTrigger, cross-references. Omit: Hunter's internal reasoning, scan coverage stats, FILES SCANNED/SKIPPED metadata.
+
+**To Referee:** Full Hunter findings + full Skeptic challenges. The Referee needs both sides to judge.
+
+**To Fixer:** For each confirmed bug: BUG-ID, severity, file, line range, description, suggested fix direction, tech stack context. Omit: Skeptic challenges, Referee reasoning.

package/modes/extended.md

@@ -0,0 +1,94 @@
+# Extended Mode (FILE_BUDGET+1 to FILE_BUDGET×2 files) — chunked sequential
+
+This mode handles larger targets that don't fit in a single Hunter pass.
+Files are split into chunks processed sequentially with persistent state.
+All phases are dispatched using the `AGENT_BACKEND` selected during SKILL preflight.
+
+---
+
+## Triage Integration
+
+Before any phase, check for `.bug-hunter/triage.json` (written by Step 1). If present:
+- Use `triage.riskMap` as the risk map — skip Recon's file classification.
+- Use `triage.scanOrder` as the chunk-building source (files already priority-ordered).
+- Use `triage.fileBudget` as FILE_BUDGET and chunk size cap.
+- Use `triage.domains` for service-aware partitioning if available.
+- Recon becomes an enrichment pass: identify tech stack and trust boundary patterns only.
+
+---
+
+## Step 4: Run Recon
+
+Dispatch Recon using the standard dispatch pattern (see `_dispatch.md`, role=`recon`).
+
+**If triage data exists**, tell Recon to use the triage risk map and only identify tech stack + patterns.
+
+**If no triage data**, Recon does full file discovery and classification.
+
+After Recon completes, read `.bug-hunter/recon.md` to extract the risk map and tech stack.
+
+---
+
+## Step 5: Run Chunked Hunters
+
+### 5a. Build chunks
+
+Partition files from `triage.scanOrder` (or the Recon risk map if no triage) into chunks:
+- **Service-aware partitioning (preferred):** If triage detected multiple domains, partition by domain.
+- **Risk-tier partitioning (fallback):** Process CRITICAL files first, then HIGH, then MEDIUM.
+- Chunk size: FILE_BUDGET ÷ 2 files per chunk (keep chunks small to avoid compaction).
+- Keep same-directory files together when possible.
+
+### 5b. Initialize state
+
+```bash
+node "$SKILL_DIR/scripts/bug-hunter-state.cjs" init ".bug-hunter/state.json" "extended" ".bug-hunter/source-files.json" 30
+```
+
+### 5c. Execute chunks sequentially
+
+For each chunk:
+
+1. Get next chunk and mark in-progress:
+   ```bash
+   node "$SKILL_DIR/scripts/bug-hunter-state.cjs" next-chunk ".bug-hunter/state.json"
+   node "$SKILL_DIR/scripts/bug-hunter-state.cjs" mark-chunk ".bug-hunter/state.json" "<chunk-id>" in_progress
+   ```
+
+2. Dispatch Hunter on this chunk's files using the standard dispatch pattern (see `_dispatch.md`, role=`hunter`).
+
+3. Record findings and mark done:
+   ```bash
+   node "$SKILL_DIR/scripts/bug-hunter-state.cjs" record-findings ".bug-hunter/state.json" ".bug-hunter/chunk-<id>-findings.json" "extended"
+   node "$SKILL_DIR/scripts/bug-hunter-state.cjs" mark-chunk ".bug-hunter/state.json" "<chunk-id>" done
+   ```
+
+4. Continue to next chunk.
+
+### 5d. Merge all findings
+
+After all chunks complete, merge findings from state into `.bug-hunter/findings.md`.
+
+If TOTAL FINDINGS: 0, skip Skeptic and Referee. Go to Step 7 (Final Report) in SKILL.md.
+
+---
+
+## Step 6: Run Skeptic(s)
+
+Dispatch 1-2 Skeptics by directory using the standard dispatch pattern (see `_dispatch.md`, role=`skeptic`).
+
+Split bugs by directory/service so each Skeptic has a focused scope. Merge results after completion.
+
+---
+
+## Step 7: Run Referee
+
+Dispatch Referee using the standard dispatch pattern (see `_dispatch.md`, role=`referee`).
+
+Pass merged Hunter findings + Skeptic challenges.
+
+---
+
+## After Step 7
+
+Proceed to **Step 7** (Final Report) in SKILL.md.

package/modes/fix-loop.md

@@ -0,0 +1,115 @@
+# Fix Loop Mode (`--loop --fix`)
+
+When both `--loop` and `--fix` are set, the ralph-loop wraps the ENTIRE pipeline (find + fix). Each iteration:
+
+1. **Phase 1**: Find bugs (or read from previous coverage file for remaining bugs)
+2. **Phase 2**: Fix confirmed bugs
+3. **Verify**: Run tests with baseline diff
+4. **Evaluate**: Update coverage file with fix status
+
+## CRITICAL: Starting the ralph-loop
+
+**You MUST call the `ralph_start` tool to begin the loop.** Without this call, the loop will not iterate.
+
+When `LOOP_MODE=true` AND `FIX_MODE=true`, before running the first pipeline iteration:
+
+1. Build the task content from the TODO.md template below.
+2. Call the `ralph_start` tool:
+
+```
+ralph_start({
+  name: "bug-hunter-fix-audit",
+  taskContent: <the TODO.md content below>,
+  maxIterations: 15
+})
+```
+
+3. The ralph-loop system will then drive iteration. Each iteration:
+   - You receive the task prompt with the current checklist state.
+   - You execute one iteration of find + fix.
+   - You update `.bug-hunter/coverage.md` with results.
+   - If all bugs are FIXED and all CRITICAL/HIGH files are DONE → output `<promise>COMPLETE</promise>`.
+   - Otherwise → call `ralph_done` to proceed to the next iteration.
+
+**Do NOT manually loop or re-invoke yourself.** The ralph-loop system handles iteration automatically.
+
+## Coverage file extension for fix mode
+
+The `.bug-hunter/coverage.md` file gains additional sections:
+
+```markdown
+## Fixes
+<!-- One line per bug. LATEST entry per BUG-ID is current status. -->
+<!-- Format: BUG-ID|STATUS|ITERATION_FIXED|FILES_MODIFIED -->
+<!-- STATUS: FIXED | FIX_REVERTED | FIX_FAILED | PARTIAL | FIX_CONFLICT | SKIPPED | FIXER_BUG -->
+BUG-3|FIXED|1|src/auth/login.ts
+BUG-7|FIXED|1|src/auth/login.ts
+BUG-12|FIXED|2|src/api/users.ts
+
+## Test Results
+<!-- One line per iteration. Format: ITERATION|PASSED|FAILED|NEW_FAILURES|RESOLVED -->
+1|45|3|2|0
+2|47|1|0|1
+```
+
+**Parsing rule:** For each BUG-ID, use the LAST entry in the Fixes section. Earlier entries for the same BUG-ID are history — only the latest matters.
+
+## Loop iteration logic
+
+```
+For each iteration:
+  1. Read coverage file
+  2. Collect (using LAST entry per BUG-ID):
+     - Unfixed bugs: latest STATUS in {FIX_REVERTED, FIX_FAILED, FIX_CONFLICT, SKIPPED, FIXER_BUG}
+     - Unscanned files: STATUS != DONE in Files section (CRITICAL/HIGH only)
+  3. If unfixed bugs exist OR unscanned files exist:
+     a. If unscanned files -> run Phase 1 (find pipeline) on them -> get new confirmed bugs
+     b. Combine: unfixed bugs + newly confirmed bugs
+     c. Run Phase 2 (fix + verify) on combined list
+     d. Update coverage file (append new entries to Fixes section)
+     e. Call ralph_done to proceed to next iteration
+  4. If all bugs FIXED and all CRITICAL/HIGH files DONE:
+     -> Run final test suite one more time
+     -> If no new failures:
+        Output <promise>COMPLETE</promise>
+     -> If pre-existing failures only:
+        Note "pre-existing test failures — not caused by bug fixes"
+        Output <promise>COMPLETE</promise>
+```
+
+## TODO.md task content for ralph_start
+
+Use this as the `taskContent` parameter when calling `ralph_start`:
+
+```markdown
+# Bug Hunt + Fix Audit
+
+## Discovery Tasks
+- [ ] All CRITICAL files scanned
+- [ ] All HIGH files scanned
+- [ ] Findings verified through Skeptic+Referee pipeline
+
+## Fix Tasks
+- [ ] All Critical bugs fixed
+- [ ] All Medium bugs fixed
+- [ ] All Low bugs fixed (best effort)
+- [ ] No new test failures introduced
+- [ ] Build and typecheck pass
+
+## Completion
+- [ ] ALL_TASKS_COMPLETE
+
+## Instructions
+1. Read .bug-hunter/coverage.md for previous iteration state
+2. Parse Files table — collect unscanned CRITICAL/HIGH files
+3. Parse Fixes table — collect unfixed bugs (latest entry not FIXED)
+4. If unscanned files exist: run Phase 1 (find pipeline) on them
+5. If unfixed bugs exist: run Phase 2 (fix pipeline) on them
+6. Update coverage file with results
+7. Output <promise>COMPLETE</promise> when all bugs are FIXED and no new test failures
+8. Otherwise call ralph_done to continue to the next iteration
+```
+
+## Ralph-loop state file for fix mode
+
+When `--loop --fix`, the `.bug-hunter/ralph-loop.local.md` is created automatically by the `ralph_start` tool. You do NOT need to create this file manually — just call `ralph_start` with the correct parameters.