create-yss-spec 2.1.9 → 2.1.11

package/template/.cursor/skills/yss-product-lifecycle/references/state-model.md

@@ -0,0 +1,107 @@
+# 生命周期状态模型
+
+## 命名空间
+
+| 域 | 允许值 |
+|---|---|
+| `lifecycle.status` | `routing`、`running`、`paused-human-gate`、`blocked`、`completed` |
+| `workflow.status` | `not-started`、`active`、`paused`、`resolved`、`failed` |
+| `artifacts.*.status` | `missing`、`draft`、`ready-for-human`、`approved`、`stale`、`not-applicable` |
+| `gates.*.status` | `not-evaluated`、`blocked`、`ready-for-human`、`approved`、`stale`、`not-applicable` |
+| `tracker.kind` | `local-markdown`、`github`、`gitlab` |
+| `ticket.role` | `needs-triage`、`needs-info`、`ready-for-agent`、`ready-for-human`、`wontfix` |
+
+Matt 五态不得扩义。资产的 `ready-for-human` 与 Ticket label 必须带命名空间表达。
+
+## 上下文与外部输入证据
+
+状态模型不新增 context 状态域。阶段边界只在状态块或 checkpoint 中保存可选证据：
+
+```yaml
+phase_boundary:
+  decision: continue # continue / clear / handoff / subagent / compact
+  reason: <why-this-choice>
+  source_ref: null
+  destination_ref: null
+  task_package_ref: null
+  convergence_ref: null
+  next_phase: null
+```
+
+`handoff` 必须有来源和目的地；subagent 必须有任务包和汇合证据；`compact` 必须有下一阶段。`Continue`、`clear` 不要求跨上下文引用，但仍应记录判断理由。
+
+`to-questionnaire` 的暂停使用 `pause.reason_code: external-input-required`，并保存 `questionnaire_ref`、`recipient_role`、`requested_outputs` 和 `resume_route`。答案回流后补 `response_ref`、`reclassified_impact` 和 `updated_authoritative_asset`，然后重新计算 `stale`、门禁和可执行 frontier。
+
+## `ready-for-agent` 公式
+
+仅当以下全部为真，垂直切片 Ticket 才能获得该角色：
+
+```text
+required gates ∈ {approved, not-applicable}
+AND related artifacts 不含 stale
+AND blocking edges 全部关闭
+AND implementation repo/branch/CI/test/rollback 已明确
+AND Slice Implementation Contract 已由生命周期编排器批准并持久化
+AND 当前工作单元消费的 contract_id/version 与最新批准版本一致
+AND Backend Slice Implementation Contract（后端适用）和 Build Architecture Checklist 已完成
+AND backend 影响且 scaffold_status=required 时，原型确认后的脚手架策略、`yss-backend-scaffold-parent` 基线、Wrapper 验证和 Router 重编译均已完成
+AND 所有后续生成代码均绑定主 YSS skill、依赖闭包、允许写路径、预期证据和 YSS Skill Execution Result
+AND UI 影响切片的前端实现还原计划已通过 schema 校验、`template=false`、`status=approved`，且基线引用可读取
+```
+
+父 Ticket、Spec、设计、原型、OpenAPI Draft、wayfinder map 和 decision ticket 不得使用 `ready-for-agent`。
+
+发布前还必须满足所有已触发门禁均为 `approved` 或 `not-applicable`；UI 影响切片必须额外通过 `gate.frontend-implementation-verified`，不能只凭 fresh verification 和回滚点放行。
+
+用户显式运行 `to-tickets` 后，垂直切片初始角色固定为 `ready-for-human`。只有 `yss-product-lifecycle` 复算上述公式全部为真后，才能把它提升为 `ready-for-agent`；生命周期不会自动调用 `to-tickets`，其默认标签也不参与该裁决。
+
+## Review 与 Git 授权状态
+
+进入代码审查时保存 `review_mode`、`review_base_ref`、`implementation_candidate_ref`、`candidate_snapshot_ref`、`candidate_digest` 及 Spec、Ticket、合同、Checklist、YSS Execution Result 引用。`worktree` 候选必须一次捕获 committed、staged、unstaged 和 untracked 文件；manifest 的按模式必填字段以及 `yss-worktree-candidate-v1`（raw path、uint64 big-endian 长度、tracked/untracked record、symlink 和不支持条目）以 `orchestration-contract.yaml.review_input` 为唯一执行定义。两个 Reviewer 消费同一不可变快照；返回后或完成 checkpoint 摘要变化则返回 `blocked` 并重新审查。不新增生命周期状态，只把该清单作为审查证据。
+
+Git 动作分别保存 `commit_authorized`、`commit_scope`、`commit_authorization_ref`、`push_authorized`、`push_scope`、`push_authorization_ref`。只有授权值严格为 `true`、范围和用户授权引用均非空时才执行相应动作；缺失授权时保持工作区不变并记录 checkpoint 判断。
+
+## 状态块
+
+状态块位于主 tracker 的功能父 Ticket，并使用 `docs/process/templates/lifecycle-checkpoint-template.yaml` 的结构化形状和 `lifecycle-checkpoint.schema.json` 校验；Local Markdown 使用 `docs/.scratch/<feature>/parent-ticket.md`，可将完整 checkpoint 保存在 `docs/.scratch/<feature>/gates/lifecycle-checkpoint.yaml` 后由父 Ticket 引用，远程 tracker 使用 Issue 并在本地功能包保留引用。平台不可用时才位于 stage checkpoint。只保存索引、状态、引用和因果关系：
+
+```yaml
+lifecycle:
+  schema_version: 1
+  mode: resume
+  stage: system-data-architecture-and-contract-review
+  status: blocked
+workflow:
+  matt_flow: main
+  active_skill: yss-openapi-draft-review
+  status: paused
+artifacts:
+  spec: {status: approved, ref: docs/.scratch/example/spec.md}
+  openapi: {status: stale, ref: docs/.scratch/example/api/example.yaml, stale_by: [spec]}
+gates:
+  openapi_freeze: {status: stale}
+tracker:
+  kind: local-markdown
+  root: docs/.scratch
+  parent_ticket: docs/.scratch/example/parent-ticket.md
+  role: ready-for-human
+pause:
+  reason_code: human-gate
+  gate_ref: requirement-freeze
+  owner_or_authority: product-owner
+  resume_condition: requirement-freeze-approved
+  next_work_unit: api-impact-assessment
+```
+
+## Schema 兼容与迁移
+
+- 当前只支持 `schema_version: 1`，支持版本列表以 `orchestration-contract.yaml` 为准。
+- 版本缺失、解析失败或版本不在支持列表时，必须暂停并进入迁移检查；不得按 v1 猜测、覆盖或降级写回。
+- 主 tracker 的父 Ticket 状态块优先作为主索引；Local Markdown 的 `docs/.scratch/<feature>/parent-ticket.md` 是主载体，远程 Issue 只是显式选择远程 tracker 时的主载体。根 `.scratch/` 与 `docs/requirements/tickets/` 只作为旧路径迁移来源。stage checkpoint 只在选定平台不可用时降级。两者版本或内容冲突时，不做字段级静默合并：读取真实资产重建新状态，保留旧块引用和迁移记录，再由人工确认主载体。
+- 不得用旧版本状态覆盖较新版本。迁移记录至少包含来源版本、目标版本、来源载体、冲突、真实资产证据、迁移人和时间。
+
+## Resume
+
+读取状态块后必须重新读取引用资产、审查记录、Ticket 最新事件和相关 Git 变化。时间戳只能提示变化，不能单独证明语义失效；应比较内容和影响面。冲突时以权威资产为准，记录修复原因，然后重算依赖、门禁和可执行 frontier。
+
+所有暂停/阻塞必须填写结构化 `pause`：`reason_code`、`gate_ref` 或证据引用、`owner_or_authority`、`resume_condition`、`next_work_unit`。`lifecycle.status` 保持粗粒度，恢复条件以 `pause` 为准。

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

