torusguard 2.0.0-alpha → 2.1.0

package/skills/torusguard-init/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: torusguard-init
 description: Initialize TorusGuard workspace — detect project stack, activate tailored TG-* security rules, and generate SECURITY.md baseline via CLI or AI Agent.
-version: 1.3.6
+version: 2.0.0
 workflow: .torusguard/workflows/init.md
 tools: Read, Grep, Glob, Write, run_command
 scripts-binding:
+  - internal/scanner/scanner.go
   - .torusguard/scripts/report_sync.py
   - .torusguard/scripts/stack_detect.py
-  - .torusguard/scripts/term_ui.py
 ---
 
 # TorusGuard Init — Project Stack Discovery & Rule Activation
@@ -17,26 +17,37 @@ Auto-detect repository technology stack across 16+ languages and frameworks, pro
 
 ---
 
-## Two Execution Modes
+## Tri-Mode Parity
+
+| Mode | Command / Tool | Governed Behavior |
+| :--- | :--- | :--- |
+| **Mode A: CLI Terminal** | `torusguard init` | Profiles workspace, provisions directories, activates tailored rules. |
+| **Mode B: AI Chat Slash** | `/torusguard init` | Inspects workspace dependencies and guides baseline rule activation. |
+| **Mode C: Native MCP Tool**| — | Workspace initialization is an administrative setup command. |
+
+---
+
+## Tri-Mode Execution
 
 ### Mode A: Automated CLI Execution
 Run the workspace initializer from your terminal:
 ```bash
 # Initialize current repository
-npx torusguard init
+torusguard init
 
 # Initialize specific directory
-npx torusguard init ./my-app
+torusguard init ./my-app
 
 # Force re-initialization (overwriting existing configuration)
-npx torusguard init --force
+torusguard init --force
 
-# Explicitly specify stack (e.g. react, nextjs, django, fastapi, express)
-npx torusguard init --stack express
+# Explicitly specify stack (e.g. react, nextjs, django, fastapi, express, go)
+torusguard init --stack express
 ```
+
 **Under the Hood:**
-- Runs `stack_detect.py` to inspect package files (`package.json`, `pyproject.toml`, `requirements.txt`, `go.mod`, `Cargo.toml`, `Gemfile`, `composer.json`, `*.csproj`).
-- Detects backend frameworks, frontend libraries, ORMs (Prisma, Mongoose, SQLAlchemy, Django ORM), and authentication systems.
+- Inspects package files (`package.json`, `pyproject.toml`, `requirements.txt`, `go.mod`, `Cargo.toml`, `Gemfile`, `composer.json`, `*.csproj`).
+- Detects backend frameworks, frontend libraries, ORMs (Prisma, Mongoose, SQLAlchemy, Django ORM, GORM), and authentication systems.
 - Scaffolds `.torusguard/` directory tree: `config/`, `rules/active/`, `runs/`, `scripts/`, `workflows/`, `templates/`, `schemas/`, `memory/`, `snapshots/`.
 - Copies tailored rule definitions into `.torusguard/rules/active/`.
 - Provisions `SECURITY.md` with standard responsible disclosure contacts.
@@ -45,12 +56,17 @@ npx torusguard init --stack express
 
 ### Mode B: In-Session AI Chat Agent Initialization
 When initializing a workspace directly in AI chat:
-1. **Detect Stack:** Inspect root files (`package.json`, `requirements.txt`, etc.) to determine languages and frameworks.
-2. **Bootstrap Structure:** Ensure `.torusguard/` structure exists. If missing, run `python skills/torusguard/bootstrap.py --target .`.
+1. **Detect Stack:** Inspect root files (`package.json`, `go.mod`, `requirements.txt`, etc.) to determine languages and frameworks.
+2. **Bootstrap Structure:** Ensure `.torusguard/` structure exists.
 3. **Activate Rules:** Populate `.torusguard/rules/active/` with applicable rule files from `rules/`.
 4. **Provision Policy:** Create `SECURITY.md` if not already present.
 5. **Write Configuration:** Persist settings into `.torusguard/config/torusguard.json`.
