feat: land structured-output migration and phase validation

Author: codexstar69

CHANGELOG.md

@@ -7,6 +7,49 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.0.4] — 2026-03-11
+
+### Added
+- `run-bug-hunter.cjs phase` command for schema-validated Skeptic, Referee, and Fixer phase execution with retry support
+- runner tests for invalid Skeptic, Referee, and Fixer artifacts plus Markdown companion rendering
+
+### Changed
+- preflight now checks all shipped structured-output schemas, not just findings
+- structured-output migration now enforces orchestrated outbound validation beyond the local/manual path
+
+## [3.0.3] — 2026-03-11
+
+### Added
+- `scripts/render-report.cjs` Markdown renderer for final report and coverage summaries from canonical JSON artifacts
+- `scripts/tests/render-report.test.cjs` coverage for report and coverage rendering
+- `coverage.json` / `coverage.md` output path in `run-bug-hunter.cjs`
+
+### Changed
+- Hunter, Skeptic, Referee, and Fixer prompts now describe JSON-first canonical artifacts
+- loop, fix-loop, local-sequential, and major mode docs now point at `*.json` phase artifacts and `coverage.json`
+- README, SKILL docs, evals, and the subagent wrapper now describe rendered Markdown as a companion to canonical JSON
+- local/manual mode docs now validate findings, skeptic, and referee artifacts with `schema-validate.cjs`
+
+## [3.0.2] — 2026-03-11
+
+### Added
+- `schemas/*.schema.json` versioned contracts for recon, findings, skeptic, referee, coverage, fix-report, plus shared definitions and example findings fixtures
+- `scripts/schema-runtime.cjs` lightweight schema runtime and `scripts/schema-validate.cjs` CLI for local artifact checks
+
+### Changed
+- `payload-guard.cjs` now emits real schema refs instead of placeholder format/version objects
+- `bug-hunter-state.cjs` now rejects malformed findings and stores canonical `confidenceScore`, `category`, `evidence`, `runtimeTrigger`, and `crossReferences`
+- `run-bug-hunter.cjs` now treats missing or invalid `findings.json` as a retriable chunk failure and checks schema assets during preflight
+- script tests now cover schema validation, malformed findings rejection, and retry-after-schema-failure
+
+## [3.0.1] — 2026-03-11
+
+### Changed
+- Loop and fix-loop completion now require full queued source-file coverage, not just CRITICAL/HIGH coverage
+- Autonomous runs now continue through remaining MEDIUM and LOW files after prioritized chunks finish unless the user interrupts
+- Loop iteration guidance now scales `maxIterations` from queue size so large audits do not stop early
+- Large-codebase mode now treats LOW domains as part of the default autonomous queue instead of optional skipped work
+
 ## [3.0.0] — 2026-03-10
 
 ### Added
@@ -136,7 +179,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Coverage enforcement — partial audits produce explicit warnings
 - Large codebase strategy with domain-first tiered scanning
 
-[Unreleased]: https://github.com/codexstar69/bug-hunter/compare/v3.0.0...HEAD
+[Unreleased]: https://github.com/codexstar69/bug-hunter/compare/v3.0.4...HEAD
+[3.0.4]: https://github.com/codexstar69/bug-hunter/compare/v3.0.3...v3.0.4
+[3.0.3]: https://github.com/codexstar69/bug-hunter/compare/v3.0.2...v3.0.3
+[3.0.2]: https://github.com/codexstar69/bug-hunter/compare/v3.0.1...v3.0.2
+[3.0.1]: https://github.com/codexstar69/bug-hunter/compare/v3.0.0...v3.0.1
 [3.0.0]: https://github.com/codexstar69/bug-hunter/compare/v2.4.1...v3.0.0
 [2.4.1]: https://github.com/codexstar69/bug-hunter/compare/v2.4.0...v2.4.1
 [2.4.0]: https://github.com/codexstar69/bug-hunter/compare/v2.3.0...v2.4.0

README.md

@@ -280,7 +280,7 @@ Bug Hunter automatically selects the optimal scanning strategy based on your cod
 | **120–180 files** | Scaled | State-driven chunks with resume capability |
 | **180+ files** | Large-codebase | Domain-scoped pipelines + boundary audits (loop mode, on by default) |
 
-Loop mode is **on by default** — the pipeline runs iteratively until every critical and high-risk file has been audited, with persistent state enabling stop-and-resume workflows. Use `--no-loop` for a single-pass scan.
+Loop mode is **on by default** — the pipeline runs iteratively until every queued scannable source file has been audited and, in fix mode, every discovered fixable bug has been processed. The agent should keep descending through CRITICAL → HIGH → MEDIUM → LOW automatically unless the user interrupts. Use `--no-loop` for a single-pass scan.
 
 ---
 
@@ -523,12 +523,16 @@ Every run creates a `.bug-hunter/` directory (add to `.gitignore`) containing:
 |------|-----------|----------|
 | `report.md` | Always | Human-readable report: confirmed bugs, dismissed findings, coverage stats |
 | `findings.json` | Always | Machine-readable JSON for CI/CD and dashboards |
