create-yss-spec 3.0.1 → 3.1.3

package/src/validation/metadata.js

@@ -0,0 +1,105 @@
+"use strict";
+
+const OWNERSHIP_TYPES = new Set([
+  "managed",
+  "managed-customizable",
+  "generated",
+  "user-owned",
+  "protected",
+]);
+const MERGE_STRATEGIES = new Set(["replace-with-force", "manual"]);
+
+function assertPositiveInteger(value, name) {
+  if (value !== undefined && (!Number.isInteger(value) || value < 1)) {
+    throw new Error(`模板元数据 ${name} 必须是正整数`);
+  }
+}
+
+function assertSha256(value, name) {
+  if (value !== undefined && !/^[0-9a-f]{64}$/.test(value)) {
+    throw new Error(`模板元数据 ${name} 必须是 64 位 sha256`);
+  }
+}
+
+function validateTemplateMetadata(metadata, {
+  currentSchemaVersion = 2,
+  templateName,
+  templateSource,
+} = {}) {
+  if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) {
+    throw new Error("模板元数据必须是 JSON 对象");
+  }
+  if (metadata.metadataSchemaVersion !== undefined && (!Number.isInteger(metadata.metadataSchemaVersion) || metadata.metadataSchemaVersion < 1)) {
+    throw new Error("模板元数据 metadataSchemaVersion 必须是正整数");
+  }
+  if (metadata.metadataSchemaVersion > currentSchemaVersion) {
+    throw new Error(`不支持的模板元数据版本：${metadata.metadataSchemaVersion}`);
+  }
+  if (metadata.managedFiles !== undefined && (typeof metadata.managedFiles !== "object" || metadata.managedFiles === null || Array.isArray(metadata.managedFiles))) {
+    throw new Error("模板元数据 managedFiles 必须是 JSON 对象");
+  }
+
+  assertPositiveInteger(metadata.ownershipPolicyVersion, "ownershipPolicyVersion");
+  assertSha256(metadata.ownershipPolicyHash, "ownershipPolicyHash");
+  assertPositiveInteger(metadata.customizationPolicyVersion, "customizationPolicyVersion");
+  assertSha256(metadata.customizationPolicyHash, "customizationPolicyHash");
+  assertPositiveInteger(metadata.generatorPolicyVersion, "generatorPolicyVersion");
+  assertSha256(metadata.generatorPolicyHash, "generatorPolicyHash");
+
+  for (const [relativePath, record] of Object.entries(metadata.managedFiles || {})) {
+    if (!record || typeof record !== "object" || Array.isArray(record)) {
+      throw new Error(`模板元数据 managedFiles.${relativePath} 必须是对象`);
+    }
+    if (record.ownership !== undefined && !OWNERSHIP_TYPES.has(record.ownership)) {
+      throw new Error(`模板元数据 managedFiles.${relativePath}.ownership 非法：${record.ownership}`);
+    }
+    if (
+      record.mergeStrategy !== undefined &&
+      !MERGE_STRATEGIES.has(record.mergeStrategy)
+    ) {
+      throw new Error(
+        `模板元数据 managedFiles.${relativePath}.mergeStrategy 非法：${record.mergeStrategy}`,
+      );
+    }
+    if (
+      record.generatorId !== undefined &&
+      !/^[a-z][a-z0-9-]*$/.test(record.generatorId)
+    ) {
+      throw new Error(
+        `模板元数据 managedFiles.${relativePath}.generatorId 非法：${record.generatorId}`,
+      );
+    }
+    if (
+      record.generatorVersion !== undefined &&
+      (!Number.isInteger(record.generatorVersion) || record.generatorVersion < 1)
+    ) {
+      throw new Error(
+        `模板元数据 managedFiles.${relativePath}.generatorVersion 必须是正整数`,
+      );
+    }
+  }
+
+  if (metadata.metadataSchemaVersion === currentSchemaVersion) {
+    if (templateName !== undefined && metadata.templateName !== templateName) {
+      throw new Error("模板元数据 templateName 与当前 CLI 不匹配");
+    }
+    if (typeof metadata.cliVersion !== "string" || !metadata.cliVersion) {
+      throw new Error("模板元数据 cliVersion 缺失或非法");
+    }
+    if (templateSource !== undefined && metadata.templateSource !== templateSource) {
+      throw new Error("模板元数据 templateSource 缺失或非法");
+    }
+    if (!/^[0-9a-f]{40}$/.test(metadata.templateCommit || "")) {
+      throw new Error("模板元数据必须包含 40 位不可变 templateCommit");
+    }
+    if (!/^[0-9a-f]{64}$/.test(metadata.managedFilesManifestVersion || "")) {
+      throw new Error("模板元数据 managedFilesManifestVersion 缺失或非法");
+    }
+    if (typeof metadata.variables !== "object" || metadata.variables === null || Array.isArray(metadata.variables)) {
+      throw new Error("模板元数据 variables 必须是 JSON 对象");
+    }
+  }
+  return metadata;
+}
+
+module.exports = { validateTemplateMetadata };

