create-yss-spec 2.2.7 → 2.2.9

package/template/.codex/skills/yss-product-lifecycle/references/orchestration-contract.yaml

@@ -241,6 +241,10 @@ work_unit_routes:
     primary_skill: yss-prototype-stage
     supporting_skills: [prototype-review, yss-design-system, yss-antd-design, product-design:index]
     skills: [prototype-review, yss-design-system, yss-prototype-stage, yss-antd-design, product-design:index]
+    execution_order: [yss-design-system, low-fidelity-assets, prototype-review, yss-antd-design-pre-build, product-design-focused-workflow, yss-antd-design-post-build, browser-design-qa-accessibility, user-confirmation]
+    prototype_adapter_ref: .agents/skills/yss-prototype-stage/references/product-design-adapter.md
+    evidence_schema_version: 2
+    version_boundary: {design_standard: ant-design-v6, prototype_components: react-antd-6.x, production_components: yss-ui-ant-design-vue-4.x, production_version_source: implementation-lockfile}
     human_gate: prototype-confirmation
     applies_when: product_design_impact
     not_applicable_reason: no_ui_or_product_design_impact
@@ -644,8 +648,49 @@ release_readiness:
 wayfinder_completion:
   required: [no_open_children, no_open_blocked_or_claimed_children, no_fog, destination_clear]
 
+wayfinder_mode:
+  optional: true
+  enable_when:
+    - multi-session-or-multi-agent-work
+    - unclear-decision-frontier
+    - cross-domain-dependency-map-needed
+  lifecycle_position: discovery-to-spec-planning
+  completion_route: wayfinder -> handoff -> to-spec
+  does_not_replace: [lifecycle-gates, spec-baseline, ticket-formalization]
+  forbidden_state_mutations: [ready-for-agent, gate-approval, ticket-role]
+  template_source_use: only-when-template-evolution-is-long-running
+
+context_engineering:
+  contract_field: slice_contract.common.context_plan
+  required_context: [CONTEXT.md, approved-spec, current-slice-contract, applicable-adr-or-baseline]
+  on_demand_context: [specialist-references, implementation-repository-files, historical-evidence]
+  stop_rule: minimal-sufficient-evidence
+  missing_context_action: [blocked, reroute]
+  numeric_token_budget: not-required
+
+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]
+  record_in: [decision-record, architecture-review, contract-review, release-review]
+  blocking_when: [missing-counterclaim, insufficient-evidence, unresolved-residual-risk]
+  ordinary-low-risk_changes: not-required
+  no_new_lifecycle_stage: true
+
+quality_baseline_reuse:
+  source: artifact.engineering-baseline
+  applies_to: project-instance
+  consumers: [slice-implementation-contract, yss-skill-execution-result, code-review, release]
+  constraint_results_field: required
+  redefinition: forbidden
+
 ready_for_agent:
-  required: [gates_satisfied, no_stale_artifacts, blockers_closed, implementation_context_ready, implementation_repo, implementation_branch, ci, verification_commands, rollback_point, predecessor_work_unit, ticket_decomposition_result_ref, ticket_decomposition_result_status, vertical_slice_ticket_ref, vertical_slice_ticket_role, vertical_slice_ticket_kind, slice_contract_approved, slice_contract_persisted, slice_contract_current_version, build_architecture_checklist, backend_slice_contract_if_applicable, backend_scaffold_policy_satisfied, frontend_implementation_plan_if_ui_impact]
+  required: [gates_satisfied, no_stale_artifacts, blockers_closed, implementation_context_ready, context_plan, quality_baseline_ref, implementation_repo, implementation_branch, ci, verification_commands, rollback_point, predecessor_work_unit, ticket_decomposition_result_ref, ticket_decomposition_result_status, vertical_slice_ticket_ref, vertical_slice_ticket_role, vertical_slice_ticket_kind, slice_contract_approved, slice_contract_persisted, slice_contract_current_version, build_architecture_checklist, backend_slice_contract_if_applicable, backend_scaffold_policy_satisfied, frontend_implementation_plan_if_ui_impact]
   ticket_formalization_validator: scripts/lib/lifecycle-transition.mjs
   requires_vertical_slice_ticket: true
   parent_ticket_as_implementation_ref: forbidden

package/template/.codex/skills/yss-product-lifecycle/references/orchestration.md

@@ -86,6 +86,12 @@ tracker 选择和冲突按 `docs/agents/issue-tracker.md` 裁决：已持久化
 
 暂停输出：门禁、指定会签 `role_id`、`runtime_id`、会签文件路径、证据、推荐答案、一个问题、恢复动作。
 
