create-yss-spec 3.0.0 → 3.1.0

package/template/.pi/skills/yss-implementation-contract-compiler/tests/compiler-scenarios.test.mjs

@@ -0,0 +1,91 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  compileImplementationContract,
+  digestDocument,
+  evaluateContractFreshness,
+  loadCompilerContract,
+  validateExecutionResult
+} from "../../../../scripts/lib/implementation-contract-compiler.mjs";
+import { loadSkillRegistry } from "../../../../scripts/lib/skill-registry.mjs";
+
+const registry = loadSkillRegistry();
+const compilerContract = loadCompilerContract();
+const fixed = "2026-09-04T00:00:00.000Z";
+const identity = { architecture_family: "domain-driven", architecture_profile: "target-domain-model", generator_skill: "yss-ddd-scaffold-generator", requested_capabilities: [], resolved_modules: ["domain", "application", "infrastructure", "adapter", "bootstrap"], verification_database: "h2", production_database: "not-bound", contract_digest: "a".repeat(64) };
+const architecture = { architecture_identity: identity, architecture_evidence: { engineering_baseline: identity, repository_registration: identity, manifest: identity } };
+const compile = (input) => compileImplementationContract({ registry, compilerContract, compiledAt: fixed, ...architecture, ...input });
+
+test("combines narrow recipes once and preserves deterministic output", () => {
+  const input = {
+    recipeIds: ["backend.ddd-http-api", "backend.ddd-domain-behavior", "backend.ddd-persistence-mybatis"],
+    conditions: ["mybatis", "conversion", "pojo", "request-validation", "error-mapping"]
+  };
+  const first = compile(input);
+  const second = compile({ ...input, recipeIds: [...input.recipeIds].reverse(), conditions: [...input.conditions].reverse() });
+  assert.deepEqual(first, second);
+  assert.deepEqual(first.recipe_ids, ["backend.ddd-domain-behavior", "backend.ddd-persistence-mybatis", "backend.ddd-http-api"]);
+  for (const skill of ["yss-domain", "yss-application", "yss-repository", "yss-mybatis", "yss-web-controller", "yss-dto", "yss-validation", "yss-exception", "mapstruct", "lombok", "alibaba-java-code-style"]) {
+    assert.equal(first.required_skills.filter((candidate) => candidate === skill).length, 1, `${skill} should appear once`);
+  }
+});
+
+test("does not promote conditional or component dependencies without explicit input", () => {
+  const persistence = compile({ requiredCapabilities: ["layer.persistence"] });
+  assert.deepEqual(persistence.required_skills, ["alibaba-java-code-style", "yss-repository"]);
+  assert.equal(persistence.required_skills.includes("yss-mybatis"), false);
+  assert.equal(persistence.required_skills.includes("mapstruct"), false);
+  assert.equal(persistence.required_skills.includes("lombok"), false);
+
+  const validation = compile({ requiredCapabilities: ["contract.request-validation"] });
+  assert.deepEqual(validation.required_skills, ["yss-validation"]);
+  assert.equal(validation.required_skills.includes("yss-exception"), false);
+  assert.ok(validation.non_expanding_dependencies.some((edge) => edge.from === "yss-validation" && edge.skill === "yss-exception"));
+});
+
+test("loads only explicitly satisfied context-conditional dependencies", () => {
+  const persistence = compile({ requiredCapabilities: ["layer.persistence"], conditions: ["mybatis"] });
+  assert.equal(persistence.required_skills.includes("yss-mybatis"), true);
+  assert.equal(persistence.required_skills.includes("mapstruct"), false);
+  assert.equal(persistence.required_skills.includes("lombok"), false);
+});
+
+test("rejects recipes that reference skills and context-required cycles", () => {
+  const invalidRecipeRegistry = structuredClone(registry);
+  invalidRecipeRegistry.recipes[0].skills = ["yss-domain"];
+  assert.throws(() => compileImplementationContract({ ...architecture, registry: invalidRecipeRegistry, compilerContract, recipeIds: [invalidRecipeRegistry.recipes[0].id] }), /不得直接引用 skills/);
+
+  const cyclicRegistry = structuredClone(registry);
+  cyclicRegistry.skill_dependencies["alibaba-java-code-style"] = [{ skill: "yss-domain", type: "context-required" }];
+  assert.throws(() => compileImplementationContract({ ...architecture, registry: cyclicRegistry, compilerContract, requiredCapabilities: ["layer.domain"] }), /依赖循环/);
+});
+
+test("rejects removed ids and schema v1 without compatibility", () => {
+  assert.throws(() => compile({ recipeIds: ["yss-router"] }), /已移除 skill id/);
+  assert.throws(() => compileImplementationContract({ registry: { ...registry, schema_version: 1 }, compilerContract, requiredCapabilities: ["layer.domain"] }), /schema v1 已停止支持/);
+  assert.throws(() => compileImplementationContract({ registry, compilerContract: { ...compilerContract, schema_version: 1 }, requiredCapabilities: ["layer.domain"] }), /schema v1 已停止支持/);
+});
+
+test("marks digest drift stale and validates v2 execution evidence", () => {
+  const resolution = compile({ requiredCapabilities: ["contract.request-validation"], architecture_identity: undefined, architecture_evidence: undefined });
+  const contract = { schema_version: 2, contract_id: "slice-1", contract_version: 1, resolution };
+  assert.deepEqual(evaluateContractFreshness(contract, { registry, compilerContract }), { freshness: "current", reasons: [] });
+  const changedRegistry = structuredClone(registry);
+  changedRegistry.description += " changed";
+  assert.equal(evaluateContractFreshness(contract, { registry: changedRegistry, compilerContract }).freshness, "stale");
+
+  const result = {
+    schema_version: 2,
+    status: "implemented",
+    consumed_contract: {
+      contract_id: "slice-1",
+      contract_version: 1,
+      registry_digest: digestDocument(registry),
+      compiler_contract_digest: digestDocument(compilerContract)
+    },
+    verification_results: [{ command: "./mvnw test", exit_code: 0, executed_at: fixed }],
+    new_impacts: []
+  };
+  assert.deepEqual(validateExecutionResult(result, contract, { registry, compilerContract }), { status: "accepted", blockers: [] });
+  assert.deepEqual(validateExecutionResult({ ...result, new_impacts: [{ impact_type: "cache" }] }, contract, { registry, compilerContract }), { status: "blocked", blockers: ["new-impacts"] });
+});

