ADR-0010: A request for changes is a comment, not a status

Status: accepted · 2026-09-11

Context

An approver reading an ADR had two answers: accept, or reject with a note. Neither says “yes, but change the rollback section.” That answer went into an ordinary comment, which an agent would never see unless a person pasted it into a prompt — and the ADR sat at proposed with nothing to say whether it was still waiting or already sent back.

The obvious fix is a fourth ADR status, changes-requested. Three things argue against it.

1. A status is one value per page; requests are several. Two reviewers can each want two things on two sections. A status can hold none of that, and the moment it is set, the second reviewer’s request has nowhere to go but the same place the first one went before this ADR: a comment.
2. A status change carries no location and no thread. ADR-0007 already built the thing a request needs: an anchor to a section or a task, a thread for the answer, list_comments to find it, and get_page counting what is open per section. A request that lives elsewhere would need all four again.
3. Moving the status moves a decision the author did not make. The ADR lifecycle (proposed → accepted | rejected | superseded) is the record of what was decided. “Not yet” is not a decision on the record; it is a conversation about one.

Two further facts shaped the answer. approvalStatuses.adr is deliberately null: ADRs are edited after acceptance to record consequences, and the withdraw-on-edit rule would keep retracting the approval — so “accepted” on an ADR is a standing decision, and the decision comment is its record. And a brief is the opposite: its approval is of those exact words, so a brief is rejected and resubmitted rather than revised in place.

Decision

A request for changes is a decision recorded on a comment. It moves no status.

• commentDecisionSchema gains changes-requested, beside approved and rejected. The note is required, and — new for decision comments — may be anchored to a section or a task.
• Only types that are revised in place accept it. decisionGates says which: an ADR does (changesRequestable), a brief does not. Same table says how a type asks for a decision — a brief by entering awaiting-review, an ADR by an explicit request_review, because an ADR is proposed from birth and most proposed ADRs are drafts.
• Addressed is the author’s word; resolved is the reviewer’s. A reply with addresses: true marks the root addressedAt. An agent never resolves the request it was asked to answer. When the last open request on a page is addressed, the page asks for review again through the record and digest the first ask used (noteReviewAddressed), worded as a revision.
• awaitsDecision(page) is the one definition of “in the queue”, shared by /home, the digest and the MCP tools: at the gate’s waiting status, asked (by status or by request), and not sent back with a request still open.
• The agent’s pull side is one tool, list_feedback: open requests across the workspace since an instant, optionally only on pages whose externalRef.system is the caller’s. The push side is a webhook event, page.changes_requested.
• The rule that a decision on an ADR reaches the plans built on it is guidance, not code: the agent playbook says to read referencedBy and revise those plans, and one end-to-end test proves the path.

Consequences

• An approver has three answers on an ADR — accept, request changes, reject — each with a note, the request’s anchored where they point. The home queue lists proposed ADRs that asked, with “Accept” as the verb.
• The page shows “2 requests · 2 addressed” and “Revised since X’s request” from the same comments the agent reads; nothing is stored twice.
• One collection-group index on comments (workspaceId, decision, createdAt) makes list_feedback one query rather than one per page.
• reviewDecision on a page can now read changes-requested, and the decision email has a third wording. reviewAddressedAt is the only new page field.
• A fourth status was not added, so nothing that filters or sorts by status — the tree, the type view, search — has to learn a state that means “waiting on someone else”.
• Not done here, and out of scope on purpose: acceptedAt on ADRs (the decision comment is the record), agents resolving threads, and changes-requested on briefs.