@namewta/speculo 0.7.0 → 0.7.2

package/template/skills/migrate-runtime-state/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: migrate-runtime-state
+description: 迁移 Speculo pending 运行时状态；当 migrate-runtime-state command 需要盘点 back、修复配置或原子恢复 workflow/command 持久项时使用。
+---
+
+# Migrate Runtime State
+
+以**对账**为主导词：当前模板合同是目标，`back/` 是不可变来源，active runtime 是可能已产生新内容的目标。每个源文件必须得到唯一处置，不按目录整包盲目覆盖。
+
+## 输入
+
+调用方必须提供：
+
+- 已解析的 project、Speculo、state 和 backup roots；
+- pending marker 与 backup manifest；
+- 允许写入的配置和 runtime state 边界；
+- `dry-run | confirmed` 模式和 command 报告 owner；
+- 用户对冲突、替换和删除的逐项决定。
+
+缺少任一输入时返回 blocked，不自行推断 command 报告目录或扩大写入范围。
+
+## 过程
+
+### 1. 验证迁移现场
+
+运行：
+
+```bash
+node scripts/migrate-runtime-state.mjs inspect --project-root <project-root>
+```
+
+核对输出中的 pending marker、源/目标版本、backup manifest 和每个文件 hash。读取所有已安装 workflow 的 INDEX、当前 schema、状态种子与 command state 合同。若 hash 不一致、存在符号链接、pending marker 缺失或另一个 staging/rollback 目录仍存在，停止。
+
+**完成标准**：来源未变、roots 唯一、所有动态路径有 owner，backup 中每个条目均已枚举。
+
+### 2. 建立逐项对账
+
+读取 [`references/migration-contract.md`](references/migration-contract.md)，为 manifest 中每个条目选择唯一动作。配置按字段合并；状态索引必须与真实 change/archive 目录重建一致；永久知识、sidecar、command cursor 和报告按 owner 恢复；未知项保持 `unresolved`，不得静默删除。
+
+同时读取 active 目标。源和目标都发生变化时比较内容与 owner，不以 backup 或新骨架的时间先后自动决定覆盖。
+
+**完成标准**：每个 backup 条目和每个将被覆盖/删除的 active 条目都有动作、理由、目标、风险、验证和用户决定；`unresolved` 为零才可执行。
+
+### 3. 生成确定性计划
+
+生成 schema v1 JSON plan。`backup_manifest_sha256` 锁定 inspect 现场；`source_decisions` 必须逐项覆盖 manifest 中的每个文件且不得包含 `unresolved`；`actions` 仅使用脚本支持的动作：
+
+```json
+{
+  "schema_version": 1,
+  "backup_manifest_sha256": "<inspect 返回的 sha256>",
+  "source_decisions": [
+    {"path": "config.json", "disposition": "merge-json", "target": "config.json"},
+    {"path": "state/workspace.json", "disposition": "keep-current", "target": ".speculo/workspace.json"}
+  ],
+  "actions": [
+    {"kind": "copy", "from": "state/specdev/context", "to": ".speculo/specdev/context", "expected_target": "absent"},
+    {"kind": "replace-json", "to": ".speculo/specdev/status.json", "value": {}, "expected_target": "file:<sha256>"},
+    {"kind": "keep-current", "to": "config.json", "expected_target": "file:<sha256>"}
+  ]
+}
+```
+
+`from` 必须相对 backup root；`to` 只能是 `config.json` 或 `.speculo/` 内非受保护路径。每个 action 都使用 `fingerprint` 输出锁定 `expected_target`；目标相互重叠时拆成不重叠动作。Plan 写入调用方声明的临时位置，报告保存等价 Markdown 表格；正式 state 不保存第二份 plan。
+
+**完成标准**：计划可由脚本解析，路径均在授权边界内，受管理静态资产和 `back/` 不会成为目标。
+
+### 4. Dry-run 门
+
+默认在计划报告完成后停止。向调用方返回文件总数、各动作数量、冲突、阻塞、目标漂移 hash 和验证清单。未取得对当前完整计划的明确确认时，不调用 apply。
+
+**完成标准**：除 command 报告外没有持久写入；用户看到全部覆盖、替换和删除动作。
+
+### 5. 原子执行
+
+仅在 `confirmed` 模式运行：
+
+```bash
+node scripts/migrate-runtime-state.mjs apply \
+  --project-root <project-root> \
+  --plan <temporary-plan.json> \
+  --confirmed
+```
+
+脚本重验来源和目标后，在项目根的临时 staging 中构建完整 Speculo 安装，执行计划、验证 JSON 与核心状态合同、清除 staged pending marker，再通过 rename 替换 active `speculo/`。失败时恢复原 active 安装；backup 始终保留。
+
+**完成标准**：脚本退出 0，active 目标已重读，pending marker 不存在，backup manifest hash 未变，无 staging/rollback 残留。
+
+### 6. 返回审计结果
+
+返回调用方：执行模式、源/目标版本、动作结果、验证、rollback 状态、backup 路径、未迁移项和残余风险。调用方把结果追加到原 command 报告。
+
+**完成标准**：报告能够从 backup、plan 摘要和 active 结果重建迁移；失败不伪装成部分成功。

