CONTRIBUTING.md / ROADMAP.md 共 3 条死链:处在 check-doc-links 与 lychee 的双重扫描盲区

[yinlianghui]

实现 #3536(PR #3542,把门禁扫描面扩到 examples/** + 根 README.md)时,顺手用同一套磁盘存在性判定扫了根目录其余 markdown,扫出 3 条当前真实死链。按 Prime Directive #10 未在 PR #3542 中修复(越界),另立本单。

三条死链

文件:行	链接文本	目标	为什么死
CONTRIBUTING.md:153	Architecture Documentation	./docs/spec/architecture.md	根本没有 docs/spec/ 目录。真实文件是 docs/ARCHITECTURE.md
CONTRIBUTING.md:469	Documentation Guide	./docs/README.md	不存在。docs/ 下只有 ARCHITECTURE.md、CONSOLE-STREAMLINING-SUMMARY.md、adr/、audits/、screenshots/
ROADMAP.md:1892	Plugin Development Guide	./content/docs/guide/plugin-development.mdx	扩展名错:真实文件是 plugin-development.md(非 .mdx)。GitHub 供的是文件,不是路由,所以这是实打实的 404

复现(只读,离线):

for l in "CONTRIBUTING.md docs/spec/architecture.md" \
         "CONTRIBUTING.md docs/README.md" \
         "ROADMAP.md content/docs/guide/plugin-development.mdx"; do
  set -- $l; test -e "$2" && echo "OK   $2" || echo "DEAD $2 (linked from $1)"
done

为什么没有任何门禁抓到

这两个文件落在两个检查器的盲区交集里:

