create-yss-spec 3.0.0 → 3.1.0

package/template/scripts/verify-scaffold-generator-scenarios

@@ -9,6 +9,7 @@ import sys
 import tempfile
 import json
 import os
+import hashlib
 from pathlib import Path
 
 
@@ -60,16 +61,66 @@ def write_contract(
     project_name: str,
     contract_id: str,
     approval_ref: str,
-    router_draft_ref: str,
+    compiler_draft_ref: str,
     persisted_ref: str,
 ) -> None:
+    decision_path = path.with_suffix(".architecture-decisions.yaml")
+    decision_id = f"scaffold-decision.{project_name}"
+    decision_text = json.dumps(
+        {
+            "schema_version": 1,
+            "kind": "scaffold-architecture-decisions",
+            "template": False,
+            "status": "current",
+            "decisions": [
+                {
+                    "decision_id": decision_id,
+                    "project_id": project_name,
+                    "parent_project_id": None,
+                    "status": "lifecycle-approved",
+                    "recommended_architecture": "domain-driven",
+                    "recommendation_reasons": ["场景验证固定使用 DDD"],
+                    "confirmed_architecture": "domain-driven",
+                    "override_reason": None,
+                    "inheritance_mode": "root-default",
+                    "inherited_from": None,
+                    "platform_profile": "spring-boot-2.7-jdk8",
+                    "architecture_profile": "target-domain-model",
+                    "verification_database": "h2",
+                    "production_database": "not-bound",
+                    "requested_capabilities": [],
+                    "resolved_modules": [
+                        "domain",
+                        "application",
+                        "infrastructure",
+                        "adapter",
+                        "bootstrap",
+                    ],
+                    "resolution_version": 1,
+                    "user_confirmation": {
+                        "confirmed_by": "scenario-runner",
+                        "channel": "test",
+                        "confirmation_ref": "test://scaffold-decision",
+                        "confirmed_at": "2026-09-05T00:00:00Z",
+                        "normalized_text": "确认使用 DDD",
+                    },
+                    "decision_inputs_digest": f"sha256:{'1' * 64}",
+                }
+            ],
+        },
+        ensure_ascii=False,
+        indent=2,
+    ) + "\n"
+    decision_path.write_text(decision_text, encoding="utf-8")
+    subprocess.run(["node", str(REPOSITORY_ROOT / "scripts/fixtures/user-decision/build-fixture.mjs"), "--scaffold", str(decision_path)], check=True, cwd=REPOSITORY_ROOT)
+    decision_text = decision_path.read_text(encoding="utf-8")
     contract = {
-        "schema_version": 2,
+        "schema_version": 3,
         "contract_id": contract_id,
         "contract_version": 1,
         "scaffold_request_id": f"{project_name}-request",
         "status": "approved",
-        "router_draft_ref": router_draft_ref,
+        "compiler_draft_ref": compiler_draft_ref,
         "lifecycle_approval_ref": approval_ref,
         "persisted_ref": persisted_ref,
         "current_version": 1,
@@ -79,6 +130,12 @@ def write_contract(
         "project_name": project_name,
         "target_output_dir": str(output_root),
         "base_package": f"com.yss.{project_name.removesuffix('-service')}",
+        "architecture_family": "domain-driven",
+        "architecture_profile": "target-domain-model",
+        "generator_skill": "yss-ddd-scaffold-generator",
+        "decision_ref": str(decision_path),
+        "decision_id": decision_id,
+        "decision_digest": f"sha256:{hashlib.sha256(decision_text.encode('utf-8')).hexdigest()}",
         "maven_coordinates": {
             "group_id": "com.yss.datamiddle",
             "project_version": "1.0.0-SNAPSHOT",
@@ -92,12 +149,24 @@ def write_contract(
         "profiles": {
             "architecture": "target-domain-model",
             "persistence": "mybatis-plus",
-            "database": "mysql",
+            "verification_database": "h2",
+            "production_database": "not-bound",
             "platform": "spring-boot-2.7-jdk8",
             "validation_namespace": "javax",
             "dto_placement": "web",
             "repository": "yss-internal",
         },
+        "module_profile": {
+            "resolution_version": 1,
+            "requested_capabilities": [],
+            "resolved_modules": [
+                "domain",
+                "application",
+                "infrastructure",
+                "adapter",
+                "bootstrap",
+            ],
+        },
         "allowed_write_paths": ["."],
         "expected_evidence_files": [
             f"{project_name}/.yss/scaffold-generation.json",
@@ -154,10 +223,12 @@ def assert_pure_scaffold(project_root: Path, contract_id: str) -> None:
     require(manifest["contract_id"] == contract_id, "生成清单必须记录脚手架合同 ID")
     require(manifest["contract_version"] == 1, "生成清单必须记录脚手架合同版本")
     require(manifest["approval_ref"], "生成清单必须记录生命周期批准引用")
-    require(manifest["router_draft_ref"], "生成清单必须记录 Router draft 引用")
+    require(manifest["compiler_draft_ref"], "生成清单必须记录 实现合同编译器 draft 引用")
     require(manifest["persisted_ref"], "生成清单必须记录合同持久化引用")
     require(manifest["generation_mode"] == "controlled-generation", "生成清单必须记录受控生成模式")
-    require(manifest["schema_version"] == 2, "生成清单必须使用 schema v2")
+    require(manifest["schema_version"] == 3, "新生成清单必须使用 schema v3")
+    require(manifest["architecture_family"] == "domain-driven", "生成清单必须记录已确认的 DDD 架构族")
+    require(manifest["generator_skill"] == "yss-ddd-scaffold-generator", "生成清单必须记录实际生成器")
     require(manifest["scaffold_request_id"], "生成清单必须记录服务级 scaffold_request_id")
     require("slice_id" not in manifest, "脚手架清单不得伪造 slice_id")
     require(manifest["maven_coordinates_source"] == "approved-contract", "Maven 坐标必须来自批准合同")
@@ -214,7 +285,7 @@ def main() -> int:
             "schemav1-service",
             "backend-scaffold-schema-v1",
             "lifecycle/approval-schema-v1",
-            "router/draft-schema-v1",
+            "compiler/draft-schema-v1",
             "lifecycle/contracts/backend-scaffold-schema-v1.yaml",
         )
         schema_v1_payload = json.loads(schema_v1_contract.read_text(encoding="utf-8"))
@@ -227,7 +298,7 @@ def main() -> int:
             "--contract-id", "backend-scaffold-schema-v1",
             "--contract-version", "1",
             "--approval-ref", "lifecycle/approval-schema-v1",
-            "--router-draft-ref", "router/draft-schema-v1",
+            "--compiler-draft-ref", "compiler/draft-schema-v1",
             "--persisted-ref", "lifecycle/contracts/backend-scaffold-schema-v1.yaml",
             "--contract-file", str(schema_v1_contract),
             "--group-id", "com.yss.datamiddle",
@@ -268,7 +339,7 @@ def main() -> int:
             "stale-service",
             "backend-scaffold-stale",
             "lifecycle/approval-stale",
-            "router/draft-stale",
+            "compiler/draft-stale",
             "lifecycle/contracts/backend-scaffold-stale.yaml",
         )
         stale_payload = json.loads(stale_contract.read_text(encoding="utf-8"))
@@ -287,8 +358,8 @@ def main() -> int:
             "1",
             "--approval-ref",
             "lifecycle/approval-stale",
-            "--router-draft-ref",
-            "router/draft-stale",
+            "--compiler-draft-ref",
+            "compiler/draft-stale",
             "--persisted-ref",
             "lifecycle/contracts/backend-scaffold-stale.yaml",
             "--contract-file",
@@ -303,7 +374,7 @@ def main() -> int:
             "pure-service",
             "backend-scaffold-000",
             "lifecycle/approval-000",
-            "router/draft-000",
+            "compiler/draft-000",
             "lifecycle/contracts/backend-scaffold-000.yaml",
         )
 
@@ -320,8 +391,8 @@ def main() -> int:
             "1",
             "--approval-ref",
             "lifecycle/approval-000",
-            "--router-draft-ref",
-            "router/draft-000",
+            "--compiler-draft-ref",
+            "compiler/draft-000",
             "--persisted-ref",
             "lifecycle/contracts/backend-scaffold-000.yaml",
             "--contract-file",
@@ -353,7 +424,7 @@ def main() -> int:
                     "contract_digest": "a" * 64,
                     "approval_ref": "lifecycle/verification",
                     "lifecycle_approval_ref": "lifecycle/verification",
-                    "router_draft_ref": "router/verification",
+                    "compiler_draft_ref": "router/verification",
                     "persisted_ref": "lifecycle/contracts/verification.yaml",
                     "contract_file_ref": "lifecycle/contracts/verification.json",
                     "current_version": 1,
@@ -501,7 +572,7 @@ def main() -> int:
         require(sentinel.read_text(encoding="utf-8") == "preserve me", "未批准覆盖不得改变原目录")
 
         force_contract = temp_root / "force-contract.json"
-        write_contract(force_contract, force_root, "force-service", "backend-scaffold-001", "lifecycle/approval-001", "router/draft-001", "lifecycle/contracts/backend-scaffold-001.yaml")
+        write_contract(force_contract, force_root, "force-service", "backend-scaffold-001", "lifecycle/approval-001", "compiler/draft-001", "lifecycle/contracts/backend-scaffold-001.yaml")
         approved_force_result = run_generator(
             "--project-name",
             "force-service",
@@ -516,8 +587,8 @@ def main() -> int:
             "1",
             "--approval-ref",
             "lifecycle/approval-001",
-            "--router-draft-ref",
-            "router/draft-001",
+            "--compiler-draft-ref",
+            "compiler/draft-001",
             "--persisted-ref",
             "lifecycle/contracts/backend-scaffold-001.yaml",
             "--contract-file",
@@ -553,7 +624,7 @@ def main() -> int:
             "gitlink-service",
             "backend-scaffold-gitlink",
             "lifecycle/approval-gitlink",
-            "router/draft-gitlink",
+            "compiler/draft-gitlink",
             "lifecycle/contracts/backend-scaffold-gitlink.yaml",
         )
         gitlink_result = run_generator(
@@ -569,8 +640,8 @@ def main() -> int:
             "1",
             "--approval-ref",
             "lifecycle/approval-gitlink",
-            "--router-draft-ref",
-            "router/draft-gitlink",
+            "--compiler-draft-ref",
+            "compiler/draft-gitlink",
             "--persisted-ref",
             "lifecycle/contracts/backend-scaffold-gitlink.yaml",
             "--contract-file",

package/template/scripts/verify-strategic-context-import

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { parseArgs } from "node:util";
+import { fileURLToPath } from "node:url";
+import { parseDocument } from "./vendor/yaml.mjs";
+import { parseContextContract } from "./lib/context-contract.mjs";
+import { validateVisualBaseline } from "../.agents/skills/yss-prototype-stage/scripts/visual-baseline-contract.mjs";
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const schemaPath = path.join(repoRoot, "docs/process/schemas/strategic-design-handoff.schema.json");
+const pythonValidator = String.raw`
+import json, sys
+from jsonschema import Draft202012Validator
+schema = json.load(open(sys.argv[1], encoding="utf-8"))
+value = json.load(sys.stdin)
+errors = sorted(Draft202012Validator(schema).iter_errors(value), key=lambda error: list(error.absolute_path))
+for error in errors:
+    where = ".".join(str(part) for part in error.absolute_path) or "<root>"
+    print(f"{where}: {error.message}", file=sys.stderr)
+sys.exit(1 if errors else 0)
+`;
+
+function parseFile(file) {
+  const document = parseDocument(readFileSync(file, "utf8"), { maxAliasCount: 0, uniqueKeys: true });
+  if (document.errors.length) throw new TypeError(document.errors[0].message);
+  return document.toJS({ maxAliasCount: 0 });
+}
+
+try {
+  const { values, positionals } = parseArgs({ options: { root: { type: "string", default: process.cwd() }, reconciliation: { type: "string" } }, allowPositionals: true, strict: true });
+  if (positionals.length !== 1 || !values.reconciliation) throw new TypeError("用法: scripts/verify-strategic-context-import --root <target-repo> --reconciliation <record> <handoff.yaml|json>");
+  const root = path.resolve(values.root);
+  const handoff = parseFile(path.resolve(positionals[0]));
+  if ([1, 2].includes(handoff.schema_version)) throw new TypeError(`migration-required: Strategic Design Handoff v${handoff.schema_version} 是只读历史资产；在途 UI 交接必须升级 v3 并携带 Visual Baseline`);
+  const schemaResult = spawnSync("python3", ["-c", pythonValidator, schemaPath], { encoding: "utf8", input: JSON.stringify(handoff) });
+  if (schemaResult.status !== 0) throw new TypeError(`${schemaResult.stdout}${schemaResult.stderr}`.trim());
+  const baselineRef = handoff.source.visual_baseline_ref;
+  const bundleRoot = path.resolve(root, baselineRef.persisted_ref);
+  const manifestPath = path.resolve(bundleRoot, baselineRef.manifest_ref);
+  if (!manifestPath.startsWith(`${bundleRoot}${path.sep}`) || !existsSync(manifestPath)) throw new TypeError("Strategic Design Handoff 的 Visual Baseline manifest 不可读或越界");
+  const baseline = parseFile(manifestPath);
+  const baselineResult = await validateVisualBaseline(baseline, { bundleRoot });
+  if (baselineResult.errors.length) throw new TypeError(`Visual Baseline 无效: ${baselineResult.errors.join("; ")}`);
+  if (baseline.baseline_id !== baselineRef.baseline_id || baseline.version !== baselineRef.version || baseline.bundle.digest !== baselineRef.digest) throw new TypeError("Strategic Design Handoff 的 Visual Baseline 身份、版本或 digest 不一致");
+  const actualCaseIds = baseline.cases.map((item) => item.case_id).sort();
+  if (JSON.stringify(actualCaseIds) !== JSON.stringify([...baselineRef.case_ids].sort())) throw new TypeError("Strategic Design Handoff 的 Visual Baseline case_ids 不一致");
+  const reconciliationResult = spawnSync(process.execPath, [path.join(repoRoot, "scripts/verify-context-reconciliation"), "--root", root, path.resolve(values.reconciliation)], { cwd: repoRoot, encoding: "utf8" });
+  if (reconciliationResult.status !== 0) throw new TypeError(reconciliationResult.stderr.trim());
+  const target = parseContextContract({ root });
+  for (const operation of ["added", "updated"]) {
+    for (const expected of handoff.context_delta[operation]) {
+      const actual = target.terms_by_ref.get(expected.term_ref);
+      if (!actual) throw new TypeError(`目标 CONTEXT.md 尚未导入 ${operation} 术语: ${expected.term_ref}`);
+      for (const field of ["term", "meaning", "english_identifier", "context_id"]) if (actual[field] !== expected[field]) throw new TypeError(`目标 CONTEXT.md 的 ${expected.term_ref}.${field} 与交接增量不一致`);
+      if (JSON.stringify([...actual.forbidden_aliases].sort()) !== JSON.stringify([...expected.forbidden_aliases].sort())) throw new TypeError(`目标 CONTEXT.md 的 ${expected.term_ref}.forbidden_aliases 与交接增量不一致`);
+    }
+  }
+  for (const deprecated of handoff.context_delta.deprecated) if (target.terms_by_ref.has(deprecated.term_ref)) throw new TypeError(`目标 CONTEXT.md 尚未处理 deprecated 术语: ${deprecated.term_ref}`);
+  process.stdout.write("Strategic context import 与目标 reconciliation 验证通过\n");
+} catch (error) {
+  process.stderr.write(`Strategic context import 验证失败: ${error.message}\n`);
+  process.exitCode = 1;
+}

package/template/scripts/verify-strategic-context-import-scenarios

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { sealVisualBaseline } from "../.agents/skills/yss-prototype-stage/scripts/visual-baseline-contract.mjs";
+
+const repoRoot = path.resolve(import.meta.dirname, "..");
+const root = mkdtempSync(path.join(tmpdir(), "yss-strategic-import-"));
+mkdirSync(path.join(root, "docs", "evidence"), { recursive: true });
+writeFileSync(path.join(root, "yss-project.yaml"), "schema_version: 1\nrepository_mode: project-instance\n");
+const context = (meaning = "提供产品或服务的主体") => `---
+context_schema_version: 1
+---
+# CONTEXT
+## 流程术语
+| 术语 | 含义 | 英文标识 | 避免 / 备注 |
+|---|---|---|---|
+| 阶段 | 生命周期阶段 | — | |
+## 业务术语
+| 术语 | 含义 | 英文标识 | 适用限界上下文 | 避免 / 备注 |
+|---|---|---|---|---|
+| 供应商 | ${meaning} | Supplier | Global | |
+`;
+writeFileSync(path.join(root, "CONTEXT.md"), context());
+const run = (command, args) => spawnSync(command, args, { cwd: repoRoot, encoding: "utf8" });
+const snapshot = JSON.parse(run("scripts/verify-context-contract", ["--root", root, "--term-ref", "Global/Supplier", "--json"]).stdout).context_snapshot;
+const reconciliation = { schema_version: 1, repository_mode: "project-instance", stage: "stage.system-data-engineering", work_unit: "work-unit.technical-analysis", status: "reconciled", context_snapshot: snapshot, changes: { added: ["Global/Supplier"], updated: [], deprecated: [] }, unresolved_terms: [], evidence_refs: ["CONTEXT.md"] };
+const reconciliationFile = path.join(root, "docs/evidence/context-reconciliation.json"); writeFileSync(reconciliationFile, JSON.stringify(reconciliation));
+const supplier = { term_ref: "Global/Supplier", term: "供应商", meaning: "提供产品或服务的主体", english_identifier: "Supplier", context_id: "Global", forbidden_aliases: [] };
+const ref = (id) => ({ id, version: "v2", digest: `sha256:${id}`, status: "approved", persisted_ref: `source/${id}` });
+function pngHeader(width, height) { const value = Buffer.alloc(24); Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]).copy(value, 0); value.writeUInt32BE(13, 8); value.write("IHDR", 12, "ascii"); value.writeUInt32BE(width, 16); value.writeUInt32BE(height, 20); return value; }
+const bundleRoot = path.join(root, "source/visual-baseline-v1"); mkdirSync(path.join(bundleRoot, "images"), { recursive: true }); mkdirSync(path.join(bundleRoot, "sources"), { recursive: true }); mkdirSync(path.join(bundleRoot, "capture"), { recursive: true });
+writeFileSync(path.join(bundleRoot, "images/primary-desktop.png"), pngHeader(1440, 900)); writeFileSync(path.join(bundleRoot, "images/primary-narrow.png"), pngHeader(390, 844));
+writeFileSync(path.join(bundleRoot, "sources/prototype.html"), "<main>supplier</main>\n"); writeFileSync(path.join(bundleRoot, "sources/interaction.md"), "# Interaction\n"); writeFileSync(path.join(bundleRoot, "sources/states.md"), "# States\n"); writeFileSync(path.join(bundleRoot, "capture/capture.mjs"), "// capture\n"); writeFileSync(path.join(bundleRoot, "capture/result.json"), "{\"result\":\"passed\"}\n");
+const baselineFile = path.join(bundleRoot, "visual-baseline.yaml");
+const baseline = { schema_version: 1, baseline_id: "visual-baseline.supplier", feature: "supplier", version: "v1", status: "approved", bundle: { format: "portable-directory", root_ref: "source/visual-baseline-v1", digest: `sha256:${"0".repeat(64)}`, size_bytes: 0, max_image_bytes: 5242880, max_bundle_bytes: 104857600 }, source: { prototype_ref: "sources/prototype.html", prototype_digest: `sha256:${"1".repeat(64)}`, interaction_spec_ref: "sources/interaction.md", interaction_spec_digest: `sha256:${"2".repeat(64)}`, state_matrix_ref: "sources/states.md", state_matrix_digest: `sha256:${"3".repeat(64)}` }, capture_environment: { browser: "chromium", browser_version: "140.0.0", operating_system: "linux", fonts_digest: `sha256:${"4".repeat(64)}`, device_scale_factor: 1, color_space: "srgb", locale: "zh-CN", timezone: "Asia/Shanghai", animations_disabled: true, cursor_hidden: true, capture_script_ref: "capture/capture.mjs", capture_script_digest: `sha256:${"5".repeat(64)}`, capture_result_ref: "capture/result.json", capture_result_digest: `sha256:${"6".repeat(64)}` }, cases: [{ case_id: "primary-desktop", route: "/supplier", page: "SupplierPage", state: "normal", viewport: { name: "desktop", width: 1440, height: 900, scroll_mode: "viewport", scroll_position: 0 }, theme: "compact-light", locale: "zh-CN", data_scenario: "primary", image_ref: "images/primary-desktop.png", image_digest: `sha256:${"0".repeat(64)}`, image_size_bytes: 1, mask_ref: "not-applicable", mask_digest: "not-applicable", mask_size_bytes: 0, semantic_refs: ["sources/prototype.html", "sources/interaction.md"], allowed_differences: [], result: "passed" }, { case_id: "primary-narrow", route: "/supplier", page: "SupplierPage", state: "normal", viewport: { name: "narrow", width: 390, height: 844, scroll_mode: "viewport", scroll_position: 0 }, theme: "compact-light", locale: "zh-CN", data_scenario: "primary", image_ref: "images/primary-narrow.png", image_digest: `sha256:${"0".repeat(64)}`, image_size_bytes: 1, mask_ref: "not-applicable", mask_digest: "not-applicable", mask_size_bytes: 0, semantic_refs: ["sources/states.md"], allowed_differences: [], result: "passed" }] };
+writeFileSync(baselineFile, JSON.stringify(baseline)); const sealedBaseline = await sealVisualBaseline(baselineFile, bundleRoot);
+const visualBaselineRef = { baseline_id: sealedBaseline.baseline_id, version: sealedBaseline.version, digest: sealedBaseline.bundle.digest, status: "approved", persisted_ref: "source/visual-baseline-v1", manifest_ref: "visual-baseline.yaml", case_ids: sealedBaseline.cases.map((item) => item.case_id) };
+const handoff = { schema_version: 3, handoff_id: "strategic-design-handoff.supplier", handoff_version: "v3", status: "approved", source: { domain_strategy_ref: ref("domain"), stage_decision_package_ref: ref("stage"), spec_ref: ref("spec"), prototype_ref: ref("prototype"), visual_baseline_ref: visualBaselineRef, business_ticket_set_ref: ref("tickets") }, source_context_snapshot: snapshot, context_delta: { added: [supplier], updated: [], deprecated: [] }, target_context_reconciliation: { target_context_ref: "CONTEXT.md", reconciliation_schema_ref: "docs/process/schemas/context-reconciliation.schema.json", required_before_skill: "yss-tactical-design", status: "pending" }, target: { team: "downstream-rd-team", skill: "yss-tactical-design", output: "tactical-design-contract" }, problem_and_business_outcomes: ["准入"], bounded_context_and_subdomain_map: ["Global"], context_map_and_translation_responsibility: ["共享"], ubiquitous_language_and_concept_candidates: ["Global/Supplier"], scenarios_and_business_invariants: ["稳定"], tactical_design_questions: ["聚合边界"], deferred_decisions_and_ownership: [], evidence_and_version_digests: ["source/evidence"], acceptance: ["target-context-reconciliation-is-required-before-tactical-design"] };
+const handoffFile = path.join(root, "handoff.json"); writeFileSync(handoffFile, JSON.stringify(handoff));
+function verify(expected, pattern) { const result = run("scripts/verify-strategic-context-import", ["--root", root, "--reconciliation", reconciliationFile, handoffFile]); if (result.status !== expected || (pattern && !pattern.test(`${result.stdout}${result.stderr}`))) throw new Error(`${result.stdout}${result.stderr}`); }
+verify(0);
+writeFileSync(path.join(root, "CONTEXT.md"), context("错误含义"));
+const staleSnapshot = JSON.parse(run("scripts/verify-context-contract", ["--root", root, "--term-ref", "Global/Supplier", "--json"]).stdout).context_snapshot;
+writeFileSync(reconciliationFile, JSON.stringify({ ...reconciliation, context_snapshot: staleSnapshot }));
+verify(1, /不一致/);
+writeFileSync(handoffFile, JSON.stringify({ ...handoff, schema_version: 2 }));
+verify(1, /migration-required/);
+process.stdout.write("Strategic context import scenarios passed\n");

package/template/scripts/verify-strategic-handoff-consumption

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { read } from './lib/strategic-handoff-io.mjs';
+import { verifyConsumption } from './lib/strategic-handoff-consumption.mjs';
+try {
+ const {values,positionals}=parseArgs({allowPositionals:true,options:{root:{type:'string',default:process.cwd()},slice:{type:'string'}}});
+ if(positionals.length!==1)throw new TypeError('用法: verify-strategic-handoff-consumption --root <target> [--slice <slice-id>] <tactical.yaml>');
+ const result=await verifyConsumption(read(positionals[0]),{root:values.root,sliceRef:values.slice});
+ process.stdout.write(`${JSON.stringify(result,null,2)}\n`);if(result.result==='blocked')process.exitCode=1;
+}catch(error){process.stderr.write(`${JSON.stringify({result:'blocked',error:error.message})}\n`);process.exitCode=1;}

package/template/scripts/verify-strategic-handoff-package-scenarios

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, readFileSync, writeFileSync, cpSync, rmSync } from 'node:fs';
+import path from 'node:path';
+import { tmpdir } from 'node:os';
+import { spawnSync } from 'node:child_process';
+import { fixture, context } from './fixtures/strategic-handoff/fixture.mjs';
+import { exportBundle, openBundle, importBundle } from './lib/strategic-handoff.mjs';
+import { read, json, hash, digest } from './lib/strategic-handoff-io.mjs';
+import { parseContextContract } from './lib/context-contract.mjs';
+const setup=async t=>{const base=mkdtempSync(path.join(tmpdir(),'handoff-test-'));t.after(()=>rmSync(base,{recursive:true,force:true}));const source=path.join(base,'source');mkdirSync(source);return{base,source,...await fixture(source)};};
+function advanceStrategy(f,version='v2') {
+ f.handoff.handoff_version=version;
+ f.strategy.domain_version=version;
+ f.strategy.approval.current_version=version;
+ f.stage.package_version=version;
+ f.stage.approval.current_version=version;
+ f.stage.domain_strategy_ref.domain_version=version;
+ f.handoff.source.domain_strategy_ref.version=version;
+ f.handoff.source.stage_decision_package_ref.version=version;
+ f.strategy.rule_catalog[0].statement='材料完整且有效';
+ f.strategy.scenarios[0].rules=['材料完整且有效'];
+ f.strategy.invariants[0].statement='材料完整且有效';
+ f.put('source/strategy.yaml',f.strategy);
+ f.handoff.source.domain_strategy_ref.digest=digest(f.strategy);
+ f.stage.domain_strategy_ref.digest=digest(f.strategy);
+ f.put('source/stage.yaml',f.stage);
+ f.handoff.source.stage_decision_package_ref.digest=digest(f.stage);
+ f.sign();
+}
+test('目录和 ZIP 可脱离源仓验包；导入幂等且不修改词汇表',async t=>{
+ const f=await setup(t);const output=path.join(f.base,'package');
+ const result=await exportBundle({sourceRoot:f.source,handoffRef:'handoff.yaml',output,zip:true});
+ rmSync(f.source,{recursive:true});
+ for(const bundle of [output,`${output}.zip`])assert.equal(await openBundle(bundle,b=>b.manifest.bundle_digest),result.bundle_digest);
+ const target=path.join(f.base,'target');mkdirSync(target);writeFileSync(path.join(target,'yss-project.yaml'),'schema_version: 1\nrepository_mode: project-instance\n');writeFileSync(path.join(target,'CONTEXT.md'),context);
+ const imported=await importBundle({bundle:`${output}.zip`,targetRoot:target});assert.equal(imported.result,'imported-pending-reconciliation');
+ assert.equal(readFileSync(path.join(target,'CONTEXT.md'),'utf8'),context);parseContextContract({root:target});
+ assert.equal((await importBundle({bundle:output,targetRoot:target})).result,'already-imported');
+});
+test('规则遗漏、摘要漂移、批准不匹配和离线资源丢失阻断导出',async t=>{
+ const f=await setup(t);const run=()=>exportBundle({sourceRoot:f.source,handoffRef:'handoff.yaml',output:path.join(f.base,'out')});
+ const text=readFileSync(path.join(f.source,'source/strategy.yaml'));f.put('source/strategy.yaml',{...f.strategy,traceability_version:undefined});
+ await assert.rejects(run,/不一致|过期|migration/);writeFileSync(path.join(f.source,'source/strategy.yaml'),text);
+ const approved=read(path.join(f.source,'approvals/spec_ref.yaml'));f.put('approvals/spec_ref.yaml',{...approved,artifact_bindings:[]});await assert.rejects(run,/批准记录未绑定/);f.put('approvals/spec_ref.yaml',approved);
+ const roles=read(path.join(f.source,'docs/agents/digital-human-roles.yaml'));f.put('docs/agents/digital-human-roles.yaml',{...roles,user_decision_policy:{...roles.user_decision_policy,gates:['gate.domain-strategy-approved']}});await assert.rejects(run,/user-decision|升级/);f.put('docs/agents/digital-human-roles.yaml',roles);
+ const sourceBytes=readFileSync(path.join(f.source,'prototype-src/main.js'));f.put('prototype-src/main.js','changed');await assert.rejects(run,/源码\/锁文件批准摘要/);writeFileSync(path.join(f.source,'prototype-src/main.js'),sourceBytes);
+ const verification=read(path.join(f.source,'evidence/offline.json'));f.put('evidence/offline.json',{...verification,command:'changed'});await assert.rejects(run,/验证记录批准摘要/);f.put('evidence/offline.json',verification);
+ f.put('preview/index.html','<img src="missing.png">');await assert.rejects(run,/过期/);
+});
+test('篡改 payload、重新封摘要后的虚构规则索引、额外文件均拒绝',async t=>{
+ const f=await setup(t),output=path.join(f.base,'package');await exportBundle({sourceRoot:f.source,handoffRef:'handoff.yaml',output});
+ const spec=path.join(output,'payload/files/source/spec.md'),bytes=readFileSync(spec);writeFileSync(spec,'tampered');await assert.rejects(()=>openBundle(output,()=>null),/摘要/);writeFileSync(spec,bytes);
+ writeFileSync(path.join(output,'extra.txt'),'extra');await assert.rejects(()=>openBundle(output,()=>null),/未登记/);rmSync(path.join(output,'extra.txt'));
+ const manifest=read(path.join(output,'manifest.json'));const idx=Buffer.from(json([]));writeFileSync(path.join(output,'indexes/rules.json'),idx);const row=manifest.files.find(x=>x.path==='indexes/rules.json');row.sha256=hash(idx);row.size_bytes=idx.length;delete manifest.bundle_digest;manifest.bundle_digest=digest(manifest);writeFileSync(path.join(output,'manifest.json'),json(manifest));await assert.rejects(()=>openBundle(output,()=>null),/索引与源/);
+});
+test('ZIP 路径穿越和重复条目拒绝',async t=>{
+ const f=await setup(t);
+ for(const names of [['../escape'],['manifest.json','manifest.json']]){
+  const zip=path.join(f.base,'bad.zip');rmSync(zip,{force:true});const py='import zipfile,json,sys; z=zipfile.ZipFile(sys.argv[1],"w"); [z.writestr(n,"x") for n in json.loads(sys.argv[2])]; z.close()';assert.equal(spawnSync('python3',['-c',py,zip,JSON.stringify(names)]).status,0);await assert.rejects(()=>openBundle(zip,()=>null),/ZIP/);
+ }
+});
+test('版本差异绑定前版，重复版本不允许；修改规则产生更新集合',async t=>{
+ const f=await setup(t),first=path.join(f.base,'v1');await exportBundle({sourceRoot:f.source,handoffRef:'handoff.yaml',output:first});
+ await assert.rejects(()=>exportBundle({sourceRoot:f.source,handoffRef:'handoff.yaml',output:path.join(f.base,'bad'),previous:first}),/提升/);
+ advanceStrategy(f);
+ const second=path.join(f.base,'v2');await exportBundle({sourceRoot:f.source,handoffRef:'handoff.yaml',output:second,previous:first});assert.deepEqual(await openBundle(second,b=>b.changes.updated),['rule.complete','scenario.submit']);
+});
+
+test('受控延期只阻断依赖切片；未知依赖扩大阻断；目标未对账禁止消费',async t=>{
+ const {verifyConsumption}=await import('./lib/strategic-handoff-consumption.mjs');
+ const f=await setup(t),output=path.join(f.base,'package');await exportBundle({sourceRoot:f.source,handoffRef:'handoff.yaml',output});
+ const target=path.join(f.base,'target');mkdirSync(target);writeFileSync(path.join(target,'yss-project.yaml'),'schema_version: 1\nrepository_mode: project-instance\n');writeFileSync(path.join(target,'CONTEXT.md'),context);
+ const result=await importBundle({bundle:output,targetRoot:target});
+ const draft=read(path.join(target,result.traceability_ref));
+ const tactical={status:'approved',strategic_handoff:{...draft,context_reconciliation_ref:'reconciliation.yaml'},behavior_catalog:[{behavior_id:'behavior.submit'}],test_seams:[{seam_id:'test-seam.submit',subject_ref:'behavior.submit'}]};
+ const record={schema_version:1,repository_mode:'project-instance',stage:'stage.system-data-engineering',work_unit:'work-unit.technical-analysis',status:'reconciled',context_snapshot:f.snapshot,changes:{added:['Global/Supplier'],updated:[],deprecated:[]},unresolved_terms:[],evidence_refs:['CONTEXT.md']};
+ writeFileSync(path.join(target,'reconciliation.yaml'),json(record));
+ for(const row of tactical.strategic_handoff.rows)Object.assign(row,{disposition:'implemented',tactical_refs:['behavior.submit'],test_seam_refs:['test-seam.submit'],scenario_tests:[{outcome:'success',seam_ref:'test-seam.submit'},{outcome:'failure',seam_ref:'test-seam.submit'}],evidence_refs:['CONTEXT.md'],dependency_status:'known',dependent_slice_refs:['slice.submit']});
+ assert.equal((await verifyConsumption(tactical,{root:target})).result,'verified');
+ const row=tactical.strategic_handoff.rows[0];Object.assign(row,{disposition:'deferred',reason:'分批实现',risk:'不能提交',owner:'需求负责人',followup_ticket_ref:'ticket.followup',verification_plan:'提交测试',target_version:'v2'});
+ assert.equal((await verifyConsumption(tactical,{root:target,sliceRef:'slice.submit'})).result,'blocked');
+ assert.equal((await verifyConsumption(tactical,{root:target,sliceRef:'slice.other'})).result,'verified');
+ row.dependency_status='unknown';assert.equal((await verifyConsumption(tactical,{root:target,sliceRef:'slice.other'})).result,'blocked');
+ row.dependency_status='known';row.disposition='implemented';advanceStrategy(f);const second=path.join(f.base,'v2');await exportBundle({sourceRoot:f.source,handoffRef:'handoff.yaml',output:second,previous:output});await importBundle({bundle:second,targetRoot:target});
+ const stale=await verifyConsumption(tactical,{root:target,sliceRef:'slice.submit'});assert.equal(stale.result,'blocked');assert(stale.issues.some(x=>x.reason==='stale-source'));assert.equal((await verifyConsumption(tactical,{root:target,sliceRef:'slice.other'})).result,'verified');
+ f.strategy.contexts[0].responsibilities.push('新增责任边界');advanceStrategy(f,'v3');const third=path.join(f.base,'v3');await exportBundle({sourceRoot:f.source,handoffRef:'handoff.yaml',output:third,previous:second});await importBundle({bundle:third,targetRoot:target});const changedBoundary=await verifyConsumption(tactical,{root:target,sliceRef:'slice.other'});assert.equal(changedBoundary.block_all,true);assert(changedBoundary.issues.some(x=>x.reason==='upstream-design-stale'));
+ writeFileSync(path.join(target,'reconciliation.yaml'),json({...record,status:'blocked',unresolved_terms:[{term:'Supplier',reason:'冲突',owner:'需求负责人',next_action:'回交战略方'}]}));
+ await assert.rejects(()=>verifyConsumption(tactical,{root:target}),/对账未通过/);
+});
+
+test('源规则必须稳定可追溯，关键场景不能遗漏结果',async t=>{
+ const {extractTraceability}=await import('./lib/strategic-handoff-rules.mjs');const f=await setup(t);
+ for(const mutate of [s=>delete s.traceability_version,s=>s.scenarios[0].rule_refs=['rule.missing'],s=>delete s.scenarios[0].success_results,s=>s.invariants[0].rule_ref='rule.missing',s=>s.rule_catalog.push({...s.rule_catalog[0]})]){const s=structuredClone(f.strategy);mutate(s);assert.throws(()=>extractTraceability(s));}
+});
+test('统一 CLI 在源目录消失后通过 ZIP 验包',async t=>{
+ const f=await setup(t),output=path.join(f.base,'cli');
+ const cli=path.join(import.meta.dirname,'strategic-handoff');
+ const exported=spawnSync(process.execPath,[cli,'export','--source-root',f.source,'--handoff','handoff.yaml','--output',output,'--zip'],{encoding:'utf8'});assert.equal(exported.status,0,exported.stderr);
+ rmSync(f.source,{recursive:true});const checked=spawnSync(process.execPath,[cli,'verify','--bundle',`${output}.zip`],{encoding:'utf8'});assert.equal(checked.status,0,checked.stderr);assert.equal(JSON.parse(checked.stdout).result,'verified');
+});

