agent-guardrails 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,335 @@
+# Agent Guardrails
+
+Ship AI-written code with production guardrails.
+
+`agent-guardrails` is a zero-dependency CLI for teams that want coding agents to work like disciplined contributors instead of improvisational code generators. It adds repo-local memory, task contracts, and production-shaped validation around agent workflows so changes stay smaller, more testable, risk-aware, and easier to review.
+
+## Why this exists
+
+Coding agents usually fail in predictable ways:
+
+- they invent abstractions that do not match the repo
+- they change too many files at once
+- they skip tests when behavior changes
+- they ignore project-specific rules unless those rules are explicit and easy to load
+
+`agent-guardrails` gives repos a small, practical workflow:
+
+1. `init` seeds repo-local instructions and templates
+2. `plan` writes a bounded task contract
+3. `check` validates scope, consistency, correctness, and review or risk signals
+
+## 60-Second Quick Start
+
+```bash
+npm install -g agent-guardrails
+agent-guardrails init . --preset node-service --adapter openclaw --lang en
+agent-guardrails plan --task "Add refund status transitions to the order service" --allow-paths "src/,tests/" --intended-files "src/orders/refund.js,tests/refund.test.js" --allowed-change-types "implementation-only" --required-commands "npm test" --evidence ".agent-guardrails/evidence/current-task.md" --lang en
+agent-guardrails check --base-ref origin/main --commands-run "npm test" --review --lang en
+```
+
+If you do not want a global install, `npx agent-guardrails ...` works too.
+
+The CLI currently supports `en` and `zh-CN`. You can switch with `--lang zh-CN` or `AGENT_GUARDRAILS_LOCALE=zh-CN`.
+
+## What This Proves
+
+The flagship proof-of-value examples are:
+
+- the bounded-scope demo in [examples/bounded-scope-demo](./examples/bounded-scope-demo)
+- the first semantic pattern-drift demo in [examples/pattern-drift-demo](./examples/pattern-drift-demo)
+- the interface-drift demo in [examples/interface-drift-demo](./examples/interface-drift-demo)
+- the boundary-violation demo in [examples/boundary-violation-demo](./examples/boundary-violation-demo)
+- the source-test-relevance demo in [examples/source-test-relevance-demo](./examples/source-test-relevance-demo)
+- the pilot write-up in [docs/REAL_REPO_PILOT.md](./docs/REAL_REPO_PILOT.md)
+
+Together they show:
+
+- a narrow task contract can block out-of-scope changes before merge
+- required commands and evidence notes are part of the merge gate, not optional ceremony
+- the OSS baseline can stay green while a semantic pack adds a higher-signal consistency warning
+- the semantic layer can also block implementation-only work when it silently changes the public surface
+- the semantic layer can block a controller that crosses a declared module boundary even when the task contract still looks narrow
+- the semantic layer can tell the difference between "a test changed" and "the right test changed"
+- the same public CLI can surface deeper enforcement without splitting into a second product
+
+Run it with:
+
+```bash
+node ./examples/bounded-scope-demo/scripts/run-demo.mjs all
+```
+
+Then run the OSS benchmark suite:
+
+```bash
+npm run benchmark
+```
+
+And run the first semantic proof demo:
+
+```bash
+npm run demo:pattern-drift
+```
+
+Then run the interface drift proof demo:
+
+```bash
+npm run demo:interface-drift
+```
+
+Then run the boundary and source-to-test proof demos:
+
+```bash
+npm run demo:boundary-violation
+npm run demo:source-test-relevance
+```
+
+## Local Workflow
+
+Use this docs-first loop in day-to-day work:
+
+```bash
+agent-guardrails plan --task "Add audit logging to the release approval endpoint" --allow-paths "src/,tests/" --intended-files "src/release/approve.js,tests/release/approve.test.js" --allowed-change-types "implementation-only" --risk-level medium --required-commands "npm test,npm run lint" --evidence ".agent-guardrails/evidence/current-task.md"
+agent-guardrails check --base-ref origin/main --commands-run "npm test,npm run lint" --review
+```
+
+Keep a short evidence note at `.agent-guardrails/evidence/current-task.md` with:
+
+- task name
+- commands run
+- notable results
+- residual risk or `none`
+
+Example:
+
+```md
+# Task Evidence
+
+- Task: Add audit logging to the release approval endpoint
+- Commands run: npm test, npm run lint
+- Notable results: Tests and lint passed after updating the approval endpoint and audit assertions.
+- Residual risk: none
+```
+
+## CI and Automation Workflow
+
+For CI, hooks, or orchestrated agent runs, prefer machine-readable output:
+
+```bash
+agent-guardrails check --base-ref origin/main --json
+```
+
+If the workflow wants parity with locally reported commands, set:
+
+```text
+AGENT_GUARDRAILS_COMMANDS_RUN=npm test,npm run lint
+```
+
+The generated user-repo workflow template lives in [templates/base/workflows/agent-guardrails.yml](./templates/base/workflows/agent-guardrails.yml).
+The maintainer CI for this package lives in [guardrails.yml](./.github/workflows/guardrails.yml).
+
+## Production Baseline
+
+The current product direction is a generic, repo-local production baseline for AI-written code:
+
+- `plan` shapes the task before implementation with bounded paths, intended files, change-type intent, and risk metadata
+- `check` enforces small-scope, test-aware, evidence-backed, reviewable changes
+- `check --review` turns the same findings into a concise reviewer-oriented report
+
+This is intentionally generic-first. It relies on file-shape heuristics, repo policy, task contracts, and command/evidence enforcement rather than framework-specific AST logic.
+
+## Open Source vs Pro
+
+### Today
+
+The open-source core is already the product:
+
+- repo-local production baseline
+- smaller, more reviewable AI changes
+- stronger validation and risk visibility before merge
+- public benchmarks and cross-platform CI proof
+- active semantic proof points for pattern drift, interface drift, boundary violation, and source-to-test relevance
+
+### Next
+
+The next technical step is deeper enforcement behind the same CLI:
+
+- detector pipeline foundation
+- benchmarked proof-of-value
+- a repo-contained first TypeScript or JavaScript semantic pack under `plugins/plugin-ts/`
+- first active semantic proofs for pattern drift, interface drift, boundary violation, and source-to-test relevance
+- semantic analyzers for TypeScript or JavaScript first, Python second
+- broader real-repo pilots beyond the documented pilot
+
+### Paid
+
+Paid tiers should extend the baseline rather than replace it:
+
+- `Pro Local`: semantic packs, richer local review, and pattern-learning workflows
+- `Pro Cloud`: hosted review, shared policies, trend dashboards, and centralized governance
+
+Baseline merge-gate features stay open source.
+
+The first semantic pack lives publicly in this repo today as a proof point. It is positioned as the future `Pro Local` direction, not as a separate closed-source runtime.
+
+## Supported Agents
+
+| Tool | Seeded file | Local workflow support | Automation guidance support |
+| :-- | :-- | :-- | :-- |
+| Codex | `AGENTS.md` | Yes | Yes |
+| Claude Code | `CLAUDE.md` | Yes | Yes |
+| Cursor | `.cursor/rules/agent-guardrails.mdc` | Yes | Yes |
+| OpenHands | `.agents/skills/agent-guardrails.md` | Yes | Yes |
+| OpenClaw | `OPENCLAW.md` | Yes | Yes |
+
+## CLI Commands
+
+### `init`
+
+Seeds a repo with:
+
+- `AGENTS.md`
+- `docs/PROJECT_STATE.md`
+- `docs/PR_CHECKLIST.md`
+- `.agent-guardrails/config.json`
+- `.agent-guardrails/tasks/TASK_TEMPLATE.md`
+- `.github/workflows/agent-guardrails.yml`
+
+Example:
+
+```bash
+agent-guardrails init . --preset nextjs --adapter openclaw
+```
+
+### `plan`
+
+Prints a bounded implementation brief and writes a task contract by default.
+
+Example:
+
+```bash
+agent-guardrails plan --task "Add audit logging to the release approval endpoint" --allow-paths "src/,tests/" --intended-files "src/release/approve.js,tests/release/approve.test.js" --allowed-change-types "implementation-only" --risk-level medium --required-commands "npm test,npm run lint" --evidence ".agent-guardrails/evidence/current-task.md"
+```
+
+### `check`
+
+Runs baseline guardrail checks against the current repo and git working tree.
+
+Example:
+
+```bash
+agent-guardrails check --base-ref origin/main --commands-run "npm test,npm run lint" --review
+```
+
+For JSON output:
+
+```bash
+agent-guardrails check --base-ref origin/main --json
+```
+
+Minimal contract example:
+
+```json
+{
+  "schemaVersion": 3,
+  "task": "Add audit logging to the release approval endpoint",
+  "preset": "node-service",
+  "allowedPaths": ["src/", "tests/"],
+  "intendedFiles": ["src/release/approve.js", "tests/release/approve.test.js"],
+  "allowedChangeTypes": ["implementation-only"],
+  "riskLevel": "medium",
+  "requiredCommands": ["npm test", "npm run lint"],
+  "evidencePaths": [".agent-guardrails/evidence/current-task.md"]
+}
+```
+
+## Presets
+
+- `node-service`
+- `nextjs`
+- `python-fastapi`
+- `monorepo`
+
+Each preset adjusts file heuristics and recommended read-before-write paths while keeping the same mental model.
+
+## Adapters
+
+The core workflow is generic, but `agent-guardrails` ships first-pass adapters for:
+
+- [Codex](./adapters/codex/README.md)
+- [Claude Code](./adapters/claude-code/README.md)
+- [Cursor](./adapters/cursor/README.md)
+- [OpenHands](./adapters/openhands/README.md)
+- [OpenClaw](./adapters/openclaw/README.md)
+
+For Codex, the default `AGENTS.md` workflow is already the main integration surface, so `--adapter codex` is a docs-level adapter rather than an extra seeded file.
+
+## FAQ
+
+### Do I need all adapters?
+
+No. Use only the adapter that matches your coding tool. The core workflow still works without tool-specific seed files.
+
+### Do I need evidence files?
+
+Only when the task contract declares them. In the default docs-first workflow, the evidence note is intentionally lightweight and meant to record what actually happened.
+
+### When should I use `--json`?
+
+Use `--json` for CI, hooks, or automation that needs machine-readable results. For normal local work, the human-readable output is the intended default.
+
+## Current Limits
+
+This project is useful today as a repo-local guardrail layer, but it still has important limits:
+
+- the heuristics are still intentionally lightweight and may need tuning for larger repos
+- the semantic detectors are still string- and path-driven, not full AST or type-graph analyzers
+- module boundaries still depend on explicit repo policy instead of automatic architecture inference
+- source-to-test relevance is heuristic and should be treated as reviewer guidance plus contract enforcement, not coverage proof
+- CI users still need to choose their canonical base ref, such as `origin/main`
+- the current pilot is documented in [docs/REAL_REPO_PILOT.md](./docs/REAL_REPO_PILOT.md), and broader external pilots are still pending
+
+## Roadmap
+
+See [docs/ROADMAP.md](./docs/ROADMAP.md).
+
+## Strategy
+
+See [docs/PRODUCT_STRATEGY.md](./docs/PRODUCT_STRATEGY.md) for the current semantic-analysis direction, proof-of-value plan, and open-source versus paid product split.
+
+## Architecture
+
+See [docs/SEMANTIC_ARCHITECTURE.md](./docs/SEMANTIC_ARCHITECTURE.md).
+
+## Benchmarks
+
+See [docs/BENCHMARKS.md](./docs/BENCHMARKS.md).
+
+## Pilot
+
+See [docs/REAL_REPO_PILOT.md](./docs/REAL_REPO_PILOT.md).
+
+## Commercialization
+
+See [docs/COMMERCIALIZATION.md](./docs/COMMERCIALIZATION.md).
+
+## Chinese Docs
+
+- [Chinese Overview](./docs/zh-CN/README.md)
+- [Product Strategy (Chinese)](./docs/zh-CN/PRODUCT_STRATEGY.md)
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## Troubleshooting
+
+See [docs/TROUBLESHOOTING.md](./docs/TROUBLESHOOTING.md).
+
+## Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md).
+
+## License
+
+MIT

package/adapters/README.md

@@ -0,0 +1,18 @@
+# Adapters
+
+This directory holds small, tool-specific guidance for teams that want to use `agent-guardrails` from a particular coding agent or workflow surface.
+
+All adapter docs now use the same docs-first task loop:
+
+1. Run `plan` with `--allow-paths`, `--required-commands`, and `--evidence ".agent-guardrails/evidence/current-task.md"`.
+2. Implement inside the task contract.
+3. Update the evidence note with the task name, commands run, notable results, and residual risk or `none`.
+4. Run `check --commands-run ...` locally, or `check --json` in automation.
+
+## Available
+
+- [Codex](./codex/README.md)
+- [Claude Code](./claude-code/README.md)
+- [Cursor](./cursor/README.md)
+- [OpenHands](./openhands/README.md)
+- [OpenClaw](./openclaw/README.md)

package/adapters/claude-code/README.md

@@ -0,0 +1,38 @@
+# Claude Code Adapter
+
+Claude Code supports project memory via `CLAUDE.md`, so this adapter seeds a project-level memory file that points Claude Code at the `agent-guardrails` workflow.
+
+## Seeded file
+
+- `CLAUDE.md`
+
+## Recommended flow
+
+```bash
+agent-guardrails init . --preset node-service --adapter claude-code
+```
+
+Then:
+
+1. Launch Claude Code in the repo.
+2. Let it load `CLAUDE.md` and `AGENTS.md`.
+3. Run `agent-guardrails plan --task "<task>" --allow-paths "src/,tests/" --intended-files "src/file.js,tests/file.test.js" --allowed-change-types "implementation-only" --required-commands "npm test" --evidence ".agent-guardrails/evidence/current-task.md"`.
+4. Update `.agent-guardrails/evidence/current-task.md` with the task name, commands run, notable results, and residual risk or `none`, then finish with `agent-guardrails check --base-ref origin/main --commands-run "npm test" --review`.
+
+Example:
+
+```bash
+agent-guardrails plan --task "Add refund status transitions" --allow-paths "src/,tests/" --intended-files "src/orders/refund.js,tests/refund.test.js" --allowed-change-types "implementation-only" --required-commands "npm test" --evidence ".agent-guardrails/evidence/current-task.md"
+agent-guardrails check --base-ref origin/main --commands-run "npm test" --review
+```
+
+Use `agent-guardrails check --json` for CI or automation hooks, not as the main local developer loop.
+
+## Automation recipe
+
+```yaml
+- name: Run guardrails
+  env:
+    AGENT_GUARDRAILS_COMMANDS_RUN: npm test
+  run: agent-guardrails check --base-ref origin/${{ github.event.repository.default_branch }} --json > agent-guardrails-report.json
+```

