@namewta/speculo 0.8.4 → 0.8.5

package/package.json

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

package/template/.speculo/README.md

@@ -15,12 +15,13 @@
 ## 读取顺序
 
 1. 读取 `workspace.json`，以当前打开项目为 `project_root` 解析公共 roots。
-2. 从 `../workflows/<workflow>/INDEX.md` 进入 workflow，再通过 `<Path>` 指针进入具体 work 入口文件。
-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 更新范围。
+2. 从 `../workflows/<workflow>/INDEX.md` 发现 workflow并按需读取其中声明的永久知识；这一步不读取 Work 条目或运行状态。
+3. 用户明确激活 workflow 或 work 后，读取 INDEX 指向的 workflow 根 `README.md`，从其中的 Work 条目选择目标并读取具体入口文件。
+4. 按激活合同读取 `<Path>{roots.state}/{workflow}/status.json</Path>`，再读取 `<Path>{roots.state}/{workflow}/changes/{change}/.status.json</Path>` 和当前 work 产物。
+5. 历史 change 只从 `<Path>{roots.state}/{workflow}/archive/{YYYY-MM}/{change}/</Path>` 读取。
+6. Command 报告位于 `<Path>{roots.state}/commands/{command}/*.md</Path>`，command state 位于 `<Path>{roots.state}/commands/{command}/state.json</Path>`。
+7. 独立 Skill 的运行记录位于 `<Path>{roots.state}/skills/{skill}/</Path>`，根级 `state.json` 仅在该 Skill 声明持久 checkpoint 时读取。
+8. 首次 docs-sync 确认后读取 `<Path>{roots.state}/{workflow}/docs-sync.json</Path>`；它分列该 workflow 的项目文档和私有 state 更新范围。
 
 ## 写入边界
 

package/template/workflows/specdev/A-archive-and-consolidate/A-archive-and-consolidate.md

