Align read-first prose with the contract's agent_read_order

[pengfei-threemoonslab]

Why

Problem #9 from the 2026-07-01 repo review: README shipped both orderings simultaneously — "Read verifier.json first" (Verify-first quickstart, §189–195; copy-into-your-agent block, §280–285; and the "What it produces" list claimed in read order with verifier.json ahead of the handoff) vs "read agent-handoff.json.gate.merge_verdict first" (§How to read your first result). The /shipgate slash command carried the same stale sentence.

The canonical order is not ambiguous: contract --json → agent_read_order[0] is agent-handoff.json, and docs/agent-contract-current.md § Two read entry points spells out the design — handoff first for the compact continue/repair/stop step, verifier.json as the authoritative controller substrate, report.json.release_decision.decision as the gate. llms.txt, AGENTS.md, and .well-known were already aligned; README and the slash command were the stragglers.

What

• README ×3: quickstart read-order sentence, the copy-into-your-agent block, and the "What it produces" list (handoff bullet now first and marked as the first read; verifier bullet reframed from "primary PR/controller evidence artifact" to "authoritative PR/controller evidence substrate", matching the contract doc's language). No field or artifact semantics change.
• .claude/commands/shipgate.md: same alignment (this file ships in the wheel byte-identical via force-include, so no second copy to sync — covered by test_wheel_claude_command_is_byte_identical_to_repo_file).
• New guard in tests/test_public_surface_contract.py: test_read_first_instructions_match_contract_agent_read_order pins every Read `<artifact>` first instruction on README.md / AGENTS.md / llms.txt / the slash command to the runtime contract's agent_read_order[0] (via build_contract_payload(), the function behind contract --json), with a vacuity check (each surface must still contain at least one read-first instruction).

Scoping notes

• The review item also asked for "CI validation of .well-known + llms.txt against contract --json" — investigation showed this largely already exists in test_public_surface_contract.py (.well-known is validated against build_contract_payload() for agent_read_order, verifier_read_order, primary_commands, schema versions, exit codes, and MCP tools; llms.txt for version literals, triggers, and llms-full references). The genuine uncovered drift was the prose read-first instructions — that's what the new test covers. Filed no redundant checks.
• skills/agents-shipgate/SKILL.md step 3 ("parse verifier.json first, then verify-run.json") is intra-substrate ordering (verifier before verify-run), which is contract-correct — deliberately untouched to avoid the three-copy bundled-prompt sync for a non-contradiction.

Verification

• New guard passes on this tree; verified to fail when the old "Read verifier.json first" phrasing is re-injected into README.
• pytest tests/test_public_surface_contract.py tests/test_zero_install_detector.py tests/test_packaging.py tests/test_trust_root.py tests/test_agent_instructions_apply.py tests/test_action_metadata.py — all green; ruff check clean.
• shipgate check --agent claude-code --format codex-boundary-json on this diff (touches the agent_instructions trust-root surface): decision: allow, completion_allowed: true — aligning instructions with the contract, not weakening them.

🤖 Generated with Claude Code