# 架构文档同步工作流

## 1. 目标与边界

当用户要求“更新项目文档”或“同步架构文档”时，先只读分析影响，得到明确确认后，再局部同步当前实现文档。

运行时只允许修改：

- `core/backend/ARCHITECTURE.md`
- `core/frontend/ARCHITECTURE.md`

禁止修改：

- `core/ARCHITECTURE.md`
- 任何业务代码、配置、迁移、测试和部署文件
- Git 暂存区、commit、push 和远端状态
- 本工作流、扫描脚本和 Skill 自身

不得访问或输出 `.env`、`account.md`、密钥、数据库文件、用户上传文件及其他敏感信息。

## 2. 基本原则

- 默认只读；没有有效确认时不得写文件。
- 使用扫描脚本提取事实，不用 AI 全量阅读项目代替扫描。
- 只读取扫描结果列出的证据文件和目标章节。
- 只做局部补丁，不整份重写文档。
- 保留原章节、历史决策和规划内容。
- 明确区分“当前实现”与“目标架构”。
- 无法从代码证实时，跳过并报告，不推测补写。
- 不覆盖或整理与本次任务无关的用户改动。
- 每次写入后必须验证；验证失败时停止，不扩大范围补救。

## 3. 状态机

```text
IDLE
  → ANALYZE_READ_ONLY
  → WAIT_CONFIRMATION
  → REVALIDATE_PLAN
  → UPDATE_ALLOWED_DOCS
  → VERIFY
  → DONE
```

任何异常进入 `STOPPED`，报告原因并等待用户决定。

## 4. 阶段 A：只读分析

1. 使用 Git 确定仓库根目录。
2. 确认 `tools/architecture-sync/scan_architecture.py` 存在；不存在则报告安装未完成并停止，不回退为全量 AI 扫描。
3. 运行扫描器的 `plan` 模式；默认使用 `--scope all`，用户明确只处理后端或前端时分别使用 `--scope backend` 或 `--scope frontend`。
4. 解析扫描器 JSON；不得自行扩大 `changed_files`、`evidence` 或目标文档范围。
5. 若 `analysis_ready` 不为 `true`，说明扫描器的影响分析能力尚未安装完整并停止，不得进入确认或写入阶段。
6. 若 `requires_update=false`，说明没有架构性变化并结束，不修改文件。
7. 若存在影响，将扫描器返回的 `plan_id`、`scope`、`snapshot_id`、目标文档指纹和 `planned_updates` 作为当前对话唯一待确认计划，按“影响预览”格式展示，然后强制停止并等待确认；不得预先修改文件。

影响预览必须包含：

- `plan_id`。
- 发现的架构变化。
- 每项变化的证据文件。
- 准备修改的文档和章节。
- 明确不会修改的范围。
- 扫描警告和无法确认的事项。

使用以下输出结构：

```text
架构文档更新计划：<plan_id>
更新范围：<scope>

发现的架构变化：
1. <变化>
   - 依据：<证据文件或符号>
   - 影响：<目标文档> · <章节>

准备修改：
- <目标文档> · <章节>

不会修改：
- core/ARCHITECTURE.md
- 业务代码、配置、迁移、测试和部署文件
- Git 暂存、commit、push

警告或待确认：
- <没有则写“无”>

是否确认更新？请回复：确认更新项目文档
```

## 5. 确认规则

有效确认必须同时满足：

- 当前对话存在尚未执行的影响预览。
- 用户确认的必须是当前唯一待确认 `plan_id`，旧计划、已执行计划和被新请求替代的计划均无效。
- 用户在预览后回复 `确认更新项目文档`；同一连续对话中也可接受明确的 `确认`。
- 用户没有改变目标、排除项或更新范围。
- 待确认计划没有被新的请求替代。

新对话中的单独“确认”、含糊回复、提前确认或针对其他任务的确认均无效。

用户拒绝、改变范围或提出新约束时，立即丢弃旧 `plan_id`，使用新的 `scope` 或约束返回阶段 A 重新生成并展示计划；不得沿用旧确认。

## 6. 阶段 B：确认后重新校验

写文件前必须使用与待确认计划完全相同的 `--scope` 重新运行 `plan`：

- 新 `plan_id` 与已确认值一致，才可继续。
- 证据文件、目标章节或目标文档发生变化时，展示新计划并重新确认。
- 目标文档自计划生成后被其他操作修改时，停止并重新计划。
- 扫描器返回警告升级、敏感文件或越界路径时，停止。

