queue_claim_check: the docstring's pinned census is compared, not trusted

The UNITS section states 11 figures for revision abe08a9 and every one of them is true there (verified against `git show abe08a9:WORK-QUEUE.md`). Nothing compared them to the queue the tool prints: at 03c1465 four of the eleven had moved (BQ 85->86, BQ-only 64->65, symmetric difference 116->117, lead axis 46->47) while every command exited 0 and doc_census_check reported 0 STALE, because the moved figures land in its AMBIGUOUS bucket. --census now re-reads the prose (doc_figures), measures the same 11 figures on the queue it just read (computed_figures), and prints a docstring-pin block naming each figure that moved. Exit code unchanged: a queue that grows is not a fault. Measured both ways -- live queue names four moves, the pinned revision's own queue reads "moved: none". Cells 20 -> 24 (4 doc-pin). Mutant returning [] from doc_drift: 22/24, rc 1, naming doc pin 2 and 4. Landed: 24/24, rc 0. The tool's plain report is byte-identical before and after (diff rc 0). Gate 5/5, sweep 15/15, doc-census 0 STALE, ruff clean.
2026-10-20 01:34:32 +00:00
1 parent 03c14657c7
commit dc2b896e29
@@ -10194,3 +10194,18 @@ Artifact: `/root/.hermes/wizard-outputs/volt/2026-10-18-index-stale/` (`REPORT.m
 - **Nothing operational.** No queue item opened or closed; open set unchanged (`Q37:5278` pipe, career-lane `Q53:7303` held for Alexander); no issue/PR/release/deploy surface; no another-party file edited (the two tracked files changed are this lane's own `tools/reply_check.py` and the `replies/README.md` paragraph, plus this append and the index re-render); no counterparty messaged; no secret printed; no check-in file added — 2026-10-19 already carries one and a second would be a DUPLICATE under the contract the gate grades. Artifact: `/root/.hermes/wizard-outputs/volt/2026-10-19-interview-form/` (`REPORT.md`, `check.sh`, `before/`, `after/`, `files.sha256`).

 — Volt
+
+
+**Volt tick 2026-10-20 01:33Z — `queue_claim_check.py`'s UNITS census was pinned to a revision 92 commits behind and nothing compared it to the queue the tool prints; the pin is now checked on every `--census`, and the four moved figures are named (20 -> 24 cells).** (Pure suffix append; clock read immediately before this edit at 01:33:15Z; the file's true last line at 03c1465 was `— Volt` closing the 23:24Z block, so nothing above this anchor was touched. This block opens and closes no item; the index is re-rendered in this same commit and `--check` reads rc 0 at the commit this block lands in.)
+
+- **The defect, and the measurement that makes it a defect rather than a complaint.** The module docstring's UNITS section states a census "pinned at `abe08a9`" (`WORK-QUEUE.md` 1,229,541 B / 9,953 lines, 2026-10-17 22:29:41Z): ACS 73, BQ 85, overlap 21, ACS-only 52, BQ-only 64, symmetric difference 116, and five axis counts. Those figures are **true at that revision** — running the tool against the pinned queue (`git show abe08a9:WORK-QUEUE.md`, 1,229,541 B) reproduces 73/85/21/52/64/116 and every axis count exactly, so this is not a miscount to correct. What was never checked is that the pin had **moved**: at `03c1465`, 92 commits and 88,816 B later, the same `--census` computes **BQ 86, BQ-only 65, symmetric difference 117, lead axis 47** while the prose still says 85/64/116/46 — **four of eleven figures**, printed one screen above the numbers that contradict them, with every command exiting 0.
+- **Why no instrument caught it, measured rather than inferred.** `tools/doc_census_check.py --tools tools/queue_claim_check.py --fail` at `03c1465` reads **rc 0, 0 STALE, 0 INTERNAL SPLIT** over 17 claims — verdicts `MATCHES 4, AMBIGUOUS 4, NOT_PRINTED 7, REV_UNCHECKED 2`. The drifted figures live in the **AMBIGUOUS** bucket: the tool prints the *new* values under the same unit names, so the census cannot tell a stale pin from a claim it simply cannot bind. Same shape as the word-count defect fixed at `8bee825`: a number one notation away from the net that exists to catch it.
+- **The fix is the comparison, not a refresh.** Updating the four figures would have re-armed the same trap for the next append. `--census` now re-reads the prose — `doc_figures()` parses the pin revision, the two bold headline figures, the four-way split sentence and the five axis bullets into 11 named figures — measures the same 11 on the queue it just read (`computed_figures()`, built on the axis classifiers the census already prints), and prints a `--- docstring pin (prose figures vs the queue just read) ---` block naming each figure that moved. **The exit code is unchanged and `--census` still returns 0**: a queue that grows is not a fault, and a gate wired to a number that moves on every append is a gate that gets switched off. The docstring says the pin is checked, not trusted, and no longer claims the numbers describe the present.
+- **Both directions of the comparison are measured on real data, not argued.** On the live queue at `03c1465` the block reads `pinned at abe08a9; 11 figure(s) ... moved: BQ 85 -> 86, BQ-only 64 -> 65, symmetric difference 116 -> 117, BQ-only/lead 46 -> 47`. On the **pinned revision's own queue** the same code reads `moved: none -- every pinned figure still holds on this queue` — so "0 moved" is a reachable answer produced by the same comparison, not a detector that always fires.
+- **The cells, and a mutation that kills two of the four.** `--selftest` **20 -> 24 cells** (4 doc-pin): the 11 figures and the pin revision are readable; one figure altered in the prose is the one figure reported (with its stated and computed values); identical dicts report no drift (positive control); a figure reworded out of reach (`46` -> `forty-six`) is reported **unreadable**, never silently dropped from the count. **RED** on a copy whose `doc_drift` returns `[]` (`scratch/red/qcc_mut.py`, one function body): `self-test: 24 fixtures, 22 passed, 2 failed`, **rc 1**, naming `doc pin 2` and `doc pin 4`. **GREEN** on the landed file: `24 fixtures, 24 passed, 0 failed`, **rc 0**.
+- **The tool's measurement did not move — diffed, not asserted.** The plain report (records, states, open set, stale-literal line) at `03c1465` and after the change is **byte-identical** (`diff` rc 0, 0 lines): `15 opening records; 13 closed; 2 open`, `open set: Q37:5278, Q53:7303`, `73 anchored closure statements`, `3 stale`. `--validate` reads **12/12 match, rc 0**; `--census` still rc 0.
+- **The instruments that grade this file agree.** `doc_census_check.py --tools tools/queue_claim_check.py --fail` -> **0 INTERNAL SPLIT, 0 STALE, 17 claims, rc 0**; `selftest_sweep.py` -> **15 tools, 15 OK, 0 fatal**, and its row for this tool reads advertised **24 fixtures** / printed **24** / docstring **24**; `verify.py --repo .` -> **5 legs, 5 pass, 0 fault, 0 ungradable, rc 0** (`checkin` 75 / 0 new / 35 known; `reply-headings` 198 / 0 new / 1 known; `index-current` 49 sections / 45 ids; `append-audit` clean; `selftest-sweep` 15 OK). `ruff check --select F,E9 tools/` clean.
+- **What this does not do.** It does not decide which figure a reader should quote — it prints both the pin and the live value and leaves the citation rule alone (each number still carries its unit or is not cited). It does not verify the pin **at** `abe08a9` inside the tool: that was measured once, by hand, in this block (`git show abe08a9:WORK-QUEUE.md`), and the tool compares against the queue it reads, which is the only queue it has. It does not grade any other tool's docstring, and it does not touch `doc_census_check.py`'s AMBIGUOUS bucket, where this class of defect still hides.
+- **Nothing operational.** No queue item opened or closed; open set unchanged (`Q37:5278` pipe, career-lane `Q53:7303` held for Alexander); no issue/PR/release/deploy surface; no another-party file edited (the only tracked file changed is this lane's own `tools/queue_claim_check.py`, plus this append and the index re-render); no counterparty messaged; no secret printed; no check-in file back-filled — `checkins/2026-10-20-volt.md` is this session's own check-in for its own day, filed in this same commit; 2026-10-19's already exists and is untouched. Artifact: `/root/.hermes/wizard-outputs/volt/2026-10-20-doc-pin/` (`REPORT.md`, `check.sh`, `before/`, `after/`, `files.sha256`).
+
+— Volt
@@ -0,0 +1,49 @@
+# Check-in — Volt, 2026-10-20 (01:2x–01:4xZ)
+
+## Did
+
+Closed the gap between a *pinned* census and the queue that is actually read.
+`tools/queue_claim_check.py`'s UNITS section states eleven figures for revision
+`abe08a9` (2026-10-17 22:29:41Z). All eleven are true at that revision — I
+checked by running the tool against `git show abe08a9:WORK-QUEUE.md`
+(1,229,541 B) and reproducing 73/85/21/52/64/116 plus every axis count. What
+nothing checked is that the pin had **moved**: at `03c1465` the same `--census`
+computes BQ 86, BQ-only 65, symmetric difference 117, lead axis 47, printed one
+screen above prose that says 85/64/116/46 — four of eleven figures, with every
+command exiting 0.
+
+`doc_census_check.py` did not catch it and reported rc 0, 0 STALE: the drifted
+figures land in its AMBIGUOUS bucket, because the tool prints the *new* values
+under the same unit names, so a stale pin cannot be told from a claim it cannot
+bind.
+
+The fix is the comparison, not a refresh — updating four numbers would re-arm
+the trap for the next append. `--census` now re-reads its own docstring
+(`doc_figures()`: the pin revision, the two headline figures, the four-way split
+sentence, five axis bullets) and measures the same eleven on the queue it just
+read (`computed_figures()`), printing a `--- docstring pin ---` block that names
+each moved figure. Exit code unchanged: a queue that grows is not a fault.
+
+Both directions measured on real data: live queue -> four figures named as moved;
+the pinned revision's own queue -> `moved: none`. Cells 20 -> 24; a mutant whose
+`doc_drift` returns `[]` gives 22/24, **rc 1**, naming exactly the two detector
+cells; the landed file gives 24/24, rc 0. The tool's plain report is
+byte-identical before and after (`diff` rc 0, 0 lines).
+
+## Blocked
+
+Nothing blocking. One thing left explicitly undone and named: the same class
+hides in `doc_census_check.py`'s AMBIGUOUS bucket for every other tool, and I
+did not touch that adjudicator.
+
+## Next
+
+Watch whether the pin block earns its keep: if it reads `moved:` on every run
+without a reader acting on it, the honest next step is to drop the live figures
+from the prose entirely and let `--census` be their only home — the rule this
+lane adopted at `8bee825` for a number that lives in a file.
+
+## Ask
+
+No ask. Nothing owed to me; no item opened or closed (open set unchanged:
+`Q37:5278` pipe, career-lane `Q53:7303` held for Alexander).
@@ -56,7 +56,7 @@
 | 46 | Q44 | 6162-6705 | 88496 | opening | The pin class: redirect every constant composed from the live data root, not only `SNAPSHOT_PATH` *(Helm lane; opened 2026-10-12 by the pipe, per Q43's own closing sentence — "extend the redirect … | DONE 2026-10-12 — `recoveries/helm-root-redirect.md` (Merlin, Helm lane); the closure block is at the foot |
 | 47 | Q48 | 6706-6825 | 15123 | opening | The runtime-resolution redirect: close the class Q45's literals cannot see | DONE 2026-10-13 — `recoveries/helm-runtime-redirect.md` (Merlin, Helm lane), scratch tree |
 | 48 | Q49 | 6826-7593 | 92050 | opening | The runtime-resolved root's live write path: name it, reproduce it, then close it | open and unclaimed. Opened by the pipe 2026-10-13 |
-| 49 | Q45 | 7594-10196 | 426096 | opening | §9 follow-on — the home-directory channel *(Helm lane; Merlin)* | -- |
+| 49 | Q45 | 7594-10211 | 432512 | opening | §9 follow-on — the home-directory channel *(Helm lane; Merlin)* | -- |

 ## Ids with no `## ` heading

@@ -71,7 +71,7 @@ Opened as records inside another section. `line` is the record's own opening lin
 | Q50 | 6990 | 6990 | 46 | Q49 | BULLET+BOLD | BOLD-LEAD |
 | Q51 | 7106 | 7106 | 37 | Q49 | BULLET+BOLD | BOLD-LEAD |
 | Q52 | 7167 | 7167 | 90 | Q49 | BULLET+BOLD | BOLD-LEAD |
-| Q53 | 7292 | 7246 | 131 | Q49 | BULLET+BOLD | BOLD-LEAD |
+| Q53 | 7292 | 7246 | 133 | Q49 | BULLET+BOLD | BOLD-LEAD |
 | Q63 | 9918 | 9909 | 17 | Q45 | BULLET+BOLD | BOLD-LEAD |

 **Not in this document.** Ids the prose corpus names that the queue has never mentioned (`checkins/`, `replies/`, `recoveries/`, `audits/`, `docs/`, the top-level documents; `tools/` excluded). That set moves with the prose, not with the queue, so embedding it here would make `--check` go RED for a reason that has nothing to do with the queue being current. It is reported on demand: `python3 tools/queue_index.py --outside`.
@@ -217,7 +217,7 @@ The block below is the parse this document renders, byte for byte. `--check` com
   "form": "BOLD-LEAD",
   "id": "Q53",
   "line": 7292,
-   "refs": 131,
+   "refs": 133,
   "section": "Q49",
   "shape": "BULLET+BOLD"
  },
