@namewta/speculo 0.6.0 → 0.7.0

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

@@ -3,85 +3,82 @@ id: specdev/diagnose-bugs
 type: workflow-entry
 workflow: specdev
 name: 诊断 Bug
-description: 通过复现、反馈回路、可证伪假设与最小插桩定位根因，输出修复契约而不是猜测性补丁。
-keywords: [bug, 诊断, 根因, 复现, 假设]
+description: 先建立会在精确症状上变红的紧凑反馈回路，再通过最小化、排名假设和单变量探针确认根因，输出修复契约而不实施生产修复。
+keywords: [bug, 诊断, 红灯, tight-loop, 根因, 复现, 假设]
 ---
 
 # 诊断 Bug
 
-诊断阶段默认只读项目代码；可以在当前 change 内创建诊断记录，并进行临时、可撤销的本地实验。未经用户授权，不提交修复、不部署、不执行不可逆操作。
+D 的主导词是**红灯**：没有一条已执行且能在此 bug 上变红的紧凑命令，就没有可进入的假设阶段。D 默认只读项目代码，可以创建 change 诊断工件和经授权的临时可撤销探针；生产修复由 Implement 拥有。
 
-## 输入与产物
+## 输入与所有权
 
-- 原始请求：`<Path>{roots.state}/specdev/changes/{change}/source-issue.md</Path>`
-- 分诊结果：`<Path>{roots.state}/specdev/changes/{change}/triage.md</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}/diagnosis.md</Path>`
-- 诊断模板：`<Path>{roots.workflows}/specdev/D-diagnose-bugs/diagnosis-template.md</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}/CONTEXT.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`
+- 相关代码、测试、配置、日志和运行环境事实。
 
-### 1. 建立最短反馈回路
+D 拥有：
 
-定义最短复现命令、输入、环境、期望、实际、复现率和观测位置。不能稳定复现时，先缩小观测范围、记录环境差异或建立最小探针，不直接修改业务逻辑。
+- `<Path>{roots.state}/specdev/changes/{change}/diagnosis.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/diagnostics/</Path>`，仅在需要脚本、捕获物或临时探针结果时延迟创建。
 
-### 2. 收集事实
+## 流程
 
-读取相关日志、调用链、测试、配置、版本差异、最近变更、运行环境和相邻成功路径。所有条目标注为事实、推断或用户报告；不得把日志缺失当作行为不存在。
+### 1. 建立并执行红灯回路
 
-外部依赖、版本行为或协议不清楚时，使用 `<Path>{roots.workflows}/specdev/common/skills/research/SKILL.md</Path>`。
+加载 `<Path>{roots.workflows}/specdev/D-diagnose-bugs/feedback-loop.md</Path>`。按其顺序尝试测试、HTTP/CLI、浏览器、追踪回放、夹具、模糊循环、bisect、差分和最终 HITL。保存命令、至少一次真实输出、精确症状断言、运行时间、确定性或复现率，以及 Agent 可运行性。
 
-### 3. 假设排名
+无法建立回路时立即使用诊断模板写 `status: blocked`、`feedback_loop_ready: false`、已尝试方式和所需输入；假设表保持为空，保留 `current_work` 后返回。不得继续阅读代码来构造根因理论。
 
-列出 3–7 个可证伪假设，按“证据支持度 × 解释范围 ÷ 验证成本”排序。每个假设必须说明：
+**完成标准**：一条已运行命令快速、可重复、由 Agent 执行，并能在用户精确症状上变红。
 
-- 支持证据；
-- 预期可观察结果；
-- 反证实验；
-- 若被证伪，下一个候选是什么。
+### 2. 复现并最小化
 
-### 4. 最小实验
+运行回路确认捕获的是用户报告的故障。逐个删除输入、调用者、配置、数据和步骤，每次删除后重跑；只保留对红灯有负载作用的元素。非确定性 bug 通过并行、压力、固定时间/随机或缩小窗口提高到可调试复现率。
 
-一次只改变一个变量。优先使用定向测试、断言、日志、追踪、调试器、配置切换或隔离环境。插桩必须可移除，不得把诊断日志、永久重试或吞错当作修复。
+**完成标准**：剩余每个元素被移除都会使回路变绿，最小复现和最后红灯证据已持久化。
 
-### 5. 根因确认
+### 3. 假设与单变量探针
 
-根因必须同时解释：
+只有前两步完成后才加载 `<Path>{roots.workflows}/specdev/D-diagnose-bugs/hypothesis-and-instrumentation.md</Path>`。生成 3–5 个带预测的可证伪假设，先展示排名；用户 AFK 时保存 checkpoint 后继续。每个探针只检验一个预测，优先 debugger/REPL，其次定向日志；性能问题使用测量和分析器。
 
-- 触发条件；
-- 失败机制；
-- 为什么此前未被测试或监控捕获；
-- 影响范围；
-- 为什么拟议修复能阻断机制；
-- 修复可能引入的回归风险。
+**完成标准**：根因由区分性实验确认，其他高排名候选有反证，所有临时探针有唯一清理标记。
 
-只能缓解症状时明确标注 workaround，不宣称根因已确认。
+### 4. 写入修复契约
 
-### 6. 写入修复契约
+使用 `<Path>{roots.workflows}/specdev/D-diagnose-bugs/diagnosis-template.md</Path>` 写入 diagnosis：触发条件、失败机制、影响范围、漏检原因、必须改变、必须保持、正确 seam、回归测试、非目标、风险和回滚。
 
-使用 `<Path>{roots.workflows}/specdev/D-diagnose-bugs/diagnosis-template.md</Path>` 写入 `<Path>{roots.state}/specdev/changes/{change}/diagnosis.md</Path>`，包含根因、受影响范围、修复不变量、回归测试、非目标、风险和回滚。
+存在正确 seam 时，把最小复现定义为 I 必须先观察红灯的回归测试合同；不存在正确 seam 时明确记录架构缺口并路由 R。D 不编写生产修复。
 
-修复前回归测试应失败，修复后应通过。诊断产物不夹带未经批准的实现。
+### 5. 清理、验证与路由
 
-### 7. 发布诊断
+重跑原始未最小化回路，确认当前诊断结论可解释症状；搜索唯一 `[DEBUG-...]` 前缀并删除临时插桩，无法删除项登记 owner 与删除条件。运行：
 
-同步 `<Path>{roots.state}/specdev/status.json</Path>` 的 `current_work`、`work_history` 和当前 change 状态，返回 `<Path>{roots.state}/specdev/changes/{change}/diagnosis.md</Path>`、状态及下一 Work 的完整路径。
+```bash
+node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> \
+  --stage diagnosis \
+  <Path>{roots.state}/specdev/changes/{change}</Path>
+```
 
-- 单一、局部、低风险且契约完全明确：可进入 `<Path>{roots.workflows}/specdev/T-tickets/T-tickets.md</Path>` 生成 Lite/Standard Ticket，或在用户批准后由 `<Path>{roots.workflows}/specdev/I-implement/I-implement.md</Path>` 使用 Direct Spec 模式；
-- 多行为、公共接口、迁移、安全或高风险：进入 `<Path>{roots.workflows}/specdev/S-spec/S-spec.md</Path>` 或 `<Path>{roots.workflows}/specdev/T-tickets/T-tickets.md</Path>`；
-- 根因仍未知：保持 blocked，继续诊断或进入 `<Path>{roots.workflows}/specdev/W-wayfinder/W-wayfinder.md</Path>`。
+根因确认后将本 Work 加入 `works_run` 并清空 `current_work`，返回 diagnosis 和下一 Work：局部修复进入 Tickets/I，公共行为或高风险进入 S/Tickets，缺 seam 进入 R，仍无根因则保持 blocked 或进入 W。
 
 ## 完成标准
 
-- 有可重复复现，或明确说明为何暂时无法复现；
-- 根因有证据和反证过程；
-- 回归测试契约在修复前应失败；
-- 诊断产物区分根因、workaround 和残余未知；
-- 修复契约决策完备；
-- 状态、诊断路径和下一 Work 路径已返回；
-- 未在诊断阶段偷偷提交修复。
+- 红灯回路硬门有已执行证据；
+- 最小复现的剩余元素都有负载作用；
+- 假设有排名、预测和反证；
+- 根因解释触发、机制、漏检和影响；
+- 修复契约决策完备但未夹带生产修复；
+- debug 插桩已清理或有明确 owner；
+- diagnosis、状态、验证证据和下一 Work 路径一致。
 
 ## 子文件引用
 
+- 反馈回路：`<Path>{roots.workflows}/specdev/D-diagnose-bugs/feedback-loop.md</Path>`
+- 假设与插桩：`<Path>{roots.workflows}/specdev/D-diagnose-bugs/hypothesis-and-instrumentation.md</Path>`
 - 诊断模板：`<Path>{roots.workflows}/specdev/D-diagnose-bugs/diagnosis-template.md</Path>`
