Git hook and CI guardrails for AI-assisted software development.
Ripstop is a standalone npm package (@jonverrier/ripstop) published from its own repository. It runs policy checks at Git boundaries (commit, commit message, push, rebase, CI) for repos where Cursor, Claude Code, Codex, Amazon Q, or humans make changes: the same rules apply no matter who produced the diff.
It was developed for the Strong AI platform and works in any repository that installs the package and wires Git hooks.
It does not replace sandboxing, server-side branch protection, secret scanning, or code review. It does give you a consistent, repo-local enforcement layer, optional agent-readable summaries (RIPSTOP.md), and forensics so casual mistakes and “quietly weaken the guardrails” edits are much harder.
Invoke the CLI as ripstop (for example npx ripstop when the package is a devDependency).
Each check is configured under checks.<name> in .guardrails.yaml, with mode: off | warn | enforce, triggers, and check-specific options. Built-in presets (for example @jonverrier/ripstop/presets/internal-tooling) wire defaults; repos can extend or override.
| Check | What it enforces | Typical triggers |
|---|---|---|
pii |
Common PII patterns in files you commit (with exemptions). | pre-commit, ci |
path-guard |
Changes under protected globs need an approval trailer in the final commit message (e.g. CHANGE-APPROVED: TICKET-123). |
commit-msg, ci |
test-skip |
New or disallowed test-skip / disabled-test patterns; optional ticket requirement. | pre-commit, ci |
history-guard |
Force-push and remote branch delete on protected branch patterns. | pre-push only (Git supplies ref updates on stdin) |
ripstop-md-fresh |
Committed RIPSTOP.md exists and its embedded config hash matches the resolved .guardrails.yaml (including preset merge). |
pre-commit, ci |
reflog-witness |
Appends witness JSONL per run (branch, .guardrails.yaml hash and optional content on change, RIPSTOP.md hash, etc.). |
pre-commit, pre-push, pre-rebase, ci |
Further behaviour is in docs/ripstop-spec.md. Checks specified but not implemented yet are listed in docs/ripstop-roadmap-plan.md.
Use commit-msg for path-guard (and other trailer-based rules): Git has not finalized the message at pre-commit.
From 0.1.x onward, Ripstop can mirror resolved policy into Layer 1 (agent static context) so agents see active rules before they edit.
ripstop generate-md— WritesRIPSTOP.mdfrom merged config (local YAML +extends:presets). Commit it and reference it fromAGENTS.md/ harness manifests (docs/per-agent-config.md).- Per-agent formats —
--format claude,cursor,codex,qadjust framing; the config hash in the file is the same across formats soripstop-md-freshstays consistent. ripstop-md-fresh— Fails whenRIPSTOP.mdis missing or stale vs resolved config.- Flags —
--output,--check-fresh,--dry-run,--config.
Design notes: docs/ripstop-markdown-enhancement-spec.md.
npx ripstop generate-md
git add RIPSTOP.md0.2.x closes the gap where an agent could weaken .guardrails.yaml or generated docs in the same commit as “fixing” a failure.
path-guardpreset defaults — Presets add.guardrails.yaml,.guardrails/,RIPSTOP.md, and.claude/settings*.json(includingsettings.ripstop.json) toprotected_paths, with the same approval trailer as your other paths. Dedicated findings call out guardrails self-protection.RIPSTOP.md— Generated copy includes what you must not modify; optional Claude output adds harness-oriented deny rules.ripstop generate-md --format claude— Writes.claude/settings.ripstop.json; mergepermissions.denyinto your real.claude/settings.jsonper docs/per-agent-config.md.reflog-witness— Witness lines include.guardrails.yamlandRIPSTOP.mdhashes (and yaml content on change, within limits).ripstop recover --config-history— Prints witness history (optional--since,--config).
This is not tamper-proof against shell access and --no-verify. Details: docs/ripstop-self-protection-enhancement-spec.md.
npx ripstop recover --config-history
npx ripstop recover --config-history --since 2026-01-01T00:00:00.000Z- Findings — human or JSON (configurable).
reporting.audit_log— findings / bypasses (default.git/ripstop/audit.jsonl).reporting.witness_log— witness events (default.git/ripstop/witness.jsonl), includingreflog-witness.
Generated C4 docs for this repo (via @jonverrier/auto-doc):
- src/README.StrongAI.Component.md — package-level component view
- src/README.StrongAI.Context.md — package-level context view
Subdirectory docs exist under src/checks/, src/config/, etc.
| Document | Role |
|---|---|
| docs/ripstop-spec.md | Full product specification. |
| docs/ripstop-consumer-playbook.md | Adoption, hooks, governance, recovery. |
| docs/per-agent-config.md | Per-agent RIPSTOP.md wiring; Claude settings merge. |
| docs/ripstop-roadmap-plan.md | Shipped vs planned. |
| docs/ripstop-markdown-enhancement-spec.md | Design notes for generate-md / ripstop-md-fresh. |
| docs/ripstop-self-protection-enhancement-spec.md | Design notes for self-protection. |
Published to GitHub Packages as @jonverrier/ripstop.
npm install --save-dev @jonverrier/ripstopExample Husky wiring:
npx ripstop check --staged --trigger pre-commit
npx ripstop check --staged --trigger commit-msg --commit-msg-file "$1"
npx ripstop check --trigger pre-push
npx ripstop check --trigger pre-rebaserepo:
name: my-service
domain: tooling
tier: 2
extends: "@jonverrier/ripstop/presets/internal-tooling"
checks:
path-guard:
mode: enforce
triggers: [commit-msg, ci]
protected_paths:
- "infra/**"
- "migrations/**"
approval_trailer: "CHANGE-APPROVED"
test-skip:
mode: warn
triggers: [pre-commit, ci]The internal-tooling preset already includes self-protection paths, reflog-witness, ripstop-md-fresh, and history-guard. See src/presets/ for the full merged defaults.
ripstop check [--staged | --all | --diff <ref>] --trigger <trigger> [options]
ripstop generate-md [options]
ripstop recover --config-history [--since <iso>] [--config <path>]
ripstop list
ripstop explain <check> [--resolved]
ripstop version
--trigger: pre-commit, commit-msg, pre-push, pre-rebase, pre-action, ci.
npm install
npm run build
npm run test:ci
npm pack --dry-runThe package is designed to support Bun-compiled standalone binaries in a later milestone. Binary consumers can use built-in checks and YAML config. npm plugin checks and repo-local TypeScript checks expect a Node-compatible runtime.
MIT