create-yss-spec 3.3.8 → 3.4.3

package/template/scripts/lib/backend-platform-provenance.mjs

@@ -0,0 +1,67 @@
+/** Version qualification binds executable sources and generated bytes, not Skill prose. */
+import { createHash } from 'node:crypto';
+import { readFileSync, readdirSync, lstatSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+const digest = bytes => `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+const fail = message => { throw new TypeError(`platform-provenance: ${message}`); };
+function fileMap(root, refs) {
+  const files = {};
+  const visit = ref => {
+    const full = path.join(root, ref), info = lstatSync(full);
+    if (info.isSymbolicLink()) fail(`source symlink: ${ref}`);
+    if (info.isDirectory()) for (const name of readdirSync(full).sort()) visit(`${ref}/${name}`);
+    else files[ref] = { digest: digest(readFileSync(full)), executable: Boolean(info.mode & 0o111) };
+  };
+  refs.forEach(visit);
+  return Object.fromEntries(Object.entries(files).sort(([a], [b]) => a.localeCompare(b)));
+}
+export function platformSourceFingerprint(family, root = ROOT) {
+  const skill = family === 'domain-driven' ? 'yss-ddd-scaffold-generator' : family === 'layered-mvc' ? 'yss-layered-mvc-scaffold-generator' : null;
+  if (!skill) fail('unknown architecture');
+  const base = `.agents/skills/${skill}`;
+  const generator = fileMap(root, [`${base}/scripts/generate_scaffold.mjs`, ...(family === 'domain-driven' ? [`${base}/assets`] : ['.agents/skills/yss-ddd-scaffold-generator/assets/wrapper']), 'scripts/lib/backend-platform.mjs', 'scripts/lib/scaffold-local-database.mjs']);
+  const verifier = fileMap(root, ['scripts/lib/backend-platform-provenance.mjs', 'scripts/lib/backend-platform-verification.mjs', 'scripts/lib/command-runner.mjs', 'scripts/vendor/xml.mjs', '.agents/skills/yss-ddd-scaffold-generator/scripts/run_scaffold_verification.mjs']);
+  return { schema_version: 1, generator_digest: digest(JSON.stringify(generator)), verifier_digest: digest(JSON.stringify(verifier)) };
+}
+export function assertSourceFingerprint(value, family, root = ROOT) {
+  if (JSON.stringify(value) !== JSON.stringify(platformSourceFingerprint(family, root))) fail('generator/verifier source drift; requalify candidate');
+}
+export function generatedTreeDigest(projectRoot, manifest) {
+  const expected = manifest.ownership?.generated_files;
+  if (!Array.isArray(expected) || !expected.length) fail('missing generated file inventory');
+  const names = new Set();
+  const actual = {};
+  for (const file of expected) {
+    if (!file.path || path.isAbsolute(file.path) || file.path.split(/[\\/]/).some(p => p === '..' || p === '') || names.has(file.path)) fail('invalid generated file inventory');
+    names.add(file.path);
+    const full = path.join(projectRoot, file.path);
+    // Check every path component: file lstat alone does not detect a linked parent directory.
+    let current = projectRoot;
+    for (const part of file.path.split('/')) { current = path.join(current, part); if (lstatSync(current).isSymbolicLink()) fail(`generated symlink: ${file.path}`); }
+    const info = lstatSync(full);
+    if (!info.isFile()) fail(`generated file absent: ${file.path}`);
+    const hash = digest(readFileSync(full));
+    if (hash.replace('sha256:', '') !== file.sha256.replace('sha256:', '')) fail(`generated file drift: ${file.path}`);
+    actual[file.path] = { digest: hash, executable: Boolean(info.mode & 0o111) };
+  }
+  const visit = (directory, relative = '') => {
+    for (const item of readdirSync(directory, { withFileTypes: true })) {
+      const ref = relative ? `${relative}/${item.name}` : item.name;
+      if (item.isSymbolicLink()) fail(`unexpected symlink: ${ref}`);
+      if (item.isDirectory()) { if (!['target', '.git'].includes(item.name)) visit(path.join(directory, item.name), ref); }
+      else if (!names.has(ref) && ref !== '.yss/scaffold-generation.json' && ref !== '.yss/platform-dependencies.json' && !ref.endsWith('/.yss/platform-dependencies.json')) fail(`unexpected source file: ${ref}`);
+    }
+  };
+  visit(projectRoot);
+  return digest(JSON.stringify(Object.fromEntries(Object.entries(actual).sort(([a],[b]) => a.localeCompare(b)))));
+}
+
+export function assertResumableCandidate(projectRoot, contract, contractBytes) {
+  const manifest = JSON.parse(readFileSync(path.join(projectRoot, '.yss/scaffold-generation.json'), 'utf8'));
+  if (manifest.platform_verification !== 'candidate' || manifest.schema_version !== 4 || manifest.contract_id !== contract.contract_id || manifest.contract_version !== contract.contract_version || manifest.contract_digest.replace('sha256:', '') !== digest(contractBytes).replace('sha256:', '') || JSON.stringify(manifest.platform_configuration) !== JSON.stringify(contract.platform_configuration)) fail('resume requires the identical candidate contract/Manifest');
+  assertSourceFingerprint(manifest.source_fingerprint, contract.architecture_family);
+  if (generatedTreeDigest(projectRoot, manifest) !== manifest.generated_tree_digest) fail('resume generated tree drift');
+  return manifest;
+}

package/template/scripts/lib/backend-platform-verification.mjs

@@ -0,0 +1,210 @@
+import { readFile, readdir, writeFile, stat } from "node:fs/promises";
+import { spawn } from "node:child_process";
+import net from "node:net";
+import path from "node:path";
+import { parseXmlDocument } from "../vendor/xml.mjs";
+import { runCommand } from "./command-runner.mjs";
+import { assertJavaPlatform, platformDigest } from "./backend-platform.mjs";
+
+const array = value => value === undefined ? [] : Array.isArray(value) ? value : [value];
+const fail = message => { throw new TypeError(`platform-dependencies: ${message}`); };
+const gav = item => `${item.groupId}:${item.artifactId}`;
+export async function platformEvidenceArtifacts(evidenceDir) {
+  const artifacts = [];
+  for (const entry of await readdir(evidenceDir, { withFileTypes: true })) {
+    if (entry.isFile() && (entry.name.endsWith('.log') || ['effective-pom.xml', 'boot-bom-effective.xml', 'dependency-trees.json', 'platform-tests.xml'].includes(entry.name))) {
+      artifacts.push({ ref: entry.name, digest: platformDigest(await readFile(path.join(evidenceDir, entry.name))) });
+    }
+  }
+  return artifacts.sort((a, b) => a.ref.localeCompare(b.ref));
+}
+export function checkPlatformTests(source, capabilities = []) {
+  const suite = parseXmlDocument(source).testsuite;
+  const cases = array(suite?.testcase);
+  const required = ['httpJsonRoundTrip', 'httpValidationRejectsBlank', 'validationAndJsonAutoConfiguration', 'mybatisCanMapVerificationQuery', ...(capabilities.includes('feign-client') ? ['feignCanDecodeJson'] : [])];
+  if (!suite || required.some(name => !cases.some(item => item['@_name'] === name && !['failure', 'error', 'skipped'].some(key => Object.hasOwn(item, key))))) fail('integration tests missing, failed or skipped');
+  return { status: 'passed', test_count: cases.length };
+}
+export async function verifyPlatformTests(projectRoot, evidenceDir, manifest, startedAt) {
+  try {
+    const module = `${manifest.project_name}-${manifest.architecture_family === 'domain-driven' ? 'bootstrap' : 'server'}`;
+    const reportPath = path.join(projectRoot, module, 'target/surefire-reports', `TEST-${manifest.base_package}.PlatformIntegrationTest.xml`);
+    if (!startedAt || (await stat(reportPath)).mtimeMs < startedAt) fail("stale integration test report");
+    const source = await readFile(reportPath, 'utf8');
+    await writeFile(path.join(evidenceDir, 'platform-tests.xml'), source);
+    return checkPlatformTests(source, manifest.module_profile?.requested_capabilities);
+  } catch (error) { return { status: 'failed', error: error.message }; }
+}
+export function checkPlatformDependencies(profile, effectivePom, dependencyTrees, { bootBom, mainArtifact, components = {} } = {}) {
+  const xml = parseXmlDocument(effectivePom);
+  const projects = array(xml.projects?.project ?? xml.project);
+  if (!projects.length || !dependencyTrees.length) fail("missing effective POM or dependency tree");
+  const main = dependencyTrees.filter(item => gav(item) === mainArtifact);
+  if (main.length !== 1) fail("missing or duplicate startup-module runtime tree");
+  const nodes = [];
+  const visit = item => { if (!["compile", "runtime"].includes(item.scope ?? "compile")) return; nodes.push(item); array(item.children).forEach(visit); };
+  array(main[0].children).forEach(visit);
+  const bom = parseXmlDocument(bootBom ?? "<missing/>").project;
+  if (bom?.groupId !== "org.springframework.boot" || bom.artifactId !== "spring-boot-dependencies" || bom.version !== profile.spring_boot_version) fail("wrong or missing independent Boot BOM");
+  const managed = new Map(array(bom.dependencyManagement?.dependencies?.dependency).map(item => [gav(item), item.version]));
+  if (!managed.size) fail("empty Boot BOM dependency management");
+  for (const item of nodes) {
+    const expected = managed.get(gav(item)) ?? components[gav(item)];
+    if (/^(com\.baomidou|org\.springdoc|org\.springframework\.cloud|com\.yss\.cloud)$/.test(item.groupId) && !expected) fail(`missing component recipe: ${gav(item)}`);
+    if (expected && String(item.version) !== String(expected)) fail(`resolved version differs from BOM/recipe: ${gav(item)}`);
+    if (/^(org\.springframework(?:\.boot)?$|org\.apache\.tomcat\.embed|jakarta\.(servlet|validation)|javax\.(servlet|validation)|(?:tools|com\.fasterxml)\.jackson|org\.slf4j|ch\.qos\.logback)/.test(item.groupId) && !expected) fail(`unmanaged platform runtime artifact: ${gav(item)}`);
+  }
+  const requireArtifact = (group, artifact, match) => {
+    const hits = nodes.filter(item => gav(item) === `${group}:${artifact}`);
+    if (!hits.length || hits.some(item => !match(String(item.version)))) fail(`${group}:${artifact} absent or incompatible`);
+  };
+  const line = (version, prefix) => version === prefix || version.startsWith(`${prefix}.`);
+  requireArtifact("org.springframework.boot", profile.web_starter, version => version === profile.spring_boot_version);
+  requireArtifact("org.springframework", "spring-webmvc", version => line(version, profile.framework_line));
+  requireArtifact("org.apache.tomcat.embed", "tomcat-embed-core", version => line(version, profile.tomcat_line));
+  requireArtifact("com.baomidou", profile.mybatis_plus_starter, version => /^3\./.test(version));
+  requireArtifact(profile.jackson_major === 3 ? "tools.jackson.core" : "com.fasterxml.jackson.core", "jackson-databind", version => version.startsWith(`${profile.jackson_major}.`));
+  for (const item of nodes) {
+    if (item.groupId === "org.springframework.boot" && String(item.version) !== profile.spring_boot_version) fail(`Boot dependency mismatch: ${gav(item)}`);
+    if (item.groupId === "org.springframework" && !line(String(item.version), profile.framework_line)) fail(`Spring dependency mismatch: ${gav(item)}`);
+    if (item.groupId === "org.apache.tomcat.embed" && !line(String(item.version), profile.tomcat_line)) fail(`Tomcat dependency mismatch: ${gav(item)}`);
+    if (item.groupId === "org.springframework.cloud" && /openfeign/.test(item.artifactId) && !line(String(item.version), profile.openfeign_line)) fail("OpenFeign line mismatch");
+    if (item.groupId === "org.springdoc" && !String(item.version).startsWith(`${profile.springdoc_major}.`)) fail("springdoc major mismatch");
+    if (profile.validation_namespace === "jakarta" && ["javax.servlet", "javax.validation"].includes(item.groupId)) fail(`legacy Java EE API: ${gav(item)}`);
+    if (profile.validation_namespace === "jakarta" && item.groupId === "jakarta.validation" && !String(item.version).startsWith("3.")) fail("Jakarta Validation version mismatch");
+    if (item.groupId === "jakarta.servlet" && !line(String(item.version), profile.servlet_version)) fail("Servlet API version mismatch");
+    if (profile.validation_namespace === "javax" && item.groupId === "jakarta.validation" && !String(item.version).startsWith("2.")) fail("Boot 2 requires javax Validation classes");
+    if (profile.validation_namespace === "javax" && item.groupId === "javax.servlet" && !String(item.version).startsWith("4.")) fail("Boot 2 Servlet mismatch");
+    if (item.groupId === "com.baomidou" && /spring-boot[34]-starter|mybatis-plus-boot-starter/.test(item.artifactId) && item.artifactId !== profile.mybatis_plus_starter) fail("mixed MyBatis-Plus starters");
+  }
+  let bootPluginFound = false;
+  for (const project of projects) {
+    const target = project.properties?.["maven.compiler.release"] ?? project.properties?.["maven.compiler.target"] ?? project.properties?.["java.version"];
+    if (![String(profile.java_version), ...(profile.java_version === 8 ? ["1.8"] : [])].includes(String(target))) fail("effective Java target mismatch");
+    for (const plugin of array(project.build?.plugins?.plugin)) if (gav(plugin) === "org.springframework.boot:spring-boot-maven-plugin") {
+      bootPluginFound = true;
+      if (plugin.version !== profile.spring_boot_version) fail("Boot plugin version mismatch");
+    }
+  }
+  if (!bootPluginFound) fail("Boot plugin absent");
+  return { status: "passed", runtime_artifacts: nodes, artifact_count: nodes.length, effective_pom_digest: platformDigest(effectivePom), dependency_tree_digest: platformDigest(dependencyTrees) };
+}
+
+export async function platformCommand(projectRoot, evidenceDir, label, args, environment, options = {}) {
+  const stdout_ref = path.join(evidenceDir, `${label}.stdout.log`);
+  const stderr_ref = path.join(evidenceDir, `${label}.stderr.log`);
+  const executed_at = new Date().toISOString();
+  const start = Date.now();
+  const result = await runCommand(path.join(projectRoot, "mvnw"), args, { cwd: projectRoot, env: environment, timeoutMs: options.timeoutMs || 180000, signal: options.signal, stdoutFile: stdout_ref, stderrFile: stderr_ref, secrets: [environment.MAVEN_REPO_USERNAME, environment.MAVEN_REPO_PASSWORD], progress: true });
+  return { command: `./mvnw ${args.join(" ")}`, exit_code: result.status, termination: result.termination, executed_at, duration_ms: Date.now() - start, stdout_ref, stderr_ref, stdout: result.stdout, stderr: result.stderr };
+}
+export async function verifyPlatformDependencies(projectRoot, evidenceDir, profile, environment, options = {}) {
+  const commands = [];
+  const run = async (label, args) => {
+    const result = await platformCommand(projectRoot, evidenceDir, label, args, environment, options);
+    const { stdout, stderr, ...record } = result;
+    commands.push(record);
+    if (result.exit_code !== 0) fail(`${label} failed; see ${record.stderr_ref}`);
+    return result;
+  };
+  try {
+    const java = await run("platform-java", ["-version"]);
+    assertJavaPlatform(`${java.stdout}\n${java.stderr}`, { java_version: profile.java_version });
+    const pom = path.join(evidenceDir, "effective-pom.xml");
+    const bootBom = path.join(evidenceDir, "boot-bom-effective.xml");
+    await run("platform-boot-bom", ["org.apache.maven.plugins:maven-help-plugin:3.5.1:effective-pom", `-Dartifact=org.springframework.boot:spring-boot-dependencies:${profile.spring_boot_version}`, `-Doutput=${bootBom}`]);
+    await run("platform-effective-pom", ["org.apache.maven.plugins:maven-help-plugin:3.5.1:effective-pom", `-Doutput=${pom}`]);
+    await run("platform-dependency-tree", ["org.apache.maven.plugins:maven-dependency-plugin:3.8.1:tree", "-DoutputType=json", "-DoutputFile=.yss/platform-dependencies.json"]);
+    const trees = [];
+    const visited = new Set();
+    for (const directory of [projectRoot, ...(await readdir(projectRoot, { withFileTypes: true })).filter(item => item.isDirectory() && item.name.startsWith(`${path.basename(projectRoot)}-`)).map(item => path.join(projectRoot, item.name))]) {
+      const candidates = [directory];
+      // DDD adapter contains the nested web module.
+      for (const entry of await readdir(directory, { withFileTypes: true })) if (entry.isDirectory() && entry.name.startsWith(`${path.basename(projectRoot)}-`)) candidates.push(path.join(directory, entry.name));
+      for (const candidate of candidates) {
+        if (visited.has(candidate)) continue;
+        visited.add(candidate);
+        try { trees.push(JSON.parse(await readFile(path.join(candidate, ".yss/platform-dependencies.json"), "utf8"))); }
+        catch (error) { if (error.code !== "ENOENT") throw error; }
+      }
+    }
+    await writeFile(path.join(evidenceDir, "dependency-trees.json"), JSON.stringify(trees, null, 2));
+    return { ...checkPlatformDependencies(profile, await readFile(pom, "utf8"), trees, { bootBom: await readFile(bootBom, "utf8"), mainArtifact: `${options.manifest.maven_coordinates.group_id}:${options.manifest.project_name}-${options.manifest.architecture_family === "domain-driven" ? "bootstrap" : "server"}`, components: options.components }), commands };
+  } catch (error) { return { status: "failed", error: error.message, commands }; }
+}
+
+async function freePort() {
+  const server = net.createServer();
+  await new Promise((resolve, reject) => { server.once("error", reject); server.listen(0, "127.0.0.1", resolve); });
+  const port = server.address().port;
+  await new Promise(resolve => server.close(resolve));
+  return port;
+}
+export function checkRuntimeArchive(entries, artifacts, { providedLombokVersion } = {}) {
+  if (!Array.isArray(artifacts) || !artifacts.length) fail("missing runtime artifact inventory");
+  const names = new Set(entries.split(/\r?\n/));
+  const expected = new Set();
+  for (const item of artifacts.filter(item => (item.type ?? "jar") === "jar")) {
+    const name = `BOOT-INF/lib/${item.artifactId}-${item.version}${item.classifier ? `-${item.classifier}` : ""}.jar`;
+    expected.add(name);
+    if (!names.has(name)) fail(`runtime jar missing ${name}`);
+  }
+  const bootVersion = artifacts.find(item => item.groupId === "org.springframework.boot")?.version;
+  // Boot's repackage goal injects its matching jarmode helper outside the dependency tree.
+  for (const name of names) if (name.startsWith("BOOT-INF/lib/") && name.endsWith(".jar") && !expected.has(name)
+    && name !== `BOOT-INF/lib/lombok-${providedLombokVersion}.jar`
+    && !["tools", "layertools"].some(kind => name === `BOOT-INF/lib/spring-boot-jarmode-${kind}-${bootVersion}.jar`)) fail(`unexpected packaged runtime jar: ${name}`);
+  return { status: "passed" };
+}
+async function inspectRuntimeJar(jar, evidenceDir, environment, options) {
+  const tool = environment.JAVA_HOME ? path.join(environment.JAVA_HOME, "bin/jar") : "jar";
+  const stdoutFile = path.join(evidenceDir, "runtime-jar-entries.log");
+  const stderrFile = path.join(evidenceDir, "runtime-jar.stderr.log");
+  const result = await runCommand(tool, ["tf", jar], { env: environment, timeoutMs: 30000, stdoutFile, stderrFile });
+  if (result.status !== 0) fail("cannot inspect packaged runtime jar");
+  return checkRuntimeArchive(result.stdout, options.runtimeArtifacts, options);
+}
+export async function verifyPlatformStartup(projectRoot, evidenceDir, manifest, environment, options = {}) {
+  const runtimeModule = `${manifest.project_name}-${manifest.architecture_family === "domain-driven" ? "bootstrap" : "server"}`;
+  const runtimeTarget = path.join(projectRoot, runtimeModule, "target");
+  try {
+    const packaged = (await readdir(runtimeTarget)).filter(name => name.endsWith(".jar") && !/-sources|-javadoc|-tests/.test(name));
+    if (packaged.length !== 1) fail("expected exactly one production runtime jar");
+    await inspectRuntimeJar(path.join(runtimeTarget, packaged[0]), evidenceDir, environment, options);
+  } catch (error) { return { status: "failed", error: error.message, commands: [] }; }
+  const packaging = await platformCommand(projectRoot, evidenceDir, "platform-local-package", ["-Pscaffold-local", "package", "-DskipTests"], environment, options);
+  const { stdout: ignoredOut, stderr: ignoredErr, ...command } = packaging;
+  if (packaging.exit_code !== 0) return { status: "failed", error: "local packaging failed", commands: [command] };
+  const module = `${manifest.project_name}-${manifest.architecture_family === "domain-driven" ? "bootstrap" : "server"}`;
+  const target = path.join(projectRoot, module, "target");
+  const jars = (await readdir(target)).filter(name => name.endsWith(".jar") && !/-sources|-javadoc|-tests/.test(name));
+  if (jars.length !== 1) return { status: "failed", error: "expected exactly one executable jar", commands: [command] };
+  const port = await freePort();
+  const java = environment.JAVA_HOME ? path.join(environment.JAVA_HOME, "bin/java") : "java";
+  const args = ["-jar", path.join(target, jars[0]), "--spring.profiles.active=scaffold-local", "--server.address=127.0.0.1", `--server.port=${port}`];
+  const processStartedAt = new Date().toISOString();
+  let output = "", errors = "", started = false, exited = false;
+  const child = spawn(java, args, { cwd: projectRoot, env: environment, stdio: ["ignore", "pipe", "pipe"] });
+  child.stdout.on("data", data => { output += data; if (/Started .* in /.test(output)) started = true; });
+  child.stderr.on("data", data => { errors += data; });
+  child.on("error", error => { errors += error.message; exited = true; });
+  const closed = new Promise(resolve => child.once("close", code => { exited = true; resolve(code); }));
+  let passed = false;
+  const deadline = Date.now() + Math.min(options.timeoutMs || 60000, 120000);
+  try {
+    while (!exited && Date.now() < deadline && !options.signal?.aborted) {
+      if (started) {
+        try { const response = await fetch(`http://127.0.0.1:${port}/`, { signal: AbortSignal.timeout(1000) }); if (response.status > 0 && response.status < 500) { passed = true; break; } } catch {}
+      }
+      await new Promise(resolve => setTimeout(resolve, 250));
+    }
+  } finally {
+    if (!exited) child.kill("SIGTERM");
+    const killTimer = setTimeout(() => { if (!exited) child.kill("SIGKILL"); }, 3000);
+    await closed; clearTimeout(killTimer);
+  }
+  const redact = text => [environment.MAVEN_REPO_USERNAME, environment.MAVEN_REPO_PASSWORD].filter(Boolean).reduce((value, secret) => value.replaceAll(secret, "[REDACTED]"), text);
+  await writeFile(path.join(evidenceDir, "startup.stdout.log"), redact(output));
+  await writeFile(path.join(evidenceDir, "startup.stderr.log"), redact(errors));
+  return { status: passed ? "passed" : "failed", commands: [command], executed_at: processStartedAt, artifact_digest: platformDigest(await readFile(path.join(target, jars[0]))), stdout_ref: path.join(evidenceDir, "startup.stdout.log"), stderr_ref: path.join(evidenceDir, "startup.stderr.log") };
+}

