create-yss-spec 3.1.3 → 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/.pi/skills/yss-tactical-design/SKILL.md

@@ -9,7 +9,7 @@ description: 在 YSS 技术分析阶段将批准的战略领域输入细化为
 
 ## 适用边界
 
-- 由 `yss-product-lifecycle` 在 `work-unit.technical-analysis` 中按领域影响条件调度。
+- 由 `yss-technical-design` 在已确认 `domain-driven` 的技术设计分支中调用；传统 MVC 使用 `yss-mvc-design`，不得按状态或一致性影响单独推断为 DDD。
 - 输入必须是版本当前的 Spec、功能架构、战略 DDD、状态矩阵、OpenAPI Draft / Freeze、ADR 和工程约束。若输入来自 Strategic Design Handoff，必须先用 `scripts/verify-strategic-context-import` 验证 schema v3 `source_context_snapshot` / `context_delta` 已对账到目标仓根 `CONTEXT.md`，Visual Baseline Bundle 可读取且 digest 当前，并且目标侧 `context_reconciliation` 有效；未完成时不得开始战术建模。
 - 默认将结果写入系统概要设计 / 数据架构中的 Tactical DDD Check；聚合、状态机、一致性或持久化映射复杂到无法清楚表达时，才升级为独立战术设计文档。
 - 没有聚合、状态、不变量、一致性或领域边界影响时返回 `not-applicable` 及原因，不生成空设计。
@@ -22,7 +22,7 @@ description: 在 YSS 技术分析阶段将批准的战略领域输入细化为
 
 ## 输出与状态
 
-输出结构化 tactical-design contract、验证结果、评审引用和影响标记；来自 Strategic Design Handoff 时保留 `strategic_context_import_ref` 与 `context_reconciliation_ref`。状态使用 `draft`、`ready-for-human`、`approved`、`blocked`、`stale`、`drift`、`new_impacts`。
+新产物输出 Technical Design Contract schema v2 的 DDD `design` 分支（沿用 v1 DDD 内容结构）；旧独立 tactical-design contract schema v1 仅显式兼容读取，不自动迁移或批准。输出验证结果、评审引用和影响标记；来自 Strategic Design Handoff 时保留 `strategic_context_import_ref` 与 `context_reconciliation_ref`。状态使用 `draft`、`ready-for-human`、`approved`、`blocked`、`stale`、`drift`、`new_impacts`。
 
 当用户或当前技术分析 / 架构评审合同明确要求聚合关系、状态转换、调用链、数据流或 Before/After 图示时，追加使用 `archify`。图必须从当前 Spec、ADR、OpenAPI、Tactical Design Contract 和代码证据派生，保存成 `*.archify.json`、`*.html` 与 `*.receipt.json` 配对资产；它是审查证据，不是新的事实源或批准门禁。没有明确图示要求时，不把 `archify` 加入 `required_skills`。
 

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

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

package/template/.pi/skills/yss-tactical-design/references/tactical-design-contract.md

@@ -6,6 +6,8 @@
 
 ## 输出
 
