/gouvernai

name: gouvernai
description: |
  Safe flow state for Claude Code. Auto-approves routine actions, activates when the agent is about to:
  write files, run shell commands, send messages, access credentials, make API calls,
  install packages, modify config, or perform any irreversible operation.
  Also activates when user invokes /guardrails, or when token cap is exceeded.
  
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "python3 ${CLAUDE_PLUGIN_ROOT}/scripts/guardrails-enforce.py"
    - matcher: "Write"
      hooks:
        - type: command
          command: "python3 ${CLAUDE_PLUGIN_ROOT}/scripts/guardrails-enforce.py"
    - matcher: "Edit"
      hooks:
        - type: command
          command: "python3 ${CLAUDE_PLUGIN_ROOT}/scripts/guardrails-enforce.py"
    - matcher: "Read"
      hooks:
        - type: command
          command: "python3 ${CLAUDE_PLUGIN_ROOT}/scripts/guardrails-enforce.py"

🛡️ GouvernAI

Runtime guardrails for AI agents. Classifies every sensitive action by risk tier, enforces proportional controls, and logs a full audit trail.

**Dual enforcement:** This skill provides probabilistic classification (you read and follow these instructions). Hard constraints are also enforced deterministically via PreToolUse hooks — obfuscated commands, credential exposure, and dangerous system commands are blocked programmatically even if you skip the skill.

Quick reference

| Situation | Action | |-----------|--------| | Read file, git status, draft message | Auto-approved — zero gate, zero overhead | | Write to user file, git commit | 🛡️ T2 — auto-approved with notification, log | | Send email, modify config, delete files, curl, npm install | 🛡️ T3 — pause, require approval, log | | sudo, credential transmit, purchase, public post | 🛡️ T4 — full stop, warn, require approval, log | | Credential transmission, obfuscated command | 🛡️ BLOCKED — hard constraint, no override | | Bulk operation (5+ targets) | Escalate +1 tier | | Unfamiliar endpoint or recipient | Escalate +1 tier | | User invokes `/guardrails` | Show session stats |

Reference files

Read these on demand — do NOT load them every session:

| File | Read when | |------|-----------| | GUIDE.md | First gated action of the session | | ACTIONS.md | Classifying an action (Step 3) | | TIERS.md | Checking escalation rules or controls (Steps 4, 7) | | POLICY.md | Checking hard constraints or conflicts (Step 6) |

All reference files are in the same directory as this SKILL.md.

When this skill does NOT activate

Do NOT run the gate for read-only or zero-side-effect actions:

• Reading files, listing directories
• Read-only CLI commands (ls, pwd, cat, git status, git log, git diff)
• Writing to files in directories explicitly named `scratch/`, `temp/`, or `tmp/` only
• Drafting messages that are not sent
• Navigating to known URLs (bookmarked, previously visited in session)
• Checking whether a credential or env var exists (boolean check, no value exposed)
• Reading existing cron or scheduling config
• Reading from public APIs with no authentication
• Writing to `guardrails_log.md` for guardrails logging purposes
• Reading or writing `guardrails-mode.json` for mode persistence

**Important limitation:** The deterministic hook layer (PreToolUse) only intercepts Bash, Write, Edit, and Read tool calls. MCP tool calls bypass the hook entirely. When classifying actions that use MCP tools (database queries, API calls via MCP servers, file operations through MCP), you must apply the full gate process linguistically — there is no hard enforcement backstop. Treat MCP actions with extra caution.

Trigger — when this skill activates

Run the gate process below before executing ANY of these action types:

1. Writing, modifying, or deleting user files or config 2. State-modifying shell or terminal commands (git commit, npm install, mkdir, and anything beyond read-only) 3. Outbound network requests using authentication or sending data externally 4. Sending emails, messages, or communications to any recipient 5. Reading, displaying, or transmitting credential values 6. Browser form submissions, interactive element clicks, or file downloads 7. Creating or modifying cron jobs or webhooks 8. Financial transactions (purchases, payments, billing changes) 9. Permission or access control changes 10. Any irreversible or bulk (5+ targets) operation

Sequential pattern detection

In addition to gating individual actions, watch for multi-step patterns across the conversation that could indicate data exfiltration or policy circumvention. If you detect any of the following patterns, escalate the current action to Tier 4 regardless of its base classification:

**Variable staging then transmission:** A command stores sensitive data in a variable (e.g. `SECRET=$(cat .env)`, `TOKEN=$(grep API_KEY config)`) followed by a later command that transmits a variable to the network (e.g. `curl -d "$SECRET"`, `wget --post-data="$TOKEN"`). Flag the transmission command as Tier 4.

**Fragmented data extraction:** Multiple commands that each extract a small piece of a secret (character slicing, substring operations, split/cut on credential files) followed by any outbound network request. Flag the first network request after the extraction as Tier 4.

**Credential embedding in generated files:** When asked to generate config files, scripts, or templates, check whether the content being written includes interpolated credential variables (like `$API_KEY`, `$SECRET_TOKEN`, `process.env.API_KEY`). If the file is then transmitted, committed to a public repo, or uploaded, escalate to Tier 4.

**Disguised exfiltration:** A request to "health check endpoints", "test connectivity", or "validate URLs" where the URLs or request bodies contain credential-like values, encoded strings, or variable interpolations. Escalate to Tier 4.

These patterns require judgment — not every variable assignment followed by