create-yss-spec 2.1.9 → 2.1.11

package/template/{.codex/skills/yss-backend-scaffold-web/SKILL.md → .agents/skills/yss-web-controller/references/web-adapter-layer-guide.md}

@@ -1,10 +1,3 @@
----
-name: "yss-backend-scaffold-web"
-description: "YSS 管理服务的 Web Adapter 开发框架和技术指南。在实现 REST API 控制器、请求处理和响应格式化时需要用到。"
----
-
-# Web Adapter Layer Development Guide
-
 本技能为开发 YSS 服务的**Web 适配器层**（REST API）提供指导和框架。
 Web 适配器负责通过 HTTP 公开业务功能、处理输入验证和格式化响应。
 

package/template/.claude/skills/ask-matt/SKILL.md

@@ -8,9 +8,15 @@ disable-model-invocation: true
 
 You don't remember every skill, so ask.
 
+## YSS default (read this first)
+
+In this template, **`yss-product-lifecycle` is the default orchestrator**. Native work-units own Spec, tickets, implementation authorization, and gates.
+
+This skill is a **Matt compatibility map**. Use `/grill-with-docs`, `/to-spec`, `/to-tickets`, and `/implement` only when the user **explicitly** names them. Do not treat the idea→ship list below as the YSS default. `/implement` does not grant git commit/push. Spec drafts from `/to-spec` stay `ready-for-human` until a human approves the Spec baseline.
+
 A **flow** is a path through the skills. Most paths run along one **main flow**, and two **on-ramps** merge onto it. Everything else is standalone, or a vocabulary layer that runs underneath.
 
-## The main flow: idea → ship
+## Matt compatibility flow: idea → ship
 
 The route most work travels. You have an idea and want it built.
 
@@ -23,7 +29,7 @@ The route most work travels. You have an idea and want it built.
    - **Yes** → **`/to-spec`** (turn the thread into a spec), then **`/to-tickets`** to split it into tracer-bullet tickets, each declaring its **blocking edges**. On a local tracker that's one file per ticket under `docs/.scratch/<feature>/issues/`, worked blockers-first by hand; on a real tracker the edges become native blocking links, so any ticket whose blockers are done can be grabbed — kick off **`/implement`** per ticket, **`/clear`ing context between each one**. Each ticket is self-contained, so the last one's context is disposable.
    - **No** → **`/implement`** right here, in the same context window.
 
-   Either way, **`/implement`** builds each issue by driving **`/tdd`** internally — one red-green slice at a time — then closes out by running **`/code-review`**, a two-axis review (Standards + Spec) of the diff, before committing. Reach for **`/tdd`** on its own when you just want to build a concrete behaviour test-first without a full spec, and **`/code-review`** on its own whenever you want to review a branch or PR against a fixed point.
+   Either way, **`/implement`** builds each issue by driving **`/tdd`** internally — one red-green slice at a time — then closes out by running **`/code-review`** (Standards + Spec, plus UI fidelity when UI is in scope). Do not commit or push from `/implement`. Reach for **`/tdd`** on its own when you just want to build a concrete behaviour test-first without a full spec, and **`/code-review`** on its own whenever you want to review a branch or PR against a fixed point.
 
 ### Context hygiene
 

package/template/.claude/skills/code-review/SKILL.md

@@ -3,12 +3,13 @@ name: code-review
 description: Use when the user wants to review a branch, PR, committed candidate, uncommitted work-in-progress changes, or changes since a fixed point.
 ---
 
-Two-axis review of a pinned candidate against a fixed point:
+Review of a pinned candidate against a fixed point on two core axes, plus UI fidelity when UI is in scope:
 
 - **Standards** — does the code conform to this repo's documented coding standards?
 - **Spec** — does the code faithfully implement the originating issue / spec?
+- **UI fidelity** (only when the change has UI impact) — does the candidate match the confirmed prototype and `yss-design-system` / `yss-ui`? Type-check or claiming "already aligned" is not a pass. Invoke those skills' verification notes; do not collapse this axis into Standards or Spec.
 
-Both axes run as **parallel sub-agents** so they don't pollute each other's context, then this skill aggregates their findings.
+Standards and Spec run as **parallel sub-agents** so they don't pollute each other's context, then this skill aggregates their findings. When UI is in scope, add a separate UI fidelity pass after those two reports (do not merge it into either axis).
 
 If `docs/agents/issue-tracker.md` is missing, tell the user to run `/setup-matt-pocock-skills`; do not invoke another user-invoked skill yourself.
 
@@ -99,17 +100,18 @@ If the spec is missing, skip the Spec sub-agent and note this in the final repor
 
 ### 5. Aggregate
 
-Present the two reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. Do **not** merge or rerank findings — the two axes are deliberately separate (see _Why two axes_).
+Present the reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. If UI is in scope, add `## UI fidelity` from the separate pass. Do **not** merge or rerank findings — the axes are deliberately separate (see _Why separate axes_).
 
 For Worktree mode, recapture the candidate digest after both reports return. If it differs from `candidate_digest`, mark both reports as reviewing a **stale candidate** and return `blocked`; the caller may start a new review against a new capture, but this invocation must not aggregate findings from different bytes. Recheck the same digest again at the completion/checkpoint boundary.
 
 State the reviewed `review_mode`, fixed point, candidate digest and coverage before the two reports. End with a one-line summary: total findings per axis, and the worst issue _within each axis_ (if any). Don't pick a single winner across axes — that's the reranking the separation exists to prevent.
 
-## Why two axes
+## Why separate axes
 
 A change can pass one axis and fail the other:
 
 - Code that follows every standard but implements the wrong thing → **Standards pass, Spec fail.**
 - Code that does exactly what the issue asked but breaks the project's conventions → **Spec pass, Standards fail.**
+- Code that implements the spec but diverges from the confirmed prototype or design system → **Spec pass, UI fidelity fail.**
 
 Reporting them separately stops one axis from masking the other.

package/template/.claude/skills/diagnosing-bugs/SKILL.md

@@ -127,7 +127,7 @@ If a correct seam exists:
 4. Watch it pass.
 5. Re-run the Phase 1 feedback loop against the original (un-minimised) scenario.
 
-## Phase 6 — Cleanup + post-mortem
+## Phase 6 — Cleanup
 
 Required before declaring done:
 
