Skip to content

Trim HOW/guarantee comments in src/subagent (CL-7009) - #630

Merged
TheGreatAxios merged 1 commit into
mainfrom
cl-7009-comments-describe-how-and-assert-guarantees-at-35x
Aug 24, 2026
Merged

Trim HOW/guarantee comments in src/subagent (CL-7009)#630
TheGreatAxios merged 1 commit into
mainfrom
cl-7009-comments-describe-how-and-assert-guarantees-at-35x

Conversation

@TheGreatAxios

Copy link
Copy Markdown
Collaborator

Comment-only cleanup of src/subagent/*. 25 files, +141/−156. No logic changes.

Closes CL-7009

Why

Nine times in one night a comment asserting a mechanism that did not exist caused real damage. Measured against ~/abklabs/interchange as the house reference:

comment lines assert a guarantee rate
interchange 41,463 83 0.20%
corbits-code 18,978 1,346 7.09%

Interchange is denser in comments than we are (37.8% vs 26% of non-test lines) and still 35× cleaner on this axis, so volume was never the target — the WHY/HOW split is.

Two confirmed false guarantees removed

  • session-store.ts — the claim that "completed" is exempt from pruneCompleted's cap. Verified against pruneCompleted(), which has no retained check at all. (CL-7007: Give retained sessions their own retention cap #628 fixed the underlying behavior separately under CL-7007; that file's version on main wins here.)
  • agent-fleet.tsfleetRecords (never capped), directly contradicted by MAX_FLEET_RECORDS = 200 and the eviction logic beneath it.

On the modest count change

The guarantee-grep count moved only a little per file (e.g. run.ts 19→18). That is the honest result rather than a miss: spot-checking the retained matches shows most are genuine WHY-narration that happens to contain "never"/"cannot", not false guarantees — for example silence alone cannot tell "wedged" from "running a ten-minute test suite", and Running sessions are never pruned by this bound, which was verified true against pruneCompleted's status !== "running" && lifecycleStatus !== "running" filter.

The vocabulary grep is a finding aid, not the metric. Driving it to interchange's 0.2% by deleting accurate rationale would make the codebase worse.

Flagged, deliberately not fixed here

  1. retain-salvage.test.ts — a test titled "…without bound" whose body asserts a bounded length. Same disease in a test name rather than a comment. CL-7007: Give retained sessions their own retention cap #628 renamed this file's tests; confirm it is resolved there.
  2. authority.ts — module doc admits the subtree-authority rule is "not enforced at runtime yet." Pre-existing; worth confirming that statement is itself still true.
  3. Missing-test candidate: the "always disposes salvage before reporting resumable" invariant on the deadline/cancel path in run.ts is only covered indirectly. That is the shape a real guarantee should take — a test, not a sentence.

Rebase note

Three files (session-store.ts, session-store.test.ts, agent-fleet.test.ts) conflicted with #628, which rewrote them. Main's versions were taken for those; the cleanup lands in the other 25 files.

Gate: bun run check green — 5294 pass, 0 fail. No CHANGELOG entry: comment-only.

Comment-only pass: removes ticket-number references, deletes or corrects
comments asserting guarantees the code no longer provides (e.g. a stale
pruneCompleted exemption claim in session-store.ts, an inaccurate
"never capped" claim about fleetRecords in agent-fleet.ts), and trims
narrative comments down to their WHY. No logic changes; no CHANGELOG entry.
@linear-code

linear-code Bot commented Aug 24, 2026

Copy link
Copy Markdown

CL-7009

@TheGreatAxios
TheGreatAxios enabled auto-merge (squash) August 24, 2026 15:51
@TheGreatAxios
TheGreatAxios merged commit 8fe3334 into main Aug 24, 2026
5 checks passed
TheGreatAxios added a commit that referenced this pull request Aug 27, 2026
Comment-only pass: removes ticket-number references, deletes or corrects
comments asserting guarantees the code no longer provides (e.g. a stale
pruneCompleted exemption claim in session-store.ts, an inaccurate
"never capped" claim about fleetRecords in agent-fleet.ts), and trims
narrative comments down to their WHY. No logic changes; no CHANGELOG entry.
TheGreatAxios added a commit that referenced this pull request Aug 27, 2026
Comment-only pass: removes ticket-number references, deletes or corrects
comments asserting guarantees the code no longer provides (e.g. a stale
pruneCompleted exemption claim in session-store.ts, an inaccurate
"never capped" claim about fleetRecords in agent-fleet.ts), and trims
narrative comments down to their WHY. No logic changes; no CHANGELOG entry.
@TheGreatAxios
TheGreatAxios deleted the cl-7009-comments-describe-how-and-assert-guarantees-at-35x branch August 28, 2026 00:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant