Repository navigation
docs: an agent-tuned ADR policy, a lean template and every ADR converted - #110
Merged
Merged
Conversation
docs/ADR_POLICY.md holds the ADR rules in one place: git is the archive, an ADR states only the current decision, a changed decision is overwritten in place, and a superseded one is deleted and never referenced again. The template drops the status, date and decider fields and the lifecycle footer. Both pages join the docs-lint ratchet. The Markdown baseline falls from 680 to 674 because the old template's issues are gone. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The root, audit, implement and engine AGENTS.md files, the docs router, CONTRIBUTING.md, spec/README.md and root ADR 0001 now link to docs/ADR_POLICY.md. The style guide and the engine AGENTS.md drop their restated ADR rules and link to the policy instead, so the rules live in one place. The Markdown baseline falls from 674 to 673. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Root ADRs 0001-0008 drop the status, date, review and decider fields, the horizontal rules and the lifecycle footer. Their bodies now state only the current decision: dated notes, release and plan IDs, and "before this ADR" history are removed or rewritten in the present tense. Old choices stay as rows in Alternatives Considered. ADR 0001 gains that section. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Spec decisions 0001 and 0002 drop the header fields, the rules and the lifecycle footer, and state their context in the present tense. The old constraints.draft.yaml output becomes a row in Alternatives Considered. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Audit ADR 0001 drops the header fields, the lifecycle footer and its dated paths note. Its text now uses the current paths (audit/tools/, audit/engine/) and no plan step IDs. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Implement ADRs 0002 and 0003 drop the header fields, the rules and the lifecycle footer. ADR 0003 states its context as a present-tense problem instead of a past disagreement between pages. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Engine ADRs 0001-0009 drop the header fields, the rules and the lifecycle footer. Their context sections describe the problem in the present tense instead of the engine's past behaviour, and roadmap, release and plan references are gone. ADR 0008 names the current template path, greenfield/templates/. The Markdown baseline falls from 673 to 658. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Git holds status and dates, so both ADR indexes now list number, title and a one-line summary. The implement group note states the retired number, and the engine index points at the ADR policy. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The docs-contract playbook no longer marks target ADRs `proposed`. A record has no status or date; the owner accepts it by merging the branch. The playbook now writes an ADR policy page, named to fit the target, and the index lists number, title and summary. The implement skill bundle carries the policy and the template so its links resolve. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The dev ruleset no longer requires an up-to-date head (ADR 0002). The alternative stays rejected because fixing a conflict would need a push to main, which the main ruleset refuses. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
New repositories get docs/ADR_POLICY.md and the lean ADR template. The style guide, AGENTS.md, CONTRIBUTING.md and the pull request template link to the policy instead of restating it. ADR 0001 drops its header fields and lifecycle footer, and the index lists a summary. The AGENTS.md pointer avoids "before you ... read", which AGT-10 reads as deferral. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
AGT-10 reads "before you ... read <file>" on one line as deferral to an unconfigured file. The line passed only because it wrapped before the file name. It now states the rule directly. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Resolves the ADR index conflict and converts the new spec decision 0003 to the lean template, with its row in the index. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This was referenced Nov 10, 2026
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
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.
Summary
An ADR policy tuned for agents: git is the archive, so an ADR states only the current decision. A changed decision
is overwritten in place; a superseded one is deleted and never referred to again.
docs/ADR_POLICY.md(11 rules) and a leandocs/templates/adr-template.mdwith nostatus, date or decider fields and no lifecycle footer.
AGENTS.md(root, audit, implement, engine),docs/STYLE_GUIDE.md,docs/README.md,CONTRIBUTING.mdandspec/README.mdlink to the policy instead of restating ADR rules.notes and plan IDs removed; context in the present tense; file names and numbers unchanged.
establish-docs-contractno longer marks target ADRsproposed; the owner's merge is theacceptance. It writes an ADR policy page into the target. The implement skill bundle now carries the policy and
the template so its links resolve.
mainalternative gets its current reason (devis no longer strict).The Markdown lint baseline falls from 680 to 647.
Checks
make check,make security,make docs-lint,make commit-lint RANGE=origin/dev..HEAD: pass.Follow-up (separate branch)
S7: DOC-04 flags superseded, deprecated or rejected ADRs in an audited repository. G2:
dev/adr_lint.pyinmake checkenforces the policy here.🤖 Generated with Claude Code