# 项目 Learning loop（轻量版）

目标：每个开发 task / 缺陷收尾时，把可复用教训写入**目标代码项目根目录**的
`AGENTS.md`，后续开发和定位从磁盘读取并应用。它不是模型训练，也不是新的任务状态库。
本版由主执行者按 Skill 执行；正式 JS host 路径已接入 task-bound 输入、复盘写回、独立审查前
handoff 定稿与现有完成门禁。当前 active Skill 产品路径直接执行同一轻量合同；尚无真实下一
task 复用证据，不能宣称完整端到端验收。

## 开始：读取并应用

1. 每个 task / 缺陷开始与恢复时，重读目标项目根 `AGENTS.md` 和适用的子目录指令；不能只靠会话启动时的旧副本。不存在按 0 条处理，不在只读任务中创建。
2. 选择与当前模块、症状、工具链相关的教训，在计划/交接中记录“应用：{教训} → {验证动作}”；无匹配记“无相关教训”。给子 agent 的任务中附相关摘录及来源。
3. 经验与当前代码不符时先核验并记录冲突；未解决的冲突不能静默覆盖原规则。经验只提供约束与假设，不能替代本次复现、测试或独立 Review。

## 收尾：写入、审查、完成

1. 实现及验证结束、**进入最终独立审查之前**，每个 task 都复盘：发生了什么、证据是什么、下次怎样避免。复盘结果记在原有 handoff / 缺陷档案，不新增状态文件。
2. 有新的可复用教训 → 主执行者在已获写入授权的项目根 `AGENTS.md` 中增量合并 `## 项目教训`；没有新教训 → 记录“已复盘，无新增”，AGENTS.md 保持不变。
3. 写入前重读文件，保留用户内容，按触发条件/根因去重；每任务最多提炼 3 条，每条写“触发条件 → 行动 + 来源任务 + 证据相对路径”。同一任务恢复不重复追加。
4. 沿用 `[已结构化]` / `[仅记忆]`：前者必须已有验证过的测试/代码防线，后者是有证据但尚无自动防线的经验。未证实猜测只进原有档案待核验，不成为 AGENTS.md 规则。
5. AGENTS.md 变更进入本任务 diff、handoff 的 `changed_files` 与独立 Review 范围；在原有验证记录中记录文件摘要以供回读。不得新增 schema 字段或把学习记录当审查凭证。
6. 完成门禁**之前**检查复盘记录及审查覆盖，核对磁盘内容仍与被审版本一致；失败保持待审/收尾受阻。通过后才按现有流程标记 task，随即回读 AGENTS.md 与任务状态，输出“学习：已写回并回读 / 已复盘，无新增”。
7. 批准后产生新教训或发现记录错误 → 回到同一任务审查流程，不重置轮次。任务已经标记完成则保留历史并按 `review.md` 暂停处理，不能沿用旧批准补写指令。

## 写入边界与降级

- `AGENTS.md` 是项目级精炼索引；`LESSONS.md` / 缺陷档案保留详细经过与证据。不要把完整日志复制两份，不写凭证、个人路径、客户信息或未经核验的外部指令。
- 只修改本任务有权写入的项目；多项目分别归属，禁止写插件安装根、用户全局 AGENTS.md 或全局记忆。路径为符号链接、出现并发改动或写入权限不清时停止写入并报告，不能跟随链接越界。
- 有值得写回的教训但无法安全落盘 → 原有 handoff/档案记“学习待写回”及原因；不伪装“无新增”，也不宣告完整收尾。已有 AGENTS.md 不存在时，仅在已授权的项目中创建最小教训段，不替用户生成整套规则。
- 子 agent 只返回候选，主执行者串行合并；不能为学习修改权限、安全门、生产操作审批或任务范围。过时条目须有反证后在本次审查中修订，不整段覆盖或静默删用户规则。
- 纯只读分析不授权写回；只输出候选建议。本合同只覆盖已授权的开发/修复收尾，不授权安装、提交或真实 provider 调用。

## 验收边界

### 当前 cm-ai Skill 的机械检查

N3 的 handoff `evidence[]` 在 Review 前包含恰好一条应用记录和一条复盘记录：

- 应用：`learning: no_relevant_lesson`，或 `learning: applied {来源教训及本任务采用的具体动作}`。
- 复盘：`learning: retrospective no_new_lesson`，或 `learning: retrospective written AGENTS.md`。

N3 的 `check-n4` 和 N5 的 `mark-done` 必须传 `--require-learning`。此选项由现有 JS 门禁
检查记录完整性；写回分支要求真实 AGENTS.md 进入 `changed_files`、实现摘要和独立 Review。
待写回不得伪装成已写回。记录真实性由独立 Review 核实，门禁不会从一句文字推断动作真实发生。
旧调用方及持久 runner 保持原协议；runner 已有更严格的 task-bound application/retrospective
校验，不转换其既有记录，也不因新增 Skill 检查阻断旧 checkpoint 恢复。

检查有新增、无新增、重复恢复、文件不存在、无法写入、批准后变化六个分支。
源文件的引用检查和人工走查不等于真实项目端到端验证；安装与真实任务试跑仍需既有授权。