create-yss-spec 2.2.7 → 2.2.9

package/template/.agents/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/.agents/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/.agents/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/.agents/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/.agents/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/.agents/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/.claude/skills/maintaining-skills/SKILL.md

@@ -17,7 +17,7 @@ Create skills that add useful, non-obvious guidance without constraining unrelat
 6. Follow the repository's declared maintenance and review policy. If none exists, run structural validation plus focused checks of the behavior or invariant changed. Use independent forward testing only when complexity or risk makes it meaningful; do not require a failing baseline for every ordinary edit.
 7. After changes, validate frontmatter, naming, references, scripts, projections, locks, and affected callers. Retire obsolete names and resources unless the repository explicitly requires compatibility.
 8. When a repository declares staged template verification, default the implementation loop to its fast impact profile and stop at `implementation-ready`. Promote explicitly to `review-ready`; do not create frozen candidates, review packages, or release evidence during ordinary iteration. Unknown paths and changes to the verification framework itself must fail safe to the full profile.
-9. For a formal L3 review, run the repository's full gate before the first frozen candidate and again before release. Between them, use focused/candidate checks. Do not weaken required evidence or independent review to gain speed.
+9. For L3 template maintenance, record maintainer self-check plus fresh verification and do not create a frozen candidate or formal independent review during ordinary iteration. Before release, run the repository's full `scripts/verify-template` gate once; historical formal-review records remain read-only compatible.
 
 ## Boundaries
 

package/template/.claude/skills/yss-antd-design/references/evidence.md

@@ -11,6 +11,8 @@
 - `antd.queries.components[]`：每个选用组件的 `info_ref` / `demo_ref` / `token_ref` / `semantic_ref`。
 - `design_baseline.project_design_ref`：`docs/design/design.md`。
 - `design_baseline.project_override_reviewed`：上游默认与项目 token 已对照。
+- `prototype_stack.actual_antd_version`：原型 lockfile 中的实际 React `antd@6.x`，必须与 `antd.target_antd_version` 一致。
+- `visual_semantic_mapping.components[]`：记录 v6 semantic role、项目 Token、React 原型组件、生产 YSS/Ant Design Vue 4.x 目标与 React-only API 隔离结论。
 
 JSON 输出存为相邻文件，证据清单只引用路径。不要把整份 `llms-full.txt` 或 MCP 对话贴进清单。
 
@@ -18,6 +20,8 @@ JSON 输出存为相邻文件，证据清单只引用路径。不要把整份 `l
 
 `antd lint` 只对可解析的 React/TSX 源码有规则命中。HTML 原型会出现空 issues（假绿）或 `skippedFiles` / `parse-error` / `partial: true`。
 
+CLI JSON 只能证明查询事实，不能单独证明原型消费了目标版本或完成了 Vue/YSS 映射。`gate.prototype-verified` 还必须通过 `yss-prototype-stage/scripts/prototype-contract.mjs` 的项目与 schema v2 证据校验、Design QA、浏览器和无障碍验证。
+
 | 产物 | `lint_applicable` | 做法 |
 |---|---|---|
 | `docs/.scratch/<feature>/design/prototypes/index.html` | `not-applicable` | 写 `lint_reason: html-prototype`；`lint_ref` 可空；`lint_passed` 保持 `false`，不得改成 `true` |

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

@@ -40,6 +40,7 @@ description: Use when YSS 产品设计系统与 Ant Design 企业级 UI 风格
 - 组件语言：优先 Ant Design / YSS UI 语义，不自造同类控件。
 - 状态完整性：loading、empty、error、readonly、disabled、no-permission、conflict、success 必须在设计或实现中可解释。
 - Ant Design v6 原型基线：先用语义 token 定义角色，再用组件 token 或 CSS variables 落地；不以局部硬编码替代主题层。
+- 双轨版本：主题/视觉标准为 React Ant Design v6；生产 API 为 Vue 3 + YSS UI + 实现仓 lockfile 的 Ant Design Vue 4.x。只迁移语义、Token、状态与验收行为。
 
 ## 强制规则
 
@@ -49,7 +50,7 @@ description: Use when YSS 产品设计系统与 Ant Design 企业级 UI 风格
 - 每个页面或决策区域只保留一个 single primary action；其余动作降级为默认、链接或危险操作。
 - 不硬编码表面色、边框色、状态色；优先使用 token 或主题变量。
 - 交互原型中的每个可点击主动作都必须给出 interaction feedback：状态变化、禁用原因、成功或失败反馈至少覆盖其一。
-- accessibility contrast：默认 token 不能满足目标文本对比度时，优先通过 `ConfigProvider` seed / component token 调整，不新增页面级特例色。
+- accessibility：品牌 Seed `#3371ff` 保持不变；实际文字/背景组合不满足 WCAG 2.2 AA 时，优先通过 `ConfigProvider` component token 调整，并验证 default/hover/active/disabled/focus、键盘焦点、200% zoom、reduced motion 与目标尺寸，不新增页面级特例色。
 - React + Ant Design 的暗色或紧凑密度必须使用 theme algorithm，不手工反转颜色或逐控件压缩尺寸。
 - 不用 Tag 表达关键错误、阻断或审批状态；关键状态必须有可读文本和语义反馈。
 - 不让按钮、标签、表头、弹窗、卡片中的文字溢出或遮挡。
