@xgent-ai/skills 0.4.0 → 0.6.0

package/skills/agi-mode/references/workspace-layout.md

@@ -0,0 +1,76 @@
+# 状态目录与原文档边界
+
+`.xgent-ai/` 是 agi-mode 的工作状态目录，开发生命周期的状态放在 `.xgent-ai/sdlc/`。**`sdlc/` 只放状态及其索引、协议、事件，不存放或复制 PRD、开发计划、评审报告、实施/验收记录、测试计划、日志、截图或原始证据。** 这些原产物的位置由用户习惯、项目约定与已有链接决定，本约定不改变各写作和评审技能的原文档落盘规则。
+
+只读查询不创建目录；初始化和更新仅保存必要的状态文件，不为统一目录而搬迁或重命名原文档。
+
+## 状态布局
+
+```text
+.xgent-ai/
+  index.md                     工作状态总入口
+  experience/                  开发经验收件箱，首次有效记录时创建
+    index.md                   任务记录导航
+    <task-id>.md              简短观察、证据链接及复盘处置
+  tasks/                       非开发任务按需创建
+    index.md                   任务目录
+    <task-id>/
+      index.md                 本任务状态文件入口
+      state.md                 恢复状态
+  sdlc/
+    index.md                   分类导航与当前重点
+    protocol.md                项目内可独立执行的状态回写协议
+    state-model.md             固定状态、证据门槛与自愈规则
+    event-template.md          单次状态变化记录模板
+    status/
+      index.md                 状态类型导航
+      prd/index.md             PRD 状态索引
+      prd/<object-id>.md       每份 PRD 的状态与原文链接
+      plan/index.md            开发计划状态索引
+      plan/<object-id>.md      每份计划的就绪、实施进度和记录链接
+      review/index.md          评审状态索引
+      review/<object-id>.md    每轮评审的结论、整改状态和报告链接
+    events/
+      index.md                 事件类型导航
+      <kind>/
+        index.md               对象事件目录
+        <object-id>/
+          index.md             本对象事件清单
+          <event-id>.md        每次状态变化一文件
+```
+
+按需创建，不预建空对象。无计划的开发任务需要恢复状态时，可增加 `status/task/` 等状态类型，不为跟进强建计划；实验也只登记状态和产物链接，实验材料仍沿用户指定位置保存。
+
+`experience/` 保存待复盘线索，不是 SDLC 状态或原始日志；收集由 `experience-capture` 负责，复盘由 `$agi-mode 复盘` / `$agi-mode reflect` 读取。只安装 agi-mode 也可读取已有记录，无需先安装收集 skill；用户指定或项目登记的已有经验目录优先，不双写。
+
+## 每层目录索引
+
+`.xgent-ai/` 下每个实际创建的目录都维护 `index.md`，包括根目录、中间层、对象事件目录、任务目录及后续归档/分片目录；不要求原文档所在目录采用本约定。新目录与其索引同批创建，旧状态目录缺索引时在获准维护范围内补齐，查询模式只报告缺失。
+
+普通目录使用 [通用目录索引模板](../assets/directory-index.md)，SDLC 入口使用 [工作导航模板](../assets/sdlc/index.md)，对象分类使用 [类型索引模板](../assets/sdlc/type-index.md)。每层索引列出直接文件及子目录入口，子目录链接其 `index.md`；索引自身不自列，不在上层重复展开全树。目录用途、覆盖范围和维护规则入口随索引保存，非开发任务索引也保留维护约定，不依赖 SDLC 已初始化。
+
+创建或改变目录内容的执行者负责同步索引；内容未改变去向时不逐级重写。新增、移动、归档、删除及多机合并的完整规则见 [协议：目录索引维护](../assets/sdlc/protocol.md#目录索引维护)。索引是可重建导航，不是进度事实、锁或不可变事件；事件枚举必须排除索引文件。
+
+## 身份与来源
+
+- 状态对象与事件使用独立 UUID；原文件不要求 UUID 命名、不嵌入台账编号，不因登记改名。每次实际评审有独立对象 ID，通过所审对象、范围、版本和报告链接区分轮次。
+- `artifact`、`sources.path` 保存原产物的仓根相对路径或可访问的稳定 URL；Markdown 链接按状态文件所在目录计算。例如状态页可引用仓内 `docs/requirements/`、`goal/`、`design/` 或任意用户目录，不能假定原文在 `.xgent-ai/sdlc/` 下。
+- 原文移动时先核实对应关系，沿用对象 ID、登记新旧路径并更新索引链接；状态整理本身不授权移动原文。跨机器按各自仓根解析路径，来源缺失标明未同步或不可核验。
+- 状态只存简要事实、关系、版本/指纹、证据位置、阻塞及下一步。完整问题说明、验收步骤和运行日志留在原处，不在状态目录另存副本作为新事实源。
+- 状态码按随仓保存的 [状态模型](../assets/sdlc/state-model.md) 固定，原文自述与证据质量单列。原计划状态行并非绝对真相；可用适用的实现、验证及处置证据纠正台账，保留差异与历史，不擅自修改原文。
+
+## 增长与按需读取
+
+- 每个对象独立状态页，计划页面链接各轮评审页面；不把所有 PRD、计划与历史塞进一个 `STATUS.md`。实施状态归对应计划，详细实现与验收记录继续按原计划链接读取。
+- `sdlc/index.md` 列直接文件和状态/事件子目录入口，可快捷链接分类索引与当前重点。类型索引一对象一行，列 ID、标题、来源、状态页和活动/归档标记，不复制进度正文；归档标记须有来源，不按文件年龄推断。
+- 类型索引过大时按领域或年份分片，父索引列全分片及范围。归档另列索引，保留原对象及事件；不要求搬动原文或历史记录，不截断列表冒充完整盘点。
+- 查询先读分类索引，再读活动/指定对象及依赖；枚举对象和事件文件可发现遗漏，不默认全文加载全部历史。原产物从用户提供的位置、项目约定、已登记链接及仓内文档发现，不将状态目录当作唯一搜索范围。
+- `.xgent-ai` 是隐藏目录，状态发现显式使用 `rg --files --hidden .xgent-ai/sdlc`（目录存在时）或等价枚举；原文在其他隐藏目录时同样显式定位。必要来源被忽略时说明限制，不擅自改变项目忽略规则。
+
+## 已有台账与共享
+
+状态台账位置按「用户指定 → 仓库明确登记 → 默认 `.xgent-ai/sdlc/`」确定。已有 `docs/project-status/protocol.md` 或等价台账沿原协议维护；新旧入口并存又无明确切换记录时先核对，不建立竞争台账或双写。
+
+用户要求迁移台账时，只迁移状态资料：保留对象/事件 ID、历史结论、来源版本，转换相对链接并记录路径映射，核验后登记新入口。原文档不在迁移范围内；旧入口留指引，不同时维护两套状态。不可变事件的历史路径可通过映射解析，不改写历史 hash。
+
+开发任务仍以原计划及实施记录为恢复入口，状态页只是跨对象索引；没有现有恢复记录时才按需补充任务状态。使用 [项目状态流程](../playbooks/what-next.md) 与 [可复制协议](../assets/sdlc/protocol.md) 回写。协议、状态页与事件可随 Git 共享，来源文件仍各按项目方式同步；状态已同步不代表源码、原文和证据已同步。

package/skills/apply-code-review/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: apply-code-review
-description: 根据开发计划与代码评审报告（如 xxx.code-review.md）逐条核实问题，实施合理且在范围内的修复，验证结果并更新对应里程碑的实现与验收记录及计划进度。用户要求 apply-code-review、落实代码评审、按评审修复并回写实现记录时使用；不用于只做代码评审、只修订计划或无评审输入的整份计划实施。
+argument-hint: "<开发计划> <代码评审报告> [上轮报告/处置记录] [修复/仅复核] [问题ID/里程碑]"
+description: 用于根据开发计划和代码评审报告落实修复或复核修复效果；不用于初次评审、仅改计划或无评审输入的计划实施。逐条核实，按模式修复或仅复核，回写处置与证据。
 ---
 
 # apply-code-review · 核实并落实代码评审
@@ -21,6 +22,13 @@ description: 根据开发计划与代码评审报告（如 xxx.code-review.md）
 
 ## 2. 逐条核实并裁定
 
+### 再次 apply 与仅复核
+
+- 默认或明确“再次 apply / 继续修复”时，先读已有处置，再处理仍成立且在范围内的未解决项、已修改待验证项和回归。明确“仅复核 / 只核实 / 检查修复效果”时，不修改目标代码、测试、配置或计划正文；可运行必要且允许的验证，并按记录合同保存复核结果。仅聊天/不保存优先，不自动调用 review-code。
+- 输入是复审报告时，读取其上轮报告引用、逐项复审表和已有实现记录，按“报告原始版本 + 问题 ID”映射。已解决项只核对证据适用性；仍存在、部分解决、回归及本轮新增问题才进入可能修复清单，未复核/待核实不当成关闭或自动授权扩大范围。同号 F-ID 必须带来源，确认同一问题后沿用主记录并补来源映射，不重复施加补丁。
+- 旧问题不因不在当前 diff 中而跳过。逐项记录上次处置、本次证据与复核结果；已解决的有效证据可复用并说明理由，缺证只标待核实。新证据推翻先前关闭时保留历史并重新打开，当前事实优先于旧的 applied 标记。
+- 没有事实、处置、证据适用性或范围变化时，只回复已核对，不改文件/时间、不重记 SDLC 事件；已修改但缺验证的项仅补所缺验证。apply 的复核属于原评审处置，不生成独立复审通过记录，也不自动开始下一轮 review。
+
 - 阅读报告引用的真实代码、当前调用链、计划契约、适用规则及已有测试。需要对比时读取报告所审版本；修复是否必要以当前目标行为为准。检查调用是否可达、输入是否允许、上游是否已有保护、行为是否有意改变。
 - 能做行为复现的缺陷先补充或运行能暴露问题的测试/最小实验；静态已足够证明的类型、接线或契约问题不为形式强造复现。无法复现不等于误报：分清未触发、环境缺失与证据反驳。
 - 独立判断建议修法是否满足计划、保留兼容性并解决根因。缺陷成立但建议会造成回归时，采用更小且正确的修法，在记录里说明依据，不机械执行报告的替换代码。
@@ -50,4 +58,12 @@ description: 根据开发计划与代码评审报告（如 xxx.code-review.md）
 ```text
 使用 $apply-code-review，根据 goal/LOGIN.md 核实 goal/LOGIN.code-review.md，修复合理问题并更新对应实现记录。
 使用 $apply-code-review，计划 docs/plan/cache.md，评审 docs/reviews/cache.code-review.md，仅处理 F-01 和 F-03。
+使用 $apply-code-review goal/LOGIN.md goal/LOGIN.code-review.md，仅复核已有修复效果，参考 goal/LOGIN.records/M2.md。
+使用 $apply-code-review goal/LOGIN.md goal/LOGIN.code-review.r2.md，继续修复仍存在的问题，沿用报告中的前轮关联。
 ```
+
+## 项目状态回写
+
+若仓库已登记状态台账，或存在仓根 `.xgent-ai/sdlc/protocol.md`（兼容已有 `docs/project-status/protocol.md`；两套并存且未登记切换时先核对，不能双写），交付原产物后读取台账的回写规则（默认目录读上述协议），按其格式新增本次事实记录并刷新受影响的状态页与必要索引；未启用时不自动建表，不依赖另装技能。只读/仅聊天/不保存要求优先，登记失败须说明，不影响如实交付已完成的原产物。
+
+接续原评审对象的处置维度，记录问题 ID、修复版本、验证和未完项，链接对应实现记录；仅同步实际改变的实施进度。已修改待验证与已验证分开，不把修复登记为独立复审通过。

package/skills/apply-code-review/references/record-contract.md

@@ -8,6 +8,19 @@
 4. 一个问题跨多个里程碑时，选直接承载修复的里程碑为主记录；其他实际受影响记录只同步相关验证/状态并链接主记录，避免复制整份处置表。集成终验归其原定收口里程碑，不新造“评审整改”里程碑改变总数。
 5. 记录已有内容须保留仍有效的交付事实、证据与未完项，只更新受影响部分。保留源 `xxx.code-review.md` 的问题与原结论；用户明确要求更新它时，追加可区分版本的处置摘要及记录链接，不把历史评审结论改成“当时就正确”。
 
+## 重复执行与修复效果复核
+
+读取输入报告引用的上轮报告及既有处置，以“来源报告/原始版本 + 问题 ID”建立对应关系；报告追加处置不改变原问题身份。复审报告中的旧问题通过明确映射接续，新问题保留新来源。报告链接相对记录所在目录，所审、修后与本轮核查版本分别保留。
+
+复核结果统一为 **已解决、仍存在、部分解决、回归、待核实、不再适用、本轮未复核**，与下文的处置状态分开：复核结果回答当前效果，处置状态记录做过什么及还缺什么。回归需先前关闭和当前失败证据；不再适用须有契约/范围依据，不表示已修复；证据不足不写已解决。
+
+沿用已有处置表，在同一条目保留上次处置/版本、本轮结果与当前证据；可加列，不另建重复整改台账。至少能读到：
+
+| 来源报告 / 问题 ID | 上次处置 / 版本 | 本轮复核结果 | 当前处置 / 修改 | 证据与适用范围 | 剩余动作 |
+| --- | --- | --- | --- | --- | --- |
+
+“仅复核/只核实”保留目标产物，只保存必要的复核记录；不会新增修复数或推进计划完成数。若用户要求完全只读/仅聊天，则不保存任何记录。原有关闭被推翻时保留历史及重新打开的依据；用户限定范围外标本轮未复核。无实质变化时不改内容或时间，不重复写台账事件；仅补缺证时接续原条目。
+
 ## 逐条处置
 
 以 **报告路径 + 报告版本/hash + 问题 ID/章节** 标识来源，避免不同报告都含 F-01 时串项。复跑同一报告、同一问题时更新已有条目并重新核对当前代码，不重复建表/记录，不重复施加补丁；新版本改变主张时注明新来源。状态可沿用仓库等价用语，但至少分清：
@@ -21,7 +34,7 @@
 | 待核实/待决策 | 缺事实、验收条件或关键选择；给影响、需要的证据/决定及可继续范围 |
 | 待修复/阻塞 | 已确认合理且需修，但尚未实施或依赖未满足；给阻塞、已完成部分和继续动作，不用“不采纳”掩盖未做 |
 
-用户排除的条目标“未处理（用户限定范围）”，说明来源范围即可，不展开额外调查。仅核实或全部不采纳时也记录相关结论，但不得据此增加完成数量或声称有代码修复。
+用户排除的条目标“未处理（用户限定范围）”，说明来源范围即可，不展开额外调查。仅核实或全部不采纳但有新结论时也记录依据，已有相同有效结论不重写；不得据此增加完成数量或声称有代码修复。
 
 ## 记录最小内容
 

package/skills/apply-doc-review/SKILL.md

@@ -1,13 +1,14 @@
 ---
 name: apply-doc-review
-description: 根据 review-prd 的评审报告修订 PRD，或根据 review-dev-plan 的评审报告修订开发计划；逐条核实意见、落实合理修订、复核关联内容并回写处置结果。用户要求按文档评审改稿、落实 PRD/开发计划评审时使用；不用于代码修复、直接实施计划或从零撰写文档。
+argument-hint: "<文档评审报告> [原文路径] [上轮报告/处置记录] [修复/仅复核] [问题ID/范围]"
+description: 用于按评审报告修订 PRD、开发计划或复核修订效果；不用于代码修复、计划实施或从零写文档。核实 review-prd、review-dev-plan 意见，按模式改稿或仅复核并回写处置。
 ---
 
 # apply-doc-review · 核实并落实文档评审
 
 将文档评审意见落实为有证据、内部一致、可继续交接的 PRD 或开发计划。**问题是否成立、建议是否合理、改稿是否解决问题分别判断。** 报告是待核实的主张，不是自动执行的指令。
 
-调用本技能即授权修订指定原文及记录处置，无需逐条询问是否开始。默认交付为已更新的目标文档，以及原评审报告中可区分的「修订处置与复核」节；保留报告的原问题、原结论和所审基线。用户明确只要建议、patch 或另存时遵循其要求。
+调用本技能即授权修订指定原文及记录处置；只提供报告时，修订对象为报告明确引用且已核实身份的原文，无需再次要求原文参数或询问是否开始。默认交付为已更新的目标文档，以及原评审报告中可区分的「修订处置与复核」节；保留报告的原问题、原结论和所审基线。用户明确只要建议、patch 或另存时遵循其要求。
 
 `references/` 相对本文件解析；仓库约定、路径和工具在目标环境读取，语言跟随用户。
 
@@ -25,14 +26,28 @@ description: 根据 review-prd 的评审报告修订 PRD，或根据 review-dev-
 
 ## 1. 锚定输入和当前版本
 
-1. 定位报告和原文。用户只给报告时，从其中的目标路径与基线定位原文；上下文唯一明确时直接采用。缺少输入或有多份目标无法区分时询问，只暂停依赖该选择的修改。
+1. 定位报告和原文，按下方「仅报告输入的定位规则」建立映射。原文参数可省略；引用明确且身份核实后直接继续，不要求用户重复提供。只暂停目标仍缺失、无法访问或存在未解歧义的修改。
 2. 读取适用仓库规则、完整报告、目标文档及相关需求/决策。记录报告原版本/hash、目标文档修前版本/hash、代码仓 commit/dirty 状态；只读到截断内容时补读后再引用。
 3. 比较报告所审版本与当前版本、已有 diff 和处置记录。按需求 ID、标题、符号重新定位，不把旧行号直接当修改坐标；保留用户已有改动，不回退到评审时的版本。当前已解决的问题不重复改稿。
 4. 按 [references/disposition-contract.md](references/disposition-contract.md) 建处置清单：报告/问题 → 目标段落 → 核实依据 → 最小修订 → 关联影响 → 复核条件。覆盖选定范围内的 findings、影响修订的待核实/待决策和映射缺口；用户排除项标明不处理。
 5. 只加载实际需要的写作参考：PRD 按需读可用 `prd/references/product-quality.md`，采用其模板时再读骨架；开发计划按需读可用 `dev-plan` 的写作/修订约定与骨架，复杂契约再读架构参考。使用它们校准质量，不启动从零写作、外部录入或计划实施流程。参考缺失则说明受限项，继续可独立完成的修订，不强制迁移历史文档或自定义模板。
 
+### 仅报告输入的定位规则
+
+- 用户显式指定原文时使用该目标并核对报告身份；省略时读取报告头「评审对象」中的类型、原文档链接、所审版本与范围。本地相对链接以**报告所在目录**解析，不以当前工作目录或仓根解析；远程 URL 沿可用访问方式读取，不自动发布外部修改。
+- 报告明确列出多个评审目标时按行分别映射，只处理用户指定范围；未限定时处理明确列出的目标。背景引用、关联 PRD/计划和代码链接不自动成为修订对象。某个目标不明时继续其他已明确对象。
+- 兼容旧报告：从覆盖/基线节的明确目标路径与已有上下文核实。引用失效时可按稳定文档 ID、仓内链接和移动历史寻找唯一对应原文；仅同名或去掉 `.review` 后缀不足以确认。找不到持久原文、存在多个候选或显式参数与报告指向不同对象时，先核对是否为移动/改名；仍无法消歧才询问，不默默选一份修改。
+- 当前内容 hash 与所审版本不同不等于目标错误；身份确认后按本节的版本比较核实哪些意见仍适用。保留报告原始引用与所审基线，原文迁移后的当前路径和修后版本写在处置节，不回退原文以匹配旧 hash。
+
 ## 2. 核实意见并解决必要决策
 
+### 再次 apply 与仅复核
+
+- 默认或明确“再次 apply / 继续修订”时，先读已有处置，再处理仍成立且在范围内的未解决项、已修订待核实项和回归。明确“仅复核 / 只核实 / 检查修复效果”时，不修改目标 PRD/开发计划正文；只核对当前内容和必要关联检查，按处置合同保存结果。仅聊天/不保存优先，不自动调用 review-prd 或 review-dev-plan。
+- 输入是复审报告时，沿其上轮报告引用、逐项复审表和处置节/applied 文档建立来源映射。已解决项只核对证据适用性；仍存在、部分解决、回归及本轮新增问题才进入可能修订清单。不同报告的同号 F-ID 不混用；确认同一问题后引用已有处置，不能因新报告路径或 appended 处置导致 hash 变化就重复改稿。
+- 逐项记录上次处置、本次证据和复核结果。用户限定范围外的条目明确未复核；缺证不算关闭，不为关闭意见改变产品承诺。当前证据推翻原关闭结论时保留历史并重新打开，而非沿用 applied 标记。
+- 原文、处置、证据适用性与范围均无实质变化时，只回复已核对，不重写原文/报告或刷新时间，也不重复记 SDLC 事件。仅补验证时更新已有对应处置；apply 复核仍属于处置，不冒称新一轮独立评审通过。
+
 - 亲自读取问题对应的原文、引用材料及相关代码行为。区分当前事实、未来目标、设计选择、假设与验收要求；不能因为新功能未实现就删掉 PRD 或把计划中的未来设计改成缺陷。
 - 对「遗漏」先查全文、附录和已有引用；对矛盾核对两处原文及适用版本。事实能查则先查，不让用户代替证据判断。代码/环境无法访问时明确限制，不能沿用报告的「已核实」声明冒充本次核实。
 - 问题成立但建议会改变已确认目标、引入回归或扩大范围时，采用满足原目标的最小合理修订；报告里记录偏离建议的理由，不能以拒绝建议修法代替解决问题。
@@ -67,13 +82,22 @@ description: 根据 review-prd 的评审报告修订 PRD，或根据 review-dev-
 2. PRD 检查需求可断言、关键场景预期状态、分期和终验一致；计划检查事实、路径、契约、依赖、验证与进度一致。目标采用 `dev-plan` 协议且工具可用时，用其实际路径运行 `check_paths.sh <计划> <仓库根>` 和 `check_progress.sh <计划> <仓库根>`；先检查脚本适用性，人工区分计划新增路径与错误复用。工具缺失/模板不适用则人工核对并说明。
 3. 只运行证明文档修订所需的检查，不为改稿启动整套实施或业务验收。未来验证写为计划要求；已有证据、静态推演和本次实测分开。缺关键复核则标「已修订待核实」，不能标关闭。
 4. 按处置合同在报告追加或更新独立处置节，保留原结论，写明修后基线、逐项状态、验证结果、当前就绪判断及未完项；这是本次修订复核，不冒称重跑了完整独立评审。
-5. 回读已写入原文和报告，核对链接、状态、统计及最终 diff，确认没有无关变更和覆盖用户修改。零改动也要如实记录逐条依据；写入失败分别说明哪份文件未完成。
+5. 回读已写入原文和报告，核对链接、状态、统计及最终 diff，确认没有无关变更和覆盖用户修改。原文零改动但有新核实结论时仍记录逐条依据；已有相同且有效的处置则不重写。写入失败分别说明哪份文件未完成。
 
 最终回复给修订文档与处置报告链接、主要改动、未采纳/待决项和实际检查结果。PRD 使用「可交接 / 仍需修订 / 待补证或决策」描述本次核查范围；开发计划使用适用的就绪状态。部分问题关闭不等于整份文档通过评审，更不等于实现或上线完成。
 
 调用示例：
 
 ```text
-使用 $apply-doc-review，根据 docs/PRD-login.review.md 修订 docs/PRD-login.md，并记录各条意见的处置。
-使用 $apply-doc-review，根据 goal/LOGIN.review.md 修订 goal/LOGIN.md，仅处理 F-01 和 F-03。
+使用 $apply-doc-review docs/PRD-login.review.md
+使用 $apply-doc-review goal/LOGIN.review.md，仅处理 F-01 和 F-03。
+使用 $apply-doc-review，根据 docs/reviews/login.review.md 修订 docs/PRD-login.md。
+使用 $apply-doc-review docs/PRD-login.review.md，仅复核已有修订效果，不改原文。
+使用 $apply-doc-review goal/LOGIN.review.r2.md，继续处理复审确认仍存在的问题。
 ```
+
+## 项目状态回写
+
+若仓库已登记状态台账，或存在仓根 `.xgent-ai/sdlc/protocol.md`（兼容已有 `docs/project-status/protocol.md`；两套并存且未登记切换时先核对，不能双写），交付原产物后读取台账的回写规则（默认目录读上述协议），按其格式新增本次事实记录并刷新受影响的状态页与必要索引；未启用时不自动建表，不依赖另装技能。只读/仅聊天/不保存要求优先，登记失败须说明，不影响如实交付已完成的原产物。
+
+接续原评审对象的处置维度，按评审 ID 与问题 ID 记录修订/复核及修后版本；同步确实改变的文档事实。不伪造新一轮独立评审，也不把部分关闭记成全部通过。

package/skills/apply-doc-review/references/disposition-contract.md

@@ -2,12 +2,25 @@
 
 ## 写入位置与历史
 
-- 默认就地修订用户指定原文，在源评审报告追加或更新「修订处置与复核」节。调用本技能已经授权这些写入，不再询问是否保存；明确只核实、仅聊天或另存时以用户要求为准。
-- 原报告的问题、证据、评审基线和原结论保持不变；当前处置与修后判断独立成节，标明日期和修后版本。原文只保留修订后的产品/设计结论及必要决策理由，不混入 F-ID、采纳经过和评审流水。
+- 默认就地修订用户指定或由报告明确引用并核实的原文，在源评审报告追加或更新「修订处置与复核」节。仅提供报告也可执行，不要求重复传原文。调用本技能已经授权这些写入，不再询问是否保存；明确只核实、仅聊天或另存时以用户要求为准。
+- 原报告的问题、证据、原文档引用、评审基线和原结论保持不变；当前处置与修后判断独立成节，标明日期、当前目标链接和修后版本。原文已移动时记录旧引用到当前路径的对应依据；本地目标链接相对处置文档所在目录，另存 applied 文档时重新计算并核验。原文只保留修订后的产品/设计结论及必要决策理由，不混入 F-ID、采纳经过和评审流水。
 - 源报告只读或用户要求保留文件不变时，另存同目录 `<报告文件名去扩展名>.applied.md`，在处置文档中链接源报告和修订目标；远程来源没有本地目录时遵循仓库惯例，无惯例则用 `docs/reviews/<主题>.applied.md`。重名且未获更新授权时加日期及序号，不覆盖无关文件。
 - 多份报告对应同一原文时合并修订，但每份报告均能追踪其问题处置；同一 F-ID 不能跨报告混用。多份原文的版本与结论分别记录。
 - 重复运行先读已有处置，以报告原始版本/问题 ID 匹配更新，不重复应用修改。新报告改变主张时标明新来源；本技能追加的处置内容改变报告 hash 不应把旧 finding 变成新问题。
 
+## 重复执行与修复效果复核
+
+读取输入报告引用的上轮报告及既有处置，以“来源报告/原始版本 + 问题 ID”建立对应关系；报告追加处置不改变原问题身份。复审报告中的旧问题通过明确映射接续，新问题保留新来源。报告链接相对记录所在目录，所审、修后与本轮核查版本分别保留。
+
+复核结果统一为 **已解决、仍存在、部分解决、回归、待核实、不再适用、本轮未复核**，与下文的处置状态分开：复核结果回答当前效果，处置状态记录做过什么及还缺什么。回归需先前关闭和当前失败证据；不再适用须有契约/范围依据，不表示已修复；证据不足不写已解决。
+
+沿用已有处置表，在同一条目保留上次处置/版本、本轮结果与当前证据；可加列，不另建重复整改台账。至少能读到：
+
+| 来源报告 / 问题 ID | 上次处置 / 版本 | 本轮复核结果 | 当前处置 / 修改 | 证据与适用范围 | 剩余动作 |
+| --- | --- | --- | --- | --- | --- |
+
+“仅复核/只核实”保留目标产物，只保存必要的复核记录；不会新增修复数或推进计划完成数。若用户要求完全只读/仅聊天，则不保存任何记录。原有关闭被推翻时保留历史及重新打开的依据；用户限定范围外标本轮未复核。无实质变化时不改内容或时间，不重复写台账事件；仅补缺证时接续原条目。
+
 ## 逐条状态
 
 | 状态 | 使用条件 |

package/skills/archify/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: archify
-description: Create polished, validated architecture, workflow, sequence, data-flow, and lifecycle/state diagrams as explorable standalone HTML with inline SVG, dark/light themes, optional trace motion, and PNG/JPEG/WebP/SVG/WebM export. Accept plain-language requirements or pasted Mermaid flowchart, sequenceDiagram, and stateDiagram input; inspect repository evidence when the diagram must reflect real code. Use when the user asks to visualize system architecture, infrastructure, cloud/security/network topology, technical workflows, API call sequences, request lifecycles, data pipelines, ETL/ELT, data lineage, state machines, or to convert/beautify Mermaid.
+description: Use when diagramming architecture, workflow, sequence, data-flow, lifecycle, or converting Mermaid. Create validated, interactive diagrams as standalone HTML with image and video export.
 license: MIT
 metadata:
   version: "2.17"

package/skills/architect/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: architect
-description: "Sketch types, signatures, and module structure before code, then stay in the loop while implementation fills in. Use for /architect, 'architect this', 'design this', or non-trivial work where jumping to code would lock in the wrong shape."
+description: "Use for /architect or complex design work needing structure before code. Sketch types, signatures and module boundaries, then guide implementation."
 disable-model-invocation: true
 ---
 

package/skills/arena/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: arena
-description: "Compatibility entry for agi-mode Arena: generate independent candidates, compare them, select a base and verify a synthesis. Use for /arena, 'arena this', or an explicit request for competing designs."
+description: "Use for /arena or explicit requests for competing designs. Routes to agi-mode Arena to compare independent candidates and verify the synthesis."
 disable-model-invocation: true
 ---
 

package/skills/automate-me/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: automate-me
-description: "Use for \"automate me\", \"create/update/refresh my -mode skill\", \"turn/capture my preferences or working style into a skill\", or wanting agents to follow how the user works. Drafts or revises a personal -mode skill via create-skill + unslop, optionally pulling fresh evidence from recent transcripts."
+description: "Use for creating or updating a personal -mode skill from user preferences and working habits, including requests to automate me."
 disable-model-invocation: true
 ---
 

package/skills/autoresearch/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: autoresearch
-description: 'Compatibility entry for agi-mode hillclimbing: autonomous, measured improvement of code, skills, prompts or agent workflows. Use for autoresearch, continuous optimization and iterative experiments; not one-shot edits or review-only tasks.'
+description: 'Use for measured, iterative optimization; skip one-shot edits and review-only tasks. Routes to agi-mode Hillclimb for experiments on code, skills, prompts or agent workflows.'
 license: MIT
 compatibility: Requires agi-mode to be installed alongside this entry and a runnable measurement path.
 ---

package/skills/crd/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: crd
+description: 用于起草跨项目协作 CRD、在收到的 CRD 中答复或整合对方返回版本；不用于代码评审、Kubernetes CRD 或直接实施。维护需求、Q&A 与文末往返记录。
+---
+
+# crd · 跨项目协作需求文档
+
+将一方向另一方提出的协作需求写成可独立阅读、逐项答复和持续跟进的 CR（Change Request），文档称为 CRD。这里的 QA 指 **Q&A 问答澄清**。双方都可能提出问题或补充需求，不把当前工作仓库自动当作需求提出方。
+
+**默认以整份 CRD 往返协作**：提出方形成 CRD → 发给接收方 → 接收方在收到的文档末尾追加答复 → 返回包含答复的完整 CRD → 提出方核对、整合并继续下一轮。CRD 本身承载需求、Q&A 和回复历史；聊天或邮件中的独立答复作为补充输入。
+
+CR 讲清「谁需要另一方提供什么、为什么、怎样算满足、哪些问题尚未达成一致」。只展开协作边界所需的契约，不替对方编写内部实施方案，也不把写文档当作发送请求、接受需求或启动开发的授权。
+
+## 1. 定位本次动作与事实来源
+
+- **发起或修订需求**：读取需求简报、相关代码/接口文档及已有 CR，形成可答复的需求条目。
+- **在收到的 CRD 中答复**：以收到的完整文档为底稿，核对本方能力与约束，在文末逐项追加接受、部分接受、替代方案、不接受或待澄清的意见，交付包含回复的完整 CRD。没有授权或实际表态时标为「答复草案」。
+- **整合对方返回的 CRD**：读取返回文档、上次发出版本和本地当前版本，识别本轮新增答复与其他改动，按第 4 节整合并同步当前摘要，不要求用户另行摘抄已有回复。
+- **补充独立答复或续接 Q&A**：先读完整 CR，尤其是末尾最新往返记录，再对照来信、聊天、评审意见等材料追加并同步当前摘要。
+
+从已有上下文确定提出方、接收方、各自项目、协作目标、文档路径和当前代表哪一方。多方参与时，每条需求注明责任项目，不假设共享同一个仓库、版本或发布节奏。
+
+只询问会改变需求对象、范围或答复归属的缺失信息，其余写「待确认」并继续完成可确定部分。拿不到对方仓库时，区分本方观察、对方陈述、推测和待核实事项；不把本方找不到的能力写成对方不存在。
+
+每项事实保留可定位来源，如文件路径与段落、接口文档链接、消息日期与发言方。未知人员、日期、排期不补造；整理日期与原消息日期分别记录。拟稿不得冒称对方已回复。
+
+## 2. 写出对方能逐项处理的需求
+
+新建时读取 [CR 模板](assets/cr-template.md)，按实际规模删去不适用内容；更新既有 CR 时沿用其结构与编号，不强制重排。路径优先使用用户指定或仓库已有约定；没有约定时用 `docs/cr/CR-<主题短名>.md`。先查同主题文档，避免续谈时另建一份。
+
+需求使用文档内稳定编号 `R-01`，问题使用 `Q-01`，往返记录使用 `RESP-01`；继承已有编号，新条目递增，撤销的编号不复用。它们是本地追踪号，不冒充外部系统 ID。
+
+每条需求应包含：
+
+- **场景与动机**：谁在什么条件下需要什么；当前阻碍和不解决的影响。
+- **请求与边界**：希望接收方提供的可观察行为或交付物，以及提出方配合事项、非目标和前置依赖。
+- **协作契约**：仅写相关部分，如输入/输出、字段语义、权限、错误与重试、兼容版本、交接方式。已有契约标来源；尚未确定的设计明确标「提议」。
+- **验收条件**：给定前提和动作后应观察到的结果、必要的失败行为，由谁在什么环境或交付节点验证。可用具体示例，不用「正常工作」「支持对接」代替判据。
+- **优先级与时间**：说明影响与理由；区分提出方期望时间、接收方估计和明确承诺，不因写 CR 而编造截止日。
+
+一条需求应能被独立答复和验收。小型协作请求不扩写为完整 PRD；不要求对方必须采用尚未达成一致的内部技术方案。
+
+## 3. 维护 Q&A 与当前结论
+
+Q&A 是双方待澄清事项的当前视图。每条记录问题、关联需求、提问方、待答方、是否阻塞及阻塞哪一步、当前回答/待确认点、状态和答复记录链接。
+
+- 未知答案保持空缺含义明确；建议答案标为建议，不生成虚构问答。
+- 回答部分问题时，仅更新对应条目；未答项继续待答。问题已回答不等于需求已接受，需求已接受不等于已交付。
+- 单方提出的新范围、替代方案或时间安排，仍属待确认提议；达成一致的结论必须能指向有权限一方的明确确认，需双方确认的协作约定保留双方依据。
+- 新答复与旧答复冲突时，在当前视图指出冲突及影响；只有明确撤回或替代旧意见时才采用新结论，否则保持待澄清，不能仅凭时间较新覆盖旧承诺。
+- 需求、问题和答复互相引用。关闭问题需有实际回答及必要确认；关闭 CR 需有约定范围的验收证据，或明确的拒绝/撤回理由，不能用「已回复」代替闭环。
+
+正文是当前工作视图：已确认内容写入需求与验收条件；未确认变更放在提议或待决项中。历史往返记录保留当时原意。正文与历史不同不等于错误，但须能追到变更依据。
+
+## 4. 整份 CRD 往返与文末答复
+
+### 交付给对方的版本
+
+保持同一 CR 标识，注明当前文档版本及本轮基于的版本；沿用已有版本约定，无约定时可用 `v1`、`v2` 等区分交接版本。交付完整需求、Q&A 和全部往返记录，关键内容不只链接到对方无法访问的本地文件。接收方保留原需求与历史，在文末追加自己的答复；范围或验收的修改先写为建议。
+
+本地保留可定位的发出基线（已有文件或版本控制记录即可），便于下轮核对，不为每次文字编辑制造新副本。尚未实际发出时称「待发送版本」；用户提供了发送事实后才记录为已发出。
+
+### 整合返回文档
+
+- 先核对 CR 标识与版本关系，再比较返回版本相对发出基线的变化，以及本地当前版本相对该基线的变化。文件名变化不代表新 CR，返回文件的时间较新也不代表可以覆盖本地。
+- 对方已在文末写好的答复直接保留或并入一次，不把整份返回文档作为一条新回复再次粘贴。来源可定位到返回文件、版本及答复章节；保留原发言方和时间。
+- 对方直接改了需求、验收、Q&A 结论或历史答复时，显式列出差异及影响；尚未确认的实质变更作为提议或冲突，不能静默成为双方已同意的新基线。保留既有历史，历史更正以追加记录承接。
+- 本地也有新增内容时，合并互不冲突的增量；有冲突则保留双方意见并列入待确认项，不丢弃本地补充。并行副本发生编号碰撞时保留来源版本限定（如 `v2-甲方/RESP-02`），明确映射，不让一个编号指向两份不同内容。
+- 缺少发出基线时仍可整理可识别的答复，但说明无法完整核实正文改动；缺少本地版本时可将返回 CRD 作为当前工作稿，保留来源和未核实范围，不声称完成了版本合并。
+
+### 追加规则
+
+所有轮次放在文档最后的「往返答复记录」中，按收录顺序追加；需求、Q&A、来源和其他章节位于它之前。接收方答复、提出方补充和双方后续确认均使用同一记录格式。
+
+每次追加包含记录编号、发言方/项目、原消息时间（未知则注明）、整理时间、来源、关联 R/Q 编号、答复内容、未答项及下一步。拟答复显式标「草案，未发送/未确认」；收到的答复标「已收到」，但不据此推定内容已获双方认可。
+
+- 原文引用必须与已读取材料一致；概括写成「整理摘要」，保留条件、否定、例外及承诺边界。大段原文可链接原件，并在记录内保留关键答复。
+- 只追加新记录，不改写或删除已收录的历史答复。更正通过新记录引用被更正的编号，注明差异与依据；可以同步正文当前视图。
+- 追加前检查来源标识和内容，重复导入同一答复不重复记账。相似但有新增条件的消息是新记录，注明变化。
+- 一轮逐项对应 R/Q；无法可靠归属的答复保留原意并标「关联待确认」，不强行绑定。新的反问建立 Q 编号，链接该轮记录。
+- 用户只要求「原样追加」时只追加与必要标识，不擅自重写需求或采纳方案；用户要求整理、同步或续接时，才按证据更新正文当前视图。
+
+不通过邮件、聊天工具或项目系统发送 CR，除非用户另有明确授权；只负责落盘时无需增加发送审批步骤。生成文件不表示已送达接收方。
+
+## 5. 回读与交付
+
+检查新增/修改内容及关联位置：
+
+- 双方角色、需求边界、配合事项和验收判据可理解，未知信息未伪装成事实。
+- R/Q/RESP 编号唯一且引用可达；未答、部分接受、冲突和时间条件未丢失。
+- 当前结论均有来源；草案、提议、已收到、已确认和验收完成没有混用。
+- 历史答复未被覆盖，新记录位于文末；重复输入未造成重复追加。
+- 返回版本的增量已核对，本地补充未丢失；交接版本保留完整上下文，正文改动与未确认分歧有明确归属。
+- 相对链接正确，修改仅涉及本次 CR；不把文档检查报告成业务验收通过。
+
+交付文档链接、这轮新增或变化的结论、仍待谁回答的阻塞问题。没有实际发送就说明「文档已保存，未发送」。
+
+## 调用示例
+
+```text
+使用 $crd，为订单项目向账号项目提出批量查询用户展示名的协作需求。
+使用 $crd，站在账号项目一方读取收到的 CRD，核对本仓库能力后在文末拟答复，交付可返还的完整 CRD。
+使用 $crd，这是对方返回的 CRD，请与上次发出版本及本地当前稿核对，整合新增回复并更新 Q&A。
+使用 $crd，把下面收到的回复追加到 docs/cr/CR-user-display-name.md，并同步需求与 Q&A 当前状态。
+使用 $crd，将这段补充原样追加到现有 CR 末尾，保留正文。
+```

package/skills/crd/assets/cr-template.md

@@ -0,0 +1,66 @@
+# CR：<协作主题>
+
+| 项目 | 内容 |
+| --- | --- |
+| CR 标识 | <沿用已有标识；无则使用文档文件名> |
+| 文档版本 / 基于版本 | <当前交接版本 / 本轮收到或上次发出的版本；首版写无，未知则注明> |
+| 提出方 / 接收方 | <项目、团队及已知联系人> |
+| 当前状态 | <草案 / 待答复 / 澄清中 / 已达成一致 / 交付中 / 已关闭，按证据填写> |
+| 创建 / 更新日期 | <日期> |
+| 相关材料 | <PRD、Issue、接口文档或代码依据> |
+| 当前结论与下一步 | <已确认什么；待谁处理什么；依据或答复链接> |
+
+协作方式：请在本文末尾追加逐项答复，保留原需求与既有往返记录，并返回完整 CRD。涉及范围或验收条件的调整请在答复中明确提出，供双方确认。
+
+## 1. 背景与目标
+
+<当前协作场景、已核实的现状、阻碍及期望结果。标明事实来源。>
+
+## 2. 范围与分工
+
+<本次包含什么、不包含什么；双方配合事项和前置依赖。>
+
+## 3. 需求与验收
+
+### R-01：<可独立答复的需求>
+
+- 场景与影响：<谁、什么条件、当前问题及优先级理由>
+- 请求接收方：<可观察行为或交付物>
+- 提出方配合：<调用适配、资料、环境等必要事项>
+- 协作契约：<相关输入/输出、语义、权限或失败行为；标明已有约定或提议>
+- 验收条件：<前提 → 动作 → 可观察结果，必要失败场景及验证方/节点>
+- 期望与承诺：<期望日期/节点及理由；对方估计或承诺另列，无则待确认>
+- 当前结论：<待答复 / 接受 / 部分接受 / 替代方案待确认 / 不接受；附依据，注明尚未解决的范围>
+
+## 4. Q&A 问答澄清
+
+| 编号 | 关联需求 | 问题 | 提问方 → 待答方 | 阻塞哪一步 | 当前回答与待确认点 | 状态 / 依据 |
+| --- | --- | --- | --- | --- | --- | --- |
+| Q-01 | R-01 | <一个明确问题> | <项目/人员> | <步骤或非阻塞> | <待答；建议须标为建议> | <待答 / 部分回答 / 待确认 / 已解决；链接答复> |
+
+无待澄清事项时写「暂无」，不编造问题凑表。
+
+## 5. 交付与闭环
+
+<有实际进展时记录约定范围、交付物/版本、验收结果与证据、剩余事项及关闭依据。尚未交付则明确写明，拒绝或撤回单列原因与来源。>
+
+## 6. 往返答复记录
+
+本节始终位于文末，按收录顺序追加。首轮尚无答复时写「暂无答复」，不把以下格式示意当作已收到的消息。
+
+### RESP-01 · <发言方> · <答复主题>
+
+- 类型：<答复草案（未发送/未确认） / 已收到答复 / 补充确认 / 更正>
+- 发言方与项目：<实际来源；未知则注明>
+- 原消息时间：<实际时间；未知则注明>
+- 整理时间：<本次整理日期>
+- 来源：<本轮基于的 CRD 版本、返回文件及章节；独立消息则写标识/链接或本轮用户提供材料>
+- 关联：<R-01、Q-01；更正时注明原 RESP 编号>
+
+**答复原文或整理摘要**（二者明确区分）：
+
+<逐项保留答复、限制条件、未接受部分及理由；草案不得写成对方承诺。>
+
+**未答项与下一步**：<待谁回答/确认什么；有明确时间约定才填写。>
+
+<!-- 后续 RESP-02、RESP-03 等追加于此，保留已有记录。生成实际 CR 时移除模板说明和未使用的示意条目。 -->

package/skills/debugging/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: debugging
-description: Four-phase debugging framework that ensures root cause investigation before attempting fixes. Never jump to solutions. Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes.
+description: Use for bugs, test failures or unexpected behavior. Investigate and verify the root cause before proposing or implementing fixes.
 license: MIT
 ---
 

package/skills/dev-plan/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: dev-plan
-description: 基于用户需求、仓库规则和当前代码事实，撰写或评审可直接交给实现者执行、跨对话续做的开发计划、技术设计、立项方案与实施路线图。用户要求先规划后实施、写 PLAN/设计方案、评审既有开发计划时使用。按既有计划实施、续做或回写实施进度时不要使用——计划文件自带实施约定，直接读计划；用户只要求直接实现且没有计划文件时也不要使用。
+argument-hint: "<需求或既有计划> [新建/修订/评审] [范围] [输出路径]"
+description: 仅在用户要求撰写、修订或评审开发计划、技术设计、立项方案与实施路线图时使用；直接实现、按既有计划实施、goal 执行、续做或回写进度时不使用。基于需求、仓库规则与代码事实交付可执行、可跨对话续做的计划。
 ---
 
 # dev-plan · 基于代码事实的可执行开发计划
@@ -9,7 +10,9 @@ description: 基于用户需求、仓库规则和当前代码事实，撰写或
 
 ## 适用边界：只管写与评审，不管实施
 
-按既有计划实施或续做不用本 skill：计划开头的「实施须知」明确告诉实施者不要加载本 skill，「实施者定位」与「实施进度」已带齐实施需要的全部约定（进度回写、独立记录格式、subagent 并行、进度校验命令），实施者直接读计划。同一对话里写完计划接着实施，也按计划顶部两节执行，不再读本 skill 的参考。由此推出一条写作约束：**实施期需要的任何规则都必须写进骨架的这两节**，不能只留在本 skill 里。
+按既有计划实施、goal 执行或续做不用本 skill：「实施者定位」与「实施进度」已带齐实施需要的全部约定（进度回写、独立记录格式、subagent 并行、回写后自查），实施者直接读计划。同一对话里写完计划接着实施，也按计划顶部两节执行，不再读本 skill 的参考。由此推出一条写作约束：**实施期需要的任何规则都必须写进骨架的这两节**，不能只留在本 skill 里。
+
+生成计划不出现本 skill 名称、目录或脚本路径，包括“不要加载”的否定提醒；实施入口用正向指令说明先读哪些内容、如何推进与回写。计划提到规划、里程碑或就地修订实施偏差，不等于用户要求重新撰写或评审计划。若误在实施期加载本 skill，直接返回计划继续实施，不读取骨架或参考、不重走规划流程。
 
 ## 角色定位（写计划前先采用）
 
@@ -35,12 +38,12 @@ description: 基于用户需求、仓库规则和当前代码事实，撰写或
 
 ## 交付约定
 
-- **模板**：除非用户显式指定另一份模板，否则必须通读并使用本 skill 自带的 [references/plan-skeleton.md](references/plan-skeleton.md)。不要探测或依赖仓库内的 `PLAN-TEMPLATE`；出仓后的目标仓通常没有它。除开头固定的「实施须知」外，计划正文不提用了哪份 skill、骨架或参考——读者是实现者，写作用了什么工具与他无关。
+- **模板**：除非用户显式指定另一份模板，否则必须通读并使用本 skill 自带的 [references/plan-skeleton.md](references/plan-skeleton.md)。不要探测或依赖仓库内的 `PLAN-TEMPLATE`；出仓后的目标仓通常没有它。计划全文不提用了哪份 skill、骨架或参考——读者是实现者，写作用了什么工具与他无关。
 - **落盘**：用户指定路径优先；否则仓库根存在 `goal/` 时写 `goal/<代号>.md`，不存在时写 `docs/plan/<代号>.md`（按需创建目录）。目标文件已存在时先确认再覆盖。
 - **范例**：输出目录里若有同类型旧计划，可选读 1–2 份校准项目惯例；旧计划只是样例，不是事实源，路径、行为和数字仍须核实。
 - **代码基线**：Git 仓库中记录调查日期、commit SHA 和工作区是否 dirty；非 Git 仓库记录调查日期与可用版本标识。dirty 时说明相关事实来自当前工作树，不能只写 HEAD。只保留最近一次核对的一条基线，改稿时就地更新，不追加复核经过。
 - **计划状态**：使用 `Ready`、`Blocked` 或 `Proposed`。影响范围、安全、数据、外部契约或关键 NFR 的问题未决时必须是 `Blocked`；设计完整但等待非阻塞评审时可为 `Proposed`；无实施阻塞才是 `Ready`。顶部状态行只写状态，定级理由写 §11，实施进展只写「实施进度」。
-- **实施进度**：计划顶部是进度的唯一汇总入口，初稿初始化恢复快照和空的完成记录。实现与验收详情按里程碑保存在计划旁的 `<计划文件名去扩展名>.records/M<n>.md`，只留结果、验证证据与续做所需缺口；子任务不默认另建过程文档，不预建空记录。
+- **实施进度**：计划顶部是本计划实施进度的唯一汇总入口，初稿初始化恢复快照和空的完成记录。实现与验收详情按里程碑保存在计划旁的 `<计划文件名去扩展名>.records/M<n>.md`，只留结果、验证证据与续做所需缺口；子任务不默认另建过程文档，不预建空记录。
 
 ## 控制计划与执行成本
 
@@ -129,7 +132,7 @@ description: 基于用户需求、仓库规则和当前代码事实，撰写或
 - 写清实际前置成果及验证、可并行范围与共享文件/资源的单一负责人。前置已满足、契约稳定且互不干扰才可并行；按任务规模与集成成本决定是否委派，不为并行硬拆。复杂调度按需读 [references/execution-workflow.md](references/execution-workflow.md)。
 - 每个里程碑的退出条件逐行以「回写『实施进度』」结尾，防止完成后漏记。
 - 在计划顶部初始化实施进度：总里程碑数、当前状态、最近完成、下一步、阻塞和代码基线必须与里程碑表一致；计划尚未实施时如实写“0/N、尚未开始、下一步 M1”，不得预填完成记录。
-- 骨架开头的“实施须知”及“实施者定位”“实施进度”协议原样带入计划，不改写、不删减：它们是给执行计划的 agent 的完整合同，与写计划的架构师定位是两回事。唯一的填空是“回写后自查”里的 `<进度校验命令>`：本 skill 目录在目标仓内时，换成从仓库根可直接运行的 `bash <本 skill 目录相对仓库根的路径>/scripts/check_progress.sh <计划相对仓库根的路径> .`；不在仓内（全局安装）时把整句改成“每次回写后按上述条目人工核对”，不写本机绝对路径。
+- 骨架开头的“实施须知”及“实施者定位”“实施进度”协议原样带入计划，不改写、不删减：它们是给执行计划的 agent 的完整合同，与写计划的架构师定位是两回事。回写后自查按计划内条目直接核对，不引入本 skill 的脚本依赖；`check_paths.sh` 与 `check_progress.sh` 留在撰写/评审期使用，不列入计划的实施或终验命令。
 - 计划按风险和改动面裁剪，不用固定行数或章节占比衡量质量；调查原始材料不倾倒进正文，只保留结论与来源。
 
 ## 第 5 步：自检、就绪与交付
@@ -138,7 +141,7 @@ description: 基于用户需求、仓库规则和当前代码事实，撰写或
 2. 对照需求账本或映射表检查 `R-* / NFR-* / C-* / A-*`：每条有设计、验证、排除去向或阻塞说明；同一事实和断言没有多处展开。
 3. 按 `references/architecture-quality.md` 的一致性清单检查凭证/scope、接口/调用方、数据约束/生命周期、设计/验证、发布/回滚和多处重复口径。
 4. 建失败模式表：高影响失败至少写触发、爆炸半径、数据后果、用户表现、检测、恢复与验证；简单局部任务可说明“不引入新的运行期失败模式”及依据。
-5. 检查顶部实施协议为骨架原文在位、`<进度校验命令>` 已替换；每个里程碑退出条件以「回写『实施进度』」结尾，依赖与并行边界明确，阶段收口覆盖被集中的验收且保留必要风险门；跑 `"$SKILL_DIR/scripts/check_progress.sh" <计划文件> <仓库根>` 确认进度与里程碑一致、记录链接有效；初稿不预填完成事实，详情不写回计划。
+5. 检查顶部实施协议为骨架原文在位，计划全文没有本 skill 名称、目录或脚本依赖；每个里程碑退出条件以「回写『实施进度』」结尾，依赖与并行边界明确，阶段收口覆盖被集中的验收且保留必要风险门；跑 `"$SKILL_DIR/scripts/check_progress.sh" <计划文件> <仓库根>` 确认进度与里程碑一致、记录链接有效；初稿不预填完成事实，详情不写回计划。
 6. 最终定级：存在影响范围、安全、数据、外部契约或关键 NFR 的未决项即 `Blocked`；只等非阻塞评审为 `Proposed`；所有实施前置已解决才是 `Ready`。
 7. 汇报计划路径与状态，并单列：待拍板问题、与用户假设冲突的事实、被砍/推迟的范围、未在真实环境完成的调查或验证。
 
@@ -151,5 +154,11 @@ description: 基于用户需求、仓库规则和当前代码事实，撰写或
 - 不吞需求，不把重大假设藏进正文，不把阻塞计划标为 `Ready`。
 - 不把未通过退出条件的里程碑写成已完成，不用聊天记录代替计划内的简要进度与独立的实现/验收记录；不在续做时批量加载历史记录。
 - 不为假想扩展造接缝、基础设施或抽象，也不照搬通用架构示例覆盖仓库现实。
-- 计划里不写写作过程（开头固定的「实施须知」除外）：用了哪份 skill / 模板 / 参考资料、读过哪些规则文件的清单、调查或复核做了几轮、评审意见的采纳与改稿经过、“本次只写/修订计划、未实施”这类写作当时的状态、“本轮/刚才”这类只在写作对话里成立的指代（来源写“用户 YYYY-MM-DD 确认”）。它们既不是实施事实也不是里程碑进展，会随实施过期、误导实施者、白占上下文；提到 skill 还会诱导实施者去加载只有写计划才需要的内容。
+- 计划里不写写作过程：用了哪份 skill / 模板 / 参考资料、读过哪些规则文件的清单、调查或复核做了几轮、评审意见的采纳与改稿经过、“本次只写/修订计划、未实施”这类写作当时的状态、“本轮/刚才”这类只在写作对话里成立的指代（来源写“用户 YYYY-MM-DD 确认”）。它们既不是实施事实也不是里程碑进展，会随实施过期、误导实施者、白占上下文；提到 skill 还会诱导实施者去加载只有写计划才需要的内容。
 - 不在出仓 skill 中硬编码某个仓库的模板、技术栈、端口、样板计划、本机路径或业务约定；这些必须在运行时从目标仓规则和代码读取。
+
+## 项目状态回写
+
+若仓库已登记状态台账，或存在仓根 `.xgent-ai/sdlc/protocol.md`（兼容已有 `docs/project-status/protocol.md`；两套并存且未登记切换时先核对，不能双写），交付原产物后读取台账的回写规则（默认目录读上述协议），按其格式新增本次事实记录并刷新受影响的状态页与必要索引；未启用时不自动建表，不依赖另装技能。只读/仅聊天/不保存要求优先，登记失败须说明，不影响如实交付已完成的原产物。
+
+登记计划的实际路径、版本、就绪状态与需求关联；实施状态只取顶部真实进度。评审模式登记独立评审事实，不替原计划改状态；本次仅聊天时不登记。