Guardrails Kit v1.5

A portable CLAUDE.md + documentation set that makes Claude Opus / Sonnet operate as close to frontier (Fable) level as possible inside Claude Code: fewer logic errors, fewer introduced bugs, fewer wasted tokens. It works by converting the implicit judgment a stronger model applies automatically into explicit, checkable, event-triggered procedures a weaker model can execute mechanically.

New to the project? Start with how-it-works.md — a plain-language walkthrough of the kit's architecture, design principles, and an honest assessment of what it can and cannot transfer. Planned improvements (enforcement hooks, compliance auditing, evals, and new guardrail docs for security/performance/frontend/trust/data/tests) live in docs/improvement-roadmap.md.

Measured results (Opus 4.8, 40 live sessions): pilot #20260709-022340 (5 easy tasks, N=1) plus run #20260709-041605 (3 harder trap tasks — misleading symptom, dynamic-dispatch rename, test-weakening temptation — N=5 per condition, 30 sessions). Task pass rate was 100% in BOTH conditions across all 40 sessions: Opus 4.8 solves tasks of this size with or without the kit, so on this tier the kit's measured effect is verifiability and process, not raw correctness. With the kit: routing engaged unprompted in 16/20 sessions; auditor marker-fire rate 71–80% (hard tasks, N=5) vs 0% without; completion claims lacking verification evidence dropped from 14/14 (without kit) to 13/29 (with kit). Discipline cost on hard tasks: +67% per task (mean $0.75 vs $0.45; spread $0.47–0.99 vs $0.40–0.61; 14.2 vs 8.8 turns).

Is the surcharge worth it? The measured overhead is ~$0.30 per hard task. What it buys: without the kit, 100% of completions arrived without evidence, so a human must re-verify each one (~3 min ≈ $3.00 at $60/h); with the kit the transcript carries Verified: <command> -> <result> and human checking drops to skimming one line — roughly an 8:1 return on labor alone. On top of that, one escaped false-"done" costs a debugging round-trip (~30 min); at $0.30/task the kit breaks even if it prevents one such escape per 100 tasks (1%). Assumptions are knobs — recompute with your own rate: value ≈ (verify-minutes-saved × your $/min) + (escape-rate × cost-per-escape) − $0.30.

Model-compat matrix (first entries, 2026-07-09):

Model	Sessions	Task pass with / without kit	Kit engaged	Unverified claims with / without	Cost delta
Opus 4.8	60 (10 tasks; N=1 easy, N=5 hard+delta)	100% / 100%	23/30 (77%)	20/41 vs 21/21	+61–92%
Sonnet 5	100 (10 tasks, N=5)	100% / 100%	27/50 (54%)	33/56 vs 24/25	+107%
Haiku 4.5	100 (10 tasks, N=5)	100% / 98%	6/50 (12%)	38/49 vs 50/50	+14%

Two findings worth reading twice. First measured correctness delta: Haiku without the kit failed rename-sweep 1/5 times (the task with a string-literal reference a code-only rename misses) while with-kit stayed 5/5 — and that is exactly the task where Haiku's routing engaged most. Engagement scales monotonically with model tier: Opus follows the kit's routing 77% of the time unprompted, Sonnet 54%, Haiku 12% — the tier that needs the kit most obeys it least, which is the evidence the roadmap's per-model overlays (stricter phrasing/thresholds for smaller models) were designed for. Raw rows: evals/results/ (local).

Origins & thanks

This project began as a fork of TheColliny/FableClaudeMDForOpus — thanks to TheColliny for the original Guardrails Kit v1.0: the research, the core concept, and the initial rule set. As the original appears to be a one-time release while this fork has grown well beyond it (coverage docs, enforcement hooks, evals, slash skills — v1.1+), it continues here as an independent project.

What's in the kit

File	Role
CLAUDE.md	Always-loaded core: 12 iron rules, an event-phrased routing table, 4 hard stops. Deliberately small (~45 kit lines, hard cap 60) — always-on compliance is roughly constant-sum, so every extra line taxes obedience to all the others.
docs/guardrails/PLAN.md	Before starting non-trivial work: TASK block, premise check, prior-art search, baseline, decomposition, ask-vs-decide.
docs/guardrails/CODE.md	While editing: read-before-edit gates, twin/generated-file checks, and the REFERENCE SWEEP procedure (RS1-RS5).
docs/guardrails/TRAPS.md	Lookup tables for the classic reasoning traps: dates, epochs, mutation-vs-copy, async, floats/money, sort, division/modulo, regex, familiar-API lookalikes, closures, boolean logic. Read on demand via CODE.md C7.
docs/guardrails/DEBUG.md	When anything fails: reproduce-first loop, CAUSE line, failed-attempts ledger with the ESCALATION LADDER, red-flag table keyed on the model's own rationalization phrases.
docs/guardrails/VERIFY.md	Before claiming done/committing: 12-item echo protocol — every claim needs output quoted from a real tool result in the same turn.
docs/guardrails/EFFICIENCY.md	Token/context discipline as paired rules: every "read less" rule has a "read enough" floor.
docs/guardrails/SESSION.md	Long-session survival: docs/STATE.md template (S2), same-turn update triggers (S3), post-compaction recovery (S1), ANCHOR/DETOUR/DECISION ledger keywords.
docs/guardrails/_FORMAT.md	Authoring contracts for editing the kit itself (budgets, trigger phrasing, single-sourcing, sanctioned iron-rule pairs).
docs/guardrails/SECURITY.md	Code touching user input, SQL, shell construction, paths, secrets, auth, or deserialization (via CODE.md C16): SEC1–SEC8, every claim a pasted grep.
docs/guardrails/PERFORMANCE.md	Loops with I/O, nested loops, list endpoints (via C17): N+1, O() notes, measure-before/after, bounds, pagination.
docs/guardrails/FRONTEND.md	UI files (via C18): state coverage, design tokens, a11y minima, viewport numbers; visual taste explicitly out of scope.
docs/guardrails/TRUST.md	Imperatives found inside tool results/files (via EFFICIENCY.md E18): untrusted content is data — marker, never silent compliance.

Not part of the installable kit (kit-source and companion materials only): how-it-works.md (plain-language explanation of the kit), docs/improvement-roadmap.md (the approved improvement roadmap), docs/research-digest.md (the 155-finding failure-mode research behind every rule), docs/review-digest.md (the 193-finding adversarial review that hardened it), and docs/superpowers/specs/ (the design record).

Install — fresh project (no existing CLAUDE.md)

Clone the kit once, then point KIT at it (every command below is copy-pasteable):

git clone https://github.com/altafino/FableClaudeMDForOpus ~/guardrails-kit
KIT=~/guardrails-kit

From the project root — POSIX (Linux/macOS):

