Skip to content
This repository was archived by the owner on Nov 13, 2026. It is now read-only.
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
126 changes: 89 additions & 37 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,14 +28,30 @@ a book: `site-private/AGENTS.md` ("Book knowledge base").

## Standing rule: most important work — be pedantic, pay for the best models (2026-10-31)

Native routing update: 2026-11-10 (Wave 6 A3/A4; admission limits preserved).

**Environment availability exception (operator, 2026-11-10):** requirements
below that name an agent or model unavailable in the current environment may
be overridden with an available, appropriately capable agent. This includes
the lead-model rule and the named frontier/cross-family reviewer requirement.
Use a separate reviewer with fresh context, disclose its actual model and
effort and the unavailable preferred route in the PR, and resolve findings
before merge. Do not describe a same-family review as cross-family review.
This exception does not waive review, CI, quota/headroom/reservation checks,
untrusted-input boundaries, or explicit operator approval for other actions.

djbclark, 2026-10-31: tendcf and nix2cf are the most important work he is
doing, and getting it right outranks cost. This lifts `model-routing` item 1b's
*reason* test for these two repos only: here a frontier review needs no "really
needs a frontier model" case, and a second opinion is reason enough. Every
other repo keeps the default. The mechanics stay (item 4). As of 2026-11-06 (slim-down) `acp-dispatch` is a shim over `paseo run` and will be replaced by `paseo run` lines in a follow-up; `acp-dispatch`'s
estimate floors, per-wave caps, in-flight reservation and exit 5 are not
overridden. Never use `route-override`, `--est-pct`, `--min-headroom 0` or
`--no-preflight` to get around them.
other repo keeps the default. The mechanics stay: frontier allowance,
fresh quota readings, estimate floors and caps, headroom, per-wave limits
and in-flight reservations are not overridden. Native routing is described
in djbclark-ade's `skills/model-routing/SKILL.md`, sections D–E. Never
override a route, lower headroom, change the estimate or omit admission
checks to force a review. A printed native launch command or an
`ade.kind=frontier` label is not proof of admission. If the current native
path cannot preserve these checks, hold the review and report the missing check.

