create-yss-spec 3.4.5 → 3.4.7

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

@@ -1,5 +1,6 @@
 import assert from "node:assert/strict";
 import test from "node:test";
+import { readFileSync } from "node:fs";
 import {
   compileImplementationContract,
   digestDocument,
@@ -8,6 +9,7 @@ import {
   validateExecutionResult
 } from "../../../../scripts/lib/implementation-contract-compiler.mjs";
 import { loadSkillRegistry } from "../../../../scripts/lib/skill-registry.mjs";
+import { loadBackendPlatforms, platformBinding } from "../../../../scripts/lib/backend-platform.mjs";
 
 const registry = loadSkillRegistry();
 const compilerContract = loadCompilerContract();
@@ -15,17 +17,18 @@ const fixed = "2026-09-04T00:00:00.000Z";
 const identity = { architecture_family: "domain-driven", architecture_profile: "target-domain-model", generator_skill: "yss-ddd-scaffold-generator", requested_capabilities: [], resolved_modules: ["domain", "application", "infrastructure", "adapter", "bootstrap"], verification_database: "h2", production_database: "not-bound", contract_digest: "a".repeat(64) };
 const architecture = { architecture_identity: identity, architecture_evidence: { engineering_baseline: identity, repository_registration: identity, manifest: identity } };
 const compile = (input) => compileImplementationContract({ registry, compilerContract, compiledAt: fixed, ...architecture, ...input });
+const stableComponentError = code => error => error?.code === code && new RegExp(`^component-capability: ${code}:`).test(error.message);
 
 test("combines narrow recipes once and preserves deterministic output", () => {
   const input = {
-    recipeIds: ["backend.ddd-http-api", "backend.ddd-domain-behavior", "backend.ddd-persistence-mybatis"],
-    conditions: ["mybatis", "conversion", "pojo", "request-validation", "error-mapping"]
+    recipeIds: ["backend.ddd-domain-behavior"],
+    conditions: ["conversion", "pojo"]
   };
   const first = compile(input);
   const second = compile({ ...input, recipeIds: [...input.recipeIds].reverse(), conditions: [...input.conditions].reverse() });
   assert.deepEqual(first, second);
-  assert.deepEqual(first.recipe_ids, ["backend.ddd-domain-behavior", "backend.ddd-persistence-mybatis", "backend.ddd-http-api"]);
-  for (const skill of ["yss-domain", "yss-application", "yss-repository", "yss-mybatis", "yss-web-controller", "yss-dto", "yss-validation", "yss-exception", "mapstruct", "lombok", "alibaba-java-code-style"]) {
+  assert.deepEqual(first.recipe_ids, ["backend.ddd-domain-behavior"]);
+  for (const skill of ["yss-domain", "yss-application", "mapstruct", "lombok", "alibaba-java-code-style"]) {
     assert.equal(first.required_skills.filter((candidate) => candidate === skill).length, 1, `${skill} should appear once`);
   }
 });
@@ -37,17 +40,43 @@ test("does not promote conditional or component dependencies without explicit in
   assert.equal(persistence.required_skills.includes("mapstruct"), false);
   assert.equal(persistence.required_skills.includes("lombok"), false);
 
-  const validation = compile({ requiredCapabilities: ["contract.request-validation"] });
-  assert.deepEqual(validation.required_skills, ["yss-validation"]);
-  assert.equal(validation.required_skills.includes("yss-exception"), false);
-  assert.ok(validation.non_expanding_dependencies.some((edge) => edge.from === "yss-validation" && edge.skill === "yss-exception"));
+  assert.throws(
+    () => compile({ requiredCapabilities: ["contract.request-validation"], architecture_identity: undefined, architecture_evidence: undefined }),
+    /component-platform-binding-required/
+  );
 });
 
 test("loads only explicitly satisfied context-conditional dependencies", () => {
-  const persistence = compile({ requiredCapabilities: ["layer.persistence"], conditions: ["mybatis"] });
-  assert.equal(persistence.required_skills.includes("yss-mybatis"), true);
-  assert.equal(persistence.required_skills.includes("mapstruct"), false);
-  assert.equal(persistence.required_skills.includes("lombok"), false);
+  const application = compile({ requiredCapabilities: ["layer.application"], conditions: ["conversion"] });
+  assert.equal(application.required_skills.includes("mapstruct"), true);
+  assert.equal(application.required_skills.includes("lombok"), false);
+  assert.equal(application.required_skills.includes("yss-mybatis"), false);
+});
+
+test("requires a platform binding for every backend component capability", () => {
+  for (const capability of ["contract.dto-wire", "contract.request-validation", "contract.error-mapping", "framework.mybatis", "component.cache", "component.current-user-context", "component.audit-log", "component.excel-import-export", "component.distributed-id", "component.security-algorithm", "component.gateway-resilience"]) {
+    assert.throws(
+      () => compile({ requiredCapabilities: [capability], architecture_identity: undefined, architecture_evidence: undefined }),
+      stableComponentError("component-platform-binding-required"),
+      capability
+    );
+  }
+});
+
+test("public compiler entry preserves stable component error codes", () => {
+  const catalog = loadBackendPlatforms();
+  const boot2Profile = catalog.profiles.find(item => item.id === "spring-boot-2.7-jdk8");
+  const boot2Entry = catalog.compatibility.find(item => item.profile_id === boot2Profile.id);
+  const boot2 = platformBinding(boot2Profile, boot2Entry);
+  const withPlatform = platform_configuration => {
+    const architecture_identity = { ...identity, platform_configuration };
+    return { architecture_identity, architecture_evidence: { engineering_baseline: architecture_identity, repository_registration: architecture_identity, manifest: architecture_identity } };
+  };
+  assert.throws(() => compile({ requiredCapabilities: ["contract.dto-wire"], ...withPlatform(boot2) }), stableComponentError("component-evidence-missing"));
+  assert.throws(() => compile({ requiredCapabilities: ["component.cache"], ...withPlatform(boot2) }), stableComponentError("component-platform-generation-mismatch"));
+  const boot3Profile = catalog.profiles.find(item => item.id === "spring-boot-3.5-jdk17");
+  const boot3 = { ...boot2, profile_id: boot3Profile.id, spring_boot_version: boot3Profile.spring_boot_version, java_version: boot3Profile.java_version, compatibility_id: "unavailable-boot3-components" };
+  assert.throws(() => compile({ requiredCapabilities: ["contract.dto-wire"], ...withPlatform(boot3) }), stableComponentError("component-unavailable-for-platform"));
 });
 
 test("rejects recipes that reference skills and context-required cycles", () => {
@@ -62,12 +91,12 @@ test("rejects recipes that reference skills and context-required cycles", () =>
 
 test("rejects removed ids and schema v1 without compatibility", () => {
   assert.throws(() => compile({ recipeIds: ["yss-router"] }), /已移除 skill id/);
-  assert.throws(() => compileImplementationContract({ registry: { ...registry, schema_version: 1 }, compilerContract, requiredCapabilities: ["layer.domain"] }), /schema v1 已停止支持/);
+  assert.throws(() => compileImplementationContract({ registry: { ...registry, schema_version: 1 }, compilerContract, requiredCapabilities: ["layer.domain"] }), /schema v1\/v2 已停止支持/);
   assert.throws(() => compileImplementationContract({ registry, compilerContract: { ...compilerContract, schema_version: 1 }, requiredCapabilities: ["layer.domain"] }), /schema v1 已停止支持/);
 });
 
 test("marks digest drift stale and validates v2 execution evidence", () => {
-  const resolution = compile({ requiredCapabilities: ["contract.request-validation"], architecture_identity: undefined, architecture_evidence: undefined });
+  const resolution = compile({ requiredCapabilities: ["quality.java-code-style"], architecture_identity: undefined, architecture_evidence: undefined });
   const contract = { schema_version: 2, contract_id: "slice-1", contract_version: 1, resolution };
   assert.deepEqual(evaluateContractFreshness(contract, { registry, compilerContract }), { freshness: "current", reasons: [] });
   const changedRegistry = structuredClone(registry);
@@ -89,3 +118,20 @@ test("marks digest drift stale and validates v2 execution evidence", () => {
   assert.deepEqual(validateExecutionResult(result, contract, { registry, compilerContract }), { status: "accepted", blockers: [] });
   assert.deepEqual(validateExecutionResult({ ...result, new_impacts: [{ impact_type: "cache" }] }, contract, { registry, compilerContract }), { status: "blocked", blockers: ["new-impacts"] });
 });
+
+test("marks legacy component contracts without component bindings stale", () => {
+  const resolution = compile({ requiredCapabilities: ["quality.java-code-style"], architecture_identity: undefined, architecture_evidence: undefined });
+  resolution.required_capabilities = ["contract.dto-wire"];
+  resolution.required_skills = ["yss-dto"];
+  const contract = { schema_version: 2, contract_id: "legacy-component", contract_version: 1, resolution };
+  assert.ok(evaluateContractFreshness(contract, { registry, compilerContract }).reasons.includes("component-binding-drift"));
+});
+
+test("current lifecycle scaffold contract delegates platform facts to the catalog", () => {
+  const source = readFileSync(new URL("../../yss-product-lifecycle/references/orchestration-contract.yaml", import.meta.url), "utf8");
+  const current = source.slice(source.indexOf("backend_scaffold:"), source.indexOf("  required_inputs:", source.indexOf("backend_scaffold:")));
+  assert.match(current, /platform_binding: platform_configuration-v2/);
+  assert.doesNotMatch(current, /yss_components_version:\s*2\.0\.0-SNAPSHOT/);
+  assert.doesNotMatch(current, /spring-boot-3/);
+  assert.doesNotMatch(current, /validation_namespace:\s*javax/);
+});

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

@@ -1,11 +1,11 @@
 ---
 name: yss-layered-mvc-scaffold-generator
-description: 用于在生命周期已批准的脚手架合同下生成按批准 Spring Boot / Java 平台生成通用 YSS 分层 MVC 后端工程；核心模块为 server、service、repository，并按能力确定性增加 adapter、client、feign-client。
+description: 在生命周期已批准的脚手架合同下生成通用 YSS 分层 MVC 后端，或按 mvc-data-analysis-v1 初始化六模块数据分析 project-instance。
 ---
 
 # YSS Layered MVC Scaffold Generator
 
-本 skill 只为已登记的全新 backend project 生成机械工程骨架，不创建 `project-instance`、不初始化 Git、不生成业务 Controller、DTO、查询、状态机或 Mock 数据。
+本 skill 只为已登记的全新 backend project 生成机械工程骨架，不生成业务 Controller、DTO、查询、状态机或 Mock 数据。普通 `layered-mvc-service` 不创建 `project-instance` 或初始化 Git；`mvc-data-analysis-v1` 按批准合同创建独立 project-instance、同级锁定 `skillUtils` 和未提交的 main Git。
 
 ## 进入条件
 
@@ -31,12 +31,13 @@ description: 用于在生命周期已批准的脚手架合同下生成按批准
 
 ## 架构与 Profile
 
-- 固定核心模块：`server`、`service`、`repository`。
+- `layered-mvc-service` 固定核心模块：`server`、`service`、`repository`。
 - `external-integration` 增加 `adapter`。
 - `published-client` 增加 `client`。
 - `feign-client` 增加 `client`、`feign-client`。
 - 平台来自批准的 `platform_configuration`；保留 YSS BOM、MyBatis-Plus，不固定单一 Boot/Java/Validation 命名空间。
-- 固定 architecture_profile=layered-mvc-service；verification_database=h2、production_database=not-bound。测试使用 H2，本地运行显式启用 scaffold-local；不引入外部驱动/数据源。
+- `mvc-data-analysis-v1` 固定 `server/core/client/repository/adapter/feign-client` 六模块，要求 `context_handoff_ref`、摘要和 `init_git=true`，复制批准的根 `CONTEXT.md`、治理资产和锁定工具包；不得从交接内容创造术语。该 Profile 仍绑定平台目录与构件证据，不再通过历史初始化器绕过平台门禁。
+- 两个 Profile 均固定 verification_database=h2、production_database=not-bound。测试使用 H2，本地运行显式启用 scaffold-local；不引入外部驱动/数据源。
 
 能力解析规则、模块职责和依赖方向见 [architecture.md](references/architecture.md)。生成器必须同时校验 `requested_capabilities` 与 `resolved_modules`，不得自行补猜模块。
 
@@ -69,7 +70,7 @@ node scripts/generate_and_verify_scaffold.mjs \
 ## 硬约束
 
 - 新生成只接受包含 API Contract Decision 的统一 schema v4；缺 API 字段的预发布 v4 不得静默接受。验证器可只读检查历史 Manifest v3，恢复必须另行完成所有权审计、技术/数据/API 设计补齐与当前批准。历史 v2/v3 均不用于新生成。
-- `architecture_family` 必须为 `layered-mvc`，`generator_skill` 必须为本 skill。
+- `architecture_family` 必须为 `layered-mvc`，`generator_skill` 必须为本 skill。旧数据分析初始化合同必须标记 `stale` 并按 `mvc-data-analysis-v1` Profile 重编译，不自动替换或继承批准。
 - 目标存在、`--force`、旧项目迁移、模板升级均为 `unsupported`。
 - Harness 内只允许以 `apps/backend/` 为输出父容器；外部实现仓库使用已登记真实路径。
 - 不生成业务示例。健康检查、上下文加载测试和架构测试只能验证机械工程能力，不定义用户可见 API。

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

@@ -1,4 +1,4 @@
 interface:
   display_name: "YSS Layered MVC Scaffold Generator"
-  short_description: "Generate an approved YSS layered MVC backend skeleton."
-  default_prompt: "Use $yss-layered-mvc-scaffold-generator only after a user-confirmed architecture decision and a lifecycle-approved schema v4 scaffold contract with approved technical and data design prerequisites."
+  short_description: "Generate approved MVC service or data-analysis profiles."
+  default_prompt: "Use $yss-layered-mvc-scaffold-generator only after a user-confirmed architecture decision and a lifecycle-approved schema v4 contract; generate layered-mvc-service or the native mvc-data-analysis-v1 project profile exactly as bound."

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

@@ -11,6 +11,8 @@
 
 合同保存 `requested_capabilities`、`resolved_modules` 和 `resolution_version: 1`。模块按 `server`、`service`、`repository`、`adapter`、`client`、`feign-client` 的稳定顺序生成。
 
+`mvc-data-analysis-v1` 是本生成器的固定 Profile，不使用上述可选闭包：模块严格为 `server`、`core`、`client`、`repository`、`adapter`、`feign-client`。`core` 承载薄应用编排，不能依赖 `client`、Spring Web 或生产数据库驱动；CONTEXT handoff、project-instance 治理信封、同级 `skillUtils` 与独立 Git 必须在最终 rename 前完成。
+
 ## 职责和依赖
 
 | 模块 | 职责 | 允许依赖 |

package/template/.cursor/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/.cursor/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/.cursor/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,25 @@ test("数据分析初始化生成 H2 六模块和独立治理信封", async (t)
   assert.doesNotMatch(core, /demo-service-client|spring-web|ojdbc|mysql-connector/);
 });
 
+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/.cursor/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/.cursor/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/.cursor/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.