torusguard 1.3.4 → 1.3.6

package/README.md

@@ -1,345 +1,476 @@
-<div align="center">
-  <img src="https://raw.githubusercontent.com/githubmofo/TorusGuard/main/TorusGuard.png" alt="TorusGuard Security Banner" width="480" style="max-width: 100%; height: auto; border-radius: 8px;">
-
-  # TorusGuard
-
-  **Autonomous Security Guardrails, Governed Remediation, and Authorized Runtime Validation for AI-Built Web Applications.**
-
-  [![npm version](https://img.shields.io/badge/npm-v1.3.4-cb3837.svg?style=flat-square&logo=npm)](https://www.npmjs.com/package/torusguard)
-  [![GitHub Packages](https://img.shields.io/badge/GitHub%20Packages-v1.3.4-181717.svg?style=flat-square&logo=github)](https://github.com/githubmofo/TorusGuard/pkgs/npm/torusguard)
-  [![Release](https://img.shields.io/badge/Release-v1.3.4-blue.svg?style=flat-square)](https://github.com/githubmofo/TorusGuard/releases/latest)
-  [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg?style=flat-square)](LICENSE)
-  [![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-blue.svg?style=flat-square&logo=python&logoColor=white)](https://python.org)
-  [![Node.js 18+](https://img.shields.io/badge/Node.js-18%2B-339933.svg?style=flat-square&logo=node.js&logoColor=white)](https://nodejs.org)
-  [![SARIF: v2.1.0](https://img.shields.io/badge/SARIF-v2.1.0%20OASIS-purple.svg?style=flat-square)](.torusguard/schemas/)
-  [![Integrity: SHA--256](https://img.shields.io/badge/Integrity-SHA--256%20(216%20Files)-teal.svg?style=flat-square)](.torusguard/.manifest.json)
-  [![OWASP: Top 10](https://img.shields.io/badge/OWASP-Top%2010%20Aligned-orange.svg?style=flat-square)](docs/architecture/SECURITY_ARCHITECTURE.md)
-</div>
-
----
-
-## 💡 Executive Summary
-
-AI coding assistants generate application code at superhuman speeds. However, they routinely hallucinate critical security boundaries: leaking database credentials into client bundles, omitting multi-tenant filters in ORM queries, stripping CSRF protections, or granting unconstrained tool permissions to autonomous agents.
-
-**TorusGuard** is an autonomous application security co-pilot and governed remediation engine built specifically for AI-written code. Operating natively within developer IDEs (Cursor, Claude Code, Antigravity, Windsurf, VS Code Copilot) and CI workflows, it deterministically audits, runtime-verifies, and surgically patches vulnerabilities without destructive full-file rewrites.
-
-### 🌐 The Core Invariant: The Browser-Code Truth
-> **"If the browser receives it, users can inspect it."**  
-> Frontend environment variables, JavaScript network bundles, and React Server Action payloads cannot conceal secrets. TorusGuard strictly enforces that database credentials, service role keys, private API secrets, and tenant boundaries remain exclusively on trusted server runtimes.
-
----
-
-## ⚔️ Why TorusGuard? (Traditional SAST vs. AI Coding Agents)
-
-| Capability | Traditional SAST (SonarQube, Snyk) | Raw AI Coding Agents | TorusGuard Engine |
-|---|:---:|:---:|:---:|
-| **Target Code Base** | Human-written legacy code | Fast, high-churn AI generations | **AI-built full-stack applications** |
-| **Remediation Model** | Issue tickets & PDF reports | Destructive full-file rewrites | **Ponytail Protocol** ($\le 35$ additions, $\le 25$ deletions) |
-| **Learning Feedback** | Static rules, zero memory | Forgets fixes across prompts | **Adaptive Security Memory** & Golden Recipes |
-| **IDE Integration** | Heavy background language servers | Bloated prompt context | **AI IDE Rules Auto-Sync** ($\le 300$ tokens) |
-| **Commit Interception** | Slow server-side webhooks | None (pushes broken code) | **Git Pre-Commit Diff Guard** ($< 200\text{ ms}$) |
-| **Privacy & Telemetry** | Cloud code upload / SaaS | Third-party cloud LLMs | **100% Local, Zero-Egress Guarantee** |
-
----
-
-## 🏛️ System Architecture & Visual Flowcharts
-
-### 1. End-to-End Governance Pipeline
-The complete operational pipeline from developer prompt down to telemetry and IDE rule synchronization:
-
-```mermaid
-flowchart TD
-    subgraph Execution ["1. Execution Layer"]
-        Agent["🤖 AI Agent (Cursor, Claude, Antigravity)"]
-        CLI["💻 Developer CLI / Local Git Hook"]
-    end
-
-    subgraph Profiling ["2. Profiling & Discovery"]
-        Profiler["🔍 Universal Stack Profiler (16+ Languages)"]
-        Monorepo["🏢 Monorepo Fleet Detector (pnpm, Cargo, Go)"]
-    end
-
-    subgraph Detection ["3. AST Audit & Scoring"]
-        Rules["⚙️ 71 Security Rules across 11 Families"]
-        TestFilter["🎯 Test-Path Noise Suppressor"]
-        Scorer["🧮 5-Factor Confidence Scorer (0–100)"]
-    end
-
-    subgraph Intelligence ["4. Memory & Runtime Verification"]
-        Memory["🧠 Adaptive Memory Engine (.torusguard/memory/)"]
-        RuntimeGate["🧪 Authorized Runtime Prober (Masked HTTP)"]
-    end
-
-    subgraph Governance ["5. Governed Remediation & Interception"]
-        Ponytail["✂️ Ponytail Remediation (&lt;= 35 Add, &lt;= 25 Del)"]
-        DiffGuard["🛑 Git Diff Guard (Pre-Commit Interception)"]
-    end
-
-    subgraph Output ["6. Telemetry & AI Sync"]
-        IDEs["🔄 AI IDE Rules Sync (&lt;= 300 Tokens)"]
-        HTML["📊 Standalone Dark-Mode HTML Report"]
-        SARIF["📋 OASIS SARIF v2.1.0 Export"]
-    end
-
-    Agent --> Profiler
-    CLI --> Profiler
-    CLI --> DiffGuard
-
-    Profiler --> Monorepo --> Rules --> TestFilter --> Scorer
-    Memory -.->|"Historical Boost"| Scorer
-    Scorer --> RuntimeGate --> Ponytail
-    Scorer --> Ponytail
-    Ponytail --> DiffGuard
-
-    Ponytail --> Memory
-    Memory --> IDEs
-    Scorer --> HTML
-    Scorer --> SARIF
-```
-
----
-
-### 2. The 7-Stage Finding Lifecycle (Dual-Strategy Governance)
-Every finding follows a strict closed-loop state machine supported equally via **Terminal CLI** (`npx torusguard ...`) and **AI Chat Workflows** (`/torusguard-...`) with an unskippable **Human Gate** and automatic `.bak` snapshots before disk modification:
-
-```mermaid
-flowchart LR
-    Detect["1. DETECT<br/>Static AST Signal<br/><code>audit · /audit</code>"] --> Classify["2. CLASSIFY<br/>0–100 Confidence"]
-    Classify --> Verify["3. VERIFY<br/>Authorized Probe<br/><code>verify · /verify</code>"]
-    Verify --> Remediate["4. REMEDIATE<br/>Ponytail Patch Plan<br/><code>harden · /harden</code>"]
-    Remediate --> Gate{"👤 Human Gate<br/>Approved? [y/N]"}
-    Gate -- Yes --> Apply["5. APPLY<br/>Backup &amp; Surgical Patch<br/><code>apply · /apply</code>"]
-    Gate -- No --> Reject["❌ Discarded"]
-    Apply --> Recheck["6. RE-CHECK<br/>Differential AST Audit<br/><code>recheck · /recheck</code>"]
-    Recheck -- Fixed --> Archive["7. ARCHIVE<br/>Golden Recipe Distilled<br/><code>recipes</code>"]
-    Recheck -- Regressed --> Rollback["⏪ Instant Rollback<br/><code>rollback (.bak)</code>"]
-```
-
----
-
-### 3. Adaptive Memory & AI Rules Sync Loop
-Verified patches are converted into Golden Fix Recipes and injected back into your AI editor's prompt instructions:
-
-```mermaid
-flowchart TD
-    Fix["✅ Verified Fix Applied (/torusguard apply)"] --> Extract["🏆 Golden Recipe Distilled (Diff &lt;= 35/25)"]
-    Extract --> Ledger["📜 Event Appended (memory/events/)"]
-    Ledger --> Patterns["🧠 Pattern Store &amp; Profile Updated"]
-    Patterns --> Sync["🔄 Rules Compiler (rules_sync.py)"]
-    Sync --> Cursor["Cursor (.cursorrules)"]
-    Sync --> Claude["Claude Code (CLAUDE.md)"]
-    Sync --> Antigravity["Antigravity (.agent/rules/)"]
-    Sync --> Windsurf["Windsurf (.windsurfrules)"]
-    Cursor & Claude & Antigravity & Windsurf --> AgentPrompt["🤖 AI Editor Enforces Guardrails (&lt;= 300 Tokens)"]
-```
-
----
-
-### 4. Git Pre-Commit Interception (Diff Guard)
-Blocks security bypasses, exposed credentials, and tenant boundary removals in $< 200\text{ ms}$ before code enters git history:
-
-```mermaid
-flowchart TD
-    Commit["💻 Developer or AI Agent runs: git commit"] --> Hook["⚡ Git Pre-Commit Hook (.git/hooks/pre-commit)"]
-    Hook --> Scanner["🔍 Content-Aware Diff Guard (diff_guard.py &lt; 200 ms)"]
-    Scanner --> Check1{"TG-DIFF-001<br/>Security Bypass?"}
-    Check1 -- Yes --> Block["🚨 COMMIT BLOCKED<br/>Detailed violation + remediation emitted"]
-    Check1 -- No --> Check2{"TG-DIFF-002<br/>Hardcoded Credential?"}
-    Check2 -- Yes --> Block
-    Check2 -- No --> Check3{"TG-DIFF-003<br/>Tenant Boundary Stripped?"}
-    Check3 -- Yes --> Block
-    Check3 -- No --> Pass["✅ COMMIT ALLOWED<br/>Clean diff merged into git history"]
-```
-
----
-
-## ⚡ Core Subsystems (At a Glance)
-
-```text
-┌────────────────────────────────────────────────────────────────────────────────────────┐
-│                                 TORUSGUARD SUBSYSTEMS                                  │
-├──────────────────────────┬──────────────────────────┬──────────────────────────────────┤
-│ 🔍 Detection & Profiling │ 🧠 Adaptive Intelligence │ 🛡️ Governance & Developer Flow   │
-├──────────────────────────┼──────────────────────────┼──────────────────────────────────┤
-│ • 16+ Languages Profiled │ • 0–100 Confidence Model │ • Ponytail Protocol (<= 35/25)   │
-│ • Monorepo Fleet Map     │ • Persistent Event Store │ • Pre-Apply Byte Snapshots (.bak)│
-│ • 71 AST Security Rules  │ • Golden Recipe Learning │ • Pre-Commit Diff Hook (<200 ms) │
-│ • Test-Path Suppression  │ • 90-Day Auto TTL Decay  │ • AI Rules Auto-Sync (<= 300 tok)│
-└──────────────────────────┴──────────────────────────┴──────────────────────────────────┘
-```
-
-- **Universal Profiler & Monorepo Detector:** Discovers manifests across 16+ languages (Go, Rust, Java, C#, PHP, Python, TS) and isolates nested packages (pnpm, Cargo, Gradle, Go work).
-- **Context-Aware Static Auditing:** Evaluates 71 rules across 11 families (`TG-AUTH`, `TG-DB`, `TG-INPUT`, `TG-SEC`, `TG-AGENT`, etc.). Suppresses test mocks automatically via `is_test_path()`.
-- **Adaptive Memory Engine:** Distills verified Before/After fixes into Golden Recipes. Proximity scoring injects targeted advice into a compact card ($\le 2,000$ tokens).
-- **Ponytail Governed Remediation:** Restricts code fixes to $\le 35$ additions and $\le 25$ deletions. Automatically saves byte-for-byte `.bak` backups for instant rollbacks.
-- **Pre-Commit Diff Guard:** 1-command installer (`diff-guard --install-hook`) blocks bypasses (`InsecureSkipVerify`, `[AllowAnonymous]`, `csrf().disable()`, `unsafe`) before git commit.
-- **AI IDE Rules Auto-Sync:** Compiles project security invariants into Cursor, Claude Code, Antigravity, and Windsurf within a strict $\le 300$ token overhead ceiling.
-- **Visual HTML Posture Dashboard:** Generates a 100% self-contained, offline-ready dark-mode report with animated SVG score gauges and interactive diff viewers.
-- **Standardized 75-Column Terminal UI:** Mathematically aligned, zero-distortion terminal cards across all commands, featuring Unicode emoji width calculation, ANSI escape stripping, and visual truncation with ellipsis.
-
----
-
-## 🌐 Polyglot Ecosystem & Framework Matrix
-
-| Language / Stack | Manifests & Ecosystem | Supported Frameworks | Data Layers / ORMs | Intercepted Bypasses (`TG-DIFF`) |
-|---|---|---|---|---|
-| **Python** | `pyproject.toml`, `requirements.txt` | FastAPI, Django, Flask, DRF | SQLAlchemy, Django ORM, Tortoise | Raw SQL formatting, unescaped templates |
-| **TypeScript / JS** | `package.json` | Next.js, Express, NestJS, Nuxt | Prisma, Drizzle, TypeORM, Mongoose | Client-side secrets, tenant deletion |
-| **Go** | `go.mod` | Gin, Fiber, Echo, Chi | GORM, Ent, SQLx | `InsecureSkipVerify: true`, GORM tenant drop |
-| **Rust** | `Cargo.toml` | Actix-web, Axum, Rocket | Diesel, SeaORM, SQLx | Unvetted `unsafe {`, unverified TLS |
-| **Java** | `pom.xml`, `build.gradle` | Spring Boot, Quarkus, Micronaut | Hibernate, JPA, MyBatis, jOOQ | `csrf().disable()`, `permitAll()` |
-| **C# (.NET)** | `*.csproj`, `*.sln` | ASP.NET Core, Blazor | Entity Framework Core, Dapper | `[AllowAnonymous]`, LINQ tenant deletion |
-| **PHP** | `composer.json` | Laravel, Symfony, Slim | Eloquent, Doctrine | `CURLOPT_SSL_VERIFYPEER => false` |
-| **Ruby** | `Gemfile` | Ruby on Rails, Sinatra | ActiveRecord, Sequel | Raw unescaped SQL fragments |
-| **Kotlin** | `build.gradle.kts` | Spring Boot, Ktor | Exposed, Hibernate | Unauthenticated route decorators |
-| **Elixir** | `mix.exs` | Phoenix | Ecto | Unfiltered changeset mutations |
-| **Dart** | `pubspec.yaml` | Flutter, Shelf | Drift | Permissive HTTP certificate overrides |
-| **C / C++** | `CMakeLists.txt`, `Makefile` | Crow, Drogon, Oat++ | Raw SQLite, libpq | Unbounded buffers, raw pointer leaks |
-
----
-
-## 🚀 60-Second Quickstart (Dual-Strategy: CLI & Chat)
-
-TorusGuard works natively in both standard terminal environments (Cursor, VS Code, CI/CD runners) and AI chat workflows:
-
-### Method A: Via Node.js / NPX (Full 7-Stage Governance Lifecycle)
-```bash
-# 1. Initialize TorusGuard in your workspace (or /torusguard init)
-npx torusguard init
-
-# 2. Run static security audit (or /torusguard audit)
-npx torusguard audit
-
-# 3. Formulate minimal Ponytail candidate patches (or /torusguard harden)
-npx torusguard harden
-
-# 4. Review interactive Human Gate & apply with pre-apply rollback snapshots (.bak) (or /torusguard apply)
-npx torusguard apply
-
-# 5. Targeted differential re-scan verifying fix closure (or /torusguard recheck)
-npx torusguard recheck
-
-# 6. Explore distilled Golden Fix Recipes
-npx torusguard recipes
-
-# 7. Generate visual dark-mode HTML posture report (or /torusguard report)
-npx torusguard report --html
-
-# 8. (Optional) Revert to pre-apply snapshot at any time
-npx torusguard rollback
-
-# 9. Install Git Pre-Commit Diff Guard Hook (blocks dangerous commits)
-npx torusguard diff-guard --install-hook
-
-# 10. Synchronize prompt guardrails across AI editors (<= 300 tokens)
-npx torusguard rules sync
-```
-
-### Method B: Via Pure Python 3.10+ (Zero-Dependency Standard Library)
-```bash
-# 1. Initialize workspace
-python .torusguard/scripts/bootstrap.py --workspace .
-
-# 2. Run static audit
-python .torusguard/scripts/finding_scorer.py --dir .
-
-# 3. Formulate candidate patch plans (Ponytail Protocol <= 35 add, <= 25 del)
-python .torusguard/scripts/harden_runner.py
-
-# 4. Interactive Human Gate patch applier with pre-apply byte snapshots
-python .torusguard/scripts/apply_runner.py
-
-# 5. Targeted differential recheck
-python .torusguard/scripts/recheck_runner.py
-
-# 6. Explore distilled Golden Fix Recipes
-python .torusguard/scripts/recipes_runner.py
-
-# 7. Generate single-file visual HTML posture report
-python .torusguard/scripts/html_reporter.py
-
-# 8. Rollback pre-apply snapshots
-python .torusguard/scripts/apply_runner.py --rollback
-
-# 9. Install Pre-Commit Diff Guard
-python .torusguard/scripts/diff_guard.py --install-hook
-
-# 10. Sync AI IDE rules
-python .torusguard/scripts/rules_sync.py --workspace . --format all
-```
-
----
-
-## 💻 CLI Command Reference
-
-| Command | Subcommands & Flags | Description |
-|---|---|---|
-| `torusguard init` | `[--stack <name>] [--profile <type>]` | Scaffolds `.torusguard/` with active security rules, schemas, and workflows. |
-| `torusguard audit` | `[--scope <path>] [--format md\|json]` | Audits source code against active rules, scores confidence, and emits run folder. |
-| `torusguard verify` | `[--id <finding_id>]` | Probes authorized endpoints with automated credential masking. |
-| `torusguard harden` | `[--scope <path>] [--format md\|json]` | Formulates surgical candidate patch bundles adhering to Ponytail bounds ($\le 35$ additions, $\le 25$ deletions). |
-| `torusguard apply` | `[--bundle <id>] [--yes \| -y]` | Interactive terminal Human Gate (`[y/N/all/quit]`) with syntax diffs, creates `.bak` snapshots, applies patches, and distills Golden Recipes. |
-| `torusguard rollback` | `[--run <run_id>]` | Restores all files from `.torusguard/snapshots/<run_id>/` back to disk instantly. |
-| `torusguard recheck`| `[--scope <path>]` | Differentially re-evaluates AST sinks over modified scopes (`Confirmed Fixed` vs `Regressed`). |
-| `torusguard recipes`| `[--rule <id>] [--json]` | Interactive explorer for distilled, verified Golden Fix Recipes stored in persistent memory. |
-| `torusguard report` | `[--sarif] [--html] [--out <path>]` | Exports OASIS SARIF v2.1.0 or single-file visual HTML posture dashboard. |
-| `torusguard status` | `[--json]` | Displays stack detection, active rule count, memory metrics, and run history. |
-| `torusguard diff-guard`| `[--install-hook] [--uninstall-hook] [--diff <file>]` | Scans git diff for bypasses (`TG-DIFF-001..004`) or installs pre-commit hook. |
-| `torusguard rules sync`| `[--format all\|cursor\|claude\|agent\|windsurf]` | Compiles project rules into AI IDE configs within $\le 300$ prompt tokens. |
-| `torusguard memory` | `status \| context \| export \| learn` | Inspects adaptive memory, generates proximity cards, or exports team packs. |
-
----
-
-## 🤖 AI IDE & Agent Setup
-
-TorusGuard injects non-destructive comment fences so your personal instructions remain untouched:
-
-```markdown
-<!-- TORUSGUARD-SECURITY-GUARDRAILS:START -->
-## TorusGuard Security Invariants
-- Browser-Code Truth: Never expose database credentials or private keys in client code.
-- Multi-Tenant Isolation: Always include tenantId/orgId filters on queries.
-- CSRF Protection: Enforce CSRF validation on all state-changing routes.
-<!-- TORUSGUARD-SECURITY-GUARDRAILS:END -->
-```
-
-- **Cursor (`.cursorrules`):** Run `npx torusguard rules sync --format cursor`.
-- **Claude Code (`CLAUDE.md`):** Run `npx torusguard rules sync --format claude`.
-- **Antigravity (`.agent/rules/torusguard.md`):** Run `npx torusguard rules sync --format agent`.
-- **Windsurf (`.windsurfrules`):** Run `npx torusguard rules sync --format windsurf`.
-- **VS Code Copilot & Cline:** Add `SKILL.md` to your skill directory for zero-footprint cognitive guidance.
-
----
-
-## 🛡️ The Ponytail Protocol & Rollback Guarantees
-
-AI coding models often destroy working applications by attempting full-file rewrites to fix minor issues. TorusGuard enforces the **Ponytail Protocol**:
-
-- **Strict Churn Limits:** Every fix is capped at $\le 35$ additions and $\le 25$ deletions.
-- **Full-File Rewrite Ban:** Large destructive edits are rejected by the patch engine.
-- **Rollback Snapshot Guarantee:** Before any file is modified, a byte-for-byte snapshot is saved to `.torusguard/snapshots/<run_id>/<path>.bak`.
-- **Instant Rollback:** Restoring original files takes 1 command (`npx torusguard rollback`).
-
----
-
-## 🔒 Zero-Telemetry Local Privacy Guarantee
-
-TorusGuard operates under an uncompromising **Local Execution Guarantee**:
-- **Zero Network Egress:** No source code, AST trees, credentials, or audit findings leave your machine.
-- **Pure Local Execution:** 100% Python standard library and local Node.js. No background daemons or cloud SaaS accounts.
-- **Automatic Secret Redaction:** Live API keys, JWTs, AWS credentials, and passwords are automatically masked before writing reports.
-- **Sanitized Team Export:** `npx torusguard memory export --sanitized` strips developer usernames and local paths before sharing.
-
-For security policies and responsible disclosure, please refer to [SECURITY.md](SECURITY.md).
-
----
-
-## 📄 License & Community
-
-TorusGuard is open-source software licensed under the [MIT License](LICENSE).
-
-- **Documentation:** Architecture guides and specifications in [docs/](docs/).
-- **Changelog:** Release milestones and updates in [CHANGELOG.md](CHANGELOG.md).
-- **Security Policy:** Vulnerability reporting in [SECURITY.md](SECURITY.md).
-- **Contributions:** Pull requests and discussions are welcomed via [CONTRIBUTING.md](CONTRIBUTING.md).
+<div align="center">
+  <img src="TorusGuard.png" alt="TorusGuard Autonomous Security Engine Banner" width="560" style="max-width: 100%; height: auto; border-radius: 12px; box-shadow: 0 10px 30px rgba(0,0,0,0.5);">
+
+  # TorusGuard
+
+  ### Autonomous Security Guardrails, Governed Remediation & Living Verification for AI-Built Applications
+
+  <p align="center">
+    <strong>Zero Telemetry · Zero External Python Dependencies · Pure Standard-Library Architecture · 100% Local-First</strong>
+  </p>
+
+  [![npm version](https://img.shields.io/badge/npm-v1.3.6-cb3837.svg?style=flat-square&logo=npm)](https://www.npmjs.com/package/torusguard)
+  [![GitHub Packages](https://img.shields.io/badge/GitHub%20Packages-v1.3.6-181717.svg?style=flat-square&logo=github)](https://github.com/githubmofo/TorusGuard/pkgs/npm/torusguard)
+  [![Release](https://img.shields.io/badge/Release-v1.3.6-blue.svg?style=flat-square)](https://github.com/githubmofo/TorusGuard/releases/latest)
+  [![Tests](https://img.shields.io/badge/Tests-120%2F120%20Passing-brightgreen.svg?style=flat-square)](harness/runner.py)
+  [![Security Health](https://img.shields.io/badge/Health%20Score-100%2F100%20Hardened-brightgreen.svg?style=flat-square)](security_report.md)
+  [![Rules Catalog](https://img.shields.io/badge/Rules%20Catalog-74%20Rules%20%7C%2018%20Families-indigo.svg?style=flat-square)](rules/)
+  [![Terminal Standard](https://img.shields.io/badge/Terminal-75--col%20Standard-informational.svg?style=flat-square)](.torusguard/scripts/term_ui.py)
+  [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg?style=flat-square)](LICENSE)
+  [![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B%20(Zero%20Deps)-blue.svg?style=flat-square&logo=python&logoColor=white)](https://python.org)
+  [![Node.js 18+](https://img.shields.io/badge/Node.js-18%2B-339933.svg?style=flat-square&logo=node.js&logoColor=white)](https://nodejs.org)
+  [![SARIF: v2.1.0](https://img.shields.io/badge/SARIF-v2.1.0%20OASIS-purple.svg?style=flat-square)](.torusguard/schemas/)
+  [![OWASP: Top 10](https://img.shields.io/badge/OWASP-Top%2010%20Aligned-orange.svg?style=flat-square)](docs/architecture/SECURITY_ARCHITECTURE.md)
+  [![Privacy](https://img.shields.io/badge/Privacy-100%25%20Local%20Zero--Egress-success.svg?style=flat-square)](docs/overview/security-philosophy.md)
+</div>
+
+---
+
+## 🛡️ The Architecture Behind the Emblem
+
+In the emblem above, the **central golden keyhole shield** represents unbreakable secret protection, authentication integrity, and tenant isolation. It is enveloped by a continuous, interlocking **torus ring**—symbolizing TorusGuard's closed-loop autonomous security lifecycle:
+
+```mermaid
+flowchart LR
+    subgraph Torus ["🔄 360° Closed-Loop Torus Lifecycle"]
+        direction LR
+        Detect["1. Detect (74 AST Rules)"] --> Verify["2. Verify (Evidence & Fingerprints)"]
+        Verify --> Harden["3. Harden (Ponytail Protocol)"]
+        Harden --> Apply["4. Apply (Human Gate & Snapshots)"]
+        Apply --> Recheck["5. Recheck (Differential Closure)"]
+        Recheck --> Memory["6. Memory (Golden Fix Recipes)"]
+        Memory -.->|Continuous Guardrail| Detect
+    end
+
+    subgraph Shield ["🛡️ Central Golden Keyhole Shield"]
+        direction TB
+        Inv1["Browser-Code Truth: Zero Client Secrets"]
+        Inv2["Tenant Partitioning: Scoped Lookups"]
+        Inv3["Zero Bypasses: No verify=False"]
+        Inv4["Living Source of Truth: security_report.md"]
+    end
+
+    Torus === Shield
+```
+
+> **The Developer Reality:** AI coding assistants (Cursor, Claude Code, Copilot, Windsurf) build software at superhuman speed, but routinely leak private keys into client bundles, drop tenant partition filters, or inject raw user input into LLM system prompts.  
+> **TorusGuard forms an unbroken local guardrail around your codebase.** It audits static ASTs, runtime-verifies exploitability with inert canaries, synthesizes minimal surgical diffs adhering to the **Ponytail Protocol** ($\le 35$ additions, $\le 25$ deletions), and eliminates hallucinations by maintaining a verifiable single source of truth in `security_report.md`.
+
+---
+
+## 📑 Table of Contents
+
+1. [Developer Overview & Value Proposition](#-developer-overview--value-proposition)
+2. [End-to-End Autonomous Architecture](#-end-to-end-autonomous-architecture)
+3. [Why TorusGuard? (Traditional SAST vs. AI Coding vs. TorusGuard)](#-why-torusguard)
+4. [Installation & Setup Guide (npm & CLI)](#-installation--setup-guide-npm--cli)
+5. [Quickstart: The 5-Step Core Lifecycle](#-quickstart-the-5-step-core-lifecycle)
+6. [Dual-Strategy Command Matrix (CLI & AI Chat Parity)](#-dual-strategy-command-matrix-cli--ai-chat-parity)
+7. [74 Canonical Security Rules Catalog (18 Families Across 6 Pillars)](#-74-canonical-security-rules-catalog-18-families-across-6-pillars)
+8. [Ponytail Remediation Protocol & Rollback Safety](#-ponytail-remediation-protocol--rollback-safety)
+9. [Living Security Report Ground Truth (`security_report.md`)](#-living-security-report-ground-truth-security_reportmd)
+10. [Visual HTML Dashboard & SARIF v2.1.0 Export](#-visual-html-dashboard--sarif-v210-export)
+11. [AI Editor Guardrails Auto-Sync](#-ai-editor-guardrails-auto-sync)
+12. [Monorepo Fleet Support & Git Pre-Commit Diff Guard](#-monorepo-fleet-support--git-pre-commit-diff-guard)
+13. [Verification & Test Harness (120/120 Passing Harness Explained)](#-verification--test-harness)
+14. [Security Policy & Responsible Disclosure](#-security-policy--responsible-disclosure)
+15. [License](#-license)
+
+---
+
+## 💡 Developer Overview & Value Proposition
+
+When developers use AI coding agents to write features, models optimize for *getting the code to run* rather than *defensive architecture*. Common failure modes include:
+- **Exposing Private Credentials:** Leaking `process.env.SUPABASE_SERVICE_ROLE_KEY` or master database connection strings into Next.js `'use client'` bundles.
+- **Dropping Tenant Boundaries:** Querying Prisma or Mongoose by record ID without scoping by tenant (`where: { id }` instead of `where: { id, tenantId }`).
+- **Prompt Injection Vulnerabilities:** Interpolating untrusted user chat messages directly into system prompts.
+- **Destructive AI Rewrites:** When asked to fix a minor bug, AI models rewrite entire 500-line files, introducing fresh regressions and breaking surrounding business logic.
+
+**TorusGuard solves this deterministically:**
+- **Zero-Egress Local Execution:** 100% of scanning and patching happens on your machine. Zero code or tokens are transmitted to external servers.
+- **Zero Pip Dependencies:** Pure Python standard library (`pathlib`, `re`, `json`, `difflib`, `shutil`). No virtualenv conflicts or broken build wheels.
+- **Ponytail Churn Bounds:** Patches are constrained strictly to $\le 35$ additions and $\le 25$ deletions. Surrounding business logic is never rewritten.
+- **Human Gate & Instant Undo:** Every change requires interactive approval with syntax-highlighted diffs, backed up byte-for-byte in `.torusguard/snapshots/` with instant 1-command rollback.
+
+### 🌐 The Browser-Code Truth Invariant
+> **"If the browser receives it, users can inspect it via DevTools."**  
+> Frontend environment variables, client JavaScript bundles, and React Server Action payloads cannot conceal secrets. TorusGuard strictly enforces that database credentials, service role keys, private API secrets, and tenant boundaries remain exclusively on trusted server runtimes.
+
+---
+
+## 📐 End-to-End Autonomous Architecture
+
+The following flowchart illustrates how TorusGuard safeguards your repository from initial developer input to verified, regression-free output:
+
+```mermaid
+flowchart TD
+    subgraph In ["1. Workspace & AI Context"]
+        A1["Polyglot Source Tree (16+ Languages)"]
+        A2["AI Coding Assistant (Cursor / Claude / Antigravity)"]
+        A3["Git Staged Diffs / Pre-Commit Hook"]
+    end
+
+    subgraph Core ["2. TorusGuard Engine (100% Local-First & Zero-Egress)"]
+        direction TB
+        B1["Static AST Engine: 74 Canonical Rules Across 18 Families"]
+        B2["Living Ledger Sync: security_report.md (0-100 Score)"]
+        B3["Ponytail Synthesizer: Minimal Surgical Diffs (&le;35 Add / &le;25 Del)"]
+        B4["Pre-Apply Snapshot Engine: Byte-for-Byte .bak Backups"]
+        B5["Human Gate: Interactive Syntax-Highlighted Approval"]
+        B6["Targeted Differential Re-Scan: Confirmed Fixed State"]
+
+        B1 --> B2 --> B3 --> B4 --> B5 --> B6
+    end
+
+    subgraph Out ["3. Verified Deliverables & Artifacts"]
+        C1["Hardened Production Code (Zero Regressions)"]
+        C2["Self-Contained Dark-Mode HTML Dashboard"]
+        C3["OASIS SARIF v2.1.0 for CI/CD Pipeline"]
+        C4["Auto-Synced AI Rules (.cursorrules, CLAUDE.md, etc.)"]
+    end
+
+    In --> Core --> Out
+```
+
+---
+
+## ⚔️ Why TorusGuard?
+
+| Security Dimension | Traditional SAST (SonarQube, Snyk) | Raw AI Coding Agents | TorusGuard v1.3.6 Engine |
+|:---|:---:|:---:|:---:|
+| **Target Architecture** | Human-written legacy codebases | High-churn AI code generation | **AI-built full-stack applications** |
+| **Remediation Model** | PDF reports & Jira tickets | Destructive full-file rewrites | **Ponytail Protocol** ($\le 35$ add, $\le 25$ del) |
+| **Fix Preservation** | None (scans from scratch) | Forgets context across chats | **Adaptive Security Memory** & Golden Recipes |
+| **Editor Sync** | Heavy background language daemons | Bloated prompt context ($> 2,000$ tokens) | **Stack-Adaptive Rules** ($\le 300$ prompt tokens) |
+| **Ground-Truth State** | External proprietary web dashboard | Ephemeral chat context (hallucinates) | **Living Security Ledger** (`security_report.md`) |
+| **Pre-Commit Defense** | Slow server-side webhooks | None (commits insecure code) | **Git Pre-Commit Diff Guard** ($< 200\text{ ms}$) |
+| **Privacy & Telemetry** | Cloud code upload / SaaS | Third-party cloud LLMs | **100% Local, Zero-Egress Guarantee** |
+
+---
+
+## 📦 Installation & Setup Guide (npm & CLI)
+
+TorusGuard is designed to be effortless to adopt in any project. There are no configuration servers, databases, or complex background daemons.
+
+### 📋 Prerequisites
+- **Node.js:** 18.0.0 or higher
+- **Python:** 3.10 or higher (**Pure standard library** — **zero `pip` dependencies required**)
+
+> [!IMPORTANT]
+> **Zero Pip Dependencies Guarantee:** TorusGuard's core Python engine relies strictly on the Python standard library (`pathlib`, `re`, `json`, `difflib`, `shutil`, `sys`, `os`, `argparse`, `hashlib`). You **never** need to create a Python virtualenv (`venv`), run `pip install`, or configure external wheels. It works out of the box with your system Python.
+
+---
+
+### 1. Zero-Install Runner (Recommended)
+Run TorusGuard instantly in any repository without installing anything globally:
+
+```bash
+# Run any command directly via npx
+npx torusguard init
+npx torusguard audit
+npx torusguard status
+```
+
+### 2. Project Dev Dependency
+Lock TorusGuard into your project's `package.json` for all team members and CI/CD pipelines:
+
+```bash
+npm install -D torusguard
+```
+
+Add convenience scripts to your `package.json`:
+```json
+{
+  "scripts": {
+    "security:audit": "torusguard audit",
+    "security:harden": "torusguard harden",
+    "security:recheck": "torusguard recheck",
+    "security:status": "torusguard status"
+  }
+}
+```
+
+### 3. Global Installation
+If you prefer having the `torusguard` binary available system-wide across all terminal sessions:
+
+```bash
+npm install -g torusguard
+```
+
+### 4. AI Agent Skill Installation
+Install TorusGuard as a native AI assistant skill for Cursor, Claude Code, Cline, or Antigravity:
+
+```bash
+npx skills add torusguard
+```
+
+---
+
+### 🔍 What Happens on First Run (`init`)
+When you execute `npx torusguard init` in your repository:
+1. **Polyglot Profiling:** Automatically detects 16+ languages (Go, Rust, Java, C#, PHP, Python, TypeScript) and 30+ frameworks without manual configuration.
+2. **Scaffolding:** Creates a local `.torusguard/` directory containing active security rules, schemas, and runners.
+3. **Editor Rules Synchronization:** Automatically compiles compact, language-specific guardrails into `.cursorrules`, `CLAUDE.md`, `.agent/rules/torusguard.md`, and `.windsurfrules` ($\le 300$ prompt tokens).
+4. **Living Ledger Initialization:** Creates `security_report.md` at workspace root to track finding states without hallucination.
+5. **Baseline Policy:** Emits a production-ready `SECURITY.md` for responsible disclosure.
+
+---
+
+## ⚡ Quickstart: The 5-Step Core Lifecycle
+
+Run the complete autonomous governance cycle in 60 seconds from your terminal:
+
+```bash
+# Step 1: Initialize workspace and profile stack
+npx torusguard init
+
+# Step 2: Run AST static security audit across 74 rules
+npx torusguard audit
+
+# Step 3: Synthesize minimal surgical candidate patches
+npx torusguard harden
+
+# Step 4: Review syntax-highlighted diffs and apply with rollback backup
+npx torusguard apply
+
+# Step 5: Differentially recheck modified files to verify fix closure
+npx torusguard recheck
+```
+
+> 💡 **Prefer AI Chat?** Every step above can be triggered directly in your AI assistant chat using `/torusguard init`, `/torusguard audit`, `/torusguard harden`, `/torusguard apply`, and `/torusguard recheck`!
+
+---
+
+## ⌨️ Dual-Strategy Command Matrix (CLI & AI Chat Parity)
+
+TorusGuard guarantees **100% operational parity** between terminal CLI execution and AI chat slash commands. Terminal outputs strictly adhere to a **75-column visual width** with Unicode emojis and ANSI stripping.
+
+### 🔄 Core Remediation Lifecycle
+
+| Lifecycle Stage | Mode A: Terminal CLI | Mode B: AI Chat Command | Governed Action & Primary Artifact |
+|:---|:---|:---|:---|
+| **1. Init** | `npx torusguard init` | `/torusguard init` | Profiles workspace, activates rules, initializes `.torusguard/` |
+| **2. Audit** | `npx torusguard audit` | `/torusguard audit` | 74-rule AST scan, line-shift fingerprints, updates `security_report.md` |
+| **3. Harden** | `npx torusguard harden` | `/torusguard harden` | Synthesizes Ponytail diffs ($\le 35$ add, $\le 25$ del) into candidate bundles |
+| **4. Apply** | `npx torusguard apply [--yes]` | `/torusguard apply` | Human Gate, pre-apply `.bak` snapshots, Golden Fix distillation |
+| **5. Rollback**| `npx torusguard rollback` | `/torusguard rollback` | Instant restoration from pre-apply snapshots in `.torusguard/snapshots/` |
+| **6. Recheck** | `npx torusguard recheck` | `/torusguard recheck` | Differential AST re-scan; marks findings `RESOLVED 🟢` in living report |
+
+### 📊 Intelligence, Memory & Reporting
+
+| Capability | Mode A: Terminal CLI | Mode B: AI Chat Command | Governed Action & Primary Artifact |
+|:---|:---|:---|:---|
+| **Status** | `npx torusguard status` | `/torusguard status` | 75-column diagnostic overview of health score, stack, memory & rules |
+| **Recipes** | `npx torusguard recipes` | `/torusguard recipes` | Explores verified Golden Fix patterns stored in `.torusguard/memory/` |
+| **Report** | `npx torusguard report --html` | `/torusguard report` | Emits single-file dark-mode HTML posture report & OASIS SARIF v2.1.0 |
+| **Rules Sync**| `npx torusguard rules sync` | `/torusguard rules sync`| Synchronizes prompt guardrails across Cursor, Claude, Antigravity, Windsurf |
+| **Diff Guard**| `npx torusguard diff-guard` | `/torusguard diff-guard`| Audits git diffs for security bypasses; `--install-hook` binds pre-commit |
+
+### 🧪 Runtime Verification & Bounded Probing
+
+| Capability | Mode A: Terminal CLI | Mode B: AI Chat Command | Governed Action & Primary Artifact |
+|:---|:---|:---|:---|
+| **Authorize** | `npx torusguard authorize` | `/torusguard authorize` | Target domain allowlisting, cryptographic ownership proof, TTL limits |
+| **Verify** | `npx torusguard verify` | `/torusguard verify` | Asserts evidence sufficiency & live disk line-shift fingerprint matches |
+| **Validate** | `npx torusguard web-validate` | `/torusguard web-validate`| Authorized non-destructive HTTP probing with transparent audit headers |
+| **Exploit** | `npx torusguard exploit-check`| `/torusguard exploit-check`| Bounded single-step exploitability confirmation using inert sentinels |
+
+---
+
+## 📋 74 Canonical Security Rules Catalog (18 Families Across 6 Pillars)
+
+TorusGuard's AST scanner inspects polyglot source trees across 74 canonical security rules organized into **6 core security pillars** across 18 families:
+
+```text
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                    74 CANONICAL RULES ACROSS 6 PILLARS                      │
+└─────────────────────────────────────────────────────────────────────────────┘
+  1. Secrets & Identity       ──► TG-SEC (7)  · TG-AUTH (8) · TG-CLIENT (2)
+  2. Data & Injection Defense ──► TG-DB (4)   · TG-INPUT (6) · TG-CSRF (2)
+  3. AI Agent & LLM Security  ──► TG-AGENT (4)
+  4. Network & Real-Time      ──► TG-SSRF (4) · TG-WEBHOOK (4) · TG-WS (4)
+  5. Platform & API Limits    ──► TG-RATE (3) · TG-GQL (4) · TG-PLATFORM (4)
+                                  TG-CACHE (3) · TG-EDGE (2)
+  6. Supply Chain & Governance──► TG-SUPPLY (6) · TG-BIZ (4) · TG-DIFF (3)
+```
+
+| Pillar | Family Prefix | Rules | Critical Invariant Enforced |
+|:---|:---|:---:|:---|
+| **🔑 Secrets & Client Bundles** | `TG-SEC`, `TG-CLIENT` | **9** | Zero hardcoded API keys, JWT secrets, private certificates, or server keys in client bundles. |
+| **🛡️ Authentication & Sessions** | `TG-AUTH`, `TG-CSRF` | **10** | Timing-safe string compares, strong password hashing, algorithm verification, SameSite cookies. |
+| **🗄️ Database & Input Safety** | `TG-DB`, `TG-INPUT` | **10** | Parameterized SQL queries, multi-tenant isolation (`where: { tenantId }`), path sanitization. |
+| **🤖 AI Agent & LLM Guardrails** | `TG-AGENT` | **4** | Structural user prompt isolation, delimiter wrapping, shell tool sandboxing, MCP least-privilege. |
+| **🌐 Network, Webhooks & WS** | `TG-SSRF`, `TG-WEBHOOK`, `TG-WS` | **12** | Private IP range blocking (`169.254.169.254`), HMAC-SHA256 signature checks, WS origin validation. |
+| **⚡ Platform, Edge & Governance** | `TG-RATE`, `TG-GQL`, `TG-PLATFORM`, `TG-CACHE`, `TG-EDGE`, `TG-SUPPLY`, `TG-BIZ`, `TG-DIFF` | **29** | Auth rate limiting, GraphQL depth bounds, Helmet headers, lockfile integrity, zero `# nosec` bypasses. |
+
+<details>
+<summary><strong>🔍 Click to expand full 18-family catalog breakdown</strong></summary>
+
+<br>
+
+- **`TG-SEC` (Secrets & API Tokens — 7 rules):** Detects hardcoded JWT secrets, private certificates, cloud API keys, environment variable leakage, and secrets in URL queries or logs.
+- **`TG-AUTH` (Authentication & Access Control — 8 rules):** Enforces constant-time string comparisons, strong password hashing (`bcrypt`/`argon2`), JWT algorithm pinning, mass assignment prevention, and server-side role verification.
+- **`TG-DB` (Database Partitioning & Injection — 4 rules):** Mandates tenant-scoped queries across Prisma, Mongoose, SQLAlchemy, and GORM; eliminates raw SQL string concatenation.
+- **`TG-INPUT` (Input Validation & Traversal — 6 rules):** Enforces safe path sanitization (`path.basename`), command argument escaping, safe DOM text assignments, and server-side file upload bounds.
+- **`TG-RATE` (Rate Limiting & Resource Protection — 3 rules):** Enforces rate-limiting middleware on authentication routes, pagination bounds, and request payload size limits.
+- **`TG-AGENT` (AI Agent & LLM Defense — 4 rules):** Enforces structural separation of user prompts from system instructions, inert XML delimiters, and containerized tool execution.
+- **`TG-SSRF` (Server-Side Request Forgery — 4 rules):** Restricts dynamic outbound HTTP calls, blocks AWS/cloud metadata access (`169.254.169.254`), and enforces request timeouts.
+- **`TG-WEBHOOK` (Webhook Verification — 4 rules):** Mandates cryptographic HMAC-SHA256 signature validation before body parsing, replay prevention, and timestamp expiration.
+- **`TG-WS` (WebSocket Security — 4 rules):** Enforces handshake authentication, origin validation, channel-level authorization, and frame size caps.
+- **`TG-CSRF` (Cross-Site Request Forgery — 2 rules):** Enforces anti-CSRF tokens on state-changing operations and `SameSite` cookie attributes.
+- **`TG-GQL` (GraphQL Protection — 4 rules):** Enforces query depth limiting, production introspection suppression, and field-level resolver authorization.
+- **`TG-SUPPLY` (Supply Chain Integrity — 6 rules):** Audits dependency lockfile presence, checks against known CVEs, prevents `--no-audit` build flags, and inspects build scripts.
+- **`TG-BIZ` (Business Logic Bounds — 4 rules):** Validates negative quantity inputs, coupon/discount boundaries, and race-condition transaction locks.
+- **`TG-CACHE` (Cache Isolation — 3 rules):** Enforces `Cache-Control: no-store, private` on authenticated responses and sanitizes unkeyed request headers.
+- **`TG-CLIENT` (Client Bundle Hygiene — 2 rules):** Forbids importing private server environment variables into browser bundles and suppresses production source maps.
+- **`TG-PLATFORM` (Server Hardening — 4 rules):** Enforces Helmet HTTP security headers, CORS origin whitelisting, cookie `secure` flags, and debug mode suppression.
+- **`TG-DIFF` (Polyglot Diff Integrity — 3 rules):** Intercepts security bypass comments (`# nosec`, `InsecureSkipVerify: true`) and asserts Ponytail patch budgets.
+- **`TG-EDGE` (Edge & Serverless Limits — 2 rules):** Prevents cross-request memory leaks in Cloudflare Workers and enforces subrequest fan-out limits.
+
+</details>
+
+---
+
+## ✂️ Ponytail Remediation Protocol & Rollback Safety
+
+Traditional AI coding assistants routinely destroy functional features by attempting full-file rewrites. TorusGuard strictly enforces the **Ponytail Protocol**:
+
+$$\Delta \text{Lines} \le 35\text{ Additions}, \quad \Delta \text{Lines} \le 25\text{ Deletions}$$
+
+### 🛡️ Pre-Apply Rollback Snapshots
+Before modifying a single file on disk, `apply_runner.py` creates a byte-for-byte backup:
+```text
+.torusguard/snapshots/<run_id>/<target_file>.bak
+```
+
+If a patch causes unforeseen behavior or test failures, execute an instant 1-command rollback:
+```bash
+npx torusguard rollback
+```
+All affected files are immediately restored to their exact pre-patch byte state.
+
+---
+
+## 📜 Living Security Report Ground Truth (`security_report.md`)
+
+To eliminate AI hallucination, TorusGuard maintains `security_report.md` at the workspace root as the single source of truth across all CLI commands and AI chat sessions.
+
+### 🔄 Lifecycle State Machine
+```text
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                     SECURITY REPORT LIFECYCLE STATE MACHINE                 │
+└─────────────────────────────────────────────────────────────────────────────┘
+  [ OPEN 🔴 ] ──(verify)──► [ VERIFIED 🟠 ] ──(harden)──► [ CANDIDATE 🟡 ]
+                                                                 │
+                                                               (apply)
+                                                                 │
+                                                                 ▼
+  [ RESOLVED 🟢 ] ◄──(recheck: confirmed)── [ APPLIED 🔵 ]
+         │
+         └──(recheck: failed)──► [ REGRESSED ❌ ]
+```
+
+### 🧮 Posture Health Score (0–100)
+The Health Score dynamically reflects the open risk ledger:
+$$\text{Penalty} = (25 \times \text{Critical}) + (15 \times \text{High}) + (5 \times \text{Medium}) + (2 \times \text{Low})$$
+$$\text{Score} = \max(0, \min(100, 100 - \text{Penalty}))$$
+
+*When all findings are verified closed via differential recheck, the repository achieves **Health Score: 100/100 🟢 Hardened & Secure**.*
+
+---
+
+## 📊 Visual HTML Dashboard & SARIF v2.1.0 Export
+
+Generate a standalone, zero-external-CDN, dark-mode visual posture dashboard:
+```bash
+npx torusguard report --html
+```
+- **SVG Circular Posture Gauge:** Animated visual health score ($0-100$).
+- **7-Stage Closed-Loop Pipeline:** Visual state timeline across all lifecycle phases.
+- **Golden Fix Recipes Grid:** Syntax-highlighted unified diffs with Ponytail metrics.
+- **Zero-CDN Architecture:** Completely offline-ready; embeds all styles and assets inline.
+
+To integrate with **GitHub Code Scanning**, export standard SARIF:
+```bash
+npx torusguard report > results.sarif
+```
+
+---
+
+## 🤖 AI Editor Guardrails Auto-Sync
+
+TorusGuard compiles project security invariants, golden recipes, and active guardrails into prompt-optimized rule files:
+```bash
+npx torusguard rules sync
+```
+
+### Supported AI Editors:
+- **Cursor:** Injects non-destructive rules into `.cursorrules`
+- **Claude Code:** Injects non-destructive rules into `CLAUDE.md`
+- **Antigravity IDE:** Injects non-destructive rules into `.agent/rules/torusguard.md`
+- **Windsurf:** Injects non-destructive rules into `.windsurfrules`
+
+*All rules are compiled under a strict overhead ceiling of $\le 300$ prompt tokens to preserve AI reasoning context.*
+
+---
+
+## 🏢 Monorepo Fleet Support & Git Pre-Commit Diff Guard
+
+TorusGuard automatically discovers and profiles multi-package workspaces:
+- **Monorepo Ecosystems:** pnpm workspaces, npm/yarn workspaces, Cargo workspaces, Go multi-module workspaces, Gradle multi-project builds.
+- **Universal Polyglot Profiler:** Automatically identifies 16+ languages and maps ORM boundaries independently per sub-package.
+- **Pre-Commit Diff Guard:** Run `npx torusguard diff-guard --install-hook` to bind `.git/hooks/pre-commit` and block security bypasses before code is committed.
+
+---
+
+## 🧪 Verification & Test Harness
+
+### What Happens When You Run `npm test`?
+TorusGuard enforces a strict **100% pass requirement across 120 test suites** before every release.
+The test harness runs with **zero third-party dependencies** via standard Python 3:
+
+```bash
+npm test
+# Equivalent to: python harness/runner.py
+```
+
+When a developer runs:
+```bash
+npm test
+```
+The test harness invokes `python harness/runner.py` directly using the Python standard library. It systematically verifies:
+1. **JSON Schema Validity:** 10 formal schemas (`finding`, `evidence`, `remediation`, `rule`, `lifecycle`, `provenance`, etc.).
+2. **74-Rule Catalog Integrity:** AST detection accuracy across all 18 security families.
+3. **Line-Shift Fingerprinting:** Stable anchor matching across file edits without line number drift.
+4. **Secret Redaction:** Stripe secret keys and JWT tokens safely masked.
+5. **Deterministic Replay:** 3-pass differential validation across Django, DRF, FastAPI, Flask, and SQLAlchemy fixtures.
+6. **Ponytail Patch Churn Bounds:** Verifying line budgets ($\le 35$ additions, $\le 25$ deletions).
+7. **Living Security Report State Transitions:** Discovery (`OPEN 🔴`), Candidate (`CANDIDATE 🟡`), Applied (`APPLIED 🔵`), and Verified Closure (`RESOLVED 🟢`).
+
+```bash
+# Run formal TorusGuard test harness
+npm test
+
+# Expected Output:
+# ================================================================================
+# SUMMARY: 120 Passed | 0 Failed
+# ================================================================================
+```
+
+To validate diff guard and monorepo profiling independently:
+```bash
+python harness/validate_v0_9_2_diff_and_monorepo.py
+```
+
+---
+
+## 🔒 Security Policy & Responsible Disclosure
+
+If you believe you have discovered a security vulnerability in TorusGuard itself, please report it responsibly and privately through [GitHub Private Vulnerability Reporting](https://github.com/githubmofo/TorusGuard/security/advisories/new) or contact the project maintainers. Do not file public issues for undisclosed security flaws. For complete details, consult [SECURITY.md](SECURITY.md).
+
+---
+
+## 📄 License
+
+TorusGuard is released under the [MIT License](LICENSE).  
+Copyright (c) 2026 Jenish Lad ([@githubmofo](https://github.com/githubmofo)).