docs(adr): propose ADR-304 typed decision records, the adr/v1 contract - #559
Merged
Merged
Conversation
Decision and spec kinds share the ADR-N number space. Three vocabulary layers (record lifecycle, decision verbs, derived product state) share no word. Capabilities are a closed vocabulary in adr.yaml, and the capability ledger is derived from add and cut decisions. Cut and retire decisions carry an enacted field that turns citation warnings into failures. Legacy records are adr/v0 and migrate when touched. Designed with the kg session, which prototypes the triage and doclint extension first.
Sub-parts are records of their own, and a bare ADR-N resolves to its family. The number stays with the spec half on a split, and the decision half links back with decided_by. The stem check covers the vocabulary layers only. The ADR declares its own adr/v1 frontmatter. Inventory targets follow the enactment rule. Capability-without-add warns during migration. The ADR adds derived spec state, freezes every terminal state, requires reasons for reject and abandon, and defines change against constrain *.
aaronsb
force-pushed
the
docs/adr-304-typed-decision-records
branch
from
September 27, 2026 00:53
2ff7263 to
5dcf496
Compare
…endored projects Re-vendoring the v1-capable tool is safe because it lints v0 records as the legacy tool does. A project adopts adr/v1 only by declaring it in adr.yaml. The ADR way's body stays contract-neutral, and its macro reads both axes to disclose v0 or v1 guidance.
…s is the migration test Record ADR's v1 expansion as Agent Decision Record, where an architecture decision is one kind of agent decision.
…ions in an external basis Kinds, their fields and their edge types live in the contract, so a new kind is a contract change and needs no tool release. Every decision carries a basis (operator, evidence, standard, upstream or precedent) whose chain must leave the corpus. add, cut, retire and one-way decisions need an operator basis before acceptance. The model draws on Beer's Viable System Model.
…e proof The agent runs git and gh under the operator's identity, so reviews, merges and record text cannot prove approval. An operator basis carries the operator's quoted words and where they were said. Signed acceptance is deferred to a later change decision.
…nce rejected as too brittle An operator basis records what was said and via which channel: session, issue, Slack or call. Written channels are quoted verbatim. Spoken ones are marked as paraphrase. The basis is an audit trail the operator can dispute, not a credential.
…nvolvement is a recorded level Agents may accept any decision, add, cut and retire included, once the basis chain leaves the corpus. An operator basis records a level: authored, directed or guided. A guided decision is still the agent's. Involving the operator is way guidance, and the tool does not enforce it.
… considered record, and operator-started decisions wait for the operator Record the float, debate, propose, consider flow. The agent owes a decision the operator can understand, and the operator owes one not accepted blindly. A brief 'looks good' counts as full consideration. The rubber-stamp failure mode is an accepted risk, mitigated by the one-way flag in the summary. The ADR now opens with its own summary.
…al records carry real identities
…replayable evidence as a later extension
The VSM framing is corrected to loose inspiration: the operator is System 5 inside the system, evidence and standards are the environment, and peer repos coordinate as System 2. Decisions record the agent (name, model), per the kernel Assisted-by tag and AgDR. Partial supersession uses typed amends and extends edges, since the untyped IETF Updates edge failed. The ADR states fabrication risk and that merge accountability is unchanged. The Summary gains labelled-confidence probes and an inversion. considered records which probes an answer covered, and a bare 'looks good' is valid but scoped to nothing. Research references are appended as the evidence basis.
…se a concern A brief 'yep, looks good' is taken as given. The probes offer the operator's judgement a foothold and do not test the operator. The agent may raise a safety, logic or anything-seems-off concern at any stage, recorded as a concern entry with the operator's answer beside it.
… probes check engagement A concern names what would resolve it, cannot be silently withdrawn, and is listed at acceptance without failing it. The agent challenges once and then proceeds on the operator's answer. An optional canary probe, revealed right after the answer and never kept in the record, calibrates how far the agent leans on brief approvals. Research on trust calibration, the two-challenge rule, andon response, sycophancy under pressure and alarm fatigue is added to References.
…ole and rights Sycophancy grows with session length, and ways already re-disclose on a decay curve. The v1 ADR way gains a child that restates the agent's role and rights on approval language, Summary and considered edits, and adr accept.
A reminder delivered after adr accept is enough, since acceptance is incremental and easy to revisit. Canaries carry a little whimsy, in the working-group Easter-egg tradition. The operator's consideration is recorded: it covers no specific probe, and no canary was used.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Proposes ADR-304: a versioned record contract (
adr/v1) declared inadr.yaml.decision(append-only, the Agent Decision Record proper) andspec(living). ExistingADR-Ncode citations keep resolving.adr lintchecksadr.yamlfor cross-layer reuse.adr.yaml. The ledger is derived from add and cut decisions.enacted: <commit>is set, then fails.doclint: superseded targets warn and name the successor, and proposed targets prompt acceptance.adr/v0, linted as today, and move to v1 when touched.Evidence comes from kg's triage of 108 ADRs (89 mix jobs, none is purely a capability) and this repo's 1,617 code citations (162 to Superseded or Deprecated ADRs).
The design was worked out with the knowledge-graph-system session over attend. kg prototypes the triage and the
doclintextension before anything lands inadr-tool. Doc-only change; the pre-existing Makefile edit is not included.