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

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 <sha>, 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 <spec id> <worktree
+  at base>`: 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: <repo> <branch> at HEAD <sha>. Check that git status is clean
 first. Pinned siblings: <repo@sha>. Do not change them.
+Before any grep or Read, expand the pack: `py -3 tools/context-pack.py <cut_spec
+id> <worktree>`. 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,14 @@ 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,
+  `py -3 tools/context-pack.py <cut_spec id> <worktree> --since <the HEAD you
+  started from>` 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 +459,8 @@ below. Admit one verdict and its findings, and nothing else.
 
 Scope: <cut_report id>. Rehydrate (recipes: target in force, rulings in force,
 one cut's record for <cut>), 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 <cut_spec id>
+<worktree at the report's head>` 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

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 <file> [ <file> ]`, jest `FAIL <file>` 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 <cut_spec id> <worktree> [--since <sha>] [--only <k>[,<k>...]] [--spec-json <file>] [--max-lines <n>]`. 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 <sha>` 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 <cut_spec id> <worktree> [--since <sha>] [--only <k>[,<k>...]] [--spec-json <file>] [--max-lines <n>]`. 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 <sha>` 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) |