create-yss-spec 3.5.6 → 3.5.9

package/template/.template-spec/templates/examples/lifecycle-writing-examples.md

@@ -1,8 +1,8 @@
-# Plan、Spec、Ticket 写作对照
+# Plan、Spec、Ticket、PR / MR 与复盘写作对照
 
 性质：虚构的写作示例，非产品资产，不代表业务术语或批准记录。
 
-本文件配合[中文写作规范](../../process/document-writing.md)。每组先给固定输入，再给两种表达，最后逐项核对。三组独立提供事实，不表示真实项目已经从 Plan 进入 Spec 或取得任何批准。“原写法”由作者构造，不是对模型运行结果或真实文档的抽样。
+本文件配合[中文写作规范](../../process/document-writing.md)。每组先给固定输入，再给两种表达，最后逐项核对。各组独立提供事实，不表示真实项目已经从 Plan 进入 Spec、执行验证或取得任何批准。“原写法”由作者构造，不是对模型运行结果或真实文档的抽样。
 
 ## 1. Plan：让业务问题和取舍可见
 
@@ -152,3 +152,93 @@
 | 预登记发现与样本类别 | [样本清单](plan-spec/expectations.json) |
 
 附件案例的变化练习：若将 FR-002 的“一次列出全部缺失名称”改成“仅显示一项”，应同时审查 S3 和 AC-001。`diff` 能展示原文字节、FR 和 AC 引用的变化，但不能决定业务含义等价，也不能据此继续使用原批准。读取附件清单失败的行为仍为 Q-001，不能由成功路径的测试例子擅自确定。
+
+## 5. PR / MR：说明最终行为和实际验证范围
+
+### 固定输入
+
+以下命令、退出码、版本和回滚记录均为虚构材料，用于写作练习，不是本仓执行结果。
+
+| 示例编号 | 已提供信息 |
+|---|---|
+| M1 | 表单缺少两个必填附件时，当前页面只显示第一个名称；候选改动展示全部缺失名称 |
+| M2 | 最终改动只涉及缺失附件列表的展示和组件测试；依据为示例 Spec v2 / R1、Ticket EX-17 与当前 Slice Implementation Contract v1，不改变提交接口 |
+| M3 | 在示例工程根目录运行 `pnpm test -- attachment-validation`，退出码 0；证据 `example-evidence/component-test.txt` 覆盖两个名称展示和页面输入保留 |
+| M4 | 在同一目录运行 `pnpm typecheck`，退出码 2；证据 `example-evidence/typecheck.txt` 含 TS2322，原因尚未确认 |
+| M5 | `pnpm test:e2e` 未执行，示例环境缺少所需浏览器；实际提交、拒绝和补齐后再次提交的浏览器流程仍未覆盖 |
+| M6 | 变更没有数据迁移；已有恢复记录可将该展示改动恢复到示例候选 `example-before`，但恢复未执行验证。当前仅授权起草描述，没有 Git 写入或远程操作授权 |
+
+### 原写法：将局部通过扩大为完成
+
+本次全面优化附件校验体验，所有测试已通过，可直接合并并发布。后续将创建 PR，必要时回滚即可。
+
+### 改写：四部分保留验证失败和边界
+
+申请人同时缺少两个必填附件时，当前页面只显示第一个名称。候选改动展示全部缺失名称；组件测试已覆盖两个名称展示和页面输入保留。
+
+最终范围是缺失附件列表展示及组件测试，依据为示例 Spec v2 / R1、Ticket EX-17 和当前 Slice Implementation Contract v1，提交接口保持既有行为。
+
+在示例工程根目录执行 `pnpm test -- attachment-validation`，退出码 0，结果见 `example-evidence/component-test.txt`。同目录的 `pnpm typecheck` 退出码 2，日志含 TS2322，原因尚未确认，见 `example-evidence/typecheck.txt`。环境缺少所需浏览器，`pnpm test:e2e` 未执行；实际提交、拒绝和补齐后再次提交的浏览器流程仍待验证。
+
+当前保留类型检查失败和浏览器流程未覆盖两项限制，不能据此声明可合并或可发布。变更没有数据迁移；可按已有恢复记录恢复到 `example-before`，恢复步骤尚未执行验证。本次交付仅为描述草稿，Git 写入和远程创建 PR / MR 仍需原任务范围内的授权。
+
+### 保真核对
+
+| 输入 | 改写落点 | 保留语义 |
+|---|---|---|
+| M1 | 首段 | Before 与候选 After 对应具体触发条件 |
+| M2 | 第二段 | 只描述最终范围，合同引用不扩展成合并批准 |
+| M3 | 首段、第三段 | 局部通过只支持其实际覆盖的行为 |
+| M4 | 第三、四段 | 保留失败退出码和未知原因 |
+| M5 | 第三、四段 | 未执行与未覆盖均保留，不并入通过项 |
+| M6 | 第四段 | 保留恢复未验证、数据影响和起草授权边界 |
+
+## 6. 复盘：把失误机制连接到改进与关闭证据
+
+### 固定输入
+
+以下检查、行动编号和证据路径均为虚构材料；它们只演示如何引用既有行动，不建立真实待办或生命周期状态。
+
+| 示例编号 | 已提供信息 |
+|---|---|
+| F1 | 日志脱敏检查已经存在，但本次验证入口没有调用它；执行记录中没有该检查，漏检机制已确认 |
+| F2 | 既有行动 EX-A1 的权威记录已登记修复和关闭证据：验证入口已接入检查，原未脱敏反例退出码 1，修正样本退出码 0，入口日志证明实际执行；证据为 `example-evidence/log-check-before.txt`、`log-check-after.txt`、`entry-run.txt` |
+| F3 | 普通 Markdown 文档引用目标缺失在两次候选中重复出现；已检查的现有校验未覆盖该类引用。既有行动 EX-A2 仅登记增加最小目标存在性检查和失败反例的计划，尚未修改或执行 |
+| F4 | 一份用户反馈摘要可能混淆事实和推断，机制与适用范围尚未确认。当前没有可靠机械判定方法；建议人工对照原始反馈逐项核对来源、确定程度和范围，并记录结果，行动尚未分派 |
+
+### 原写法：将建议和文件存在当作闭合
+
+检查体系已完善，相关问题全部闭环。以后所有反馈摘要都禁止使用推断，并增加全量文档扫描以避免遗漏。
+
+### 改写：沿用复盘模板的四个章节
+
+#### 做得好的地方
+
+既有日志脱敏检查能检测原未脱敏反例，修正样本可以通过；本次修复后，入口日志也证明检查实际执行。结果引用 EX-A1 的权威行动记录及三份验证证据，收益仅限于这项已验证的接入修复。
+
+#### 需要改进的地方
+
+日志脱敏检查原先没有接入本次验证入口，有检查文件未能阻止漏执行。该机制已由执行记录确认。
+
+普通 Markdown 引用目标缺失已在两次候选中重复出现，现有校验未覆盖这一可机械判定的不变量。反馈摘要混淆事实和推断目前只是待验证假设，尚不能据单份材料确定通用机制。
+
+#### 改进动作
+
+EX-A1 的修复、实际执行与关闭证据继续引用其权威行动记录，本报告不另维护状态。EX-A2 已登记最小目标存在性检查及失败反例的计划；尚未修改或执行，保持待处理。反馈摘要的人工核对行动尚未分派，写“未登记”，不自行指定负责人或关闭时点。
+
+#### 沉淀去向
+
+EX-A1 已修订既有验证入口；原反例退出码 1、修正样本退出码 0，以及入口实际执行证据共同支持接入修复的关闭条件。
+
+EX-A2 拟在既有校验场景中增加只覆盖目标引用类型的最小检查。需要保留缺失目标时失败的反例和修订后的实际执行结果；当前只有计划，不能关闭。
+
+反馈摘要先按建议的人工方法对照原始反馈，逐项记录出处、确定程度和范围，将结果留在关联行动中。机制未确认前不修订通用 Skill 禁令，也不把单次现象扩大为所有反馈的限制。
+
+### 保真核对
+
+| 输入 | 改写落点 | 保留语义 |
+|---|---|---|
+| F1 | 需要改进、沉淀去向 | 区分检查存在与接入、执行；优先修复已有检查的接线 |
+| F2 | 做得好的地方、改进动作、沉淀去向 | 关闭引用实际修订、失败反例和执行证据，不另建行动状态 |
+| F3 | 需要改进、改进动作、沉淀去向 | 重复且可机械判定的问题落到最小检查；计划未被写成完成 |
+| F4 | 需要改进、改进动作、沉淀去向 | 假设、人工方法和未分派均保留；单次问题不成为通用禁令 |

