@namewta/speculo 0.6.0 → 0.7.0

package/template/canonical/canonical-specdev-engineering-cognitive-mentor.md

@@ -46,7 +46,7 @@
 
 按存在情况读取：
 
-- 原始请求：`specdev/changes/{change}/source-issue.md`
+- 原始请求：`specdev/changes/{change}/source.md`
 - 分诊结果：`specdev/changes/{change}/triage.md`
 - 诊断结果：`specdev/changes/{change}/diagnosis.md`
 - 当前领域上下文：`specdev/changes/{change}/CONTEXT.md`
@@ -78,7 +78,7 @@
 2. 选择用户指定 change、唯一活跃 change，或按 SpecDev 协议创建新 change；多个候选必须先消歧；
 3. 确认 `specdev/config.json` 存在；不存在时先进入 “初始化设置阶段”；
 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 唯一；状态已登记；主产物已初始化或成功恢复；没有覆盖历史记录。
@@ -208,7 +208,7 @@
 - 用户确认当前没有其他问题，或剩余问题被显式延后；
 - 主产物包含完整 `MLOG`、最终综合和后续路线。
 
-关闭时更新全局状态与 change 状态，完成 `work_history`，将本 Work 加入 `works_run`，并返回主产物完整路径及适用的下一 Work 完整路径。关闭本 Work 不等于完成或归档整个 change。
+关闭时更新全局状态与 change 状态，将本 Work 去重加入 `works_run` 并清空 `current_work`，返回主产物完整路径及适用的下一 Work 完整路径。关闭本 Work 不等于完成或归档整个 change。
 
 **完成标准：**主产物状态与全局状态一致；完整日志可恢复；未伪造理解或 change 完成状态。
 
@@ -1156,26 +1156,13 @@ change 状态：`specdev/changes/{change}/.status.json`。
 ### 开始
 
 - 在 `active` 中找到或创建当前 change；
-- 设置该 change 的 `current_work` 为 `specdev/engineering-cognitive-mentor`；
+- `current_work` 已是 `specdev/engineering-cognitive-mentor` 时恢复，为 null 时设置为该 id；指向其他 Work 时停止并要求先完成显式 handoff；
 - `specdev/changes/{change}/.status.json` 的 `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 和 `specdev/changes/{change}/.status.json` 承载。
 
 ### 等待用户或跨会话暂停
 
 - 保持 `current_work` 为本 Work；
-- 保持唯一 `work_history` 记录未完成；
 - 更新主产物 `updated_at`、`current_phase`、`next_question`、`unresolved_questions` 与 `last_mlog_id`；
 - 每轮在回复前先落盘，确保用户即使中断也可恢复。
 
@@ -1183,10 +1170,9 @@ change 状态：`specdev/changes/{change}/.status.json`。
 
 ### 正常关闭
 
-- 将唯一未完成 `work_history` 的 `completed_at` 写为当前时间，`result` 写为 `completed`；
 - 将本 Work id 以去重方式加入 active change 的 `works_run`；
 - active change 的 `current_work` 与 `specdev/changes/{change}/.status.json` 的 `current_work` 设为 null；
-- 不改变整个 change 的 `result` 或 `change_status`，除非用户明确结束、取消或外部阻塞确实影响整个 change；
+- 不改变整个 change 的 `change_status`，除非用户明确结束或外部阻塞确实影响整个 change；
 - 主产物 `status` 写为 `completed`，记录 `closed_at` 与理解确认状态。
 
 ### 外部阻塞
@@ -1195,15 +1181,14 @@ change 状态：`specdev/changes/{change}/.status.json`。
 
 - 主产物 `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. 主产物幂等初始化
@@ -1433,33 +1418,44 @@ SpecDev 通过分层工件避免同一决策被多个模型反复重做。每个
 
 | 工件 | 具体位置 | 必须决定 | 不应决定 |
 |---|---|---|---|
-| 分诊 | `specdev/changes/{change}/triage.md` | 请求类别、影响、风险、缺失输入和下一 work | 详细实现方案 |
+| 来源快照 | `specdev/changes/{change}/source.md` | 原始请求、捕获时间、locator、hash 和关闭能力 | 当前产品合同或实现状态 |
+| 分诊 | `specdev/changes/{change}/triage.md` | 请求类别、影响、风险、缺失输入、下一 work 和远程 reconcile 状态 | 详细实现方案或开发进度 |
 | 诊断 | `specdev/changes/{change}/diagnosis.md` | 复现、证据、根因、修复不变量和回归契约 | 未经验证的修复实现 |
 | 设计日志 | `specdev/changes/{change}/LOG.md` | 讨论轨迹、确认、延后、替代与废弃结论 | 当前架构权威摘要 |
 | 设计树 | `specdev/changes/{change}/design-tree.json` | 决策节点、依赖、当前 frontier、轮次与共识状态 | 领域真相或架构决定正文 |
-| 领域上下文 | `specdev/changes/{change}/CONTEXT.md` | 当前领域术语、语义和稳定不变量 | 临时会议记录 |
-| 架构决策 | `specdev/changes/{change}/ADR.md` | 已接受架构决策、原因、后果和替代关系 | 尚未决定的方案集合 |
+| Change 领域上下文 | `specdev/changes/{change}/CONTEXT.md` | 本 change 已确认、供下游使用的领域术语和语义 | 永久领域知识或临时会议记录 |
+| Change 架构决策 | `specdev/changes/{change}/ADR.md` | 已成为本 change 下游合同的架构决策、原因、后果和替代关系 | 永久项目 ADR 或尚未决定的方案集合 |
 | Spec | `specdev/changes/{change}/spec.md` | 用户问题、外部行为、范围、验收合同、非功能要求和已锁定实现约束 | 文件级施工步骤 |
 | Ticket | `specdev/changes/{change}/ticket/NN-<ticket-name>.md` | 单一垂直切片的行为、决策、范围、路径所有权、执行路线和验证证据 | 跨 Ticket 里程碑治理 |
 | Tickets Map | `specdev/changes/{change}/tickets-map.md` | 依赖 DAG、合同覆盖、Ready 投影、并行候选和路径冲突 | 单 Ticket 的完整实现契约 |
 | Goal Plan | `specdev/changes/{change}/goal-plan.md` | 跨 Ticket 调度、Gate、共享所有权、迁移顺序、集成和偏差治理 | 复制 Ticket 全文 |
 | Evidence | `specdev/changes/{change}/evidence/T-NN.md` | 实际修改、命令、结果、验收映射、偏差、风险和提交引用 | 新的产品或架构决策 |
+| 代码审查 | `specdev/changes/{change}/reviews/CR-###.md` | 固定点、标准轴和规范轴 finding | 实施修复或合并两轴排名 |
+| 原型记录 | `specdev/changes/{change}/prototypes/{prototype-id}/record.md` | 一个问题、分支、资产、答案、promotion 和清理 | 生产实现或多个问题的计划 |
+| Stakeholder 问卷 | `specdev/changes/{change}/questionnaires/{slug}.md` | 第三方原始回答和恢复条件 | 未经转录确认的产品/架构决定 |
 | Wayfinder 地图 | `specdev/changes/{change}/wayfinder-map.md` | 目的地、说明、已关闭决策索引、战争迷雾和范围之外 | 开放 Ticket 正文或答案详情 |
 | Wayfinder Ticket | `specdev/changes/{change}/investigation/{investigation-id}.md` | 一个可精确陈述的问题、类型、阻塞和关闭状态 | 解决方案评论或交付目标 |
 | Wayfinder solution comment | `specdev/changes/{change}/investigation/comments/{investigation-id}/NN-solution.md` | Ticket 的答案、结果事实和资产指针 | 地图索引或产品实现 |
 | 架构审查 | `specdev/changes/{change}/architecture-review.md` 与 `specdev/changes/{change}/architecture-review.html` | 深化候选、证据、可视化、选择和访谈状态 | 未经用户选择的执行契约 |
 
+Change CONTEXT/ADR 是 active change 内的执行权威，不是 workflow 级永久知识。G 和其他设计/执行 Works 只读 `specdev/context/` 与 `specdev/adr/`；只有 A 在 change 完成、实现证据验证、毕业评估和用户确认后才能写入永久 namespace。未毕业内容随归档 change 保留，不能从 change 工件消失。
+
 ## 2. 权威顺序
 
 同一事项冲突时按下列顺序裁决：
 
 1. 用户最新明确决定；
-2. 当前已接受架构决策：`specdev/changes/{change}/ADR.md`；
-3. 当前外部行为权威：`specdev/changes/{change}/spec.md`；
-4. 当前 Ticket 契约：`specdev/changes/{change}/ticket/NN-<ticket-name>.md`；
-5. 当前跨 Ticket 编排：`specdev/changes/{change}/goal-plan.md`；
-6. 当前代码与运行事实；
-7. 旧计划、旧日志和未经确认的推断。
+2. 当前 change 已接受的架构决策：`specdev/changes/{change}/ADR.md`；
+3. 永久 ADR 与领域上下文：`specdev/adr/`、`specdev/context/`；
+4. 当前外部行为权威：`specdev/changes/{change}/spec.md`；
+5. 当前 Ticket 契约：`specdev/changes/{change}/ticket/NN-<ticket-name>.md`；
+6. 当前跨 Ticket 编排：`specdev/changes/{change}/goal-plan.md`；
+7. 当前代码与运行事实；
+8. 旧计划、旧日志和未经确认的推断。
+
+当前 change 决定与永久知识冲突时，必须在 LOG/ADR 中显式说明替代关系；它只约束当前 change，直到 A 决定是否提升并更新永久版本。
+
+`specdev/changes/{change}/source.md` 只对“原始输入是什么”具有权威；后续用户决定、ADR 和 Spec 可以显式演进该意图。远程来源在摄入后发生变化不会自动改写本地合同，必须重新 Triage。
 
 代码事实可以证明计划已过时，但不能静默改写用户目标或已接受契约。出现这种情况时，按 下方 `<deviation-control>` 标签 退回相应工件修订。
 
