create-yss-spec 2.2.7 → 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/README.md

@@ -42,17 +42,17 @@
 
 1. 先读取 `yss-project.yaml`，按 `repository_mode` 选择模板维护或产品研发生命周期。
 2. 必读入口为 `AGENTS.md` 与 `CONTEXT.md`；流程事实分别以生命周期映射和裁剪指南为准。
-3. `template-source` 修改流程、技能或模板后，执行 `scripts/sync-skills`、`scripts/update-skill-lock` 和 `scripts/verify-template`。
-4. `project-instance` 先做影响面分诊；进入 Spec 基线时使用 `grill-with-docs`、`to-spec`，契约冻结后再用 `to-tickets` 拆分垂直切片 Ticket。
+3. `template-source` 修改后先按 `maintenance-intensity.yaml` 判定 L1 / L2 / L3，默认用 `scripts/verify-template-fast` 达到 `implementation-ready`；L3 日常采用维护者自检，正式发布前执行完整门禁；只有共享 skill 变更才运行 `scripts/sync-skills` 和 `scripts/update-skill-lock`。
+4. `project-instance` 默认从 `yss-product-lifecycle` 的 `route` 模式开始，再由原生 `work-unit.*` 推进 Discovery、Spec、产品设计、工程契约和 Ticket 正式化；`grill-with-docs`、`to-spec`、`to-tickets`、`implement` 仅作为用户显式调用的兼容入口。
 5. 实现仓库接入、YSS 路由、独立审查、fresh verification 和 Git checkpoint 以 `AGENTS.md` 的硬门禁为准。
 
 YSS skills 的公开发布投影维护在 [iloveZzz/yss-spec-dev-skills](https://github.com/iloveZzz/yss-spec-dev-skills)，发布清单和导出命令见 [skills 维护说明](./docs/agents/skills-maintenance.md)。
 
 ## 模板初始化 CLI
 
-`create-yss-spec` 的目标维护位置是独立 GitHub 仓库 [iloveZzz/create-yss-spec](https://github.com/iloveZzz/create-yss-spec)。本仓库不再包含 CLI 源码、测试、发布配置或开发过程记录，只保留面向模板使用者的实践指南：
+`create-yss-spec` 的目标维护位置是独立 GitHub 仓库 [iloveZzz/create-yss-spec](https://github.com/iloveZzz/create-yss-spec)。本仓库不再包含 CLI 源码、测试、发布配置或开发过程记录。CLI 的使用方法已经合并到统一用户手册：
 
-- [create-yss-spec 外部 CLI 实践指南](./docs/user-guide/外部命令行工具实践指南.md)
+- [YSS 用户手册：创建、接管和更新项目](./docs/user-guide/用户手册.md#创建接管和更新项目)
 
 推荐入口：
 
@@ -80,13 +80,13 @@ main@6acc160e4e0cd062dbbbd7a1b26ae92855edf07e
 
 主研发流程使用 `skills/engineering`；`skills-lock.json` 同时记录本次安装的关联 `productivity`、`in-progress`、`deprecated`、`misc` 和 `personal` skill 路径。
 
-## 轻量校验
+## 模板校验
 
 ```bash
-scripts/verify-template
+scripts/verify-template-fast
 ```
 
-该脚本检查：
+快速入口按 Git 影响面执行相关检查，未映射路径或核心校验资产变化时 fail-safe 升级。它与 candidate / 发布 profile 共同检查：
 
 - `yss-project.yaml`、权威流程资产和模板是否完整。
 - 共享技能投影及 `skills-lock.json` 的完整树哈希是否一致。
@@ -96,14 +96,14 @@ scripts/verify-template
 - 示例 OpenAPI YAML 是否可解析。
 - Git diff 是否存在空白错误。
 
+显式准备审查候选时执行 `scripts/verify-template-candidate`；首次正式冻结前和最终发布前执行不可裁剪的 `scripts/verify-template`。
+
 ## 关键文档
 
 | 文档 | 内容 |
 |------|------|
 | [AGENTS.md](./AGENTS.md) | 全局 AI 指令 + 工程基线入口 + Agent 协作 |
-| [docs/user-guide/用户手册索引.md](./docs/user-guide/用户手册索引.md) | 模板使用说明 |
-| [docs/user-guide/产品生命周期工作流.md](./docs/user-guide/产品生命周期工作流.md) | 产品全生命周期使用手册 |
-| [docs/user-guide/图示生成器使用指南.md](./docs/user-guide/图示生成器使用指南.md) | Excalidraw 可视化辅助 skill 使用手册 |
+| [docs/user-guide/用户手册.md](./docs/user-guide/用户手册.md) | 从首次只读检查到需求、开发、审查、发布和 CLI 操作的统一用户手册 |
 | [docs/process/PDCA-SCRUM.md](./docs/process/PDCA-SCRUM.md) | PDCA × Scrum × AI |
 | [docs/process/MATT-POCOCK-ENGINEERING-SKILLS.md](./docs/process/MATT-POCOCK-ENGINEERING-SKILLS.md) | Matt Pocock Engineering Skills 集成与使用 |
 | [docs/process/lifecycle-registry.yaml](./docs/process/lifecycle-registry.yaml) | 生命周期结构事实源：主阶段、门禁、产物、工作单元、证据与稳定 ID |
@@ -113,7 +113,6 @@ scripts/verify-template
 | [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/规格与任务迁移指南.md](./docs/user-guide/规格与任务迁移指南.md) | 旧规格与任务入口迁移指南 |
 | [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/__yss_dotfile__.gitignore

@@ -37,6 +37,7 @@ htmlcov/
 Excalidraw
 .obsidian
 .ua
+output
 docs/process/presentations/
 docs/process/yss-product-lifecycle-team-guide.md
 docs/graphify-out

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/skills-maintenance.md

@@ -36,7 +36,7 @@
 
 1. 在临时目录读取或下载锁定来源，不直接覆盖工作区。
 2. 只在 `.agents/skills/<skill-name>/` 修改共享技能；平台专属技能只在所属 root 修改。
-3. 创建、修改或退役 skill 时使用 `maintaining-skills`，并先按 `docs/process/harness-process-tailoring.md` 判定验证与审查强度：L1 执行相关检查，L2 记录最小反例和 fresh verification，L3 记录完整 RED 基线、压力场景、GREEN 结果和 REFACTOR 检查。未定义分级的外部仓库按实际风险执行结构校验和针对性行为验证，不强制为每次普通修改构造失败基线。
+3. 创建、修改或退役 skill 时使用 `maintaining-skills`，并先按 `docs/process/harness-process-tailoring.md` 判定验证与审查强度：L1 执行相关检查，L2 记录最小反例、fresh verification 和聚焦审查，L3 记录维护者自检与 fresh verification；正式发布前统一执行完整模板门禁。未定义分级的外部仓库按实际风险执行结构校验和针对性行为验证。
 4. 生成共享投影并更新锁文件：
 
    ```bash
@@ -78,7 +78,7 @@ scripts/update-skill-lock --check
 scripts/verify-upstream-skill-source --source-root <matt-skills-checkout>
 ```
 
-前者检查所有共享投影是否指向或匹配权威内容，后者检查 `skills-lock.json` 是否与当前完整目录树一致。过时技能不会保留兼容别名；旧版项目按 `docs/user-guide/规格与任务迁移指南.md` 一次性迁移。
+前者检查所有共享投影是否指向或匹配权威内容，后者检查 `skills-lock.json` 是否与当前完整目录树一致。过时技能不会保留兼容别名；旧 skill 名称和入口按 [`docs/agents/skill-migrations.md`](./skill-migrations.md) 一次性迁移，项目文件升级由 `create-yss-spec attach` / `sync` 处理。
 
 ## skills.sh 公开发布
 

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/api/templates/openapi-draft-review-checklist.md

@@ -16,7 +16,7 @@
 | 原型 / 线框图 |  |  |
 | 状态矩阵 | `docs/.scratch/<feature>/design/<feature>-state-matrix.md` |  |
 | 原型评审结论 | `docs/.scratch/<feature>/design/<feature>-prototype-review.md` |  |
-| 高保真 HTML 原型 | `docs/.scratch/<feature>/design/prototypes/index.html` | 有 UI 时必需；必须使用 Ant Design v6，并通过 `product-design:index` 路由产出或记录例外原因 |
+| 高保真 HTML 原型 | `docs/.scratch/<feature>/design/prototypes/index.html` | 有 UI 时必需；主题/视觉标准必须为 Ant Design v6，并通过 YSS Product Design adapter + `product-design:index` 路由产出或记录例外原因；生产 API 为 YSS UI + Ant Design Vue 4.x |
 | AntD CLI 校验证据 | `docs/.scratch/<feature>/design/<feature>-prototype-confirmation.md` 或评审记录 | 有 UI 时必需；记录 design.md / info / demo / token / semantic 查询 |
 | 用户确认记录 | `docs/.scratch/<feature>/design/<feature>-prototype-confirmation.md` | 有 UI 时必需；未确认前不得进入 OpenAPI Draft 评审 |
 | YSS 工程基线 | `.codex/skills/yss-ddd-scaffold-generator/references/yss-backend-scaffold-parent/SKILL.md` |  |
@@ -37,7 +37,7 @@
 | YAML 权威性 | 单一 OAS 3.1 document；未混入生命周期 frontmatter / 根字段；`operationId` 稳定 |  |  |
 | P0 覆盖 | 每个 P0 需求有 endpoint/schema/error/test 或明确非目标 |  |  |
 | 产品总体设计完整 | Draft 已依据 Spec 和产品总体设计 / 功能架构；缺产品总体设计时返回上游补齐 |  |  |
-| 交互输入完整 | 有 UI 时，Draft 已同时依据交互说明、原型/线框、状态矩阵、prototype-review、Ant Design v6 高保真 HTML 原型、AntD CLI 校验证据和用户确认记录；无 UI 时需说明页面 / 交互资产不适用原因 |  |  |
+| 交互输入完整 | 有 UI 时，Draft 已同时依据交互说明、原型/线框、状态矩阵、prototype-review、Ant Design v6 主题/视觉标准高保真 HTML 原型、schema v2 AntD/语义映射/浏览器/无障碍证据和用户确认记录；无 UI 时需说明页面 / 交互资产不适用原因 |  |  |
 | DDD 契约边界 | Endpoint/schema 归属的限界上下文清楚；术语与 `CONTEXT.md` 和功能架构一致；契约不直接暴露内部聚合、Repository 或持久化表结构 |  |  |
 | 页面动作覆盖 | 每个按钮 / 抽屉 / 弹窗动作有 endpoint/non-goal、`actionKey` 和错误码；Spec 明确认认证 / 授权变化时同时映射该行为 |  |  |
 | 对象生命周期 | manage/maintain/configure/create/update/archive/retry/cancel/publish/export/create-draft 语义闭环 |  |  |

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 生命周期的小改动可在影响面评估中记录不适用原因。
@@ -20,7 +31,7 @@
 - 表单、表格、弹窗、抽屉、步骤流等交互说明。
 - loading、empty、error、readonly、disabled、no-permission、conflict 等状态矩阵。
 - 页面字段、筛选条件、操作按钮和权限规则。
-- 低保真原型评审通过后的 Ant Design v6 高保真可交互 HTML 原型，默认路径为 `docs/.scratch/<feature>/design/prototypes/index.html`；该产物可由系统 / Agent 自动生成，不要求用户手工提供，产出前必须使用 `yss-antd-design` 查询设计语言、组件 API、demo、token 和 semantic 信息，产出后必须记录 AntD v6 校验证据并获得用户确认。前端代码落地改用 `yss-ui`。
+- 低保真原型评审通过后的 Ant Design v6 主题/视觉标准高保真可交互 HTML 原型，默认路径为 `docs/.scratch/<feature>/design/prototypes/index.html`；标准 React 原型组件精确锁定与 CLI 一致的 `antd@6.x`，通过 YSS Product Design adapter 消费项目 token、pnpm、同视口 QA 和无障碍证据。生产组件/API 仍是 Vue 3 + YSS UI + 实现仓 lockfile 的 Ant Design Vue 4.x。产出后必须记录 schema v2 原型证据并获得用户确认。
 
 这些资产用于反推 API 影响、契约草案、OpenAPI 请求 / 响应字段、错误结构、分页筛选、权限状态和前端验收标准。
 
@@ -36,7 +47,7 @@
 推荐技能：
 
 - `yss-design-system`：项目设计系统与 Ant Design 企业级 UI 风格基线；页面设计、原型评审、UI 实现和主题 token 落地时默认先引用。Codex `$design-qa` 的 token / 字体对照读该技能的 `references/design-qa-theme.md`，以项目覆盖为准，不改上游 `design-qa` 插件。
-- `yss-prototype-stage`：跨 Agent 的原型阶段合同，固定资产、证据、设计优先级与生命周期回流；Codex 的主路由为 `product-design:index`。
+- `yss-prototype-stage`：跨 Agent 的原型阶段主合同，固定资产、证据、设计优先级与生命周期回流；其 `references/product-design-adapter.md` 把 Codex `product-design:index` 通用产出接入 YSS 双轨版本、项目主题和证据合同。
 - `product-design:index`：Codex 产品原型产出的主路由；根据输入是否有 URL、截图、Figma、代码目标或视觉方向，进入 `$get-context`、`$ideate`、`$prototype`、`$image-to-code`、`$url-to-code`、`$share` 或 `$design-qa` 等 focused skill。
 - Product Design focused skills：基于 Spec 初稿和产品总体设计 / 功能架构，产出低保真 / 高保真页面、原型、交互设计资产和可分享原型；高保真 HTML 原型默认由该路由链路产出。
 - `yss-antd-design`：仅用于原型设计构建的 Ant Design v6 事实技能；生成或修改高保真 HTML 原型前后必须留下 CLI 校验证据。前端代码落地改用 `yss-ui`。

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