decision-lifecycle

Author and track ADRs. Routed to when the user invokes /adr "<title>" (author a new ADR) or /adr-status [--adr N] (list ADR health, read-only). Every ADR is user-attributed — this skill never records a decision the user did not explicitly make.

The append-only decision-log format (entry fields, supersession protocol) lives in {{PLUGIN_ROOT}}/includes/smarts/decision-log-format.md. Read it before writing a log line; do not restate it here.

Boundary with decision-variance. This skill owns ADR authoring and status (/adr, /adr-status) — recording a decision the user has already made, and reporting ADR health. decision-variance owns arbitration — detecting variances between artifacts and the scaffold, scoring options via SMARTS, and the decision log itself. The two share the canonical SMARTS reference under {{PLUGIN_ROOT}}/includes/smarts/ (core.md for scoring, decision-log-format.md for the log) and one ADR template (references/adr-template.md); they are one domain split by responsibility, not duplicated. When a decision needs making (competing options), route to decision-variance; when it needs recording (already decided), stay here.

Pre-flight

Read these, or STOP and surface the gap — never guess a path:

• {{PROJECT_DIR}}/.codearbiter/decisions/ — the ADR directory and existing records. Create it on first /adr if absent.
• For /adr: confirm the user explicitly authorized this decision and supplied (or confirmed) its content. An ADR is never authored as the disposition of a routine finding.

Phase 1 — Index · gate: BLOCK

Scan {{PROJECT_DIR}}/.codearbiter/decisions/ for existing NNNN-*.md ADR files. Record each by filename stem (0014-githook-shim-dropin-fail-closed), title, and status. Determine the next sequential number (no gaps) for /adr; for /adr-status this is the working set.

The stem is the identifier; the number is only a sort key. Two ADRs may already share a number — this repository holds two numbered 0014 — so a bare number can name more than one document. Index by stem, and never assume NNNN resolves to one file until you have checked.

Gate: the existing ADRs are indexed by stem and, for /adr, the next number is fixed and unused — a number already taken by an existing stem is not available, even for an unrelated decision.

Phase 2 — Author (/adr) · gate: STOP

Confirm the decision content with the user — context, the decision itself, alternatives, consequences. MUST NOT fill these from inference. Surface any unknown as an inline [CONFIRM-NN] placeholder; do not resolve it by guessing.

Drop the authoring marker first. The pre-write/pre-edit hooks block any write to .codearbiter/decisions/NNNN-*.md unless a fresh authoring marker is present — that block is the mechanism enforcing "ADRs only via /adr" (arbiter.md §3), so the sanctioned path must arm it itself. Immediately before writing, create the marker at the path the hooks check (project root = git top level):

mkdir -p "$(git rev-parse --show-toplevel)/.codearbiter/.markers"
touch "$(git rev-parse --show-toplevel)/.codearbiter/.markers/adr-authoring-active"

The marker is honored for 30 minutes. Then write {{PROJECT_DIR}}/.codearbiter/decisions/NNNN-<slug>.md using the canonical ADR template — {{PLUGIN_ROOT}}/skills/decision-lifecycle/references/adr-template.md (the single source of truth for the ADR shape, shared with decompose). Author it with status: proposed. If this decision supersedes an existing one, set supersedes: to that ADR's full filename stem — supersedes: 0014-githook-shim-dropin-fail-closed, never supersedes: 0014 — and leave the prior ADR's file untouched (forward-only chain — do not edit it to add a back-reference).

If the new ADR supersedes only part of the prior decision, say which part in the body. supersedes: names a document, not a clause, so a chain may legitimately fork — two ADRs can each supersede different clauses of one predecessor. That fork is correct and must not be "repaired"; only the prose can carry the scope.

After writing the ADR, append a corresponding entry to the decision log per the format in {{PLUGIN_ROOT}}/includes/smarts/decision-log-format.md — Decided by: names the user. Status transitions (proposed → accepted → superseded | rejected) require explicit user instruction; never advance status on this skill's own judgment.

governs: makes the decision live. When an ADR names path globs in governs:, the post-write hook surfaces a one-line notice on any Write/Edit touching a matching file — "this file is governed by ADR-NNNN" — so a recorded decision pushes back at edit time instead of waiting for a checkpoint sweep. Offer the field whenever a decision constrains identifiable files; omit it for decisions without a file footprint. Globs are fnmatch-style against repo-relative forward-slash paths.

Once the ADR file and its log entry are written (and any user-instructed status edit is applied), remove the marker — it exists only for one authoring pass:

rm -f "$(git rev-parse --show-toplevel)/.codearbiter/.markers/adr-authoring-active"

Gate: the ADR file is written with a real decided-by user attribution, numbered without a gap, and its log entry is appended. An ADR with no user attribution, or authored as the disposition of a finding, does not pass — STOP.

Accepted/Planned binding

accepted means Accepted/Planned. It records the user's governance decision; it does not claim that any obligation is Implemented or Verified. When the user explicitly authorizes acceptance:

1. Change only the ADR's status fields to accepted. Derive stable, stem-scoped obligations from every normative clause in its immutable record, bind each obligation to exact ADR text, and obtain independent review that the sealed obligation set is complete.
2. Route through commit-gate to commit the accepted ADR and decision-log append. Do not add the acceptance binding to that commit: its source_commit cannot truthfully name a commit that does not exist yet.
3. From that exact commit, hash the committed Git blob bytes and the separately canonicalized immutable record: strict UTF-8 with LF-normalized line endings, containing the complete ADR while replacing only the recognized status value in the strictly parsed frontmatter status: field and ## Status section with fixed sentinels. The two values must agree. All remaining Status prose, including approval attribution, stays bound alongside title, date, decided-by, supersession, governed paths, H1, and every other section. Malformed or duplicate frontmatter, status, or headings fail closed. Append one acceptance event to {{PROJECT_DIR}}/.codearbiter/decisions/adr-lifecycle.jsonl, then persist that acceptance binding in a subsequent commit. The event uses schema adr-lifecycle/v1 and records adr (full stem), recorded_at, source_commit, blob_sha256, body_sha256, obligations, obligations_sha256, and obligations_sealed: true. A second acceptance or baseline binding for the same stem is invalid.

