continuous-improvement 3.8.0 → 3.9.2

package/commands/superpowers.md

@@ -1,22 +1,95 @@
 ---
 name: superpowers
-description: "Activate mandatory agent workflows: brainstorming, TDD, code review, git worktrees, and structured development"
+description: "Law activator and dispatcher — route the task to the right Law-aligned specialist across continuous-improvement and four vendored upstream skill libraries (Obra superpowers, addy-agent-skills, ruflo-swarm, oh-my-claudecode)."
 ---
 
 # /superpowers
 
-Activate the Superpowers mandatory workflow framework. Skills trigger automatically based on context — this is not optional guidance.
+`/superpowers` is **the dispatcher**, not a peer skill. It does not do work itself; it routes each user task to the correct Law-aligned specialist so the right discipline fires automatically instead of the agent skipping a step.
+
+The 7 Laws define *what* discipline must be applied. `/superpowers` decides *which specialist* enforces it for this specific task, across five sources installed from this marketplace.
+
+## Routing surface (five sources)
+
+| Source | Where it lives | Examples of what it routes to |
+|---|---|---|
+| `continuous-improvement` (this plugin) | bundled — always present | `gateguard` (Law 1), `tdd-workflow` (Law 3+4), `verification-loop` (Law 4), `wild-risa-balance` (Law 2), `safety-guard` (Law 3), `proceed-with-the-recommendation` (all 7), `ralph` (Law 6), `workspace-surface-audit` (Law 1) |
+| `obra/superpowers` (Jesse Vincent) | vendored at `third-party/superpowers/`, pinned SHA `f2cbfbe` (v5.1.0) | `superpowers:brainstorming`, `:writing-plans`, `:executing-plans`, `:test-driven-development`, `:systematic-debugging`, `:requesting-code-review`, `:receiving-code-review`, `:verification-before-completion`, `:dispatching-parallel-agents`, `:using-git-worktrees`, `:finishing-a-development-branch`, `:subagent-driven-development`, `:writing-skills`, `:using-superpowers` |
+| `addyosmani/agent-skills` | vendored at `third-party/addy-agent-skills/`, pinned SHA `742dca5` (v1.0.0) | `spec-driven-development`, `source-driven-development`, `context-engineering`, `idea-refine`, `incremental-implementation`, `code-review-and-quality`, `code-simplification`, `security-and-hardening`, `debugging-and-error-recovery`, `performance-optimization`, `api-and-interface-design`, `frontend-ui-engineering`, `browser-testing-with-devtools`, `ci-cd-and-automation`, `deprecation-and-migration`, `documentation-and-adrs`, `git-workflow-and-versioning`, `planning-and-task-breakdown`, `shipping-and-launch` |
+| `ruflo-swarm` (ruvnet) | vendored at `third-party/ruflo-swarm/`, pinned SHA `addb5cd` (v0.2.0) | `swarm-init`, `monitor-stream`; `swarm_*` and `agent_*` MCP tools; `/swarm`, `/watch` |
+| `oh-my-claudecode` (Yeachan-Heo) | vendored at `third-party/oh-my-claudecode/`, pinned SHA `aacde3e` (v4.13.6) | 39 skills + 19 agents — `release`, `ultrawork`, `ultraqa`, `team`, `trace`, `visual-verdict`, `debug`, `deep-dive`, `deep-interview`, `autopilot`, `autoresearch`, plus a separate `ralph` (overlaps with our `/ralph` — see "Distinct variants" below) |
+
+PM coverage (product-management skills) lives **outside** this marketplace. If you need it, install [`phuryn/pm-skills`](https://github.com/phuryn/pm-skills) separately via Claude Code's host marketplace; the dispatcher names it as a routing target without pre-resolving the namespace. See [docs/THIRD_PARTY.md § Routing in /superpowers](../docs/THIRD_PARTY.md#routing-in-superpowers).
+
+## Distinct variants — never collapse them
+
+Two routing targets carry the same short name across sources. Treat them as distinct; do not silently substitute one for the other.
+
+| Short name | `obra/superpowers` (Obra) | `continuous-improvement` (CI fork) |
+|---|---|---|
+| `superpowers` (skill) | activator routing into Obra skills | `superpowers` skill in this repo: Law-aligned activator wrapping the dispatcher commitments below |
+| `ralph` | not present in Obra | bundled here; `oh-my-claudecode` ships its own `ralph` — pick deliberately, do not auto-merge |
+
+If both Obra `superpowers` and continuous-improvement are loaded, you can call either explicitly: `superpowers:test-driven-development` (Obra) or `tdd-workflow` (CI). Same Law (3+4), different implementation depth.
+
+## Dispatcher commitments (override looser global defaults when `/superpowers` is in scope)
+
+When this dispatcher is active for a task, these six rules apply over any looser convention:
+
+1. **Subagent-driven development is the default for non-trivial tasks.** Two-stage spec + quality review per [obra/superpowers § subagent-driven-development](https://github.com/obra/superpowers).
+2. **Parallel fan-out goes through `superpowers:dispatching-parallel-agents`** (or `/swarm`), not hand-rolled `Task` calls.
+3. **TDD runs RED → GREEN → REFACTOR.** Code written before its test is **deleted**, not retrofitted. Routes to `tdd-workflow` (CI) or `superpowers:test-driven-development` (Obra) — pick by depth, never both for the same task.
+4. **Branch isolation is `using-git-worktrees`** by default for any task that touches more than one file.
+5. **`finishing-a-development-branch` runs before any push.** No bypass via `--no-verify`, `--force`, or direct push to `main`.
+6. **Obra `superpowers` and `continuous-improvement:superpowers` stay distinct.** Both can be installed; neither shadows the other; the dispatcher names which one is firing.
+
+## Routing rules (which source wins)
+
+| User intent | Preferred routing target | Source |
+|---|---|---|
+| New feature, vague requirements | `superpowers:brainstorming` → `:writing-plans` | `obra/superpowers` |
+| Fix this bug | `superpowers:systematic-debugging` → `tdd-workflow` (RED first) → `verification-loop` | Obra → CI → CI |
+| Walk an agent's recommendation list | `proceed-with-the-recommendation` | CI |
+| Write tests for new code | `tdd-workflow` (CI default) or `superpowers:test-driven-development` (Obra, deeper) | CI / Obra |
+| Verify before reporting "done" | `verification-loop` | CI |
+| Refactor, multi-file | `superpowers:using-git-worktrees` → `:writing-plans` → `tdd-workflow` → `:finishing-a-development-branch` | Obra → Obra → CI → Obra |
+| Long autonomous PRD execution | `/ralph` (CI variant) | CI |
+| Parallel sub-agent fan-out | `superpowers:dispatching-parallel-agents` or `/swarm` | Obra / ruflo-swarm |
+| Spec-first, contract-first feature | `spec-driven-development` | addy-agent-skills |
+| Frontend / UI generation | `frontend-design` (external plugin) | external |
+| Diff walk + severity tagging | `code-review` (external plugin) or `superpowers:requesting-code-review` | external / Obra |
+| Library / framework docs lookup | `documentation-lookup` (Context7 MCP) | external |
+| Compliance / security gate | `security-and-hardening` (addy) → `security-review` (host built-in) | addy → host |
+| Release coordination across PRs | `/release-train` | CI |
+
+## Missing-companion detection
+
+If `/superpowers` is asked to route to a source that is not installed, it does not silently fall back to the inline placeholder. It must:
+
+1. **Name the missing source** explicitly (e.g. `obra/superpowers` not loaded).
+2. **Quote the exact install line** for it from the marketplace already added in setup, e.g. `/plugin install superpowers@continuous-improvement`.
+3. **State the inline-fallback equivalent** that will run if the user declines to install (and which Law that fallback enforces).
+4. **Stop and ask** before continuing. Do not silently downgrade.
+
+This is the same hard-halt discipline used by `proceed-with-the-recommendation` for `needs-approval` items.
 
 ## Subcommands
 
 ### `/superpowers status`
 
-Show which workflow stages are active:
+Show which routing sources are loaded, which workflow stages are active for the current task, and which sources are **missing**:
 
 ```
 === Superpowers Status ===
 
-Active Skills:
+Sources:
+  [x] continuous-improvement       (bundled)
+  [x] obra/superpowers              v5.1.0 (vendored)
+  [ ] addyosmani/agent-skills       MISSING — /plugin install agent-skills@continuous-improvement
+  [x] ruflo-swarm                   v0.2.0 (vendored)
+  [ ] oh-my-claudecode              MISSING — /plugin install oh-my-claudecode@continuous-improvement
+
+Active for current task:
   [x] brainstorming (trigger: new feature request)
   [ ] using-git-worktrees (waiting: design approval)
   [ ] writing-plans (waiting: worktree ready)
@@ -27,127 +100,81 @@ Active Skills:
 
 ### `/superpowers enable <skill>`
 
-Explicitly enable a skill for the current session:
+Explicitly enable a skill for the current session — useful when the dispatcher's intent detection guesses wrong:
 
 ```
 /superpowers enable test-driven-development
+/superpowers enable superpowers:writing-plans   # namespaced form for Obra
 ```
 
 ### `/superpowers workflow <type>`
 
 Activate a complete workflow preset:
 
-| Preset | Skills Activated |
-|--------|------------------|
-| `new-feature` | brainstorming → worktrees → plans → TDD → review → finish |
-| `bug-fix` | systematic-debugging → verification → TDD → review |
-| `refactor` | worktrees → plans → TDD → review → finish |
-| `review` | requesting-code-review → receiving-code-review |
+| Preset | Skills activated (in order) |
+|---|---|
+| `new-feature` | `superpowers:brainstorming` → `:using-git-worktrees` → `:writing-plans` → `tdd-workflow` → `verification-loop` → `:requesting-code-review` → `:finishing-a-development-branch` |
+| `bug-fix` | `superpowers:systematic-debugging` → `verification-loop` → `tdd-workflow` (regression test first) → `:requesting-code-review` |
+| `refactor` | `superpowers:using-git-worktrees` → `:writing-plans` → `tdd-workflow` → `:requesting-code-review` → `:finishing-a-development-branch` |
+| `review` | `superpowers:requesting-code-review` → `:receiving-code-review` |
+| `release` | `/release-train` → `verification-loop` → `superpowers:finishing-a-development-branch` |
 
 Example:
 ```
 /superpowers workflow new-feature
 ```
 
-## Mandatory Skills
-
-### brainstorming
-**Triggers:** New feature requests, vague requirements
-
-1. Ask clarifying questions
-2. Explore 2-3 alternatives
-3. Present design in sections
-4. Wait for explicit approval
+## Verification protocol (Law 4)
 
-### using-git-worktrees
-**Triggers:** Design approved, feature branch needed
-
-Creates isolated workspace:
-```bash
-git worktree add -b feature-name ../feature-name
-```
+Every routed skill must verify before reporting completion. The dispatcher refuses to advance to the next stage until the current one shows:
 
-### writing-plans
-**Triggers:** Worktree ready, implementation starting
+1. Code runs without errors
+2. Output matches expected result
+3. Actual result checked — not assumed
+4. Build passes
+5. Change explainable in one sentence
 
-Breaks work into bite-sized tasks (2-5 minutes each). Every task includes:
-- Exact file paths
-- Complete code
-- Verification steps
-
-### test-driven-development
-**Triggers:** Plan approved, coding begins
-
-```
-RED: Write failing test → Watch it fail
-GREEN: Write minimal code → Watch it pass
-REFACTOR: Improve while green → Commit
-```
-
-**Rule:** Code written before tests is deleted.
-
-### requesting-code-review
-**Triggers:** Task complete, before continuing
-
-Two-stage review:
-1. Spec compliance — Does it match the plan?
-2. Code quality — Clean, tested, maintainable?
-
-Severity levels: Critical (blocks), Warning (note), Info (log)
-
-### finishing-a-development-branch
-**Triggers:** All tasks complete
-
-Options presented:
-- Merge to main
-- Create PR
-- Keep branch
-- Discard (with confirmation)
-
-## Skill Activation Rules
-
-| User Request | Activates |
-|--------------|-----------|
-| "Create a feature" | brainstorming → writing-plans → executing-plans |
-| "Fix this bug" | systematic-debugging → verification → TDD |
-| "Review this code" | requesting-code-review |
-| "Refactor this" | using-git-worktrees → writing-plans → TDD |
-
-## Verification Protocol
-
-Every skill requires verification before reporting completion:
-
-1. **Code runs** without errors
-2. **Output matches** expected result
-3. **Actual result checked** — not assumed
-4. **Build passes**
-5. **Explained** in one sentence
+This is `verification-loop` from `continuous-improvement`. It runs after every workflow stage, not just at the end.
 
 ## Integration
 
-Superpowers integrates with:
-- **continuous-improvement** — reflection and learning after each stage
-- **ralph** — autonomous execution of planned stories
-- **workspace-surface-audit** — verify environment before starting
+`/superpowers` integrates with:
+
+- **`/seven-laws`** — runs after each stage to capture the reflection block and update instincts (Laws 5 + 7)
+- **`/proceed-with-the-recommendation`** — orchestrates a list of recommendations end-to-end, using `/superpowers` per item
+- **`/workspace-surface-audit`** — runs at task start to confirm the right routing surface is actually present (Law 1 pre-flight)
+- **`/ralph`** — autonomous variant; takes a PRD and walks it story-by-story under the same routing table
 
-## Example Session
+## Example session
 
 ```
 User: "Build a checkout flow"
 
-[brainstorming activates]
+[/superpowers status] →
+  Sources: continuous-improvement [x], obra/superpowers [x], others [ ]
+  Routing intent: new-feature
+
+[brainstorming activates — obra/superpowers]
 AI: "Clarifying questions: 1) Payment provider? 2) Guest checkout?"
 
 User: "Stripe, yes guest checkout"
 
-[writing-plans activates]
+[using-git-worktrees activates — obra/superpowers]
+AI: "Created worktree at ../checkout-feature"
+
+[writing-plans activates — obra/superpowers]
 AI: "Plan created with 6 tasks. Approve?"
 
 User: "Approved"
 
-[using-git-worktrees activates]
-AI: "Created worktree at ../checkout-feature"
+[tdd-workflow activates — continuous-improvement]
+AI: "Task 1 RED: write failing test for cart validation..."
+AI: "Task 1 GREEN: minimal handler. Verifying with `npm test cart.test.ts`..."
+AI: "Task 1 REFACTOR: extract validator, tests still green. Committing."
+
+[verification-loop activates — continuous-improvement]
+AI: "Build [x] Types [x] Lint [x] Tests 42/42 [x] Security scan clean [x]"
 
-[test-driven-development activates]
-AI: "Task 1: Write failing test for cart validation..."
+[finishing-a-development-branch activates — obra/superpowers]
+AI: "Options: merge / PR / keep / discard?"
 ```

package/commands/workspace-surface-audit.md

@@ -1,77 +1,77 @@
----
-name: workspace-surface-audit
-description: "Audit workspace capabilities and recommend continuous-improvement-native skills, hooks, and workflows"
----
-
-# /workspace-surface-audit
-
-Audit the active repo, MCP servers, plugins, connectors, env surfaces, and harness setup. Returns a 5-section report with specific next moves.
-
-## Usage
-
-```
-/workspace-surface-audit
-```
-
-## What It Checks
-
-1. **Repo surface** — `package.json`, lockfiles, framework config, `.mcp.json`, `.claude/settings*.json`, `AGENTS.md`
-2. **Environment surface** — `.env*` files (key names only, no secrets)
-3. **Connected tools** — installed plugins, MCP servers, LSPs, app integrations
-4. **continuous-improvement surface** — existing skills, commands, hooks, agents
-
-## Output Format
-
-```
-=== Workspace Surface Audit ===
-
-## Current Surface
-- [What is usable right now]
-
-## Parity
-- [Where continuous-improvement matches or exceeds benchmarks]
-
-## Primitive-Only Gaps
-- [Tools exist, but continuous-improvement lacks clean operator skills]
-
-## Missing Integrations
-- [Capabilities not available yet]
-
-## Top 3-5 Next Moves
-1. [Concrete continuous-improvement-native addition]
-2. [Ordered by impact]
-```
-
-## Rules
-
-- **Never print secrets** — only provider names, capability names, file paths
-- **Prefer continuous-improvement** over generic "install another plugin" advice
-- **Organize by workflows**, not API brands
-- **Specific recommendations** — concrete enough to implement without another discovery pass
-
-## Example Output
-
-```
-## Current Surface
-- MCP: filesystem, github, playwright
-- Plugins: beginner, expert (continuous-improvement)
-- Env: STRIPE_API_KEY, FAL_KEY configured
-- Framework: Next.js 15, React 19, TypeScript
-
-## Parity
-- Continuous improvement: covered (native)
-- Testing discipline: covered (TDD workflows)
-
-## Primitive-Only Gaps
-- Stripe connected but no billing-operator skill
-- GitHub MCP available but no issue-triage workflow
-
-## Missing Integrations
-- No Linear connector detected
-- No Slack webhook configured
-
-## Top 3-5 Next Moves
-1. Create billing-operator skill (Stripe integration)
-2. Create github-ops workflow for issue triage
-3. Add Linear connector skill for project management
-```
+---
+name: workspace-surface-audit
+description: "Audit workspace capabilities and recommend continuous-improvement-native skills, hooks, and workflows"
+---
+
+# /workspace-surface-audit
+
+Audit the active repo, MCP servers, plugins, connectors, env surfaces, and harness setup. Returns a 5-section report with specific next moves.
+
+## Usage
+
+```
+/workspace-surface-audit
+```
+
+## What It Checks
+
+1. **Repo surface** — `package.json`, lockfiles, framework config, `.mcp.json`, `.claude/settings*.json`, `AGENTS.md`
+2. **Environment surface** — `.env*` files (key names only, no secrets)
+3. **Connected tools** — installed plugins, MCP servers, LSPs, app integrations
+4. **continuous-improvement surface** — existing skills, commands, hooks, agents
+
+## Output Format
+
+```
+=== Workspace Surface Audit ===
+
+## Current Surface
+- [What is usable right now]
+
+## Parity
+- [Where continuous-improvement matches or exceeds benchmarks]
+
+## Primitive-Only Gaps
+- [Tools exist, but continuous-improvement lacks clean operator skills]
+
+## Missing Integrations
+- [Capabilities not available yet]
+
+## Top 3-5 Next Moves
+1. [Concrete continuous-improvement-native addition]
+2. [Ordered by impact]
+```
+
+## Rules
+
+- **Never print secrets** — only provider names, capability names, file paths
+- **Prefer continuous-improvement** over generic "install another plugin" advice
+- **Organize by workflows**, not API brands
+- **Specific recommendations** — concrete enough to implement without another discovery pass
+
+## Example Output
+
+```
+## Current Surface
+- MCP: filesystem, github, playwright
+- Plugins: beginner, expert (continuous-improvement)
+- Env: STRIPE_API_KEY, FAL_KEY configured
+- Framework: Next.js 15, React 19, TypeScript
+
+## Parity
+- Continuous improvement: covered (native)
+- Testing discipline: covered (TDD workflows)
+
+## Primitive-Only Gaps
+- Stripe connected but no billing-operator skill
+- GitHub MCP available but no issue-triage workflow
+
+## Missing Integrations
+- No Linear connector detected
+- No Slack webhook configured
+
+## Top 3-5 Next Moves
+1. Create billing-operator skill (Stripe integration)
+2. Create github-ops workflow for issue triage
+3. Add Linear connector skill for project management
+```

package/hooks/gateguard.mjs

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+/**
+ * Runtime PreToolUse gateguard hook.
+ *
+ * Stdin  : JSON { tool_name, tool_input }
+ * Stdout : JSON { decision: "allow" | "block", reason?: string }
+ * Exit   : 0 always (decision is in stdout, fail-open on parse error).
+ *
+ * Three-stage gate per skills/gateguard.md:
+ * - DENY  : first mutating tool call per file, with fact-list reason
+ * - FORCE : agent presents facts (model-side; out of band)
+ * - ALLOW : retry once `_gateguard_facts_presented: true` is set or the
+ *           per-file marker is recorded in session state
+ *
+ * Read-only and exploratory tools (Read, Grep, Glob, routine Bash) bypass
+ * unconditionally. Destructive Bash gates EVERY call, not just first.
+ *
+ * V1 honest limitations (see src/lib/gateguard-state.mts header):
+ *   honor-system flag, state-file deletion, parallel-hook race.
+ *
+ * MultiEdit handling (V1): gates on edits[0].file_path only. Per-file
+ * batching is not implemented — TODO: extend to gate every entry in
+ * edits[]. Tracked in issue #106 acceptance criteria item 5.
+ */
+import { readFileSync } from "node:fs";
+import { isCapReached, loadState, markFileCleared, resolveSessionDir, saveState, } from "../lib/gateguard-state.mjs";
+const TOOL_ROUTE = {
+    Read: "allow",
+    Grep: "allow",
+    Glob: "allow",
+    LS: "allow",
+    NotebookRead: "allow",
+    Write: "mutating-file",
+    Edit: "mutating-file",
+    MultiEdit: "mutating-file",
+    NotebookEdit: "mutating-file",
+    Bash: "allow",
+};
+const DESTRUCTIVE_PATTERNS = [
+    "rm -rf",
+    "rm -fr",
+    "git reset --hard",
+    "git push --force",
+    "git push -f",
+    "--force-with-lease",
+    "git branch -D",
+    "drop table",
+    "drop database",
+    "drop schema",
+    "truncate ",
+    "mkfs",
+    "dd if=",
+    "format ",
+    "rmdir /s",
+    "del /f /q",
+    "del /q /f",
+    "Remove-Item -Recurse",
+    "Remove-Item -Force",
+];
+function isDestructiveBash(command) {
+    const lower = command.toLowerCase();
+    return DESTRUCTIVE_PATTERNS.some((p) => lower.includes(p.toLowerCase()));
+}
+function classifyTool(toolName, toolInput) {
+    const route = TOOL_ROUTE[toolName] ?? "allow";
+    if (route !== "allow")
+        return route;
+    if (toolName === "Bash" && typeof toolInput.command === "string") {
+        if (isDestructiveBash(toolInput.command))
+            return "destructive-bash";
+    }
+    return "allow";
+}
+function extractFilePath(toolInput) {
+    if (typeof toolInput.file_path === "string")
+        return toolInput.file_path;
+    // MultiEdit V1: first edit's file_path is the canonical key.
+    if (Array.isArray(toolInput.edits) && toolInput.edits.length > 0) {
+        const first = toolInput.edits[0];
+        if (first && typeof first.file_path === "string")
+            return first.file_path;
+    }
+    if (typeof toolInput.command === "string")
+        return toolInput.command;
+    return "";
+}
+function buildMutatingFileReason(toolName, filePath) {
+    return [
+        `Before ${toolName === "Write" ? "creating" : "editing"} ${filePath || "<unknown>"}, present these facts:`,
+        "",
+        "  1. List ALL files that import/require this file (use Grep)",
+        "  2. List the public functions/classes affected by this change",
+        "  3. If this file reads/writes data files, show field names, structure, and date format",
+        "  4. Quote the user's current instruction verbatim",
+        "",
+        "After presenting the facts, retry with `_gateguard_facts_presented: true` in tool_input,",
+        "or with the same file_path after a previous clearance has been recorded for this session.",
+    ].join("\n");
+}
+function buildDestructiveBashReason(command) {
+    return [
+        `Destructive command requested: ${command}`,
+        "",
+        "  1. List ALL files/data this command will modify or delete",
+        "  2. Write a one-line rollback procedure",
+        "  3. Quote the user's current instruction verbatim",
+        "",
+        "Destructive Bash gates EVERY call — clearance is not cached.",
+    ].join("\n");
+}
+function buildCapReachedReason() {
+    return [
+        "Gateguard session clearance cap reached (50 distinct files).",
+        "Start a new Claude Code session to reset the gate. The cap exists to bound",
+        "stuck-loop or rogue-agent clearance from compounding within a single session.",
+    ].join("\n");
+}
+function emit(decision) {
+    process.stdout.write(`${JSON.stringify(decision)}\n`);
+    process.exit(0);
+}
+function main() {
+    let raw = "";
+    try {
+        raw = readFileSync(0, "utf8");
+    }
+    catch {
+        emit({ decision: "allow" });
+        return;
+    }
+    let payload;
+    try {
+        payload = JSON.parse(raw);
+    }
+    catch {
+        emit({ decision: "allow" }); // fail-open
+        return;
+    }
+    const toolName = typeof payload.tool_name === "string" ? payload.tool_name : "";
+    const toolInput = payload.tool_input ?? {};
+    const gate = classifyTool(toolName, toolInput);
+    if (gate === "allow") {
+        emit({ decision: "allow" });
+        return;
+    }
+    if (gate === "destructive-bash") {
+        const cmd = typeof toolInput.command === "string" ? toolInput.command : "";
+        emit({ decision: "block", reason: buildDestructiveBashReason(cmd) });
+        return;
+    }
+    // mutating-file
+    const sessionDir = resolveSessionDir();
+    const state = loadState(sessionDir);
+    const filePath = extractFilePath(toolInput);
+    const factsFlagged = toolInput._gateguard_facts_presented === true;
+    const alreadyCleared = filePath !== "" && filePath in state.cleared_files;
+    if (!factsFlagged && !alreadyCleared) {
+        emit({ decision: "block", reason: buildMutatingFileReason(toolName, filePath) });
+        return;
+    }
+    if (factsFlagged && !alreadyCleared) {
+        if (isCapReached(state)) {
+            emit({ decision: "block", reason: buildCapReachedReason() });
+            return;
+        }
+        if (filePath !== "") {
+            saveState(sessionDir, markFileCleared(state, filePath));
+        }
+    }
+    emit({ decision: "allow" });
+}
+main();