@namewta/speculo 1.0.18 → 1.0.19

package/template/workflows/specdev/I-implement/references/implementation-procedure.md

@@ -10,7 +10,7 @@
 
 ### Ticket 模式（默认）
 
-先读取 Tickets Map 的总体实施背景与项目 Skill 读取矩阵，再读取适用于 `ALL` 或当前 Ticket 的项目 Skill，随后读取 Ready Ticket、可选子 Goal Plan 和可选父 Implementation Plan。存在父 Plan 时使用其 Lead、workspace/integration 策略和全局门，即使子 Goal Plan 不存在也可以执行；两者都存在时必须策略一致。没有父 Plan 时沿用子 Goal Plan；两者都不存在时，当前主会话作为该 Ticket 的 Lead，并按 Direct Spec 规则执行，不推断 worktree 策略。`required` 模式每个 Ticket 建立独立 worktree；`current` 模式所有受同一计划约束的 Ticket 严格串行，使用当前分支和当前 workspace。
+使用下节规定的输入顺序。父 Implementation Plan 存在时采用其 Lead、workspace/integration 与全局 Gate，即使子 Goal Plan 不存在；两者都有时必须一致。没有父计划沿用子计划；两者都没有时当前主会话作为 Lead，按 Direct Spec 的轻量边界执行，不猜测 worktree 策略。
 
 ### Direct Spec 模式
 