@@ -135,6 +135,4 @@ Required before declaring done:
 - [ ] Regression test passes (or absence of seam is documented)
 - [ ] All `[DEBUG-...]` instrumentation removed (`grep` the prefix)
 - [ ] Throwaway prototypes deleted (or moved to a clearly-marked debug location)
-- [ ] The hypothesis that turned out correct is stated in the commit / PR message — so the next debugger learns
-
-**Then ask: what would have prevented this bug?** If the answer involves architectural change (no good test seam, tangled callers, hidden coupling) hand off to the `/improve-codebase-architecture` skill with the specifics. Make the recommendation **after** the fix is in, not before — you have more information now than when you started.
+- [ ] The hypothesis that turned out correct is stated in the commit / PR message, so the next debugger learns

package/template/.claude/skills/domain-modeling/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: domain-modeling
-description: Build and sharpen a project's domain model. Use when the user wants to pin down domain terminology or a ubiquitous language, record an architectural decision, or when another skill needs to maintain the domain model.
+description: Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a CONTEXT.md, or recording or editing an ADR.
 ---
 
 # Domain Modeling

package/template/.claude/skills/grilling/SKILL.md

@@ -7,11 +7,17 @@ Interview the user relentlessly until you reach a shared understanding. Map this
 
 Work the tree in **rounds**. The **frontier** is every decision whose prerequisites are already settled — the questions you can ask _now_ without guessing at answers you haven't heard yet. Ask the whole frontier in one round: number each question and give your recommended answer. Then wait for the user's answers before the next round.
 
-Each question should be formatted like so:
+Format a round like so:
 
 ```
 ❓ **Q1** - **<question title>**: <question body, might be multiple paragraphs, including multiple choices>
 
+➡️ <your recommended answer>
+
+---
+
+❓ **Q2** - **<question title>**: <question body, might be multiple paragraphs, including multiple choices>
+
 ➡️ <your recommended answer>
 ```
 

package/template/.claude/skills/high-fidelity-html-prototype/SKILL.md

@@ -102,5 +102,5 @@ High-fidelity HTML prototype
 - <yes/no; list blocking gaps>
 
 ### 下一步