+| `skeptic.json` | When findings exist | Canonical Skeptic challenge artifact |
+| `referee.json` | When findings exist | Canonical Referee verdict artifact |
+| `coverage.json` | Loop/autonomous runs | Canonical coverage and loop state |
 | `triage.json` | Always | File classification, risk map, strategy selection, token estimates |
 | `recon.md` | Always | Tech stack analysis, attack surface mapping, scan order |
-| `findings.md` | Always | Raw Hunter findings before Skeptic review |
-| `skeptic.md` | Always | Skeptic challenge decisions with evidence |
-| `referee.md` | Always | Referee final verdicts with enrichment |
-| `fix-report.md` | Fix mode | Per-bug fix status, verification results, git diff summary |
+| `findings.md` | Optional | Markdown companion rendered from `findings.json` |
+| `skeptic.md` | Optional | Markdown companion rendered from `skeptic.json` |
+| `referee.md` | Optional | Markdown companion rendered from `referee.json` |
+| `coverage.md` | Loop/autonomous runs | Markdown companion rendered from `coverage.json` |
+| `fix-report.md` | Fix mode | Markdown companion for fix results |
 | `fix-report.json` | Fix mode | Machine-readable fix results for CI/CD gating and dashboards |
 | `worktree-*/` | Worktree fix mode | Temporary isolated worktrees for Fixer subagents (auto-cleaned) |
 | `threat-model.md` | `--threat-model` | STRIDE threat model with trust boundaries and data flows |
@@ -560,7 +564,7 @@ The pipeline adapts to whatever it finds. Triage classifies files by extension a
 | `--fix` | Find and auto-fix bugs (default behavior) |
 | `--approve` | Interactive mode — ask before each fix |
 | `--autonomous` | Full auto-fix with zero intervention |
-| `--loop` | Iterative mode — runs until 100% critical file coverage **(on by default)** |
+| `--loop` | Iterative mode — runs until 100% queued source-file coverage **(on by default)** |
 | `--no-loop` | Disable loop mode — single-pass scan only |
 | `--deps` | Include dependency CVE scanning with reachability analysis |
 | `--threat-model` | Generate or use STRIDE threat model for targeted security analysis |

SKILL.md

@@ -50,7 +50,7 @@ For large scans: process chunks sequentially with persistent state to avoid comp
 /bug-hunter --autonomous src/            # Alias for no-intervention auto-fix run
 /bug-hunter --fix -b feature-xyz        # Find + fix on branch diff
 /bug-hunter --fix --approve src/        # Find + fix, but ask before each fix
-/bug-hunter src/                         # Loops by default: audit until 100% coverage
+/bug-hunter src/                         # Loops by default: audit + fix until all queued source files are covered
 /bug-hunter --no-loop src/               # Single-pass only, no iterating
 /bug-hunter --no-loop --scan-only src/   # Single-pass scan, no fixes, no loop
 /bug-hunter --deps src/                 # Include dependency CVE scan
@@ -130,7 +130,7 @@ If triage was not run (e.g., Recon was called directly without the orchestrator)
 
 **File partitioning rules (Extended/Scaled modes):**
 - **Service-aware partitioning (preferred)**: If Recon detected multiple service boundaries (monorepo), partition by service.
-- **Risk-tier partitioning (fallback)**: process CRITICAL then HIGH then MEDIUM.
+- **Risk-tier partitioning (fallback)**: process CRITICAL then HIGH then MEDIUM then LOW.
 - Keep chunk size small (recommended 20-40 files) to avoid context compaction issues.
 - Persist chunk progress in `.bug-hunter/state.json` so restarts do not re-scan done chunks.
 - Test files (CONTEXT-ONLY) are included only when needed for intent.
@@ -296,7 +296,7 @@ Token estimate: ~[N] tokens for full pipeline
 ```
 ⚠️ This codebase has [N] source files (FILE_BUDGET: [B]).
 Single-pass mode will only cover a subset. Remove `--no-loop` to enable iterative coverage.
-Proceeding with partial scan — CRITICAL and HIGH domains only.
+Proceeding with partial scan — highest-priority queued files only.
 ```
 
 **Triage replaces Recon's FILE_BUDGET computation.** Recon still runs for tech stack identification and pattern-based analysis, but it no longer needs to count files or compute the context budget — triage already did that, for free.
@@ -362,8 +362,8 @@ read({ path: "$SKILL_DIR/prompts/hunter.md" })
 #    - Apply the security checklist sweep
 #    - Write each finding in BUG-N format
 
-# 3. Write your findings to disk:
-write({ path: ".bug-hunter/findings.md", content: "<your findings>" })
+# 3. Write your canonical findings artifact to disk:
+write({ path: ".bug-hunter/findings.json", content: "<your findings json>" })
 ```
 
 #### Example B: subagent dispatch
@@ -383,16 +383,16 @@ read({ path: "$SKILL_DIR/templates/subagent-wrapper.md" })
 #    - {RISK_MAP} = <risk map from .bug-hunter/recon.md>
 #    - {TECH_STACK} = <framework, auth, DB from Recon>
 #    - {PHASE_SPECIFIC_CONTEXT} = <doc-lookup instructions from doc-lookup.md>
-#    - {OUTPUT_FILE_PATH} = ".bug-hunter/findings.md"
+#    - {OUTPUT_FILE_PATH} = ".bug-hunter/findings.json"
 #    - {SKILL_DIR} = <absolute path>
 # 4. Dispatch:
 subagent({
   agent: "hunter-agent",
   task: "<the filled template>",
-  output: ".bug-hunter/findings.md"
+  output: ".bug-hunter/findings.json"
 })
 # 5. Read the output:
-read({ path: ".bug-hunter/findings.md" })
+read({ path: ".bug-hunter/findings.json" })
 ```
 
 When launching subagents, always pass `SKILL_DIR` explicitly in the task context so prompt commands like `node "$SKILL_DIR/scripts/doc-lookup.cjs"` resolve correctly. The `context7-api.cjs` script is kept as a fallback if `doc-lookup.cjs` fails.
@@ -491,30 +491,36 @@ In a collapsed `<details>` section (for transparency).
 - Skeptic accuracy: X/Y correct challenges (Z%)
 
 ### 7. Coverage assessment
-- If ALL CRITICAL/HIGH files scanned: "Full coverage achieved."
+- If ALL queued scannable source files scanned: "Full queued coverage achieved."
 - If any missed: list them with note about `--loop` mode.
 
 ### 7b. Coverage enforcement (mandatory)
 
-If the coverage assessment shows ANY CRITICAL or HIGH files were not scanned, the pipeline is NOT complete:
+If the coverage assessment shows ANY queued scannable source files were not scanned, the pipeline is NOT complete:
 
-1. If `LOOP_MODE=true` (default): the ralph-loop will automatically continue to the next iteration covering missed files. Call `ralph_done` to proceed to the next iteration. Do NOT output `<promise>COMPLETE</promise>` until all CRITICAL/HIGH files show DONE.
+1. If `LOOP_MODE=true` (default): the ralph-loop will automatically continue to the next iteration covering missed files. Call `ralph_done` to proceed to the next iteration. Do NOT output `<promise>COMPLETE</promise>` until all queued scannable source files show DONE.
 
 2. If `LOOP_MODE=false` (`--no-loop` was specified) AND missed files exist:
    - If total files ≤ FILE_BUDGET × 3: Output the report with a WARNING:
      ```
-     ⚠️ PARTIAL COVERAGE: [N] CRITICAL/HIGH files were not scanned.
+     ⚠️ PARTIAL COVERAGE: [N] queued source files were not scanned.
      Run `/bug-hunter [path]` for complete coverage (loop is on by default).
      Unscanned files: [list them]
      ```
    - If total files > FILE_BUDGET × 3: The report MUST include:
      ```
      🚨 LARGE CODEBASE: [N] source files (FILE_BUDGET: [B]).
-     Single-pass audit covered [X]% of CRITICAL/HIGH files.
+     Single-pass audit covered [X]% of queued source files.
      Use `/bug-hunter [path]` for full coverage (loop is on by default).
      ```
 
-3. Do NOT claim "audit complete" or "full coverage achieved" unless ALL CRITICAL and HIGH files have status DONE. A partial audit is still valuable — report what you found honestly.
+3. Do NOT claim "audit complete" or "full coverage achieved" unless ALL queued scannable source files have status DONE. A partial audit is still valuable — report what you found honestly.
+
+4. Autonomous runs must keep descending through the remaining priority queue after the current prioritized chunk is done:
+   - Finish current CRITICAL/HIGH work first.
+   - Immediately continue with remaining MEDIUM files.
+   - Then continue with remaining LOW files.
+   - Only stop when the queue is exhausted, the user interrupts, or a hard blocker prevents safe progress.
 
 If zero bugs were confirmed, say so clearly — a clean report is a good result.
 
@@ -577,7 +583,12 @@ Rules for JSON output:
 - `dependencies` array: populated only if `--deps` was used and `.bug-hunter/dep-findings.json` exists.
 - This JSON enables CI/CD gating, dashboard ingestion, and downstream patch generation.
 
-Also write the final markdown report to `.bug-hunter/report.md` as the canonical human-readable output (in addition to displaying it to the user).
+Also write the final markdown report to `.bug-hunter/report.md` as the
+canonical human-readable output. Generate it from the JSON artifacts with:
+
+```bash
+node "$SKILL_DIR/scripts/render-report.cjs" report ".bug-hunter/findings.json" ".bug-hunter/referee.json" > ".bug-hunter/report.md"
+```
 
 ---