@@ -51,17 +51,11 @@ Git 已处于 merge/rebase 冲突时，先加载 `<Path>{roots.workflows}/specde
 
 加载 `<Path>{roots.workflows}/specdev/I-implement/execution-preflight.md</Path>`。
 
-Ticket 模式：
+预检参考拥有 Ready、依赖证据、真实 Skill、计划版本、owner、权限、Git 状态与 workspace 的完整检查，不在此复写。
 
-1. 验证 Ready、依赖 Evidence、Spec/ADR/Goal Plan、一致性、路径 owner 和验证接缝；确认 Tickets Map 的总体实施背景、项目 Skill 矩阵、当前 Ticket 覆盖与实际文件均有效，并完成规定读取顺序；
-2. 确认子 Goal Plan schema v6（若存在）与父 Implementation Plan schema v1（若存在）、唯一 Lead、workspace 策略、动态 implementation/integration 上限与授权；
-3. `required` 模式以 `purpose=ticket, operation=create|restore` 调用 `<Path>{roots.workflows}/specdev/common/skills/dev-worktree/SKILL.md</Path>`；`current` 模式读取当前 branch、HEAD、dirty 状态并确认没有其他 Ticket implementation writer；
-4. Lead 把 Ticket 设为 `in_progress`；`required` 模式将 change worktree 记录设为 `active`，`current` 模式建立 current workspace 执行记录；
-5. 当前代码使合同失效时停止并返回对应上游 owner。
+通过预检后：`required` Ticket 以 `purpose=ticket, operation=create|restore` 调用 `<Path>{roots.workflows}/specdev/common/skills/dev-worktree/SKILL.md</Path>`；`current` Ticket 确认当前 branch/HEAD/dirty 状态和单 writer。Lead 设置 Ticket 为 `in_progress` 并按策略登记 active worktree 或 current workspace 记录。Direct Spec 不创建虚假 Ticket/worktree 状态。
 
-Direct Spec 模式验证用户批准、轻量合同和 current workspace 唯一写入 owner；不创建虚假 Ticket/worktree 状态。
-
-**完成标准**：按策略完成 workspace、基线、owners、权限与实际 Git 一致；current 模式只有一个 implementation writer 且 Ticket 串行可恢复。
+**完成标准**：真实 workspace、基线、唯一 owners 和授权与预检一致；代码使合同失效时停止并返回上游 owner，current Ticket 严格串行。
 
 ### 2. Lead 决定自行实现或动态派单
 
@@ -86,7 +80,7 @@ Ticket 模式下，Lead 根据 Ticket 独立性、路径冲突、上下文、风
 
 ### 4. TDD 红→绿垂直循环
 
-加载 `<Path>{roots.workflows}/specdev/I-implement/tdd-rules.md</Path>`、`<Path>{roots.workflows}/specdev/I-implement/tdd-test-design.md</Path>`、`<Path>{roots.workflows}/specdev/I-implement/tdd-mocking.md</Path>` 和 `<Path>{roots.workflows}/specdev/common/rules/code-commenting-rule.md</Path>`。对每个验收行为或关键风险：
+加载 `<Path>{roots.workflows}/specdev/I-implement/tdd-rules.md</Path>`、`<Path>{roots.workflows}/specdev/I-implement/tdd-test-design.md</Path>` 和 `<Path>{roots.workflows}/specdev/common/rules/code-commenting-rule.md</Path>`。对每个验收行为或关键风险：
 
 1. 选择公共接口或稳定接缝；
 2. 编写因目标行为缺失而失败的测试/验证并确认失败原因；
@@ -94,6 +88,8 @@ Ticket 模式下，Lead 根据 Ticket 独立性、路径冲突、上下文、风
 4. 运行定向非 E2E 验证；
 5. 保存 red/green 事实并进入下一条窄切片。
 
+涉及外部依赖、隔离策略或已有 Mock 时，先读取 `<Path>{roots.workflows}/specdev/I-implement/tdd-mocking.md</Path>`，再决定是否复用真实接缝或替身。
+
 不得删除测试、放宽断言、吞错、永久跳过或只验证 Mock 调用次数来制造绿色。
 
 新增或修改代码注释时，先判断信息能否由命名、类型或结构表达，并同步维护受行为变化影响的既有注释。
@@ -126,14 +122,7 @@ Direct Spec 模式由 Lead 在 current workspace 运行轻量合同要求的定
 
 ### 7. 最终集成与适用 E2E
 
-`required` Ticket 模式中，Lead 以 `purpose=ticket, operation=finalize` 调用 dev-worktree：
-
-1. 在最新父分支的 Lead-owned candidate checkout 组合 source commit；
-2. 运行受影响集成/回归、项目父状态检查和 Ticket 标记 required 的 E2E；
-3. candidate 失败时父分支不动，Ticket 回 `in_progress`/`blocked`；
-4. 父 HEAD 漂移时废弃本轮 candidate，基于最新父分支重建并重跑；
-5. 全部通过后父分支 fast-forward 到 candidate/result SHA；
-6. 重读父 HEAD/tree 和 ancestor 关系后，才允许 Ticket Done。
+`required` Ticket 模式中，Lead 以 `purpose=ticket, operation=finalize` 调用 dev-worktree，并读取 `<Path>{roots.workflows}/specdev/common/skills/dev-worktree/references/finalize.md</Path>`。该参考唯一维护最新父分支 candidate 的组合、检查、失败/漂移、重建、fast-forward、回读与尝试上限过程。验证失败或父 HEAD 漂移，父分支不推进；不能凭来源检查通过标记 Done。
 
 E2E 是否需要由 Ticket/Goal Plan 的实际跨边界风险决定，不限于 UI；不适用必须记录原因。
 
@@ -164,29 +153,6 @@ node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> \
 
 Ticket 模式返回 Ticket/change 状态、Evidence 完整路径、workspace locator、implementation/source、适用 candidate/result SHA、父分支、E2E disposition、适用 Lead 复盘决定、未验证项和下一路由。Direct Spec 返回 change 状态、`<Path>{roots.state}/specdev/changes/{change}/evidence/direct-spec.md</Path>`、current workspace、实施前/最终 checkpoint、适用 E2E 和下一路由。push、PR、remote merge、deploy、migration、生产动作及来源 branch/worktree cleanup 只在独立授权时执行。
 
-## 完成标准
-
-- Ticket 模式按策略完成 current workspace/direct-parent 或 worktree/implementation commit/candidate gate；Direct Spec 的轻量合同、current workspace checkpoint、双轴审查和最终验证完整；
-- current Ticket 的适用 E2E 由 Lead 在 current workspace 运行；required Ticket 的适用 E2E 由 Lead 在 parent-candidate 运行；Direct Spec 适用 E2E 由 Lead 在 current workspace 运行；
-- Lead 独立核对并写全部 SpecDev 工件；
-- Lead 与任何 implementation subagent 都已先读 Tickets Map、再读当前 Ticket 适用的项目 Skill；实现中发现的新匹配 Skill 已同步回 Map 并通过校验；
-- 重复失败或 integration attempt 上限只触发 Lead 复盘；没有 Evidence 中的原因、改变和 owner 决定，不得重置 attempts 或重复派发；
-- current Ticket 父分支只推进到通过的 direct-parent 验证 commit；required Ticket 父分支只推进到通过的 candidate；两者 Ticket Done 都必须与实际 Git 一致；Direct Spec 的完成状态与 current workspace 最终 checkpoint 一致；
-- 实际路径、验证、偏差和状态可由 Evidence 恢复；
-- validator 无 error。
-
-## 子文件引用
-
-- 执行前预检：`<Path>{roots.workflows}/specdev/I-implement/execution-preflight.md</Path>`
-- 代码库设计：`<Path>{roots.workflows}/specdev/common/rules/codebase-design.md</Path>`
-- Design It Twice：`<Path>{roots.workflows}/specdev/I-implement/design-it-twice.md</Path>`
-- TDD：`<Path>{roots.workflows}/specdev/I-implement/tdd-rules.md</Path>`、`<Path>{roots.workflows}/specdev/I-implement/tdd-test-design.md</Path>`、`<Path>{roots.workflows}/specdev/I-implement/tdd-mocking.md</Path>`
-- 代码注释：`<Path>{roots.workflows}/specdev/common/rules/code-commenting-rule.md</Path>`
-- Evidence：`<Path>{roots.workflows}/specdev/I-implement/evidence-template.md</Path>`
-- Agent 交付：`<Path>{roots.workflows}/specdev/common/skills/subagent-delivery/SKILL.md</Path>`
-- Worktree：`<Path>{roots.workflows}/specdev/common/skills/dev-worktree/SKILL.md</Path>`
-- 冲突处理：`<Path>{roots.workflows}/specdev/I-implement/merge-conflict-protocol.md</Path>`
-
 ## 计划型票扩展
 
 实施前按 `<Path>{roots.workflows}/specdev/common/rules/skill-invocation.md</Path>` 执行绑定；恢复或上游变化按 `<Path>{roots.workflows}/specdev/P-goal-plan/references/replan-and-recovery.md</Path>` 核验。不以读取替代调用，不因他人任务冲突暂停独立已授权工作。

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

@@ -9,134 +9,33 @@ keywords: [初始化, 配置, status, tracking, 验证命令]
 
 # 初始化设置
 
-> 激活本 Work 后，先读取 `<Path>{roots.workflows}/specdev/README.md</Path>`，再执行本入口。
+激活后读取 `<Path>{roots.workflows}/specdev/README.md</Path>`、`<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>` 与 `<Path>{roots.workflows}/specdev/common/rules/path-reference-contract.md</Path>`。本 Work 只配置 SpecDev，不修改业务代码或迁移旧状态。
 
-首次使用 SpecDev、状态根不存在或治理契约发生变化后运行。此 work 只初始化 SpecDev 的状态与配置，不修改项目业务代码。
+## 定位与探测
 
-## 读取范围
+创建任何目录前，从 cwd 向上定位并打开 `<Path>{roots.state}/workspace.json</Path>`，验证 `path_base` 与 roots。只写声明的 `<Path>{roots.state}/specdev/</Path>`；不得把状态根默认展开成项目根 `.speculo`，嵌套安装的项目根 `.speculo/specdev` 非法。根目录未解析或未获授权时停止写入；持久化引用使用根变量，不把机器绝对路径写回模板。
 
-1. 先读取 `<Path>{roots.workflows}/specdev/README.md</Path>` 与当前 Work 的状态入口。
-2. 再读取 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`，按当前分支、状态和关键词定位最小相关工件。
-3. 只在本 Work 明确要求恢复、冲突、执行安全或归档证据时扩展为全量读取；缺少匹配证据或 owner/gateway 时停止受影响分支。
+只读探测包管理、多工作区、构建/测试/类型/lint/CI、默认父分支、worktree、项目 Agent 指令及分支/提交/发布先例；记录根依赖清单、锁文件、共享 schema、迁移索引、全局导出/路由等高冲突资源。能从仓库发现的事实不重复问用户。
 
