create-yss-spec 3.4.10 → 3.5.2

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

@@ -1,72 +1,28 @@
 ---
 name: yss-distributed-id
-description: "接入或排查 YSS 分布式 ID：Leaf、CosId、号段、雪花算法或 MyBatis 主键注入。"
+description: "接入或排查 YSS 分布式 ID 的 Segment、Snowflake、主键注入与迁移；旧 CosId/远程调用仅按既有平台线分诊。"
 ---
 
 # yss-distributed-id
 
-用于处理 `yss-component-distributed-id` 的配置、接入和问题定位。
+处理 `yss-component-distributed-id` 及 Leaf 消费项目的发号、主键填充与迁移。先从批准的 `platform_configuration.component_platform_line` 选择 [源码索引](references/source-index.md)；Boot 2 的历史能力不能推定为 Boot 3 可用能力。无批准合同的既有工程故障可只读分诊，不据此改策略或宣布兼容。
 
-## 何时使用
+## 接入决策
 
-- 用户要启用分布式 ID。
-- 用户提到 Leaf Segment、Snowflake、CosId、UUID。
-- 用户反馈批量插入未自动注入 ID、ID 冲突、ID 类型不匹配。
+1. 核对实际组件 GAV、平台线、依赖树及当前源码，再确定已有主键策略、注入模式和数据库约束。保持既有 Long 主键及调用方类型，策略变更单独评估数据和 API 影响。
+2. Boot 3 的数值分布式发号使用本地 Leaf Segment / Snowflake；拦截器仍有 String UUID 分支，但它不是数值发号方案。CosId、Feign/远程注入及旧注解参数是迁移分诊线索，不作为新接入选项；Boot 2 维护以其独立源码索引为准。
+3. Boot 3 默认 `local + Segment`：引入组件后核对 DataSource、JDBC 驱动、目标方言建表脚本及 `leaf_alloc`。不发号的应用应显式关闭注入及 Segment；选 Snowflake 时显式启用 Snowflake、关闭 Segment，并验证 worker-id 唯一、时钟回拨处理和节点重启行为。`local` 注入须且只能启用一种算法，不要把 ZooKeeper 当作当前 Snowflake 的默认依赖。
+4. Segment 缺失标签策略、声明、step 和初始水位必须与真实业务表及既有分配记录一致。自动建标签不建表、也不读取业务表最大 ID；迁移前固定停写/切换边界，起点不得低于已分配号段上界，不重置 `leaf_alloc`。
+5. 主键填充同时核对实体注解、插入方法和参数形态。`IdType.AUTO` 保留数据库自增；`ASSIGN_ID` 或显式 Segment/Snowflake 才走组件发号。已有非零值应保留；生成值与 `Long`、十进制 `String`、`Integer` 的转换及溢出必须验证，不能只凭注解推断批量入口已被拦截。
 
-## 工作方式
+## 排障与验证
 
-1. 先识别项目用的是哪种 ID 策略。
-2. 涉及真实类名、配置项、Leaf 服务或批量插入排障时，先读 `references/source-index.md`，再定位源码或文档。
-3. 再看实体注解、拦截器配置和底层表或注册中心依赖是否齐全。
-4. 修改时优先保持现有策略，不轻易切换算法。
+- 启动失败：按自动配置、注入模式、算法开关、DataSource、`leaf_alloc`、方言顺序定位。`disabled` 仅关闭自动注入；完全不用 Segment 时还须核对其算法开关。
+- 重号/错号：核对跨服务业务 tag、控制表唯一键、当前水位、历史号段、Snowflake worker-id 与时钟；先保留现场，不用重建表或清空控制记录排障。
+- 插入缺 ID：核对 `TableId`/生成策略、实体字段类型、当前公开批量方法及 MyBatis 参数包装是否经过拦截器；再检查消费者自定义 `IdentifierGenerator` 是否接管。
+- 行为修改使用组件父 reactor 的根 `./mvnw` 验证启动、单条/批量主键、迁移边界和目标数据库方言；H2 不能证明生产方言。只读故障分诊与已执行验证分别记录。
 
-## 源码索引
-
-- 源码位置不要假设固定目录；先按 `yss-skill-source-index-refresh/references/source-location.md` 定位。
-- 当前技能索引：`references/source-index.md`
-- 重点源码入口通常包括 `EnableDistributedId`、`AutoIdInterceptor`、Leaf 配置、Leaf REST/Feign/gRPC 模块、ID 策略相关类。
-
-当组件源码变化后，用 `yss-skill-source-index-refresh` 刷新索引；刷新或读取前先按源码定位策略确认真实位置。
-
-## 检查清单
-
-- 启动类是否启用了分布式 ID 能力。
-- 当前策略是否与部署条件匹配。
-- 批量插入链路是否会经过拦截器。
-- 实体主键类型与生成策略是否兼容。
-- Leaf Segment 场景下 `leaf_alloc` 是否已初始化。
-- MyBatis/MyBatis-Plus 的插入方法是否绕过了自动 ID 拦截逻辑。
-- 多服务共享号段时，业务 tag/key 是否唯一且稳定。
-
-## 策略建议
-
-- 追求稳定和趋势递增时，优先 Leaf Segment。
-- 依赖 ZooKeeper 且要求高吞吐时，可考虑 Snowflake。
-- 若项目已有 CosId 统一方案，沿用现有生态。
-- 除非业务明确允许，否则不要把 Long 主键切到 String UUID。
-
-## 修改约束
-
-- 不要混用多种主键生成策略而不说明边界。
-- 不要仅改实体注解而忽略底层配置和依赖。
-- 如果用户只是在做普通 MyBatis-Plus 主键配置，不要过度引入新组件。
-- 不要在已有 Long 主键生态里随意改成 String UUID，除非调用方和数据库约束都确认兼容。
-
-## 排障顺序
-
-1. 确认启用注解和 starter 依赖。
-2. 确认实体主键类型、注解和插入方法。
-3. 确认拦截器是否参与 MyBatis 调用链。
-4. Leaf 场景确认服务、号段表和业务 key。
-5. Snowflake/CosId 场景确认机器号、时钟、注册中心或 worker 分配。
-6. 批量插入失败时确认是否调用了项目推荐批量方法。
-
-## 按需读取
-
-- 源码索引：`references/source-index.md`
-- 拦截器与自动注入：`assets/AutoIdInterceptor.java`
-- 启用注解：`assets/EnableDistributedId.java`
-- Leaf 配置相关：`assets/LeafConf.java`
+当前源码入口与平台差异见 [能力与迁移说明](references/README.md)。不要从 Skill 的历史示例或旧资产复制生产源码；精确类名、配置和默认值以选定平台线的当前源码为准。
 
 ## 平台与源码门禁
 

package/template/.codex/skills/yss-distributed-id/agents/openai.yaml

@@ -1,5 +1,5 @@
 version: 1
 interface:
   display_name: "YSS Distributed ID"
-  short_description: "Leaf、CosId 与分布式 ID 接入与配置规范"
-  default_prompt: "Use $yss-distributed-id to configure or debug distributed ID generation, Leaf, CosId, and MyBatis ID injection."
+  short_description: "Leaf Segment、Snowflake 与主键注入排障"
+  default_prompt: "Use $yss-distributed-id to configure or debug platform-bound Leaf Segment, Snowflake, and MyBatis ID injection; treat CosId and remote modes as legacy migration cases."

package/template/.codex/skills/yss-distributed-id/references/README.md

