intent-review — gate a diff against governance

decree intent-review --diff … takes a diff and reports which decisions govern the changed paths, what’s stale, which acceptance criteria are unchecked, and structural conflicts — a deterministic, exit-coded gate that runs in CI before a human reviews. It is the after-you-code counterpart to intent-check: the diff already exists, and you ask whether it collides with the corpus.

Scenario A PR changes src/auth/tokens.py. Does the diff collide with any decision?

Without decree

Governance review depends on a human remembering every decision. Two SPECs claim this path; one is implemented, one is still a draft. The reviewer who knew that nobody remembers has moved teams, so the conflict slips through and ships.

With decree

A build gate that fails when a diff collides with the corpus — before a human looks:

$ decree intent-review --diff change.diff
[intent-review] exit 1: findings present (conflicts or stale governance).
Intent review — file:change.diff

Changed paths (1):
  • src/auth/tokens.py

Governing decisions (2):
  ▸ SPEC-00000000000000000000000001  implemented  exact  governs src/auth/tokens.py
    JWT token storage
  ▸ SPEC-00000000000000000000000002  draft  exact  governs src/auth/tokens.py
    Token rotation policy

Stale governance (0):
  (none)

Unchecked acceptance criteria (2):
  ☐ SPEC-00000000000000000000000002  [Acceptance Criteria]  Rotation job runs on schedule
  ☐ SPEC-00000000000000000000000002  [Acceptance Criteria]  Old tokens revoked on rotation

Conflicts (1):
  ✗ src/auth/tokens.py: SPEC-00000000000000000000000001, SPEC-00000000000000000000000002

Recommended actions (4):
  → check_ac [SPEC-00000000000000000000000002]: SPEC-00000000000000000000000002 has an unchecked AC under 'Acceptance Criteria': Rotation job runs on schedule
  → check_ac [SPEC-00000000000000000000000002]: SPEC-00000000000000000000000002 has an unchecked AC under 'Acceptance Criteria': Old tokens revoked on rotation
  → resolve_conflict: src/auth/tokens.py is governed by SPEC-00000000000000000000000001, SPEC-00000000000000000000000002. Decide which decision is authoritative or supersede the others.
  → add_implements_trailer [SPEC-00000000000000000000000002]: Changes touch files governed by in-flight SPEC-00000000000000000000000002. Consider `decree commit --implements SPEC-00000000000000000000000002` so the commit links to the SPEC.
→ exit 1

VALUE A build gate fails when a diff collides with the decision corpus — instead of a reviewer having to remember every decision that touches the path.

HONESTY intent-review reports structural intersection plus conflict and stale findings. It makes no judgment about whether the change is correct. Exit 1 means “a human or agent must look”, not “this is wrong”.

How it works

intent-review accepts a diff — a file, stdin, a --diff-base ref, or one auto-detected from your git staged and working-tree changes. It intersects the changed paths with the decision corpus, then reports the governing decisions, stale governance, unchecked acceptance criteria, and structural conflicts. It exits non-zero when any of those findings exist, so a CI step can gate on it.

Run it

The canonical invocation: write the diff to a file, then review it against governance.

$ decree intent-review --diff change.diff
[intent-review] exit 1: findings present (conflicts or stale governance).
Intent review — file:change.diff

Changed paths (1):
  • src/auth/tokens.py

Governing decisions (2):
  ▸ SPEC-00000000000000000000000001  implemented  exact  governs src/auth/tokens.py
    JWT token storage
  ▸ SPEC-00000000000000000000000002  draft  exact  governs src/auth/tokens.py
    Token rotation policy

Stale governance (0):
  (none)

Unchecked acceptance criteria (2):
  ☐ SPEC-00000000000000000000000002  [Acceptance Criteria]  Rotation job runs on schedule
  ☐ SPEC-00000000000000000000000002  [Acceptance Criteria]  Old tokens revoked on rotation

Conflicts (1):
  ✗ src/auth/tokens.py: SPEC-00000000000000000000000001, SPEC-00000000000000000000000002

