Tidy source comments

bench/run.sh

@@ -19,7 +19,7 @@ ISSUES="${ISSUES:-20 21 22 23}"
 HARNESSES="${HARNESSES:-codeaf pi opencode}"
 
 # Wall-clock cap per cell. A harness that has not produced a diff by here is
-# recorded as DNF rather than left to spend: opencode hit this on issue #22 and
+# recorded as DNF rather than left running indefinitely. A stalled process
 # kept spending after the diff never arrived.
 CELL_TIMEOUT="${CELL_TIMEOUT:-40m}"
 
@@ -31,7 +31,7 @@ CELL_TIMEOUT="${CELL_TIMEOUT:-40m}"
 # (2026-08-02, merge of PR #18): the last commit with all four issues open.
 BASE_COMMIT="${BASE_COMMIT:-}"
 
-# codeaf shape. Four values, against the same recorded pi and opencode rows:
+# codeaf shape. Four values use the same recorded comparison rows:
 #
 #   node     one leaf, one graph. The executor measured alone, and the drift
 #            control: byte for byte the invocation the recorded codeaf numbers
@@ -61,7 +61,7 @@ case "${1:-}" in
   --dry-run) BENCH_DRY_RUN=1 ;;
 esac
 
-# pi and opencode flags move between versions. These are the invocations the
+# External harness flags move between versions. These are the invocations the
 # recorded runs used; check them against your installed version before
 # concluding anything from a zero-file result.
 PI_BIN="${PI_BIN:-pi}"
@@ -296,8 +296,8 @@ run_harness() {
 }
 
 # harness_cost reads the run's own accounting. For codeaf that is the $ figure