@@ -1,51 +1,15 @@
-# 参考资料
+# 分布式 ID 能力与迁移说明
 
-本文档详细介绍了 `yss-component-distributed-id` 框架的核心组件和实现原理。
+本文件只说明选择和核验边界。类名、配置默认值及方法签名以所选平台线的生成索引和匹配的干净源码为准，不复制组件实现。
 
-## 核心类 (Core Classes)
+| 场景 | Boot 3 / Java 17 当前工作树观察 | 核验重点 |
+|---|---|---|
+| Segment | 本地号段；默认 local + Segment | DataSource、目标方言建表、`biz_tag` 唯一键、已分配水位、缺失标签策略 |
+| Snowflake | 本地节点发号；可配置 worker-id，未指定时按节点地址派生 | 所有实例 worker-id 无冲突、时钟回拨和序列等待；不假设 ZooKeeper 注册 |
+| 主键自动填充 | MyBatis 拦截与 MyBatis-Plus `IdentifierGenerator` 两条入口 | `AUTO` 与 `ASSIGN_ID` 区分、已有值保留、批量参数形态、`Integer` 溢出 |
+| String UUID | 本地拦截器仍有 UUID 字符串分支 | 仅核对显式 UUID 策略及 String 字段，不当作 Segment/Snowflake 的数值主键迁移替代 |
+| CosId、Feign/远程注入 | 当前 Boot 3 主线不提供 | 仅对既有项目按其实际平台线和源码做迁移分诊，不把旧模块写成新接入依赖 |
 
-### 1. AutoIdInterceptor.java
-**位置**: `../assets/AutoIdInterceptor.java`
+Segment 从现有业务表接管 ID 时，先记录业务表最大值、`leaf_alloc.max_id` 和尚未用尽的已分配号段，再在停写窗口确定不回退的起点。缺失标签自动创建不会计算这些值；不得删除或重置控制记录。Snowflake 切换需验证新旧机器位语义及所有活跃节点，不在混合写流量时直接换算法。遗留 `feign_segment` 注解仍是明确的拒绝路径，迁移须清理旧注解及依赖，不能用已有非零 ID 掩盖它。
 
-MyBatis 拦截器，是实现自动 ID 注入的核心。
-
-**拦截逻辑**:
-- **拦截点**: `StatementHandler.prepare` 方法。
-- **判断条件**: 仅拦截 `INSERT` 语句。
-- **处理流程**:
-  1. 获取 SQL 绑定的参数对象 (`parameterObject`)。
-  2. 支持处理单对象、`List`、`Array` 和 `Map` (MyBatis 多参数封装)。
-  3. 遍历参数对象的实体类，检查是否有 `@Entity` (JPA) 或 `@TableName` (MP) 注解。
-  4. 扫描实体字段，查找 `@GeneratedValue` 或 `@TableId` 注解。
-  5. 根据注解指定的策略 (`segment`, `snowflake`, `cosid_segment` 等)，调用对应的 ID 生成器获取 ID。
-  6. 通过反射将 ID 设置到实体的相应字段中。
-
-### 2. EnableDistributedId.java
-**位置**: `../assets/EnableDistributedId.java`
-
-开启分布式 ID 功能的注解。
-
-**属性**:
-- `autoRegister`: 是否自动注册配置，默认为 `true`。
-- `cosid`: 是否开启 CosId 模式，默认为 `false` (即默认使用 Leaf 模式)。
-
-**作用**:
-- 导入 `LeafDataSourceConfiguration` 和 `EnableDistributedImportSelector`，从而根据配置加载相应的 Bean。
-
-### 3. LeafConf.java
-**位置**: `../assets/LeafConf.java`
-
-Leaf 模式的配置类，对应 `spring.leaf` 配置项。
-
-**属性**:
-- `leafSegmentEnable`: 是否开启号段模式。
-- `leafSnowflakeEnable`: 是否开启雪花算法模式。
-
-## ID 生成策略详解
-
-| 策略名称 | 依赖组件 | 描述 | 适用场景 |
-| :--- | :--- | :--- | :--- |
-| **Leaf Segment** | DB (MySQL) | 基于数据库号段，每次从 DB 获取一个号段到内存，高性能，ID 趋势递增。 | 大多数业务场景，高可用要求高。 |
-| **Leaf Snowflake** | Zookeeper | 基于 Twitter 雪花算法，依赖 ZK 进行 WorkerID 管理。 | 对 ID 生成速度要求极高，且不依赖 DB 的场景。 |
-| **CosId Segment** | DB (MySQL) | CosId 的号段模式实现，支持更丰富的配置（如步长动态调整）。 | 需要 CosId 特性或作为 Leaf 的替代方案。 |
-| **UUID** | JDK | 标准 UUID。 | 无需有序、不关心存储空间的场景。 |
+只读分诊可参考当前组件 `readme.md` 和源码路径提示；组件子树 dirty、索引 tree 不一致或兼容证据未 verified 时，这些观察不构成精确接入或发布结论。

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

@@ -25,7 +25,7 @@ Read `references/source-index.md` as a path-hint index whenever the task depends
 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.
-7. MVC Profile 的稳定业务错误归 service/core；Repository 保留 cause；server 持有 HTTP 映射与脱敏。不要为了复用错误码引入 Domain 层或让 core 依赖 client。分层依据 `docs/agents/backend-architecture-profiles.md`。
+7. MVC Profile 的稳定业务错误归 service/core；Repository 保留 cause；server 持有 HTTP 映射与脱敏。不要为了复用错误码引入 Domain 层或让 core 依赖 client。分层依据 `.template-spec/agents/backend-architecture-profiles.md`。
 
 ## Boot 3 Current Source Behavior
 

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

@@ -32,7 +32,7 @@ description: Use when creating a new YSS frontend micro-application from the sta
 
 ## Workflow
 
-采用专职前端 profile 或显式 `frontend_delivery` 绑定时，先按 `docs/process/frontend-backend-delivery.md` 实际核验战略与后端联合交付。缺任一输入只能诊断和回交；输入通过后准备计划/合同，正式实现、生成和恢复仍须当前批准的 Slice Contract 冻结接收摘要。接口或部署版本漂移时重新接收，不复用旧成功输出。
+采用专职前端 profile 或显式 `frontend_delivery` 绑定时，先按 `.template-spec/process/frontend-backend-delivery.md` 实际核验战略与后端联合交付。缺任一输入只能诊断和回交；输入通过后准备计划/合同，正式实现、生成和恢复仍须当前批准的 Slice Contract 冻结接收摘要。接口或部署版本漂移时重新接收，不复用旧成功输出。
 
 1. 确认当前任务已经通过 Harness 入口分诊、逐项目脚手架决定已由真实用户确认，且 schema v4 合同已由生命周期批准、持久化并保持当前。
 2. 确认目标是外部实现仓库；只有用户明确选择时才输出到 Harness 仓库的 `apps/frontend/<project>/`。`apps/frontend/` 只能作为项目容器，`app/frontend/`、`app/backend/` 及其子路径禁止作为输出位置。`git-submodule` 只能在已初始化且附加分支的子仓工作树生成；空 gitlink、detached HEAD、`--force` 覆盖挂载点不得当成普通目录。
