Repository navigation
docs(agents): split AGENTS.md into a router and topic docs - #272
Conversation
…e to the rest Every session loads AGENTS.md whole, whatever the task, so its cost is attention: each rule competes with every other one for compliance. It was carrying the full reference for topics most sessions never touch - the release procedure, per-workflow CI descriptions, the mirror format, the copyright provenance rules - and those competed with rules that genuinely bind every task, like never weakening a test to go green. The test applied to each section: does an agent need this regardless of what it is working on? If not, what catches a miss? A rule with a gate behind it - copyright headers, issue references, the quarantine registry, the PR checklist, PR dependencies - is safe to relocate, because forgetting it fails CI and the root file needs only the rule and its enforcer's name. A rule with nothing behind it stays even when situational: worktree ownership, the commit subject format (nothing lints commit messages), "a PR never adds a changelog entry" (the changelog gate checks citations, not this), and keeping the upstream manifest in sync (nothing checks the fork side). Those fail silently, and an agent will not know to go looking. New topic docs, each with a row in the Where-things-live table: testing.md, ci.md, investigating.md, issue-references.md, copyright.md, releasing.md, and upstream.md - the last covering the manifest, the mirrors, the commit trailers and the sweep as one topic. The prior-art checks stay while the method for settling an investigation moves out: an agent mid-debug will not think to open a document about investigating, but one that already has a hypothesis will follow a pointer. Every rule, command, threshold, constant and path survives - verified by sweeping the old file's distinctive tokens across the new set. Relative links resolve, and the two inbound anchors in docs/refactoring.md and docs/inflight/AGENTS.md now point at the doc that holds the rule they promise rather than at a section heading. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Fpk9yEDEhPnbad2WKvZUmP
git log --numstat -- AGENTS.md is a column of additions with almost no deletions, overwhelmingly from learning-capture commits. No commit in the file's history has ever retired a rule that stopped earning its place, which is how it came to hold the full story behind every rule instead of the rule. Nothing can enforce this. Whether a given rule binds every agent or only one topic is a judgement for whoever writes and reviews the change, not something a script can decide, so the mechanism is a written scope block at the top of the file rather than a CI gate. It states the test for what belongs (does an agent need this whatever it is doing), the follow-up for anything situational (what catches a miss - a gate-enforced rule can move out, an unenforced one cannot), and that retiring and relocating is part of adding. Entries are the rule, a one-line why, and a citation; incidents get cited, never retold; no fact appears twice; no rule needs paragraphs defending it against misreadings. Backstops in case the judgement slips, ordered by how early they fire: a section outgrowing a screen, a backstory longer than its rule, a fact in two places, a rule now covered by a script, routine conflicts on unrelated PRs - and, last and weakest, the whole-file line count. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Fpk9yEDEhPnbad2WKvZUmP
… it dropped Review of the restructure found eight pointers elsewhere in the repo that name AGENTS.md headings the split removed, plus several rules that changed meaning or vanished in the move. The pointers were the real defect: nothing checks a prose citation of a heading, so all eight were silent. Six were outright wrong - copyright.yml, check-copyright-headers.sh, pom.xml, a chaos-suite javadoc, the copyright solution doc (which called AGENTS.md the authoritative source for rules it no longer held) and the live 0.6.0.0 release tracker. Two more were misleading rather than broken: QUARANTINED_TESTS.md and CHANGELOG.adoc pointed at sections that survive but no longer hold what was promised. All now point at the doc that owns the content. The changelog edit is a factual correction to existing text, which is the one edit the policy allows. Rules restored or corrected: - "Quarantine is master-state, not PR-state" moved back to AGENTS.md. Only two of the three quarantine rules have a checker; this one lives in a workflow comment, so by the file's own test it belongs in the root. - The copyright rule had been compressed into one sentence that lost "as an incidental or standalone change", permitting a year bump the source rule forbids. Both constraints are back. - docs/ci.md claimed the repo-hygiene jobs do not gate. Both are required status checks. Corrected, and docs/testing.md now says what non-gating means for the quarantine lane precisely: its job is required too, but the test step is continue-on-error, so only the registry audit can fail it. - Restored the docs/solutions/ frontmatter field names, the upstream-pr-analysis.adoc router row, and the worked example showing a PR title carrying both the fork and upstream number. - Deduplicated four facts stated in two places: copyright enforcement, test-utility reuse, release-blocking, and the PR-checklist gate. - bin/AGENTS.md was in neither routing table while the root claimed a complete map. Added. And the lesson that would have prevented the pointer breakage is now a writing rule: grep the whole repo for a heading before moving it, because citations hide in pom.xml, shell headers, workflow YAML and javadoc. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Fpk9yEDEhPnbad2WKvZUmP
…facts
Second review round, against the fix commit itself - which is where new
defects get least scrutiny, and it earned that reputation.
Self-inflicted by the previous commit:
- Restoring the quarantine rule to AGENTS.md left it stated in three
places and made "Two rules bind regardless" a lie. The root now owns it
(nothing enforces it, so that is where the file's own test puts it) and
says three; docs/testing.md and docs/QUARANTINED_TESTS.md point at it
instead of restating it.
- Correcting the gating claim in docs/ci.md and docs/testing.md left
docs/ci.md and docs/QUARANTINED_TESTS.md still calling the quarantine
lane non-gating, so two docs contradicted each other on the same job.
Both now state the mechanism: the job is the required check `tests`, but
its test step is continue-on-error, so red quarantined tests cannot
block a merge.
- The javadoc citation used an absolute blob/master URL, the only one in
any javadoc here; every other doc reference in that same file uses
{@code path}. Matched to the convention.
Stale facts the split carried forward unexamined:
- docs/ci.md named Kafka 3.9.1 as the CI default; the pom has been on
3.9.2 since #198. It now names no version, so it cannot go stale
again.
And the new rules, sharpened by what they missed:
- "Grep before moving a heading" would not have caught the actual
breakage: "Copyright rules for this fork" was a bold sub-item label, not
a heading, and six files cited it. The rule now covers any labelled
block and excludes .git/target from the grep.
- The "never state a fact twice" bullet retold an incident it did not
cite, breaking the rule immediately above it. Trimmed.
- The restored PR-title example put a qualified upstream ref in the
trailing parenthetical, which read as contradicting the subject rule.
Spelled out the distinction: what is forbidden there is a *bare* number.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Fpk9yEDEhPnbad2WKvZUmP
…t never looked A rebase hands you decisions, constraints and sometimes instructions addressed to your branch, and none of them announce themselves. A green build proves the code still compiles; it proves nothing about whether the ground under the design moved. The worked example is the Connect spike (#240, PR #269): the parent's tip commit said in its body that Connect inherits a decision and should extend the second persona rather than re-litigate whether one exists. Never read, so obeyed only by luck. The same window renamed a module - found by tripping over a conflict - and landed STRATEGY.md, found only because the owner asked whether it had been read. This repo makes the failure likelier rather than rarer: every task gets its own worktree, so bases move underneath branches routinely; commit bodies are load-bearing by design, since release notes are generated from the log, which puts the most consequential sentence nowhere near the subject line; and some inherited commits ship coordination mechanisms rather than code - docs/inflight/pr-strategy-doc-merge-triggers.md names which open branches must re-check STRATEGY.md before merging and which explicitly must not, and a branch that never reads it cannot know which list it is on. Applied to this branch on the way in: its base carried the STRATEGY.md commit, unread until now. Re-checked - a docs restructure is hygiene, which that file lists as explicitly not a trigger, and the router row that commit shipped to make STRATEGY.md discoverable survives the restructure intact. A null result, but a checked one. Written up in docs/solutions/ first, then cited from AGENTS.md, per the rule that incidents get cited rather than retold. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Fpk9yEDEhPnbad2WKvZUmP
…line It was filed under PR Discipline, which is what an agent opens at merge prep - and inheriting happens at the start of work, not the end. Cutting a worktree from a master that advanced, merging master in mid-flight, resuming a branch: all of those hand you commits, and all of them precede the design work the inherited decisions would have changed. An agent meeting the rule while drafting a merge-strategy recommendation has already built on ground that may have shifted. It is also the sibling of the section above it. "Before you investigate anything" says read the record before forming a hypothesis; this says read the record before building on a base. Same shape, same silent failure, so they belong adjacent and near the top rather than one of them buried in a shipping checklist. Moved rather than copied - a rule stated in two sections is the duplication this file forbids. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Fpk9yEDEhPnbad2WKvZUmP
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
Dependency Review✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.Scanned FilesNone |
✅ Duplicate Code ReportTwo engines run in parallel for cross-validation. Each has its own thresholds tuned to its baseline - the real safety net is the per-engine "max increase vs base" check. ✅ PMD CPD
No new clones introduced by this PR. ✅ jscpd (language-agnostic)
No new clones introduced by this PR. Powered by astubbs/duplicate-code-cross-check |
|
Claude finished @astubbs's task in 7m 2s —— View job Claude's Review
This is a documentation-only restructuring (splitting
Three findings are posted as inline review comments; finding 1 is text-only above since it targets a file outside this diff. No action taken beyond review, per the request. |
✅ SpotBugs ReportNo bugs found (new bugs only — baseline from base branch excluded). |
Checked, and this PR introduces no duplication between those two files. Its only change to The +0.1 is a token-distribution artifact of swapping one unique string for another inside a comment, not new shared logic. Nothing to refactor here. The PMD CPD engine agrees independently - 0 new clones, duplication flat at 2.48%. |
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
…e the quarantine rule once Two findings from review on #272. The CONCEPTS.md row lost "class names" from its exclusion list when it was compacted: "no file paths, class names, or current config values" became "no file paths or current config values". That narrowed the rule rather than rewording it - an agent writing an entry that cites a class name would no longer see anything telling them not to. Restored. The quarantine master-state rule was then stated three times: in full in AGENTS.md, and restated with its rationale in both docs/testing.md and docs/QUARANTINED_TESTS.md. The rationale now lives once, in AGENTS.md, which owns the rule because nothing enforces it; both topic docs keep the list item as a bare cross-reference so their numbered lists stay complete without repeating the explanation. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Fpk9yEDEhPnbad2WKvZUmP
Tasks
|
The 0.6.0.0 blocker list still called the hard-coded CI Kafka version "the genuine defect... left alone to keep this PR scoped", and cited it as AGENTS.md:183. Both halves are now wrong: the text moved to docs/ci.md in this branch and lost its version entirely, so the defect is fixed and the line numbers point at unrelated content. A future agent working the release checklist would either chase the stale line numbers or re-fix something already fixed. The entry now records the fix and cites sections rather than line numbers, and the two command examples that were never defects keep their do-not-touch note. Found by review on #272, which could not post it inline because the file is outside this PR's diff - the finding would have been invisible to anyone reading only the inline threads. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Fpk9yEDEhPnbad2WKvZUmP
|
Claude finished @astubbs's task in 2m 21s —— View job Tasks
Code review is running in the background (multi-agent review of this documentation restructure). I'll update this comment with findings once it completes.
|
Good catch, and thank you for surfacing it in the summary rather than dropping it when the inline post failed - it would have been invisible to anyone reading only the threads. Fixed in 3ce991a. That entry called the hard-coded version "the genuine defect... left alone to keep this PR scoped", which stopped being true the moment this branch moved the text into The other three findings are fixed and resolved in their own threads, with one dissent: I did not restore "six runners, all online" - reasoning in that thread. |
|
@claude review this |
|
Claude finished @astubbs's task in 5m 2s —— View job Tasks
ReviewVerified the fixes from both prior rounds landed cleanly: the One new finding, introduced by this PR itself:
It's exactly the class of drift this PR's own "grep before moving a heading" rule targets, but that rule (correctly) only fires when moving text within No other content-fidelity issues found: I diffed every citation-repointing file ( |
…ted to The "read the commits you inherit" write-up's Related list still sent readers to AGENTS.md, PR Discipline. Commit 56c7c41 - in this same branch - promoted that rule out of PR Discipline into its own top-level section, on the argument that inheriting a base happens at the start of work, not at merge prep. The backlink was left naming the one section the promotion existed to move it away from, so following it lands a reader exactly where the rule is not. The forward link (AGENTS.md to this file) was already correct; only the return leg drifted. Nothing checks a prose citation, so it would have stayed wrong indefinitely. Swept the class rather than the instance: every citation in the repo naming an AGENTS.md section - .gitignore, .gitmessage, bin/check-issue-refs.sh, bin/worktree-status.sh, docs/ci.md, docs/upstream.md, docs/testing.md, docs/QUARANTINED_TESTS.md, the release blockers, pr-checklist.yml, issue-ref-gate.js and four docs/solutions write-ups. This was the only one pointing at a section that no longer holds what it cites. Found by review on #272. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Fpk9yEDEhPnbad2WKvZUmP
Correct, and fixed in 8687fa3. The backlink now reads Your reading of it is the right one: the forward link was fine, only the return leg drifted, and it drifted because 56c7c41 moved the rule for a reason the backlink then contradicted - it pointed at the one section the promotion existed to move the rule away from. I swept the class rather than the instance, since a single repointed citation invites the next one. Every citation in the repo that names an Worth separating the two sub-classes, because your sweep and mine looked for different things. You swept for citations of removed headings ("CI", "Releasing", "Documented Solutions", "Copyright rules for this fork") and correctly found nothing dangling. This defect is the other shape: the cited section still exists, so a heading-existence check passes - what moved was the content out of it. That is the harder one to catch, and it is why your finding is a real one rather than a nit. One I looked at and left alone, for the record: |
|
Claude finished @astubbs's task in 5m 13s —— View job Tasks
ReviewThe latest fix is correct. Commit 8687fa3 repoints the "Related" backlink in I also re-swept for the same defect class the author flagged — a citation naming a section that still exists but whose content moved elsewhere — across every remaining prose citation in the repo ( Independently re-verified two of the PR's factual claims rather than trusting the description:
No new findings. Between this round and the three that preceded it, every issue raised (CONCEPTS.md class-names exclusion, triplicated quarantine rule, stale Kafka version, and this backlink) has been fixed and verified to land correctly. |
Merges origin/master (d6a2bf5) into the AGENTS.md restructure. Four commits inherited; two of them act on this branch. d5a2ccd "gh addresses upstream by default, and the failure is silent" added a 46-line section plus six command qualifications to the file this branch rewrote wholesale, so it conflicted rather than merged. Resolved against this PR's own rule: nothing enforces the gh default-repo trap and the failure is silent, so the rule stays in the root file even though it is situational - it is the archetype the "what catches a miss" test was written for, and it has to be read before an agent's first command. What did move is the story. "Cite incidents, never retell them" applies to the two paragraphs that argued the case, and the incident already had a durable home: docs/solutions/workflow-issues/ compound-tooling-breaks-in-worktrees-and-forks-2026-08-07.md section 3 is the same defect, written up on 2026-08-07. The narrative and the loud-vs-silent distinction went there and are cited from the root; the actionable pair (gh repo set-default, plus the deliberately unqualified verification) stayed in the root, stated once. No fact from d5a2ccd was dropped. Its six command qualifications were re-applied where this branch had moved the commands to: the prior-art table and the PR-template bullet in AGENTS.md, the chaos dispatch in docs/testing.md, the job-log recipe in docs/ci.md (including the "--log flag on gh run view" rewording, which exists so the paragraph does not read as a recipe), and the closing-references lookup in docs/issue-references.md. d6a2bf5 lowercased docs/QUARANTINED_TESTS.md, docs/TODO_INDEX.md and docs/SELF_HOSTED_RUNNER.md. Git merged the renames with no conflict and left this branch's citations of the old names pointing at nothing, silently - no CI check resolves a relative markdown link. Fixed in AGENTS.md (routing table and the ownership table), docs/testing.md and docs/ci.md; master's own sweep had already fixed docs/inflight/AGENTS.md and docs/refactoring.md, which came through the auto-merge. Nothing in the tree matches the old names now, docs/plans/ included - no category was skipped. The other two commits are build-side (ossindex audit, central-publishing pinning) and merged into pom.xml untouched. Verified: check-issue-refs.sh and check-copyright-headers.sh clean; check-quarantine-registry.sh consistent and todo-index.sh --check up to date, so the renamed generated docs and their scripts still agree; every relative markdown link in AGENTS.md and the seven topic docs resolves against the filesystem (44 links, 0 broken - 76 across all of docs/). AGENTS.md is now 415 lines, past its own ~400-line backstop; the overrun is the inherited section and is called out rather than paid for by cutting an existing rule. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Fpk9yEDEhPnbad2WKvZUmP
|
Claude finished @astubbs's task in 6m 55s —— View job Tasks
Review (round 5)Re-checked all four previously-fixed findings from earlier rounds and confirmed they're still landed correctly: One new, low-severity finding, posted inline on The "full discipline in No other issues found. |
`docs/quarantined-tests.md` promised the "full discipline" lived in `docs/testing.md` and the `@Quarantined` javadoc, but rule 2 - quarantine is master-state, not PR-state - is stated only in AGENTS.md, because it is unenforced and this split keeps unenforced rules in the root. The pointer now names all three sources instead of overselling two. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Fpk9yEDEhPnbad2WKvZUmP
|
Claude finished @astubbs's task in 3m 15s —— View job Tasks
Review agents are running now (this is round 6 — four prior rounds already found and fixed several issues). I'll update this comment with findings once they complete.
|
#272 split AGENTS.md into a router plus topic docs, relocating the per-workflow CI reference to docs/ci.md. This branch's only two AGENTS.md edits - the `dependency-audit.yml` entry and the amendment to "there is no scheduled build, deliberately" - live in exactly that relocated section, so both move to docs/ci.md and AGENTS.md resolves to master's version unchanged. Verified the router retains no scheduled-build, cron or ossindex rule that would now contradict them: it has none. A clean textual merge would have been the wrong answer here rather than the right one. Git had no way to know the section had moved files, so the choice was between a conflict and silently stranding both additions in a router doc while the real CI reference lived elsewhere. Condensed to the destination file's conventions - bare workflow filename, plain hyphen, 95-column wrap - since the whole point of that split was to stop the per-workflow list regrowing into narratives. One clause did not survive: the flat claim that "Dependabot misses transitive components entirely". That is exactly the assertion docs/inflight/ci-ossindex-lane-reassessment.md now qualifies at length, and it does not belong stated baldly in a reference doc that will outlive the current state. The schedule justification it was bundled with - that nothing else notices an unchanged tree acquiring a new advisory - is kept. Also checked aa61238 (the rename to Parallel Consumer for Apache Kafka) against this branch: no impact. It changes each pom's <name>, while bin/check-ossindex-audit.sh keys on plugin output strings ("Checking for vulnerabilities;", "Failed to fetch component-reports") and on artifactId coordinates, neither of which the rename touches. No file on this branch referenced the old project name. Gates re-run after the merge: actionlint clean on both workflows this branch touches (the two findings it reports are pre-existing on master, in files this branch does not touch), bin/check-action-versions.sh ok, bin/check-shell-sigpipe.sh ok, and all bin/check-ossindex-audit.sh self-tests pass. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01STG7ygSMtmFuu36BiqdA1m
#272 moved "there is no scheduled build, deliberately" out of AGENTS.md into docs/ci.md. This header cited the rule by its old home, so the pointer went stale the moment master landed - the kind of reference that rots silently because nothing checks it. Swept the rest of this branch for the same breakage: the only other AGENTS.md citation is bin/check-ossindex-audit.sh's "bin/AGENTS.md -> Scripts that guard other scripts", and that file and section both still exist. No other stale anchors. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01STG7ygSMtmFuu36BiqdA1m
The merge of master was clean and wrong. git resolves renames and restructures without a conflict, so four citations on this branch kept pointing at files, line numbers and a sentence that no longer exist, and nothing in CI reads a prose citation. All four were silent. - `docs/TODO_INDEX.md` -> `docs/todo-index.md`. #270 lowercased the three shouting docs. This one is not cosmetic: it sits in the R5 sweep inventory as an actionable checklist item, so a future session executing the rename would have been sent to a path that does not exist, next to a correct instruction to regenerate it. - `pom.xml:723-724,750` -> `:743-744,770`. The surefire excludes and the failsafe include moved 20 lines when #259 added the central-publishing pluginManagement block. §6's claim - that the unit/integration split keys on the `integrationTest*` path segment and so survives the package move - was still true, but pointed at the compiler `<source>` element and an unrelated comment. Added what the lines are, so the next drift is detectable by reading rather than by counting. - The `=== Improvements` changelog quote, in both §8 and the release blocker. #276 deleted the exact sentence both quoted ("Java package names ... are unchanged, so imports are unaffected") while renaming the project, for a reason unrelated to this branch. The underlying warning survives - the `== 0.6.0.0` section still asserts the groupId is the only required change, in its opening paragraph and in the `=== Breaking` bullet - so both now name those two passages instead, and §8 records that the third is already gone so nobody hunts for it. - The "links to confluentinc that legitimately remain" item named `AGENTS.md` as one file. #272 split it into seven topic docs and three of them carry such links. Replaced the fixed filename list with the grep that produces it, since the same split will happen again. Verified rather than assumed, because every one of these fails silently: zero matches for the three old SCREAMING_CASE names anywhere outside .git; all 40 repo-relative backtick path citations in the branch's three docs resolve, the single exception being `bin/rename-packages.sh`, a deliberate forward reference to work in flight elsewhere; all 7 relative markdown links and all 8 adoc `link:` targets resolve; and the 24 `path:line` citations were checked by reading the cited line and confirming it still says what the prose claims. check-issue-refs, check-copyright-headers, todo-index --check and check-quarantine-registry are all green, and README.adoc regenerates byte-identical from the template, so master's branding rename merged into the generated file correctly rather than being hand-patched. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Fpk9yEDEhPnbad2WKvZUmP
#272 split AGENTS.md into a router plus seven topic docs, which conflicted with this branch's one addition to the Testing section. Resolved by that commit's own placement rule rather than by keeping the text: a situational rule stays in the root only when nothing catches a miss, and nothing in CI detects someone re-adding -Dsurefire.rerunFailingTestsCount. So the rule stays in the root, recompressed to the new house style - the rule, a one-line why, and a citation - with the incident left in docs/solutions/ where it already lives rather than retold inline. Root Testing now states four binding rules instead of three. Also repoints this branch's commitTimeout write-up at docs/testing.md for the ambient-probe threshold caveat. The split moved that caveat's detail out of AGENTS.md, leaving the citation resolving to a one-line summary instead of the thresholds it promises - the same defect class #272 reported fixing in six other files. Swept this branch's remaining AGENTS.md citations (Testing, Before you investigate anything, PR Discipline): all three labels survive the split, so nothing else needed moving. Note for whoever adds the next root rule: AGENTS.md is now 424 lines, past the ~400 backstop #272 set for itself. It arrived over that line at 415; this adds nine. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XXViiRK9G6aHhYFoL3RTst
Review finding on #224. The earlier sweep on this branch checked whether the AGENTS.md headings a citation named still existed, not whether the content the citation claimed was still under them. #272 kept the headings and moved the content, so that test could not detect the defect it was looking for, and two instances survived in the same file the sweep had already edited for exactly this reason. - The related-PRs entry said #220's probe correction is "in AGENTS.md". Historically true, so this records the relocation rather than rewriting it: the thresholds are now in docs/testing.md and the settling method in docs/investigating.md. - "Its §11 control-arm method is now promoted into AGENTS.md" was simply false. AGENTS.md:151-152 explicitly hands hypothesis-settling off, and the method is at docs/investigating.md:13-18. Repointed there. Re-swept the branch on the corrected test - every doc-location citation in every file this PR touches, checked against where the content actually lives now, not against whether the heading survived. The remaining one, "AGENTS.md (Testing) - carries the no-retry rule and the quarantine alternative", still holds: root Testing states both. The two inflight entries cite no doc locations at all. Both new relative links resolve. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XXViiRK9G6aHhYFoL3RTst
Description
AGENTS.mdis loaded into every agent session whatever the task, so its cost is not tokens butattention: every rule competes with every other for compliance. It had grown to hold the full
reference for topics most sessions never touch - the release procedure, per-workflow CI
descriptions, the mirror format, the copyright provenance rules - alongside rules that genuinely
bind every task, like never weakening a test to make it pass.
This splits it into a router plus topic docs: the root keeps the rules that bind every agent,
plus a complete map to everything else.
The test applied to each section: does an agent need this regardless of what it is working on?
If not, what catches a miss? A rule with a gate behind it - copyright headers, issue references, the
quarantine registry, the PR checklist - is safe to relocate, because forgetting it fails CI, so the
root needs only the rule and its enforcer's name. A rule with nothing behind it stays even when
situational: worktree ownership, the commit subject format, "a PR never adds a changelog entry",
keeping the upstream manifest in sync. Those fail silently, and an agent will not know to go looking.
New topic docs, each with a row in the Where-things-live table:
testing.md,ci.md,investigating.md,issue-references.md,copyright.md,releasing.md, andupstream.md(themanifest, mirrors, trailers and sweep as one topic).
A
How to write this filesection records the maintenance rules, so future additions inherit theformat instead of regrowing the narratives, and makes retiring and relocating part of adding.
git log --numstat -- AGENTS.mdwas a column of additions with almost no deletions: no commit inthe file's history had ever retired a rule that stopped earning its place.
Also here: read the commits you inherit
A separate rule, added while this branch was open and separable if you would rather it shipped
alone. A rebase or merge hands you decisions, constraints and sometimes instructions addressed to
your branch, and none announce themselves - a green build proves the code compiles, not that the
ground under your design held. Written up in
docs/solutions/workflow-issues/read-the-commits-you-inherit-2026-08-10.mdand cited from a rootsection beside Before you investigate anything, its sibling: one says read the record before
forming a hypothesis, the other before building on a base.
Applied to this branch on the way in. Its own base carried the
STRATEGY.mdcommit, unread untilthen; that commit ships
docs/inflight/pr-strategy-doc-merge-triggers.md, which names the branchesthat must re-check
STRATEGY.mdbefore merging and those that explicitly must not. Re-checked: adocs restructure is hygiene, which that file lists as not a trigger, and the router row the commit
shipped to make
STRATEGY.mddiscoverable survives intact. A null result, but a checked one.Corrections found along the way
AGENTS.mdlabel the split removed, and two more promised content that hadmoved -
pom.xml, the copyright scanner's own header, a workflow, a chaos-suite javadoc,CHANGELOG.adoc, and the live 0.6.0.0 release tracker. Nothing checks a prose citation, so everyone was silent. All repointed.
docs/ci.mdclaimed the repo-hygiene jobs do not gate. Bothshell: sigpipeandworkflows: action versionsare required status checks. Corrected.docs/testing.mdnow alsostates what "non-gating" means for the quarantine lane precisely: its
testsjob is required too,but the test-running step is
continue-on-error, so red quarantined tests cannot block a merge.docs #197: fix the two release-blocking factual errors in the 0.6.0.0 artefacts #198. It now names no version, so it cannot go stale again.
shell-hygiene.ymlbullet described a workflow that no longer exists, superseded byrepo-hygiene.ymland documented twice.Every rule, command, threshold and path from the original survives, verified by sweeping the
pre-split file's distinctive tokens across the new set. One class was dropped deliberately: a
cached mechanical count with no failure detector. The pre-split file asserted "six runners, all
online", which is wrong the moment a runner is added, removed or goes offline and which nothing
would ever catch - and the paragraph beside it already tells you to ask
gh api repos/astubbs/parallel-consumer/actions/runnersinstead.What review kept finding
The first round found eight defects. The second reviewed the fix commit and found seven more, six
of them introduced by the first round's fixes: a rule restored into three places at once, two docs
left contradicting each other on the same job, a javadoc citation breaking the convention used
elsewhere in the same file. The new "grep before moving a heading" rule would not have caught the
breakage it was written for - the casualty was a bold sub-item label, not a heading - so it now
covers any labelled block.
Later rounds converged on one defect shape: a citation that still resolves, but no longer to what
it cites. A backlink in the
read-the-commits-you-inheritwrite-up still pointed at PR Disciplineafter this branch promoted that rule out of it, and
docs/quarantined-tests.mdpromised the "fulldiscipline" lived in
docs/testing.mdwhen the deliberately-unenforced rule 2 is kept inAGENTS.md.Both survive a heading-existence check, because the heading is fine and the content moved. That is
the argument for the doc-link gate named below rather than another manual sweep.
Not addressed here
docs/plans/still name moved sections. The repo's convention is that a datedplan goes stale once its work lands, so sweeping them would contradict the rule the router states.
spotbugs,which no job produces any more -
maven.ymlemitsstatic: spotbugs. A live gap in branchprotection, outside this PR.
durable gap; a
bin/check-doc-links.shwired intorepo-hygiene.ymlbesideshell: sigpipeisthe obvious follow-up, left out to keep this PR to one idea.
Checklist
N/A: documentation and comments only, no behaviour to test. Verifiedinstead by a token sweep against the pre-split file, relative-link resolution, the
issue-reference and copyright gates, the sigpipe and action-version guards, and a
parallel-consumer-coretest-compile, since one javadoc was edited..github/workflows/copyright.ymlwas repointed; no runner, permission, trigger or step logicchanged, and no self-hosted lane is touched.