@namewta/speculo 1.0.18 → 1.0.20

package/template/AGENTS.md

@@ -11,4 +11,4 @@
 
 详细状态、所有权和副作用合同由各 workflow 的 `INDEX.md`、`README.md`、`common/rules/` 和 schema 定义。
 
-编辑任何文档时，读取 `<Path>{roots.skills}/writing-great-skills/references/document-contract.md</Path>` 的保真合同（不自动激活该 Skill）。保留能力、用户明确的交付数量、默认工具、验收与失败停止条件；模式专属流程和长示例按明确入口下沉。真实源优先，保留软链接、许可与必要元数据，不修改系统/插件缓存。交付实际修改、完整前后字符统计、备份、验证和未完成项；没有实际用量对比不宣称 Token 或额度节省比例。
+编辑任何文档时，读取 `<Path>{roots.skills}/writing-for-agents/references/document-contract.md</Path>` 的保真合同（不自动激活该 Skill）。保留能力、用户明确的交付数量、默认工具、验收与失败停止条件；模式专属流程和长示例按明确入口下沉。真实源优先，保留软链接、许可与必要元数据，不修改系统/插件缓存。交付实际修改、完整前后字符统计、备份、验证和未完成项；没有实际用量对比不宣称 Token 或额度节省比例。

package/template/CLAUDE.md

@@ -1,3 +1,3 @@
 # CLAUDE.md
 
-Speculo agent handbook: see [AGENTS.md](./AGENTS.md).
+@AGENTS.md

package/template/canonical/canonical-specdev-goal-plan.md

@@ -18,9 +18,9 @@
 
 ## 读取范围
 
-先读 下方 `<activation-and-memory>` 标签，定位用户指定的 change 或 map，再读状态、当前 map 和所选模式。只有进入 frontier 的 Ticket、命中的项目 Skill、Gate 与恢复证据需要展开；不默认通读所有 Ticket 或永久索引。
+先读 下方 `<activation-and-memory>` 标签，定位用户指定的 change 或 map，再读状态、当前 map 和所选模式。每次只展开实际进入 frontier 的 Ticket、直接依赖 Evidence、命中的项目 Skill、当前 Gate 与恢复证据；不默认通读所有 Ticket 或永久索引。
 
-## 模式与权威
+## 按意图选择模式与权威
 
 | 用户意图 | 模式 | 必须按需读取 |
 |---|---|---|
@@ -79,7 +79,7 @@ node 本地只读 Goal 控制器（不含于网页快照） --map <map-path> --r
 - 等待真实上游产物的未来 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 与 `specdev/changes/{change}/spec.md`、`specdev/changes/{change}/ADR.md`、`specdev/adr/`、`specdev/context/` 和当前代码事实不存在未处理冲突；
@@ -541,6 +541,13 @@ W 的 `specdev/changes/{change}/initiative.json` 只拥有候选 change 的边
 
 父 `specdev/changes/{change}/tickets-map.md` 是 goal-tickets-map 无状态入口，只引用现有 Implementation Map/Plan；它不能拥有第二份 status、owner 或任务清单。统一 P 拥有生命周期，旧 O 仅保留入口与恢复键。
 
+## 新增工件 owner
+
+- T：specdev/changes/{change}/pull-requests/PR-###.md 拥有 PR 交付回执；specdev/triage-runs/TRI-###.md 拥有独立远程操作，绝不复用 external_action/publish_action/capture。
+- R-retro：specdev/changes/{change}/retro/RETRO-###.md 拥有活动复盘建议和来源；不成为永久知识。
+- P：specdev/changes/{change}/prototypes/LOGIC-NNN/logic.md 记录逻辑模型与浏览器证据；index.html 是可运行原型，ready 时 hash 与记录一致。
+- 来源更新：specdev/changes/{change}/source.md 冻结后保持不变。T 将后续读取写入 specdev/changes/{change}/sources/SRC-###.md，记录 replaces、固定 SHA/hash、完整性和原 locator，triage 正文选择有效快照；不得把新远程事实自动升级为已接受 Spec。
+
 </artifact-contract>
 
 <path-ownership>
