@namewta/speculo 0.8.2 → 0.8.4

package/README.md

@@ -49,7 +49,7 @@ After initialization, the target project gains the following AI agent-callable a
 | `retro` | Retrospective analysis with `gh issue` creation |
 | `status` | Summary of installed workflows, active changes, and anomalies |
 
-### 8 Skills
+### 9 Skills
 
 | Skill | Purpose |
 |---|---|
@@ -59,6 +59,7 @@ After initialization, the target project gains the following AI agent-callable a
 | `optimize-codex-config` | Audit and optimize local Codex configuration, custom Responses providers, permissions, and compaction failures |
 | `source-code-zip` | Create a dependency-free, code-only ZIP for isolated source delivery |
 | `speculo-retro` | Retrospective analysis |
+| `upstream-fork-sync` | Assess fork/upstream deltas from proven integration checkpoints and persist reproducible diff and conflict reports |
 | `engineering-standards-builder` | Interview-driven generator that produces a project-specific TypeScript/JS/React/Node standards skill |
 | `writing-great-skills` | Authoring guidance for agent skills |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@namewta/speculo",
-  "version": "0.8.2",
+  "version": "0.8.4",
   "description": "Workflow-packaged specification-driven development assets with state-safe refresh tooling.",
   "type": "module",
   "bin": {

package/template/.speculo/README.md

@@ -16,16 +16,18 @@
 
 1. 读取 `workspace.json`，以当前打开项目为 `project_root` 解析公共 roots。
 2. 从 `../workflows/<workflow>/INDEX.md` 进入 workflow，再通过 `<Path>` 指针进入具体 work 入口文件。
-3. 读取 `<workflow>/status.json`，再读取 `changes/<change>/.status.json` 和当前 work 产物。
-4. 历史 change 只从 `<workflow>/archive/YYYY-MM/<change>/` 读取。
-5. Command 报告位于 `commands/<command>/*.md`，command state 位于 `commands/<command>/state.json`。
-6. 首次 docs-sync 确认后读取 `<workflow>/docs-sync.json`；它分列该 workflow 的项目文档和私有 state 更新范围。
+3. 读取 `<Path>{roots.state}/{workflow}/status.json</Path>`，再读取 `<Path>{roots.state}/{workflow}/changes/{change}/.status.json</Path>` 和当前 work 产物。
+4. 历史 change 只从 `<Path>{roots.state}/{workflow}/archive/{YYYY-MM}/{change}/</Path>` 读取。
+5. Command 报告位于 `<Path>{roots.state}/commands/{command}/*.md</Path>`，command state 位于 `<Path>{roots.state}/commands/{command}/state.json</Path>`。
+6. 独立 Skill 的运行记录位于 `<Path>{roots.state}/skills/{skill}/</Path>`，根级 `state.json` 仅在该 Skill 声明持久 checkpoint 时读取。
+7. 首次 docs-sync 确认后读取 `<Path>{roots.state}/{workflow}/docs-sync.json</Path>`；它分列该 workflow 的项目文档和私有 state 更新范围。
 
 ## 写入边界
 
-- 每个 workflow 只写自己的 `status.json/changes/archive` 和已声明 namespace。
+- 每个 workflow 只写 `<Path>{roots.state}/{workflow}/</Path>` 下自己的 `status.json/changes/archive` 和已声明 namespace。
 - `docs-sync.json` 是 docs-sync command 拥有的延迟 sidecar，不进入 `_state`，也不授予越过 workflow 确认规则的权限。
 - `.config` 不是标准目录；只有 workflow 声明时才可使用。
-- Command 报告命名为 `<YYYY-MM-DD>-<scope>-<topic>[-NN].md`，禁止覆盖。
+- Command 只写 `<Path>{roots.state}/commands/{command}/</Path>`，报告命名为 `<YYYY-MM-DD>-<scope>-<topic>[-NN].md`，禁止覆盖。
+- 独立 Skill 只写 `<Path>{roots.state}/skills/{skill}/</Path>`；一次运行目录命名为 `<YYYY-MM-DD>-<kebab-topic>[-NN]`，禁止覆盖。由 command/work 调用时改用调用方提供的 owner 路径。
 - `back/` 由 `speculo init` 单一写入；workflow 和 commands 不得修改。
 - `install.json`、`managed.json`、`baselines/` 与 refresh contract 由 CLI 拥有，workflow 不得创建、修改或删除。

package/template/canonical/canonical-specdev-engineering-cognitive-mentor.md

@@ -1432,7 +1432,7 @@ SpecDev 通过分层工件避免同一决策被多个模型反复重做。每个
 | Evidence | `specdev/changes/{change}/evidence/T-NN.md` | 实际修改、命令、结果、验收映射、偏差、风险和提交引用 | 新的产品或架构决策 |
 | 代码审查 | `specdev/changes/{change}/reviews/CR-###.md` | 固定点、标准轴和规范轴 finding | 实施修复或合并两轴排名 |
 | 原型记录 | `specdev/changes/{change}/prototypes/{prototype-id}/record.md` | 一个问题、分支、资产、答案、promotion 和清理 | 生产实现或多个问题的计划 |
-| 五岁图解 | `specdev/changes/{change}/eli5.html` | 面向五岁、零背景读者的大图少字解释 | 产品决定、架构决定或实现授权 |
+| 零基础新生图解 | `specdev/changes/{change}/eli_index.md` 与 `specdev/changes/{change}/<number>_<topic>.md` | 面向刚上大一、没有专业背景读者的 Markdown 与 ASCII 图解；索引按序号持续追加 | 产品决定、架构决定或实现授权 |
 | Stakeholder 问卷 | `specdev/changes/{change}/questionnaires/{slug}.md` | 第三方原始回答和恢复条件 | 未经转录确认的产品/架构决定 |
 | Wayfinder 地图 | `specdev/changes/{change}/wayfinder-map.md` | 目的地、说明、已关闭决策索引、战争迷雾和范围之外 | 开放 Ticket 正文或答案详情 |
 | Wayfinder Ticket | `specdev/changes/{change}/investigation/{investigation-id}.md` | 一个可精确陈述的问题、类型、阻塞和关闭状态 | 解决方案评论或交付目标 |

package/template/canonical/canonical-specdev-goal-plan.md

@@ -559,7 +559,7 @@ SpecDev 通过分层工件避免同一决策被多个模型反复重做。每个
 | Evidence | `specdev/changes/{change}/evidence/T-NN.md` | 实际修改、命令、结果、验收映射、偏差、风险和提交引用 | 新的产品或架构决策 |
 | 代码审查 | `specdev/changes/{change}/reviews/CR-###.md` | 固定点、标准轴和规范轴 finding | 实施修复或合并两轴排名 |
 | 原型记录 | `specdev/changes/{change}/prototypes/{prototype-id}/record.md` | 一个问题、分支、资产、答案、promotion 和清理 | 生产实现或多个问题的计划 |
-| 五岁图解 | `specdev/changes/{change}/eli5.html` | 面向五岁、零背景读者的大图少字解释 | 产品决定、架构决定或实现授权 |
+| 零基础新生图解 | `specdev/changes/{change}/eli_index.md` 与 `specdev/changes/{change}/<number>_<topic>.md` | 面向刚上大一、没有专业背景读者的 Markdown 与 ASCII 图解；索引按序号持续追加 | 产品决定、架构决定或实现授权 |
 | Stakeholder 问卷 | `specdev/changes/{change}/questionnaires/{slug}.md` | 第三方原始回答和恢复条件 | 未经转录确认的产品/架构决定 |
 | Wayfinder 地图 | `specdev/changes/{change}/wayfinder-map.md` | 目的地、说明、已关闭决策索引、战争迷雾和范围之外 | 开放 Ticket 正文或答案详情 |
 | Wayfinder Ticket | `specdev/changes/{change}/investigation/{investigation-id}.md` | 一个可精确陈述的问题、类型、阻塞和关闭状态 | 解决方案评论或交付目标 |

package/template/canonical/canonical-specdev-grill-with-docs.md

@@ -377,7 +377,7 @@ SpecDev 通过分层工件避免同一决策被多个模型反复重做。每个
 | Evidence | `specdev/changes/{change}/evidence/T-NN.md` | 实际修改、命令、结果、验收映射、偏差、风险和提交引用 | 新的产品或架构决策 |
 | 代码审查 | `specdev/changes/{change}/reviews/CR-###.md` | 固定点、标准轴和规范轴 finding | 实施修复或合并两轴排名 |
 | 原型记录 | `specdev/changes/{change}/prototypes/{prototype-id}/record.md` | 一个问题、分支、资产、答案、promotion 和清理 | 生产实现或多个问题的计划 |
-| 五岁图解 | `specdev/changes/{change}/eli5.html` | 面向五岁、零背景读者的大图少字解释 | 产品决定、架构决定或实现授权 |
+| 零基础新生图解 | `specdev/changes/{change}/eli_index.md` 与 `specdev/changes/{change}/<number>_<topic>.md` | 面向刚上大一、没有专业背景读者的 Markdown 与 ASCII 图解；索引按序号持续追加 | 产品决定、架构决定或实现授权 |
 | Stakeholder 问卷 | `specdev/changes/{change}/questionnaires/{slug}.md` | 第三方原始回答和恢复条件 | 未经转录确认的产品/架构决定 |
 | Wayfinder 地图 | `specdev/changes/{change}/wayfinder-map.md` | 目的地、说明、已关闭决策索引、战争迷雾和范围之外 | 开放 Ticket 正文或答案详情 |
 | Wayfinder Ticket | `specdev/changes/{change}/investigation/{investigation-id}.md` | 一个可精确陈述的问题、类型、阻塞和关闭状态 | 解决方案评论或交付目标 |

package/template/canonical/canonical-specdev-spec.md

@@ -368,7 +368,7 @@ SpecDev 通过分层工件避免同一决策被多个模型反复重做。每个
 | Evidence | `specdev/changes/{change}/evidence/T-NN.md` | 实际修改、命令、结果、验收映射、偏差、风险和提交引用 | 新的产品或架构决策 |
 | 代码审查 | `specdev/changes/{change}/reviews/CR-###.md` | 固定点、标准轴和规范轴 finding | 实施修复或合并两轴排名 |
 | 原型记录 | `specdev/changes/{change}/prototypes/{prototype-id}/record.md` | 一个问题、分支、资产、答案、promotion 和清理 | 生产实现或多个问题的计划 |
-| 五岁图解 | `specdev/changes/{change}/eli5.html` | 面向五岁、零背景读者的大图少字解释 | 产品决定、架构决定或实现授权 |
+| 零基础新生图解 | `specdev/changes/{change}/eli_index.md` 与 `specdev/changes/{change}/<number>_<topic>.md` | 面向刚上大一、没有专业背景读者的 Markdown 与 ASCII 图解；索引按序号持续追加 | 产品决定、架构决定或实现授权 |
 | Stakeholder 问卷 | `specdev/changes/{change}/questionnaires/{slug}.md` | 第三方原始回答和恢复条件 | 未经转录确认的产品/架构决定 |
 | Wayfinder 地图 | `specdev/changes/{change}/wayfinder-map.md` | 目的地、说明、已关闭决策索引、战争迷雾和范围之外 | 开放 Ticket 正文或答案详情 |
 | Wayfinder Ticket | `specdev/changes/{change}/investigation/{investigation-id}.md` | 一个可精确陈述的问题、类型、阻塞和关闭状态 | 解决方案评论或交付目标 |

package/template/canonical/canonical-specdev-tickets.md

@@ -655,7 +655,7 @@ SpecDev 通过分层工件避免同一决策被多个模型反复重做。每个
 | Evidence | `specdev/changes/{change}/evidence/T-NN.md` | 实际修改、命令、结果、验收映射、偏差、风险和提交引用 | 新的产品或架构决策 |
 | 代码审查 | `specdev/changes/{change}/reviews/CR-###.md` | 固定点、标准轴和规范轴 finding | 实施修复或合并两轴排名 |
 | 原型记录 | `specdev/changes/{change}/prototypes/{prototype-id}/record.md` | 一个问题、分支、资产、答案、promotion 和清理 | 生产实现或多个问题的计划 |
-| 五岁图解 | `specdev/changes/{change}/eli5.html` | 面向五岁、零背景读者的大图少字解释 | 产品决定、架构决定或实现授权 |
+| 零基础新生图解 | `specdev/changes/{change}/eli_index.md` 与 `specdev/changes/{change}/<number>_<topic>.md` | 面向刚上大一、没有专业背景读者的 Markdown 与 ASCII 图解；索引按序号持续追加 | 产品决定、架构决定或实现授权 |
 | Stakeholder 问卷 | `specdev/changes/{change}/questionnaires/{slug}.md` | 第三方原始回答和恢复条件 | 未经转录确认的产品/架构决定 |
 | Wayfinder 地图 | `specdev/changes/{change}/wayfinder-map.md` | 目的地、说明、已关闭决策索引、战争迷雾和范围之外 | 开放 Ticket 正文或答案详情 |
 | Wayfinder Ticket | `specdev/changes/{change}/investigation/{investigation-id}.md` | 一个可精确陈述的问题、类型、阻塞和关闭状态 | 解决方案评论或交付目标 |

package/template/commands/archive-and-consolidate.md

@@ -12,7 +12,7 @@ keywords: [archive, consolidate, knowledge, cleanup, adr, 归档, 知识合并,
 
 ## 报告
 
-统一写入：`speculo/.speculo/commands/archive-and-consolidate/<YYYY-MM-DD>-<scope>-<topic>[-NN].md`（`<scope>` 为目标 workflow 名，`<topic>` 为 change 名或 `batch`）。
+统一写入：`<Path>{roots.state}/commands/archive-and-consolidate/{date}-{scope}-{topic}[-NN].md</Path>`（`<scope>` 为目标 workflow 名，`<topic>` 为 change 名或 `batch`）。
 
 报告必须记录：`mode`（dry-run 或 executed）、选中的 workflow、归档计划、合并计划、清理候选、用户确认状态和最终结果。
 
@@ -22,9 +22,9 @@ keywords: [archive, consolidate, knowledge, cleanup, adr, 归档, 知识合并,
 
 归档并合并单个已完成 change 的知识。
 
-1. 读取 `../skills/archive-and-consolidate/SKILL.md`，执行路径解析（Step 0），解析 `speculo/config.json`（不存在时静默降级）。
+1. 读取 `<Path>{roots.skills}/archive-and-consolidate/SKILL.md</Path>`，执行路径解析（Step 0），解析 `<Path>{roots.config}</Path>`（不存在时静默降级）。
 2. 选择一个 `change_status: completed` 的 change。
-3. 目标为 SpecDev 时先读取其 `common/rules/change-completion.md` 与 `triage.md`：完成门必须通过，`external_action` 必须为 `closed | waived | not-applicable`；pending/failed 返回 Triage，不生成可执行归档计划。
+3. 目标为 SpecDev 时先读取 `<Path>{roots.workflows}/specdev/common/rules/change-completion.md</Path>` 与当前 change 的 `<Path>{roots.state}/specdev/changes/{change}/triage.md</Path>`：完成门必须通过，`external_action` 必须为 `closed | waived | not-applicable`；pending/failed 返回 Triage，不生成可执行归档计划。
 4. 执行 Step 1-5：扫描 stores、扫描 change、生成归档计划、生成合并计划、生成清理候选。
 5. 默认 dry-run：将完整计划写入报告文件，展示摘要并等待用户显式确认。
 6. 确认后以 mode=`confirmed` 执行 Step 7-8：归档移动、合并写入、清理、重读验证。
@@ -34,7 +34,7 @@ keywords: [archive, consolidate, knowledge, cleanup, adr, 归档, 知识合并,
 
 批量归档并合并所有已完成 change 的知识。
 
-1. 读取 `../skills/archive-and-consolidate/SKILL.md`，执行路径解析。
+1. 读取 `<Path>{roots.skills}/archive-and-consolidate/SKILL.md</Path>`，执行路径解析。
 2. 扫描目标 workflow 下所有 `change_status: completed` 的 change。不接受 active 或 broken 状态。
 3. SpecDev 候选逐个通过 change completion 与 external reconcile 门；任一 pending/failed 阻塞整批。
 4. 执行 Step 1-5：扫描 stores、逐 change 扫描、批量预检、合并计划、清理候选。

package/template/commands/docs-sync.md

@@ -10,15 +10,15 @@ keywords: [docs-sync, readme, changelog, agents, documentation]
 
 ## 产物
 
-- 报告：`speculo/.speculo/commands/docs-sync/<YYYY-MM-DD>-<scope>-<topic>[-NN].md`
-- 全局 state：`speculo/.speculo/commands/docs-sync/state.json`
-- Workflow 范围：`speculo/.speculo/<workflow>/docs-sync.json`
+- 报告：`<Path>{roots.state}/commands/docs-sync/{date}-{scope}-{topic}[-NN].md</Path>`
+- 全局 state：`<Path>{roots.state}/commands/docs-sync/state.json</Path>`
+- Workflow 范围：`<Path>{roots.state}/{workflow}/docs-sync.json</Path>`
 
 调用本命令即授权它在校验通过后创建本地 checkpoint 与文档同步 commit；不授权 push、tag、stash、历史改写或丢弃文件。
 
 ## 执行
 
-1. 读取 `../skills/docs-sync/SKILL.md`，解析 `speculo/config.json` 与 `speculo/.speculo/workspace.json`（不存在时以默认值静默降级），获取全部已安装 workflow/state 根。
+1. 读取 `<Path>{roots.skills}/docs-sync/SKILL.md</Path>`，解析 `<Path>{roots.config}</Path>` 与 `<Path>{roots.state}/workspace.json</Path>`（不存在时以默认值静默降级），获取全部已安装 workflow/state 根。
 2. 将 runtime context、报告路径、全局 state 路径、Git 副作用责任和 `handbook_mode` 传给 skill。`handbook_mode` 默认为 `incremental`；用户明确要求、手册缺失或 manifest 拓扑变化时使用 `rebuild`。
 3. 整文件/目录删除和受保护知识仍逐次确认；skill 返回原子写入内容后，由本命令显式暂存并创建同步或 no-op commit。
 4. 重新读取 Git、state、报告与 sidecar；只有工作区干净、节点可复现且所有文件已提交时完成。

package/template/commands/git-repository-audit.md

@@ -24,13 +24,13 @@ keywords: [git-audit, git-inventory, repository, commit, merge, contribution,
 唯一持久化产物：
 
 ```text
-speculo/.speculo/commands/git-repository-audit/<YYYY-MM-DD>-<scope>-<topic>[-NN].md
+<Path>{roots.state}/commands/git-repository-audit/{date}-{scope}-{topic}[-NN].md</Path>
 ```
 
-实际路径必须通过 `speculo/.speculo/workspace.json` 的 `roots.state` 解析：
+实际路径必须通过 `<Path>{roots.state}/workspace.json</Path>` 的 `roots.state` 解析：
 
 ```text
-{roots.state}/commands/git-repository-audit/<YYYY-MM-DD>-<scope>-<topic>[-NN].md
+<Path>{roots.state}/commands/git-repository-audit/{date}-{scope}-{topic}[-NN].md</Path>
 ```
 
 规则：
@@ -105,7 +105,7 @@ paths:
   include: []
   exclude:
     - ".git/**"
-    - "speculo/.speculo/**"
+    - "<Path>{roots.state}/**</Path>"
     - ".venv/**"
     - "node_modules/**"
     - "vendor/**"
@@ -161,13 +161,13 @@ options:
 
 ### 1. 解析 Speculo 工作区
 
-1. 从当前目录向上寻找 `speculo/.speculo/workspace.json`。
+1. 从当前目录向上寻找 `<Path>{roots.state}/workspace.json</Path>`。
 2. 第一个命中的目录为 `project_root`；多个候选或用户目录不一致时停止消歧。
 3. 验证 `workspace.json`：
    - 非空且是有效 JSON；
    - `path_base` 为 `project-root`；
    - roots 是 POSIX 项目相对路径。
-4. 读取 `speculo/config.json`。
+4. 读取 `<Path>{roots.config}</Path>`。
 5. 任一初始化文件缺失、为空或不可解析时，停止并提示运行：
 
 ```bash
@@ -208,7 +208,7 @@ uv run --no-project python -V
 
 ```text
 .git
-speculo/.speculo
+<Path>{roots.state}</Path>
 .venv
 node_modules
 vendor

package/template/commands/handoff.md

@@ -15,7 +15,7 @@ disable-model-invocation: true
 报告文件必须写入以下规范路径：
 
 ```
-speculo/.speculo/commands/handoff/<YYYY-MM-DD>-<scope>-<topic>[-NN].md
+<Path>{roots.state}/commands/handoff/{date}-{scope}-{topic}[-NN].md</Path>
 ```
 
 - **<YYYY-MM-DD>** — 使用当前日期。
@@ -43,7 +43,7 @@ speculo/.speculo/commands/handoff/<YYYY-MM-DD>-<scope>-<topic>[-NN].md
 
 - ✅ `src/modules/auth/`
 - ✅ `scripts/migrate/2024-add-index.sql`
-- ✅ `speculo/.speculo/specdev/changes/<YYYY-MM-DD>-<topic>/spec.md`
+- ✅ `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`
 - ❌ `../../specdev/changes/...` — 相对于 handoff 文件，脱离目录后不可定位
 - ❌ `auth` — 裸名，无法判断是目录/文件/子模块
 

package/template/commands/retro.md

@@ -12,7 +12,7 @@ keywords: [retro, 复盘, 痛点, feedback, issue, 优化, 反馈]
 
 ## 归档路径模式
 
-报告文件：`speculo/.speculo/commands/retro/<YYYY-MM-DD>-<scope>-<topic>[-NN].md`
+报告文件：`<Path>{roots.state}/commands/retro/{date}-{scope}-{topic}[-NN].md</Path>`
 
 - `<YYYY-MM-DD>` 使用当前日期。
 - `<topic>` 从复盘范围或用户主题提取，使用小写 kebab-case；无法判断时使用 `speculo`。
@@ -20,14 +20,14 @@ keywords: [retro, 复盘, 痛点, feedback, issue, 优化, 反馈]
 
 ## 调用的 skills
 
-- `../skills/speculo-retro/SKILL.md` — 复盘 Speculo 使用痛点、深度分析并产出去重/分级/根因化的 issue-ready 提案时读取。
-- `../skills/github-npm-ops/SKILL.md` — 以 `issue-search` 去重、以 `issue-create` dry-run/confirmed 创建 Issue；该能力不成为任何 workflow 的 tracker。
+- `<Path>{roots.skills}/speculo-retro/SKILL.md</Path>` — 复盘 Speculo 使用痛点、深度分析并产出去重/分级/根因化的 issue-ready 提案时读取。
+- `<Path>{roots.skills}/github-npm-ops/SKILL.md</Path>` — 以 `issue-search` 去重、以 `issue-create` dry-run/confirmed 创建 Issue；该能力不成为任何 workflow 的 tracker。
 
 ## 执行步骤
 
-1. 读取 `../skills/speculo-retro/SKILL.md`，解析 `speculo/config.json` 与 `speculo/.speculo/workspace.json`（不存在时以默认值静默降级），采集对话、command 报告、change 状态以及各 `INDEX.md` 声明的知识 store。
+1. 读取 `<Path>{roots.skills}/speculo-retro/SKILL.md</Path>`，解析 `<Path>{roots.config}</Path>` 与 `<Path>{roots.state}/workspace.json</Path>`（不存在时以默认值静默降级），采集对话、command 报告、change 状态以及各 `INDEX.md` 声明的知识 store。
 2. 用该 skill 产出规范化复盘结论：去重、分级、根因化的 issue-ready 提案清单，附丢弃/合并说明与每条处置建议。
-3. 创建 command 专属目录 `speculo/.speculo/commands/retro/`，把复盘结论写入带 scope 的 Markdown 报告。
+3. 创建 command 专属目录 `<Path>{roots.state}/commands/retro/</Path>`，把复盘结论写入带 scope 的 Markdown 报告。
 4. **去重**：调用 `github-npm-ops` 的 `operation=issue-search`，对每条 `disposition: file-issue` 检索；命中语义重复的默认跳过并记录 `dup_of`，仅当用户明确要求才补提。
 5. **外部写操作边界**：向用户展示将要创建的 issue 清单（标题、类型/优先级标签、正文摘要、目标仓库 `NAMEWTA/Speculo`）与去重结果，等待用户明确确认。没有确认时只输出计划，不调用 `gh`。
 6. 用户确认后，按优先级倒序调用 `github-npm-ops` 的 `operation=issue-create` confirmed 分支。任一条失败时停止后续创建，报告已建/未建清单，不重复创建同一条。
@@ -54,7 +54,7 @@ generated_at: [TODO: ISO-8601]
 [TODO: 本次复盘覆盖的 command / workflow 与时间/会话范围。]
 
 ## 信号来源
-[TODO: 列出采集到的证据出处：对话节点、`speculo/.speculo/...` 产物路径、`.status.json` 字段、LESSONS。]
+[TODO: 列出采集到的证据出处：对话节点、`<Path>{roots.state}/...</Path>` 产物路径、`.status.json` 字段、LESSONS。]
 
 ## 改进提案
 [TODO: 按优先级倒序列出每条提案：标题 / 类型 / 优先级 / 根因 / 建议改动 / 验收标准 / 受影响资产 / 去重结论。]

package/template/commands/status.md

@@ -8,10 +8,10 @@ keywords: [status, 状态, active, blocked]
 
 # Status 命令
 
-1. 读取 `speculo/.speculo/workspace.json`，解析 `speculo/config.json`（不存在时以默认值静默降级），获取全部已安装 workflow/state 根。
-2. 扫描 `speculo/workflows/*/INDEX.md`，得到已安装 workflow ids。
-3. 对每个 id 读取 `speculo/.speculo/<workflow>/status.json`。SpecDev schema v4 直接按 `active` 与 `archived` 分块；对 active 再读取 `changes/<change>/.status.json`，对 archived 按 `archive/YYYY-MM/<change>/.status.json` 定位。
+1. 读取 `<Path>{roots.state}/workspace.json</Path>`，解析 `<Path>{roots.config}</Path>`（不存在时以默认值静默降级），获取全部已安装 workflow/state 根。
+2. 扫描 `<Path>{roots.workflows}/{workflow}/INDEX.md</Path>`，得到已安装 workflow ids。
+3. 对每个 id 读取 `<Path>{roots.state}/{workflow}/status.json</Path>`。SpecDev schema v4 直接按 `active` 与 `archived` 分块；对 active 再读取 `changes/<change>/.status.json`，对 archived 按 `archive/YYYY-MM/<change>/.status.json` 定位。
 4. 报告 active 数量、各 change 的 `current_work`、去重后的 `works_run`、change 业务状态、最近更新时间、调查 claims，以及停滞 change（`.status.json` 超过 14 天未更新）。SpecDev change 存在 `triage.md` 时同时读取 `external_action`，把 `pending-close`、`close-failed` 和可归档状态分开显示；不执行远程动作。
 5. 报告 archived 数量和名称；预期归档目录或归档 `.status.json` 缺失、active/archived 重叠、重复名称、未知 schema 和 malformed 目录均列为异常，不自动修复。
 6. 报告没有 workflow 资产的孤立状态根，以及缺少状态根的已安装 workflow；不自动修复。
-7. 用户要求持久化时写入 `speculo/.speculo/commands/status/<YYYY-MM-DD>-workspace-<topic>[-NN].md`，并在报告中列出本次扫描的 workflow 选择。
+7. 用户要求持久化时写入 `<Path>{roots.state}/commands/status/{date}-workspace-{topic}[-NN].md</Path>`，并在报告中列出本次扫描的 workflow 选择。

package/template/skills/archive-and-consolidate/SKILL.md

@@ -32,7 +32,7 @@ description: >
 
 ### Step 0：路径解析（内建，不依赖外部 skill）
 
-1. 从 CWD 向上查找 `speculo/.speculo/workspace.json`；第一个命中目录为 `project_root`；多候选或冲突时返回 blocked。
+1. 从 CWD 向上查找 `<Path>{roots.state}/workspace.json</Path>`；第一个命中目录为 `project_root`；多候选或冲突时返回 blocked。
 2. 读取 `workspace.json`，校验 `path_base` 为 `project-root`，所有 roots 使用 POSIX 相对路径。
 3. 读取目标 workflow 的 `INDEX.md`，解析运行时根声明：
    - 查找 `## 运行时根` 或类似标题下的 `<Path>{roots.X}/path/</Path>` 标签。
@@ -43,8 +43,8 @@ description: >
    - 识别操作型路径：`status.json`、`changes/`、`archive/`。
    - 识别知识型 store：`adr/`、`context/` 及任何标注为"永久"的目录（其内容在 change 完成后提升至此）。
    - 每个路径解析为完整的项目相对路径。
-5. 派生固定路径：`changes_root = state_root/changes`、`archive_root = state_root/archive`；`commands_root` 从公共 `{roots.state}/commands` 解析，不放进 workflow 私有 state root。
-6. 读取 `speculo/config.json`（若存在）；不存在时静默降级为默认值（`language: "en"`、`confirm_before_external_write: true`）。
+5. 派生固定路径：`changes_root = state_root/changes`、`archive_root = state_root/archive`；`commands_root` 从公共 `<Path>{roots.state}/commands</Path>` 解析，不放进 workflow 私有 state root。
+6. 读取 `<Path>{roots.config}</Path>`（若存在）；不存在时静默降级为默认值（`language: "en"`、`confirm_before_external_write: true`）。
 7. 对每个已解析路径执行真实路径包含检查；符号链接逃逸或不存在的静态引用阻塞。
 8. 读取 `status.json`；扫描 changes 时校验 change 名称格式 `^\d{4}-\d{2}-\d{2}-[a-z0-9]+(-[a-z0-9]+)*$`，无日期前缀的历史 change 标注遗留但不阻塞。
 

package/template/skills/docs-sync/assets/state-template.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 4,
   "command": "docs-sync",
-  "state_path": "speculo/.speculo/commands/docs-sync/state.json",
+  "state_path": "<Path>{roots.state}/commands/docs-sync/state.json</Path>",
   "baseline": {
     "mode": "explicit",
     "sha": null

package/template/skills/docs-sync/assets/workflow-scope-template.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "workflow": "{workflow}",
-  "manifest_path": "speculo/.speculo/{workflow}/docs-sync.json",
+  "manifest_path": "<Path>{roots.state}/{workflow}/docs-sync.json</Path>",
   "project_targets": [],
   "state_targets": [],
   "scope_revision": 1,

package/template/skills/docs-sync/references/git-state-contract.md

@@ -15,13 +15,13 @@
 
 ## State v4
 
-默认路径为 `speculo/.speculo/commands/docs-sync/state.json`：
+默认路径为 `<Path>{roots.state}/commands/docs-sync/state.json</Path>`：
 
 ```json
 {
   "schema_version": 4,
   "command": "docs-sync",
-  "state_path": "speculo/.speculo/commands/docs-sync/state.json",
+  "state_path": "<Path>{roots.state}/commands/docs-sync/state.json</Path>",
   "baseline": { "mode": "explicit", "sha": null },
   "last_range": { "from_sha": null, "to_sha": null },
   "project_targets": [],

package/template/skills/docs-sync/references/workflow-scope-contract.md

@@ -4,8 +4,8 @@ docs-sync 必须遵循每个 workflow 的 `INDEX.md`。`docs-sync.json` 是 comm
 
 ## 发现
 
-1. 从 `speculo/workflows/*/INDEX.md` 发现已安装 workflow。
-2. 每个包必须有匹配的 `speculo/.speculo/<workflow>/` 状态根；包或状态根单边缺失时阻塞，不猜测归属。
+1. 从 `<Path>{roots.workflows}/{workflow}/INDEX.md</Path>` 发现已安装 workflow。
+2. 每个包必须有匹配的 `<Path>{roots.state}/{workflow}/</Path>` 状态根；包或状态根单边缺失时阻塞，不猜测归属。
 3. 读取 `INDEX.md` 中声明的运行时根、持久化约定、固定 archive 和知识 store。
 4. 状态根存在但没有已安装 package 时只报告 orphan，不创建 sidecar。
 
@@ -17,7 +17,7 @@ docs-sync 必须遵循每个 workflow 的 `INDEX.md`。`docs-sync.json` 是 comm
 {
   "schema_version": 1,
   "workflow": "example",
-  "manifest_path": "speculo/.speculo/example/docs-sync.json",
+  "manifest_path": "<Path>{roots.state}/example/docs-sync.json</Path>",
   "project_targets": [],
   "state_targets": [],
   "scope_revision": 1,

package/template/skills/github-npm-ops/references/preflight-checklist.md

@@ -16,7 +16,7 @@
 | 7 | 包管理器 | `pnpm --version` (或 `npm` / `yarn`) | 版本 ≥ 仓库 lockfile 隐含版本 | 安装匹配版本；不要随意切换包管理器 |
 | 8 | release.yml 存在 | `test -f .github/workflows/release.yml` | 文件存在 | 转 `github-npm-ops` skill 的 `references/workflow-yaml-reference.md` 先落该文件 |
 | 9 | release.yml 形态 | 见 [publish-detection.md](publish-detection.md) | 输出 `PUBLISH_TO_NPM=true` 或 `false` | 见 publish-detection 文档的判定矩阵 |
-| 10 | docs-sync state | `test -f speculo/.speculo/commands/docs-sync/state.json && jq . speculo/.speculo/commands/docs-sync/state.json` | schema v4、scope 已确认，baseline 可解析 | 不存在/未确认 → 走 docs-sync command bootstrap；旧 schema 或损坏 → 停止发布并按 docs-sync state contract 修复，`speculo init` 不解析未登记的 command state |
+| 10 | docs-sync state | 对 `<Path>{roots.state}/commands/docs-sync/state.json</Path>` 执行存在性检查与 JSON 解析 | schema v4、scope 已确认，baseline 可解析 | 不存在/未确认 → 走 docs-sync command bootstrap；旧 schema 或损坏 → 停止发布并按 docs-sync state contract 修复，`speculo init` 不解析未登记的 command state |
 | 11 | tag 名称冲突 | `git rev-parse vX.Y.Z 2>/dev/null` | 退出码非 0（tag 不存在） | 同 tag 已存在：先确认是否真的失败需要重发；若是则 `git tag -d` + `git push origin :refs/tags/vX.Y.Z`，否则 bump 到下一版本 |
 
 ## 失败处理总策略

package/template/skills/github-npm-ops/references/release-notes-injection.md

@@ -88,7 +88,7 @@ GitHub Release 的正文(body)**事后可改**(tag 不可改、npm 包不可改
 
 ### 3.1 命令行(推荐)
 
-`notes_file` 只是一次性传给 `gh --notes-file` 的中间文件；若需要保留回填记录或 release notes，由调用方写入 `speculo/.speculo/commands/<command>/<YYYY-MM-DD>-<scope>-<topic>[-NN].md`。
+`notes_file` 只是一次性传给 `gh --notes-file` 的中间文件；若需要保留回填记录或 release notes，由调用方写入 `<Path>{roots.state}/commands/{command}/{date}-{scope}-{topic}[-NN].md</Path>`。
 
 ```bash
 VERSION="0.0.10"

package/template/skills/github-npm-ops/references/release-pipeline.md

@@ -5,7 +5,7 @@
 ## Iron Law
 
 - 禁止提交破坏构建的代码；release 前必须运行仓库声明的 lint / test / build 或等价质量闸。
-- docs-sync 必须由调用方按 `../../../commands/docs-sync.md` 执行；输入起点来自最后修改 state 文件的 commit，终点是运行前清洁后的 HEAD，并写入 `last_range`。
+- docs-sync 必须由调用方按 `<Path>{roots.commands}/docs-sync.md</Path>` 执行；输入起点来自最后修改 state 文件的 commit，终点是运行前清洁后的 HEAD，并写入 `last_range`。
 - tag 必须精确指向 release commit，即包含 `package.json` version bump 与 CHANGELOG 迁移的 commit；禁止指向后续 docs / state commit。
 - npm 已成功上传后，同一 version 不可重发；不要通过删 tag 或 unpublish 试图覆盖。
 
@@ -18,7 +18,7 @@
 - Node 与包管理器满足仓库声明
 - `.github/workflows/release.yml` 存在
 - 已确定 `PUBLISH_TO_NPM=true | false`
-- `speculo/.speculo/commands/docs-sync/state.json` 存在且可解析；不存在时转 docs-sync command 的首次 bootstrap
+- `<Path>{roots.state}/commands/docs-sync/state.json</Path>` 存在且可解析；不存在时转 docs-sync command 的首次 bootstrap
 - 目标 tag `vX.Y.Z` 不存在，除非正在执行明确的失败恢复
 
 任一项不通过就停止，输出修复建议。
@@ -32,7 +32,7 @@
 
 ## Phase 2 — Docs Sync
 
-- 由调用方执行 `../../../commands/docs-sync.md`。
+- 由调用方执行 `<Path>{roots.commands}/docs-sync.md</Path>`。
 - 只修改全局 state 与 workflow sidecar 已确认范围中需要同步的文档或知识资产。
 - CHANGELOG 类文档只写 `[Unreleased]`，保留该段落。
 - 本阶段由 docs-sync 自动提交文档、报告与 state；最终 release commit 仍在 Phase 3 创建，发布后再由 Phase 6 记录为新输入终点。
@@ -88,7 +88,7 @@ npm view "<package-name>" dist-tags
 
 ## Phase 6 — 记录 release 输入节点
 
-仅当 Phase 1-5 全绿时执行。再次调用 `../../../commands/docs-sync.md`，并确认运行前 `HEAD` 等于 `RELEASE_COMMIT_SHA`：
+仅当 Phase 1-5 全绿时执行。再次调用 `<Path>{roots.commands}/docs-sync.md</Path>`，并确认运行前 `HEAD` 等于 `RELEASE_COMMIT_SHA`：
 
 - state 的 `last_range.to_sha` 必须等于 `RELEASE_COMMIT_SHA`。
 - `last_range.from_sha` 来自最后修改旧 state 的 commit，或迁移期 explicit baseline。

package/template/skills/github-npm-ops/references/version-bump-flow.md

@@ -46,7 +46,7 @@ head -30 CHANGELOG.md
  - [0.0.9](https://github.com/owner/repo/releases/tag/v0.0.9)
 ```
 
-完整 CHANGELOG 契约见 `../../docs-sync/references/changelog-contract.md`。
+完整 CHANGELOG 契约见 `<Path>{roots.skills}/docs-sync/references/changelog-contract.md</Path>`。
 
 ## 2. bump package.json
 
@@ -160,7 +160,7 @@ git push origin v0.0.10
 
 npm 已上线 → **不要**改版本号,只补后续动作。
 
-下面的 `notes_file` 只是一次性传给 `gh --notes-file` 的中间文件；若需要保留发布摘要或 release notes，由调用方写入 `speculo/.speculo/commands/<command>/<YYYY-MM-DD>-<scope>-<topic>[-NN].md`。
+下面的 `notes_file` 只是一次性传给 `gh --notes-file` 的中间文件；若需要保留发布摘要或 release notes，由调用方写入 `<Path>{roots.state}/commands/{command}/{date}-{scope}-{topic}[-NN].md</Path>`。
 
 ```bash
 notes_file="$(mktemp -t speculo-release-notes.XXXXXX)"

package/template/skills/speculo-retro/references/friction-taxonomy.md

@@ -7,8 +7,8 @@
 按以下顺序采集原始摩擦点，每条记录**证据出处**（文件路径或对话节点），后续起草 issue 时要引用：
 
 1. **当前对话上下文** —— 本次会话激活过的 command / workflow；用户在哪一步卡住、追问、返工；为绕开限制做了哪些手动动作；哪些指令被误解。
-2. **命令产物** —— `speculo/.speculo/commands/<command>/*.md`：其中记录的验证失败、未完成和阻塞点是一手摩擦。
-3. **change 状态机** —— `speculo/.speculo/<workflow>/changes/<change>/.status.json` 的 `phase_history`：
+2. **命令产物** —— `<Path>{roots.state}/commands/{command}/*.md</Path>`：其中记录的验证失败、未完成和阻塞点是一手摩擦。
+3. **change 状态机** —— `<Path>{roots.state}/{workflow}/changes/{change}/.status.json</Path>` 的 `phase_history`：
    - `revisited` —— phase 被迫回退，通常意味着流程设计或前置产物有缺口
    - `blocked` —— 卡点，记录阻塞原因
    - `skipped` —— phase 被跳过，可能是冗余或不适用

package/template/skills/speculo-retro/references/issue-drafting-sop.md

@@ -14,7 +14,7 @@
   "area":         "string|null, 例 area:commands / area:workflows / area:skills / area:cli / area:contract",
   "body":         "string, 见正文结构",
   "affected":     ["相对路径，例 speculo/commands/archive-and-consolidate.md"],
-  "evidence":     ["证据出处，例 speculo/.speculo/<workflow>/changes/<change>/.status.json#phase_history"],
+  "evidence":     ["证据出处，例 <Path>{roots.state}/{workflow}/changes/{change}/.status.json</Path>#phase_history"],
   "disposition":  "file-issue | record-lesson | drop",
   "dup_of":       "number|null, 疑似重复的已存在 issue 编号"
 }
@@ -28,7 +28,7 @@
 
 ## 类型 → 标签映射
 
-复用 `../github-npm-ops/references/issue-pr-triage.md` 的标签体系，每条至少一个**类型**标签，外加**优先级**，可选**领域**：
+复用 `<Path>{roots.skills}/github-npm-ops/references/issue-pr-triage.md</Path>` 的标签体系，每条至少一个**类型**标签，外加**优先级**，可选**领域**：
 
 | 提案 type | issue 类型标签 |
 |-----------|---------------|
@@ -49,7 +49,7 @@
 [一句话说清痛点 / 不符合预期的行为。]
 
 ## 证据
-[引用具体出处：对话节点、`speculo/.speculo/...` 产物路径、`.status.json` 字段、文档段落。可附最小复现。]
+[引用具体出处：对话节点、`<Path>{roots.state}/...</Path>` 产物路径、`.status.json` 字段、文档段落。可附最小复现。]
 
 ## 根因
 [判断是 asset 设计 / 持久化契约 / 文档 / 工具问题，指明根因而非表象。]
@@ -69,9 +69,9 @@
 起草后、交给调用方提交前，对每条做去重判定：
 
 1. 提取标题与根因的关键词。
-2. 由调用方用 `gh issue list --repo <owner/repo> --search "<关键词>" --state all --limit 20` 检索（机制见 `../github-npm-ops/references/issue-pr-triage.md`）。
+2. 由调用方用 `gh issue list --repo <owner/repo> --search "<关键词>" --state all --limit 20` 检索（机制见 `<Path>{roots.skills}/github-npm-ops/references/issue-pr-triage.md</Path>`）。
 3. 命中语义重复：把 `disposition` 设为 `drop` 或在 `dup_of` 记录已存在编号，默认不重复提；仅当用户明确要求才补提。
 
 ## 交接契约
 
-本 skill 只返回上面的结构化提案清单 + 丢弃/合并说明，**不写文件、不调用 `gh`、不创建 issue**。落盘到 `speculo/.speculo/commands/retro/<YYYY-MM-DD>-<scope>-<topic>[-NN].md` 与实际 `gh issue create` 由调用方 command 在用户确认后执行。
+本 skill 只返回上面的结构化提案清单 + 丢弃/合并说明，**不写文件、不调用 `gh`、不创建 issue**。落盘到 `<Path>{roots.state}/commands/retro/{date}-{scope}-{topic}[-NN].md</Path>` 与实际 `gh issue create` 由调用方 command 在用户确认后执行。

package/template/skills/upstream-fork-sync/SKILL.md

@@ -0,0 +1,83 @@
+---
+id: upstream-fork-sync
+type: skill
+name: upstream-fork-sync
+description: 上游同步评估：为持续二次开发的 Git fork 冻结已集成 checkpoint 与最新上游差异，生成 diff、冲突和定制风险报告；当任务涉及跟踪、评估或记录 fork 上游集成时使用。
+---
+
+# Upstream Fork Sync
+
+以**检查点**为主导词。每个仓库始终分开记录：本次观测到的 upstream tip、可选本地 mirror tip，以及已经由产品分支历史证明完成集成的 upstream checkpoint。Fetch 或 mirror 变化不能推进集成 checkpoint。
+
+## 1. 解析上下文
+
+1. 从当前目录向上寻找并读取 `<Path>{roots.state}/workspace.json</Path>`，验证 `path_base` 和所有 roots，再读取 `<Path>{roots.config}</Path>`；无法唯一确定项目根时停止。
+2. 读取项目 `AGENTS.md` 及其作用域内规则。项目存在工程规范时读取适用入口。
+3. 将本 Skill 的唯一持久化根解析为 `<Path>{roots.state}/skills/upstream-fork-sync/</Path>`。独立运行只写该根；不得创建 workflow change 或 command 报告。
+4. 读取 [Repository contract](references/repository-contract.md)，确定仓库、refs、网络刷新和副作用边界。
+
+完成标准：项目根、Skill state 根、目标仓库集合和本次是否允许 fetch 都只有一个解释。
+
+## 2. 建立稳定配置
+
+读取 `<Path>{roots.state}/skills/upstream-fork-sync/repository-map.json</Path>`。不存在时，只读发现 Git 仓库、remotes、默认产品分支和 upstream tracking refs，按 [Repository contract](references/repository-contract.md) 创建 schema v1 配置；无法从 Git 事实唯一判断的字段一次性询问用户。配置已存在时验证，不静默改写。
+
+读取 `<Path>{roots.state}/skills/upstream-fork-sync/customization-map.md</Path>`。不存在时创建最小稳定清单，记录 fork 必须长期保留的产品不变量和审查热点；无法从项目文档或代码证明的业务约束标记为待确认。该文件不接收运行 SHA、dirty paths、冲突或本次结论。
+
+完成标准：每个 repository id 唯一，所有项目路径和 refs 可解析，稳定配置与动态运行事实分离。
+
+## 3. 创建评估 change
+
+读取 [State schema](references/state-schema.md) 和 [Report contract](references/report-contract.md)，从用户主题生成小写 ASCII kebab-case topic，然后运行：
+
+```bash
+node <Path>{roots.skills}/upstream-fork-sync/scripts/upstream-sync.mjs</Path> assess \
+  --root . \
+  --state-root <Path>{roots.state}/skills/upstream-fork-sync</Path> \
+  --repository-map <Path>{roots.state}/skills/upstream-fork-sync/repository-map.json</Path> \
+  --topic <topic>
+```
+
+- 默认离线使用本地 refs；只有用户明确要求刷新网络 refs 时添加 `--fetch`。
+- 只需预览完整冻结快照时添加 `--dry-run`，此分支不写 state 或 change。
+- 正常运行创建 `<Path>{roots.state}/skills/upstream-fork-sync/{date}-{topic}[-NN]/</Path>`，已有目录永不覆盖。
+
+完成标准：脚本退出 0，change 的 state 与两份报告完整发布，根 `state.json` 只在 change 发布成功后更新。
+
+## 4. 深化风险结论
+
+逐仓库检查报告中的 Git 确认冲突、自动合并重叠和定制风险路径。对每条高风险路径使用报告冻结的 SHA 执行精确 `git diff <base>..<target> -- <path>`，再与 `customization-map.md` 的稳定不变量映射。
+
+只把路径级证据支持的语义结论补入本 change 的报告。保持 Git 冲突、自动合并重叠、定制合同风险和 dirty-worktree 重叠为四个类别；零文本冲突不得表述为集成安全。
+
+完成标准：所有冲突和定制热点都有结论或明确未验证项，报告中的命令可以从冻结 SHA 复现。
+
+## 5. 返回后续选择
+
+返回 change 路径、仓库 checkpoint、观测 upstream SHA、风险摘要和未验证项。列出适合继续处理的已安装 Work，但不自动创建 workflow change、不调用 Work、不 merge、不 commit、不 push；后续路线由用户选择。
+
+完成标准：本次 Skill 在评估 change 完整后停止，用户能用冻结产物自行选择下一 Work。
+
+## 6. 记录外部集成
+
+只有其他 Work 已完成集成且用户要求更新 checkpoint 时进入此分支。读取目标 change state，并运行：
+
+```bash
+node <Path>{roots.skills}/upstream-fork-sync/scripts/upstream-sync.mjs</Path> record-integration \
+  --root . \
+  --state-root <Path>{roots.state}/skills/upstream-fork-sync</Path> \
+  --repository-map <Path>{roots.state}/skills/upstream-fork-sync/repository-map.json</Path> \
+  --change <change> \
+  --repository <repository-id> \
+  --merge-commit <full-sha> \
+  --upstream-sha <full-sha> \
+  --verification '<command>: exit 0'
+```
+
+该入口只在 merge commit 可从产品 ref 到达、目标 upstream SHA 是其精确非第一父节点且匹配 change 冻结目标时更新状态；它不执行集成。
+
+完成标准：change state 和根 checkpoint 都已原子重读，实际 Git 历史与记录一致。
+
+## 停止条件
+
+目标 ref 缺失、保存的 checkpoint 不在产品历史、checkpoint 不在当前 upstream 历史、存在多个 merge-base、配置越界或状态 schema 非法时，停止且不移动 refs、不发布部分 change、不推进 checkpoint。返回准确 repository id、路径、refs 与 SHAs。