docs: record cross-session agent coordination know-how

AGENTS.md

@@ -66,6 +66,123 @@ The materialization contract is also covered by [`docs/doctoring/exact-artifact-
   force-push, disable a security gate, or use admin bypass for product or
   security changes.
 
+## Cross-session agent coordination and accumulated know-how
+
+This organization runs a fleet of independently-scheduled agent sessions sharing one
+GitHub account. Sessions do not share memory, and there is no live messaging channel
+between them — a `ListAgents`-style lookup from inside one such session finds no other
+reachable session. The repo itself (its PRs, issues, and comment history) is the only
+coordination layer that persists across sessions.
+
+- **Check for an existing claim before starting non-trivial new work.** Before opening a
+  new fix PR or resuming a stalled Gap item, look for an open PR/issue already addressing
+  it, a Draft PR carrying explicit "keep Draft until ..." governance language, or an
+  active comment thread, and do not duplicate it. When resuming work on a PR after a gap,
+  say so once in a PR comment so the next session or the human owner sees who currently
+  owns it. When you learn something reusable, add it here (or to the relevant repo's
+  `AGENTS.md`/`CLAUDE.md`), not only to a PR comment or a gap-baseline doc entry — those
+  are per-incident, and this file is what every future session reads first, per its own
+  opening instruction to read it before any work.
+- **PR-driving postures.** A PR you opened or were asked to drive is yours to keep green:
+  on every CI-red event, either push a fix or post exactly one comment naming the failing
+  check and why it is not yours to fix — never leave a PR you are driving both red and
+  untouched. A PR you are only watching (someone else, human or agent, is actively driving
+  it) gets diagnosis and a proposal, never an uninvited push.
+- **Prove base-branch debt before citing it.** Before claiming a CI-red failure on your
+  own PR "isn't caused by your diff," reproduce the exact failing CI command in a
+  throwaway git worktree checked out at the unmodified base branch; only a failure that
+  reproduces identically there is legitimate base-branch debt to cite in a standing-down
+  comment. Done for real on `contextual-orchestrator#1070`: a `coverage report
+  --fail-under=100` failure on `nim_benchmark.py` (missing statement/branch coverage at
+  `434, 645, 671->682`) reproduced identically in a throwaway worktree on unmodified
+  `origin/main`, so it was cited as pre-existing debt and tracked separately as
+  `contextual-orchestrator#1075` instead of being folded into that PR's scope.
+- **Org-wide GitHub Actions capacity exhaustion is a real, independently observed,
+  non-code-fixable condition** — hundreds of runs queued for hours across repositories,
+  jobs materializing with no runner assigned and zero steps, reproducing even on pinned
+  `ubuntu-24.04` runners — already tracked in `docs/product-technical-gap-baseline.md`. A
+  queued or pending required check is not a blocker to route around by re-running,
+  retargeting runner images, or shortening timeouts; those address different failure
+  classes. Runner-image pinning off floating `ubuntu-latest` onto explicit `ubuntu-24.04`
+  (precedent: this repo's `#1870`, and `contextual-orchestrator#1072`) is a narrow,
+  legitimate fix for a specific, different, independently-confirmed pattern — floating-image
+  starvation with a sampled window of zero clean successes — and must not be applied as a
+  generic response to ordinary queue depth.
+- **Re-verify an "already implemented, no code change needed"-style claim yourself,
+  against exact `file:line` evidence, before repeating it — including a human reviewer's
+  own claims.** A claim can cite individually true facts and still be scoped too broadly.
+  This repo's `#1884` originally claimed Noema/OpenCode/Strix review was "already fully
+  routed through contextual-orchestrator's `orchestrator/free`, no code change needed."
+  Independently re-checked in this checkout: the model-selection/logical-routing layer
+  (`opencode.jsonc`'s `enabled_providers`/`model`/`small_model`, and
+  `opencode-review-dispatch.yml`'s `OPENCODE_MODEL_CANDIDATES`) is in fact pinned to
+  `contextual-orchestrator/orchestrator/free` with no NIM-branch candidate — that part of
+  the claim held up. But it was bundled with the actual runtime sidecar/egress layer,
+  `scripts/ci/contextual_orchestrator_review_sidecar.sh`, which — independently re-verified
+  in this checkout — still requires and injects at least one of five raw provider secrets
+  (`BYTEZ_API_KEY`, `NVIDIA_NIM_API_KEY`, `NVIDIA_NIM_API_KEY_SUB`, `OPENROUTER_API_KEY`,
+  `OPENAI_API_KEY`), `git clone`s and installs `contextual-orchestrator` fresh on the
+  calling runner on every invocation, and runs model discovery in-process there — not yet
+  the immutable, secrets-free gateway artifact the org wants. That gap is tracked by this
+  repo's `#1759` and `contextual-orchestrator#1041` comment `5550412102`. `#1884`'s own
+  claim was corrected in place, in the same PR, once this was raised and independently
+  re-verified point-by-point against exact `file:line` evidence — do not repeat the
+  original, too-broad "already implemented" framing for this sidecar.
+- **Codex is a real, currently active fleet-mate, not a hypothetical.** An OpenAI Codex
+  agent session opens its own PRs under this same shared GitHub account, using
+  `codex/`-prefixed branch names (e.g. `codex/repair-codeql-startup-materialization`,
+  `codex/goal13-opencode-noema-concurrency`) — confirmed via `git log --all --grep=codex`
+  history and a live open-PR search (`is:open head:codex/`) turning up 20+ concurrently
+  open PRs in this repo alone at any given time. Before starting non-trivial new work,
+  search `is:open head:codex/` (and any other agent-branch prefix in observed use, e.g.
+  `claude/`) in the target repository in addition to the checks above — it is a cheap,
+  concrete way to see exactly what another kind of agent is already doing, catching claims
+  in a PR/issue thread might miss.
+- **`docs/agent-github-project-protocol.md`'s GitHub Project #1 Status field is the org's
+  actual designed collision-avoidance mechanism** (`Todo`/`In Progress`/`Done`, with an
+  explicit "set `In Progress` before starting, pick a different item if already claimed"
+  convention), operable by any agent with `gh`/GraphQL access. Verified independently: a
+  Claude Code session using the GitHub MCP server integration (rather than a `gh` CLI with
+  the `project` OAuth scope) cannot operate it — there is no Projects-v2 item-list/item-edit
+  tool exposed, and the adjacent-sounding `list_issue_fields`/`issue_write` `issue_fields`
+  mechanism targets a completely different, unrelated GitHub feature (org-level issue
+  custom fields: Priority/Start date/Target date/Effort), returning "Resource not
+  accessible by integration" when tried against the Projects-v2 surface. Until that MCP
+  server exposes a Projects-v2 tool (or a session's token gets the `project` scope), fall
+  back to the PR/issue/comment-based signals above rather than assuming Project-board state
+  is visible to you.
+- **The `codex` CLI is directly invokable from a shell as a second, differently-trained
+  reviewer for adversarial verification of your own conclusions** —
+  `npx --yes @openai/codex@latest exec -s read-only -C <dir> "<prompt>"` (this repo's own
+  `#1907` used exactly this and it caught a factual error same-family review had missed).
+  Verified the mechanism itself works in this environment: the package resolves and the
+  binary runs (note the *unscoped* `codex` npm package is an unrelated, unmaintained
+  decade-old tool — always install `@openai/codex`, never bare `codex`). Whether it
+  actually returns a review depends on that specific session's container already having
+  working OpenAI credentials (`~/.codex/auth.json` or equivalent) provisioned — this
+  session's did not (`401 Unauthorized` on every attempt, no `OPENAI_API_KEY` in its
+  environment), so no Codex-reviewed pass could be attached to this change. Check with a
+  trivial `exec` call first, and never claim a Codex-adversarial pass happened if
+  authentication actually failed.
+- **A draft PR being unreviewable is real (four gates skip drafts: the OpenCode receipt
+  gate, `noema_review_gate.py`, `pr_auto_rebase.py`, and CodeRabbit's
+  `auto_review.drafts=false`), but flipping every open draft to ready-for-review is not a
+  safe blanket response — check for an explicit owner hold first, even on a PR you opened
+  yourself.** Found this the hard way: flipped this repo's own docs PR to ready, and
+  separately flipped `noema#552` (a sibling docs PR in this same cross-session-knowhow
+  effort) to ready — `noema#552` was converted back to draft by the repository owner
+  27 minutes later, no comment, on an otherwise-idle PR with clean checks. Two other open
+  PRs carry the same instruction explicitly in writing: `contextual-orchestrator#1070`
+  has an owner comment reading verbatim "Left as Draft per your instructions — no
+  self-approval, no ready-for-review flip. Over to you for the full-gate re-run and Ready
+  decision," and `noema#553`'s own PR body says "Keep Draft until this unchanged exact
+  head receives current terminal CI/reviewer/Security/image and every applicable ... gate
+  ... Do not source-churn for runner allocation, transfer predecessor GREEN, self-approve,
+  force-push/destructively rebase, or weaken the publisher race controls." Before flipping
+  a draft you opened, grep its body and comment thread for "keep draft" / "ready-for-review"
+  / "self-approve" language — a standing per-PR owner hold overrides the general
+  draft-is-unreviewable finding.
+
 ## Verification discipline
 
 Many agent sessions work this organization concurrently under the same standing

CHANGELOG.md

@@ -23,6 +23,37 @@
 - Raised `hourly-review-repair.yml`'s discovery ceiling from 50 to 200 while rotating deterministic 50-PR deep-inspection windows by hourly run number. The scheduler hydrates only the selected window and stops immediately after its single dispatch, preserving access to newer PRs without quadrupling expensive review/check/comment work. See `docs/doctoring/hourly-review-repair-single-file-consolidation.md`'s 2026-09-03 follow-up.
 
 ## [Unreleased]
+- **Document cross-session agent coordination know-how in `AGENTS.md`, with a pointer
+  bullet in `CLAUDE.md` (documentation-only, no code or behavior change).** Added a new
+  top-level `AGENTS.md` section, "Cross-session agent coordination and accumulated
+  know-how," capturing lessons learned this cycle: the repo/PR/issue history is the only
+  durable coordination layer across independently-scheduled agent sessions that share no
+  live channel and no shared memory; PR-driving vs. PR-watching postures; proving
+  base-branch CI debt in a throwaway worktree before citing it (precedent:
+  `contextual-orchestrator#1070`); distinguishing non-code-fixable org-wide Actions
+  capacity exhaustion from the narrow, legitimate floating-`ubuntu-latest`-to-
+  `ubuntu-24.04` runner-image-starvation fix (precedent: `#1870`,
+  `contextual-orchestrator#1072`); and re-verifying "already implemented" claims against
+  exact `file:line` evidence before repeating them, using this repo's own `#1884` (whose
+  sidecar/egress claim was corrected in place; canonical tracking remains `#1759` and
+  `contextual-orchestrator#1041` comment `5550412102`) as the worked example. Also added,
+  after independent verification: Codex is a real, currently active fleet-mate (20+
+  concurrently open `codex/`-branch PRs found in this repo alone via `is:open head:codex/`);
+  `docs/agent-github-project-protocol.md`'s Project #1 Status field is the org's designed
+  collision-avoidance mechanism, but this session's GitHub MCP integration cannot operate
+  it (confirmed "Resource not accessible by integration"; the adjacent `list_issue_fields`
+  tool targets an unrelated org issue-field feature, not Projects-v2); and the `@openai/codex`
+  CLI is directly invokable (`npx --yes @openai/codex@latest exec -s read-only -C <dir>
+  "<prompt>"`, confirmed to run in this environment) for adversarial second-opinion review,
+  though this session's own container lacked the OpenAI credentials to actually get a
+  response from it. Also added, from a fleet-wide broadcast counter-check: a draft PR
+  being unreviewable by the four review/rebase gates is real, but flipping every open
+  draft to ready-for-review is not a safe blanket response to it -- check for an explicit
+  owner hold in the PR body or comment thread first, even on a PR you opened yourself
+  (`noema#552` was reverted from ready back to draft by the repository owner 27 minutes
+  after this session flipped it; `contextual-orchestrator#1070` and `noema#553` carry
+  explicit "keep draft"/"no self-approval" owner instructions in writing). No workflow,
+  script, or test file changed.
 - Include merge-scheduler entrypoint, core, and regression-test changes in
   the existing runtime-quality workflow's trigger and suite selector. Scheduler
   workflow edits retain queue checks and also select the full review-repair

CLAUDE.md

@@ -181,6 +181,11 @@ repeatable compile command.
   cross-repo references as `owner/repo#num` or full URLs; durable knowledge in the repo/Project, not
   private memory; one roadmap phase at a time) are defined in `docs/CWL-MASTER-CONTEXT.md` §7 and
   apply here.
+- **Cross-session agent coordination** (no live channel between independently-scheduled agent
+  sessions; claim-checking before starting work; PR-driving postures; proving base-branch debt in a
+  throwaway worktree; Actions-capacity exhaustion vs. legitimate runner-image pinning; re-verifying
+  "already implemented" claims at `file:line`) is covered in `AGENTS.md`'s "Cross-session agent
+  coordination and accumulated know-how" section — read it before resuming or claiming any PR.
 - **Agent sessions here share one GitHub identity, so they cannot approve each other's PRs.** Every
   session pushes and reviews as the same account, and GitHub refuses a review with `event=APPROVE` on
   a PR that account authored (`POST /repos/{owner}/{repo}/pulls/{n}/reviews` → 422 "Can not approve