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

Merged

vnprc merged 1 commit from agent/comments-module-scripts into master

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

allod-agent commented

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

Member

The three shell scripts under modules/ that are shipped into dev machines (pi-provider-reconcile.sh, pi-provider-token-select.sh, sync-pr-branch-protection.sh) lose 13 comment lines and keep every contract and trap; not one non-comment line moves. Because the script text is copied into the store, this does move one machine's toplevel derivation (allod-dev, the only dev machine on the template data) and the pi-provider-lifecycle check on both data sets, and nothing else; that is why these three files are a PR of their own rather than part of allod/archetypes#104. What proves it is the comment-only gate, the derivation-path comparison showing exactly those three moves, and ./check.sh green on this branch, which builds and runs the pi-provider-lifecycle check that executes the two Pi scripts through every reconcile and token-select path. The third script has no check that executes it, before or after this change; its witnesses are bash -n and the build. If it is wrong, revert the one commit.

What changed

Comment lines: pi-provider-reconcile.sh 73 to 64, pi-provider-token-select.sh 14 to 14 (a compressed block and a reshaped usage: header cancel out), sync-pr-branch-protection.sh 12 to 8. Ten ledger entries were in scope for the cold review.
Which check witnesses each script: pi-provider-reconcile.sh and pi-provider-token-select.sh are built as writeShellApplication packages by checks/pi-provider-lifecycle.nix and executed by checks/pi-provider-lifecycle/run.sh across the empty-set, missing-secret, concurrent-writer, rollback and legacy-retirement paths, and the token and credential selection modes. sync-pr-branch-protection.sh is a home.file source in modules/agent-hooks.nix; consumed-file-carve-out observes its store path but nothing under checks/ executes it.
The rule these edits apply is the "Code comments" section in writing.md (allod/memory#63).

Risk

R1. Comment-only in shell text, shown by the comment-stripped diff against master and bash -n; the derivation-path capture moves for exactly the one machine and one check that carry the scripts, and that check's build and run are green. The residual risk is a compressed trap in sync-pr-branch-protection.sh that a reader no longer notices, and that script has no executing witness; the cold review asked the per-block question and found nothing. Rollback is a straight revert.

Validation

Comment-only gate: non-comment lines changed: 0 (files checked: 3).
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. Three lines differ: the allod-dev toplevel, and the pi-provider-lifecycle check on template data and on the fork fixtures. All 42 other lines 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: FINDINGS: 0, after reading the three scripts, modules/agent-hooks.nix, the README and 10 ledger entries (the transcript shows the reads; an empty review was ruled out before it was read as approval).

Refs allod/archetypes#101

The three shell scripts under `modules/` that are shipped into dev machines (`pi-provider-reconcile.sh`, `pi-provider-token-select.sh`, `sync-pr-branch-protection.sh`) lose 13 comment lines and keep every contract and trap; not one non-comment line moves. Because the script text is copied into the store, this does move one machine's toplevel derivation (`allod-dev`, the only dev machine on the template data) and the `pi-provider-lifecycle` check on both data sets, and nothing else; that is why these three files are a PR of their own rather than part of allod/archetypes#104. What proves it is the comment-only gate, the derivation-path comparison showing exactly those three moves, and `./check.sh` green on this branch, which builds and runs the `pi-provider-lifecycle` check that executes the two Pi scripts through every reconcile and token-select path. The third script has no check that executes it, before or after this change; its witnesses are `bash -n` and the build. If it is wrong, revert the one commit. ## What changed - Comment lines: `pi-provider-reconcile.sh` 73 to 64, `pi-provider-token-select.sh` 14 to 14 (a compressed block and a reshaped `usage:` header cancel out), `sync-pr-branch-protection.sh` 12 to 8. Ten ledger entries were in scope for the cold review. - Which check witnesses each script: `pi-provider-reconcile.sh` and `pi-provider-token-select.sh` are built as `writeShellApplication` packages by `checks/pi-provider-lifecycle.nix` and executed by `checks/pi-provider-lifecycle/run.sh` across the empty-set, missing-secret, concurrent-writer, rollback and legacy-retirement paths, and the token and credential selection modes. `sync-pr-branch-protection.sh` is a `home.file` source in `modules/agent-hooks.nix`; `consumed-file-carve-out` observes its store path but nothing under `checks/` executes it. - The rule these edits apply is the "Code comments" section in `writing.md` (allod/memory#63). ## Risk R1. Comment-only in shell text, shown by the comment-stripped diff against master and `bash -n`; the derivation-path capture moves for exactly the one machine and one check that carry the scripts, and that check's build and run are green. The residual risk is a compressed trap in `sync-pr-branch-protection.sh` that a reader no longer notices, and that script has no executing witness; the cold review asked the per-block question and found nothing. Rollback is a straight revert. ## Validation - Comment-only gate: `non-comment lines changed: 0 (files checked: 3)`. - 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`. Three lines differ: the `allod-dev` toplevel, and the `pi-provider-lifecycle` check on template data and on the fork fixtures. All 42 other lines 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: `FINDINGS: 0`, after reading the three scripts, `modules/agent-hooks.nix`, the README and 10 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:35 +01:00

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

Same rule as the preceding modules/*.nix commit, applied to the three shell
scripts under modules/. These are separate because their comment text is part
of the script a writeShellApplication or a home.file ships, so every one of
these edits moves a derivation path and, through it, every dev VM's toplevel.

The witness for each script, so the moved paths can be read against something
that actually runs the changed text:

- pi-provider-reconcile.sh — checks/pi-provider-lifecycle.nix builds it as the
  pi-provider-reconcile writeShellApplication and passes three variants
  (ALL_RECONCILE, PARTIAL_RECONCILE, EMPTY_RECONCILE, plus the ambiguous and
  dual fixtures) into pi-provider-lifecycle-check, whose body
  checks/pi-provider-lifecycle/run.sh executes as
  $ALL_RECONCILE/bin/pi-provider-reconcile and friends across the empty-set,
  missing-secret, concurrent-writer, rollback and legacy-retirement paths. An
  executing witness: the check runs the script, not a grep of it.

- pi-provider-token-select.sh — the same check. run.sh executes the built
  selector directly in both modes: token mode against known, unknown and
  unmanaged credentials, and credential mode across the remembered-name,
  deployment-default, sole-delivered-token and ambiguous cases. Also an
  executing witness.

- sync-pr-branch-protection.sh — nothing under checks/ builds or executes it.
  checks/consumed-file-carve-out.nix sweeps every dev machine's enabled
  home.file sources, which includes .config/git/sync-pr-branch-protection.sh,
  and forces its store path through toString, so the check's evaluation does
  observe the new path — but it only asserts the path retains no source root.
  checks/agent-vm-status.nix names syncPrBranchProtection once, in a comment
  about activation DAG ordering. The script's behavior has no check witness
  either before or after this change.

Zero non-comment lines change; bash -n passes on all three.

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