@namewta/speculo 0.1.21 → 0.2.1

package/template/workflows/dev/04-finalize/finalize-archive.md

@@ -1,55 +0,0 @@
-# Finalize & Archive Phase
-
-本阶段把通过验证的 change 收尾并归档。**归档是破坏性目录移动，必须先列清单、经用户确认才执行。**
-
-## 输入
-
-- `speculo/.speculo/dev/<change>/completion-verification.md`，且 `verification_status: verified`
-- 当前 change 的 `.status.json`
-- 顶层索引 `speculo/.speculo/dev-status.json`
-
-## 产物
-
-- `speculo/.speculo/dev/<change>/completion-summary.md`，由 `../_templates/completion-summary-template.md` 填写
-- 归档动作：change 目录移动到 `speculo/.speculo/archive/dev/<YYYY-MM>/<change>/`
-
-## 填写引导
-
-### 前置门控
-
-1. 确认 `verification_status: verified`。若为 `blocked`，**停止**，不收尾、不归档，回到验证或修复。
-   - **Worktree 模式**：本阶段前应已完成 `04-finalize.md` 的 Phase 2 Merge Back & Cleanup（`worktree_status: removed`），change 目录已随合并到达 `base_branch`，归档在 base 分支上对该目录执行。若 `worktree_status` 仍非 `removed`，先回 Phase 2 合并清理，再进入归档。
-
-### 状态收尾
-
-2. 写 `completion-summary.md`：交付边界、关键变更、验证证据指针（指向 `completion-verification.md`）、遗留事项。
-3. 把当前 change `.status.json` 的 `change_status` 置为 `completed`。
-4. 如有可沉淀经验，在用户或项目规则允许时追加到 `speculo/.speculo/.config/LESSONS.md`。
-
-### 归档（破坏性，需确认）
-
-本步与 `../../../commands/archive.md` 共用同一安全契约；此处作用域仅限**当前单个 change**：
-
-5. 列出归档计划：源路径 `speculo/.speculo/dev/<change>/`、目标路径 `speculo/.speculo/archive/dev/<YYYY-MM>/<change>/`、`updated_at`、最后 phase、是否仍在 `dev-status.json` 的 `active[]`。
-6. 向用户展示计划并等待明确确认。**没有确认时只输出计划，不移动目录、不改索引。**
-7. 若目标归档路径已存在，标记冲突并停止，不覆盖。
-8. 用户确认后执行：
-   - 创建 `speculo/.speculo/archive/dev/<YYYY-MM>/`
-   - 移动 change 目录到 `speculo/.speculo/archive/dev/<YYYY-MM>/<change>/`
-   - 从 `speculo/.speculo/dev-status.json` 的 `active[]` 删除该 change
-   - 把（已随目录移动的）`.status.json` 的 `change_status` 置为 `archived`，写 `archived: true`、`archive_path`
-9. 若移动失败，停止后续动作，报告已完成与未完成项；不要回滚已成功的移动，除非用户明确要求。
-
-## 边界
-
-- `verification_status` 非 `verified` 时不得归档。
-- 未获用户确认时不执行任何破坏性移动或索引修改。
-- 不覆盖已存在的归档目标。
-- 批量归档多个 change 时改用 `../../../commands/archive.md`。
-
-## 完成准则
-
-- `completion-summary.md` 无残留 `[TODO:]`
-- change 目录已位于 `speculo/.speculo/archive/dev/<YYYY-MM>/<change>/`
-- `speculo/.speculo/dev-status.json` 的 `active[]` 已移除该 change
-- `.status.json` 的 `change_status: archived`，`archived: true`，`archive_path` 已写入

package/template/workflows/dev/A-improve-architecture/A-improve-architecture.md

@@ -1,60 +0,0 @@
----
-id: dev/A-improve-architecture
-category: dev
-name: Improve Architecture
-description: 扫描代码库寻找深化机会，以可视化 HTML 报告呈现候选，再对选中方向深入质询并沉淀领域模型
-keywords: [architecture, deepening, deep-module, refactor, 架构, 深化, 接缝]
----
-
-# Improve Architecture 工作流执行指引
-
-本工作流是 `dev/A` 入口：浮现架构摩擦、提出**深化机会**，目标是可测试性与 AI 可导航性。架构词汇统一引用 `../../../vendor/codebase-design/SKILL.md`；领域语言以 `speculo/.speculo/.config/context/CONTEXT.md` 为准。
-
-> **目录命名：** `<change>` 必须为 `YYYY-MM-DD-<kebab-name>`。产物写入 `speculo/.speculo/dev/<change>/`。
-
-## 何时使用
-
-当用户想系统性发现并落实架构深化机会时使用。也可由 `../H-diagnose/H-diagnose.md` 在修复后转入。
-
-## 阶段
-
-| Phase | id | 规范 | 产物 |
-|-------|-----|------|------|
-| 1. Scan | `architecture-scan` | `architecture-scan.md` | `architecture-candidates.md` |
-| 2. Report | `architecture-review` | `architecture-review.md`、`HTML-REPORT.md` | `architecture-review.html` |
-| 3. Grill | `architecture-grill` | `architecture-grill.md` | `architecture-design.md` |
-
-### 1. Scan — 探索深化候选
-- id：`architecture-scan`
-- 完成准则：`architecture-candidates.md` 无残留 `[TODO:]`；候选用 codebase-design 词汇命名
-
-### 2. Report — 可视化架构审查报告
-- id：`architecture-review`
-- 完成准则：HTML 已写入 change 目录并为用户打开；已请用户选择候选
-
-### 3. Grill — 质询所选候选并沉淀
-- id：`architecture-grill`
-- 完成准则：`architecture-design.md` 无残留 `[TODO:]`；术语/ADR 经用户确认后沉淀
-
-## 依赖
-
-- 硬依赖：无
-- 软依赖：`../M-domain-modeling/`（领域沉淀）、`../03-tdd/03-tdd.md`（实现落地）
-
-## 状态扩展字段
-
-- `dev_entry` (string) — 固定为 `dev/A`
-- `embedded_guides` (array) — 包含 `improve-architecture`
-- `candidate_count` (number)
-- `selected_candidate` (string|null)
-- `report_path` (string|null)
-- `architecture_status` (scanning | reported | grilling | designed | blocked)
-
-## 完成与状态更新
-
-- 进入每个 phase 时更新 `current_phase` 和 `phase_history`。
-- 本工作流不自动完成 change；深化的实现交由 `../03-tdd/03-tdd.md` 落地。
-
-### 缺少 change 目录时
-
-若无 active change，执行 `../AGENTS.md` 进入协议步骤 3（原子三步），不得内联自初始化 JSON。

