create-yss-spec 3.4.4 → 3.4.6

package/template/.codex/skills/yss-skill-source-index-refresh/scripts/refresh-yss-skill-index.mjs

@@ -2,11 +2,10 @@
 import { createHash } from "node:crypto";
 import { execFileSync } from "node:child_process";
 import { access, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
-import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
-const BACKEND = {
+export const BACKEND = {
   "yss-cache": ["yss-microservice-components/yss-component-cache-parent"],
   "yss-mybatis": ["yss-microservice-components/yss-component-persistence"],
   "yss-dto": ["yss-microservice-components/yss-component-dto"],
@@ -20,15 +19,41 @@ const BACKEND = {
     "yss-microservice-components/yss-component-leaf",
   ],
   "yss-resilience4j": ["yss-microservice-components/yss-component-resilience4j-starter"],
-  "yss-validation": [
-    "yss-microservice-components/yss-component-validation-engine-parent",
-    "yss-microservice-components/yss-component-validation-jsr303",
-  ],
+  "yss-validation": ["yss-microservice-components/yss-component-validation-jsr303"],
   "yss-security-algorithm": ["yss-microservice-components/yss-component-security-algorithm"],
   "yss-userinfo": ["yss-microservice-components/yss-component-userinfo-starter"],
   "yss-exception": ["yss-microservice-components/yss-component-exception"],
 };
 
+export const BACKEND_PLATFORM_LINES = Object.freeze({
+  "boot2-java8": Object.freeze({
+    env: "YSS_SOURCE_ROOT_BOOT2_JAVA8",
+    label: "Spring Boot 2.7 / Java 8 maintenance line",
+  }),
+  "boot3-java17": Object.freeze({
+    env: "YSS_SOURCE_ROOT_BOOT3_JAVA17",
+    label: "Spring Boot 3.5 / Java 17 mainline",
+  }),
+});
+
+const BACKEND_PATH_OVERRIDES = Object.freeze({
+  "boot2-java8": Object.freeze({}),
+  "boot3-java17": Object.freeze({
+    "yss-excel-mvc": Object.freeze(["yss-microservice-components/yss-component-excel-mvc"]),
+  }),
+});
+
+export function backendComponentPaths(skill, platformLine) {
+  if (!BACKEND_PLATFORM_LINES[platformLine]) throw new TypeError(`unknown backend component platform line: ${platformLine}`);
+  if (!BACKEND[skill]) throw new TypeError(`unknown backend component skill: ${skill}`);
+  return BACKEND_PATH_OVERRIDES[platformLine][skill] ?? BACKEND[skill];
+}
+
+export function backendPlatformIndexPath(skillsRoot, skill, platformLine) {
+  if (!BACKEND_PLATFORM_LINES[platformLine]) throw new TypeError(`unknown backend component platform line: ${platformLine}`);
+  return path.join(skillsRoot, skill, "references", `source-index.${platformLine}.md`);
+}
+
 const FRONTEND = {
   "yss-ui": ["components", "hooks", "skills"],
   "yss-hook": ["hooks"],
@@ -165,42 +190,23 @@ export function sourceState(root, componentPaths) {
   }
 }
 
-async function sourceRoot() {
-  if (process.env.YSS_SOURCE_ROOT) {
-    const root = path.resolve(process.env.YSS_SOURCE_ROOT);
-    if (await exists(path.join(root, "yss-microservice-components"))) return root;
-    throw new Error(`YSS_SOURCE_ROOT must point to the repository root containing \`yss-microservice-components\`: ${root}`);
-  }
-
-  const home = os.homedir();
-  const candidates = [
-    process.cwd(),
-    ...ancestors(process.cwd()),
-    path.join(home, "Documents/yss-project/yss-cloud-microservice"),
-    path.join(home, "Documents/yss-project"),
-    path.join(home, "Projects/yss-cloud-microservice"),
-    path.join(home, "Projects"),
-  ];
-  for (const base of [path.join(home, "Projects"), path.join(home, "Documents"), path.join(home, "Documents/yss-project")]) {
-    if (!await exists(base)) continue;
-    for (const entry of await readdir(base, { withFileTypes: true })) {
-      if (entry.isDirectory()) candidates.push(path.join(base, entry.name));
+async function configuredSourceRoots() {
+  const entries = [];
+  for (const [platformLine, contract] of Object.entries(BACKEND_PLATFORM_LINES)) {
+    const configured = process.env[contract.env];
+    if (!configured) continue;
+    const root = path.resolve(configured);
+    if (!await exists(path.join(root, "yss-microservice-components"))) {
+      throw new Error(`${contract.env} must point to the repository root containing \`yss-microservice-components\`: ${root}`);
     }
+    entries.push([platformLine, root]);
   }
-  for (const root of candidates) {
-    if (await exists(path.join(root, "yss-microservice-components"))) return path.resolve(root);
+  if (entries.length === Object.keys(BACKEND_PLATFORM_LINES).length) return Object.fromEntries(entries);
+  if (entries.length) {
+    const missing = Object.values(BACKEND_PLATFORM_LINES).filter((item) => !process.env[item.env]).map((item) => item.env);
+    throw new Error(`dual-track refresh requires both backend source roots; missing ${missing.join(", ")}`);
   }
-  throw new Error("Could not find a YSS source repository containing `yss-microservice-components`. Export YSS_SOURCE_ROOT=/absolute/path/to/yss-cloud-microservice and rerun.");
-}
-
-function ancestors(start) {
-  const output = [];
-  let current = path.resolve(start);
-  while (path.dirname(current) !== current) {
-    current = path.dirname(current);
-    output.push(current);
-  }
-  return output;
+  throw new Error(`Set both ${Object.values(BACKEND_PLATFORM_LINES).map((item) => item.env).join(" and ")} to clean, generation-specific YSS source roots.`);
 }
 
 async function files(bases) {
@@ -210,13 +216,170 @@ async function files(bases) {
       if (DOCS.has(path.basename(target))) output.docs.push(target);
       else if (path.basename(target) === "pom.xml") output.poms.push(target);
       else if (target.endsWith(".java") && target.includes(`${path.sep}src${path.sep}main${path.sep}java${path.sep}`)) output.java.push(target);
-      else if (path.basename(target) === "spring.factories") output.metadata.push(target);
+      else if (["spring.factories", "org.springframework.boot.autoconfigure.AutoConfiguration.imports"].includes(path.basename(target))) output.metadata.push(target);
     }
   }
   for (const items of Object.values(output)) items.sort();
   return output;
 }
 
+function xmlText(contents, tag) {
+  const match = contents.match(new RegExp(`<${tag}(?:\\s[^>]*)?>([\\s\\S]*?)<\\/${tag}>`));
+  return match ? match[1].trim() : null;
+}
+
+function xmlSection(contents, tag) {
+  const match = contents.match(new RegExp(`<${tag}(?:\\s[^>]*)?>[\\s\\S]*?<\\/${tag}>`));
+  return match?.[0] ?? null;
+}
+
+function xmlProperties(contents) {
+  const block = xmlText(contents, "properties");
+  if (!block) return {};
+  return Object.fromEntries([...block.matchAll(/<([A-Za-z0-9_.-]+)(?:\s[^>]*)?>([^<]*)<\/\1>/g)]
+    .map((match) => [match[1], match[2].trim()]));
+}
+
+function pomCoordinateText(contents, tag) {
+  let direct = contents;
+  for (const nested of ["parent", "properties", "modules", "dependencyManagement", "dependencies", "build", "profiles", "repositories", "pluginRepositories", "distributionManagement", "reporting"]) {
+    direct = direct.replace(new RegExp(`<${nested}(?:\\s[^>]*)?>[\\s\\S]*?<\\/${nested}>`, "g"), "");
+  }
+  return xmlText(direct, tag);
+}
+
+function resolveProperties(value, properties) {
+  let result = value;
+  for (let round = 0; result && round < 8; round += 1) {
+    const next = result.replace(/\$\{([^}]+)\}/g, (whole, key) => properties[key] ?? whole);
+    if (next === result) break;
+    result = next;
+  }
+  return result;
+}
+
+export async function assertSourcePlatformLine(source, platformLine) {
+  if (!BACKEND_PLATFORM_LINES[platformLine]) throw new TypeError(`unknown backend component platform line: ${platformLine}`);
+  const rootPom = path.join(source, "pom.xml");
+  if (!await exists(rootPom)) throw new Error(`backend source root has no pom.xml: ${source}`);
+  const contents = (await readFile(rootPom, "utf8")).replace(/<!--[\s\S]*?-->/g, "");
+  const parent = xmlSection(contents, "parent");
+  const parentVersion = parent ? xmlText(parent, "version") : null;
+  const properties = {
+    ...xmlProperties(contents),
+    "project.parent.version": parentVersion,
+    "parent.version": parentVersion,
+  };
+  const javaVersion = resolveProperties(properties["java.version"] ?? properties["maven.compiler.release"] ?? properties["maven.compiler.source"], properties);
+  const bootVersion = resolveProperties(properties["spring-boot.version"] ?? parentVersion, properties);
+  const matches = platformLine === "boot2-java8"
+    ? /^(?:1\.)?8(?:\D|$)/.test(javaVersion ?? "") && /^2\./.test(bootVersion ?? "")
+    : /^17(?:\D|$)/.test(javaVersion ?? "") && /^3\./.test(bootVersion ?? "");
+  if (!matches) throw new Error(`source root does not match ${platformLine}: java=${javaVersion ?? "unknown"}, spring-boot=${bootVersion ?? "unknown"}`);
+  return { platformLine, javaVersion, bootVersion };
+}
+
+async function pomLineage(source, target, seen = new Set()) {
+  const normalized = path.resolve(target);
+  if (seen.has(normalized) || !await exists(normalized)) return [];
+  seen.add(normalized);
+  const contents = (await readFile(normalized, "utf8")).replace(/<!--[\s\S]*?-->/g, "");
+  const parent = xmlSection(contents, "parent");
+  let inherited = [];
+  if (parent && !/<relativePath\s*\/>/.test(parent)) {
+    const relativePath = xmlText(parent, "relativePath") ?? "../pom.xml";
+    const parentPath = path.resolve(path.dirname(normalized), relativePath);
+    const withinSource = path.relative(source, parentPath);
+    if (!withinSource.startsWith("..") && !path.isAbsolute(withinSource)) inherited = await pomLineage(source, parentPath, seen);
+  }
+  const body = parent ? contents.replace(parent, "") : contents;
+  const parentCoordinates = parent ? {
+    groupId: xmlText(parent, "groupId"),
+    artifactId: xmlText(parent, "artifactId"),
+    version: xmlText(parent, "version"),
+  } : {};
+  return [...inherited, {
+    path: relative(source, normalized),
+    groupId: pomCoordinateText(body, "groupId"),
+    artifactId: pomCoordinateText(body, "artifactId"),
+    version: pomCoordinateText(body, "version"),
+    parent: parentCoordinates,
+    properties: xmlProperties(contents),
+  }];
+}
+
+async function mavenAndPlatformFacts(source, pomFiles, javaFiles, metadataFiles) {
+  const gavLines = [];
+  const javaVersions = new Set();
+  const bootVersions = new Set();
+  for (const target of pomFiles) {
+    const lineage = await pomLineage(source, target);
+    const inheritedProperties = {};
+    for (const item of lineage) {
+      const itemParent = item.parent ?? {};
+      const itemResolution = {
+        ...inheritedProperties,
+        ...item.properties,
+        "project.groupId": item.groupId ?? itemParent.groupId,
+        "project.artifactId": item.artifactId,
+        "project.version": item.version ?? itemParent.version,
+        "project.parent.groupId": itemParent.groupId,
+        "project.parent.artifactId": itemParent.artifactId,
+        "project.parent.version": itemParent.version,
+        "parent.groupId": itemParent.groupId,
+        "parent.artifactId": itemParent.artifactId,
+        "parent.version": itemParent.version,
+      };
+      for (const [key, value] of Object.entries(item.properties)) inheritedProperties[key] = resolveProperties(value, itemResolution);
+    }
+    const current = lineage.at(-1) ?? {};
+    const parent = current.parent ?? {};
+    const properties = {
+      ...inheritedProperties,
+      "project.groupId": current.groupId ?? parent.groupId,
+      "project.artifactId": current.artifactId,
+      "project.version": current.version ?? parent.version,
+      "project.parent.groupId": parent.groupId,
+      "project.parent.artifactId": parent.artifactId,
+      "project.parent.version": parent.version,
+      "parent.groupId": parent.groupId,
+      "parent.artifactId": parent.artifactId,
+      "parent.version": parent.version,
+    };
+    const groupId = resolveProperties(current.groupId ?? parent.groupId ?? "unknown", properties);
+    const artifactId = resolveProperties(current.artifactId ?? "unknown", properties);
+    const version = resolveProperties(current.version ?? parent.version ?? "unknown", properties);
+    const parentGav = parent.artifactId
+      ? `${resolveProperties(parent.groupId ?? "unknown", properties)}:${resolveProperties(parent.artifactId, properties)}:${resolveProperties(parent.version ?? "unknown", properties)}`
+      : "none";
+    gavLines.push(`- \`${relative(source, target)}\` — GAV \`${groupId}:${artifactId}:${version}\`; parent \`${parentGav}\``);
+    const javaVersion = inheritedProperties["java.version"] ?? inheritedProperties["maven.compiler.release"] ?? inheritedProperties["maven.compiler.source"];
+    const bootVersion = inheritedProperties["spring-boot.version"]
+      ?? (parent.groupId === "org.springframework.boot" ? parent.version : null);
+    if (javaVersion) javaVersions.add(resolveProperties(javaVersion, properties));
+    if (bootVersion) bootVersions.add(resolveProperties(bootVersion, properties));
+  }
+  let javaxFiles = 0;
+  let jakartaFiles = 0;
+  for (const target of javaFiles) {
+    const contents = await readFile(target, "utf8");
+    if (/\b(?:import|extends|implements|new)\s+javax\.|\bjavax\./.test(contents)) javaxFiles += 1;
+    if (/\b(?:import|extends|implements|new)\s+jakarta\.|\bjakarta\./.test(contents)) jakartaFiles += 1;
+  }
+  const springFactories = metadataFiles.filter((target) => path.basename(target) === "spring.factories").length;
+  const autoConfigurationImports = metadataFiles.filter((target) => path.basename(target) === "org.springframework.boot.autoconfigure.AutoConfiguration.imports").length;
+  return {
+    gavLines,
+    platformLines: [
+      `- Inherited Java signals: ${javaVersions.size ? [...javaVersions].map((item) => `\`${item}\``).join(", ") : "not declared in the local POM lineage"}.`,
+      `- Inherited Spring Boot signals: ${bootVersions.size ? [...bootVersions].map((item) => `\`${item}\``).join(", ") : "not declared in the local POM lineage"}.`,
+      `- Namespace source signals: \`javax.*\` in ${javaxFiles} main Java files; \`jakarta.*\` in ${jakartaFiles} main Java files.`,
+      `- Auto-configuration metadata: ${springFactories} \`spring.factories\`; ${autoConfigurationImports} \`AutoConfiguration.imports\` files.`,
+      "- These are source observations, not compatibility certification. Use the approved `platform_configuration` and verified compatibility evidence before integration or generation.",
+    ],
+  };
+}
+
 async function sha256(target) {
   return createHash("sha256").update(await readFile(target)).digest("hex");
 }
@@ -278,7 +441,7 @@ async function mybatisCapabilityMatrix(source, javaFiles, metadataFiles) {
   return output;
 }
 
-async function backendIndex({ skill, parts, source, found, now, stateResolver }) {
+async function backendIndex({ skill, parts, source, platformLine, found, now, stateResolver }) {
   const currentState = stateResolver(source, parts);
   const bases = parts.map((item) => path.join(source, item));
   const baseHints = await Promise.all(bases.map(async (target) =>
@@ -287,14 +450,17 @@ async function backendIndex({ skill, parts, source, found, now, stateResolver })
   const treeLines = currentState.componentTrees.map(({ path: componentPath, tree }) =>
     `Component tree \`${componentPath}\`: \`${tree}\``,
   );
+  const facts = await mavenAndPlatformFacts(source, found.poms, found.java, found.metadata);
   const lines = [
     `# ${skill} Source Index`,
     "",
+    "Index schema: `backend-component-source-index-v2`",
+    `Platform line: \`${platformLine}\``,
     `Generated: ${now}`,
     `Source commit: \`${currentState.commit}\``,
     `Component worktree: \`${currentState.componentWorktree}\``,
     ...treeLines,
-    "Indexed source root: resolved at refresh time; set `YSS_SOURCE_ROOT` to reproduce or refresh.",
+    `Indexed source root: resolved at refresh time; set \`${BACKEND_PLATFORM_LINES[platformLine].env}\` to reproduce or refresh.`,
     "",
     "This file is generated by `yss-skill-source-index-refresh/scripts/refresh-yss-skill-index.mjs`. Do not hand-edit generated sections.",
     "",
@@ -312,7 +478,11 @@ async function backendIndex({ skill, parts, source, found, now, stateResolver })
     "",
     "## Maven Modules",
     "",
-    ...list(found.poms, (target) => `- \`${relative(source, path.dirname(target))}\``, "- No Maven modules found."),
+    ...(facts.gavLines.length ? facts.gavLines : ["- No Maven modules found."]),
+    "",
+    "## Platform Signals",
+    "",
+    ...facts.platformLines,
     "",
   ];
 
@@ -322,8 +492,9 @@ async function backendIndex({ skill, parts, source, found, now, stateResolver })
   lines.push(
     "## Freshness and Use",
     "",
-    "- Locate the current source root using `YSS_SOURCE_ROOT`, CodeGraph, Maven artifact names or repository search.",
+    `- Locate the current source root using \`${BACKEND_PLATFORM_LINES[platformLine].env}\`, CodeGraph, Maven artifact names or repository search.`,
     "- Compare each indexed `Component tree` with `git rev-parse HEAD:<component-path>` and require the current component subtree to be clean before exact guidance.",
+    `- Run \`node ../yss-skill-source-index-refresh/scripts/check-backend-skill-source-index.mjs --skill <skill-id> --platform-line ${platformLine} --source-root <root>\` from the canonical skill root before exact integration guidance.`,
     "- A repository commit difference alone is not stale when the component tree is unchanged; a component tree mismatch or component-local dirty state is stale.",
     "- Read only the source entries needed for the current decision or troubleshooting path.",
     "",
@@ -333,7 +504,7 @@ async function backendIndex({ skill, parts, source, found, now, stateResolver })
 
 export async function refresh({
   skillsRoot,
-  source,
+  sources,
   now = new Date().toISOString(),
   frontend = true,
   backendSkills = Object.keys(BACKEND),
@@ -341,13 +512,35 @@ export async function refresh({
 }) {
   const unknownSkills = backendSkills.filter((skill) => !(skill in BACKEND));
   if (unknownSkills.length) throw new Error(`Unknown backend source-index skill: ${unknownSkills.join(", ")}`);
+  const sourceEntries = Object.entries(sources ?? {});
+  const unknownLines = sourceEntries.filter(([platformLine]) => !BACKEND_PLATFORM_LINES[platformLine]).map(([platformLine]) => platformLine);
+  if (unknownLines.length) throw new Error(`Unknown backend platform line: ${unknownLines.join(", ")}`);
+  if (backendSkills.length && sourceEntries.length === 0) throw new Error("Backend source-index refresh requires at least one explicit platform source root.");
+  for (const [platformLine, source] of sourceEntries) await assertSourcePlatformLine(source, platformLine);
   for (const skill of backendSkills) {
-    const parts = BACKEND[skill];
-    const bases = parts.map((item) => path.join(source, item));
-    const found = await files(bases);
-    const target = path.join(skillsRoot, skill, "references", "source-index.md");
-    await mkdir(path.dirname(target), { recursive: true });
-    await writeFile(target, await backendIndex({ skill, parts, source, found, now, stateResolver }), "utf8");
+    const referenceRoot = path.join(skillsRoot, skill, "references");
+    await mkdir(referenceRoot, { recursive: true });
+    for (const [platformLine, source] of sourceEntries) {
+      const parts = backendComponentPaths(skill, platformLine);
+      const bases = parts.map((item) => path.join(source, item));
+      const found = await files(bases);
+      const target = backendPlatformIndexPath(skillsRoot, skill, platformLine);
+      await writeFile(target, await backendIndex({ skill, parts, source, platformLine, found, now, stateResolver }), "utf8");
+    }
+    await writeFile(path.join(referenceRoot, "source-index.md"), [
+      `# ${skill} Source Index Router`,
+      "",
+      "Index schema: `backend-component-source-index-router-v1`",
+      "",
+      "Select the source index from the approved `platform_configuration.component_platform_line`; do not infer a line from imports, a branch name or a requested upgrade.",
+      "",
+      ...Object.entries(BACKEND_PLATFORM_LINES).map(([platformLine, contract]) =>
+        `- \`${platformLine}\` — [${contract.label}](source-index.${platformLine}.md)`,
+      ),
+      "",
+      "Run the freshness checker with the same explicit `--platform-line` and its matching clean source root before exact integration guidance.",
+      "",
+    ].join("\n"), "utf8");
   }
 
   if (frontend) {
@@ -369,7 +562,7 @@ export async function refresh({
       ].join("\n"), "utf8");
     }
   }
-  return { backend: backendSkills.length, frontend: frontend ? Object.keys(FRONTEND).length : 0 };
+  return { backend: backendSkills.length, backendTracks: backendSkills.length * sourceEntries.length, frontend: frontend ? Object.keys(FRONTEND).length : 0 };
 }
 
 async function main() {
@@ -377,13 +570,13 @@ async function main() {
     const script = path.dirname(fileURLToPath(import.meta.url));
     const result = await refresh({
       skillsRoot: path.resolve(process.env.YSS_SKILLS_ROOT || path.join(script, "../..")),
-      source: await sourceRoot(),
+      sources: await configuredSourceRoots(),
       frontend: !["0", "false", "no"].includes((process.env.YSS_REFRESH_FRONTEND || "true").toLowerCase()),
       backendSkills: process.env.YSS_REFRESH_BACKEND_SKILLS
         ? process.env.YSS_REFRESH_BACKEND_SKILLS.split(",").map((skill) => skill.trim()).filter(Boolean)
         : Object.keys(BACKEND),
     });
-    console.log(`Updated ${result.backend} backend indexes and ${result.frontend} frontend doc references.`);
+    console.log(`Updated ${result.backendTracks} backend platform indexes for ${result.backend} skills and ${result.frontend} frontend doc references.`);
   } catch (error) {
     console.error(error.message);
     process.exitCode = 1;

package/template/.codex/skills/yss-skill-source-index-refresh/scripts/refresh-yss-skill-index.test.mjs

@@ -4,15 +4,38 @@ import { mkdir, mkdtemp, readFile, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import test from "node:test";
-import { refresh, sourceState } from "./refresh-yss-skill-index.mjs";
+import { BACKEND, backendComponentPaths, refresh, sourceState } from "./refresh-yss-skill-index.mjs";
+import { checkBackendSkillSourceIndex } from "./check-backend-skill-source-index.mjs";
+
+const platformPom = (javaVersion, bootVersion) => `<project><parent><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><version>${bootVersion}</version><relativePath/></parent><artifactId>fixture</artifactId><version>1.0.0</version><properties><java.version>${javaVersion}</java.version><spring-boot.version>\${project.parent.version}</spring-boot.version></properties></project>`;
 
 test("writes Node-labelled generated indexes", async () => {
-  const root=await mkdtemp(path.join(tmpdir(),"yss-index-")); const source=path.join(root,"source"); const skills=path.join(root,"skills");
-  await mkdir(path.join(source,"yss-microservice-components/yss-component-cache-parent/src/main/java/demo"),{recursive:true}); await writeFile(path.join(source,"yss-microservice-components/yss-component-cache-parent/src/main/java/demo/CacheConfiguration.java"),"class CacheConfiguration {}");
+  const root=await mkdtemp(path.join(tmpdir(),"yss-index-")); const boot2=path.join(root,"boot2"); const boot3=path.join(root,"boot3"); const skills=path.join(root,"skills");
+  for (const [source, javaVersion, bootVersion] of [[boot2,"1.8","2.7.18"],[boot3,"17","3.5.16"]]) {
+    await mkdir(path.join(source,"yss-microservice-components/yss-component-cache-parent/src/main/java/demo"),{recursive:true});
+    await writeFile(path.join(source,"pom.xml"),platformPom(javaVersion,bootVersion));
+    await writeFile(path.join(source,"yss-microservice-components/yss-component-cache-parent/src/main/java/demo/CacheConfiguration.java"),"class CacheConfiguration {}");
+  }
   for(const name of ["yss-cache","yss-ui"])await mkdir(path.join(skills,name),{recursive:true});
-  await refresh({skillsRoot:skills,source,now:"2026-01-01T00:00:00Z"});
-  assert.match(await readFile(path.join(skills,"yss-cache/references/source-index.md"),"utf8"),/refresh-yss-skill-index\.mjs/);
+  await refresh({skillsRoot:skills,sources:{"boot2-java8":boot2,"boot3-java17":boot3},now:"2026-01-01T00:00:00Z"});
+  assert.match(await readFile(path.join(skills,"yss-cache/references/source-index.md"),"utf8"),/backend-component-source-index-router-v1/);
+  assert.match(await readFile(path.join(skills,"yss-cache/references/source-index.boot2-java8.md"),"utf8"),/Platform line: `boot2-java8`/);
+  assert.match(await readFile(path.join(skills,"yss-cache/references/source-index.boot3-java17.md"),"utf8"),/Platform line: `boot3-java17`/);
   assert.match(await readFile(path.join(skills,"yss-ui/references/frontend-docs.md"),"utf8"),/components/);
+  await assert.rejects(
+    () => refresh({skillsRoot:skills,sources:{"boot3-java17":boot2},frontend:false,backendSkills:["yss-cache"]}),
+    /source root does not match boot3-java17/,
+  );
+});
+
+test("keeps generation-specific component path sets", () => {
+  assert.deepEqual(backendComponentPaths("yss-excel-mvc", "boot2-java8"), [
+    "yss-microservice-components/yss-component-excel-mvc",
+    "yss-microservice-components/yss-component-excel-starter",
+  ]);
+  assert.deepEqual(backendComponentPaths("yss-excel-mvc", "boot3-java17"), [
+    "yss-microservice-components/yss-component-excel-mvc",
+  ]);
 });
 
 test("writes a source-backed MyBatis capability matrix without absolute paths", async () => {
@@ -28,6 +51,7 @@ test("writes a source-backed MyBatis capability matrix without absolute paths",
   await mkdir(path.join(baseJava, "config"), { recursive: true });
   await mkdir(commonJava, { recursive: true });
   await mkdir(path.join(skills, "yss-mybatis"), { recursive: true });
+  await writeFile(path.join(source, "pom.xml"), platformPom("1.8", "2.7.18"));
   await writeFile(path.join(source, component, "pom.xml"), "<project/>");
   await writeFile(path.join(plusJava, "support/BasePlusRepository.java"), [
     "public interface BasePlusRepository<T> extends BaseMapper<T> {",
@@ -48,7 +72,7 @@ test("writes a source-backed MyBatis capability matrix without absolute paths",
 
   await refresh({
     skillsRoot: skills,
-    source,
+    sources: { "boot2-java8": source },
     now: "2026-01-01T00:00:00Z",
     frontend: false,
     backendSkills: ["yss-mybatis"],
@@ -59,7 +83,7 @@ test("writes a source-backed MyBatis capability matrix without absolute paths",
     }),
   });
 
-  const index = await readFile(path.join(skills, "yss-mybatis/references/source-index.md"), "utf8");
+  const index = await readFile(path.join(skills, "yss-mybatis/references/source-index.boot2-java8.md"), "utf8");
   assert.match(index, /## Capability Matrix/);
   assert.match(index, /BasePlusRepository<T>/);
   assert.match(index, /yss\.mybatis\.page-helper\.enabled/);
@@ -91,3 +115,46 @@ test("source freshness is scoped to the indexed component subtree", async () =>
   await writeFile(componentFile, "<project><dirty/></project>\n");
   assert.equal(sourceState(root, [component]).componentWorktree, "dirty");
 });
+
+test("records Maven lineage and platform signals and validates the exact component tree", async () => {
+  const root = await mkdtemp(path.join(tmpdir(), "yss-platform-index-"));
+  const source = path.join(root, "source");
+  const skills = path.join(root, "skills");
+  const component = "yss-microservice-components/yss-component-validation-jsr303";
+  const javaFile = path.join(source, component, "src/main/java/demo/ValidationConfiguration.java");
+  await mkdir(path.dirname(javaFile), { recursive: true });
+  await mkdir(path.join(skills, "yss-validation"), { recursive: true });
+  await writeFile(path.join(source, "pom.xml"), `<project>
+    <parent><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><version>2.7.18</version><relativePath/></parent>
+    <groupId>com.yss.cloud</groupId><artifactId>yss-cloud-microservice</artifactId><version>2.0.0-SNAPSHOT</version>
+    <properties><java.version>1.8</java.version><spring-boot.version>\${project.parent.version}</spring-boot.version></properties>
+  </project>`);
+  await writeFile(path.join(source, "yss-microservice-components/pom.xml"), `<project><parent>
+    <groupId>com.yss.cloud</groupId><artifactId>yss-cloud-microservice</artifactId><version>2.0.0-SNAPSHOT</version><relativePath>../pom.xml</relativePath>
+  </parent><artifactId>yss-microservice-components</artifactId></project>`);
+  await writeFile(path.join(source, component, "pom.xml"), `<project><parent>
+    <groupId>com.yss.cloud</groupId><artifactId>yss-microservice-components</artifactId><version>2.0.0-SNAPSHOT</version><relativePath>../pom.xml</relativePath>
+  </parent><artifactId>yss-component-validation-jsr303</artifactId></project>`);
+  await writeFile(javaFile, "package demo; import javax.validation.Valid; class ValidationConfiguration {}\n");
+  execFileSync("git", ["init", "-q"], { cwd: source });
+  execFileSync("git", ["config", "user.email", "test@example.com"], { cwd: source });
+  execFileSync("git", ["config", "user.name", "Test"], { cwd: source });
+  execFileSync("git", ["add", "."], { cwd: source });
+  execFileSync("git", ["commit", "-qm", "fixture"], { cwd: source });
+
+  await refresh({ skillsRoot: skills, sources: { "boot2-java8": source }, frontend: false, backendSkills: ["yss-validation"], now: "2026-01-01T00:00:00Z" });
+  const index = await readFile(path.join(skills, "yss-validation/references/source-index.boot2-java8.md"), "utf8");
+  assert.match(index, /backend-component-source-index-v2/);
+  assert.match(index, /GAV `com\.yss\.cloud:yss-component-validation-jsr303:2\.0\.0-SNAPSHOT`/);
+  assert.match(index, /Inherited Java signals: `1\.8`/);
+  assert.match(index, /Inherited Spring Boot signals: `2\.7\.18`/);
+  assert.match(index, /`javax\.\*` in 1 main Java files; `jakarta\.\*` in 0/);
+  assert.deepEqual(BACKEND["yss-validation"], [component]);
+  await checkBackendSkillSourceIndex({ skill: "yss-validation", platformLine: "boot2-java8", skillsRoot: skills, sourceRoot: source });
+
+  await writeFile(javaFile, "package demo; import jakarta.validation.Valid; class ValidationConfiguration {}\n");
+  await assert.rejects(
+    () => checkBackendSkillSourceIndex({ skill: "yss-validation", platformLine: "boot2-java8", skillsRoot: skills, sourceRoot: source }),
+    /component worktree is dirty/,
+  );
+});

package/template/.codex/skills/yss-tactical-design/SKILL.md

@@ -9,7 +9,7 @@ description: 在 YSS 技术分析阶段将批准的战略领域输入细化为
 
 ## 适用边界
 
-- 由 `yss-technical-design` 在已确认 `domain-driven` 的技术设计分支中调用；新建后端必须先通过 `gate.backend-architecture-platform-approved`，由用户在同一次决定中确认 DDD / MVC 与精确 Spring Boot 版本。传统 MVC 使用 `yss-mvc-design`；既有工程直接核验并复用当前登记架构及固定工程基线/POM 中的实际 Spring Boot 版本，不重复询问。不得按状态、一致性影响、目录或默认值单独推断为 DDD。
+- 由 `yss-technical-design` 在已确认 `domain-driven` 的技术设计分支中调用；新建后端必须先通过 `gate.backend-architecture-platform-approved`，由用户在同一次决定中确认 DDD / MVC 与精确 Spring Boot 版本。传统 MVC 由 `yss-technical-design` 自身的 `layered-mvc` 分支负责；既有工程直接核验并复用当前登记架构及固定工程基线/POM 中的实际 Spring Boot 版本，不重复询问。不得按状态、一致性影响、目录或默认值单独推断为 DDD。
 - 输入必须是版本当前的 Spec、功能架构、战略 DDD、状态矩阵、OpenAPI Draft / Freeze、ADR 和工程约束。若输入来自 Strategic Design Handoff，必须先用 `scripts/verify-strategic-context-import` 验证历史 v3/v4 或当前 v5 的 `source_context_snapshot` / `context_delta` 已对账到目标仓根 `CONTEXT.md`，对应的 prototype 或 existing UI baseline 可读取且摘要当前，并且目标侧 `context_reconciliation` 有效；未完成时不得开始战术建模。
 - 默认将结果写入系统概要设计 / 数据架构中的 Tactical DDD Check；聚合、状态机、一致性或持久化映射复杂到无法清楚表达时，才升级为独立战术设计文档。
 - 没有聚合、状态、不变量、一致性或领域边界影响时返回 `not-applicable` 及原因，不生成空设计。

package/template/.codex/skills/yss-tactical-design/references/output-template.md

@@ -5,7 +5,7 @@ owner: ai
 
 # <功能名称> Tactical DDD Design
 
-仅用于已确认 domain-driven 分支的阅读视图；引用 Technical Design Contract v2 的 design，不复制共同输入与审批状态。MVC 使用 yss-mvc-design。
+仅用于已确认 domain-driven 分支的阅读视图；引用 Technical Design Contract v2 的 design，不复制共同输入与审批状态。MVC 使用 `yss-technical-design` 的 `layered-mvc` 分支。
 
 ## 上游引用
 

package/template/.codex/skills/yss-technical-design/SKILL.md

@@ -20,7 +20,7 @@ description: 在 YSS 技术分析中统一承接需求与战略输入，按已
 按项目绑定架构选择的来源及摘要。新工程必须先通过 `gate.backend-architecture-platform-approved`：Agent 展示 DDD / MVC 推荐依据及平台清单中的精确 Spring Boot、Java 版本，用户在同一次决定中确认两项内容；决定持久化到 `scaffold-architecture-decisions.yaml`，再进入对应分支，后续脚手架消费同一决定。既有工程核验并沿用当前登记架构及固定工程基线/POM 中的实际 Spring Boot 版本，该门禁记录为 `not-applicable`，不重复询问；架构转换或平台升级另行立项。只有 `domain-driven` 和 `layered-mvc` 两种架构族，不能从目录推断或默认 DDD、MVC 或 Spring Boot 版本。具体 Profile 及模块边界消费技能注册表与 `docs/agents/backend-architecture-profiles.md`。
 
 - `domain-driven`：调用 `yss-tactical-design`，补齐适用的战略领域输入。
-- `layered-mvc`：调用 `yss-mvc-design`，不要求战略 DDD、聚合、值对象、Domain Event 或 DDD Gateway。
+- `layered-mvc`：由本 skill 直接设计模块职责与依赖方向、用例流程、业务规则、状态转换、事务与回滚、幂等与并发、持久化映射、外部集成和公开测试 seam；不要求战略 DDD、聚合、值对象、Domain Event 或 DDD Gateway。分层边界消费 `docs/agents/backend-architecture-profiles.md`，不得为 MVC 加载 `yss-domain` 或生成 DDD Gateway。
 
 已有 Strategic Design Handoff 时，两种分支都必须先完成导入和目标词汇对账，再逐条承接规则与关键场景。没有战略交接包的项目直接消费批准需求，不能为 MVC 补造战略 DDD。
 
@@ -30,6 +30,8 @@ description: 在 YSS 技术分析中统一承接需求与战略输入，按已
 
 新产物使用 schema v2 Technical Design Contract：共同头记录架构来源、输入版本与摘要、规则/场景承接、评审证据和状态，`design` 保存架构专属内容。合同格式与兼容规则见 `references/technical-design-contract.md`，Schema 见 `references/technical-design.schema.json`。
 
+MVC `design` 分支由 `references/mvc-design.schema.json` 约束。无状态流转或外部集成时记录有依据的不适用；业务规则和关键场景必须关联具体用例与成功/失败测试 seam。MVC 与 DDD 使用同一承接和审查要求，不能因采用分层 MVC 省略规则、一致性或测试设计。历史 `yss-mvc-design` 入口仅保留迁移提示，不再拥有该能力或被新合同调用。
+
 运行 `node .agents/skills/yss-technical-design/scripts/validate-technical-design.mjs <合同> --root <项目根>`。整体存在延期或冲突即阻断整体；相关切片可带 `--slice <切片ID>` 按依赖核验，仍须合同已批准。校验成功只返回审查输入，不批准、不设置 `ready-for-agent`。
 
 schema v1 战术合同只按 DDD 显式兼容读取；使用 `--legacy-ddd`，不能解释为 MVC。迁移不自动批准，输入或架构变化必须重新校验并按现有门禁审查。新合同使用 `artifact.technical-design` / `evidence.technical-design-review`；旧 DDD 稳定 ID 保留原含义。