@namewta/speculo 1.0.24 → 2.0.2

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

@@ -0,0 +1,153 @@
+{
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {
+      "const": 1
+    },
+    "artifact": {
+      "const": "prototype-browser-evidence"
+    },
+    "prototype_digest": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$"
+    },
+    "generated_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "provider": {
+      "type": "string",
+      "minLength": 1
+    },
+    "inspected_files": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "cases": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string",
+            "minLength": 1
+          },
+          "width": {
+            "type": "integer",
+            "minimum": 320
+          },
+          "height": {
+            "type": "integer",
+            "minimum": 200
+          },
+          "screenshot": {
+            "type": "string",
+            "minLength": 1
+          },
+          "checks": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "rendered": {
+                "const": true
+              },
+              "no_overflow": {
+                "const": true
+              },
+              "keyboard": {
+                "const": true
+              },
+              "focus": {
+                "const": true
+              },
+              "long_text": {
+                "const": true
+              },
+              "zoom": {
+                "const": true
+              },
+              "reduced_motion": {
+                "const": true
+              },
+              "states": {
+                "const": true
+              }
+            },
+            "required": [
+              "rendered",
+              "no_overflow",
+              "keyboard",
+              "focus",
+              "long_text",
+              "zoom",
+              "reduced_motion",
+              "states"
+            ]
+          },
+          "states": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "string",
+              "minLength": 1
+            }
+          },
+          "entry": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "required": [
+          "id",
+          "width",
+          "height",
+          "screenshot",
+          "checks",
+          "states",
+          "entry"
+        ]
+      }
+    },
+    "console_errors": {
+      "type": "array",
+      "maxItems": 0
+    },
+    "offline": {
+      "const": true
+    },
+    "design_review": {
+      "type": "string",
+      "minLength": 1
+    },
+    "technical_review": {
+      "type": "string",
+      "minLength": 1
+    },
+    "rechecked": {
+      "const": true
+    }
+  },
+  "required": [
+    "schema_version",
+    "artifact",
+    "prototype_digest",
+    "generated_at",
+    "provider",
+    "inspected_files",
+    "cases",
+    "console_errors",
+    "offline",
+    "design_review",
+    "technical_review",
+    "rechecked"
+  ],
+  "$id": "urn:speculo:specdev:prototype-browser-evidence:v1",
+  "$schema": "https://json-schema.org/draft/2020-12/schema"
+}

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

@@ -276,6 +276,46 @@
         "minLength": 1
       },
       "uniqueItems": true
+    },
+    "ui_change": {
+      "type": "boolean"
+    },
+    "design_ref": {
+      "type": [
+        "object",
+        "null"
+      ],
+      "properties": {
+        "revision": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "digest": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$"
+        },
+        "pages": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string"
+          }
+        },
+        "acceptance": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string"
+          }
+        }
+      },
+      "required": [
+        "revision",
+        "digest",
+        "pages",
+        "acceptance"
+      ],
+      "additionalProperties": false
     }
   },
   "$defs": {

package/template/workflows/specdev/common/skills/code-review/SKILL.md

@@ -1,16 +1,20 @@
 ---
 name: code-review
-description: 从不可变固定点对本地 diff 执行隔离的标准轴与规范轴审查，供独立 C Work 和 I Work 最终审查共同调用。
-compatibility: Requires the owning Speculo workflow and its workspace path resolver.
-metadata: {"speculo-legacy-name": "specdev-code-review"}
+description: 对固定的本地文件快照或不可变 Git diff 执行隔离的标准轴与规范轴审查，供独立 C Work 和 I Work 最终审查共同调用。
+compatibility: Requires the owning Speculo workflow resources and explicit project roots.
+metadata: {"speculo-source-id": "specdev-code-review"}
 ---
 
 # SpecDev Code Review
 
 本 Skill 返回审查结果，不创建 runtime namespace。调用方分别负责 C review 工件或 I Evidence。
 
+采用调用方按 <Path>{roots.references}/coordination/coordination-contract.md</Path> 确定的当前 review 阶段执行方式，复用已有选择和授权；I 的实现方式不能覆盖明确的 review 阶段选择。未明确指定时使用当前宿主实际具备的 reviewer 能力，兼容 App、CLI 等；明确指定 CLI 交互等方式时按选择执行，选择 Herdr 才通过项目内 Herdr Skill 交接。两轴输入隔离、只读范围和独立审查要求在各方式下相同；能力不足时报告未验证或阻塞，不能用自审冒充独立 reviewer。task 上下文只执行所分配的轴，不再启动另一轮编排。
+
 ## 输入
 
+默认 diff 模式使用下列 fixed_point/head/diff/log。C 显式本地文件分支使用 `review_mode: source-files` 与 `source_snapshot`（路径/原始字节 SHA256）；不提供虚假的 Git 字段。两种模式均须提供相同的规范、标准、范围与隔离输入，I 最终审查保留 diff 模式。
+
 - `fixed_point`：已解析的 commit SHA；
 - `head`：已解析的 HEAD/checkpoint SHA；
 - `diff_command`：由调用方冻结的实际 argv；legacy 默认三点，显式 range/commit 使用已确认端点，不由 reviewer 换范围；
@@ -22,7 +26,7 @@ metadata: {"speculo-legacy-name": "specdev-code-review"}
 
 ## 流程
 
-1. 重验 fixed point/head、实际 diff 语义和摘要；无效引用不启动 reviewer。合法空 diff 由调用方返回 no-diff，不伪造 approved 或复用非空报告。显式范围不得回退为默认三点比较。
+1. diff 模式重验 fixed point/head、实际 diff 语义和摘要；无效引用不启动 reviewer。合法空 diff 由调用方返回 no-diff，不伪造 approved 或复用非空报告。显式范围不得回退为默认三点比较。source-files 模式重验固定路径与原字节，不推断历史 diff 或 commit。
 2. 加载 `<Path>{roots.workflows}/specdev/common/skills/code-review/references/source-discovery.md</Path>`，穷尽规范和标准来源。
 3. 发现已有审查并拟复用时，先读取 `<Path>{roots.workflows}/specdev/common/skills/code-review/references/result-reuse.md</Path>`，完整核对输入、两轴隔离与原始证据；能证明相同的轴保留原结果，其余轴按下列步骤运行；未能证明相同就正常重审两轴。
 4. 加载 `<Path>{roots.workflows}/specdev/common/skills/code-review/references/fowler-smells.md</Path>` 作为标准轴最低启发式；仓库明确标准优先。
@@ -32,6 +36,8 @@ metadata: {"speculo-legacy-name": "specdev-code-review"}
 
 ## 输出
 
+source-files 结果以 `review_mode` 和 `source_snapshot` 代替下例 Git 字段，其余两轴、来源和限制结构相同。
+
 ```text
 {
   fixed_point, head, diff_command, commit_log,
@@ -46,7 +52,7 @@ Finding 必须包含 severity、项目相对 Path/代码块、具体风险、依
 
 ## 完成标准
 
-- fixed point、head、diff 和 commits 固定且可重复；
+- diff 的 fixed point、head、diff、commits 或 source-files 的原字节快照固定且可重复；
 - 仓库标准优先于 Fowler 启发式；
 - 两个 reviewer 上下文没有相互发现污染；
 - 每个发现可定位且说明行为风险；

package/template/workflows/specdev/common/skills/code-review/references/result-reuse.md

@@ -4,7 +4,7 @@
 
 | 必须相同并可回读 | 核对证据 |
 |---|---|
-| fixed_point、head、实际 diff 比较模式（legacy 默认三点）与 commit 范围 | 本地不可变 SHA、diff 字节摘要 |
+| review_mode、实际比较或文件范围 | diff 模式的 fixed_point/head、不可变 SHA、diff 摘要与 commit 范围（legacy 默认三点）；source-files 的路径与原字节摘要；不可跨模式复用 |
 | 规范、标准、ADR 和适用项目指令 | 稳定来源路径、原始字节摘要与明确范围 |
 | review Skill 与当前触发的全部参考 | ID、入口/参考字节摘要、风险分支与跳过理由 |
 | 与结论相关的工具、测试环境、配置 | 实际版本/配置摘要与观察证据；未记录不能宣称相同 |
@@ -12,4 +12,4 @@
 
 Lead 必须回读真实原报告和证据；相同文件名、报告“通过”文字、相同 HEAD 或结构校验均不足。任一输入变化、缺失、不可解析或来源不明，重跑受影响轴；无法证明两轴输入独立时重跑两轴。新风险范围必须完整审查，不因复用缩减 finding 数量。
 
-复用保持原结果与来源，不能把 request-changes、skipped:no-spec 或未测结果改成 passed。C 仍创建自己的新 CR 报告并引用原证据；I 仍由 Lead 写入本票 Evidence，旧报告/旧完成证据不覆盖。复用报告不跳过当前 workspace/集成/E2E/授权检查，不新增全局缓存、状态树或完成捷径。
+复用保持原结果与来源，不能把 request-changes、skipped:no-spec 或未测结果改成 passed。有 change 的正式 C 仍创建自己的新 CR 报告并引用原证据；会话文件审查只返回本次结果；I 仍由 Lead 写入本票 Evidence，旧报告/旧完成证据不覆盖。复用报告不跳过当前 workspace/集成/E2E/授权检查，不新增全局缓存、状态树或完成捷径。

package/template/workflows/specdev/common/skills/code-review/references/reviewer-contracts.md

@@ -2,11 +2,11 @@
 
 ## 标准轴
 
-输入仅包含固定 diff/log、标准来源和 Fowler baseline。报告仓库规则违规和判断性 smell，引用来源与代码块，区分 hard violation 与 heuristic，并跳过工具链已强制执行的纯格式项。
+输入仅包含固定 diff/log（source-files 为固定文件快照）、标准来源和 Fowler baseline。报告仓库规则违规和判断性 smell，引用来源与代码块，区分 hard violation 与 heuristic，并跳过工具链已强制执行的纯格式项。
 
 ## 规范轴
 
-输入仅包含固定 diff/log 与规范来源。报告缺失或不完整需求、超出范围行为和语义/失败/边界错误，并引用具体规范来源。
+输入仅包含固定 diff/log（source-files 为固定文件快照）与规范来源。报告缺失或不完整需求、超出范围行为和语义/失败/边界错误，并引用具体规范来源。
 
 ## 隔离与结果
 

package/template/workflows/specdev/common/skills/code-review/references/source-discovery.md

@@ -4,11 +4,13 @@
 
 按顺序查找并记录每一步结论：
 
-1. commit message 中的 Issue/PR 引用，对应本地 `<Path>{roots.state}/specdev/changes/{change}/source.md</Path>`；
+1. commit message 中的 Issue/PR 引用，对应本地 `<Path>{roots.state}/specdev/changes/{change}/source.md</Path>`；显式 source-files 无 commit 时记 not-applicable，不创建该来源文件；
 2. 调用方显式提供的 Spec、Ticket、ADR、Goal Plan 或其他路径；
 3. 与分支或功能匹配的仓库 `docs/`、`specs/` 或同类规范文件；
 4. 都不存在时询问规范是否确实不存在。确认不存在后规范轴标记 `skipped:no-spec`。
 
+UI 范围按 <Path>{roots.workflows}/specdev/common/rules/design-contract.md</Path> 找到批准 <Path>{roots.state}/specdev/changes/{change}/DESIGN.md</Path>、对应基线 revision/digest、Ticket design_ref 与 `Design Conformance`。这些是规范轴的必需来源；缺失或漂移报告具体缺口，不因其他 Spec 存在而忽略，不将原型截图等同实现验证。
+
 远程 Issue/PR 必须先由 Triage 冻结，或解析为本地不可变 SHA；review 不把可变远程正文当作唯一权威。
 
 ## 标准来源

package/template/workflows/specdev/common/skills/dev-worktree/SKILL.md

@@ -1,32 +1,32 @@
 ---
 name: dev-worktree
-description: 管理 SpecDev required Ticket 的 Git worktree；创建隔离来源 workspace、固定实现 commit，并由 Lead 在 parent-candidate checkout 验证后推进父分支。
+description: 管理 SpecDev required Ticket 或 Direct Spec change 的 Git worktree；创建隔离来源 workspace、固定实现 commit，并由 Lead 在 parent-candidate checkout 验证后推进父分支。
 compatibility: Requires the owning Speculo workflow and its workspace path resolver.
 ---
 
 # Dev Worktree
 
-本 Skill 由 T-tickets、P-goal-plan 和 I-implement 复用。仅在 Goal Plan 选择 `required` 时使用完整 source → candidate → parent 状态机；`current` Ticket 不调用本 Skill。
+本 Skill 由 T-tickets、P-goal-plan 和 I-implement 复用。按 <Path>{roots.workflows}/specdev/common/rules/execution-policy.md</Path> 选择 `required` 时使用 source → candidate → parent 状态机，无需先建 Goal；`current` 不调用本 Skill。原生执行与 Herdr 使用同一工作区合同。
 
 ## 输入
 
 - `operation=create | restore | finalize | remove`；
-- `purpose=ticket`；
+- `purpose=ticket | direct-spec`；
 - repository、父分支、`base_sha`、branch、portable workspace locator；
 - workspace、implementation 和 integration owner；
 - 允许动作、路径合同、验证合同、调用方状态记录位置。
 
-required Ticket 还必须提供 Ready Ticket、Goal Plan（若存在）、Evidence 路径、implementation commit 与本地 candidate integration/父分支更新授权。缺失时返回 blocked；current Ticket 应按 I-implement 的 direct-parent 规则执行。
+required Ticket 提供 Ready Ticket；Direct Spec 提供获批完整规格及验证合同。两者都提供实际存在的 Goal/父计划、原 Evidence 路径、Lead、尝试上限来源、implementation commit 与 local candidate integration/父分支更新授权。缺失时返回 blocked；不为这些输入补造 Ticket/Goal。
 
 ## 1. 创建或恢复
 
-`operation=create` 时加载 `<Path>{roots.workflows}/specdev/common/skills/dev-worktree/references/create.md</Path>`。Ticket 使用 `specdev-worktree/<ticket-id>`；同一 Ticket 只存在一个来源 worktree。`operation=restore` 时重读实际 Git worktree/branch/tip/dirty 状态并与调用方记录核对，漂移时停止。
+`operation=create` 时加载 `<Path>{roots.workflows}/specdev/common/skills/dev-worktree/references/create.md</Path>`。Ticket 使用 `specdev-worktree/<change>/<ticket-id>`；Direct Spec 使用 `specdev-worktree/<change>/direct-spec`。每个实现单元只有一个来源 worktree。`operation=restore` 时重读实际 Git worktree/branch/tip/dirty 状态并与调用方记录核对，漂移时停止。
 
 **完成标准**：来源基线、branch、locator、owners 和实际 Git 状态一致；现有用户改动未被覆盖。
 
 ## 2. 来源实现门
 
-implementation owner 只在来源 worktree 修改授权项目路径，运行 Ticket 要求的单元、组件、静态、类型、lint/build 等非 E2E 检查。进入 `review` 前，worktree 必须 clean，branch tip 必须是已授权的 `source_checkpoint` commit，实际 diff 必须符合路径合同。
+implementation owner 只在来源 worktree 修改授权项目路径，运行规格或 Ticket 要求的单元、组件、静态、类型、lint/build 等非 E2E 检查。进入 `review` 前，worktree 必须 clean，branch tip 必须是已授权的 `source_checkpoint` commit，实际 diff 必须符合路径合同。
 
 **完成标准**：source checkpoint 不可变且可达；来源 worktree 没有 E2E pass 声明。
 
@@ -36,18 +36,18 @@ implementation owner 只在来源 worktree 修改授权项目路径，运行 Tic
 
 本地 candidate checkout/branch 的创建、重建和回收属于已授权 local candidate integration；来源 branch/worktree 的删除仍需要独立 cleanup 授权。push、PR、remote merge、deploy、migration 和生产动作不从本 Skill 继承。
 
-**完成标准**：Ticket `integrated` 时父 HEAD 精确等于记录的 result SHA，并包含 source checkpoint；失败或 stale 时父分支未变化。后续 `removed` 只表示来源 branch/worktree 已清理，不撤销该集成事实。
+**完成标准**：执行单元 `integrated` 时父 HEAD 精确等于记录的 result SHA，并包含 source checkpoint；失败或 stale 时父分支未变化。后续 `removed` 只表示来源 branch/worktree 已清理，不撤销该集成事实。
 
 ## 4. 移除
 
-`operation=remove` 先验证 Ticket 已 `integrated`、目标 worktree clean、checkpoint 可恢复且删除目标精确。只有明确 cleanup 授权时删除来源 branch/worktree；强制删除需要单独确认。删除后重读 `git worktree list` 与 refs，并只把调用方生命周期状态更新为 `removed`；`base_sha`、source checkpoint、candidate/result、验证、E2E 与 Evidence 字段必须原样保留。
+`operation=remove` 先验证执行单元已 `integrated`、目标 worktree clean、checkpoint 可恢复且删除目标精确。只有明确 cleanup 授权时删除来源 branch/worktree；强制删除需要单独确认。删除后重读 `git worktree list` 与 refs，并只把调用方生命周期状态更新为 `removed`；`base_sha`、source checkpoint、candidate/result、验证、E2E 与 Evidence 字段必须原样保留。
 
 **完成标准**：只删除精确授权目标；失败保留现场与恢复命令。
 
 ## 固定规则
 
-- Agent Team 不决定 worktree；Ticket 切片本身决定来源 worktree；
-- Ticket E2E 只在 Lead-owned parent-candidate checkout 运行；
-- 每个 Done Ticket 必须有 source commit 与父分支 result，worktree 状态为 `integrated` 或其清理后终态 `removed`；
+- 执行方式与工作区正交；获批策略决定是否使用 worktree，Ticket 或 Direct Spec change 决定工作单元；
+- required E2E 只在 Lead-owned parent-candidate checkout 运行；
+- 每个 required 实现单元完成前必须有 source commit 与父分支 result，worktree 状态为 `integrated` 或其清理后终态 `removed`；
 - candidate 失败保留来源 worktree 修正，父分支不动；
 - 成功集成不自动清理来源 branch/worktree。

package/template/workflows/specdev/common/skills/dev-worktree/references/create.md

@@ -1,22 +1,24 @@
 # Create Or Restore Worktree
 
-## Ticket 前置条件
+## 前置条件
 
-- Ticket Ready，项目根是有效 Git repository，父分支和 `base_sha` 可解析；
+- Ticket Ready 或完整 Direct Spec 已获批且规格就绪，项目根是有效 Git repository，父分支和 `base_sha` 可解析；
 - implementation commit 与 local candidate integration/父分支更新已授权；
 - workspace、implementation、integration owner 唯一；integration owner 必须为 Lead；
-- `specdev-worktree/` 已由 Speculo init 加入项目 `.gitignore`；
+- 检查 `specdev-worktree/` 已被 Git ignore；未初始化项目由当前 I 在授权写集内补充该忽略规则并记录，不能强制运行 init；
 - 目标 branch/worktree 不覆盖现有用户 workspace，路径合同无冲突。
 
-## 创建 Ticket 来源 worktree
+## 创建来源 worktree
+
+先确定 `unit-id`：Ticket 使用真实 ID（如 T-01），Direct Spec 固定为 `direct-spec`；change 使用已解析的 change 名。下列路径由两者共同限定。
 
 1. 重读父分支 HEAD、工作树、现有 worktrees 与 refs；父 HEAD 与计划基线不一致时由 Lead决定更新 `base_sha` 或阻塞；
-2. 固定 branch `speculo/<change>/<ticket-id>` 与 locator `specdev-worktree/<ticket-id>`；
-3. 确认目标 branch/path 不存在，或其实际记录精确匹配当前 Ticket；
-4. 从 `base_sha` 创建 Git worktree，不复用其他 Ticket 目录；
+2. 固定 branch `speculo/<change>/<unit-id>` 与 locator `specdev-worktree/<change>/<unit-id>`；
+3. 确认目标 branch/path 不存在，或其实际记录精确匹配当前实现单元；
+4. 从 `base_sha` 创建 Git worktree，不复用其他实现单元目录；
 5. 在来源 worktree 读取项目 Agent 指令、依赖、构建与路径合同；
 6. 安装实际需要的依赖，运行最小非 E2E 基线；
-7. Lead 写入 `<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>`，状态为 `active`。
+7. Lead 将实际 workspace、owner、checkpoint 和 `status: active` 记录在本单元原 Evidence 的 `## Workspace Execution Record` 唯一 JSON object 中，保留原执行字段；不创建全局 worktree 镜像。
 
 初始记录：
 
@@ -30,29 +32,35 @@
   "base_sha": "<immutable-sha>",
   "parent_branch": "<parent-branch>",
   "branch": "speculo/<change>/T-01",
-  "workspace_ref": "specdev-worktree/T-01",
+  "workspace_ref": "specdev-worktree/<change>/T-01",
   "source_checkpoint": null,
   "integration": {
     "status": "pending",
+    "parent_ref": "<parent-branch>",
     "parent_before_sha": null,
     "source_sha": null,
     "candidate_sha": null,
+    "candidate_tree_sha": null,
     "candidate_branch": null,
     "candidate_workspace_ref": null,
     "result_sha": null,
     "method": null,
     "conflict_paths": [],
     "verification": "pending",
-    "e2e": {"required": false, "status": "not-required", "evidence": null},
+    "full_suite": {"required": true, "status": "pending", "reason": null, "evidence": null},
+    "e2e": {"required": false, "status": "not-required", "reason": "实际范围无端到端风险时填写依据", "evidence": null},
     "evidence": "<Path>{roots.state}/specdev/changes/<change>/evidence/T-01.md</Path>",
-    "attempts": 0
+    "attempts": 0,
+    "promotion_status": "pending"
   },
   "status": "active",
   "updated_at": "<ISO-8601>"
 }
 ```
 
-`e2e.required` 与 Ticket/Goal Plan disposition 一致；required 时初始 status 为 `pending`。
+Direct Spec 将 `ticket_id` 替换为 `purpose: "direct-spec"`、`change: "<change>"`、`integration_attempt_limit: <实际正整数上限>`；branch 与 workspace 的单元部分替换为 direct-spec，integration.evidence 指向 <Path>{roots.state}/specdev/changes/{change}/evidence/direct-spec.md</Path>。不额外创建 Ticket。
+
+`full_suite` 与 `e2e` 的 required/reason 依据 Spec/Ticket/有效计划的实际验证合同；required 初始为 pending，not-required 必须给真实理由。未发生操作不预填通过。
 
 ## 恢复
 

package/template/workflows/specdev/common/skills/dev-worktree/references/finalize.md

@@ -1,27 +1,27 @@
 # Candidate Merge And Parent Integration
 
-仅由 Lead/integration owner 对状态为 `review` 的 Ticket 调用。
+仅由 Lead/integration owner 对处于 review 的 Ticket 或 Direct Spec 执行单元调用。Ticket 状态来自原票；Direct Spec 状态来自原 Evidence 的 Workspace Execution Record。unit-id 为真实 Ticket ID 或 direct-spec。
 
 ## 1. 接收 source checkpoint
 
-1. 核对 Ticket、Goal Plan、Evidence 目标、owner 与本地 integration 授权；
+1. 核对获批 Spec/Ready Ticket、实际存在的计划、Evidence 目标、owner 与本地 integration 授权；
 2. 验证来源 worktree clean，branch tip 精确等于 `source_checkpoint`，commit 从 `base_sha` 可达；
 3. 审计实际 diff 未越过 writable/shared owner 合同；
 4. 确认 source-worktree 必跑非 E2E 检查已执行，且没有把 E2E 自报为通过；
 5. 重读父分支 checkout clean、HEAD 与 remote/本地约定，记录 `parent_before_sha`。
 
-建立新 candidate 前先比较 Ticket `attempts` 与有效 Plan 的 `integration_attempt_limit`。若前一轮尚未通过且当前 attempts 已达到上限，不创建或重建 candidate、不增加 attempts；保留 source workspace、旧 candidate 与失败记录，将 Ticket/worktree 标为 `blocked`，向有效 Lead 返回 `integration-attempt-limit`。
+建立新 candidate 前先比较原记录 `attempts` 与有效 Plan 或无 Goal 执行合同的 `integration_attempt_limit`。若前一轮尚未通过且当前 attempts 已达到上限，不创建或重建 candidate、不增加 attempts；保留 source workspace、旧 candidate 与失败记录，将执行记录及已有 Ticket 标为 `blocked`，向有效 Lead 返回 `integration-attempt-limit`。
 
 其他预检失败时保持 `review`/`blocked`，不开始候选合并。
 
 ## 2. 建立 parent-candidate checkout
 
-1. 使用 branch `speculo/integration/<change>/<ticket-id>` 和 locator `specdev-worktree/.integration/<ticket-id>`，从最新 `parent_before_sha` 建立 Lead-owned integration worktree；
+1. 使用 branch `speculo/integration/<change>/<unit-id>` 和 locator `specdev-worktree/.integration/<change>/<unit-id>`，从最新 `parent_before_sha` 建立 Lead-owned integration worktree；
 2. 如果父 SHA 是 source checkpoint 的祖先，在 candidate checkout 执行 `git merge --ff-only <source_checkpoint>`，`method=fast-forward`；
 3. 否则执行 `git merge --no-ff --no-commit <source_checkpoint>`；
-4. 冲突按 `<Path>{roots.workflows}/specdev/I-implement/merge-conflict-protocol.md</Path>` 处理。需要新产品决定时执行 `git merge --abort`，记录 blocker 并返回来源 worktree；
+4. 冲突按 `<Path>{roots.workflows}/specdev/specdev-i-implement/references/merge-conflict-protocol.md</Path>` 处理。需要新产品决定时执行 `git merge --abort`，记录 blocker 并返回来源 worktree；
 5. 对分叉结果创建一次 Lead-owned candidate merge commit，`method=merge-commit`；
-6. 记录 candidate branch/locator、`candidate_sha`、`source_sha`、冲突路径与 attempts，worktree 状态改为 `integrating`、integration 状态改为 `candidate`。
+6. 记录 candidate branch/locator、`candidate_sha`、实际 Git tree SHA `candidate_tree_sha`、`source_sha`、冲突路径与 attempts，worktree 状态改为 `integrating`、integration 状态改为 `candidate`。
 
 重试前从最新父分支重建 candidate branch/worktree；旧 candidate SHA 保存在 Evidence。候选生命周期的重建/回收包含在 local candidate integration 授权中。
 
@@ -29,11 +29,11 @@
 
 在 candidate checkout 运行：
 
-- Ticket 受影响集成与回归；
+- 当前实现单元受影响集成与回归；
 - 项目要求的 typecheck/lint/build 或其他父状态检查；
-- 仅当 Ticket/Goal Plan `e2e.required=true` 时运行对应 E2E。
+- 仅当 Spec/Ticket/有效执行合同 `e2e.required=true` 时运行对应 E2E。
 
-每条命令记录运行环境 `parent-candidate`、退出码与摘要。E2E required 未运行或失败时 integration `verification=failed`、`status=failed`；父分支保持 `parent_before_sha`。当本轮失败使 attempts 达到 Goal Plan 快照的 `integration_attempt_limit` 时，保存本轮失败并返回 Lead 复盘；不得继续机械修正、放宽断言、删除检查或发明行为。上限是 Lead 复盘触发点，不是永久禁止恢复。
+每条命令记录运行环境 `parent-candidate`、退出码与摘要。E2E required 未运行或失败时 integration `verification=failed`、`status=failed`；父分支保持 `parent_before_sha`。当本轮失败使 attempts 达到有效执行合同的 `integration_attempt_limit` 时，保存本轮失败并返回 Lead 复盘；不得继续机械修正、放宽断言、删除检查或发明行为。上限是 Lead 复盘触发点，不是永久禁止恢复。
 
 ## 4. 推进父分支
 
@@ -42,13 +42,13 @@
 1. 重读父分支 HEAD；不等于 `parent_before_sha` 时将 candidate 标记 `stale`，不推进父分支并从步骤 2 重建；
 2. 在父分支 checkout 执行 `git merge --ff-only <candidate_sha>`；候选 merge commit 本身已以父 SHA 为第一祖先，因此不再创建第二个 merge commit；
 3. 重读父 HEAD、tree 与 ancestor 关系，确认 HEAD 精确等于 candidate SHA 且包含 source checkpoint；
-4. 写入 `result_sha=candidate_sha`、`verification=passed`、E2E 最终状态和 Evidence；
-5. integration/status 改为 `passed`/`integrated`，再由 Lead 标记 Ticket Done。
+4. 写入 `result_sha=candidate_sha`、`verification=passed`、full_suite/E2E 最终状态、`promotion_status=applied` 和 Evidence；
+5. integration/status 改为 `passed`/`integrated`，再由 Lead 标记 Ticket Done 或在 Direct Spec 全部 AC 通过后完成 change。
 
 ## 5. 失败、清理与恢复
 
-- candidate 检查失败：父分支不动，Ticket 回 `in_progress` 或 `blocked`，来源 worktree 保留；
-- 达到 integration attempt 上限：保留全部 source/candidate checkpoint 与失败记录，等待 Lead 在 Ticket Evidence 写明共同失败模式、最可能原因、下一轮改变和下一 owner/路由；只有形成有实质变化的新 Dispatch Packet 后，Lead 才可将当前 Ticket `attempts` 重置为 `0` 并重新进入 finalize；
+- candidate 检查失败：父分支不动，已有 Ticket 回 `in_progress` 或 `blocked`，来源 worktree 保留；
+- 达到 integration attempt 上限：保留全部 source/candidate checkpoint 与失败记录，等待 Lead 在原 Evidence 写明共同失败模式、最可能原因、下一轮改变和下一 owner/路由；只有形成有实质变化的新 Dispatch Packet 后，Lead 才可将当前执行记录 `attempts` 重置为 `0` 并重新进入 finalize；
 - 父 HEAD 漂移：旧 candidate 记 `stale`，完整重建并重跑；
 - 成功后可按 candidate integration 授权回收 transient integration worktree/branch；来源 branch/worktree 不自动清理。获得独立 cleanup 授权并清理后，只将生命周期状态改为 `removed`，完整保留已经通过的集成与 E2E 证据；
 - push、PR、remote merge、deploy、migration 和生产动作仍需各自授权。

package/template/workflows/specdev/common/skills/plan-quality-review/SKILL.md

@@ -2,7 +2,7 @@
 name: plan-quality-review
 description: T 发布计划型 Ticket 或 P 发布/重规划 Goal 前检查决策完备、Skill 调用和执行门禁；不执行代码审查或代替用户批准。
 compatibility: Requires the owning Speculo workflow and its workspace path resolver.
-metadata: {"speculo-legacy-name": "specdev-plan-quality-review"}
+metadata: {"speculo-source-id": "specdev-plan-quality-review"}
 ---
 
 # Plan Quality Review

package/template/workflows/specdev/common/skills/research/SKILL.md

@@ -2,7 +2,7 @@
 name: research
 description: 为调用 Work 的具体决定研究外部技术、依赖、标准或未知行为，逐声明返回一手来源、限制与不确定性，由调用方写入其拥有的工件。
 compatibility: Requires the owning Speculo workflow and its workspace path resolver.
-metadata: {"speculo-legacy-name": "specdev-research"}
+metadata: {"speculo-source-id": "specdev-research"}
 ---
 
 # SpecDev Research

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

@@ -4,16 +4,18 @@
 
 ```bash
 node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> \
-  --stage <triage|diagnosis|grill|spec|tickets|goal-plan|implement|learn-change|retro|pr-delivery|review|prototype|wayfinder|complete> \
+  --stage <triage|diagnosis|grill|spec|tickets|goal-plan|implement|learn|retro|pr-delivery|review|prototype|wayfinder|complete|archive-ready|archived> \
   --repo <project-root> \
   <Path>{roots.state}/specdev/changes/{change}</Path>
 ```
 
-`--stage` 只要求该阶段已经拥有的工件；所有已经存在的工件仍会验证。单 change 的 `goal-plan` 要求自己的 Goal Plan，允许合法的 `draft / ready_for_execution: false`；Tickets 阶段可尚无 Goal。Goal 的就绪字段必须是布尔值并与状态对应。
+无安装直接 Work 显式传 `--repo <project-root> --method-root <method-package-root> --state-root <shared-state-root>`；state-root 是 SpecDev 根的上级。已有安装仍核验 workspace，显式根不能覆盖其身份。省略 stage 时只验证当前实际工件。
+
+`--stage` 只要求该阶段已经拥有的工件；所有已经存在的工件仍会验证。无独立 Spec/计划的轻量任务读取 README 稳定 scope/acceptance/verification 章节。显式 `lightweight-goal-plan` 由原 Goal 的 Tasks 负责进度；完整 Goal 使用既有 schema，允许合法的 `draft / ready_for_execution: false`，不自动降级轻量。Tickets 阶段可尚无 Goal。完整 Goal 的就绪字段必须是布尔值并与状态对应。
 
 存在 Implementation Map、Implementation Plan 或 goal-tickets-map 入口中的任一项即走父编排校验；缺少另一父工件会报错，不回退单 change，也不额外要求单 change Goal。父编排读取 sibling 成员，创建时要求每个成员已有 Ready Spec/Tickets，继续校验组合 Ticket DAG、唯一父归属、serialization、跨 Ticket 写路径、全局 workspace/实现配额和完成门。已有父 Map/Plan 尚未补建无状态入口时仍可验证。
 
-省略 stage 时验证当前存在的工件，不会因未来 Work 尚未运行而报错。`--repo` 可选；提供后会把状态中的 SHA、祖先关系、当前分支和完成时 clean 状态与真实 Git 仓库交叉验证。
+解析出项目根后，把 Ticket Evidence 中实际 Workspace Execution Record 的 SHA、祖先关系、当前分支和完成时 clean 状态与真实 Git 仓库交叉验证。没有实际 Git 执行记录时不制造 worktree/领导权骨架；结构通过不等于取得并行排他或写入授权。
 
 校验 workspace 捕获账本（文件必须已存在；缺失时不要为了校验去创建）：
 
@@ -28,7 +30,7 @@ node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> \
 node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> --self-check
 ```
 
