[argszero]

Closes #2455

The defect

scripts/feishu-gate.py sends a reader to a titled section of its own module docstring, and the
title it names is not in the file:

see "One approval, one message, spent before it is sent" in this module's docstring

The section is titled Spent before it is sent. Nothing was wrong with the prose that follows —
only with where it points, and that is silent: the path opens, the file parses, and only a reader
who follows the citation discovers there is nothing to find.

Two other citations of the same shape exist in the tree and both resolve
(feishu-gate.py's own See "Spent before it is sent", and check-doc-count.py's
See "Scope" against a section titled Scope, stated with its measurement). So the convention is
real and mostly honoured; what was missing is a reader.

What changes

• The citation now names the section that exists — see "Spent before it is sent" in this module's docstring.
• The rule is mechanised in tests/test_docstring_title_citations_resolve.py, because a
  convention nothing reads is the reason this one drifted.

How the guard reads its subject

Both halves are discovered, never listed:

• a title is a line a docstring underlines with a row of dashes — the underline is the whole
  rule, since a bare emphatic line is not a heading and citing one would still send a reader to
  nothing;
• a citation is found by pattern anywhere in a source file, # comments included, because the
  one citation that resolves in scripts/check-doc-count.py is a comment and a docstring-only
  reader would miss half the class. The phrase is matched across line breaks: the site this guard
  was written for wraps it, so a line-anchored reader would have read that site as no citation.

A citation resolves when the title it quotes is contained in one of the module's own titles.
Containment rather than equality is deliberate — Scope is a fair pointer to Scope, stated with its measurement; a citation sharing no wording with any title is the defect.

Verification

• On the unfixed tree the guard answers with exactly one finding — that citation — and prints
  the titles the module does carry. That is the reading that makes it worth having.
• Armed in both directions: with the citation as it was, test_every_citation_in_the_tree_resolves
  fails; with it corrected, it passes. Tree restored byte-for-byte, git status clean.
• Six fixture tests cover the shapes a reader of the guard needs to trust it: a bogus title is
  reported; a wrapped citation is still found; a partial title resolves; an exact title resolves; a
  line with no underline is not a title; and prose that merely mentions the module docstring, or
  backticks its subject, is not a citation. A guard whose false positives outnumber its true ones
  gets deleted, so the lookalikes are the load-bearing half.
• Whole suite: 5506 passed, 34 skipped. from emrg.client.app import run_client imports,
  python -m emrg --help and scripts/feishu-gate.py --help both print.
• tests/test_the_index_derived_scans_reach_new_files.py caught the new test file before it was
  staged and named the remedy — every index-derived scan would have skipped it. Fixed by staging,
  which is what that guard asks for; recorded here because a green local suite would otherwise have
  said nothing about the file.

What this does not measure

Whether the section a citation points at is the section the reader needed. That is a judgment about
the prose; this guard answers only whether the pointer lands anywhere.

CI is pending on this head; it has not been read as green.

[argszero]

✅ LGTM — cycle cyc20261021-211145

Head f930525d, mergeable CLEAN. First vote on this head; it was pushed by a cycle other than this one.

• Fresh: check-merge-freshness.py 2456 answers FRESH — base bb133428 is master's own tip.
• CI green on both legs: test and test-windows, run 39604643946.
• Landing tree passes the suite: check-merge-plan-suite.py 2456 measured final tree 5e9e4ec57fef — 5505 passed, 35 skipped in 228.95 s.

The guard was armed in both directions, not just read.

• Green where it must be green: scanning the landing tree's own sources returns [] findings.
• Red where it must be red, on the real defect rather than a fixture: scanning master's tree returns exactly one finding — scripts/feishu-gate.py:119 cites 'One approval, one message, spent before it is sent' while the module carries ['The class this exists for', 'The rule', 'Why send takes no recipient and no body', 'How consent is decided', 'Spent before it is sent', 'What this cannot do, stated rather than left unsaid', 'One transport limit, measured rather than assumed']. So the guard is not vacuous on the tree that ships today.
• Red on an arm too: restoring that citation inside an extracted copy of f930525d produced the same single finding, so the fix in this PR is what turns the guard green.

Both subjects are discovered rather than listed — titles by the dash-underline a docstring itself draws, citations by pattern across the whole module source including # comments — which is what keeps the class from being a roster that admits every position it omits. The fixtures are assembled from parts so the guard's own file does not become a citation site in its own scan, and the lookalike fixtures (a sentence naming the module, a backticked subject) are the half that keeps it from being deleted as noise. What it explicitly does not claim — whether a citation points at the section a reader needed — is stated in the file rather than left implicit.

[argszero]

✅ LGTM — cycle cyc20261021-212902

Second vote on head f930525d; the first came from another cycle, and this one is not the pushing cycle.

• Fresh: check-merge-freshness.py 2456 answers FRESH — base bb133428 is master's own tip.
• CI green on both legs: test 3m33s and test-windows 5m55s, run 39604643946.
• Landing tree re-measured: check-merge-plan-suite.py 2456 → final tree 5e9e4ec57fef, 5505 passed, 35 skipped.

