create-yss-spec 2.2.7 → 2.2.8

package/README.md

@@ -52,7 +52,7 @@ npx create-yss-spec@latest --version
 
 ## 当前版本说明
 
-当前 CLI 版本为 `2.2.7`，模板固定到 `96fb0900f8f49e42fe17d36e4cac4717b341bcf2`，同步 Archify 安全 receipt 写入修复及稳定交付路径示例。
+当前 CLI 版本为 `2.2.8`，模板固定到 `f9f97eb080519b3388be12fed07b2ce0e026b04b`，同步 L3 模板维护证据策略更新。
 
 ## 接管已有项目
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-yss-spec",
-  "version": "2.2.7",
+  "version": "2.2.8",
   "description": "Initialize a YSS spec project template repository",
   "repository": {
     "type": "git",

package/template/.agents/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/.agents/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/.agents/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/.agents/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/.agents/skills/yss-product-lifecycle/SKILL.md

@@ -31,7 +31,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/.agents/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

package/template/.agents/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/.agents/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/.agents/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/.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-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