> ## Documentation Index > Fetch the complete documentation index at: https://docs.whyfile.dev/llms.txt > Use this file to discover all available pages before exploring further. # Team collaboration > changed, coverage, digest, drift, affirm, trust, and review-context — the PR/CI workflow commands. whyfile turns the tribal "why is the code like this?" into a layer that is queryable, PR-reviewable, and survives turnover. Three jobs a team gets for free (all LLM-free, \$0 at query time): * **Onboard.** A new hire runs `whyfile explain ` instead of interrupting a senior. * **Review.** `whyfile changed --base main` surfaces the intent a PR touches, so a reviewer sees the constraints a change is bound by; `whyfile review-context --base main` turns that into a brief an external reviewer like Codex can act on directly. * **Retain.** `whyfile coverage` shows which code has recorded intent and which is dark, and `whyfile digest` reports what was decided since a checkpoint. ### The PR check ```bash theme={null} git diff --name-only origin/main...HEAD | whyfile changed --format markdown ``` Maps each changed file to the intent that governs it (constraints and trade-offs first). It is informational by default (exit 0). Add `--fail-on-constraint` to turn it into a soft gate that exits 5 when a PR touches a file bound by a constraint, so the constraint gets a reviewer's acknowledgement. ### Coverage and digest ```bash theme={null} whyfile coverage --format text # golden fraction, intent debt, covered vs dark code whyfile digest --since last-run # what intent changed since the last run ``` `coverage` reports the **golden fraction** beside the coverage numbers: the share of intent that is trusted evidence (human-written: authored decision records, captured live decisions, and attested commit trailers / `# why:` comments; the numerator grows further as the confirmed tier lands) over total intent. It is partitioned by evidence class and never blended, so reconstructed intent is shown separately and never inflates the trusted count. Alongside it, `intent_debt` reports dark files and orphaned intent (intent that explains no code); stale decisions come from `drift` and disputes from the audit phase, reported as `null` here rather than a misleading zero. The **attested tier** is the zero-workflow capture channel: on every pipeline run (unless `--no-attest`), commit trailers (`Why:`/`Decision:`) and `# why:` code comments are ingested deterministically as `provenance: attested` intent nodes, anchored to the code they touch or annotate. This gives any repo a non-empty trusted layer on day one, with no new workflow to adopt. List them with `whyfile list-intent --provenance attested`. The **capture** subcommand records a decision at the moment of choosing, the cheapest time to capture ground truth: ```bash theme={null} whyfile capture --chosen "Use SQLite" --question "Which datastore?" \ --option "Use SQLite" --option "Use Postgres" --rationale "single-writer, zero-ops" \ --recommendation "Use SQLite" ``` It writes a `# Decision:` record to `docs/decisions/` (idempotent by slug) and merges a `provenance: captured` node into the graph, immediately queryable via `why`/`explain`/`list-intent --provenance captured`. The node is built through the same ingest path a committed record takes, so re-ingesting the record reproduces the identical node. If `--recommendation` differs from `--chosen`, the node records a `resolution_delta` capturing where the human overrode the agent. `--since last-run` needs at least two pipeline runs: the first run has no prior snapshot to diff against, so it writes none and `digest --since last-run` exits `2` with a clear message until a second run has happened. ### Drift and affirmation Recorded decisions rot silently when the code they explain changes underneath them. `affirm` stamps a decision as reviewed against the current code; `drift` flags any affirmed decision whose anchored code has changed since, so staleness is visible instead of silent. ```bash theme={null} whyfile affirm # "I reviewed this against the code; it still holds" whyfile drift --format text # decisions whose anchored code changed since affirming ``` `affirm` records a content fingerprint of the anchored code (symbol-level where the anchor names a function or class, file-level otherwise) into `intent-affirmations.json`, a small human-owned ledger you commit. `drift` recomputes those fingerprints and reports four buckets: needs-reaffirmation (affirmed, but the code moved), expired-assumptions (see below), never-affirmed (anchored, staleness unknown), and orphaned (a ledger entry for a decision no longer in the graph). It is deterministic, LLM-free, and informational (exit 0); re-affirming a flagged decision clears it. Assumptions are the other decay mechanism: most stale intent is stale because an assumption quietly expired. A record's `## Assumptions` section (see `docs/adr/TEMPLATE.md`) is ingested into authored `assumption` intent nodes, each with an optional review-by date: ```bash theme={null} whyfile list-intent --kind assumption # the facts your decisions bet on whyfile drift --as-of 2026-12-31 # what is overdue for review by that date ``` An assumption past its review-by date surfaces in `drift` as an expired assumption, prompting you to revisit the decision that rests on it. `--as-of` defaults to today; pass a future date to see what will be overdue by then. Because assumptions are first-class intent nodes, `explain ` and `why "..."` also answer "which assumption governs this path?" during incident triage. ### Trust lifecycle Trust is a lifecycle, not a label. `trust` resolves each intent node's current state: it rises through `provisional` (reconstructed, unverified), `corroborated`, `confirmed` (survived an audit), and `affirmed` (a human signed off), and falls to `stale` (affirmed but the code drifted since), `disputed`, `superseded` (a newer record replaced it), or `orphaned` (its anchored code was deleted). ```bash theme={null} whyfile trust --format text # every node's state, counted by state whyfile trust --set confirmed --by panel # record a court verdict (who/what/when) ``` States are derived deterministically from the graph plus the affirmation ledger plus a recorded verdict log (`intent-trust.json`), so they are stable across re-runs. Structural facts (superseded, orphaned) win over promotions, and a human `affirm` outranks a panel verdict. Recording a verdict appends to the log with the actor and timestamp; it never edits the graph. Superseded and orphaned states are detected automatically from the graph; confirmed and disputed come from recorded verdicts — by hand via `--set`, or auto-recorded by `whyfile audit --record` (see above). ### Roadmap Cached Pass B anchoring (to make per-PR updates truly diff-proportional) and `--since` pipeline scoping are planned. ### Feeding intent to external reviewers: `review-context` `whyfile review-context [--base ] [--files ...] [--format json|markdown|focus]` emits a diff-scoped **intent brief**: for the changed files, the recorded decisions and constraints that govern them, each tagged with its provenance tier (`authored`/`reconstructed`) and resolved trust state, plus the constraints with no superseding record in the changeset. It is LLM-free — a projection over `intent-diff` joined with trust state. It exists so an external code reviewer (e.g. Codex, which auto-reads `AGENTS.md`) can weight its findings by recorded intent: a diff that violates a *blocking* constraint (kind=constraint, trust `authored`/`affirmed`/`corroborated`/`confirmed`) with no superseding decision record is a blocking finding; reconstructed or disputed intent is advisory. `--format focus` emits a compact, budgeted paragraph for injection as reviewer focus text; `markdown` (default) is the full block; `json` is the structured object. This is **not** a gate — it exits `0`/`2` only, never `EXIT_POLICY`. ```bash theme={null} whyfile review-context --base main # brief vs the default branch, markdown whyfile review-context --files src/auth.py --format focus # compact focus text for one file whyfile review-context --install # drop the reviewer pointer into AGENTS.md ```