create-yss-spec 2.2.7 → 2.2.9

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

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { parseDocument } from "../../../../scripts/vendor/yaml.mjs";
+
+const nonEmpty = (value) => typeof value === "string" && value.trim().length > 0;
+const object = (value) => value && typeof value === "object" && !Array.isArray(value);
+const semver = /^6\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?$/;
+const pnpmSemver = /^[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?$/;
+
+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 requiredPassed(data, field, parent, errors) {
+  requiredString(data, field, parent, errors);
+  if (object(data) && nonEmpty(data[field]) && !["passed", "approved"].includes(data[field])) errors.push(`${parent}.${field} 必须为 passed/approved`);
+}
+
+export function validatePrototypeEvidence(data, { allowTemplate = false, allowLegacy = false } = {}) {
+  const errors = [];
+  const warnings = [];
+  if (!object(data)) return { errors: ["原型证据必须是对象"], warnings };
+  if (data.schema_version === 1) {
+    if (!allowLegacy) errors.push("schema_version 1 是旧证据；完成 gate.prototype-verified 前必须迁移到 2，或只读时显式 --allow-legacy");
+    else warnings.push("legacy prototype evidence schema v1");
+    return { errors, warnings };
+  }
+  if (data.schema_version !== 2) errors.push("schema_version 必须为 2");
+  for (const field of ["feature", "prototype_ref", "prototype_stack", "design_baseline", "visual_semantic_mapping", "antd", "browser_verification", "design_qa", "accessibility_verification", "review", "user_confirmation", "blockers"]) required(data, field, "root", errors);
+
+  const templateValue = (value) => allowTemplate && nonEmpty(value) && /<[^>]+>/.test(value);
+  const stack = data.prototype_stack;
+  if (object(stack)) {
+    for (const field of ["framework", "package_manager", "package_manifest_ref", "lockfile_ref", "source_entry_ref", "build_entry_ref", "build_command", "build_result", "actual_antd_version"]) requiredString(stack, field, "prototype_stack", errors);
+    if (stack.framework !== "react") errors.push("prototype_stack.framework 必须为 react");
+    if (stack.package_manager !== "pnpm") errors.push("prototype_stack.package_manager 必须为 pnpm");
+    if (nonEmpty(stack.lockfile_ref) && !stack.lockfile_ref.endsWith("pnpm-lock.yaml")) errors.push("prototype_stack.lockfile_ref 必须指向 pnpm-lock.yaml");
+    if (!templateValue(stack.actual_antd_version) && nonEmpty(stack.actual_antd_version) && !semver.test(stack.actual_antd_version)) errors.push("prototype_stack.actual_antd_version 必须是明确的 antd 6.x semver");
+    if (!allowTemplate) requiredPassed(stack, "build_result", "prototype_stack", errors);
+  }
+
+  const baseline = data.design_baseline;
+  if (object(baseline)) {
+    for (const field of ["design_standard", "project_design_ref", "project_token_refs", "theme_adapter_ref", "project_override_reviewed"]) required(baseline, field, "design_baseline", errors);
+    if (baseline.design_standard !== "ant-design-v6") errors.push("design_baseline.design_standard 必须为 ant-design-v6");
+    if (!Array.isArray(baseline.project_token_refs) || baseline.project_token_refs.length === 0) errors.push("design_baseline.project_token_refs 必须是非空数组");
+    if (!allowTemplate && baseline.project_override_reviewed !== true) errors.push("design_baseline.project_override_reviewed 必须为 true");
+  }
+
+  const mapping = data.visual_semantic_mapping;
+  if (object(mapping)) {
+    if (mapping.runtime_component_library !== "ant-design-vue-4.x") errors.push("visual_semantic_mapping.runtime_component_library 必须为 ant-design-vue-4.x");
+    if (mapping.runtime_version_source !== "implementation-lockfile") errors.push("visual_semantic_mapping.runtime_version_source 必须为 implementation-lockfile");
+    if (!Array.isArray(mapping.components) || mapping.components.length === 0) errors.push("visual_semantic_mapping.components 必须是非空数组");
+    for (const [index, component] of (mapping.components ?? []).entries()) {
+      const parent = `visual_semantic_mapping.components[${index}]`;
+      for (const field of ["semantic_role", "antd_v6_component", "project_token_refs", "yss_or_antdv_target", "state_mapping", "react_only_api_not_copied", "verification_ref"]) required(component, field, parent, errors);
+      if (!Array.isArray(component?.project_token_refs) || component.project_token_refs.length === 0) errors.push(`${parent}.project_token_refs 必须是非空数组`);
+      if (!Array.isArray(component?.state_mapping) || component.state_mapping.length === 0) errors.push(`${parent}.state_mapping 必须是非空数组`);
+      if (!allowTemplate && component?.react_only_api_not_copied !== true) errors.push(`${parent}.React-only API 未确认隔离`);
+    }
+  }
+
+  if (object(data.antd)) {
+    requiredString(data.antd, "target_antd_version", "antd", errors);
+    if (object(stack) && nonEmpty(data.antd.target_antd_version) && nonEmpty(stack.actual_antd_version) && !templateValue(data.antd.target_antd_version) && data.antd.target_antd_version !== stack.actual_antd_version) errors.push("antd.target_antd_version 必须与 prototype_stack.actual_antd_version 一致");
+  }
+  if (object(data.design_qa)) {
+    requiredString(data.design_qa, "report_ref", "design_qa", errors);
+    requiredString(data.design_qa, "result", "design_qa", errors);
+    if (nonEmpty(data.design_qa.report_ref) && !/^docs\/\.scratch\/[^/]+\/verification\/design-qa\.md$/.test(data.design_qa.report_ref) && !templateValue(data.design_qa.report_ref)) errors.push("design_qa.report_ref 必须是 feature 级 verification/design-qa.md");
+    if (!allowTemplate) requiredPassed(data.design_qa, "result", "design_qa", errors);
+  }
+  const accessibility = data.accessibility_verification;
+  if (object(accessibility)) {
+    for (const field of ["contrast_results_ref", "keyboard_navigation_result", "focus_visible_and_order_result", "semantic_label_dialog_result", "zoom_200_result", "reduced_motion_result", "target_size_result", "automated_scan"]) required(accessibility, field, "accessibility_verification", errors);
+    requiredString(accessibility, "contrast_results_ref", "accessibility_verification", errors);
+    if (!allowTemplate) for (const field of ["keyboard_navigation_result", "focus_visible_and_order_result", "semantic_label_dialog_result", "zoom_200_result", "reduced_motion_result", "target_size_result"]) requiredPassed(accessibility, field, "accessibility_verification", errors);
+    if (object(accessibility.automated_scan)) for (const field of ["tool", "version", "result", "ref"]) requiredString(accessibility.automated_scan, field, "accessibility_verification.automated_scan", errors);
+  }
+  if (!Array.isArray(data.blockers)) errors.push("root.blockers 必须是数组");
+  if (!allowTemplate && Array.isArray(data.blockers) && data.blockers.length > 0) errors.push("存在 blockers，不能通过原型验证");
+  return { errors, warnings };
+}
+
+function safePrototypeRoot(projectRoot, root, feature) {
+  const resolvedProject = path.resolve(projectRoot);
+  const resolvedRoot = path.resolve(root);
+  const expected = path.resolve(resolvedProject, "docs/.scratch", feature, "design/prototypes");
+  if (resolvedRoot !== expected) throw new TypeError(`原型目录必须精确匹配 ${expected}`);
+  if (!resolvedRoot.startsWith(`${resolvedProject}${path.sep}`)) throw new TypeError("原型目录越出项目根");
+  return { resolvedProject, resolvedRoot };
+}
+
+export async function preparePrototype({ projectRoot, root, feature, targetAntdVersion, pnpmVersion }) {
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(feature ?? "")) throw new TypeError("feature 必须是小写 kebab-case");
+  if (!semver.test(targetAntdVersion ?? "")) throw new TypeError("targetAntdVersion 必须是明确的 antd 6.x semver");
+  if (!pnpmSemver.test(pnpmVersion ?? "")) throw new TypeError("pnpmVersion 必须是明确 semver");
+  const { resolvedProject, resolvedRoot } = safePrototypeRoot(projectRoot, root, feature);
+  const packagePath = path.join(resolvedRoot, "package.json");
+  if (!existsSync(packagePath)) throw new TypeError(`缺少 Product Design starter package.json: ${packagePath}`);
+  const pkg = JSON.parse(await readFile(packagePath, "utf8"));
+  pkg.packageManager = `pnpm@${pnpmVersion}`;
+  pkg.dependencies = { ...(pkg.dependencies ?? {}), "@ant-design/icons": "^6.0.0", antd: targetAntdVersion };
+  await writeFile(packagePath, `${JSON.stringify(pkg, null, 2)}\n`);
+
+  const themeSourcePath = path.join(resolvedProject, "docs/design/tokens/theme.json");
+  if (!existsSync(themeSourcePath)) throw new TypeError(`缺少项目主题: ${themeSourcePath}`);
+  const themeSource = JSON.parse(await readFile(themeSourcePath, "utf8"));
+  const generated = [
+    'import { theme } from "antd";',
+    "",
+    `const source = ${JSON.stringify(themeSource, null, 2)};`,
+    'const layoutKeys = new Set(["layoutHeaderHeight", "layoutSiderBackground", "layoutBodyBackground"]);',
+    "export const yssLayoutTokens = Object.fromEntries(Object.entries(source.token ?? {}).filter(([key]) => layoutKeys.has(key)));",
+    "export const yssTheme = {",
+    "  algorithm: [theme.defaultAlgorithm, theme.compactAlgorithm],",
+    "  token: Object.fromEntries(Object.entries(source.token ?? {}).filter(([key]) => !layoutKeys.has(key)))",
+    "};",
+    ""
+  ].join("\n");
+  await mkdir(path.join(resolvedRoot, "src"), { recursive: true });
+  await writeFile(path.join(resolvedRoot, "src/yss-theme.js"), generated);
+  const manifest = {
+    schema_version: 1,
+    feature,
+    design_standard: "ant-design-v6",
+    target_antd_version: targetAntdVersion,
+    prototype_framework: "react",
+    package_manager: `pnpm@${pnpmVersion}`,
+    theme_source: "docs/design/tokens/theme.json",
+    theme_adapter: `docs/.scratch/${feature}/design/prototypes/src/yss-theme.js`,
+    production_runtime: { framework: "vue-3", component_library: "ant-design-vue-4.x", version_source: "implementation-lockfile" },
+    next_commands: ["pnpm install", "pnpm build"]
+  };
+  await writeFile(path.join(resolvedRoot, "yss-prototype-adapter.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+  return manifest;
+}
+
+export async function validatePrototypeProject({ root, targetAntdVersion }) {
+  const errors = [];
+  const packagePath = path.join(root, "package.json");
+  if (!existsSync(packagePath)) return { errors: ["缺少 package.json"] };
+  const pkg = JSON.parse(await readFile(packagePath, "utf8"));
+  if (pkg.dependencies?.antd !== targetAntdVersion) errors.push(`package.json 必须精确锁定 antd ${targetAntdVersion}`);
+  if (!String(pkg.packageManager ?? "").startsWith("pnpm@")) errors.push("package.json 必须记录实际 pnpm packageManager");
+  if (!existsSync(path.join(root, "pnpm-lock.yaml"))) errors.push("缺少 pnpm-lock.yaml");
+  if (!existsSync(path.join(root, "src/yss-theme.js"))) errors.push("缺少 src/yss-theme.js");
+  const sourceFiles = ["src/App.jsx", "src/App.tsx", "src/main.jsx", "src/main.tsx"].filter((file) => existsSync(path.join(root, file)));
+  const source = (await Promise.all(sourceFiles.map((file) => readFile(path.join(root, file), "utf8")))).join("\n");
+  if (!/ConfigProvider/.test(source) || !/yssTheme/.test(source)) errors.push("原型入口必须通过 ConfigProvider 消费 yssTheme");
+  if (!existsSync(path.join(root, "yss-prototype-adapter.json"))) errors.push("缺少 yss-prototype-adapter.json");
+  return { errors };
+}
+
+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 loadYaml(file) {
+  const document = parseDocument(await readFile(file, "utf8"), { uniqueKeys: true });
+  if (document.errors.length > 0) throw new TypeError(document.errors[0].message);
+  return document.toJS({ maxAliasCount: 0 });
+}
+
+async function main(argv) {
+  const parsed = args(argv);
+  const command = parsed._[0];
+  if (command === "prepare") {
+    const result = await preparePrototype({ projectRoot: parsed["project-root"], root: parsed.root, feature: parsed.feature, targetAntdVersion: parsed["target-antd-version"], pnpmVersion: parsed["pnpm-version"] });
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return;
+  }
+  if (command === "validate-project") {
+    const result = await validatePrototypeProject({ root: parsed.root, targetAntdVersion: parsed["target-antd-version"] });
+    if (result.errors.length > 0) throw new TypeError(result.errors.join("\n"));
+    process.stdout.write("prototype project contract passed\n");
+    return;
+  }
+  if (command === "validate-evidence") {
+    const result = validatePrototypeEvidence(await loadYaml(parsed._[1]), { allowTemplate: Boolean(parsed["allow-template"]), allowLegacy: Boolean(parsed["allow-legacy"]) });
+    if (result.errors.length > 0) throw new TypeError(result.errors.join("\n"));
+    process.stdout.write(`prototype evidence passed${result.warnings.length ? ` with warnings: ${result.warnings.join(", ")}` : ""}\n`);
+    return;
+  }
+  throw new TypeError("usage: prototype-contract.mjs prepare|validate-project|validate-evidence ...");
+}
+
+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

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+import assert from "node:assert/strict";
+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";
+
+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));
+
+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");
+
+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/);
+
+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 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),
+    feature,
+    targetAntdVersion: "6.6.2",
+    pnpmVersion: "10.15.0"
+  }),
+  /docs\/.scratch/,
+  "非标准原型目录必须被拒绝"
+);
+
+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 missingMapping = structuredClone(validEvidence);
+delete missingMapping.visual_semantic_mapping;
+assert(validatePrototypeEvidence(missingMapping).errors.some((message) => message.includes("visual_semantic_mapping")));
+
+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 inaccessible = structuredClone(validEvidence);
+inaccessible.accessibility_verification.contrast_results_ref = "";
+assert(validatePrototypeEvidence(inaccessible).errors.some((message) => message.includes("contrast_results_ref")));
+
+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")));
+
+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")));
+
+process.stdout.write("YSS prototype contract scenarios passed\n");

