DSH / Atlas
2026-09-08implementedprocessarchived 2026-09-30

Include package indexes in Markdown link discovery

将包索引纳入 Markdown 链接发现范围

In `verify-md-links`, nested group and package globs cannot match `packages/README.md` or its Chinese counterpart. A broken link in either index escapes validation unless the check also discovers those sources.

English

Problem

In verify-md-links, nested group and package globs cannot match packages/README.md or its Chinese counterpart. A broken link in either index escapes validation unless the check also discovers those sources.

Decision

verify-md-links includes packages/*.md in its existing source discovery. The command and its tests share that discovery function. Symlink deduplication and frozen Agent Note exclusion remain owned by repo-files.

Alternatives considered

Repair individual links only. This leaves the source-discovery omission in place, so a later broken index link can pass the same check.

Add a separate package-inventory checker. Index completeness is a different requirement from link validity. It needs to support the current table formats and bilingual link targets; it does not replace checking links in every discovered source.

Consequences

Broken relative links in both package indexes fail the existing documentation command. Discovery tests exercise those failures, preserve package-instruction and nested-document coverage, and exclude frozen notes. This check validates links; it does not require indexes to enumerate every package or define the source sets of other documentation checks.

中文

问题

在 verify-md-links 中,嵌套的组级与包级 glob 无法匹配 packages/README.md 及其中文对应文件。除非检查器也发现这些源文件,否则两份索引中的死链都不会进入校验。

决策

verify-md-links 在现有源文件发现范围中加入 packages/*.md。命令与测试共用同一个发现函数。符号链接去重与冻结 Agent Note 的排除仍由 repo-files 负责。

考虑过的替代方案

仅修复个别链接。 这会保留源文件发现遗漏,后续新增的索引死链仍可能通过同一检查。

另加包清单检查器。 索引完整性与链接有效性是不同要求。前者需要支持当前表格格式与双语链接目标,不能替代对每个已发现源文件的链接检查。

后果

两份包索引中的相对死链会使现有文档命令失败。发现测试覆盖这些失败,保留包级指令文件与嵌套文档的检查范围,并排除冻结笔记。本检查验证链接,不要求索引枚举每个包,也不定义其他文档检查的源文件集合。