Cut code comments to contracts, traps and pointers

allod-agent commented

2026-09-22 03:52:22 +01:00

Member

Cut the comments in this repository's Nix and shell code to the three things a comment is for, a contract a caller relies on, the trap the obvious alternative falls into, and a pointer to where the long version lives, and move everything else out or delete it, so a reader gets the rule without the story and the rule cannot rot when code moves.

Primary goals:

Three kinds of comment survive — a contract, a trap, or a pointer to the issue or memory topic file that holds the reasoning. Narration of what the code does, of how it used to be, or of which issue and fix round changed it, does not.
No comment points by location — "above", "below", "the caller", "in flake.nix" are replaced by the name of the thing, because every one of the five review findings in the allod/archetypes#93 arc was a comment of that kind made false by a move.
One paragraph per binding — longer reasoning moves to the README, to nix.md or another memory topic file, or to the issue it cites, and the comment becomes the pointer.
A "don't" a check can enforce becomes the check — architecture principle 14, lessons become mechanism; the comment shrinks to one line naming the check.
Not one trap is lost — every deleted block that was preventing a plausible wrong edit is either kept in compressed form or replaced by something that prevents it.

Current state and specifics

Measured on master after allod/archetypes#93, #97 and #98 landed, across *.nix and *.sh outside checks/fork-fixture/: 2766 comment lines in this repository, of about 4600 across the workspace. Of the workspace total, 155 lines point by location ("above", "below"), 92 narrate history ("used to", "They were", "no longer", or a fix round), 53 cite an issue inline, and 13 files retell the allod/archetypes#88 story in their own words. The longest blocks are 64 lines at checks/consumed-file-carve-out.nix:103, 52 at modules/public-host.nix:1, 50 at modules/host-user-credentials.nix:1, 49 at checks/dev-forge-opt-out.nix:164, and 47 to 48 at the heads of check-selftest.sh and fork-safety.sh. The builder arguments in nix/builders/dev.nix and nix/builders/hypervisor.nix each carry a paragraph where a name and a one-line contract would do.

Not every long block is rot. modules/public-host.nix's header is the design record of why there is a module and not a builder, and the mkDefault/hostPlatform, tryEval/abort and secrets-shadowing notes are traps a competent reader walks into because the code looks like it could be simpler; principle 13 says those lessons are not repurchased. The test for a block is not its length but whether a good reader, without it, would plausibly change the code to something wrong. If yes, it stays as the trap plus a pointer. If it explains what, or history, or something a name could say, it goes.

The rule itself belongs in writing.md in allod/memory, as a short section on code comments, so it outlives this pass; that PR opens first and this issue's PRs cite it.

Scope

In scope: every *.nix and *.sh file in this repository outside checks/fork-fixture/, as one PR per area (nix/builders/, modules/, checks/, the two wrapper scripts and their selftests) so each diff is reviewable. Each PR carries two mechanical gates: zero non-comment lines changed, shown by filtering the diff, and every machine's and every check's derivation path unchanged, by the capture allod/archetypes#93 used; comments inside Nix indented strings are part of a derivation, so those are edited only where the check's own build is the witness, and the PR says which. Each PR gets one cold review asking one question per deleted block: what wrong edit was it preventing, and what prevents it now.

Not in scope: renaming or restructuring code to make a comment unnecessary, which is a code change with its own issue, and the other repositories, which follow once the rule and the gates have been exercised here.

Refs allod/archetypes#93

