Skip to content

docs(ledger): mark the historical "93" suite counts as historical - #168

Merged
doublegate merged 3 commits into
mainfrom
docs/ledger-stale-count
Jul 29, 2026
Merged

docs(ledger): mark the historical "93" suite counts as historical#168
doublegate merged 3 commits into
mainfrom
docs/ledger-stale-count

Conversation

@doublegate

Copy link
Copy Markdown
Owner

Motivation

Nine ledger entries state the n64-systemtest failing-assertion count as 93. That
was true when each was written, but Phase 5 dropped it to 90 — and the correction
lives ~1200 lines further down under "Measured n64-systemtest impact". A reader (or a
review bot) landing on R-8 / R-11 / R-16 / R-17 sees a stale number with no indication
it has moved. It has been flagged repeatedly across recent PRs.

What this does — and deliberately does not do

The ledger states its own policy at that correction note: the older entries are
"left as-is (historical, per the ledger's immutability discipline)". This PR
respects that and does not rewrite a single claim.

Instead each stale mention now carries a short parenthetical: that it is the count as
at that entry, that docs/STATUS.md is authoritative, and that the note below
corrected it to 90. Additive only.

Why it is worth doing at all

This is the decaying-claim hazard in a different costume — the one this project
already has a lesson about. A hardcoded number in prose is only true on the day it is
written, nothing fails when it goes stale, and it then gets read as current. The
fix that stops it recurring is pointing at the single source of truth rather than
restating the value.

Precision

The sweep touched only the suite-count claims. Verified unchanged:

  • the three 93.75 MHz PClock mentions (a clock rate, not a count)
  • the 0x4E93_2C05 expected-value hex in the FPU section

0 unmarked stale suite-count claims remain; 9 marked.

Gates run locally

pre-commit run markdownlint and cargo test --workspace — green. Docs-only, no
code change.

🤖 Generated with Claude Code

Nine ledger entries state the n64-systemtest failing-assertion count as 93.
That was true when each was written, but Phase 5 dropped it to 90, and the
correction lives ~1200 lines further down under "Measured n64-systemtest
impact" — so a reader (or a review bot) landing on R-8/R-11/R-16/R-17 sees a
stale number with no indication it has moved. It has been flagged repeatedly.

The ledger's stated policy is to leave those notes as-is, "historical, per the
ledger's immutability discipline", so this does NOT rewrite them. Each stale
mention now carries a short parenthetical saying it is the count as at that
entry, that `docs/STATUS.md` is authoritative, and that the note below
corrected it to 90. The claims themselves are untouched.

This is the decaying-claim hazard in a different costume: a hardcoded number
in prose is only true on the day it is written, and nothing fails when it goes
stale. Pointing at the single source of truth is what stops it recurring.

Precision check: the sweep touched only the suite-count claims — the three
`93.75 MHz` PClock mentions and the `0x4E93_2C05` expected-value hex are
verified unchanged.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@coderabbitai

coderabbitai Bot commented Jul 29, 2026

Copy link
Copy Markdown

Review Change Stack

Warning

Review limit reached

@doublegate, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 2 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 3866b3f4-6dd1-42c4-aa3e-6d44f22ace4c

📥 Commits

Reviewing files that changed from the base of the PR and between 6703392 and 8611d52.

📒 Files selected for processing (1)
  • docs/accuracy-ledger.md
📝 Walkthrough

Walkthrough

The accuracy ledger adds provenance for the corrected n64-systemtest total, expands R-14’s triangle edge slope resolution details, and aligns R-12, R-11, R-8, and R-7 status wording with the updated count rules.

Changes

Accuracy ledger updates

Layer / File(s) Summary
Ledger resolution and count provenance
docs/accuracy-ledger.md
The ledger identifies 90 as the Phase 5 suite-wide failing-assertion total, with docs/STATUS.md as the authoritative current source. R-14 documents the quarter-pixel fixed-point unit error and decode-time slope pre-shift; R-12, R-11, R-8, and R-7 use consistent “as-at” provenance wording.

Estimated code review effort: 1 (Trivial) | ~3 minutes

Possibly related PRs

🚥 Pre-merge checks | ✅ 9 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Changelog Entry For User-Visible Changes ⚠️ Warning FAIL — user-visible docs change in docs/accuracy-ledger.md has no [Unreleased] CHANGELOG entry; the diff touches only that file. Add a brief [Unreleased] bullet for the accuracy-ledger provenance/count-note update so the user-facing docs change is recorded.
✅ Passed checks (9 passed)
Check name Status Explanation
Title check ✅ Passed It matches Conventional Commits with a docs scope, imperative subject, no trailing period, and stays within 72 characters.
Description check ✅ Passed It is clearly about marking historical n64-systemtest count claims and preserving the ledger's immutability policy.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
Oracle Number Is Stated ✅ Passed PASS: this is docs-only (docs/accuracy-ledger.md), and the ledger explicitly says n64-systemtest impact is not measured while docs/STATUS.md is authoritative.
Docs-As-Spec Sync ✅ Passed Docs-only change in docs/accuracy-ledger.md; no chip-crate behaviour changed, so the subsystem-doc sync rule is not triggered.
Measured, Never Tuned ✅ Passed PASS: The patch only adds provenance for n64-systemtest counts and leaves the existing hardware/timing entries (R-14/R-12/R-11/R-8) unchanged; no new unmeasured constant appears.
Unsafe Stays Out Of The Chip Crates ✅ Passed HEAD changes only docs/accuracy-ledger.md; diff shows no unsafe or forbid(unsafe_code) edits, so the chip-crate unsafe gate is untouched.