-工件结构校验只依赖 Speculo 已要求的 Node.js 运行时，不使用第三方包。真实 Git 检查、review-scope 和包 self-check 中的隔离回归另需 Git；self-check 会在系统临时目录创建并清理测试仓库，不修改用户项目或 workflow 状态。返回码 `0` 表示没有阻塞性结构错误；warning 仍需人工判断。工具不替代项目测试、事实核验、设计审查或用户批准。
+工件结构校验只依赖 Speculo 已要求的 Node.js 运行时；YAML、设计 schema 和冻结历史 schema 所需代码随包分发，无需项目另装校验依赖。真实 Git 检查、Git review-scope 模式和包 self-check 中的隔离回归另需 Git；source-files 模式不依赖 Git。self-check 会在系统临时目录创建并清理测试仓库，不修改用户项目或 workflow 状态。返回码 `0` 表示没有阻塞性结构错误；warning 仍需人工判断。工具不替代项目测试、事实核验、设计审查或用户批准。
 
 ## 从 tickets-map 分析下一轮
 
@@ -42,7 +44,7 @@ node <Path>{roots.workflows}/specdev/common/tools/ticket-control.mjs</Path> --ma
 
 只读工具不调用 Skill、不执行实现、不检查真实授权/正式记忆网关，不获取锁或自动解锁；Lead 必须在 dispatch 前完成这些检查。结构错误返回非零；局部错误仍可能带独立 frontier，调用方必须检查节点和全局 diagnostics。结构检查成功的退出码 0 不代表任务完成，且业务门禁可能仍阻塞全部票。eligible_for_final_verification 只表示可进入最终验收，不是 Goal completed。
 
-`<Path>{roots.workflows}/specdev/common/tools/plan-contract.mjs</Path>` 是两个工具共用的只读校验库：新 Ticket 的真实 Skill 名称/摘要、必需调用证据、Map 数量合同、父入口与 W 候选图。普通 --repo 仍支持原 Git 事实验证；存在未完成票的真实项目 Skill 绑定时必须提供项目根。旧票可读，开始新实现前必须显式补齐 Plan 合同；已完成历史证据不要求当前 Skill 包仍与历史版本相同。
+`<Path>{roots.workflows}/specdev/common/tools/plan-contract.mjs</Path>` 是两个工具共用的只读校验库：新 Ticket 的真实 Skill 名称/摘要、必需调用证据、Map 数量合同、父入口与 W 候选图。普通 --repo 仍支持原 Git 事实验证；存在未完成票的真实项目 Skill 绑定时必须提供项目根。Ticket/Map 必须满足当前 Plan 合同；已完成历史证据不要求当前 Skill 包仍与历史版本相同。
 
 ## 专业分支与审查固定点
 
@@ -52,4 +54,18 @@ node <Path>{roots.workflows}/specdev/common/tools/ticket-control.mjs</Path> --ma
 
 输出包含固定 SHA、实际 diff argv、内容摘要、路径和 changes/no-diff；无差异退出 0，但不是审查 approved。无效引用、歧义 merge-base、缺参数、重复参数或外部工具失败返回非零。差异不执行外部 diff/textconv，受限输出不会泄漏全日志。
 
