create-yss-spec 3.3.8 → 3.4.1

package/template/docs/process/schemas/strategic-handoff-delivery.schema.json

@@ -0,0 +1,84 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://yss.dev/schemas/strategic-handoff-delivery-v1.schema.json",
+  "title": "YSS Strategic Handoff Delivery Record v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "kind", "status", "handoff", "source_assets", "package_ref", "manifest_ref", "bundle_digest", "verification_ref", "consumer_routes", "previous_delivery"],
+  "properties": {
+    "schema_version": {"const": 1},
+    "kind": {"const": "strategic-handoff-delivery-v1"},
+    "status": {"const": "packaged"},
+    "handoff": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "version", "ref", "sha256", "schema_version"],
+      "properties": {
+        "id": {"type": "string", "pattern": "^strategic-design-handoff\\.[a-z0-9][a-z0-9-]*$"},
+        "version": {"type": "string", "pattern": "^v[1-9][0-9]*$"},
+        "ref": {"type": "string", "minLength": 1},
+        "sha256": {"type": "string", "pattern": "^sha256:[a-f0-9]{64}$"},
+        "schema_version": {"const": 5}
+      }
+    },
+    "source_assets": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["source_key", "id", "version", "ref", "digest"],
+        "properties": {
+          "source_key": {"type": "string", "minLength": 1},
+          "id": {"type": "string", "minLength": 1},
+          "version": {"type": "string", "minLength": 1},
+          "ref": {"type": "string", "minLength": 1},
+          "digest": {"type": "string", "pattern": "^sha256:[a-f0-9]{64}$"}
+        }
+      }
+    },
+    "package_ref": {"const": "package"},
+    "manifest_ref": {"const": "package/manifest.json"},
+    "bundle_digest": {"type": "string", "pattern": "^sha256:[a-f0-9]{64}$"},
+    "verification_ref": {"const": "verification.json"},
+    "consumer_routes": {
+      "type": "array",
+      "minItems": 3,
+      "maxItems": 3,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["route_id", "capability", "activation"],
+        "properties": {
+          "route_id": {"type": "string", "pattern": "^route\\.[a-z0-9][a-z0-9-]*$"},
+          "capability": {"enum": ["backend-technical-design", "frontend-engineering-design", "delivery-coordination"]},
+          "activation": {"enum": ["required", "optional", "not-applicable"]}
+        }
+      }
+    },
+    "zip": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["ref", "sha256"],
+      "properties": {
+        "ref": {"const": "package.zip"},
+        "sha256": {"type": "string", "pattern": "^sha256:[a-f0-9]{64}$"}
+      }
+    },
+    "previous_delivery": {
+      "anyOf": [
+        {"type": "null"},
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["handoff_id", "version", "bundle_digest"],
+          "properties": {
+            "handoff_id": {"type": "string", "minLength": 1},
+            "version": {"type": "string", "pattern": "^v[1-9][0-9]*$"},
+            "bundle_digest": {"type": "string", "pattern": "^sha256:[a-f0-9]{64}$"}
+          }
+        }
+      ]
+    }
+  }
+}

package/template/docs/process/schemas/strategic-handoff-import-receipt-v3.schema.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://yss.dev/schemas/strategic-handoff-import-receipt-v3.schema.json",
+  "title": "YSS Strategic Handoff Import Receipt v3",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "bundle_id", "version", "bundle_digest", "package_ref", "source_delivery_record_ref", "source_delivery_record_sha256", "target_context_digest", "target_profile_id", "selected_consumer_capabilities", "routes", "status", "ready_for_agent"],
+  "properties": {
+    "schema_version": {"const": 3},
+    "bundle_id": {"type": "string", "pattern": "^strategic-design-handoff\\.[a-z0-9][a-z0-9-]*$"},
+    "version": {"type": "string", "pattern": "^v[1-9][0-9]*$"},
+    "bundle_digest": {"type": "string", "pattern": "^sha256:[a-f0-9]{64}$"},
+    "package_ref": {"type": "string", "minLength": 1},
+    "source_delivery_record_ref": {"type": "string", "minLength": 1},
+    "source_delivery_record_sha256": {"type": "string", "pattern": "^sha256:[a-f0-9]{64}$"},
+    "target_context_digest": {"type": "string", "pattern": "^sha256:[a-f0-9]{64}$"},
+    "target_profile_id": {"type": "string", "minLength": 1},
+    "selected_consumer_capabilities": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {"enum": ["backend-technical-design", "frontend-engineering-design", "delivery-coordination"]}
+    },
+    "routes": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["route_id", "capability", "activation", "artifact_refs"],
+        "properties": {
+          "route_id": {"type": "string", "pattern": "^route\\.[a-z0-9][a-z0-9-]*$"},
+          "capability": {"enum": ["backend-technical-design", "frontend-engineering-design", "delivery-coordination"]},
+          "activation": {"enum": ["required", "optional", "not-applicable"]},
+          "artifact_refs": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"type": "string", "minLength": 1}}
+        }
+      }
+    },
+    "status": {"const": "pending-context-reconciliation"},
+    "ready_for_agent": {"const": false}
+  }
+}

package/template/docs/process/strategic-handoff-package.md

@@ -1,12 +1,12 @@
 # 战略交接快照包
 