@@ -0,0 +1,40 @@
+---
+name: yss-prototype-stage
+description: Use when a YSS feature has product-design impact on a primary flow, navigation, state, recovery, permission experience, or UI-driven API contract and needs prototype assets before implementation readiness.
+---
+
+# YSS Prototype Stage
+
+把产品设计影响收敛为跨 Agent 一致的产物、证据和生命周期回流合同。它不替代 `yss-product-lifecycle` 的门禁裁决，也不把原型当作生产前端代码。
+
+## 进入条件与主入口
+
+- 先由 `yss-product-lifecycle` 判断产品设计影响；无行为变化的孤立视觉修复记录 `not-applicable`，不创建空资产。
+- Codex 的产出主入口是 `product-design:index`；其他 Agent 使用等价的产品设计能力，但必须产出本技能规定的相同资产和证据。能力或证据不能等价时，暂停并回到人工确认。
+- `high-fidelity-html-prototype` 仅为历史兼容入口；从它进入时立即回到本合同。已退休的原型技能（含 `product-design-prototype`）不得继续路由。
+
+## 资产与门禁顺序
+
+1. 以 Spec、产品总体设计和 `docs/design/design.md` 形成交互说明、低保真页面/流程与状态矩阵。
+2. 用 `prototype-review` 形成独立评审结论；未通过不得生成高保真或进入需求冻结。
+3. 通过 `product-design:index` 产出 `docs/.scratch/<feature>/design/prototypes/index.html`。
+4. 写入 `docs/.scratch/<feature>/verification/prototype-evidence.yaml`，完成 AntD CLI 与浏览器验证。
+5. 用户确认后，才可校准 Spec、分析 API 影响或进入 Router readiness。
+
+## 设计与 AntD 依据
+
+优先级固定为：官方 `design.md` 的上游默认 → `docs/design/design.md` 与项目 token 的 `project_design` 项目覆盖 → 当前功能的语义组件映射。不得用上游默认覆盖项目 token。
+
+使用官方 `antd` skill / CLI 查询事实，始终用 `--format json`，并记录实际 `antd`、CLI 和目标组件版本。至少保存 `antd design.md`、已选组件的 `info`/`demo`/`token`/`semantic` 查询和 `antd lint` 结果；目标版本存在时，将同一 `<target_antd_version>` 传给版本敏感查询，禁止在模板中固化某个 CLI 或组件版本。
+
+## 验证与回流
+
+`browser_verification` 至少覆盖非空渲染、主流程、一个失败/权限/冲突状态、桌面与窄屏视口和控制台错误；优先使用 Browser 或可执行浏览器自动化，Computer Use 只作人工交互补充。把路径、命令、版本、视口、结果和阻塞项写入证据清单。
+
+`gate.prototype-reviewed` 的证据是评审记录；`gate.prototype-verified` 的证据是 AntD CLI 与浏览器验证；`gate.user-confirmation` 的证据是确认记录。三者均不是实现授权。
+
+## 常见错误
+
+- 仅有截图或 HTML，却没有可复现的 CLI、浏览器和确认记录。
+- 把 `product-design:index` 或某个旧技能当作生命周期批准者。
+- 直接复制官方默认颜色、圆角或间距，忽略项目覆盖。