+- HITL 模板：`<Path>{roots.workflows}/specdev/D-diagnose-bugs/scripts/hitl-loop.template.sh</Path>`

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

@@ -1,64 +1,68 @@
-# Diagnosis: <问题>
+---
+schema_version: 1
+artifact: diagnosis
+change: <YYYY-MM-DD-topic>
+status: reproducing
+feedback_loop_ready: false
+red_command: null
+red_evidence: null
+cleanup_status: pending
+updated_at: <ISO-8601>
+---
 
-- **Change：** `<change>`
-- **来源：** `<Path>{roots.state}/specdev/changes/{change}/source-issue.md</Path>` / `<Path>{roots.state}/specdev/changes/{change}/triage.md</Path>`
-- **诊断状态：** gathering / reproducing / testing-hypotheses / root-cause-confirmed / blocked
-- **诊断工件：** `<Path>{roots.state}/specdev/changes/{change}/diagnosis.md</Path>`
+# Diagnosis: <问题>
 
 ## 1. 现象与影响
 
-只记录可观察现象、受影响对象、严重度和时间范围；把解释留到假设部分。
+只记录可观察现象、受影响对象、严重度和时间范围。
 
-## 2. 复现契约
+## 2. 红灯反馈回路
 
-- **环境：** 版本、配置、数据前置条件
-- **输入/步骤：** 最小稳定复现路径
-- **期望：** 来自契约、测试或已确认行为
-- **实际：** 可观察输出
-- **复现率：**
-- **对照组：** 能正常工作的最接近路径
-- **相关路径：** `<Path>src/example.ts</Path>` / 无
+- **命令：**
+- **至少一次真实输出：**
+- **精确症状断言：**
+- **耗时：**
+- **确定性/复现率：**
+- **Agent 可运行性：** autonomous / structured-HITL
+- **无法建立时已尝试方式和所需输入：** 不适用 / ...
 
-## 3. 证据时间线
+`feedback_loop_ready: false` 时以下假设表必须为空。
 
-| 时间/阶段 | 观察 | 来源 | 可信度 |
-|---|---|---|---|
-| ... | ... | 日志、测试、代码、配置或用户报告 | high / medium / low |
+## 3. 最小复现
 
-## 4. 假设与证伪
+- **环境与输入：**
+- **剩余步骤：**
+- **逐项删除证据：**
+- **最后红灯证据：**
+- **捕获物：** 无 / `<Path>{roots.state}/specdev/changes/{change}/diagnostics/<artifact></Path>`
 
-| 排名 | 可证伪假设 | 支持证据 | 区分性实验 | 预期反证 | 结果 |
-|---|---|---|---|---|---|
-| 1 | ... | ... | ... | ... | confirmed / rejected / pending |
+## 4. 假设与证伪
 
-每个实验应尽量只区分一个机制。插桩、日志或临时探针必须记录撤销方式，不能成为无主永久代码。
+| 排名 | 假设与预测 | 支持证据 | 单变量实验 | 结果 |
+|---|---|---|---|---|
 
 ## 5. 已确认根因
 
 - **触发条件：**
-- **失败机制：** 从输入到错误结果的因果链
+- **失败机制：**
 - **根因位置：** `<Path>src/example.ts</Path>`
-- **为何不是其他候选：**
-- **漏检原因：** 测试、监控、契约或流程缺口
-- **确认实验：** 能稳定使问题出现和消失的最小变化
-
-根因未确认时不得把“最可能”写成结论，也不得直接把 change 标记为实现就绪。
+- **漏检原因：**
+- **为何排除其他候选：**
+- **确认实验：**
 
 ## 6. 修复契约
 
 - **必须改变：**
-- **必须保持：** 不变量、兼容性和无关行为
-- **回归测试：** 能在旧实现失败、修复后通过的验证
-- **防复发措施：** 测试、监控、断言或治理修正
-- **OUT：** 本次明确不处理的相邻问题
+- **必须保持：**
+- **正确测试 seam：** `<Path>test/example.test.ts</Path>` / 缺失并路由 R
+- **回归测试：** 修复前红、修复后绿的具体合同
+- **OUT：**
 - **风险与回滚：**
 - **推荐下游：** S-spec / T-tickets / I-implement / R-review-architecture
 
-## 7. 诊断完成门禁
+## 7. 清理
 
