improvise/.agents/skills/wave/agent-rules.md

Standing rules for a wave agent

Every work-unit agent reads this in full before its first command. A brief points here and adds only what is specific to its wave: the expected base commit, the agent's ground, its BEADS_ACTOR, and its tickets. Every rule below was bought by a failure.

This file holds each agent-side rule once. The brief checklist is SKILL.md beside it. Where AGENTS.md ("The Wave Workflow") carries a longer history, the rule here points there. Change a rule here, not in a brief, and not in a second copy.

Base, branch, push

1. Verify your base against the commit your brief names, first. Run git log --oneline -1 and compare. Worktrees do not reliably branch from the orchestrator's HEAD: one was created three merges behind, and it was only noticed because the agent was told to look.
2. Branch from gh/main, never main or origin/main. git fetch gh && git checkout -b <branch> gh/main. A worktree handed to you may already sit on unpushed commits. Why: AGENTS.md, "Shipping a wave" (the two remotes both spelled main, and the worktree-base vector).
3. Before opening a PR, check git diff --numstat gh/main...<branch>. Do not use gh pr view --json files: that is the union of your commits' files, not the effective diff.
4. Push with an explicit refspec: git push gh HEAD:refs/heads/<branch>. A branch cut from gh/main tracks gh/main, so a bare push targets main and is refused.
5. Before pushing a fix to an existing PR, check gh pr view <n> --json state. GitHub deletes a merged PR's branch. A push to it then prints * [new branch] and lands nowhere. Why: AGENTS.md, "Shipping a wave".
6. The Beads "Session Completion" block near the end of AGENTS.md does not set your git policy. This repository does not opt in to the block's "team-maintainer" profile. On a wave branch that profile's pull and bare git push would be refused (rule 4), or worse. Rules 1–5 and 7 are your git policy. The block is bd's and bd regenerates it whole, so it is not edited by hand: AGENTS.md, "Repository policy over the Beads blocks" (improvise-x1uk).
7. Pin gh/main to a literal SHA when the task starts. Run git rev-parse gh/main once. Use that SHA, not the ref name, for every reset, merge-base and diff. Remote refs are shared by every worktree of the repository, so gh/main moves whenever another session fetches. An agent ran git reset --soft gh/main mid-task and staged a reverse diff of #196. It noticed only because it read git status (improvise-diho). Re-resolve only on purpose, for example when you mean to merge a newer main. Rule 3's check before a PR is such a time.

Commit early: a worktree is not durable storage

Commit a WIP as soon as your first test run is green, and again after every meaningful step. Push your branch (rule 4) once it is worth keeping. An agent finished a whole ticket with every gate green and lost all of it, uncommitted, when its worktree was deleted in a disk cleanup. A local commit survives a deleted worktree. Tidying history before the PR is fine; losing it is not.

Gates

direnv exec . ./scripts/fmt-workspaces.sh          # NOT cargo fmt --all; exit 2 = the gate did not run
direnv exec . ./scripts/check-harness-lock.sh      # offline; a Cargo.toml change can stale harness/opfs-contract's lock
direnv exec . cargo clippy --workspace --all-targets -- -D warnings
direnv exec . cargo test --workspace --no-fail-fast
direnv exec . python3 scripts/check-comment-runs.py --self-test
direnv exec . python3 scripts/check-comment-runs.py --check-evidence   # also answers the comment cap
direnv exec . python3 scripts/check-ci-graph.py --self-test
direnv exec . python3 scripts/check-ci-graph.py
direnv exec . ./scripts/checkers.sh                # every suite in scripts/, its own self-test included
direnv exec . tpl prolog-sessions/kb.pl -g "(kb_consistent -> halt(0) ; (kb_report, halt(1)))"
direnv exec . ./scripts/node-test.sh 'web/tests/*.test.js'

This list is the test, js and kb jobs of .github/workflows/ci.yml, step for step, and this file is the one place it is written down. Change it in the same PR that changes CI. The other CI jobs are conditional, below, or left out on purpose:

• wasm: when you touch a crate it checks (next bullet).

• harness-lint: when you touch harness/opfs-contract, run cargo clippy --target wasm32-unknown-unknown --all-targets -- -D warnings from that directory. Its format half is already fmt-workspaces.sh.

• build and browser: when you touch web/, harness/, or the surface the page calls in improvise-wasm-client or improvise-worker-server (third bullet).

• pages-deploy is left out. It deploys, and it runs only on a push to main. What guards it locally is check-ci-graph.py, which is in the list.

• Never cargo fmt --all. It reaches only one of this repo's two workspace roots, because harness/opfs-contract declares its own [workspace]. The obvious repair is worse: cargo fmt -p opfs-contract from the repo root exits 1, "not a member of the workspace", which looks exactly like a real formatting failure (improvise-b4ks). Both spellings fail in the direction that looks like success.