-本合同用于批准后的战略交付和研发接收，不增加生命周期阶段或门禁。`scripts/strategic-handoff` 是统一入口；Node 22+、Python 3 和现有 `jsonschema` 环境即可运行，不下载依赖、不执行交接包中的代码。包 schema 与导出配置见同目录 `schemas/strategic-handoff-package.schema.json`、`schemas/strategic-handoff-export.schema.json`（历史 v1）与 `schemas/strategic-handoff-export-v2.schema.json`（Handoff v5）。源规则仍由战略合同持有，索引与快照不成为第二套事实源。
+本合同用于批准后的战略交付和研发接收，不增加生命周期阶段或门禁。`scripts/strategic-handoff` 是统一入口；Node 22+、Python 3 和现有 `jsonschema` 环境即可运行，不下载依赖、不执行交接包中的代码。新交付统一使用 Handoff v5，并生成 `Strategic Delivery Bundle`；交付记录、验证记录、逻辑包和可选 ZIP 的 schema 分别见 `schemas/strategic-handoff-delivery.schema.json`、`schemas/strategic-handoff-delivery-verification.schema.json`、`schemas/strategic-handoff-package.schema.json`。源规则仍由战略合同持有，README、索引与快照不成为第二套事实源。
 
 ## 源资产准备
 
 1. 源仓必须为 `project-instance`。新交付使用 Domain Strategy v3 与 Stage Decision Package v3；规则、场景、决定、假设、约束、成功标准、测试 seam 与 downstream mapping 使用稳定 ID 和证据。v2 仅用于历史 Handoff v3 的只读验证；修改或重发须显式迁移、重新批准。不得用行号、文字 hash 或导出顺序生成业务身份。
 2. 每个场景明确 `critical`、`rule_refs`、`success_results` 和既有 `failure_results`；兼容字段 `rules` 必须与引用规则正文一致。不变量使用 `rule_ref`，并通过 `scenario_refs` 指向确实覆盖该规则的场景。缺身份或关联先回战略方确认、更新并重新批准，导出器不猜测。
-3. 新的既有 UI 交接使用 Handoff v5；原型交付可继续使用 Handoff v4 或显式使用 v5 的 prototype 分支。历史 Handoff v3/v4 按各自冻结 schema 和来源语义严格验证，不原地升级。校验器先读取 `schema_version` 再选择固定 schema，未知版本输出支持列表并 fail closed。`package_export` 的 `approvals` 按 `source` 字段及 `handoff` 绑定批准记录，声明 `record_ref`、`gate_id`、`digest_kind`。沿用源角色表的现有门禁；当前综合模板的战略、阶段决策及交接资产统一绑定 `gate.plan-approved`，Spec 对应 Spec 基线批准，原型和视觉基线对应 `gate.product-design-approved`；历史包及其他源 profile 仍按包内明确登记的源批准规则验证，不自动迁移当前门禁状态。
+3. 新原型与既有 UI 交接都使用 Handoff v5，分别选择 `prototype` 或 `existing-ui-baseline`。历史 Handoff v3/v4 与既有裸 v5 包继续按冻结 schema 执行 `verify/import`，但 v3/v4 不再创建新 export；修改或重新交付必须迁移到 v5 并重新批准。校验器先读取 `schema_version` 再选择固定 schema，未知版本输出支持列表并 fail closed。`package_export` 的 `approvals` 按 `source` 字段及 `handoff` 绑定批准记录，声明 `record_ref`、`gate_id`、`digest_kind`。沿用源角色表的现有门禁；当前综合模板的战略、阶段决策及交接资产统一绑定 `gate.plan-approved`，Spec 对应 Spec 基线批准，原型和视觉基线对应 `gate.product-design-approved`；历史包及其他源 profile 仍按包内明确登记的源批准规则验证，不自动迁移当前门禁状态。
 4. 批准记录除既有会签字段，还要在 `artifact_bindings` 中逐项绑定 `{id, version, digest}`。战略/阶段建议 `canonical-json`；普通文件使用 `sha256-bytes`；视觉基线使用 `visual-baseline`。正文中的 `approved` 和可读取批准路径不能替代当前字节的批准绑定。源角色表要求用户决定记录时，接收端必须支持并核验该策略；旧工具缺少该能力时阻断并要求升级，不能按旧规则放行。
 5. `additional_files` 明确补充依赖；`reference_map` 将 `evidence.*` 稳定证据引用解析为仓内路径。源资产、批准记录、证据引用、Markdown 本地链接和显式目录共同形成依赖闭包。HTTP 引用保留为引用，不在导出时下载网页。
 6. 原型分支的 `prototype` 指定 `profile`、`preview_root`、`entry_ref`、`verification_ref`、`verification_digest`（验证记录的字节摘要）；H2 另须 `source_root`、`lock_ref` 和 `source_digest`（源码目录树摘要，算法同下述预览树）。源码交付目录不含 node_modules / .git；锁文件与源码一同保存。预览目录须资源闭合，可通过本地静态服务离线浏览。源码、锁文件或验证记录变化须更新交接摘要并重新批准。
