create-yss-spec 2.2.8 → 2.2.10

package/template/DESIGN.md

@@ -0,0 +1,203 @@
+---
+version: alpha
+name: YSS Enterprise Design System
+description: A machine-readable visual design contract for YSS enterprise applications. It complements the product lifecycle and does not define product behavior, API contracts, permissions, or business states.
+
+colors:
+  primary: "#3371ff"
+  primary-hover: "#5c8dff"
+  primary-active: "#245bdb"
+  on-primary: "#000000"
+  text: "rgba(0, 0, 0, 0.88)"
+  text-secondary: "rgba(0, 0, 0, 0.65)"
+  text-tertiary: "rgba(0, 0, 0, 0.45)"
+  canvas-layout: "#f0f2f5"
+  surface: "#ffffff"
+  surface-subtle: "#fafafa"
+  border-secondary: "#f0f0f0"
+  success: "#52c41a"
+  warning: "#faad14"
+  error: "#f5222d"
+  selected: "#e6f4ff"
+
+typography:
+  body:
+    fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "Noto Sans", sans-serif'
+    fontSize: 14px
+    fontWeight: 400
+    lineHeight: 1.571
+  body-strong:
+    fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "Noto Sans", sans-serif'
+    fontSize: 14px
+    fontWeight: 600
+    lineHeight: 1.571
+  heading-lg:
+    fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "Noto Sans", sans-serif'
+    fontSize: 24px
+    fontWeight: 600
+    lineHeight: 1.333
+  heading-md:
+    fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "Noto Sans", sans-serif'
+    fontSize: 18px
+    fontWeight: 600
+    lineHeight: 1.333
+  caption:
+    fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "Noto Sans", sans-serif'
+    fontSize: 12px
+    fontWeight: 400
+    lineHeight: 1.571
+  button:
+    fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "Noto Sans", sans-serif'
+    fontSize: 14px
+    fontWeight: 600
+    lineHeight: 1.571
+
+rounded:
+  none: 0px
+  sm: 4px
+  md: 6px
+  lg: 8px
+  pill: 9999px
+
+spacing:
+  xxs: 4px
+  xs: 8px
+  sm: 12px
+  md: 16px
+  lg: 24px
+  xl: 32px
+  xxl: 48px
+
+components:
+  button-primary:
+    backgroundColor: "{colors.primary}"
+    textColor: "{colors.on-primary}"
+    typography: "{typography.button}"
+    rounded: "{rounded.md}"
+    padding: "{spacing.xs} {spacing.md}"
+    height: 32px
+  button-primary-hover:
+    backgroundColor: "{colors.primary-hover}"
+    textColor: "{colors.on-primary}"
+    typography: "{typography.button}"
+    rounded: "{rounded.md}"
+    padding: "{spacing.xs} {spacing.md}"
+    height: 32px
+  button-primary-disabled:
+    backgroundColor: "{colors.border-secondary}"
+    textColor: "{colors.text-tertiary}"
+    typography: "{typography.button}"
+    rounded: "{rounded.md}"
+    padding: "{spacing.xs} {spacing.md}"
+    height: 32px
+  button-default:
+    backgroundColor: "{colors.surface}"
+    textColor: "{colors.text}"
+    typography: "{typography.button}"
+    rounded: "{rounded.md}"
+    padding: "{spacing.xs} {spacing.md}"
+    height: 32px
+  input-default:
+    backgroundColor: "{colors.surface}"
+    textColor: "{colors.text}"
+    typography: "{typography.body}"
+    rounded: "{rounded.md}"
+    padding: "{spacing.xs} {spacing.sm}"
+    height: 32px
+  input-error:
+    backgroundColor: "{colors.surface}"
+    textColor: "{colors.text}"
+    typography: "{typography.body}"
+    rounded: "{rounded.md}"
+    padding: "{spacing.xs} {spacing.sm}"
+    height: 32px
+  table-header:
+    backgroundColor: "{colors.surface-subtle}"
+    textColor: "{colors.text}"
+    typography: "{typography.body-strong}"
+    padding: "{spacing.xs} {spacing.sm}"
+  table-row-selected:
+    backgroundColor: "{colors.selected}"
+    textColor: "{colors.text}"
+    typography: "{typography.body}"
+    padding: "{spacing.xs} {spacing.sm}"
+  modal-default:
+    backgroundColor: "{colors.surface}"
+    textColor: "{colors.text}"
+    typography: "{typography.body}"
+    rounded: "{rounded.lg}"
+    padding: "{spacing.md}"
+  button-primary-active:
+    backgroundColor: "{colors.primary-active}"
+    textColor: "#ffffff"
+    typography: "{typography.button}"
+    rounded: "{rounded.md}"
+    padding: "{spacing.xs} {spacing.md}"
+    height: 32px
+  page-shell:
+    backgroundColor: "{colors.canvas-layout}"
+    textColor: "{colors.text}"
+    typography: "{typography.body}"
+    padding: "{spacing.md}"
+  alert-success:
+    backgroundColor: "{colors.success}"
+    textColor: "#000000"
+    typography: "{typography.body}"
+    rounded: "{rounded.sm}"
+    padding: "{spacing.xs} {spacing.sm}"
+  alert-warning:
+    backgroundColor: "{colors.warning}"
+    textColor: "#000000"
+    typography: "{typography.body}"
+    rounded: "{rounded.sm}"
+    padding: "{spacing.xs} {spacing.sm}"
+  alert-error:
+    backgroundColor: "{colors.error}"
+    textColor: "#000000"
+    typography: "{typography.body}"
+    rounded: "{rounded.sm}"
+    padding: "{spacing.xs} {spacing.sm}"
+  secondary-copy:
+    textColor: "{colors.text-secondary}"
+    typography: "{typography.caption}"
+
+---
+
+# Overview
+
+YSS is an enterprise UI system for dense, scannable work surfaces: tables, forms, filters, workflows and operational feedback. This file is the normative source for visual tokens and component visual variants. Product behavior remains in Spec, interaction specifications and state matrices.
+
+The visual baseline is Ant Design semantic tokens mapped to YSS UI. Production applications use Vue 3 + YSS UI / Ant Design Vue 4.x; high-fidelity prototypes use React + Ant Design 6.x. Both tracks consume the same semantic intent.
+
+# Colors
+
+Use semantic roles (`primary`, `text`, `surface`, `border`, `success`, `warning`, `error`) instead of literal values in product pages. Keep a single primary action per decision area. State colors must be paired with readable text or an icon and must meet WCAG 2.2 AA.
+
+# Typography
+
+Use the system font stack, 14px body text and 400/600 weights. Use `caption` only for supporting information; do not encode business status through weight alone.
+
+# Layout
+
+Use a 4px spacing grid and the spacing tokens above. Default controls are 32px high. Page, container and overlay surfaces form the base three-layer model. On narrow screens, toolbars and filters reflow or collapse; table overflow is restricted to the table container.
+
+# Elevation & Depth
+
+Prefer surface and border changes over decorative shadows. Use the component library elevation tokens when available. Shadow values remain an implementation detail until the upstream DESIGN.md schema provides a stable structured elevation contract.
+
+# Shapes
+
+Controls use `rounded.md` (6px); cards and overlays use `rounded.lg` (8px); compact tags may use `rounded.sm` or `rounded.pill`. A container radius must not be smaller than the radius of its child controls.
+
+# Components
+
+The component keys above describe visual variants, not business states. Required implementation states include hover, focus, active, disabled, loading, error, empty, readonly, no-permission, conflict and success. Define those behavior and acceptance details in the lifecycle state-matrix and prototype evidence assets.
+
+# Do’s and Don’ts
+
+- Do consume tokens through ConfigProvider, CSS variables or the target component library theme.
+- Do verify desktop (`1440x900`), mobile (`390x844`) and impacted intermediate viewports.
+- Do provide visible feedback for save, submit, publish, export and retry actions.
+- Don’t use marketing hero layouts, large gradients or decorative cards in operational pages.
+- Don’t hard-code colors, arbitrary spacing or duplicate controls that already exist in YSS UI.
+- Don’t use a Tag as the only representation of an error, permission or approval state.

