跳转至

English

Recipe：存量仓只读采用盘点

1. 场景与非场景

适用：需要对一个已存在的存量仓判断是否可采用 Foundation，并拿到精确写集、冲突与旧实现退出清单，且不改动任何字节。

不适用：需要自动改写存量仓（禁止写文件、禁止自动迁移）；需要发布到远端（归 release-skill）。

2. 架构选择及能力 ID

首选能力：foundation.kit.adopt-plan（严格只读盘点与完成判定）。它只输出，不写文件、不运行 git 写命令。

3. 前置条件与信任边界

  • 目标仓存在且可被只读访问。
  • 信任边界：adopt-plan 对输入仓字节零变化；旧实现删除由调用方负责，工具绝不代为删除。

4. 最小命令

npm install --save-dev skill-family-engineering-kit@0.3.0
npm exec -- skill-family-kit adopt-plan --root <repo>

5. 预期输出与证据

输出包含现状（target）、目标 Profile 与追溯（project/traceability）、只读 Git 前置状态（git）、精确写集（writeSet）、冲突（conflicts）、风险（risks）、迁移状态机（migration）与验收命令序列（verificationPlan）。证据来自 packages/skill-family-engineering-kit/test/adopt-plan.test.mjs 与 test/migration.test.mjs。

6. 安全/失败负例

dirty 仓运行 adopt-plan 前后，输入仓字节必须完全一致（哈希走查可证）；工具不写临时文件、不触碰远端。若迁移清单缺 exceptions 必填字段，计划直接失败（完成判定 false），工具不续期。

7. 可复制验证命令

# 正例：对公开 fixture 存量仓做只读盘点
npm exec -- skill-family-kit adopt-plan --root fixtures/m0-consumer

# 只读诊断，不修复
npm exec -- skill-family-kit check --root fixtures/m0-consumer

8. 调用方继续拥有的业务逻辑

  • 旧实现是否退出、何时删除（工具只评估存在性并列出退出清单）。
  • business-logic-to-keep 与 legacy-removal-recovery 恒为 INCOMPLETE，必须由人类负责人给出。

9. 升级与回滚注意事项

  • adopt-plan 只读，无写风险，无需回滚。
  • 真正落盘由 scaffold/projection 执行，回滚以 adoptionProof 与 foundationPlanDigest 双摘要绑定为准；未声明 expect.sha256 前置状态的覆盖动作在 projection 阶段即拒绝。
  • 若采用 Quickstart Profile candidate，三个包按同一 profile 精确锁定：v2 使用 0.3.0，v1 继续使用 0.2.1，不混装。