@@ -17,12 +17,29 @@
 以下路径参数由当前资产提供，不从目录 glob 猜测业务含义。
 
 ```bash
-scripts/strategic-handoff export --source-root <战略项目根> --handoff <仓内交接文件> --output <新目录> --zip
-scripts/strategic-handoff export --source-root <战略项目根> --handoff <新版本交接文件> --output <新目录> --previous <上一目录或ZIP> --zip
-scripts/strategic-handoff verify --bundle <目录或ZIP>
-scripts/strategic-handoff import --bundle <目录或ZIP> --target-root <研发项目根>
+scripts/strategic-handoff finalize --source-root <战略项目根> --handoff <Handoff-v5相对路径> [--previous <上一交付目录或package>] [--zip]
+scripts/strategic-handoff verify --bundle <交付目录|package目录|历史ZIP>
+scripts/strategic-handoff import --bundle <交付目录|package目录|历史ZIP> --target-root <研发项目根>
 ```
 
+生命周期在交接批准后自动调用 `finalize`，不要求业务用户提供 `--output`。固定输出为：
+
+```text
+docs/deliveries/strategic/<handoff-id>/<version>/
+  delivery-record.json
+  verification.json
+  package/
+    README.md
+    manifest.json
+    payload/
+    indexes/
+  package.zip  # 仅 --zip 时生成
+```
+
+`package/` 是权威不可变交付件。相同 ID/version 且逻辑摘要一致时重新整包验证并返回 `already-packaged`；内容不一致返回 `delivery-version-conflict`，必须提升版本。README 由工具确定性生成，只列范围、来源引用、消费者、待决项和接收命令，不复制业务正文。ZIP 只负责运输，不参与逻辑版本判定，也不要求提交 Git。
+
+战略 checkpoint 不新增产物 ID：`artifact.strategic-design-handoff.ref` 继续指向批准的 Handoff v5，其 `evidence_refs` 必须同时包含交付目录内的 `delivery-record.json` 与 `verification.json`。`verification.strategic_delivery` 记录实际命令、`exit_code: 0`、`result: verified` 和同一 `bundle_digest`。缺记录、包缺失、摘要漂移或验证失败时，`work-unit.strategic-design-handoff` 保持 `blocked`；已成包并验证通过后允许阶段完成，不等待后端或前端 Import Receipt。
+
 目录是逻辑包；ZIP 只负责运输。源资产原始字节进入 payload，清单以 `original_ref → path` 映射原路径到包内路径；v3/v4 的原 Handoff 保存在 `handoff.yaml`，源根词汇表保存为 `payload/source-context.snapshot.md`。v5 的原文件映射为 `payload/files/<original_ref>`，只有根词汇表使用固定物理别名 `payload/files/source-context.snapshot.md`；该别名不成为第二个根词汇表。包中不创建嵌套 `CONTEXT.md`。常规独立验包时工具在临时目录重建验证视图，完成后清理；不把临时源词汇表注册为目标权威。
 
 `manifest.json` 的 `files` 声明所有文件的字节摘要和大小。`bundle_digest` 是删除自身字段后 canonical JSON 的 SHA-256；不把整 ZIP 摘要当逻辑版本摘要。目录与 ZIP 的逻辑摘要相同。源合同的既有语义 digest 另行复核。目录/ZIP 已存在时拒绝覆盖，同身份版本不同内容的导入拒绝；已验过且相同的重复导入返回 `already-imported`。限制为 20,000 文件、512 MiB 展开内容；拒绝 ZIP 路径穿越、重复路径、大小写碰撞和符号链接。
@@ -35,7 +52,7 @@ Handoff v5 必须声明 `ui_baseline_kind: prototype | existing-ui-baseline`，`
 
 初始化和构建前运行 `scripts/preflight-delivery --input <输入清单> --stage prepare|build|export|accept --json`；完整阶段语义见 [交付预检](delivery-preflight.md)。`openBundle(...,{readOnly:true})` 对已展开 v5 包以固定别名映射核验，不写临时源目录、不执行来源代码；ZIP 返回 `readonly-extraction-required`，旧布局返回 `readonly-source-layout-required`，均不得视为验证通过。实际导出和接收仍在执行边界重新校验。
 
-## Handoff v4/v5 消费者路由
+## Handoff v5 消费者路由
 
 `consumer_routes` 固定表达三种能力，不绑定仓名：`backend-technical-design`、`frontend-engineering-design`、`delivery-coordination`。每条路由记录稳定 `route_id`、`required | optional | not-applicable`、影响引用、入口工作单元、预期输出、依赖和 Context Reconciliation 要求；`optional` / `not-applicable` 必须有原因与证据，不能产生 `ready-for-agent`。
 
@@ -45,7 +62,7 @@ Handoff v5 必须声明 `ui_baseline_kind: prototype | existing-ui-baseline`，`
 
 ## 下游接收与逐条追溯
 