package/src/validation/security.js

@@ -0,0 +1,67 @@
+"use strict";
+
+const path = require("node:path");
+const { collectGitRoots, inspectCheckoutState } = require("../git/worktree");
+const { isGitSubmoduleMount } = require("../git/submodule");
+
+const DEFAULT_UNMANAGED_USER_PATHS = new Set([".gitmodules"]);
+
+function gitlinkWriteViolation(targetDir, { force = false, packageRoot = null, deps = {} } = {}) {
+  const resolved = path.resolve(targetDir);
+  const roots = (deps.collectGitRoots || collectGitRoots)(resolved);
+  for (const root of roots) {
+    if (packageRoot && path.resolve(root) === path.resolve(packageRoot)) continue;
+    let current = resolved;
+    while (true) {
+      if ((deps.isGitSubmoduleMount || isGitSubmoduleMount)(root, current, deps)) {
+        const checkout = (deps.inspectCheckoutState || inspectCheckoutState)(root, current, deps);
+        if (checkout === "empty-gitlink" || checkout === "uninitialized") {
+          return "空 gitlink 不得当成普通目录写入；gitlink 不得由 CLI 覆盖";
+        }
+        if (checkout === "detached-head") {
+          return "detached HEAD 不得当成普通目录写入；gitlink 不得由 CLI 覆盖";
+        }
+        if (path.resolve(current) === resolved) {
+          return force
+            ? "--force 不得把 git-submodule 挂载点当成普通目录覆盖"
+            : "git-submodule gitlink 不得由 CLI 覆盖；先 git submodule update --init，在子仓附加分支的工作树内操作，或改用独立目录";
+        }
+      }
+      if (path.resolve(current) === path.resolve(root)) break;
+      const parent = path.dirname(current);
+      if (parent === current) break;
+      current = parent;
+    }
+  }
+  return null;
+}
+
+function assertTargetWorkingTreeWritable(targetDir, options = {}) {
+  const violation = gitlinkWriteViolation(targetDir, options);
+  if (violation) throw new Error(violation);
+}
+
+function unmanagedPathReason(targetDir, relativePath, { packageRoot = null, unmanagedPaths = DEFAULT_UNMANAGED_USER_PATHS, deps = {} } = {}) {
+  const normalized = String(relativePath).split(path.sep).join("/");
+  if (unmanagedPaths.has(normalized) || normalized.split("/")[0] === ".gitmodules") {
+    return ".gitmodules 是用户资产，不属于受管模板文件";
+  }
+  const absolutePath = path.resolve(targetDir, normalized);
+  const roots = (deps.collectGitRoots || collectGitRoots)(targetDir);
+  for (const root of roots) {
+    if (packageRoot && path.resolve(root) === path.resolve(packageRoot)) continue;
+    let current = absolutePath;
+    while (true) {
+      if ((deps.isGitSubmoduleMount || isGitSubmoduleMount)(root, current, deps)) {
+        return "gitlink / apps 挂载工作树是用户资产，不属于受管模板文件";
+      }
+      if (path.resolve(current) === path.resolve(root)) break;
+      const parent = path.dirname(current);
+      if (parent === current) break;
+      current = parent;
+    }
+  }
+  return null;
+}
+
+module.exports = { DEFAULT_UNMANAGED_USER_PATHS, gitlinkWriteViolation, assertTargetWorkingTreeWritable, unmanagedPathReason };

package/src/validation/snapshot.js

@@ -0,0 +1,47 @@
+"use strict";
+
+const path = require("node:path");
+
+function normalizeRelativePath(value) {
+  return String(value).split(path.sep).join("/");
+}
+
+function validateTemplateSnapshot(snapshot, { manifestHash, treeHash } = {}) {
+  if (!snapshot || typeof snapshot !== "object" || Array.isArray(snapshot)) {
+    throw new Error("模板快照元数据必须是 JSON 对象");
+  }
+  if (!/^[0-9a-f]{40}$/.test(snapshot.templateCommit || "")) {
+    throw new Error("模板快照必须绑定 40 位不可变 templateCommit");
+  }
+  if (!/^[0-9a-f]{64}$/.test(snapshot.snapshotHash || "")) {
+    throw new Error("模板快照必须包含 64 位 snapshotHash");
+  }
+  if (manifestHash !== undefined && snapshot.manifestHash !== manifestHash) {
+    throw new Error("模板快照与当前 template.manifest.json 不一致，请重新构建 CLI 包");
+  }
+  if (snapshot.encodedPaths !== undefined && (typeof snapshot.encodedPaths !== "object" || snapshot.encodedPaths === null || Array.isArray(snapshot.encodedPaths))) {
+    throw new Error("模板快照 encodedPaths 必须是 JSON 对象");
+  }
+
+  const encodedTargets = new Set();
+  for (const [logicalPath, encodedPath] of Object.entries(snapshot.encodedPaths || {})) {
+    for (const value of [logicalPath, encodedPath]) {
+      const normalized = normalizeRelativePath(value);
+      if (!normalized || normalized === "." || normalized.startsWith("../") || normalized.includes("/../") || path.posix.isAbsolute(normalized)) {
+        throw new Error(`模板快照包含越界路径：${value}`);
+      }
+    }
+    const normalizedTarget = normalizeRelativePath(encodedPath);
+    if (encodedTargets.has(normalizedTarget)) {
+      throw new Error(`模板快照 encodedPaths 存在重复目标：${encodedPath}`);
+    }
+    encodedTargets.add(normalizedTarget);
+  }
+
+  if (treeHash !== undefined && snapshot.snapshotHash !== treeHash) {
+    throw new Error("模板快照内容 hash 不匹配，请重新构建 CLI 包");
+  }
+  return snapshot;
+}
+
+module.exports = { validateTemplateSnapshot, normalizeRelativePath };

