Align read-first prose with the contract's agent_read_order

The runtime contract (contract --json → agent_read_order), llms.txt,
AGENTS.md, .well-known, and docs/agent-contract-current.md § Two read
entry points all name agent-handoff.json as the first artifact a coding
agent reads after verify — but README told agents "read verifier.json
first" in two places (the Verify-first quickstart and the copy-into-
your-agent block) while telling them "read agent-handoff.json.gate.
merge_verdict first" a few lines later, and the "What it produces" list
claimed "in read order" with verifier.json ahead of the handoff. The
/shipgate slash command carried the same stale sentence.

Fix the three README spots and the slash command to lead with
agent-handoff.json (gate.merge_verdict, then controller) and present
verifier.json as the authoritative controller substrate, matching the
contract doc's language. No field or artifact semantics change.

Guard: new test_read_first_instructions_match_contract_agent_read_order
in tests/test_public_surface_contract.py pins every "Read `<artifact>`
first" instruction on README.md, AGENTS.md, llms.txt, and
.claude/commands/shipgate.md to the runtime contract's
agent_read_order[0], so the two orderings cannot ship simultaneously
again. Verified to fail on the old verifier-first phrasing.
(.well-known's machine-readable agent_read_order and primary_commands
were already contract-validated by existing tests in this file.)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: pengfei-threemoonslab

.claude/commands/shipgate.md

