create-yss-spec 3.0.0 → 3.1.0

package/template/.cursor/skills/yss-product-lifecycle/references/user-decisions.md

@@ -0,0 +1,56 @@
+# 关键决策的真实用户回复协议
+
+适用门禁、工作单元和条件事项只由 `docs/agents/digital-human-roles.yaml.user_decision_policy` 定义。本协议解释执行和证据格式，不新增阶段、门禁或 Ticket 状态。专业审查记录与用户决定分别保存；关键决定缺少任一适用条件都不能放行。
+
+## 六条执行规则
+
+1. **先展示，再决定**：先完成可独立执行的检查和可审阅材料，展示资产链接、版本、关键变化、风险、推荐方案、批准范围和批准后的动作。优先使用 `renderDecisionRequest(request)` 生成完整展示文本；也接受原始消息已完整覆盖各项资产、版本、变化、风险、范围、推荐方案和后续动作的等价展示，不能因格式不同重复询问。不得请用户批准尚未形成的资产。
+2. **绑定原始回复**：保存回复人、原始消息引用、回复时间、原文、决定、对应事项、范围及请求摘要。Agent 只能整理，不得生成、推测或补造用户同意。来源记录是可追溯证据，不是密码学身份认证。
+3. **无回复就等待**：超时、默认选项、数字人同意、无反对意见和 Agent 自述均无效。依赖该决定的工作保持 `paused-human-gate` / `ready-for-human`；来源错误等使用 `blocked`。独立工作可以继续，不得借其完成清除未决决定。
+4. **回复必须指向明确**：单项明确请求的“同意”有效。多项需要逐项指定、清楚的子集或“同意以上全部事项”；“继续”不算全部批准。拒绝、修改意见和撤回均保留为有效回复，但不放行。编排器结合原文判定语义；机器核验结构、明确性底线、来源和绑定，不能用自填 `approved` 覆盖相反原文。
+5. **复用已有有效确认**：同一版本、范围和依据不重复询问，不按时间自动过期。相关资产或依据摘要变化、范围扩大或撤回时，旧批准失效；展示差异后重新确认。无关文件变化不触发重新确认。回复按来源时间追加，禁止删除拒绝、修改或撤回记录来恢复旧批准。
+6. **提问者和负责人分开**：默认回复人为提问者。其他业务、技术或发布负责人必须由提问者在原始消息中明确指定，包含对应事项和负责人；数字人不得自行代任。用户表达使用自然语言，内部 ID 和引用由 Agent 整理。
+
+## 记录与来源
+
+使用 `docs/process/schemas/user-decision.schema.json` 和 `docs/process/templates/user-decision-template.yaml`。存于 `docs/.scratch/<feature>/decisions/<request-id>.yaml`；已展示的请求快照不改写，修改方案产生新请求并保留旧引用。请求中的 `subject` 指向可独立摘要的资产正文或冻结快照，批准记录另存，避免正文包含自己的批准摘要形成循环。`basis` 列出影响决定的额外冻结依据。
+
+原始消息可由运行时直接读取，或保存为原始会话导出 / 用户提供的确认文件。跨平台统一捕获封装如下；字段必须来自原始来源，保留原始引用和完整原文，不能把 Agent 编写的摘要包装成来源：
+
+```yaml
+source_kind: session-export # platform-message | session-export | user-confirmation-file
+messages:
+  - id: <原始消息 ID>
+    original_ref: <平台消息链接或用户文件原始位置>
+    principal_ref: <原始作者标识>
+    actor_kind: biological-human # 展示请求的 Agent 消息使用 digital-human
+    sent_at: <原始时间，ISO 8601>
+    text: <完整原文>
+    reply_to: <回复关联的原始请求展示消息引用> # 回复必需；用户确认文件也可携带 request_digest
+```
+
+决定记录中的 `source` 绑定 `kind/ref/digest/message_id`。`ref` 必须可读；平台引用可经运行时的只读解析器提供，CLI 默认读取本地原始捕获封装。不能读取消息时使用原始导出或用户确认文件，不能仅填 URL 假定读取成功。文件摘要只能证明捕获内容一致，不证明作者身份；可信作者与消息内容由运行时或用户提供来源建立。
+
+回复人、时间、原文必须与来源一致。来源还须通过原始 `reply_to` 或用户确认文件中的 `request_digest` 指向当前展示，不能把其他对话中的“同意”嫁接到本次批准。平台没有显式 reply-to 时，可以使用同一原始会话导出中紧邻回复之前、原文和原始引用均匹配的请求消息建立关联；无法建立来源关联就保持等待，不由 Agent 虚构。多项映射使用 `single`、`explicit-items`、`explicit-all`；负责人不同的事项分别回复。`decision` 为 `approved/rejected/changes-requested/unclear/revoked`，只对回复列出的事项和范围生效。需要自然语言补充澄清时保持等待，不要求用户手填内部 schema。
+
+`requestDigest` 对请求除 `presented_source` 外的字段按键排序摘要，避免展示来源循环；展示文本包含该摘要。历史有效回复可导入原始展示消息的完整记录；只要原始展示覆盖当前决定且来源、范围与摘要可核验，即可复用，不要求补发模板消息。不能伪造已展示的新格式。无法证明历史请求与当前资产等价时，重新展示并确认。
+
+## 消费边界
+
+`scripts/verify-user-decision --requirements <当前事项.json> <决定记录.yaml>` 校验当前消费者要求的 `boundary/subject_ref/scope`；未给 `--requirements` 时校验请求中全部事项。无回复的草案可以保存，但不能通过批准验证。局部批准只允许已明确批准的事项推进。
+
+会签记录新增 `subject_ref`、`approval_scope` 和 `user_decision_ref`；checkpoint 门禁同时声明 `subject_ref/approval_scope` 并与会签记录一致。`verify-approval-record` 默认严格验证当前放行条件，`--require-approved` 是显式等价选项；只有 `--history` 仅检查历史记录结构，不构成批准。恢复和门禁关闭必须使用严格校验。旧数字人记录仍可读取和用于专业审查，不自动升级成用户决定。
+
+Workflow Execution Result 使用 `user_decisions` 保存当前要求与证据引用。`user_decision_not_applicable` 仅对未命中的既有技术条件门禁记录 `boundary/reason`，不得跳过已经执行的业务决策。完成结果通过 `validateNextRoute(..., result)` 检查；两参数调用仅检查路由结构，不能证明可以实际流转。
+
+checkpoint 的 `human_review` 保存 `user_decisions`、`required_decisions`、`not_applicable` 和需要时的 `external_input`。`stage_trace.completed_work_unit` 标识已完成单元；进入实施时 `human_review.implementation` 保存当前切片及持久化合同引用。等待态可以保存；恢复、流转和完成时重新核验。外部回复、新授权、风险接受均以同一决定记录作为恢复依据，不能以工具恢复或默认答案替代。
+
+## 首次实施与脚手架
+
+首次实施批准的主体为功能级 `implementation-scope` 清单，`slices` 每行包含：`ticket_ref`、`contract`（ref/version/digest）、`repositories`、`allowed_write_paths`、`baselines`（ref/version/digest）。仓库与写路径必须对应当前合同 `common.project_roots/allowed_write_paths`；基线包含合同引用的工程基线。`scope` 使用批准的切片引用集合。合同、范围或基线变化时回到确认；已覆盖的后续切片复用原记录。
+
+实施就绪和派发必须同时提供 `user_decisions`、`slice_contract_ref` 与 `vertical_slice_ticket_ref`。Worker 任务包通过 `user_decisions` 传递记录，不能只声明 `ready_for_agent=true`。
+
+脚手架 `user_confirmation` 新增 `user_decision_ref/decision_subject_ref`，主体为生成前的决策输入快照；当前范围至少包含项目 ID、确认的架构和 `decision_inputs_digest`。先获得真实回复，再由生命周期批准生成合同；不能回到生成器内提问。
+
+Git commit/push、外部动作仍分别检查已有授权和其范围。用户对一个具体动作的明确自然语言授权可整理成结构化记录，不必再次要求填写内部字段；生命周期批准不隐含其他动作授权。

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

