Correct six documentation claims the overnight review falsified #45

Merged
JMR-dev merged 4 commits from docs/review-corrections into main 2026-08-23 04:21:33 +00:00
JMR-dev commented 2026-08-23 04:02:56 +00:00 (Migrated from github.com)

Closes six findings from the overnight max-effort review (Fable lead, Opus sub-agents). Documentation only — README.md and docs/defect-audit.md, verified by path check against main...HEAD. No app/src, tools/, .github/, CLAUDE.md, or the two emulator docs (another branch owns those).

Finding Issue What was wrong
R3 #12 The audit reported D5 and D7 as unfixed; both merged hours before the review
R12 #21 Named a branch that no longer exists, and a test count 15 short
R13 #22 D11 marked merged though one of its four rows was deliberately not done
R14 #23 Asserted instrumented tests cannot run locally in two places, recorded the opposite in a third
R15 #24 "On testing these" falsified in four separate statements
R18 #27 README's front-page status said the FFmpeg format tests never ran on a device; they ran green five times

How the corrections were made

Every replacement claim was verified against the source of truth, not against another document. Test counts from a real run in the worktree (257/0/0/0 across 34 classes). Branch existence from git show-ref. Merge status from git merge-base --is-ancestor. The README's five green runs by counting @Test in FFmpegEngineTest at both edd6385 and 22c7914.

No as-found body was rewritten. The audit's entries describe each defect as found — that is deliberate and stated in the file, and it is why D1's entry is still useful (it carries a falsified prediction next to the measurement that killed it). Corrections are marked editorial notes beside the original text, the pattern D1's entry already uses.

The old header did not add up. "Ten / two / one" covered 13 of 16 entries, silently dropping D12, D15 and D16. It now sums: 12 merged + 1 parked + 2 open + 1 no-action = 16.

One correction refines the review rather than repeating it. R12 implied two branches were gone; fix/space-proxy-and-notification still exists at c2e6344. The doc says so precisely.

The last commit holds the corrections to their own standard — self-review caught three defects in the first three: both correction blocks stamped with tomorrow's date, a new 18c53a3 anchor sitting two lines above an unchanged Last verified: 903b43c, and "detekt 0, lint clean" carried over on the strength of a green build rather than read off the reports.

Deliberately not decided

Four items were held rather than guessed, and are for the repo owner:

  1. Fix-column policy — whether it tracks main or freezes at a stated commit, and who updates it on merge. The minimal true anchor was written; no policy was set.
  2. Whether D11's OutputPublisher KDoc row moves into D1's entry.
  3. Whether the README status line should carry a verification claim at all — what it says is fixed; what it is for was not decided.
  4. R35 (README's restore-after-restart promise) — excluded by scope; the honest version is longer than one clause.

The API 37 pre-release Pixel rule is explicitly left standing — the emulator finding changes what runs locally, not that rule.

Gate: ktlintCheck :detekt :lintDebug --continue → BUILD SUCCESSFUL.

🤖 Generated with Claude Code

Closes six findings from the overnight max-effort review (Fable lead, Opus sub-agents). **Documentation only** — `README.md` and `docs/defect-audit.md`, verified by path check against `main...HEAD`. No `app/src`, `tools/`, `.github/`, `CLAUDE.md`, or the two emulator docs (another branch owns those). | Finding | Issue | What was wrong | |---|---|---| | R3 | #12 | The audit reported **D5 and D7 as unfixed**; both merged hours before the review | | R12 | #21 | Named a branch that no longer exists, and a test count 15 short | | R13 | #22 | D11 marked merged though one of its four rows was deliberately not done | | R14 | #23 | Asserted instrumented tests cannot run locally in two places, recorded the opposite in a third | | R15 | #24 | "On testing these" falsified in four separate statements | | R18 | #27 | README's front-page status said the FFmpeg format tests never ran on a device; they ran green five times | ## How the corrections were made **Every replacement claim was verified against the source of truth, not against another document.** Test counts from a real run in the worktree (257/0/0/0 across 34 classes). Branch existence from `git show-ref`. Merge status from `git merge-base --is-ancestor`. The README's five green runs by counting `@Test` in `FFmpegEngineTest` at both `edd6385` and `22c7914`. **No as-found body was rewritten.** The audit's entries describe each defect *as found* — that is deliberate and stated in the file, and it is why D1's entry is still useful (it carries a falsified prediction next to the measurement that killed it). Corrections are marked editorial notes beside the original text, the pattern D1's entry already uses. **The old header did not add up.** "Ten / two / one" covered 13 of 16 entries, silently dropping D12, D15 and D16. It now sums: 12 merged + 1 parked + 2 open + 1 no-action = 16. **One correction refines the review rather than repeating it.** R12 implied two branches were gone; `fix/space-proxy-and-notification` still exists at `c2e6344`. The doc says so precisely. **The last commit holds the corrections to their own standard** — self-review caught three defects in the first three: both correction blocks stamped with tomorrow's date, a new `18c53a3` anchor sitting two lines above an unchanged `Last verified: 903b43c`, and "detekt 0, lint clean" carried over on the strength of a green build rather than read off the reports. ## Deliberately not decided Four items were held rather than guessed, and are for the repo owner: 1. **Fix-column policy** — whether it tracks `main` or freezes at a stated commit, and who updates it on merge. The minimal true anchor was written; no policy was set. 2. Whether D11's `OutputPublisher` KDoc row **moves into D1's entry**. 3. Whether the README status line **should carry a verification claim at all** — what it says is fixed; what it is *for* was not decided. 4. **R35** (README's restore-after-restart promise) — excluded by scope; the honest version is longer than one clause. The API 37 pre-release Pixel rule is **explicitly left standing** — the emulator finding changes what runs locally, not that rule. Gate: `ktlintCheck :detekt :lintDebug --continue` → BUILD SUCCESSFUL. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Sign in to join this conversation.