package/template/scripts/verify-subagent-task-package-scenarios

@@ -1,7 +1,13 @@
 #!/usr/bin/env node
 import assert from "node:assert/strict";
-import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, rmSync, writeFileSync, mkdtempSync, readFileSync } from "node:fs";
 import path from "node:path";
+import os from "node:os";
+import { buildDecisionFixture } from "./fixtures/user-decision/build-fixture.mjs";
+import { decisionDigest } from "./lib/user-decision.mjs";
+const decisionTemp = mkdtempSync(path.join(os.tmpdir(), "task-decision-test-"));
+process.on("exit", () => rmSync(decisionTemp, { recursive: true, force: true }));
+let decisionRequirement;
 import { spawnSync } from "node:child_process";
 import { ROOT } from "./lib/lifecycle-registry.mjs";
 import { generateTaskPackageDefaults, validateTaskPackage, validateTaskPackageSet } from "./lib/task-package.mjs";
@@ -19,7 +25,8 @@ const contract = {
   contract_version: 2,
   slice_id: "todo",
   status: "approved",
-  lifecycle_refs: {},
+  lifecycle_refs: { ticket: "docs/.scratch/todo/issues/01-todo.md", engineering_baseline: evidenceRef },
+  common: { project_roots: ["apps/frontend/todo", "apps/backend/todo"], allowed_write_paths: ["apps/frontend/todo/", "apps/backend/todo/"] },
   readiness: {},
   work_units: [
     { id: "work-unit.slice-frontend", role_id: "role.frontend-engineer", runtime_id: "runtime.skill-projection", task_package_ref: "work-unit.slice-frontend", contract_id: "slice-todo", contract_version: 2, allowed_write_paths: ["apps/frontend/todo/"] },
@@ -45,6 +52,10 @@ function writeFixtures() {
   writeFileSync(contractFile, JSON.stringify(contract));
   writeFileSync(evidenceFile, JSON.stringify({ ok: true }));
   writeFileSync(path.join(ROOT, maintenanceRef), JSON.stringify(maintenance));
+  const scopeRef = path.join(decisionTemp, "scope.json");
+  const asset = (ref) => ({ ref, version: "v1", digest: decisionDigest(readFileSync(path.join(ROOT, ref))) });
+  writeFileSync(scopeRef, JSON.stringify({ kind: "implementation-scope", slices: [{ ticket_ref: contract.lifecycle_refs.ticket, contract: asset(contractRef), repositories: contract.common.project_roots, allowed_write_paths: contract.common.allowed_write_paths, baselines: [asset(evidenceRef)] }] }));
+  decisionRequirement = buildDecisionFixture(decisionTemp, { boundary: "implementation-scope", scope: [contract.lifecycle_refs.ticket], subjectRef: scopeRef }).requirement;
 }
 
 function packageBase(roleId, taskId, workUnitId, kind, contractFields, stageId) {
@@ -95,6 +106,7 @@ function slicePackage(roleId, taskId, workUnitId, writePath) {
     workflow_status: "not-started",
     contract: { kind: "slice-implementation", contract_id: contract.contract_id, contract_version: contract.contract_version, status: "issued", contract_ref: contractRef, slice_contract_ref: contractRef },
     inputs: ["CONTEXT.md"],
+    user_decisions: [decisionRequirement],
     objective: "实现 Todo 垂直切片",
     allowed_write_paths: [writePath],
     forbidden_actions: ["不得修改合同"],
@@ -115,6 +127,7 @@ function completedResult(pkg, overrides = {}) {
     result: "completed",
     skill: "yss-product-lifecycle",
     changed_files: [],
+    context_reconciliation: { status: "reconciled", ref: evidenceRef },
     evidence_refs: [evidenceRef],
     deferred_seams: [],
     drift: [],
@@ -150,6 +163,7 @@ try {
   [discovery, spec, prototype, technical, tickets, review].forEach((pkg) => validateTaskPackage(pkg));
   validateTaskPackage(maintenance);
   validateTaskPackage(frontend);
+  assert.throws(() => validateTaskPackage({ ...frontend, user_decisions: [] }), /user-decision-scope-mismatch/, "Worker 派发前必须有当前实施范围批准");
   validateTaskPackage(backend);
   validateTaskPackageSet([frontend, backend]);
 
@@ -183,7 +197,7 @@ try {
   mustFail((value) => { value.execution_state = "Reviewer"; value.review_context = { implementation_actor_id: value.actor_id }; }, /不同 actor_id/, "reviewer-implementer-conflict");
   mustFail((value) => { value.workflow_status = "resolved"; value.verification_results = [{ command: "scripts/verify-template", exit_code: 0, executed_at: "now", evidence_ref: evidenceRef }]; value.result = completedResult(value, { new_impacts: ["api-change"] }); }, /new_impacts 必须为空/, "completed-new-impact");
   mustFail((value) => { value.workflow_status = "resolved"; value.verification_commands = ["scripts/verify-template", "pnpm test"]; value.verification_results = [{ command: "scripts/verify-template", exit_code: 0, executed_at: "now", evidence_ref: evidenceRef }]; value.result = completedResult(value); }, /覆盖全部 verification_commands/, "verification-command-gap");
-  mustFail((value) => { value.workflow_status = "resolved"; value.result = completedResult(value, { evidence_refs: [".template-source/evidence/.missing.json"] }); value.verification_results = [{ command: "scripts/verify-template", exit_code: 0, executed_at: "now", evidence_ref: evidenceRef }]; }, /不可读/, "unreadable-evidence");
+  mustFail((value) => { value.workflow_status = "resolved"; value.result = completedResult(value, { context_reconciliation: { status: "reconciled", ref: ".template-source/evidence/.missing.json" }, evidence_refs: [".template-source/evidence/.missing.json"] }); value.verification_results = [{ command: "scripts/verify-template", exit_code: 0, executed_at: "now", evidence_ref: evidenceRef }]; }, /不可读/, "unreadable-evidence");
   mustFail((value) => { value.workflow_status = "resolved"; value.verification_results = [{ command: "scripts/verify-template", exit_code: 0, executed_at: "now", evidence_ref: evidenceRef }]; }, /Workflow Execution Result/, "resolved-without-result");
   mustFail((value) => { value.workflow_status = "resolved"; value.result = { result: "blocked" }; value.verification_results = [{ command: "scripts/verify-template", exit_code: 0, executed_at: "now", evidence_ref: evidenceRef }]; }, /Workflow Execution Result/, "resolved-blocked-result");
   mustFail((value) => { value.workflow_status = "resolved"; value.verification_results = [{ command: "scripts/verify-template", exit_code: 0, executed_at: "now", evidence_ref: evidenceRef }]; value.result = completedResult(value); value.expected_evidence_files = [".template-source/evidence/.missing.json"]; }, /expected_evidence_files.*不可读/, "missing-expected-evidence");

package/template/scripts/verify-template-verification-scenarios

@@ -17,8 +17,13 @@ const releaseBaseline = [
   "scripts/verify-yss-dto-openapi-scenarios",
   "scripts/verify-digital-human-roles",
   "scripts/verify-digital-human-roles-scenarios",
-  "scripts/verify-approval-record docs/templates/approval-record-template.yaml",
+  "scripts/verify-approval-record --history docs/templates/approval-record-template.yaml",
   "scripts/verify-lifecycle-registry",
+  "scripts/verify-context-contract --root . --json",
+  "scripts/verify-context-contract-scenarios",
+  "scripts/verify-context-reconciliation-scenarios",
+  "scripts/verify-grill-with-docs-context-scenarios",
+  "scripts/verify-strategic-context-import-scenarios",
   "scripts/verify-lifecycle-checkpoint docs/process/templates/lifecycle-checkpoint-template.yaml",
   "scripts/verify-frontend-implementation-evidence --allow-template docs/process/templates/frontend-implementation-plan-template.yaml",
   "scripts/verify-frontend-implementation-evidence --allow-template docs/process/templates/frontend-implementation-verification-template.yaml",
@@ -36,7 +41,10 @@ const releaseBaseline = [
   "scripts/verify-scaffold-generator-scenarios",
   "scripts/verify-prototype-backend-scaffold-scenarios",
   "scripts/verify-matt-yss-integration-scenarios",
-  "scripts/verify-yss-router-scenarios",
+  "scripts/verify-yss-implementation-contract-compiler-scenarios",
+  "scripts/generate-yss-skill-boundaries --check",
+  "scripts/audit-yss-backend-skills --check",
+  "scripts/verify-retired-skill-ids",
   "scripts/verify-yss-ui-scenarios",
   "scripts/verify-yss-prototype-contract-scenarios",
   "node .agents/skills/yss-prototype-stage/scripts/prototype-contract.mjs validate-evidence docs/design/templates/prototype-evidence-template.yaml --allow-template",

package/template/scripts/verify-user-decision

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { decisionIO, verifyUserDecisionFile } from "./lib/user-decision.mjs";
+try {
+  const { positionals, values } = parseArgs({ allowPositionals: true, options: { root: { type: "string" }, requirements: { type: "string" } } });
+  if (positionals.length !== 1) throw new TypeError("用法: scripts/verify-user-decision [--root <repo>] [--requirements <当前事项.json>] <record.yaml>");
+  const options = values.root ? { root: values.root } : {};
+  const io = decisionIO(options);
+  const record = io.document(positionals[0]);
+  // No requirements means verify every requested item for approval; partial approvals need explicit current requirements.
+  options.expected = values.requirements ? io.document(values.requirements) : record.request.items.map((item) => ({ boundary: item.boundary, subject_ref: item.subject.ref, scope: item.scope }));
+  verifyUserDecisionFile(positionals[0], options);
+  process.stdout.write("用户决定及当前批准范围校验通过\n");
+} catch (error) {
+  process.stderr.write(`用户决定校验失败: ${error.message}\n`);
+  process.exitCode = 1;
+}