guardrails-ref 1.2.0 → 1.2.1

package/examples/README.md

@@ -8,9 +8,14 @@ Reference guardrails you can add with `npx guardrails-ref add <name>`. Use `npx
 | `no-placeholder-credentials` | Fake or placeholder API keys instead of asking for real values |
 | `no-silent-error-handling` | Catching errors without surfacing them to the user |
 | `require-access-control` | Exposing sensitive data or admin actions without role checks |
+| `artifact-verification` | Destructive ops without plan.md and audit log |
+| `context-rotation` | Continuing in polluted context; reset when 80% full or 10+ errors |
 | `database-migrations` | Direct schema changes instead of migrations |
 | `no-destructive-commands` | `rm -rf`, `DROP TABLE`, `TRUNCATE` without approval |
+| `no-eval-or-dynamic-code` | eval(), new Function(), or dynamic code execution |
 | `no-new-deps-without-approval` | New packages without human confirmation |
+| `privilege-boundaries` | Touching node_modules, .git, lockfiles, .env without approval |
+| `require-commit-approval` | git commit or push without explicit user approval |
 | `no-hardcoded-urls` | Hardcoded API URLs, base URLs, endpoints |
 | `no-sudo-commands` | `sudo`, `su`, or root commands without approval |
 | `rate-limiting` | Runaway tool calls and API loops |

package/examples/artifact-verification/GUARDRAIL.md

@@ -0,0 +1,35 @@
+---
+name: artifact-verification
+description: Before destructive operations, generate a plan for human review and log actions to an audit trail. Apply when deleting, dropping, truncating, or modifying production.
+scope: project
+severity: critical
+triggers:
+  - "Deleting files or directories"
+  - "Dropping tables or databases"
+  - "Truncating data"
+  - "Production modifications"
+  - "Schema changes"
+license: MIT
+metadata:
+  author: agent-guardrails
+  version: "1.0"
+  source: https://guardrails.md/
+---
+
+# Artifact Verification
+
+## Trigger
+Before any destructive operation: deletes, drops, truncates, or production modifications.
+
+## Instruction
+- Generate a `plan.md` (or equivalent) describing all changes, affected paths, and impact
+- Present the plan for human approval before executing
+- Wait for explicit confirmation before proceeding
+- Log all actions to `audit.log` (or project-defined audit trail) with timestamp and scope
+- Never skip the plan step even if the user seems to approve verbally — require written confirmation or explicit approval in the plan
+
+## Reason
+Agents have executed destructive operations without a reviewable artifact. A plan provides rollback context and ensures humans can verify scope before irreversible changes. Audit logging enables post-incident analysis.
+
+## Provenance
+Based on guardrails.md Pattern 1: Artifact verification.

package/examples/context-rotation/GUARDRAIL.md

@@ -0,0 +1,34 @@
+---
+name: context-rotation
+description: When context exceeds 80% capacity or 10+ consecutive errors, save state, summarize, and reset to prevent "The Gutter" — agents repeating mistakes in polluted context.
+scope: session
+severity: warning
+triggers:
+  - "Context window approaching capacity"
+  - "Repeated identical errors"
+  - "Circular tool call loops"
+  - "10+ consecutive failures"
+license: MIT
+metadata:
+  author: agent-guardrails
+  version: "1.0"
+  source: https://guardrails.md/
+---
+
+# Context Rotation
+
+## Trigger
+Context exceeds 80% capacity, 10+ consecutive errors, repeated identical failures, or circular tool call loops.
+
+## Instruction
+- Save current state to `context-snapshot.md` (or equivalent) before resetting
+- Summarize key learnings and what was attempted
+- Reset the context window
+- Re-inject: GUARDRAILS.md + summary + original objective
+- Do not continue in polluted context — rotation prevents recursive failure loops
+
+## Reason
+Agents feed outputs back into context. When it fills with error logs and failed attempts, the agent prioritizes recent failures over original instructions and enters "The Gutter" — repeating the same mistakes indefinitely. Rotation breaks the loop.
+
+## Provenance
+Based on guardrails.md Pattern 2: Context rotation.

package/examples/no-eval-or-dynamic-code/GUARDRAIL.md

@@ -0,0 +1,34 @@
+---
+name: no-eval-or-dynamic-code
+description: Never use eval(), new Function(), or similar dynamic code execution. Prevents code injection and security vulnerabilities.
+scope: project
+severity: critical
+triggers:
+  - "Executing user input"
+  - "Dynamic code execution"
+  - "JSON parsing to code"
+  - "eval"
+  - "Function constructor"
+license: MIT
+metadata:
+  author: agent-guardrails
+  version: "1.0"
+---
+
+# No Eval or Dynamic Code
+
+## Trigger
+Considering `eval()`, `new Function()`, `setTimeout(string)`, `setInterval(string)`, or any mechanism that executes a string as code.
+
+## Instruction
+- Never use `eval()` — use `JSON.parse()` for JSON, proper parsers for other formats
+- Never use `new Function(body)` or `Function(arg1, arg2, body)` with dynamic body
+- Never pass user input to `setTimeout`, `setInterval`, or `vm.runInContext` as executable code
+- For dynamic behavior: use lookup tables, strategy pattern, or safe configuration — not code-as-string
+- If the user requests "eval" or "dynamic execution": explain the security risk and suggest alternatives
+
+## Reason
+Dynamic code execution with user or external input enables code injection. Attackers can escape strings and execute arbitrary code. Use structured data and safe parsing instead.
+
+## Provenance
+OWASP, common security guidance for handling untrusted input.

package/examples/no-plaintext-secrets/GUARDRAIL.md

@@ -25,6 +25,7 @@ Implementing authentication endpoints, adding logging, integrating third-party A
 - Use bcrypt with 12 salt rounds for password hashing
 - Always require HTTPS for authentication endpoints
 - Use a `redactSensitive()` helper when logging objects that may contain secrets
+- Audit all logs before committing to ensure no credentials are included
 
 ## Reason
 API keys were exposed in git during a 2025 security audit. Plaintext credentials in logs led to emergency key rotation.

package/examples/privilege-boundaries/GUARDRAIL.md

@@ -0,0 +1,34 @@
+---
+name: privilege-boundaries
+description: Define what paths and resources the agent can read or write. Never touch node_modules, .git, or production config without explicit approval.
+scope: project
+severity: critical
+triggers:
+  - "File system operations"
+  - "Reading or writing files"
+  - "Modifying config"
+  - "Accessing dependencies"
+license: MIT
+metadata:
+  author: agent-guardrails
+  version: "1.0"
+  source: https://guardrails.md/
+---
+
+# Privilege Boundaries
+
+## Trigger
+Any file system read/write, config modification, or access to project directories.
+
+## Instruction
+- **Forbidden (never touch without explicit approval):** `node_modules/`, `.git/`, `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `.env`, `.env.*`, production config files
+- **Read-only unless instructed:** Database migrations, CI config (`.github/`, `.gitlab-ci.yml`), deployment config
+- **Allowed for normal edits:** Source code (`src/`, `lib/`), tests (`test/`, `__tests__/`), docs, project config files
+- When in doubt, ask before modifying files outside the current task scope
+- If the user requests changes to forbidden paths, stop and confirm scope before proceeding
+
+## Reason
+Agents have corrupted `node_modules`, overwritten lockfiles, and exposed secrets by modifying `.env`. Explicit boundaries prevent accidental damage to dependency state and version control.
+
+## Provenance
+Based on guardrails.md Pattern 3: Privilege boundaries.

package/examples/require-commit-approval/GUARDRAIL.md

@@ -0,0 +1,33 @@
+---
+name: require-commit-approval
+description: Never run git commit or git push without explicit user approval. Show diff, wait for confirmation before committing.
+scope: project
+severity: critical
+triggers:
+  - "Committing changes"
+  - "git commit"
+  - "git push"
+  - "Pushing to remote"
+license: MIT
+metadata:
+  author: agent-guardrails
+  version: "1.0"
+---
+
+# Require Commit Approval
+
+## Trigger
+About to run `git commit`, `git push`, or any operation that persists changes to version control.
+
+## Instruction
+- Never run `git commit` or `git push` without explicit user approval
+- Show the diff (or summary of changes) and ask for confirmation before committing
+- Wait for the user to confirm (e.g. "yes", "commit", "push") before executing
+- If the user says "commit my changes" or similar, still show what will be committed and get explicit approval
+- Prefer `git add` + show status, then wait — do not auto-commit
+
+## Reason
+Agents have committed incomplete work, wrong files, or broken code without the user reviewing. Unapproved commits pollute history and can push secrets or bugs to remotes.
+
+## Provenance
+Common failure mode in autonomous coding agents.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "guardrails-ref",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Validate and manage Agent Guardrails (GUARDRAIL.md) — init, add, remove, setup, validate, check, upgrade, list, why",
   "type": "module",
   "main": "dist/validate.js",