-导入落盘到 `docs/handoffs/<handoff-id>/<version>/`。Handoff v3 继续生成 Import Receipt v1 和原固定文件名；Handoff v4/v5 生成 Import Receipt v2，按目标 profile 的消费者能力登记 route、产物引用和状态，并分别生成后端追踪、Frontend Strategic Preflight / 前端追踪、协调状态索引草案。共同生成 route-aware Context Reconciliation 和 upstream impact 草案。仅写快照与草案，不自动更新根词汇表或批准状态。目标侧确认增量后更新唯一根 `CONTEXT.md` 并完成正式 reconciliation。
+导入落盘到 `docs/handoffs/<handoff-id>/<version>/`。Handoff v3 继续生成 Import Receipt v1；历史裸 Handoff v4/v5 包继续生成 Import Receipt v2。新的 v5 交付目录生成 Import Receipt v3，保存源 `delivery-record.json` 原始字节及摘要，按目标 profile 的消费者能力登记 route、产物引用和状态，并分别生成后端追踪、Frontend Strategic Preflight / 前端追踪、协调状态索引草案。共同生成 route-aware Context Reconciliation 和 upstream impact 草案，所有入口固定 `ready_for_agent: false`。接收回执由研发仓持有，不反向修改战略仓；协调索引只保存回执引用。目标侧确认增量后更新唯一根 `CONTEXT.md` 并完成正式 reconciliation。
 
 Technical Design Contract v2（DDD / MVC 共用）的 `strategic_handoff` 绑定 `import_receipt_ref`、`bundle_digest`、`context_reconciliation_ref` 和 `rows`。逐条覆盖全部规则与 `critical: true` 的成功/失败场景；行字段如下：
 
@@ -61,7 +78,7 @@ scripts/verify-strategic-handoff-consumption --root <研发项目根> --slice <
 node .agents/skills/yss-technical-design/scripts/validate-technical-design.mjs <技术设计合同> --root <研发项目根>
 ```
 
-Handoff v4/v5 后端消费必须绑定 `backend-technical-design` 的 `route_id`，先对账，再由 `yss-technical-design` 依据已批准架构调用 `yss-tactical-design` 或 `yss-mvc-design`。Handoff v3 的 `yss-technical-design` / `yss-tactical-design` 单目标组合只读兼容，不修改已冻结包。`tactical_refs` 在 v2 Technical Design 可指向 MVC 或 DDD 分支对象；无战略交接包的 MVC 项目直接消费批准需求，不补造战略 DDD。
+Handoff v4/v5 后端消费必须绑定 `backend-technical-design` 的 `route_id`，先对账，再由 `yss-technical-design` 依据已批准架构调用 `yss-tactical-design` 或 `yss-mvc-design`。Handoff v3/v4 仅作历史只读兼容，不修改已冻结包。`tactical_refs` 在 v2 Technical Design 可指向 MVC 或 DDD 分支对象；无战略交接包的 MVC 项目直接消费批准需求，不补造战略 DDD。
 
 前端先验证与交接版本匹配的 Strategic Preflight：Handoff v4 使用 v1，Handoff v5 使用 v2 的 `ui_baseline_kind/ui_baseline_ref`，只允许起草前端工程设计与实现计划，固定返回 `ready_for_agent: false`。最终 Frontend Delivery Acceptance v2（Handoff v4）或 v3（Handoff v5）在 Backend/API/Data 有影响时必须绑定真实 Backend Delivery 收据与版本探测；UI-only 时使用与战略路由一致的 `backend-not-applicable`，此时 `operation_ids` 必须为空。无论哪条路径，当前且已批准的 Slice Contract 仍是实现入口。
 

package/template/docs/user-guide//350/256/276/345/244/207/345/200/237/347/224/250/350/264/257/347/251/277/346/241/210/344/276/213.md

@@ -35,7 +35,7 @@
 
 ```bash
 node scripts/preflight-delivery --input <战略预检输入.json> --stage export --json