-6. **Prompt Audit:** Advise the user to run `npx torusguard audit` or `/torusguard audit`.
+6. **Prompt Audit:** Advise the user to run `torusguard audit` or `/torusguard audit`.
+
+### Mode C: Native MCP Tool Integration
+For autonomous AI coding agents (Antigravity, Cursor, Windsurf, Claude Code):
+- **Administrative Provisioning:** Agents prompt or invoke `torusguard init` to scaffold workspace boundaries.
+- **Posture Verification:** Once initialized, agents query `torusguard_status` via MCP to inspect active rules and verify initialization state.
 
 ---
 
@@ -61,8 +77,39 @@ When initializing a workspace directly in AI chat:
 - **Active Rules:** 74 canonical security rules enabled in `.torusguard/rules/active/`
 - **Configuration:** Written to `.torusguard/config/torusguard.json`
 - **Security Policy:** Baseline `SECURITY.md` generated
-- **Next Step:** Run `npx torusguard audit` or `/torusguard audit` to scan for flaws
+- **Next Step:** Run `torusguard audit` or `/torusguard audit` to scan for flaws
 ```
 
 ## Living Report Ground Truth
 - Read `security_report.md` in the workspace root before taking any action. Update the relevant finding card after completing remediation.
+
+---
+
+## 🚨 LLM Trap Table
+
+| Pattern | What AI Does Wrong | What Is Actually Correct |
+| :--- | :--- | :--- |
+| **Destructive Overwrite** | Overwrites user-customized `.torusguard/rules/active/` without checking `--force`. | Preserve existing customized rules unless `--force` is explicitly provided. |
+| **Generic Stack Guess** | Guesses Node.js without reading `go.mod`, `pyproject.toml`, or `Cargo.toml` in the repository. | Check actual package manifests to detect real multi-language frameworks. |
+| **Root Directory Clutter** | Spills temporary configuration files across root instead of isolating inside `.torusguard/config/`. | Confine all configuration, snapshots, and run artifacts strictly within `.torusguard/`. |
+| **Missing SECURITY.md** | Fails to verify whether responsible disclosure policy already exists before creating a new one. | Check for existing `SECURITY.md` at workspace root; avoid clobbering existing policies. |
+
+---
+
+## ✅ Pre-Flight Self-Audit
+
+Before initializing a workspace:
+- [ ] Did I inspect root manifests (`go.mod`, `package.json`, etc.) to identify the true technology stack?
+- [ ] Did I verify whether `.torusguard/` is already initialized?
+- [ ] Did I check if `SECURITY.md` already exists before writing?
+- [ ] Are all directories properly scoped to `.torusguard/`?
+
+---
+
+## 🔁 VBC Protocol (Verify → Build → Confirm)
+
+```
+VERIFY:  Check workspace root for manifest files and existing .torusguard configuration.
+BUILD:   Generate directory tree, configure tailored TG-* rules, and draft SECURITY.md.
+CONFIRM: Verify .torusguard/config/torusguard.json is valid JSON and notify user of readiness.
+```

package/skills/torusguard-ocr-scan/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: torusguard-ocr-scan
+description: Scans images, architecture diagrams, and screenshots via Tesseract OCR for leaked API keys, tokens, and credentials via CLI or AI Agent.
+version: 2.0.0
+workflow: .torusguard/workflows/ocr-scan.md
+tools: Read, Grep, Glob, Write, run_command
+scripts-binding:
+  - internal/scanner/ocr.go
+  - cmd/torusguard/main.go
+---
+
+# TorusGuard OCR Vision Scan — Multi-Modal Secret Extraction
+
+## Objective
+Detect optical leaks of private API keys, AWS credentials, database URIs, GitHub personal access tokens, and private certificates embedded inside visual artifacts (PNG, JPG, WebP, BMP, TIFF) up to 10MB using Tesseract OCR and deterministic regex signatures.
+
+---
+
+## Tri-Mode Execution
+
+### Mode A: Automated CLI Execution
+Run OCR scanning against a single diagram file or an entire directory of visual assets:
+```bash
+# Scan a specific architecture diagram or screenshot
+torusguard ocr-scan docs/architecture/diagram.png
+
+# Scan an entire directory of media assets
+torusguard ocr-scan ./assets/images/
+```
+
+### Mode B: In-Session AI Chat Slash Command
+Run `/torusguard ocr-scan <path>` in chat.
+The agent invokes the native Go scanner or MCP tool to extract optical text, analyze credential patterns, and report leaked keys.
+
+### Mode C: Native MCP Tool Call
+MCP-enabled coding agents (Antigravity, Cursor, Windsurf, Claude Code) call:
+```json
+{
+  "tool": "torusguard_ocr_scan",
+  "arguments": {
+    "target": "docs/architecture/cloud-architecture.png",
+    "max_image_mb": 10
+  }
+}
+```
+
+---
+
+## Supported Patterns & Invariants
+- **TG-SEC-001:** Hardcoded API Keys / Tokens / OpenAI & Stripe Keys (`sk-live-...`, `sk-...`).
+- **TG-SEC-002:** AWS Access Key IDs (`AKIA[0-9A-Z]{16}`).
+- **TG-SEC-003:** GitHub Personal Access Tokens (`ghp_...`, `github_pat_...`).
+- **TG-SEC-004:** Database Connection URIs (`postgres://user:pass@host:5432/db`).
+- **TG-SEC-005:** Private Key Headers (`-----BEGIN RSA PRIVATE KEY-----`).
+- **TG-SEC-007:** Password assignments (`password = "..."`).
+- **10MB DoS Guard:** Files exceeding 10MB are rejected fail-closed to prevent resource exhaustion attacks.
+
+---
+
+## 🏛️ OpenCodeReview Hybrid Architecture Integration
+- **Deterministic OCR Preprocessing:** Optical extraction and regex pattern matching run entirely in compiled Go code without LLM hallucination.
+- **Token Efficiency:** Only the extracted text and detected secret matches are emitted to the agent context (zero token waste on binary image blobs).
+
+---
+
+## 🚨 LLM Trap Table
+
+| Pattern | What AI Does Wrong | What Is Actually Correct |
+| :--- | :--- | :--- |
+| **Reading Binary Images as Text** | Attempts to read raw `.png` or `.jpg` with `view_file` as utf-8 text. | Invoke `torusguard ocr-scan` or `torusguard_ocr_scan` to perform OCR. |
+| **Ignoring Image File Size Bounds** | Tries to OCR multi-hundred megabyte video files or giant raw images. | Adhere to the 10MB DoS boundary (`DefaultMaxImageSize`). |
+| **Echoing Full Leaked Secrets in Logs** | Prints live production credentials unredacted in terminal output or reports. | Partially redact sensitive tokens (e.g. `sk-live-****3211`). |
+| **Assuming Images Don't Contain Secrets** | Audits only `.go` or `.js` code and ignores cloud diagrams or screenshots. | Always run OCR vision scan across image directories during full audits. |
+
+---
+
+## ✅ Pre-Flight Self-Audit
+
+Before concluding an OCR inspection, verify:
+- [ ] Is Tesseract installed and discoverable on PATH?
+- [ ] Are all target files valid image formats (`.png`, `.jpg`, `.jpeg`, `.webp`, `.bmp`, `.tiff`)?
+- [ ] Are target image file sizes strictly $\le 10$ MB?
+- [ ] Did I check against all 7 canonical secret signatures (`TG-SEC-001` through `TG-SEC-007`)?
+- [ ] Are confirmed leaks documented in `security_report.md` with remediation steps?
+
+---
+
+## 🔁 VBC Protocol (Verify → Build → Confirm)
+
+```
+VERIFY: Confirm target image existence and size <= 10MB.
+BUILD:  Execute torusguard ocr-scan or torusguard_ocr_scan to extract optical text.
+CONFIRM: Match text against OCRSecretPattern signatures, redact sensitive tokens, and record in security_report.md.
+```

