@namewta/speculo 0.6.0 → 0.7.0

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

@@ -3,43 +3,82 @@ id: specdev/triage
 type: workflow-entry
 workflow: specdev
 name: 请求分诊
-description: 完整摄入外部请求，判断问题类型、影响、风险、缺失信息和下一 work，不在分诊阶段过早设计或实现。
-keywords: [triage, 摄入, issue, 风险, 路由]
+description: 把远程 Issue、URL、文件或对话冻结为本地来源工件，完成风险分诊与路由，并在本地 change 完成后受控回写和关闭支持的远程 Issue。
+keywords: [triage, 摄入, import, issue, reconcile, close, 风险, 路由]
 ---
 
 # 请求分诊
 
-分诊负责保存原始意图、建立 change、识别问题类型与风险，并推荐下一 work。分诊完成不等于实现 Ready。
+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 和状态文件是唯一权威；远程系统只保存原始请求以及经确认后的完成通知。
 
-## 流程
+## 模式
 
-1. **创建或选择 change**：使用 `<Path>{roots.state}/specdev/changes/{change}/</Path>`。
-2. **摄入原文**：完整保存到 `<Path>{roots.state}/specdev/changes/{change}/source-issue.md</Path>`，保留来源、时间、链接和附件引用，不改写原意。
-3. **读取上下文**：按需读取 `<Path>{roots.state}/specdev/context/</Path>`、`<Path>{roots.state}/specdev/adr/</Path>`、当前 change 文档和相关代码事实。
-4. **分类**：bug、feature、refactor、investigation、operations、documentation 或混合；混合请求按主要阻塞问题路由，不强行塞入单类。
-5. **评估**：影响、紧急度、风险、事故半径、安全/数据/兼容/迁移因素和所需人工批准。
-6. **未知项分类**：可发现事实继续探索；无法发现且会改变方案的内容标为 decision-needed；低影响实现细节不阻塞。
-7. **推荐路线**：
-   - bug 且根因未知 → `<Path>{roots.workflows}/specdev/D-diagnose-bugs/D-diagnose-bugs.md</Path>`；
-   - 需求或架构不清 → `<Path>{roots.workflows}/specdev/G-grill-with-docs/G-grill-with-docs.md</Path>`；
-   - 外部行为已清楚 → `<Path>{roots.workflows}/specdev/S-spec/S-spec.md</Path>`；
-   - 小且完全明确、风险低 → `<Path>{roots.workflows}/specdev/T-tickets/T-tickets.md</Path>` 的 Lite Ticket，或用户批准的 Direct Spec 实现；
-   - 路径未知或调查超出单次上下文 → `<Path>{roots.workflows}/specdev/W-wayfinder/W-wayfinder.md</Path>`；
-   - 架构质量问题 → `<Path>{roots.workflows}/specdev/R-review-architecture/R-review-architecture.md</Path>`。
-8. **写入结果**：使用 `<Path>{roots.workflows}/specdev/T-triage/triage-template.md</Path>` 写入 `<Path>{roots.state}/specdev/changes/{change}/triage.md</Path>`，更新 `<Path>{roots.state}/specdev/status.json</Path>` 和 `<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>`（首次创建时使用 `<Path>{roots.workflows}/specdev/I-init-setup/change-status-template.json</Path>`）。
+- **intake**：冻结输入、创建或恢复 change、分类并返回下一 Work。
+- **reconcile**：本地 change 已完成后，确认远程完成摘要并关闭支持的 GitHub Issue；不重新分诊或修改开发契约。
 
-## 就绪门禁
+## 共同启动
 
