@namewta/speculo 1.0.22 → 2.0.1

package/template/workflows/specdev/common/schemas/project-design.schema.json

@@ -0,0 +1,164 @@
+{
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {
+      "const": 1
+    },
+    "artifact": {
+      "const": "project-design"
+    },
+    "revision": {
+      "type": "string",
+      "pattern": "^DESIGN-\\d{4,}$"
+    },
+    "owner": {
+      "const": "specdev/archive-and-consolidate"
+    },
+    "scope": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "tokens": {
+      "type": "object",
+      "minProperties": 1
+    },
+    "rules": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string",
+            "minLength": 1
+          },
+          "statement": {
+            "type": "string",
+            "minLength": 1
+          },
+          "scope": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "string",
+              "minLength": 1
+            }
+          },
+          "verification": {
+            "enum": [
+              "approved-intent",
+              "implemented"
+            ]
+          },
+          "sources": {
+            "type": "array",
+            "minItems": 0,
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "change": {
+                  "type": "string",
+                  "pattern": "^\\d{4}-\\d{2}-\\d{2}-[a-z0-9]+(?:-[a-z0-9]+)*$"
+                },
+                "locator": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "digest": {
+                  "type": "string",
+                  "pattern": "^[a-f0-9]{64}$"
+                }
+              },
+              "required": [
+                "change",
+                "locator",
+                "digest"
+              ]
+            }
+          }
+        },
+        "required": [
+          "id",
+          "statement",
+          "scope",
+          "verification",
+          "sources"
+        ]
+      }
+    },
+    "sources": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string",
+            "minLength": 1
+          },
+          "locator": {
+            "type": "string",
+            "minLength": 1
+          },
+          "url": {
+            "type": "string",
+            "minLength": 1
+          },
+          "revision": {
+            "type": "string",
+            "minLength": 1
+          },
+          "license": {
+            "type": "string",
+            "minLength": 1
+          },
+          "digest": {
+            "type": "string",
+            "pattern": "^[a-f0-9]{64}$"
+          }
+        },
+        "required": [
+          "id",
+          "locator"
+        ]
+      }
+    },
+    "supersedes": {
+      "anyOf": [
+        {
+          "type": "string",
+          "minLength": 1
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "updated_at": {
+      "type": "string",
+      "format": "date-time"
+    }
+  },
+  "required": [
+    "schema_version",
+    "artifact",
+    "revision",
+    "owner",
+    "scope",
+    "tokens",
+    "rules",
+    "sources",
+    "supersedes",
+    "updated_at"
+  ],
+  "$id": "urn:speculo:specdev:project-design:v1",
+  "$schema": "https://json-schema.org/draft/2020-12/schema"
+}

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,8 +1,8 @@
 ---
 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
@@ -11,9 +11,11 @@ metadata: {"speculo-legacy-name": "specdev-code-review"}
 
 ## 输入
 
+默认 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`：固定为三点 diff；
+- `diff_command`：由调用方冻结的实际 argv；legacy 默认三点，显式 range/commit 使用已确认端点，不由 reviewer 换范围；
 - `commit_log`：固定点之后的 commit 列表；
 - `spec_sources`：零个或多个本地权威来源；
 - `standards_sources`：仓库编码标准来源；
@@ -22,7 +24,7 @@ metadata: {"speculo-legacy-name": "specdev-code-review"}
 
 ## 流程
 
-1. 重验 fixed point/head 可解析、三点 diff 非空，失败时不启动 reviewer。
+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 +34,8 @@ metadata: {"speculo-legacy-name": "specdev-code-review"}
 
 ## 输出
 
+source-files 结果以 `review_mode` 和 `source_snapshot` 代替下例 Git 字段，其余两轴、来源和限制结构相同。
+
 ```text
 {
   fixed_point, head, diff_command, commit_log,
@@ -46,8 +50,10 @@ Finding 必须包含 severity、项目相对 Path/代码块、具体风险、依
 
 ## 完成标准
 
-- fixed point、head、diff 和 commits 固定且可重复；
+- diff 的 fixed point、head、diff、commits 或 source-files 的原字节快照固定且可重复；
 - 仓库标准优先于 Fowler 启发式；
 - 两个 reviewer 上下文没有相互发现污染；
 - 每个发现可定位且说明行为风险；
 - 两轴按固定顺序返回，缺失规范没有掩盖标准审查。
+
+对适用风险先给出可证伪反例，再追踪消费者、实现、测试及恢复；测试覆盖率、配对哈希或 schema 成功不代替语义审查。错误和可靠性分别引用 <Path>{roots.workflows}/specdev/common/rules/error-handling.md</Path> 与 <Path>{roots.workflows}/specdev/common/rules/test-reliability.md</Path>。

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

@@ -4,7 +4,7 @@
 
 | 必须相同并可回读 | 核对证据 |
 |---|---|
-| fixed_point、head、三点 diff 与 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/references/create.md

@@ -16,7 +16,7 @@
 4. 从 `base_sha` 创建 Git worktree，不复用其他 Ticket 目录；
 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 镜像。
 
 初始记录：
 

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

@@ -19,7 +19,7 @@
 1. 使用 branch `speculo/integration/<change>/<ticket-id>` 和 locator `specdev-worktree/.integration/<ticket-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`。
 

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|review|prototype|wayfinder|complete> \
+  --stage <triage|diagnosis|grill|spec|tickets|goal-plan|implement|learn-change|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 运行时，不使用第三方包。返回码 `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,4 +44,28 @@ 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 包仍与历史版本相同。
+
+## 专业分支与审查固定点
+
+原 change 校验支持 `--engineering performance|documentation|incident`，要求对应原 owner 工件中的标记证据；不传时仍检查已经存在的标记。字段见 <Path>{roots.workflows}/specdev/common/rules/engineering-evidence.md</Path>。历史无标记工件不强制回填，所有路径只读。
+
+`--review-scope --repo <project-root> --mode baseline|range|commit|pr` 是独立只读模式，不选择 change、不加载状态、不访问网络。baseline/pr 使用唯一 merge-base；range 比较两个端点；commit 只比较指定提交与其父，不用当前 HEAD。前三种端点模式传 `--base` 与 `--head`；commit 传 `--commit`，多父提交还须 `--parent`。PR 必须传刚读取的完整 base/head SHA。根提交没有现有 CR 所需的 committed fixed point，明确拒绝，不编造父提交。
+
+输出包含固定 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 标记改成新版。