docs(capabilities): add implementation code map

[huangruiteng]

Summary

• add a contributor-facing landing page for loopx/capabilities/
• route contributors to the canonical product capability guide, runtime catalog, implementation modules, and validation
• add the reverse link from the product capability index without duplicating a package-to-document table

Product and architecture judgment

The capability documentation now explains the user-facing outcome boundary, but contributors entering through the implementation tree had no landing page. This closes that navigation gap while preserving three distinct authorities: CLI/catalog readback for shipped registration, docs/capabilities/ for product contracts, and loopx/capabilities/ for implementation ownership. Per-capability link-only READMEs are deliberately not added because they would duplicate catalog metadata and drift as modules or documents move.

This is documentation-only. It changes no capability registration, provider lifecycle, Kernel authority, permissions, or runtime behavior.

Validation

• python3 examples/docs-governance-smoke.py
• loopx canary premerge --from-git-diff
  • standard tier passed
  • 14 selected checks passed
  • public-boundary scan passed
  • no failures, warnings, skips, or manual holds
• git diff --check origin/main...HEAD

Boundary review

• no credentials, private state, raw evidence, generated logs, internal links, or local paths are included
• no runtime, benchmark, permission, installation, or public evidence-policy surface changes

[huangruiteng]

Self-review

Findings

No actionable findings.

Open questions and assumptions

None. The code tree remains a navigation surface; capability registration and availability remain authoritative in the runtime catalog and loopx capability list/show readback.

Product and architecture judgment

• Motivation: contributors entering loopx/capabilities/ lacked a path to the product contracts, registry metadata, and focused validation.
• Solved: the new parent README provides that route, and the product capability index links back to it.
• Design: the diff deliberately avoids per-capability link-only READMEs or a second package-to-document table. Existing catalog fields remain the single maintained cross-reference.
• Impact and risk: documentation-only; no runtime behavior, typed state rule, capability registration, provider lifecycle, Kernel authority, permission, benchmark, installation, or evidence-policy change.
• Review lenses: no substring classification, domain-specific wording in a generic control-plane contract, silent default change, or guidance-versus-enforced-obligation ambiguity was introduced.

Validation

• python3 examples/docs-governance-smoke.py passed.
• loopx canary premerge --from-git-diff passed on the latest main: standard tier, 14 selected checks, zero failures, warnings, skips, or manual holds.
• Diff hygiene and the public/private boundary scan passed for both changed paths.
• The owner reviewed and approved the new capability landing-page first screen before commit.

This coverage is sufficient because the PR changes only two public Markdown navigation surfaces and the risk-based gate exercised link governance, catalog-selected canaries, content-ops documentation risk checks, and the public boundary. No runtime or permission surface requires additional execution coverage.

Merge decision

Eligible for authorized self-merge after the required GitHub checks pass.

[huangruiteng]

PR #3252 全量双语评审 — Capability Implementation Code Map

精确评审头（Exact Head）: 3252@5421bab54790258561760b1b03b05cbf3cafdc7f
Base: main | 类型: docs-only（2 files, +50） | 作者: huangruiteng（owner）

---

详细中文评审

动机

能力文档解释了用户侧 outcome 边界，但从实现树进入的贡献者没有 landing page：loopx/capabilities/ 里几十个包/模块缺少一份「这是代码边界、不是注册证据」的导航说明。PR 补上实现代码地图，并把三份权威分开：CLI/catalog readback（shipped 注册事实）、docs/capabilities/（产品契约）、loopx/capabilities/（实现 ownership）。刻意不加逐能力 link-only README，避免与 catalog 元数据重复漂移——动机与取舍都合理。

改动思路

loopx/capabilities/README.md（+45）作为实现树入口：先声明「包存在 ≠ 注册/启用」，再给 capability list/show 作为 installed release 的事实源；贡献者导航按产品指南 → catalog.py/registry.py → capability 返回的 docs/protocols/smokes 字段走；扩展/Provider 边界与「安装不授予 Kernel authority」重申；增改代码时遵守「caller outcome 命名 + 真实 entrypoint/注册/文档/验证」。docs/capabilities/README.md（+5）加反向链接并带同一 caveat。

具体改动

• loopx/capabilities/README.md（+45）：代码地图主体（Capability Implementations / Contributor Navigation / Adding Or Moving Capability Code）。
• docs/capabilities/README.md（+5）：产品契约页顶部加实现树反向链接。

关键内容讲解

1. 「目录是导航、不是证据」声明：直接对应本仓库的 capability 纪律（与 #3242/#3248 一脉相承），防止实现树被误当注册事实。
2. capability list/show 作为唯一事实源：文档不维护第二份 package→document 索引，而是引导读 show 返回的字段——正是仓库「压缩而非追加」原则。
3. Kernel/Provider/Extension 边界重申：安装/发现 extension 不授予 authority，实现目录不等于注册——与 AGENTS.md 的 capability 放置决策一致。
4. 新增能力门槛：真实 entrypoint + catalog 注册 + canonical docs + focused validation，缺一不可。

对主干的风险

阻断项（P1，流程/CI）：Sign-off（DCO）check FAILURE——commit 5421bab5 的 message 无 Signed-off-by trailer（已用 git log 核实）。补 sign-off 后重推即可。

非阻断（P2）： build 与 pytest 评审时刻 IN_PROGRESS（dependency-review 已 SUCCESS；docs-governance-smoke.py 在 exact head 独立运行通过）。合并前确认变绿。

验证矩阵（exact head 实测）：

场景	结果
链接（product guide / catalog.py / registry.py / extensions.md）	全部存在
docs-governance-smoke.py	PASS
commit sign-off trailer	缺失 → 解释 Sign-off FAILURE
GitHub checks	dependency-review SUCCESS；Sign-off FAILURE；build/pytest IN_PROGRESS
改动范围	仅 docs（2 files, +50），无运行时变化

我的整体评价

小而清晰的导航修复：把实现树从「代码堆」变成带边界与事实源说明的贡献者入口，且刻意避免重复索引，符合仓库纪律。唯一阻断是 DCO sign-off；补签后即可放行。结论：REQUEST_CHANGES（窄化到 sign-off 修复）。

---

English Verdict

Verdict: REQUEST_CHANGES — exact head 3252@5421bab54790258561760b1b03b05cbf3cafdc7f.

Summary: A small docs-only code map for loopx/capabilities/, clearly separating the implementation tree from the shipped catalog, routing contributors to capability list/show as the source of truth, and restating capability/extension placement rules. All links resolve and docs-governance-smoke.py passes at the head.

Blocking (P1): DCO Sign-off FAILS because commit 5421bab5 lacks a Signed-off-by trailer (verified via git log). Add the sign-off and re-push.

P2 (non-blocking): confirm build and pytest turn green before merge.

[huangruiteng]

PR #3252 复审 — DCO 已修复，build 因 mkdocs 链接校验失败

精确评审头（Exact Head）: 3252@a9b403f3a3cf8639acf141cf8dae95d3a686d745
复审依据: 上一轮 review 4945571651（5421bab5：P1 DCO sign-off 缺失）

详细中文评审（复审）

结论

作者 force-push 新 head a9b403f3：commit 已补 Signed-off-by，Sign-off（DCO）已 SUCCESS——上一轮 P1 已解决。但 build check 现为 FAILURE，且根因是本 PR 自己引入的链接：

WARNING - Doc file 'capabilities/README.md' contains a link
'../../loopx/capabilities/README.md', but the target
'../loopx/capabilities/README.md' is not found among documentation files.

docs/capabilities/README.md 新增的反向链接指向 ../../loopx/capabilities/README.md，该目标位于 mkdocs 文档树（docs/）之外，Material for MkDocs 以 warning-as-error 使构建失败（CI job 95125729653，exit 1）。

阻断项（P1）：反向链接破坏 mkdocs 构建

最小修复：把 docs/capabilities/README.md 里的链接改成仓库 blob URL（如 https://github.com/huangruiteng/loopx/blob/main/loopx/capabilities/README.md），或把实现代码地图移入 docs/ 树（不推荐，会改变目录边界）；不要简单删掉该链接，因为贡献者入口仍然有价值。修复后重跑 mkdocs build 确认无 warning。

验证矩阵（exact head 实测）

场景	结果
上一轮 P1（DCO sign-off）	已修复：commit 带 Signed-off-by，Sign-off SUCCESS
build check	FAILURE（mkdocs link validation，warning-as-error）
docs-governance-smoke.py	PASS
dependency-review	SUCCESS；pytest IN_PROGRESS

我的整体评价

上一轮 P1 已修；新阻断是构建层链接校验失败，根因明确、修复直接（改用 blob URL 或移入 docs 树）。内容本身保持已认可质量。结论：REQUEST_CHANGES（窄化到反向链接修复）。

---

English Verdict

Verdict: REQUEST_CHANGES — exact head 3252@a9b403f3a3cf8639acf141cf8dae95d3a686d745.

The previous P1 (DCO sign-off) is fixed: the commit now carries Signed-off-by and the Sign-off check is SUCCESS. The new blocker is a direct build regression: the reverse link ../../loopx/capabilities/README.md added in docs/capabilities/README.md targets a file outside the mkdocs docs tree, and Material for MkDocs treats it as a warning-as-error (CI build FAILURE, exit 1). Replace the link with a GitHub blob URL (or move the target into the docs tree) and re-run the docs build. docs-governance-smoke.py still passes; pytest is IN_PROGRESS.

[huangruiteng]

CI refinement

The first Frontstage Pages run correctly rejected the repository-relative link from docs/capabilities/README.md to loopx/capabilities/README.md: MkDocs serves only the docs/ tree and treats that target as outside its documentation source.

The docs-side link now uses the public GitHub repository URL, while the code-side README keeps its relative link into docs/. This preserves bidirectional navigation without copying implementation files into the documentation site or adding a second capability mapping.

Validation after the refinement:

• uv run --with-requirements docs/requirements-docs.txt mkdocs build --strict ... passed locally with no warnings.
• python3 examples/docs-governance-smoke.py passed.
• loopx canary premerge --from-git-diff passed again: standard tier, 14 selected checks, zero failures, warnings, skips, or manual holds.
• DCO trailer remains valid; the changed commit is signed off.

The temporary validation environment and generated lock file were excluded from the branch. The PR still changes only the two intended public Markdown paths.

[huangruiteng]

Approval conclusion (author-owned PR; GitHub blocks formal self-approval)

精确评审头（Exact Head）: 3252@3adac5932bccb0edc7bfb0fee86c8c83e32b8601
复审依据: 上一轮 review 4945575840（a9b403f3：P1 mkdocs 反向链接在 docs 树外导致 build FAILURE）

详细中文评审（复审）

结论

上一轮 P1 已修复：docs/capabilities/README.md 的反向链接改为 GitHub tree URL（https://github.com/huangruiteng/loopx/tree/main/loopx/capabilities），不再指向 mkdocs 文档树外的相对路径。两个 build check 现均为 SUCCESS，Sign-off 保持 SUCCESS，docs-governance-smoke.py 在 exact head 独立运行通过。内容与上一轮已认可版本一致（仅链接形态变化）。

验证矩阵（exact head 实测）

场景	结果
上一轮 P1（mkdocs 反向链接）	已修复：改为 GitHub tree URL
build checks	两个 build 均 SUCCESS
Sign-off / dependency-review	SUCCESS
docs-governance-smoke.py	PASS
pytest	IN_PROGRESS（评审时刻）

我的整体评价

上一轮唯一阻断（mkdocs 链接校验）已解决，内容保持已认可质量。剩余只需确认 pytest 变绿后即可合并。结论：APPROVE（author-owned PR，以 COMMENTED 记录批准结论）。

---

English Verdict

Verdict: APPROVE (author-owned PR; recorded as COMMENTED because GitHub blocks formal self-approval)

Exact head: 3252@3adac5932bccb0edc7bfb0fee86c8c83e32b8601

The P1 mkdocs build blocker from review 4945575840 is fixed: the reverse link now uses a GitHub tree URL, both build checks are SUCCESS, Sign-off and dependency-review are SUCCESS, and docs-governance-smoke.py passes at the head. Confirm pytest turns green before merge.

[huangruiteng]

Merge result

Self-merged via squash after all required GitHub checks passed.

• Sign-off: passed
• dependency review: passed
• Frontstage Pages strict build: passed
• release artifacts build: passed
• pytest: passed
• local risk-based premerge gate: passed with 14 selected checks and no failures or manual holds

Final decision: self-merged. The result adds one contributor code map and one docs-side reverse link while keeping runtime catalog metadata as the only maintained capability-to-module/document cross-reference.