torusguard 2.0.0-alpha → 2.1.1

package/.torusguard/skills/torusguard-full/SKILL.md

@@ -1,16 +1,14 @@
 ---
 name: torusguard-full
 description: Master 7-stage security pipeline orchestrator — coordinates discovery, authorization, static audit, runtime validation, governed remediation, recheck, and reporting.
-version: 1.3.6
+version: 2.0.0
 workflow: .torusguard/workflows/audit.md
 tools: Read, Grep, Glob, Bash, Edit, Write, run_command
 scripts-binding:
+  - internal/scanner/scanner.go
+  - internal/harden/patch.go
+  - internal/apply/apply.go
   - .torusguard/scripts/report_sync.py
-  - .torusguard/scripts/stack_detect.py
-  - .torusguard/scripts/safety_gate.py
-  - .torusguard/scripts/finding_scorer.py
-  - .torusguard/scripts/run_manager.py
-  - .torusguard/scripts/sarif_exporter.py
 ---
 
 # TorusGuard Full — Master 7-Stage Pipeline Orchestrator
@@ -20,15 +18,33 @@ Execute the full, closed-loop TorusGuard security lifecycle from stack discovery
 
 ---
 
+## Tri-Mode Pipeline Parity
+
+| Stage | Mode A: Terminal CLI | Mode B: AI Chat Slash | Mode C: Native MCP Tool |
+| :--- | :--- | :--- | :--- |
+| **0. Init** | `torusguard init` | `/torusguard init` | Init + `torusguard_status` |
+| **1. Authorize** | `torusguard authorize` | `/torusguard authorize` | Safety Gate Boundary |
+| **2. Audit & Vision** | `torusguard audit` / `ocr-scan` | `/torusguard audit` / `ocr-scan` | `torusguard_audit` / `torusguard_ocr_scan` |
+| **3. Verify** | `torusguard verify` | `/torusguard verify` | `torusguard_verify` |
+| **4. Harden** | `torusguard harden` | `/torusguard harden` | `torusguard_harden` |
+| **5. Apply** | `torusguard apply [--yes]` | `/torusguard apply` | Human Gate Approval |
+| **6. Recheck** | `torusguard recheck` | `/torusguard recheck` | `torusguard_recheck` |
+| **7. Report** | `torusguard report --html` | `/torusguard report` | `torusguard://security_report` |
+
+---
+
 ## 7-Stage Security Pipeline
-0. Init (Baseline) ──► 1. Authorize (Scope) ──► 2. Audit (AST Scan) ──► 3. Validate (Evidence/Exploit) ──► 4. Harden (Ponytail Patch) ──► 5. Apply (Backup & Edit) ──► 6. Recheck (Regression) ──► 7. Report (SARIF)
+```
+0. Init ──► 1. Authorize ──► 2. Audit ──► 3. Validate ──► 4. Harden ──► 5. Apply ──► 6. Recheck ──► 7. Report
+(Baseline)   (Scope Gate)     (AST Scan)   (Evidence)     (Ponytail)   (Human Gate)  (Regression)   (SARIF/HTML)
+```
 
 ---
 
 ## Specialist Skill Routing
 - **Phase 0:** `torusguard-init` (`profiler`)
 - **Phase 1:** `torusguard-authorize` (`reviewer`)
-- **Phase 2:** `torusguard-audit` (`auditor`)
+- **Phase 2:** `torusguard-audit` (`auditor`) / `torusguard-ocr-scan` (`vision`)
 - **Phase 3:** `torusguard-verify` / `torusguard-exploit-check` (`validator`)
 - **Phase 4:** `torusguard-harden` (`remediator`)
 - **Phase 5:** `torusguard-apply` (`remediator`)
@@ -38,19 +54,14 @@ Execute the full, closed-loop TorusGuard security lifecycle from stack discovery
 ---
 
 ## Pipeline Execution Instructions