Comment @coderabbitai help to get the list of available commands.

All three Antigravity points, which materially improved this:

- The 26-word parenthetical repeated nine times was genuine noise. Replaced by
  ONE authoritative note above the residuals table (carrying the detail: the
  93->90 correction, the immutability rationale, and STATUS.md as the single
  source), plus a four-word uniform marker per entry. The short marker is kept
  rather than dropped so a reader who greps into a single row still sees that
  the number is as-at rather than current.
- The italic syntax differed between entries (`**93** *` vs `93 *—`); every
  marker is now byte-identical in form.
- R-11 ended up with back-to-back parenthetical fragments; the marker now
  follows the existing "(no systemtest drives the render path)" clause instead
  of splitting it.

Still additive only: no historical claim is rewritten, and the three
`93.75 MHz` PClock mentions and the `0x4E93_2C05` hex remain untouched.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@doublegate

Copy link
Copy Markdown
Owner Author

Adjudication of the Antigravity review (ledger stale counts, #168):

Suggestion — nine copies of a 26-word disclaimer is significant noise; prefer a single note or a footnote: adopted (7e2b4d0). You're right, and the first version traded one readability problem for another. There is now one authoritative note above the residuals table carrying all the detail (the 93→90 correction, the immutability rationale, and docs/STATUS.md as the single source), and each entry keeps only a four-word marker. I kept a short marker rather than removing them entirely for one specific reason: the failure mode being fixed is a reader grepping into a single row, who would never see a table-head note — the marker is what tells them the number is as-at rather than current, and the note is what tells them what it should be.

Nitpick — inconsistent italic syntax between rows: adopted. Every marker is now byte-identical in form (verified: exactly one distinct string across all nine).

Nitpick — R-11 ends up with back-to-back parenthetical fragments: adopted. The marker now follows the existing (no systemtest drives the render path) clause rather than splitting it.

Still additive only — no historical claim is rewritten, and the precision check holds: the three 93.75 MHz PClock mentions and the 0x4E93_2C05 expected-value hex are unchanged.

Thanks — this one genuinely came out better for the review.

@doublegate

Copy link
Copy Markdown
Owner Author

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Jul 29, 2026

Copy link
Copy Markdown
✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/accuracy-ledger.md`:
- Line 394: The R-14 entry uses an incomplete citation for the edge-coefficient
slope units. Replace the abbreviated “N64brew …/Commands §Edge Coefficients”
reference in the R-14 documentation with the complete primary-source page
title/path and exact section, preserving the surrounding explanation and other
citations.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 486d8603-19c9-4e89-8027-360b0e2ca529

📥 Commits

Reviewing files that changed from the base of the PR and between 43bb108 and 6703392.

📒 Files selected for processing (1)
  • docs/accuracy-ledger.md

Comment thread docs/accuracy-ledger.md Outdated
…ot exist

CodeRabbit asked for the abbreviated `N64brew *…/Commands* §Edge Coefficients`
to be spelled out so it could be independently re-opened. Doing that found
something worse than an abbreviation: **there is no "Edge Coefficients" section**
in the page — the string does not appear anywhere in the wiki mirror.

The SUBSTANCE was right. The quoted phrase is verbatim in the page and the
fixed-point formats check out; they just live under §0x08 through 0x0F - Fill
Triangle, in the Base Command word tables:

  dxhdy/dxmdy/dxldy -> "Integer part of change in x per change in y of line
                        connecting ..." (s13.16)
  yh / ym / yl      -> "s11.2 format" screen y coordinates

So the citation now names the section that exists, quotes the fields it rests
on, and records that the old section name was wrong — rather than quietly
swapping one label for another.

Every element of the new citation was verified against
`n64brew_wiki/markdown/Reality Display Processor/Commands.md` before committing
(heading, subheading, quoted phrase, both formats), and the absence of the old
section name was confirmed too.

This is the "cite the pages actually read" rule catching a citation that had
been carried for months: nothing fails when a section name is wrong, so it
survives review and then gets trusted.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@github-actions

Copy link
Copy Markdown

Antigravity review (Gemini via Ultra)

This documentation PR annotates historical 93 failing-assertion counts in docs/accuracy-ledger.md with a blockquote disclaimer and inline markers pointing to docs/STATUS.md for the current count (90).

Blocking issues

None found.

Suggestions

  • docs/accuracy-ledger.md line 388: The blockquote references (see "Measured n64-systemtest impact" below), but there is no header or column with that exact name. The table entries use n64-systemtest impact: within their status text. Update the phrasing (e.g., see the "n64-systemtest impact" notes in the table entries below) to avoid confusing readers looking for a standalone section.
  • docs/accuracy-ledger.md table cells: Repeating the verbatim 44-character text *(as-at — see the note above this table)* across 9 distinct table rows introduces significant visual noise. Use a concise footnote key (e.g., 93† or 93*) anchored to the note above the table.

Nitpicks

  • The change is trivial and strictly limited to markdown documentation.

Automated first-pass review by agy on a self-hosted runner -- not a human review.

@doublegate
doublegate merged commit 1ca51a1 into main Jul 29, 2026
11 checks passed
@doublegate
doublegate deleted the docs/ledger-stale-count branch July 29, 2026 01:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant