文档唯一来源维护规则

文档唯一来源维护规则

本文用于解决 root-remote 中“同一主题在多个目录看起来都能改”的问题。

原则只有一条：

每类事实只保留一个权威源；镜像、历史规格和运行时切片必须写清派生关系。

1. 维护总规则

类型	允许存在几份	维护要求
当前产品事实	一份	只在权威目录更新，其他位置只放链接或历史说明
运行时镜像	可有一份镜像	必须标明上游源，并用脚本同步
历史规格 / Prompt	可保留	必须标明日期、用途和“不再作为当前事实源”
决策草稿	临时存在	收口后要么并入权威源，要么归档

2. yomiya-dev-flow 如何维护

层级	路径	定位
政策源	team-consensus/dev-workflow.md	Yomiya 研发流转唯一政策源
运行时源	skills/yomiya-dev-flow/	OpenClaw / workspace skill 的可安装源
兼容镜像	.agents/skills/yomiya-dev-flow/	Kimi 系 project skill 发现路径

维护顺序固定为：

1. 先改 team-consensus/dev-workflow.md 的政策口径。
2. 再改 skills/yomiya-dev-flow/ 的运行时切片。
3. 执行 scripts/sync-skill-mirrors.sh 同步 .agents/skills/yomiya-dev-flow/。
4. 跑 python3 scripts/validate_yomiya_workflow.py 复核。

禁止：

• 直接在 .agents/skills/yomiya-dev-flow/ 单独改规则。
• 让 skills/yomiya-dev-flow/references/full-workflow.md 反向覆盖政策源。
• 为了“看起来只有一份”删除兼容镜像，导致 skill 发现路径失效。

3. YomiyaOnboarding 如何维护

路径	定位
product/YomiyaOnboarding/README.md 与 01-05 文档	当前中文事实入口
EveryDayJapanese-iOS/pencil/EveryDayJapanese-iOS.pen	当前设计源
docs/superpowers/specs/2026-04-11-yomiya-onboarding-*	历史设计输入、Prompt 和 Stitch 资料

当前 onboarding 的事实口径只在 product/YomiyaOnboarding/ 维护。

docs/superpowers/specs/ 中 2026-04-11 的 onboarding 文档可以继续保留，用于追溯当时的设计推导和第三方 Prompt；但它们不再承担当前屏数、当前实现顺序、当前 Pencil 结论的更新职责。

维护时执行：

1. 当前产品结论改 product/YomiyaOnboarding/。
2. 当前设计改 Pencil 源文件及其对应实现仓库。
3. 历史 specs 只允许补边界说明、追溯链接和归档说明。

4. 中文可读规则

长期维护文档默认中文可读：

• 标题、结论、维护规则和风险说明必须用中文。
• 命令、字段名、API 名、代码路径按原样保留。
• 给第三方模型的 Prompt 可保留英文，但文件头必须先用中文说明用途、日期、当前事实源。
• 如果同主题已经有中文权威文档，不再新增英文平行版本。

5. 收口检查

每次新增或重写文档前先回答：

1. 这份文档写的是当前事实、运行时镜像、历史资料，还是临时草稿？
2. 它的唯一上游源在哪里？
3. 后续维护者会不会误以为它也能独立更新？

只要第 3 个问题答案是“会”，就要补入口说明、归档标记或同步脚本。