torusguard 2.0.0-alpha → 2.1.1

package/README.md

@@ -11,8 +11,8 @@
 
 <p align="center">
   <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
-  <a href="https://github.com/githubmofo/TorusGuard/releases"><img src="https://img.shields.io/badge/version-2.0.0--alpha-orange.svg" alt="Version"></a>
-  <a href="https://www.npmjs.com/package/torusguard"><img src="https://img.shields.io/badge/npm-v2.0.0--alpha-CB3837?logo=npm&logoColor=white" alt="npm: v2.0.0-alpha"></a>
+  <a href="https://github.com/githubmofo/TorusGuard/releases"><img src="https://img.shields.io/badge/version-v2.1.1-orange.svg" alt="Version"></a>
+  <a href="https://www.npmjs.com/package/torusguard"><img src="https://img.shields.io/badge/npm-v2.1.1-CB3837?logo=npm&logoColor=white" alt="npm: v2.1.1"></a>
   <img src="https://img.shields.io/badge/Privacy-Local_First-success" alt="Privacy: Local First">
   <img src="https://img.shields.io/badge/Dependencies-Zero-brightgreen" alt="Dependencies: Zero">
   <img src="https://img.shields.io/badge/SARIF-v2.1.0-6C3483" alt="SARIF">
@@ -22,9 +22,10 @@
 <p align="center">
   <img src="https://img.shields.io/badge/Unit%20Tests-100%25%20Passing-brightgreen?logo=go&logoColor=white" alt="Unit Tests: 100% Passing">
   <img src="https://img.shields.io/badge/Polyglot%20Tests-36%2F36%20Repos%20Passed-brightgreen?logo=checkmarx&logoColor=white" alt="Polyglot Tests: 36/36 Repos Passed">
+  <a href="docs/validation/unseen-repos-tri-mode-validation-report.md"><img src="https://img.shields.io/badge/Tri--Mode%20Validation-6%2F6%20Unseen%20Stacks%20Passed-brightgreen?logo=checkmarx&logoColor=white" alt="Tri-Mode Validation: 6/6 Unseen Stacks Passed"></a>
   <img src="https://img.shields.io/badge/Tri--Mode%20E2E-16%2F16%20Verified-blue?logo=checkmarx&logoColor=white" alt="Tri-Mode E2E: 16/16 Verified">
   <img src="https://img.shields.io/badge/Vision%20OCR-Tested%20%26%20Verified-blueviolet?logo=tesseract&logoColor=white" alt="Vision OCR: Tested & Verified">
-  <img src="https://img.shields.io/badge/Rules%20Verified-74%2F74%20Rules-success" alt="Rules: 74/74 Verified">
+  <img src="https://img.shields.io/badge/Rules%20Verified-88%2F88%20Rules-success" alt="Rules: 88/88 Verified">
 </p>
 
 <p align="center">
