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

[yinlianghui]

认领(PM 分诊晋级)— 会话 session_01GTRjn8xBqp75dk7kFupVRt,分支 claude/issue-3545-contrib-roadmap-links。

查重(补 dev 未能完成的部分):PM 基线核对无同源单。分诊裁定:三处死链按 issue 给的真实目标修(CONTRIBUTING.md:153 → docs/ARCHITECTURE.md;:469 的 ./docs/README.md 按现状定去留 —— 目标不存在则改指真实入口或删句,如实处置;ROADMAP.md:1892 的 .mdx → .md)。注意这两个文件在 #3542 扩展后仍不在扫描面内(其 SCAN_ROOTS 是 content/docs + examples + 根 README)—— 修完后是否值得把 CONTRIBUTING/ROADMAP 也纳入扫描面,dev 给一行成本评估进报告,不在本单实施。

文件面:CONTRIBUTING.md、ROADMAP.md(仅那三行及其必要上下文)。越界即停。

---

Generated by Claude Code

[yinlianghui]

验收:ACCEPT — PR #3571。

核过 GitHub 实物(恰 2 文件 3 处)。裁定要点:

1. 链接一的改道背书:派单假设的 docs/ARCHITECTURE.md 被 dev 读实物证伪(那是 console-streamlining 重构文档,与"包树+设计原则"的引用语境不符),真正对应物 content/docs/guide/architecture.md 且按目标真实标题改写链文案 —— 派单让核验,dev 核出了不同答案并如实改道,这是好运行不是偏离。
2. 链接二整句删除处置正确(目标从未存在、承诺的内容就是它所在的节);链接三扩展名修正保持兄弟条目风格。
3. 证据如实:两文件在所有门禁扫描面之外(含 feat(scripts): check-doc-links 两向扩展 —— 扫描面扩到 examples/** 与根 README,自仓 GitHub URL 离线校验 #3542 后),dev 明说"没有红转绿可看",用检查器自己导出的函数做只读探针复刻 disk 规则测得 2→0/1→0 —— 不编造门禁证据,又给出了可复现读数。
4. 顺带完成的扫描面成本实测(3 行配置、70 链接、docs/** 15 文件 49 链接今日零死链)把 step 2 从"猜测有益"变成"实测无害" —— 已依此另立 step 2 单。
5. 相邻缺陷不夹带:lychee 假声明 + 代码围栏里的 3 条死"正确示例"(stripCode 盲区)→ CONTRIBUTING.md 的 Documentation 一节有两处与仓库现状不符:门禁描述指错工具/触发条件,"✅ 正确链接示例" 里 3 条路由是死的 #3570,已核存在;⚠️ 与本 PR 同文件,docs: 修正 CONTRIBUTING.md / ROADMAP.md 的 3 条死链 #3571 合并前不派。

PR 转 ready + auto-merge。

---

Generated by Claude Code