-1. **Init:** Detect stack via `stack_detect.py` and activate rules in `.torusguard/rules/active/`.
+1. **Init:** Detect stack via `torusguard init` and activate tailored rules in `.torusguard/rules/active/`.
 2. **Authorize:** Verify target ownership and TTL in `.torusguard/config/scope.json`.
-3. **Audit:** Scan ASTs; assign fingerprints; cluster root causes; compute confidence scores.
+3. **Audit:** Scan ASTs via `torusguard audit` (or `torusguard ocr-scan` for visual assets); assign fingerprints; compute confidence scores.
 4. **Validate:** Audit evidence sufficiency; optionally send bounded probe canary.
-5. **Harden:** Formulate surgical diffs bound by Ponytail limits ($\le 35$ add, $\le 25$ del).
-6. **Apply:** Save `.bak` snapshot in `pre_apply/`; obtain Human Gate; apply patch.
-7. **Recheck:** Re-scan modified files; assert findings are `Fixed` with zero regressions.
-8. **Report:** Export OASIS SARIF v2.1.0 and emit signed markdown summary.
-
----
-
-## Confidence Scoring Rubric
-Evaluates Evidence (35 pts), Reproduction (25 pts), Corroboration (15 pts), Environment (15 pts), and Review Status (10 pts) into 4 bands: Confirmed (90–100), High (70–89), Medium (50–69), Needs Review (<50).
+5. **Harden:** Formulate surgical diffs bound by Ponytail limits ($\le 35$ additions, $\le 25$ deletions).
+6. **Apply:** Capture `.bak` snapshot in `.torusguard/snapshots/`; obtain Human Gate; apply patch via `torusguard apply`.
+7. **Recheck:** Re-scan modified files via `torusguard recheck`; assert findings are `Fixed` with zero regressions.
+8. **Report:** Export OASIS SARIF v2.1.0 and emit visual HTML dashboard via `torusguard report --html`.
 
 ---
 
@@ -62,6 +73,7 @@ Evaluates Evidence (35 pts), Reproduction (25 pts), Corroboration (15 pts), Envi
 - Human Gate mandatory before code modifications in Phase 5.
 - Enforce Ponytail line bounds ($\le 35$ additions, $\le 25$ deletions).
 - Never dispatch network probes outside authorized scope in `scope.json`.
+- Zero security bypasses permitted (`TG-DIFF-001`).
 
 ---
 
