create-yss-spec 3.3.1 → 3.3.3

package/template/.trae/skills/yss-prototype-stage/scripts/visual-baseline-contract.mjs

@@ -1,314 +0,0 @@
-#!/usr/bin/env node
-import { createHash } from "node:crypto";
-import { existsSync } from "node:fs";
-import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
-import path from "node:path";
-import { pathToFileURL } from "node:url";
-import { parseDocument, stringify } from "../../../../scripts/vendor/yaml.mjs";
-
-const SHA256 = /^sha256:[a-f0-9]{64}$/;
-const CASE_ID = /^[a-z0-9][a-z0-9-]*$/;
-const MAX_IMAGE_BYTES = 5 * 1024 * 1024;
-const MAX_BUNDLE_BYTES = 100 * 1024 * 1024;
-
-const object = (value) => value && typeof value === "object" && !Array.isArray(value);
-const nonEmpty = (value) => typeof value === "string" && value.trim().length > 0;
-const digest = (value) => `sha256:${createHash("sha256").update(value).digest("hex")}`;
-
-function required(data, field, parent, errors) {
-  if (!object(data) || data[field] === undefined || data[field] === null) errors.push(`${parent}.${field} 缺失`);
-}
-
-function requiredString(data, field, parent, errors) {
-  required(data, field, parent, errors);
-  if (object(data) && data[field] !== undefined && !nonEmpty(data[field])) errors.push(`${parent}.${field} 必须是非空字符串`);
-}
-
-function placeholder(value) {
-  return typeof value === "string" && /<[^>]+>/.test(value);
-}
-
-function safeRelativeRef(value, prefix, suffix, field, errors, allowTemplate) {
-  if (allowTemplate && placeholder(value)) return;
-  if (!nonEmpty(value) || path.isAbsolute(value) || value.split("/").includes("..") || !value.startsWith(prefix) || !value.endsWith(suffix)) {
-    errors.push(`${field} 必须是 ${prefix} 下的相对 ${suffix} 文件`);
-  }
-}
-
-async function listPayloadFiles(root, relative = "") {
-  const files = [];
-  for (const entry of await readdir(path.join(root, relative), { withFileTypes: true })) {
-    const ref = relative ? `${relative}/${entry.name}` : entry.name;
-    if (entry.isSymbolicLink()) throw new TypeError(`Bundle 不允许符号链接: ${ref}`);
-    if (entry.isDirectory()) files.push(...await listPayloadFiles(root, ref));
-    else if (entry.isFile() && ref !== "visual-baseline.yaml") files.push(ref);
-  }
-  return files.sort();
-}
-
-function validateDigest(value, field, errors, allowTemplate) {
-  if (!(allowTemplate && placeholder(value)) && !SHA256.test(value ?? "")) errors.push(`${field} 必须为 sha256 摘要`);
-}
-
-function canonicalDigestPayload(data) {
-  return {
-    schema_version: data.schema_version,
-    baseline_id: data.baseline_id,
-    feature: data.feature,
-    version: data.version,
-    prototype_ref: data.source?.prototype_ref,
-    prototype_digest: data.source?.prototype_digest,
-    interaction_spec_ref: data.source?.interaction_spec_ref,
-    interaction_spec_digest: data.source?.interaction_spec_digest,
-    state_matrix_ref: data.source?.state_matrix_ref,
-    state_matrix_digest: data.source?.state_matrix_digest,
-    capture_script_ref: data.capture_environment?.capture_script_ref,
-    capture_script_digest: data.capture_environment?.capture_script_digest,
-    capture_result_ref: data.capture_environment?.capture_result_ref,
-    capture_result_digest: data.capture_environment?.capture_result_digest,
-    cases: (data.cases ?? []).map((item) => ({
-      case_id: item.case_id,
-      route: item.route,
-      page: item.page,
-      state: item.state,
-      viewport: item.viewport,
-      theme: item.theme,
-      locale: item.locale,
-      data_scenario: item.data_scenario,
-      image_ref: item.image_ref,
-      image_digest: item.image_digest,
-      image_size_bytes: item.image_size_bytes,
-      mask_ref: item.mask_ref,
-      mask_digest: item.mask_digest,
-      mask_size_bytes: item.mask_size_bytes,
-      semantic_refs: item.semantic_refs,
-      allowed_differences: item.allowed_differences,
-    })),
-  };
-}
-
-export function computeVisualBaselineDigest(data) {
-  return digest(JSON.stringify(canonicalDigestPayload(data)));
-}
-
-function pngDimensions(buffer) {
-  const signature = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
-  if (buffer.length < 24 || !buffer.subarray(0, 8).equals(signature) || buffer.toString("ascii", 12, 16) !== "IHDR") {
-    throw new TypeError("文件不是有效 PNG");
-  }
-  return { width: buffer.readUInt32BE(16), height: buffer.readUInt32BE(20) };
-}
-
-export async function validateVisualBaseline(data, { allowTemplate = false, bundleRoot } = {}) {
-  const errors = [];
-  if (!object(data)) return { errors: ["Visual Baseline 必须是对象"] };
-  for (const field of ["schema_version", "baseline_id", "feature", "version", "status", "bundle", "source", "capture_environment", "cases"]) required(data, field, "root", errors);
-  if (data.schema_version !== 1) errors.push("schema_version 必须为 1");
-  requiredString(data, "baseline_id", "root", errors);
-  requiredString(data, "feature", "root", errors);
-  requiredString(data, "version", "root", errors);
-  if (!(allowTemplate && placeholder(data.feature)) && !CASE_ID.test(data.feature ?? "")) errors.push("feature 必须是小写 kebab-case");
-  if (!(allowTemplate && placeholder(data.baseline_id)) && data.baseline_id !== `visual-baseline.${data.feature}`) errors.push("baseline_id 必须为 visual-baseline.<feature>");
-  if (!(allowTemplate && placeholder(data.version)) && !/^v[1-9][0-9]*$/.test(data.version ?? "")) errors.push("version 必须形如 v1");
-  if (!['draft', 'ready-for-human', 'approved', 'stale', 'blocked'].includes(data.status)) errors.push("status 非法");
-
-  const bundle = data.bundle;
-  for (const field of ["format", "root_ref", "digest", "size_bytes", "max_image_bytes", "max_bundle_bytes"]) required(bundle, field, "bundle", errors);
-  if (bundle?.format !== "portable-directory") errors.push("bundle.format 必须为 portable-directory");
-  requiredString(bundle, "root_ref", "bundle", errors);
-  validateDigest(bundle?.digest, "bundle.digest", errors, allowTemplate);
-  if (!(allowTemplate && placeholder(bundle?.size_bytes)) && (!Number.isInteger(bundle?.size_bytes) || bundle.size_bytes < 0 || bundle.size_bytes > MAX_BUNDLE_BYTES)) errors.push("bundle.size_bytes 必须是不超过 100 MiB 的非负整数");
-  if (bundle?.max_image_bytes !== MAX_IMAGE_BYTES) errors.push(`bundle.max_image_bytes 必须为 ${MAX_IMAGE_BYTES}`);
-  if (bundle?.max_bundle_bytes !== MAX_BUNDLE_BYTES) errors.push(`bundle.max_bundle_bytes 必须为 ${MAX_BUNDLE_BYTES}`);
-
-  const source = data.source;
-  for (const field of ["prototype_ref", "prototype_digest", "interaction_spec_ref", "interaction_spec_digest", "state_matrix_ref", "state_matrix_digest"]) requiredString(source, field, "source", errors);
-  for (const field of ["prototype_digest", "interaction_spec_digest", "state_matrix_digest"]) validateDigest(source?.[field], `source.${field}`, errors, allowTemplate);
-  safeRelativeRef(source?.prototype_ref, "sources/", "", "source.prototype_ref", errors, allowTemplate);
-  safeRelativeRef(source?.interaction_spec_ref, "sources/", "", "source.interaction_spec_ref", errors, allowTemplate);
-  safeRelativeRef(source?.state_matrix_ref, "sources/", "", "source.state_matrix_ref", errors, allowTemplate);
-
-  const environment = data.capture_environment;
-  for (const field of ["browser", "browser_version", "operating_system", "fonts_digest", "device_scale_factor", "color_space", "locale", "timezone", "animations_disabled", "cursor_hidden", "capture_script_ref", "capture_script_digest", "capture_result_ref", "capture_result_digest"]) required(environment, field, "capture_environment", errors);
-  if (environment?.browser !== "chromium") errors.push("capture_environment.browser 必须为 chromium");
-  if (environment?.device_scale_factor !== 1) errors.push("capture_environment.device_scale_factor 必须为 1");
-  if (environment?.color_space !== "srgb") errors.push("capture_environment.color_space 必须为 srgb");
-  if (environment?.animations_disabled !== true || environment?.cursor_hidden !== true) errors.push("截图必须关闭动画并隐藏光标");
-  for (const field of ["browser_version", "operating_system", "locale", "timezone"]) requiredString(environment, field, "capture_environment", errors);
-  for (const field of ["fonts_digest", "capture_script_digest", "capture_result_digest"]) validateDigest(environment?.[field], `capture_environment.${field}`, errors, allowTemplate);
-  safeRelativeRef(environment?.capture_script_ref, "capture/", "", "capture_environment.capture_script_ref", errors, allowTemplate);
-  safeRelativeRef(environment?.capture_result_ref, "capture/", "", "capture_environment.capture_result_ref", errors, allowTemplate);
-
-  if (!Array.isArray(data.cases) || data.cases.length === 0) errors.push("cases 必须是非空数组");
-  const ids = new Set();
-  const viewportSizes = new Set();
-  const referencedFiles = new Set();
-  const fileCache = new Map();
-  const readBundleFile = async (ref, field) => {
-    if (!bundleRoot || (allowTemplate && placeholder(ref))) return null;
-    const resolvedRoot = path.resolve(bundleRoot);
-    const filePath = path.resolve(resolvedRoot, ref);
-    if (!filePath.startsWith(`${resolvedRoot}${path.sep}`) || !existsSync(filePath)) {
-      errors.push(`${field} 不可读或越界`);
-      return null;
-    }
-    referencedFiles.add(ref);
-    if (!fileCache.has(ref)) fileCache.set(ref, await readFile(filePath));
-    return fileCache.get(ref);
-  };
-  if (bundleRoot) {
-    for (const [refField, digestField] of [["prototype_ref", "prototype_digest"], ["interaction_spec_ref", "interaction_spec_digest"], ["state_matrix_ref", "state_matrix_digest"]]) {
-      const bytes = await readBundleFile(source?.[refField], `source.${refField}`);
-      if (bytes && digest(bytes) !== source?.[digestField]) errors.push(`source.${digestField} 与文件不一致`);
-    }
-    for (const [refField, digestField] of [["capture_script_ref", "capture_script_digest"], ["capture_result_ref", "capture_result_digest"]]) {
-      const bytes = await readBundleFile(environment?.[refField], `capture_environment.${refField}`);
-      if (bytes && digest(bytes) !== environment?.[digestField]) errors.push(`capture_environment.${digestField} 与文件不一致`);
-    }
-  }
-  for (const [index, item] of (data.cases ?? []).entries()) {
-    const parent = `cases.${index}`;
-    for (const field of ["case_id", "route", "page", "state", "viewport", "theme", "locale", "data_scenario", "image_ref", "image_digest", "image_size_bytes", "mask_ref", "mask_digest", "mask_size_bytes", "semantic_refs", "allowed_differences", "result"]) required(item, field, parent, errors);
-    if (!(allowTemplate && placeholder(item?.case_id)) && !CASE_ID.test(item?.case_id ?? "")) errors.push(`${parent}.case_id 必须是小写 kebab-case`);
-    if (ids.has(item?.case_id)) errors.push(`${parent}.case_id 重复`);
-    ids.add(item?.case_id);
-    for (const field of ["route", "page", "state", "theme", "locale", "data_scenario"]) requiredString(item, field, parent, errors);
-    const viewport = item?.viewport;
-    for (const field of ["name", "width", "height", "scroll_mode", "scroll_position"]) required(viewport, field, `${parent}.viewport`, errors);
-    if (!(allowTemplate && (placeholder(viewport?.width) || placeholder(viewport?.height))) && (!Number.isInteger(viewport?.width) || !Number.isInteger(viewport?.height) || viewport.width <= 0 || viewport.height <= 0)) errors.push(`${parent}.viewport 尺寸必须是正整数`);
-    if (!["viewport", "segment"].includes(viewport?.scroll_mode)) errors.push(`${parent}.viewport.scroll_mode 必须为 viewport/segment`);
-    if (viewport?.scroll_mode === "viewport" && viewport?.scroll_position !== 0) errors.push(`${parent}.viewport.scroll_position 在 viewport 模式必须为 0`);
-    viewportSizes.add(`${viewport?.width}x${viewport?.height}`);
-    safeRelativeRef(item?.image_ref, "images/", ".png", `${parent}.image_ref`, errors, allowTemplate);
-    validateDigest(item?.image_digest, `${parent}.image_digest`, errors, allowTemplate);
-    if (!(allowTemplate && placeholder(item?.image_size_bytes)) && (!Number.isInteger(item?.image_size_bytes) || item.image_size_bytes <= 0 || item.image_size_bytes > MAX_IMAGE_BYTES)) errors.push(`${parent}.image_size_bytes 必须为 1..${MAX_IMAGE_BYTES}`);
-    if (item?.mask_ref === "not-applicable") {
-      if (item?.mask_digest !== "not-applicable" || item?.mask_size_bytes !== 0) errors.push(`${parent} 无 mask 时 digest 必须为 not-applicable 且 size 为 0`);
-    } else {
-      safeRelativeRef(item?.mask_ref, "masks/", ".png", `${parent}.mask_ref`, errors, allowTemplate);
-      validateDigest(item?.mask_digest, `${parent}.mask_digest`, errors, allowTemplate);
-      if (!(allowTemplate && placeholder(item?.mask_size_bytes)) && (!Number.isInteger(item?.mask_size_bytes) || item.mask_size_bytes <= 0 || item.mask_size_bytes > MAX_IMAGE_BYTES)) errors.push(`${parent}.mask_size_bytes 必须为 1..${MAX_IMAGE_BYTES}`);
-    }
-    const allowedSemanticRefs = new Set([source?.prototype_ref, source?.interaction_spec_ref, source?.state_matrix_ref]);
-    if (!Array.isArray(item?.semantic_refs) || item.semantic_refs.length === 0 || item.semantic_refs.some((ref) => !nonEmpty(ref) || !allowedSemanticRefs.has(ref))) errors.push(`${parent}.semantic_refs 必须引用 source 中的可移植快照`);
-    if (!Array.isArray(item?.allowed_differences)) errors.push(`${parent}.allowed_differences 必须是数组`);
-    if (!(allowTemplate && placeholder(item?.result)) && item?.result !== "passed") errors.push(`${parent}.result 必须为 passed`);
-
-    if (bundleRoot && !(allowTemplate && placeholder(item?.image_ref))) {
-      const bytes = await readBundleFile(item.image_ref, `${parent}.image_ref`);
-      if (bytes) {
-        try {
-          const dimensions = pngDimensions(bytes);
-          if (dimensions.width !== viewport.width || dimensions.height !== viewport.height) errors.push(`${parent}.image_ref PNG 尺寸与 viewport 不一致`);
-        } catch (error) { errors.push(`${parent}.image_ref ${error.message}`); }
-        if (digest(bytes) !== item.image_digest) errors.push(`${parent}.image_digest 与文件不一致`);
-        if (bytes.length !== item.image_size_bytes) errors.push(`${parent}.image_size_bytes 与文件不一致`);
-      }
-      if (item?.mask_ref !== "not-applicable") {
-        const mask = await readBundleFile(item.mask_ref, `${parent}.mask_ref`);
-        if (mask) {
-          try {
-            const dimensions = pngDimensions(mask);
-            if (dimensions.width !== viewport.width || dimensions.height !== viewport.height) errors.push(`${parent}.mask_ref PNG 尺寸与 viewport 不一致`);
-          } catch (error) { errors.push(`${parent}.mask_ref ${error.message}`); }
-          if (digest(mask) !== item.mask_digest) errors.push(`${parent}.mask_digest 与文件不一致`);
-          if (mask.length !== item.mask_size_bytes) errors.push(`${parent}.mask_size_bytes 与文件不一致`);
-        }
-      }
-    }
-  }
-  if (!allowTemplate && (!viewportSizes.has("1440x900") || !viewportSizes.has("390x844"))) errors.push("Visual Baseline 至少覆盖 1440x900 与 390x844");
-  if (!allowTemplate && data.status !== "approved") errors.push("正式 Visual Baseline 必须达到 approved");
-  if (!allowTemplate && computeVisualBaselineDigest(data) !== bundle?.digest) errors.push("bundle.digest 与 manifest 内容不一致");
-  if (bundleRoot) {
-    let payloadFiles = [];
-    try { payloadFiles = await listPayloadFiles(path.resolve(bundleRoot)); } catch (error) { errors.push(error.message); }
-    for (const ref of payloadFiles) if (!referencedFiles.has(ref)) errors.push(`Bundle 包含未登记 payload: ${ref}`);
-    const actualBundleBytes = [...fileCache.values()].reduce((sum, bytes) => sum + bytes.length, 0);
-    if (actualBundleBytes !== bundle?.size_bytes) errors.push("bundle.size_bytes 与全部已登记 payload 大小不一致");
-  }
-  return { errors };
-}
-
-async function loadYaml(file) {
-  const document = parseDocument(await readFile(file, "utf8"), { uniqueKeys: true });
-  if (document.errors.length) throw new TypeError(document.errors[0].message);
-  return document.toJS({ maxAliasCount: 0 });
-}
-
-export async function sealVisualBaseline(file, bundleRoot) {
-  const data = await loadYaml(file);
-  const referencedFiles = new Set();
-  const payloads = new Map();
-  const consume = async (ref) => {
-    if (!nonEmpty(ref) || path.isAbsolute(ref) || ref.split("/").includes("..")) throw new TypeError(`Bundle 引用越界: ${ref}`);
-    referencedFiles.add(ref);
-    if (!payloads.has(ref)) payloads.set(ref, await readFile(path.resolve(bundleRoot, ref)));
-    return payloads.get(ref);
-  };
-  for (const [refField, digestField] of [["prototype_ref", "prototype_digest"], ["interaction_spec_ref", "interaction_spec_digest"], ["state_matrix_ref", "state_matrix_digest"]]) {
-    data.source[digestField] = digest(await consume(data.source[refField]));
-  }
-  for (const [refField, digestField] of [["capture_script_ref", "capture_script_digest"], ["capture_result_ref", "capture_result_digest"]]) {
-    data.capture_environment[digestField] = digest(await consume(data.capture_environment[refField]));
-  }
-  for (const item of data.cases ?? []) {
-    const bytes = await consume(item.image_ref);
-    const dimensions = pngDimensions(bytes);
-    if (dimensions.width !== item.viewport.width || dimensions.height !== item.viewport.height) throw new TypeError(`${item.case_id} PNG 尺寸与 viewport 不一致`);
-    if (bytes.length > MAX_IMAGE_BYTES) throw new TypeError(`${item.case_id} PNG 超过 5 MiB`);
-    item.image_digest = digest(bytes);
-    item.image_size_bytes = bytes.length;
-    item.result = "passed";
-    if (item.mask_ref === "not-applicable") {
-      item.mask_digest = "not-applicable";
-      item.mask_size_bytes = 0;
-    } else {
-      const mask = await consume(item.mask_ref);
-      const maskDimensions = pngDimensions(mask);
-      if (maskDimensions.width !== item.viewport.width || maskDimensions.height !== item.viewport.height) throw new TypeError(`${item.case_id} mask PNG 尺寸与 viewport 不一致`);
-      if (mask.length > MAX_IMAGE_BYTES) throw new TypeError(`${item.case_id} mask PNG 超过 5 MiB`);
-      item.mask_digest = digest(mask);
-      item.mask_size_bytes = mask.length;
-    }
-  }
-  const payloadFiles = await listPayloadFiles(path.resolve(bundleRoot));
-  for (const ref of payloadFiles) if (!referencedFiles.has(ref)) throw new TypeError(`Bundle 包含未登记 payload: ${ref}`);
-  const sizeBytes = [...payloads.values()].reduce((sum, bytes) => sum + bytes.length, 0);
-  if (sizeBytes > MAX_BUNDLE_BYTES) throw new TypeError("Visual Baseline Bundle 超过 100 MiB");
-  data.bundle.size_bytes = sizeBytes;
-  data.bundle.digest = computeVisualBaselineDigest(data);
-  await mkdir(path.dirname(file), { recursive: true });
-  await writeFile(file, stringify(data));
-  return data;
-}
-
-function args(argv) {
-  const result = { _: [] };
-  for (let index = 0; index < argv.length; index += 1) {
-    const item = argv[index];
-    if (!item.startsWith("--")) { result._.push(item); continue; }
-    const key = item.slice(2);
-    const value = argv[index + 1];
-    if (!value || value.startsWith("--")) result[key] = true;
-    else { result[key] = value; index += 1; }
-  }
-  return result;
-}
-
-async function main(argv) {
-  const parsed = args(argv);
-  const [command, file] = parsed._;
-  if (!file || !["validate", "seal"].includes(command)) throw new TypeError("usage: visual-baseline-contract.mjs validate|seal <visual-baseline.yaml> [--bundle-root <dir>] [--allow-template]");
-  const bundleRoot = parsed["bundle-root"] ? path.resolve(parsed["bundle-root"]) : undefined;
-  if (command === "seal") {
-    if (!bundleRoot) throw new TypeError("seal 必须提供 --bundle-root");
-    await sealVisualBaseline(path.resolve(file), bundleRoot);
-  }
-  const data = await loadYaml(path.resolve(file));
-  const result = await validateVisualBaseline(data, { allowTemplate: Boolean(parsed["allow-template"]), bundleRoot });
-  if (result.errors.length) throw new TypeError(result.errors.join("\n"));
-  process.stdout.write(`Visual Baseline ${command} passed\n`);
-}
-
-if (import.meta.url === pathToFileURL(process.argv[1]).href) main(process.argv.slice(2)).catch((error) => { process.stderr.write(`${error.message}\n`); process.exitCode = 1; });