+以下 v1 结构作为新 Technical Design Contract v2 的 DDD `design` 内容使用。旧独立 v1 文件保持显式只读兼容；新合同共同头与战略交接绑定由 `yss-technical-design` 持有，分支不重复保存。
+
 ```yaml
 schema_version: 1
 tactical_design_id: tactical-design.<feature>
@@ -40,4 +42,4 @@ evidence_refs: []
 6. 复杂跨聚合一致性、并发、幂等、事件补偿或持久化错位必须写明策略，必要时升级独立文档。
 7. 实现发现新影响时必须阻断并回到生命周期重新路由。
 
-跨仓快照消费另须 `strategic_handoff`；字段与实际命令以 `docs/process/strategic-handoff-package.md` 为准。
+跨仓快照消费在 v2 共同头（旧独立 v1 则为根对象）绑定 `strategic_handoff`；字段与实际命令以 `docs/process/strategic-handoff-package.md` 为准。

package/template/.pi/skills/yss-tactical-design/scripts/validate-tactical-design.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { readFile } from "node:fs/promises";
 import process from "node:process";
+import { pathToFileURL } from "node:url";
 import { parseDocument } from "../../../../scripts/vendor/yaml.mjs";
 
 import { parseArgs } from "node:util";
@@ -68,7 +69,7 @@ function refsExist(values, known, path, errors) {
   }
 }
 
-function validate(data) {
+export function validate(data) {
   const errors = [];
   if (!isObject(data)) return ["合同必须是对象"];
   for (const field of required) requireField(data, field, "root", errors);
@@ -218,4 +219,4 @@ async function main() {
   process.stdout.write(`${JSON.stringify({ result: "ready-for-lifecycle-review", tactical_design_id: document.get("tactical_design_id"), status: document.get("status") }, null, 2)}\n`);
 }
 
-main().catch((error) => { process.stderr.write(`${error.message}\n`); process.exitCode = 1; });
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) main().catch((error) => { process.stderr.write(`${error.message}\n`); process.exitCode = 1; });

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

@@ -0,0 +1,31 @@
+---
+name: yss-technical-design
+description: 在 YSS 技术分析中统一承接需求与战略输入，按已确认的 DDD 或传统 MVC 架构组织设计合同。
+---
+
+# YSS 技术设计
+
+由 `yss-product-lifecycle` 调度，负责 `work-unit.technical-analysis` 的技术设计，不另起生命周期、不生成生产代码。生命周期维护批准和状态；`yss-implementation-contract-compiler` 消费批准且当前的设计，起草实现合同。
+
+## 输入与架构选择
+
+先读根 `CONTEXT.md`、已批准且当前的 Spec、业务规则、关键场景、适用的 API 契约、ADR 和工程约束。没有 API 或其他专项影响时记录有依据的不适用，不生成占位设计。
+
+按项目绑定架构选择的来源及摘要。新工程复用 `scaffold-architecture-decisions.yaml` 的用户确认决定，先确认再进入分支，后续脚手架消费同一决定；既有工程沿用已登记架构，架构转换另行立项。只有 `domain-driven` 和 `layered-mvc` 两种架构族，不能从目录推断或默认 DDD。具体 Profile 及模块边界消费技能注册表与 `docs/agents/backend-architecture-profiles.md`。
+
+- `domain-driven`：调用 `yss-tactical-design`，补齐适用的战略领域输入。
+- `layered-mvc`：调用 `yss-mvc-design`，不要求战略 DDD、聚合、值对象、Domain Event 或 DDD Gateway。
+
+已有 Strategic Design Handoff 时，两种分支都必须先完成导入和目标词汇对账，再逐条承接规则与关键场景。没有战略交接包的项目直接消费批准需求，不能为 MVC 补造战略 DDD。
+
+## 合同与验证
+
+新产物使用 schema v2 Technical Design Contract：共同头记录架构来源、输入版本与摘要、规则/场景承接、评审证据和状态，`design` 保存架构专属内容。合同格式与兼容规则见 `references/technical-design-contract.md`，Schema 见 `references/technical-design.schema.json`。
+
+运行 `node .agents/skills/yss-technical-design/scripts/validate-technical-design.mjs <合同> --root <项目根>`。整体存在延期或冲突即阻断整体；相关切片可带 `--slice <切片ID>` 按依赖核验，仍须合同已批准。校验成功只返回审查输入，不批准、不设置 `ready-for-agent`。
+
+schema v1 战术合同只按 DDD 显式兼容读取；使用 `--legacy-ddd`，不能解释为 MVC。迁移不自动批准，输入或架构变化必须重新校验并按现有门禁审查。新合同使用 `artifact.technical-design` / `evidence.technical-design-review`；旧 DDD 稳定 ID 保留原含义。
+
+## 交接
+
+按现有架构审查门禁进行独立评审。批准且版本当前后交回生命周期，再交编译器；DDD 实现使用 `yss-domain`，MVC 实现按已登记 Profile 的能力与 Recipe 路由。发现 `stale`、`drift`、`new_impacts` 或路径越界时回交重路由。需要图示时按用户或合同要求调用 `archify`，图只作派生证据。

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "YSS 技术设计"
+  short_description: "按已确认 DDD 或 MVC 架构组织技术设计合同"
+  default_prompt: "基于当前批准输入和已确认架构，按已确认 DDD 或 MVC 架构组织技术设计合同，返回待生命周期审查的结果。"