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

Merged

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

2026-09-22 13:34:03 +01:00

allod-agent commented

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

Member

The sixteen Nix modules under modules/ lose 148 comment lines and keep every contract and trap: public-host.nix's 52-line design record is 19 lines of contract and traps pointing at the README's Public hosts section, which now carries the design reasoning; host-user-credentials.nix's 50-line head is 21, with the agenix custom-path facts compressed to one sentence pointing at nix.md; every other trap stays as the sentence that names the wrong edit and why it fails. 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. The three shell scripts under modules/ are shipped into machines, so their comments move derivations; they are a separate PR. What proves it is the comment-only gate, the derivation-path comparison, and ./check.sh green on this branch. If it is wrong, revert the one commit; no other repository reads these files.

What changed

Comment lines in modules/*.nix: 370 to 222. ssh-hosts.nix 81 to 49, public-host.nix 62 to 23, host-user-credentials.nix 50 to 21, static-site.nix 31 to 16, rented-kvm-guest.nix 25 to 15, ai-agents.nix 42 to 34, the rest by a few lines each; netrc.nix, home-shared.nix and agent-forgejo-token.nix had none. Blocks of three or more lines: narration, provenance, history and a table of contents deleted; the rest compressed to a contract, trap or pointer; 35 ledger entries were in scope for the cold review.
README ## Public hosts gains one paragraph naming the three things the base deliberately leaves out (boot and disk shape, agenix, the stateful-service layer) and one sentence on why the base no longer tries to be unbypassable, so public-host.nix points there instead of carrying it.
The hostPlatform without mkDefault trap, which lives in rented-kvm-guest.nix, points at nix.md, which holds the rule.
Position words in comments: 17 to 0. The three remaining "above" in modules/ are inside warnEcho runtime strings and mean "earlier in this terminal", so they were left alone.
Comments inside Nix indented strings were not touched. The rule these edits apply is the "Code comments" section in writing.md (allod/memory#63).

Risk

R1. Comment-only: the gate diffs the Nix parse tree (nix-instantiate --parse, which drops comments) against master and reports zero non-comment changes, and the derivation-path witness covers every machine and every check on both data sets. 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: non-comment lines changed: 0 (files checked: 13); README.md is the only other file changed.
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).
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 13 changed files, the README and 35 ledger entries (the transcript shows the reads; an empty review was ruled out before it was read as approval).

Refs allod/archetypes#101

The sixteen Nix modules under `modules/` lose 148 comment lines and keep every contract and trap: `public-host.nix`'s 52-line design record is 19 lines of contract and traps pointing at the README's Public hosts section, which now carries the design reasoning; `host-user-credentials.nix`'s 50-line head is 21, with the agenix custom-path facts compressed to one sentence pointing at `nix.md`; every other trap stays as the sentence that names the wrong edit and why it fails. 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. The three shell scripts under `modules/` are shipped into machines, so their comments move derivations; they are a separate PR. What proves it is the comment-only gate, the derivation-path comparison, and `./check.sh` green on this branch. If it is wrong, revert the one commit; no other repository reads these files. ## What changed - Comment lines in `modules/*.nix`: 370 to 222. `ssh-hosts.nix` 81 to 49, `public-host.nix` 62 to 23, `host-user-credentials.nix` 50 to 21, `static-site.nix` 31 to 16, `rented-kvm-guest.nix` 25 to 15, `ai-agents.nix` 42 to 34, the rest by a few lines each; `netrc.nix`, `home-shared.nix` and `agent-forgejo-token.nix` had none. Blocks of three or more lines: narration, provenance, history and a table of contents deleted; the rest compressed to a contract, trap or pointer; 35 ledger entries were in scope for the cold review. - README `## Public hosts` gains one paragraph naming the three things the base deliberately leaves out (boot and disk shape, agenix, the stateful-service layer) and one sentence on why the base no longer tries to be unbypassable, so `public-host.nix` points there instead of carrying it. - The `hostPlatform` without `mkDefault` trap, which lives in `rented-kvm-guest.nix`, points at `nix.md`, which holds the rule. - Position words in comments: 17 to 0. The three remaining "above" in `modules/` are inside `warnEcho` runtime strings and mean "earlier in this terminal", so they were left alone. - Comments inside Nix indented strings were not touched. The rule these edits apply is the "Code comments" section in `writing.md` (allod/memory#63). ## Risk R1. Comment-only: the gate diffs the Nix parse tree (`nix-instantiate --parse`, which drops comments) against master and reports zero non-comment changes, and the derivation-path witness covers every machine and every check on both data sets. 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: `non-comment lines changed: 0 (files checked: 13)`; README.md is the only other file changed. - 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).` - 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 13 changed files, the README and 35 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:23:18 +01:00

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

Apply the writing.md "Code comments" rule across every modules/*.nix file: a
comment survives only as a contract a caller relies on, the trap the obvious
alternative falls into, or a pointer to where the long version lives.
Narration, provenance and fix-round history go; every position word ("above",
"below", "this file") is replaced by the name of the function, option, module
or check it meant.

Every block that was preventing a plausible wrong edit is kept in compressed
form or replaced by a pointer:

- public-host.nix's 52-line header keeps the contract (no enable option) and
  the two traps a reader walks into — folding in the boot and disk shape, and
  routing adminAuthorizedKeys through agenix. Its design record was already in
  README.md under Public hosts, which gains the deliberate exclusions and the
  earlier-unbypassable-version sentence.
- host-user-credentials.nix's 50-line header keeps what the module reads and
  writes, and compresses the three agenix custom-path facts to one sentence
  pointing at nix.md, which holds them in full.
- rented-kvm-guest.nix's hostPlatform note points at nix.md for the mkDefault
  shadowing rule.
- ssh-hosts.nix drops the header's table of contents for three refusals that
  each already carry their own trap and their own throw message.

Zero non-comment lines change, so no derivation path moves. Comments inside
Nix indented strings are part of a derivation and are left untouched.

The three modules/*.sh files are a separate commit: their comment text is
inside the script a writeShellApplication builds, so editing them does move
derivation paths.

Refs allod/archetypes#101

allod-agent referenced this pull request

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

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

allod-agent referenced this pull request

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

Cut code comments to contracts, traps and pointers #101