-只有推荐为“直接实现”，且目标、范围、验证、路径和风险均明确并获用户批准时，才能设置 `ready_for_implementation: true`。其他情况必须为 `false`，并明确下一 work。
+1. 解析 roots，读取 `<Path>{roots.workflows}/specdev/INDEX.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>`，不覆盖已冻结的来源。
+
+## Intake
+
+输入为远程 Issue、URL、项目相对文件、用户粘贴内容或当前对话时，加载 `<Path>{roots.workflows}/specdev/T-triage/intake-protocol.md</Path>`：
+
+1. 按协议解析来源、查重、脱敏、冻结并计算内容 hash；使用 `<Path>{roots.workflows}/specdev/T-triage/source-template.md</Path>` 原子写入 `<Path>{roots.state}/specdev/changes/{change}/source.md</Path>`。
+2. 按需读取永久 ADR/CONTEXT、当前 change 工件和相关代码事实；缺失的可选输入静默跳过。
+3. 分类为 bug、feature、refactor、investigation、operations、documentation、review 或 mixed。
+4. 评估影响、紧急度、事故半径、安全、数据、迁移和人工批准；把未知项分为可发现事实、decision-needed 和低影响实现细节。
+5. 使用 `<Path>{roots.workflows}/specdev/T-triage/triage-template.md</Path>` 写入 `<Path>{roots.state}/specdev/changes/{change}/triage.md</Path>`。
+6. 运行阶段校验并返回最小正确路线：
+   - 根因未知的 bug → `<Path>{roots.workflows}/specdev/D-diagnose-bugs/D-diagnose-bugs.md</Path>`；
+   - 产品或架构决定未锁定 → `<Path>{roots.workflows}/specdev/G-grill-with-docs/G-grill-with-docs.md</Path>`；
+   - 路径超出单次上下文 → `<Path>{roots.workflows}/specdev/W-wayfinder/W-wayfinder.md</Path>`；
+   - 需要可运行原型回答设计问题 → `<Path>{roots.workflows}/specdev/P-prototype/P-prototype.md</Path>`；
+   - 外部行为明确 → `<Path>{roots.workflows}/specdev/S-spec/S-spec.md</Path>`；
+   - 固定点 diff 或 PR 审查 → `<Path>{roots.workflows}/specdev/C-code-review/C-code-review.md</Path>`；
+   - 小型明确变更 → `<Path>{roots.workflows}/specdev/T-tickets/T-tickets.md</Path>` 或获批 Direct Spec。
+
+只有目标、范围、验证、路径和风险全部明确且用户批准 Direct Spec 时，`ready_for_implementation` 才能为 true。
+
+## Reconcile
+
+本地 change 完成并需要关闭来源 Issue 时，加载：
+
+- `<Path>{roots.workflows}/specdev/common/rules/change-completion.md</Path>`；
+- `<Path>{roots.workflows}/specdev/T-triage/reconcile-protocol.md</Path>`。
+
+按协议重验本地完成、生成最小外部摘要、展示准确目标和动作、取得本次明确授权，再调用 `<Path>{roots.skills}/github-npm-ops/SKILL.md</Path>`。成功时把 `external_action` 更新为 `closed`；部分或完全失败为 `close-failed` 并保留可重试检查点；用户明确不关闭时为 `waived`。任何结果都不改写本地完成事实。
+
+Reconcile 成功或 waived 后返回 `<Path>{roots.workflows}/specdev/A-archive-and-consolidate/A-archive-and-consolidate.md</Path>`。不支持关闭的来源使用 `not-applicable`，无需虚构 provider。
+
+## 状态与验证
+
+运行：
+
+```bash
+node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> \
+  --stage triage \
+  <Path>{roots.state}/specdev/changes/{change}</Path>
+```
+
+验证通过后原子重读 source、triage 和 change 状态。Intake 或 reconcile 成功时将 `specdev/triage` 去重加入 `works_run` 并清空 `current_work`；可恢复失败保留 `current_work` 和具体 blocker。
 
 ## 完成标准
 
-- 原始请求未被改写或丢失；
-- 问题类型、影响、风险和未知项已区分；
-- 推荐下一 work 有明确理由；
-- 分诊没有夹带实现；
-- 状态已更新。
+- 来源已冻结为本地工件，原意未被改写，敏感值未持久化；
+- 相同 locator 不会静默创建重复 change或覆盖已有快照；
+- 分类、影响、风险、未知项和下一 Work 有证据；
+- 开发权威完全位于本地 state；
+- 未授权时远程写入为零；
+- Reconcile 可从失败检查点幂等恢复；
+- 状态、验证结果和下一 Work 完整路径已返回。
 
 ## 子文件引用
 
-- 分诊模板：`<Path>{roots.workflows}/specdev/T-triage/triage-template.md</Path>`
+- Intake：`<Path>{roots.workflows}/specdev/T-triage/intake-protocol.md</Path>`
+- Reconcile：`<Path>{roots.workflows}/specdev/T-triage/reconcile-protocol.md</Path>`
+- Source 模板：`<Path>{roots.workflows}/specdev/T-triage/source-template.md</Path>`
+- Triage 模板：`<Path>{roots.workflows}/specdev/T-triage/triage-template.md</Path>`

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

@@ -0,0 +1,32 @@
+# Intake Protocol
+
+仅在 Triage `mode=intake` 时加载。本协议把外部输入转换为不可静默覆盖的本地来源快照。
+
+## 1. 解析来源
+
+按以下优先级确定 `source_type`：GitHub Issue/PR URL、普通 URL、项目相对文件、用户粘贴内容、当前对话。来源为 GitHub 时调用 `<Path>{roots.skills}/github-npm-ops/SKILL.md</Path>` 的 `issue-read` 或 `pr-read`；其他 URL 使用当前环境可用的只读读取能力。读取失败时保持 blocked，并请求用户提供导出或粘贴内容。
+
+只记录规范化 URL、项目相对 Path 或 null；不保存机器绝对路径、认证信息、Cookie 或令牌。
+
+## 2. 查重与漂移
+
+在 active 和 archive 的 `<Path>{roots.state}/specdev/changes/{change}/source.md</Path>` 或对应归档 Source 中查询相同 `canonical_locator`：
+
+- locator 与 hash 相同：恢复已有 change，不创建副本；
+- locator 相同但 hash 不同：展示漂移，不覆盖原快照；只有用户确认后才创建新 change，并在新 source 中记录 `supersedes_source`；
+- 没有稳定 locator：按用户指定 change 或新 change 继续。
+
+## 3. 冻结内容
+
+GitHub 来源保存 title、body、author、state、labels、created/updated 和截至捕获时可见的全部评论。普通 URL 保存可读正文和元数据；项目文件保存内容及项目相对 Path；粘贴或对话保存用户原文。
+
+在计算 SHA-256 前移除秘密、令牌、Cookie、个人隐私和不应长期保存的敏感日志，并在 Redactions 记录类型，不记录原值。附件默认只留 URL 与描述。
+
+使用 `<Path>{roots.workflows}/specdev/T-triage/source-template.md</Path>` 写临时文件，重读并验证后原子替换目标。已有 `<Path>{roots.state}/specdev/changes/{change}/source.md</Path>` 永不就地覆盖。
+
+## 完成标准
+
+- 来源类型、locator、捕获时间、hash 和关闭能力已确定；
+- 完整可持久化正文与评论已冻结；
+- 重复和漂移分支有唯一结果；
+- 失败没有生成伪造或不完整的 Ready source。

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

