create-yss-spec 3.0.0 → 3.0.1

package/template/docs/design/design.md

@@ -63,7 +63,7 @@ node .template-source/tooling/node/scripts/design-md.mjs drift
 
 Codex `$design-qa` 的 Colors/tokens 与 Fonts/typography 对照必须以本文件和 `docs/design/tokens/*` 为 source visual truth，而不是官方默认或历史 `#1677ff` / `Inter` / `8px` 品牌圆角。执行清单见 `.agents/skills/yss-design-system/references/design-qa-theme.md`。
 
-版本边界固定为双轨：高保真原型以 React Ant Design v6 的 `design.md`、semantic token 和标准组件事实作为主题样式基线；生产实现使用 Vue 3、YSS UI 与目标实现仓 lockfile 中的 Ant Design Vue 4.x API。两者版本号不同不是冲突。原型到生产只迁移视觉角色、项目 Token、状态和验收行为，禁止迁移 React hook、props、JSX、静态 API 或事件模型。
+版本边界按原型档位处理：H1 直接消费项目 Token；H2 仅在采用 React AntD 时以 Ant Design v6 的 `design.md`、semantic token 和标准组件事实为补充。原型阶段不得调用 `yss-ui`；生产实现进入批准切片后才从目标实现仓 lockfile 中读取 Vue 3、YSS UI 与 Ant Design Vue 的真实 API。原型到生产只迁移视觉角色、项目 Token、状态和验收行为，禁止把 React hook、props、JSX、静态 API 或事件模型当作 Vue 合同。
 
 ## 设计原则
 
@@ -181,7 +181,7 @@ Codex `$design-qa` 的 Colors/tokens 与 Fonts/typography 对照必须以本文
 
 ### 紧凑密度（默认原型规格）
 
-高保真原型和中后台数据密集页面默认使用紧凑密度。紧凑密度不是把所有间距机械缩小，而是使用 `docs/design/tokens/tokens.compact.json` 和下表控制页面节奏；没有明确的展示型或触屏场景时，不切回宽松密度。
+原型交付物和中后台数据密集页面默认使用紧凑密度。紧凑密度不是把所有间距机械缩小，而是使用 `docs/design/tokens/tokens.compact.json` 和下表控制页面节奏；没有明确的展示型或触屏场景时，不切回宽松密度。
 
 | 场景 | Padding | Margin / Gap | 说明 |
 | --- | --- | --- | --- |
@@ -266,24 +266,32 @@ Margin 使用规则：组件自身默认不声明外部 margin，兄弟元素之
 - 避免大面积渐变、装饰插画、夸张 hero、过多卡片化包装和单色系视觉堆叠。
 - 权限不足、只读、空数据、加载中、校验失败、冲突、提交成功等状态必须在设计阶段明确。
 
-## 高保真原型交付规格
+## 原型交付规格
 
-高保真原型的主产物是可在浏览器运行和复验的 HTML，而不是截图、设计说明或生产前端代码。默认入口固定为 `docs/.scratch/<feature>/design/prototypes/index.html`；关联 CSS、JavaScript、字体和本地资源应与入口一起存放在该目录内，保持相对路径可移植。
+原型交付物必须提供可在浏览器运行或复验的稳定入口，而不是只给截图、设计说明或生产前端代码。默认入口为 `docs/.scratch/<feature>/design/prototypes/index.html`；也可交付稳定 URL。关联资源保持相对路径可移植，不强制内联成单文件。
 
-- HTML 必须呈现真实页面密度、Card、表单、筛选、表格、弹层和状态反馈；不得只输出静态画布或图片热区。
-- 默认启用本文件定义的紧凑密度：页面 padding、区域 gap、Card `8px` 圆角、Card padding 和 `28px` 控件高度必须可在浏览器计算样式中复核。
-- 至少覆盖主流程、一个 loading / empty 状态，以及一个 error / no-permission / conflict 状态；主操作必须产生可见反馈。
-- HTML 是评审与确认主载体；截图只作为指定视口和指定状态的验证证据，不能替代 HTML。
-- 原型可以使用构建工具生成，但交付目录必须提供稳定的 `index.html` 入口。依赖开发服务器时，证据中必须记录启动命令、实际端口和版本；不得只交付无法独立定位入口的源码目录。
-- 标准组件存在 Ant Design 实现时，React 原型必须精确锁定与 CLI 查询一致的 `antd@6.x`，使用 pnpm lockfile，并通过 `ConfigProvider` 消费由 `docs/design/tokens/theme.json` 转换出的可执行 ThemeConfig。生产映射仍以 YSS UI / Ant Design Vue 4.x lockfile 为准。
-- Design QA、浏览器验证和视觉目标必须使用同一视口与同一状态；默认 desktop `1440×900`、mobile `390×844`，按实际影响追加其他视口。
-- 原型仍须通过 `prototype-review`、AntD CLI 事实核对和浏览器验证；HTML 存在不代表 `gate.prototype-reviewed`、`gate.prototype-verified` 或 `gate.user-confirmation` 已通过。
+低保真与状态矩阵经独立 `prototype-review` 后，按风险选择满足当前决策的最低档位：
+
+| 档位 | 用途 | 技术边界 | 最低验证 |
+|---|---|---|---|
+| H1 `visual-review` | 布局、密度、层级、文案和少量关键交互 | 语义 HTML/CSS/最小 JS 或设计工具导出；无需 Node、package、lockfile 或 AntD CLI | desktop/narrow 非空渲染、项目 Token、console、关键交互、基础键盘/焦点/对比度；zoom/reduced-motion 按影响 |
+| H2 `flow-review` | 主流程、权限、失败恢复、复杂联动和冲突 | 浏览器可运行流程；React/Vite + AntD v6 是受支持默认而非强制 | H1 共同证据 + 主流程、关键异常、zoom/reduced-motion；视觉回归按风险 |
+
+- H1 不得为了“显得完整”创建空 `package.json`、lockfile 或 AntD 证据。H2 不得声明真实目标组件已验证。
+- 原型中识别出的生产组件假设与待验行为写入 `implementation_handoff`，由 `frontend_implementation_plan` 和 `frontend_implementation_verification` 承接；不得在原型阶段引入 `yss-ui`、目标 lockfile 或 Storybook。
+- 新视觉方向、信息架构不确定或有多个合理方案时执行三方案 ideation；复用已批准视觉模式时记录 source visual 与 `not-applicable` 理由。
+- 默认启用紧凑密度；页面 padding、gap、Card 圆角、Card padding 和控件高度必须在浏览器计算样式中可复核。
+- Design QA、浏览器验证和视觉目标使用同一视口与同一状态；默认 desktop `1440×900`、narrow `390×844`。
+- Design QA 统一覆盖 visual、layout、interaction、content、accessibility、cross-platform 六轴，不再复制第二份检查清单。
+- AntD fact pack 仅在精确版本、组件集合、项目 Token baseline digest 相同且没有新 API 疑问时复用；否则做增量查询。`lint/doctor` 只在存在相关 React 源时执行。
+- 原型源码默认 throwaway；项目 Token、组件语义映射、状态、测试场景和验收标准可以进入下游，源码复用仍需 实现合同编译器、Slice Contract 与 TDD。
+- 用户确认只覆盖原型确认的决定、可操作范围、模拟/gap 与接受结论；HTML、story 或截图存在都不代表三个产品设计门禁已经通过。
 
 ### 无障碍覆盖
 
 品牌 Seed `#3371ff` 保持项目身份，不等于每个组件状态都必须直接使用该填充。普通文本或控件状态不满足 WCAG 2.2 AA 时，优先通过组件 Token 调整实际填充色或文字色，并同时验证 default、hover、active、disabled 与 focus；不得用单页特例色绕过主题层。
 
-原型证据至少覆盖对比度、键盘导航、焦点顺序与可见焦点、语义标签和 Dialog 焦点管理、200% zoom、`prefers-reduced-motion`、目标尺寸及自动化扫描。组件库默认能力不能替代对真实页面 DOM 与交互的验证。
+原型证据按档位覆盖无障碍：所有档位至少检查对比度、键盘导航、焦点顺序与可见焦点；H2 追加语义标签/Dialog、200% zoom、`prefers-reduced-motion`、目标尺寸及适用扫描。组件库默认能力不能替代对真实页面 DOM 与交互的验证。
 
 ## 响应式验收矩阵
 
@@ -318,7 +326,7 @@ Margin 使用规则：组件自身默认不声明外部 margin，兄弟元素之
 - 组件样式优先通过 Ant Design token、component token、CSS variables 或主题算法表达。
 - 消息、通知、Modal 静态方法应使用 `App`、hook API 或 context holder，避免主题上下文丢失。
 - 暗色模式使用 `darkAlgorithm` 或 `docs/design/tokens/variables.dark.css`，不要手工反转颜色。本轮只同步了暗色的字体栈和圆角 seed；完整暗色色板仍是历史算法结果，启用暗色前应再派生一次。
-- 紧凑模式默认使用 `compactAlgorithm` 或 `docs/design/tokens/tokens.compact.json`，不要逐组件压缩高度；高保真 HTML 必须按紧凑 token 验收实际 padding、gap、Card 圆角和控件高度。
+- 紧凑模式默认使用 `compactAlgorithm` 或 `docs/design/tokens/tokens.compact.json`，不要逐组件压缩高度；原型交付物必须按紧凑 token 验收实际 padding、gap、Card 圆角和控件高度。
 
 如果前端不是 Ant Design：
 
@@ -345,13 +353,13 @@ Margin 使用规则：组件自身默认不声明外部 margin，兄弟元素之
 - 将 `docs/design/tokens/theme.json` 接入前端工程主题配置。
 - 将 `docs/design/tokens/variables.css` 中的 `--brand-*` 与运行时别名纳入项目 token 管理。
 - 如果项目启用暗色模式，用 `darkAlgorithm` 按新 seed 重派生 `docs/design/tokens/tokens.dark.json`，并补充截图验收。
-- 将高保真 HTML 原型模板默认接入 `docs/design/tokens/tokens.compact.json`，并在浏览器证据中记录实际计算后的 padding、gap、Card 圆角和控件高度。
+- 让三档原型适配器默认接入项目 Token，并在浏览器证据中记录实际计算后的 padding、gap、Card 圆角和控件高度。
 
 ## Ant Design v6 原型补充基线
 
-本节根据官方 `https://ant.design/design.md` 与本轮固定目标版本的 `antd design.md --format json` 提炼，用于高保真原型和后续前端实现，不替代项目 token，也不提供 Ant Design Vue API。
+本节根据官方 `https://ant.design/design.md` 与目标版本的 `antd design.md --format json` 提炼，仅用于采用 React AntD 的 H2 和语义映射，不替代项目 token，也不提供 Ant Design Vue API。
 
 - 先按 `bg-layout`、`bg-container`、`bg-elevated`、文本、边框、状态、圆角和阴影等 semantic token 角色设计，再映射到 `ConfigProvider`、组件 token 或 CSS variables；不得用页面局部色值替代主题层。
-- 默认亮色使用 `theme.defaultAlgorithm`；高保真原型默认叠加紧凑密度 algorithm，暗色和紧凑密度均通过 theme algorithm 切换，禁止手工反色或逐控件压缩。
+- 默认亮色使用 `theme.defaultAlgorithm`；相关 H2 默认叠加紧凑密度 algorithm，暗色和紧凑密度均通过 theme algorithm 切换，禁止手工反色或逐控件压缩。
 - 每个决策区域只保留一个 single primary action。保存、提交、审批、发布、导出和重试等动作必须提供 interaction feedback；不可逆或高风险动作使用确认弹窗。
 - 对实际字号、图标和背景复核 accessibility contrast。默认 token 不足时，通过种子 token 或组件 token 调整，不引入单页特例色。

