fix(scripts): the citation extractor reads hyphen-suffixed, slash-joined and URL-spelled citations, pinned in one spelling table

[objectstack-fleet]

Fixes #20636
Clause-②: no

The family closeout for the citation extractor in scripts/check-issue-citations.mjs: every spelling a seat measured as invisible to the diff gate and the census is now read, every exclusion keeps only the shapes it was measured protecting, and the self-test carries the one enumeration table the triage asked for (48 spellings, each "extracted as" or "not a citation, because"). Landing site: scripts/check-issue-citations.mjs only. scripts/check-doc-authoring.mjs is untouched; H2 below says why.

What changed

• Hyphen after the number. The lookahead no longer refuses a -, so #13398-class, #5347-A and ui#6206-B read as citations of their number. It still refuses a word character, so a hex colour stays out.
• Slash before the #. A / is now valid context before a bare #. It stays refused only before a qualifier candidate, so a URL path fragment such as https://example.com/docs/page#12 never reads page as prose. A / right after a digit is the exception, so #3076/objectui#2614 still reads its own qualifier.
• Slash-joined continuation. In #A/#B, the second number takes the chain head's reading: bare after a bare or prose head, the head's repository after a qualified head, and an ordinal after an ordinal. Only a joined / continues a chain. objectui#1 / #2 and objectui#1 + #2 stay two separate readings.
• URL spelling. https://github.com/OWNER/REPO/issues/N and .../pull/N are now citations, qualified by their own OWNER/REPO. That puts objectstack-ai/framework in this repository and makes every other repository's URL cross-repo, never a finding. Inside a markdown link [#N](URL), the citation counts once.
• Head rows. I retired re-charter, clause and option (named in the thread), plus acceptance and the section mark (found by the same measurement). Each protects 0 sites repo-wide at two or more digits and hides board citations. The grammar's two-digit floor already keeps one-digit ordinals out. I added a ]( row, the narrower guard the hyphen exclusion leaves behind for markdown in-page heading anchors.
• Self-test.
  • A new spellings battery (56 cases) reads the table row by row.
  • Every head row must excuse at least one table row, and every required spelling (the card's list plus the thread's) must be present.
  • The live-corpus battery gains three floors, one per new arm, each counting only a number spelled once on its line.
  • The roster floor rises from 6 to 9 batteries.
  • Total: 114 cases in 8 batteries became 173 in 9.
• I edited the header in place and kept its line count, because scripts/pm/dispatch-gates.mjs's self-test pins scripts/check-issue-citations.mjs:204 local-env. The marker is still on line 204, and that pin passes (see Gates).

H1: what each exclusion protected and hid

Measured on 3693a1b50 over the declared surfaces. Every arm was judged against one enumerated board: 188 pages, frontier 20959, 2026-09-30T22:55Z. The instrument mirrors the gate's extractor and matched it file for file on all 2,640 files (0 mismatches).

