why — which decision explains this file

decree why <file> maps a path to the decisions that govern it — before you edit a line. It is the first question to ask about unfamiliar code: why is this the way it is, and is my change allowed?

Scenario You're about to edit src/auth/tokens.py. Why are tokens hashed, not encrypted?

Without decree

You don’t know. So you git blame, open three stale PRs, grep the wiki, and ping a teammate who left last quarter. Twenty minutes gone, and you’re still guessing whether your change is allowed.

With decree

One command returns the exact governing decision, attached to the file:

$ decree why src/auth/tokens.py
src/auth/tokens.py — 1 governing decision

  ▸ SPEC-00000000000000000000000001  implemented  2026-05-10  exact
    JWT token storage
    governs: src/auth/tokens.py
→ exit 0

VALUE The reason behind the code is one query away — not buried in chat history or a teammate’s memory.

HONESTY why answers only from declared governs: frontmatter — never git, never semantic guessing. It cannot tell you the decision is still correct, only that it governs this path.

How it works

why queries decree’s provenance index for every decision whose governs: list covers the path you give it. An exact path match outranks a prefix (directory) match, and results are ordered by status priority, then most recent first. You can scope to a symbol with path#symbol. That’s the whole model: declared scope in, governing decisions out.

Run it

why <file>

Human-readable: the governing decision, its status, and its declared scope.

$ decree why src/auth/tokens.py
src/auth/tokens.py — 1 governing decision

  ▸ SPEC-00000000000000000000000001  implemented  2026-05-10  exact
    JWT token storage
    governs: src/auth/tokens.py
→ exit 0

why --json

The same answer as structured JSON, for an agent or a CI step to consume.

$ decree why src/auth/tokens.py --json
{
  "query": "src/auth/tokens.py",
  "match_count": 1,
  "matches": [
    {
      "decision_id": "SPEC-00000000000000000000000001",
      "type": "spec",
      "status": "implemented",
      "date": "2026-05-10",
      "title": "JWT token storage",
      "match_kind": "exact",
      "matched_path": "src/auth/tokens.py",
      "symbol": null
    }
  ]
}
→ exit 0

When nothing governs the path, that is a real answer — not a failure. why returns an empty result and exits 0. It will not invent a decision to look helpful.

$ decree why src/auth/charge.py
src/auth/charge.py — no governing decisions
→ exit 0

When you’d reach for this

• Before editing a file you didn’t write — surface the constraint before you break it.
• In code review — confirm a diff’s files are governed by the decision the PR claims.
• When an agent proposes a change — give it the governing decision as context, deterministically.

Flags & exit codes

why is a query, not a gate: it exits exit 0 clean · advisory-only whether or not it finds a governing decision. An empty result is a valid abstention, never an error.

All flags

| Flag | What it does | |------|--------------| | <path> | Repo-relative path to query, optionally path#symbol. | | --json | Emit JSON for programmatic consumers. | | --project PATH | Operate on the project at this path (default: cwd). | | --with-abstention | Route through calibrated retrieval; abstain when confidence is below threshold. | | --target-precision P | Desired precision floor for non-abstain responses. |

---

Next: intent-check — catch a collision before you write a line.