package/template/.agents/rules/yss-ai-skills.md

@@ -2,60 +2,8 @@
 trigger: always_on
 ---
 
-# YSS AI Skills Entry
+# YSS UI 实现入口
 
-本项目使用 YSS UI 业务页面开发规范。处理 Vue3 业务页面、CRUD、列表、表单、抽屉、YTable、YEditTable、YFormily、YTree、API 对接任务时，必须先读取匹配的 SKILL.md，再写计划或代码。
+仅在生产前端或 YSS UI 实现影响命中时使用本入口。先按当前 Slice Implementation Contract 与 `docs/agents/yss-skill-registry.yaml` 选择最小技能集，再进入 `.agents/skills/yss-ui/SKILL.md`；完整业务页面使用 `.agents/skills/yss-ui-business-page-generation/SKILL.md`，并按任务触发读取其引用的 canonical `SKILL.md`。原型阶段使用 `yss-prototype-stage`，不得调用生产实现技能 `yss-ui`。
 
-## Available Skills
-
-- yss-ui-business-page-generation: .agents/skills/yss-ui-business-page-generation/SKILL.md
-- yss-page-module-development: .agents/skills/yss-page-module-development/SKILL.md
-- theme-token-usage: .agents/skills/theme-token-usage/SKILL.md
-- component-selection-imports: .agents/skills/component-selection-imports/SKILL.md
-- page-skeleton: .agents/skills/page-skeleton/SKILL.md
-- page-list-module: .agents/skills/page-list-module/SKILL.md
-- page-form-module: .agents/skills/page-form-module/SKILL.md
-- ytable-usage: .agents/skills/ytable-usage/SKILL.md
-- yedit-table-usage: .agents/skills/yedit-table-usage/SKILL.md
-- ytree-usage: .agents/skills/ytree-usage/SKILL.md
-- prototype-page-acceptance: .agents/skills/prototype-page-acceptance/SKILL.md
-- yss-api-integration: .agents/skills/yss-api-integration/SKILL.md
-- file-export-download: .agents/skills/file-export-download/SKILL.md
-- vue3-best-practices: .agents/skills/vue3-best-practices/SKILL.md
-- frontend-commit: .agents/skills/frontend-commit/SKILL.md
-- java-backend-commit: .agents/skills/java-backend-commit/SKILL.md
-- yss-use-table-height: .agents/skills/yss-use-table-height/SKILL.md
-- yss-use-tree-height: .agents/skills/yss-use-tree-height/SKILL.md
-- yss-formily: .agents/skills/yss-formily/SKILL.md
-- formily-foundation: .agents/skills/formily-foundation/SKILL.md
-- formily-linkage-effects: .agents/skills/formily-linkage-effects/SKILL.md
-- formily-mode-slot-detail: .agents/skills/formily-mode-slot-detail/SKILL.md
-- formily-step-flow: .agents/skills/formily-step-flow/SKILL.md
-
-## Mandatory Workflow
-
-1. 业务页面/CRUD/列表/表单/树表生成主入口：先读 `.agents/skills/yss-ui-business-page-generation/SKILL.md`（旧触发词读 `.agents/skills/yss-page-module-development/SKILL.md`）。
-2. 新增或修改页面、组件、Less、内联样式、TS 渲染配置、SVG 色值：必须读 `.agents/skills/theme-token-usage/SKILL.md`。
-3. 导出、报表、模板、附件、Excel、CSV、PDF、ZIP、Blob 下载任务：必须读 `.agents/skills/file-export-download/SKILL.md`。
-4. 列表或表格任务：同时读 `.agents/skills/page-list-module/SKILL.md`、`.agents/skills/ytable-usage/SKILL.md`、`.agents/skills/yss-use-table-height/SKILL.md`。
-5. 新增/编辑/查看/抽屉表单：同时读 `.agents/skills/yss-formily/SKILL.md`、`.agents/skills/page-form-module/SKILL.md`。
-6. 可编辑表格、扩展属性、添加行/删除行：必须读 `.agents/skills/yedit-table-usage/SKILL.md`。
-7. 用户给原型截图或旧项目路径：必须读 `.agents/skills/prototype-page-acceptance/SKILL.md`，先生成验收清单，再实现。
-
-## Hard Stops
-
-- 模板已预置 yss-ui 项目级 MCP 配置；当前会话可用时，生成业务代码前必须先调用一次 `get_codegen_rules`。不确定导出时用 `list_components`，配置组件/Hook/Utils 前用 `get_component_docs`，复杂场景用 `get_demo`，不确定归属时用 `search_docs`。需要全局配置的客户端按 `docs/user-guide/yss-ui-mcp.md` 人工安装，不自动修改用户主目录。
-- 禁止使用 YTable 不存在的 `request`、`search-params` Props 和 `actionConfig.actions`；实例 `refresh()` 只刷新当前表格数据，不得当作远程重新查询。
-- 标准列表必须使用 `:data`、`:columns`、`:loading`、`pageable`、`v-model:pagination`、`@page-change`。
-- 表格主操作必须放入 `#toolbar-right`；只有确实需要列设置时才使用 `:toolbar-config="{ custom: true }"`。
-- 业务列表查询区默认将查询/重置按钮放在 YFormily 外部独占一行并右对齐；`AutoButtonGroup + Submit + Reset` 仅用于纯 Formily 提交表单。
-- 所有 YFormily 横向业务表单必须使用 `FormLayout(labelWidth, labelAlign: 'right') -> FormGrid -> 字段`，不得省略固定 label 宽度和右对齐。
-- FormGrid 必须保持响应式：默认 `minColumns: 1`，通过 `maxColumns`、`minWidth` 控制宽屏列数；禁止 `minColumns` 等于 `maxColumns` 固定列数，除非用户明确要求不响应式。
-- 抽屉/弹窗编辑表单默认 `labelWidth: 140`、`FormGrid { maxColumns: 2, minColumns: 1, minWidth: 320~360 }`；备注/长文本字段必须用 `gridSpan` 占满整行。
-- 可编辑表格必须优先使用 `YEditTable`，禁止用 `a-table` 手搓。
-- 抽屉表单必须有响应式宽度，查看态不显示保存按钮。
-- 页面和组件禁止硬编码品牌色及 hover/active/selected/focus 色阶；主色透明态必须从真实动态 Token 派生，不得依赖未同步变量的固定色 fallback。
-- 导出下载必须优先调用 `handleBlobResponse(res.data, res.headers)`；生成方法缺少 Blob 配置时，第二参数必须传 `{ responseType: 'blob' }`，禁止手改 Orval 生成文件。
-- Orval 请求失败由 `mutator.ts` 统一提示并 reject；业务 Hook 禁止 `if (res?.success)` 冗余判断，也禁止在 `else`/`catch` 重复 `message.error`，除非请求显式跳过了全局处理。
-- 调用 Orval API 前必须检查当前生成文件；存在具名导出时直接导入，只有工厂导出时在模块顶层创建一次实例，禁止猜测 `getApi()` 名称。
-- 有截图/旧项目参考时，交付前必须逐项对照查询区、表格工具栏、分页高度、抽屉、label、字段控件类型。
+YTable 使用真实 API：不得臆造 `request`、`search-params` 或 `actionConfig.actions`；主操作必须放入 `#toolbar-right`，只有确实需要列设置时才使用 `toolbar-config.custom`。其余组件、表单、主题、API 与导出细则以下沉技能为准。