@@ -89,6 +90,7 @@ description: Use when YSS 产品设计系统与 Ant Design 企业级 UI 风格
 | YTable / YTree / 高度自适应 | `yss-components` / `yss-use-table-height` / `yss-use-tree-height` |
 | 原型阶段的 Ant Design v6 组件 / token / demo 查询 | `yss-antd-design`（只用于原型设计构建；前端落地改用 `yss-ui`） |
 | Codex 原型交接前的视觉 QA | `design-qa`；token / 字体对照读 `references/design-qa-theme.md`，以项目覆盖为准 |
+| Product Design 通用 starter 接入 YSS | `yss-prototype-stage/references/product-design-adapter.md`；锁定 antd@6、pnpm、主题 adapter、feature 级 QA 与证据 |
 | API 契约 / 接入 | `yss-openapi-governance` / `yss-api-integration` |
 
 ## 更新设计系统

package/template/.claude/skills/yss-page-module-development/SKILL.md

@@ -157,7 +157,7 @@ When implementing a page module, the result should usually include:
 
 ## Stage 7 Contract
 
-- Require an approved `Slice Implementation Contract`, requirement freeze, low-fidelity review, Ant Design v6 high-fidelity HTML prototype, AntD CLI evidence, user confirmation, and state matrix for UI-impact work.
+- Require an approved `Slice Implementation Contract`, requirement freeze, low-fidelity review, Ant Design v6 theme/visual-standard high-fidelity HTML prototype, schema v2 semantic mapping/browser/accessibility evidence, user confirmation, and state matrix for UI-impact work; production APIs still come from YSS UI + the actual Ant Design Vue 4.x lockfile.
 - Bind page, hooks, schema, blocks, generated API client, component tests, and E2E paths to contract fields and `allowed_write_paths`.
 - User-visible loading, empty, error, permission, selection, pagination, and action behavior use `behavior-tdd`; purely mechanical page scaffolding may use documented `controlled-generation`.
 - Return the shared `YSS Skill Execution Result`. A prototype mismatch, new API, new permission state, path overrun, or missing evidence must produce `drift`, `violation`, or `new_impacts`, not `implemented`.

package/template/.claude/skills/yss-product-lifecycle/SKILL.md

@@ -16,6 +16,8 @@ description: 编排 YSS 产品或模块从机会调研到 Spec、原型、技术
 
 Matt 的 `grill-with-docs`、`to-spec`、`to-tickets`、`implement` 等保留为显式兼容入口；默认路径是本 skill 持有的原生工作单元，由本编排器创建正式资产、维护状态并在会签门禁暂停（级别见数字人角色注册表）。兼容入口不得自动调用它们或代替其创建正式资产；Matt 只导航，不得写生命周期资产或改变门禁/Ticket 状态；任何写入前回交本编排器。
 
+技能调用先消费 `docs/agents/yss-skill-registry.yaml` 的 `invocation_contract`：它只约束调用模式、触发/排除条件、主要输出和依赖，不替代生命周期证据或门禁。进入实现后，Slice Contract 的 `common.context_plan` 只加载当前切片的最小充分上下文；缺失权威上下文必须 `blocked` 或回 Router，不得猜测补齐。质量标准由 `engineering-baseline` 一次定义并由切片、Execution Result、审查和发布复用；命中高风险影响时在途记录 Doubt-Driven 主张、反证、证据和残余风险。Wayfinder 仅作为超长或决策前沿不清晰工作的可选 Discovery → Spec 规划模式，完成后回到 `handoff → to-spec`，不改变生命周期状态。
+
 ## 不可裁剪的主链
 
 入口分诊 → Discovery → Spec / 功能架构 → 产品设计 → 系统 / 数据架构与工程契约 → Ticket 正式化 → 垂直切片实现（前后端 TDD）→ 验证 / 发布 / 复盘。