package/adapters/codex/README.md

@@ -0,0 +1,39 @@
+# Codex Adapter
+
+Codex already uses `AGENTS.md` as a repository instruction surface, so the core `agent-guardrails` setup is enough for Codex to work well.
+
+## What to use
+
+- `AGENTS.md` for repo instructions
+- `docs/PROJECT_STATE.md` for short-term project memory
+- `.agent-guardrails/task-contract.json` for per-task scope
+
+## Recommended flow
+
+1. Initialize the repo with `agent-guardrails`.
+2. Ask Codex to read `AGENTS.md` and project state first.
+3. Run `agent-guardrails plan --task "<task>" --allow-paths "src/,tests/" --intended-files "src/file.js,tests/file.test.js" --allowed-change-types "implementation-only" --required-commands "npm test" --evidence ".agent-guardrails/evidence/current-task.md"`.
+4. Implement within the task contract and keep `.agent-guardrails/evidence/current-task.md` updated with the task name, commands run, notable results, and residual risk or `none`.
+5. Run `agent-guardrails check --base-ref origin/main --commands-run "npm test" --review`.
+
+Example:
+
+```bash
+agent-guardrails plan --task "Add refund status transitions" --allow-paths "src/,tests/" --intended-files "src/orders/refund.js,tests/refund.test.js" --allowed-change-types "implementation-only" --required-commands "npm test" --evidence ".agent-guardrails/evidence/current-task.md"
+agent-guardrails check --base-ref origin/main --commands-run "npm test" --review
+```
+
+Use `agent-guardrails check --json` when Codex is being orchestrated by automation or CI, not as the default local workflow.
+
+## Automation recipe
+
+For GitHub Actions or another orchestrator, report the commands through `AGENT_GUARDRAILS_COMMANDS_RUN` and collect JSON output:
+
+```yaml
+- name: Run guardrails
+  env:
+    AGENT_GUARDRAILS_COMMANDS_RUN: npm test
+  run: agent-guardrails check --base-ref origin/${{ github.event.repository.default_branch }} --json > agent-guardrails-report.json
+```
+
+Codex does not need a separate adapter file today because `AGENTS.md` is already the primary repo-level instruction file.