确认只授权当前 `plan_id`，不授权未来变化。

## 7. 局部更新规则

阶段 B 重校验通过后，锁定扫描器返回的 `update_context`，不得自行扩大范围：

1. 校验 `update_context.plan_id` 等于已确认 `plan_id`，并校验每个 `document_preconditions.before_sha256` 仍与目标文档一致；任一不一致立即停止并重新规划。
2. 将 `evidence_allowlist` 视为最大读取白名单，只选取证明当前影响所必需的文件；禁止因方便而遍历其他代码。
3. 目标文档只读取 `document_preconditions.sections` 指定章节及定位标题所需的相邻行；不把整篇文档交给 AI 重写。
4. 根据证据判断这是当前实现变化、规划变化还是普通业务修复；普通业务修复没有改变架构边界时，跳过该影响。
5. 使用 `apply_patch` 对一个文档、一个局部事实逐项修改；禁止生成整篇替换内容或用脚本重写 Markdown。
6. 保留标题层级、术语、相对链接、风险说明、演进原则、历史决策和原有写作风格。
7. 当前实现与历史设计或目标架构并存时，保留原内容并明确标注“当前实现”与“目标架构”，不得用当前代码覆盖历史决策。
8. 正文事实确实发生变化时，将文首“最后核对”更新为执行当日日期，并将同步标记设置为 `update_context.sync_metadata.marker`；标记必须使用完整小写 HEAD SHA，且每份文档只能存在一条。
9. 对缺少同步标记的 `baseline_review`，若证据核对后正文已经准确，允许只新增首次同步标记并更新“最后核对”日期；不得借首次基线核对改写无关正文。
10. 若 `has_uncommitted_evidence=true`，同步标记仍只表示当前 HEAD；结果中必须说明包含了工作区证据，后续代码提交后需要再次扫描。
11. 修改完成后直接进入阶段 C；不得执行 `git add`、`git commit`、`git push`，也不得生成或保存临时计划文件。

禁止：

- 删除未受影响章节。
- 为了“精简”覆盖整个文件。
- 把规划内容改写成已实现事实。
- 把暂时未使用的历史决策直接删除。
- 根据文件名猜测实现细节。
- 顺手修复代码、格式化其他文件或清理工作区。
- 在没有有效确认时执行以上任何写入步骤。

## 8. 阶段 C：验证

更新后必须使用原计划令牌运行：

```text
python tools/architecture-sync/scan_architecture.py verify --scope <原 scope> --guard <update_context.verification_guard>
```

不得省略、修改或跨计划复用校验令牌。只有 `verification.status=passed` 才能完成流程。验证器检查：

- 本流程新增的文件修改是否仅落在两个允许文档。
- 计划外的目标章节是否保持不变。
- 原有一级、二级标题是否被误删。
- 文档引用的目录、文件和关键符号是否存在。
- 相对链接是否有效。
- 是否引入本机绝对路径、敏感信息或裸密钥。
- 是否出现异常大范围删除或整篇覆盖。
- Markdown 格式是否有效。
- 计划生成后 HEAD、相关代码指纹、证据文件和同步控制文件是否发生漂移。

验证失败：

- 停止流程并列出失败项。
- 按验证器返回的 `code`、`message` 和 `suggestion` 向用户说明原因；不得绕过失败项。
- 不自动修改业务代码来迁就文档。
- 不自动扩大写入白名单。
- 不暂存、不提交、不推送。

验证通过后输出：

```text
架构文档已更新：
- <文档> · <章节>：<一句话变化>

验证：通过
未执行：业务代码修改、git add、commit、push
```

## 9. 工作区保护

- 阶段 A 记录目标文档摘要和现有工作区变化，阶段 B 用于漂移检查。
- 已存在的用户改动属于用户，不得覆盖、回滚、暂存或提交。
- 如果现有改动与目标章节重叠且不能安全合并，停止并请求用户处理。
- 不使用 `git reset`、`git checkout --` 或任何破坏性恢复命令。

## 10. 安装与能力缺失

缺少扫描脚本、Python、Git、读取权限或写入权限时：

- 明确指出缺少的能力。
- 保持只读并停止。
- 不改用无约束的全项目 AI 扫描。
- 不建议扩大业务服务权限或让线上服务访问 Git 仓库。