Skip to content

census(spec): how many bare-path citations in packages/spec/src/** docblocks name a file that exists NOWHERE in the tree — the 2,635-span axis the gate pins and deliberately declines #17591

Description

@os-litant

Filed by the 分诊 seat while grading #17578, which is this card's one confirmed member. ⛔ Unassigned; this is the census, ⛔ not a gate and ⛔ not a cleanup.

The question

packages/spec/src/** comment prose cites in-repo files as bare path code spans — a filename or package-relative path with no line number (component-props-union-arm.test.ts, contracts/realtime-service.ts). Those spans are deliberately unjudged by the existing gate.

How many of them name a file that exists nowhere in the tree?

⚠️ That number is currently unknown, and it is the number that decides whether anything further is worth building.

Why it is not already answered

scripts/check-spec-docblock-symbol-anchors.mjs measures and pins the axis, then declines it on purpose (measured on origin/main @ abc4b83ce8b01d4e5af3560a0547421f6f5ca98f, 2026-09-11T00:5xZ):

barePathSpans:              2635
barePathsTrackedAtRepoRoot:  346
:87  "judging every bare path code span here produces **2,290** findings"
     ⇒ registered with `checkBarePaths: false`

The scope call is correct and this card does not reopen it. A gate red with 2,290 findings on day one is a migration, not a gate — the permanently-red-verifier shape this repo has retired before.

⚠️ But 2,290 is "unbindable", ⛔ not "wrong". The overwhelming majority are abbreviations of real files: a human or agent who searches finds them. The subset that matters is the one where searching finds nothing — a reader burns the search and ends with no answer, or trusts the sentence and never checks.

⇒ unbindable ≠ dead. The dead subset has never been counted.

Scope — one number, then stop

  1. For every bare path code span in packages/spec/src/** comment prose, ask the cheap question the existing gate does not: does a file with that basename exist anywhere in git ls-tree -r --name-only origin/main? ⚠️ A path listing, ⛔ not a content grep — #17578 is the worked example of why: git grep -F returns 1 hit for the dead name and that hit is the claim itself, so a content grep reports the reference as live.
  2. Report three numbers: spans examined, basename-resolvable, basename-resolves-nowhere. Pin the arithmetic (resolvable + dead == examined) in a self-test, the way judged + declined == comment-prose population is already pinned.
  3. List the dead ones with their sites.
  4. Stop there. Whether this earns a gate, a ratchet, or a one-off cleanup depends entirely on number 3 — 「失效修法按序取」, and a check is the last rung, not the first.

⛔ Explicitly out of scope: fixing the dead references, changing checkBarePaths, touching judgeUntrackedLineAnchors, and any packages/spec source edit at all. This card produces a measurement.

The seed, and its shape

#17578 (closed not_planned — three classes out as a standalone prose defect, and reopening is free if this census says otherwise): packages/spec/src/ui/component.zod.ts:1179 says

`component-props-union-arm.test.ts` pins it from this side.

git ls-tree -r --name-only origin/main | grep -c 'component-props-union-arm'  → 0
git grep -n -F 'component-props-union-arm' origin/main                        → 1  (the claim itself)
lit controls, same corpus:  state-machine.test.ts ✓   view-union-diagnostics.test.ts ✓

⇒ one confirmed dead bare-path reference, in a published file (@objectstack/spec's files[] admits src/**/*.zod.ts), pointing at a guard that does not exist.

Dedupe

Run against the 582-issue open objectstack board, 2026-09-11T00:5xZ.

What this card does NOT claim

Refs: #17578 (seed, closed) · #17242 (the other axis) · scripts/check-spec-docblock-symbol-anchors.mjs (the pins this reads) · PR #17576 (open — carries the replacement target union-author-message-pins.test.ts, which does not exist on main yet)


Generated by Claude Code

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions