chore(devx): measure the #6635 partial-retirement-annotation signal over the repo

[os-help]

Part of #6635 — this is the measurement the card was re-scoped to, not the gate. Merging it does not close the card: the decision branch is the maintainer's, per the ruling.

What this is, and what it deliberately is not

The maintainer ruling of 2026-08-09 changed what this card is, verbatim:

Maintainer ruling (2026-08-09): measurement first — no gate is built yet. pm:queue, as a measurement card.
The dispatchable deliverable is the #5757-pattern measurement, not the gate: run the proposed signal (a retired symbol whose retirement issue number appears in SOME but not ALL of its mentions within one file) over the whole repo once and report — total hits, true-positive/false-positive split (spot-verified), and the exemption count a warning-tier rule would need on day one. Decision rule recorded now: FP burden controllable (exemption count in the low tens or fewer, no structurally-legitimate partial-citation class) ⇒ the gate lands at warning tier in a follow-up PR; FP burden structural ⇒ this card closes not planned with the numbers as the record. ⛔ The measuring dev does not decide — a needs_decision report with numbers is the success outcome, exactly as #5757's was.

So: no gate is wired here, and no existing gate's behaviour changes. Two files, both new — a one-shot measurement instrument and its audit record. The instrument is committed only so the numbers are reproducible rather than asserted.

It is named measure-* rather than check-* / gen-* on purpose, so the #4203 script ledger has nothing to classify. Verified rather than assumed: pnpm --filter @objectstack/spec check:generated --reconcile-only is green and does not list it.

The numbers

Measured at origin/main bf32d4a0ec1cebca4f636b26c040ad6903c54287. main takes roughly 18 merges a day, so the numbers belong to that sha.

Positive control first — the scanner is proven to see before any number is believed. The specimen fixes landed before this measurement, so the control was rebuilt from history:

tree	packages/spec/src/shared/retry-policy.zod.ts
4e271b2c6 (the #6630 fix commit's parent)	FLAGGED — ETLPipeline, cited at L30 (#6414), bare at L81 and L133
bf32d4a0e (origin/main)	clear — 0 hits

That is #6630 reproduced mechanically, red before the fix and green after it.

Total hits: 197, across 65 files (all tiers, no exclusions). Stable under window choice: 184 hits at plus/minus 3 lines, 179 at plus/minus 6.

True/false-positive split: 34 hits hand-verified, 0 true positives, 34 false positives. Every hit in the residual set below was verified exhaustively (20/20), plus 14 more drawn one-per-class to cover each structural class.

Exemption count a warning-tier rule would need on day one. Building the most generous structural exclusions into the rule itself — drop the bare-key tier entirely, path-exclude every record surface:

rule shape	hits	files
all tiers, no exclusions	197	65
tier A+B only	141	51
tier A+B, record surfaces excluded	20	16
tier A only, record surfaces excluded	8	5

All 20 were hand-verified and all 20 are false positives — every warning the best-case rule emits on the current tree would need an exemption, against zero true positives.

The part the ruling said would flip the decision

The ruling's decision rule turns on whether a structurally legitimate partial-citation class exists. Five were found; in each, annotating every mention would make the prose worse:

1. The retirement ledgers themselves (62 hits / 2 files). RETIRED_DEFS_BY_MAJOR's entries are bare string literals — 'ui/I18nObject', — that can never carry an issue number, and the D2/D3 evidence strings enumerate the retired names by design.
2. Retirement pin tests. A removal's pin test asserts the name is gone; the name must appear bare, once per assertion. The repo requires this genre of every retirement.
3. Migration guides with a "Before" specimen — the retired shape must be spelled out un-annotated or the guide teaches nothing.
4. Changelogs, changesets and generated projections (74 hits / 34 files), historical by construction.
5. Annotated header plus enumeration stanza — the repo's own correct pattern (system/http-server.zod.ts L198-215 is the model): a header carrying the issue number, then a table naming one retired shape per row.

Two further inputs that price the gate

• Recall bound. [finding][spec] #6414 retired the L2 ETL layer, but retry-policy.zod.ts still teaches ETLPipeline.retry as a live surface in six places — including the retryDelayMs tombstone an upgrading author actually reads #6630 landed in two parts; the signal catches part 1 (PR fix(spec): stop teaching the retired ETL layer as a live retry surface (#6630, part 1) #6701) and structurally cannot catch part 2 (PR fix(spec): stop teaching the retired ETL layer as a live retry surface in flow.zod.ts (#6630, part 2) #6753) — one mention, phrased as prose rather than as the symbol name. It is also blind to the pure-miss case where no mention was annotated at all, which is the more common shape of a missed retirement.
• There is no machine-readable retirement-to-issue mapping in the repo, and a gate needs one as data. Parsing the registry comments is wrong in two silent ways: it picks the wrong number when a comment names several (the transform trio's header reads "The first entries since build-schemas.ts 检查 (b) 用叶名匹配 conversion surface —— 无关簇的 .type 就能让一个 tombstone 冒充「已登记迁移」 #4659 built this table (shared/mapping.zod.ts 的 javascript 变换 describe 推荐 dialect="js",而 ExpressionDialect 只有 cel/cron/template —— 照着写会被拒 #5552)" — build-schemas.ts 检查 (b) 用叶名匹配 conversion surface —— 无关簇的 .type 就能让一个 tombstone 冒充「已登记迁移」 #4659 built the table, shared/mapping.zod.ts 的 javascript 变换 describe 推荐 dialect="js",而 ExpressionDialect 只有 cel/cron/template —— 照着写会被拒 #5552 is the retirement), and it cannot see repo boundaries (objectui#3829 / objectui#3818 are indistinguishable from local numbers once the prefix is dropped). The mapping in the instrument is hand-curated and stated explicitly so it can be audited.

Full detail, including the per-class breakdown and reproduction commands: docs/audits/2026-08-partial-retirement-annotation-signal.md.

Verification

• node scripts/check-nul-bytes.mjs — OK, 6606 text files, no raw ASCII control bytes.
• pnpm --filter @objectstack/spec check:generated --reconcile-only — green, 20 check: + 14 gen: scripts all classified; the new script is correctly not among them.
• Positive control and window-sensitivity runs as tabled above.

No changeset: the PR adds a repo-internal measurement script and an audit record, and releases nothing. Labelled skip-changeset.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 10, 2026 2:15am