@namewta/speculo 1.0.24 → 2.0.1

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,6 +11,8 @@ 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`：由调用方冻结的实际 argv；legacy 默认三点，显式 range/commit 使用已确认端点，不由 reviewer 换范围；
@@ -22,7 +24,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 +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,7 +50,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/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|retro|pr-delivery|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 运行时，不使用第三方包。真实 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 标记改成新版。

package/template/workflows/specdev/common/tools/change-artifacts.mjs

@@ -0,0 +1,170 @@
+/** Read-only completion preflight. Artifact text never authenticates user authority. */
+import { existsSync, readdirSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { basename, join } from 'node:path';
+import {
+  readChangeFactsSync, readArtifactSectionSync, readUtf8ArtifactSync,
+  safeWorkPathSync, markdownBodyLines, parseFrontmatter,
+} from '../../../../lib/speculo-runtime.mjs';
+
+const meaningful = value => typeof value === 'string' && value.trim() && !/^(?:unknown|unassigned|pending|tbd|todo|\.\.\.|<.*>)$/i.test(value.trim());
+function error(code, path, message) { throw new Error(`${code}: ${path}: ${message}`); }
+function section(path, heading) {
+  const text = readUtf8ArtifactSync(path), lines = markdownBodyLines(text, path);
+  const matches = lines.filter(line => line.text === `## ${heading}`);
+  if (matches.length !== 1) error('closure-evidence-missing', path, `expected one ${heading} section`);
+  const start = matches[0].line, end = lines.find(line => line.line > start && /^#{1,2} /.test(line.text))?.line;
+  return text.split(/\r?\n/).slice(start, end ? end - 1 : undefined).join('\n');
+}
+function fields(text, path) {
+  const result = {};
+  for (const {text: line} of markdownBodyLines(text, path)) {
+    const m = /^([A-Za-z][A-Za-z-]*): (.+)$/.exec(line);
+    if (!m) continue;
+    if (m[1] in result) error('closure-evidence-missing', path, `duplicate ${m[1]}`);
+    result[m[1]] = m[2].trim();
+  }
+  return result;
+}
+function evidence(root, locator) {
+  if (!meaningful(locator)) error('closure-evidence-missing', root, 'missing evidence locator');
+  const pieces = locator.split('#');
+  if (pieces.length > 2) error('closure-evidence-missing', root, 'ambiguous evidence locator');
+  const path = safeWorkPathSync(root, pieces[0] || 'README.md', { mustExist: true, type: 'file' });
+  const text = pieces.length === 2 ? readArtifactSectionSync(path, pieces[1]).text : readUtf8ArtifactSync(path);
+  if (!meaningful(text)) error('closure-evidence-missing', path, 'empty evidence');
+  return { path, text };
+}
+export function readChangeOwner(context, change) {
+  const facts = readChangeFactsSync(context, change), root = facts.location.root;
+  for (const name of ['implementation-plan.md', 'goal-plan.md']) {
+    const path = safeWorkPathSync(root, name, { type: 'file' });
+    if (!existsSync(path)) continue;
+    const {fields: meta} = parseFrontmatter(readUtf8ArtifactSync(path));
+    if (meta.change !== facts.location.name || !meaningful(meta.lead)) error('owner-unresolved', path, 'plan must identify this change and its actual Lead');
+    return { owner: meta.lead, path, evidencePath: path, kind: name === 'implementation-plan.md' ? 'parent-lead' : 'goal-lead' };
+  }
+  const data = fields(section(facts.readmePath, 'Ownership'), facts.readmePath);
+  if (!meaningful(data.Owner)) error('owner-unresolved', facts.readmePath, 'no actual owner/session locator');
+  const source = evidence(root, data.Evidence);
+  if (source.path === facts.readmePath && !data.Evidence.includes('#')) error('owner-unresolved', source.path, 'Ownership must point to a separate session/handoff section');
+  const sourceFields = fields(source.text, source.path);
+  if (![sourceFields.Owner, sourceFields.Session].includes(data.Owner)) error('owner-unresolved', source.path, 'owner differs from original session/handoff evidence');
+  if (data.Work && sourceFields.Work !== data.Work) error('owner-unresolved', source.path, 'Work differs from original ownership evidence');
+  return { owner: data.Owner, path: facts.readmePath, evidencePath: source.path, work: data.Work, kind: 'direct-owner' };
+}
+export function readLightweightSpec(changeRoot) {
+  const readme = safeWorkPathSync(changeRoot, 'README.md', { mustExist: true, type: 'file' });
+  const hasSpec = existsSync(join(changeRoot, 'spec.md'));
+  const visible = markdownBodyLines(readUtf8ArtifactSync(readme), readme);
+  const readmeOwns = visible.some(line => line.text === '<a id="scope"></a>');
+  if (hasSpec && readmeOwns) error('identity-conflict', readme, 'README and spec.md both claim specification ownership; replace the migrated README scope with navigation');
+  if (hasSpec) return { path: join(changeRoot, 'spec.md'), kind: 'independent' };
+  const scope = readArtifactSectionSync(readme, 'scope');
+  const acceptance = readArtifactSectionSync(readme, 'acceptance');
+  const verification = readArtifactSectionSync(readme, 'verification');
+  const ids = [...new Set(acceptance.text.match(/\bAC-\d+\b/g) ?? [])];
+  if (!ids.length) error('closure-evidence-missing', readme, 'lightweight acceptance must identify observable AC-n contracts');
+  return { path: readme, kind: 'lightweight', scope, acceptance, verification, ids };
+}
+function validateLightweightCompletion(root, errors) {
+  const spec = readLightweightSpec(root);
+  if (spec.kind !== 'lightweight') return;
+  const rows = spec.verification.text.split(/\r?\n/).filter(line => /^\|\s*AC-\d+\s*\|/.test(line)).map(line => line.split('|').slice(1,-1).map(cell => cell.trim()));
+  for (const id of spec.ids) {
+    const matches = rows.filter(row => row[0] === id);
+    if (matches.length !== 1) { errors.push(`closure-evidence-missing: ${spec.path}: ${id} needs one verification row (AC | Result | Evidence [| SHA256])`); continue; }
+    const row = matches[0];
+    if (![3,4].includes(row.length) || row[1] !== 'passed' || (row[3] && !/^[a-f0-9]{64}$/.test(row[3]))) { errors.push(`closure-evidence-missing: ${spec.path}: ${id} needs a passed result and valid optional evidence digest`); continue; }
+    try {
+      const record = evidence(root, row[2]);
+      if (record.path === spec.path && (!row[2].includes('#') || row[2].split('#')[1] === 'verification')) error('closure-evidence-missing', record.path, 'verification must cite a separate actual evidence section');
+      const actual = createHash('sha256').update(readUtf8ArtifactSync(record.path)).digest('hex');
+      if (row[3] && row[3] !== actual) error('source-drift', record.path, `${id} evidence digest changed`);
+      const data = fields(record.text, record.path);
+      if (data.Result !== 'passed' || !meaningful(data.Method) || !meaningful(data.Observed) || !meaningful(data.Source)) error('closure-evidence-missing', record.path, 'verification record needs Method, Source, Observed and Result: passed');
+      if (data.Command && data.Exit !== '0') error('closure-evidence-missing', record.path, 'command verification requires Exit: 0');
+    } catch (e) { errors.push(String(e)); }
+  }
+  for (const row of rows) if (!spec.ids.includes(row[0])) errors.push(`closure-evidence-missing: ${spec.path}: verification references undeclared ${row[0]}`);
+  if (/^\s*[-*] \[ \]/m.test(spec.acceptance.text)) errors.push(`closure-evidence-missing: ${spec.path}: acceptance remains unchecked`);
+}
+function validateCancellation(facts, owner, errors) {
+  const root = facts.location.root, content = readArtifactSectionSync(facts.readmePath, 'cancellation');
+  const data = fields(content.text, facts.readmePath);
+  for (const key of ['Source','Scope','Time','Confirmed-By','Undelivered','Landed','Writers','Dependencies','Checkpoints','External','Next']) if (!meaningful(data[key])) errors.push(`closure-evidence-missing: ${facts.readmePath}: cancellation needs ${key}`);
+  if (data['Confirmed-By'] !== owner?.owner) errors.push(`owner-unresolved: ${facts.readmePath}: cancellation was not confirmed by original completion owner`);
+  if (!/^\d{4}-\d\d-\d\dT/.test(data.Time ?? '') || !Number.isFinite(Date.parse(data.Time))) errors.push(`closure-evidence-missing: ${facts.readmePath}: cancellation needs actual decision time`);
+  const source = evidence(root, data.Source);
+  if (source.path === facts.readmePath && (!data.Source.includes('#') || data.Source.split('#')[1] === 'cancellation')) error('closure-evidence-missing', source.path, 'cancellation must point to a separate actual request section');
+  if (!/^none: \S/.test(data.Writers ?? '')) {
+    if (!/^stopped: \S/.test(data.Writers ?? '')) errors.push(`writer-active: ${facts.readmePath}: need none with rationale or stopped with termination/handoff evidence; timeout is not termination`);
+    else {
+      const stopped = evidence(root, data.Writers.slice(9)), stoppedFields = fields(stopped.text, stopped.path);
+      if (stoppedFields.Writers !== 'stopped' || !meaningful(stoppedFields.Observed)) errors.push(`writer-active: ${stopped.path}: missing observed termination/handoff`);
+    }
+  }
+  for (const key of ['Dependencies','Checkpoints','External']) if (!/^(?:none|resolved|transferred|waived): \S/.test(data[key] ?? '')) errors.push(`closure-evidence-missing: ${facts.readmePath}: unresolved ${key}`);
+  const tickets = safeWorkPathSync(root, 'evidence', { type: 'directory' });
+  if (existsSync(tickets)) for (const file of readdirSync(tickets).filter(n => /^T-\d+\.md$/.test(n))) {
+    const path = safeWorkPathSync(tickets, file, { type: 'file', mustExist: true }), text = readUtf8ArtifactSync(path);
+    const blocks = [...text.matchAll(/^## Workspace Execution Record\r?\n([\s\S]*?)(?=^## |$(?![\s\S]))/gm)];
+    for (const block of blocks) {
+      const json = /```json\s*\n([\s\S]*?)\n```/.exec(block[1]);
+      if (!json) error('closure-evidence-missing', path, 'invalid workspace execution record');
+      const record = JSON.parse(json[1]);
+      if (['active','review','integrating','blocked'].includes(record.status)) errors.push(`writer-active: ${path}: cancellation does not end an execution owner or candidate`);
+    }
+  }
+}
+export function validateArchiveDelivery(changeRoot) {
+  const errors = [];
+  for (const name of ['triage.md','publish.md']) {
+    const path = safeWorkPathSync(changeRoot, name, { type: 'file' }); if (!existsSync(path)) continue;
+    try {
+      const {fields: meta} = parseFrontmatter(readUtf8ArtifactSync(path));
+      if (meta.change !== basename(changeRoot)) errors.push(`${path}: change identity mismatch`);
+      if (name === 'triage.md' && !['closed','waived','not-applicable'].includes(meta.external_action)) errors.push(`${path}: external delivery is not closed`);
+      if (meta.publish_action !== undefined && !['not-requested','published','waived'].includes(meta.publish_action)) errors.push(`${path}: publish delivery is not closed`);
+    } catch (e) { errors.push(String(e)); }
+  }
+  const prs = safeWorkPathSync(changeRoot, 'pull-requests', { type: 'directory' });
+  if (existsSync(prs)) for (const name of readdirSync(prs)) {
+    try {
+      const path = safeWorkPathSync(prs, name, { type: 'file', mustExist: true });
+      const {fields: meta} = parseFrontmatter(readUtf8ArtifactSync(path));
+      if (meta.change !== basename(changeRoot)) errors.push(`${path}: change identity mismatch`);
+      if (meta.requested === true && !(meta.status === 'waived' || meta.status === 'ready' || (meta.delivery_target === 'draft' && meta.status === 'draft'))) errors.push(`${path}: requested PR delivery is unresolved`);
+    } catch (e) { errors.push(String(e)); }
+  }
+  return errors;
+}
+/** complex-preflight is deliberately not a completion certificate; the full validator must follow. */
+export function validateChangeClosure({context, change, forArchive = false}) {
+  const errors = []; let facts, owner, scope;
+  try {
+    facts = readChangeFactsSync(context, change);
+    owner = readChangeOwner(context, change);
+    if (facts.outcome === 'active') errors.push(`closure-evidence-missing: ${facts.readmePath}: change is still active`);
+    const root = facts.location.root;
+    if (facts.outcome === 'cancelled') { scope = 'cancellation'; validateCancellation(facts, owner, errors); }
+    else {
+      const goalPath = safeWorkPathSync(root, 'goal-plan.md', {type:'file'});
+      const lightweightGoal = existsSync(goalPath) && parseFrontmatter(readUtf8ArtifactSync(goalPath)).fields.artifact === 'lightweight-goal-plan';
+      const independent = ['spec.md','ticket','tickets-map.md','implementation-plan.md','implementation-map.md','retro',...(!lightweightGoal ? ['goal-plan.md'] : [])].some(name => existsSync(join(root, name)));
+      const complex = independent || ['DESIGN.md','prototypes'].some(name => existsSync(join(root,name)));
+      scope = complex ? 'complex-preflight' : 'lightweight';
+      if (!independent && facts.outcome === 'completed') {
+        validateLightweightCompletion(root, errors);
+        if (lightweightGoal) {
+          const tasks = section(goalPath, 'Tasks');
+          if (!/^\s*[-*] \[x\]/m.test(tasks) || /^\s*[-*] \[ \]/m.test(tasks)) errors.push(`closure-evidence-missing: ${goalPath}: Goal tasks must be actually delivered`);
+          for (const heading of ['Integration and Verification','Next Steps']) if (!meaningful(section(goalPath,heading))) errors.push(`closure-evidence-missing: ${goalPath}: ${heading} is empty`);
+          if (/^\s*[-*] \[[ x]\]/m.test(readUtf8ArtifactSync(facts.readmePath))) errors.push(`identity-conflict: ${facts.readmePath}: Goal owns task progress; README must not mirror it`);
+        }
+      }
+    }
+    if (forArchive) errors.push(...validateArchiveDelivery(root));
+  } catch (e) { errors.push(String(e)); }
+  return { valid: errors.length === 0, complete: errors.length === 0 && scope !== 'complex-preflight', scope, errors, facts, owner };
+}