create-yss-spec 3.4.7 → 3.4.9

package/template/.cursor/skills/yss-ddd-scaffold-generator/scripts/run_first_slice_verification.mjs

@@ -8,33 +8,15 @@ import { fileURLToPath } from "node:url";
 
 import { run as runScaffoldVerification } from "./run_scaffold_verification.mjs";
 import { assertArchitectureAgreement } from "../../../../scripts/lib/backend-architecture.mjs";
-import { mvcFirstSliceProfile } from "../../../../scripts/lib/first-slice-architecture.mjs";
+import { inspectSliceContract } from "../../../../scripts/lib/slice-execution-preflight.mjs";
+import { selectSliceWorkUnit } from "../../../../scripts/lib/slice-contract.mjs";
+import { verifyFirstSliceTests } from "../../../../scripts/lib/first-slice-tests.mjs";
+import { inspectFirstSliceArtifacts } from "../../../../scripts/lib/first-slice-artifacts.mjs";
 
 const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
 const REPOSITORY_ROOT = path.resolve(SCRIPT_DIR, "../../../..");
 const REQUIRED_SKILLS = ["yss-domain", "yss-application", "yss-repository", "yss-mybatis", "yss-web-controller", "yss-dto", "yss-exception", "yss-validation", "mapstruct", "lombok", "alibaba-java-code-style"];
 const REQUIRED_LAYERS = ["domain", "application", "infrastructure", "web"];
-const ARTIFACT_CHECKS = [
-  ["domain-model", /-domain\/src\/main\/java\/.+\/domain\/.+\/model\/.+\.java$/],
-  ["domain-gateway", /-domain\/src\/main\/java\/.+\/domain\/.+\/gateway\/.+Gateway\.java$/],
-  ["domain-behavior-test", /-domain\/src\/test\/java\/.+(?:Test|Tests)\.java$/],
-  ["application-command-or-query", /-application\/src\/main\/java\/.+\/application\/(?:command|query)\/.+\.java$/],
-  ["application-result", /-application\/src\/main\/java\/.+\/application\/result\/.+Result\.java$/],
-  ["application-service", /-application\/src\/main\/java\/.+\/application\/service\/.+Service\.java$/],
-  ["application-service-implementation", /-application\/src\/main\/java\/.+\/application\/service\/impl\/.+ServiceImpl\.java$/],
-  ["application-behavior-test", /-application\/src\/test\/java\/.+(?:Test|Tests)\.java$/],
-  ["infrastructure-po", /-infrastructure\/src\/main\/java\/.+\/infrastructure\/persistence\/po\/.+PO\.java$/],
-  ["infrastructure-repository", /-infrastructure\/src\/main\/java\/.+\/infrastructure\/persistence\/repository\/.+Repository\.java$/],
-  ["infrastructure-convertor", /-infrastructure\/src\/main\/java\/.+\/infrastructure\/persistence\/convertor\/.+Convertor\.java$/],
-  ["infrastructure-gateway-implementation", /-infrastructure\/src\/main\/java\/.+\/infrastructure\/persistence\/gateway\/.+GatewayImpl\.java$/],
-  ["infrastructure-query-adapter", /-infrastructure\/src\/main\/java\/.+\/infrastructure\/query\/adapter\/.+QueryAdapter\.java$/],
-  ["infrastructure-integration-test", /-infrastructure\/src\/test\/java\/.+(?:Test|Tests)\.java$/],
-  ["web-controller", /-adapter\/.+-web\/src\/main\/java\/.+\/rest\/.+Controller\.java$/],
-  ["web-convertor", /-adapter\/.+-web\/src\/main\/java\/.+\/rest\/convertor\/.+WebConvertor\.java$/],
-  ["web-request", /-adapter\/.+-web\/src\/main\/java\/.+\/rest\/dto\/request\/.+Request\.java$/],
-  ["web-response", /-adapter\/.+-web\/src\/main\/java\/.+\/rest\/dto\/response\/.+Response\.java$/],
-  ["web-contract-test", /-adapter\/.+-web\/src\/test\/java\/.+(?:Test|Tests)\.java$/]
-];
 
 const isoNow = () => new Date().toISOString();
 const sha256 = (content) => createHash("sha256").update(content).digest("hex");
@@ -62,59 +44,7 @@ async function writeJsonAtomic(target, value) {
   await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, "utf8");
   await rename(temporary, target);
 }