@@ -73,3 +85,34 @@ Evaluates Evidence (35 pts), Reproduction (25 pts), Corroboration (15 pts), Envi
 - SARIF Log: `.torusguard/runs/<run_id>/results.sarif`
 - Report: `.torusguard/runs/<run_id>/report.md`
 ```
+
+---
+
+## 🚨 LLM Trap Table
+
+| Pattern | What AI Does Wrong | What Is Actually Correct |
+| :--- | :--- | :--- |
+| **Pipeline Step Skipping** | Jumps directly from Audit to Apply without verifying evidence or validating Ponytail patch bounds. | Follow the 7 stages in sequential order; each stage gate must be satisfied. |
+| **Human Gate Bypass** | Writes modifications directly to disk without presenting candidate diffs or awaiting user confirmation. | Always require explicit Human Gate confirmation before Phase 5 (`torusguard apply`). |
+| **Full File Rewrites** | Rewrites complete source files during remediation, causing massive line churn and regression risk. | Formulate surgical patches respecting Ponytail bounds ($\le 35$ add, $\le 25$ del) using Line-Level Reflection. |
+| **Unsynchronized State** | Generates reports that don't match the statuses in `security_report.md`. | Keep `security_report.md` synchronized at every phase transition as the single living source of truth. |
+
+---
+
+## ✅ Pre-Flight Self-Audit
+
+Before orchestrating the full pipeline:
+- [ ] Are all prerequisite tools (`torusguard` binary) available?
+- [ ] Is `security_report.md` inspected prior to initiating any scans or fixes?
+- [ ] Are all patches bounded by Ponytail limits and verified without security bypasses?
+- [ ] Is a `.bak` snapshot captured before any disk modification?
+
+---
+
+## 🔁 VBC Protocol (Verify → Build → Confirm)
+
+```
+VERIFY:  Review current workspace security posture and verify phase prerequisites.
+BUILD:   Execute the pipeline stage by stage using designated specialist skills.
+CONFIRM: Validate final SARIF, HTML report, and synchronized security_report.md.
+```

package/.torusguard/skills/torusguard-git-mine/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: torusguard-git-mine
+description: Mines git commit history, commit diffs, and local repository metadata for leaked credentials, private keys, and historical API tokens via CLI, Chat, or MCP.
+version: 2.0.0
+workflow: .torusguard/workflows/git-mine.md
+tools: Read, Grep, Glob, Write, run_command
+scripts-binding:
+  - internal/scanner/git_mine.go
+  - cmd/torusguard/main.go
+  - cmd/torusguard/mcp.go
+---
+
+# TorusGuard Git History Secret Mining
+
+## Objective
+Inspect local `.git` metadata, remote configurations, and commit logs across the repository's commit history to identify leaked API tokens, private keys, database URIs, and credentials that were committed in past revisions or embedded in remote URLs.
+
+---
+
+## Tri-Mode Execution
+
+### Mode A: Automated CLI Execution
+Run Git history mining against current repository or specified target workspace:
+```bash
+# Mine Git commit history and .git/config in current workspace
+torusguard git-mine
+
+# Mine specific repository target
+torusguard git-mine --target /path/to/repo
+```
+
+### Mode B: In-Session AI Chat Slash Command
+Run `/torusguard git-mine` in chat.
+The agent executes the compiled Go Git mining engine or MCP tool to inspect commit history logs, detect historical secret leaks, and provide provider revocation guidance.
+
+### Mode C: Native MCP Tool Call
+MCP-enabled coding agents (Antigravity, Cursor, Windsurf, Claude Code) call:
+```json
+{
+  "tool": "torusguard_git_mine",
+  "arguments": {
+    "target": "."
+  }
+}
+```
+
+---
+
+## Supported Patterns & Invariants
+- **TG-GIT-001 (Historical Secret Commit):** Detects API keys (OpenAI `sk-...`, AWS `AKIA...`, GitHub `ghp_...`), private certificates, or database credentials introduced in prior git commits even if removed from the current working tree.
+- **TG-GIT-002 (Plaintext Remote Credentials):** Flags remote URLs in `.git/config` containing basic authentication credentials (`https://user:token@github.com/...`).
+- **TG-GIT-003 (Sensitive File History Tracking):** Detects tracked `.env`, `id_rsa`, `.pem`, or `.key` files in git log metadata that bypass `.gitignore`.
+
+---
+
+## 🏛️ OpenCodeReview Hybrid Architecture Integration
+- **Deterministic History Inspection:** Analyzes commit logs via local Git commands or fallback file reading with strict 5-second timeouts and bounded commit depths.
+- **Token Minimization:** Emits commit SHA, author timestamp, and redacted secret preview rather than dumping full commit logs into LLM context.
+- **Revocation-First Governance:** Prioritizes immediate credential revocation at the provider (OpenAI, AWS, GitHub) before history rewrites (`git filter-repo` / BFG).
+
+---
+
+## 🚨 LLM Trap Table
+
+| Pattern | What AI Does Wrong | What Is Actually Correct |
+| :--- | :--- | :--- |
+| **Working Tree Only Bias** | Only scans files currently on disk, assuming deleted secrets are safely removed. | Always mine Git commit history (`git log -p`) because Git never forgets past commits. |
+| **Token in Remote Origin URL** | Recommends `git remote set-url origin https://ghp_xxx@github.com/...` which writes token to disk in plaintext. | Use SSH keys, GitHub CLI (`gh auth login`), or credential helpers (`git credential-manager`). |
+| **History Rewriting Over Revocation** | Recommends scrubbing Git history before revoking the leaked secret at the cloud provider. | Always rotate and revoke the credential immediately at the provider first; assume it was scraped. |
+| **Single Commit Amends** | Recommends `git commit --amend` when the secret was committed 5 commits ago. | Use `git rebase -i` or `git-filter-repo` for deeper historical scrubbing. |
+| **Tracking .env in Git** | Adds `.env` to `.gitignore` without running `git rm --cached .env`, leaving file tracked. | Run `git rm --cached <file>` so Git stops tracking the sensitive file in subsequent commits. |
+
+---
+
+## ✅ Pre-Flight Self-Audit
+
+Before concluding a Git repository security audit, verify:
+- [ ] Is `.git` directory present and valid?
+- [ ] Were remote URLs in `.git/config` checked for embedded plaintext passwords or tokens?
+- [ ] Were the most recent 50 commits audited for added secrets in commit diffs?
+- [ ] Did I verify whether `.env` or private keys were ever tracked in git history?
+- [ ] Was the user instructed to rotate/revoke leaked keys at the provider immediately?
+
+---
+
+## 🔁 VBC Protocol (Verify → Build → Confirm)
+
+```
+VERIFY: Confirm workspace is a valid Git repository with accessible commit history.
+BUILD:  Execute torusguard git-mine or torusguard_git_mine to detect historical leaks and credential configs.
+CONFIRM: Provide immediate rotation steps, clean .git/config, and scrub historical commits via git-filter-repo.
+```

