Skip to content
decree

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:

Terminal window
$ 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-06-03T20:01:07+00:00; 0 decision(s) have no trailer-linked commits (governance unobservable).


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

Section titled “How it works”

health surfaces four 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().

Run it

Section titled “Run it”
Terminal window
$ 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-06-03T20:01:07+00:00; 0 decision(s) have no trailer-linked commits (governance unobservable).


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.”

When you’d reach for this

Section titled “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

Section titled “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 is advisory: it is an exit 0 clean · advisory-only contribution and never affects 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.