package/template/workflows/dev/A-improve-architecture/HTML-REPORT.md

@@ -1,123 +0,0 @@
-# HTML 报告格式
-
-架构审查以单个**自包含 HTML 文件**渲染，写入 `speculo/.speculo/dev/<change>/architecture-review.html`（由入口 `A-improve-architecture.md` Phase 2 规定，**不写临时目录**）。Tailwind 和 Mermaid 均从 CDN 加载。Mermaid 可靠地处理图形状图表；手写 div 和内联 SVG 处理更具编辑性的可视化（质量图、横截面图）。两者混合使用——不要所有内容都依赖 Mermaid，否则会显得千篇一律。
-
-## 脚手架
-
-```html
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <title>Architecture review — {{repo name}}</title>
-    <script src="https://cdn.tailwindcss.com"></script>
-    <script type="module">
-      import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";
-      mermaid.initialize({ startOnLoad: true, theme: "neutral", securityLevel: "loose" });
-    </script>
-    <style>
-      /* small custom layer for things Tailwind doesn't cover cleanly:
-         dashed seam lines, hand-drawn-feeling arrow heads, etc. */
-      .seam { stroke-dasharray: 4 4; }
-      .leak { stroke: #dc2626; }
-      .deep { background: linear-gradient(135deg, #0f172a, #1e293b); }
-    </style>
-  </head>
-  <body class="bg-stone-50 text-slate-900 font-sans">
-    <main class="max-w-5xl mx-auto px-6 py-12 space-y-12">
-      <header>...</header>
-      <section id="candidates" class="space-y-10">...</section>
-      <section id="top-recommendation">...</section>
-    </main>
-  </body>
-</html>
-```
-
-## 页头
-
-仓库名称、日期和紧凑图例：实线框 = 模块，虚线 = 接缝，红色箭头 = 泄漏，深色粗框 = 深层模块。没有介绍段落——直接进入候选方案。
-
-## 候选卡片
-
-图表承担主要信息量。文字稀疏、平实，使用 `../../../vendor/codebase-design/SKILL.md` 的术语表词汇，不铺陈。
-
-每个候选方案为一个 `<article>`：
-
-- **标题**——简短，命名深化操作（例如「折叠订单接收流水线」）。
-- **徽章行**——推荐强度（`Strong` = 翡翠绿，`Worth exploring` = 琥珀色，`Speculative` = 石板灰），外加一个依赖类别标签（`in-process`、`local-substitutable`、`ports & adapters`、`mock`）。
-- **文件**——等宽字体列表，`font-mono text-sm`。
-- **Before / After 图表**——核心部分。两列并排。见下方模式。
-- **问题**——一句话。痛点是什么。
-- **解决方案**——一句话。改变了什么。
-- **收益**——项目符号，每条 ≤6 个字。例如「测试只需命中一个接口」「定价逻辑不再泄漏」「删除 4 个浅层包装器」。
-- **ADR 提示**（如适用）——琥珀色背景框中的一行说明。
-
-没有解释性段落。如果图表需要一段文字才能理解，那就重绘图表。
-
-## 图表模式
-
-选择适合候选方案的模式。混合使用。不要让每张图表看起来都一样——多样性本身就是目的之一。
-
-### Mermaid 图（依赖/调用流的常用工具）
-
-当要表达「X 调用 Y 调用 Z，看看这有多乱」时，使用 Mermaid `flowchart` 或 `graph`。用 Tailwind 风格的卡片包裹它，避免显得突兀。使用 classDef 将泄漏边着色为红色，将深层模块着色为深色。时序图适合表达「Before：6 次往返；After：1 次」。
-
-```html
-<div class="rounded-lg border border-slate-200 bg-white p-4">
-  <pre class="mermaid">
-    flowchart LR
-      A[OrderHandler] --> B[OrderValidator]
-      B --> C[OrderRepo]
-      C -.leak.-> D[PricingClient]
-      classDef leak stroke:#dc2626,stroke-width:2px;
-      class C,D leak
-  </pre>
-</div>
-```
-
-### 手写框线箭头图（当 Mermaid 布局不理想时）
-
-模块用带有边框和标签的 `<div>` 表示。箭头用绝对定位在相对容器上的内联 SVG `<line>` 或 `<path>` 元素表示。当你希望「After」图表呈现为一个粗边框的深层模块，内部变灰时，使用这种方式——Mermaid 无法渲染出正确的视觉重量。
-
-### 横截面图（适合展示分层浅度）
-
-堆叠水平条带（`h-12 border-l-4`）来展示调用经过的层级。Before：6 个薄层，每层几乎什么都不做。After：1 个粗条带，标注了合并后的职责。
-
-### 质量图（适合展示「接口与实现一样宽」）
-
-每个模块两个矩形——一个表示接口表面积，一个表示实现。Before：接口矩形几乎和实现矩形一样高（浅层）。After：接口矩形短，实现矩形高（深层）。
-
-### 调用图折叠
-
-Before：函数调用树，渲染为嵌套盒子。After：同一棵树折叠为一个盒子，内部现已内部化的调用在其中淡色显示。
-
-## 样式指南
-
-- 偏编辑风格，而非企业仪表盘风格。宽裕的留白。标题可选衬线字体（`font-serif` 与 stone/slate 配色搭配效果很好）。
-- 颜色克制：一种强调色（翡翠绿或靛蓝）加红色表示泄漏，琥珀色表示警告。
-- 图表高度保持在约 320px，以便 before/after 并排显示无需滚动。
-- 图表内模块标签使用 `text-xs uppercase tracking-wider`——它们应该呈现为示意图风格，而非 UI 风格。
-- 唯一的脚本是 Tailwind CDN 和 Mermaid ESM 导入。报告其余部分是静态的——没有应用代码，除 Mermaid 自身渲染外没有交互性。
-
-## 首选推荐部分
-
-一张较大的卡片。候选方案名称，一句说明原因的话，锚链接指向其卡片。仅此而已。
-
-## 语气
-
-平实中文，简洁——但架构名词和动词直接来自 `../../../vendor/codebase-design/SKILL.md`。简洁不是偏离术语表的借口。
-
-**精确使用：** 模块（module）、接口（interface）、实现（implementation）、深度（depth）、深（deep）、浅（shallow）、接缝（seam）、适配器（adapter）、杠杆（leverage）、局部性（locality）。
-
-**绝不替换：** 组件 / 服务 / 单元（表示 module）· API / 签名（表示 interface）· 边界（表示 seam）· 层 / 包装器（表示 module，当你的意思是 module 时）。
-
-**符合风格的表述：**
-
-- 「订单接收模块是浅的——接口几乎和实现一样复杂。」
-- 「定价逻辑在接缝处泄漏。」
-- 「深化：一个接口，一处可测。」
-- 「两个适配器证明了接缝：生产用 HTTP，测试用内存。」
-
-**收益项目符号**用术语表词汇命名收益：「局部性：bug 集中在一个模块」「杠杆：一个接口，N 个调用点」「接口缩小，实现吸收包装器」。不要写「更易维护」或「更干净的代码」——这些词不在术语表中，不应出现。
-
-不模棱两可，不开场白，不写「值得注意的是……」。如果一句话可以变成项目符号，就变成项目符号。如果一个项目符号可以删掉，就删掉。如果一个词不在 `../../../vendor/codebase-design/SKILL.md` 术语表中，在发明新词之前先找一个术语表中有的词。

package/template/workflows/dev/A-improve-architecture/architecture-grill.md

@@ -1,30 +0,0 @@
-# Architecture Grill Phase — 质询所选候选并沉淀
-
-## 输入
-
-- 用户选中的深化候选（来自 `architecture-review.html`）
-- `speculo/.speculo/dev/<change>/architecture-candidates.md`
-- `speculo/.speculo/.config/context/CONTEXT.md`、`speculo/.speculo/.config/adr/`
-
-## 产物
-
-- `speculo/.speculo/dev/<change>/architecture-design.md`
-- 经用户确认后更新 `.config/context/`、`.config/adr/`
-
-## 填写引导
-
-1. 用 `../../../skills/grill-me/SKILL.md` 与用户走设计树：约束、依赖、深化后模块形态、接缝后面是什么、哪些测试存活。
-2. 决策结晶时按 `../M-domain-modeling/M-domain-modeling.md` 内联沉淀：深化模块用了 CONTEXT 没有的概念 → 加术语；锐化了模糊术语 → 更新 CONTEXT；用户以关键理由否决候选 → 按 ADR 三判据决定是否记 ADR。
-3. 想探索深化模块的备选接口时，按 `../../../vendor/codebase-design/DESIGN-IT-TWICE.md` 的「设计两次」并行子代理模式。
-
-## 边界
-
-- 写 `.config/context/` 或 `.config/adr/` 前必须经用户确认。
-- 本 phase 不落地代码实现（交由 `../03-tdd/03-tdd.md`）。
-
-## 完成准则
-
-- 选中候选的接口、依赖策略与适配器、存活测试已记入 `architecture-design.md`
-- 决策结晶处的术语 / ADR 已按 `../M-domain-modeling/` 沉淀（经用户确认）
-- `architecture-design.md` 无残留 `[TODO:]`
-- `.status.json` 写入 `selected_candidate`，置 `architecture_status: designed`

package/template/workflows/dev/A-improve-architecture/architecture-review.md