@@ -1,47 +1,58 @@
 ---
 name: yss-prototype-stage
-description: Use when a YSS feature has product-design impact on a primary flow, navigation, state, recovery, permission experience, or UI-driven API contract and needs prototype assets before implementation readiness.
+description: Use when a YSS feature has product-design impact on a primary flow, navigation, state, recovery, permission experience, or UI-driven API contract and needs profile-routed prototype assets before implementation readiness.
 ---
 
 # YSS Prototype Stage
 
-把产品设计影响收敛为跨 Agent 一致的产物、证据和生命周期回流合同。它不替代 `yss-product-lifecycle` 的门禁裁决，也不把原型当作生产前端代码。
+把产品设计影响收敛为跨 Agent 一致的原型交付物、证据和生命周期回流合同。它不替代 `yss-product-lifecycle` 的门禁裁决，也不把原型当作生产前端代码。
 
 ## 进入条件与主入口
 
 - 先由 `yss-product-lifecycle` 判断产品设计影响；无行为变化的孤立视觉修复记录 `not-applicable`，不创建空资产。
-- Codex 的产出主入口是 `product-design:index`；其他 Agent 使用等价的产品设计能力，但必须产出本技能规定的相同资产和证据。能力或证据不能等价时，暂停并回到人工确认。
-- `high-fidelity-html-prototype` 仅为历史兼容入口；从它进入时立即回到本合同。已退休的原型技能（含 `product-design-prototype`）不得继续路由。
+- 先读取 Spec、产品总体设计、`CONTEXT.md`、`yss-design-system`，再按 `DESIGN.md` → `docs/design/design.md` → `docs/design/tokens/*` 顺序消费设计基线，形成交互说明、低保真页面/流程和状态矩阵。
+- 用独立 `prototype-review` 评审低保真与状态；未通过不得选择档位或构建原型交付物。
+- 按 [原型档位路由](references/prototype-profile-routing.md) 选择 H1/H2 中满足当前决策风险的最低档位。没有充分证据时默认 H2。
+- Codex 按档位消费 `product-design:index` 的 focused workflow；H1 可直接走静态适配器，H2 使用 `get-context/image-to-code/design-qa`。其他 Agent 必须交付等价合同资产。
+- `high-fidelity-html-prototype` 仅为历史兼容入口；新资产统一为 `artifact.prototype-deliverable`、Prototype Evidence schema v4 与 Visual Baseline schema v1。
 
-## 资产与门禁顺序
+## 执行顺序
 
-1. 以 Spec、产品总体设计、`yss-design-system` 和 `docs/design/design.md` 形成交互说明、低保真页面/流程与状态矩阵。
-2. 用 `prototype-review` 形成独立评审结论；未通过不得生成高保真或进入需求冻结。
-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。
+1. 形成交互说明、低保真与状态矩阵；状态至少包含事件、转换、guard、动作与可退出路径。
+2. 完成独立 `prototype-review`，提取仍需由原型回答的风险。
+3. 计算并记录 `prototype_profile`。新视觉方向或信息架构不确定时执行三方案 ideation；复用已批准模式时记录 `not-applicable` 与 source visual。
+4. H1 用 `prototype-contract.mjs prepare-static` 生成无 Node 运行时的静态适配器；H2 按 `references/product-design-adapter.md` 构建可运行流程。
+5. 自动采集版本、digest、视口、截图、console 与扫描结果。截图按 `route + page + state + viewport + theme + locale + data_scenario` 写入 `Visual Baseline Bundle`，执行 `visual-baseline-contract.mjs seal` 后由 feature 级 schema v4 `prototype-evidence.yaml` 引用；人工只补决策、风险、允许差异和用户确认。
+6. 以统一六轴 Design QA 和档位验证矩阵完成浏览器/无障碍验证。用户确认后才可校准 Spec、分析 API 影响或进入 实现合同编译器 readiness。
 