package/template/.cursor/skills/yss-repository/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: yss-repository
+description: Use when generating or refactoring YSS persistence models, BaseRepository/MyBatis repositories, MapStruct convertors, Domain Gateway implementations, or metadata/DDL-backed queries.
+---
+
+# yss-repository
+
+这是一个偏代码生成和结构补全的 skill，适合在已有工程里补 Repository 层，不适合替代完整脚手架。
+
+## 何时使用
+
+- 用户要生成 `PO / Repository / Convertor / GatewayImpl`。
+- 用户已有 Domain 模型，缺基础设施持久层落地。
+- 用户要基于表结构、DDL、metadata 补齐持久层代码。
+
+## 不适用
+
+- 只做 Controller 时，优先 `yss-web-controller`。
+- 只做领域建模时，优先 `yss-domain`。
+- 从零建多模块工程时，优先 `yss-ddd-scaffold-generator`。
+
+## 工作方式
+
+1. 先确认输入来源：领域模型、metadata、数据库表、DDL。
+2. 探测持久化 profile：新 DDD 默认 `PO <-> Domain Model`；legacy YSS 常见 `Entity + BaseRepository + GatewayImpl`。沿用现有工程命名，不混用两套模型。
+3. 如果 metadata 不完整，先补齐 metadata、数据库表结构或 DDL 输入。
+4. 涉及 POJO 字段、getter/setter、constructor、builder 或日志时，必须加载并遵守 `lombok`。
+5. 涉及持久化模型与 Domain/VO/CMD 转换时，必须加载并遵守 `mapstruct`。
+6. 生成代码时严格保持 Domain 与 Infrastructure 分层边界。
+7. 默认先生成基础 CRUD 骨架，把复杂查询留给手工实现。
+
+## 产物范围
+
+- `domain/{segment}/gateway/*Gateway.java`
+- `repository/entity/*PO.java`（legacy profile 沿用 `*Entity.java`）
+- `repository/*Repository.java`
+- `repository/convertor/*Convertor.java`
+- `repository/gateway/impl/*GatewayImpl.java`
+
+## 约束
+
+- Domain 不依赖 Infrastructure。
+- Gateway 定义在 Domain，实现放在 Infrastructure。
+- PO / Domain Model 等 POJO 样板代码优先使用 Lombok；不要成片手写 getter/setter、constructor、builder 或 logger。
+- Convertor 必须优先使用 MapStruct；禁止 `BeanUtils.copyProperties`、反射式通用拷贝和重复手写字段赋值，除非实现合同记录受控例外、测试和 review 证据。
+- MapStruct 与 Lombok 同时使用时，必须确认注解处理器顺序和 `lombok-mapstruct-binding` 配置；构建命令使用项目根目录 `./mvnw ...`。
+- 逻辑删除、审计字段、主键策略要显式处理，不要隐式略过。
+- 事务放在批准的 Application 用例边界；legacy GatewayImpl 已有事务时先记录并测试迁移影响，不重复嵌套制造假边界。
+
+## 质量门禁
+
+- 生成代码必须可编译。
+- 命名、包路径、注解要与工程现有规范一致。
+- Convertor 必须有 MapStruct 接口 / 抽象类、生成实现可编译，必要时补 mapper 单测或覆盖核心字段转换的行为测试。
+- POJO 使用 Lombok 时不得引入 `@Data` 造成实体 equals / toString 风险；有关系字段、敏感字段或懒加载字段时按 `lombok` skill 排除。
+- 遇到无法自动判断的字段或规则时，写 TODO 或向用户说明，不要假装已确认。
+
+## 协同顺序
+
+- metadata / DDL 输入准备：确认输入完整
+- 领域建模：`yss-domain`
+- 用例编排：`yss-application`
+- POJO 样板代码：`lombok`
+- 对象转换：`mapstruct`
+- Web 补齐：`yss-web-controller`
+
+## 分层开发规范
+
+实现 PO / Repository / GatewayImpl 前，必须加载 `references/infrastructure-layer-guide.md`：其中定义持久化对象、Repository、Convertor 与 Gateway 实现的结构与示例。
+
+## 阶段 7 合同
+
+- 前置条件：数据架构、领域元数据、实现仓库和批准后的 `Slice Implementation Contract` 均可用；否则不执行本 skill，由 Router 返回 `blocked`。
+- PO/Repository/Convertor 骨架可使用 `controlled-generation`；复杂过滤、分页语义、并发、事务和迁移行为必须拆为 `behavior-tdd`。
+- 写入仅限合同 `allowed_write_paths`，证据必须包含实际 PO、Repository、Convertor、GatewayImpl、测试和 `./mvnw ...` 结果。
+- 按统一 `YSS Skill Execution Result` 返回 `seam_deferred/deviations/new_impacts`；发现数据模型、DDL、SQL、索引或 API schema 变化时暂停并重路由。