-- [ ] 复现或无法复现的边界已明确；
-- [ ] 根因由区分性证据支持；
-- [ ] 症状、触发条件与失败机制没有混为一谈；
-- [ ] 回归验证可执行；
-- [ ] 修复边界与必须保持项明确；
-- [ ] 未撤销的临时插桩为零，或已登记 owner 与后续删除条件。
+- **原始回路重跑：**
+- **`[DEBUG-...]` 搜索：**
+- **一次性脚本/原型：**
+- **未清理项 owner 与删除条件：** 无 / ...

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

@@ -0,0 +1,41 @@
+# 红灯反馈回路
+
+本文件只负责阶段 1–2。回路尚未满足完成门时，不加载假设或修复材料。
+
+## 构建顺序
+
+按大致顺序穷尽适用方式：
+
+1. 能触及 bug 的失败测试；
+2. 针对开发服务器的 curl/HTTP 脚本；
+3. 固定输入的 CLI 调用和已知良好输出 diff；
+4. 对 DOM、控制台或网络断言的无头浏览器脚本；
+5. 回放真实请求、负载、事件或追踪捕获物；
+6. 启动最小系统子集的一次性夹具；
+7. 属性或模糊测试循环；
+8. 可供 `git bisect run` 使用的状态检查夹具；
+9. 旧/新版本或配置的差分循环；
+10. 最后手段：复制并定制 `<Path>{roots.workflows}/specdev/D-diagnose-bugs/scripts/hitl-loop.template.sh</Path>`。
+
+## 收紧
+
+把回路当作需要优化的产品：缩小启动范围和测试目标；断言精确症状而非“没有崩溃”；固定时间、随机、文件系统与网络。记录一次运行耗时和复现率。
+
+非确定性问题以提高复现率为目标：批量运行、并行、增加压力、缩小时间窗口或注入 sleep，直到失败率稳定到可调试区间。
+
+## 最小化
+
+看见正确红灯后，逐项删除输入、调用者、配置、数据和步骤，每次只删除一项并重跑。删除后仍红则永久移除；变绿则恢复。完成时剩余每一项都承载故障。
+
+## 无法建立回路
+
+停止并列出尝试过的方式，请求以下之一：可复现环境、HAR/日志/core dump/带时间戳录屏等捕获物，或临时生产插桩授权。没有红灯不得进入假设。
+
+## 完成门
+
+- 命令已至少运行一次并保存调用与输出；
+- 驱动真实 bug 路径并断言用户精确症状；
+- 结果确定，或有稳定且足够高的复现率；
+- 秒级或已证明是当前最短可行回路；
+- Agent 可无人值守运行，或由结构化 HITL 脚本捕获结果；
+- 最小复现的每个剩余元素都有负载作用。

package/template/workflows/specdev/D-diagnose-bugs/hypothesis-and-instrumentation.md

@@ -0,0 +1,32 @@
+# 假设与单变量插桩
+
+只在反馈回路已变红并最小化后加载。
+
+## 排名假设
+
+在测试前生成 3–5 个候选，按证据支持度、解释范围和验证成本排序。每个候选使用：
+
+> 如果 X 是原因，那么改变 Y 会让红灯消失，或改变 Z 会使其更明显。
+
+无法给出可观察预测的候选不是假设。测试前向用户展示排名；用户 AFK 时记录该 checkpoint 并按排名继续。
+
+## 探针
+
+每个探针只映射一个预测，一次只改变一个变量：
+
+1. 环境支持时优先 debugger 或 REPL；
+2. 其次在区分假设的边界放置定向日志；
+3. 每条临时日志使用同一唯一前缀，如 `[DEBUG-a4f2]`；
+4. 性能分支建立计时/分析器/查询计划基线，再执行二分；
+5. 不使用“记录全部再 grep”代替实验设计。
+
+## 根因确认
+
+确认项必须同时解释触发条件、失败机制、漏检原因、影响范围、修复为何阻断机制及回归风险。只能缓解症状时标为 workaround。没有正确测试 seam 时记录架构发现并路由 Architecture Review。
+
+## 完成门
+
+- 每个已测候选有预测、实验、结果和结论；
+- 确认根因能让红灯出现和消失；
+- 其他高排名候选有区分性反证；
+- 临时探针有唯一前缀、owner 和清理结果。

