docs(review): one telling per invariant — trim the rebuilt modules' header autopsies

[benvinegar]

Third cleanup PR from the post-merge Opus review. Stacked on #737 (base is claude/review-cleanup-renames; retarget to main after #737 merges). Comments only — the diff is 31 files, +108/−107, with no code, export, or behavior changes.

What the documentation review found

The rebuild's inline comments are excellent — invariants stated where they're load-bearing. The module headers, though, ran one rhetorical template across all 24 new modules: aphoristic opener, a paragraph re-litigating a prototype defect with its audit finding ID, and a "deliberately X rather than Y" closer ("rather than" 85×, "deliberately" 15×, the same prototype anecdote retold in up to 8 files). Headers exist to orient a maintainer, not to argue with a dead prototype.

Editing rule applied

Keep the invariant, drop the autopsy. A claim like "revisions are only comparable within a generation" survives; "the prototype's browser compared two of them by JSON.stringify" does not. Each recurring anecdote now lives once, in the module that owns the rule (generationOrder.ts for ordering, noteSize.ts for the byte limit, reviewCommands.ts for anchor fallback) — the other tellings shrink to a bare audit finding-ID citation. Unverifiable global claims ("no other comparison anywhere in the daemon") and defensive self-assessments ("that indirection is the point", "a scope boundary rather than a missing feature") are cut. "Deliberately" dropped from 13 sites where the sentence already gives the reason; kept where it does semantic work (e.g. "a selection that deliberately preserves the viewport"). src/ui/lib/reviewProjection.ts's header was the style model throughout.

JSDoc gaps filled

ReviewAddress (what distinguishes the four variants), ReviewNoteAnchorInput.preferred (it decides ownership), ReviewIntentFacts (core refuses to invent identity or time), the five previously-bare ReviewIntent variants, ReviewState, and ReviewChunkAssemblerOptions (the injected ReviewDigestFn seam). Two drafts were corrected against the implementation before landing: notes/set-visibility only gates agent notes, and filter/set does not re-home the selection.

Gates

bun run typecheck clean; bun run lint 0/0; bun run format no residual diff; core + app + session + conformance + scripts suites 725 pass / 0 fail. No test asserted on any changed comment text. Empty changeset (maintenance).

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hunk-web	Ignored		Aug 14, 2026 6:49pm

[greptile-apps]

Greptile Summary

This documentation-only cleanup removes repetitive historical commentary while preserving locally relevant invariants and adds JSDoc for key review-model types and intent variants.

• Simplifies module headers across review core, application, session, and conformance-test modules.
• Documents review addresses, anchor ownership, intent facts and variants, review state, and resource assembler options.
• Adds an empty maintenance changeset without changing executable behavior.

Confidence Score: 5/5

The PR appears safe to merge because it changes only comments and adds an empty maintenance changeset.

The diff does not modify executable statements, exported type shapes, configuration behavior, or test expectations, and no actionable documentation defect was identified.

Important Files Changed

Filename	Overview
src/core/review/intents.ts	Adds and refines JSDoc for intent facts and variants without changing their types or behavior.
src/core/review/address.ts	Documents the semantics and distinctions of ReviewAddress variants; executable code is unchanged.
src/core/review/anchors.ts	Clarifies preferred-line ownership and trims header commentary without changing anchor resolution.
src/core/review/resourceAssembly.ts	Adds documentation for assembler options and the injected digest seam without modifying assembly logic.
src/core/review/state.ts	Adds a semantic overview for ReviewState while preserving all state shapes and transitions.
.changeset/review-header-cleanup.md	Adds an intentionally empty maintenance changeset for the documentation-only update.

_{Reviews (1): Last reviewed commit: "docs(review): trim the rebuild's module ..." | Re-trigger Greptile}