create-yss-spec 3.5.6 → 3.5.9

package/template/.codex/skills/yss-cache/SKILL.md

@@ -7,6 +7,10 @@ description: "接入或排查 YSS QueryCache、UpdateCache、ClearCache、TTL、
 
 处理 `yss-component-cache-parent` 及其消费项目的缓存任务。
 
+## 平台与源码门禁
+
+接入、修改、代码生成或提供精确类名/配置前，必须读取并执行 [共享平台与源码门禁](../yss-skill-source-index-refresh/references/backend-component-platform-compatibility.md)，以 `--skill yss-cache` 校验批准的平台线及匹配源码根。缺失、错配或漂移返回 `blocked`；不跨代回退，不在业务实现中升级、降级或替换组件。只读分诊可继续，但须标注未完成源码核验，不能据此宣称跨 Boot/JDK 兼容。
+
 ## 工作流
 
 1. 按 `yss-skill-source-index-refresh/references/source-location.md` 定位真实源码。当前工作区有 `.codegraph/` 时先用 CodeGraph；否则读取 [source-index.md](references/source-index.md) 后用符号或 Maven 模块搜索。
@@ -43,7 +47,3 @@ description: "接入或排查 YSS QueryCache、UpdateCache、ClearCache、TTL、
 - `scripts/check-skill-freshness.sh <boot2-java8|boot3-java17> [source-root]`：比较所选平台线的技能契约与当前组件源码；发现平台错配或漂移返回 1。
 
 本 Skill 中新增的 `failure-mode`、区域策略和 `empty-key-eviction` 指引针对当前 Boot 3 组件；Boot 2 的精确配置与默认值须查其独立索引及源码。组件源码形成干净、固定的来源后，用 `yss-skill-source-index-refresh` 刷新所选平台的生成索引，再运行 freshness 检查。`source-index.md` 是平台选择页；不要手工修改生成索引或把 dirty 工作树的观察说成已核验事实。
