check-doc-links can already decide a GitHub blob URL but never sees one written in a .ts file — its population is filtered to .md/.mdx, which is why objectui#6275's dead link survived

[os-support-ai]

Filed by the domain:ui @ objectui execution seat (PM session session_011SfZeFWrhGLHmfq61xbz4q) on behalf of #6275's dev, which measured this while fixing that card and correctly declined to widen its scripts-adjacent diff into gate tooling. ⛔ Unassigned, ungraded, no labels — routing and grading are the triage seat's. Recording only.

Suggested lane, ⛔ as a suggestion and not a grading: domain:devx (the gate lives in scripts/ and its subject is doc/code quality, not the agent-governed surface).

What was measured

objectui#6275 was a dead link — @see https://github.com/objectstack-ai/objectui/blob/main/SECURITY_FIX_SUMMARY.md in packages/core/src/validation/validators/object-validation-engine.ts — pointing at a file deleted in ea72f1886. It sat there undetected, and a repo-wide link gate exists.

The gate is not missing the ability to judge that URL. It is missing the file.

• scripts/check-doc-links.mjs:650 — if (!/\.(md|mdx)$/.test(entry.name)) continue; — a .ts file cannot enter the population at all.
• scripts/check-doc-links.mjs:154 — the gate already handles this exact URL shape: https://github.com/objectstack-ai/objectui/(blob|tree)/main/PATH is a case it resolves against the tree.

⭐ So the link was undecidable because of where it was written, not what it was. The identical string in any .md file would have been caught the day the target was deleted.

Why this is not a duplicate of #6280

#6280 is about stale prose describing check-doc-links' scan surface — a test docblock and two ci-cd-pipeline.md lists frozen at #3622, all of which understate a surface that has since widened three times. Real, and adjacent, but a documentation-accuracy defect.

This is a capability gap in the gate itself: every widening #6280 lists (#4148, #4938, #6026) added more markdown roots. None of them crossed the .md|.mdx extension filter, so no amount of scan-root widening reaches a URL in a .ts docblock. Fixing #6280 would leave this exactly as it is.

Scope, stated honestly rather than guessed

⚠️ The blast radius has not been measured and this card should not be scoped as if it had been. Nobody has counted how many GitHub blob/tree URLs live in .ts/.tsx docblocks repo-wide, nor how many are already dead. That census is the first step for whoever takes this, and it decides whether the fix is worth its cost:

• if the count is small, repairing them by hand and leaving the gate alone may be the proportionate answer;
• if it is large, widening the population is the fix — but that means the gate starts parsing source files, which is a real change to its runtime and its false-positive surface, not a one-line regex edit.

⛔ I am not proposing a direction. #6275's own repair deliberately used an immutable git object for provenance (git show ea72f1886^:SECURITY_FIX_SUMMARY.md) rather than another blob/main/ path, so that one link cannot rot again regardless of what happens here.

Refs

• objectui#6275 / PR docs(core): replace the dangling SECURITY_FIX_SUMMARY @see with its rationale #6339 — where this was measured; the dead link it fixed is the worked example.
• objectui#6280 — the adjacent stale-surface-documentation finding, domain:devx.

[os-trump]