• Run every gate under direnv exec .. ./scripts/checkers.sh scrubs the environment to an allowlist, so a bare run drops tpl off PATH and reports spurious failures.

• Never pipe a gate. $? must be the gate's own. And check-comment-runs.py --check-evidence prints two lines with the comment cap first, so | tail -1 silently drops half of it. fmt-workspaces.sh is the one most often lost this way: an unformatted tree exits 1 and prints a diff, and | tail shows the diff's last lines and exits 0. Read its exit status, or run it with --fix and commit what it rewrites.

• CI takes every tool from nix develop .#ci, and so should your scripts: no /bin/… or /usr/bin/… paths, and no bash-version or tool-version probes (AGENTS.md, "CI takes its tools from the dev shell"). A test that needs a restricted PATH builds one on purpose. It does not assume the runner's /bin holds anything, because on the NixOS runners it holds only env and sh.

• --no-fail-fast, because plain cargo test --workspace stops at the first failing binary. Use it for any claim about blast radius.

• If you touch a browser-bundle crate (core, formula, io, protocol, command, wasm-client, worker-server) or improvise-gp, also run cargo check --target wasm32-unknown-unknown -p <crate> for each crate. CI checks each one separately, so feature unification cannot hide a leak.

• If you touch web/, harness/ or the page's wasm surface, run ./harness/build.sh, then ./scripts/node-test.sh 'web/tests/bundle/*.test.js', then npm ci and npx playwright test in harness/. The bundle tests sit outside the web/tests/*.test.js glob and read the built web/pkg, so the standard list never runs them. They failed only in CI once. A fresh worktree has no harness/node_modules, and Playwright then reports a missing @playwright/test, which reads like a broken checkout.

• Playwright serves harness/serve/, not web/. harness/build.sh assembles that tree and it is gitignored, so after any change to web/*.js — yours, or one a merge brought in — re-run ./harness/build.sh before the specs. Otherwise they test the old page. That failure looks exactly like a real regression (doctrine(rebuild_the_assembled_site_after_merging_web)). CI runs Chromium and Firefox only (--project=chromium --project=firefox), so run those two locally.

• If you change the grid's row or column count, also grep harness/fixtures/*.improv and harness/tests/*.spec.js. On PR #176 a Playwright spec pinned the old collapsed-group row count. cargo test cannot see that.

• A PR that conflicts with its base gets no CI run. So anything "left to CI" is unchecked until the PR is mergeable (PR #177).

• Measure your own baseline before changing anything, and report it with the machine it was measured on. A figure from the brief is a reference, not your baseline.

• Merge gh/main and re-run every gate before calling a PR green. Then check that no test disappeared. Diff test names, not counts: a textually clean merge can delete a test module with no conflict marker, and the other side's new tests mask the loss in a count.

• Build each side's test list in a fresh CARGO_TARGET_DIR, every time. If a parent's tree comes from git archive, a reused target dir gives a wrong answer, not just a slow one. Archive stamps every file with its commit time, so cargo judges the sources older than the last build and lists the previous tree's tests. On #188 that made three of the branch's own tests look merge-only.

• The shell guard refusing a compound command means NEITHER part ran. Split the command. After a refusal, re-check the state it was meant to produce.

• Re-run the full suite after reverting an injected fault. A revert applied to the wrong occurrence once shipped two faults past every other gate.

Discipline per ticket

• Claim first: export BEADS_ACTOR=<your actor> in every shell, then bd update <id> --claim. Exit 13 means another actor holds it. Pick another; do not retry.
• bd needs .envrc allowed in your worktree. Without it you get a version mismatch, not a clean failure. Run direnv allow in the worktree, or rely on the [whitelist] prefix in ~/.config/direnv/direnv.toml. direnv status reports Found RC allowed 0, and 0 means allowed (the enum is 0=Allowed, 1=NotAllowed). It reads like the opposite.
• Reproduce at HEAD before fixing. A dozen tickets were stale-open in one campaign, one fixed two days before it was filed. If it does not reproduce, find the fixing commit, confirm with git merge-base --is-ancestor <sha> HEAD, report the SHA, and close nothing.
• Write a failing test first, then inject a rival and watch it fail. Run it; do not reason about it. Report where it failed, by case name. An injection that does not compile reads as a clean run, so get a positive signal that the build ran.
• Check your test against every vacuity shape seen here:
  • an assertion the default state already satisfies;
  • f(x) == f(x): calling a pure Cmd twice against one immutable context;
  • a disjunctive assertion whose other branch is the bug's own symptom;
  • a rival that fails the setup, which proves the neighbouring question (e.g. setup and subject share an EffectKind);
  • a fixture that is right by accident (expected value 1, group at row 0, bystander already on the relayed value);
  • a fixture or stub that lacks the structure the hazard needs, or fails in a wider shape than the real fault;
  • hand-picked fixture cases where the set could be enumerated: four vacuities in fmt-workspaces-test.sh were each a case nobody thought of (improvise-90ea);
  • a rendered-output test at a width where the thing asserted is never drawn;
  • a fold test that batches differently from the real producer (a Binding::Sequence is ONE effect vec);
  • the cursor at index 0: "the item under the cursor" and "the first item" are indistinguishable there, and that was four of five findings in one review. Seat the cursor at a nonzero index of a list with at least two elements;
  • a determinism check against ONE context instance: every HashMap iterates the same way twice. Build two equal contexts independently (improvise-hzjo);
  • two derivations of one fact where the fixture makes them agree (drawn vs committed, edit text vs value, 1200 vs 1.23456789). Use a value where they disagree.
• Record each bug in context/test-evidence/<area>.md, keyed by test name (module-qualify the name when the leaf is not unique). It is append-at-EOF, so expect a conflict. Keep both sides and verify line by line against both parents: --check-evidence cannot see a dropped entry.
• Never resolve a conflict with git checkout --ours or --theirs. Either one takes the whole file from one side and silently drops the other side's non-conflicting changes to it. That is how a ci.yml step vanished while the merge message said it was unchanged (improvise-dndu). After resolving, diff the merge against each parent and against the merge base (AGENTS.md, "Merging many PRs at once").
• Comment runs are at most two lines. Reasoning goes in context/, not in comments (context/design-principles.md §6).
• If the acceptance criteria look wrong, argue it rather than following them silently. Three agents inverted theirs in one campaign, and all three were right.

Files you must not write

.beads/** (never commit issues.jsonl, never git checkout it), prolog-sessions/kb.pl, context/repo-map.md: AGENTS.md, "Who owns what". Also AGENTS.md, unless your brief grants you a named section. Report proposed text for any of these in your hand-back.

GitHub

• gh is shell-aliased to a different tool. Use nix shell nixpkgs#gh --command gh …, and pass bodies with -F body=@file.
• Everything posted goes out under the repository owner's account. Open every PR body and comment with the attribution line your brief gives you, verbatim. It names your agent and model, which is how our posts are told apart from an automated Codex review (AGENTS.md, "Shipping a wave").
• The attribution line, commit trailers and PR footer all come from your brief. They name the agent and the session, so this shared file cannot hold them.
• Read reviews with ./scripts/pr-reviews <n>, and do not pipe it. It also shows inline comments, which is where Copilot puts most of its findings. Copilot reviews here again (2026-09-24), so answer its findings as you answer Codex's. How to tell a Codex review from ours: AGENTS.md, "Shipping a wave".
• As a PR's author, reply on the PR to every review finding you address. Name the commit that fixes it, or say why you declined it. Putting it only in your hand-back to the orchestrator is not enough: the PR thread is where the next reader looks.
• As a reviewer, read the existing reviews first, with ./scripts/pr-reviews <n>, unpiped. Reply on its thread to every Codex review: fixed (name the commit), declined (say why), or already one of our tickets (name it). Every review you post states the head SHA it reviewed.
• Answer a review even if the PR has already merged. Reviews arrive late, and the thread is still where the next reader looks.
• Do not merge, and do not close beads. Your part ends at an open PR plus your hand-back. What "done" means is in AGENTS.md, "Repository policy over the Beads blocks". Avoid stacked PRs. If you must stack, say in the PR body which PR it is stacked on. Once that base PR merges, check the stacked PR's baseRefName (gh pr view <n> --json baseRefName) and, unless it is main, retarget it with gh pr edit <n> --base main before anyone merges it: merging it otherwise lands it in the stale base branch, not in main. Fifteen PRs did that on 2026-09-24 (AGENTS.md, "Shipping a wave").

Hand-back, per ticket

Report:

• your branch, head SHA and PR number. Review is dispatched against the SHA;
• what changed, per ticket;
• the claim result;
• your measured baseline;
• whether the ticket reproduced (the SHA if it did not);
• the rival and where it failed;
• what you could not verify, and why;
• proposed repo-map and kb.pl text;
• what the ticket did not predict, consistently the most valuable part.

Disk

Each worktree's target/ grows to 3–6G, and a full disk (ENOSPC) once stopped every agent. When you hand back, delete your own build output, and only yours.

Run pwd and git rev-parse --show-toplevel first, and read the answer. Then delete by literal absolute path, typed out: rm -rf /Users/.../.claude/worktrees/agent-<you>/target.

Never interpolate a computed path into rm -rf. One agent's worktree had been removed, so $(git rev-parse --show-toplevel) printed nothing and the command became rm -rf "/target". A guarded one-liner was tried, but the worktree shell guard refuses it as too complex, which pushed agents back to an unguarded form. A literal path is the version that is both allowed and safe.

Keep your branch and any uncommitted work. Delete only target/ (and harness/opfs-contract/target if you built it). If you see ENOSPC, stop and report rather than deleting anything outside your worktree.