Cut the check suite's comments to contracts, traps and pointers #107

Merged

vnprc merged 3 commits from agent/comments-checks into master

2026-09-22 13:35:40 +01:00

allod-agent commented

2026-09-22 04:31:57 +01:00

Member

The check suite under checks/ loses 235 comment lines and keeps every contract and trap: the 64-line block in consumed-file-carve-out.nix and the 49-line block in dev-forge-opt-out.nix are now the contract each check pins, the traps that made it necessary, and a pointer to the issue; the allod/archetypes#88 story is cited, not retold; every trap that already has its long form in nix.md, testing.md or architecture.md points there. Not one non-comment line moved, and every machine's derivation path is byte-identical to master. Ten checks' derivation paths do move, and only those, for two known reasons: the four shell files under checks/ are copied into the store by path literal, and eleven position words inside the check bodies' own comments were named instead; for each of those ten the witness is the check's own build, and ./check.sh built all nineteen green on this branch. If it is wrong, revert the three commits; no other repository reads these files.

What changed

Comment lines across checks/ (outside fork-fixture/): 1631 to 1396. Position words in comment lines: 79 to 0; history phrasing: 22 to 0 (the one remaining "no longer" in pi-provider-lifecycle/run.sh is ordinary English about a live owner, not a history note). Of the 96 ledger entries, each names the wrong edit the block was preventing and what prevents it now.
The longest blocks: consumed-file-carve-out.nix:103 64 lines to 10, dev-forge-opt-out.nix:164 49 to 20, each keeping the trap and citing allod/archetypes#21 and #88. agent-vm-status.nix's six-space indentation is kept as a one-sentence trap.
Comments that retold testing.md (derivation-name shadowing, one sabotage fixture per validator, a real machine in a fixture) or nix.md (per-check evaluation memory, tryEval versus abort, indented-string dedenting) are one line plus the topic file's name. No README change was needed: every long block landed on a forge-issue pointer instead.
Second commit: eleven one-line edits inside Nix indented strings, in eight check bodies, replacing "above"/"below" with the binding or assertion meant. Every changed line is a # comment inside the string; the diff hunks are in the ledger's report.
Third commit, from the review round: the compressed carve-out sentence in host-user-credentials.nix regained "every dev machine", since consumed-file-carve-out sweeps dev machines only; "those three" in public-host.nix's header and "the remaining comparisons" in static-site.nix name their evaluations and comparisons.
The rule these edits apply is the "Code comments" section in writing.md (allod/memory#63). Assertion and error message strings that point by position are a code change and are tracked as allod/archetypes#106.

Risk

R1. Comment-only: the gate diffs the Nix parse tree (nix-instantiate --parse, which drops comments) and comment-stripped shell text against master and reports zero non-comment changes for the first commit; for the in-string commit, the diff filtered to changed non-comment lines is empty and every file parses. No machine's derivation moves. The ten checks whose derivation moves were rebuilt from scratch by ./check.sh and passed. The residual risk is a compressed trap that a reader no longer notices; the cold review asked that question per block, found three, and all three are fixed. Rollback is a straight revert.

Validation

Comment-only gate on the first commit: non-comment lines changed: 0 (files checked: 20). Second commit: git diff | grep -E '^[+-][^+-]' | grep -vE '^[+-]\s*#' is empty across 8 files, 11 insertions, 11 deletions; all eight parse. Third commit: gate against the second commit reports zero for the three files.
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 four machines, vmFacts, lib and nixosModules identical. Exactly ten checks differ, on both data sets: credential-store-url-parity, dev-forge-opt-out, host-user-credentials, memory-traces, pi-integration, pi-provider-lifecycle, site-content, ssh-settings, static-site, vm-facts-coherence. The other nine are identical.
./check.sh on this branch: All 32 steps passed (checks: 19 built).
./fork-safety.sh was not run: it is the lock-bump pin witness, and the fork-side derivations move for the same ten checks for the same comment-only reasons.
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: three findings (one compressed sentence that overstated a sweep's coverage, two pointers by position), all confirmed against the source and fixed in the third commit. The transcript shows the diff and ledger reads.

Closes allod/archetypes#101

The check suite under `checks/` loses 235 comment lines and keeps every contract and trap: the 64-line block in `consumed-file-carve-out.nix` and the 49-line block in `dev-forge-opt-out.nix` are now the contract each check pins, the traps that made it necessary, and a pointer to the issue; the allod/archetypes#88 story is cited, not retold; every trap that already has its long form in `nix.md`, `testing.md` or `architecture.md` points there. Not one non-comment line moved, and every machine's derivation path is byte-identical to master. Ten checks' derivation paths do move, and only those, for two known reasons: the four shell files under `checks/` are copied into the store by path literal, and eleven position words inside the check bodies' own comments were named instead; for each of those ten the witness is the check's own build, and `./check.sh` built all nineteen green on this branch. If it is wrong, revert the three commits; no other repository reads these files. ## What changed - Comment lines across `checks/` (outside `fork-fixture/`): 1631 to 1396. Position words in comment lines: 79 to 0; history phrasing: 22 to 0 (the one remaining "no longer" in `pi-provider-lifecycle/run.sh` is ordinary English about a live owner, not a history note). Of the 96 ledger entries, each names the wrong edit the block was preventing and what prevents it now. - The longest blocks: `consumed-file-carve-out.nix:103` 64 lines to 10, `dev-forge-opt-out.nix:164` 49 to 20, each keeping the trap and citing allod/archetypes#21 and #88. `agent-vm-status.nix`'s six-space indentation is kept as a one-sentence trap. - Comments that retold `testing.md` (derivation-name shadowing, one sabotage fixture per validator, a real machine in a fixture) or `nix.md` (per-check evaluation memory, `tryEval` versus `abort`, indented-string dedenting) are one line plus the topic file's name. No README change was needed: every long block landed on a forge-issue pointer instead. - Second commit: eleven one-line edits inside Nix indented strings, in eight check bodies, replacing "above"/"below" with the binding or assertion meant. Every changed line is a `#` comment inside the string; the diff hunks are in the ledger's report. - Third commit, from the review round: the compressed carve-out sentence in `host-user-credentials.nix` regained "every dev machine", since `consumed-file-carve-out` sweeps dev machines only; "those three" in `public-host.nix`'s header and "the remaining comparisons" in `static-site.nix` name their evaluations and comparisons. - The rule these edits apply is the "Code comments" section in `writing.md` (allod/memory#63). Assertion and error message strings that point by position are a code change and are tracked as allod/archetypes#106. ## Risk R1. Comment-only: the gate diffs the Nix parse tree (`nix-instantiate --parse`, which drops comments) and comment-stripped shell text against master and reports zero non-comment changes for the first commit; for the in-string commit, the diff filtered to changed non-comment lines is empty and every file parses. No machine's derivation moves. The ten checks whose derivation moves were rebuilt from scratch by `./check.sh` and passed. The residual risk is a compressed trap that a reader no longer notices; the cold review asked that question per block, found three, and all three are fixed. Rollback is a straight revert. ## Validation - Comment-only gate on the first commit: `non-comment lines changed: 0 (files checked: 20)`. Second commit: `git diff | grep -E '^[+-][^+-]' | grep -vE '^[+-]\s*#'` is empty across 8 files, 11 insertions, 11 deletions; all eight parse. Third commit: gate against the second commit reports zero for the three files. - 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 four machines, `vmFacts`, `lib` and `nixosModules` identical. Exactly ten checks differ, on both data sets: `credential-store-url-parity`, `dev-forge-opt-out`, `host-user-credentials`, `memory-traces`, `pi-integration`, `pi-provider-lifecycle`, `site-content`, `ssh-settings`, `static-site`, `vm-facts-coherence`. The other nine are identical. - `./check.sh` on this branch: `All 32 steps passed (checks: 19 built).` - `./fork-safety.sh` was not run: it is the lock-bump pin witness, and the fork-side derivations move for the same ten checks for the same comment-only reasons. - 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: three findings (one compressed sentence that overstated a sweep's coverage, two pointers by position), all confirmed against the source and fixed in the third commit. The transcript shows the diff and ledger reads. Closes allod/archetypes#101

allod-agent added 3 commits

2026-09-22 04:31:57 +01:00

Cut checks/ comments to contracts, traps and pointers 254002c8c9

Compresses the comment blocks under checks/ to a contract, a trap or a
pointer per writing.md's Code comments rule. The two longest blocks, the
retention-rule essay in consumed-file-carve-out.nix and the composed-machine
sweep rationale in dev-forge-opt-out.nix, keep every trap they were carrying
and cite allod/archetypes#21 and #88 for the long version. Thirteen retellings
of the fork-safety story shrink to one sentence plus allod/archetypes#88, and
the site-content rule deletions point at allod/archetypes#62.

Position words are replaced with the names of the bindings, fixtures, files
and checks they pointed at: 79 "above"/"below" comment lines become 10, all of
them inside Nix indented strings, which are part of a derivation and left
alone. History phrasing drops from 22 comment lines to 2.

No non-comment line changes: the Nix parse trees and comment-stripped shell
text are identical to master for all 20 files.

Refs allod/archetypes#101

Name the thing, not its position, inside the check bodies 9e4099b683

Eleven comments inside Nix indented strings still pointed at a sibling by
position. Each becomes the name of the binding or assertion it meant, one
line per edit and nothing else inside the string changed. These are the
pointers listed as left alone in the first pass; taking them changes each
check's derivation path, so the check's own build is the witness.

  checks/credential-store-url-parity.nix:18  credential-store-url-parity-check
  checks/dev-forge-opt-out.nix:233           dev-forge-opt-out-check
  checks/host-user-credentials.nix:277       host-user-credentials-check
  checks/memory-traces.nix:51                memory-traces-timer-check
  checks/pi-integration.nix:159              pi-integration-check
  checks/ssh-settings.nix:396                ssh-settings-check
  checks/ssh-settings.nix:454                ssh-settings-check
  checks/static-site.nix:214                 static-site-first-boot
  checks/vm-facts-coherence.nix:81           vm-facts-coherence-check
  checks/vm-facts-coherence.nix:91           vm-facts-coherence-check
  checks/vm-facts-coherence.nix:111          vm-facts-coherence-check

Every changed line is a shell or Python comment line inside the string; the
diff against the previous commit touches nothing else.

Refs allod/archetypes#101

Review round: name the swept set, the evaluations and the comparisons a645cd3088

Three cold-review findings, all outside indented strings, so no derivation
moves.

checks/host-user-credentials.nix: the compression dropped "every dev machine"
and left the sentence claiming a hypervisor's ciphertext is swept for a
retained source root. consumed-file-carve-out's ageSecretRetentionErrors maps
over devMachineNames and nothing else, so the sentence now says which set is
swept and that no check covers a hypervisor's.

checks/public-host.nix: "those three" in the cost paragraph pointed by
position; it names bare, composed and adminPortCollision.

checks/static-site.nix: "The remaining comparisons" pointed by position; it
names the property the comparisons share — firewall, sshd, fail2ban and Caddy
are machine-wide and publicHost's, not what staticSite contributes — so the
sentence stays true if one of them moves.

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