@lhi/tdd-audit 1.18.0 → 1.20.0

package/README.md

@@ -1,41 +1,124 @@
 # @lhi/tdd-audit
-![Coverage](https://img.shields.io/badge/coverage-95%25-brightgreen)
+![Coverage](https://img.shields.io/badge/coverage-98%25-brightgreen)
 [![tdd-audit](https://img.shields.io/badge/tdd--audit-passing-brightgreen)](https://www.npmjs.com/package/@lhi/tdd-audit) <!-- tdd-audit-badge -->
 
-> **v1.18.0** — AI-powered security audit skill for **Claude Code, Gemini CLI, Cursor, Codex, and OpenCode**. Four output depth tiers let you choose between a fast scan report, a rich findings report, copy-ready patches, or fully automated patch application — all backed by an agentic LLM with tool use.
+> **Your AI-generated code is probably vulnerable right now.** SQL injection. Hardcoded secrets. Prompt injection backdoors. The same assistant that built your feature in 30 minutes didn't think twice about security. `tdd-audit` finds the holes, proves they're real, and closes them — every fix backed by a failing test before and a passing test after.
+
+## One command. Proven secure.
+
+```bash
+npx @lhi/tdd-audit --local --claude
+```
+
+That's it. In seconds you get:
+
+- A severity-ranked findings report (CRITICAL → LOW) with the exact file and line
+- Exploit tests that **prove the vulnerability is real** — not theoretical
+- Patches that close each hole, verified by a passing test suite
+- ≥ 95% test coverage enforced, a README security badge, and a `SECURITY.md` ready for auditors
+
+No security expertise required. No config needed to start.
+
+---
+
+## Why this exists
+
+Vibecoders move fast. AI assistants hallucinate security. The result: apps with SQL injection in the ORM layer, JWT algorithm confusion, hardcoded API keys one `git log` away from leaking, and LLM prompt injection that hands your backend to anyone who knows the trick.
+
+PMs and security officers feel it too — "is this thing actually secure?" has no good answer when there are no tests proving it.
+
+`tdd-audit` gives you the answer. Every vulnerability is proven closed by a test, not just patched and hoped for the best.
+
+---
 
 ## Install
 
 ```bash
-npx @lhi/tdd-audit
+# Claude Code (recommended)
+npx @lhi/tdd-audit --local --claude
+
+# Gemini CLI / Codex / OpenCode / Cursor
+npx @lhi/tdd-audit --local
 ```
 
 On first run the installer:
 
-1. Scaffolds `__tests__/security/` with a framework-matched exploit test boilerplate
+1. Scaffolds `__tests__/security/` with framework-matched exploit test boilerplate
 2. Adds `test:security` to `package.json`
-3. Creates `.github/workflows/security-tests.yml` with SHA-pinned actions and `npm audit`
-4. Installs the `/tdd-audit` skill for your AI agent
+3. Creates `.github/workflows/security-tests.yml` — SHA-pinned actions, `npm audit` on every PR
+4. Installs the `/tdd-audit` skill in your AI agent
 
-### Flags
+Then open your agent and type `/tdd-audit`. It handles the rest.
 
-| Flag | Description |
+### Install flags
+
+| Flag | What it does |
 |---|---|
-| `--local` | Install into the current project instead of `~` |
-| `--claude` | Use `.claude/` instead of `.agents/` |
-| `--with-hooks` | Add a pre-commit hook that blocks commits on failing security tests |
-| `--skip-scan` | Skip the vulnerability scan on install |
-| `--config <path>` | Load config from an explicit file path |
+| `--local` | Install into the current project (recommended) |
+| `--claude` | Use `.claude/` for Claude Code |
+| `--with-hooks` | Block commits that break security tests |
+| `--skip-scan` | Skip the initial vulnerability scan |
+| `--config <path>` | Load config from a specific path |
 
-### Platform
+---
 
-| Platform | Command |
-|---|---|
-| Claude Code | `npx @lhi/tdd-audit --local --claude` |
-| Gemini CLI / Codex / OpenCode | `npx @lhi/tdd-audit --local` |
+## What gets caught
+
+100+ patterns across Node.js, Python, Go, React, React Native, Flutter, and Expo — including the AI-specific vulnerabilities that most scanners miss entirely:
+
+**Standard OWASP holes** — SQL/NoSQL/Command injection · Path traversal · Broken auth · XSS · IDOR · Mass assignment · SSRF · Open redirect · XXE · Insecure deserialization · Prototype pollution · Weak crypto · Hardcoded secrets · TLS bypass
+
+**AI / LLM-specific** (the ones that will actually get you hacked in 2025) — LLM prompt injection · Eval of model output · LangChain ShellTool / ExecChain · Unbounded agent loops · MCP credential leakage · GitHub Actions expression injection · Hardcoded provider keys (OpenAI, Anthropic, Gemini, Cohere, Mistral, HuggingFace) · Missing `max_tokens` · Dynamic require from user input · VM sandbox escape · Electron `nodeIntegration: true`
+
+**Vibecoding anti-patterns** — `localStorage` token storage · `Math.random()` for session IDs · `process.env.SECRET || "hardcoded-fallback"` · Silent exception swallowing · Insecure WebSocket URLs
+
+---
+
+## How it works
+
+The full `/tdd-audit` skill run follows Red-Green-Refactor for every finding:
+
+1. **Detect** — scans your stack, scopes patterns to what's actually relevant
+2. **Report** — presents a CRITICAL → LOW findings table with plain-language risk and effort estimate. Waits for your sign-off before touching anything
+3. **Red** — writes an exploit test that **fails** (proves the hole is real)
+4. **Green** — applies the patch (test now passes)
+5. **Refactor** — runs the full suite (zero regressions)
+6. **Harden** — security headers, rate limiting, `npm audit`, secret scan, production error handling
+7. **Coverage gate** — pushes test coverage to ≥ 95% line and branch
+8. **Badge + SECURITY.md** — updates your README badge, creates `SECURITY.md` in GitHub Security Advisory format
+
+Nothing is marked done until a test proves it.
+
+---
+
+## For PMs and security officers
+
+You need evidence, not promises. `tdd-audit` produces:
+
+- **Exploit tests** — a failing test per vulnerability, committed to source, proves the hole existed
+- **Passing tests** — the fix is proven by the test suite, not just code review
+- **`--format report`** — a markdown compliance report with findings table, fix evidence, patch commits, and coverage gate result; ready to attach to SOC 2, ISO 27001, or vendor security questionnaire
+- **`--sbom`** — CycloneDX Software Bill of Materials (required for US federal contracts under EO 14028)
+- **`SECURITY.md`** — GitHub Security Advisory format with your security contact, supported versions, and hardening summary
+- **Webhook + Slack notifications** — findings summary delivered to your security channel on every scan
+
+Configure your security contact in `.tdd-audit.json`:
+
+```json
+{
+  "security_name":  "Alice Smith",
+  "security_email": "security@yourorg.com"
+}
+```
+
+Both fields are optional — use one, both, or neither. When set, they appear in SECURITY.md, the compliance report, and webhook payloads.
+
+---
 
 ## AI Audit (`--ai`)
 
+Let the LLM explore and report on your codebase directly:
+
 ```bash
 npx @lhi/tdd-audit --ai \
   --provider anthropic \
@@ -44,32 +127,27 @@ npx @lhi/tdd-audit --ai \
   --format json
 ```
 
-The `--ai` flag triggers a full agentic audit: the LLM explores your codebase using `read_file`, `list_files`, and `search_in_files` tool calls, then produces a structured findings report shaped by `--depth`.
-
 ### Depth tiers
 
-| Tier | Mode | Output | Billing unit |
+| Tier | Mode | What you get | Billing unit |
 |---|---|---|---|
-| `tier-1` | scan-only | `name`, `severity`, `file`, `line`, `snippet` | per report |
-| `tier-2` | scan-only | + `risk`, `effort`, `cwe`, `owasp`, `references` | per report |
-| `tier-3` | full audit, read-only | + `patch` (copy-ready), `testSnippet` | per report |
-| `tier-4` | full audit, writes enabled | LLM applies patches via `write_file`; `patchesApplied` in envelope | per applied patch |
+| `tier-1` | Scan only | File, line, severity, snippet | per report |
+| `tier-2` | Scan only | + risk explanation, effort estimate, CWE, OWASP, references | per report |
+| `tier-3` | Full audit, read-only | + copy-ready patches and test snippets — you apply manually | per report |
+| `tier-4` | Full audit, writes | LLM applies every patch via `write_file` | per applied patch |
 
 ```bash
-# Minimal scan report
+# Fast scan — just the findings
 npx @lhi/tdd-audit --ai --depth tier-1 --format json
 
-# Rich report with CWE/OWASP/references — no changes made
+# Full report with context, no changes made
 npx @lhi/tdd-audit --ai --depth tier-2 --format json
 
-# Copy-ready patches in every finding — apply manually
+# Copy-ready patches — apply yourself
 npx @lhi/tdd-audit --ai --depth tier-3 --format json
 
-# Let the LLM apply the patches for you
+# Let the LLM fix everything
 npx @lhi/tdd-audit --ai --depth tier-4 --allow-writes
-
-# Targeted apply: apply one specific patch from a prior tier-3 report
-# (via REST API — see docs/rest-api.md)
 ```
 
 ### AI flags
@@ -77,132 +155,129 @@ npx @lhi/tdd-audit --ai --depth tier-4 --allow-writes
 | Flag | Description |
 |---|---|
 | `--ai` | Enable LLM agentic audit |
-| `--depth tier-1\|tier-2\|tier-3\|tier-4` | Output depth tier (default: `tier-1`) |
+| `--depth tier-1\|2\|3\|4` | Output depth tier (default: `tier-1`) |
 | `--allow-writes` | Permit the LLM to write files (auto-enabled for `tier-4`) |
 | `--provider <name>` | `anthropic` \| `openai` \| `gemini` \| `ollama` |
 | `--api-key <key>` | Provider API key |
 | `--model <name>` | Model override (e.g. `claude-opus-4-6`, `gpt-4o`) |
-| `--base-url <url>` | Base URL for any OpenAI-compatible service |
-| `--format json\|sarif` | Structured output format (default: streaming text) |
+| `--base-url <url>` | Any OpenAI-compatible service |
+| `--format json\|sarif\|report` | Structured output format |
 | `--verbose` | Print tool call details to stderr |
 
-## Config file
+---
+
+## CI integration
+
+### PR gate — block merges on new findings
+
+```yaml
+- run: npx @lhi/tdd-audit@latest --pr --threshold HIGH
+```
+
+Exits non-zero if any finding meets or exceeds the threshold. Sub-second — no AI, no agents, pure static scan. Wire into branch protection rules to stop vulnerable code from merging.
+
+### Org-wide posture scan
+
+```bash
+npx @lhi/tdd-audit@latest --org my-github-org --format report
+```
+
+Scans every repo in the org, produces a cross-org summary and a compliance report. Fires your webhook/Slack with the aggregate payload.
 
-Scaffold a starter config with a single command:
+---
+
+## Config file
 
 ```bash
-npx @lhi/tdd-audit init
-# or at a custom path:
-npx @lhi/tdd-audit init ~/configs/my-audit.json
+npx @lhi/tdd-audit init                      # scaffold .tdd-audit.json
+npx @lhi/tdd-audit init --provider anthropic  # with Anthropic defaults
 ```
 
-`.tdd-audit.json` — all CLI flags settable here, loaded automatically from your project root:
+`.tdd-audit.json` — everything settable here, CLI flags always win:
 
 ```json
 {
-  "provider":          "openai",
-  "model":             "gpt-4o",
-  "apiKeyEnv":         "OPENAI_API_KEY",
-  "baseUrl":           null,
-  "output":            "json",
-  "severityThreshold": "LOW",
-  "port":              3000,
-  "serverApiKey":      null,
-  "trustProxy":        false,
-  "ignore":            ["node_modules", "dist", "build", "coverage"]
+  "provider":          "anthropic",
+  "model":             "claude-opus-4-6",
+  "apiKeyEnv":         "ANTHROPIC_API_KEY",
+  "severityThreshold": "HIGH",
+  "ignore":            ["node_modules", "dist", "coverage"],
+
+  "security_name":     "Alice Smith",
+  "security_email":    "security@yourorg.com",
+
+  "webhook_url":       "https://hooks.yourorg.com/security",
+  "slack_webhook":     "https://hooks.slack.com/services/...",
+  "slack_channel":     "#security-alerts",
+
+  "severity_overrides": {
+    "CORS Wildcard": "CRITICAL"
+  }
 }
 ```
 
-Point to a config anywhere with `--config`:
+Full schema → [docs/configuration.md](docs/configuration.md)
 
-```bash
-npx @lhi/tdd-audit serve --config ~/configs/prod-audit.json
-```
+---
 
 ## REST API
 
 ```bash
-# Start the API server
 npx @lhi/tdd-audit serve --port 3000 --api-key YOUR_SECRET
-
-# AI audit — returns jobId immediately
-curl -X POST http://localhost:3000/audit/ai \
-  -H "Authorization: Bearer YOUR_SECRET" \
-  -H "Content-Type: application/json" \
-  -d '{"provider": "anthropic", "apiKey": "sk-ant-...", "depth": "tier-2"}' \
-  | jq '.jobId'
-
-# Poll job status
-curl http://localhost:3000/jobs/<jobId>
-
-# Or stream real-time LLM output via SSE
-curl -N http://localhost:3000/jobs/<jobId>/stream
-
-# Targeted apply: re-apply a specific patch from a tier-3 report
-curl -X POST http://localhost:3000/audit/ai \
-  -H "Authorization: Bearer YOUR_SECRET" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "provider": "anthropic",
-    "apiKey": "sk-ant-...",
-    "depth": "tier-4",
-    "findings": [{ "name": "SQL Injection", "file": "src/db.js", "line": 10, "patch": "..." }]
-  }'
-
-# Use any OpenAI-compatible service (Groq, OpenRouter, Together AI, etc.)
-npx @lhi/tdd-audit serve \
-  --provider openai \
-  --base-url https://api.groq.com/openai/v1 \
-  --api-key $GROQ_API_KEY \
-  --model llama-3.3-70b-versatile
 ```
 
-Supported providers: `anthropic` · `openai` · `gemini` · `ollama` (local) · **any OpenAI-compatible endpoint via `--base-url`**
-
-### Endpoints
-
 | Method | Path | Auth | Description |
 |---|---|---|---|
-| `GET` | `/health` | No | Version + liveness check |
-| `POST` | `/audit/ai` | Yes | Agentic LLM audit with depth tiers; returns `jobId` |
+| `GET` | `/health` | No | Liveness check |
+| `POST` | `/audit/ai` | Yes | LLM audit with depth tiers; returns `jobId` |
+| `POST` | `/scan` | Yes | Static scan; returns findings immediately |
 | `POST` | `/remediate` | Yes | AI-fix a provided findings list; returns `jobId` |
-| `POST` | `/audit` | Yes | Static scan + AI remediation pipeline; returns `jobId` |
 | `GET` | `/jobs/:id` | Yes | Poll job status |
-| `GET` | `/jobs/:id/stream` | Yes | SSE stream — real-time job progress |
+| `GET` | `/jobs/:id/stream` | Yes | SSE — stream live LLM output |
 
-## Agent skill
+```bash
+# Start an AI audit
+curl -X POST http://localhost:3000/audit/ai \
+  -H "Authorization: Bearer YOUR_SECRET" \
+  -H "Content-Type: application/json" \
+  -d '{"provider": "anthropic", "apiKey": "sk-ant-...", "depth": "tier-2"}'
 
-```text
-/tdd-audit
+# Stream results live
+curl -N http://localhost:3000/jobs/<jobId>/stream
 ```
 
-The agent detects your stack, presents a CRITICAL → LOW findings report, waits for confirmation, then works through each vulnerability one at a time using Red-Green-Refactor (prove the hole exists, apply the fix, prove it's closed). Enforces ≥ 95% test coverage, README badge, and SECURITY.md on every audit.
+Supported providers: `anthropic` · `openai` · `gemini` · `ollama` · **any OpenAI-compatible endpoint via `--base-url`**
 
-## Testing
+---
 
-791 tests across unit, E2E, and security suites:
+## Testing
 
 ```bash
-npm test                  # full suite
-npm run test:unit         # unit tests with coverage (95.6% branch coverage)
+npm test                  # full suite (841 tests)
+npm run test:unit         # unit tests with coverage
 npm run test:security     # security regression tests only
 npm run test:e2e          # end-to-end REST API tests
 ```
 
-Security tests cover prompt injection, path traversal, rate limiting, timing-safe auth, job store bounds, SARIF schema, and more. See [__tests__/security/](__tests__/security/) for all regression tests.
+Security tests cover: prompt injection · path traversal · SSRF via webhook and baseUrl · rate limiting · timing-safe auth · XFF bypass · job store bounds · SARIF schema · AI key redaction · coverage skip detection · and more. Every past vulnerability is a permanent regression test.
+
+---
 
 ## Documentation
 
 | | |
 |---|---|
+| [Configuration](docs/configuration.md) | Full schema — all fields, CLI equivalents, payload schemas |
 | [REST API](docs/rest-api.md) | Endpoints, auth, rate limiting, depth tiers, targeted apply |
-| [AI Remediation](docs/ai-remediation.md) | Provider setup, `--base-url` for compatible APIs, config file |
-| [Vulnerability Patterns](docs/vulnerability-patterns.md) | All 79 patterns — descriptions, grep signatures, fix pointers |
+| [AI Remediation](docs/ai-remediation.md) | Provider setup, `--base-url` for compatible APIs |
+| [Vulnerability Patterns](docs/vulnerability-patterns.md) | All 100+ patterns — descriptions, grep signatures, fix pointers |
 | [TDD Protocol](docs/tdd-protocol.md) | Red-Green-Refactor in full, with framework templates for all 6 stacks |
 | [Agentic AI Security](docs/agentic-ai-security.md) | ASI01–ASI10 — prompt injection, MCP supply chain, Actions injection |
 | [Hardening](docs/hardening.md) | Phase 4 controls — Helmet, CSP, CSRF, rate limiting, gitleaks, SRI |
 | [CI/CD](docs/ci-cd.md) | Workflow templates, existing pipeline integration, secret leak prevention |
 
+---
+
 ## License
 
 MIT

package/docs/configuration.md

@@ -0,0 +1,236 @@
+# Configuration Reference
+
+All `tdd-audit` behaviour is controlled by `.tdd-audit.json` at your repo root. CLI flags override file config; file config overrides built-in defaults.
+
+Generate a starter file:
+```bash
+npx @lhi/tdd-audit@latest init
+npx @lhi/tdd-audit@latest init --provider anthropic
+```
+
+---
+
+## Full schema
+
+```jsonc
+{
+  // ── Core ──────────────────────────────────────────────────────────────────
+  "output":            "text",      // "text" | "json" | "sarif" | "report"
+  "severityThreshold": "LOW",       // minimum severity to include: "LOW" | "MEDIUM" | "HIGH" | "CRITICAL"
+  "ignore":            [],          // path prefixes to skip: ["node_modules", "dist"]
+  "port":              3000,        // port for `tdd-audit serve`
+  "serverApiKey":      null,        // required on REST API calls; falls back to TDD_AUDIT_API_KEY env var
+
+  // ── AI provider ───────────────────────────────────────────────────────────
+  "provider":  "anthropic",         // "anthropic" | "openai" | "gemini" | "ollama"
+  "model":     "claude-opus-4-6",
+  "apiKeyEnv": "ANTHROPIC_API_KEY", // env var to read the key from
+  "baseUrl":   null,                // override for OpenAI-compatible providers
+
+  // ── Branding ──────────────────────────────────────────────────────────────
+  // For wrapper/rebranded distributions. See docs/extensibility.md.
+  "org":          "Daily Caller",
+  "project":      "my-project",
+  "badge_label":       "dc-audit",                   // replaces "tdd-audit" in the shields.io badge
+  "tdd_site":          "https://security.example.com", // replaces npm link in badge + SARIF
+  "security_name":     "Alice Smith",                   // name of the security contact — stamped into SECURITY.md, compliance reports, and webhook payloads
+  "security_email":    "security@example.com",           // email for the vulnerability reporting address in SECURITY.md and payloads
+
+  // ── Policy as code ────────────────────────────────────────────────────────
+  // Override the default severity for any named pattern.
+  // Useful when a pattern's default severity doesn't match your org's risk model.
+  "severity_overrides": {
+    "CORS Wildcard":   "CRITICAL",  // default: MEDIUM
+    "Sensitive Log":   "HIGH",      // default: MEDIUM
+    "Cleartext Traffic": "HIGH"     // default: MEDIUM
+  },
+
+  // ── Notifications ─────────────────────────────────────────────────────────
+  // Fired when a scan completes. Both can be set simultaneously.
+  "webhook_url":   "https://hooks.example.com/tdd-audit",
+  // POST body: { project, timestamp, summary: { critical, high, medium, low }, findings: [...] }
+
+  "slack_webhook": "https://hooks.slack.com/services/...",
+  "slack_channel": "#security",     // optional override; uses webhook default if absent
+
+  // ── Workflow integration ───────────────────────────────────────────────────
+  "open_pr":      true,   // open a GitHub PR per finding instead of committing directly
+  "github_token": null,   // falls back to GITHUB_TOKEN env var
+  "github_repo":  null,   // "owner/repo" — auto-detected from git remote if null
+
+  // ── CI / scheduled modes ──────────────────────────────────────────────────
+  "pr_mode":   false,     // lightweight static scan only — fast, designed for PR gates
+  "org_scan":  null,      // "my-github-org" — scan all repos in the org
+  "schedule":  null,      // cron expression for external schedulers: "0 2 * * *"
+
+  // ── Output additions ──────────────────────────────────────────────────────
+  "sbom":   false,    // generate CycloneDX SBOM alongside the audit
+  "report": false,    // generate human-readable compliance report (markdown)
+  "watch":  false,    // re-scan affected files on save (watch mode)
+
+  // ── Secret rotation ───────────────────────────────────────────────────────
+  "rotate_secrets": false,  // when a hardcoded key is detected, prompt to rotate via provider API
+
+  // ── Extensibility ─────────────────────────────────────────────────────────
+  // See docs/extensibility.md for full documentation.
+  "pattern_repos":    [],
+  "extra_skill_dirs": [],
+  "extra_repos":      [],
+  "mcp_services":     [],
+  "extra_domains":    []
+}
+```
+
+---
+
+## CLI flag equivalents
+
+| Config key | CLI flag |
+|---|---|
+| `output: "json"` | `--json` or `--format json` |
+| `output: "sarif"` | `--format sarif` |
+| `output: "report"` | `--format report` |
+| `pr_mode: true` | `--pr` |
+| `org_scan: "myorg"` | `--org myorg` |
+| `open_pr: true` | `--open-pr` |
+| `sbom: true` | `--sbom` |
+| `watch: true` | `--watch` |
+| `report: true` | `--report` |
+| `rotate_secrets: true` | `--rotate-secrets` |
+| `provider: "openai"` | `--provider openai` |
+| `model: "gpt-4o"` | `--model gpt-4o` |
+| `severityThreshold: "HIGH"` | `--threshold HIGH` |
+
+CLI flags always win over file config.
+
+---
+
+## Policy as code
+
+`severity_overrides` lets you redefine what severity means for your org without forking the scanner. The key is the exact pattern name from the [vulnerability patterns reference](./vulnerability-patterns.md).
+
+```json
+"severity_overrides": {
+  "CORS Wildcard": "CRITICAL"
+}
+```
+
+This is applied before findings are reported, before notifications fire, and before PR gates are evaluated. A pattern overridden to `CRITICAL` will block a PR merge just like any built-in CRITICAL.
+
+---
+
+## Notifications
+
+Both `webhook_url` and `slack_webhook` fire after every scan (CLI, `--ai`, and `POST /scan`).
+
+**Webhook payload:**
+```json
+{
+  "project":   "my-project",
+  "org":       "My Org",
+  "timestamp": "2026-03-26T12:00:00Z",
+  "duration_ms": 4200,
+  "summary":   { "critical": 1, "high": 3, "medium": 2, "low": 0 },
+  "findings":  [ ... ]
+}
+```
+
+**Slack message format:**
+```
+🔴 tdd-audit — my-project
+1 critical · 3 high · 2 medium
+Run /caller-audit to remediate.
+```
+
+---
+
+## PR mode (`--pr`)
+
+Designed for CI PR gates. Runs only the static scanner — no AI agents, no RAG, no fixes. Completes in under a second.
+
+```yaml
+- run: npx @lhi/tdd-audit@latest --pr --threshold HIGH
+```
+
+Exits non-zero if any finding meets or exceeds `severityThreshold`. Wire into your branch protection rules to block merges automatically.
+
+Use `severity_overrides` to tune what counts as a blocker for your stack.
+
+---
+
+## Auto-fix PR (`--open-pr`)
+
+Instead of committing fixes directly to the working branch, opens a GitHub PR per finding. Each PR contains:
+- The exploit test (Red)
+- The patch (Green)
+- A description linking to the vulnerability pattern
+
+Requires `GITHUB_TOKEN` in the environment or `github_token` in config.
+
+---
+
+## Watch mode (`--watch`)
+
+```bash
+npx @lhi/tdd-audit@latest --watch
+```
+
+Re-runs the static scanner on any modified file on save. Reports new findings immediately in the terminal. Does not run agents or apply fixes — use `/caller-audit` for that.
+
+---
+
+## SBOM (`--sbom`)
+
+Generates a [CycloneDX](https://cyclonedx.org/) Software Bill of Materials in JSON format alongside the audit report. Output to `sbom.json` in the project root.
+
+Required for US federal contracts (EO 14028), increasingly required in enterprise vendor questionnaires.
+
+---
+
+## Compliance report (`--format report` / `--report`)
+
+Generates a markdown report suitable for attaching to a SOC 2 audit, ISO 27001 evidence package, or vendor security questionnaire. Includes:
+
+- Findings summary table (severity, location, status)
+- Fix evidence (exploit test name, patch commit, suite result)
+- Coverage gate result
+- Hardening controls applied
+- SBOM reference (if generated)
+- Timestamp and auditor (org/project from config)
+
+---
+
+## Org scan (`--org`)
+
+```bash
+npx @lhi/tdd-audit@latest --org my-github-org --format report
+```
+
+Discovers all repos in a GitHub org, runs `--pr` mode on each, and produces a cross-org summary:
+
+```
+my-github-org security posture — 2026-03-26
+
+✅ repo-a     0 critical · 0 high
+⚠️  repo-b     0 critical · 2 high
+🔴 repo-c     1 critical · 4 high
+
+3 repos scanned · 1 critical · 6 high total
+```
+
+Fires `webhook_url` and `slack_webhook` with the aggregate payload if configured.
+
+---
+
+## Secret rotation (`--rotate-secrets`)
+
+When a hardcoded API key is detected, prompts to rotate it via the provider's API. Supported providers:
+
+| Secret type | Rotation method |
+|---|---|
+| OpenAI key (`sk-...`) | OpenAI API — revoke + generate new key |
+| Anthropic key (`sk-ant-...`) | Anthropic console link + clipboard |
+| GitHub token | GitHub API — revoke token |
+| Supabase service key | Supabase API — regenerate |
+
+After rotation, updates the relevant `.env` file and removes the hardcoded value from source. The old key is invalidated whether you commit the change or not.

package/lib/auditor.js

@@ -16,6 +16,7 @@ function loadSkillSuite(packageDir) {
     ['hardening-phase.md',          path.join(packageDir, 'prompts', 'hardening-phase.md')],
     ['ai-security.md',              path.join(packageDir, 'prompts', 'ai-security.md')],
     ['node-advanced-security.md',   path.join(packageDir, 'prompts', 'node-advanced-security.md')],
+    ['security-test-patterns.md',   path.join(packageDir, 'prompts', 'security-test-patterns.md')],
   ];
   const suite = {};
   for (const [name, filePath] of entries) {