package/template/docs/design/templates/interaction-spec-template.md

@@ -12,8 +12,8 @@
 | Discovery | `docs/.scratch/<feature>/discovery/<feature>-discovery.md` | 可选 |
 | 原型阶段合同 / Product Design 路由 | `yss-prototype-stage -> product-design:index -> <focused skill>` | 必需；记录 `$get-context`、`$ideate`、`$prototype`、`$image-to-code` 或 `$url-to-code` |
 | 原型 / 线框图 | `<链接或导出图片路径>` | Excalidraw / Figma / Penpot / tldraw / Axure / Markdown |
-| 高保真 HTML 原型 | `docs/.scratch/<feature>/design/prototypes/index.html` | 低保真原型评审通过后补齐；主题/视觉标准必须为 Ant Design v6，标准 React 组件锁定 antd@6，生产映射为 YSS UI + Ant Design Vue 4.x；产出后必须获得用户确认 |
-| 原型验证清单 | `docs/.scratch/<feature>/verification/prototype-evidence.yaml` | 记录实际 CLI / AntD 版本、CLI JSON 输出、浏览器验证和阻塞项 |
+| 原型交付物 | `docs/.scratch/<feature>/design/prototypes/index.html` 或稳定 URL | 低保真评审后按 H1/H2 档位补齐；H2 AntD 条件取事实；真实组件待验事项交接到前端实现计划，产出后必须获得用户确认 |
+| 原型验证清单 | `docs/.scratch/<feature>/verification/prototype-evidence.yaml` | 记录 schema v3 档位、浏览器、统一 Design QA、条件组件证据和阻塞项 |
 | 现有 API 草案 | `docs/.scratch/<feature>/api/<feature>.yaml` | 可选；通常应先完成产品设计和 Spec 校准 |
 
 ## 2. 页面地图
@@ -105,8 +105,8 @@
 - loading、empty、error、no-permission、readonly、conflict、dirty-form 状态已展示，或明确不适用。
 - 每个表格列、筛选条件、表单字段、抽屉、弹窗和按钮都有数据来源或契约反推说明。
 - 设计可以拆成独立可演示的垂直切片。
-- 低保真原型评审通过后，高保真 HTML 原型使用 Ant Design v6 主题/视觉标准覆盖主流程、关键状态和响应式断点，并记录到生产 YSS UI/Ant Design Vue 4.x 的语义映射。
-- 原型产出前已使用 `antd` CLI 查询设计语言、组件 API、demo、token 和 semantic 信息；原型产出后已在 `prototype-evidence.yaml` 记录实际版本、CLI 与浏览器验证证据。
+- 低保真评审通过后，记录档位触发与待确认决定；H1 覆盖视觉和少量交互，H2 覆盖主流程/关键异常。
+- H2 只有实际使用 React AntD 且 fact pack 不新鲜时才执行增量 CLI 查询；H1 不创建 AntD 证据。任何原型档位都不得调用 `yss-ui` 或声明已验证真实生产组件。
 
 ## 9. 决策与未决问题
 

package/template/docs/design/templates/prototype-confirmation-template.md

@@ -1,6 +1,6 @@
-# <功能名称> 高保真原型确认记录
+# <功能名称> 原型交付物确认记录
 
-> 适用时机：Ant Design v6 主题/视觉标准高保真 HTML 原型产出后、Spec 校准 / 需求冻结 / UI 驱动 OpenAPI Draft 前。生产 API 仍为 YSS UI + Ant Design Vue 4.x；未确认前不得进入下游门禁。
+> 适用时机：H1/H2 原型交付物验证后、Spec 校准 / 需求冻结 / UI 驱动 OpenAPI Draft 前。用户只确认设计决定、可操作范围与模拟/gap；未确认前不得进入下游门禁。
 
 ## 1. 原型信息
 
@@ -12,24 +12,22 @@
 | 交互说明 | `docs/.scratch/<feature>/design/<feature>-interaction-spec.md` |
 | 状态矩阵 | `docs/.scratch/<feature>/design/<feature>-state-matrix.md` |
 | 原型评审 | `docs/.scratch/<feature>/design/<feature>-prototype-review.md` |
-| 高保真 HTML 原型 | `docs/.scratch/<feature>/design/prototypes/index.html` |
+| 原型档位与交付物 | `<H1/H2>`；`docs/.scratch/<feature>/design/prototypes/index.html` 或稳定 URL |
 | 机器可读验证清单 | `docs/.scratch/<feature>/verification/prototype-evidence.yaml` |
-| Product Design 路由 | `product-design:index -> <focused skill>` |
+| 原型路由 | `yss-prototype-stage -> H1/H2 -> <adapter>` |
 | 产出方式 | 系统 / Agent 自动产出 / 人工补充 |
-| Ant Design 目标版本 | `<实际项目选择的 v6 版本>` |
 
-## 2. AntD CLI 校验证据
+## 2. 用户需要确认的范围
 
-| 校验项 | 命令 / 记录路径 | 结论 |
+| 项目 | 内容 |
 |---|---|---|