package/skills/torusguard-recheck/SKILL.md

@@ -1,15 +1,13 @@
 ---
 name: torusguard-recheck
 description: Execute targeted differential AST re-scan against modified files, verify fix closure, and assert zero regressions via CLI or AI Agent.
-version: 1.3.6
+version: 2.0.0
 workflow: .torusguard/workflows/recheck.md
 tools: Read, Grep, Glob, Write, run_command
 scripts-binding:
+  - internal/scanner/scanner.go
+  - internal/harden/patch.go
   - .torusguard/scripts/report_sync.py
-  - .torusguard/scripts/recheck_runner.py
-  - .torusguard/scripts/audit_runner.py
-  - .torusguard/scripts/memory_engine.py
-  - .torusguard/scripts/term_ui.py
 ---
 
 # TorusGuard Recheck — Targeted Differential Audit & Fix Closure
@@ -19,26 +17,37 @@ Execute differential security re-scans strictly scoped to modified files and adj
 
 ---
 
-## Two Execution Modes
+## Tri-Mode Parity
+
+| Mode | Command / Tool | Governed Behavior |
+| :--- | :--- | :--- |
+| **Mode A: CLI Terminal** | `torusguard recheck` | Scans modified files, verifies fix closure, and updates run artifacts. |
+| **Mode B: AI Chat Slash** | `/torusguard recheck` | Guides interactive differential review and records fix events. |
+| **Mode C: Native MCP Tool**| `torusguard_recheck` | Machine-to-machine differential AST re-scan for AI coding agents. |
+
+---
+
+## Tri-Mode Execution
 
 ### Mode A: Automated CLI Execution
 Run the differential recheck engine from the terminal:
 ```bash
 # Recheck the latest applied run
-npx torusguard recheck
+torusguard recheck
 
 # Recheck a specific project directory
-npx torusguard recheck ./my-project
+torusguard recheck ./my-project
 
 # Recheck a specific run ID
-npx torusguard recheck --run run-20260910-121618-audit
+torusguard recheck --run run-20260910-121618-audit
 
 # Machine-readable JSON output
-npx torusguard recheck --json
+torusguard recheck --json
 ```