package/template/.agents/skills/.strategic-design-skills-manifest.json

@@ -3,33 +3,38 @@
   "source": "iloveZzz/yss-harness-design-agent",
   "source_type": "git-submodule",
   "source_root": ".agents/skills",
-  "source_revision": "c93911622e1ada4a42ec5b0781f6cd06b504977c",
+  "source_revision": "5c1c98225bb181c7c1add8972c1e44b866205f76",
   "adaptation_ref": "docs/agents/strategic-design-skills-integration.md",
   "skills": [
     {
       "upstream": "prototype-review",
       "canonical": "prototype-review",
-      "upstream_hash": "92ab63f2c9aabf81580bd80d1a96a6174c9d4808f893a06a5180413af381e291"
+      "upstream_hash": "2e77b3093a758bb692fb3bda453c5c020d0523f875975e17e2731365f67432e1"
     },
     {
       "upstream": "yss-prototype-stage",
       "canonical": "yss-prototype-stage",
-      "upstream_hash": "bb8835942c113cb754e34cbb5b192d14191903460cbfe7c7fe321f8e798cb5be"
+      "upstream_hash": "e8f2f3a507da6bf7be0582e4a4dd9659381da8e291755070698a1f51a4e33808"
     },
     {
       "upstream": "yss-design-system",
       "canonical": "yss-design-system",
-      "upstream_hash": "54ab669e04c8eddb278cf52fe174878cd4797ef8fdf8546f41e1a59c6fb434ba"
+      "upstream_hash": "90aaf06b2514353152464a4d032076fa9d5ef56272d8ad526f5544f3c22a2b00"
     },
     {
       "upstream": "yss-antd-design",
       "canonical": "yss-antd-design",
-      "upstream_hash": "917099caa9b76ca3cfd1d0f81f61b28111c1c54ed93e92891f81012dcd0662e2"
+      "upstream_hash": "08ce99d45586d5ea19e25fdd9e9a6ede16e66f18992b70b87e0cd23f92343b16"
+    },
+    {
+      "upstream": "yss-antdv-next-design",
+      "canonical": "yss-antdv-next-design",
+      "upstream_hash": "2942ed52dd58a38e51f09eb11254809334aeaed08f21cd081f09f35e6647a68c"
     },
     {
       "upstream": "yss-stage-decision",
       "canonical": "yss-stage-decision",
-      "upstream_hash": "3a8a49a8d006543788023dc24764188a29863bb1a1a5af30e5a57a536e75f4f6"
+      "upstream_hash": "1eadf230f0e17bf6d209c1df1249acef3520ab29c26a80c476a2a557a224c10a"
     }
   ]
 }

