Cut the wrapper scripts' comments to contracts, traps and pointers #102

Merged

vnprc merged 1 commit from agent/comments-wrappers into master

2026-09-22 13:31:33 +01:00

allod-agent commented

2026-09-22 04:12:33 +01:00

Member

The four gate scripts (check.sh, check-selftest.sh, fork-safety.sh, fork-safety-selftest.sh) lose 74 comment lines and keep every contract and trap: each head now states what the script does and refuses, names the traps in one sentence each, and points at the README, nix.md, testing.md or shell.md for the reasoning instead of retelling it. Nothing a machine builds changes: not one non-comment line moved, and every machine's and every check's derivation path is byte-identical to master. What proves it is the comment-only gate, the derivation-path comparison, ./check.sh green, and both selftests green on this branch. If it is wrong, revert the one commit; no other repository reads these files.

What changed

Comment lines: check.sh 98 to 80, check-selftest.sh 81 to 56, fork-safety.sh 88 to 77, fork-safety-selftest.sh 78 to 58. Fourteen blocks of three or more lines were compressed, none deleted outright: every block in these files carried a contract or a trap.
The two selftest heads keep their fixture lists as the contract, one line per fixture.
fork-safety.sh's head keeps the fork-safe contract in one sentence and the traps (path: versus the git fetcher, path: on the repository root, one nix process per check, set -e and inverted commands) as one sentence each, pointing at nix.md, testing.md and shell.md, which already hold the long form. The allod/archetypes#88 story is cited, not retold.
No position words remain in any comment; the two grep hits for "above"/"used to" are inside runtime message strings, which are not comments and were not touched.
The rule these edits apply is the "Code comments" section landing in writing.md (allod/memory#63).

Per-block accounting (what wrong edit each compressed block was preventing, and what prevents it now) was the input to the cold review below.

Risk

R1. Comment-only: the parse-tree and comment-stripped-shell gate shows zero non-comment lines changed, and the four scripts are not part of any derivation, so no machine or check output moves. The residual risk is a compressed trap that a reader no longer notices; the cold review asked that question per block and found nothing. Rollback is a straight revert.

Validation

Comment-only gate (Nix parse tree via nix-instantiate --parse and comment-stripped shell text diffed against master, bash -n on every script): non-comment lines changed: 0 (files checked: 4).
Derivation paths captured one nix process per item on master and on this branch: 4 machines, 19 checks on template data, 19 checks on the fork fixtures, plus vmFacts, lib and nixosModules. All identical.
./check.sh on this branch: All 32 steps passed (checks: 19 built).
./check-selftest.sh: PASS. ./fork-safety-selftest.sh: PASS.
One cold cross-family review of the diff (gpt-5.6-terra on codex, high effort), asked per deleted or compressed block what wrong edit it prevented and what prevents it now, with every new pointer verified against the README and the memory topic files: FINDINGS: 0, after reading all four files and 17 ledger entries (the transcript shows the reads; an empty review was ruled out before it was read as approval).

Refs allod/archetypes#101

The four gate scripts (`check.sh`, `check-selftest.sh`, `fork-safety.sh`, `fork-safety-selftest.sh`) lose 74 comment lines and keep every contract and trap: each head now states what the script does and refuses, names the traps in one sentence each, and points at the README, `nix.md`, `testing.md` or `shell.md` for the reasoning instead of retelling it. Nothing a machine builds changes: not one non-comment line moved, and every machine's and every check's derivation path is byte-identical to master. What proves it is the comment-only gate, the derivation-path comparison, `./check.sh` green, and both selftests green on this branch. If it is wrong, revert the one commit; no other repository reads these files. ## What changed - Comment lines: `check.sh` 98 to 80, `check-selftest.sh` 81 to 56, `fork-safety.sh` 88 to 77, `fork-safety-selftest.sh` 78 to 58. Fourteen blocks of three or more lines were compressed, none deleted outright: every block in these files carried a contract or a trap. - The two selftest heads keep their fixture lists as the contract, one line per fixture. - `fork-safety.sh`'s head keeps the fork-safe contract in one sentence and the traps (`path:` versus the git fetcher, `path:` on the repository root, one `nix` process per check, `set -e` and inverted commands) as one sentence each, pointing at `nix.md`, `testing.md` and `shell.md`, which already hold the long form. The allod/archetypes#88 story is cited, not retold. - No position words remain in any comment; the two grep hits for "above"/"used to" are inside runtime message strings, which are not comments and were not touched. - The rule these edits apply is the "Code comments" section landing in `writing.md` (allod/memory#63). Per-block accounting (what wrong edit each compressed block was preventing, and what prevents it now) was the input to the cold review below. ## Risk R1. Comment-only: the parse-tree and comment-stripped-shell gate shows zero non-comment lines changed, and the four scripts are not part of any derivation, so no machine or check output moves. The residual risk is a compressed trap that a reader no longer notices; the cold review asked that question per block and found nothing. Rollback is a straight revert. ## Validation - Comment-only gate (Nix parse tree via `nix-instantiate --parse` and comment-stripped shell text diffed against master, `bash -n` on every script): `non-comment lines changed: 0 (files checked: 4)`. - Derivation paths captured one `nix` process per item on master and on this branch: 4 machines, 19 checks on template data, 19 checks on the fork fixtures, plus `vmFacts`, `lib` and `nixosModules`. All identical. - `./check.sh` on this branch: `All 32 steps passed (checks: 19 built).` - `./check-selftest.sh`: `PASS`. `./fork-safety-selftest.sh`: `PASS`. - One cold cross-family review of the diff (`gpt-5.6-terra` on codex, high effort), asked per deleted or compressed block what wrong edit it prevented and what prevents it now, with every new pointer verified against the README and the memory topic files: `FINDINGS: 0`, after reading all four files and 17 ledger entries (the transcript shows the reads; an empty review was ruled out before it was read as approval). Refs allod/archetypes#101

allod-agent added 1 commit

2026-09-22 04:12:34 +01:00

Cut wrapper script comments to contracts, traps and pointers 374ebb1b7e

check.sh, check-selftest.sh, fork-safety.sh and fork-safety-selftest.sh
carried narration, history and position-pointing prose alongside their
contracts and traps. This compresses each block to at most one
paragraph, replaces every "above"/"below" with the name of the thing,
and points long-form reasoning at README.md's Common commands and
Fork-safe checks sections, nix.md, testing.md and shell.md instead of
repeating it inline. No non-comment line changes.

Refs allod/archetypes#101

allod-agent referenced this pull request

2026-09-22 04:32:19 +01:00

Cut code comments to contracts, traps and pointers #101