-## 设计与 AntD 依据
+## 档位边界
 
-优先级固定为：官方 `design.md` 的上游默认 → `docs/design/design.md` 与项目 token 的 `project_design` 项目覆盖 → 当前功能的语义组件映射。不得用上游默认覆盖项目 token。
+- H1 `visual-review`：浏览器可复验的 HTML/CSS/少量 JS 或设计工具导出；不得要求 `package.json`、lockfile、Node 或 AntD CLI。
+- H2 `flow-review`：主流程与关键异常状态可操作；Vue 3/Vite + Antdv Next 是受支持默认。React/Vite + Ant Design v6 仅作为显式兼容路线；只消费与实际 `component_basis` 匹配的精确版本事实或 fresh fact pack。
+- 原型代码默认 throwaway；可复用的是项目 Token、组件语义映射、状态、测试场景和验收标准。任何源码进入生产仍需 实现合同编译器、Slice Contract 和 TDD。
+- 原型阶段不得调用 `yss-ui`，不得读取生产组件 API 来制造“真实组件原型”。需要核验真实 YSS/AntDV 组件的事项写入 `implementation_handoff`，由前端实现计划、已批准切片的实现和实现还原验证负责。
 
-Codex `$design-qa` 仍走官方对比流程；Colors/tokens 与 Fonts/typography 必须以项目覆盖为 source visual truth。对照清单见 `yss-design-system/references/design-qa-theme.md`。仍用官方 `#1677ff`、强制 `Inter` 或历史 8px 品牌圆角当默认主题，视为项目覆盖漂移。
+## 事实、QA 与确认
 
-主题与视觉标准固定为 `ant-design-v6`；生产运行时固定为 Vue 3 + YSS UI + `ant-design-vue-4.x`，精确生产版本来自实现仓 lockfile。版本号不同本身不是冲突。Ant Design v6 事实由 `yss-antd-design` 查询并回写证据，不要并列调用官方 `antd` skill，也不要在前端代码落地时继续使用它。进入实现后改走 `yss-ui`。
+优先级固定为：项目根 `DESIGN.md` 规范 Token / 组件变体 → `docs/design/design.md` 治理解释 → `docs/design/tokens/*` 派生快照 → 当前功能语义 → 相关上游组件事实。H2 默认通过 `yss-antdv-next-design` 使用 Antdv Next exact-version fact pack；只有显式选择 `react-antd-6` 时才调用 `yss-antd-design`。fact pack 仅在精确版本、组件集合、根 `DESIGN.md` digest 和项目 Token digest 均匹配且无新 API 疑问时可复用；否则做增量查询。`antd lint/doctor` 只对 React 兼容路线的相关源文件执行。
 
-标准原型组件存在 Ant Design 实现时必须精确锁定与 CLI 目标一致的 `antd@6.x`，并通过 `ConfigProvider` 消费项目主题 adapter。执行与验证命令见 `references/product-design-adapter.md` 和 `scripts/prototype-contract.mjs`。
+Design QA 合并 visual、layout、interaction、content、accessibility、cross-platform 六轴，不再建立第二份评审。所有档位至少证明 desktop/narrow 非空渲染、项目 Token、console 和基础键盘/焦点/对比度；H2 追加主流程、关键异常、200% zoom/reduced motion 与按风险视觉回归。图片是视觉基准而非唯一事实来源；模型必须从 `visual-baseline.yaml` 的 `case_id` 读取对应语义引用，禁止靠目录 glob 猜测页面含义。
 
-## 验证与回流
+用户确认必须绑定提问者或其明确指定负责人的原始回复，使用生命周期 `user_decision_policy` 和统一用户决定记录；产品数字人只提供确认建议，不能代答。正式证据追加 `user_decision_ref/decision_subject_ref`，校验原型、视觉基线和操作范围与用户所见快照一致。用户确认只描述原型确认了什么、哪些范围可操作、哪些为模拟或 gap，以及接受/拒绝结论；不要求用户确认技术栈、CLI 或构建细节。
 