package/template/.template-spec/templates/retro-report-template.md

@@ -13,12 +13,19 @@ owner: ai
 
 ## 需要改进的地方
 
-记录触发条件、实际影响与证据，区分已确认机制和待验证假设；说明返工或漏检为何未被既有检查发现。
+记录触发条件、实际影响与证据，区分事实、已确认机制和待验证假设；说明返工或漏检为何未被既有检查发现。检查是否存在、是否接入本次执行路径、是否实际执行分别说明，不把“有检查”写成“本次已检查”。
 
 ## 改进动作
 
-引用既有待办 / 工作项；在其权威记录中登记负责人、解决时点、验证方法、关闭条件与关闭证据。本节说明动作如何解决上述问题，不另外维护一套进度；未分派写未登记。
+引用既有待办 / 工作项；在其权威记录中登记负责人、解决时点、验证方法、关闭条件与关闭证据。本节说明动作如何解决上述问题，不另外维护一套进度；未分派写未登记。只有计划、建议或尚未执行的验证时保持待处理，不能关闭行动。
 
 ## 沉淀去向
 
-列出需修订的事实源、Skill / 模板 / 校验场景及关联行动。关闭时引用实际修订和验证结果，只有建议或计划时保持待处理。
+列出需修订的事实源、Skill / 模板 / 校验场景及关联行动，说明每项采取以下哪种处置及理由：
+
+- 既有检查未接线或漏执行：优先修复接入与执行路径，引用修订位置及本次实际执行证据。
+- 重复出现、可机械判定的不变量缺少检查：确认既有检查未覆盖后，增加最小检查，以失败反例证明能检测目标情形，并记录修订后的实际验证结果。
+- 无法机械判定：说明人工验证的方法、判断依据和结果记录位置，按关联行动的关闭条件留证。
+- 机制或适用范围尚未确认：登记待验证假设与验证方法，不把单次现象直接写成通用禁令。
+
+关闭时引用实际修订与验证结果；检查已存在、方法已提出或文档已起草本身不构成关闭证据。事实源、Skill、模板和检查只在各自权威位置修订，本节引用其去向。

package/template/.template-spec/templates/review-bundle-template.yaml

@@ -1,4 +1,4 @@
-schema_version: 1
+schema_version: 2
 kind: review-bundle
 bundle_id: review-bundle.plan
 task_id: replace-with-plan-review-task-id
@@ -7,20 +7,29 @@ review_session_id: replace-with-stable-review-session-id
 role_id: role.product-manager
 runtime_id: runtime.generic
 principal_ref: replace-with-reviewer-instance
+review_task_ref: docs/.scratch/<feature>/reviews/task.json
+review_task_digest: replace-with-current-task-64-char-sha256
+capability_ids: [capability.business-rules]
+basis:
+- ref: replace-with-current-review-evidence
+  digest: replace-with-current-evidence-64-char-sha256
 reviews:
