@codexstar/bug-hunter 3.0.0 → 3.0.5

package/CHANGELOG.md

@@ -1,102 +1,158 @@
 # Changelog
 
-## 3.0.0 — 2026-03-10
-
-### npm package, worktree-isolated Fixer, and cross-IDE installation
-
-**npm global install and CLI:**
-- New `package.json` with `@codexstar/bug-hunter` package name
-- New `bin/bug-hunter` CLI entry point with `install`, `doctor`, and `info` commands
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [3.0.5] — 2026-03-11
+
+### Added
+- `agents/openai.yaml` UI metadata for skill lists and quick-invoke prompts
+
+### Changed
+- `SKILL.md` frontmatter now validates cleanly against the `skill-creator` validator
+- `evals/evals.json` now matches the current `.bug-hunter/*` JSON-first pipeline, default loop/fix behavior, and modern flags like `--deps`, `--threat-model`, `--dry-run`, and `--autonomous`
+- npm package files now include the `agents/` directory so `openai.yaml` ships with the published skill
+
+## [Unreleased]
+
+### Highlights
+- PR review is now a first-class workflow with `--pr`, `--pr current`, `--pr recent`, `--pr 123`, `--last-pr`, and `--pr-security`.
+- Bug Hunter now emits both `fix-strategy.json` and `fix-plan.json` before fix execution so remediation stays reviewable and confidence-gated.
+- The enterprise security pack now ships inside the repository under `skills/`, making PR security review and full security audits portable.
+- Fix execution is now safer through schema-validated planning, atomic lock handling, safer worktree cleanup, stash preservation, and shell-safe templating.
+
+### Added
+- GitHub Actions npm publish workflow on release publish or manual dispatch, with version/tag verification before `npm publish`
+- bundled local security skills under `skills/`: `commit-security-scan`, `security-review`, `threat-model-generation`, and `vulnerability-validation`
+- enterprise security entrypoints: `--pr-security`, `--security-review`, and `--validate-security`
+- regression tests and eval coverage for integrated local security-skill routing
+- `schemas/fix-plan.schema.json` plus validation coverage for canonical fix-plan artifacts
+- focused regressions for lock-token ownership, atomic lock acquisition, stale artifact clearing, shell-safe worker paths, failed-chunk fix-plan suppression, managed worktree cleanup, and stash-ref preservation
+
+### Changed
+- portable security capabilities now live inside the repository under `skills/` instead of depending on external machine-specific skill paths
+- package metadata now ships the `skills/` directory for self-contained distribution
+- main Bug Hunter orchestration now routes into the bundled local security skills for PR security review, threat-model generation, enterprise security review, and vulnerability validation
+- fix-lock now uses owner tokens for renew/release, atomic acquisition under contention, and safe recovery from corrupted lock files
+- run-bug-hunter now shell-quotes templated command arguments, clears stale artifacts before retries, validates fix-plan artifacts, and skips fix-plan emission when chunks fail
+- worktree cleanup/status now preserve unrelated directories, preserve stash metadata from defensive harvests, and avoid reporting manifest-only worktrees as dirty
+- current-PR git fallback now diffs against the discovered `origin/<default-branch>` ref when the base branch comes from `origin/HEAD`
+- README now opens with a short “New in This Update” and PR-first quick-start section
+- `llms.txt` and `llms-full.txt` now describe the PR review flow, bundled local security pack, current fix artifacts, and the current regression-test coverage
+- `skills/README.md` now explains how the bundled security skills map into Bug Hunter workflows
+
+## [3.0.4] — 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
+- `scripts/render-report.cjs` Markdown renderer for report, coverage, skeptic, referee, and fix-report views from canonical JSON artifacts
+- canonical `coverage.json` output with derived `coverage.md`
+- `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
+- Hunter, Skeptic, Referee, and Fixer prompts now describe JSON-first canonical artifacts
+- `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, validates phase artifacts, and checks all shipped schema assets during preflight
+- 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
+- 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.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
+- `package.json` with `@codexstar/bug-hunter` package name
+- `bin/bug-hunter` CLI entry point with `install`, `doctor`, and `info` commands
 - `bug-hunter install` auto-detects Claude Code, Codex, Cursor, Kiro, and generic agents directories
 - `bug-hunter doctor` checks environment readiness (Node.js, Context Hub, Context7, git)
 - Install via: `npm install -g @codexstar/bug-hunter && bug-hunter install`