+确认项目根 `.gitignore` 已含 `specdev-worktree/` 或 `/specdev-worktree/`；该条目由 `speculo init` 唯一维护，缺失时停止并提示重新运行当前版本 CLI，不由 Work 补写。
 
-## 规范输入
+## 选择初始化分支
 
-- 工作流运行合同：`<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>`
-- 全局状态模板：`<Path>{roots.workflows}/specdev/I-init-setup/status-template.json</Path>`
-- 全局状态 Schema：`<Path>{roots.workflows}/specdev/common/schemas/status.schema.json</Path>`
-- Change 状态模板：`<Path>{roots.workflows}/specdev/I-init-setup/change-status-template.json</Path>`
-- Change 状态 Schema：`<Path>{roots.workflows}/specdev/common/schemas/change-status.schema.json</Path>`
+| 当前事实 | 执行 |
+|---|---|
+| 配置或状态不存在 | 读取 `<Path>{roots.workflows}/specdev/I-init-setup/references/first-setup.md</Path>`，仅在首次创建对应文件时读取 `<Path>{roots.workflows}/specdev/I-init-setup/config-template.json</Path>`、`<Path>{roots.workflows}/specdev/I-init-setup/tracking-template.md</Path>`、`<Path>{roots.workflows}/specdev/I-init-setup/domain-layout-template.md</Path>`；只创建缺失骨架；语言、并发、UI 数量与人工批准偏好仅补问尚未知项 |
+| 已有有效配置和状态 | 对照 `<Path>{roots.workflows}/specdev/common/schemas/config.schema.json</Path>`、`<Path>{roots.workflows}/specdev/common/schemas/status.schema.json</Path>` 验证并复用；保留 active、历史、永久知识和用户配置 |
+| 用户要求修改既有配置 | 先验证并展示差异，再按授权更新；不存全局自动提交/集成开关 |
+| JSON 无效、版本未知或契约冲突 | 保留原文件并报告 blocker；迁移只由 `speculo init` 使用 `<Path>{roots.workflows}/specdev/runtime-contract.json</Path>` 中登记的显式 migrator 完成 |
 
-## 流程
+## 验收与返回
 
-### 1. 解析根目录
+配置/全局状态必须可解析且满足 schema；状态、changes、永久 ADR/context/research、archive 与配置目录齐全，tracking/domain-layout 两份配置文档有效。验证命令必须有仓库或用户来源，未知值保留 `null`，不保存秘密。
 