package/adapters/cursor/README.md

@@ -0,0 +1,38 @@
+# Cursor Adapter
+
+Cursor supports repository rules in `.cursor/rules`, so this adapter seeds a project rule that reinforces the `agent-guardrails` workflow.
+
+## Seeded file
+
+- `.cursor/rules/agent-guardrails.mdc`
+
+## Recommended flow
+
+```bash
+agent-guardrails init . --preset node-service --adapter cursor
+```
+
+Then:
+
+1. Open the repo in Cursor.
+2. Let Cursor load the project rule alongside `AGENTS.md`.
+3. Run `agent-guardrails plan --task "<task>" --allow-paths "src/,tests/" --intended-files "src/file.js,tests/file.test.js" --allowed-change-types "implementation-only" --required-commands "npm test" --evidence ".agent-guardrails/evidence/current-task.md"`.
+4. Update `.agent-guardrails/evidence/current-task.md` with the task name, commands run, notable results, and residual risk or `none`, then finish with `agent-guardrails check --base-ref origin/main --commands-run "npm test" --review`.
+
+Example:
+
+```bash
+agent-guardrails plan --task "Add refund status transitions" --allow-paths "src/,tests/" --intended-files "src/orders/refund.js,tests/refund.test.js" --allowed-change-types "implementation-only" --required-commands "npm test" --evidence ".agent-guardrails/evidence/current-task.md"
+agent-guardrails check --base-ref origin/main --commands-run "npm test" --review
+```
+
+Use `agent-guardrails check --json` for automation or CI integrations, not as the primary local interaction.
+
+## Automation recipe
+
+```yaml
+- name: Run guardrails
+  env:
+    AGENT_GUARDRAILS_COMMANDS_RUN: npm test
+  run: agent-guardrails check --base-ref origin/${{ github.event.repository.default_branch }} --json > agent-guardrails-report.json
+```