@@ -42,7 +42,7 @@ description: Use when creating a new YSS frontend micro-application from the sta
 6. 有 API 影响时核验 OpenAPI Freeze 记录和 JSON 派生记录，将摘要一致的 JSON 原样物化到 `<frontend>/openapi/openapi.json`；`openapi_impact=not-applicable` 时必须有原因并禁止生成 API client。
 7. 保持模板既有的前端代码生成配置不变；本 Harness 只将 SHA-256 一致的 JSON 原样交给既有前端代码生成流程，不修改该配置、不在此仓库执行生成，也不设置生成 CI 门禁。目标前端项目在需要时手动运行其既有命令。
 8. 企业 registry / 认证由目标环境用户级 npm 配置提供，禁止复制来源 `.npmrc` 或 token。实际执行并记录 `pnpm install --frozen-lockfile`、`pnpm lint:check`、`pnpm type-check`、`pnpm build`、`pnpm build:standalone` 的退出码和日志；缺失脚本只能由批准的工程基线提供替代命令。任何必需命令失败都阻断。
-9. 按 `docs/templates/implementation-repo-registry-template.md` 回写前端实现仓库登记。
+9. 按 `.template-spec/templates/implementation-repo-registry-template.md` 回写前端实现仓库登记。
 
 ## Expected Template Shape
 

package/template/.codex/skills/yss-frontend-scaffold-generator/scripts/generate_scaffold.mjs