-node scripts/strategic-handoff export --source-root . --handoff <交接描述相对路径> --output <新包目录> --zip
+node scripts/strategic-handoff finalize --source-root . --handoff <Handoff-v5相对路径> --zip
 node scripts/strategic-handoff verify --bundle <包目录或ZIP>
 ```
 

package/template/scripts/audit-legacy-backend-scaffold

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import process from "node:process";
+import { auditLegacyBackendScaffold } from "./lib/legacy-backend-scaffold-audit.mjs";
+
+function parse(argv) {
+  const options = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === "--project-root") options.projectRoot = argv[++index];
+    else if (token === "--manifest-ref") options.manifestRef = argv[++index];
+    else if (token === "--help" || token === "-h") options.help = true;
+    else throw new TypeError(`不支持的参数: ${token}`);
+  }
+  if (!options.help && !options.projectRoot) throw new TypeError("缺少 --project-root");
+  return options;
+}
+
+try {
+  const options = parse(process.argv.slice(2));
+  if (options.help) process.stdout.write("用法: scripts/audit-legacy-backend-scaffold --project-root <path> [--manifest-ref .yss/scaffold-generation.json]\n");
+  else {
+    const result = await auditLegacyBackendScaffold(options.projectRoot, { manifestRef: options.manifestRef });
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    if (result.status === "blocked") process.exitCode = 2;
+  }
+} catch (error) {
+  process.stderr.write(`❌ 历史后端脚手架审计失败: ${error.message}\n`);
+  process.exitCode = 1;
+}

package/template/scripts/lib/api-contract-decision.mjs

@@ -0,0 +1,49 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseDocument } from "../vendor/yaml.mjs";
+import { validateJsonSchema } from "./json-schema.mjs";
+import { openApiDigest, resolveOpenApiRef, validateOpenApiDraftValidationRecord } from "./openapi-draft-validation.mjs";
+
+const TEMPLATE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+const SCHEMA = path.join(TEMPLATE_ROOT, "docs/process/schemas/api-contract-decision.schema.json");
+const fail = (message) => { throw new TypeError(message); };
+const readBound = (root, ref, label) => {
+  const file = resolveOpenApiRef(root, ref);
+  const bytes = readFileSync(file);
+  return { file, bytes, digest: openApiDigest(bytes), label };
+};
+const requireDigest = (asset, expected) => { if (asset.digest !== expected) fail(`${asset.label}摘要漂移`); };
+
+export function validateApiContractDecision(binding, { root = TEMPLATE_ROOT } = {}) {
+  if (!binding || !binding.ref || !binding.version || !binding.digest || !["required", "not-applicable"].includes(binding.impact)) fail("缺少 API Contract Decision 当前版本绑定");
+  const projectRoot = path.resolve(root);
+  const decisionAsset = readBound(projectRoot, binding.ref, "API Contract Decision");
+  requireDigest(decisionAsset, binding.digest);
+  const document = parseDocument(decisionAsset.bytes.toString("utf8"), { uniqueKeys: true, maxAliasCount: 0 });
+  if (document.errors.length) fail(`API Contract Decision 无法解析: ${document.errors[0].message}`);
+  const decision = document.toJS({ maxAliasCount: 0 });
+  validateJsonSchema(decision, SCHEMA, { cwd: TEMPLATE_ROOT, label: "API Contract Decision v1" });
+  if (decision.decision_version !== binding.version || decision.impact !== binding.impact) fail("API Contract Decision 版本或影响结论与合同不一致");
+  requireDigest(readBound(projectRoot, decision.assessment_ref, "API 影响评估"), decision.assessment_digest);
+  for (const ref of decision.evidence_refs) readBound(projectRoot, ref, "API Decision 证据");
+  if (decision.impact === "not-applicable") return { decision, binding: { ref: binding.ref, version: binding.version, digest: binding.digest, impact: decision.impact } };
+
+  const draft = readBound(projectRoot, decision.openapi.ref, "OpenAPI YAML");
+  requireDigest(draft, decision.openapi.digest);
+  const validation = readBound(projectRoot, decision.validation_record.ref, "OpenAPI Validation");
+  requireDigest(validation, decision.validation_record.digest);
+  const review = readBound(projectRoot, decision.draft_review.ref, "OpenAPI Draft Review");
+  requireDigest(review, decision.draft_review.digest);
+  const reviewDocument = parseDocument(review.bytes.toString("utf8"), { uniqueKeys: true, maxAliasCount: 0 });
+  if (reviewDocument.errors.length) fail(`OpenAPI Draft Review 无法解析: ${reviewDocument.errors[0].message}`);
+  const reviewRecord = reviewDocument.toJS({ maxAliasCount: 0 });
+  if (reviewRecord?.result !== "approved" || !Array.isArray(reviewRecord.blocking_findings) || reviewRecord.blocking_findings.length > 0) fail("OpenAPI Draft Review 实际记录未批准或仍有阻断项");
+  if (reviewRecord.draft_ref !== decision.openapi.ref || reviewRecord.draft_digest !== decision.openapi.digest) fail("OpenAPI Draft Review 实际记录未绑定当前权威 YAML");
+  for (const ref of decision.draft_review.evidence_refs) readBound(projectRoot, ref, "OpenAPI Draft Review 证据");
+  const validated = validateOpenApiDraftValidationRecord(validation.file, { root: projectRoot });
+  if (validated.record.draft.ref !== decision.openapi.ref || validated.draftDigest !== decision.openapi.digest) fail("OpenAPI Validation 未绑定当前权威 YAML");
+  if (decision.draft_review.draft_ref !== decision.openapi.ref || decision.draft_review.draft_digest !== decision.openapi.digest || decision.draft_review.blocking_findings.length) fail("OpenAPI Draft Review 未批准当前权威 YAML");
+  if (decision.freeze.version !== decision.openapi.version || decision.freeze.draft_ref !== decision.openapi.ref || decision.freeze.draft_digest !== decision.openapi.digest) fail("OpenAPI Freeze 未绑定当前权威 YAML 版本和摘要");
+  return { decision, openapi: decision.openapi, binding: { ref: binding.ref, version: binding.version, digest: binding.digest, impact: decision.impact } };
+}

package/template/scripts/lib/api-contract-decision.test.mjs

@@ -0,0 +1,69 @@
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { validateApiContractDecision } from "./api-contract-decision.mjs";
+
+const digest = (bytes) => `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+
+function write(root, ref, value) {
+  const file = path.join(root, ref);
+  mkdirSync(path.dirname(file), { recursive: true });
+  writeFileSync(file, typeof value === "string" ? value : `${JSON.stringify(value, null, 2)}\n`);
+  return { ref, file, digest: digest(readFileSync(file)) };
+}
+
+function notApplicableFixture() {
+  const root = mkdtempSync(path.join(os.tmpdir(), "api-contract-decision-"));
+  const assessment = write(root, "api-impact.json", { api: false, project_id: "demo" });
+  const evidence = write(root, "api-impact-evidence.md", "无 API 影响证据。\n");
+  const decision = {
+    schema_version: 1,
+    kind: "api-contract-decision",
+    decision_id: "api-contract.demo",
+    decision_version: "v1",
+    status: "approved",
+    current_version: true,
+    impact: "not-applicable",
+    assessment_ref: assessment.ref,
+    assessment_digest: assessment.digest,
+    evidence_refs: [evidence.ref],
+    reason: "不新增或修改 HTTP、消息或集成接口",
+  };
+  const asset = write(root, "api-contract-decision.json", decision);
+  return { root, assessment, evidence, decision, asset, binding: { ref: asset.ref, version: "v1", digest: asset.digest, impact: "not-applicable" } };
+}
+
+test("API not-applicable 决定必须绑定影响评估、原因和可读证据", () => {
+  const data = notApplicableFixture();
+  try {
+    assert.equal(validateApiContractDecision(data.binding, { root: data.root }).decision.impact, "not-applicable");
+    for (const mutation of [
+      (value) => { delete value.reason; },
+      (value) => { value.evidence_refs = []; },
+      (value) => { value.openapi = { id: "openapi.demo", ref: "empty.yaml", version: "v1", digest: `sha256:${"0".repeat(64)}` }; },
+    ]) {
+      const value = structuredClone(data.decision);
+      mutation(value);
+      const changed = write(data.root, "api-contract-decision.json", value);
+      assert.throws(() => validateApiContractDecision({ ...data.binding, digest: changed.digest }, { root: data.root }));
+    }
+  } finally {
+    rmSync(data.root, { recursive: true, force: true });
+  }
+});
+
+test("API Decision 或影响评估原始字节漂移即失效", () => {
+  const data = notApplicableFixture();
+  try {
+    writeFileSync(data.asset.file, "\n", { flag: "a" });
+    assert.throws(() => validateApiContractDecision(data.binding, { root: data.root }), /摘要漂移/);
+    const restored = write(data.root, data.asset.ref, data.decision);
+    writeFileSync(data.assessment.file, "\n", { flag: "a" });
+    assert.throws(() => validateApiContractDecision({ ...data.binding, digest: restored.digest }, { root: data.root }), /摘要漂移/);
+  } finally {
+    rmSync(data.root, { recursive: true, force: true });
+  }
+});