+## Context Plan 与质量基线
+
+实现合同先消费 `common.context_plan`：必需上下文只包含 `CONTEXT.md`、已批准 Spec、当前合同和适用 ADR / 工程基线；专项 references、实现仓库文件和历史证据按影响面按需加载。达到最小充分证据后停止扩展，缺失权威上下文只能 `blocked` 或 `reroute`。
+
+质量标准由 `engineering-baseline` 以 `baseline_id` / `baseline_version` 定义一次，Slice Contract、YSS Skill Execution Result、`code-review` 和发布检查只引用它，并将约束结果写入 `constraint_results`。命中 API / 数据迁移、跨仓契约、发布回滚、实际安全行为或生命周期 / 生成语义时，必须在现有决策或审查记录中完成 Doubt-Driven 主张、反证、证据、残余风险和 Reviewer 引用；普通低风险变更不触发该流程。
+
 ## Wayfinder 完成判定
 
 “无 frontier”不等于完成。只有以下条件同时成立，才能 `wayfinder → handoff → to-spec`：

package/template/.codex/skills/yss-prototype-stage/SKILL.md

@@ -15,11 +15,12 @@ description: Use when a YSS feature has product-design impact on a primary flow,
 
 ## 资产与门禁顺序
 
-1. 以 Spec、产品总体设计和 `docs/design/design.md` 形成交互说明、低保真页面/流程与状态矩阵。
+1. 以 Spec、产品总体设计、`yss-design-system` 和 `docs/design/design.md` 形成交互说明、低保真页面/流程与状态矩阵。
 2. 用 `prototype-review` 形成独立评审结论；未通过不得生成高保真或进入需求冻结。
-3. 通过 `product-design:index` 产出 `docs/.scratch/<feature>/design/prototypes/index.html`。
-4. 写入 `docs/.scratch/<feature>/verification/prototype-evidence.yaml`，完成 AntD CLI 与浏览器验证。
-5. 用户确认后，才可校准 Spec、分析 API 影响或进入 Router readiness。
+3. 用 `yss-antd-design` 固定目标 React `antd@6.x`，先查询 `design.md` 与本功能组件事实。
+4. 通过 `product-design:index` 的 `get-context → ideate → 用户选择 → image-to-code → design-qa` 产出 feature 级 React/Vite 原型；必须套用 `references/product-design-adapter.md`，不能把通用 starter 视为已符合 YSS。
+5. 完成 AntD post-build manifest/lint（按产物类型）、同视口 Design QA、浏览器与无障碍验证，写入 schema v2 `docs/.scratch/<feature>/verification/prototype-evidence.yaml`。
+6. 用户确认后，才可校准 Spec、分析 API 影响或进入 Router readiness。
 
 ## 设计与 AntD 依据
 
@@ -27,11 +28,13 @@ description: Use when a YSS feature has product-design impact on a primary flow,
 
 Codex `$design-qa` 仍走官方对比流程；Colors/tokens 与 Fonts/typography 必须以项目覆盖为 source visual truth。对照清单见 `yss-design-system/references/design-qa-theme.md`。仍用官方 `#1677ff`、强制 `Inter` 或历史 8px 品牌圆角当默认主题，视为项目覆盖漂移。
 
-Ant Design v6 事实由 `yss-antd-design` 查询并回写证据，不要并列调用官方 `antd` skill，也不要在前端代码落地时继续使用它。进入实现后改走 `yss-ui`。
+主题与视觉标准固定为 `ant-design-v6`；生产运行时固定为 Vue 3 + YSS UI + `ant-design-vue-4.x`，精确生产版本来自实现仓 lockfile。版本号不同本身不是冲突。Ant Design v6 事实由 `yss-antd-design` 查询并回写证据，不要并列调用官方 `antd` skill，也不要在前端代码落地时继续使用它。进入实现后改走 `yss-ui`。
+
+标准原型组件存在 Ant Design 实现时必须精确锁定与 CLI 目标一致的 `antd@6.x`，并通过 `ConfigProvider` 消费项目主题 adapter。执行与验证命令见 `references/product-design-adapter.md` 和 `scripts/prototype-contract.mjs`。
 
 ## 验证与回流
 
-`browser_verification` 至少覆盖非空渲染、主流程、一个失败/权限/冲突状态、桌面与窄屏视口和控制台错误；优先使用 Browser 或可执行浏览器自动化，Computer Use 只作人工交互补充。把路径、命令、版本、视口、结果和阻塞项写入证据清单。
+`browser_verification` 至少覆盖非空渲染、主流程、一个失败/权限/冲突状态、桌面与窄屏视口和控制台错误；`accessibility_verification` 至少覆盖对比度、键盘/焦点、语义标签与 Dialog、200% zoom、reduced motion、目标尺寸和自动化扫描。优先使用 Browser 或可执行浏览器自动化，Computer Use 只作人工交互补充。把路径、命令、版本、视口、结果和阻塞项写入证据清单。
 
 `gate.prototype-reviewed` 的证据是评审记录；`gate.prototype-verified` 的证据是 AntD CLI 与浏览器验证；`gate.user-confirmation` 的证据是确认记录。三者均不是实现授权。
 
