create-yss-spec 3.5.6 → 3.5.8

package/template/.cursor/skills/theme-token-usage/SKILL.md

@@ -20,12 +20,12 @@ description: "实现或修复 Vue3 YSS UI 主题、交互状态色与动态换
 
 ## 开发前检查
 
-1. 读取当前微应用的 `packages/src/styles/variables.less`、主题 store/config 和相近页面，确认真实 Token 名称与运行时同步逻辑。
+1. 从目标工程实际的主题入口、store/config 和相近页面定位 Token 声明与同步逻辑；`variables.less` 只作为存在时的路径线索。当前 bundled 骨架使用 `packages/src/config/theme.json`、`packages/src/store/theme.ts`、`packages/src/styles/index.less` 与 `ThemeScope.vue`。
 2. 确认主应用传入的 `colorPrimary` 最终是否同步到 Ant Design ConfigProvider、YSS CSS 变量和 VXE 变量。
 3. 搜索本次改动涉及的硬编码色值，覆盖 SFC style、`style.less`、内联 `style`、`:style`、TS 配置、SVG `fill/stroke`。
 4. 区分“主题消费代码”和“主题定义代码”；禁止机械替换主题源文件中的合法默认色板。
 
-> 变量在 `:root` 中声明，不代表它会随运行时主题更新。必须同时检查主题同步代码是否写入该变量。
+> 变量在 `:root` 或应用容器中声明，不代表它会随运行时主题更新。必须同时检查主题同步代码是否写入该变量，以及消费节点是否处于相同作用域。
 
 ## Token 选择
 
