Repository navigation
docs: say how to accept a draft and merge the Changed headings - #954
Merged
Merged
Conversation
…raft Unreleased had two `### Changed` headings. The README bullet now sits in the first one, so the section follows Keep a Changelog's one heading per type. The README and Getting Started said a draft written from a coding agent's shell is read by no check until its status is accepted, but not how to accept it. Both now name the two ways that work on 0.14.0: change `status: draft` to `status: accepted` in the header of both files, or have the agent pass `--status accepted`. City: city · Agent: local-core__builder-ci-wisp-r28ve8
Accepting a draft by hand now also changes the decision file's `Status: proposed` line below the header. No check reads it, but it is what a person reading the decision sees, and `adr new --status accepted` writes `Status: accepted` there. `--status accepted` doesn't accept an existing draft; it makes `adr new` write an accepted decision in the first place, so it now has a sentence of its own. City: city · Agent: local-core__builder-ci-wisp-r28ve8
davidmiuraactualai
approved these changes
Nov 18, 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
This follows up the review on #948, whose first two points arrived after that PR merged.
### Changedheadings. The README bullet now sits in the first section, so the release keeps one heading per type, as Keep a Changelog expects. No bullet text changed.status: drafttostatus: acceptedin the header of both filesadr newwrote, and the decision file'sStatus: proposedline toStatus: accepted. A second sentence notes that an agent passing--status acceptedwrites an accepted decision in the first place. Both hold on 0.14.0 and on main.The review's third point, the README paragraph that repeats the new section's
actual adr newsentence, waits on #943, which rewrites that paragraph. It's tracked for a trim once #943 merges.Risk is low, since only docs change. #930 and #950 append CHANGELOG bullets where the two headings meet, so whichever merges after this one resolves a two-line conflict there. Other open PRs on these files conflict no more than they already do.
Verification: none, docs only
The new sentences were checked against the released 0.14.0 CLI in a scratch repository (details below).
Test plan and overlapping pull requests
Test plan
The released
actual0.14.0 binary ran in a scratch git repository, with telemetry off through a scratch config directory:actual adr new "Use Postgres for storage" --policy "MUST: Services store relational data in Postgres." < /dev/null(no terminal, as in an agent's shell) wrote both files withstatus: draft, andactual rules lslisted the rule asMUST 1 (draft, not enforced).status: drafttostatus: acceptedin the rule file's header madeactual rules lslist the rule as enforced, since the checks read the rule file under.actual/rules/. The decision file's header and itsStatus: proposedline change too, so the file reads as one written with--status accepteddoes (Status: acceptedbelow the header). No check or save reads that line, andactual adr check --no-cloudpassed with all three changed.actual adr new "Use Redis for caching" --policy "MUST: Services cache through Redis." --status accepted < /dev/nullwrote both files withstatus: accepted, printed "It is accepted, so plan-check and impl-check enforce it now", andactual rules lslisted the rule as enforced.--status accepted|draftappears in 0.14.0'sactual adr new --helpand in itsdocs/ADR_COMMANDS.md, and the README already marksadr newas CLI 0.14.0 or later, so the new sentences need no version note of their own. The status list that decides whether a rule governs (src/rules/types.rs:228) is unchanged between v0.14.0 and main.Pushing a draft with
actual adr create --filewasn't exercised, since it needs a sign-in and saves to Actual AI, so the docs don't offer it as a way to accept a local draft.Overlapping pull requests
git merge-tree --write-treeof this branch against each open PR that edits these files, beside main against the same PR: