create-yss-spec 3.3.8 → 3.4.1

package/README.md

@@ -2,7 +2,7 @@
 
 用于初始化、接管已有项目并持续同步 `yss-spec-project-template` 研发管理资产的 npm CLI。
 
-源码候选版本：`3.3.8`。当前固定模板身份、来源状态和摘要见 `template.snapshot.json`；CLI 运行时不会拉取模板仓库。`npm create yss-spec@latest` 获取的是实际已发布 npm 包，发布版本请以 `npm view create-yss-spec version` 为准，并用 `create-yss-spec --version` 核对当前执行版本。
+源码候选版本：`3.4.1`。当前固定模板身份、来源状态和摘要见 `template.snapshot.json`；CLI 运行时不会拉取模板仓库。`npm create yss-spec@latest` 获取的是实际已发布 npm 包，发布版本请以 `npm view create-yss-spec version` 为准，并用 `create-yss-spec --version` 核对当前执行版本。
 
 ## 本版模板能力
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-yss-spec",
-  "version": "3.3.8",
+  "version": "3.4.1",
   "description": "Initialize a YSS spec project template repository",
   "main": "src/api/index.js",
   "repository": {

package/template/.agents/skills/.strategic-design-skills-manifest.json

@@ -3,7 +3,7 @@
   "source": "iloveZzz/yss-harness-design-agent",
   "source_type": "git-submodule",
   "source_root": ".agents/skills",
-  "source_revision": "b7947298f74510861a36caedda4e77d03df35569",
+  "source_revision": "e5cc1b2b9a99297b475551174057dbeb1d5f1a24",
   "adaptation_ref": "docs/agents/strategic-design-skills-integration.md",
   "skills": [
     {
@@ -14,22 +14,12 @@
     {
       "upstream": "yss-prototype-stage",
       "canonical": "yss-prototype-stage",
-      "upstream_hash": "4bb0ba6cdbbbd1a3b89e97d94a7b0829c9282e21c8ce9e4bfda6e69a8714bc6d"
+      "upstream_hash": "8256a1edfeb203f4de27d190210b0ba5593f8f74e0f3655b62b146daff2105a8"
     },
     {
       "upstream": "yss-design-system",
       "canonical": "yss-design-system",
-      "upstream_hash": "90aaf06b2514353152464a4d032076fa9d5ef56272d8ad526f5544f3c22a2b00"
-    },
-    {
-      "upstream": "yss-antd-design",
-      "canonical": "yss-antd-design",
-      "upstream_hash": "08ce99d45586d5ea19e25fdd9e9a6ede16e66f18992b70b87e0cd23f92343b16"
-    },
-    {
-      "upstream": "yss-antdv-next-design",
-      "canonical": "yss-antdv-next-design",
-      "upstream_hash": "2942ed52dd58a38e51f09eb11254809334aeaed08f21cd081f09f35e6647a68c"
+      "upstream_hash": "c917ecf40a67c52f0fa7894fbdfbf827cc1ed6aff1037be2911377387fede1a0"
     },
     {
       "upstream": "yss-stage-decision",

package/template/.agents/skills/yss-ddd-scaffold-generator/SKILL.md

@@ -88,10 +88,10 @@ node scripts/run_first_slice_verification.mjs \
 - 生成后的后端工程必须使用项目根目录 `./mvnw ...` 执行构建、测试、运行和 CI 验证；不得在 README、实施记录、Ticket、Review 或 Release 中默认写裸 `mvn ...`。既有仓库确实无法使用 wrapper 时，必须记录受控例外。
 - 原型确认后，`scaffold_status=required` 才能进入本 skill；本 skill 的生成边界是工程结构、POM、配置、Wrapper 和机械模板，不是业务实现。
 - 脚手架合同必须携带 `contract_id`、`contract_version`、实现合同编译器 draft 引用、生命周期批准引用、持久化引用、当前版本、允许写路径、预期证据文件和验证命令；字段缺失或版本过期时阻断。
-- 新脚手架优先接受统一 Project Scaffold Contract schema v4；已批准且当前的后端 schema v3 可完成兼容生成。两者都必须携带 `architecture_family=domain-driven`、`generator_skill`、`decision_ref/id/digest`、固定模块闭包，以及 `project_name`、`base_package` 和 `maven_coordinates`。历史 schema v2 仅只读兼容，不用于新生成；schema v1/v2 均不自动升级。
+- 新脚手架只接受统一 Project Scaffold Contract schema v4，并必须以原始字节摘要绑定批准且当前的 Technical Design、Data Architecture Decision v1、API Contract Decision v1 和真实工程合同批准记录。API `required` 必须闭包绑定同一 OpenAPI YAML 字节的 Validation、独立 Review、Freeze 与工程批准；`not-applicable` 必须绑定评估、明确原因和证据且禁止空占位资产。历史 schema v3/v2 仅用于 Manifest 只读验证和补齐 API 对账后的恢复审计，不用于新生成。
 - 合同 `profiles` 只支持 `target-domain-model`、`mybatis-plus`、`mysql`、`spring-boot-2.7-jdk8`、`javax`、`web`、`yss-internal`。普通 MyBatis、Boot 3、独立 client module、client-in-domain 和其他旧架构均为 `unsupported`，不提供回退分支。
 - 运行生成器必须传入 `--contract-file`；生成器会校验合同 `status=approved`、`current_version`、`primary_skill`、`controlled-generation`、实际输出路径和固定三条验证命令，不接受仅凭任意字符串引用的放行。
-- 生成项目必须写入 Manifest v3 `.yss/scaffold-generation.json`，记录架构选择及 digest、生成器、合同 digest、Target Profile、模块闭包、模板 digest、下游完整 skill tree digest、脚手架父合同与 实现合同编译器 合同 digest、generator-owned 文件 hash、严格 `generation_policy` 和完成等级；清单缺失或不一致时不得交给后续 实现合同编译器。
+- 生成项目必须写入 Manifest v4 `.yss/scaffold-generation.json`，记录技术、数据与 API 设计门禁、架构选择及 digest、生成器、合同 digest、Target Profile、模块闭包、模板 digest、下游完整 skill tree digest、generator-owned 文件 hash、严格 `generation_policy` 和完成等级；清单缺失或不一致时不得交给后续 实现合同编译器。
 - `first-slice-verified` 只能由 `run_first_slice_verification.mjs` 写入。手工改 Manifest、只生成 Controller、只通过局部模块测试或仅有结构扫描都不能升级完成等级。
 - 严禁把领域规则、状态机、权限、事务、复杂查询、错误映射、业务字段或用户可见行为塞进脚手架生成步骤。`./mvnw validate`、输出目录存在或“生成成功”都不等于生命周期批准、架构放行或 `ready-for-agent`。
 - 生命周期脚手架生成必须关闭 `--with-example`，不得把 User CRUD 或业务字段当作样板。生成器严格 `initialize-only`：非空目标、`--force`、旧项目迁移和当前模板升级一律 `unsupported`。未来若支持同一 Target Profile 内的模板升级，必须另行设计和批准，当前不预留可执行承诺。
@@ -109,7 +109,7 @@ node scripts/run_first_slice_verification.mjs \
 - 受控验证器：`scripts/run_scaffold_verification.mjs`
 - 首切片验证器：`scripts/run_first_slice_verification.mjs`
 - 模板目录：`assets/templates/`
-- 分层细化参考：`references/yss-backend-scaffold-parent/` 及其子 skill
+- Parent 工程约束使用已登记的 `references/yss-backend-scaffold-parent/`；生成后的分层实现路由见 `references/layer-skill-routing.md`
 
 ## 阶段 7 合同
 

package/template/.agents/skills/yss-ddd-scaffold-generator/references/USAGE_EXAMPLES.md

@@ -2,7 +2,7 @@
 
 ## 1. 准备批准合同
 
-新合同是服务级工程基线，使用 schema v3 与 `scaffold_request_id`，并把已批准的架构决策、Java 包名、Maven 坐标和 Profile 分开登记：
+新合同是服务级工程基线，使用 schema v4 与 `scaffold_request_id`，并把已批准的技术/数据设计、工程合同批准、架构决策、Java 包名、Maven 坐标和 Profile 分开登记：
 
 ```json
 {

package/template/.agents/skills/yss-ddd-scaffold-generator/references/layer-skill-routing.md

@@ -0,0 +1,18 @@
+# DDD 分层实现路由
+
+本文件只记录脚手架完成后的分层实现路由，不作为独立 Skill 被发现。实际实现必须回到已批准的 Slice Implementation Contract，并加载对应的顶层权威 Skill。
+
+| 分层或适配器 | 权威 Skill | 边界 |
+|---|---|---|
+| Application | `yss-application` | 编排用例与事务，不复制领域规则。 |
+| Domain | `yss-domain` | 持有聚合、实体、值对象、领域行为和端口。 |
+| Infrastructure | `yss-repository`，按需追加 `yss-mybatis` | 实现持久化端口，不向 Domain 泄漏 PO、Mapper 或框架类型。 |
+| Web | `yss-web-controller`，按需追加 `yss-dto`、`yss-exception`、`yss-validation` | Controller 只调用 Application Service；HTTP 与异常包装停留在 Web 边界。 |
+| Scheduler / External Adapter | 按入口选择 `yss-application`、`yss-web-controller` 或 `yss-repository` | 只做协议、调度或外部系统适配，不承载领域规则。 |
+
+Adapter 额外遵循以下约束：
+
+- 输入先转换为 Application Command / Query，再调用 Application Service。
+- 实现 Application 或 Domain 端口时，签名不得泄漏 HTTP DTO、PO、Mapper 或第三方 SDK 类型。
+- 映射使用 Spring 管理的 MapStruct Bean，禁止静态 `Mappers.getMapper(...)` 或 `INSTANCE`。
+- 旧式 Controller 或旧分层结构不是 `target-domain-model` 的实现依据；架构现代化必须单独立项。

package/template/.agents/skills/yss-ddd-scaffold-generator/references/yss-backend-scaffold-parent/SKILL.md

@@ -40,7 +40,7 @@ infrastructure-+
 
 ## 生成与验证
 
-- 输入是批准且持久化的服务级 scaffold contract schema v3，身份为 `scaffold_request_id`，并绑定已确认的 `architecture_family=domain-driven` 架构决策；不使用 `slice_id`。历史 Manifest v2 仅供验证器只读兼容。
+- 输入是批准、持久化且当前的服务级 scaffold contract schema v4，身份为 `scaffold_request_id`，并绑定已确认的 `architecture_family=domain-driven` 架构决策、Technical Design、Data Architecture Decision v1 与真实工程合同批准；不使用 `slice_id`。历史 Manifest v2/v3 仅供验证器只读兼容。
 - 生成器严格 initialize-only：目标工程目录必须不存在，`--force`、旧项目迁移和当前模板升级均为 `unsupported`。
 - Maven 内部仓库通过命名 profile `yss-internal` 与环境变量注入；共享模板不写内部 URL 或凭据。
 - Wrapper 必须带 checksum；DEBUG 和 MyBatis stdout SQL 只允许在 `application-local.yml`。

package/template/.agents/skills/yss-ddd-scaffold-generator/scripts/first-slice-compatibility.test.mjs

@@ -7,6 +7,7 @@ import os from "node:os";
 import path from "node:path";
 import test from "node:test";
 import { fileURLToPath } from "node:url";
+import { attachDesignPrerequisites } from "../../../../scripts/fixtures/backend-scaffold/design-prerequisites.mjs";
 
 import { generate as generateWeb, parseArgs as parseWebArgs } from "../../yss-web-controller/scripts/generate_controller.mjs";
 import { runFirstSliceVerification } from "./run_first_slice_verification.mjs";
@@ -18,7 +19,12 @@ const execute = (file, args, options = {}) => new Promise((resolve) => execFile(
 
 function scaffoldContract(output, decisionDigest) {
   return {
-    schema_version: 3,
+    schema_version: 4,
+    kind: "project-scaffold-contract",
+    delivery_role: "backend",
+    scaffold_kind: "backend-ddd",
+    repository_scope: "external-repository",
+    init_git: false,
     contract_id: "golden-scaffold-1",
     contract_version: 1,
     scaffold_request_id: "golden-request-1",
@@ -26,7 +32,7 @@ function scaffoldContract(output, decisionDigest) {
     compiler_draft_ref: "compiler-golden-1",
     lifecycle_approval_ref: "approval-golden-1",
     persisted_ref: "persisted-golden-1",
-    current_version: 1,
+    current_version: true,
     implementation_repository: "external",
     backend_repository: "external",
     scaffold_status: "required",
@@ -69,8 +75,11 @@ async function prepareGoldenProject(t) {
   await writeFile(decisionFile, decisionText);
   const decisionDigest = `sha256:${createHash("sha256").update(decisionText).digest("hex")}`;
   const contractFile = path.join(root, "scaffold-contract.json");
-  await writeFile(contractFile, `${JSON.stringify(scaffoldContract(output, decisionDigest), null, 2)}\n`);
-  const args = ["--project-name", "golden-service", "--base-package", "com.yss.golden", "--output-dir", output, "--contract-id", "golden-scaffold-1", "--contract-version", "1", "--approval-ref", "approval-golden-1", "--compiler-draft-ref", "compiler-golden-1", "--persisted-ref", "persisted-golden-1", "--contract-file", contractFile, "--group-id", "com.yss.datamiddle", "--project-version", "1.0.0-SNAPSHOT", "--parent-group-id", "com.yss.datamiddle", "--parent-artifact-id", "yss-datamiddle-parent", "--parent-version", "2.0.0-SNAPSHOT", "--yss-components-version", "2.0.0-SNAPSHOT"];
+  const contract = scaffoldContract(output, decisionDigest);
+  contract.decision_ref = decisionFile;
+  attachDesignPrerequisites(root, contract);
+  await writeFile(contractFile, `${JSON.stringify(contract, null, 2)}\n`);
+  const args = ["--project-name", "golden-service", "--base-package", "com.yss.golden", "--output-dir", output, "--contract-id", "golden-scaffold-1", "--contract-version", "1", "--approval-ref", contract.lifecycle_approval_ref, "--compiler-draft-ref", "compiler-golden-1", "--persisted-ref", "persisted-golden-1", "--contract-file", contractFile, "--group-id", "com.yss.datamiddle", "--project-version", "1.0.0-SNAPSHOT", "--parent-group-id", "com.yss.datamiddle", "--parent-artifact-id", "yss-datamiddle-parent", "--parent-version", "2.0.0-SNAPSHOT", "--yss-components-version", "2.0.0-SNAPSHOT"];
   const generated = await execute(process.execPath, [generator, ...args]);
   assert.equal(generated.code, 0, generated.stderr);
   const project = path.join(output, "golden-service");

package/template/.agents/skills/yss-ddd-scaffold-generator/scripts/generate_scaffold.mjs

@@ -10,6 +10,7 @@ import { parseDocument } from "../../../../scripts/vendor/yaml.mjs";
 import { assertLocalDatabaseProfile, localDatabaseConfiguration, scaffoldArchitectureIdentity } from "../../../../scripts/lib/scaffold-local-database.mjs";
 import { validateArchitectureIdentity } from "../../../../scripts/lib/backend-architecture.mjs";
 import { validateJsonSchema } from "../../../../scripts/lib/json-schema.mjs";
+import { validateBackendScaffoldPrerequisites } from "../../../../scripts/lib/backend-scaffold-prerequisites.mjs";
 
 import {
   findGitRoot,
@@ -205,9 +206,9 @@ class ScaffoldGenerator {
     const contractText = await readFile(this.contractFile, "utf8");
     let contract; try { contract = JSON.parse(contractText); } catch { fail(`脚手架合同文件无法读取或不是合法 JSON: ${this.contractFile}`); }
     if (!contract || Array.isArray(contract) || typeof contract !== "object") fail("脚手架合同必须是 JSON 对象");
-    if (![3, 4].includes(contract.schema_version)) fail(`unsupported: scaffold contract schema_version=${contract.schema_version}；只接受兼容 v3 或统一 v4`);
-    if (contract.schema_version === 4 && (contract.kind !== "project-scaffold-contract" || contract.delivery_role !== "backend" || contract.scaffold_kind !== "backend-ddd")) fail("schema v4 合同必须绑定 backend/backend-ddd");
-    if (contract.schema_version === 4) validateJsonSchema(contract, path.join(REPOSITORY_ROOT, "docs/process/schemas/project-scaffold-contract.schema.json"), { label: "Project Scaffold Contract v4" });
+    if (contract.schema_version !== 4) fail(`unsupported: 后端新生成只接受 Project Scaffold Contract v4，收到 v${contract.schema_version}`);
+    if (contract.kind !== "project-scaffold-contract" || contract.delivery_role !== "backend" || contract.scaffold_kind !== "backend-ddd") fail("schema v4 合同必须绑定 backend/backend-ddd");
+    validateJsonSchema(contract, path.join(REPOSITORY_ROOT, "docs/process/schemas/project-scaffold-contract.schema.json"), { label: "Project Scaffold Contract v4" });
     const requiredMetadata = [["--contract-id", this.options.contractId], ["--contract-version", this.options.contractVersion], ["--approval-ref", this.options.approvalRef], ["--compiler-draft-ref", this.options.compilerDraftRef], ["--persisted-ref", this.options.persistedRef]];
     const missing = requiredMetadata.filter(([, value]) => !isPresent(value)).map(([flag]) => flag);
     if (missing.length) fail(`生成项目必须提供当前已批准脚手架合同的完整元数据: ${missing.join(", ")}`);
@@ -217,7 +218,7 @@ class ScaffoldGenerator {
     if (contract.status !== "approved") fail("脚手架合同必须已由生命周期批准");
     if (contract.contract_id !== this.options.contractId) fail("--contract-id 与脚手架合同不一致");
     if (contract.contract_version !== this.options.contractVersion) fail("--contract-version 与脚手架合同不一致");
-    if (contract.current_version !== contract.contract_version && !(contract.schema_version === 4 && contract.current_version === true)) fail("脚手架合同版本不是当前版本");
+    if (contract.current_version !== true) fail("脚手架合同版本不是当前版本");
     if (contract.compiler_draft_ref !== this.options.compilerDraftRef) fail("--compiler-draft-ref 与脚手架合同不一致");
     if (contract.persisted_ref !== this.options.persistedRef) fail("--persisted-ref 与脚手架合同不一致");
     if (contract.lifecycle_approval_ref !== this.options.approvalRef) fail("--approval-ref 与脚手架合同不一致");
@@ -255,7 +256,8 @@ class ScaffoldGenerator {
     if (!decision || decision.status !== "lifecycle-approved" || decision.confirmed_architecture !== "domain-driven" || decision.project_id !== contract.project_name) fail("架构决策未批准、项目不匹配或不是 domain-driven");
     if (decision.platform_profile !== contract.profiles.platform || decision.architecture_profile !== contract.architecture_profile || decision.verification_database !== "h2" || decision.production_database !== "not-bound" || Object.hasOwn(decision, "database_profile") || JSON.stringify(decision.requested_capabilities) !== JSON.stringify(contract.module_profile.requested_capabilities) || JSON.stringify(decision.resolved_modules) !== JSON.stringify(contract.module_profile.resolved_modules)) fail("架构决策的 Profile 或模块闭包与脚手架合同不一致");
     if (!decision.user_confirmation || Object.values(decision.user_confirmation).some((value) => !isPresent(value))) fail("架构决策缺少完整用户确认记录");
-  assertScaffoldUserDecision(decision);
+    assertScaffoldUserDecision(decision);
+    this.designPrerequisites = await validateBackendScaffoldPrerequisites(contract, { contractFile: this.contractFile });
     const generationPolicy = contract.generation_policy;
     if (!generationPolicy || generationPolicy.mode !== "initialize-only" || generationPolicy.existing_target !== "unsupported" || generationPolicy.old_project_migration !== "unsupported" || generationPolicy.template_upgrade !== "unsupported") fail("脚手架合同 generation_policy 必须声明 initialize-only，且 existing_target、old_project_migration、template_upgrade 均为 unsupported");
     this.contractDigest = sha256(contractText);
@@ -366,8 +368,7 @@ class ScaffoldGenerator {
     }
     const scaffoldParent = path.join(SKILL_ROOT, "references", "yss-backend-scaffold-parent", "SKILL.md");
     const compilerContract = path.join(REPOSITORY_ROOT, ".agents", "skills", "yss-implementation-contract-compiler", "references", "compiler-contract.yaml");
-    const manifest = { schema_version: 3, kind: "backend-scaffold", architecture_profile: contract.architecture_profile, architecture_identity: scaffoldArchitectureIdentity(contract, this.contractDigest), contract_id: this.options.contractId, contract_version: this.options.contractVersion, scaffold_request_id: contract.scaffold_request_id, architecture_family: contract.architecture_family, generator_skill: contract.generator_skill, decision_id: contract.decision_id, decision_digest: contract.decision_digest, module_profile: contract.module_profile, approval_ref: this.options.approvalRef, compiler_draft_ref: this.options.compilerDraftRef, persisted_ref: this.options.persistedRef, contract_file_ref: this.contractFile, contract_digest: this.contractDigest, lifecycle_approval_ref: contract.lifecycle_approval_ref, current_version: contract.current_version, approver: contract.approval.approver, allowed_write_paths: contract.allowed_write_paths, expected_evidence_files: contract.expected_evidence_files, project_name: this.projectName, base_package: this.basePackage, bootstrap_main_class: `${this.basePackage}.${this.applicationClassName}`, bootstrap_main_source: this.bootstrapMainSource, maven_coordinates: this.mavenCoordinates, maven_coordinates_source: this.mavenCoordinatesSource, profiles: this.profiles, generation_mode: "controlled-generation", completion_level: "generated", generator: { id: "yss-ddd-scaffold-generator", template_digest: await treeDigest(path.join(SKILL_ROOT, "assets")) }, ownership: { generated_files: generatedFiles, user_owned_globs: ["**/src/main/java/**", "**/src/test/java/**", "db/**"] }, readiness: { downstream_skills: downstream, contracts: { scaffold_parent: sha256(await readFile(scaffoldParent)), compiler_contract: sha256(await readFile(compilerContract)) }, architecture_ruleset: sha256(await readFile(path.join(this.javaTemplateDir, "architecture-rules-test.java.template"))) }, generation_policy: { mode: "initialize-only", existing_target: "unsupported", old_project_migration: "unsupported", template_upgrade: "unsupported" }, verification_commands: COMMANDS, generated_at: isoNow() };
-    manifest.schema_version = contract.schema_version;
+    const manifest = { schema_version: 4, kind: "backend-scaffold", architecture_profile: contract.architecture_profile, architecture_identity: scaffoldArchitectureIdentity(contract, this.contractDigest), contract_id: this.options.contractId, contract_version: this.options.contractVersion, scaffold_request_id: contract.scaffold_request_id, architecture_family: contract.architecture_family, generator_skill: contract.generator_skill, decision_id: contract.decision_id, decision_digest: contract.decision_digest, module_profile: contract.module_profile, design_prerequisites: this.designPrerequisites, approval_ref: this.options.approvalRef, compiler_draft_ref: this.options.compilerDraftRef, persisted_ref: this.options.persistedRef, contract_file_ref: this.contractFile, contract_digest: this.contractDigest, lifecycle_approval_ref: contract.lifecycle_approval_ref, current_version: contract.current_version, approver: contract.approval.approver, allowed_write_paths: contract.allowed_write_paths, expected_evidence_files: contract.expected_evidence_files, project_name: this.projectName, base_package: this.basePackage, bootstrap_main_class: `${this.basePackage}.${this.applicationClassName}`, bootstrap_main_source: this.bootstrapMainSource, maven_coordinates: this.mavenCoordinates, maven_coordinates_source: this.mavenCoordinatesSource, profiles: this.profiles, generation_mode: "controlled-generation", completion_level: "generated", generator: { id: "yss-ddd-scaffold-generator", template_digest: await treeDigest(path.join(SKILL_ROOT, "assets")) }, ownership: { generated_files: generatedFiles, user_owned_globs: ["**/src/main/java/**", "**/src/test/java/**", "db/**"] }, readiness: { downstream_skills: downstream, contracts: { scaffold_parent: sha256(await readFile(scaffoldParent)), compiler_contract: sha256(await readFile(compilerContract)) }, architecture_ruleset: sha256(await readFile(path.join(this.javaTemplateDir, "architecture-rules-test.java.template"))) }, generation_policy: { mode: "initialize-only", existing_target: "unsupported", old_project_migration: "unsupported", template_upgrade: "unsupported" }, verification_commands: COMMANDS, generated_at: isoNow() };
     await writeText(path.join(this.projectRoot, ".yss", "scaffold-generation.json"), `${JSON.stringify(manifest, null, 2)}\n`); console.log("  ✓ .yss/scaffold-generation.json");
   }
   async copyWrapperFiles() {
@@ -379,7 +380,7 @@ class ScaffoldGenerator {
     const required = [path.join(this.projectRoot, "pom.xml"), path.join(this.projectRoot, `${this.projectName}-bootstrap`, "pom.xml"), path.join(this.projectRoot, this.bootstrapMainSource), path.join(this.projectRoot, "mvnw"), path.join(this.projectRoot, ".yss", "scaffold-generation.json")];
     const missing = []; for (const target of required) if (!await isFile(target)) missing.push(target); if (missing.length) fail(`生成产物缺失: ${missing.join(", ")}`);
     const manifest = await readJson(required[4], "脚手架生成元数据清单无法读取");
-    if (![3, 4].includes(manifest.schema_version) || manifest.contract_id !== this.options.contractId || manifest.contract_version !== this.options.contractVersion || (manifest.current_version !== this.options.contractVersion && manifest.current_version !== true) || manifest.generation_mode !== "controlled-generation" || manifest.architecture_family !== "domain-driven" || manifest.generator_skill !== "yss-ddd-scaffold-generator" || manifest.decision_id !== this.scaffoldContract.decision_id || manifest.decision_digest !== this.scaffoldContract.decision_digest || JSON.stringify(manifest.module_profile) !== JSON.stringify(this.scaffoldContract.module_profile) || manifest.bootstrap_main_class !== `${this.basePackage}.${this.applicationClassName}` || manifest.bootstrap_main_source !== this.bootstrapMainSource || manifest.profiles.architecture !== SUPPORTED_PROFILES.architecture || manifest.generation_policy.mode !== "initialize-only" || manifest.generation_policy.existing_target !== "unsupported" || JSON.stringify(manifest.verification_commands) !== JSON.stringify(COMMANDS)) fail("脚手架生成元数据清单与当前批准架构决策、合同、Target Profile、initialize-only 边界、机械启动入口或固定验证命令不一致");
+    if (manifest.schema_version !== 4 || manifest.contract_id !== this.options.contractId || manifest.contract_version !== this.options.contractVersion || manifest.current_version !== true || manifest.generation_mode !== "controlled-generation" || manifest.architecture_family !== "domain-driven" || manifest.generator_skill !== "yss-ddd-scaffold-generator" || manifest.decision_id !== this.scaffoldContract.decision_id || manifest.decision_digest !== this.scaffoldContract.decision_digest || JSON.stringify(manifest.module_profile) !== JSON.stringify(this.scaffoldContract.module_profile) || JSON.stringify(manifest.design_prerequisites) !== JSON.stringify(this.designPrerequisites) || manifest.bootstrap_main_class !== `${this.basePackage}.${this.applicationClassName}` || manifest.bootstrap_main_source !== this.bootstrapMainSource || manifest.profiles.architecture !== SUPPORTED_PROFILES.architecture || manifest.generation_policy.mode !== "initialize-only" || manifest.generation_policy.existing_target !== "unsupported" || JSON.stringify(manifest.verification_commands) !== JSON.stringify(COMMANDS)) fail("脚手架生成元数据清单与当前批准设计、架构决策、合同、Target Profile、initialize-only 边界、机械启动入口或固定验证命令不一致");
     const stack = [this.projectRoot], binary = new Set([".class", ".db", ".jar", ".png", ".jpg", ".jpeg", ".gif"]);
     while (stack.length) { const dir = stack.pop(); for (const entry of await readdir(dir, { withFileTypes: true })) { const target = path.join(dir, entry.name); if (entry.isDirectory()) { stack.push(target); continue; } if (!entry.isFile() || binary.has(path.extname(entry.name))) continue; const content = await readFile(target, "utf8"); if (content.includes("{{") || content.includes("root/root")) fail(`生成文件包含未替换占位符或明文凭据: ${target}`); } }
   }

package/template/.agents/skills/yss-ddd-scaffold-generator/scripts/run_first_slice_verification.mjs

@@ -133,7 +133,8 @@ export async function runFirstSliceVerification(projectRoot, evidenceDir, sliceC
     assertArchitectureAgreement(identity, { manifest });
     for (const unit of contract.work_units ?? []) assertArchitectureAgreement(identity, { work_unit: unit.architecture_identity });
   } catch (error) { contractFailures.push(`architecture-identity:${error.message}`); }
-  if (![2, 3].includes(manifest.schema_version) || manifest.completion_level !== "empty-scaffold-verified") contractFailures.push("scaffold-not-empty-scaffold-verified");
+  if (![2, 3, 4].includes(manifest.schema_version) || manifest.completion_level !== "empty-scaffold-verified") contractFailures.push("scaffold-not-empty-scaffold-verified");
+  if (manifest.schema_version === 3 && manifest.legacy_reconciliation?.status !== "approved") contractFailures.push("legacy-scaffold-reconciliation-required");
   const projectFiles = await files(projectRoot);
   const missingArtifacts = adapter.artifacts.filter(([, pattern]) => !projectFiles.some((file) => pattern.test(file))).map(([name]) => name);
   const skillDrift = await downstreamDrift(manifest, adapter.skills);

package/template/.agents/skills/yss-ddd-scaffold-generator/scripts/run_scaffold_verification.mjs

@@ -41,20 +41,22 @@ function parseArgs(argv) { const result = {}; for (let index = 0; index < argv.l
 function validateManifest(manifest) {
   if (![2, 3, 4].includes(manifest.schema_version)) throw new Error(`unsupported: scaffold Manifest schema_version=${manifest.schema_version}；只读兼容 v2，并验证当前 v3/v4`);
   const required = ["schema_version", "contract_id", "contract_version", "scaffold_request_id", "contract_digest", "profiles", "ownership", "readiness", "generation_policy", "completion_level", "approval_ref", "approver", "lifecycle_approval_ref", "compiler_draft_ref", "persisted_ref", "contract_file_ref", "current_version", "allowed_write_paths", "expected_evidence_files", "verification_commands", "generation_mode"];
-  if (manifest.schema_version === 3) required.push("architecture_family", "generator_skill", "decision_id", "decision_digest", "module_profile");
+  if (manifest.schema_version >= 3) required.push("architecture_family", "generator_skill", "decision_id", "decision_digest", "module_profile");
+  if (manifest.schema_version === 4) required.push("design_prerequisites");
   const missing = required.filter((field) => manifest[field] === undefined || manifest[field] === null || manifest[field] === "");
   if (manifest.generation_mode !== "controlled-generation" || missing.length) throw new Error(`脚手架生成元数据清单不完整或不是 controlled-generation: ${missing.join(", ")}`);
-  if (manifest.schema_version === 3) {
+  if (manifest.schema_version >= 3) {
     if (manifest.kind || manifest.architecture_identity) {
       assertLocalDatabaseProfile(manifest.profiles);
       assertArchitectureAgreement(manifest.architecture_identity, { manifest_fields: scaffoldArchitectureIdentity(manifest, manifest.contract_digest) });
     }
     const supportedArchitecture = manifest.architecture_family === "domain-driven" && manifest.generator_skill === "yss-ddd-scaffold-generator" && manifest.profiles.architecture === "target-domain-model"
       || manifest.architecture_family === "layered-mvc" && ["yss-layered-mvc-scaffold-generator", "yss-mvc-data-analysis-project-initializer"].includes(manifest.generator_skill) && manifest.profiles.architecture === "layered-mvc";
-    if (!supportedArchitecture || manifest.module_profile?.resolution_version !== 1 || !Array.isArray(manifest.module_profile?.resolved_modules)) throw new Error("Manifest v3 的架构族、生成器、Profile 或模块闭包不一致");
+    if (!supportedArchitecture || manifest.module_profile?.resolution_version !== 1 || !Array.isArray(manifest.module_profile?.resolved_modules)) throw new Error("Manifest v3/v4 的架构族、生成器、Profile 或模块闭包不一致");
+    if (manifest.schema_version === 4 && (!manifest.design_prerequisites?.technical_design || !manifest.design_prerequisites?.data_architecture_decision || !manifest.design_prerequisites?.engineering_contract_approval_ref)) throw new Error("Manifest v4 缺少设计门禁绑定");
   } else if (manifest.profiles.architecture !== "target-domain-model") throw new Error("历史 Manifest v2 只读兼容仅支持 target-domain-model");
   if (manifest.generation_policy.mode !== "initialize-only" || manifest.generation_policy.existing_target !== "unsupported" || manifest.generation_policy.old_project_migration !== "unsupported" || manifest.generation_policy.template_upgrade !== "unsupported") throw new Error("Manifest 必须声明严格 initialize-only；已有目标、旧项目迁移和模板升级均须为 unsupported");
-  if (manifest.current_version !== manifest.contract_version) throw new Error("脚手架生成元数据清单不是当前合同版本");
+  if (manifest.schema_version === 4 ? manifest.current_version !== true : manifest.current_version !== manifest.contract_version) throw new Error("脚手架生成元数据清单不是当前合同版本");
   if (JSON.stringify(manifest.verification_commands) !== JSON.stringify(COMMANDS)) throw new Error("脚手架生成元数据清单验证命令不符合固定合同");
 }
 export async function run(projectRoot, evidenceDir, environment = process.env, { timeoutMs = 0, signal } = {}) {

package/template/.agents/skills/yss-ddd-scaffold-generator/scripts/scaffold-generator.test.mjs

@@ -11,6 +11,7 @@ import { fileURLToPath } from "node:url";
 import { run } from "./run_scaffold_verification.mjs";
 import { makeGitlinkFixture } from "../../../../scripts/lib/git-submodule-fixtures.mjs";
 import { GITLINK_MODE, gitLsFilesStage } from "../../../../scripts/lib/repository-scope-policy.mjs";
+import { attachDesignPrerequisites } from "../../../../scripts/fixtures/backend-scaffold/design-prerequisites.mjs";
 
 const scripts = path.dirname(fileURLToPath(import.meta.url));
 const generator = path.join(scripts, "generate_scaffold.mjs");
@@ -31,7 +32,12 @@ async function treeDigest(root) {
 }
 function contract(outputDir, overrides = {}) {
   return {
-    schema_version: 3,
+    schema_version: 4,
+    kind: "project-scaffold-contract",
+    delivery_role: "backend",
+    scaffold_kind: "backend-ddd",
+    repository_scope: "external-repository",
+    init_git: false,
     contract_id: "scaffold-1",
     contract_version: 1,
     scaffold_request_id: "scaffold-request-1",
@@ -39,7 +45,7 @@ function contract(outputDir, overrides = {}) {
     compiler_draft_ref: "compiler-1",
     lifecycle_approval_ref: "approval-1",
     persisted_ref: "persisted-1",
-    current_version: 1,
+    current_version: true,
     implementation_repository: "external",
     backend_repository: "external",
     scaffold_status: "required",
@@ -87,9 +93,13 @@ async function fixture(contractOverrides = {}) {
   decisionText = JSON.stringify(decisionSet, null, 2) + "\n";
   await writeFile(decisionFile, decisionText);
   const decisionDigest = `sha256:${createHash("sha256").update(decisionText).digest("hex")}`;
+  const scaffoldContract = contract(output, { decision_digest: decisionDigest, ...contractOverrides });
+  const design = attachDesignPrerequisites(root, scaffoldContract, { dataImpact: contractOverrides.dataImpact ?? "not-applicable", apiImpact: contractOverrides.apiImpact ?? "not-applicable" });
+  delete scaffoldContract.dataImpact;
+  delete scaffoldContract.apiImpact;
   const contractFile = path.join(root, "contract.json");
-  await writeFile(contractFile, `${JSON.stringify(contract(output, { decision_digest: decisionDigest, ...contractOverrides }), null, 2)}\n`);
-  return { root, output, contractFile, decisionFile, args: ["--project-name", "demo-service", "--base-package", "com.yss.demo", "--output-dir", output, "--contract-id", "scaffold-1", "--contract-version", "1", "--approval-ref", "approval-1", "--compiler-draft-ref", "compiler-1", "--persisted-ref", "persisted-1", "--contract-file", contractFile, "--group-id", "com.yss.datamiddle", "--project-version", "1.0.0-SNAPSHOT", "--parent-group-id", "com.yss.datamiddle", "--parent-artifact-id", "yss-datamiddle-parent", "--parent-version", "2.0.0-SNAPSHOT", "--yss-components-version", "2.0.0-SNAPSHOT"] };
+  await writeFile(contractFile, `${JSON.stringify(scaffoldContract, null, 2)}\n`);
+  return { root, output, contractFile, decisionFile, contract: scaffoldContract, design, args: ["--project-name", "demo-service", "--base-package", "com.yss.demo", "--output-dir", output, "--contract-id", "scaffold-1", "--contract-version", "1", "--approval-ref", scaffoldContract.lifecycle_approval_ref, "--compiler-draft-ref", "compiler-1", "--persisted-ref", "persisted-1", "--contract-file", contractFile, "--group-id", "com.yss.datamiddle", "--project-version", "1.0.0-SNAPSHOT", "--parent-group-id", "com.yss.datamiddle", "--parent-artifact-id", "yss-datamiddle-parent", "--parent-version", "2.0.0-SNAPSHOT", "--yss-components-version", "2.0.0-SNAPSHOT"] };
 }
 
 const controlledEnvironment = {
@@ -100,7 +110,7 @@ const controlledEnvironment = {
 };
 function targetManifest(overrides = {}) {
   return {
-    schema_version: 3,
+    schema_version: 4,
     contract_id: "id",
     contract_version: 1,
     scaffold_request_id: "request",
@@ -111,7 +121,7 @@ function targetManifest(overrides = {}) {
     compiler_draft_ref: "router",
     persisted_ref: "persisted",
     contract_file_ref: "contract",
-    current_version: 1,
+    current_version: true,
     allowed_write_paths: ["."],
     expected_evidence_files: ["manifest"],
     verification_commands: ["./mvnw validate", "./mvnw test", "./mvnw package"],
@@ -122,6 +132,7 @@ function targetManifest(overrides = {}) {
     decision_id: "scaffold-decision.demo-service",
     decision_digest: `sha256:${"a".repeat(64)}`,
     module_profile: { resolution_version: 1, requested_capabilities: [], resolved_modules: ["domain", "application", "infrastructure", "adapter", "bootstrap"] },
+    design_prerequisites: { technical_design: { ref: "technical.json", version: "v1", digest: `sha256:${"b".repeat(64)}` }, data_architecture_decision: { ref: "data.json", version: "v1", digest: `sha256:${"c".repeat(64)}`, impact: "not-applicable" }, api_contract_decision: { ref: "api.json", version: "v1", digest: `sha256:${"d".repeat(64)}`, impact: "not-applicable" }, engineering_contract_approval_ref: "approval.json" },
     profiles: { architecture: "target-domain-model", repository: "yss-internal" },
     ownership: { generated_files: [] },
     readiness: { downstream_skills: {}, architecture_ruleset: "b".repeat(64) },
@@ -138,15 +149,100 @@ async function prepareVerifierProject(project, manifest = targetManifest()) {
   await writeFile(path.join(project, ".yss", "scaffold-generation.json"), `${JSON.stringify(manifest)}\n`);
 }
 
-test("生成批准的服务级 target profile 骨架，并写入可追溯 Manifest v3", async (t) => { const data = await fixture(); t.after(() => rm(data.root, { recursive: true, force: true })); const result = await command(data.args); assert.equal(result.code, 0, result.stderr); const project = path.join(data.output, "demo-service"); const manifest = JSON.parse(await readFile(path.join(project, ".yss/scaffold-generation.json"), "utf8")); assert.equal(manifest.schema_version, 3); assert.equal(manifest.architecture_family, "domain-driven"); assert.equal(manifest.generator_skill, "yss-ddd-scaffold-generator"); assert.equal(manifest.decision_id, "scaffold-decision.demo-service"); assert.equal(manifest.scaffold_request_id, "scaffold-request-1"); assert.equal(manifest.slice_id, undefined); assert.equal(manifest.completion_level, "generated"); assert.equal(manifest.profiles.architecture, "target-domain-model"); assert.deepEqual(manifest.generation_policy, { mode: "initialize-only", existing_target: "unsupported", old_project_migration: "unsupported", template_upgrade: "unsupported" }); assert.match(manifest.generator.template_digest, /^[a-f0-9]{64}$/); assert.match(manifest.contract_digest, /^[a-f0-9]{64}$/); assert.ok(manifest.ownership.generated_files.length > 8); assert.ok(manifest.ownership.generated_files.every((item) => item.owner === "generator" && /^[a-f0-9]{64}$/.test(item.sha256))); assert.equal(manifest.generation_mode, "controlled-generation"); assert.deepEqual(manifest.verification_commands, ["./mvnw validate", "./mvnw test", "./mvnw package"]); assert.equal(manifest.bootstrap_main_class, "com.yss.demo.DemoServiceApplication"); assert.equal(manifest.bootstrap_main_source, "demo-service-bootstrap/src/main/java/com/yss/demo/DemoServiceApplication.java"); assert.match(await readFile(path.join(project, manifest.bootstrap_main_source), "utf8"), /class DemoServiceApplication/); assert.match(await readFile(path.join(project, "pom.xml"), "utf8"), /demo-service/); assert.equal(manifest.readiness.downstream_skills["yss-domain"], await treeDigest(path.resolve(scripts, "../../yss-domain"))); assert.match(manifest.readiness.contracts.scaffold_parent, /^[a-f0-9]{64}$/); assert.match(manifest.readiness.contracts.compiler_contract, /^[a-f0-9]{64}$/); });
+test("生成批准的服务级 target profile 骨架，并写入带设计门禁的 Manifest v4", async (t) => { const data = await fixture(); t.after(() => rm(data.root, { recursive: true, force: true })); const result = await command(data.args); assert.equal(result.code, 0, result.stderr); const project = path.join(data.output, "demo-service"); const manifest = JSON.parse(await readFile(path.join(project, ".yss/scaffold-generation.json"), "utf8")); assert.equal(manifest.schema_version, 4); assert.equal(manifest.architecture_family, "domain-driven"); assert.equal(manifest.generator_skill, "yss-ddd-scaffold-generator"); assert.equal(manifest.decision_id, "scaffold-decision.demo-service"); assert.equal(manifest.scaffold_request_id, "scaffold-request-1"); assert.equal(manifest.slice_id, undefined); assert.equal(manifest.completion_level, "generated"); assert.equal(manifest.profiles.architecture, "target-domain-model"); assert.deepEqual(manifest.design_prerequisites, { ...data.contract.design_prerequisites, data_architecture_decision: { ...data.contract.design_prerequisites.data_architecture_decision, impact: "not-applicable" } }); assert.deepEqual(manifest.generation_policy, { mode: "initialize-only", existing_target: "unsupported", old_project_migration: "unsupported", template_upgrade: "unsupported" }); assert.match(manifest.generator.template_digest, /^[a-f0-9]{64}$/); assert.match(manifest.contract_digest, /^[a-f0-9]{64}$/); assert.ok(manifest.ownership.generated_files.length > 8); assert.ok(manifest.ownership.generated_files.every((item) => item.owner === "generator" && /^[a-f0-9]{64}$/.test(item.sha256))); assert.equal(manifest.generation_mode, "controlled-generation"); assert.deepEqual(manifest.verification_commands, ["./mvnw validate", "./mvnw test", "./mvnw package"]); assert.equal(manifest.bootstrap_main_class, "com.yss.demo.DemoServiceApplication"); assert.equal(manifest.bootstrap_main_source, "demo-service-bootstrap/src/main/java/com/yss/demo/DemoServiceApplication.java"); assert.match(await readFile(path.join(project, manifest.bootstrap_main_source), "utf8"), /class DemoServiceApplication/); assert.match(await readFile(path.join(project, "pom.xml"), "utf8"), /demo-service/); assert.equal(manifest.readiness.downstream_skills["yss-domain"], await treeDigest(path.resolve(scripts, "../../yss-domain"))); assert.match(manifest.readiness.contracts.scaffold_parent, /^[a-f0-9]{64}$/); assert.match(manifest.readiness.contracts.compiler_contract, /^[a-f0-9]{64}$/); });
 
-test("统一 Project Scaffold Contract v4 可生成 DDD 后端并保留 v4 Manifest", async (t) => {
-  const data = await fixture({ schema_version: 4, kind: "project-scaffold-contract", delivery_role: "backend", scaffold_kind: "backend-ddd", repository_scope: "external-repository", init_git: false, current_version: true });
+test("数据影响为 required 时绑定数据架构后可生成 DDD 后端", async (t) => {
+  const data = await fixture({ dataImpact: "required" });
   t.after(() => rm(data.root, { recursive: true, force: true }));
   const result = await command(data.args);
   assert.equal(result.code, 0, result.stderr);
   const manifest = JSON.parse(await readFile(path.join(data.output, "demo-service", ".yss/scaffold-generation.json"), "utf8"));
   assert.equal(manifest.schema_version, 4);
+  assert.equal(manifest.design_prerequisites.data_architecture_decision.impact, "required");
+});
+
+test("API 影响为 required 时绑定同字节 Draft、Validation、Review 和 Freeze 后可生成 DDD 后端", async (t) => {
+  const data = await fixture({ apiImpact: "required" });
+  t.after(() => rm(data.root, { recursive: true, force: true }));
+  const result = await command(data.args);
+  assert.equal(result.code, 0, result.stderr);
+  const manifest = JSON.parse(await readFile(path.join(data.output, "demo-service", ".yss/scaffold-generation.json"), "utf8"));
+  assert.equal(manifest.design_prerequisites.api_contract_decision.impact, "required");
+});
+
+test("缺少设计门禁时在写文件前拒绝 DDD 新生成", async (t) => {
+  const data = await fixture();
+  t.after(() => rm(data.root, { recursive: true, force: true }));
+  delete data.contract.design_prerequisites;
+  await writeFile(data.contractFile, `${JSON.stringify(data.contract, null, 2)}\n`);
+  const result = await command(data.args);
+  assert.equal(result.code, 1);
+  assert.match(result.stderr, /design_prerequisites|Technical Design/);
+  assert.equal(existsSync(path.join(data.output, "demo-service")), false);
+});
+
+test("技术和数据设计齐全但缺少 API Decision 时在写文件前拒绝 DDD 新生成", async (t) => {
+  const data = await fixture();
+  t.after(() => rm(data.root, { recursive: true, force: true }));
+  delete data.contract.design_prerequisites.api_contract_decision;
+  await writeFile(data.contractFile, `${JSON.stringify(data.contract, null, 2)}\n`);
+  const result = await command(data.args);
+  assert.equal(result.code, 1);
+  assert.match(result.stderr, /API Contract Decision|api_contract_decision/);
+  assert.equal(existsSync(path.join(data.output, "demo-service")), false);
+});
+
+test("API Draft、Validation、Review 或工程批准漂移时均在零写入状态阻断 DDD", async (t) => {
+  const mutations = [
+    ["OpenAPI YAML 摘要漂移", async (data) => writeFile(data.design.openapi.file, "\n# drift\n", { flag: "a" })],
+    ["Redocly Validation 失败", async (data) => {
+      const decision = JSON.parse(await readFile(data.design.api.file, "utf8"));
+      const validationFile = path.join(data.root, decision.validation_record.ref);
+      const validation = JSON.parse(await readFile(validationFile, "utf8"));
+      validation.status = "blocked";
+      validation.toolchain.exit_code = 1;
+      validation.checks.lint = "blocked";
+      await writeFile(validationFile, `${JSON.stringify(validation, null, 2)}\n`);
+      decision.validation_record.digest = `sha256:${createHash("sha256").update(await readFile(validationFile)).digest("hex")}`;
+      await writeFile(data.design.api.file, `${JSON.stringify(decision, null, 2)}\n`);
+      data.contract.design_prerequisites.api_contract_decision.digest = `sha256:${createHash("sha256").update(await readFile(data.design.api.file)).digest("hex")}`;
+      await writeFile(data.contractFile, `${JSON.stringify(data.contract, null, 2)}\n`);
+    }],
+    ["Draft Review blocked", async (data) => {
+      const decision = JSON.parse(await readFile(data.design.api.file, "utf8"));
+      const reviewFile = path.join(data.root, decision.draft_review.ref);
+      const review = JSON.parse(await readFile(reviewFile, "utf8"));
+      review.result = "blocked";
+      review.blocking_findings = ["breaking response"];
+      await writeFile(reviewFile, `${JSON.stringify(review, null, 2)}\n`);
+      decision.draft_review.digest = `sha256:${createHash("sha256").update(await readFile(reviewFile)).digest("hex")}`;
+      await writeFile(data.design.api.file, `${JSON.stringify(decision, null, 2)}\n`);
+      data.contract.design_prerequisites.api_contract_decision.digest = `sha256:${createHash("sha256").update(await readFile(data.design.api.file)).digest("hex")}`;
+      await writeFile(data.contractFile, `${JSON.stringify(data.contract, null, 2)}\n`);
+    }],
+    ["工程批准未绑定 API Decision", async (data) => {
+      const approval = JSON.parse(await readFile(data.design.approval.file, "utf8"));
+      approval.artifact_bindings = approval.artifact_bindings.filter((item) => !item.id.startsWith("api-contract."));
+      await writeFile(data.design.approval.file, `${JSON.stringify(approval, null, 2)}\n`);
+    }],
+  ];
+  for (const [name, mutate] of mutations) {
+    const data = await fixture({ apiImpact: "required" });
+    t.after(() => rm(data.root, { recursive: true, force: true }));
+    await mutate(data);
+    const result = await command(data.args);
+    assert.equal(result.code, 1, `${name}: ${result.stderr}`);
+    assert.equal(existsSync(path.join(data.output, "demo-service")), false, name);
+  }
+});
+
+test("schema v3 只读兼容但禁止用于 DDD 新生成", async (t) => {
+  const data = await fixture({ schema_version: 3, current_version: 1 });
+  t.after(() => rm(data.root, { recursive: true, force: true }));
+  const result = await command(data.args);
+  assert.equal(result.code, 1);
+  assert.match(result.stderr, /只接受 Project Scaffold Contract v4|新生成/);
+  assert.equal(existsSync(path.join(data.output, "demo-service")), false);
 });
 
 test("schema v1 scaffold contract is unsupported and is never upgraded", async (t) => {
@@ -154,7 +250,7 @@ test("schema v1 scaffold contract is unsupported and is never upgraded", async (
   t.after(() => rm(data.root, { recursive: true, force: true }));
   const result = await command(data.args);
   assert.equal(result.code, 1);
-  assert.match(result.stderr, /unsupported: scaffold contract schema_version=1/);
+  assert.match(result.stderr, /只接受 Project Scaffold Contract v4/);
   assert.equal(existsSync(path.join(data.output, "demo-service")), false);
 });
 
@@ -395,11 +491,11 @@ test("验证器单独标记 Java 编译失败和 Bootstrap 主类缺失", async
 
 test("验证器在全部 Maven 命令成功时通过并保留日志引用", async (t) => { const root = await mkdtemp(path.join(os.tmpdir(), "yss-scaffold-verifier-success-")); t.after(() => rm(root, { recursive: true, force: true })); const project = path.join(root, "project"); await prepareVerifierProject(project); const wrapper = path.join(project, "mvnw"); await writeFile(wrapper, "#!/bin/sh\nprintf 'ran %s\\n' \"$1\"\n"); await chmod(wrapper, 0o755); const report = await run(project, path.join(root, "evidence"), controlledEnvironment); assert.equal(report.status, "passed"); assert.ok(report.commands.every((item) => item.exit_code === 0 && item.stdout_ref.endsWith(".stdout.log"))); });
 
-test("Manifest v3 在缺少受控仓库环境时先于 Maven 执行阻断", async (t) => {
+test("历史 Manifest v3 只读校验仍在缺少受控仓库环境时先于 Maven 阻断", async (t) => {
   const root = await mkdtemp(path.join(os.tmpdir(), "yss-scaffold-v2-preflight-"));
   t.after(() => rm(root, { recursive: true, force: true }));
   const project = path.join(root, "project");
-  await prepareVerifierProject(project);
+  await prepareVerifierProject(project, targetManifest({ schema_version: 3, current_version: 1, design_prerequisites: undefined }));
   const wrapper = path.join(project, "mvnw");
   await writeFile(wrapper, "#!/bin/sh\nprintf 'must not run'\nexit 99\n");
   await chmod(wrapper, 0o755);