-创建任何状态目录之前，先从 cwd 向上定位并打开 `<Path>{roots.state}/workspace.json</Path>`，校验 `path_base` 与 `roots.*`。只在解析后的状态根下创建 specdev 目录；禁止在声明的状态根之外新建 `.speculo`。
-
-确认：
-
-- 工作流根可解析为 `<Path>{roots.workflows}/specdev/</Path>`；
-- 状态根可解析为 `<Path>{roots.state}/specdev/</Path>`，且必须来自已打开的 `<Path>{roots.state}/workspace.json</Path>`；
-- 当前用户允许在状态根创建目录和工件。
-
-嵌套安装反例：不得把状态根默认展开成项目根 `.speculo`。项目根 `.speculo/specdev` 非法；init 与 Grill 只写入声明的 `<Path>{roots.state}/specdev/</Path>`。
-
-不得把真实绝对路径写回模板或治理文档；持久化引用继续使用根变量。
-
-### 2. 探测项目事实
-
-只读检查仓库根、包管理方式、构建脚本、测试脚本、静态检查、CI、默认分支、项目级 Agent 指令与 worktree 约定。能从仓库发现的事实直接记录，不询问用户。
-
-至少探测：
-
-- 项目测试、类型检查、lint 和构建命令；
-- 是否存在多包或多工作区结构；
-- 默认父分支、Git worktree 支持和项目已有分支/提交约定；
-- 共享高冲突路径的类型，例如根依赖清单、锁文件、全局导出、共享 schema、迁移索引和全局路由；
-- 项目中已有的提交、分支和发布约定。
-
-同时确认项目根 `.gitignore` 存在且包含 `specdev-worktree/`（`/specdev-worktree/` 视为等价）。该条目由 `speculo init` 单一维护；缺失时停止并提示用户以当前 Speculo 版本重新运行 `speculo init`，本 Work 不作为第二写入者修改它。
-
-### 3. 询问不可发现偏好
-
-仅在上下文未提供时询问：
-
-- 交互语言与持久化工件语言；
-- implementation subagent、集成尝试次数和 UI 设计候选上限（初始化时写入 config，Lead 不计入）；
-- Deep Ticket 的迁移、发布和不可逆操作是否必须人工批准；
-
-不询问可由仓库事实回答的文件位置、脚本名或默认分支。
-
-### 4. 写入配置
-
-以 `<Path>{roots.workflows}/specdev/I-init-setup/config-template.json</Path>` 为模板写入 `<Path>{roots.state}/specdev/config.json</Path>`。
-
-要求：
-
-- 字段满足 `<Path>{roots.workflows}/specdev/common/schemas/config.schema.json</Path>`；
-- 验证命令来自仓库事实或显式用户决定；
-- 未确认命令写 `null`，不得虚构；
-- 不写入令牌、凭据、Cookie、个人隐私或敏感环境变量值；
-- Ticket 的实现 commit 与本地 candidate integration 仍由具体 Goal Plan/I-implement 取得授权，不存为全局自动副作用开关。
-
-### 5. 初始化目录与状态
-
-创建或确认以下目录和文件：
-
-- 以 `<Path>{roots.workflows}/specdev/I-init-setup/status-template.json</Path>` 生成 `<Path>{roots.state}/specdev/status.json</Path>`
-- `<Path>{roots.state}/specdev/.config/</Path>`
-- `<Path>{roots.state}/specdev/changes/</Path>`
-- `<Path>{roots.state}/specdev/adr/</Path>`
-- `<Path>{roots.state}/specdev/context/</Path>`
-- `<Path>{roots.state}/specdev/research/</Path>`
-- `<Path>{roots.state}/specdev/archive/</Path>`
-
-若全局状态或 config 已存在，先检查各自 `schema_version`。版本未知、JSON 不可解析或状态与当前 workflow 契约不一致时，停止当前 Work；不得在 Work 内迁移、兼容或猜测旧状态。`speculo init` 只会对 `<Path>{roots.workflows}/specdev/runtime-contract.json</Path>` 已登记且存在显式 migrator 的旧版本升级，其他冲突会保留当前安装并报告具体 blocker。只有状态不存在时才从当前 schema 模板创建。
-
-从模板生成：
-
-- `<Path>{roots.workflows}/specdev/I-init-setup/tracking-template.md</Path>` → `<Path>{roots.state}/specdev/.config/tracking.md</Path>`
-- `<Path>{roots.workflows}/specdev/I-init-setup/domain-layout-template.md</Path>` → `<Path>{roots.state}/specdev/.config/domain-layout.md</Path>`
-
-已有永久知识不得被初始化过程清空。已有配置应先验证和展示差异，再按用户授权更新。
-
-### 6. 验证初始化结果
-
-1. 解析 `<Path>{roots.state}/specdev/config.json</Path>` 和 `<Path>{roots.state}/specdev/status.json</Path>`；
-2. 对照 `<Path>{roots.workflows}/specdev/common/schemas/config.schema.json</Path>` 与 `<Path>{roots.workflows}/specdev/common/schemas/status.schema.json</Path>`；
-3. 确认 `<Path>{roots.workflows}/specdev/I-init-setup/change-status-template.json</Path>` 的字段与 `<Path>{roots.workflows}/specdev/common/schemas/change-status.schema.json</Path>` 对齐；实际创建 change 时替换模板占位符后再执行 Schema 验证；
-4. 确认所有必需目录存在；
-5. 确认两个配置文档均已从对应模板生成；
-6. 确认项目根 `.gitignore` 已忽略 `specdev-worktree/`；
-7. 运行：
+创建 change 前，对照 `<Path>{roots.workflows}/specdev/I-init-setup/change-status-template.json</Path>` 与 `<Path>{roots.workflows}/specdev/common/schemas/change-status.schema.json</Path>`，真实创建时替换占位符后校验；纯初始化不创建虚假的 change。
 
 ```bash
 node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> --self-check
 ```
 
-### 7. 更新状态并汇报
-
-若本 Work 由某个 active change 调用，开始时把该 entry 的 `current_work` 设为 `specdev/init-setup`，完成时将该 id 去重加入 `works_run` 并清空；纯工作流初始化没有 active change 时不创建虚假的 change。时间和验证结果写入本次回复或 change 自有 Evidence/LOG，不写入全局索引。向用户汇报：状态根、语言、验证命令、并发策略、人工批准策略和任何仍为 `null` 的配置项。
-
-## 完成标准
-
-- `<Path>{roots.state}/specdev/config.json</Path>` 与 `<Path>{roots.state}/specdev/status.json</Path>` 可解析且满足 Schema；
-- 状态目录、永久知识目录和归档目录齐全；
-- 两个配置文档已就位；
-- 验证命令与并发规则有来源；
-- 项目根 `.gitignore` 已包含 `specdev-worktree/`；
-- 无敏感值被写入；
-- 包级自检无 error；
-- 存在调用 change 时，其 `works_run` 已包含本 work且 `current_work` 已清空；纯初始化时全局 active 保持真实为空。
-
-## 子文件引用
-
-- `<Path>{roots.workflows}/specdev/I-init-setup/config-template.json</Path>`
-- `<Path>{roots.workflows}/specdev/I-init-setup/status-template.json</Path>`
-- `<Path>{roots.workflows}/specdev/I-init-setup/change-status-template.json</Path>`
-- `<Path>{roots.workflows}/specdev/I-init-setup/tracking-template.md</Path>`
-- `<Path>{roots.workflows}/specdev/I-init-setup/domain-layout-template.md</Path>`
+回读实际配置、状态、目录和忽略项后返回状态根、语言、验证命令、并发/批准策略、未确认配置与检查结果。若由 active change 调用，按原启动/交接合同登记 `current_work`，成功后去重更新 `works_run` 并清空；纯初始化不改已有 active 索引。时间和验证证据留在回复或调用 change 的 Evidence/LOG，不写进全局索引。

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

