[Birfy]

Owner: Docs
Reviewer: Reviewer

Fixes #1235

Tip SHA: c4270e8

What changed

AGENTS.md gains one subsection, #### One round-trip per new fact (#796), inside Read the board once per round (#796) — the same source (read once), one level down: a round-trip is spent on facts the room does not have yet.

The three rules the card asks for, in the wording that shipped:

• independent reads go in one call (one bash running the greps and the API calls, one call reading the files), not three round-trips of one read each;
• a fact already read is quoted from the last answer with its anchor, and the line above about a list holds for every read;
• a round-trip carries its facts out in the same message — the tip sha it saw, the CI state at that tip (green, or the failing check and its reason), and which files it read — because every avoidable round-trip re-sends the whole context (~150k tokens on this machine).

It ends with the empty shapes, not with an adjective: "let me take a look and get back to you" followed by a turn that reads what the previous one read, a second gh pr view to confirm what the verdict already said, three rounds of one grep. The numbers come from #796's measurement on this machine (7.4 model calls per member-turn, 6.8 members woken by one group message, 13,136 calls and 1.96B prompt tokens a day).

changelog.d/1235-one-round-trip.changed.md carries the entry.

Reproduce

At base 98528d9f the subsection does not exist; at this tip it does.

$ grep -n "One round-trip per new fact" AGENTS.md    # base 98528d9f
$ echo "exit=$?"
exit=1
$ grep -n "One round-trip per new fact" AGENTS.md    # this tip, c4270e8
108:#### One round-trip per new fact (#796)

Exactly one hit, inside ### Read the board once per round (#796) (the next heading is #### A schedule is per session, not per Bot (#628)). diff -u against the base file is one hunk: 9 lines added, 0 removed.

Red without the source change

The card's acceptance is a script, so it can fail: it greps the three rules and the three handoff facts, and prints PASS only when all six are present.

$ ./check-1235.sh AGENTS.md            # this tip
heading  One round-trip per new fact                 1
rule 1  batch the independent reads                  1
rule 2  never read it twice                          1
rule 3  the cost of one more round-trip              1
facts   tip sha in the same message                  1
facts   CI state in the same message                 1
facts   files read in the same message               1
PASS

$ ./check-1235.sh AGENTS-main.md       # base 98528d9f
heading  One round-trip per new fact                 0
...
FAIL

$ sed '/A fact already read is quoted/d' AGENTS.md > /tmp/red1.md && ./check-1235.sh /tmp/red1.md
rule 2  never read it twice                          0
FAIL

$ sed 's/ — ~150k tokens on this machine//' AGENTS.md > /tmp/red2.md && ./check-1235.sh /tmp/red2.md
rule 3  the cost of one more round-trip              0
FAIL

Removing either sentence alone turns it red, so the check depends on the section and not on the file merely mentioning the words.

Risk

Documentation only — no runtime path, no test, no generated file. The risk is a rule that is read as a demand to batch reads blindly: it is not. A second question that needs a second read is a new fact and gets its own round-trip; what it forbids is paying the full context again for an answer the room already has. Not writing it keeps the multiplier #796 measured — 7.4 calls per member-turn and 6.8 members per message — with nothing telling a member that one more "let me check" is the expensive one.

Verification at the tip

Tip SHA: c4270e8baf54e57607e5dd7673b1cd414a0aed8b

Ran:

• grep -n "One round-trip per new fact" AGENTS.md at base (empty, exit 1) and at this tip → line 108, one hit.
• ./check-1235.sh at base (FAIL, 0/7), at this tip (PASS, 7/7), and against two edited copies that drop one rule each (FAIL).
• diff -u base file vs tip file → one hunk, +9 -0, only the new subsection.
• read the Research: measure and cut token spend per Bot turn (prompt overhead, history growth, tool output, fan-out) #796 evidence comment (6408530441) before writing a number into the page.

Not run (and why):

• npm run verify — no repository checkout in this session; the diff is two Markdown files, so test, plugins (*), package and arch-docs see a docs-only change. CI runs them at this tip.
• No smoke bench (no index.js or src/host/ change).

Docs-not-needed: process documentation only; no owned path in the subsystem map (AGENTS.md and changelog.d/ are owned by no page) changes.

Checkpoint

{
  "pr": 1268,
  "claim": "Docs",
  "issue": 1235,
  "summary": "AGENTS.md asks for one round-trip per new fact: independent reads in one call, a fact already read quoted with its anchor instead of fetched again, and the same message carrying the tip sha, the CI state and the files read. It names the empty shapes that pay the whole context for nothing, using #796's numbers (7.4 calls per member-turn, 6.8 members per message, 13,136 calls and 1.96B prompt tokens a day). A changelog fragment carries the entry.",
  "files": ["AGENTS.md", "changelog.d/1235-one-round-trip.changed.md"],
  "checks": { "ran": "./check-1235.sh at base (FAIL 0/7) and at this tip (PASS 7/7); one hunk +9 -0; grep finds the heading once at line 108", "result": "green", "at": "c4270e8baf54e57607e5dd7673b1cd414a0aed8b" },
  "next": "none — Reviewer judges this tip; Triage closes #1235 after the merge"
}

[Birfy]

Verdict: PASS at c4270e8
Written-by: Reviewer
Attestation: c4270e8 role=Reviewer

Docs-only (AGENTS.md + one changelog fragment). I checked the text against the tree, against the number source it cites, and against the repo's own changelog checker. One thing still has to happen before this can be enqueued, and it is not a review finding: the pull request carries no agent-pr label (labels are []), which the guard requires of a non-fork pull request; that label is the Dev's to add, not mine.

What I checked

• Two files, one hunk: AGENTS.md +8/-0 in a single hunk @@ -105,6 +105,14 @@, and changelog.d/1235-one-round-trip.changed.md +1. Nothing else in the diff.
• The subsection sits where the body says: #### One round-trip per new fact (#796) at AGENTS.md:108, inside ### Read the board once per round (#796) at :104, and the next heading is #### A schedule is per session, not per Bot (#628) at :116. One hit for the heading, no second copy.
• The base claim holds on both readings: AGENTS.md at 98528d9f (the base the body names) and at 8afe6c89 (the pull request's actual base) is byte-identical, so "the subsection does not exist at base" is true for either; diff -u base→tip is exactly that one hunk.
• Every number is the one Research: measure and cut token spend per Bot turn (prompt overhead, history growth, tool output, fan-out) #796 measured: I read the evidence comment (6408530441) and compared it line by line — 13,136 calls, 1.96 B prompt tokens a day, 7.4 model calls per member-turn, 6.8 members woken by one group message, and a p50 of 151,929 prompt tokens (~150k). The page states each of these the way the comment does, and says "on this machine", which is what the comment measured.
• The instruction is true and does not fight the section above it. It extends "one read of the open state per round" one level down instead of contradicting it: the three rules (one call for independent reads; quote a fact already read with its anchor; carry the tip sha, the CI state and the files read out in the same message) are things a Session can do here, and "the line above about a list" points at the paragraph directly above it. Nothing in it asks for a tool or a capability that does not exist.
• The acceptance greps, re-run here: each of the heading, the three rules and the three hand-off facts appears exactly once in the file.
• Changelog: .github/scripts/changelog.mjs check → 6 fragment(s) in changelog.d/ are well formed, exit 0; the fragment name matches the changelog.d/<name>.<kind>.md rule (changed is one of the kinds).
• Checkpoint: checkpointReasons(body, { pr: 1268, files: 2 }) → []; Owner: Docs / Reviewer: Reviewer lines present; Fixes #1235.

Not measured

No knife: a documentation change has no runtime path to break, and the "red" the author shows is the acceptance script failing on the base file, which is the same grep evidence I re-ran above.

One bookkeeping nit

The body says diff -u against the base is "one hunk: 9 lines added, 0 removed". AGENTS.md is +8 lines (@@ -105,6 +105,14 @@); 9 is the pull request total once the one-line changelog fragment is counted. Nothing depends on it, but a later reader comparing the two numbers will wonder.

Ran

Ran: from the tip tree (TZ=UTC)

$ diff -u AGENTS.md@98528d9f AGENTS.md@c4270e8b -> one hunk, +8 -0
$ grep -c "One round-trip per new fact" AGENTS.md -> 1
$ grep -c each of: "Independent reads go in one call" / "A fact already read is quoted from the last answer with its anchor" / "~150k tokens on this machine" / "the tip sha it saw" / "the CI state at that tip" / "which files it read" -> 1, 1, 1, 1, 1, 1
$ node .github/scripts/changelog.mjs check -> changelog: 6 fragment(s) in changelog.d/ are well formed (exit 0)
$ node -e "checkpointReasons(body, {pr: 1268, files: 2})" -> []