Lane contract and AGENTS.md steps 2-4 for cloud lanes (cloud migration item 5)

[thejackshelton]

Cloud migration plan item 5 (docs/goals/milestone-2-proof/notes/cloud-migration.md). Docs only. Every quality rule is kept; only how each rule is met changes for a cloud lane (Ubuntu x86_64, fresh clone, 30-minute command limit, no macOS, Chrome, Swift or Kotlin). The local-Mac path stays documented as an alternative.

What changed

lane-contract.md

• New "GitHub commands (REST)" section: exact gh api forms for creating a PR, head sha and conflict state, the files a PR changes, open PRs, PR comments, review comments, replying to a review comment, adding and removing labels, and a commit's checks. Lanes use these until the PM confirms GraphQL passes the proxy.
• Regen: only on CI and only through the regen label, with no local fallback in the cloud; how to find the run over REST (pull_request runs on the branch, skipped ones dropped).
• Targeted tests: node scripts/test-shards.ts group-files decides; platform-free files run locally, Chrome and native files through pnpm ci:test-files ... --once. New Never rule: no claim that a Chrome or native file passed unless ci:test-files reported it. The cross-cutting registry tests (Chrome group) go in the ci:test-files run. Macos-only floor and pin writes use --floor-write.
• Heavy commands: never run regen, full test, captures, wpt:run or tw:sweep in a cloud session (replaces the heavy-lease rule; the lease stays for the Mac).
• Waiting: end the turn while CI runs and resume from GitHub state; single polls (--once, pr:review without --wait), optionally repeated in a foreground loop under 25 minutes. No watchers, job.sh, leases or .done files.
• Push work in progress early. The local-prep exception for a queued parent now pushes the prep branch (no PR, no regen).
• Stop rule 5: under 5 GB free on the session disk (df -h .) replaces the macOS /System/Volumes/Data 40 GB check (the cloud disk is 30 GB in total, so the old rule would always fire).
• Review loop: what to do while pr:review still uses GraphQL (plan item 2): answer findings over REST, check CI over REST, report that pr:review could not run; never claim clean without its exit 0.
• Landing: the precomputed Claude review the driver needs is provided by the PM (plan item 8 moves it to a PR comment); lanes don't write it.
• Specs move from /tmp/specs to docs/goals/milestone-2-proof/notes/-spec.md on a pushed spec/<task> branch, which the PM commits as a board update.
• Resuming a killed lane reads GitHub state (branch, PR, checks, regen and test-files runs) instead of /tmp transcripts and worktrees.
• Receipt: a waiting on line with run ids replaces job ids; the READY line from the lane header is now in the contract.
• The header's reference to notes/PM-2026-10-03.md for "Defaults D1–D13": that note has the owner's approval but its D1–D13 table was never filled in. The header now cites the approval section and says the defaults are this file's Work and Scope sections.
• New "Local Mac" section keeps the Mac path: worktrees, job.sh, heavy lease, local Chrome and native tests, the 15-minute local regen fallback, watchers, gh pr create, pr:review --wait, the 40 GB disk rule, transcript-tail resume.

AGENTS.md

• "Before reporting done": pnpm typecheck plus the tests for what you changed, saying exactly what passed. The full pnpm test runs once per landing in the driver. In the cloud, platform-free files run locally and Chrome and native files through ci:test-files.
• Step 2: push work in progress early; regen on CI only in the cloud, through the regen label (pnpm regen still allowed on the Mac); targeted tests, with the full test left to the driver.
• Direct pushes to master: owner-requested changes need the full test of the exact commit first (pnpm test on the Mac; in the cloud, full-test.yml dispatched on a scratch branch's commit, then the push and the scratch branch's deletion). Board-only docs/goals/** pushes need only typecheck.
• Step 3: REST form of PR creation (gh pr create still fine on the Mac).
• Step 4: in the cloud, pr:review without --wait as a single poll, ending the turn while CI runs.

Review fixes (42a11b6, from the Claude review of e3b21ae)

• Direct pushes kept their full test. Owner-requested pushes to master never reach the driver, so AGENTS.md now requires the full test of the exact commit before them (Mac pnpm test; cloud: full-test.yml with sha, run looked up by its full test of <sha> title). Board-only pushes stay exempt.
• Regen run tracking. A gh workflow run regen-on-ci.yml -f branch= run is filed under master with no branch in its title, and other labels' events add skipped runs on the branch. Lanes now use only the regen label, and the status command filters branch=<b>&event=pull_request and drops skipped runs. The resume procedure uses it. Tested on real runs: pnt1-opacity-z lists its failure and success runs; ios-sim-fullscreen's lone skipped run is dropped.
• No rebase of a pushed prep branch. The parent's new head is merged in instead.
• Lows: the Never rule on Chrome and native claims is cloud-only; the registry-tests routing is corrected (dragon's registry-claims is platform-free); "Never wait on anything outside your lane" restored; mergeable_state unknown means poll again; the cloud path applies once Cloud session bootstrap and DRAGON_REQUIRE_NATIVE (cloud migration items 1 and 4) #219, test-files.yml: run chosen test files on their full-test runners, dispatched and read over REST by pnpm ci:test-files #221 and Land: ci-only mode (LAND_CI=only), queued CI runs waited for, CI Android ABI rebaseline #222 are on master; the PR body PATCH command is added.

Review fixes (second round, from the Claude review of 42a11b6)

• READY gate. pr:review can't see ci:test-files runs (their checks are filed under master), so Landing step 4 and the READY line now require, on the PR's current head sha: pr:review exit 0, the regen run finished for that sha (or none was needed), typecheck passed, and every targeted test passed (platform-free locally, the rest through ci:test-files runs whose tested <ref> at <sha> line names that sha). The READY report lists the sha and every run URL. Lanes now pass the full head sha, not the branch, to ci:test-files.
• AGENTS.md step 3: audit before opening the PR, not before the first push.
• Direct-push full test: rebase onto origin/master first; if master moves before the push, rebase and test again.
• The ci:test-files resume command filters by the head sha in the run title. I tested the filter mechanics on real runs by title prefix (test files of ci-test-files lists exactly that ref's two runs, not ci-test-files-mismatch or -plant). No run with a sha ref exists yet, so the sha form itself hasn't run; test-files.yml documents ref as "Full commit sha or branch".

What passed

• pnpm vitest run packages/parity/test/regen.test.ts -t "catch-up procedure" (it reads AGENTS.md steps 1 and 2): 1 passed.
• pnpm typecheck: pass.
• The REST commands in the contract were run against this repo (head sha, files, comments, review comments, regen-on-ci, test-files and full-test run lookups); this PR was created with the contract's REST create command, and its label add and remove commands were run on this PR.

No tolerance, check, test or fixture changed.

🤖 Generated with Claude Code