package/template/.trae/skills/yss-router/references/boundaries.md

@@ -15,7 +15,7 @@ Use this reference when multiple YSS skills seem applicable.
 - `yss-use-table-height`: Only table available-height calculation and required container/pagination/toolbar wiring.
 - `yss-use-tree-height`: Only tree available-height calculation, search offset, and virtual scrolling wiring.
 
-Default for a new page: first verify the approved product design, state matrix, Ant Design v6 high-fidelity HTML prototype, AntD CLI evidence, and user confirmation; then start with `yss-page-module-development` and add the narrow skills that match the page controls.
+Default for a new page: first verify the approved product design, state matrix, Ant Design v6 theme/visual-standard high-fidelity HTML prototype, schema v2 semantic mapping/browser/accessibility evidence, and user confirmation; then use the implementation lockfile to map into YSS UI + Ant Design Vue 4.x, start with `yss-page-module-development`, and add the narrow skills that match the page controls.
 
 中文说明：新建页面默认从页面模块技能开始，只有遇到具体组件、Hook、API、Formily 细节时再加载专项技能。
 

package/template/.trae/skills/yss-router/references/router-contract.yaml

@@ -68,7 +68,7 @@ slice_contract_required:
   root: [schema_version, contract_id, contract_version, slice_id, status, lifecycle_refs, readiness, common, frontend, backend, contract, cross_repo, work_units]
   lifecycle_refs: [spec, ticket, requirement_freeze, low_fidelity_review, prototype_review, high_fidelity_html, prototype_verification, antd_cli_evidence, browser_verification_evidence, prototype_confirmation, openapi_freeze_or_no_impact, architecture_review, data_architecture, tactical_design, engineering_baseline, build_architecture_checklist, implementation_repository, frontend_repository, backend_repository, maven_wrapper]
   readiness: [blockers, stale_inputs, not_applicable]