-`browser_verification` 至少覆盖非空渲染、主流程、一个失败/权限/冲突状态、桌面与窄屏视口和控制台错误；`accessibility_verification` 至少覆盖对比度、键盘/焦点、语义标签与 Dialog、200% zoom、reduced motion、目标尺寸和自动化扫描。优先使用 Browser 或可执行浏览器自动化，Computer Use 只作人工交互补充。把路径、命令、版本、视口、结果和阻塞项写入证据清单。
+`gate.prototype-reviewed`、`gate.prototype-verified`、`gate.user-confirmation` 保持三个既有门禁。档位选择是 `gate.prototype-verified` 的输入证据，不增加新门禁，也不授权实现。
 
-`gate.prototype-reviewed` 的证据是评审记录；`gate.prototype-verified` 的证据是 AntD CLI 与浏览器验证；`gate.user-confirmation` 的证据是确认记录。三者均不是实现授权。
+## 按需读取
+
+- 档位、上游融合与迁移：[prototype-profile-routing.md](references/prototype-profile-routing.md)
+- 渲染适配、fact pack 与命令：[product-design-adapter.md](references/product-design-adapter.md)
+- 证据模板：`docs/design/templates/prototype-evidence-template.yaml`
+- Visual Baseline 模板与 schema：`docs/design/templates/visual-baseline-template.yaml`、`docs/design/schemas/visual-baseline.schema.json`
 
 ## 常见错误
 
-- 仅有截图或 HTML，却没有可复现的 CLI、浏览器和确认记录。
-- 把 `product-design:index` 或某个旧技能当作生命周期批准者。
-- 直接复制官方默认颜色、圆角或间距，忽略项目覆盖。
-- 只证明查询过 AntD v6，却没有 v6 semantic role → 项目 Token → YSS/AntDV4 的映射证据。
-- 沿用 Product Design starter 的 npm、根目录 `design-qa.md` 或未安装 `antd` 的通用配置。
+- 继续把 React/AntD 当作 H2 默认，或把单个 HTML 文件当成所有档位的答案。
+- 低保真未评审就选择技术栈；用主观评分代替确定性触发规则。
+- H1 伪造 lockfile/AntD 段，或 H2 声称已验证生产 YSS/AntDV 真实组件。
+- 重复抄写机器可采集的版本、digest、截图和 console；创建第二份状态机、QA 或 handoff 资产。
+- 把原型源码直接复制进生产，或在原型阶段调用 `yss-ui`。

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

@@ -1,54 +1,82 @@
-# YSS Product Design Adapter
+# YSS 原型渲染适配器
 
-本合同把 Codex Product Design 的通用 React/Vite 产出接入 YSS 原型阶段。它不修改上游 Product Design skill，也不把 React API 带入 Vue 生产实现。
+生命周期调用方只选择 H1/H2 并验证 schema v3；静态与流程原型渲染细节留在本适配器内。
 
-## 双轨版本
+## H1：静态视觉评审
 
-- `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 实现合同。
+目录固定为 `docs/.scratch/<feature>/design/prototypes/`。运行：
 
-## 产出前适配
+```bash
+node .agents/skills/yss-prototype-stage/scripts/prototype-contract.mjs prepare-static \
+  --project-root <project-root> \
+  --root <project-root>/docs/.scratch/<feature>/design/prototypes \
+  --feature <feature>
+```
 
-1. 目标目录固定为 `docs/.scratch/<feature>/design/prototypes/`。
-2. Product Design 完成 `get-context`、三方案 `ideate` 和用户视觉选择后，进入 `image-to-code` 的 local preflight，只执行官方 bootstrap 创建空 starter；在安装依赖或编写 UI 前立即运行 adapter：
+命令生成语义化 `index.html`、`styles.css` 和 `yss-prototype-adapter.json`，引用项目 Token CSS。它不创建 `package.json`、lockfile、`node_modules` 或运行时构建合同。设计者在此最小壳中实现布局和少量关键交互；交付可以是静态目录或 URL，不要求单文件。
 
-   ```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 \
+  --profile H1 --root <prototype-root>
+```
 
-   ```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>
-   ```
+## H2：可运行流程
 
-## 视觉与实现映射
+H2 可选择任何能稳定浏览器交付的轻量前端实现。默认 `component_basis=vue-antdv-next`，使用 Vue 3/Vite + Antdv Next：
 
-每个关键组件在 `visual_semantic_mapping` 中记录四层映射：Ant Design v6 semantic role、项目 Token、React 原型组件、生产 YSS/Ant Design Vue 目标。映射的是视觉角色、状态和验收行为，不是 React API 表面形状。
+```bash
+node .agents/skills/yss-prototype-stage/scripts/prototype-contract.mjs prepare-flow \
+  --project-root <project-root> \
+  --root <prototype-root> \
+  --feature <feature> \
+  --pnpm-version <actual-pnpm-version>
 