package/template/README.md

@@ -48,6 +48,8 @@
 
 YSS skills 的公开发布投影维护在 [iloveZzz/yss-spec-dev-skills](https://github.com/iloveZzz/yss-spec-dev-skills)，发布清单和导出命令见 [skills 维护说明](./docs/agents/skills-maintenance.md)。
 
+YSS UI 组件知识同时通过项目级 MCP 配置提供；支持的客户端、Codex 全局安装和自检方法见 [YSS UI MCP 接入](./docs/user-guide/yss-ui-mcp.md)。
+
 ## 模板初始化 CLI
 
 `create-yss-spec` 的目标维护位置是独立 GitHub 仓库 [iloveZzz/create-yss-spec](https://github.com/iloveZzz/create-yss-spec)。本仓库不再包含 CLI 源码、测试、发布配置或开发过程记录。CLI 的使用方法已经合并到统一用户手册：
@@ -113,6 +115,7 @@ scripts/verify-template-fast
 | [docs/process/implementation-repo-integration.md](./docs/process/implementation-repo-integration.md) | 外部前端 / 后端实现仓库接入与跨仓库切片绑定 |
 | [docs/agents/README.md](./docs/agents/README.md) | Agent 协作文档目录说明 |
 | [docs/agents/skills-maintenance.md](./docs/agents/skills-maintenance.md) | Agent skills 安装与维护 |
+| [docs/user-guide/yss-ui-mcp.md](./docs/user-guide/yss-ui-mcp.md) | YSS UI MCP 项目配置、全局安装边界与自检 |
 | [docs/discovery/IDEATION.md](./docs/discovery/IDEATION.md) | 机会构想方法 |
 | [docs/architecture/README.md](./docs/architecture/README.md) | 架构设计 + 审查清单 |
 | [docs/testing/README.md](./docs/testing/README.md) | 测试策略 |

package/template/docs/agents/digital-human-roles.md

@@ -10,7 +10,7 @@
 
 | 轴 | 是什么 | 不是什么 |
 |---|---|---|
-| 数字人角色 | 职称配置（需求经理、前端工程师…） | Ticket 五态、某个平台的 Bot |
+| 数字人角色 | 职称配置（需求经理、产品经理、前端工程师…） | Ticket 五态、某个平台的 Bot |
 | 主控数字人 | 生命周期编排器的运行时实例 | 第八个业务职称 |
 | 职能工作单元 | Discovery / Spec / Code / Review | 职称 |
 | 执行态 | Explorer / Drafter / Worker / Reviewer / Verifier | 数字人角色 |

package/template/docs/agents/digital-human-roles.yaml

@@ -82,6 +82,7 @@ roles:
   - id: role.requirements-manager
     name: 需求经理
     kind: digital-human
+    contract_version: 1
     title: YSS 需求经理
     stages: [stage.discovery, stage.spec-architecture]
     draft_artifact_ids: [artifact.discovery-record, artifact.spec]
@@ -96,34 +97,26 @@ roles:
   - id: role.product-manager
     name: 产品经理
     kind: digital-human
+    contract_version: 1
     title: YSS 产品经理
     stages: [stage.discovery, stage.spec-architecture, stage.product-design, stage.verification-release-retrospective]
     draft_artifact_ids: [artifact.product-overview, artifact.functional-architecture, artifact.interaction-spec, artifact.state-matrix, artifact.prototype-confirmation]
-    core_skills: [yss-design-system, yss-prototype-stage, prototype-review, yss-antd-design]
+    core_skills: [yss-design-system, yss-prototype-stage, prototype-review, yss-antd-design, research, competitive-intelligence]
     forbidden_skills: [yss-ui, yss-domain, yss-repository, yss-web-controller, yss-ddd-scaffold-generator, implement, tdd]
     description: >-
-      Own priority, product-design impact, interaction, state matrix, and
-      prototype confirmation recommendation. May reject Spec scope. Do not write
-      production code or freeze OpenAPI alone. Frontend implementation uses the
-      frontend-engineer role and yss-ui, not yss-antd-design.
-
-  - id: role.business
-    name: 商务
-    kind: digital-human
-    title: YSS 商务
-    stages: [stage.discovery, stage.verification-release-retrospective]
-    draft_artifact_ids: [artifact.discovery-record]
-    core_skills: [competitive-intelligence, research]
-    forbidden_skills: [yss-ui, yss-domain, yss-web-controller, yss-openapi-governance, to-spec, to-tickets, implement, tdd, yss-router]
-    description: >-
-      Own commercial constraints, delivery promises, and business non-goals in
-      Discovery and release windows. Do not finalize Spec, API, tickets, or
-      code. External quotes and contracts stay behind runtime side-effect
-      approval by a biological human.
+      Own priority, product-design impact, interaction, state matrix, prototype
+      confirmation recommendation, and the commercial constraints, delivery
+      commitments, release window, and commercial non-goals for Discovery and
+      release. May reject Spec scope. Do not write production code or freeze
+      OpenAPI alone. Do not independently approve external commercial contracts
+      or formal commitments; those require biological-human approval. Frontend
+      implementation uses the frontend-engineer role and yss-ui, not
+      yss-antd-design.
 
   - id: role.project-manager
     name: 项目经理
     kind: digital-human
+    contract_version: 1
     title: YSS 项目经理
     stages: [stage.entry-triage, stage.discovery, stage.spec-architecture, stage.product-design, stage.system-data-engineering, stage.ticket-formalization, stage.vertical-slice-implementation, stage.verification-release-retrospective]
     draft_artifact_ids: [artifact.parent-ticket, artifact.vertical-slice-ticket]
@@ -140,10 +133,11 @@ roles:
   - id: role.frontend-engineer
     name: 前端工程师
     kind: digital-human
+    contract_version: 1
     title: YSS 前端工程师
     stages: [stage.product-design, stage.system-data-engineering, stage.ticket-formalization, stage.vertical-slice-implementation, stage.verification-release-retrospective]
     draft_artifact_ids: [artifact.frontend-implementation-plan]
-    core_skills: [yss-ui, yss-page-module-development, yss-components, yss-formily, formily-foundation, formily-linkage-effects, formily-mode-slot-detail, formily-step-flow, ytable-usage, ytree-usage, yedit-table-usage, yss-api-integration, yss-hook, theme-token-usage, page-skeleton, page-list-module, page-form-module, component-selection-imports, vue3-best-practices, tdd]
+    core_skills: [yss-ui, yss-ui-business-page-generation, yss-page-module-development, yss-components, yss-formily, formily-foundation, formily-linkage-effects, formily-mode-slot-detail, formily-step-flow, ytable-usage, ytree-usage, yedit-table-usage, yss-api-integration, yss-hook, theme-token-usage, page-skeleton, page-list-module, page-form-module, component-selection-imports, vue3-best-practices, tdd]
     forbidden_skills: [yss-domain, yss-application, yss-repository, yss-mybatis, yss-web-controller, yss-ddd-scaffold-generator, java-backend-commit]
     description: >-
       Own Vue page modules, frontend tests, and frontend_implementation_plan.
@@ -154,6 +148,7 @@ roles:
   - id: role.backend-engineer
     name: 后端工程师
     kind: digital-human
+    contract_version: 1
     title: YSS 后端工程师
     stages: [stage.system-data-engineering, stage.ticket-formalization, stage.vertical-slice-implementation, stage.verification-release-retrospective]
     draft_artifact_ids: [artifact.openapi-draft, artifact.data-architecture]
@@ -168,6 +163,7 @@ roles:
   - id: role.test-engineer
     name: 测试工程师
     kind: digital-human
+    contract_version: 1
     title: YSS 测试工程师
     stages: [stage.spec-architecture, stage.vertical-slice-implementation, stage.verification-release-retrospective]
     draft_artifact_ids: [artifact.frontend-implementation-verification]
@@ -186,7 +182,7 @@ stage_groups:
   - id: group.discovery
     name: Discovery
     stage: stage.discovery
-    members: [role.lifecycle-orchestrator, role.requirements-manager, role.product-manager, role.business]
+    members: [role.lifecycle-orchestrator, role.requirements-manager, role.product-manager]
   - id: group.spec
     name: Spec
     stage: stage.spec-architecture
@@ -210,7 +206,7 @@ stage_groups:
   - id: group.release
     name: 发布
     stage: stage.verification-release-retrospective
-    members: [role.lifecycle-orchestrator, role.project-manager, role.test-engineer, role.product-manager, role.business]
+    members: [role.lifecycle-orchestrator, role.project-manager, role.test-engineer, role.product-manager]
 
 gate_policy:
   default_if_unlisted: biological-human

package/template/docs/agents/skills-maintenance.md

@@ -18,6 +18,7 @@
 | `mattpocock/skills` | `0ab1b63a410a03d3627979a109c8695de27af954` / `skills/engineering` 及锁文件记录的关联路径 | 通用工程流程及关联 skills |
 | `anthropics/knowledge-work-plugins` | `sales/skills/competitive-intelligence` | 竞品与市场事实研究 |
 | `tt-a1i/archify` | `199360cc6687a7857b54dd188d4922b09e466a4b` / `archify` | 条件式、可验证的技术架构图；YSS 适配见 `docs/agents/archify-integration.md` |
+| `iloveZzz/yss-ui` | `.agents/skills/.yss-skills-manifest.json` 锁定的 revision / `packages/skills` | 22 个 `categories.app` 业务前端 skills；排除组件库内部 `categories.library` 和后端提交 skill，适配见 `docs/agents/yss-ui-skills-integration.md` |
 | 项目本地 | `.agents/skills` 或平台专属 root | YSS 适配与项目治理 skills |
 
 `skills-lock.json` 是技能清单、来源、上游哈希、当前有效内容哈希和投影目标的权威记录：
@@ -44,10 +45,11 @@
    scripts/update-skill-lock
    ```
 
-   若来源来自可访问的 Matt checkout，还应显式校验锁定 revision 与每个上游目录哈希：
+   若来源来自可访问的上游 checkout，还应显式校验锁定 revision 与每个上游目录哈希：
 
    ```bash
-   scripts/verify-upstream-skill-source --source-root <matt-skills-checkout>
+   scripts/verify-upstream-skill-source --source=mattpocock/skills --source-root <matt-skills-checkout>
+   scripts/verify-upstream-skill-source --source=iloveZzz/yss-ui --source-root <yss-ui-checkout>
    ```
 
    新增共享 skill 时先显式登记：`scripts/update-skill-lock --add=<skill-name>`；新增平台专属 skill 使用 `scripts/update-skill-lock --add-platform=<root>:<skill-name>`。脚本不会把工作区中偶然出现的未跟踪目录自动纳入发布清单。
@@ -74,8 +76,9 @@
 ```bash
 scripts/sync-skills --check
 scripts/update-skill-lock --check
-# 可选：对照锁文件中的 mattpocock/skills revision 与上游目录哈希
-scripts/verify-upstream-skill-source --source-root <matt-skills-checkout>
+# 可选：对照锁文件中的 source revision 与上游目录哈希
+scripts/verify-upstream-skill-source --source=mattpocock/skills --source-root <matt-skills-checkout>
+scripts/verify-upstream-skill-source --source=iloveZzz/yss-ui --source-root <yss-ui-checkout>
 ```
 
 前者检查所有共享投影是否指向或匹配权威内容，后者检查 `skills-lock.json` 是否与当前完整目录树一致。过时技能不会保留兼容别名；旧 skill 名称和入口按 [`docs/agents/skill-migrations.md`](./skill-migrations.md) 一次性迁移，项目文件升级由 `create-yss-spec attach` / `sync` 处理。

package/template/docs/agents/yss-plugin-dependency-contract.md

@@ -0,0 +1,45 @@
+# YSS 插件依赖契约
+
+## 目的
+
+YSS Codex 插件可以随插件包提供角色 Harness skill，但不拥有目标项目的共享 skill。共享 skill 的权威内容仍是目标项目的 `.agents/skills`，投影、来源和 hash 由目标项目的 `skills-lock.json` 与 `docs/agents/yss-skill-registry.yaml` 管理。
+
+插件依赖文件位于插件根目录 `.yss-plugin/dependencies.yaml`，用于声明插件需要的角色契约，而不是复制 `core_skills` 清单。
+
+```yaml
+schema_version: 1
+plugin: yss-backend-harness
+requires:
+  - role_id: role.backend-engineer
+    registry: docs/agents/digital-human-roles.yaml
+    minimum_contract_version: 1
+```
+
+## 校验规则
+
+1. 插件导入时只校验 `dependencies.yaml` 的结构、插件名和 `schema_version`。
+2. 插件调用前必须校验目标项目 `yss-project.yaml`，且 `repository_mode` 合法。
+3. 目标项目必须存在依赖声明中的角色，且 `contract_version` 不低于 `minimum_contract_version`。
+4. 角色的 `core_skills` 由目标项目的 `digital-human-roles.yaml` 动态解析；插件不得维护第二份清单。
+5. 共享 skill 必须通过 `yss-skill-registry.yaml`、`skills-lock.json` 和目标 Agent projection 校验。
+6. 缺少角色、版本不兼容、skill 缺失、来源或 hash 漂移、投影不完整时，插件必须返回 `blocked`，不得降级执行。
+7. 插件不得自动写入 `.agents/skills`、`skills-lock.json` 或任何 Agent projection；修复应回路由到目标项目维护流程。
+
+## 运行时结果
+
+依赖不满足时至少返回：
+
+```yaml
+status: blocked
+blocking_signals: [missing-role]
+diagnostics:
+  plugin: yss-backend-harness
+  required_role: role.backend-engineer
+  next_route: install-or-sync-target-project-skills
+```
+
+`blocking_signals` 可使用 `repository-identity-invalid`、`missing-role`、`incompatible-contract-version`、`missing-skill`、`skill-source-drift`、`skill-hash-drift` 和 `skill-projection-incomplete`。
+
+## 版本策略
+
+依赖文件 schema 只保证同一主版本向后兼容。插件的 `minimum_contract_version` 是硬门槛；`tested_with` 等兼容性信息只能作为提示，不能替代目标项目的契约版本校验。

package/template/docs/agents/yss-skill-registry.yaml

@@ -3,12 +3,41 @@ registry_id: yss.skill-routing
 status: active
 description: >-
   技能分层、别名、默认可发现性和 Agent 运行时入口的可执行路由注册表。
-  本文件不替代 skills-lock.json 的来源、hash 与投影完整性职责；Router 与生命周期编排器只消费通过本表校验的 canonical 技能。
+  invocation_contract 提供低成本的调用模式、触发条件、排除条件、主要输出与依赖元数据；不执行三层行为评估，也不替代 skills-lock.json 的来源、hash 与投影完整性职责。
+  Router 与生命周期编排器只消费通过本表校验的 canonical 技能。
 canonical_content_root: .agents/skills
 runtime_policy:
   consumed_by_router: true
   consumed_by_lifecycle: true
   discovery_enforced: true
+invocation_contract:
+  schema_version: 1
+  scope: routing-and-dependencies-only
+  required_fields: [invocation_mode, trigger_conditions, exclusion_conditions, primary_output, required_dependencies, optional_dependencies]
+  allowed_invocation_modes: [user, model, both]
+  trigger_source: impacts
+  trigger_encoding: "impact:<impact>"
+  default:
+    invocation_mode: model
+    trigger_conditions: [registered-skill-request]
+    exclusion_conditions: [no-trigger-match]
+    primary_output: skill-guidance
+    required_dependencies: []
+    optional_dependencies: []
+  layer_defaults:
+    core:
+      invocation_mode: both
+      primary_output: workflow-result
+    specialist:
+      invocation_mode: model
+      primary_output: implementation-guidance
+    compatibility:
+      invocation_mode: user
+      primary_output: explicit-user-compatibility-input
+    maintainer-only:
+      invocation_mode: user
+      primary_output: maintenance-operation
+  overrides: {}
 agent_runtime_roots:
   claude: .claude/skills
   codex: .codex/skills
@@ -418,7 +447,7 @@ skills:
     layer: specialist
     maturity: supported
     instance_default_discoverable: false
-    aliases: [page-module-development, yss-ui-business-page-generation]
+    aliases: [page-module-development]
     impacts: [frontend]
   - id: yss-product-lifecycle
     layer: core
@@ -474,6 +503,12 @@ skills:
     instance_default_discoverable: false
     aliases: []
     impacts: [frontend]
+  - id: yss-ui-business-page-generation
+    layer: specialist
+    maturity: supported
+    instance_default_discoverable: false
+    aliases: []
+    impacts: [frontend]
   - id: yss-up-springboot3
     layer: specialist
     maturity: supported

package/template/docs/agents/yss-ui-skills-integration.md

@@ -0,0 +1,24 @@
+# YSS UI 前端 Skills 集成合同
+
+本模板以 `iloveZzz/yss-ui` 的 `packages/skills` 为上游来源，以 `.agents/skills/.yss-skills-manifest.json` 冻结来源 revision、包版本、目录映射和上游树哈希。`.agents/skills` 仍是模板内跨 Agent 共享内容的唯一权威目录；其他 Agent root 只接收生成投影。
+
+## 范围
+
+- 只集成 yss-ui `skills.config.json` 中 `categories.app` 的业务项目 skills，并排除后端 `java-backend-commit`，当前共 22 个。
+- `categories.library` 的 10 个组件库内部维护 skills 全部不进入模板；该分组同时位于上游 `excludeFromDefaultSync`。
+- `api-integration`、`page-module-development`、`use-table-height`、`use-tree-height` 在模板中分别映射为 `yss-api-integration`、`yss-page-module-development`、`yss-use-table-height`、`yss-use-tree-height`，旧名称只作为 registry alias。
+- `java-backend-commit` 明确不属于本合同；其内容、路由与锁定信息不随本前端同步更新。
+- 允许模板基于生命周期、组件路由和证据门禁做受控适配；适配后的 `effectiveHash` 与上游 `upstreamHash` 同时进入 `skills-lock.json`。
+
+## 更新步骤
+
+1. 在临时 checkout 中确认 `iloveZzz/yss-ui` 的目标 revision，并更新 `.agents/skills/.yss-skills-manifest.json`。
+2. 将新增或替换内容只写入 `.agents/skills/<canonical-name>`，不得直接编辑平台投影。
+3. 新增 skill 使用 `scripts/update-skill-lock --add=<canonical-name>` 显式登记。
+4. 运行 `scripts/sync-skills` 与 `scripts/update-skill-lock`。
+5. 使用 `scripts/verify-upstream-skill-source --source=iloveZzz/yss-ui --source-root=<checkout>` 验证 revision、清单和树哈希。
+6. 执行 `scripts/verify-template-fast`；首次冻结或正式发布前执行 `scripts/verify-template`。
+
+## MCP
+
+项目级 MCP 配置路径和容器字段同样由 manifest 固定，配置内容必须使用 `npx -y @yss-ui/mcp`。需要全局配置的运行时只提供人工安装说明，模板不得自动修改用户主目录。

package/template/docs/architecture/templates/engineering-baseline-review-template.md

@@ -33,6 +33,23 @@ owner: ai
 | 是否影响统一响应 / DTO / VO / Query / CMD | 是 / 否 |  |
 | 是否存在高风险变更、人工确认项或回滚约束 | 是 / 否 |  |
 
+## 2.1 质量基线与高风险反证
+
+| 字段 | 内容 |
+|---|---|
+| `baseline_id` |  |
+| `baseline_version` |  |
+| 适用范围 | `project-instance` / 影响面裁剪 |
+| 复用消费者 | Slice Contract、YSS Skill Execution Result、`code-review`、发布检查 |
+| 质量标准定义 | 一次定义，后续阶段只引用，不在切片内重复定义 |
+| 约束结果字段 | `constraint_results`（required） |
+
+| 高风险影响 | Doubt-Driven 状态 | 主张 / 反证 | 证据引用 | 残余风险 / 责任人 |
+|---|---|---|---|---|
+| API / 数据 / 跨仓 / 发布回滚 / 实际安全行为 / 生命周期或生成语义 | `not-applicable` / `required` / `completed` / `blocked` |  |  |  |
+
+> Doubt-Driven 只在命中的高风险决策中启用，不新增生命周期阶段；缺少反证、证据不足或残余风险未处理时不得通过工程基线。
+
 ## 3. YSS DDD 分层检查
 
 | 层级 | 职责 | 本次影响 | 约束 / 结论 |
@@ -72,6 +89,8 @@ owner: ai
 - [ ] Controller 不穿透 Repository。
 - [ ] 对象转换优先 MapStruct，重复 mapping 有处理策略。
 - [ ] 所需 YSS skills 已最小化选择。
+- [ ] `baseline_id` / `baseline_version` 已登记，后续切片和审查只引用该质量基线，未重复定义。
+- [ ] 命中高风险影响时已完成 Doubt-Driven 主张、反证、证据和残余风险记录；未命中时已记录 `not-applicable` 原因。
 - [ ] 风险影响、验证证据和责任人已记录。
 - [ ] 原型确认后已按脚手架顺序完成工程基线、生成器、`yss-backend-scaffold-parent` 和 Router 重编译；脚手架未生成业务行为。
 

package/template/docs/design/README.md

@@ -4,9 +4,20 @@
 
 设计系统基线：
 
-- `docs/design/design.md`：项目设计系统说明。默认亮色覆盖来自项目 Ant Design 5 `:root` / Less 裁定（主色 `#3371ff`、系统字体、6px 圆角），不再只沿用历史 `Product-Design-System` 包；官方 `design.md` 是上游默认，项目 token 是项目覆盖，优先级以该文件为准。
+- `DESIGN.md`：机器可读的视觉 token 与组件变体规范源，按 Google `design.md` alpha 格式维护。
+- `docs/design/design-system-sync.yaml`：主模板与可独立分发的战略设计模板之间的共享章节版本与 SHA-256 同步摘要。
+- `docs/design/design.md`：YSS 设计治理、双轨运行时、生命周期和验证说明；不与规范源重复定义 token。
 - `docs/design/tokens/`：随仓库保存的主题、亮色 / 暗色 / 紧凑 token 和 CSS 变量快照，后续实现不得依赖本机 Downloads 目录或原始 Less。
 
+模板源维护工具（仅在 `template-source` 仓库执行）：
+
+```bash
+node .template-source/tooling/node/scripts/design-md.mjs lint DESIGN.md
+node .template-source/tooling/node/scripts/design-md.mjs drift
+```
+
+令牌变更必须先修改 `DESIGN.md`，再更新派生快照；业务状态、API、权限和交互验收继续使用 Spec、交互说明及状态矩阵。
+
 产品原型产出默认以 `product-design:index` 为主入口。该 skill 只负责路由，实际按 Product Design plugin 规则进入 `$get-context`、`$ideate`、`$prototype`、`$image-to-code`、`$url-to-code`、`$share` 或 `$design-qa` 等 focused skill；YSS 生命周期仍负责校验低保真评审、高保真 HTML 原型、AntD CLI 校验证据、用户确认和 Spec / OpenAPI 回填。
 
 进入 Spec 初稿 / 需求基线流程后，必须先沉淀产品总体设计 / 功能架构，再进入页面 / 原型 / 交互设计、Spec 校准、API 影响分析 / 契约草案或实现。产品总体设计文档必须包含低保真原型 / 页面草图，用于验证页面结构、关键操作和主流程。无 UI 的功能也需要产品总体设计 / 功能架构来说明功能域、业务对象、模块边界、API / 数据影响和不适用的页面状态；只有不进入 Spec 生命周期的小改动可在影响面评估中记录不适用原因。

package/template/docs/design/design-system-sync.yaml

@@ -0,0 +1,12 @@
+schema_version: 1
+design_system_sync:
+  baseline: yss-spec-project-template
+  baseline_version: alpha
+  baseline_commit: 36af9ac3895162cefc5da8889af8141c2dfce2cd
+  baseline_sha256: 976d74b4af85b5062f9c5a365591809ff240159f0f4445ce05e7a4dcb76d0185
+  synchronized_sections:
+    - Colors
+    - Typography
+    - Layout
+    - Shapes
+    - Components

package/template/docs/design/design.md

@@ -1,8 +1,28 @@
-# 设计系统引入说明
+# 设计系统治理与生命周期适配
+
+> 规范源：仓库根目录 [`DESIGN.md`](../../DESIGN.md)。其中的 YAML frontmatter 和组件变体是视觉令牌的唯一事实来源；本文件只记录 YSS 的中文治理说明、运行时双轨、产品生命周期衔接和验证要求。
+
+## 与 DESIGN.md 的职责边界
+
+- `DESIGN.md`：机器可读的颜色、排版、圆角、间距和组件视觉变体规范；使用 Google `design.md` alpha 格式。
+- `docs/design/tokens/*`：由规范源投影的运行时快照，禁止直接修改后作为规范依据；使用 `scripts/design-md` 执行漂移检查。
+- 本文件：解释 YSS UI / Ant Design 双轨、页面设计约束、原型证据和生命周期门禁，不重新定义规范 token 的具体值。
+- Spec、交互说明和状态矩阵：继续承载业务状态、API、权限、并发、失败恢复和页面验收，不写入 `DESIGN.md`。
+
+## 规范校验
+
+模板源维护者在修改设计令牌后执行（项目实例不包含 `.template-source` 工具目录）：
+
+```bash
+node .template-source/tooling/node/scripts/design-md.mjs lint DESIGN.md
+node .template-source/tooling/node/scripts/design-md.mjs drift
+```
+
+`lint` 固定调用 `@google/design.md@0.4.0`，同时执行本地 frontmatter、章节、组件属性和引用校验；`drift` 检查规范源与全部 token/CSS 派生产物的哈希。任何漂移都必须回写规范源并重新生成投影。
 
 ## 来源与定位
 
-本文件基于本地设计系统包 `/Users/zhudaoming/Downloads/Product-Design-System` 首次分析整理，并在后续用项目 Ant Design 5 Less / `:root` CSS 变量覆盖默认亮色主题。紧凑密度、间距和容器规格同时参考 `/Users/zhudaoming/Projects/demo/yss-meta/apps/frontend/metadata-platform/packages/src/styles` 的实际实现。自本文件落地后，项目内设计系统的权威来源为 `docs/design/design.md` 与 `docs/design/tokens/*`；外部目录只作为历史输入或实现样本，不作为后续工程依赖，也不作为实现语言。
+本文件基于本地设计系统包首次分析整理，并在后续用项目 Ant Design 5 Less / `:root` CSS 变量覆盖默认亮色主题。紧凑密度、间距和容器规格同时参考既有 YSS 实现。视觉 token 的规范源改为根目录 `DESIGN.md`；本文件和 `docs/design/tokens/*` 是治理说明与派生视图。外部目录只作为历史输入或实现样本，不作为后续工程依赖，也不作为实现语言。
 
 关键来源：
 

package/template/docs/design/preview-dark.html

@@ -0,0 +1,15 @@
+<!doctype html>
+<html lang="zh-CN">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>YSS Design System Dark Preview</title>
+  <style>
+    :root { color-scheme:dark; --primary:#6f9bff; --primary-active:#91b2ff; --text:rgba(255,255,255,.88); --secondary:rgba(255,255,255,.65); --layout:#141414; --surface:#1f1f1f; --subtle:#262626; --border:#434343; --selected:#112a45; --success:#73d13d; --warning:#ffc53d; --error:#ff7875; font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif; }
+    * { box-sizing:border-box } body { margin:0; color:var(--text); background:var(--layout); font-size:14px; } .shell { max-width:1440px; margin:auto; padding:16px; } .toolbar { display:flex; gap:8px; flex-wrap:wrap; align-items:center; margin-bottom:12px; } h1,h2 { margin:0 0 12px; } h1 { font-size:24px; } h2 { font-size:18px; } .card { background:var(--surface); border:1px solid var(--border); border-radius:8px; padding:16px; margin-bottom:12px; } button,input,select { height:32px; border-radius:6px; border:1px solid var(--border); padding:0 12px; font:inherit; background:var(--surface); color:var(--text); } button.primary { border-color:var(--primary); background:var(--primary); color:#000; font-weight:600; } button.primary:hover,button.primary:focus-visible { background:var(--primary-active); } button:disabled { background:var(--subtle); color:var(--secondary); } input:focus-visible,select:focus-visible,button:focus-visible { outline:2px solid var(--primary); outline-offset:2px; } table { width:100%; border-collapse:collapse; } th,td { padding:8px 12px; border-bottom:1px solid var(--border); text-align:left; } th { background:var(--subtle); font-weight:600; } tr.selected { background:var(--selected); } .status { padding:8px 12px; border-radius:4px; margin:8px 0; } .success { background:var(--success); color:#000; } .warning { background:var(--warning); color:#000; } .error { background:var(--error); color:#000; } .muted { color:var(--secondary); } @media (max-width:768px) { .shell { padding:12px; } table { min-width:620px; } .table-wrap { overflow-x:auto; } }
+  </style>
+</head>
+<body>
+  <main class="shell"><div class="toolbar"><h1>YSS 设计系统预览</h1><span class="muted">暗色 / 紧凑密度</span><button class="primary">发布</button><button disabled>禁用</button></div><section class="card"><h2>暗色表面与状态</h2><div class="toolbar"><input aria-label="关键词" placeholder="关键词"><select aria-label="状态"><option>全部状态</option></select><button class="primary">查询</button></div><div class="status success" role="status">操作成功</div><div class="status warning" role="status">需要确认</div><div class="status error" role="alert">操作失败，请重试</div></section><section class="card"><h2>选中行与空状态</h2><div class="table-wrap"><table><thead><tr><th>名称</th><th>状态</th><th>操作</th></tr></thead><tbody><tr class="selected"><td>当前记录</td><td>已选中</td><td><button>查看</button></td></tr></tbody></table></div><p class="muted">无数据时使用可读文案，不使用空白占位。</p></section></main>
+</body>
+</html>