Repository navigation
docs(rfc): add bilingual semantic mirror markers - #8128
Conversation
Signed-off-by: NIU-123370 <191000457+NIU-123370@users.noreply.github.com>
loopx-agent
left a comment
There was a problem hiding this comment.
Reviewer: actor_kind=model_agent; model=gpt-6.1-sol; provider=OpenAI; declaration_source=runtime_reported; reasoning_effort=max.
动机 / Motivation
维护者运行完整文档治理检查时,会在本来已经成对存在的 RFC 上失败。
主线在英文镜像标记断言处退出;当前提交补齐中英文标记后,原完整检查通过,互链仍指向原文件。
该改动恢复了既有文档治理入口,并保留缺标记、坏互链和缺镜像的拒绝行为。
本 PR 只修复两处文档标签,不交付 Stride/Yardstick 实现、默认变更、实验资格或长期收益证明。
改动思路 / Approach
已有校验器要求英文文件明确包含 semantic mirror、中文文件包含“语义镜像”,并检查镜像文件和双向链接。当前修复只调整原互链标签,继续由同一个文档治理函数读取同一对文件。不改会保留真实失败;删除断言或给这份 RFC 加例外会削弱公共规则。两处直接标注是完整且更窄的修复,不需要另加 helper、测试框架或兼容分支。
实际执行路径是原完整文档检查进入镜像校验,再继续原有 ledger、状态索引等检查。正例使用真实 source checkout;反例只隔离 DOCS 根目录,调用未修改的实际函数,未模拟“检查通过”这个后置条件。
具体改动 / Changes
审查绑定完整 head 9d7d70a1aa08f0892089eb9c6676819b9c76573c,base 为 1b636dee161f5ec0039b2c0121ef7ff7060dcb72。完整差异是两份文档各 +1/-1,提交含 DCO trailer。依据变更前的 RFC 模板,spec_ref=docs/architecture/rfcs/TEMPLATE.md,spec_revision=1b636dee161f5ec0039b2c0121ef7ff7060dcb72;以下标识仅映射原文要求。
| 规格映射 | 当前 head 的处理 |
|---|---|
| MIRROR-PAIR | implemented:原英文与同名中文文件成对保留,补上既有镜像标注;完整治理检查和缺镜像反例验证。 |
| MIRROR-LINKS | implemented:两端仍是原相对链接,独立解析确认落到原文件;坏互链被原 owner 拒绝。 |
| MIRROR-NORMATIVE | implemented:完整文件逐字节比较,仅两处标签替换;其余正文、规范修订、生命周期和实现基线不变。双语 diff 与 RFC 状态索引检查通过。 |
关键内容讲解
英文第 11 行 将 Language mirror 明确为 Semantic mirror;中文第 11 行 写明“语义镜像(语言镜像)”。两处链接目标保持原值。消费它们的 check_rfc_language_mirrors 及 allowlist 没有修改。这些是文档标注,不是新增状态、权限或执行协议。
对主干的风险 / Risks
没有发现阻塞问题。最强反例是只补英文标记,或者用标记掩盖互链/正文错误:前者仍会在中文断言处失败。独立探针分别去掉英文标记、中文标记、破坏互链、删除中文镜像,四项均被实际 owner 拒绝;同时确认原文件未被探针改动。完整 blob 对照补充了简单字符串检查不能证明的正文保真边界。
| 验证 | 结果 |
|---|---|
| 完整 docs-governance-smoke | base FAIL:缺英文标记;head PASS,完整执行结束。 |
| 镜像、互链和正文保真 | PASS:真实正例及四个拒绝反例,原相对链接和非标签字节保留。 |
| 双语差异、RFC 状态索引、diff hygiene | PASS,均在上述 head 与实际 base 运行。 |
| CQR / quick premerge / 公开边界 | PASS;exact-scope CQR 有效,quick 整体通过:四项直接检查、语义词汇、候选来源及公开边界通过,另保留一项旧失败 advisory;公开扫描 0 errors / 0 warnings。 |
| 既有 maintainability ratchet | FAIL 保留为 advisory:base/head 完整报告只去除各自 repository_root 后相同。 |
最后一项的实际同源失败为 _admitted_interaction_next_cli_actions 的 62 decision points,原阈值 60;相关代码、检查器和配置未变,未修改阈值或将失败改绿。首次 quick 因隔离工作树缺少 TypeScript 开发依赖失败;按既有 npm ci --ignore-scripts 准备后,同一 head 重跑通过,原失败保留。按 wait_for_ci=false 未查询或等待远端 CI,不声称托管 workflow 已通过。
我的整体评价 / Verdict
交付判断为 goal_achieved,仅结清这次有独立复现的文档治理修复。long_horizon=preserved:原研究、Stride、预算与后续验收义务不变;user_experience=preserved:原有双语导航继续可达,没有新增配置或确认轮次。改动限于两份 RFC 第 11 行的互链标签;没有产品页面、布局、展开或响应式行为变化。未验证托管 Markdown 页面的视觉呈现,也未重新认证整篇 RFC 的翻译或研究结论。
两处修改复用原 owner,代码量与实际缺口相称;没有需要顺带重构的运行时边界。批准限于这个未变 head,合并权限与 GitHub 就绪度另外核验,旧维护性债务继续保留。
English verdict: APPROVE — 9d7d70a repairs the reproduced documentation-governance failure while preserving the original links, RFC bytes and rejection checks. Hosted CI and the underlying RFC implementation are not qualified here.
Goal And Delivered Outcome
Full Public Smokesdocs-governance-smoke.pyfailure introduced by RFC: joint target/yardstick selection with lightweight Stride decisions #8105.target-yardstick-stride-decisions-v0was merged without the bilingual semantic-mirror markers the governance check requires. Before:docs-governance-smoke.pyexits 1 withAssertionError: target-yardstick-stride-decisions-v0.md, then with the zh-CN mirror. After: it printsdocs-governance-smoke ok.python3 examples/docs-governance-smoke.pyfails on the missingsemantic mirror/语义镜像markers; after this change it passes.loopx-project/loopx:main.Author Declaration
Implemented against
examples/docs-governance-smoke.pyat1b636dee16, checks at lines 202-203; the merged RFC from RFC: joint target/yardstick selection with lightweight Stride decisions #8105.semantic mirrordocs/architecture/rfcs/target-yardstick-stride-decisions-v0.md:11python3 examples/docs-governance-smoke.py语义镜像docs/architecture/rfcs/target-yardstick-stride-decisions-v0.zh-CN.md:11python3 scripts/check_rfc_bilingual.py --base upstream/main --head HEADScope And Continuation
Validation
9d7d70a1aa08f0892089eb9c6676819b9c76573cintegrationpassedpython3 examples/docs-governance-smoke.py→docs-governance-smoke ok.regression_paritypassed1b636dee16with the missing-marker assertion and passes on this head.staticpassedgit diff --check;python3 scripts/check_rfc_bilingual.py --base upstream/main --head HEAD→RFC bilingual diff check passed.unitnot_runFrontend / Visual Evidence
Type of Change
LoopX Area
Technical Direction
Shared-authority RFC fixture impact
Boundary Checklist
.loopx/,.codex/goals/, and liveACTIVE_GOAL_STATE.md).python3 scripts/check_rfc_bilingual.py --base upstream/main --head HEADpasses.none.Signed-off-bytrailer (git commit -s).