create-yss-spec 3.3.8 → 3.4.3

package/template/.codex/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/.codex/skills/yss-ddd-scaffold-generator/references/yss-backend-scaffold-parent/SKILL.md

@@ -11,9 +11,9 @@ description: YSS DDD scaffold Engineering Baseline entry for profile, module, de
 
 - Architecture: `target-domain-model`
 - Persistence: `mybatis-plus`
-- Database: `mysql`
-- Platform: `spring-boot-2.7-jdk8`
-- Validation namespace: `javax`
+- Verification database: `h2`; production database: `not-bound`
+- Platform: approved `platform_configuration` v2 from the shared backend platform catalog
+- Validation namespace: derived from that platform (`javax` for Boot 2.7; `jakarta` for Boot 3.5/4.1)
 - DTO placement: `web`
 - Repository: `yss-internal`
 
@@ -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/.codex/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,15 +75,22 @@ 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 generated = await execute(process.execPath, [generator, ...args]);
+  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, [path.resolve(scripts, "../../../../scripts/fixtures/backend-scaffold/generate-candidate.mjs"), generator, ...args]);
   assert.equal(generated.code, 0, generated.stderr);
   const project = path.join(output, "golden-service");
   const manifestPath = path.join(project, ".yss", "scaffold-generation.json");
   const emptyVerificationPath = path.join(root, "empty-scaffold-verification.json");
   await writeFile(emptyVerificationPath, JSON.stringify({ status: "passed", completion_level: "empty-scaffold-verified", commands: ["./mvnw validate", "./mvnw test", "./mvnw package"] }));
   const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+  // Legacy Manifest compatibility fixture only; this does not qualify a new platform.
+  delete manifest.platform_configuration;
+  delete manifest.platform_verification;
+  delete manifest.architecture_identity.platform_configuration;
   manifest.completion_level = "empty-scaffold-verified";
   manifest.empty_scaffold_verification_ref = emptyVerificationPath;
   await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);

package/template/.codex/skills/yss-ddd-scaffold-generator/scripts/first-slice-verification.test.mjs

@@ -54,7 +54,9 @@ async function fixture({ omitGatewayImpl = false, omitReadiness = false } = {})
   const manifestPath = path.join(project, ".yss", "scaffold-generation.json");
   const contractPath = path.join(root, "slice-contract.json");
   await mkdir(path.dirname(manifestPath), { recursive: true });
+  const architectureIdentity = { architecture_family: "domain-driven", architecture_profile: "target-domain-model", generator_skill: "yss-ddd-scaffold-generator", requested_capabilities: [], resolved_modules: ["domain", "application", "infrastructure", "adapter", "bootstrap"], contract_digest: "a".repeat(64), verification_database: "h2", production_database: "not-bound" };
   await writeFile(manifestPath, JSON.stringify({
+    architecture_identity: architectureIdentity,
     schema_version: 2,
     contract_id: "scaffold-1",
     contract_version: 1,
@@ -79,7 +81,8 @@ async function fixture({ omitGatewayImpl = false, omitReadiness = false } = {})
     maven_coordinates_source: "approved-contract"
   }));
   await writeFile(contractPath, JSON.stringify({
-    schema_version: 1,
+    architecture_identity: architectureIdentity,
+    schema_version: 2,
     contract_id: "slice-1",
     contract_version: 1,
     slice_id: "quality-rule-first-slice",
@@ -87,7 +90,7 @@ async function fixture({ omitGatewayImpl = false, omitReadiness = false } = {})
     readiness: { blockers: [], stale_inputs: [] },
     common: { required_skills: requiredSkills },
     backend: { status: "required", affected_layers: ["domain", "application", "infrastructure", "web"], required_skills: requiredSkills },
-    work_units: [{ id: "slice-backend", contract_id: "slice-1", contract_version: 1, work_unit: { primary_skill: "yss-domain" } }]
+    work_units: [{ architecture_identity: architectureIdentity, id: "slice-backend", contract_id: "slice-1", contract_version: 1, work_unit: { primary_skill: "yss-domain" } }]
   }));
   await write(project, "mvnw", "#!/bin/sh\nexit 0\n");
   await chmod(path.join(project, "mvnw"), 0o755);

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

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
 /** YSS DDD 后端纯工程骨架生成器；只生成工程结构，不生成任何业务行为。 */