Recommended actions (4):
  → check_ac [SPEC-00000000000000000000000002]: SPEC-00000000000000000000000002 has an unchecked AC under 'Acceptance Criteria': Rotation job runs on schedule
  → check_ac [SPEC-00000000000000000000000002]: SPEC-00000000000000000000000002 has an unchecked AC under 'Acceptance Criteria': Old tokens revoked on rotation
  → resolve_conflict: src/auth/tokens.py is governed by SPEC-00000000000000000000000001, SPEC-00000000000000000000000002. Decide which decision is authoritative or supersede the others.
  → add_implements_trailer [SPEC-00000000000000000000000002]: Changes touch files governed by in-flight SPEC-00000000000000000000000002. Consider `decree commit --implements SPEC-00000000000000000000000002` so the commit links to the SPEC.
→ exit 1

The diff can come from anywhere. The findings are the same regardless of source — only the input differs.

--diff <file>

Review a diff you’ve already written to a file (or - to read it from stdin). This is the form a CI job uses after writing the PR diff to disk.

$ decree intent-review --diff change.diff
[intent-review] exit 1: findings present (conflicts or stale governance).
Intent review — file:change.diff

Changed paths (1):
  • src/auth/tokens.py

Governing decisions (2):
  ▸ SPEC-00000000000000000000000001  implemented  exact  governs src/auth/tokens.py
    JWT token storage
  ▸ SPEC-00000000000000000000000002  draft  exact  governs src/auth/tokens.py
    Token rotation policy

Stale governance (0):
  (none)

Unchecked acceptance criteria (2):
  ☐ SPEC-00000000000000000000000002  [Acceptance Criteria]  Rotation job runs on schedule
  ☐ SPEC-00000000000000000000000002  [Acceptance Criteria]  Old tokens revoked on rotation

Conflicts (1):
  ✗ src/auth/tokens.py: SPEC-00000000000000000000000001, SPEC-00000000000000000000000002

Recommended actions (4):
  → check_ac [SPEC-00000000000000000000000002]: SPEC-00000000000000000000000002 has an unchecked AC under 'Acceptance Criteria': Rotation job runs on schedule
  → check_ac [SPEC-00000000000000000000000002]: SPEC-00000000000000000000000002 has an unchecked AC under 'Acceptance Criteria': Old tokens revoked on rotation
  → resolve_conflict: src/auth/tokens.py is governed by SPEC-00000000000000000000000001, SPEC-00000000000000000000000002. Decide which decision is authoritative or supersede the others.
  → add_implements_trailer [SPEC-00000000000000000000000002]: Changes touch files governed by in-flight SPEC-00000000000000000000000002. Consider `decree commit --implements SPEC-00000000000000000000000002` so the commit links to the SPEC.
→ exit 1

--diff-base <ref>

Skip the file: pass a git ref and intent-review runs git diff <ref>...HEAD for you, then reviews the result. With no diff source at all, it auto-detects from your staged and working-tree changes.

When the changed paths intersect nothing contested — no conflicts, no stale governance — the gate passes and exits 0. A clean run is a real answer, not a silent one.

When you’d reach for this

• As a CI gate on every PR — fail the build when a diff collides with the corpus, so the conflict surfaces before anyone reads the code.
• Before requesting human review — run it on your own branch and resolve the findings first, so the reviewer sees a diff that already passed the gate.
• In an agent loop, after it writes a diff — feed the changed paths back through the corpus deterministically, and let a non-zero exit say “stop and look”.

Flags & exit codes

intent-review is a gate, not a query. It exits exit 1 a finding you can gate CI on when conflicts or stale findings exist, exit 0 clean · advisory-only when the changed paths are clean, and exit 2 config error on a config error (such as an invalid --under id).

All flags

| Flag | What it does | |------|--------------| | --diff PATH | Unified-diff file path, or - to read the diff from stdin. | | --diff-base REF | Run git diff <REF>...HEAD to compute the diff. | | --under ID | Active decision id of a governed session. When a changed file is one this decision’s own commits repeat-touch (≥2) but does not declare, surface an advisory governs: gap. Needs a structured diff; an invalid id exits 2. | | --json | Emit JSON for programmatic consumers. | | --project PATH | Operate on the project at this path (default: cwd). |

---

Next: health — has a decision’s scope rotted over time?