docs(architecture): 用现行单一提供者事实取代指向已删除 ADR-0001 的死链

[os-project-manager]

Fixes #6733

问题

ARCHITECTURE.md 的 “Architecture Decision Records” 小节里唯一一条 bullet 是一个 markdown 链接,指向 docs/adr/0001-metadata-service-architecture.md。该文件已于 2026-02-11 在 9da8e3e72 中随 docs/adr/0002-database-driven-metadata-storage.md 与 docs/adr/README.md 一并删除。读者从仓库最显眼的架构入口点进去,拿到 404。

为什么不是「换个 ADR 重指」

先按 origin/main 验证前提,而不是直接机械重指。结论:那条链接承载的架构论断本身已经不成立,重指到任何别的记录都只会把一句假话保留下来。

把删掉的 ADR-0001 从历史里取回来读(git show 9da8e3e72^:docs/adr/0001-…),它选定的是 “Option 3: Hybrid Approach”——ObjectQL 与 MetadataPlugin 都能提供 metadata 服务,MetadataPlugin 优先、ObjectQL 兜底。对照今天的代码:

ADR-0001 的论断	今天的事实
两者都能提供 metadata 服务	全仓只有 packages/metadata/src/plugin.ts:268 调 registerService('metadata', …)
ObjectQL 兜底注册	packages/objectql/src/plugin.ts 只注册 objectql / data / manifest / lifecycle,没有 metadata
双方实现同一接口	这一半活下来了,但已升格为 spec 契约 IMetadataService(packages/spec/src/contracts/metadata-service.ts)
ObjectQL 从 metadata 服务加载	仍然如此:start() 里读服务、同步定义、订阅事件(ADR-0008 PR-7),取不到时退回自身内部 registry

也就是说:「两个提供者」那一半已经退役,「共享接口 + ObjectQL 消费」那一半还在,但换了归属。

改法

该小节不再挂链接,改为:

1. 用纯文本(非链接)记下被删路径与删除出处(日期 + commit),让下一个读者不必重做一遍考古;
2. 陈述现行的单一提供者架构,并逐条指向仍然存在的活记录——packages/metadata/src/plugin.ts、packages/objectql/src/plugin.ts、packages/spec/src/contracts/metadata-service.ts、packages/spec/src/system/core-services.zod.ts;
3. 仓储 / 变更日志 / 订阅机制指向仍在的 ADR-0008(链接经核验可解析);
4. 明确写出一句话:「单一提供者」这个决策今天没有 ADR 归属——ADR-0001 被删后没有任何记录接手。按 dispatch 与 AGENTS.md PD feat: Comprehensive CRM example demonstrating all ObjectStack protocol features #14,重新立档是维护者的事,本 PR 不做。

⛔ 本 PR 没有创建、恢复或修改 docs/adr/** 下的任何文件。

顺带修掉自己造成的一处陈述失真

scripts/check-adr-anchors.mjs 里 UNRESOLVED_ADR_CITATIONS 的 0001 条注释原文写着 “⚠️ ARCHITECTURE.md still carries a markdown LINK to the deleted path”。本 PR 之后这句不再为真,留着就是一句新的假话,所以同步更新为事实描述。

条目本身保留:ADR-0002 的历史引用(“already discarded in v3.4's ADR-0001”)仍让它 earning its place。门禁自带 stale 检查(条目若不再需要会以 stale 报红),实测仍绿,见下。

门禁

三个门禁全绿,均为真实输出:

$ node scripts/check-adr-links.mjs --self-test
✅ check-adr-links --self-test: discrimination, census, ADR-0046 pin and baseline staleness all verified
$ node scripts/check-adr-links.mjs
✅ check-adr-links: 531 relative link destination(s) under docs/adr/ resolve (8 frozen on the shrink-only baseline)

$ node scripts/check-adr-anchors.mjs --self-test
✓ check-adr-anchors --self-test: 39 assertions over the real auditAdrDirectory() / auditCitedNumbers() paths.
$ node scripts/check-adr-anchors.mjs
check-adr-anchors: OK (40 anchored file(s), every governing ADR still referenced; 118 decision
number(s), each naming one decision or an allowlisted pair; 19993 citation(s) across 3280 file(s) resolve).

$ node scripts/check-nul-bytes.mjs
check-nul-bytes: OK (scanned 6398 tracked text file(s); skipped 5 binary, 1 non-regular; no raw ASCII control bytes).

那 8 条 frozen 基线正是 #6726 记录的 ADR→源码死链,与本 PR 无交集。

关于「反向验证」的诚实说明

这里没有「改回去就变红」的门禁可用,而这恰恰是本 issue 的一部分事实:没有任何门禁扫 ARCHITECTURE.md 的链接。

• check:adr-links 只解析 docs/adr/ 下的相对链接(531 条全绿),而这条死链在文件外;
• check:adr-anchors 审的是 ADR 编号能否解析,不是链接目标,所以编号绿而链接 404;
• .github/workflows/check-links.yml 的 lychee glob 恰好是 content/**/*.md、content/**/*.mdx、README.md —— ARCHITECTURE.md 不在其中。这回答了原 issue 结尾那个悬而未决的问题:它不是没跑,是根本没覆盖到。

所以本次修复的证据是链接普查而不是门禁颜色:同一段脚本在改前后各跑一次,ARCHITECTURE.md 的相对链接从 12 条 / 1 条可解析 变为 12 条 / 2 条可解析,ADR-0001 那条从死链清单中消失,新增的 ADR-0008 链接可解析。

顺带发现(已另行归档,未纳入本 PR diff)

普查同时暴露 ARCHITECTURE.md 还有 10 条死链 + 2 处失效路径引用(整个 ## Related Documentation 段除 ./ROADMAP.md 外全死)。按 PD #10 另立 #6867(finding,未指派),未扩进本 PR 的 diff。它与 #6726 无交集:#6726 是 docs/adr/ 内指向源码树的链接,#6867 是 ARCHITECTURE.md 自身的出链。

影响面

纯文档 + 一处注释,无用户可见行为变化,故无 changeset,已打 skip-changeset。

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 9, 2026 1:55am