@@ -28,7 +28,7 @@ function walk(root) {
   });
 }
 function validate(contract, outputDir) {
-  validateJsonSchema(contract, path.join(REPOSITORY_ROOT, "docs/process/schemas/project-scaffold-contract.schema.json"), { label: "Project Scaffold Contract v4" });
+  validateJsonSchema(contract, path.join(REPOSITORY_ROOT, ".template-spec/process/schemas/project-scaffold-contract.schema.json"), { label: "Project Scaffold Contract v4" });
   if (contract.schema_version !== 4 || contract.kind !== "project-scaffold-contract") fail("frontend scaffold requires Project Scaffold Contract schema v4");
   if (contract.status !== "approved" || contract.current_version !== true || !contract.persisted_ref) fail("scaffold contract must be approved, persisted and current");
   if (contract.delivery_role !== "frontend" || contract.scaffold_kind !== "frontend-yss-vue3" || contract.generator_skill !== "yss-frontend-scaffold-generator") fail("contract is not for the YSS frontend generator");

package/template/.codex/skills/yss-frontend-scaffold-generator/scripts/refresh_baseline.mjs

@@ -9,8 +9,8 @@ const assets = path.join(skill, 'assets/data-quality-v1');
 const sha = bytes => `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
 const walk = root => readdirSync(root, { withFileTypes: true }).flatMap(item => item.isDirectory() ? walk(path.join(root, item.name)) : [path.join(root, item.name)]);
 const design = readFileSync(path.join(repository, 'DESIGN.md'));
-const theme = JSON.parse(readFileSync(path.join(repository, 'docs/design/tokens/theme.json')));
-const css = readFileSync(path.join(repository, 'docs/design/tokens/variables.css'), 'utf8');
+const theme = JSON.parse(readFileSync(path.join(repository, '.template-spec/design/tokens/theme.json')));
+const css = readFileSync(path.join(repository, '.template-spec/design/tokens/variables.css'), 'utf8');
 const token = name => css.match(new RegExp(`--${name}: ([^;]+);`))[1];
 const projection = { ...theme, accessibility: { primaryControl: token('yss-color-primary-control'), primaryControlHover: token('yss-color-primary-control-hover') } };
 const generated = { 'DESIGN.md': design, 'packages/src/config/theme.json': Buffer.from(JSON.stringify(projection, null, 2) + '\n') };

package/template/.codex/skills/yss-implementation-contract-compiler/SKILL.md

@@ -5,15 +5,15 @@ description: "编译或重验 YSS Slice Implementation Contract、最小 Skill
 
 # YSS Implementation Contract Compiler
 
-已有生命周期资产优先用 `scripts/contract view <资产> --kind <类型>` 阅读；执行任务用 `--profile task --unit <ID>`，绑定与校验明细用 `--profile full`。视图不授予执行权限，仍按本 Skill 的原始来源和批准门禁处理。类型、准备和迁移见 `docs/process/contract-reading.md`。
+已有生命周期资产优先用 `scripts/contract view <资产> --kind <类型>` 阅读；执行任务用 `--profile task --unit <ID>`，绑定与校验明细用 `--profile full`。视图不授予执行权限，仍按本 Skill 的原始来源和批准门禁处理。类型、准备和迁移见 `.template-spec/process/contract-reading.md`。
 
 阶段 7 的实现合同编译器。它把已批准的生命周期资产、垂直切片、capability 和窄 Recipe 编译为 `Slice Implementation Contract` v3 草案；不批准合同、不写业务代码、不设置 `ready-for-agent`。
 
-文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `docs/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。
+文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `.template-spec/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。
 
 ## 文档写作
 
-撰写实现合同的解释正文和切片交接说明前，读取 `docs/process/document-writing.md` 的共用写法及工程契约 / Ticket 指引；不改变结构化合同、批准状态或就绪条件。
+撰写实现合同的解释正文和切片交接说明前，读取 `.template-spec/process/document-writing.md` 的共用写法及工程契约 / Ticket 指引；不改变结构化合同、批准状态或就绪条件。
 
 ## 输入
 
@@ -22,8 +22,8 @@ description: "编译或重验 YSS Slice Implementation Contract、最小 Skill
 ## 编译循环
 
 1. 判断 frontend/backend/API/data/domain/cross-repo 影响，并按 [compiler-contract.yaml](references/compiler-contract.yaml) 把 impact 映射为入口 capability；逐项填写 backend `component_impacts`。
-2. 按 `docs/process/delivery-preflight.md` 只读检查当前阶段交付前提，再检查工程存在性和核心/长尾 skill 可用性。既有 Java/Maven 工程按 `docs/process/existing-backend-architecture.md` 加载登记、工程基线、独立观测的原始引用与摘要；不伪填生成器或 H2。
-3. 从 `docs/agents/yss-skill-registry.yaml` 选择一个或多个窄 Recipe，合并 `required_capabilities`；Recipe 不得直接引用 skill。
+2. 按 `.template-spec/process/delivery-preflight.md` 只读检查当前阶段交付前提，再检查工程存在性和核心/长尾 skill 可用性。既有 Java/Maven 工程按 `.template-spec/process/existing-backend-architecture.md` 加载登记、工程基线、独立观测的原始引用与摘要；不伪填生成器或 H2。
+3. 从 `.template-spec/agents/yss-skill-registry.yaml` 选择一个或多个窄 Recipe，合并 `required_capabilities`；Recipe 不得直接引用 skill。
 4. 由 capability 解析入口 skill，只递归 `context-required`；`context-conditional` 仅在显式 condition 命中时加载，其他依赖类型只进入原因链，不扩张执行上下文。
 5. 按“Recipe 声明顺序 → 依赖拓扑 → skill ID”确定性排序，去重 skill 并保留全部原因；冻结 Registry 与编译器合同 SHA-256。
 6. 为切片生成基线合同；为当前行为生成工作单元增量路由。
@@ -32,11 +32,11 @@ description: "编译或重验 YSS Slice Implementation Contract、最小 Skill
 
 完整草案使用 `scripts/slice-contract prepare` 或 `prepareSliceImplementationContract` 从已有 Ticket / checkpoint 和必要细化组装；执行前读取唯一 YAML，视图和检查报告不授予权限。
 
-合同结构见 [slice-implementation-contract.md](references/slice-implementation-contract.md)，专项返回协议见 [yss-skill-execution-result.md](references/yss-skill-execution-result.md)。前端、后端和测试子任务必须由生命周期主控从批准的 Slice Contract 编译任务包；任务包 schema 为 `docs/process/schemas/subagent-task-package.schema.json`，技能列表必须来自 `taskPackageDefaults`，不能由编译器或执行 Agent 另行手写。
+合同结构见 [slice-implementation-contract.md](references/slice-implementation-contract.md)，专项返回协议见 [yss-skill-execution-result.md](references/yss-skill-execution-result.md)。前端、后端和测试子任务必须由生命周期主控从批准的 Slice Contract 编译任务包；任务包 schema 为 `.template-spec/process/schemas/subagent-task-package.schema.json`，技能列表必须来自 `taskPackageDefaults`，不能由编译器或执行 Agent 另行手写。
 
 ## 硬规则
 
-采用专职前端 profile 或显式 `frontend_delivery` 绑定时，先按 `docs/process/frontend-backend-delivery.md` 实际核验战略与后端联合交付。缺任一输入只能诊断和回交；输入通过后准备计划/合同，正式实现、生成和恢复仍须当前批准的 Slice Contract 冻结接收摘要。接口或部署版本漂移时重新接收，不复用旧成功输出。
+采用专职前端 profile 或显式 `frontend_delivery` 绑定时，先按 `.template-spec/process/frontend-backend-delivery.md` 实际核验战略与后端联合交付。缺任一输入只能诊断和回交；输入通过后准备计划/合同，正式实现、生成和恢复仍须当前批准的 Slice Contract 冻结接收摘要。接口或部署版本漂移时重新接收，不复用旧成功输出。
 
 - 编译器不得输出 `approved`、`ready-for-agent` 或 `completed`。
 - Registry 和编译规则保持 schema v2；新 Slice 使用 v3，v2 按原规则读取和显式迁移。schema v1 一律拒绝，不自动升级，不提供旧技能名兼容。
@@ -49,7 +49,7 @@ description: "编译或重验 YSS Slice Implementation Contract、最小 Skill
 - Harness 内实现路径必须落在 `apps/backend/<project>/` 或 `apps/frontend/<project>/` 的具体项目目录；`apps/backend/`、`apps/frontend/` 只能作为容器，`app/backend/`、`app/frontend/` 及其子路径一律阻断。外部实现仓库使用其登记的真实项目根路径。`git-submodule` 使用 `implementation_path_policy: git-submodule-harness-apps`，空 gitlink、detached HEAD 或 `--force` 覆盖挂载点不得脚手架；`inspectWorkingTreeScope.writable` 必须为显式布尔值。
 - 当前用户、缓存、审计、Excel、分布式 ID、请求校验、错误映射、加解密或网关韧性命中时，必须按 `compiler-contract.yaml` 的 `impact_to_capabilities` 补齐入口 capability；不能只在 `boundaries.md` 中提及。仅复用已经验证的平台认证 / 授权能力不算 component impact，不自动增加权限专项 skill。
 - 业务行为使用 `behavior-tdd`；只有机械脚手架/生成物可用 `controlled-generation`，并记录例外和验证。
-- 阶段 5 若命中交付面且无已有工程，按 Project Scaffold Contract schema v4 编译 `controlled-generation` 合同 draft。后端先读取已通过 `gate.backend-architecture-platform-approved` 的架构与精确 Spring Boot 版本决定，并以原始字节 digest 绑定批准且当前的 Technical Design、Data Architecture Decision v1、API Contract Decision v1 及 `gate.engineering-contract-approved` 真实批准记录；编译器不得自行默认、提问或批准。既有工程核验并复用当前登记架构及固定工程基线/POM 中的实际版本，不重新询问或生成。API `required` 时工程批准还必须直接绑定冻结 OpenAPI YAML 的版本与摘要，`not-applicable` 时必须有影响评估、明确原因和证据。前端绑定标准模板精确 commit、应用标识、路由、OpenAPI 影响、目标路径和 `init_git` 决定。合同经生命周期批准并持久化后才能运行生成器。历史后端 schema v3 只允许 Manifest 只读恢复审计，并须补齐 API 对账，不得新生成；前端只接受 v4。生成与验证完成、仓库登记并通过 `check.implementation-repositories-ready` 后，才编译 Ticket 与业务 Slice Contract。
+- 阶段 5 若命中交付面且无已有工程，按 Project Scaffold Contract schema v4 编译 `controlled-generation` 合同 draft。后端先读取已通过 `gate.backend-architecture-platform-approved` 的架构与精确 Spring Boot 版本决定，并以原始字节 digest 绑定批准且当前的 Technical Design、Data Architecture Decision v1、API Contract Decision（新建 v2；历史 v1 只读兼容，准备与迁移见 `.template-spec/process/contract-reading.md`） 及 `gate.engineering-contract-approved` 真实批准记录；编译器不得自行默认、提问或批准。既有工程核验并复用当前登记架构及固定工程基线/POM 中的实际版本，不重新询问或生成。API `required` 时工程批准还必须直接绑定冻结 OpenAPI YAML 的版本与摘要，`not-applicable` 时必须有影响评估、明确原因和证据。前端绑定标准模板精确 commit、应用标识、路由、OpenAPI 影响、目标路径和 `init_git` 决定。合同经生命周期批准并持久化后才能运行生成器。历史后端 schema v3 只允许 Manifest 只读恢复审计，并须补齐 API 对账，不得新生成；前端只接受 v4。生成与验证完成、仓库登记并通过 `check.implementation-repositories-ready` 后，才编译 Ticket 与业务 Slice Contract。
 - 脚手架合同在编译阶段只能是 `draft` / `ready-for-lifecycle-review` / `blocked`；只有生命周期编排器可以把已持久化脚手架合同标记为 `approved`。脚手架合同只覆盖业务代码前的工程骨架工作单元；生成、基线校验和合同重编译完成后，它不能替代脚手架后的 Slice Implementation Contract。
 - 脚手架输出消费批准的脚手架合同；脚手架后的所有生成后端代码都必须绑定当前批准且版本当前的 Slice Implementation Contract、主 YSS skill、依赖闭包、允许写路径、预期证据和 YSS Skill Execution Result。打印命令、`./mvnw validate` 单项通过或脚手架成功不能替代合同批准；生成范围从机械内容变成业务行为时触发完整重路由。
 - 专项结果中的越界路径、缺失证据、`drift`、`violation` 或 `new_impacts` 必须阻断或重路由。
@@ -72,6 +72,6 @@ description: "编译或重验 YSS Slice Implementation Contract、最小 Skill
 
 ## 后端脚手架平台承接
 
-消费生命周期已确认的架构与 `platform_configuration` v2；不得自行选择、批准或静默升级 Boot/Java。平台清单执行 `scripts/backend-platforms` 查询；只允许已验证 YSS 组合，新生成缺少配置或证据即阻断。决定、合同、Manifest 与下游架构身份须绑定同一平台及兼容摘要。详见 仓库共享合同 `docs/engineering/backend-platforms.md`。
+消费生命周期已确认的架构与 `platform_configuration` v2；不得自行选择、批准或静默升级 Boot/Java。平台清单执行 `scripts/backend-platforms` 查询；只允许已验证 YSS 组合，新生成缺少配置或证据即阻断。决定、合同、Manifest 与下游架构身份须绑定同一平台及兼容摘要。详见 仓库共享合同 `.template-spec/engineering/backend-platforms.md`。
 
 后端 Slice 解析出 `component_binding: required` 的 capability 或其主 Skill 时，必须在同一平台兼容条目中逐项解析 `component_capabilities`。编译结果保存 `component_bindings` 与 `component_bindings_digest`；未登记、未验证、架构证据缺失、构件坐标冲突或摘要漂移均阻断。旧合同含组件 Skill 但没有组件绑定时直接 `stale`，重新编译并交生命周期批准，禁止自动补字段后沿用原批准。

package/template/.codex/skills/yss-implementation-contract-compiler/references/boundaries.md

@@ -1,6 +1,6 @@
 # YSS Skill Boundaries
 
-> Generated by `scripts/generate-yss-skill-boundaries` from `docs/agents/yss-skill-registry.yaml` and `compiler-contract.yaml`. Do not hand-edit.
+> Generated by `scripts/generate-yss-skill-boundaries` from `.template-spec/agents/yss-skill-registry.yaml` and `compiler-contract.yaml`. Do not hand-edit.
 
 实现入口先选择 capability 或窄 Recipe，再由实现合同编译器计算最小 skill 闭包。下面是派生阅读视图，不是第二套路由事实源。
 

package/template/.codex/skills/yss-implementation-contract-compiler/references/compiler-contract.yaml

@@ -2,12 +2,12 @@ schema_version: 2
 slice_contract_versions:
   default: 3
   accepted: [2, 3]
-  v3_schema: docs/process/schemas/slice-implementation-contract-v3.schema.json
+  v3_schema: .template-spec/process/schemas/slice-implementation-contract-v3.schema.json
   normalization: scripts/lib/slice-contract.mjs
   v2_migration: explicit-new-draft-no-inherited-approval
 backend_architecture:
-  registry_source: docs/agents/yss-skill-registry.yaml
-  identity_schema: docs/process/schemas/backend-architecture-identity.schema.json
+  registry_source: .template-spec/agents/yss-skill-registry.yaml
+  identity_schema: .template-spec/process/schemas/backend-architecture-identity.schema.json
   required_evidence: [engineering_baseline, repository_registration, manifest]
   evidence_loading: original-references-and-raw-sha256
   existing_identity: {schema_version: 2, source_kind: existing-registration, profiles_source: existing_project_profiles}
@@ -18,8 +18,8 @@ backend_architecture:
   readiness: supported-profile-and-current-identical-evidence
 compiled_by: yss-implementation-contract-compiler
 approved_by: yss-product-lifecycle
-capability_source: docs/agents/yss-skill-registry.yaml
-recipe_source: docs/agents/yss-skill-registry.yaml
+capability_source: .template-spec/agents/yss-skill-registry.yaml
+recipe_source: .template-spec/agents/yss-skill-registry.yaml
 digest_algorithm: sha256
 unsupported_inputs:
   registry_schema_v1: reject-with-migration-guidance
@@ -73,7 +73,7 @@ readiness:
   cross_repo: [repository_registry, delivery_order, integration_verification, rollback_order]
   frontend_delivery:
     when: specialized-frontend-profile-or-explicit-frontend-delivery-binding
-    source: docs/process/frontend-backend-delivery.md
+    source: .template-spec/process/frontend-backend-delivery.md
     verifier: scripts/verify-frontend-delivery
     output_binding: frontend.delivery
     inputs_verified_is_implementation_approval: false
@@ -146,7 +146,7 @@ resolution_contract:
   component_bindings:
     when: any-required-capability-provider-kind-is-yss-component
     platform_configuration: required-v2
-    catalog_source: docs/engineering/backend-platforms.json
+    catalog_source: .template-spec/engineering/backend-platforms.json
     required_fields: [component_bindings, component_bindings_digest]
     exact_artifact_binding: [group_id, artifact_id, declared_version, resolved_version, pom_sha256, jar_sha256, source_tree]
     digest_change_status: stale
@@ -159,7 +159,7 @@ context_plan:
 
 project_scaffold_contract_schema:
   schema_version: 4
-  schema_ref: docs/process/schemas/project-scaffold-contract.schema.json
+  schema_ref: .template-spec/process/schemas/project-scaffold-contract.schema.json
   identity: project-engineering-baseline
   discriminant: delivery_role
   delivery_roles:
@@ -440,7 +440,7 @@ strategic_handoff_consumption:
 
 backend_platform_contract:
   schema_version: 2
-  catalog_ref: docs/engineering/backend-platforms.json
+  catalog_ref: .template-spec/engineering/backend-platforms.json
   configuration_field: platform_configuration
   selection_owner: yss-product-lifecycle
   new_generation_requires: [exact-boot-java, confirmed-decision, matching-yss-coordinates, verified-compatibility-entry]

package/template/.codex/skills/yss-implementation-contract-compiler/references/slice-implementation-contract-v2.md

@@ -4,11 +4,11 @@
 
 # Slice Implementation Contract
 
-后端合同还必须绑定 `architecture_identity`（schema 见 `docs/process/schemas/backend-architecture-identity.schema.json`），并与工程基线、登记和 Manifest 一致。将同一身份复制到 `resolution`、backend 工作单元和执行结果；Profile 的成熟度/Recipe 来源是技能注册表，draft 不得 ready-for-agent。旧 backend.domain-behavior/persistence-mybatis/http-api Recipe 只读退役，重新编译时显式选择 backend.ddd-* 或 backend.mvc-*。
+后端合同还必须绑定 `architecture_identity`（schema 见 `.template-spec/process/schemas/backend-architecture-identity.schema.json`），并与工程基线、登记和 Manifest 一致。将同一身份复制到 `resolution`、backend 工作单元和执行结果；Profile 的成熟度/Recipe 来源是技能注册表，draft 不得 ready-for-agent。旧 backend.domain-behavior/persistence-mybatis/http-api Recipe 只读退役，重新编译时显式选择 backend.ddd-* 或 backend.mvc-*。
 
 `yss-implementation-contract-compiler` 生成草案；`yss-product-lifecycle` 核验、批准并持久化。合同缺少必填字段时状态为 `blocked`。schema v1 已停止支持，必须重新编译为 v2，不提供自动升级。
 
-采用专职前端 profile 时，`frontend.delivery` 绑定 `{acceptance_ref, digest}`，来自 `scripts/verify-frontend-delivery` 的当前结果；也可由 `resolution.frontend_delivery` 承载，两处并存时必须一致。正式执行从持久化合同读取并重验输入。细则见 `docs/process/frontend-backend-delivery.md`。
+采用专职前端 profile 时，`frontend.delivery` 绑定 `{acceptance_ref, digest}`，来自 `scripts/verify-frontend-delivery` 的当前结果；也可由 `resolution.frontend_delivery` 承载，两处并存时必须一致。正式执行从持久化合同读取并重验输入。细则见 `.template-spec/process/frontend-backend-delivery.md`。
 
 ```yaml
 slice_contract:
@@ -55,7 +55,7 @@ slice_contract:
     recipe_ids: []
     conditions: []
     reason_chains: {}
-    registry_digest: # sha256 of normalized docs/agents/yss-skill-registry.yaml
+    registry_digest: # sha256 of normalized .template-spec/agents/yss-skill-registry.yaml
     compiler_contract_digest: # sha256 of normalized compiler-contract.yaml
     compiled_at:
     freshness: current # digest 变化后为 stale

package/template/.codex/skills/yss-implementation-contract-compiler/references/slice-implementation-contract.md

@@ -2,7 +2,7 @@
 
 YAML 是唯一权威合同。Agent 从已确认上游整理草案；用户确认目标、范围、验收和关键取舍；独立专业审查核验工程约束，生命周期主控关闭 `gate.slice-contract-approved`。新合同使用 schema v3；[v2](slice-implementation-contract-v2.md) 保留原规则读取和校验，schema v1 继续拒绝。
 
-结构权威为 `docs/process/schemas/slice-implementation-contract-v3.schema.json`。Registry、编译规则与 Execution Result 继续使用各自版本；Slice v3 不要求它们一同升级。
+结构权威为 `.template-spec/process/schemas/slice-implementation-contract-v3.schema.json`。Registry、编译规则与 Execution Result 继续使用各自版本；Slice v3 不要求它们一同升级。
 
 ## 只保存一次
 

package/template/.codex/skills/yss-implementation-contract-compiler/references/strategic-handoff-routing.md

@@ -1,6 +1,6 @@
 ## 战略交接快照包
 
-跨仓交接使用 `scripts/strategic-handoff export / verify / import`。正式导出前补齐源战略的稳定规则 ID、关键场景和当前批准绑定；源资产原字节冻结、包内路径通过清单解析。目标导入只产生快照和对账/承接草案，正式 reconciliation 通过后才能进入战术设计。流程与字段见 `docs/process/strategic-handoff-package.md`。
+跨仓交接使用 `scripts/strategic-handoff export / verify / import`。正式导出前补齐源战略的稳定规则 ID、关键场景和当前批准绑定；源资产原字节冻结、包内路径通过清单解析。目标导入只产生快照和对账/承接草案，正式 reconciliation 通过后才能进入战术设计。流程与字段见 `.template-spec/process/strategic-handoff-package.md`。
 
 来自战略交接包的技术设计合同（DDD / MVC）必须绑定 `strategic_handoff` 导入收据、包摘要、正式目标对账及逐条承接 rows。来自导入包时禁止仅填 `upstream_current: true`。批准前执行 `scripts/verify-strategic-handoff-consumption --root <target> <tactical>`；存在受控延期时按切片执行 `--slice <slice-id>`，实际核验通过且合同批准后才可继续相关切片。最新源规则、关键场景或资产变化使依赖项 stale；未知依赖扩大阻断，业务冲突回交战略方。结果绑定当前包与战术摘要，不能复用旧输出宣布 ready-for-agent。
 

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

@@ -11,7 +11,7 @@ description: 在生命周期已批准的脚手架合同下生成通用 YSS 分
 
 - backend `scaffold_status=required`，目标目录已确认且不存在。
 - `scaffold-architecture-decisions.yaml` 中对应项目已达到 `lifecycle-approved`，确认架构为 `layered-mvc`。
-- `yss-implementation-contract-compiler` 已编译统一 Project Scaffold Contract schema v4，并绑定批准且当前的 Technical Design、Data Architecture Decision v1、API Contract Decision v1 和真实工程合同批准记录。API `required` 时 Draft、Validation、独立 Review、Freeze 与工程批准必须绑定同一 OpenAPI YAML 字节；`not-applicable` 时必须有评估、原因和证据且不得携带占位资产。合同须由生命周期批准并持久化。
+- `yss-implementation-contract-compiler` 已编译统一 Project Scaffold Contract schema v4，并绑定批准且当前的 Technical Design、Data Architecture Decision v1、API Contract Decision（新建 v2；历史 v1 只读兼容，准备与迁移见 `.template-spec/process/contract-reading.md`） 和真实工程合同批准记录。API `required` 时 Draft、Validation、独立 Review、Freeze 与工程批准必须绑定同一 OpenAPI YAML 字节；`not-applicable` 时必须有评估、原因和证据且不得携带占位资产。合同须由生命周期批准并持久化。
 - 合同中的 `decision_id`、文件 digest、Profile、能力闭包、写路径和验证命令仍为当前版本。
 
 任一条件缺失时返回 `blocked`。本生成器无交互、无默认回退；用户选择由 `yss-product-lifecycle` 在 `work-unit.technical-analysis` 的工程基线内完成。
@@ -27,7 +27,7 @@ description: 在生命周期已批准的脚手架合同下生成通用 YSS 分
 - Spring MVC、Servlet、Validation、Jackson 和 starter 坐标消费共享平台清单；Java 下限和允许组合由当前平台条目决定。Jakarta 转换不包括 `javax.sql` 等 Java SE API。
 - 平台候选维护验证产物标记 `platform_verification=candidate`，不能交给业务生成、升级完成等级或进入首切片验证。测试夹具不证明 YSS 兼容。
 
-版本清单、合同字段、候选验证和支持晋级规则见 仓库共享合同 `docs/engineering/backend-platforms.md`。
+版本清单、合同字段、候选验证和支持晋级规则见 仓库共享合同 `.template-spec/engineering/backend-platforms.md`。
 
 ## 架构与 Profile
 

package/template/.codex/skills/yss-layered-mvc-scaffold-generator/scripts/data-analysis-profile.mjs

@@ -32,7 +32,7 @@ async function sharedTools(outputDir, contract) {
   }
   const staging = await mkdtemp(path.join(outputDir, ".skillUtils.staging-"));
   try {
-    for (const relative of [".agents/skills", ".codex/skills", ".cursor/skills", ".pi/skills", "scripts", "docs/agents", "docs/process", "AGENTS.md", "skills-lock.json"]) {
+    for (const relative of [".agents/skills", ".codex/skills", ".cursor/skills", ".pi/skills", "scripts", ".template-spec/agents", ".template-spec/process", "AGENTS.md", "skills-lock.json"]) {
       await mkdir(path.dirname(path.join(staging, relative)), { recursive: true });
       await cp(path.join(REPOSITORY_ROOT, relative), path.join(staging, relative), { recursive: true });
     }
@@ -55,7 +55,7 @@ export async function finalizeDataAnalysisProfile({ projectRoot, contract, archi
   if (digest(context) !== contract.context_handoff_digest || !/^---\r?\ncontext_schema_version: 1\r?\n---/m.test(context.toString())) throw new Error("CONTEXT handoff schema/digest 不匹配");
   if (spawnSync("git", ["--version"]).status !== 0) throw new Error("Git 不可用");
 
-  for (const relative of ["docs/agents", "docs/process", "docs/templates", "docs/architecture/templates"]) {
+  for (const relative of [".template-spec/agents", ".template-spec/process", ".template-spec/templates", ".template-spec/architecture/templates"]) {
     await mkdir(path.dirname(path.join(projectRoot, relative)), { recursive: true });
     await cp(path.join(REPOSITORY_ROOT, relative), path.join(projectRoot, relative), { recursive: true });
   }
@@ -73,9 +73,9 @@ export async function finalizeDataAnalysisProfile({ projectRoot, contract, archi
   }
   const lockDigest = await sharedTools(path.resolve(options.outputDir), contract);
   await put(path.join(projectRoot, "skills-lock.json"), JSON.stringify({ version: 1, distribution: { mode: "sibling-directory", skillUtilsDir: "../skillUtils", required: true, compatibility: "skill-utils-v1", lock_digest: lockDigest } }, null, 2));
-  await put(path.join(projectRoot, "docs/process/engineering-baseline.json"), JSON.stringify({ schema_version: 1, architecture_identity: architectureIdentity, platform_profile: contract.profiles.platform, scaffold_completion: "generated" }, null, 2));
-  await put(path.join(projectRoot, "docs/process/implementation-repo-registry.yaml"), JSON.stringify({ schema_version: 1, projects: [{ project_type: "backend", project_name: options.projectName, project_root: ".", git_root: ".", repository_scope: "external-repository", scaffold_status: "initialized", default_branch: "main", architecture_identity: architectureIdentity, allowed_write_paths: ["."], verification_commands: contract.verification_commands, expected_evidence_files: contract.expected_evidence_files, ci: "not-configured", rollback_point: "initial-empty-repository" }] }, null, 2));
-  await put(path.join(projectRoot, "docs/process/service-initialization.json"), JSON.stringify({ work_unit: "work-unit.service-project-initialization", context_handoff_ref: contract.context_handoff_ref, context_handoff_digest: contract.context_handoff_digest, contract_id: contract.contract_id, architecture_identity: architectureIdentity, status: "generated" }, null, 2));
+  await put(path.join(projectRoot, ".template-spec/process/engineering-baseline.json"), JSON.stringify({ schema_version: 1, architecture_identity: architectureIdentity, platform_profile: contract.profiles.platform, scaffold_completion: "generated" }, null, 2));
+  await put(path.join(projectRoot, ".template-spec/process/implementation-repo-registry.yaml"), JSON.stringify({ schema_version: 1, projects: [{ project_type: "backend", project_name: options.projectName, project_root: ".", git_root: ".", repository_scope: "external-repository", scaffold_status: "initialized", default_branch: "main", architecture_identity: architectureIdentity, allowed_write_paths: ["."], verification_commands: contract.verification_commands, expected_evidence_files: contract.expected_evidence_files, ci: "not-configured", rollback_point: "initial-empty-repository" }] }, null, 2));
+  await put(path.join(projectRoot, ".template-spec/process/service-initialization.json"), JSON.stringify({ work_unit: "work-unit.service-project-initialization", context_handoff_ref: contract.context_handoff_ref, context_handoff_digest: contract.context_handoff_digest, contract_id: contract.contract_id, architecture_identity: architectureIdentity, status: "generated" }, null, 2));
   await put(path.join(projectRoot, ".gitignore"), "target/\n**/target/\n.idea/\n*.iml\n.env\n.env.*\n.local/");
   const git = spawnSync("git", ["init", "--initial-branch=main"], { cwd: projectRoot, encoding: "utf8" });
   if (git.status !== 0) throw new Error(`Git 初始化失败: ${git.stderr}`);

package/template/.codex/skills/yss-layered-mvc-scaffold-generator/scripts/generate_scaffold.mjs

@@ -166,7 +166,7 @@ export async function validateContract(options, skillId, architectureProfile, pl
     if (contract.init_git !== true) fail("mvc-data-analysis-v1 必须由合同显式要求独立 Git 初始化");
     if (!contract.context_handoff_ref || !contract.context_handoff_digest) fail("mvc-data-analysis-v1 缺少批准的 CONTEXT handoff");
   }
-  validateJsonSchema(contract, path.join(REPOSITORY_ROOT, "docs/process/schemas/project-scaffold-contract.schema.json"), { label: "Project Scaffold Contract v4" });
+  validateJsonSchema(contract, path.join(REPOSITORY_ROOT, ".template-spec/process/schemas/project-scaffold-contract.schema.json"), { label: "Project Scaffold Contract v4" });
   const required = ["contract_id", "contract_version", "scaffold_request_id", "status", "compiler_draft_ref", "lifecycle_approval_ref", "persisted_ref", "current_version", "implementation_repository", "backend_repository", "scaffold_status", "project_name", "target_output_dir", "base_package", "architecture_family", "generator_skill", "decision_ref", "decision_id", "decision_digest", "maven_coordinates", "profiles", "module_profile", "allowed_write_paths", "expected_evidence_files", "verification_commands", "approval", "work_unit", "generation_policy"];
   const missing = required.filter((field) => !isPresent(contract[field]));
   if (missing.length) fail(`脚手架合同缺少字段: ${missing.join(", ")}`);
@@ -319,7 +319,7 @@ export async function generate(options, { skillId = SKILL_ID, architectureProfil
       verification_commands: COMMANDS,
       generator: { id: skillId, template_digest: await treeDigest(SKILL_ROOT) },
       ownership: { generated_files: generatedFiles, user_owned_globs: ["**/src/main/java/**", "**/src/test/java/**", "db/**"] },
-      readiness: { downstream_skills: downstream, contracts: { architecture_profiles: rawSha256(await readFile(path.join(REPOSITORY_ROOT, "docs/agents/backend-architecture-profiles.md"))), compiler_contract: rawSha256(await readFile(path.join(REPOSITORY_ROOT, ".agents/skills/yss-implementation-contract-compiler/references/compiler-contract.yaml"))) }, architecture_ruleset: rawSha256(await readFile(path.join(projectRoot, architectureRuleset))) },
+      readiness: { downstream_skills: downstream, contracts: { architecture_profiles: rawSha256(await readFile(path.join(REPOSITORY_ROOT, ".template-spec/agents/backend-architecture-profiles.md"))), compiler_contract: rawSha256(await readFile(path.join(REPOSITORY_ROOT, ".agents/skills/yss-implementation-contract-compiler/references/compiler-contract.yaml"))) }, architecture_ruleset: rawSha256(await readFile(path.join(projectRoot, architectureRuleset))) },
       generated_at: new Date().toISOString()
     };
     await put(projectRoot, ".yss/scaffold-generation.json", JSON.stringify(manifest, null, 2));

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

@@ -8,6 +8,7 @@ import path from "node:path";
 import test from "node:test";
 import { fileURLToPath } from "node:url";
 import { attachDesignPrerequisites } from "../../../../scripts/fixtures/backend-scaffold/design-prerequisites.mjs";
+import { validateNextRoute } from "../../../../scripts/lib/lifecycle-transition.mjs";
 
 const script = path.join(path.dirname(fileURLToPath(import.meta.url)), "generate_scaffold.mjs");
 const digest = (value) => `sha256:${createHash("sha256").update(value).digest("hex")}`;
@@ -80,8 +81,27 @@ test("数据分析初始化生成 H2 六模块和独立治理信封", async (t)
   data.contract.context_handoff_ref = "context-handoff.md";
   data.contract.context_handoff_digest = digest(context);
   await writeFile(data.contractFile, JSON.stringify(data.contract));
+  const contractBytes = await readFile(data.contractFile);
+  const state = { service_project_initialization: {
+    project_id: "demo-service", contract_ref: data.contractFile, contract_digest: digest(contractBytes),
+    project_root: data.project, context_handoff_digest: digest(context)
+  } };
+  const edge = (from, to, value = state) => validateNextRoute(from, to, value, { root: data.root });
+  assert.equal(edge("work-unit.implementation-repository-preparation", "work-unit.service-project-initialization").result, "allowed", JSON.stringify(edge("work-unit.implementation-repository-preparation", "work-unit.service-project-initialization")));
+  const missingContract = structuredClone(state); missingContract.service_project_initialization.contract_ref = path.join(data.root, "missing-contract.json");
+  assert.equal(edge("work-unit.implementation-repository-preparation", "work-unit.service-project-initialization", missingContract).result, "blocked");
+  const changedContract = structuredClone(state); changedContract.service_project_initialization.contract_digest = digest("stale");
+  assert.equal(edge("work-unit.implementation-repository-preparation", "work-unit.service-project-initialization", changedContract).result, "blocked");
+  const approvedContract = structuredClone(data.contract);
+  data.contract.design_prerequisites.engineering_contract_approval_ref = "missing-approval.json";
+  await writeFile(data.contractFile, JSON.stringify(data.contract));
+  const missingApproval = structuredClone(state); missingApproval.service_project_initialization.contract_digest = digest(await readFile(data.contractFile));
+  assert.equal(edge("work-unit.implementation-repository-preparation", "work-unit.service-project-initialization", missingApproval).result, "blocked");
+  await writeFile(data.contractFile, JSON.stringify(approvedContract));
+  assert.equal(edge("work-unit.service-project-initialization", "work-unit.implementation-repository-preparation").result, "blocked");
   const result = spawnSync(process.execPath, [path.resolve(path.dirname(script), "../../../../scripts/fixtures/backend-scaffold/generate-candidate.mjs"), script, ...data.args], { encoding: "utf8" });
   assert.equal(result.status, 0, result.stderr);
+  assert.equal(edge("work-unit.implementation-repository-preparation", "work-unit.service-project-initialization").result, "blocked", "重复初始化不得放行");
   const manifest = JSON.parse(await readFile(path.join(data.project, ".yss/scaffold-generation.json"), "utf8"));
   assert.equal(manifest.architecture_identity.architecture_profile, "mvc-data-analysis-v1");
   assert.equal(manifest.generator_skill, "yss-layered-mvc-scaffold-generator");
@@ -89,6 +109,28 @@ test("数据分析初始化生成 H2 六模块和独立治理信封", async (t)
   await stat(path.join(data.project, ".git"));
   await stat(path.join(data.output, "skillUtils/skills-lock.json"));
   assert.ok(!manifest.ownership.generated_files.some((entry) => entry.path.startsWith(".git/")));
+  const manifestRef = path.join(data.project, ".yss/scaffold-generation.json");
+  const verificationRef = path.join(data.root, "scaffold-verification.json");
+  const resultRef = path.join(data.root, "service-result.json");
+  manifest.completion_level = "empty-scaffold-verified";
+  await writeFile(manifestRef, JSON.stringify(manifest));
+  const commands = [];
+  for (const phase of ["validate", "test", "package"]) {
+    const stdout_ref = path.join(data.root, `${phase}.stdout.log`), stderr_ref = path.join(data.root, `${phase}.stderr.log`);
+    await writeFile(stdout_ref, "synthetic route fixture"); await writeFile(stderr_ref, "");
+    commands.push({ phase, command: `./mvnw ${phase}`, exit_code: 0, stdout_ref, stderr_ref });
+  }
+  await writeFile(verificationRef, JSON.stringify({ status: "passed", completion_level: "empty-scaffold-verified", project_root: data.project, commands }));
+  await writeFile(resultRef, JSON.stringify({ result_schema: "workflow-execution-result-v1", work_unit: "work-unit.service-project-initialization", result: "completed", evidence_refs: [manifestRef, verificationRef] }));
+  Object.assign(state.service_project_initialization, { manifest_ref: manifestRef, verification_ref: verificationRef, result_ref: resultRef });
+  assert.equal(edge("work-unit.service-project-initialization", "work-unit.implementation-repository-preparation").result, "allowed");
+  const stale = structuredClone(state); stale.service_project_initialization.context_handoff_digest = digest("stale");
+  assert.equal(edge("work-unit.service-project-initialization", "work-unit.implementation-repository-preparation", stale).result, "blocked");
+  commands[0].exit_code = 1; await writeFile(verificationRef, JSON.stringify({ status: "passed", completion_level: "empty-scaffold-verified", project_root: data.project, commands }));
+  assert.equal(edge("work-unit.service-project-initialization", "work-unit.implementation-repository-preparation").result, "blocked", "Wrapper 非零退出不得放行");
+  commands[0].exit_code = 0;
+  commands.pop(); await writeFile(verificationRef, JSON.stringify({ status: "passed", completion_level: "empty-scaffold-verified", project_root: data.project, commands }));
+  assert.equal(edge("work-unit.service-project-initialization", "work-unit.implementation-repository-preparation").result, "blocked", "缺失 Wrapper 命令不得放行");
   const core = await readFile(path.join(data.project, "demo-service-core/pom.xml"), "utf8");
   assert.doesNotMatch(core, /demo-service-client|spring-web|ojdbc|mysql-connector/);
 });

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

@@ -33,6 +33,18 @@ description: 用于 YSS MyBatis / MyBatis-Plus 组件能力核验、接入决策
 <!-- yss-rule {"id":"mybatis.transaction","when":"mybatis","level":"mandatory","evidence":"code-and-verification"} -->
 - 事务边界归批准的 Application 用例或 MVC service/core；Repository 不临时声明新的业务事务。
 
+## 能力选择记录
+
+| 既有工程调用 seam | 选择与核验 |
+|---|---|
+| `PageQuery` 经组件切面进入 Repository/Gateway | 核对代理切点、参数位置、PageHelper 开关、实际 SQL 与 `tempTotalCount`；不能因 Bean 注册就认定切面命中。 |
+| Mapper 使用 MyBatis-Plus `IPage` | 核对 MP 分页开关、方言、实际 SQL 与 total；同一次查询不得叠加 PageHelper 上下文。两插件都注册不等于查询已双分页。 |
+| 原生 Mapper/Example/ListMapper | 按当前源码和实体映射选择 `BaseRepository<T,D>`；与完整 MP `BasePlusRepository<T>` 不可直接互换，混用或复合键须验证主键方法、XML 与映射。 |
+| SQL 级批量写入 | 核对公开入口、分片大小、目标方言生成的单批 SQL、审计填充和 ID；多个分片整体回滚由上层用例事务保证。若 batch size 存在进程级可变状态，多 Spring Context 不得据此宣称配置隔离。 |
+| 命名数据源 | Holder 中有多个 DataSource 不证明动态路由；记录实际 Mapper 的 `SqlSessionFactory`/DataSource、主池与自建池所有权，以及事务绑定。 |
+
+以上仅对命中的能力记录，不改变两套分页插件的当前默认注册行为；选择由批准 Profile、消费工程配置和运行测试共同证明。
+
 ## 任务分流
 
 | 请求 | 本 Skill 动作 | 后续路由 |
@@ -48,8 +60,8 @@ description: 用于 YSS MyBatis / MyBatis-Plus 组件能力核验、接入决策
 2. 装配与开关：自动配置、条件属性、Mapper 扫描和 XML location 是否真实生效。
 3. 调用 seam：代理是否命中、分页参数位置/类型、分页插件链和 total 回填责任。
 4. 映射：接口签名、XML namespace、resultMap、字段、逻辑删除和主键策略。
-5. 批量：是否调用当前公开批量入口、分批与方言是否匹配、是否退化为循环单条。
-6. 数据源：先确认组件只提供了什么，再检查上层路由与事务进入顺序；不得假设存在当前线程数据源上下文。
+5. 批量：是否调用当前公开批量入口、分批与方言是否匹配、是否退化为循环单条；核对 batch size 在多个应用上下文中的作用域。
+6. 数据源：先确认组件只提供了什么，再检查 Mapper 实际绑定的会话工厂、上层路由与事务进入顺序；不得假设存在当前线程数据源上下文。
 7. 最后检查 SQL、绑定参数、数据库方言与执行计划。
 
 ## Review 输入