docs: record cross-session agent coordination know-how

[seonghobae]

Summary

Documentation-only. Adds a new AGENTS.md section, "Cross-session agent coordination and accumulated know-how" (with a pointer bullet in CLAUDE.md), capturing operational lessons from this cycle so a future agent session doesn't have to re-learn them:

• No live channel exists between independently-scheduled agent sessions sharing this GitHub account — check for an existing claim (open PR/issue, Draft governance language, comment thread) before starting non-trivial new work, and record reusable know-how here rather than only in a PR comment.
• PR-driving postures: a PR you opened or were asked to drive stays yours to keep green (push a fix or post one standing-down comment on every CI-red event); a PR you're only watching gets diagnosis and a proposal, never an uninvited push.
• Prove base-branch CI debt in a throwaway git worktree against unmodified origin/main before citing it — worked example: contextual-orchestrator#1070 / contextual-orchestrator#1075.
• Org-wide GitHub Actions capacity exhaustion is real, independently observed, and non-code-fixable — distinct from the narrow, legitimate ubuntu-latest→ubuntu-24.04 runner-image-starvation fix (precedent: #1870, contextual-orchestrator#1072).
• Re-verify an "already implemented, no code change needed" claim against exact file:line evidence before repeating it, even a human reviewer's own claim — worked example: this repo's own #1884, whose sidecar/egress claim was corrected in place.
• Codex is a real, currently active fleet-mate on this shared account (20+ concurrently open codex/-branch PRs found live) — search is:open head:codex/ before starting work, not just PR/issue text.
• docs/agent-github-project-protocol.md's Project Add Palette journal for profile repo #1 Status field is the org's actual designed collision-avoidance mechanism, but a Claude Code session on the GitHub MCP integration used here cannot operate it (confirmed "Resource not accessible by integration") — falls back to PR/issue/comment signals instead.
• The @openai/codex CLI is directly shell-invokable for adversarial second-opinion review (npx --yes @openai/codex@latest exec -s read-only -C <dir> "<prompt>", confirmed to run in this environment) — but only works if that session's container has OpenAI credentials provisioned, which this one's did not.
• A draft PR being unreviewable by four review/rebase gates is real, but flipping every open draft to ready-for-review is not a safe blanket response — check for an explicit owner hold (PR body/comment thread) before flipping, even on a PR you opened.

Also merges a real, live instance of the exact gap being documented: main advanced with #1907 between this branch's creation and its own push, adding a thematically-related "Verification discipline" section at the same anchor point in both files (an independently-scheduled peer session — this repo's commit history shows it as co-authored Claude Opus 5, coordinating with "four concurrent peer sessions"). Resolved as a normal merge keeping both sections in sequence — no content lost, no rewriting of the other session's text. Also resolved a second, later merge conflict against current main in CHANGELOG.md the same way.

Verification

• python -m pytest tests/test_strix_contextual_orchestrator_contract.py tests/test_strix_required_smoke_availability.py tests/test_noema_review_gate.py tests/test_opencode_review_normalize_output.py tests/test_pr_governance_audit_contract.py -q → 235 passed, 1 subtest passed, 0 failed.
• Full suite (python -m pytest tests -q) → 2893 passed, 1 skipped, 21 subtests passed, 0 failed, post-merge.
• git diff against pre-merge main is strictly additive to AGENTS.md/CLAUDE.md/CHANGELOG.md; no existing line touched.

Related

• Companion PRs in the same fleet-wide effort: ContextualWisdomLab/contextual-orchestrator and ContextualWisdomLab/noema (same branch name, same theme, repo-specific content).
• ContextualWisdomLab/.github#1884, ContextualWisdomLab/.github#1759, ContextualWisdomLab/contextual-orchestrator#1041, ContextualWisdomLab/contextual-orchestrator#1070, ContextualWisdomLab/contextual-orchestrator#1072, ContextualWisdomLab/contextual-orchestrator#1075.

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01KPmJErfkcHer4UVEgrQxUX

---

Generated by Claude Code

[coderabbitai]

Warning

Review limit reached

Next included review available in 47 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Team

Run ID: 52384ea7-0dd8-4f7b-a1fd-0ee921f49554

📥 Commits

Reviewing files that changed from the base of the PR and between f2f91b8 and 1ae08d5.

📒 Files selected for processing (3)

• AGENTS.md
• CHANGELOG.md
• CLAUDE.md

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[seonghobae]

Resolved the merge conflict against current main (b82f5934, merging origin/main in): both branches had appended a new ## [Unreleased] entry to CHANGELOG.md at the same anchor point — kept both entries in sequence, same pattern as this branch's earlier #1907 reconciliation. AGENTS.md/CLAUDE.md auto-merged cleanly with no manual resolution needed.

Verified on the merged head:

• Doc-contract tests (changelog, agents_md, pr_governance_audit_contract, opencode_agent_contract selectors): 60 passed.
• Full suite: 2893 passed, 1 skipped, 21 subtests passed.

Marking ready for review — docs-only, no code/workflow/test content changed beyond the two AGENTS.md/CLAUDE.md/CHANGELOG.md append points.

---

Generated by Claude Code

---

Generated by Claude Code

[seonghobae]

noema-review failed on this head (06d61f8a, job 101355124126): Noema gateway transport failed: HTTPError: HTTP Error 502: Bad Gateway; ... duration=1769.9s, served_model=deepseek-ai/deepseek-v4-flash-0731.

Not this PR's — it's the sidecar route-starvation issue another session root-caused today: scripts/ci/contextual_orchestrator_review_sidecar.sh's ORCHESTRATOR_CATALOG_ACCOUNT_CAP default (8, vs. policy default 4) lets nvidia_nim+nvidia_nim_sub fill the entire 12-route catalog limit alphabetically before openrouter is ever reached, so every review is served by exhausted NVIDIA routes. Fix is in progress (not yet merged); no fix exists in this PR's scope to port. This PR is documentation-only (AGENTS.md/CLAUDE.md/CHANGELOG.md), unrelated to the sidecar. Keeping this PR watched until the sidecar fix lands.

---

Generated by Claude Code

---

Generated by Claude Code

[seonghobae]

Sidecar route-starvation fix (#1939) merged to main (f2f91b80) at 17:25Z. Per the recovery guidance (re-running the failed job would replay the pre-fix sidecar since workflow_sha is bound at run creation), merged current main into this head instead: 06d61f8a → 1ae08d52, clean merge, full suite green (2896 passed, 1 skipped, 21 subtests). This fires a fresh noema-review event against the fixed sidecar.

---

Generated by Claude Code

---

Generated by Claude Code

[seonghobae]

noema-review failed on this head (1ae08d52, job 101388341942) with a genuine (non-transient-wait-state) failure: HTTPError: HTTP Error 503: Service Unavailable; caller attempts=1, duration=1655.2s, phase=response_error, served_model=deepseek-ai/deepseek-v4-flash-0731.

Not caused by this PR's own diff (uploading sidecar stderr/preflight artifacts on review-gate failure — unrelated to gateway transport). Root cause is in contextual-orchestrator, not .github: the sidecar's own preflight found 3 "ready" routes in the orchestrator/free pool (nvidia_nim_sub_deepseek_ai_deepseek_v4_flash_0731, flagged escalated: true i.e. already flaky; nvidia_nim_deepseek_ai_deepseek_v4_pro_0813; nvidia_nim_sub_deepseek_ai_deepseek_v4_pro_0813, both cleanly ready). The actual review request then spent 27.5 minutes and failed with served_model=deepseek-ai/deepseek-v4-flash-0731 — the flaky one — with no evidence it ever tried either of the two cleanly-ready sibling routes before giving up. Noema's own caller makes exactly one request and explicitly expects the gateway to own retry/failover across the pool (caller attempts=1 (gateway owns repair/failover)), so a request that never advances past a route already flagged flaky during preflight is a gateway-side failover gap, not a .github-side one.

I've dispatched a background investigation into contextual-orchestrator's actual pool-routing/retry code to confirm this precisely and fix it if it's real (not proposing a shorter timeout — this repo's maintainer has explicitly rejected fixed model-path timeouts; the issue is which agent gets retried, not how long). Not re-running this check yet since a re-run without that fix would likely just reproduce the same gap. Keeping this PR watched.

Co-Authored-By: Claude Sonnet 5 noreply@anthropic.com
Claude-Session: https://claude.ai/code/session_01KPmJErfkcHer4UVEgrQxUX

---

Generated by Claude Code

[seonghobae]

opencode-review failure on this head (1ae08d52, job 101394224158) is the standard fail-closed wait-state, not a defect: "No APPROVED or CHANGES_REQUESTED from opencode-agent on the current head. The dispatch workflow will rerun this failed job after publishing an authenticated exact-head verdict." No action needed beyond waiting for the next dispatch cycle.

Co-Authored-By: Claude Sonnet 5 noreply@anthropic.com
Claude-Session: https://claude.ai/code/session_01KPmJErfkcHer4UVEgrQxUX

---

Generated by Claude Code