why-was-fable-banned
SihyeonJeon/why-was-fable-banned
Spec-first, evidence-gated engineering-procedure enforcement for AI coding agents (Claude Code + Codex). The agent can't edit until it writes a passing spec.
Instalação
npx convez-ai SihyeonJeon/why-was-fable-banned1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
why-was-fable-banned
English · 한국어
Gate for AI coding agents: blocks edits until a spec passes.

The agent can't edit code until it writes .wfb/spec.json and a deterministic
gate accepts it: restated goal, non-goals, context chosen by authority, ≥2 rejected
alternatives with the boundary each breaks, risks, and runnable acceptance. One
shared gate, installed as hooks. Works in Claude Code and Codex.

[!NOTE] A spec must exist and pass before edits land, and unspeced or forbidden-path work never reaches your repo. Every change ships with an auditable decision record.
Install
git clone https://github.com/SihyeonJeon/why-was-fable-banned
cd why-was-fable-banned && sh install.sh
python3 only, stdlib. Remove: sh install.sh --uninstall.
Scope
-
sh install.shinstalls machine-wide: every Claude Code project on this computer (and every subagent / orchestrated worker) inherits the gate -
sh install.sh --hereinstalls for this repo only (Claude Code project-level.claude/settings.json) -
Toggle in-session at three scopes by typing (the hook handles it, never sent to the model):
type scope persists wfb off/wfb onthis project dir across sessions in this repo wfb off here/wfb on herethis session only this chat wfb off all/wfb on allthe whole machine everywhere Most-specific wins (session > project > machine > default on), so you can turn the project off and force one hard session on. State is a file, so it survives reboots until you flip it back.
wfb statusshows all three. One-off env bypass:WFB_BYPASS=1. -
Status line: when the gate is on,
[why-was-fable-banned]shows in the Claude Code status line (installed only if you don't already have one; otherwise the installer prints how to add the segment) -
Works wherever Claude Code runs: terminal, the VS Code and JetBrains extensions, desktop (they share the same hooks), plus Codex. It does not apply to non-Claude-Code/Codex agents (e.g. Cursor's own agent)
How it works
- Block: a
PreToolUsehook intercepts every edit and exits 2 until the spec passes - Spec: restated goal · non-goals · context by authority · ≥2 rejected alternatives · risks · runnable acceptance · forbidden paths
- Verify: "done" isn't done until each acceptance command shows live output (fail closed)
- Apply: on headless Codex the worker runs in a throwaway git worktree; only a gate-passing diff reaches your repo
Quickstart
sh install.sh: wires the hooks at user level (every project + subagent inherits it)- Prompt your agent to do real work: a gated task auto-starts
- The agent writes
.wfb/spec.json(it's told exactly what to fill); edits stay blocked until it passes - It implements, runs the acceptance commands, records evidence, then closes
Grade auto-scales the depth: typos (LIGHT) require only a restated goal + one acceptance check; auth/payments/migration (HEAVY) pay the full gate.
Supported agents
- Claude Code: native hooks, in-session block; the grade-specific contract is injected up front
- Codex:
wfb-codex-accept "<goal>" --repo <dir>(worktree-accept; headless)
Where the rules came from
Recorded real engineering sessions with hooks (42 traces), extracted them as a structured decision schema, generalized 19 into 8 decision axes, and cross-checked the generalization with a second model. Observable artifacts only: no chain-of-thought, local, secrets masked.
| layer | checks | how |
|---|---|---|
gates/wfb_gate.py | form: fields, real paths, forbidden, fail-closed | deterministic, free |
gates/wfb_judge.py | meaning: 0–2 rubric, gaming detection | optional LLM judge |
bench/ | correctness: hidden grader | runs the tests |
Benchmarks
Measured in this repo, reproducible (bash bench/run_quality.sh, bash tests/run_all.sh):
| measure | gate OFF | gate ON |
|---|---|---|
| Decision record per change | none | enforced |
| Unspeced or forbidden-path edits reaching the repo | possible | blocked |
| Adversarial / edge gate tests (downgrade, bypass, malformed, no-brick) | n/a | 35/35 pass |
Validated live: a Codex run left a protected file untouched and applied only the gate-passing diff; if verification is incomplete it retries, then rejects rather than apply. Details: bench/BENCHMARK.md · TOKEN_BUDGET.md.
License
PRs welcome. MIT.