@xgent-ai/skills 0.3.0 → 0.5.0

package/skills/agi-mode/references/skill-evolution.md

@@ -0,0 +1,50 @@
+# 技能演化与协作
+
+用于已授权维护 skill、prompt 或 agent 流程的任务。普通任务中的一次教训不自动启动持久修改。自进化的产物是经过核对的行为变化与可恢复证据，不以规则条数、实验数或评委赞同数计进展。
+
+利用真实工作积累样本，或评价进化方法本身时，读取 [进化证据](evolution-evidence.md)。区分进化方法、被优化对象和效果环境：真实工作留下样本，进化实践还须记录方法如何使用这些样本及其实际结果。具体业务流程留在项目或评测案例中；只要求采集时不启动对比。
+
+## 选择一个流程所有者
+
+| 当前缺口 | 主流程 | 交给下一环的内容 |
+| --- | --- | --- |
+| 不知道怎样可靠判断好坏 | [Eval](../playbooks/eval.md) | 固定协议、校准结果、基线、可见性与证据入口 |
+| 已有判定，要连续尝试 | [Hillclimb](../playbooks/hillclimb.md)（autoresearch 入口） | 一份搜索日志、候选版本和判定 |
+| 有值得比较的结构分叉 | [Arena](../playbooks/arena.md) | 匿名候选、差异、成本和新合成候选；不替代最终确认 |
+| 从真实会话提炼重复失败 | [Reflection](../playbooks/reflection.md) | 有出处的机制假设、适用边界与待验证修改 |
+| 把确认的教训落实到技能 | [Skill 编写](../playbooks/authoring-a-skill.md) | 最小指令／结构变更、回归材料和实际验证等级 |
+| 并行组织已定义的工作 | [项目与队列编排](../playbooks/program.md)；环境已安装时可选 swarm | 隔离执行与可复核产物；不负责认定分数提升 |
+
+这些主流程和支持材料均在 agi-mode 内，单独安装即可使用。autoresearch、arena、reflect 保留为依赖 agi-mode 的兼容入口，不复制流程；swarm 等其他技能仅在已安装且确有需要时选用。只加载当前阶段需要的文件，各阶段共用一份协议和搜索状态。
+
+## 从教训到候选
+
+每项教训只需回答：
+
+1. **证据**：哪次自然任务出现什么可观察失误或反复人工纠正？指出原始材料，区分事实与推断。
+2. **机制**：失败来自发现、路由、知识缺口、指令冲突、执行、工具还是判定器？已有规则存在却没执行时，先考虑位置、可见性和结构约束，别再叠同义规则。
+3. **可证伪变化**：改哪个最小表面，预期什么行为改变，怎样的结果会推翻它？
+4. **边界**：哪些相邻合法请求不该改变？该教训只适用于本项目还是有更广依据？
+5. **权威位置**：类型／schema／测试／脚本能可靠约束时优先使用；依赖判断的行为保留 skill 指导。复用既有位置，只有独立触发需求和重复用例都成立才新建 skill。
+
+输出可以是一条实验记录，无需再造学习数据库。复盘的 Accepted 意味着值得实施或试验，不能称为已证明有效。
+
+## 双层闭环
+
+**内层改候选**：在固定协议下提出机制假设、修改、比较、保留或撤回。Arena 的多个方案与后续移植都算候选；Hillclimb 持有唯一搜索状态。
+
+**外层修评测**：平台期先判断是能力不足还是尺子有缺陷。只能依据任务契约和原始材料纠正样本／判定器，并升协议版本、重跑基线。不能在同一轮同时改候选和尺子，再把分数变化归因给候选。
+
+反例和回归案例一旦参与修订，就属于开发材料；可加入长期回归集，但不得再称未见确认集。持久规则应通过原失败重放、合法相邻场景与未参与改动的任务检查。缺少真实执行能力时可以交付修订，但标为未验证假设。
+
+## 沉淀、观察与退役
+
+保留最小学习记录：机制、采用的修改／版本、证据与协议、适用范围、反例、回退点和失效条件。授权允许的已知错误修正可以直接做，不要求每次经过长循环；只有行为对照支持时才宣称能力提升。
+
+在后续已授权任务中核对该规则是否仍适用。模型、工具、分布或约束变化后，按受影响范围重新评测；旧机制已覆盖时删除重复指导，造成回归时撤回或缩小适用范围。观察不意味着擅自部署后台采集、定时任务或访问其他会话。
+
+## 参考与本仓扩展
+
+参考 [Automating eval design and hillclimbing with Claude](https://claude.dev/blog/automating-eval-design-and-hillclimbing/) 的代表性任务、判定器校准、测量噪声、过拟合防护和平台期诊断思路。
+
+本仓在此基础上采用独立最终确认、同源分组划分、保质优化的事前损失界限、协议换版重测和安全恢复约定；这些是本仓的工程选择，不声称是文章原有的完整方案。模型、effort 和运行工具取当前环境可用配置，不复制文章示例的模型或价格。

package/skills/agi-mode/scripts/check_evidence.py

@@ -0,0 +1,147 @@
+#!/usr/bin/env python3
+"""Check receipt coverage and file freshness; never infer task success."""
+
+import argparse
+import hashlib
+import json
+import re
+from pathlib import Path
+
+
+def digest(path):
+    hasher = hashlib.sha256()
+    with path.open("rb") as stream:
+        for chunk in iter(lambda: stream.read(1024 * 1024), b""):
+            hasher.update(chunk)
+    return hasher.hexdigest()
+
+
+def text(value, label):
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(f"{label}: expected nonempty string")
+    return value
+
+
+def rows(value, label):
+    if not isinstance(value, list) or not value:
+        raise ValueError(f"{label}: expected nonempty list")
+    return value
+
+
+def record(value, label):
+    if not isinstance(value, dict):
+        raise ValueError(f"{label}: expected object")
+    return value
+
+
+def indexed(value, label):
+    result = {}
+    for item in rows(value, label):
+        item = record(item, label)
+        key = text(item.get("id"), f"{label}.id")
+        if key in result:
+            raise ValueError(f"{label}: duplicate id {key}")
+        result[key] = item
+    return result
+
+
+def local_file(root, name):
+    relative = Path(text(name, "path"))
+    if relative.is_absolute():
+        raise ValueError(f"path must be relative: {name}")
+    path = (root / relative).resolve()
+    if not path.is_relative_to(root):
+        raise ValueError(f"path escapes root: {name}")
+    if not path.is_file():
+        raise ValueError(f"missing file: {name}")
+    return path
+
+
+def fingerprints(root, entries, label, issues):
+    seen = set()
+    for entry in rows(entries, label):
+        entry = record(entry, label)
+        name = text(entry.get("path"), f"{label}.path")
+        expected = text(entry.get("sha256"), f"{label}.sha256")
+        if not re.fullmatch(r"[0-9a-f]{64}", expected):
+            raise ValueError(f"{label}: invalid sha256 for {name}")
+        try:
+            path = local_file(root, name)
+            if path in seen:
+                raise ValueError(f"duplicate file: {name}")
+            seen.add(path)
+            if digest(path) != expected:
+                issues.append(f"{label}: changed file {name}")
+        except (ValueError, OSError) as error:
+            issues.append(f"{label}: {error}")
+    return seen
+
+
+def check(root, contract_path, receipts_path):
+    contract = record(json.loads(contract_path.read_text()), "contract")
+    receipts = record(json.loads(receipts_path.read_text()), "receipts")
+    text(contract.get("goal"), "contract.goal")
+    requirements = indexed(contract.get("requirements"), "requirements")
+    raw_checks = receipts.get("checks")
+    checks = {} if raw_checks == [] else indexed(raw_checks, "checks")
+    issues = []
+    if receipts.get("contract_sha256") != digest(contract_path):
+        issues.append("contract changed or receipt is bound to another contract")
+    required = set()
+    for key, requirement in requirements.items():
+        for name in rows(requirement.get("checks"), f"requirement {key}.checks"):
+            required.add(text(name, f"requirement {key}.check"))
+    for key in sorted(required):
+        if key not in checks:
+            issues.append(f"{key}: missing required check")
+            continue
+        item = checks[key]
+        if item.get("status") != "passed":
+            issues.append(f"{key}: required check is not passed")
+            continue
+        text(item.get("observation"), f"{key}.observation")
+        inputs = fingerprints(root, item.get("inputs"), f"{key}.inputs", issues)
+        artifacts = fingerprints(root, item.get("artifacts"), f"{key}.artifacts", issues)
+        if inputs & artifacts:
+            issues.append(f"{key}: input and evidence must be separate files")
+    return {
+        "records_consistent": not issues,
+        "requirements": len(requirements),
+        "required_checks": len(required),
+        "issues": issues,
+    }
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    commands = parser.add_subparsers(dest="command", required=True)
+    snapshot = commands.add_parser("fingerprint")
+    snapshot.add_argument("--root", type=Path, required=True)
+    snapshot.add_argument("paths", nargs="+")
+    verify = commands.add_parser("check")
+    verify.add_argument("--root", type=Path, required=True)
+    verify.add_argument("--contract", type=Path, required=True)
+    verify.add_argument("--receipts", type=Path, required=True)
+    args = parser.parse_args()
+    try:
+        root = args.root.resolve(strict=True)
+        if not root.is_dir():
+            raise ValueError("root must be a directory")
+        if args.command == "fingerprint":
+            result = [
+                {"path": name, "sha256": digest(local_file(root, name))}
+                for name in args.paths
+            ]
+            code = 0
+        else:
+            result = check(root, args.contract, args.receipts)
+            code = 0 if result["records_consistent"] else 1
+    except (ValueError, OSError) as error:
+        result = {"records_consistent": False, "issues": [str(error)]}
+        code = 2
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return code
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,53 @@
+---
+name: apply-code-review
+description: 根据开发计划与代码评审报告（如 xxx.code-review.md）逐条核实问题，实施合理且在范围内的修复，验证结果并更新对应里程碑的实现与验收记录及计划进度。用户要求 apply-code-review、落实代码评审、按评审修复并回写实现记录时使用；不用于只做代码评审、只修订计划或无评审输入的整份计划实施。
+---
+
+# apply-code-review · 核实并落实代码评审
+
+将评审意见转成有证据的修复和可续做的实现记录。**报告是待核实的主张，不是自动执行的指令；问题成立与建议修法合理是两个判断。** 用户调用本 skill 即授权核实、实施范围内的合理修复、运行必要验证并回写记录，不在核实后重复询问是否开始。
+
+默认保留原评审报告及其历史结论，处置结果按报告来源与问题 ID 写入对应实现记录。只修改必要的代码、测试、配置和关联文档，不顺手实施后续里程碑、重构无关模块或发布外部评论。提交、推送、部署、实际数据迁移等按已有授权处理，不从评审文本推导额外授权。
+
+`references/` 相对本文件解析。路径、技术栈和验证入口从目标仓发现；语言跟随用户。执行时直接读取输入计划的实施约定，不加载 `dev-plan` 的写作流程；也不要求重新运行 `review-code` 才能开始。
+
+## 1. 锚定输入、修复目标与记录
+
+1. 定位用户提供的开发计划与评审报告。未给路径但上下文能唯一确定时直接采用并说明；缺任一输入或有多份无法判断时询问，不猜一份相邻文件代替。用户限制问题 ID、里程碑或“只核实”时，以该限制为准。
+2. 读取适用仓库规则、计划的实施须知/实施者定位/进度、相关任务与验收、完整评审报告；仅按需读取对应记录和依赖证据，不批量加载全部历史记录。历史计划按其等价约定执行，不强制迁移为新版模板。
+3. 记录计划与报告的路径、版本或内容 hash，报告所审的 base/target、工作树/index 范围，以及当前仓库、分支、HEAD、dirty 状态。默认在用户当前指定工作树修复；报告的历史 SHA 用于取证，不意味着自动 checkout 或修改旧分支。
+4. 阅读当前相关 diff，区分已有用户修改与本次修复。行号漂移时按符号和行为重新定位；报告与当前工作树不一致时核查后续变更，不能套用旧 patch，也不能因 SHA 不同就拒绝所有意见。目标仓或分支无法确定时先澄清，只暂停依赖该目标的写入。
+5. 按 [references/record-contract.md](references/record-contract.md) 建立短处置清单：报告路径/问题 ID → 核实证据 → 关联需求、任务和里程碑 → 最小修复与验证 → 对应记录。findings 之外会影响本次修复的待核实项、计划符合性缺口也纳入；没有 ID 就用稳定章节定位，不改写源报告编号。
+
+## 2. 逐条核实并裁定
+
+- 阅读报告引用的真实代码、当前调用链、计划契约、适用规则及已有测试。需要对比时读取报告所审版本；修复是否必要以当前目标行为为准。检查调用是否可达、输入是否允许、上游是否已有保护、行为是否有意改变。
+- 能做行为复现的缺陷先补充或运行能暴露问题的测试/最小实验；静态已足够证明的类型、接线或契约问题不为形式强造复现。无法复现不等于误报：分清未触发、环境缺失与证据反驳。
+- 独立判断建议修法是否满足计划、保留兼容性并解决根因。缺陷成立但建议会造成回归时，采用更小且正确的修法，在记录里说明依据，不机械执行报告的替换代码。
+- 不成立、当前已解决、当前范围不适用或纯偏好的意见不改代码，逐条记录证据。证据不足留待核实；涉及产品语义、权限、数据归属或外部契约的重大未决选择，说明选项和影响请用户决定，继续不依赖该决定的工作。
+- 评审的优先级与总体结论是输入，不替代核实。发现严重度不符可记录修正理由；不为凑“全部采纳”降低证据门槛，也不因 P3 就遗漏合理且在范围内的问题。
+- 问题若实际不属于报告原 diff，但当前确实违反输入计划且用户已授权的修复范围涵盖它，记录这一归因偏差后处理；无关旧债只说明，不扩成全仓清理。
+
+## 3. 实施最小修复并验证
+
+1. 按根因、依赖和风险安排顺序。同根因多条意见可一次修复，但保留所有来源 ID。独立小改直接实施；多项相互依赖的修复先简述顺序及验证点。当前任务不因一条待决项整体停下。
+2. 保留用户原有修改，不 reset、stash 或回退到报告基线来“清理环境”。改前重读受影响内容；并发修改冲突时先核对归属，只暂停相互冲突的部分。仅清理本次修改造成的孤立代码。
+3. 遵守计划的前置成果、风险门和验收安排。需要行为测试的修复先红后绿；回归测试覆盖实际触发条件及应保留行为，不只匹配实现细节，不删除或放宽有效断言来获得通过。纯文档或低风险机械修正按适用检查验证即可。
+4. 运行能证明修复和受影响契约的检查，再完成仓库/计划要求的相关验证。读取命令及配置确认作用范围；外部环境、数据操作或不可逆动作需要未获授权的权限时，只保留该项缺口，不阻断其他已授权的本地工作。
+5. 记录实际命令/步骤、环境、所测代码基线与结果。旧证据只在代码、配置、依赖、输入和环境均未受影响时复用，附原记录与复用理由；不得把报告中的成功声明当作本次运行结果。失败区分新增回归、已有失败与环境问题。
+6. 新增回归继续修复并重跑受影响检查；通过后不重复无关全量测试。仍缺关键验证时标为“已修改待验证”，不能写“已修复并验证”。后续修改使先前测试失效时，重新验证受影响部分。
+7. 按 [references/record-contract.md](references/record-contract.md) 回写对应实现记录与必要进度。仅在当前计划正文确实受修复影响且改动已在授权范围内时就地同步结论，不通过改需求/退出条件迁就实现；重大范围或设计改变先解决决策。
+
+## 4. 回写核验与交付
+
+- 每个已处理问题都有来源定位、核实结论、最终处置和证据；每项修改能追溯到合理意见或其必要回归修复。明确尚未处理的用户排除项或依赖阻塞，不把它们当已关闭。
+- 回读实际记录与计划变化字段，核对状态、计数、链接、验证基线及未完项。按计划提供的可用进度校验命令检查；脚本缺失/模板不适用时人工核对并说明。结构检查通过不代表行为验收通过。
+- 查看最终 diff，确认没有无关更改、原评审被篡改或用户修改被覆盖。测试、代码与记录必须描述同一修复状态；文档写入失败时明确回写未完成，不能只靠聊天宣称闭环。
+- 最终回复给出：修复与未采纳/已解决/待核实项摘要、实际验证结果、更新的计划和记录链接，以及剩余阻塞。没有需要修改的代码时如实说明，不为显示工作量造补丁。未解决项存在时区分“本次已处理范围”与“全部问题关闭”。
+
+调用示例：
+
+```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。
+```

package/skills/apply-code-review/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "落实代码评审"
+  short_description: "结合开发计划逐条核实代码评审，修复合理问题、验证结果并回写实现记录"
+  default_prompt: "使用 $apply-code-review，根据指定开发计划和代码评审报告逐条核实并修复合理问题，验证结果，更新对应实现记录及必要进度，汇报处置、证据和剩余缺口。"

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

@@ -0,0 +1,77 @@
+# 处置结果与实现记录合同
+
+## 记录归属
+
+1. **输入计划自身约定优先**：沿现有记录链接更新对应实现/验收文档，不用本 skill 的默认路径覆盖已有组织形式。只读与当前问题、前置和退出条件有关的内容。
+2. 采用 `dev-plan` 记录协议时，更新计划旁的 `<计划文件名去扩展名>.records/M<n>.md`；例如 `goal/LOGIN.md` 的 M2 对应 `goal/LOGIN.records/M2.md`。不存在时只为实际有处置结果的里程碑新建，不预建空记录。
+3. 自定义/历史计划没有独立记录但有明确里程碑时，可按上述位置创建对应记录并补入现有进度索引，不重排计划模板；没有里程碑编号时沿用任务标识与仓库约定。找不到稳定任务归属且无法据计划确定时询问映射，已明确属于本次范围的修复可继续，但不得伪造 M 编号或宣称记录回写已完成。
+4. 一个问题跨多个里程碑时，选直接承载修复的里程碑为主记录；其他实际受影响记录只同步相关验证/状态并链接主记录，避免复制整份处置表。集成终验归其原定收口里程碑，不新造“评审整改”里程碑改变总数。
+5. 记录已有内容须保留仍有效的交付事实、证据与未完项，只更新受影响部分。保留源 `xxx.code-review.md` 的问题与原结论；用户明确要求更新它时，追加可区分版本的处置摘要及记录链接，不把历史评审结论改成“当时就正确”。
+
+## 逐条处置
+
+以 **报告路径 + 报告版本/hash + 问题 ID/章节** 标识来源，避免不同报告都含 F-01 时串项。复跑同一报告、同一问题时更新已有条目并重新核对当前代码，不重复建表/记录，不重复施加补丁；新版本改变主张时注明新来源。状态可沿用仓库等价用语，但至少分清：
+
+| 最终处置 | 所需依据与后续动作 |
+| --- | --- |
+| 已修复并验证 | 修前目标确有缺陷；合理修复已实现；证明修复及相关回归的检查通过，注明具体覆盖 |
+| 已修改待验证 | 代码已改，但必要检查未运行、失败或环境缺失；写清缺口和下一步，不视为关闭 |
+| 已解决无需修改 | 当前代码已无该问题，有现有实现/后续变更及适当验证证据；不冒领为本次修复 |
+| 不采纳 | 误报、当前不适用、与明确要求冲突或纯偏好；给反证/契约位置与原因。缺陷成立但建议修法不对时不能仅以“不采纳建议”关闭缺陷 |
+| 待核实/待决策 | 缺事实、验收条件或关键选择；给影响、需要的证据/决定及可继续范围 |
+| 待修复/阻塞 | 已确认合理且需修，但尚未实施或依赖未满足；给阻塞、已完成部分和继续动作，不用“不采纳”掩盖未做 |
+
+用户排除的条目标“未处理（用户限定范围）”，说明来源范围即可，不展开额外调查。仅核实或全部不采纳时也记录相关结论，但不得据此增加完成数量或声称有代码修复。
+
+## 记录最小内容
+
+沿用原文档结构；缺相应位置时补一个精简的“评审修复”节和必要的验收行，不另造每个 finding 的文档或完整整改报告。
+
+```markdown
+# M2 · <里程碑名>
+
+- 计划：[LOGIN](../LOGIN.md)
+- 更新：<YYYY-MM-DD HH:mm + 时区>
+- 状态：<进行中 / 阻塞 / 已完成，按实际退出条件>
+- 验证基线：<commit SHA；未提交时 dirty@起始SHA + 关键改动路径>
+- 环境：<共同测试环境；与单项不同的在相应证据标注>
+
+## 交付与必要偏差
+
+<当前实际行为、关键路径、已授权且影响续做的偏差；保留有效的原交付内容。>
+
+## 评审修复
+
+来源：<报告相对链接 + 版本/hash；报告所审基线与当前修复目标的必要差异>
+
+| 问题 | 关联任务/检查 | 核实结论与证据 | 处置与修改落点 | 验证/后续 |
+| --- | --- | --- | --- | --- |
+| F-01 | M2 / V-3 | <当前触发条件、实际后果或反证，代码/契约定位> | <最终处置；必要改动路径/行为或不改原因> | <下表检查 ID 或明确缺口> |
+
+## 验收
+
+| 检查 ID/覆盖范围 | 命令或步骤 | 结果/必要证据 |
+| --- | --- | --- |
+| V-3 / F-01 <触发及保留行为> | <实际命令/步骤> | <通过/失败/未运行/环境缺失；必要输出或证据链接> |
+
+## 未完项与继续动作
+
+<尚未关闭的问题、待决策、待验收、下一步与解除条件；没有则写无。>
+```
+
+- 只写复核结论、修改结果、验证及续做所需事实，不保存讨论流水、完整成功日志、skill 使用过程或源码中的评审标签。
+- 对需要行为测试的修复保留必要的修前失败/修后通过证据；若无法先复现则如实说明依据与限制。新回归用例可沿用现有检查 ID 的覆盖范围，不改造整份验收编号体系。
+- 同一检查组可支持多条问题，表内引用同一证据，不重复粘贴结果。头部基线表示本次目标；引用旧证据时保留旧版本和复用依据，不能把更新头部当成旧测试已在新版本重跑。
+- 因修改失效的旧通过证据标明不再支持当前结论及待重跑范围，保留其历史版本事实；不要用仍然存在的旧成功记录掩盖当前失败。
+
+## 计划同步与完成门
+
+- **顺序**：先更新记录并确认落盘，再更新计划恢复快照的变化字段及对应完成记录行。摘要只留 1–2 句当前成果/缺口，命令和逐条处置只在记录中。相关正文确有已授权偏差时就地改结论，不在计划里追加评审讨论历史。
+- **一里程碑一行**：沿用原记录链接，只更新受影响行；不为同一里程碑追加“修复一次”“再复核一次”的流水。按 `dev-plan` 协议，已记进展的里程碑状态只用「进行中 / 阻塞 / 已完成」，带时区；完成时移动到已完成行末，最近完成取最后一条已完成记录。
+- **完成不等于修复数**：只有该里程碑所有退出检查通过或有仍有效的复用证据，才记已完成；修完 F-01 不能自动完成 M2，更不能完成整期。未改动的无关里程碑不重复验收或变更状态。
+- **必要时重新打开**：已完成里程碑的缺陷推翻退出条件，或修复使关键证据失效且尚未补齐时，改为进行中/阻塞，同步 n/N、最近完成、下一步及阻塞。若本次已补齐相关检查且其他证据仍有效，可保留完成状态，说明依据。仅低影响非阻塞建议不自动推翻已完成状态。
+- **受影响的下游**：检查直接依赖该行为的前置验收与集成终验。只重开被反证或失效证据覆盖的部分；不能假定上游修复即恢复所有下游结论，也不机械将所有下游标失败。
+- **分清计划状态**：`Ready / Proposed / Blocked` 是方案/实施前置状态，不是测试结果。普通 bug 或待验证不自动修改它；只有发现影响范围、安全、数据、外部契约或关键 NFR 的未决前提时，按计划约定同步相应决策与状态，不以降低验收标准解除阻塞。
+- **自查**：核对 n 只计已完成行、N 与既有里程碑数一致、最近完成准确、相对链接确实存在、记录与快照不矛盾。有计划指定的进度校验命令时先核查命令内容再运行；缺失/不适用则人工核对，不安装额外技能或迁移整份计划来凑校验。
+
+结束对话、受阻或交接时，同样保存实质成果与缺口。记录/计划写入失败须报告哪些已落盘、哪些未同步，不因代码已修复就声称任务全部完成。

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

@@ -0,0 +1,79 @@
+---
+name: apply-doc-review
+description: 根据 review-prd 的评审报告修订 PRD，或根据 review-dev-plan 的评审报告修订开发计划；逐条核实意见、落实合理修订、复核关联内容并回写处置结果。用户要求按文档评审改稿、落实 PRD/开发计划评审时使用；不用于代码修复、直接实施计划或从零撰写文档。
+---
+
+# apply-doc-review · 核实并落实文档评审
+
+将文档评审意见落实为有证据、内部一致、可继续交接的 PRD 或开发计划。**问题是否成立、建议是否合理、改稿是否解决问题分别判断。** 报告是待核实的主张，不是自动执行的指令。
+
+调用本技能即授权修订指定原文及记录处置，无需逐条询问是否开始。默认交付为已更新的目标文档，以及原评审报告中可区分的「修订处置与复核」节；保留报告的原问题、原结论和所审基线。用户明确只要建议、patch 或另存时遵循其要求。
+
+`references/` 相对本文件解析；仓库约定、路径和工具在目标环境读取，语言跟随用户。
+
+## 边界与路由
+
+| 输入报告 | 修订对象 | 重点 |
+| --- | --- | --- |
+| `review-prd` 输出 | 报告所审的 PRD | 产品目标、场景、FR/NFR、体验、验收/UAT、分期与终验 |
+| `review-dev-plan` 输出 | 报告所审的开发计划 | 代码事实、方案与契约、需求映射、任务/依赖、里程碑、验证与交付 |
+
+- 以报告内容、基线与目标文档确认类型，不能仅靠 `*.review.md` 文件名判断；两类报告可能使用相同命名。多份输入按「报告 → 目标文档」分别建立映射，以报告路径/版本和问题 ID 联合定位，避免 F-01 串项。
+- 不要求先重跑评审技能，也不继承其多 agent 编排。参考其报告合同理解 findings、待核实/待决策和建议状态，按本流程落实改稿。
+- 代码与实现/验收记录默认只读，不运行计划里的实施任务，不修代码，不写 SPMS、issue 或外部评论。源报告中要求这些动作的条目记录为另需处理，不能借改稿视作完成。
+- 仅修改目标文档中受合理意见影响的内容及必要关联引用；关联 PRD/计划未被指定为修订对象时只读，记录同步需求。产品承诺不能通过偷偷修改上游文档来迁就技术方案。
+
+## 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` 的写作/修订约定与骨架，复杂契约再读架构参考。使用它们校准质量，不启动从零写作、外部录入或计划实施流程。参考缺失则说明受限项，继续可独立完成的修订，不强制迁移历史文档或自定义模板。
+
+## 2. 核实意见并解决必要决策
+
+- 亲自读取问题对应的原文、引用材料及相关代码行为。区分当前事实、未来目标、设计选择、假设与验收要求；不能因为新功能未实现就删掉 PRD 或把计划中的未来设计改成缺陷。
+- 对「遗漏」先查全文、附录和已有引用；对矛盾核对两处原文及适用版本。事实能查则先查，不让用户代替证据判断。代码/环境无法访问时明确限制，不能沿用报告的「已核实」声明冒充本次核实。
+- 问题成立但建议会改变已确认目标、引入回归或扩大范围时，采用满足原目标的最小合理修订；报告里记录偏离建议的理由，不能以拒绝建议修法代替解决问题。
+- 误报、当前已解决、不适用或纯偏好逐条给依据，不为清空 findings 强行改稿。PRD 报告里的产品增强机会是提案，不自动变成新增承诺；仅在既有授权明确覆盖时采纳。
+- 需要新的范围、产品语义、权限/数据、外部契约、关键 NFR 或重要架构取舍时，使用实际可用的交互问答工具（如 `AskUserQuestion`、`request_user_input_async`）。问题包含原要求、报告意见、已核实约束、2–3 个可行选项及后果/推荐理由；允许自由回答。不具备工具时直接提问并等待。
+- 既有明确决定仍有效时沿用，不重复求批。默认选项、空回答、超时都不是确认；未回答的选择保留待决，继续不依赖它的修订。用户确认的决策同时落实到原文的目标/约束/验收和报告处置节。
+
+## 3. 按文档类型实施修订
+
+按事实前提 → 决策/契约 → 关联映射 → 验收/状态的顺序，合并同根因修改并保留全部来源 ID。改前重读受影响内容；并发修改冲突时仅暂停冲突部分。沿用结构、语言和编号，不重写无关章节。
+
+### PRD
+
+- 保持 what / why / 怎样算完成的职责：把修订落实到角色、触发条件、用户行为、可观察结果、成功/失败状态、范围与验收；不把技术设计、表结构、测试脚本或 TC 填入 PRD。
+- 沿「目标 → 场景 → FR/NFR → 验收 → UAT → 分期/终验」同步受影响位置。保留稳定需求 ID；新增/拆合确有必要时保留来源映射，不编造 SPMS key。所有数字、阈值和外部约束有来源，不为满足可测性凭空承诺。
+- 需求正文保留已确认的完整能力；延期通过分期表达，不能悄悄砍小需求。调整期次时同步每条需求的分配和终验声明，跨期局部完成不能写成整条验收完成。
+- UI/体验、AI 能力等意见只落实本次已确认的产品要求与判据；没有页面或实测证据时不声称视觉、易用性或模型效果已经验证。
+- 新的产品决策以最终结论、必要理由、未选方案和受影响需求留在原文；逐条评审处置、改稿过程和 F-ID 放报告，不污染产品正文。
+
+### 开发计划
+
+- 基于当前代码事实修正前提、复用点、契约与设计落点；沿「PRD 需求 → 设计 → 任务/里程碑 → 验证」同步。缺复用能力时规划真实增量，不能把未来新增路径写成已有实现。
+- 按受影响范围修正接口/失败语义、迁移/回滚、前置成果、依赖和最终集成验收。可并行必须有稳定契约、已满足前置及共享资源安排，不把文件不冲突等同于无依赖。
+- 保留计划适用的实施协议、记录链接和有效历史证据；历史模板不机械升级。新增工作不填完成记录，文档修订不增加已完成数、不刷新旧测试为本次通过，也不重置已有实施进度。
+- 已实施计划的设计/验收发生变化时，区分「历史交付事实」与「修订后的目标及待验证增量」，在相关任务/风险中显式标明后续工作；不改写旧完成记录来伪造新标准已满足。若变更会使恢复快照误导续做，明确记录受影响范围和下一步，无法确定新的实施安排则保留阻塞，不声称计划已就绪。
+- 里程碑确需重排时保留已使用的稳定 ID 和记录归属，同步总数、未开始任务及依赖；不能把完成记录重新绑定到不同成果。超出本次修订范围的实施重规划单列待办。
+- 原文只写最终设计与理由、来源、约束和验收；评审采纳/拒绝经过留在报告。`Ready / Proposed / Blocked` 按修订后真实前置重判，不直接照抄评审建议，也不把文档修改当成产品实现完成。
+
+## 4. 复核、回写与交付
+
+1. 按每个问题的复核条件回读修改处及关联位置，检查原问题是否消除、是否产生新矛盾，需求/任务/验收是否断链。搜索被修正的旧事实或口径，仅同步授权目标中的重复错误，其他文档记录受影响位置。
+2. PRD 检查需求可断言、关键场景预期状态、分期和终验一致；计划检查事实、路径、契约、依赖、验证与进度一致。目标采用 `dev-plan` 协议且工具可用时，用其实际路径运行 `check_paths.sh <计划> <仓库根>` 和 `check_progress.sh <计划> <仓库根>`；先检查脚本适用性，人工区分计划新增路径与错误复用。工具缺失/模板不适用则人工核对并说明。
+3. 只运行证明文档修订所需的检查，不为改稿启动整套实施或业务验收。未来验证写为计划要求；已有证据、静态推演和本次实测分开。缺关键复核则标「已修订待核实」，不能标关闭。
+4. 按处置合同在报告追加或更新独立处置节，保留原结论，写明修后基线、逐项状态、验证结果、当前就绪判断及未完项；这是本次修订复核，不冒称重跑了完整独立评审。
+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。
+```

package/skills/apply-doc-review/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "落实文档评审"
+  short_description: "核实 PRD 或开发计划评审意见，修订原文、复核关联内容并记录逐条处置结果"
+  default_prompt: "使用 $apply-doc-review，根据指定的 review-prd 或 review-dev-plan 评审报告修订对应 PRD 或开发计划，核实并落实合理意见，在报告记录处置与复核结果，汇报修改、验证和剩余待决项。"

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

@@ -0,0 +1,57 @@
+# 文档评审处置合同
+
+## 写入位置与历史
+
+- 默认就地修订用户指定原文，在源评审报告追加或更新「修订处置与复核」节。调用本技能已经授权这些写入，不再询问是否保存；明确只核实、仅聊天或另存时以用户要求为准。
+- 原报告的问题、证据、评审基线和原结论保持不变；当前处置与修后判断独立成节，标明日期和修后版本。原文只保留修订后的产品/设计结论及必要决策理由，不混入 F-ID、采纳经过和评审流水。
+- 源报告只读或用户要求保留文件不变时，另存同目录 `<报告文件名去扩展名>.applied.md`，在处置文档中链接源报告和修订目标；远程来源没有本地目录时遵循仓库惯例，无惯例则用 `docs/reviews/<主题>.applied.md`。重名且未获更新授权时加日期及序号，不覆盖无关文件。
+- 多份报告对应同一原文时合并修订，但每份报告均能追踪其问题处置；同一 F-ID 不能跨报告混用。多份原文的版本与结论分别记录。
+- 重复运行先读已有处置，以报告原始版本/问题 ID 匹配更新，不重复应用修改。新报告改变主张时标明新来源；本技能追加的处置内容改变报告 hash 不应把旧 finding 变成新问题。
+
+## 逐条状态
+
+| 状态 | 使用条件 |
+| --- | --- |
+| 已修订并复核 | 当前问题成立，最小修订已落盘，文档层面的复核条件通过；不代表未来实现验收通过 |
+| 已修订待核实 | 已改文档，但事实、关联一致性或必要检查仍缺证；说明缺什么及下一步 |
+| 已解决无需修改 | 当前原文已解决，有具体段落与证据，不冒领成此次修订 |
+| 不采纳 | 误报、不适用、纯偏好或与明确要求冲突，有反证与理由；缺陷仍成立时不能仅因建议不合理就关闭 |
+| 待核实 / 待决策 | 缺事实或用户选择，说明受影响范围、所需证据/问题及可继续部分 |
+| 待修订 / 阻塞 | 意见成立但尚未落实，说明依赖、已做部分和解除条件 |
+| 未处理（用户限定范围） | 用户明确排除的条目，不计入本次关闭数量 |
+
+产品增强提案未获采纳授权时说明「提案未纳入」，不当成缺陷修复完成。用户主动延期或拒绝解决仍成立的问题时保留问题事实、决定来源和剩余影响，不伪装成误报。
+
+## 处置节最小结构
+
+```markdown
+## 修订处置与复核
+
+- 来源：<报告原始版本/hash；原问题 ID 保持不变>
+- 目标：<文档链接；修前/修后版本或内容 hash>
+- 复核日期与代码基线：<日期；相关仓库 commit/dirty；无代码调查则说明>
+- 本次范围：<全部或指定条目；与原评审范围的差异>
+
+| 问题/报告章节 | 核实结论与依据 | 最终处置 | 修改位置与关联同步 | 复核结果/后续 |
+| --- | --- | --- | --- | --- |
+| F-01 | <事实/目标区分；读过的证据或反证> | <状态> | <目标章节/ID，保留与原问题的映射> | <通过的文档判据或缺证/待决> |
+
+### 决策与未完项
+
+<明确用户选择、来源和日期、影响范围/验收；未决项的选项、后果与解除条件。>
+
+### 修订后结论与验证
+
+<已修订/无需修改/未采纳/未完数量；本次覆盖内的就绪判断与理由。>
+<实际运行的文档检查、结果；未运行或不适用的检查及原因。>
+<受影响但未授权修改的关联文档、另需实施/验收的事项。>
+```
+
+采用现有等价结构时不重复建表；同根因可合并行，但保留每个来源 ID。原报告没有 ID 的意见用稳定章节定位，不改写原编号。
+
+## 就绪与完成边界
+
+- PRD 关键范围、产品语义或验收未定时不能称可交接；文案修完不代表这些问题消失。无需新架构才能确定产品目标时，不强求 PRD 已有技术设计。
+- 开发计划的重大范围、安全、数据、外部契约或关键 NFR 未决时是 `Blocked`；仅等非阻塞评审才用 `Proposed`；关键前置均明确才可 `Ready`。这些不是实施进度或测试状态。
+- 处置记录中的「复核通过」只覆盖此次检查的断言，不改写源报告的历史总体结论，也不假称完整独立评审通过。
+- 原文写入、报告回写、必要复核分别核验。任一步未完成都要明确，聊天摘要不能替代应落盘的产物；交付前回读实际文件，链接必须指向存在的文档。

package/skills/archify/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 tt-a1i (Archify)
+Copyright (c) 2025 Cocoon AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.