Skip to content

feat(architecture): sweep citations on ADR retirement and offer a pointer comment - #16552

Merged
kyle-sexton merged 4 commits into
mainfrom
feat/record-decision-citation-sweep
Nov 16, 2026
Merged

kyle-sexton merged 4 commits into
mainfrom
feat/record-decision-citation-sweep

Conversation

@kyle-sexton

Copy link
Copy Markdown
Member

No related issue: owner-decided change to /architecture:record-decision, with no tracking issue

Summary

Retiring an ADR left every line that cited it pointing at a record that no longer exists, is archived, or no longer holds. /architecture:record-decision now finds and fixes those citations in the same change as the retirement, and offers one pointer comment at the code a new record governs.

Fix

  • Citation sweep (Step 3). For every adr_retirement value (delete, supersede, archive) and for a partial reversal, git grep -n the old record's identifier forms and filename across tracked files, list each hit as file:line, and propose pointing it at the new record or dropping it. A changelog or release-note hit is listed as keep. The edits apply behind the existing yes, in the same change. An accepted record may now also be edited to repoint a citation.
  • Audit. Each retire candidate lists its citing lines (a Contradicted candidate's later record is the successor; with none, the proposal is drop). Audit stays read-only.
  • Pointer offer (new Step 4). After a record is written, offer one one-line pointer comment at the module or line the decision governs, in the repository's ADR id or path form, with no restated reason; written only on a yes. The sweep finds it when the record is retired, so it does not outlive its record.
  • Done conditions, the Variables table, Step 2b and the Hand-off section updated to match; plugin README paragraph updated.
  • Evals: rd-reversal-asks-before-retiring and rd-audit-lists-gone-record scaffolds gain a citing line, with a lists-citation regex grader each and a citing-file-not-edited grader on the reversal case, all with pass and fail samples.

Verification

  • scripts/check-affected.sh: 17 passed, 1 skipped (ruff, no Python changed).
  • plugins/evals/skills/validate/scripts/validate-cases.py plugins/architecture/evals: no FAIL; only existing WARN lines.
  • Pre-push hook (check-affected, guardrails reference and content checks): passed.
  • The eval cases were not run against a model.

Related

  • /code-tidying:remove-comments (if enabled) is being taught separately to keep such a pointer comment; this PR does not touch that plugin.

session: AI Hero

🤖 Generated with Claude Code

…nter comment

record-decision Step 3 now lists every tracked line citing the retired
record's identifier or path, by file:line, and proposes pointing each at
the new record or dropping it, applied in the same change behind the
existing yes. It runs for every adr_retirement value and for a partial
reversal. audit lists each candidate's citing lines and stays read-only.

New Step 4 offers one pointer comment at the code a new record governs,
written only after a yes; the citation sweep keeps it from outliving its
record.

The reversal and audit eval cases gain a citing line and a grader that
the reply lists it by file:line.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@kyle-sexton
kyle-sexton marked this pull request as ready for review November 16, 2026 15:43
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-16T15:45:49.977109Z 137c7f2 Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

… unchanged

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 137c7f24f0

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@github-actions

Copy link
Copy Markdown
Contributor

Lane run report

Field Value
Activity pr-refine/fix-docs
Model rung 0
Leg handoff
Run job success
Activity step skipped
Commits pushed none (read lane)
Run 43899609895

Failed GitHub API calls

Method Path Status
GET /repos/{repo}/git/ref/tags/* 404

@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

claude-security-review needs no new review of 2203ddc43abde2246561478b082299f3c6b97357: no file of this pull request changed since the review of 5251c7d.

Security review (incremental, blocking only): no security issues found

This was an incremental review covering the changes since a5bf3ec2. I read every hunk of both files in scope:

  • plugins/architecture/evals/rd-reversal-asks-before-retiring/case.yaml gains a tool_used grader, citing-file-not-overwritten. It fails the eval when a Write call's file_path matches schema\.graphql. It is a static regex inside eval configuration and runs nothing.
  • plugins/architecture/evals/rd-reversal-asks-before-retiring/samples/citing-file-not-overwritten.json is a new fixture with one pass case and one fail case. It is plain JSON test data.

Neither file matches a trusted-path glob. The change touches no workflow, token, kill switch, merge hold or trusted-actor list, no plugin.json or marketplace.json, and no instruction surface. It reaches no trust boundary.

Usage. The added grader is checked against the same eval transcripts, so at most it adds a negligible amount of prepaid model usage when evals run. This is not a billing change.

Earlier posts. This lane already reviewed head a5bf3ec2, so this pass was blocking only and reported only CRITICAL and IMPORTANT findings. There were none. The earlier summary comment had no findings to restate.

critical-findings: 0

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

claude-review: 1 inline finding(s) on a5bf3ec2e3334762e0c9ef551676c576a28665e7; the summary is in this lane's pull request comment.

claude-lane: claude-review

@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

claude-review needs no new review of 2203ddc43abde2246561478b082299f3c6b97357: no file of this pull request changed since the review of 5251c7d.

Code review (incremental, blocking only): PR #16552

Scope: the push since a5bf3ec2 changed two files, and I read every hunk of both in .claude-lane/incremental.diff:

  • plugins/architecture/evals/rd-reversal-asks-before-retiring/case.yaml
  • plugins/architecture/evals/rd-reversal-asks-before-retiring/samples/citing-file-not-overwritten.json

This lane already reviewed an earlier head, so this review reports blocking findings only.

Result: no new findings. This push fixes my earlier finding (#16552 (comment)): the citing file was guarded against Edit but not Write.

  • New grader. citing-file-not-overwritten (tool_used, Write, input_match: '"file_path":"[^"]*schema\.graphql', min 0, max 0, arm both) now sits next to citing-file-not-edited. It mirrors the existing old-record-not-edited / old-record-not-overwritten pair (case.yaml:34-40).
  • New sample file. It uses the same layout as samples/old-record-not-overwritten.json.
  • Pass cases: a Write to docs/adr/0003-...md and an empty answer. The regex matches neither, so the count stays 0.
  • Fail case: a Write to src/api/schema.graphql. The regex matches its file_path, so the count reaches 1, which is over max: 0.

Not verified by me: the owner's "Offline eval validator: no FAIL" is their own claim; I ran nothing.

Settled threads: the owner's reply on that thread is a decision ("CORRECT … Added citing-file-not-overwritten"), and its lines have not changed since it was resolved. Nothing to raise again.

Usage: one more offline grader in the eval case. It makes no extra model calls.

Verifier dropped 0 of 0 candidates.

@kyle-sexton kyle-sexton added the do-not-merge Hard merge gate: do not merge while applied. label Nov 16, 2026
@kyle-sexton

Copy link
Copy Markdown
Member Author

Held: Step 4 says /code-tidying:remove-comments keeps the offered ADR pointer, which holds only once #16553 adds that keep. Released when #16553 is merged and this branch is updated from main.

kyle-sexton and others added 2 commits November 16, 2026 10:55
citing-file-not-edited counted only Edit calls, so a Write over
src/api/schema.graphql passed. citing-file-not-overwritten counts Write
calls to that file, mirroring the old-record-not-overwritten pair.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kyle-sexton kyle-sexton removed the do-not-merge Hard merge gate: do not merge while applied. label Nov 16, 2026
@kyle-sexton
kyle-sexton added this pull request to the merge queue Nov 16, 2026
Merged via the queue into main with commit fc198bb Nov 16, 2026
66 checks passed
@kyle-sexton
kyle-sexton deleted the feat/record-decision-citation-sweep branch November 16, 2026 16:23
@github-actions github-actions Bot added the merge-path: owner-agent Post-merge accounting record (README.md, Merge paths) label Nov 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

merge-path: owner-agent Post-merge accounting record (README.md, Merge paths)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant