create-yss-spec 2.2.8 → 2.2.9

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/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,6 +133,7 @@ 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]
@@ -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/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

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>

package/template/docs/design/preview.html

@@ -0,0 +1,20 @@
+<!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 Preview</title>
+  <style>
+    :root { --primary:#3371ff; --primary-active:#245bdb; --text:rgba(0,0,0,.88); --secondary:rgba(0,0,0,.65); --layout:#f0f2f5; --surface:#fff; --subtle:#fafafa; --border:#d9d9d9; --selected:#e6f4ff; --success:#52c41a; --warning:#faad14; --error:#f5222d; 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); } 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); color:#fff; } button:disabled { background:#f0f0f0; color:rgba(0,0,0,.45); } 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); } .grid { display:grid; grid-template-columns:repeat(3,minmax(0,1fr)); gap:12px; } .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; } .grid { grid-template-columns:1fr; } .toolbar > * { flex:1 1 140px; } 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" onclick="this.textContent='已保存'; this.disabled=true">保存</button><button disabled>禁用</button></div>
+    <section class="card"><h2>筛选与表单</h2><div class="toolbar"><input aria-label="关键词" placeholder="关键词"><select aria-label="状态"><option>全部状态</option><option>已启用</option></select><button class="primary">查询</button><button>重置</button></div><div class="status warning" role="status">请补充必填筛选条件。</div></section>
+    <section class="card"><h2>数据表格</h2><div class="table-wrap"><table><thead><tr><th>名称</th><th>状态</th><th>更新时间</th><th>操作</th></tr></thead><tbody><tr class="selected"><td>示例任务</td><td><span class="status success">成功</span></td><td>2026-09-02 09:30</td><td><button>查看</button></td></tr><tr><td>加载中的任务</td><td>加载中…</td><td>—</td><td><button disabled>编辑</button></td></tr><tr><td>失败任务</td><td><span class="status error">失败：权限不足</span></td><td>—</td><td><button>重试</button></td></tr></tbody></table></div></section>
+    <div class="grid"><section class="card"><h2>空状态</h2><p class="muted">暂无数据，请调整筛选条件。</p><button class="primary">创建记录</button></section><section class="card"><h2>弹层触发</h2><button onclick="alert('Modal / Drawer 应提供可见反馈和焦点管理')">打开 Modal</button></section><section class="card"><h2>无障碍</h2><p class="muted">使用 Tab 检查焦点顺序；缩放到 200% 检查布局。</p></section></div>
+  </main>
+</body>
+</html>

package/template/docs/design/tokens/.design-md-projection.json

@@ -0,0 +1,13 @@
+{
+  "schema_version": 1,
+  "source": "DESIGN.md",
+  "source_sha256": "976d74b4af85b5062f9c5a365591809ff240159f0f4445ce05e7a4dcb76d0185",
+  "files": {
+    "docs/design/tokens/theme.json": "94010a32320bfe7135f75d87357609162e0358061fe8577d820dcb62f43ac4e4",
+    "docs/design/tokens/tokens.default.json": "bf89486a8730a68673473fa7d5afe40b158e833b10df7da75d505bc53f8f6167",
+    "docs/design/tokens/tokens.dark.json": "79b93203f305d26f2f230a8af1f4b7e77c9bdb7997efa0746eed1508c928f85b",
+    "docs/design/tokens/tokens.compact.json": "afa4ae457a3db81d4b8a4b103ed9d6baa897daa1bbc23c96ee7d9182d2b4b992",
+    "docs/design/tokens/variables.css": "d5bb7bdfe13d71214c44d1a0fdf9648cb5fa35cb6511fb2a35202f8a96fb39dd",
+    "docs/design/tokens/variables.dark.css": "b8ebb18f304831ee5c86cf6e5563702b2cc0ce2f51b055036e437a385226cd99"
+  }
+}

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

@@ -0,0 +1,71 @@
+# Agent Skill 治理升级决策分析
+
+## 结论摘要
+
+1. 逐技能结构 / 路由 / 行为 eval 不作为 YSS 模板首个升级方向。结构和路由已有确定性校验；行为 eval 成本高、易重复生命周期门禁，应降为后续按变更和风险触发的试验性能力。
+2. invocation metadata 进入 `yss-skill-registry.yaml`；Router 合同只定义字段 schema、解析和阻断规则，不复制每个 skill 的示例。trigger examples 进入注册表，但保持少量、结构化、只为消歧服务。
+3. freshness audit 作为生命周期完成条件的 core 能力，不新建一个常驻通用 skill；Doubt-Driven 作为高风险条件触发的 core 路由策略；Wayfinder 保持 maintainer-only / 兼容入口的可选模式，不进入默认 core 路由。
+
+## Q1：eval 是否为首个升级方向
+
+### 现状事实
+
+- 技能身份、层级、成熟度、别名、默认可发现性和来源投影已经由 [`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 重路由。
+
+### 决策
+
+不把“每个 skill 三层 eval”作为 P0。采用以下顺序：
+
+| 层次 | 初始策略 | 原因 |
+|---|---|---|
+| 结构 | 继续使用现有静态 / schema 校验 | 成本最低，收益已覆盖大部分缺陷 |
+| 路由 | 只对注册表、Router、生命周期变更做确定性增量校验 | 与现有门禁直接对齐，避免重复运行 |
+| 行为 | P2 试验；只覆盖变更中的 core / 高风险 skill | 避免全量运行导致 token 和维护成本失控 |
+
+行为 eval 的进入条件应是：skill 内容或路由发生变化、命中高风险影响、或出现真实 finding；退出条件是连续真实任务证明它能发现现有静态校验抓不到的问题，且没有形成第二套生命周期门禁。
+
+## Q2：invocation metadata 与 trigger examples 的归属
+
+### 决策
+
+- **注册表**是技能级调用元数据的唯一事实源：调用模式、触发条件、排除条件、主要输出、依赖和少量 trigger examples 均放在这里。
+- **Router 合同**定义 schema、解析顺序、依赖闭包和阻断规则；不复制每个技能的完整示例，避免注册表与 Router 漂移。
+- **生命周期编排合同**继续保留工作单元级 `workflow_reference.invocation_mode`（例如 `model-invoked` / `reference`）。它描述一次工作单元如何被执行，不与注册表的 `user` / `model` / `both` 技能级模式混用。
+
+### trigger examples 约束
+
+- 仅为消歧提供 1–3 个正向示例，必要时提供反向排除示例。
+- 示例优先使用 `impact:<name>`、显式用户入口或工作单元 ID 等稳定标识；长篇自然语言放入 skill reference，不放在注册表核心字段。
+- 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) 的合同字段。
+
+## Q3：三项能力的路由层级
+
+| 能力 | 推荐层级 | 具体落点 | 不应做什么 |
+|---|---|---|---|
+| freshness audit | core 能力 | 生命周期完成条件、候选快照、fresh verification、stale / drift 检查 | 不再新增一个对所有任务常驻的通用审计 skill |
+| Doubt-Driven | core 条件路由 | Router / 工程基线 / 架构与契约审查中的高风险分支 | 不升级为所有低风险任务的默认步骤，不新建生命周期阶段 |
+| Wayfinder | maintainer-only / 兼容入口的可选模式 | 超长、多 Agent、多会话或 frontier 不清晰时，完成后回 `handoff → to-spec` | 不改变阶段、门禁、Ticket 角色或 `ready-for-agent` |
+
+### Doubt-Driven 的高风险触发器
+
+API schema、数据库 schema / 迁移、跨仓库契约、发布 / 回滚、实际改变的认证授权 / 租户 / 敏感数据行为，以及生命周期或生成语义。反证记录进入既有决策、架构、契约或发布审查记录；缺反证、证据不足或残余风险未处理时阻断。
+
+### freshness audit 的边界
+
+freshness 是“完成结论可信度”的 core 约束，而不是新的工作单元。模板维护继续使用 L1/L2/L3 checkpoint；产品切片继续使用 Slice Contract 和候选快照。这样可以复用同一条 finding 闭环，不增加每次调用的上下文负担。
+
+## 证据来源
+
+- [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)
+- [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)
+- [Matt Pocock skills](https://github.com/mattpocock/skills)