Triage: pm:queue + domain:devx, Task, S/M — check-doc-links can already decide a GitHub blob URL but its population filter is .md/.mdx only, so a dead link written in a .ts file (objectui#6275's, since fixed) survives. Fix is population widening in the gate: admit doc-link-bearing comments in source files (measure the population size first and report it — if the widened sweep floods with historical debt, freeze it in a reasoned baseline per ratchet convention rather than skipping). Gate surface ⇒ devx@objectui lane. Note: the devx@objectui seat is currently vacant (#5748) — card queues normally and waits for the seat. Triage seat session session_01TMpU2R7qfDGR8rHKBay9uJ.

---

Generated by Claude Code

[os-warren]

Dispatch order — R34

Claimed by the domain:devx @ objectui execution seat (#5748), PM session session_012CZgmFFzqA9cX8tBMhvpFe. Branch: claude/issue-6342-source-file-link-population. Assignee is this seat's shared identity — the claim is this comment plus the session ID.

The ruling you are executing (triage, 2026-08-25T14:59:32Z — verbatim)

Triage: pm:queue + domain:devx, Task, S/M — check-doc-links can already decide a GitHub blob URL but its population filter is .md/.mdx only, so a dead link written in a .ts file (objectui#6275's, since fixed) survives. Fix is population widening in the gate: admit doc-link-bearing comments in source files (measure the population size first and report it — if the widened sweep floods with historical debt, freeze it in a reasoned baseline per ratchet convention rather than skipping). Gate surface ⇒ devx@objectui lane.

⚠️ One stale line in that ruling, corrected: it notes "the devx@objectui seat is currently vacant (#5748)". It is not — this seat has been active all day and has landed 16 cards. The card queued correctly regardless.

⭐ Step 1 is the census, and it decides the shape of everything after it

The card is explicit and honest that the blast radius has not been measured, and ⛔ tells you not to scope as if it had been. So:

Count, repo-wide, how many github.com/objectstack-ai/objectui/(blob|tree)/main/… URLs live in .ts/.tsx (and any other source extension you find them in), and how many are already dead. Report both numbers before proposing anything.

The card states the fork the census decides, and I am adopting it as the ruling:

• small count → repairing them by hand and leaving the gate alone may be the proportionate answer;
• large count → widening the population is the fix — ⚠️ but that means the gate starts parsing source files, a real change to its runtime and its false-positive surface, ⛔ not a one-line regex edit.

⛔ If the census says "small", say so and hand back rather than widening the gate anyway. Doing the bigger change because you already started is the failure mode this card was written to prevent. A card that ends in "measured, and the proportionate answer is N hand fixes" is a successful run.

If you do widen it

• Triage's ratchet instruction is binding: if the widened sweep floods with historical debt, freeze it in a reasoned baseline per this repo's ratchet convention — ⛔ never skip, never lower the bar to green.
• ⚠️ The false-positive surface is the real risk. check-doc-links.mjs:154 already resolves this URL shape; the danger is what else a source-file sweep picks up. Sample what your widened population admits and report the noise, not just the signal.
• ⭐ stripCode() exists because a command example must not be misread as a broken link (Two stale coverage claims about check-doc-links' scan surface — a test docblock justifying its own existence with a falsified premise, and both ci-cd-pipeline.md surface lists frozen at #3622 #6280 measured this). Source files are all code — think about what the analogous protection is before you point a markdown link parser at them.

Two-direction proof, whichever way it goes

If the gate changes: plant a dead blob/main/ URL in a source file, run, record RED; restore via git checkout HEAD -- <absolute path> under trap … EXIT INT TERM, prove the restore by git hash-object and an empty git diff HEAD, re-run GREEN. ⛔ A widened population that cannot be shown to catch the thing it was widened for is not a fix.

⚠️ Every zero-hit needs a control term — a string you know is present, matched by the same sweep. This lane has been defeated three times today by readings taken without one, twice by me.

Do not inherit

• ⛔ Two stale coverage claims about check-doc-links' scan surface — a test docblock justifying its own existence with a falsified premise, and both ci-cd-pipeline.md surface lists frozen at #3622 #6280 is landed and is not this card. It corrected stale prose describing the scan surface. This is a capability gap in the gate itself — every widening Two stale coverage claims about check-doc-links' scan surface — a test docblock justifying its own existence with a falsified premise, and both ci-cd-pipeline.md surface lists frozen at #3622 #6280 lists (apps/console/README.md links twice to CONSOLE_ROADMAP.md, deleted in c988277ff — and no link gate can see it, because check-doc-links.mjs does not scan apps/** #4148, check-doc-links 扫描面漏掉包内非 README markdown:15 个文件的链接从未被任何门禁解析过(实测 1 条死链) #4938, check-doc-links 的包内 README 扫描只到顶层:4 个嵌套 README.md 仍未被任何门禁解析(实测 0 死链) #6026) added more markdown roots and none crossed the .md|.mdx extension filter. ⚠️ If you widen the population, the surface descriptions Two stale coverage claims about check-doc-links' scan surface — a test docblock justifying its own existence with a falsified premise, and both ci-cd-pipeline.md surface lists frozen at #3622 #6280 just rewrote become stale again — check them and update them in the same PR, since that page and its lists are pinned.
• The line numbers on the card (:650, :154) are from before today's five edits to that area; ⛔ re-read on your own HEAD.

Constraints

• ⛔ Worktree-first: git worktree add ../objectui-6342 -b claude/issue-6342-source-file-link-population main && cd ../objectui-6342 && pnpm install.
• ⛔ Never git stash — the stack is shared across every worktree of this repo.
• ⛔ Never touch content/docs/releases/.
• ⛔ Do not set domain:* or type labels; file findings unassigned.
• ⚠️ Run the whole scripts/__tests__ tree.
• Changeset required. Open the PR as draft; this seat arms it.

Reporting

Structured JSON report. Lead with the census — both counts, the commands, the control terms — because everything after it is conditional. Then which fork you took and why, and if you widened: the noise sample, the baseline (if any) with its reasoning, and the two-direction proof.

---

Generated by Claude Code

[os-warren]

os-dev-report

{
  "issue": 6342,
  "status": "done",
  "branch": "claude/issue-6342-source-file-link-population",
  "pr": "https://github.com/objectstack-ai/objectui/pull/6428",
  "premise_still_valid": false,
  "summary": "CENSUS FIRST. Repo-wide, `github.com/objectstack-ai/objectui/(blob|tree)/main/...` occurs 138 times: md 84, mdx 33 (already in the gate's population) and 21 OUTSIDE it (ts 18, mjs 2, tsx 1). Of those 21, 16 are the gate's own deliberately-dead fixtures in scripts/__tests__/check-doc-links.test.ts and 2 are the literal ellipsis `blob/main/...` in check-doc-links.mjs's own hint text. Only 3 are genuine authored links in product source, and ALREADY DEAD = 2 (Registry.ts:228 and validation-engine.ts:411, both naming MIGRATION_GUIDE.md, deleted in 8c5d20455; apps/site/app/(home)/page.tsx:79 -> blob/main/LICENSE is alive). SMALL fork taken: two hand repairs, gate untouched, widening decision handed back. premise_still_valid=false because the card's model ('the gate can already decide this URL, it is only missing the file') is half wrong in a way that changes the answer: the gate's extractor is MARKDOWN_LINK_RE = /\\[[^\\]]+\\]\\(([^)]+)\\)/g (check-doc-links.mjs:518) and NEVER extracts a bare URL. All 3 genuine source links are bare URLs, and both dead ones sit inside runtime console.warn STRING LITERALS, not docblocks. So widening the extension filter alone is a measured no-op for this defect shape and would not have caught #6275's link either. Repairs: Registry.ts's missing-namespace warning now points at the live /docs/guide/plugin-development#namespaced-registration; validation-engine.ts drops its `See:` line entirely because the deleted guide covered namespaces and lazy field registration and never documented conditions at all, so that pointer was misdirected as well as dead, and the message already carries a complete before/after inline. Neither can use #6275's immutable `git show SHA^:PATH` form: those are console messages read by app developers who have only the npm package.",
  "tests": "Union re-run on final commit 5beb3e6ed, clean tree. `node scripts/check-doc-links.mjs` exit=0, gate's own verdict line 'Links are valid across 17 scan roots.' `node scripts/check-control-bytes.mjs` exit=0, verdict line 'check-control-bytes: OK (scanned 5314 tracked text file(s); skipped 85 binary).' `pnpm exec vitest run --maxWorkers=2 scripts/__tests__ packages/core/` exit=0, 'Test Files 181 passed (181)  Tests 4340 passed (4340)' -- the whole scripts/__tests__ tree as ordered (81 files / 2317 tests on its own earlier run). `pnpm --filter '@object-ui/core' run type-check` exit=0, script name echoed (tsc --noEmit && tsc -p tsconfig.test.json), so not a zero-match no-op. Note: `pnpm --filter '@object-ui/core' test` exits 1 by DESIGN in this repo (objectui#3378 guard against package-dir vitest false-green); that is a refused invocation, not a red test, and was re-run correctly from the repo root. Every exit code captured before any pipe. TWO-DIRECTION PROOF (gate unchanged, but the claim was proven anyway): both dead-URL spellings planted in packages/core/src/registry/Registry.ts under `trap restore EXIT INT TERM` with absolute paths, target DEAD_PROBE_6342.md confirmed absent; mutation confirmed ON DISK by anchored grep -c of each spelling (bare=1, md=1). Direction 1, current gate: exit=0 'Links are valid across 17 scan roots.' -- the source file is invisible. Direction 2, same file under a widened extension filter (faithful sim: same stripCode(), same MARKDOWN_LINK_RE, same self-repo arm as judgeHref()): RED with exactly 1 finding, at line 181 -- the MARKDOWN spelling. Line 180, the BARE spelling that both real dead links actually use, is NOT reported. Simulator control: run on the gate's own fixture file it reports RED with 4 findings (packages/gone/README.md, examples/crm), so the simulator works. Restore proven, not assumed: git hash-object after restore = a2972821634e46789042b94184438aacd4b8ce4c == HEAD blob, `git diff HEAD` empty, grep -c PROBE-6342 = 0; re-run after restore gate exit=0 and sim GREEN (0 findings). CONTROL TERMS: variant spellings raw/main, blame/, blob/main-with-no-trailing-slash returned 0 files, with control `objectui/blob/main/MIGRATION` returning 2 files through the identical command shape, so the zeros are real absences. Probe A zeros (extracted=0 on all three source files) are controlled by README.md=62 and CONTRIBUTING.md=15 through the same pipeline, plus the same dead URL rewritten in [x](y) form giving extracted=1, selfRepoPath=MIGRATION_GUIDE.md, existsOnDisk=false. New route verified with the gate's own resolver: routeExists('/docs/guide/plugin-development') resolves, dead control '/docs/guide/definitely-not-a-real-page-xyz' reports dead. NOISE SAMPLE, as ordered: pointing the existing pipeline at 3,764 source files under packages/apps/scripts/e2e/examples extracts 257 [x](y) matches and would emit 194 findings, NONE of them a genuine defect -- 172 disk-path, 18 site-absolute-url, 4 self-repo-url; 135 of the 194 come from the gate's OWN test file (a widened gate's first act is to fail on its own fixtures), 17 from apps/console/src/pages/doc-links.test.ts, 9 from apps/console/vite.config.ts. 48 of the 257 extractions are not links at all but TypeScript matching the regex, e.g. NotificationContext.tsx yielding href 'n.title, { description: n.message }', useActionRunner.ts yielding 'msg', app-generator.test.ts yielding a regex character class, markdown-render.test.tsx yielding 'javascript:alert(1'. BASELINE: none proposed, and the ratchet instruction's precondition is not met -- the flood is test fixtures and non-links, not historical debt, so freezing 194 fixture strings would not be a ratchet. Also measured: inside the gate's CURRENT markdown population, 116 of 116 self-repo blob/tree URLs are written as [x](y) and 0 are bare, so the bare-URL blind spot has zero live instances there; in source files 3 of 3 are bare. The two populations spell links differently, which is the real mechanism.",
  "open_questions": [
    {
      "question": "Should check-doc-links gain the capability to decide links written in source files at all? The census says the current debt does not justify it, and the measurement shows the widening triage described would not have worked: population widening alone is a no-op because the extractor is markdown-syntax-only. Real capability = widened population PLUS a new bare-URL extractor PLUS a comment/string discipline, which is a materially larger gate than the card priced.",
      "options": [
        "A. Do nothing further. 2 dead links repaired by hand; 3 genuine self-repo URLs exist in source repo-wide, so the accrual rate is roughly one per several thousand files. Close #6342 on the census.",
        "B. Build the real capability: widen the population to source files, add a bare-URL extractor, and mask non-comment spans with scripts/js-comment-mask.mjs. Cost: 194 findings to triage on day one, ~135 of them the gate's own fixtures needing an explicit exclusion, plus a new false-positive class. NOTE: js-comment-mask keeps comments only, and both dead links found here lived in string literals, so this design would still miss the exact defect that motivated the card unless it also scans string literals -- which is what produces the 48 not-a-link extractions.",
        "C. Narrow, cheap variant: a bare-URL-only self-repo check over source files (no markdown-link parsing at all, so none of the 194 noise). Population would be the 3 genuine URLs plus the 2 in the gate's own hint text. Signal 3, noise 2, both trivially excludable."
      ],
      "recommendation": "A, with C as the option worth costing if the maintainer wants the capability. A because the measured debt is 2 links repaired here and the accrual rate is negligible, and because the card's own fork rule says small count means hand repair. B is the shape triage imagined and is the one option the measurement rules out: it imports 194 findings, 135 of them the gate's own fixtures, to catch a defect class of size 2 -- and its natural false-positive protection (comment-only masking) is mutually exclusive with the defect, which lived in string literals. If the capability is wanted anyway, C gets the same signal with essentially none of the noise, because a bare self-repo URL is an unambiguous shape that no TypeScript construct imitates, unlike [x](y)."
    }
  ],
  "out_of_scope_findings": []
}

Nothing filed as a separate finding: the one measured discovery (the extractor is markdown-syntax-only, so a bare URL is invisible on every surface) is the decisive input to this card's own open decision, so it is recorded here rather than split into a card that would fragment the same decision. It has zero live instances in the scanned markdown population (116 of 116 written as [x](y)), so it is not a standalone defect today.

---

Generated by Claude Code

---

Generated by Claude Code

[os-warren]

Review — ACCEPT (PR #6428), and ⭐ the census refuted this card's own model

Reviewed by the domain:devx @ objectui execution seat (#5748), PM session session_012CZgmFFzqA9cX8tBMhvpFe, R34. Report returned premise_still_valid: false — correctly.

What the census found, and why it changes the answer rather than sizing it

138 self-repo blob|tree URLs repo-wide; 21 outside the gate's population; 16 of those are the gate's own deliberately-dead fixtures, 2 are the literal ellipsis in its own hint text, and 3 are genuine authored links in product source — 2 of them dead. Small fork taken, per this card's own rule and the dispatch order: two hand repairs, gate untouched, widening handed back.

⭐ But the important finding is not the size — it is that the card's model is half wrong in a way that changes the answer. This card says the gate "is not missing the ability to judge that URL, it is missing the file." Measured:

• the extractor is MARKDOWN_LINK_RE = /\[[^\]]+\]\(([^)]+)\)/g (:518) and ⛔ never extracts a bare URL;
• all 3 genuine source links are bare, and both dead ones live inside console.warn string literals, not docblocks;
• ⛔ so widening the extension filter alone would not have caught object-validation-engine.ts @see points at SECURITY_FIX_SUMMARY.md, deleted in ea72f1886 #6275's link either — the worked example this card was built on.

⭐ And the real mechanism, which neither the card nor triage had: 116 of 116 self-repo URLs inside the current markdown population are [x](y) and 0 are bare; in source files 3 of 3 are bare. The two populations spell links differently. The extension filter was never the only thing in the way.

⭐ That claim was proven rather than argued — a faithful simulator (same stripCode(), same regex, same self-repo arm) over a source file carrying both spellings reports the markdown one and not the bare one, while the same simulator finds 4 on the gate's own fixture file, so it demonstrably works. A simulator that found nothing would have proven nothing.

The two repairs are better than "make the link resolve"

• Registry.ts:228 → re-pointed at the live /docs/guide/plugin-development#namespaced-registration, verified with the gate's own resolver, plus a dead control (/docs/guide/definitely-not-a-real-page-xyz) confirming the resolver reports dead.
• validation-engine.ts:411 → the See: line dropped entirely, because the deleted guide covered namespaces and lazy field registration and ⚠️ never documented conditions at all — so that pointer was misdirected as well as dead, and the message already carries a complete before/after inline. ⭐ Noticing that a dead link was also pointing at the wrong thing is the difference between repairing a URL and repairing the sentence.
• ⛔ Neither can use object-validation-engine.ts @see points at SECURITY_FIX_SUMMARY.md, deleted in ea72f1886 #6275's immutable git show SHA^:PATH form, and the reason is right: these are console messages read by app developers who have only the npm package.

Noise sample, as ordered — and it is what prices the open question

194 findings over 3,764 source files, none a genuine defect: 135 from the gate's own test file, and 48 of 257 extractions are not links at all but TypeScript matching the regex ('n.title, { description: n.message }', 'javascript:alert(1'). ⛔ No baseline proposed, and correctly so — the ratchet instruction's precondition is not met, because the flood is fixtures and non-links, not historical debt. Freezing 194 fixture strings would not be a ratchet.

The open question is now a decision card

Filed as #6430, with the census, the refutation, the noise measurement, four-axis analysis and a recommendation of A (close on the census), with C (bare-URL-only check, signal 3 / noise 2) as the only shape worth costing if the capability is wanted. ⭐ B is the shape triage imagined and the one the measurement rules out — 194:2, and its natural false-positive defence (comment-only masking) is mutually exclusive with the defect, which lived in string literals.

One instrument note worth keeping

⚠️ pnpm --filter '@object-ui/core' test exits 1 by design in this repo (#3378's guard against package-dir vitest false-green). The dev identified that as a refused invocation, not a red test, and re-ran correctly from the repo root. ⛔ Reading that exit code as a failure is how a good run gets reported as broken.

Disposition

⛔ Arming PR #6428 on every check green. The repairs are correct under all three options on #6430 — a dead pointer is wrong regardless of whether a gate ever learns to see it — so they do not wait on that decision.

---

Generated by Claude Code