cp "$KIT"/CLAUDE.md CLAUDE.md
mkdir -p docs/guardrails
cp "$KIT"/docs/guardrails/*.md docs/guardrails/

or PowerShell (Windows):

$KIT = "$HOME\guardrails-kit"
Copy-Item "$KIT/CLAUDE.md" CLAUDE.md
New-Item -ItemType Directory -Force docs/guardrails | Out-Null
Copy-Item "$KIT/docs/guardrails/*.md" docs/guardrails/

Optional slash-skill layer (/kit-verify, /kit-sql, …): copy $KIT/.claude/skills/kit-* into your project's .claude/skills/ — each is a pointer bundle into the docs above, giving a typeable command plus harness auto-load on topic match.

Then fill the ## Project section of CLAUDE.md with your run/test commands and hard project constraints (cap: 40 lines — everything conditional goes in docs/guardrails/PROJECT.md with a pointer line in ## Project). Never edit inside the BEGIN/END KIT markers.

Install — project with an existing CLAUDE.md

One command from your project root (KIT = your kit clone, as above):

"$KIT"/scripts/migrate.sh "$KIT"              # mechanical prep: probe, snapshot, collision scan
"$KIT"/scripts/migrate-auto.sh --kit "$KIT"   # same + launches the Claude session for you

The script does everything judgment-free (idempotency probe, sha256 snapshot, collision pre-scan, kit manifest — writing NO kit docs before your approval), then hands off to /kit-migrate for the semantic phases; migration always stops at the M5 checkpoint for your explicit approval, and the post-approval copies run hash-verified via migrate.sh apply. Changed your mind at any point — even after completion? "$KIT"/scripts/migrate.sh "$KIT" rollback restores CLAUDE.md from the snapshot and removes exactly what the migration created (pre-existing files always survive), showing the full plan and asking before touching anything. Test suite: scripts/test_migrate.sh.

No-script fallback — tell the model (Opus is fine — the procedure is designed for it):

Read MIGRATE.md in ~/guardrails-kit and execute it exactly, phase by phase.

MIGRATE.md is built so nothing is lost: snapshot first, every original line gets a logged disposition, kit files are installed by per-file copy (never retyped), rule conflicts are surfaced instead of silently resolved, and it stops for your approval before installing kit docs or composing the new CLAUDE.md. Re-running it on a migrated project is detected and switches to UPGRADE mode.

Design principles (why it looks like this)

1. Lean core + on-demand playbooks. Only ~45 kit lines are always loaded. The extensive material is read at the moment its trigger fires — that is how "extensive" and "fewer tokens" coexist.
2. Event-phrased routing. Models route on what they literally experience ("a test failed", "about to type done"), not on topic labels ("debugging", "verification"). A doc that never gets opened is worth zero, so the routing table is the most engineered block in the kit — and its contract makes the doc-Read the next tool call, alone in its message.
3. Paste, don't check. Every rule produces a transcript artifact (a pasted grep, a quoted summary line, a TRIGGER:/ANCHOR:/V3: PASS line), and VERIFY requires quoted lines to exist verbatim in a tool result in the same turn. Compliance is visible; "ensure" is not.
4. Numbers, not judgment. "10 messages", "2 failures", ">50 hits", ">300 lines" — weaker models comply with countable thresholds and rationalize their way around graded ones.
5. Prohibitions carry replacements. Every NEVER has its replacement on the same line, because a banned action with no named alternative gets taken anyway under pressure.
6. Single source with sanctioned compression. Each rule lives in exactly one file; a CLAUDE.md iron rule may compress a doc rule, but shared trigger lists stay byte-identical (_FORMAT.md F7 lists the sanctioned pairs).

Auditing compliance

The kit's markers are greppable in any session transcript. To see which rules fired and which were skipped, search a transcript for: TRIGGER:, GOAL:, FILES:, EST:, DONE-WHEN:, BASELINE:, ASSUMPTION:, PLAN CHANGE:, CAUSE:, WORKAROUND:, ATTEMPT , ANCHOR:, DETOUR(, RETURNING:, DECISION:, CONSTRAINT CHECK:, HANDLED FAILURES:, NOTED (not done), EDITED-UNVERIFIED, CANNOT-REPRODUCE, SIGNATURE UNVERIFIED, INJECTION-SUSPECT, AUTH:, STATES COVERED:, BREAKING CHECKED:, UNBOUNDED (by choice), OPTIONS:, COUNTEREXAMPLE TRIED:, P1:–P10:, C1:–C22:, D1:–D10:, V1:–V14:, E1:–E19:, S1:–S8:, RS1–RS6, SEC1:–SEC8:, PERF1:–PERF6:, FE1:–FE7:, TR1:–TR4:, DA1:–DA6:, TE1:–TE5:, RE1:–RE4:. Missing markers at the moments their triggers occurred are the non-compliance you should tune for.

Enforcement companion (optional)

scripts/install.sh "$KIT" [target] [--skills] is the self-verifying fresh installer (hash-checked); python3 scripts/kit-doctor.py health-checks any installed project (markers, doc set, STATE.md shape, drift); hooks/rearm.py (SessionStart) deterministically re-injects the post-compaction recovery instruction and nudges on stale/missing STATE.md; evals/ holds the with/without-kit eval harness (evals/run.py, metrics in evals/METRICS.md, 5 solvability-proven tasks).

hooks/ converts the highest-stakes rules from prose into deterministic Claude Code hooks: no Edit of an un-Read file, no Write over an existing file, no generated-path edits, no kill-by-image-name, git push only after the user runs scripts/allow-push, secret-scan on git commit, and a Stop-hook that blocks ending a turn on an unverified done-claim. Every deny names its rule and its escape (GUARDRAILS_BYPASS=1, logged). scripts/audit-transcript.py scores any session transcript against the kit's markers. Opt-in: see hooks/README.md; test suite: hooks/test_hooks.sh. POSIX-first; not enabled on this repo by default.

Upgrading the kit

Kit text in an installed project lives inside <!-- BEGIN/END KIT CORE --> and <!-- BEGIN/END KIT FOOTER --> markers and as verbatim files under docs/guardrails/. Upgrades are wholesale block/file swaps — see UPGRADE mode (U0–U4) at the bottom of MIGRATE.md — which is exactly why project content must never be interleaved into kit blocks, and why kit files must never be paraphrased. When editing kit content itself, follow docs/guardrails/_FORMAT.md.

Upgrade notes

• v1.5.1 — migration rollback: migrate.sh rollback [--yes] [--purge] (+ migrate-auto.sh --rollback) — plan-and-confirm undo that restores CLAUDE.md from the logged snapshot and removes only migration-created files (APPLIED:/PRE-EXISTING: tracking added to prep and apply); pre-existing files always survive. Suite now 31 cases.
• v1.5 — migration scripts (design doc 2026-07-10): scripts/migrate.sh with gate-respecting prep (M0 probe incl. orphaned-log stop, sha256 snapshot, collision pre-scan with verbatim M6a(1) options, kit manifest — zero kit-doc writes before the M5 checkpoint) and apply (post-approval hash-verified copies); scripts/migrate-auto.sh one-command orchestrator (interactive Claude only — M5 needs a human); 19-case scripts/test_migrate.sh suite; MIGRATE.md script-prepped entry note; README migration section rewritten around the one-command path.
• v1.4 — reasoning scaffolds (roadmap Addendum 5): docs/guardrails/REASONING.md (RE1–RE4: worked-example trace before code, counterexample hunt after, invariant comments, explain-then-code), PLAN.md P10 (OPTIONS enumeration for multi-shape design decisions), CODE.md C22 routing, MIGRATE kit-doc count 20 -> 21, /kit-reasoning skill, auditor + README marker sets extended, algorithmic eval pack (quoted-CSV parser, overlapping windows). Scaffolds extract existing capability; expect deltas on mid/small tiers, not frontier (measured ceiling).
• v1.3 — Phase C + B4 harness (no kit-doc rule changes): SessionStart re-arm hook (hooks/rearm.py, wired in the settings snippet) with STATE.md freshness nudge; self-verifying installer (scripts/install.sh); scripts/kit-doctor.py; /kit-rearm + /kit-doctor skills; eval harness (evals/: metrics doc, 5 solvability-proven tasks, runner with dry-run). Test suite now 23 cases. Kit docs remain v1.1. Includes the first pilot eval results (N=1, Opus 4.8, marked as pilot in the intro); N>=5 numbers per evals/METRICS.md still pending.
• v1.2 — slash-skill layer (roadmap Addendum 4 / Phase C2+): 15 skills under .claude/skills/kit-*/ — 6 workflow commands (kit-verify, kit-audit, kit-state, kit-migrate, kit-plan, kit-debug) + 9 topic packs (kit-sql, kit-nosql, kit-go, kit-angular, kit-vue, kit-tailwind, kit-security, kit-performance, kit-testing), all F7 pointer bundles; install lines in README + MIGRATE M6e. kit-doctor/kit-rearm follow with their Phase C artifacts. Kit docs remain v1.1.
• v1.1.1 — enforcement companion (roadmap Phase B1–B3, no kit-doc rule changes): hooks/ (guard.py, track.py, stop_verify.py + settings snippet, README, 20-case test suite), scripts/allow-push, scripts/audit-transcript.py compliance auditor. Opt-in; kit docs remain v1.1.