From ac3313b14b56bb0f020c6825291e804fbd4c7a7c Mon Sep 17 00:00:00 2001 From: Eureka Date: Fri, 9 Oct 2026 14:07:11 +0200 Subject: [PATCH 1/4] Briefs: Imagination writes file_changes as the context pack; Hands expands it first; Soul prints the sites Replaces the sed -n anchor-range clause and the read-twice sentence in the Hands brief. Co-Authored-By: Claude Opus 5.5 --- references/briefs.md | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/references/briefs.md b/references/briefs.md index af3debd..fd3adfa 100644 --- a/references/briefs.md +++ b/references/briefs.md @@ -161,6 +161,12 @@ from the spec by DocRef rather than restating them. The cut_spec's fields are the spec standard. Beyond filling them: - file_changes against base , for code that exists +- file_changes are Hands' context pack. Each range is exact at base and is the + window Hands needs for that change, at most 100 lines (split a longer site). A + new file goes in adds, never as a line-1 anchor. Write no prose about lines + moving. After admitting, run `py -3 tools/context-pack.py `: every anchor must read SAME and each window must show what its + change names, or admit a revision. - cite in `rulings` every ruling in force the cut rests on - the deploy owner: for any cut that changes what a service needs (transport, env, dependency, state), the recipe, binding and runbook that must admit it, @@ -199,6 +205,10 @@ ends there: report the question id and its receipt, and admit no cut_report Repo/branch: at HEAD . Check that git status is clean first. Pinned siblings: . Do not change them. +Before any grep or Read, expand the pack: `py -3 tools/context-pack.py `. An anchor that reads NEW for a path the spec does not create, +OUT_OF_RANGE, UNRESOLVED, or GONE outside deletes is a spec discrepancy: record +it in deviations. When the brief names a worktree, every tool call's path goes under it: Read, Edit and Write as well as the shell's working directory. An absolute path into the main checkout silently edits the wrong tree. @@ -280,12 +290,13 @@ one head (SKILL.md, step 3); keep it fitting: the final sweep will not. One job carries the build, the scoped tests and the mutation run, so the queue and the compile are paid once. - **Orient in one script.** One Bash call prints git status, the base and the - spec's anchor ranges (`sed -n`) for every file the spec names. Independent + pack (`tools/context-pack.py`). Independent reads, views and greps go in one parallel message. - **Bound every observation.** No command prints more than about 150 lines. Logs go to a file; read `tail -n 60` or `grep -n -m`, and read windows of a - file, never the whole of anything over about 300 lines. Reading a file twice - is a smell: write what you need to keep to a scratch notes file. + file, never the whole of anything over about 300 lines. After editing, + `tools/context-pack.py --since ` reprints only the + changed windows; re-read only files you edited. - **Read the spec by id, not the map.** The cut_spec is bounded and holds only this cut; a worker that reads 900 lines of map to find 60 has spent its budget before it starts. @@ -447,7 +458,8 @@ below. Admit one verdict and its findings, and nothing else. 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 -cites, and every ruling the spec cites. Admitting your verdict is a write to +cites, and every ruling the spec cites. `py -3 tools/context-pack.py +` prints the cut's sites at that head. Admitting your verdict is a write to the mind, not to a repo. Hands' promises are one input, not the boundary of the pass. Falsify every -- 2.47.3 From 15a6afe36f5fe8f47e0e1175e6c36e0824411ff4 Mon Sep 17 00:00:00 2001 From: Eureka Date: Fri, 9 Oct 2026 14:07:12 +0200 Subject: [PATCH 2/4] SKILL.md step 1: file_changes are also Hands' context pack Co-Authored-By: Claude Opus 5.5 --- SKILL.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/SKILL.md b/SKILL.md index 21c0929..21818b3 100644 --- a/SKILL.md +++ b/SKILL.md @@ -128,7 +128,9 @@ an edit. **Spend the detail where the map can be wrong, not where Hands will rewrite it anyway.** Anchors against existing code earn their length: they say what to -delete and what not to touch. Transcribing the body of code that does not exist +delete and what not to touch. They are also Hands' context pack, pinned at base +and carried to Hands' tree by `tools/context-pack.py` (ruling +context-pack-resolving-anchors), so each one is stated exactly at base. Transcribing the body of code that does not exist yet does not. A cut section that runs to eight hundred lines against a crate nobody has written is a 1:1 map, and the only spec complete enough at that scale is the code itself. Soul catches a wrong function body cheaply; it cannot catch -- 2.47.3 From 903794ca0c878a8c7eee73f0f8b6b9297f7a9c28 Mon Sep 17 00:00:00 2001 From: Eureka Date: Fri, 9 Oct 2026 14:07:12 +0200 Subject: [PATCH 3/4] tools/INDEX.md: context-pack.py row names the briefs and SKILL.md step 1 Co-Authored-By: Claude Opus 5.5 --- tools/INDEX.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tools/INDEX.md b/tools/INDEX.md index d8e883c..f629edb 100644 --- a/tools/INDEX.md +++ b/tools/INDEX.md @@ -13,4 +13,4 @@ gets a Soul pass before merge. | `tools/mutation-table.sh` | One verify job that runs a list of hand mutants (file, before, after, test) against a revision and returns a kill table: CAUGHT with the killing test, SURVIVED, UNVIABLE, TIMEOUT, NOAPPLY, ERROR. Refuses a red or zero-test baseline and a red BUILD; rows print live. Isolation is Docker's: the baselines run once in a container that holds the revision, that container is committed to a throwaway image, and every mutant runs in a fresh `--rm` container from it, so nothing a run writes (tracked, untracked or ignored, such as `target/`) reaches the next mutant; the image is removed when the job ends, killed or not. The shared registry and sccache volumes and the network are not isolated. A file-level load failure (vitest `FAIL [ ]`, jest `FAIL ` plus `Test suite failed to run`) reads UNVIABLE. Replaces per-agent runmut/mutrun/strykrun scripts. | Soul, Hands (scoped run) | `references/briefs.md` (Hands verification, Soul reruns) | | `tools/testparse.sh` | Sourced library: failing test names and pass/fail/skip counts from cargo, dotnet, vitest, jest and pytest logs, and test files that failed to load (`LOADFAIL`). Shared by the summary and the kill table. | the two scripts above | not named by a brief; it lives and dies with them | | `tools/test-tools.sh` | Local fixture check of the parsers and the summary over `tools/fixtures/logs` (real cargo and mutation logs, plus hand-written dotnet, vitest, jest, pytest, exit-0-but-failed and no-verdict logs), and of the mutation runner's host driver and container half under a mock docker. Run it before merging a change to the scripts above. | whoever changes those scripts | `SKILL.md` (Shared tools) | -| `tools/context-pack.py` | `py -3 tools/context-pack.py [--since ] [--only [,...]] [--spec-json ] [--max-lines ]`. Carries a cut_spec's `file_changes` anchors from the spec's base to the worktree by `git diff` hunks (the working tree included) and prints one header, a status table (SAME, MOVED, TOUCHED, RENAMED, NEW, GONE, OUT_OF_RANGE, UNRESOLVED) and windows of at most 100 lines numbered in worktree lines, within `--max-lines` (800). Exit 3 when an anchor cannot be carried, 4 when the spec is unreadable (fetched by id through the eureka-state binding, retried once on Unavailable; `--spec-json` takes a saved view). `--since ` re-prints only the windows edited since that commit. Standard library plus git; writes nothing. | Hands, Soul, Imagination | the briefs that cut `context-pack-briefs` edits; not yet named | +| `tools/context-pack.py` | `py -3 tools/context-pack.py [--since ] [--only [,...]] [--spec-json ] [--max-lines ]`. Carries a cut_spec's `file_changes` anchors from the spec's base to the worktree by `git diff` hunks (the working tree included) and prints one header, a status table (SAME, MOVED, TOUCHED, RENAMED, NEW, GONE, OUT_OF_RANGE, UNRESOLVED) and windows of at most 100 lines numbered in worktree lines, within `--max-lines` (800). Exit 3 when an anchor cannot be carried, 4 when the spec is unreadable (fetched by id through the eureka-state binding, retried once on Unavailable; `--spec-json` takes a saved view). `--since ` re-prints only the windows edited since that commit. Standard library plus git; writes nothing. | Hands, Soul, Imagination | `references/briefs.md` (Imagination map, Hands, Soul), `SKILL.md` (step 1) | -- 2.47.3 From 40e61f08aea6f3627e0105be75bc4fe9ccde4153 Mon Sep 17 00:00:00 2001 From: Eureka Date: Fri, 9 Oct 2026 14:18:34 +0200 Subject: [PATCH 4/4] Briefs: the --since sentence prints the full runnable command Fixes Soul finding since-sentence-unrunnable: spec id and worktree are required positionals. Co-Authored-By: Claude Opus 5.5 --- references/briefs.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/references/briefs.md b/references/briefs.md index fd3adfa..81a038c 100644 --- a/references/briefs.md +++ b/references/briefs.md @@ -295,8 +295,9 @@ one head (SKILL.md, step 3); keep it fitting: - **Bound every observation.** No command prints more than about 150 lines. Logs go to a file; read `tail -n 60` or `grep -n -m`, and read windows of a file, never the whole of anything over about 300 lines. After editing, - `tools/context-pack.py --since ` reprints only the - changed windows; re-read only files you edited. + `py -3 tools/context-pack.py --since ` reprints only the changed windows; re-read only files you + edited. - **Read the spec by id, not the map.** The cut_spec is bounded and holds only this cut; a worker that reads 900 lines of map to find 60 has spent its budget before it starts. -- 2.47.3