-
-**Cross-IDE installation via skills.sh:**
 - Compatible with `npx skills add codexstar69/bug-hunter` for Cursor, Windsurf, Copilot, Kiro, and Claude Code
-- No publish step required — auto-discovered from public GitHub repo with valid SKILL.md
-
-**Worktree-isolated Fixer dispatch (subagent/teams backends):**
-- New `scripts/worktree-harvest.cjs` — manages git worktrees for safe, isolated Fixer execution
-  - 6 subcommands: `prepare`, `harvest`, `checkout-fix`, `cleanup`, `cleanup-all`, `status`
-  - Fixer edits happen in an isolated worktree; commits land on the fix branch without touching the user's working tree
-  - Crash recovery via `cleanup-all` with automatic stash preservation
-  - Meta-file filtering prevents `.worktree-manifest.json` and `.harvest-result.json` from polluting dirty detection
+- `scripts/worktree-harvest.cjs` — manages git worktrees for safe, isolated Fixer execution (6 subcommands: `prepare`, `harvest`, `checkout-fix`, `cleanup`, `cleanup-all`, `status`)
+- 13 new tests in `scripts/tests/worktree-harvest.test.cjs` (full suite: 25/25 passing)
+- 5 new error rows in SKILL.md for worktree failures: prepare, harvest dirty, harvest no-manifest, cleanup, and checkout-fix errors
+
+### Changed
 - `modes/fix-pipeline.md` updated with dual-path dispatch: worktree path (prepare → dispatch → harvest → cleanup) and direct path
 - `modes/_dispatch.md` updated with Fixer worktree lifecycle diagram and CRITICAL warning about Agent tool's built-in `isolation: "worktree"`
 - `templates/subagent-wrapper.md` updated with `{WORKTREE_RULES}` variable for Fixer isolation rules
-- 13 new tests in `scripts/tests/worktree-harvest.test.cjs` (full suite: 25/25 passing)
-
-**Context Hub preflight warning:**
-- SKILL.md Step 5b now shows a visible `⚠️` warning when `chub` is not installed, with install command
-- Previously was a silent suggestion — now impossible to miss
-
-**SKILL.md error table:**
-- 5 new error rows for worktree failures: prepare, harvest dirty, harvest no-manifest, cleanup, and checkout-fix errors
-
----
+- SKILL.md Step 5b now shows a visible `⚠️` warning when `chub` is not installed (previously a silent suggestion)
 
-## 2026-03-10 13:26
+## [2.4.1] — 2026-03-10
 
+### Fixed
 - `scripts/triage.cjs`: LOW-only repositories promoted into `scanOrder` so script-heavy codebases do not collapse to zero scannable files
 - `scripts/run-bug-hunter.cjs`: `teams` backend name aligned with the documented dispatch mode
 - `scripts/run-bug-hunter.cjs`: `code-index.cjs` treated as optional during preflight and gated only when index-backed flows are requested
 - `scripts/run-bug-hunter.cjs`: low-confidence delta expansion now reuses the caller's configured `--delta-hops` value
+
+### Added
 - `scripts/tests/run-bug-hunter.test.cjs`: regressions for LOW-only triage, optional `code-index`, `teams` backend selection, and delta-hop expansion
 
-## 2.4.0 — 2026-03-10
+## [2.4.0] — 2026-03-10
 