The lifecycle ledger is append-only. A legacy accepted ADR receives a baseline with no fabricated acceptance commit, an observed_commit whose Git blob is rechecked as the migration snapshot, an empty or incrementally mapped obligation list, and obligations_sealed: false; it remains Accepted/Planned. Later delivery evidence appends records: implemented binds one declared obligation to a source commit and relevant input digests; verified additionally binds a unique event ID, explicit proof contract, repository-scoped claim, producer, command/workflow identity, timezone-aware observation and expiry times, and the same current inputs. Evidence paths and digests are recomputed from the named Git commit, never trusted from the caller. A later uniquely identified event may renew expired or changed-input evidence; an append-only invalidation event may withdraw a prior evidence event. Only a complete, sealed obligation set with current implementation inputs and fresh verification inputs derives Implemented or Verified. Changed inputs invalidate the derived state; history is never rewritten.

After acceptance, do not edit any bound ADR content. A later user-authorized stored status transition may change only the recognized status value in the strictly parsed frontmatter status: and ## Status; approval prose remains immutable. Supersession remains a forward reference in the new ADR. The acceptance commit retains the exact original blob while the immutable-record digest proves every other byte-equivalent field did not change.

Phase 3 — Status (/adr-status) · gate: BLOCK

Read-only. For each ADR (or the --adr N target), report: stem, title, stored governance status, derived delivery state, date, and supersession state. Read adr-lifecycle.jsonl when present. Display stored accepted as Accepted/Planned. Display Implemented or Verified only when every obligation in a sealed binding has the required current, input-bound evidence; otherwise name the narrow reason (unsealed, incomplete, stale, expired, or mismatched) and do not promote the ADR. Repository evidence never implies live-host, publication, support, legal, or other external truth. Find supersession by scanning forward for any later ADR whose supersedes: resolves to it.

Resolve a supersedes: value like this, and never guess:

• The value is a stem → it names that ADR. Done.
• The value is a bare number → collect every stem with that number. Exactly one → it names that ADR. More than one → ambiguous: report it as an error and resolve nothing. Zero → a dangling reference; report that too.
• none (or empty) → no predecessor.

.github/scripts/check_adr_identity.py enforces this same rule mechanically in CI; if it disagrees with this report, the report is wrong.

If a supersession candidate contradicts an accepted ADR with no clear direction, do not pick one — flag it for /conflict.

## ADR Status — YYYY-MM-DD

### Active
- ADR-NNNN-<slug> — <title> — governance: <status>; delivery: <Accepted/Planned | Implemented | Verified> (<date>)

### Superseded
- ADR-NNNN-<slug> — <title> — superseded by ADR-MMMM-<slug>

### Ambiguous supersession
- ADR-NNNN-<slug> — supersedes: <value> names <N> ADRs (<stems>) — unresolved

### Unresolved CONFIRM-NN
- ADR-NNNN-<slug> — [CONFIRM-NN]: <text>

Every ADR is named by its stem, so a shared number never collapses two rows into one. An empty section is marked "None" — not omitted. MAY dispatch decision-challenger ({{PLUGIN_ROOT}}/agents/decision-challenger.md) to stress-test an ADR; optional, never forced.

Gate: every indexed ADR appears with its current status and supersession state; no [CONFIRM-NN] resolved; no file modified.

Hard rules

• MUST author an ADR only via /adr with explicit user attribution. MUST NOT author an ADR as the disposition of a routine finding — an out-of-scope finding gets an inline [NEEDS-TRIAGE] marker instead.
• MUST NOT record a decision the user did not explicitly make. "Use your best judgment," "I trust you" are declined.
• MUST NOT resolve a [CONFIRM-NN] placeholder by guessing. Surface it and stop.
• MUST NOT advance an ADR's status without explicit user instruction.
• MUST NOT report accepted as Implemented or Verified without complete, sealed, current lifecycle evidence.
• MUST NOT rewrite or truncate a committed adr-lifecycle.jsonl, create a second binding, or fabricate legacy acceptance evidence.
• MUST NOT edit a prior ADR or a prior decision-log entry to add a back-reference — supersession is a forward-only chain; append a new record whose supersedes: names the prior one.
• The never-edit rule protects decision CONTENT, not identifiers. Rewriting what was decided corrupts the record; disambiguating which document a pointer names repairs it. Maintainer ruling, 2026-07-25: "the never edit rule is meant to prevent this situation, not prevent this situation from being fixed." So a correction that is provably identifier-only — a supersedes: value changed from a number to the stem it already meant — is permissible, and nothing else about the file is. Any such correction MUST be a single-line diff that alters not one word of any decision, MUST be visible in its own commit, and still requires the maintainer-armed adr-authoring-active marker. MUST NOT touch Context, Decision, Alternatives, Consequences, Risks, status:, date:, decided-by:, or title: under this allowance.
• MUST NOT number an ADR with a gap, and MUST NOT reuse a number an existing stem already holds — a shared number makes every bare reference to it ambiguous.
• MUST NOT modify any file under /adr-status — it is read-only.
• MUST NOT force the decision-challenger agent — its dispatch is MAY only.