+import { platformSourceFingerprint, generatedTreeDigest } from "../../../../scripts/lib/backend-platform-provenance.mjs";
+import { assertContractPlatform, platformTemplateVars, platformSmokeTest } from "../../../../scripts/lib/backend-platform.mjs";
 import { assertScaffoldUserDecision } from "../../../../scripts/lib/user-decision.mjs";
 import { createHash } from "node:crypto";
 import { chmod, cp, lstat, mkdir, mkdtemp, readFile, readdir, rename, rm, stat, writeFile, copyFile } from "node:fs/promises";
@@ -10,6 +12,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,
@@ -26,8 +29,6 @@ const SUPPORTED_PROFILES = Object.freeze({
   persistence: "mybatis-plus",
   verification_database: "h2",
   production_database: "not-bound",
-  platform: "spring-boot-2.7-jdk8",
-  validation_namespace: "javax",
   dto_placement: "web",
   repository: "yss-internal"
 });
@@ -55,14 +56,14 @@ function usage(error) {
     `用法: node scripts/generate_scaffold.mjs --project-name <kebab-case> --base-package <package> --output-dir <dir> --contract-file <json> [选项]\n\n` +
     `必填合同元数据: --contract-id --contract-version --approval-ref --compiler-draft-ref --persisted-ref\n` +
     `Maven 坐标: --group-id --project-version --parent-group-id --parent-artifact-id --parent-version --yss-components-version\n` +
-    `固定 Profile: target-domain-model / mybatis-plus / spring-boot-2.7-jdk8 / javax / web / yss-internal\n` +
+    `固定 Profile: target-domain-model / mybatis-plus / approved Boot/Java platform / derived validation namespace / web / yss-internal\n` +
     `本生成器严格 initialize-only；--force 和任何已有项目目标均为 unsupported。\n` +
     `--with-example 已禁用；--without-example 仅保留为无操作参数。`;
   if (error) process.stderr.write(`错误: ${error}\n\n`);
   process.stdout.write(`${text}\n`);
 }
 
-function parseArgs(argv) {
+export function parseArgs(argv) {
   const options = { force: false, withExample: false };
   const mapping = new Map([
     ["--project-name", "projectName"], ["--base-package", "basePackage"], ["--output-dir", "outputDir"],
@@ -129,8 +130,9 @@ async function treeDigest(root) {
   return hash.digest("hex");
 }
 
-class ScaffoldGenerator {
-  constructor(options) {
+export class ScaffoldGenerator {
+  constructor(options, platformOptions = {}) {
+    this.platformOptions = platformOptions;
     this.options = options;
     this.projectName = options.projectName;
     this.basePackage = options.basePackage;
@@ -205,9 +207,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 +219,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 +257,9 @@ 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 });
+    this.platform = assertContractPlatform(contract, decision, { ...this.platformOptions, requireVerified: this.platformOptions.candidate !== true }).profile;
     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);
@@ -304,7 +308,7 @@ class ScaffoldGenerator {
 
   templateVars() {
     const coordinates = this.mavenCoordinates;
-    return { project_name: this.projectName, application_class_name: this.applicationClassName, base_package: this.basePackage, group_id: coordinates.group_id, project_version: coordinates.project_version, parent_group_id: coordinates.parent.group_id, parent_artifact_id: coordinates.parent.artifact_id, parent_version: coordinates.parent.version, yss_components_version: coordinates.yss_components_version, project_description: `${this.projectName} service`, author: this.author, date: this.date, db_dependency: "" };
+    return { ...platformTemplateVars(this.platform), project_name: this.projectName, application_class_name: this.applicationClassName, base_package: this.basePackage, group_id: coordinates.group_id, project_version: coordinates.project_version, parent_group_id: coordinates.parent.group_id, parent_artifact_id: coordinates.parent.artifact_id, parent_version: coordinates.parent.version, yss_components_version: coordinates.yss_components_version, project_description: `${this.projectName} service`, author: this.author, date: this.date, db_dependency: "" };
   }
   render(text) { let output = text; for (const [key, value] of Object.entries(this.templateVars())) output = output.replaceAll(`{{${key}}}`, String(value)); return output; }
   async renderTemplate(template, output) { if (!await isFile(template)) fail(`模板文件不存在: ${template}`); await writeText(output, this.render(await readFile(template, "utf8"))); }
@@ -331,6 +335,7 @@ class ScaffoldGenerator {
     const source = path.join(this.javaTemplateDir, "bootstrap-application.java.template");
     const target = path.join(this.projectRoot, this.bootstrapMainSource);
     await this.renderTemplate(source, target);
+    await writeText(path.join(this.projectRoot, `${this.projectName}-bootstrap/src/test/java/${this.basePackage.replaceAll(".", "/")}/PlatformIntegrationTest.java`), platformSmokeTest(this.basePackage, this.platform));
     console.log(`\n☕ 生成机械启动入口...\n  ✓ ${this.applicationClassName}.java`);
   }
   async generateArchitectureRules() {
@@ -349,7 +354,7 @@ class ScaffoldGenerator {
   generateDatabaseScripts() { console.log("\n🗃️  保留数据库目录布局...\n  ✓ db/（业务 schema 和初始化数据由批准切片合同生成）"); }
   async generateDocumentation() {
     console.log("\n📚 生成项目文档...");
-    await writeText(path.join(this.projectRoot, "README.md"), this.render("# {{project_name}}\n\n## 模块说明\n\n- {{project_name}}-domain\n- {{project_name}}-application\n- {{project_name}}-infrastructure\n- {{project_name}}-adapter\n- {{project_name}}-bootstrap\n\n业务 API、领域模型、数据结构和权限行为必须在冻结的 Slice Implementation Contract 下，由对应 YSS skill 逐切片实现。\n\n## 快速开始\n\n```bash\ncd {{project_name}}\n./mvnw clean compile\n./mvnw -Pscaffold-local spring-boot:run -pl {{project_name}}-bootstrap -Dspring-boot.run.profiles=scaffold-local\n```\n"));
+    await writeText(path.join(this.projectRoot, "README.md"), this.render("# {{project_name}}\n\n平台：Spring Boot {{boot_version}} / Java {{java_version}}。\n\n## 模块说明\n\n- {{project_name}}-domain\n- {{project_name}}-application\n- {{project_name}}-infrastructure\n- {{project_name}}-adapter\n- {{project_name}}-bootstrap\n\n业务 API、领域模型、数据结构和权限行为必须在冻结的 Slice Implementation Contract 下，由对应 YSS skill 逐切片实现。\n\n## 快速开始\n\n```bash\ncd {{project_name}}\n./mvnw clean compile\n./mvnw -Pscaffold-local spring-boot:run -pl {{project_name}}-bootstrap -Dspring-boot.run.profiles=scaffold-local\n```\n"));
     console.log("  ✓ README.md");
   }
   async writeGenerationManifest() {
@@ -366,8 +371,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 = { source_fingerprint: platformSourceFingerprint(contract.architecture_family), generated_tree_digest: generatedTreeDigest(this.projectRoot, { ownership: { generated_files: generatedFiles } }), platform_verification: this.platformOptions.candidate === true ? "candidate" : "verified", platform_configuration: contract.platform_configuration, 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,11 +383,11 @@ 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}`); } }
   }
 }
 
 async function main() { let options; try { options = parseArgs(process.argv.slice(2)); if (options.help) { usage(); return 0; } await new ScaffoldGenerator(options).generate(); return 0; } catch (error) { process.stderr.write(`\n❌ 生成失败: ${error.message}\n`); return 1; } }
-process.exitCode = await main();
+if (process.argv[1] === fileURLToPath(import.meta.url)) process.exitCode = await main();

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

@@ -126,6 +126,7 @@ export async function runFirstSliceVerification(projectRoot, evidenceDir, sliceC
   if (!await isFile(sliceContractFile)) throw new Error(`missing Slice Implementation Contract: ${sliceContractFile}`);
   const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
   const contract = JSON.parse(await readFile(sliceContractFile, "utf8"));
+  if (manifest.platform_verification === "candidate") throw new Error("backend-platform: candidate scaffold cannot become first-slice-verified");
   const adapter = manifest.architecture_family === "layered-mvc" ? mvcFirstSliceProfile(manifest.architecture_identity ?? {}) : { skills: REQUIRED_SKILLS, layers: REQUIRED_LAYERS, artifacts: ARTIFACT_CHECKS };
   const contractFailures = invalidContractReasons(contract, adapter.skills, adapter.layers);
   try {
@@ -133,7 +134,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);
@@ -144,7 +146,7 @@ export async function runFirstSliceVerification(projectRoot, evidenceDir, sliceC
   }
 
   const mavenEvidence = path.join(evidenceDir, "maven");
-  const wrapper = await runScaffoldVerification(projectRoot, mavenEvidence, environment);
+  const wrapper = await runScaffoldVerification(projectRoot, mavenEvidence, environment, { firstSlice: true });
   const passed = wrapper.status === "passed";
   const report = { verification_mode: "first-slice", project_root: projectRoot, slice_contract_ref: sliceContractFile, scaffold_manifest_ref: manifestPath, generated_at: isoNow(), status: passed ? "passed" : "failed", failure_category: wrapper.failure_category, completion_level: passed ? "first-slice-verified" : manifest.completion_level, contract_failures: [], missing_artifacts: [], downstream_skill_drift: [], commands: wrapper.commands };
   await writeJsonAtomic(reportPath, report);

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

@@ -1,5 +1,8 @@
 #!/usr/bin/env node
 /** 在生成项目根目录实际执行 YSS 脚手架的固定验证命令并留证。 */
+import { assertSourceFingerprint, generatedTreeDigest } from "../../../../scripts/lib/backend-platform-provenance.mjs";
+import { assertContractPlatform, assertPlatformAgreement, platformDigest } from "../../../../scripts/lib/backend-platform.mjs";
+import { verifyPlatformDependencies, verifyPlatformStartup, verifyPlatformTests, platformEvidenceArtifacts } from "../../../../scripts/lib/backend-platform-verification.mjs";
 import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import process from "node:process";
@@ -41,28 +44,48 @@ 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 } = {}) {
+export async function run(projectRoot, evidenceDir, environment = process.env, { timeoutMs = 0, signal, platformOptions = {}, firstSlice = false } = {}) {
   const wrapper = path.join(projectRoot, "mvnw"), manifestPath = path.join(projectRoot, ".yss", "scaffold-generation.json");
   if (!await isFile(wrapper)) throw new Error(`项目根目录缺少 Maven wrapper: ${wrapper}`);
   if (!await isFile(manifestPath)) throw new Error(`项目根目录缺少脚手架生成元数据清单: ${manifestPath}`);
   let manifest; try { manifest = JSON.parse(await readFile(manifestPath, "utf8")); } catch { throw new Error(`脚手架生成元数据清单无法读取或不是合法 JSON: ${manifestPath}`); }
   validateManifest(manifest);
+  let selectedPlatform, selectedEntry;
+  if (manifest.platform_verification && !manifest.platform_configuration) throw new Error("backend-platform: Manifest missing platform_configuration");
+  if (manifest.platform_configuration) {
+    if (manifest.platform_verification === "candidate" && platformOptions.candidate !== true) throw new Error("backend-platform: candidate scaffold cannot enter production verification");
+    const contractBytes = await readFile(manifest.contract_file_ref);
+    if (platformDigest(contractBytes).replace(/^sha256:/, "") !== manifest.contract_digest.replace(/^sha256:/, "")) throw new Error("backend-platform: contract digest drift");
+    const contract = JSON.parse(contractBytes);
+    assertPlatformAgreement(manifest.platform_configuration, contract.platform_configuration);
+    if (firstSlice) {
+      if (manifest.platform_verification !== "verified" || manifest.completion_level !== "empty-scaffold-verified") throw new Error("backend-platform: first slice requires a verified empty scaffold");
+    } else {
+      const relativeEvidence = path.relative(path.resolve(projectRoot), path.resolve(evidenceDir));
+      if (!relativeEvidence || (!relativeEvidence.startsWith(`..${path.sep}`) && relativeEvidence !== ".." && !path.isAbsolute(relativeEvidence))) throw new Error("backend-platform: empty scaffold evidence must be outside the generated project");
+      assertSourceFingerprint(manifest.source_fingerprint, manifest.architecture_family);
+      if (generatedTreeDigest(projectRoot, manifest) !== manifest.generated_tree_digest) throw new Error("backend-platform: generated tree drift");
+    }
+    ({ profile: selectedPlatform, entry: selectedEntry } = assertContractPlatform(contract, null, { ...platformOptions, requireVerified: platformOptions.candidate !== true }));
+  }
   await mkdir(evidenceDir, { recursive: true });
   const mavenConfig = await readTextIfPresent(path.join(projectRoot, ".mvn", "maven.config"));
   const preflight = {
@@ -84,6 +107,7 @@ export async function run(projectRoot, evidenceDir, environment = process.env, {
   if (!preflight.maven_repository_url_configured) failed.push("repository-url-not-configured");
   if (!preflight.maven_repository_credentials_configured) failed.push("repository-credentials-not-configured");
   if (failed.length) return { verification_mode: "controlled-generation", project_root: projectRoot, scaffold_manifest_ref: manifestPath, generated_at: isoNow(), status: "failed", failure_category: "verification-preflight", completion_level: "generated", preflight: { ...preflight, failures: failed }, commands: [] };
+  const verificationStartedAt = Date.now();
   const commands = [];
   for (const phase of PHASES) {
     const stdoutPath = path.join(evidenceDir, `mvnw-${phase}.stdout.log`);
@@ -107,15 +131,25 @@ export async function run(projectRoot, evidenceDir, environment = process.env, {
       stderr_ref: stderrPath
     });
   }
-  const failureCategory = commands.find((item) => item.failure_category)?.failure_category ?? null;
+  let failureCategory = commands.find((item) => item.failure_category)?.failure_category ?? null;
+  const platformDependencies = selectedPlatform && failureCategory === null ? await verifyPlatformDependencies(projectRoot, evidenceDir, selectedPlatform, environment, { timeoutMs, signal, manifest, components: selectedEntry.components }) : null;
+  if (platformDependencies?.status === "failed") failureCategory = "platform-dependencies";
+  const integrationTests = selectedPlatform && failureCategory === null ? await verifyPlatformTests(projectRoot, evidenceDir, manifest, verificationStartedAt) : null;
+  if (integrationTests?.status === "failed") failureCategory = "platform-integration-tests";
+  const startup = selectedPlatform && failureCategory === null ? await verifyPlatformStartup(projectRoot, evidenceDir, manifest, environment, { timeoutMs, signal, runtimeArtifacts: platformDependencies.runtime_artifacts, providedLombokVersion: selectedPlatform.versions.lombok }) : null;
+  if (startup?.status === "failed") failureCategory = "platform-startup";
+  if (selectedPlatform && !firstSlice && generatedTreeDigest(projectRoot, manifest) !== manifest.generated_tree_digest) throw new Error("backend-platform: Maven modified generated source bytes");
   return {
+    verification_scope: firstSlice ? "first-slice" : "empty-scaffold",
+    ...(selectedPlatform && !firstSlice ? { recipe_digest: manifest.platform_configuration.compatibility_digest, source_fingerprint: manifest.source_fingerprint, generated_tree_digest: manifest.generated_tree_digest, evidence_artifacts: await platformEvidenceArtifacts(evidenceDir), verified_capabilities: manifest.module_profile?.requested_capabilities ?? [], integration_tests: integrationTests } : {}),
+    ...(selectedPlatform ? { spring_boot_version: selectedPlatform.spring_boot_version, java_version: selectedPlatform.java_version, parent: manifest.platform_configuration.parent, bom: manifest.platform_configuration.bom, architecture_family: manifest.architecture_family, platform_dependencies: platformDependencies, dependency_check: platformDependencies?.status ?? "not-executed", startup, startup_check: startup?.status ?? "not-executed", platform_verification: manifest.platform_verification } : {}),
     verification_mode: "controlled-generation",
     project_root: projectRoot,
     scaffold_manifest_ref: manifestPath,
     generated_at: isoNow(),
     status: failureCategory === null ? "passed" : "failed",
     failure_category: failureCategory,
-    completion_level: failureCategory === null ? "empty-scaffold-verified" : "generated",
+    completion_level: firstSlice ? manifest.completion_level : failureCategory === null && manifest.platform_verification !== "candidate" ? "empty-scaffold-verified" : "generated",
     preflight,
     commands
   };