@@ -1499,7 +1495,7 @@ SpecDev 通过分层工件避免同一决策被多个模型反复重做。每个
 ## 1. 偏差等级
 
 - **local**：只改变局部实现，不改变 Ticket 的行为、范围、公共契约、路径所有权或验证；记录到 Evidence 后可继续。
-- **ticket**：改变 Ticket 的执行路线、可写范围、局部契约或验收映射，但不改变 Spec；必须停止相关修改、更新 Ticket 并获得 owner 或 Lead 批准。
+- **ticket**：改变 Ticket 的执行路线、可写范围、局部契约或验收映射，但不改变 Spec；必须停止相关修改、更新 Ticket 并获得该 Ticket 或计划明确的批准 owner 同意。
 - **spec**：改变外部行为、范围、用户故事、验收合同或非功能要求；必须返回 “编写 Spec 阶段”。
 - **architecture**：改变已接受架构决策或公共架构约束；必须返回 “设计访谈能力” 并更新 `specdev/changes/{change}/ADR.md`。
 - **release**：改变迁移、兼容窗口、发布门禁、回滚或不可逆批准点；必须停止并获得明确人工批准。
@@ -1534,7 +1530,7 @@ SpecDev 通过分层工件避免同一决策被多个模型反复重做。每个
 
 - 未批准的 ticket、spec、architecture 或 release 偏差不得继续实现。
 - 不得通过扩大 `writable_paths`、删除测试、降低断言或把风险改写成“已知限制”来绕过停止。
-- 偏差影响并发 Agent 时，Lead 必须暂停受影响 Wave，重新计算路径所有权、依赖和 Gate。
+- 偏差影响普通并行执行时，当前集成 owner 必须暂停受影响 Wave，重新计算路径所有权、依赖和 Gate；委派执行由 Lead 承担同一责任。
 
 </deviation-control>
 
@@ -1542,42 +1538,54 @@ SpecDev 通过分层工件避免同一决策被多个模型反复重做。每个
 
 # SpecDev Research
 
-## 触发
+## 输入
+
+- `decision`：研究要支持的一个具体决定；
+- `questions`：需要回答的穷尽问题集；
+- `stop_condition`：何时证据已足够；
+- `caller`：D、G、S、W、R、T 或 I；
+- `target_artifact`：调用方拥有且将接收结果的完整 Path。
 
-当外部 API、库版本、协议、法规、产品能力或最佳实践会改变设计/实现决策，且当前材料不足时使用。
+缺少 owner 或 target 时返回阻塞，不创建 `{change}/research/` 等共享 namespace。
 
 ## 流程
 
-1. 写清楚要支持的具体决策和停止条件。
-2. 优先官方文档、规范、源代码、论文或维护者材料；技术问题优先一手来源。
-3. 核对版本、发布日期、适用环境和已知限制。
-4. 区分：来源明确事实、代码库事实、推断、建议。
-5. 对关键结论至少交叉验证；来源冲突时并列呈现，不强行调和。
-6. 记录摘要、证据、置信度、对 ADR/Spec/Ticket 的影响和仍未知项。
-7. 长期有效且经实现验证后才可由 Archive 提升到永久 research。
+1. 固定问题、版本、环境和停止条件。
+2. 优先官方文档、规范、源代码、论文或维护者材料；技术问题使用一手来源。
+3. 核对发布日期、版本、适用环境、限制和已知冲突。
+4. 对每个会改变决定的实质声明就近给出来源；关键结论交叉验证，来源冲突时并列呈现。
+5. 区分来源事实、代码库事实、推断、建议和未知项。
+6. 返回一个 Markdown block，由 caller 原子写入 `target_artifact`；本 Skill 不自行写 state。
 
-## 输出模板
+## 输出
 
 ```markdown
-# Research: <问题>
-- 决策用途：
-- 范围/版本：
-- 停止条件：
+## Research: <问题>
+- Decision / target:
+- Scope / version:
+- Stop condition:
 
-## Findings
 ### R-001
-- 结论：
-- 类型：官方事实 / 代码事实 / 推断 / 建议
-- 来源：
-- 置信度：high / medium / low
-- 适用限制：
-- 对工件影响：
-
-## Conflicts and Unknowns
-## Recommendation
+- Claim:
+- Type: official fact / code fact / inference / recommendation
+- Source:
+- Confidence:
+- Limits:
+- Artifact impact:
+
+### Conflicts and Unknowns
+### Recommendation
 ```
 