@@ -65,8 +65,9 @@ box-shadow: 0 0 0 3px color-mix(in srgb, var(--primary-color, #3371ff) 15%, tran
 
 ## 标准代码骨架
 
+下面只说明语义 Token 的消费方式；变量名称、fallback 与默认值须先核对目标工程。主题已由应用入口注入时，不另加不存在的 Less 导入。
+
 ```less
-@import url('@/styles/variables.less');
 
 .module-card {
   color: var(--text-color, rgba(0, 0, 0, 0.88));
@@ -94,7 +95,7 @@ box-shadow: 0 0 0 3px color-mix(in srgb, var(--primary-color, #3371ff) 15%, tran
 }
 ```
 
-仅在 JS、图表或 Canvas 必须读取计算后色值时，优先使用 Ant Design Vue `theme.useToken()`；若消费微应用 CSS 变量，则通过 `getComputedStyle(document.documentElement)` 读取，不复制默认色板到业务常量。
+仅在 JS、图表或 Canvas 必须读取计算后色值时，优先使用当前 ConfigProvider 内的 Ant Design Vue `theme.useToken()`。消费 CSS 变量时，对实际获得主题变量的应用容器或其消费节点调用 `getComputedStyle()`；当前 bundled 微应用只向自己的容器同步变量，不读取或写入宿主 `documentElement`。只有已核验主题同步到文档根节点的独立应用，才从该根节点读取。不复制默认色板到业务常量。
 
 ## 验证流程
 
@@ -117,7 +118,7 @@ box-shadow: 0 0 0 3px color-mix(in srgb, var(--primary-color, #3371ff) 15%, tran
 
 ## 失败兜底策略
 
-- 找不到 Token 时，先查项目 `variables.less`、主题 store/config 和 `llms-full.txt`；禁止猜测变量名。
+- 找不到 Token 时，先查项目实际主题入口、store/config 和匹配版本的文档；`variables.less` 存在时才读取，禁止猜测变量名或创建同名文件充当输入。
 - 只有颜色值但没有语义 Token 时，先在统一主题源补充语义变量和运行时同步，再在页面消费。
 - 第三方组件不跟随主题时，优先通过 ConfigProvider/component token 或其官方 CSS 变量桥接；最后才使用受控的深度样式覆盖。
 - 浏览器目标不支持 `color-mix()` 时，在主题层生成并同步明确的透明态变量；不要在各页面散落固定透明色。

package/template/.cursor/skills/wayfinder/references/chart-map.md

@@ -7,8 +7,8 @@
 User invokes with a loose idea.
 
 1. **Name the destination.** Run a `/grilling` and `/domain-modeling` session to pin down what this map is finding its way to — the spec, decision, or change. The destination fixes the scope, so it's settled first.
-2. **Map the frontier.** Grill again, **breadth-first** this time: fan out across the whole space rather than deep on any one thread, surfacing the open decisions and the first steps takeable now. **If this surfaces no fog** — the way to the destination is already clear, the whole journey small enough for one session — you don't need a map. Stop and ask the user how they'd like to proceed.
+2. **Map the frontier.** Grill again, **breadth-first** this time: fan out across the whole space rather than deep on any one thread, surfacing the open decisions and the first steps takeable now. If no open decision remains and the work fits one session, return the settled destination, scope and evidence to the active orchestrator. Continue within the existing authorization; ask only for a missing real decision or new authorization.
 3. **Create the map** (label `wayfinder:map`): Destination and Notes filled in, Decisions-so-far empty, the fog sketched into **Not yet specified**.
 4. **Create the tickets you can specify now** as child issues of the map — then wire blocking edges in a **second pass** (issues need ids before they can reference each other). Wiring sorts them into the frontier and the blocked; everything you can't yet specify stays in the fog — the **Not yet specified** section.
-5. **Fire the research subagents.** For each `research` ticket you just created, spin up a `/yss-research` subagent to resolve it in parallel, capturing its findings on a throwaway `research/<name>` branch with a context pointer from the ticket. `/research` remains only as a deprecated compatibility alias.
+5. **Dispatch research.** Route independent research tickets to `yss-research` when the runtime supports delegation; otherwise research in the current session. Follow the registered task-package and evidence contracts, and link the resulting sources from the ticket. Read-only intake uses schema v2 with empty write scope; formal research requires a new owner-issued task package. Template maintenance evidence stays in the registered external maintenance directory. Research does not require creating a Git branch.
 6. Stop — charting is one session's work; it hand-resolves nothing.

package/template/.cursor/skills/wayfinder/references/ticket-types.md

@@ -6,7 +6,7 @@
 
 Every ticket is either **HITL** — human in the loop, worked _with_ a human who speaks for themselves — or **AFK**, driven by the agent alone. A HITL ticket only resolves through that live exchange; the agent never stands in for the human's side of it (a grilling agent that answers its own questions has broken this).
 
-- **Research** (AFK): Reading documentation, third-party APIs, or local resources like knowledge bases to surface a fact a decision waits on. Resolved by a `/yss-research` **subagent** (`/research` is a deprecated alias). Use when knowledge outside the current working directory is required.
+- **Research** (AFK): Reading documentation, third-party APIs, or local resources to surface a fact a decision waits on. Route to `yss-research`, delegating independent reading when supported. Use when a decision needs evidence unavailable in the current inputs; local evidence and external sources follow the same source policy.
 - **Prototype** (HITL): Raise the fidelity of the discussion by making a cheap, rough, concrete artifact to react to — an outline, a rough take, a stub, or UI/logic code via the /prototype skill. Links the prototype as an asset. Use when "how should it look" or "how should it behave" is the key question.
 - **Grilling** (HITL): Conversation. The default case. Always invoke the /grilling and /domain-modeling skills.
 - **Task** (HITL or AFK): Manual work that must happen before a _decision_ can be made — nothing to decide, prototype, or research, but the discussion is blocked until it's done. Signing up for a service so its API can be judged, provisioning access, moving data so its shape can be seen. This is the one type that _does_ rather than decides — and it earns its place by unblocking a decision, not by delivering the destination. The agent drives it alone where it can (AFK); otherwise it hands the human a precise checklist (HITL). Resolved when the work is done; the answer records what was done and any resulting facts (credentials location, new URLs, row counts) later tickets depend on.

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

@@ -5,24 +5,22 @@ description: "在 Vue3 YSS UI 中对接 Orval API；核验生成方法、mutator
 
 # API 集成 Skill
 
-本目录是 API 集成的 canonical 技能；历史名称 `api-integration` 仅通过注册表和 实现合同编译器 alias 解析，不再维护第二份内容。
+本技能的 canonical 名称为 `yss-api-integration`。历史名称 `api-integration` 只由注册表与实现合同编译器解析，不维护第二份内容。
 
-目录、frontmatter、注册表 ID 和 实现合同编译器 canonical 闭包键均为 `yss-api-integration`；历史名称 `api-integration` 只在注册表和 实现合同编译器 alias 表中解析为本技能。
-
-## 📋 目标
+## 目标
 
 帮助 AI 正确使用基于 **Orval** 生成的 API 客户端：
 
-- ✅ 正确导入 API 函数
-- ✅ 统一错误处理与 Toast 门禁
-- ✅ Loading 状态管理
-- ✅ 长整型 ID 精度保持
-- ✅ TypeScript 类型安全
+- 正确导入 API 函数
+- 统一错误处理与 Toast 门禁
+- Loading 状态管理
+- 长整型 ID 精度保持
+- TypeScript 类型安全
 
-## 🔍 前置条件
+## 前置条件
 
 1. **契约状态已明确**：
-   - 已有生成客户端：可以直接集成。
+   - 已有生成客户端：先核验冻结契约、JSON 派生记录和真实导出，输入当前且一致时可以直接集成。
    - 新增或变更 API：必须先在 `docs/.scratch/<feature>/api/<feature>.yaml` 形成 OpenAPI Draft，经工程基线 / 架构 / Spec Delta 设计和设计审查后 Freeze。冻结的 OpenAPI YAML 是唯一权威，JSON 仅为它的受控派生物。
    - 如果接口尚未冻结、JSON 派生记录缺失或生成函数不存在，先回到 `yss-product-lifecycle` / `yss-openapi-governance`，不要手写临时路径、DTO 或响应结构。
 2. **API 已生成**：在目标前端实现仓库中，按其既有的手动代码生成命令（例如 `pnpm generate:api`）刷新 API；本 Harness 不配置、不执行该命令，也不把它加入 CI。
@@ -41,9 +39,9 @@ description: "在 Vue3 YSS UI 中对接 Orval API；核验生成方法、mutator
 ```
 
 1. 读取 `yss-openapi-governance` 产出的 OpenAPI Freeze 记录和 `docs/.scratch/<feature>/api/<feature>-json-export.md`；确认 YAML SHA-256、JSON SHA-256、Redocly CLI 版本、lockfile 引用和 JSON 校验均通过。治理 JSON 的唯一产物路径是 `docs/.scratch/<feature>/api/<feature>.json`。
-2. JSON 导出由 `yss-openapi-governance` 负责。`api-integration` 只接受该 skill 留下的派生记录；记录中的锁定 `redocly bundle` 命令是治理导出证据，不是前端集成任意重跑的入口。
+2. JSON 导出由 `yss-openapi-governance` 负责。`yss-api-integration` 只接受该 skill 留下的派生记录；记录中的锁定 `redocly bundle` 命令是治理导出证据，不是前端集成任意重跑的入口。
 3. **受控交接**：若前端实现仓库需要本地输入，批准的 Cross-repo 子合同或项目脚本只能将上述治理 JSON 原样物化为 `<frontend>/openapi/openapi.json`；物化后的 SHA-256 必须与派生记录一致。禁止从 URL、Draft YAML、后端运行时或任意本地文件临时替换输入。
-4. `api-integration` 只核对 JSON 派生记录、交接路径和 SHA-256，并把原始 JSON 交给既有前端代码生成流程；本 Harness 可只读核对目标前端的生成器配置与真实导出，但不修改该配置，不在此仓库执行生成，也不建立生成 CI 门禁。若 JSON SHA 与派生记录不一致，停止交接并回到治理流程。
+4. `yss-api-integration` 只核对 JSON 派生记录、交接路径和 SHA-256，并把原始 JSON 交给既有前端代码生成流程；本 Harness 可只读核对目标前端的生成器配置与真实导出，但不修改该配置，不在此仓库执行生成，也不建立生成 CI 门禁。若 JSON SHA 与派生记录不一致，停止交接并回到治理流程。
 5. 目标前端项目在需要时手动运行其既有生成命令、类型检查和受影响组件 / API 测试；将实际命令、结果、生成输入 SHA 和偏离写入 `YSS Skill Execution Result`。
 
 ## 真实 mutator 响应契约
@@ -81,44 +79,9 @@ pnpm generate:api
 - 不得根据文档示例假定工厂一定名为 `getApi()`；Orval `title` 配置会影响真实名称。
 - 请求/响应 DTO 必须从当前生成的 `schemas` 导入，禁止重复声明。
 
-## 标准代码骨架
-
-以微应用的真实 `getApiApi()` 产物为例：
-
-```typescript
-import { reactive, ref } from 'vue';
-import { getApiApi } from '@/api/generated/quality';
-import type { QualityBusinessRuleVO, QualityRulePage } from '@/api/generated/quality/schemas';
-
-const { pageQualityRule } = getApiApi();
-
-/** 管理质量规则列表请求和分页状态。 */
-export const useQualityRuleList = () => {
-  const loading = ref(false);
-  const dataList = ref<QualityBusinessRuleVO[]>([]);
-  const query = reactive<QualityRulePage>({ pageIndex: 1, pageSize: 20, ruleName: '' });
-  const total = ref(0);
-
-  /** 加载规则列表。 */
-  const fetchData = async (): Promise<void> => {
-    loading.value = true;
-    try {
-      const res = await pageQualityRule(query);
-      dataList.value = res.data ?? [];
-      total.value = res.totalCount ?? 0;
-    } catch {
-      dataList.value = [];
-      total.value = 0;
-    } finally {
-      loading.value = false;
-    }
-  };
-
-  return { loading, dataList, query, total, fetchData };
-};
-```
+## 按需示例
 
-> 如果所在项目已生成 `pageQualityRule` 具名导出，直接导入该函数，删除上面的工厂实例行。
+首次组织列表请求或需比较具名导出与工厂导出时，读取 [Orval 列表示例](references/orval-list-example.md)。示例中的业务名称与响应字段仅作已核验版本的用法说明，目标工程仍消费自己的冻结 DTO 和真实导出。
 
 ## 长整型与数值类型
 

package/template/.cursor/skills/yss-api-integration/references/orval-list-example.md

@@ -0,0 +1,38 @@
+## 标准代码骨架
+
+以微应用的真实 `getApiApi()` 产物为例：
+
+```typescript
+import { reactive, ref } from 'vue';
+import { getApiApi } from '@/api/generated/quality';
+import type { QualityBusinessRuleVO, QualityRulePage } from '@/api/generated/quality/schemas';
+
+const { pageQualityRule } = getApiApi();
+
+/** 管理质量规则列表请求和分页状态。 */
+export const useQualityRuleList = () => {
+  const loading = ref(false);
+  const dataList = ref<QualityBusinessRuleVO[]>([]);
+  const query = reactive<QualityRulePage>({ pageIndex: 1, pageSize: 20, ruleName: '' });
+  const total = ref(0);
+
+  /** 加载规则列表。 */
+  const fetchData = async (): Promise<void> => {
+    loading.value = true;
+    try {
+      const res = await pageQualityRule(query);
+      dataList.value = res.data ?? [];
+      total.value = res.totalCount ?? 0;
+    } catch {
+      dataList.value = [];
+      total.value = 0;
+    } finally {
+      loading.value = false;
+    }
+  };
+
+  return { loading, dataList, query, total, fetchData };
+};
+```
+
+> 如果所在项目已生成 `pageQualityRule` 具名导出，直接导入该函数，删除上面的工厂实例行。

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

@@ -1,17 +1,23 @@
 ---
 name: yss-application
-description: Use when implementing YSS application use cases, transaction boundaries, cross-aggregate orchestration, idempotency, or application-level DTO conversion.
+description: 实现或排查 YSS 用例编排、事务边界、跨聚合协作、幂等和用例层模型转换；按已登记 DDD 或 MVC 架构执行。
 ---
 
 # yss-application
 
-## 架构分流（先执行）
+## 任务分流
 
-读取当前合同的 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；组件、安全、批准合同、允许路径及执行证据规则仍共用。
+- 只读审计先读取实际用例、工程登记和可读契约；不要求先补批准 Slice 或生成 Manifest，业务 Spec 缺失须记录。
+- 整改消费批准且当前的 Slice、已确认行为 seam 与登记的 Application/service/core 映射，保持允许写范围。
+- 新工程按生成式 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 称为受支持。
 
 以下 Application / Domain Gateway / Infrastructure / Web module 叙述仅适用于 target-domain-model；MVC 的 service/core/repository/server/client 所有权由所选 Profile 引用定义。
 
-Application 层用例编排 skill。负责协调 Domain 与 Gateway，定义事务边界和跨聚合流程，不承载核心领域规则。
+DDD 用例层协调 Domain 与 Gateway，定义事务边界和跨聚合流程，不承载核心领域规则。MVC 不执行 DDD 专属规则，也不加载其分层 guide；组件、安全、批准合同、允许路径及执行证据规则共用。
 
 ## 何时使用
 
@@ -71,4 +77,4 @@ Application 层用例编排 skill。负责协调 Domain 与 Gateway，定义事
 
 ## 既有工程与条件适用
 
-只读审计不要求先补批准 Slice；业务 Spec 缺失须记录。整改消费批准 Slice、已确认行为 seam 与登记的 Application/service/core 映射，不要求生成 Manifest。事务、幂等、提交后副作用按实际用例评估；未命中不创建空事务、空端口或空恢复实现。DDD 的领域规则归 Domain，MVC 规则允许留在已登记 service/core。
+事务、幂等、提交后副作用按实际用例评估；未命中不创建空事务、空端口或空恢复实现。DDD 的领域规则归 Domain，MVC 规则允许留在已登记 service/core。

package/template/.cursor/skills/yss-audit-log/SKILL.md

@@ -7,6 +7,10 @@ description: "接入或排查 YSS AuditLog 的 SpEL 摘要、异步发布、订
 
 用于处理 `yss-component-audit-log` 的接入、排障和代码修改。
 
+## 平台与源码门禁
+
+接入、修改、代码生成或提供精确类名/配置前，必须读取并执行 [共享平台与源码门禁](../yss-skill-source-index-refresh/references/backend-component-platform-compatibility.md)，以 `--skill yss-audit-log` 校验批准的平台线及匹配源码根。缺失、错配或漂移返回 `blocked`；不跨代回退，不在业务实现中升级、降级或替换组件。只读分诊可继续，但须标注未完成源码核验，不能据此宣称跨 Boot/JDK 兼容。
+
 ## 何时使用
 
 - 用户要求接入或修改审计日志。
@@ -31,13 +35,15 @@ description: "接入或排查 YSS AuditLog 的 SpEL 摘要、异步发布、订
 
 ## 接入检查清单
 
+下述 Boot 3 要点是所登记平台基线的核验项；只有匹配源码门禁通过，才能作为当前精确结论。索引或源码漂移时将受影响结论标为待核验并停止精确接入指导，不借历史快照补齐。
+
 - 启动类是否启用了类似 `@EnableAuditLog` 的能力。
 - 目标方法是否是可被 AOP 代理拦截的 Spring Bean 方法。
 - `@AuditLog` 是否标在正确的方法上。
 - `boot3-java17` 的 SpEL 根上下文只暴露 ASCII key：`args` 和 `result`；例如 `#{args[0]}`、`#{result[name]}`。方法参数名不会自动进入上下文。
 - `args` 仅在 `@AuditLog(isNeedArgs = true)` 时写入，`result` 仅在 `isNeedResult = true` 时写入；表达式引用未启用的 key 属于配置错误，必须由组件 seam 测试覆盖。
 - `boot3-java17` 不再使用中文 context key，也不得把 Boot 2 的历史模板直接复制到 Boot 3。处理旧模板时先读取所选平台线索引并显式迁移。
-- `yss.audit.enabled` 是否开启；`sendSysManageEnabled` 与 `auditLogPrintEnabled` 在当前实现中不会自动阻止订阅器注册，需按源码验证，不能假设开关生效。
+- 按匹配源码核验 `yss.audit.enabled`、`sendSysManageEnabled` 与 `auditLogPrintEnabled` 是否控制订阅器注册及投递，不能从字段名或历史快照推断开关生效。
 - 审计身份由 `CurrentUserProvider` 提供；不得在审计切面中重新解析 Header 或未验签 JWT。
 
 ## 排障顺序
@@ -51,7 +57,7 @@ description: "接入或排查 YSS AuditLog 的 SpEL 摘要、异步发布、订
 7. 异步线程池或事件发布异常是否被吞掉。
 8. 参数位置、返回值字段、异常分支是否满足摘要模板。
 
-`boot3-java17` 审计切面当前是 `@AfterReturning`，只记录成功返回；异常审计、参数脱敏、队列满丢弃、线程池关闭、重试和幂等必须单独设计并测试。组件测试至少覆盖 `#{result[name]}`、`args` / `result` 资源写入和可信身份来源。
+核验 `boot3-java17` 审计切面的 advice 与成功/异常边界；所登记平台基线使用 `@AfterReturning` 记录成功返回，源码漂移时该结论待核验。异常审计、参数脱敏、队列满丢弃、线程池关闭、重试和幂等须按当前组件能力及批准设计单独核验和测试，不能由旧基线推断已覆盖。组件测试至少覆盖 `#{result[name]}`、`args` / `result` 资源写入和可信身份来源。
 
 ## 修改约束
 
@@ -68,7 +74,3 @@ description: "接入或排查 YSS AuditLog 的 SpEL 摘要、异步发布、订
 - 审计切面与 SpEL 解析：`assets/AuditLogAspect.java`
 - 异步发布链路：`assets/YssAuditPublishService.java`
 - 默认订阅器：`assets/YssAuditLogPrintSubscriberImpl.java`、`assets/YssAuditLogSysManagerSubscriberImpl.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-audit-log --platform-line <line> --source-root <matching-root>` 运行统一 freshness 校验。平台线与源码根不匹配、组件 tree 不一致、组件子树 dirty、索引缺少平台信号，或 Manifest / 组件 GAV 缺少 verified 兼容证据时返回 `blocked`；不得回退另一代索引，也不在业务实现中升级、降级或替换 YSS 组件。既有工程只读分诊可继续，但不得据此宣称跨 Boot/JDK 兼容。

package/template/.cursor/skills/yss-audit-log/references/README.md

@@ -1,6 +1,6 @@
-# 参考资料
+# Boot 2 历史审计资料
 
-本文档详细介绍了 `yss-component-audit-log` 组件的核心类和配置类。
+本文件说明 `assets/` 中的 `boot2-java8` 历史快照，仅用于旧工程比对与迁移诊断，不作为当前 Boot 3 实现模板或 freshness 证据。当前平台任务从 [平台索引](source-index.md) 定位匹配源码并执行共享门禁；[入口](../SKILL.md) 中的身份、SpEL 和异步边界同样须与所选平台当前源码核对。
 
 ## 核心类 (Core Classes)
 
@@ -17,7 +17,7 @@
   1. **解析注解**: 获取 `@AuditLog` 中的操作类型、描述、资源类型等信息。
   2. **SpEL 解析**: 如果 `summary` 中包含 `#{...}` 表达式，会解析方法参数和返回值，动态生成日志内容。
   3. **构建消息**:
-     - 收集用户信息（从 JWT 解析）。
+     - 历史快照使用 `AuthUserInfoUtil.currentUserJson()`；特定 `Principal` 返回分支还解析 `id_token`。这段历史行为不构成可信认证依据，不能迁入 Boot 3 的 `CurrentUserProvider` 链路。
      - 收集请求信息（URL, IP, User-Agent）。
      - 收集参数和结果（根据 `isNeedArgs` 和 `isNeedResult` 配置）。
   4. **发布消息**: 调用 `YssAuditPublishService.publish` 将构建好的 `AuditMessage` 发布出去。
@@ -41,14 +41,14 @@
 **位置**: `../assets/YssAuditLogPrintSubscriberImpl.java`
 
 - **功能**: 简单的控制台日志打印，用于开发调试。
-- **开关**: 通过 `yss.audit.auditLogPrintEnabled` 控制。
+- **配置核验**: 历史订阅器快照自身不检查 `auditLogPrintEnabled`。开关是否控制注册或投递须检查实际工程的配置装配，不能从字段名推断生效。
 
 #### YssAuditLogSysManagerSubscriberImpl.java
 
 **位置**: `../assets/YssAuditLogSysManagerSubscriberImpl.java`
 
 - **功能**: 调用 `YssDmSystemManageFeign` 将审计日志发送到系统管理服务进行持久化存储。
-- **开关**: 通过 `yss.audit.sendSysManageEnabled` 控制。
+- **配置核验**: 历史订阅器快照自身不检查 `sendSysManageEnabled`。按实际工程核验配置装配及投递；当前平台行为不由这份快照证明。
 
 ## 关键注解
 

package/template/.cursor/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/.cursor/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/.cursor/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/.cursor/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/.cursor/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/.cursor/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/.cursor/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/.cursor/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 检查。旧包/旧协议差距单列迁移，不静默改锁或改公开响应。