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