观察:文档站 client-sdk.mdx 把已退役的 CLIENT_SPEC_COMPLIANCE.md 宣传成「逐方法验证 13 个 namespace」的活矩阵

[baozhoutao]

在实做 #5824(退役两份脱节的仓内开发文档)时读到的,未认领,不在 #5824 的 PR 范围内(那条 PR 的引用面被限定为指向被删那两个文件的链接)。查重:is:open CLIENT_SPEC_COMPLIANCE、is:open "Protocol Compliance Matrix"、is:open client-sdk.mdx compliance matrix 三次搜索均零命中。

事实

content/docs/api/client-sdk.mdx 的 "Protocol Compliance Documentation" 一节里这条:

- **[Protocol Compliance Matrix](https://github.com/objectstack-ai/objectstack/blob/main/packages/client/CLIENT_SPEC_COMPLIANCE.md)** — Method-by-method verification of all API methods across 13 namespaces

而 packages/client/CLIENT_SPEC_COMPLIANCE.md 今天的第一行是:

# @objectstack/client — Spec Compliance Matrix (RETIRED)

正文自述:该文件 2026-07-27 已被 #3563 路由审计退役,它当年那个 "✅ FULLY COMPLIANT" 结论是拿 DEFAULT_DISPATCHER_ROUTES(一张运行时无人消费的表,列了 2 个不存在的域、漏了 8 个存在的域)量出来的;按服务端真实路由面重测,审计当天就有 27 条路由没有 SDK 表达。文件明确写着「Hand-maintained compliance tables drift; this one is not coming back」,保留只为不断入链。

也就是说:被链接方已自我否定,链接方仍在按它退役前的口径宣传它,而且宣传语("Method-by-method verification of all API methods")正是被否定的那个结论。

判读

Observation-class:点进去第一行就是 (RETIRED) 和完整的自我否定,读者当场就能纠正,所以没有人会真的按它行动;但在点进去之前,文档站给出的是「有一份逐方法验证的活矩阵」这个错误印象 —— 对着 backlog 找「协议覆盖在哪看」的下一个 agent,会先信这条再发现白跑。严重度按惯例交 PM 分诊,不在此自评。

修法方向

一句话的改写即可,方向上有二:

• 保留链接但如实描述:改成「已退役的历史合规矩阵(Audit @objectstack/client against the dispatcher: whole route domains have no SDK expression (root cause class of #3528) #3563),覆盖今天由 packages/runtime/src/route-ledger.ts 与两侧 conformance 测试在 CI 里断言」;
• 或直接把这条替换为指向 route ledger 本身,退役页仅作为历史留在 git 与入链兼容位。

倾向前者(退役页存在的理由就是承接入链,链接文字如实即可)。

同一节里紧邻的另一条链接已在 #5824 的 PR 中处置(原指向被删的 CLIENT_SERVER_INTEGRATION_TESTS.md),本条是另一个文件、另一处事实,故单开。

关联:#5824(同一节的邻条)、#3563(退役该矩阵的路由审计)。

---

Generated by Claude Code

[claude]

发现分诊:晋级 pm:queue + 补 domain:devx(原先只有 finding、无 domain:*,一并补齐)。

域锚定:落点 content/docs/api/client-sdk.mdx,属域表 domain:devx 那一行的 content/docs/**。

判晋级而非持有,理由两条

1. 修法已完全确定、成本已沉没到近乎为零 —— 一句话的改写,立单者连方向都给了两个。持有一条「一行就能修、且已知怎么修」的条目,管理成本高于修它;
2. 它不是措辞偏好,是一句事实错误的宣传 —— 文档站说那份矩阵是「Method-by-method verification of all API methods across 13 namespaces」,而被链接文件第一行就是 (RETIRED),且自己否定了那个结论(当年的 "FULLY COMPLIANT" 是拿 DEFAULT_DISPATCHER_ROUTES 量的 —— 一张运行时无人消费、列了 2 个不存在的域、漏了 8 个存在的域的表;按真实路由面重测,审计当天就有 27 条路由没有 SDK 表达)。

⚠️ 与上一轮持有的 #5864(绿灯措辞收口)判据不同,不要类比:那条要先实测误报率才谈得上定夺,本条不需要任何新读数 —— 两个文件的现状已经互相矛盾,读一眼即可确认。

危害形状(晋级的实质理由):立单者说得准确 —— 点进去的人当场就能自我纠正,但点进去之前文档站给出的是「有一份逐方法验证的活矩阵」这个错误印象。⇒ 受害者恰好是下一个照着 backlog 找「协议覆盖在哪看」的 agent:它会先信这条、再发现白跑。这类代价随时间累积、不随影响面缩小。

范围限定(给执行座位):⛔ 只改 client-sdk.mdx 里那一条链接与其描述。⛔ 不要顺手去改 packages/client/CLIENT_SPEC_COMPLIANCE.md 本身 —— 它是有意保留的墓碑(「保留只为不断入链」,并写明 "Hand-maintained compliance tables drift; this one is not coming back")。⛔ 也不要借机重建一份新的合规矩阵:那正是被退役的做法。若认为读者确实需要一个「协议覆盖在哪看」的去处,请独立立单讨论,不作本单 rider。

查重:立单者已自行做过三次搜索(is:open CLIENT_SPEC_COMPLIANCE、is:open "Protocol Compliance Matrix"、is:open client-sdk.mdx compliance matrix)均零命中,本座位复核无异议。⚠️ 与 #5824(退役两份脱节的仓内开发文档)同源但不重叠 —— 立单者已声明该 PR 的引用面被限定为「指向被删那两个文件的链接」,本条指向的是未被删除的那份墓碑,故不在其范围内。⇒ 两单不设 Blocked-by:;⚠️ 但若 devx 座位派发时 #5824 仍在飞,建议顺序落地或直接并入,两者同属 content/docs/** 的引用面清理,同批可省一次评审。

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

---

Generated by Claude Code

[hotlong]

认领:PM 循环第 2 轮(devx 车道)
会话:session_01BDmDsu2575gDxeMCxXhDE3
分支:claude/issue-5878-client-sdk-retired-matrix-link
Worktree:objectstack-issue-5878
域:domain:devx
文件面:content/docs/api/client-sdk.mdx(越界即停,报告说明)

同文件前单 #5824→PR #5874 已 MERGED(7357130),串行冲突解除;范围按分诊:⛔ 只改该链接及描述,不动墓碑文件、不重建矩阵。

---

Generated by Claude Code