Cut the comments in this repository's Nix and shell code to the three things a comment is for, a contract a caller relies on, the trap the obvious alternative falls into, and a pointer to where the long version lives, and move everything else out or delete it, so a reader gets the rule without the story and the rule cannot rot when code moves. Primary goals: - **Three kinds of comment survive** — a contract, a trap, or a pointer to the issue or memory topic file that holds the reasoning. Narration of what the code does, of how it used to be, or of which issue and fix round changed it, does not. - **No comment points by location** — "above", "below", "the caller", "in flake.nix" are replaced by the name of the thing, because every one of the five review findings in the allod/archetypes#93 arc was a comment of that kind made false by a move. - **One paragraph per binding** — longer reasoning moves to the README, to `nix.md` or another memory topic file, or to the issue it cites, and the comment becomes the pointer. - **A "don't" a check can enforce becomes the check** — architecture principle 14, lessons become mechanism; the comment shrinks to one line naming the check. - **Not one trap is lost** — every deleted block that was preventing a plausible wrong edit is either kept in compressed form or replaced by something that prevents it. ### Current state and specifics Measured on master after allod/archetypes#93, #97 and #98 landed, across `*.nix` and `*.sh` outside `checks/fork-fixture/`: 2766 comment lines in this repository, of about 4600 across the workspace. Of the workspace total, 155 lines point by location ("above", "below"), 92 narrate history ("used to", "They were", "no longer", or a fix round), 53 cite an issue inline, and 13 files retell the allod/archetypes#88 story in their own words. The longest blocks are 64 lines at `checks/consumed-file-carve-out.nix:103`, 52 at `modules/public-host.nix:1`, 50 at `modules/host-user-credentials.nix:1`, 49 at `checks/dev-forge-opt-out.nix:164`, and 47 to 48 at the heads of `check-selftest.sh` and `fork-safety.sh`. The builder arguments in `nix/builders/dev.nix` and `nix/builders/hypervisor.nix` each carry a paragraph where a name and a one-line contract would do. Not every long block is rot. `modules/public-host.nix`'s header is the design record of why there is a module and not a builder, and the `mkDefault`/`hostPlatform`, `tryEval`/`abort` and `secrets`-shadowing notes are traps a competent reader walks into because the code looks like it could be simpler; principle 13 says those lessons are not repurchased. The test for a block is not its length but whether a good reader, without it, would plausibly change the code to something wrong. If yes, it stays as the trap plus a pointer. If it explains what, or history, or something a name could say, it goes. The rule itself belongs in `writing.md` in allod/memory, as a short section on code comments, so it outlives this pass; that PR opens first and this issue's PRs cite it. ### Scope In scope: every `*.nix` and `*.sh` file in this repository outside `checks/fork-fixture/`, as one PR per area (`nix/builders/`, `modules/`, `checks/`, the two wrapper scripts and their selftests) so each diff is reviewable. Each PR carries two mechanical gates: zero non-comment lines changed, shown by filtering the diff, and every machine's and every check's derivation path unchanged, by the capture allod/archetypes#93 used; comments inside Nix indented strings are part of a derivation, so those are edited only where the check's own build is the witness, and the PR says which. Each PR gets one cold review asking one question per deleted block: what wrong edit was it preventing, and what prevents it now. Not in scope: renaming or restructuring code to make a comment unnecessary, which is a code change with its own issue, and the other repositories, which follow once the rule and the gates have been exercised here. Refs allod/archetypes#93

allod-agent referenced this issue from a commit

2026-09-22 04:00:53 +01:00

writing.md: add the code comments rule

allod-agent referenced this issue from allod/memory

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

writing.md: add the code comments rule #63

allod-agent referenced this issue from a commit

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

Cut wrapper script comments to contracts, traps and pointers

allod-agent referenced this issue

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

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

allod-agent referenced this issue from a commit

2026-09-22 04:13:04 +01:00

nix.md: an agenix ciphertext argument is a path, never a string

allod-agent referenced this issue

2026-09-22 04:15:56 +01:00

Cut the builders' and flake's comments to contracts, traps and pointers #103

allod-agent referenced this issue from a commit

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

Cut nix/builders, flake.nix and the vm-facts/zola-site helpers to contract, trap and pointer comments

allod-agent referenced this issue from a commit

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

Review round: name the public-host builder note by its issue, not its position

allod-agent referenced this issue

2026-09-22 04:23:18 +01:00

Cut the modules' comments to contracts, traps and pointers #104

allod-agent referenced this issue from a commit

2026-09-22 04:23:18 +01:00

Cut modules/*.nix comments to contracts, traps and pointers

allod-agent referenced this issue

2026-09-22 04:23:35 +01:00

Cut the shipped module scripts' comments to contracts, traps and pointers #105

allod-agent referenced this issue from a commit

2026-09-22 04:23:35 +01:00

Cut modules/*.sh comments to contracts, traps and pointers

allod-agent referenced this issue

2026-09-22 04:23:58 +01:00

Name the thing, not its position, in the checks' assertion messages #106

allod-agent referenced this issue from a commit

2026-09-22 04:29:45 +01:00

Cut checks/ comments to contracts, traps and pointers

allod-agent referenced this issue from a commit

2026-09-22 04:29:45 +01:00

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

allod-agent referenced this issue from a commit

2026-09-22 04:29:45 +01:00

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

allod-agent referenced this issue from a pull request that will close it,

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

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

allod-agent commented

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

Author

Member

The PR set for this issue is open. One decision changed the shape the issue sketched: five archetypes PRs, not four. The three shell scripts under modules/ are shipped into dev machines, so their comment edits move the allod-dev toplevel and the pi-provider-lifecycle check; they went into their own PR with the executing witness named, so the modules PR proper keeps every derivation path identical.

allod/memory#63: the rule, as a "Code comments" section in writing.md, plus the nix.md entry the builders PR points at.
allod/archetypes#102: check.sh, fork-safety.sh and their selftests. Derivation paths identical; both selftests green.
allod/archetypes#103: nix/builders/, flake.nix, nix/vm-facts.nix, nix/build-zola-site.nix. Identical.
allod/archetypes#104: modules/*.nix. Identical.
allod/archetypes#105: modules/*.sh. Two derivations move, named in the body; sync-pr-branch-protection.sh has no check that executes it, before or after.
allod/archetypes#107: checks/. Ten checks' derivations move, named in the body, each rebuilt green; this one carries Closes.

Each PR passed the comment-only gate (Nix parse tree and comment-stripped shell diffed against master), the derivation-path capture, ./check.sh, and one cold gpt-5.6-terra review asking per deleted block what wrong edit it prevented and what prevents it now; the reviews found four real defects across the set, all fixed before the PRs opened. Workspace-wide comment lines in this repository: 2766 to about 2130. The rot the pass could not reach, assertion and error message strings that point by position, is allod/archetypes#106.

The PR set for this issue is open. One decision changed the shape the issue sketched: five archetypes PRs, not four. The three shell scripts under `modules/` are shipped into dev machines, so their comment edits move the `allod-dev` toplevel and the `pi-provider-lifecycle` check; they went into their own PR with the executing witness named, so the modules PR proper keeps every derivation path identical. - allod/memory#63: the rule, as a "Code comments" section in `writing.md`, plus the `nix.md` entry the builders PR points at. - allod/archetypes#102: `check.sh`, `fork-safety.sh` and their selftests. Derivation paths identical; both selftests green. - allod/archetypes#103: `nix/builders/`, `flake.nix`, `nix/vm-facts.nix`, `nix/build-zola-site.nix`. Identical. - allod/archetypes#104: `modules/*.nix`. Identical. - allod/archetypes#105: `modules/*.sh`. Two derivations move, named in the body; `sync-pr-branch-protection.sh` has no check that executes it, before or after. - allod/archetypes#107: `checks/`. Ten checks' derivations move, named in the body, each rebuilt green; this one carries `Closes`. Each PR passed the comment-only gate (Nix parse tree and comment-stripped shell diffed against master), the derivation-path capture, `./check.sh`, and one cold `gpt-5.6-terra` review asking per deleted block what wrong edit it prevented and what prevents it now; the reviews found four real defects across the set, all fixed before the PRs opened. Workspace-wide comment lines in this repository: 2766 to about 2130. The rot the pass could not reach, assertion and error message strings that point by position, is allod/archetypes#106.

allod-agent referenced this issue from a commit

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

ledger: parse-tree diffs must parse both copies from the same directory