package/template/.cursor/skills/yss-repository/agents/openai.yaml

@@ -0,0 +1,5 @@
+version: 1
+interface:
+  display_name: "YSS Repository"
+  short_description: "Repository、Convertor 与 gateway 实现规范"
+  default_prompt: "Use $yss-repository to generate or refactor YSS repository, convertor, and gateway implementation code."

package/template/{.agents/skills/yss-backend-scaffold-infrastructure/SKILL.md → .cursor/skills/yss-repository/references/infrastructure-layer-guide.md}

@@ -1,10 +1,3 @@
----
-name: "yss-backend-scaffold-infrastructure"
-description: "YSS 服务的基础设施层开发框架和技术指南。在实现数据访问层、数据库实体、外部服务适配器时需要用到。"
----
-
-# Infrastructure 层开发规范 (Infrastructure Layer Development Guide)
-
 本 Skill 提供了 YSS **Infrastructure (基础设施层)** 的通用开发规范。Infrastructure 层负责实现 Domain 层定义的网关接口，处理数据持久化、外部服务调用和配置管理。
 
 ## 1. 核心职责 (Core Responsibilities)

package/template/.cursor/skills/yss-resilience4j/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: yss-resilience4j
+description: Use when 用于 YSS Resilience4j starter、网关熔断、限流降级、GlobalCircuitExceptionAdvice、GatewayConfiguration 和断路器配置排障。
+---
+
+# yss-resilience4j
+
+Use this skill for YSS Resilience4j 组件. Keep implementation grounded in the local project and resolvable YSS backend component source.
+
+中文说明：本技能用于 YSS Resilience4j 组件。执行时优先读取源码索引，避免凭记忆猜类名、配置项或接入方式。
+
+## Source Index First
+
+- Backend source location is environment-specific; resolve it with `yss-source-index/references/source-location.md`.
+- Generated index: `references/source-index.md`
+- Component path hints: `yss-microservice-components/yss-component-resilience4j-starter`
+
+Read `references/source-index.md` as a path-hint index whenever the task depends on exact modules, annotations, auto configuration, properties, controllers, clients, repositories, DTOs, handlers, or troubleshooting.
+
+## Workflow
+
+1. Read `references/source-index.md`, then read component `readme.md`.
+2. Identify whether the task is gateway circuit breaker configuration, fallback response, global circuit exception handling, or resilience troubleshooting.
+3. Inspect `GatewayConfiguration` for route/filter wiring and `GlobalCircuitExceptionAdvice` for exception response behavior.
+4. Tune thresholds/timeouts in configuration rather than hardcoding resilience behavior in business handlers.
+5. Keep fallback responses consistent with gateway/API response contracts.
+
+## Capability Split
+
+- Gateway resilience wiring: `GatewayConfiguration`.
+- Circuit exception mapping: `GlobalCircuitExceptionAdvice`.
+- Operational guidance: README "轻量微服务断路器".
+
+## Checklist
+
+- Required dependency or starter module is present.
+- Circuit breaker names and route IDs match gateway configuration.
+- Fallback status/body are acceptable for frontend/API consumers.
+- Timeout, slow-call, and failure thresholds match service SLOs.
+- Logs/metrics make open/half-open/recovered states diagnosable.
+
+## Do Not
+
+- Do not invent class names or configuration keys without checking the source index.
+- Do not replace component extension points with business-local framework code.
+- Do not broaden the task into unrelated YSS components unless the user asks.

package/template/.cursor/skills/yss-resilience4j/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "yss-resilience4j"
+  short_description: "YSS component skill for yss-resilience4j"
+  default_prompt: "Use yss-resilience4j for this YSS backend component task."

package/template/{.codex/skills/yss-jdbc → .cursor/skills/yss-resilience4j}/references/source-index.md

@@ -1,4 +1,4 @@
-# yss-jdbc Source Index
+# yss-resilience4j Source Index
 
 Generated: 2026-08-17T12:03:37.436Z
 Source commit: `38b556a5081e6c66c0c538cbc1ef839b19996ed3`
@@ -11,20 +11,20 @@ Paths below are source path hints captured at refresh time. If they do not exist
 
 ## Component Path Hints
 
-- `yss-microservice-components/yss-component-jdbc` (existed when indexed)
+- `yss-microservice-components/yss-component-resilience4j-starter` (existed when indexed)
 
 ## Documentation Files
 
-- No component documentation files found.
+- `yss-microservice-components/yss-component-resilience4j-starter/readme.md`
 
 ## Maven Modules
 
-- `yss-microservice-components/yss-component-jdbc`
+- `yss-microservice-components/yss-component-resilience4j-starter`
 
 ## Key Java Entry Points
 
-- `yss-microservice-components/yss-component-jdbc/src/main/java/com/yss/cloud/jdbc/db/DefaultHutoolConfiguration.java`
-- `yss-microservice-components/yss-component-jdbc/src/main/java/com/yss/cloud/jdbc/db/JdbcSqlUtil.java`
+- `yss-microservice-components/yss-component-resilience4j-starter/src/main/java/com/yss/cloud/breaker/config/GatewayConfiguration.java`
+- `yss-microservice-components/yss-component-resilience4j-starter/src/main/java/com/yss/cloud/breaker/exception/GlobalCircuitExceptionAdvice.java`
 
 ## Recommended Next Reads
 

package/template/.cursor/skills/yss-router/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: yss-router
+description: Use when a YSS vertical slice is entering implementation, spans multiple frontend/backend/API areas, needs implementation readiness checked, or requires a minimal YSS skill set, Slice Implementation Contract, TDD mode, evidence plan, or reroute decision.
+---
+
+# YSS Router
+
+阶段 7 的实现合同编译器。它把已批准的生命周期资产和垂直切片编译为 `Slice Implementation Contract` 草案；不批准合同、不写业务代码、不设置 `ready-for-agent`。
+
+## 输入
+
+先读取 Spec、切片 Ticket、需求冻结、适用的原型确认、OpenAPI Freeze/no-impact、系统/数据架构、Design Review、Build Architecture Checklist、实现仓库和验证命令。输入缺失、未批准或 `stale` 时输出 `blocked`，交回 `yss-product-lifecycle`。
+
+## 编译循环
+
+1. 判断 frontend/backend/API/data/cross-repo 影响，并逐项填写 backend `component_impacts`。
+2. 检查工程存在性和核心/长尾 skill 可用性。
+3. 选择主 skill，并按 [router-contract.yaml](references/router-contract.yaml) 计算强制依赖闭包。
+4. 为切片生成基线合同；为当前行为生成工作单元增量路由。
+5. 选择 `behavior-tdd` 或 `controlled-generation`。
+6. 输出 `draft`、`blocked` 或 `ready-for-lifecycle-review`，交生命周期编排器核验和持久化。
+
+合同结构见 [slice-implementation-contract.md](references/slice-implementation-contract.md)，专项返回协议见 [yss-skill-execution-result.md](references/yss-skill-execution-result.md)。
+
+## 硬规则
+
+- Router 不得输出 `approved`、`ready-for-agent` 或 `completed`。
+- UI 影响缺少正式原型确认时，不得路由页面实现。
+- Repository/数据模型影响缺少数据架构时，不得路由持久化实现。
+- API 变化必须回到生命周期 Draft/Review/Freeze；半成品 backend 不得冒充稳定 source of truth。
+- 后端端到端切片必须包含 Application；对象/POJO 影响按契约自动补 `mapstruct`、`lombok`、`alibaba-java-code-style`。
+- Harness 内实现路径必须落在 `apps/backend/<project>/` 或 `apps/frontend/<project>/` 的具体项目目录；`apps/backend/`、`apps/frontend/` 只能作为容器，`app/backend/`、`app/frontend/` 及其子路径一律阻断。外部实现仓库使用其登记的真实项目根路径。
+- 当前用户、审计事件、普通技术日志、请求校验、错误映射或加解密命中时，必须按 `router-contract.yaml` 的 `component_impact_routing` 补齐长尾 skill；不能只在 `boundaries.md` 中提及。仅复用已经验证的平台认证 / 授权能力不算 component impact，不自动增加权限专项 skill。
+- 业务行为使用 `behavior-tdd`；只有机械脚手架/生成物可用 `controlled-generation`，并记录例外和验证。
+- 原型确认后若 backend `scaffold_status=required`，先由本 Router 按 `scaffold_contract_schema` 编译 `yss-ddd-scaffold-generator` 的 `controlled-generation` 工作单元合同 draft；合同必须带 `contract_id`、`contract_version`、Router draft、生命周期批准、持久化引用、允许写路径、预期证据和验证命令。经生命周期编排器批准并持久化后才能运行生成器，再由受控工作单元实际执行固定的 `./mvnw validate`、`./mvnw test`、`./mvnw package` 并记录逐条结果，随后加载 `yss-backend-scaffold-parent` 并重新编译业务合同；脚手架不承载业务行为。
+- 脚手架合同在 Router 阶段只能是 `draft` / `ready-for-lifecycle-review` / `blocked`；只有生命周期编排器可以把已持久化脚手架合同标记为 `approved`。脚手架合同只覆盖业务代码前的工程骨架工作单元；生成、基线校验和 Router 重编译完成后，它不能替代脚手架后的 Slice Implementation Contract。
+- 脚手架输出消费批准的脚手架合同；脚手架后的所有生成后端代码都必须绑定当前批准且版本当前的 Slice Implementation Contract、主 YSS skill、依赖闭包、允许写路径、预期证据和 YSS Skill Execution Result。打印命令、`./mvnw validate` 单项通过或脚手架成功不能替代合同批准；生成范围从机械内容变成业务行为时触发完整重路由。
+- 专项结果中的越界路径、缺失证据、`drift`、`violation` 或 `new_impacts` 必须阻断或重路由。
+- 长尾 skill 不可用时显式 `blocked`，不得用通用知识假装已应用 YSS 规范。
+
+## 三级路由
+
+- 切片基线路由：生成完整合同和技能闭包。
+- 工作单元增量路由：绑定一个行为、主/辅 skills、TDD 模式、路径和证据。
+- 完整重路由：API/schema、状态机、数据模型、仓库、写路径、skill、测试 seam 或架构约束发生实质变化时触发。实现中出现未冻结的新行为（包括明确的权限业务行为）统一写入 `new_impacts`，由生命周期按普通影响面重新分诊。
+
+## 输出
+
+输出合同草案、技能依赖闭包、不适用理由、阻塞项、TDD 模式、工作单元、预期证据、验证命令、人工审查点和完整重路由触发器。自然语言说明不能替代结构化合同字段。