-- schema_version: 1
+- schema_version: 2
   gate_id: check.domain-strategy-approved
-  decision: approved
+  decision: pending
   actor_kind: digital-human
   role_id: role.product-manager
   runtime_id: runtime.generic
   principal_ref: replace-with-reviewer-instance
-  drafter_role_id: role.requirements-manager
   drafter_principal_ref: replace-with-drafter-instance
   subject_ref: docs/.scratch/<feature>/domain/domain-strategy-v1.yaml
-  subject_digest: replace-with-64-char-sha256
-  approval_scope:
-  - replace-with-feature-id
-  evidence_refs:
-  - replace-with-current-review-evidence
-notes: 本模板只用于起草。只保留实际命中的 check；同一 bundle 的所有结论必须来自同一复核任务、会话和实例。
+  subject_digest: replace-with-current-subject-64-char-sha256
+  approval_scope: [replace-with-feature-id]
+  basis:
+  - ref: replace-with-current-review-evidence
+    digest: replace-with-current-evidence-64-char-sha256
+  evidence_refs: [replace-with-current-review-evidence]
+  review_task_ref: docs/.scratch/<feature>/reviews/task.json
+  review_task_digest: replace-with-current-task-64-char-sha256
+  capability_ids: [capability.business-rules]
+notes: 由 prepare-review-package 按当前 checkpoint 起草 task、摘要、差异和覆盖。所有逐项结论必须由同一独立任务、会话和实例实际审查；pending 草案不授予批准。

package/template/.template-spec/user-guide//347/224/250/346/210/267/346/211/213/345/206/214.md

@@ -19,6 +19,8 @@
 
 先运行所用包的 `--version` 和 `--help`；源码候选版本、npm 已发布版本和实例记录的模板快照是三个不同事实。
 
+执行过程中出现 JS/MJS 或 Python 时，按[脚本执行与依赖说明](../process/script-execution.md)核对其用途、已安装入口和解释器依赖；重复的机械操作应复用已有工具。
+
 | 能力 | `create-yss-spec` | 战略、后端、前端专职 CLI |
 |---|---|---|
 | init | 默认命令；写入新目录 | `init`；只接受不存在或空目录 |

package/template/AGENTS.md

@@ -74,9 +74,10 @@
 
 - 实现者不做独立审查，Reviewer 不写实现；代码审查统一用 `code-review`。mandatory 不豁免；`violation` 修复后重审，`drift` / `new_impacts` 使合同 `stale` 并回编译器。
 - “完成 / 可合并 / 可发布”仅基于 Fresh Verification；历史结果、自述无效。
-- 会签按角色表 `gate_policy` 并经 `scripts/verify-approval-record --require-approved` 核验；`user_decision_policy` 命中的关键决定必须先展示可审阅资产，再取得提问者或其明确指定负责人的真实回复。无回复保持等待，数字人不能代答；原始来源、范围、复用和失效见生命周期 `references/user-decisions.md`。发布、商务承诺、运行时外部副作用仍须生物人。
-- 普通功能默认一个推进负责人和一个独立审查者；候选角色列表不要求逐角色签字。相邻检查可组合审查、逐项留结论。已有范围授权按用户决定协议验证延续，实质变化或未知影响才重新决定；外部强制审批不得裁掉，缺陷和缺证据仍阻断，非阻断建议进入待办。
-- 会签暂停、handoff、实现、合并、发布边界同步范围、证据、风险、会签点、Ticket 状态和下一步。Git checkpoint 只含本轮范围；提交 / 推送须用户授权。
+- 会签按角色表 `gate_policy` 并经 `scripts/verify-approval-record --require-approved --checkpoint <current checkpoint>` 核验；当前期望上下文由消费者的 checkpoint / 任务提供，不从会签记录反向填充。`user_decision_policy` 命中的关键决定必须先展示可审阅资产，再取得提问者或其明确指定负责人的真实回复。无回复保持等待，数字人不能代答；原始来源、范围、复用和失效见生命周期 `references/user-decisions.md`。发布、商务承诺、运行时外部副作用仍须生物人。
+- 普通功能默认一个推进负责人和一个独立审查者；候选角色列表不要求逐角色签字。相邻检查可组合审查、逐项留结论。已有范围授权按用户决定协议验证延续，未知影响先调查，确认实质决定变化后才重新决定；外部强制审批不得裁掉，缺陷和缺证据仍阻断，非阻断建议进入待办。
+- 首轮覆盖全部适用审查项；修复后按差异、受影响结论 / 行为及依赖定向复审，并重新绑定当前候选。摘要变化、UI 影响或 `new_impacts` 不触发默认全轴复审；未知影响先调查。能力与补充只读技能从角色表编译，禁止用职称代替能力或独立身份。专业审查等待由主控自主派发并等待，验证失败修复或路由；仅缺真实决定或新授权时展示资产后询问，独立工作继续。
+- 会签暂停、handoff、实现、合并、发布边界同步范围、证据、风险、会签点、Ticket 状态和下一步。Git checkpoint 只含本轮范围；提交 / 推送须用户授权。仅 `template-source` 的 `scripts/advance-maintenance-iteration` 入口可在**本地 `refs/checkpoints/<run-id>` 引用**上自动创建 checkpoint 提交（不推送、不改分支、不建 tag）；`project-instance` 不适用；写入 main、推送远端、打 tag、发布仍须用户授权。
 - 发布或阶段完成时判断复盘；架构 / 验证返工、IMPORTANT / CRITICAL finding、人工确认延期时，落中文复盘并修订事实源。
 
 ## 11. Subagent 协同

package/template/CONTEXT.md

@@ -106,8 +106,8 @@ context_schema_version: 1
 | 跨仓库契约变更 | 需要两个或多个独立仓库协同实现、验证和按顺序发布的共享契约变化。 | — | 任一参与仓库未完成契约对齐和集成验证时，不得单独声称整体可发布。 |
 | 模板源仓库（`template-source`） | 承载 `yss-spec-project-template` 权威模板资产及其演进规则的仓库身份。 | — | 只管理可复用模板，不承载某个具体产品的研发生命周期资产。 |
 | 模板实例仓库（`project-instance`） | 由模板初始化后生成、承载某个具体产品研发生命周期资产的仓库身份。 | — | 不作为通用流程模板的权威来源。 |
-| 模板实例分发面 | 模板源中应随 CLI 快照进入 `project-instance` 的共享生命周期、模板、用户指南和验证资产集合。 | — | 不包含模板源审查、研究、发布路线、源仓库专属 ADR 或源仓库 LLM Wiki 编译树。 |
-| 模板源治理区 | 仅供 `template-source` 使用、保存审查证据、研究记录、跨仓契约、发布路线、源仓库治理决策和源仓库 LLM Wiki 编译树的归档区域。 | — | 不随 CLI 分发；不等于产品实例的研发管理资产。`wiki-root` 为 `.template-source/wiki`。 |
+| 模板实例分发面 | 模板源中应随 CLI 快照进入 `project-instance` 的共享生命周期、模板、用户指南和验证资产集合。 | — | 不包含模板源维护记录、源仓库专属治理资产或源仓库 LLM Wiki 编译树。 |
+| 模板源治理区 | 仅供 `template-source` 使用、保存现行跨仓契约、治理配置、维护工具和 LLM Wiki 阅读树的区域；维护日志、审查候选与历史证据保存在仓外运行目录。 | — | 不随 CLI 分发；不等于产品实例的研发管理资产。`wiki-root` 为 `.template-source/wiki`。 |
 | 仓库身份清单 | 显式声明仓库身份和清单结构版本的机器可读资产。 | — | 不承载项目名称、团队规模、Tracker 或其他易变业务配置。 |
 | 聚合门禁 | 汇总适用自动检查和独立专业审查后，对当前资产与范围作一次批准或验收；权威定义见生命周期注册表。 | — | 内部检查失败仍阻断；有效批准只在相关依据、范围或授权变化时失效。 |
 | 授权延续 | 原始用户批准明确覆盖当前边界、资产范围和决定依据时，经独立审查与当前验证继续推进。 | — | 不产生新的用户回复；未知或实质变化、撤回和外部强制审批缺失不能延续。证据格式见用户决定协议。 |

package/template/README.md

@@ -15,7 +15,7 @@
 ├── CONTEXT.md               ← 唯一业务词汇表
 ├── yss-project.yaml         ← 仓库身份
 ├── .template-spec/          ← 可复用流程、门禁、契约与文档模板
-├── .template-source/        ← 模板维护、分发工具和历史证据（不进入实例）
+├── .template-source/        ← 现行模板维护资产与分发工具（不进入实例；运行历史存仓外）
 ├── docs/                    ← 项目实例按需创建的 Plan、Spec、设计、Ticket 与交付证据
 └── scripts/                 ← 合同与流程验证工具
 ```
@@ -72,7 +72,7 @@ main@6acc160e4e0cd062dbbbd7a1b26ae92855edf07e
 scripts/verify-template-fast
 ```
 
-快速入口按 Git 影响面执行相关检查，未映射路径或核心校验资产变化时 fail-safe 升级。它与 candidate / 发布 profile 共同检查：
+快速入口按 Git 影响面执行相关检查，未映射路径或核心校验资产变化时 fail-safe 升级为完整验证，来源仍为当前工作树，用于 `implementation-ready`。显式 candidate / 发布入口要求已提交来源。三个入口共同检查：
 
 - `yss-project.yaml`、权威流程资产和模板是否完整。
 - 共享技能投影及 `skills-lock.json` 的完整树哈希是否一致。