package/template/.pi/skills/yss-layered-mvc-scaffold-generator/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: yss-layered-mvc-scaffold-generator
+description: 用于在生命周期已批准的脚手架合同下生成通用 YSS Java 8 分层 MVC 后端工程；核心模块为 server、service、repository，并按能力确定性增加 adapter、client、feign-client。
+---
+
+# YSS Layered MVC Scaffold Generator
+
+本 skill 只为已登记的全新 backend project 生成机械工程骨架，不创建 `project-instance`、不初始化 Git、不生成业务 Controller、DTO、查询、状态机或 Mock 数据。
+
+## 进入条件
+
+- backend `scaffold_status=required`，目标目录已确认且不存在。
+- `scaffold-architecture-decisions.yaml` 中对应项目已达到 `lifecycle-approved`，确认架构为 `layered-mvc`。
+- `yss-implementation-contract-compiler` 已编译 scaffold contract schema v3，生命周期已批准并持久化。
+- 合同中的 `decision_id`、文件 digest、Profile、能力闭包、写路径和验证命令仍为当前版本。
+
+任一条件缺失时返回 `blocked`。本生成器无交互、无默认回退；用户选择由 `yss-product-lifecycle` 在 `work-unit.technical-analysis` 的工程基线内完成。
+
+## 架构与 Profile
+
+- 固定核心模块：`server`、`service`、`repository`。
+- `external-integration` 增加 `adapter`。
+- `published-client` 增加 `client`。
+- `feign-client` 增加 `client`、`feign-client`。
+- 固定平台：Java 8、Spring Boot 2.7、`javax`、YSS BOM、MyBatis-Plus。
+- 固定 architecture_profile=layered-mvc-service；verification_database=h2、production_database=not-bound。测试使用 H2，本地运行显式启用 scaffold-local；不引入外部驱动/数据源。
+
+能力解析规则、模块职责和依赖方向见 [architecture.md](references/architecture.md)。生成器必须同时校验 `requested_capabilities` 与 `resolved_modules`，不得自行补猜模块。
+
+## 执行
+
+优先使用一键入口：
+
+```bash
+node scripts/generate_and_verify_scaffold.mjs \
+  --project-name my-service \
+  --base-package com.yss.myservice \
+  --output-dir /path/to/backend-container \
+  --contract-file /path/to/approved-scaffold-contract.json \
+  --contract-id <id> \
+  --contract-version <version> \
+  --approval-ref <approval-ref> \
+  --compiler-draft-ref <compiler-ref> \
+  --persisted-ref <persisted-ref> \
+  --group-id com.yss.example \
+  --project-version 1.0.0-SNAPSHOT \
+  --parent-group-id com.yss.cloud \
+  --parent-artifact-id yss-cloud-microservice \
+  --parent-version 2.0.0-SNAPSHOT \
+  --yss-components-version 2.0.0-SNAPSHOT \
+  --evidence-dir /path/to/evidence
+```
+
+受控工作流必须在项目根实际执行 `./mvnw validate`、`./mvnw test`、`./mvnw package`，逐条记录退出码、时间、stdout/stderr 和失败分类。全部通过后只得到 `empty-scaffold-verified`。
+
+## 硬约束
+
+- 只接受 scaffold contract schema v3 和 Manifest schema v3；历史 v2 只读兼容，不用于新生成。
+- `architecture_family` 必须为 `layered-mvc`，`generator_skill` 必须为本 skill。
+- 目标存在、`--force`、旧项目迁移、模板升级均为 `unsupported`。
+- Harness 内只允许以 `apps/backend/` 为输出父容器；外部实现仓库使用已登记真实路径。
+- 不生成业务示例。健康检查、上下文加载测试和架构测试只能验证机械工程能力，不定义用户可见 API。
+- 生成后业务实现必须回到当前批准的 Slice Implementation Contract，使用适用 YSS skills 和 `behavior-tdd`。
+- DDD/MVC 互转不属于脚手架生成；已生成项目改变架构时必须建立独立迁移工作单元。

package/template/.pi/skills/yss-layered-mvc-scaffold-generator/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "YSS Layered MVC Scaffold Generator"
+  short_description: "Generate an approved YSS layered MVC backend skeleton."
+  default_prompt: "Use $yss-layered-mvc-scaffold-generator only after a user-confirmed scaffold architecture decision and a lifecycle-approved schema v3 scaffold contract."

package/template/.pi/skills/yss-layered-mvc-scaffold-generator/references/architecture.md

