diff --git a/.changes/architecture/feat-record-decision-citation-sweep-4c1e9a72.md b/.changes/architecture/feat-record-decision-citation-sweep-4c1e9a72.md new file mode 100644 index 00000000000..076aa02d5e6 --- /dev/null +++ b/.changes/architecture/feat-record-decision-citation-sweep-4c1e9a72.md @@ -0,0 +1,9 @@ +--- +bump: minor +--- + +### Added + +- `record-decision` Step 3: a citation sweep lists, by `file:line`, every tracked line citing the retired record's identifier or path, and proposes pointing each at the new record or dropping it, applied in the same change behind the same yes. It runs for every `adr_retirement` value and for a partial reversal, where only citations of the reversed part change. +- `record-decision audit`: each retire candidate lists the lines citing it; the audit stays read-only. +- `record-decision` Step 4: after a record is written, it offers one pointer comment at the code the decision governs, citing the record in the repository's own form, and writes it only after a yes. diff --git a/plugins/architecture/README.md b/plugins/architecture/README.md index 8716a935d1a..f3179887d58 100644 --- a/plugins/architecture/README.md +++ b/plugins/architecture/README.md @@ -188,8 +188,11 @@ considered options, optional consequences) beside one or two other shapes, and writes nothing at all until you pick one: this plugin never imposes a convention on a repository that has none. When a new decision reverses an existing record, it retires the old one after your yes: deleted (the default), marked superseded, -or archived, per `adr_retirement`. `audit` lists records the code or a later -decision no longer backs, and changes nothing. A team can set its own template, +or archived, per `adr_retirement`, and in the same change repoints or drops +each line that cites the old record, listed by `file:line`. After writing a +record it offers one pointer comment at the code the decision governs, added +only on your yes. `audit` lists records the code or a later decision no longer +backs, with the lines citing each, and changes nothing. A team can set its own template, extra admission triggers and retirement mode in `architecture.yaml` (`reference/config.md`, "Decision-record keys"). The upstream template catalog is cited by URL for you to read, under its own diff --git a/plugins/architecture/evals/rd-audit-lists-gone-record/case.yaml b/plugins/architecture/evals/rd-audit-lists-gone-record/case.yaml index f32058f88dc..a8a96a71d64 100644 --- a/plugins/architecture/evals/rd-audit-lists-gone-record/case.yaml +++ b/plugins/architecture/evals/rd-audit-lists-gone-record/case.yaml @@ -24,6 +24,10 @@ graders: min: 0 max: 0 arm: both + - name: lists-citation + type: regex + pattern: 'cookie_store\.py:1\b' + target: last_message - name: lists-redis-record type: regex pattern: '(?:\b0001\b|ADR[- ]?0*1\b)[^\n]*\bredis\b|\bredis\b[^\n]*(?:\b0001\b|ADR[- ]?0*1\b)' diff --git a/plugins/architecture/evals/rd-audit-lists-gone-record/prompt.md b/plugins/architecture/evals/rd-audit-lists-gone-record/prompt.md index 3c714cb50ab..a414325da48 100644 --- a/plugins/architecture/evals/rd-audit-lists-gone-record/prompt.md +++ b/plugins/architecture/evals/rd-audit-lists-gone-record/prompt.md @@ -1,10 +1,10 @@ --- -description: "The audit lists a record whose decided thing no longer exists in the code as a retire candidate, with evidence, and changes nothing" +description: "The audit lists a record whose decided thing no longer exists in the code as a retire candidate, with evidence and the lines citing it, and changes nothing" tags: [architecture, record-decision, outcome, scaffold] max_turns: 25 timeout_seconds: 600 allowed_tools: [Skill, Bash, Read, Glob, Grep, Write, Edit] -expected_outcome: "The final reply lists ADR 0001 (Redis sessions) as a retire candidate because Redis no longer exists in the code, citing the commit or search that shows it, and does not list ADR 0002 as gone. No Write or Edit call is made and no shell command removes, moves or writes a file." +expected_outcome: "The final reply lists ADR 0001 (Redis sessions) as a retire candidate because Redis no longer exists in the code, citing the commit or search that shows it, lists `src/session/cookie_store.py:1` as a line citing ADR 0001, and does not list ADR 0002 as gone. No Write or Edit call is made and no shell command removes, moves or writes a file." --- /architecture:record-decision audit diff --git a/plugins/architecture/evals/rd-audit-lists-gone-record/samples/lists-citation.json b/plugins/architecture/evals/rd-audit-lists-gone-record/samples/lists-citation.json new file mode 100644 index 00000000000..50f286629db --- /dev/null +++ b/plugins/architecture/evals/rd-audit-lists-gone-record/samples/lists-citation.json @@ -0,0 +1,18 @@ +{ + "pass": [ + { + "answer": "**Gone**\n- 0001 Keep sessions in Redis: commit abc1234 removed redis.\n Cited at src/session/cookie_store.py:1: propose drop." + }, + { + "answer": "ADR-1 citations: cookie_store.py:1 (drop on retirement)." + } + ], + "fail": [ + { + "answer": "**Gone**\n- 0001 Keep sessions in Redis: commit abc1234 removed redis." + }, + { + "answer": "src/session/cookie_store.py mentions ADR 0001." + } + ] +} diff --git a/plugins/architecture/evals/rd-audit-lists-gone-record/scaffold.sh b/plugins/architecture/evals/rd-audit-lists-gone-record/scaffold.sh index f96b058f938..70496e64e79 100755 --- a/plugins/architecture/evals/rd-audit-lists-gone-record/scaffold.sh +++ b/plugins/architecture/evals/rd-audit-lists-gone-record/scaffold.sh @@ -53,6 +53,7 @@ git commit -q -m "Sessions in Redis, orders in PostgreSQL" git rm -q src/session/redis_store.py mkdir -p src/session cat >src/session/cookie_store.py <<'PY' +# Replaces the session store ADR 0001 chose. """Sessions live in signed cookies.""" diff --git a/plugins/architecture/evals/rd-reversal-asks-before-retiring/case.yaml b/plugins/architecture/evals/rd-reversal-asks-before-retiring/case.yaml index c18c34eb6a6..b55dd2acf21 100644 --- a/plugins/architecture/evals/rd-reversal-asks-before-retiring/case.yaml +++ b/plugins/architecture/evals/rd-reversal-asks-before-retiring/case.yaml @@ -24,6 +24,24 @@ graders: min: 0 max: 0 arm: both + - name: citing-file-not-edited + type: tool_used + tool: 'Edit' + input_match: '"file_path":"[^"]*schema\.graphql' + min: 0 + max: 0 + arm: both + - name: citing-file-not-overwritten + type: tool_used + tool: 'Write' + input_match: '"file_path":"[^"]*schema\.graphql' + min: 0 + max: 0 + arm: both + - name: lists-citation + type: regex + pattern: 'schema\.graphql:1\b' + target: last_message - name: names-old-record type: regex pattern: '\b(?:ADR[- ]?0*2|0002)\b' diff --git a/plugins/architecture/evals/rd-reversal-asks-before-retiring/prompt.md b/plugins/architecture/evals/rd-reversal-asks-before-retiring/prompt.md index 952496ca73a..da5ff81764a 100644 --- a/plugins/architecture/evals/rd-reversal-asks-before-retiring/prompt.md +++ b/plugins/architecture/evals/rd-reversal-asks-before-retiring/prompt.md @@ -1,10 +1,10 @@ --- -description: "A decision that reverses an existing record gets a new record naming the old one, and the old record is neither deleted, edited nor moved before the person says yes" +description: "A decision that reverses an existing record gets a new record naming the old one, the line citing the old record is listed with a proposal, and neither the old record nor the citing file changes before the person says yes" tags: [architecture, record-decision, outcome, scaffold] max_turns: 25 timeout_seconds: 600 allowed_tools: [Skill, Bash, Read, Glob, Grep, Write, Edit] -expected_outcome: "The run proposes or writes a new record numbered 0003 that names ADR 0002 and why it was reversed, states the retirement mode (delete by default) and its layer, and ends by asking before retiring 0002. ADR 0002 is not removed, edited or moved." +expected_outcome: "The run proposes or writes a new record numbered 0003 that names ADR 0002 and why it was reversed, states the retirement mode (delete by default) and its layer, lists `src/api/schema.graphql:1` as a line citing ADR 0002 with a proposal to point it at 0003 or drop it, and ends by asking before retiring 0002. ADR 0002 is not removed, edited or moved, and `src/api/schema.graphql` is not edited." --- /architecture:record-decision We are reversing ADR 0002: the public API goes back to REST. Context: partners now use three fixed views, and GraphQL query cost made rate limiting unpredictable. We weighed keeping GraphQL with query cost limits and rejected it because partners could not predict their quotas. Consequences: every partner view needs a versioned endpoint, and moving back to GraphQL later means rewriting the partner SDKs. diff --git a/plugins/architecture/evals/rd-reversal-asks-before-retiring/samples/citing-file-not-edited.json b/plugins/architecture/evals/rd-reversal-asks-before-retiring/samples/citing-file-not-edited.json new file mode 100644 index 00000000000..1b712368c01 --- /dev/null +++ b/plugins/architecture/evals/rd-reversal-asks-before-retiring/samples/citing-file-not-edited.json @@ -0,0 +1,33 @@ +{ + "pass": [ + { + "answer": [ + { + "tool": "Edit", + "input": { + "file_path": "docs/adr/0003-serve-the-public-api-over-rest.md", + "old_string": "a", + "new_string": "b" + } + } + ] + }, + { + "answer": [] + } + ], + "fail": [ + { + "answer": [ + { + "tool": "Edit", + "input": { + "file_path": "src/api/schema.graphql", + "old_string": "# ADR 0002", + "new_string": "# ADR 0003" + } + } + ] + } + ] +} diff --git a/plugins/architecture/evals/rd-reversal-asks-before-retiring/samples/citing-file-not-overwritten.json b/plugins/architecture/evals/rd-reversal-asks-before-retiring/samples/citing-file-not-overwritten.json new file mode 100644 index 00000000000..d7913cc611f --- /dev/null +++ b/plugins/architecture/evals/rd-reversal-asks-before-retiring/samples/citing-file-not-overwritten.json @@ -0,0 +1,31 @@ +{ + "pass": [ + { + "answer": [ + { + "tool": "Write", + "input": { + "file_path": "docs/adr/0003-serve-the-public-api-over-rest.md", + "content": "# 3. Serve the public API over REST\n\nReverses ADR 0002.\n" + } + } + ] + }, + { + "answer": [] + } + ], + "fail": [ + { + "answer": [ + { + "tool": "Write", + "input": { + "file_path": "src/api/schema.graphql", + "content": "# ADR 0003\ntype Query {\n order(id: ID!): Order\n}\n" + } + } + ] + } + ] +} diff --git a/plugins/architecture/evals/rd-reversal-asks-before-retiring/samples/lists-citation.json b/plugins/architecture/evals/rd-reversal-asks-before-retiring/samples/lists-citation.json new file mode 100644 index 00000000000..a9699fc6ae2 --- /dev/null +++ b/plugins/architecture/evals/rd-reversal-asks-before-retiring/samples/lists-citation.json @@ -0,0 +1,18 @@ +{ + "pass": [ + { + "answer": "Lines citing ADR 0002:\n- src/api/schema.graphql:1 `# ADR 0002`: point it at ADR 0003.\nDelete docs/adr/0002-serve-the-public-api-over-graphql.md and repoint that line?" + }, + { + "answer": "Citation sweep (git grep for 0002 and the filename): schema.graphql:1, propose drop. Shall I retire 0002?" + } + ], + "fail": [ + { + "answer": "adr_retirement: delete (default). Delete docs/adr/0002-serve-the-public-api-over-graphql.md now?" + }, + { + "answer": "The schema in src/api/schema.graphql still mentions ADR 0002; retire it?" + } + ] +} diff --git a/plugins/architecture/evals/rd-reversal-asks-before-retiring/scaffold.sh b/plugins/architecture/evals/rd-reversal-asks-before-retiring/scaffold.sh index ed2de656891..21a90148f9f 100755 --- a/plugins/architecture/evals/rd-reversal-asks-before-retiring/scaffold.sh +++ b/plugins/architecture/evals/rd-reversal-asks-before-retiring/scaffold.sh @@ -32,6 +32,7 @@ Partners asked for flexible queries, so the public API is a GraphQL endpoint. MD cat >src/api/schema.graphql <<'GQL' +# ADR 0002 type Query { order(id: ID!): Order } diff --git a/plugins/architecture/skills/record-decision/SKILL.md b/plugins/architecture/skills/record-decision/SKILL.md index aa315f54c0e..fb11377b040 100644 --- a/plugins/architecture/skills/record-decision/SKILL.md +++ b/plugins/architecture/skills/record-decision/SKILL.md @@ -40,7 +40,7 @@ Arguments: `$ARGUMENTS` | Action | Does | |---|---| -| *(bare)* | Records one decision: Steps 1 to 3. The whole argument is the decision text or a file path | +| *(bare)* | Records one decision: Steps 1 to 4. The whole argument is the decision text or a file path | | `audit` | Lists retire candidates and writes nothing: [Audit](#audit) | Only `audit` as the first word selects the audit; any other first word is part of the decision. @@ -117,9 +117,9 @@ everything Step 2 does. 4. Re-read the target directory immediately before writing, confirming no record has appeared since Step 1 that would change the identifier. 5. Write **exactly one** new record, and report its path. Done when `git status --porcelain` shows - that one new path and nothing else, until Step 3 runs. + that one new path and nothing else, until Step 3 or Step 4 runs. -Outside Step 3, do not create, rename, or renumber any other file. Report duplicates and leave them +Outside Steps 3 and 4, do not create, rename, renumber or edit any other file. Report duplicates and leave them where they are. ## Step 2b. No convention @@ -136,7 +136,7 @@ where they are. `git status --porcelain` is exactly what it was before the invocation. When the human chooses in the same session, create only what they chose (the directory plus the -first record, its sections taken from the chosen template) and nothing else. A repository's own +first record, its sections taken from the chosen template) and nothing else, then run Step 4. A repository's own convention, found in Step 1, always wins over `adr_template` and the bundled template. ## Step 3. Retire the record the decision replaces @@ -146,18 +146,33 @@ person picks. The new record's `Considered options` (or the convention's equival retired record by identifier and title and says why it was reversed. A changed decision gets a new record, never an amendment inside the accepted one: an accepted record -is edited in place only to rename a term or to set its status. +is edited in place only to rename a term, to set its status, or to repoint a citation the sweep +below lists. + +**Citation sweep.** Every retirement path runs it, whatever `adr_retirement` says: `delete` and +`archive` break a path citation, and `supersede` leaves a citation naming a decision no longer in +force. Search tracked files with `git grep -n` for the old record's identifier, in each form the +records and existing citations use (`ADR 7`, `ADR-007`, `0007`), and for its filename; report the +patterns searched. Skip the old record itself and the new record's line naming it. List each hit as +`file:line` (code, docs, skills, other records) with one proposal: point it at the new record's +identifier or path, or drop it when there is no new record or the line only made sense with the old +decision. List a changelog or release-note hit as keep: it is history. Done when every hit carries a +proposal, or the report says the search found none. **Partial reversal.** When the new decision reverses only part of a record, keep the old file whatever `adr_retirement` says, and in place of steps 1 to 3: after writing the new record, name the old one and the superseded-in-part status you will set, naming the part, in the words and form the -existing records use. Ask. On a yes, edit only that status; on a no, leave it and say so. When the -records carry no such wording, say so and ask for it. - -1. After writing the new record, name the old one, the resolved `adr_retirement` and its layer, and - what that will do to the old file. Ask. Act only on a yes; on a no, leave it and say so. Done - when the person has answered. -2. Retire it, done when the one change below is on disk: +existing records use, and run the citation sweep, proposing a change only for a citation of the +reversed part and listing the rest as keep. Ask. On a yes, edit that status and the proposed +citation lines only; on a no, leave them and say so. When the records carry no such wording, say so +and ask for it. + +1. After writing the new record, name the old one, the resolved `adr_retirement` and its layer, what + that will do to the old file, and the citation sweep's hits with their proposals. Ask; one yes + covers the retirement and the citation edits. Act only on a yes; on a no, leave them and say so. + Done when the person has answered. +2. Retire it, and edit each proposed citation line as proposed and nothing else in those files. Done + when the citation edits and the one change below are on disk: - `delete`: remove the file. Its number is never reused (discovery's numbering rule). - `supersede`: set the old record's status to superseded by the new identifier, in the words and form the existing records use; edit only that status. Retiring an audit candidate with no new @@ -177,7 +192,17 @@ records carry no such wording, say so and ask for it. live. Done when `git status --porcelain` shows the new record, the one retirement or partial-status -change, and the line's file if it was written, and nothing else. +change, the files whose citations were edited, and the line's file if it was written, and nothing +else. + +## Step 4. Offer a pointer comment + +After a record is written, offer one pointer comment at the module or line the decision governs: one +line in that file's comment syntax, citing the record in the form the repository's records and +citations already use (its identifier, or its path), and no restated reason. Write it only after a +yes; never add one unasked. The citation sweep finds it when the record is retired, so the pointer +does not outlive its record. `/code-tidying:remove-comments` (if enabled) keeps such a pointer. Done +when the pointer is written or declined. ## Audit @@ -195,13 +220,17 @@ what it was before the invocation. record's `file:line`. - **Fails admission**: no real alternative was weighed, or none of the "at least one" conditions holds. Evidence: the record's `file:line`. -3. Report retire candidates grouped by those reasons, each with identifier, title and evidence, then - the count of records still backed. Offer Step 3 for the candidates the person picks; retirement - runs only there, after a yes. Done when the report is delivered. +3. Run Step 3's citation sweep for each retire candidate; the new record is a Contradicted + candidate's later record, and with none the proposal is drop. Done when every candidate has its + hits listed, or none. +4. Report retire candidates grouped by those reasons, each with identifier, title, evidence and its + citation hits, then the count of records still backed. Offer Step 3 for the candidates the person + picks; retirement and citation edits run only there, after a yes. Done when the report is + delivered. ## Hand-off -Commit the record, and any retirement, in the pull request of the change that made the decision; a +Commit the record, and any retirement, citation edits and pointer, in the pull request of the change that made the decision; a decision with no code change gets a pull request of its own. ## Upstream template catalog