create-yss-spec 3.0.0 → 3.1.0

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

@@ -1,154 +1,186 @@
 #!/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 {
-  preparePrototype,
-  validatePrototypeEvidence,
-  validatePrototypeProject
-} from "../scripts/prototype-contract.mjs";
+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";
-const prototypeRoot = path.join(projectRoot, "docs/.scratch", feature, "design/prototypes");
-await mkdir(path.join(prototypeRoot, "src"), { recursive: true });
 await mkdir(path.join(projectRoot, "docs/design/tokens"), { recursive: true });
-await writeFile(path.join(prototypeRoot, "package.json"), JSON.stringify({
-  name: "order-review-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 writeFile(path.join(projectRoot, "docs/design/tokens/theme.json"), JSON.stringify({
-  algorithm: "default",
-  token: {
-    colorPrimary: "#3371ff",
-    borderRadius: 6,
-    controlHeight: 32,
-    layoutHeaderHeight: 64
-  }
-}, null, 2));
+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 before = await validatePrototypeProject({ root: prototypeRoot, targetAntdVersion: "6.6.2" });
-assert(before.errors.some((message) => message.includes("antd")), "RED: starter without antd must fail");
-assert(before.errors.some((message) => message.includes("pnpm-lock.yaml")), "RED: missing pnpm lockfile must fail");
+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 必须拒绝伪构建依赖");
 
-await preparePrototype({ projectRoot, root: prototypeRoot, feature, targetAntdVersion: "6.6.2", pnpmVersion: "10.15.0" });
-const pkg = JSON.parse(await readFile(path.join(prototypeRoot, "package.json"), "utf8"));
-assert.equal(pkg.dependencies.antd, "6.6.2");
-assert.equal(pkg.packageManager, "pnpm@10.15.0");
-assert.match(await readFile(path.join(prototypeRoot, "src/yss-theme.js"), "utf8"), /compactAlgorithm/);
+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("精确锁定")));
 
-await writeFile(path.join(prototypeRoot, "pnpm-lock.yaml"), "lockfileVersion: '9.0'\n");
-await writeFile(path.join(prototypeRoot, "src/App.jsx"), [
-  'import { ConfigProvider, Button } from "antd";',
-  'import { yssTheme } from "./yss-theme.js";',
-  'export function App() { return <ConfigProvider theme={yssTheme}><Button type="primary">提交</Button></ConfigProvider>; }'
-].join("\n"));
-const after = await validatePrototypeProject({ root: prototypeRoot, targetAntdVersion: "6.6.2" });
-assert.deepEqual(after.errors, []);
+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, []);
 
