Skip to content

test: hold the documented group and elevation-page counts against source - #2340

Merged
laurentiu021 merged 1 commit into
mainfrom
docs/structural-count-guard
Sep 16, 2026
Merged

laurentiu021 merged 1 commit into
mainfrom
docs/structural-count-guard

Conversation

@laurentiu021

Copy link
Copy Markdown
Owner

Follow-up to #2336. That PR fixed two wrong counts and found the guard could not see them; this one closes the
class by sweeping every numeric claim in the public docs and guarding the two that drift the same way.

The sweep

88 candidate numeric claims across README.md, ARCHITECTURE.md, TESTING.md, SECURITY.md,
CONTRIBUTING.md, ROADMAP.md and docs/screenshots/README.md. Every countable one, checked against source:

Claim Verdict Guarded
59 tabs (×5) correct yes, already
53 tabs with a status line correct yes, already
16 / 41 / 12 accelerator tabs correct since #2336 yes
43 screenshots · 59 tabs · 16 uncovered correct since the last PR yes
12 groups, 11 collapsible correct no → this PR
31 pages needing elevation correct no → this PR
55 of 59 tabs carry search keywords correct no
12 privacy toggles across 3 categories correct no
6 dark + 6 light theme presets correct, and all twelve names match exactly no
108 process descriptions correct no
37 view-models set the indeterminate flag, 10 set a percentage correct no

So the two I already fixed were the only genuine drifts, and both were caused by v1.109.0 adding a tab. That is
a reassuring result about the discipline and a precise one about where it fails.

Two of my own measurements were wrong first

Worth stating because it is the same trap twice:

  • "31 pages needing elevation" first read as 32 — the scan counted AdminBanner.xaml itself alongside its
    31 call sites.
  • "37 view-models" first read as 38 — it counted NavItem.cs, which mirrors a tab's progress rather than
    computing one.

A definition or a mirror sitting inside the folder being counted. Both would have produced a confident "found a
drift" report on correct code.

What is guarded, and why only these two

EveryDocumentedStructuralCount_MatchesTheSource derives the nav-group count and the collapsible count from
MainWindowViewModel, and the elevation-page count from the views that embed <v:AdminBanner/>. It checks the
claims in both README and ARCHITECTURE, each with its own floor.

These two change when a tab or an admin-gated page ships — a reason unrelated to the sentence containing them,
which is exactly the property that made the accelerator counts drift. The rest of the table changes only when
someone deliberately edits that data, so a guard there would be watching a file nobody touches by accident.

It is a sibling of EveryReadmeTabCount_MatchesTheSource, not more arms inside it: that guard is built
around the noun "tabs" and classifies claims by the phrase that follows them, and folding in different nouns
from different sources would turn a focused guard into a grab-bag whose failure message no longer says what
broke.

"Collapsible" is derived rather than counted separately — a group with one child renders as a flat row, so it is
the groups with more than one leaf. Today: Dashboard flat, eleven collapsible, which is what both documents say.

Also in this diff

OnNavFilterChanged's doc comment described NavItems as "the flat list of all 58". It is 59. The number
was doing no work in that sentence, so it now reads "every tab" rather than inviting the same drift again.

Red ritual

Mutation Result
README group count wrong RED — "claims 13 nav groups; the source has 12"
README collapsible count wrong RED — "11 of the 12 have more than one tab"
ARCHITECTURE group count wrong RED, named per document
README elevation count wrong RED — "claims 30 …; 31 views embed"
a view loses its elevation banner RED — the source side moves too, not just the doc
group sentence reworded away RED via its own floor
elevation sentence reworded away RED via its own floor
banner element match broken RED — "only 0 views were found"
group split broken RED — "only 0 nav groups were parsed"