@@ -0,0 +1,34 @@
+# Reconcile Protocol
+
+仅在 Triage `mode=reconcile` 时加载。目标是把本地完成结果最小化投影到来源 Issue，并关闭它。
+
+## 1. 本地完成硬门
+
+按 `<Path>{roots.workflows}/specdev/common/rules/change-completion.md</Path>` 重验：change 为 completed、全部计划内 Ticket 已完成或批准取消、Evidence 与 Gate 齐全、验证通过、无未批准 deviation。任一项失败时停止，不准备远程写入。
+
+`<Path>{roots.state}/specdev/changes/{change}/source.md</Path>` 必须指向仍可定位的 open GitHub Issue，且 `<Path>{roots.state}/specdev/changes/{change}/triage.md</Path>` 的 `external_action` 为 `pending-close` 或 `close-failed`。其他来源使用 `not-applicable`。
+
+## 2. 准备关闭计划
+
+从本地 Evidence 生成简短评论：完成结果、关键验证、可公开的 commit/PR URL、残余风险或后续工作。不得发布 state Path、机器路径、秘密、内部日志或未核对声明。
+
+向用户展示准确 repo、Issue 编号、评论全文、close reason 和将执行的动作。只有本次明确确认后才继续；拒绝或暂不执行时零远程写入。用户明确放弃关闭可将状态置为 `waived`。
+
+## 3. 幂等执行
+
+调用 `<Path>{roots.skills}/github-npm-ops/SKILL.md</Path>` 的 `issue-comment-close`，marker 固定为 `specdev:<change>:completion`。执行前重读 Issue 与评论：
+
+- 已关闭且 marker 存在：按已完成恢复；
+- marker 存在但 Issue 仍 open：只重试 close；
+- marker 不存在：评论成功后再 close；
+- 任一步失败：记录已完成步骤、错误和下一重试动作，状态为 `close-failed`。
+
+成功后重读远程状态，只有观察到 closed 才写 `external_action: closed`。
+
+## 完成标准
+
+- 本地完成先于远程动作；
+- 用户看见并批准了准确写入计划；
+- 重试不会重复评论；
+- 外部失败不改写本地完成事实；
+- closed、close-failed 或 waived 与证据一致。

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

@@ -0,0 +1,30 @@
+---
+schema_version: 1
+artifact: source
+change: <YYYY-MM-DD-topic>
+source_type: conversation
+canonical_locator: null
+captured_at: <ISO-8601>
+content_sha256: <sha256>
+remote_state: not-applicable
+close_capability: not-applicable
+---
+
+# Source: <标题>
+
+## Capture Metadata
+
+- **Capture method:** conversation / pasted / project-file / URL fetch / GitHub CLI
+- **Author:** unknown / <name>
+- **Created / updated:** unknown / <timestamps>
+- **Labels or classification supplied by source:** none / ...
+- **Attachments:** none / URL references only
+- **Redactions:** none / description of omitted sensitive material
+
+## Original Content
+
+<保存脱敏后的完整原始正文，不改写语气、结构或意图。>
+
+## Source Comments
+
+<按来源顺序保存评论；没有评论时写“无”。>

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

@@ -1,29 +1,43 @@
+---
+schema_version: 1
+artifact: triage
+change: <YYYY-MM-DD-topic>
+mode: intake
+source: <Path>{roots.state}/specdev/changes/{change}/source.md</Path>
+classification: investigation
+risk: medium
+route: specdev/wayfinder
+ready_for_implementation: false
+external_action: not-applicable
+updated_at: <ISO-8601>
+---
+
 # Triage: <标题>
 
-- **Change：** `<change>`
-- **来源工件：** `<Path>{roots.state}/specdev/changes/{change}/source-issue.md</Path>` / 外部输入
-- **类型：** bug / feature / refactor / investigation / operations / documentation
+## 当前判定
+
 - **影响：** 用户、系统、数据或交付影响
-- **风险：** low / medium / high / critical
 - **紧急度：** immediate / scheduled / normal / unknown
 - **当前证据：** 已观察事实，不写推测
