the lifecycle — create, validate, and track decisions

Before decree can tell you which decision governs a file, the decisions have to be real: validated, linked, and tracked. That is the rest of the toolkit — the deterministic core that keeps a folder of markdown from rotting into a folder of lies.

PRD what / why ADR how SPEC blueprint Code implementation

Scenario Your team writes decisions as markdown — a PRD, an ADR, a SPEC — in a folder.

Without decree

A SPEC references an ADR that was archived months ago. Another points at an ID that never existed. Statuses say “draft” on work that shipped. Nothing checks any of it, so the corpus drifts until nobody trusts it.

With decree

decree validates every cross-reference and required section in one pass:

$ decree lint
✓ 3 documents validated. 0 errors.
→ exit 0

VALUE A folder of decisions becomes a corpus you can trust — broken links, missing sections, and illegal transitions fail loudly instead of rotting silently.

HONESTY lint checks structure — references resolve, sections exist, transitions are legal. It does not judge whether a decision is good. Staleness is direct-only: a SPEC pointing at a superseded ADR is flagged; the chain beyond it is not.

lint — validate everything

decree lint checks the whole corpus: dangling references, stale links to dead statuses, self-references, duplicate IDs, supersede symmetry, and missing required sections. It exits exit 1 a finding you can gate CI on when anything fails, so it runs in CI as a gate on the decision corpus itself.

$ decree lint
✓ 3 documents validated. 0 errors.
→ exit 0

progress — track completion

decree progress scans every document for - [x] / - [ ] checkboxes and reports completion per decision, with deferred items separated from primary progress. Scope it to a single doc, a chain, changed files, or a governed path for parallel work.

$ decree progress
[progress] loaded 3 documents
[progress] scope: all documents
✓ 3/6 primary items complete (50%) across 3 documents
[progress] use --doc ID, --chain ID, --changed --base REF, or --governs PATH to narrow parallel work
Scope: all documents

  ADR-00000000000000000000000001   Auth via JWT         accepted  ░░░░░░░░░░   —
  PRD-00000000000000000000000001   User Authentication  draft     ███████░░░  67% (2/3 primary)
  SPEC-00000000000000000000000001  Token Storage API    draft     ███░░░░░░░  33% (1/3 primary)

→ exit 0

status — enforce transitions

decree status <id> <action> moves a decision through its lifecycle, and only legal transitions are allowed — draft → approved → implemented, never a skipped step. A supersede links both documents automatically: the old one gains superseded-by, the new one gains supersedes. The transitions are defined per type in decree.toml, so the rules are yours, not decree’s.

index & graph — generate views

decree index regenerate writes a sorted table per decision type, and decree index rebuild refreshes the SQLite query cache that why, health, and the intent checks read from. decree graph appends Mermaid diagrams — decision timelines, supersede chains, status distributions, C4 container views — below a generated marker in each type’s index.md. Both are derived from the corpus, so they never drift from it.

refs — the reverse graph

Where why goes from a file to its decisions, decree refs <id> goes the other way: everything connected to one decision — forward and reverse references, the supersedes chain, every file it governs, and the trailer-linked commits that implemented it. Here it is run against decree’s own identity SPEC:

$ decree refs SPEC-01KT22NMS0D19VMD8VPK4D2MNX
SPEC-01KT22NMS0D19VMD8VPK4D2MNX  implemented  2026-06-01
  Parallel-Safe Document Identity and Scoped Progress

  Forward refs (2):
    → ADR-01KT22NMRV8ZFMDKV0WNFNGMCJ  (references)
    → PRD-01KT22NMRTFTWFFARAN0PVEETA  (references)

  Reverse refs (0):
    (none)

  Supersedes chain (0):
    (none)

  Governs (7):
    src/decree/identity.py
    src/decree/parser.py
    src/decree/commands/new.py
    src/decree/commands/migrate.py
    src/decree/commands/progress.py
    src/decree/commands/ddd.py
    src/decree/cli.py

  Commits (1):
    5645dcb4  Implements  feat: make decree parallel-safe and fail-closed
→ exit 0

When you’d reach for this

In CI — gate every push with decree lint, so a broken reference fails the build.
At a standup — decree progress shows where each decision actually stands.
On every transition — decree status makes “approved” mean something.

The full configuration schema, every lint rule, and the graph types are documented in the decree repository. Next: see it all run in order — decree by example.