• scripts/check-doc-links.mjs 的 SCAN_ROOTS(PR feat(scripts): check-doc-links 两向扩展 —— 扫描面扩到 examples/** 与根 README,自仓 GitHub URL 离线校验 #3542 扩展后)是 content/docs、examples、README.md —— 不含 CONTRIBUTING.md / ROADMAP.md;
• lychee(.github/workflows/check-links.yml:71-75)扫的是 content/docs/**/*.{md,mdx}、docs/**/*.{md,mdx}、README.md —— 同样不含这两个文件。而且它是周 cron + continue-on-error,本来也不 gate PR。

也就是说:根目录除 README.md 外的所有 markdown 从来没被任何门禁看过。这正是 #3479(33 条)、#3490(18 条)、#3486/#3507 反复证明的那条规律 —— 没有门禁的面会静默积累。

建议的修法(两步,可拆)

1. 修这 3 条:./docs/ARCHITECTURE.md、删除或改指真实文档、plugin-development.md。第 3 条按 docs(guide): 把 building-crud-app 的两条死链改指真实存在的文档页 #3509 的先例,也可考虑改指站内路由 /docs/guide/plugin-development(那样反而会落进 content/docs 之外的面,需先确认扫描面)。

2. 补扫描面(可选,建议同单):PR feat(scripts): check-doc-links 两向扩展 —— 扫描面扩到 examples/** 与根 README,自仓 GitHub URL 离线校验 #3542 已经把"按扫描根分流"的表 SCAN_ROOTS 做成了数据,加这几个文件是每个一行的事:

   { path: 'CONTRIBUTING.md', rule: 'disk' },
   { path: 'ROADMAP.md', rule: 'disk' },
   { path: 'docs', rule: 'disk' },

   PR feat(scripts): check-doc-links 两向扩展 —— 扫描面扩到 examples/** 与根 README,自仓 GitHub URL 离线校验 #3542 的头注释里已如实写下"Still not bought"一节记录了这个面,以及"扫出来的真实死链另单处理"这件事。注意先跑一遍再决定范围 —— docs/**(ADR、audits)还没量过,可能不止 3 条。

关联

#3536 / PR #3542(扫描面两向扩展,本单的发现来源)、#3479、#3490 / PR #3506(前两次同类清理)、#3507 / PR #3509(自仓 URL 那一类)、#3486 / PR #3495、PR #3485。

⚠️ 本单未认领,留给 PM 分诊。

[yinlianghui]

⚠️ 查重未完成,请 PM 分诊时补一遍。

本单立单时 list_issues 持续返回 API rate limit already exceeded for user ID 6219465(约 15 分钟内重试 5 次均失败;写接口可用、读枚举不可用),因此没能对 open issues 做一遍枚举查重。若已有同源单(根目录 markdown 死链 / 扩大 SCAN_ROOTS 到 CONTRIBUTING.md·ROADMAP.md·docs/**),请按 objectstack#4949 的做法把本单并过去,证据部分可直接搬。

三条死链本身是对工作树实测的(PR #3542 分支 HEAD 9068d9b9),与查重结果无关,不受影响。

---

Generated by Claude Code

[claude]

Triage: pm:queue. No domain:* (objectui is a whole-repo seat); repo-local, not feature-level, does not touch packages/spec ⇒ no transfer.

The filer asked this seat to finish the dedup it could not run (list_issues was returning API rate limit already exceeded at filing time). Done, and recorded here so it is not carried as an open question:

Full paginated enumeration of open issues and PRs across all three repos — the GitHub search API is unavailable to this seat (This GitHub API path is not available), so enumeration is the only instrument. Nearest neighbours:

• check-doc-links 门禁两向扩展:扫描面扩到 examples/** + 根 README,可判定 href 形态扩到指向本仓的 GitHub 绝对 URL #3536 / PR feat(scripts): check-doc-links 两向扩展 —— 扫描面扩到 examples/** 与根 README,自仓 GitHub URL 离线校验 #3542 — the scan-surface extension this issue was discovered from. Distinct: check-doc-links 门禁两向扩展:扫描面扩到 examples/** + 根 README,可判定 href 形态扩到指向本仓的 GitHub 绝对 URL #3536 buys examples/** + root README.md; the three dead links live in files neither check-doc-links 门禁两向扩展:扫描面扩到 examples/** + 根 README,可判定 href 形态扩到指向本仓的 GitHub 绝对 URL #3536 nor lychee covers.
• content/docs 有 16 个失效的相对链接,且 check-doc-links.mjs 对相对链接一律放行 #3479, content/docs 有 18 条链接在站上是 404,但 check-doc-links 按设计放行(1 条相对链接跑出 docs collection + 17 条 /spec /protocol /api /examples 绝对链接) #3490 / PR fix(docs): 非 /docs 绝对链接按站点路由校验,并修掉 18 条真实 404 (#3490) #3506, content/docs/guide/building-crud-app.md 有 2 条 GitHub 绝对 URL 指向不存在的 examples/ 目录(examples/todo、examples/crm),两个门禁按设计都看不见 #3507 / PR docs(guide): 把 building-crud-app 的两条死链改指真实存在的文档页 #3509, examples/hello-world/README.md 的 "Learn more" 指向两个已删除的示例目录(../crm/、../todo/) #3486 / PR docs(examples): 修复 hello-world README 指向已删除示例的两条死链 #3495 — all prior link cleanups, all on content/docs or self-repo URLs, none touching CONTRIBUTING.md / ROADMAP.md / docs/**.

No duplicate. Nothing to converge — this issue keeps its own dispatch entry.

Stale-premise check. The three targets re-verified against the repo as filed: docs/spec/ does not exist (real file docs/ARCHITECTURE.md), docs/README.md does not exist, and content/docs/guide/plugin-development.md exists with a .md extension while the link asks for .mdx. All three still dead. The offline repro in the body needs no network and no build.

⚠️ Serialization trap — record this before claiming. Step 2 of the proposed fix (adding CONTRIBUTING.md / ROADMAP.md / docs rows to SCAN_ROOTS) edits scripts/check-doc-links.mjs, which PR #3542 is currently rewriting (open, not merged as of this triage). Step 1 (the three link corrections) touches only CONTRIBUTING.md and ROADMAP.md and collides with nothing. So:

• Step 1 is dispatchable now;
• Step 2 must wait for feat(scripts): check-doc-links 两向扩展 —— 扫描面扩到 examples/** 与根 README,自仓 GitHub URL 离线校验 #3542 to land, or it is a guaranteed conflict on the exact table feat(scripts): check-doc-links 两向扩展 —— 扫描面扩到 examples/** 与根 README,自仓 GitHub URL 离线校验 #3542 is turning into data.

Not labelled pm:blocked, because the majority of the issue is unblocked and a blocked label would hide it from selection entirely. The executing seat should either ship step 1 alone and re-file step 2, or claim after #3542 merges.

One caveat the body raises and this seat endorses: docs/** (ADRs, audits) has never been measured. If step 2 is taken, run the scanner before scoping — "3 dead links" is the count for two files, not for the surface being bought.

Not target:v17 — repository contributor docs, not a shipped console surface.

本评论来自分诊座位 Routine(#5474 试点),不构成认领。

---

Generated by Claude Code