@@ -730,6 +737,12 @@ Owner 原子更新 `specdev/changes/{change}/.status.json` 的 `change_status`
 
 **完成标准**：完成声明可由本地工件、Git 与验证重建；只有一个 owner 命中；失败 candidate 不污染父分支。
 
+## 非实现复盘终点与 PR 归档门
+
+仅有 R-retro（可先经 T intake）的 review-only change，以 completed 的 RETRO 报告作为等价验收；不能同时存在 Spec、Ticket、Map、Goal Plan、implementation 工件、Evidence 或 worktree。报告 sources 非空、结果诚实、全部验收完成，owner 按原完成转换规则更新状态；存在实现工件时仍走原实现完成门。insufficient-evidence 仅表示报告完整，不表示问题已解决。
+
+PR requested=true 且 status=planned/failed 时阻塞归档；delivery_target=ready 时 draft 也保持未闭合。draft 目标可由 draft/ready 满足，ready 目标只由 ready 满足；waived 须记录放弃交付的授权与原因。创建成功不等于已授权 merge。独立 TRI 不因关联 change 就参与完成/归档门。
+
 </change-completion>
 
 <parent-implementation-orchestration>
@@ -1498,7 +1511,7 @@ node "${ZIP_SCRIPT}" "${RETURN_STAGING}" \
 
 ```json
 {
-  "schema_version": 5,
+  "schema_version": 6,
   "interaction_language": "zh-CN",
   "artifact_language": "zh-CN",
   "git": {
@@ -1522,6 +1535,10 @@ node "${ZIP_SCRIPT}" "${RETURN_STAGING}" \
     "require_evidence": true,
     "ui_design_default_candidates": 3,
     "ui_design_max_candidates": 4
+  },
+  "github": {
+    "include_external_prs": false,
+    "labels": {}
   }
 }
 ```
@@ -1533,60 +1550,171 @@ node "${ZIP_SCRIPT}" "${RETURN_STAGING}" \
 ```json
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "urn:speculo:specdev:config:v5",
+  "$id": "urn:speculo:specdev:config:v6",
   "title": "SpecDev Configuration",
   "type": "object",
-  "required": ["schema_version", "interaction_language", "artifact_language", "git", "execution", "verification", "planning"],
+  "required": [
+    "schema_version",
+    "interaction_language",
+    "artifact_language",
+    "git",
+    "execution",
+    "verification",
+    "planning",
+    "github"
+  ],
   "properties": {
-    "schema_version": {"const": 5},
-    "interaction_language": {"type": "string", "minLength": 1},
-    "artifact_language": {"type": "string", "minLength": 1},
+    "schema_version": {
+      "const": 6
+    },
+    "interaction_language": {
+      "type": "string",
+      "minLength": 1
+    },
+    "artifact_language": {
+      "type": "string",
+      "minLength": 1
+    },
     "git": {
       "type": "object",
-      "required": ["default_branch"],
+      "required": [
+        "default_branch"
+      ],
       "properties": {
-        "default_branch": {"type": ["string", "null"]}
+        "default_branch": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
       },
       "additionalProperties": false
     },
     "execution": {
       "type": "object",
-      "required": ["max_implementation_agents", "max_integration_attempts", "deep_ticket_human_approval", "shared_path_owner"],
+      "required": [
+        "max_implementation_agents",
+        "max_integration_attempts",
+        "deep_ticket_human_approval",
+        "shared_path_owner"
+      ],
       "properties": {
-        "max_implementation_agents": {"type": "integer", "minimum": 1},
-        "max_integration_attempts": {"type": "integer", "minimum": 1},
-        "deep_ticket_human_approval": {"type": "boolean"},
-        "shared_path_owner": {"type": "string", "minLength": 1}
+        "max_implementation_agents": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "max_integration_attempts": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "deep_ticket_human_approval": {
+          "type": "boolean"
+        },
+        "shared_path_owner": {
+          "type": "string",
+          "minLength": 1
+        }
       },
       "additionalProperties": false
     },
     "verification": {
       "type": "object",
-      "required": ["test", "typecheck", "lint", "build"],
+      "required": [
+        "test",
+        "typecheck",
+        "lint",
+        "build"
+      ],
       "properties": {
-        "test": {"type": ["string", "null"]},
-        "typecheck": {"type": ["string", "null"]},
-        "lint": {"type": ["string", "null"]},
-        "build": {"type": ["string", "null"]}
+        "test": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "typecheck": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "lint": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "build": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
       },
       "additionalProperties": true
     },
     "planning": {
       "type": "object",
-      "required": ["default_depth", "require_ready_gate", "require_evidence", "ui_design_default_candidates", "ui_design_max_candidates"],
+      "required": [
+        "default_depth",
+        "require_ready_gate",
+        "require_evidence",
+        "ui_design_default_candidates",
+        "ui_design_max_candidates"
+      ],
       "properties": {
-        "default_depth": {"enum": ["lite", "standard", "deep"]},
-        "require_ready_gate": {"type": "boolean"},
-        "require_evidence": {"type": "boolean"},
-        "ui_design_default_candidates": {"type": "integer", "minimum": 2, "maximum": 4},
-        "ui_design_max_candidates": {"type": "integer", "minimum": 2, "maximum": 4}
+        "default_depth": {
+          "enum": [
+            "lite",
+            "standard",
+            "deep"
+          ]
+        },
+        "require_ready_gate": {
+          "type": "boolean"
+        },
+        "require_evidence": {
+          "type": "boolean"
+        },
+        "ui_design_default_candidates": {
+          "type": "integer",
+          "minimum": 2,
+          "maximum": 4
+        },
+        "ui_design_max_candidates": {
+          "type": "integer",
+          "minimum": 2,
+          "maximum": 4
+        }
       },
       "additionalProperties": true
+    },
+    "github": {
+      "type": "object",
+      "required": [
+        "include_external_prs",
+        "labels"
+      ],
+      "properties": {
+        "include_external_prs": {
+          "type": "boolean"
+        },
+        "labels": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      },
+      "additionalProperties": false
     }
   },
-  "allOf": [{
-    "$comment": "ui_design_default_candidates <= ui_design_max_candidates is enforced by validate-specdev.mjs because JSON Schema cannot compare sibling numeric values."
-  }],
+  "allOf": [
+    {
+      "$comment": "ui_design_default_candidates <= ui_design_max_candidates is enforced by validate-specdev.mjs because JSON Schema cannot compare sibling numeric values."
+    }
+  ],
   "additionalProperties": false
 }
 ```

