create-yss-spec 3.0.0 → 3.1.0

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

@@ -6,6 +6,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { parseDocument } from "../../../../scripts/vendor/yaml.mjs";
+import { assertArchitectureAgreement, validateArchitectureIdentity } from "../../../../scripts/lib/backend-architecture.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 = {
@@ -131,9 +132,15 @@ async function validateContract(contract, args) {
   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");
+  const mvc = contract.architecture_profile !== "target-domain-model";
+  const applicationModule = { "target-domain-model": "application", "layered-mvc-service": "service", "mvc-data-analysis-v1": "core" }[contract.architecture_profile];
+  if (!applicationModule) throw new Error("unsupported architecture_profile");
+  const allowedDto = { "target-domain-model": ["web"], "layered-mvc-service": ["server", "client"], "mvc-data-analysis-v1": ["client"] }[contract.architecture_profile];
+  if (!allowedDto.includes(contract.dto_placement)) throw new Error("dto_placement does not match architecture_profile");
+  if (mvc) validateArchitectureIdentity(contract.architecture_identity);
   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`;
+  const applicationPackage = args["application-service-package"] || `${args["base-package"]}.${applicationModule}.service`;
+  if (mvc && !applicationPackage.startsWith(`${args["base-package"]}.${applicationModule}.`)) throw new Error("MVC service interface must belong to its application module");
   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");
@@ -142,7 +149,8 @@ async function validateContract(contract, args) {
   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 (mvc) throw new Error("existing MVC project requires explicit onboarding support; no automatic migration");
+    return { applicationPackage, implementationRoot, applicationModule };
   }
 
   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");
@@ -150,18 +158,26 @@ 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 (manifest.schema_version !== 2) throw new Error("scaffold manifest must use schema_version=2");
+  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 (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");
   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`);
