create-yss-spec 2.2.10 → 3.0.0

package/template/.qoder/skills/yss-research/tests/run-scenarios.mjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const validator = path.join(root, "scripts/validate-research-package.mjs");
+const template = JSON.parse(readFileSync(path.join(root, "assets/evidence-template.yaml"), "utf8"));
+const directory = mkdtempSync(path.join(tmpdir(), "yss-research-"));
+const brief = path.join(directory, "sample-research-brief.md");
+const evidence = path.join(directory, "sample-evidence.yaml");
+const headings = ["Research Scope", "Executive Read", "Findings", "Counter-Signals", "Source Map", "Decision Handoff", "Evidence Limitations"];
+
+function run(payload, status, expected) {
+  writeFileSync(brief, `${headings.map((heading) => `## ${heading}`).join("\n\n")}\n\n${payload.claims.map((claim) => claim.id).join(" ")}\n`);
+  writeFileSync(evidence, `${JSON.stringify(payload, null, 2)}\n`);
+  const result = spawnSync(process.execPath, [validator, brief, evidence], { encoding: "utf8" });
+  if (result.status !== status || !`${result.stdout}${result.stderr}`.includes(expected)) throw new Error(`expected ${status}/${expected}, got ${result.status}: ${result.stdout}${result.stderr}`);
+}
+
+try {
+  template.scope.topic = "Example strategy question";
+  template.scope.audience = "Product team";
+  template.scope.time_horizon = "Last 12 months";
+  template.scope.research_questions = ["Which problem should the domain address?"];
+  template.scope.inclusion_criteria = ["Direct experience in scope"];
+  template.scope.exclusion_criteria = ["Untraceable reposts"];
+  template.ownership.downstream_owner = "yss-stage-decision";
+  template.search_log[0].channel = "Support records";
+  template.search_log[0].query_or_corpus = "failed approval workflow";
+  template.search_log[0].searched_at = "2026-09-03";
+  template.search_log[1].channel = "Support records";
+  template.search_log[1].query_or_corpus = "successful approval workflow";
+  template.search_log[1].searched_at = "2026-09-03";
+  template.evidence_items[0].source_class = "support";
+  template.evidence_items[0].source_ref = "support-case-001";
+  template.evidence_items[0].locator = "event-3";
+  template.evidence_items[0].observed_at = "2026-09-03";
+  template.evidence_items[0].evidence_date = "2026-08-30";
+  template.evidence_items[0].observation = "The approval stopped when the owner was missing.";
+  template.evidence_items[0].limitations = ["Single support case"];
+  template.claims[0].statement = "A missing owner can block the approval workflow.";
+  run(template, 0, "YSS research package valid");
+
+  const falseStrategyBackground = structuredClone(template);
+  falseStrategyBackground.claims[0].decision_bearing = false;
+  run(falseStrategyBackground, 1, "strategy claim kind must be decision-bearing");
+
+  const unsupported = structuredClone(template);
+  unsupported.claims[0].audit_status = "unsupported";
+  unsupported.claims[0].disposition = "publish";
+  run(unsupported, 1, "must use needs-deeper-research");
+
+  const unsupportedDecision = structuredClone(template);
+  unsupportedDecision.claims[0].audit_status = "unsupported";
+  unsupportedDecision.claims[0].disposition = "needs-deeper-research";
+  run(unsupportedDecision, 1, "decision-bearing and cannot remain unsupported");
+
+  const falseCounter = structuredClone(template);
+  falseCounter.claims[0].counter_signal_refs = ["search-001"];
+  run(falseCounter, 1, "counter-signal search must have result none-found");
+
+  const technicalWithoutPrimary = structuredClone(template);
+  technicalWithoutPrimary.profile = "technical-evidence";
+  technicalWithoutPrimary.claims[0].claim_kind = "technical-fact";
+  run(technicalWithoutPrimary, 1, "technical claim without primary evidence");
+
+  const leadOnly = structuredClone(template);
+  leadOnly.evidence_items[0].source_level = "lead-only";
+  run(leadOnly, 1, "uses lead-only evidence as support");
+
+  const unaudited = structuredClone(template);
+  unaudited.audit_summary.audited_claim_ids = [];
+  run(unaudited, 1, "must be a non-empty array");
+
+  process.stdout.write("YSS research scenarios passed (8)\n");
+} finally {
+  rmSync(directory, { recursive: true, force: true });
+}

package/template/.qoder/skills/yss-router/references/router-contract.yaml

@@ -5,6 +5,7 @@ skill_aliases:
   api-integration: yss-api-integration
   microapp-commit: yss-microapp-commit
   page-module-development: yss-page-module-development
+  research: yss-research
   use-table-height: yss-use-table-height
   use-tree-height: yss-use-tree-height
 implementation_path_policy:
@@ -197,10 +198,10 @@ dependency_closure:
     always: [alibaba-java-code-style]
     when_conversion: [mapstruct, lombok]
   yss-repository:
-    always: [mapstruct, lombok, alibaba-java-code-style]
-    when_mybatis: [yss-mybatis]
+    always: [yss-mybatis, mapstruct, lombok, alibaba-java-code-style]
   yss-web-controller:
-    always: [yss-dto, mapstruct, lombok, alibaba-java-code-style]
+    always: [yss-dto, yss-validation, mapstruct, lombok, alibaba-java-code-style]
+    when_error_mapping: [yss-exception]
   yss-userinfo:
     always: [yss-dto]
     when_cache_lookup: [yss-cache]
@@ -245,8 +246,11 @@ end_to_end_backend_required:
   - yss-domain
   - yss-application
   - yss-repository
+  - yss-mybatis
   - yss-web-controller
   - yss-dto
+  - yss-exception
+  - yss-validation
   - mapstruct
   - lombok
   - alibaba-java-code-style

package/template/.qoder/skills/yss-stage-decision/SKILL.md

@@ -17,7 +17,7 @@ description: 编排 Discovery 到 Spec 入口的阶段决策与 DDD 战略设计
 ## 执行顺序
 
 1. 读取 `yss-project.yaml`、`CONTEXT.md`、既有 Discovery/Spec、ADR 和父 Ticket/checkpoint。
-2. 分离事实、决策、假设、约束和未决项；技术事实走 `research`，市场/竞品事实走 `competitive-intelligence`。
+2. 分离事实、决策、假设、约束和未决项；技术事实走 `yss-research` 的 `technical-evidence`，领域边界、业务规则、MVP、非目标、成功标准或阶段推进依据等决策证据走 `strategy-evidence`，市场/竞品事实走 `competitive-intelligence`。
 3. 从业务场景、事件、规则、责任人和失败路径识别子域及限界上下文，不从数据库表或调用链直接反推边界。
 4. 为每个上下文建立本地统一语言；为跨上下文关系记录语义上游/下游、业务决策权、技术传输方向和翻译责任。
 5. 记录核心领域概念候选，不提前锁定 Entity 或 Aggregate。
@@ -31,6 +31,7 @@ description: 编排 Discovery 到 Spec 入口的阶段决策与 DDD 战略设计
 ## 产物与批准
 
 - DDD 资产是事实源，阶段决策包只通过 `domain_strategy_ref` 引用它们。
+- 进入 `gate.domain-strategy-approved` 或 `gate.stage-decision-package-approved` 的外部决策证据必须引用通过校验的 `yss-research` `evidence-audited` 研究包；研究包只提供证据，不得直接修改本技能资产或批准门禁。
 - `stage_decision_package` 必须经过 `draft → ready-for-human → approved`；起草者不得自签。
 - 建议门禁为 `gate.domain-strategy-approved` 和 `gate.stage-decision-package-approved`，实际状态由 `yss-product-lifecycle` 维护；阶段包批准引用必须通过 `scripts/verify-approval-record`，不得用不可读路径或聊天确认替代。
 - 下游只能消费批准且版本当前的包；发现语义冲突返回 `drift` / `new_impacts`，不得静默修改上游。

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

@@ -16,16 +16,17 @@ description: Use when generating or refactoring YSS Web Adapter Controllers, req
 ## 不适用
 
 - 用户只是要新增一个手写复杂接口，不一定要用脚本。
-- 用户还没有稳定的领域模型或 metadata，先补 `yss-domain` 并准备完整的 metadata 输入。
+- 用户还没有稳定的 Application Service、冻结 OpenAPI 或 metadata，先回 Router 补 `yss-application` / `yss-domain` 和相应合同输入。
 
 ## 优先流程
 
-1. 先确认冻结 OpenAPI、批准的 Web generation contract、Application Service 接口、metadata、基础包、模块名、领域 segment 和 web 落盘目录；合同中的 `base_package`、`module_name`、`domain_segment` 必须与 CLI 一致。
-2. 涉及 DTO / VO / CMD / Query POJO 样板代码时，加载并遵守 `lombok`。
-3. 涉及 Domain / Application Result 到 VO / DTO 或 CMD / Query 到输入模型的转换时，加载并遵守 `mapstruct`。
-4. 运行 `node scripts/generate_controller.mjs`。
-5. 生成后检查路径、命名、返回值包装、Application Service 引用、`@Valid`、Lombok 注解和 MapStruct WebConvertor 是否对齐项目。
-6. 对复杂接口做少量手工修正，不在 skill 中承诺自动覆盖全部业务逻辑。
+1. 先确认冻结 OpenAPI、批准且版本当前的 Web generation contract schema v2、Application Service 接口、metadata、基础包、模块名、领域 segment 和 web 落盘目录；合同必须绑定 Slice `contract_id` / `contract_version` / `slice_id`、`yss-dto` wire profile 引用与 digest、允许写路径、证据与验证命令。
+2. 加载并遵守 `yss-dto` 与 `yss-validation`；错误映射影响命中时再加载 `yss-exception`。
+3. 涉及 DTO / VO / CMD / Query POJO 样板代码时，加载并遵守 `lombok`。
+4. 涉及 Domain / Application Result 到 VO / DTO 或 CMD / Query 到输入模型的转换时，加载并遵守 `mapstruct`。
+5. 运行 `node scripts/generate_controller.mjs`。
+6. 生成后检查路径、命名、返回值包装、Application Service 引用、`@Valid`、Lombok 注解和 MapStruct WebConvertor 是否对齐项目。
+7. 对复杂接口做少量手工修正，不在 skill 中承诺自动覆盖全部业务逻辑。
 
 ## 推荐命令
 
@@ -33,6 +34,8 @@ description: Use when generating or refactoring YSS Web Adapter Controllers, req
 node scripts/generate_controller.mjs \
   --metadata-file /path/metadata.json \
   --contract-file /path/approved-web-generation-contract.json \
+  --dto-wire-profile-file /path/to/yss-dto/references/openapi-wire-profile.yaml \
+  --scaffold-manifest-file /path/service/.yss/scaffold-generation.json \
   --base-package com.yss.demo \
   --module-name demo \
   --domain-segment example \
@@ -53,18 +56,21 @@ node scripts/generate_controller.mjs \
 ## 约束
 
 - 生成代码只依赖既有 Application Service；读写操作都禁止绕过 Application。复杂查询经 Application Query Port 接入 Infrastructure。
-- 返回结构保持项目既有 `SingleResult`、`PageResult`、`MultiResult` 体系。
+- 返回包装类、分页默认值、允许字段与 `PageResult.of(...)` 参数语义必须消费合同绑定的 `yss-dto/references/openapi-wire-profile.yaml`；Web skill 不复制或自行维护第二套协议。
 - DTO / VO / CMD / Query 默认用 Lombok 处理 getter/setter、constructor、builder 和日志样板；不要在 Controller 内部类或非约定包临时定义主要 DTO / VO。
 - `WebConvertor` 使用 `@Mapper(componentModel = "spring")` 和构造器注入；禁止静态 `INSTANCE`、在 Controller / Application 中大段手写字段赋值、使用 `BeanUtils.copyProperties` 或反射式通用拷贝。
 - HTTP Request 不继承会暴露内部协作字段的 `PageQuery`；只生成冻结 OpenAPI allowlist 字段，禁止把 `offset`、`needTotalCount`、`tempTotalCount` 变成客户端输入。
+- `fields.<table>.pagination` 必须显式列出 `yss-dto` wire profile 允许暴露的字段子集；模板不得无条件生成字段或自行定义默认值。
 - 先跑脚本，再按项目规范做少量手调。
 - `javax` / `jakarta` validation namespace 必须来自工程基线，不得按记忆选择。
 - 若用户只是要改单个 Controller，先看现有代码，不要盲覆盖整个目录。
-- 脚本是 initialize-only；写入前先规划全部目标，任一目标已存在或传入 `--force` 时整体返回 `unsupported` 且不得留下部分文件。旧项目迁移不属于该生成器。
+- 脚本是 initialize-only；写入前先规划全部目标并校验 `allowed_write_paths`，任一目标已存在或传入 `--force` 时整体返回 `unsupported`。落盘使用排他创建和失败回滚，不得留下部分文件；旧项目迁移不属于该生成器。
+- `integration_mode=existing-project` 保留已登记工程的 Boot 2/Boot 3 能力；`integration_mode=scaffold-v2` 必须提供 `--scaffold-manifest-file`，且 Manifest 已达到 `empty-scaffold-verified`，Profile、基础包和标准 Web module 路径全部一致。
 
 ## 按需读取
 
 - 分层开发规范：`references/web-adapter-layer-guide.md`
+- Web 生成合同 schema：`references/web-generation-contract.schema.json`
 - 生成脚本：`scripts/generate_controller.mjs`
 - Controller 模板：`assets/templates/Controller.java.template`
 - Convertor 模板：`assets/templates/WebConvertor.java.template`
@@ -73,7 +79,7 @@ node scripts/generate_controller.mjs \
 
 ## 阶段 7 合同
 
-- 只消费已批准合同和冻结 OpenAPI/no-impact record；不得用 Controller 或半成品 backend 反向定义产品契约。
+- 只消费已批准且当前的 schema v2 Web generation contract 和冻结 OpenAPI/no-impact record；schema v1 为 `unsupported`，不得自动升级，也不得用 Controller 或半成品 backend 反向定义产品契约。
 - DTO/VO/WebConvertor 机械骨架可用 `controlled-generation`；权限、错误映射、校验语义和接口行为必须使用 `behavior-tdd`。
 - 写入必须位于合同 `allowed_write_paths`，并提供 Controller、DTO/VO、WebConvertor、契约/API 测试和实际验证结果。
 - 按统一 `YSS Skill Execution Result` 返回偏离与新增影响；出现新 API/schema、权限或响应包装变化时暂停并回到 Router/生命周期。

package/template/.qoder/skills/yss-web-controller/agents/openai.yaml

@@ -1,5 +1,5 @@
 version: 1
 interface:
   display_name: "YSS Web Controller"
-  short_description: "Web Controller、DTO、VO 与响应封装规范"
-  default_prompt: "Use $yss-web-controller to generate or refactor a YSS REST controller, request DTO, and response VO."
+  short_description: "按批准 Slice/Web 合同生成 Controller、Wire DTO 与 Convertor"
+  default_prompt: "Use $yss-web-controller with an approved schema v2 Web generation contract, frozen OpenAPI, stable Application interfaces, and allowed write paths to generate YSS REST adapters atomically."

package/template/.qoder/skills/yss-web-controller/assets/templates/Controller.java.template

@@ -3,8 +3,8 @@ package ${base_package}.rest;
 ${application_service_import}
 ${dto_imports}
 ${web_convertor_import}
-import com.yss.cloud.dto.result.PageResult;
-import com.yss.cloud.dto.result.SingleResult;
+import ${page_result_type};
+import ${single_result_type};
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.*;
 import io.swagger.v3.oas.annotations.Operation;
@@ -30,7 +30,7 @@ public class ${domain_class}Controller {
      */
     @PostMapping("/page")
     @Operation(summary = "分页查询")
-    public PageResult<${response_class}> page(@Valid @RequestBody ${page_request_class} request) {
+    public ${page_result_simple_name}<${response_class}> page(@Valid @RequestBody ${page_request_class} request) {
         return webConvertor.toResponsePage(${query_call});
     }
 
@@ -39,8 +39,8 @@ public class ${domain_class}Controller {
      */
     @GetMapping("/{id}")
     @Operation(summary = "详情查询")
-    public SingleResult<${response_class}> detail(@PathVariable Long id) {
-        return SingleResult.of(webConvertor.toResponse(${detail_call}));
+    public ${single_result_simple_name}<${response_class}> detail(@PathVariable Long id) {
+        return ${single_result_simple_name}.${single_result_factory_method}(webConvertor.toResponse(${detail_call}));
     }
 
     /**
@@ -48,8 +48,8 @@ public class ${domain_class}Controller {
      */
     @PostMapping
     @Operation(summary = "新增")
-    public SingleResult<Long> add(@Valid @RequestBody ${create_request_class} request) {
-        return SingleResult.of(${add_call});
+    public ${single_result_simple_name}<Long> add(@Valid @RequestBody ${create_request_class} request) {
+        return ${single_result_simple_name}.${single_result_factory_method}(${add_call});
     }
 
     /**
@@ -57,8 +57,8 @@ public class ${domain_class}Controller {
      */
     @PutMapping
     @Operation(summary = "更新")
-    public SingleResult<Boolean> update(@Valid @RequestBody ${update_request_class} request) {
-        return SingleResult.of(${update_call});
+    public ${single_result_simple_name}<Boolean> update(@Valid @RequestBody ${update_request_class} request) {
+        return ${single_result_simple_name}.${single_result_factory_method}(${update_call});
     }
 
     /**
@@ -66,7 +66,7 @@ public class ${domain_class}Controller {
      */
     @DeleteMapping("/{id}")
     @Operation(summary = "删除")
-    public SingleResult<Boolean> delete(@PathVariable Long id) {
-        return SingleResult.of(${delete_call});
+    public ${single_result_simple_name}<Boolean> delete(@PathVariable Long id) {
+        return ${single_result_simple_name}.${single_result_factory_method}(${delete_call});
     }
 }

package/template/.qoder/skills/yss-web-controller/assets/templates/WebConvertor.java.template

@@ -1,6 +1,6 @@
 package ${base_package}.rest.convertor;
 
-import com.yss.cloud.dto.result.PageResult;
+import ${page_result_type};
 ${application_type_imports}
 import ${base_package}.rest.dto.request.${domain_class}CreateRequest;
 import ${base_package}.rest.dto.request.${domain_class}UpdateRequest;
@@ -22,12 +22,9 @@ public interface ${web_convertor_class} {
 
     List<${domain_class}Response> toResponses(List<${domain_class}Result> source);
 
-    default PageResult<${domain_class}Response> toResponsePage(PageResult<${domain_class}Result> source) {
-        return PageResult.of(
-                toResponses(source.getData()),
-                source.getTotalCount(),
-                source.getPageSize(),
-                source.getPageIndex()
+    default ${page_result_simple_name}<${domain_class}Response> toResponsePage(${page_result_simple_name}<${domain_class}Result> source) {
+        return ${page_result_simple_name}.${page_result_factory_method}(
+${page_result_factory_arguments}
         );
     }
 }

package/template/.qoder/skills/yss-web-controller/assets/templates/web/dto/CreateRequest.java.template

@@ -1,6 +1,6 @@
 package ${base_package}.rest.dto.request;
 
-import com.yss.cloud.dto.CommandDTO;
+import ${command_dto_type};
 import lombok.Getter;
 import lombok.Setter;
 import ${validation_namespace}.validation.constraints.NotBlank;
@@ -13,7 +13,7 @@ import java.time.LocalDate;
 /** ${domain_desc}新增请求。字段来自批准的 OpenAPI allowlist。 */
 @Getter
 @Setter
-public class ${domain_class}CreateRequest extends CommandDTO {
+public class ${domain_class}CreateRequest extends ${command_dto_simple_name} {
 
 ${field_declarations}
 }

package/template/.qoder/skills/yss-web-controller/assets/templates/web/dto/PageRequest.java.template

@@ -1,8 +1,9 @@
 package ${base_package}.rest.dto.request;
 
-import com.yss.cloud.dto.QueryDTO;
+import ${query_dto_type};
 import lombok.Getter;
 import lombok.Setter;
+import ${validation_namespace}.validation.constraints.Pattern;
 import java.util.Date;
 import java.math.BigDecimal;
 import java.time.LocalDateTime;
@@ -13,12 +14,8 @@ import java.time.LocalDate;
  */
 @Getter
 @Setter
-public class ${domain_class}PageRequest extends QueryDTO {
-    private int pageIndex = 1;
-    private int pageSize = 20;
-    private String orderBy;
-    private String orderDirection;
-    private String groupBy;
+public class ${domain_class}PageRequest extends ${query_dto_simple_name} {
+${pagination_field_declarations}
 
 ${field_declarations}
 }

package/template/.qoder/skills/yss-web-controller/assets/templates/web/dto/UpdateRequest.java.template

@@ -1,6 +1,6 @@
 package ${base_package}.rest.dto.request;
 
-import com.yss.cloud.dto.CommandDTO;
+import ${command_dto_type};
 import lombok.Getter;
 import lombok.Setter;
 import ${validation_namespace}.validation.constraints.NotBlank;
@@ -13,7 +13,7 @@ import java.time.LocalDate;
 /** ${domain_desc}更新请求。字段来自批准的 OpenAPI allowlist。 */
 @Getter
 @Setter
-public class ${domain_class}UpdateRequest extends CommandDTO {
+public class ${domain_class}UpdateRequest extends ${command_dto_simple_name} {
 
 ${field_declarations}
 }

package/template/.qoder/skills/yss-web-controller/references/web-adapter-layer-guide.md

@@ -20,7 +20,7 @@ DTO 固定属于 Web module。独立 client module 与把 client DTO 放进 Doma
 
 - Request/Response 字段必须来自冻结 OpenAPI 和批准 allowlist。
 - 数据库 metadata 只补充 Java 类型候选，不能自行扩大公开字段。
-- Web Page Request 不继承含内部协作字段的 `PageQuery`；只暴露批准的 `pageIndex/pageSize/orderBy/orderDirection/groupBy` 及业务查询字段。
+- Web Page Request 不继承含内部协作字段的 `PageQuery`；分页字段、默认值、枚举和禁用字段全部来自合同绑定且 digest 匹配的 `yss-dto` wire profile，再与 `fields.<table>.pagination` allowlist 取交集。Web Adapter 不维护第二份分页协议。
 - `orderBy` / `groupBy` 必须在 Application/Infrastructure 映射到数据库列白名单。
 - `offset`、`needTotalCount`、`tempTotalCount` 禁止进入 HTTP 绑定面。
 
@@ -70,9 +70,11 @@ public interface QualityRuleWebConvertor {
 
 ## 6. 生成门禁
 
-- `generate_controller.mjs` 必须消费 `status=approved` 的 Web generation contract。
-- 合同必须声明 `base_package`、`module_name`、`domain_segment`、`target-domain-model`、平台/validation Profile、`dto_placement=web`、OpenAPI Freeze 引用和每张表的 create/update/query/response allowlist；CLI 身份必须逐项匹配。
-- 生成器是 initialize-only，必须在写入前规划全部目标；任一文件已存在或传入 `--force` 时整体阻断，不允许“跳过已有文件后继续生成”的部分成功。
+- `generate_controller.mjs` 只消费 `schema_version=2`、`status=approved` 且 `current_version=contract_version` 的 Web generation contract；schema v1 为 `unsupported`。
+- `references/web-generation-contract.schema.json` 是 Web generation contract v2 的机器可读结构合同；生成器仍执行跨字段、文件系统与 Manifest 语义校验。
+- 合同必须声明 Slice `contract_id/contract_version/slice_id`、`integration_mode`、`implementation_project_root`、`allowed_write_paths`、预期证据、验证命令、`base_package`、`module_name`、`domain_segment`、Application Service package、`target-domain-model`、平台/validation Profile、`dto_placement=web`、`dto_wire_profile_ref/digest`、OpenAPI Freeze 引用和每张表的 create/update/query/pagination/response allowlist；CLI 身份必须逐项匹配。
+- `scaffold-v2` 模式必须绑定已达 `empty-scaffold-verified` 或 `first-slice-verified` 的 Manifest，并校验标准 Web module 路径和所有 Profile；`existing-project` 模式不得伪造 scaffold manifest。
+- 生成器是 initialize-only，必须在写入前规划全部目标并校验每个目标位于批准写路径；任一文件已存在或传入 `--force` 时整体阻断。落盘使用排他创建，任一步失败都回滚本次已创建文件，不允许部分成功。
 - 权限、校验语义、异常行为和复杂查询仍使用 `behavior-tdd`，不能由 metadata 猜测。
 
 ## 7. 验证

package/template/.qoder/skills/yss-web-controller/references/web-generation-contract.schema.json

@@ -0,0 +1,97 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://yss.local/schemas/web-generation-contract.schema.json",
+  "title": "YSS Web Generation Contract",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "contract_id",
+    "contract_version",
+    "current_version",
+    "slice_id",
+    "status",
+    "integration_mode",
+    "implementation_project_root",
+    "base_package",
+    "module_name",
+    "domain_segment",
+    "application_service_package",
+    "architecture_profile",
+    "platform_profile",
+    "validation_namespace",
+    "dto_placement",
+    "dto_wire_profile_ref",
+    "dto_wire_profile_digest",
+    "openapi_freeze_ref",
+    "allowed_write_paths",
+    "expected_evidence_files",
+    "verification_commands",
+    "fields"
+  ],
+  "properties": {
+    "schema_version": { "const": 2 },
+    "contract_id": { "$ref": "#/$defs/nonEmptyString" },
+    "contract_version": { "type": "integer", "minimum": 1 },
+    "current_version": { "type": "integer", "minimum": 1 },
+    "slice_id": { "$ref": "#/$defs/nonEmptyString" },
+    "status": { "const": "approved" },
+    "integration_mode": { "enum": ["existing-project", "scaffold-v2"] },
+    "implementation_project_root": { "$ref": "#/$defs/nonEmptyString" },
+    "scaffold_manifest_ref": { "$ref": "#/$defs/nonEmptyString" },
+    "base_package": { "$ref": "#/$defs/nonEmptyString" },
+    "module_name": { "$ref": "#/$defs/nonEmptyString" },
+    "domain_segment": { "$ref": "#/$defs/nonEmptyString" },
+    "application_service_package": { "$ref": "#/$defs/nonEmptyString" },
+    "architecture_profile": { "const": "target-domain-model" },
+    "platform_profile": { "enum": ["spring-boot-2.7-jdk8", "spring-boot-3-jdk17"] },
+    "validation_namespace": { "enum": ["javax", "jakarta"] },
+    "dto_placement": { "const": "web" },
+    "dto_wire_profile_ref": { "$ref": "#/$defs/nonEmptyString" },
+    "dto_wire_profile_digest": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "openapi_freeze_ref": { "$ref": "#/$defs/nonEmptyString" },
+    "allowed_write_paths": { "$ref": "#/$defs/nonEmptyStringArray" },
+    "expected_evidence_files": { "$ref": "#/$defs/nonEmptyStringArray" },
+    "verification_commands": { "$ref": "#/$defs/nonEmptyStringArray" },
+    "fields": {
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["create", "update", "query", "pagination", "response"],
+        "properties": {
+          "create": { "$ref": "#/$defs/stringArray" },
+          "update": { "$ref": "#/$defs/stringArray" },
+          "query": { "$ref": "#/$defs/stringArray" },
+          "pagination": {
+            "type": "array",
+            "uniqueItems": true,
+            "items": { "$ref": "#/$defs/nonEmptyString" }
+          },
+          "response": { "$ref": "#/$defs/stringArray" }
+        }
+      }
+    }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "integration_mode": { "const": "scaffold-v2" } } },
+      "then": { "required": ["scaffold_manifest_ref"] },
+      "else": { "not": { "required": ["scaffold_manifest_ref"] } }
+    },
+    {
+      "if": { "properties": { "platform_profile": { "const": "spring-boot-2.7-jdk8" } } },
+      "then": { "properties": { "validation_namespace": { "const": "javax" } } }
+    },
+    {
+      "if": { "properties": { "platform_profile": { "const": "spring-boot-3-jdk17" } } },
+      "then": { "properties": { "validation_namespace": { "const": "jakarta" } } }
+    }
+  ],
+  "$defs": {
+    "nonEmptyString": { "type": "string", "minLength": 1 },
+    "stringArray": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/$defs/nonEmptyString" } },
+    "nonEmptyStringArray": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/$defs/nonEmptyString" } }
+  }
+}