create-yss-spec 3.5.2 → 3.5.3

package/template/.template-spec/process/schemas/digital-human-task-package.schema.json

@@ -31,13 +31,28 @@
       "type": "object",
       "additionalProperties": false,
       "properties": {
-        "strategic_handoff_consumption": { "type": "object" },
-        "approved_spec": { "type": "object" },
-        "context_reconciliation": { "type": "object" },
-        "technical_design": { "type": "object" },
-        "data_architecture_decision": { "type": "object" },
-        "api_contract_decision": { "type": "object" },
-        "engineering_contract_approval_ref": { "type": "string", "minLength": 1 }
+        "strategic_handoff_consumption": {
+          "type": "object"
+        },
+        "approved_spec": {
+          "type": "object"
+        },
+        "context_reconciliation": {
+          "type": "object"
+        },
+        "technical_design": {
+          "type": "object"
+        },
+        "data_architecture_decision": {
+          "type": "object"
+        },
+        "api_contract_decision": {
+          "type": "object"
+        },
+        "engineering_contract_approval_ref": {
+          "type": "string",
+          "minLength": 1
+        }
       }
     },
     "plan_review_ref": {
@@ -57,7 +72,10 @@
       "minLength": 1
     },
     "schema_version": {
-      "const": 1
+      "enum": [
+        1,
+        2
+      ]
     },
     "frontend_delivery": {
       "type": "object",
@@ -181,7 +199,8 @@
           "enum": [
             "lifecycle-work-unit",
             "slice-implementation",
-            "template-maintenance"
+            "template-maintenance",
+            "read-only-intake"
           ]
         },
         "contract_id": {
@@ -343,7 +362,7 @@
     },
     "allowed_write_paths": {
       "type": "array",
-      "minItems": 1,
+      "minItems": 0,
       "uniqueItems": true,
       "items": {
         "type": "string",
@@ -369,7 +388,7 @@
     },
     "expected_evidence_files": {
       "type": "array",
-      "minItems": 1,
+      "minItems": 0,
       "uniqueItems": true,
       "items": {
         "type": "string",
@@ -378,7 +397,7 @@
     },
     "verification_commands": {
       "type": "array",
-      "minItems": 1,
+      "minItems": 0,
       "items": {
         "type": "string",
         "minLength": 1
@@ -423,6 +442,10 @@
           "stderr_ref": {
             "type": "string",
             "minLength": 1
+          },
+          "evidence_digest": {
+            "type": "string",
+            "pattern": "^sha256:[a-f0-9]{64}$"
           }
         }
       }
@@ -599,6 +622,42 @@
         "checkpoint_ref": {
           "type": "string",
           "minLength": 1
+        },
+        "research_verification": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "ref",
+            "digest"
+          ],
+          "properties": {
+            "ref": {
+              "type": "string",
+              "minLength": 1
+            },
+            "digest": {
+              "type": "string",
+              "pattern": "^sha256:[0-9a-f]{64}$"
+            }
+          }
+        },
+        "maintenance_authorization": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "ref",
+            "digest"
+          ],
+          "properties": {
+            "ref": {
+              "type": "string",
+              "minLength": 1
+            },
+            "digest": {
+              "type": "string",
+              "pattern": "^sha256:[0-9a-f]{64}$"
+            }
+          }
         }
       }
     },
@@ -677,6 +736,16 @@
     "checkpoint_ref": {
       "type": "string",
       "minLength": 1
+    },
+    "verification_status": {
+      "enum": [
+        "not-executed",
+        "executed"
+      ]
+    },
+    "observation_ref": {
+      "type": "string",
+      "pattern": "^run:"
     }
   },
   "allOf": [
@@ -765,6 +834,127 @@
           "review_context"
         ]
       }
