@namewta/speculo 1.0.18 → 1.0.20

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/INDEX.md

@@ -3,8 +3,8 @@ id: specdev
 type: workflow
 workflow: specdev
 name: SpecDev Workflow
-description: 以本地工件为唯一开发权威，从来源冻结、诊断、设计、原型、规格、Ticket、编排和审查推进到证据驱动实现、远程 reconcile 或票级发布投影、记事项捕获与知识归档。
-keywords: [specdev, local-first, 规格驱动开发, decision-complete, prototype, code-review, TDD, 证据]
+description: 以本地工件为开发权威，覆盖来源分诊、诊断、设计、逻辑/UI 原型、规格、Ticket、编排、实现、审查、复盘、GitHub/PR/包发布交付与知识归档。
+keywords: [specdev, local-first, 规格驱动开发, decision-complete, prototype, code-review, TDD, retro, PR, release, 证据]
 ---
 
 # SpecDev Index

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-goal-plan/planning-modes.md

@@ -13,7 +13,7 @@
 - 等待真实上游产物的未来 Ticket 保持 `status: draft`、`ready: false`，在未决问题中记录缺口、生产者 Ticket、所需证据和 DoR 重审条件；不编造版本、路径或验证入口；
 - 每个验收合同被 Ticket 覆盖；
 - writable/shared path 有唯一 owner，Wave 候选无写冲突；
-- config schema v5，`max_implementation_agents` 与 `max_integration_attempts` 为正整数；UI 设计候选范围读取 planning 配置；
+- config schema v6，`max_implementation_agents` 与 `max_integration_attempts` 为正整数；UI 设计候选范围读取 planning 配置；
 - 父分支可定位，implementation commit 与本地 integration 的授权状态已记录；`plan` 可以列出待批准项并保持 `ready_for_execution: false`；
 - 待执行 Deep Ticket 的迁移、兼容、监控、恢复和不可逆批准点完整。
 - Ticket 与 `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`、`<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`、`<Path>{roots.state}/specdev/adr/</Path>`、`<Path>{roots.state}/specdev/context/</Path>` 和当前代码事实不存在未处理冲突；

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

@@ -2,23 +2,22 @@
 id: specdev/prototype
 type: workflow-entry
 workflow: specdev
-name: UI 设计原型
-description: 检测现有项目的 UI 事实，按产品任务推荐并逐步选择设计风格，生成持久化设计系统文档、多风格 HTML 对照和可运行 HTML/CSS/JS 原型。
+name: 逻辑与 UI 原型
+description: 按需验证离线逻辑模型，或检测现有项目的 UI 事实，按产品任务推荐并逐步选择设计风格，生成持久化设计系统文档、多风格 HTML 对照和可运行 HTML/CSS/JS 原型。
 keywords: [prototype, UI 原型, 风格检测, 设计系统, HTML, CSS, 交互, design tokens]
 ---
 
-# UI 设计原型
+# 逻辑与 UI 原型
 
 > 激活本 Work 后，先读取 `<Path>{roots.workflows}/specdev/README.md</Path>`，再执行本入口。
 
 本 Work 的主导词是**设计定向**：先从项目事实识别现状，再让用户看到基于功能而非流行色推荐的候选，最后把选择固化为既可阅读又可运行的 UI 设计包。P 不修改生产 UI；后续 S、Tickets 和 I 以设计包为视觉与交互权威。
 
-## 读取范围
+激活时读取 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`，按当前步骤定位输入和证据。
 
-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/P-prototype/logic-protocol.md</Path>，跳过下方 UI 专属步骤。UI 仍默认离线持久化，默认 3 个、最多 4 个方案。只有用户明确要求项目内预览时读取 <Path>{roots.workflows}/specdev/P-prototype/project-preview-protocol.md</Path>；其临时写集与清理由该分支管理，下方 UI 设计权威与离线交付保持。
 
 ## 输入与所有权
 
@@ -36,7 +35,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 +47,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>`。

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