package/template/canonical/canonical-specdev-grill-with-docs.md

@@ -20,9 +20,9 @@
 
 读取 下方 `<activation-and-memory>` 标签；定位当前 change 的 `specdev/changes/{change}/design-tree.json`、`specdev/changes/{change}/LOG.md`、`specdev/changes/{change}/CONTEXT.md`、`specdev/changes/{change}/ADR.md` 和相关 initiative 决策。先找到相关条目再回读必要原文，不默认整读永久 ADR 或索引。
 
-## 过程与边界
+## 当前 change 的访谈与共识
 
-进入访谈必须读取 下方 `<ref-g-grill-with-docs-references-interview-procedure>` 标签，再按触发分支读取 grilling、领域建模、日志格式或 stakeholder questionnaire。保留完整 frontier、推荐答案和逐轮共识检查，但不替用户回答高影响取舍。
+进入访谈必须读取 下方 `<ref-g-grill-with-docs-references-interview-procedure>` 标签，由该过程在出现设计取舍、术语变化、日志写入或外部 stakeholder 缺口时分别读取 grilling、领域建模、日志格式或 questionnaire；不默认加载所有参考。保留完整 frontier、推荐答案和逐轮共识检查，但不替用户回答高影响取舍。
 
 - 先查仓库可发现事实，只询问会改变行为、架构、风险、范围、迁移或验收的决定。
 - W 的每个 materialized change 在自己的目录拥有设计树和文档；共享答案以来源指针引用，不能共用一棵可写设计树。
@@ -83,7 +83,7 @@
 
 </design-tree-template>
 
-<domain-modeling-rules>
+<domain-modeling>
 
 # 领域建模规则
 
@@ -98,7 +98,7 @@
 
 完成标准：每个 change CONTEXT 条目都是本 change 下游必须使用的项目规范语言；每个 change ADR 都有明确来源和当前 change 的适用范围；没有把候选结论写成永久知识。
 
-</domain-modeling-rules>
+</domain-modeling>
 
 <adr-format>
 
@@ -333,6 +333,13 @@ W 的 `specdev/changes/{change}/initiative.json` 只拥有候选 change 的边
 
 父 `specdev/changes/{change}/tickets-map.md` 是 goal-tickets-map 无状态入口，只引用现有 Implementation Map/Plan；它不能拥有第二份 status、owner 或任务清单。统一 P 拥有生命周期，旧 O 仅保留入口与恢复键。
 
+## 新增工件 owner
+
+- T：specdev/changes/{change}/pull-requests/PR-###.md 拥有 PR 交付回执；specdev/triage-runs/TRI-###.md 拥有独立远程操作，绝不复用 external_action/publish_action/capture。
+- R-retro：specdev/changes/{change}/retro/RETRO-###.md 拥有活动复盘建议和来源；不成为永久知识。
+- P：specdev/changes/{change}/prototypes/LOGIC-NNN/logic.md 记录逻辑模型与浏览器证据；index.html 是可运行原型，ready 时 hash 与记录一致。
+- 来源更新：specdev/changes/{change}/source.md 冻结后保持不变。T 将后续读取写入 specdev/changes/{change}/sources/SRC-###.md，记录 replaces、固定 SHA/hash、完整性和原 locator，triage 正文选择有效快照；不得把新远程事实自动升级为已接受 Spec。
+
 </artifact-contract>
 
 <planning-principles>
@@ -562,7 +569,7 @@ Ticket 只有同时满足以下适用条件才可设置 `ready: true`：
 
 ```json
 {
-  "schema_version": 5,
+  "schema_version": 6,
   "interaction_language": "zh-CN",
   "artifact_language": "zh-CN",
   "git": {
@@ -586,6 +593,10 @@ Ticket 只有同时满足以下适用条件才可设置 `ready: true`：
     "require_evidence": true,
     "ui_design_default_candidates": 3,
     "ui_design_max_candidates": 4
+  },
+  "github": {
+    "include_external_prs": false,
+    "labels": {}
   }
 }
 ```