@@ -9,6 +9,8 @@ keywords: [归档, consolidation, ADR, context, research, knowledge, 代码库
 
 # 归档与沉淀
 
+> 激活本 Work 后，先读取 `<Path>{roots.workflows}/specdev/README.md</Path>`，再执行本入口。
+
 A 是 SpecDev 的归档 wrapper：它拥有模式选择、SpecDev 完成门和代码访谈；机械扫描、dry-run、知识毕业、合并、清理、移动与重读由 `<Path>{roots.skills}/archive-and-consolidate/SKILL.md</Path>` 单一维护。
 
 ## 模式

package/template/workflows/specdev/C-code-review/C-code-review.md

@@ -9,6 +9,8 @@ keywords: [code-review, review, diff, fixed-point, PR, 标准, 规范]
 
 # 代码审查
 
+> 激活本 Work 后，先读取 `<Path>{roots.workflows}/specdev/README.md</Path>`，再执行本入口。
+
 C 是独立 review 入口，不实施修复。它拥有 `<Path>{roots.state}/specdev/changes/{change}/reviews/</Path>`；I 的最终审查由 I 写入 Evidence，不写本目录。
 
 ## 输入

package/template/workflows/specdev/D-diagnose-bugs/D-diagnose-bugs.md

@@ -9,6 +9,8 @@ keywords: [bug, 诊断, 红灯, tight-loop, 根因, 复现, 假设]
 
 # 诊断 Bug
 
+> 激活本 Work 后，先读取 `<Path>{roots.workflows}/specdev/README.md</Path>`，再执行本入口。
+
 D 的主导词是**红灯**：没有一条已执行且能在此 bug 上变红的紧凑命令，就没有可进入的假设阶段。D 默认只读项目代码，可以创建 change 诊断工件和经授权的临时可撤销探针；生产修复由 Implement 拥有。
 
 ## 输入与所有权

package/template/workflows/specdev/E-eli5/E-eli5.md

@@ -8,6 +8,8 @@ keywords: [eli5, 零基础, 大一新生, Markdown, ASCII]
 ---
 # ELI5：给零基础新生的图解
 
+> 激活本 Work 后，先读取 `<Path>{roots.workflows}/specdev/README.md</Path>`，再执行本入口。
+
 ## 读者与职责
 
 读者是刚入大学、没有专业背景（零专业背景）的新生。读者能理解日常因果和简单流程，但不应被假定知道代码、网络、数学或行业背景。
@@ -77,7 +79,7 @@ ASCII 全图 + 分步图 + 简短说明
 
 ## 执行
 
-1. 读取 `<Path>{roots.workflows}/specdev/INDEX.md</Path>`、全局状态和当前 change 状态。选择用户指定或唯一活跃的 change；没有时按 SpecDev 启动协议创建。`current_work` 为空时设为 `specdev/eli5`；若指向其他 Work，先完成显式交接。
+1. 按 `<Path>{roots.workflows}/specdev/README.md</Path>` 读取全局状态和当前 change 状态。选择用户指定或唯一活跃的 change；没有时按 SpecDev 启动协议创建。`current_work` 为空时设为 `specdev/eli5`；若指向其他 Work，先完成显式交接。
 2. 将调用中的 `$ARGUMENTS` 解析为主题；直接提出的图解请求以用户最新消息为主题。主题缺失时只询问主题，不猜测。先写下读者要带走的三个答案：它是什么、为什么需要它、它怎样流动或被调用。
 3. 按需读取当前 change 工件、项目事实和可靠来源。区分已验证事实、便于理解的类比和未知处；类比只能帮助理解，不能替代事实或掩盖边界。
 4. 先画 `先看全图`，再按实际关系补充结构图、数据流图、调用流图或状态变化图。每张图旁只用短句解释箭头；避免长段落、术语堆叠、缩写和先备知识。

package/template/workflows/specdev/E-engineering-cognitive-mentor/E-engineering-cognitive-mentor.md

@@ -9,6 +9,8 @@ keywords: [认知导师, 教学, why, bug, 源码研究, 技术方案, 架构,
 
 # 工程认知导师
 
+> 激活本 Work 后，先读取 `<Path>{roots.workflows}/specdev/README.md</Path>`，再执行本入口。
+
 本 Work 将工程研究从“一次性答案”转化为可恢复、可追溯、可继续讨论的认知过程。它负责解释、教学、建议、证据组织、方案比较和理解确认，不负责替用户实施工程变更。
 
 核心闭环：

package/template/workflows/specdev/G-grill-with-docs/G-grill-with-docs.md

@@ -9,6 +9,8 @@ keywords: [设计访谈, grilling, design-tree, frontier, ADR, LOG, CONTEXT, 决
 
 # 设计访谈（带文档）
 
+> 激活本 Work 后，先读取 `<Path>{roots.workflows}/specdev/README.md</Path>`，再执行本入口。
+
 不留情面地访谈用户，直到达成共识。把这件事映射为一棵**设计树（design tree）**：每个决策都会分出挂在它下面的后续决策。
 
 按**轮次**推进这棵树。**前沿（frontier）** 是所有前置条件已经确定的决策——那些现在就能问、不必猜测尚未得到答案的问题。每轮询问完整 frontier；用户的答案会重塑设计树并解除下一层问题的阻塞。

package/template/workflows/specdev/I-implement/I-implement.md

@@ -9,6 +9,8 @@ keywords: [实现, TDD, Lead, subagent, worktree, current workspace, direct-pare
 
 # 实现
 
+> 激活本 Work 后，先读取 `<Path>{roots.workflows}/specdev/README.md</Path>`，再执行本入口。
+
 本 work 保留模块设计检查、design-it-twice、TDD 红绿循环、双轴审查和证据治理。Ticket 模式按 Goal Plan 的 `ticket_workspace_policy` 选择 current workspace 串行直接父分支或独立 worktree candidate-merge；Lead 根据实际情况自行实现或动态派单。
 
 ## 执行模式

package/template/workflows/specdev/I-init-setup/I-init-setup.md

@@ -9,11 +9,13 @@ keywords: [初始化, 配置, status, tracking, 验证命令]
 
 # 初始化设置
 
+> 激活本 Work 后，先读取 `<Path>{roots.workflows}/specdev/README.md</Path>`，再执行本入口。
+
 首次使用 SpecDev、状态根不存在或治理契约发生变化后运行。此 work 只初始化 SpecDev 的状态与配置，不修改项目业务代码。
 
 ## 规范输入
 
-- 工作流总览：`<Path>{roots.workflows}/specdev/INDEX.md</Path>`
+- 工作流运行合同：`<Path>{roots.workflows}/specdev/README.md</Path>`
 - 路径引用契约：`<Path>{roots.workflows}/specdev/common/rules/path-reference-contract.md</Path>`
 - 配置模板：`<Path>{roots.workflows}/specdev/I-init-setup/config-template.json</Path>`
 - 配置 Schema：`<Path>{roots.workflows}/specdev/common/schemas/config.schema.json</Path>`

package/template/workflows/specdev/INDEX.md

@@ -7,250 +7,18 @@ description: 以本地工件为唯一开发权威，从来源冻结、诊断、
 keywords: [specdev, local-first, 规格驱动开发, decision-complete, eli5, prototype, code-review, TDD, 证据]
 ---
 
-# SpecDev Workflow
+# SpecDev Index
 
-SpecDev 将“理解、决定、规划、执行、验证、沉淀”拆成职责清晰的工件链。目标不是让文档尽可能长，而是让每一层拥有明确权威，并让后续模型无需重新决定前一层已经锁定的事项。
+本索引用于发现 SpecDev，并让未激活 SpecDev 的会话按需取得项目已经沉淀的长期知识。
 
-## 运行时根
+## 永久知识
 
-- 工作流根：`<Path>{roots.workflows}/specdev/</Path>`
-- 状态根：`<Path>{roots.state}/specdev/</Path>`
+读取本索引时，只把与当前请求相关且已经存在的内容作为只读背景；不存在的路径静默跳过：
 
-任何具体文件或目录引用必须遵守 `<Path>{roots.workflows}/specdev/common/rules/path-reference-contract.md</Path>`。禁止内部相对链接、裸文件名和机器绝对路径。
-
-## 工件链
-
-```text
-远程 Issue、指定内容或对话
-        ↓
-Triage 冻结为本地 Source
-        ↓
-Diagnose / Grill / ELI5 / Wayfinder / Prototype / Code Review / Architecture Review
-        ↓
-Spec             外部行为、范围、验收合同与关键约束
-        ↓
-Ticket           单一垂直切片的决策完备微计划
-        ↓
-Tickets Map      DAG、合同覆盖、Ready 与并行投影
-        ↓
-Goal Plan        仅在需要时编排跨 Ticket Gate、Wave、owner 与恢复
-        ↓
-Implement        在既定契约内设计、TDD、审查、验证和交接
-        ↓
-Evidence         实际修改、命令、结果、偏差和残余风险
-        ↓
-Triage           本地完成后按确认回写/关闭支持的远程 Issue
-        ↓
-Archive          归档历史并将经验证知识提升为当前长期知识
-```
-
-核心状态工件：
-
-- `<Path>{roots.state}/specdev/changes/{change}/source.md</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/triage.md</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/ticket/</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/design-tree.json</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/wayfinder-map.md</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/investigation/</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/evidence/</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/reviews/</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/prototypes/</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/questionnaires/</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/eli_index.md</Path>` 与 `<Path>{roots.state}/specdev/changes/{change}/<number>_<topic>.md</Path>`
-
-工件职责和冲突裁决位于 `<Path>{roots.workflows}/specdev/common/rules/artifact-contract.md</Path>`。
-
-## 持久化约定
-
-`speculo init` 创建固定状态骨架：
-
-- 全局状态：`<Path>{roots.state}/specdev/status.json</Path>`
-- 活跃 change：`<Path>{roots.state}/specdev/changes/</Path>`
-- 历史归档：`<Path>{roots.state}/specdev/archive/</Path>`
-
-刷新时 CLI 依据 `<Path>{roots.workflows}/specdev/runtime-contract.json</Path>` 处理持久化数据：配置使用 baseline 三方合并，登记的状态 schema 使用显式 migrator，其他 runtime 文件按字节保留。只有字段删除或结构迁移时才在 `<Path>{roots.state}/back/</Path>` 写入 targeted backup；冲突在替换 active 安装前阻塞。`<Path>{roots.state}/back/</Path>`、`<Path>{roots.state}/install.json</Path>`、`<Path>{roots.state}/managed.json</Path>` 与 `<Path>{roots.state}/baselines/</Path>` 均不属于 SpecDev 写入 namespace。
-
-初始化设置 work 首次运行时生成配置并创建空的永久 namespace：
-
-- 全局配置：`<Path>{roots.state}/specdev/config.json</Path>`
-- 追踪规则：`<Path>{roots.state}/specdev/.config/tracking.md</Path>`
-- 领域布局：`<Path>{roots.state}/specdev/.config/domain-layout.md</Path>`
-- 永久 ADR：`<Path>{roots.state}/specdev/adr/</Path>`
+- 永久架构决策：`<Path>{roots.state}/specdev/adr/</Path>`
 - 永久领域上下文：`<Path>{roots.state}/specdev/context/</Path>`
 - 永久研究：`<Path>{roots.state}/specdev/research/</Path>`
 
-初始化只保证永久目录存在，不写知识内容。只有 A-archive-and-consolidate 在 change 完成、实现证据验证、毕业评估和用户确认后，才能创建、合并或改写这些永久 namespace 中的内容；其他 Works 只读。
-
-单个 change 可以包含：
-
-- `<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/source.md</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/triage.md</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/diagnosis.md</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/diagnostics/</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/design-tree.json</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/ticket/</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/wayfinder-map.md</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/investigation/</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/investigation/comments/</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/architecture-review.md</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/architecture-review.html</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/evidence/</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/reviews/</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/prototypes/</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/questionnaires/</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/eli_index.md</Path>` 与 `<Path>{roots.state}/specdev/changes/{change}/<number>_<topic>.md</Path>`
-
-## 全局治理原则
-
-1. **先发现、后询问**：仓库、配置、schema、测试和文档能回答的事实先探索；只询问真正影响行为、架构、风险、范围、迁移或验收的偏好。
-2. **规划深度随风险增长**：Lite、Standard、Deep 由复杂度和事故半径决定，不由文档长度决定。
-3. **Ticket 是微型计划**：每个 Ready Ticket 决策完备，但不展开逐行代码。
-4. **Goal Plan 按需出现**：只在跨 Ticket 编排复杂度需要时生成，不以固定章节数量作为质量标准。
-5. **证据优先**：每个验收合同、Ticket 和 Gate 都必须有可重复验证与 Evidence。
-6. **路径所有权**：并发实现者只能修改授权项目路径；shared path 有唯一 owner。
-7. **偏差显式化**：计划与事实冲突时停止、记录、修订，不静默扩大范围或改写契约。
-8. **状态单一来源**：Ticket frontmatter 是单 Ticket 状态权威；Map 和 Goal Plan 是投影与编排。
-9. **知识以当前真相为目标**：归档保留历史，永久知识只保留仍真实且经实现验证的结论。
-10. **恢复依赖权威工件**：跨 Work 或 Agent 边界时同步 active change 的 `current_work`，成功完成后去重更新 `works_run`，返回下一 Work 和权威工件的完整路径。
-11. **本地执行权威**：远程 Issue/PR/URL 只作为来源或完成投影；Spec、Ticket、Map、Goal Plan、Evidence 和状态始终以本地工件为准。
-12. **完成与归档分离**：本地完成按 change completion 合同决定；远程 close 失败不回滚完成，但必须 reconcile 或 waive 后才归档。
-13. **Lead 与隔离正交**：Lead 固定拥有 SpecDev 状态、Evidence 与父分支；是否派遣 subagent 由 Lead 动态决定。Goal Plan 创建时询问 Ticket 是否开启 worktree，默认不开启；选择只作用于当前 Goal Plan。
-14. **策略化验收**：current 模式使用当前 workspace 严格串行、direct-parent 验证；required 模式使用 source worktree 与 parent-candidate。只有 required 模式创建独立 Ticket worktree。
-
-共享规则：
-
-- `<Path>{roots.workflows}/specdev/common/rules/planning-principles.md</Path>`
-- `<Path>{roots.workflows}/specdev/common/rules/artifact-contract.md</Path>`
-- `<Path>{roots.workflows}/specdev/common/rules/readiness-and-depth.md</Path>`
-- `<Path>{roots.workflows}/specdev/common/rules/path-ownership.md</Path>`
-- `<Path>{roots.workflows}/specdev/common/rules/evidence-and-verification.md</Path>`
-- `<Path>{roots.workflows}/specdev/common/rules/deviation-control.md</Path>`
-- `<Path>{roots.workflows}/specdev/common/rules/path-reference-contract.md</Path>`
-- `<Path>{roots.workflows}/specdev/common/rules/codebase-design.md</Path>`
-- `<Path>{roots.workflows}/specdev/common/rules/change-completion.md</Path>`
-
-## 启动协议
-
-1. 解析 workflow 和 state roots。
-2. 读取 `<Path>{roots.state}/specdev/config.json</Path>`；不存在时运行 `<Path>{roots.workflows}/specdev/I-init-setup/I-init-setup.md</Path>`。
-3. 读取 `<Path>{roots.state}/specdev/status.json</Path>`：用户指定 change 优先；唯一活跃 change 直接使用；无活跃时创建；多个候选时请求消歧。
-4. 若当前 change 已有非空 `current_work`，先恢复或显式结束该 Work；否则将 `current_work` 设置为本次 work id。
-5. 只加载当前步骤需要的 work 子文件和共享规则。
-6. 完成后写入产物、运行适用校验、更新状态和 `works_run`。
-
-Change 从 active/blocked 转为 completed 时加载 `<Path>{roots.workflows}/specdev/common/rules/change-completion.md</Path>`：有 Goal Plan 时由其中唯一 Lead 拥有转换；无 Goal Plan 的 Ticket/Direct Spec 由当前 I owner 拥有；非实现型终点由最终验收工件 owner 拥有。Archive 不补造 completed。
-
-## 状态字段
-
-`<Path>{roots.state}/specdev/status.json</Path>` 使用全局 schema v5；Spec/Ticket/Tickets Map 继续使用各自 schema v3，config 使用 schema v5，Goal Plan 使用 schema v6，`<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>` 使用 schema v6：
-
-- `schema_version`（数字）：全局状态 schema 版本，固定为 `4`。
-- `workflow`（字符串）：workflow 标识，固定为 `"specdev"`。
-- `active`（对象数组）：当前活跃 change；每项包含：
-  - `change`（字符串）：change 目录名，格式 `"YYYY-MM-DD-<kebab-topic>"`。
-  - `current_work`（字符串或 null）：当前 work id，如 `"specdev/implement"`；无运行中 work 时为 null。
-  - `works_run`（去重字符串数组）：已成功完成的 work id；重复运行同一 work 不追加副本。
-  - `claimed_investigations`（对象数组，可选）：并行调查领取记录；每项包含 `id`、`owner`、可选 `session` 和 `claimed_at`。
-- `archived`（去重字符串数组）：已归档 change 名称。详细归档时间、路径和 promotion 摘要只存在于 `<Path>{roots.state}/specdev/archive/YYYY-MM/{change}/.status.json</Path>`。
-
-`active[].change` 必须唯一，且不得同时出现在 `archived`。开始 Work 时设置 `current_work`；暂停或可恢复阻塞时保留；成功完成时加入 `works_run` 并清空；取消时清空但不加入。逐次时间、结果和审计证据由 change 自有状态、Work 主产物、Evidence 或 LOG 承载，不写入全局索引。
-
-`<Path>{roots.state}/specdev/config.json</Path>` 的 `execution.max_implementation_agents`、`max_integration_attempts` 和 planning 原型变体字段均为可配置正整数，初始化时写入默认值；仅 implementation subagent 受前者约束且不含 Lead，current workspace 仍保持单 writer 串行安全不变量；只读 review/research/test-observation agent 不设 SpecDev 数字上限。
-
-`<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>` 的 `worktrees` 保存 Ticket 级 `base_sha`、父分支、workspace/implementation/integration owner、workspace locator、implementation/source checkpoint、适用 candidate/result SHA、验证、E2E disposition 与生命周期状态。current 记录使用 `workspace_ref=current` 和 direct-parent；required 记录使用 source/parent-candidate。每个实现 Ticket 都有一条记录；父分支只有在对应策略的验证通过后推进。`removed` 是 required 集成后来源 branch/worktree 完成清理的终态，必须保留全部集成与 E2E 证据。
-
-领域状态枚举：
-
-- change：`active | blocked | completed | archived`
-- Ticket：`draft | ready | in_progress | blocked | review | done | deviated | cancelled`
-- Investigation status：`open | closed`
-- Investigation resolution：`answered | out-of-scope | superseded | cancelled | null`
-- Planning Depth：`lite | standard | deep`
-- Worktree：`planned | active | review | integrating | integrated | removed | blocked`
-
-## 路径分配
-
-1. workflow 运行状态写入 `<Path>{roots.state}/specdev/</Path>`。
-2. change 产物写入 `<Path>{roots.state}/specdev/changes/{change}/</Path>`。
-3. 项目代码、测试和用户要求的项目文档写入项目路径；Evidence 仅保存项目相对指针。
-4. 长期知识候选先在 change 内形成；只有 A 在完成证据、毕业评估和用户确认全部通过后，才提升到对应永久 namespace。
-
-## 副作用边界
-
-未经用户明确授权不得提交、推送、合并、删除来源 branch/worktree、部署、发布、移动归档、写入/关闭远程 Issue 或执行不可逆迁移。Ready Goal Plan/Ticket 执行必须明确取得 implementation commit 与所选 direct-parent/candidate integration/父分支更新授权；required 模式该授权包含 transient candidate checkout/branch 生命周期，不扩展到来源 cleanup、远端或生产动作。只读探索、change 工件生成和已授权验证可以进行。远程开发投影仅由 Triage reconcile 执行；Retro command 的 Speculo 反馈 Issue 是独立 command 边界。敏感值不得写入 `<Path>{roots.state}/specdev/</Path>`。
-
-## 场景路由
-
-| 场景 | 入口 | 正常出口 |
-|---|---|---|
-| 远程 Issue、URL、文件或对话摄入 | T-triage intake | D / G / W / P / S / C / T |
-| 本地 change 完成且来源可关闭 | T-triage reconcile | A |
-| 疑难 bug 或性能回归 | D-diagnose-bugs | S / T / I / R / W |
-| 模糊但可通过决策访谈收敛 | G-grill-with-docs | P / S / T / W |
-| 需要向刚上大一、没有专业背景的读者做 Markdown 与 ASCII 图解 | E-eli5 | 返回用户 / 继续当前 change |
-| 路径超出单次上下文 | W-wayfinder | G / P / D / S / T |
-| 需要用代码回答逻辑/UI 问题 | P-prototype | G / S / T / I |
-| 固定点 diff、branch 或 PR review | C-code-review | completed / T / S / G |
-| 外部行为已清楚 | S-spec | T-tickets |
-| Ready Spec 需要垂直切片 | T-tickets | P-goal-plan / I |
-| 多 Ticket 协调 | P-goal-plan | I / Triage / A |
-| Ready 执行 | I-implement | Triage / A / blocked / deviation |
-| 架构健康扫描 | R-review-architecture | G / T |
-
-同 change 下一阶段需要当前一手推理且上下文健康时继续；切换 repo/person/harness 或旁路时使用 `<Path>{roots.commands}/handoff.md</Path>`；严格限定且可独立派单时使用 Dispatch Packet；其他长上下文以权威工件路径恢复。平台不支持 clear/compact 时不虚构操作。
-
-## Work 条目
-
-<!-- AUTO-INDEX-START -->
-
-- **A-archive-and-consolidate** — 归档与沉淀：校验本地完成与远程 reconcile 门，复用全局归档能力移动 completed change 并提升当前知识，或从代码访谈形成可归档知识 change。
-- **C-code-review** — 代码审查：将 commit、branch、tag、merge-base 或 PR 解析为本地不可变固定点，执行隔离的标准轴与规范轴审查并持久化可恢复报告。
-- **D-diagnose-bugs** — 诊断 Bug：先建立会在精确症状上变红的紧凑反馈回路，再通过最小化、排名假设和单变量探针确认根因，输出修复契约而不实施生产修复。
-- **E-eli5** — 零基础新生解释：面向刚上大一、没有专业背景的读者解释一个主题；用 Markdown 和 ASCII 图解说明概念、数据与调用如何流动。
-- **E-engineering-cognitive-mentor** — 工程认知导师：面向 Bug、项目源码、需求技术方案、架构设计与陌生技术领域的非执行型认知指导 Work；以证据、因果 Why、候选方案对比和逐轮澄清帮助用户形成可复述理解，并将完整问答轨迹持续持久化到当前 change。
-- **G-grill-with-docs** — 设计访谈（带文档）：以完整 frontier 逐轮推进设计树，直到每个决策分支都已关闭并获得用户共识，同时持续维护当前 change 的设计树、日志、领域上下文和架构决策。
-- **I-implement** — 实现：基于 Ready Ticket 或获批小型 Spec 执行设计检查、TDD、动态派单、双轴审查、按 Goal Plan 选择的 current workspace 或 Ticket worktree 提交、直接父分支或候选合并验证和 Lead Evidence 回写。
-- **I-init-setup** — 初始化设置：初始化 SpecDev 的语言、配置、全局状态、本地 change 追踪、领域知识布局、验证命令和并发治理。
-- **P-goal-plan** — 目标规划：在跨 Ticket 协调复杂度需要时，以固定 Lead、动态派单、DAG/Gate 和候选合并门禁生成决策完备且可恢复的执行计划。
-- **P-prototype** — 原型：在获授权的临时 branch/worktree 中构建一次性 Logic 或 UI 原型，回答一个明确设计问题并持久化答案、资产定位和清理状态。
-- **R-review-architecture** — 架构审查：从用户指定范围或 Git 热点扫描代码库的深化机会，以持久化可视化 HTML 呈现候选，并对用户选择的一个方案运行设计树访谈。
-- **S-spec** — 编写 Spec：综合已知事实、设计决定、诊断与代码现状，产出以外部行为和验收合同为权威的 Ready Spec。
-- **T-tickets** — 拆分 Tickets：将 Spec、计划或已确认对话拆成曳光弹式垂直切片；每个 Ticket 决策完备、可独立验证、适配单一上下文，并建立阻塞 DAG、路径所有权和执行就绪门禁。
-- **T-triage** — 请求分诊：把远程 Issue、URL、文件或对话冻结为本地来源工件，完成风险分诊与路由，并在本地 change 完成后受控回写和关闭支持的远程 Issue。
-- **W-wayfinder** — 寻路：为超出单次会话且路径尚不可见的工作建立本地共享地图，逐个解决 research、prototype、grilling 或 task Ticket，直到目的地路线决策完备。
-
-<!-- AUTO-INDEX-END -->
-
-## Common 目录
-
-- 总览：`<Path>{roots.workflows}/specdev/common/README.md</Path>`
-- Rules：`<Path>{roots.workflows}/specdev/common/rules/</Path>`
-- Schemas：`<Path>{roots.workflows}/specdev/common/schemas/</Path>`
-- Tools：`<Path>{roots.workflows}/specdev/common/tools/</Path>`
-- Skills：`<Path>{roots.workflows}/specdev/common/skills/</Path>`
-
-## 自动校验
-
-校验一个 change：
-
-```bash
-node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> \
-  --stage <triage|diagnosis|grill|eli5|spec|tickets|goal-plan|implement|review|prototype|wayfinder|complete> \
-  <Path>{roots.state}/specdev/changes/{change}</Path>
-```
-
-校验工作流包：
+## Work 激活
 
-```bash
-node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> --self-check
-```
+用户明确激活 SpecDev 或其中某个 Work 后，读取 `<Path>{roots.workflows}/specdev/README.md</Path>` 取得 Work 条目、启动、恢复、状态、所有权和副作用合同，再进入目标 Work。仅发现本索引或读取永久知识不加载该合同。

package/template/workflows/specdev/P-goal-plan/P-goal-plan.md

@@ -9,6 +9,8 @@ keywords: [目标规划, Lead, Subagent, DAG, Gate, Wave, worktree, candidate-me
 
 # 目标规划
 
+> 激活本 Work 后，先读取 `<Path>{roots.workflows}/specdev/README.md</Path>`，再执行本入口。
+
 Goal Plan 只拥有单个 Ticket 无法独立决定的事情：整体 Outcome、跨 Ticket 顺序与并发、共享所有权、里程碑 Gate、动态派单边界、父分支集成、迁移/发布顺序、偏差升级和恢复。Ticket 继续拥有局部实现合同。
 
 每次 Goal Plan 都采用 `lead-directed`：当前主会话是唯一 Lead，负责计划、SpecDev 状态、Evidence、派单、验收、父分支推进和最终回复。形成 Goal Plan 时必须询问是否开启 worktree 开发，默认不开启；选择写入当前 Goal Plan，不修改全局配置。不开启时 Ticket 严格串行，允许动态派遣 implementation subagent，但同一时间只有一个 implementation owner 可写当前 workspace；开启时沿用每 Ticket 独立 worktree 与 candidate-merge。

package/template/workflows/specdev/P-prototype/P-prototype.md

@@ -9,6 +9,8 @@ keywords: [prototype, 原型, logic, UI, variant, 一次性代码, 设计问题]
 
 # 原型
 
+> 激活本 Work 后，先读取 `<Path>{roots.workflows}/specdev/README.md</Path>`，再执行本入口。
+
 原型是**回答一个问题的一次性代码**。P 不交付生产实现，也不把原型代码提升到 main；它把答案和一手资料 locator 交给后续 G/S/Tickets/I。
 
 ## 输入与所有权

package/template/workflows/specdev/R-review-architecture/R-review-architecture.md

@@ -9,6 +9,8 @@ keywords: [architecture, review, module, interface, depth, seam, adapter, levera
 
 # 改善代码库架构
 
+> 激活本 Work 后，先读取 `<Path>{roots.workflows}/specdev/README.md</Path>`，再执行本入口。
+
 揭示架构摩擦，提出**深化机会**——将 shallow module 转变为 deep module 的重构。目标是可测试性和 AI 可导航性。
 
 本 work 基于项目领域模型，并建立在共享设计词汇之上：

package/template/workflows/specdev/README.md

@@ -0,0 +1,249 @@
+# SpecDev Activation Contract
+
+本合同只在用户明确激活 SpecDev Work 后读取。它定义所有 Works 共享的启动、恢复、状态、所有权、路由和验证规则；具体 Work 仍只加载当前步骤需要的分支文件与共享规则。
+
+SpecDev 将“理解、决定、规划、执行、验证、沉淀”拆成职责清晰的工件链。目标不是让文档尽可能长，而是让每一层拥有明确权威，并让后续模型无需重新决定前一层已经锁定的事项。
+
+## 运行时根
+
+- 工作流根：`<Path>{roots.workflows}/specdev/</Path>`
+- 状态根：`<Path>{roots.state}/specdev/</Path>`
+
+任何具体文件或目录引用必须遵守 `<Path>{roots.workflows}/specdev/common/rules/path-reference-contract.md</Path>`。禁止内部相对链接、裸文件名和机器绝对路径。
+
+## 工件链
+
+```text
+远程 Issue、指定内容或对话
+        ↓
+Triage 冻结为本地 Source
+        ↓
+Diagnose / Grill / ELI5 / Wayfinder / Prototype / Code Review / Architecture Review
+        ↓
+Spec             外部行为、范围、验收合同与关键约束
+        ↓
+Ticket           单一垂直切片的决策完备微计划
+        ↓
+Tickets Map      DAG、合同覆盖、Ready 与并行投影
+        ↓
+Goal Plan        仅在需要时编排跨 Ticket Gate、Wave、owner 与恢复
+        ↓
+Implement        在既定契约内设计、TDD、审查、验证和交接
+        ↓
+Evidence         实际修改、命令、结果、偏差和残余风险
+        ↓
+Triage           本地完成后按确认回写/关闭支持的远程 Issue
+        ↓
+Archive          归档历史并将经验证知识提升为当前长期知识
+```
+
+核心状态工件：
+
+- `<Path>{roots.state}/specdev/changes/{change}/source.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/triage.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/ticket/</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/design-tree.json</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/wayfinder-map.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/investigation/</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/evidence/</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/reviews/</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/prototypes/</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/questionnaires/</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/eli_index.md</Path>` 与 `<Path>{roots.state}/specdev/changes/{change}/<number>_<topic>.md</Path>`
+
+工件职责和冲突裁决位于 `<Path>{roots.workflows}/specdev/common/rules/artifact-contract.md</Path>`。
+
+## 持久化约定
+
+`speculo init` 创建固定状态骨架：
+
+- 全局状态：`<Path>{roots.state}/specdev/status.json</Path>`
+- 活跃 change：`<Path>{roots.state}/specdev/changes/</Path>`
+- 历史归档：`<Path>{roots.state}/specdev/archive/</Path>`
+
+刷新时 CLI 依据 `<Path>{roots.workflows}/specdev/runtime-contract.json</Path>` 处理持久化数据：配置使用 baseline 三方合并，登记的状态 schema 使用显式 migrator，其他 runtime 文件按字节保留。只有字段删除或结构迁移时才在 `<Path>{roots.state}/back/</Path>` 写入 targeted backup；冲突在替换 active 安装前阻塞。`<Path>{roots.state}/back/</Path>`、`<Path>{roots.state}/install.json</Path>`、`<Path>{roots.state}/managed.json</Path>` 与 `<Path>{roots.state}/baselines/</Path>` 均不属于 SpecDev 写入 namespace。
+
+初始化设置 work 首次运行时生成配置并创建空的永久 namespace：
+
+- 全局配置：`<Path>{roots.state}/specdev/config.json</Path>`
+- 追踪规则：`<Path>{roots.state}/specdev/.config/tracking.md</Path>`
+- 领域布局：`<Path>{roots.state}/specdev/.config/domain-layout.md</Path>`
+- 永久 ADR：`<Path>{roots.state}/specdev/adr/</Path>`
+- 永久领域上下文：`<Path>{roots.state}/specdev/context/</Path>`
+- 永久研究：`<Path>{roots.state}/specdev/research/</Path>`
+
+初始化只保证永久目录存在，不写知识内容。只有 A-archive-and-consolidate 在 change 完成、实现证据验证、毕业评估和用户确认后，才能创建、合并或改写这些永久 namespace 中的内容；其他 Works 只读。
+
+单个 change 可以包含：
+
+- `<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/source.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/triage.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/diagnosis.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/diagnostics/</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/design-tree.json</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/ticket/</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/wayfinder-map.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/investigation/</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/investigation/comments/</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/architecture-review.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/architecture-review.html</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/evidence/</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/reviews/</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/prototypes/</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/questionnaires/</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/eli_index.md</Path>` 与 `<Path>{roots.state}/specdev/changes/{change}/<number>_<topic>.md</Path>`
+
+## 全局治理原则
+
+1. **先发现、后询问**：仓库、配置、schema、测试和文档能回答的事实先探索；只询问真正影响行为、架构、风险、范围、迁移或验收的偏好。
+2. **规划深度随风险增长**：Lite、Standard、Deep 由复杂度和事故半径决定，不由文档长度决定。
+3. **Ticket 是微型计划**：每个 Ready Ticket 决策完备，但不展开逐行代码。
+4. **Goal Plan 按需出现**：只在跨 Ticket 编排复杂度需要时生成，不以固定章节数量作为质量标准。
+5. **证据优先**：每个验收合同、Ticket 和 Gate 都必须有可重复验证与 Evidence。
+6. **路径所有权**：并发实现者只能修改授权项目路径；shared path 有唯一 owner。
+7. **偏差显式化**：计划与事实冲突时停止、记录、修订，不静默扩大范围或改写契约。
+8. **状态单一来源**：Ticket frontmatter 是单 Ticket 状态权威；Map 和 Goal Plan 是投影与编排。
+9. **知识以当前真相为目标**：归档保留历史，永久知识只保留仍真实且经实现验证的结论。
+10. **恢复依赖权威工件**：跨 Work 或 Agent 边界时同步 active change 的 `current_work`，成功完成后去重更新 `works_run`，返回下一 Work 和权威工件的完整路径。
+11. **本地执行权威**：远程 Issue/PR/URL 只作为来源或完成投影；Spec、Ticket、Map、Goal Plan、Evidence 和状态始终以本地工件为准。
+12. **完成与归档分离**：本地完成按 change completion 合同决定；远程 close 失败不回滚完成，但必须 reconcile 或 waive 后才归档。
+13. **Lead 与隔离正交**：Lead 固定拥有 SpecDev 状态、Evidence 与父分支；是否派遣 subagent 由 Lead 动态决定。Goal Plan 创建时询问 Ticket 是否开启 worktree，默认不开启；选择只作用于当前 Goal Plan。
+14. **策略化验收**：current 模式使用当前 workspace 严格串行、direct-parent 验证；required 模式使用 source worktree 与 parent-candidate。只有 required 模式创建独立 Ticket worktree。
+
+共享规则：
+
+- `<Path>{roots.workflows}/specdev/common/rules/planning-principles.md</Path>`
+- `<Path>{roots.workflows}/specdev/common/rules/artifact-contract.md</Path>`
+- `<Path>{roots.workflows}/specdev/common/rules/readiness-and-depth.md</Path>`
+- `<Path>{roots.workflows}/specdev/common/rules/path-ownership.md</Path>`
+- `<Path>{roots.workflows}/specdev/common/rules/evidence-and-verification.md</Path>`
+- `<Path>{roots.workflows}/specdev/common/rules/deviation-control.md</Path>`
+- `<Path>{roots.workflows}/specdev/common/rules/path-reference-contract.md</Path>`
+- `<Path>{roots.workflows}/specdev/common/rules/codebase-design.md</Path>`
+- `<Path>{roots.workflows}/specdev/common/rules/change-completion.md</Path>`
+
+## 启动协议
+
+1. 解析 workflow 和 state roots。
+2. 读取 `<Path>{roots.state}/specdev/config.json</Path>`；不存在时运行 `<Path>{roots.workflows}/specdev/I-init-setup/I-init-setup.md</Path>`。
+3. 读取 `<Path>{roots.state}/specdev/status.json</Path>`：用户指定 change 优先；唯一活跃 change 直接使用；无活跃时创建；多个候选时请求消歧。
+4. 若当前 change 已有非空 `current_work`，先恢复或显式结束该 Work；否则将 `current_work` 设置为本次 work id。
+5. 只加载当前步骤需要的 work 子文件和共享规则。
+6. 完成后写入产物、运行适用校验、更新状态和 `works_run`。
+
+Change 从 active/blocked 转为 completed 时加载 `<Path>{roots.workflows}/specdev/common/rules/change-completion.md</Path>`：有 Goal Plan 时由其中唯一 Lead 拥有转换；无 Goal Plan 的 Ticket/Direct Spec 由当前 I owner 拥有；非实现型终点由最终验收工件 owner 拥有。Archive 不补造 completed。
+
+## 状态字段
+
+`<Path>{roots.state}/specdev/status.json</Path>` 使用全局 schema v5；Spec/Ticket/Tickets Map 继续使用各自 schema v3，config 使用 schema v5，Goal Plan 使用 schema v6，`<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>` 使用 schema v6：
+
+- `schema_version`（数字）：全局状态 schema 版本，固定为 `5`。
+- `workflow`（字符串）：workflow 标识，固定为 `"specdev"`。
+- `active`（对象数组）：当前活跃 change；每项包含：
+  - `change`（字符串）：change 目录名，格式 `"YYYY-MM-DD-<kebab-topic>"`。
+  - `current_work`（字符串或 null）：当前 work id，如 `"specdev/implement"`；无运行中 work 时为 null。
+  - `works_run`（去重字符串数组）：已成功完成的 work id；重复运行同一 work 不追加副本。
+  - `claimed_investigations`（对象数组，可选）：并行调查领取记录；每项包含 `id`、`owner`、可选 `session` 和 `claimed_at`。
+- `archived`（去重字符串数组）：已归档 change 名称。详细归档时间、路径和 promotion 摘要只存在于 `<Path>{roots.state}/specdev/archive/YYYY-MM/{change}/.status.json</Path>`。
+
+`active[].change` 必须唯一，且不得同时出现在 `archived`。开始 Work 时设置 `current_work`；暂停或可恢复阻塞时保留；成功完成时加入 `works_run` 并清空；取消时清空但不加入。逐次时间、结果和审计证据由 change 自有状态、Work 主产物、Evidence 或 LOG 承载，不写入全局索引。
+
+`<Path>{roots.state}/specdev/config.json</Path>` 的 `execution.max_implementation_agents`、`max_integration_attempts` 和 planning 原型变体字段均为可配置正整数，初始化时写入默认值；仅 implementation subagent 受前者约束且不含 Lead，current workspace 仍保持单 writer 串行安全不变量；只读 review/research/test-observation agent 不设 SpecDev 数字上限。
+
+`<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>` 的 `worktrees` 保存 Ticket 级 `base_sha`、父分支、workspace/implementation/integration owner、workspace locator、implementation/source checkpoint、适用 candidate/result SHA、验证、E2E disposition 与生命周期状态。current 记录使用 `workspace_ref=current` 和 direct-parent；required 记录使用 source/parent-candidate。每个实现 Ticket 都有一条记录；父分支只有在对应策略的验证通过后推进。`removed` 是 required 集成后来源 branch/worktree 完成清理的终态，必须保留全部集成与 E2E 证据。
+
+领域状态枚举：
+
+- change：`active | blocked | completed | archived`
+- Ticket：`draft | ready | in_progress | blocked | review | done | deviated | cancelled`
+- Investigation status：`open | closed`
+- Investigation resolution：`answered | out-of-scope | superseded | cancelled | null`
+- Planning Depth：`lite | standard | deep`
+- Worktree：`planned | active | review | integrating | integrated | removed | blocked`
+
+## 路径分配
+
+1. workflow 运行状态写入 `<Path>{roots.state}/specdev/</Path>`。
+2. change 产物写入 `<Path>{roots.state}/specdev/changes/{change}/</Path>`。
+3. 项目代码、测试和用户要求的项目文档写入项目路径；Evidence 仅保存项目相对指针。
+4. 长期知识候选先在 change 内形成；只有 A 在完成证据、毕业评估和用户确认全部通过后，才提升到对应永久 namespace。
+
+## 副作用边界
+
+未经用户明确授权不得提交、推送、合并、删除来源 branch/worktree、部署、发布、移动归档、写入/关闭远程 Issue 或执行不可逆迁移。Ready Goal Plan/Ticket 执行必须明确取得 implementation commit 与所选 direct-parent/candidate integration/父分支更新授权；required 模式该授权包含 transient candidate checkout/branch 生命周期，不扩展到来源 cleanup、远端或生产动作。只读探索、change 工件生成和已授权验证可以进行。远程开发投影仅由 Triage reconcile 执行；Retro command 的 Speculo 反馈 Issue 是独立 command 边界。敏感值不得写入 `<Path>{roots.state}/specdev/</Path>`。
+
+## 场景路由
+
+| 场景 | 入口 | 正常出口 |
+|---|---|---|
+| 远程 Issue、URL、文件或对话摄入 | T-triage intake | D / G / W / P / S / C / T |
+| 本地 change 完成且来源可关闭 | T-triage reconcile | A |
+| 疑难 bug 或性能回归 | D-diagnose-bugs | S / T / I / R / W |
+| 模糊但可通过决策访谈收敛 | G-grill-with-docs | P / S / T / W |
+| 需要向刚上大一、没有专业背景的读者做 Markdown 与 ASCII 图解 | E-eli5 | 返回用户 / 继续当前 change |
+| 路径超出单次上下文 | W-wayfinder | G / P / D / S / T |
+| 需要用代码回答逻辑/UI 问题 | P-prototype | G / S / T / I |
+| 固定点 diff、branch 或 PR review | C-code-review | completed / T / S / G |
+| 外部行为已清楚 | S-spec | T-tickets |
+| Ready Spec 需要垂直切片 | T-tickets | P-goal-plan / I |
+| 多 Ticket 协调 | P-goal-plan | I / Triage / A |
+| Ready 执行 | I-implement | Triage / A / blocked / deviation |
+| 架构健康扫描 | R-review-architecture | G / T |
+
+同 change 下一阶段需要当前一手推理且上下文健康时继续；切换 repo/person/harness 或旁路时使用 `<Path>{roots.commands}/handoff.md</Path>`；严格限定且可独立派单时使用 Dispatch Packet；其他长上下文以权威工件路径恢复。平台不支持 clear/compact 时不虚构操作。
+
+## Work 条目
+
+<!-- AUTO-INDEX-START -->
+
+- **A-archive-and-consolidate** — 归档与沉淀：校验本地完成与远程 reconcile 门，复用全局归档能力移动 completed change 并提升当前知识，或从代码访谈形成可归档知识 change。
+- **C-code-review** — 代码审查：将 commit、branch、tag、merge-base 或 PR 解析为本地不可变固定点，执行隔离的标准轴与规范轴审查并持久化可恢复报告。
+- **D-diagnose-bugs** — 诊断 Bug：先建立会在精确症状上变红的紧凑反馈回路，再通过最小化、排名假设和单变量探针确认根因，输出修复契约而不实施生产修复。
+- **E-eli5** — 零基础新生解释：面向刚上大一、没有专业背景的读者解释一个主题；用 Markdown 和 ASCII 图解说明概念、数据与调用如何流动。
+- **E-engineering-cognitive-mentor** — 工程认知导师：面向 Bug、项目源码、需求技术方案、架构设计与陌生技术领域的非执行型认知指导 Work；以证据、因果 Why、候选方案对比和逐轮澄清帮助用户形成可复述理解，并将完整问答轨迹持续持久化到当前 change。
+- **G-grill-with-docs** — 设计访谈（带文档）：以完整 frontier 逐轮推进设计树，直到每个决策分支都已关闭并获得用户共识，同时持续维护当前 change 的设计树、日志、领域上下文和架构决策。
+- **I-implement** — 实现：基于 Ready Ticket 或获批小型 Spec 执行设计检查、TDD、动态派单、双轴审查、按 Goal Plan 选择的 current workspace 或 Ticket worktree 提交、直接父分支或候选合并验证和 Lead Evidence 回写。
+- **I-init-setup** — 初始化设置：初始化 SpecDev 的语言、配置、全局状态、本地 change 追踪、领域知识布局、验证命令和并发治理。
+- **P-goal-plan** — 目标规划：在跨 Ticket 协调复杂度需要时，以固定 Lead、动态派单、DAG/Gate 和候选合并门禁生成决策完备且可恢复的执行计划。
+- **P-prototype** — 原型：在获授权的临时 branch/worktree 中构建一次性 Logic 或 UI 原型，回答一个明确设计问题并持久化答案、资产定位和清理状态。
+- **R-review-architecture** — 架构审查：从用户指定范围或 Git 热点扫描代码库的深化机会，以持久化可视化 HTML 呈现候选，并对用户选择的一个方案运行设计树访谈。
+- **S-spec** — 编写 Spec：综合已知事实、设计决定、诊断与代码现状，产出以外部行为和验收合同为权威的 Ready Spec。
+- **T-tickets** — 拆分 Tickets：将 Spec、计划或已确认对话拆成曳光弹式垂直切片；每个 Ticket 决策完备、可独立验证、适配单一上下文，并建立阻塞 DAG、路径所有权和执行就绪门禁。
+- **T-triage** — 请求分诊：把远程 Issue、URL、文件或对话冻结为本地来源工件，完成风险分诊与路由，并在本地 change 完成后受控回写和关闭支持的远程 Issue。
+- **W-wayfinder** — 寻路：为超出单次会话且路径尚不可见的工作建立本地共享地图，逐个解决 research、prototype、grilling 或 task Ticket，直到目的地路线决策完备。
+
+<!-- AUTO-INDEX-END -->
+
+## Common 目录
+
+- 总览：`<Path>{roots.workflows}/specdev/common/README.md</Path>`
+- Rules：`<Path>{roots.workflows}/specdev/common/rules/</Path>`
+- Schemas：`<Path>{roots.workflows}/specdev/common/schemas/</Path>`
+- Tools：`<Path>{roots.workflows}/specdev/common/tools/</Path>`
+- Skills：`<Path>{roots.workflows}/specdev/common/skills/</Path>`
+
+## 自动校验
+
+校验一个 change：
+
+```bash
+node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> \
+  --stage <triage|diagnosis|grill|eli5|spec|tickets|goal-plan|implement|review|prototype|wayfinder|complete> \
+  <Path>{roots.state}/specdev/changes/{change}</Path>
+```
+
+校验工作流包：
+
+```bash
+node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> --self-check
+```

package/template/workflows/specdev/S-spec/S-spec.md

@@ -9,6 +9,8 @@ keywords: [spec, PRD, 用户故事, 验收合同, 接缝, 范围, readiness]
 
 # 编写 Spec
 
+> 激活本 Work 后，先读取 `<Path>{roots.workflows}/specdev/README.md</Path>`，再执行本入口。
+
 本 work 以“综合已有上下文”为主，不启动宽泛访谈。它保留原有的代码库探索、领域词汇、ADR 约束、测试接缝设计和用户确认能力，但将确认限制为真正影响外部行为或验证的高价值问题。
 
 Spec 决定“为什么、为谁、系统应表现为何”。它可以锁定影响公共接口、数据、兼容、安全或验收的实现约束，但不写逐文件施工计划。

package/template/workflows/specdev/T-tickets/T-tickets.md

@@ -9,6 +9,8 @@ keywords: [tickets, 拆分, 垂直切片, 阻塞, 曳光弹, decision-complete,
 
 # 拆分 Tickets
 
+> 激活本 Work 后，先读取 `<Path>{roots.workflows}/specdev/README.md</Path>`，再执行本入口。
+
 Ticket 是**决策完备的微型执行计划**：它消除执行者在目标、范围、公共契约、关键顺序和验收上的关键决策，但不展开逐行代码、局部变量或可从现有惯例自然推导的实现细节。
 
 本 work 保留原有能力：代码库探索、prefactor 识别、曳光弹垂直切片、真实阻塞边、用户粒度核对、宽重构的 expand-contract 排序、Ticket 独立文件和总体 Tickets Map。

package/template/workflows/specdev/T-triage/T-triage.md

@@ -9,6 +9,8 @@ keywords: [triage, 摄入, import, issue, reconcile, close, 风险, 路由]
 
 # 请求分诊
 
+> 激活本 Work 后，先读取 `<Path>{roots.workflows}/specdev/README.md</Path>`，再执行本入口。
+
 Triage 是 SpecDev 唯一的远程摄入与关闭边界。开发期间，`<Path>{roots.state}/specdev/changes/{change}/source.md</Path>`、`<Path>{roots.state}/specdev/changes/{change}/triage.md</Path>`、Spec、Ticket、Map、Goal Plan、Evidence 和状态文件是唯一权威；远程系统只保存原始请求以及经确认后的完成通知。
 
 ## 模式
@@ -18,7 +20,7 @@ Triage 是 SpecDev 唯一的远程摄入与关闭边界。开发期间，`<Path>
 
 ## 共同启动
 
-1. 解析 roots，读取 `<Path>{roots.workflows}/specdev/INDEX.md</Path>`、全局状态和 change 状态。
+1. 解析 roots，按 `<Path>{roots.workflows}/specdev/README.md</Path>` 读取全局状态和 change 状态。
 2. Intake 可以创建 change；reconcile 必须选择一个已存在的 completed change。
 3. 若该 change 的 `current_work` 为 null，设置为 `specdev/triage`；指向其他 Work 时先恢复或完成显式 handoff。
 4. 重读已有 `<Path>{roots.state}/specdev/changes/{change}/source.md</Path>` 与 `<Path>{roots.state}/specdev/changes/{change}/triage.md</Path>`，不覆盖已冻结的来源。

package/template/workflows/specdev/W-wayfinder/W-wayfinder.md

@@ -9,6 +9,8 @@ keywords: [wayfinder, 寻路, shared-map, research, prototype, grilling, task,
 
 # 寻路
 
+> 激活本 Work 后，先读取 `<Path>{roots.workflows}/specdev/README.md</Path>`，再执行本入口。
+
 一个模糊的想法出现了——太大而无法放入单个 Agent 会话，且从当前状态到**目的地**的路径尚不可见。寻路就是找到那条路，而非冲向目标。此 work 在 change state 中绘制一张**共享地图**，然后逐个处理其 Tickets，直到路径变得清晰。
 
 目的地可能是一份待移交和迭代的 Spec、一个在规划开始前需锁定的决策，或一项经说明允许在地图中完成的变更。命名目的地是第一步，它塑造每个 Ticket。