diff --git a/AGENTS.md b/AGENTS.md index 2817552..bb364ae 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,7 +1,10 @@ # nix2cf — notes for AI sessions +`CLAUDE.md` is a symlink to this file. + Generates CFEngine policy from Nix expressions, so CFEngine semantics are load-bearing here. + ## CFEngine reference book — query it, don't guess (2026-10-03) `Learning CFEngine` (Diego Zamboni, 2nd ed.; covers CFEngine 3.12) is in the @@ -22,3 +25,71 @@ query it rather than relying on recall: Never read `~/kb/raw/learning-cfengine.md`: that is the entire book, ~115k tokens. The index exists so you don't have to. Full detail, including how to add a book: `site-private/AGENTS.md` ("Book knowledge base"). + +## Standing rule: most important work — be pedantic, pay for the best models (2026-10-31) + +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): `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. + +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 + describes. When in doubt, look it up (the CFEngine book, upstream source, + the host itself) instead of assuming. Take the slower path. Never narrow + scope or call something verified that you did not run, and say what you did + not check. +2. **Models.** Every lead session runs Opus 5.5 `high`, pipeline-only sessions + (merges, waiters) included; `[lead].pipeline_model` does not apply here. + Never Sonnet as a lead, and Fable is never a lead. Code slices run on + Sonnet 5.5 `high` or better (agy's Opus pool is fine) on whichever pool + `route_agent.py plan` picks, through `/bigteam`. Never use a weaker tier + (GLM, Gemini Flash, Cursor Auto, `gpt-6-luna`) in these repos. A slice + climbs a tier only on evidence of failure. +3. **Review is cross-model, never same-model.** An Opus review of Opus work is + one model with a fresh context, not an independent check. No PR merges on a + review by the model family that wrote the change. For Opus- or + Sonnet-authored work, astra, Fable or Argon count; for a Codex-authored + slice, Fable or Argon count. + - Every PR, docs-only included (this rule's own PR was reviewed this way), + 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 " 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-run agy --model gemini-4-argon --effort high -C WORKTREE -f BRIEF`, run with read-only instructions in the brief. Argon was probed working on 2026-10-31 and has its own weekly window. Use `acp-run` until djbclark-ade's Argon frontier wiring lands; until then, record the model, effort and `aiuse` reading in the PR body yourself. + - A pool is **short** when `acp-dispatch` answers exit 5 (`unavailable`: + wont-fit, inflight, headroom or preflight), when `aiuse --available --json` + lists it `usable_now: false`, or, for Argon, when `acp-run agy` fails on + quota. Short means move to the next model in the order, never force it. + Say in the PR body which model was short and why. As of 2026-10-31 astra + is short: Codex has 45% left, below the 60% `codex:frontier` estimate + floor, so Fable takes the first seat. + - 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 + for one of them and never counts twice. With both astra and Fable short, + take the Argon review now and wait for a reset for the second. A + disagreement goes to djbclark, not to the lead to settle. + - 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 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 or Fable review goes through + `acp-dispatch --kind frontier`, never a hand-run `acp-run`. Argon is the + one exception, for the reason given in item 3. +5. **Gemini 4 Carbon** (announced 2026-10-28, not yet reachable by us): + recheck weekly with `acp-run agy --info --model gemini-4-carbon` and + `aiuse --available --json`. When it is reachable, adopt it as the Google + frontier model in place of Argon. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file