@@ -31,7 +33,7 @@ Matt 的 `grill-with-docs`、`to-spec`、`to-tickets`、`implement` 等保留为
 | 入口分诊 `stage.entry-triage` | 身份、影响面、最近可信阶段 | `work-unit.entry-triage`；`yss-product-lifecycle` | `yss-project.yaml` 合法且影响面可解释 |
 | Discovery `stage.discovery` | Discovery、用户/MVP/非目标/成功标准、测试 seam；命中 DDD 影响时补充领域战略设计与阶段决策包 | `work-unit.discovery-opportunity` + `work-unit.discovery-requirements` + `work-unit.domain-strategy-design` + `work-unit.stage-decision`；市场/竞品事实用 `competitive-intelligence`，技术/标准事实用 `research`；需求澄清用 `grilling`，领域建模用 `domain-modeling` / `yss-stage-decision`；`grill-with-docs` 为兼容入口 | 未决事实已 research 或 handoff，领域边界和统一语言可审查，阶段决策包完成必要批准；`gate.domain-strategy-approved`、`gate.stage-decision-package-approved` |
 | Spec / 功能架构 `stage.spec-architecture` | Spec、产品总体设计、功能架构；必要时 Spec Delta | 原生 `work-unit.spec-synthesis`；`to-spec` 为兼容入口 | 初稿先为 `ready-for-human`；只有 Spec baseline 会签批准后资产才为 `approved` 并进入下游 |
-| 产品设计 `stage.product-design` | 交互说明、低保真、状态矩阵、高保真 HTML、评审记录 | `work-unit.prototype-design`；`yss-design-system` → `prototype-review` → `yss-prototype-stage` → `yss-antd-design`（仅原型事实）→ Codex `product-design:index`（非 Codex 交付等价合同）。前端落地改用 `yss-ui` | `gate.prototype-reviewed`、`gate.prototype-verified`、`gate.user-confirmation` 均有证据 |
+| 产品设计 `stage.product-design` | 交互说明、低保真、状态矩阵、高保真 HTML、评审记录 | `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/浏览器/无障碍验证（非 Codex 交付等价合同）。前端落地改用 `yss-ui` | `gate.prototype-reviewed`、`gate.prototype-verified`、`gate.user-confirmation` 均有 schema v2 证据 |
 | 系统 / 数据架构与工程契约 `stage.system-data-engineering` | OpenAPI Draft/Freeze、数据架构、工程基线、架构审查；按领域影响执行 Tactical DDD Check | `work-unit.technical-analysis`；`yss-router` + `yss-openapi-governance` / `yss-openapi-draft-review`、`codebase-design`、`implementation-repo-onboarding`、`yss-tactical-design`；用户或合同明确要求架构可视化时条件追加 `archify` | API/架构契约冻结；无 API 影响有明确记录；战术模型无未解释冲突；脚手架策略满足；Archify 图只作派生审查证据；`gate.openapi-draft-reviewed`、`gate.design-reviewed`、`gate.openapi-frozen`、`gate.engineering-baseline-accepted`、`gate.architecture-reviewed` |
 | Ticket 正式化 `stage.ticket-formalization` | 功能父 Ticket、垂直切片、Slice Implementation Contract | 原生 `work-unit.ticket-decomposition`；`yss-router`；`to-tickets` 为兼容入口；生命周期复算 | 依赖、验收、测试 seam 可执行；合同已批准、持久化且为当前版本；`gate.slice-contract-approved`、`gate.slice-ready-for-agent` |
 | 垂直切片实现 `stage.vertical-slice-implementation` | 前端/后端代码、TDD 证据、YSS Skill Execution Result | 原生 `work-unit.slice-implementation`；`yss-router` + `tdd`；前端按 `yss-ui` + `yss-page-module-development`，后端按 Router 最小闭包；`implement` 为兼容入口 | 仅接收已完成 Ticket 正式化、已绑定垂直切片且 `ready-for-agent` 公式通过的输入；只写允许路径；业务行为用 `tdd` 的 `behavior-tdd` 模式；UI 影响必须有还原计划 |

package/template/.claude/skills/yss-product-lifecycle/references/matt-yss-adapter.md

@@ -19,7 +19,7 @@ Matt skills 决定如何工作；YSS 生命周期决定是否允许推进；YSS
 | 通用入口 | `ask-matt` | 检测到 YSS 后由本编排器最终裁决 |
 | 需求澄清 | `grill-with-docs`（用户显式）或 `grilling`、`domain-modeling`（生命周期原语） | 按退出判定检查未决项和回流 |
 | 信息在其他人手中 | `to-questionnaire` | 使用 `external-input-required` 暂停；答案回流后记录 response、重新分类影响面，再进入 `grill-with-docs` 或 `to-spec` |
-| 大型模糊工作 | `wayfinder` | map 真正完成后 `handoff → to-spec` |
+| 大型模糊工作 | `wayfinder`（可选） | 仅在跨会话 / 跨 Agent 或 frontier 不清晰时启用；map 真正完成后 `handoff → to-spec` |
 | 技术事实 | `research` | 一手资料回填 Spec/OpenAPI/架构/ADR |
 | runnable 问题 | `prototype` | 生成单文件可分享 HTML，保留 `prototype/<name>` 分支作为主来源；必须 source/return handoff 和结论回填，不得替代阶段 4 的低保真评审、Ant Design v6 高保真 HTML、AntD CLI 证据和用户确认 |
 | Spec 综合 | 原生 `work-unit.spec-synthesis`；`to-spec`（用户显式兼容） | 初稿进入 `ready-for-human`，不得直接实现 |
@@ -76,7 +76,7 @@ Router 状态映射为：`draft → completed`、`blocked → blocked`、`ready-
 
 ## Review 候选与 Git 授权
 
