ship-workflow-doc-sync

name	ship-workflow-doc-sync
description	发布后文档同步。当代码已合并需要同步更新项目文档，或提到"文档同步""CHANGELOG""README 更新"

Doc Sync — 发布后文档同步

入口/出口

• 入口: 已合并到主分支的变更
• 出口: 文档一致性报告
• 指向: 完成后进入 reflect-team-documentation（可选）或回到项目工作
• 前置加载: CANON.md
• 输出路径: 完成后进入 ship-workflow-ship

何时不使用

• 代码或产物尚未合并，文档同步会基于不稳定事实
• 只是写新功能文档，不是发布后修正项目真相
• 变更没有影响 README、架构说明、命令、路径、版本或用户文档

核心锚点

Fact vs Narrative Dichotomy

区分事实性更新（路径、版本号、数量、命令）和叙事性变更（功能描述、架构理由、迁移指南）。事实直接改；叙事必须问 human partner。

执行规则：

• 事实性更新（路径/版本/数量/命令/配置字段/链接/拼写）→ 直接执行，不询问
• 叙事性变更（新功能描述/架构理由/新增章节/迁移指南/弃用通知/项目定位）→ 逐条询问 human partner
• 混淆两者 = 文档失去人的视角 = 文档变成谎言

流程

Step 1：Diff 分析

收集合并 commit 涉及的文件：git diff-tree --no-commit-id --name-only -r <merge-sha>

分类变更：代码文件 → 影响 README/ARCHITECTURE/API 文档；配置文件 → 影响部署章节；依赖文件 → 影响安装文档；CI/CD 文件 → 影响 CONTRIBUTING。

Step 2：逐文档审计

交叉引用变更文件与项目文档。检查维度：

文档	检查内容
README.md	项目描述、安装步骤、快速开始、特性列表
CLAUDE.md	命令映射、技能列表、项目结构
AGENTS.md	入口合同、激活门、命令映射
docs/contracts/*.md	运行时详细规则（按需加载）
ARCHITECTURE.md	组件关系、数据流、技术栈
CHANGELOG.md	版本条目、变更类型
CONTRIBUTING.md	开发流程、PR 规则、CI 说明

Step 3：自动更新事实性内容

对事实性不一致直接修复。每处修改记录到文档一致性报告。不修改叙事性内容，不添加新章节。数量变更必须先验证实际数量。

Step 4：询问叙事性变更

对叙事性不一致逐条询问 human partner，每次一个问题。每个问题包含：文件路径 + 具体位置 + 当前内容 + 变更原因。human partner 提供新内容或选择跳过。不替 human partner 写叙事性内容。

Step 5：CHANGELOG 润色

检查 CHANGELOG.md 最新条目。绝不覆盖或删除历史条目。只润色最新条目措辞（更清晰、更一致），保持与已有格式一致。变更类型：Added / Changed / Fixed / Deprecated / Removed / Security，每条以动词开头。

Step 6：跨文档一致性检查

验证同一事实在所有文档中表述一致：版本号、特性列表、组件列表、命令列表、API 端点。不一致时以代码为真实来源更新文档。

Step 7：可发现性检查

确认每个文档都能从入口点（README.md 或 CLAUDE.md）通过链接到达。孤立文档需添加引用。

验证证据

输出或记录必须包含：输入/来源、执行动作、验证结果、阻塞/回退。

常见说辞

说辞	现实	后果
"文档以后再更新"	"以后"永远不会来。代码变更时同步更新成本最低。	事后补文档耗时 ×3-5；新人按旧文档操作 = 环境 +2h
"CHANGELOG 自己写就行"	AI 润色措辞，变更的业务意义只有 human partner 知道。	叙事不准确 → 用户误解变更影响 → 升级决策失误
"README 不需要那么详细"	README 是新人的第一个文件。少一个步骤 = 新人多花一小时。	每个新人多花 1h × 10 人 = 10h 团队浪费
"这个文档没人看"	没人看是因为过时了。保持准确的文档会被发现和使用。	过时 → 信任崩塌 → 团队不再参考任何文档
"自动更新就行，不用问"	事实自动更新。叙事、判断、理由不能。	自动写叙事 → 措辞不符真实意图 → 文档变成谎言

红旗

• 不区分事实性更新和叙事性变更，全部自动修改
• 修改或删除 CHANGELOG 中的历史条目
• 不验证实际数量就更新文档中的数字
• 添加 human partner 不知道的新章节
• 跳过跨文档一致性检查
• 文档中有无法从入口点到达的孤立页面
• 以"文档不重要"为由跳过整个同步流程
• 一次列出多个问题让 human partner 批量回答

验证失败处理

验证项	失败表现	处理方式
变更文件识别不全	部分合并文件未被发现	扩展 diff 范围；检查 submodule 和生成文件
事实性更新未执行	路径/版本/数量仍不一致	立即修正；事实性更新不停顿
叙事性变更未询问	AI 替 human partner 写了描述	回滚叙事性修改；逐条询问
CHANGELOG 历史被修改	旧条目被删除或重写	恢复历史条目；只允许润色最新条目
跨文档数量不一致	README 与代码不符	以代码为真实来源，验证后更新所有文档

输出模板

文档同步完成：

事实性更新（已自动执行）:
  - [文件]: [变更描述] (old → new)

叙事性更新（已询问 human partner）:
  - [文件] [位置]: 已更新 (user provided) / 跳过 (user declined)

CHANGELOG:
  - 最新条目措辞已润色
  - 历史条目: 未修改

一致性检查:
  - 版本号: 一致 / 不一致 → 已修复
  - 特性列表: 一致 / 不一致 → 已修复
  - 组件列表: 一致 / 不一致 → 已修复
  - 命令列表: 一致 / 不一致 → 已修复
  - API 端点: 一致 / 不一致 → 已修复

可发现性:
  - 所有文档可从入口点到达 / [孤立文档] → 已添加引用

验证清单

• 所有变更文件已识别并分类
• 事实性更新已自动执行并记录
• 叙事性变更已逐条询问 human partner
• CHANGELOG 仅润色最新条目，历史未动
• 版本号跨文档一致
• 特性列表跨文档一致
• 组件列表跨文档一致
• 所有文档可从入口点到达
• 文档一致性报告已输出