-不得长篇复制受版权保护的来源；使用短引文和自己的准确摘要。
+不得长篇复制受版权保护内容。长期有效且经实现验证的结论只能由 Archive 从调用方工件提升到永久 research。
+
+## 完成标准
+
+- 每个输入问题有答案或明确未知；
+- 每个实质声明就近引用一手来源；
+- 版本、限制、冲突和置信度已记录；
+- 结果有唯一 owning artifact；
+- 本 Skill 没有创建自己的 state 路径。
 
 </research>
 
@@ -1596,7 +1604,7 @@ SpecDev 通过分层工件避免同一决策被多个模型反复重做。每个
   "execution": {
     "max_parallel": 3,
     "deep_ticket_human_approval": true,
-    "shared_path_owner": "lead"
+    "shared_path_owner": "explicit"
   },
   "verification": {
     "test": null,
@@ -1679,11 +1687,10 @@ SpecDev 通过分层工件避免同一决策被多个模型反复重做。每个
 
 ```json
 {
-  "schema_version": 3,
+  "schema_version": 4,
   "workflow": "specdev",
   "active": [],
-  "work_history": [],
-  "completed": []
+  "archived": []
 }
 ```
 
@@ -1694,19 +1701,18 @@ SpecDev 通过分层工件避免同一决策被多个模型反复重做。每个
 ```json
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "urn:speculo:specdev:status:v3",
+  "$id": "urn:speculo:specdev:status:v4",
   "title": "SpecDev Global Status",
   "type": "object",
   "required": [
     "schema_version",
     "workflow",
     "active",
-    "work_history",
-    "completed"
+    "archived"
   ],
   "properties": {
     "schema_version": {
-      "const": 3
+      "const": 4
     },
     "workflow": {
       "const": "specdev"
@@ -1718,30 +1724,27 @@ SpecDev 通过分层工件避免同一决策被多个模型反复重做。每个
         "required": [
           "change",
           "current_work",
-          "works_run",
-          "result"
+          "works_run"
         ],
         "properties": {
           "change": {
-            "type": "string"
+            "type": "string",
+            "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9]+(?:-[a-z0-9]+)*$"
           },
           "current_work": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "pattern": "^specdev/"
           },
           "works_run": {
             "type": "array",
             "items": {
-              "type": "string"
-            }
-          },
-          "result": {
-            "type": [
-              "string",
-              "null"
-            ]
+              "type": "string",
+              "pattern": "^specdev/"
+            },
+            "uniqueItems": true
           },
           "claimed_investigations": {
             "type": "array",
@@ -1769,77 +1772,23 @@ SpecDev 通过分层工件避免同一决策被多个模型反复重做。每个
                   "type": "string"
                 }
               },
-              "additionalProperties": true
+              "additionalProperties": false
             }
           }
         },
-        "additionalProperties": true
+        "additionalProperties": false
       }
     },
-    "work_history": {
-      "type": "array",
-      "items": {
-        "type": "object",
-        "required": [
-          "change",
-          "work_id",
-          "started_at",
-          "completed_at",
-          "result"
-        ],
-        "properties": {
-          "change": {
-            "type": "string"
-          },
-          "work_id": {
-            "type": "string",
-            "pattern": "^specdev/"
-          },
-          "started_at": {
-            "type": "string"
-          },
-          "completed_at": {
-            "type": [
-              "string",
-              "null"
-            ]
-          },
-          "result": {
-            "type": [
-              "string",
-              "null"
-            ]
-          }
-        },
-        "additionalProperties": true
-      }
-    },
-    "completed": {
+    "archived": {
       "type": "array",
       "items": {
-        "type": "object",
-        "required": [
-          "change",
-          "archived_at",
-          "archive_path"
-        ],
-        "properties": {
-          "change": {
-            "type": "string"
-          },
-          "archived_at": {
-            "type": "string"
-          },
-          "archive_path": {
-            "type": "string",
-            "pattern": "^specdev/archive/[0-9]{4}-[0-9]{2}/.+/$"
-          }
-        },
-        "additionalProperties": true
-      }
+        "type": "string",
+        "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9]+(?:-[a-z0-9]+)*$"
+      },
+      "uniqueItems": true
     }
   },
-  "additionalProperties": true
+  "additionalProperties": false
 }
 ```
 
@@ -2017,6 +1966,49 @@ SpecDev 通过分层工件避免同一决策被多个模型反复重做。每个
     }
   },
   "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": {