-| 设计语言 | `antd design.md --format json` |  |
-| 组件 API | `antd info <Component> --version <target_antd_version> --format json` |  |
-| 组件 demo | `antd demo <Component> <demo> --version <target_antd_version> --format json` |  |
-| 组件 token | `antd token <Component> --version <target_antd_version> --format json` |  |
-| semantic | `antd semantic <Component> --version <target_antd_version> --format json` |  |
-| lint / 替代校验 | `antd lint <prototype path> --format json` |  |
-
-CLI 实际版本、目标 AntD 版本、完整 JSON 输出与浏览器验证结论以 `prototype-evidence.yaml` 为准；不得用本文中的示例版本替代实际记录。
+| 本原型确认的决定 |  |
+| 可操作范围 |  |
+| 模拟数据 / 模拟行为 |  |
+| 未关闭 gap |  |
+| 接受的差异或非目标 |  |
+
+技术栈、CLI、lockfile、digest 和扫描结果由 `prototype-evidence.yaml` 自动或工程验证记录，不要求用户确认。
 
 ## 3. 用户确认
 

package/template/docs/design/templates/prototype-evidence-template.yaml

@@ -1,99 +1,123 @@
 # 复制到 docs/.scratch/<feature>/verification/prototype-evidence.yaml。
-# schema v1 只读兼容；关闭 gate.prototype-verified 前必须迁移到本 schema v2。
-schema_version: 2
+# 只保留所选档位的 profile_evidence 子块；schema v1/v2 仅允许只读迁移。
+schema_version: 3
 feature: <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: pending
-  actual_antd_version: <exact-6.x-version-from-lockfile>
+prototype_profile: H2
+profile_kind: flow-review
+profile_decision:
+  decision_to_inform: <本轮原型需要支持的决定>
+  risk_assumptions:
+    - <需要验证或接受的风险假设>
+  trigger_results:
+    - trigger: <multi-page-navigation-or-other-trigger>
+      matched: true
+      evidence_ref: <spec-state-matrix-or-review-ref>
+  calculated_profile: H2
+  override:
+    applied: false
+    direction: none
+    reason: not-applicable
+    evidence_ref: not-applicable
+upstream_refs:
+  spec_ref: docs/.scratch/<feature>/spec/<feature>-spec.md
+  interaction_spec_ref: docs/.scratch/<feature>/design/<feature>-interaction-spec.md
+  low_fidelity_ref: docs/.scratch/<feature>/design/<feature>-low-fidelity.md
+  state_matrix_ref: docs/.scratch/<feature>/design/<feature>-state-matrix.md
+  prototype_review_ref: docs/.scratch/<feature>/design/<feature>-prototype-review.md
+source_visual:
+  ideation_status: required
+  selected_ref: <selected-source-visual-ref>
+  reuse_reason: not-applicable
 design_baseline:
-  design_standard: ant-design-v6
   project_design_ref: docs/design/design.md
   project_token_refs:
     - docs/design/tokens/theme.json
     - docs/design/tokens/tokens.compact.json
-  upstream_design_md_source: https://ant.design/design.md
-  upstream_design_md_record_ref: <path-to-json-output-or-summary>
-  theme_adapter_ref: docs/.scratch/<feature>/design/prototypes/src/yss-theme.js
+  project_token_baseline_digest: <sha256>
   project_override_reviewed: false
-  theme_override:
-    color_primary: "#3371ff"
-    color_error: "#f5222d"
-    color_bg_layout: "#f0f2f5"
-    compact_control_height: 28
-    border_radius: 6
-    font_family: system-stack
-    recorded: false
-    note: 官方当前同样使用系统字体和 6px 默认控件圆角；真实项目差异主要是品牌/状态色、页面背景和默认紧凑密度，不得误写为 Inter/8px 差异。
-visual_semantic_mapping:
-  runtime_component_library: ant-design-vue-4.x
-  runtime_version_source: implementation-lockfile
-  components:
-    - semantic_role: <primary-action-or-other-role>
-      antd_v6_component: <React-AntD-component-used-by-prototype>
-      project_token_refs: [<token-name>]
-      yss_or_antdv_target: <YSS-or-AntDV-production-component>
-      state_mapping: [default, hover, active, disabled, loading]
-      react_only_api_not_copied: false
-      verification_ref: <same-state-screenshot-or-test-ref>
-antd:
-  fact_skill: yss-antd-design
-  cli_command: antd
-  cli_version: <actual-cli-version>
-  target_antd_version: <same-exact-6.x-version>
-  queries:
-    design_md: <path-to-json-output>
-    components:
-      - component: <Component>
-        info_ref: <path-to-json-output>
-        demo_ref: <path-to-json-output>
-        token_ref: <path-to-json-output>
-        semantic_ref: <path-to-json-output>
-  lint_applicable: true
-  lint_reason: react-source
-  lint_ref: <path-to-json-output>
-  lint_passed: false
-browser_verification:
-  executor: <browser-or-automation-name>
+browser_delivery:
+  delivery_kind: static-directory
+  entry_ref: docs/.scratch/<feature>/design/prototypes/index.html
   rendered_nonblank: false
-  prototype_digest: <sha256-or-version-ref>
+  prototype_digest: <sha256>
   viewports:
     - name: desktop
       size: 1440x900
       result: pending
-    - name: narrow-mobile
+      screenshot_ref: <path>
+    - name: narrow
       size: 390x844
       result: pending
-  main_flow_result: pending
-  failure_permission_or_conflict_result: pending
-  console_error_ref: <path-to-console-output-or-none>
+      screenshot_ref: <path>
+  console_result: pending
+  console_ref: <path-to-console-output-or-none>
 design_qa:
   report_ref: docs/.scratch/<feature>/verification/design-qa.md
   result: pending