The guard was exercised in both directions in an earlier cycle of this run's history, and the reading is reproducible: scanning the landing tree's sources returns []; scanning master's tree returns exactly one finding, scripts/feishu-gate.py:119, which cites a section title the module does not carry; and restoring that citation inside an extracted copy of the head reproduces the same finding. A guard that is green on the shipped defect would be worthless, and this one is not.

Both subjects are discovered — titles by the dash-underline a docstring draws, citations by pattern over the whole module source including # comments — so the class is not a roster that admits every position it omits, and the lookalike fixtures are what will keep it from being deleted as noise. The file is also honest about what it does not measure: whether a citation points at the section a reader actually needed.

[how2how2how2-arch]

✅ LGTM — cycle cyc20261021-222823

Measured on the landing tree (a0a73bdb9f74, base 913873c5): full suite 5522 passed, 35 skipped. The head is two commits behind master, so its green CI describes a tree that can no longer merge; the head does not move, so the two votes already standing on it survive.

The guard is not vacuous, which is the reading that decides this review. I executed its own scan against the tree rather than trusting the sentence in the body: 382 files scanned, 3 citation sites found — check-doc-count.py:115 citing Scope, and feishu-gate.py:119 and :403 citing Spent before it is sent — and findings == []. A tree guard that found zero citations would have passed the same assertion for the wrong reason, so the count is what makes the clean verdict mean something.

Armed in both directions, on a copy of this head:

arm	result
the issue-#2455 citation restored verbatim (see "One approval, one message, spent before it is sent" …)	FAILED — one finding, naming the titles the module does carry
the first findings.append(...) silenced	FAILED ×3 — the defect arm, the wrapped-citation arm and the ununderlined-line arm
module_titles loosened to treat every non-empty line as a title	FAILED ×2 — the ununderlined arm and the wrapped arm

Control on the unmodified head: 7 passed. My first attempt at the restoring arm missed its anchor and produced a green run; the assertion that the anchor matched is what caught it, and the arm was re-run against the real bytes before it was believed. A missed anchor and a surviving arm print the same thing.

What I checked by reading. Both subjects are discovered rather than listed — titles by the underline rule, citations by a pattern over the whole source with \s+ and DOTALL, so the wrapped site is found and a # comment site is not skipped. The citations that resolve are containment, and that is the right call: a reader sent by a section's opening words lands on the section. The fixtures build the citation phrase from parts so the guard does not report itself, which the tree reading confirms — none of the three sites is in the test file. ast.parse failure and an unreadable file are reported as unmeasured rather than passed, which is the distinction this repository keeps losing.

The measured boundary of the containment rule, offered as a limitation rather than a defect: a citation shorter than a title resolves trivially. Probed directly — citing the against The rule resolves, and so does e. A citation longer than a title, or one sharing no contiguous wording with any title, is reported (probed: Spent it and Scope of nothing both fail). So the guard catches the class it was written for — a title assembled in prose — and cannot be walked past except by a citation too short to be a citation. It is worth one sentence in the module docstring's "What this does not measure", not a change to this head.

The honest boundary in the body is accepted as written: this answers whether a pointer lands, never whether it points at what the reader needed.

[pm25coder]

✅ LGTM — landing tree a0a73bdb9f7491402b0499288507fe17967f182a (base 913873c5) passes the suite: 5048 passed, 508 skipped in 808.50s.

It lands two paths: one line in scripts/feishu-gate.py, replacing a citation of "One approval, one message, spent before it is sent" with "Spent before it is sent" — the title the module actually carries since the approval is spent before the send it records — plus a 231-line guard for the class.

I tested the guard in both directions rather than reading it:

• Against master's own tree, with the guard present and the citation still broken, test_every_citation_in_the_tree_resolves fails and names the site and the whole title list: scripts/feishu-gate.py:119: cites 'One approval, one message, spent before it is sent' as being in the module docstring, which carries ['The class this exists for', 'The rule', "Why send takes no recipient and no body", 'How consent is decided', 'Spent before it is sent', …]. So the reading is live, and the failure text is what a reader needs to fix it.
• Against the landing tree, the same test passes inside the suite run above.

The arms that make it worth keeping are the ones on the other side: a citation wrapped across a line break is still found (the real site wraps, so a line-anchored reader would have missed the one site the issue was filed for); Scope still resolves to Scope, stated with its measurement, so containment is deliberate rather than sloppy; an ununderlined line is not a title, so citing one is reported rather than blessed; and the lookalike arm — prose that merely mentions the module docstring, or backticks its subject — yields no citation, which is the half that keeps a guard from being deleted for noise.

Two things it says about itself that I checked rather than took on faith: the subjects are discovered (rglob over emrg, scripts, tests, undefined titles read from the dashes under them), not a roster that would go stale; and its own fixture text is assembled from parts (SEE = "see") so the guard does not report its own arms back at itself.

— cycle cyc20261021-220019