package/template/.trae/skills/yss-prototype-stage/tests/run-scenarios.mjs

@@ -1,186 +0,0 @@
-#!/usr/bin/env node
-import assert from "node:assert/strict";
-import { buildDecisionFixture } from "../../../../scripts/fixtures/user-decision/build-fixture.mjs";
-import { mkdtemp, mkdir, readFile, writeFile } from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-import { prepareFlowPrototype, prepareStaticPrototype, validatePrototypeEvidence, validatePrototypeProject, prototypeDecisionSnapshot } from "../scripts/prototype-contract.mjs";
-import { sealVisualBaseline, validateVisualBaseline } from "../scripts/visual-baseline-contract.mjs";
-
-const tempRoot = await mkdtemp(path.join(os.tmpdir(), "yss-prototype-contract-"));
-const projectRoot = path.join(tempRoot, "project");
-const feature = "order-review";
-await mkdir(path.join(projectRoot, "docs/design/tokens"), { recursive: true });
-await writeFile(path.join(projectRoot, "DESIGN.md"), "---\nversion: alpha\n---\n");
-await writeFile(path.join(projectRoot, "docs/design/tokens/theme.json"), JSON.stringify({ token: { colorPrimary: "#3371ff", borderRadius: 6, controlHeight: 32 } }, null, 2));
-
-const h1Root = path.join(projectRoot, "docs/.scratch", feature, "design/prototypes");
-await prepareStaticPrototype({ projectRoot, root: h1Root, feature });
-assert.match(await readFile(path.join(h1Root, "index.html"), "utf8"), /H1 · visual-review/);
-const h1Styles = await readFile(path.join(h1Root, "styles.css"), "utf8");
-for (const token of ["--brand-font-family", "--brand-color-text", "--brand-color-bg-layout", "--brand-color-bg-container", "--yss-color-primary-control", "--yss-control-height-compact", "--brand-size-lg", "--brand-size", "--brand-size-sm", "--brand-border-radius-lg", "--brand-border-radius"]) assert.match(h1Styles, new RegExp(token));
-for (const staleAlias of ["--font-family", "--layout-background", "--container-background", "--brand-primary"]) assert.doesNotMatch(h1Styles, new RegExp(staleAlias));
-for (const hardcodedDeclaration of ["padding:24px", "padding:20px", "min-height:32px", "border-radius:8px", "border-radius:6px"]) assert.doesNotMatch(h1Styles, new RegExp(hardcodedDeclaration));
-assert.deepEqual((await validatePrototypeProject({ root: h1Root, profile: "H1" })).errors, []);
-await writeFile(path.join(h1Root, "package.json"), "{}\n");
-assert((await validatePrototypeProject({ root: h1Root, profile: "H1" })).errors.some((message) => message.includes("package.json")), "H1 必须拒绝伪构建依赖");
-
-const h2Feature = "approval-flow";
-const h2Root = path.join(projectRoot, "docs/.scratch", h2Feature, "design/prototypes");
-const h2Manifest = await prepareFlowPrototype({ projectRoot, root: h2Root, feature: h2Feature, pnpmVersion: "10.15.0" });
-await writeFile(path.join(h2Root, "pnpm-lock.yaml"), "lockfileVersion: '9.0'\n");
-assert.equal(h2Manifest.component_basis, "vue-antdv-next");
-assert.equal(h2Manifest.library.version, "1.5.2");
-assert.match(await readFile(path.join(h2Root, "src/App.vue"), "utf8"), /a-config-provider/);
-assert.match(await readFile(path.join(h2Root, "src/yss-theme.js"), "utf8"), /compactAlgorithm/);
-assert.deepEqual((await validatePrototypeProject({ root: h2Root, profile: "H2" })).errors, []);
-assert((await validatePrototypeProject({ root: h2Root, profile: "H2", componentBasis: "vue-antdv-next", libraryVersion: "1.5.1" })).errors.some((message) => message.includes("精确锁定")));
-
-const reactFeature = "legacy-react-flow";
-const reactRoot = path.join(projectRoot, "docs/.scratch", reactFeature, "design/prototypes");
-await mkdir(path.join(reactRoot, "src"), { recursive: true });
-await writeFile(path.join(reactRoot, "index.html"), "<!doctype html><div id=app></div>\n");
-await writeFile(path.join(reactRoot, "package.json"), JSON.stringify({ name: "legacy-react-flow-prototype", private: true, type: "module", scripts: { build: "vite build" }, dependencies: { react: "19.2.0", "react-dom": "19.2.0", vite: "6.4.2" } }, null, 2));
-await prepareFlowPrototype({ projectRoot, root: reactRoot, feature: reactFeature, targetAntdVersion: "6.6.2", pnpmVersion: "10.15.0" });
-await writeFile(path.join(reactRoot, "pnpm-lock.yaml"), "lockfileVersion: '9.0'\n");
-await writeFile(path.join(reactRoot, "src/App.jsx"), 'import { ConfigProvider } from "antd"; import { yssTheme } from "./yss-theme.js"; export function App(){return <ConfigProvider theme={yssTheme}/>;}\n');
-assert.deepEqual((await validatePrototypeProject({ root: reactRoot, profile: "H2", targetAntdVersion: "6.6.2" })).errors, []);
-
-function common(profile, kind, block) {
-  const data = {
-    schema_version: 4,
-    feature,
-    prototype_ref: `docs/.scratch/${feature}/design/prototypes/index.html`,
-    prototype_profile: profile,
-    profile_kind: kind,
-    profile_decision: {
-      decision_to_inform: "确认审批交互与状态",
-      risk_assumptions: ["状态必须可理解"],
-      trigger_results: [{ trigger: "visual-only", matched: profile === "H1", evidence_ref: "design/review.md" }],
-      calculated_profile: profile,
-      override: { applied: false, direction: "none", reason: "not-applicable", evidence_ref: "not-applicable" }
-    },
-    upstream_refs: { spec_ref: "spec.md", interaction_spec_ref: "interaction.md", low_fidelity_ref: "low.md", state_matrix_ref: "states.md", prototype_review_ref: "review.md" },
-    source_visual: { ideation_status: "not-applicable", selected_ref: "approved-pattern.md", reuse_reason: "复用已批准模式" },
-    design_baseline: { canonical_design_ref: "DESIGN.md", canonical_design_digest: "sha256:design", project_design_ref: "docs/design/design.md", project_token_refs: ["docs/design/tokens/theme.json"], project_token_baseline_digest: "sha256:tokens", project_override_reviewed: true },
-    visual_baseline: { manifest_ref: `docs/.scratch/${feature}/handoff/visual-baseline-v1/visual-baseline.yaml`, baseline_id: `visual-baseline.${feature}`, version: "v1", digest: `sha256:${"a".repeat(64)}`, status: "approved", case_ids: ["primary-desktop", "primary-narrow"] },
-    browser_delivery: {
-      delivery_kind: "static-directory", entry_ref: `docs/.scratch/${feature}/design/prototypes/index.html`, rendered_nonblank: true, prototype_digest: "sha256:prototype",
-      viewports: [
-        { name: "desktop", size: "1440x900", result: "passed", case_ids: ["primary-desktop"] },
-        { name: "narrow", size: "390x844", result: "passed", case_ids: ["primary-narrow"] }
-      ],
-      console_result: "passed", console_ref: "console.txt"
-    },
-    design_qa: { report_ref: `docs/.scratch/${feature}/verification/design-qa.md`, result: "passed", axes: { visual: "passed", layout: "passed", interaction: "passed", content: "passed", accessibility: "passed", cross_platform: "passed" } },
-    profile_evidence: block,
-    implementation_handoff: {
-      prototype_code_reusable: false,
-      production_component_assumptions: ["YSS 组件可以表达已确认的交互语义"],
-      verification_targets: [{ behavior: "核验目标组件的真实 props/slots/events 与状态", target_stage: "frontend-implementation-plan" }]
-    },
-    review: { result: "approved", review_ref: "review.md" },
-    user_confirmation: { result: "approved", confirmation_ref: "confirmation.md", confirmed_decision: "接受当前设计", operable_scope: ["主操作"], simulations_or_gaps: [] },
-    gaps: [], blockers: []
-  };
-  const f = buildDecisionFixture(path.join(tempRoot, `decision-${profile}-${kind}`), { boundary: "gate.user-confirmation", scope: data.user_confirmation.operable_scope, subjectContent: JSON.stringify(prototypeDecisionSnapshot(data)) });
-  data.user_confirmation.user_decision_ref = f.ref;
-  data.user_confirmation.decision_subject_ref = f.requirement.subject_ref;
-  return data;
-}
-
-const h1Evidence = common("H1", "visual-review", { visual_review: {
-  runtime_build_required: false, key_interactions_result: "passed", keyboard_result: "passed", focus_result: "passed", contrast_result: "passed",
-  zoom_200: { applicable: false, result: "not-applicable", evidence_ref: "not-applicable" },
-  reduced_motion: { applicable: false, result: "not-applicable", evidence_ref: "not-applicable" }
-} });
-assert.deepEqual(validatePrototypeEvidence(h1Evidence).errors, []);
-const missingCanonicalDesign = structuredClone(h1Evidence);
-delete missingCanonicalDesign.design_baseline.canonical_design_ref;
-delete missingCanonicalDesign.design_baseline.canonical_design_digest;
-assert(validatePrototypeEvidence(missingCanonicalDesign).errors.some((message) => message.includes("canonical_design")), "schema v4 必须绑定根 DESIGN.md 及其 digest");
-const fakeH1 = structuredClone(h1Evidence);
-fakeH1.profile_evidence.visual_review.lockfile_ref = "pnpm-lock.yaml";
-assert(validatePrototypeEvidence(fakeH1).errors.some((message) => message.includes("H1 禁止字段")));
-
-const h2Evidence = common("H2", "flow-review", { flow_review: {
-  implementation: { framework: "vue", runtime_build_required: true, package_manager: "pnpm", package_manifest_ref: "package.json", lockfile_ref: "pnpm-lock.yaml", build_command: "pnpm build", build_result: "passed" },
-  main_flow_result: "passed", exceptional_state_result: "passed", exceptional_state_ref: "conflict.png", keyboard_result: "passed", focus_result: "passed", contrast_result: "passed", zoom_200_result: "passed", reduced_motion_result: "passed",
-  visual_regression: { applicable: true, result: "passed", evidence_ref: "visual.json" },
-  prototype_library_facts: { applicable: true, component_basis: "vue-antdv-next", source: "fact-pack", library_package: "antdv-next", library_version: "1.5.2", manifest_ref: "docs/design/facts/antdv-next/1.5.2/manifest.json", manifest_digest: "sha256:facts", components_covered: ["Button"], canonical_design_digest: "sha256:design", project_token_baseline_digest: "sha256:tokens", new_api_uncertainty: false }
-} });
-assert.deepEqual(validatePrototypeEvidence(h2Evidence).errors, []);
-const legacyReactEvidence = structuredClone(h2Evidence);
-legacyReactEvidence.profile_evidence.flow_review.implementation.framework = "react";
-legacyReactEvidence.profile_evidence.flow_review.prototype_library_facts = { applicable: true, component_basis: "react-antd-6", source: "fact-pack", actual_antd_version: "6.6.2", manifest_ref: "docs/design/facts/antd/6.6.2/manifest.json", manifest_digest: "sha256:facts", components_covered: ["Button"], canonical_design_digest: "sha256:design", project_token_baseline_digest: "sha256:tokens", new_api_uncertainty: false };
-assert.deepEqual(validatePrototypeEvidence(legacyReactEvidence).errors, []);
-const staleFacts = structuredClone(h2Evidence);
-staleFacts.profile_evidence.flow_review.prototype_library_facts.project_token_baseline_digest = "sha256:old";
-assert(validatePrototypeEvidence(staleFacts).errors.some((message) => message.includes("Token digest")));
-const staleCanonicalDesign = structuredClone(h2Evidence);
-staleCanonicalDesign.profile_evidence.flow_review.prototype_library_facts.canonical_design_digest = "sha256:old-design";
-assert(validatePrototypeEvidence(staleCanonicalDesign).errors.some((message) => message.includes("DESIGN.md digest")));
-const fakeH3Claim = structuredClone(h2Evidence);
-fakeH3Claim.profile_evidence.flow_review.real_component_verified = true;
-assert(validatePrototypeEvidence(fakeH3Claim).errors.some((message) => message.includes("禁止生产组件字段")));
-
-const h3Evidence = common("H3", "component-contract", { component_contract: {
-  implementation_repo_ref: "repo:frontend", lockfile_ref: "pnpm-lock.yaml", framework: "vue-3", component_library: "@yss-ui/components", component_library_version: "4.2.1", harness_ref: "storybook-static/index.html", story_refs: ["stories/approval.stories.ts"], real_component_verified: true,
-  main_flow_result: "passed", exceptional_state_result: "passed", keyboard_result: "passed", focus_result: "passed", contrast_result: "passed", zoom_200_result: "passed", reduced_motion_result: "passed", automated_visual_regression: { result: "passed", evidence_ref: "visual-regression.json" }
-} });
-assert(validatePrototypeEvidence(h3Evidence).errors.some((message) => message.includes("H1/H2")), "H3 必须被原型合同拒绝");
-
-const invalidHandoff = structuredClone(h2Evidence);
-invalidHandoff.implementation_handoff.verification_targets[0].target_stage = "prototype";
-assert(validatePrototypeEvidence(invalidHandoff).errors.some((message) => message.includes("前端实现阶段")));
-
-assert(validatePrototypeEvidence({ schema_version: 3 }).errors.some((message) => message.includes("只读旧证据")));
-assert.deepEqual(validatePrototypeEvidence({ schema_version: 3 }, { allowLegacy: true }).errors, []);
-
-function pngHeader(width, height) {
-  const value = Buffer.alloc(24);
-  Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]).copy(value, 0);
-  value.writeUInt32BE(13, 8); value.write("IHDR", 12, "ascii"); value.writeUInt32BE(width, 16); value.writeUInt32BE(height, 20);
-  return value;
-}
-const bundleRoot = path.join(projectRoot, "docs/.scratch", feature, "handoff/visual-baseline-v1");
-await mkdir(path.join(bundleRoot, "images"), { recursive: true });
-await mkdir(path.join(bundleRoot, "sources"), { recursive: true });
-await mkdir(path.join(bundleRoot, "capture"), { recursive: true });
-await writeFile(path.join(bundleRoot, "images/primary-desktop.png"), pngHeader(1440, 900));
-await writeFile(path.join(bundleRoot, "images/primary-narrow.png"), pngHeader(390, 844));
-await writeFile(path.join(bundleRoot, "sources/prototype.snapshot.html"), "<!doctype html><main>order review</main>\n");
-await writeFile(path.join(bundleRoot, "sources/interaction-spec.snapshot.md"), "# Interaction\n");
-await writeFile(path.join(bundleRoot, "sources/state-matrix.snapshot.md"), "# States\n");
-await writeFile(path.join(bundleRoot, "capture/capture.mjs"), "// deterministic capture\n");
-await writeFile(path.join(bundleRoot, "capture/result.json"), "{\"result\":\"passed\"}\n");
-const baselineFile = path.join(bundleRoot, "visual-baseline.yaml");
-const baseline = {
-  schema_version: 1, baseline_id: `visual-baseline.${feature}`, feature, version: "v1", status: "approved",
-  bundle: { format: "portable-directory", root_ref: `docs/.scratch/${feature}/handoff/visual-baseline-v1`, digest: `sha256:${"0".repeat(64)}`, size_bytes: 0, max_image_bytes: 5242880, max_bundle_bytes: 104857600 },
-  source: { prototype_ref: "sources/prototype.snapshot.html", prototype_digest: `sha256:${"1".repeat(64)}`, interaction_spec_ref: "sources/interaction-spec.snapshot.md", interaction_spec_digest: `sha256:${"2".repeat(64)}`, state_matrix_ref: "sources/state-matrix.snapshot.md", state_matrix_digest: `sha256:${"3".repeat(64)}` },
-  capture_environment: { browser: "chromium", browser_version: "140.0.0", operating_system: "linux", fonts_digest: `sha256:${"4".repeat(64)}`, device_scale_factor: 1, color_space: "srgb", locale: "zh-CN", timezone: "Asia/Shanghai", animations_disabled: true, cursor_hidden: true, capture_script_ref: "capture/capture.mjs", capture_script_digest: `sha256:${"5".repeat(64)}`, capture_result_ref: "capture/result.json", capture_result_digest: `sha256:${"6".repeat(64)}` },
-  cases: [
-    { case_id: "primary-desktop", route: "/orders", page: "OrderPage", state: "normal", viewport: { name: "desktop", width: 1440, height: 900, scroll_mode: "viewport", scroll_position: 0 }, theme: "compact-light", locale: "zh-CN", data_scenario: "primary", image_ref: "images/primary-desktop.png", image_digest: `sha256:${"0".repeat(64)}`, image_size_bytes: 1, mask_ref: "not-applicable", mask_digest: "not-applicable", mask_size_bytes: 0, semantic_refs: ["sources/prototype.snapshot.html", "sources/interaction-spec.snapshot.md"], allowed_differences: [], result: "passed" },
-    { case_id: "primary-narrow", route: "/orders", page: "OrderPage", state: "normal", viewport: { name: "narrow", width: 390, height: 844, scroll_mode: "viewport", scroll_position: 0 }, theme: "compact-light", locale: "zh-CN", data_scenario: "primary", image_ref: "images/primary-narrow.png", image_digest: `sha256:${"0".repeat(64)}`, image_size_bytes: 1, mask_ref: "not-applicable", mask_digest: "not-applicable", mask_size_bytes: 0, semantic_refs: ["sources/state-matrix.snapshot.md"], allowed_differences: [], result: "passed" }
-  ]
-};
-await writeFile(baselineFile, JSON.stringify(baseline, null, 2));
-const sealed = await sealVisualBaseline(baselineFile, bundleRoot);
-assert.deepEqual((await validateVisualBaseline(sealed, { bundleRoot })).errors, []);
-const tamperedDigest = structuredClone(sealed);
-tamperedDigest.cases[0].image_digest = `sha256:${"f".repeat(64)}`;
-assert((await validateVisualBaseline(tamperedDigest, { bundleRoot })).errors.some((message) => message.includes("image_digest 与文件不一致")));
-const missingNarrow = structuredClone(sealed);
-missingNarrow.cases = missingNarrow.cases.slice(0, 1);
-assert((await validateVisualBaseline(missingNarrow)).errors.some((message) => message.includes("390x844")));
-const badDpr = structuredClone(sealed);
-badDpr.capture_environment.device_scale_factor = 2;
-assert((await validateVisualBaseline(badDpr)).errors.some((message) => message.includes("device_scale_factor")));
-const traversal = structuredClone(sealed);
-traversal.source.prototype_ref = "../prototype.html";
-assert((await validateVisualBaseline(traversal)).errors.some((message) => message.includes("source.prototype_ref")));
-await writeFile(path.join(bundleRoot, "capture/unregistered.log"), "unexpected\n");
-assert((await validateVisualBaseline(sealed, { bundleRoot })).errors.some((message) => message.includes("未登记 payload")));
-
-process.stdout.write("YSS prototype profile contract scenarios passed\n");