package/template/scripts/advance-maintenance-iteration

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { parseArgs } from "node:util";
+import { ROOT } from "./lib/template-verification.mjs";
+import { captureMaintenanceCandidate } from "./lib/maintenance-candidate.mjs";
+import { commitCheckpoint, validateCheckpointRunId } from "./lib/checkpoint-commit.mjs";
+
+// One lean maintenance iteration: validate the run identity, capture the
+// candidate, publish a local checkpoint commit, run the mechanical gate, and
+// report machine-readable results. It never pushes, never moves a branch, and
+// never writes main. Approval stays human.
+const PROFILES = new Set(["fast", "candidate"]);
+try {
+  const { values } = parseArgs({ options: {
+    "run-id": { type: "string" },
+    base: { type: "string", default: "HEAD" },
+    output: { type: "string" },
+    plan: { type: "boolean", default: false },
+    json: { type: "boolean", default: false },
+    "skip-verify": { type: "boolean", default: false },
+    profile: { type: "string", default: "fast" },
+  }, strict: true });
+  if (!values["run-id"] || !values.output) throw new TypeError("用法: scripts/advance-maintenance-iteration --run-id <id> --output maintenance:candidates/<id> [--plan] [--json] [--profile fast|candidate]");
+  if (!PROFILES.has(values.profile)) throw new TypeError("--profile 必须是 fast 或 candidate: " + values.profile);
+  const runId = values["run-id"];
+  // Fail fast: an invalid or already-taken run id must not leave a candidate
+  // directory behind that blocks the retry.
+  validateCheckpointRunId(ROOT, runId);
+  const capture = values.plan ? { candidate_digest: null, manifest_ref: null, files: [] } : captureMaintenanceCandidate({ root: ROOT, outputDir: values.output, baseRef: values.base });
+  const checkpoint = commitCheckpoint({
+    root: ROOT,
+    runId,
+    baseRef: values.base,
+    dryRun: values.plan,
+    message: "checkpoint " + runId + "\n\nCandidate-Digest: " + (capture.candidate_digest || "plan") + "\nRun-Id: " + runId + "\n",
+  });
+  let verification = { profile: values.profile, exit_code: null, skipped: true };
+  if (!values.plan && !values["skip-verify"]) {
+    const command = values.profile === "candidate" ? ["scripts/verify-template-candidate", "--base", values.base] : ["scripts/verify-template-fast"];
+    const result = spawnSync(command[0], command.slice(1), { cwd: ROOT, encoding: "utf8", stdio: "inherit" });
+    if (result.error) throw new TypeError("机械验证无法执行: " + result.error.message);
+    verification = { profile: values.profile, exit_code: result.status, skipped: false, command: command.join(" ") };
+  }
+  const result = { run_id: runId, candidate_digest: capture.candidate_digest, manifest_ref: capture.manifest_ref, checkpoint, verification, review_required: true, approval: "human" };
+  if (values.json) process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+  else process.stdout.write("迭代 " + runId + "：" + (checkpoint.commit ? "checkpoint " + checkpoint.ref + " @ " + checkpoint.commit.slice(0, 12) : "计划模式") + "；机械验证=" + (verification.skipped ? "skipped" : verification.exit_code) + "；审查与批准仍由人确认\n");
+  if (!verification.skipped && verification.exit_code !== 0) process.exitCode = 1;
+} catch (error) {
+  process.stderr.write("迭代增强失败: " + error.message + "\n");
+  process.exitCode = 1;
+}

package/template/scripts/lib/approval-checkpoint-discovery.mjs

@@ -0,0 +1,26 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {approvalIO, approvalError} from './approval-record-io.mjs';
+
+/** Finds a declared owner; ambiguity is an error, never a guessed approval context. */
+export function findApprovalCheckpoint(root, approvalRef) {
+  const selected = path.resolve(root, approvalRef), matches = [];
+  const visit = ref => {
+    const full = path.resolve(root, ref);
+    if (!fs.existsSync(full)) return;
+    const stat = fs.lstatSync(full);
+    if (stat.isSymbolicLink()) return;
+    if (stat.isDirectory()) { for (const name of fs.readdirSync(full).sort()) visit(`${ref}/${name}`); return; }
+    if (!/\.(?:json|ya?ml)$/.test(ref)) return;
+    let value;
+    try { value = approvalIO({root}).document(ref); } catch { return; }
+    if (!value || value.gate_id || !value.gates) return;
+    const rows = [...Object.values(value.gates), ...Object.values(value.checks || {})];
+    if (rows.some(row => row?.approval_ref && path.resolve(root,row.approval_ref) === selected)) matches.push(ref);
+  };
+  for (const name of fs.readdirSync(root).sort()) {
+    if (name === 'docs' || name === '.yss' || /\.(?:json|ya?ml)$/.test(name)) visit(name);
+  }
+  if (matches.length !== 1) approvalError('APPROVAL_CONTEXT_REQUIRED', `批准记录需要唯一当前 checkpoint（找到 ${matches.length} 个）；请显式提供上下文`);
+  return matches[0];
+}

package/template/scripts/lib/approval-consumption.mjs

@@ -0,0 +1,35 @@
+import {createHash} from 'node:crypto';
+import {approvalIO, approvalError} from './approval-record-io.mjs';
+import {approvalExpectationFromSubject, approvalExpectationFromState} from './approval-current.mjs';
+
+const hex = value => value?.replace(/^sha256:/, '');
+const hash = bytes => createHash('sha256').update(bytes).digest('hex');
+
+/** The consumer's current binding chooses the review subject, never the approval record. */
+export function approvalExpectationForBoundAsset(boundary, binding, context = {}) {
+  const io = approvalIO(context);
+  const assetRef = typeof binding === 'string' ? binding : binding?.ref;
+  if (!assetRef) approvalError('APPROVAL_CONTEXT_REQUIRED', '消费方缺少当前资产引用');
+  const bytes = io.bytes(assetRef);
+  if (typeof binding === 'object' && binding.digest && hex(binding.digest) !== hash(bytes)) approvalError('APPROVAL_CURRENT_INVALID', '消费方当前资产摘要过期');
+  let asset;
+  try { asset = io.document(assetRef); } catch { asset = null; }
+  const current = binding?.approval_context || asset?.approval_context;
+  if (!current && !asset) approvalError('APPROVAL_CONTEXT_REQUIRED', '原始资产缺少消费方独立批准上下文');
+  // A current structured review package can be consumed directly. Raw assets
+  // need an independently selected approval_context in their current binding.
+  const expected = current
+    ? approvalExpectationFromState(boundary, current, context)
+    : approvalExpectationFromSubject(boundary, assetRef, context);
+  if (io.resolve(assetRef) !== io.resolve(expected.subject_ref)) {
+    const frozen = expected.basis?.find(item => io.resolve(item.ref) === io.resolve(assetRef));
+    if (frozen && hex(frozen.digest) !== hash(bytes)) approvalError('APPROVAL_CURRENT_INVALID', '当前资产批准上下文摘要过期');
+    if (!frozen) expected.basis = [...(expected.basis || []), {ref:assetRef,digest:hash(bytes)}];
+  }
+  if (context.scope && JSON.stringify([...context.scope].sort()) !== JSON.stringify([...expected.approval_scope].sort())) approvalError('APPROVAL_CURRENT_INVALID', '当前资产消费范围与审阅包不匹配');
+  return {...expected, review_package: context.review_package ?? expected.review_package};
+}
+
+export function approvalExpectationForCheckpoint(boundary, state, context = {}) {
+  return approvalExpectationFromState(boundary, state, context);
+}