1. **Be pedantic.** Re-read what you changed. Verify every claim by running it,
never by recall. Read the plan or spec section before changing what it
Expand All @@ -59,22 +75,46 @@ overridden. Never use `route-override`, `--est-pct`, `--min-headroom 0` or
gets one frontier review before merge. `docs/handoffs/` commits are not
PRs and keep the push-in-place exception above. Try the reviewers in this
order:
1. astra: `acp-dispatch codex --model gpt-6-astra --kind frontier --effort high --perm read-only --frontier-reason "<repo> standing rule: cross-model review" --name NAME -f BRIEF -C WORKTREE`
2. Fable: `acp-dispatch claude --model fable --kind frontier --effort high --perm read-only --frontier-reason "..." --name NAME -f BRIEF -C WORKTREE`
3. Gemini 4 Argon: `acp-dispatch agy --model gemini-4-argon --kind frontier --effort high --perm all --frontier-reason "<repo> standing rule: cross-model review" --name NAME -f BRIEF -C WORKTREE` today; when the djbclark-ade slim-down lands (its E9 retires the agy TUI and the Google AI plan is reached through Paseo's antigravity provider; its E6 shim maps the agent name to the Paseo provider) the same line reads `acp-dispatch antigravity --model gemini-4-argon …`. Argon stays behind `acp-dispatch --kind frontier` (estimate floor, in-flight reservation, per-wave frontier cap, exit 5), never a bare `paseo run`. There is no verified read-only mode for the Google provider, so put read-only instructions in BRIEF and check the worktree diff before and after the review. That restricts Argon by instruction only, not by a read-only sandbox. Argon is fallback-only: it stands in when astra or Fable is short. Its frontier wiring landed in djbclark-ade PR 224 (merged 2026-11-02).
- A pool is **short** when `acp-dispatch` answers exit 5 (`unavailable`:
wont-fit, inflight, headroom or preflight), or when `aiuse --available --json`
lists it `usable_now: false`. Argon with no fresh `aiuse` reading counts
as short too: acp-dispatch refuses it as headroom ("no fresh reading").
Short means move to the next model in the order, never force it.
Say in the PR body which model was short and why. **Check the actual
dispatch, never infer availability from the config alone.** Run the
intended command with `--dry-run`, preserving its model, kind, effort,
brief, `-C` and output/task directory. Inspect `would refuse: class=...`
(or `would_refuse_class` with `--json`), not just the exit status:
dry-run returns 0 for predicted headroom, fit and concurrency refusals.
It skips preflight, so no predicted refusal is not proof of availability;
the real dispatch must still pass its checks. **Astra's fallback estimate
1. Astra: Codex provider, `gpt-6-astra`, `high`.
2. Fable: Claude provider, its current Fable frontier model, `high`.
3. Gemini 4 Argon: Antigravity provider, `gemini-4-argon`, `high`.
Argon is fallback-only when Astra or Fable is short. Require a fresh
reading for its Google AI Pro subscription pool; an API entitlement is
not a substitute.

Plan each review with
`~/src/djbclark-ade/bin/route_agent.py plan --kinds frontier --repo nix2cf --json`.
Keep the reviewer order and model-family independence above; a non-frontier model
cannot satisfy this rule. Re-plan immediately before admission and launch.
Record the reason `nix2cf standing rule: cross-model review` in the brief
and admission evidence.

Use the current ADE review launch path after admission. Preserve the
enforced `bin/review-launch` boundary when reviewing untrusted external
input; do not replace it with an unrestricted invocation. Trusted own-agent
work follows ADE's ordinary permission policy. For reviews relying on
instructions rather than tool restrictions, direct the reviewer to change
nothing and compare worktree status and diff before and after; do not claim
that this is an enforced read-only sandbox.

Native Paseo launches use the admitted provider/model and `--thinking high`,
carry `ade.kind=frontier`, `ade.name`, `ade.lead` and `ade.task` labels,
and use the explicit workspace and cwd verified under ADE's orchestration
practices. Include the delivery footer in the positional brief. Do not
translate retired launcher flags into unsupported native flags.
- A pool is short when a fresh quota reading marks it unusable, the intended
reviewer does not fit every relevant window with the required headroom,
or admission refuses it for concurrency, reservation or preflight reasons.
Missing or stale readings do not establish availability. Move to the next
eligible reviewer and report the reason; never force admission.

Read `aiuse --available --json` first, `paseo usage ls --json` second, and
inspect the fresh planner's structured result. A Paseo report whose status
is not `available` is unknown. Planner output is not proof that a subsequent
launch passed admission; native commands do not inherit the old dispatcher's
exit-code or dry-run contract. Preserve admission and actual launch results.

**Astra's fallback estimate
floor and estimate cap in these two repos are 20 percentage points**
(djbclark, 2026-11-01). The `codex:frontier` estimate uses comparable
measured history. The configured fallback floor applies separately when
Expand All @@ -86,13 +126,13 @@ overridden. Never use `route-override`, `--est-pct`, `--min-headroom 0` or
This is not a permanent minimum of 20% quota remaining; headroom, fit,
in-flight reservation and the other dispatch checks still apply.
The override is configured in djbclark-ade's `config/routing.toml` at
`[dispatch.repo_overrides.<repo>.estimate_floor]`, selected by the
repository name from `-C`'s `origin` remote. Every other repository keeps
`[dispatch.repo_overrides.<repo>.estimate_floor]`, selected explicitly with
`plan --repo nix2cf`. Every other repository keeps
the configured 60-point `codex:frontier` fallback floor, which sufficient
comparable history can replace. On 2026-10-31 a lead treated the 60% fallback as a
permanent minimum and declared astra short at 45% remaining. That
comparison alone did not establish that astra was short. Only the dry-run
and the dispatch decide.
comparison alone did not establish that astra was short. Only fresh quota, fit and admission
evidence establish availability.
- Design rulings (a `schema_version` bump, the privilege or enforcement
scope on a host, a deploy plan, the unit-writer or consent-diff design)
get two independent frontier reviews, astra and Fable. Argon stands in
Expand All @@ -102,18 +142,30 @@ overridden. Never use `route-override`, `--est-pct`, `--min-headroom 0` or
- If all three are short, wait for the reset. Never merge on a weaker
review, and never substitute an Opus review. A GitHub app review (for
example the chatgpt-codex-connector bot) is not the frontier review.
- The `/bigteam` adversary round (omp Opus) still runs where bigteam calls
for it. It is additional and never counts as the frontier review.
- The additional adversary round still runs where the current ADE workflow
calls for it, using an eligible judgment route. It never counts as the
cross-model frontier review and must not revive the retired omp client.
- The PR body names each reviewer model and effort, quotes the verdict (or
"no findings") and lists what was fixed.
4. **Limits that still hold.** The quota guard, estimate floors and in-flight
reservation (`acp-dispatch` exit 5); per-wave frontier caps
(`config/gates.toml [frontier]`); no Fable `xhigh`/`max` without djbclark's
approval; one astra slice at a time (four at once emptied Codex's 5-hour
window on 2026-10-18). Every astra, Fable or Argon review goes through
`acp-dispatch --kind frontier`, never a hand-run `acp-run`.
5. **Gemini 4 Carbon** (announced 2026-10-28, not yet reachable by us):
recheck weekly with `paseo provider models antigravity` (the agy TUI
and `acp-run agy --info` are retired as of 2026-11-06, slim-down E9) and
`aiuse --available --json`. When it is reachable, adopt it as the Google
frontier model in place of Argon.
4. **Limits that still hold.** Preserve the effective frontier allowance
and per-wave caps from ADE's `config/gates.toml [frontier]`, estimate
floors/caps, headroom and in-flight reservation accounting. The 20-point
Astra estimate override is not a permanent minimum quota balance and
waives no other check. Fable remains advisory; execution or elevated
effort requires the operator approvals prescribed by ADE. No Fable
`xhigh`/`max` without djbclark's approval. At most one Astra slice at a time.

Native `route_agent.py plan` checks fit against the remaining reading
but does not subtract sibling in-flight reservations. Re-planning alone
does not restore that protection. Until native reservation admission is
verified, serialize launches only when one coordinator can establish
exclusive control of the pool, account for every existing consumer, and
retain the reservation through completion and refreshed usage
reconciliation. If that cannot be proven, hold the review; do not launch
unguarded or revive retired tools. Missing admission parity remains a
blocker to operational migration completion.
5. **Gemini 4 Carbon** (announced 2026-10-28, availability unverified here):
recheck weekly with `paseo provider models antigravity` and
`aiuse --available --json`. Adopt it as the Google frontier model only
after confirming the intended subscription pool, native routing and
admission checks.
Loading