package/template/.trae/skills/yss-repository/SKILL.md

@@ -1,44 +0,0 @@
----
-name: yss-repository
-description: 用于按批准的 YSS 架构与持久化合同实现或重构 PO、Repository、Convertor、Domain Gateway/Query Adapter；负责结构路由、分层边界和验证，不内置可照抄的业务代码模板。
----
-
-# yss-repository
-
-本 Skill 消费批准合同，将持久化责任落到选定架构 Profile。它不是完整脚手架，也不从 DDL、表名或示例反向创造领域/API 合同。
-
-## 架构分流
-
-1. 读取当前 Slice Implementation Contract 的 `architecture_identity`、`persistence_profile`、实现仓登记、数据合同、`allowed_write_paths` 和预期证据。
-2. 将架构身份与工程基线、Manifest 和 `docs/agents/yss-skill-registry.yaml` 核对；成熟度以注册表为准，不能把 `draft` 称为已支持。
-3. 根据 `architecture_profile` **且只**加载一个文件：
-   - [target-domain-model](references/profiles/target-domain-model.md)
-   - [layered-mvc-service](references/profiles/layered-mvc-service.md)
-   - [mvc-data-analysis-v1](references/profiles/mvc-data-analysis-v1.md)
-4. Profile 缺失、身份冲突、Manifest 漂移或数据输入不完整时返回 `blocked` / `drift` / `new_impacts`，不得选择“最像”的分支继续。
-
-## 共用规则
-
-- 只实现批准合同已有的结构与 seam，不创建或改写 Domain Gateway、Application Query Port、service/core 接口或 Web/API DTO。
-- 持久化 Profile 命中 MyBatis 时加载 `yss-mybatis`，以当前组件能力索引核验基类、分页、批量、扫描、XML 和数据源行为；本 Skill 不复制这些规则。
-- POJO、转换和 Java 规范分别消费 Registry 编译出的 `lombok`、`mapstruct`、`alibaba-java-code-style`；不在此重复其注解和处理器规则。
-- 数据合同必须显式覆盖主键、逻辑删除、审计字段、空值、枚举/值对象映射和敏感字段；动态排序、分组与过滤必须使用批准白名单和参数绑定。
-- 事务归所选 Profile 的用例边界。Repository/Gateway Adapter 不临时新增业务事务，也不把数据库异常原文或凭据暴露给上层。
-- 基础机械结构只有在合同标记 `controlled-generation`、metadata 完整且目标文件不存在时才可受控生成；查询语义、分页、并发、事务和迁移行为使用 `behavior-tdd`。
-- 发现 SQL、DDL、索引、数据模型或 API schema 新影响时立即暂停并返回 `new_impacts`，不能以 TODO 代替合同重编译。
-
-## 产物与证据
-
-实际产物由所选 Profile 和合同共同决定，不以固定示例类名或固定包路径推断。完成前至少证明：
-
-- 每个实现类对应已批准的端口或用例调用方；
-- Mapper/Repository、XML、扫描和转换实现可编译且被运行时发现；
-- 保存/重载、查询、分页、空结果、排序白名单和回滚等命中行为有测试；
-- 所有写入位于 `allowed_write_paths`；
-- 使用各后端项目根的 `./mvnw ...` 记录实际命令、退出码和时间。
-
-按 [YSS Skill Execution Result v2](../yss-implementation-contract-compiler/references/yss-skill-execution-result.md) 返回实际文件、测试、约束结果、`seam_deferred`、`deviations`、`new_impacts`、`drift` 和 `violation`。
-
-## Review 输入
-
-`code-review` 仅对本体项目及合同/实现仓登记的后端研发项目执行本 Skill。候选命中持久化结构或数据访问时，Standards 轴必须读取所选 Profile 并引用规则与代码证据；未命中时记录带原因的 `not-applicable`。Reviewer 只报告 finding，不写实现。