9/9. The last two first reported SETUP-FAIL: I built their anchors as ordinary Python strings, so \b became
a backspace and \n a real newline, and neither matched. Re-run with raw strings they are red for their own
reasons. The harness asserts the anchor appears exactly once before writing — which is why that surfaced as a
setup failure instead of as two mutations that "stayed green", the reading that would have made the guard look
worthless.

Verification

  • dotnet build -c Release on all four projects: 0 errors, 0 warnings.
  • Unit suite: 5772 / 5772, 0 failed.
  • dotnet format --verify-no-changes clean on all four.

No CHANGELOG entry or version bump: test: does not release, and no application behaviour changed.

Follow-up to #2336, which fixed two count claims and found the guard could
not see them. That fix prompted a sweep of every numeric claim in the
public docs — 88 candidates across README, ARCHITECTURE, TESTING, SECURITY,
CONTRIBUTING and docs/screenshots. Result: everything else is accurate.

  59 tabs (x5) .................... correct, already guarded
  53 tabs with a status line ....... correct, already guarded
  16 / 41 / 12 accelerator tabs .... correct since #2336, now guarded
  43 screenshots / 59 / 16 ......... correct since the last PR, now guarded
  12 groups, 11 collapsible ........ correct, UNGUARDED  <- this commit
  31 pages needing elevation ....... correct, UNGUARDED  <- this commit
  55 of 59 tabs carry keywords ..... correct
  12 privacy toggles, 3 categories . correct
  6 dark + 6 light presets ......... correct, and the twelve names match exactly
  108 process descriptions ......... correct
  37 view-models set the flag,
     10 set a percentage ........... correct

Two of those took a second measurement. "31 pages needing elevation" first
read as 32 because the scan counted AdminBanner.xaml itself alongside its 31
call sites, and "37 view-models" first read as 38 because it counted
NavItem.cs, which mirrors a tab's value rather than computing one. Both are
the same population trap: a definition or a mirror sitting in the folder
being counted.

The two now guarded are the ones that drift the way the accelerator counts
did — they change when a tab or an admin-gated page ships, which is a reason
unrelated to the sentence containing them. The rest change only when someone
deliberately edits that data, so a guard would be watching a file nobody
touches by accident.

EveryDocumentedStructuralCount_MatchesTheSource is a sibling of
EveryReadmeTabCount_MatchesTheSource rather than more arms inside it: that
one is built around the noun "tabs" and classifies by the phrase that
follows, and folding in different nouns from different sources would turn a
focused guard into a grab-bag whose message no longer says what broke.
"Collapsible" is derived rather than counted separately — a group with one
child renders as a flat row, so it is the groups with more than one leaf.

Also drops a stale count from a code comment: OnNavFilterChanged described
NavItems as "the flat list of all 58". It is 59, and the number was doing no
work in that sentence, so it now says "every tab" instead of inviting the
same drift again.

Red ritual, 9 mutations, all red:

  README group count wrong ......... RED "claims 13 nav groups; the source has 12"
  README collapsible count wrong ... RED "11 of the 12 have more than one tab"
  ARCHITECTURE group count wrong ... RED, named per document
  README elevation count wrong ..... RED "30 ... ; 31 views embed"
  a view loses its banner .......... RED, the source side moves too
  group sentence reworded away ..... RED via its own floor
  elevation sentence reworded away . RED via its own floor
  banner element match broken ...... RED "only 0 views were found"
  group split broken ............... RED "only 0 nav groups were parsed"

The last two first reported SETUP-FAIL: I built their anchors as ordinary
Python strings, so \b became a backspace and \n a real newline and neither
matched. Re-run with raw strings they are red for their own reasons. The
harness asserts the anchor appears exactly once before writing, which is why
that surfaced as a setup failure rather than as two mutations that "stayed
green".

Refs #2336
@laurentiu021
laurentiu021 merged commit 478bad1 into main Sep 16, 2026
6 checks passed
@laurentiu021
laurentiu021 deleted the docs/structural-count-guard branch September 16, 2026 11:15
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