@@ -70,9 +70,10 @@ permissions, policies, CI gates, or `shipgate.yaml`, run the verifier:
 agents-shipgate verify --base origin/main --head HEAD --json
 ```
 
-Read `agents-shipgate-reports/verifier.json` first and lead with `merge_verdict`
-(a deterministic projection of `release_decision.decision`, which remains the
-gate in `report.json`), then `capability_changes[]`. Do not claim completion when
+Read `agents-shipgate-reports/agent-handoff.json` first and lead with
+`gate.merge_verdict` (a deterministic projection of `release_decision.decision`,
+which remains the gate in `report.json`), then the authoritative substrate
+`agents-shipgate-reports/verifier.json` and `capability_changes[]`. Do not claim completion when
 `merge_verdict` is `blocked`, `insufficient_evidence`, or
 `human_review_required` unless the user accepted the human-review requirement, and
 never weaken `shipgate.yaml`, Shipgate CI, `AGENTS.md`, policies, baselines, or

README.md

@@ -189,10 +189,11 @@ The release gate is `agents-shipgate-reports/report.json` →
 The PR/controller surface is `agents-shipgate-reports/verifier.json` →
 `merge_verdict` (`mergeable | human_review_required | insufficient_evidence |
 blocked | unknown`), a deterministic projection of the release decision. Read
-`verifier.json` first for `merge_verdict`, `applicability`,
-`agent_controller`, `can_merge_without_human`, `first_next_action`, and
-`fix_task`. `capability_review.top_changes` is supporting/provisional reviewer
-context.
+`agent-handoff.json` first (`gate.merge_verdict`, then `controller`), then the
+authoritative controller substrate `verifier.json` for `merge_verdict`,
+`applicability`, `agent_controller`, `can_merge_without_human`,
+`first_next_action`, and `fix_task`. `capability_review.top_changes` is
+supporting/provisional reviewer context.
 
 Zero-setup demos of both verdicts are in
 [60 seconds](#60-seconds-watch-it-block-two-prs) above; `uvx` runs them with no
@@ -278,10 +279,11 @@ For local control, parse the `shipgate check` stdout JSON
 `repair`, and `policy`. For local uncommitted verify work,
 omit `--base`/`--head`. For committed PR/CI refs,
 make the base ref available first because `verify` never fetches. Read
-`agents-shipgate-reports/verifier.json` first and lead with `merge_verdict`,
-`applicability`, `agent_controller`, `can_merge_without_human`,
-`first_next_action`, and `fix_task`, then read supporting/provisional
-`capability_review.top_changes` and
+`agents-shipgate-reports/agent-handoff.json` first and lead with
+`gate.merge_verdict` and `controller`, then read the authoritative substrate
+`agents-shipgate-reports/verifier.json` (`merge_verdict`, `applicability`,
+`agent_controller`, `can_merge_without_human`, `first_next_action`,
+`fix_task`), then supporting/provisional `capability_review.top_changes` and
 `agents-shipgate-reports/report.json` for `release_decision.decision`. Do not
 claim completion when `merge_verdict` is `blocked`, `insufficient_evidence`, or
 `human_review_required` unless the user explicitly accepts human review. Do not auto-assert approval. Do not auto-assert confirmation, idempotency,
@@ -486,8 +488,8 @@ and pre-commit equivalents.
 When a PR changes what your agent can do, the verify loop writes these
 artifacts — in read order:
 
-- **`agents-shipgate-reports/verifier.json`** — the **primary PR/controller evidence artifact**. A coding agent reads `merge_verdict` (`mergeable | human_review_required | insufficient_evidence | blocked | unknown`), `can_merge_without_human`, `agent_controller`, `first_next_action`, and `fix_task` when producing reviewer evidence for an agent-capability PR. Local control comes from `shipgate check --format codex-boundary-json` and `shipgate.codex_boundary_result/v1`. See [`docs/agent-contract-current.md`](docs/agent-contract-current.md) for the field contract.
-- **`agents-shipgate-reports/agent-handoff.json`** — the compact `shipgate.agent_handoff/v1` object for coding agents. It projects `gate`, `controller`, `blocked_by[]`, `remediation_plan[]`, and verify-run reproducibility from existing artifacts; it does not introduce a second verdict.
+- **`agents-shipgate-reports/agent-handoff.json`** — the **first artifact a coding agent reads**: the compact `shipgate.agent_handoff/v1` object. Lead with `gate.merge_verdict`, then `controller`; it also projects `blocked_by[]`, `remediation_plan[]`, and verify-run reproducibility from existing artifacts, and it does not introduce a second verdict.
+- **`agents-shipgate-reports/verifier.json`** — the **authoritative PR/controller evidence substrate**. A coding agent reads `merge_verdict` (`mergeable | human_review_required | insufficient_evidence | blocked | unknown`), `can_merge_without_human`, `agent_controller`, `first_next_action`, and `fix_task` when producing reviewer evidence for an agent-capability PR. Local control comes from `shipgate check --format codex-boundary-json` and `shipgate.codex_boundary_result/v1`. See [`docs/agent-contract-current.md`](docs/agent-contract-current.md) for the field contract.
 - **`agents-shipgate-reports/verify-run.json`** — the deterministic verify-run reproducibility artifact. It records stable subject/input hashes, policy-pack hashes, outcome, artifact paths, and `run_id` without wall-clock timestamps.
 - **`agents-shipgate-reports/attestation.json`** + **`agents-shipgate-reports/org-evidence-bundle.json`** — optional organization-governance projections over the same verifier/report artifacts. They are ledger inputs for platform teams, not release gates; `report.json.release_decision.decision` remains the decision engine.
 - **`agents-shipgate-reports/host-grants.json`** + **`agents-shipgate-reports/org-status.json`** — optional fleet-governance artifacts from `audit --host --out` and `org status --json`, useful for host-grant drift, policy-pack pin state, and exception hygiene.

tests/test_public_surface_contract.py

@@ -2348,3 +2348,51 @@ def test_no_singular_underscore_module_name(relpath):
             f"{relpath}:{line} uses singular `agent_shipgate`; the "
             f"correct Python module is `agents_shipgate` (plural)."
         )
+
+
+# ---------------------------------------------------------------------------
+# Read-first artifact vs the runtime contract's agent_read_order
+# ---------------------------------------------------------------------------
+
+READ_FIRST_PATTERN = re.compile(r"[Rr]ead\s+`([^`]+)`\s+first")
+# Prose surfaces that tell a coding agent which verify artifact to read
+# first. .well-known/agents-shipgate.json carries the machine-readable
+# agent_read_order (validated against the contract elsewhere in this
+# file); these are the human/agent prose mirrors of that order.
+READ_FIRST_SURFACES = (
+    "README.md",
+    "AGENTS.md",
+    "llms.txt",
+    ".claude/commands/shipgate.md",
+)
+
+
+@pytest.mark.parametrize("relpath", READ_FIRST_SURFACES)
+def test_read_first_instructions_match_contract_agent_read_order(relpath):
+    """Every 'Read `<artifact>` first' instruction must name the first
+    artifact in the runtime contract's agent_read_order (agent-handoff.json
+    since contract v7), optionally with a reports-dir prefix or a field
+    path suffix. README shipped both 'read verifier.json first' and
+    'read agent-handoff.json first' simultaneously until v0.14.x; this
+    pins the prose surfaces to the contract so the contradiction cannot
+    return. verifier.json stays the authoritative controller substrate —
+    mentioning it is fine, telling an agent to read it *first* is not."""
+    contract = build_contract_payload().model_dump(mode="json")
+    first_artifact = contract["agent_read_order"][0]
+    assert first_artifact == "agent-handoff.json", (
+        "contract agent_read_order[0] changed; sweep the read-first "
+        "prose on READ_FIRST_SURFACES, then update this pin."
+    )
+    text = _read(relpath)
+    matches = READ_FIRST_PATTERN.findall(text)
+    assert matches, (
+        f"{relpath} no longer contains a 'Read `<artifact>` first' "
+        "instruction. Either restore one naming "
+        f"{first_artifact} or drop the surface from READ_FIRST_SURFACES."
+    )
+    for artifact in matches:
+        assert first_artifact in artifact, (
+            f"{relpath} tells an agent to read {artifact!r} first; the "
+            f"contract's agent_read_order starts with {first_artifact!r} "
+            "(see docs/agent-contract-current.md § Two read entry points)."
+        )