docs: clarify Octopool routing and freshness

AGENTS.MD

@@ -75,8 +75,8 @@
 - Explicit land of own draft PR: ignore draft; mark ready if needed; continue.
 - `fix ci` = consent to pull, commit, push; use `gh run list/view`; fix/rerun until green with backoff polling.
 - GitHub quota: bare `gh` only (Octopool cache). Watch commands (`gh run watch`, `gh pr checks --watch`) shim-native since octopool 0.4.7; still poll one exact id, not loops.
-- gh reads: ALWAYS `--json <fields>`. Human-format `gh pr view/list/checks`, `run list`, bare `gh api graphql` delegate silently to real gh (GraphQL+core on personal token). Machine shapes ride the shared cache.
-- `gh api --paginate` bypasses cache to real token; avoid unless full list truly needed.
+- gh reads: request narrow `--json <fields>` for machine output. `--json` alone does not guarantee relay use: unsupported field bundles (such as PR `mergeStateStatus` or issue `comments`) use native gh for the whole export. Supported human output and exact recognized GraphQL projections can also relay; let the installed Octopool own routing.
+- Supported `gh api --paginate`/`--slurp` and `--hostname github.com` reads can relay. `--include` selects native caller credentials, not just fresher cache data. Use `OCTOPOOL_FRESH=1` or `Cache-Control: max-age=0` for relay freshness; preserve required decision fields and verify CI by exact run/head, not the newest broad-list row.
 - CI logs: fetch once per failed run; reuse printed output. One `gh search`/`list --json` over per-item view loops; narrow fields, exact refs.
 - `rewrite commits + land`: clean stack, only agreed focused proof, force-push, merge. No PR-body proof polish or CI babysit unless asked.
 - Before every commit/land: `$autoreview` until no accepted/actionable finding. Always prefer Codex for autoreview, independent of environment.

CHANGELOG.md

@@ -6,6 +6,8 @@ summary: Timeline of guardrail helper changes mirrored from Sweetistics and rela
 
 ## Unreleased
 
+- Correct Octopool calling guidance for native JSON bundles, pagination, caller-owned headers, exact-run CI verification, and sandbox coverage.
+
 - Guard Xcode installs with bounded Git/Python smoke checks and selected-bundle rollback; require a Git host preflight before Codex workers and document the stable-Xcode workaround.
 
 - Fixed false missing-asset errors when verifying macOS releases with long asset lists.

skills/github-cache-hygiene/SKILL.md

@@ -28,16 +28,31 @@ gh search issues "<terms>" -R owner/repo --state open --json number,title,state,
 gh search prs "<terms>" -R owner/repo --state open --json number,title,state,url,updatedAt,isDraft,author
 gh issue list -R owner/repo --state open --author user --assignee user --label bug --json number,title,url
 gh pr list -R owner/repo --state open --author user --label dependencies --json number,title,url