package/template/workflows/specdev/D-diagnose-bugs/scripts/hitl-loop.template.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# Human-in-the-loop reproduction loop. Copy and edit the steps, then let the
+# Agent run the script while the user performs the prompted actions.
+
+set -euo pipefail
+
+step() {
+  printf '\n>>> %s\n' "$1"
+  read -r -p "    [Enter when done] " _
+}
+
+capture() {
+  local var="$1" question="$2" answer
+  printf '\n>>> %s\n' "$question"
+  read -r -p "    > " answer
+  printf -v "$var" '%s' "$answer"
+}
+
+# Replace these example steps with the exact reproduction.
+step "Open the affected screen and prepare the failing action."
+capture ERRORED "Run the action. Did the exact symptom occur? (y/n)"
+capture ERROR_MSG "Paste the exact error or observed output (or 'none'):"
+
+printf '\n--- Captured ---\n'
+printf 'ERRORED=%s\n' "$ERRORED"
+printf 'ERROR_MSG=%s\n' "$ERROR_MSG"

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

@@ -42,7 +42,7 @@ keywords: [认知导师, 教学, why, bug, 源码研究, 技术方案, 架构,
 
 按存在情况读取：
 
-- 原始请求：`<Path>{roots.state}/specdev/changes/{change}/source-issue.md</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}/CONTEXT.md</Path>`
@@ -74,7 +74,7 @@ keywords: [认知导师, 教学, why, bug, 源码研究, 技术方案, 架构,
 2. 选择用户指定 change、唯一活跃 change，或按 SpecDev 协议创建新 change；多个候选必须先消歧；
 3. 确认 `<Path>{roots.state}/specdev/config.json</Path>` 存在；不存在时先进入 `<Path>{roots.workflows}/specdev/I-init-setup/I-init-setup.md</Path>`；
 4. 读取全局状态、change 状态和已有主产物；存在未完成会话时从其 `current_phase` 与未决问题恢复，不重新盘问已记录内容；
-5. 以 `specdev/engineering-cognitive-mentor` 更新 `current_work`，创建或复用唯一未完成的 `work_history` 记录；
+5. 若当前 change 的 `current_work` 已是 `specdev/engineering-cognitive-mentor` 则恢复；为 null 时设置为该 id；指向其他 Work 时停止并先完成显式 handoff；
 6. 主产物不存在时按模板初始化，存在时只做兼容性读取和真实增量更新。
 
 **完成标准：**workspace 与 change 唯一；状态已登记；主产物已初始化或成功恢复；没有覆盖历史记录。
@@ -204,7 +204,7 @@ keywords: [认知导师, 教学, why, bug, 源码研究, 技术方案, 架构,
 - 用户确认当前没有其他问题，或剩余问题被显式延后；
 - 主产物包含完整 `MLOG`、最终综合和后续路线。
 
-关闭时更新全局状态与 change 状态，完成 `work_history`，将本 Work 加入 `works_run`，并返回主产物完整路径及适用的下一 Work 完整路径。关闭本 Work 不等于完成或归档整个 change。
+关闭时更新全局状态与 change 状态，将本 Work 去重加入 `works_run` 并清空 `current_work`，返回主产物完整路径及适用的下一 Work 完整路径。关闭本 Work 不等于完成或归档整个 change。
 
 **完成标准：**主产物状态与全局状态一致；完整日志可恢复；未伪造理解或 change 完成状态。
 

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

@@ -25,26 +25,13 @@ change 状态：`<Path>{roots.state}/specdev/changes/{change}/.status.json</Path
 ### 开始
 
 - 在 `active` 中找到或创建当前 change；
-- 设置该 change 的 `current_work` 为 `specdev/engineering-cognitive-mentor`；
+- `current_work` 已是 `specdev/engineering-cognitive-mentor` 时恢复，为 null 时设置为该 id；指向其他 Work 时停止并要求先完成显式 handoff；
 - `<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>` 的 `current_work` 同步设置为相同值；
-- 在 `work_history` 中查找该 change 与 work id 的未完成记录；存在唯一一条时复用，不重复创建；不存在时追加：
-
-```json
-{
-  "change": "<change>",
-  "work_id": "specdev/engineering-cognitive-mentor",
-  "started_at": "<ISO-8601>",
-  "completed_at": null,
-  "result": null
-}
-```
-
-若存在两条以上未完成记录，记录状态异常并停止自动写入，先请求消歧或修复。
+- 全局索引不创建逐次调用日志；开始时间与恢复阶段由主产物 frontmatter、MLOG 和 `<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>` 承载。
 
 ### 等待用户或跨会话暂停
 
 - 保持 `current_work` 为本 Work；
-- 保持唯一 `work_history` 记录未完成；
 - 更新主产物 `updated_at`、`current_phase`、`next_question`、`unresolved_questions` 与 `last_mlog_id`；
 - 每轮在回复前先落盘，确保用户即使中断也可恢复。
 
@@ -52,10 +39,9 @@ change 状态：`<Path>{roots.state}/specdev/changes/{change}/.status.json</Path
 
 ### 正常关闭
 
-- 将唯一未完成 `work_history` 的 `completed_at` 写为当前时间，`result` 写为 `completed`；
 - 将本 Work id 以去重方式加入 active change 的 `works_run`；
 - active change 的 `current_work` 与 `<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>` 的 `current_work` 设为 null；
-- 不改变整个 change 的 `result` 或 `change_status`，除非用户明确结束、取消或外部阻塞确实影响整个 change；
+- 不改变整个 change 的 `change_status`，除非用户明确结束或外部阻塞确实影响整个 change；
 - 主产物 `status` 写为 `completed`，记录 `closed_at` 与理解确认状态。
 
 ### 外部阻塞
@@ -64,15 +50,14 @@ change 状态：`<Path>{roots.state}/specdev/changes/{change}/.status.json</Path
 
 - 主产物 `status: blocked`；
 - 记录 blocker、已知事实、所需输入和恢复条件；
-- 完成当前 `work_history`，结果为 `blocked`；
+- 保留 `current_work` 作为唯一恢复指针；
 - change 是否设为 blocked 取决于该阻塞是否阻止整个 change，不自动扩大。
 
 ### 用户取消
 
 - 主产物 `status: cancelled`；
 - 保存当前综合和完整 MLOG；
-- `work_history.result` 写为 `cancelled`；
-- 清空 current_work；
+- 清空全局与 change 状态的 `current_work`，但不将本 Work 加入 `works_run`；
 - 不删除工件或日志。
 
 ## 3. 主产物幂等初始化

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

@@ -3,7 +3,7 @@ id: specdev/grill-with-docs
 type: workflow-entry
 workflow: specdev
 name: 设计访谈（带文档）
-description: 以完整 frontier 逐轮推进设计树，直到每个决策分支都已关闭并获得用户共识，同时持续维护设计树、日志、领域上下文和架构决策。
+description: 以完整 frontier 逐轮推进设计树，直到每个决策分支都已关闭并获得用户共识，同时持续维护当前 change 的设计树、日志、领域上下文和架构决策。
 keywords: [设计访谈, grilling, design-tree, frontier, ADR, LOG, CONTEXT, 决策, 领域建模]
 ---
 
@@ -13,16 +13,16 @@ keywords: [设计访谈, grilling, design-tree, frontier, ADR, LOG, CONTEXT, 决
 
 按**轮次**推进这棵树。**前沿（frontier）** 是所有前置条件已经确定的决策——那些现在就能问、不必猜测尚未得到答案的问题。每轮询问完整 frontier；用户的答案会重塑设计树并解除下一层问题的阻塞。
 
-本 work 还负责把访谈持久化：设计树保存可恢复状态，LOG 保存讨论轨迹，CONTEXT 保存当前领域真相，ADR 保存长期架构决定。持久化不构成实现授权；在用户确认共识前不进入实现。
+本 work 只把访谈写成当前 change 的可恢复工件：设计树保存进度，LOG 保存讨论轨迹，CONTEXT 保存本 change 已确认的规范语言，ADR 保存已成为本 change 下游合同的架构决定。这些工件不等于项目永久知识，也不构成实现授权；永久 namespace 对 G 只读，只有 `<Path>{roots.workflows}/specdev/A-archive-and-consolidate/A-archive-and-consolidate.md</Path>` 能在实现证据、毕业评估和用户确认通过后执行提升。
 
 ## 输入与产物
 
 按存在情况读取：
 
 - `<Path>{roots.state}/specdev/config.json</Path>`
-- `<Path>{roots.state}/specdev/adr/</Path>`
-- `<Path>{roots.state}/specdev/context/</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/source-issue.md</Path>`
+- `<Path>{roots.state}/specdev/adr/</Path>`（只读永久基线）
+- `<Path>{roots.state}/specdev/context/</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}/spec.md</Path>`
@@ -35,6 +35,7 @@ keywords: [设计访谈, grilling, design-tree, frontier, ADR, LOG, CONTEXT, 决
 - `<Path>{roots.state}/specdev/changes/{change}/LOG.md</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}/questionnaires/</Path>`，仅在第三方 stakeholder 持有阻塞答案时延迟创建。
 
 不存在的可选输入静默跳过，不把缺失文件伪装成已知事实。
 
@@ -67,6 +68,8 @@ keywords: [设计访谈, grilling, design-tree, frontier, ADR, LOG, CONTEXT, 决
 - 高影响决策：进入设计树；
 - 低影响实现细节：记录为实现者可自行决定，不制造决策节点。
 
+阻塞答案既不可发现、当前用户也无法回答、但另一个明确 stakeholder 掌握时，加载 `<Path>{roots.workflows}/specdev/G-grill-with-docs/stakeholder-questionnaire.md</Path>`，生成问卷并保存恢复条件；不在本轮继续猜测该分支。
+
 **完成标准**：每个候选问题已分类；用户只接收无法从环境发现的真实决策。
 
 ### 3. 建立设计树
@@ -92,18 +95,20 @@ keywords: [设计访谈, grilling, design-tree, frontier, ADR, LOG, CONTEXT, 决
 
 **完成标准**：本轮开始时的完整 frontier 每个节点都有回答、明确延后或阻塞记录；所有状态已原子写入并重读。
 
-### 5. 同步领域模型
+### 5. 同步 change-local 领域模型
 
-加载 `<Path>{roots.workflows}/specdev/G-grill-with-docs/domain-modeling-rules.md</Path>`。每轮先写 LOG，再把已确认且当前仍真实的术语、不变量、示例、反例和代码映射同步到 CONTEXT，最后把满足 ADR 条件的长期架构决定写入 ADR。
+加载 `<Path>{roots.workflows}/specdev/G-grill-with-docs/domain-modeling-rules.md</Path>`。每轮先写 LOG，再把已确认且本 change 下游必须使用的项目规范术语同步到 change CONTEXT，最后把同时满足三个准入条件、已成为本 change 合同的架构决定写入 change ADR。
 
-历史轨迹只留在 LOG；未确认选项不写成已接受 ADR；已有 ADR 被替代时建立 supersedes 链。同步文档用于记录共识生长过程，不授权产品实现。
+历史轨迹只留在 LOG；未确认选项不写成已接受 ADR；已有 change ADR 被替代时建立 supersedes 链。同步只更新本 change 工件，不创建、合并或改写永久 `context/`、`adr/`；它记录共识生长过程，不授权产品实现。
 
-**完成标准**：LOG、CONTEXT、ADR 和 design tree 无冲突；每个提升结论都有用户回答或事实来源。
+**完成标准**：LOG、CONTEXT、ADR 和 design tree 无冲突；每个同步结论都有用户回答或事实来源；永久 namespace 未被修改。
 
 ### 6. 共识确认与路由
 
 frontier 为空时，向用户确认设计树的每个分支均已走过且已经达成共识。用户指出遗漏时新增节点并继续；只有明确确认后把 design tree 标为 `consensus`。
 
+路由前使用 `<Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path>` 的 `--stage grill` 校验当前 change；失败时保持本 Work 可恢复状态，不发布共识。
+
 随后按成熟度路由：
 
 - 通常进入 `<Path>{roots.workflows}/specdev/S-spec/S-spec.md</Path>`；
@@ -119,7 +124,8 @@ frontier 为空时，向用户确认设计树的每个分支均已走过且已
 - 每轮询问的是完整 frontier，依赖未关闭的问题没有提前出现；
 - 可发现事实由 Agent 查找，没有转交用户；
 - design tree 通过 schema，LOG 指针完整；
-- CONTEXT 只包含当前领域真相，ADR 只包含满足条件的架构决定；
+- CONTEXT 只包含当前 change 已确认的规范语言，ADR 只包含满足条件且已成为本 change 合同的架构决定；
+- 永久 `context/`、`adr/` 保持只读，未在 G 中执行知识提升；
 - frontier 为空且用户明确确认共识；
 - 状态、权威工件和下一 work 路径已返回；
 - 未执行产品实现。
@@ -132,3 +138,4 @@ frontier 为空时，向用户确认设计树的每个分支均已走过且已
 - ADR 格式：`<Path>{roots.workflows}/specdev/G-grill-with-docs/adr-format.md</Path>`
 - CONTEXT 格式：`<Path>{roots.workflows}/specdev/G-grill-with-docs/context-format.md</Path>`
 - LOG 格式：`<Path>{roots.workflows}/specdev/G-grill-with-docs/log-format.md</Path>`
+- Stakeholder 问卷：`<Path>{roots.workflows}/specdev/G-grill-with-docs/stakeholder-questionnaire.md</Path>`

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

@@ -1,24 +1,38 @@
 # ADR 格式
 
-只有同时满足“影响多个实现点、存在实质替代方案、结论预计长期有效”时才写 ADR。局部且可逆的实现选择留在 Ticket，不把 ADR 变成日常日志。
+本格式用于 `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`。这里的 ADR 是当前 change 的架构决定合同，不是已经提升到永久 `<Path>{roots.state}/specdev/adr/</Path>` 的项目 ADR。
+
+只有一个决定同时满足以下三个条件才写 ADR：
+
+1. 难以逆转；
+2. 没有上下文会令后续维护者惊讶；
+3. 来自真实可行方案之间的权衡。
+
+局部、可逆或没有实质替代方案的选择留在 Ticket/代码。一个 ADR 只表达一个决定。
 
 ```markdown
 ## ADR-###: <标题>
-- **状态：** proposed / accepted / superseded / deprecated
-- **日期：**
-- **决策范围：** 哪些系统、接口或工件受约束
-- **来源：** LOG-### / 用户结论 / 外部规范
-- **上下文：** 需要解决的长期张力，而非实现步骤
-- **决策驱动：** 必须优化或保护的目标与约束
-- **决策：** 清晰、可测试的规范性结论
-- **替代方案：** 至少列出认真考虑过的可行方案
-- **权衡理由：** 为什么选择当前方案
-- **后果：** 正面 / 负面 / 新风险 / 组织影响
-- **不变量与约束：** 下游 Spec、Ticket 和实现不得破坏的条件
-- **验证方式：** 如何知道决策在真实系统中成立
-- **迁移/采用：** 如适用
-- **替代：** ADR-###（如适用）
-- **被替代于：** ADR-###（如适用）
+
+**Status:** proposed / accepted / superseded / deprecated
+**Source:** LOG-### / user decision / external specification
+**Supersedes:** none / ADR-###
+
+### Context
+<缺少什么背景会让这个决定令人惊讶。>
+
+### Decision
+<清晰、规范且可验证的结论。>
+
+### Trade-off
+<认真考虑的替代方案，以及为什么接受当前代价。>
+
+### Consequences
+<真正重要的正面、负面和风险。>
+
+### Verification / Migration
+<仅在适用时出现。>
 ```
 
-一个 ADR 只表达一个决策。修改已接受决策时，新建 ADR 并建立 supersedes 链；不得重写历史来掩盖决策变化。
+`accepted` 只表示用户已接受该决定作为当前 change 的下游合同；它不证明实现已经落地，也不代表永久知识毕业。修改已接受决定时新建 change ADR 并建立 supersedes 链，不重写历史。
+
+只有 A 在 change 完成后对照代码、测试和 Evidence 重新验证，并通过毕业评估与用户确认，才能把决定写为永久 ADR；不通过的决定随归档 change 保留。

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

@@ -1,37 +1,17 @@
 # CONTEXT 格式
 
-CONTEXT 保存跨 change 可复用的领域语言、关系和不变量，不保存一次性任务计划。
+本格式用于 `<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`。它是当前 change 已确认、供本 change 下游使用的项目规范语言表，不是 workflow 级永久领域知识。每个文件只描述一个 bounded context；多个 context 的关系写入单独 Context Map。
 
 ```markdown
-# <主题> 领域上下文
+# <Bounded Context>
 
-- **Owner：**
-- **最后核验：**
-- **权威来源：** ADR / 代码 / 外部规范 / 用户确认
+**<规范术语>**：<一到两句项目特有定义。>
+_Avoid_: <会造成歧义或已废弃的同义词>
 
-## 术语
-### <规范术语>
-- 定义：
-- 边界：
-- 示例：
-- 反例：
-- 不变量：
-- 代码映射：<Path>src/example.ts</Path> / 无
-- 别名与禁用词：
-- 来源与最后核验：
-
-## 概念关系
-- 聚合、生命周期、依赖、拥有关系或状态转换
-
-## 全局不变量
-- 始终成立、可被验证且不属于单个 change 的规则
-
-## 当前实现映射
-- 领域概念与模块、接口、存储或事件之间的对应
+**<另一个术语>**：<一到两句定义。>
+_Avoid_: none
+```
 
-## 当前实现差距
-- 已知偏离、历史负担和待验证假设；不得伪装成已确认事实
+不包含 owner、最后核验、代码路径、实现差距、change 历史、示例大表、普通编程概念或临时假设。来源和演进历史由 LOG/ADR/Spec 保存。
 
-## 变更记录
-- LOG-###：增加、修订或废弃了什么
-```
+G 不把该文件复制或合并到永久 `<Path>{roots.state}/specdev/context/</Path>`。只有 A 在 change 完成后验证实现证据、应用毕业标准并获得用户确认，才生成或更新永久术语文件；未毕业内容随归档 change 保留。