package/template/scripts/lib/backend-scaffold-prerequisites.mjs

@@ -0,0 +1,123 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { parseDocument } from "../vendor/yaml.mjs";
+import { loadApprovalRecord, validateApprovalRecord } from "./approval-record.mjs";
+import { validateJsonSchema } from "./json-schema.mjs";
+import { ROOT } from "./lifecycle-registry.mjs";
+import { validateTechnicalDesign } from "../../.agents/skills/yss-technical-design/scripts/validate-technical-design.mjs";
+import { validateApiContractDecision } from "./api-contract-decision.mjs";
+
+const DATA_DECISION_SCHEMA = path.join(ROOT, "docs/process/schemas/data-architecture-decision.schema.json");
+
+const fail = (message) => { throw new TypeError(message); };
+const digest = (bytes) => `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+const text = (value) => typeof value === "string" && value.trim().length > 0;
+
+function resolveLocalRef(root, ref, label) {
+  if (!text(ref) || /^[a-z][a-z0-9+.-]*:\/\//i.test(ref)) fail(`${label} 必须是可读取的本地文件引用`);
+  const resolved = path.isAbsolute(ref) ? path.normalize(ref) : path.resolve(root, ref);
+  if (!existsSync(resolved)) fail(`${label} 不可读取: ${ref}`);
+  return resolved;
+}
+
+export function findGovernanceRoot(contractFile) {
+  let current = path.dirname(path.resolve(contractFile));
+  const fallback = current;
+  while (true) {
+    if (existsSync(path.join(current, "yss-project.yaml"))) return current;
+    const parent = path.dirname(current);
+    if (parent === current) return fallback;
+    current = parent;
+  }
+}
+
+function readDocument(root, binding, label) {
+  if (!binding || !text(binding.ref) || !text(binding.digest)) fail(`${label} 缺少 ref/digest`);
+  const file = resolveLocalRef(root, binding.ref, label);
+  const bytes = readFileSync(file);
+  if (digest(bytes) !== binding.digest) fail(`${label} 原始字节摘要漂移`);
+  const document = parseDocument(bytes.toString("utf8"), { maxAliasCount: 0, uniqueKeys: true });
+  if (document.errors.length) fail(`${label} 无法解析: ${document.errors[0].message}`);
+  const value = document.toJS({ maxAliasCount: 0 });
+  if (!value || typeof value !== "object" || Array.isArray(value)) fail(`${label} 必须是对象`);
+  return { file, bytes, value };
+}
+
+function requireReadableRefs(root, refs, label) {
+  if (!Array.isArray(refs) || refs.length === 0) fail(`${label} 必须包含可读取证据`);
+  for (const ref of refs) resolveLocalRef(root, ref, label);
+}
+
+function requireArtifactBinding(record, expected, label) {
+  const binding = (record.artifact_bindings || []).find((item) => item?.id === expected.id);
+  if (!binding || binding.version !== expected.version || binding.digest !== expected.digest) fail(`${label} 未绑定当前资产版本和摘要`);
+}
+
+function requireExactBinding(actual, expected, label, { impact = false, id = false } = {}) {
+  const keys = ["ref", "version", "digest", ...(impact ? ["impact"] : []), ...(id ? ["id"] : [])];
+  if (!actual || keys.some((key) => actual[key] !== expected[key])) fail(`${label} 未原子绑定当前资产`);
+}
+
+function requireEngineeringPackage(root, approval, contract, technical, data, api, prerequisites) {
+  const packageFile = resolveLocalRef(root, approval.subject_ref, "工程合同批准主体");
+  const packageDocument = parseDocument(readFileSync(packageFile, "utf8"), { maxAliasCount: 0, uniqueKeys: true });
+  if (packageDocument.errors.length) fail(`工程合同批准主体无法解析: ${packageDocument.errors[0].message}`);
+  const value = packageDocument.toJS({ maxAliasCount: 0 });
+  if (value?.schema_version !== 1 || value?.kind !== "engineering-contract-package" || value?.project_id !== contract.project_name) fail("工程合同批准主体必须是当前项目的 engineering-contract-package v1");
+  requireExactBinding(value.technical_design, { ...prerequisites.technical_design, version: technical.value.version }, "工程合同包 Technical Design");
+  requireExactBinding(value.data_architecture_decision, { ...prerequisites.data_architecture_decision, version: data.value.decision_version, impact: data.value.impact }, "工程合同包 Data Architecture Decision", { impact: true });
+  requireExactBinding(value.api_contract_decision, { ...prerequisites.api_contract_decision, version: api.decision.decision_version, impact: api.decision.impact }, "工程合同包 API Contract Decision", { impact: true });
+  if (api.decision.impact === "required") {
+    requireExactBinding(value.frozen_openapi, api.decision.openapi, "工程合同包冻结 OpenAPI", { id: true });
+  } else if (Object.hasOwn(value, "frozen_openapi")) {
+    fail("API not-applicable 的工程合同包禁止携带 frozen_openapi 占位字段");
+  }
+}
+
+export async function validateBackendScaffoldPrerequisites(contract, { contractFile, root = findGovernanceRoot(contractFile) } = {}) {
+  if (contract?.schema_version !== 4 || contract?.delivery_role !== "backend") fail("后端新生成只接受 Project Scaffold Contract v4");
+  const prerequisites = contract.design_prerequisites;
+  if (!prerequisites || typeof prerequisites !== "object") fail("后端脚手架合同缺少 design_prerequisites");
+
+  const technical = readDocument(root, prerequisites.technical_design, "Technical Design");
+  if (technical.value.schema_version !== 2 || technical.value.status !== "approved" || technical.value.version !== prerequisites.technical_design.version) fail("Technical Design 必须是 approved 的当前 v2 合同");
+  if (technical.value.architecture?.family !== contract.architecture_family || technical.value.architecture?.project_id !== contract.project_name || technical.value.architecture?.decision_digest !== contract.decision_digest) fail("Technical Design 与脚手架架构决定不一致");
+  await validateTechnicalDesign(technical.value, { root });
+
+  const data = readDocument(root, prerequisites.data_architecture_decision, "数据架构决定");
+  validateJsonSchema(data.value, DATA_DECISION_SCHEMA, { label: "Data Architecture Decision v1" });
+  if (data.value.decision_version !== prerequisites.data_architecture_decision.version) fail("数据架构决定版本不匹配");
+  const assessment = resolveLocalRef(root, data.value.assessment_ref, "数据影响评估");
+  if (digest(readFileSync(assessment)) !== data.value.assessment_digest) fail("数据影响评估摘要漂移");
+  requireReadableRefs(root, data.value.evidence_refs, "数据架构决定证据");
+  if (data.value.impact === "required") {
+    const architecture = resolveLocalRef(root, data.value.data_architecture_ref, "数据架构文档");
+    if (digest(readFileSync(architecture)) !== data.value.data_architecture_digest) fail("数据架构文档摘要漂移");
+    requireReadableRefs(root, data.value.review_evidence_refs, "数据架构评审证据");
+  }
+
+  const api = validateApiContractDecision(prerequisites.api_contract_decision, { root });
+
+  const approvalRef = prerequisites.engineering_contract_approval_ref;
+  if (approvalRef !== contract.lifecycle_approval_ref || approvalRef !== contract.approval?.approval_ref) fail("工程合同批准引用与脚手架合同不一致");
+  const approvalFile = resolveLocalRef(root, approvalRef, "工程合同批准记录");
+  const approval = loadApprovalRecord(approvalFile);
+  validateApprovalRecord(approval, { requireApproved: true, root });
+  if (approval.gate_id !== "gate.engineering-contract-approved") fail("工程合同批准记录 gate_id 必须为 gate.engineering-contract-approved");
+  if (!Array.isArray(approval.approval_scope) || !approval.approval_scope.includes(contract.contract_id) || !approval.approval_scope.includes(contract.project_name)) fail("工程合同批准范围未覆盖当前合同和项目");
+  requireEngineeringPackage(root, approval, contract, technical, data, api, prerequisites);
+  requireArtifactBinding(approval, { id: technical.value.technical_design_id, version: technical.value.version, digest: prerequisites.technical_design.digest }, "工程合同批准记录");
+  requireArtifactBinding(approval, { id: data.value.decision_id, version: data.value.decision_version, digest: prerequisites.data_architecture_decision.digest }, "工程合同批准记录");
+  requireArtifactBinding(approval, { id: api.decision.decision_id, version: api.decision.decision_version, digest: prerequisites.api_contract_decision.digest }, "工程合同批准记录");
+  if (api.decision.impact === "required") {
+    requireArtifactBinding(approval, { id: api.decision.openapi.id, version: api.decision.openapi.version, digest: api.decision.openapi.digest }, "工程合同批准记录");
+  }
+
+  return {
+    technical_design: { ref: prerequisites.technical_design.ref, version: technical.value.version, digest: prerequisites.technical_design.digest },
+    data_architecture_decision: { ref: prerequisites.data_architecture_decision.ref, version: data.value.decision_version, digest: prerequisites.data_architecture_decision.digest, impact: data.value.impact },
+    api_contract_decision: { ref: prerequisites.api_contract_decision.ref, version: api.decision.decision_version, digest: prerequisites.api_contract_decision.digest, impact: api.decision.impact },
+    engineering_contract_approval_ref: approvalRef,
+  };
+}

package/template/scripts/lib/legacy-backend-scaffold-audit.mjs

@@ -0,0 +1,87 @@
+import { createHash } from "node:crypto";
+import { lstat, readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+
+const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
+const normalizedDigest = (value) => String(value ?? "").replace(/^sha256:/, "");
+
+async function collectFiles(root) {
+  const files = [];
+  async function visit(directory) {
+    for (const entry of (await readdir(directory, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+      if ([".git", "target", "node_modules"].includes(entry.name)) continue;
+      const target = path.join(directory, entry.name);
+      const relative = path.relative(root, target).split(path.sep).join("/");
+      if (entry.isDirectory()) await visit(target);
+      else files.push({ relative, target, symlink: entry.isSymbolicLink() });
+    }
+  }
+  await visit(root);
+  return files;
+}
+
+function isBusinessFile(relative, manifest) {
+  if (relative === manifest.bootstrap_main_source || /(^|\/)package-info\.java$/.test(relative)) return false;
+  return /(^|\/)src\/(main|test)\/java\/.+\.java$/.test(relative)
+    || /(^|\/)src\/main\/resources\/.+\.(sql|xml|ya?ml|properties)$/.test(relative)
+    || /(^|\/)(db|mapper|repository|controller|domain)(\/|$)/i.test(relative)
+    || /(^|\/)(Controller|Repository|Mapper|Aggregate|Entity)\.java$/i.test(relative);
+}
+
+export async function auditLegacyBackendScaffold(projectRoot, { manifestRef = ".yss/scaffold-generation.json" } = {}) {
+  const root = path.resolve(projectRoot);
+  const manifestFile = path.resolve(root, manifestRef);
+  const relativeManifest = path.relative(root, manifestFile);
+  if (relativeManifest.startsWith("..") || path.isAbsolute(relativeManifest)) throw new TypeError("Manifest 必须位于项目根内");
+  const manifestBytes = await readFile(manifestFile).catch(() => { throw new TypeError(`Manifest 不可读取: ${manifestRef}`); });
+  let manifest;
+  try { manifest = JSON.parse(manifestBytes); } catch { throw new TypeError("Manifest 必须是 JSON 对象"); }
+  if (manifest?.schema_version !== 3) throw new TypeError("恢复审计只接受历史 v3 Manifest");
+  if (!Array.isArray(manifest?.ownership?.generated_files)) throw new TypeError("历史 v3 Manifest 缺少 ownership.generated_files");
+
+  const generated = new Map(manifest.ownership.generated_files.map((entry) => [entry.path, entry]));
+  const generatedFileDrift = [];
+  for (const [relative, entry] of generated) {
+    const target = path.resolve(root, relative);
+    const inside = path.relative(root, target);
+    if (inside.startsWith("..") || path.isAbsolute(inside)) {
+      generatedFileDrift.push({ path: relative, reason: "path-outside-project" });
+      continue;
+    }
+    try {
+      const info = await lstat(target);
+      if (!info.isFile()) generatedFileDrift.push({ path: relative, reason: "not-a-regular-file" });
+      else {
+        const actual = sha256(await readFile(target));
+        if (actual !== normalizedDigest(entry.sha256)) generatedFileDrift.push({ path: relative, reason: "digest-drift", expected: normalizedDigest(entry.sha256), actual });
+      }
+    } catch (error) {
+      if (error.code === "ENOENT") generatedFileDrift.push({ path: relative, reason: "missing" });
+      else throw error;
+    }
+  }
+
+  const files = await collectFiles(root);
+  const unownedFiles = files.map((entry) => entry.relative).filter((relative) => relative !== manifestRef && !generated.has(relative));
+  const businessFiles = files
+    .filter((entry) => entry.symlink || (unownedFiles.includes(entry.relative) && isBusinessFile(entry.relative, manifest)))
+    .map((entry) => entry.relative);
+  const premature = businessFiles.length > 0;
+  const state = premature ? "premature-implementation-detected" : generatedFileDrift.length > 0 ? "generated-file-drift" : "unchanged-mechanical-scaffold";
+  return {
+    schema_version: 1,
+    kind: "legacy-backend-scaffold-ownership-audit",
+    status: state === "unchanged-mechanical-scaffold" ? "reconcilable" : "blocked",
+    manifest_ref: manifestRef,
+    manifest_digest: `sha256:${sha256(manifestBytes)}`,
+    manifest_schema_version: 3,
+    ownership_state: state,
+    premature_implementation: premature,
+    generated_file_drift: generatedFileDrift,
+    business_files: businessFiles,
+    unowned_files: unownedFiles,
+    recovery_requirements: state === "unchanged-mechanical-scaffold"
+      ? ["approved-current-technical-design", "data-architecture-decision", "gate.engineering-contract-approved", "recovery-approval"]
+      : ["preserve-all-files", "design-reconciliation", "difference-review", "current-user-approval"],
+  };
+}