package/.torusguard/skills/torusguard-harden/SKILL.md

@@ -1,78 +1,80 @@
 ---
 name: torusguard-harden
 description: Package surgical remediation bundles conforming to the Ponytail Protocol (<= 35 additions, <= 25 deletions) via CLI or AI Agent.
-version: 1.3.6
+version: 2.0.0
 workflow: .torusguard/workflows/harden.md
 tools: Read, Grep, Glob, Write, run_command
 scripts-binding:
-  - .torusguard/scripts/report_sync.py
-  - .torusguard/scripts/harden_runner.py
-  - .torusguard/scripts/diff_guard.py
-  - .torusguard/scripts/term_ui.py
+  - internal/harden/harden.go
+  - internal/harden/patch.go
+  - internal/harden/reflection.go
+  - cmd/torusguard/main.go
 ---
 
 # TorusGuard Harden — Governed Remediation & Bundle Packaging
 
 ## Objective
-Formulate minimal, surgical code fixes bound by the Ponytail Protocol ($\le 35$ additions, $\le 25$ deletions), packaging unified diffs into auditable remediation bundles ready for review.
+Formulate minimal, surgical code fixes bound by the Ponytail Protocol ($\le 35$ additions, $\le 25$ deletions), packaging unified diffs or semantic reflection patches into auditable remediation bundles ready for review.
 
 ---
 
-## Two Execution Modes
+## Tri-Mode Execution
 
 ### Mode A: Automated CLI Execution (Recommended First Step)
 Run the autonomous remediation engine via the terminal:
 ```bash
-# Harden latest audit run
-npx torusguard harden
+# Validate candidate patch or semantic patch against Ponytail bounds
+torusguard harden candidate.patch
 
-# Harden specific project directory
-npx torusguard harden ./my-project
-
-# Harden specific run ID
-npx torusguard harden --run run-20260910-121618-audit
-
-# Machine-readable JSON output
-npx torusguard harden --json
+# Validate semantic JSON patch
+torusguard harden patch.json
 ```
