[dinooo13]

Stacked on #70. Comments went from 4,744 lines to 1,060. The design explanations moved into a new docs/ARCHITECTURE.md, and the code is unchanged apart from a handful of renames in their own commits.

Non-blank lines	Comments before	Comments after	Code before	Code after
Sources	4,147	1,010	10,007	10,007
Tests	597	50	5,843	5,843

The rule

A comment stays only when it says something the code cannot, and a reader would otherwise get it wrong. That is either a constraint from outside, a measured number with its source, or a trap that looks removable but isn't. Doc comments that restate a name go, as do narration, history, and repeats of CLAUDE.md. Where a comment only explained what something is, the fix is a better name. The rule is now in CLAUDE.md under "Code style", so the code doesn't drift back.

Kept on purpose:

• the "main thread only" lines that justify an @unchecked Sendable
• the privacy notes in the logging code
• the measured numbers and their sources (110 ms cold pass, the 400 ms floor and issue Timing experiments: warm on wake, trailing silence pad, receipt-sequenced clipboard restore #40, Chromium's double read)
• the coordinator's ordering notes
• // MARK: in sources

How to review it

Comment-only commits (Core, System, Refine, Engines/Audio/Bench, CLI, App, Tests, and one more): each passes a checker that strips comments and whitespace from every Swift file before and after, and finds no code change. A second check compares every string literal, multi-line prompts included, file by file, because the first check can't see whitespace inside strings. It finds none changed. These commits can be skimmed.

Naming commits (2), checked by the build and all 558 tests:

• HotkeyEvent.cancelled → .interrupted. That's the word the trackers already used, and it no longer reads like the Escape cancel key.
• hotkeyOverride → standInHotkey, the name HotkeyRouter and HotkeyWarning already use.
• The coordinator's recording counter → recordingID.
• PasteWindow fields → pasteStart, pasteLength, fieldLengthAtPaste.
• ClipboardKeeper.left → leftBehind.
• The corrector's term → termIndex.

Three of these renames sit on the release-to-paste path, as renames only. Nothing persisted, logged or localised was renamed.

Docs commit: docs/ARCHITECTURE.md (389 lines) has these sections:

• Modules
• Dictation flow
• Engine
• Hotkeys
• Paste and clipboard
• Muting the speakers
• Processors
• Polish
• Learned corrections
• Settings file
• The app
• The overlay
• pladder-cli

It links to the CLAUDE.md Decisions table, PERFORMANCE.md and BENCHMARKS.md rather than repeating them. Code points into it with one line where a reader needs it, and every pointer names a section that exists. README and CLAUDE.md link to it.

No benchmark: no code on the release path changed beyond the three renames.

Review fixes

• Merge of Architecture review: every bug fixed with a regression test, polish and clipboard robustness, and the structural work #70's second review fixes (0cab953). Conflicts resolved to this branch's comment rule, with its renames applied to the new code (update(_:standInHotkey:monitor:), currentStandInHotkey, recordingID). Checked again with a comment- and whitespace-stripping comparison of every Swift file: apart from the documented renames, the code here equals Architecture review: every bug fixed with a regression test, polish and clipboard robustness, and the structural work #70's head (5b2afc3).
• ARCHITECTURE.md for Architecture review: every bug fixed with a regression test, polish and clipboard robustness, and the structural work #70's fixes (2a66a4a): the utterance handle and UtteranceSlot, each cancel waiting for the one before, a press cancelled while it waits, the monitor a chord change picks, the processors rebuilt for the dictionary only, the checksum a cancel reaches, firstOf in Core.
• Factual slips (d279d92): the key-down order (engine, polish toggle and style are read before the state flips), the Live Transcript loop's cadence, the polish budget starting when the polish does rather than at the release, and key names coming from KeyNames.xcstrings in PladderSystem.
• Constraints the comment pass dropped (b78c30d): why a non-ASCII term is not fuzzy-matched, why the AX reads are not debounced, that a secure field is never watched, why eventually and waitForSleeper wait in real time, the lifecycle's rule for every session end, Carbon taking only a bare Escape, and a cancelled download starting over where a failed one resumes.
• One statement per timing (a619a6c): ARCHITECTURE.md and ClipboardKeeper's header point at CLAUDE.md's Output, Send key, Toggle key and Interrupted press rows instead of repeating them.

The line counts in the table above are from before these commits. swift test: 590 tests by swift-testing's count, all passing; swift build and swift build -c release have no warnings in Sources/.

🤖 Generated with Claude Code