+  const expectedWebProject = mvc ? path.join(scaffoldRoot, `${manifest.project_name}-server`) : 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"]];
+  const profilePairs = mvc ? [["platform", "platform_profile"], ["validation_namespace", "validation_namespace"]] : [["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 };
+  const dtoProject = contract.dto_placement === "client" ? path.join(scaffoldRoot, `${manifest.project_name}-client`) : expectedWebProject;
+  if (contract.dto_placement === "client" && !contract.architecture_identity.resolved_modules.includes("client")) throw new Error("client DTO requires approved client capability");
+  if (args["web-output-dir"] && path.resolve(args["web-output-dir"]) !== path.join(expectedWebProject, "src/main/java", packagePath(args["base-package"]))) throw new Error("web-output-dir must not override approved module ownership");
+  return { applicationPackage, implementationRoot, applicationModule, dtoProject };
 }
 
 export async function generate(args, logger = console) {
@@ -171,7 +187,7 @@ 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}`); }
-  const { applicationPackage, implementationRoot } = await validateContract(contract, args);
+  const { applicationPackage, implementationRoot, applicationModule, dtoProject } = 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 []; }
@@ -183,16 +199,17 @@ export async function generate(args, logger = console) {
   const basePath = packagePath(args["base-package"]);
   const webBase = args["web-output-dir"] || (args["web-project-dir"] ? path.join(args["web-project-dir"], "src", "main", "java", basePath) : path.join(args["output-dir"], basePath));
   const webRoot = ensureSubdir(webBase, "rest");
+  const dtoRoot = dtoProject ? path.join(dtoProject, "src/main/java", basePath, "rest") : webRoot;
   const planned = [];
   const plan = (target, contents) => planned.push({ target, contents });
   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", "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 };
+    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"]}.${applicationModule}.command.${domainClass}CreateCommand;`, `import ${args["base-package"]}.${applicationModule}.command.${domainClass}UpdateCommand;`, `import ${args["base-package"]}.${applicationModule}.query.${domainClass}PageQuery;`, `import ${args["base-package"]}.${applicationModule}.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, pagination_field_declarations: paginationFields(approvedFields.pagination, dto.profile) }));
+    for (const [templateName, target, declaration] of [["web/dto/Response.java.template", path.join(dtoRoot, "dto", "response", `${domainClass}Response.java`), fields(table.columns || [], approvedFields.response)], ["web/dto/CreateRequest.java.template", path.join(dtoRoot, "dto", "request", `${domainClass}CreateRequest.java`), fields(table.columns || [], approvedFields.create, { command: true })], ["web/dto/UpdateRequest.java.template", path.join(dtoRoot, "dto", "request", `${domainClass}UpdateRequest.java`), fields(table.columns || [], approvedFields.update, { command: true })], ["web/dto/PageRequest.java.template", path.join(dtoRoot, "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");

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

@@ -1,6 +1,6 @@
 import assert from "node:assert/strict";
 import { createHash } from "node:crypto";
-import { mkdir, mkdtemp, readFile, writeFile } from "node:fs/promises";
+import { mkdir, mkdtemp, readFile, writeFile, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import test from "node:test";
@@ -11,6 +11,34 @@ 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");
 
+for (const [profile, module, placement, modules, generator] of [
+  ["layered-mvc-service", "service", "server", ["server", "service", "repository"], "yss-layered-mvc-scaffold-generator"],
+  ["mvc-data-analysis-v1", "core", "client", ["server", "core", "client", "repository", "adapter", "feign-client"], "yss-mvc-data-analysis-project-initializer"]
+]) test(`${profile} binds MVC service types, DTO ownership and drift checks`, async (t) => {
+  const data = await fixture({ platform_profile: "spring-boot-2.7-jdk8", validation_namespace: "javax" });
+  t.after(() => rm(data.root, { recursive: true, force: true }));
+  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" } };
+  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` });
+  await writeFile(data.contract, JSON.stringify(contract));
+  const args = parseArgs([...data.args.map((x) => x === "com.yss.demo.application.service" ? `com.yss.demo.${module}.service` : x), "--scaffold-manifest-file", manifestFile, "--web-project-dir", path.join(project, "demo-service-server")]);
+  manifest.architecture_identity = { ...identity, contract_digest: "b".repeat(64) };
+  await writeFile(manifestFile, JSON.stringify(manifest));
+  await assert.rejects(() => generate(args), /stale/);
+  manifest.architecture_identity = identity;
+  await writeFile(manifestFile, JSON.stringify(manifest));
+  const files = await generate(args, { log() {}, warn() {} });
+  assert.equal(files.length, 6);
+  const convertor = await readFile(path.join(project, "demo-service-server/src/main/java/com/yss/demo/rest/convertor/QualityRuleWebConvertor.java"), "utf8");
+  assert.match(convertor, new RegExp(`com\\.yss\\.demo\\.${module}\\.command`));
+  assert.doesNotMatch(convertor, /\.application\.|\.domain\.|Gateway/);
+  await readFile(path.join(project, `demo-service-${placement}/src/main/java/com/yss/demo/rest/dto/request/QualityRuleCreateRequest.java`));
+});
+
 const metadataValue = {
   tables: [{
     table_name: "quality_rule",

package/template/AGENTS.md

@@ -1,131 +1,92 @@
 # AGENTS.md — AI 开发入口规则
 
-> 本文件只保存 Agent 必须首先遵守的仓库身份路由、硬门禁和禁止事项。完整生命周期、流程裁剪和 YSS 实现细则以下文引用的权威资产为准。
+> 只保留入口、硬门禁和禁令。
 
 ## 1. 首先识别仓库身份
 
-每个任务开始时先读取根目录 `yss-project.yaml`：
+先读根 `yss-project.yaml`：`template-source` 走模板维护；`project-instance` 走产品生命周期。
 
-- `repository_mode: template-source`：使用“模板维护流程”，不默认生成具体产品的 Spec、原型、OpenAPI 或垂直切片 Ticket。
-- `repository_mode: project-instance`：按产品研发生命周期分诊任务。
-- 文件缺失、schema 版本不支持或模式值非法时，停止路由并执行迁移检查；不根据目录、Git 远程或占位符猜测身份。
-
-仓库身份契约由根目录 `yss-project.yaml` 和本文件共同声明。
+- `template-source` 不生成产品 Spec、原型、OpenAPI 或垂直切片 Ticket。
+- 文件缺失、schema 不支持或模式非法时停止并迁移检查；不得按目录、Git remote 或占位符猜身份。
 
 ## 2. 单一事实来源
 
-| 事实类型                    | 权威资产                                        |
-| ----------------------- | ------------------------------------------- |
-| 领域与流程词汇                 | `CONTEXT.md`                                |
-| Agent 入口、硬门禁、禁止事项       | `AGENTS.md`                                 |
-| 主阶段、门禁、产物、工作单元、证据和稳定 ID | `docs/process/lifecycle-registry.yaml`；`docs/process/lifecycle-artifact-map.md` 为派生阅读视图 |
-| 影响面触发与 `not-applicable` | `docs/process/harness-process-tailoring.md` |
-| 模板维护强度触发与最低等级 | `docs/process/maintenance-intensity.yaml` |
-| 技能清单、来源、版本、哈希和投影目标      | `skills-lock.json`                          |
-| 技能分层、别名、默认可发现性和运行时入口 | `docs/agents/yss-skill-registry.yaml`（当前 `status: active`；Router / 生命周期必须消费） |
-| 数字人角色、阶段协作组、运行时绑定与生命周期会签 | `docs/agents/digital-human-roles.yaml`；`docs/agents/digital-human-roles.md` 为操作说明 |
-| 视觉令牌与组件视觉变体规范 | 根目录 `DESIGN.md`；`docs/design/design.md` 为中文治理与生命周期适配，`docs/design/tokens/*` 为派生快照 |
+| 事实 | 权威资产 |
+|---|---|
+| 词汇 | `CONTEXT.md` |
+| Agent 入口红线 | `AGENTS.md` |
+| 阶段、门禁、产物、工作单元、证据、稳定 ID | `docs/process/lifecycle-registry.yaml`；`docs/process/lifecycle-artifact-map.md` 仅为派生阅读视图 |
+| 影响面、`not-applicable`、模板维护强度 | `docs/process/harness-process-tailoring.md`、`docs/process/maintenance-intensity.yaml` |
+| Skill 来源、版本、投影、路由 | `skills-lock.json`、`docs/agents/yss-skill-registry.yaml` |
+| 数字人角色、运行时与会签 | `docs/agents/digital-human-roles.yaml` |
+| 视觉规范 | `DESIGN.md`；治理见 `docs/design/design.md` |
 
-README、用户指南、根目录 `CLAUDE.md` 和其他说明文档只引用或解释上述事实，不重复定义同一规则。`CLAUDE.md` 是 Claude Code 入口指针，不是第二套 Agent 规则。
+其他文档和派生视图只引用，不重复定义。
 
 ## 3. 标准文档语言与规范语汇
 
-- 所有面向业务、产品、架构、实施、审查、发布和复盘的落地文档，正文统一使用简体中文。
-- 英文专有名词、代码标识、API 路径、schema、类名、方法名、枚举值、错误码、命令、文件名和协议 metadata 保持原样。
-- 新流程统一使用 Spec、Ticket、`to-spec`、`to-tickets`。过时术语和技能名只能出现在迁移指南或明确标注的旧项目上下文。
-- `CONTEXT.md` 是 Spec 构建及其落地工具链的统一语言输入，也是所有会创建或修改稳定业务、产品、架构、实施、审查、发布和复盘资产的强制前置上下文。`yss-product-lifecycle`、其原生 work unit，以及 `grill-with-docs`、`to-spec`、`to-tickets`、`implement` 等显式兼容入口，在规划、起草、评审、拆 Ticket 或实现前都必须读取并持续消费它；工具无法读取或消费时必须暂停并返回 `blocked`，不得凭临场翻译、同义词或局部上下文继续。
-- 稳定业务术语必须先在 `CONTEXT.md` 中登记 PascalCase `英文标识`，再进入 Spec、原型、契约、Ticket、代码或验证资产；代码类型 / 字段与契约 property 使用该词干按 `CONTEXT.md` 文首规则变形。改中文术语或英文标识都先回写 `CONTEXT.md`，并重新检查受影响资产；与词汇或 ADR 冲突时立即指出并先解决冲突。
+- 生命周期文档用简体中文；英文专名、代码 / API 标识、schema、命令、文件名和 metadata 原样保留。新流程统一用 Spec、Ticket、`to-spec`、`to-tickets`。
+- 规划至实现全程消费根 `CONTEXT.md` 及文首合同；不可读即 `blocked`。稳定术语先登记，再以 `<ContextId>/<EnglishIdentifier>` 引用；跨上下文用 `Global/<EnglishIdentifier>`。
+- 每仓只允许根目录一个大小写精确的 `CONTEXT.md`；禁止嵌套、`CONTEXT-MAP.md`、跨仓路径和伪锚点。
+- `project-instance` 每个工作单元批准或流转前完成 `context_reconciliation`；缺失、冲突或摘要漂移即 `blocked`。`template-source` 校验模板合同并记录带原因的 `not-applicable`。
 
 ## 4. `template-source` 模板维护路由
 
-按“影响面 → 单一事实来源 → 投影 / 派生资产 → 分级证据”维护。强度分级、最低证据和 checkpoint 合同见 `docs/process/harness-process-tailoring.md`。
-
-- 创建、修改或退役 skill 时使用 `maintaining-skills`，并先按 `docs/process/harness-process-tailoring.md` 判定 L1 / L2 / L3；L3 日常记录维护者自检与 fresh verification，正式发布前执行完整模板门禁。
-- `.agents/skills` 是跨 Agent 共享技能的权威内容；`.claude/skills`、`.codex/skills`、`.cursor/skills`、`.hermes/skills`、`.pi/skills`、`.qoder/skills`、`.trae/skills` 中的共享技能是生成投影，禁止分别手工修改。Cursor 的契约运行时入口是 `.cursor/skills`；不得把 canonical `.agents/skills` 与某个平台投影当作同权双入口。
-- 模板维护默认以 `scripts/verify-template-fast` 完成 `implementation-ready`；显式晋级审查时用 `scripts/verify-template-candidate`，首次冻结前和最终发布前仍必须执行完整 `scripts/verify-template`。后者是不可裁剪的模板发布阻断门禁。模板与外部 `create-yss-spec` 的跨仓库契约未完成集成验证时，不得声称可发布。
+- 按“影响面 → 事实源 → 投影 / 派生 → 分级证据”维护；改 Skill 必须用 `maintaining-skills`，并按 `docs/process/harness-process-tailoring.md` 判定 L1 / L2 / L3。
+- `.agents/skills` 是共享 Skill 权威目录；其他 Agent root 下的同名 Skill 是生成投影，不得手改或与 canonical 并列维护。
+- 内循环运行 `scripts/verify-template-fast`；晋级审查运行 `scripts/verify-template-candidate`；首次冻结和最终发布前运行不可裁剪的 `scripts/verify-template`。外部 `create-yss-spec` 集成未闭合不得称可发布。
 
 ## 5. `project-instance` 产品研发路由
 
-先用 `docs/process/harness-process-tailoring.md` 判定变更类型、影响面和最近可信阶段，再按 `docs/process/lifecycle-registry.yaml` 执行命中的工作单元和条件门禁。
-
-下表是与 `yss-product-lifecycle` 对齐的阶段级导航索引；阶段、工作单元、技能和门禁不是同一层，条件细节以注册表及 lifecycle skill references 为准。
-
-| 主阶段（registry） | 原生工作单元 | 技能入口（按影响面裁剪） | 关键产物 / 门禁 |
-|---|---|---|---|
-| 入口分诊 `stage.entry-triage` | `work-unit.entry-triage` | `yss-product-lifecycle` | 仓库身份、影响面、最近可信阶段；`gate.repository-identity-valid` |
-| Discovery `stage.discovery` | `work-unit.discovery-opportunity`、`work-unit.discovery-requirements`、`work-unit.domain-strategy-design`、`work-unit.stage-decision` | `yss-product-lifecycle`；按事实 / 领域影响使用 `competitive-intelligence`、`yss-research`、`grilling`、`domain-modeling`、`yss-stage-decision` | Discovery、用户/MVP/非目标/成功标准、测试 seam；必要时 DDD 战略设计与阶段决策包；`gate.domain-strategy-approved`、`gate.stage-decision-package-approved` |
-| Spec / 功能架构 `stage.spec-architecture` | `work-unit.spec-synthesis` | `yss-product-lifecycle`；`to-spec` 仅为显式兼容入口 | Spec、产品总体设计、功能架构；必要时 Spec Delta；`gate.spec-baseline-approved` |
-| 产品设计 `stage.product-design` | `work-unit.prototype-design` | `yss-prototype-stage` 为主合同，内部依次消费 `yss-design-system`、低保真、独立 `prototype-review`、`yss-antd-design` pre-build facts、Codex `product-design:index` focused workflow、post-build/浏览器/无障碍验证；前端落地改用 `yss-ui` | 交互说明、低 / 高保真原型、状态矩阵；`gate.prototype-reviewed`、`gate.prototype-verified`、`gate.user-confirmation` |
-| 系统 / 数据架构与工程契约 `stage.system-data-engineering` | `work-unit.technical-analysis` | `yss-router`；按影响使用 `yss-openapi-governance`、`yss-openapi-draft-review`、`codebase-design`、`implementation-repo-onboarding`、`yss-tactical-design` | OpenAPI Draft / Freeze、数据架构、工程基线、架构审查；无 API 影响记录；必要时 Tactical DDD Check；`gate.openapi-draft-reviewed`、`gate.design-reviewed`、`gate.openapi-frozen`、`gate.engineering-baseline-accepted`、`gate.architecture-reviewed` |
-| Ticket 正式化 `stage.ticket-formalization` | `work-unit.ticket-decomposition` | `yss-product-lifecycle` + `yss-router`；`to-tickets` 仅为显式兼容入口 | 功能父 Ticket、垂直切片、Slice Implementation Contract；切片初始 `ready-for-human`；`gate.slice-contract-approved`、`gate.slice-ready-for-agent` |
-| 垂直切片实现 `stage.vertical-slice-implementation` | `work-unit.slice-implementation` | `yss-router` + `tdd`；UI 影响追加 `yss-ui`、`yss-page-module-development` 及条件专项 skill；`implement` 仅为显式兼容入口 | 前后端代码、TDD、YSS Skill Execution Result；仅允许 `ready-for-agent` 且合同当前 |
-| 验证 / 发布 / 复盘 `stage.verification-release-retrospective` | `work-unit.frontend-implementation-verification`、`work-unit.code-review`、`work-unit.release-and-retrospective` | `code-review`（唯一入口，Standards 消费 YSS / Alibaba 专项检查输入）；UI 影响追加 `yss-ui` + `yss-design-system`；发布 / 复盘由 `yss-product-lifecycle` 持有 | 不可变候选快照、独立审查、findings 按合同分流、fresh verification、发布 / 回滚证据、复盘；UI 影响追加 `gate.frontend-implementation-verified`；`gate.release-ready` |
-
-- 生命周期注册表中的条件门禁全部按影响面强制。命中触发条件时必须完成；未命中时只记录 `not-applicable` 及原因，不生成空文档；不得把产物、工作单元或证据统称为门禁。
-- 安全 / 权限不设独立生命周期资料或专属门禁。日常功能不做额外登记、`not-applicable` 或推导校验；只有需求或冻结资产明确要求改变认证、授权、租户隔离、敏感数据或合规行为时，才把该行为写入普通 Spec、API、架构、验收和测试 seam，并仅按实际 UI、API、Backend、Data、High-risk 影响触发既有门禁。普通 action 注册、沿用既有认证中间件、未变化的 `401` / `403`、一般字段、SQL / DDL / 迁移和上传 / 下载本身不构成安全 / 权限专项。
-- `seam-deferred` 只能显式记录风险、责任人、后续 Ticket、验证计划和目标版本或发布日期。
-- 新功能或较大变更先进入 `yss-product-lifecycle` 的原生 Discovery / 需求分析工作单元；`grill-with-docs` 与 `to-spec` 仅作为用户显式兼容入口，Spec 基线和产品设计影响的完整判定以注册表和裁剪规则为准。
-- API 契约变更先形成 OpenAPI 3.1 Draft，经必要的工程基线、系统 / 数据架构和设计审查后 Freeze，再进入实现。
-- Spec Delta 只记录相对既有冻结 Spec 基线的高风险行为差异；全新产品、全新模块和低风险调整不生成 Spec Delta。
-- OpenAPI Freeze 或无 API 影响记录完成后，由生命周期原生 Ticket 正式化工作单元拆成可独立验证的窄垂直切片；用户显式 `to-tickets` 仅作为兼容入口，禁止只按 Adapter / Application / Domain / Infrastructure 横向拆分。
+主流程：分诊 → Discovery → Spec / 功能架构 → 产品设计 → 工程契约 → Ticket → 切片 → 验证 / 发布 / 复盘。
+
+- 先按 `docs/process/harness-process-tailoring.md` 判定影响面和最近可信阶段，再由 `yss-product-lifecycle` 执行 `docs/process/lifecycle-registry.yaml`；阅读导航见 `docs/process/lifecycle-artifact-map.md`。
+- 命中门禁必须完成；仅未命中时记录带原因的 `not-applicable`，不得生成空文档或混淆门禁、产物、工作单元、证据。安全 / 权限写入普通 Spec、契约、架构、验收和 seam，按实际影响触发门禁。
+- 新功能和较大变更先进入 Discovery；`grill-with-docs`、`to-spec`、`to-tickets`、`implement` 仅为用户显式兼容入口。API 变更先形成 OpenAPI 3.1 Draft，审查后 Freeze，再实现。
+- Spec Delta 只记冻结基线的高风险行为差异。OpenAPI Freeze 或无 API 影响记录后拆窄垂直切片，禁止仅按技术层横拆。
+- `seam-deferred` 必须记录风险、责任人、后续 Ticket、验证计划和目标版本或发布日期。
 
 ## 6. Ticket 与状态
 
-- 每个功能先建立功能父 Ticket，用于汇总 Spec、设计、审查、OpenAPI Freeze、阻塞项和阶段证据。
-- Spec 初稿、产品设计、原型、OpenAPI Draft 和待冻结资产使用 `ready-for-human`。
-- 只有通过必要门禁、阻塞边已清除并具备直接实现条件的垂直切片 Ticket，才能使用 `ready-for-agent`。
-- Ticket、Spec 和阶段证据按 `docs/agents/issue-tracker.md` 选定的主 tracker 持久化；Git remote 不代表 tracker 选择，平台不可用时按该文档生成待发布草案。五态标签见 `docs/agents/triage-labels.md`。
+- 每个功能先建父 Ticket，汇总阶段资产、审查、阻塞和证据。
+- Spec、设计、原型、OpenAPI Draft 和待冻结资产使用 `ready-for-human`；只有门禁通过、阻塞清除且可直接实现的垂直切片才能使用 `ready-for-agent`。
+- 按 `docs/agents/issue-tracker.md` 持久化主 tracker，不从 Git remote 推断；平台不可用时生成待发布草案。五态见 `docs/agents/triage-labels.md`。
 
 ## 7. 实现与 YSS 路由硬门禁
 
-进入实现时先读 `docs/process/implementation-repo-integration.md`，登记实现仓库、项目根、分支、CI、验证命令和回滚点；再使用 `yss-router` 编译最小 skill 集合与当前实现合同。
-
-- 无可复用工程时，先确认外部目标仓库或输出目录，再使用 `yss-ddd-scaffold-generator` / `yss-frontend-scaffold-generator`；当前仓库缺少 frontend / backend 目录不改变此路由。
-- 脚手架只在 `scaffold_status=required` 且受控生成合同已持久化、获得生命周期批准后运行；它只产生机械骨架，业务行为回到 Router 并使用 `behavior-tdd`。
-- 正式垂直切片必须消费已批准、已持久化且版本当前的 Slice Implementation Contract。Router 只生成草案，不批准合同、不设置 `ready-for-agent`、不宣布完成。合同 schema、Backend 子合同和证据字段以 `yss-router` references 为准。
-- UI 影响切片必须在 `ready-for-agent` 前具备通过校验的 `frontend_implementation_plan`，实现完成后补齐 `frontend_implementation_verification`；截图 / 视觉回归、状态与交互、console warning 和实际 `pnpm` 退出码均须有证据，不能只做 type-check 或声称“已对齐”。
-- 前端测试、type-check 与构建优先使用 `pnpm`；后端校验、测试与编译优先使用项目根 `./mvnw`。不要默认 `npm` / `yarn` 或裸 `mvn`。既有仓库确实没有 pnpm 或 Maven Wrapper 时，必须记录受控例外和实际命令。登记字段见 `docs/process/implementation-repo-integration.md`。
-- 路径越界、证据缺失、未执行验证、`drift`、`violation` 或 `new_impacts` 时停止实现并重新路由。
-
-实现细则由已批准合同、YSS skills 和实现接入文档定义；`AGENTS.md` 只保留入口与边界。
+- 实现前按 `docs/process/implementation-repo-integration.md` 登记仓库、项目根、分支、CI、验证命令、回滚点；再用 `yss-implementation-contract-compiler` 编译最小 Skill 集和当前合同。
+- 无工程先确认外部仓库或输出目录。Backend `scaffold_status=required` 时，由生命周期推荐 `domain-driven` / `layered-mvc`，用户逐项目确认后路由；Frontend 用 `yss-frontend-scaffold-generator`。缺目录不改路由。
+- 脚手架仅在 `scaffold-architecture-decisions.yaml` 已确认且当前、schema v3 合同已持久化并获批准后无交互运行，只生成机械骨架。既有工程不得重选或覆盖；架构转换单独立项。
+- 正式切片只消费已批准、已持久化且当前的 Slice Implementation Contract；编译器只起草，不批准、不设置 `ready-for-agent`、不宣布完成。
+- UI 切片在 `ready-for-agent` 前须有已校验的 `frontend_implementation_plan`，实现后补 `frontend_implementation_verification`，覆盖截图 / 视觉回归、状态交互、console warning、实际 `pnpm` 退出码。
+- 前端验证优先 `pnpm`，后端优先根 `./mvnw`；缺少时记录受控例外和实际命令。
+- 路径越界、证据缺失、验证未执行、`drift`、`violation` 或 `new_impacts` 时停止实现并重新路由。
 
 ## 8. 专项任务的强制入口
 
-本表补充跨阶段的触发型技能；主阶段对应的原生工作单元和条件技能以第 5 节、`yss-product-lifecycle` 及 `orchestration-contract.yaml` 为准。
-
-| 触发情形 | 必须使用 |
-|---|---|
-| 技术事实、标准、第三方 API 或框架行为影响决策，或外部证据进入领域战略 / 阶段决策 | `yss-research`；技术事实使用 `technical-evidence`，战略决策证据使用 `strategy-evidence`；旧名 `research` 仅为 deprecated alias |
-| 竞品、市场或用户口碑事实 | `competitive-intelligence` |
-| UI 设计、原型、组件或主题 | `yss-prototype-stage` 持有阶段合同：`yss-design-system` → 低保真 → 独立 `prototype-review` → `yss-antd-design` pre-build facts → Codex `product-design:index` focused workflow → post-build/浏览器/无障碍验证；其他 Agent 交付等价合同资产。前端代码落地改用 `yss-ui`，不要继续调用 `yss-antd-design` |
-| Bug、测试失败或性能回退 | `diagnosing-bugs` 建立可复现反馈，再用 `tdd` |
-| merge / rebase 冲突 | `resolving-merge-conflicts` |
-| 架构治理、难测模块或深模块设计 | `codebase-design`；`improve-codebase-architecture` 仅作为用户显式兼容入口 |
-| 跨线程、跨仓库、上下文过长或原型结论回流 | `handoff` 或等价交接记录 |
-| 数字人角色、Agent 运行时协同或生命周期会签 | 先读 `docs/agents/digital-human-roles.yaml`。职称实例叠加在编排器上，不另起生命周期，不批准 Slice 合同、不设 `ready-for-agent`、不宣布可发布 |
-| 本地知识库 init / refresh / rebuild，或要把研究结果落成持久 wiki | `llm-wiki`（落成持久 wiki 用 `ingest`；已映射 live 源变了用 `refresh`）。`template-source` 的 wiki-root 为 `.template-source/wiki`；`project-instance` 不附带源仓库编译树，需要时在仓库根 `wiki/` 执行 `init` |
-
-业务行为默认按 `tdd` 的 `behavior-tdd` 模式使用已确认的公开 seam 逐切片实现。一次性生成、纯配置或流程文档不适用代码 TDD 时，必须记录例外理由和可执行验证方式。
+- 技术事实、标准、第三方 API 或框架行为用 `yss-research`（`technical-evidence` / `strategy-evidence`）；竞品、市场、口碑用 `competitive-intelligence`。
+- 产品设计由 `yss-prototype-stage` 持有合同并调用设计系统、独立评审、H1 / H2 适配器；原型禁用 `yss-ui`。真实组件事实只用于实现计划、已批准实现和还原验证。
+- 数字人协同或会签先读 `docs/agents/digital-human-roles.yaml`；角色不得另起生命周期、批准 Slice 合同、设置 `ready-for-agent` 或宣布可发布。
+- 业务行为默认按 `tdd` 的 `behavior-tdd` 使用已确认公开 seam 逐切片实现；一次性生成、纯配置或流程文档不适用时，记录例外理由和可执行验证。
 
 ## 9. 工作区与实现仓库边界
 
-当前仓库默认是研发管理仓库，运行时代码优先位于已登记的独立实现仓库（`repository_scope: external-repository`）。只有用户明确选择当前仓库承载实现代码时，才使用同源的 `apps/backend/<project>/` 或 `apps/frontend/<project>/`（`harness-apps`），或以 Git submodule 把独立实现仓挂到同一 `apps/` 布局（`git-submodule`）。三种 scope 必须用登记字段、Git 身份和工作树 gitlink 区分；空 gitlink、detached HEAD 或 `--force` 覆盖挂载点不得当成普通目录。
-
-`apps/backend/` 和 `apps/frontend/` 只是项目容器；`app/backend/`、`app/frontend/` 及其子路径禁止作为工程输出。`git-submodule` 不得登记为 `harness-apps`，也不得把实现源码复制进 Harness。完整登记字段、嵌套 Git 授权和跨仓约束见 `docs/process/implementation-repo-integration.md`。
+- 运行时代码默认进入已登记的 `external-repository`；仅用户明确选择时使用 `apps/backend/<project>`、`apps/frontend/<project>` 的 `harness-apps`，或以真实 gitlink 使用 `git-submodule`。三种 scope 按实现接入文档登记。
+- 禁止向 `app/backend/`、`app/frontend/` 输出；空 gitlink、detached HEAD、`--force` 挂载点不得视为普通目录；不得把 submodule 登记为 `harness-apps` 或复制源码冒充。
 
 ## 10. 独立审查、验证和追踪
 
-- 实现者不能承担命中的独立审查（含数字人）。模板维护的 L3 日常路径使用维护者自检；L2 仍按需使用聚焦独立审查，正式发布仍执行完整模板门禁。模板发布、代码切片和高风险变更仍必须满足各自独立审查要求。产品切片与模板维护共用同一 finding 闭环：`violation` 由实现者在原合同路径修复后重新捕获并全轴复审；`drift` / `new_impacts` 使合同 `stale` 并回 Router。审查者不得写实现。命中后的 mandatory 不得豁免；未命中才 `not-applicable`。
-- 任何“完成 / 可合并 / 可发布”结论必须基于 fresh verification，不接受“之前跑过”或实现者自述。
-- 会签门禁按 `docs/agents/digital-human-roles.yaml` 的 `gate_policy` 关闭，会签文件经 `scripts/verify-approval-record` 核验；`gate.release-ready`、对外商务承诺和运行时外部副作用仍须生物人。
-- 在会签暂停、handoff、进入实现、合并或发布边界集中同步范围、验证证据、风险、会签点、Ticket 状态和下一步；阻塞、责任人变化或资产单独批准时立即同步。
-- Git checkpoint 只包含本轮明确范围；获得用户授权后才提交或推送。
-- 发布后或阶段性完成后做复盘判断；出现架构返工、验证返工、IMPORTANT / CRITICAL review finding 或人工确认延期时，落简体中文复盘并修订权威资产。
+- 实现者不做独立审查，Reviewer 不写实现；代码审查统一用 `code-review`。mandatory 不豁免；`violation` 修复后重审，`drift` / `new_impacts` 使合同 `stale` 并回编译器。
+- “完成 / 可合并 / 可发布”仅基于 Fresh Verification；历史结果、自述无效。
+- 会签按角色表 `gate_policy` 并经 `scripts/verify-approval-record --require-approved` 核验；`user_decision_policy` 命中的关键决定必须先展示可审阅资产，再取得提问者或其明确指定负责人的真实回复。无回复保持等待，数字人不能代答；原始来源、范围、复用和失效见生命周期 `references/user-decisions.md`。发布、商务承诺、运行时外部副作用仍须生物人。
+- 会签暂停、handoff、实现、合并、发布边界同步范围、证据、风险、会签点、Ticket 状态和下一步。Git checkpoint 只含本轮范围；提交 / 推送须用户授权。
+- 发布或阶段完成时判断复盘；架构 / 验证返工、IMPORTANT / CRITICAL finding、人工确认延期时，落中文复盘并修订事实源。
 
 ## 11. Subagent 协同
 
-使用 subagent 或其它 Agent 运行时前按 `docs/process/subagent-collaboration.md` 定义任务包和不重叠的写入范围，并同时写明数字人角色、`runtime_id`、从角色表复制的 `core_skills` / `forbidden_skills` 与 Explorer / Drafter / Worker / Reviewer / Verifier 执行态。实现者不担任独立审查者；仓库身份、Ticket 最终状态、Git checkpoint、Slice 合同批准和完成结论仍由主控数字人按编排器规则决定。会签恢复前校验 `scripts/verify-approval-record`。写隔离靠任务包；共享工作区不是默认沙箱。
+- 使用 subagent 或其他运行时前读 `docs/process/subagent-collaboration.md`，建立含角色、`runtime_id`、执行态、技能约束和不重叠写范围的任务包；共享工作区不是安全边界。
+- 仓库身份、Ticket 最终状态、Git checkpoint、Slice 合同批准和完成结论由主控裁决；实现者不得兼任独立审查者或会签自己的资产。
 
 ## 12. 测试质量基线
 
-模板推荐值为 Domain / Application `>= 90%`、API `>= 80%`、前端组件 `>= 75%`、已明确的关键流程 `100% E2E`。只有项目实例在测试策略中明确采纳或覆盖后才构成 CI 门禁；未定义关键流程清单时，不声称其 E2E 覆盖率达到 100%。
+模板推荐 Domain / Application `>= 90%`、API `>= 80%`、前端组件 `>= 75%`、关键流程 `100% E2E`；`project-instance` 明确采纳后才是 CI 门禁，未定义关键流程不得称 100% E2E。

package/template/CONTEXT.md

@@ -1,8 +1,11 @@
-# 领域上下文
+---
+context_schema_version: 1
+---
+# 业务上下文
 
-本文档是项目的领域词汇表，只记录稳定业务语言和协作概念，不记录实现细节、计划草稿或架构说明。
+本文档是项目的业务词汇表，只记录稳定业务语言和协作概念，不记录实现细节、计划草稿或架构说明。
 
-`英文标识` 是 PascalCase 词干，不是英语释义。`## 业务术语` 必须填写该列；`## 流程术语` 填 `—`。代码类型名、字段名和契约 property 由该词干变形：类名 = 词干 + YSS 工程后缀；字段与 JSON property 为 camelCase；数据库列为 snake_case；枚举常量为 UPPER_SNAKE。工程后缀以 YSS skill 和当前工程惯例为准，不作为领域词写入本表。JSON 与 Java 字段不一致时，以 DTO wire shape / OpenAPI 为准，不在本表另开列。改中文术语或英文标识都是统一语言变更，必须先回写本表。`避免 / 备注` 同时记录禁用中文和禁用英文别名。
+`英文标识` 是 PascalCase 词干，不是英语释义。`## 业务术语` 必须填写该列，并使用 `Global` 或“业务边界与规则设计”中已确认的 PascalCase `context_id` 填写 `适用业务责任区`；术语稳定身份仍是 `<ContextId>/<EnglishIdentifier>`，该编号由 Agent 维护，业务人员只需确认名称、含义和适用范围。`## 流程术语` 的英文标识填 `—`。代码类型名、字段名和契约 property 由该词干变形：类名 = 词干 + YSS 工程后缀；字段与 JSON property 为 camelCase；数据库列为 snake_case；枚举常量为 UPPER_SNAKE。工程后缀以 YSS skill 和当前工程惯例为准，不作为业务词写入本表。JSON 与 Java 字段不一致时，以 DTO wire shape / OpenAPI 为准，不在本表另开列。改中文术语、英文标识、含义或适用业务责任区都是统一业务词汇变更，必须先回写本表。`避免 / 备注` 中的禁用别名使用 `避免：别名一、别名二`，其他说明使用 `备注：...`。
 
 只有在计划、分诊、调试或架构讨论中明确沉淀出稳定语言时，才新增术语。
 
@@ -19,6 +22,7 @@
 | 主控数字人 | 运行 `yss-product-lifecycle` 的协调实例。 | — | 不是第八个业务职称；默认兼任项目经理。 |
 | 角色配置 | 某数字人角色的关注阶段、技能包、可起草产物和禁止事项。 | — | 不是独立编排器，也不含平台群聊人数。 |
 | 生命周期会签 | 指定数字人或生物人关闭 `gate.*` / 独立审查并写入 `evidence.approval-record`。 | — | 不是运行时副作用审批。会签人由 `docs/agents/digital-human-roles.yaml` 的 `gate_policy` 指定。起草者不得会签自己起草的资产。`paused-human-gate` 表示等待该会签人，不是必须生物人。 |
+| 用户决定 | 提问者或其明确指定的生物人负责人针对已展示资产、版本及范围作出的可追溯回复。 | — | 数字人审查不能代答；原始回复、指定依据及批准范围按用户决定协议记录。 |
 | 运行时副作用审批 | 对发消息、改生产、付款、删数据等工具动作的账号级确认。 | — | 点 Allow 不等于门禁已批准或可发布。避免只称「Grok 平台审批」。 |
 | Ticket 状态 | Tracker 五态：`needs-triage`、`needs-info`、`ready-for-agent`、`ready-for-human`、`wontfix`。 | — | 不要称为数字人角色或「标准角色」。 |
 | 阶段协作组 | 某阶段需要共同可见会签的逻辑成员集合。 | — | 不是某个产品的群聊；平台人数上限只写在对应 `runtimes`。 |
@@ -30,7 +34,7 @@
 | Matt Engineering Skills | 来自 `mattpocock/skills` 的轻量工程流程技能集合。 | — | 用于澄清、Spec、Ticket、实现、TDD、诊断、审查和架构治理，不替代 YSS 专项规范。 |
 | 上游技能基线 | 从外部技能源锁定的可追溯 revision 及其未经项目适配的原始内容。 | — | 不等同于项目当前实际生效的 skill；上游更新不得直接覆盖 YSS 适配。 |
 | YSS 技能适配 | 在上游技能基线之上，为 YSS 仓库身份、门禁、状态、授权和专项规范保留的可追溯差异。 | — | 必须同时保留上游内容哈希、有效内容哈希和适配依据，不作无记录的直接 fork。 |
-| YSS skills | 本项目内置的 YSS 工程规范技能。 | — | 用于 DDD、UI、OpenAPI、Repository、Controller、DTO、组件和编码规范。 |
+| YSS skills | 本项目内置的 YSS 工程规范技能。 | — | 用于业务方案设计、UI、OpenAPI、后端工程、组件和编码规范。 |
 | 技能投影 | 从权威共享技能生成、供特定 Agent root 加载的同步副本。 | — | 投影不是独立维护的技能源，不应在各 Agent root 中分别修改。 |
 | Spec | 记录用户问题、解决方案、用户故事、关键决策、验收标准和测试 seam 的产品研发规格。 | — | 新资产统一使用 Spec；旧规格称谓只在迁移记录中保留。 |
 | Spec Delta | 记录相对于既有冻结 Spec 基线的 `ADDED / MODIFIED / REMOVED` 行为、验收场景和测试映射。 | — | 不用于全新产品或全新模块，也不替代完整 Spec、OpenAPI 或架构资产。 |
@@ -45,17 +49,19 @@
 | DTO wire shape | DTO 在 HTTP/JSON 边界实际暴露的字段、类型、可空性和方向性；与 Java 字段、getter 或内部协作字段区分。 | — | 以目标 mapper / contract evidence 为准，不从 getter、Lombok 或 `@JsonIgnore` 机械推断。 |
 | UI 影响 | 会改变用户可见页面、导航、交互流程、状态呈现或权限体验的功能影响。 | — | 纯后端、API、批处理或数据变更不自动构成 UI 影响。 |
 | 产品设计影响 | UI 变化触及主流程、导航、权限体验、异常 / 恢复状态、状态流转或 API 反推，需要页面流、状态矩阵和原型校准。 | — | 文案、token、颜色、间距和无行为变化的孤立视觉修复属于 UI 影响，但不自动构成产品设计影响。 |
-| 高保真 HTML 原型 | 低保真原型评审通过后，用于在浏览器中审查真实视觉密度、交互状态和页面流的产品设计资产。 | — | 不等同于生产前端实现，也不替代 OpenAPI、Spec 校准或垂直切片。 |
+| 原型交付物 | 低保真原型评审通过后，按当前决策风险选择 H1 视觉评审或 H2 流程评审档位，并在浏览器中复验的产品设计资产。 | — | `高保真 HTML 原型` 仅用于历史资产迁移；原型交付物不等同于生产前端实现，不消费 `yss-ui`，也不替代 OpenAPI、Spec 校准或垂直切片。 |
+| 原型档位 | 用 H1 `visual-review`、H2 `flow-review` 表达原型需要回答的问题与最低证据强度。 | — | 不是实现技术栈分级，也不是成熟度评分；真实 YSS/AntDV 组件验证属于前端实现计划与实现还原验证，不属于第三种原型档位。 |
 | Visual Baseline Contract | 为生产前端还原冻结页面、视口、交互状态、参考图像和允许差异的可验收合同。 | — | 不是仅有一张原型截图或绝对像素匹配；每个基线必须可定位到同一视口和同一状态复验。 |
 | 垂直切片（Vertical Slice） | 贯穿所有受影响层、可独立验证的窄功能路径。 | — | 优先使用垂直切片，避免只按层拆分的横向任务。 |
-| Slice Implementation Contract | 阶段 7 进入实现前，由 `yss-router` 根据冻结资产和垂直切片编译、再由生命周期编排器批准的实现合同，包含 Common、Frontend、Backend、Contract 和 Cross-repo 子合同。 | — | Router 只能生成草案，不能自行批准、设置 `ready-for-agent` 或宣布完成；Backend 子合同仍保留额外强约束。 |
-| YSS Skill Execution Result | YSS 专项 skill 完成工作单元后返回的结构化执行证据，记录合同版本、变更文件、证据文件、实际验证、延期 seam、偏离和新增影响。 | — | 实现者自报 `implemented` 不构成最终通过，必须由 Router、生命周期编排器和独立 Reviewer 复核。 |
+| Slice Implementation Contract | 阶段 7 进入实现前，由 `yss-implementation-contract-compiler` 根据冻结资产和垂直切片编译、再由生命周期编排器批准的实现合同，包含 Common、Frontend、Backend、Contract 和 Cross-repo 子合同。 | — | 实现合同编译器 只能生成草案，不能自行批准、设置 `ready-for-agent` 或宣布完成；Backend 子合同仍保留额外强约束。 |
+| YSS Skill Execution Result | YSS 专项 skill 完成工作单元后返回的结构化执行证据，记录合同版本、变更文件、证据文件、实际验证、延期 seam、偏离和新增影响。 | — | 实现者自报 `implemented` 不构成最终通过，必须由 实现合同编译器、生命周期编排器和独立 Reviewer 复核。 |
 | ADR | 架构决策记录，用于沉淀难以回滚、非显而易见且存在真实取舍的技术决策。 | — | 常规实现选择不要写 ADR。 |
 | Fresh Verification | 完成前重新执行的验证证据，包括测试命令、契约校验、关键路径检查或人工审查结论。 | — | 不等同于“之前跑过”或实现者自述。 |
 | `implementation-ready` | 模板维护实现和命中影响面的快速核验已经完成，但尚未冻结正式审查候选。 | — | 是模板维护默认出口；不等同于 `ready-for-agent`、已审查或可发布。 |
 | `review-ready` | 模板维护候选已完成 candidate 核验、首次完整发布门禁和摘要冻结，可以派发独立审查。 | — | Reviewer 必须消费同一候选摘要；候选字节变化后旧审查失效。 |
 | `release-ready` | 模板维护冻结候选已经通过独立审查和最终完整 Fresh Verification。 | — | 仍不替代 `gate.release-ready` 所需的生物人发布裁决。 |
 | 实现验证命令 | 前端测试 / 构建优先 `pnpm`，后端校验 / 测试 / 编译优先 `./mvnw`。 | — | 不要默认 `npm`、`yarn` 或裸 `mvn`；仓库确实缺少 pnpm 或 Maven Wrapper 时记受控例外。 |
+| 脚手架架构选择 | 新建后端工程在工程基线中对 `domain-driven` 与 `layered-mvc` 的结构化选择；Agent 提供证据化推荐，用户确认后由生命周期批准并供脚手架合同消费。 | — | 不是新门禁，也不是生成器内的交互参数；缺失、未确认或摘要漂移时阻断生成。 |
 | 测试质量基线 | 项目实例明确采纳的覆盖率阈值、关键流程清单和受控例外。 | — | 模板推荐值本身不构成可执行门禁；未定义关键流程时，不得声称其 E2E 覆盖率达到 100%。 |
 | 主阶段 | 对相邻研发目标、工作单元和退出条件的粗粒度生命周期分组。 | — | 不等同于门禁编号，也不因增加门禁而自动增加主阶段。 |
 | 生命周期门禁（条件强制门禁） | 只有当影响面命中触发条件时才必须裁决的生命周期审查点。 | — | 未触发时记录 `not-applicable` 及原因，不生成空文档；门禁不是产物、工作单元或证据的统称。 |
@@ -63,6 +69,8 @@
 | 工作单元 | 具有明确输入、输出、允许动作和完成条件的一次有界执行。 | — | 不等同于主阶段或门禁；一个主阶段可以包含多个工作单元。 |
 | 执行证据 | 用于证明工作单元结果、门禁裁决或完成结论的可读取引用和实际验证记录。 | — | 口头声明、计划执行的命令或无法解析的引用不构成执行证据。 |
 | 单一事实来源（Single Source of Truth） | 对某一类流程事实拥有唯一定义权的权威资产。 | — | 其他资产只引用或解释，不重复定义同一规则。 |
+| 战略交接快照包 | 将批准的战略资产及证据冻结为可离线验证的完整目录或 ZIP，并提供规则和场景的派生索引。 | — | 源规则由战略方维护；包内快照与索引不成为目标仓词汇权威。 |
+| 战术承接记录 | 将源规则和关键场景关联到战术落点、测试 seam、处置结论及依赖切片的结构化记录。 | — | 延期登记不等于依赖切片可实现；冲突回交战略方，未知依赖扩大阻断。 |
 | 流程模板资产 | 可被不同项目复用的文档模板、技能说明、校验脚本、流程规范和目录占位文件。 | — | 不包含某个具体产品的 Spec、设计、OpenAPI 或 Ticket。 |
 | 模板维护流程 | 用于评估影响、修改权威资产、同步投影、执行压力验证并审查模板演进的工作流。 | — | 面向模板源仓库，不默认生成具体产品的 Spec、原型、OpenAPI 或垂直切片 Ticket。 |
 | 模板发布门禁 | 模板源发布前必须通过的结构、技能同步、流程语义和压力场景验证集合。 | — | 不等同于只检查文件存在、Markdown 链接或 YAML 语法。 |
@@ -70,15 +78,15 @@
 | YSS 研发操作系统 | 由生命周期控制、通用工作流、YSS 专项技能、证据反馈和技能供应链共同构成的可版本化研发治理体系。 | — | 不等同于单个主控 skill、某个 Agent 客户端或运行时代码平台。 |
 | 生命周期注册表 | 结构化定义主阶段、门禁、产物、工作单元、证据及其稳定标识和关系的机器可读权威资产。 | — | Markdown 地图、数量说明和验证 fixture 是其派生产物，不应分别维护同一结构事实。 |
 | 生命周期编排器 | 持有阶段、影响面、产物状态、门禁裁决、工作单元路由和恢复条件的研发流程控制平面。 | — | 不替代专项技能执行业务实现，也不以文件存在或执行者自述宣布完成。 |
-| 前端实现还原验证 | 证明生产前端相对冻结 Spec、交互说明、状态矩阵和高保真原型不存在未解释差异的独立验证。 | — | 不是绝对像素复刻、普通 type-check 或原型评审；UI 影响切片需覆盖关键视觉、状态、交互和工程证据。 |
+| 前端实现还原验证 | 证明生产前端相对冻结 Spec、交互说明、状态矩阵和原型交付物不存在未解释差异的独立验证。 | — | 不是绝对像素复刻、普通 type-check 或原型评审；UI 影响切片需覆盖关键视觉、状态、交互和工程证据。 |
 | 生命周期稳定 ID | 以对象类型命名空间和英文标识唯一指向一个生命周期对象的兼容身份。 | — | 中文名称、展示顺序和数量可以变化；已发布 ID 不得复用来表达另一种语义。 |
 | 派生产物 | 根据生命周期注册表确定性生成的结构表、数量、索引、依赖图或测试 fixture。 | — | 不承载需要人工解释的原理、取舍或实践建议，禁止脱离注册表分别维护。 |
 | 核心技能（Core Skill） | 默认可发现、负责生命周期控制或通用研发入口的稳定技能。 | — | 不包含只在特定技术影响下才需要的专项实现规则。 |
-| 专项技能（Specialist Skill） | 由 Router 根据影响面和实现合同按需选择的前端、后端、OpenAPI 或组件技能。 | — | 不作为所有任务的平级默认入口。 |
-| 试验技能 | 尚未达到项目默认支持成熟度的技能。 | — | 只在明确试验范围内使用，不进入 Router 默认技能闭包。 |
+| 专项技能（Specialist Skill） | 由 实现合同编译器 根据影响面和实现合同按需选择的前端、后端、OpenAPI 或组件技能。 | — | 不作为所有任务的平级默认入口。 |
+| 试验技能 | 尚未达到项目默认支持成熟度的技能。 | — | 只在明确试验范围内使用，不进入 实现合同编译器 默认技能闭包。 |
 | 显式兼容入口 | 为已有用户操作习惯保留的 user-invoked 工作流入口，写入前由生命周期编排器预检，结果回交其验收。 | — | 不是默认路径、过时别名或可以越过门禁的第二套生命周期。 |
 | 技能成熟度 | 描述技能从 `draft`、`verified`、`supported` 到 `deprecated` 的治理状态。 | — | 不等同于文件存在、已被投影或能够安装。 |
-| 技能注册表 | 记录技能身份、别名、分层、适用影响面、成熟度、默认可发现性和 Agent 运行时入口的机器可读路由资产。 | — | 不替代 `skills-lock.json` 的来源、hash 和投影完整性职责。当前 `docs/agents/yss-skill-registry.yaml` 为 `active`，Router、生命周期编排器和实例发现面必须消费通过校验的 canonical 技能及其 alias 解析结果。 |
+| 技能注册表 | 记录技能身份、别名、分层、适用影响面、成熟度、默认可发现性和 Agent 运行时入口的机器可读路由资产。 | — | 不替代 `skills-lock.json` 的来源、hash 和投影完整性职责。当前 `docs/agents/yss-skill-registry.yaml` 为 `active`，实现合同编译器、生命周期编排器和实例发现面必须消费通过校验的 canonical 技能及其 alias 解析结果。 |
 | LLM Wiki | 由 `raw/`、`wiki/` 与 `.wiki-manifest.json` 组成的本地持久知识库。 | — | 不是 `yss-research` 一次性研究包，也不替代权威源。`ingest` 只把用户点名的外源或已落盘研究笔记编进 IR，不改 live 权威文件。 |
 | 生态发布清单 | 关联模板 schema 与 commit、CLI 版本与快照、公开技能来源与导出 hash 的跨仓发布证据。 | — | 不要求尚未生成的仓库 commit 互相循环引用。 |
 | 研发管理仓库 | 承载 Spec、OpenAPI、架构、Ticket、验证、发布和复盘等研发管理资产的仓库。 | — | 不等同于前端 / 后端代码 monorepo。 |
@@ -93,4 +101,7 @@
 
 ## 业务术语
 
-`project-instance` 在本节新增产品对象。每一行必须有 PascalCase `英文标识`；缺该列视为统一语言未冻结。模板源不放虚构业务行。
+`project-instance` 在本节新增产品对象。每一行必须有 PascalCase `英文标识`；缺该列视为统一业务词汇未冻结。模板源不放虚构业务行。
+
+| 术语 | 含义 | 英文标识 | 适用业务责任区 | 避免 / 备注 |
+|---|---|---|---|---|