-**Under the Hood:** Executes `python .torusguard/scripts/harden_runner.py`.
-- Discovers findings in `.torusguard/runs/<run_id>/findings.json`.
-- Matches findings against canonical AST patch templates (`TG-SEC-*`, `TG-INPUT-*`, `TG-DB-*`, `TG-PLATFORM-*`, `TG-AUTH-*`, `TG-DIFF-*`).
-- Validates that every candidate patch strictly satisfies Ponytail bounds ($\le 35$ additions, $\le 25$ deletions).
-- Packages candidate bundles into `.torusguard/runs/<run_id>/bundles/<bundle_id>/` containing `patch.diff`, `minimal_patch_plan.md`, and `metadata.json`.
-- Emits run-level summary `remediation.md`.
+**Under the Hood:** Executes compiled Go hardening engine (`internal/harden`).
+- Evaluates patch churn strictly against Ponytail bounds ($\le 35$ additions, $\le 25$ deletions).
+- Scans replacement code for security bypasses (`# nosec`, `verify=False`, `InsecureSkipVerify: true`).
+- Supports both unified diff files (`.diff`, `.patch`) and Semantic Reflection JSON files.
 - Renders pixel-perfect 75-column terminal cards.
 
 ### Mode B: In-Session AI Chat Agent Remediation
-When findings require complex architectural changes, or when the automated CLI cannot formulate a template match:
-1. **Locate Target Finding:** Inspect `.torusguard/runs/<run_id>/findings.md` or `findings.json`.
-2. **Inspect AST Context:** Read surrounding lines ($\pm 15$) of the vulnerable sink using `view_file`.
-3. **Formulate Minimal Fix:** Craft a surgical code modification:
+When findings require complex architectural changes, or when formulating fixes:
+1. **Locate Target Finding:** Inspect `security_report.md` at workspace root.
+2. **Inspect AST Context (1/9th Token Strategy):** Inspect only surrounding lines ($\pm 3$ lines) via `ExtractContext` rather than ingesting entire files.
+3. **Formulate Minimal Semantic Patch:** Formulate a surgical code modification using the Line-Level Reflection Module:
+   - Provide `target_file`, `find_snippet`, and `replace_snippet`.
    - Parameterize SQL queries (replace concatenation with `?` or `$1` or `%s`).
-   - Add tenant isolation (`where: { tenantId }`, `organization_id=...`).
-   - Replace unsafe HTML injection (`dangerouslySetInnerHTML`, `.innerHTML = ...`) with safe text rendering (`textContent`, React elements).
-   - Sanitize path traversal using `path.basename()` or `os.path.basename()`.
-   - Constrain wildcard CORS headers to verified origin environment variables.
-   - Restore TLS verification flags (`verify=True`, `rejectUnauthorized: true`).
+   - Add tenant isolation (`where: { tenantId: user.tenantId }`).
+   - Replace unsafe HTML injection with safe text rendering (`textContent`).
+   - Sanitize path traversal using `filepath.Base()` or `path.basename()`.
+   - Restore TLS verification flags.
 4. **Validate Ponytail Bounds:** Count additions ($\le 35$) and deletions ($\le 25$). Never perform full-file rewrites.
-5. **Package Bundle Artifacts:** Write bundle under `.torusguard/runs/<run_id>/bundles/<bundle_id>/`:
-   - `patch.diff`: Standard unified diff.
-   - `minimal_patch_plan.md`: Context, rationale, and diff preview.
-   - `metadata.json`: Bundle metadata.
-6. **Report to Operator:** Present proposed diff card and recommend running `/torusguard apply` or `npx torusguard apply`.
+5. **Report to Operator:** Present proposed diff card and recommend running `/torusguard apply` or `torusguard apply`.
+
+### Mode C: Native MCP Tool Execution
+For autonomous AI coding agents (Antigravity, Cursor, Windsurf, Claude Code):
+- **Tool Invocation:** Call `torusguard_harden` with semantic reflection arguments:
+  ```json
+  {
+    "target_file": "src/controllers/userController.js",
+    "find_snippet": "const query = `SELECT * FROM users WHERE id = ${req.params.id}`;",
+    "replace_snippet": "const query = 'SELECT * FROM users WHERE id = ? AND tenant_id = ?';\nconst params = [req.params.id, req.user.tenantId];"
+  }
+  ```
+- **Programmatic Return:** Receives exact line ranges matched by Go AST, calculated additions/deletions, and verification that no `# nosec` or security bypasses exist.
 
 ---
 