-const wrongTarget = await validatePrototypeProject({ root: prototypeRoot, targetAntdVersion: "6.6.1" });
-assert(wrongTarget.errors.some((message) => message.includes("精确锁定 antd 6.6.1")), "target 与实际 antd 版本不一致必须失败");
-
-const npmPackage = structuredClone(pkg);
-npmPackage.packageManager = "npm@11.0.0";
-await writeFile(path.join(prototypeRoot, "package.json"), JSON.stringify(npmPackage, null, 2));
-const npmProject = await validatePrototypeProject({ root: prototypeRoot, targetAntdVersion: "6.6.2" });
-assert(npmProject.errors.some((message) => message.includes("packageManager")), "原型包管理器漂移到 npm 必须失败");
-await writeFile(path.join(prototypeRoot, "package.json"), JSON.stringify(pkg, null, 2));
-
-await assert.rejects(
-  preparePrototype({
-    projectRoot,
-    root: path.join(projectRoot, "prototypes", feature),
+function common(profile, kind, block) {
+  const data = {
+    schema_version: 4,
     feature,
-    targetAntdVersion: "6.6.2",
-    pnpmVersion: "10.15.0"
-  }),
-  /docs\/.scratch/,
-  "非标准原型目录必须被拒绝"
-);
+    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 validEvidence = {
-  schema_version: 2,
-  feature,
-  prototype_ref: `docs/.scratch/${feature}/design/prototypes/index.html`,
-  prototype_stack: {
-    framework: "react",
-    package_manager: "pnpm",
-    package_manifest_ref: `docs/.scratch/${feature}/design/prototypes/package.json`,
-    lockfile_ref: `docs/.scratch/${feature}/design/prototypes/pnpm-lock.yaml`,
-    source_entry_ref: `docs/.scratch/${feature}/design/prototypes/src/App.jsx`,
-    build_entry_ref: `docs/.scratch/${feature}/design/prototypes/dist/index.html`,
-    build_command: "pnpm build",
-    build_result: "passed",
-    actual_antd_version: "6.6.2"
-  },
-  design_baseline: {
-    design_standard: "ant-design-v6",
-    project_design_ref: "docs/design/design.md",
-    project_token_refs: ["docs/design/tokens/theme.json"],
-    theme_adapter_ref: `docs/.scratch/${feature}/design/prototypes/src/yss-theme.js`,
-    project_override_reviewed: true
-  },
-  visual_semantic_mapping: {
-    runtime_component_library: "ant-design-vue-4.x",
-    runtime_version_source: "implementation-lockfile",
-    components: [{
-      semantic_role: "primary-action",
-      antd_v6_component: "Button",
-      project_token_refs: ["colorPrimary"],
-      yss_or_antdv_target: "YButton",
-      state_mapping: ["default", "hover", "active", "disabled", "loading"],
-      react_only_api_not_copied: true,
-      verification_ref: "verification/button-states.png"
-    }]
-  },
-  antd: { target_antd_version: "6.6.2", queries: { design_md: "verification/antd-design.json", components: [] } },
-  browser_verification: { rendered_nonblank: true, viewports: [], main_flow_result: "passed", failure_permission_or_conflict_result: "passed", console_error_ref: "verification/console.txt" },
-  design_qa: { report_ref: `docs/.scratch/${feature}/verification/design-qa.md`, result: "passed" },
-  accessibility_verification: {
-    contrast_results_ref: "verification/contrast.json",
-    keyboard_navigation_result: "passed",
-    focus_visible_and_order_result: "passed",
-    semantic_label_dialog_result: "passed",
-    zoom_200_result: "passed",
-    reduced_motion_result: "passed",
-    target_size_result: "passed",
-    automated_scan: { tool: "axe", version: "4", result: "passed", ref: "verification/axe.json" }
-  },
-  review: { prototype_review_ref: "design/review.md", result: "approved" },
-  user_confirmation: { confirmation_ref: "design/confirmation.md", result: "approved" },
-  blockers: []
-};
-assert.deepEqual(validatePrototypeEvidence(validEvidence).errors, []);
+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 missingMapping = structuredClone(validEvidence);
-delete missingMapping.visual_semantic_mapping;
-assert(validatePrototypeEvidence(missingMapping).errors.some((message) => message.includes("visual_semantic_mapping")));
+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 copiedReactApi = structuredClone(validEvidence);
-copiedReactApi.visual_semantic_mapping.components[0].react_only_api_not_copied = false;
-assert(validatePrototypeEvidence(copiedReactApi).errors.some((message) => message.includes("React-only")));
+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 inaccessible = structuredClone(validEvidence);
-inaccessible.accessibility_verification.contrast_results_ref = "";
-assert(validatePrototypeEvidence(inaccessible).errors.some((message) => message.includes("contrast_results_ref")));
+const invalidHandoff = structuredClone(h2Evidence);
+invalidHandoff.implementation_handoff.verification_targets[0].target_stage = "prototype";
+assert(validatePrototypeEvidence(invalidHandoff).errors.some((message) => message.includes("前端实现阶段")));
 
-const wrongQaRoot = structuredClone(validEvidence);
-wrongQaRoot.design_qa.report_ref = "docs/design/design-qa.md";
-assert(validatePrototypeEvidence(wrongQaRoot).errors.some((message) => message.includes("design_qa.report_ref")));
+assert(validatePrototypeEvidence({ schema_version: 3 }).errors.some((message) => message.includes("只读旧证据")));
+assert.deepEqual(validatePrototypeEvidence({ schema_version: 3 }, { allowLegacy: true }).errors, []);
 
-const versionMismatch = structuredClone(validEvidence);
-versionMismatch.antd.target_antd_version = "6.6.1";
-assert(validatePrototypeEvidence(versionMismatch).errors.some((message) => message.includes("target_antd_version")));
-
-const unresolvedBlocker = structuredClone(validEvidence);
-unresolvedBlocker.blockers = ["缺少权限失败态"];
-assert(validatePrototypeEvidence(unresolvedBlocker).errors.some((message) => message.includes("blockers")));
+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 contract scenarios passed\n");
+process.stdout.write("YSS prototype profile contract scenarios passed\n");

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

@@ -5,6 +5,12 @@ description: Use when generating or refactoring YSS Infrastructure persistence m
 
 # yss-repository
 
+## 架构分流（先执行）
+
+读取当前合同的 architecture_identity 并与工程基线、仓库登记及 Manifest 核对；再且只读取 `references/profiles/<architecture_profile>.md`。支持的分支为 target-domain-model、layered-mvc-service、mvc-data-analysis-v1；成熟度以注册表为准，不能把 draft 称为受支持。MVC 不执行下文 DDD 专属规则，也不加载其旧分层 guide；组件、安全、批准合同、允许路径及执行证据规则仍共用。
+
+以下 Application / Domain Gateway / Infrastructure / Web module 叙述仅适用于 target-domain-model；MVC 的 service/core/repository/server/client 所有权由所选 Profile 引用定义。
+
 这是一个偏代码生成和结构补全的 skill，适合在已有工程里补 Repository 层，不适合替代完整脚手架。
 
 ## 何时使用
@@ -43,7 +49,7 @@ description: Use when generating or refactoring YSS Infrastructure persistence m
 
 - Domain 不依赖 Infrastructure。
 - Gateway 定义在 Domain，实现放在 Infrastructure。
-- `yss-repository` 不创建或改写 Domain Gateway interface；缺少或需要改变 Gateway 时返回 `new_impacts`，由 Router 回到 `yss-domain` / `yss-tactical-design`。
+- `yss-repository` 不创建或改写 Domain Gateway interface；缺少或需要改变 Gateway 时返回 `new_impacts`，由 实现合同编译器 回到 `yss-domain` / `yss-tactical-design`。
 - Domain Gateway 只交换 Domain Model、领域值和标识；分页、列表和读模型走 Application Query Port，禁止返回 Web VO 或把 `PageQuery` 带入 Domain。
 - PO / Domain Model 等 POJO 样板代码优先使用 Lombok；不要成片手写 getter/setter、constructor、builder 或 logger。
 - Convertor 必须优先使用 `@Mapper(componentModel = "spring")` 和构造器注入；禁止静态 `INSTANCE`、`BeanUtils.copyProperties`、反射式通用拷贝和重复手写字段赋值，除非实现合同记录受控例外、测试和 review 证据。
@@ -74,7 +80,7 @@ description: Use when generating or refactoring YSS Infrastructure persistence m
 
 ## 阶段 7 合同
 
-- 前置条件：数据架构、领域元数据、实现仓库和批准后的 `Slice Implementation Contract` 均可用；否则不执行本 skill，由 Router 返回 `blocked`。
+- 前置条件：数据架构、领域元数据、实现仓库和批准后的 `Slice Implementation Contract` 均可用；否则不执行本 skill，由 实现合同编译器 返回 `blocked`。
 - PO/Repository/Convertor 骨架可使用 `controlled-generation`；复杂过滤、分页语义、并发、事务和迁移行为必须拆为 `behavior-tdd`。
 - 写入仅限合同 `allowed_write_paths`，证据必须包含实际 PO、Repository、Convertor、GatewayImpl、测试和 `./mvnw ...` 结果。
 - 按统一 `YSS Skill Execution Result` 返回 `seam_deferred/deviations/new_impacts`；发现数据模型、DDL、SQL、索引或 API schema 变化时暂停并重路由。

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

@@ -0,0 +1,3 @@
+# layered-mvc-service
+
+先读仓库 `docs/agents/backend-architecture-profiles.md`。依据批准的数据合同写入 repository 的 po/repository/convertor 及 Mapper XML；无需领域模型或 Gateway。使用 `yss-mybatis` 的 MyBatis-Plus 体系；保留 cause，避免向上暴露原始 SQL/凭据。事务由 service 用例拥有。测试覆盖查询、分页、回滚与字段转换；H2 不证明生产方言。生产驱动/数据源接入须另有批准的存储工作单元。

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

@@ -0,0 +1,3 @@
+# mvc-data-analysis-v1
+
+遵守 `layered-mvc-service.md`，但事务所有者为 `core`。repository 不依赖 core/client/server，不生成 DDD Gateway。数据分析的动态排序、分组、过滤均须白名单及参数绑定；只消费批准的数据和查询合同。

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

@@ -0,0 +1,3 @@
+# target-domain-model
+
+完整执行规则见 `../infrastructure-layer-guide.md`。Domain Gateway 和 Application Query Port 必须已存在；本 Skill 只在 Infrastructure 实现，不反向创建领域端口。事务归 Application。

package/template/.trae/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/.trae/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/.trae/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/.trae/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/.trae/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/.trae/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/.trae/skills/yss-skill-source-index-refresh/references/source-map-config.md

@@ -0,0 +1,29 @@
+# YSS Source Index Mapping
+
+The refresh script maps component source path hints to skill references. These paths are relative to the detected or configured `YSS_SOURCE_ROOT`; they are not guaranteed to exist in every workspace.
+
+中文说明：这个文件记录“哪个组件源码目录生成到哪个 skill 的引用索引”，方便你以后维护映射关系。
+
+| Skill | Backend source path hints |
+| --- | --- |
+| `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` |
+
+Frontend docs are written to these skills:
+
+| Skill | Frontend references |
+| --- | --- |
+| `yss-ui` | components, hooks, skills docs |
+| `yss-components` | components docs |
+| `yss-hook` | hooks docs |
+| `yss-use-table-height` | hooks docs |
+| `yss-use-tree-height` | hooks docs |

package/template/.trae/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-ui-business-page-generation":["components","hooks","skills"],"yss-use-table-height":["hooks"],"yss-use-tree-height":["hooks"]};
+const URLS={components:"http://192.168.164.27:3200/components",hooks:"http://192.168.164.27:3200/hooks",skills:"http://192.168.164.27:3200/skills"};
+const KEYS=["Audit","Cache","Clear","Command","Configuration","Controller","DTO","Data","Enable","Excel","Handler","Interceptor","Jdbc","Mapper","Mybatis","Page","Properties","Query","Repository","Request","Response","Result","Update","Aspect","Leaf","Id","Dir","Dic","Dictionary","File","Upload","Log","Message","Mail","Liquibase","Circuit","Breaker","Sql","Tpl","Tag","Task","Flow","Report","Validation","Validator","Security","Crypto","User","Variable","Quality","Search","Similarity","Scheduler","Runner","Duck","Dynamic","Factory","Client","Feign","Gateway","Convertor","Adapter","Advice","Bridge","Route","Uploader","Sftp","Minio","Parser","Express","Rule","Template","Generator","Importer","Engine","Event","Submitter","Executor","Context","Status","Type","State"];
+const DOCS=new Set(["README.md","readme.md","HELP.md","TECHNICAL_DESIGN.md"]);
+const exists=async p=>{try{await access(p);return true}catch{return false}};
+async function walk(root){if(!await exists(root))return[];const out=[];for(const item of await readdir(root,{withFileTypes:true})){const p=path.join(root,item.name);if(item.isDirectory())out.push(...await walk(p));else if(item.isFile())out.push(p)}return out}
+const relative=(root,p)=>{const value=path.relative(root,p);return value&&!value.startsWith("..")?value:p};
+function state(root){try{const run=args=>execFileSync("git",["-C",root,...args],{encoding:"utf8",stdio:["ignore","pipe","ignore"]}).trim();return[run(["rev-parse","HEAD"]),run(["status","--porcelain"])?"dirty":"clean"]}catch{return["unavailable","unknown"]}}
+async function sourceRoot(){if(process.env.YSS_SOURCE_ROOT){const root=path.resolve(process.env.YSS_SOURCE_ROOT);if(await exists(path.join(root,"yss-microservice-components")))return root;throw new Error(`YSS_SOURCE_ROOT must point to the repository root containing \`yss-microservice-components\`: ${root}`)}const home=os.homedir(),candidates=[process.cwd(),...ancestors(process.cwd()),path.join(home,"Documents/yss-project/yss-cloud-microservice"),path.join(home,"Documents/yss-project"),path.join(home,"Projects/yss-cloud-microservice"),path.join(home,"Projects")];for(const base of [path.join(home,"Projects"),path.join(home,"Documents"),path.join(home,"Documents/yss-project")])if(await exists(base))for(const entry of await readdir(base,{withFileTypes:true}))if(entry.isDirectory())candidates.push(path.join(base,entry.name));for(const root of candidates)if(await exists(path.join(root,"yss-microservice-components")))return path.resolve(root);throw new Error("Could not find a YSS source repository containing `yss-microservice-components`. Export YSS_SOURCE_ROOT=/absolute/path/to/yss-cloud-microservice and rerun.")}
+function ancestors(start){const out=[];let current=path.resolve(start);while(path.dirname(current)!==current){current=path.dirname(current);out.push(current)}return out}
+async function files(bases){const out={docs:[],poms:[],java:[]};for(const base of bases)for(const p of await walk(base)){if(DOCS.has(path.basename(p)))out.docs.push(p);else if(path.basename(p)==="pom.xml")out.poms.push(p);else if(p.endsWith(".java")&&p.includes(`${path.sep}src${path.sep}main${path.sep}java${path.sep}`))out.java.push(p)}for(const a of Object.values(out))a.sort();return out}
+export async function refresh({skillsRoot,source,now=new Date().toISOString(),frontend=true}){const [commit,worktree]=state(source);for(const [skill,parts]of Object.entries(BACKEND)){const bases=parts.map(item=>path.join(source,item));const found=await files(bases);const java=found.java.filter(p=>KEYS.some(key=>path.basename(p,".java").includes(key))).slice(0,120);const list=(items,map,empty)=>items.length?items.map(map):[empty];const baseHints=await Promise.all(bases.map(async p=>`- \`${relative(source,p)}\` (${await exists(p)?"existed":"missing"} when indexed)`));const lines=[`# ${skill} Source Index`,``,`Generated: ${now}`,`Source commit: \`${commit}\``,`Source worktree: \`${worktree}\``,`Indexed source root: resolved at refresh time; set \`YSS_SOURCE_ROOT\` to reproduce or refresh.`,``,`This file is generated by \`yss-skill-source-index-refresh/scripts/refresh-yss-skill-index.mjs\`. Do not hand-edit generated sections.`,``,`Paths below are source path hints captured at refresh time. If they do not exist in the current workspace, locate sources using \`YSS_SOURCE_ROOT\`, CodeGraph, package/class names, Maven artifact names, or repository search before assuming the source is unavailable.`,``,`## Component Path Hints`,``,...baseHints,``,`## Documentation Files`,``,...list(found.docs,p=>`- \`${relative(source,p)}\``,"- No component documentation files found."),``,`## Maven Modules`,``,...list(found.poms,p=>`- \`${relative(source,path.dirname(p))}\``,"- No Maven modules found."),``,`## Key Java Entry Points`,``,...list(java,p=>`- \`${relative(source,p)}\``,"- No key Java entry points matched the configured name patterns."),``,`## Recommended Next Reads`,``,`- Start with the documentation files above when learning component usage.`,`- Search the key Java entry points for annotations, auto configuration, properties, aspects, interceptors, handlers, and result objects before changing application code.`,`- Prefer existing component extension points over rewriting framework logic in business modules.`,``];const target=path.join(skillsRoot,skill,"references","source-index.md");await mkdir(path.dirname(target),{recursive:true});await writeFile(target,lines.join("\n"),"utf8")}
+ if(frontend)for(const[skill,keys]of Object.entries(FRONTEND)){if(!await exists(path.join(skillsRoot,skill)))continue;const target=path.join(skillsRoot,skill,"references","frontend-docs.md");await mkdir(path.dirname(target),{recursive:true});await writeFile(target,[`# ${skill} Frontend Documentation`,``,`Generated: ${now}`,``,`Use these YSS UI documentation entry points as authoritative references when local repo examples are insufficient.`,``,...keys.map(key=>`- ${key}: ${URLS[key]}`),``,`When documentation and local code differ, inspect the current project code before editing and prefer established local usage.`,``].join("\n"),"utf8")}
+ return{backend:Object.keys(BACKEND).length,frontend:frontend?Object.keys(FRONTEND).length:0}}
+async function main(){try{const script=path.dirname(fileURLToPath(import.meta.url));const result=await refresh({skillsRoot:path.resolve(process.env.YSS_SKILLS_ROOT||path.join(script,"../..")),source:await sourceRoot(),frontend:!["0","false","no"].includes((process.env.YSS_REFRESH_FRONTEND||"true").toLowerCase())});console.log(`Updated ${result.backend} backend indexes and ${result.frontend} frontend doc references.`)}catch(error){console.error(error.message);process.exitCode=1}}
+if(process.argv[1]===fileURLToPath(import.meta.url))await main();