allod/memory
Watch
2
0
Fork
You've already forked memory
 0
Code Issues 4 Pull requests Projects Releases Packages Wiki Activity Actions

writing.md: add the code comments rule #63

Merged
vnprc merged 3 commits from agent/code-comments-rule into master 2026-09-22 13:30:30 +01:00
Conversation 1 Commits 3 Files changed 3 +15
allod-agent commented 2026-09-22 04:01:04 +01:00
Member
Copy link

writing.md gains a short "Code comments" section, and nix.md gains the long form of one trap the comment-cutting PRs cite by pointer: a comment in code is a contract, a trap, or a pointer, and everything else moves out or is deleted. Nothing changes for any running machine; this is a memory rule that the comment-cutting PRs in allod/archetypes cite and that outlives them. What proves it is the diff itself, ten lines of prose, and the tracked memory-budget hook passing. If it is wrong, revert the one commit.

What changed

  • nix.md: a new entry, "An agenix ciphertext argument is a path, never a string", the reasoning that nix/builders/dev.nix now cites as (nix.md) instead of carrying inline.

  • A new ## Code comments section in writing.md, placed before "Where this applies", stating the three kinds of comment that survive and five rules: name the thing, never its position; one paragraph per binding; an enforceable "don't" becomes the check (architecture.md principle 14); the test for a block is whether a good reader would plausibly make a wrong edit without it; no trap is lost when comments are cut.

  • The section is the rule allod/archetypes#101 asks for, so it opens first and that issue's PRs cite it.

Risk

R0. Prose only; the memory budget hook (.hooks/memory-budget --worktree) passes, writing.md is 3.9 KB and nix.md 18.3 KB against a 24 KB cap.

Validation

  • .hooks/memory-budget --worktree: exit 0.

Refs allod/archetypes#101

`writing.md` gains a short "Code comments" section, and `nix.md` gains the long form of one trap the comment-cutting PRs cite by pointer: a comment in code is a contract, a trap, or a pointer, and everything else moves out or is deleted. Nothing changes for any running machine; this is a memory rule that the comment-cutting PRs in allod/archetypes cite and that outlives them. What proves it is the diff itself, ten lines of prose, and the tracked memory-budget hook passing. If it is wrong, revert the one commit. ## What changed - `nix.md`: a new entry, "An agenix ciphertext argument is a path, never a string", the reasoning that `nix/builders/dev.nix` now cites as `(nix.md)` instead of carrying inline. - A new `## Code comments` section in `writing.md`, placed before "Where this applies", stating the three kinds of comment that survive and five rules: name the thing, never its position; one paragraph per binding; an enforceable "don't" becomes the check (`architecture.md` principle 14); the test for a block is whether a good reader would plausibly make a wrong edit without it; no trap is lost when comments are cut. - The section is the rule allod/archetypes#101 asks for, so it opens first and that issue's PRs cite it. ## Risk R0. Prose only; the memory budget hook (`.hooks/memory-budget --worktree`) passes, `writing.md` is 3.9 KB and `nix.md` 18.3 KB against a 24 KB cap. ## Validation - `.hooks/memory-budget --worktree`: exit 0. Refs allod/archetypes#101 
A comment is a contract, a trap, or a pointer; everything else moves out or goes. Names, never positions; one paragraph per binding; an enforceable don't becomes the check; no trap is lost.

Refs allod/archetypes#101
The long form of the trap that nix/builders/dev.nix now cites by pointer.

Refs allod/archetypes#101
Refs allod/archetypes#101
vnprc approved these changes 2026-09-22 13:30:24 +01:00
vnprc merged commit 9c41ce8965 into master 2026-09-22 13:30:30 +01:00
vnprc deleted branch agent/code-comments-rule 2026-09-22 13:30:30 +01:00
Sign in to join this conversation.
Reviewers
No reviewers
vnprc
Labels
Clear labels   
blocked
Groom: conflicts with master, based on another open PR, or has unanswered review findings

  
bug
Something is not working

  
decision
Groom: open past 30 days with a yes/no the owner has to answer

  
duplicate
This issue or pull request already exists

  
enhancement
New feature

  
help wanted
Need some help

  
invalid
Something is wrong

  
landed?
Groom: a merged PR or master commit references this, no Closes line; confirm by hand

  
question
More information is needed

  
ready-to-merge
Groom: base is master, merges clean, no unanswered review findings

  
stale
Groom: no comment or commit in 30 days

  
wontfix
This won't be fixed

  
bug
Something is not working

  
duplicate
This issue or pull request already exists

  
enhancement
New feature

  
help wanted
Need some help

  
invalid
Something is wrong

  
question
More information is needed

  
wontfix
This won't be fixed

No labels
blocked
bug
decision
duplicate
enhancement
help wanted
invalid
landed?
question
ready-to-merge
stale
wontfix
bug
duplicate
enhancement
help wanted
invalid
question
wontfix
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
allod/memory!63
No description provided.