-## Remediation Bundle Structure
-```
-.torusguard/runs/<run_id>/
-├── remediation.md                         # Run-level catalog of formulated candidate patches
-└── bundles/
-    └── bnd-<rule_id>-<line>-<hash>/
-        ├── patch.diff                    # Unified diff preview
-        ├── minimal_patch_plan.md         # Detailed explanation, rationale, and churn stats
-        └── metadata.json                 # Machine-readable bundle metadata
+## 🏛️ Line-Level Reflection Module (OpenCodeReview Hybrid Engine)
+Instead of forcing the LLM to guess error-prone unified diff line offsets (`@@ -14,6 +14,8 @@`), TorusGuard allows formulating **Semantic Patches**:
+```json
+{
+  "target_file": "server/index.js",
+  "rule_id": "TG-SEC-001",
+  "find_snippet": "const jwtSecret = 'hardcoded-dev-secret-key-12345';",
+  "replace_snippet": "const jwtSecret = process.env.JWT_SECRET;",
+  "rationale": "Extracted hardcoded JWT secret to environment variable"
+}
 ```
+The Go engine deterministically matches `find_snippet` against the target file, counts additions/deletions, verifies Ponytail bounds, and guarantees zero line-number drift.
 
 ---
 
@@ -90,9 +92,38 @@ When findings require complex architectural changes, or when the automated CLI c
 - **Target Finding:** `[TG-SEC-001]` at `server/index.js:9`
 - **Ponytail Churn:** +1 / -1 (Compliant <= 35 add, <= 25 del)
 - **Strategy:** Migrated hardcoded JWT secret to environment variable process.env.JWT_SECRET
-- **Bundle Directory:** `.torusguard/runs/<run_id>/bundles/bnd-tg-sec-001-9-a8310c/`
-- **Next Step:** Run `npx torusguard apply` or `/torusguard apply` to review and apply
+- **Mode:** Line-Level Reflection Match (Semantic Patch)
+- **Next Step:** Run `torusguard apply` or `/torusguard apply` to review and apply
 ```
 
-## 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 |
+| :--- | :--- | :--- |
+| **Line-Number Drift** | Formulates diff headers with estimated line numbers that fail `git apply`. | Use semantic patches (`find_snippet` -> `replace_snippet`) so Go reflection pins line bounds. |
+| **Exceeding Ponytail Budget** | Produces patches with +50 additions or +40 deletions rewriting surrounding logic. | Split complex remediations or keep changes surgical ($\le 35$ additions, $\le 25$ deletions). |
+| **Introducing Bypass Flags** | Inserts `# nosec`, `verify=False`, or `@csrf_exempt` to quickly silence warnings. | Fix the root cause without disabling security invariants. Bypasses trigger immediate error. |
+| **Formatting Unrelated Lines** | Re-indents or cleans up imports in unrelated sections of the target file. | Zero unrelated churn. Touch only the lines required for vulnerability remediation. |
+
+---
+
+## ✅ Pre-Flight Self-Audit
+
+Before formulating a remediation bundle, verify:
+- [ ] Did I read only the bounded AST context window ($\pm 3$ lines) to keep tokens minimal?
+- [ ] Is `find_snippet` an exact, verbatim substring of the target file?
+- [ ] Are total additions $\le 35$ and deletions $\le 25$?
+- [ ] Does `replace_snippet` strictly avoid any bypass flags (`# nosec`, `verify=False`)?
+- [ ] Does the fix preserve existing application behavior and business contracts?
+
+---
+
+## 🔁 VBC Protocol (Verify → Build → Confirm)
+
+```
+VERIFY: Inspect target finding context and verify verbatim match of find_snippet in source code.
+BUILD:  Formulate minimal SemanticPatch or unified diff conforming to Ponytail budget (<=35 add, <=25 del).
+CONFIRM: Validate via torusguard harden or torusguard_harden MCP tool; verify zero bypass rejections.
+```

package/.torusguard/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/.torusguard/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.
+```