Skip to main content

​
Configuring whyfile: the whyfile.config.json file

Every repo has a Makefile, a Dockerfile, a lockfile. This tool adds the missing one: a checked-in whyfile.config.json at repo root holds this repo’s own contract — where intent lives, and how strict the audit panel is — as a small hand-edited JSON file instead of a code change. Missing entirely is a no-op: every field falls back to today’s hardcoded default, byte-for-byte.
  • intent_sources.docs / intent_sources.records — the reconstruct pass’s --docs default and the decision-record ingest directories, so a whole team shares one source of truth without repeating --docs/--records on every invocation. An explicit CLI flag still wins over the whyfile.config.json.
  • convergence — the audit panel’s dispute thresholds (Audit in Gates): structural refutations auto-dispute, sharpen and note stay advisory. Tune this once you’ve measured the panel (see Panel evaluation) — never hand-picked without evidence.
A malformed contract (unknown key, wrong type, or thresholds that violate `structural >= sharpen
= note >= 1) fails loud rather than being silently ignored — a committed contract nobody reads is the exact dishonesty this tool exists to catch elsewhere. whyfile —doctor reports whether a whyfile.config.json is present and what it resolves to. This repo's own [whyfile.config.json`](../../whyfile.config.json) is the worked example. See ADR-0029.

​
Seeing what this actually captures

docs/decisions/ holds this repo’s everyday decision records (see its own README.md for the full open → resolved → promoted lifecycle). For a real, concrete example of a human overriding an agent’s recommendation, read keep-the-active-wrapper-deferred-the-passive-channel-is-suff.md. For the artifact rename this file itself just went through, see rename-whyfile-artifact-to-whyfile-config-json.md.