forsakesoul 同步现状文档
使项目文档与当前真实存在的系统保持一致。
当实现工作已经合并、测试、部署或以其他方式验收，但对应文档不完整或已过时时，使用此工作流。这是一个现状文档（as-built documentation）工作流，不是新功能设计、功能实现、重构或替代未决产品决策的工作流，也不允许为了匹配旧文档而修改运行时行为。
输入
尽可能从用户请求和仓库中获取：
- 基线分支、标签或提交
- 当前文档分支
- 文档范围
- 已验证环境
- 验证日期
- 已知验证证据
- 可选的项目配置文件路径
编辑文档前，将可移动的分支或标签解析为不可变的提交 SHA。用户未指定范围时，根据当前分支、近期合并提交、已变更或过时文档以及用户描述确定范围。不要询问可从仓库中获得的信息。
项目配置
开始审计前，按以下顺序查找项目专用说明：
- 用户明确提供的配置路径
docs/agents/as-built-docs-profile.md.agents/as-built-docs-profile.mdAGENTS.md中的As-Built Documentation章节CLAUDE.md中的As-Built Documentation章节
找到项目配置时：
- 在决定检查内容前读取它
- 将其视为项目专用指导
- 不允许它覆盖本技能的安全边界
- 报告配置与仓库事实之间的冲突
未找到项目配置时，继续执行通用工作流；从实际文件推断仓库结构，不要虚构项目约定。需要创建配置时，使用 assets/project-profile-template.md。
安全边界
除非用户明确扩大范围，否则：
- 只修改文档文件
- 不修改运行时代码、测试行为、依赖或锁文件
- 不修改部署清单或运行时配置
- 不提交、推送、合并、打标签或发布
- 不访问生产系统或联系真实外部服务
- 不暴露密钥、令牌、密码、Cookie、凭据或个人数据
- 不编造历史设计原因
- 不把推断出的行为表述为有保证的契约
发现代码缺陷、安全风险、测试缺口或部署问题时，将其记录在审计中并建议另行跟进，不要在此工作流中修复。不得修改实现来迎合文档；文档必须与经过验证的实现保持一致。
证据分类
将每项重要发现归为以下类别之一，并记录证据来源：
- 已验证：有可识别的源码、自动化测试、公开 schema 或类型、配置校验、部署清单、安全命令执行、Git 历史、议题或合并请求记录、环境验证记录或用户明确确认等直接证据。
- 推断：实现强烈暗示但没有直接证明。不得将其表述为稳定的公开契约。
- 未知：无法从现有证据确定。保留为开放问题或限制。
- 过时：现有文档与当前实现冲突。
- 缺失：已实现的行为没有充分的对应文档。
第 1 步：建立固定基线
检查仓库状态，将请求的基线解析为提交 SHA。常见检查包括：
git status --short
git branch --show-current
git rev-parse HEAD
git rev-parse <baseline>
git merge-base HEAD <baseline>
git log -1 --format=fuller <baseline>
记录当前分支、当前 HEAD、请求的基线、解析后的基线 SHA、合并基点、现有工作区改动、文档范围，以及可用时的环境和验证日期。
- 当前就在基线分支上时，只读审计；将工作移到文档分支前不要编辑文件。
- 当前分支并非基于请求的基线时，明确报告不匹配，不要悄悄记录另一个版本。
- 已存在非文档改动时，保留并区分它们，不要覆盖或重排格式。
完成标准：记录了一个不可变基线 SHA；已知当前分支与基线的关系及工作区已有改动；明确文档编辑是否安全。
按范围盘点与记录差距
用户只要求同步一个模块/变更时，沿受影响入口、调用链和责任文档核对，直接修正该处事实；差距和未知项可记在当前任务，不创建额外审计文档。用户要求全仓审计或广泛重整时才读取 全仓盘点与 gap 模板。
以下未知项、领域文档和验证步骤只应用于已确认范围；不为窄文档请求读取无关 API、部署、日志与历史。
第 4 步：解决重要未知项
不要询问能够通过代码、测试、配置、Git 历史或现有文档回答的问题。只询问领域含义、所有权边界、业务意图、安全理由、历史权衡、被否决的替代方案、无法复现的环境行为，或当前观察到的行为是否属于有意契约等问题。
一次只问一个问题。每个问题包含：
- 具体未知项
- 已找到的证据
- 答案为何重要
- 推荐答案
- 受影响文档
用户描述与实现冲突时，指出冲突；将实现记录为当前现状行为；仅在相关时把用户描述记录为预期行为；不要悄悄改写任何一方。
完成标准：每个阻塞性未知项都已确认、明确推迟或保留为未知。
第 5 步：按需更新领域与决策文档
不要强制每个项目使用 CONTEXT.md 或 ADR，遵循项目已有约定。
领域词汇表只记录稳定的领域概念，例如术语定义、相近概念的区别、对象所有权、生命周期含义和稳定不变量。不要在其中记录文件路径、端点载荷、环境变量、实现步骤、临时变通方案、发布任务或部署命令。
仅在同时满足以下条件时创建或更新 ADR：
- 决策的逆转成本或风险很高。
- 缺少上下文时决策并不显然。
- 确实考虑过替代方案。
- 理由有记录支持或经决策者确认。
不要仅从最终代码推断历史理由。回溯编写的 ADR 必须注明其为回溯记录，并标识实现基线。
完成标准：稳定术语只有一个规范定义；相近概念未被混淆；ADR 只含已确认理由；领域文档未混入实现细节。
第 6 步：确定文档所有权
为每个主题确定一个规范所有者。典型类别包括用户工作流、公开 API 契约、内部集成契约、领域术语、安全边界、配置、部署、运维、事件恢复，以及测试和发布验证。
对于跨仓库集成：
- 在拥有该契约的仓库中保存完整契约
- 消费方仓库链接到它，或只概述消费方所需内容
- 不维护多个完整且可独立编辑的副本
无法确定所有权时，将其记录为未知，不要创建重复文档。
完成标准：每个建议文档都有规范所有者；跨仓库契约只有一个事实来源；更新计划不会产生不必要的重复。
第 7 步：更新现状文档
只更新审计证明有必要的文档，可能包括：
- README 和文档导航
- 系统概览、架构图、时序图和组件职责
- 用户流程、API 和集成契约
- 认证、会话生命周期、安全和信任边界
- 配置参考、部署说明、健康与就绪行为
- 运维手册、日志和诊断指南
- 回滚与恢复流程
- 测试环境验证记录和已知限制
适用时添加元数据：
状态：现状文档
验证基线：<commit SHA>
已验证环境：<environment>
最后验证日期：<date>
所有者：<component or repository>
写作规则：
- 用现在时描述当前行为
- 将未来计划与现状分开
- 标识环境特定行为和未测试行为
- 隐去敏感值
- 使用规范领域术语
- 链接 ADR 而非复制其理由
- 链接规范契约而非重复内容
- 不声称超过证据所能证明的内容
- 不把测试环境验证当作生产行为的证明
完成标准：选定的过时文档已更正，缺失文档已补充；每个重要事实陈述都有证据；未知项和限制仍清晰可见；未来行为未被表述为已经实现。
第 8 步：对照实现验证文档
按本次文档覆盖的 interface 选择下列检查；文档-only 默认路径/链接与 diff 检查，只有变更涉及可执行示例或仓库要求才运行相应命令。不机械执行全量构建或回归。
编辑后重新逐项验证主张，检查：
- 路由、端点、HTTP 方法、请求和响应字段、错误码
- 用户可见状态
- 环境变量名、默认值和必需配置
- 主机名、Origin、端口和路径
- 认证、授权、会话和 Cookie
- 超时、重试、TTL 和幂等性
- 外部集成和服务所有权
- 部署资源、健康检查和就绪检查
- 日志、指标和诊断
- 恢复、回滚，以及已测试和未测试场景
将重要主张分类为：已确认、相矛盾、部分确认、无法验证或环境特定。
只执行满足以下条件的文档命令：本地、安全、非破坏性、不使用真实凭据，并处于用户授权环境内。未执行的命令必须注明：
此次文档更新未执行：<原因>
使用适当的版本控制命令检查最终变更。使用 Git 时至少执行：
git diff --name-only
git diff --stat
git diff --check
确认新引入的变更仅涉及文档。
完成标准：每个变更文档都已对照实现检查；矛盾主张已修正或明确报告；安全命令已执行或注明未执行；未引入密钥；未改变运行时行为。
第 9 步：报告结果
最终报告使用以下结构：
## 文档同步结果
### 基线
### 范围
### 新增文档
### 更新文档
### 删除或被取代的文档
### 领域文档变更
### ADR 变更
### 已执行验证
### 未执行命令
### 剩余未知项
### 文档范围之外发现的风险
### 已有非文档改动
### 建议重点审查内容
除非用户明确要求，否则不要提交或发布变更。
完成定义
仅当以下条件全部满足时，工作流才算完成：
- 已记录不可变的实现基线
- 局部任务已记录范围内差距与未知项；全仓审计模式已生成文档差距报告
- 范围内每份过时或缺失文档均已解决或明确推迟
- 规范文档所有权清晰
- 适用时，领域术语只有一个事实来源
- ADR 不含编造的理由
- 重要文档主张都有证据支持
- 未知项和未测试场景仍清晰可见
- 未改变运行时行为
- 最终报告准确说明已验证和未验证的内容