@@ -0,0 +1,46 @@
+# 首次配置与缺失骨架
+
+只在配置或状态尚不存在时读取；已有文件先按入口验证，不重新初始化。
+
+### 3. 询问不可发现偏好
+
+仅在上下文未提供时询问：
+
+- 交互语言与持久化工件语言；
+- implementation subagent、集成尝试次数和 UI 设计候选上限（初始化时写入 config，Lead 不计入）；
+- Deep Ticket 的迁移、发布和不可逆操作是否必须人工批准；
+
+不询问可由仓库事实回答的文件位置、脚本名或默认分支。
+
+### 4. 写入配置
+
+以 `<Path>{roots.workflows}/specdev/I-init-setup/config-template.json</Path>` 为模板写入 `<Path>{roots.state}/specdev/config.json</Path>`。
+
+要求：
+
+- 字段满足 `<Path>{roots.workflows}/specdev/common/schemas/config.schema.json</Path>`；
+- 验证命令来自仓库事实或显式用户决定；
+- 未确认命令写 `null`，不得虚构；
+- 不写入令牌、凭据、Cookie、个人隐私或敏感环境变量值；
+- Ticket 的实现 commit 与本地 candidate integration 仍由具体 Goal Plan/I-implement 取得授权，不存为全局自动副作用开关。
+
+### 5. 初始化目录与状态
+
+创建或确认以下目录和文件：
+
+- 以 `<Path>{roots.workflows}/specdev/I-init-setup/status-template.json</Path>` 生成 `<Path>{roots.state}/specdev/status.json</Path>`
+- `<Path>{roots.state}/specdev/.config/</Path>`
+- `<Path>{roots.state}/specdev/changes/</Path>`
+- `<Path>{roots.state}/specdev/adr/</Path>`
+- `<Path>{roots.state}/specdev/context/</Path>`
+- `<Path>{roots.state}/specdev/research/</Path>`
+- `<Path>{roots.state}/specdev/archive/</Path>`
+
+若全局状态或 config 已存在，先检查各自 `schema_version`。版本未知、JSON 不可解析或状态与当前 workflow 契约不一致时，停止当前 Work；不得在 Work 内迁移、兼容或猜测旧状态。`speculo init` 只会对 `<Path>{roots.workflows}/specdev/runtime-contract.json</Path>` 已登记且存在显式 migrator 的旧版本升级，其他冲突会保留当前安装并报告具体 blocker。只有状态不存在时才从当前 schema 模板创建。
+
+从模板生成：
+
+- `<Path>{roots.workflows}/specdev/I-init-setup/tracking-template.md</Path>` → `<Path>{roots.state}/specdev/.config/tracking.md</Path>`
+- `<Path>{roots.workflows}/specdev/I-init-setup/domain-layout-template.md</Path>` → `<Path>{roots.state}/specdev/.config/domain-layout.md</Path>`
+
+已有永久知识不得被初始化过程清空。已有配置应先验证和展示差异，再按用户授权更新。

package/template/workflows/specdev/L-learn-change/L-learn-change.md

@@ -9,98 +9,20 @@ keywords: [learn-change, change 学习, 开发后提问, 零基础, 大一新生
 
 # Change 学习：给零基础新生的图解
 
-> 激活本 Work 后，先读取 `<Path>{roots.workflows}/specdev/README.md</Path>`，再执行本入口。
+激活后读取 `<Path>{roots.workflows}/specdev/README.md</Path>` 与 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`。只解释当前 change 已验证的实现与测试事实，不作产品/架构决定或授予实现权限。
 
-## 读取范围
-
-1. 先读取 `<Path>{roots.workflows}/specdev/README.md</Path>` 与当前 Work 的状态入口。
-2. 再读取 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`，按当前分支、状态和关键词定位最小相关工件。
-3. 只在本 Work 明确要求恢复、冲突、执行安全或归档证据时扩展为全量读取；缺少匹配证据或 owner/gateway 时停止受影响分支。
-
-
-## 读者与职责
-
-读者是刚入大学、没有专业背景（零专业背景）的新生。读者能理解日常因果和简单流程，但不应被假定知道代码、网络、数学或行业背景。
-
-本 Work 用于在 change 开发完成后回答与该 change 有关的问题。它只解释，不作产品决定、架构决定或实现授权；它把当前 change 中已验证的工件、实现和测试事实写成可恢复的 Markdown 图解。图比段落更先出现，文字只负责读懂图。
-
-```text
-已完成 change 的已验证事实
-            |
-            v
-      用户关于 change 的问题
-            |
-            v
-    ASCII 全图 + 分步图 + 简短说明
-            |
-            v
- learning/01_<topic>.md、02_<topic>.md、...
-            |
-            v
-      learning/index.md（图解目录）
-```
-
-主题：`$ARGUMENTS`
-
-## 输出格式
-
-在当前 change 的 `<Path>{roots.state}/specdev/changes/{change}/learning/</Path>` 内原子写入一份新的 `<Path>{roots.state}/specdev/changes/{change}/learning/{number}_{topic}.md</Path>`，并原子更新索引 `<Path>{roots.state}/specdev/changes/{change}/learning/index.md</Path>`。这些产物属于 SpecDev change，不写入 `<Path>{roots.state}/learning/</Path>`。文档必须是纯 Markdown，不生成 HTML、CSS、SVG、图片链接或浏览器专属交互。
-
-`<number>` 是两位起始、持续递增的序号：先读取索引和同目录已有的图解文件，取最大序号加一，因此第一次为 `01`，下一次为 `02`；不为旧文件重编号。`<topic>` 是主题的简短、可作文件名的标签，可使用中文、字母、数字、`-` 或 `_`，但不能含空格、`/`、`\\` 或 `..`。同主题再次解释也创建新编号文件。
-
-索引是唯一目录，使用下列 Markdown 表格；每新增一份图解就在表末追加一行，并保留既有行。文件列只写同目录的文件名：
-
-```markdown
-# Change 学习图解索引
-
-| 编号 | 文件 | 主题 | 简介 |
-| --- | --- | --- | --- |
-| 01 | 01_<topic>.md | <主题> | <一句话说明它解释什么> |
-```
-
-按主题选择最贴切的图，但优先用多个短小 ASCII 图代替长文字：
-
-```text
-结构图：
-[系统]
-  |
-  +-- [部件 A]
-  +-- [部件 B]
+## 执行
 
-数据流图：
-[输入] -> [处理] -> [结果]
+1. **选择现有 change**：使用用户指定或唯一未归档 change；没有时返回缺失输入，不创建空 change。只读归档不追加学习材料。按原交接规则登记 `current_work=specdev/learn-change`，不把 `change_status=completed` 重新打开为开发中。
+2. **确定主题**：使用 `$ARGUMENTS` 调用参数或用户最新问题；缺少时只询问主题。读者是刚入大学、零专业背景的新生，先确定“它是什么、为什么需要、怎样流动或被调用”三个答案。
+3. **定位事实**：按主题读取 Source、Spec、Ticket、Evidence、review、实际代码/测试与可靠来源。区分已验证事实、类比与未知；旧计划和实现冲突时明确差异，以当前代码、测试、Evidence 为实现事实，不让类比代替证据。
+4. **生成与保存**：读取 `<Path>{roots.workflows}/specdev/L-learn-change/references/lesson-format.md</Path>` 的完整格式和命名合同。先画 ASCII 全图，再按实际关系画短小结构/数据/调用/状态图；用短句解释箭头，术语先日常解释再给专业名字。验证零背景读者能复述三个答案；不能时拆图或换词，不灌长文。
+5. **追加而非覆盖**：从 `<Path>{roots.state}/specdev/changes/{change}/learning/index.md</Path>` 及同目录真实图解的最大编号取下一号；先原子创建 `<Path>{roots.state}/specdev/changes/{change}/learning/{number}_{topic}.md</Path>` 新图解，再更新索引并回读。重讲同主题仍新增编号，保留旧文件、原顺序和全部历史行。产物仅为纯 Markdown/ASCII，不生成 HTML、CSS、SVG、图片或浏览器依赖，不写 `<Path>{roots.state}/learning/</Path>`、生产代码、永久知识或远程系统。
 
-调用流图：
-[用户动作] -> [入口] -> [服务] -> [回应]
+## 验收与恢复
 
-状态变化图：
-[等待] -> [进行中] -> [完成]
+```bash
+node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> --stage learn-change <Path>{roots.state}/specdev/changes/{change}</Path>
 ```
 
-每份图解至少包含以下四节：
-
-1. `## 先看全图`：一个能说清“谁和谁有关”的 ASCII 图。
-2. `## 一步一步看`：按箭头顺序解释。流程、数据或调用会移动时，再给对应的 ASCII 图。
-3. `## 术语小词典`：只保留读图必需的词。每个词先用日常语言解释，再给它的专业名字。例如：`临时便签（缓存）`，意思是“把常用结果先放在手边，下一次不用重新找”。
-4. `## 你现在能复述什么`：用短句归纳“它是什么、为什么需要它、它怎样流动或被调用”。
-
-图中的方框名称使用普通名词和动词，不用缩写；箭头必须有方向。一个图只讲一个问题。确有边界、失败或例外时，单独画一张小图说明，不把它塞进主图。
-
-## 执行
-
-1. 按 `<Path>{roots.workflows}/specdev/README.md</Path>` 读取全局状态和当前 change 状态。只选择用户指定或唯一未归档的现有 change；没有可用 change 时说明必须先完成或指定一个 SpecDev change，不创建空 change。已归档 change 保持只读，不在归档目录追加学习产物。`current_work` 为空时设为 `specdev/learn-change`；若指向其他 Work，先完成显式交接。`change_status=completed` 不因本 Work 被重新打开为开发中。
-2. 将调用中的 `$ARGUMENTS` 解析为主题；直接提出的问题以用户最新消息为主题。主题缺失时只询问问题或主题，不猜测。先写下读者要带走的三个答案：它是什么、为什么需要它、它怎样流动或被调用。
-3. 按需读取当前 change 的 Source、Spec、Ticket、Evidence、review、项目实现、测试和可靠来源。区分已验证事实、便于理解的类比和未知处；实现事实与旧计划冲突时以当前代码、测试和 Evidence 为准，并显式指出差异。类比只能帮助理解，不能替代事实或掩盖边界。
-4. 先画 `先看全图`，再按实际关系补充结构图、数据流图、调用流图或状态变化图。每张图旁只用短句解释箭头；避免长段落、术语堆叠、缩写和先备知识。
-5. 首次使用术语时，先写日常解释，再在括号中给专业名字。读完后从读者角度检查：没有背景知识的人能否仅靠图和短句复述三个答案；若不能，拆图或替换术语，不增加大段说明。
-6. 读取 `<Path>{roots.state}/specdev/changes/{change}/learning/index.md</Path>` 和 `<Path>{roots.state}/specdev/changes/{change}/learning/</Path>` 内已有图解文件。从两者的最大序号计算下一个编号，先原子创建新的图解文件，再原子更新索引；不覆盖、重命名或重排已有图解。重读确认新文件是 Markdown，包含四个必需章节、至少一个 ASCII 图且没有 HTML 标记或图片依赖；索引的文件名、主题和简介都与新文件对应。
-7. 运行 `<Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path>` 的 `--stage learn-change`。成功后把 `specdev/learn-change` 去重加入 `works_run`，清空 `current_work`，并返回新 Markdown 与索引的完整路径；失败时保留 `current_work` 和阻塞原因，便于恢复，但不改变 change 的开发完成状态。
-
-## 完成标准
-
-- `<Path>{roots.state}/specdev/changes/{change}/learning/index.md</Path>` 存在，按序列出每份图解的编号、文件、主题和简介；每个文件名都对应同目录真实文件。
-- 新的 `<Path>{roots.state}/specdev/changes/{change}/learning/{number}_{topic}.md</Path>` 存在，是纯 Markdown，并含有全部四个必需章节和至少一个 ASCII 图；编号比既有最大编号大一，旧文件未被重排或覆盖。
-- 文档面向刚上大一、没有专业背景的读者；用图和短句回答当前 change 的问题，而不是把专业长文换成更简单的字。
-- 图解覆盖主题需要的结构、数据流、调用流或状态变化；能画图的地方优先画图，且每张图的箭头方向与事实一致。
-- 术语首次出现前有日常解释；类比不把读者带向相反结论；计划与最终实现的差异没有被隐藏。
-- 状态已原子更新；所有学习产物只写入当前 SpecDev change 的 `learning/` namespace，没有修改项目代码、永久知识、Learning workflow state 或远程系统。
+图解符合格式参考的四节、至少一个 ASCII 图和连续编号；索引指向真实新文件且主题/简介一致，箭头方向与事实相符。验证通过才去重更新 `works_run`、清空 `current_work`，返回新图解和索引完整路径。失败保留恢复位置与原因，不改变 change 原有开发完成状态。

package/template/workflows/specdev/L-learn-change/references/lesson-format.md

@@ -0,0 +1,47 @@
+# Change 学习图解格式
+
+写图解与分配编号时读取；这是产物格式权威，不是另一套学习状态。
+
+## 输出格式
+
+在当前 change 的 `<Path>{roots.state}/specdev/changes/{change}/learning/</Path>` 内原子写入一份新的 `<Path>{roots.state}/specdev/changes/{change}/learning/{number}_{topic}.md</Path>`，并原子更新索引 `<Path>{roots.state}/specdev/changes/{change}/learning/index.md</Path>`。这些产物属于 SpecDev change，不写入 `<Path>{roots.state}/learning/</Path>`。文档必须是纯 Markdown，不生成 HTML、CSS、SVG、图片链接或浏览器专属交互。
+
+`<number>` 是两位起始、持续递增的序号：先读取索引和同目录已有的图解文件，取最大序号加一，因此第一次为 `01`，下一次为 `02`；不为旧文件重编号。`<topic>` 是主题的简短、可作文件名的标签，可使用中文、字母、数字、`-` 或 `_`，但不能含空格、`/`、`\\` 或 `..`。同主题再次解释也创建新编号文件。
+
+索引是唯一目录，使用下列 Markdown 表格；每新增一份图解就在表末追加一行，并保留既有行。文件列只写同目录的文件名：
+
+```markdown
+# Change 学习图解索引
+
+| 编号 | 文件 | 主题 | 简介 |
+| --- | --- | --- | --- |
+| 01 | 01_<topic>.md | <主题> | <一句话说明它解释什么> |
+```
+
+按主题选择最贴切的图，但优先用多个短小 ASCII 图代替长文字：
+
+```text
+结构图：
+[系统]
+  |
+  +-- [部件 A]
+  +-- [部件 B]
+
+数据流图：
+[输入] -> [处理] -> [结果]
+
+调用流图：
+[用户动作] -> [入口] -> [服务] -> [回应]
+
+状态变化图：
+[等待] -> [进行中] -> [完成]
+```
+
+每份图解至少包含以下四节：
+
+1. `## 先看全图`：一个能说清“谁和谁有关”的 ASCII 图。
+2. `## 一步一步看`：按箭头顺序解释。流程、数据或调用会移动时，再给对应的 ASCII 图。
+3. `## 术语小词典`：只保留读图必需的词。每个词先用日常语言解释，再给它的专业名字。例如：`临时便签（缓存）`，意思是“把常用结果先放在手边，下一次不用重新找”。
+4. `## 你现在能复述什么`：用短句归纳“它是什么、为什么需要它、它怎样流动或被调用”。
+
+图中的方框名称使用普通名词和动词，不用缩写；箭头必须有方向。一个图只讲一个问题。确有边界、失败或例外时，单独画一张小图说明，不把它塞进主图。

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

@@ -13,9 +13,9 @@ keywords: [goal, 目标, plan, run, resume, replan, verify, Lead]
 
 ## 读取范围
 
-先读 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`，定位用户指定的 change 或 map，再读状态、当前 map 和所选模式。只有进入 frontier 的 Ticket、命中的项目 Skill、Gate 与恢复证据需要展开；不默认通读所有 Ticket 或永久索引。
+先读 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`，定位用户指定的 change 或 map，再读状态、当前 map 和所选模式。每次只展开实际进入 frontier 的 Ticket、直接依赖 Evidence、命中的项目 Skill、当前 Gate 与恢复证据；不默认通读所有 Ticket 或永久索引。
 
-## 模式与权威
+## 按意图选择模式与权威
 
 | 用户意图 | 模式 | 必须按需读取 |
 |---|---|---|

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

@@ -13,12 +13,7 @@ keywords: [prototype, UI 原型, 风格检测, 设计系统, HTML, CSS, 交互,
 
 本 Work 的主导词是**设计定向**：先从项目事实识别现状，再让用户看到基于功能而非流行色推荐的候选，最后把选择固化为既可阅读又可运行的 UI 设计包。P 不修改生产 UI；后续 S、Tickets 和 I 以设计包为视觉与交互权威。
 
-## 读取范围
-
-1. 先读取 `<Path>{roots.workflows}/specdev/README.md</Path>` 与当前 Work 的状态入口。
-2. 再读取 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`，按当前分支、状态和关键词定位最小相关工件。
-3. 只在本 Work 明确要求恢复、冲突、执行安全或归档证据时扩展为全量读取；缺少匹配证据或 owner/gateway 时停止受影响分支。
-
+激活时读取 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`，按当前步骤定位输入和证据。
 
 ## 输入与所有权
 
@@ -36,7 +31,7 @@ P 拥有 `<Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/</
 3. **建立功能候选**：读取 `<Path>{roots.workflows}/specdev/P-prototype/design-library/INDEX.md</Path>`，依据产品任务、平台和信息密度从八种风格及六种布局中推荐 2-4 个候选。每个候选写明适合原因、需要保留/调整/替换的现有事实、参考项目和迁移成本。
 4. **逐项选择并持久化**：加载 `<Path>{roots.workflows}/specdev/P-prototype/style-selection-protocol.md</Path>`。每轮只处理一个决策层；每个答案立即写回设计系统主文档并重读。高影响偏好未确认时保持 `status: selecting`，不得自行标记 Ready。
 5. **生成可视对照与最终原型**：加载 `<Path>{roots.workflows}/specdev/P-prototype/generate-design-package.md</Path>`。为每个候选生成独立 comparison variant，再生成 comparison 索引。用户确认或明确组合后，把最终 HTML/CSS/JS 作为具名代码块写入设计系统主文档，再物化到 final 目录。
-6. **验证并封板**：运行 `<Path>{roots.workflows}/specdev/P-prototype/tools/materialize-prototype.mjs</Path> --check` 和 `<Path>{roots.workflows}/specdev/P-prototype/tools/validate-design-package.mjs</Path>`；随后运行 SpecDev `--stage prototype`。全部通过且选择闭合后设置 `status: ready`，更新 `works_run` 并清空 `current_work`。缺少项目事实或用户决定时设置 `blocked` 并保留恢复位置。
+6. **验证并封板**：运行 `<Path>{roots.workflows}/specdev/P-prototype/tools/materialize-prototype.mjs</Path> --check` 和 `<Path>{roots.workflows}/specdev/P-prototype/tools/validate-design-package.mjs</Path>`；随后运行 SpecDev `--stage prototype`。对照 `<Path>{roots.workflows}/specdev/P-prototype/design-package.schema.json</Path>`，全部通过且选择闭合后设置 `status: ready`，更新 `works_run` 并清空 `current_work`。缺少项目事实或用户决定时设置 `blocked` 并保留恢复位置。
 7. **返回路由**：返回设计包、comparison 和 final 的完整路径、验证命令与结果、未决问题和下一 Work。需要补足产品决定时返回 G；需要写外部行为合同返回 S；需要拆实施工作返回 Tickets；已有 Ready Ticket 才返回 I。Wayfinder 调用时只把设计包与 comparison locator 写入对应 solution comment。
 
 ## 完成标准
@@ -48,12 +43,3 @@ P 拥有 `<Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/</
 - 字体、间距、圆角、色彩、层级、控件状态、异步反馈、响应式、键盘、focus 和 reduced motion 均有明确合同。
 - Markdown 代码块与 `final/` 文件逐字一致，schema、局部校验和 SpecDev stage 校验全部通过。
 - 设计包不包含机器绝对路径、敏感值、生产数据写入、发布动作或未授权的生产实现。
-
-## 子文件引用
-
-- 检测：`<Path>{roots.workflows}/specdev/P-prototype/detect-existing-style.md</Path>`，仅在步骤 2 加载。
-- 选择：`<Path>{roots.workflows}/specdev/P-prototype/style-selection-protocol.md</Path>`，仅在步骤 4 加载。
-- 生成：`<Path>{roots.workflows}/specdev/P-prototype/generate-design-package.md</Path>`，仅在步骤 5 加载。
-- 模板：`<Path>{roots.workflows}/specdev/P-prototype/design-system-template.md</Path>`，创建设计包时加载。
-- 设计库：`<Path>{roots.workflows}/specdev/P-prototype/design-library/INDEX.md</Path>`，建立候选或查具体规则时渐进读取。
-- Schema：`<Path>{roots.workflows}/specdev/P-prototype/design-package.schema.json</Path>`。