-**Under the Hood:** Executes `python .torusguard/scripts/recheck_runner.py`.
+
+**Under the Hood:**
 - Evaluates applied candidate bundles from `.torusguard/runs/<run_id>/bundles/`.
-- Executes single-file targeted differential AST scans via `audit_runner.scan_file()`.
+- Executes single-file targeted differential AST scans via `internal/scanner` and `internal/recheck`.
 - Calculates formal status transitions:
   - `✔ [Confirmed Fixed]`: Vulnerable pattern absent, zero regressions.
   - `✖ [Regressed]`: New security finding introduced by patch.
@@ -50,10 +59,22 @@ npx torusguard recheck --json
 ### Mode B: In-Session AI Chat Agent Differential Scan
 When evaluating patches directly in AI chat:
 1. **Identify Modified Files:** Read `diff_summary.md` or git status for files modified in the active run.
-2. **Re-Scan Sinks:** View the target file and verify that the specific rule violation (e.g. `TG-INPUT-003`, `TG-PLATFORM-001`) is no longer triggered.
-3. **Assert Zero Regressions:** Verify that no new vulnerabilities (like raw concatenation or unvalidated input) were introduced by the fix.
-4. **Update Status:** Log outcome in `.torusguard/runs/<run_id>/recheck.md`.
-5. **Memory Telemetry:** Record verification event with `memory_engine.record_event("fix_verified", ...)`.
+2. **Re-Scan Sinks:** View the target file and verify that the specific rule violation (e.g. `TG-INPUT-003`, `TG-PLATFORM-001`, `TG-NPE-001`) is no longer triggered.
+3. **Assert Zero Regressions:** Verify that no new vulnerabilities (like raw concatenation, missing null checks, or unvalidated inputs) were introduced by the fix.
+4. **Update Status:** Log outcome in `.torusguard/runs/<run_id>/recheck.md` and transition status in `security_report.md`.
+5. **Memory Telemetry:** Record verification event in persistent memory.
+
+### Mode C: Native MCP Tool Execution
+For autonomous AI coding agents (Antigravity, Cursor, Windsurf, Claude Code):
+- **Tool Invocation:** Call `torusguard_recheck` with target workspace:
+  ```json
+  {
+    "target": "."
+  }
+  ```
+- **Programmatic Return:** Receives differential AST re-scan results, baseline comparison, and confirms zero regressions.
+
+---
 
 ---
 
