create-yss-spec 3.2.0 → 3.3.0

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

@@ -1,24 +1,394 @@
 #!/usr/bin/env node
+import { createHash } from "node:crypto";
 import { execFileSync } from "node:child_process";
-import { access, mkdir, readdir, writeFile } from "node:fs/promises";
+import { access, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
-const BACKEND = {"yss-cache":["yss-microservice-components/yss-component-cache-parent"],"yss-mybatis":["yss-microservice-components/yss-component-persistence"],"yss-dto":["yss-microservice-components/yss-component-dto"],"yss-audit-log":["yss-microservice-components/yss-component-audit-log"],"yss-excel-mvc":["yss-microservice-components/yss-component-excel-mvc","yss-microservice-components/yss-component-excel-starter"],"yss-distributed-id":["yss-microservice-components/yss-component-distributed-id","yss-microservice-components/yss-component-leaf"],"yss-resilience4j":["yss-microservice-components/yss-component-resilience4j-starter"],"yss-validation":["yss-microservice-components/yss-component-validation-engine-parent","yss-microservice-components/yss-component-validation-jsr303"],"yss-security-algorithm":["yss-microservice-components/yss-component-security-algorithm"],"yss-userinfo":["yss-microservice-components/yss-component-userinfo-starter"],"yss-exception":["yss-microservice-components/yss-component-exception"]};
-const FRONTEND={"yss-ui":["components","hooks","skills"],"yss-components":["components"],"yss-hook":["hooks"],"yss-ui-business-page-generation":["components","hooks","skills"],"yss-use-table-height":["hooks"],"yss-use-tree-height":["hooks"]};
-const URLS={components:"http://192.168.164.27:3200/components",hooks:"http://192.168.164.27:3200/hooks",skills:"http://192.168.164.27:3200/skills"};
-const KEYS=["Audit","Cache","Clear","Command","Configuration","Controller","DTO","Data","Enable","Excel","Handler","Interceptor","Jdbc","Mapper","Mybatis","Page","Properties","Query","Repository","Request","Response","Result","Update","Aspect","Leaf","Id","Dir","Dic","Dictionary","File","Upload","Log","Message","Mail","Liquibase","Circuit","Breaker","Sql","Tpl","Tag","Task","Flow","Report","Validation","Validator","Security","Crypto","User","Variable","Quality","Search","Similarity","Scheduler","Runner","Duck","Dynamic","Factory","Client","Feign","Gateway","Convertor","Adapter","Advice","Bridge","Route","Uploader","Sftp","Minio","Parser","Express","Rule","Template","Generator","Importer","Engine","Event","Submitter","Executor","Context","Status","Type","State"];
-const DOCS=new Set(["README.md","readme.md","HELP.md","TECHNICAL_DESIGN.md"]);
-const exists=async p=>{try{await access(p);return true}catch{return false}};
-async function walk(root){if(!await exists(root))return[];const out=[];for(const item of await readdir(root,{withFileTypes:true})){const p=path.join(root,item.name);if(item.isDirectory())out.push(...await walk(p));else if(item.isFile())out.push(p)}return out}
-const relative=(root,p)=>{const value=path.relative(root,p);return value&&!value.startsWith("..")?value:p};
-function state(root){try{const run=args=>execFileSync("git",["-C",root,...args],{encoding:"utf8",stdio:["ignore","pipe","ignore"]}).trim();return[run(["rev-parse","HEAD"]),run(["status","--porcelain"])?"dirty":"clean"]}catch{return["unavailable","unknown"]}}
-async function sourceRoot(){if(process.env.YSS_SOURCE_ROOT){const root=path.resolve(process.env.YSS_SOURCE_ROOT);if(await exists(path.join(root,"yss-microservice-components")))return root;throw new Error(`YSS_SOURCE_ROOT must point to the repository root containing \`yss-microservice-components\`: ${root}`)}const home=os.homedir(),candidates=[process.cwd(),...ancestors(process.cwd()),path.join(home,"Documents/yss-project/yss-cloud-microservice"),path.join(home,"Documents/yss-project"),path.join(home,"Projects/yss-cloud-microservice"),path.join(home,"Projects")];for(const base of [path.join(home,"Projects"),path.join(home,"Documents"),path.join(home,"Documents/yss-project")])if(await exists(base))for(const entry of await readdir(base,{withFileTypes:true}))if(entry.isDirectory())candidates.push(path.join(base,entry.name));for(const root of candidates)if(await exists(path.join(root,"yss-microservice-components")))return path.resolve(root);throw new Error("Could not find a YSS source repository containing `yss-microservice-components`. Export YSS_SOURCE_ROOT=/absolute/path/to/yss-cloud-microservice and rerun.")}
-function ancestors(start){const out=[];let current=path.resolve(start);while(path.dirname(current)!==current){current=path.dirname(current);out.push(current)}return out}
-async function files(bases){const out={docs:[],poms:[],java:[]};for(const base of bases)for(const p of await walk(base)){if(DOCS.has(path.basename(p)))out.docs.push(p);else if(path.basename(p)==="pom.xml")out.poms.push(p);else if(p.endsWith(".java")&&p.includes(`${path.sep}src${path.sep}main${path.sep}java${path.sep}`))out.java.push(p)}for(const a of Object.values(out))a.sort();return out}
-export async function refresh({skillsRoot,source,now=new Date().toISOString(),frontend=true}){const [commit,worktree]=state(source);for(const [skill,parts]of Object.entries(BACKEND)){const bases=parts.map(item=>path.join(source,item));const found=await files(bases);const java=found.java.filter(p=>KEYS.some(key=>path.basename(p,".java").includes(key))).slice(0,120);const list=(items,map,empty)=>items.length?items.map(map):[empty];const baseHints=await Promise.all(bases.map(async p=>`- \`${relative(source,p)}\` (${await exists(p)?"existed":"missing"} when indexed)`));const lines=[`# ${skill} Source Index`,``,`Generated: ${now}`,`Source commit: \`${commit}\``,`Source worktree: \`${worktree}\``,`Indexed source root: resolved at refresh time; set \`YSS_SOURCE_ROOT\` 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 below are source path hints captured at refresh time. If they do not exist in the current workspace, locate sources using \`YSS_SOURCE_ROOT\`, CodeGraph, package/class names, Maven artifact names, or repository search before assuming the source is unavailable.`,``,`## Component Path Hints`,``,...baseHints,``,`## Documentation Files`,``,...list(found.docs,p=>`- \`${relative(source,p)}\``,"- No component documentation files found."),``,`## Maven Modules`,``,...list(found.poms,p=>`- \`${relative(source,path.dirname(p))}\``,"- No Maven modules found."),``,`## Key Java Entry Points`,``,...list(java,p=>`- \`${relative(source,p)}\``,"- No key Java entry points matched the configured name patterns."),``,`## Recommended Next Reads`,``,`- Start with the documentation files above when learning component usage.`,`- Search the key Java entry points for annotations, auto configuration, properties, aspects, interceptors, handlers, and result objects before changing application code.`,`- Prefer existing component extension points over rewriting framework logic in business modules.`,``];const target=path.join(skillsRoot,skill,"references","source-index.md");await mkdir(path.dirname(target),{recursive:true});await writeFile(target,lines.join("\n"),"utf8")}
- if(frontend)for(const[skill,keys]of Object.entries(FRONTEND)){if(!await exists(path.join(skillsRoot,skill)))continue;const target=path.join(skillsRoot,skill,"references","frontend-docs.md");await mkdir(path.dirname(target),{recursive:true});await writeFile(target,[`# ${skill} Frontend Documentation`,``,`Generated: ${now}`,``,`Use these YSS UI documentation entry points as authoritative references when local repo examples are insufficient.`,``,...keys.map(key=>`- ${key}: ${URLS[key]}`),``,`When documentation and local code differ, inspect the current project code before editing and prefer established local usage.`,``].join("\n"),"utf8")}
- return{backend:Object.keys(BACKEND).length,frontend:frontend?Object.keys(FRONTEND).length:0}}
-async function main(){try{const script=path.dirname(fileURLToPath(import.meta.url));const result=await refresh({skillsRoot:path.resolve(process.env.YSS_SKILLS_ROOT||path.join(script,"../..")),source:await sourceRoot(),frontend:!["0","false","no"].includes((process.env.YSS_REFRESH_FRONTEND||"true").toLowerCase())});console.log(`Updated ${result.backend} backend indexes and ${result.frontend} frontend doc references.`)}catch(error){console.error(error.message);process.exitCode=1}}
-if(process.argv[1]===fileURLToPath(import.meta.url))await main();
+const BACKEND = {
+  "yss-cache": ["yss-microservice-components/yss-component-cache-parent"],
+  "yss-mybatis": ["yss-microservice-components/yss-component-persistence"],
+  "yss-dto": ["yss-microservice-components/yss-component-dto"],
+  "yss-audit-log": ["yss-microservice-components/yss-component-audit-log"],
+  "yss-excel-mvc": [
+    "yss-microservice-components/yss-component-excel-mvc",
+    "yss-microservice-components/yss-component-excel-starter",
+  ],
+  "yss-distributed-id": [
+    "yss-microservice-components/yss-component-distributed-id",
+    "yss-microservice-components/yss-component-leaf",
+  ],
+  "yss-resilience4j": ["yss-microservice-components/yss-component-resilience4j-starter"],
+  "yss-validation": [
+    "yss-microservice-components/yss-component-validation-engine-parent",
+    "yss-microservice-components/yss-component-validation-jsr303",
+  ],
+  "yss-security-algorithm": ["yss-microservice-components/yss-component-security-algorithm"],
+  "yss-userinfo": ["yss-microservice-components/yss-component-userinfo-starter"],
+  "yss-exception": ["yss-microservice-components/yss-component-exception"],
+};
+
+const FRONTEND = {
+  "yss-ui": ["components", "hooks", "skills"],
+  "yss-components": ["components"],
+  "yss-hook": ["hooks"],
+  "yss-ui-business-page-generation": ["components", "hooks", "skills"],
+  "yss-use-table-height": ["hooks"],
+  "yss-use-tree-height": ["hooks"],
+};
+
+const URLS = {
+  components: "http://192.168.164.27:3200/components",
+  hooks: "http://192.168.164.27:3200/hooks",
+  skills: "http://192.168.164.27:3200/skills",
+};
+
+const KEYS = [
+  "Audit", "Cache", "Clear", "Command", "Configuration", "Controller", "DTO", "Data", "Enable", "Excel",
+  "Handler", "Interceptor", "Jdbc", "Mapper", "Mybatis", "Page", "Properties", "Query", "Repository", "Request",
+  "Response", "Result", "Update", "Aspect", "Leaf", "Id", "Dir", "Dic", "Dictionary", "File", "Upload", "Log",
+  "Message", "Mail", "Liquibase", "Circuit", "Breaker", "Sql", "Tpl", "Tag", "Task", "Flow", "Report",
+  "Validation", "Validator", "Security", "Crypto", "User", "Variable", "Quality", "Search", "Similarity",
+  "Scheduler", "Runner", "Duck", "Dynamic", "Factory", "Client", "Feign", "Gateway", "Convertor", "Adapter",
+  "Advice", "Bridge", "Route", "Uploader", "Sftp", "Minio", "Parser", "Express", "Rule", "Template", "Generator",
+  "Importer", "Engine", "Event", "Submitter", "Executor", "Context", "Status", "Type", "State",
+];
+
+const DOCS = new Set(["README.md", "readme.md", "HELP.md", "TECHNICAL_DESIGN.md"]);
+const SKIPPED_DIRECTORIES = new Set([".git", "node_modules", "target", "build", "out", "${project.build.directory}"]);
+
+const MYBATIS_CAPABILITIES = [
+  {
+    title: "Repository abstractions",
+    sources: [
+      {
+        suffix: "/support/BaseRepository.java",
+        patterns: [/public interface BaseRepository/, /int (insert|insertSelective|insertList|updateList|updateListSelective)\(/],
+      },
+      {
+        suffix: "/support/BasePlusRepository.java",
+        patterns: [/public interface BasePlusRepository/, /insertBatchSomeColumn/],
+      },
+    ],
+  },
+  {
+    title: "Pagination and activation",
+    sources: [
+      { suffix: "/aop/EntityQueryAspect.java", patterns: [/@Around\(/, /PageHelper\.offsetPage/] },
+      { suffix: "/config/PageQueryEntityConfigration.java", patterns: [/@ConditionalOnProperty/] },
+      {
+        suffix: "/YssMybatisMapperProperties.java",
+        patterns: [
+          /@ConfigurationProperties/,
+          /private (String mapperLocation|String mapperScan|Integer batchSize|String dbType|PageHelper pageHelper|MybatisPlusPagination mybatisPlusPagination)/,
+          /public static class (PageHelper|MybatisPlusPagination)/,
+          /private Boolean enabled/,
+        ],
+      },
+      {
+        suffix: "/config/MapperConfiguration.java",
+        patterns: [/new PageInterceptor\(/, /new PaginationInnerInterceptor\(/, /setBatchSize\(/, /setDbType\(/],
+      },
+    ],
+  },
+  {
+    title: "SQL-level batch insertion",
+    sources: [
+      { suffix: "/config/BatchInsertSettings.java", patterns: [/DEFAULT_BATCH_SIZE/, /configuredBatchSize/] },
+      { suffix: "/config/BatchSqlInjector.java", patterns: [/public class BatchSqlInjector/, /insertBatchSomeColumnInternal/, /FieldFill\.UPDATE/] },
+      { suffix: "/config/DialectInsertBatchSomeColumn.java", patterns: [/public class DialectInsertBatchSomeColumn/, /DbType\.(ORACLE|ORACLE_12C|DM)/] },
+    ],
+  },
+  {
+    title: "Multi-data-source capability boundary",
+    sources: [
+      {
+        suffix: "/MultiDataSourceHolder.java",
+        patterns: [/public class MultiDataSourceHolder/, /Map<String, DataSource>/, /getMultiDataSource\(/],
+      },
+    ],
+  },
+];
+
+const exists = async (target) => {
+  try {
+    await access(target);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+async function walk(root) {
+  if (!await exists(root)) return [];
+  const output = [];
+  for (const item of await readdir(root, { withFileTypes: true })) {
+    const target = path.join(root, item.name);
+    if (item.isDirectory() && !SKIPPED_DIRECTORIES.has(item.name)) output.push(...await walk(target));
+    else if (item.isFile()) output.push(target);
+  }
+  return output;
+}
+
+function relative(root, target) {
+  const value = path.relative(root, target).replaceAll(path.sep, "/");
+  return value && !value.startsWith("..") ? value : target;
+}
+
+function runGit(root, args) {
+  return execFileSync("git", ["-C", root, ...args], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"],
+  }).trim();
+}
+
+export function sourceState(root, componentPaths) {
+  try {
+    const commit = runGit(root, ["rev-parse", "HEAD"]);
+    const componentWorktree = runGit(root, ["status", "--porcelain", "--", ...componentPaths]) ? "dirty" : "clean";
+    const componentTrees = componentPaths.map((componentPath) => {
+      let tree = "missing";
+      try {
+        tree = runGit(root, ["rev-parse", `HEAD:${componentPath}`]);
+      } catch {
+        // The path can be newly added or absent in the indexed commit.
+      }
+      return { path: componentPath, tree };
+    });
+    return { commit, componentWorktree, componentTrees };
+  } catch {
+    return {
+      commit: "unavailable",
+      componentWorktree: "unknown",
+      componentTrees: componentPaths.map((componentPath) => ({ path: componentPath, tree: "unavailable" })),
+    };
+  }
+}
+
+async function sourceRoot() {
+  if (process.env.YSS_SOURCE_ROOT) {
+    const root = path.resolve(process.env.YSS_SOURCE_ROOT);
+    if (await exists(path.join(root, "yss-microservice-components"))) return root;
+    throw new Error(`YSS_SOURCE_ROOT must point to the repository root containing \`yss-microservice-components\`: ${root}`);
+  }
+
+  const home = os.homedir();
+  const candidates = [
+    process.cwd(),
+    ...ancestors(process.cwd()),
+    path.join(home, "Documents/yss-project/yss-cloud-microservice"),
+    path.join(home, "Documents/yss-project"),
+    path.join(home, "Projects/yss-cloud-microservice"),
+    path.join(home, "Projects"),
+  ];
+  for (const base of [path.join(home, "Projects"), path.join(home, "Documents"), path.join(home, "Documents/yss-project")]) {
+    if (!await exists(base)) continue;
+    for (const entry of await readdir(base, { withFileTypes: true })) {
+      if (entry.isDirectory()) candidates.push(path.join(base, entry.name));
+    }
+  }
+  for (const root of candidates) {
+    if (await exists(path.join(root, "yss-microservice-components"))) return path.resolve(root);
+  }
+  throw new Error("Could not find a YSS source repository containing `yss-microservice-components`. Export YSS_SOURCE_ROOT=/absolute/path/to/yss-cloud-microservice and rerun.");
+}
+
+function ancestors(start) {
+  const output = [];
+  let current = path.resolve(start);
+  while (path.dirname(current) !== current) {
+    current = path.dirname(current);
+    output.push(current);
+  }
+  return output;
+}
+
+async function files(bases) {
+  const output = { docs: [], poms: [], java: [], metadata: [] };
+  for (const base of bases) {
+    for (const target of await walk(base)) {
+      if (DOCS.has(path.basename(target))) output.docs.push(target);
+      else if (path.basename(target) === "pom.xml") output.poms.push(target);
+      else if (target.endsWith(".java") && target.includes(`${path.sep}src${path.sep}main${path.sep}java${path.sep}`)) output.java.push(target);
+      else if (path.basename(target) === "spring.factories") output.metadata.push(target);
+    }
+  }
+  for (const items of Object.values(output)) items.sort();
+  return output;
+}
+
+async function sha256(target) {
+  return createHash("sha256").update(await readFile(target)).digest("hex");
+}
+
+function list(items, render, empty) {
+  return items.length ? items.map(render) : [empty];
+}
+
+async function genericJavaEntries(source, javaFiles) {
+  const selected = javaFiles
+    .filter((target) => KEYS.some((key) => path.basename(target, ".java").includes(key)))
+    .slice(0, 120);
+  const output = [];
+  for (const target of selected) {
+    output.push(`- \`${relative(source, target)}\` — \`sha256:${await sha256(target)}\``);
+  }
+  return output.length ? output : ["- No key Java entry points matched the configured name patterns."];
+}
+
+function matchingLines(contents, patterns) {
+  return contents
+    .split(/\r?\n/)
+    .map((line, index) => ({ line: index + 1, text: line.trim().replace(/\s+/g, " ") }))
+    .filter(({ text }) => text && patterns.some((pattern) => pattern.test(text)))
+    .slice(0, 14);
+}
+
+async function mybatisCapabilityMatrix(source, javaFiles, metadataFiles) {
+  const output = ["## Capability Matrix", ""];
+  for (const capability of MYBATIS_CAPABILITIES) {
+    output.push(`### ${capability.title}`, "");
+    for (const expected of capability.sources) {
+      const target = javaFiles.find((candidate) => relative(source, candidate).endsWith(expected.suffix));
+      if (!target) {
+        output.push(`- \`${path.basename(expected.suffix)}\` — source not found.`);
+        continue;
+      }
+      const sourcePath = relative(source, target);
+      output.push(`- \`${sourcePath}\` — \`sha256:${await sha256(target)}\``);
+      const lines = matchingLines(await readFile(target, "utf8"), expected.patterns);
+      if (!lines.length) output.push("  - No configured public fact matched; refresh rules may need maintenance.");
+      else for (const fact of lines) output.push(`  - \`${sourcePath}:${fact.line}\` — \`${fact.text.replaceAll("`", "'")}\``);
+    }
+    output.push("");
+  }
+
+  output.push("### Auto-configuration registration", "");
+  for (const target of metadataFiles) {
+    const sourcePath = relative(source, target);
+    output.push(`- \`${sourcePath}\` — \`sha256:${await sha256(target)}\``);
+    const registrations = (await readFile(target, "utf8"))
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter((line) => line && !line.startsWith("#"));
+    for (const registration of registrations.slice(0, 12)) output.push(`  - \`${registration.replaceAll("`", "'")}\``);
+  }
+  if (!metadataFiles.length) output.push("- No `spring.factories` registration found.");
+  output.push("");
+  return output;
+}
+
+async function backendIndex({ skill, parts, source, found, now, stateResolver }) {
+  const currentState = stateResolver(source, parts);
+  const bases = parts.map((item) => path.join(source, item));
+  const baseHints = await Promise.all(bases.map(async (target) =>
+    `- \`${relative(source, target)}\` (${await exists(target) ? "existed" : "missing"} when indexed)`,
+  ));
+  const treeLines = currentState.componentTrees.map(({ path: componentPath, tree }) =>
+    `Component tree \`${componentPath}\`: \`${tree}\``,
+  );
+  const lines = [
+    `# ${skill} Source Index`,
+    "",
+    `Generated: ${now}`,
+    `Source commit: \`${currentState.commit}\``,
+    `Component worktree: \`${currentState.componentWorktree}\``,
+    ...treeLines,
+    "Indexed source root: resolved at refresh time; set `YSS_SOURCE_ROOT` to reproduce or refresh.",
+    "",
+    "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",
+    "",
+    ...baseHints,
+    "",
+    "## Documentation Files",
+    "",
+    ...list(found.docs, (target) => `- \`${relative(source, target)}\``, "- No component documentation files found."),
+    "",
+    "Component documentation is a discovery aid. For API signatures, conditions and defaults, prefer the indexed source facts below when documentation differs.",
+    "",
+    "## Maven Modules",
+    "",
+    ...list(found.poms, (target) => `- \`${relative(source, path.dirname(target))}\``, "- No Maven modules found."),
+    "",
+  ];
+
+  if (skill === "yss-mybatis") lines.push(...await mybatisCapabilityMatrix(source, found.java, found.metadata));
+  else lines.push("## Key Java Entry Points", "", ...await genericJavaEntries(source, found.java), "");
+
+  lines.push(
+    "## Freshness and Use",
+    "",
+    "- Locate the current source root using `YSS_SOURCE_ROOT`, 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.",
+    "- 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.",
+    "",
+  );
+  return lines.join("\n");
+}
+
+export async function refresh({
+  skillsRoot,
+  source,
+  now = new Date().toISOString(),
+  frontend = true,
+  backendSkills = Object.keys(BACKEND),
+  stateResolver = sourceState,
+}) {
+  const unknownSkills = backendSkills.filter((skill) => !(skill in BACKEND));
+  if (unknownSkills.length) throw new Error(`Unknown backend source-index skill: ${unknownSkills.join(", ")}`);
+  for (const skill of backendSkills) {
+    const parts = BACKEND[skill];
+    const bases = parts.map((item) => path.join(source, item));
+    const found = await files(bases);
+    const target = path.join(skillsRoot, skill, "references", "source-index.md");
+    await mkdir(path.dirname(target), { recursive: true });
+    await writeFile(target, await backendIndex({ skill, parts, source, found, now, stateResolver }), "utf8");
+  }
+
+  if (frontend) {
+    for (const [skill, keys] of Object.entries(FRONTEND)) {
+      if (!await exists(path.join(skillsRoot, skill))) continue;
+      const target = path.join(skillsRoot, skill, "references", "frontend-docs.md");
+      await mkdir(path.dirname(target), { recursive: true });
+      await writeFile(target, [
+        `# ${skill} Frontend Documentation`,
+        "",
+        `Generated: ${now}`,
+        "",
+        "Use these YSS UI documentation entry points as authoritative references when local repo examples are insufficient.",
+        "",
+        ...keys.map((key) => `- ${key}: ${URLS[key]}`),
+        "",
+        "When documentation and local code differ, inspect the current project code before editing and prefer established local usage.",
+        "",
+      ].join("\n"), "utf8");
+    }
+  }
+  return { backend: backendSkills.length, frontend: frontend ? Object.keys(FRONTEND).length : 0 };
+}
+
+async function main() {
+  try {
+    const script = path.dirname(fileURLToPath(import.meta.url));
+    const result = await refresh({
+      skillsRoot: path.resolve(process.env.YSS_SKILLS_ROOT || path.join(script, "../..")),
+      source: await sourceRoot(),
+      frontend: !["0", "false", "no"].includes((process.env.YSS_REFRESH_FRONTEND || "true").toLowerCase()),
+      backendSkills: process.env.YSS_REFRESH_BACKEND_SKILLS
+        ? process.env.YSS_REFRESH_BACKEND_SKILLS.split(",").map((skill) => skill.trim()).filter(Boolean)
+        : Object.keys(BACKEND),
+    });
+    console.log(`Updated ${result.backend} backend indexes and ${result.frontend} frontend doc references.`);
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main();

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

@@ -1,9 +1,10 @@
 import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
 import { mkdir, mkdtemp, readFile, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import test from "node:test";
-import { refresh } from "./refresh-yss-skill-index.mjs";
+import { refresh, sourceState } from "./refresh-yss-skill-index.mjs";
 
 test("writes Node-labelled generated indexes", async () => {
   const root=await mkdtemp(path.join(tmpdir(),"yss-index-")); const source=path.join(root,"source"); const skills=path.join(root,"skills");
@@ -13,3 +14,80 @@ test("writes Node-labelled generated indexes", async () => {
   assert.match(await readFile(path.join(skills,"yss-cache/references/source-index.md"),"utf8"),/refresh-yss-skill-index\.mjs/);
   assert.match(await readFile(path.join(skills,"yss-ui/references/frontend-docs.md"),"utf8"),/components/);
 });
+
+test("writes a source-backed MyBatis capability matrix without absolute paths", async () => {
+  const root = await mkdtemp(path.join(tmpdir(), "yss-mybatis-index-"));
+  const source = path.join(root, "source");
+  const skills = path.join(root, "skills");
+  const component = "yss-microservice-components/yss-component-persistence";
+  const plusJava = path.join(source, component, "yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis");
+  const baseJava = path.join(source, component, "yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis");
+  const commonJava = path.join(source, component, "yss-component-persistence-common/src/main/java/com/yss/cloud/mybatis");
+
+  await mkdir(path.join(plusJava, "support"), { recursive: true });
+  await mkdir(path.join(baseJava, "config"), { recursive: true });
+  await mkdir(commonJava, { recursive: true });
+  await mkdir(path.join(skills, "yss-mybatis"), { recursive: true });
+  await writeFile(path.join(source, component, "pom.xml"), "<project/>");
+  await writeFile(path.join(plusJava, "support/BasePlusRepository.java"), [
+    "public interface BasePlusRepository<T> extends BaseMapper<T> {",
+    "  default Integer insertBatchSomeColumn(List<T> entities) { return 0; }",
+    "  Integer insertBatchSomeColumnInternal(List<T> entities);",
+    "}",
+  ].join("\n"));
+  await writeFile(path.join(baseJava, "config/PageQueryEntityConfigration.java"), [
+    "public class PageQueryEntityConfigration {",
+    "  @ConditionalOnProperty(name = \"yss.mybatis.page-helper.enabled\", havingValue = \"true\", matchIfMissing = true)",
+    "}",
+  ].join("\n"));
+  await writeFile(path.join(commonJava, "MultiDataSourceHolder.java"), [
+    "public class MultiDataSourceHolder {",
+    "  private Map<String, DataSource> multiDataSource;",
+    "}",
+  ].join("\n"));
+
+  await refresh({
+    skillsRoot: skills,
+    source,
+    now: "2026-01-01T00:00:00Z",
+    frontend: false,
+    backendSkills: ["yss-mybatis"],
+    stateResolver: () => ({
+      commit: "a".repeat(40),
+      componentWorktree: "clean",
+      componentTrees: [{ path: component, tree: "b".repeat(40) }],
+    }),
+  });
+
+  const index = await readFile(path.join(skills, "yss-mybatis/references/source-index.md"), "utf8");
+  assert.match(index, /## Capability Matrix/);
+  assert.match(index, /BasePlusRepository<T>/);
+  assert.match(index, /yss\.mybatis\.page-helper\.enabled/);
+  assert.match(index, /Map<String, DataSource>/);
+  assert.match(index, /Component worktree: `clean`/);
+  assert.match(index, /Component tree.*b{40}/);
+  assert.doesNotMatch(index, new RegExp(root.replaceAll("/", "\\/")));
+  assert.doesNotMatch(index, /## Key Java Entry Points/);
+});
+
+test("source freshness is scoped to the indexed component subtree", async () => {
+  const root = await mkdtemp(path.join(tmpdir(), "yss-component-state-"));
+  const component = "yss-microservice-components/yss-component-persistence";
+  const componentFile = path.join(root, component, "pom.xml");
+  const unrelatedFile = path.join(root, "yss-microservice-components/other/README.md");
+  await mkdir(path.dirname(componentFile), { recursive: true });
+  await mkdir(path.dirname(unrelatedFile), { recursive: true });
+  await writeFile(componentFile, "<project/>\n");
+  await writeFile(unrelatedFile, "clean\n");
+  execFileSync("git", ["init", "-q"], { cwd: root });
+  execFileSync("git", ["config", "user.email", "test@example.com"], { cwd: root });
+  execFileSync("git", ["config", "user.name", "Test"], { cwd: root });
+  execFileSync("git", ["add", "."], { cwd: root });
+  execFileSync("git", ["commit", "-qm", "fixture"], { cwd: root });
+
+  await writeFile(unrelatedFile, "dirty elsewhere\n");
+  assert.equal(sourceState(root, [component]).componentWorktree, "clean");
+
+  await writeFile(componentFile, "<project><dirty/></project>\n");
+  assert.equal(sourceState(root, [component]).componentWorktree, "dirty");
+});

package/template/.qoder/skills/code-review/SKILL.md

@@ -62,6 +62,10 @@ Look for the originating spec, in this order:
 
 Compile sources **before** spawning reviewers. For YSS implementation candidates follow [yss-review-standards.md](references/yss-review-standards.md): run machine checks that exist in the implementation repo; then collect repo docs (`CODING_STANDARDS.md` / `CONTRIBUTING.md` if present), every Slice `required_skills` skill file, the impact-conditioned specialist inputs (`alibaba-java-code-style`, `yss-ui`, `yss-domain`, …), and `docs/templates/review-report-template.md`. Missing applicable coverage is `missing_evidence`, not a pass.
 
+For YSS backend review, derive the review roots from the candidate project root, implementation-repository registry, Slice `project_roots` and `allowed_write_paths`. Review only the project itself and registered backend development projects; exclude frontend roots, unrelated submodules/vendor trees and unregistered directories. Never replace this resolution with a fixed `apps/backend` assumption.
+
+Every backend candidate must explicitly assess `yss-repository` and `yss-mybatis`. When the candidate changes persistence structure, Mapper/XML, SQL, pagination, batch operations, scanning/configuration or data-source behavior, read both skills and the selected Repository Profile; exact component claims also require a current `yss-mybatis` source index. When no persistence impact exists, record a concrete `not-applicable` reason for both instead of silently skipping them.
+
 Anything in the repo that documents how code should be written, such as `CODING_STANDARDS.md` or `CONTRIBUTING.md`, remains a source. It does **not** replace YSS or Alibaba specialist inputs.
 
 On top of whatever the repo documents, the Standards axis always carries the **smell baseline** below — a fixed set of Fowler code smells (_Refactoring_, ch.3) that applies even when a repo documents nothing. Two rules bind it:

package/template/.qoder/skills/code-review/agents/openai.yaml

@@ -1,3 +1,3 @@
 interface:
   display_name: "Code Review"
-  short_description: "Review a diff on standards, spec, and YSS/Alibaba specialist inputs"
+  short_description: "Review standards/spec plus YSS backend Repository/MyBatis and UI inputs"

package/template/.qoder/skills/code-review/references/yss-review-standards.md

@@ -11,7 +11,7 @@
 1. 仓库文档：`CODING_STANDARDS.md`、`CONTRIBUTING.md` 或实现仓等价文件（若存在）。
 2. Slice Implementation Contract 的 `required_skills`：对每个技能读取 `.agents/skills/<id>/SKILL.md` 及该 skill 指明的 references。
 3. 影响面专项检查输入（与合同并集，不得互相替代）：
-   - 后端：`alibaba-java-code-style`、`yss-domain`、`yss-application`、`yss-repository`、`yss-web-controller`、`yss-dto`、`mapstruct`、`lombok`
+   - 后端：`alibaba-java-code-style`、`yss-domain`、`yss-application`、`yss-repository`、`yss-mybatis`、`yss-web-controller`、`yss-dto`、`mapstruct`、`lombok`
    - UI：`yss-ui`、`yss-design-system`、`yss-ui-business-page-generation`
 4. 报告模板中的后端 / 前端门禁表。空着的适用行视为 `missing_evidence`。
 
@@ -19,11 +19,18 @@ YSS 页面模块约定（YTable、YFormily、页面骨架等）走 Standards，
 
 审查者只读这些 skill，不得用它们写实现路径。`role.test-engineer` 任务包禁止 `implement` 与脚手架生成器。
 
+### 后端范围与持久化适用性
+
+- Review roots 从候选本体项目、实现仓登记、Slice `project_roots` 和 `allowed_write_paths` 解析；只包含本体项目和已登记后端研发项目，不固定为 `apps/backend`，不扫描前端、无关 submodule/vendor 或未登记目录。
+- 每个后端候选都必须分别评估 `yss-repository` 与 `yss-mybatis`。命中 PO、Repository、Mapper/XML、SQL、分页、批量、扫描/配置或数据源行为时，两者均为 applicable，并加载所选 Repository Profile 与当前 MyBatis source index。
+- 精确组件 API/配置结论要求 source index 的组件 tree 与当前源码一致且组件子树 clean；不满足时为 `missing_evidence` / `stale`，不能判 pass。
+- 无持久化影响时，两项 Skill 分别记录具体 `not-applicable` 原因；仅写“未命中”或留空不构成证据。
+
 ## 2. 机器检查
 
 在派发 Standards / Spec 子审查之前，对实现仓**已登记且当前可执行**的命令实际跑一遍：
 
-- 后端优先：切片合同里的 `./mvnw` 验证；若工程已配置 Checkstyle / P3C / Spotless / `validate`，一并执行。
+- 后端优先：对本体项目和每个已登记后端研发项目分别执行其切片合同里的 `./mvnw` 验证；若工程已配置 Checkstyle / P3C / Spotless / `validate`，一并执行。
 - 前端优先：切片合同里的 `pnpm` 验证；若存在 `pnpm lint` / `pnpm type-check`，一并执行。
 
 记录命令、退出码、时间和证据引用。退出码非 0 记为 Standards **hard violation**。

package/template/.qoder/skills/yss-ddd-scaffold-generator/SKILL.md

@@ -88,7 +88,7 @@ node scripts/run_first_slice_verification.mjs \
 - 生成后的后端工程必须使用项目根目录 `./mvnw ...` 执行构建、测试、运行和 CI 验证；不得在 README、实施记录、Ticket、Review 或 Release 中默认写裸 `mvn ...`。既有仓库确实无法使用 wrapper 时，必须记录受控例外。
 - 原型确认后，`scaffold_status=required` 才能进入本 skill；本 skill 的生成边界是工程结构、POM、配置、Wrapper 和机械模板，不是业务实现。
 - 脚手架合同必须携带 `contract_id`、`contract_version`、实现合同编译器 draft 引用、生命周期批准引用、持久化引用、当前版本、允许写路径、预期证据文件和验证命令；字段缺失或版本过期时阻断。
-- 新脚手架合同只接受 schema v3，必须携带 `architecture_family=domain-driven`、`generator_skill`、`decision_ref/id/digest`、固定模块闭包，并分别携带 `project_name`、`base_package` 和 `maven_coordinates`；后者包含项目 `group_id` / `project_version`、父 POM GAV 与 `yss_components_version`，并由 CLI 原样传入。历史 schema v2 仅只读兼容，不用于新生成；schema v1/v2 均不自动升级。
+- 新脚手架优先接受统一 Project Scaffold Contract schema v4；已批准且当前的后端 schema v3 可完成兼容生成。两者都必须携带 `architecture_family=domain-driven`、`generator_skill`、`decision_ref/id/digest`、固定模块闭包，以及 `project_name`、`base_package` 和 `maven_coordinates`。历史 schema v2 仅只读兼容，不用于新生成；schema v1/v2 均不自动升级。
 - 合同 `profiles` 只支持 `target-domain-model`、`mybatis-plus`、`mysql`、`spring-boot-2.7-jdk8`、`javax`、`web`、`yss-internal`。普通 MyBatis、Boot 3、独立 client module、client-in-domain 和其他旧架构均为 `unsupported`，不提供回退分支。
 - 运行生成器必须传入 `--contract-file`；生成器会校验合同 `status=approved`、`current_version`、`primary_skill`、`controlled-generation`、实际输出路径和固定三条验证命令，不接受仅凭任意字符串引用的放行。
 - 生成项目必须写入 Manifest v3 `.yss/scaffold-generation.json`，记录架构选择及 digest、生成器、合同 digest、Target Profile、模块闭包、模板 digest、下游完整 skill tree digest、脚手架父合同与 实现合同编译器 合同 digest、generator-owned 文件 hash、严格 `generation_policy` 和完成等级；清单缺失或不一致时不得交给后续 实现合同编译器。

package/template/.qoder/skills/yss-ddd-scaffold-generator/scripts/generate_scaffold.mjs

@@ -9,6 +9,7 @@ import { fileURLToPath } from "node:url";
 import { parseDocument } from "../../../../scripts/vendor/yaml.mjs";
 import { assertLocalDatabaseProfile, localDatabaseConfiguration, scaffoldArchitectureIdentity } from "../../../../scripts/lib/scaffold-local-database.mjs";
 import { validateArchitectureIdentity } from "../../../../scripts/lib/backend-architecture.mjs";
+import { validateJsonSchema } from "../../../../scripts/lib/json-schema.mjs";
 
 import {
   findGitRoot,
@@ -204,7 +205,9 @@ class ScaffoldGenerator {
     const contractText = await readFile(this.contractFile, "utf8");
     let contract; try { contract = JSON.parse(contractText); } catch { fail(`脚手架合同文件无法读取或不是合法 JSON: ${this.contractFile}`); }
     if (!contract || Array.isArray(contract) || typeof contract !== "object") fail("脚手架合同必须是 JSON 对象");
-    if (contract.schema_version !== 3) fail(`unsupported: scaffold contract schema_version=${contract.schema_version}；新生成只接受 schema v3，不提供自动升级`);
+    if (![3, 4].includes(contract.schema_version)) fail(`unsupported: scaffold contract schema_version=${contract.schema_version}；只接受兼容 v3 或统一 v4`);
+    if (contract.schema_version === 4 && (contract.kind !== "project-scaffold-contract" || contract.delivery_role !== "backend" || contract.scaffold_kind !== "backend-ddd")) fail("schema v4 合同必须绑定 backend/backend-ddd");
+    if (contract.schema_version === 4) validateJsonSchema(contract, path.join(REPOSITORY_ROOT, "docs/process/schemas/project-scaffold-contract.schema.json"), { label: "Project Scaffold Contract v4" });
     const requiredMetadata = [["--contract-id", this.options.contractId], ["--contract-version", this.options.contractVersion], ["--approval-ref", this.options.approvalRef], ["--compiler-draft-ref", this.options.compilerDraftRef], ["--persisted-ref", this.options.persistedRef]];
     const missing = requiredMetadata.filter(([, value]) => !isPresent(value)).map(([flag]) => flag);
     if (missing.length) fail(`生成项目必须提供当前已批准脚手架合同的完整元数据: ${missing.join(", ")}`);
@@ -214,7 +217,7 @@ class ScaffoldGenerator {
     if (contract.status !== "approved") fail("脚手架合同必须已由生命周期批准");
     if (contract.contract_id !== this.options.contractId) fail("--contract-id 与脚手架合同不一致");
     if (contract.contract_version !== this.options.contractVersion) fail("--contract-version 与脚手架合同不一致");
-    if (contract.current_version !== contract.contract_version) fail("脚手架合同版本不是当前版本");
+    if (contract.current_version !== contract.contract_version && !(contract.schema_version === 4 && contract.current_version === true)) fail("脚手架合同版本不是当前版本");
     if (contract.compiler_draft_ref !== this.options.compilerDraftRef) fail("--compiler-draft-ref 与脚手架合同不一致");
     if (contract.persisted_ref !== this.options.persistedRef) fail("--persisted-ref 与脚手架合同不一致");
     if (contract.lifecycle_approval_ref !== this.options.approvalRef) fail("--approval-ref 与脚手架合同不一致");
@@ -364,6 +367,7 @@ class ScaffoldGenerator {
     const scaffoldParent = path.join(SKILL_ROOT, "references", "yss-backend-scaffold-parent", "SKILL.md");
     const compilerContract = path.join(REPOSITORY_ROOT, ".agents", "skills", "yss-implementation-contract-compiler", "references", "compiler-contract.yaml");
     const manifest = { schema_version: 3, kind: "backend-scaffold", architecture_profile: contract.architecture_profile, architecture_identity: scaffoldArchitectureIdentity(contract, this.contractDigest), contract_id: this.options.contractId, contract_version: this.options.contractVersion, scaffold_request_id: contract.scaffold_request_id, architecture_family: contract.architecture_family, generator_skill: contract.generator_skill, decision_id: contract.decision_id, decision_digest: contract.decision_digest, module_profile: contract.module_profile, approval_ref: this.options.approvalRef, compiler_draft_ref: this.options.compilerDraftRef, persisted_ref: this.options.persistedRef, contract_file_ref: this.contractFile, contract_digest: this.contractDigest, lifecycle_approval_ref: contract.lifecycle_approval_ref, current_version: contract.current_version, approver: contract.approval.approver, allowed_write_paths: contract.allowed_write_paths, expected_evidence_files: contract.expected_evidence_files, project_name: this.projectName, base_package: this.basePackage, bootstrap_main_class: `${this.basePackage}.${this.applicationClassName}`, bootstrap_main_source: this.bootstrapMainSource, maven_coordinates: this.mavenCoordinates, maven_coordinates_source: this.mavenCoordinatesSource, profiles: this.profiles, generation_mode: "controlled-generation", completion_level: "generated", generator: { id: "yss-ddd-scaffold-generator", template_digest: await treeDigest(path.join(SKILL_ROOT, "assets")) }, ownership: { generated_files: generatedFiles, user_owned_globs: ["**/src/main/java/**", "**/src/test/java/**", "db/**"] }, readiness: { downstream_skills: downstream, contracts: { scaffold_parent: sha256(await readFile(scaffoldParent)), compiler_contract: sha256(await readFile(compilerContract)) }, architecture_ruleset: sha256(await readFile(path.join(this.javaTemplateDir, "architecture-rules-test.java.template"))) }, generation_policy: { mode: "initialize-only", existing_target: "unsupported", old_project_migration: "unsupported", template_upgrade: "unsupported" }, verification_commands: COMMANDS, generated_at: isoNow() };
+    manifest.schema_version = contract.schema_version;
     await writeText(path.join(this.projectRoot, ".yss", "scaffold-generation.json"), `${JSON.stringify(manifest, null, 2)}\n`); console.log("  ✓ .yss/scaffold-generation.json");
   }
   async copyWrapperFiles() {
@@ -375,7 +379,7 @@ class ScaffoldGenerator {
     const required = [path.join(this.projectRoot, "pom.xml"), path.join(this.projectRoot, `${this.projectName}-bootstrap`, "pom.xml"), path.join(this.projectRoot, this.bootstrapMainSource), path.join(this.projectRoot, "mvnw"), path.join(this.projectRoot, ".yss", "scaffold-generation.json")];
     const missing = []; for (const target of required) if (!await isFile(target)) missing.push(target); if (missing.length) fail(`生成产物缺失: ${missing.join(", ")}`);
     const manifest = await readJson(required[4], "脚手架生成元数据清单无法读取");
-    if (manifest.schema_version !== 3 || manifest.contract_id !== this.options.contractId || manifest.contract_version !== this.options.contractVersion || manifest.current_version !== this.options.contractVersion || manifest.generation_mode !== "controlled-generation" || manifest.architecture_family !== "domain-driven" || manifest.generator_skill !== "yss-ddd-scaffold-generator" || manifest.decision_id !== this.scaffoldContract.decision_id || manifest.decision_digest !== this.scaffoldContract.decision_digest || JSON.stringify(manifest.module_profile) !== JSON.stringify(this.scaffoldContract.module_profile) || manifest.bootstrap_main_class !== `${this.basePackage}.${this.applicationClassName}` || manifest.bootstrap_main_source !== this.bootstrapMainSource || manifest.profiles.architecture !== SUPPORTED_PROFILES.architecture || manifest.generation_policy.mode !== "initialize-only" || manifest.generation_policy.existing_target !== "unsupported" || JSON.stringify(manifest.verification_commands) !== JSON.stringify(COMMANDS)) fail("脚手架生成元数据清单与当前批准架构决策、合同、Target Profile、initialize-only 边界、机械启动入口或固定验证命令不一致");
+    if (![3, 4].includes(manifest.schema_version) || manifest.contract_id !== this.options.contractId || manifest.contract_version !== this.options.contractVersion || (manifest.current_version !== this.options.contractVersion && manifest.current_version !== true) || manifest.generation_mode !== "controlled-generation" || manifest.architecture_family !== "domain-driven" || manifest.generator_skill !== "yss-ddd-scaffold-generator" || manifest.decision_id !== this.scaffoldContract.decision_id || manifest.decision_digest !== this.scaffoldContract.decision_digest || JSON.stringify(manifest.module_profile) !== JSON.stringify(this.scaffoldContract.module_profile) || manifest.bootstrap_main_class !== `${this.basePackage}.${this.applicationClassName}` || manifest.bootstrap_main_source !== this.bootstrapMainSource || manifest.profiles.architecture !== SUPPORTED_PROFILES.architecture || manifest.generation_policy.mode !== "initialize-only" || manifest.generation_policy.existing_target !== "unsupported" || JSON.stringify(manifest.verification_commands) !== JSON.stringify(COMMANDS)) fail("脚手架生成元数据清单与当前批准架构决策、合同、Target Profile、initialize-only 边界、机械启动入口或固定验证命令不一致");
     const stack = [this.projectRoot], binary = new Set([".class", ".db", ".jar", ".png", ".jpg", ".jpeg", ".gif"]);
     while (stack.length) { const dir = stack.pop(); for (const entry of await readdir(dir, { withFileTypes: true })) { const target = path.join(dir, entry.name); if (entry.isDirectory()) { stack.push(target); continue; } if (!entry.isFile() || binary.has(path.extname(entry.name))) continue; const content = await readFile(target, "utf8"); if (content.includes("{{") || content.includes("root/root")) fail(`生成文件包含未替换占位符或明文凭据: ${target}`); } }
   }