convez.ai
Agente
SihyeonJeon

why-was-fable-banned

SihyeonJeon/why-was-fable-banned

Ver no GitHub
BomPluginScore · de 0 a 100

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-banned

1 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

Estrelas
48
Forks
9
Acompanhando
1
Saúde
42%
Último commit
há 4 meses
Versão
v0.1.0
Issues abertas
0
Contribuidores
2

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.

license python Claude Code Codex tests

why-was-fable-banned

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.

demo: edit blocked until the spec passes, then applied

[!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.sh installs machine-wide: every Claude Code project on this computer (and every subagent / orchestrated worker) inherits the gate

  • sh install.sh --here installs 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):

    typescopepersists
    wfb off / wfb onthis project diracross sessions in this repo
    wfb off here / wfb on herethis session onlythis chat
    wfb off all / wfb on allthe whole machineeverywhere

    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 status shows 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 PreToolUse hook 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

  1. sh install.sh: wires the hooks at user level (every project + subagent inherits it)
  2. Prompt your agent to do real work: a gated task auto-starts
  3. The agent writes .wfb/spec.json (it's told exactly what to fill); edits stay blocked until it passes
  4. 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.

layercheckshow
gates/wfb_gate.pyform: fields, real paths, forbidden, fail-closeddeterministic, free
gates/wfb_judge.pymeaning: 0–2 rubric, gaming detectionoptional LLM judge
bench/correctness: hidden graderruns the tests

Benchmarks

Measured in this repo, reproducible (bash bench/run_quality.sh, bash tests/run_all.sh):

measuregate OFFgate ON
Decision record per changenoneenforced
Unspeced or forbidden-path edits reaching the repopossibleblocked
Adversarial / edge gate tests (downgrade, bypass, malformed, no-brick)n/a35/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.

Ver o original no GitHub

Bom para

Relacionados