-- <Spec calibration / return to high-fidelity prototype / return to product-design-prototype>
+- <Spec calibration / return to high-fidelity prototype / return to yss-prototype-stage>
 ```

package/template/.claude/skills/implement/SKILL.md

@@ -12,4 +12,4 @@ Run typechecking regularly, single test files regularly, and the full test suite
 
 Once done, use /code-review to review the work.
 
-Commit your work to the current branch.
+Do not commit or push. Implementation authorization does not include git commit/push. Natural language such as "do it and commit" is not structured Git authorization. Stop after review unless a structured Git authorization is already present.

package/template/.claude/skills/to-spec/SKILL.md

@@ -16,7 +16,7 @@ If the issue tracker or triage label vocabulary is missing, tell the user to run
 
 Check with the user that these seams match their expectations.
 
-3. Write the spec using the template below, then publish it to the project issue tracker. Apply the `ready-for-agent` triage label - no need for additional triage.
+3. Write the spec using the template below, then publish it to the project issue tracker. Apply the `ready-for-human` triage label. Spec drafts need a human baseline approval before they are `approved`, and before implementation tickets may become `ready-for-agent`. Do not label the Spec itself `ready-for-agent`.
 
 <spec-template>
 

package/template/.claude/skills/triage/SKILL.md

@@ -40,7 +40,7 @@ For a PR, the same states read against the attached code: `ready-for-agent` mean
 
 Every triaged issue should carry exactly one category role and one state role. If state roles conflict, flag it and ask the maintainer before doing anything else.
 
-These are canonical role names — the actual label strings used in the issue tracker may differ. The mapping should have been provided to you - run `/setup-matt-pocock-skills` if not.
+These are canonical role names. The actual label strings used in the issue tracker may differ. The mapping should have been provided to you. If not, tell the user to run `/setup-matt-pocock-skills`.
 
 State transitions: an unlabeled issue normally goes to `needs-triage` first; from there it moves to `needs-info`, `ready-for-agent`, `ready-for-human`, or `wontfix`. `needs-info` returns to `needs-triage` once the reporter replies. The maintainer can override at any time — flag transitions that look unusual and ask before proceeding.
 
@@ -73,7 +73,7 @@ Show counts and a one-line summary per item. Let the maintainer pick.
 
 3. **Verify the claim.** Before any grilling, check that the claim holds up. For a bug, reproduce it from the reporter's steps. For a PR, confirm the diff does what it claims — check it out, run the relevant tests or commands. Report what happened: confirmed (with code path), failed, or insufficient detail (a strong `needs-info` signal). A confirmed verification makes a much stronger agent brief.
 
-4. **Grill (if needed).** If the request needs fleshing out, run the `/grilling` and `/domain-modeling` skills together — grill it into shape a round of questions at a time, sharpening domain terms and updating `CONTEXT.md`/ADRs inline as decisions land.
+4. **Grill (if needed).** If the request needs fleshing out, call the Skill tool twice, for "grilling" and "domain-modeling", and grill it into shape a round of questions at a time, sharpening domain terms and updating `CONTEXT.md`/ADRs inline as decisions land.
 
 5. **Apply the outcome:**
    - `ready-for-agent` — post an agent brief comment ([AGENT-BRIEF.md](AGENT-BRIEF.md)).

package/template/.claude/skills/wait-what/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: wait-what
-description: Stop. That last message did not land — re-pitch it.
+description: "Stop. That last message did not land: re-pitch it."
 disable-model-invocation: true
 ---
 
-Wait — I don't understand where you've got to here. Re-pitch that: give me a little bit of context, talk in ASD-STE100 Simplified Technical English, and use the ubiquitous language from `CONTEXT.md`.
+Wait, I don't understand where you've got to here. Re-pitch that: give me a little bit of context, talk in ASD-STE100 Simplified Technical English, and use the ubiquitous language from `CONTEXT.md` (follow `CONTEXT-MAP.md` to the right one if the repo has more than one).

package/template/.claude/skills/wayfinder/SKILL.md

@@ -22,7 +22,7 @@ The map is a single issue on this repo's issue tracker, labelled `wayfinder:map`
 
 The map is an **index**, not a store. It lists the decisions made and points at the tickets that hold their detail; a decision lives in exactly one place — its ticket — so the map never restates it, only gists it and links.
 
-**Where the map, its child tickets, blocking, and frontier queries physically live is tracker-specific.** The issue tracker should have been provided to you — run `/setup-matt-pocock-skills` if not. Consult the tracker doc's "Wayfinding operations" section for how _this_ repo expresses them. If no tracker has been provided, default to the local-markdown tracker.
+**Where the map, its child tickets, blocking, and frontier queries physically live is tracker-specific.** The issue tracker should have been provided to you. If not, tell the user to run `/setup-matt-pocock-skills`. Consult the tracker doc's "Wayfinding operations" section for how _this_ repo expresses them. If no tracker has been provided, default to the local-markdown tracker.
 
 ### The map body
 

package/template/.claude/skills/yss-api-integration/SKILL.md

@@ -5,6 +5,8 @@ description: Guide AI to correctly use Orval-generated API clients in Vue 3 micr
 
 # API 集成 Skill
 
+目录与锁文件身份是 `yss-api-integration`；Agent 发现名与 Router 闭包键是 `api-integration`。二者指向同一技能，注册表以 alias 对齐。
+
 ## 📋 目标
 
 帮助 AI 正确使用基于 **Orval** 生成的 API 客户端：

package/template/.claude/skills/yss-application/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: yss-application
+description: Use when implementing YSS application use cases, transaction boundaries, cross-aggregate orchestration, idempotency, or application-level DTO conversion.
+---
+
+# yss-application
+
+Application 层用例编排 skill。负责协调 Domain 与 Gateway，定义事务边界和跨聚合流程，不承载核心领域规则。
+
+## 何时使用
+
+- 用户要实现 Application Service、用例编排或 `@Transactional` 边界。
+- 用户要补 App 层 MapStruct Convertor 或跨聚合协调逻辑。
+- 脚手架生成完成后进入业务实现，Router 按 `backend_impact` 加载本 skill。
+
+## 不适用
+
+- 只做领域建模时，优先 `yss-domain`。
+- 只做持久层时，优先 `yss-repository`。
+- 只做 Controller 时，优先 `yss-web-controller`。
+
+## 工作方式
+
+1. 先探测工程是新 DDD `application/domain/infrastructure/adapter` 还是 legacy `core/client/repository` profile。
+2. 确认 Use Case、Application 边界、事务边界已在批准合同中写明。
+3. 实现 AppService 时调用 Domain Service / Gateway，核心规则下沉 Domain。
+4. 涉及 POJO 样板加载 `lombok`；涉及 App 层转换加载 `mapstruct`。
+5. 详细包结构、注解、示例和 legacy 兼容说明见 `references/application-layer-guide.md`。
+
+## 产物范围
+
+- `application/.../service/*Service.java`（或 legacy `core/service`）
+- `application/.../service/impl/*ServiceImpl.java`
+- `application/.../service/convertor/*Convertor.java`（MapStruct）
+
+## 协同顺序
+
+- 领域建模：`yss-domain`
+- 持久层：`yss-repository`
+- Web 适配：`yss-web-controller`
+- DTO 契约：`yss-dto`
+
+## 阶段 7 合同
+
+- 只消费批准后的 `Slice Implementation Contract` 和当前 `work_unit`。
+- AppService 骨架可 `controlled-generation`；用例编排、事务、幂等、权限和失败行为必须 `behavior-tdd`。
+- 按 `yss-router/references/yss-skill-execution-result.md` 返回统一 `YSS Skill Execution Result`。
+- 发现新 API、权限、状态机或跨上下文影响时填入 `new_impacts` 并暂停。
+
+## 按需读取
+
+- 分层开发规范：`references/application-layer-guide.md`

package/template/.claude/skills/yss-application/agents/openai.yaml

@@ -0,0 +1,5 @@
+version: 1
+interface:
+  display_name: "YSS Application Layer"
+  short_description: "YSS Application 层用例编排、事务边界与跨聚合协调规范"
+  default_prompt: "Use $yss-application to implement the application layer for a YSS backend module."

package/template/{.codex/skills/yss-backend-scaffold-application/SKILL.md → .claude/skills/yss-application/references/application-layer-guide.md}

@@ -1,10 +1,3 @@
----
-name: yss-backend-scaffold-application
-description: Use when implementing YSS application use cases, transaction boundaries, cross-aggregate orchestration, idempotency, or application-level DTO conversion.
----
-
-# Application 层开发规范 (Application Layer Development Guide)
-
 本 Skill 约束 Application 层的用例边界。它是目标 DDD 架构规则，不等同于现有 YSS 组件仓库中所有 `core/service` 的历史实现；先探测工程布局并记录兼容 profile。
 
 ## 1. 核心职责 (Core Responsibilities)

package/template/.claude/skills/yss-ddd-scaffold-generator/SKILL.md

@@ -67,7 +67,7 @@ node scripts/generate_scaffold.mjs \
 - Harness 内多项目布局必须使用 `apps/backend/<project>/`；`apps/backend/` 只能是生成器的父容器，`app/backend/`、`app/frontend/` 及其子路径一律拒绝。
 - 不要在 skill 里硬编码用户业务字段或真实连接信息。
 - 生成后要检查依赖关系是否仍符合分层约束。
-- 生成后必须继续使用 `yss-backend-scaffold-parent` 校验工程基线，再按垂直切片加载 `yss-domain`、`yss-repository`、`yss-web-controller` 等局部技能。
+- 生成后必须继续使用 `yss-backend-scaffold-parent` 校验工程基线，再按垂直切片加载 `yss-domain`、`yss-application`、`yss-repository`、`yss-web-controller` 等行为 skill；各 skill 的 `references/*-layer-guide.md` 承载分层开发规范。
 - 当前脚手架第一阶段仅支持经过验证的 `mysql`；未提供完整模板和验证的数据库类型不得伪装成已支持。
 - 生成后的后端工程必须使用项目根目录 `./mvnw ...` 执行构建、测试、运行和 CI 验证；不得在 README、实施记录、Ticket、Review 或 Release 中默认写裸 `mvn ...`。既有仓库确实无法使用 wrapper 时，必须记录受控例外。
 - 原型确认后，`scaffold_status=required` 才能进入本 skill；本 skill 的生成边界是工程结构、POM、配置、Wrapper 和机械模板，不是业务实现。

package/template/.claude/skills/yss-ddd-scaffold-generator/references/ARCHITECTURE.md

@@ -188,7 +188,7 @@ Controller -> Service -> Gateway -> Repository -> Database
 ## 7. 参考资料
 
 - [YSS 后端开发规范](./yss-backend-scaffold-parent/SKILL.md)
-- [Domain 层开发指南](./yss-backend-scaffold-domain/SKILL.md)
-- [Application 层开发指南](./yss-backend-scaffold-application/SKILL.md)
-- [Infrastructure 层开发指南](./yss-backend-scaffold-infrastructure/SKILL.md)
-- [Web Adapter 开发指南](./yss-backend-scaffold-web/SKILL.md)
+- [Domain 层开发指南](./yss-backend-scaffold-domain/SKILL.md) → `yss-domain`
+- [Application 层开发指南](./yss-backend-scaffold-application/SKILL.md) → `yss-application`
+- [Infrastructure 层开发指南](./yss-backend-scaffold-infrastructure/SKILL.md) → `yss-repository`
+- [Web Adapter 开发指南](./yss-backend-scaffold-web/SKILL.md) → `yss-web-controller`

package/template/.claude/skills/yss-ddd-scaffold-generator/references/yss-backend-scaffold-application/SKILL.md

@@ -1,8 +1,8 @@
 ---
-name: yss-backend-scaffold-application-reference
+name: yss-application-layer-reference
 description: Use when the YSS DDD scaffold workflow reaches Application-layer implementation and needs the shared Application skill.
 ---
 
 # Application Layer Reference
 
-**REQUIRED SUB-SKILL:** Use `yss-backend-scaffold-application` as the single authoritative Application-layer implementation guide. Do not maintain a second copy under the scaffold generator.
+**REQUIRED SUB-SKILL:** Use `yss-application` as the single authoritative Application-layer implementation guide (`references/application-layer-guide.md`). Do not maintain a second copy under the scaffold generator.

package/template/.claude/skills/yss-ddd-scaffold-generator/references/yss-backend-scaffold-application/agents/openai.yaml

@@ -2,4 +2,4 @@ version: 1
 interface:
   display_name: "YSS Scaffold Application"
   short_description: "YSS 后端脚手架应用层、用例编排与 DTO 规范"
-  default_prompt: "Use $yss-backend-scaffold-application to implement the application layer for a YSS backend scaffold module."
+  default_prompt: "Use $yss-application to implement the application layer for a YSS backend scaffold module."

package/template/.claude/skills/yss-ddd-scaffold-generator/references/yss-backend-scaffold-domain/SKILL.md

@@ -1,8 +1,8 @@
 ---
-name: yss-backend-scaffold-domain-reference
+name: yss-domain-layer-reference
 description: Use when the YSS DDD scaffold workflow reaches Domain-layer implementation and needs the shared Domain skill.
 ---
 
 # Domain Layer Reference
 
-**REQUIRED SUB-SKILL:** Use `yss-backend-scaffold-domain` as the single authoritative Domain-layer implementation guide. Do not maintain a second copy under the scaffold generator.
+**REQUIRED SUB-SKILL:** Use `yss-domain` as the single authoritative Domain-layer implementation guide (`references/domain-layer-guide.md`). Do not maintain a second copy under the scaffold generator.

package/template/.claude/skills/yss-ddd-scaffold-generator/references/yss-backend-scaffold-domain/agents/openai.yaml

@@ -2,4 +2,4 @@ version: 1
 interface:
   display_name: "YSS Scaffold Domain"
   short_description: "YSS 后端脚手架领域层、聚合与规则建模实践落地规范"
-  default_prompt: "Use $yss-backend-scaffold-domain to implement the domain layer for a YSS backend scaffold module."
+  default_prompt: "Use $yss-domain to implement the domain layer for a YSS backend scaffold module."

package/template/.claude/skills/yss-ddd-scaffold-generator/references/yss-backend-scaffold-infrastructure/SKILL.md

@@ -1,8 +1,8 @@
 ---
-name: yss-backend-scaffold-infrastructure-reference
-description: Use when the YSS DDD scaffold workflow reaches Infrastructure-layer implementation and needs the shared Infrastructure skill.
+name: yss-infrastructure-layer-reference
+description: Use when the YSS DDD scaffold workflow reaches Infrastructure-layer implementation and needs the shared Repository skill.
 ---
 
 # Infrastructure Layer Reference
 
-**REQUIRED SUB-SKILL:** Use `yss-backend-scaffold-infrastructure` as the single authoritative Infrastructure-layer implementation guide. Do not maintain a second copy under the scaffold generator.
+**REQUIRED SUB-SKILL:** Use `yss-repository` as the single authoritative Infrastructure-layer implementation guide (`references/infrastructure-layer-guide.md`). Do not maintain a second copy under the scaffold generator.

package/template/.claude/skills/yss-ddd-scaffold-generator/references/yss-backend-scaffold-infrastructure/agents/openai.yaml

@@ -2,4 +2,4 @@ version: 1
 interface:
   display_name: "YSS Scaffold Infrastructure"
   short_description: "YSS 后端脚手架基础设施层与持久化实现设计落地规范"
-  default_prompt: "Use $yss-backend-scaffold-infrastructure to implement the infrastructure layer for a YSS backend scaffold module."
+  default_prompt: "Use $yss-repository to implement the infrastructure layer for a YSS backend scaffold module."

package/template/.claude/skills/yss-ddd-scaffold-generator/references/yss-backend-scaffold-web/SKILL.md

@@ -1,8 +1,8 @@
 ---
-name: yss-backend-scaffold-web-reference
-description: Use when the YSS DDD scaffold workflow reaches Web-layer implementation and needs the shared Web skill.
+name: yss-web-layer-reference
+description: Use when the YSS DDD scaffold workflow reaches Web Adapter implementation and needs the shared Web Controller skill.
 ---
 
-# Web Layer Reference
+# Web Adapter Layer Reference
 
-**REQUIRED SUB-SKILL:** Use `yss-backend-scaffold-web` as the single authoritative Web-layer implementation guide. Do not maintain a second copy under the scaffold generator.
+**REQUIRED SUB-SKILL:** Use `yss-web-controller` as the single authoritative Web-layer implementation guide (`references/web-adapter-layer-guide.md`). Do not maintain a second copy under the scaffold generator.

package/template/.claude/skills/yss-ddd-scaffold-generator/references/yss-backend-scaffold-web/agents/openai.yaml

@@ -2,4 +2,4 @@ version: 1
 interface:
   display_name: "YSS Scaffold Web"
   short_description: "YSS 后端脚手架 Web 层、DTO 与控制器规范"
-  default_prompt: "Use $yss-backend-scaffold-web to implement the web adapter layer for a YSS backend scaffold module."
+  default_prompt: "Use $yss-web-controller to implement the web adapter layer for a YSS backend scaffold module."

package/template/.claude/skills/yss-domain/SKILL.md

@@ -51,10 +51,15 @@ description: 用于构建或重构 YSS 领域层代码。当用户要求设计
 
 ## 协同顺序
 
+- 需要用例编排时，再接 `yss-application`
 - 需要持久层时，再接 `yss-repository`
 - 需要 Web 层时，再接 `yss-web-controller`
 - 需要完整工程时，先 `yss-ddd-scaffold-generator`
 
+## 分层开发规范
+
+脚手架生成或进入 Domain 实现前，必须加载 `references/domain-layer-guide.md`：其中定义 DTO/Gateway/Domain Service 包结构、命名、校验与示例，与本 skill 的建模约束一并生效。
+
 ## 阶段 7 合同
 
 - 只消费生命周期已批准的 `Slice Implementation Contract` 和当前 `work_unit`；不得扩大 `allowed_write_paths`。

package/template/{.agents/skills/yss-backend-scaffold-domain/SKILL.md → .claude/skills/yss-domain/references/domain-layer-guide.md}

@@ -1,10 +1,3 @@
----
-name: "yss-backend-scaffold-domain"
-description: "YSS 管理服务领域层的脚手架和最佳实践。在实现业务逻辑、定义数据网关或创建领域模型时调用。"
----
-
-# Domain 层开发规范 (Domain Layer Development Guide)
-
 本 Skill 提供了 YSS 数据质量管理服务 **Domain (领域层)** 的开发规范。Domain 层是系统的核心，包含业务逻辑、领域模型和接口定义。
 
 ## 1. 核心职责 (Core Responsibilities)

package/template/.claude/skills/yss-microapp-commit/SKILL.md

@@ -5,6 +5,8 @@ description: Use when committing or analyzing changes in a YSS micro-frontend ap
 
 # 微应用提交规范 Skill
 
+目录与锁文件身份是 `yss-microapp-commit`；Agent 发现名是 `microapp-commit`。二者指向同一技能，注册表以 alias 对齐。
+
 ## 📋 目标
 
 帮助 AI 为微应用项目生成符合 **Conventional Commits** 规范的 Git 提交信息，支持智能分析变更内容并处理复杂提交场景。

package/template/.claude/skills/yss-product-lifecycle/SKILL.md

@@ -1,97 +1,49 @@
 ---
 name: yss-product-lifecycle
-description: Use when starting, continuing, auditing, or routing a YSS product/module/change across Discovery, Spec, design, OpenAPI, architecture, Tickets, implementation, review, release, or retrospective; or when lifecycle assets, gates, Matt flows, YSS skills, or readiness are unclear.
+description: 编排 YSS 产品或模块从机会调研到 Spec、原型、技术契约、垂直切片实现、审查、发布和复盘；当阶段、产物、门禁或 YSS skill 不清晰时使用。
 ---
 
 # YSS Product Lifecycle
 
-YSS 产品研发的全生命周期主控编排器。它决定阶段、条件门禁、状态和工作顺序；Matt skills 提供通用工作流，YSS skills 提供专项实现规则。编排器持续主控，但不得绕过专项 skill 直接规定业务实现。
-
-## 启动
-
-1. 读取根目录 `yss-project.yaml`；非法或缺失时停止并进入迁移检查。
-2. 读取 `CONTEXT.md`、相关 ADR、父 Ticket/checkpoint、当前资产与 tracker 配置。
-3. `template-source` 只走模板维护流程；不得生成具体产品 Spec、原型、OpenAPI 或切片 Ticket。
-4. `project-instance` 以 `docs/process/lifecycle-registry.yaml`、由其派生的 `docs/process/lifecycle-artifact-map.md` 和 `docs/process/harness-process-tailoring.md` 为阶段、门禁和裁剪事实来源。
-
-YSS 仓库以本 skill 为直接入口，不机械嵌套调用 `ask-matt`。`ask-matt` 仅在用户显式调用时作为 Matt 通用导航：不得写生命周期资产或改变门禁/Ticket 状态，并须在任何写入前回交本编排器。不要修改 Matt skills 来复制 YSS 规则。
-
-## 选择模式
-
-| 请求 | 模式 | 副作用 |
-|---|---|---|
-| “该怎么做/下一步” | `route` | 只读 |
-| “推进/完成” | `orchestrate` | 在授权范围内有界推进 |
-| “继续之前工作” | `resume` | 先重建并核验状态，再有界推进 |
-| “是否可开发/合并/发布” | `audit` | 严格只读，不顺带修复 |
-
-用户显式模式优先；无法判断时用 `route`。执行协议见 [orchestration.md](references/orchestration.md)。
-
-## 核心规则
-
-- 保留生命周期注册表定义的主阶段；其中条件门禁全部按影响面强制。命中项必须达到 `approved`，未命中项记录 `not-applicable` 和原因；产物、工作单元和证据不得被统称为门禁。
-- 安全 / 权限不设独立生命周期资料、专属门禁或 `not-applicable` 记录。只有需求或冻结资产明确要求改变认证、授权、租户隔离、敏感数据或合规行为时，才把该行为写入普通 Spec、API、架构、验收和测试 seam，并仅按实际 UI、API、Backend、Data、High-risk 影响触发既有门禁；普通 action 注册、沿用认证中间件、未变化的 `401` / `403`、一般字段、SQL / DDL / 迁移和上传 / 下载本身不触发安全 / 权限流程。
-- 有效 `yss-project.yaml` 存在时，Matt user-invoked skill 保持显式用户入口。生命周期可以准备和验收其结果，但不得自动调用它们或代替其创建正式资产；最终入口、仓库身份和模式裁决归本编排器。
-- `template-source` 命中产品 flow 时必须返回 `blocked`（`template-source-product-artifact-forbidden`），不得继续到产品资产或 Ticket 生成。
-- `template-source` 迁移共享工具或验证器前，先区分维护侧构建资产、实例分发面和实例运行资产；冻结公开入口、运行时前提、旧实现处置和跨仓消费者契约后，才可改写实现。
-- 替换自身验证门禁时，不得只用候选门禁自证；必须保留独立 baseline oracle 或同一 fixture 的双跑证据。涉及共享运行资产时，只有生成/同步实例、失败回滚和跨仓消费者的 fresh evidence 齐备，才能声明生态完成或可发布。
-- 文件存在不等于就绪。按内容、审查结论和上游新鲜度评估资产。
-- 父 Ticket/checkpoint 的状态只是索引；与真实资产冲突时，以权威资产为准并修复索引。
-- 上游变化按依赖图精准传播 `stale`；不要无条件重跑完整阶段。
-- Matt 五态保持原义。只有解除阻塞、门禁通过且可直接实现的垂直切片才能使用 `ready-for-agent`。
-- 用户显式运行 `to-spec` 后，生命周期必须把其 `ready-for-agent` 发布提示归一化为 Spec `ready-for-human`；不得把 Spec 初稿当作可直接实现的 Ticket。
-- 用户显式运行 `to-tickets` 后，新建垂直切片统一写为 `ready-for-human`；只有本编排器复算完整 `ready-for-agent` 公式后才能提升，通用默认标签不得提前覆盖生命周期状态。
-- `orchestrate`/`resume` 连续执行安全的准备、校验和 model-invoked 工作单元，直到需要显式用户入口、人工门禁、真实阻塞、新授权、实现/发布裁决或专项失败。
-- 进入实现准备后继续主控，通过 `yss-router`、`code-review` 和 YSS 专项 skills 执行允许的 model-invoked 工作单元；`implement` 本身仍须由用户显式启动，并在其自身流程内按需使用 `tdd`，结果回交后再做独立审查和 fresh verification。只有工作单元真实触碰当前用户、审计、加密或明确的权限业务行为时，才增加 `yss-userinfo`、`yss-audit-log`、`yss-security-algorithm` 等专项依赖。
-- 原型确认 → 后端脚手架：命中产品设计影响时，先按 `yss-prototype-stage` 形成交互说明、独立 Prototype Review、高保真 HTML、AntD CLI 与浏览器验证、用户确认；只有 `gate.prototype-reviewed`、`gate.prototype-verified` 和 `gate.user-confirmation` 均满足时，才能进入下游。若 backend `scaffold_status=required`，随后先完成工程基线，由 `yss-router` 编译脚手架受控生成工作单元合同，经生命周期编排器批准并持久化后，才使用 `yss-ddd-scaffold-generator` 生成后端骨架；随后由 `yss-backend-scaffold-parent` 校验并重新进入 `yss-router`，不得先写业务代码。
-- 所有后续生成的后端代码都必须消费生命周期批准、已持久化且版本当前的 Slice Implementation Contract，绑定最小 YSS skill 闭包、允许写路径、证据文件和 YSS Skill Execution Result；没有这些证据时必须阻断。
-- Harness 内承载运行时代码时，项目路径策略固定为 `apps/backend/<project>/` 和 `apps/frontend/<project>/`；`apps/backend/`、`apps/frontend/` 仅是项目容器，`app/backend/`、`app/frontend/` 及其子路径禁止生成。外部实现仓库不强制使用该目录，但必须登记真实项目根路径并写入合同。
-- Setup readiness 每个任务只评估一次并在本轮缓存；只有 tracker、主远端、真实标签或配置变化时重查。
-- Ticket tracker 支持 `local-markdown`、GitHub 和 GitLab；模板默认 `local-markdown`，以 `docs/.scratch/<feature>/` 完整功能包为主载体。Git remote 只代表代码托管，不能覆盖已持久化的 tracker 选择；Local 主 tracker 不要求远程 Ticket。根 `.scratch/` 与 `docs/requirements/tickets/` 只作为旧路径迁移来源。
-- 小改动和中等变更允许同一独立执行者完成 Review 与 fresh verification；该执行者不得是实现者。新模块、高风险或职责冲突时拆分 Reviewer 与 Verifier。
-- 进入 `code-review` 前必须持久化或明确传入 `review_mode`、`review_base_ref`、`candidate_snapshot_ref`、`candidate_digest` 和完整候选引用；`worktree` 模式必须一次捕获 committed、staged、unstaged、untracked，并让两个 Reviewer 消费同一快照，不能用只看 `HEAD` 或实时变化的 diff 宣称已审查。候选 manifest 和 `yss-worktree-candidate-v1` 不可变摘要流以 `orchestration-contract.yaml.review_input` 为唯一机器契约。
-- 实现授权不包含 Git 授权。只有用户分别明确给出值为 `true` 的 `commit_authorized` / `push_authorized`、非空 scope 和对应 `*_authorization_ref` 时才执行动作；缺失时只记录 checkpoint 判断，不得把 `implement`、`orchestrate`、当前分支或负责人要求解释成隐含授权。
-- “然后 commit”“做完提交”等自然语言意向不构成上述结构化 Git 授权，不能据此预授权或事后补齐 scope / authorization ref。
-- 连续自动推进期间累积 Ticket/Git 证据，在人工暂停、handoff、进入实现、合并或发布边界集中 checkpoint；不为每个连续经过的概念阶段重复写同类记录。
-- 跨线程、仓库、原型分支或上下文边界时使用 `handoff` 或等价记录。
-- 在 Matt 阶段边界（phase boundary）先按 `Continue → /clear → /handoff → subagent → /compact` 判断上下文动作；只在 checkpoint 记录可选 `phase_boundary` 证据，不新增生命周期状态。
-- `to-questionnaire` 进入结构化 `external-input-required` 暂停；回答回流后必须重新分类影响面并更新权威资产，不能直接恢复下游实现。
-- `wait-what` 只重新解释当前结论，不改变阶段、门禁、Ticket 或 `ready-for-agent` 状态；Agent 无法替代的人工步骤使用显式人工 checkpoint，秘密值不得进入持久化输出。
-- Matt `prototype` 是保留在 `prototype/<name>` 分支的单文件可分享 HTML 主来源；YSS 高保真 HTML 原型仍必须经过 Prototype Review、AntD CLI、浏览器验证和用户确认，两者不得互相替代。
-- 新工作单元返回 `Workflow Execution Result`；旧 `Matt Skill Result` 仅可兼容读取后归一化。`drift`、`new_impacts`、`violation`、`stale_candidates`、缺失证据或不完整结果不得推进为 `completed`。
-
-### 原型完成后的后端脚手架与代码生成边界
-
-`prototype_confirmation` 是产品设计门禁，不是业务实现授权。后端新工程的顺序固定为：工程基线 → `yss-router` 编译脚手架合同 draft → 生命周期批准/持久化 → `yss-ddd-scaffold-generator` → `yss-backend-scaffold-parent` → `yss-router` 合同重编译 → 垂直切片实现。
-
-- `scaffold_status=required` 时，脚手架工作单元使用 `controlled-generation`，记录项目名、基础包名、输出目录、数据库类型、预期文件和实际 `./mvnw validate`、`./mvnw test`、`./mvnw package` 结果，并返回 YSS Skill Execution Result。
-- 脚手架合同必须结构化记录 `contract_id`、`contract_version`、`slice_id`、Router draft 引用、生命周期批准引用、持久化引用、当前版本、实现仓库、允许写路径、预期证据文件和验证命令；生命周期批准记录至少包含 `approval_ref`、`approver`、`persisted_ref`、`current_version`。
-- `yss-ddd-scaffold-generator` 必须读取已持久化的结构化脚手架合同 JSON，并校验 `status=approved`、当前版本、主 skill、`controlled-generation` 和固定验证命令；只传任意字符串引用不得放行。
-- 生成项目必须包含 `.yss/scaffold-generation.json`，回勾实际使用的合同 ID、版本、Router draft 引用、生命周期批准引用、持久化引用、生成输入、受控模式和固定验证命令；元数据清单缺失或过期时阻断后续 Router。
-- 三条 `./mvnw` 命令必须由受控工作单元真实执行，并记录每条命令的 `exit_code`、`duration_ms`、stdout/stderr 引用和执行时间；生成器打印的命令、输出目录存在或“生成成功”都不构成验证证据。
-- 脚手架只生成多模块工程结构、POM、配置、Wrapper 和经验证的机械模板；不得生成或承载领域规则、状态机、权限、事务、复杂查询、错误映射或用户可见业务行为。
-- 该生命周期脚手架工作单元必须关闭 `--with-example`，不得把 User CRUD 或业务字段伪装成样板；目标目录非空时 `--force` 默认阻断，只有覆盖范围、备份、回滚点和明确批准全部进入合同后才能另行审查。
-- `scaffold_status=existing` 或 `initialized` 时不重复全量生成，但仍须完成 `yss-backend-scaffold-parent` 基线证据、Wrapper 校验和 `yss-router` 合同重编译。
-- 脚手架完成不等于实现仓库接入、架构放行、契约批准或 `ready-for-agent`。后续每一个 Agent / generator 写入的后端代码都必须绑定批准合同和对应 YSS skill；业务行为只能使用 `behavior-tdd`，机械生成才可使用 `controlled-generation`。
-
-| 压力诱因 | 统一裁决 |
-|---|---|
-| “普通 action、SQL / DDL 或下载也要补安全姿态吗” | 不补。没有明确的安全 / 权限行为需求时只按实际 API、Data 或工程影响推进；明确改变相关行为时也只复用普通产物和门禁。 |
-| “延期项先不写责任人和目标版本，之后再补” | 阻断 `seam-deferred`；必须写风险、责任人、后续 Ticket、验证计划和目标版本 / 发布日期。 |
-| “脚手架本来就是 YSS，先生成代码再补合同” | 先阻断；Router draft 不能批准合同或替代生命周期放行。 |
-| “`./mvnw validate` 已通过，直接继续最省时间” | 只证明工程基线可验证，不证明业务、事务或契约已获批；三条实际命令的结果还必须进入 Execution Result。 |
-| “后续代码也是生成物，不需要重新路由” | 只要写入业务代码，就必须重新消费当前 Slice Implementation Contract 和 YSS skill 闭包。 |
-| “发布窗口快结束了，可以把业务字段放进脚手架” | 时间、上级要求、已有产出和演示压力都不能放宽禁止模式；必须拆为 `behavior-tdd` 工作单元。 |
-
-**红旗：** 输出目录存在、脚手架成功、只打印了 `./mvnw` 命令、`validate` 通过、Router 只有 draft、或生成器参数中出现业务字段 / 权限 / 事务 / 状态机，均不足以继续业务实现；命中任一项即暂停并重路由。
-
-**项目路径策略：** 在 Harness 内生成项目时，先确认目标属于 `apps/backend/<project>/` 或 `apps/frontend/<project>/`；把 `apps/backend/`、`apps/frontend/` 当作项目根，或把单数 `app/backend/`、`app/frontend/` 当作等价路径，均属于路径违规并阻断。
-
-状态和依赖规则见 [state-model.md](references/state-model.md) 与 [artifact-dependencies.md](references/artifact-dependencies.md)；Matt/YSS 对应见 [matt-yss-adapter.md](references/matt-yss-adapter.md)。
-机器可执行的模式、readiness、Wayfinder、影响传播和回流字段见 [orchestration-contract.yaml](references/orchestration-contract.yaml)。说明文档与该契约冲突时必须暂停并修订权威资产，不得猜测。
-
-## 输出
-
-始终输出：模式、当前阶段、影响面、证据、资产/门禁状态、阻塞项、本轮动作、下一工作单元、暂停或继续理由、Ticket 同步和 Git checkpoint 判断；追加 `Workflow Execution Result`，并注明 workflow reference 或实际 model-invoked skill。
-
-暂停时只提出一个具体人工决策，并给出推荐答案与确认后的恢复动作。`audit`/`route` 不得写文件、Ticket、标签或 Git。
+这是生命周期主控 skill：负责识别阶段、判定影响面、检查产物与门禁、选择下一工作单元并验收结果。业务实现必须交给对应的 Matt/YSS 专项 skill；本 skill 不替代它们。
+
+## 入口与边界
+
+1. 先读取 `yss-project.yaml`、`CONTEXT.md`、相关 ADR、父 Ticket/checkpoint 和当前资产。
+2. `repository_mode=template-source` 只走模板维护流程；命中产品流程时返回 `blocked: template-source-product-artifact-forbidden`，不得生成产品 Spec、原型、OpenAPI 或切片 Ticket。
+3. `repository_mode=project-instance` 以 `docs/process/lifecycle-registry.yaml`、`harness-process-tailoring.md` 和本目录 references 为唯一阶段、门禁和裁剪事实源。
+4. 模式：`route` 只读规划；`orchestrate` 有界推进；`resume` 重建后推进；`audit` 严格只读。未明确时使用 `route`。
+
+Matt 的 `grill-with-docs`、`to-spec`、`to-tickets`、`implement` 等保留为显式兼容入口；默认路径是本 skill 持有的原生工作单元，由本编排器创建正式资产、维护状态并在四类人工门禁暂停。兼容入口不得自动调用它们或代替其创建正式资产；Matt 只导航，不得写生命周期资产或改变门禁/Ticket 状态；任何写入前回交本编排器。
+
+## 不可裁剪的主链
+
+机会调研/需求分析 → Spec/功能架构 → 产品设计与原型 → 技术分析（系统、数据、API、工程基线）→ Ticket 正式化 → 垂直切片实现（前后端 TDD）→ 独立 code review 与 fresh verification → 发布/复盘。
+
+裁剪只允许将未命中的条件门禁标记为 `not-applicable` 并写原因；不得删除主阶段、已命中的门禁或必需产物。阶段是否完成取决于“内容 + 审查结论 + 上游新鲜度 + 可读证据”，文件存在不算通过。
+
+## 阶段路由与技能
+
+| 阶段 | 必需产物/门禁 | 工作单元与技能 | 通过条件 |
+|---|---|---|---|
+| 入口分诊 | 身份、影响面、最近可信阶段 | `yss-product-lifecycle` | `yss-project.yaml` 合法且影响面可解释 |
+| 机会调研/需求分析 | Discovery、用户/MVP/非目标/成功标准、测试 seam | `work-unit.discovery-opportunity` + `work-unit.discovery-requirements`；市场/竞品事实用 `competitive-intelligence`，技术/标准事实用 `research`；`grill-with-docs` 为兼容入口 | 未决事实已 research 或 handoff，用户确认，无 runnable blocker |
+| Spec/功能架构 | Spec、产品总体设计、功能架构；必要时 Spec Delta | 原生 `work-unit.spec-synthesis`；`to-spec` 为兼容入口 | 初稿先为 `ready-for-human`；只有 Spec baseline 人工批准后资产才为 `approved` 并进入下游 |
+| 原型设计 | 交互说明、低保真、状态矩阵、高保真 HTML、评审记录 | `yss-design-system` → `yss-prototype-stage` → Codex `product-design:index`（非 Codex 交付等价合同） | `gate.prototype-reviewed`、`gate.prototype-verified`、`gate.user-confirmation` 均有证据 |
+| 技术分析 | OpenAPI Draft/Freeze、数据架构、工程基线、架构审查 | `yss-openapi-governance` / `yss-openapi-draft-review`、`codebase-design`、`implementation-repo-onboarding`、`yss-router` | API/架构契约冻结；无 API 影响有明确记录；脚手架策略满足 |
+| Ticket 正式化 | 功能父 Ticket、垂直切片、Slice Implementation Contract | 原生 `work-unit.ticket-decomposition`；`to-tickets` 为兼容入口；生命周期复算 | 依赖、验收、测试 seam 可执行；合同已批准、持久化且为当前版本 |
+| 技术实现 | 前端/后端代码、TDD 证据、YSS Skill Execution Result | 原生 `work-unit.slice-implementation`；`implement` 为兼容入口；前端按 `yss-ui` + `yss-page-module-development`，后端按 `yss-router` 最小闭包，业务行为统一 `tdd` | 只写允许路径；业务行为用 `behavior-tdd`；UI 影响必须有还原计划 |
+| Review/验证 | 不可变候选快照、review 结论、fresh verification | `code-review`（独立于实现者）；UI 影响追加 `yss-ui` + `yss-design-system` 的 UI fidelity 轴 | findings 已处理；同一候选快照通过全部审查轴与验证 |
+| 发布/复盘 | 发布/回滚证据、复盘记录 | 生命周期自有工作单元 | fresh verification、独立审查和人工发布裁决齐全 |
+
+## 前端实现还原硬检查
+
+原型通过不等于前端实现通过。`ready-for-agent` 前先产生 `frontend_implementation_plan`（原型/Spec、路由与页面清单、桌面/窄屏验收用例、加载/空态/错误/权限/关键交互状态、拟执行的 `pnpm` 命令）；实现完成、发布前再产生 `frontend_implementation_verification`，补齐截图或视觉回归、console warning、命令退出码、未覆盖差异与责任人。差异未解释、截图缺失、只做 type-check 或只声称“已对齐”均为 `blocked`；发现新 API、状态或视觉行为时返回 `new_impacts`/`drift` 并重新路由。优先使用 `yss-ui/references/verification.md` 的分层验证和既有 `pnpm` scripts。
+
+## 结果与暂停
+
+每个工作单元必须返回 `Workflow Execution Result`（workflow reference、skill、changed files、evidence refs、actual verification、deferred seams、drift/new impacts）。缺少可读证据、`stale`、`violation`、`drift`、`new_impacts` 或阻塞信号时不得标记 completed。实现授权不包含 Git commit/push 授权；“做完提交”等自然语言意向不构成上述结构化 Git 授权。
+
+输出固定包含：模式、当前阶段、影响面、资产/门禁状态、证据、阻塞项、本轮动作、下一工作单元、暂停/继续理由、Ticket 同步和 Git checkpoint 判断。暂停时只提出一个具体人工决策，并给出推荐答案与恢复动作。
+
+详细执行循环、readiness、脚手架（包括 `controlled-generation`）、审查快照、状态传播和 Matt 边界见 [orchestration.md](references/orchestration.md)、[orchestration-contract.yaml](references/orchestration-contract.yaml)、[artifact-dependencies.md](references/artifact-dependencies.md) 和 [state-model.md](references/state-model.md)。