-- **相关代码/工件：** `<Path>src/example.ts</Path>` / `<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>` / 无
-- **缺失的可发现事实：** 无 / 可通过仓库、日志、测试或配置查明的事实
-- **需要用户决定：** 无 / 只有无法从环境推导且会改变目标、范围或风险承受度的决定
-- **推荐下一 work：** D-diagnose-bugs / G-grill-with-docs / S-spec / W-wayfinder / I-implement / R-review-architecture / A-archive-and-consolidate
-- **推荐理由：** 为什么该 work 是最小且正确的下一步
-- **ready_for_implementation：** false
-
-## 路由判定
-
-- **Bug 但根因未知：** 进入 D-diagnose-bugs。
-- **需求或设计存在关键未知：** 进入 G-grill-with-docs。
-- **意图清晰但尚无可验收 Spec：** 进入 S-spec。
-- **需要并行调查多个未知：** 进入 W-wayfinder。
-- **已具备 Ready Ticket，或满足受控 Direct Spec：** 进入 I-implement。
-- **目标是结构健康评估而非立即修复：** 进入 R-review-architecture。
-- **目标是关闭、合并或沉淀 change：** 进入 A-archive-and-consolidate。
-
-## 输出
-
-将结果写入 `<Path>{roots.state}/specdev/changes/{change}/triage.md</Path>`，并同步 `<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>` 的下一阶段和阻塞状态。
+- **相关代码/工件：** `<Path>src/example.ts</Path>` / 无
+
+## 未知项
+
+- **可发现事实：** 无 / 需要从仓库、日志、测试或配置查明的事实
+- **需要用户决定：** 无 / 会改变目标、范围、行为或风险承受度的决定
+- **低影响实现细节：** 无 / 由后续实现者按既有惯例决定
+
+## 路由
+
+- **下一 Work：** `<Path>{roots.workflows}/specdev/W-wayfinder/W-wayfinder.md</Path>`
+- **理由：** 为什么这是最小且正确的下一步
+
+## 外部动作
+
+- **远程目标：** 无 / `<Url>https://github.com/owner/repo/issues/123</Url>`
+- **关闭能力：** supported / unsupported / not-applicable
+- **当前状态：** not-applicable / pending-close / closed / close-failed / waived
+- **授权记录：** 无
+- **尝试与结果：** 无
+
+外部动作只投影最终完成，不替代本地状态、Ticket、Map 或 Evidence。

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

@@ -45,7 +45,7 @@ Wayfinder 默认进行**规划**：每个 Ticket 解决一个决策，当地图
 每个 Ticket 要么是 **HITL**，与一个代表自己发言的人类一起工作；要么是 **AFK**，由 Agent 独立驱动。HITL Ticket 只能通过实时交流解决，Agent 绝不代替人类一方发言。
 
 - **Research（AFK）**：阅读文档、第三方 API 或知识库等资源，揭示某个决策等待的事实。调用 `<Path>{roots.workflows}/specdev/common/skills/research/SKILL.md</Path>`。当需要当前工作目录之外的知识时使用。
-- **Prototype（HITL）**：制作廉价、粗糙、具体的产物提高讨论保真度——大纲、粗略尝试、桩代码或 UI/逻辑原型。将原型链接为资产；当“它应是什么样”或“怎样表现”是关键问题时使用。
+- **Prototype（HITL）**：调用 `<Path>{roots.workflows}/specdev/P-prototype/P-prototype.md</Path>` 回答一个 UI/逻辑问题，并把 record、临时 branch/worktree 和运行 URL 链接为 solution comment 资产；P 不实现目的地。
 - **Grilling（HITL）**：对话。调用 `<Path>{roots.workflows}/specdev/G-grill-with-docs/G-grill-with-docs.md</Path>` 的 grilling 与 domain-modeling 能力，但本会话只关闭当前 Wayfinder Ticket。
 - **Task（HITL 或 AFK）**：在决策做出前必须完成的手动工作。它通过为决策解除阻塞赢得位置，不以交付目的地为目标。Agent 能独立驱动时使用 AFK，否则给人类精确清单。
 