package/template/.trae/skills/yss-repository/agents/openai.yaml

@@ -1,5 +0,0 @@
-version: 1
-interface:
-  display_name: "YSS Repository"
-  short_description: "按架构 Profile 实现并验证 YSS 持久层结构"
-  default_prompt: "Use $yss-repository to route and implement persistence structures from an approved architecture profile and contract without inventing domain, service, or API contracts."

package/template/.trae/skills/yss-repository/references/profiles/layered-mvc-service.md

@@ -1,21 +0,0 @@
-# layered-mvc-service
-
-仅适用于注册表中 `architecture_family=layered-mvc`、用例层为 `service` 的当前合同。先读仓库 `docs/agents/backend-architecture-profiles.md`；Profile 的成熟度沿用注册表。
-
-## 前置与所有权
-
-- 已有批准的 service 用例接口、数据合同和查询/写入语义；不得从表结构反推 service 或 HTTP API。
-- repository module 拥有 PO、Repository/Mapper、XML 和持久化 Convertor；不生成 DDD Domain Gateway、Application Query Port 或 Web DTO。
-- repository 不反向依赖 service、server、client；事务、业务规则和幂等归 service 用例。
-
-## 结构决策
-
-- 包、module、Mapper 扫描和 XML 路径来自 `architecture_identity`、当前工程基线及合同，不使用 DDD Infrastructure 固定布局。
-- MyBatis-Plus 基类、分页、批量和数据源能力由 `yss-mybatis` 当前能力矩阵决定。
-- repository 输出 service 已批准的内部模型或结果，不泄漏 PO、原始 SQL、数据库异常原文或凭据。
-
-## 必须验证
-
-- service 是唯一业务事务边界，Controller 不直连 Repository。
-- Repository/Mapper 覆盖查询、写入、分页、回滚、字段转换和批准数据库 fixture。
-- H2 仅作为验证数据库；生产驱动和数据源必须由单独批准的存储工作单元接入。

