diff --git a/AGENTS.md b/AGENTS.md index e955f8b36a..1a6a6e8adc 100644 --- a/AGENTS.md +++ b/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 ""` (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 diff --git a/CHANGELOG.md b/CHANGELOG.md index 46d599a320..fe02457e6b 100644 --- a/CHANGELOG.md +++ b/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 + ""`, 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 diff --git a/CLAUDE.md b/CLAUDE.md index 30db1fc23b..91ce00d877 100644 --- a/CLAUDE.md +++ b/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