Add CLAUDE.md

[ryckakas]

Problem

There was no CLAUDE.md, AGENTS.md, CONTRIBUTING.md, or docs/ tree, and no Cursor or Copilot
rules. The conventions are real but distributed: the contracts live in class docblocks, the recipes
in README.md, the behavioural record in CHANGELOG.md, and the gates in composer.json scripts
plus four tool configs. Reconstructing that costs a full pass over the repo, and the parts that are
easiest to break are precisely the ones no single file states.

Change

One new file, CLAUDE.md. No code touched.

It deliberately does not restate the file tree, the README, or generic PHP practice. What it
does carry:

• Commands, including how to run a single test and the -- flag-forwarding convention.
• The one design decision the rest follows from — fetchPage(?string $cursor) never says what
  a cursor means, which is why src/Offset/ needed no engine change — flagged so a future change
  doesn't quietly regress it.
• The invariants that look like details and are not: pages()'s budget-before-fetch and
  yield-before-loop-detection ordering; Walk misuse raising a bare \LogicException outside
  CursorWalkException on purpose; Walk setting finished before throwing so a driver that
  swallows the exception cannot keep walking; hasNext() not meaning "the next draw will succeed";
  slice() anchoring endCursor to the last upstream page for O(1) load-more; the fetcher-unit
  rule for totalPages vs totalItems.
• Environment traps that cost real time to rediscover: php-cs-fixer's parallel runner hanging
  locally, coverage/mutation being unrunnable without a coverage driver (so CI is the only
  check), and .gitattributes eol=lf being load-bearing rather than incidental.
• Testing conventions actually in use: ZOMBIES section comments, tests/Support/ fixtures,
  failOnRisky making an assertion-free test a failure, the 100% coverage floor, and why the MSI
  floor sits at 85 rather than being chased upward.
• That docblocks are the contract, not commentary — so a behaviour change means editing one.

Verification

#	Gate	Method	Result
1	Tests	vendor/bin/phpunit	283 passed, 1136 assertions
2	Static analysis	composer stan (level max)	No errors
3	Code style	composer cs -- --sequential	0 of 37 files need fixing
4	Claim: no phpstan-phpunit	grep composer.json	Absent — so PHPUnit assertions really do not narrow types
5	Claim: no version field	grep composer.json	Absent — releases are tag-driven, as stated
6	Claim: no docs/ tree	ls -d docs	Absent
7	Claim: fixture names	ls tests/Support/	All nine named in the file exist
8	Claim: ZOMBIES sections	grep for the section comments	Present across tests/ and tests/Offset/
9	Branch protection facts	gh api .../branches/main/protection	4 contexts, strict, enforce_admins: true, 0 approvals — as documented

Every factual claim in the file was checked against the repo rather than written from memory; rows
4–9 are the ones that were not already obvious from this session's work.

Notes

• No markdown formatter is configured in the repo, so there is no prettier step to run on it.
• The commands section documents composer cs -- --sequential as the local invocation. CI runs
  plain composer cs and is unaffected — the parallel runner only hangs in some Windows sandboxes.

Risk: 🟢 low — a new documentation file; no shipped code, no config, no CI change.

🤖 Generated with Claude Code