@@ -97,6 +97,8 @@ Ticket label 只能是 `wayfinder:research | wayfinder:prototype | wayfinder:gri
 
 当前沿为空且“尚未明确”不再包含阻塞目的地的内容时，路径清晰：
 
+路由前使用 `<Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path>` 的 `--stage wayfinder`；Ticket、claim、comment 或地图不一致时保持 blocked。
+
 - 需要产品或架构取舍：`<Path>{roots.workflows}/specdev/G-grill-with-docs/G-grill-with-docs.md</Path>`；
 - 外部行为已清楚：`<Path>{roots.workflows}/specdev/S-spec/S-spec.md</Path>`；
 - Spec Ready、只需拆分：`<Path>{roots.workflows}/specdev/T-tickets/T-tickets.md</Path>`；

package/template/workflows/specdev/_state/status.json

@@ -1,7 +1,6 @@
 {
-  "schema_version": 3,
+  "schema_version": 4,
   "workflow": "specdev",
   "active": [],
-  "work_history": [],
-  "completed": []
+  "archived": []
 }

package/template/workflows/specdev/common/README.md

@@ -18,6 +18,7 @@
 - 证据与验证：`<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>`
+- Change 完成：`<Path>{roots.workflows}/specdev/common/rules/change-completion.md</Path>`
 - 代码注释：`<Path>{roots.workflows}/specdev/common/rules/code-commenting-rule.md</Path>`
 - 代码库设计：`<Path>{roots.workflows}/specdev/common/rules/codebase-design.md</Path>`
 
@@ -32,14 +33,20 @@
 - Goal Plan：`<Path>{roots.workflows}/specdev/common/schemas/goal-plan.schema.json</Path>`
 - 设计树：`<Path>{roots.workflows}/specdev/common/schemas/design-tree.schema.json</Path>`
 - Wayfinder Ticket：`<Path>{roots.workflows}/specdev/common/schemas/wayfinder-ticket.schema.json</Path>`
+- 来源快照：`<Path>{roots.workflows}/specdev/common/schemas/source.schema.json</Path>`
+- 分诊：`<Path>{roots.workflows}/specdev/common/schemas/triage.schema.json</Path>`
+- 诊断：`<Path>{roots.workflows}/specdev/common/schemas/diagnosis.schema.json</Path>`
+- 代码审查：`<Path>{roots.workflows}/specdev/common/schemas/code-review.schema.json</Path>`
+- 原型记录：`<Path>{roots.workflows}/specdev/common/schemas/prototype-record.schema.json</Path>`
 
 ## 工具与 Skill
 
 - 包与 change 校验器：`<Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path>`
 - 校验器说明：`<Path>{roots.workflows}/specdev/common/tools/README.md</Path>`
 - 外部技术研究 Skill：`<Path>{roots.workflows}/specdev/common/skills/research/SKILL.md</Path>`
-- 并行 Ticket worktree Skill：`<Path>{roots.workflows}/specdev/common/skills/dev-worktree/SKILL.md</Path>`
-- Agent 交付合同 Skill：`<Path>{roots.workflows}/specdev/common/skills/subagent-delivery/SKILL.md</Path>`
+- 隔离 Ticket/原型 worktree Skill：`<Path>{roots.workflows}/specdev/common/skills/dev-worktree/SKILL.md</Path>`，角色中立；委派 Goal Plan 才映射为 Lead/Worker
+- 委派 Agent 交付合同 Skill：`<Path>{roots.workflows}/specdev/common/skills/subagent-delivery/SKILL.md</Path>`，仅用户选择委派 Goal Plan 时调用
+- 双轴代码审查 Skill：`<Path>{roots.workflows}/specdev/common/skills/code-review/SKILL.md</Path>`
 
 ## 加载原则
 

package/template/workflows/specdev/common/rules/artifact-contract.md

@@ -6,33 +6,44 @@ SpecDev 通过分层工件避免同一决策被多个模型反复重做。每个
 
 | 工件 | 具体位置 | 必须决定 | 不应决定 |
 |---|---|---|---|
-| 分诊 | `<Path>{roots.state}/specdev/changes/{change}/triage.md</Path>` | 请求类别、影响、风险、缺失输入和下一 work | 详细实现方案 |
+| 来源快照 | `<Path>{roots.state}/specdev/changes/{change}/source.md</Path>` | 原始请求、捕获时间、locator、hash 和关闭能力 | 当前产品合同或实现状态 |
+| 分诊 | `<Path>{roots.state}/specdev/changes/{change}/triage.md</Path>` | 请求类别、影响、风险、缺失输入、下一 work 和远程 reconcile 状态 | 详细实现方案或开发进度 |
 | 诊断 | `<Path>{roots.state}/specdev/changes/{change}/diagnosis.md</Path>` | 复现、证据、根因、修复不变量和回归契约 | 未经验证的修复实现 |
 | 设计日志 | `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>` | 讨论轨迹、确认、延后、替代与废弃结论 | 当前架构权威摘要 |
 | 设计树 | `<Path>{roots.state}/specdev/changes/{change}/design-tree.json</Path>` | 决策节点、依赖、当前 frontier、轮次与共识状态 | 领域真相或架构决定正文 |
-| 领域上下文 | `<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>` | 当前领域术语、语义和稳定不变量 | 临时会议记录 |
-| 架构决策 | `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>` | 已接受架构决策、原因、后果和替代关系 | 尚未决定的方案集合 |
+| Change 领域上下文 | `<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>` | 本 change 已确认、供下游使用的领域术语和语义 | 永久领域知识或临时会议记录 |
+| Change 架构决策 | `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>` | 已成为本 change 下游合同的架构决策、原因、后果和替代关系 | 永久项目 ADR 或尚未决定的方案集合 |
 | Spec | `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>` | 用户问题、外部行为、范围、验收合同、非功能要求和已锁定实现约束 | 文件级施工步骤 |
 | Ticket | `<Path>{roots.state}/specdev/changes/{change}/ticket/{ticket-file}.md</Path>` | 单一垂直切片的行为、决策、范围、路径所有权、执行路线和验证证据 | 跨 Ticket 里程碑治理 |
 | Tickets Map | `<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>` | 依赖 DAG、合同覆盖、Ready 投影、并行候选和路径冲突 | 单 Ticket 的完整实现契约 |
 | Goal Plan | `<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>` | 跨 Ticket 调度、Gate、共享所有权、迁移顺序、集成和偏差治理 | 复制 Ticket 全文 |
 | Evidence | `<Path>{roots.state}/specdev/changes/{change}/evidence/{ticket-id}.md</Path>` | 实际修改、命令、结果、验收映射、偏差、风险和提交引用 | 新的产品或架构决策 |
+| 代码审查 | `<Path>{roots.state}/specdev/changes/{change}/reviews/CR-###.md</Path>` | 固定点、标准轴和规范轴 finding | 实施修复或合并两轴排名 |
+| 原型记录 | `<Path>{roots.state}/specdev/changes/{change}/prototypes/{prototype-id}/record.md</Path>` | 一个问题、分支、资产、答案、promotion 和清理 | 生产实现或多个问题的计划 |
+| Stakeholder 问卷 | `<Path>{roots.state}/specdev/changes/{change}/questionnaires/{slug}.md</Path>` | 第三方原始回答和恢复条件 | 未经转录确认的产品/架构决定 |
 | Wayfinder 地图 | `<Path>{roots.state}/specdev/changes/{change}/wayfinder-map.md</Path>` | 目的地、说明、已关闭决策索引、战争迷雾和范围之外 | 开放 Ticket 正文或答案详情 |
 | Wayfinder Ticket | `<Path>{roots.state}/specdev/changes/{change}/investigation/{investigation-id}.md</Path>` | 一个可精确陈述的问题、类型、阻塞和关闭状态 | 解决方案评论或交付目标 |
 | Wayfinder solution comment | `<Path>{roots.state}/specdev/changes/{change}/investigation/comments/{investigation-id}/NN-solution.md</Path>` | Ticket 的答案、结果事实和资产指针 | 地图索引或产品实现 |
 | 架构审查 | `<Path>{roots.state}/specdev/changes/{change}/architecture-review.md</Path>` 与 `<Path>{roots.state}/specdev/changes/{change}/architecture-review.html</Path>` | 深化候选、证据、可视化、选择和访谈状态 | 未经用户选择的执行契约 |
 