-
-## 平台与源码门禁
-
-接入、修改、代码生成或给出精确类名/配置前，读取 [后端组件平台与源码门禁](../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-cache --platform-line <line> --source-root <matching-root>` 运行统一 freshness 校验。平台线与源码根不匹配、组件 tree 不一致、组件子树 dirty、索引缺少平台信号，或 Manifest / 组件 GAV 缺少 verified 兼容证据时返回 `blocked`；不得回退另一代索引，也不在业务实现中升级、降级或替换 YSS 组件。既有工程只读分诊可继续，但不得据此宣称跨 Boot/JDK 兼容。

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

@@ -50,10 +50,10 @@ description: 用于生成完整的 YSS DDD 多模块后端脚手架。当用户
 
 - 先在生命周期批准的脚手架受控生成合同下生成骨架，再做业务化定制；不要直接把脚手架当最终代码交付。
 - 永不生成 `User CRUD` 示例；`--with-example` 已禁用，业务代码必须按批准的 Slice Implementation Contract 逐切片实现。
-- 若目标工程已经存在，直接返回 `unsupported`。旧项目继续按原工程维护；需要现代化时单独立项、先评估再逐切片迁移，不属于本 skill。
-- 输出目录必须显式指定；目标工程目录必须不存在，`--force` 永久拒绝。
-- Harness 内多项目布局必须使用 `apps/backend/<project>/`；`apps/backend/` 只能是生成器的父容器，`app/backend/`、`app/frontend/` 及其子路径一律拒绝。`git-submodule` gitlink、空挂载点、detached HEAD 工作树不得覆盖生成，即使传入 `--force` 也不得当成普通目录，且不得走「请显式传入 `--force`」普通目录覆盖 / rename 路径。`--output-dir` 指向 detached HEAD 子仓时不得 mkdir、staging 或生成工程。先 `git submodule update --init` 并在子仓附加分支工作树内生成。维护生成器时按 [守卫顺序](references/generator-maintenance.md) 检查，不能将 gitlink 当普通目录。
-- 生成时的工程基线由本 skill 的 `references/engineering-baseline.md` 持有并绑定摘要；它不是独立 Skill。生成后必须回到 实现合同编译器，并按批准切片加载 `yss-domain`、`yss-application`、`yss-repository`、`yss-mybatis`、`yss-web-controller`、`yss-dto`、`yss-exception`、`yss-validation`、`mapstruct`、`lombok`、`alibaba-java-code-style` 等实际命中的行为 skill。
+- 输出目录必须显式指定，生成器严格 `initialize-only`；目标工程目录必须不存在。已有工程、非空目标、`--force`、旧项目迁移和当前模板升级均返回 `unsupported`。旧项目继续按原工程维护；现代化或未来同一 Target Profile 模板升级须另行设计、批准，当前不提供该执行能力。
+- Harness 内多项目使用 `apps/backend/<project>/`，`apps/backend/` 只作输出父容器；`app/backend/`、`app/frontend/` 及其子路径一律拒绝。
+- `git-submodule` gitlink、空挂载点和 detached HEAD 不作为普通目录覆盖或 rename，`--force` 不解除边界。`--output-dir` 指向 detached HEAD 子仓时不得 mkdir、staging 或生成；工程准备须先初始化 submodule 并在子仓附加分支工作树内生成。维护生成器时读取 [守卫顺序](references/generator-maintenance.md)。
+- 生成工程基线由本 Skill 的 `references/engineering-baseline.md` 持有并绑定摘要，不是独立 Skill。后续实现的专项路由见 [分层 Skill 路由](references/layer-skill-routing.md)，由实现合同编译器按批准切片选择实际命中的技能。
 - 生成后的后端工程必须使用项目根目录 `./mvnw ...` 执行构建、测试、运行和 CI 验证；不得在 README、实施记录、Ticket、Review 或 Release 中默认写裸 `mvn ...`。既有仓库确实无法使用 wrapper 时，必须记录受控例外。
 - 原型确认后，`scaffold_status=required` 才能进入本 skill；本 skill 的生成边界是工程结构、POM、配置、Wrapper 和机械模板，不是业务实现。
 - 脚手架合同必须携带 `contract_id`、`contract_version`、实现合同编译器 draft 引用、生命周期批准引用、持久化引用、当前版本、允许写路径、预期证据文件和验证命令；字段缺失或版本过期时阻断。
@@ -63,8 +63,7 @@ description: 用于生成完整的 YSS DDD 多模块后端脚手架。当用户
 - 生成项目必须写入 Manifest v4 `.yss/scaffold-generation.json`，记录技术、数据与 API 设计门禁、架构选择及 digest、生成器、合同 digest、Target Profile、模块闭包、模板 digest、下游完整 当前合同 freshness、generator-owned 文件 hash、严格 `generation_policy` 和完成等级；清单缺失或不一致时不得交给后续 实现合同编译器。
 - `first-slice-verified` 只能由 `run_first_slice_verification.mjs` 写入。手工改 Manifest、只生成 Controller、只通过局部模块测试或仅有结构扫描都不能升级完成等级。
 - 严禁把领域规则、状态机、权限、事务、复杂查询、错误映射、业务字段或用户可见行为塞进脚手架生成步骤。`./mvnw validate`、输出目录存在或“生成成功”都不等于生命周期批准、架构放行或 `ready-for-agent`。
-- 生命周期脚手架生成必须关闭 `--with-example`，不得把 User CRUD 或业务字段当作样板。生成器严格 `initialize-only`：非空目标、`--force`、旧项目迁移和当前模板升级一律 `unsupported`。未来若支持同一 Target Profile 内的模板升级，必须另行设计和批准，当前不预留可执行承诺。
-- 脚手架完成后，所有后续生成的后端代码必须回到 `yss-implementation-contract-compiler`，消费批准且版本当前的 Slice Implementation Contract 和对应 YSS skill；业务行为使用 `behavior-tdd`，机械生成才使用 `controlled-generation`。
+- 脚手架完成后，所有后续后端代码必须回到 `yss-implementation-contract-compiler`，消费批准且版本当前的 Slice Implementation Contract 和适用 YSS skill；业务行为使用 `behavior-tdd`，机械生成才使用 `controlled-generation`。
 - 涉及 API 契约时，先确认 `docs/.scratch/<feature>/api/<feature>.yaml` 中的 OpenAPI Draft / Freeze 状态；不要用脚手架生成结果反向替代产品契约设计。
 
 ## 按需读取
@@ -79,7 +78,7 @@ description: 用于生成完整的 YSS DDD 多模块后端脚手架。当用户
 ## 阶段 7 合同
 
 - 仅在实现仓库/输出目录、`scaffold_status=required` 和批准合同明确时运行。
-- 工程骨架属于 `controlled-generation`，必须记录生成器输入、预期文件和 `./mvnw ...` 编译/测试结果；不得将业务状态机、权限、事务或查询逻辑混入生成步骤。
+- 工程骨架属于 `controlled-generation`，记录生成器输入、预期文件和实际编译/测试结果。
 - 生成结果必须包含 `.yss/scaffold-generation.json`，并由验证器回勾该清单；清单与批准合同不一致时阻断。
-- `./mvnw validate`、`./mvnw test`、`./mvnw package` 必须由受控工作单元真实执行，并记录每条命令的 `exit_code`、耗时、stdout/stderr 引用和执行时间；只列命令计划、生成器成功或打印输出均视为缺失证据并阻断。
+- 三条根 Wrapper 验证必须按 [受控生成与验证](references/generation-workflow.md) 真实执行，逐条记录 `exit_code`、耗时、stdout/stderr 引用和执行时间；计划、生成器成功或打印输出不构成执行证据，缺失即阻断。
 - 生成后按统一 `YSS Skill Execution Result` 返回 changed/evidence files、实际验证结果和新增影响，再由 实现合同编译器 为业务工作单元重新路由。

package/template/.codex/skills/yss-ddd-scaffold-generator/references/USAGE_EXAMPLES.md

@@ -2,16 +2,22 @@
 
 ## 1. 准备批准合同
 
-新合同是服务级工程基线，使用 schema v4 与 `scaffold_request_id`，并把已批准的技术/数据设计、工程合同批准、架构决策、Java 包名、Maven 坐标和 Profile 分开登记：
+新合同是服务级工程基线，使用统一 Project Scaffold Contract schema v4 与 `scaffold_request_id`。以下仅展示身份、Profile 和生成策略片段；实际平台、Maven 坐标、设计与批准绑定必须来自当前已批准输入，示例值不能作为生成授权：
 
 ```json
 {
-  "schema_version": 3,
+  "schema_version": 4,
+  "kind": "project-scaffold-contract",
+  "delivery_role": "backend",
+  "scaffold_kind": "backend-ddd",
+  "repository_scope": "external-repository",
+  "init_git": false,
   "scaffold_request_id": "scaffold-metadata-service-1",
   "project_name": "metadata-service",
   "target_output_dir": "/path/to/implementation-repo",
   "base_package": "com.yss.metadata",
   "architecture_family": "domain-driven",
+  "architecture_profile": "target-domain-model",
   "generator_skill": "yss-ddd-scaffold-generator",
   "decision_ref": "scaffold-architecture-decisions.yaml",
   "decision_id": "architecture-metadata-service",
@@ -29,9 +35,10 @@
   "profiles": {
     "architecture": "target-domain-model",
     "persistence": "mybatis-plus",
-    "database": "mysql",
-    "platform": "spring-boot-2.7-jdk8",
-    "validation_namespace": "javax",
+    "verification_database": "h2",
+    "production_database": "not-bound",
+    "platform": "<approved-platform-profile>",
+    "validation_namespace": "<resolved-platform-namespace>",
     "dto_placement": "web",
     "repository": "yss-internal"
   },
@@ -49,7 +56,7 @@
 }
 ```
 
-以上只是关键片段；实际合同还必须满足 `yss-implementation-contract-compiler/references/compiler-contract.yaml` 中的完整 `scaffold_contract_schema`，引用经用户确认并由生命周期批准的 `scaffold-architecture-decisions.yaml`，再持久化为当前版本。历史 schema v2 仅用于验证器只读兼容；新生成拒绝 schema v1/v2 且不自动升级。
+完整结构以仓库 `.template-spec/process/schemas/project-scaffold-contract.schema.json` 和编译器 `project_scaffold_contract_schema` 为准，不能使用历史 `scaffold_contract_schema` v3 生成新工程。完整合同还须绑定当前 `platform_configuration` v2、用户确认且生命周期批准的架构决定，以及 `design_prerequisites` 中技术设计、数据与 API 决策、真实工程合同批准；API 有影响时绑定同一 OpenAPI YAML 原字节的 Validation、独立 Review 与 Freeze，无影响时绑定评估、原因和证据。当前批准与持久化、允许路径和验证字段仍须完整，不能直接执行这个片段。历史 Manifest v2/v3 只供只读验证与受控恢复审计；新生成拒绝旧合同且不自动升级。
 
 ## 2. 一键生成并验证
 

package/template/.codex/skills/yss-ddd-scaffold-generator/references/command-examples.md

@@ -1,5 +1,7 @@
 ## 推荐命令
 
+仅在入口所列批准合同、输出范围和平台证据已齐备时读取；命令从 Skill 根目录执行。项目坐标与平台参数使用当前批准输入，示例值不授予生成、覆盖或版本升级权限。
+
 ```bash
 node scripts/generate_and_verify_scaffold.mjs \
   --project-name my-service \

package/template/.codex/skills/yss-ddd-scaffold-generator/scripts/scaffold-generator.test.mjs

@@ -192,7 +192,7 @@ test("技术和数据设计齐全但缺少 API Decision 时在写文件前拒绝
   assert.equal(existsSync(path.join(data.output, "demo-service")), false);
 });
 