@@ -62,7 +83,7 @@ When evaluating patches directly in AI chat:
 | :--- | :--- | :--- | :--- |
 | **Confirmed Fixed** | `✔ [Confirmed Fixed]` | Sink eliminated, zero regressions | Proceed to Posture Report |
 | **Unresolved** | `⚠ [Unresolved]` | Flaw still present in file | Re-harden with alternative pattern |
-| **Regressed** | `✖ [Regressed]` | New security flaw introduced | Instant `npx torusguard rollback` |
+| **Regressed** | `✖ [Regressed]` | New security flaw introduced | Instant `torusguard rollback` |
 
 ---
 
@@ -74,8 +95,40 @@ When evaluating patches directly in AI chat:
 - **Regressions:** 0 detected
 - **Unresolved:** 0
 - **Artifact:** `.torusguard/runs/<run_id>/recheck.md`
-- **Next Step:** Run `npx torusguard report --html` for visual dashboard
+- **Next Step:** Run `torusguard report --html` for visual dashboard
 ```
 
 ## Living Report Ground Truth
 - Read `security_report.md` in the workspace root before taking any action. Update the relevant finding card after completing remediation.
+
+---
+
+## 🚨 LLM Trap Table
+
+| Pattern | What AI Does Wrong | What Is Actually Correct |
+| :--- | :--- | :--- |
+| **Premature Closure** | Marks finding "Fixed" merely because code was written, without differential AST re-scan. | Must execute `torusguard recheck` or differential scan to verify the AST sink is genuinely absent. |
+| **Line-Shift Drift** | Relies on original finding line numbers after patches shifted line offsets. | Use semantic snippet matching or recalculate line numbers from fresh AST scan. |
+| **Regression Blindness** | Checks only the original sink and ignores new flaws introduced in surrounding lines (e.g., introducing an unhandled null pointer or SQL concatenation). | Scan entire changed block and adjacent context ($\pm 3$ lines) for zero newly introduced `TG-*` violations. |
+| **Bypass Disguise** | Accepts `# nosec`, `// eslint-disable`, or `InsecureSkipVerify` as a valid "fix". | Strictly flag security bypasses as `✖ [Regressed]` under rule `TG-DIFF-001`. |
+
+---
+
+## ✅ Pre-Flight Self-Audit
+
+Before declaring any finding resolved:
+- [ ] Did I read the modified file from disk after applying the patch?
+- [ ] Did I verify the exact AST sink is absent and unreachable?
+- [ ] Did I verify no new vulnerabilities were introduced in surrounding code ($\pm 3$ lines)?
+- [ ] Did I verify zero security suppression comments or bypasses (`# nosec`, `verify=False`, etc.) exist?
+- [ ] Is the finding status updated in `security_report.md`?
+
+---
+
+## 🔁 VBC Protocol (Verify → Build → Confirm)
+
+```
+VERIFY:  Inspect disk content of modified files to confirm patch application.
+BUILD:   Execute differential re-scan against modified files using scanner rules.
+CONFIRM: Assert finding transition to Confirmed Fixed and verify zero regressions.
+```