@@ -1,29 +0,0 @@
-# Architecture Review Phase — 可视化架构审查报告
-
-## 输入
-
-- `speculo/.speculo/dev/<change>/architecture-candidates.md`
-- `speculo/.speculo/.config/context/CONTEXT.md`
-
-## 产物
-
-- `speculo/.speculo/dev/<change>/architecture-review.html`
-
-## 填写引导
-
-1. 按 `../HTML-REPORT.md` 编写**自包含** HTML（Tailwind + Mermaid 走 CDN），每个候选一张卡片含**前后对比图**，结尾「首要推荐」段。
-2. 写入 `speculo/.speculo/dev/<change>/architecture-review.html`（**不写临时目录**），用 OS 命令打开（macOS `open`、Linux `xdg-open`、Windows `start`），并告知用户绝对路径。
-3. 领域用 CONTEXT 词汇、架构用 codebase-design 词汇。
-4. 此时不提接口设计；写入并打开后，询问用户：「这些候选你想探索哪一个？」
-
-## 边界
-
-- 本 phase 不做接口设计或质询。
-- 报告必须写入 change 目录，禁止 `temp/` 或项目根目录。
-
-## 完成准则
-
-- HTML 自包含、每个候选有前后对比图与推荐强度徽章、含首要推荐段
-- 报告已为用户打开
-- 已请用户选择候选
-- `.status.json` 写入 `candidate_count`、`report_path`，置 `architecture_status: reported`

package/template/workflows/dev/A-improve-architecture/architecture-scan.md

@@ -1,37 +0,0 @@
-# Architecture Scan Phase — 探索深化候选
-
-## 输入
-
-- 当前 git 仓库与待改进的代码区域
-- `speculo/.speculo/.config/context/CONTEXT.md`、触及区域的 `speculo/.speculo/.config/adr/` ADR
-- 设计词汇单一事实源 `../../../vendor/codebase-design/SKILL.md`、`DEEPENING.md`
-
-## 产物
-
-- `speculo/.speculo/dev/<change>/architecture-candidates.md`
-
-## 核心原则（引用 codebase-design）
-
-- **删除测试**：对任何疑似浅的模块，想象删除它——复杂性会集中（好信号）还是只是移动？
-- **深度是接口的属性**：小接口 + 大量实现；深化 = 缩小接口、把复杂性吸收进实现。
-- **接缝纪律**：一个适配器 = 假设接缝，两个 = 真实接缝。
-- 完整原则见 `../../../vendor/codebase-design/SKILL.md` 与 `DEEPENING.md`，本 phase 不复制。
-
-## 填写引导
-
-1. 先读 `speculo/.speculo/.config/context/CONTEXT.md` 与触及区域的 `.config/adr/`。
-2. 用 Agent 工具（`subagent_type=Explore`）遍历代码库，注意摩擦：理解一个概念要在许多小模块间跳转？模块浅？纯函数仅为可测试性而提取？紧耦合泄漏？难以通过当前接口测试？
-3. 对每个疑似浅模块应用**删除测试**，保留「删除会集中复杂性」的候选。
-4. 每个候选记录：**涉及文件**、**问题**、**解决方案**、**收益**（局部性 / 杠杆 / 测试改善）、**依赖类别**（进程内 / 本地可替换 / 端口与适配器 / mock）、**推荐强度**（强烈 / 值得探索 / 推测性）。
-5. 与现有 ADR 冲突的候选，仅在摩擦真实到值得重审 ADR 时保留，并显式标注。
-
-## 边界
-
-- 本 phase 不写 HTML 报告、不做接口设计。
-- 候选均用 codebase-design 词汇命名，不散用「组件 / 服务 / 边界」。
-
-## 完成准则
-
-- 每个候选含文件、问题、解决方案、收益、依赖类别、推荐强度
-- `architecture-candidates.md` 无残留 `[TODO:]`
-- `.status.json` 写入 `candidate_count`，置 `architecture_status: scanning`

package/template/workflows/dev/AGENTS.md

