fix(execute): the helper and the executor give red proof no list

Operator decisions 30 and 31 (14.10); review findings 11ee78c5 and d01df508.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Kjell Tore Guttormsen 2026-10-14 12:32:29 +02:00
commit a70f082f6e
Signed by: ktg
SSH key fingerprint: SHA256:JakMjO6FTBBzN0Bhfj9saOoEjaFxlSdYuZQQpM/lF9Q
6 changed files with 224 additions and 43 deletions

View file

@ -27,24 +27,31 @@ and never touch a file the step does not list.
- `start_sha` — the commit the step starts from. Everything you change is read
later as `git diff {start_sha}`, so the diff is your real report.
- `report_path` — where your report goes.
- `mode` — `build` (the step's first helper) or `fix` (a fix round: the
controller's findings to fix are included; fix only those).
- `mode` — `build` (the step's first helper, or, in the round `build (restart)`,
a fresh one after the executor corrected its own red-proof call) or `fix` (a
fix round: the controller's findings to fix are included; fix only those).
- `voyage_root` — the plugin root, for the CLIs below.
## Mode `build`
1. **Test first.** Read the step's `Test first:` and write that test (and only
that test) first. Follow the `Pattern:` file's style when one is named.
In the round `build (restart)` the tree holds what the first helper left
and nothing is reverted: keep one copy of each test case you write (add no
case the test file already holds).
The step's test files are every file on the `Test first:` `File:` line:
the backticked paths that stand right after `File:`, separated only by
commas or spaces; a path in the description after them is not a test file
commas or spaces, and below plan_version 1.9 also each further path after
a note in brackets such as `(new)` or after `and`, `plus` or `+`, as long
as it is clearly a test (the first path that is not ends the list; operator
decision 31); a path in the description after them is not a test file
(every plan_version; operator decision 20, 2026-10-12).
Then register every new file you created so the executor's diff sees it:
`git add --intent-to-add -- <path>` (this stages nothing).
2. **Prove it red before you build.** Run, from the repository root:
`node {voyage_root}/lib/verification/red-proof.mjs --red-only --base {start_sha} --cmd "<the step's Verify command>" --tests <test files as ONE comma-separated argument: a,b> --plan "{plan}" --step {step}`
(`--tests` lists the step's test files. Red proof refuses a list that
differs from the plan's and prints the plan's list as `plan_tests`.)
`node {voyage_root}/lib/verification/red-proof.mjs --red-only --base {start_sha} --cmd "<the step's Verify command>" --plan "{plan}" --step {step}`
(Red proof reads the step's test files from the plan and prints the list
it ran on a `tests:` line; give it no `--tests` (operator decision 30).)
Exit 0 = the test fails at the start point: continue. Exit 1 = the test
already passes at the start point, so it proves nothing: rewrite the test
until it fails for the reason the step exists, and run the check again.
@ -53,10 +60,9 @@ and never touch a file the step does not list.
`Files:` alone decides this, not what you have changed: the behaviour
already exists at the start point, and no test can be red here. Do not rewrite the test and do not build; say so in
the report and stop. The executor sends the step up to the plan.
Exit 2 = it could not run. When its reason starts `tests-mismatch` (the
`--tests` you gave differs from the plan's list), run the gate once more
with `plan_tests` as `--tests`, whatever the plan_version; only a second
exit 2 goes on to the two branches that follow. Exit 2 otherwise (the
Exit 2 = it could not run. When its reason starts `plan-unreadable`, the
plan path or the step number you were given is wrong: do not build; say
so in the report and stop (the executor corrects its call). Exit 2 otherwise (the
Verify command is not one test-runner invocation, or a file is missing):
on `plan_version` ≥ 1.8 do not build; say so in the report and stop.
Below 1.8, write "red proof not run: {reason}" in the report and go on to
@ -68,8 +74,8 @@ and never touch a file the step does not list.
3. **Lock the tests** (when the CLI exists):
`node {voyage_root}/lib/util/test-lock.mjs lock --files <test files> --step {step} --cmd "{Verify command}"`
(the lock stores the step's test command; only that command can later
mark the step green). `--files` is the list red proof accepted: the
`--tests` it ran without `tests-mismatch` (after a rerun, `plan_tests`).
mark the step green). `--files` is the list red proof printed on its
`tests:` line; copy that line into the report.
If the file does not exist, write "not-locked (test-lock.mjs missing)" in the
report. Never silent. Once locked you cannot edit the tests, and that is the
point: the code changes to meet the test, never the reverse.
@ -112,7 +118,7 @@ earlier section kept word for word. Never remove or rewrite what is there.
Use the round label the executor gave you in the heading.
```markdown
## Step {N} - {build | fix round R}
## Step {N} - {build | build (restart) | fix round R}
### Ran
- `{command}` -> exit {code}