-# on the run summary line, which every graph shape ends with. For pi and
-# opencode there is nothing to read, and the account-level delta is not a
+# on the run summary line, which every graph shape ends with. Other harnesses
+# provide no summary value, and the account-level delta is not a
 # substitute — see bench/README.md.
 harness_cost() {
   local harness="$1" log="$2" cell="${3:-}"

cmd/codeaf-census/main.go

@@ -7,7 +7,7 @@
 // committed instrument every one of those numbers is an argument about
 // anecdotes. The first census was a
 // throwaway pass over the same file; this is that pass, committed, tested on a
-// fixture, and runnable nightly by a cron on the Spark (`make census`).
+// fixture, and runnable nightly by a cron in a test run (`make census`).
 //
 // It is a developer's binary and never a verb on codeaf, for the reason
 // cmd/codeaf-changes and cmd/codeaf-demo-home are: the shipped binary is on a

cmd/codeaf-demo-home/main.go

@@ -4,16 +4,12 @@ package main
 // something on every one of v3's places, so the surface can be looked at full
 // rather than empty.
 //
-// WHY IT IS NOT A FIXTURE FOR TESTS AND NOT A SEED FOR A REAL MACHINE. The
-// owner opened the standing page, the memory page and the spend page on their
-// own machine and saw nothing, because on their machine those stores are new
-// and empty — which is the emptiness law working exactly as designed. The
-// answer is not to write invented automations, invented memories and invented
-// spending into ~/.codeaf, which would make a person's own record a lie; it is
-// a SECOND home, somewhere else, that the surface can be pointed at.
-// So this program never touches the real state root: it writes one directory,
-// the one it was given, and the launcher hands that directory to the binary as
-// HOME.
+// WHY IT IS NOT A FIXTURE FOR TESTS AND NOT A SEED FOR A REAL MACHINE. The answer is not
+// to write invented automations, invented memories and invented spending into ~/.codeaf,
+// which would make a person's own record a lie; it is a SECOND home, somewhere else, that
+// the surface can be pointed at. So this program never touches the real state root: it
+// writes one directory, the one it was given, and the launcher hands that directory to the
+// binary as HOME.
 //
 // WHY IT IS A SEPARATE BINARY. cmd/codeaf has a clean place for a hidden verb —
 // `engine` and `tick` both live there — but the seeding below is several hundred

cmd/codeaf/chatv3.go

@@ -1426,7 +1426,7 @@ func v3Connections(manager *connect.Manager) tui3.Connections {
 // since two writers on one journal is a corrupted journal.
 //
 // SILENTLY STARTING A NEW CONVERSATION IS DEAD, and killing it is the point of
-// this lane. This door used to mint a sibling session and say "session open
+// this implementation. This door used to mint a sibling session and say "session open
 // elsewhere — started a new one", which sounds like an explanation and is
 // actually the defect: the conversation the person came back for was still
 // running a few inches away, in another terminal or in this workspace's session

cmd/codeaf/chatv3_exchange.go

@@ -7,7 +7,7 @@ package main
 //
 // ───────────────────────────────────────────────────────────────────────────
 // MERGE NOTE (lane errand). Everything in this file is new, and the only line
-// this lane added outside it is the `Errand:` / `ErrandsRoot:` pair in
+// this implementation added outside it is the `Errand:` / `ErrandsRoot:` pair in
 // chatv3.go's tui3.Options literal. If that literal has moved under another
 // lane, the pair is the whole of what has to be carried across.
 // ───────────────────────────────────────────────────────────────────────────

cmd/codeaf/chatv3_layout.go

@@ -12,7 +12,7 @@ package main
 //   - WHICH PROJECT. The workspace is the git root of the directory the person
 //     stood in, so `codeaf` typed in repo/cmd and in repo/ is the same project.
 //     The encoded directory name is a bucket and not an identity — meta.json
-//     carries the real path — which is what lets the encoding stay dumb.
+//     carries the real path — which is what lets the encoding stay simple.
 //   - BORROWED OR OWNED. A conversation opened inside a project borrows it and
 //     litters nothing; one opened nowhere at all owns a workspace of its own.
 //   - WHICH CONVERSATION. The newest one the PERSON spoke in, or a fresh

cmd/codeaf/chatv3_process_test.go

@@ -149,7 +149,7 @@ type gateOnly struct {
 	recordingGate
 }
 
-// THE BUG THIS LANE FIXES, at the door's end.
+// THE BUG this test FIXES, at the door's end.
 //
 // The three approval seams used to be minted once, at boot, around the boot
 // agent, and the surface went on holding them through every /new and every

cmd/codeaf/chatv3_session_test.go

@@ -12,7 +12,7 @@ import (
 
 // A second window in the same directory resumes the same transcript, which the
 // first one is holding open. It used to be handed a NEW conversation and one
-// sentence about it, which is the defect this lane ends: the chat the person
+// sentence about it, which is the defect this test ends: the chat the person
 // came back for was still running, and nothing led them to it. Now it is a
 // refusal that says where the conversation is and what lets go of it.
 func TestASecondWindowOnALockedSessionIsRefusedAndNamesTheWayOut(t *testing.T) {

cmd/codeaf/do.go

@@ -2935,7 +2935,7 @@ func (w *settlementWatch) checklistFor(nodeID string, wrote []string) (rows []re
 // is empty - contains no implementation" over exit 0 for want of the Unclosed
 // field, and another produced no file at all and reported settled, done, success
 // under a note explaining that the review had overreached
-// (2026-08-28, meta/muse-spark-1.1). Exit 2, partial, is the honest code for a
+// (2026-08-28, a model response). Exit 2, partial, is the honest code for a
 // job that delivered less than it promised.
 //
 // THE READING IS store.DeliveryGate.Whole AND IT IS NOT REPEATED HERE. This

cmd/codeaf/do_machine_gate_test.go

@@ -61,12 +61,11 @@ func TestDoRunHonoursProfileMachineFloor(t *testing.T) {
 	}
 }
 
-// THE CONTRACT, from the owner's ruling on #1410 (2026-09-24): when `codeaf do`
-// is held by the machine, the person sees why on stderr, once, in the rail's
-// own words and naming the limit that held it; and a run whose --timeout
-// arrives before anything started says, in its --json stop, that the machine
-// held it. Before this, a held run waited in silence and ended `deadline` with
-// nothing to say why nothing had happened.
+// THE CONTRACT, from on #1410 (2026-09-24): when `codeaf do` is held by the machine, the
+// person sees why on stderr, once, in the rail's own words and naming the limit that held
+// it; and a run whose --timeout arrives before anything started says, in its --json stop,
+// that the machine held it. Before this, a held run waited in silence and ended `deadline`
+// with nothing to say why nothing had happened.
 func TestDoHeldByTheMachineSaysWhyOnStderrAndInItsStop(t *testing.T) {
 	if _, err := os.Stat("/proc/meminfo"); err != nil {
 		t.Skip("host has no proc memory reading")

cmd/codeaf/engine.go

@@ -990,7 +990,7 @@ func runEngineHost(workspaceFlag, sessionFlag string) error {
 //
 // A NAMED SESSION IS SPELLED THE WAY THE BOOT WILL SPELL IT, through the same
 // [engineSessionPath] every other door reads a --session with, so two surfaces
-// that named one file two ways ("~/x", "/home/you/x") are asking for one
+// that named one file two ways ("~/x", "/workspace/x") are asking for one
 // conversation rather than two.
 func engineHelloKey(hello remote.Hello, workspaceFlag, sessionFlag string) string {
 	if named := firstEngineWord(hello.Session, sessionFlag); named != "" {

cmd/codeaf/plainwords.go

@@ -56,7 +56,7 @@ func plainWords(sentence string) string {
 // A filesystem failure arrives as an [os.PathError] wrapped on every floor it
 // passed on the way up:
 //
-//	open notebook: stat /home/x/.codeaf/graph.db: no such file or directory
+//	open notebook: stat /workspace/.codeaf/graph.db: no such file or directory
 //	create chat workspace: mkdir /nope: permission denied
 //
 // `stat`, `mkdir` and `open` are the names of system calls — a library's words

cmd/codeaf/window.go

@@ -11,7 +11,7 @@ import (
 //
 // IT CARRIES ONE PATH, NOT TWO. It used to keep the store's resolved path
 // beside the spelling a `--db` flag was given in, because the v2 chat door
-// parsed that flag and `~/store.db` and `/home/…/store.db` are different
+// parsed that flag and `~/store.db` and `/workspace/store.db` are different
 // strings for one file. That door is gone (#329), the only caller left resolves
 // the path before it opens anything, and a second field that always held the
 // same value was one more thing to keep in step.

docs/changes/unreleased/1923-source-comments.md

@@ -0,0 +1,7 @@
+---
+kind: changed
+title: Tidy source comments and add a comment style check
+pr: 1923
+surface: [build]
+invalidates: []
+---

internal/calllog/calllog.go

@@ -123,7 +123,7 @@ type Record struct {
 	// 65,536-token ceiling looked identical to an idle process.
 	Phase string `json:"phase,omitempty"`
 	// Tag is what the call was for — "turn", "leaf", "compile", "brief" — set
-	// by whoever made it (provider.WithCallTag). Empty for a call this lane did
+	// by whoever made it (provider.WithCallTag). Empty for a call this implementation did
 	// not locate, which is honest: an untagged row is still a row.
 	Tag string `json:"tag,omitempty"`
 	// Node is the work the call belongs to, where the caller knows one: a plan

internal/cellstore/guard_test.go

@@ -169,8 +169,8 @@ func TestScopeIsTheNormalizedRemoteElseTheCell(t *testing.T) {
 	}
 }
 
-// TestL3_SecretsNeverEnterTheStore proves that committed history travels sealed,
-// so this fixture commits
+// TestL3_SecretsNeverEnterTheStore checks the working-tree boundary.
+// Committed history travels sealed, so this fixture commits
 // only non-secret files. The secrets remain untracked rather than ignored to
 // prove the guard, independently of Git's ignore rules. After two seals no
 // store object holds the key, and the next tool call still gets the .env value.

internal/cellstore/rebuild.go

@@ -47,8 +47,7 @@ func (s Screened) paths() []string {
 }
 
 // leftOut is the install folders this seal leaves out because a lockfile that
-// travels rebuilds them. It is the rule of docs/STAGE-1-CONTRACTS.md section
-// 19.4, and each folder that fails any test of it travels with the seal exactly
+// travels rebuilds them. Each folder that fails any test of it travels with the seal exactly
 // as before, so being wrong costs the bytes the seal would have carried anyway.
 func (g Guard) leftOut(tree string, changed, locks []string, policy policyFile) Screened {
 	personal := policy

internal/cellstore/withheld.go

@@ -17,7 +17,7 @@ import (
 // lands in the person's folder; a cell that seals its own folder uses that
 // folder's file. Below one marker line sit the paths withheld because they
 // carry secrets, and below another the install folders left out because a
-// lockfile that does travel rebuilds them (docs/STAGE-1-CONTRACTS.md section 19).
+// lockfile that does travel rebuilds them.
 // Two more blocks set single paths apart: those this machine cannot read (a file
 // with no permissions, a folder it may not list) and those whose name this
 // machine's file system cannot keep beside another's (written when a chat is

internal/cellsync/liveness.go

@@ -1,7 +1,7 @@
 package cellsync
 
 // Liveness is a watch socket that can vouch for the leases this process holds
-// (STAGE-1-CONTRACTS.md §21.11). While it does, the relay counts the socket's
+// . While it does, the relay counts the socket's
 // pings as the holder's proof of life, so the Batcher need not heartbeat.
 type Liveness interface {
 	// Keep names the lease of cell at fence on the socket and answers how to

internal/chatlist/copy.go

@@ -6,7 +6,7 @@ import (
 	"time"
 )
 
-// The frozen sentences (STAGE-1-CONTRACTS §8.1). Every surface takes its words
+// The frozen sentences. Every surface takes its words
 // from here so a respelling happens once.
 const (
 	OfferContinue = "continue here"

internal/chatlist/rows.go

@@ -44,7 +44,7 @@ type Row struct {
 
 // Quiet is the row of a chat whose live holder has gone: a lease that still
 // runs on a device that is no longer online is a chat that stopped, so it reads
-// as one that went off (`studio offline`), not `running on studio`.
+// as one that went off (`desktop offline`), not `running on desktop`.
 func (r Row) Quiet() Row {
 	if r.Status == Running {
 		r.Status = Off