create-yss-spec 3.2.0 → 3.3.1

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

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+import { createHash } from "node:crypto";
+import { cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { tmpdir } from "node:os";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { validateJsonSchema } from "../../../../scripts/lib/json-schema.mjs";
+
+const fail = (message) => { throw new TypeError(message); };
+const REPOSITORY_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../..");
+const sha256 = (value) => `sha256:${createHash("sha256").update(value).digest("hex")}`;
+function argsOf(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i += 2) args[argv[i].replace(/^--/, "")] = argv[i + 1];
+  return args;
+}
+function git(cwd, ...args) {
+  const result = spawnSync("git", args, { cwd, encoding: "utf8" });
+  if (result.status !== 0) fail(result.stderr || `git ${args.join(" ")} failed`);
+  return result.stdout.trim();
+}
+function walk(root) {
+  return readdirSync(root, { withFileTypes: true }).flatMap((entry) => {
+    const item = path.join(root, entry.name);
+    return entry.isDirectory() ? walk(item) : entry.isFile() || entry.isSymbolicLink() ? [item] : [];
+  });
+}
+function validate(contract, outputDir) {
+  validateJsonSchema(contract, path.join(REPOSITORY_ROOT, "docs/process/schemas/project-scaffold-contract.schema.json"), { label: "Project Scaffold Contract v4" });
+  if (contract.schema_version !== 4 || contract.kind !== "project-scaffold-contract") fail("frontend scaffold requires Project Scaffold Contract schema v4");
+  if (contract.status !== "approved" || contract.current_version !== true || !contract.persisted_ref) fail("scaffold contract must be approved, persisted and current");
+  if (contract.delivery_role !== "frontend" || contract.scaffold_kind !== "frontend-yss-vue3" || contract.generator_skill !== "yss-frontend-scaffold-generator") fail("contract is not for the YSS frontend generator");
+  if (path.resolve(contract.target_output_dir) !== outputDir) fail("output directory differs from approved contract");
+  if (contract.generation_policy?.mode !== "initialize-only" || contract.generation_policy?.existing_target !== "unsupported") fail("unsupported generation policy");
+  if (!contract.frontend?.template?.repository || !/^[a-f0-9]{40}$/.test(contract.frontend.template.commit || "")) fail("template repository and exact 40-character commit are required");
+  if (contract.frontend.openapi_impact === "frozen" && (!contract.frontend.openapi_json_ref || !contract.frontend.openapi_json_digest)) fail("frozen OpenAPI JSON and digest are required");
+  if (contract.frontend.openapi_impact === "not-applicable" && !contract.frontend.openapi_not_applicable_reason) fail("no-API scaffold requires a reason");
+}
+
+export function generate({ contractFile, templateCheckout, outputDir }) {
+  const contract = JSON.parse(readFileSync(contractFile, "utf8"));
+  outputDir = path.resolve(outputDir);
+  templateCheckout = path.resolve(templateCheckout);
+  validate(contract, outputDir);
+  if (!existsSync(path.join(templateCheckout, ".git"))) fail("template checkout must be a Git worktree");
+  if (git(templateCheckout, "rev-parse", "HEAD") !== contract.frontend.template.commit) fail("template checkout does not match approved commit");
+  if (git(templateCheckout, "config", "--get", "remote.origin.url") !== contract.frontend.template.repository) fail("template repository differs from approved source");
+  if (existsSync(outputDir) && readdirSync(outputDir).length > 0) fail("target directory must not exist or must be empty");
+  mkdirSync(outputDir, { recursive: true });
+  const scratch = mkdtempSync(path.join(tmpdir(), "yss-frontend-source-"));
+  try {
+    // Read the approved Git tree, never dependency caches or edits in the checkout.
+    const archive = spawnSync("git", ["archive", contract.frontend.template.commit], { cwd: templateCheckout, maxBuffer: 256 * 1024 * 1024 });
+    if (archive.error || archive.status !== 0) fail(archive.error?.message || String(archive.stderr));
+    const unpack = spawnSync("tar", ["-xf", "-", "-C", scratch], { input: archive.stdout });
+    if (unpack.error || unpack.status !== 0) fail(unpack.error?.message || String(unpack.stderr));
+    cpSync(scratch, outputDir, { recursive: true, verbatimSymlinks: true });
+  } finally { rmSync(scratch, { recursive: true, force: true }); }
+
+  const replacements = {
+    "__APP_NAME__": contract.frontend.app_name,
+    "__MICROAPP_NAME__": contract.frontend.microapp_name,
+    "__BASE_ROUTE__": contract.frontend.base_route,
+    ...(contract.frontend.replacements || {}),
+  };
+  const generatedFiles = walk(outputDir).map(file => path.relative(outputDir, file));
+  for (const ref of generatedFiles) {
+    const file = path.join(outputDir, ref);
+    const info = lstatSync(file);
+    if (info.isSymbolicLink() || info.size > 2_000_000) continue;
+    const bytes = readFileSync(file);
+    if (bytes.includes(0) || !Buffer.from(bytes.toString("utf8")).equals(bytes)) continue;
+    const text = bytes.toString("utf8");
+    const replaced = Object.entries(replacements).reduce((value, [from, to]) => value.split(from).join(to), text);
+    if (replaced !== text) writeFileSync(file, replaced);
+  }
+  if (contract.frontend.openapi_impact === "frozen") {
+    const bytes = readFileSync(contract.frontend.openapi_json_ref);
+    if (sha256(bytes) !== contract.frontend.openapi_json_digest) fail("OpenAPI JSON digest mismatch");
+    mkdirSync(path.join(outputDir, "openapi"), { recursive: true });
+    writeFileSync(path.join(outputDir, "openapi", "openapi.json"), bytes);
+    if (!generatedFiles.includes("openapi/openapi.json")) generatedFiles.push("openapi/openapi.json");
+  }
+  if (contract.init_git === true) git(outputDir, "init");
+  generatedFiles.sort();
+  const manifest = {
+    schema_version: 4,
+    kind: "frontend-scaffold",
+    delivery_role: "frontend",
+    generator_skill: "yss-frontend-scaffold-generator",
+    contract_id: contract.contract_id,
+    contract_version: contract.contract_version,
+    contract_digest: sha256(readFileSync(contractFile)),
+    contract_file_ref: path.resolve(contractFile),
+    persisted_ref: contract.persisted_ref,
+    approval_ref: contract.approval.approval_ref,
+    template: { ...contract.frontend.template, checkout: templateCheckout },
+    repository_scope: contract.repository_scope,
+    target_output_dir: outputDir,
+    init_git: contract.init_git,
+    openapi_impact: contract.frontend.openapi_impact,
+    generation_mode: "controlled-generation",
+    generation_policy: contract.generation_policy,
+    verification_commands: contract.verification_commands,
+    generated_files: generatedFiles,
+    completion_level: "generated",
+    generated_at: new Date().toISOString(),
+  };
+  mkdirSync(path.join(outputDir, ".yss"), { recursive: true });
+  writeFileSync(path.join(outputDir, ".yss", "scaffold-generation.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+  return manifest;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  try {
+    const args = argsOf(process.argv.slice(2));
+    generate({ contractFile: args["contract-file"], templateCheckout: args["template-checkout"], outputDir: args["output-dir"] });
+    process.stdout.write("frontend scaffold generated\n");
+  } catch (error) { process.stderr.write(`${error.message}\n`); process.exitCode = 1; }
+}

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

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { runCommandSync } from "../../../../scripts/lib/command-runner.mjs";
+
+const ALLOWED = new Map([
+  ["pnpm install --frozen-lockfile", ["install", "--frozen-lockfile"]],
+  ["pnpm lint", ["lint"]],
+  ["pnpm type-check", ["type-check"]],
+  ["pnpm build", ["build"]],
+]);
+function argsOf(argv) { const args = {}; for (let i = 0; i < argv.length; i += 2) args[argv[i].replace(/^--/, "")] = argv[i + 1]; return args; }
+export function verify(projectRoot, evidenceDir, { timeoutMs = 0 } = {}) {
+  projectRoot = path.resolve(projectRoot); evidenceDir = path.resolve(evidenceDir);
+  const manifestPath = path.join(projectRoot, ".yss", "scaffold-generation.json");
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+  if (manifest.schema_version !== 4 || manifest.kind !== "frontend-scaffold" || manifest.generation_mode !== "controlled-generation") throw new TypeError("invalid frontend scaffold manifest");
+  if (!manifest.generated_files.includes("pnpm-lock.yaml")) throw new TypeError("frontend template must contain pnpm-lock.yaml");
+  const commands = manifest.verification_commands;
+  for (const required of ALLOWED.keys()) if (!commands.includes(required)) throw new TypeError(`missing required verification command: ${required}`);
+  mkdirSync(evidenceDir, { recursive: true });
+  const results = commands.map((command, index) => {
+    const argv = ALLOWED.get(command);
+    if (!argv) throw new TypeError(`unsupported verification command: ${command}`);
+    const started = Date.now();
+    const stdoutRef = path.join(evidenceDir, `${index + 1}-stdout.log`), stderrRef = path.join(evidenceDir, `${index + 1}-stderr.log`);
+    const result = runCommandSync("pnpm", argv, { cwd: projectRoot, timeoutMs, stdoutFile: stdoutRef, stderrFile: stderrRef, progress: true });
+    return { command, exit_code: result.status ?? 1, duration_ms: Date.now() - started, ...(result.termination ? { termination: result.termination } : {}), stdout_ref: stdoutRef, stderr_ref: stderrRef, executed_at: new Date().toISOString() };
+  });
+  const passed = results.every((item) => item.exit_code === 0);
+  const report = { schema_version: 1, kind: "frontend-scaffold-verification", status: passed ? "passed" : "failed", project_root: projectRoot, scaffold_manifest_ref: manifestPath, commands: results };
+  const reportPath = path.join(evidenceDir, "scaffold-verification.json");
+  writeFileSync(reportPath, `${JSON.stringify(report, null, 2)}\n`);
+  if (passed) { manifest.completion_level = "empty-scaffold-verified"; manifest.scaffold_verification_ref = reportPath; writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`); }
+  return report;
+}
+if (import.meta.url === `file://${process.argv[1]}`) {
+  try { const args = argsOf(process.argv.slice(2)); const report = verify(args["project-root"], args["evidence-dir"], { timeoutMs: Number(args["timeout-ms"] || 0) }); process.stdout.write(`${report.status}\n`); if (report.status !== "passed") process.exitCode = 1; }
+  catch (error) { process.stderr.write(`${error.message}\n`); process.exitCode = 1; }
+}

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

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+import assert from "node:assert/strict";
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readlinkSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+const root = mkdtempSync(path.join(os.tmpdir(), "yss-frontend-scaffold-"));
+process.on("exit", () => rmSync(root, { recursive: true, force: true }));
+const template = path.join(root, "template"), output = path.join(root, "output"), evidence = path.join(root, "evidence"), bin = path.join(root, "bin");
+mkdirSync(template); mkdirSync(bin);
+writeFileSync(path.join(template, "package.json"), JSON.stringify({ name: "__APP_NAME__", scripts: { lint: "noop", "type-check": "noop", build: "noop" } }));
+writeFileSync(path.join(template, "pnpm-lock.yaml"), "lockfileVersion: '9.0'\n");
+writeFileSync(path.join(template, "micro-config.json"), JSON.stringify({ name: "__MICROAPP_NAME__", route: "__BASE_ROUTE__" }));
+mkdirSync(path.join(template, "assets"));
+writeFileSync(path.join(template, "assets/binary.bin"), Buffer.from([0, 255, 95, 95, 65, 80, 80, 95, 78, 65, 77, 69, 95, 95]));
+writeFileSync(path.join(template, "assets/large.txt"), "__APP_NAME__".repeat(200_000));
+writeFileSync(path.join(template, "assets/run.sh"), "#!/bin/sh\necho __APP_NAME__\n");
+chmodSync(path.join(template, "assets/run.sh"), 0o755);
+symlinkSync("run.sh", path.join(template, "assets/current"));
+for (const args of [["init"], ["config", "user.email", "test@example.com"], ["config", "user.name", "test"], ["remote", "add", "origin", template], ["add", "."], ["commit", "-m", "fixture"]]) {
+  const result = spawnSync("git", args, { cwd: template, encoding: "utf8" }); assert.equal(result.status, 0, result.stderr);
+}
+const commit = spawnSync("git", ["rev-parse", "HEAD"], { cwd: template, encoding: "utf8" }).stdout.trim();
+mkdirSync(path.join(template, "node_modules"));
+writeFileSync(path.join(template, "node_modules/cache.txt"), "not approved");
+writeFileSync(path.join(template, "micro-config.json"), "uncommitted edit");
+const contract = {
+  schema_version: 4, kind: "project-scaffold-contract", contract_id: "frontend.demo.v1", contract_version: "1", status: "approved", persisted_ref: "docs/.scratch/demo/scaffold-contract.json", current_version: true,
+  delivery_role: "frontend", scaffold_kind: "frontend-yss-vue3", generator_skill: "yss-frontend-scaffold-generator", implementation_repository: output, target_output_dir: output, repository_scope: "external-repository", init_git: false,
+  frontend: { app_name: "demo-app", microapp_name: "demo", base_route: "/demo", package_manager: "pnpm", template: { repository: template, commit }, openapi_impact: "not-applicable", openapi_not_applicable_reason: "static-only" },
+  allowed_write_paths: [output], expected_evidence_files: [".yss/scaffold-generation.json"], verification_commands: ["pnpm install --frozen-lockfile", "pnpm lint", "pnpm type-check", "pnpm build"], approval: { approval_ref: "decision://frontend", approver: "user" }, generation_policy: { mode: "initialize-only", existing_target: "unsupported", old_project_migration: "unsupported", template_upgrade: "unsupported" }
+};
+const contractFile = path.join(root, "contract.json"); writeFileSync(contractFile, JSON.stringify(contract));
+const mockPnpm = path.join(bin, "pnpm"); writeFileSync(mockPnpm, "#!/bin/sh\nexit 0\n"); chmodSync(mockPnpm, 0o755);
+const runner = path.resolve(".agents/skills/yss-frontend-scaffold-generator/scripts/generate_and_verify_scaffold.mjs");
+const result = spawnSync(process.execPath, [runner, "--contract-file", contractFile, "--template-checkout", template, "--output-dir", output, "--evidence-dir", evidence], { encoding: "utf8", env: { ...process.env, PATH: `${bin}:${process.env.PATH}` } });
+assert.equal(result.status, 0, result.stderr);
+assert.equal(existsSync(path.join(output, ".git")), false);
+assert.equal(JSON.parse(readFileSync(path.join(output, "package.json"))).name, "demo-app");
+assert.equal(JSON.parse(readFileSync(path.join(output, ".yss", "scaffold-generation.json"))).completion_level, "empty-scaffold-verified");
+assert.equal(JSON.parse(readFileSync(path.join(evidence, "scaffold-verification.json"))).commands.length, 4);
+assert.equal(existsSync(path.join(output, "node_modules")), false);
+assert.equal(JSON.parse(readFileSync(path.join(output, "micro-config.json"))).name, "demo");
+assert.deepEqual(readFileSync(path.join(output, "assets/binary.bin")), readFileSync(path.join(template, "assets/binary.bin")));
+assert.deepEqual(readFileSync(path.join(output, "assets/large.txt")), readFileSync(path.join(template, "assets/large.txt")));
+assert.equal(readlinkSync(path.join(output, "assets/current")), "run.sh");
+assert.equal(statSync(path.join(output, "assets/run.sh")).mode & 0o777, 0o755);
+assert.match(readFileSync(path.join(output, "assets/current"), "utf8"), /echo demo-app/);
+const generated = JSON.parse(readFileSync(path.join(output, ".yss/scaffold-generation.json"))).generated_files;
+assert.deepEqual(generated, ["assets/binary.bin", "assets/current", "assets/large.txt", "assets/run.sh", "micro-config.json", "package.json", "pnpm-lock.yaml"]);
+const second = spawnSync(process.execPath, [runner, "--contract-file", contractFile, "--template-checkout", template, "--output-dir", output, "--evidence-dir", evidence], { encoding: "utf8", env: { ...process.env, PATH: `${bin}:${process.env.PATH}` } });
+assert.notEqual(second.status, 0);
+assert.match(second.stderr, /must not exist or must be empty/);
+process.stdout.write("前端脚手架受控生成场景验证通过\n");

package/template/.agents/skills/yss-implementation-contract-compiler/SKILL.md

@@ -39,7 +39,7 @@ description: Use when a YSS vertical slice is entering implementation, spans mul
 - Harness 内实现路径必须落在 `apps/backend/<project>/` 或 `apps/frontend/<project>/` 的具体项目目录；`apps/backend/`、`apps/frontend/` 只能作为容器，`app/backend/`、`app/frontend/` 及其子路径一律阻断。外部实现仓库使用其登记的真实项目根路径。`git-submodule` 使用 `implementation_path_policy: git-submodule-harness-apps`，空 gitlink、detached HEAD 或 `--force` 覆盖挂载点不得脚手架；`inspectWorkingTreeScope.writable` 必须为显式布尔值。
 - 当前用户、缓存、审计、Excel、分布式 ID、请求校验、错误映射、加解密或网关韧性命中时，必须按 `compiler-contract.yaml` 的 `impact_to_capabilities` 补齐入口 capability；不能只在 `boundaries.md` 中提及。仅复用已经验证的平台认证 / 授权能力不算 component impact，不自动增加权限专项 skill。
 - 业务行为使用 `behavior-tdd`；只有机械脚手架/生成物可用 `controlled-generation`，并记录例外和验证。
-- 原型确认后若 backend `scaffold_status=required`，必须先读取工程基线中的 `scaffold-architecture-decisions.yaml`。编译器按已达到 `lifecycle-approved` 且 digest 当前的选择，把 `domain-driven` 解析为 `backend.ddd-scaffold` / `yss-ddd-scaffold-generator`，把 `layered-mvc` 解析为 `backend.mvc-scaffold` / `yss-layered-mvc-scaffold-generator`；处于 `undecided`、`recommended`、`awaiting-user-decision` 或 `stale` 时返回 `blocked`，不得默认 DDD。随后按 `scaffold_contract_schema` v3 编译 `controlled-generation` 工作单元合同 draft；合同必须带选择引用与 digest、`generator_skill`、Profile、能力模块闭包、批准/持久化引用、允许写路径、预期证据和验证命令。经生命周期批准并持久化后才能运行对应生成器，再由受控工作单元实际执行固定的 `./mvnw validate`、`./mvnw test`、`./mvnw package` 并记录逐条结果，随后重新编译业务合同；脚手架不承载业务行为。
+- 阶段 5 若命中交付面且无已有工程，按 Project Scaffold Contract schema v4 编译 `controlled-generation` 合同 draft。后端先读取 `scaffold-architecture-decisions.yaml`，只接受已达到 `lifecycle-approved` 且 digest 当前的 DDD / Layered MVC 选择；前端绑定标准模板精确 commit、应用标识、路由、OpenAPI 影响、目标路径和 `init_git` 决定。合同经生命周期批准并持久化后才能运行生成器。历史后端 schema v3 只读兼容并可完成已批准生成；前端只接受 v4。生成与验证完成、仓库登记并通过 `gate.implementation-repositories-ready` 后，才编译 Ticket 与业务 Slice Contract。
 - 脚手架合同在编译阶段只能是 `draft` / `ready-for-lifecycle-review` / `blocked`；只有生命周期编排器可以把已持久化脚手架合同标记为 `approved`。脚手架合同只覆盖业务代码前的工程骨架工作单元；生成、基线校验和合同重编译完成后，它不能替代脚手架后的 Slice Implementation Contract。
 - 脚手架输出消费批准的脚手架合同；脚手架后的所有生成后端代码都必须绑定当前批准且版本当前的 Slice Implementation Contract、主 YSS skill、依赖闭包、允许写路径、预期证据和 YSS Skill Execution Result。打印命令、`./mvnw validate` 单项通过或脚手架成功不能替代合同批准；生成范围从机械内容变成业务行为时触发完整重路由。
 - 专项结果中的越界路径、缺失证据、`drift`、`violation` 或 `new_impacts` 必须阻断或重路由。

package/template/.agents/skills/yss-implementation-contract-compiler/references/boundaries.md

@@ -46,6 +46,7 @@
 | `component.gateway-resilience` | `yss-resilience4j` | `guidance`, `integration`, `slice-implementation`, `troubleshooting`, `component-maintenance`, `review-input` |
 | `scaffold.ddd` | `yss-ddd-scaffold-generator` | `integration`, `component-maintenance` |
 | `scaffold.layered-mvc` | `yss-layered-mvc-scaffold-generator` | `integration`, `component-maintenance` |
+| `scaffold.frontend-vue3` | `yss-frontend-scaffold-generator` | `integration`, `component-maintenance` |
 | `project-init.mvc-data-analysis` | `yss-mvc-data-analysis-project-initializer` | `component-maintenance` |
 | `migration.springboot3` | `yss-up-springboot3` | `guidance`, `integration`, `troubleshooting`, `component-maintenance`, `review-input` |
 
@@ -73,6 +74,7 @@
 | `backend.distributed-id` | `component.distributed-id` |
 | `backend.ddd-scaffold` | `scaffold.ddd`, `quality.java-code-style` |
 | `backend.mvc-scaffold` | `scaffold.layered-mvc`, `quality.java-code-style` |
+| `frontend.vue3-scaffold` | `scaffold.frontend-vue3` |
 | `backend.springboot3-migration` | `migration.springboot3`, `quality.java-code-style` |
 
 ## Impact Entry Mapping
@@ -103,6 +105,8 @@
 
 | Skill | Dependency | Type | Condition |
 | --- | --- | --- | --- |
+| `code-review` | `yss-repository` | `context-conditional` | `backend-persistence-impact` |
+| `code-review` | `yss-mybatis` | `context-conditional` | `backend-persistence-impact` |
 | `yss-prototype-stage` | `prototype-review` | `review-only` | — |
 | `yss-prototype-stage` | `yss-design-system` | `coordination-only` | — |
 | `yss-prototype-stage` | `yss-antdv-next-design` | `context-conditional` | `h2-vue-antdv-next-default` |

package/template/.agents/skills/yss-implementation-contract-compiler/references/compiler-contract.yaml

@@ -138,8 +138,33 @@ context_plan:
   context_stop_rule: minimal-sufficient-evidence
   missing_context_action: [blocked, reroute]
 
+project_scaffold_contract_schema:
+  schema_version: 4
+  schema_ref: docs/process/schemas/project-scaffold-contract.schema.json
+  identity: project-engineering-baseline
+  discriminant: delivery_role
+  delivery_roles:
+    backend:
+      scaffold_kinds: [backend-ddd, backend-layered-mvc]
+      generators: [yss-ddd-scaffold-generator, yss-layered-mvc-scaffold-generator]
+      requires: [scaffold_request_id, architecture_family, decision_ref, decision_id, decision_digest, project_name, base_package, maven_coordinates, profiles, module_profile]
+    frontend:
+      scaffold_kinds: [frontend-yss-vue3]
+      generators: [yss-frontend-scaffold-generator]
+      requires: [frontend, repository_scope, init_git]
+      openapi_modes: [frozen, not-applicable]
+  common_required: [contract_id, contract_version, status, persisted_ref, current_version, delivery_role, scaffold_kind, generator_skill, implementation_repository, target_output_dir, repository_scope, init_git, allowed_write_paths, expected_evidence_files, verification_commands, approval, generation_policy]
+  approved_by: yss-product-lifecycle
+  generation_mode: controlled-generation
+  target_policy: nonexistent-or-empty
+  force_overwrite: forbidden
+  compatibility:
+    backend_schema_v3: read-only-and-complete-approved-generation
+    frontend_before_v4: unsupported
+
 scaffold_contract_schema:
   schema_version: 3
+  compatibility_status: legacy-backend-read-only
   identity: service-engineering-baseline
   compiled_by: yss-implementation-contract-compiler
   approved_by: yss-product-lifecycle

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

@@ -11,7 +11,7 @@ description: 用于在生命周期已批准的脚手架合同下生成通用 YSS
 
 - backend `scaffold_status=required`，目标目录已确认且不存在。
 - `scaffold-architecture-decisions.yaml` 中对应项目已达到 `lifecycle-approved`，确认架构为 `layered-mvc`。
-- `yss-implementation-contract-compiler` 已编译 scaffold contract schema v3，生命周期已批准并持久化。
+- `yss-implementation-contract-compiler` 已编译统一 Project Scaffold Contract schema v4；已批准且当前的后端 schema v3 可完成兼容生成。合同须由生命周期批准并持久化。
 - 合同中的 `decision_id`、文件 digest、Profile、能力闭包、写路径和验证命令仍为当前版本。
 
 任一条件缺失时返回 `blocked`。本生成器无交互、无默认回退；用户选择由 `yss-product-lifecycle` 在 `work-unit.technical-analysis` 的工程基线内完成。
@@ -55,7 +55,7 @@ node scripts/generate_and_verify_scaffold.mjs \
 
 ## 硬约束
 
-- 只接受 scaffold contract schema v3 和 Manifest schema v3；历史 v2 只读兼容，不用于新生成。
+- 接受统一 schema v4，兼容已批准后端 schema v3；验证器接受对应 Manifest v3/v4。历史 v2 只读兼容，不用于新生成。
 - `architecture_family` 必须为 `layered-mvc`，`generator_skill` 必须为本 skill。
 - 目标存在、`--force`、旧项目迁移、模板升级均为 `unsupported`。
 - Harness 内只允许以 `apps/backend/` 为输出父容器；外部实现仓库使用已登记真实路径。

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

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-/** 依据生命周期批准的 schema v3 合同生成纯机械 YSS 分层 MVC 后端骨架。 */
+/** 依据生命周期批准的兼容 schema v3 或统一 schema v4 合同生成纯机械 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";
@@ -10,6 +10,7 @@ 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";
+import { validateJsonSchema } from "../../../../scripts/lib/json-schema.mjs";
 
 const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
 const SKILL_ROOT = path.resolve(SCRIPT_DIR, "..");
@@ -151,11 +152,13 @@ async function validateContract(options, skillId, architectureProfile) {
   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}`);
+  if (![3, 4].includes(contract.schema_version)) fail(`unsupported: 只接受兼容 scaffold contract v3 或统一 v4，收到 v${contract.schema_version}`);
+  if (contract.schema_version === 4 && (contract.kind !== "project-scaffold-contract" || contract.delivery_role !== "backend" || contract.scaffold_kind !== "backend-layered-mvc")) fail("schema v4 合同必须绑定 backend/backend-layered-mvc");
+  if (contract.schema_version === 4) validateJsonSchema(contract, path.join(REPOSITORY_ROOT, "docs/process/schemas/project-scaffold-contract.schema.json"), { label: "Project Scaffold Contract v4" });
   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.status !== "approved" || (contract.current_version !== contract.contract_version && !(contract.schema_version === 4 && contract.current_version === true))) 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("项目身份或输出目录与合同不一致");
@@ -244,14 +247,14 @@ export async function generate(options, { skillId = SKILL_ID, architectureProfil
     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。生产数据库须由后续已批准存储工作单元接入。`);
+    await put(projectRoot, "README.md", `# ${options.projectName}\n\n该工程由 ${skillId} 根据批准的 schema v${contract.schema_version} 合同生成。模块：${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,
+      schema_version: contract.schema_version,
       kind: architectureProfile === "mvc-data-analysis-v1" ? "service-project-initialization" : "backend-scaffold",
       architecture_profile: contract.architecture_profile,
       architecture_identity: scaffoldArchitectureIdentity(contract, sha256(contractText)),

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

@@ -18,7 +18,7 @@ const capabilityModules = {
   combined: { capabilities: ["external-integration", "feign-client"], modules: ["server", "service", "repository", "adapter", "client", "feign-client"] }
 };
 
-async function fixture(t, { profile = capabilityModules.basic, architectureProfile = "layered-mvc-service", skillId = "yss-layered-mvc-scaffold-generator" } = {}) {
+async function fixture(t, { profile = capabilityModules.basic, architectureProfile = "layered-mvc-service", skillId = "yss-layered-mvc-scaffold-generator", schemaVersion = 3 } = {}) {
   const root = await mkdtemp(path.join(os.tmpdir(), "yss-layered-mvc-"));
   t.after(() => rm(root, { recursive: true, force: true }));
   const output = path.join(root, "backend");
@@ -30,7 +30,12 @@ async function fixture(t, { profile = capabilityModules.basic, architectureProfi
   const decisionFile = path.join(root, "scaffold-architecture-decisions.yaml");
   await writeFile(decisionFile, decisionText);
   const contract = {
-    schema_version: 3,
+    schema_version: schemaVersion,
+    kind: "project-scaffold-contract",
+    delivery_role: "backend",
+    scaffold_kind: "backend-layered-mvc",
+    repository_scope: "external-repository",
+    init_git: false,
     contract_id: "scaffold.demo-service.v1",
     contract_version: 1,
     scaffold_request_id: "request.demo-service",
@@ -97,6 +102,16 @@ test("旧数据库和 Mock 参数在写入前被拒绝", async (t) => {
   }
 });
 
+test("统一 Project Scaffold Contract v4 可生成 Layered MVC 后端并保留 v4 Manifest", async (t) => {
+  const data = await fixture(t, { schemaVersion: 4 });
+  data.contract.current_version = true;
+  await writeFile(data.contractFile, JSON.stringify(data.contract));
+  const result = spawnSync(process.execPath, [script, ...data.args], { encoding: "utf8" });
+  assert.equal(result.status, 0, result.stderr);
+  const manifest = JSON.parse(await readFile(path.join(data.project, ".yss/scaffold-generation.json"), "utf8"));
+  assert.equal(manifest.schema_version, 4);
+});
+
 test("可选离线 Maven 可行性检查（不替代受控仓库验收）", { skip: process.env.YSS_BACKEND_OFFLINE_PROBE !== "1" }, async (t) => {
   const data = await fixture(t);
   const generated = spawnSync(process.execPath, [script, ...data.args], { encoding: "utf8" });

package/template/.agents/skills/yss-mybatis/SKILL.md

@@ -1,77 +1,53 @@
 ---
 name: yss-mybatis
-description: 用于 YSS MyBatis 与 MyBatis-Plus 持久层规范、配置和排障。当用户提到 BaseRepository、BasePlusRepository、PageQuery 自动分页、多数据源、批量插入或 MyBatis 配置异常时调用。
+description: 用于 YSS MyBatis / MyBatis-Plus 组件能力核验、接入决策和排障；涉及 Mapper/Repository 基类、分页、批量 SQL、扫描配置或数据源能力时使用，不负责生成持久层结构。
 ---
 
 # yss-mybatis
 
-用于处理 `yss-component-persistence` 相关的持久层规范、接入和问题定位。
+本 Skill 只维护 `yss-component-persistence` 的组件能力、选择条件和排障顺序。PO、Repository、Convertor、Gateway/Query Adapter 的结构与生成边界由 `yss-repository` 负责。
 
-## 何时使用
+## 入口与前置
 
-- 用户要定义新的 Repository。
-- 用户在 MyBatis 与 MyBatis-Plus 两种模式间排查问题。
-- 用户提到自动分页、`PageQuery`、批量插入、多数据源。
-- 用户反馈 Mapper 扫描、分页不生效、批量性能差。
+1. 读取批准且当前的 `architecture_identity`、`persistence_profile`、实现仓登记和 Slice Implementation Contract。没有合同的故障诊断可以继续，但不得据此生成或改变架构。
+2. 精确类名、方法签名、配置 key、默认值或启用条件必须先读 [source-index.md](references/source-index.md)，并按 `yss-skill-source-index-refresh/references/source-location.md` 核验组件 tree 与组件子树 clean 状态。
+3. 组件 tree 不匹配或 persistence 子树为 dirty 时，路径提示只能用于定位；精确实现或审查结论返回 `stale` / `missing_evidence`，刷新索引后再继续。
+4. 新 DDD / MVC scaffold 只支持批准的 `mybatis-plus` Profile。普通 MyBatis 仅用于既有工程维护、兼容与排障；新增支持必须有独立 Profile 和 fixture，不自动猜测或混用。
 
-## 工作方式
+## 稳定决策规则
 
-1. 先读取批准的 `persistence_profile` 和 `architecture_identity`。新 DDD / MVC scaffold 都使用 `mybatis-plus`；普通 MyBatis 必须有独立 fixture 和批准 Profile，禁止自动猜测或混用。模块所有权按 `docs/agents/backend-architecture-profiles.md`；H2 仅用于本地/测试，生产数据库另行批准接入。
-2. 涉及真实类名、配置项、模块依赖或排障时，先读 `references/source-index.md`，再定位源码或文档。
-3. 先复用现有基类与配置，不手搓新的基础设施。
-4. 涉及分页时，先验证 `PageQuery` 传递链路和拦截器是否生效。
+- 基类、Mapper 注解、XML 位置和扫描范围以批准 Profile、当前工程基线及当前组件源码共同决定；不得在既有体系外再造 Mapper 抽象。
+- 一条查询 seam 只能有一个分页责任模型。核对实际插件/切面开关、拦截范围、参数绑定条件和返回 total 的责任，不以“依赖已引入”代替行为验证。
+- 批量写入必须证明是组件当前支持的 SQL 级批量能力，并验证分批大小、字段填充、主键和数据库方言；循环单条写入不能冒充批量 SQL。
+- 多数据源实例创建不等于动态路由、线程上下文切换或事务传播。先做 capability check；组件未提供的路由能力必须由批准的上层适配承担。
+- Mapper/XML、逻辑删除、审计字段、主键策略、动态排序/分组白名单和参数绑定必须与数据合同一致；任何 SQL/DDL/索引新影响返回 `new_impacts`。
+- 事务边界归批准的 Application 用例或 MVC service/core；Repository 不临时声明新的业务事务。
 
-## 源码索引
+## 任务分流
 
-- 源码位置不要假设固定目录；先按 `yss-skill-source-index-refresh/references/source-location.md` 定位。
-- 当前技能索引：`references/source-index.md`
-- 重点源码入口通常包括 `BaseRepository`、`BasePlusRepository`、`EntityQueryAspect`、`PageQueryEntityConfigration`、`MybatisBaseConfiguration`、`MybatisPlusConfiguration`、`MultiDataSourceConfiguration`、`MultiDataSourceHolder`。
-
-当组件源码变化后，用 `yss-skill-source-index-refresh` 刷新索引；刷新或读取前先按源码定位策略确认真实位置。
-
-## 实施建议
-
-- 通用模式优先继承 `BaseRepository`
-- MP 模式优先继承项目既有的 `BasePlusRepository`
-- 批量导入优先使用真正的 SQL 级批量方法，不要默认循环单条插入
-- 多数据源问题优先先看配置和扫描范围，再怀疑业务代码
-- DDD 分页经 Application Query Port 进入 Infrastructure；MVC 经 service/core 进入 Repository。不把 `PageQuery` 带入 Domain Gateway，也不得在 Repository 内临时发明分页参数。
-- 生成或重构持久层时，先看当前模块已有 Repository/Mapper 命名、包路径、XML 位置。
-
-## 检查清单
-
-- Mapper 扫描路径是否正确。
-- XML 路径和接口是否对齐。
-- `PageQuery` 是否真的出现在被拦截的方法参数里。
-- 批量方法是否用了项目推荐实现。
-- 多数据源名称和主从配置是否一致。
-- MyBatis 与 MyBatis-Plus 的基类、分页插件和扫描配置是否混用。
-- 数据源切换是否在事务边界之前完成。
+| 请求 | 本 Skill 动作 | 后续路由 |
+|---|---|---|
+| 组件接入、基类选择、配置核验 | 读取当前 Profile 和源码能力矩阵，给出来源可追踪的选择 | 需要结构实现时转 `yss-repository` |
+| 分页、批量、扫描、XML、数据源故障 | 按下列顺序定位并保留实际证据 | 发现合同或数据影响时返回编译器 |
+| 生成 PO / Repository / Convertor / GatewayImpl | 不生成 | `yss-repository` |
+| 普通 MyBatis 新工程生成 | `unsupported` | 新 Profile / fixture 获批后再进入 |
 
 ## 排障顺序
 
-1. 确认依赖模块：starter、mapper、plus starter、persistence common。
-2. 确认 Mapper/Repository 扫描范围。
-3. 确认分页参数、分页切面或插件是否参与调用。
-4. 确认 XML、方法签名、resultMap/字段映射是否一致。
-5. 确认多数据源配置和当前线程数据源上下文。
-6. 最后再排查 SQL 本身和数据库执行计划。
-
-## 修改约束
-
-- 不要同时引入两套分页机制而不说明谁生效。
-- 不要在已有 Repository 基类体系之外再造一套 Mapper 抽象。
-- 若用户只是要生成持久层骨架，优先衔接 `yss-repository`。
+1. 依赖与 Profile：starter、组件版本、MyBatis/MyBatis-Plus 模式是否与合同一致。
+2. 装配与开关：自动配置、条件属性、Mapper 扫描和 XML location 是否真实生效。
+3. 调用 seam：代理是否命中、分页参数位置/类型、分页插件链和 total 回填责任。
+4. 映射：接口签名、XML namespace、resultMap、字段、逻辑删除和主键策略。
+5. 批量：是否调用当前公开批量入口、分批与方言是否匹配、是否退化为循环单条。
+6. 数据源：先确认组件只提供了什么，再检查上层路由与事务进入顺序；不得假设存在当前线程数据源上下文。
+7. 最后检查 SQL、绑定参数、数据库方言与执行计划。
 
-## 按需读取
+## Review 输入
 
-- 源码索引：`references/source-index.md`
-- 基础 Repository：`assets/BaseRepository.java`
-- 分页切面：`assets/EntityQueryAspect.java`
-- MyBatis 基础配置：`assets/MybatisBaseConfiguration.java`
+仅审查本体项目和合同/实现仓登记的后端研发项目。命中 Mapper、Repository、SQL、分页、批量、扫描配置或数据源能力时，`code-review` Standards 轴必须读取本 Skill 和当前 source index；无持久化影响时显式记录带原因的 `not-applicable`。
 
-## 阶段 7 合同
+## 结果与验证
 
-- 仅在数据架构、Repository 策略和批准合同明确时使用。
-- Mapper/XML 骨架可受控生成；查询语义、分页、数据源切换和事务行为使用 `behavior-tdd`。
-- 按统一 `YSS Skill Execution Result` 返回 Mapper/XML/配置、集成测试、实际 `./mvnw ...` 结果和新增 SQL/DDL/索引影响。
+- 行为变更使用 `behavior-tdd`；纯 Mapper/XML 骨架仅在批准合同明确为 `controlled-generation` 时允许。
+- 使用项目根 `./mvnw ...` 记录实际命令、退出码和时间；H2 只证明本地/测试行为，不证明生产方言。
+- 按 [YSS Skill Execution Result v2](../yss-implementation-contract-compiler/references/yss-skill-execution-result.md) 返回证据、`seam_deferred`、`deviations`、`new_impacts`、`drift` 和 `violation`。

package/template/.agents/skills/yss-mybatis/agents/openai.yaml

@@ -1,5 +1,5 @@
 version: 1
 interface:
   display_name: "YSS MyBatis"
-  short_description: "MyBatis 持久层、多数据源、分页与查询处理规范"
-  default_prompt: "Use $yss-mybatis to implement or debug YSS MyBatis repositories, pagination, and multi-datasource access."
+  short_description: "MyBatis 组件能力、配置、分页、批量与数据源排障"
+  default_prompt: "Use $yss-mybatis to verify or troubleshoot current YSS MyBatis capabilities and configuration; route persistence structure work to $yss-repository."