GameCult/Eureka
Watch
9
0
Fork
You've already forked Eureka
 0
Code Issues Pull requests 3 Projects Releases Packages Wiki Activity Actions

briefs: one canonical wait block, fresh/offset log paths, pid-form caveat, consistent scratch paths

Browse source 
F1/F2: Hands block says prefer log+WAIT_PID, pid form means gone not succeeded,
fresh log per job or WAIT_FROM at launch. F3: exact Aetheria DOCKER_ARGS mounts.
F8: Soul points at the Hands block instead of rewording it; Imagination and
Eyes templates name wait-on.sh, <scratchpad>/<agent>/ and py -3; all examples
use <scratchpad>/<agent>/.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Eureka 2026-10-08 15:04:22 +02:00
commit de35a72fc3
1 changed files with 36 additions and 35 deletions
Download patch file Download diff file Expand all files Collapse all files

71
references/briefs.md
View file

@ -109,6 +109,8 @@ commits.
Rehydrate (recipes: target in force, rulings in force, open questions and
follow-ups). Read enough of the Body to enumerate the persistent kinds. Orient
and probe through scripts, one call per question, output at most 150 lines.
Wait only through `tools/wait-on.sh` (never `true`, `echo` or `sleep`), write only
under `<scratchpad>/<agent>/`, and use `py -3` for Python.
Give one table, a row per persistent kind:
- Identity: what names it. Is the namespace stated? Is the name injective? Can
@ -138,9 +140,11 @@ Admit only cut_specs, their superseding resolutions, and questions. In the
prose map at <path>, edit body facts and rationale. Also edit the model page
whenever a probe changes a row's identity, lifecycle or authority. Imagination
wrote that page in 0b, and a model a cut contradicts is stale steering text.
Do not commit; the root agent commits. Do not change code in any repo. Scratch probes in
<scratchpad> are fine. Orient and probe through scripts: one call per question,
output at most 150 lines. Budget 40-80 calls and about 250k context.
Do not commit; the root agent commits. Do not change code in any repo. Scratch probes under
<scratchpad>/<agent>/ are fine. Orient and probe through scripts: one call per question,
output at most 150 lines. Wait only through `tools/wait-on.sh` (never `true`,
`echo` or `sleep`), write only under `<scratchpad>/<agent>/`, and use `py -3` for
Python. Budget 40-80 calls and about 250k context.
Rehydrate (recipes: target in force, rulings in force, open questions and
follow-ups, specs with no report, one cut's record for <cuts that constrain
@ -314,26 +318,34 @@ one head (SKILL.md, step 3); keep it fitting:
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 (run_in_background) with
`SUMMARY=<scratchpad>/<job>.log` in front of `tools/stopgap/ygg-verify.sh`, a
`SUMMARY=<scratchpad>/<agent>/<job>.log` in front of `tools/stopgap/ygg-verify.sh`, a
fresh log path per job. Then wait in the foreground, one call at a time:
`tools/stopgap/ygg-verify.sh wait <scratchpad>/<job>.log` blocks for at most
`tools/stopgap/ygg-verify.sh wait <scratchpad>/<agent>/<job>.log` blocks for at most
270 s (run it with a Bash tool `timeout` of at least 280000 ms: the default 120 s backgrounds the call and costs a wake), so your cache stays warm, and prints the bounded summary when the job is
done. If it prints `RUNNING <n>s` (exit 99), call it again. Exit 98 means the
launcher is gone with no verdict: rerun the job, do not guess its outcome. 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 in a loop of your own, and
send no interim message.
Every other wait goes through `tools/wait-on.sh`, never a loop of your own:
`wait-on.sh pid <pid> [<log>]` for a detached process, `wait-on.sh log <log>
<done-regex>` (with `WAIT_PID=<pid>` to notice a dead process) for a build, a
Unity batchmode run or a script that writes a done line, `wait-on.sh file
<path>` for an output file. It has the same contract: pass a Bash tool
`timeout` of at least 280000 ms, it blocks at most 270 s, exit 0 is done with a
bounded log tail, `RUNNING <n>s` (exit 99) means call it again, exit 98 means
the thing is gone with no completion evidence. Bare `true`, `echo waiting` and
`sleep` calls are forbidden as polling: on 2026-10-07 and before, Hands and
Soul runs made 974 idle `true`/`echo` calls and 324 `sleep` calls (49 refused
by the harness), each one a model turn that waited on nothing.
Every other wait goes through `tools/wait-on.sh`, never a loop of your own.
Prefer `tools/wait-on.sh log <log> <done-regex>` with `WAIT_PID=<pid>` whenever
the job writes a done line (a build, a Unity batchmode run, a script that echoes
`DONE`): it is the only form that can tell success from a crash, because a dead
pid with no match is exit 98. `tools/wait-on.sh pid <pid> [<log>]` is only for a
process with no completion evidence; it prints `GONE (no completion evidence)`
and its exit 0 means "gone", not "succeeded". `tools/wait-on.sh file <path>` is
for an output file written last. The regex is an ERE; an invalid one is exit 3.
Use a fresh log path per job. If a log path is reused (Unity `-logFile`, a
re-run script), record where it ended at launch and pass it, so a stale done
line from the earlier job does not count: `WAIT_FROM=$(wc -c < <log> 2>/dev/null
|| echo 0)` captured before the launch, then `WAIT_FROM=<n> tools/wait-on.sh log
<log> <regex>`. Same contract as the ygg-verify wait: pass a Bash tool `timeout`
of at least 280000 ms, it blocks at most 270 s, exit 0 is done with a bounded
log tail, `RUNNING <n>s` (exit 99) means call it again, exit 98 means the thing
is gone with no completion evidence. Bare `true`, `echo waiting` and `sleep`
calls are forbidden as polling: on 2026-10-07 and before, Hands and Soul runs
made 974 idle `true`/`echo` calls and 324 `sleep` calls (49 refused by the
harness), each one a model turn that waited on nothing.
Write only under your own scratchpad subdirectory, `<scratchpad>/<agent>/`:
a shared `job.sh` or probe file gets overwritten (one Soul clobbered `job.sh`
and `SoulProbe.cs`, 2026-10-07).
@ -375,7 +387,7 @@ Verification: <exact builds, tests, captures, negative greps>.
the LF content (`git show <rev>:<path>`), never from the CRLF Windows checkout.
A run whose ranges hit nothing tests nothing, and a green with zero mutants
tested is not evidence (line-scoped runs tested nothing, 2026-10-06).
- Aetheria verify jobs set `DOCKER_ARGS` to mount `/pins` and `/lfs-aetheria`.
- Aetheria verify jobs set `DOCKER_ARGS='-v /home/gamecultadmin/eureka-verify/pins:/pins:ro -v /home/gamecultadmin/eureka-verify/lfs-aetheria:/lfs:ro'` (jobs that read sibling repos add `-v /home/gamecultadmin/eureka-verify/repos:/repos:ro`).
- Revert incidental asset churn.
Budget: if the cut can't land coherently, stop at a pushed, building commit
@ -422,21 +434,9 @@ below. Admit one verdict and its findings, and nothing else.
- Check the report's per-project test counts against the project files
yourself. A consuming test project missing from the report is a finding,
and you run it.
- Long jobs: wait for them and finish, and never end your turn before your
report. Run the job as one background shell with `SUMMARY=<scratchpad>/<job>.log`
in front of `tools/stopgap/ygg-verify.sh` (a fresh log path per job), and wait
in the foreground with `tools/stopgap/ygg-verify.sh wait <that log>`: pass a Bash tool `timeout` of at least 280000 ms (the default 120 s backgrounds the call and costs a wake); it blocks
at most 270 s and prints the bounded summary when the job is done, or `RUNNING
<n>s` (exit 99) and you call it again. Exit 98 means no verdict: rerun, do not
guess. No second watcher, no timer under 60 s in a loop of your own, and no
interim message: each turn end is a paid wake of Self. Every wait that is not
a Yggdrasil job goes through `tools/wait-on.sh` (`pid <pid> [<log>]`,
`log <log> <done-regex>`, `file <path>`; same 280000 ms timeout rule, same
`RUNNING`/exit 99 and exit 98 contract); bare `true`, `echo` or `sleep`
polling is forbidden. Write only under `<scratchpad>/<agent>/`: a shared
`job.sh` or probe file gets overwritten (one Soul clobbered `job.sh` and
`SoulProbe.cs`, 2026-10-07). Python is `py -3` (works from Git Bash and
PowerShell; bare `python` hit the Windows Store stub in 65 calls, 2026-10-07).
- Long jobs and waits: Self pastes the Hands brief's `Long jobs` block here
verbatim (the canonical wait protocol, including the scratch subdirectory and
`py -3` rules); do not reword or shorten it.
- Bound every observation: no command prints more than about 150 lines, logs go
to files, and you read windows of them.
@ -484,7 +484,7 @@ specifically:
probes into one job script rather than one job each. Run the mutation tool
in parallel (`--jobs 3`), and skip by name any test that a follow-up records
as flaky, so that its flakes cannot count a surviving mutant as killed.
Dump the range once (`git diff <base>..<head> > <scratchpad>/range.diff` plus
Dump the range once (`git diff <base>..<head> > <scratchpad>/<agent>/range.diff` plus
`--stat`) and grep that file instead of re-running `git show` per file. Hand
mutants go in one list to `tools/mutation-table.sh`, never one job each.
@ -563,9 +563,10 @@ what was missing and what it would have prevented.
Dispatch: `subagent_type: eyes`, model Sonnet.
```
Write findings to <scratchpad>/<name>.md and return a
Write findings to <scratchpad>/<agent>/<name>.md and return a
short summary. Budget at most 40 calls: transcripts by script, never whole
reads, and fetches batched in parallel. You read the campaign's mind with query and view only, through
reads, waits only through `tools/wait-on.sh`, writes only under
`<scratchpad>/<agent>/`, Python as `py -3`, and fetches batched in parallel. You read the campaign's mind with query and view only, through
the Rehydrate block (recipes: <as needed>); you never admit.
Sources: