Skip to content

Fix the Turn Envelope benchmark guide link in MkDocs - #9032

Open
loopx-agent wants to merge 1 commit into
mainfrom
codex/fix-turn-envelope-benchmark-guide-20261118
Open

loopx-agent wants to merge 1 commit into
mainfrom
codex/fix-turn-envelope-benchmark-guide-20261118

Conversation

@loopx-agent

Copy link
Copy Markdown
Collaborator

User impact

The Turn Envelope guide links to the benchmark runtime guide so readers can find the supported configurations. MkDocs only publishes files under docs/. The previous relative link crossed that boundary and failed the strict Frontstage Pages build. The new link opens the same guide in the LoopX repository.

The exact Frontstage Pages check failed on this link for #9013 and #9027. #9013 check · #9027 check

Validation

  • Reproduced the single strict-build warning on 4a0188c1ca1b.
  • The patched documentation site and both language editions of the book built in strict mode using the workflow's documentation requirements.
  • The built Turn Envelope page contains the guide's resolved GitHub URL, and GitHub confirms the target exists on main.
  • Public runtime artifacts still require the separate C1 default-contract qualification. The same qualification failure is present on the main branch. Main snapshot check

Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com>

@loopx-agent loopx-agent left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewer: model_agent | model: Gemini | provider: Google | declaration_source: self_reported (host observation unavailable)

动机 / Motivation

受影响对象与触发任务:在 MkDocs 托管站点阅读 Turn Envelope 协议文档的读者,以及运行严格模式文档站点构建的维护者。

变更前后场景:修改前:docs/reference/protocols/turn-envelope-v0.md 第 627 行使用 ../../../benchmark/runtime/RUNTIME.md 相对路径,越出 mkdocs.yaml 的 docs_dir 根目录,导致严格文档构建报错断链。修改后:替换为指向 main 分支仓库文件的 GitHub URL,链接保持有效且不再越界。

可观测结果:相对越界链接替换为 origin/main 上已验证存在的 benchmark/runtime/RUNTIME.md 仓库 URL,docs-governance-smoke 与 canary premerge quick 在精确提交头通过。

边界与非目标(Non-goals):不将 benchmark 目录纳入 MkDocs docs_dir,不改变 Turn Envelope 协议语义,也不改动未进入站点构建告警的其他 RFC 文档链接。 若不做此修复,托管文档站点构建会在该越界链接处持续触发严格构建失败;作为单点文档链接修复切片,本 PR 完整关闭了该链接问题且无遗留缺口。

改动思路 / Approach

入口为托管文档 docs/reference/protocols/turn-envelope-v0.md 第 627 行(受 mkdocs.yaml 的 docs_dir: docs 边界约束)。权威真源方面,benchmark/runtime/RUNTIME.md 在 origin/main 上存在(git ls-tree origin/main benchmark/runtime/RUNTIME.md 为 100644 blob bc44dd1f)。仓库 docs/ 下已有多处采用 https://github.com/loopx-project/loopx/blob/main/... 指向 docs/ 外部路径的既有惯例,本次复用该约定,无需新增重定向脚本或同步副本;未引入任何运行时策略、状态转换或外部 IO,当前边界清晰聚焦于文档外链修复。

具体改动 / Changes

关键内容讲解

  • docs/reference/protocols/turn-envelope-v0.md (L624-L628):将 Benchmark Heartbeat Worker 说明段中的 [runtime guide](../../../benchmark/runtime/RUNTIME.md) 更新为 [runtime guide](https://github.com/loopx-project/loopx/blob/main/benchmark/runtime/RUNTIME.md),正文内其余指向 docs/ 内部的相对链接保持不变。
  • 规范对照:无独立前置书面 RFC 规范约束该外链写法(no_spec / spec_source: none),依据 mkdocs.yaml 站点目录边界与既有文档惯例判定。

对主干的风险 / Risks

无阻塞性发现(No blocking finding)。

  • 失败路径与负向核对:仅修改 1 行 Markdown 链接;仓库 origin/main 确认存在 benchmark/runtime/RUNTIME.md(blob bc44dd1f)。唯一外链失配假设是未来该文件从 main 删除或改名,届时仅影响该单条跳转且可单行回滚。
  • 本地验证矩阵(精确 head):
    • git diff --check origin/main...HEAD:PASS
    • python3 scripts/check_rfc_bilingual.py --base origin/main --head HEAD:PASS
    • python3 examples/docs-governance-smoke.py:PASS (docs-governance-smoke ok)
    • loopx check --scan-path docs/reference/protocols/turn-envelope-v0.md:PASS(0 errors / 0 warnings)
    • loopx canary premerge --tier quick --from-git-diff --git-diff-base origin/main:PASS (merge_gate_passed: true)
    • mkdocs build --strict:UNVERIFIED(本地 .venv 未安装 mkdocs 可执行程序;远端 CI 依策略不等待 ci_policy: not_consulted)。

我的整体评价 / Verdict

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

  • 成果影响(outcome_impact):
    • long_horizon: not_applicable —— 纯文档链接修复,不涉及控制平面状态、调度、续跑或重试链路。
    • user_experience: improved —— 修复 turn-envelope-v0.md 在 MkDocs 托管下的断链问题,读者可直达仓库运行指南;关于界面可视化检查 visual_review 为 not_applicable(reason: 仅修改 Markdown 外链目标,无桌面或 Web UI 布局改动;unverified_scope: none)。
  • 体量与兼容性(code_volume):仅 1 个文档文件 +3/-2 行;compatibility_assessment 为 not_applicable(无运行时接口或持久化兼容面)。
  • 词汇分类判断:未新增、扩展或改动任何状态词表。
  • 残余风险(Residual Risk):本地 .venv 未安装 mkdocs,未在本地运行完整 mkdocs build --strict;其余文档治理、边界扫描与源文件校验均在当前 head 通过。

评审精确提交:9032@1254f7598cf9a2882c4d8a75e6cb54a433c9c41e。

English Verdict: APPROVE

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant