# 业务地图增量回写

供需求开发、缺陷修复和文档同步共用。只复用本次定位、diff 和验证所得事实，
不为回写启动全量 scan，不重新读取整仓或全部地图；不新增任务状态或完成凭证。

## 选择地图与范围

- 先遵守目标项目 AGENTS/项目规则指定的地图路径与存储政策；已有架构/业务文档可直接作为地图，不另建同义副本。
- 未指定时使用 `docs/codebase-context/`：有 `00-index.md` 就按索引定位相关章节；目录残缺先保留现有内容，只补本次所需部分。
- 没有可用地图时，在已授权文档范围内创建最小局部地图：`00-index.md`（标明“局部地图”、已覆盖模块与未覆盖范围）和 `07-business-logic.md`（本次链路、调用/依赖、业务规则、代码依据）。不生成其余空文档、不伪造 `.scan-meta.json` 或全仓扫描完成。
- 项目明确禁止持久地图且无替代文档时，在原 handoff/缺陷档案记录本次链路与规则出处，标明“项目规则豁免”；不能写“地图已同步”。普通缺失、写入失败不属于豁免。
- 启动写入或固定宿主 scope 前确定所需路径；写入只限已批准范围，缺范围走原变更流程，禁止借回写扩大权限。符号链接越界、并发改动或权限不明时停止写入并报告。

## 开工前核实：缺失、陈旧与局部覆盖

先读索引或项目指定地图的相关章节，再核对本任务入口、直接调用方/依赖、共享状态与最近测试。
核实只读；**业务代码修改前**必须弄清本次链路与影响范围，地图写入仍须在授权 scope 内、Review 前完成。

| 情况 | 处理 |
| --- | --- |
| 无地图、无索引或只有空壳 | 从当前代码定向还原本次链路，先记入原任务计划/缺陷分析；按上节建局部地图，不能凭空补业务或先改代码后定位 |
| 只有局部地图 | 复用已覆盖部分，补查本次触及的盲区；无关区域保持“未覆盖”，不补齐十份空文档 |
| 很久未更新，但相关实现核实一致 | 继续使用，只记录本次核实范围与依据，不为刷新日期改文档 |
| 日期很新，但代码/调用关系已改变 | 以当前代码和验证为准，标出旧描述与待更新章节，审前增量纠正 |
| 无可信代码基线、切换分支或有未提交改动 | 不凭日期/HEAD 判新旧；对本次相关代码和调用关系重新核实，纳入 staged、unstaged、未跟踪文件，保留用户原改动 |
| 地图属于别的项目/子项目，或读取失败 | 不复用；先核对目标根与路径，按当前项目定向重建。若关键代码不可读或关系仍冲突，暂停依赖这些信息的修改并报告具体缺口 |

- 地图时间和文件 mtime 只是线索；若已有可信代码版本/摘要，可用其定位差异，但仍核对当前工作树与新增调用方。没有版本记录不强制补历史、不自动全扫。
- 复用本任务已读代码与核实结果；恢复任务时仅在相关文件/调用关系或任务范围变化后补查。影响扩展到共享模块，再追关联业务，不能用固定读取配额截断关键链路。
- 在原计划/缺陷分析记录“地图核实：范围、代码依据、已确认/待核实、需更新章节”；只读阶段不创建地图、不扩大写入权限。收尾结论只覆盖已核实范围，不宣称整张地图最新。

## 更新判据

| 本次变化 | 默认地图章节 |
| --- | --- |
| API 调用/接口行为 | 04-api-routes |
| 类型、实体、枚举 | 05-data-models |
| 组件、Hook、Store、模块职责 | 06-core-modules |
| 业务流程、规则、异常分支或原地图错误 | 07-business-logic |
| 目录/文件结构 | 02-directory |
| 架构、依赖方向、分层 | 03-architecture |
| 依赖、构建配置、环境变量 | 01-overview |
| 编码约定、常量、工具函数 | 08-conventions |

1. 仅读取并编辑命中的章节；项目自定地图更新对应段落。只写代码与验证支持的事实，未知关系标为待核实，不把“没读到”写成“不存在”。
2. 地图已准确描述修复后的行为、且关系/规则未变化时不改文档，记录“无需更新”及依据；地图不存在时先建局部地图，不能用“无需更新”跳过。
3. 标准目录中发生更新时，在 `09-changelog.md` 追加一条（类型 `dev回写` 或 `fix回写`），更新 `00-index.md` 的日期与实际文档链接；自定地图沿用项目记录方式，不另建日志。
4. 局部回写不得刷新 `.scan-meta.json` 的全仓扫描时间，不把局部覆盖宣称为全仓最新。保留原有用户内容和无关章节。

## 审查与收口

- **在 handoff 定稿和独立 Review 之前**完成回写；地图文件纳入 `changed_files`、实现摘要与审查范围，不在批准后顺手补文档。
- “无需更新”也要提供实际参考地图的正文与代码依据作为只读审核材料；只给路径或结论不够。只携带本次引用的地图，不加载无关章节；没有改动的地图不能伪报 `changed_files` 或增加写权限。
- 普通流程在原 handoff/缺陷档案记一行：`业务地图：已更新/已建局部地图/无需更新/项目规则豁免/待同步；路径；覆盖范围或原因`。JS 使用下节既有通道，不能手改 owner 产物或增加 schema。
- reviewer 对照真实 diff、调用链与地图核验遗漏和过时描述；收口只核对已审版本。待同步或审后漂移不能成功收口，沿原修订/复审流程处理，不重置轮次、不改历史完成事实。
- 微缺陷也评估；若需新增/修改地图使单文件门槛不成立，走完整修复流程。未改业务代码的观测/升级退出只记录现状，不冒充修复完成。

## JS 宿主边界

- `cm-ai` 沿用 N3 的 `execution.documentationSync`；`cm-fix` 在首次启动前把所需地图路径列入已批准的 `repair.scope`。默认地图 Markdown 可作为同步目标，不将待建地图伪装成根因源文件塞入 `affectedPaths`；自定地图须为诊断所涵盖的现有文件。
- 启动前将本次参考且将保留路径的**已存在地图文件**加入既有只读材料：`cm-fix` 的 `repair.requirements`、`cm-ai` run definition 的 `requirements`。计划修改但可能无实际 diff 的现有地图也须加入；这些路径不自动加入 `scope`，仍保留原必需材料。
- 已批准删除/改名的旧地图路径仅进写 scope，不进要求修后仍存在的 `requirements`；真实删除 diff 的 before 携带旧正文，迁移后新路径的 after 携带新正文。若最终没有对应 diff、正文不可见，保持待审，不临时修改持久配置或伪造改动。
- 待新建地图只列入批准的写 scope，创建后由真实 diff 携带，不能预先塞入要求文件存在的 `requirements`。Review 前核对实际包中相关地图正文可见；材料缺失沿原待审/修订路径处理，禁止在持久运行中换配置或手改已绑定包。
- JS 定位时在既有 `diagnosis.plan` 记录地图路径、覆盖范围和预计动作/无需变更依据/豁免规则（这是计划，尚非修后完成）。owner 已将 plan 带入 handoff；reviewer 对照修后地图字节与计划核验并在原 Review 中给结论，包括无需更新和豁免，不另外索取修复结果字段。
- `fix_repair` 在同一次受控修复内回写，保护模式只返回原 `edits` 提案，由 owner 写入；不能在宿主外另写地图或伪造新操作/配置字段。
- 在途运行的固定 scope 缺地图路径时报告阻断，沿现有变更/恢复规则处理；不能修改持久配置、扩大 scope 或新建身份绕过。以上是 Skill 执行要求，现有 JS 字节/范围门禁不自动判断业务地图内容是否完整。