health — has a decision's declared scope rotted?

decree health surfaces governance drift — where a decision’s declared scope has diverged from where the code actually changed. A governs: list is a claim. Over months, the claim and the commits drift apart. health measures the gap and tells you which half is a finding and which half is only a hint.

Scenario Months in: a SPEC still claims it governs src/auth/legacy_sso.py — but no commit that cited it ever touched that file.

Without decree

The governs: list quietly becomes fiction. The SPEC still names a file its own history never touched, while its commits keep editing a helper it never declared. You’d only catch it in a quarterly audit — if ever.

With decree

decree separates a finding from an advisory and never confuses the two:

$ decree health
Stale decisions: none (all governed paths quiet).

Ungoverned hotspots: none above threshold.

Dead governance (declared governs paths no trailer-linked commit has touched):

  SPEC-00000000000000000000000001   untouched by its 2 linked commit(s):
    src/auth/legacy_sso.py

Suggested governance (advisory — ungoverned files with a proposed owner; does not affect exit status):

  SPEC-00000000000000000000000001   from 2 linked commit(s) touching 2 path(s):
    src/auth/helper.py  (touched in 2 commits)

  observed as of 2026-07-07T17:47:32+00:00; 0 decision(s) have no trailer-linked commits (governance unobservable).

Lifecycle drift (1) — advisory:
  ~ SPEC-00000000000000000000000001 [terminal_but_governance_dead]: SPEC-00000000000000000000000001 is implemented (terminal) but its declared governance is dead (unobserved in commits).

Thresholds: --threshold-commits=10 --threshold-days=30
→ exit 1

VALUE Dead governance — a declared path no trailer-linked commit ever touched — is a finding you can gate on. Scope the code grew into but never declared is advisory, surfaced beside it, kept apart from it.

HONESTY The signals read the Implements: trailer convention: deterministic to compute, not certain. A SPEC with zero trailered commits is reported “unobserved, not dead” — fail-safe. Suggested governance never feeds why().

How it works

health surfaces four coherence signals from the SQLite index and git history. Stale decisions (declared paths churned while the decision sat still) and ungoverned hotspots (high-churn files no decision owns) key off git churn. Dead governance (declared governs: paths no trailer-linked commit ever touched) and suggested governance (files a decision’s own commits repeat-touch but never declare) additionally rest on the Implements:/Refs:/Fixes: trailer convention — deterministic to compute, not certain. All four are read-only and never feed why().

Two further signals report governance quality rather than coherence, and both are advisory — they never change the exit code. Lifecycle drift flags a decision at 100% acceptance criteria with commits attached but still marked draft (status stopped signalling maturity), or a shipped decision whose governance has since gone stale or dead. Broad governance flags a governs: surface that grew too wide — the counts, the exact-vs-directory split, the governs-to-commits ratio, and how many paths another decision also governs — the drift from “files owned” toward “files touched”.

Run it

$ decree health
Stale decisions: none (all governed paths quiet).

Ungoverned hotspots: none above threshold.

Dead governance (declared governs paths no trailer-linked commit has touched):

  SPEC-00000000000000000000000001   untouched by its 2 linked commit(s):
    src/auth/legacy_sso.py

Suggested governance (advisory — ungoverned files with a proposed owner; does not affect exit status):

  SPEC-00000000000000000000000001   from 2 linked commit(s) touching 2 path(s):
    src/auth/helper.py  (touched in 2 commits)

  observed as of 2026-07-07T17:47:32+00:00; 0 decision(s) have no trailer-linked commits (governance unobservable).

Lifecycle drift (1) — advisory:
  ~ SPEC-00000000000000000000000001 [terminal_but_governance_dead]: SPEC-00000000000000000000000001 is implemented (terminal) but its declared governance is dead (unobserved in commits).

Thresholds: --threshold-commits=10 --threshold-days=30
→ exit 1

Read the split in the output. Dead governance lists src/auth/legacy_sso.py — a declared path the SPEC’s two linked commits never touched, so it counts as a finding. Suggested governance lists src/auth/helper.py — a file those same commits keep editing but the SPEC doesn’t claim, surfaced as advisory and marked “does not affect exit status.” The same implemented SPEC also appears once more under Lifecycle drift — shipped, yet its declared governance is dead — an advisory nudge, covered next.

Governance quality

Beyond coherence, health flags where a decision’s lifecycle or scope has drifted. Here a SPEC has every primary acceptance criterion checked and a commit attached, yet is still marked draft, and its governs: list has grown to 26 paths. Both surface as advisory — the four coherence signals are clean, so health exits exit 0 clean · advisory-only .

$ decree health
✓ health: clean.
Stale decisions: none (all governed paths quiet).

Ungoverned hotspots: none above threshold.

Dead governance: none (every declared path with a commit basis was touched).

Suggested governance: none (no repeat-touched undeclared paths).

  observed as of 2026-07-07T17:47:34+00:00; 0 decision(s) have no trailer-linked commits (governance unobservable).

Lifecycle drift (1) — advisory:
  ~ SPEC-00000000000000000000000001 [complete_but_not_terminal]: SPEC-00000000000000000000000001 has 2/2 primary ACs done and 1 commit(s) attached, but status is 'draft'. Transition it, or move incomplete work to a deferred section.

Broad governance (1) — advisory:
  ~ SPEC-00000000000000000000000001: governs 26 (26 exact / 0 dir), 0 shared hot file(s), ratio 26.0

Thresholds: --threshold-commits=10 --threshold-days=30
→ exit 0

VALUE A “100% complete but still draft” SPEC is exactly the drift that makes an agent distrust status. health names it — without ever failing your build on it.

When you’d reach for this

A periodic governance audit — sweep the corpus for governs: lists that have rotted into fiction since they were written.
A CI guard against governs: rot — fail the build when a decision declares scope its own commits abandoned.
Onboarding to a codebase — see where the map and the territory drifted before you trust either one.

Flags & exit codes

health exits exit 1 a finding you can gate CI on when stale, ungoverned-hotspot, or dead-governance findings exist. Suggested governance, lifecycle drift, and broad governance are advisory: they are exit 0 clean · advisory-only contributions and never affect the exit. A config error exits exit 2 config error .

All flags

| Flag | What it does | |------|--------------| | --json | Emit JSON for programmatic consumers (uncapped — the full advisory + findings set). | | --project PATH | Operate on the project at this path (default: cwd). | | --threshold-commits N | Stale / hotspot commit threshold (default: 10, or the [health] block). | | --threshold-days N | Ungoverned-hotspot lookback window in days (default: 30). |

The signals are convention-bounded — they need decree commit trailer discipline to see your history. For why they are trustworthy because they refuse to guess, read the health signals reference.

Next: governs-gap — the point-of-change counterpart to this batch audit.