-### Context Hub integration — curated docs with Context7 fallback
+### Added
+- `scripts/doc-lookup.cjs`: hybrid documentation lookup that tries [Context Hub](https://github.com/andrewyng/context-hub) (chub) first for curated, versioned, annotatable docs, then falls back to Context7 API when chub doesn't have the library
+- Requires `@aisuite/chub` installed globally (`npm install -g @aisuite/chub`) — optional but recommended; pipeline works without it via Context7 fallback
 
-- New `scripts/doc-lookup.cjs`: hybrid documentation lookup that tries [Context Hub](https://github.com/andrewyng/context-hub) (chub) first for curated, versioned, annotatable docs, then falls back to Context7 API when chub doesn't have the library
+### Changed
 - All agent prompts (hunter, skeptic, fixer, doc-lookup) updated to use `doc-lookup.cjs` as primary with `context7-api.cjs` as explicit fallback
 - Preflight smoke test now checks `doc-lookup.cjs` first, falls back to `context7-api.cjs`
 - `run-bug-hunter.cjs` validates both scripts exist at startup
-- Requires `@aisuite/chub` installed globally (`npm install -g @aisuite/chub`) — optional but recommended; pipeline works without it via Context7 fallback
-
-## 2.3.0 — 2026-03-10
 
-### Loop mode is now on by default
+## [2.3.0] — 2026-03-10
 
+### Changed
 - `LOOP_MODE=true` is the new default — every `/bug-hunter` invocation iterates until full CRITICAL/HIGH coverage
-- Added `--no-loop` flag to opt out and get single-pass behavior
 - `--loop` flag still accepted for backwards compatibility (no-op)
 - Updated triage warnings, coverage enforcement, and all documentation to reflect the new default
-- `/bug-hunter src/` now finds bugs, fixes them, AND loops until full coverage — zero flags needed
 
-## 2.2.1 — 2026-03-10
+### Added
+- `--no-loop` flag to opt out and get single-pass behavior
 
-### Fix: `--loop` mode now actually loops
+## [2.2.1] — 2026-03-10
 
-The `--loop` flag was broken — loop mode files described a "ralph-loop" system but never called `ralph_start`, so the pipeline ran once and stopped. Fixed:
-
-- **`modes/loop.md`**: added explicit `ralph_start` call instructions with correct `taskContent` and `maxIterations` parameters
-- **`modes/fix-loop.md`**: same fix for `--loop --fix` combined mode, plus removed manual state file creation (handled by `ralph_start`)
-- **`SKILL.md`**: added CRITICAL integration note requiring `ralph_start` call when `LOOP_MODE=true`
+### Fixed
+- `modes/loop.md`: added explicit `ralph_start` call instructions with correct `taskContent` and `maxIterations` parameters
+- `modes/fix-loop.md`: same fix for `--loop --fix` combined mode, plus removed manual state file creation (handled by `ralph_start`)
+- `SKILL.md`: added CRITICAL integration note requiring `ralph_start` call when `LOOP_MODE=true`
 - Changed completion signal from `<promise>DONE</promise>` to `<promise>COMPLETE</promise>` (correct ralph-loop API)
 - Each iteration now calls `ralph_done` to proceed instead of relying on a non-existent hook
 
-## 2.2.0 — 2026-03-10
-
-### Fix pipeline hardening — 12 reliability and safety optimizations
+## [2.2.0] — 2026-03-10
 
-- **Rollback timeout guard**: `git revert` calls now timeout after 60 seconds; conflicts abort cleanly instead of hanging the pipeline indefinitely
-- **Dynamic lock TTL**: single-writer lock TTL scales with queue size (`max(1800, bugs * 600)`), preventing expiry on large fix runs
-- **Lock heartbeat renewal**: new `renew` command in `fix-lock.cjs` — fixer renews the lock after each bug fix to prevent mid-run TTL expiry
-- **Fixer context budget**: `MAX_BUGS_PER_FIXER = 5` — large fix queues are split into sequential batches to prevent context window overflow and hallucinated patches
-- **Cross-file dependency ordering**: when `code-index.cjs` is available, fixes are ordered by import graph (fix dependencies before dependents)
-- **Flaky test detection**: baseline tests run twice; tests that fail non-deterministically are excluded from revert decisions
-- **Per-bug revert granularity**: clarified one-commit-per-bug as mandatory; reverts target individual bugs, not clusters
-- **Dynamic canary sizing**: `max(1, min(3, ceil(eligible * 0.2)))` — canary group scales with queue size instead of hardcoded 1–3
-- **Post-fix re-scan severity floor**: fixer-introduced bugs below MEDIUM severity are logged but don't trigger `FIXER_BUG` status
-- **Dry-run mode** (`--dry-run`): preview planned fixes without editing files — Fixer reads code and outputs unified diff previews, no git commits
-- **Machine-readable fix report**: `.bug-hunter/fix-report.json` written alongside markdown report for CI/CD gating, dashboards, and ticket automation
-- **Circuit breaker**: if >50% of fix attempts fail/revert (min 3 attempts), remaining fixes are halted to prevent token waste on unstable codebases
-- **Global Phase 2 timeout**: 30-minute deadline for the entire fix execution phase; unprocessed bugs are marked SKIPPED
+### Added
+- Rollback timeout guard: `git revert` calls now timeout after 60 seconds; conflicts abort cleanly instead of hanging
+- Dynamic lock TTL: single-writer lock TTL scales with queue size (`max(1800, bugs * 600)`)
+- Lock heartbeat renewal: new `renew` command in `fix-lock.cjs`
+- Fixer context budget: `MAX_BUGS_PER_FIXER = 5` — large fix queues split into sequential batches
+- Cross-file dependency ordering: when `code-index.cjs` is available, fixes are ordered by import graph
+- Flaky test detection: baseline tests run twice; non-deterministic failures excluded from revert decisions
+- Dynamic canary sizing: `max(1, min(3, ceil(eligible * 0.2)))` — canary group scales with queue size
+- Dry-run mode (`--dry-run`): preview planned fixes without editing files
+- Machine-readable fix report: `.bug-hunter/fix-report.json` for CI/CD gating, dashboards, and ticket automation
+- Circuit breaker: if >50% of fix attempts fail/revert (min 3 attempts), remaining fixes are halted
+- Global Phase 2 timeout: 30-minute deadline for the entire fix execution phase
 
-## 2.1.0 — 2026-03-10
+### Changed
+- Per-bug revert granularity: clarified one-commit-per-bug as mandatory; reverts target individual bugs, not clusters
+- Post-fix re-scan severity floor: fixer-introduced bugs below MEDIUM severity are logged but don't trigger `FIXER_BUG` status
 
-### v3 security pipeline + dependency scanner reliability
+## [2.1.0] — 2026-03-10
 
+### Added
 - STRIDE/CWE fields in Hunter findings format, with CWE quick-reference mapping for security categories
 - Skeptic hard-exclusion fast path (15 false-positive classes) before deep review
 - Referee security enrichment: reachability, exploitability, CVSS 3.1, and PoC blocks for critical/high security bugs
@@ -104,48 +160,58 @@ The `--loop` flag was broken — loop mode files described a "ralph-loop" system
 - Dependency scan support: `--deps` flag and `scripts/dep-scan.cjs` output to `.bug-hunter/dep-findings.json`
 - JSON report contract: `.bug-hunter/findings.json` plus canonical `.bug-hunter/report.md`
 - Few-shot calibration examples for Hunter and Skeptic in `prompts/examples/`
-- `dep-scan.cjs` lockfile-aware audits (`npm`, `pnpm`, `yarn`, `bun`) and non-zero audit exit handling so vulnerability exits are not misreported as scanner failures
 
-## 2.0.0 — 2026-03-10
+### Fixed
+- `dep-scan.cjs` lockfile-aware audits (`npm`, `pnpm`, `yarn`, `bun`) and non-zero audit exit handling so vulnerability exits are not misreported as scanner failures
 
-### Structural overhaul — triage pipeline + 36% token reduction
+## [2.0.0] — 2026-03-10
 
-**Pipeline restructure:**
+### Changed
 - Triage moved to Step 1 (after arg parse) — was running before target resolved
 - All mode files consume triage JSON — riskMap, scanOrder, fileBudget flow downstream
 - Recon demoted to enrichment — no longer does file classification when triage exists
-- Step 7.0 re-audit gate removed — duplicated Referee's work
-
-**Deduplication:**
-- `modes/_dispatch.md` — shared dispatch patterns (18 references across modes)
 - Mode files compressed: small 7.3→2.9KB, parallel 7.9→4.2KB, extended 7.1→3.3KB, scaled 7.3→2.7KB
 - Skip-file patterns consolidated — single authoritative list in SKILL.md
 - Error handling table updated with correct step references
-
-**Dead weight removed:**
-- FIX-PLAN.md deleted (26KB dead planning doc)
-- README.md compressed from 8.5KB to 3.7KB
-- code-index.cjs marked optional
-
-**Prompt compression:**
 - hunter.md: scope rules and security checklist compressed
 - recon.md: output format template and "What to map" sections compressed
 - referee.md: tiering rules, re-check section, output format compressed
 - skeptic.md: false-positive patterns compressed to inline format
-
-**Logic gaps fixed:**
 - Branch-diff/staged optimization note in Step 3
 - single-file.md: local-sequential backend support added
 
-**Size:** 187,964 → 119,825 bytes (36% reduction, ~30K tokens)
+### Added
+- `modes/_dispatch.md` — shared dispatch patterns (18 references across modes)
+
+### Removed
+- Step 7.0 re-audit gate removed — duplicated Referee's work
+- FIX-PLAN.md deleted (26KB dead planning doc)
+- README.md compressed from 8.5KB to 3.7KB
+- code-index.cjs marked optional
 
-## 1.0.0 — 2026-03-10
+## [1.0.0] — 2026-03-10
 
-### Zero-token pre-recon triage (`triage.cjs`)
-- `scripts/triage.cjs` runs before any LLM agent — 0 tokens, <2s for 2,000+ files
+### Added
+- `scripts/triage.cjs` — zero-token pre-recon triage, runs before any LLM agent (<2s for 2,000+ files)
 - FILE_BUDGET, strategy, and domain map decided by triage, not Recon
 - Writes `.bug-hunter/triage.json` with strategy, fileBudget, domains, riskMap, scanOrder
 - `local-sequential.md` with full phase-by-phase instructions
 - Subagent wrapper template in `templates/subagent-wrapper.md`
 - 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.5...HEAD
+[3.0.5]: https://github.com/codexstar69/bug-hunter/compare/v3.0.4...v3.0.5
+[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
+[2.3.0]: https://github.com/codexstar69/bug-hunter/compare/v2.2.1...v2.3.0
+[2.2.1]: https://github.com/codexstar69/bug-hunter/compare/v2.2.0...v2.2.1
+[2.2.0]: https://github.com/codexstar69/bug-hunter/compare/v2.1.0...v2.2.0
+[2.1.0]: https://github.com/codexstar69/bug-hunter/compare/v2.0.0...v2.1.0
+[2.0.0]: https://github.com/codexstar69/bug-hunter/compare/v1.0.0...v2.0.0
+[1.0.0]: https://github.com/codexstar69/bug-hunter/releases/tag/v1.0.0

package/README.md

@@ -1,11 +1,13 @@
 <p align="center">
-  <img src="docs/images/hero.png" alt="Bug Hunter — AI-powered adversarial code security scanner with multi-agent pipeline for automated vulnerability detection, false-positive elimination, and safe auto-fix" width="720">
+  <img src="docs/images/2026-03-12-hero-bug-hunter-overview.png" alt="Bug Hunter product overview banner — code and pull requests flow through adversarial review, strategic fix planning, and verified patch delivery" width="720">
 </p>
 
 <h1 align="center">🐛 Bug Hunter</h1>
 <p align="center"><strong>AI-powered adversarial bug finding that argues with itself to surface real vulnerabilities — and auto-fixes them safely.</strong></p>
 <p align="center">
   <a href="#install">Install</a> ·
+  <a href="#new-in-this-update">New in This Update</a> ·
+  <a href="#start-here">Start Here</a> ·
   <a href="#usage">Usage</a> ·
   <a href="#how-the-adversarial-pipeline-works">How It Works</a> ·
   <a href="#features">Features</a> ·
@@ -47,6 +49,39 @@ npm install -g @aisuite/chub
 
 ---
 
+## New in This Update
+
+This release makes Bug Hunter much better at PR-first auditing and safer at automated remediation.
+
+- **PR review is now a first-class workflow.** Review the current PR, the most recent PR, or a specific PR number with `--pr`, `--pr current`, `--pr recent`, or `--pr 123`.
+- **PR security review is now built in.** `--pr-security` runs a PR-scoped security audit with threat-model and dependency context, without editing code.
+- **Strategic remediation is now explicit.** Bug Hunter writes `fix-strategy.json` and `fix-plan.json` before fixes run, so auto-fix decisions stay explainable and reviewable.
+- **The security pack is now bundled locally.** `commit-security-scan`, `security-review`, `threat-model-generation`, and `vulnerability-validation` now ship inside the repo under `skills/`.
+- **Fix execution is harder to break.** This update adds schema-validated fix plans, atomic lock handling, safer worktree cleanup, stash preservation, and shell-safe worker command templating.
+
+<p align="center">
+  <img src="docs/images/2026-03-12-pr-review-flow.png" alt="PR review workflow banner — pull request scope, security checks, threat-model context, and final verdict in a clean product-style UI" width="100%">
+</p>
+
+## Start Here
+
+If you're evaluating the new PR flow, start with one of these:
+
+```bash
+/bug-hunter --pr                 # review the current PR end to end
+/bug-hunter --pr-security        # PR-focused security review without editing code
+/bug-hunter --last-pr --review   # review the most recent PR without fixes
+/bug-hunter --plan src/          # build fix-strategy.json + fix-plan.json only
+```
+
+If you just want the default repo audit:
+
+```bash
+/bug-hunter
+```
+
+---
+
 ## Usage
 
 ```bash
@@ -54,9 +89,22 @@ npm install -g @aisuite/chub
 /bug-hunter src/                   # scan a specific directory
 /bug-hunter lib/auth.ts            # scan a single file
 /bug-hunter --scan-only src/       # report only — no code changes
+/bug-hunter --review src/          # easy alias for --scan-only
 /bug-hunter --fix --approve src/   # ask before each fix
+/bug-hunter --safe src/            # easy alias for --fix --approve
 /bug-hunter -b feature-xyz         # scan only files changed in branch (vs main)
+/bug-hunter --pr                   # easy alias for --pr current
+/bug-hunter --pr current           # review the current PR end to end
+/bug-hunter --pr recent            # review the most recently updated open PR
+/bug-hunter --pr 123               # review a specific PR number
+/bug-hunter --pr-security          # PR security review with threat model + CVE context
+/bug-hunter --review-pr            # easy alias for --pr current
+/bug-hunter --last-pr --review     # review the most recent PR without editing
 /bug-hunter --staged               # scan staged files (pre-commit hook)
+/bug-hunter --plan src/            # easy alias for --plan-only
+/bug-hunter --preview src/         # easy alias for --fix --dry-run
+/bug-hunter --security-review src/ # enterprise security workflow for a path or repo
+/bug-hunter --validate-security src/ # force exploitability validation for security findings
 /bug-hunter --deps --threat-model  # full audit: CVEs + STRIDE threat model
 ```
 
@@ -72,6 +120,8 @@ This eliminates the two biggest problems with AI code review: **false positive o
 
 ## Table of Contents
 
+- [New in This Update](#new-in-this-update)
+- [Start Here](#start-here)
 - [How the Adversarial Pipeline Works](#how-the-adversarial-pipeline-works)
 - [Features](#features)
 - [Security Classification — STRIDE, CWE, and CVSS](#security-classification-stride-cwe-cvss)
@@ -162,6 +212,28 @@ This scoring creates a **self-correcting equilibrium**. The Hunter doesn't flood
 
 ## Features
 
+### Bundled Local Security Skills
+
+Bug Hunter now ships with a portable local security pack under `skills/`:
+- `commit-security-scan`
+- `security-review`
+- `threat-model-generation`
+- `vulnerability-validation`
+
+These are bundled inside the repository so the system does not depend on external marketplace paths or machine-specific skill installs. They are adapted to Bug Hunter-native artifacts like `.bug-hunter/threat-model.md`, `.bug-hunter/security-config.json`, `.bug-hunter/findings.json`, and `.bug-hunter/referee.json`.
+
+They are now wired into the main Bug Hunter flow:
+- PR-focused security review routes into `commit-security-scan`
+- `--threat-model` routes into `threat-model-generation`
+- enterprise/full security review routes into `security-review`
+- exploitability confirmation for security findings routes into `vulnerability-validation`
+
+Bug Hunter remains the top-level orchestrator; the bundled skills are capability modules inside that orchestration.
+
+<p align="center">
+  <img src="docs/images/2026-03-12-security-pack.png" alt="Bundled local security pack banner — Bug Hunter orchestrates commit security scan, security review, threat-model generation, and vulnerability validation" width="100%">
+</p>
+
 ### Zero-Token Triage — Instant File Classification
 
 Before any AI agent runs, a lightweight Node.js script (`scripts/triage.cjs`) scans your entire codebase in **under 2 seconds**. It classifies every file by risk level — CRITICAL, HIGH, MEDIUM, LOW, or CONTEXT-ONLY — computes a token budget, and selects the optimal scanning strategy.
@@ -280,7 +352,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.
 
 ---
 
@@ -385,6 +457,10 @@ Dependency findings are saved to `.bug-hunter/dep-findings.json` and cross-refer
 
 Bug Hunter doesn't throw uncoordinated patches at your codebase. After the Referee confirms real bugs, the system builds a **strategic fix plan** with safety gates at every step — the difference between "an AI that edits files" and "an AI that engineers patches."
 
+<p align="center">
+  <img src="docs/images/2026-03-12-fix-plan-rollout.png" alt="Strategic fix planning banner — strategy, confidence gating, canary rollout, verification, and rollback safety" width="100%">
+</p>
+
 ### Phase 1 — Safety Setup and Git Branching
 
 - Verifies you're in a git repository (warns if not — no rollback without version control)
@@ -400,14 +476,26 @@ Bug Hunter doesn't throw uncoordinated patches at your codebase. After the Refer
 - Runs the test suite once to record the **passing baseline**
 - This baseline is critical: if a fix causes a previously-passing test to fail, the fix is auto-reverted
 
-### Phase 3 — Confidence-Gated Fix Queue
+### Phase 3 — Strategy Before Patching
+
+Before the Fixer edits anything, Bug Hunter now writes a canonical `fix-strategy.json` artifact.
+It clusters confirmed bugs and classifies them into one of four tracks:
+
+- **safe-autofix** — localized enough for guarded patching
+- **manual-review** — confidence too low for unattended edits
+- **larger-refactor** — needs coordinated multi-file changes
+- **architectural-remediation** — broad contract or design issue; report, don’t auto-edit
+
+This makes the remediation plan visible before execution. Users who want review without mutation can run `--plan-only` to stop after strategy + plan generation.
+
+### Phase 4 — Confidence-Gated Fix Queue
 
 - **75% confidence gate**: only bugs the Referee confirmed with ≥75% confidence are auto-fixed
 - Bugs below the threshold are marked `MANUAL_REVIEW` — reported but never auto-edited
 - **Conflict resolution**: same-file bugs are grouped and ordered to prevent overlapping edits
 - **Severity ordering**: Critical → High → Medium → Low
 
-### Phase 4 — Canary Rollout Strategy
+### Phase 5 — Canary Rollout Strategy
 
 ```
 Fix Plan: 7 eligible bugs | canary: 2 | rollout: 5 | manual-review: 3
@@ -470,6 +558,10 @@ This prevents a common failure: the Fixer "fixing" a bug using an API pattern th
 
 ## Structured JSON Output for CI/CD Integration
 
+<p align="center">
+  <img src="docs/images/2026-03-12-machine-readable-artifacts.png" alt="Machine-readable artifacts banner — findings, skeptic, referee, fix strategy, fix plan, and CI automation outputs" width="100%">
+</p>
+
 Every run produces machine-readable output at `.bug-hunter/findings.json` for pipeline automation:
 
 ```json
@@ -523,12 +615,20 @@ 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-strategy.json` | When findings exist | Canonical remediation strategy: safe autofix vs manual review vs refactor vs architectural work |
+| `fix-strategy.md` | When findings exist | Markdown companion rendered from `fix-strategy.json` |
+| `fix-plan.json` | Plan/fix mode | Canonical execution plan for canary rollout, gating, and safe fix order |
+| `fix-plan.md` | Plan/fix mode | Markdown companion rendered from `fix-plan.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 |
@@ -555,16 +655,30 @@ The pipeline adapts to whatever it finds. Triage classifies files by extension a
 | `src/` or `file.ts` | Scan specific path |
 | `-b branch-name` | Scan files changed in branch (vs main) |
 | `-b branch --base dev` | Scan branch diff against specific base |
+| `--pr` | Easy alias for `--pr current` |
+| `--pr current` | Review the current PR using GitHub metadata when available, with git fallback on the current branch |
+| `--pr recent` | Review the most recently updated open PR |
+| `--pr 123` | Review a specific PR number |
+| `--pr-security` | Enterprise PR security review: PR scope + threat model + dependency context |
+| `--last-pr` | Easy alias for `--pr recent` |
+| `--review-pr` | Alias for `--pr current` |
 | `--staged` | Scan git-staged files (pre-commit hook integration) |
 | `--scan-only` | Report only — no code changes |
+| `--review` | Easy alias for `--scan-only` |
 | `--fix` | Find and auto-fix bugs (default behavior) |
+| `--plan-only` | Build `fix-strategy.json` + fix plan, then stop before the fixer edits code |
+| `--plan` | Easy alias for `--plan-only` |
 | `--approve` | Interactive mode — ask before each fix |
+| `--safe` | Easy alias for `--fix --approve` |
 | `--autonomous` | Full auto-fix with zero intervention |
-| `--loop` | Iterative mode — runs until 100% critical file coverage **(on by default)** |
+| `--dry-run` | Preview planned fixes without editing files — outputs diff previews and `fix-report.json` |
+| `--preview` | Easy alias for `--fix --dry-run` |
+| `--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 |
-| `--dry-run` | Preview planned fixes without editing files — outputs diff previews and `fix-report.json` |
+| `--security-review` | Run the bundled enterprise security-review workflow with threat model + CVE + validation context |
+| `--validate-security` | Force vulnerability-validation for confirmed security findings |
 
 All flags compose: `/bug-hunter --deps --threat-model --fix src/`
 
@@ -574,6 +688,8 @@ All flags compose: `/bug-hunter --deps --threat-model --fix src/`
 
 Bug Hunter ships with a test fixture containing an Express app with **6 intentionally planted bugs** (2 Critical, 3 Medium, 1 Low):
 
+The repository also ships with **60 Node.js regression tests** covering orchestration, schemas, PR scope resolution, fix-plan validation, lock behavior, worktree lifecycle, and the bundled local security-skill routing.
+
 ```bash
 /bug-hunter test-fixture/
 ```
@@ -594,6 +710,8 @@ bug-hunter/
 ├── SKILL.md                              # Pipeline orchestration logic
 ├── README.md                             # This documentation
 ├── CHANGELOG.md                          # Version history
+├── llms.txt                              # Short LLM-facing summary
+├── llms-full.txt                         # Full LLM-facing reference
 ├── package.json                          # npm package config (@codexstar/bug-hunter)
 │
 ├── bin/
@@ -601,11 +719,15 @@ bug-hunter/
 │
 ├── docs/
 │   └── images/                           # Documentation visuals
-│       ├── hero.png                      #   Hero banner
-│       ├── pipeline-overview.png         #   8-stage pipeline diagram
-│       ├── adversarial-debate.png        #   Hunter vs Skeptic vs Referee flow
-│       ├── doc-verify-fix-plan.png       #   Documentation verification + fix planning
-│       └── security-finding-card.png     #   Enriched finding card with CVSS
+│       ├── 2026-03-12-hero-bug-hunter-overview.png   #   Product overview hero
+│       ├── 2026-03-12-pr-review-flow.png             #   PR review + security workflow
+│       ├── 2026-03-12-security-pack.png              #   Bundled local security pack
+│       ├── 2026-03-12-fix-plan-rollout.png           #   Strategic fix planning + rollout
+│       ├── 2026-03-12-machine-readable-artifacts.png #   CI/CD artifact outputs
+│       ├── pipeline-overview.png                     #   8-stage pipeline diagram
+│       ├── adversarial-debate.png                    #   Hunter vs Skeptic vs Referee flow
+│       ├── doc-verify-fix-plan.png                   #   Documentation verification + fix planning
+│       └── security-finding-card.png                 #   Enriched finding card with CVSS
 │
 ├── modes/                                # Execution strategies by codebase size
 │   ├── single-file.md                    #   1 file
@@ -632,6 +754,19 @@ bug-hunter/
 │       ├── hunter-examples.md            #     3 real + 2 false positives
 │       └── skeptic-examples.md           #     2 accepted + 2 disproved + 1 review
 │
+├── schemas/                              # Canonical JSON artifact contracts
+│   ├── findings.schema.json              #   Hunter findings schema
+│   ├── skeptic.schema.json               #   Skeptic artifact schema
+│   ├── referee.schema.json               #   Referee artifact schema
+│   ├── fix-strategy.schema.json          #   Strategic remediation schema
+│   └── fix-plan.schema.json              #   Fix execution schema
+│
+├── skills/                               # Bundled local security pack
+│   ├── commit-security-scan/
+│   ├── security-review/
+│   ├── threat-model-generation/
+│   └── vulnerability-validation/
+│
 ├── scripts/                              # Node.js helpers (zero AI tokens)
 │   ├── triage.cjs                        #   File classification (<2s)
 │   ├── dep-scan.cjs                      #   Dependency CVE scanner