package/skills/torusguard-redos/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: torusguard-redos
+description: Analyzes regular expressions across JavaScript, TypeScript, Python, and Go for catastrophic exponential backtracking and ReDoS vulnerabilities via CLI, Chat, or MCP.
+version: 2.0.0
+workflow: .torusguard/workflows/redos.md
+tools: Read, Grep, Glob, Write, run_command
+scripts-binding:
+  - internal/scanner/redos.go
+  - cmd/torusguard/main.go
+  - cmd/torusguard/mcp.go
+---
+
+# TorusGuard ReDoS Complexity Scanner
+
+## Objective
+Detect and remediate catastrophic exponential ($O(2^n)$) and polynomial ($O(n^k)$) backtracking regular expressions in web applications. Prevents thread starvation, CPU exhaustion, and availability denial of service attacks caused by untrusted user input matching evil regex patterns.
+
+---
+
+## Tri-Mode Execution
+
+### Mode A: Automated CLI Execution
+Run ReDoS scanning against source code files:
+```bash
+# Scan current workspace for catastrophic regex backtracking
+torusguard redos
+
+# Scan specific directory or source tree
+torusguard redos --target ./src
+```
+
+### Mode B: In-Session AI Chat Slash Command
+Run `/torusguard redos` in chat.
+The agent executes the compiled Go ReDoS analyzer or MCP tool to locate dangerous nested quantifiers, overlapping alternations, and unanchored expressions.
+
+### Mode C: Native MCP Tool Call
+MCP-enabled coding agents (Antigravity, Cursor, Windsurf, Claude Code) call:
+```json
+{
+  "tool": "torusguard_redos",
+  "arguments": {
+    "target": "."
+  }
+}
+```
+
+---
+
+## Supported Patterns & Invariants
+- **TG-REDOS-001 (Nested Quantifier Catastrophic Backtracking):** Detects nested repetitions such as `(a+)+`, `([a-zA-Z0-9]+)*`, or `((foo)*)+` that cause exponential evaluation time $O(2^n)$ when matching non-matching suffixes (e.g. `aaaaaaaaaaaaaaaa!`).
+- **TG-REDOS-002 (Overlapping Alternation with Outer Repetition):** Detects patterns like `(a|ab)+` or `(user|username)*` where multiple branches match identical prefixes, causing exponential branch exploration.
+
+---
+
+## 🏛️ OpenCodeReview Hybrid Architecture Integration
+- **First-Principles NFA/DFA Complexity Analysis:** Scans regex literals and constructor invocations across JS, TS, Python, and Go.
+- **Engine-Aware Triage:** Flags backtracking engines (V8, Node.js, Python `re`, PCRE) as high risk while noting linear-time DFA engines (Go `regexp`/RE2, Rust `regex`).
+- **Surgical Patching:** Replaces evil regexes with bounded, non-overlapping expressions or length pre-checks (≤35 additions, ≤25 deletions).
+
+---
+
+## 🚨 LLM Trap Table
+
+| Pattern | What AI Does Wrong | What Is Actually Correct |
+| :--- | :--- | :--- |
+| **Nested Quantifiers** | Writes `([a-zA-Z0-9_]+)*` or `(https?://.+)*`, causing $O(2^n)$ catastrophic backtracking on malicious input. | Flatten expressions: `[a-zA-Z0-9_]*` or use non-overlapping delimiters like `[^/\s]+`. |
+| **Overlapping Alternation** | Combines overlapping options inside repetition: `(a\|aa)+` or `(\w+\|\d+)+`. | Disjoint branch design: ensure alternatives cannot consume the same character prefix. |
+| **Missing Input Length Guards** | Evaluates complex regexes against arbitrarily long input strings from untrusted HTTP bodies. | Impose input bounds (`if (input.length > 256) return false`) before regex evaluation. |
+| **Unanchored Wildcards** | Writes `.*foo.*` without anchors, leading to quadratic scan across long documents. | Anchor patterns with `^` and `$` whenever full string matching is intended. |
+| **Engine Indifference** | Assumes all regex engines backtrack identically; doesn't know Go RE2 is linear $O(n)$ while Node V8 is vulnerable. | Tailor remediation to target runtime: use atomic groups/lookahead in V8/Python or switch to parser combinators. |
+
+---
+
+## ✅ Pre-Flight Self-Audit
+
+Before concluding a ReDoS complexity audit, verify:
+- [ ] Were all regex literals and `RegExp` / `re.compile` declarations inspected?
+- [ ] Are any nested quantifiers (`(x+)+`, `(x*)*`) present in the codebase?
+- [ ] Are alternatives in grouped alternations strictly mutually exclusive?
+- [ ] Is untrusted input strictly bounded in length before regex execution?
+- [ ] Are remediations validated within Ponytail diff bounds?
+
+---
+
+## 🔁 VBC Protocol (Verify → Build → Confirm)
+
+```
+VERIFY: Identify regex patterns evaluated on untrusted user inputs.
+BUILD:  Execute torusguard redos or torusguard_redos to detect exponential backtracking structures.
+CONFIRM: Refactor pattern into deterministic, non-overlapping tokens, adding length guards and testing with evil payloads.
+```