@@ -0,0 +1,29 @@
+# 通用分层 MVC 架构合同
+
+## 模块闭包
+
+| 能力 | 解析模块 |
+|---|---|
+| 核心 | `server`、`service`、`repository` |
+| `external-integration` | `adapter` |
+| `published-client` | `client` |
+| `feign-client` | `client`、`feign-client` |
+
+合同保存 `requested_capabilities`、`resolved_modules` 和 `resolution_version: 1`。模块按 `server`、`service`、`repository`、`adapter`、`client`、`feign-client` 的稳定顺序生成。
+
+## 职责和依赖
+
+| 模块 | 职责 | 允许依赖 |
+|---|---|---|
+| `server` | Spring Boot 启动、Controller 装配和 Web 配置 | `service`、可选 `client` |
+| `service` | 应用服务、事务脚本和用例编排 | `repository`、可选 `adapter` / `feign-client` |
+| `repository` | PO、Mapper、SQL 与数据库访问 | 无本项目上游模块 |
+| `adapter` | 外部系统适配实现 | 无本项目上游模块 |
+| `client` | 对外稳定调用契约 | 无本项目上游模块 |
+| `feign-client` | `client` 的 Feign 实现 | `client` |
+
+MVC 模式不等于禁止领域分析。若技术分析发现聚合不变量、复杂状态机、跨聚合一致性、Domain Event 或复杂并发，Agent 应推荐 `domain-driven`；用户仍选择 MVC 时必须记录覆盖理由和残余风险。局部 Tactical DDD Check 仍可按真实领域影响触发。
+
+## 生成边界
+
+允许生成 POM、Wrapper、启动入口、环境配置、包级占位、架构测试与上下文加载测试。禁止生成业务 API、DTO、字段、查询、状态、事务规则、权限、错误映射和 Mock 业务数据。

package/template/.pi/skills/yss-layered-mvc-scaffold-generator/scripts/generate_and_verify_scaffold.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+import { execFile } from "node:child_process";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import { run } from "./run_scaffold_verification.mjs";
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const GENERATOR = path.join(SCRIPT_DIR, "generate_scaffold.mjs");
+
+function parseArgs(argv) {
+  const generatorArgs = [];
+  let evidenceDir;
+  let outputDir;
+  let projectName;
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === "--evidence-dir" || token.startsWith("--evidence-dir=")) {
+      evidenceDir = token.includes("=") ? token.slice(token.indexOf("=") + 1) : argv[++index];
+      continue;
+    }
+    generatorArgs.push(token);
+    if (token === "--output-dir") outputDir = argv[index + 1];
+    if (token.startsWith("--output-dir=")) outputDir = token.slice(token.indexOf("=") + 1);
+    if (token === "--project-name") projectName = argv[index + 1];
+    if (token.startsWith("--project-name=")) projectName = token.slice(token.indexOf("=") + 1);
+  }
+  if (!evidenceDir || !outputDir || !projectName) throw new Error("必须提供 --evidence-dir、--output-dir 和 --project-name");
+  return { evidenceDir: path.resolve(evidenceDir), generatorArgs, projectRoot: path.join(path.resolve(outputDir), projectName) };
+}
+
+function executeGenerator(args) {
+  return new Promise((resolve) => execFile(process.execPath, [GENERATOR, ...args], { encoding: "utf8" }, (error, stdout, stderr) => resolve({ exitCode: error?.code ?? 0, stdout, stderr })));
+}
+
+async function main() {
+  try {
+    const args = parseArgs(process.argv.slice(2));
+    await mkdir(args.evidenceDir, { recursive: true });
+    const generation = await executeGenerator(args.generatorArgs);
+    await writeFile(path.join(args.evidenceDir, "generation.stdout.log"), generation.stdout, "utf8");
+    await writeFile(path.join(args.evidenceDir, "generation.stderr.log"), generation.stderr, "utf8");
+    if (generation.exitCode !== 0) throw new Error(`生成失败: ${generation.stderr.trim()}`);
+    const verification = await run(args.projectRoot, args.evidenceDir);
+    await writeFile(path.join(args.evidenceDir, "scaffold-verification.json"), `${JSON.stringify(verification, null, 2)}\n`, "utf8");
+    if (verification.status !== "passed") return 1;
+    const manifestPath = path.join(args.projectRoot, ".yss/scaffold-generation.json");
+    const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+    manifest.completion_level = "empty-scaffold-verified";
+    manifest.empty_scaffold_verification_ref = path.join(args.evidenceDir, "scaffold-verification.json");
+    manifest.empty_scaffold_verified_at = new Date().toISOString();
+    await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+    return 0;
+  } catch (error) {
+    process.stderr.write(`❌ MVC 脚手架工作流失败: ${error.message}\n`);
+    return 1;
+  }
+}
+
+process.exitCode = await main();

package/template/.pi/skills/yss-layered-mvc-scaffold-generator/scripts/generate_scaffold.mjs