@@ -42,13 +43,13 @@
 
 - [What Is TorusGuard?](#what-is-torusguard)
 - [Features](#-features)
-- [Autonomous Architecture](#-autonomous-architecture)
+- [Autonomous Architecture & Workflow](#-autonomous-architecture--workflow)
 - [Prerequisites](#-prerequisites)
 - [Installation](#-installation)
 - [Usage](#-usage)
 - [Commands](#-commands)
 - [Project Structure](#-project-structure)
-- [Security Rules (74 Rules, 18 Families)](#-security-rules-74-rules-18-families)
+- [Security Invariants & Rule Governance](#-security-invariants--rule-governance)
 - [AI Agent Integration](#-ai-agent-integration)
 - [Verified Test Suite & Benchmarks](#-verified-test-suite--mass-benchmarks)
 - [Non-Negotiable Invariants](#-non-negotiable-invariants)
@@ -60,10 +61,11 @@
 
 ## What Is TorusGuard?
 
-TorusGuard is a **zero-dependency, single-binary security engine** that scans, hardens, and validates AI-generated codebases. It enforces 74 security rules across 18 architectural families and works in two complementary modes:
+TorusGuard is a **zero-dependency, single-binary security engine** that scans, hardens, and validates AI-generated codebases. It enforces 88 security rules across 22 architectural families and works across three unified operational modes (**Tri-Mode Parity**):
 
-- **CLI Mode (Go Binary)** — A deterministic scanner and enforcer that runs in your terminal or CI/CD pipeline.
-- **AI Agent Mode** — Integrates natively with Antigravity, Cursor, Claude Code, Windsurf, VS Code, and other AI coding assistants via slash commands.
+- **Mode A: Terminal CLI (Go Binary)** — A deterministic scanner and enforcer that runs in your terminal or CI/CD pipeline (`torusguard <command>`).
+- **Mode B: AI Chat Slash Commands** — Integrates natively with Antigravity, Cursor, Claude Code, Windsurf, VS Code, and other AI coding assistants via slash commands (`/torusguard <command>`).
+- **Mode C: Native MCP Tools** — Stdio Model Context Protocol (JSON-RPC 2.0) interface exposing autonomous security tools and living resources directly to AI agents.
 
 TorusGuard ensures that the code your AI assistant writes is secure *before* it reaches production.
 
@@ -71,8 +73,14 @@ TorusGuard ensures that the code your AI assistant writes is secure *before* it
 
 ## ✨ Features
 
-- **74 Security Rules** across 18 families (Secrets, Auth, SQL Injection, SSRF, CSRF, GraphQL, Supply Chain, and more)
-- **Heuristic AST Scanner** — Polyglot static analysis for Go, JavaScript, TypeScript, and Python
+- **88 Security Rules** across 22 families (Secrets, Auth, SQL Injection, Deserialization, Open Redirects, SSRF, CSRF, GraphQL, Supply Chain, Containers, Git History, ReDoS, AI & RAG, and more)
+- **Taint Analysis & Interprocedural Dataflow Engine** — Cross-file, interprocedural taint flow tracking from untrusted sources to critical sinks across imports, modules, and call graphs
+- **7-Signal Calibrated Confidence Scorer** — Evidence-chain calibration combining rule severity, taint confirmation, taint depth, sanitizer absence, framework context, multi-line evidence, and persistent memory
+- **First-Principles Security Suite** — Built-in native scanners for Dockerfile/Compose privilege bounds, Git commit log secret mining, exponential regex backtracking, and cross-tenant vector isolation
+- **Polyglot Parser & AST Walker** — Tree-sitter powered AST traversal with unified CST nodes and symbol resolution across Go, JavaScript, TypeScript, and Python
+- **Incremental Hash Cache & Parallel Scanning** — SHA-256 mtime incremental scan caching, process-pool parallelization, and continuous file-watcher debounce
+- **Line-Level Reflection Module** — Semantic patch synthesis (`find_snippet` / `replace_snippet`) that accurately replaces exact code blocks without brittle line-number offsets
+- **1/9th Token Bounded Context Extraction** — AST context extraction (±3 lines) via `scanner.ExtractContext` to keep review prompts hyper-efficient and prevent context saturation
 - **Ponytail Protocol** — Surgical patch bounds (≤35 additions, ≤25 deletions) to prevent full-file rewrites
 - **Pre-Apply Snapshots** — Automatic `.bak` rollback snapshots before every code modification
 - **SARIF v2.1.0 Export** — Standards-compliant output for GitHub Advanced Security, VS Code, and other SARIF consumers
@@ -104,37 +112,64 @@ TorusGuard’s static scanner and enforcement binary have been rigorously tested
 
 ---
 
-## 🏗️ Autonomous Architecture
+## 🏗️ Autonomous Architecture & Workflow
 
 TorusGuard uses a **tri-track architecture** where intelligence, deterministic enforcement, and agent tool execution are cleanly separated across three unified operational modes:
 
 ```mermaid
 flowchart TD
-    User([Developer / CI / AI Coding Assistant])
-    
-    User --> ModeA[Mode A: Terminal CLI<br/><code>torusguard &lt;cmd&gt;</code><br/>Deterministic Go Binary]
-    User --> ModeB[Mode B: AI Chat Slash Command<br/><code>/torusguard &lt;cmd&gt;</code><br/>Chat Prompt & Workflow Bridge]
-    User --> ModeC[Mode C: Native MCP Protocol<br/><code>torusguard_audit / ocr_scan</code><br/>Stdio JSON-RPC 2.0 Agent Tools]
-    
-    ModeA --> Router[Command Router & Dispatcher<br/>cmd/torusguard]
-    ModeB --> Router
-    ModeC --> Router
-    
-    Router --> Engine
-    
-    subgraph Engine[TorusGuard Core Engine]
-        Scanner[Polyglot AST & Heuristic Scanner<br/>74 Rules across 18 Families]
-        OCR[Multi-Modal Vision OCR Engine<br/>Tesseract Optical Analysis &le;10MB]
-        Harden[Harden Engine<br/>Ponytail Protocol &le;35 add, &le;25 del]
-        Apply[Snapshot & Apply Engine<br/>Byte-for-byte Rollback Backups]
-        Validate[Runtime Web Validator<br/>SSRF Defense & Audit Probing]
-        Recheck[Differential Recheck Engine<br/>Fix Closure Verification]
+    subgraph Ingress["Unified Tri-Mode Ingress"]
+        ModeA["<b>Mode A: Terminal CLI</b><br/><code>torusguard &lt;cmd&gt;</code><br/>Deterministic Single Binary"]
+        ModeB["<b>Mode B: AI Chat Slash Commands</b><br/><code>/torusguard &lt;cmd&gt;</code><br/>Cursor &bull; Claude &bull; Windsurf &bull; Antigravity"]
+        ModeC["<b>Mode C: Native MCP Tools</b><br/><code>torusguard_*</code> (10 Tools &bull; 2 Resources)<br/>Stdio JSON-RPC 2.0 Agent Server"]
     end
-    
-    Engine --> Ledger[Living Security Ground Truth<br/><code>security_report.md</code>]
-    Engine --> Workspace[(.torusguard/ Workspace State<br/>rules/ &bull; schemas/ &bull; memory/ &bull; snapshots/)]
+
+    Ingress --> Router["<b>Command Router &amp; Dispatcher</b><br/>cmd/torusguard (21 Commands)"]
+
+    subgraph Core["TorusGuard Core Security Engine (Go Single Binary)"]
+        direction TB
+        subgraph Scanners["First-Principles &amp; Multi-Modal Scanner Suite"]
+            AST["<b>Polyglot AST &amp; Heuristic Scanner</b><br/>Go &bull; TS/JS &bull; Python &bull; SQL &bull; Auth &bull; SSRF &bull; CSRF"]
+            OCR["<b>Multi-Modal Vision OCR Engine</b><br/>Tesseract v5.4.0 &bull; Leaked Keys in PNG/JPG &le;10MB"]
+            Container["<b>Container &amp; Dockerfile Auditor</b><br/>Root Execution &bull; Docker Sockets &bull; Build Secrets"]
+            GitMine["<b>Git History Secret Miner</b><br/>Past Commits &bull; Diff Logs &bull; Remote Credentials"]
+            ReDoS["<b>ReDoS Complexity Analyzer</b><br/>Polynomial &amp; Exponential Backtracking Loops"]
+            AIGuard["<b>AI Agent &amp; RAG Vector Guard</b><br/>Prompt Injection &bull; Tenant Vector Contamination"]
+        end
+
+        subgraph Governance["Governance &amp; Remediation Pipeline"]
+            Harden["<b>Harden &amp; Line Reflection</b><br/>Ponytail Bounds: &le;35 Add &bull; &le;25 Del"]
+            Snapshot["<b>Pre-Apply Snapshot Engine</b><br/>Byte-for-Byte Rollback Backups in .torusguard/snapshots/"]
+            HumanGate{"<b>Human Gate Authorization</b><br/>Explicit --yes Confirmation Required"}
+            Recheck["<b>Differential Recheck Engine</b><br/>Zero-Regression Fix Closure"]
+        end
+    end
+
+    Router --> Scanners
+    Scanners --> Ledger[("<b>Living Security Ledger</b><br/><code>security_report.md</code><br/>Single Source of Truth")]
+    Ledger --> Harden
+    Harden --> Snapshot
+    Snapshot --> HumanGate
+    HumanGate -- Approved --> Recheck
+    Recheck --> Outputs["<b>Enterprise Outputs</b><br/>OASIS SARIF v2.1.0 &bull; Dark-Mode HTML Report &bull; Golden Fix Distillation"]
+
+    classDef ingressStyle fill:#1e293b,stroke:#38bdf8,stroke-width:2px,color:#f8fafc;
+    classDef scannerStyle fill:#0f172a,stroke:#818cf8,stroke-width:2px,color:#f8fafc;
+    classDef govStyle fill:#0f172a,stroke:#34d399,stroke-width:2px,color:#f8fafc;
+    classDef ledgerStyle fill:#312e81,stroke:#a78bfa,stroke-width:2px,color:#f8fafc;
+    classDef outStyle fill:#064e3b,stroke:#10b981,stroke-width:2px,color:#f8fafc;
+
+    class ModeA,ModeB,ModeC ingressStyle;
+    class AST,OCR,Container,GitMine,ReDoS,AIGuard scannerStyle;
+    class Harden,Snapshot,HumanGate,Recheck govStyle;
+    class Ledger ledgerStyle;
+    class Outputs outStyle;
 ```
 
+> 🌐 **Interactive Architecture Visualizations:**
+> - [**System Architecture Diagram** (HTML)](docs/architecture/torusguard-architecture.html) — Dynamic zoomable/pannable pipeline with dark/light themes, live view switching (Tri-Mode Ingress, AST Engine, Multi-Modal Vision OCR, Ponytail Bounds, Fail-Closed Recovery), and SVG/PNG export.
+> - [**Governed Remediation Workflow** (HTML)](docs/architecture/torusguard-governance.workflow.html) — Step-by-step visual trace of the 7-stage remediation loop, safety gates, and automatic rollback path.
+
 **Key design decisions:**
 - **Tri-Mode Parity:** The CLI (Mode A), Chat Slash Commands (Mode B), and Native MCP Tools (Mode C) share the exact same underlying governance and validation rules.
 - **Multi-Modal Vision OCR:** Images, architecture diagrams, and screenshots are automatically scanned for leaked secrets using Tesseract OCR, bounded by strict 10MB memory safety limits.
@@ -169,7 +204,7 @@ npx torusguard init
 ```
 
 <a href="https://www.npmjs.com/package/torusguard">
-  <img src="https://img.shields.io/badge/npm-v2.0.0--alpha-CB3837?logo=npm&logoColor=white" alt="npm package">
+  <img src="https://img.shields.io/badge/npm-v2.1.1-CB3837?logo=npm&logoColor=white" alt="npm package">
 </a>
 
 ### Option 2: Build from Source (Recommended for Contributors)
@@ -256,8 +291,14 @@ torusguard exploit-check
 | `recipes`        | Manage the Golden Fix recipe library                           |
 | `authorize`      | Generate cryptographic auth tokens for runtime probing         |
 | `web-validate`   | Authorized HTTP probing with `X-TorusGuard-Audit` headers      |
+| `exploit-check`  | Bounded single-step exploitability confirmation                |
 | `ocr-scan`       | Run Tesseract OCR secret scan on images/diagrams (<10MB)       |
+| `container`      | Audit Dockerfile, compose, and container configurations        |
+| `git-mine`       | Mine git commit history for leaked secrets & creds             |
+| `redos`          | Analyze regex patterns for catastrophic backtracking           |
+| `ai-guard`       | Scan AI/LLM code for prompt injection & RAG flaws              |
 | `mcp`            | Run native Model Context Protocol (MCP) server over stdio      |
+| `full`           | Master 7-stage closed-loop security governance pipeline        |
 | `update`         | Self-update the TorusGuard engine                              |
 | `help`           | Show interactive command guide                                 |
 
@@ -272,7 +313,9 @@ TorusGuard/
 │   └── mcp.go            # Model Context Protocol (MCP) JSON-RPC 2.0 stdio server
 ├── internal/
 │   ├── apply/            # Patch application + pre-apply snapshot engine
-│   ├── harden/           # Ponytail Protocol bounds enforcement
+│   ├── harden/           # Ponytail Protocol bounds enforcement & line-level reflection
+│   │   ├── patch.go      # Ponytail Protocol bounds verification
+│   │   └── reflection.go # Line-level reflection & semantic replacement
 │   ├── memory/           # Golden Fix recipe persistence
 │   ├── recheck/          # Differential re-scan engine
 │   ├── report/           # SARIF v2.1.0 + dark-mode HTML generators
@@ -296,28 +339,13 @@ TorusGuard/
 
 ---
 
-## 🔒 Security Rules (74 Rules, 18 Families)
-
-| Family         | Domain                           | Rules | Core Invariant                                           |
-| :------------- | :------------------------------- | :---: | :------------------------------------------------------- |
-| `TG-SEC`       | Core Secrets & API Tokens        |   7   | Zero hardcoded API keys or JWT secrets in source          |
-| `TG-AUTH`      | Authentication & Sessions        |   8   | Timing-safe compares, strong hashing, algorithm verify    |
-| `TG-DB`        | Database Isolation & Injection   |   4   | Parameterized queries and tenant partition scoping        |
-| `TG-INPUT`     | Input Sanitization & Traversal   |   6   | Strict path sanitization, safe DOM assignments            |
-| `TG-RATE`      | Rate Limiting & Resources        |   3   | Rate-limiting on auth endpoints, payload size bounds      |
-| `TG-AGENT`     | AI Agent & LLM Injection         |   4   | Structural prompt isolation, tool call schema validation  |
-| `TG-SSRF`      | Server-Side Request Forgery      |   4   | Hostname whitelisting, private IP range blocking          |
-| `TG-WEBHOOK`   | Inbound Webhook Verification     |   4   | HMAC-SHA256 signature verification, replay prevention     |
-| `TG-WS`        | WebSocket & Real-Time            |   4   | Origin verification, handshake auth, frame size limits    |
-| `TG-CSRF`      | Cross-Site Request Forgery       |   2   | SameSite cookies, anti-CSRF token verification            |
-| `TG-GQL`       | GraphQL Safety                   |   4   | Query depth limiting, introspection suppression           |
-| `TG-SUPPLY`    | Supply Chain & Dependencies      |   6   | Lockfile integrity, known CVE audits                      |
-| `TG-BIZ`       | Business Logic & Workflows       |   4   | Negative amount validation, transaction locks             |
-| `TG-CACHE`     | Cache Poisoning & Timing         |   3   | Cache-control headers, unkeyed header sanitization        |
-| `TG-CLIENT`    | Client Bundle & Frontend         |   2   | Zero private env vars in client bundles                   |
-| `TG-PLATFORM`  | Server Hardening & Headers       |   4   | Helmet headers, debug suppression, cookie secure flags    |
-| `TG-DIFF`      | Polyglot Bypass & Churn          |   3   | Block `# nosec`, `InsecureSkipVerify`, churn bounds       |
-| `TG-EDGE`      | Edge Computing & Serverless      |   2   | Subrequest fan-out limits, execution timeouts             |
+## 🔒 Security Invariants & Rule Governance
+
+TorusGuard enforces **88 security invariants across 22 architectural families** covering Secrets, Authentication, Multi-Tenant Database Isolation, Input Sanitization, Rate Limiting, AI Agent Prompt Injection, SSRF, Webhooks, WebSockets, CSRF, GraphQL, Supply Chain, Business Logic, Cache Poisoning, Client Bundles, Platform Headers, Polyglot Bypasses, Edge Timeouts, Container & Docker Safety, Git History Secret Mining, Regular Expression Backtracking (ReDoS), and Vector Database RAG Isolation.
+
+> 📘 **Full Rules Catalog & Invariants:**  
+> The complete rulebook with formal invariant definitions, severity scores, and testing signatures is maintained in [`AGENTS.md`](AGENTS.md) and the [`rules/`](rules/) directory.  
+> You can also explore verified Golden Fix patterns anytime via `torusguard recipes` or stream the live catalog over MCP via `torusguard://rules_catalog`.
 
 ---
 
@@ -356,10 +384,16 @@ When configured with `.agents/mcp_config.json` or `mcp_config.json`, AI coding a
 
 - `torusguard_audit`: Deep static AST scan + Vision OCR; writes `security_report.md`
 - `torusguard_ocr_scan`: Dedicated image credential analysis via Tesseract (5-10MB bounds)
+- `torusguard_container`: Audits container files for root execution, docker socket exposure, and privileged mode
+- `torusguard_git_mine`: Mines git commit history and config for leaked credentials and tokens
+- `torusguard_redos`: Analyzes regex patterns for catastrophic exponential backtracking
+- `torusguard_ai_guard`: Audits AI agent prompt templates, tool registries, and vector database queries
+- `torusguard_verify`: Asserts evidence sufficiency & line-shift invariant fingerprint matches
 - `torusguard_harden`: Validates remediation diff against Ponytail Protocol bounds
 - `torusguard_recheck`: Differential re-scan confirming fix closure
 - `torusguard_status`: Workspace posture and tech stack inspection
 - `torusguard://security_report`: MCP Resource reading the living security report
+- `torusguard://rules_catalog`: MCP Resource exploring verified rules catalog & Golden Fix patterns
 
 ---
 
@@ -369,11 +403,12 @@ TorusGuard undergoes rigorous automated multi-tier testing across polyglot stack
 
 | Testing Tier | Scope & Target Stacks | Pass Rate | Verified Capabilities |
 | :--- | :--- | :---: | :--- |
-| **Go Engine & Unit Tests** | `cmd/torusguard`, `internal/scanner`, `internal/*` | **100% Passing** | Deterministic AST matching, 74 rule patterns, JSON-RPC 2.0 MCP protocol. |
+| **Go Engine & Unit Tests** | `cmd/torusguard`, `internal/scanner`, `internal/*` | **100% Passing** | Deterministic AST matching, 88 canonical rule patterns, JSON-RPC 2.0 MCP protocol (133/133 harness tests passing). |
 | **Mass Polyglot Benchmarks** | **20 Enterprise Tech Stacks** (Go, Python, Java, Node, Rust, PHP, C#, Ruby, Svelte, Vue, Angular) | **20/20 Passed** | Framework auto-profiling, heuristic AST analysis, finding deduplication. |
+| **Unseen Tri-Mode Validation** | **6 Unseen Framework Ecosystems** (SvelteKit 2 + Bun, FastAPI AI RAG, DevOps Git Mine, OCR Asset Suite, Kotlin Ktor, Laravel 11) | **6/6 Passed (100%)** | Mode A (CLI) + Mode B (Slash Commands) + Mode C (Native MCP Tools) across 18/18 canonical skills with automated sandbox cleanup. |
 | **Tri-Mode & Vision E2E** | **16 Diverse Framework Repos** (React, Next.js, Express, Django, FastAPI, Spring Boot, etc.) | **16/16 Passed** | Mode A (CLI) + Mode B (Slash Commands) + Mode C (Native MCP Tools) + Multi-Modal Vision OCR. |
-| **Multi-Modal Vision OCR** | Diagram & Image assets (`.png`, `.jpg`, etc.) via Tesseract v5.4.0 | **100% Recall** | Secrets detection (`TG-SEC-001` - `TG-SEC-007`), 10MB DoS bounding, OCR character substitution tolerance. |
-| **Ponytail Churn Limits** | Surgical patch validation across all 74 rules | **Bounded** | Line bounds (≤35 additions, ≤25 deletions), zero-bypass verification (`TG-DIFF-001`). |
+| **Multi-Modal Vision OCR** | Diagram & Image assets (`.png`, `.jpg`, `.webp`) via Tesseract v5.4.0 | **100% Recall** | Secrets detection (`TG-SEC-001` - `TG-SEC-007`), 10MB DoS bounding, OCR character substitution tolerance. |
+| **Ponytail Churn Limits** | Surgical patch validation across all 88 rules | **Bounded** | Line bounds (≤35 additions, ≤25 deletions), zero-bypass verification (`TG-DIFF-001`). |
 
 All test environments are completely sandboxed, verified with byte-for-byte assertions, and cleaned up automatically.
 
@@ -422,5 +457,6 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines and [CODE_OF_COND
 | [Testing Playbook](docs/usage/testing-playbook.md)        | Testing guide and CI integration         |
 | [Demo Guide](docs/demo.md)                                | Quick start and full lifecycle demo      |
 | [Roadmap](docs/roadmap.md)                                | Feature roadmap and release planning     |
+| [Unseen Stacks Validation Report](docs/validation/unseen-repos-tri-mode-validation-report.md) | Tri-mode validation across 6 unseen ecosystems & vision OCR |
 | [SECURITY.md](SECURITY.md)                                | Vulnerability disclosure policy          |
 | [CHANGELOG.md](CHANGELOG.md)                              | Version history and release notes        |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "torusguard",
-  "version": "2.0.0-alpha",
+  "version": "2.1.1",
   "description": "Security guardrails, governed remediation, and authorized runtime validation for AI-built web applications.",
   "main": "bin/torusguard.js",
   "bin": {
@@ -22,7 +22,12 @@
     "harden": "node bin/torusguard.js harden",
     "apply": "node bin/torusguard.js apply",
     "recipes": "node bin/torusguard.js recipes",
-    "update": "node bin/torusguard.js update"
+    "update": "node bin/torusguard.js update",
+    "build": "echo \"No build step required\""
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.3",
+    "typescript": "^5.0.0"
   },
   "keywords": [
     "security",

package/skills/torusguard/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: torusguard
-description: Universal autonomous security engine: 74 canonical rules across 18 families, polyglot stack detection across 16+ languages, Ponytail remediation bounds (<=35 add, <=25 del), standardized 75-column terminal UI, living security_report.md ground-truth ledger, SARIF v2.1.0 exports, and persistent security memory context.
-version: 1.3.6
+description: Universal autonomous security engine: 88 canonical rules across 22 families, polyglot stack detection across 16+ languages, Ponytail remediation bounds (<=35 add, <=25 del), standardized 75-column terminal UI, SARIF v2.1.0 exports, and persistent security memory context.
+version: 2.1.1
 ---
 
 # TorusGuard Master Security Engine & Command Router
@@ -10,39 +10,54 @@ version: 1.3.6
 
 ---
 
-## Command Catalog: Terminal CLI & AI Chat Parity
+## Tri-Mode Execution & Command Catalog
 
-TorusGuard operates with 100% feature parity across both the terminal CLI and AI chat slash commands:
+TorusGuard operates with 100% feature parity across the compiled terminal CLI, AI chat slash commands, and Model Context Protocol (MCP) tools:
 
-| Capability | Terminal CLI Command | AI Chat Slash Command | Specialist Skill | Purpose |
+| Capability | Terminal CLI Command | AI Chat Slash Command | Specialist Skill | Governed Purpose |
 | :--- | :--- | :--- | :--- | :--- |
-| **Init** | `npx torusguard init` | `/torusguard init` | `skills/torusguard-init` | Stack discovery, rule activation, workspace scaffolding |
-| **Status** | `npx torusguard status` | `/torusguard status` | `skills/torusguard-status` | Posture score, active rules, run history, scope check |
-| **Audit** | `npx torusguard audit` | `/torusguard audit` | `skills/torusguard-audit` | Static AST scan, invariant fingerprinting, confidence scoring |
-| **Verify** | `npx torusguard verify` | `/torusguard verify` | `skills/torusguard-verify` | Evidence sufficiency audit & line match calibration |
-| **Harden** | `npx torusguard harden` | `/torusguard harden` | `skills/torusguard-harden` | Ponytail patch formulation ($\le 35$ add, $\le 25$ del) |
-| **Apply** | `npx torusguard apply [--yes]` | `/torusguard apply` | `skills/torusguard-apply` | Human Gate review, `.bak` snapshots, patch application |
-| **Rollback** | `npx torusguard rollback` | `/torusguard rollback` | `skills/torusguard-apply` | Instant 1-step rollback from pre-apply snapshots |
-| **Recheck** | `npx torusguard recheck` | `/torusguard recheck` | `skills/torusguard-recheck` | Targeted differential AST scan, fix closure verification |
-| **Recipes** | `npx torusguard recipes` | `/torusguard recipes` | `skills/torusguard-harden` | Explore verified Golden Fix Recipes from persistent memory |
-| **Report** | `npx torusguard report --html` | `/torusguard report` | `skills/torusguard-report` | Executive posture reporting, SARIF v2.1.0 & visual HTML |
-| **Authorize** | `npx torusguard authorize` | `/torusguard authorize` | `skills/torusguard-authorize`| Legal scope definition & safety boundaries |
-| **Validate** | `npx torusguard web-validate` | `/torusguard web-validate` | `skills/torusguard-web-validate`| Authorized non-destructive HTTP probing |
-| **Exploit** | `npx torusguard exploit-check` | `/torusguard exploit-check`| `skills/torusguard-exploit-check`| Bounded single-step exploitability confirmation |
-| **Full** | `npx torusguard full` | `/torusguard full` | `skills/torusguard-full` | End-to-end 7-stage closed-loop execution |
-| **Sync** | `npx torusguard rules sync` | `/torusguard rules sync` | `skills/torusguard-init` | Synchronize rules across AI editors (Cursor, Claude, Antigravity) |
+| **Init** | `torusguard init` | `/torusguard init` | `.torusguard/skills/torusguard-init` | Stack discovery, rule activation, workspace scaffolding |
+| **Status** | `torusguard status` | `/torusguard status` | `.torusguard/skills/torusguard-status` | Posture score, active rules, run history, scope check |
+| **Audit** | `torusguard audit` | `/torusguard audit` | `.torusguard/skills/torusguard-audit` | Static AST scan, invariant fingerprinting, confidence scoring |
+| **OCR Vision**| `torusguard ocr-scan <path>` | `/torusguard ocr-scan` | `.torusguard/skills/torusguard-ocr-scan` | Tesseract OCR secret scan on images/diagrams |
+| **Verify** | `torusguard verify` | `/torusguard verify` | `.torusguard/skills/torusguard-verify` | Evidence sufficiency audit & line match calibration |
+| **Harden** | `torusguard harden <patch>` | `/torusguard harden` | `.torusguard/skills/torusguard-harden` | Ponytail patch formulation ($\le 35$ add, $\le 25$ del) & reflection validation |
+| **Apply** | `torusguard apply [--yes]` | `/torusguard apply` | `.torusguard/skills/torusguard-apply` | Human Gate review, `.bak` snapshots, patch application |
+| **Rollback** | `torusguard rollback` | `/torusguard rollback` | `.torusguard/skills/torusguard-apply` | Instant 1-step rollback from pre-apply snapshots |
+| **Recheck** | `torusguard recheck` | `/torusguard recheck` | `.torusguard/skills/torusguard-recheck` | Targeted differential AST scan, fix closure verification |
+| **Recipes** | `torusguard recipes` | `/torusguard recipes` | `.torusguard/skills/torusguard-harden` | Explore verified Golden Fix Recipes from persistent memory |
+| **Report** | `torusguard report --html` | `/torusguard report` | `.torusguard/skills/torusguard-report` | Executive posture reporting, SARIF v2.1.0 & visual HTML |
+| **Authorize** | `torusguard authorize` | `/torusguard authorize` | `.torusguard/skills/torusguard-authorize`| Legal scope definition & safety boundaries |
+| **Validate** | `torusguard web-validate` | `/torusguard web-validate` | `.torusguard/skills/torusguard-web-validate`| Authorized non-destructive HTTP probing |
+| **Exploit** | `torusguard exploit-check` | `/torusguard exploit-check`| `.torusguard/skills/torusguard-exploit-check`| Bounded single-step exploitability confirmation |
+| **Container** | `torusguard container` | `/torusguard container` | `.torusguard/skills/torusguard-container` | Audits Dockerfile & Compose for root users, sockets, privileged mode |
+| **Git Mine** | `torusguard git-mine` | `/torusguard git-mine` | `.torusguard/skills/torusguard-git-mine` | Mines git commit history & config for leaked credentials & tokens |
+| **ReDoS** | `torusguard redos` | `/torusguard redos` | `.torusguard/skills/torusguard-redos` | Analyzes regex patterns for catastrophic exponential backtracking |
+| **AI Guard** | `torusguard ai-guard` | `/torusguard ai-guard` | `.torusguard/skills/torusguard-ai-guard` | Audits AI agents & RAG pipelines for prompt injection & tenant leaks |
+| **Full** | `torusguard full` | `/torusguard full` | `.torusguard/skills/torusguard-full` | End-to-end 7-stage closed-loop execution |
+| **MCP Server**| `torusguard mcp` | — | Native Stdio JSON-RPC 2.0 | Serves native Model Context Protocol tools to AI coding agents |
+| **Update** | `torusguard update` | `/torusguard update` | `.torusguard/skills/torusguard-init` | Self-update TorusGuard engine binary |
+| **Help** | `torusguard help` | `/torusguard help` | — | Interactive command guide |
 
 ---
 
 ## Non-Negotiable Invariants
 
-1. **Browser-Code Truth:** If the client receives it, it is public. Zero hardcoded secrets (`SUPABASE_SERVICE_ROLE_KEY`, private tokens, live API keys) in frontend code.
-2. **Multi-Tenant Isolation:** All database lookups must be scoped by organization or user ownership (`tenant_id`, `organization_id`, `where: { tenantId }`).
+1. **Browser-Code Truth:** If the client receives it, it is public. Zero hardcoded secrets (`SUPABASE_SERVICE_ROLE_KEY`, private tokens, live API keys) in frontend code (`TG-CLIENT-001`).
+2. **Multi-Tenant Isolation:** All database lookups must be scoped by organization or user ownership (`tenant_id`, `organization_id`, `where: { tenantId }`) (`TG-DB-001`).
 3. **Ponytail Churn Bounds:** Patches must be minimal and surgical ($\le 35$ additions, $\le 25$ deletions). Never perform full-file rewrites.
 4. **Standardized 75-Column Terminal:** All CLI terminal output is strictly normalized to 75 visual columns with Unicode emoji width calculation, ANSI escape handling, and visual truncation with ellipsis (`...`).
-5. **Zero Security Bypasses:** Never insert `# nosec`, `verify=False`, `InsecureSkipVerify: true`, `[AllowAnonymous]`, or `csrf().disable()`.
+5. **Zero Security Bypasses:** Never insert `# nosec`, `verify=False`, `InsecureSkipVerify: true`, `[AllowAnonymous]`, or `csrf().disable()` (`TG-DIFF-001`).
 6. **Snapshots Before Edits:** Every code modification must capture a byte-for-byte pre-apply backup in `.torusguard/snapshots/<run_id>/` before touching disk code.
-7. **Living Security Report Ground Truth:** All finding discoveries, patch formulations, applications, and recheck verifications must synchronize with `security_report.md` at the workspace root to maintain verifiable finding state and eliminate hallucination.
+7. **Living Report Ground Truth:** All findings synchronize directly with `security_report.md` at workspace root.
+
+---
+
+## 🏛️ Alibaba OpenCodeReview Hybrid Architecture Integration
+TorusGuard employs the dual-track hybrid architecture battle-tested at Alibaba Group scale:
+1. **Deterministic Engineering Pipeline (Go CLI Engine):** Mechanical tasks (file traversal, whitespace tolerance, exact AST matching, Ponytail churn bounds calculation, pre-apply snapshot capture, and OCR extraction) are strictly executed by the compiled Go binary.
+2. **Context Minimization (1/9th Token Strategy):** Agents never dump full files into prompt context. Bounded AST windows ($\pm 3$ lines) are extracted via `ExtractContext` to keep review tokens hyper-dense.
+3. **Line-Level Reflection:** In remediation, the agent provides semantic intent (`find_snippet` + `replace_snippet`). The Go CLI reflection module pins and verifies line bounds deterministically, preventing line-number drift.
 
 ---
 
@@ -68,6 +83,42 @@ TorusGuard operates with 100% feature parity across both the terminal CLI and AI
 │       ├── report.html          # Single-file visual dark-mode HTML report
 │       ├── results.sarif        # OASIS SARIF v2.1.0 log
 │       └── bundles/             # Formulated Ponytail remediation bundles
+├── skills/                      # Canonical distribution skills for end-user AI agents
+├── workflows/                   # Operational step-by-step workflow guides
 └── snapshots/
     └── run-YYYYMMDD-HHMMSS-audit/ # Pre-apply .bak files for instant rollback
 ```
+
+---
+
+## 🚨 LLM Trap Table
+
+| Pattern | What AI Does Wrong | What Is Actually Correct |
+| :--- | :--- | :--- |
+| **Line-Number Diff Hallucination** | Guesses line numbers in unified diff headers (`@@ -42,5 +42,7 @@`) causing patch rejection. | Use the Line-Level Reflection Module (`SemanticPatch` with `find_snippet` and `replace_snippet`) to let Go resolve exact lines. |
+| **Context Window Bloating** | Dumps entire 1,000-line source files into conversation when diagnosing a single finding. | Use bounded AST context extraction ($\pm 3$ lines) matching OpenCodeReview's 1/9th token efficiency. |
+| **Full-File Rewrites** | Rewrites the entire file or surrounding business logic when fixing a vulnerability. | Strictly conform to Ponytail bounds ($\le 35$ additions, $\le 25$ deletions per bundle). |
+| **Security Bypass Insertion** | Introduces `# nosec`, `verify=False`, or `[AllowAnonymous]` to make tests pass. | Strictly forbidden (`TG-DIFF-001`). Rejections are enforced fail-closed by the Go engine. |
+| **Missing Multi-Tenant Scope** | Modifies queries to filter only by record `id`. | Always scope database lookups by tenant or user ownership (`tenantId: user.tenantId`). |
+
+---
+
+## ✅ Pre-Flight Self-Audit
+
+Before producing any security remediation or analysis, verify:
+- [ ] Did I read `security_report.md` at workspace root before proposing changes?
+- [ ] Did I inspect only the bounded AST context window ($\pm 3$ lines) rather than the entire file?
+- [ ] Does my proposed remediation stay strictly within Ponytail bounds ($\le 35$ additions, $\le 25$ deletions)?
+- [ ] Is the fix free of any `# nosec`, `verify=False`, or bypass flags?
+- [ ] Did I verify multi-tenant isolation on all database and model queries?
+- [ ] Can this patch be applied via deterministic reflection (`find_snippet` -> `replace_snippet`)?
+
+---
+
+## 🔁 VBC Protocol (Verify → Build → Confirm)
+
+```
+VERIFY: Inspect living security_report.md and bounded AST context snippet.
+BUILD:  Formulate surgical SemanticPatch (find_snippet + replace_snippet within <=35 add / <=25 del).
+CONFIRM: Validate via torusguard harden, apply snapshot, and execute differential torusguard recheck.
+```