package/skills/torusguard-report/SKILL.md

@@ -5,11 +5,11 @@ version: 2.2.0
 workflow: .torusguard/workflows/report.md
 tools: Read, Grep, Glob, Write, run_command
 scripts-binding:
+  - internal/scanner/scanner.go
   - .torusguard/scripts/report_sync.py
   - .torusguard/scripts/html_reporter.py
   - .torusguard/scripts/sarif_exporter.py
   - .torusguard/scripts/run_manager.py
-  - .torusguard/scripts/term_ui.py
 ---
 
 # TorusGuard Report — Posture Reporting & SARIF / HTML Export
@@ -19,30 +19,40 @@ Aggregate findings, verification traces, and recheck results into an auditable e
 
 ---
 
+## Tri-Mode Parity
+
+| Mode | Command / Tool | Governed Behavior |
+| :--- | :--- | :--- |
+| **Mode A: CLI Terminal** | `torusguard report --html` | Compiles single-file HTML dashboard and OASIS SARIF v2.1.0 log. |
+| **Mode B: AI Chat Slash** | `/torusguard report` | Generates executive posture summary and checks CI/CD readiness. |
+| **Mode C: Native MCP Tool**| `torusguard://security_report` | Serves resource payload and posture metrics directly to agent context. |
+
+---
+
 ## Execution Steps
 
 ### Mode A: Automated CLI Execution
 Run the report engine from your terminal:
 ```bash
 # Generate visual dark-mode HTML dashboard (defaults to report.html at project root)
-npx torusguard report --html
+torusguard report --html
 
 # Export OASIS SARIF v2.1.0 for GitHub Code Scanning / CI
-npx torusguard report --sarif
+torusguard report --sarif
 
 # Generate both HTML and SARIF in a single pass
-npx torusguard report --html --sarif
+torusguard report --html --sarif
 
 # Custom HTML output location
-npx torusguard report --html --out ./docs/security-audit.html
+torusguard report --html --out ./docs/security-audit.html
 
 # Target a specific subproject / monorepo package
-npx torusguard report --target ./apps/api --html
+torusguard report --target ./apps/api --html
 ```
 
 **Under the Hood:**
