Repository navigation
Description
Part 6 of #744. The broadest slice by file count, the smallest by volume.
Scope
58 files, 7,709 code lines, 2,032 comment lines (21%), 155 blocks over 3 lines, 89 citing an issue or ADR.
src/*.js— the webview.chat.js(194),main.js(177) are the heaviest, andsrc/main.jsis 38% comments.scripts/—verify-overlay.sh(170),import-pet.py(137).tests/— 325 lines across 22 files.
Land it as one PR
No single file exceeds 200 comment lines, so this stays reviewable whole.
Watch out, three things
-
tests/chat-ui-tokens.test.js:60strips CSS comments with a single-line regex (/\/\*[^*]*\*\//g). A multi-line CSS comment containing a hex color false-positives the hard-coded-color check. If you reflow a CSS comment across lines and it mentions a color, you will turn CI red in a way that looks like a design violation. -
scripts/import-pet.py:1179asserts that generatedcharacter.tomlkeeps art notes in TOML comments (assert "# Mapping:" in manifest). Paired withscripts/make-character-gallery.py:106. This is the one place in the repo where comment placement is load-bearing. Do not touch those comments or the code that writes them. -
Verify and test scripts get no phase-narrating comments.
// Phase 1: add cardsis exactly what this effort removes — the assertion or log string already documents the step, as inassert(ok, 'persisted across restart').
tests/ comments are mostly explaining what a test asserts. If the test name and the assertion already say it, the comment is a restatement and goes.
Before you start
Read #744 in full. It carries the bar, the five-step decision procedure, the hazards and the verification checklist. This issue only names your slice. Wait for #745 (the amended standard) so you compact to the new bar, not the old one.
The rule, in one line
Cap blocks at 3 lines. Delete blocks that only restate the code. Keep the one-line summary on any public item. A comment you do not understand is not a comment you are qualified to delete.
Truncating alone lands at 13.4%, not 10%. Two rules, not one.
Verify
- The diff touches no code line. Prove it over
git diff -U0, do not assert it. cargo test --workspaceandnode --test tests/*.test.jsgreen, same counts before and after.cargo clippy --workspace --all-targets -- -D warningsgreen.- Add the
windowslabel to each PR, or that leg is lint-only and will not run the tests. - Census before and after in each PR description.
— Claude Code agent, on @omesser's behalf.
Metadata
Metadata
Assignees
Labels
Projects
- StatusShow more project fieldsDone
Activity
omesser commentedon Sep 15, 2026
Correction: the CSS hazard here is a silent disarm, not a false positive
The issue body above describes
tests/chat-ui-tokens.test.jsas risking a false positive on a multi-line comment containing a hex color. That is real but minor. The serious one is the opposite, and it stays green.tests/chat-ui-tokens.test.js:30-32decides where a.chat-ui-*design block starts by counting braces per raw line, comments included:src/chat-ui.css:6and:7are comment lines that already contain.chat-ui-*:They carry no brace today, so
opens > 0is false and the guard holds. Rewrap either line so a{lands on it andskippingturns on at depth 0 and never turns off — the ADR-0013 hard-coded-colour lint silently stops checking the rest of the stylesheet, and the test still passes.A false positive turns CI red and you fix it. This turns a lint off and nobody notices.
So for this part specifically: run
node --test tests/*.test.jsbefore and after and diff the pass list, not just the exit code. Better, reflow no comment insrc/chat-ui.cssthat mentions.chat-ui-; there are only two and neither is long.Same shape elsewhere in your scope:
tests/bubble.test.js:461regexessrc/main.jsandsrc-tauri/src/main.rs;tests/connect-buttons.test.js:24slicesharness.rsbetween source literals.— Claude Code agent, on @omesser's behalf.
omesser commentedon Sep 16, 2026
Shipped on main via #765
PR #765 merged (
8976c1ad). Child 6 of #744 is done.On main now: comment-only compaction across the 71 touched files under
src/,scripts/, andtests/(vendor/fixtures excluded). Census in the PR: comment lines 2,845 → 1,906 (13.9% after restoring verify/bench one-line step labels), blocks over 3 lines 218 → 38. Code lines unchanged; node and cargo suites green with identical named pass lists vs main; the three #750 hazards (CSS hex /import-petTOML comment asserts / phase narration) were handled as specified.Acceptance met. This issue was auto-closed by the merge; leaving it closed as completed.
— Cursor agent (Coder), on @omesser's behalf.