@@ -597,60 +608,171 @@ Ticket 只有同时满足以下适用条件才可设置 `ready: true`：
 ```json
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "urn:speculo:specdev:config:v5",
+  "$id": "urn:speculo:specdev:config:v6",
   "title": "SpecDev Configuration",
   "type": "object",
-  "required": ["schema_version", "interaction_language", "artifact_language", "git", "execution", "verification", "planning"],
+  "required": [
+    "schema_version",
+    "interaction_language",
+    "artifact_language",
+    "git",
+    "execution",
+    "verification",
+    "planning",
+    "github"
+  ],
   "properties": {
-    "schema_version": {"const": 5},
-    "interaction_language": {"type": "string", "minLength": 1},
-    "artifact_language": {"type": "string", "minLength": 1},
+    "schema_version": {
+      "const": 6
+    },
+    "interaction_language": {
+      "type": "string",
+      "minLength": 1
+    },
+    "artifact_language": {
+      "type": "string",
+      "minLength": 1
+    },
     "git": {
       "type": "object",
-      "required": ["default_branch"],
+      "required": [
+        "default_branch"
+      ],
       "properties": {
-        "default_branch": {"type": ["string", "null"]}
+        "default_branch": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
       },
       "additionalProperties": false
     },
     "execution": {
       "type": "object",
-      "required": ["max_implementation_agents", "max_integration_attempts", "deep_ticket_human_approval", "shared_path_owner"],
+      "required": [
+        "max_implementation_agents",
+        "max_integration_attempts",
+        "deep_ticket_human_approval",
+        "shared_path_owner"
+      ],
       "properties": {
-        "max_implementation_agents": {"type": "integer", "minimum": 1},
-        "max_integration_attempts": {"type": "integer", "minimum": 1},
-        "deep_ticket_human_approval": {"type": "boolean"},
-        "shared_path_owner": {"type": "string", "minLength": 1}
+        "max_implementation_agents": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "max_integration_attempts": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "deep_ticket_human_approval": {
+          "type": "boolean"
+        },
+        "shared_path_owner": {
+          "type": "string",
+          "minLength": 1
+        }
       },
       "additionalProperties": false
     },
     "verification": {
       "type": "object",
-      "required": ["test", "typecheck", "lint", "build"],
+      "required": [
+        "test",
+        "typecheck",
+        "lint",
+        "build"
+      ],
       "properties": {
-        "test": {"type": ["string", "null"]},
-        "typecheck": {"type": ["string", "null"]},
-        "lint": {"type": ["string", "null"]},
-        "build": {"type": ["string", "null"]}
+        "test": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "typecheck": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "lint": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "build": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
       },
       "additionalProperties": true
     },
     "planning": {
       "type": "object",
-      "required": ["default_depth", "require_ready_gate", "require_evidence", "ui_design_default_candidates", "ui_design_max_candidates"],
+      "required": [
+        "default_depth",
+        "require_ready_gate",
+        "require_evidence",
+        "ui_design_default_candidates",
+        "ui_design_max_candidates"
+      ],
       "properties": {
-        "default_depth": {"enum": ["lite", "standard", "deep"]},
-        "require_ready_gate": {"type": "boolean"},
-        "require_evidence": {"type": "boolean"},
-        "ui_design_default_candidates": {"type": "integer", "minimum": 2, "maximum": 4},
-        "ui_design_max_candidates": {"type": "integer", "minimum": 2, "maximum": 4}
+        "default_depth": {
+          "enum": [
+            "lite",
+            "standard",
+            "deep"
+          ]
+        },
+        "require_ready_gate": {
+          "type": "boolean"
+        },
+        "require_evidence": {
+          "type": "boolean"
+        },
+        "ui_design_default_candidates": {
+          "type": "integer",
+          "minimum": 2,
+          "maximum": 4
+        },
+        "ui_design_max_candidates": {
+          "type": "integer",
+          "minimum": 2,
+          "maximum": 4
+        }
       },
       "additionalProperties": true
+    },
+    "github": {
+      "type": "object",
+      "required": [
+        "include_external_prs",
+        "labels"
+      ],
+      "properties": {
+        "include_external_prs": {
+          "type": "boolean"
+        },
+        "labels": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      },
+      "additionalProperties": false
     }
   },
-  "allOf": [{
-    "$comment": "ui_design_default_candidates <= ui_design_max_candidates is enforced by validate-specdev.mjs because JSON Schema cannot compare sibling numeric values."
-  }],
+  "allOf": [
+    {
+      "$comment": "ui_design_default_candidates <= ui_design_max_candidates is enforced by validate-specdev.mjs because JSON Schema cannot compare sibling numeric values."
+    }
+  ],
   "additionalProperties": false
 }
 ```
@@ -1099,7 +1221,7 @@ Ticket 只有同时满足以下适用条件才可设置 `ready: true`：
 
 ### 5. 同步 change-local 领域模型
 
-加载 下方 `<domain-modeling-rules>` 标签。每轮先写 LOG，再把已确认且本 change 下游必须使用的项目规范术语同步到 change CONTEXT，最后把同时满足三个准入条件、已成为本 change 合同的架构决定写入 change ADR。
+加载 下方 `<domain-modeling>` 标签。每轮先写 LOG，再把已确认且本 change 下游必须使用的项目规范术语同步到 change CONTEXT，最后把同时满足三个准入条件、已成为本 change 合同的架构决定写入 change ADR。
 
 历史轨迹只留在 LOG；未确认选项不写成已接受 ADR；已有 change ADR 被替代时建立 supersedes 链。同步只更新本 change 工件，不创建、合并或改写永久 `context/`、`adr/`；它记录共识生长过程，不授权产品实现。
 
@@ -1136,7 +1258,7 @@ frontier 为空时，向用户确认设计树的每个分支均已走过且已
 
 - 质询协议：下方 `<grilling-protocol>` 标签
 - 设计树模板：下方 `<design-tree-template>` 标签
-- 领域建模：下方 `<domain-modeling-rules>` 标签
+- 领域建模：下方 `<domain-modeling>` 标签
 - ADR 格式：下方 `<adr-format>` 标签
 - CONTEXT 格式：下方 `<context-format>` 标签
 - LOG 格式：下方 `<log-format>` 标签