@@ -40,3 +43,5 @@ Ant Design v6 事实由 `yss-antd-design` 查询并回写证据，不要并列
 - 仅有截图或 HTML，却没有可复现的 CLI、浏览器和确认记录。
 - 把 `product-design:index` 或某个旧技能当作生命周期批准者。
 - 直接复制官方默认颜色、圆角或间距，忽略项目覆盖。
+- 只证明查询过 AntD v6，却没有 v6 semantic role → 项目 Token → YSS/AntDV4 的映射证据。
+- 沿用 Product Design starter 的 npm、根目录 `design-qa.md` 或未安装 `antd` 的通用配置。

package/template/.codex/skills/yss-prototype-stage/references/product-design-adapter.md

@@ -0,0 +1,54 @@
+# YSS Product Design Adapter
+
+本合同把 Codex Product Design 的通用 React/Vite 产出接入 YSS 原型阶段。它不修改上游 Product Design skill，也不把 React API 带入 Vue 生产实现。
+
+## 双轨版本
+
+- `design_standard: ant-design-v6`：高保真原型的主题、视觉语义、标准组件和 CLI 事实。
+- `runtime_component_library: ant-design-vue-4.x`：生产 Vue/YSS 组件 API；精确版本只从实现仓 lockfile 读取。
+- 标准原型组件存在 Ant Design 实现时，React 原型必须精确锁定与 CLI 查询一致的 `antd@6.x`。YSS 专有布局可用适配 CSS，但仍消费项目 Token。
+- 禁止把 React hook、props、JSX、静态 API 或事件模型作为 Vue/YSS 实现合同。
+
+## 产出前适配
+
+1. 目标目录固定为 `docs/.scratch/<feature>/design/prototypes/`。
+2. Product Design 完成 `get-context`、三方案 `ideate` 和用户视觉选择后，进入 `image-to-code` 的 local preflight，只执行官方 bootstrap 创建空 starter；在安装依赖或编写 UI 前立即运行 adapter：
+
+   ```bash
+   node .agents/skills/yss-prototype-stage/scripts/prototype-contract.mjs prepare \
+     --project-root <project-root> \
+     --root <project-root>/docs/.scratch/<feature>/design/prototypes \
+     --feature <feature> \
+     --target-antd-version <exact-6.x-version> \
+     --pnpm-version <actual-pnpm-version>
+   ```
+
+3. adapter 只做机械动作：精确写入 `antd` 版本、登记 pnpm、生成 `src/yss-theme.js` 和 `yss-prototype-adapter.json`。随后由 Product Design 将入口包在 `ConfigProvider theme={yssTheme}` 中，并优先使用标准 `antd` 组件。
+4. 执行 `pnpm install`、`pnpm build`，保留 `pnpm-lock.yaml`、源码入口、构建入口、实际命令与退出码。禁止用 npm lockfile 代替受控例外记录。
+5. 校验项目：
+
+   ```bash
+   node .agents/skills/yss-prototype-stage/scripts/prototype-contract.mjs validate-project \
+     --root <project-root>/docs/.scratch/<feature>/design/prototypes \
+     --target-antd-version <exact-6.x-version>
+   ```
+
+## 视觉与实现映射
+
+每个关键组件在 `visual_semantic_mapping` 中记录四层映射：Ant Design v6 semantic role、项目 Token、React 原型组件、生产 YSS/Ant Design Vue 目标。映射的是视觉角色、状态和验收行为，不是 React API 表面形状。
+
+至少覆盖主操作、表单输入、表格/列表、反馈、弹层和导航中本功能实际出现的类型。每项记录 `default/hover/active/disabled/loading/error` 等适用状态，并把 `react_only_api_not_copied` 设为 `true` 后才能通过。
+
+## 视口、QA 与无障碍
+
+- 默认视觉目标和同状态 QA 使用 desktop `1440x900`、mobile `390x844`；按影响追加 tablet/laptop/wide，不机械要求九个视口。
+- Design QA 报告固定到 `docs/.scratch/<feature>/verification/design-qa.md`，不得写仓库根共享文件。
+- 项目品牌 Seed `#3371ff` 保持不变；普通文本、按钮及状态组合不满足 WCAG 2.2 AA 时，通过组件 Token 调整实际填充或文字色，并保存对比度证据。
+- 验证至少包含键盘、焦点、语义标签/Dialog、200% zoom、reduced motion、目标尺寸和自动化扫描；工具不可用时记录人工替代与未覆盖缺口，不得空填 passed。
+
+## 交互档位
+
+- `reviewable-flow`（默认）：合同内主路径和关键状态可操作；非范围控件禁用或明确标注，不伪装完整功能。
+- `full-prototype`：brief 明确要求的全部可见范围控件可操作。
+
+不得使用含义冲突的 `static` / `mostly-static` 作为 YSS 交付状态。

package/template/.codex/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/.codex/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/.codex/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/.codex/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/.codex/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: []