Gouvernai

🛡️ 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

Reference files

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

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 a curl is malicious. Apply this detection when the conversation context suggests sensitive data is in play (credentials were recently accessed, .env files were read, secrets were discussed).

Gate process

IMPORTANT — Output efficiency: Every message adds cost. Combine steps into a single response. Keep reasoning brief. Do not narrate steps separately. Read GUIDE.md on the first gated action for output format templates.

Step 1 — Identify. List the actions matching trigger criteria. State what, where, and what data is involved.

Step 2 — Determine mode. Read guardrails-mode.json from the project root (CLAUDE_PROJECT_DIR). If the file exists, use the mode and audit_only fields. If the file does not exist, default to full gate (mode: "full-gate", audit_only: false). Mode values: full-gate (default), strict (all tiers +1), relaxed (T2 skips gate). If audit_only is true, T2 and T3 auto-proceed with logging; T4 halts without executing.

Step 3 — Classify. Read ACTIONS.md. Assign base tier (2, 3, or 4).

Step 4 — Escalate. Read TIERS.md. Apply escalation rules if applicable. Result is final tier.

Step 5 — Pre-approval. If action matches a known pre-approved pattern AND final tier < 4, log with "PRE-APPROVED" tag and proceed. If escalation raised the action to Tier 4, pre-approval is void.

Step 6 — Hard constraints. Read POLICY.md. If any NEVER rule is violated, BLOCK regardless of tier or approval.

Step 7 — Controls. Apply the universal control from TIERS.md for the final tier × mode.

Step 8 — Log and execute. Append to guardrails_log.md in the project root using the Write or Edit tool (never Bash echo/redirect — Bash triggers the obfuscation hook on $(date) substitution). Log: timestamp, tier, type, description, mode, outcome, approval, escalation reason. Execute or halt. Do NOT read back, display, or echo the log after writing. The log write is silent — never show log entries to the user unless they explicitly request /guardrails log.

SILENT LOGGING — NO EXCEPTIONS: After writing to the log, do NOT read the log file. Do NOT display log contents. Do NOT show "here are the latest entries." Do NOT cat, head, or tail the log. The write is completely invisible to the user. The ONLY time log entries are shown is when the user explicitly runs /guardrails log. Violating this rule wastes tokens and breaks the flow. If you find yourself about to show log entries after a gate action, STOP.

Note: Writes to guardrails_log.md are exempt from the gate.

Token cap (cost governance)

When token_cap is set in guardrails-mode.json, estimate the token cost of your planned action before executing.

What counts toward the estimate:

• File content being written (Write/Edit payload)
• Shell command length (Bash)
• For multi-step plans: sum the estimated tokens of all planned actions in the current turn

How to estimate: Use ~4 characters = 1 token as a rough heuristic.

When the estimate exceeds the cap:

• Apply T3 controls: pause, present the estimated token count and the cap to the user, wait for approval
• Format: 🛡️ **T3 — Token cap**: Estimated ~[N] tokens (cap: [cap]). [Brief description of planned actions]. Approve? (yes/no)
• Log with "TOKEN-CAP" tag

The hook layer also checks payload size deterministically. If the Write/Edit content or Bash command exceeds the cap, the hook prompts the user before the skill layer sees it. The skill layer adds coverage for multi-step plans where individual payloads are under the cap but the total exceeds it.

Token cap does not apply to:

• Guardrails internal file operations (log writes, mode config reads/writes)
• Read operations
• Actions where token_cap is null or not set

Actions not in the catalog

1. Does it match trigger criteria? If not, proceed normally.
2. If it triggers the gate, classify by analogy to the most similar listed action.
3. If no analogy fits, default to Tier 3.
4. Log with "UNLISTED" tag for future catalog updates.