# Decision record contract

Canonical owner for the ADR (Architecture Decision Record) practice: when an accepted decision must be persisted, where the record lives, and how it connects to the existing RFC-escalation path.

RFC-worthy decisions reach the parent session / human operator through refiner escalation notes, the grill rationale comment or the review template's RFC-escalation sanity check.

A fail-closed tripwire (issue [#1867](https://github.com/mfittko/dev-loops/issues/1867)) enforces part of this practice. `scripts/loop/check-adr-tripwire.mjs` runs at both ready-gate paths: `ready-for-review.mjs` and the raw `gh pr ready` guard `pre-pr-ready-gate.mjs`. It blocks any PR whose diff touches a decision-shaped surface:
- a `skills/docs/*-contract.md` file;
- the shared gate config `packages/core/src/config/extension-defaults.yaml`;
- a change to the `standingAuthorizations` block in `.devloops`;
- a rule-modality (MUST/SHALL vs SHOULD vs MAY family) reversal on an existing `<!-- rule: <ID> -->`, including a keyword stripped from a rule that keeps its marker, or a rule removed outright from a still-present rule-bearing doc.

The block clears when the same diff adds or updates a `docs/decisions/NNNN-*.md` record, or when the PR body carries a one-line waiver `adr-tripwire:allow <reason>` for the deliberate no-ADR case, except for a `standingAuthorizations` change, which only a decision record satisfies. A bare marker without a reason, or the marker mentioned mid-sentence, does not waive. Agents write the waiver only through `node <dev-loops-package-root>/cli/index.mjs pr waive-adr-tripwire` (`ADR-TRIPWIRE-STANDING-WAIVER`). A changed rule-bearing doc whose base and head content cannot both be read also blocks (fail-closed unresolvable-rule-scan). Reviewers judge the remaining ADR-worthiness through the RFC-escalation sanity check.

`docs/decisions/` always means the directory at the root of the repo where the decision is made — in an installed-plugin context that is the consumer repo, which creates the directory (and a `0000-template.md` following the section structure defined here) on first use.

## Rule ownership

| Rule ID | Rule |
|---|---|
| <!-- rule: ADR-WORTHY-PERSIST --> `ADR-WORTHY-PERSIST` | An accepted policy-level choice, architecture-shaping decision, or reversal of previously established policy or contract modality MUST be persisted as an ADR under `docs/decisions/`. |
| <!-- rule: ADR-RFC-TERMINAL --> `ADR-RFC-TERMINAL` | The existing RFC-escalation path (refiner escalation notes, grill rationale, operator checkpoint) is the proposal mechanism; when the operator accepts a decision escalated from an in-flight change, the implementing PR MUST include the ADR alongside the change — unless the escalation was spun out into its own RFC issue, in which case `ADR-RFC-ISSUE-DECISION-ONLY` governs. A separate RFC document type MUST NOT be introduced. |
| <!-- rule: ADR-RFC-ISSUE-DECISION-ONLY --> `ADR-RFC-ISSUE-DECISION-ONLY` | An RFC issue — an issue opened to resolve an RFC-worthy question — MUST deliver the ADR as its sole substantive merge artifact (mechanical registration and mirror updates aside) and MUST NOT carry implementation; implementation MUST be scheduled as separate main-track (epic-tree) work that references the accepted ADR. When an in-flight escalation is spun out into its own RFC issue, this path governs: the ADR lands via the RFC issue's PR and the original change references the accepted record instead of carrying it. |
| <!-- rule: ADR-PATH-NUMBERING --> `ADR-PATH-NUMBERING` | An ADR MUST live at `docs/decisions/NNNN-<slug>.md`, where `NNNN` is the highest existing record number plus one, zero-padded to four digits, and `<slug>` is lowercase kebab-case (`[a-z0-9-]`); numbers MUST NOT be reused, and merged records MUST NOT be renumbered. A PR MUST NOT merge a record whose number already exists on the default branch: when concurrent in-flight PRs claim the same number, each later-merging PR MUST renumber its record before merge. When a duplicate number has already merged, the only repair is a rename of one colliding record to a free number, with its body unchanged apart from the number in the title; the validator accepts that rename and still rejects any other deletion or renumbering. Number `0000` is permanently reserved for the template (`0000-template.md`), which is not a record and is exempt from the ADR-* rules; records start at `0001`. |
| <!-- rule: ADR-TEMPLATE-SECTIONS --> `ADR-TEMPLATE-SECTIONS` | An ADR MUST contain the sections `Status`, `Context`, `Decision`, and `Consequences`, in that order (see `docs/decisions/0000-template.md`). |
| <!-- rule: ADR-STATUS-VALUES --> `ADR-STATUS-VALUES` | The `Status` section MUST be exactly one of `Proposed`, `Accepted`, or `Superseded by` followed by a markdown link to the superseding record. `Accepted` and `Superseded` statuses MUST carry dated acceptance evidence appended as ` — YYYY-MM-DD (<link>)`: the date the decision was accepted and a link to the accepting event — the merged PR, closed issue, or commit — using the merge/close timestamp when acceptance was implicit. `Proposed` MAY appear only while the authoring PR is still under review; the same PR MUST flip it to `Accepted` (or remove the record) before merge. |
| <!-- rule: ADR-SUPERSEDE-NOT-REWRITE --> `ADR-SUPERSEDE-NOT-REWRITE` | Changing an accepted decision MUST be recorded as a new ADR that supersedes the old one; the old record's body is never rewritten beyond flipping its `Status` to the superseded form. |
| <!-- rule: ADR-TRIPWIRE-STANDING-WAIVER --> `ADR-TRIPWIRE-STANDING-WAIVER` | No agent hand-writes an `adr-tripwire:allow` line. `edit-pr.mjs` (`node <dev-loops-package-root>/cli/index.mjs pr edit`) MUST refuse a body whose set of marker lines differs from the PR's current set, and `create-pr.mjs` MUST refuse any marker line, and `comment-issue.mjs` and `edit-comment.mjs` MUST refuse a comment body with a marker line (`OPERATOR-OWNED-LINE`, no override); each refusal names `node <dev-loops-package-root>/cli/index.mjs pr waive-adr-tripwire`. That command is the only agent writer of the line. It MUST write only under the standing authorization and eligibility checks in [Standing waiver for contract-doc triggers](#standing-waiver-for-contract-doc-triggers). On `nextAction: resolve_adr_tripwire` the orchestrator MUST run it before asking the operator, and on a refusal MUST quote the typed refusal reason in that ask. |
| <!-- rule: OPERATOR-OWNED-LINE --> `OPERATOR-OWNED-LINE` | One registry, `OPERATOR_OWNED_LINES` in `@dev-loops/core` (`packages/core/src/github/operator-owned-lines.mjs`, ADR 0258), lists the operator-owned comment lines. They are: a line that opens with `approve merge` (the per-merge approval), `approve release v<version>` (the stable-release approval), an `adr-tripwire:allow` line (the ADR tripwire waiver), and a Copilot body-disposition `operator` marker. `guardCommentBodyNoIssuePrIds` reads the registry, so every sanctioned comment writer that calls the guard MUST refuse a body with any of them, with exit 1, no GitHub call and `OPERATOR-OWNED-LINE` in the refusal. `--allowed-refs` never clears a refusal. The size-budget waiver record of `pr ready-for-review` calls the registry directly and also refuses an operator-owned line. Each entry has a `standingAuthorization` value. `--standing-authorization` on `comment-issue.mjs` and `edit-comment.mjs` clears only the Copilot `operator` marker, and no flag clears the other three. The human posts every line. A code span, a fenced block or a `>` quote line passes for `approve release` and for the Copilot marker, whose readers strip them. A mid-line mention of `approve merge` passes, and so does the Copilot `fix` marker. `approve merge` is refused on the raw body, including `>` quote and fence lines. `adr-tripwire:allow` is refused at line start, including fence lines. A line-start code span of either passes. `approve release` is refused anywhere in bare prose. The gate surface writers (`upsert-checkpoint-verdict.mjs`, `post-gate-findings.mjs`, `close-gate-findings.mjs` and the inline finding, findings comment, deferred summary and close or reject reply text they render) MUST wrap every bare operator-owned phrase in reviewer, judge and Copilot free text in a code span through `wrapOperatorOwnedPhrases` before the guard sees the body, so the guard does not refuse the round (operator decision, 2026-11-08, ADR 0258). Every other writer, including `comment-issue.mjs`, `edit-comment.mjs` and the no-core `post-gate-verdict-fallback.mjs`, keeps the refusal with no override flag. Ceiling: the guard stops an instruction-following agent. An agent that calls the GitHub API directly with the shared token is not stopped. |
| <!-- rule: ADR-TRIPWIRE-EARLY-SURFACE --> `ADR-TRIPWIRE-EARLY-SURFACE` | The ADR tripwire and the size budget MUST be reported before the ready flip. `create-pr.mjs` (`node <dev-loops-package-root>/cli/index.mjs pr create`) MUST print one `{adrTripwire,sizeBudget}` JSON line after the `gh pr create` stdout once the PR exists and a base resolves (a lightweight issue-less or body-less create then prints a further `{board}` line), and a block never refuses creation. The one exception is the size check before creation (ADR 0154, amends ADR 0123): `pr create` refuses with `size_split_required_before_pr` when the local `origin/<base>...<head>` whole-PR logic LOC is at or above the resolved default-tier `waiverLoc` (`PRE-PR-SIZE-CHECK`), and an `unknown` size does not refuse. `loop gate-coordination` MUST report both fields for a draft PR at every run, from refs that already resolve locally; an unresolvable ref gives outcome `unknown` and no fetch. While the current head has no clean `draft_gate` evidence a block is advisory and does not change `nextAction`, which still routes to the draft gate. The coordinator MUST report an advisory hit to the operator in its first draft hand-back, before the first `draft_gate` round. With clean current-head `draft_gate` evidence and a tripwire block the result is `nextAction: resolve_adr_tripwire`, with a waivable size block it is `resolve_size_budget`, and with `unknown` or an unwaivable size block it is `report_blocked`; each forbids `mark_ready_for_review`, and a combined block names every decision in one reason. On `resolve_adr_tripwire` or `resolve_size_budget` the coordinator MUST stop and hand back. The orchestrator MUST NOT resume the coordinator while the coordination result still reports that action at the same head and PR body. The one exit for `resolve_size_budget` is a size waiver: after the operator decides it, the orchestrator (not the coordinator) flips ready at the same head with `pr ready-for-review --waive-size-budget --reason <r> [--approved-by <h>]`, and this is the only case where the no-resume rule yields. During draft rounds a size-budget `escalate` is advisory (reported in the hand-back). After the ready flip the existing runner stop on `escalate` applies, and merge-pr's `size_budget_human_approval` enforces the approve-merge marker. |
| <!-- rule: ADR-OVER-WAIVER --> `ADR-OVER-WAIVER` | Parent: `PURPOSE-HIGHEST-SAFE-AUTONOMY`. When a PR trips the ADR tripwire for an ADR-worthy decision, the orchestrator adds the ADR to the PR and requests no `adr-tripwire:allow` line from the operator. A waiver line is not the remedy for a decision that needs a record. This rule applies before `ADR-TRIPWIRE-STANDING-WAIVER`: for an ADR-worthy trigger the orchestrator adds the ADR and does not run `waive-adr-tripwire`. `ADR-TRIPWIRE-STANDING-WAIVER` governs the writer of any waiver line that remains. ADR 0188 records this rule. |
| <!-- rule: ADR-LINKS-ONLY --> `ADR-LINKS-ONLY` | ADRs MUST be referenced from issue and PR bodies as plain links only; decision content MUST NOT be synchronized into tracker artifacts (consistent with the linkage rows in [Tracker-first loop state](./tracker-first-loop-state.md)). An ADR SHOULD link its source issue/PR URLs in `Context`. |

## Standing waiver for contract-doc triggers

The operator records a standing authorization in `.devloops` under `standingAuthorizations.adrTripwireWaiver` with four required fields: `grantedBy` (GitHub login), `grantedAt` (ISO date), `expires` (ISO date, at most 90 days after `grantedAt`) and `reason` (non-empty). The record has no scope field. The writer reads it only from the effective `.devloops` config file on `origin/<defaultBranch>` (the first existing of `.devloops`, `.devloops.yaml`, `.devloops.yml`, `.devloops.json`, in loader order), never from the worktree, the PR head, the PR body, an environment variable or a CLI argument. A missing, malformed, over-long or expired record (expiry compared with the current UTC date) means no authorization is in force, and the writer refuses.

`node <dev-loops-package-root>/cli/index.mjs pr waive-adr-tripwire --repo <owner/name> --pr <n>` writes the waiver only when every check passes, and otherwise refuses with a typed reason and leaves the body unchanged:
- a standing authorization is in force;
- the PR body links exactly one tracker issue and the PR is not on the lightweight `pr_body` path:
  - `Closes`/`Fixes` links the issue;
  - a body with no closing keyword may link with `Refs`;
  - the one `Refs` target that carries a valid AC / DoD matrix is the linked issue, while two or more such targets refuse `ambiguous_refs_tracker_issue`;
  - a list such as `Refs #7, #8 and #9` counts every same-repo number, and each entry carries its own optional `owner/repo` qualifier (`Refs x/y#5, #7` counts only #7);
  - an unreadable target counts as carrying no matrix;
- the tripwire at `origin/<baseRefName>...<headRefOid>` blocks, and every trigger is a `skills/docs/*-contract.md` path;
- every triggering path appears, as a backticked repo path, in a row of the linked issue's valid `## AC / DoD matrix`;
- the current head has a clean `draft_gate` or `pre_approval_gate` verdict whose recorded `specDigest` equals the digest of the linked issue's current body. With neither verdict, the cap-round-fixed proof (`GATE-EXEC-ROUND-CAP-WAIVER-PROOF` in the [gate review sub-loop contract](gate-review-sub-loop-contract.md)) qualifies, and its findings ledger supplies the recorded `specDigest`. A converged or carried `draft_gate` marker reads the sealed ledger at the head it names (`convergedFromHeadSha`, else `carriedFrom`), and a ledger that fails its seal counts as unrecorded (ADR 0252).

`merge-pr` runs the same writer in-process when the tripwire blocks only because the standing waiver line is stale (pinned to an older head, expired, or missing a current trigger from `paths=`), and quotes a refusal. ADR 0132 amends ADR 0119 for both rules.

The standing authorization never waives a `packages/core/src/config/extension-defaults.yaml` trigger, a rule-modality reversal or rule removal, an unresolvable rule scan, a contract doc the matrix does not name, or a change to the `standingAuthorizations` block. It never satisfies, and is never satisfied by, a size-budget waiver, `--allow-cross-issue`, `--allow-replacement-pr`, an `approve merge <headSha>` comment, a `copilot-body-disposition` record or an `approve release v<version>` comment.

The writer emits one line, `adr-tripwire:allow standing-authorization head=<40-hex> issue=<n> granted-by=<login> expires=<date> paths=<comma-separated paths>`, and replaces an earlier standing-authorization line. The tripwire treats a line whose reason starts with `standing-authorization` as valid only when its `head=` equals the evaluated head, its `expires=` day (UTC) has not passed, and every current trigger is a contract-doc listed in its `paths=`, so a later push blocks again until the writer re-runs. A hand-written `adr-tripwire:allow <reason>` line (an operator edit in the GitHub UI) keeps its meaning.

A diff that changes the `standingAuthorizations` block is a tripwire trigger that only a decision record satisfies. `ready-for-review.mjs` and `pre-pr-ready-gate.mjs` also refuse the ready flip of such a PR until the repo owner has left an `APPROVED` review or an `approve merge <headSha>` comment at the current head. ADR 0119 records this rule and amends ADR 0052.

## What is ADR-worthy

`ADR-WORTHY-PERSIST` intentionally excludes routine implementation choices. Any single one of the following signals is sufficient to make the rule bind:

- the operator decided it at a policy checkpoint (link scheme, external coupling, release policy);
- it reverses or re-scopes an established contract rule's modality;
- it shapes an architectural seam other work must build against (adapter boundaries, enforcement layers, artifact locations);
- it was escalated as RFC-worthy and accepted.

A decision that only affects one PR's internals is not ADR-worthy.

## Cross-references

- [Contract style guide](./contract-style-guide.md) — rule ID and RFC-2119 conventions
- `docs/decisions/0000-template.md` — the record template
