writing-decisions

name	writing-decisions
description	Use when creating or superseding a criv ADR under docs/adr, setting its governs scopes, or adding an inline policy pattern.

Writing decisions

A decision note lives under docs/adr/ as NNNN-kebab-title.md and carries id, kind: decision, title, status, and date. Take the ID from criv query next-adr-id, which reads the state and returns the next free number.

Governed scope

governs: lists the path globs and source selectors the decision controls. Each glob must match at least one indexed source file; criv check reports an unmatched glob as unresolved-governs. Name the files a reader would open, and let the decision govern only what it really decides.

Policy patterns

State an enforceable structural rule as an inline policy.patterns entry, so the rule and its rationale stay in one file:

policy:
  patterns:
    - id: no-println
      language: rust
      pattern: "println!($$$ARGS)"
      message: Prefer structured diagnostics.

Use pattern for a simple ast-grep pattern and rule for full ast-grep YAML. An ADR's policy.patterns frontmatter is the only home for a persistent named rule, addressed as ADR-NNNN/local-id.

Inspect policy diagnostics before accepting the decision:

• criv check --filter ADR-NNNN — text diagnostics for one decision, each with its fix: line.
• criv check --format json --filter ADR-NNNN — the same diagnostics with code and fix as fields.
• criv enforce --stage ci — the complete policy gate. Add --format json for the counts, the violations, and the failure code.

Immutability

An accepted ADR is a historical record. Change a decision by writing a new ADR whose supersedes: names the old one, and leave the old file exactly as it is.

The decision is complete when its globs resolve, its patterns match what the message describes, and the vault is green.