governs-gap — a file your decision owns but never declared

decree intent-check --under <decision> flags, at the moment you plan an edit, a file your active decision’s own commits keep touching but never declared. You run in a governed session; decree watches for the file your decision quietly owns in practice — and nudges you to make that ownership real.

Scenario You're working under SPEC-…0001 and about to edit src/auth/helper.py — a helper its commits keep touching, but it never declared.

Without decree

The decision governs login.py and nothing else. Its commits keep editing helper.py too, so the scope drifts unnoticed. You only catch the gap in a quarterly audit — if one ever happens. Until then the governs: list quietly lies about what the decision owns.

With decree

Pass --under to mark a governed session, and “this file is yours in practice but undeclared” surfaces at the exact moment you touch it:

$ decree intent-check --plan edit auth helper --files src/auth/helper.py --under SPEC-00000000000000000000000001
Intent check — pre-PR governance map
  Plan: edit auth helper

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

Governing decisions (0):
  (none — ungoverned plan)

Stale governance (0):
  (none)

Unchecked acceptance criteria (0):
  (none)

Conflicts (0):
  (none)

Live-session conflicts (0):
  (none)

Recommended actions (2):
  → add_governance: src/auth/helper.py has no governing decision. Consider writing a SPEC or amending an existing one's `governs:` list before starting.
  → declare_governs [SPEC-00000000000000000000000001]: SPEC-00000000000000000000000001's commits repeat-touch src/auth/helper.py, which is not in its `governs:`. Consider declaring it (advisory).
→ exit 0

VALUE “This file is yours in practice but undeclared” surfaces at the exact moment you touch it — not in a quarterly audit, if ever.

HONESTY Advisory by construction: the declare_governs suggestion never blocks (exit stays 0), and the gap is not a governance fact — it does not feed why() until a human adds the path to the decision’s governs:. Squash-immune (needs commit_count >= 2).

How it works

Pass --under <decision-id> to mark the session as governed by that decision. If a planned or changed file is one the decision’s own trailer-linked commits repeat-touch — at least two of them — but it doesn’t appear in the decision’s governs:, decree surfaces an advisory governs: gap. The two-commit floor makes it squash-immune: a single squashed commit can’t manufacture a suggestion. It is the point-of-change counterpart to health’s batch suggested-governance audit, and it works the same way on both intent-check and intent-review.

Run it

$ decree intent-check --plan edit auth helper --files src/auth/helper.py --under SPEC-00000000000000000000000001
Intent check — pre-PR governance map
  Plan: edit auth helper

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

Governing decisions (0):
  (none — ungoverned plan)

Stale governance (0):
  (none)

Unchecked acceptance criteria (0):
  (none)

Conflicts (0):
  (none)

Live-session conflicts (0):
  (none)

Recommended actions (2):
  → add_governance: src/auth/helper.py has no governing decision. Consider writing a SPEC or amending an existing one's `governs:` list before starting.
  → declare_governs [SPEC-00000000000000000000000001]: SPEC-00000000000000000000000001's commits repeat-touch src/auth/helper.py, which is not in its `governs:`. Consider declaring it (advisory).
→ exit 0

The declare_governs line is a recommendation, not a verdict. The plan is ungoverned and the gap is advisory, so the exit stays 0 either way. decree will not gate your edit on a file you haven’t declared yet.

When you’d reach for this

• An agent working in a governed session — give it --under so it learns which files its decision already owns in practice, deterministically.
• Catching scope drift at edit time, not audit time — the gap surfaces the moment you plan to touch the file, not a quarter later.
• Keeping a decision’s governs: honest as the code grows — close the gap between what the commits do and what the frontmatter claims.

Flags & exit codes

--under is advisory: it never blocks. The exit stays exit 0 clean · advisory-only whether or not a governs: gap is found — a suggestion is not a finding. An invalid --under id is a config error and exits exit 2 config error .

The --under flag

| Flag | What it does | |------|--------------| | --under ID | Active decision id for a governed session. When a planned file is one this decision’s own commits repeat-touch (>=2) but it does not declare, surface an advisory governs: gap. An invalid id exits 2. |

--under exists on both intent-check (the pre-PR planning guard) and intent-review (the post-diff review), with identical semantics. Use it wherever you already run a governed-session check.

---

Next: the lifecycle — create, validate, and track decisions.