[jdsika]

What

Adopt CLAUDE.md's stricter comment standard in AGENTS.md, so the two agent instruction files
stop contradicting each other on the one line where they differ.

Why

AGENTS.md and CLAUDE.md are byte-identical apart from a single bullet, and that bullet is a
contradiction rather than a Claude-specific tweak:

file	rule
AGENTS.md	"Comments explain invariants, not syntax. Code readable without comments."
CLAUDE.md	"Comments: default none, hard max 1 line", with an explicit list of banned forms

Agents load one file or the other depending on which tool is driving — Copilot and Codex read
AGENTS.md, Claude Code reads CLAUDE.md — so the same codebase has been getting written to two
different standards, and neither copy mentions that the other exists. A reviewer quoting one at an
agent that loaded the other is a disagreement nobody can resolve from the repository.

The stricter rule wins because it is the one written for this codebase, it is specific enough to
act on without interpretation, and it is what the recent C code actually follows. "Explain
invariants, not syntax" is the same intent stated loosely enough that two readers reach opposite
conclusions about a four-line rationale comment.

This is cheap to get right and expensive to leave alone: a vague standard is exactly the kind of
thing that turns into a round of review nits on every pull request, which is precisely the cost
this batch of work is trying to remove.

How tested

• pre-commit run --all-files
• make rebuild (required if .c/.h changed — zero new warnings)
• make test-unit / make test-eval
• make test-c (C sim logic)
• make test-notebooks (notebooks touched)
• make test-docker-smoke (dynamics, rewards, observations, or training loop touched)
• make -C tests/drive perf (hot paths touched)
• make test before marking ready (unit + eval + c + notebooks — does not include
  docker-smoke or perf; those are the two boxes above)

Documentation-only: one bullet in one Markdown file. No code, config, notebook or workflow is
touched, so the suites above have nothing to exercise. pre-commit ran because it is what checks
trailing whitespace and end-of-file on Markdown:

$ pre-commit run --all-files
trim trailing whitespace.................................................Passed
fix end of files.........................................................Passed
ruff format..............................................................Passed
clang-format.............................................................Passed

Verified by diff that the two files are now identical except for the fork-only block, which is
fork-only content and must stay out of this commit.

New behaviour is covered by a new test / the fix has a test that fails without it:

Not applicable — prose.

Stack hygiene

• forkctl check-commit passes (--chore on a fork-only branch)
• Conventional Commits subject, rebased on current integration/3.0

== check-commit
  PASS  exactly one commit on the branch
  PASS  rebased directly onto origin/integration/3.0
  PASS  subject is well formed: 'docs: align the comment standard across AGENTS.md and CLAUDE.md'
  PASS  fork-only markers are well formed
  PASS  fork-only state is intact
  PASS  no registered fork-only file in the diff
  PASS  fork-only branch filters are untouched in shared workflows
  PASS  fork-only blocks in shared files are unchanged
== check-commit: OK

The last check is the interesting one: AGENTS.md carries the fork-only <!-- fork:begin -->
block, so the file is shared with upstream and only the fork-only hunk is protected. This commit
changes a line well outside it, which is allowed and is the whole point.

Merge gate

• Gate 1 — CI green on the final commit (no "green except a flake")
• Gate 2 — adversarial review posted by someone other than the author; findings fixed or
  explicitly accepted in the thread
• Gate 3 — upstream-readiness proven: forkctl mirror <slug> --sha HEAD passes, i.e. the
  commit cherry-picks onto pure upstream/3.0 and its diff is upstream-clean

Gate 3 result:

== mirror/align-agent-comment-standard
        feature commit b1fec6d34  docs: align the comment standard across AGENTS.md and CLAUDE.md
  PASS  cherry-picks onto pure upstream without conflict
  PASS  no registered fork-only file in the mirror diff
  PASS  no fork-only marker added anywhere in the mirror diff
        mirror diff touches 1 file(s):
          AGENTS.md
== mirror/align-agent-comment-standard: OK

Upstream disposition

• Mirror PR to Emerge-Lab/PufferDrive requested now — needs a human to verify the final
  title, body and diff first, and the body must carry the authorship disclosure from
  .github/fork/PROCESS.md → Agent authorship
• Contributable, but we hold it for now, because: both files are upstream's and the
  contradiction is upstream's, so this belongs there — but which of the two standards upstream
  wants is their call, not ours, and §5 requires explicit human approval before we open an
  upstream PR arguing for one.
• Never upstream — fork-only chore(fork): change, Gate 3 exempt

Risk / notes

The obvious bigger fix was attempted and rejected. Rather than keeping two copies in sync, the
better change is to make CLAUDE.md a one-line @AGENTS.md pointer. That is structurally blocked
today, and it is worth recording why so nobody re-derives it:

1. Deleting CLAUDE.md's body makes the trailing context of the deletion hunk the
   <!-- fork:begin --> line. That line does not exist upstream, so the commit cannot
   cherry-pick onto pure upstream/3.0 — Gate 3 fails on a conflict, not on a policy check.
2. The fork block's own text ("The section above governs PRs sent to…") stops making sense once
   the section above it is gone, and a feature commit may not edit that block.

A clean path exists but costs two coupled changes and weakens a guard: first a chore(fork) commit
dropping CLAUDE.md from FORK_BLOCK_FILES and removing its fork block from the base commit, then
the pointer commit, which would then cherry-pick cleanly. Judged not worth it — the saving is
roughly 800 tokens per Copilot CLI session, and Claude Code expands @AGENTS.md at session start
anyway, so there is no context saving on that side at all. Left for a human to decide.

Until then, the standing risk is simply that the two files drift again. This PR resolves the one
place they had already drifted.

[jdsika]

Gate 1 note — the two red checks are not this PR's.

Unit Tests and Notebook Execution fail here on test_drive_mean_action_is_exact_in_physical_units with ImportError: fused_slot_encoder=true requires triton. That is a repository-wide defect inherited from upstream (fused_slot_encoder: true in the shipped config, upstream PR Emerge-Lab#601) and it is red on every open PR, including ones that touch only documentation.

It is fixed by #13, which is now 12/12 green. Once #13 is stacked and this branch is rebased, Gate 1 can be satisfied here.