@@ -0,0 +1,11 @@
+# 逻辑原型
+
+用于验证状态、算法、规则和交互因果。先读取 <Path>{roots.workflows}/specdev/P-prototype/logic-template.md</Path>。P 拥有 <Path>{roots.state}/specdev/changes/{change}/prototypes/LOGIC-NNN/</Path>，ID 最小未用；不修改生产代码或创建 branch/worktree。
+
+1. 选择当前问题的最小纯逻辑，明确初始状态、输入、状态转换、不变量、非法输入及希望验证的决定；有缺口先返回 G。
+2. 写 logic.md 作为决定和证据记录；生成 index.html，所有 CSS/JS 内联，无远程字体、CDN、网络调用或外部文件依赖。使用内存状态，reset 回到同一初始状态。
+3. 提供可见状态、自由操作、带解释的引导场景与 reset；场景包括正常、边界和非法输入。不要用动画或精美 UI 替代规则反馈。
+4. 在实际浏览器离线验证上述场景，记录观察和失败；静态脚本校验不能冒充浏览器观察。通过后 status=ready、verification=passed，保存 SHA-256 摘要。
+5. 运行 SpecDev --stage prototype，返回产物与已确认/未确认决定，路由 G/S/T。网页只是原型，不能自动复制为生产实现或把模拟结果当作后端真实行为。
+
+记录按 <Path>{roots.workflows}/specdev/common/schemas/logic-prototype.schema.json</Path> 校验。不能运行浏览器时保持 draft/blocked，报告可运行文件与未验证项。

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

@@ -0,0 +1,27 @@
+---
+schema_version: 1
+artifact: logic-prototype
+change: <YYYY-MM-DD-topic>
+id: LOGIC-001
+status: draft
+verification: pending
+html_sha256: null
+updated_at: <ISO-8601>
+---
+
+# 逻辑原型
+
+## Model
+状态、初值、输入、纯转换、不变量与非法输入。
+
+## Scenarios
+自由操作、引导路径、正常/边界/非法输入与每次 reset 的预期状态。
+
+## Evidence
+浏览器、离线运行、实际观察、失败与修复、index.html 摘要；未执行写未验证。
+
+## Decisions
+已确认的行为、仍需产品选择的事项与 S/T 可以引用的决定。
+
+## Handoff
+产物位置、验证结果、下一 Work；不得自动进入生产实现。

package/template/workflows/specdev/P-prototype/project-preview-protocol.md

@@ -0,0 +1,9 @@
+# 显式项目内 UI 预览
+
+仅在用户明确要求项目内预览时加载；默认仍是离线持久化 UI 包，候选默认 3、最多 4，不改变 design-system.md 权威。
+
+记录项目路由/启动命令、允许的临时文件写集、现有未提交改动和清理方案。用当前项目真实组件与布局环境，加隔离 mock/stub 阻断生产写入；不连接真实付款、发信或数据变更服务。使用 ?variant= 或项目等价参数切换方案，可加底部切换器；快捷键不能劫持输入框、编辑区或浏览器功能。
+
+每个候选决定与项目相对证据回写 design-system.md。验证相同任务、viewport、状态与交互，用户选定后仍生成离线 comparison/final 并通过原有两个局部校验器。临时预览不是另一权威源。
+
+只清理本次明确拥有且内容未漂移的临时修改，保留原有用户内容；发现 owner/内容冲突时停止该清理并记录剩余写集。清理完成或明确 handoff 后才能把项目预览分支标完成。不自动创建分支、提交、推送或删除 worktree。

package/template/workflows/specdev/R-retro/R-retro.md