-YSS 调用 `code-review` 前必须形成 review input，至少包含 `review_mode`、`review_base_ref`、`implementation_candidate_ref`、`candidate_snapshot_ref`、`candidate_digest`、`spec_ref`、`ticket_ref`、`slice_contract_ref`、`build_architecture_checklist_ref` 和 `yss_execution_result_refs`，并满足 `orchestration-contract.yaml.review_input.manifest_required_by_mode`。Standards 还必须编译 `review_standards_route`：合同 `required_skills`、影响面专项检查输入、报告模板与 `finding_disposition`；机器检查按 `run_if_present` 执行。`committed` 审查 merge-base 到不可变 `HEAD`；`worktree` 一次捕获 merge-base 到 working tree 的 committed、staged、unstaged 和 untracked 内容，使用 `yss-worktree-candidate-v1` 规定的 raw path、uint64 big-endian 长度、tracked/untracked record 和不支持条目阻断规则计算 SHA-256，让两个 Reviewer 消费同一不可变快照，并在返回和完成 checkpoint 复核摘要未变化。缺少输入、候选为空、专项覆盖缺失、未关闭 mandatory `violation`、适用行空白或摘要变化时返回 `blocked`，不能缩小审查范围、另起通用审查 skill、由审查者改实现，或合并不同候选的结论。`violation` 类 finding 交实现者在原合同路径修复后全轴复审；`drift` / `new_impacts` 使合同 `stale` 并回 Router。
+YSS 调用 `code-review` 前必须形成 review input，至少包含 `review_mode`、`review_base_ref`、`implementation_candidate_ref`、`candidate_snapshot_ref`、`candidate_digest`、`spec_ref`、`ticket_ref`、`slice_contract_ref`、`build_architecture_checklist_ref` 和 `yss_execution_result_refs`，并满足 `orchestration-contract.yaml.review_input.manifest_required_by_mode`。Standards 还必须编译 `review_standards_route`：合同 `required_skills`、影响面专项检查输入、报告模板与 `finding_disposition`；机器检查按 `run_if_present` 执行。质量标准只从 `engineering-baseline` 引用，禁止在 review input 或切片中另起一份。命中高风险影响时，review input 还要引用 Doubt-Driven 主张 / 反证记录；缺少反证或残余风险未处理时返回 `blocked`。`committed` 审查 merge-base 到不可变 `HEAD`；`worktree` 一次捕获 merge-base 到 working tree 的 committed、staged、unstaged 和 untracked 内容，使用 `yss-worktree-candidate-v1` 规定的 raw path、uint64 big-endian 长度、tracked/untracked record 和不支持条目阻断规则计算 SHA-256，让两个 Reviewer 消费同一不可变快照，并在返回和完成 checkpoint 复核摘要未变化。缺少输入、候选为空、专项覆盖缺失、未关闭 mandatory `violation`、适用行空白或摘要变化时返回 `blocked`，不能缩小审查范围、另起通用审查 skill、由审查者改实现，或合并不同候选的结论。`violation` 类 finding 交实现者在原合同路径修复后全轴复审；`drift` / `new_impacts` 使合同 `stale` 并回 Router。
 
 Matt `implement` 的通用提交指令不构成 YSS Git 授权。只有用户明确给出 `commit_authorized` 为 `true`、非空 `commit_scope` 和 `commit_authorization_ref` 时才能 commit；只有明确给出 `push_authorized` 为 `true`、非空 `push_scope` 和 `push_authorization_ref` 时才能 push。缺少任一字段时保持工作区不变，只输出 checkpoint 判断；不得把 `orchestrate`、实现授权、当前分支、测试通过或负责人要求解释为隐含授权。`git-submodule` 还必须按仓授权、禁止 detached HEAD 提交，并先推子仓再更新父仓 gitlink。
 

package/template/.claude/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/.claude/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/.claude/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/.claude/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 交付状态。