@@ -1,95 +0,0 @@
----
-id: dev/index
-category: dev
-name: Dev Workflow AGENTS Guide
-description: 开发工作流导航、状态汇报、下一步推荐与渐进披露指引
-keywords: [dev, 开发, workflow, index, agents, 状态]
----
-
-# Dev Workflow AGENTS Guide
-
-> ⚠️ **持久化铁律：本文件及所有 dev workflow 的全部产物，必须且只能写入 `speculo/.speculo/dev/<change>/`。绝对禁止写入项目根目录的 `.speculo/`、`temp/` 或其他任何非规范位置。**
-
-本文件是 dev 分类的 AGENTS 导航入口。进入时先读取 `speculo/.speculo/dev-status.json`，再按其中 active change 读取 `speculo/.speculo/dev/<change>/.status.json`，根据用户意图推荐下一步。
-
-> **命名铁律：** 所有 change 目录必须为 `YYYY-MM-DD-<kebab-name>`（例：`2026-06-12-user-auth`）。不符合此格式的目录视为 `malformed`，仅汇报不自动操作。
-
-## 渐进披露
-
-1. 先读本文件，确认当前 dev change、执行模式和入口别名。
-2. 选定入口后，只读取对应 workflow 入口文件（如 `03-tdd/03-tdd.md`）。
-3. 进入具体 phase 时，再读取该 phase 文件、模板和被调用 skill wrapper。
-4. 执行中如涉及项目硬约束、跨任务经验、领域上下文、术语定义、ADR 或决策依据，必须参考 `../../.speculo/.config/` 下对应文件；`RULES.md` 的约束高于普通 workflow 文案。
-5. 需要理解状态骨架、archive 或 `.config` 时，读取 `../../.speculo/AGENTS.md` 和相关子目录的 `AGENTS.md`。
-
-## 入口别名
-
-| 别名 | 入口 | 用途 |
-|------|------|------|
-| `dev/01` | `01-grill-with-docs/01-grill-with-docs.md` | 领域术语、CONTEXT、ADR 与方案拷问 |
-| `dev/02` | `02-prd/02-prd.md` | zoom-out 全景理解与 PRD 综合 |
-| `dev/03` | `03-tdd/03-tdd.md` | 垂直切片 TDD 实现 |
-| `dev/04` | `04-finalize/04-finalize.md` | 完成前验证、状态收尾与归档 |
-| `dev/I` | `I-to-issues/I-to-issues.md` | 垂直切片 issue 分解，可嵌入其他 dev workflow，也可独立进入 |
-| `dev/H` | `H-diagnose/H-diagnose.md` | hotfix / bug / 性能回退诊断，零依赖，可独立进入 |
-| `dev/R` | `R-review/R-review.md` | Spec / Engineering / Standards 三维度 diff 审查，零依赖，可独立进入 |
-| `dev/D` | `D-docs-sync/D-docs-sync.md` | 基于 git diff、归档产物和 `.config` 生命周期同步文档/知识资产 |
-| `dev/M` | `M-domain-modeling/M-domain-modeling.md` | 主动领域建模：挑战术语、压测边界，沉淀 CONTEXT 通用语言与 ADR；格式单一事实源，可嵌入其他 dev workflow，也可独立进入 |
-| `dev/A` | `A-improve-architecture/A-improve-architecture.md` | 深化机会扫描 + HTML 架构审查 + 质询，基于 `vendor/codebase-design` 词汇，零依赖，可独立进入 |
-
-## 进入协议
-
-1. 若用户未指定 change，扫描 `speculo/.speculo/dev-status.json` 和 `speculo/.speculo/dev/*/.status.json`，列出 active changes。
-   - **命名校验**：扫描时仅处理符合 `YYYY-MM-DD-<kebab-name>` 格式的目录。不符合的目录标记为 `malformed`，单独列出路径并提示用户修复或手动清理，不自动删除或重命名。
-2. 若只有一个 active change，默认继续该 change；若有多个 active change，要求用户选择。
-3. 若没有 active change，按用户意图创建新的 change。**以下三步为原子操作，不可跳过，前一步失败时停止后续并报告：**
-   - **3a. 创建 change 目录** —— `speculo/.speculo/dev/<YYYY-MM-DD>-<kebab-name>/`（使用当前日期，`<kebab-name>` 从用户意图提取，不超过 5 个词）。
-   - **3b. 写入 `.status.json`** —— 在 change 目录下创建 `.status.json`，按 `../../skills/speculo-write/references/persistence-contract-sop.md` 最小初始化模板填入所有必填字段（`name`、`category: "dev"`、`change_status: "active"`、`created_at`、`updated_at`、`current_phase: "00-init"`、`phase_history`）。
-   - **3c. 更新 `dev-status.json`** —— 读取 `speculo/.speculo/dev-status.json`，在 `active[]` 中追加该 change 的索引条目（`name`、`current_phase: "00-init"`、`updated_at`），写回文件。
-   - 以上三步全部成功后，方可继续推荐入口。
-4. 推荐入口时优先使用用户显式别名；没有别名时按执行模式推荐。
-5. 执行任何 workflow 前，读取该 workflow 入口文件、阶段文件、模板和被调用 skill wrapper。
-6. 执行中一旦需要项目规则、经验、领域术语、上下文或 ADR，先读取 `../../.speculo/.config/`，再继续判断或写入产物；除非用户明确要求或规则允许，不自动改写 `.config/`。
-7. **Worktree 隔离（可选，默认 off）**：仅当用户**显式请求**隔离时，新 change 在 `dev/01` 的 Phase 0 经 `../../skills/worktree-isolation/SKILL.md` 建立隔离分支 `speculo/dev/<change>` 与 `.worktree/<change>/` 工作树，并把 `base_branch`、`change_branch` 记入 `.status.json`。扫描 active changes 时，对 `worktree_enabled` 为真者可结合 `git worktree list` 核对工作树是否存在。
-
-## 执行模式
-
-- `full`：`dev/01` -> `dev/02` -> `dev/I` -> `dev/03` -> `dev/04`。
-- `planning-only`：`dev/01` -> `dev/02` -> `dev/I`，不进入实现。
-- `implementation-only`：已有 PRD、issue 或明确任务时，从 `dev/03` 开始。
-- `hotfix`：Bug、异常、性能回退时，从 `dev/H` 开始（零依赖，无需上游工作流产物）；修复阶段可嵌入 `dev/03` 的 TDD 回归循环。
-- `review`：已有 fixed point 或用户要求审查时，从 `dev/R` 开始（零依赖，无需上游工作流产物）。
-- `finalize`：实现完成、需要完成前验证与状态收尾归档时，从 `dev/04` 开始。
-- `docs-sync`：需要基于 git 差异刷新对外文档时，从 `dev/D` 开始。
-- `domain-modeling`：需要主动澄清/锐化领域术语、维护 CONTEXT 与 ADR 时，从 `dev/M` 开始（零依赖；也被 `dev/01`、`dev/02`、`dev/04`、`dev/D`、`dev/A` 引用）。
-- `improve-architecture`：需要系统性发现并落实架构深化机会时，从 `dev/A` 开始（零依赖；建立在 `vendor/codebase-design` 词汇与 `dev/M` 领域模型之上）。
-
-> **独立入口说明：** `dev/H`、`dev/I`、`dev/R`、`dev/M`、`dev/A` 五个横向工作流均为零硬依赖设计。用户可直接从任一入口进入，无需预先执行 `dev/01`、`dev/02` 等主线工作流。当同 change 目录下缺少上游产物时，各工作流会自行通过代码库探索（git 考古、grep 搜索、文档扫描）采集所需上下文，仅在代码库无法确定的决策点上询问用户。
->
-> **横向工作流的共享底座：** `dev/M`（领域模型）拥有 CONTEXT / ADR 格式的单一事实源；`dev/A`（架构深化）与 `dev/03`（TDD）共享 `vendor/codebase-design` 的设计词汇（模块 / 接口 / 接缝 / 适配器 / 深度 / 杠杆 / 局部性）。引用方一律不复制这些规范。
-
-## 状态汇报
-
-输出 dev 状态时至少包含：
-
-- active change 数量与每个 change 的 `current_phase`
-- malformed 目录清单（不符合 `YYYY-MM-DD-<kebab-name>` 格式的目录）
-- 最近更新的 change，按 `updated_at` 倒序
-- `phase_history` 最后一项为 `blocked` 或 `updated_at` 超过 14 天未变化的 change
-- worktree 模式 change 额外汇报 `base_branch` / `change_branch` / `worktree_status`
-- 推荐下一步入口和原因
-
-## 续跑协议
-
-1. 读取 change 目录下 `.status.json` 的 `current_phase` 与 `phase_history`。
-2. 跳过 `status: completed` 的 phase；从 `in-progress`、`blocked` 或首个 `pending` phase 继续。
-3. 根据 `current_phase` 匹配 workflow 入口 `## 阶段` 中的机器 id，只读取对应 phase 文件与模板。
-4. 首个 workflow 进入 change 时写入 `execution_mode`（使用入口声明的执行模式名或用户指定别名）。
-5. 不得因续跑而重复创建 change 或重写已完成的 phase 产物。
-
-## 完成与状态更新
-
-- 所有 dev workflow 必须维护同一 change 的 `.status.json`。
-- 进入 phase 时更新 `current_phase`，并在 `phase_history` 追加 `in-progress` 记录。
-- phase 完成时写入 `completed_at` 和 `status: completed`。
-- 只有 `dev/04-finalize` 或 `archive` 命令可写 `change_status: completed | archived`；其他 dev workflow 只写各自扩展字段。

