diff --git a/SKILL.md b/SKILL.md index 6029b91..ce9cc6d 100644 --- a/SKILL.md +++ b/SKILL.md @@ -217,6 +217,10 @@ for map cuts and fix batches alike. Sonnet degrades at about 0.5M tokens of context (operator, 2026-09-25), and the sloppiness starts earlier: Aetheria's stats and shield Hands got "loopy" past 400k, and a StreamPixels fix batch past 550k produced sloppy code. Treat 0.5M as the danger line, never the target. +Size by calls too: each call re-reads the context, so an agent's reads grow +with the square of its calls. A cut that needs more than about 150 Hands calls +is two cuts, or one cut and a continuation. + Before dispatch, Self estimates what the run will carry: - the brief, and the `cut_spec` Hands views; @@ -511,6 +515,25 @@ and reconciles the target doc with the Body. follow-ups in the mind; "Substrate gaps" in `references/campaign-state.md` gives the query and where a new one is admitted. - **Never claim an agent's result before its notification arrives.** +- **Self's own context is the most expensive in the pipeline.** Every + notification re-reads all of it. Rotate at about 300k context or at a phase + boundary: write a short handoff (campaign slug, session label, in-flight + agent ids, next action) to the scratchpad and ask the operator to `/clear`. + Agents are capped at about 300k context or 150 calls, after which a fresh + continuation agent takes over. Never read logs or diffs in the root; `view` + reports and verdicts. +- **A subagent that notifies before its report is a brief defect.** Count + finished notifications per agent. More than one means a turn ended + mid-wait, and the brief template is what gets fixed. + +### Shared tools + +Scripts that agents share live in this repo under `tools/`. `tools/INDEX.md` +lists each script, its consumer and the brief that names it; briefs name the +exact script they want and agents do not browse. Contributions come by branch +and pull request, never a push to main. A script that verdicts depend on gets +a Soul pass before merge. A script whose brief no longer names it is pruned. +Scripts that know a project's layout stay in that project. ## Git and tooling rules (scars) @@ -539,9 +562,8 @@ and reconciles the target doc with the Body. is Idunn's verify transaction (a campaign in progress, ruled 2026-09-22). Until it lands, use the stopgap `tools/stopgap/ygg-verify.sh`. It pushes an exact revision to a mirror on Yggdrasil and runs one command in a container - capped at 4 CPUs and 12 GiB, niced, with at most 3 jobs at a time (raised - from 2 by the operator on 2026-09-22: "the other cores are mostly sitting - idle"). **The script owns these numbers; where this text and `ygg-verify.sh` + capped at 4 CPUs and 6 GiB, niced, with at most 5 jobs at a time. **The script + owns these numbers (`CPUS`, `MEM`, `SLOTS`); where this text and `ygg-verify.sh` disagree, the script is right** — this line was already stale once. Every Hands and Soul brief says so. Starfire runs only what has to run on Windows, such as the QUIC win32 scenarios: one job at a time, never burners. @@ -565,17 +587,17 @@ and reconciles the target doc with the Body. Node process on the shared workstation, including other agents' and the operator's. Record the PID of every process you launch, and stop only those PIDs. -- **Write commit messages with the Write tool to a uniquely named scratch file, - then `git commit -F`.** PowerShell 5 here-strings break `-m` quoting, and its - `Out-File`/`Set-Content` write a BOM into message files. - Shared filenames like `msg1.txt` collided between parallel agents. +- **Commit from Git Bash with `git commit -F- <<'MSG'`.** PowerShell 5 + here-strings break `-m` quoting, and its `Out-File`/`Set-Content` write a BOM + into message files. - **Push at most three tags per push.** GitHub skips tag-triggered workflows when one push carries more tags, so the npm and PyPI publish jobs silently never ran. - **Keep release byte checks commit-independent.** Exclude the source revision and Source Link from the version, build non-incrementally, and use `/Brepro` for native code. A committed DLL otherwise always carries its parent's SHA. -- **Run long builds detached, with a log and a PID, and poll.** Unity batchmode - and similar builds must never be one attached call. Revert incidental asset +- **Operator-side builds run detached, with a log and a PID.** Unity batchmode + and similar builds must never be one attached call. Agents waiting on a job + do so in the foreground, in calls of at most 270 s (briefs, Hands). Revert incidental asset churn afterwards, such as Unity's SDF font asset. - **Before a mass-spawn or process-launching probe, read how the child chooses its role.** A probe that relaunched its own executable fork-bombed the workstation diff --git a/references/briefs.md b/references/briefs.md index 78aeac5..8a1bda6 100644 --- a/references/briefs.md +++ b/references/briefs.md @@ -12,6 +12,15 @@ Every brief that reads or admits campaign state carries: - the Rehydrate block below, as the agent's first step, with `` set to the recipes that brief names. +Every dispatch names its model: Sonnet for Hands, probes, search and Life; Opus +for Imagination and for Soul over a cut that puts the foundation at risk. +Never leave it as "default", which inherits the root's model. + +Every agent is capped at about 300k context or 150 calls. At the cap it +commits what is verified, admits its report with what is undone, and stops; +Self dispatches a fresh continuation agent with the report id. Do not stop +because the scope merely looks large. + This block is the one definition of rehydration; the other files point here. ## Contents @@ -272,15 +281,15 @@ one head (SKILL.md, step 3); keep it fitting: deliverable, and say the budget is sufficient for it. The hand-back clause is for a head that is actually full, not for a job that looks big. -Long jobs: wait for them and finish. Never end the turn with a to-do list in -place of a report. Every turn you take is a paid model call, so waiting must -cost no calls. Start the job as ONE background shell (run_in_background) whose -command exits only when the job does: chain build, suite and mutations in one -script, or block remotely (`until ; do sleep 60; done`). The -harness wakes you once, when it exits. Never poll in foreground chunks, never -run a second watcher on the same job, and never use a wait timer shorter than -60 s. Announcing the wait in a final message is the violation: end the turn -with the waiter running and say nothing, or read the finished output. +Long jobs: wait for them and finish, and never end your turn before your +report. Each turn end reaches Self as a notification and costs a read of its +whole context. Start the job as one background shell whose command exits only +when the job does. Then wait in the foreground, one call at a time, each at +most 270 s so that your cache stays warm: `timeout 270 bash -c 'until [ -e + ]; do sleep 60; done'`, then read the result or call again. A call +longer than 5 minutes rewrites your whole context. Never run a second watcher +on the same job, never use a timer shorter than 60 s, and send no interim +message. Mutation tools run on schemata or copies and never edit the tree. A Soul probe that mutates by hand works on a scratch copy: the stopgap's container or a throwaway clone, never the working tree. @@ -299,14 +308,14 @@ Commits: - Never amend a commit or force-push. Self and other agents commit on the same branch while you work. Fix a commit with a new commit. On a rejected push, `git pull --rebase`, then push. -- Write each message with the Write tool to /-.txt, then run - `git commit -F`. +- In Git Bash, one call: `git add && git commit -F- <<'MSG' ... MSG && + git push`. Never commit from PowerShell (it writes a BOM and breaks + here-strings). - End each message with the attribution trailer. -- Check each message with `git log -1 --format=%B`. - Say in the message which commits don't build. Verification: . -- Long builds run detached, with a log in the scratchpad; poll the log. +- Verify through `tools/stopgap/ygg-verify.sh`; read its output tail, and open the full log only at a named failing test, with `grep -n -A 40`. - Revert incidental asset churn. Budget: if the cut can't land coherently, stop at a pushed, building commit @@ -347,10 +356,12 @@ Admit one verdict and its findings, and nothing else. - Use a temporary detached worktree for other checkouts, and remove it afterwards. - Do not run unless told. -- Long jobs: one background shell per job whose command exits only when the - job does (or a remote `until ...; do sleep 60; done`); the harness wakes you - once on exit. No foreground poll chunks, no duplicate watchers, no timer - under 60 s, and no interim "waiting" messages: each is a paid model call. +- Long jobs: wait for them and finish, and never end your turn before your + report. Run the job as one background shell whose command exits only when the + job does, and wait in the foreground in calls of at most 270 s (`timeout 270 + bash -c 'until [ -e ]; do sleep 60; done'`). No second watcher, + no timer under 60 s, and no interim message: each turn end is a paid wake of + Self. Scope: . Rehydrate (recipes: target in force, rulings in force, one cut's record for ), then view the report (its range and its promises), the cut_spec it diff --git a/references/changelog.md b/references/changelog.md index eec8130..63443bc 100644 --- a/references/changelog.md +++ b/references/changelog.md @@ -2,6 +2,14 @@ Record each change to the skill together with the evidence that motivated it. +## 2026-10-01: waiting costs no wakes, and a shared tools directory + +Operator rulings on `references/tool-calling-cut.md`, verbatim: "Q1 A, Q2 yes, Q3 agreed, Q4 B, Q5 yes, but see Epiphany's approach where each subagent gets its own targeted philosophy centered on its role". + +Evidence: 602 finish notifications from 245 agents and 1,324 root text-only calls, 596M tokens read, with a 5-minute subagent cache TTL. + +What changed. Q1 A amends `92bf6f7`: agents wait in the foreground in calls of at most 270 s and never end a turn before their report, instead of ending the turn on a background waiter. Q3 C: Self rotates at about 300k context or at a phase boundary with a handoff and the operator's `/clear`; agents are capped at about 300k or 150 calls and continued by a fresh agent. Q4 B: shared scripts live in `tools/` with `tools/INDEX.md`, by branch and pull request, Soul before merge for verdict-bearing scripts, pruned when no brief names them. The Yggdrasil verify line in SKILL.md no longer states stale limits (the script sets 5 slots and 6 GiB). Briefs now state that every dispatch names its model. Commit messages go from Git Bash with `git commit -F-`. + ## 2026-10-01: the stopgap no longer forces CARGO_TARGET_DIR In idunn-watchdog's Idunn incident cut, Soul pass s3 ran cargo-mutants twice diff --git a/tools/INDEX.md b/tools/INDEX.md new file mode 100644 index 0000000..84b0647 --- /dev/null +++ b/tools/INDEX.md @@ -0,0 +1,10 @@ +# Shared tools + +One line per script. Briefs name the exact script they want; agents do not +browse. A line whose consuming brief no longer names the script is dead and is +deleted. Contributions come by branch and pull request. A script that verdicts +depend on gets a Soul pass before merge. + +| script | purpose | consumer | named by | +|---|---|---|---| +| `tools/stopgap/ygg-verify.sh` | Pushes an exact revision to a mirror on Yggdrasil and runs one command in a capped, niced container. Dies with the stopgap when Idunn's verify transaction lands. | Hands, Soul, Imagination probes | `references/briefs.md` (Hands and Soul verification), `SKILL.md` (Yggdrasil) |