create-yss-spec 3.3.8 → 3.4.1

package/template/.cursor/skills/yss-skill-source-index-refresh/scripts/refresh-yss-skill-index.mjs

@@ -31,7 +31,6 @@ const BACKEND = {
 
 const FRONTEND = {
   "yss-ui": ["components", "hooks", "skills"],
-  "yss-components": ["components"],
   "yss-hook": ["hooks"],
   "yss-ui-business-page-generation": ["components", "hooks", "skills"],
   "yss-use-table-height": ["hooks"],

package/template/.cursor/skills/yss-tactical-design/SKILL.md

@@ -10,7 +10,7 @@ description: 在 YSS 技术分析阶段将批准的战略领域输入细化为
 ## 适用边界
 
 - 由 `yss-technical-design` 在已确认 `domain-driven` 的技术设计分支中调用；传统 MVC 使用 `yss-mvc-design`，不得按状态或一致性影响单独推断为 DDD。
-- 输入必须是版本当前的 Spec、功能架构、战略 DDD、状态矩阵、OpenAPI Draft / Freeze、ADR 和工程约束。若输入来自 Strategic Design Handoff，必须先用 `scripts/verify-strategic-context-import` 验证 schema v3 `source_context_snapshot` / `context_delta` 已对账到目标仓根 `CONTEXT.md`，Visual Baseline Bundle 可读取且 digest 当前，并且目标侧 `context_reconciliation` 有效；未完成时不得开始战术建模。
+- 输入必须是版本当前的 Spec、功能架构、战略 DDD、状态矩阵、OpenAPI Draft / Freeze、ADR 和工程约束。若输入来自 Strategic Design Handoff，必须先用 `scripts/verify-strategic-context-import` 验证历史 v3/v4 或当前 v5 的 `source_context_snapshot` / `context_delta` 已对账到目标仓根 `CONTEXT.md`，对应的 prototype 或 existing UI baseline 可读取且摘要当前，并且目标侧 `context_reconciliation` 有效；未完成时不得开始战术建模。
 - 默认将结果写入系统概要设计 / 数据架构中的 Tactical DDD Check；聚合、状态机、一致性或持久化映射复杂到无法清楚表达时，才升级为独立战术设计文档。
 - 没有聚合、状态、不变量、一致性或领域边界影响时返回 `not-applicable` 及原因，不生成空设计。
 

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

@@ -32,7 +32,7 @@ pnpm why vue @yss-ui/components @yss-ui/hooks ant-design-vue vxe-table
 
 记录实际版本、lockfile、验证命令和环境阻塞。完整策略见 `references/antdv-compatibility.md`。
 
-产品设计使用的 Antdv Next 或 Ant Design v6 视觉/token 语义，不等于 Vue 生产实现 API。生产代码必须使用项目安装的 Ant Design Vue 4.x API，禁止把原型 props、events、slots、hook 或组件写法当作生产合同。`yss-antdv-next-design` 只用于默认 H2 Vue 原型，`yss-antd-design` 只用于显式 React 兼容原型；原型阶段不得调用本技能。只有进入前端实现计划、已批准切片的生产实现或实现还原验证后，才从目标 lockfile、类型、本地文档和既有用法取得真实组件事实。
+产品设计使用的 Antdv Next 或 Ant Design v6 视觉/token 语义，不等于 Vue 生产实现 API。生产代码必须使用项目安装的 Ant Design Vue 4.x API，禁止把原型 props、events、slots、hook 或组件写法当作生产合同。原型统一使用 HTML/CSS/JavaScript；原型阶段不得调用本技能。只有进入前端实现计划、已批准切片的生产实现或实现还原验证后，才从目标 lockfile、类型、本地文档和既有用法取得真实组件事实。
 
 ## 3. 组件选型门禁
 
@@ -56,7 +56,7 @@ pnpm why vue @yss-ui/components @yss-ui/hooks ant-design-vue vxe-table
 | 任务 | 必须路由 |
 |---|---|
 | 新建或改造完整业务页面 | `yss-ui-business-page-generation` |
-| 页面布局、组件和交互 | `yss-components` |
+| 页面布局与无独立 Skill 的专项组件 | `page-skeleton`、`component-selection-imports`、`references/specialized-components.md` |
 | 请求、分页、参数、树数据映射 | `yss-hook` |
 | Formily schema、联动、校验、详情态 | `yss-formily` |
 | 表格高度 | `yss-use-table-height` |
@@ -153,6 +153,7 @@ verification: pnpm type-check
 ## 10. 按需读取
 
 - 组件路由：`references/component-routing.md`
+- 无独立 Skill 的专项组件：`references/specialized-components.md`
 - 版本兼容：`references/antdv-compatibility.md`
 - 主题/locale/浮层：`references/theme-locale-overlay.md`
 - 可访问性与性能：`references/accessibility.md`

package/template/.cursor/skills/yss-ui/references/component-routing.md

@@ -6,17 +6,18 @@
 |---|---|---|---|---|
 | 普通按钮、权限按钮 | `YButton` | AntDV Button | required | 权限、主题和统一动作语义；不得直接导入 Button |
 | 卡片 | `YCard` | AntDV Card | required | YSS 布局与间距扩展 |
-| 数据表格 | `YTable` | VXE Table + AntDV Pagination | specialized | 使用 `yss-components`、`field/type`、字段插槽 |
-| 编辑表格 | `YEditTable` | VXE Table | specialized | 对照 edit-table docs/demo |
-| 树 | `YTree` | AntDV Tree | specialized | 搜索、Tooltip、动作和高度路由 |
+| 数据表格 | `YTable` | VXE Table + AntDV Pagination | specialized | 使用 `ytable-usage`；远程分页交给 `page-list-module`，高度交给 `yss-use-table-height` |
+| 编辑表格 | `YEditTable` | VXE Table | specialized | 使用 `yedit-table-usage`，不要把编辑与普通展示表格混为一套 API |
+| 树 | `YTree` | AntDV Tree | specialized | 使用 `ytree-usage`；高度交给 `yss-use-tree-height` |
 | Schema 表单 | `YFormily` | Formily + AntDV | specialized | `YFormily` 为 canonical；`YssFormily` 仅为历史兼容名；加载 `yss-formily` |
-| 分栏布局 | `YSplitPane` | YSS layout | required | 统一主从页面与容器高度 |
-| 文件导入 | `YFileImport` | Upload/业务适配 | required | 使用 YSS 上传结果和表单适配 |
-| 条件构建 | `YConditionBuilder` | YSS domain component | required | 使用对应 docs/demo |
-| Cron | `YCron` | YSS domain component | required | 底层 Popover 可 fallback |
-| 图表 | `YEcharts` | ECharts | required | 主题、resize、darkMode 使用 YSS API |
-| 编辑器 | `YMonaco` | Monaco | required | 按需加载和尺寸治理 |
-| Sheet | `YSheet` | Univer | required | locale 与资源包按 YSS 文档 |
+| 分栏布局 | `YSplitPane` | YSS layout | required | 页面骨架使用 `page-skeleton`；组件边界见 `specialized-components.md` |
+| 文件导入 | `YFileImport` | Upload/业务适配 | required | 两步导入边界见 `specialized-components.md` |
+| 条件构建 | `YConditionBuilder` | YSS domain component | required | 标准模型与校验边界见 `specialized-components.md` |
+| 月历 | `YMonthCalendar` | YSS domain component | required | 日期、月份、高度与事件边界见 `specialized-components.md` |
+| Cron | `YCron` | YSS domain component | required | 七段表达式边界见 `specialized-components.md` |
+| 图表 | `YssEcharts` | ECharts | required | 主题、更新和尺寸边界见 `specialized-components.md` |
+| 编辑器 | `YMonaco` / `YMonacoDiff` | Monaco | required | 按需加载和尺寸治理见 `specialized-components.md` |
+| Sheet | `YSheet` | Univer | required | Facade、释放和依赖边界见 `specialized-components.md` |
 | 输入、选择、日期 | 无独立通用 Wrapper | AntDV Input/Select/DatePicker 等 | fallback | 读取实际 AntDV 版本；服从 theme/locale/popup 规则 |
 | 浮层反馈 | 无统一 Wrapper | Modal/Drawer/Popover/Tooltip/Alert | fallback | 服从容器、焦点、销毁、z-index 规则 |
 | 服务式反馈 | 无统一 Wrapper | message/notification | fallback | 检查 App/ConfigProvider 上下文 |

package/template/.cursor/skills/yss-ui/references/specialized-components.md

@@ -0,0 +1,52 @@
+# YSS 专项组件契约
+
+本文件只承载尚无独立 Skill 的组件边界。页面编排使用 `yss-ui-business-page-generation`，表格、树、Formily、请求和高度分别加载对应专项 Skill。
+
+## YSplitPane
+
+- 轻内容可使用实时拖拽；树、宽表、编辑器、图表等重内容优先 `resize-mode="deferred"` 与 `collapse-animation="transform"`。
+- 尺寸受控时使用 `v-model:left-width`，纵向使用 `v-model:top-height`；`storage-key` 只保存尺寸，不替代页面状态。
+- 折叠默认保留内容状态。只有允许丢失展开、勾选、滚动等内部状态时才启用销毁。
+
+## YConditionBuilder
+
+- 根值是 `ConditionGroup`；叶子保持字段、操作符和值的标准模型。接口 DSL 的序列化、恢复与错误兜底放入 Hook。
+- 字段切换需要动态操作符或候选值时使用组件公开的加载入口；提交前执行公开校验。
+- 默认严格校验，只有明确允许未完成草稿时才关闭；展示态使用 `disabled`，不使用已废弃的 `readonly`。
+- 组件资料见 `../assets/component-docs/condition-builder-*`，实现前仍须核对目标项目安装版本。
+
+## YMonthCalendar
+
+- `v-model` 管理选中日期，`v-model:month` 管理展示月份，不把二者当作日期范围。
+- `valid-range` 限制范围，`disabled-date` 表达业务禁用日期；业务层仍需规范化起止输入。
+- 自定义日期单元格应保留 today、selected、disabled 等状态语义。
+- `fill-height` 仅用于父容器已有明确高度的场景；键盘、右键和双击动作使用公开事件，不覆盖默认焦点行为。
+
+## YFileImport
+
+- 文件选择、预检、结果回显和最终确认组成两步流程；业务上传与校验由 `nextStep` / `finalImport` 接入。
+- 默认 `beforeUpload=false`，不能期待 `action` 自动上传；直传只通过 `upload-props.customRequest`。
+- `importResult` 展示结果，失败数据通过 `exportErrorData` 下载。弹窗配置与上传器配置保持分离。
+- 组件资料见 `../assets/component-docs/file-import-*`。
+
+## YMonaco / YMonacoDiff
+
+- 分栏折叠或 Drawer 打开等容器尺寸变化后确认已重新布局。
+- 日志增量使用 `appendContent()`，避免频繁重设超大完整字符串。
+- 编辑器必须按需加载并在页面卸载时释放相关资源。
+
+## YCron
+
+- 业务值是七段表达式：秒、分、时、天、月、周、年。
+- 页面只负责双向绑定和禁用态；时区、后端模型转换和生效校验属于 API/Hook 层。
+
+## YSheet
+
+- 必须提供明确容器高度。
+- 初始化后只通过公开 Facade API 修改工作簿，并通过公开保存入口取值；不得直接修改工作簿原始数据对象。
+- 卸载时释放实例，接入前确认 Univer、React、RxJS 等可选依赖及包体影响。
+
+## YssEcharts
+
+- option、更新策略和容器尺寸以目标版本手册与项目已验证实践为准。
+- 不在页面层重复原生 ECharts 初始化、销毁或 ResizeObserver 管理。

package/template/.cursor/skills/yss-web-controller/scripts/generate_controller.mjs

@@ -158,12 +158,13 @@ async function validateContract(contract, args) {
   if (manifestPath !== path.resolve(contract.scaffold_manifest_ref)) throw new Error("--scaffold-manifest-file does not match the approved web generation contract");
   if (!await exists(manifestPath)) throw new Error(`scaffold manifest not found: ${manifestPath}`);
   const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
-  if (![2, 3].includes(manifest.schema_version)) throw new Error("scaffold manifest must use historical schema_version=2 or current schema_version=3");
-  if (mvc && manifest.schema_version !== 3) throw new Error("MVC requires schema v3 scaffold identity");
+  if (![2, 3, 4].includes(manifest.schema_version)) throw new Error("scaffold manifest must use supported schema_version=2/3/4");
+  if (manifest.schema_version === 3 && manifest.legacy_reconciliation?.status !== "approved") throw new Error("historical schema v3 scaffold requires approved legacy reconciliation before business generation");
+  if (mvc && ![3, 4].includes(manifest.schema_version)) throw new Error("MVC requires schema v3/v4 scaffold identity");
   if (manifest.architecture_identity || mvc) {
     assertArchitectureAgreement(contract.architecture_identity, { manifest });
     if (contract.architecture_identity.architecture_profile !== contract.architecture_profile) throw new Error("Web architecture profile differs from its identity");
-  } else if (manifest.schema_version === 3 && (manifest.architecture_family !== "domain-driven" || manifest.generator_skill !== "yss-ddd-scaffold-generator")) throw new Error("schema v3 scaffold manifest must bind the domain-driven generator for Web adapter generation");
+  } else if (manifest.schema_version >= 3 && (manifest.architecture_family !== "domain-driven" || manifest.generator_skill !== "yss-ddd-scaffold-generator")) throw new Error("schema v3/v4 scaffold manifest must bind the domain-driven generator for Web adapter generation");
   if (!["empty-scaffold-verified", "first-slice-verified"].includes(manifest.completion_level)) throw new Error("scaffold manifest must be empty-scaffold-verified before Web generation");
   const scaffoldRoot = path.dirname(path.dirname(manifestPath));
   if (implementationRoot !== scaffoldRoot) throw new Error("implementation_project_root does not match the scaffold manifest project root");

package/template/.cursor/skills/yss-web-controller/scripts/generate_controller.test.mjs

@@ -20,7 +20,7 @@ for (const [profile, module, placement, modules, generator] of [
   const identity = { architecture_family: "layered-mvc", architecture_profile: profile, generator_skill: generator, requested_capabilities: [], resolved_modules: modules, contract_digest: "a".repeat(64), verification_database: "h2", production_database: "not-bound" };
   const project = path.join(data.root, "demo-service");
   const manifestFile = path.join(project, ".yss/scaffold-generation.json");
-  const manifest = { schema_version: 3, project_name: "demo-service", base_package: "com.yss.demo", completion_level: "empty-scaffold-verified", architecture_identity: identity, profiles: { platform: "spring-boot-2.7-jdk8", validation_namespace: "javax" } };
+  const manifest = { schema_version: 4, project_name: "demo-service", base_package: "com.yss.demo", completion_level: "empty-scaffold-verified", architecture_identity: identity, profiles: { platform: "spring-boot-2.7-jdk8", validation_namespace: "javax" } };
   await mkdir(path.dirname(manifestFile), { recursive: true });
   await writeFile(manifestFile, JSON.stringify(manifest));
   const contract = webContract(project, { architecture_profile: profile, architecture_identity: identity, dto_placement: placement, integration_mode: "scaffold-v2", scaffold_manifest_ref: manifestFile, platform_profile: "spring-boot-2.7-jdk8", validation_namespace: "javax", application_service_package: `com.yss.demo.${module}.service` });

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

@@ -88,10 +88,10 @@ node scripts/run_first_slice_verification.mjs \
 - 生成后的后端工程必须使用项目根目录 `./mvnw ...` 执行构建、测试、运行和 CI 验证；不得在 README、实施记录、Ticket、Review 或 Release 中默认写裸 `mvn ...`。既有仓库确实无法使用 wrapper 时，必须记录受控例外。
 - 原型确认后，`scaffold_status=required` 才能进入本 skill；本 skill 的生成边界是工程结构、POM、配置、Wrapper 和机械模板，不是业务实现。
 - 脚手架合同必须携带 `contract_id`、`contract_version`、实现合同编译器 draft 引用、生命周期批准引用、持久化引用、当前版本、允许写路径、预期证据文件和验证命令；字段缺失或版本过期时阻断。
-- 新脚手架优先接受统一 Project Scaffold Contract schema v4；已批准且当前的后端 schema v3 可完成兼容生成。两者都必须携带 `architecture_family=domain-driven`、`generator_skill`、`decision_ref/id/digest`、固定模块闭包，以及 `project_name`、`base_package` 和 `maven_coordinates`。历史 schema v2 仅只读兼容，不用于新生成；schema v1/v2 均不自动升级。
+- 新脚手架只接受统一 Project Scaffold Contract schema v4，并必须以原始字节摘要绑定批准且当前的 Technical Design、Data Architecture Decision v1、API Contract Decision v1 和真实工程合同批准记录。API `required` 必须闭包绑定同一 OpenAPI YAML 字节的 Validation、独立 Review、Freeze 与工程批准；`not-applicable` 必须绑定评估、明确原因和证据且禁止空占位资产。历史 schema v3/v2 仅用于 Manifest 只读验证和补齐 API 对账后的恢复审计，不用于新生成。
 - 合同 `profiles` 只支持 `target-domain-model`、`mybatis-plus`、`mysql`、`spring-boot-2.7-jdk8`、`javax`、`web`、`yss-internal`。普通 MyBatis、Boot 3、独立 client module、client-in-domain 和其他旧架构均为 `unsupported`，不提供回退分支。
 - 运行生成器必须传入 `--contract-file`；生成器会校验合同 `status=approved`、`current_version`、`primary_skill`、`controlled-generation`、实际输出路径和固定三条验证命令，不接受仅凭任意字符串引用的放行。
-- 生成项目必须写入 Manifest v3 `.yss/scaffold-generation.json`，记录架构选择及 digest、生成器、合同 digest、Target Profile、模块闭包、模板 digest、下游完整 skill tree digest、脚手架父合同与 实现合同编译器 合同 digest、generator-owned 文件 hash、严格 `generation_policy` 和完成等级；清单缺失或不一致时不得交给后续 实现合同编译器。
+- 生成项目必须写入 Manifest v4 `.yss/scaffold-generation.json`，记录技术、数据与 API 设计门禁、架构选择及 digest、生成器、合同 digest、Target Profile、模块闭包、模板 digest、下游完整 skill tree digest、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 内的模板升级，必须另行设计和批准，当前不预留可执行承诺。
@@ -109,7 +109,7 @@ node scripts/run_first_slice_verification.mjs \
 - 受控验证器：`scripts/run_scaffold_verification.mjs`
 - 首切片验证器：`scripts/run_first_slice_verification.mjs`
 - 模板目录：`assets/templates/`
-- 分层细化参考：`references/yss-backend-scaffold-parent/` 及其子 skill
+- Parent 工程约束使用已登记的 `references/yss-backend-scaffold-parent/`；生成后的分层实现路由见 `references/layer-skill-routing.md`
 
 ## 阶段 7 合同
 

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

@@ -2,7 +2,7 @@
 
 ## 1. 准备批准合同
 
-新合同是服务级工程基线，使用 schema v3 与 `scaffold_request_id`，并把已批准的架构决策、Java 包名、Maven 坐标和 Profile 分开登记：
+新合同是服务级工程基线，使用 schema v4 与 `scaffold_request_id`，并把已批准的技术/数据设计、工程合同批准、架构决策、Java 包名、Maven 坐标和 Profile 分开登记：
 
 ```json
 {

package/template/.pi/skills/yss-ddd-scaffold-generator/references/layer-skill-routing.md

@@ -0,0 +1,18 @@
+# DDD 分层实现路由
+
+本文件只记录脚手架完成后的分层实现路由，不作为独立 Skill 被发现。实际实现必须回到已批准的 Slice Implementation Contract，并加载对应的顶层权威 Skill。
+
+| 分层或适配器 | 权威 Skill | 边界 |
+|---|---|---|
+| Application | `yss-application` | 编排用例与事务，不复制领域规则。 |
+| Domain | `yss-domain` | 持有聚合、实体、值对象、领域行为和端口。 |
+| Infrastructure | `yss-repository`，按需追加 `yss-mybatis` | 实现持久化端口，不向 Domain 泄漏 PO、Mapper 或框架类型。 |
+| Web | `yss-web-controller`，按需追加 `yss-dto`、`yss-exception`、`yss-validation` | Controller 只调用 Application Service；HTTP 与异常包装停留在 Web 边界。 |
+| Scheduler / External Adapter | 按入口选择 `yss-application`、`yss-web-controller` 或 `yss-repository` | 只做协议、调度或外部系统适配，不承载领域规则。 |
+
+Adapter 额外遵循以下约束：
+
+- 输入先转换为 Application Command / Query，再调用 Application Service。
+- 实现 Application 或 Domain 端口时，签名不得泄漏 HTTP DTO、PO、Mapper 或第三方 SDK 类型。
+- 映射使用 Spring 管理的 MapStruct Bean，禁止静态 `Mappers.getMapper(...)` 或 `INSTANCE`。
+- 旧式 Controller 或旧分层结构不是 `target-domain-model` 的实现依据；架构现代化必须单独立项。

package/template/.pi/skills/yss-ddd-scaffold-generator/references/yss-backend-scaffold-parent/SKILL.md

@@ -40,7 +40,7 @@ infrastructure-+
 
 ## 生成与验证
 
-- 输入是批准且持久化的服务级 scaffold contract schema v3，身份为 `scaffold_request_id`，并绑定已确认的 `architecture_family=domain-driven` 架构决策；不使用 `slice_id`。历史 Manifest v2 仅供验证器只读兼容。
+- 输入是批准、持久化且当前的服务级 scaffold contract schema v4，身份为 `scaffold_request_id`，并绑定已确认的 `architecture_family=domain-driven` 架构决策、Technical Design、Data Architecture Decision v1 与真实工程合同批准；不使用 `slice_id`。历史 Manifest v2/v3 仅供验证器只读兼容。
 - 生成器严格 initialize-only：目标工程目录必须不存在，`--force`、旧项目迁移和当前模板升级均为 `unsupported`。
 - Maven 内部仓库通过命名 profile `yss-internal` 与环境变量注入；共享模板不写内部 URL 或凭据。
 - Wrapper 必须带 checksum；DEBUG 和 MyBatis stdout SQL 只允许在 `application-local.yml`。

package/template/.pi/skills/yss-ddd-scaffold-generator/scripts/first-slice-compatibility.test.mjs

@@ -7,6 +7,7 @@ import os from "node:os";
 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 { generate as generateWeb, parseArgs as parseWebArgs } from "../../yss-web-controller/scripts/generate_controller.mjs";
 import { runFirstSliceVerification } from "./run_first_slice_verification.mjs";
@@ -18,7 +19,12 @@ const execute = (file, args, options = {}) => new Promise((resolve) => execFile(
 
 function scaffoldContract(output, decisionDigest) {
   return {
-    schema_version: 3,
+    schema_version: 4,
+    kind: "project-scaffold-contract",
+    delivery_role: "backend",
+    scaffold_kind: "backend-ddd",
+    repository_scope: "external-repository",
+    init_git: false,
     contract_id: "golden-scaffold-1",
     contract_version: 1,
     scaffold_request_id: "golden-request-1",
@@ -26,7 +32,7 @@ function scaffoldContract(output, decisionDigest) {
     compiler_draft_ref: "compiler-golden-1",
     lifecycle_approval_ref: "approval-golden-1",
     persisted_ref: "persisted-golden-1",
-    current_version: 1,
+    current_version: true,
     implementation_repository: "external",
     backend_repository: "external",
     scaffold_status: "required",
@@ -69,8 +75,11 @@ async function prepareGoldenProject(t) {
   await writeFile(decisionFile, decisionText);
   const decisionDigest = `sha256:${createHash("sha256").update(decisionText).digest("hex")}`;
   const contractFile = path.join(root, "scaffold-contract.json");
-  await writeFile(contractFile, `${JSON.stringify(scaffoldContract(output, decisionDigest), null, 2)}\n`);
-  const args = ["--project-name", "golden-service", "--base-package", "com.yss.golden", "--output-dir", output, "--contract-id", "golden-scaffold-1", "--contract-version", "1", "--approval-ref", "approval-golden-1", "--compiler-draft-ref", "compiler-golden-1", "--persisted-ref", "persisted-golden-1", "--contract-file", contractFile, "--group-id", "com.yss.datamiddle", "--project-version", "1.0.0-SNAPSHOT", "--parent-group-id", "com.yss.datamiddle", "--parent-artifact-id", "yss-datamiddle-parent", "--parent-version", "2.0.0-SNAPSHOT", "--yss-components-version", "2.0.0-SNAPSHOT"];
+  const contract = scaffoldContract(output, decisionDigest);
+  contract.decision_ref = decisionFile;
+  attachDesignPrerequisites(root, contract);
+  await writeFile(contractFile, `${JSON.stringify(contract, null, 2)}\n`);
+  const args = ["--project-name", "golden-service", "--base-package", "com.yss.golden", "--output-dir", output, "--contract-id", "golden-scaffold-1", "--contract-version", "1", "--approval-ref", contract.lifecycle_approval_ref, "--compiler-draft-ref", "compiler-golden-1", "--persisted-ref", "persisted-golden-1", "--contract-file", contractFile, "--group-id", "com.yss.datamiddle", "--project-version", "1.0.0-SNAPSHOT", "--parent-group-id", "com.yss.datamiddle", "--parent-artifact-id", "yss-datamiddle-parent", "--parent-version", "2.0.0-SNAPSHOT", "--yss-components-version", "2.0.0-SNAPSHOT"];
   const generated = await execute(process.execPath, [generator, ...args]);
   assert.equal(generated.code, 0, generated.stderr);
   const project = path.join(output, "golden-service");

package/template/.pi/skills/yss-ddd-scaffold-generator/scripts/generate_scaffold.mjs

@@ -10,6 +10,7 @@ import { parseDocument } from "../../../../scripts/vendor/yaml.mjs";
 import { assertLocalDatabaseProfile, localDatabaseConfiguration, scaffoldArchitectureIdentity } from "../../../../scripts/lib/scaffold-local-database.mjs";
 import { validateArchitectureIdentity } from "../../../../scripts/lib/backend-architecture.mjs";
 import { validateJsonSchema } from "../../../../scripts/lib/json-schema.mjs";
+import { validateBackendScaffoldPrerequisites } from "../../../../scripts/lib/backend-scaffold-prerequisites.mjs";
 
 import {
   findGitRoot,
@@ -205,9 +206,9 @@ class ScaffoldGenerator {
     const contractText = await readFile(this.contractFile, "utf8");
     let contract; try { contract = JSON.parse(contractText); } catch { fail(`脚手架合同文件无法读取或不是合法 JSON: ${this.contractFile}`); }
     if (!contract || Array.isArray(contract) || typeof contract !== "object") fail("脚手架合同必须是 JSON 对象");
-    if (![3, 4].includes(contract.schema_version)) fail(`unsupported: scaffold contract schema_version=${contract.schema_version}；只接受兼容 v3 或统一 v4`);
-    if (contract.schema_version === 4 && (contract.kind !== "project-scaffold-contract" || contract.delivery_role !== "backend" || contract.scaffold_kind !== "backend-ddd")) fail("schema v4 合同必须绑定 backend/backend-ddd");
-    if (contract.schema_version === 4) validateJsonSchema(contract, path.join(REPOSITORY_ROOT, "docs/process/schemas/project-scaffold-contract.schema.json"), { label: "Project Scaffold Contract v4" });
+    if (contract.schema_version !== 4) fail(`unsupported: 后端新生成只接受 Project Scaffold Contract v4，收到 v${contract.schema_version}`);
+    if (contract.kind !== "project-scaffold-contract" || contract.delivery_role !== "backend" || contract.scaffold_kind !== "backend-ddd") fail("schema v4 合同必须绑定 backend/backend-ddd");
+    validateJsonSchema(contract, path.join(REPOSITORY_ROOT, "docs/process/schemas/project-scaffold-contract.schema.json"), { label: "Project Scaffold Contract v4" });
     const requiredMetadata = [["--contract-id", this.options.contractId], ["--contract-version", this.options.contractVersion], ["--approval-ref", this.options.approvalRef], ["--compiler-draft-ref", this.options.compilerDraftRef], ["--persisted-ref", this.options.persistedRef]];
     const missing = requiredMetadata.filter(([, value]) => !isPresent(value)).map(([flag]) => flag);
     if (missing.length) fail(`生成项目必须提供当前已批准脚手架合同的完整元数据: ${missing.join(", ")}`);
@@ -217,7 +218,7 @@ class ScaffoldGenerator {
     if (contract.status !== "approved") fail("脚手架合同必须已由生命周期批准");
     if (contract.contract_id !== this.options.contractId) fail("--contract-id 与脚手架合同不一致");
     if (contract.contract_version !== this.options.contractVersion) fail("--contract-version 与脚手架合同不一致");
-    if (contract.current_version !== contract.contract_version && !(contract.schema_version === 4 && contract.current_version === true)) fail("脚手架合同版本不是当前版本");
+    if (contract.current_version !== true) fail("脚手架合同版本不是当前版本");
     if (contract.compiler_draft_ref !== this.options.compilerDraftRef) fail("--compiler-draft-ref 与脚手架合同不一致");
     if (contract.persisted_ref !== this.options.persistedRef) fail("--persisted-ref 与脚手架合同不一致");
     if (contract.lifecycle_approval_ref !== this.options.approvalRef) fail("--approval-ref 与脚手架合同不一致");
@@ -255,7 +256,8 @@ class ScaffoldGenerator {
     if (!decision || decision.status !== "lifecycle-approved" || decision.confirmed_architecture !== "domain-driven" || decision.project_id !== contract.project_name) fail("架构决策未批准、项目不匹配或不是 domain-driven");
     if (decision.platform_profile !== contract.profiles.platform || decision.architecture_profile !== contract.architecture_profile || decision.verification_database !== "h2" || decision.production_database !== "not-bound" || Object.hasOwn(decision, "database_profile") || JSON.stringify(decision.requested_capabilities) !== JSON.stringify(contract.module_profile.requested_capabilities) || JSON.stringify(decision.resolved_modules) !== JSON.stringify(contract.module_profile.resolved_modules)) fail("架构决策的 Profile 或模块闭包与脚手架合同不一致");
     if (!decision.user_confirmation || Object.values(decision.user_confirmation).some((value) => !isPresent(value))) fail("架构决策缺少完整用户确认记录");
-  assertScaffoldUserDecision(decision);
+    assertScaffoldUserDecision(decision);
+    this.designPrerequisites = await validateBackendScaffoldPrerequisites(contract, { contractFile: this.contractFile });
     const generationPolicy = contract.generation_policy;
     if (!generationPolicy || generationPolicy.mode !== "initialize-only" || generationPolicy.existing_target !== "unsupported" || generationPolicy.old_project_migration !== "unsupported" || generationPolicy.template_upgrade !== "unsupported") fail("脚手架合同 generation_policy 必须声明 initialize-only，且 existing_target、old_project_migration、template_upgrade 均为 unsupported");
     this.contractDigest = sha256(contractText);
@@ -366,8 +368,7 @@ class ScaffoldGenerator {
     }
     const scaffoldParent = path.join(SKILL_ROOT, "references", "yss-backend-scaffold-parent", "SKILL.md");
     const compilerContract = path.join(REPOSITORY_ROOT, ".agents", "skills", "yss-implementation-contract-compiler", "references", "compiler-contract.yaml");
-    const manifest = { schema_version: 3, kind: "backend-scaffold", architecture_profile: contract.architecture_profile, architecture_identity: scaffoldArchitectureIdentity(contract, this.contractDigest), contract_id: this.options.contractId, contract_version: this.options.contractVersion, scaffold_request_id: contract.scaffold_request_id, architecture_family: contract.architecture_family, generator_skill: contract.generator_skill, decision_id: contract.decision_id, decision_digest: contract.decision_digest, module_profile: contract.module_profile, approval_ref: this.options.approvalRef, compiler_draft_ref: this.options.compilerDraftRef, persisted_ref: this.options.persistedRef, contract_file_ref: this.contractFile, contract_digest: this.contractDigest, lifecycle_approval_ref: contract.lifecycle_approval_ref, current_version: contract.current_version, approver: contract.approval.approver, allowed_write_paths: contract.allowed_write_paths, expected_evidence_files: contract.expected_evidence_files, project_name: this.projectName, base_package: this.basePackage, bootstrap_main_class: `${this.basePackage}.${this.applicationClassName}`, bootstrap_main_source: this.bootstrapMainSource, maven_coordinates: this.mavenCoordinates, maven_coordinates_source: this.mavenCoordinatesSource, profiles: this.profiles, generation_mode: "controlled-generation", completion_level: "generated", generator: { id: "yss-ddd-scaffold-generator", template_digest: await treeDigest(path.join(SKILL_ROOT, "assets")) }, ownership: { generated_files: generatedFiles, user_owned_globs: ["**/src/main/java/**", "**/src/test/java/**", "db/**"] }, readiness: { downstream_skills: downstream, contracts: { scaffold_parent: sha256(await readFile(scaffoldParent)), compiler_contract: sha256(await readFile(compilerContract)) }, architecture_ruleset: sha256(await readFile(path.join(this.javaTemplateDir, "architecture-rules-test.java.template"))) }, generation_policy: { mode: "initialize-only", existing_target: "unsupported", old_project_migration: "unsupported", template_upgrade: "unsupported" }, verification_commands: COMMANDS, generated_at: isoNow() };
-    manifest.schema_version = contract.schema_version;
+    const manifest = { schema_version: 4, kind: "backend-scaffold", architecture_profile: contract.architecture_profile, architecture_identity: scaffoldArchitectureIdentity(contract, this.contractDigest), contract_id: this.options.contractId, contract_version: this.options.contractVersion, scaffold_request_id: contract.scaffold_request_id, architecture_family: contract.architecture_family, generator_skill: contract.generator_skill, decision_id: contract.decision_id, decision_digest: contract.decision_digest, module_profile: contract.module_profile, design_prerequisites: this.designPrerequisites, approval_ref: this.options.approvalRef, compiler_draft_ref: this.options.compilerDraftRef, persisted_ref: this.options.persistedRef, contract_file_ref: this.contractFile, contract_digest: this.contractDigest, lifecycle_approval_ref: contract.lifecycle_approval_ref, current_version: contract.current_version, approver: contract.approval.approver, allowed_write_paths: contract.allowed_write_paths, expected_evidence_files: contract.expected_evidence_files, project_name: this.projectName, base_package: this.basePackage, bootstrap_main_class: `${this.basePackage}.${this.applicationClassName}`, bootstrap_main_source: this.bootstrapMainSource, maven_coordinates: this.mavenCoordinates, maven_coordinates_source: this.mavenCoordinatesSource, profiles: this.profiles, generation_mode: "controlled-generation", completion_level: "generated", generator: { id: "yss-ddd-scaffold-generator", template_digest: await treeDigest(path.join(SKILL_ROOT, "assets")) }, ownership: { generated_files: generatedFiles, user_owned_globs: ["**/src/main/java/**", "**/src/test/java/**", "db/**"] }, readiness: { downstream_skills: downstream, contracts: { scaffold_parent: sha256(await readFile(scaffoldParent)), compiler_contract: sha256(await readFile(compilerContract)) }, architecture_ruleset: sha256(await readFile(path.join(this.javaTemplateDir, "architecture-rules-test.java.template"))) }, generation_policy: { mode: "initialize-only", existing_target: "unsupported", old_project_migration: "unsupported", template_upgrade: "unsupported" }, verification_commands: COMMANDS, generated_at: isoNow() };
     await writeText(path.join(this.projectRoot, ".yss", "scaffold-generation.json"), `${JSON.stringify(manifest, null, 2)}\n`); console.log("  ✓ .yss/scaffold-generation.json");
   }
   async copyWrapperFiles() {
@@ -379,7 +380,7 @@ class ScaffoldGenerator {
     const required = [path.join(this.projectRoot, "pom.xml"), path.join(this.projectRoot, `${this.projectName}-bootstrap`, "pom.xml"), path.join(this.projectRoot, this.bootstrapMainSource), path.join(this.projectRoot, "mvnw"), path.join(this.projectRoot, ".yss", "scaffold-generation.json")];
     const missing = []; for (const target of required) if (!await isFile(target)) missing.push(target); if (missing.length) fail(`生成产物缺失: ${missing.join(", ")}`);
     const manifest = await readJson(required[4], "脚手架生成元数据清单无法读取");
-    if (![3, 4].includes(manifest.schema_version) || manifest.contract_id !== this.options.contractId || manifest.contract_version !== this.options.contractVersion || (manifest.current_version !== this.options.contractVersion && manifest.current_version !== true) || manifest.generation_mode !== "controlled-generation" || manifest.architecture_family !== "domain-driven" || manifest.generator_skill !== "yss-ddd-scaffold-generator" || manifest.decision_id !== this.scaffoldContract.decision_id || manifest.decision_digest !== this.scaffoldContract.decision_digest || JSON.stringify(manifest.module_profile) !== JSON.stringify(this.scaffoldContract.module_profile) || manifest.bootstrap_main_class !== `${this.basePackage}.${this.applicationClassName}` || manifest.bootstrap_main_source !== this.bootstrapMainSource || manifest.profiles.architecture !== SUPPORTED_PROFILES.architecture || manifest.generation_policy.mode !== "initialize-only" || manifest.generation_policy.existing_target !== "unsupported" || JSON.stringify(manifest.verification_commands) !== JSON.stringify(COMMANDS)) fail("脚手架生成元数据清单与当前批准架构决策、合同、Target Profile、initialize-only 边界、机械启动入口或固定验证命令不一致");
+    if (manifest.schema_version !== 4 || manifest.contract_id !== this.options.contractId || manifest.contract_version !== this.options.contractVersion || manifest.current_version !== true || manifest.generation_mode !== "controlled-generation" || manifest.architecture_family !== "domain-driven" || manifest.generator_skill !== "yss-ddd-scaffold-generator" || manifest.decision_id !== this.scaffoldContract.decision_id || manifest.decision_digest !== this.scaffoldContract.decision_digest || JSON.stringify(manifest.module_profile) !== JSON.stringify(this.scaffoldContract.module_profile) || JSON.stringify(manifest.design_prerequisites) !== JSON.stringify(this.designPrerequisites) || manifest.bootstrap_main_class !== `${this.basePackage}.${this.applicationClassName}` || manifest.bootstrap_main_source !== this.bootstrapMainSource || manifest.profiles.architecture !== SUPPORTED_PROFILES.architecture || manifest.generation_policy.mode !== "initialize-only" || manifest.generation_policy.existing_target !== "unsupported" || JSON.stringify(manifest.verification_commands) !== JSON.stringify(COMMANDS)) fail("脚手架生成元数据清单与当前批准设计、架构决策、合同、Target Profile、initialize-only 边界、机械启动入口或固定验证命令不一致");
     const stack = [this.projectRoot], binary = new Set([".class", ".db", ".jar", ".png", ".jpg", ".jpeg", ".gif"]);
     while (stack.length) { const dir = stack.pop(); for (const entry of await readdir(dir, { withFileTypes: true })) { const target = path.join(dir, entry.name); if (entry.isDirectory()) { stack.push(target); continue; } if (!entry.isFile() || binary.has(path.extname(entry.name))) continue; const content = await readFile(target, "utf8"); if (content.includes("{{") || content.includes("root/root")) fail(`生成文件包含未替换占位符或明文凭据: ${target}`); } }
   }

package/template/.pi/skills/yss-ddd-scaffold-generator/scripts/run_first_slice_verification.mjs

@@ -133,7 +133,8 @@ export async function runFirstSliceVerification(projectRoot, evidenceDir, sliceC
     assertArchitectureAgreement(identity, { manifest });
     for (const unit of contract.work_units ?? []) assertArchitectureAgreement(identity, { work_unit: unit.architecture_identity });
   } catch (error) { contractFailures.push(`architecture-identity:${error.message}`); }
-  if (![2, 3].includes(manifest.schema_version) || manifest.completion_level !== "empty-scaffold-verified") contractFailures.push("scaffold-not-empty-scaffold-verified");
+  if (![2, 3, 4].includes(manifest.schema_version) || manifest.completion_level !== "empty-scaffold-verified") contractFailures.push("scaffold-not-empty-scaffold-verified");
+  if (manifest.schema_version === 3 && manifest.legacy_reconciliation?.status !== "approved") contractFailures.push("legacy-scaffold-reconciliation-required");
   const projectFiles = await files(projectRoot);
   const missingArtifacts = adapter.artifacts.filter(([, pattern]) => !projectFiles.some((file) => pattern.test(file))).map(([name]) => name);
   const skillDrift = await downstreamDrift(manifest, adapter.skills);

package/template/.pi/skills/yss-ddd-scaffold-generator/scripts/run_scaffold_verification.mjs

@@ -41,20 +41,22 @@ function parseArgs(argv) { const result = {}; for (let index = 0; index < argv.l
 function validateManifest(manifest) {
   if (![2, 3, 4].includes(manifest.schema_version)) throw new Error(`unsupported: scaffold Manifest schema_version=${manifest.schema_version}；只读兼容 v2，并验证当前 v3/v4`);
   const required = ["schema_version", "contract_id", "contract_version", "scaffold_request_id", "contract_digest", "profiles", "ownership", "readiness", "generation_policy", "completion_level", "approval_ref", "approver", "lifecycle_approval_ref", "compiler_draft_ref", "persisted_ref", "contract_file_ref", "current_version", "allowed_write_paths", "expected_evidence_files", "verification_commands", "generation_mode"];
-  if (manifest.schema_version === 3) required.push("architecture_family", "generator_skill", "decision_id", "decision_digest", "module_profile");
+  if (manifest.schema_version >= 3) required.push("architecture_family", "generator_skill", "decision_id", "decision_digest", "module_profile");
+  if (manifest.schema_version === 4) required.push("design_prerequisites");
   const missing = required.filter((field) => manifest[field] === undefined || manifest[field] === null || manifest[field] === "");
   if (manifest.generation_mode !== "controlled-generation" || missing.length) throw new Error(`脚手架生成元数据清单不完整或不是 controlled-generation: ${missing.join(", ")}`);
-  if (manifest.schema_version === 3) {
+  if (manifest.schema_version >= 3) {
     if (manifest.kind || manifest.architecture_identity) {
       assertLocalDatabaseProfile(manifest.profiles);
       assertArchitectureAgreement(manifest.architecture_identity, { manifest_fields: scaffoldArchitectureIdentity(manifest, manifest.contract_digest) });
     }
     const supportedArchitecture = manifest.architecture_family === "domain-driven" && manifest.generator_skill === "yss-ddd-scaffold-generator" && manifest.profiles.architecture === "target-domain-model"
       || manifest.architecture_family === "layered-mvc" && ["yss-layered-mvc-scaffold-generator", "yss-mvc-data-analysis-project-initializer"].includes(manifest.generator_skill) && manifest.profiles.architecture === "layered-mvc";
-    if (!supportedArchitecture || manifest.module_profile?.resolution_version !== 1 || !Array.isArray(manifest.module_profile?.resolved_modules)) throw new Error("Manifest v3 的架构族、生成器、Profile 或模块闭包不一致");
+    if (!supportedArchitecture || manifest.module_profile?.resolution_version !== 1 || !Array.isArray(manifest.module_profile?.resolved_modules)) throw new Error("Manifest v3/v4 的架构族、生成器、Profile 或模块闭包不一致");
+    if (manifest.schema_version === 4 && (!manifest.design_prerequisites?.technical_design || !manifest.design_prerequisites?.data_architecture_decision || !manifest.design_prerequisites?.engineering_contract_approval_ref)) throw new Error("Manifest v4 缺少设计门禁绑定");
   } else if (manifest.profiles.architecture !== "target-domain-model") throw new Error("历史 Manifest v2 只读兼容仅支持 target-domain-model");
   if (manifest.generation_policy.mode !== "initialize-only" || manifest.generation_policy.existing_target !== "unsupported" || manifest.generation_policy.old_project_migration !== "unsupported" || manifest.generation_policy.template_upgrade !== "unsupported") throw new Error("Manifest 必须声明严格 initialize-only；已有目标、旧项目迁移和模板升级均须为 unsupported");
-  if (manifest.current_version !== manifest.contract_version) throw new Error("脚手架生成元数据清单不是当前合同版本");
+  if (manifest.schema_version === 4 ? manifest.current_version !== true : manifest.current_version !== manifest.contract_version) throw new Error("脚手架生成元数据清单不是当前合同版本");
   if (JSON.stringify(manifest.verification_commands) !== JSON.stringify(COMMANDS)) throw new Error("脚手架生成元数据清单验证命令不符合固定合同");
 }
 export async function run(projectRoot, evidenceDir, environment = process.env, { timeoutMs = 0, signal } = {}) {