create-yss-spec 3.5.6 → 3.5.8

package/template/.pi/skills/yss-userinfo/SKILL.md

@@ -5,52 +5,46 @@ description: "接入或排查 YSS CurrentUserProvider、已认证 SecurityContex
 
 # yss-userinfo
 
-Use this skill for YSS 用户信息组件. Keep implementation grounded in the local project and resolvable YSS backend component source.
+处理已认证当前用户、受信网关适配、自定义 `CurrentUserProvider` 和后台空上下文；身份来源须符合当前平台契约。
 
-中文说明：本技能用于 YSS 用户信息组件。执行时优先读取源码索引，避免凭记忆猜类名、配置项或接入方式。
+## 平台与源码门禁
 
-## Source Index First
+接入、修改、代码生成或提供精确类名/配置前，必须读取并执行 [共享平台与源码门禁](../yss-skill-source-index-refresh/references/backend-component-platform-compatibility.md)，以 `--skill yss-userinfo` 校验批准的平台线及匹配源码根。缺失、错配或漂移返回 `blocked`；不跨代回退，不在业务实现中升级、降级或替换组件。只读分诊可继续，但须标注未完成源码核验，不能据此宣称跨 Boot/JDK 兼容。
 
-- Backend source location is environment-specific; resolve it with `yss-skill-source-index-refresh/references/source-location.md`.
-- Generated index: `references/source-index.md`
-- Component path hints: `yss-microservice-components/yss-component-userinfo-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.
+按 [源码定位策略](../yss-skill-source-index-refresh/references/source-location.md) 确认真实位置，再从 [平台索引](references/source-index.md) 定位当前任务需要的源码。`yss-microservice-components/yss-component-userinfo-starter` 仅是模块路径提示。
 
-## Workflow
+## 工作流
 
 1. 先按已批准平台线读取对应索引；以下当前行为针对 `boot3-java17`，Boot 2 旧工程只按其独立索引做只读分诊和迁移。
-2. Identify whether the task is authenticated current-user lookup, an explicitly trusted gateway adapter, a custom `CurrentUserProvider`, or non-REST/background fallback behavior.
-3. Read `references/source-index.md`, then inspect `CurrentUserProvider`, `SecurityContextCurrentUserProvider`, `TrustedGatewayHeaderCurrentUserProvider`, `AuthUserInfoUtil`, `DmUser`, and `DmUserDetails`.
+2. 区分已认证当前用户、显式受信网关、自定义 `CurrentUserProvider` 与非 REST/后台 fallback。
+3. 按所选任务核验 `CurrentUserProvider`、对应 provider、兼容 facade `AuthUserInfoUtil` 及 `DmUser` / `DmUserDetails`，不无条件读取所有实现。
 4. 默认使用 `SecurityContextCurrentUserProvider`，只消费 Spring Security 已认证且非 anonymous 的 `Authentication`。JWT 的 signature、issuer、audience、expiry 与算法校验必须在资源服务器认证链完成。
 5. `AuthUserInfoUtil` 是由 `CurrentUserProvider` 驱动的兼容 facade；业务代码可继续调用 `userInfo()`、`userName()`、`userCode()` 或 `currentUserJson()`，但不得自行解析 Header、JWT payload 或 Redis 身份缓存。
 6. 只有显式启用 `yss.userinfo.trusted-gateway.enabled` 且配置非空 `trusted-proxies` 时，才启用 `TrustedGatewayHeaderCurrentUserProvider`；它只接受 remote address 在 allow-list 中的请求，并且 SecurityContext 结果优先。
-7. For scheduled/background tasks, an empty provider result causes the compatibility facade to return the distinct `system` fallback; do not represent it as an authenticated system principal.
-
-## Source-Backed Notes
+7. 定时/后台任务的 provider 为空时，兼容 facade 返回独立的 `system` fallback；它不是已认证 system principal。
 
-- `SecurityContextCurrentUserProvider` supports a `UserInfo` principal and an authenticated `OAuth2AuthenticatedPrincipal`; claim mapping happens only after authentication.
-- Trusted gateway header names are `X-Username`, `X-Usercode`, and `X-LoginDisplayName`; the adapter requires a trusted proxy allow-list and a nonblank username.
-- `UserInfoAutoConfiguration` installs SecurityContext as the default and composes the optional gateway provider behind it. A project-supplied `CurrentUserProvider` remains the explicit extension seam.
-- The Boot 3 component does not parse an unverified Bearer payload and does not use Redis as an authentication fallback. Cache behavior is outside this identity provider contract.
+## 平台行为核验
 
-## Checklist
+- `SecurityContextCurrentUserProvider` 支持 `UserInfo` principal 与已认证的 `OAuth2AuthenticatedPrincipal`；claim 映射在认证后进行。
+- 受信网关 Header 为 `X-Username`、`X-Usercode` 和 `X-LoginDisplayName`；适配器要求可信代理 allow-list 与非空 username。
+- `UserInfoAutoConfiguration` 默认使用 SecurityContext，再组合可选网关 provider；工程自定义 `CurrentUserProvider` 是显式扩展 seam。
+- Boot 3 不解析未验证 Bearer payload，不以 Redis 作为认证 fallback；缓存行为不属于此身份 provider 合同。
 
-- Required dependency or starter module is present.
-- Request context exists before relying on servlet headers.
-- Spring Security has authenticated the request before the provider reads the principal.
-- When trusted gateway mode is enabled, at least one proxy address is allow-listed and untrusted remote addresses are rejected.
-- Business code does not duplicate JWT or header parsing logic.
-- SecurityContext/gateway/background precedence and empty-result behavior are covered by tests; `system` fallback is distinguished from an authenticated system user.
-- User info propagation is tested for REST calls and async/background execution separately.
+## 验收
 
-## Do Not
+- 核验所需依赖或 starter 已进入实际工程。
+- 使用 Servlet Header 前核验 request context 存在。
+- Provider 读取 principal 前，Spring Security 已完成请求认证。
+- 受信网关启用时，至少一个代理地址进入 allow-list，且拒绝不可信 remote address。
+- 业务代码不重复 JWT 或 Header 解析。
+- 测试覆盖 SecurityContext/网关/后台的优先级与空结果，区分 `system` fallback 和已认证 system 用户。
+- REST 与异步/后台执行分别验证用户信息传播。
 
-- 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 treat raw `Authorization` payloads or gateway headers as authenticated identity.
-- Do not broaden the task into unrelated YSS components unless the user asks.
-
-## 平台与源码门禁
+## 修改边界
 
-接入、修改、代码生成或给出精确类名/配置前，读取 [后端组件平台与源码门禁](../yss-skill-source-index-refresh/references/backend-component-platform-compatibility.md)，从批准的 `platform_configuration.component_platform_line` 选择 `source-index.boot2-java8.md` 或 `source-index.boot3-java17.md`，并以 `--skill yss-userinfo --platform-line <line> --source-root <matching-root>` 运行统一 freshness 校验。平台线与源码根不匹配、组件 tree 不一致、组件子树 dirty、索引缺少平台信号，或 Manifest / 组件 GAV 缺少 verified 兼容证据时返回 `blocked`；不得回退另一代索引，也不在业务实现中升级、降级或替换 YSS 组件。既有工程只读分诊可继续，但不得据此宣称跨 Boot/JDK 兼容。
+- 类名和配置 key 先核验当前索引与源码，不凭记忆补造。
+- 使用组件已有扩展 seam，不以业务本地框架代码替换。
+- 原始 `Authorization` payload 与网关 Header 不能直接作为已认证身份。
+- 保持当前组件任务范围；扩展到其他组件须有用户要求或重新路由依据。

package/template/.pi/skills/yss-validation/SKILL.md

@@ -5,52 +5,46 @@ description: "接入或排查 YSS Bean Validation、校验消息与校验错误
 
 # yss-validation
 
-Use this skill for YSS 校验组件. Keep implementation grounded in the local project and resolvable YSS backend component source.
+处理 YSS Bean Validation 注解、消息资源和校验失败映射；先区分 DTO 校验与当前不可用的历史 EL/parser 请求。
 
-中文说明：本技能用于 YSS 校验组件。执行时优先读取源码索引，避免凭记忆猜类名、配置项或接入方式。
+## 平台与源码门禁
 
-## Source Index First
+接入、修改、代码生成或提供精确类名/配置前，必须读取并执行 [共享平台与源码门禁](../yss-skill-source-index-refresh/references/backend-component-platform-compatibility.md)，以 `--skill yss-validation` 校验批准的平台线及匹配源码根。缺失、错配或漂移返回 `blocked`；不跨代回退，不在业务实现中升级、降级或替换组件。只读分诊可继续，但须标注未完成源码核验，不能据此宣称跨 Boot/JDK 兼容。
 
-- Backend source location is environment-specific; resolve it with `yss-skill-source-index-refresh/references/source-location.md`.
-- Generated index: `references/source-index.md`
-- Component path hints: `yss-microservice-components/yss-component-validation-jsr303`
+## 源码定位
 
-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.
+按 [源码定位策略](../yss-skill-source-index-refresh/references/source-location.md) 确认真实位置，再从 [平台索引](references/source-index.md) 定位当前任务需要的源码。`yss-microservice-components/yss-component-validation-jsr303` 仅是模块路径提示。
 
-## Workflow
+## 工作流
 
-1. Identify whether the task is JSR-303 annotation validation or an expression/EL parser request.
-2. Select the approved platform index and inspect the actual POM, validation message resources, consuming Controller annotations and matching exception Advice. The current module README is empty; do not treat reading it as prerequisite evidence.
+1. 区分 JSR-303 注解校验与表达式/EL parser 请求。
+2. 从批准平台索引核验实际 POM、校验消息资源、消费 Controller 注解及匹配的异常 Advice。当前模块 README 为空，不作为前置证据。
 3. 当前组件仓不存在历史 `yss-component-validation-engine-parent`；表达式、LiteFlow EL 或 `ExpressParserFactory` 请求返回 `blocked`，先确认真实组件来源和生命周期影响，不以旧索引或通用知识生成实现。
-4. Keep validation failures mapped to the service/API error contract used by the local project.
+4. 校验失败映射保持当前工程的 service/API 错误合同。
 5. 消费工程基线选择 javax/jakarta，不自行升级 Java/Boot。MVC 输入校验放在 server/client，业务不变量由 service/core 验证；不生成 DDD Domain。HTTP 失败形态由 server 的合同测试验证。
 
-## Capability Split
+## 能力边界
 
-- `validation-jsr303`: currently a dependency/message-resource aggregation module; it has no local Validator, Advice, or auto-configuration Java implementation.
+- `validation-jsr303` 当前聚合依赖与消息资源，没有本地 Validator、Advice 或自动配置 Java 实现。
 - 历史 `validation-el-parser` / `ExpressParserFactory`：当前源码根不存在，状态为 `blocked`，不得作为可用 capability。
 
-## Troubleshooting Notes
-
-- If an EL/parser capability is requested, stop and resolve its actual repository/module instead of assuming the removed path.
-- If validation annotations do not fire, check controller/service validation annotations and Spring validation starter wiring before editing parser code.
-- The component README is empty; use the POM, message resources, Controller annotations, and `GlobalExceptionAdvice` as current evidence.
-- If behavior differs between expression validation and DTO validation, route the problem to the correct submodule first.
+## 排障
 
-## Checklist
+- EL/parser 请求停止实施并确认真实仓库/模块，不假设已移除路径仍存在。
+- 注解未生效时先检查 Controller/service 校验注解和 Spring validation starter 装配，不先改 parser 代码。
+- 当前证据使用 POM、消息资源、Controller 注解和 `GlobalExceptionAdvice`。
+- 表达式校验与 DTO 校验行为不一致时先确认对应模块，再路由问题。
 
-- Required dependency or starter module is present.
-- JSR-303 and unavailable expression-validation requests are not mixed in the same fix.
-- No class, parser or configuration is attributed to the absent historical module.
-- Validation errors preserve readable messages for Chinese business users.
-- Existing project conventions are reused before adding new wrappers.
+## 验收
 
-## Do Not
+- 核验所需依赖或 starter 已进入实际工程。
+- JSR-303 与不可用的表达式校验不混入同一整改。
+- 不将类、parser 或配置归给不存在的历史模块。
+- 校验错误保留中文业务用户可理解的消息。
+- 新增包装前先复用工程既有约定。
 
-- 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.
-
-## 平台与源码门禁
+## 修改边界
 
-接入、修改、代码生成或给出精确类名/配置前，读取 [后端组件平台与源码门禁](../yss-skill-source-index-refresh/references/backend-component-platform-compatibility.md)，从批准的 `platform_configuration.component_platform_line` 选择 `source-index.boot2-java8.md` 或 `source-index.boot3-java17.md`，并以 `--skill yss-validation --platform-line <line> --source-root <matching-root>` 运行统一 freshness 校验。平台线与源码根不匹配、组件 tree 不一致、组件子树 dirty、索引缺少平台信号，或 Manifest / 组件 GAV 缺少 verified 兼容证据时返回 `blocked`；不得回退另一代索引，也不在业务实现中升级、降级或替换 YSS 组件。既有工程只读分诊可继续，但不得据此宣称跨 Boot/JDK 兼容。
+- 类名和配置 key 先核验当前索引与源码，不凭记忆补造。
+- 使用组件已有扩展 seam，不以业务本地框架代码替换。
+- 保持当前组件任务范围；扩展到其他组件须有用户要求或重新路由依据。

package/template/.pi/skills/yss-web-controller/SKILL.md

@@ -5,13 +5,17 @@ description: "按冻结合同与稳定 Application 接口生成或重构 YSS Con
 
 # yss-web-controller
 
-## 架构分流（先执行）
+## 任务分流
 
-读取当前合同的 architecture_identity 并与工程基线、仓库登记及 Manifest 核对；再且只读取 `references/profiles/<architecture_profile>.md`。生成式分支为 target-domain-model、layered-mvc-service、mvc-data-analysis-v1；既有工程分支为 existing-domain-driven-maven、existing-layered-mvc-maven。成熟度以注册表为准，不能把 draft 称为受支持。MVC 不执行下文 DDD 专属规则，也不加载其旧分层 guide；组件、安全、批准合同、允许路径及执行证据规则仍共用。
+- 只读审计读取实际入口和现有契约，缺用例 seam、契约或批准证据时记录缺口；不要求先补 Slice、生成 Manifest 或 metadata。
+- 既有整改消费批准且当前的 Slice、冻结 API/no-impact 与稳定用例 seam；缺必要输入回实现合同编译器补齐。
+- 仅新建 CRUD 要求 Web generation contract、metadata 并调用 initialize-only 生成器。认证、回调、Cookie、下载或流式接口可手工适配，不强制 CRUD 脚本或 metadata。
 
-以下 Application / Domain Gateway / Infrastructure / Web module 叙述仅适用于 target-domain-model；MVC 的 service/core/repository/server/client 所有权由所选 Profile 引用定义。
+## 架构分流
+
+将 `architecture_identity` 与当前工程基线和仓库登记核对；仅生成式来源核对脚手架 Manifest，既有来源使用登记及独立工程观测。再且只读取 `references/profiles/<architecture_profile>.md`。生成式分支为 target-domain-model、layered-mvc-service、mvc-data-analysis-v1；既有分支为 existing-domain-driven-maven、existing-layered-mvc-maven。成熟度以注册表为准，不能把 draft 称为受支持。MVC 不执行下文 DDD 专属规则，也不加载其分层 guide；组件、安全、批准合同、允许路径及执行证据规则共用。
 
-本 Skill 同时支持只读审计、既有整改和新建 CRUD 生成。审计读取实际入口和现有契约，缺证据只记录缺口；整改消费批准 Slice、冻结 API/no-impact 与稳定用例 seam；仅新建 CRUD 才要求 Web generation contract、metadata 并调用 initialize-only 生成器。
+以下 Application / Domain Gateway / Infrastructure / Web module 叙述仅适用于 target-domain-model；MVC 的 service/core/repository/server/client 所有权由所选 Profile 引用定义。
 
 ## 何时使用
 
@@ -19,46 +23,9 @@ description: "按冻结合同与稳定 Application 接口生成或重构 YSS Con
 - 用户要根据冻结 OpenAPI 字段合同、metadata 和稳定 Application 接口生成 Request / Response / Controller / WebConvertor。
 - 用户要求统一 Web Adapter 风格、返回值和接口路径。
 
-手工认证、回调、Cookie、下载或流式接口适用本 Skill，但不强制使用 CRUD 脚本或 metadata。
-
-## 实施前置与审计边界
-
-- 只读审计可以记录用例 seam 或契约缺失。既有整改缺少批准 Slice、稳定用例 seam 或接口契约时，回实现合同编译器补齐；仅新建 CRUD 生成要求 metadata，不因缺 metadata 拒绝既有代码审计或手工接口整改。
-
-## 新建 CRUD 生成流程
-
-1. 先确认冻结 OpenAPI、批准且版本当前的 Web generation contract schema v2、Application Service 接口、metadata、基础包、模块名、领域 segment 和 web 落盘目录；合同必须绑定 Slice `contract_id` / `contract_version` / `slice_id`、`yss-dto` wire profile 引用与 digest、允许写路径、证据与验证命令。
-2. 加载并遵守 `yss-dto` 与 `yss-validation`；错误映射影响命中时再加载 `yss-exception`。
-3. 涉及 DTO / VO / CMD / Query POJO 样板代码时，加载并遵守 `lombok`。
-4. 涉及 Domain / Application Result 到 VO / DTO 或 CMD / Query 到输入模型的转换时，加载并遵守 `mapstruct`。
-5. 运行 `node scripts/generate_controller.mjs`。
-6. 生成后检查路径、命名、返回值包装、Application Service 引用、`@Valid`、Lombok 注解和 MapStruct WebConvertor 是否对齐项目。
-7. 对复杂接口做少量手工修正，不在 skill 中承诺自动覆盖全部业务逻辑。
-
-## 推荐命令
-
-```bash
-node scripts/generate_controller.mjs \
-  --metadata-file /path/metadata.json \
-  --contract-file /path/approved-web-generation-contract.json \
-  --dto-wire-profile-file /path/to/yss-dto/references/openapi-wire-profile.yaml \
-  --scaffold-manifest-file /path/service/.yss/scaffold-generation.json \
-  --base-package com.yss.demo \
-  --module-name demo \
-  --domain-segment example \
-  --web-project-dir /path/demo-adapter/demo-web \
-  --application-service-package com.yss.demo.application.service \
-  --validation-namespace <resolved-platform-namespace>
-```
-
-## 输出预期
-
-- `rest/dto/request/*CreateRequest.java`
-- `rest/dto/request/*UpdateRequest.java`
-- `rest/dto/request/*PageRequest.java`
-- `rest/dto/response/*Response.java`
-- `rest/*Controller.java`
-- `rest/convertor/*WebConvertor.java`
+## 新建 CRUD 生成
+
+仅新建 CRUD 在输入齐备后必须读取 [生成流程与命令](references/crud-generation.md)，核验 schema v2 Web generation contract、metadata、绑定的 wire profile 与允许路径，再运行 initialize-only 生成器并检查完整输出。复杂接口仍按批准合同补足实现，不以生成成功替代行为验证。
 
 ## 约束
 

package/template/.pi/skills/yss-web-controller/references/crud-generation.md

@@ -0,0 +1,38 @@
+# 新建 CRUD 生成与核验
+
+仅在新建 CRUD 且入口的批准合同、冻结 API 与稳定用例 seam 已齐备时读取。只读审计、既有整改和手工协议适配不运行初始化生成器。以下命令从 Skill 根目录执行；参数消费当前合同与工程平台解析值，示例不授予写入或覆盖权限。
+
+## 新建 CRUD 生成流程
+
+1. 先确认冻结 OpenAPI、批准且版本当前的 Web generation contract schema v2、Application Service 接口、metadata、基础包、模块名、领域 segment 和 web 落盘目录；合同必须绑定 Slice `contract_id` / `contract_version` / `slice_id`、`yss-dto` wire profile 引用与 digest、允许写路径、证据与验证命令。
+2. 加载并遵守 `yss-dto` 与 `yss-validation`；错误映射影响命中时再加载 `yss-exception`。
+3. 涉及 DTO / VO / CMD / Query POJO 样板代码时，加载并遵守 `lombok`。
+4. 涉及 Domain / Application Result 到 VO / DTO 或 CMD / Query 到输入模型的转换时，加载并遵守 `mapstruct`。
+5. 运行 `node scripts/generate_controller.mjs`。
+6. 生成后检查路径、命名、返回值包装、Application Service 引用、`@Valid`、Lombok 注解和 MapStruct WebConvertor 是否对齐项目。
+7. 对复杂接口做少量手工修正，不在 skill 中承诺自动覆盖全部业务逻辑。
+
+## 推荐命令
+
+```bash
+node scripts/generate_controller.mjs \
+  --metadata-file /path/metadata.json \
+  --contract-file /path/approved-web-generation-contract.json \
+  --dto-wire-profile-file /path/to/yss-dto/references/openapi-wire-profile.yaml \
+  --scaffold-manifest-file /path/service/.yss/scaffold-generation.json \
+  --base-package com.yss.demo \
+  --module-name demo \
+  --domain-segment example \
+  --web-project-dir /path/demo-adapter/demo-web \
+  --application-service-package com.yss.demo.application.service \
+  --validation-namespace <resolved-platform-namespace>
+```
+
+## 输出预期
+
+- `rest/dto/request/*CreateRequest.java`
+- `rest/dto/request/*UpdateRequest.java`
+- `rest/dto/request/*PageRequest.java`
+- `rest/dto/response/*Response.java`
+- `rest/*Controller.java`
+- `rest/convertor/*WebConvertor.java`

package/template/.pi/skills/ytable-usage/SKILL.md

@@ -33,7 +33,7 @@ description: "配置或修复 YSS UI YTable 的列表查询、列、分页、行
 - 行键使用 `:row-config="{ keyField: 'id', useKey: true }"`，不臆造 `row-key` Prop。
 - 新增、导入、批量操作等主按钮直接放入 `#toolbar-right` 或 `#toolbar-left` 插槽即可自动渲染工具栏；**无需配置 `:toolbar-config="{ custom: true }"`**，避免无端展示列设置图标；**仅在业务明确需要列设置时才传入 `:toolbar-config="{ custom: true }"`**。
 - 删除、启停、发布等危险操作使用 `actionConfig.buttons[].isConfirm = true`，不默认使用 `Modal.confirm`。
-- 列配置超过 10 行时放入 `constant.ts`；需要调用组件 Hook 的操作配置使用工厂函数注入回调，禁止在 `constant.ts` 直接引用组件局部的 `openEdit/deleteItem`。
+- 纯列配置集中到 `constant.ts`；需要调用组件 Hook 的操作配置使用工厂函数注入回调，禁止在 `constant.ts` 直接引用组件局部的 `openEdit/deleteItem`。按职责和依赖拆分，不用配置行数决定拆分。
 - 远程筛选必须提供稳定 `filters`，设置 `filterMethod: () => true` 禁用本地二次过滤，并监听 `filter-change`。
 - 自适应滚动列表绑定 `:height="tableHeight"`；`pageable`、工具栏分别对应 `withPagination: true`、`withToolbar: true`。纯短表不强制引入高度 Hook。
 - `mutator.ts` 已对网络错误和 `success === false` 统一 `message.error` 并 reject。API Hook 不再检查 `success === false`，不在 `else/catch` 重复 `message.error`；用 `finally` 恢复 loading，让异常继续中断流程。
@@ -55,7 +55,7 @@ description: "配置或修复 YSS UI YTable 的列表查询、列、分页、行
 ## 交付检查清单
 
 - [ ] 分页状态和 `page-change` 参数均使用 `current/pageSize`，未使用 `currentPage`；`filter-change` 与 YTable 真实 API 一致。
-- [ ] 多选列已配置 `type: 'checkbox'`，已设置 `:row-config="{ keyField: 'xxx', useKey: true }"`，批量按钮绑定了 `selectedRowKeys.length === 0` 禁用。
+- [ ] 启用多选时，列已配置 `type: 'checkbox'`，已设置 `:row-config="{ keyField: 'xxx', useKey: true }"`，批量按钮绑定了 `selectedRowKeys.length === 0` 禁用。
 - [ ] 批量成功后，所有实际受控选择字段与表格可见勾选均已清空；内部缓存存在时已通过 `clearSelection()` 清除。
 - [ ] 未使用虚构 `request/searchParams/row-key` Props，也未把 `refresh()` 当成远程请求。
 - [ ] 工具栏、字典翻译、操作确认与高度偏移均与实际开关一致。

package/template/.pi/skills/ytree-usage/SKILL.md

@@ -36,87 +36,9 @@ description: "配置或修复 YSS UI YTree 的字段映射、搜索、选中与
 - 左树右表优先组合 `YSplitPane + YCard + YTree + YTable`；切换节点时同步查询条件并把右表分页重置为第 1 页。
 - 节点删除 API 的错误由 `mutator.ts` 统一提示并 reject；不在 `else/catch` 重复 `message.error`。
 
-## 标准代码骨架
+## 按需示例
 
-```vue
-<script setup lang="ts">
-import { ref } from 'vue';
-import { YTree, type YTreeActionItem } from '@yss-ui/components';
-import { useTreeHeight, YTREE_SEARCH_HEIGHT } from '@yss-ui/hooks';
-
-/** 树节点数据。 */
-interface TreeNode {
-  id: string;
-  name: string;
-  children?: TreeNode[];
-}
-
-const emit = defineEmits<{
-  create: [node: TreeNode];
-  edit: [node: TreeNode];
-}>();
-const treeAreaRef = ref<HTMLDivElement>();
-const treeData = ref<TreeNode[]>([]);
-const searchValue = ref('');
-const selectedKeys = ref<Array<string | number>>([]);
-const { treeHeight } = useTreeHeight(treeAreaRef, {
-  extraOffset: YTREE_SEARCH_HEIGHT,
-});
-
-/** 生成当前节点的非危险操作。 */
-const getNodeActions = (): YTreeActionItem[] => [
-  { key: 'add', label: '新增子节点' },
-  { key: 'edit', label: '编辑' },
-];
-
-/** 处理 YTree 动作事件。 */
-const handleTreeAction = ({ key, node }: { key: string; node: TreeNode }) => {
-  if (key === 'add') emit('create', node);
-  if (key === 'edit') emit('edit', node);
-};
-</script>
-
-<template>
-  <div ref="treeAreaRef" class="tree-area">
-    <YTree
-      :height="treeHeight"
-      :tree-data="treeData"
-      :field-names="{ title: 'name', key: 'id', children: 'children' }"
-      filterable
-      show-actions
-      v-model:searchValue="searchValue"
-      v-model:selectedKeys="selectedKeys"
-      :get-node-actions="getNodeActions"
-      @action="handleTreeAction"
-    />
-  </div>
-</template>
-
-<style scoped lang="less">
-@import './style.less';
-</style>
-```
-
-```less
-/* style.less */
-.tree-area {
-  flex: 1;
-  min-height: 0;
-  overflow: hidden;
-}
-```
-
-## 删除确认边界
-
-```vue
-<template #node-suffix="{ node }">
-  <Popconfirm title="确认删除该节点吗？" ok-text="确定" cancel-text="取消" @confirm="handleDelete(node)">
-    <YButton type="link" @click.stop>删除</YButton>
-  </Popconfirm>
-</template>
-```
-
-`Popconfirm` 从 `ant-design-vue` 导入，`YButton` 从 `@yss-ui/components` 导入。如果每个节点都展示删除会过密，把同样的 `Popconfirm` 放到选中节点的页面工具栏。
+首次组合受控树、高度与节点动作，或实现删除确认时，读取 [树与删除确认示例](references/tree-and-confirmation-example.md)。简单字段映射修改无需加载整段示例。
 
 ## 交付检查清单
 

package/template/.pi/skills/ytree-usage/references/tree-and-confirmation-example.md

@@ -0,0 +1,81 @@
+## 标准代码骨架
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { YTree, type YTreeActionItem } from '@yss-ui/components';
+import { useTreeHeight, YTREE_SEARCH_HEIGHT } from '@yss-ui/hooks';
+
+/** 树节点数据。 */
+interface TreeNode {
+  id: string;
+  name: string;
+  children?: TreeNode[];
+}
+
+const emit = defineEmits<{
+  create: [node: TreeNode];
+  edit: [node: TreeNode];
+}>();
+const treeAreaRef = ref<HTMLDivElement>();
+const treeData = ref<TreeNode[]>([]);
+const searchValue = ref('');
+const selectedKeys = ref<Array<string | number>>([]);
+const { treeHeight } = useTreeHeight(treeAreaRef, {
+  extraOffset: YTREE_SEARCH_HEIGHT,
+});
+
+/** 生成当前节点的非危险操作。 */
+const getNodeActions = (): YTreeActionItem[] => [
+  { key: 'add', label: '新增子节点' },
+  { key: 'edit', label: '编辑' },
+];
+
+/** 处理 YTree 动作事件。 */
+const handleTreeAction = ({ key, node }: { key: string; node: TreeNode }) => {
+  if (key === 'add') emit('create', node);
+  if (key === 'edit') emit('edit', node);
+};
+</script>
+
+<template>
+  <div ref="treeAreaRef" class="tree-area">
+    <YTree
+      :height="treeHeight"
+      :tree-data="treeData"
+      :field-names="{ title: 'name', key: 'id', children: 'children' }"
+      filterable
+      show-actions
+      v-model:searchValue="searchValue"
+      v-model:selectedKeys="selectedKeys"
+      :get-node-actions="getNodeActions"
+      @action="handleTreeAction"
+    />
+  </div>
+</template>
+
+<style scoped lang="less">
+@import './style.less';
+</style>
+```
+
+```less
+/* style.less */
+.tree-area {
+  flex: 1;
+  min-height: 0;
+  overflow: hidden;
+}
+```
+
+## 删除确认边界
+
+```vue
+<template #node-suffix="{ node }">
+  <Popconfirm title="确认删除该节点吗？" ok-text="确定" cancel-text="取消" @confirm="handleDelete(node)">
+    <YButton type="link" @click.stop>删除</YButton>
+  </Popconfirm>
+</template>
+```
+
+`Popconfirm` 从 `ant-design-vue` 导入，`YButton` 从 `@yss-ui/components` 导入。如果每个节点都展示删除会过密，把同样的 `Popconfirm` 放到选中节点的页面工具栏。