package/template/scripts/lib/approval-current.mjs

@@ -0,0 +1,111 @@
+import {createHash} from 'node:crypto';
+import path from 'node:path';
+import {withValidationPhase, existsSync, readFileSync} from './validation-phase.mjs';
+import {loadRegistry, ROOT} from './lifecycle-registry.mjs';
+import {loadDigitalHumanRoles, countersignRuleForGate, BIOLOGICAL_ROLE_ID} from './digital-human-roles.mjs';
+import {parseAsset, validateAssetStructure} from './structured-assets.mjs';
+import {approvalIO, approvalError} from './approval-record-io.mjs';
+import {assertApprovalUserDecision} from './user-decision-reuse.mjs';
+import {assertReviewCapabilityBinding, approvalExpectedFromTask} from './review-capabilities.mjs';
+
+const hash = value => createHash('sha256').update(value).digest('hex');
+const hex = value => typeof value === 'string' ? value.replace(/^sha256:/, '') : value;
+const text = value => typeof value === 'string' && value.trim();
+const sameScope = (a,b) => Array.isArray(a) && a.length > 0 && Array.isArray(b) && b.length > 0 && new Set(a).size === a.length && new Set(b).size === b.length && JSON.stringify([...a].sort()) === JSON.stringify([...b].sort());
+const fail = detail => approvalError('APPROVAL_CURRENT_INVALID', detail);
+function checkedBasis(basis, io, label) {
+  if (!Array.isArray(basis) || !basis.length) fail(`${label} 缺少当前证据摘要`);
+  const refs = new Set();
+  return basis.map(asset => {
+    if (!text(asset?.ref) || refs.has(asset.ref) || !/^[a-f0-9]{64}$/.test(hex(asset.digest))) fail(`${label} 证据引用缺失、重复或摘要非法`);
+    refs.add(asset.ref);
+    if (hash(io.bytes(asset.ref)) !== hex(asset.digest)) fail(`${label} 证据过期: ${asset.ref}`);
+    return {ref:asset.ref,digest:hex(asset.digest)};
+  });
+}
+export function assertApprovalSigner(record, {rolesDoc = loadDigitalHumanRoles(), registry = loadRegistry()} = {}) {
+  validateAssetStructure(record, 'approval-record');
+  if (registry.id_policy?.deprecated_ids?.includes(record.gate_id)) fail(`未知或已退役门禁: ${record.gate_id}`);
+  if (!rolesDoc.runtimes?.some(runtime => runtime.id === record.runtime_id)) fail(`未知 runtime_id: ${record.runtime_id}`);
+  if (record.actor_kind === 'orchestrator') fail('编排器门禁不使用会签记录关闭');
+  let rule = countersignRuleForGate(rolesDoc.gate_policy, record.gate_id);
+  const continuationReviewers = rolesDoc.gate_policy.continuation_reviews?.[record.gate_id];
+  if (record.continuation_ref && record.actor_kind === 'digital-human' && continuationReviewers) rule = {bucket:'digital_human_review',gate:record.gate_id,countersigners:continuationReviewers};
+  if (!rule) fail(`${record.gate_id} 不是会签门禁；evidence_only / orchestrator 门禁不写 approval-record`);
+  if (record.decision !== 'approved') fail(`${record.gate_id} 会签 decision 必须为 approved 才能关闭门禁`);
+  if (record.biological_veto === true) fail(`${record.gate_id} 已被生物人否决，不能标为 approved`);
+  if (rule.bucket === 'biological_human') {
+    if (record.actor_kind !== 'biological-human' || record.role_id !== BIOLOGICAL_ROLE_ID) fail(`${record.gate_id} 必须由生物人会签`);
+  } else {
+    if (record.actor_kind !== 'digital-human') fail(`${record.gate_id} 必须由数字人会签`);
+    // v2 professional review is constrained by the issued capability task below.
+    if (!(record.schema_version === 2 && rule.capability_ids?.length) && !rule.countersigners?.includes(record.role_id)) fail(`${record.gate_id} 会签角色必须是 ${(rule.countersigners || []).join(' / ')}`);
+    if (record.schema_version === 1 && rule.drafter && record.role_id === rule.drafter) fail(`${record.gate_id} 起草者不得会签自己`);
+    if (record.schema_version === 1 && rule.drafter && record.countersigner_role_ids?.includes(rule.drafter)) fail(`${record.gate_id} 起草者不得出现在 countersigner_role_ids`);
+    if (rule.drafter && record.drafter_role_id && record.drafter_role_id !== rule.drafter) fail(`${record.gate_id} drafter_role_id 必须为 ${rule.drafter}`);
+  }
+  return rule;
+}
+export function approvalExpectationFromState(boundary, state, context = {}) {
+  if (!state || !text(state.subject_ref) || !sameScope(state.approval_scope, state.approval_scope)) approvalError('APPROVAL_CONTEXT_REQUIRED','当前消费边界缺少主体或批准范围');
+  const io = approvalIO(context), bytes = io.bytes(state.subject_ref);
+  let subject;
+  try {subject = parseAsset(bytes,io.resolve(state.subject_ref));} catch {subject = null;}
+  return {boundary,subject_ref:state.subject_ref,subject_digest:state.subject_digest || state.basis?.find(asset=>asset.ref===state.subject_ref)?.digest || hash(bytes),approval_scope:[...state.approval_scope],basis:state.basis?.filter(asset => ![state.approval_ref,state.subject_ref].includes(asset.ref)),drafter_principal_ref:state.drafter_principal_ref || subject?.drafter_principal_ref,review_package:context.review_package ?? state.review_package ?? boundary.startsWith('gate.'),review_context:state.review_context};
+}
+export function approvalExpectationFromSubject(boundary, subjectRef, context = {}) {
+  const io=approvalIO(context),bytes=io.bytes(subjectRef),subject=parseAsset(bytes,io.resolve(subjectRef)),scope=subject.approval_scope || subject.scope;
+  if (!sameScope(scope,scope) || !subject.basis?.length) approvalError('APPROVAL_CONTEXT_REQUIRED','当前主体缺少独立范围及依据；请提供 checkpoint/task 消费上下文');
+  return {boundary,subject_ref:subjectRef,subject_digest:hash(bytes),approval_scope:[...scope],basis:subject.basis,drafter_principal_ref:subject.drafter_principal_ref,review_package:context.review_package ?? boundary.startsWith('gate.')};
+}
+/** Validates only a supplied current binding; never derives expected values from the approval record. */
+function validateCurrentApproval(record, expected, context = {}) {
+  const authorityRoot=context.root || ROOT,rolesPath=path.resolve(authorityRoot,'.template-spec/agents/digital-human-roles.yaml'),registryPath=path.resolve(authorityRoot,'.template-spec/process/lifecycle-registry.yaml');
+  const roles = context.rolesDoc || loadDigitalHumanRoles(existsSync(rolesPath)?rolesPath:undefined), registry = context.registry || loadRegistry(existsSync(registryPath)?registryPath:undefined);
+  const rule = assertApprovalSigner(record, {rolesDoc:roles,registry});
+  if (!expected || !text(expected.boundary) || !text(expected.subject_ref) || !sameScope(expected.approval_scope,expected.approval_scope) || !expected.basis?.length) approvalError('APPROVAL_CONTEXT_REQUIRED','当前批准须有来自 checkpoint/task/当前主体的边界、范围及依据');
+  const io = approvalIO(context);
+  if (record.schema_version === 2) {
+    const task = io.document(record.review_task_ref);
+    const issued = approvalExpectedFromTask(task,{...context,expected:expected.review_context,read:context.read || readFileSync,rolesDoc:roles,registry,boundary:expected.boundary,reviewTaskRef:record.review_task_ref,reviewTaskDigest:record.review_task_digest});
+    if ((record.review_task_id && record.review_task_id !== task.task_id) || (record.review_work_unit_id && record.review_work_unit_id !== task.work_unit_id)) fail('组合包身份与正式审查任务不匹配');
+    if (record.review_bundle_basis) {
+      const basis = checkedBasis(record.review_bundle_basis,io,'组合包');
+      if (basis.length !== task.review_context.basis.length || basis.some(asset=>!task.review_context.basis.some(bound=>bound.ref===asset.ref && hex(bound.digest)===asset.digest))) fail('组合包依据与正式审查任务不匹配');
+    }
+    if (issued.subject_ref !== expected.subject_ref || !sameScope(issued.approval_scope,expected.approval_scope)) fail('当前消费上下文与正式审查任务范围不匹配');
+    for (const asset of expected.basis) if (!issued.basis.some(row => row.ref === asset.ref && hex(row.digest) === hex(asset.digest))) fail('当前消费上下文依据不属于正式审查任务');
+    if (expected.drafter_principal_ref && expected.drafter_principal_ref !== issued.drafter_principal_ref) fail('正式审查任务作者与消费上下文不匹配');
+    expected = {...expected,drafter_principal_ref:issued.drafter_principal_ref,review_context:expected.review_context || issued.review_context};
+  }
+  if (!text(expected.drafter_principal_ref)) approvalError('APPROVAL_CONTEXT_REQUIRED','当前消费上下文缺少独立起草者来源');
+  if (record.gate_id !== expected.boundary || record.subject_ref !== expected.subject_ref) fail('审查对象不匹配');
+  if (!sameScope(record.approval_scope,expected.approval_scope)) fail('审查范围不匹配');
+  if (!text(record.drafter_principal_ref) || record.drafter_principal_ref === record.principal_ref) fail('缺少独立审查身份或起草者自签');
+  if (expected.drafter_principal_ref && expected.drafter_principal_ref !== record.drafter_principal_ref) fail('起草者身份与当前消费上下文不匹配');
+  if (expected.implementer_principal_ref && record.principal_ref === expected.implementer_principal_ref) fail('实施者不得审查自己');
+  const bytes = io.bytes(expected.subject_ref);
+  if (!/^[a-f0-9]{64}$/.test(hex(record.subject_digest)) || hash(bytes) !== hex(record.subject_digest)) fail('审查资产摘要不匹配；批准依据过期');
+  if (expected.subject_digest && hash(bytes) !== hex(expected.subject_digest)) fail('当前主体摘要与消费边界冻结摘要不匹配');
+  let subject;
+  try {subject = io.document(expected.subject_ref);} catch {subject = null;}
+  if (expected.subject_id && ![subject?.id,subject?.contract_id].includes(expected.subject_id)) fail('主体 ID 不匹配');
+  if (expected.subject_version && ![subject?.version,subject?.contract_version].includes(expected.subject_version)) fail('主体版本不匹配');
+  if ((expected.review_package ?? expected.boundary.startsWith('gate.')) && (subject?.gate_id !== expected.boundary || !subject?.basis?.length)) fail('审阅包身份或依据缺失');
+  const required = checkedBasis(expected.basis,io,'当前消费上下文');
+  const bound = checkedBasis(record.basis || subject?.basis,io,'批准记录');
+  for (const asset of required) if (!bound.some(row => row.ref === asset.ref && row.digest === asset.digest)) fail(`批准范围未覆盖证据: ${asset.ref}`);
+  if (record.schema_version === 2) {
+    if (!expected.review_context) approvalError('APPROVAL_CONTEXT_REQUIRED','v2 批准缺少独立当前审查任务上下文');
+    assertReviewCapabilityBinding(record,{...context,read:context.read || readFileSync,rolesDoc:roles,registry,expected:expected.review_context});
+  }
+  if (roles.user_decision_policy.gates.includes(record.gate_id)) {
+    const result = assertApprovalUserDecision(record, roles, {...context,root:io.root});
+    if (record.actor_kind === 'biological-human' && result.validated.some(row => row.principal_ref !== record.principal_ref)) fail('user-decision-responder-mismatch: 生物人会签者与原始回复者不一致');
+  }
+  return {...rule, subject_ref:expected.subject_ref, approval_scope:[...expected.approval_scope], execution_authorization:'not-evaluated'};
+}
+
+export function assertCurrentApproval(record,expected,context={}) {
+  return withValidationPhase({root:context.root || ROOT,purpose:"approval-current-kernel",readOnly:true},()=>validateCurrentApproval(record,expected,context));
+}