-gh issue view 123 -R owner/repo --json number,title,state,body,comments,labels,url
+gh issue view 123 -R owner/repo --json number,title,state,body,labels,url
 gh pr view 123 -R owner/repo --json number,title,state,url,headRefName,headRefOid
 gh pr checks 123 -R owner/repo --json name,state,bucket,link
 gh run list -R owner/repo --branch branch-name --json databaseId,workflowName,status,conclusion,url
 gh pr diff 123 -R owner/repo --patch
 ```
 
-Use exact refs and narrow fields. Avoid broad loops like one `gh issue view` per result when a single `gh search` or `gh issue list --json ...` can answer the first-pass question.
+Use exact refs and narrow fields. `--json` selects output, not a reader identity.
+In Octopool 0.7.1, PR `mergeStateStatus` and issue `comments` select native gh
+for the entire field bundle. PR comment/review/commit exports also retain native
+handling. Request those fields when needed, but omit them from descriptive reads
+that do not consume them. Never remove merge/review gates merely to raise cache
+reuse, or split one decision into separately timed reads without preserving its
+consistency contract.
 
-For CI, avoid tight `gh run list` / `gh run view` polling loops. After a push or workflow dispatch, identify one exact run, then poll that run at 30s, 60s, then 120s intervals. Fetch logs once, only after failure or explicit request. Reuse prior output instead of re-reading completed runs.
+Supported human output and recognized landing GraphQL projections can also relay.
+Supported `gh api --paginate`/`--slurp` and `--hostname github.com` reads need not
+bypass Octopool. Use the installed version's CLI contract and observed routing;
+an absolute `gh` path alone does not establish that it is the native binary.
+
+Avoid broad loops like one `gh issue view` per result when a single `gh search` or `gh issue list --json ...` can answer the first-pass question.
+
+For CI, avoid tight `gh run list` / `gh run view` polling loops. After a push or workflow dispatch, identify one exact run, then use an exact-run watcher or poll that run at 30s, 60s, then 120s intervals.
+Check the expected head SHA and run attempt. A broad or filtered list can lag even
+on a fresh upstream acquisition; its newest row is not final CI evidence. Fetch logs once, only after failure or explicit request. Reuse prior output instead of re-reading completed runs.
 
 ## Freshness
 
@@ -61,7 +76,17 @@ This refresh spends GitHub API calls and updates Gitcrawl's archive, not Octopoo
 
 `gitcrawl gh` is retired and exits `2` with a migration note. Replace those recipes with archive reads followed by bare `gh`; the note is not an authentication failure. Do not run `octopool login`, change tokens/auth/PATH/config, or bypass the existing shim to repair a retired command.
 
-After a write, do one targeted readback, not a broad rescan.
+After a write, do one targeted fresh readback, not a broad rescan.
+Use `OCTOPOOL_FRESH=1` or an explicit `Cache-Control: max-age=0` for relay reads.
+Supported PR decision fields such as `state`, `headRefOid` and `statusCheckRollup`
+automatically revalidate. Descriptive fields such as `title` can reuse cache.
+
+`gh api --include` uses native gh and caller credentials. It changes identity,
+quota and potentially visibility; it is not a freshness switch or a guaranteed
+stale-list workaround. Keep caller-owned permission and merge decisions on their
+required identity path. A fresh relay MISS with an old list does not by itself
+prove expired cache reuse, and a HIT after revalidation does not prove zero
+upstream requests.
 
 ## Octopool
 
@@ -74,9 +99,24 @@ octopool stats --since 1h
 octopool stats --since 24h --json
 ```
 
-Check the saved-vs-backend totals, eligible hit rate, top route kinds, fallbacks, and client attribution. A missing client or unexpected server means that machine is outside the shared fleet cache.
-
-Use `OCTOPOOL_NO_FALLBACK=1` only for a bounded read probe that must prove relay coverage. Do not set it globally; mutations and unsupported reads still need real `gh`.
+Prioritize cached eligible responses divided by eligible requests. Retain the UTC
+window, numerator, denominator, misses, bypasses and coalesced requests. Compare
+route/client mix, explicit freshness and latency before attributing a change.
+These are response-reuse metrics, not GitHub quota savings. Pool totals cover all
+callers, while client tables cover the authenticated caller. Native GraphQL and
+direct clients are outside relay metrics; absence from a bounded sample is not
+proof of a broken installation.
+
+Check the actual execution context. A host shim can work while a container uses
+a separate native read-only wrapper. Preserve that wrapper's allowlist and
+credential boundary; never mount host mutation credentials to gain cache coverage.
+
+Use `OCTOPOOL_NO_FALLBACK=1` only for a bounded, known-supported relay read.
+It blocks a relay-to-native handoff, but deliberately unsupported commands can
+still delegate directly. Success alone is therefore not universal relay proof.
+Pair it with a known supported command and observed route/cache evidence. A
+separate native wrapper may ignore this variable entirely. Do not set it globally;
+mutations and unsupported reads still need real `gh`.
 
 For relay-only proof: