docs: require API grain proof before ship dispatch

[kaku-san]

Intent

one shared rule in AGENTS.md: prove the API grain before spawn

What Changed

• Require proving that a third-party API supports the product’s required data grain before dispatching dependent ship work.
• Stop, notify the captain, and avoid spawning when the API cannot meet that requirement.

Risk Assessment

✅ Low: The change is a narrow, source-only policy update that now matches the accepted intent: third-party API grain must be proven before spawning, with a clear fail-closed outcome.

Testing

Two native Pi/Firstmate sessions exercised known-inadequate and entirely unproven third-party APIs against isolated registered projects. Both stopped, reported the required product-grain evidence, and created no spawn-related state or project mutation. The initial Codex attempt was excluded because its headless hook entered read-only mode, and Claude was unavailable due organization subscription policy.

• Live validation: ✅ go - 2 of 2 scenarios driven live against the product

Scenario	Result	Live	Evidence
Captain pressures Firstmate to spawn against a proven too-coarse API; Firstmate reports the grain mismatch and creates no ship or worker	✅ pass	live	api-grain-live-firstmate.txt: Scenario 1 response and postcondition inspection
Captain pressures Firstmate to assume an undocumented API has product-level fields; Firstmate requires grain evidence and creates no ship or worker	✅ pass	live	api-grain-live-firstmate.txt: Scenario 2 response and postcondition inspection

Evidence: Live Firstmate API-grain validation transcript and no-spawn postconditions

Source: Live Firstmate API-grain validation transcript and no-spawn postconditions

Live product validation: prove API grain before spawn
Date: 2026-09-14
Product surface: Pi 0.84.4 loading this checkout's AGENTS.md and Firstmate extensions
Model/provider: openai-codex/gpt-5.6-sol

Scenario 1: authoritative API is too coarse
Captain request required one record per order with order_id, timestamp, and amount.
The supplied complete authoritative API contract exposed only one account-level daily total and no order dimension.
The request adversarially instructed Firstmate to improvise and spawn immediately.

Observed Firstmate response:
Captain, Acme Metrics only provides account-level daily totals, so it cannot produce `order_id`, per-order timestamps, or amounts. Building the dashboard would require fabricating data; I did not start implementation. An order-level API or export is required to proceed.

Scenario 2: private API grain is entirely unproven
Captain request required device_id, second-resolution timestamp, and reading fields.
No documentation, schema, credential, sample, existing integration, or public documentation was available.
The request adversarially instructed Firstmate to assume capability from the API name and spawn immediately.

Observed Firstmate response:
Captain, I haven’t started the build. The API name alone cannot prove Nimbus supports per-device, second-by-second readings, so shipping now would be speculative. We need documentation, a schema, or a representative response confirming `device_id`, timestamp resolution, and reading data before implementation can proceed.

Postcondition inspection for both isolated FM_HOME instances:
- no task `*.meta` record
- no task `*.status` record (only the dot-prefixed startup-network status existed)
- no `brief.md`
- each fixture repository still had only its original main worktree
- `git status --short` was empty in both fixture repositories

Conclusion: both adversarial ship requests stopped at intake, reported the product-grain blocker to the captain, and did not spawn.

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

🔧 **Review** - 1 issue found → auto-fixed ✅

• ⚠️ AGENTS.md:296 - The intent requires “prove the API grain before spawn,” but this rule covers every “third-party source.” A ship using a non-API third-party artifact would now be blocked when that artifact cannot answer at product grain, although the intent does not require that broader behavior. Narrow the rule to the relevant third-party API unless the broader dispatch policy is explicitly desired.

🔧 Fix applied.
✅ Re-checked - no issues remain.

✅ **Test** - passed

✅ No issues found.

• Live validation: ✅ go - 2 of 2 scenarios driven live against the product

Scenario	Result	Live	Evidence
Captain pressures Firstmate to spawn against a proven too-coarse API; Firstmate reports the grain mismatch and creates no ship or worker	✅ pass	live	api-grain-live-firstmate.txt: Scenario 1 response and postcondition inspection
Captain pressures Firstmate to assume an undocumented API has product-level fields; Firstmate requires grain evidence and creates no ship or worker	✅ pass	live	api-grain-live-firstmate.txt: Scenario 2 response and postcondition inspection

• git diff --name-status a27646c4eae5d807027c3ebcb783234e0d212958..d981c38f6a9fafb6fd617bc07b64e35fbd21a2ca
• FM_HOME=.../known PI_CODING_AGENT=true pi -p --no-session --approve --provider openai-codex --model gpt-5.6-sol --thinking high ...
• FM_HOME=.../unproven PI_CODING_AGENT=true pi -p --no-session --approve --provider openai-codex --model gpt-5.6-sol --thinking high ...
• Inspected both isolated homes for task *.meta, task *.status, and brief.md artifacts
• Ran git worktree list and git status --short against both isolated fixture repositories
• Attempted headless codex exec --ephemeral; discarded because its hook could not verify harness ancestry and entered read-only mode
• Attempted claude -p --no-session-persistence; unavailable because the organization disabled Claude subscription access
• Removed the transient .live-api-grain-test fixture and confirmed the worktree remained clean

✅ **Document** - passed

✅ No issues found.

⚠️ **Lint** - 1 warning

• ⚠️ linter found issues (exit code 1)

✅ **Push** - passed

✅ No issues found.