@@ -0,0 +1,26 @@
+---
+id: specdev/retro
+type: workflow-entry
+workflow: specdev
+name: 开发复盘
+description: 对指定开发活动、环境或协作流程的已观察摩擦做证据化复盘，形成根因、改进 owner 与可检验提案；代码讲解使用 L-learn-change，Speculo 产品反馈使用 retro 命令。
+keywords: [retro, retrospective, 复盘, 环境, 反馈, 改进]
+---
+
+# 开发复盘
+
+先读 <Path>{roots.workflows}/specdev/README.md</Path> 和 <Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>。本 Work 不自动修代码、提 Issue 或改永久知识。
+
+## 流程
+
+1. 固定本次会话/活动范围，按来源 ID 定位 change、测试、CI、交接和失败证据，不全读历史。缺失资料列 unknown；范围清楚且证据可定位才开始分析。
+2. 未归档且尚未 completed 的当前 change 使用其 retro 目录。completed 或 archived 来源以及独立复盘建立非实现 review change，引用原 locator；不重开来源状态或改写归档。按 <Path>{roots.workflows}/specdev/common/rules/workflow-state-and-lifecycle.md</Path> 初始化/恢复；他项占用 current_work 时先 handoff。
+3. 调用 <Path>{roots.skills}/retrospective/SKILL.md</Path>，检查约束是否缺失、已有检查是否失效或未接入；区分环境事实、机械检查和判断规则。每个发现有因果证据或明确假设，建议有 owner、正反验收与路由。
+4. 按 <Path>{roots.workflows}/specdev/R-retro/retro-template.md</Path> 创建 <Path>{roots.state}/specdev/changes/{change}/retro/RETRO-###.md</Path>，选择最小未占用 ID。原子保存并重读，运行 SpecDev --stage retro；修订保留来源与被替代结论。
+5. 验证通过后追加 works_run=specdev/retro 并清空 current_work；证据不足可完成一份 outcome=insufficient-evidence 的诚实报告，不冒充解决问题。只读复盘不创建 Spec/Ticket 或 implementation Evidence。review-only change 按专用完成门关闭。
+
+## 结果与路由
+
+合法 outcome：findings、no-findings、insufficient-evidence。发现的 disposition 为 file-issue / lesson-only / discard / duplicate；每项记录理由，允许没有发现。
+
+代码问题交 <Path>{roots.workflows}/specdev/D-diagnose-bugs/D-diagnose-bugs.md</Path>，计划改进交 <Path>{roots.workflows}/specdev/T-tickets/T-tickets.md</Path>，远程反馈交 <Path>{roots.workflows}/specdev/T-triage/T-triage.md</Path>；永久知识交 <Path>{roots.workflows}/specdev/A-archive-and-consolidate/A-archive-and-consolidate.md</Path>。返回完整报告、已验证与未验证项、下一入口；不自动推进这些后续副作用。

package/template/workflows/specdev/R-retro/retro-template.md

@@ -0,0 +1,27 @@
+---
+schema_version: 1
+artifact: retrospective
+change: <YYYY-MM-DD-topic>
+id: RETRO-001
+status: completed
+outcome: findings
+sources: []
+updated_at: <ISO-8601>
+---
+
+# 开发复盘
+
+## Scope
+本次活动、会话、change 与来源 locator。扩大范围必须有来源。
+
+## Evidence
+原始现象、证据与未知项；已归档来源只引用不修改。
+
+## Findings
+逐项：ID、根因/假设、影响和频率、已有约束是否失效/未接入、remediation_axis、owner、disposition、合并/重复关系。没有发现明确写 none；不能强造 Issue。
+
+## Acceptance
+每项建议的正反样例、验证命令/方法与完成条件；区分机械检查和人的判断。
+
+## Routes
+下一入口、所需授权、未完成项及恢复条件；无后续动作注明原因。

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

@@ -11,18 +11,13 @@ keywords: [架构审查, 维护性, 浅模块, 深模块, 局部性, 杠杆, 接
 
 > 激活本 Work 后，先读取 `<Path>{roots.workflows}/specdev/README.md</Path>`，再执行本入口。
 
-本 work 以热核级维护性标准审查当前范围：先找会让 module 变浅的结构性坏味道，再找能删掉复杂性的 `code-judo` 机会，再找真正值得深化的 seam。行为正确不构成通过；如果存在更简单的路径，就优先把复杂性删掉，而不是搬家。
+本 work 根据可定位的代码压力审查当前范围：先找会让 module 变浅的结构性坏味道，再找能删掉复杂性的 `code-judo` 机会，再找真正值得深化的 seam。行为正确不构成通过；如果存在更简单的路径，就优先把复杂性删掉，而不是搬家。
 
 本 work 只审查、呈现和访谈，不直接修改产品代码。报告阶段只产出 Markdown 决策记录，不生成 HTML。
 
-本 work 的候选筛选、排序和删除测试见 `<Path>{roots.workflows}/specdev/R-review-architecture/review-rubric.md</Path>`。审查语言必须使用 module、interface、depth、seam、adapter、leverage、locality。
+本 work 的候选筛选、排序和删除测试见 `<Path>{roots.workflows}/specdev/R-review-architecture/review-rubric.md</Path>`。沿用 CONTEXT 与共享设计词汇（module、interface、depth、seam、adapter、leverage、locality）准确表达含义，不为机械出现英文而牺牲理解。
 
-## 读取范围
-
-1. 先读取 `<Path>{roots.workflows}/specdev/README.md</Path>` 与当前 Work 的状态入口。
-2. 再读取 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`、`<Path>{roots.workflows}/specdev/common/rules/codebase-design.md</Path>` 和 `<Path>{roots.workflows}/specdev/common/rules/evidence-and-verification.md</Path>`，按当前分支、状态和关键词定位最小相关工件。
-3. 只在本 Work 明确要求恢复、冲突、执行安全或归档证据时扩展为全量读取；缺少匹配证据或 owner/gateway 时停止受影响分支。
-4. 用户指定范围优先于 Git 热点；若未指定，则从最近 churn、重复编辑和报错/回归轨迹中找出最值得审查的 module。
+激活时读取 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`，按当前步骤定位输入和证据。
 
 ## 输入与产物
 
@@ -43,7 +38,14 @@ keywords: [架构审查, 维护性, 浅模块, 深模块, 局部性, 杠杆, 接
 
 每个候选都必须说明：files、structural problem、code-judo move、deleted complexity、dependency class、strength、ADR conflict、interview state 和 user conclusion。文件若因为本次变化接近或超过 1k lines，必须显式标注 decomposition pressure，不得默默吞掉。
 
-## 流程
+## 选择交付分支
+
+- `report`（默认）：用户只请求 review/扫描时完成下方探索与报告，候选保持 `unselected`；没有候选是有效结果，不要求用户先选方案才完成报告。
+- `selected-design`：只有用户已经选择一个候选并请求深入设计，才加载 `<Path>{roots.workflows}/specdev/R-review-architecture/references/selected-design.md</Path>`。输入是可回读报告和所选候选；来源漂移先核对影响，不用旧结论代替当前代码。
+
+两分支均不修改生产代码，报告不授权访谈、建票或实施。
+
+## Report 流程
 
 ### 1. 探索
 
@@ -53,18 +55,8 @@ keywords: [架构审查, 维护性, 浅模块, 深模块, 局部性, 杠杆, 接
 - 否则翻阅足够长的 `git log --oneline`，找出反复出现的 files、call sites 和 test surfaces；
 - 变更散落、没有明确热点时才扩大搜索范围；
 - 只接受能通过删除测试的候选：删掉该 module 后，复杂性应集中或消失，而不是换一个地方继续蔓延；
-- 优先挑出结构性回归、重复 special cases、wrong-layer logic、thin wrappers、identity abstractions、type boundary drift、sequential orchestration 和 file-size/decomposition pressure；
-- 如果一个更 canonical 的 helper 已经存在，优先复用它；如果 proposal 只是 rearrange complexity，不算候选。
-
-首先阅读项目领域词汇和接触区域的 ADR。然后有机探索 codebase，注意哪里会让 maintenance knowledge 分散：
-
-- 哪些 module 是 shallow，interface 几乎与 implementation 一样复杂；
-- 哪些 seam 正在 leak；
-- 哪些纯函数只是为了可测试性被拆出，但 bug 实际藏在缺少 locality 的调用方式中；
-- 哪些模块因为 ad-hoc conditionals、mode flags 或 one-off branches 变得更 spaghetti；
-- 哪些区域正在把 feature logic 泄漏进 shared path 或 canonical helper 之外；
-- 哪些结构已经逼近或超过 1k lines，应该先 decomposition 再 review；
-- 哪些 orchestration 本可以并行或更 atomic，却被无谓串行化。
+- 逐项应用 `<Path>{roots.workflows}/specdev/R-review-architecture/review-rubric.md</Path>` 的结构压力、删除测试与排序规则；
+- 先读取项目领域词汇及当前区域 ADR；探索真实调用和测试表面，过滤仅 rearrange complexity 的提案。
 
 对每个怀疑对象应用删除测试。候选必须有真实路径、调用或测试证据，并说明不做的实际后果。与业务目标、近期变化压力、测试改善或风险降低无关的候选过滤掉。若没有任何候选通过这条线，明确写出“没有高置信候选”，不要为了填表而硬造一个。
 
@@ -86,46 +78,16 @@ keywords: [架构审查, 维护性, 浅模块, 深模块, 局部性, 杠杆, 接
 - **依赖类别**——`in-process | local-substitutable | ports & adapters | mock`；
 - **ADR 冲突**——只在摩擦真实到值得重审时显示警告。
 
-报告以“最佳推荐”结束；若没有高置信候选，就明确写 `无高置信候选`。此时**不提出 interface**，只询问用户想探索哪一个候选，或者为何没有候选。
+报告以“最佳推荐”结束；若没有高置信候选，就明确写 `无高置信候选`。报告阶段**不提出 interface**；返回候选和证据即可，不强制追加选择问题。
 
 **完成标准**：每个候选字段完整、最佳推荐唯一或明确为空，Markdown 已原子写入并重读。
 
-### 3. 访谈用户选择的一个候选
-
-用户选择候选后，调用 `<Path>{roots.workflows}/specdev/G-grill-with-docs/G-grill-with-docs.md</Path>`，用完整 frontier 遍历约束、依赖、deep module 形状、seam 后面的内容和保留测试。
-
-决策结晶时保持领域模型同步：
-
-- 新概念加入 change CONTEXT；永久 CONTEXT 不存在时延迟到归档提升；
-- 模糊术语当场精炼；
-- 用户的选择同时难以逆转、没有上下文会令人惊讶且来自真实权衡时，询问是否记录 ADR；任一条件不满足就留在 LOG/Ticket，不制造 ADR；
-- 替代 interface 需要探索时使用 `<Path>{roots.workflows}/specdev/I-implement/design-it-twice.md</Path>`；
-- 如果候选最终只是把复杂性搬家，而不是删掉它，在访谈中直接回退，不把它升级成 Ticket。
-
-将选择、访谈状态与结论同步到 Markdown；每次运行只访谈用户选择的候选，不批量迫使用户决定所有卡片。
-
-**完成标准**：被选候选的设计树达到共识或明确 blocked；领域词汇、LOG、ADR 和审查报告一致。
-
-### 4. 转化为执行工作
-
-只有被接受且有具体变更压力的提案进入 `<Path>{roots.workflows}/specdev/T-tickets/T-tickets.md</Path>`。加载 `<Path>{roots.workflows}/specdev/R-review-architecture/proposal-to-ticket.md</Path>`，按 Prefactor、Standard 或 Deep/expand-contract 建立 Ready 治理；只有能删除复杂性的提案才继续，纯重排和 thin wrapper 不进入 Ticket。
+## 分支完成、状态与返回
 
-## 完成标准
+`report` 完成条件：范围有依据；高置信候选满足删除测试且每项有当前文件/调用/测试证据、前后对比、收益、强度和 ADR 冲突处理；最佳推荐唯一或明确为“无高置信候选”；Markdown 已原子写入并回读。未选择或拒绝的候选不变成 Ticket。
 
-- 范围来自用户方向或 Git 热点，未进行无边界扫描；
-- 每个候选通过删除测试并有真实代码压力；
-- 领域使用 CONTEXT 词汇，架构严格使用共享词汇；
-- Markdown 决策记录可重读；
-- 每个候选有前后对比、强度、收益和 ADR 冲突处理；
-- 报告阶段没有提前设计 interface；
-- 用户选择的一个候选完成完整 frontier 访谈；
-- 接受项进入 Ticket 治理，没有直接修改产品代码；
-- 没有把结构性弱候选包装成最佳推荐。
+`selected-design` 完成条件：用户选定的一个候选完成参考中的完整 frontier 访谈，或明确 blocked/rejected；只有接受且达成共识的方案才按原 Ticket 治理交接。其他候选保持未选择，不批量要求决定。
 
-## 子文件引用
+按本分支真实结果更新 Work 状态：成功才把本 Work 去重加入 `works_run` 并清空 `current_work`，blocked 保留恢复键和原因。报告完成不是产品交付；只有请求本来以非实现审查为终点且满足 `<Path>{roots.workflows}/specdev/common/rules/change-completion.md</Path>`，该终点 owner 才可关闭 change。
 
-- 共享设计规则：`<Path>{roots.workflows}/specdev/common/rules/codebase-design.md</Path>`
-- 证据与验证：`<Path>{roots.workflows}/specdev/common/rules/evidence-and-verification.md</Path>`
-- 审查准则：`<Path>{roots.workflows}/specdev/R-review-architecture/review-rubric.md</Path>`
-- Markdown 模板：`<Path>{roots.workflows}/specdev/R-review-architecture/architecture-review-template.md</Path>`
-- 提案转 Ticket：`<Path>{roots.workflows}/specdev/R-review-architecture/proposal-to-ticket.md</Path>`
+返回分支、报告完整路径、审查范围/排除范围、代码证据、候选结论、实际验证与未验证项；有选择时再返回相应设计树/下一 Work。结构检查不证明设计判断正确，不能把弱候选包装成最佳推荐。

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

@@ -64,5 +64,6 @@ status: draft
 
 ## 5. 下一步
 
-- 报告生成后询问用户选择一个候选，不批量访谈。
+- 当前请求：report / selected-design。report 到此完成，访谈状态可为 unselected；无高置信候选也可交付。
+- 用户选择原文与候选 ID：仅 selected-design 填写；未选择时不虚构结论、不自动转票。
 - 达成共识的接受项进入 `<Path>{roots.workflows}/specdev/T-tickets/T-tickets.md</Path>`。

package/template/workflows/specdev/R-review-architecture/references/selected-design.md

@@ -0,0 +1,23 @@
+# 已选架构候选的设计与转票
+
+用户选定一个候选后读取；保持审查报告和 change 内决策同步，不修改生产代码。
+
+### 3. 访谈用户选择的一个候选
+
+用户选择候选后，调用 `<Path>{roots.workflows}/specdev/G-grill-with-docs/G-grill-with-docs.md</Path>`，用完整 frontier 遍历约束、依赖、deep module 形状、seam 后面的内容和保留测试。
+
+决策结晶时保持领域模型同步：
+
+- 新概念加入 change CONTEXT；永久 CONTEXT 不存在时延迟到归档提升；
+- 模糊术语当场精炼；
+- 用户的选择同时难以逆转、没有上下文会令人惊讶且来自真实权衡时，询问是否记录 ADR；任一条件不满足就留在 LOG/Ticket，不制造 ADR；
+- 替代 interface 需要探索时使用 `<Path>{roots.workflows}/specdev/common/rules/design-it-twice.md</Path>`；
+- 如果候选最终只是把复杂性搬家，而不是删掉它，在访谈中直接回退，不把它升级成 Ticket。
+
+将选择、访谈状态与结论同步到 Markdown；每次运行只访谈用户选择的候选，不批量迫使用户决定所有卡片。
+
+**完成标准**：被选候选的设计树达到共识或明确 blocked；领域词汇、LOG、ADR 和审查报告一致。
+
+### 4. 转化为执行工作
+
+只有被接受且有具体变更压力的提案进入 `<Path>{roots.workflows}/specdev/T-tickets/T-tickets.md</Path>`。加载 `<Path>{roots.workflows}/specdev/R-review-architecture/proposal-to-ticket.md</Path>`，按 Prefactor、Standard 或 Deep/expand-contract 建立 Ready 治理；只有能删除复杂性的提案才继续，纯重排和 thin wrapper 不进入 Ticket。

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

@@ -1,8 +1,8 @@
 # 架构审查准则
 
-本准则只在 `<Path>{roots.workflows}/specdev/R-review-architecture/R-review-architecture.md</Path>` 激活时生效。它把热核级维护性标准转成候选筛选和排序规则。
+本准则只在 `<Path>{roots.workflows}/specdev/R-review-architecture/R-review-architecture.md</Path>` 激活时生效。它把实际维护压力转成候选筛选和排序规则；每个结论都要有路径、调用或测试证据。
 
-使用 `<Path>{roots.workflows}/specdev/common/rules/codebase-design.md</Path>` 的术语：module、interface、depth、seam、adapter、leverage、locality。描述架构时不要滑向更弱的替代词。
+使用 `<Path>{roots.workflows}/specdev/common/rules/codebase-design.md</Path>` 的术语：module、interface、depth、seam、adapter、leverage、locality。优先保持项目共享含义；中文解释可与专业词并列，不要求机械复述每个词。
 
 ## 重点观察