create-yss-spec 2.2.10 → 3.0.0

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

@@ -1,18 +1,22 @@
 #!/usr/bin/env node
-import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { constants, access, copyFile, mkdir, mkdtemp, readFile, rm, unlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
+import { parseDocument } from "../../../../scripts/vendor/yaml.mjs";
+
 const TYPE_MAPPING = { bigint: "Long", int: "Integer", integer: "Integer", smallint: "Integer", tinyint: "Integer", number: "Long", numeric: "BigDecimal", decimal: "BigDecimal", float: "Float", double: "Double", real: "Float", varchar: "String", varchar2: "String", nvarchar2: "String", char: "String", nchar: "String", text: "String", clob: "String", nclob: "String", date: "LocalDateTime", datetime: "LocalDateTime", timestamp: "LocalDateTime", "timestamp with time zone": "LocalDateTime", boolean: "Boolean", bool: "Boolean", bit: "Boolean", json: "String", jsonb: "String", uuid: "String" };
 const PLATFORM_VALIDATION_NAMESPACES = {
   "spring-boot-2.7-jdk8": "javax",
   "spring-boot-3-jdk17": "jakarta"
 };
-const required = ["metadata-file", "contract-file", "base-package", "module-name", "domain-segment"];
-const valued = new Set([...required, "output-dir", "web-project-dir", "web-output-dir", "author", "application-service-package", "validation-namespace"]);
+const required = ["metadata-file", "contract-file", "dto-wire-profile-file", "base-package", "module-name", "domain-segment"];
+const valued = new Set([...required, "output-dir", "web-project-dir", "web-output-dir", "author", "application-service-package", "validation-namespace", "scaffold-manifest-file"]);
 
 function usage() {
-  return "Usage: node generate_controller.mjs --metadata-file FILE --contract-file FILE --base-package PACKAGE --module-name NAME --domain-segment SEGMENT [--output-dir DIR] [--web-project-dir DIR] [--web-output-dir DIR] [--author NAME] [--application-service-package PACKAGE] [--validation-namespace javax|jakarta]";
+  return "Usage: node generate_controller.mjs --metadata-file FILE --contract-file FILE --dto-wire-profile-file FILE --base-package PACKAGE --module-name NAME --domain-segment SEGMENT [--output-dir DIR] [--web-project-dir DIR] [--web-output-dir DIR] [--scaffold-manifest-file FILE] [--author NAME] [--application-service-package PACKAGE] [--validation-namespace javax|jakarta]";
 }
 export function parseArgs(argv) {
   const args = { "output-dir": "./output", author: "System", "validation-namespace": "javax", force: false };
@@ -51,6 +55,114 @@ function fields(columns, selected, { command = false } = {}) {
 }
 function render(template, context) { return template.replace(/\$(?:\{([A-Za-z_][A-Za-z0-9_]*)\}|([A-Za-z_][A-Za-z0-9_]*))/g, (_, braced, plain) => { const key = braced || plain; if (!(key in context)) throw new Error(`missing template field: ${key}`); return context[key]; }); }
 async function exists(target) { try { await access(target); return true; } catch { return false; } }
+const present = (value) => value !== undefined && value !== null && value !== "";
+function within(root, target) {
+  const relative = path.relative(path.resolve(root), path.resolve(target));
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+function simpleJavaName(javaType) {
+  return javaType.replace(/<.*$/, "").split(".").at(-1);
+}
+function paginationFields(selected, dtoProfile) {
+  const definitions = dtoProfile.page_query.fields;
+  const unique = [...new Set(selected)];
+  const unsupported = unique.filter((name) => !(name in definitions) || dtoProfile.page_query.forbidden_client_fields.includes(name));
+  if (unsupported.length) throw new Error(`unsupported pagination fields: ${unsupported.join(", ")}`);
+  return unique.map((name) => {
+    const definition = definitions[name];
+    const wireType = definition.wire_types.find((item) => item !== "null");
+    const javaType = wireType === "integer" ? (definition.nullable ? "Integer" : "int") : wireType === "string" ? "String" : null;
+    if (!javaType) throw new Error(`unsupported yss-dto pagination wire type for ${name}: ${definition.wire_types.join(", ")}`);
+    const annotation = definition.enum?.length
+      ? `    @Pattern(regexp = "${definition.enum.join("|")}", message = "${name} must be one of ${definition.enum.join(", ")}")\n`
+      : "";
+    const initializer = definition.default === undefined ? "" : ` = ${typeof definition.default === "string" ? JSON.stringify(definition.default) : definition.default}`;
+    return `${annotation}    private ${javaType} ${name}${initializer};`;
+  }).join("\n");
+}
+
+async function loadDtoWireProfile(contract, args) {
+  const profilePath = path.resolve(args["dto-wire-profile-file"]);
+  if (profilePath !== path.resolve(contract.dto_wire_profile_ref ?? "")) throw new Error("--dto-wire-profile-file does not match the approved Web generation contract");
+  if (!await exists(profilePath)) throw new Error(`yss-dto wire profile not found: ${profilePath}`);
+  const source = await readFile(profilePath);
+  const digest = createHash("sha256").update(source).digest("hex");
+  if (digest !== contract.dto_wire_profile_digest) throw new Error("yss-dto wire profile digest does not match the approved Web generation contract");
+  const document = parseDocument(source.toString("utf8"), { maxAliasCount: 0, uniqueKeys: true });
+  if (document.errors.length) throw new Error(`invalid yss-dto wire profile: ${document.errors[0].message}`);
+  const profile = document.toJS({ maxAliasCount: 0 });
+  if (profile?.schema_version !== 1 || profile?.kind !== "yss-dto-openapi-wire-profile") throw new Error("unsupported yss-dto wire profile");
+  const resultPackage = profile.canonical?.java_package;
+  const pageResult = profile.wrappers?.PageResult;
+  const singleResult = profile.wrappers?.SingleResult;
+  const commandDtoType = profile.request_bases?.command?.java_type;
+  const queryDtoType = profile.request_bases?.query?.java_type;
+  if (![resultPackage, pageResult?.java_type, singleResult?.java_type, commandDtoType, queryDtoType].every(present)) throw new Error("incomplete yss-dto wire profile type mapping");
+  if (![pageResult.java_type, singleResult.java_type].every((type) => type.startsWith(`${resultPackage}.`))) throw new Error("yss-dto result wrapper package is inconsistent");
+  if (!profile.page_query?.fields || !Array.isArray(profile.page_query?.forbidden_client_fields)) throw new Error("incomplete yss-dto page_query mapping");
+  const factory = pageResult.java_factory;
+  const singleFactory = singleResult.java_factory;
+  const javaIdentifier = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+  if (!javaIdentifier.test(factory?.method ?? "") || !Array.isArray(factory.arguments) || !factory.arguments.length) throw new Error("incomplete yss-dto PageResult factory mapping");
+  if (!javaIdentifier.test(singleFactory?.method ?? "") || JSON.stringify(singleFactory.arguments) !== JSON.stringify(["data"])) throw new Error("incomplete yss-dto SingleResult factory mapping");
+  const expressionByArgument = { data: "toResponses(source.getData())", totalCount: "source.getTotalCount()", pageSize: "source.getPageSize()", pageIndex: "source.getPageIndex()" };
+  const unsupportedArguments = factory.arguments.filter((name) => !(name in expressionByArgument));
+  if (unsupportedArguments.length) throw new Error(`unsupported yss-dto PageResult factory arguments: ${unsupportedArguments.join(", ")}`);
+  return {
+    profile,
+    resultPackage,
+    pageResultType: pageResult.java_type.replace(/<.*$/, ""),
+    singleResultType: singleResult.java_type.replace(/<.*$/, ""),
+    pageResultFactoryMethod: factory.method,
+    singleResultFactoryMethod: singleFactory.method,
+    commandDtoType,
+    queryDtoType,
+    pageResultFactoryArguments: factory.arguments.map((name, index) => `                ${expressionByArgument[name]}${index < factory.arguments.length - 1 ? "," : ""}`).join("\n")
+  };
+}
+
+async function validateContract(contract, args) {
+  if (contract.schema_version !== 2) throw new Error(`web generation contract schema_version=${contract.schema_version} is unsupported; only schema_version=2 is accepted`);
+  if (contract.status !== "approved") throw new Error("web generation contract must be approved");
+  const requiredFields = ["contract_id", "contract_version", "current_version", "slice_id", "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", "fields", "allowed_write_paths", "expected_evidence_files", "verification_commands"];
+  const missing = requiredFields.filter((name) => !present(contract[name]));
+  if (missing.length) throw new Error(`approved web generation contract is incomplete: ${missing.join(", ")}`);
+  if (contract.current_version !== contract.contract_version) throw new Error("web generation contract is not the current approved version");
+  if (!Number.isInteger(contract.contract_version) || contract.contract_version < 1) throw new Error("web generation contract_version must be a positive integer");
+  if (!["existing-project", "scaffold-v2"].includes(contract.integration_mode)) throw new Error("unsupported web generation integration_mode");
+  if (!["allowed_write_paths", "expected_evidence_files", "verification_commands"].every((name) => Array.isArray(contract[name]) && contract[name].length)) throw new Error("web generation contract requires non-empty allowed_write_paths, expected_evidence_files, and verification_commands");
+  if (contract.architecture_profile !== "target-domain-model" || contract.dto_placement !== "web") throw new Error("web generation only supports target-domain-model with dto_placement=web");
+  if (contract.base_package !== args["base-package"] || contract.module_name !== args["module-name"] || contract.domain_segment !== args["domain-segment"]) throw new Error("CLI generation identity does not match the approved web generation contract");
+  const applicationPackage = args["application-service-package"] || `${args["base-package"]}.application.service`;
+  if (contract.application_service_package !== applicationPackage) throw new Error("--application-service-package does not match the approved web generation contract");
+  if (!(contract.platform_profile in PLATFORM_VALIDATION_NAMESPACES)) throw new Error("unsupported platform_profile in approved web generation contract");
+  if (PLATFORM_VALIDATION_NAMESPACES[contract.platform_profile] !== contract.validation_namespace) throw new Error("platform_profile and validation_namespace are inconsistent");
+  if (contract.validation_namespace !== args["validation-namespace"]) throw new Error("--validation-namespace must match the approved web generation contract");
+
+  const implementationRoot = path.resolve(contract.implementation_project_root);
+  if (contract.integration_mode === "existing-project") {
+    if (args["scaffold-manifest-file"] || present(contract.scaffold_manifest_ref)) throw new Error("existing-project Web generation must not claim a scaffold manifest");
+    return { applicationPackage, implementationRoot };
+  }
+
+  if (!args["scaffold-manifest-file"] || !present(contract.scaffold_manifest_ref)) throw new Error("scaffold-v2 Web generation requires --scaffold-manifest-file and scaffold_manifest_ref");
+  const manifestPath = path.resolve(args["scaffold-manifest-file"]);
+  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 (manifest.schema_version !== 2) throw new Error("scaffold manifest must use schema_version=2");
+  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");
+  const expectedWebProject = path.join(scaffoldRoot, `${manifest.project_name}-adapter`, `${manifest.project_name}-web`);
+  if (!args["web-project-dir"] || path.resolve(args["web-project-dir"]) !== expectedWebProject) throw new Error("--web-project-dir does not match the scaffold manifest project layout");
+  const profilePairs = [["architecture", "architecture_profile"], ["platform", "platform_profile"], ["validation_namespace", "validation_namespace"], ["dto_placement", "dto_placement"]];
+  for (const [manifestField, contractField] of profilePairs) {
+    if (manifest.profiles?.[manifestField] !== contract[contractField]) throw new Error(`scaffold manifest ${manifestField} profile does not match the approved Web contract`);
+  }
+  if (manifest.base_package !== contract.base_package) throw new Error("scaffold manifest base_package does not match the approved Web contract");
+  return { applicationPackage, implementationRoot };
+}
 
 export async function generate(args, logger = console) {
   if (!await exists(args["metadata-file"])) throw new Error(`Metadata file not found: ${args["metadata-file"]}`);
@@ -59,14 +171,8 @@ export async function generate(args, logger = console) {
   try { metadata = JSON.parse(await readFile(args["metadata-file"], "utf8")); } catch (error) { throw new Error(`Error reading metadata file: ${error.message}`); }
   let contract;
   try { contract = JSON.parse(await readFile(args["contract-file"], "utf8")); } catch (error) { throw new Error(`Error reading contract file: ${error.message}`); }
-  if (contract.schema_version !== 1 || contract.status !== "approved") throw new Error("web generation contract must be schema_version=1 and approved");
-  if (contract.architecture_profile !== "target-domain-model" || contract.dto_placement !== "web") throw new Error("web generation only supports target-domain-model with dto_placement=web");
-  if (!contract.openapi_freeze_ref || !contract.fields || typeof contract.fields !== "object") throw new Error("approved web generation contract requires openapi_freeze_ref and fields");
-  if (!contract.base_package || !contract.module_name || !contract.domain_segment) throw new Error("approved web generation contract requires base_package, module_name, and domain_segment");
-  if (contract.base_package !== args["base-package"] || contract.module_name !== args["module-name"] || contract.domain_segment !== args["domain-segment"]) throw new Error("CLI generation identity does not match the approved web generation contract");
-  if (!(contract.platform_profile in PLATFORM_VALIDATION_NAMESPACES)) throw new Error("unsupported platform_profile in approved web generation contract");
-  if (PLATFORM_VALIDATION_NAMESPACES[contract.platform_profile] !== contract.validation_namespace) throw new Error("platform_profile and validation_namespace are inconsistent");
-  if (contract.validation_namespace !== args["validation-namespace"]) throw new Error("--validation-namespace must match the approved web generation contract");
+  const { applicationPackage, implementationRoot } = await validateContract(contract, args);
+  const dto = await loadDtoWireProfile(contract, args);
   const tables = metadata.tables || [];
   if (!tables.length) { logger.warn("Warning: No tables found in metadata."); return []; }
   const scriptDir = path.dirname(fileURLToPath(import.meta.url));
@@ -82,22 +188,37 @@ export async function generate(args, logger = console) {
   for (const table of tables) {
     const domainClass = pascal(table.table_name); const domainVar = lowerCamel(table.table_name); const domainDesc = String(table.table_comment || domainClass).trim().replaceAll("\n", " ");
     const approvedFields = contract.fields[table.table_name];
-    if (!approvedFields || ["create", "update", "query", "response"].some((name) => !Array.isArray(approvedFields[name]))) throw new Error(`approved web field contract is missing for table: ${table.table_name}`);
-    const applicationPackage = args["application-service-package"] || `${args["base-package"]}.application.service`;
-    const context = { base_package: args["base-package"], module_name: args["module-name"], domain_class: domainClass, domain_var: domainVar, domain_desc: domainDesc, domain_url_path: kebab(table.table_name), domain_pkg_name: args["domain-segment"], author: args.author, dto_imports: [`import ${args["base-package"]}.rest.dto.request.${domainClass}CreateRequest;`, `import ${args["base-package"]}.rest.dto.request.${domainClass}UpdateRequest;`, `import ${args["base-package"]}.rest.dto.request.${domainClass}PageRequest;`, `import ${args["base-package"]}.rest.dto.response.${domainClass}Response;`].join("\n"), application_type_imports: [`import ${args["base-package"]}.application.command.${domainClass}CreateCommand;`, `import ${args["base-package"]}.application.command.${domainClass}UpdateCommand;`, `import ${args["base-package"]}.application.query.${domainClass}PageQuery;`, `import ${args["base-package"]}.application.result.${domainClass}Result;`].join("\n"), application_service_import: `import ${applicationPackage}.${domainClass}Service;`, web_convertor_import: `import ${args["base-package"]}.rest.convertor.${domainClass}WebConvertor;`, web_convertor_class: `${domainClass}WebConvertor`, application_service_field: `private final ${domainClass}Service ${domainVar}Service;`, query_call: `${domainVar}Service.page(webConvertor.toPageQuery(request))`, detail_call: `${domainVar}Service.detail(id)`, add_call: `${domainVar}Service.add(webConvertor.toCreateCommand(request))`, update_call: `${domainVar}Service.update(webConvertor.toUpdateCommand(request))`, delete_call: `${domainVar}Service.delete(id)`, response_class: `${domainClass}Response`, create_request_class: `${domainClass}CreateRequest`, update_request_class: `${domainClass}UpdateRequest`, page_request_class: `${domainClass}PageRequest`, validation_namespace: args["validation-namespace"] };
+    if (!approvedFields || ["create", "update", "query", "pagination", "response"].some((name) => !Array.isArray(approvedFields[name]))) throw new Error(`approved web field contract is missing create/update/query/pagination/response allowlists for table: ${table.table_name}`);
+    const context = { base_package: args["base-package"], module_name: args["module-name"], domain_class: domainClass, domain_var: domainVar, domain_desc: domainDesc, domain_url_path: kebab(table.table_name), domain_pkg_name: args["domain-segment"], author: args.author, dto_imports: [`import ${args["base-package"]}.rest.dto.request.${domainClass}CreateRequest;`, `import ${args["base-package"]}.rest.dto.request.${domainClass}UpdateRequest;`, `import ${args["base-package"]}.rest.dto.request.${domainClass}PageRequest;`, `import ${args["base-package"]}.rest.dto.response.${domainClass}Response;`].join("\n"), application_type_imports: [`import ${args["base-package"]}.application.command.${domainClass}CreateCommand;`, `import ${args["base-package"]}.application.command.${domainClass}UpdateCommand;`, `import ${args["base-package"]}.application.query.${domainClass}PageQuery;`, `import ${args["base-package"]}.application.result.${domainClass}Result;`].join("\n"), application_service_import: `import ${applicationPackage}.${domainClass}Service;`, web_convertor_import: `import ${args["base-package"]}.rest.convertor.${domainClass}WebConvertor;`, web_convertor_class: `${domainClass}WebConvertor`, application_service_field: `private final ${domainClass}Service ${domainVar}Service;`, query_call: `${domainVar}Service.page(webConvertor.toPageQuery(request))`, detail_call: `${domainVar}Service.detail(id)`, add_call: `${domainVar}Service.add(webConvertor.toCreateCommand(request))`, update_call: `${domainVar}Service.update(webConvertor.toUpdateCommand(request))`, delete_call: `${domainVar}Service.delete(id)`, response_class: `${domainClass}Response`, create_request_class: `${domainClass}CreateRequest`, update_request_class: `${domainClass}UpdateRequest`, page_request_class: `${domainClass}PageRequest`, validation_namespace: args["validation-namespace"], result_package: dto.resultPackage, page_result_type: dto.pageResultType, page_result_simple_name: simpleJavaName(dto.pageResultType), page_result_factory_method: dto.pageResultFactoryMethod, single_result_type: dto.singleResultType, single_result_simple_name: simpleJavaName(dto.singleResultType), single_result_factory_method: dto.singleResultFactoryMethod, command_dto_type: dto.commandDtoType, command_dto_simple_name: simpleJavaName(dto.commandDtoType), query_dto_type: dto.queryDtoType, query_dto_simple_name: simpleJavaName(dto.queryDtoType), page_result_factory_arguments: dto.pageResultFactoryArguments };
     plan(path.join(webRoot, `${domainClass}Controller.java`), render(templates["Controller.java.template"], context));
     plan(path.join(webRoot, "convertor", `${domainClass}WebConvertor.java`), render(templates["WebConvertor.java.template"], context));
-    for (const [templateName, target, declaration] of [["web/dto/Response.java.template", path.join(webRoot, "dto", "response", `${domainClass}Response.java`), fields(table.columns || [], approvedFields.response)], ["web/dto/CreateRequest.java.template", path.join(webRoot, "dto", "request", `${domainClass}CreateRequest.java`), fields(table.columns || [], approvedFields.create, { command: true })], ["web/dto/UpdateRequest.java.template", path.join(webRoot, "dto", "request", `${domainClass}UpdateRequest.java`), fields(table.columns || [], approvedFields.update, { command: true })], ["web/dto/PageRequest.java.template", path.join(webRoot, "dto", "request", `${domainClass}PageRequest.java`), fields(table.columns || [], approvedFields.query)]]) plan(target, render(templates[templateName], { ...context, field_declarations: declaration }));
+    for (const [templateName, target, declaration] of [["web/dto/Response.java.template", path.join(webRoot, "dto", "response", `${domainClass}Response.java`), fields(table.columns || [], approvedFields.response)], ["web/dto/CreateRequest.java.template", path.join(webRoot, "dto", "request", `${domainClass}CreateRequest.java`), fields(table.columns || [], approvedFields.create, { command: true })], ["web/dto/UpdateRequest.java.template", path.join(webRoot, "dto", "request", `${domainClass}UpdateRequest.java`), fields(table.columns || [], approvedFields.update, { command: true })], ["web/dto/PageRequest.java.template", path.join(webRoot, "dto", "request", `${domainClass}PageRequest.java`), fields(table.columns || [], approvedFields.query)]]) plan(target, render(templates[templateName], { ...context, field_declarations: declaration, pagination_field_declarations: paginationFields(approvedFields.pagination, dto.profile) }));
   }
   const targets = planned.map(({ target }) => target);
   if (new Set(targets).size !== targets.length) throw new Error("approved metadata produces duplicate target files");
   const existing = [];
   for (const target of targets) if (await exists(target)) existing.push(target);
   if (existing.length) throw new Error(`initialize-only Web generation refuses existing targets: ${existing.join(", ")}`);
-  for (const { target, contents } of planned) {
-    await mkdir(path.dirname(target), { recursive: true });
-    await writeFile(target, contents, "utf8");
-    logger.log(`Generated: ${target}`);
+  const allowedRoots = contract.allowed_write_paths.map((item) => path.resolve(implementationRoot, String(item)));
+  const outside = targets.filter((target) => !allowedRoots.some((root) => within(root, target)));
+  if (outside.length) throw new Error(`planned Web targets are outside allowed_write_paths: ${outside.join(", ")}`);
+  const staging = await mkdtemp(path.join(tmpdir(), "yss-web-generation-"));
+  const created = [];
+  try {
+    for (const [index, { contents }] of planned.entries()) await writeFile(path.join(staging, String(index)), contents, "utf8");
+    for (const [index, { target }] of planned.entries()) {
+      await mkdir(path.dirname(target), { recursive: true });
+      await copyFile(path.join(staging, String(index)), target, constants.COPYFILE_EXCL);
+      created.push(target);
+      logger.log(`Generated: ${target}`);
+    }
+  } catch (error) {
+    for (const target of created.reverse()) {
+      try { await unlink(target); } catch (cleanupError) { if (cleanupError.code !== "ENOENT") error.cleanupError = cleanupError.message; }
+    }
+    throw error;
+  } finally {
+    await rm(staging, { recursive: true, force: true });
   }
   return targets;
 }

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

@@ -1,60 +1,156 @@
 import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
 import { mkdir, mkdtemp, readFile, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import test from "node:test";
+import { fileURLToPath } from "node:url";
 import { generate, parseArgs } from "./generate_controller.mjs";
 
-test("generates application-service controller with requested validation profile", async () => {
+const scripts = path.dirname(fileURLToPath(import.meta.url));
+const dtoWireProfileFile = path.resolve(scripts, "../../yss-dto/references/openapi-wire-profile.yaml");
+const dtoWireProfileDigest = createHash("sha256").update(await readFile(dtoWireProfileFile)).digest("hex");
+
+const metadataValue = {
+  tables: [{
+    table_name: "quality_rule",
+    table_comment: "质量规则",
+    columns: [
+      { name: "id", sql_type: "bigint", primary: true, nullable: false },
+      { name: "rule_name", sql_type: "varchar(64)", nullable: false }
+    ]
+  }]
+};
+
+function webContract(root, overrides = {}) {
+  return {
+    schema_version: 2,
+    contract_id: "slice-quality-web-1",
+    contract_version: 1,
+    current_version: 1,
+    slice_id: "quality-rule-create",
+    status: "approved",
+    integration_mode: "existing-project",
+    implementation_project_root: root,
+    base_package: "com.yss.demo",
+    module_name: "demo",
+    domain_segment: "quality",
+    application_service_package: "com.yss.demo.application.service",
+    architecture_profile: "target-domain-model",
+    platform_profile: "spring-boot-3-jdk17",
+    validation_namespace: "jakarta",
+    dto_placement: "web",
+    dto_wire_profile_ref: dtoWireProfileFile,
+    dto_wire_profile_digest: dtoWireProfileDigest,
+    openapi_freeze_ref: "openapi://quality-rule@1",
+    allowed_write_paths: [root],
+    expected_evidence_files: ["evidence/web-generation.json"],
+    verification_commands: ["./mvnw test", "./mvnw package"],
+    fields: {
+      quality_rule: {
+        create: ["rule_name"],
+        update: ["id", "rule_name"],
+        query: ["rule_name"],
+        pagination: ["pageIndex", "pageSize"],
+        response: ["id", "rule_name"]
+      }
+    },
+    ...overrides
+  };
+}
+
+async function fixture(overrides = {}) {
   const root = await mkdtemp(path.join(tmpdir(), "yss-controller-"));
   const metadata = path.join(root, "metadata.json");
   const contract = path.join(root, "web-contract.json");
-  await writeFile(metadata, JSON.stringify({ tables: [{ table_name: "quality_rule", table_comment: "质量规则", columns: [{ name: "id", sql_type: "bigint", primary: true, nullable: false }, { name: "rule_name", sql_type: "varchar(64)", nullable: false }] }] }));
-  await writeFile(contract, JSON.stringify({ schema_version: 1, status: "approved", base_package: "com.yss.demo", module_name: "demo", domain_segment: "quality", architecture_profile: "target-domain-model", platform_profile: "spring-boot-3-jdk17", validation_namespace: "jakarta", dto_placement: "web", openapi_freeze_ref: "openapi://quality-rule@1", fields: { quality_rule: { create: ["rule_name"], update: ["id", "rule_name"], query: ["rule_name"], response: ["id", "rule_name"] } } }));
-  await generate(parseArgs(["--metadata-file", metadata, "--contract-file", contract, "--base-package", "com.yss.demo", "--module-name", "demo", "--domain-segment", "quality", "--output-dir", path.join(root, "out"), "--application-service-package", "com.yss.demo.application.service", "--validation-namespace", "jakarta"]), { log() {}, warn() {} });
-  const controller = await readFile(path.join(root, "out", "com", "yss", "demo", "rest", "QualityRuleController.java"), "utf8");
-  const convertor = await readFile(path.join(root, "out", "com", "yss", "demo", "rest", "convertor", "QualityRuleWebConvertor.java"), "utf8");
-  const createRequest = await readFile(path.join(root, "out", "com", "yss", "demo", "rest", "dto", "request", "QualityRuleCreateRequest.java"), "utf8");
+  const output = path.join(root, "out");
+  await writeFile(metadata, JSON.stringify(metadataValue));
+  await writeFile(contract, JSON.stringify(webContract(root, overrides)));
+  const args = ["--metadata-file", metadata, "--contract-file", contract, "--dto-wire-profile-file", dtoWireProfileFile, "--base-package", "com.yss.demo", "--module-name", "demo", "--domain-segment", "quality", "--output-dir", output, "--application-service-package", "com.yss.demo.application.service", "--validation-namespace", overrides.validation_namespace ?? "jakarta"];
+  return { root, metadata, contract, output, args };
+}
+
+test("generates approved standalone Web code and exposes only approved pagination fields", async () => {
+  const data = await fixture();
+  await generate(parseArgs(data.args), { log() {}, warn() {} });
+  const rest = path.join(data.output, "com", "yss", "demo", "rest");
+  const controller = await readFile(path.join(rest, "QualityRuleController.java"), "utf8");
+  const convertor = await readFile(path.join(rest, "convertor", "QualityRuleWebConvertor.java"), "utf8");
+  const createRequest = await readFile(path.join(rest, "dto", "request", "QualityRuleCreateRequest.java"), "utf8");
+  const pageRequest = await readFile(path.join(rest, "dto", "request", "QualityRulePageRequest.java"), "utf8");
   assert.match(controller, /import com\.yss\.demo\.application\.service\.QualityRuleService;/);
+  assert.match(controller, /SingleResult\.of\(/);
   assert.match(controller, /import jakarta\.validation\.Valid;/);
-  assert.match(controller, /webConvertor\.toCreateCommand\(request\)/);
   assert.match(convertor, /@Mapper\(componentModel = "spring"\)/);
-  assert.match(convertor, /application\.command\.QualityRuleCreateCommand/);
-  assert.match(convertor, /application\.result\.QualityRuleResult/);
+  assert.match(convertor, /PageResult\.of\(\s*toResponses\(source\.getData\(\)\),\s*source\.getTotalCount\(\),\s*source\.getPageSize\(\),\s*source\.getPageIndex\(\)/s);
   assert.doesNotMatch(`${controller}\n${convertor}`, /Gateway|\.domain\.|Mappers\.getMapper|INSTANCE/);
   assert.match(createRequest, /private String ruleName;/);
   assert.doesNotMatch(createRequest, /private Long id;|@Data/);
+  assert.match(pageRequest, /private int pageIndex = 1;/);
+  assert.match(pageRequest, /private int pageSize = 10;/);
+  assert.doesNotMatch(pageRequest, /orderBy|orderDirection|groupBy|offset|needTotalCount|tempTotalCount|extends PageQuery/);
 });
 
-test("rejects missing required CLI arguments", () => assert.throws(() => parseArgs(["--module-name", "demo"]), /required/));
+test("rejects a yss-dto wire profile whose digest differs from the approved contract", async () => {
+  const data = await fixture({ dto_wire_profile_digest: "0".repeat(64) });
+  await assert.rejects(() => generate(parseArgs(data.args), { log() {}, warn() {} }), /yss-dto wire profile digest/);
+});
 
-test("requires an approved target-profile field contract and refuses force overwrite", async () => {
-  const root = await mkdtemp(path.join(tmpdir(), "yss-controller-contract-"));
-  const metadata = path.join(root, "metadata.json");
-  const contract = path.join(root, "web-contract.json");
-  await writeFile(metadata, JSON.stringify({ tables: [{ table_name: "quality_rule", columns: [{ name: "id", sql_type: "bigint", primary: true, nullable: false }] }] }));
-  await writeFile(contract, JSON.stringify({ schema_version: 1, status: "draft", base_package: "com.yss.demo", module_name: "demo", domain_segment: "quality", architecture_profile: "target-domain-model", platform_profile: "spring-boot-2.7-jdk8", validation_namespace: "javax", dto_placement: "web", openapi_freeze_ref: "openapi://quality-rule@1", fields: { quality_rule: { create: [], update: ["id"], query: [], response: ["id"] } } }));
-  const base = ["--metadata-file", metadata, "--contract-file", contract, "--base-package", "com.yss.demo", "--module-name", "demo", "--domain-segment", "quality", "--output-dir", path.join(root, "out")];
-  await assert.rejects(() => generate(parseArgs(base), { log() {}, warn() {} }), /approved/);
-  await writeFile(contract, JSON.stringify({ schema_version: 1, status: "approved", base_package: "com.yss.demo", module_name: "demo", domain_segment: "quality", architecture_profile: "target-domain-model", platform_profile: "spring-boot-2.7-jdk8", validation_namespace: "javax", dto_placement: "web", openapi_freeze_ref: "openapi://quality-rule@1", fields: { quality_rule: { create: [], update: ["id"], query: [], response: ["id"] } } }));
-  await writeFile(contract, JSON.stringify({ schema_version: 1, status: "approved", base_package: "com.yss.demo", module_name: "demo", domain_segment: "quality", architecture_profile: "target-domain-model", platform_profile: "spring-boot-3-jdk17", validation_namespace: "javax", dto_placement: "web", openapi_freeze_ref: "openapi://quality-rule@1", fields: { quality_rule: { create: [], update: ["id"], query: [], response: ["id"] } } }));
-  await assert.rejects(() => generate(parseArgs(base), { log() {}, warn() {} }), /platform_profile and validation_namespace/);
-  assert.throws(() => parseArgs([...base, "--force"]), /initialize-only/);
+test("rejects missing CLI arguments, schema v1, draft contracts, and inconsistent platform profiles", async () => {
+  assert.throws(() => parseArgs(["--module-name", "demo"]), /required/);
+  const v1 = await fixture({ schema_version: 1 });
+  await assert.rejects(() => generate(parseArgs(v1.args), { log() {}, warn() {} }), /schema_version=1.*unsupported/);
+  const draft = await fixture({ status: "draft" });
+  await assert.rejects(() => generate(parseArgs(draft.args), { log() {}, warn() {} }), /approved/);
+  const mismatch = await fixture({ platform_profile: "spring-boot-3-jdk17", validation_namespace: "javax" });
+  await assert.rejects(() => generate(parseArgs(mismatch.args), { log() {}, warn() {} }), /platform_profile and validation_namespace/);
+  assert.throws(() => parseArgs([...draft.args, "--force"]), /initialize-only/);
 });
 
-test("binds generation identity to the approved contract and fails before writing when any target exists", async () => {
-  const root = await mkdtemp(path.join(tmpdir(), "yss-controller-initialize-only-"));
-  const metadata = path.join(root, "metadata.json");
-  const contract = path.join(root, "web-contract.json");
-  const output = path.join(root, "out");
-  await writeFile(metadata, JSON.stringify({ tables: [{ table_name: "quality_rule", columns: [{ name: "id", sql_type: "bigint", nullable: false }] }] }));
-  await writeFile(contract, JSON.stringify({ schema_version: 1, status: "approved", base_package: "com.yss.demo", module_name: "demo", domain_segment: "quality", architecture_profile: "target-domain-model", platform_profile: "spring-boot-2.7-jdk8", validation_namespace: "javax", dto_placement: "web", openapi_freeze_ref: "openapi://quality-rule@1", fields: { quality_rule: { create: [], update: ["id"], query: [], response: ["id"] } } }));
-  const args = ["--metadata-file", metadata, "--contract-file", contract, "--base-package", "com.yss.demo", "--module-name", "demo", "--domain-segment", "quality", "--output-dir", output];
-  await assert.rejects(() => generate(parseArgs(args.map((value) => value === "demo" ? "other" : value)), { log() {}, warn() {} }), /approved web generation contract/);
-  const existing = path.join(output, "com/yss/demo/rest/QualityRuleController.java");
+test("binds identity and every target to the approved write scope before writing", async () => {
+  const data = await fixture();
+  await assert.rejects(() => generate(parseArgs(data.args.map((value) => value === "demo" ? "other" : value)), { log() {}, warn() {} }), /approved web generation contract/);
+  await writeFile(data.contract, JSON.stringify(webContract(data.root, { allowed_write_paths: [path.join(data.root, "different-root")] })));
+  await assert.rejects(() => generate(parseArgs(data.args), { log() {}, warn() {} }), /allowed_write_paths/);
+  await writeFile(data.contract, JSON.stringify(webContract(data.root)));
+  const existing = path.join(data.output, "com/yss/demo/rest/QualityRuleController.java");
   await mkdir(path.dirname(existing), { recursive: true });
   await writeFile(existing, "user-owned\n");
-  await assert.rejects(() => generate(parseArgs(args), { log() {}, warn() {} }), /initialize-only/);
+  await assert.rejects(() => generate(parseArgs(data.args), { log() {}, warn() {} }), /initialize-only/);
   assert.equal(await readFile(existing, "utf8"), "user-owned\n");
-  await assert.rejects(() => readFile(path.join(output, "com/yss/demo/rest/convertor/QualityRuleWebConvertor.java"), "utf8"), /ENOENT/);
+  await assert.rejects(() => readFile(path.join(data.output, "com/yss/demo/rest/convertor/QualityRuleWebConvertor.java"), "utf8"), /ENOENT/);
+});
+
+test("scaffold-v2 mode requires an empty-scaffold-verified manifest with matching profile and project layout", async () => {
+  const data = await fixture({ platform_profile: "spring-boot-2.7-jdk8", validation_namespace: "javax" });
+  const projectRoot = path.join(data.root, "demo-service");
+  const webProject = path.join(projectRoot, "demo-service-adapter", "demo-service-web");
+  const manifest = path.join(projectRoot, ".yss", "scaffold-generation.json");
+  await mkdir(path.dirname(manifest), { recursive: true });
+  await writeFile(manifest, JSON.stringify({ schema_version: 2, project_name: "demo-service", base_package: "com.yss.demo", completion_level: "empty-scaffold-verified", profiles: { architecture: "target-domain-model", platform: "spring-boot-2.7-jdk8", validation_namespace: "javax", dto_placement: "web" } }));
+  const contractValue = webContract(projectRoot, {
+    integration_mode: "scaffold-v2",
+    implementation_project_root: projectRoot,
+    scaffold_manifest_ref: manifest,
+    platform_profile: "spring-boot-3-jdk17",
+    validation_namespace: "jakarta",
+    allowed_write_paths: [path.join(webProject, "src/main/java/com/yss/demo/rest")]
+  });
+  await writeFile(data.contract, JSON.stringify(contractValue));
+  const args = ["--metadata-file", data.metadata, "--contract-file", data.contract, "--dto-wire-profile-file", dtoWireProfileFile, "--scaffold-manifest-file", manifest, "--base-package", "com.yss.demo", "--module-name", "demo", "--domain-segment", "quality", "--web-project-dir", webProject, "--application-service-package", "com.yss.demo.application.service", "--validation-namespace", "jakarta"];
+  await assert.rejects(() => generate(parseArgs(args), { log() {}, warn() {} }), /scaffold manifest.*platform/i);
+  contractValue.platform_profile = "spring-boot-2.7-jdk8";
+  contractValue.validation_namespace = "javax";
+  await writeFile(data.contract, JSON.stringify(contractValue));
+  await generate(parseArgs(args.map((value) => value === "jakarta" ? "javax" : value)), { log() {}, warn() {} });
+});
+
+test("rolls back files written before a filesystem failure", async () => {
+  const data = await fixture();
+  const rest = path.join(data.output, "com/yss/demo/rest");
+  await mkdir(rest, { recursive: true });
+  await writeFile(path.join(rest, "convertor"), "blocking-file\n");
+  await assert.rejects(() => generate(parseArgs(data.args), { log() {}, warn() {} }));
+  await assert.rejects(() => readFile(path.join(rest, "QualityRuleController.java"), "utf8"), /ENOENT/);
+  assert.equal(await readFile(path.join(rest, "convertor"), "utf8"), "blocking-file\n");
 });

package/template/.trae/skills/ask-matt/SKILL.md

@@ -84,7 +84,7 @@ Off the main flow entirely.
 - **`/grilling`** — the interview primitive itself: rounds, the frontier, facts are the agent's job and decisions are yours. `/grill-me` and `/grill-with-docs` are the two named ways in, and `/triage`, `/wayfinder` and `/improve-codebase-architecture` all run it internally. Reach for it directly only when you want the interview with no wrapper around it.
 - **`/resolving-merge-conflicts`** — work an in-progress merge or rebase conflict hunk by hunk, resolving by **intent** traced to each side's primary source rather than by picking lines, then finish the operation. It never runs `--abort`. Standalone and off every flow: reach for it when you are already mid-conflict.
 - **`/prototype`** — a small, throwaway program that answers one design question: does this state model feel right, or what should this UI look like. Throwaway is a constraint on how the code is written, not a promise to destroy it: the answer folds into the real code, and the prototype itself is kept as a **primary source** on a `prototype/<name>` branch out of main, pointed at from the implementation issue. It's the detour in step 2 of the main flow, but reach for it any time a design question is hard to settle on paper.
-- **`/research`** — delegate reading legwork to a **background agent**: it investigates a question against **primary sources**, then leaves a cited Markdown file in the repo. Keep working while it reads. The file it produces is something to take *into* the main flow at `/grill-with-docs` — research feeds the thinking, it doesn't replace it.
+- **`/yss-research`** — investigate technical or strategy evidence using `technical-evidence` / `strategy-evidence` and `quick` / `evidence-audited` modes. Use a background agent when the runtime supports it and parallel reading is useful; delegation is not a trust guarantee. The old `/research` name is a deprecated alias. Research feeds `/grill-with-docs` and lifecycle decisions; it does not approve them.
 - **`/to-questionnaire`** — when the thing blocking you isn't in your head or the codebase but in **someone else's**, this writes them a questionnaire to fill in. It's the inverse of `/grill-me`: instead of interviewing you about the subject, it interviews you about the **send** — who it's going to, what you need back — and aims the questions at the gap. What comes back is material for `/grill-with-docs` or `/to-spec`.
 - **`/wait-what`** — the corrective for a message that didn't land. Use it mid-conversation, inside any other skill, and the agent re-pitches what it just said with the context you were missing, in plain English, using the `CONTEXT.md` vocabulary. It works after the fact; `/grill-with-docs` is the upfront cure, because a shared language agreed early is what stops the jargon arriving at all.
 - **`/teach`** — learn a concept over multiple sessions, using the current directory as a stateful workspace.

package/template/.trae/skills/wayfinder/SKILL.md

@@ -74,7 +74,7 @@ The answer isn't part of the body — it's recorded on resolution (see [Work thr
 
 Every ticket is either **HITL** — human in the loop, worked _with_ a human who speaks for themselves — or **AFK**, driven by the agent alone. A HITL ticket only resolves through that live exchange; the agent never stands in for the human's side of it (a grilling agent that answers its own questions has broken this).
 
-- **Research** (AFK): Reading documentation, third-party APIs, or local resources like knowledge bases to surface a fact a decision waits on. Resolved by a `/research` **subagent**. Use when knowledge outside the current working directory is required.
+- **Research** (AFK): Reading documentation, third-party APIs, or local resources like knowledge bases to surface a fact a decision waits on. Resolved by a `/yss-research` **subagent** (`/research` is a deprecated alias). Use when knowledge outside the current working directory is required.
 - **Prototype** (HITL): Raise the fidelity of the discussion by making a cheap, rough, concrete artifact to react to — an outline, a rough take, a stub, or UI/logic code via the /prototype skill. Links the prototype as an asset. Use when "how should it look" or "how should it behave" is the key question.
 - **Grilling** (HITL): Conversation. The default case. Always invoke the /grilling and /domain-modeling skills.
 - **Task** (HITL or AFK): Manual work that must happen before a _decision_ can be made — nothing to decide, prototype, or research, but the discussion is blocked until it's done. Signing up for a service so its API can be judged, provisioning access, moving data so its shape can be seen. This is the one type that _does_ rather than decides — and it earns its place by unblocking a decision, not by delivering the destination. The agent drives it alone where it can (AFK); otherwise it hands the human a precise checklist (HITL). Resolved when the work is done; the answer records what was done and any resulting facts (credentials location, new URLs, row counts) later tickets depend on.
@@ -112,7 +112,7 @@ User invokes with a loose idea.
 2. **Map the frontier.** Grill again, **breadth-first** this time: fan out across the whole space rather than deep on any one thread, surfacing the open decisions and the first steps takeable now. **If this surfaces no fog** — the way to the destination is already clear, the whole journey small enough for one session — you don't need a map. Stop and ask the user how they'd like to proceed.
 3. **Create the map** (label `wayfinder:map`): Destination and Notes filled in, Decisions-so-far empty, the fog sketched into **Not yet specified**.
 4. **Create the tickets you can specify now** as child issues of the map — then wire blocking edges in a **second pass** (issues need ids before they can reference each other). Wiring sorts them into the frontier and the blocked; everything you can't yet specify stays in the fog — the **Not yet specified** section.
-5. **Fire the research subagents.** For each `research` ticket you just created, spin up a `/research` subagent to resolve it in parallel, capturing its findings on a throwaway `research/<name>` branch with a context pointer from the ticket.
+5. **Fire the research subagents.** For each `research` ticket you just created, spin up a `/yss-research` subagent to resolve it in parallel, capturing its findings on a throwaway `research/<name>` branch with a context pointer from the ticket. `/research` remains only as a deprecated compatibility alias.
 6. Stop — charting is one session's work; it hand-resolves nothing.
 
 ### Work through the map

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

@@ -28,7 +28,7 @@ description: 用于生成完整的 YSS DDD 多模块后端脚手架。当用户
 2. 优先运行 `node scripts/generate_and_verify_scaffold.mjs`，在同一个受控工作流中生成骨架并执行真实 Maven 验证。`generate_scaffold.mjs` 只是底层生成原语，单独返回 0 不代表脚手架完成。
 3. 检查生成的模块名、POM、机械启动入口、基础配置文件和包路径。
 4. 受控工作流必须在生成项目根目录实际执行 `./mvnw validate`、`./mvnw test` 和 `./mvnw package`；三条命令全部返回 0 后才能报告完成。
-5. 三条 Wrapper 命令通过只得到 `empty-scaffold-verified`。如需声称已满足下游技能的首切片就绪条件，必须再通过 golden first slice，得到 `first-slice-verified`。
+5. 三条 Wrapper 命令通过只得到 `empty-scaffold-verified`。如需声称已满足下游技能的首切片就绪条件，必须使用 `node scripts/run_first_slice_verification.mjs` 校验批准且版本当前的 Slice Implementation Contract、完整分层产物、skill tree digest 与根 Wrapper；只有验证器成功更新 Manifest 后才得到 `first-slice-verified`。
 
 受控验证命令由本 skill 的 `node scripts/run_scaffold_verification.mjs` 固定执行；验证器先检查 `.yss/scaffold-generation.json` 的合同元数据和 Wrapper、Java、项目级 Maven settings/profile、仓库凭据是否就绪，再在指定 evidence 目录写入每条命令的 stdout/stderr、`exit_code`、`failure_category`、耗时、执行时间和 `scaffold-verification.json`。仓库或凭据失败归为 `repository-access`，与 `project-model`、`compilation`、`bootstrap-entrypoint`、`test-failure`、`packaging` 分开；任何一条命令失败或未执行都必须阻断。
 
@@ -55,6 +55,15 @@ node scripts/generate_and_verify_scaffold.mjs \
   --evidence-dir /path/to/evidence/scaffold
 ```
 
+完成批准的 golden first slice 后运行：
+
+```bash
+node scripts/run_first_slice_verification.mjs \
+  --project-root /path/to/implementation-repo/my-service \
+  --slice-contract-file /path/to/approved-slice-contract.json \
+  --evidence-dir /path/to/evidence/first-slice
+```
+
 ## 生成结果应包含
 
 - 父工程 POM
@@ -75,7 +84,7 @@ node scripts/generate_and_verify_scaffold.mjs \
 - Harness 内多项目布局必须使用 `apps/backend/<project>/`；`apps/backend/` 只能是生成器的父容器，`app/backend/`、`app/frontend/` 及其子路径一律拒绝。`git-submodule` gitlink、空挂载点、detached HEAD 工作树不得覆盖生成，即使传入 `--force` 也不得当成普通目录，且不得走「请显式传入 `--force`」普通目录覆盖 / rename 路径。`--output-dir` 指向 detached HEAD 子仓时不得 mkdir、staging 或生成工程。先 `git submodule update --init` 并在子仓附加分支工作树内生成。生成器必须先调用 `gitSubmoduleScaffoldViolation`，再在 exists / `--force` / rename 之前调用 `refuseGitlinkAsRegularDirectory`。
 - 不要在 skill 里硬编码用户业务字段或真实连接信息。
 - 生成后要检查依赖关系是否仍符合分层约束。
-- 生成后必须继续使用 `yss-backend-scaffold-parent` 校验工程基线，再按垂直切片加载 `yss-domain`、`yss-application`、`yss-repository`、`yss-web-controller` 等行为 skill；各 skill 的 `references/*-layer-guide.md` 承载分层开发规范。
+- 生成时的静态依赖由技能注册表与 Router 共同约束为 `yss-backend-scaffold-parent`、`alibaba-java-code-style`。生成后必须回到 Router，并按批准切片加载 `yss-domain`、`yss-application`、`yss-repository`、`yss-mybatis`、`yss-web-controller`、`yss-dto`、`yss-exception`、`yss-validation`、`mapstruct`、`lombok`、`alibaba-java-code-style` 等实际命中的行为 skill。
 - 当前脚手架第一阶段仅支持经过验证的 `mysql`；未提供完整模板和验证的数据库类型不得伪装成已支持。
 - 生成后的后端工程必须使用项目根目录 `./mvnw ...` 执行构建、测试、运行和 CI 验证；不得在 README、实施记录、Ticket、Review 或 Release 中默认写裸 `mvn ...`。既有仓库确实无法使用 wrapper 时，必须记录受控例外。
 - 原型确认后，`scaffold_status=required` 才能进入本 skill；本 skill 的生成边界是工程结构、POM、配置、Wrapper 和机械模板，不是业务实现。
@@ -83,7 +92,8 @@ node scripts/generate_and_verify_scaffold.mjs \
 - 新脚手架合同只接受 schema v2，必须分别携带 `project_name`、`base_package` 和 `maven_coordinates`；后者包含项目 `group_id` / `project_version`、父 POM GAV 与 `yss_components_version`，并由 CLI 原样传入。schema v1 为 `unsupported`，直接拒绝且不自动升级。
 - 合同 `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 v2 `.yss/scaffold-generation.json`，记录合同 digest、Target Profile、模板 digest、下游 skill hash、generator-owned 文件 hash、严格 `generation_policy` 和完成等级；清单缺失或不一致时不得交给后续 Router。
+- 生成项目必须写入 Manifest v2 `.yss/scaffold-generation.json`，记录合同 digest、Target Profile、模板 digest、下游完整 skill tree digest、脚手架父合同与 Router 合同 digest、generator-owned 文件 hash、严格 `generation_policy` 和完成等级；清单缺失或不一致时不得交给后续 Router。
+- `first-slice-verified` 只能由 `run_first_slice_verification.mjs` 写入。手工改 Manifest、只生成 Controller、只通过局部模块测试或仅有结构扫描都不能升级完成等级。
 - 严禁把领域规则、状态机、权限、事务、复杂查询、错误映射、业务字段或用户可见行为塞进脚手架生成步骤。`./mvnw validate`、输出目录存在或“生成成功”都不等于生命周期批准、架构放行或 `ready-for-agent`。
 - 生命周期脚手架生成必须关闭 `--with-example`，不得把 User CRUD 或业务字段当作样板。生成器严格 `initialize-only`：非空目标、`--force`、旧项目迁移和当前模板升级一律 `unsupported`。未来若支持同一 Target Profile 内的模板升级，必须另行设计和批准，当前不预留可执行承诺。
 - 脚手架完成后，所有后续生成的后端代码必须回到 `yss-router`，消费批准且版本当前的 Slice Implementation Contract 和对应 YSS skill；业务行为使用 `behavior-tdd`，机械生成才使用 `controlled-generation`。
@@ -98,6 +108,7 @@ node scripts/generate_and_verify_scaffold.mjs \
 - 主脚本：`scripts/generate_scaffold.mjs`
 - 推荐的一键生成验证入口：`scripts/generate_and_verify_scaffold.mjs`
 - 受控验证器：`scripts/run_scaffold_verification.mjs`
+- 首切片验证器：`scripts/run_first_slice_verification.mjs`
 - 模板目录：`assets/templates/`
 - 分层细化参考：`references/yss-backend-scaffold-parent/` 及其子 skill
 

package/template/.trae/skills/yss-ddd-scaffold-generator/references/ARCHITECTURE.md

@@ -104,13 +104,13 @@ Domain Error -> Application propagation/translation -> Web Exception Translator
 
 - Scaffold 只生成机械模块、POM、Wrapper、配置、架构规则和 Manifest，不生成生产业务 CRUD。
 - 初始生成器为 `initialize-only`，非空目标失败。
-- Manifest v2 记录模板/合同/downstream skill digest 与 generator-owned 文件 hash。
+- Manifest v2 记录模板、脚手架父合同、Router 合同、downstream 完整 skill tree digest 与 generator-owned 文件 hash。
 - 当前不支持模板升级，不得重跑初始生成器覆盖业务工程。未来如需支持同一 Target Profile 内的模板版本升级，必须另行设计、批准并验证。
 
 ## 5. 完成等级
 
 - `generated`：文件已原子生成，尚未完成 Wrapper 验证。
 - `empty-scaffold-verified`：根目录 `./mvnw validate/test/package` 全部通过。
-- `first-slice-verified`：golden first slice 的 Domain、Application、Repository/MyBatis、DTO/Web、Exception、Wire 与架构负例全部通过。
+- `first-slice-verified`：批准且版本当前的 golden first slice 已具备 Domain 模型/Gateway、Application Service 实现/事务/Query Port、Repository/Mapper/GatewayImpl/QueryAdapter、DTO/Web/Exception 与分层测试；下游完整 skill tree digest 无漂移，且根 Wrapper 全部通过。该状态只能由 `scripts/run_first_slice_verification.mjs` 写入。
 
-只有最后一级可以声明已满足下游 YSS skills 的首切片就绪条件。
+只有首切片验证器可以把 Manifest 从 `empty-scaffold-verified` 升级到最后一级；手工写值、局部测试或结构扫描均无效。只有最后一级可以声明已满足下游 YSS skills 的首切片就绪条件。

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

@@ -102,7 +102,18 @@ metadata-service/
 
 ## 4. 后续路由
 
-`empty-scaffold-verified` 不等于业务切片可实现。后续必须回到 `yss-router`，消费批准且版本当前的 Slice Implementation Contract，再按影响面加载 `yss-domain`、`yss-application`、`yss-repository`、`yss-mybatis`、`yss-dto`、`yss-exception`、`yss-web-controller` 等 skill，并使用 `behavior-tdd` 实现业务行为。只有 golden first slice 全部通过才能标记 `first-slice-verified`。
+`empty-scaffold-verified` 不等于业务切片可实现。后续必须回到 `yss-router`，消费批准且版本当前的 Slice Implementation Contract，再按影响面加载 `yss-domain`、`yss-application`、`yss-repository`、`yss-mybatis`、`yss-web-controller`、`yss-dto`、`yss-exception`、`yss-validation`、`mapstruct`、`lombok`、`alibaba-java-code-style` 等 skill，并使用 `behavior-tdd` 实现业务行为。
+
+完成 golden first slice 后，必须运行：
+
+```bash
+node .agents/skills/yss-ddd-scaffold-generator/scripts/run_first_slice_verification.mjs \
+  --project-root /path/to/implementation-repo/metadata-service \
+  --slice-contract-file /path/to/approved-slice-contract.json \
+  --evidence-dir /path/to/evidence/first-slice
+```
+
+只有该验证器确认合同、全层产物、skill tree digest 与根 Wrapper 全部通过，并更新 Manifest 后，才能标记 `first-slice-verified`。
 
 目标目录必须不存在。`--force`、旧项目迁移和当前模板升级均为 `unsupported`。旧项目继续按原工程维护；现代化改造必须单独立项、先评估再逐切片迁移。
 

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

@@ -45,7 +45,7 @@ infrastructure-+
 - Maven 内部仓库通过命名 profile `yss-internal` 与环境变量注入；共享模板不写内部 URL 或凭据。
 - Wrapper 必须带 checksum；DEBUG 和 MyBatis stdout SQL 只允许在 `application-local.yml`。
 - `./mvnw validate`、`./mvnw test`、`./mvnw package` 全部成功只得到 `empty-scaffold-verified`。
-- 只有 golden first slice 真实组合 Domain/Application/Infrastructure/Web 并通过根 Wrapper，才能得到 `first-slice-verified`。
+- 只有批准且版本当前的 golden first slice 真实组合 Domain/Application/Infrastructure/Web、通过下游 skill tree drift 校验与根 Wrapper，才能由 `run_first_slice_verification.mjs` 写入 `first-slice-verified`。
 
 ## 下游权威技能
 
@@ -53,5 +53,6 @@ infrastructure-+
 - Application：`yss-application`
 - Persistence：`yss-repository` + `yss-mybatis`
 - Web：`yss-web-controller` + `yss-dto` + `yss-exception`
+- 横切实现约束：`yss-validation` + `mapstruct` + `lombok` + `alibaba-java-code-style`
 
 业务代码必须回到 `yss-router`，消费批准且版本当前的 Slice Implementation Contract，并采用 `behavior-tdd`；脚手架只生成机械工程资产。