Repository navigation
docs(agents): state who owns each topic, from both ends of the pointer - #291
Conversation
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 |
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
✅ SpotBugs ReportNo bugs found (new bugs only — baseline from base branch excluded). |
🧪🔒 Quarantine Lane Report
🔴 expected while the owner PR is open · 🟡🎲 flapper, pass proves nothing · 🚨 a deterministic quarantined test passing means its fix landed: delete its |
b9ae97a to
319ebbe
Compare
astubbs
changed the title
AGENTS.md is a router: it holds what binds every session and points at the doc that
owns the rest. That only works if a reader can tell which side is authoritative from
the side they entered on, and most pointers did not say.
Two already did it right - docs/ci.md ("stated in one place only... Do not restate the
rule here; it has drifted before") and the refactoring pointer ("see the table above for
what it owns"). The rest listed adjacent topics, which reads as further detail rather
than a hand-off. Converted those: testing, releasing, issue-references, copyright,
citations now name the owner and say it wins on conflict.
Three routed docs never stated their half of the contract - bin/AGENTS.md,
docs/refactoring.md and docs/inflight/AGENTS.md - so entering from the doc gave no
signal either. They do now, matching the eight that already did.
Left alone: pointers already carrying the signal, and plain citations, where the
phrasing would be noise. The goal is that a reader can find the owner, not that a
template appears everywhere.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
319ebbe to
1bcf63f
Compare
|
@claude review this |
|
Claude finished @astubbs's task in 2m 32s —— View job Review: docs(agents) router ownership pass
SummaryDoc-only change, does what it says: pointers in Finding: PR body undercounts its own scopeThe body says "Three routed docs now state their half: -concurrently. This document walks through the one-time setup on a Linux VM.
+concurrently. This doc owns setting up and operating them: the one-time setup on a Linux VM, the
+labels, and the service. AGENTS.md carries only the pointer; which lanes are pinned to the
+`highcpu` label, and why, belongs to [`ci.md`](ci.md).That's the same "doc states its half" pattern as the other three, on a file that (per your own grep of prior state) didn't have it before. It's listed in Minor nit (non-blocking)
Everything else — link targets, the |
… role form Two changes to the same rule, in the order they have to happen. FIRST, three shapes made stripQualified report a number as unqualified when the URL right beside it already named the repo: - asciidoc `URL[link text]` - the bare-URL rule matches \S+, so it consumed "...astubbs/issues/65[Enhanced" and left "retry epic astubbs#65]" looking like prose. The new rule must run BEFORE the bare-URL one, or the URL eats the opening bracket and there is nothing left to recognise. - asciidoc `{attr}/path[link text]` - no http prefix at all, so nothing stripped it. This is how the README writes upstream links. - an html anchor wrapped across two lines - suspectRefs works a line at a time, so the single-line rule never sees a complete element. Each half now strips only when its counterpart is absent, which leaves a complete anchor to the original rule and keeps a #NN sitting OUTSIDE the element visible. This was found by the sweep having to work around it: the qualifier had to sit immediately before the number, so "[confluentinc PR astubbs#291 ...]" failed while "[PR confluentinc#291 ...]" passed. With the macro stripped whole, either reads. SECOND, `upstream #NNN` is no longer accepted. The sweep removed its last use, and a tolerated form comes back the moment someone copies older text. Four edits that must move together: the alternation leaves stripQualified; "allows upstream prose" becomes "flags upstream prose"; "still flags trailing items" now expects astubbs#233 too, since the leading `upstream` no longer qualifies the first item; and formatFailure() stops telling authors the form still passes, with the assertion that pinned that wording updated to pin the new state rather than deleted. Stripping MORE is the direction that produces false negatives, and AGENTS.md is explicit that a wrong reference which resolves is worse than a broken one. So the fixtures assert both directions: link macros are accepted, and a bare ref elsewhere on the line, or after a split anchor closes, is still flagged. 30 assertions pass.
1 participant
Description
Doc-only. One commit, five files, +24/-11.
AGENTS.md is a router: it holds the rules that bind every session and points at the topic doc that owns the rest. That split only works if a reader can tell which side is authoritative from the side they entered on — and most pointers did not say.
It failed that way on #258. A reviewer cited AGENTS.md's "the manifest tracks upstream PRs only", so that copy was read as authoritative and amended there — while
docs/upstream.mdhad been stating the same rule, and claiming ownership of the topic in its own opening, the whole time. Both copies read as complete; neither said who won.Pointers now name the owner. Two already did it right —
docs/ci.md("stated in one place only… Do not restate the rule here; it has drifted before") and the refactoring pointer ("see the table above for what it owns"). The rest listed adjacent topics, which reads as further detail rather than a hand-off. Converted: testing, releasing, issue-references, copyright, citations.Three routed docs now state their half.
bin/AGENTS.md,docs/refactoring.mdanddocs/inflight/AGENTS.mdwere routed from AGENTS.md but said nothing from their side, so entering from the doc gave no signal either. Eight others already did; these match them now.Left alone: pointers that already carry the signal, and plain citations, where the phrasing would be noise. The goal is that a reader can find the owner — not that a template appears everywhere.
Deliberately not here
An earlier draft added a script to enforce the reciprocal half in CI. It was cut. A review of it found the guard silently skipped a routed doc (
bin/AGENTS.md— fixed by hand here instead), and that its self-test could not detect the guard checking only one doc of nine. Enforcement machinery for a documentation convention was not worth its own maintenance burden, let alone its own bugs. The convention is a review call, which is what the rule now says.Checklist
docs/features/-N/A - no user-facing feature; these are contributor/agent-facing conventionsN/A - prose only, no executable code in this PR