create-yss-spec 3.2.0 → 3.3.1

package/template/.agents/skills/yss-skill-source-index-refresh/SKILL.md

@@ -28,10 +28,11 @@ node "$YSS_SKILLS_ROOT/yss-skill-source-index-refresh/scripts/refresh-yss-skill-
 ```
 
 Backend-only refreshes may set `YSS_REFRESH_FRONTEND=false` to avoid unrelated frontend timestamp churn.
+Use `YSS_REFRESH_BACKEND_SKILLS=yss-mybatis` (comma-separated) to refresh only selected backend indexes and avoid unrelated component churn.
 
 The script updates `references/source-index.md` for backend component skills and `references/frontend-docs.md` for frontend YSS UI skills. Read `references/source-map-config.md` for the full skill-to-source mapping.
 
-中文说明：脚本不会复制大段源码，只会生成可追踪的文档路径、模块路径和关键 Java 入口类，方便 Agent 后续精准读取。
+中文说明：脚本不会复制大段源码；通用组件生成可追踪的入口索引，持久化组件额外生成公开 API、配置开关和能力边界矩阵，方便 Agent 按需读取真实源码。
 
 If `YSS_SOURCE_ROOT` is omitted, the script tries to find a repository containing `yss-microservice-components` from the current workspace and common local project folders. If it cannot find one, set `YSS_SOURCE_ROOT` explicitly.
 
@@ -39,18 +40,20 @@ If `YSS_SOURCE_ROOT` is omitted, the script tries to find a repository containin
 
 Generated source indexes should contain:
 
-- source root and generated timestamp
-- exact source Git commit and worktree state
+- generated timestamp and trace-only source Git commit
+- component-relative tree hashes and component-scoped worktree state
 - component directories and documentation files
 - Maven modules
-- key Java classes matched by names such as annotations, auto configurations, properties, aspects, interceptors, handlers, repositories, DTOs, and result objects
+- source file hashes and relocatable paths
+- for capability-sensitive components, concise public signatures, configuration keys/defaults, conditional activation and capability boundaries extracted from source
+- for other components, key Java classes matched by names such as annotations, auto configurations, properties, aspects, interceptors, handlers, repositories, DTOs, and result objects
 - recommended next reads for Agent when performing implementation or troubleshooting
 
 Do not paste full component source into `SKILL.md`. Keep `SKILL.md` short and let specialists read generated indexes or targeted assets only when needed.
 
 ## Freshness Gate
 
-Before exact class/config/security guidance, compare the index `Source commit` with `git -C "$YSS_SOURCE_ROOT" rev-parse HEAD`. A mismatch or `dirty` indexed state means `stale`: refresh the index or return `blocked`; do not silently rely on the old snapshot. Historical path hints may still be used only to locate current source.
+Before exact class/config/security guidance, compare each indexed `Component tree` with `git -C "$YSS_SOURCE_ROOT" rev-parse HEAD:<component-path>` and check `git status --porcelain -- <component-path>`. A tree mismatch or component-local dirty state means `stale`: refresh the index or return `blocked`; do not silently rely on the old snapshot. A repository commit difference alone is trace metadata and does not make the index stale when the component tree is unchanged. Historical path hints may still be used only to locate current source.
 
 中文说明：`SKILL.md` 保持短小，细节放到 `references/`，这是为了降低每次触发技能时的上下文成本。
 

package/template/.agents/skills/yss-skill-source-index-refresh/references/source-location.md

@@ -6,7 +6,7 @@ YSS skill references may mention paths such as `yss-microservice-components/yss-
 
 1. Check the current workspace first. If `.codegraph/` exists, use `codegraph explore "<class, module, or path hint>"` before text search.
 2. If the component source is outside the workspace, use `YSS_SOURCE_ROOT` when it is set. It should point to the repository root that contains `yss-microservice-components`.
-   Compare `git -C "$YSS_SOURCE_ROOT" rev-parse HEAD` with the selected index `Source commit`; mismatch is `stale` and blocks exact implementation guidance until refresh.
+   Compare every indexed `Component tree` with `git -C "$YSS_SOURCE_ROOT" rev-parse HEAD:<component-path>` and check `git status --porcelain -- <component-path>`. A tree mismatch or component-local dirty state is `stale` and blocks exact implementation guidance until refresh. `Source commit` is trace metadata only; unrelated monorepo changes do not stale an unchanged component tree.
 3. If `YSS_SOURCE_ROOT` is not set, search common local roots such as the current repository parents, `~/Projects`, `~/Documents`, and `~/Documents/yss-project`.
 4. If the source still cannot be found, use the generated `references/source-index.md` as a stale-but-useful map of module names, package names, class names, and Maven artifacts. Do not assume listed files exist locally.
 
@@ -15,4 +15,5 @@ YSS skill references may mention paths such as `yss-microservice-components/yss-
 - Say "source path hints" instead of "source root" unless you have verified the directory in the current environment.
 - Keep generated indexes useful for search, but do not require agents to open those exact paths.
 - Prefer symbols, package names, Maven artifact names, and annotations in instructions; they survive repository relocation better than absolute paths.
+- Keep full production source out of skill `assets/`; generate concise signatures, activation conditions and file hashes instead.
 - When refreshing indexes, export `YSS_SOURCE_ROOT=/absolute/path/to/yss-cloud-microservice` if auto-detection cannot find the component repository.

package/template/.agents/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/.agents/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/.agents/skills/yss-stage-decision/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yss-stage-decision
-description: 编排 Discovery 到 Spec 入口的方案决策与业务边界、协作和规则设计；当需求、业务责任区、统一业务词汇或下游影响尚未稳定时使用。
+description: 编排 Plan 到 Spec 入口的方案决策与业务边界、协作和规则设计；当需求、业务责任区、统一业务词汇或下游影响尚未稳定时使用。
 ---
 
 # YSS Stage Decision
@@ -9,14 +9,16 @@ description: 编排 Discovery 到 Spec 入口的方案决策与业务边界、
 
 ## 适用边界
 
-- 适用于 `project-instance` 的 Discovery → Spec 入口。
+- 适用于 `project-instance` 的 Plan → Spec 入口。
 - `template-source` 只维护本技能、Schema、验证器和合成 Fixture，不生成具体产品领域资产。
 - 业务边界与协作工作单元只回答：有哪些业务板块、每个业务责任区负责什么、不同责任区如何交接、使用哪些统一业务词汇、发生哪些业务事实、有哪些待确认的关键业务对象和不可违反的业务规则。
 - Entity、Aggregate、Repository、Java 类、数据库表和 OpenAPI Freeze 留给下游工作单元。
 
 ## 执行顺序
 
-1. 读取 `yss-project.yaml`、`CONTEXT.md`、既有 Discovery/Spec、ADR 和父 Ticket/checkpoint。
+Plan 的目标与退出条件由 `docs/process/lifecycle-registry.yaml` 持有；从 `docs/plan/templates/plan-template.md` 汇总输入。旧资产按 `docs/process/plan-migration.md` 重新整理并核查，关键未决项不得延期到 Spec，非关键项记录责任人、解决时点与接收方。
+
+1. 读取 `yss-project.yaml`、`CONTEXT.md`、既有 Plan/Spec、ADR 和父 Ticket/checkpoint。
 2. 分离事实、决策、假设、约束和未决项；技术事实走 `yss-research` 的 `technical-evidence`，领域边界、业务规则、MVP、非目标、成功标准或阶段推进依据等决策证据走 `strategy-evidence`，市场/竞品事实走 `competitive-intelligence`。
 3. 从业务故事、已发生的事实、规则、责任人和失败路径识别业务板块与业务责任区，不从数据库表或调用链直接反推边界。
 4. 为每个业务责任区建立统一业务词汇；对跨责任区协作记录规则提供方、规则使用方、业务决策权、信息传递方向和口径转换负责人。

package/template/.agents/skills/yss-stage-decision/references/stage-decision-package-contract.md

@@ -1,6 +1,6 @@
 # 方案决策包合同
 
-内部对象 `stage_decision_package` 是 Discovery、需求/产品/商务决策与业务边界和规则设计之间的冻结入口。它记录“做什么、为什么做、范围是什么、哪些仍未决”，不复制业务边界与规则事实。
+内部对象 `stage_decision_package` 是 Plan、需求/产品/商务决策与业务边界和规则设计之间的冻结入口。它记录“做什么、为什么做、范围是什么、哪些仍未决”，不复制业务边界与规则事实。
 
 ## 必须包含
 

package/template/.claude/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/.claude/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"