-  common: [impacted_areas, implementation_path_policy, project_roots, required_skills, optional_skills, unavailable_skills, allowed_write_paths, forbidden_patterns, expected_evidence_files, verification_commands, human_review_points, full_reroute_triggers]
+  common: [impacted_areas, implementation_path_policy, project_roots, required_skills, optional_skills, unavailable_skills, allowed_write_paths, forbidden_patterns, expected_evidence_files, verification_commands, human_review_points, full_reroute_triggers, quality_baseline_ref, context_plan, doubt_driven_review]
   frontend: [status, required_skills, approved_prototype_ref, state_matrix_ref, allowed_write_paths, component_test_seams, e2e_paths]
   backend: [status, affected_layers, component_impacts, required_skills, application_boundary, transaction_boundary, persistence_strategy, allowed_write_paths, forbidden_patterns, expected_evidence_files, seam_deferred, verification_commands, tactical_ddd]
   contract: [api_impact, freeze_ref, no_api_impact_ref, generated_clients, contract_tests, regeneration_commands]
@@ -100,7 +100,12 @@ work_unit_required: [id, behavior, primary_skill, supporting_skills, tdd_mode, a
 work_unit_nonempty_arrays: [allowed_write_paths, expected_evidence, verification_commands]
 slice_contract_nonempty: [contract_id, contract_version, slice_id, status]
 slice_contract_array_fields:
-  common: [impacted_areas, implementation_path_policy, project_roots, required_skills, allowed_write_paths, forbidden_patterns, expected_evidence_files, verification_commands, full_reroute_triggers]
+  common: [impacted_areas, implementation_path_policy, project_roots, required_skills, allowed_write_paths, forbidden_patterns, expected_evidence_files, verification_commands, full_reroute_triggers, quality_baseline_ref, context_plan, doubt_driven_review]
+
+context_plan:
+  required: [required_context_refs, on_demand_context_refs, context_stop_rule, missing_context_action]
+  context_stop_rule: minimal-sufficient-evidence
+  missing_context_action: [blocked, reroute]
 
 scaffold_contract_schema:
   schema_version: 1
@@ -241,6 +246,7 @@ full_reroute_triggers:
   - test-seam-changed
   - verification-command-changed
   - delivery-order-changed
+  - doubt-review-triggered
 
 reroute_destinations:
   scaffold-baseline-drift: stage7-scaffold-revalidation
@@ -258,9 +264,30 @@ reroute_destinations:
   test-seam-changed: spec-ticket-test-seam-review
   verification-command-changed: stage7-contract-recompile
   delivery-order-changed: cross-repo-release-review
+  doubt-review-triggered: high-risk-decision-review
+
+doubt_driven_review:
+  applies_when:
+    - api-schema-impact
+    - database-schema-impact
+    - cross-repo-contract
+    - release-or-rollback
+    - authentication-authorization-tenant-or-sensitive-data-behavior
+    - lifecycle-or-generation-semantics
+  required: [claim, counterclaim, evidence_refs, residual_risks, reviewer_ref]
+  status_values: [not-applicable, required, completed, blocked]
+  blocking_when: [missing-counterclaim, insufficient-evidence, unresolved-residual-risk]
+  evidence_owner: decision-or-review-record
+  no_new_lifecycle_stage: true
+
+quality_baseline:
+  source: lifecycle_refs.engineering_baseline
+  required_for: [project-instance]
+  reused_by: [slice-contract, yss-skill-execution-result, code-review, release]
+  redefinition: forbidden
 
 execution_result_allowed_statuses: [implemented, seam-deferred, drift, violation, not-applicable]
-execution_blockers: [path-outside-contract, missing-evidence, verification-not-executed, verification-command-mismatch, seam-deferred-without-owner, constraint-failed, unapproved-deviation, drift, violation, new-impacts]
+execution_blockers: [path-outside-contract, missing-evidence, verification-not-executed, verification-command-mismatch, seam-deferred-without-owner, constraint-failed, doubt-review-missing, unapproved-deviation, drift, violation, new-impacts]
 
 contract_versioning:
   full_reroute_current_status: stale

package/template/.trae/skills/yss-router/references/slice-implementation-contract.md

@@ -54,6 +54,20 @@ slice_contract:
     verification_commands: []
     human_review_points: []
     full_reroute_triggers: []
+    quality_baseline_ref:
+    context_plan:
+      required_context_refs: []
+      on_demand_context_refs: []
+      context_stop_rule: minimal-sufficient-evidence
+      missing_context_action: blocked # or reroute
+    doubt_driven_review:
+      status: not-applicable # or required / completed / blocked
+      trigger_impacts: []
+      claim:
+      counterclaim:
+      evidence_refs: []
+      residual_risks: []
+      reviewer_ref:
   frontend:
     status: not-applicable
     required_skills: []

package/template/.trae/skills/yss-router/references/yss-skill-execution-result.md

@@ -13,6 +13,8 @@ execution_result:
     contract_ref:
     contract_id:
     contract_version:
+    quality_baseline_ref:
+    context_plan_ref:
   changed_files:
     - path:
       contract_area: common | frontend | backend | contract | cross_repo
@@ -28,6 +30,9 @@ execution_result:
     - constraint:
       status: passed | failed | not-applicable
       evidence_ref:
+  doubt_driven_review:
+    status: not-applicable | completed | blocked
+    record_ref:
   seam_deferred:
     - risk:
       owner:

package/template/.trae/skills/yss-ui/references/antdv-compatibility.md

@@ -32,7 +32,7 @@ pnpm why vue @yss-ui/components @yss-ui/hooks ant-design-vue vxe-table
 
 ## Ant Design v6 边界
 
-Ant Design v6 可以作为产品原型的视觉和 token 语义参考；Vue 生产实现使用 Ant Design Vue 4.x。禁止复制 React hooks、JSX、组件 props、theme algorithm API 或事件模型到 Vue 代码。
+Ant Design v6 是产品原型默认的主题样式、视觉和 token 语义标准；Vue 生产实现使用 Ant Design Vue 4.x。版本号不同本身不是冲突。生产映射必须消费原型证据中的 `visual_semantic_mapping`，并用实现仓 lockfile/类型验证 YSS 或 AntDV 目标；禁止复制 React hooks、JSX、组件 props、theme algorithm API 或事件模型到 Vue 代码。
 
 ## 兼容性证据
 

package/template/AGENTS.md

@@ -24,6 +24,7 @@
 | 技能清单、来源、版本、哈希和投影目标      | `skills-lock.json`                          |
 | 技能分层、别名、默认可发现性和运行时入口 | `docs/agents/yss-skill-registry.yaml`（当前 `status: active`；Router / 生命周期必须消费） |
 | 数字人角色、阶段协作组、运行时绑定与生命周期会签 | `docs/agents/digital-human-roles.yaml`；`docs/agents/digital-human-roles.md` 为操作说明 |
+| 视觉令牌与组件视觉变体规范 | 根目录 `DESIGN.md`；`docs/design/design.md` 为中文治理与生命周期适配，`docs/design/tokens/*` 为派生快照 |
 
 README、用户指南、根目录 `CLAUDE.md` 和其他说明文档只引用或解释上述事实，不重复定义同一规则。`CLAUDE.md` 是 Claude Code 入口指针，不是第二套 Agent 规则。
 
@@ -39,7 +40,7 @@ README、用户指南、根目录 `CLAUDE.md` 和其他说明文档只引用或
 
 按“影响面 → 单一事实来源 → 投影 / 派生资产 → 分级证据”维护。强度分级、最低证据和 checkpoint 合同见 `docs/process/harness-process-tailoring.md`。
 
-- 创建、修改或退役 skill 时使用 `maintaining-skills`，并先按 `docs/process/harness-process-tailoring.md` 判定 L1 / L2 / L3；只有 L3 必须保留完整基线失败、压力场景、修订后验证和正式独立审查证据。
+- 创建、修改或退役 skill 时使用 `maintaining-skills`，并先按 `docs/process/harness-process-tailoring.md` 判定 L1 / L2 / L3；L3 日常记录维护者自检与 fresh verification，正式发布前执行完整模板门禁。
 - `.agents/skills` 是跨 Agent 共享技能的权威内容；`.claude/skills`、`.codex/skills`、`.cursor/skills`、`.hermes/skills`、`.pi/skills`、`.qoder/skills`、`.trae/skills` 中的共享技能是生成投影，禁止分别手工修改。Cursor 的契约运行时入口是 `.cursor/skills`；不得把 canonical `.agents/skills` 与某个平台投影当作同权双入口。
 - 模板维护默认以 `scripts/verify-template-fast` 完成 `implementation-ready`；显式晋级审查时用 `scripts/verify-template-candidate`，首次冻结前和最终发布前仍必须执行完整 `scripts/verify-template`。后者是不可裁剪的模板发布阻断门禁。模板与外部 `create-yss-spec` 的跨仓库契约未完成集成验证时，不得声称可发布。
 
@@ -54,7 +55,7 @@ README、用户指南、根目录 `CLAUDE.md` 和其他说明文档只引用或
 | 入口分诊 `stage.entry-triage` | `work-unit.entry-triage` | `yss-product-lifecycle` | 仓库身份、影响面、最近可信阶段；`gate.repository-identity-valid` |
 | Discovery `stage.discovery` | `work-unit.discovery-opportunity`、`work-unit.discovery-requirements`、`work-unit.domain-strategy-design`、`work-unit.stage-decision` | `yss-product-lifecycle`；按事实 / 领域影响使用 `competitive-intelligence`、`research`、`grilling`、`domain-modeling`、`yss-stage-decision` | Discovery、用户/MVP/非目标/成功标准、测试 seam；必要时 DDD 战略设计与阶段决策包；`gate.domain-strategy-approved`、`gate.stage-decision-package-approved` |
 | Spec / 功能架构 `stage.spec-architecture` | `work-unit.spec-synthesis` | `yss-product-lifecycle`；`to-spec` 仅为显式兼容入口 | Spec、产品总体设计、功能架构；必要时 Spec Delta；`gate.spec-baseline-approved` |
-| 产品设计 `stage.product-design` | `work-unit.prototype-design` | `yss-design-system` → `prototype-review` → `yss-prototype-stage` → `yss-antd-design` → Codex `product-design:index`；前端落地改用 `yss-ui` | 交互说明、低 / 高保真原型、状态矩阵；`gate.prototype-reviewed`、`gate.prototype-verified`、`gate.user-confirmation` |
+| 产品设计 `stage.product-design` | `work-unit.prototype-design` | `yss-prototype-stage` 为主合同，内部依次消费 `yss-design-system`、低保真、独立 `prototype-review`、`yss-antd-design` pre-build facts、Codex `product-design:index` focused workflow、post-build/浏览器/无障碍验证；前端落地改用 `yss-ui` | 交互说明、低 / 高保真原型、状态矩阵；`gate.prototype-reviewed`、`gate.prototype-verified`、`gate.user-confirmation` |
 | 系统 / 数据架构与工程契约 `stage.system-data-engineering` | `work-unit.technical-analysis` | `yss-router`；按影响使用 `yss-openapi-governance`、`yss-openapi-draft-review`、`codebase-design`、`implementation-repo-onboarding`、`yss-tactical-design` | OpenAPI Draft / Freeze、数据架构、工程基线、架构审查；无 API 影响记录；必要时 Tactical DDD Check；`gate.openapi-draft-reviewed`、`gate.design-reviewed`、`gate.openapi-frozen`、`gate.engineering-baseline-accepted`、`gate.architecture-reviewed` |
 | Ticket 正式化 `stage.ticket-formalization` | `work-unit.ticket-decomposition` | `yss-product-lifecycle` + `yss-router`；`to-tickets` 仅为显式兼容入口 | 功能父 Ticket、垂直切片、Slice Implementation Contract；切片初始 `ready-for-human`；`gate.slice-contract-approved`、`gate.slice-ready-for-agent` |
 | 垂直切片实现 `stage.vertical-slice-implementation` | `work-unit.slice-implementation` | `yss-router` + `tdd`；UI 影响追加 `yss-ui`、`yss-page-module-development` 及条件专项 skill；`implement` 仅为显式兼容入口 | 前后端代码、TDD、YSS Skill Execution Result；仅允许 `ready-for-agent` 且合同当前 |
@@ -96,7 +97,7 @@ README、用户指南、根目录 `CLAUDE.md` 和其他说明文档只引用或
 |---|---|
 | 技术事实、标准、第三方 API 或框架行为影响决策 | `research` 或等价的一手资料记录 |
 | 竞品、市场或用户口碑事实 | `competitive-intelligence` |
-| UI 设计、原型、组件或主题 | `yss-design-system` → `prototype-review` → `yss-prototype-stage`；原型事实用 `yss-antd-design`，Codex 再路由 `product-design:index`，其他 Agent 交付等价合同资产。前端代码落地改用 `yss-ui`，不要继续调用 `yss-antd-design` |
+| UI 设计、原型、组件或主题 | `yss-prototype-stage` 持有阶段合同：`yss-design-system` → 低保真 → 独立 `prototype-review` → `yss-antd-design` pre-build facts → Codex `product-design:index` focused workflow → post-build/浏览器/无障碍验证；其他 Agent 交付等价合同资产。前端代码落地改用 `yss-ui`，不要继续调用 `yss-antd-design` |
 | Bug、测试失败或性能回退 | `diagnosing-bugs` 建立可复现反馈，再用 `tdd` |
 | merge / rebase 冲突 | `resolving-merge-conflicts` |
 | 架构治理、难测模块或深模块设计 | `codebase-design`；`improve-codebase-architecture` 仅作为用户显式兼容入口 |
@@ -114,7 +115,7 @@ README、用户指南、根目录 `CLAUDE.md` 和其他说明文档只引用或
 
 ## 10. 独立审查、验证和追踪
 
-- 实现者不能承担命中的独立审查（含数字人）。模板维护按 L1 / L2 / L3 分别使用 self-check / 人工 checkpoint、聚焦独立审查、正式独立审查；模板发布、代码切片和高风险变更仍必须由其他 Agent 或独立审查者完成。产品切片与模板维护共用同一 finding 闭环：`violation` 由实现者在原合同路径修复后重新捕获并全轴复审；`drift` / `new_impacts` 使合同 `stale` 并回 Router。审查者不得写实现。命中后的 mandatory 不得豁免；未命中才 `not-applicable`。
+- 实现者不能承担命中的独立审查（含数字人）。模板维护的 L3 日常路径使用维护者自检；L2 仍按需使用聚焦独立审查，正式发布仍执行完整模板门禁。模板发布、代码切片和高风险变更仍必须满足各自独立审查要求。产品切片与模板维护共用同一 finding 闭环：`violation` 由实现者在原合同路径修复后重新捕获并全轴复审；`drift` / `new_impacts` 使合同 `stale` 并回 Router。审查者不得写实现。命中后的 mandatory 不得豁免；未命中才 `not-applicable`。
 - 任何“完成 / 可合并 / 可发布”结论必须基于 fresh verification，不接受“之前跑过”或实现者自述。
 - 会签门禁按 `docs/agents/digital-human-roles.yaml` 的 `gate_policy` 关闭，会签文件经 `scripts/verify-approval-record` 核验；`gate.release-ready`、对外商务承诺和运行时外部副作用仍须生物人。
 - 在会签暂停、handoff、进入实现、合并或发布边界集中同步范围、验证证据、风险、会签点、Ticket 状态和下一步；阻塞、责任人变化或资产单独批准时立即同步。

package/template/CONTEXT.md

@@ -23,8 +23,8 @@
 | Ticket 状态 | Tracker 五态：`needs-triage`、`needs-info`、`ready-for-agent`、`ready-for-human`、`wontfix`。 | — | 不要称为数字人角色或「标准角色」。 |
 | 阶段协作组 | 某阶段需要共同可见会签的逻辑成员集合。 | — | 不是某个产品的群聊；平台人数上限只写在对应 `runtimes`。 |
 | 需求经理 | 主责 Discovery 语言、用户/MVP/非目标、Spec 正文与测试 seam 的数字人角色。 | — | 不拥有原型视觉定稿，不 Freeze API，不写实现。 |
-| 产品经理 | 主责优先级、产品设计影响、原型确认建议和范围裁剪的数字人角色。 | — | 不写生产代码，不单独 Freeze API。 |
-| 商务 | 主责机会调研商业约束、交付承诺和发布窗口商务非目标的数字人角色。 | — | 不参与 Spec 定稿、契约、代码或 Ticket 状态推进。 |
+| 产品经理 | 主责优先级、产品设计影响、原型确认建议、范围裁剪以及商业约束、交付承诺、发布窗口和商业非目标的数字人角色。 | — | 不写生产代码，不单独 Freeze API；对外商务合同和正式承诺须由生物人批准。 |
+| 商业约束 | Discovery 与发布阶段需要确认的商业边界、交付承诺、发布窗口和商业非目标。 | — | 由产品经理负责数字人侧的整理与协调；不等同于独立的“商务”数字人角色。 |
 | Agent 入口规则 | Agent 启动任务时必须先遵守的全局路由、硬门禁和禁止事项。 | — | 不作为 YSS 后端、前端或其他专项编码规范的完整手册。 |
 | 标准文档语言 | 面向业务、产品、架构、实施、审查、发布和复盘的持久化文档所使用的默认语言。 | — | 统一使用简体中文；英文专有名词、代码标识、API 路径、schema、文件名和协议 metadata 保持原样。 |
 | Matt Engineering Skills | 来自 `mattpocock/skills` 的轻量工程流程技能集合。 | — | 用于澄清、Spec、Ticket、实现、TDD、诊断、审查和架构治理，不替代 YSS 专项规范。 |