-- Invokes `python .torusguard/scripts/html_reporter.py` to compile self-contained, offline-ready HTML reports with dynamic filtering, posture gauge, directory attack surface heatmap, and golden recipe explorer at `report.html` (workspace root) and mirrors to `.torusguard/runs/report-latest.html`.
-- Invokes `python .torusguard/scripts/sarif_exporter.py` to produce OASIS SARIF v2.1.0 logs at `.torusguard/runs/results-latest.sarif`.
+- Compiles self-contained, offline-ready HTML reports with dynamic filtering, posture gauge, directory attack surface heatmap, and golden recipe explorer at `report.html` (workspace root) and mirrors to `.torusguard/runs/report-latest.html`.
+- Produces OASIS SARIF v2.1.0 logs at `.torusguard/runs/results-latest.sarif`.
 - Finalizes `manifest.json` metrics and updates historical posture scoring.
 - Displays standardized 75-column terminal cards adhering to visual width invariants.
 
@@ -65,7 +75,7 @@ When generating security posture summaries in AI chat:
 
 ## SARIF v2.1.0 Output Specification
 - **Schema:** `https://docs.oasis-open.org/sarif/sarif/v2.1.0/cos02/schemas/sarif-schema-2.1.0.json`
-- **Tool Driver:** `name: TorusGuard`, `semanticVersion: 1.3.6`, full rules catalog in `driver.rules`.
+- **Tool Driver:** `name: TorusGuard`, `semanticVersion: 2.0.0`, full rules catalog in `driver.rules`.
 - **Automation Details:** `automationDetails.id: "torusguard/static"` to avoid collisions in multi-scanner CI/CD pipelines.
 - **Fingerprints:** `partialFingerprints.primaryLocationLineHash` with SHA-256 context hash.
 
@@ -91,3 +101,34 @@ When generating security posture summaries in AI chat:
 
 ## Living Report Ground Truth
 - Read `security_report.md` in the workspace root before taking any action. Update the relevant finding card after completing remediation.
+
+---
+
+## 🚨 LLM Trap Table
+
+| Pattern | What AI Does Wrong | What Is Actually Correct |
+| :--- | :--- | :--- |
+| **Credential Leakage in HTML** | Embeds raw plaintext passwords, JWTs, or API secrets into HTML report DOM or SARIF output. | Redact all secret values (`[REDACTED]`) before serializing findings to HTML or SARIF. |
+| **External CDN Dependency** | Inserts CDN links (`https://cdn.jsdelivr.net/...`, Google Fonts) breaking offline and air-gapped environments. | Embed 100% of styles, SVGs, and interactive logic inline inside single-file `report.html`. |
+| **SARIF Schema Invalidation** | Emits invalid JSON or omits required fields (`runs[0].tool.driver.rules`), breaking GitHub Code Scanning ingestion. | Validate SARIF output against OASIS v2.1.0 specification with valid rule IDs and URI locations. |
+| **Out-of-Sync Ledger** | Emits HTML report with different counts or statuses than `security_report.md`. | Synchronize metrics so `report.html`, `security_report.md`, and SARIF reflect the identical ground truth. |
+
+---
+
+## ✅ Pre-Flight Self-Audit
+
+Before generating reports:
+- [ ] Are all secrets, tokens, and authorization credentials redacted?
+- [ ] Is `report.html` 100% self-contained with zero external CDN tags?
+- [ ] Does the SARIF export conform strictly to OASIS SARIF v2.1.0?
+- [ ] Does the reported posture score match findings in `security_report.md`?
+
+---
+
+## 🔁 VBC Protocol (Verify → Build → Confirm)
+
+```
+VERIFY:  Collect finding counts, verification states, and recheck results from active run.
+BUILD:   Compile self-contained visual HTML dashboard and serialize SARIF v2.1.0 log.
+CONFIRM: Check file size and validity on disk; verify zero unredacted secrets exist.
+```