Trim HOW/guarantee comments in src/subagent (CL-7009) - #630
Merged
TheGreatAxios merged 1 commit intoAug 24, 2026
Merged
Conversation
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
enabled auto-merge (squash)
August 24, 2026 15:51
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
deleted the
cl-7009-comments-describe-how-and-assert-guarantees-at-35x
branch
August 28, 2026 00:09
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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/interchangeas the house reference: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 againstpruneCompleted(), which has noretainedcheck 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.ts—fleetRecords (never capped), directly contradicted byMAX_FLEET_RECORDS = 200and the eviction logic beneath it.On the modest count change
The guarantee-grep count moved only a little per file (e.g.
run.ts19→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 examplesilence alone cannot tell "wedged" from "running a ten-minute test suite", andRunning sessions are never pruned by this bound, which was verified true againstpruneCompleted'sstatus !== "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
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.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.run.tsis 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 checkgreen — 5294 pass, 0 fail. No CHANGELOG entry: comment-only.