intent-check — catch a collision before you write a line

decree intent-check --plan … --files … is the pre-code planning guard. You describe the change in a sentence and name the files it will touch, and decree tells you which decisions stand in the way — before you have written a single line.

Scenario You're about to change how src/auth/tokens.py stores refresh tokens.

Without decree

You write the change, push the branch, and open a PR. Only in review does a teammate notice that two decisions claim that file — one shipped, one still in-flight with open acceptance criteria. You found out too late, after the work was done.

With decree

One command, run against the plan, surfaces the collision at planning time:

$ decree intent-check --plan Change token refresh storage --files src/auth/tokens.py
[intent-check] exit 1: findings present (conflicts, live-session overlaps, or stale governance).
Intent check — pre-PR governance map
  Plan: Change token refresh storage

Planned files (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

Live-session conflicts (0):
  (none)

Recommended actions (4):
  → update_spec_first [SPEC-00000000000000000000000002]: SPEC-00000000000000000000000002 (Token rotation policy) governs planned files and has unchecked acceptance criteria. Check off or amend ACs before implementing on top.
  → 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_first: src/auth/tokens.py is governed by SPEC-00000000000000000000000001, SPEC-00000000000000000000000002. Decide which decision is authoritative before implementing.
→ exit 1

VALUE The two-decision collision, the in-flight SPEC, and its unchecked acceptance criteria show up before you code — not in a review comment after.

HONESTY intent-check reports the structural conflict — two decisions declare the same path. It does not judge whether they truly contradict; that semantic call is the agent’s or reviewer’s job.

How it works

Give intent-check a plan summary and the files the plan will touch. It reports the decisions that govern those files, which of them are stale, which acceptance criteria are still unchecked, and any structural conflicts — two decisions claiming the same path. All of it lands before a diff exists, so you adjust the plan instead of unwinding code.

Two decisions declare src/auth/tokens.py. The in-flight one has unchecked acceptance criteria. intent-check surfaces the conflict and the recommended actions.

$ decree intent-check --plan Change token refresh storage --files src/auth/tokens.py
[intent-check] exit 1: findings present (conflicts, live-session overlaps, or stale governance).
Intent check — pre-PR governance map
  Plan: Change token refresh storage

Planned files (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

Live-session conflicts (0):
  (none)

Recommended actions (4):
  → update_spec_first [SPEC-00000000000000000000000002]: SPEC-00000000000000000000000002 (Token rotation policy) governs planned files and has unchecked acceptance criteria. Check off or amend ACs before implementing on top.
  → 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_first: src/auth/tokens.py is governed by SPEC-00000000000000000000000001, SPEC-00000000000000000000000002. Decide which decision is authoritative before implementing.
→ exit 1

--other-active-files takes a JSON map of other session ids to the paths they plan to touch. A planned file that overlaps a live session surfaces as a live-session conflict with an isolate_session recommendation.

$ decree intent-check --plan Edit token storage --files src/auth/tokens.py --other-active-files {"session-b": ["src/auth/tokens.py"]}
[intent-check] exit 1: findings present (conflicts, live-session overlaps, or stale governance).
Intent check — pre-PR governance map
  Plan: Edit token storage

Planned files (1):
  • src/auth/tokens.py

Governing decisions (1):
  ▸ SPEC-00000000000000000000000001  implemented  exact  governs src/auth/tokens.py
    JWT token storage

Stale governance (0):
  (none)

Unchecked acceptance criteria (0):
  (none)

Conflicts (0):
  (none)

Live-session conflicts (1):
  ⇄ src/auth/tokens.py: also planned by session-b

Recommended actions (1):
  → isolate_session: src/auth/tokens.py is also planned by active session(s) session-b. Run in a dedicated worktree, or split this file out of one plan, before starting.
→ exit 1

decree owns no session state. You supply the other sessions’ planned paths; decree only computes the overlap. It reports that two sessions claim the file — not who should win.

When you’d reach for this

Before an agent starts implementing — hand it the governing decisions and conflicts as deterministic context, not a guess.
Before opening a PR — gate CI on a clean plan so collisions surface at planning time, not in review.
When two agents or people might touch the same file — pass their planned paths and catch the live overlap before either writes a line.

Flags & exit codes

intent-check exits exit 1 a finding you can gate CI on on findings — structural conflicts, live-session overlaps, or stale governance — exit 0 clean · advisory-only when the plan is clean, and exit 2 config error on a config error, such as an invalid --under id.

All flags

| Flag | What it does | |------|--------------| | --plan TEXT | One-sentence to one-paragraph description of the planned change. | | --files PATH [PATH ...] | One or more repo-relative paths the plan will touch. | | --other-active-files JSON | JSON map of other active session ids to the paths they plan to touch, e.g. '{"session-b": ["src/foo.py"]}'. Planned files overlapping a live session surface as live-session conflicts. | | --under ID | Active decision id. When a planned file is one this decision’s own commits repeat-touch (≥2) but it does not declare, surface an advisory governs: gap. Invalid id exits 2. | | --json | Emit JSON for programmatic consumers. | | --project PATH | Operate on the project at this path (default: cwd). | | --with-abstention | Route governance lookups through the calibrated method. | | --target-precision P | Desired precision floor for non-abstain responses. |

Next: intent-review — gate the diff after you code.