package/template/.agents/skills/.yss-skills-manifest.json

@@ -5,7 +5,7 @@
   "source_root": "packages/skills",
   "source_category": "app",
   "excluded_categories": ["library"],
-  "excluded_skills": ["java-backend-commit"],
+  "excluded_skills": ["java-backend-commit", "page-module-development", "prototype-page-acceptance"],
   "source_revision": "c4d958f18cc947cb91cbe1bd48783fa4601cc18f",
   "adaptation_ref": "docs/agents/yss-ui-skills-integration.md",
   "package": {
@@ -23,9 +23,7 @@
     { "upstream": "frontend-commit", "canonical": "frontend-commit", "upstream_hash": "ffc1c7813607705c7c1158f4c5d3111aca79e73f1843e33bbc95eda9b5c726de" },
     { "upstream": "page-form-module", "canonical": "page-form-module", "upstream_hash": "4df686c7267c6be00680ea1faa908e0cf02e59bfe01c8111bbcaa80dea63c9b8" },
     { "upstream": "page-list-module", "canonical": "page-list-module", "upstream_hash": "303d8fc2161465ec3e81692c7b750ed814307ccf65f4fb51e0de69fe7af38d4f" },
-    { "upstream": "page-module-development", "canonical": "yss-page-module-development", "upstream_hash": "5f917ca85e522ddf2bf5a149db1c51e2e1b64b21e4fd6d7f8d3378177184244d" },
     { "upstream": "page-skeleton", "canonical": "page-skeleton", "upstream_hash": "d82c44770054d9bb0bc17849c25675e5672f01144614b3ffb846ec575ac19dec" },
-    { "upstream": "prototype-page-acceptance", "canonical": "prototype-page-acceptance", "upstream_hash": "bc5d75925ac8d7a2cbc38a0d65383faa4e8384c64be3d98b9994a506f50d6003" },
     { "upstream": "theme-token-usage", "canonical": "theme-token-usage", "upstream_hash": "b38acb4caf5012c9134df16a312b6be31b2b5d3fd6b976cfccee8d845f27c0ef" },
     { "upstream": "use-table-height", "canonical": "yss-use-table-height", "upstream_hash": "8a5baa8ca6a8dd2b2ed123391838b1a13e3f5cab8196225ed3429ca5b513d43f" },
     { "upstream": "use-tree-height", "canonical": "yss-use-tree-height", "upstream_hash": "2a9265cc997c2c20b6cfebbdc19b66b04450278fca5d5db252a5d855b2d95bed" },

package/template/.agents/skills/alibaba-java-code-style/SKILL.md

@@ -20,6 +20,7 @@ This skill distills the provided `阿里巴巴 Java 开发手册` 1.4.0 PDF into
 
 ## Core Priorities
 
+- 先消费 architecture_identity 与工程 Java/数据库基线。MVC 分层按 `docs/agents/backend-architecture-profiles.md`；MySQL 专属方言规则仅对批准的 MySQL 存储生效，不能要求 H2 骨架引入 MySQL 驱动。YSS 包装、命名及处理器差异逐项记录基线例外，安全、权限、敏感信息与 SQL 参数绑定不得豁免。
 - Keep names readable, English, and consistent with Java layer conventions.
 - Avoid null, equality, wrapper comparison, collection, and concurrency traps that compile cleanly but fail at runtime.
 - Make logs useful without wasting CPU, disk, or alert budget.

package/template/.agents/skills/code-review/references/yss-review-standards.md

@@ -12,7 +12,7 @@
 2. Slice Implementation Contract 的 `required_skills`：对每个技能读取 `.agents/skills/<id>/SKILL.md` 及该 skill 指明的 references。
 3. 影响面专项检查输入（与合同并集，不得互相替代）：
    - 后端：`alibaba-java-code-style`、`yss-domain`、`yss-application`、`yss-repository`、`yss-web-controller`、`yss-dto`、`mapstruct`、`lombok`
-   - UI：`yss-ui`、`yss-design-system`、`yss-ui-business-page-generation`、`yss-page-module-development`
+   - UI：`yss-ui`、`yss-design-system`、`yss-ui-business-page-generation`
 4. 报告模板中的后端 / 前端门禁表。空着的适用行视为 `missing_evidence`。
 
 YSS 页面模块约定（YTable、YFormily、页面骨架等）走 Standards，不并入 UI fidelity。UI fidelity 只核原型与状态矩阵。

package/template/.agents/skills/domain-modeling/CONTEXT-FORMAT.md

@@ -1,60 +1,55 @@
-# CONTEXT.md Format
+# YSS 业务词汇表合同
 
-## Structure
+## 位置与版本
 
-```md
-# {Context Name}
-
-{One or two sentence description of what this context is and why it exists.}
-
-## Language
+每个 YSS Git 仓库只允许一个大小写精确的根目录 `CONTEXT.md`。禁止嵌套 `CONTEXT.md`、`CONTEXT-MAP.md`、跨仓相对路径和绝对路径引用。独立仓库各自拥有自己的根词汇表，通过结构化 handoff 同步，不共同写一个文件。
 
-**Order**:
-{A one or two sentence description of the term}
-_Avoid_: Purchase, transaction
+文件顶部必须声明：
 
-**Invoice**:
-A request for payment sent to a customer after delivery.
-_Avoid_: Bill, payment request
-
-**Customer**:
-A person or organization that places orders.
-_Avoid_: Client, buyer, account
+```yaml
+---
+context_schema_version: 1
+---
 ```
 
-## Rules
+缺失或不支持的版本必须返回 `migration-required`，不得猜测格式。
 
-- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others under `_Avoid_`.
-- **Keep definitions tight.** One or two sentences max. Define what it IS, not what it does.
-- **Only include terms specific to this project's context.** General programming concepts (timeouts, error types, utility patterns) don't belong even if the project uses them extensively. Before adding a term, ask: is this a concept unique to this context, or a general programming concept? Only the former belongs.
-- **Group terms under subheadings** when natural clusters emerge. If all terms belong to a single cohesive area, a flat list is fine.
+## 标准结构
 
-## Single vs multi-context repos
+```md
+# 业务上下文
 
-**Single context (most repos):** One `CONTEXT.md` at the repo root.
+本文档只记录稳定业务语言，不记录实现细节、计划草稿或架构说明。
 
-**Multiple contexts:** A `CONTEXT-MAP.md` at the repo root lists the contexts, where they live, and how they relate to each other:
+## 流程术语
 
-```md
-# Context Map
+| 术语 | 含义 | 英文标识 | 避免 / 备注 |
+|---|---|---|---|
+| Spec | 产品研发规格。 | — |  |
+
+## 业务术语
 
-## Contexts
+| 术语 | 含义 | 英文标识 | 适用业务责任区 | 避免 / 备注 |
+|---|---|---|---|---|
+| 准入决定 | 合规审查形成的准入结论。 | AdmissionDecision | ComplianceReview | 避免：`审批结果` |
+```
 
-- [Ordering](./src/ordering/CONTEXT.md) — receives and tracks customer orders
-- [Billing](./src/billing/CONTEXT.md) — generates invoices and processes payments
-- [Fulfillment](./src/fulfillment/CONTEXT.md) — manages warehouse picking and shipping
+## 术语身份
 
-## Relationships
+- 业务术语的稳定身份是 `<ContextId>/<EnglishIdentifier>`，例如 `ComplianceReview/AdmissionDecision`。
+- 跨业务责任区共享且含义完全一致的术语使用 `Global/<EnglishIdentifier>`。
+- `英文标识` 与 `ContextId` 使用 PascalCase；非 `Global` 的 ContextId 必须来自当前业务边界与规则设计的内部 `contexts[].context_id`。
+- 同一业务责任区内中文术语、英文标识和禁用别名不得冲突。不同责任区可以拥有同名局部术语，但引用必须带 ContextId。
+- `Global` 术语不得被局部上下文用相同中文术语或英文标识重新定义；语义不同的词不应声明为 Global。
+- 流程术语的 `英文标识` 固定为 `—`，只由 `template-source` 维护；`project-instance` 只维护业务术语。
 
-- **Ordering → Fulfillment**: Ordering emits `OrderPlaced` events; Fulfillment consumes them to start picking
-- **Fulfillment → Billing**: Fulfillment emits `ShipmentDispatched` events; Billing consumes them to generate invoices
-- **Ordering ↔ Billing**: Shared types for `CustomerId` and `Money`
-```
+## 内容边界
 
-The skill infers which structure applies:
+- 只写已经确认、稳定且未来资产需要复用的业务语言。候选、猜测和未决术语保留在 Discovery、业务边界与规则设计或 `context_delta`。
+- 定义保持一到两句，说明概念是什么；不要写类全名、表名、接口路径、实现步骤或计划。
+- 禁用别名使用 `避免：别名一、别名二`；需要补充说明时追加 `；备注：...`。
+- 术语稳定时立即回写。工作单元完成、门禁批准或阶段转换前仍须执行 context reconciliation。
 
-- If `CONTEXT-MAP.md` exists, read it to find contexts
-- If only a root `CONTEXT.md` exists, single context
-- If neither exists, create a root `CONTEXT.md` lazily when the first term is resolved
+## 机器验证
 
-When multiple contexts exist, infer which one the current topic relates to. If unclear, ask.
+使用根目录 `scripts/verify-context-contract` 校验位置、版本、表格、术语身份、适用业务责任区和引用。业务资产只使用结构化 `context_ref: CONTEXT.md` 与 `term_refs`，不得使用 `CONTEXT.md#Term` 或 `contexts/<ContextId>/CONTEXT.md`。校验器兼容旧项目的 `适用限界上下文` 表头，但新模板只写 `适用业务责任区`。

package/template/.agents/skills/domain-modeling/SKILL.md

@@ -1,15 +1,15 @@
 ---
 name: domain-modeling
-description: Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a CONTEXT.md, or recording or editing an ADR.
+description: 梳理项目的业务词汇、责任范围和关键决策；讨论术语、编辑 CONTEXT.md 或记录 ADR 时使用。
 ---
 
-# Domain Modeling
+# 业务词汇与关键决策
 
-Actively build and sharpen the project's domain model as you design. This is the *active* discipline — challenging terms, inventing edge-case scenarios, and writing the glossary and decisions down the moment they crystallise. (Merely *reading* `CONTEXT.md` for vocabulary is not this skill — that's a one-line habit any skill can do. This skill is for when you're changing the model, not just consuming it.)
+在设计过程中主动澄清业务词汇、责任范围和关键决策：质疑含糊说法，用边界与失败场景检验规则，并在结论稳定时写入词汇表或决策记录。仅仅读取 `CONTEXT.md` 不需要调用本技能；只有准备改变业务语言或关键决策时才使用。
 
 ## File structure
 
-Most repos have a single context:
+YSS repositories use exactly one root context file:
 
 ```
 /
@@ -21,37 +21,21 @@ Most repos have a single context:
 └── src/
 ```
 
-If a `CONTEXT-MAP.md` exists at the root, the repo has multiple contexts. The map points to where each one lives:
-
-```
-/
-├── CONTEXT-MAP.md
-├── docs/
-│   └── adr/                          ← system-wide decisions
-├── src/
-│   ├── ordering/
-│   │   ├── CONTEXT.md
-│   │   └── docs/adr/                 ← context-specific decisions
-│   └── billing/
-│       ├── CONTEXT.md
-│       └── docs/adr/
-```
-
-Create files lazily — only when you have something to write. If no `CONTEXT.md` exists, create one when the first term is resolved. If no `docs/adr/` exists, create it when the first ADR is needed.
+不要创建嵌套 `CONTEXT.md` 或 `CONTEXT-MAP.md`。多个业务责任区统一记录在根词汇表的 `适用业务责任区` 列中；内部仍使用稳定 `ContextId`。第一次确有必要记录 ADR 时再创建 `docs/adr/`。YSS 仓库缺少根 `CONTEXT.md` 属于合同错误，必须先修复再继续生命周期工作。
 
 ## During the session
 
-### Challenge against the glossary
+### 对照词汇表检查冲突
 
 When the user uses a term that conflicts with the existing language in `CONTEXT.md`, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"
 
-### Sharpen fuzzy language
+### 澄清含糊语言
 
 When the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account' — do you mean the Customer or the User? Those are different things."
 
-### Discuss concrete scenarios
+### 讨论具体业务故事
 
-When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts.
+讨论业务关系时，用具体故事和失败案例检验它们，促使用户明确概念边界、规则责任和例外结果。
 
 ### Cross-reference with code
 
@@ -61,7 +45,7 @@ When the user states how something works, check whether the code agrees. If you
 
 When a term is resolved, update `CONTEXT.md` right there. Don't batch these up — capture them as they happen. Use the format in [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md).
 
-`CONTEXT.md` should be totally devoid of implementation details. Do not treat `CONTEXT.md` as a spec, a scratch pad, or a repository for implementation decisions. It is a glossary and nothing else.
+`CONTEXT.md` 不得包含实现细节。不要把它当作 Spec、草稿区或实现决策仓库；它只是一份稳定业务词汇表。
 
 ### Offer ADRs sparingly
 

package/template/.agents/skills/grill-with-docs/SKILL.md

@@ -4,16 +4,17 @@ description: Use when the user explicitly requests a relentless design interview
 disable-model-invocation: true
 ---
 
-Call the Skill tool with `grilling`, then call it separately with `domain-modeling`.
+Call the Skill tool with `grilling`, then call it separately with `domain-modeling`. This compatibility entry does not define a second glossary format: it consumes `domain-modeling/CONTEXT-FORMAT.md`, the repository Context Contract validator, and the lifecycle reconciliation contract.
 
 ## Output Contract
 
-1. Read the repository identity and current glossary before the first round.
+1. Read `yss-project.yaml` and the root glossary before the first round, then run `scripts/verify-context-contract --root . --json`. Missing or lowercase root files, nested `CONTEXT.md`, `CONTEXT-MAP.md`, unsupported schema, absolute/cross-repository references, and Markdown pseudo-anchors are `blocked` or `migration-required`.
 2. Separate discoverable facts from user decisions; investigate facts instead of asking the user.
 3. Ask the entire current decision frontier, with a recommendation for every question, then wait.
-4. Record resolved stable terms in the authoritative `CONTEXT.md` only when they are true glossary entries.
+4. Keep candidate or disputed terms in the Discovery decision frontier. Only after confirmation, use `domain-modeling` to record true stable glossary entries in the repository root's single, case-sensitive `CONTEXT.md`; business rows use the five-column format and `<ContextId>/<EnglishIdentifier>` identity. Non-`Global` Context IDs must come from the approved business responsibility areas in the business-boundary asset.
 5. Create an ADR only when the decision is hard to reverse, surprising without context, and a real trade-off.
 6. Persist factual research/validation records in the repository's existing review or research convention.
-7. Do not modify implementation skills, contracts, or code until the user confirms shared understanding and the intended change scope.
+7. For `project-instance`, before requesting approval or returning a next work unit, generate and validate `context_reconciliation` with a readable ref, `document_digest`, `referenced_terms_digest`, and `term_refs`. Unresolved candidates, scope conflicts, aliases, or digest drift are `blocked`; reconciliation does not create another gate. For `template-source`, do not add fictional business terms and return a reasoned `not-applicable` after validating the template contract.
+8. Do not modify implementation skills, contracts, or code until the user confirms shared understanding and the intended change scope.
 
-The final grilling round must list confirmed decisions, unresolved assumptions, documents changed, and the next authorized action. A research note is evidence, not an architecture approval or release claim.
+The final grilling round must list confirmed decisions, unresolved assumptions, documents changed, `context_reconciliation` status/ref, and the next authorized action, then return control to `yss-product-lifecycle` (or the active YSS lifecycle orchestrator). It cannot approve an asset or advance a stage itself. A research note is evidence, not an architecture approval or release claim.

package/template/.agents/skills/lombok/SKILL.md

@@ -19,6 +19,7 @@ allowed-tools: Read, Grep, Glob, Write, Edit
 
 ## YSS 阶段 7 执行结果
 
+- 消费工程 Java 与处理器基线；三个新后端 Profile 为 Java 8。MapStruct binding 进入 annotationProcessorPaths，不作为业务依赖单独引入；示例不授权升级依赖。MVC PO 的身份/敏感字段风险与 DDD 相同，不能默认全量 @Data。
 - 消费批准后的 Slice Contract/work unit，只在允许路径内调整 POJO 样板和注解处理器配置。
 - 受控生成必须记录对象类型、选用/排除注解、实体关系和敏感字段风险、编译/测试实际结果。
 - 按 `yss-implementation-contract-compiler` 的统一 Execution Result 返回 changed files、证据、偏离和新增影响；`@Data` 实体风险、处理器配置缺失或越界路径返回 `violation`。
@@ -258,7 +259,7 @@ public void readFile(String path) throws IOException {
 ```java
 @SneakyThrows  // Wraps checked exception
 public String readConfig() {
-    return Files.readString(Path.of("config.json"));
+    return new String(Files.readAllBytes(Paths.get("config.json")), StandardCharsets.UTF_8);
 }
 ```
 

package/template/.agents/skills/mapstruct/SKILL.md

@@ -19,6 +19,7 @@ allowed-tools: Read, Grep, Glob, Write, Edit
 
 ## YSS 阶段 7 执行结果
 
+- Java、依赖与处理器版本来自工程基线，不从下面通用示例推断。三个新后端 Profile 为 Java 8；MVC 的 wire/internal 转换在 server，core/service 不依赖 client，Repository 不依赖上层 DTO。采用 Spring Bean 和构造器注入，显式映射或忽略字段；禁止通过全局 IGNORE 掩盖合同字段遗漏。
 - 消费批准后的 Slice Contract/work unit，只为合同中的 DTO/VO/PO/Domain 转换生成 Mapper/Convertor。
 - 受控生成必须记录 source/target、忽略字段、更新语义、Lombok processor 配置和 mapper 行为测试。
 - 按 `yss-implementation-contract-compiler` 的统一 Execution Result 返回生成/源文件、测试和实际验证；未映射字段、反射/BeanUtils 退化或越界路径返回 `violation`。
@@ -230,8 +231,8 @@ public abstract class UserMapper {
             <artifactId>maven-compiler-plugin</artifactId>
             <version>3.13.0</version>
             <configuration>
-                <source>17</source>
-                <target>17</target>
+                <source>${maven.compiler.source}</source>
+                <target>${maven.compiler.target}</target>
                 <annotationProcessorPaths>
                     <!-- Order matters: Lombok first -->
                     <path>