@codexstar/bug-hunter 3.0.0 → 3.0.6

package/modes/single-file.md

@@ -13,7 +13,7 @@ Pass the single file path as the file list. No risk map needed — the file is i
 
 For `local-sequential`: read the prompt file and scan the single file yourself.
 
-After completion, read `.bug-hunter/findings.md`.
+After completion, read `.bug-hunter/findings.json`.
 
 If TOTAL FINDINGS: 0, go to Step 7 (Final Report) in SKILL.md.
 
@@ -25,7 +25,7 @@ Dispatch Skeptic using the standard dispatch pattern (see `_dispatch.md`, role=`
 
 Inject the Hunter's findings.
 
-After completion, read `.bug-hunter/skeptic.md`.
+After completion, read `.bug-hunter/skeptic.json`.
 
 ---
 
@@ -35,4 +35,4 @@ Dispatch Referee using the standard dispatch pattern (see `_dispatch.md`, role=`
 
 Inject Hunter + Skeptic reports.
 
-After completion, read `.bug-hunter/referee.md`. Go to Step 7 (Final Report) in SKILL.md.
+After completion, read `.bug-hunter/referee.json`, render `.bug-hunter/report.md`, and go to Step 7 (Final Report) in SKILL.md.

package/modes/small.md

@@ -33,12 +33,12 @@ Report architecture summary to user.
 Dispatch Hunter using the standard dispatch pattern (see `_dispatch.md`, role=`hunter`).
 
 Pass to the Hunter:
-- File list in risk-map order (CRITICAL → HIGH → MEDIUM). If triage exists, use `triage.scanOrder`.
+- File list in risk-map order (CRITICAL → HIGH → MEDIUM → LOW). If triage exists, use `triage.scanOrder`.
 - Risk map from Recon (or triage).
 - Tech stack from Recon.
 - `doc-lookup.md` contents as phase-specific context.
 
-After completion, read `.bug-hunter/findings.md`.
+After completion, read `.bug-hunter/findings.json`.
 
 If TOTAL FINDINGS: 0, skip Skeptic and Referee. Go to Step 7 (Final Report) in SKILL.md.
 
@@ -48,11 +48,11 @@ If TOTAL FINDINGS: 0, skip Skeptic and Referee. Go to Step 7 (Final Report) in S
 
 Compare the Hunter's FILES SCANNED list against the risk map.
 
-If any CRITICAL or HIGH files appear in FILES SKIPPED:
+If any queued scannable files appear in FILES SKIPPED:
 
-**local-sequential:** Read the missed files yourself now and scan them for bugs. Append new findings to `.bug-hunter/findings.md`.
+**local-sequential:** Read the missed files yourself now in priority order (CRITICAL → HIGH → MEDIUM → LOW) and scan them for bugs. Append new findings to `.bug-hunter/findings.json`.
 
-**subagent/teams:** Launch a second Hunter on ONLY the missed files using the standard dispatch pattern. Merge gap findings into `.bug-hunter/findings.md`.
+**subagent/teams:** Launch a second Hunter on ONLY the missed files using the standard dispatch pattern. Merge gap findings into `.bug-hunter/findings.json`.
 
 ---
 
@@ -61,11 +61,11 @@ If any CRITICAL or HIGH files appear in FILES SKIPPED:
 Dispatch Skeptic using the standard dispatch pattern (see `_dispatch.md`, role=`skeptic`).
 
 Pass to the Skeptic:
-- Hunter findings from `.bug-hunter/findings.md` (compact format: bugId, severity, file, lines, claim, evidence, runtimeTrigger).
+- Hunter findings from `.bug-hunter/findings.json`.
 - Tech stack from Recon.
 - `doc-lookup.md` contents as phase-specific context.
 
-After completion, read `.bug-hunter/skeptic.md`.
+After completion, read `.bug-hunter/skeptic.json`.
 
 ---
 
@@ -74,13 +74,13 @@ After completion, read `.bug-hunter/skeptic.md`.
 Dispatch Referee using the standard dispatch pattern (see `_dispatch.md`, role=`referee`).
 
 Pass to the Referee:
-- Hunter findings from `.bug-hunter/findings.md`.
-- Skeptic challenges from `.bug-hunter/skeptic.md`.
+- Hunter findings from `.bug-hunter/findings.json`.
+- Skeptic challenges from `.bug-hunter/skeptic.json`.
 
-After completion, read `.bug-hunter/referee.md`.
+After completion, read `.bug-hunter/referee.json`.
 
 ---
 
 ## After Step 7
 
-Proceed to **Step 7** (Final Report) in SKILL.md. The Referee output in `.bug-hunter/referee.md` provides the confirmed bugs table, dismissed findings, and coverage stats needed for the final report.
+Proceed to **Step 7** (Final Report) in SKILL.md. The Referee output in `.bug-hunter/referee.json` plus the rendered `.bug-hunter/report.md` provide the confirmed bugs table, dismissed findings, and coverage stats needed for the final report.

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@codexstar/bug-hunter",
-  "version": "3.0.0",
+  "version": "3.0.6",
   "description": "Adversarial AI bug hunter — multi-agent pipeline finds security vulnerabilities, logic errors, and runtime bugs, then fixes them autonomously. Works with Claude Code, Cursor, Codex CLI, Copilot, Kiro, and more.",
   "license": "MIT",
+  "main": "bin/bug-hunter",
   "type": "commonjs",
   "bin": {
     "bug-hunter": "bin/bug-hunter"
@@ -31,10 +32,14 @@
   "files": [
     "bin/",
     "scripts/",
+    "schemas/",
     "prompts/",
     "templates/",
     "modes/",
     "evals/",
+    "docs/",
+    "agents/",
+    "skills/",
     "SKILL.md",
     "README.md",
     "CHANGELOG.md",
@@ -48,7 +53,12 @@
     "url": "https://github.com/codexstar69/bug-hunter/issues"
   },
   "homepage": "https://github.com/codexstar69/bug-hunter#readme",
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
+    "prepublishOnly": "node scripts/prepublish-guard.cjs",
+    "prepack": "node --test scripts/tests/*.test.cjs",
     "test": "node --test scripts/tests/*.test.cjs",
     "doctor": "node bin/bug-hunter doctor",
     "postinstall": "node -e \"console.log('\\n  Run: bug-hunter install    to set up the skill\\n  Run: bug-hunter doctor     to check your environment\\n')\""

package/prompts/fixer.md

@@ -2,17 +2,22 @@ You are a surgical code fixer. You will receive a list of verified bugs from a R
 
 ## Output Destination
 
-Write your fix report to the file path provided in your assignment (typically `.bug-hunter/fix-report.md`). If no path was provided, output to stdout. The report should list each fix applied, the before/after code, and verification results.
+Write your structured fix report to the file path provided in your assignment
+(typically `.bug-hunter/fix-report.json`). If no path was provided, output the
+JSON to stdout. If a Markdown companion is requested, write it only after the
+JSON artifact exists.
 
 ## Scope Rules
 
 - Only fix the bugs listed in your assignment. Do NOT fix other issues you notice.
+- Respect the assigned strategy. If the cluster is marked `manual-review`, `larger-refactor`, or `architectural-remediation`, do not silently upgrade it into a surgical patch.
 - Do NOT refactor, add tests, or improve code style — surgical fixes only.
 - Each fix should change the minimum lines necessary to resolve the bug.
 
 ## What you receive
 
 - **Bug list**: Confirmed bugs with BUG-IDs, file paths, line numbers, severity, description, and suggested fix direction
+- **Fix strategy context**: Whether the assigned cluster is `safe-autofix`, `manual-review`, `larger-refactor`, or `architectural-remediation`
 - **Tech stack context**: Framework, auth mechanism, database, key dependencies
 - **Directory scope**: You are assigned bugs grouped by directory — all bugs in files from the same directory subtree are yours. All bugs in the same file are guaranteed to be in your assignment.
 
@@ -79,25 +84,34 @@ Use only when you need the correct API pattern for a fix. One lookup per fix, ma
 
 ## Output format
 
-After completing all fixes:
-
----
-**FIX REPORT**
-
-**Bugs fixed:**
-
-For each bug:
-**BUG-[N]** | [severity]
-- **File(s) changed:** [list of files and line ranges modified]
-- **What was changed:** [one-sentence description of the actual code change]
-- **Confidence:** [High/Medium/Low — how confident you are this fully resolves the bug]
-- **Side effects:** [None / list any potential side effects or breaking changes]
-- **Notes:** [Any caveats or partial-fix details. "Requires larger refactor" if applicable.]
-
-**Summary:**
-- Bugs assigned: [N]
-- Bugs fixed: [N]
-- Bugs requiring larger refactor: [N] (minimal patches applied)
-- Bugs skipped: [N] (with reason for each)
-- Files modified: [list]
----
+Write a JSON object with this shape:
+
+```json
+{
+  "generatedAt": "2026-03-11T12:00:00.000Z",
+  "summary": {
+    "bugsAssigned": 2,
+    "bugsFixed": 1,
+    "bugsNeedingLargerRefactor": 1,
+    "bugsSkipped": 0,
+    "filesModified": ["src/api/users.ts"]
+  },
+  "fixes": [
+    {
+      "bugId": "BUG-1",
+      "severity": "Critical",
+      "filesChanged": ["src/api/users.ts:45-52"],
+      "whatChanged": "Replaced string interpolation with the parameterized query helper.",
+      "confidenceLabel": "high",
+      "sideEffects": ["None"],
+      "notes": "Minimal patch only."
+    }
+  ]
+}
+```
+
+Rules:
+- Keep the output valid JSON.
+- Use `confidenceLabel` values `high`, `medium`, or `low`.
+- Keep `sideEffects` as an array, using `["None"]` when there are none.
+- Do not add prose outside the JSON object.

package/prompts/hunter.md

@@ -2,7 +2,11 @@ You are a code analysis agent. Your task is to thoroughly examine the provided c
 
 ## Output Destination
 
-Write your complete findings report to the file path provided in your assignment (typically `.bug-hunter/findings.md`). If no path was provided, output to stdout. The orchestrator reads this file to pass your findings to the Skeptic phase.
+Write your canonical findings artifact as JSON to the file path provided in your
+assignment (typically `.bug-hunter/findings.json`). If no path was provided,
+output the JSON to stdout. If the assignment also asks for a Markdown companion,
+write that separately as a derived human-readable summary; the JSON artifact is
+the source of truth the Skeptic and Referee read.
 
 ## Scope Rules
 
@@ -90,25 +94,40 @@ Quality matters more than quantity. The downstream Skeptic agent will challenge
 
 ## Output format
 
-For each finding, use this exact format:
-
----
-**BUG-[number]** | Severity: [Low/Medium/Critical] | Points: [1/5/10]
-- **File:** [exact file path]
-- **Line(s):** [line number or range]
-- **Category:** [logic | security | error-handling | concurrency | edge-case | data-integrity | type-safety | resource-leak | api-contract | cross-file]
-- **STRIDE:** [Spoofing | Tampering | Repudiation | InfoDisclosure | DoS | ElevationOfPrivilege | N/A]
-- **CWE:** [CWE-NNN | N/A]
-- **Claim:** [One-sentence statement of what is wrong — no justification, just the claim]
-- **Evidence:** [Quote the EXACT code from the file, including the line number(s). Copy-paste — do not paraphrase or reconstruct from memory. The Referee will spot-check these quotes against the actual file. If the quote doesn't match, your finding is automatically dismissed.]
-- **Runtime trigger:** [Describe a concrete scenario — what input, API call, or sequence of events causes this bug to manifest. Be specific: "POST /api/users with body {name: null}" not "if the input is invalid"]
-- **Cross-references:** [If this bug involves multiple files, list the other files and line numbers involved. Otherwise write "Single file"]
----
-
-**STRIDE + CWE rules:**
-- `category: security` → STRIDE and CWE are REQUIRED. Choose the most specific match from the CWE Quick Reference below.
-- All other categories (logic, concurrency, etc.) → STRIDE=N/A, CWE=N/A.
-- If a logic bug has security implications (e.g., auth bypass via wrong comparison), reclassify as `category: security`.
+Write a JSON array. Each item must match this contract:
+
+```json
+[
+  {
+    "bugId": "BUG-1",
+    "severity": "Critical",
+    "category": "security",
+    "file": "src/api/users.ts",
+    "lines": "45-49",
+    "claim": "SQL is built from unsanitized user input.",
+    "evidence": "src/api/users.ts:45-49 const query = `...${term}...`",
+    "runtimeTrigger": "GET /api/users?term=' OR '1'='1",
+    "crossReferences": ["src/db/query.ts:10-18"],
+    "confidenceScore": 93,
+    "confidenceLabel": "high",
+    "stride": "Tampering",
+    "cwe": "CWE-89"
+  }
+]
+```
+
+Rules:
+- Return a valid empty array `[]` when you found no bugs.
+- `confidenceScore` must be numeric on a `0-100` scale.
+- `confidenceLabel` is optional, but if present it must be `high`, `medium`,
+  or `low`.
+- `crossReferences` must always be an array. Use `["Single file"]` when no
+  extra file is involved.
+- `category: security` requires specific `stride` and `cwe` values.
+- Non-security findings must use `stride: "N/A"` and `cwe: "N/A"`.
+- Do not append coverage summaries, totals, or prose outside the JSON array.
+- If the assignment also requested a Markdown companion, render it from this
+  JSON after writing the canonical artifact.
 
 ## CWE Quick Reference (security findings only)
 

package/prompts/referee.md

@@ -6,7 +6,10 @@ You will receive both the Hunter findings file and the Skeptic challenges file.
 
 ## Output Destination
 
-Write your complete Referee verdict report to the file path provided in your assignment (typically `.bug-hunter/referee.md`). If no path was provided, output to stdout. This is the FINAL phase — your verdicts determine which bugs are confirmed.
+Write your canonical Referee verdict artifact as JSON to the file path provided
+in your assignment (typically `.bug-hunter/referee.json`). If no path was
+provided, output the JSON to stdout. If a Markdown report is requested, render
+it from this JSON artifact after writing the canonical file.
 
 ## Scope Rules
 
@@ -56,20 +59,38 @@ Before final report: (1) Coverage — did you evaluate every BUG-ID from both re
 
 ## Output format
 
-Per bug:
-```
-**BUG-N** | Verification: INDEPENDENTLY VERIFIED / EVIDENCE-BASED
-- **Hunter's claim:** [summary]
-- **Skeptic's response:** DISPROVE/ACCEPT [summary]
-- **My analysis:** [what you traced and found]
-- **VERDICT: REAL BUG / NOT A BUG** | Confidence: High/Medium/Low
-- **True severity:** [Critical/Medium/Low] (if changed, explain)
-- **Suggested fix:** [concrete: function name, check to add, line to change]
+Write a JSON array. Each item must match this contract:
+
+```json
+[
+  {
+    "bugId": "BUG-1",
+    "verdict": "REAL_BUG",
+    "trueSeverity": "Critical",
+    "confidenceScore": 94,
+    "confidenceLabel": "high",
+    "verificationMode": "INDEPENDENTLY_VERIFIED",
+    "analysisSummary": "Confirmed by tracing user-controlled input into an unsafe sink without validation.",
+    "suggestedFix": "Validate the input before building the query and use the parameterized helper."
+  }
+]
 ```
 
+Rules:
+- `verdict` must be one of `REAL_BUG`, `NOT_A_BUG`, or `MANUAL_REVIEW`.
+- `confidenceScore` must be numeric on a `0-100` scale.
+- `confidenceLabel` must be `high`, `medium`, or `low`.
+- `verificationMode` must be `INDEPENDENTLY_VERIFIED` or `EVIDENCE_BASED`.
+- Keep the reasoning in `analysisSummary`; do not emit free-form prose outside
+  the JSON array.
+- Return `[]` only when there were no findings to referee.
+
 ### Security enrichment (confirmed security bugs only)
 
-For each finding with `category: security` that you confirm as REAL BUG, add these fields below the verdict:
+For each finding with `category: security` that you confirm as `REAL_BUG`,
+include the security enrichment details in `analysisSummary` and
+`suggestedFix`. Until the schema grows extra typed security fields, do not emit
+out-of-contract keys.
 
 **Reachability** (required for all security findings):
 - `EXTERNAL` — reachable from unauthenticated external input (public API, form, URL)
@@ -111,12 +132,5 @@ Non-security findings use the standard verdict format above (no enrichment neede
 
 ## Final Report
 
-**VERIFIED BUG REPORT**
-
-Stats: Total reported | Dismissed | Confirmed (Critical/Medium/Low) | Independently verified vs Evidence-based | Per-Hunter accuracy (if parallel) | Skeptic accuracy
-
-Confirmed bugs table: # | Severity | STRIDE | CWE | Reachability | File | Lines | Description | Fix | Verification
-
-Low-confidence items (flagged for manual review): file + one-line uncertainty reason.
-
-<details><summary>Dismissed findings</summary>Table: # | Claim | Skeptic Position | Reason</details>
+If a human-readable report is requested, generate it from the final JSON array.
+The JSON artifact remains canonical.

package/prompts/skeptic.md

@@ -6,7 +6,10 @@ Read the Hunter findings file completely before starting. Each finding has BUG-I
 
 ## Output Destination
 
-Write your Skeptic challenge report to the file path in your assignment (typically `.bug-hunter/skeptic.md`). The Referee reads both Hunter findings and your challenges.
+Write your canonical Skeptic artifact as JSON to the file path in your
+assignment (typically `.bug-hunter/skeptic.json`). The Referee reads the JSON
+artifact, not a free-form Markdown note. If the assignment also asks for a
+Markdown companion, that Markdown must be derived from the JSON output.
 
 ## Scope Rules
 
@@ -91,28 +94,28 @@ Before writing your final summary, verify:
 
 ## Output format
 
-For each bug:
-
----
-**BUG-[number]** | Original: [points] pts
-- **Code reviewed:** [List the files and line ranges you actually read to evaluate this — must include all cross-referenced files]
-- **Runtime trigger test:** [Did you trace the Hunter's exact scenario? What actually happens at each step?]
-- **Counter-argument:** [Your specific technical argument, citing code]
-- **Evidence:** [Quote the actual code or behavior that supports your position]
-- **Confidence:** [0-100]%
-- **Risk calc:** EV = ([confidence]% x [points]) - ([100-confidence]% x [2 x points]) = [value]
-- **Decision:** DISPROVE / ACCEPT
----
-
-After all bugs, output:
-
-**SUMMARY:**
-- Bugs disproved: [count] (total points claimed: [sum])
-- Bugs accepted as real: [count]
-- Files read during review: [list of files you actually read]
+Write a JSON array. Each item must match this contract:
+
+```json
+[
+  {
+    "bugId": "BUG-1",
+    "response": "DISPROVE",
+    "analysisSummary": "The route is wrapped by auth middleware before this handler runs, so the claimed bypass is not reachable.",
+    "counterEvidence": "src/routes/api.ts:10-21 attaches requireAuth before the handler."
+  }
+]
+```
 
-**ACCEPTED BUG LIST:**
-[List only the BUG-IDs that you ACCEPTED, with their original severity, file path, and primary file cluster]
+Rules:
+- Use `response: "ACCEPT"` when the finding stands as a real bug.
+- Use `response: "DISPROVE"` only when your challenge is strong enough to
+  survive Referee review.
+- Use `response: "MANUAL_REVIEW"` when you cannot safely disprove or accept the
+  finding.
+- Return `[]` when there were no findings to challenge.
+- Keep all reasoning inside `analysisSummary` and optional `counterEvidence`.
+- Do not append summary prose outside the JSON array.
 
 ## Doc Lookup Tool
 

package/schemas/coverage.schema.json

@@ -0,0 +1,67 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "schemaVersion": 1,
+  "artifact": "coverage",
+  "title": "Bug Hunter Coverage Artifact",
+  "type": "object",
+  "required": ["schemaVersion", "iteration", "status", "files", "bugs", "fixes"],
+  "properties": {
+    "schemaVersion": {
+      "type": "integer",
+      "minimum": 1
+    },
+    "iteration": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "status": {
+      "type": "string",
+      "enum": ["IN_PROGRESS", "COMPLETE"]
+    },
+    "files": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["path", "status"],
+        "properties": {
+          "path": { "type": "string", "minLength": 1 },
+          "status": {
+            "type": "string",
+            "enum": ["pending", "in_progress", "done", "failed"]
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "bugs": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["bugId", "severity", "file", "claim"],
+        "properties": {
+          "bugId": { "type": "string", "minLength": 1 },
+          "severity": {
+            "type": "string",
+            "enum": ["Critical", "Medium", "Low"]
+          },
+          "file": { "type": "string", "minLength": 1 },
+          "claim": { "type": "string", "minLength": 1 }
+        },
+        "additionalProperties": false
+      }
+    },
+    "fixes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["bugId", "status"],
+        "properties": {
+          "bugId": { "type": "string", "minLength": 1 },
+          "status": { "type": "string", "minLength": 1 }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/examples/findings.invalid.json

@@ -0,0 +1,13 @@
+[
+  {
+    "bugId": "BUG-1",
+    "severity": "Critical",
+    "category": "security",
+    "file": "src/example.ts",
+    "lines": "12-16",
+    "evidence": "src/example.ts:12-16 unvalidated body flows into exec().",
+    "runtimeTrigger": "POST /api/example with body {\"command\":\"rm -rf /\"}",
+    "crossReferences": ["src/router.ts:8-14"],
+    "confidenceScore": 92
+  }
+]

package/schemas/examples/findings.valid.json

@@ -0,0 +1,17 @@
+[
+  {
+    "bugId": "BUG-1",
+    "severity": "Critical",
+    "category": "security",
+    "file": "src/example.ts",
+    "lines": "12-16",
+    "claim": "Request body reaches a dangerous sink without validation.",
+    "evidence": "src/example.ts:12-16 unvalidated body flows into exec().",
+    "runtimeTrigger": "POST /api/example with body {\"command\":\"rm -rf /\"}",
+    "crossReferences": ["src/router.ts:8-14"],
+    "confidenceScore": 92,
+    "confidenceLabel": "high",
+    "stride": "Tampering",
+    "cwe": "CWE-78"
+  }
+]

package/schemas/findings.schema.json

@@ -0,0 +1,76 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "schemaVersion": 1,
+  "artifact": "findings",
+  "title": "Bug Hunter Findings Artifact",
+  "type": "array",
+  "items": {
+    "type": "object",
+    "required": [
+      "bugId",
+      "severity",
+      "category",
+      "file",
+      "lines",
+      "claim",
+      "evidence",
+      "runtimeTrigger",
+      "crossReferences",
+      "confidenceScore"
+    ],
+    "properties": {
+      "bugId": { "type": "string", "minLength": 1 },
+      "severity": {
+        "type": "string",
+        "enum": ["Critical", "Medium", "Low"]
+      },
+      "category": {
+        "type": "string",
+        "enum": [
+          "logic",
+          "security",
+          "error-handling",
+          "concurrency",
+          "edge-case",
+          "data-integrity",
+          "type-safety",
+          "resource-leak",
+          "api-contract",
+          "cross-file"
+        ]
+      },
+      "file": { "type": "string", "minLength": 1 },
+      "lines": { "type": "string", "minLength": 1 },
+      "claim": { "type": "string", "minLength": 1 },
+      "evidence": { "type": "string", "minLength": 1 },
+      "runtimeTrigger": { "type": "string", "minLength": 1 },
+      "crossReferences": {
+        "type": "array",
+        "items": { "type": "string", "minLength": 1 }
+      },
+      "confidenceScore": {
+        "type": "number",
+        "minimum": 0,
+        "maximum": 100
+      },
+      "confidenceLabel": {
+        "type": "string",
+        "enum": ["high", "medium", "low"]
+      },
+      "stride": {
+        "type": "string",
+        "enum": [
+          "Spoofing",
+          "Tampering",
+          "Repudiation",
+          "InfoDisclosure",
+          "DoS",
+          "ElevationOfPrivilege",
+          "N/A"
+        ]
+      },
+      "cwe": { "type": "string", "minLength": 1 }
+    },
+    "additionalProperties": false
+  }
+}