用途
sync 用于保持 keel 文档与实际实现进度一致，检测偏差并更新状态，处理文档与代码漂移。其核心思路是：文档是计划，代码是实现，偏差是正常的，关键是及时同步；同步应双向进行——文档→代码（指导）与代码→文档（记录）。
主要能力
默认模式（/sync）会串行执行三段流程：
- trace 阶段：校验追溯矩阵的「变更来源」列（不扫描代码，因为代码里没有 keel 编号）。
- audit 阶段：检测编号体系完整性，防止文档维护债积累，检查 AC 覆盖、F 任务闭环、INS 转化、孤立编号、CON 闭环、needs review 未闭合项报龄。
- check 阶段：输出偏差报告与 health report；schema drift 诊断统一委托 /verify --schema-drift，本技能只合并其结果。
默认流程会先返回检查结果并等待写入确认，用户未确认时不生成进度报告也不更新文档。低风险偏差按 absorb 规则自动吸收，高风险需确认。
归档模式（/sync --archive [requirements|design|tests|tasks] [--release v1.0.0]）支持所有文档类型的归档，控制文档膨胀并保留历史记录：需求（功能已完成/已废弃）、设计（关联功能已归档）、测试（关联 AC 已归档）、任务（已完成 > 15 个）。归档时支持级联，归档 F-001 时可同时归档关联的设计、测试、任务。
反向同步模式（/sync --back-propagate-prd）仅在用户显式调用时执行，将 keel 需求变更反向同步到 PRD 映射表：定位 docs/prd/requirements/index.md（未找到则提示无需反向同步），读取 docs/devdocs/01-requirements.md 的 F-XXX 列表，对比映射表后标注新增（无 prd 来源）、废弃（mapping_status: removed）或保持已有映射，最后更新 index.md 的「keel 映射」章节。写权限边界：只允许修改该章节，若不存在只允许在文末创建，不重排其他章节，只写映射状态，不改 FR 内容。
工作流程
- 读取 keel 文档。
- 扫描代码库（工作区状态）：检查文件是否存在（Glob）、运行测试获取实时结果、检查未提交变更（git status）、参考提交记录（git log，辅助）。检查基于当前工作区状态，而非仅依赖 git 提交历史。
- 对比分析任务完成状态、测试覆盖情况、功能实现状态。
- 生成偏差报告。
- 询问用户确认更新。
- 更新文档。
输出文件
确认写入后生成 docs/devdocs/00-progress-report.md，包含总体进度、偏差汇总、下一步建议。检查-only 内部调用时为空。
偏差修复路由
检测到偏差时必须在报告中指派下一步修复 Skill：设计缺失/漂移→/system-design；AC 缺测试→/test-cases；F 缺任务闭环→/dev-tasks；代码已实现文档落后→/sync（低风险吸收）；追溯矩阵代码位置缺失→/sync。
使用时机与协作
适用于用户完成一个或多个开发任务后、要求检查文档与代码一致性、需要更新文档进度、定期同步（如 Sprint 结束时）。与 /dev-workflow、/dev-tasks、/test-cases、/feature、/bugfix、/insights、/retrofit 等技能协作。任务完成后可直接运行 /sync。同一会话内的低风险变更合并为文档级批量确认。
约束
检查约束：必须读取所有 keel 文档后再检查，必须生成偏差报告，更新文档前必须询问用户确认（吸收模式低风险除外），检查结果必须可追溯。更新约束：不自动删除文档内容只标记状态，不自动修改代码只更新文档，更新时记录时间戳。吸收模式约束：低风险吸收仅限状态字段更新，新增内容必须指定关联编号（AC/F/US），无法确定关联的内容标记为「待手动处理」。安全约束：不执行未知的 shell 命令，测试命令使用项目配置的命令。
限制
不适合用于验证对齐（应使用 /verify）或提取经验（应使用 /compound）。当技能作为子 Agent 运行时，返回结构化摘要，包含 status、summary（headline、mode、internal_operations、trace_results、audit_results、deviations）、blockers、output_files、new_ids、next_recommended 等字段。
参考资料：absorb-mode.md、audit-mode.md、trace-mode.md、archive.md、examples.md。