package/adapters/openclaw/OPENCLAW.md

@@ -0,0 +1,35 @@
+# OpenClaw Instructions
+
+Use this repo with `agent-guardrails` as the shared workflow guardrail layer.
+
+## Read First
+
+Before editing, read:
+
+1. `AGENTS.md`
+2. `docs/PROJECT_STATE.md`
+3. `README.md`
+4. `adapters/openclaw/README.md`
+5. the target files for the task
+
+## Working Rules
+
+- Keep tasks small and reviewable.
+- Prefer the existing repo structure over new abstractions.
+- If the task scope is narrow, declare it with `agent-guardrails plan --allow-paths ... --required-commands "npm test" --evidence ".agent-guardrails/evidence/current-task.md"`.
+- If the task touches behavior, include tests and update `.agent-guardrails/evidence/current-task.md` with the task name, commands run, notable results, and residual risk or `none`.
+- Before finishing, run `agent-guardrails check --base-ref origin/main --commands-run "npm test"`.
+- Use `agent-guardrails check --json` for automation or CI, not as the primary local loop.
+
+## Default Task Pattern
+
+1. Read the repo state and the task brief.
+2. Run `agent-guardrails plan --task "<task>" --allow-paths "src/,tests/" --required-commands "npm test" --evidence ".agent-guardrails/evidence/current-task.md"`.
+3. Make the smallest implementation that fits the task contract.
+4. Update `.agent-guardrails/evidence/current-task.md` with the real commands run and results, then run `agent-guardrails check --base-ref origin/main --commands-run "npm test"`.
+5. Update `docs/PROJECT_STATE.md` if the next step changed.
+
+## Notes
+
+- If the task needs broader scope, update the task contract first.
+- If `check` fails, fix the scope or the tests before expanding the change.

package/adapters/openclaw/README.md