package/template/.template-spec/agents/backend-architecture-profiles.md

@@ -6,7 +6,7 @@ Profile、模块闭包、生成器、成熟度和 Recipe 的权威映射见 `yss
 
 ## 既有工程适配
 
-`existing_project_profiles` 与下述生成器 Profile 独立维护。首版两个 Maven 适配器通过真实 Git/POM 三方核验、对应架构的成功/失败行为测试与 Maven test/package 后标记 supported；依据见 `.template-source/evidence/maintenance/2026-09-12-existing-project-delivery/maven-adapters-04.json`。这是适配协议支持证据，不是实际产品批准、数据库兼容或真实跨仓 S0 结论。每个工程仍须自己的固定来源、架构边界审查和执行证据，详见 `.template-spec/process/existing-backend-architecture.md`。生成器原有 draft 和首切片要求保持。
+`existing_project_profiles` 与下述生成器 Profile 独立维护。首版两个 Maven 适配器通过真实 Git/POM 三方核验、对应架构的成功/失败行为测试与 Maven test/package 后标记 supported；当前适配行为由 `scripts/verify-existing-backend-architecture-scenarios` 和对应独立 fixture 核验。这是适配协议支持证据，不是实际产品批准、数据库兼容或真实跨仓 S0 结论。每个工程仍须自己的固定来源、架构边界审查和执行证据，详见 `.template-spec/process/existing-backend-architecture.md`。生成器原有 draft 和首切片要求保持。
 
 ## MVC 分层
 

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

@@ -22,12 +22,16 @@
 
 正式门禁的会签由 `gate_policy.digital_human_review` / `dual_digital_human` / `biological_human` 定义；内部专业审查由 `check_reviews` 定义，自动检查由 `automatic_checks` 定义。每项的起草者与会签人只读取 YAML，不在本文复制名单。
 
+专业审查按 YAML `review_capabilities` 和检查策略的 `capability_ids` 选择具备能力的独立执行者；角色是职责边界，不能用另一个职称替代能力或独立身份。正式 v1 审查任务的 `review_context` 绑定当前检查 / 能力、候选、策略、范围、依据摘要和审查 / 起草主体；`skill_source.review_skills` 从能力表编译，只供 Reviewer / Verifier 只读审查，角色核心技能和禁止技能不变。能力定义不在本文重复维护。
+
 Plan、产品设计、工程契约统一呈现适用检查后批准。`gate.delivery-accepted` 由测试角色进行交付验收，实际合并或发布仍须另有生物人授权。内部检查不独立请求用户决定；检查失败仍阻断聚合门禁。专业审查可在同一工作单元完成多个检查项，但必须保留逐项结论、资产摘要与独立执行者身份。
 
-会签写入 `docs/.scratch/<feature>/gates/<gate-id>-approval.yaml`，形状见 `.template-spec/templates/approval-record-template.yaml`。恢复前运行 `scripts/verify-approval-record --require-approved`。错误会签只能得到 `blocked`，不能把门禁标成 `approved`。Checkpoint 里会签桶门禁为 `approved` 时必须有可读 `approval_ref`。
+会签写入 `docs/.scratch/<feature>/gates/<gate-id>-approval.yaml`，新记录使用 schema v2，形状见 `.template-spec/templates/approval-record-template.yaml`。专业记录绑定 `review_task_ref/digest`、`capability_ids` 与 `basis`，相邻检查可组合为 schema v2 `review-bundle` 并逐项记录。恢复前运行 `scripts/verify-approval-record --require-approved --checkpoint <current checkpoint>`；当前期望上下文由消费 checkpoint / 任务建立，不能反向复制会签记录。错误会签只能得到 `blocked`，不能把门禁标成 `approved`。Checkpoint 里会签桶门禁为 `approved` 时必须有可读 `approval_ref`。历史记录可用 `--history` 只读查看，不放行当前执行；旧消费者须拒绝 v2 并升级。
 
 `paused-human-gate` 表示等待指定会签人；`user_decision_policy` 命中的关键决定同时强制真实用户回复，数字人审查不能代答。请求展示、原始回复证据、复用和恢复规则见 [用户决定协议](../../.agents/skills/yss-product-lifecycle/references/user-decisions.md)。
 
+专业等待由主控自主派发、等待并继续无依赖工作；验证失败修复或路由。未知影响先调查，缺真实决定或新授权才展示材料后询问。首轮覆盖全部适用检查；修复后按差异、受影响结论 / 行为及依赖定向复审并绑定当前候选，不因摘要变化、UI 影响或 `new_impacts` 默认重跑全轴。
+
 主控默认兼任项目经理，直到 `dual_hat_split_when`（`cross-repo-load` 或 `responsibility-conflict`）要求分体。
 
 ## 跨平台协同（默认）

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

@@ -172,6 +172,41 @@ stage_groups:
     stage: stage.verification-release-retrospective
     members: [ role.lifecycle-orchestrator, role.project-manager, role.test-engineer, role.product-manager ]
 
+# 职称继续用于导航；正式专业审查按能力绑定同一独立实例，不授予实现权限。
+review_capabilities:
+  - id: capability.business-rules
+    name: 业务边界与规则审查
+    eligible_roles: [role.product-manager]
+    review_skills: [domain-modeling, yss-stage-decision]
+  - id: capability.spec-acceptance
+    name: Spec 范围与验收审查
+    eligible_roles: [role.product-manager]
+    review_skills: [code-review]
+  - id: capability.prototype-assurance
+    name: 原型与体验审查
+    eligible_roles: [role.frontend-engineer, role.test-engineer]
+    review_skills: [prototype-review, yss-design-system]
+  - id: capability.openapi-contract
+    name: OpenAPI Draft 契约与客户端适配审查
+    eligible_roles: [role.frontend-engineer, role.test-engineer]
+    review_skills: [yss-openapi-draft-review]
+  - id: capability.technical-design
+    name: 技术设计与架构审查
+    eligible_roles: [role.backend-engineer, role.test-engineer]
+    review_skills: [yss-technical-design]
+  - id: capability.engineering-baseline
+    name: 工程基线与验证审查
+    eligible_roles: [role.test-engineer]
+    review_skills: [code-review]
+  - id: capability.engineering-acceptance
+    name: 工程契约聚合审查
+    eligible_roles: [role.test-engineer, role.product-manager]
+    review_skills: [code-review]
+  - id: capability.implementation-assurance
+    name: 实现与交付证据审查
+    eligible_roles: [role.test-engineer]
+    review_skills: [code-review]
+
 gate_policy:
   # countersigners 是可胜任该边界的候选角色，不是必须集齐的签字名单。
   review_execution:
@@ -188,29 +223,34 @@ gate_policy:
     gate.backend-architecture-platform-approved: [role.backend-engineer]
     gate.engineering-contract-approved: [role.backend-engineer, role.test-engineer]
     implementation-scope: [role.test-engineer]
-  default_if_unlisted: biological-human
+  default_if_unlisted: reject-unlisted
   evidence_only: []
   orchestrator:
     - gate.slice-contract-approved
   digital_human_review:
     - gate: gate.delivery-accepted
+      capability_ids: [capability.implementation-assurance]
       countersigners:
         - role.test-engineer
   digital_human_review_work_units:
     - work_unit: work-unit.code-review
+      capability_ids: [capability.implementation-assurance]
       countersigners:
         - role.test-engineer
       implementer_must_differ: true
   dual_digital_human:
     - gate: gate.plan-approved
+      capability_ids: [capability.business-rules]
       drafter: role.requirements-manager
       countersigners:
         - role.product-manager
     - gate: gate.spec-baseline-approved
+      capability_ids: [capability.spec-acceptance]
       drafter: role.requirements-manager
       countersigners:
         - role.product-manager
     - gate: gate.engineering-contract-approved
+      capability_ids: [capability.engineering-acceptance]
       drafter: role.backend-engineer
       countersigners:
         - role.test-engineer
@@ -229,33 +269,41 @@ gate_policy:
     - check.openapi-frozen
   check_reviews:
     - gate: check.domain-strategy-approved
+      capability_ids: [capability.business-rules]
       drafter: role.requirements-manager
       countersigners:
         - role.product-manager
     - gate: check.stage-decision-package-approved
+      capability_ids: [capability.business-rules]
       drafter: role.requirements-manager
       countersigners:
         - role.product-manager
     - gate: check.prototype-reviewed
+      capability_ids: [capability.prototype-assurance]
       drafter: role.product-manager
       countersigners:
         - role.frontend-engineer
     - gate: check.openapi-draft-reviewed
+      capability_ids: [capability.openapi-contract]
       drafter: role.backend-engineer
       countersigners:
         - role.frontend-engineer
     - gate: check.design-reviewed
+      capability_ids: [capability.technical-design]
       countersigners:
         - role.backend-engineer
         - role.test-engineer
     - gate: check.architecture-reviewed
+      capability_ids: [capability.technical-design]
       countersigners:
         - role.backend-engineer
         - role.test-engineer
     - gate: check.engineering-baseline-accepted
+      capability_ids: [capability.engineering-baseline]
       countersigners:
         - role.test-engineer
     - gate: check.frontend-implementation-verified
+      capability_ids: [capability.implementation-assurance]
       drafter: role.frontend-engineer
       countersigners:
         - role.test-engineer

package/template/.template-spec/engineering/backend-platforms.json

@@ -478,7 +478,7 @@
       "artifact_resolution_evidence": {
         "report_id": "aliyun-maven-artifact-resolution-2026-09-18",
         "repository_id": "2306938-snapshot-Yloqmt",
-        "ref": ".template-source/evidence/maintenance/2026-09-18-yss-backend-components/aliyun-artifact-resolution.json",
+        "ref": ".template-source/engineering/evidence/aliyun-artifact-resolution.json",
         "digest": "sha256:35a82e84eb93d35046900886affb806f3620b1416b4b097f67f42c658b676bca"
       }
     },