create-yss-spec 2.2.10 → 3.0.1

package/template/.agents/skills/yss-research/scripts/validate-research-package.mjs

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import path from "node:path";
+
+const PROFILE_VALUES = ["technical-evidence", "strategy-evidence"];
+const SOURCE_LEVELS = ["primary", "direct-experience", "near-primary", "secondary", "lead-only"];
+const CLAIM_KINDS = ["technical-fact", "user-problem", "business-constraint", "domain-boundary", "business-rule", "mvp", "non-goal", "success-criterion", "stage-decision-basis", "background"];
+const STRATEGY_DECISION_KINDS = new Set(["user-problem", "business-constraint", "domain-boundary", "business-rule", "mvp", "non-goal", "success-criterion", "stage-decision-basis"]);
+
+function fail(message) { throw new TypeError(message); }
+function requireString(value, label) { if (typeof value !== "string" || !value.trim()) fail(`${label} must be a non-empty string`); }
+function requireArray(value, label, nonEmpty = false) { if (!Array.isArray(value) || (nonEmpty && value.length === 0)) fail(`${label} must be ${nonEmpty ? "a non-empty" : "an"} array`); }
+function requireChoice(value, choices, label) { if (!choices.includes(value)) fail(`${label} must be one of: ${choices.join(", ")}`); }
+
+function indexed(items, label) {
+  const result = new Map();
+  items.forEach((item, index) => {
+    requireString(item?.id, `${label}[${index}].id`);
+    if (result.has(item.id)) fail(`${label} contains duplicate id: ${item.id}`);
+    result.set(item.id, item);
+  });
+  return result;
+}
+
+function readEvidence(file) {
+  try {
+    const value = JSON.parse(readFileSync(file, "utf8"));
+    if (!value || typeof value !== "object" || Array.isArray(value)) fail("evidence root must be an object");
+    return value;
+  } catch (error) {
+    if (error instanceof TypeError && error.message === "evidence root must be an object") throw error;
+    fail(`${path.basename(file)} must use JSON-compatible YAML 1.2 syntax: ${error.message}`);
+  }
+}
+
+function validate(briefFile, evidenceFile) {
+  if (!briefFile || !evidenceFile) fail("usage: validate-research-package.mjs <brief.md> <evidence.yaml>");
+  const briefPath = path.resolve(briefFile);
+  const evidencePath = path.resolve(evidenceFile);
+  if (path.dirname(briefPath) !== path.dirname(evidencePath)) fail("brief and evidence files must be adjacent");
+  if (!briefPath.endsWith("-research-brief.md") || !evidencePath.endsWith("-evidence.yaml")) fail("expected <slug>-research-brief.md and <slug>-evidence.yaml");
+  const briefSlug = path.basename(briefPath, "-research-brief.md");
+  if (!briefSlug || briefSlug !== path.basename(evidencePath, "-evidence.yaml")) fail("brief and evidence files must use the same non-empty slug");
+
+  const brief = readFileSync(briefPath, "utf8");
+  ["Research Scope", "Executive Read", "Findings", "Counter-Signals", "Source Map", "Decision Handoff", "Evidence Limitations"].forEach((heading) => {
+    if (!brief.includes(`## ${heading}`)) fail(`brief is missing heading: ## ${heading}`);
+  });
+
+  const data = readEvidence(evidencePath);
+  if (data.schema_version !== 1) fail("schema_version must be 1");
+  requireChoice(data.profile, PROFILE_VALUES, "profile");
+  if (data.mode !== "evidence-audited") fail("mode must be evidence-audited");
+  ["topic", "audience", "time_horizon"].forEach((field) => requireString(data.scope?.[field], `scope.${field}`));
+  ["research_questions", "inclusion_criteria", "exclusion_criteria"].forEach((field) => requireArray(data.scope?.[field], `scope.${field}`, true));
+  if (data.ownership?.research_owner !== "yss-research") fail("ownership.research_owner must be yss-research");
+  requireString(data.ownership?.downstream_owner, "ownership.downstream_owner");
+  if (data.ownership.decision_ref !== null && (typeof data.ownership.decision_ref !== "string" || !data.ownership.decision_ref.trim())) fail("ownership.decision_ref must be null or a non-empty string");
+
+  requireArray(data.search_log, "search_log", true);
+  const searches = indexed(data.search_log, "search_log");
+  data.search_log.forEach((entry, index) => {
+    ["channel", "query_or_corpus", "searched_at"].forEach((field) => requireString(entry[field], `search_log[${index}].${field}`));
+    requireChoice(entry.result, ["results-found", "none-found", "access-failed", "excluded"], `search_log[${index}].result`);
+  });
+
+  requireArray(data.evidence_items, "evidence_items", true);
+  const evidence = indexed(data.evidence_items, "evidence_items");
+  data.evidence_items.forEach((item, index) => {
+    requireChoice(item.source_level, SOURCE_LEVELS, `evidence_items[${index}].source_level`);
+    requireChoice(item.visibility, ["public", "internal"], `evidence_items[${index}].visibility`);
+    requireChoice(item.stance, ["support", "counter"], `evidence_items[${index}].stance`);
+    ["source_class", "source_ref", "locator", "observed_at", "observation"].forEach((field) => requireString(item[field], `evidence_items[${index}].${field}`));
+    requireArray(item.limitations, `evidence_items[${index}].limitations`);
+  });
+
+  requireArray(data.claims, "claims", true);
+  const claims = indexed(data.claims, "claims");
+  data.claims.forEach((claim, index) => {
+    requireChoice(claim.claim_kind, CLAIM_KINDS, `claims[${index}].claim_kind`);
+    requireString(claim.statement, `claims[${index}].statement`);
+    if (typeof claim.decision_bearing !== "boolean") fail(`claims[${index}].decision_bearing must be boolean`);
+    requireArray(claim.evidence_refs, `claims[${index}].evidence_refs`, true);
+    requireArray(claim.counter_signal_refs, `claims[${index}].counter_signal_refs`, true);
+    requireChoice(claim.audit_status, ["supported", "partially-supported", "unsupported", "not-audited"], `claims[${index}].audit_status`);
+    requireChoice(claim.confidence, ["low", "medium", "high"], `claims[${index}].confidence`);
+    requireChoice(claim.disposition, ["publish", "qualify", "needs-deeper-research"], `claims[${index}].disposition`);
+
+    const supporting = claim.evidence_refs.map((ref) => {
+      if (!evidence.has(ref)) fail(`${claim.id} has unresolved evidence ref: ${ref}`);
+      const item = evidence.get(ref);
+      if (item.stance !== "support") fail(`${claim.id} support ref is not marked support: ${ref}`);
+      if (item.source_level === "lead-only") fail(`${claim.id} uses lead-only evidence as support: ${ref}`);
+      return item;
+    });
+    claim.counter_signal_refs.forEach((ref) => {
+      if (!evidence.has(ref) && !searches.has(ref)) fail(`${claim.id} has unresolved counter-signal ref: ${ref}`);
+      if (evidence.has(ref) && evidence.get(ref).stance !== "counter") fail(`${claim.id} counter-signal evidence is not marked counter: ${ref}`);
+      if (searches.has(ref) && searches.get(ref).result !== "none-found") fail(`${claim.id} counter-signal search must have result none-found: ${ref}`);
+    });
+    if (data.profile === "technical-evidence" && claim.decision_bearing && !supporting.some((item) => item.source_level === "primary")) fail(`${claim.id} is a decision-bearing technical claim without primary evidence`);
+    if (data.profile === "strategy-evidence" && STRATEGY_DECISION_KINDS.has(claim.claim_kind) && claim.decision_bearing !== true) fail(`${claim.id} strategy claim kind must be decision-bearing: ${claim.claim_kind}`);
+    if (claim.audit_status === "partially-supported" && claim.disposition !== "qualify") fail(`${claim.id} is partially supported and must use qualify`);
+    if (claim.audit_status === "unsupported" && claim.disposition !== "needs-deeper-research") fail(`${claim.id} is unsupported and must use needs-deeper-research`);
+    if (claim.decision_bearing && claim.audit_status === "unsupported") fail(`${claim.id} is decision-bearing and cannot remain unsupported`);
+    if (!brief.includes(claim.id)) fail(`brief does not reference claim: ${claim.id}`);
+  });
+
+  requireArray(data.source_gaps, "source_gaps");
+  if (data.audit_summary?.status !== "complete") fail("audit_summary.status must be complete");
+  requireArray(data.audit_summary.audited_claim_ids, "audit_summary.audited_claim_ids", true);
+  requireArray(data.audit_summary.notes, "audit_summary.notes");
+  const audited = new Set(data.audit_summary.audited_claim_ids);
+  audited.forEach((id) => { if (!claims.has(id)) fail(`audit_summary has unknown claim: ${id}`); });
+  claims.forEach((claim, id) => {
+    if (claim.decision_bearing && !audited.has(id)) fail(`audit_summary is missing decision-bearing claim: ${id}`);
+    if (claim.decision_bearing && claim.audit_status === "not-audited") fail(`${id} remains not-audited`);
+  });
+  return { claims: claims.size, evidence: evidence.size, searches: searches.size, profile: data.profile };
+}
+
+try {
+  const result = validate(process.argv[2], process.argv[3]);
+  process.stdout.write(`YSS research package valid (${result.profile}, ${result.claims} claims, ${result.evidence} evidence items, ${result.searches} searches)\n`);
+} catch (error) {
+  process.stderr.write(`YSS research package invalid: ${error.message}\n`);
+  process.exitCode = 1;
+}

package/template/.agents/skills/yss-research/tests/run-scenarios.mjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const validator = path.join(root, "scripts/validate-research-package.mjs");
+const template = JSON.parse(readFileSync(path.join(root, "assets/evidence-template.yaml"), "utf8"));
+const directory = mkdtempSync(path.join(tmpdir(), "yss-research-"));
+const brief = path.join(directory, "sample-research-brief.md");
+const evidence = path.join(directory, "sample-evidence.yaml");
+const headings = ["Research Scope", "Executive Read", "Findings", "Counter-Signals", "Source Map", "Decision Handoff", "Evidence Limitations"];
+
+function run(payload, status, expected) {
+  writeFileSync(brief, `${headings.map((heading) => `## ${heading}`).join("\n\n")}\n\n${payload.claims.map((claim) => claim.id).join(" ")}\n`);
+  writeFileSync(evidence, `${JSON.stringify(payload, null, 2)}\n`);
+  const result = spawnSync(process.execPath, [validator, brief, evidence], { encoding: "utf8" });
+  if (result.status !== status || !`${result.stdout}${result.stderr}`.includes(expected)) throw new Error(`expected ${status}/${expected}, got ${result.status}: ${result.stdout}${result.stderr}`);
+}
+
+try {
+  template.scope.topic = "Example strategy question";
+  template.scope.audience = "Product team";
+  template.scope.time_horizon = "Last 12 months";
+  template.scope.research_questions = ["Which problem should the domain address?"];
+  template.scope.inclusion_criteria = ["Direct experience in scope"];
+  template.scope.exclusion_criteria = ["Untraceable reposts"];
+  template.ownership.downstream_owner = "yss-stage-decision";
+  template.search_log[0].channel = "Support records";
+  template.search_log[0].query_or_corpus = "failed approval workflow";
+  template.search_log[0].searched_at = "2026-09-03";
+  template.search_log[1].channel = "Support records";
+  template.search_log[1].query_or_corpus = "successful approval workflow";
+  template.search_log[1].searched_at = "2026-09-03";
+  template.evidence_items[0].source_class = "support";
+  template.evidence_items[0].source_ref = "support-case-001";
+  template.evidence_items[0].locator = "event-3";
+  template.evidence_items[0].observed_at = "2026-09-03";
+  template.evidence_items[0].evidence_date = "2026-08-30";
+  template.evidence_items[0].observation = "The approval stopped when the owner was missing.";
+  template.evidence_items[0].limitations = ["Single support case"];
+  template.claims[0].statement = "A missing owner can block the approval workflow.";
+  run(template, 0, "YSS research package valid");
+
+  const falseStrategyBackground = structuredClone(template);
+  falseStrategyBackground.claims[0].decision_bearing = false;
+  run(falseStrategyBackground, 1, "strategy claim kind must be decision-bearing");
+
+  const unsupported = structuredClone(template);
+  unsupported.claims[0].audit_status = "unsupported";
+  unsupported.claims[0].disposition = "publish";
+  run(unsupported, 1, "must use needs-deeper-research");
+
+  const unsupportedDecision = structuredClone(template);
+  unsupportedDecision.claims[0].audit_status = "unsupported";
+  unsupportedDecision.claims[0].disposition = "needs-deeper-research";
+  run(unsupportedDecision, 1, "decision-bearing and cannot remain unsupported");
+
+  const falseCounter = structuredClone(template);
+  falseCounter.claims[0].counter_signal_refs = ["search-001"];
+  run(falseCounter, 1, "counter-signal search must have result none-found");
+
+  const technicalWithoutPrimary = structuredClone(template);
+  technicalWithoutPrimary.profile = "technical-evidence";
+  technicalWithoutPrimary.claims[0].claim_kind = "technical-fact";
+  run(technicalWithoutPrimary, 1, "technical claim without primary evidence");
+
+  const leadOnly = structuredClone(template);
+  leadOnly.evidence_items[0].source_level = "lead-only";
+  run(leadOnly, 1, "uses lead-only evidence as support");
+
+  const unaudited = structuredClone(template);
+  unaudited.audit_summary.audited_claim_ids = [];
+  run(unaudited, 1, "must be a non-empty array");
+
+  process.stdout.write("YSS research scenarios passed (8)\n");
+} finally {
+  rmSync(directory, { recursive: true, force: true });
+}

package/template/.agents/skills/yss-resilience4j/SKILL.md

@@ -11,7 +11,7 @@ Use this skill for YSS Resilience4j 组件. Keep implementation grounded in the
 
 ## Source Index First
 
-- Backend source location is environment-specific; resolve it with `yss-source-index/references/source-location.md`.
+- Backend source location is environment-specific; resolve it with `yss-skill-source-index-refresh/references/source-location.md`.
 - Generated index: `references/source-index.md`
 - Component path hints: `yss-microservice-components/yss-component-resilience4j-starter`
 

package/template/.agents/skills/yss-resilience4j/references/source-index.md

@@ -5,7 +5,7 @@ Source commit: `38b556a5081e6c66c0c538cbc1ef839b19996ed3`
 Source worktree: `dirty`
 Indexed source root: resolved at refresh time; set `YSS_SOURCE_ROOT` to reproduce or refresh.
 
-This file is generated by `yss-source-index/scripts/refresh-yss-skill-index.mjs`. Do not hand-edit generated sections.
+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.
 

package/template/.agents/skills/yss-security-algorithm/SKILL.md

@@ -11,7 +11,7 @@ Use this skill for YSS 安全算法组件. Keep implementation grounded in the l
 
 ## Source Index First
 
-- Backend source location is environment-specific; resolve it with `yss-source-index/references/source-location.md`.
+- Backend source location is environment-specific; resolve it with `yss-skill-source-index-refresh/references/source-location.md`.
 - Generated index: `references/source-index.md`
 - Component path hints: `yss-microservice-components/yss-component-security-algorithm`
 

package/template/.agents/skills/yss-security-algorithm/references/source-index.md

@@ -5,7 +5,7 @@ Source commit: `38b556a5081e6c66c0c538cbc1ef839b19996ed3`
 Source worktree: `dirty`
 Indexed source root: resolved at refresh time; set `YSS_SOURCE_ROOT` to reproduce or refresh.
 
-This file is generated by `yss-source-index/scripts/refresh-yss-skill-index.mjs`. Do not hand-edit generated sections.
+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.
 

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

@@ -0,0 +1,63 @@
+---
+name: yss-skill-source-index-refresh
+description: Use when YSS backend component source or frontend UI documentation changes and skill source indexes need refreshing.
+---
+
+# YSS Skill Source Index Refresh
+
+Use this maintenance skill to keep YSS skills grounded in current source and documentation.
+
+中文说明：这个技能用于维护 YSS skills 的“源码索引”。后端组件库或前端文档入口变化后，运行脚本刷新引用文件。
+
+## Source Location Policy
+
+- Backend component source is environment-specific. Use `references/source-location.md` before trusting any generated path.
+- Preferred explicit setting: `YSS_SOURCE_ROOT=/absolute/path/to/yss-cloud-microservice`.
+- Frontend YSS UI components: `http://192.168.164.27:3200/components`
+- Frontend YSS UI hooks: `http://192.168.164.27:3200/hooks`
+- Frontend YSS UI skill docs: `http://192.168.164.27:3200/skills`
+
+## Refresh Workflow
+
+Run:
+
+```bash
+export YSS_SKILLS_ROOT="/path/to/.agents/skills"
+export YSS_SOURCE_ROOT="/path/to/yss-cloud-microservice"
+node "$YSS_SKILLS_ROOT/yss-skill-source-index-refresh/scripts/refresh-yss-skill-index.mjs"
+```
+
+Backend-only refreshes may set `YSS_REFRESH_FRONTEND=false` to avoid unrelated frontend timestamp 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 后续精准读取。
+
+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.
+
+## Output Contract
+
+Generated source indexes should contain:
+
+- source root and generated timestamp
+- exact source Git commit and 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
+- 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.
+
+中文说明：`SKILL.md` 保持短小，细节放到 `references/`，这是为了降低每次触发技能时的上下文成本。
+
+## After Refresh
+
+Validate the migrated Node helper with:
+
+```bash
+node --test "$YSS_SKILLS_ROOT/yss-skill-source-index-refresh/scripts/refresh-yss-skill-index.test.mjs"
+```

package/template/.agents/skills/yss-skill-source-index-refresh/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "YSS Skill Source Index Refresh"
+  short_description: "Locate sources and refresh YSS skill indexes"
+  default_prompt: "Refresh YSS skill indexes from yss-cloud-microservice and YSS UI docs."

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

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import { execFileSync } from "node:child_process";
+import { access, mkdir, 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-page-module-development":["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();

package/template/.agents/skills/yss-stage-decision/SKILL.md

@@ -17,7 +17,7 @@ description: 编排 Discovery 到 Spec 入口的阶段决策与 DDD 战略设计
 ## 执行顺序
 
 1. 读取 `yss-project.yaml`、`CONTEXT.md`、既有 Discovery/Spec、ADR 和父 Ticket/checkpoint。
-2. 分离事实、决策、假设、约束和未决项；技术事实走 `research`，市场/竞品事实走 `competitive-intelligence`。
+2. 分离事实、决策、假设、约束和未决项；技术事实走 `yss-research` 的 `technical-evidence`，领域边界、业务规则、MVP、非目标、成功标准或阶段推进依据等决策证据走 `strategy-evidence`，市场/竞品事实走 `competitive-intelligence`。
 3. 从业务场景、事件、规则、责任人和失败路径识别子域及限界上下文，不从数据库表或调用链直接反推边界。
 4. 为每个上下文建立本地统一语言；为跨上下文关系记录语义上游/下游、业务决策权、技术传输方向和翻译责任。
 5. 记录核心领域概念候选，不提前锁定 Entity 或 Aggregate。
@@ -31,6 +31,7 @@ description: 编排 Discovery 到 Spec 入口的阶段决策与 DDD 战略设计
 ## 产物与批准
 
 - DDD 资产是事实源，阶段决策包只通过 `domain_strategy_ref` 引用它们。
+- 进入 `gate.domain-strategy-approved` 或 `gate.stage-decision-package-approved` 的外部决策证据必须引用通过校验的 `yss-research` `evidence-audited` 研究包；研究包只提供证据，不得直接修改本技能资产或批准门禁。
 - `stage_decision_package` 必须经过 `draft → ready-for-human → approved`；起草者不得自签。
 - 建议门禁为 `gate.domain-strategy-approved` 和 `gate.stage-decision-package-approved`，实际状态由 `yss-product-lifecycle` 维护；阶段包批准引用必须通过 `scripts/verify-approval-record`，不得用不可读路径或聊天确认替代。
 - 下游只能消费批准且版本当前的包；发现语义冲突返回 `drift` / `new_impacts`，不得静默修改上游。

package/template/.agents/skills/yss-ui/SKILL.md

@@ -30,7 +30,7 @@ pnpm why vue @yss-ui/components @yss-ui/hooks ant-design-vue vxe-table
 
 记录实际版本、lockfile、验证命令和环境阻塞。完整策略见 `references/antdv-compatibility.md`。
 
-产品设计使用的 Ant Design v6 视觉/token 语义，不等于 Vue 生产实现 API。生产代码必须使用项目安装的 Ant Design Vue 4.x API，禁止复制 React hook、props 或组件写法。`yss-antd-design` 与 `@ant-design/cli` 只用于原型设计构建，进入本技能后不得再调用。
+产品设计使用的 Ant Design v6 视觉/token 语义，不等于 Vue 生产实现 API。生产代码必须使用项目安装的 Ant Design Vue 4.x API，禁止复制 React hook、props 或组件写法。`yss-antd-design` 与 `@ant-design/cli` 只用于相关 H2 React/AntD 原型；原型阶段不得调用本技能。只有进入前端实现计划、已批准切片的生产实现或实现还原验证后，才从目标 lockfile、类型、本地文档和既有用法取得真实组件事实。
 
 ## 3. 组件选型门禁
 
@@ -168,3 +168,4 @@ verification: pnpm type-check
 - 禁止把 React Ant Design v6 API 写入 Vue 生产代码。
 - 禁止引用不存在的 skill、未验证 Demo 或未冻结 API 契约。
 - 禁止省略错误、权限、空态、焦点和验证证据。
+- 禁止在原型阶段调用本技能，或用生产组件实现冒充原型资产。

package/template/.agents/skills/yss-ui/assets/docs/guide/llms.md

@@ -110,67 +110,6 @@ Always reference the YSS UI documentation when working with components:
 
 ---
 
-### Gemini CLI
-
-在 Gemini CLI 中，可以通过 `--context` 参数或在 `.gemini/config.json` 中指定 LLMs.txt 文件路径。
-
-**使用方法 1：命令行参数**
-
-```bash
-gemini --context http://192.168.164.27:3200/llms-full.txt "如何使用 YTable 组件？"
-```
-
-**使用方法 2：配置文件**
-
-在项目根目录创建 `.gemini/config.json`：
-
-```json
-{
-  "context": [
-    "http://192.168.164.27:3200/llms-full.txt"
-  ]
-}
-```
-
-<a href="https://ai.google.dev/gemini-api/docs" target="_blank">详细了解 Gemini CLI 上下文配置</a>
-
----
-
-### Antigravity
-
-Antigravity（Google Gemini 官方 AI 编程助手）可以通过 `read_url_content` 工具直接读取在线文档。
-
-**方式 1：全局规则配置（强力推荐）** 🚀
-
-配置 `~/.gemini/GEMINI.md`，从根本上教会 AI "文档优先"，无需每次重复提示。
-
-```markdown
-## 核心原则：文档优先
-在回答关于 YSS UI 问题时，必须优先读取以下文档：
-http://192.168.164.27:3200/llms-full.txt
-```
-
-**方式 2：项目 README 配置**
-
-在项目根目录 `README.md` 中添加文档链接，Antigravity 读取项目概况时会自动发现。
-
-```markdown
-## 相关文档
-- YSS UI: http://192.168.164.27:3200/llms-full.txt
-```
-
-**方式 3：对话直接引用**
-
-临时询问时，直接在对话中粘贴 URL：
-
-```
-参考文档 http://192.168.164.27:3200/llms-full.txt，帮我写一个表格。
-```
-
-> **提示**：Antigravity 不支持类似 Cursor `@Docs` 的配置，主要依靠上下文理解和工具调用。
-
----
-
 ### Trae
 
 在 Trae 中，将 LLMs.txt 文件放入项目的 knowledge sources 并在设置里开启引用。

package/template/.agents/skills/yss-up-springboot3/SKILL.md

@@ -21,7 +21,7 @@ Use this skill for YSS backend upgrade analysis and migration tasks around Sprin
 2. Check for Jakarta namespace changes (`javax.servlet`, `javax.validation`, `javax.annotation`, JPA APIs, and related imports).
 3. Check Spring Security configuration style, deprecated adapters, authorization server dependencies, and filter registration behavior.
 4. Check component-specific integration by loading specialist skills such as `yss-mybatis`, `yss-dto`, `yss-cache`, `yss-audit-log`, `yss-excel-mvc`, or `yss-jdbc`.
-5. Prefer source-backed evidence from the local workspace or a source root resolved via `yss-source-index/references/source-location.md` before recommending code changes.
+5. Prefer source-backed evidence from the local workspace or a source root resolved via `yss-skill-source-index-refresh/references/source-location.md` before recommending code changes.
 6. Produce an upgrade checklist or patch with explicit compatibility risks and verification commands.
 
 ## Common Checks

package/template/.agents/skills/yss-userinfo/SKILL.md

@@ -11,7 +11,7 @@ Use this skill for YSS 用户信息组件. Keep implementation grounded in the l
 
 ## Source Index First
 
-- Backend source location is environment-specific; resolve it with `yss-source-index/references/source-location.md`.
+- Backend source location is environment-specific; resolve it with `yss-skill-source-index-refresh/references/source-location.md`.
 - Generated index: `references/source-index.md`
 - Component path hints: `yss-microservice-components/yss-component-userinfo-starter`
 

package/template/.agents/skills/yss-userinfo/references/source-index.md

@@ -5,7 +5,7 @@ Source commit: `38b556a5081e6c66c0c538cbc1ef839b19996ed3`
 Source worktree: `dirty`
 Indexed source root: resolved at refresh time; set `YSS_SOURCE_ROOT` to reproduce or refresh.
 
-This file is generated by `yss-source-index/scripts/refresh-yss-skill-index.mjs`. Do not hand-edit generated sections.
+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.
 

package/template/.agents/skills/yss-validation/SKILL.md

@@ -11,7 +11,7 @@ Use this skill for YSS 校验组件. Keep implementation grounded in the local p
 
 ## Source Index First
 
-- Backend source location is environment-specific; resolve it with `yss-source-index/references/source-location.md`.
+- Backend source location is environment-specific; resolve it with `yss-skill-source-index-refresh/references/source-location.md`.
 - Generated index: `references/source-index.md`
 - Component path hints: `yss-microservice-components/yss-component-validation-engine-parent`, `yss-microservice-components/yss-component-validation-jsr303`
 

package/template/.agents/skills/yss-validation/references/source-index.md

@@ -5,7 +5,7 @@ Source commit: `38b556a5081e6c66c0c538cbc1ef839b19996ed3`
 Source worktree: `dirty`
 Indexed source root: resolved at refresh time; set `YSS_SOURCE_ROOT` to reproduce or refresh.
 
-This file is generated by `yss-source-index/scripts/refresh-yss-skill-index.mjs`. Do not hand-edit generated sections.
+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.
 

package/template/.agents/skills/yss-web-controller/SKILL.md

@@ -16,16 +16,17 @@ description: Use when generating or refactoring YSS Web Adapter Controllers, req
 ## 不适用
 
 - 用户只是要新增一个手写复杂接口，不一定要用脚本。
-- 用户还没有稳定的领域模型或 metadata，先补 `yss-domain` 并准备完整的 metadata 输入。
+- 用户还没有稳定的 Application Service、冻结 OpenAPI 或 metadata，先回 实现合同编译器 补 `yss-application` / `yss-domain` 和相应合同输入。
 
 ## 优先流程
 
-1. 先确认冻结 OpenAPI、批准的 Web generation contract、Application Service 接口、metadata、基础包、模块名、领域 segment 和 web 落盘目录；合同中的 `base_package`、`module_name`、`domain_segment` 必须与 CLI 一致。
-2. 涉及 DTO / VO / CMD / Query POJO 样板代码时，加载并遵守 `lombok`。
-3. 涉及 Domain / Application Result 到 VO / DTO 或 CMD / Query 到输入模型的转换时，加载并遵守 `mapstruct`。
-4. 运行 `node scripts/generate_controller.mjs`。
-5. 生成后检查路径、命名、返回值包装、Application Service 引用、`@Valid`、Lombok 注解和 MapStruct WebConvertor 是否对齐项目。
-6. 对复杂接口做少量手工修正，不在 skill 中承诺自动覆盖全部业务逻辑。
+1. 先确认冻结 OpenAPI、批准且版本当前的 Web generation contract schema v2、Application Service 接口、metadata、基础包、模块名、领域 segment 和 web 落盘目录；合同必须绑定 Slice `contract_id` / `contract_version` / `slice_id`、`yss-dto` wire profile 引用与 digest、允许写路径、证据与验证命令。
+2. 加载并遵守 `yss-dto` 与 `yss-validation`；错误映射影响命中时再加载 `yss-exception`。
+3. 涉及 DTO / VO / CMD / Query POJO 样板代码时，加载并遵守 `lombok`。
+4. 涉及 Domain / Application Result 到 VO / DTO 或 CMD / Query 到输入模型的转换时，加载并遵守 `mapstruct`。
+5. 运行 `node scripts/generate_controller.mjs`。
+6. 生成后检查路径、命名、返回值包装、Application Service 引用、`@Valid`、Lombok 注解和 MapStruct WebConvertor 是否对齐项目。
+7. 对复杂接口做少量手工修正，不在 skill 中承诺自动覆盖全部业务逻辑。
 
 ## 推荐命令
 
@@ -33,6 +34,8 @@ description: Use when generating or refactoring YSS Web Adapter Controllers, req
 node scripts/generate_controller.mjs \
   --metadata-file /path/metadata.json \
   --contract-file /path/approved-web-generation-contract.json \
+  --dto-wire-profile-file /path/to/yss-dto/references/openapi-wire-profile.yaml \
+  --scaffold-manifest-file /path/service/.yss/scaffold-generation.json \
   --base-package com.yss.demo \
   --module-name demo \
   --domain-segment example \
@@ -53,18 +56,21 @@ node scripts/generate_controller.mjs \
 ## 约束
 
 - 生成代码只依赖既有 Application Service；读写操作都禁止绕过 Application。复杂查询经 Application Query Port 接入 Infrastructure。
-- 返回结构保持项目既有 `SingleResult`、`PageResult`、`MultiResult` 体系。
+- 返回包装类、分页默认值、允许字段与 `PageResult.of(...)` 参数语义必须消费合同绑定的 `yss-dto/references/openapi-wire-profile.yaml`；Web skill 不复制或自行维护第二套协议。
 - DTO / VO / CMD / Query 默认用 Lombok 处理 getter/setter、constructor、builder 和日志样板；不要在 Controller 内部类或非约定包临时定义主要 DTO / VO。
 - `WebConvertor` 使用 `@Mapper(componentModel = "spring")` 和构造器注入；禁止静态 `INSTANCE`、在 Controller / Application 中大段手写字段赋值、使用 `BeanUtils.copyProperties` 或反射式通用拷贝。
 - HTTP Request 不继承会暴露内部协作字段的 `PageQuery`；只生成冻结 OpenAPI allowlist 字段，禁止把 `offset`、`needTotalCount`、`tempTotalCount` 变成客户端输入。
+- `fields.<table>.pagination` 必须显式列出 `yss-dto` wire profile 允许暴露的字段子集；模板不得无条件生成字段或自行定义默认值。
 - 先跑脚本，再按项目规范做少量手调。
 - `javax` / `jakarta` validation namespace 必须来自工程基线，不得按记忆选择。
 - 若用户只是要改单个 Controller，先看现有代码，不要盲覆盖整个目录。
-- 脚本是 initialize-only；写入前先规划全部目标，任一目标已存在或传入 `--force` 时整体返回 `unsupported` 且不得留下部分文件。旧项目迁移不属于该生成器。
+- 脚本是 initialize-only；写入前先规划全部目标并校验 `allowed_write_paths`，任一目标已存在或传入 `--force` 时整体返回 `unsupported`。落盘使用排他创建和失败回滚，不得留下部分文件；旧项目迁移不属于该生成器。
+- `integration_mode=existing-project` 保留已登记工程的 Boot 2/Boot 3 能力；`integration_mode=scaffold-v2` 必须提供 `--scaffold-manifest-file`，且 Manifest 已达到 `empty-scaffold-verified`，Profile、基础包和标准 Web module 路径全部一致。
 
 ## 按需读取
 
 - 分层开发规范：`references/web-adapter-layer-guide.md`
+- Web 生成合同 schema：`references/web-generation-contract.schema.json`
 - 生成脚本：`scripts/generate_controller.mjs`
 - Controller 模板：`assets/templates/Controller.java.template`
 - Convertor 模板：`assets/templates/WebConvertor.java.template`
@@ -73,7 +79,7 @@ node scripts/generate_controller.mjs \
 
 ## 阶段 7 合同
 
-- 只消费已批准合同和冻结 OpenAPI/no-impact record；不得用 Controller 或半成品 backend 反向定义产品契约。
+- 只消费已批准且当前的 schema v2 Web generation contract 和冻结 OpenAPI/no-impact record；schema v1 为 `unsupported`，不得自动升级，也不得用 Controller 或半成品 backend 反向定义产品契约。
 - DTO/VO/WebConvertor 机械骨架可用 `controlled-generation`；权限、错误映射、校验语义和接口行为必须使用 `behavior-tdd`。
 - 写入必须位于合同 `allowed_write_paths`，并提供 Controller、DTO/VO、WebConvertor、契约/API 测试和实际验证结果。
-- 按统一 `YSS Skill Execution Result` 返回偏离与新增影响；出现新 API/schema、权限或响应包装变化时暂停并回到 Router/生命周期。
+- 按统一 `YSS Skill Execution Result` 返回偏离与新增影响；出现新 API/schema、权限或响应包装变化时暂停并回到 实现合同编译器/生命周期。

package/template/.agents/skills/yss-web-controller/agents/openai.yaml

@@ -1,5 +1,5 @@
 version: 1
 interface:
   display_name: "YSS Web Controller"
-  short_description: "Web Controller、DTO、VO 与响应封装规范"
-  default_prompt: "Use $yss-web-controller to generate or refactor a YSS REST controller, request DTO, and response VO."
+  short_description: "按批准 Slice/Web 合同生成 Controller、Wire DTO 与 Convertor"
+  default_prompt: "Use $yss-web-controller with an approved schema v2 Web generation contract, frozen OpenAPI, stable Application interfaces, and allowed write paths to generate YSS REST adapters atomically."