package/template/skills/migrate-runtime-state/references/migration-contract.md

@@ -0,0 +1,58 @@
+# Runtime migration contract
+
+## 权威顺序
+
+1. 当前模板中的 workspace、workflow INDEX、schema 和 `_state` 种子决定目标结构。
+2. `back/` 保存刷新前事实，始终只读。
+3. active runtime 中 pending 后产生的合法用户内容不能被静默覆盖。
+4. 用户对真实冲突的当前明确决定优先，但不能授权路径逃逸、损坏 backup 或伪造 schema 成功。
+
+## 动作选择
+
+| 情况 | 动作 |
+|---|---|
+| backup 有、active 无、owner 仍存在 | `copy` |
+| JSON schema 相同且只缺新默认字段 | `replace-json`，值为递归合并结果，旧用户值优先 |
+| 状态 schema 可从目录事实确定性重建 | `replace-json`，报告逐字段来源 |
+| active 是当前模板管理的 workspace/install metadata | `keep-current` |
+| backup 与 active 内容相同 | `keep-current` |
+| active 在 pending 后有新内容 | 比较后由用户选择 `keep-current`、`copy` 或 `replace-json` |
+| owner 已删除但内容有历史价值 | 保持 `unresolved`，由用户选择归档目标；不得放入虚构 namespace |
+| 文件损坏且无法从其他权威事实重建 | 保持 `unresolved` |
+
+## SpecDev 对账
+
+- 全局状态只恢复当前 schema 允许的字段。
+- `active` 从仍位于 `changes/` 且 change 状态为 active/blocked/completed 的真实目录核对；不得创建虚假 change。
+- `archived` 从 `archive/YYYY-MM/<change>/` 核对，active/archived 不得重叠。
+- `config.json` 保留语言、Git、执行、验证与规划偏好，并补入当前 schema 的必需默认值。
+- `.config/`、`adr/`、`context/`、`research/`、`changes/`、`archive/` 和声明的 sidecar 都是持久项。
+- Command Markdown 报告和具有当前 owner 的 `state.json` 均迁移；未知 command state 保持 unresolved。
+
+## 路径边界
+
+允许目标：
+
+- `config.json`
+- `.speculo/commands/**`
+- `.speculo/<installed-workflow>/**`
+
+受保护目标：
+
+- `.speculo/back/**`
+- `.speculo/workspace.json`
+- `.speculo/install.json`
+- `.speculo/migration.json`（只由脚本在验证成功后清除）
+- `commands/**`、`skills/**`、`workflows/**` 静态资产
+
+所有路径必须使用 POSIX 相对路径，不得包含空段、`.`、`..`、绝对路径或符号链接逃逸。
+
+## 验证
+
+- backup manifest 的每个 file hash、size 和 symlink 条目与现场一致；存在 symlink 时阻塞。
+- plan 的 `backup_manifest_sha256` 与现场一致，`source_decisions` 恰好覆盖 manifest 全部条目，且每个 action 的 `expected_target` 与 active 现场一致。
+- 所有迁移后 JSON 可解析。
+- workspace、install manifest、项目配置和已安装 workflow 全局状态满足当前版本。
+- SpecDev active/archive 索引与目录一致；person 状态满足 schema v1。
+- pending marker 只在全部验证通过后从 staged 安装删除。
+- 执行后 backup manifest 与内容 hash 不变。