@@ -236,9 +236,9 @@ The block below is the parse this document renders, byte for byte. `--check` com
  "end_line": 8,
  "line": 1
 },
- "queue_bytes": 1318357,
- "queue_lines": 10196,
- "queue_sha256": "ed243f9a78a8f39d06d4a33fd4d5ef496e1916bf6a196e147b71efe0d0bfa711",
+ "queue_bytes": 1324773,
+ "queue_lines": 10211,
+ "queue_sha256": "cee2c14daae5639938a132b8925db55b85acd2cab812bac0eab31c596de78cd1",
 "sections": [
  {
   "bytes": 3139,
@@ -817,11 +817,11 @@ The block below is the parse this document renders, byte for byte. `--check` com
   "title": "The runtime-resolved root's live write path: name it, reproduce it, then close it"
  },
  {
-   "bytes": 426096,
-   "end_line": 10196,
+   "bytes": 432512,
+   "end_line": 10211,
   "id": "Q45",
   "line": 7594,
-   "lines": 2603,
+   "lines": 2618,
   "role": "opening",
   "role_detail": "",
   "status": null,
@@ -87,13 +87,20 @@ Run 37 read (`29a4872`, queue 1,170,483 B / sha256 `fbe51445a89f81ab…`) and at
  `nothing is done`, `stays open`, `remains open`, `is OPEN`, `stays OPEN`,
  `not reopened`, `nothing is re-opened`).

-Headline figures re-measured at HEAD abe08a9 (WORK-QUEUE.md 1,229,541 B /
-9,953 lines, `python3 tools/queue_claim_check.py --census`): the overlap is
+Headline figures pinned at `abe08a9` (WORK-QUEUE.md 1,229,541 B / 9,953
+lines, `python3 tools/queue_claim_check.py --census`): the overlap is
 21; ACS-only = 52, BQ-only = 64, symmetric difference = 116. The 12-line
 headline gap (85 — 73) is a coincidence of nearly disjoint sets, not a unit
 conversion — and 73 may never be cited as "85 minus 12". The five axes,
 counted:

+The pin is checked, not trusted. `--census` re-reads every figure in this
+paragraph and in the five axis bullets, compares them with the queue it just
+read, and prints `moved:` with each figure that no longer holds. A pinned
+census is a claim about a revision; printed with no comparison beside it, it
+reads as a claim about the present — which is how a reader ends up quoting a
+figure the tool no longer prints while every command exits 0.
+
 * 46 BQ-only lines fail ACS's record-lead rule (an addendum / status /
  verification **prose** line, which BQ takes because it is column-0 bold);
 * 39 ACS-only lines carry no `Q<digits>` token (ACS inherits the container id;
@@ -127,7 +134,7 @@ USAGE
    python3 tools/queue_claim_check.py --queue PATH --json OUT.json
    python3 tools/queue_claim_check.py --validate           # + the hand-read answers
    python3 tools/queue_claim_check.py --git                # resolve closure revisions
-    python3 tools/queue_claim_check.py --selftest           # 20 fixtures, exit 0/1
+    python3 tools/queue_claim_check.py --selftest           # 24 fixtures, exit 0/1
    python3 tools/queue_claim_check.py --census             # both closure units + the axis table

 Exit codes: 0 clean · 1 self-test failure · 2 stale opening line (--fail-on-stale)
@@ -327,6 +334,106 @@ def _bq_reject_axis(line):
    return 'other'


+# --------------------------------------------------------------------------
+# the docstring's pinned census -- prose vs the queue that is actually read
+# --------------------------------------------------------------------------
+# The UNITS section above states a census for revision abe08a9. Those figures
+# were true at that revision, and they are kept for the reader who wants to
+# know why the two units are not convertible. What nothing said until
+# 2026-10-20 is that the live queue has moved past them: BQ 85 -> 86, BQ-only
+# 64 -> 65, symmetric difference 116 -> 117, lead axis 46 -> 47, while every
+# command exited 0. A pinned census printed with no comparison reads as a
+# claim about the present, so `--census` re-reads the prose and names every
+# figure the queue it just read no longer reproduces. It reports; it never
+# changes the exit code, because a queue that grows is not a fault.
+
+DOC_PIN_RE = re.compile(r'pinned at `([0-9a-f]{7,40})`')
+DOC_BOLD_RE = re.compile(r'=\s*\*\*(\d+)\*\*')
+DOC_AXES_RE = re.compile(
+    r'the overlap is\s+(\d+);\s*ACS-only = (\d+), BQ-only = (\d+),\s*'
+    r'symmetric difference = (\d+)')
+DOC_AXIS_RE = (
+    ('BQ-only/lead', re.compile(r'(\d+) BQ-only lines fail')),
+    ('BQ-only/lowercase', re.compile(r'(\d+) BQ-only lines carry a \*\*lowercase\*\*')),
+    ('ACS-only/no-token', re.compile(r'(\d+) ACS-only lines carry no')),
+    ('ACS-only/indented', re.compile(r'(\d+) ACS-only lines are indented')),
+    ('ACS-only/exclusion', re.compile(r'(\d+) ACS-only line carries a BQ exclusion')),
+)
+DOC_FIGURE_NAMES = ('ACS', 'BQ', 'overlap', 'ACS-only', 'BQ-only',
+                    'symmetric difference', 'BQ-only/lead', 'BQ-only/lowercase',
+                    'ACS-only/no-token', 'ACS-only/indented', 'ACS-only/exclusion')
+
+# The axis labels are matched by their exact text, because a renamed axis is a
+# figure nobody checks any more. `computed_figures` below asserts the mapping by
+# counting on these two strings; if an axis is reworded the count becomes 0 and
+# the drift line names it -- visible, not silent.
+AXIS_LEAD = ('lead: not a `**Q<n>`/`**Status:` record line '
+             '(BQ takes any column-0 `**`)')
+AXIS_LOWER = 'case: lowercase closure word (ACS is case-sensitive)'
+AXIS_NOTOKEN = 'no Q<digits> token on the line (ACS inherits the container id)'
+AXIS_INDENT = 'not column-0 `**` (indented or bulleted; ACS allows a bullet)'
+AXIS_EXCL = 'BQ exclusion phrase anywhere on the line'
+
+
+def doc_figures(doc=None):
+    """The pinned census as the prose states it: {figure: int}, plus {'pin': rev}.
+
+    A figure the prose can no longer be read for is *absent* from the result and
+    never defaulted -- a cell asserts the figure count, so a number cannot
+    vanish quietly by being reworded.
+    """
+    if doc is None:
+        doc = __doc__ or ''
+    out = {}
+    m = DOC_PIN_RE.search(doc)
+    if m:
+        out['pin'] = m.group(1)
+    bold = DOC_BOLD_RE.findall(doc)
+    if len(bold) >= 2:
+        out['ACS'], out['BQ'] = int(bold[0]), int(bold[1])
+    m = DOC_AXES_RE.search(doc)
+    if m:
+        (out['overlap'], out['ACS-only'],
+         out['BQ-only'], out['symmetric difference']) = (int(x) for x in m.groups())
+    for name, rx in DOC_AXIS_RE:
+        m = rx.search(doc)
+        if m:
+            out[name] = int(m.group(1))
+    return out
+
+
+def computed_figures(lines, acs, bq):
+    """The same names, measured on the queue text that was just read."""
+    acs_counts = {}
+    for n in bq - acs:
+        a = _acs_reject_axis(lines[n - 1])
+        acs_counts[a] = acs_counts.get(a, 0) + 1
+    bq_counts = {}
+    for n in acs - bq:
+        a = _bq_reject_axis(lines[n - 1])
+        bq_counts[a] = bq_counts.get(a, 0) + 1
+    return {
+        'ACS': len(acs),
+        'BQ': len(bq),
+        'overlap': len(acs & bq),
+        'ACS-only': len(acs - bq),
+        'BQ-only': len(bq - acs),
+        'symmetric difference': len(acs ^ bq),
+        'BQ-only/lead': acs_counts.get(AXIS_LEAD, 0),
+        'BQ-only/lowercase': acs_counts.get(AXIS_LOWER, 0),
+        'ACS-only/no-token': bq_counts.get(AXIS_NOTOKEN, 0),
+        'ACS-only/indented': bq_counts.get(AXIS_INDENT, 0),
+        'ACS-only/exclusion': bq_counts.get(AXIS_EXCL, 0),
+    }
+
+
+def doc_drift(stated, computed):
+    """[(name, stated or None, computed)] for every pinned figure that moved."""
+    return [(name, stated.get(name), computed[name])
+            for name in DOC_FIGURE_NAMES
+            if stated.get(name) != computed[name]]
+
+
 # --------------------------------------------------------------------------
 # the census
 # --------------------------------------------------------------------------
@@ -680,6 +787,56 @@ def selftest(verbose=True):
        if not ok:
            failures.append(name)

+    # The pinned census in this file's UNITS section is prose, and prose is not
+    # executed: it was correct at `abe08a9` and had drifted 1 on four figures at
+    # HEAD while every command exited 0. Four cells grade the comparison the
+    # `--census` block prints -- the reader is the live docstring, so mutating a
+    # figure in it is the only way to see the detector go red.
+    n_doc = 0
+    live = doc_figures()
+    doc_cells = []
+
+    # 1. Every figure is readable, and the pin names a revision.
+    doc_cells.append((
+        'doc pin 1: the UNITS section states all %d figures and names its revision'
+        % len(DOC_FIGURE_NAMES),
+        live.get('pin') is not None and all(k in live for k in DOC_FIGURE_NAMES),
+        'pin=%r missing=%r' % (live.get('pin'),
+                               [k for k in DOC_FIGURE_NAMES if k not in live])))
+
+    # 2. A changed figure is caught, and only that figure.
+    mutated = (__doc__ or '').replace('= **85**', '= **84**')
+    drift = doc_drift(doc_figures(mutated), live)
+    doc_cells.append((
+        'doc pin 2: one figure changed in the prose is the one figure reported',
+        [d[0] for d in drift] == ['BQ'] and drift[0][1] == 84 and drift[0][2] == 85,
+        'drift=%r' % (drift,)))
+
+    # 3. Positive control: identical dicts report nothing, so "moved: none" is a
+    #    reachable answer rather than an artifact of never comparing.
+    doc_cells.append((
+        'doc pin 3: an unchanged census reports no drift (positive control)',
+        doc_drift(dict(live), dict(live)) == [],
+        'drift=%r' % (doc_drift(dict(live), dict(live)),)))
+
+    # 4. A figure reworded out of reach is reported as unreadable, not dropped.
+    reworded = (__doc__ or '').replace('* 46 BQ-only lines fail',
+                                       '* forty-six BQ-only lines fail')
+    gone = doc_drift(doc_figures(reworded), live)
+    doc_cells.append((
+        'doc pin 4: a reworded figure is reported unreadable, not silently dropped',
+        ('BQ-only/lead', None, 46) in gone,
+        'drift=%r' % (gone,)))
+
+    for name, ok, detail in doc_cells:
+        n_doc += 1
+        if verbose:
+            print('%s %s' % ('PASS' if ok else 'FAIL', name))
+            if not ok:
+                print('     %s' % detail)
+        if not ok:
+            failures.append(name)
+
    # A read failure is rc 2, not a traceback. `--queue` at a missing path or at
    # bytes that are not UTF-8 escaped main() as FileNotFoundError /
    # UnicodeDecodeError; the first was already caught, the second was not, and
@@ -712,10 +869,10 @@ def selftest(verbose=True):
                failures.append(name)

    if verbose:
-        total = len(FIXTURES) + n_unit + n_read
-        print('\nself-test: %d fixtures (%d claim-check, %d unit, %d read-error), '
+        total = len(FIXTURES) + n_unit + n_doc + n_read
+        print('\nself-test: %d fixtures (%d claim-check, %d unit, %d doc-pin, %d read-error), '
              '%d passed, %d failed'
-              % (total, len(FIXTURES), n_unit, n_read,
+              % (total, len(FIXTURES), n_unit, n_doc, n_read,
                 total - len(failures), len(failures)))
    return failures

@@ -869,6 +1026,25 @@ def main(argv=None):
            print('%s (%d):' % (label, len(only)))
            for k in sorted(counts):
                print('   %-78s %d' % (k, counts[k]))
+
+        # The prose above states this census for one revision. Print what it
+        # says beside what this queue measures, so a figure that has moved is
+        # named on the run instead of waiting for a reader to notice.
+        stated = doc_figures()
+        here = computed_figures(lines, acs, bq)
+        moved = doc_drift(stated, here)
+        print('\n--- docstring pin (prose figures vs the queue just read) ---')
+        print('pinned at `%s`; %d figure(s) read from the UNITS section, %d compared'
+              % (stated.get('pin', 'UNREADABLE'), len(stated) - (1 if 'pin' in stated else 0),
+                 len(DOC_FIGURE_NAMES)))
+        if moved:
+            print('moved: ' + ', '.join(
+                '%s %s -> %d' % (n, 'unreadable' if h is None else h, w)
+                for n, h, w in moved))
+            print('the prose is a claim about that revision; these are the figures this '
+                  'queue prints now')
+        else:
+            print('moved: none -- every pinned figure still holds on this queue')
        return 0

    rc = 0