-function invalidContractReasons(contract, requiredSkills = REQUIRED_SKILLS, requiredLayers = REQUIRED_LAYERS) {
-  const reasons = [];
-  if (contract.schema_version !== 2) reasons.push("slice-contract-schema");
-  if (contract.status !== "approved") reasons.push("slice-contract-not-approved");
-  for (const field of ["contract_id", "contract_version", "slice_id"]) if (contract[field] === undefined || contract[field] === null || contract[field] === "") reasons.push(`slice-contract-${field}-missing`);
-  if (contract.readiness?.blockers?.length) reasons.push("slice-contract-has-blockers");
-  if (contract.readiness?.stale_inputs?.length) reasons.push("slice-contract-has-stale-inputs");
-  const actualSkills = new Set([...(contract.common?.required_skills ?? []), ...(contract.backend?.required_skills ?? [])]);
-  for (const skill of requiredSkills) if (!actualSkills.has(skill)) reasons.push(`required-skill-missing:${skill}`);
-  const actualLayers = new Set(contract.backend?.affected_layers ?? []);
-  for (const layer of requiredLayers) if (!actualLayers.has(layer)) reasons.push(`required-layer-missing:${layer}`);
-  if (!Array.isArray(contract.work_units) || !contract.work_units.length) reasons.push("slice-contract-work-units-missing");
-  else for (const [index, unit] of contract.work_units.entries()) {
-    const id = unit.id || `index-${index}`;
-    if (unit.contract_id !== contract.contract_id) reasons.push(`work-unit-contract-id-mismatch:${id}`);
-    if (unit.contract_version !== contract.contract_version) reasons.push(`work-unit-contract-version-mismatch:${id}`);
-    if (!unit.work_unit?.primary_skill) reasons.push(`work-unit-primary-skill-missing:${id}`);
-  }
-  return reasons;
-}
-async function downstreamDrift(manifest, requiredSkills = REQUIRED_SKILLS) {
-  const drift = [];
-  const recordedSkills = manifest.readiness?.downstream_skills ?? {};
-  for (const skill of requiredSkills) {
-    const expected = recordedSkills[skill];
-    if (typeof expected !== "string" || !/^[a-f0-9]{64}$/.test(expected)) {
-      drift.push(`${skill}:digest-missing`);
-      continue;
-    }
-    const root = path.join(REPOSITORY_ROOT, ".agents", "skills", skill);
-    if (!await isFile(path.join(root, "SKILL.md"))) drift.push(`${skill}:unavailable`);
-    else if (await treeDigest(root) !== expected) drift.push(`${skill}:digest-mismatch`);
-  }
-  const contracts = manifest.readiness?.contracts ?? {};
-  const contractFiles = {
-    compiler_contract: path.join(REPOSITORY_ROOT, ".agents", "skills", "yss-implementation-contract-compiler", "references", "compiler-contract.yaml")
-  };
-  if (manifest.architecture_family === "layered-mvc") {
-    contractFiles.architecture_profiles = path.join(REPOSITORY_ROOT, "docs/agents/backend-architecture-profiles.md");
-  } else contractFiles.engineering_baseline = path.join(REPOSITORY_ROOT, ".agents", "skills", "yss-ddd-scaffold-generator", "references", "engineering-baseline.md");
-  for (const [name, target] of Object.entries(contractFiles)) {
-    const expected = contracts[name];
-    if (typeof expected !== "string" || !/^[a-f0-9]{64}$/.test(expected)) {
-      drift.push(`${name}:digest-missing`);
-      continue;
-    }
-    if (!await isFile(target)) drift.push(`${name}:unavailable`);
-    else if (sha256(await readFile(target)) !== expected) drift.push(`${name}:digest-mismatch`);
-  }
-  return drift;
-}
-
-export async function runFirstSliceVerification(projectRoot, evidenceDir, sliceContractFile, environment = process.env) {
+export async function runFirstSliceVerification(projectRoot, evidenceDir, sliceContractFile, environment = process.env, options = {}) {
   projectRoot = path.resolve(projectRoot);
   evidenceDir = path.resolve(evidenceDir);
   sliceContractFile = path.resolve(sliceContractFile);
@@ -123,20 +53,33 @@ export async function runFirstSliceVerification(projectRoot, evidenceDir, sliceC
   if (!await isFile(manifestPath)) throw new Error(`missing scaffold manifest: ${manifestPath}`);
   if (!await isFile(sliceContractFile)) throw new Error(`missing Slice Implementation Contract: ${sliceContractFile}`);
   const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
-  const contract = JSON.parse(await readFile(sliceContractFile, "utf8"));
+  const contractRoot = path.resolve(options.contractRoot || projectRoot);
+  let contract, preflight;
+  try {
+    const loaded = inspectSliceContract(path.relative(contractRoot, sliceContractFile), {
+      root: contractRoot, approval_ref: options.approvalRef, work_unit_id: options.workUnit
+    });
+    preflight = loaded.report;
+    contract = selectSliceWorkUnit(loaded.contract, options.workUnit);
+  } catch (error) {
+    preflight = { execution_allowed: false, blockers: [error.message] };
+    contract = {};
+  }
   if (manifest.platform_verification === "candidate") throw new Error("backend-platform: candidate scaffold cannot become first-slice-verified");
-  const adapter = manifest.architecture_family === "layered-mvc" ? mvcFirstSliceProfile(manifest.architecture_identity ?? {}) : { skills: REQUIRED_SKILLS, layers: REQUIRED_LAYERS, artifacts: ARTIFACT_CHECKS };
-  const contractFailures = invalidContractReasons(contract, adapter.skills, adapter.layers);
+  const contractFailures = [...preflight.blockers];
+  if (!preflight.execution_allowed) contractFailures.push("slice-execution-not-authorized");
+  if (!(contract.common?.project_roots || []).some(ref => path.resolve(contractRoot, ref) === projectRoot)) contractFailures.push("slice-project-root-mismatch");
   try {
     const identity = contract.architecture_identity ?? contract.resolution?.architecture_identity;
-    assertArchitectureAgreement(identity, { manifest });
+    if (identity?.source_kind !== "existing-registration") assertArchitectureAgreement(identity, { manifest });
     for (const unit of contract.work_units ?? []) assertArchitectureAgreement(identity, { work_unit: unit.architecture_identity });
   } catch (error) { contractFailures.push(`architecture-identity:${error.message}`); }
   if (![2, 3, 4].includes(manifest.schema_version) || manifest.completion_level !== "empty-scaffold-verified") contractFailures.push("scaffold-not-empty-scaffold-verified");
   if (manifest.schema_version === 3 && manifest.legacy_reconciliation?.status !== "approved") contractFailures.push("legacy-scaffold-reconciliation-required");
-  const projectFiles = await files(projectRoot);
-  const missingArtifacts = adapter.artifacts.filter(([, pattern]) => !projectFiles.some((file) => pattern.test(file))).map(([name]) => name);
-  const skillDrift = await downstreamDrift(manifest, adapter.skills);
+  const artifacts = inspectFirstSliceArtifacts(contract, projectRoot);
+  const missingArtifacts = artifacts.failures;
+  // Generation-time Skill hashes are provenance. Current authority was checked by execution preflight.
+  const skillDrift = [];
   if (contractFailures.length || missingArtifacts.length || skillDrift.length) {
     const report = { verification_mode: "first-slice", project_root: projectRoot, slice_contract_ref: sliceContractFile, scaffold_manifest_ref: manifestPath, generated_at: isoNow(), status: "failed", completion_level: manifest.completion_level, contract_failures: contractFailures, missing_artifacts: missingArtifacts, downstream_skill_drift: skillDrift, commands: [] };
     await writeJsonAtomic(reportPath, report);
@@ -144,9 +87,15 @@ export async function runFirstSliceVerification(projectRoot, evidenceDir, sliceC
   }
 
   const mavenEvidence = path.join(evidenceDir, "maven");
-  const wrapper = await runScaffoldVerification(projectRoot, mavenEvidence, environment, { firstSlice: true });
-  const passed = wrapper.status === "passed";
-  const report = { verification_mode: "first-slice", project_root: projectRoot, slice_contract_ref: sliceContractFile, scaffold_manifest_ref: manifestPath, generated_at: isoNow(), status: passed ? "passed" : "failed", failure_category: wrapper.failure_category, completion_level: passed ? "first-slice-verified" : manifest.completion_level, contract_failures: [], missing_artifacts: [], downstream_skill_drift: [], commands: wrapper.commands };
+  const startedAt = Date.now();
+  const wrapper = await runScaffoldVerification(projectRoot, mavenEvidence, environment, { firstSlice: true, systemProperties: artifacts.properties });
+  const mvc = manifest.architecture_family === "layered-mvc";
+  const tests = wrapper.status === "passed" ? verifyFirstSliceTests(contract, projectRoot, startedAt, {
+    module: `${manifest.project_name}-${mvc ? "server" : "bootstrap"}`,
+    type: `${manifest.base_package}.${mvc ? "architecture.LayeredMvcArchitectureTest" : "ArchitectureRulesTest"}`
+  }) : { status: "not-executed", failures: [], evidence: [] };
+  const passed = wrapper.status === "passed" && tests.status === "passed";
+  const report = { verification_mode: "first-slice", project_root: projectRoot, slice_contract_ref: sliceContractFile, scaffold_manifest_ref: manifestPath, generated_at: isoNow(), status: passed ? "passed" : "failed", test_execution: tests, failure_category: wrapper.failure_category || (tests.status === "failed" ? "first-slice-tests" : null), completion_level: passed ? "first-slice-verified" : manifest.completion_level, contract_failures: [], missing_artifacts: [], downstream_skill_drift: [], commands: wrapper.commands };
   await writeJsonAtomic(reportPath, report);
   if (passed) {
     manifest.completion_level = "first-slice-verified";
@@ -162,7 +111,7 @@ function parseArgs(argv) {
   const result = {};
   for (let index = 0; index < argv.length; index += 2) {
     const flag = argv[index], value = argv[index + 1];
-    if (!["--project-root", "--evidence-dir", "--slice-contract-file"].includes(flag) || !value) throw new Error("usage: run_first_slice_verification.mjs --project-root DIR --evidence-dir DIR --slice-contract-file FILE");
+    if (!["--project-root", "--evidence-dir", "--slice-contract-file", "--contract-root", "--approval-ref", "--work-unit"].includes(flag) || !value) throw new Error("usage: run_first_slice_verification.mjs --project-root DIR --evidence-dir DIR --slice-contract-file FILE");
     result[flag.slice(2).replaceAll(/-([a-z])/g, (_, letter) => letter.toUpperCase())] = value;
   }
   if (!result.projectRoot || !result.evidenceDir || !result.sliceContractFile) throw new Error("project root, evidence dir, and slice contract file are required");
@@ -172,7 +121,7 @@ function parseArgs(argv) {
 async function main() {
   try {
     const args = parseArgs(process.argv.slice(2));
-    const report = await runFirstSliceVerification(args.projectRoot, args.evidenceDir, args.sliceContractFile);
+    const report = await runFirstSliceVerification(args.projectRoot, args.evidenceDir, args.sliceContractFile, process.env, args);
     process.stdout.write(`${report.status}: ${path.join(path.resolve(args.evidenceDir), "first-slice-verification.json")}\n`);
     return report.status === "passed" ? 0 : 1;
   } catch (error) {

package/template/.cursor/skills/yss-ddd-scaffold-generator/scripts/run_scaffold_verification.mjs

@@ -62,7 +62,7 @@ function validateManifest(manifest) {
   if (manifest.schema_version === 4 ? manifest.current_version !== true : manifest.current_version !== manifest.contract_version) throw new Error("脚手架生成元数据清单不是当前合同版本");
   if (JSON.stringify(manifest.verification_commands) !== JSON.stringify(COMMANDS)) throw new Error("脚手架生成元数据清单验证命令不符合固定合同");
 }
-export async function run(projectRoot, evidenceDir, environment = process.env, { timeoutMs = 0, signal, platformOptions = {}, firstSlice = false } = {}) {
+export async function run(projectRoot, evidenceDir, environment = process.env, { timeoutMs = 0, signal, platformOptions = {}, firstSlice = false, systemProperties = {} } = {}) {
   const wrapper = path.join(projectRoot, "mvnw"), manifestPath = path.join(projectRoot, ".yss", "scaffold-generation.json");
   if (!await isFile(wrapper)) throw new Error(`项目根目录缺少 Maven wrapper: ${wrapper}`);
   if (!await isFile(manifestPath)) throw new Error(`项目根目录缺少脚手架生成元数据清单: ${manifestPath}`);
@@ -114,13 +114,14 @@ export async function run(projectRoot, evidenceDir, environment = process.env, {
     const stderrPath = path.join(evidenceDir, `mvnw-${phase}.stderr.log`);
     const startedAt = isoNow();
     const started = process.hrtime.bigint();
-    const execution = await runCommand(wrapper, [phase], { cwd: projectRoot, env: environment, timeoutMs, signal, stdoutFile: stdoutPath, stderrFile: stderrPath, secrets: [environment.MAVEN_REPO_USERNAME, environment.MAVEN_REPO_PASSWORD], progress: true });
+    const args = [phase, ...Object.entries(systemProperties).map(([key, value]) => `-D${key}=${value}`)];
+    const execution = await runCommand(wrapper, args, { cwd: projectRoot, env: environment, timeoutMs, signal, stdoutFile: stdoutPath, stderrFile: stderrPath, secrets: [environment.MAVEN_REPO_USERNAME, environment.MAVEN_REPO_PASSWORD], progress: true });
     const outcome = { ...execution, exitCode: execution.status };
     const durationMs = Number(process.hrtime.bigint() - started) / 1e6;
     await writeText(stdoutPath, redactSecrets(outcome.stdout, environment));
     await writeText(stderrPath, redactSecrets(outcome.stderr, environment));
     commands.push({
-      command: `./mvnw ${phase}`,
+      command: `./mvnw ${args.join(" ")}`,
       phase,
       exit_code: outcome.exitCode,
       failure_category: outcome.termination || classifyFailure(phase, outcome),

package/template/.cursor/skills/yss-design-system/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yss-design-system
-description: Use when YSS 产品设计系统与 Ant Design 企业级 UI 风格基线。涉及页面设计、原型评审、UI 实现、组件选型、主题 token、颜色排版间距、响应式验收、Ant Design/YSS UI 风格一致性、docs/design/design.md 更新或从外部设计系统引入规范时必须使用。
+description: 建立或核验 YSS 设计系统、主题 Token 与页面视觉一致性；用于设计规范变更、原型评审及按当前设计基线验收。
 ---
 
 # YSS Design System
@@ -18,7 +18,7 @@ description: Use when YSS 产品设计系统与 Ant Design 企业级 UI 风格
 - Codex `$design-qa` 项目对照：`references/design-qa-theme.md`，不替代官方 `design-qa` 流程，也不改上游插件正文。
 - 原型阶段合同：`yss-prototype-stage`，用于统一 H1/H2 原型资产和浏览器验证证据。H1/H2 默认使用项目 Token 驱动的 HTML/CSS/JavaScript 离线原型。
 
-如果只需要快速判断，先读本文件。若要写 UI 规范、实现页面、评审设计或调整 Token，必须按 `DESIGN.md` → `docs/design/design.md` → `docs/design/tokens/*` 顺序读取；若要执行评审或实现检查，再读 `references/design-system.md`。
+如果只需要快速判断，先读本文件。若要写 UI 规范、实现页面、评审设计或调整 Token，必须按 `DESIGN.md` → `docs/design/design.md` 顺序读取，再按当前主题、密度与输出表面选择对应 Token 文件，不全量预读所有主题；若要执行评审或实现检查，再读 `references/design-system.md`。
 
 ## 使用流程
 

package/template/.cursor/skills/yss-domain/SKILL.md

@@ -1,19 +1,21 @@
 ---
 name: yss-domain
-description: 用于构建或重构 YSS 领域层代码。当用户要求设计聚合、Entity、Domain Gateway、领域规则、状态流转或先做领域建模再补持久层时调用。
+description: 按已批准的 DDD 技术设计实现或重构领域行为、不变量、状态机与 Gateway；不负责起草领域设计。
 ---
 
 # yss-domain
 
 这是一个领域实现 skill。核心目标是消费已批准的战术模型，将领域行为落实为代码；`yss-technical-design` 组织 DDD 分支，由 `yss-tactical-design` 设计、`yss-product-lifecycle` 维护批准。
 
+既有工程先读取 `references/existing-project.md`，按登记的职责和批准边界审计或整改；只读审计不要求批准 Slice。
+
 本 skill 在新脚手架链路只支持 `domain-driven` / `target-domain-model`。`layered-mvc-service` 与 `mvc-data-analysis-v1` 是独立 MVC Profile，不是失败的 DDD 工程；它们不加载本 skill，也不生成 Domain Gateway。既有旧架构不在本链路内迁移。
 
 ## 何时使用
 
-- 用户要求先做 Domain、先抽象实体或聚合。
-- 用户要补 `Entity`、`Gateway`、领域规则或状态机。
-- 用户给出页面流程、业务规则、DDL，希望先沉淀领域模型。
+- 当前已批准的 DDD Slice Contract 要求实现或修复领域行为、不变量或状态机。
+- 在既有已确认领域边界内重构 Entity、Value Object、Domain Event 或 Gateway。
+- 需要从需求、页面或 DDL 决定聚合及领域边界时，回交 `yss-technical-design` / `yss-tactical-design`，不先写领域代码。
 
 ## 不适用
 
@@ -36,17 +38,27 @@ description: 用于构建或重构 YSS 领域层代码。当用户要求设计
 
 ## 建模约束
 
+<a id="domain.dependencies"></a>
+<!-- yss-rule {"id":"domain.dependencies","when":"domain","level":"mandatory","evidence":"code-and-verification"} -->
 - Domain 层不依赖 Repository、Mapper、Controller。
+<a id="domain.behavior"></a>
+<!-- yss-rule {"id":"domain.behavior","when":"domain","level":"mandatory","evidence":"code-and-verification"} -->
 - 领域行为放在模型方法，不要放在 Web 层。
+<a id="domain.gateway"></a>
+<!-- yss-rule {"id":"domain.gateway","when":"domain","level":"mandatory","evidence":"code-and-verification"} -->
 - Gateway 只暴露领域能力，不暴露持久化细节。
 - 对关键状态流转给出明确方法，如 `publish()`、`cancel()`、`terminate()`。
+<a id="domain.invariants"></a>
+<!-- yss-rule {"id":"domain.invariants","when":"domain","level":"mandatory","evidence":"code-and-verification"} -->
 - 明确 Aggregate Root、Entity identity、Value Object、不变量、Domain Event 和一致性边界；没有业务行为时不要伪造富领域模型。
-- 发现旧架构时停止套用新脚手架合同并返回 `unsupported`；旧项目继续按原工程维护，现代化改造单独立项。
+- `unsupported` 只阻断不支持的生成方式。既有 DDD 按登记边界整改；目录差异不是领域违规。架构身份转换或公开契约迁移单独立项，MVC 不套用 DDD 规则。
 
 ## 质量要求
 
 - 命名体现业务语义，不照抄表名缩写。
 - 生成代码应可编译，且没有跨层依赖泄漏。
+<a id="domain.gateway-owner"></a>
+<!-- yss-rule {"id":"domain.gateway-owner","when":"domain","level":"mandatory","evidence":"code-and-verification"} -->
 - Domain Gateway interface 由本 skill 唯一拥有；Infrastructure 只能实现，不得由 `yss-repository` 反向创建或改写其签名。
 - 对不确定规则返回 `new_impacts` / `drift` 并暂停；不要把未批准假设或 TODO 写进实现冒充已确认事实。
 

package/template/.cursor/skills/yss-domain/references/domain-layer-guide.md

@@ -1,6 +1,6 @@
 # YSS Domain Target Profile 指南
 
-本指南只定义新 DDD `target-domain-model`。历史 DTO/VO 型 Gateway、`core/client/repository` 和贫血对象均为 `unsupported`，不存在旧架构 Profile 或迁移分支。
+本指南的目录和生成布局只定义新 DDD `target-domain-model`。既有 DDD 通过 [既有工程边界](existing-project.md) 应用领域语义规则；历史目录或贫血对象不能单凭名称判违规。HTTP DTO/VO 穿入领域端口仍须按登记职责检查。架构迁移不属于生成器。
 
 ## 1. Domain 所有权
 
@@ -62,7 +62,7 @@ public interface QualityTemplateGateway {
 - `*VO`、`PageResult`、Repository PO。
 - MyBatis、Spring MVC、Jackson、Swagger 类型。
 
-分页、列表和投影查询由 Application Query Port 定义，Infrastructure 实现。
+展示分页、列表和投影查询由 Application Query Port 定义，Infrastructure 实现。
 
 ## 5. Domain Error
 
@@ -98,4 +98,11 @@ Web Exception Translator 再将它映射为批准的状态码、错误码和消
 - 消费批准且当前的 Tactical Design 与 Slice Implementation Contract。
 - 返回 YSS Skill Execution Result，包含 Domain 文件、行为测试、ArchUnit 结果及实际 `./mvnw ...` 证据。
 - 新聚合、不变量、状态机或跨上下文影响进入 `new_impacts` 并暂停。
-- 检测到旧架构时返回 `unsupported`；如需现代化，退出 scaffold 工作流并单独立项评估。
+- 旧布局不走 scaffold 生成分支；既有 DDD 按登记整改。需改变架构或公开契约时单独评估并批准。
+
+## 聚合创建与重建
+
+- 创建入口执行当前创建规则；持久化重建入口恢复已批准状态并校验结构不变量，不重复发送创建事件、生成身份或执行外部调用。两者不得通过公开任意 setter 混为一体。
+- 值对象按值相等；聚合按稳定身份相等。集合对外只读，修改经业务方法；Java 8 使用普通类与防御性复制，不从示例推导 record 等高版本语法。
+- 领域错误携带稳定标识与参数；公开消息和 HTTP 状态由 Web 翻译。测试通过公开行为覆盖非法状态、重复动作和重建后语义一致性。
+- 为业务决策加载一个或一组聚合仍可使用 Domain Gateway；展示列表、分页、排序、统计和投影走 Application Query Port。返回 List 本身不是违规，须按调用目的判定。

package/template/.cursor/skills/yss-domain/references/existing-project.md

@@ -0,0 +1,5 @@
+# 既有领域工程
+
+只对 `existing-domain-driven-maven` 或登记为 DDD 的只读盘点范围应用领域语义。读取实际 build unit、role_paths、source roots 与工程基线；不要求 target 模块名、Entity 后缀或生成 Manifest。创建/重建、不变量、端口所有权和技术依赖边界仍按 domain-layer-guide 检查。MVC 不创建聚合或 Gateway。
+
+只读审计允许缺设计资产，但记录 missing_evidence。修改消费当前批准 Slice 和已确认行为 seam；不得从历史代码伪造业务规则批准。新增聚合、改变一致性或架构身份回设计与合同编译器。

package/template/.cursor/skills/yss-dto/SKILL.md

@@ -44,6 +44,8 @@ description: "实现或核验 YSS Result、PageResult、PageQuery、CommandDTO
 
 - 写操作参数优先继承 `CommandDTO`。
 - Application/Infrastructure 内部读参数可按项目 Profile 使用 `QueryDTO` 或 `PageQuery`。
+<a id="dto.page-input"></a>
+<!-- yss-rule {"id":"dto.page-input","when":"pagination","level":"mandatory","evidence":"code-and-verification"} -->
 - 公开 HTTP Page Request 默认不继承 `PageQuery`，只复制冻结 OpenAPI 允许的分页字段，再由 WebConvertor 转为 Application Query；避免继承的 `offset`、`needTotalCount`、`tempTotalCount` 进入绑定面。
 - Controller 返回优先使用项目既有的 `Result` 或派生结果对象。
 - 单对象返回优先 `SingleResult`，列表返回优先 `MultiResult`，分页返回优先 `PageResult`，前提是当前项目已采用这套体系。
@@ -54,27 +56,24 @@ description: "实现或核验 YSS Result、PageResult、PageQuery、CommandDTO
 - `PageResult` 当前稳定公共字段为 `totalCount/pageSize/pageIndex/data[]`；`totalPages` 是计算 getter，只有目标 HTTP mapper / contract fixture 证明后才能进入具体契约。
 - `PageQuery` 客户端输入只允许 `pageIndex/pageSize/orderBy/orderDirection/groupBy`（后四项按 profile 的 optional / whitelist 规则）；`orderDirection` 只能是 `ASC|DESC`。`offset`、`needTotalCount`、`tempTotalCount` 是计算或内部协作字段，禁止成为客户端输入。
 - `buildSuccess(...)` 各重载设置 code 的行为并不一致；冻结契约必须测试 `success/code/message/tips/dataType`、nullability 和三种 data shape，不能只测试 data。
+<a id="dto.wire-evidence"></a>
+<!-- yss-rule {"id":"dto.wire-evidence","when":"wire","level":"mandatory","evidence":"code-and-verification"} -->
 - Java getter、Lombok、`@JsonIgnore` 或默认 Jackson 结果都不是目标 HTTP wire fact；冻结前必须记录 mapper identity、代表性序列化 fixture 和 contract-test / 等价 HTTP 证据。
+<a id="dto.boundary"></a>
+<!-- yss-rule {"id":"dto.boundary","when":"wire","level":"mandatory","evidence":"code-and-verification"} -->
 - DTO 只表达接口契约，不承载 Repository PO 或领域对象的持久化细节。
 
 ## 检查清单
 
-- 分页字段名是否和框架约定一致。
-- `orderBy` / `groupBy` 是否经过 Repository 白名单映射，禁止直接拼接 SQL。
-- Application Query Port / Infrastructure 是否收到批准的分页语义；Domain Gateway 不接收 `PageQuery`。
-- 新增 DTO 是否与现有序列化和校验方式兼容。
-- 返回结构是否和前端或上游调用方契约一致。
-- 是否通过 `scripts/verify-yss-dto-openapi-profile`，并引用 profile 版本。
-- wrapper extension、`YssResultMeta`、`allOf`、具体 data schema 和方向性是否逐 endpoint 对齐。
-- 是否有针对 `offset` / `needTotalCount` / `tempTotalCount` 的负向断言，以及对 `totalPages` 的目标 mapper 证据。
-- Controller、Application Service、Domain、Repository 之间是否存在 DTO/VO/DO/PO 混穿。
-- 前端 Orval 或调用方是否依赖当前返回包装结构。
+仅在 DTO/OpenAPI wire shape 受影响时读取 [wire 验收清单](references/wire-validation-checklist.md)，按当前平台和请求/响应方向执行；权威字段形状继续由 `references/openapi-wire-profile.yaml` 持有。
 
 ## 修改约束
 
 - 不要在一个项目里混用多套返回包装类。
 - 不要新建与 `PageQuery` 含义重叠的分页基类。
 - 不要把 `com.yss.cloud.dto.response` 作为新 API 的 canonical 包，也不要从 Java getter 机械生成 wire schema。
+<a id="dto.no-leak"></a>
+<!-- yss-rule {"id":"dto.no-leak","when":"pagination","level":"mandatory","evidence":"code-and-verification"} -->
 - 不要把 `offset`、`needTotalCount`、`tempTotalCount` 作为客户端分页输入；不要无证据把 `totalPages` 写入所有分页响应。
 - 若项目已有 `SingleResult`、`PageResult`、`MultiResult` 体系，优先保持一致。
 
@@ -95,3 +94,7 @@ description: "实现或核验 YSS Result、PageResult、PageQuery、CommandDTO
 ## 平台与源码门禁
 
 接入、修改、代码生成或给出精确类名/配置前，读取 [后端组件平台与源码门禁](../yss-skill-source-index-refresh/references/backend-component-platform-compatibility.md)，从批准的 `platform_configuration.component_platform_line` 选择 `source-index.boot2-java8.md` 或 `source-index.boot3-java17.md`，并以 `--skill yss-dto --platform-line <line> --source-root <matching-root>` 运行统一 freshness 校验。平台线与源码根不匹配、组件 tree 不一致、组件子树 dirty、索引缺少平台信号，或 Manifest / 组件 GAV 缺少 verified 兼容证据时返回 `blocked`；不得回退另一代索引，也不在业务实现中升级、降级或替换 YSS 组件。既有工程只读分诊可继续，但不得据此宣称跨 Boot/JDK 兼容。
+
+## 既有契约与特殊协议
+
+只读审计先辨认已锁定的 wire 契约。下载、流式和第三方回调按批准协议检查媒体类型、状态、Header、错误与权限边界；不强套 Result，也不因声称“特殊接口”豁免契约证据。普通已采用 YSS wrapper 的接口继续按 wire profile 检查。旧包/旧协议差距单列迁移，不静默改锁或改公开响应。

package/template/.cursor/skills/yss-dto/references/wire-validation-checklist.md

@@ -0,0 +1,14 @@
+## 检查清单
+
+- 分页字段名是否和框架约定一致。
+<a id="dto.sort"></a>
+<!-- yss-rule {"id":"dto.sort","when":"pagination","level":"mandatory","evidence":"code-and-verification"} -->
+- `orderBy` / `groupBy` 是否经过 Repository 白名单映射，禁止直接拼接 SQL。
+- Application Query Port / Infrastructure 是否收到批准的分页语义；Domain Gateway 不接收 `PageQuery`。
+- 新增 DTO 是否与现有序列化和校验方式兼容。
+- 返回结构是否和前端或上游调用方契约一致。
+- 是否通过 `scripts/verify-yss-dto-openapi-profile`，并引用 profile 版本。
+- wrapper extension、`YssResultMeta`、`allOf`、具体 data schema 和方向性是否逐 endpoint 对齐。
+- 是否有针对 `offset` / `needTotalCount` / `tempTotalCount` 的负向断言，以及对 `totalPages` 的目标 mapper 证据。
+- Controller、Application Service、Domain、Repository 之间是否存在 DTO/VO/DO/PO 混穿。
+- 前端 Orval 或调用方是否依赖当前返回包装结构。

package/template/.cursor/skills/yss-exception/SKILL.md

@@ -47,12 +47,12 @@ Read `references/source-index.md` as a path-hint index whenever the task depends
 - Required dependency or starter module is present.
 - Error code/message are meaningful to API consumers.
 - Response messages are sanitized and do not expose raw RuntimeException or localized exception details.
-- HTTP assertions cover business 4xx, unknown/runtime 5xx, upload 413, and `X-Trace-Id`.
+- For affected boot3-java17 HTTP seams, assert the documented business 4xx, unknown/runtime 5xx and trace header behavior. Assert upload 413 only for upload-limit impact. Boot 2 assertions follow its own source and frozen contract; do not import Boot 3 behavior into it.
 - Business validation failures are not reported as unknown system errors.
 - Stack traces are preserved in structured logger output for unknown/system failures, never printed directly to stderr or serialized to clients.
 - Retry guidance matches exception type.
 - Known system failures use `ExceptionFactory.sysException(..., cause)`; Application code does not replace them with ad-hoc `RuntimeException`.
-- Endpoint contract tests cover business, known-system, unknown/runtime, and upload-limit failures; unknown public messages never expose `getLocalizedMessage()`.
+- Endpoint tests cover the failure types actually affected by this change; upload-limit tests apply only to upload endpoints or changed upload handling. Public messages must follow the selected platform contract and never leak protected exception details.
 
 ## Do Not
 

package/template/.cursor/skills/yss-formily-schema-generator/SKILL.md

@@ -3,9 +3,9 @@ name: yss-formily-schema-generator
 description: "从需求或设计图生成 YFormily JSON Schema 与表单代码；仅用于生产表单实现。"
 ---
 
-# YssFormily Schema Generator
+# YFormily Schema Generator
 
-Use this skill to turn upstream input into downstream YssFormily form artifacts.
+Use this skill to turn upstream input into downstream YFormily form artifacts.
 
 Supported input forms:
 
@@ -16,13 +16,13 @@ Supported input forms:
 
 Expected output forms:
 
-- a YssFormily JSON Schema or `ISchema`
+- a YFormily JSON Schema or `ISchema`
 - a recommended `v-model` data shape
 - optional `scope`, `effects`, and slot plan
-- optional Vue render snippet showing how to mount `YssFormily`
+- optional Vue render snippet showing how to mount `YFormily`
 
 This skill designs the schema.
-For implementation rules and exact YssFormily behavior, also read:
+For implementation rules and exact YFormily behavior, also read:
 
 - [yss-formily](../yss-formily/SKILL.md)
 
@@ -35,10 +35,10 @@ For conversion workflow and field mapping, read:
 Use this skill when the request is any of the following:
 
 - “根据需求描述生成表单 schema”
-- “根据原型图生成 YssFormily”
+- “根据原型图生成 YFormily”
 - “根据图片/截图还原表单”
 - “根据 Figma 生成表单 JSON Schema”
-- “把业务字段整理成 YssFormily schema”
+- “把业务字段整理成 YFormily schema”
 - “输出 schema 和渲染代码”
 
 ## Core principle
@@ -50,7 +50,7 @@ Translate the input into a stable form model:
 2. field semantics
 3. validation and dependency rules
 4. layout grouping
-5. YssFormily schema
+5. YFormily schema
 
 The schema must reflect business meaning, not just pixel arrangement.
 
@@ -88,7 +88,7 @@ If the image contains only visual cues and no validation semantics, generate a s
 
 ### Figma input
 
-When a Figma link or node is provided, use the Figma workflow to inspect the design first.
+When a Figma link or node is provided, discover an available design-inspection capability first. If unavailable, use supplied design exports or screenshots; report the missing access when those cannot establish a required detail. Do not invent a tool name or claim inspection succeeded.
 Extract:
 
 - field labels
@@ -99,7 +99,7 @@ Extract:
 - readonly versus editable patterns
 - footer actions
 
-Then convert that structure to YssFormily, following local YSS conventions instead of raw design-tool naming.
+Then convert that structure to YFormily, following local YSS conventions instead of raw design-tool naming.
 
 ## Required outputs
 
@@ -120,7 +120,7 @@ If the user asks for code generation, also produce:
 
 Always align with `yss-formily`:
 
-- wrapper component is `YssFormily` or `YFormily`
+- wrapper component for new code is `YFormily`; the historical `YssFormily` alias is accepted only when an existing installed export is verified
 - schema is `FormLayout -> FormGrid -> fields`
 - use `FormItem` for ordinary fields
 - prefer one shared schema for create/edit/detail when feasible
@@ -151,7 +151,7 @@ Follow this sequence every time:
 4. Decide field types and components.
 5. Decide sections and layout spans.
 6. Identify validation, enum, and linkage requirements.
-7. Produce YssFormily schema.
+7. Produce YFormily schema.
 8. Produce render snippet if requested.
 9. Call out assumptions and uncertain inferences.
 

package/template/.cursor/skills/yss-hook/SKILL.md

@@ -43,7 +43,7 @@ description: Use when YSS Vue 页面涉及 vue-hooks-plus/useRequest、分页、
 ```ts
 export function useReportTable() {
   const tableData = ref<any[]>([]);
-  const currentParams = ref({ page: 1, pageSize: 20 });
+  const currentParams = ref({ pageIndex: 1, pageSize: 20 });
   const pagination = reactive({
     current: 1, pageSize: 20, total: 0,
     showSizeChanger: true, showQuickJumper: true,
@@ -52,8 +52,8 @@ export function useReportTable() {
   const { loading, run: fetchList } = useRequest(apiFn, {
     manual: true,
     onSuccess: (res) => {
-      tableData.value = res?.data?.list || [];
-      pagination.total = res?.data?.total || 0;
+      tableData.value = res?.data || [];
+      pagination.total = res?.totalCount || 0;
     },
     onError: () => {
       tableData.value = [];
@@ -64,60 +64,24 @@ export function useReportTable() {
     currentParams.value = { ...currentParams.value, ...params };
     return fetchList(currentParams.value);
   };
-  const handlePageChange = (current: number, pageSize: number) => {
+  // YTable emits one object; adapt it at this boundary.
+  const handlePageChange = ({ current, pageSize }: { current: number; pageSize: number }) => {
     pagination.current = current;
     pagination.pageSize = pageSize;
-    return query({ page: current, pageSize });
+    return query({ pageIndex: current, pageSize });
   };
   return { loading, tableData, currentParams, pagination, query, handlePageChange };
 }
 ```
 
 - 仅当项目已批准的请求库支持时使用 `useRequest`；通常使用 `manual: true`，除非需求明确要求挂载即请求。
-- `currentParams` 是唯一参数源。筛选变化重置 `page: 1`；翻页只改 `page/pageSize`；刷新、导出和编辑后重载复用它。
+- `currentParams` 是唯一参数源。筛选变化重置 `pageIndex: 1`；翻页只改 `pageIndex/pageSize`；刷新、导出和编辑后重载复用它。
 - 在 Hook 内处理成功、失败、空数据和响应映射；旧列表会误导时才在失败时清空。
 - 树数据同样由 Hook 暴露 `treeData`、`treeLoading`、`selectedKey`、`handleSelect`，并在其中处理会触发加载的选中副作用。
 
 ## 3. `vue-hooks-plus/useRequest`（项目已批准时）
 
-`useRequest` 接收返回 `Promise<TData>` 的 service，并以插件组合管理 `loading`、`data`、`error`、`params`。自动模式默认在组件初始化时执行；`manual: true` 时用 `run` 或 `runAsync` 发起请求。
-
-```ts
-import { useRequest } from 'vue-hooks-plus';
-
-const { data, error, loading, params, run, runAsync, refresh, mutate, cancel } = useRequest(
-  searchReports,
-  {
-    manual: true,
-    debounceWait: 300,
-    onSuccess: (result, requestParams) => {
-      tableData.value = result.list;
-      pagination.total = result.total;
-    },
-    onError: (cause) => { requestError.value = cause; },
-  },
-);
-```
-
-- `run` 会捕获异常并交给 `onError`；`runAsync` 返回 `Promise`，调用处必须自行 `catch`。`refresh` / `refreshAsync` 使用上一次 `params` 重发请求；不要在页面重拼参数。
-- `mutate(nextData | updater)` 用于乐观更新；启用 `rollbackOnError` 时，远端失败会恢复更新前数据。先保存局部错误 / 刷新策略，不能只依赖乐观 UI。
-- `cancel()` 会忽略当前 Promise 的结果和错误，并会取消仍在等待执行的防抖调用；它**不会**终止底层 Promise。若 transport 支持真正中止，service 才能额外使用其已验证的 `AbortSignal` 支持。
-- 搜索场景优先 `debounceWait`（毫秒），并按需要配置 `debounceLeading`、`debounceTrailing`、`debounceMaxWait`。组件卸载与后一次请求的竞态响应会被库忽略；需要提前停止时调用 `cancel()`。不要再叠加自定义 timer / 序号，除非已验证当前版本或 transport 存在库无法覆盖的缺口。
-- `useRequest` 的并发语义在文档版本间出现差异：页面说明从 v2.4.0 起手动调用可独立执行，而 Options 表仍列出 `concurrent`（默认 `false`）控制新旧请求关系。启用并发前，必须以项目锁定版本的类型、测试与行为为准；搜索和同一资源写入默认采用单一最新请求策略。
-
-### 3.1 缓存、刷新与重试
-
-- `cacheKey` 成功后会全局共享 data 和 params：同 key 的并发实例共用 Promise、数据同步。因此 key 必须包含稳定的业务身份与影响结果的参数；不同租户、用户、筛选条件或权限视图不能共用 key。副作用、实时性强或权限敏感结果默认不启用共享缓存。
-- `staleTime` 内数据视为新鲜，不重新请求；`cacheTime` 到期清除缓存。没有 `staleTime` 时，重新挂载会先展示缓存、再后台请求（SWR）。编辑 / 提交成功后的显式 `refresh` 优先于等待 SWR。
-- `refreshOnWindowFocus: true` 在 `visibilitychange` / `focus` 后刷新，使用 `focusTimespan`（默认 5000ms）限频。只给允许后台重取的读模型开启；编辑中的表单、一次性动作和高成本查询默认关闭。
-- `retryCount` 控制失败后的重试次数，`-1` 为无限重试；未设 `retryInterval` 时按 2s、4s…且最高 30s 的指数退避。仅对暂时性网络 / 可恢复服务错误设置有限重试；认证授权、参数校验、业务拒绝、显式取消和非幂等写操作禁止自动重试。`cancel()` 可停止正在等待的重试。
-- `loadingDelay` 可延迟 loading 变为 `true`，避免短请求闪烁；它不延迟请求，也不能作为防抖替代。
-
-### 3.2 请求轮询与依赖刷新
-
-- `pollingInterval > 0` 启用请求轮询；每次请求完成后等待间隔再发下一次。`manual: true` 时，先 `run/runAsync` 才启动。`pollingWhenHidden` 默认 `true`；仅在业务允许后台继续请求时保留，需暂停则显式设为 `false`。`pollingErrorRetryCount` 默认 `-1`，必须为生产读模型配置有限值或明确停止条件。
-- 同一数据源只能选择 `useRequest` 轮询或 YSS `usePollingTask` 之一，禁止嵌套或同时运行。手动刷新前 `cancel()` 当前请求 / 轮询，执行带 loading 的 `refresh`，再依据明确业务规则恢复轮询。
-- `refreshDeps` 仅在非 manual 自动模式生效；传入 `WatchSource[]` 精确声明依赖，或在理解捕获范围后用 `true` 自动收集。筛选列表通常使用显式 `query` 并在筛选变化时重置页码，不以 `refreshDeps` 隐式驱动复杂参数。
+仅项目已批准且当前任务使用该库时，读取 [useRequest 实现细则](references/use-request.md)，覆盖返回值、错误处理、取消、缓存、刷新、重试和轮询。不得因技能示例引入未批准依赖；调用 `runAsync` 必须捕获拒绝，业务失败提示遵循 mutator 的唯一所有权。
 
 ## 4. 单一异步动作：`useLoading`