+Change CONTEXT/ADR 是 active change 内的执行权威，不是 workflow 级永久知识。G 和其他设计/执行 Works 只读 `<Path>{roots.state}/specdev/context/</Path>` 与 `<Path>{roots.state}/specdev/adr/</Path>`；只有 A 在 change 完成、实现证据验证、毕业评估和用户确认后才能写入永久 namespace。未毕业内容随归档 change 保留，不能从 change 工件消失。
+
 ## 2. 权威顺序
 
 同一事项冲突时按下列顺序裁决：
 
 1. 用户最新明确决定；
-2. 当前已接受架构决策：`<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`；
-3. 当前外部行为权威：`<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`；
-4. 当前 Ticket 契约：`<Path>{roots.state}/specdev/changes/{change}/ticket/{ticket-file}.md</Path>`；
-5. 当前跨 Ticket 编排：`<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>`；
-6. 当前代码与运行事实；
-7. 旧计划、旧日志和未经确认的推断。
+2. 当前 change 已接受的架构决策：`<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`；
+3. 永久 ADR 与领域上下文：`<Path>{roots.state}/specdev/adr/</Path>`、`<Path>{roots.state}/specdev/context/</Path>`；
+4. 当前外部行为权威：`<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`；
+5. 当前 Ticket 契约：`<Path>{roots.state}/specdev/changes/{change}/ticket/{ticket-file}.md</Path>`；
+6. 当前跨 Ticket 编排：`<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>`；
+7. 当前代码与运行事实；
+8. 旧计划、旧日志和未经确认的推断。
+
+当前 change 决定与永久知识冲突时，必须在 LOG/ADR 中显式说明替代关系；它只约束当前 change，直到 A 决定是否提升并更新永久版本。
+
+`<Path>{roots.state}/specdev/changes/{change}/source.md</Path>` 只对“原始输入是什么”具有权威；后续用户决定、ADR 和 Spec 可以显式演进该意图。远程来源在摄入后发生变化不会自动改写本地合同，必须重新 Triage。
 
 代码事实可以证明计划已过时，但不能静默改写用户目标或已接受契约。出现这种情况时，按 `<Path>{roots.workflows}/specdev/common/rules/deviation-control.md</Path>` 退回相应工件修订。
 

package/template/workflows/specdev/common/rules/change-completion.md

@@ -0,0 +1,33 @@
+# Change Completion
+
+本规则是 change 从 active/blocked 转为 completed 的唯一合同，并由 Implement、Goal Plan、Triage、Status 与 Archive 共同读取。
+
+## 完成门
+
+一个 change 只有同时满足以下条件才能设置 `change_status: completed`：
+
+1. 所有计划内 Ticket 为 `done`，或有明确批准理由的 `cancelled`；无 Ticket 的 Direct Spec/非实现流程有等价的验收清单。
+2. 每个完成行为有 Evidence，全部 Spec 验收合同和适用 Goal Gate 可定位。
+3. 项目级验证通过；既有或环境失败已分类、接受并记录风险。
+4. 迁移、发布、监控、回滚和不可逆批准已完成或明确不适用。
+5. 没有未批准 deviation、未处置 blocker 或伪装成通过的 `unverified` 声明。
+6. Ticket、Map、Goal Plan、Evidence、源码 checkpoint 和 change 状态一致。
+
+## 转换 Owner
+
+- Goal Plan 含完整 `## Delegated Execution Addendum`：Lead 在独立验收并关闭最后一个 Gate 后拥有完成转换。
+- Goal Plan 不含委派附录，或无 Goal Plan 的 Ticket/Direct Spec 实现：最后一个计划内 Implement 在最后一项验收通过后拥有完成转换。
+- 非实现型终点：最后一个拥有最终验收工件的 Work 使用本规则完成转换。
+
+Owner 原子更新 `<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>` 的 `change_status`、`completed_at`、`updated_at` 和 `current_work`，然后重读验证。全局 `<Path>{roots.state}/specdev/status.json</Path>` 继续只保存 active 索引，不复制完成详情。
+
+## 远程来源与归档
+
+远程动作不参与本地完成判定。完成后若 `<Path>{roots.state}/specdev/changes/{change}/triage.md</Path>` 的 `external_action` 为 `pending-close` 或 `close-failed`，下一路线是 Triage reconcile；`closed`、`waived` 或 `not-applicable` 才允许 Archive 移动 change。归档后工件只读，不在归档目录补写远程结果。
+
+## 完成标准
+
+- 完成声明可以从本地工件和实际验证重建；
+- 当前 change 只有一个条件命中的转换 owner；
+- 远程失败不会把 completed 改回 active；
+- Archive 不接收尚未 reconcile 或 waive 的远程来源。

package/template/workflows/specdev/common/rules/deviation-control.md

@@ -5,7 +5,7 @@
 ## 1. 偏差等级
 
 - **local**：只改变局部实现，不改变 Ticket 的行为、范围、公共契约、路径所有权或验证；记录到 Evidence 后可继续。
-- **ticket**：改变 Ticket 的执行路线、可写范围、局部契约或验收映射，但不改变 Spec；必须停止相关修改、更新 Ticket 并获得 owner 或 Lead 批准。
+- **ticket**：改变 Ticket 的执行路线、可写范围、局部契约或验收映射，但不改变 Spec；必须停止相关修改、更新 Ticket 并获得该 Ticket 或计划明确的批准 owner 同意。
 - **spec**：改变外部行为、范围、用户故事、验收合同或非功能要求；必须返回 `<Path>{roots.workflows}/specdev/S-spec/S-spec.md</Path>`。
 - **architecture**：改变已接受架构决策或公共架构约束；必须返回 `<Path>{roots.workflows}/specdev/G-grill-with-docs/G-grill-with-docs.md</Path>` 并更新 `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`。
 - **release**：改变迁移、兼容窗口、发布门禁、回滚或不可逆批准点；必须停止并获得明确人工批准。
@@ -40,4 +40,4 @@
 
 - 未批准的 ticket、spec、architecture 或 release 偏差不得继续实现。
 - 不得通过扩大 `writable_paths`、删除测试、降低断言或把风险改写成“已知限制”来绕过停止。
-- 偏差影响并发 Agent 时，Lead 必须暂停受影响 Wave，重新计算路径所有权、依赖和 Gate。
+- 偏差影响普通并行执行时，当前集成 owner 必须暂停受影响 Wave，重新计算路径所有权、依赖和 Gate；委派执行由 Lead 承担同一责任。

package/template/workflows/specdev/common/rules/evidence-and-verification.md

@@ -24,7 +24,7 @@
 4. 可重复手动步骤、截图或查询结果；
 5. 代码阅读推断。
 
-E2E 仅在变更影响用户界面交互时加入验证矩阵，并且只由 Lead 在集成阶段执行。Worker 只记录场景、预期结果和待执行状态。API、CLI、后端、库或数据变更默认使用其稳定接缝，不追加 E2E。
+E2E 仅在变更影响用户界面交互时加入验证矩阵。普通执行由当前实现或集成 owner 运行；委派执行中 Worker 只记录场景、预期结果和待执行状态，由 Lead 在集成阶段运行。API、CLI、后端、库或数据变更默认使用其稳定接缝，不追加 E2E。
 
 低层证据不能替代明确要求的用户行为证据。高风险迁移还需要 dry-run、调用点扫描、数据核对、监控信号或回滚演练。
 

package/template/workflows/specdev/common/rules/path-ownership.md

@@ -23,13 +23,13 @@ shared_paths: ["<Path>package.json</Path>"]
 1. 可能并行的 Ticket，其 `writable_paths` 不得相交。
 2. glob 与具体路径按覆盖关系判断，不得只比较字符串。
 3. 根依赖清单、锁文件、根导出、共享 schema、迁移索引、全局路由和跨 Ticket 合同文件默认视为 shared。
-4. shared path 只能由 Lead 或专用 owner Ticket 修改；消费者 Ticket 只读。
+4. shared path 只能由专用 owner Ticket 或 Goal Plan 明确指定的唯一集成 owner 修改；消费者 Ticket 只读。委派 Goal Plan 可以把该 owner 指定为 Lead，但普通计划不预设角色。
 5. 需要越界时先停止，按 `<Path>{roots.workflows}/specdev/common/rules/deviation-control.md</Path>` 提出 ownership change；不得先改后报。
 6. 前置 Ticket 改变目录结构后，后续 Ticket 开始前重新解析项目路径；若授权范围语义未改变，可只更新导航路径。
 7. 不得把“最后解决合并冲突”当作所有权方案。
 
 ## 3. Worktree 与分支
 
-并行写代码的 Ready Ticket 使用隔离 worktree；只读调查和顺序执行默认共用当前工作区。Worktree 防止工作区污染，路径所有权防止逻辑冲突，两者不能互相替代。
+需要并行或临时隔离项目写入时使用独立 worktree；只读调查和顺序执行默认共用当前工作区。Worktree 防止工作区污染，路径所有权防止逻辑冲突，两者不能互相替代。
 