-至少覆盖主操作、表单输入、表格/列表、反馈、弹层和导航中本功能实际出现的类型。每项记录 `default/hover/active/disabled/loading/error` 等适用状态，并把 `react_only_api_not_copied` 设为 `true` 后才能通过。
+node .agents/skills/yss-prototype-stage/scripts/prototype-contract.mjs validate-project \
+  --profile H2 --root <prototype-root>
+```
 
-## 视口、QA 与无障碍
+默认命令生成最小 Vue/Vite starter，精确写入 `antdv-next@1.5.2`、`vue@3.5.21`、`vite@6.4.2`、`@vitejs/plugin-vue@5.2.4`，登记实际 pnpm，生成 Vue 入口、`src/yss-theme.js` 与 provider-neutral adapter schema v3。设计 workflow 在 starter 中替换占位页面，再以 `ConfigProvider`、`pnpm install`、`pnpm build` 形成可移植静态输出。已有 Vue 页面不会被重写，但必须通过合同验证。
 
-- 默认视觉目标和同状态 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。
+显式兼容 React/Vite + Ant Design v6 时传入：
 
-## 交互档位
+```bash
+node .agents/skills/yss-prototype-stage/scripts/prototype-contract.mjs prepare-flow \
+  --project-root <project-root> \
+  --root <prototype-root> \
+  --feature <feature> \
+  --component-basis react-antd-6 \
+  --library-version <exact-6.x-version> \
+  --pnpm-version <actual-pnpm-version>
+```
 
-- `reviewable-flow`（默认）：合同内主路径和关键状态可操作；非范围控件禁用或明确标注，不伪装完整功能。
-- `full-prototype`：brief 明确要求的全部可见范围控件可操作。
+历史 `--target-antd-version` 继续映射到 `react-antd-6`，只为在途兼容，不再是默认调用。其他 H2 基座必须在证据中明确记录，不得伪造 Antdv Next 或 AntD 字段。
 
-不得使用含义冲突的 `static` / `mostly-static` 作为 YSS 交付状态。
+### Provider fact pack
+
+默认目录为 `docs/design/facts/antdv-next/<exact-version>/`；React 兼容路线使用 `docs/design/facts/antd/<exact-version>/`。至少包含 `manifest.json`、design-md 摘要、组件事实与 digest。只有以下全部相等才为 fresh：
+
+- manifest 的 package 与 exact version 等于原型 lockfile；
+- 所需组件均被覆盖；
+- 根 `DESIGN.md` path / digest 与当前规范源相等；
+- `project_token_baseline_digest` 等于当前 Token 派生基线；
+- 没有新的 API/semantic 疑问。
+
+不满足时只查询缺失或变化的事实。默认 Vue 路线调用 `yss-antdv-next-design`；React 兼容路线调用 `yss-antd-design`，且 `lint/doctor` 只在存在相关 React 源时运行。不要创建占位 fact 目录；feature 证据只引用实际 manifest。
+
+## 共同映射与验证
+
+映射的是 semantic role、项目 Token、状态和验收行为，不是 React API 表面。默认视口为 desktop `1440x900` 与 narrow `390x844`；按影响追加其他断点。Design QA 固定写 feature 级 verification 路径，并按 visual/layout/interaction/content/accessibility/cross-platform 六轴执行。
+
+浏览器/Design QA 将每个风险驱动 case 捕获为 PNG，写入 `docs/.scratch/<feature>/handoff/visual-baseline-v<version>/images/`，并从 `docs/design/templates/visual-baseline-template.yaml` 生成 manifest。截图必须使用固定数据、sRGB、DPR 1，等待字体完成，关闭动画、过渡和光标闪烁；长页面使用固定滚动分段。捕获完成后运行：
+
+```bash
+node .agents/skills/yss-prototype-stage/scripts/visual-baseline-contract.mjs seal \
+  docs/.scratch/<feature>/handoff/visual-baseline-v1/visual-baseline.yaml \
+  --bundle-root docs/.scratch/<feature>/handoff/visual-baseline-v1
+```
+
+`seal` 校验 PNG 尺寸与大小并写入图像和整包摘要；随后以 `validate` 重验。模型和下游实现只从 manifest 的 `case_id` 取图，不通过 glob 推断含义。工作目录可位于被忽略的 `.scratch`，但 Strategic Design Handoff 必须携带或引用可读取的自包含 Bundle。
+
+H1/H2 的条件验证矩阵与实现阶段交接规则见 [prototype-profile-routing.md](prototype-profile-routing.md)。原型阶段禁止调用 `yss-ui`；真实组件事实只在批准后的前端实现与实现还原验证中取得。

package/template/.cursor/skills/yss-prototype-stage/references/prototype-profile-routing.md

@@ -0,0 +1,69 @@
+# 原型档位路由与 Designer Skills 适配
+
+本合同是 `artifact.prototype-deliverable` 的档位选择单一入口。生命周期只依赖 `prototype_profile` 和统一证据，不感知渲染器内部结构。
+
+## 选择算法
+
+先读取已批准 Spec、交互说明、低保真、状态矩阵和独立 `prototype-review`。按下列确定性规则选择，最高命中档位优先；无命中或证据不充分时使用 H2。人工可以直接升级，降级必须写明已关闭的触发风险与证据。
+
+| 档位 | 名称 | 命中条件 | 默认适配器 |
+|---|---|---|---|
+| H1 | `visual-review` | 仅需确认布局、密度、层级、文案或少量关键交互；不涉及多页面导航、复杂联动、权限、恢复、冲突或真实组件差异 | 语义 HTML + 项目 Token CSS + 最小 JavaScript；可使用设计工具导出，但必须有浏览器可复验入口 |
+| H2 | `flow-review` | 多页面/路由、复杂表单联动、权限体验、失败恢复、并发冲突或需要可操作主流程测试 | 可运行前端原型；Vue 3/Vite + Antdv Next 是受支持默认，React/Vite + Ant Design v6 为显式兼容路线 |
+
+真实 YSS/AntDV 组件行为、lockfile、props、slots、events 或 Storybook 状态不是第三种原型档位。它们属于前端实现计划、已批准切片的生产实现与实现还原验证。原型中发现的相关不确定性写入 `implementation_handoff`，不得为解决它调用 `yss-ui` 或把实现仓组件代码引入原型。
+
+## 共同资产
+
+- `decision_to_inform`：本轮原型要支持的具体决策。
+- `risk_assumptions` 与 `trigger_results`：机器可读档位来源。
+- Spec、交互说明、状态矩阵、设计系统与低保真评审引用。
+- 浏览器入口、产物 digest、desktop/narrow 非空渲染、console 结果，以及由 `case_id` 定位的 Visual Baseline Bundle。
+- 统一 Design QA 六轴：visual、layout、interaction、content、accessibility、cross-platform。
+- 独立原型评审引用、用户确认、blockers 和 gaps。
+- `implementation_handoff`：只记录生产组件假设、待验证事项和目标阶段，不提前执行生产组件核验。
+
+机器优先采集版本、digest、视口、截图、console 与扫描结果；人只填写决策、风险解释、允许差异和用户确认。PNG 基准图统一使用 sRGB、DPR 1，关闭动画并隐藏光标；长页面使用固定滚动分段，full-page 只可作总览。每张图不超过 5 MiB，整包不超过 100 MiB。不得把同一事实复制到多个段落。
+
+`visual-baseline.yaml` 是模型与实现验证的唯一图片索引。每个 case 必须绑定 route、page、state、viewport、theme、locale、data scenario、PNG digest、语义引用和允许差异；至少覆盖 1440x900 与 390x844。原型用户确认时冻结版本，后续变更创建新版本并使依赖的实现计划与 Slice Contract `stale`，禁止覆盖旧版本。
+
+## 档位证据
+
+### H1
+
+- 浏览器不依赖 Node/runtime build；原型目录不得伪造 `package.json`、lockfile 或 AntD 查询段。
+- 至少验证一个或少量关键交互，以及基础键盘、焦点和对比度。
+- 200% zoom 与 reduced motion 只在影响面命中时要求；视觉回归和真实组件 story 不强制。
+
+### H2
+
+- 主流程与关键 failure / no-permission / conflict 状态可操作。
+- 验证键盘、焦点、对比度、200% zoom、reduced motion；按风险决定视觉回归。
+- 默认使用 `vue-antdv-next` 并记录 package 与精确版本；显式兼容路线记录 `react-antd-6`。fact pack 只有在 provider、版本、组件集合和项目 Token baseline digest 全部匹配且没有新 API 疑问时才可复用，否则只补增量查询。
+- 使用其他基座时记录 `component_basis`，不创建空 Antdv Next 或 AntD 字段。
+
+### 实现阶段交接
+
+- 若原型结论依赖真实 YSS/AntDV 组件能力，在 `implementation_handoff.production_component_assumptions` 中记录假设，在 `verification_targets` 中写明待验证行为。
+- 实现合同编译器 将这些事项编入 `frontend_implementation_plan`；真实组件事实在实现准备或进入已批准切片后由 `yss-ui` 基于目标 lockfile 核验，最终写入 `frontend_implementation_verification`。
+- 原型门禁只证明设计决策、流程与状态可验证，不得声称已证明生产组件兼容性。
+
+## 条件 ideation
+
+新视觉方向、信息架构不确定或存在两个以上合理布局时，`product-design:ideate` 的三方案比较为 mandatory。沿用已批准模式且 source visual 可定位时记录 `not-applicable`、复用来源和理由，不制造三份无意义变体。
+
+## 上游融合记录
+
+- 来源：`https://github.com/Owl-Listener/designer-skills`
+- 检查 revision：`20e34c4a587e5eb09fcdf8351fa97b3ad761b31e`
+- 许可证：MIT
+- 采用：`prototype-strategy` → 本档位算法；`state-machine` → 现有状态矩阵；`design-qa-checklist` → 统一六轴 QA；`handoff-spec` → 交互说明、状态矩阵、前端实现计划与 Slice 合同。
+- 不采用：上游 107 skills / 32 commands 的整包安装、第二套生命周期与第二份 handoff 资产。
+- 更新：仅人工 diff 新 revision；YSS `CONTEXT.md`、生命周期注册表、设计系统与本合同冲突时始终以 YSS SSOT 为准。
+- `taste-skill` revision `ccbc15639c97057cbfcf32ecebc38ef716e4bb37` 本轮不集成；未来只能作为 H1/H2 可选视觉 lens，不能覆盖 dashboard、data table 或 multi-step flow 的主合同。
+
+## 迁移
+
+- 新证据只生成 schema v4、Visual Baseline schema v1 与 `artifact.prototype-deliverable`。
+- prototype evidence schema v1/v2/v3 和 `artifact.high-fidelity-html-prototype` 只读兼容；已经关闭的历史证据保持有效，不补造图片。
+- 在途 UI 证据必须迁移到 v4 并产生 Visual Baseline 后才能关闭 `gate.prototype-verified`；非 UI 功能不生成空包。