@@ -0,0 +1,315 @@
+#!/usr/bin/env node
+/** 依据生命周期批准的 schema v3 合同生成纯机械 YSS 分层 MVC 后端骨架。 */
+import { assertScaffoldUserDecision } from "../../../../scripts/lib/user-decision.mjs";
+import { createHash } from "node:crypto";
+import { chmod, cp, lstat, mkdir, mkdtemp, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import { parseDocument } from "../../../../scripts/vendor/yaml.mjs";
+import { findGitRoot, gitSubmoduleScaffoldViolation, overlayMountViolation } from "../../../../scripts/lib/repository-scope-policy.mjs";
+import { assertLocalDatabaseProfile, localDatabaseConfiguration, scaffoldArchitectureIdentity } from "../../../../scripts/lib/scaffold-local-database.mjs";
+import { validateArchitectureIdentity } from "../../../../scripts/lib/backend-architecture.mjs";
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const SKILL_ROOT = path.resolve(SCRIPT_DIR, "..");
+const REPOSITORY_ROOT = path.resolve(SCRIPT_DIR, "../../../..");
+const SKILL_ID = "yss-layered-mvc-scaffold-generator";
+const COMMANDS = ["./mvnw validate", "./mvnw test", "./mvnw package"];
+const MODULE_ORDER = ["server", "service", "repository", "adapter", "client", "feign-client"];
+const CORE_MODULES = ["server", "service", "repository"];
+const CAPABILITIES = Object.freeze({
+  "external-integration": ["adapter"],
+  "published-client": ["client"],
+  "feign-client": ["client", "feign-client"]
+});
+
+function fail(message) { throw new Error(message); }
+function isPresent(value) { return value !== undefined && value !== null && value !== "" && (!Array.isArray(value) || value.length > 0); }
+function sha256(content) { return `sha256:${createHash("sha256").update(content).digest("hex")}`; }
+function rawSha256(content) { return createHash("sha256").update(content).digest("hex"); }
+function isWithin(parent, target) { const relative = path.relative(parent, target); return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative)); }
+function xml(value) { return String(value).replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;"); }
+function toUpperCamel(value) { return value.split("-").map((part) => `${part[0].toUpperCase()}${part.slice(1)}`).join(""); }
+function orderedModules(requested) {
+  const modules = new Set(CORE_MODULES);
+  for (const capability of requested) {
+    if (!CAPABILITIES[capability]) fail(`unsupported MVC capability: ${capability}`);
+    for (const module of CAPABILITIES[capability]) modules.add(module);
+  }
+  return MODULE_ORDER.filter((module) => modules.has(module));
+}
+async function exists(target) { try { await lstat(target); return true; } catch (error) { if (error.code === "ENOENT") return false; throw error; } }
+async function put(root, relative, content) { const target = path.join(root, relative); await mkdir(path.dirname(target), { recursive: true }); await writeFile(target, content.endsWith("\n") ? content : `${content}\n`, "utf8"); }
+async function fileEntries(root, excluded = new Set()) {
+  const entries = [];
+  async function visit(directory) {
+    for (const entry of (await readdir(directory, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+      const target = path.join(directory, entry.name);
+      const relative = path.relative(root, target).split(path.sep).join("/");
+      if (entry.name === ".git") continue;
+      if (excluded.has(relative)) continue;
+      if (entry.isDirectory()) await visit(target);
+      else if (entry.isFile()) entries.push({ target, relative });
+    }
+  }
+  await visit(root);
+  return entries;
+}
+async function treeDigest(root) {
+  const hash = createHash("sha256");
+  async function visit(directory) {
+    for (const entry of (await readdir(directory, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+      const target = path.join(directory, entry.name);
+      if (entry.isDirectory()) await visit(target);
+      else if (entry.isFile()) hash.update(path.relative(root, target)).update("\0").update(await readFile(target)).update("\0");
+    }
+  }
+  await visit(root);
+  return `sha256:${hash.digest("hex")}`;
+}
+
+export function parseArgs(argv) {
+  const options = { force: false };
+  const mapping = new Map([
+    ["--project-name", "projectName"], ["--base-package", "basePackage"], ["--output-dir", "outputDir"],
+    ["--contract-file", "contractFile"], ["--contract-id", "contractId"], ["--contract-version", "contractVersion"],
+    ["--approval-ref", "approvalRef"], ["--compiler-draft-ref", "compilerDraftRef"], ["--persisted-ref", "persistedRef"],
+    ["--group-id", "groupId"], ["--project-version", "projectVersion"], ["--parent-group-id", "parentGroupId"],
+    ["--parent-artifact-id", "parentArtifactId"], ["--parent-version", "parentVersion"], ["--yss-components-version", "yssComponentsVersion"]
+  ]);
+  for (let index = 0; index < argv.length; index += 1) {
+    let token = argv[index];
+    if (token === "--help" || token === "-h") { options.help = true; continue; }
+    if (token === "--force") { options.force = true; continue; }
+    const equal = token.indexOf("=");
+    let value;
+    if (equal >= 0) { value = token.slice(equal + 1); token = token.slice(0, equal); }
+    if (!mapping.has(token)) fail(`不支持的参数: ${token}`);
+    if (value === undefined) value = argv[++index];
+    if (!value || value.startsWith("--")) fail(`参数 ${token} 缺少值`);
+    options[mapping.get(token)] = value;
+  }
+  if (options.help) return options;
+  for (const key of mapping.values()) if (!isPresent(options[key])) fail(`缺少必填参数: ${key}`);
+  if (!/^[a-z][a-z0-9-]*$/.test(options.projectName)) fail("--project-name 必须是 kebab-case");
+  if (!/^[a-z](?:[a-z0-9]*)(?:\.[a-z](?:[a-z0-9]*)?)*$/.test(options.basePackage)) fail("--base-package 不是合法 Java 包名");
+  if (!/^\d+$/.test(options.contractVersion) || Number(options.contractVersion) < 1) fail("--contract-version 必须为正整数");
+  options.contractVersion = Number(options.contractVersion);
+  if (options.force) fail("unsupported: initialize-only 脚手架禁止 --force");
+  return options;
+}
+
+function dependency(groupId, artifactId, version = null, scope = null) {
+  return `<dependency><groupId>${xml(groupId)}</groupId><artifactId>${xml(artifactId)}</artifactId>${version ? `<version>${xml(version)}</version>` : ""}${scope ? `<scope>${scope}</scope>` : ""}</dependency>`;
+}
+
+function parentPom(contract, modules) {
+  const c = contract.maven_coordinates;
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+  <parent><groupId>${xml(c.parent.group_id)}</groupId><artifactId>${xml(c.parent.artifact_id)}</artifactId><version>${xml(c.parent.version)}</version><relativePath/></parent>
+  <groupId>${xml(c.group_id)}</groupId><artifactId>${xml(contract.project_name)}</artifactId><version>${xml(c.project_version)}</version><packaging>pom</packaging>
+  <properties><java.version>1.8</java.version><maven.compiler.source>1.8</maven.compiler.source><maven.compiler.target>1.8</maven.compiler.target><project.build.sourceEncoding>UTF-8</project.build.sourceEncoding><yss-components.version>${xml(c.yss_components_version)}</yss-components.version></properties>
+  <modules>${modules.map((module) => `<module>${contract.project_name}-${module}</module>`).join("")}</modules>
+  <dependencyManagement><dependencies>${dependency("com.yss.cloud", "yss-components-bom", "${yss-components.version}", "import").replace("</dependency>", "<type>pom</type></dependency>")}</dependencies></dependencyManagement>
+  <build><pluginManagement><plugins><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-compiler-plugin</artifactId><version>3.11.0</version><configuration><source>1.8</source><target>1.8</target><annotationProcessorPaths><path><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId><version>1.18.30</version></path><path><groupId>org.mapstruct</groupId><artifactId>mapstruct-processor</artifactId><version>1.5.5.Final</version></path><path><groupId>org.projectlombok</groupId><artifactId>lombok-mapstruct-binding</artifactId><version>0.2.0</version></path></annotationProcessorPaths></configuration></plugin></plugins></pluginManagement></build>
+</project>`;
+}
+
+function modulePom(contract, module, modules) {
+  const applicationModule = modules.includes("core") ? "core" : "service";
+  const own = (name) => dependency(contract.maven_coordinates.group_id, `${contract.project_name}-${name}`, "${project.version}");
+  const dependencies = [];
+  if (module === "server") {
+    dependencies.push(own(applicationModule), dependency("org.springframework.boot", "spring-boot-starter-web"), dependency("org.springframework.boot", "spring-boot-starter-validation"), dependency("org.springframework.boot", "spring-boot-starter-test", null, "test"), dependency("com.tngtech.archunit", "archunit-junit5", "1.2.1", "test"));
+    if (modules.includes("client")) dependencies.push(own("client"));
+    dependencies.push(dependency("com.h2database", "h2", null, "test"), dependency("org.mapstruct", "mapstruct", "1.5.5.Final"), dependency("com.yss.cloud", "yss-component-dto"));
+  }
+  if (module === applicationModule) {
+    dependencies.push(own("repository"), dependency("org.springframework", "spring-tx"), dependency("com.yss.cloud", "yss-component-dto"), dependency("org.springframework.boot", "spring-boot-starter-test", null, "test"));
+    if (modules.includes("adapter")) dependencies.push(own("adapter"));
+  }
+  if (module === "repository") {
+    dependencies.push(dependency("com.yss.cloud", "yss-component-mybatis-plus-starter"), dependency("org.mapstruct", "mapstruct", "1.5.5.Final"), dependency("org.springframework.boot", "spring-boot-starter-test", null, "test"), dependency("com.h2database", "h2", null, "test"));
+  }
+  if (module === "adapter") {
+    dependencies.push(dependency("org.springframework", "spring-context"));
+    if (modules.includes("feign-client")) dependencies.push(own("feign-client"));
+  }
+  if (module === "client") dependencies.push(dependency("com.yss.cloud", "yss-component-dto"), dependency("javax.validation", "validation-api"));
+  if (["server", "service", "core", "client", "repository"].includes(module)) dependencies.push(dependency("org.projectlombok", "lombok", "1.18.30", "provided"));
+  if (module === "feign-client") dependencies.push(own("client"), dependency("org.springframework.cloud", "spring-cloud-openfeign-core"));
+  const plugin = module === "server" ? `<profiles><profile><id>scaffold-local</id><dependencies>${dependency("com.h2database", "h2", null, "runtime")}</dependencies></profile></profiles><build><plugins><plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId></plugin></plugins></build>` : "";
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"><modelVersion>4.0.0</modelVersion><parent><groupId>${xml(contract.maven_coordinates.group_id)}</groupId><artifactId>${xml(contract.project_name)}</artifactId><version>${xml(contract.maven_coordinates.project_version)}</version></parent><artifactId>${xml(contract.project_name)}-${module}</artifactId><dependencies>${dependencies.join("")}</dependencies>${plugin}</project>`;
+}
+
+async function validateContract(options, skillId, architectureProfile) {
+  const contractFile = path.resolve(options.contractFile);
+  const contractText = await readFile(contractFile, "utf8").catch(() => fail(`脚手架合同不可读取: ${contractFile}`));
+  let contract;
+  try { contract = JSON.parse(contractText); } catch { fail("脚手架合同必须是 JSON 对象"); }
+  if (contract.schema_version !== 3) fail(`unsupported: 新生成只接受 scaffold contract schema v3，收到 v${contract.schema_version}`);
+  const required = ["contract_id", "contract_version", "scaffold_request_id", "status", "compiler_draft_ref", "lifecycle_approval_ref", "persisted_ref", "current_version", "implementation_repository", "backend_repository", "scaffold_status", "project_name", "target_output_dir", "base_package", "architecture_family", "generator_skill", "decision_ref", "decision_id", "decision_digest", "maven_coordinates", "profiles", "module_profile", "allowed_write_paths", "expected_evidence_files", "verification_commands", "approval", "work_unit", "generation_policy"];
+  const missing = required.filter((field) => !isPresent(contract[field]));
+  if (missing.length) fail(`脚手架合同缺少字段: ${missing.join(", ")}`);
+  if (contract.status !== "approved" || contract.current_version !== contract.contract_version) fail("脚手架合同必须已批准且为当前版本");
+  if (contract.contract_id !== options.contractId || contract.contract_version !== options.contractVersion || contract.compiler_draft_ref !== options.compilerDraftRef || contract.lifecycle_approval_ref !== options.approvalRef || contract.persisted_ref !== options.persistedRef) fail("命令行合同元数据与批准合同不一致");
+  if (contract.scaffold_status !== "required" || contract.architecture_family !== "layered-mvc" || contract.generator_skill !== skillId) fail("合同必须绑定 layered-mvc 与本生成器");
+  if (contract.project_name !== options.projectName || contract.base_package !== options.basePackage || path.resolve(contract.target_output_dir) !== path.resolve(options.outputDir)) fail("项目身份或输出目录与合同不一致");
+  if (!["allowed_write_paths", "expected_evidence_files", "verification_commands"].every((field) => Array.isArray(contract[field]) && contract[field].length)) fail("allowed_write_paths、expected_evidence_files、verification_commands 必须为非空数组");
+  const finalProjectRoot = path.join(path.resolve(options.outputDir), options.projectName);
+  const allowedRoots = contract.allowed_write_paths.map((item) => path.resolve(options.outputDir, String(item)));
+  if (!allowedRoots.some((root) => isWithin(root, finalProjectRoot))) fail("实际项目根不在合同 allowed_write_paths 内");
+  const expectedProfiles = { architecture: "layered-mvc", persistence: "mybatis-plus", platform: "spring-boot-2.7-jdk8", validation_namespace: "javax", repository: "yss-internal" };
+  for (const [field, value] of Object.entries(expectedProfiles)) if (contract.profiles?.[field] !== value) fail(`unsupported profile ${field}: ${contract.profiles?.[field]}`);
+  assertLocalDatabaseProfile(contract.profiles);
+  if (contract.architecture_profile !== architectureProfile) fail(`合同必须显式绑定 ${architectureProfile} Profile`);
+  const requested = contract.module_profile?.requested_capabilities;
+  if (!Array.isArray(requested)) fail("module_profile.requested_capabilities 必须是数组");
+  const resolved = architectureProfile === "mvc-data-analysis-v1" ? ["server", "core", "client", "repository", "adapter", "feign-client"] : orderedModules(requested);
+  if (contract.module_profile.resolution_version !== 1 || JSON.stringify(contract.module_profile.resolved_modules) !== JSON.stringify(resolved)) fail("MVC 能力闭包与 resolution_version=1 不一致");
+  if (JSON.stringify(contract.verification_commands) !== JSON.stringify(COMMANDS)) fail("验证命令必须固定为三条 ./mvnw 命令");
+  if (!contract.expected_evidence_files.includes(".yss/scaffold-generation.json")) fail("expected_evidence_files 必须包含 Manifest");
+  const work = contract.work_unit;
+  if (work?.primary_skill !== skillId || work?.tdd_mode !== "controlled-generation" || work?.controlled_generation !== true) fail("工作单元必须绑定本生成器和 controlled-generation");
+  if (!Array.isArray(work.allowed_write_paths) || !Array.isArray(work.expected_evidence) || !Array.isArray(work.verification_commands) || JSON.stringify(work.allowed_write_paths) !== JSON.stringify(contract.allowed_write_paths) || JSON.stringify(work.verification_commands) !== JSON.stringify(contract.verification_commands)) fail("工作单元与根级写路径或验证命令不一致");
+  const approval = contract.approval;
+  if (!approval || ["approval_ref", "approver", "persisted_ref", "current_version"].some((field) => !isPresent(approval[field])) || approval.approval_ref !== options.approvalRef || approval.persisted_ref !== options.persistedRef || approval.current_version !== options.contractVersion) fail("approval 记录不完整或不是当前合同版本");
+  const policy = contract.generation_policy;
+  if (policy?.mode !== "initialize-only" || policy?.existing_target !== "unsupported" || policy?.old_project_migration !== "unsupported" || policy?.template_upgrade !== "unsupported") fail("generation_policy 不符合 initialize-only");
+  const coordinates = contract.maven_coordinates;
+  const coordinateValues = [coordinates?.group_id, coordinates?.project_version, coordinates?.parent?.group_id, coordinates?.parent?.artifact_id, coordinates?.parent?.version, coordinates?.yss_components_version];
+  const optionValues = [options.groupId, options.projectVersion, options.parentGroupId, options.parentArtifactId, options.parentVersion, options.yssComponentsVersion];
+  if (coordinateValues.some((value) => !isPresent(value)) || JSON.stringify(coordinateValues) !== JSON.stringify(optionValues)) fail("Maven 坐标与合同不一致");
+  if (coordinateValues.some((value) => !/^[A-Za-z0-9_.-]+$/.test(String(value)))) fail("Maven 坐标只能包含字母、数字、点、下划线和连字符");
+  const decisionPath = path.isAbsolute(contract.decision_ref) ? contract.decision_ref : path.resolve(path.dirname(contractFile), contract.decision_ref);
+  const decisionText = await readFile(decisionPath, "utf8").catch(() => fail(`架构决策文件不可读取: ${decisionPath}`));
+  if (sha256(decisionText) !== contract.decision_digest) fail("架构决策文件 digest 与合同不一致");
+  const document = parseDocument(decisionText, { maxAliasCount: 0, uniqueKeys: true });
+  if (document.errors.length) fail(`架构决策 YAML 无效: ${document.errors[0].message}`);
+  const decisionSet = document.toJS({ maxAliasCount: 0 });
+  if (decisionSet?.kind !== "scaffold-architecture-decisions" || decisionSet?.template !== false || decisionSet?.status !== "current") fail("架构决策文件必须是 current 的正式 scaffold-architecture-decisions 记录");
+  const decisions = decisionSet.decisions ?? [];
+  const decision = decisions.find((item) => item.decision_id === contract.decision_id);
+  if (!decision || decision.status !== "lifecycle-approved" || decision.confirmed_architecture !== "layered-mvc" || decision.project_id !== contract.project_name) fail("架构决策未批准、项目不匹配或不是 layered-mvc");
+  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);
+  validateArchitectureIdentity(scaffoldArchitectureIdentity(contract, sha256(contractText)));
+  return { contract, contractText, modules: resolved };
+}
+
+async function validateOutputLayout(outputDir, projectName) {
+  const target = path.join(path.resolve(outputDir), projectName);
+  const relative = path.relative(REPOSITORY_ROOT, path.resolve(outputDir));
+  if (!relative.startsWith("..") && !path.isAbsolute(relative)) {
+    const parts = relative.split(path.sep).filter(Boolean);
+    if (!(parts.length === 2 && parts[0] === "apps" && parts[1] === "backend")) fail("Harness 内后端脚手架输出父目录必须是 apps/backend");
+  }
+  const gitRoot = findGitRoot(target) || findGitRoot(outputDir) || REPOSITORY_ROOT;
+  const violation = gitSubmoduleScaffoldViolation(gitRoot, path.resolve(outputDir), projectName, { force: false }) || overlayMountViolation(gitRoot, target, { force: true });
+  if (violation) fail(violation);
+  if (await exists(target)) fail(`unsupported: 目标已存在 ${target}`);
+}
+
+export async function generate(options, { skillId = SKILL_ID, architectureProfile = "layered-mvc-service", finalize } = {}) {
+  if (!((skillId === SKILL_ID && architectureProfile === "layered-mvc-service") || (skillId === "yss-mvc-data-analysis-project-initializer" && architectureProfile === "mvc-data-analysis-v1"))) fail("unsupported MVC generator/Profile pair");
+  await validateOutputLayout(options.outputDir, options.projectName);
+  const { contract, contractText, modules } = await validateContract(options, skillId, architectureProfile);
+  const outputDir = path.resolve(options.outputDir);
+  await mkdir(outputDir, { recursive: true });
+  const staging = await mkdtemp(path.join(outputDir, `.${options.projectName}.staging-`));
+  const projectRoot = path.join(staging, options.projectName);
+  const packagePath = options.basePackage.replaceAll(".", "/");
+  try {
+    await mkdir(projectRoot, { recursive: true });
+    await put(projectRoot, "pom.xml", parentPom(contract, modules));
+    for (const module of modules) {
+      const moduleRoot = `${options.projectName}-${module}`;
+      await put(projectRoot, `${moduleRoot}/pom.xml`, modulePom(contract, module, modules));
+      await put(projectRoot, `${moduleRoot}/src/main/java/${packagePath}/${module.replaceAll("-", "/")}/package-info.java`, `/** ${module} mechanical package boundary. */\npackage ${options.basePackage}.${module.replaceAll("-", ".")};`);
+    }
+    const applicationClass = `${toUpperCamel(options.projectName)}Application`;
+    const serverRoot = `${options.projectName}-server`;
+    await put(projectRoot, `${serverRoot}/src/main/java/${packagePath}/${applicationClass}.java`, `package ${options.basePackage};\n\nimport org.springframework.boot.SpringApplication;\nimport org.springframework.boot.autoconfigure.SpringBootApplication;\n\n/** Mechanical Spring Boot entrypoint. */\n@SpringBootApplication\npublic class ${applicationClass} {\n    public static void main(String[] args) {\n        SpringApplication.run(${applicationClass}.class, args);\n    }\n}`);
+    await put(projectRoot, `${serverRoot}/src/main/resources/application.yml`, `spring:\n  application:\n    name: ${options.projectName}`);
+    await put(projectRoot, `${serverRoot}/src/main/resources/application-scaffold-local.yml`, localDatabaseConfiguration(options.projectName));
+    await put(projectRoot, `${serverRoot}/src/test/resources/application-scaffold-test.yml`, localDatabaseConfiguration(`${options.projectName}_test`));
+    await put(projectRoot, `${serverRoot}/src/test/java/${packagePath}/${applicationClass}Test.java`, `package ${options.basePackage};\n\nimport org.junit.jupiter.api.Test;\nimport org.springframework.boot.test.context.SpringBootTest;\nimport org.springframework.test.context.ActiveProfiles;\n\n@SpringBootTest\n@ActiveProfiles("scaffold-test")\nclass ${applicationClass}Test {\n    @Test\n    void contextLoads() {\n    }\n}`);
+    await put(projectRoot, `${serverRoot}/src/test/java/${packagePath}/architecture/LayeredMvcArchitectureTest.java`, `package ${options.basePackage}.architecture;\n\nimport static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.noClasses;\n\nimport com.tngtech.archunit.core.importer.ImportOption;\nimport com.tngtech.archunit.junit.AnalyzeClasses;\nimport com.tngtech.archunit.junit.ArchTest;\nimport com.tngtech.archunit.lang.ArchRule;\n\n@AnalyzeClasses(packages = "${options.basePackage}", importOptions = ImportOption.DoNotIncludeTests.class)\nclass LayeredMvcArchitectureTest {\n    @ArchTest\n    static final ArchRule repositoryDoesNotDependOnUpperLayers = noClasses().that().resideInAPackage("..repository..").should().dependOnClassesThat().resideInAnyPackage("..service..", "..server..");\n}`);
+    const wrapper = path.join(REPOSITORY_ROOT, ".agents/skills/yss-ddd-scaffold-generator/assets/wrapper");
+    await cp(wrapper, projectRoot, { recursive: true });
+    await chmod(path.join(projectRoot, "mvnw"), 0o755);
+    if (finalize) await finalize({ projectRoot, contract, architectureIdentity: scaffoldArchitectureIdentity(contract, sha256(contractText)) });
+    await put(projectRoot, "README.md", `# ${options.projectName}\n\n该工程由 ${skillId} 根据批准的 schema v3 合同生成。模块：${modules.join("、")}。不包含业务 API、SQL 或生产数据库绑定。\n\n本地运行需同时显式启用 Maven -Pscaffold-local 和 Spring scaffold-local Profile；测试独立使用 H2。生产数据库须由后续已批准存储工作单元接入。`);
+    const generatedFiles = [];
+    for (const entry of await fileEntries(projectRoot, new Set([".yss/scaffold-generation.json"]))) generatedFiles.push({ path: entry.relative, owner: "generator", sha256: rawSha256(await readFile(entry.target)) });
+    const architectureRuleset = `${serverRoot}/src/test/java/${packagePath}/architecture/LayeredMvcArchitectureTest.java`;
+    const downstream = {};
+    for (const skill of ["yss-application", "yss-repository", "yss-mybatis", "yss-web-controller", "yss-dto", "yss-exception", "yss-validation", "mapstruct", "lombok", "alibaba-java-code-style"]) downstream[skill] = (await treeDigest(path.join(REPOSITORY_ROOT, ".agents/skills", skill))).replace(/^sha256:/, "");
+    const manifest = {
+      schema_version: 3,
+      kind: architectureProfile === "mvc-data-analysis-v1" ? "service-project-initialization" : "backend-scaffold",
+      architecture_profile: contract.architecture_profile,
+      architecture_identity: scaffoldArchitectureIdentity(contract, sha256(contractText)),
+      contract_id: contract.contract_id,
+      contract_version: contract.contract_version,
+      scaffold_request_id: contract.scaffold_request_id,
+      architecture_family: "layered-mvc",
+      generator_skill: skillId,
+      decision_id: contract.decision_id,
+      decision_digest: contract.decision_digest,
+      decision_ref: contract.decision_ref,
+      contract_digest: sha256(contractText),
+      contract_file_ref: path.resolve(options.contractFile),
+      approval_ref: options.approvalRef,
+      approver: contract.approval.approver,
+      lifecycle_approval_ref: contract.lifecycle_approval_ref,
+      compiler_draft_ref: contract.compiler_draft_ref,
+      persisted_ref: contract.persisted_ref,
+      current_version: contract.current_version,
+      allowed_write_paths: contract.allowed_write_paths,
+      expected_evidence_files: contract.expected_evidence_files,
+      profiles: contract.profiles,
+      module_profile: contract.module_profile,
+      maven_coordinates: contract.maven_coordinates,
+      maven_coordinates_source: "approved-contract",
+      project_name: contract.project_name,
+      base_package: contract.base_package,
+      bootstrap_main_class: `${options.basePackage}.${applicationClass}`,
+      bootstrap_main_source: `${serverRoot}/src/main/java/${packagePath}/${applicationClass}.java`,
+      generation_mode: "controlled-generation",
+      completion_level: "generated",
+      generation_policy: contract.generation_policy,
+      verification_commands: COMMANDS,
+      generator: { id: skillId, template_digest: await treeDigest(SKILL_ROOT) },
+      ownership: { generated_files: generatedFiles, user_owned_globs: ["**/src/main/java/**", "**/src/test/java/**", "db/**"] },
+      readiness: { downstream_skills: downstream, contracts: { architecture_profiles: rawSha256(await readFile(path.join(REPOSITORY_ROOT, "docs/agents/backend-architecture-profiles.md"))), compiler_contract: rawSha256(await readFile(path.join(REPOSITORY_ROOT, ".agents/skills/yss-implementation-contract-compiler/references/compiler-contract.yaml"))) }, architecture_ruleset: rawSha256(await readFile(path.join(projectRoot, architectureRuleset))) },
+      generated_at: new Date().toISOString()
+    };
+    await put(projectRoot, ".yss/scaffold-generation.json", JSON.stringify(manifest, null, 2));
+    await rename(projectRoot, path.join(outputDir, options.projectName));
+    await rm(staging, { recursive: true, force: true });
+    process.stdout.write(`${JSON.stringify({ status: "generated", project_root: path.join(outputDir, options.projectName), modules }, null, 2)}\n`);
+  } catch (error) {
+    await rm(staging, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+async function main() {
+  try {
+    const options = parseArgs(process.argv.slice(2));
+    if (options.help) { process.stdout.write("Use --project-name --base-package --output-dir and approved contract metadata. Local/test database is H2; production is not bound.\n"); return 0; }
+    await generate(options);
+    return 0;
+  } catch (error) {
+    process.stderr.write(`❌ MVC 脚手架生成失败: ${error.message}\n`);
+    return 1;
+  }
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) process.exitCode = await main();

package/template/.pi/skills/yss-layered-mvc-scaffold-generator/scripts/run_scaffold_verification.mjs

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+/** 复用统一 Manifest v3 / Maven Wrapper 验证协议。 */
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+import { run as runUnifiedVerification } from "../../yss-ddd-scaffold-generator/scripts/run_scaffold_verification.mjs";
+
+export async function run(projectRoot, evidenceDir, environment = process.env) {
+  return runUnifiedVerification(path.resolve(projectRoot), path.resolve(evidenceDir), environment);
+}
+
+async function main() {
+  const [projectRoot, evidenceDir] = process.argv.slice(2);
+  if (!projectRoot || !evidenceDir) {
+    process.stderr.write("用法: node run_scaffold_verification.mjs <project-root> <evidence-dir>\n");
+    return 1;
+  }
+  try {
+    const report = await run(projectRoot, evidenceDir);
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    return report.status === "passed" ? 0 : 1;
+  } catch (error) {
+    process.stderr.write(`${error.message}\n`);
+    return 1;
+  }
+}
+
+const currentFile = fileURLToPath(import.meta.url);
+if (process.argv[1] && path.resolve(process.argv[1]) === currentFile) process.exitCode = await main();