-生命周期由 Lead 按 `<Path>{roots.workflows}/specdev/common/skills/dev-worktree/SKILL.md</Path>` 管理，编排规则位于 `<Path>{roots.workflows}/specdev/P-goal-plan/orchestration-protocol.md</Path>`。
+生命周期由调用方明确的 workspace owner 按 `<Path>{roots.workflows}/specdev/common/skills/dev-worktree/SKILL.md</Path>` 管理。普通 Goal Plan 由当前执行或集成 owner 负责；委派 Goal Plan 才把 workspace owner 映射为 Lead。编排规则位于 `<Path>{roots.workflows}/specdev/P-goal-plan/orchestration-protocol.md</Path>`。

package/template/workflows/specdev/common/schemas/change-status.schema.json

@@ -145,6 +145,49 @@
     }
   },
   "allOf": [
+    {
+      "if": {
+        "properties": {
+          "worktrees": {
+            "contains": {
+              "properties": {
+                "provider": {
+                  "const": "git"
+                }
+              },
+              "required": [
+                "provider"
+              ]
+            }
+          }
+        }
+      },
+      "then": {
+        "properties": {
+          "worktrees": {
+            "items": {
+              "if": {
+                "properties": {
+                  "provider": {
+                    "const": "git"
+                  }
+                },
+                "required": [
+                  "provider"
+                ]
+              },
+              "then": {
+                "properties": {
+                  "workspace_ref": {
+                    "pattern": "^specdev-worktree/T-[0-9]{2,}$"
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     {
       "if": {
         "properties": {

package/template/workflows/specdev/common/schemas/code-review.schema.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:speculo:specdev:code-review:v1",
+  "title": "SpecDev Code Review Frontmatter",
+  "type": "object",
+  "required": ["schema_version", "artifact", "change", "review_id", "fixed_point", "head", "status", "standards_result", "specification_result", "spec_sources", "standards_sources", "created_at"],
+  "properties": {
+    "schema_version": {"const": 1},
+    "artifact": {"const": "code-review"},
+    "change": {"type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9]+(?:-[a-z0-9]+)*$"},
+    "review_id": {"type": "string", "pattern": "^CR-[0-9]{3,}$"},
+    "fixed_point": {"type": "string", "minLength": 7},
+    "head": {"type": "string", "minLength": 7},
+    "status": {"enum": ["approved", "request-changes", "blocked"]},
+    "standards_result": {"enum": ["pass", "request-changes", "skipped"]},
+    "specification_result": {"enum": ["pass", "request-changes", "skipped"]},
+    "spec_sources": {"type": "array", "items": {"type": "string"}, "uniqueItems": true},
+    "standards_sources": {"type": "array", "items": {"type": "string"}, "uniqueItems": true},
+    "created_at": {"type": "string", "minLength": 1}
+  },
+  "additionalProperties": true
+}

package/template/workflows/specdev/common/schemas/diagnosis.schema.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:speculo:specdev:diagnosis:v1",
+  "title": "SpecDev Diagnosis Frontmatter",
+  "type": "object",
+  "required": ["schema_version", "artifact", "change", "status", "feedback_loop_ready", "red_command", "red_evidence", "cleanup_status", "updated_at"],
+  "properties": {
+    "schema_version": {"const": 1},
+    "artifact": {"const": "diagnosis"},
+    "change": {"type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9]+(?:-[a-z0-9]+)*$"},
+    "status": {"enum": ["reproducing", "minimizing", "testing-hypotheses", "root-cause-confirmed", "blocked"]},
+    "feedback_loop_ready": {"type": "boolean"},
+    "red_command": {"type": ["string", "null"]},
+    "red_evidence": {"type": ["string", "null"]},
+    "cleanup_status": {"enum": ["pending", "clean", "registered"]},
+    "updated_at": {"type": "string", "minLength": 1}
+  },
+  "additionalProperties": true
+}

package/template/workflows/specdev/common/schemas/prototype-record.schema.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:speculo:specdev:prototype-record:v1",
+  "title": "SpecDev Prototype Record Frontmatter",
+  "type": "object",
+  "required": ["schema_version", "artifact", "change", "prototype_id", "question", "branch", "status", "workspace_ref", "project_paths", "assets", "winner", "promotion_target", "cleanup_status", "updated_at"],
+  "properties": {
+    "schema_version": {"const": 1},
+    "artifact": {"const": "prototype-record"},
+    "change": {"type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9]+(?:-[a-z0-9]+)*$"},
+    "prototype_id": {"type": "string", "pattern": "^PROTO-[0-9]{3,}$"},
+    "question": {"type": "string", "minLength": 1},
+    "branch": {"enum": ["logic", "ui"]},
+    "status": {"enum": ["active", "answered", "blocked", "discarded"]},
+    "workspace_ref": {"type": "string", "minLength": 1, "pattern": "^(?!/)(?![A-Za-z]:[\\\\/]).+"},
+    "project_paths": {"type": "array", "items": {"type": "string"}, "uniqueItems": true},
+    "assets": {"type": "array", "items": {"type": "string"}, "uniqueItems": true},
+    "winner": {"type": ["string", "null"]},
+    "promotion_target": {"type": ["string", "null"]},
+    "cleanup_status": {"enum": ["pending", "clean", "registered"]},
+    "updated_at": {"type": "string", "minLength": 1}
+  },
+  "additionalProperties": true
+}