+    },
+    {
+      "if": {
+        "properties": {
+          "schema_version": {
+            "const": 1
+          }
+        }
+      },
+      "then": {
+        "properties": {
+          "contract": {
+            "properties": {
+              "kind": {
+                "enum": [
+                  "lifecycle-work-unit",
+                  "slice-implementation",
+                  "template-maintenance"
+                ]
+              }
+            }
+          },
+          "allowed_write_paths": {
+            "minItems": 1
+          },
+          "expected_evidence_files": {
+            "minItems": 1
+          },
+          "verification_commands": {
+            "minItems": 1
+          }
+        }
+      },
+      "else": {
+        "required": [
+          "verification_status"
+        ],
+        "properties": {
+          "execution_state": {
+            "const": "Explorer"
+          },
+          "work_unit_id": {
+            "enum": [
+              "work-unit.entry-triage",
+              "work-unit.harness-entry"
+            ]
+          },
+          "allowed_write_paths": {
+            "maxItems": 0
+          },
+          "contract": {
+            "properties": {
+              "kind": {
+                "const": "read-only-intake"
+              }
+            },
+            "not": {
+              "anyOf": [
+                {
+                  "required": [
+                    "maintenance_ref"
+                  ]
+                },
+                {
+                  "required": [
+                    "slice_contract_ref"
+                  ]
+                },
+                {
+                  "required": [
+                    "lifecycle_ref"
+                  ]
+                }
+              ]
+            }
+          },
+          "result": {
+            "properties": {
+              "changed_files": {
+                "maxItems": 0
+              },
+              "changed_artifacts": {
+                "maxItems": 0
+              },
+              "next_route": {
+                "type": "null"
+              }
+            }
+          },
+          "stage_id": {
+            "enum": [
+              "stage.entry-triage",
+              "stage.harness-entry"
+            ]
+          }
+        },
+        "not": {
+          "anyOf": [
+            {
+              "required": [
+                "checkpoint_ref"
+              ]
+            },
+            {
+              "required": [
+                "review_context"
+              ]
+            },
+            {
+              "required": [
+                "review_input"
+              ]
+            },
+            {
+              "required": [
+                "user_decisions"
+              ]
+            }
+          ]
+        }
+      }
     }
   ]
 }

package/template/.template-spec/process/schemas/frontend-implementation-evidence.schema.json

@@ -6,6 +6,8 @@
   "additionalProperties": false,
   "required": ["schema_version", "kind", "template", "status", "prototype_ref", "spec_ref", "visual_baseline", "route_and_page_inventory", "pnpm_commands"],
   "properties": {
+    "console_evidence": {"$ref": "#/$defs/binding"},
+    "implementation_plan": {"$ref": "#/$defs/binding"},
     "frontend_delivery": {"type":"object","additionalProperties":false,"required":["acceptance_ref","digest"],"properties":{"acceptance_ref":{"type":"string","minLength":1},"digest":{"type":"string","pattern":"^sha256:[0-9a-f]{64}$"}}},
     "slice_id": {"type":"string","minLength":1},
     "slice_contract_ref": {"type":"string","minLength":1},
@@ -23,7 +25,7 @@
     "state_cases": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}},
     "pnpm_commands": {"type": "array", "minItems": 1, "items": {"type": "string", "pattern": "^pnpm(?: |$)"}},
     "case_results": {"type": "array", "minItems": 1, "items": {"$ref": "#/$defs/caseResult"}},
-    "interaction_results": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}},
+    "interaction_results": {"type": "array", "minItems": 1, "items": {"oneOf": [{"type": "string", "minLength": 1}, {"$ref": "#/$defs/interaction"}]}},
     "console_warning_check": {"enum": ["pass", "blocked"]},
     "actual_verification": {"type": "array", "minItems": 1, "items": {"$ref": "#/$defs/verification"}},
     "uncovered_differences": {"type": "array", "items": {"type": "string", "minLength": 1}},
@@ -35,6 +37,8 @@
     {"if": {"properties": {"kind": {"const": "verification"}}, "required": ["kind"]}, "then": {"required": ["case_results", "interaction_results", "console_warning_check", "actual_verification", "uncovered_differences", "difference_owner", "independent_review"]}}
   ],
   "$defs": {
+    "interaction": {"type": "object", "additionalProperties": false, "required": ["case_id", "state", "result", "evidence_ref", "evidence_digest"], "properties": {"case_id": {"$ref": "#/$defs/caseId"}, "state": {"type": "string", "minLength": 1}, "result": {"enum": ["pass", "failed", "blocked"]}, "evidence_ref": {"type": "string", "minLength": 1}, "evidence_digest": {"$ref": "#/$defs/digest"}}},
+    "binding": {"type": "object", "additionalProperties": false, "required": ["ref", "digest"], "properties": {"ref": {"type": "string", "minLength": 1}, "digest": {"$ref": "#/$defs/digest"}}},
     "digest": {"type": "string", "pattern": "^sha256:[a-f0-9]{64}$"},
     "caseId": {"type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$"},
     "visualBaseline": {
@@ -52,20 +56,8 @@
       "required": ["route", "page", "case_ids"],
       "properties": {"route": {"type": "string", "minLength": 1}, "page": {"type": "string", "minLength": 1}, "case_ids": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"$ref": "#/$defs/caseId"}}}
     },