package/template/scripts/lib/backend-platform.mjs

@@ -0,0 +1,175 @@
+import { assertSourceFingerprint } from "./backend-platform-provenance.mjs";
+/** Shared, exact backend platform selection. Catalog entries are maintenance-owned. */
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const PLATFORM_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+export const PLATFORM_CATALOG_REF = "docs/engineering/backend-platforms.json";
+export const PLATFORM_SKILLS = ["yss-ddd-scaffold-generator", "yss-layered-mvc-scaffold-generator"];
+const fail = (message) => { throw new TypeError(`backend-platform: ${message}`); };
+const stable = (value) => Array.isArray(value) ? value.map(stable) : value && typeof value === "object" ? Object.fromEntries(Object.keys(value).sort().map(key => [key, stable(value[key])])) : value;
+export const platformDigest = value => `sha256:${createHash("sha256").update(typeof value === "string" || Buffer.isBuffer(value) ? value : JSON.stringify(stable(value ?? null))).digest("hex")}`;
+export function loadBackendPlatforms(root = PLATFORM_ROOT) {
+  const value = JSON.parse(readFileSync(path.join(root, PLATFORM_CATALOG_REF), "utf8"));
+  if (value.schema_version !== 1 || value.kind !== "backend-platform-catalog" || !Array.isArray(value.profiles) || !Array.isArray(value.compatibility)) fail("invalid catalog");
+  if (new Set(value.profiles.map(item => `${item.id}:${item.spring_boot_version}:${item.java_version}`)).size !== value.profiles.length || new Set(value.compatibility.map(item => item.id)).size !== value.compatibility.length) fail("duplicate catalog release/id");
+  for (const profile of value.profiles) if (!/^\d+\.\d+\.\d+$/.test(profile.spring_boot_version)) fail("catalog requires exact patch versions");
+  return value;
+}
+export function platformProfile(id, catalog = loadBackendPlatforms(), version) {
+  const matches = catalog.profiles.filter(item => item.id === id && (!version || item.spring_boot_version === version));
+  if (matches.length > 1) fail("multiple patches: select an exact spring_boot_version");
+  const result = matches[0];
+  if (!result) fail(`unsupported platform_profile: ${id}`);
+  return result;
+}
+export function platformRecipeDigest(profile, entry) {
+  const { candidate_blockers, recommended, ...recipe } = profile;
+  return platformDigest({ profile: recipe, entry: { id: entry.id, profile_id: entry.profile_id, spring_boot_version: entry.spring_boot_version, parent: entry.parent, bom: entry.bom, components: entry.components ?? {} } });
+}
+export function platformBinding(profile, entry) {
+  return { schema_version: 2, profile_id: profile.id, spring_boot_version: profile.spring_boot_version, java_version: profile.java_version, parent: entry.parent, bom: entry.bom, compatibility_id: entry.id, compatibility_digest: platformRecipeDigest(profile, entry) };
+}
+export function resolveBackendPlatform(binding, { catalog = loadBackendPlatforms(), requireVerified = true, root = PLATFORM_ROOT } = {}) {
+  if (!binding || binding.schema_version !== 2) fail("missing platform_configuration v2 (v1 is historical read-only); 生命周期须展示 Boot/Java/YSS 组合并取得用户确认");
+  const profile = platformProfile(binding.profile_id, catalog, binding.spring_boot_version);
+  if (binding.spring_boot_version !== profile.spring_boot_version || binding.java_version !== profile.java_version) fail("unsupported exact Boot/Java combination (x/latest and Java 8/11 for Boot 3.5/4.1 are rejected)");
+  const entry = catalog.compatibility.find(item => item.id === binding.compatibility_id);
+  const evidenceReports = [];
+  if (!entry || entry.profile_id !== profile.id || entry.spring_boot_version !== profile.spring_boot_version) fail("YSS compatibility entry missing; parent/BOM/starter verification required");
+  if (platformDigest(binding) !== platformDigest(platformBinding(profile, entry))) fail("stale compatibility digest or YSS coordinates");
+  if (requireVerified) {
+    if (entry.status !== "verified") fail(`YSS combination ${entry.id} is not verified`);
+    if (!Array.isArray(entry.evidence) || !entry.evidence.length) fail("verified combination lacks evidence");
+    for (const item of entry.evidence) {
+      if (!item.ref || !item.digest || path.isAbsolute(item.ref) || item.ref.split(/[\\/]/).includes("..")) fail("invalid portable evidence reference");
+      const bytes = readFileSync(path.join(root, item.ref));
+      if (platformDigest(bytes) !== item.digest) fail("compatibility evidence drift");
+      const report = JSON.parse(bytes);
+      if (report.verification_scope !== "empty-scaffold") fail("qualification requires empty-scaffold evidence");
+      if (report.recipe_digest !== platformRecipeDigest(profile, entry)) fail("evidence recipe drift");
+      assertSourceFingerprint(report.source_fingerprint, report.architecture_family);
+      if (!/^sha256:[a-f0-9]{64}$/.test(report.generated_tree_digest ?? "")) fail("missing generated tree digest");
+      evidenceReports.push(report);
+      if (report.status !== "passed" || report.spring_boot_version !== profile.spring_boot_version || report.java_version !== profile.java_version || report.architecture_family !== item.architecture_family || platformDigest(report.parent) !== platformDigest(entry.parent) || platformDigest(report.bom) !== platformDigest(entry.bom)) fail("compatibility evidence identity mismatch");
+      for (const phase of ["validate", "test", "package"]) if (!report.commands?.some(cmd => cmd.command === `./mvnw ${phase}` && cmd.exit_code === 0 && cmd.stdout_ref && cmd.stderr_ref && cmd.executed_at)) fail("missing real Maven evidence");
+      if (report.dependency_check !== "passed" || report.startup_check !== "passed" || report.integration_tests?.status !== "passed") fail("missing dependency/startup/integration-test evidence");
+      const required = ["effective-pom.xml", "dependency-trees.json", "platform-tests.xml", "boot-bom-effective.xml", "runtime-jar-entries.log", "startup.stdout.log", "startup.stderr.log", ...["validate", "test", "package"].flatMap(phase => [`mvnw-${phase}.stdout.log`, `mvnw-${phase}.stderr.log`])];
+      if (!Array.isArray(report.evidence_artifacts) || required.some(ref => !report.evidence_artifacts.some(artifact => artifact.ref === ref))) fail("missing portable evidence artifacts");
+      for (const artifact of report.evidence_artifacts) {
+        if (!artifact.ref || path.isAbsolute(artifact.ref) || artifact.ref.split(/[\\/]/).includes("..")) fail("invalid evidence artifact path");
+        if (platformDigest(readFileSync(path.join(root, path.dirname(item.ref), artifact.ref))) !== artifact.digest) fail("evidence artifact drift");
+      }
+    }
+  }
+  return { profile, entry, evidenceReports };
+}
+export function assertContractPlatform(contract, decision, options = {}) {
+  const binding = contract.platform_configuration;
+  const resolved = resolveBackendPlatform(binding, options);
+  if (contract.profiles?.platform !== resolved.profile.id || contract.profiles?.validation_namespace !== resolved.profile.validation_namespace) fail("platform and validation_namespace are inconsistent");
+  if (platformDigest(contract.maven_coordinates?.parent) !== platformDigest(binding.parent) || contract.maven_coordinates?.yss_components_version !== binding.bom.version || binding.bom.group_id !== "com.yss.cloud" || binding.bom.artifact_id !== "yss-components-bom") fail("YSS Maven coordinates mismatch");
+  if (decision && platformDigest(decision.platform_configuration) !== platformDigest(binding)) fail("decision/contract platform_configuration mismatch");
+  if (options.requireVerified !== false && !resolved.entry.evidence?.some(item => item.architecture_family === contract.architecture_family)) fail("architecture has no compatibility evidence");
+  for (const capability of contract.module_profile?.requested_capabilities ?? []) if (!resolved.entry.capabilities?.includes(capability)) fail(`unverified capability: ${capability}`);
+  if (options.requireVerified !== false && !resolved.evidenceReports.some(report => report.architecture_family === contract.architecture_family && (contract.module_profile?.requested_capabilities ?? []).every(capability => report.verified_capabilities?.includes(capability)))) fail("architecture/capability combination lacks evidence");
+  return resolved;
+}
+export function assertPlatformAgreement(left, right) {
+  if (platformDigest(left) !== platformDigest(right)) fail("platform_configuration drift between contract and Manifest");
+}
+export function javaMajor(output) {
+  const value = output.match(/(?:java|openjdk) version "(?:1\.)?(\d+)|Java version:\s*(?:1\.)?(\d+)/i);
+  return value ? Number(value[1] ?? value[2]) : null;
+}
+export function assertJavaPlatform(output, binding) {
+  if (javaMajor(output) !== binding.java_version) fail(`JDK mismatch: expected Java ${binding.java_version}`);
+}
+export function platformTemplateVars(profile) {
+  return { boot_version: profile.spring_boot_version, java_version: profile.java_version === 8 ? "1.8" : String(profile.java_version), java_range: profile.java_version === 8 ? "[1.8,1.9)" : `[${profile.java_version},${profile.java_version + 1})`, web_starter: profile.web_starter, web_test_starter: profile.web_test_starter, aop_starter: profile.aop_starter, swagger_artifact: profile.swagger_artifact, ...Object.fromEntries(Object.entries(profile.versions).map(([key, value]) => [`${key}_version`, value])) };
+}
+
+export function platformSmokeTest(basePackage, profile, capabilities = []) {
+  const mapper = profile.jackson_major === 3 ? "tools.jackson.databind.json.JsonMapper" : "com.fasterxml.jackson.databind.ObjectMapper";
+  return `package ${basePackage};
+
+import ${profile.validation_namespace}.validation.Validator;
+import ${profile.validation_namespace}.validation.Valid;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.context.annotation.Import;
+import org.springframework.web.bind.annotation.RestController;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import ${profile.validation_namespace}.validation.constraints.NotBlank;
+import ${mapper};
+import org.apache.ibatis.annotations.Select;
+import org.apache.ibatis.session.SqlSession;
+import org.apache.ibatis.session.SqlSessionFactory;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.test.context.ActiveProfiles;
+import static org.junit.jupiter.api.Assertions.*;
+
+/** Mechanical integration only: no business endpoint or production storage. */
+@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
+@Import(PlatformIntegrationTest.ProbeController.class)
+@ActiveProfiles("scaffold-test")
+class PlatformIntegrationTest {
+    @Value("\${local.server.port}") int port;
+    @Autowired Validator validator;
+    public static class ProbePayload {
+        @NotBlank private String value;
+        public String getValue() { return value; }
+        public void setValue(String value) { this.value = value; }
+    }
+    @RestController
+    public static class ProbeController {
+        @PostMapping(value = "/__scaffold_probe", consumes = "application/json", produces = "application/json")
+        public ProbePayload echo(@Valid @RequestBody ProbePayload body) { return body; }
+    }
+    @Test void httpJsonRoundTrip() throws Exception { httpProbe("probe", 200); }
+    @Test void httpValidationRejectsBlank() throws Exception { httpProbe("", 400); }
+    private void httpProbe(String value, int expectedStatus) throws Exception {
+        java.net.HttpURLConnection connection = (java.net.HttpURLConnection) new java.net.URL("http://127.0.0.1:" + port + "/__scaffold_probe").openConnection();
+        connection.setConnectTimeout(5000); connection.setReadTimeout(5000);
+        connection.setRequestMethod("POST"); connection.setRequestProperty("Content-Type", "application/json"); connection.setDoOutput(true);
+        ProbePayload request = new ProbePayload(); request.setValue(value);
+        try {
+            try (java.io.OutputStream stream = connection.getOutputStream()) { stream.write(mapper.writeValueAsBytes(request)); }
+            assertEquals(expectedStatus, connection.getResponseCode());
+            if (expectedStatus == 200) {
+                assertTrue(connection.getContentType().startsWith("application/json"));
+                try (java.io.InputStream stream = connection.getInputStream()) { assertEquals(value, mapper.readValue(stream, ProbePayload.class).getValue()); }
+            }
+        } finally { connection.disconnect(); }
+    }
+    @Autowired ${mapper.split(".").at(-1)} mapper;
+    @Autowired SqlSessionFactory sqlSessionFactory;
+    static final class ValidationProbe { @NotBlank String value = ""; }
+    @Test void validationAndJsonAutoConfiguration() throws Exception {
+        assertFalse(validator.validate(new ValidationProbe()).isEmpty());
+        assertEquals("\\\"probe\\\"", mapper.writeValueAsString("probe"));
+    }
+    interface ProbeMapper { @Select("SELECT 1") int probe(); }
+    @Test void mybatisCanMapVerificationQuery() throws Exception {
+        try (SqlSession session = sqlSessionFactory.openSession()) {
+            if (!session.getConfiguration().hasMapper(ProbeMapper.class)) session.getConfiguration().addMapper(ProbeMapper.class);
+            assertEquals(1, session.getMapper(ProbeMapper.class).probe());
+        }
+    }
+${capabilities.includes("feign-client") ? `    @Autowired org.springframework.cloud.openfeign.${profile.java_version === 8 ? "FeignContext" : "FeignClientFactory"} feignFactory;
+    @Test void feignCanDecodeJson() throws Exception {
+        feign.codec.Decoder decoder = feignFactory.getInstance("platform-probe", feign.codec.Decoder.class);
+        assertNotNull(decoder);
+        feign.Request request = feign.Request.create(feign.Request.HttpMethod.GET, "http://localhost/probe", java.util.Collections.emptyMap(), (byte[]) null, java.nio.charset.StandardCharsets.UTF_8, null);
+        feign.Response response = feign.Response.builder().request(request).status(200).reason("OK")
+            .headers(java.util.Collections.singletonMap("Content-Type", java.util.Collections.singletonList("application/json")))
+            .body("{}", java.nio.charset.StandardCharsets.UTF_8).build();
+        assertTrue(decoder.decode(response, java.util.Map.class) instanceof java.util.Map);
+    }
+` : ""}}
+`;
+}

package/template/scripts/lib/backend-scaffold-prerequisites.mjs

@@ -0,0 +1,123 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { parseDocument } from "../vendor/yaml.mjs";
+import { loadApprovalRecord, validateApprovalRecord } from "./approval-record.mjs";
+import { validateJsonSchema } from "./json-schema.mjs";
+import { ROOT } from "./lifecycle-registry.mjs";
+import { validateTechnicalDesign } from "../../.agents/skills/yss-technical-design/scripts/validate-technical-design.mjs";
+import { validateApiContractDecision } from "./api-contract-decision.mjs";
+
+const DATA_DECISION_SCHEMA = path.join(ROOT, "docs/process/schemas/data-architecture-decision.schema.json");
+
+const fail = (message) => { throw new TypeError(message); };
+const digest = (bytes) => `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+const text = (value) => typeof value === "string" && value.trim().length > 0;
+
+function resolveLocalRef(root, ref, label) {
+  if (!text(ref) || /^[a-z][a-z0-9+.-]*:\/\//i.test(ref)) fail(`${label} 必须是可读取的本地文件引用`);
+  const resolved = path.isAbsolute(ref) ? path.normalize(ref) : path.resolve(root, ref);
+  if (!existsSync(resolved)) fail(`${label} 不可读取: ${ref}`);
+  return resolved;
+}
+
+export function findGovernanceRoot(contractFile) {
+  let current = path.dirname(path.resolve(contractFile));
+  const fallback = current;
+  while (true) {
+    if (existsSync(path.join(current, "yss-project.yaml"))) return current;
+    const parent = path.dirname(current);
+    if (parent === current) return fallback;
+    current = parent;
+  }
+}
+
+function readDocument(root, binding, label) {
+  if (!binding || !text(binding.ref) || !text(binding.digest)) fail(`${label} 缺少 ref/digest`);
+  const file = resolveLocalRef(root, binding.ref, label);
+  const bytes = readFileSync(file);
+  if (digest(bytes) !== binding.digest) fail(`${label} 原始字节摘要漂移`);
+  const document = parseDocument(bytes.toString("utf8"), { maxAliasCount: 0, uniqueKeys: true });
+  if (document.errors.length) fail(`${label} 无法解析: ${document.errors[0].message}`);
+  const value = document.toJS({ maxAliasCount: 0 });
+  if (!value || typeof value !== "object" || Array.isArray(value)) fail(`${label} 必须是对象`);
+  return { file, bytes, value };
+}
+
+function requireReadableRefs(root, refs, label) {
+  if (!Array.isArray(refs) || refs.length === 0) fail(`${label} 必须包含可读取证据`);
+  for (const ref of refs) resolveLocalRef(root, ref, label);
+}
+
+function requireArtifactBinding(record, expected, label) {
+  const binding = (record.artifact_bindings || []).find((item) => item?.id === expected.id);
+  if (!binding || binding.version !== expected.version || binding.digest !== expected.digest) fail(`${label} 未绑定当前资产版本和摘要`);
+}
+
+function requireExactBinding(actual, expected, label, { impact = false, id = false } = {}) {
+  const keys = ["ref", "version", "digest", ...(impact ? ["impact"] : []), ...(id ? ["id"] : [])];
+  if (!actual || keys.some((key) => actual[key] !== expected[key])) fail(`${label} 未原子绑定当前资产`);
+}
+
+function requireEngineeringPackage(root, approval, contract, technical, data, api, prerequisites) {
+  const packageFile = resolveLocalRef(root, approval.subject_ref, "工程合同批准主体");
+  const packageDocument = parseDocument(readFileSync(packageFile, "utf8"), { maxAliasCount: 0, uniqueKeys: true });
+  if (packageDocument.errors.length) fail(`工程合同批准主体无法解析: ${packageDocument.errors[0].message}`);
+  const value = packageDocument.toJS({ maxAliasCount: 0 });
+  if (value?.schema_version !== 1 || value?.kind !== "engineering-contract-package" || value?.project_id !== contract.project_name) fail("工程合同批准主体必须是当前项目的 engineering-contract-package v1");
+  requireExactBinding(value.technical_design, { ...prerequisites.technical_design, version: technical.value.version }, "工程合同包 Technical Design");
+  requireExactBinding(value.data_architecture_decision, { ...prerequisites.data_architecture_decision, version: data.value.decision_version, impact: data.value.impact }, "工程合同包 Data Architecture Decision", { impact: true });
+  requireExactBinding(value.api_contract_decision, { ...prerequisites.api_contract_decision, version: api.decision.decision_version, impact: api.decision.impact }, "工程合同包 API Contract Decision", { impact: true });
+  if (api.decision.impact === "required") {
+    requireExactBinding(value.frozen_openapi, api.decision.openapi, "工程合同包冻结 OpenAPI", { id: true });
+  } else if (Object.hasOwn(value, "frozen_openapi")) {
+    fail("API not-applicable 的工程合同包禁止携带 frozen_openapi 占位字段");
+  }
+}
+
+export async function validateBackendScaffoldPrerequisites(contract, { contractFile, root = findGovernanceRoot(contractFile) } = {}) {
+  if (contract?.schema_version !== 4 || contract?.delivery_role !== "backend") fail("后端新生成只接受 Project Scaffold Contract v4");
+  const prerequisites = contract.design_prerequisites;
+  if (!prerequisites || typeof prerequisites !== "object") fail("后端脚手架合同缺少 design_prerequisites");
+
+  const technical = readDocument(root, prerequisites.technical_design, "Technical Design");
+  if (technical.value.schema_version !== 2 || technical.value.status !== "approved" || technical.value.version !== prerequisites.technical_design.version) fail("Technical Design 必须是 approved 的当前 v2 合同");
+  if (technical.value.architecture?.family !== contract.architecture_family || technical.value.architecture?.project_id !== contract.project_name || technical.value.architecture?.decision_digest !== contract.decision_digest) fail("Technical Design 与脚手架架构决定不一致");
+  await validateTechnicalDesign(technical.value, { root });
+
+  const data = readDocument(root, prerequisites.data_architecture_decision, "数据架构决定");
+  validateJsonSchema(data.value, DATA_DECISION_SCHEMA, { label: "Data Architecture Decision v1" });
+  if (data.value.decision_version !== prerequisites.data_architecture_decision.version) fail("数据架构决定版本不匹配");
+  const assessment = resolveLocalRef(root, data.value.assessment_ref, "数据影响评估");
+  if (digest(readFileSync(assessment)) !== data.value.assessment_digest) fail("数据影响评估摘要漂移");
+  requireReadableRefs(root, data.value.evidence_refs, "数据架构决定证据");
+  if (data.value.impact === "required") {
+    const architecture = resolveLocalRef(root, data.value.data_architecture_ref, "数据架构文档");
+    if (digest(readFileSync(architecture)) !== data.value.data_architecture_digest) fail("数据架构文档摘要漂移");
+    requireReadableRefs(root, data.value.review_evidence_refs, "数据架构评审证据");
+  }
+
+  const api = validateApiContractDecision(prerequisites.api_contract_decision, { root });
+
+  const approvalRef = prerequisites.engineering_contract_approval_ref;
+  if (approvalRef !== contract.lifecycle_approval_ref || approvalRef !== contract.approval?.approval_ref) fail("工程合同批准引用与脚手架合同不一致");
+  const approvalFile = resolveLocalRef(root, approvalRef, "工程合同批准记录");
+  const approval = loadApprovalRecord(approvalFile, 'gate.engineering-contract-approved');
+  validateApprovalRecord(approval, { requireApproved: true, root });
+  if (approval.gate_id !== "gate.engineering-contract-approved") fail("工程合同批准记录 gate_id 必须为 gate.engineering-contract-approved");
+  if (!Array.isArray(approval.approval_scope) || !approval.approval_scope.includes(contract.contract_id) || !approval.approval_scope.includes(contract.project_name)) fail("工程合同批准范围未覆盖当前合同和项目");
+  requireEngineeringPackage(root, approval, contract, technical, data, api, prerequisites);
+  requireArtifactBinding(approval, { id: technical.value.technical_design_id, version: technical.value.version, digest: prerequisites.technical_design.digest }, "工程合同批准记录");
+  requireArtifactBinding(approval, { id: data.value.decision_id, version: data.value.decision_version, digest: prerequisites.data_architecture_decision.digest }, "工程合同批准记录");
+  requireArtifactBinding(approval, { id: api.decision.decision_id, version: api.decision.decision_version, digest: prerequisites.api_contract_decision.digest }, "工程合同批准记录");
+  if (api.decision.impact === "required") {
+    requireArtifactBinding(approval, { id: api.decision.openapi.id, version: api.decision.openapi.version, digest: api.decision.openapi.digest }, "工程合同批准记录");
+  }
+
+  return {
+    technical_design: { ref: prerequisites.technical_design.ref, version: technical.value.version, digest: prerequisites.technical_design.digest },
+    data_architecture_decision: { ref: prerequisites.data_architecture_decision.ref, version: data.value.decision_version, digest: prerequisites.data_architecture_decision.digest, impact: data.value.impact },
+    api_contract_decision: { ref: prerequisites.api_contract_decision.ref, version: api.decision.decision_version, digest: prerequisites.api_contract_decision.digest, impact: api.decision.impact },
+    engineering_contract_approval_ref: approvalRef,
+  };
+}