Docs

Everything here is written for someone who has never seen chaff and is deciding, in about ninety seconds, whether it is serious.

Install

git clone https://github.com/jamessuuu/chaff
cd chaff
pnpm install
pnpm --filter chaff build

chaff is pre-release and not on npm yet, so this workspace-local build is the only way to run it today. See the quickstart for the first real analysis.

Where to go next

Quickstart →
Five minutes: install, write a small context file with one real problem, run chaff, read the finding.
Concepts →
Resident vs. on-demand vs. dropped, and why the chaff% numerator excludes heuristics and set-level aggregates.
Rule tiers →
Two tiers gate a build (enforced, heuristic); three evidence kinds explain why (measured, structural, unmeasured).
Rule admission pipeline →
SPEC §8: how a heuristic becomes a measured, enforced rule. Specified in full; not yet run in this build.
Failure modes →
What chaff does when an entry is missing, a glob matches nothing, a schema is malformed, or a run itself goes wrong.
Limitations →
Static analysis only. Ref-tokenizer estimates. False negatives preferred over false positives. Named plainly.

Also useful

The rule catalog is generated at build time from the committed registry: every id, tier, evidence kind, claim, and fix, including the graveyard. The case study runs chaff on a real, redacted context file, before and after a fix, with every number computed at build time. SPEC.md is the frozen design document these docs summarize; where they disagree, SPEC.md is binding.