Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 2 additions & 8 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -201,9 +201,6 @@ Two consequences worth internalizing:
design were one command each; run on day one they would have prevented
most of five review rounds.

When several reviewers are on one PR, the classes are what make their
findings cheap to reconcile — *Measured* from one and *Read* from
another on the same point is a signal, not a contradiction.

## Predicates That Predict Another Program

Expand Down Expand Up @@ -254,8 +251,8 @@ both reproduce on `main`:
passes, while node's loader skips any block not labelled exactly
`CERTIFICATE`.

We were not careless. We measured a write→rename race at 0.88 ms over
5,000 iterations, grepped the rendezvous path, checked file modes —
That review was not lazy — it measured a write→rename race at 0.88 ms
over 5,000 iterations, grepped the rendezvous path, checked file modes —
**and never fed the guard a realistic bundle.** The shape to watch for
is *verifying the checkable parts and reasoning about the deciding
part*, and it is invisible from inside because the deciding function
Expand Down Expand Up @@ -297,9 +294,6 @@ answered with the wrong oracle.
The runtime fact stayed unexamined for three further rounds, until it
was measured directly against the shipped binary.

The failure is not that the fact was hidden. It is that reviewing a
diff invites reasoning from the diff, and project history is exactly
the context a diff does not carry.

### The expectations are part of what gets checked

Expand Down
34 changes: 34 additions & 0 deletions docs/code-reviews/pr-305-round-1-codex.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
# Review: AGENTS.md editorial trim in PR #305

Date: 2026-08-04
Reviewed: `AGENTS.md` at `69c1c9f8fe6fcdcd92fad5e0a5479fac808e8710`
Round: 1
Label applied: `approved-by-codex-agent`

## What Is Correct
- **Read** `AGENTS.md:196-205`, `AGENTS.md:239-259`, and `AGENTS.md:267-304`: the diff removes exactly two explanatory paragraphs and rewrites one sentence without deleting the measured `0.88 ms` / `5,000 iterations` facts or the operative rule text. The full removal set is:
1. `AGENTS.md` old lines 204-206: "When several reviewers are on one PR..."
2. `AGENTS.md` old lines 300-302: "The failure is not that the fact was hidden..."
3. `AGENTS.md` old lines 257-258 rewritten as current `AGENTS.md:254-255`, preserving the same measurements and the same cautionary point.
- **Read** `AGENTS.md:198-202`: deleting the reviewer-reconciliation paragraph does not change Evidence Class meaning. The binding rule remains in the three class bullets plus the hard rule against repeating unmeasured load-bearing claims.
- **Read** `AGENTS.md:269-295`: deleting "The failure is not that the fact was hidden..." does not change the README/history rule. The mandatory instruction is already stated in `AGENTS.md:269-273`, and the concrete Bun/BoringSSL example remains intact in `AGENTS.md:275-295`.
- **Read** `AGENTS.md:254-259` against old `AGENTS.md:257-262`: the "We were not careless" compression is editorial only. It still records the measured write→rename race, the `5,000`-iteration count, the additional checks (`grep` / file modes), and the lesson that the deciding path was never exercised with a realistic bundle.
- **Read** `AGENTS.md:152-163`: keeping the #296 CI timestamp table remains justified. It is still the section's only compact, falsifiable evidence that the CI rule answers a real failure mode rather than asserting one.
- **Measured** `gh pr view 305 --json statusCheckRollup` on 2026-08-04: `test (18)`, `test (20)`, and `test (22)` were `IN_PROGRESS`; GitGuardian and Snyk were `SUCCESS`. Because this PR is docs-only and the review question is purely editorial fidelity, approval with CI pending is proportionate here, and the pending state is stated explicitly.
- **Read** `git diff origin/main...HEAD -- AGENTS.md`: the trim introduces no orphaned references, broken transitions, or mismatched pronouns. The surrounding sections still read coherently after each deletion.

## Blockers
None.

## What Needs Attention
- **Read** `AGENTS.md:152-163`, `AGENTS.md:269-295`: my round-4 view has not moved. After seeing this smaller trim and re-reading the merged text with Grok's counter-position in mind, I still would not endorse the larger cut here. The remaining narrative blocks I would defend are the ones carrying measured examples or the shortest path from rule to failure mode.

## Bloat / Non-Functional
None.

## Recommendations
- **Read** `AGENTS.md` diff as a whole: merge this trim as-is.
- **Reported** from the PR body, not independently measured by me: Grok's broader "`~45 lines`" target is useful as an outside readability pressure test, but I would treat it as a future rewrite brief, not as justification for more cutting in this PR without re-verifying each surviving rule against the repo record.

## Bottom Line
Codex review: **approve.** **Read** `AGENTS.md` at `69c1c9f` against merged `2a4a033`: this PR drops no verifiable claim, changes no rule meaning, keeps the only measured evidence that makes the CI rule falsifiable, and introduces no editorial breakage. CI was still pending on the Node 18/20/22 matrix when I reviewed; that state is noted here rather than assumed green. — Codex review
Loading