package/template/.trae/skills/yss-repository/references/profiles/mvc-data-analysis-v1.md

@@ -1,21 +0,0 @@
-# mvc-data-analysis-v1
-
-仅适用于注册表中的数据分析 MVC Profile。先读仓库 `docs/agents/backend-architecture-profiles.md`；Profile 的成熟度沿用注册表。
-
-## 前置与所有权
-
-- 已有批准的数据合同、查询语义和 core 用例接口；不得从 DDL 或报表字段反推对外 API。
-- repository module 拥有 PO、Repository/Mapper、XML 和持久化 Convertor；不生成 DDD Gateway，也不依赖 core、client、server。
-- 事务、业务规则和查询编排归 core；repository 只实现批准的数据访问 seam。
-
-## 数据分析约束
-
-- 动态排序、分组、过滤、聚合字段和表来源必须来自批准白名单并使用参数绑定；客户端输入不得直接拼接 SQL 标识符或表达式。
-- MyBatis-Plus 基类、分页、批量和数据源能力由 `yss-mybatis` 当前能力矩阵决定，不假设组件提供动态数据源路由。
-- repository 不返回 HTTP DTO，不暴露原始 SQL、数据库错误原文或连接凭据。
-
-## 必须验证
-
-- 查询覆盖白名单边界、空值、空结果、分页 total、稳定排序和大数据量限制。
-- 数据库 fixture 验证实际 Mapper/XML 与方言；H2 不能证明生产数据库的函数、排序或执行计划。
-- core 是唯一业务事务边界，server 不直连 Repository。