+`--review-scope --repo <project-root> --mode source-files --file <relative-path>` 可重复 `--file`，仅冻结指定实际文件的原始内容摘要和字面路径；不创建 change、不初始化 workspace、不假造 commit/base。越界、链接、重复路径、未知参数和混入 Git 比较参数均拒绝。source snapshot 仍须由 C 执行规范与质量审查，不能当作自动批准。
+
 包级 self-check 同时执行内置工程合同回归测试；测试用临时目录和真实 Git fixture，既验证合法输入，也从本顶层入口证明非法记录被拒绝。测试不调用远程、不接管状态、不认证真实模型遵从。
+
+## 设计工件与归档
+
+UI 原型阶段用 --stage prototype --prototype-id UI-NNN；逻辑原型可指定 LOGIC-NNN。多个包并存不能以旧 ready 替代本次对象。下游按 change DESIGN 的 prototype_ref 定位当前包，其余历史包保持原字节。
+
+<Path>{roots.workflows}/specdev/common/tools/design-artifacts.mjs</Path> 提供 --project、--change、--handoff、--archived 只读校验，以及 --digest 和 --prototype-digest 摘要计算。规范摘要排除确认回执和工作流时间戳，运行资源必须位于当前包的 final/comparison 内。浏览器证据必须覆盖每个候选和最终入口的 390px/1440px 实际运行；结构测试不会认证截图来源或审美质量。
+
+永久写入只通过 <Path>{roots.workflows}/specdev/common/tools/publish-design.mjs</Path> 及 <Path>{roots.workflows}/specdev/specdev-a-archive-and-consolidate/references/design-knowledge-gateway.md</Path>：先形成具体 dry-run 计划，绑定明确批准与当前摘要，再 apply 并回读；失败按返回检查点恢复。
+
+本地完成使用 `--stage complete`；移动前使用 `--stage archive-ready`，额外核验本次实际请求的外部交付。A 完成现役维护后最后无覆盖移动，再以 `--stage archived` 核验唯一目标与原回执；`moved` 结果明确尚未封存，原 A8 回执完成后用 `--stage archived --sealed` 验证。回执导航与完整移动清单依 <Path>{roots.workflows}/specdev/specdev-a-archive-and-consolidate/references/archive-receipt-contract.md</Path>，不能创建第二份报告。
+
+历史已完成/已归档包不自动重写；旧 v6 归档只读解析原完整 schema、身份和位置，不凭 archived 枚举批准新的 implemented 晋升。旧活动 UI 包应保留为证据，按 v3 新建 UI 编号、生成新 HTML/浏览器证据并重新确认。不能只把旧 schema 数字或 ready 标记改成新版。