@@ -0,0 +1,41 @@
+# OpenClaw Adapter
+
+This is the smallest useful OpenClaw slice for `agent-guardrails`.
+
+It does not add a custom binary integration. Instead, it gives OpenClaw users a ready-to-use instruction template and a clear workflow for using the repo-local guardrails already in this project.
+
+## What it gives you
+
+- A repo-local instruction template in [OPENCLAW.md](./OPENCLAW.md)
+- A simple adoption flow that uses `init`, `plan`, and `check`
+- A documented path to task contracts and base-ref checks
+
+## Recommended flow
+
+1. Initialize the repo with `agent-guardrails`, ideally with `--adapter openclaw`.
+2. Use the OpenClaw instruction template to keep tasks bounded.
+3. Run `plan --allow-paths ... --intended-files ... --allowed-change-types "implementation-only" --required-commands "npm test" --evidence ".agent-guardrails/evidence/current-task.md"` to write a task contract for the current task.
+4. Update `.agent-guardrails/evidence/current-task.md` with the task name, commands run, notable results, and residual risk or `none`, then run `check --base-ref origin/main --commands-run "npm test" --review` before finishing.
+
+Example:
+
+```bash
+node ./bin/agent-guardrails.js init . --preset node-service --adapter openclaw
+node ./bin/agent-guardrails.js plan --task "Add refund status transitions" --allow-paths "src/,tests/" --intended-files "src/orders/refund.js,tests/refund.test.js" --allowed-change-types "implementation-only" --required-commands "npm test" --evidence ".agent-guardrails/evidence/current-task.md"
+node ./bin/agent-guardrails.js check --base-ref origin/main --commands-run "npm test" --review
+```
+
+Use `agent-guardrails check --json` when OpenClaw is being orchestrated by automation or CI, not as the default local loop.
+
+## Automation recipe
+
+```yaml
+- name: Run guardrails
+  env:
+    AGENT_GUARDRAILS_COMMANDS_RUN: npm test
+  run: agent-guardrails check --base-ref origin/${{ github.event.repository.default_branch }} --json > agent-guardrails-report.json
+```
+
+## Best fit
+
+OpenClaw works best here when it is used as the task-execution layer and `agent-guardrails` is the repo policy layer. That keeps the setup lightweight while still enforcing scope, test expectations, and CI-friendly diffs.

package/adapters/openhands/README.md

@@ -0,0 +1,38 @@
+# OpenHands Adapter
+
+OpenHands supports repository guidance through `.agents/skills`, so this adapter seeds a repo-level skill that tells OpenHands to use the `agent-guardrails` workflow.
+
+## Seeded file
+
+- `.agents/skills/agent-guardrails.md`
+
+## Recommended flow
+
+```bash
+agent-guardrails init . --preset node-service --adapter openhands
+```
+
+Then:
+
+1. Start OpenHands in the repo.
+2. Let it load the repo skill and `AGENTS.md`.
+3. Run `agent-guardrails plan --task "<task>" --allow-paths "src/,tests/" --intended-files "src/file.js,tests/file.test.js" --allowed-change-types "implementation-only" --required-commands "npm test" --evidence ".agent-guardrails/evidence/current-task.md"`.
+4. Update `.agent-guardrails/evidence/current-task.md` with the task name, commands run, notable results, and residual risk or `none`, then finish with `agent-guardrails check --base-ref origin/main --commands-run "npm test" --review`.
+
+Example:
+
+```bash
+agent-guardrails plan --task "Add refund status transitions" --allow-paths "src/,tests/" --intended-files "src/orders/refund.js,tests/refund.test.js" --allowed-change-types "implementation-only" --required-commands "npm test" --evidence ".agent-guardrails/evidence/current-task.md"
+agent-guardrails check --base-ref origin/main --commands-run "npm test" --review
+```
+
+Use `agent-guardrails check --json` for automation or CI orchestration, not as the main local workflow.
+
+## Automation recipe
+
+```yaml
+- name: Run guardrails
+  env:
+    AGENT_GUARDRAILS_COMMANDS_RUN: npm test
+  run: agent-guardrails check --base-ref origin/${{ github.event.repository.default_branch }} --json > agent-guardrails-report.json
+```

package/bin/agent-guardrails.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+import { runCli } from "../lib/cli.js";
+
+runCli(process.argv.slice(2)).catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`agent-guardrails: ${message}`);
+  process.exit(1);
+});