-    "caseResult": {
-      "type": "object", "additionalProperties": false,
-      "required": ["case_id", "baseline_image_ref", "implementation_image_ref", "diff_ref", "mask_ref", "result", "uncovered_difference", "explanation"],
-      "properties": {
-        "case_id": {"$ref": "#/$defs/caseId"}, "baseline_image_ref": {"type": "string", "minLength": 1}, "implementation_image_ref": {"type": "string", "minLength": 1},
-        "diff_ref": {"type": "string", "minLength": 1}, "mask_ref": {"type": "string", "minLength": 1}, "result": {"enum": ["pass", "blocked"]},
-        "uncovered_difference": {"type": "boolean"}, "explanation": {"type": "string"}
-      }
-    },
-    "verification": {
-      "type": "object", "additionalProperties": false,
-      "required": ["command", "exit_code", "executed_at", "evidence_ref"],
-      "properties": {"command": {"type": "string", "minLength": 1}, "exit_code": {"type": "integer"}, "executed_at": {"type": "string", "minLength": 1}, "evidence_ref": {"type": "string", "minLength": 1}}
-    },
+    "caseResult": {"type": "object", "additionalProperties": false, "required": ["case_id", "baseline_image_ref", "implementation_image_ref", "diff_ref", "mask_ref", "result", "uncovered_difference", "explanation"], "properties": {"case_id": {"$ref": "#/$defs/caseId"}, "baseline_image_ref": {"type": "string", "minLength": 1}, "implementation_image_ref": {"type": "string", "minLength": 1}, "diff_ref": {"type": "string", "minLength": 1}, "mask_ref": {"type": "string", "minLength": 1}, "result": {"enum": ["pass", "blocked"]}, "uncovered_difference": {"type": "boolean"}, "explanation": {"type": "string"}, "implementation_image_digest": {"$ref": "#/$defs/digest"}, "diff_digest": {"$ref": "#/$defs/digest"}}},
+    "verification": {"type": "object", "additionalProperties": false, "required": ["command", "exit_code", "executed_at", "evidence_ref"], "properties": {"command": {"type": "string", "minLength": 1}, "exit_code": {"type": "integer"}, "executed_at": {"type": "string", "minLength": 1}, "evidence_ref": {"type": "string", "minLength": 1}, "evidence_digest": {"$ref": "#/$defs/digest"}}},
     "review": {
       "type": "object", "additionalProperties": false,
       "required": ["reviewer", "candidate_digest", "status", "findings_ref"],

package/template/.template-spec/process/subagent-collaboration.md

@@ -11,3 +11,11 @@ Subagent 和其它运行时实例只接收边界清晰的任务包。主控数
 ## 汇合
 
 返回结果必须符合 `workflow-execution-result-v1`，至少包括 `work_unit`、`workflow_reference`、`result`、`skill`、`changed_files` / `changed_artifacts`、`evidence_refs`、实际验证结果、`deferred_seams`、`drift`、`violation`、`new_impacts`、`stale_candidates`、`blocking_signals` 和 `next_route`。主控必须重新执行 fresh verification，并在集中 checkpoint 中保留阶段因果。会签写入 `docs/.scratch/<feature>/gates/<gate-id>-approval.yaml`（形状见 `.template-spec/templates/approval-record-template.yaml`），不能用聊天表情代替。恢复前校验 `scripts/verify-approval-record`。
+
+## 只读分诊任务包 v2
+
+schema v1 及三种正式合同继续执行原规则。v2 仅用于 `read-only-intake`：`Explorer`、注册表已有 `work-unit.entry-triage` 或专职 Profile 的 `work-unit.harness-entry`、`allowed_write_paths: []`，不带 checkpoint、Slice 或正式审查合同。研究完成只回传来源和结论，不更新阶段、Ticket、批准或 `next_route`；写正式资产前由主控重新分析影响并生成正式任务包。旧消费者必须拒绝 v2 并升级，禁止改写为 v1 绕过边界。
+
+`prepare-read-only-intake --input <选择.yaml> --output <仓库外/task.json>` 从角色默认值生成任务包；输入沿用任务 ID、角色、运行时、分诊入口、合同 ID/版本/来源、输入、目标、禁止事项、预期输出、下游消费者和汇合字段。`run-read-only-intake --task <task.json> --run-dir <仓库外新目录> [--timeout-ms <毫秒>] -- <命令> <参数>` 保存观测与日志；不传命令时明确未执行验证。复核使用 `verify-digital-human-task-package <run-dir/task-result.json> --run-dir <绝对目录>`。
+
+运行证据使用 `run:` 相对引用，禁止绝对路径、`..` 与符号链接逃逸。命令、退出码、时间、stdout/stderr 与摘要必须一致；源码引用不能冒充运行日志。派发器观察 Git 跟踪、未跟踪及忽略文件的新增、删除、修改及已初始化子仓，结果中的空变更声明不能覆盖实际差异。未初始化子仓阻断观测。此工具是合同与结果审计，不是 OS 沙箱：执行期间改后恢复及可信派发器证据被恶意同步伪造不在终态观测能力内；运行目录应由派发器持有，不扩大 Agent 仓库写权限，运行时仍须采用只读权限。恢复后重新观察，不能直接复用旧完成状态。

package/template/.template-spec/process/templates/frontend-implementation-verification-template.yaml

@@ -19,12 +19,25 @@ case_results:
   - case_id: primary-desktop
     baseline_image_ref: docs/.scratch/example/handoff/visual-baseline-v1/images/primary-desktop.png
     implementation_image_ref: docs/.scratch/example/verification/images/primary-desktop.png
+    implementation_image_digest: sha256:0000000000000000000000000000000000000000000000000000000000000000
+    diff_digest: sha256:0000000000000000000000000000000000000000000000000000000000000000
     diff_ref: docs/.scratch/example/verification/diffs/primary-desktop.png
     mask_ref: not-applicable
     result: blocked
     uncovered_difference: false
     explanation: <difference-or-not-applicable>
-interaction_results: [loading, empty, error, permission, selected, key-interaction]
+implementation_plan:
+  ref: docs/.scratch/example/verification/frontend-plan.yaml
+  digest: sha256:0000000000000000000000000000000000000000000000000000000000000000
+interaction_results:
+  - case_id: primary-desktop
+    state: key-interaction
+    result: blocked
+    evidence_ref: docs/.scratch/example/verification/interaction.json
+    evidence_digest: sha256:0000000000000000000000000000000000000000000000000000000000000000
+console_evidence:
+  ref: docs/.scratch/example/verification/console.json
+  digest: sha256:0000000000000000000000000000000000000000000000000000000000000000
 console_warning_check: blocked
 pnpm_commands: [pnpm lint, pnpm type-check, pnpm test]
 actual_verification:
@@ -32,6 +45,7 @@ actual_verification:
     exit_code: 0
     executed_at: <iso-8601>
     evidence_ref: docs/.scratch/example/verification/pnpm-test.txt
+    evidence_digest: sha256:0000000000000000000000000000000000000000000000000000000000000000
 uncovered_differences: []
 difference_owner: null
 independent_review:

package/template/AGENTS.md

@@ -36,7 +36,7 @@
 
 - 先按 `.template-spec/process/harness-process-tailoring.md` 判定影响面和最近可信阶段，再由 `yss-product-lifecycle` 执行 `.template-spec/process/lifecycle-registry.yaml`；阅读导航见 `.template-spec/process/lifecycle-artifact-map.md`。
 - 命中门禁必须完成；仅未命中时记录带原因的 `not-applicable`，不得生成空文档或混淆门禁、产物、工作单元、证据。安全 / 权限写入普通 Spec、契约、架构、验收和 seam，按实际影响触发门禁。
-- 新功能和较大变更先进入 Plan；`grill-with-docs`、`to-spec`、`to-tickets`、`implement` 仅为用户显式兼容入口。API 变更先形成 OpenAPI 3.1 Draft，审查后 Freeze，再实现。
+- 新功能和较大变更先进入 Plan；`to-spec`、`to-tickets`、`implement` 仅为用户显式兼容入口。API 变更先形成 OpenAPI 3.1 Draft，审查后 Freeze，再实现。
 - Spec Delta 只记冻结基线的高风险行为差异。OpenAPI Freeze 或无 API 影响记录后拆窄垂直切片，禁止仅按技术层横拆。
 - `seam-deferred` 必须记录风险、责任人、后续 Ticket、验证计划和目标版本或发布日期。
 

package/template/CONTEXT.md

@@ -9,6 +9,10 @@ context_schema_version: 1
 
 只有在计划、分诊、调试或架构讨论中明确沉淀出稳定语言时，才新增术语。
 
+## 消费规则
+
+探索仓库、起草 Spec / Ticket、架构设计和实现前读取根目录唯一的 CONTEXT.md，并按当前影响面读取 docs/adr/。合同缺失时先恢复，不能临时另建词汇表。Spec、Ticket 标题、测试、架构说明和总结使用已确认的中文术语；与冻结术语或 ADR 冲突时先明确冲突。稳定术语由 domain-modeling 维护，临时猜测留在决策前沿。生命周期引用保存结构化 snapshot 与双摘要，不使用 Markdown 伪锚点。
+
 ## 流程术语
 
 模板源与生命周期协作概念放在本节。`英文标识` 填 `—`，不回溯补译。
@@ -62,7 +66,7 @@ context_schema_version: 1
 | Fresh Verification | 完成前重新执行的验证证据，包括测试命令、契约校验、关键路径检查或人工审查结论。 | — | 不等同于“之前跑过”或实现者自述。 |
 | `implementation-ready` | 模板维护实现和命中影响面的快速核验已经完成，但尚未冻结正式审查候选。 | — | 是模板维护默认出口；不等同于 `ready-for-agent`、已审查或可发布。 |
 | `review-ready` | 模板维护显式选择独立审查时的就绪状态；旧候选协议要求 candidate 核验、首次完整验证和摘要冻结。 | — | Reviewer 必须消费同一候选摘要；候选字节变化后旧审查失效。 |
-| `release-ready` | 模板维护已完成维护者自检和发布前完整 Fresh Verification；显式选择独立审查时还须闭合该审查。 | — | 仍不替代 `gate.release-ready` 所需的生物人发布裁决。 |
+| `release-ready` | 模板维护已完成维护者自检和发布前完整 Fresh Verification；显式选择独立审查时还须闭合该审查。 | — | 交付验收使用 `gate.delivery-accepted`；实际合并、发布仍须单独取得生物人授权。 |
 | 实现验证命令 | 前端测试 / 构建优先 `pnpm`，后端校验 / 测试 / 编译优先 `./mvnw`。 | — | 不要默认 `npm`、`yarn` 或裸 `mvn`；仓库确实缺少 pnpm 或 Maven Wrapper 时记受控例外。 |
 | 脚手架架构选择 | 新建后端工程在工程基线中对 `domain-driven` 与 `layered-mvc` 的结构化选择；Agent 提供证据化推荐，用户确认后由生命周期批准并供脚手架合同消费。 | — | 不是新门禁，也不是生成器内的交互参数；缺失、未确认或摘要漂移时阻断生成。 |
 | 测试质量基线 | 项目实例明确采纳的覆盖率阈值、关键流程清单和受控例外。 | — | 模板推荐值本身不构成可执行门禁；未定义关键流程时，不得声称其 E2E 覆盖率达到 100%。 |

package/template/README.md

@@ -9,27 +9,15 @@
 ## 项目结构
 
 ```text
-├── .agents/                 ← 跨 Agent 共享 skills 的权威内容
-├── .codex/                  ← Codex skills 投影与平台专属 skills
-├── .cursor/                 ← Cursor skills 投影
-├── .pi/                     ← Pi skills 投影与平台专属 skills
-├── AGENTS.md                ← AI 指令
-├── CONTEXT.md               ← 领域词汇表
-├── yss-project.yaml         ← 仓库身份清单
-├── docs/
-│   ├── api/                 ← OpenAPI 3.1 契约
-│   ├── adr/                 ← 架构决策记录
-│   ├── requirements/        ← Spec / 用户故事 / 需求草案 / 垂直切片
-│   ├── plan/                ← 战略规划与 Spec 上游输入
-│   ├── design/              ← 产品设计、原型、交互说明和状态矩阵
-│   ├── architecture/        ← 架构设计与审查模板
-│   ├── releases/            ← 发布说明
-│   ├── implementation/      ← 实施方案、上线记录和回滚方案
-│   ├── testing/             ← 测试策略和验证记录
-│   ├── agents/              ← Agent 协作规范、Ticket/Triage/领域文档约定
-│   ├── templates/           ← 通用文档模板
-│   └── process/             ← 生命周期、裁剪、Scrum 和技能治理说明
-└── scripts/                 ← 模板轻量校验脚本
+├── .agents/skills/          ← 共享技能权威内容
+├── .codex/、.cursor/、.pi/  ← 技能投影与平台专属能力
+├── AGENTS.md                ← Agent 入口规则
+├── CONTEXT.md               ← 唯一业务词汇表
+├── yss-project.yaml         ← 仓库身份
+├── .template-spec/          ← 可复用流程、门禁、契约与文档模板
+├── .template-source/        ← 模板维护、分发工具和历史证据（不进入实例）
+├── docs/                    ← 项目实例按需创建的 Plan、Spec、设计、Ticket 与交付证据
+└── scripts/                 ← 合同与流程验证工具
 ```
 
 项目需要生成度量、外部实现仓库记录或其他临时产物时再按需创建对应目录。前后端实现仓库接入规则见 `.template-spec/process/implementation-repo-integration.md`。
@@ -37,9 +25,9 @@
 ## Quickstart
 
 1. 先读取 `yss-project.yaml`，按 `repository_mode` 选择模板维护或产品研发生命周期。
-2. 必读入口为 `AGENTS.md` 与 `CONTEXT.md`；流程事实分别以生命周期映射和裁剪指南为准。
+2. 必读入口为 `AGENTS.md` 与 `CONTEXT.md`；流程事实以生命周期注册表和裁剪指南为准。
 3. `template-source` 修改后先按 `maintenance-intensity.yaml` 判定 L1 / L2 / L3，默认用 `scripts/verify-template-fast` 达到 `implementation-ready`；L3 日常采用维护者自检，正式发布前执行完整门禁；只有共享 skill 变更才运行 `scripts/sync-skills` 和 `scripts/update-skill-lock`。
-4. `project-instance` 默认从 `yss-product-lifecycle` 的 `route` 模式开始，再由原生 `work-unit.*` 推进 Plan、Spec、产品设计、工程契约和 Ticket 正式化；`grill-with-docs`、`to-spec`、`to-tickets`、`implement` 仅作为用户显式调用的兼容入口。
+4. `project-instance` 默认从 `yss-product-lifecycle` 的 `route` 模式开始，再由原生 `work-unit.*` 推进 Plan、Spec、产品设计、工程契约和 Ticket 正式化；`to-spec`、`to-tickets`、`implement` 仅作为用户显式调用的兼容入口。
 5. 实现仓库接入、YSS 路由、独立审查、fresh verification 和 Git checkpoint 以 `AGENTS.md` 的硬门禁为准。
 
 
@@ -94,7 +82,7 @@ scripts/verify-template-fast
 - 示例 OpenAPI YAML 是否可解析。
 - Git diff 是否存在空白错误。
 
-显式准备审查候选时执行 `scripts/verify-template-candidate`；首次正式冻结前和最终发布前执行不可裁剪的 `scripts/verify-template`。
+PR 执行 `scripts/verify-template-candidate`；main 与正式发布前执行不可裁剪的 `scripts/verify-template`。独立审查和候选冻结仅在显式采用旧兼容协议时执行。
 
 ## 关键文档
 

package/template/scripts/contract

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
 import path from 'node:path';
-import {viewContract,diffContract} from './lib/contract-views.mjs';
+import {viewContract,diffContract,prepareContractReview} from './lib/contract-views.mjs';
 try{
  const args=process.argv.slice(2),mode=args.shift(),options={},positional=[];
- for(let i=0;i<args.length;i++){const arg=args[i];if(arg==='--json')options.json=true;else if(arg.startsWith('--')){const key=arg.slice(2);if(!['kind','profile','unit','root','before-root'].includes(key)||!args[i+1]||args[i+1].startsWith('--'))throw Error(`未知或缺值参数 ${arg}`);options[key]=args[++i];}else positional.push(arg);}
- const config={kind:options.kind,root:path.resolve(options.root||process.cwd()),profile:options.profile||'review',unit_id:options.unit,beforeRoot:options['before-root']?path.resolve(options['before-root']):undefined};
+ for(let i=0;i<args.length;i++){const arg=args[i];if(arg==='--json')options.json=true;else if(arg.startsWith('--')){const key=arg.slice(2);if(!['kind','profile','unit','root','before-root','decision','task-layout'].includes(key)||!args[i+1]||args[i+1].startsWith('--'))throw Error(`未知或缺值参数 ${arg}`);options[key]=args[++i];}else positional.push(arg);}
+ const config={kind:options.kind,root:path.resolve(options.root||process.cwd()),profile:options.profile||'review',unit_id:options.unit,task_layout:options['task-layout']||'legacy',beforeRoot:options['before-root']?path.resolve(options['before-root']):undefined,decision_ref:options.decision};
  if(!options.kind)throw Error('必须用 --kind 明确资产类型');
- if(!['view','diff'].includes(mode)||positional.length!==(mode==='view'?1:2))throw Error('用法: contract view <资产> --kind <类型> [--profile review|task|full] [--unit <ID>] [--json] | diff <旧资产> <新资产> --kind <类型>');
- const result=mode==='view'?viewContract(positional[0],config):diffContract(positional[0],positional[1],config);
+ if(!['view','diff','prepare-review'].includes(mode)||positional.length!==(mode==='view'?1:2))throw Error('用法: contract view <资产> --kind <类型> [--profile review|task|full] [--unit <ID>] [--json] | diff|prepare-review <旧资产> <新资产> --kind <类型> [--decision <原决定>]');
+ const result=mode==='view'?viewContract(positional[0],config):mode==='prepare-review'?prepareContractReview(positional[0],positional[1],config):diffContract(positional[0],positional[1],config);
  process.stdout.write(options.json||!result.markdown?JSON.stringify(result,null,2)+'\n':result.markdown);
  if(result.blockers?.length)process.exitCode=1;
 }catch(error){process.stderr.write(error.message+'\n');process.exitCode=1;}

package/template/scripts/lib/contract-views.mjs

@@ -59,19 +59,25 @@ function markdown(view){
  return lines.join('\n\n')+'\n';
 }
 export function viewContract(ref,options={}){return withValidationPhase({root:options.root,purpose:'contract-view',slice_id:ref,work_unit_id:options.unit_id,readOnly:true},()=>view(ref,options));}
-function view(ref,{root=process.cwd(),kind,profile='review',unit_id}={}){
+function view(ref,{root=process.cwd(),kind,profile='review',unit_id,task_layout='legacy'}={}){
  validateKind(kind);if(!['review','task','full'].includes(profile))throw new TypeError(`未知阅读档位 ${profile}`);
+ if(!['legacy','focused'].includes(task_layout))throw new TypeError(`未知 task layout ${task_layout}`);
  let binding,content,checks=['可读取'],blockers=[],sourceChecks=[];
  if(kind==='slice'){
   const loaded=readSliceContract(ref,{root,diagnostic:true});binding=loaded.binding;blockers.push(...declaredBlockers(loaded.raw));
   const legacy=renderSliceContractView(ref,{root,unit_id:profile==='task'?unit_id:undefined});
   checks.push('Slice 结构及绑定来源');
-  if(legacy.diagnostic_only){content={诊断:legacy.blockers};blockers=legacy.blockers.map(b=>b.reason);}
+  if(legacy.diagnostic_only){content={诊断:legacy.blockers,未校验的原合同:loaded.raw};blockers=legacy.blockers.map(b=>b.reason);}
   else if(profile==='full')content={权威合同:loaded.raw,完整视图:legacy};
   else if(profile==='review'){
    content={...legacy.summary,验收:legacy.acceptance,实施范围:{工程:loaded.raw.scope?.project_roots||legacy.constraints.project_roots,允许写入:loaded.raw.scope?.allowed_write_paths||legacy.constraints.allowed_write_paths},关键约束:loaded.raw.scope?.forbidden_patterns||legacy.constraints.forbidden_patterns,停止条件:'来源或批准过期、越界、缺证据、验证失败、drift / violation / new_impacts 时停止并回交。'};
    for(const key of ['risks','risk_acceptance','blockers','pending_decisions','constraints'])if(loaded.raw[key])content[key]=loaded.raw[key];
    for(const [label,pattern]of [['风险',/风险/],['关键取舍',/取舍/],['待决定事项',/待|决定/],['变化',/变化|变更/]])if(!Object.keys(content).some(k=>pattern.test(k)))content[label]='来源未说明，审阅时核实。';
+   const reviewKnown=new Set(['schema_version','contract_id','contract_version','slice_id','status','basis','scope','common','lifecycle_refs','applicability','resolution','acceptance','verification','work_units','extensions','ticket_policy']);
+   content.未分类约束=Object.fromEntries(Object.entries(loaded.raw).filter(([key])=>!reviewKnown.has(key)));
+   // Normalization preserves raw v2 common / v3 scope, including nested unknown constraints.
+   content.全局约束=legacy.constraints;
+   content.专项约束=loaded.raw.extensions;content.适用性=loaded.raw.applicability;
    const extensions=loaded.raw.extensions||{};
    for(const [name,extension]of Object.entries(extensions))for(const [key,value]of Object.entries(extension))if(/risk|constraint|decision|block|exception|unknown/.test(key))content[`${name}.${key}`]=value;
   }else{
@@ -80,6 +86,13 @@ function view(ref,{root=process.cwd(),kind,profile='review',unit_id}={}){
    content={当前任务:units[0].work_unit||units[0],全局约束:legacy.constraints,专项约束:legacy.extensions,编译约束:loaded.raw.resolution,适用性:loaded.raw.applicability,验收:legacy.acceptance,上游引用:Object.fromEntries(Object.entries(loaded.sources).map(([k,v])=>[k,{ref:v.ref,version:v.version}])),停止条件:'来源或批准过期、越界、缺证据、验证失败、drift / violation / new_impacts 时停止并回交。'};
    const known=new Set(['schema_version','contract_id','contract_version','slice_id','status','basis','scope','applicability','resolution','acceptance','verification','work_units','extensions','ticket_policy']);
    content.其他约束=Object.fromEntries(Object.entries(loaded.raw).filter(([k])=>!known.has(k)));
+   if(task_layout==='focused' && loaded.raw.schema_version===3){
+    const task=units[0].work_unit||units[0];
+    const ids=new Set([...(task.acceptance_refs||[]),...(task.verification||[]).flatMap(v=>v.acceptance_refs||[])]);
+    content={当前任务:task,验收:Object.fromEntries(Object.entries(legacy.acceptance).filter(([id])=>ids.has(id))),全局约束:{...legacy.constraints,verification_commands:task.verification_commands,expected_evidence_files:task.expected_evidence},专项约束:legacy.extensions,编译约束:loaded.raw.resolution,适用性:loaded.raw.applicability,上游引用:content.上游引用,其他约束:content.其他约束,停止条件:content.停止条件,
+     恢复动作:['读取主 tracker 或当前任务包，核对实际运行结果；运行状态未知时不重复派发','复验当前来源、批准和适用门禁；失效时回交，不能沿用旧完成结论'],
+     完整验收引用:{ref,digest:binding.digest,profile:'full',omitted_acceptance_ids:Object.keys(legacy.acceptance).filter(id=>!ids.has(id))}};
+   }
   }
  }else{
   const {bytes,raw}=load(ref,root);binding={ref,id:raw.contract_id||raw.technical_design_id||raw.decision_id||raw.request?.request_id||raw.handoff_id||raw.baseline_id||raw.spec_id||raw.plan_id||raw.id||null,version:raw.contract_version||raw.decision_version||raw.handoff_version||raw.version||null,digest:hash(bytes)};
@@ -107,3 +120,45 @@ export function diffContract(beforeRef,afterRef,{root=process.cwd(),beforeRoot=r
  walk(before.raw,after.raw,'');const source_checks=[...references(before.raw,beforeRoot).map(x=>({...x,side:'before'})),...references(after.raw,root).map(x=>({...x,side:'after'}))];
  return{read_only:true,approval_reusable:false,execution_allowed:false,before:{ref:beforeRef,digest:hash(before.bytes)},after:{ref:afterRef,digest:hash(after.bytes)},bytes_changed:!before.bytes.equals(after.bytes),changes,source_checks,decision_impact:'必须按当前差异和授权延续协议核验；无法读取旧来源时影响未知。'};
 }
+
+/** Mechanical review material only; original decisions and semantic review remain authoritative. */
+export function prepareContractReview(beforeRef, afterRef, options = {}) {
+  const root = options.root || process.cwd();
+  return withValidationPhase({root,purpose:'prepare-contract-review',readOnly:true}, () => {
+    validateKind(options.kind);
+    const gaps = [];
+    const gap = (code, source_ref, reason, recovery) => gaps.push({code,source_ref,reason,recovery});
+    const readView = (ref, side, sourceRoot) => {
+      try {
+        const value = viewContract(ref,{...options,root:sourceRoot,profile:'full'});
+        for(const blocker of value.blockers)gap('SOURCE_INVALID',ref,blocker,'恢复当前权威来源并重新校验');
+        return value;
+      } catch(error) { gap('SOURCE_UNREADABLE',ref,`${side}: ${error.message}`,'提供可读取的原始资产；不推断历史内容');return null; }
+    };
+    const before = readView(beforeRef,'before',options.beforeRoot||root), after = readView(afterRef,'after',root);
+    if(before?.binding.id && after?.binding.id && before.binding.id!==after.binding.id)gap('IDENTITY_CONFLICT',afterRef,'前后资产 ID 不一致','选择同一资产的前后版本');
+    if(before?.binding.version && before.binding.version===after?.binding.version && before.binding.digest!==after.binding.digest)gap('VERSION_CONFLICT',afterRef,'相同版本包含不同字节','形成新候选版本并重新核验');
+    let diff = null;
+    if(before&&after)try{diff=diffContract(beforeRef,afterRef,options);}catch(error){gap('DIFF_UNAVAILABLE',afterRef,error.message,'先修复来源绑定与版本冲突');}
+    let originalDecision = null;
+    if(options.decision_ref) {
+      try {
+        const loaded=load(options.decision_ref,root);
+        schema(loaded.raw,'.template-spec/process/schemas/user-decision.schema.json');
+        originalDecision={ref:options.decision_ref,digest:hash(loaded.bytes),record:loaded.raw};
+        for(const row of references(loaded.raw,root))if(!row.current)gap('DECISION_SOURCE_STALE',row.ref,row.error||'原决定来源摘要不匹配','恢复原决定快照；不得重绑旧回复');
+      }catch(error){gap('DECISION_UNAVAILABLE',options.decision_ref,error.message,'提供有效的原始决定；本材料不能替代用户回复');}
+    }
+    if(!options.decision_ref)gaps.push({code:'DECISION_NOT_PROVIDED',source_ref:null,reason:'未提供原决定，不能判断批准延续',recovery:'需要沿用批准时提供原决定及原始回复来源',blocking:false});
+    return {
+      schema_version:1,kind:'contract-review-preparation',read_only:true,execution_allowed:false,
+      approval_reusable:false,approval_validity:'not-checked',semantic_equivalence:'requires-independent-review',
+      before:before?.binding||null,after:after?.binding||null,original_decision:originalDecision,
+      decision_status:options.decision_ref?(originalDecision?'requires-validation':'missing-or-invalid'):'not-provided',
+      source_views:{before:before?.content||null,after:after?.content||null},diff,gaps,
+      review_required:['business_scope','acceptance','contract_commitments','authorization','risk_acceptance','quality','external_commitments'],
+      next_action:gaps.some(x=>x.blocking!==false)?'repair-source-gaps':'independent-semantic-review',
+      blockers:gaps.filter(x=>x.blocking!==false).map(item=>item.reason)
+    };
+  });
+}