create-yss-spec 3.4.4 → 3.4.6

package/template/.pi/skills/yss-layered-mvc-scaffold-generator/scripts/data-analysis-profile.mjs

@@ -0,0 +1,82 @@
+import { createHash } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { cp, lstat, mkdir, mkdtemp, readFile, rename, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const REPOSITORY_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../..");
+const digest = (value) => `sha256:${createHash("sha256").update(value).digest("hex")}`;
+
+async function present(target) {
+  try { await lstat(target); return true; }
+  catch (error) { if (error.code === "ENOENT") return false; throw error; }
+}
+
+async function put(target, text) {
+  await mkdir(path.dirname(target), { recursive: true });
+  await writeFile(target, `${text.trimEnd()}\n`);
+}
+
+function within(parent, target) {
+  const relative = path.relative(parent, target);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+async function sharedTools(outputDir, contract) {
+  const destination = path.join(outputDir, "skillUtils");
+  if (!contract.allowed_write_paths.some((item) => within(path.resolve(outputDir, item), destination))) throw new Error("skillUtils 不在批准写范围内");
+  const lock = await readFile(path.join(REPOSITORY_ROOT, "skills-lock.json"));
+  if (await present(destination)) {
+    if (!await present(path.join(destination, "skill-utils.yaml")) || !lock.equals(await readFile(path.join(destination, "skills-lock.json")))) throw new Error("已有 skillUtils 不匹配；须独立批准刷新，初始化不会覆盖");
+    return digest(lock);
+  }
+  const staging = await mkdtemp(path.join(outputDir, ".skillUtils.staging-"));
+  try {
+    for (const relative of [".agents/skills", ".codex/skills", ".cursor/skills", ".pi/skills", "scripts", "docs/agents", "docs/process", "AGENTS.md", "skills-lock.json"]) {
+      await mkdir(path.dirname(path.join(staging, relative)), { recursive: true });
+      await cp(path.join(REPOSITORY_ROOT, relative), path.join(staging, relative), { recursive: true });
+    }
+    await put(path.join(staging, "skill-utils.yaml"), "schema_version: 1\nkind: yss-skill-utils\ncompatibility: skill-utils-v1\ncanonical_root: .agents/skills");
+    await rename(staging, destination);
+  } catch (error) {
+    await rm(staging, { recursive: true, force: true });
+    throw error;
+  }
+  return digest(lock);
+}
+
+export async function finalizeDataAnalysisProfile({ projectRoot, contract, architectureIdentity, options }) {
+  if (!contract.context_handoff_ref || !contract.context_handoff_digest) throw new Error("缺少批准的 context_handoff_ref/context_handoff_digest");
+  const contractFile = path.resolve(options.contractFile);
+  const contractRoot = path.dirname(contractFile);
+  const handoffPath = path.resolve(contractRoot, contract.context_handoff_ref);
+  if (!within(contractRoot, handoffPath)) throw new Error("CONTEXT handoff 不得越过脚手架合同目录");
+  const context = await readFile(handoffPath);
+  if (digest(context) !== contract.context_handoff_digest || !/^---\r?\ncontext_schema_version: 1\r?\n---/m.test(context.toString())) throw new Error("CONTEXT handoff schema/digest 不匹配");
+  if (spawnSync("git", ["--version"]).status !== 0) throw new Error("Git 不可用");
+
+  for (const relative of ["docs/agents", "docs/process", "docs/templates", "docs/architecture/templates"]) {
+    await mkdir(path.dirname(path.join(projectRoot, relative)), { recursive: true });
+    await cp(path.join(REPOSITORY_ROOT, relative), path.join(projectRoot, relative), { recursive: true });
+  }
+  await put(path.join(projectRoot, "CONTEXT.md"), context.toString());
+  const agents = (await readFile(path.join(REPOSITORY_ROOT, "AGENTS.md"), "utf8"))
+    .replace(/## 4\. `template-source` 模板维护路由[\s\S]*?(?=## 5\.)/, "## 4. 模板维护\n\n本仓为 project-instance；模板维护回上游执行。\n\n")
+    .replaceAll(".agents/skills", "../skillUtils/.agents/skills");
+  await put(path.join(projectRoot, "AGENTS.md"), agents);
+  await put(path.join(projectRoot, "yss-project.yaml"), "schema_version: 1\nrepository_mode: project-instance");
+  await put(path.join(projectRoot, ".artifact-workspace.yaml"), `schema_version: 1\nkind: service\nservice_id: ${options.projectName}`);
+  await cp(path.join(REPOSITORY_ROOT, "scripts/lib"), path.join(projectRoot, "scripts/lib"), { recursive: true });
+  await cp(path.join(REPOSITORY_ROOT, "scripts/vendor"), path.join(projectRoot, "scripts/vendor"), { recursive: true });
+  for (const name of ["repository-mode", "implementation-path-policy", "repository-scope-policy", "generate-lifecycle-artifacts", "node-generate-lifecycle-artifacts.mjs", "verify-lifecycle-registry", "node-verify-lifecycle-registry.mjs", "verify-lifecycle-checkpoint", "verify-context-reconciliation", "verify-approval-record", "verify-user-decision", "verify-digital-human-task-package", "verify-yss-dto-openapi-profile", "verify-frontend-implementation-evidence"]) {
+    await cp(path.join(REPOSITORY_ROOT, "scripts", name), path.join(projectRoot, "scripts", name));
+  }
+  const lockDigest = await sharedTools(path.resolve(options.outputDir), contract);
+  await put(path.join(projectRoot, "skills-lock.json"), JSON.stringify({ version: 1, distribution: { mode: "sibling-directory", skillUtilsDir: "../skillUtils", required: true, compatibility: "skill-utils-v1", lock_digest: lockDigest } }, null, 2));
+  await put(path.join(projectRoot, "docs/process/engineering-baseline.json"), JSON.stringify({ schema_version: 1, architecture_identity: architectureIdentity, platform_profile: contract.profiles.platform, scaffold_completion: "generated" }, null, 2));
+  await put(path.join(projectRoot, "docs/process/implementation-repo-registry.yaml"), JSON.stringify({ schema_version: 1, projects: [{ project_type: "backend", project_name: options.projectName, project_root: ".", git_root: ".", repository_scope: "external-repository", scaffold_status: "initialized", default_branch: "main", architecture_identity: architectureIdentity, allowed_write_paths: ["."], verification_commands: contract.verification_commands, expected_evidence_files: contract.expected_evidence_files, ci: "not-configured", rollback_point: "initial-empty-repository" }] }, null, 2));
+  await put(path.join(projectRoot, "docs/process/service-initialization.json"), JSON.stringify({ work_unit: "work-unit.service-project-initialization", context_handoff_ref: contract.context_handoff_ref, context_handoff_digest: contract.context_handoff_digest, contract_id: contract.contract_id, architecture_identity: architectureIdentity, status: "generated" }, null, 2));
+  await put(path.join(projectRoot, ".gitignore"), "target/\n**/target/\n.idea/\n*.iml\n.env\n.env.*\n.local/");
+  const git = spawnSync("git", ["init", "--initial-branch=main"], { cwd: projectRoot, encoding: "utf8" });
+  if (git.status !== 0) throw new Error(`Git 初始化失败: ${git.stderr}`);
+}

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

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 /** 依据生命周期批准的 schema v4 合同生成纯机械 YSS 分层 MVC 后端骨架。 */
 import { platformSourceFingerprint, generatedTreeDigest } from "../../../../scripts/lib/backend-platform-provenance.mjs";
-import { assertContractPlatform, platformProfile, platformTemplateVars, platformSmokeTest } from "../../../../scripts/lib/backend-platform.mjs";
+import { assertContractPlatform, platformTemplateVars, platformSmokeTest } from "../../../../scripts/lib/backend-platform.mjs";
 import { assertScaffoldUserDecision } from "../../../../scripts/lib/user-decision.mjs";
 import { validateBackendScaffoldPrerequisites } from "../../../../scripts/lib/backend-scaffold-prerequisites.mjs";
 import { createHash } from "node:crypto";
@@ -14,6 +14,7 @@ import { findGitRoot, gitSubmoduleScaffoldViolation, overlayMountViolation } fro
 import { assertLocalDatabaseProfile, localDatabaseConfiguration, scaffoldArchitectureIdentity } from "../../../../scripts/lib/scaffold-local-database.mjs";
 import { validateArchitectureIdentity } from "../../../../scripts/lib/backend-architecture.mjs";
 import { validateJsonSchema } from "../../../../scripts/lib/json-schema.mjs";
+import { finalizeDataAnalysisProfile } from "./data-analysis-profile.mjs";
 
 const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
 const SKILL_ROOT = path.resolve(SCRIPT_DIR, "..");
@@ -146,7 +147,7 @@ function modulePom(contract, module, modules, platform) {
   }
   if (module === "client") dependencies.push(dependency("com.yss.cloud", "yss-component-dto"), dependency(platform.validation_group, platform.validation_artifact));
   if (["server", "service", "core", "client", "repository"].includes(module)) dependencies.push(dependency("org.projectlombok", "lombok", platform.versions.lombok, "provided"));
-  if (module === "feign-client") dependencies.push(own("client"), dependency("org.springframework.cloud", contract.generator_skill === SKILL_ID ? "spring-cloud-starter-openfeign" : "spring-cloud-openfeign-core"));
+  if (module === "feign-client") dependencies.push(own("client"), dependency("org.springframework.cloud", contract.architecture_profile === "mvc-data-analysis-v1" ? "spring-cloud-openfeign-core" : "spring-cloud-starter-openfeign"));
   const plugin = module === "server" ? `<profiles><profile><id>scaffold-local</id><dependencies>${dependency("com.h2database", "h2", null, "runtime")}</dependencies></profile></profiles><build><plugins><plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId></plugin></plugins></build>` : "";
   return `<?xml version="1.0" encoding="UTF-8"?>
 <project xmlns="http://maven.apache.org/POM/4.0.0"><modelVersion>4.0.0</modelVersion><parent><groupId>${xml(contract.maven_coordinates.group_id)}</groupId><artifactId>${xml(contract.project_name)}</artifactId><version>${xml(contract.maven_coordinates.project_version)}</version></parent><artifactId>${xml(contract.project_name)}-${module}</artifactId><dependencies>${dependencies.join("")}</dependencies>${plugin}</project>`;
@@ -160,6 +161,10 @@ export async function validateContract(options, skillId, architectureProfile, pl
   if (contract.schema_version !== 4) fail(`unsupported: 新生成只接受 scaffold contract v4，收到 v${contract.schema_version}`);
   const expectedScaffoldKind = architectureProfile === "mvc-data-analysis-v1" ? "backend-mvc-data-analysis" : "backend-layered-mvc";
   if (contract.kind !== "project-scaffold-contract" || contract.delivery_role !== "backend" || contract.scaffold_kind !== expectedScaffoldKind) fail(`schema v4 合同必须绑定 backend/${expectedScaffoldKind}`);
+  if (architectureProfile === "mvc-data-analysis-v1") {
+    if (contract.init_git !== true) fail("mvc-data-analysis-v1 必须由合同显式要求独立 Git 初始化");
+    if (!contract.context_handoff_ref || !contract.context_handoff_digest) fail("mvc-data-analysis-v1 缺少批准的 CONTEXT handoff");
+  }
   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]));
@@ -176,6 +181,7 @@ export async function validateContract(options, skillId, architectureProfile, pl
   for (const [field, value] of Object.entries(expectedProfiles)) if (contract.profiles?.[field] !== value) fail(`unsupported profile ${field}: ${contract.profiles?.[field]}`);
   assertLocalDatabaseProfile(contract.profiles);
   if (contract.architecture_profile !== architectureProfile) fail(`合同必须显式绑定 ${architectureProfile} Profile`);
+  if (architectureProfile !== "mvc-data-analysis-v1" && contract.init_git !== false) fail("通用 layered-mvc-service 脚手架不得初始化 Git");
   const requested = contract.module_profile?.requested_capabilities;
   if (!Array.isArray(requested)) fail("module_profile.requested_capabilities 必须是数组");
   const resolved = architectureProfile === "mvc-data-analysis-v1" ? ["server", "core", "client", "repository", "adapter", "feign-client"] : orderedModules(requested);
@@ -209,8 +215,7 @@ export async function validateContract(options, skillId, architectureProfile, pl
   assertScaffoldUserDecision(decision);
   validateArchitectureIdentity(scaffoldArchitectureIdentity(contract, sha256(contractText)));
   const designPrerequisites = await validateBackendScaffoldPrerequisites(contract, { contractFile });
-  const platform = skillId === SKILL_ID ? assertContractPlatform(contract, decision, { ...platformOptions, requireVerified: platformOptions.candidate !== true }).profile : platformProfile("spring-boot-2.7-jdk8", undefined, "2.7.18");
-  if (skillId !== SKILL_ID && (contract.platform_configuration || contract.profiles.platform !== "spring-boot-2.7-jdk8" || contract.profiles.validation_namespace !== "javax")) fail("unsupported: data-analysis initializer remains on legacy Boot 2.7/Java 8");
+  const platform = assertContractPlatform(contract, decision, { ...platformOptions, requireVerified: platformOptions.candidate !== true }).profile;
   return { contract, contractText, modules: resolved, designPrerequisites, platform };
 }
 
@@ -227,8 +232,15 @@ async function validateOutputLayout(outputDir, projectName) {
   if (await exists(target)) fail(`unsupported: 目标已存在 ${target}`);
 }
 
-export async function generate(options, { skillId = SKILL_ID, architectureProfile = "layered-mvc-service", finalize, platformOptions = {} } = {}) {
-  if (!((skillId === SKILL_ID && architectureProfile === "layered-mvc-service") || (skillId === "yss-mvc-data-analysis-project-initializer" && architectureProfile === "mvc-data-analysis-v1"))) fail("unsupported MVC generator/Profile pair");
+async function profileFromContract(options) {
+  const text = await readFile(path.resolve(options.contractFile), "utf8").catch(() => fail(`脚手架合同不可读取: ${path.resolve(options.contractFile)}`));
+  try { return JSON.parse(text).architecture_profile; }
+  catch { fail("脚手架合同必须是 JSON 对象"); }
+}
+
+export async function generate(options, { skillId = SKILL_ID, architectureProfile, finalize, platformOptions = {} } = {}) {
+  architectureProfile ??= await profileFromContract(options);
+  if (skillId !== SKILL_ID || !["layered-mvc-service", "mvc-data-analysis-v1"].includes(architectureProfile)) fail("unsupported MVC generator/Profile pair");
   await validateOutputLayout(options.outputDir, options.projectName);
   const { contract, contractText, modules, designPrerequisites, platform } = await validateContract(options, skillId, architectureProfile, platformOptions);
   const outputDir = path.resolve(options.outputDir);
@@ -252,11 +264,13 @@ export async function generate(options, { skillId = SKILL_ID, architectureProfil
     await put(projectRoot, `${serverRoot}/src/test/resources/application-scaffold-test.yml`, localDatabaseConfiguration(`${options.projectName}_test`));
     await put(projectRoot, `${serverRoot}/src/test/java/${packagePath}/${applicationClass}Test.java`, `package ${options.basePackage};\n\nimport org.junit.jupiter.api.Test;\nimport org.springframework.boot.test.context.SpringBootTest;\nimport org.springframework.test.context.ActiveProfiles;\n\n@SpringBootTest\n@ActiveProfiles("scaffold-test")\nclass ${applicationClass}Test {\n    @Test\n    void contextLoads() {\n    }\n}`);
     await put(projectRoot, `${serverRoot}/src/test/java/${packagePath}/architecture/LayeredMvcArchitectureTest.java`, `package ${options.basePackage}.architecture;\n\nimport static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.noClasses;\n\nimport com.tngtech.archunit.core.importer.ImportOption;\nimport com.tngtech.archunit.junit.AnalyzeClasses;\nimport com.tngtech.archunit.junit.ArchTest;\nimport com.tngtech.archunit.lang.ArchRule;\n\n@AnalyzeClasses(packages = "${options.basePackage}", importOptions = ImportOption.DoNotIncludeTests.class)\nclass LayeredMvcArchitectureTest {\n    @ArchTest\n    static final ArchRule repositoryDoesNotDependOnUpperLayers = noClasses().that().resideInAPackage("..repository..").should().dependOnClassesThat().resideInAnyPackage("..service..", "..server..");\n}`);
-    if (skillId === SKILL_ID) await put(projectRoot, `${serverRoot}/src/test/java/${packagePath}/PlatformIntegrationTest.java`, platformSmokeTest(options.basePackage, platform, contract.module_profile.requested_capabilities));
+    await put(projectRoot, `${serverRoot}/src/test/java/${packagePath}/PlatformIntegrationTest.java`, platformSmokeTest(options.basePackage, platform, contract.module_profile.requested_capabilities));
     const wrapper = path.join(REPOSITORY_ROOT, ".agents/skills/yss-ddd-scaffold-generator/assets/wrapper");
     await cp(wrapper, projectRoot, { recursive: true });
     await chmod(path.join(projectRoot, "mvnw"), 0o755);
-    if (finalize) await finalize({ projectRoot, contract, architectureIdentity: scaffoldArchitectureIdentity(contract, sha256(contractText)) });
+    const architectureIdentity = scaffoldArchitectureIdentity(contract, sha256(contractText));
+    const profileFinalize = finalize ?? (architectureProfile === "mvc-data-analysis-v1" ? finalizeDataAnalysisProfile : null);
+    if (profileFinalize) await profileFinalize({ projectRoot, contract, architectureIdentity, options });
     await put(projectRoot, "README.md", `# ${options.projectName}\n\n平台：Spring Boot ${platform.spring_boot_version} / Java ${platform.java_version}。\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)) });
@@ -269,7 +283,7 @@ export async function generate(options, { skillId = SKILL_ID, architectureProfil
       schema_version: 4,
       kind: architectureProfile === "mvc-data-analysis-v1" ? "service-project-initialization" : "backend-scaffold",
       architecture_profile: contract.architecture_profile,
-      architecture_identity: scaffoldArchitectureIdentity(contract, sha256(contractText)),
+      architecture_identity: architectureIdentity,
       contract_id: contract.contract_id,
       contract_version: contract.contract_version,
       scaffold_request_id: contract.scaffold_request_id,

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

@@ -36,7 +36,7 @@ async function fixture(t, { profile = capabilityModules.basic, architectureProfi
     delivery_role: "backend",
     scaffold_kind: architectureProfile === "mvc-data-analysis-v1" ? "backend-mvc-data-analysis" : "backend-layered-mvc",
     repository_scope: "external-repository",
-    init_git: false,
+    init_git: architectureProfile === "mvc-data-analysis-v1",
     contract_id: "scaffold.demo-service.v1",
     contract_version: 1,
     scaffold_request_id: "request.demo-service",
@@ -74,19 +74,17 @@ async function fixture(t, { profile = capabilityModules.basic, architectureProfi
 }
 
 test("数据分析初始化生成 H2 六模块和独立治理信封", async (t) => {
-  const skillId = "yss-mvc-data-analysis-project-initializer";
-  const data = await fixture(t, { architectureProfile: "mvc-data-analysis-v1", skillId, profile: { capabilities: [], modules: ["server", "core", "client", "repository", "adapter", "feign-client"] } });
+  const data = await fixture(t, { architectureProfile: "mvc-data-analysis-v1", profile: { capabilities: [], modules: ["server", "core", "client", "repository", "adapter", "feign-client"] } });
   const context = "---\ncontext_schema_version: 1\n---\n# 业务上下文\n\n## 业务术语\n\n| 术语 | 含义 | 英文标识 | 适用业务责任区 | 避免 / 备注 |\n|---|---|---|---|---|\n";
   await writeFile(path.join(data.root, "context-handoff.md"), context);
   data.contract.context_handoff_ref = "context-handoff.md";
   data.contract.context_handoff_digest = digest(context);
   await writeFile(data.contractFile, JSON.stringify(data.contract));
-  const initializer = path.resolve(path.dirname(script), `../../${skillId}/scripts/generate_project.mjs`);
-  const result = spawnSync(process.execPath, [initializer, ...data.args], { encoding: "utf8" });
+  const result = spawnSync(process.execPath, [path.resolve(path.dirname(script), "../../../../scripts/fixtures/backend-scaffold/generate-candidate.mjs"), 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.architecture_identity.architecture_profile, "mvc-data-analysis-v1");
-  assert.equal(manifest.generator_skill, skillId);
+  assert.equal(manifest.generator_skill, "yss-layered-mvc-scaffold-generator");
   assert.equal(await readFile(path.join(data.project, "CONTEXT.md"), "utf8"), context);
   await stat(path.join(data.project, ".git"));
   await stat(path.join(data.output, "skillUtils/skills-lock.json"));
@@ -95,6 +93,32 @@ test("数据分析初始化生成 H2 六模块和独立治理信封", async (t)
   assert.doesNotMatch(core, /demo-service-client|spring-web|ojdbc|mysql-connector/);
 });
 
+test("历史数据分析初始化入口只返回稳定退役错误", () => {
+  const initializer = path.resolve(path.dirname(script), "../../yss-mvc-data-analysis-project-initializer/scripts/generate_project.mjs");
+  const result = spawnSync(process.execPath, [initializer], { encoding: "utf8" });
+  assert.notEqual(result.status, 0);
+  assert.match(result.stderr, /^skill-deprecated:/);
+});
+
+test("数据分析 Profile 缺少 CONTEXT handoff 或独立 Git 合同时零写入阻断", async (t) => {
+  const profile = { capabilities: [], modules: ["server", "core", "client", "repository", "adapter", "feign-client"] };
+  const missingContext = await fixture(t, { architectureProfile: "mvc-data-analysis-v1", profile });
+  const missingResult = spawnSync(process.execPath, [path.resolve(path.dirname(script), "../../../../scripts/fixtures/backend-scaffold/generate-candidate.mjs"), script, ...missingContext.args], { encoding: "utf8" });
+  assert.notEqual(missingResult.status, 0);
+  assert.match(missingResult.stderr, /CONTEXT handoff/);
+  await assert.rejects(stat(missingContext.project), { code: "ENOENT" });
+
+  const noGit = await fixture(t, { architectureProfile: "mvc-data-analysis-v1", profile });
+  const context = "---\ncontext_schema_version: 1\n---\n# 业务上下文\n";
+  await writeFile(path.join(noGit.root, "context-handoff.md"), context);
+  Object.assign(noGit.contract, { init_git: false, context_handoff_ref: "context-handoff.md", context_handoff_digest: digest(context) });
+  await writeFile(noGit.contractFile, JSON.stringify(noGit.contract));
+  const noGitResult = spawnSync(process.execPath, [path.resolve(path.dirname(script), "../../../../scripts/fixtures/backend-scaffold/generate-candidate.mjs"), script, ...noGit.args], { encoding: "utf8" });
+  assert.notEqual(noGitResult.status, 0);
+  assert.match(noGitResult.stderr, /独立 Git/);
+  await assert.rejects(stat(noGit.project), { code: "ENOENT" });
+});
+
 test("旧数据库和 Mock 参数在写入前被拒绝", async (t) => {
   const data = await fixture(t);
   for (const args of [["--database", "mysql"], ["--with-mock"]]) {

package/template/.pi/skills/yss-layered-mvc-scaffold-generator/tests/scaffold-generator.test.mjs

@@ -0,0 +1,2 @@
+// Keep the task-package entry stable while the canonical implementation test remains beside the generator.
+import "../scripts/scaffold-generator.test.mjs";

package/template/.pi/skills/yss-mvc-data-analysis-project-initializer/SKILL.md

@@ -1,22 +1,12 @@
 ---
 name: yss-mvc-data-analysis-project-initializer
-description: 在生命周期批准的初始化合同下创建独立 Git 管理的数据分析 project-instance；固定 mvc-data-analysis-v1 六模块、Java 8 和本地测试 H2。
+description: 迁移历史数据分析初始化合同到 yss-layered-mvc-scaffold-generator 的 mvc-data-analysis-v1 Profile。
 ---
 
-# 数据分析 MVC 项目初始化
+# 数据分析 MVC 项目初始化（Deprecated）
 
-这是 `work-unit.service-project-initialization` 的执行器，不是通用 MVC 脚手架。通用 MVC 使用 `yss-layered-mvc-scaffold-generator`；DDD 使用 `yss-ddd-scaffold-generator`。历史数据分析初始化入口不提供自动别名，迁移关系只在 `docs/agents/skill-migrations.md` 记录。
+本入口处于 `migration-only`。`mvc-data-analysis-v1` 已由 `yss-layered-mvc-scaffold-generator` 原生持有；本入口不得进入新的 Project Scaffold Contract、Recipe、typed dependency 或任务包。
 
-## 执行合同
+发现旧合同或调用方引用本 ID 时返回 `skill-deprecated`，将合同标记为 `stale`，改由编译器生成绑定 `generator_skill=yss-layered-mvc-scaffold-generator` 与 `architecture_profile=mvc-data-analysis-v1` 的新合同。不得静默替换、继承批准或自动设置 `ready-for-agent`。
 
-- 必须有生命周期批准且当前的 schema v4 scaffold contract，绑定 `architecture_profile=mvc-data-analysis-v1`、本生成器、已批准的架构决策、Technical Design、Data Architecture Decision v1 和真实工程合同批准记录。
-- 固定 server/core/client/repository/adapter/feign-client；core 是薄应用层，规则见 `docs/agents/backend-architecture-profiles.md`。不生成业务接口、SQL、DDL、Mock、生产数据库配置或额外数据源。
-- `verification_database=h2` / `production_database=not-bound`；Java 8 / Boot 2.7 / javax。目标不存在，禁止覆盖、迁移、自动提交和推送。
-- 合同必须包含 `context_handoff_ref`、`context_handoff_digest`：批准交接的完整根 CONTEXT.md（含 schema frontmatter），不得用跨仓路径替代本仓词汇表。初始化只复制已确认内容，不创造业务术语；父项目只保留服务引用和 handoff 证据。
-- `allowed_write_paths` 必须覆盖目标项目及同级 skillUtils。已有 skillUtils 锁不匹配即 blocked，不替换别的项目正在使用的工具包。
-
-## 命令与结果
-
-`node scripts/generate_project.mjs` 使用通用 MVC 生成器相同的批准合同与 Maven 坐标参数（`--output-dir` 是父容器）；无 `--database`、`--with-mock` 或交互选项。
-
-输出独立 project-instance、初始化但未提交的 main Git、生命周期资产、完整锁定 skillUtils、架构身份及 Manifest。使用共享 `run_scaffold_verification.mjs <project> <evidence>` 实跑三条 Wrapper 命令；只在实际成功后报告 empty-scaffold-verified。Profile 仍须独立首切片 fixture 达标才能晋升 supported。
+`scripts/run_scaffold_verification.mjs` 仅为历史已生成项目保留只读恢复验证；它不允许新生成。迁移关系由 `docs/agents/skill-migrations.md` 记录；引用归零后删除本目录，不建立 alias。

package/template/.pi/skills/yss-mvc-data-analysis-project-initializer/scripts/generate_project.mjs

@@ -1,77 +1,18 @@
 #!/usr/bin/env node
-import { createHash } from "node:crypto";
-import { spawnSync } from "node:child_process";
-import { cp, lstat, mkdir, mkdtemp, readFile, rename, rm, writeFile } from "node:fs/promises";
-import path from "node:path";
+import process from "node:process";
 import { fileURLToPath } from "node:url";
-import { generate, parseArgs } from "../../yss-layered-mvc-scaffold-generator/scripts/generate_scaffold.mjs";
 
-const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../..");
-const skillId = "yss-mvc-data-analysis-project-initializer";
-const digest = (value) => `sha256:${createHash("sha256").update(value).digest("hex")}`;
-async function present(target) { try { await lstat(target); return true; } catch (error) { if (error.code === "ENOENT") return false; throw error; } }
-async function put(target, text) { await mkdir(path.dirname(target), { recursive: true }); await writeFile(target, `${text.trimEnd()}\n`); }
-function within(parent, target) { const relative = path.relative(parent, target); return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative)); }
-
-async function sharedTools(outputDir, contract) {
-  const destination = path.join(outputDir, "skillUtils");
-  if (!contract.allowed_write_paths.some((item) => within(path.resolve(outputDir, item), destination))) throw new Error("skillUtils 不在批准写范围内");
-  const lock = await readFile(path.join(root, "skills-lock.json"));
-  if (await present(destination)) {
-    if (!await present(path.join(destination, "skill-utils.yaml")) || !lock.equals(await readFile(path.join(destination, "skills-lock.json")))) throw new Error("已有 skillUtils 不匹配；须独立批准刷新，初始化不会覆盖");
-    return digest(lock);
-  }
-  const staging = await mkdtemp(path.join(outputDir, ".skillUtils.staging-"));
-  try {
-    for (const relative of [".agents/skills", ".codex/skills", ".cursor/skills", ".pi/skills", "scripts", "docs/agents", "docs/process", "AGENTS.md", "skills-lock.json"]) {
-      await mkdir(path.dirname(path.join(staging, relative)), { recursive: true });
-      await cp(path.join(root, relative), path.join(staging, relative), { recursive: true });
-    }
-    await put(path.join(staging, "skill-utils.yaml"), "schema_version: 1\nkind: yss-skill-utils\ncompatibility: skill-utils-v1\ncanonical_root: .agents/skills");
-    await rename(staging, destination);
-  } catch (error) { await rm(staging, { recursive: true, force: true }); throw error; }
-  return digest(lock);
+export function deprecatedInitializerError() {
+  const error = new Error("skill-deprecated: yss-mvc-data-analysis-project-initializer 已由 yss-layered-mvc-scaffold-generator 的 mvc-data-analysis-v1 Profile 替代；旧合同必须标记 stale 并重新编译");
+  error.code = "skill-deprecated";
+  return error;
 }
 
-export async function initialize(options) {
-  // Shared generation validates approval, decision, target and write scope before invoking this callback.
-  return generate(options, { skillId, architectureProfile: "mvc-data-analysis-v1", finalize: async ({ projectRoot, contract, architectureIdentity }) => {
-    if (!contract.context_handoff_ref || !contract.context_handoff_digest) throw new Error("缺少批准的 context_handoff_ref/context_handoff_digest");
-    const handoffPath = path.resolve(path.dirname(path.resolve(options.contractFile)), contract.context_handoff_ref);
-    const context = await readFile(handoffPath);
-    if (digest(context) !== contract.context_handoff_digest || !/^---\r?\ncontext_schema_version: 1\r?\n---/m.test(context.toString())) throw new Error("CONTEXT handoff schema/digest 不匹配");
-    if (spawnSync("git", ["--version"]).status !== 0) throw new Error("Git 不可用");
-    for (const relative of ["docs/agents", "docs/process", "docs/templates", "docs/architecture/templates"]) {
-      await mkdir(path.dirname(path.join(projectRoot, relative)), { recursive: true });
-      await cp(path.join(root, relative), path.join(projectRoot, relative), { recursive: true });
-    }
-    await put(path.join(projectRoot, "CONTEXT.md"), context.toString());
-    const agents = (await readFile(path.join(root, "AGENTS.md"), "utf8"))
-      .replace(/## 4\. `template-source` 模板维护路由[\s\S]*?(?=## 5\.)/, "## 4. 模板维护\n\n本仓为 project-instance；模板维护回上游执行。\n\n")
-      .replaceAll(".agents/skills", "../skillUtils/.agents/skills");
-    await put(path.join(projectRoot, "AGENTS.md"), agents);
-    await put(path.join(projectRoot, "yss-project.yaml"), "schema_version: 1\nrepository_mode: project-instance");
-    await put(path.join(projectRoot, ".artifact-workspace.yaml"), `schema_version: 1\nkind: service\nservice_id: ${options.projectName}`);
-    await cp(path.join(root, "scripts/lib"), path.join(projectRoot, "scripts/lib"), { recursive: true });
-    await cp(path.join(root, "scripts/vendor"), path.join(projectRoot, "scripts/vendor"), { recursive: true });
-    for (const name of ["repository-mode", "implementation-path-policy", "repository-scope-policy", "generate-lifecycle-artifacts", "node-generate-lifecycle-artifacts.mjs", "verify-lifecycle-registry", "node-verify-lifecycle-registry.mjs", "verify-lifecycle-checkpoint", "verify-context-reconciliation", "verify-approval-record", "verify-user-decision", "verify-digital-human-task-package", "verify-yss-dto-openapi-profile", "verify-frontend-implementation-evidence"]) {
-      await cp(path.join(root, "scripts", name), path.join(projectRoot, "scripts", name));
-    }
-    const lockDigest = await sharedTools(path.resolve(options.outputDir), contract);
-    await put(path.join(projectRoot, "skills-lock.json"), JSON.stringify({ version: 1, distribution: { mode: "sibling-directory", skillUtilsDir: "../skillUtils", required: true, compatibility: "skill-utils-v1", lock_digest: lockDigest } }, null, 2));
-    await put(path.join(projectRoot, "docs/process/engineering-baseline.json"), JSON.stringify({ schema_version: 1, architecture_identity: architectureIdentity, platform_profile: contract.profiles.platform, scaffold_completion: "generated" }, null, 2));
-    await put(path.join(projectRoot, "docs/process/implementation-repo-registry.yaml"), JSON.stringify({ schema_version: 1, projects: [{ project_type: "backend", project_name: options.projectName, project_root: ".", git_root: ".", repository_scope: "external-repository", scaffold_status: "initialized", default_branch: "main", architecture_identity: architectureIdentity, allowed_write_paths: ["."], verification_commands: contract.verification_commands, expected_evidence_files: contract.expected_evidence_files, ci: "not-configured", rollback_point: "initial-empty-repository" }] }, null, 2));
-    await put(path.join(projectRoot, "docs/process/service-initialization.json"), JSON.stringify({ work_unit: "work-unit.service-project-initialization", context_handoff_ref: contract.context_handoff_ref, context_handoff_digest: contract.context_handoff_digest, contract_id: contract.contract_id, architecture_identity: architectureIdentity, status: "generated" }, null, 2));
-    await put(path.join(projectRoot, ".gitignore"), "target/\n**/target/\n.idea/\n*.iml\n.env\n.env.*\n.local/");
-    const git = spawnSync("git", ["init", "--initial-branch=main"], { cwd: projectRoot, encoding: "utf8" });
-    if (git.status !== 0) throw new Error(`Git 初始化失败: ${git.stderr}`);
-  } });
+export async function initialize() {
+  throw deprecatedInitializerError();
 }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
-  try {
-    const options = parseArgs(process.argv.slice(2));
-    if (options.help) process.stdout.write("使用批准且绑定技术/数据设计的 MVC schema v4 合同与 Maven 坐标参数；输出独立数据分析项目，无数据库/Mock 选项。\n");
-    else await initialize(options);
-  } catch (error) { process.stderr.write(`数据分析项目初始化失败: ${error.message}\n`); process.exitCode = 1; }
+  process.stderr.write(`${deprecatedInitializerError().message}\n`);
+  process.exitCode = 1;
 }

package/template/.pi/skills/yss-mvc-design/SKILL.md

@@ -1,16 +1,12 @@
 ---
 name: yss-mvc-design
-description: 为已确认 layered-mvc 的 YSS 项目设计分层职责、用例、业务规则、事务和持久化映射，不生成代码。
+description: 迁移历史 yss-mvc-design 引用到 yss-technical-design；不再承接新的 MVC 技术设计。
 ---
 
-# YSS MVC 技术设计
+# YSS MVC 技术设计（Deprecated）
 
-由 `yss-technical-design` 在 `layered-mvc` 分支调用，输入和批准边界由通用技术设计合同持有。既有工程按已登记 Profile 设计，不重选架构。
+本入口处于 `migration-only`。新的 MVC 技术设计统一使用 `yss-technical-design`；本入口不再拥有 capability、Recipe、typed dependency 或设计批准责任，也不得进入新的 Technical Design 或 Slice Contract。
 
-必须说明模块职责与依赖方向、用例流程、业务规则、状态转换、事务边界、失败回滚、幂等与并发、持久化映射、外部集成与公开测试 seam。无状态流转或外部集成时记录有原因的不适用，不硬造对象。
+发现旧合同、任务包或调用方引用本 ID 时，返回 `skill-deprecated`，报告替代入口 `yss-technical-design`，并把旧合同标记为 `stale` 后重新编译。不得静默替换 Skill、继承旧批准或自动设置 `ready-for-agent`。
 
-分层边界消费 `docs/agents/backend-architecture-profiles.md`：Controller 处理 HTTP 边界；service/core 承载用例、规则与事务；Repository 负责持久化；适用时 Adapter 承接外部集成。不得为 MVC 加载 `yss-domain` 或生成 DDD Gateway。
-
-输出 Technical Design Contract 的 `design` 分支，结构见 `references/mvc-design.schema.json`。业务规则和关键场景必须关联具体用例与测试 seam；关键场景覆盖成功和失败。与 DDD 使用同一承接和审查要求，不能因采用 MVC 省略规则、一致性或测试设计。
-
-由通用入口校验整个合同并回交生命周期独立审查。本技能不自行批准、不创建 Ticket、不设置 `ready-for-agent`，不生成 Java、SQL 或生产 API。实现由编译器按批准的架构 Profile 和最小技能闭包路由。
+`references/mvc-design.schema.json` 在退役期保持只读，仅用于与 `yss-technical-design/references/mvc-design.schema.json` 做语义等价检查。新合同不得引用本目录。迁移关系由 `docs/agents/skill-migrations.md` 记录；硬退役后不保留 alias。

package/template/.pi/skills/yss-mvc-design/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
-  display_name: "YSS MVC 技术设计"
-  short_description: "设计 MVC 用例、分层、事务和测试边界"
-  default_prompt: "基于当前批准输入和已确认架构，设计 MVC 用例、分层、事务和测试边界，返回待生命周期审查的结果。"
+  display_name: "YSS MVC 技术设计迁移"
+  short_description: "迁移已退役的 MVC 设计入口"
+  default_prompt: "返回 skill-deprecated，并将历史 yss-mvc-design 引用迁移到 yss-technical-design；不得继承旧批准。"

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

@@ -52,6 +52,6 @@ description: 用于 YSS MyBatis / MyBatis-Plus 组件能力核验、接入决策
 - 使用项目根 `./mvnw ...` 记录实际命令、退出码和时间；H2 只证明本地/测试行为，不证明生产方言。
 - 按 [YSS Skill Execution Result v2](../yss-implementation-contract-compiler/references/yss-skill-execution-result.md) 返回证据、`seam_deferred`、`deviations`、`new_impacts`、`drift` 和 `violation`。
 
-## 新脚手架平台约束
+## 平台与源码门禁
 
-消费批准切片架构身份中的 `platform_configuration`，与工程 Manifest 核对后使用对应 YSS 组件。Boot 2.7 使用 `javax` Web/Validation API；Boot 3.5/4.1 使用 `jakarta`。Boot 4 按 Jackson 3、对应自动配置和 starter 适配；不替换 `javax.sql` 等 Java SE 包。平台不一致、兼容条目缺失或候选未验证时回合同编译器阻断，不在业务实现中升级或替换组件。详见 仓库共享合同 `docs/engineering/backend-platforms.md`。
+接入、修改、代码生成或给出精确类名/配置前，读取 [后端组件平台与源码门禁](../yss-skill-source-index-refresh/references/backend-component-platform-compatibility.md)，从批准的 `platform_configuration.component_platform_line` 选择 `source-index.boot2-java8.md` 或 `source-index.boot3-java17.md`，并以 `--skill yss-mybatis --platform-line <line> --source-root <matching-root>` 运行统一 freshness 校验。平台线与源码根不匹配、组件 tree 不一致、组件子树 dirty、索引缺少平台信号，或 Manifest / 组件 GAV 缺少 verified 兼容证据时返回 `blocked`；不得回退另一代索引，也不在业务实现中升级、降级或替换 YSS 组件。既有工程只读分诊可继续，但不得据此宣称跨 Boot/JDK 兼容。

package/template/.pi/skills/yss-mybatis/references/source-index.boot2-java8.md

@@ -0,0 +1,126 @@
+# yss-mybatis Source Index
+
+Index schema: `backend-component-source-index-v2`
+Platform line: `boot2-java8`
+Generated: 2026-09-18T18:40:26.031Z
+Source commit: `a3be2b2e33dca4545782e2b31894aaa00d0305cd`
+Component worktree: `clean`
+Component tree `yss-microservice-components/yss-component-persistence`: `274d9f4c948d0bd8a58e7f6fb50685d6de740f7b`
+Indexed source root: resolved at refresh time; set `YSS_SOURCE_ROOT_BOOT2_JAVA8` 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.
+
+Paths are relocatable source hints. Exact guidance requires a matching component tree and a clean indexed component subtree; the repository commit is trace metadata and may differ when unrelated components change.
+
+## Component Path Hints
+
+- `yss-microservice-components/yss-component-persistence` (existed when indexed)
+
+## Documentation Files
+
+- `yss-microservice-components/yss-component-persistence/HELP.md`
+- `yss-microservice-components/yss-component-persistence/README.md`
+- `yss-microservice-components/yss-component-persistence/TECHNICAL_DESIGN.md`
+
+Component documentation is a discovery aid. For API signatures, conditions and defaults, prefer the indexed source facts below when documentation differs.
+
+## Maven Modules
+
+- `yss-microservice-components/yss-component-persistence/pom.xml` — GAV `com.yss.cloud:yss-component-persistence:2.0.0-SNAPSHOT`; parent `com.yss.cloud:yss-microservice-components:2.0.0-SNAPSHOT`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/pom.xml` — GAV `com.yss.cloud:yss-component-mybatis-mapper:2.0.0-SNAPSHOT`; parent `com.yss.cloud:yss-component-persistence:2.0.0-SNAPSHOT`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/pom.xml` — GAV `com.yss.cloud:yss-component-mybatis-plus-starter:2.0.0-SNAPSHOT`; parent `com.yss.cloud:yss-component-persistence:2.0.0-SNAPSHOT`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/pom.xml` — GAV `com.yss.cloud:yss-component-mybatis-starter:2.0.0-SNAPSHOT`; parent `com.yss.cloud:yss-component-persistence:2.0.0-SNAPSHOT`
+- `yss-microservice-components/yss-component-persistence/yss-component-persistence-common/pom.xml` — GAV `com.yss.cloud:yss-component-persistence-common:2.0.0-SNAPSHOT`; parent `com.yss.cloud:yss-component-persistence:2.0.0-SNAPSHOT`
+
+## Platform Signals
+
+- Inherited Java signals: `1.8`.
+- Inherited Spring Boot signals: `2.7.18`.
+- Namespace source signals: `javax.*` in 8 main Java files; `jakarta.*` in 0 main Java files.
+- Auto-configuration metadata: 4 `spring.factories`; 1 `AutoConfiguration.imports` files.
+- These are source observations, not compatibility certification. Use the approved `platform_configuration` and verified compatibility evidence before integration or generation.
+
+## Capability Matrix
+
+### Repository abstractions
+
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/support/BaseRepository.java` — `sha256:fd6d72ff759b3438a2cf9d8a2ba24e848a9e68995fc8a100a0a53c65ee3500bb`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/support/BaseRepository.java:20` — `public interface BaseRepository<T, D extends Serializable> extends Mapper<T>, BaseMapper<T, D>, ListMapper<T> {`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/support/BaseRepository.java:66` — `<S extends T> int insert(S entity);`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/support/BaseRepository.java:80` — `<S extends T> int insertSelective(S entity);`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/support/BaseRepository.java:85` — `<S extends T> int insertList(@Param("entityList") List<S> entityList);`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/support/BaseRepository.java:96` — `<S extends T> int updateList(@Param("entityList") List<S> entityList);`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/support/BaseRepository.java:108` — `<S extends T> int updateListSelective(@Param("entityList") List<S> entityList);`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/support/BasePlusRepository.java` — `sha256:3c37b73a2a2dcaa1ad47fee42f8fb4f9b9ecf51b095f8d1fef816cf785fcbb05`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/support/BasePlusRepository.java:12` — `public interface BasePlusRepository<T> extends BaseMapper<T> {`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/support/BasePlusRepository.java:21` — `default Integer insertBatchSomeColumn(List<T> entityList) {`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/support/BasePlusRepository.java:29` — `Integer rows = insertBatchSomeColumnInternal(entityList.subList(fromIndex, toIndex));`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/support/BasePlusRepository.java:43` — `Integer insertBatchSomeColumnInternal(List<T> entityList);`
+
+### Pagination and activation
+
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/aop/EntityQueryAspect.java` — `sha256:617d5eba33a8266bfc485c8e5f39f43519dd16f4d89c9fea7f918d87b00293ba`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/aop/EntityQueryAspect.java:22` — `@Around("( (execution(public * (@org.springframework.stereotype.Repository *).*(..)) || execution(* com.yss..*.gateway.impl.*.*(..))))&& (args(pageQuery)||args(pageQuery,..))")`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/aop/EntityQueryAspect.java:27` — `Page<Object> page = PageHelper.offsetPage(pageQuery.getOffset(), pageQuery.getPageSize());`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/config/PageQueryEntityConfigration.java` — `sha256:c2659f417c10db7fd9e1a91f825d3b6396ae949f7858dbd3b3d9f8917ae42031`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/config/PageQueryEntityConfigration.java:15` — `@ConditionalOnProperty(name = "yss.mybatis.page-helper.enabled", havingValue = "true", matchIfMissing = true)`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/YssMybatisMapperProperties.java` — `sha256:2fda7b769434bd6942f680cdc7ffa71030c0d6a0e448d762e0f19b2d0b33cd85`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/YssMybatisMapperProperties.java:8` — `@ConfigurationProperties(value = "yss.mybatis",ignoreUnknownFields = false)`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/YssMybatisMapperProperties.java:10` — `private String mapperLocation = "mappers/*.xml";`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/YssMybatisMapperProperties.java:11` — `private String mapperScan = "com.yss.cloud.**.mapper";`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/YssMybatisMapperProperties.java:15` — `private Integer batchSize = 200;`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/YssMybatisMapperProperties.java:21` — `private PageHelper pageHelper = new PageHelper();`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/YssMybatisMapperProperties.java:27` — `private MybatisPlusPagination mybatisPlusPagination = new MybatisPlusPagination();`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/YssMybatisMapperProperties.java:36` — `private String dbType;`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/YssMybatisMapperProperties.java:164` — `private Boolean enabled = true;`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/YssMybatisMapperProperties.java:183` — `private Boolean enabled = true;`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/MapperConfiguration.java` — `sha256:79509947c12aeac7b9d6d3e8610edea438240b6613368b84b57b492f06a6b7fc`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/MapperConfiguration.java:47` — `PageInterceptor pageInterceptor = new PageInterceptor();`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/MapperConfiguration.java:264` — `batchSqlInjector.setDbType(dbType);`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/MapperConfiguration.java:265` — `BatchInsertSettings.setBatchSize(yssMybatisMapperProperties.getBatchSize());`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/MapperConfiguration.java:275` — `PaginationInnerInterceptor paginationInnerInterceptor = new PaginationInnerInterceptor(dbType);`
+
+### SQL-level batch insertion
+
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/BatchInsertSettings.java` — `sha256:b1ae05aed5f90a97c36ad29d240b05f9f7c5ee5796f2bc293917e09f7d1c8bd2`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/BatchInsertSettings.java:8` — `private static final int DEFAULT_BATCH_SIZE = 200;`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/BatchInsertSettings.java:9` — `private static volatile int batchSize = DEFAULT_BATCH_SIZE;`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/BatchInsertSettings.java:18` — `public static void setBatchSize(Integer configuredBatchSize) {`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/BatchInsertSettings.java:19` — `batchSize = configuredBatchSize == null || configuredBatchSize <= 0`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/BatchInsertSettings.java:20` — `? DEFAULT_BATCH_SIZE : configuredBatchSize;`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/BatchSqlInjector.java` — `sha256:463dfc881c0c33e27ed2a9157041e8b06d2b2e8bbab0dae1a106f467c31fb4ef`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/BatchSqlInjector.java:16` — `public class BatchSqlInjector extends DefaultSqlInjector {`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/BatchSqlInjector.java:28` — `"insertBatchSomeColumnInternal", dbType, i -> FieldFill.UPDATE != i.getFieldFill()));`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/DialectInsertBatchSomeColumn.java` — `sha256:9cc31f71154fffbc99e4f67816b9026f286f864cfb56a57420185f5e0362dca3`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/DialectInsertBatchSomeColumn.java:24` — `public class DialectInsertBatchSomeColumn extends AbstractMethod {`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/DialectInsertBatchSomeColumn.java:82` — `return dbType == DbType.ORACLE`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/DialectInsertBatchSomeColumn.java:83` — `|| dbType == DbType.ORACLE_12C`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/DialectInsertBatchSomeColumn.java:84` — `|| dbType == DbType.DM;`
+
+### Multi-data-source capability boundary
+
+- `yss-microservice-components/yss-component-persistence/yss-component-persistence-common/src/main/java/com/yss/cloud/mybatis/MultiDataSourceHolder.java` — `sha256:d19370f6a63af76ccb0d05084ef9f0aa71488dcc98b320933ffb8ccf9b9bf896`
+  - `yss-microservice-components/yss-component-persistence/yss-component-persistence-common/src/main/java/com/yss/cloud/mybatis/MultiDataSourceHolder.java:10` — `public class MultiDataSourceHolder {`
+  - `yss-microservice-components/yss-component-persistence/yss-component-persistence-common/src/main/java/com/yss/cloud/mybatis/MultiDataSourceHolder.java:12` — `private Map<String, DataSource> multiDataSource;`
+
+### Auto-configuration registration
+
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/resources/META-INF/spring.factories` — `sha256:592ecdc43e8e11f86c6d1c4b335661f7a05ae8faf4ebb206ec49ef25512d5e46`
+  - `org.springframework.boot.autoconfigure.EnableAutoConfiguration=\`
+  - `io.mybatis.config.spring.SpringEnvAutoConfiguration`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports` — `sha256:d489ab3426d162416a1dfb396dbd3e530f9d5a287c880aab4b021229cc4f06fd`
+  - `io.mybatis.config.spring.SpringEnvAutoConfiguration`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/resources/META-INF/spring.factories` — `sha256:22d8e4510b67fffe9a132b20524c1982c530d80594a3c4e9f839e914068e0a58`
+  - `org.springframework.boot.autoconfigure.EnableAutoConfiguration = com.yss.cloud.mybatis.MybatisPlusConfiguration`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/resources/META-INF/spring.factories` — `sha256:ab6be3903a3af9369ecc56d47dac769511e62bc4a7215ebb7171a920415fa23f`
+  - `org.springframework.boot.autoconfigure.EnableAutoConfiguration = com.yss.cloud.mybatis.MybatisBaseConfiguration,com.yss.cloud.mybatis.MybatisPlusConfiguration`
+- `yss-microservice-components/yss-component-persistence/yss-component-persistence-common/src/main/resources/META-INF/spring.factories` — `sha256:59e4a12550a854ad5a5b253ba3300058edc6646b2b221505aab4fb6bfcad1721`
+  - `org.springframework.boot.autoconfigure.EnableAutoConfiguration = com.yss.cloud.mybatis.MultiDataSourceConfiguration`
+
+## Freshness and Use
+
+- Locate the current source root using `YSS_SOURCE_ROOT_BOOT2_JAVA8`, 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 boot2-java8 --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.