-test("API Draft、Validation、Review 或工程批准漂移时均在零写入状态阻断 DDD", async (t) => {
+test("API、工程批准或独立当前批准上下文缺失及漂移时均在零写入状态阻断 DDD", async (t) => {
   const mutations = [
     ["OpenAPI YAML 摘要漂移", async (data) => writeFile(data.design.openapi.file, "\n# drift\n", { flag: "a" })],
     ["Redocly Validation 失败", async (data) => {
@@ -225,6 +225,33 @@ test("API Draft、Validation、Review 或工程批准漂移时均在零写入状
       approval.artifact_bindings = approval.artifact_bindings.filter((item) => !item.id.startsWith("api-contract."));
       await writeFile(data.design.approval.file, `${JSON.stringify(approval, null, 2)}\n`);
     }],
+    ["缺少独立当前批准上下文", async (data) => {
+      delete data.contract.design_prerequisites.technical_design.approval_context;
+      await writeFile(data.contractFile, `${JSON.stringify(data.contract, null, 2)}\n`);
+    }],
+    ["消费范围替换", async (data) => {
+      data.contract.design_prerequisites.technical_design.approval_context.approval_scope = ["scaffold.other", "demo-service"];
+      await writeFile(data.contractFile, `${JSON.stringify(data.contract, null, 2)}\n`);
+    }],
+    ["消费主体替换", async (data) => {
+      data.contract.design_prerequisites.technical_design.approval_context.subject_ref = data.design.data.ref;
+      await writeFile(data.contractFile, `${JSON.stringify(data.contract, null, 2)}\n`);
+    }],
+    ["当前依据摘要漂移", async (data) => {
+      data.contract.design_prerequisites.technical_design.approval_context.basis[0].digest = `sha256:${"0".repeat(64)}`;
+      await writeFile(data.contractFile, `${JSON.stringify(data.contract, null, 2)}\n`);
+    }],
+    ["当前起草主体替换", async (data) => {
+      data.contract.design_prerequisites.technical_design.approval_context.drafter_principal_ref = "other-drafter";
+      await writeFile(data.contractFile, `${JSON.stringify(data.contract, null, 2)}\n`);
+    }],
+    ["当前起草者自签", async (data) => {
+      const approval = JSON.parse(await readFile(data.design.approval.file, "utf8"));
+      approval.drafter_principal_ref = approval.principal_ref;
+      data.contract.design_prerequisites.technical_design.approval_context.drafter_principal_ref = approval.principal_ref;
+      await writeFile(data.design.approval.file, `${JSON.stringify(approval, null, 2)}\n`);
+      await writeFile(data.contractFile, `${JSON.stringify(data.contract, null, 2)}\n`);
+    }],
   ];
   for (const [name, mutate] of mutations) {
     const data = await fixture({ apiImpact: "required" });

package/template/.codex/skills/yss-design-system/SKILL.md

@@ -26,7 +26,7 @@ description: 建立或核验 YSS 设计系统、主题 Token 与页面视觉一
 2. 读取已有资产：先读根 `DESIGN.md`，再读 `.template-spec/design/design.md` 和 Token 派生快照，最后按任务读取相关 Spec、交互说明、状态矩阵、OpenAPI Draft、现有页面代码。
 3. 按设计系统基线约束输出或修改产物：颜色、排版、间距、圆角、动效、组件、状态、响应式。
 4. 若是产品设计阶段，先使用 `yss-prototype-stage`；规范直出由 YSS HTML adapter 执行；存在已选视觉稿时条件使用 `product-design:index`，其他 Agent 交付等价证据。
-5. 若是前端实现阶段，配合 `yss-ui`、`yss-ui-business-page-generation`、`yss-formily` 及实际命中的组件专项，但本技能负责风格与体验一致性门禁。
+5. 若是前端实现阶段，配合 `yss-ui`、`yss-ui-business-page-generation`、`yss-formily` 及实际命中的组件专项，但本技能负责风格与体验一致性门禁。原型阶段只选择设计语义及已登记原型组件；生产组件名称、版本和 API 留给实现计划按目标仓来源核验，不在原型阶段调用 `yss-ui`。
 6. 若发现视觉 Token 或组件变体不足，先更新根 `DESIGN.md` 并重新生成投影；只有治理、流程或验收说明不足时才更新 `.template-spec/design/design.md`。
 
 新建高保真原型默认选择根规范已有的紧凑组件变体，按需读取 [原型默认主题](references/prototype-default-theme.md)；此选择不改变生产主题默认值或既有批准页面。
@@ -72,7 +72,7 @@ description: 建立或核验 YSS 设计系统、主题 Token 与页面视觉一
 
 - 设计系统引用：明确引用根 `DESIGN.md`、治理说明 `.template-spec/design/design.md` 和所选主题的 Token 快照；原型证据记录规范与 Token 摘要。
 - 页面和模块：页面清单、布局结构、主路径、异常路径。
-- 组件选择：YSS UI / Ant Design 组件映射。
+- 组件选择：设计 / 原型记录控件语义及原型组件映射；前端实现计划按目标仓已核验版本记录 YSS UI / Ant Design 生产组件映射。原型中的语义对应关系不能作为生产 API 事实。
 - 状态矩阵：加载、空、错、禁用、只读、无权限、冲突、成功。
 - API 反推：字段、筛选、分页、动作、错误码、权限、并发或幂等规则。
 - 响应式要求：关键断点和窄屏替代形态。

package/template/.codex/skills/yss-distributed-id/SKILL.md

@@ -7,6 +7,10 @@ description: "接入或排查 YSS 分布式 ID 的 Segment、Snowflake、主键
 
 处理 `yss-component-distributed-id` 及 Leaf 消费项目的发号、主键填充与迁移。先从批准的 `platform_configuration.component_platform_line` 选择 [源码索引](references/source-index.md)；Boot 2 的历史能力不能推定为 Boot 3 可用能力。无批准合同的既有工程故障可只读分诊，不据此改策略或宣布兼容。
 
+## 平台与源码门禁
+
+接入、修改、代码生成或提供精确类名/配置前，必须读取并执行 [共享平台与源码门禁](../yss-skill-source-index-refresh/references/backend-component-platform-compatibility.md)，以 `--skill yss-distributed-id` 校验批准的平台线及匹配源码根。缺失、错配或漂移返回 `blocked`；不跨代回退，不在业务实现中升级、降级或替换组件。只读分诊可继续，但须标注未完成源码核验，不能据此宣称跨 Boot/JDK 兼容。
+
 ## 接入决策
 
 1. 核对实际组件 GAV、平台线、依赖树及当前源码，再确定已有主键策略、注入模式和数据库约束。保持既有 Long 主键及调用方类型，策略变更单独评估数据和 API 影响。
@@ -23,7 +27,3 @@ description: "接入或排查 YSS 分布式 ID 的 Segment、Snowflake、主键
 - 行为修改使用组件父 reactor 的根 `./mvnw` 验证启动、单条/批量主键、迁移边界和目标数据库方言；H2 不能证明生产方言。只读故障分诊与已执行验证分别记录。
 
 当前源码入口与平台差异见 [能力与迁移说明](references/README.md)。不要从 Skill 的历史示例或旧资产复制生产源码；精确类名、配置和默认值以选定平台线的当前源码为准。
-
-## 平台与源码门禁
-
-接入、修改、代码生成或给出精确类名/配置前，读取 [后端组件平台与源码门禁](../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-distributed-id --platform-line <line> --source-root <matching-root>` 运行统一 freshness 校验。平台线与源码根不匹配、组件 tree 不一致、组件子树 dirty、索引缺少平台信号，或 Manifest / 组件 GAV 缺少 verified 兼容证据时返回 `blocked`；不得回退另一代索引，也不在业务实现中升级、降级或替换 YSS 组件。既有工程只读分诊可继续，但不得据此宣称跨 Boot/JDK 兼容。

package/template/.codex/skills/yss-dto/SKILL.md

@@ -9,6 +9,10 @@ description: "实现或核验 YSS Result、PageResult、PageQuery、CommandDTO
 
 本 skill 同时负责把中台 DTO 映射到公开 HTTP/JSON 边界。`references/openapi-wire-profile.yaml` 是可复用的机器可读映射源；OpenAPI 治理和 Draft Review 必须消费它，不得各自复制一份 wrapper 或分页字段表。
 
+## 平台与源码门禁
+
+接入、修改、代码生成或提供精确类名/配置前，必须读取并执行 [共享平台与源码门禁](../yss-skill-source-index-refresh/references/backend-component-platform-compatibility.md)，以 `--skill yss-dto` 校验批准的平台线及匹配源码根。缺失、错配或漂移返回 `blocked`；不跨代回退，不在业务实现中升级、降级或替换组件。只读分诊可继续，但须标注未完成源码核验，不能据此宣称跨 Boot/JDK 兼容。
+
 ## 所有权边界
 
 - 先消费 `architecture_identity`：DDD 的 HTTP DTO 在 Web；通用 MVC 私有 DTO 在 server、已批准公开 DTO 在 client；数据分析 MVC 公开 DTO 在 client。service/core 自有内部 Command/Query/Result，不依赖 client DTO；server 用 MapStruct 转换。共用 wire profile 不意味着共用模块路径。
@@ -28,7 +32,7 @@ description: "实现或核验 YSS Result、PageResult、PageQuery、CommandDTO
 1. 优先沿用项目现有 DTO 体系，不重复造返回包装类。
 2. 涉及真实类名、返回结构、分页字段或排障时，先读 `references/source-index.md`，再定位源码或文档。
 3. 新 Target Profile 的 canonical 包固定为 `com.yss.cloud.dto.result`；`com.yss.cloud.dto.response` 为 `unsupported`，不得在新契约或脚手架输出中引入。检测到旧包时只报告边界，不自动改写；旧项目现代化须单独立项。
-4. 需要设计或审查 API 时，先校验 `references/openapi-wire-profile.yaml`，再把 endpoint 的具体 DTO/VO schema 组合到 wrapper；Java 泛型不是 OpenAPI schema。
+4. 需要设计或审查 API 时，先辨认已批准协议；采用 YSS wrapper 的普通 HTTP/JSON 接口校验 `references/openapi-wire-profile.yaml`，再把 endpoint 的具体 DTO/VO schema 组合到 wrapper。下载、流式和第三方回调按批准协议检查；Java 泛型不是 OpenAPI schema。
 5. 只围绕当前 DTO 结构回答，不泛化到整个微服务理论。
 
 ## 源码索引
@@ -50,11 +54,11 @@ description: "实现或核验 YSS Result、PageResult、PageQuery、CommandDTO
 - Controller 返回优先使用项目既有的 `Result` 或派生结果对象。
 - 单对象返回优先 `SingleResult`，列表返回优先 `MultiResult`，分页返回优先 `PageResult`，前提是当前项目已采用这套体系。
 - 三种泛型结果要求 `T extends Serializable`；生成的 VO/响应类型必须满足该编译约束。
-- OpenAPI 响应以 `YssResultMeta` 表达公共字段，并用 `allOf` 叠加 endpoint-specific `data` / page 字段；每个响应声明 `x-yss-response-wrapper: SingleResult|MultiResult|PageResult`，不得把 `SingleResult<T>` 文字写成 schema。
-- wire shape 不是 Java 字段清单：`success` 为 boolean，`dataType` 为 `string|null`，`code` 只允许 `string|integer|null`；不得把全局 `code` 放宽为任意 object。
+- 采用 YSS wrapper 的普通 HTTP/JSON 响应以 `YssResultMeta` 表达公共字段，并用 `allOf` 叠加 endpoint-specific `data` / page 字段；这些响应声明 `x-yss-response-wrapper: SingleResult|MultiResult|PageResult`，不得把 `SingleResult<T>` 文字写成 schema。
+- YSS wrapper 的 wire shape 不是 Java 字段清单：`success` 为 boolean，`dataType` 为 `string|null`，`code` 只允许 `string|integer|null`；不得把该 profile 的全局 `code` 放宽为任意 object。
 - `MultiResult.data` 和 `PageResult.data` 对外是数组，空值按 `[]` 建模；`SingleResult.data` 按 endpoint schema 建模并显式处理 nullability。
 - `PageResult` 当前稳定公共字段为 `totalCount/pageSize/pageIndex/data[]`；`totalPages` 是计算 getter，只有目标 HTTP mapper / contract fixture 证明后才能进入具体契约。
-- `PageQuery` 客户端输入只允许 `pageIndex/pageSize/orderBy/orderDirection/groupBy`（后四项按 profile 的 optional / whitelist 规则）；`orderDirection` 只能是 `ASC|DESC`。`offset`、`needTotalCount`、`tempTotalCount` 是计算或内部协作字段，禁止成为客户端输入。
+- 采用 YSS 分页协议的 `PageQuery` 客户端输入只允许 `pageIndex/pageSize/orderBy/orderDirection/groupBy`（后四项按 profile 的 optional / whitelist 规则）；`orderDirection` 只能是 `ASC|DESC`。`offset`、`needTotalCount`、`tempTotalCount` 是计算或内部协作字段，禁止从内部 `PageQuery` 泄露为客户端输入。其他已批准公开分页协议按冻结字段映射，不静默改名或套用该字段表。
 - `buildSuccess(...)` 各重载设置 code 的行为并不一致；冻结契约必须测试 `success/code/message/tips/dataType`、nullability 和三种 data shape，不能只测试 data。
 <a id="dto.wire-evidence"></a>
 <!-- yss-rule {"id":"dto.wire-evidence","when":"wire","level":"mandatory","evidence":"code-and-verification"} -->
@@ -74,7 +78,7 @@ description: "实现或核验 YSS Result、PageResult、PageQuery、CommandDTO
 - 不要把 `com.yss.cloud.dto.response` 作为新 API 的 canonical 包，也不要从 Java getter 机械生成 wire schema。
 <a id="dto.no-leak"></a>
 <!-- yss-rule {"id":"dto.no-leak","when":"pagination","level":"mandatory","evidence":"code-and-verification"} -->
-- 不要把 `offset`、`needTotalCount`、`tempTotalCount` 作为客户端分页输入；不要无证据把 `totalPages` 写入所有分页响应。
+- 采用 YSS 分页协议时，不要把内部 `offset`、`needTotalCount`、`tempTotalCount` 作为客户端输入；其他批准协议按冻结契约核验公开字段。不要无证据把 `totalPages` 写入所有分页响应。
 - 若项目已有 `SingleResult`、`PageResult`、`MultiResult` 体系，优先保持一致。
 
 ## 按需读取
@@ -91,10 +95,6 @@ description: "实现或核验 YSS Result、PageResult、PageQuery、CommandDTO
 - POJO 样板可 `controlled-generation`；校验、权限输入、错误结构和序列化行为必须由对应 `behavior-tdd` 工作单元覆盖。
 - 必须加载合同要求的 `lombok`、`mapstruct` 和 `alibaba-java-code-style`，并按统一 `YSS Skill Execution Result` 返回文件、契约测试和偏离。
 
-## 平台与源码门禁
-
-接入、修改、代码生成或给出精确类名/配置前，读取 [后端组件平台与源码门禁](../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-dto --platform-line <line> --source-root <matching-root>` 运行统一 freshness 校验。平台线与源码根不匹配、组件 tree 不一致、组件子树 dirty、索引缺少平台信号，或 Manifest / 组件 GAV 缺少 verified 兼容证据时返回 `blocked`；不得回退另一代索引，也不在业务实现中升级、降级或替换 YSS 组件。既有工程只读分诊可继续，但不得据此宣称跨 Boot/JDK 兼容。
-
 ## 既有契约与特殊协议
 
 只读审计先辨认已锁定的 wire 契约。下载、流式和第三方回调按批准协议检查媒体类型、状态、Header、错误与权限边界；不强套 Result，也不因声称“特殊接口”豁免契约证据。普通已采用 YSS wrapper 的接口继续按 wire profile 检查。旧包/旧协议差距单列迁移，不静默改锁或改公开响应。

package/template/.codex/skills/yss-dto/references/README.md

@@ -29,7 +29,7 @@
 
 **位置**: `../assets/PageQuery.java`
 
-分页查询基础类，所有需要分页的查询参数都应继承此类。
+用于 Application/Infrastructure 内部分页协作；是否继承按批准的工程 Profile 决定。公开 HTTP Page Request 默认不继承此类，只声明冻结 OpenAPI 允许的字段，再由 WebConvertor 转换，避免内部协作字段进入绑定面。
 
 **核心字段**:
 
@@ -57,11 +57,11 @@
 
 基础 DTO 抽象类，用于区分命令（写操作）和查询（读操作）对象。
 
-- **CommandDTO**: 实现 `Serializable` 接口，所有命令参数应继承此类。
-- **QueryDTO**: 继承自 `CommandDTO`，所有查询参数应继承此类。
+- **CommandDTO**: 实现 `Serializable` 接口；当前工程采用此体系时，写操作参数优先继承。
+- **QueryDTO**: 继承自 `CommandDTO`；Application/Infrastructure 内部读参数按批准 Profile 使用它或 `PageQuery`，不据此扩大公开请求字段。
 
 ## 使用场景
 
-1. **API 响应**: 所有 Controller 方法应返回 `Result` 或其子类（如 `PageResult`, `SingleResult`）。
+1. **API 响应**: 普通接口已采用 YSS wrapper 时保持 `Result` 或其派生体系。下载、流式和第三方回调按批准协议核验媒体类型、状态、Header、错误与权限边界，不强套 wrapper，也不豁免契约证据。
 2. **分页查询**: `PageQuery` 用于 Application/Infrastructure 内部协作；公开 HTTP Page Request 默认只声明冻结 OpenAPI 允许的字段，再由 WebConvertor 转换，避免内部字段被继承到绑定面。MyBatis 拦截器所需形状必须由 Query Port 集成测试证明。
 3. **参数封装**: 使用 `CommandDTO` 封装增删改参数，使用 `QueryDTO` 封装查询参数，保持代码语义清晰。

package/template/.codex/skills/yss-dto/references/wire-validation-checklist.md

@@ -1,14 +1,14 @@
 ## 检查清单
 
-- 分页字段名是否和框架约定一致。
+- 分页字段名是否与已批准公开协议一致；采用 YSS 分页协议时对齐 wire profile。
 <a id="dto.sort"></a>
 <!-- yss-rule {"id":"dto.sort","when":"pagination","level":"mandatory","evidence":"code-and-verification"} -->
 - `orderBy` / `groupBy` 是否经过 Repository 白名单映射，禁止直接拼接 SQL。
 - Application Query Port / Infrastructure 是否收到批准的分页语义；Domain Gateway 不接收 `PageQuery`。
 - 新增 DTO 是否与现有序列化和校验方式兼容。
 - 返回结构是否和前端或上游调用方契约一致。
-- 是否通过 `scripts/verify-yss-dto-openapi-profile`，并引用 profile 版本。
-- wrapper extension、`YssResultMeta`、`allOf`、具体 data schema 和方向性是否逐 endpoint 对齐。
-- 是否有针对 `offset` / `needTotalCount` / `tempTotalCount` 的负向断言，以及对 `totalPages` 的目标 mapper 证据。
+- 采用 YSS wrapper / 分页协议时，是否通过 `scripts/verify-yss-dto-openapi-profile`，并引用 profile 版本。
+- 采用 YSS wrapper 的 endpoint，其 wrapper extension、`YssResultMeta`、`allOf`、具体 data schema 和方向性是否对齐；特殊协议检查实际媒体类型、状态、Header、错误与权限边界。
+- 采用 YSS 分页协议时，是否有针对内部 `offset` / `needTotalCount` / `tempTotalCount` 泄露的负向断言；其他批准协议是否逐项绑定冻结公开字段。公开 `totalPages` 是否有目标 mapper / fixture 证据。
 - Controller、Application Service、Domain、Repository 之间是否存在 DTO/VO/DO/PO 混穿。
 - 前端 Orval 或调用方是否依赖当前返回包装结构。

package/template/.codex/skills/yss-excel-mvc/SKILL.md

@@ -7,6 +7,10 @@ description: "实现或排查 YSS Spring MVC Excel 导入导出、RequestExcel
 
 用于处理基于注解的 Excel 导入导出能力。
 
+## 平台与源码门禁
+
+接入、修改、代码生成或提供精确类名/配置前，必须读取并执行 [共享平台与源码门禁](../yss-skill-source-index-refresh/references/backend-component-platform-compatibility.md)，以 `--skill yss-excel-mvc` 校验批准的平台线及匹配源码根。缺失、错配或漂移返回 `blocked`；不跨代回退，不在业务实现中升级、降级或替换组件。只读分诊可继续，但须标注未完成源码核验，不能据此宣称跨 Boot/JDK 兼容。
+
 ## 何时使用
 
 - 用户要新增 Excel 导入接口。
@@ -64,7 +68,3 @@ description: "实现或排查 YSS Spring MVC Excel 导入导出、RequestExcel
 - 源码索引：`references/source-index.md`
 - 注解与返回结构：`assets/RequestExcel.java`、`assets/ResponseExcel.java`、`assets/ExcelDynamicData.java`
 - MVC 解析器：`assets/RequestFastExcelArgumentResolver.java`、`assets/ResponseFastExcelReturnValueHandler.java`
-
-## 平台与源码门禁
-
-接入、修改、代码生成或给出精确类名/配置前，读取 [后端组件平台与源码门禁](../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-excel-mvc --platform-line <line> --source-root <matching-root>` 运行统一 freshness 校验。平台线与源码根不匹配、组件 tree 不一致、组件子树 dirty、索引缺少平台信号，或 Manifest / 组件 GAV 缺少 verified 兼容证据时返回 `blocked`；不得回退另一代索引，也不在业务实现中升级、降级或替换 YSS 组件。既有工程只读分诊可继续，但不得据此宣称跨 Boot/JDK 兼容。

package/template/.codex/skills/yss-exception/SKILL.md

@@ -5,61 +5,55 @@ description: "接入或排查 YSS 统一异常、错误码、异常处理器与
 
 # yss-exception
 
-Use this skill for YSS 异常组件. Keep implementation grounded in the local project and resolvable YSS backend component source.
+处理 YSS 业务、系统及未知异常的错误码、日志和 HTTP 映射；结论使用当前项目契约及匹配的平台源码。
 
-中文说明：本技能用于 YSS 异常组件。执行时优先读取源码索引，避免凭记忆猜类名、配置项或接入方式。
+## 平台与源码门禁
 
-## Source Index First
+接入、修改、代码生成或提供精确类名/配置前，必须读取并执行 [共享平台与源码门禁](../yss-skill-source-index-refresh/references/backend-component-platform-compatibility.md)，以 `--skill yss-exception` 校验批准的平台线及匹配源码根。缺失、错配或漂移返回 `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-exception`
+## 源码定位
 
-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-exception` 仅是模块路径提示。
 
-## Workflow
+## 工作流
 
-1. Read `references/source-index.md`, then read `readme.md` before changing exception behavior.
-2. Classify the failure as business exception, known system exception, or unknown exception.
-3. Use `ExceptionFactory` and `ResultErrorCode` conventions instead of ad-hoc runtime exceptions when creating YSS component errors.
-4. Check `YssGlobalExceptionProperties` when global exception output/logging behavior is configurable.
-5. Keep logging semantics aligned: business exceptions usually do not require error-stack logging; system/unknown exceptions usually do.
-6. In the `target-domain-model` profile, Domain owns stable error meaning and parameters but does not depend directly on YSS `BizException` or HTTP. Translate at the Web boundary after verifying the component handler precedence.
+1. 修改异常行为前，按平台索引定位当前组件源码与可读取的 `readme.md`。
+2. 区分业务异常、已知系统异常和未知异常。
+3. 创建 YSS 组件错误时使用 `ExceptionFactory` 与 `ResultErrorCode` 约定，不临时构造无明确语义的 runtime exception。
+4. 命中全局异常输出或日志配置时核验 `YssGlobalExceptionProperties`。
+5. 保持异常与日志语义一致：业务异常通常不记 Error 堆栈；系统和未知异常通常需要。
+6. `target-domain-model` 的稳定错误含义与参数归 Domain，不直接依赖 YSS `BizException` 或 HTTP；先验证组件 handler 优先级，再在 Web 边界翻译。
 7. MVC Profile 的稳定业务错误归 service/core；Repository 保留 cause；server 持有 HTTP 映射与脱敏。不要为了复用错误码引入 Domain 层或让 core 依赖 client。分层依据 `.template-spec/agents/backend-architecture-profiles.md`。
 
-## Boot 3 Current Source Behavior
+## Boot 3 行为
 
 - 以下当前行为针对 `boot3-java17`；Boot 2 旧工程必须读取其独立索引，旧行为只用于迁移识别。
-- `GlobalExceptionAdvice` maps `BizException` to HTTP 400. Unknown `Exception`, `RuntimeException`, and `NullPointerException` map to HTTP 500 and return a sanitized `SysException` with `ResultErrorCode.INTERNAL_ERROR` instead of raw exception text.
-- `MaxUploadSizeExceededException` maps to HTTP 413 (`PAYLOAD_TOO_LARGE`) with `ResultErrorCode.MAX_UPLOAD_SIZE_EXCEEDED`.
-- System and unknown failures are recorded with the SLF4J logger. `yss.exception.level=debug` adds a logger-backed debug stack trace; it never calls `Throwable#printStackTrace()`.
-- Every handled response attaches or reuses a trace id in MDC and exposes it through the `X-Trace-Id` response header. The public body does not contain the raw localized exception or stack trace.
-- Validation binding failures become `SysException(PARAM_VALIDATION_ERROR)`. Coordinate changes with `yss-validation` and contract tests.
-
-## Source-Backed Exception Semantics
-
-- `BizException`: clear business meaning, generally no Error log and no retry.
-- `SysException`: known system problem, Error log, retry may be possible.
-- unknown `Exception`: full stack log, retry may be possible.
-
-## Checklist
-
-- Required dependency or starter module is present.
-- Error code/message are meaningful to API consumers.
-- Response messages are sanitized and do not expose raw RuntimeException or localized exception details.
-- For affected boot3-java17 HTTP seams, assert the documented business 4xx, unknown/runtime 5xx and trace header behavior. Assert upload 413 only for upload-limit impact. Boot 2 assertions follow its own source and frozen contract; do not import Boot 3 behavior into it.
-- Business validation failures are not reported as unknown system errors.
-- Stack traces are preserved in structured logger output for unknown/system failures, never printed directly to stderr or serialized to clients.
-- Retry guidance matches exception type.
-- Known system failures use `ExceptionFactory.sysException(..., cause)`; Application code does not replace them with ad-hoc `RuntimeException`.
-- Endpoint tests cover the failure types actually affected by this change; upload-limit tests apply only to upload endpoints or changed upload handling. Public messages must follow the selected platform contract and never leak protected exception details.
-
-## 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.
-
-## 平台与源码门禁
-
-接入、修改、代码生成或给出精确类名/配置前，读取 [后端组件平台与源码门禁](../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-exception --platform-line <line> --source-root <matching-root>` 运行统一 freshness 校验。平台线与源码根不匹配、组件 tree 不一致、组件子树 dirty、索引缺少平台信号，或 Manifest / 组件 GAV 缺少 verified 兼容证据时返回 `blocked`；不得回退另一代索引，也不在业务实现中升级、降级或替换 YSS 组件。既有工程只读分诊可继续，但不得据此宣称跨 Boot/JDK 兼容。
+- `GlobalExceptionAdvice` 将 `BizException` 映射到 HTTP 400；未知 `Exception`、`RuntimeException` 和 `NullPointerException` 映射到 HTTP 500，返回脱敏的 `SysException` 与 `ResultErrorCode.INTERNAL_ERROR`，不返回异常原文。
+- `MaxUploadSizeExceededException` 映射到 HTTP 413（`PAYLOAD_TOO_LARGE`）与 `ResultErrorCode.MAX_UPLOAD_SIZE_EXCEEDED`。
+- 系统和未知失败使用 SLF4J logger；`yss.exception.level=debug` 增加 logger debug 堆栈，不调用 `Throwable#printStackTrace()`。
+- 每个处理响应在 MDC 中附加或复用 trace id，并通过 `X-Trace-Id` 响应头公开；正文不含原始 localized exception 或堆栈。
+- 校验绑定失败转为 `SysException(PARAM_VALIDATION_ERROR)`；修改时协同 `yss-validation` 与契约测试。
+
+## 异常语义
+
+- `BizException`：有明确业务含义，通常不记 Error 日志、不重试。
+- `SysException`：已知系统问题，记 Error 日志，是否可重试需按场景判断。
+- 未知 `Exception`：保留完整堆栈日志，是否可重试需按场景判断。
+
+## 验收
+
+- 核验所需依赖或 starter 已进入实际工程。
+- 错误码与消息对 API 消费方有明确含义。
+- 公开消息已脱敏，不暴露原始 RuntimeException 或 localized exception 细节。
+- 对受影响的 `boot3-java17` HTTP seam 验证业务 4xx、未知/runtime 5xx 与 trace header；仅上传限制影响验证 413。Boot 2 使用其独立源码与冻结合同，不引入 Boot 3 断言。
+- 业务校验失败不归为未知系统错误。
+- 未知/系统失败的堆栈保留在结构化日志中，不直接打印 stderr 或序列化给客户端。
+- 重试建议与异常类型及实际用例一致。
+- 已知系统失败使用 `ExceptionFactory.sysException(..., cause)`，Application 不改为无明确语义的 `RuntimeException`。
+- Endpoint 测试覆盖实际受影响的失败类型；仅上传端点或上传处理变更执行上传限制测试。公开消息符合所选平台合同，不泄露受保护异常细节。
+
+## 修改边界
+
+- 类名和配置 key 先核验当前索引与源码，不凭记忆补造。
+- 使用组件已有扩展 seam，不以业务本地框架代码替换。
+- 保持当前组件任务范围；扩展到其他组件须有用户要求或重新路由依据。