package/template/.trae/skills/yss-repository/references/profiles/target-domain-model.md

@@ -1,23 +0,0 @@
-# target-domain-model
-
-仅适用于注册表中 `architecture_family=domain-driven` 的当前合同。Profile 的成熟度沿用注册表，不因加载本文件而升级。
-
-## 前置与所有权
-
-- 写模型必须已有批准的 Domain Gateway；读模型必须已有批准的 Application Query Port。缺失或需要改变签名时返回 `new_impacts`，由 `yss-domain` / `yss-application` 和实现合同编译器处理。
-- Infrastructure 实现既有端口，拥有 PO、Repository/Mapper、XML、持久化 Convertor、GatewayImpl 和 QueryAdapter；不拥有领域规则、HTTP DTO 或业务事务。
-- Domain Gateway 只交换 Aggregate、Domain Model、领域值和标识；分页、列表和读模型走 Application Query Port，`PageQuery` 不进入 Domain。
-
-## 结构决策
-
-- 包与 module 必须来自 `architecture_identity` 和现有工程基线；新脚手架的持久化责任位于 Infrastructure，既有工程不得因本 Skill 自动迁移目录。
-- 写模型转换覆盖 `PO <-> Domain Model`；读模型转换只到 Application Result。Infrastructure 不生成或返回 Web VO/CMD。
-- Repository 基类、Mapper/XML、分页与批量能力由 `yss-mybatis` 当前能力矩阵决定，不把组件版本方法名写成领域规则。
-- 事务归 Application 用例。GatewayImpl/QueryAdapter 只执行端口语义，不新增业务编排。
-
-## 必须验证
-
-- Domain 不反向依赖 Infrastructure、Mapper、PO 或组件类型。
-- 经 Domain Gateway 保存后可重新加载语义等价的 Aggregate。
-- Query Port 覆盖分页 total、空结果、排序/过滤白名单和字段转换。
-- Mapper/Repository 使用批准数据库 fixture；H2 不能证明生产方言。