package/template/workflows/dev/D-docs-sync/D-docs-sync.md

@@ -1,140 +0,0 @@
----
-id: dev/D-docs-sync
-category: dev
-name: Docs Sync
-description: 基于 git 差异、归档产物和 .config 生命周期同步或初始化项目文档与知识资产
-keywords: [docs-sync, changelog, readme, agents, config, archive, adr, context, lessons, rules, documentation, 文档同步]
----
-
-# Docs Sync 工作流执行指引
-
-本工作流是 `dev/D` 入口，用于把一段 git 差异、归档产物和项目知识资产生命周期映射回 README、CHANGELOG、AGENTS、`docs/` 与 `speculo/.speculo/.config/`。常规状态下它只做基于事实的差量同步，不做整页重写，也不堆积没有当前代码或归档证据支撑的内容。
-
-当 `speculo/.speculo/dev/docs-sync-state.json` 没有同步内容（例如 `tracked_assets: []`、`last_sync_sha: null` 或 state 文件不存在）时，默认进入 `bootstrap` 模式：面向当前项目执行一次从 0 到 1 的完整文档初始化，自动盘点项目事实、推导首批 `tracked_assets`、创建缺失的基础文档，并在验证通过后建立首次同步基线。
-
-## 内置指引
-
-### Iron Law
-
-禁止在不读取 `speculo/.speculo/dev/docs-sync-state.json` 的 `last_sync_sha`、当前 `HEAD`、`speculo/.speculo/archive/` 相关归档产物与 `tracked_assets` 的情况下修改任何文档或 `.config` 知识资产。若 state 不存在或为空，也必须先按 `state-json-schema.md` 识别为 `bootstrap`，完成项目事实盘点后再创建或修改文档。
-
-已建立基线后，如果 diff 为空且归档/`.config` 审计没有 stale、missing 或 prune 信号，直接报告无需同步或空同步，并按规则推进 state；不要触碰无关资产。`bootstrap` 模式不视为空同步，必须完成初始化审计。
-
-文档更新必须是动态生命周期管理：每次同步都判断应新增、删除、修改、保留哪些内容。禁止只追加内容；发现旧事实、旧 ADR 引用、被当前实现反转的说明、空模板或重复沉淀时，必须删除、改写、标记废弃或在 report 中说明为何暂不处理。
-
-### 输入
-
-- `speculo/.speculo/dev/docs-sync-state.json`
-- 当前 git `HEAD`
-- state 中的 `tracked_assets` 列表
-- `speculo/.speculo/archive/` 中与本次 diff、路径、术语或决策相关的归档 change
-- `speculo/.speculo/.config/RULES.md`、`LESSONS.md`、`context/`、`adr/`
-- 当前 change 目录：`speculo/.speculo/dev/<change>/`（`<change>` 必须为 `YYYY-MM-DD-<kebab-name>`，例：`2026-06-12-docs-sync`）
-
-### 输出
-
-- `speculo/.speculo/dev/<change>/docs-sync-report.md`
-- 初始化或更新后的 tracked assets
-- 更新后的 `speculo/.speculo/dev/docs-sync-state.json`
-
-（`<change>` 格式：`YYYY-MM-DD-<kebab-name>`）
-
-### 渐进披露
-
-- `readme-contract.md`：更新 README 类文档时读取。
-- `agents-contract.md`：更新 AGENTS / AI 代理手册类文档时读取。
-- `changelog-contract.md`：更新 CHANGELOG 类文档时读取。
-- `config-contract.md`：更新或审计 `speculo/.speculo/.config/` 时读取。
-- `knowledge-extract.md`：从 `speculo/.speculo/archive/` 提取知识沉淀时读取。
-- `state-json-schema.md`：初始化、迁移、读取或写回 docs-sync state 时读取。
-- `../M-domain-modeling/M-domain-modeling.md`：术语、ADR、上下文边界不稳定或一词多义时读取并调用其确认流程；写 CONTEXT / ADR 前还要按需读取 `../M-domain-modeling/CONTEXT-FORMAT.md` 或 `../M-domain-modeling/ADR-FORMAT.md`。
-
-> **通用语言对齐**：对外文档（README / AGENTS）中的领域术语以 `speculo/.speculo/.config/context/CONTEXT.md` 为准；同步中若发现文档与 CONTEXT 术语漂移，交由 `../M-domain-modeling/M-domain-modeling.md` 沉淀，docs-sync 本身不另立或重定义领域术语。
->
-> **RULES 写入边界**：`speculo/.speculo/.config/RULES.md` 是用户维护资产。docs-sync 可以读取、审计并在 report 中提出增删改建议；只有用户明确确认某条规则改动时才写入。
-
-## 阶段
-
-| Phase | id | agent | 规范 | 产物 |
-|-------|-----|-------|------|------|
-| 1. State Read | `state-read` | — | `docs-sync-state.md` | `docs-sync-state.json` |
-| 2. Diff Collect | `diff-collect` | `agents/docs-diff-agent.md` | `docs-sync-diff.md` | `docs-sync-report.md` |
-| 3. Knowledge Extract | `knowledge-extract` | — | `knowledge-extract.md` | `docs-sync-report.md` |
-| 4. Asset Audit & Update | `asset-audit-update` | `agents/docs-update-agent.md` | `docs-sync-update.md` | `docs-sync-report.md` |
-| 5. State Write | `state-write` | `agents/docs-update-agent.md` | `docs-sync-finish.md` | `docs-sync-state.json` |
-
-### 1. State Read — 读取同步状态
-- id：`state-read`
-- 规范：`docs-sync-state.md`
-- 模板：`../_templates/docs-sync-state-template.json`
-- 产物：`speculo/.speculo/dev/docs-sync-state.json`
-- 完成准则：
-  - 已确定 `LAST_SYNC_SHA` 和 `HEAD_SHA`
-  - v1 state 已迁移或已明确阻塞
-  - 首次空 state 已进入 `bootstrap` 模式，并已生成首批 `tracked_assets` 候选与初始化范围
-
-### 2. Diff Collect — 收集 git 差异
-- id：`diff-collect`
-- 规范：`docs-sync-diff.md`
-- 模板：无
-- 产物：`docs-sync-report.md`
-- 完成准则：
-  - 常规同步已记录 git log、name-status、shortstat、路径分组和 archive/.config 相关 diff
-  - `bootstrap` 模式下已完成项目文件、元数据、命令、入口、文档缺口和 `.config` 的全量盘点
-  - 已判断哪些资产需要新增、删除、修改或保留
-
-### 3. Knowledge Extract — 归档知识沉淀
-- id：`knowledge-extract`
-- 规范：`knowledge-extract.md`
-- 模板：`../_templates/docs-sync-report-template.md`
-- 产物：`docs-sync-report.md`
-- 完成准则：
-  - 已读取本次范围内新增/变更的 archive 高信号产物
-  - 已把归档中的决策、术语、规则、经验和文档漂移信号映射到 tracked assets
-  - 不确定或多语义项已转交 `../M-domain-modeling/M-domain-modeling.md` 或标记为待确认
-
-### 4. Asset Audit & Update — 审计并差量更新资产
-- id：`asset-audit-update`
-- 规范：`docs-sync-update.md`
-- 模板：`../_templates/docs-sync-report-template.md`
-- 产物：`docs-sync-report.md`
-- 完成准则：
-  - 常规同步只修改 `tracked_assets` 中需要同步的资产；`bootstrap` 模式可先把推导出的基础文档纳入 `tracked_assets` 并创建缺失资产
-  - README / CHANGELOG / AGENTS 类文档遵守对应 contract
-  - `.config` 资产遵守 `config-contract.md`
-  - ADR / CONTEXT 语义不稳定时已调用 `../M-domain-modeling/M-domain-modeling.md`
-  - `docs-sync-report.md` 无残留 `[TODO:]`
-
-### 5. State Write — 验证与写回状态
-- id：`state-write`
-- 规范：`docs-sync-finish.md`
-- 模板：`../_templates/docs-sync-report-template.md`
-- 产物：`speculo/.speculo/dev/docs-sync-state.json`
-- 完成准则：
-  - 已运行项目级校验或记录无法运行原因
-  - state 已原子写入
-  - 已向用户报告范围、改动资产和新基线
-
-## 依赖
-
-- 软依赖：`../M-domain-modeling/M-domain-modeling.md`，用于不稳定术语、上下文边界和 ADR 候选确认
-- 硬依赖：git 仓库；首次空 state 默认执行 `bootstrap` 文档初始化。写入 `RULES.md`、删除 `.config` 文件或确认不稳定术语/ADR 时，仍需要用户明确确认
-
-## 状态扩展字段
-
-本工作流需在同 change 的 `.status.json` 追加：
-
-- `dev_entry` (string) — 固定为 `dev/D`
-- `docs_sync_state_path` (string) — 固定为 `speculo/.speculo/dev/docs-sync-state.json`
-- `docs_sync_range` (string) — 常规同步为 `<LAST_SYNC_SHA>..HEAD`，`bootstrap` 模式为 `<bootstrap>..HEAD`
-- `tracked_assets` (array) — 本次纳入同步的文档和 `.config` 资产
-- `synced_assets` (array) — 本次实际修改的资产
-- `archive_sources` (array) — 本次读取的归档产物路径
-- `config_audit_status` (none | proposed | confirmed | updated | blocked) — `.config` 审计/写入状态
-- `docs_sync_status` (bootstrap | first-run | no-op | extracting | updating | synced | blocked) — 同步状态
-
-## 完成与状态更新
-
-- 进入每个 phase 时更新 `current_phase` 和 `phase_history`。
-- 只有验证完成后才原子写回 `speculo/.speculo/dev/docs-sync-state.json`。
-- 本 workflow 不自动完成 change；同步完成后仅更新 `docs_sync_status` 等扩展字段。需要收尾时移交 `../04-finalize/04-finalize.md`；不得自行写入 `change_status: completed`。