-accessibility_verification:
-  contrast_results_ref: <path-to-default-hover-active-disabled-focus-results>
-  keyboard_navigation_result: pending
-  focus_visible_and_order_result: pending
-  semantic_label_dialog_result: pending
-  zoom_200_result: pending
-  reduced_motion_result: pending
-  target_size_result: pending
-  automated_scan:
-    tool: <tool-or-manual>
-    version: <actual-version-or-not-applicable>
-    result: pending
-    ref: <path-to-result-or-manual-check>
+  axes:
+    visual: pending
+    layout: pending
+    interaction: pending
+    content: pending
+    accessibility: pending
+    cross_platform: pending
+profile_evidence:
+  # H1 只保留 visual_review；不得包含 package/lockfile/AntD 字段。
+  # visual_review:
+  #   runtime_build_required: false
+  #   key_interactions_result: pending
+  #   keyboard_result: pending
+  #   focus_result: pending
+  #   contrast_result: pending
+  #   zoom_200: {applicable: false, result: not-applicable, evidence_ref: not-applicable}
+  #   reduced_motion: {applicable: false, result: not-applicable, evidence_ref: not-applicable}
+  flow_review:
+    implementation:
+      framework: react
+      runtime_build_required: true
+      package_manager: pnpm
+      package_manifest_ref: docs/.scratch/<feature>/design/prototypes/package.json
+      lockfile_ref: docs/.scratch/<feature>/design/prototypes/pnpm-lock.yaml
+      build_command: pnpm build
+      build_result: pending
+    main_flow_result: pending
+    exceptional_state_result: pending
+    exceptional_state_ref: <failure-permission-or-conflict-ref>
+    keyboard_result: pending
+    focus_result: pending
+    contrast_result: pending
+    zoom_200_result: pending
+    reduced_motion_result: pending
+    visual_regression:
+      applicable: true
+      result: pending
+      evidence_ref: <snapshot-result-ref>
+    prototype_library_facts:
+      applicable: true
+      component_basis: react-antd-6
+      source: fact-pack
+      actual_antd_version: <exact-6.x-version-from-lockfile>
+      manifest_ref: docs/design/facts/antd/<exact-version>/manifest.json
+      manifest_digest: <sha256>
+      components_covered: [<Component>]
+      project_token_baseline_digest: <same-as-design-baseline>
+      new_api_uncertainty: false
+implementation_handoff:
+  prototype_code_reusable: false
+  production_component_assumptions:
+    - <原型采用的语义预计可由目标 YSS/AntDV 组件表达>
+  verification_targets:
+    - behavior: <进入实现后需要基于真实组件验证的行为>
+      target_stage: frontend-implementation-plan
 review:
-  prototype_review_ref: docs/.scratch/<feature>/design/<feature>-prototype-review.md
   result: pending
+  review_ref: docs/.scratch/<feature>/design/<feature>-prototype-review.md
 user_confirmation:
-  confirmation_ref: docs/.scratch/<feature>/design/<feature>-prototype-confirmation.md
   result: pending
+  confirmation_ref: docs/.scratch/<feature>/design/<feature>-prototype-confirmation.md
+  confirmed_decision: <用户确认的设计决定>
+  operable_scope: [<可操作范围>]
+  simulations_or_gaps: [<模拟或缺口>]
+gaps: []
 blockers: []

package/template/docs/design/templates/prototype-review-checklist.md

@@ -1,6 +1,6 @@
 # <功能名称> 原型评审清单
 
-> 适用时机：配合 `prototype-review` 使用。评审采用 记录阻塞原因：有阻断项时必须回到产品设计阶段；产品原型产出以 `product-design:index` 路由到 Product Design focused skill 为主；低保真评审通过后必须产出高保真 HTML 原型，可由系统 / Agent 自动产出；产出后必须获得用户确认，确认前不能直接进入 Spec 校准或 API 影响分析 / 契约草案。
+> 适用时机：配合 `prototype-review` 使用。低保真与状态矩阵有阻断项时回产品设计；通过后先提取风险，再按确定性规则选择 H1/H2 原型交付物。产出后仍须用户确认，确认前不能进入 Spec 校准或 API 影响分析。
 
 ## 评审输入
 
@@ -11,7 +11,7 @@
 | 原型 / 线框图 | `<链接或导出图片路径>` |  |
 | 状态矩阵 | `docs/.scratch/<feature>/design/<feature>-state-matrix.md` |  |
 | 原型阶段合同 / Product Design 路由记录 | `yss-prototype-stage -> product-design:index -> <focused skill>` |  |
-| 原型验证清单 | `docs/.scratch/<feature>/verification/prototype-evidence.yaml` | 高保真完成后补齐 CLI 与浏览器验证 |
+| 原型验证清单 | `docs/.scratch/<feature>/verification/prototype-evidence.yaml` | 档位确定后补齐 schema v3 共同与档位证据 |
 | 现有 API 草案 | `docs/.scratch/<feature>/api/<feature>.yaml` | 可选 |
 
 ## 门禁清单
@@ -26,7 +26,8 @@
 | 权限行为能区分隐藏、禁用和调用后拒绝 |  |  |
 | 校验错误能区分模型级和字段级展示位置 |  |  |
 | 能从界面需求反推出 API 影响和契约草案 |  |  |
-| 高保真 HTML 原型已按 `yss-prototype-stage` 通过 `product-design:index` 路由产出，或记录等价 Agent 适配及例外原因 |  |  |
+| 已列出原型需要回答的决定、风险触发及 H1/H2 推荐档位；无充分证据时回退 H2 |  |  |
+| 状态矩阵中的每个状态均有事件、转换、guard、动作和退出路径 |  |  |
 | 前端验收、组件状态和数据依赖已明确 |  |  |
 | 风险 / 回滚约束和人工确认项已记录 |  |  |
 
@@ -63,5 +64,5 @@
 非阻断建议：
 - 
 下一步：
-- product-design:index 路由高保真 HTML 原型产出 / 回到 Product Design focused skill 补齐原型 / 进入用户确认
+- yss-prototype-stage 计算档位并进入对应适配器 / 回到产品设计补齐状态与风险 / 进入原型交付物构建
 ```

package/template/docs/design/templates/state-matrix-template.md

@@ -2,6 +2,8 @@
 
 > 适用时机：配合 `product-design:index` 路由后的 Product Design focused skill 使用，在 Spec 校准和 API 影响分析 / 契约草案之前补齐页面状态。
 
+状态矩阵同时承担轻量状态机合同：每个可进入状态都必须有触发事件、允许转换、guard、动作与退出路径。不要另建第二份 state-machine 资产。
+
 | 页面 / 组件 | 状态 | 触发条件 | 界面行为 | API / 数据要求 | 验收点 |
 |---|---|---|---|---|---|
 | 模型列表 | 加载中 | 首次进入或筛选条件变化 | 表格展示加载态；查询条件尽量保持可用 | 列表请求进行中 | 用户看到进度且布局不跳动 |
@@ -16,6 +18,15 @@
 | 发布弹窗 | 并发冲突 | 页面加载后草稿已被他人修改 | 展示刷新或重试决策 | 冲突错误码、最新版本或 token | 不会误覆盖他人修改 |
 | 发布弹窗 | 发布成功 | 发布接口成功 | 关闭弹窗，展示已发布状态和版本号 | 发布版本元数据 | 详情页反映冻结版本 |
 
+## 状态转换合同
+
+| 状态 | 事件 | Guard | 下一状态 | 进入 / 退出动作 | 恢复或退出路径 |
+|---|---|---|---|---|---|
+| 加载中 | 请求成功 | 响应有效 | 可操作 | 渲染数据、解除 busy | 进入主流程 |
+| 加载中 | 请求失败 | 错误可重试 | 错误 | 保留上下文、展示错误 | 重试或返回 |
+| 表单已修改 | 提交 | 校验通过且有权限 | 提交中 | 禁用重复提交 | 成功、失败或冲突 |
+| 并发冲突 | 刷新 | 用户确认放弃本地旧版本 | 可操作 | 拉取最新版本 | 重新编辑或退出 |
+
 ## 必须确认的状态决策
 
 | 决策项 | 选择的行为 | 负责人 |

package/template/docs/discovery/reports/agent-governance-options.md

@@ -3,7 +3,7 @@
 ## 结论摘要
 
 1. 逐技能结构 / 路由 / 行为 eval 不作为 YSS 模板首个升级方向。结构和路由已有确定性校验；行为 eval 成本高、易重复生命周期门禁，应降为后续按变更和风险触发的试验性能力。
-2. invocation metadata 进入 `yss-skill-registry.yaml`；Router 合同只定义字段 schema、解析和阻断规则，不复制每个 skill 的示例。trigger examples 进入注册表，但保持少量、结构化、只为消歧服务。
+2. invocation metadata 进入 `yss-skill-registry.yaml`；实现合同编译器 合同只定义字段 schema、解析和阻断规则，不复制每个 skill 的示例。trigger examples 进入注册表，但保持少量、结构化、只为消歧服务。
 3. freshness audit 作为生命周期完成条件的 core 能力，不新建一个常驻通用 skill；Doubt-Driven 作为高风险条件触发的 core 路由策略；Wayfinder 保持 maintainer-only / 兼容入口的可选模式，不进入默认 core 路由。
 
 ## Q1：eval 是否为首个升级方向
@@ -11,7 +11,7 @@
 ### 现状事实
 
 - 技能身份、层级、成熟度、别名、默认可发现性和来源投影已经由 [`yss-skill-registry.yaml`](../../agents/yss-skill-registry.yaml)、[`skill-registry.mjs`](../../../scripts/lib/skill-registry.mjs)、`sync-skills` 和 `skills-lock.json` 共同校验。
-- 生命周期路由和 Router 已经对未登记技能、依赖闭包、原型独立评审、代码审查唯一入口等关键路由做确定性检查。
+- 生命周期路由和 实现合同编译器 已经对未登记技能、依赖闭包、原型独立评审、代码审查唯一入口等关键路由做确定性检查。
 - 生命周期完成已经要求 fresh verification、证据可读、阻断信号清空和 stale / drift 重路由。
 
 ### 决策
@@ -21,7 +21,7 @@
 | 层次 | 初始策略 | 原因 |
 |---|---|---|
 | 结构 | 继续使用现有静态 / schema 校验 | 成本最低，收益已覆盖大部分缺陷 |
-| 路由 | 只对注册表、Router、生命周期变更做确定性增量校验 | 与现有门禁直接对齐，避免重复运行 |
+| 路由 | 只对注册表、实现合同编译器、生命周期变更做确定性增量校验 | 与现有门禁直接对齐，避免重复运行 |
 | 行为 | P2 试验；只覆盖变更中的 core / 高风险 skill | 避免全量运行导致 token 和维护成本失控 |
 
 行为 eval 的进入条件应是：skill 内容或路由发生变化、命中高风险影响、或出现真实 finding；退出条件是连续真实任务证明它能发现现有静态校验抓不到的问题，且没有形成第二套生命周期门禁。
@@ -31,7 +31,7 @@
 ### 决策
 
 - **注册表**是技能级调用元数据的唯一事实源：调用模式、触发条件、排除条件、主要输出、依赖和少量 trigger examples 均放在这里。
-- **Router 合同**定义 schema、解析顺序、依赖闭包和阻断规则；不复制每个技能的完整示例，避免注册表与 Router 漂移。
+- **实现合同编译器 合同**定义 schema、解析顺序、依赖闭包和阻断规则；不复制每个技能的完整示例，避免注册表与 实现合同编译器 漂移。
 - **生命周期编排合同**继续保留工作单元级 `workflow_reference.invocation_mode`（例如 `model-invoked` / `reference`）。它描述一次工作单元如何被执行，不与注册表的 `user` / `model` / `both` 技能级模式混用。
 
 ### trigger examples 约束
@@ -41,14 +41,14 @@
 - specialist 技能可继承 `impacts` 触发条件；只有存在歧义时才增加显式 examples。
 - examples 只影响发现和路由提示，不直接批准门禁、Ticket 状态或 `ready-for-agent`。
 
-当前已落地的低成本基础见 [`yss-skill-registry.yaml`](../../agents/yss-skill-registry.yaml) 的 `invocation_contract`，以及 [`router-contract.yaml`](../../.agents/skills/yss-router/references/router-contract.yaml) 的合同字段。
+当前已落地的低成本基础见 [`yss-skill-registry.yaml`](../../agents/yss-skill-registry.yaml) 的 `invocation_contract`，以及 [`compiler-contract.yaml`](../../.agents/skills/yss-implementation-contract-compiler/references/compiler-contract.yaml) 的合同字段。
 
 ## Q3：三项能力的路由层级
 
 | 能力 | 推荐层级 | 具体落点 | 不应做什么 |
 |---|---|---|---|
 | freshness audit | core 能力 | 生命周期完成条件、候选快照、fresh verification、stale / drift 检查 | 不再新增一个对所有任务常驻的通用审计 skill |
-| Doubt-Driven | core 条件路由 | Router / 工程基线 / 架构与契约审查中的高风险分支 | 不升级为所有低风险任务的默认步骤，不新建生命周期阶段 |
+| Doubt-Driven | core 条件路由 | 实现合同编译器 / 工程基线 / 架构与契约审查中的高风险分支 | 不升级为所有低风险任务的默认步骤，不新建生命周期阶段 |
 | Wayfinder | maintainer-only / 兼容入口的可选模式 | 超长、多 Agent、多会话或 frontier 不清晰时，完成后回 `handoff → to-spec` | 不改变阶段、门禁、Ticket 角色或 `ready-for-agent` |
 
 ### Doubt-Driven 的高风险触发器
@@ -63,8 +63,8 @@ freshness 是“完成结论可信度”的 core 约束，而不是新的工作
 
 - [YSS skill registry](../../agents/yss-skill-registry.yaml)
 - [Skill registry validator](../../../scripts/lib/skill-registry.mjs)
-- [YSS Router contract](../../.agents/skills/yss-router/references/router-contract.yaml)
-- [Slice Implementation Contract](../../.agents/skills/yss-router/references/slice-implementation-contract.md)
+- [YSS 实现合同编译器 contract](../../.agents/skills/yss-implementation-contract-compiler/references/compiler-contract.yaml)
+- [Slice Implementation Contract](../../.agents/skills/yss-implementation-contract-compiler/references/slice-implementation-contract.md)
 - [Lifecycle orchestration contract](../../.agents/skills/yss-product-lifecycle/references/orchestration-contract.yaml)
 - [Harness process tailoring](../../process/harness-process-tailoring.md)
 - [Addy Osmani agent-skills](https://github.com/addyosmani/agent-skills)

package/template/docs/process/MATT-POCOCK-ENGINEERING-SKILLS.md

@@ -5,7 +5,7 @@ Matt Pocock Engineering Skills 提供轻量的澄清、实现、TDD、诊断和
 ## 进入与退出
 
 - Matt user-invoked 的 `grill-with-docs`、`to-spec`、`to-tickets` 和 `implement` 必须由用户显式启动，任何 skill 不得自动调用它们；YSS 生命周期只准备、校验和验收其结果。所有 Matt model-invoked skill 仍须遵守 `AGENTS.md` 的阶段、门禁和证据要求，并只能在生命周期允许的工作单元中调用。
-- `code-review` 保持唯一默认审查入口。YSS 适配把 Slice `required_skills`、`alibaba-java-code-style` 与命中的 `yss-ui` / `yss-domain` 等专项 skill 编译为 Standards 检查输入，并要求实现仓已有的 `pnpm` / `./mvnw` 机器检查；禁止再增加第二个通用审查 skill 或专用审查 Cloud 环境来代替这条接线。审查 finding 按编排合同分流：实现者修复后全轴复审，或合同 `stale` 后回 Router；审查者不得写实现。
+- `code-review` 保持唯一默认审查入口。YSS 适配把 Slice `required_skills`、`alibaba-java-code-style` 与命中的 `yss-ui` / `yss-domain` 等专项 skill 编译为 Standards 检查输入，并要求实现仓已有的 `pnpm` / `./mvnw` 机器检查；禁止再增加第二个通用审查 skill 或专用审查 Cloud 环境来代替这条接线。审查 finding 按编排合同分流：实现者修复后全轴复审，或合同 `stale` 后回 实现合同编译器；审查者不得写实现。
 - `template-source` 只执行模板维护流程，不生成具体产品 Spec、原型、OpenAPI 或垂直切片 Ticket。
 - Matt 的 `research` 已适配为 canonical `yss-research`，旧名只作为 deprecated alias。YSS 版本提供 `technical-evidence` / `strategy-evidence` profile、`quick` / `evidence-audited` 模式、证据合同和确定性校验，同时保留上游 revision 与原始 hash 以便追溯。
 - Agent 完成工作单元后返回可核验的 evidence refs、变更资产、验证命令、残余风险和下一路由。

package/template/docs/process/implementation-repo-integration.md

@@ -40,7 +40,7 @@ apps/
 - 后端：已登记项目根的 `./mvnw` 校验 / 测试；若工程已配置 Checkstyle、P3C 或 Spotless，审查时实际执行。
 - `git-submodule` 必须递归检出；空 gitlink 不得当作「没有工程」。
 - 模板源 `.cursor/environment.json` 只安装模板校验依赖（`jsonschema`、模板 `pnpm`），**不是**实现仓审查运行时。`project-instance` 与实现仓库的 Cloud / CI 环境自行包含 JDK、Maven Wrapper 和 `pnpm`。
-- 审查任务包只写证据路径；专项 skill 只读，不得写实现。审查 finding 按 `review_standards_route.finding_disposition` 分流：`violation` 交实现者修复后全轴复审；`drift` / `new_impacts` 回 Router，不在审查会话中改代码。
+- 审查任务包只写证据路径；专项 skill 只读，不得写实现。审查 finding 按 `review_standards_route.finding_disposition` 分流：`violation` 交实现者修复后全轴复审；`drift` / `new_impacts` 回 实现合同编译器，不在审查会话中改代码。
 
 ## 1.3 `repository_scope: git-submodule`
 

package/template/docs/process/lifecycle-artifact-map.md

@@ -31,7 +31,7 @@
 | `gate.stage-decision-package-approved` | 阶段决策包批准 | `stage.discovery` | Discovery 到 Spec 入口需要稳定的阶段决策合同。 | `gate.domain-strategy-approved` | `evidence.stage-decision-package`、`evidence.approval-record` |
 | `gate.spec-baseline-approved` | Spec 基线批准 | `stage.spec-architecture` | 新功能、行为变化或范围扩大进入 Spec 基线。 | 无 | `evidence.approval-record` |
 | `gate.prototype-reviewed` | 原型评审 | `stage.product-design` | 命中产品设计影响，且低保真页面、流程、状态或 API 反推需要独立评审。 | 无 | `evidence.prototype-review-result` |
-| `gate.prototype-verified` | 高保真原型验证 | `stage.product-design` | 需要高保真 HTML 原型进行视觉与交互校准。 | 无 | `evidence.antd-cli-validation`、`evidence.browser-prototype-verification` |
+| `gate.prototype-verified` | 原型交付物验证 | `stage.product-design` | 产品设计影响需要通过 H1/H2 原型交付物进行视觉或流程校准；真实组件验证留到前端实现阶段。 | 无 | `evidence.prototype-profile-decision`、`evidence.prototype-deliverable-verification` |
 | `gate.user-confirmation` | 用户确认 | `stage.product-design` | 产品设计影响尚未被人工确认。 | 无 | `evidence.prototype-confirmation` |
 | `gate.openapi-draft-reviewed` | OpenAPI Draft Review | `stage.system-data-engineering` | 有 API 影响且 Draft 已生成。 | 无 | `evidence.openapi-draft-review` |
 | `gate.design-reviewed` | 设计审查 | `stage.system-data-engineering` | API 或架构影响。 | 无 | `evidence.design-review-result` |
@@ -57,7 +57,7 @@
 | `artifact.interaction-spec` | 交互说明 | `stage.product-design` | 命中产品设计影响。 |
 | `artifact.low-fidelity-prototype` | 低保真原型 | `stage.product-design` | 命中产品设计影响。 |
 | `artifact.state-matrix` | 状态矩阵 | `stage.product-design` | 存在状态流转、异常或恢复。 |
-| `artifact.high-fidelity-html-prototype` | 高保真 HTML 原型 | `stage.product-design` | 需要视觉与交互校准。 |
+| `artifact.prototype-deliverable` | 原型交付物 | `stage.product-design` | 低保真评审后需要 H1 视觉或 H2 流程校准。 |
 | `artifact.prototype-review` | 原型评审记录 | `stage.product-design` | 命中 gate.prototype-reviewed。 |
 | `artifact.prototype-confirmation` | 原型确认记录 | `stage.product-design` | 命中 gate.user-confirmation。 |
 | `artifact.openapi-draft` | OpenAPI Draft | `stage.system-data-engineering` | 有 API 影响。 |
@@ -89,6 +89,8 @@
 | `evidence.prototype-review-result` | 原型评审结果 | 低保真页面、流程、状态与 API 反推的独立评审结论和阻断项。 |
 | `evidence.antd-cli-validation` | Ant Design CLI 校验证据 | 设计语言、组件、demo、token、semantic 与 lint 的实际 CLI/目标版本和可读输出引用。 |
 | `evidence.browser-prototype-verification` | 浏览器原型验证证据 | 高保真原型的非空渲染、主流程、异常状态、视口和控制台验证记录。 |
+| `evidence.prototype-profile-decision` | 原型档位选择证据 | 基于低保真评审后的风险触发、决定目标、H1/H2 计算结果以及人工升降级依据。 |
+| `evidence.prototype-deliverable-verification` | 原型交付物验证证据 | schema v3 共同证据与所选档位的浏览器、Design QA、无障碍、组件事实或真实组件合同验证结果。 |
 | `evidence.prototype-confirmation` | 原型用户确认记录 | 高保真原型、验证清单和进入下游阶段范围的人工确认结论。 |
 | `evidence.openapi-draft-review` | OpenAPI Draft 审查记录 | P0、错误、分页、幂等和契约测试审查记录。 |
 | `evidence.contract-approval` | Slice 合同批准记录 | 生命周期编排器批准且已持久化的当前版本合同引用。 |

package/template/docs/process/lifecycle-registry-baseline.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "registry_id": "yss.lifecycle",
-  "semantic_sha256": "15375e8d7da599e2117e19399cb5e14b9c53aa4e4ce7c94c4e9c135a499e55e6",
+  "semantic_sha256": "6fe3accf810dda1686080f1dd32f9393b22fa006acceb89ff17cb5668a8a67a6",
   "published_ids": [
     "artifact.architecture-review",
     "artifact.data-architecture",
@@ -19,6 +19,7 @@
     "artifact.openapi-freeze-record",
     "artifact.parent-ticket",
     "artifact.product-overview",
+    "artifact.prototype-deliverable",
     "artifact.prototype-confirmation",
     "artifact.prototype-review",
     "artifact.retrospective",
@@ -42,6 +43,8 @@
     "evidence.maintenance-intensity-checkpoint",
     "evidence.openapi-draft-review",
     "evidence.prototype-confirmation",
+    "evidence.prototype-deliverable-verification",
+    "evidence.prototype-profile-decision",
     "evidence.prototype-review-result",
     "evidence.repository-identity-check",
     "evidence.stage-decision-package",