exclusion	hid (sites, dead)	protected in the declared surfaces	disposition
hyphen after the number	58, 1 dead (8 cross-repo)	0: no numeric range, slug or hex-like token. Repo-wide: in-page heading anchors, 16 lines in docs/design/** and skills/**, plus one range, docs/audits/...md, whose first number is a citation	dropped; the ]( row keeps the anchor out
/ before the #	528, 10 dead: 523 #A/#B second numbers and 5 TOKEN/#N such as ADR-0049/#1888	0 paths and 0 URL fragments	narrowed to the candidate arm; continuations read as their chain
head re-charter	0 left on this tree (the 26 dead re-charter #13135 were rewritten by PR #20750)	0; only the gate's own fixtures used it	retired
head clause	0 in the surfaces; 4 in deferred test files, all board citations	0	retired
head option	1 (option #14088, live); 1 more under scripts/**	0	retired
head acceptance	1 (the silent acceptance #6132 closed, live)	0 at two or more digits	retired (in-place, below)
head section mark	0 in the surfaces; 4 in test files (§6 #11176's decisions)	0 at two or more digits	retired (in-place, below)
heads kept	none measured hiding a citation	directive 203 (max 13), PD 85 (max 13), batch 276 (69 distinct, 11 to 227), OQ 10, PKCS 1	kept

The 8 slash chains headed by another repository are not a case where the two populations cannot be told apart. The 5 on objectui's public board each name objectui's record, the issue and then the pull request that fixed it, read one by one against both boards:

• objectui#2715/#2717
• #2711/#2722
• #2725/#2732
• #2967/#2904
• #4648/#4901

This repository's records with the same numbers are unrelated. The other 3 (cloud, hotcrm-heimao) are boards one credential cannot read, so they stay unjudged, as they were before.

H2: where the URL spelling belongs

The extractor. At 3693a1b50, 57 URL sites sit in the gate's projection: 56 in package comments and 1 link on a release page. 4 of them are dead. Only 2 URL sites in package sources are inside string literals, both internal note: strings in packages/runtime/src/route-ledger.ts.

check:doc-authoring asks a different question: may a runtime string carry a tracker reference at all? It reads string literals, skills and spec refusal messages. The two projections are disjoint, so adding the URL to the extractor double-counts nothing there. Inside the extractor, the one double-spelled site ([#15325](.../issues/15325) on v17/17-3.mdx) counts once. check-doc-authoring.mjs is not touched.

H3: open PRs' added lines

All 13 open PRs at 2026-09-30T23:2xZ: their heads were fetched into a private ref namespace (deleted afterwards). For each, the BASE extractor and this one were run over the lines it adds, against its merge base. Result: 85 added-line citations under both extractors, 0 newly extracted, 0 lost. No PR's verdict changes. Lines a PR does not add are never judged, which is unchanged and pinned in the diff-scope battery.

Census, before and after

The gate's own --census --json, once with the 3693a1b50 script and once with this one, over the same tree:

	judged	resolves	resolves as PR	cross-repo	allocated-but-absent
before (frontier 20965)	37,152	33,403	1,985	1,024	740
after (frontier 20966)	37,796	33,917	2,083	1,041	755

That is 644 more judged sites and 15 more dead ones, with 0 findings lost. By arm: hyphen 1 dead, slash 10 dead, URL 4 dead.

Newly visible dead sites per lane. I rewrote none of them; they belong to the lane cards:

• dead tracker citations in the domain:cli packages (689 sites, 166 numbers, 95 files): the ruling C+D stage for this lane (from #20556) #20594 (domain:cli): 1. packages/rest/src/rest-server.ts:7456, [裁决] MetadataProtocol 是否应声明 publishMetaItem 成员 —— 半声明的门（响应已声明、请求未声明） #11006.
• dead tracker citations in the domain:engine packages (645 sites, 160 numbers, 104 files): the ruling C+D stage for this lane (from #20556) #20595 (domain:engine): 6.
  • driver-sql: sql-driver.ts:3933 (URL, driver-sql: the $contains MEMBERSHIP spelling on any multi-valued / JSON column is a DATABASE_ERROR 500 on live PostgreSQL (SQLSTATE 42883, operator does not exist: json ~~ text) — it has only ever been executed on SQLite #17590), :12110 ([finding] 15 more PASSING @objectstack/runtime tests print the same refused a read on feature — 134 lines after #10380 quiets its two, led by notifications.hono.integration.test.ts (52) #10629), :16106 (driver-sql: a multiple: true BOOLEAN column loses its $contains membership filter — the #14079 type-gate compiles it to 1 = 0, where the same shape on a multiple: true number keeps its GLOB #17343).
  • metadata: loaders/ambiguous-metadata-stem.ts:40 ([finding] Two residual audit ↔ router asymmetries after #14123: the audit's third source is loadMany while the router's is load by name, and unboundDeclarations still reads two sources where the undeclared-handler half now reads three #14423).
  • metadata-protocol: migrations/partial-index-probe.ts:395 (Raw-exec consumers that surface error.message as an operator-facing detail now read the composed DATABASE_ERROR sentence — read cause there (follow-up to #16019) #16657).
  • objectql: plugin.ts:1496 ([finding] 15 more PASSING @objectstack/runtime tests print the same refused a read on feature — 134 lines after #10380 quiets its two, led by notifications.hono.integration.test.ts (52) #10629).
• dead tracker citations in the domain:services packages (629 sites, 112 numbers, 152 files): the ruling C+D stage for this lane (from #20556) #20596 (domain:services): 0.
• dead tracker citations in the domain:spec packages (84 sites, 21 numbers, 23 files): the ruling C+D stage for this lane (from #20556) #20597 (domain:spec, packages/lint): 0.
• packages/spec/src: 1,277 comment lines still cite 170 deleted tracker numbers (1,295 sites) — the staged remainder of ruling C+D on #19123, measured by PR #20226 #20234 (packages/spec/src): 7.
  • data/datasource.zod.ts:701 (mongo config.options.auth.password is a fourth spelling of an inline credential — authorable, persisted cleartext, unredacted, and read by the client #9040).
  • data/filter.zod.ts:1040 (URL, driver-sql: the $contains MEMBERSHIP spelling on any multi-valued / JSON column is a DATABASE_ERROR 500 on live PostgreSQL (SQLSTATE 42883, operator does not exist: json ~~ text) — it has only ever been executed on SQLite #17590) and :1042 (URL, driver-memory: the stored-ARRAY value axis is still unrepaired outside the equality arm — $in/$nin, the text family and the ordering family answer one filter two ways, and the two exclusion arms answer it in the WIDENING direction #17286).
  • data/value-roundtrip-conformance.ts:100 (URL, [finding] driver-sql's SQLite json codec is not round-trip faithful for a string whose content is valid JSON — '123' reads back as a number, and Postgres does not agree #12380).
  • ui/component.zod.ts:593 and :669 (element:record_picker 的 sort / limit 扁平简写:renderer 兑现、schema 未声明(#5775 实施中新测出,A 表之外的第 7 处) #6276), and :3771 ([finding] page:tabs items[].icon is the exact sibling of #9881 — live objectui reader, no .describe(), no accept-pin #9972).
• Release pages (domain:devx, no lane card): 1. content/docs/releases/v17/index.mdx:168 ([finding][drivers] 五个驱动的 find/count/… 仍声明 query: QueryAST，而调用方已可省略 object —— 双变让它编译，但声明开始说谎 #6075).

This census was run on the PR head's tree, not after landing. A re-run after landing reads the same corpus plus whatever main has gained by then.

In-place fixes beyond the three named rows

I retired the acceptance and section-mark rows here rather than filing them. All four conditions hold:

1. They are the same defect class as option and clause: a head row hiding a board citation.
2. The fix is mechanical, and the shape is pinned by the table.
3. The file is this claim's own surface (NON_CITATION_HEADS).
4. The same gate's self-test covers them, so no new verification surface is added.

Evidence: acceptance #6132 (live) in packages/formula/src/cel-pushdown-limits.ts:82, and the section-mark sites in deferred test files. Neither row has any two-or-more-digit ordinal anywhere in the repository.

Gates (final head 25d96fcc0)

I re-derived the list with node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack, which gave 32 commands. The same derivation on a throwaway tree at origin/main (05be35259) with this diff applied gave an identical list. I ran all 32, plus pnpm check:doc-authoring and the self-test, and every one exited 0. Reconciliation verdict line:

✓ dispatch-gates --ran: 32 derived famil(ies) accounted for — 32 run, 0 NOT-MEASURED (a DERIVED zero — all 32 recorded an exit code and none of them is 3).

Verdict lines worth quoting:

• node scripts/check-issue-citations.mjs --self-test: ✅ ... every spelling enumerated ... (173 cases, 9 batteries). It also passes on origin/main 05be35259 with this diff applied.
• node scripts/check-issue-citations.mjs (diff mode): ✅ check-issue-citations: no issue citations added against 3693a1b50 (0 file(s) read). The script lives in the deferred scripts/** surface.
• pnpm check:pm-dispatch-gates: ✓ dispatch-gates self-test: 1976 cases pass. (1237.9s). Its pin scripts/check-issue-citations.mjs:204 local-env holds.
• pnpm check:doc-authoring: ✓ doc authoring guard: ... hold the baseline — 549 pinned site(s).
• pnpm check:nul-bytes: check-nul-bytes: OK (scanned 9582 text file(s) ...).
• node scripts/check-scripts-symbol-anchors.mjs: ✅ ... 3706 anchors across 282 scripts resolve.

Ablations (one-shot, from committed 25d96fcc0, via scripts/ablation-replace.mjs)

Every leg was expected to go red, and every leg did. Each one restored to blob c732ce2e21c7 (equal to HEAD) with an empty git diff HEAD. No permanent ablation file is left.

mutation	first red
hyphen refused again after the number	the live corpus must yield a #N-word citation
/ refused again before the #	the live corpus must yield a slash-joined #A/#B second number
URL arm disabled	the live corpus must yield a URL-spelled citation
option head row restored	spelling option #N in "the option #14088 gave" must read #14088; got nothing
continuation disabled	spelling repo#A/#B ... must read objectstack-ai/objectui#2711, objectstack-ai/objectui#2722
]( row disabled	a markdown link's in-page heading anchor is not a citation
link de-duplication disabled	spelling [#N](URL) ... must read #15325

The first slash ablation, run before the floors were tightened, went red in the table but left the live-corpus continuation floor green. A line citing the same number twice let a plain citation stand in for the slash-joined one. Commit 25d96fcc0 makes each new floor count only a number spelled once on its line. The re-run above is red at that floor.

Acceptance notes

• URL spelling in runtime strings. check:doc-authoring does not read it. At 3693a1b50 the population is 2 internal route-ledger note: strings (packages/runtime/src/route-ledger.ts:459, :465), and no author-facing door shows them. Noted, not filed; carrier: none.
• Range second numbers. In a range such as #712-714, the second number carries no # and is not read. There is 1 site repo-wide, in docs/audits/**, outside the declared surfaces. Pinned in the table with its reason.
• Dormant test-file citations. The 8 test-file citations the retired clause and section-mark rows hid are in the deferred test surface. They become visible only when that surface is swept.
• Line-number pin. dispatch-gates.mjs pins this file's local-env marker by line number (:204), so any future header growth above it has to move that pin in the same PR.

No changeset: a root scripts/ file publishes nothing (the root package.json is private, and no package's files ships scripts/), so this PR takes skip-changeset.

---

Generated by Claude Code