package/template/workflows/dev/D-docs-sync/agents/docs-diff-agent.md

@@ -1,34 +0,0 @@
----
-id: dev/D-docs-sync/docs-diff-agent
-type: agent
-name: Docs Diff Agent
-description: 隔离执行 State Read 与 Diff Collect phase：读取同步状态并收集 git 差异
----
-
-## 使命
-
-读取 docs-sync state，收集 git 差异与 bootstrap 盘点结果，初始化 `docs-sync-report.md`。
-
-## 输入契约
-
-- change 路径：`speculo/.speculo/dev/<change>/`
-- `current_phase` / phase-id：`diff-collect`（承接 `state-read` 完成后）
-- 全局 state：`speculo/.speculo/dev/docs-sync-state.json`
-- 规范：`../docs-sync-state.md`、`../docs-sync-diff.md`
-
-## 执行规范
-
-- 先按 `../docs-sync-state.md` 确定 `LAST_SYNC_SHA`、`HEAD_SHA` 与 bootstrap 模式。
-- 再按 `../docs-sync-diff.md` 收集 git log、name-status、路径分组。
-- bootstrap 模式执行全量项目盘点。
-- 报告写入 `speculo/.speculo/dev/<change>/docs-sync-report.md`。
-
-## 产物与状态
-
-- 产物：`docs-sync-report.md`（diff 段）
-- `.status.json`：更新 `docs_sync_range`、`docs_sync_status`
-
-## 边界
-
-- 不修改 tracked assets 正文；不写回 docs-sync state。
-- 不写 `change_status`。

package/template/workflows/dev/D-docs-sync/agents/docs-update-agent.md

@@ -1,34 +0,0 @@
----
-id: dev/D-docs-sync/docs-update-agent
-type: agent
-name: Docs Update Agent
-description: 隔离执行 Knowledge Extract、Asset Audit & Update 与 State Write phase
----
-
-## 使命
-
-从归档提取知识、差量更新 tracked assets、验证后原子写回 docs-sync state。
-
-## 输入契约
-
-- change 路径：`speculo/.speculo/dev/<change>/`
-- `current_phase` / phase-id：`asset-audit-update` 或 `state-write`
-- 上游产物：`docs-sync-report.md`（diff 段已完成）
-- 规范：`../knowledge-extract.md`、`../docs-sync-update.md`、`../docs-sync-finish.md`
-- 契约：`../readme-contract.md`、`../agents-contract.md`、`../changelog-contract.md`、`../config-contract.md`
-
-## 执行规范
-
-- 按 `../knowledge-extract.md` 读取 archive 高信号产物。
-- 按 `../docs-sync-update.md` 差量更新 tracked assets；术语不稳定时转交 `../../M-domain-modeling/M-domain-modeling.md`。
-- 按 `../docs-sync-finish.md` 验证并原子写回 `speculo/.speculo/dev/docs-sync-state.json`。
-
-## 产物与状态
-
-- 产物：`docs-sync-report.md`（完整）、更新后的 tracked assets、`docs-sync-state.json`
-- `.status.json`：更新 `synced_assets`、`config_audit_status`、`docs_sync_status: synced`
-
-## 边界
-
-- RULES.md 删除或改写须用户确认。
-- 不写 `change_status`；需要收尾时移交 `../../04-finalize/04-finalize.md`。