package/template/.cursor/skills/yss-router/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "YSS Router"
+  short_description: "Route YSS tasks to the right skills"
+  default_prompt: "Use yss-router to choose the minimal YSS skills for this task."

package/template/.cursor/skills/yss-router/references/boundaries.md

@@ -0,0 +1,50 @@
+# YSS Skill Boundaries
+
+Use this reference when multiple YSS skills seem applicable.
+
+中文说明：当多个 YSS 技能看起来都能用时，先看这个边界说明，选择最小技能组合。
+
+## Frontend Boundaries
+
+- `yss-page-module-development`: Page/module workflow. Use for creating or reorganizing a page folder, deciding structure, and assembling page, hooks, schemas, and blocks.
+- `yss-components`: Component layout and visual/page composition rules. Use for YTable/YTree/YssFormily/YSplitPane usage details.
+- `yss-hook`: Request, pagination, parameter, tree-selection, and response-mapping logic in `views/**/hooks/useXxx.ts`.
+- `api-integration`: Orval-generated API client imports, request/response mapping, `useRequest` calling patterns, submit/list/detail flows.
+- `yss-formily`: Hand-written YssFormily schema implementation and form behavior.
+- `yss-formily-schema-generator`: Generate YssFormily schema from requirements, screenshots, mockups, Figma, or natural-language field descriptions.
+- `yss-use-table-height`: Only table available-height calculation and required container/pagination/toolbar wiring.
+- `yss-use-tree-height`: Only tree available-height calculation, search offset, and virtual scrolling wiring.
+
+Default for a new page: first verify the approved product design, state matrix, Ant Design v6 high-fidelity HTML prototype, AntD CLI evidence, and user confirmation; then start with `yss-page-module-development` and add the narrow skills that match the page controls.
+
+中文说明：新建页面默认从页面模块技能开始，只有遇到具体组件、Hook、API、Formily 细节时再加载专项技能。
+
+## Backend Boundaries
+
+- `yss-ddd-scaffold-generator`: Create a whole multi-module backend skeleton.
+- `yss-domain`: Domain modeling, domain gateway contracts, and domain-layer conventions.
+- `yss-application`: Application use cases, transaction boundaries, and cross-aggregate orchestration.
+- `yss-repository`: Persistence implementation, PO, Repository, Convertor, GatewayImpl.
+- `yss-web-controller`: REST adapter layer, request/response DTOs, VO, web convertor.
+- `yss-mybatis`: Framework behavior for MyBatis/MyBatis-Plus, BaseRepository, pagination, mapper scanning, batch, datasource issues.
+- `yss-dto`: Result/PageQuery/CommandDTO/QueryDTO and unified API contract objects.
+
+Default for end-to-end backend CRUD: include Domain, Application, Infrastructure, and Web skills plus `mapstruct`, `lombok`, and `alibaba-java-code-style`; add `yss-mybatis` when persistence framework details matter. The executable closure in `router-contract.yaml` is authoritative.
+
+中文说明：后端 CRUD 按领域、DTO、持久层、Controller 分层处理；只有涉及 MyBatis 机制、分页、扫描、多数据源时才加 `yss-mybatis`。
+
+## Component Boundaries
+
+- `yss-cache`: Query/update/clear cache annotations, Redis/Caffeine/JetCache wiring, cache invalidation.
+- `yss-audit-log`: Audit annotations, SpEL summaries, async publication, subscribers.
+- `yss-excel-mvc`: Spring MVC Excel import/export annotations and handlers.
+- `yss-distributed-id`: ID strategies, AutoIdInterceptor, Leaf/CosId/Snowflake, batch ID injection.
+- `yss-resilience4j`: Circuit breaker, fallback, and gateway resilience integration.
+- `yss-validation`: Validation engine and JSR-303 integration.
+- `yss-security-algorithm`: RSA/AES/SM/JWT/JWK/password-encoding compatibility and production key-management safety gates.
+- `yss-userinfo`: Current-user info propagation and starter integration.
+- `yss-exception`: Exception component and unified exception handling.
+
+Component skills should inspect generated `references/source-index.md` before changing code when the task depends on exact class or config names.
+
+中文说明：组件类技能不要凭记忆猜类名，先用源码索引找真实位置。