package/template/scripts/lib/approval-record-io.mjs

@@ -0,0 +1,56 @@
+import path from 'node:path';
+import {existsSync, readFileSync} from './validation-phase.mjs';
+import {ROOT} from './lifecycle-registry.mjs';
+import {parseAsset, validateAssetStructure} from './structured-assets.mjs';
+
+export const approvalError = (code, detail) => { throw Object.assign(new TypeError(`${code}: ${detail}`), {code}); };
+export function approvalIO({root = ROOT, read = ref => readFileSync(ref)} = {}) {
+  root = path.resolve(root);
+  const resolve = ref => {
+    if (typeof ref !== 'string' || !ref.trim()) approvalError('APPROVAL_REFERENCE_REQUIRED', '缺少可读取引用');
+    return path.isAbsolute(ref) ? ref : path.resolve(root, ref);
+  };
+  const bytes = ref => read(resolve(ref));
+  const document = ref => parseAsset(bytes(ref), resolve(ref));
+  return {root, resolve, bytes, document};
+}
+export function readApprovalDocument(filePath, context = {}) {
+  const io = approvalIO(context), value = io.document(filePath);
+  validateAssetStructure(value, 'approval-record');
+  return value;
+}
+export function reviewBundleRows(bundle) {
+  if (![1, 2].includes(bundle?.schema_version) || bundle.kind !== 'review-bundle') approvalError('APPROVAL_BUNDLE_INVALID', '组合审查身份无效');
+  if (!Array.isArray(bundle.reviews) || !bundle.reviews.length) approvalError('APPROVAL_BUNDLE_INVALID', '组合审查不能为空');
+  if (new Set(bundle.reviews.map(row => row.gate_id)).size !== bundle.reviews.length) approvalError('APPROVAL_BUNDLE_INVALID', '组合审查 gate_id 重复');
+  for (const row of bundle.reviews) {
+    if (row.schema_version !== bundle.schema_version || row.role_id !== bundle.role_id || row.runtime_id !== bundle.runtime_id || row.principal_ref !== bundle.principal_ref) approvalError('APPROVAL_BUNDLE_INVALID', '组合审查必须来自同一复核角色、运行时和实例');
+    if (row.review_session_id != null && row.review_session_id !== bundle.review_session_id) approvalError('APPROVAL_BUNDLE_INVALID', '组合审查 review_session_id 不一致');
+    if (bundle.schema_version === 2) {
+      for (const field of ['review_task_ref','review_task_digest']) if (row[field] !== bundle[field]) approvalError('APPROVAL_BUNDLE_INVALID', `组合审查 ${field} 不一致`);
+      if (JSON.stringify([...(row.capability_ids || [])].sort()) !== JSON.stringify([...(bundle.capability_ids || [])].sort())) approvalError('APPROVAL_BUNDLE_INVALID', '组合审查 capability_ids 不一致');
+      if (row.basis?.some(asset=>!bundle.basis?.some(bound=>bound.ref===asset.ref && bound.digest===asset.digest))) approvalError('APPROVAL_BUNDLE_INVALID', '组合审查未覆盖逐项 basis');
+    }
+  }
+  return bundle.reviews;
+}
+export function selectApprovalRecord(record, gateId) {
+  if (record.kind !== 'review-bundle') return record;
+  const selected = reviewBundleRows(record).filter(row => row.gate_id === gateId);
+  if (selected.length !== 1) approvalError('APPROVAL_BUNDLE_INVALID', '组合审查缺少当前检查的明确结论');
+  return {...selected[0], review_bundle_id:record.bundle_id, review_task_id:record.task_id, review_work_unit_id:record.work_unit_id, review_session_id:record.review_session_id,...(record.schema_version===2?{review_bundle_basis:record.basis}:{})};
+}
+export function loadApprovalRecord(filePath, gateId, context = {}) {
+  return selectApprovalRecord(readApprovalDocument(filePath, context), gateId);
+}
+export function readApprovalHistory(filePath, context = {}) {
+  const record = readApprovalDocument(filePath, context);
+  if (record.kind === 'review-bundle') reviewBundleRows(record);
+  return {record, bucket:'history-only', execution_authorization:'not-evaluated'};
+}
+export function resolveApprovalRef(ref, fromFile = ROOT, {root = ROOT} = {}) {
+  if (typeof ref !== 'string' || !ref.trim()) approvalError('APPROVAL_REFERENCE_REQUIRED', 'approval_ref 不能为空');
+  if (path.isAbsolute(ref)) return ref;
+  const candidate = path.resolve(root, ref);
+  return existsSync(candidate) ? candidate : path.resolve(path.dirname(fromFile), ref);
+}