create-yss-spec 3.3.8 → 3.4.3

package/template/.codex/skills/yss-ddd-scaffold-generator/scripts/scaffold-generator.test.mjs

@@ -11,11 +11,12 @@ import { fileURLToPath } from "node:url";
 import { run } from "./run_scaffold_verification.mjs";
 import { makeGitlinkFixture } from "../../../../scripts/lib/git-submodule-fixtures.mjs";
 import { GITLINK_MODE, gitLsFilesStage } from "../../../../scripts/lib/repository-scope-policy.mjs";
+import { attachDesignPrerequisites } from "../../../../scripts/fixtures/backend-scaffold/design-prerequisites.mjs";
 
 const scripts = path.dirname(fileURLToPath(import.meta.url));
 const generator = path.join(scripts, "generate_scaffold.mjs");
 const workflow = path.join(scripts, "generate_and_verify_scaffold.mjs");
-const command = (args, options = {}) => new Promise((resolve) => execFile(process.execPath, [generator, ...args], { encoding: "utf8", ...options }, (error, stdout, stderr) => resolve({ code: error?.code ?? 0, stdout, stderr })));
+const command = (args, options = {}) => new Promise((resolve) => execFile(process.execPath, [path.resolve(scripts, "../../../../scripts/fixtures/backend-scaffold/generate-candidate.mjs"), generator, ...args], { encoding: "utf8", ...options }, (error, stdout, stderr) => resolve({ code: error?.code ?? 0, stdout, stderr })));
 const workflowCommand = (args, options = {}) => new Promise((resolve) => execFile(process.execPath, [workflow, ...args], { encoding: "utf8", ...options }, (error, stdout, stderr) => resolve({ code: error?.code ?? 0, stdout, stderr })));
 async function treeDigest(root) {
   const hash = createHash("sha256");
@@ -31,7 +32,12 @@ async function treeDigest(root) {
 }
 function contract(outputDir, overrides = {}) {
   return {
-    schema_version: 3,
+    schema_version: 4,
+    kind: "project-scaffold-contract",
+    delivery_role: "backend",
+    scaffold_kind: "backend-ddd",
+    repository_scope: "external-repository",
+    init_git: false,
     contract_id: "scaffold-1",
     contract_version: 1,
     scaffold_request_id: "scaffold-request-1",
@@ -39,7 +45,7 @@ function contract(outputDir, overrides = {}) {
     compiler_draft_ref: "compiler-1",
     lifecycle_approval_ref: "approval-1",
     persisted_ref: "persisted-1",
-    current_version: 1,
+    current_version: true,
     implementation_repository: "external",
     backend_repository: "external",
     scaffold_status: "required",
@@ -87,9 +93,13 @@ async function fixture(contractOverrides = {}) {
   decisionText = JSON.stringify(decisionSet, null, 2) + "\n";
   await writeFile(decisionFile, decisionText);
   const decisionDigest = `sha256:${createHash("sha256").update(decisionText).digest("hex")}`;
+  const scaffoldContract = contract(output, { decision_digest: decisionDigest, ...contractOverrides });
+  const design = attachDesignPrerequisites(root, scaffoldContract, { dataImpact: contractOverrides.dataImpact ?? "not-applicable", apiImpact: contractOverrides.apiImpact ?? "not-applicable" });
+  delete scaffoldContract.dataImpact;
+  delete scaffoldContract.apiImpact;
   const contractFile = path.join(root, "contract.json");
-  await writeFile(contractFile, `${JSON.stringify(contract(output, { decision_digest: decisionDigest, ...contractOverrides }), null, 2)}\n`);
-  return { root, output, contractFile, decisionFile, args: ["--project-name", "demo-service", "--base-package", "com.yss.demo", "--output-dir", output, "--contract-id", "scaffold-1", "--contract-version", "1", "--approval-ref", "approval-1", "--compiler-draft-ref", "compiler-1", "--persisted-ref", "persisted-1", "--contract-file", contractFile, "--group-id", "com.yss.datamiddle", "--project-version", "1.0.0-SNAPSHOT", "--parent-group-id", "com.yss.datamiddle", "--parent-artifact-id", "yss-datamiddle-parent", "--parent-version", "2.0.0-SNAPSHOT", "--yss-components-version", "2.0.0-SNAPSHOT"] };
+  await writeFile(contractFile, `${JSON.stringify(scaffoldContract, null, 2)}\n`);
+  return { root, output, contractFile, decisionFile, contract: scaffoldContract, design, args: ["--project-name", "demo-service", "--base-package", "com.yss.demo", "--output-dir", output, "--contract-id", "scaffold-1", "--contract-version", "1", "--approval-ref", scaffoldContract.lifecycle_approval_ref, "--compiler-draft-ref", "compiler-1", "--persisted-ref", "persisted-1", "--contract-file", contractFile, "--group-id", "com.yss.datamiddle", "--project-version", "1.0.0-SNAPSHOT", "--parent-group-id", "com.yss.datamiddle", "--parent-artifact-id", "yss-datamiddle-parent", "--parent-version", "2.0.0-SNAPSHOT", "--yss-components-version", "2.0.0-SNAPSHOT"] };
 }
 
 const controlledEnvironment = {
@@ -100,7 +110,7 @@ const controlledEnvironment = {
 };
 function targetManifest(overrides = {}) {
   return {
-    schema_version: 3,
+    schema_version: 4,
     contract_id: "id",
     contract_version: 1,
     scaffold_request_id: "request",
@@ -111,7 +121,7 @@ function targetManifest(overrides = {}) {
     compiler_draft_ref: "router",
     persisted_ref: "persisted",
     contract_file_ref: "contract",
-    current_version: 1,
+    current_version: true,
     allowed_write_paths: ["."],
     expected_evidence_files: ["manifest"],
     verification_commands: ["./mvnw validate", "./mvnw test", "./mvnw package"],
@@ -122,6 +132,7 @@ function targetManifest(overrides = {}) {
     decision_id: "scaffold-decision.demo-service",
     decision_digest: `sha256:${"a".repeat(64)}`,
     module_profile: { resolution_version: 1, requested_capabilities: [], resolved_modules: ["domain", "application", "infrastructure", "adapter", "bootstrap"] },
+    design_prerequisites: { technical_design: { ref: "technical.json", version: "v1", digest: `sha256:${"b".repeat(64)}` }, data_architecture_decision: { ref: "data.json", version: "v1", digest: `sha256:${"c".repeat(64)}`, impact: "not-applicable" }, api_contract_decision: { ref: "api.json", version: "v1", digest: `sha256:${"d".repeat(64)}`, impact: "not-applicable" }, engineering_contract_approval_ref: "approval.json" },
     profiles: { architecture: "target-domain-model", repository: "yss-internal" },
     ownership: { generated_files: [] },
     readiness: { downstream_skills: {}, architecture_ruleset: "b".repeat(64) },
@@ -138,15 +149,100 @@ async function prepareVerifierProject(project, manifest = targetManifest()) {
   await writeFile(path.join(project, ".yss", "scaffold-generation.json"), `${JSON.stringify(manifest)}\n`);
 }
 
-test("生成批准的服务级 target profile 骨架，并写入可追溯 Manifest v3", async (t) => { const data = await fixture(); t.after(() => rm(data.root, { recursive: true, force: true })); const result = await command(data.args); assert.equal(result.code, 0, result.stderr); const project = path.join(data.output, "demo-service"); const manifest = JSON.parse(await readFile(path.join(project, ".yss/scaffold-generation.json"), "utf8")); assert.equal(manifest.schema_version, 3); assert.equal(manifest.architecture_family, "domain-driven"); assert.equal(manifest.generator_skill, "yss-ddd-scaffold-generator"); assert.equal(manifest.decision_id, "scaffold-decision.demo-service"); assert.equal(manifest.scaffold_request_id, "scaffold-request-1"); assert.equal(manifest.slice_id, undefined); assert.equal(manifest.completion_level, "generated"); assert.equal(manifest.profiles.architecture, "target-domain-model"); assert.deepEqual(manifest.generation_policy, { mode: "initialize-only", existing_target: "unsupported", old_project_migration: "unsupported", template_upgrade: "unsupported" }); assert.match(manifest.generator.template_digest, /^[a-f0-9]{64}$/); assert.match(manifest.contract_digest, /^[a-f0-9]{64}$/); assert.ok(manifest.ownership.generated_files.length > 8); assert.ok(manifest.ownership.generated_files.every((item) => item.owner === "generator" && /^[a-f0-9]{64}$/.test(item.sha256))); assert.equal(manifest.generation_mode, "controlled-generation"); assert.deepEqual(manifest.verification_commands, ["./mvnw validate", "./mvnw test", "./mvnw package"]); assert.equal(manifest.bootstrap_main_class, "com.yss.demo.DemoServiceApplication"); assert.equal(manifest.bootstrap_main_source, "demo-service-bootstrap/src/main/java/com/yss/demo/DemoServiceApplication.java"); assert.match(await readFile(path.join(project, manifest.bootstrap_main_source), "utf8"), /class DemoServiceApplication/); assert.match(await readFile(path.join(project, "pom.xml"), "utf8"), /demo-service/); assert.equal(manifest.readiness.downstream_skills["yss-domain"], await treeDigest(path.resolve(scripts, "../../yss-domain"))); assert.match(manifest.readiness.contracts.scaffold_parent, /^[a-f0-9]{64}$/); assert.match(manifest.readiness.contracts.compiler_contract, /^[a-f0-9]{64}$/); });
+test("生成批准的服务级 target profile 骨架，并写入带设计门禁的 Manifest v4", async (t) => { const data = await fixture(); t.after(() => rm(data.root, { recursive: true, force: true })); const result = await command(data.args); assert.equal(result.code, 0, result.stderr); const project = path.join(data.output, "demo-service"); const manifest = JSON.parse(await readFile(path.join(project, ".yss/scaffold-generation.json"), "utf8")); assert.equal(manifest.schema_version, 4); assert.equal(manifest.architecture_family, "domain-driven"); assert.equal(manifest.generator_skill, "yss-ddd-scaffold-generator"); assert.equal(manifest.decision_id, "scaffold-decision.demo-service"); assert.equal(manifest.scaffold_request_id, "scaffold-request-1"); assert.equal(manifest.slice_id, undefined); assert.equal(manifest.completion_level, "generated"); assert.equal(manifest.profiles.architecture, "target-domain-model"); assert.deepEqual(manifest.design_prerequisites, { ...data.contract.design_prerequisites, data_architecture_decision: { ...data.contract.design_prerequisites.data_architecture_decision, impact: "not-applicable" } }); assert.deepEqual(manifest.generation_policy, { mode: "initialize-only", existing_target: "unsupported", old_project_migration: "unsupported", template_upgrade: "unsupported" }); assert.match(manifest.generator.template_digest, /^[a-f0-9]{64}$/); assert.match(manifest.contract_digest, /^[a-f0-9]{64}$/); assert.ok(manifest.ownership.generated_files.length > 8); assert.ok(manifest.ownership.generated_files.every((item) => item.owner === "generator" && /^[a-f0-9]{64}$/.test(item.sha256))); assert.equal(manifest.generation_mode, "controlled-generation"); assert.deepEqual(manifest.verification_commands, ["./mvnw validate", "./mvnw test", "./mvnw package"]); assert.equal(manifest.bootstrap_main_class, "com.yss.demo.DemoServiceApplication"); assert.equal(manifest.bootstrap_main_source, "demo-service-bootstrap/src/main/java/com/yss/demo/DemoServiceApplication.java"); assert.match(await readFile(path.join(project, manifest.bootstrap_main_source), "utf8"), /class DemoServiceApplication/); assert.match(await readFile(path.join(project, "pom.xml"), "utf8"), /demo-service/); assert.equal(manifest.readiness.downstream_skills["yss-domain"], await treeDigest(path.resolve(scripts, "../../yss-domain"))); assert.match(manifest.readiness.contracts.scaffold_parent, /^[a-f0-9]{64}$/); assert.match(manifest.readiness.contracts.compiler_contract, /^[a-f0-9]{64}$/); });
 
-test("统一 Project Scaffold Contract v4 可生成 DDD 后端并保留 v4 Manifest", async (t) => {
-  const data = await fixture({ schema_version: 4, kind: "project-scaffold-contract", delivery_role: "backend", scaffold_kind: "backend-ddd", repository_scope: "external-repository", init_git: false, current_version: true });
+test("数据影响为 required 时绑定数据架构后可生成 DDD 后端", async (t) => {
+  const data = await fixture({ dataImpact: "required" });
   t.after(() => rm(data.root, { recursive: true, force: true }));
   const result = await command(data.args);
   assert.equal(result.code, 0, result.stderr);
   const manifest = JSON.parse(await readFile(path.join(data.output, "demo-service", ".yss/scaffold-generation.json"), "utf8"));
   assert.equal(manifest.schema_version, 4);
+  assert.equal(manifest.design_prerequisites.data_architecture_decision.impact, "required");
+});
+
+test("API 影响为 required 时绑定同字节 Draft、Validation、Review 和 Freeze 后可生成 DDD 后端", async (t) => {
+  const data = await fixture({ apiImpact: "required" });
+  t.after(() => rm(data.root, { recursive: true, force: true }));
+  const result = await command(data.args);
+  assert.equal(result.code, 0, result.stderr);
+  const manifest = JSON.parse(await readFile(path.join(data.output, "demo-service", ".yss/scaffold-generation.json"), "utf8"));
+  assert.equal(manifest.design_prerequisites.api_contract_decision.impact, "required");
+});
+
+test("缺少设计门禁时在写文件前拒绝 DDD 新生成", async (t) => {
+  const data = await fixture();
+  t.after(() => rm(data.root, { recursive: true, force: true }));
+  delete data.contract.design_prerequisites;
+  await writeFile(data.contractFile, `${JSON.stringify(data.contract, null, 2)}\n`);
+  const result = await command(data.args);
+  assert.equal(result.code, 1);
+  assert.match(result.stderr, /design_prerequisites|Technical Design/);
+  assert.equal(existsSync(path.join(data.output, "demo-service")), false);
+});
+
+test("技术和数据设计齐全但缺少 API Decision 时在写文件前拒绝 DDD 新生成", async (t) => {
+  const data = await fixture();
+  t.after(() => rm(data.root, { recursive: true, force: true }));
+  delete data.contract.design_prerequisites.api_contract_decision;
+  await writeFile(data.contractFile, `${JSON.stringify(data.contract, null, 2)}\n`);
+  const result = await command(data.args);
+  assert.equal(result.code, 1);
+  assert.match(result.stderr, /API Contract Decision|api_contract_decision/);
+  assert.equal(existsSync(path.join(data.output, "demo-service")), false);
+});
+
+test("API Draft、Validation、Review 或工程批准漂移时均在零写入状态阻断 DDD", async (t) => {
+  const mutations = [
+    ["OpenAPI YAML 摘要漂移", async (data) => writeFile(data.design.openapi.file, "\n# drift\n", { flag: "a" })],
+    ["Redocly Validation 失败", async (data) => {
+      const decision = JSON.parse(await readFile(data.design.api.file, "utf8"));
+      const validationFile = path.join(data.root, decision.validation_record.ref);
+      const validation = JSON.parse(await readFile(validationFile, "utf8"));
+      validation.status = "blocked";
+      validation.toolchain.exit_code = 1;
+      validation.checks.lint = "blocked";
+      await writeFile(validationFile, `${JSON.stringify(validation, null, 2)}\n`);
+      decision.validation_record.digest = `sha256:${createHash("sha256").update(await readFile(validationFile)).digest("hex")}`;
+      await writeFile(data.design.api.file, `${JSON.stringify(decision, null, 2)}\n`);
+      data.contract.design_prerequisites.api_contract_decision.digest = `sha256:${createHash("sha256").update(await readFile(data.design.api.file)).digest("hex")}`;
+      await writeFile(data.contractFile, `${JSON.stringify(data.contract, null, 2)}\n`);
+    }],
+    ["Draft Review blocked", async (data) => {
+      const decision = JSON.parse(await readFile(data.design.api.file, "utf8"));
+      const reviewFile = path.join(data.root, decision.draft_review.ref);
+      const review = JSON.parse(await readFile(reviewFile, "utf8"));
+      review.result = "blocked";
+      review.blocking_findings = ["breaking response"];
+      await writeFile(reviewFile, `${JSON.stringify(review, null, 2)}\n`);
+      decision.draft_review.digest = `sha256:${createHash("sha256").update(await readFile(reviewFile)).digest("hex")}`;
+      await writeFile(data.design.api.file, `${JSON.stringify(decision, null, 2)}\n`);
+      data.contract.design_prerequisites.api_contract_decision.digest = `sha256:${createHash("sha256").update(await readFile(data.design.api.file)).digest("hex")}`;
+      await writeFile(data.contractFile, `${JSON.stringify(data.contract, null, 2)}\n`);
+    }],
+    ["工程批准未绑定 API Decision", async (data) => {
+      const approval = JSON.parse(await readFile(data.design.approval.file, "utf8"));
+      approval.artifact_bindings = approval.artifact_bindings.filter((item) => !item.id.startsWith("api-contract."));
+      await writeFile(data.design.approval.file, `${JSON.stringify(approval, null, 2)}\n`);
+    }],
+  ];
+  for (const [name, mutate] of mutations) {
+    const data = await fixture({ apiImpact: "required" });
+    t.after(() => rm(data.root, { recursive: true, force: true }));
+    await mutate(data);
+    const result = await command(data.args);
+    assert.equal(result.code, 1, `${name}: ${result.stderr}`);
+    assert.equal(existsSync(path.join(data.output, "demo-service")), false, name);
+  }
+});
+
+test("schema v3 只读兼容但禁止用于 DDD 新生成", async (t) => {
+  const data = await fixture({ schema_version: 3, current_version: 1 });
+  t.after(() => rm(data.root, { recursive: true, force: true }));
+  const result = await command(data.args);
+  assert.equal(result.code, 1);
+  assert.match(result.stderr, /只接受 Project Scaffold Contract v4|新生成/);
+  assert.equal(existsSync(path.join(data.output, "demo-service")), false);
 });
 
 test("schema v1 scaffold contract is unsupported and is never upgraded", async (t) => {
@@ -154,7 +250,7 @@ test("schema v1 scaffold contract is unsupported and is never upgraded", async (
   t.after(() => rm(data.root, { recursive: true, force: true }));
   const result = await command(data.args);
   assert.equal(result.code, 1);
-  assert.match(result.stderr, /unsupported: scaffold contract schema_version=1/);
+  assert.match(result.stderr, /只接受 Project Scaffold Contract v4/);
   assert.equal(existsSync(path.join(data.output, "demo-service")), false);
 });
 
@@ -395,11 +491,11 @@ test("验证器单独标记 Java 编译失败和 Bootstrap 主类缺失", async
 
 test("验证器在全部 Maven 命令成功时通过并保留日志引用", async (t) => { const root = await mkdtemp(path.join(os.tmpdir(), "yss-scaffold-verifier-success-")); t.after(() => rm(root, { recursive: true, force: true })); const project = path.join(root, "project"); await prepareVerifierProject(project); const wrapper = path.join(project, "mvnw"); await writeFile(wrapper, "#!/bin/sh\nprintf 'ran %s\\n' \"$1\"\n"); await chmod(wrapper, 0o755); const report = await run(project, path.join(root, "evidence"), controlledEnvironment); assert.equal(report.status, "passed"); assert.ok(report.commands.every((item) => item.exit_code === 0 && item.stdout_ref.endsWith(".stdout.log"))); });
 
-test("Manifest v3 在缺少受控仓库环境时先于 Maven 执行阻断", async (t) => {
+test("历史 Manifest v3 只读校验仍在缺少受控仓库环境时先于 Maven 阻断", async (t) => {
   const root = await mkdtemp(path.join(os.tmpdir(), "yss-scaffold-v2-preflight-"));
   t.after(() => rm(root, { recursive: true, force: true }));
   const project = path.join(root, "project");
-  await prepareVerifierProject(project);
+  await prepareVerifierProject(project, targetManifest({ schema_version: 3, current_version: 1, design_prerequisites: undefined }));
   const wrapper = path.join(project, "mvnw");
   await writeFile(wrapper, "#!/bin/sh\nprintf 'must not run'\nexit 99\n");
   await chmod(wrapper, 0o755);

package/template/.codex/skills/yss-design-system/SKILL.md

@@ -14,9 +14,9 @@ description: Use when YSS 产品设计系统与 Ant Design 企业级 UI 风格
 - 项目 Token 快照：`docs/design/tokens/theme.json`、`docs/design/tokens/tokens.default.json`、`docs/design/tokens/tokens.dark.json`、`docs/design/tokens/tokens.compact.json`、`docs/design/tokens/variables.css`、`docs/design/tokens/variables.dark.css`；它们是派生实现视图，不得反向覆盖规范源。
 - 本技能执行清单：`references/design-system.md`，用于 Agent 执行和评审，不替代 `docs/design/design.md`。
 - 历史输入包：`/Users/zhudaoming/Downloads/Product-Design-System`，只用于追溯首次引入来源，不作为后续工程依赖。
-- 默认亮色覆盖：项目 Ant Design 5 Less / `:root` 变量已裁定进 `docs/design/design.md` 与 token 快照；原始 Less 不是实现语言。
+- 默认主题来源：Data Quality 主题经项目适配后落到根 `DESIGN.md`；来源与 AntD v6 设计参考 / Vue 运行时的区别见 `references/data-quality-theme.md`。
 - Codex `$design-qa` 项目对照：`references/design-qa-theme.md`，不替代官方 `design-qa` 流程，也不改上游插件正文。
-- 原型阶段合同：`yss-prototype-stage`，用于统一 H1/H2 原型资产和浏览器验证证据。H2 默认由 `yss-antdv-next-design` 提供 Vue/Antdv Next 事实；显式 React 兼容路线由 `yss-antd-design` 提供事实。
+- 原型阶段合同：`yss-prototype-stage`，用于统一 H1/H2 原型资产和浏览器验证证据。H1/H2 默认使用项目 Token 驱动的 HTML/CSS/JavaScript 离线原型。
 
 如果只需要快速判断，先读本文件。若要写 UI 规范、实现页面、评审设计或调整 Token，必须按 `DESIGN.md` → `docs/design/design.md` → `docs/design/tokens/*` 顺序读取；若要执行评审或实现检查，再读 `references/design-system.md`。
 
@@ -25,8 +25,8 @@ description: Use when YSS 产品设计系统与 Ant Design 企业级 UI 风格
 1. 先判断任务阶段：设计系统引入 / 产品设计 / 原型评审 / 前端实现 / UI 改造 / 主题 token 落地。
 2. 读取已有资产：先读根 `DESIGN.md`，再读 `docs/design/design.md` 和 Token 派生快照，最后按任务读取相关 Spec、交互说明、状态矩阵、OpenAPI Draft、现有页面代码。
 3. 按设计系统基线约束输出或修改产物：颜色、排版、间距、圆角、动效、组件、状态、响应式。
-4. 若是产品设计阶段，先使用 `yss-prototype-stage`；Codex 以 `product-design:index` 为主入口，其他 Agent 必须交付等价合同资产和证据。
-5. 若是前端实现阶段，配合 `yss-ui`、`yss-ui-business-page-generation`、`yss-components`、`yss-formily`，但本技能负责风格与体验一致性门禁。
+4. 若是产品设计阶段，先使用 `yss-prototype-stage`；规范直出由 YSS HTML adapter 执行；存在已选视觉稿时条件使用 `product-design:index`，其他 Agent 交付等价证据。
+5. 若是前端实现阶段，配合 `yss-ui`、`yss-ui-business-page-generation`、`component-selection-imports`、`yss-formily` 及实际命中的组件专项，但本技能负责风格与体验一致性门禁。
 6. 若发现视觉 Token 或组件变体不足，先更新根 `DESIGN.md` 并重新生成投影；只有治理、流程或验收说明不足时才更新 `docs/design/design.md`。
 
 ## 核心基线
@@ -34,14 +34,14 @@ description: Use when YSS 产品设计系统与 Ant Design 企业级 UI 风格
 - UI 定位：中后台、数据密集、表单密集、流程密集、可扫描、低装饰。
 - 颜色：使用 `DESIGN.md` 的 `colors.*`；品牌 seed 与高对比主控件变体是不同角色，不得用 seed 绕过 `components.button-primary*`。
 - 排版：使用 `DESIGN.md` 的 `typography.*`，状态不能只靠字重表达。
-- 密度：使用 `DESIGN.md` 的组件高度与 `spacing.*`；默认工作界面只应用一次 compact algorithm，不手工二次压缩。
+- 密度：使用 `DESIGN.md` 的组件高度与 `spacing.*`；默认采用 Data Quality 浅色、32px 控件；仅显式紧凑模式应用一次 compact algorithm，不手工二次压缩。
 - 圆角：使用 `rounded.*`，控件、容器和 pill 角色不得用页面级 magic number 替代。
 - 运行时换肤：短名 CSS 变量必须指向 `--brand-*`，不要再维护第二套色值。
 - 表面层级：页面背景、内容容器、浮层三层模型。
 - 组件语言：优先 Ant Design / YSS UI 语义，不自造同类控件。
 - 状态完整性：loading、empty、error、readonly、disabled、no-permission、conflict、success 必须在设计或实现中可解释。
-- 原型基线：先用项目语义 token 定义角色，再用组件 token 或 CSS variables 落地；不以局部硬编码替代主题层。H2 默认 Vue/Antdv Next 只消费精确版本且 digest 新鲜的 fact pack；React AntD 只用于显式兼容路线。
-- 档位版本边界：H1 只依赖项目 Token；H2 Vue/Antdv Next 默认路线与 React AntD 兼容路线分别精确锁版本。两条原型路线都不改变生产实现边界；生产 API 只在实现阶段从目标仓 lockfile 读取 Vue 3 + YSS UI + AntDV 事实。
+- 原型基线：先用项目语义 token 定义角色，再用组件 token 或 CSS variables 落地；不以局部硬编码替代主题层。H1/H2 都使用包内 CSS Token；生成后复核实际计算样式，并保存根规范和 Token 摘要。
+- 档位边界：H1 视觉评审，H2 流程评审；低保真是二者前置资产。原型组件 Provider 已退役，生产 API 仍只在实现阶段从目标仓 lockfile 读取 Vue 3 + YSS UI + AntDV 事实。
 
 ## 强制规则
 
@@ -52,8 +52,8 @@ description: Use when YSS 产品设计系统与 Ant Design 企业级 UI 风格
 - 不硬编码表面色、边框色、状态色；优先使用 token 或主题变量。
 - 交互原型中的每个可点击主动作都必须给出 interaction feedback：状态变化、禁用原因、成功或失败反馈至少覆盖其一。
 - accessibility：品牌 Seed 保持 `colors.primary`；实际文字/背景组合不满足 WCAG 2.2 AA 时，优先使用 `components.*` 中的高对比变体或 `ConfigProvider` component token 调整，并验证 default/hover/active/disabled/focus、键盘焦点、200% zoom、reduced motion 与目标尺寸，不新增页面级特例色。
-- Antdv Next 默认路线与 React Ant Design 兼容路线的暗色或紧凑密度必须使用各自精确版本支持的 theme algorithm；基础 seed 和 compact 结果均从规范源/派生快照读取，不手工反转颜色、逐控件压缩或重复 compact。
-- 不依赖 Ant Design v6 / Antdv Next 的内部 DOM、生成类名或未记录 API；只使用公开 API、semantic token 与项目主题变量。
+- 离线原型直接消费所选主题的派生值；默认使用 default 快照，显式紧凑模式才使用 compact 快照，避免重复 compact。生产组件库的主题算法由其实现合同约束；暗色启用前必须核验当前派生 Token 与浏览器截图。
+- 原型使用语义 HTML、项目主题变量与当前行为合同；生产实现不得依赖组件库内部 DOM、生成类名或未记录 API。
 - 不用 Tag 表达关键错误、阻断或审批状态；关键状态必须有可读文本和语义反馈。
 - 不让按钮、标签、表头、弹窗、卡片中的文字溢出或遮挡。
 - 不在表格 / 筛选 / 批量操作密集页面使用松散营销式布局。
@@ -62,7 +62,7 @@ description: Use when YSS 产品设计系统与 Ant Design 企业级 UI 风格
 
 设计类任务至少输出：
 
-- 设计系统引用：明确引用 `docs/design/design.md`。
+- 设计系统引用：明确引用根 `DESIGN.md`、治理说明 `docs/design/design.md` 和所选主题的 Token 快照；原型证据记录规范与 Token 摘要。
 - 页面和模块：页面清单、布局结构、主路径、异常路径。
 - 组件选择：YSS UI / Ant Design 组件映射。
 - 状态矩阵：加载、空、错、禁用、只读、无权限、冲突、成功。
@@ -73,7 +73,7 @@ description: Use when YSS 产品设计系统与 Ant Design 企业级 UI 风格
 
 - 是否通过 `ConfigProvider`、CSS variables 或项目 token 消费主题。
 - 是否将颜色、圆角、阴影和状态样式绑定到 semantic token，而不是复制表面色和交互色。
-- 是否使用当前 `DESIGN.md` 和 compact 派生快照中的控件、排版与间距值，且没有重复 compact。
+- 是否使用当前 `DESIGN.md` 和所选主题派生快照中的控件、排版与间距值；默认使用 default，仅显式紧凑模式使用 compact，且没有重复 compact。
 - 是否使用 YSS UI / Ant Design 的语义组件，而不是自造同类组件。
 - 是否保留 hover、focus、active、disabled、loading、error、empty 状态。
 - 是否为可提交、导出、保存、发布、审批等操作提供明确的 interaction feedback 与不可逆操作确认。
@@ -83,17 +83,15 @@ description: Use when YSS 产品设计系统与 Ant Design 企业级 UI 风格
 
 | 场景 | 配合技能 |
 | --- | --- |
-| Spec 后做页面 / 原型 / 交互说明 | `yss-prototype-stage` → `product-design:index` |
+| Spec 后做页面 / 原型 / 交互说明 | `yss-prototype-stage`；需要独立视觉稿时条件使用 `product-design:index` |
 | 低保真原型进入高保真前评审 | `prototype-review` |
 | 低保真评审后的原型交付物 | `yss-prototype-stage` 选择 H1/H2；`high-fidelity-html-prototype` 仅只读迁移 |
-| 低保真线框或流程图 | `product-design:index` |
+| 低保真线框或流程图 | 语义草图或 HTML；设计工具按需使用 |
 | 前端页面实现 | `yss-ui` / `yss-ui-business-page-generation` |
 | 表单 schema | `yss-formily` |
-| YTable / YTree / 高度自适应 | `yss-components` / `yss-use-table-height` / `yss-use-tree-height` |
-| H2 Vue/Antdv Next 默认原型的组件 / token / demo 查询 | `yss-antdv-next-design`（精确版本 fact pack，不用于 H1） |
-| H2 React/AntD 显式兼容原型的组件 / token / demo 查询 | `yss-antd-design`（fact pack 优先，不用于 H1） |
-| Codex 原型交接前的视觉 QA | `design-qa`；token / 字体对照读 `references/design-qa-theme.md`，以项目覆盖为准 |
-| 原型渲染适配 | `yss-prototype-stage/references/product-design-adapter.md`；H1 静态、H2 可运行流程；不得调用 `yss-ui` |
+| YTable / YTree / 高度自适应 | `ytable-usage` / `ytree-usage` / `yss-use-table-height` / `yss-use-tree-height` |
+| 原型交接前的六轴 QA | 规范直出由 YSS adapter 按 design-contract 验收；独立视觉稿才条件使用 design-qa 比对，项目 Token 优先 |
+| 原型渲染适配 | `yss-prototype-stage/references/product-design-adapter.md`；H1/H2 统一 HTML 交付、分别验证视觉与可操作流程；不得调用 `yss-ui` |
 | API 契约 / 接入 | `yss-openapi-governance` / `yss-api-integration` |
 
 ## 更新设计系统
@@ -102,7 +100,9 @@ description: Use when YSS 产品设计系统与 Ant Design 企业级 UI 风格
 
 1. 分析来源设计系统，不原样堆拷贝。
 2. 将稳定视觉 Token 与组件变体先落到根 `DESIGN.md`；治理、流程和验收说明再落到 `docs/design/design.md`。
-3. 运行 `node .template-source/tooling/node/scripts/design-md.mjs export dtcg --write --write-manifest` 更新派生视图，并更新 `docs/design/design-system-sync.yaml` 的规范源摘要。
+3. 运行 `node .template-source/tooling/node/scripts/design-md.mjs export dtcg --write --write-manifest --antd-toolchain <固定antd6.6.4作者目录>` 更新派生视图；运行前先更新 `docs/design/design-system-sync.yaml` 的规范源摘要。
 4. 将 Agent 执行入口落到 `.agents/skills/yss-design-system/SKILL.md`，执行清单落到 `references/design-system.md`；两者只引用 Token 名和角色，不复制具体值。
 5. 更新 `docs/design/README.md` 和必要的 `AGENTS.md` 入口规则。
 6. 运行 frontmatter、对应 `node --test`、`design-md lint/drift`、技能投影与 lock 校验。
+
+默认主题事实见 `references/data-quality-theme.md`；运行时 Ant Design Vue 4 与 AntD v6 设计参考分别记录。

package/template/.codex/skills/yss-design-system/references/data-quality-theme.md

@@ -0,0 +1,13 @@
+# Data Quality 默认主题
+
+根 `DESIGN.md` 是唯一视觉事实源。此参考解释采用依据，不定义第二份主题。
+
+采用 Data Quality `packages/src/store/theme.ts` 的全局浅色主题：主色 / info `#3371ff`，正文14px，默认 / small / large控件32 / 24 / 40px，圆角6 / 4 / 8px，Card内距20px。`isDarkMode=false`、`isCompactMode=false`。页面玻璃效果、广大发行主题与人保红色 JSP 主题均为局部选择。
+
+Ant Design v6 提供设计语义与 HTML 原型算法参考；Data Quality 真实运行时为 Vue3 + ant-design-vue4.2.6 + YSS UI。实现主题通过目标库公开 ConfigProvider API 适配，不能把 React API 或 v6版本号移植为 Vue 依赖结论。
+
+`primary-control` / hover 是 YSS 为白色小字保留的可访问性变体，品牌 seed 保持 Data Quality 蓝；它们是已声明适配，不是 Data Quality 原值。默认32px，显式 compact28px，seed不得以28px再次压缩。暗色使用算法生成中性色，不能把浅色 text/surface 固定覆盖带入暗色。
+
+更新顺序：修改根 DESIGN.md → 更新 design-system-sync.yaml 摘要 → 在独立作者目录提供固定 antd6.6.4 → `node .template-source/tooling/node/scripts/design-md.mjs export dtcg --write --write-manifest --antd-toolchain <作者目录>` → lint / drift → 刷新 frontend scaffold baseline → 浏览器核对 HTML 和 Vue 两条实现。禁止手改 token 快照或生成投影。
+
+采集依据：Data Quality commit `532509a59856fc02f3b9bcb28a062663ce887d71`；theme.ts SHA256 `8bdb5d13a0dabccc0771bac07d6e28e29d23dcc70fc72adfe04825b5a5ae16e1`。详细研究位于模板维护证据 `data-quality-theme-scaffold-2026-09-15/`。

package/template/.codex/skills/yss-design-system/references/design-qa-theme.md

@@ -7,6 +7,7 @@
 - 规范：根 `DESIGN.md`
 - 治理说明：`docs/design/design.md`
 - Token 投影：`docs/design/tokens/theme.json`、`docs/design/tokens/tokens.default.json`、`docs/design/tokens/variables.css`
+- 主题选择：默认采用根 `DESIGN.md` 的 Data Quality 浅色主题；仅显式暗色 / 紧凑模式使用对应的 `tokens.dark.json` / `variables.dark.css` / `tokens.compact.json`，以实际消费文件记录摘要。
 - 实现截图：当前原型或页面在同一 viewport / 主题 / 状态下的渲染
 
 官方 `https://ant.design/design.md` 只是上游默认。项目覆盖与官方不同时，以根 `DESIGN.md` 为准；本清单不复制规范值。
@@ -51,12 +52,13 @@
 
 - 使用上游默认、历史品牌值或未登记字体/圆角覆盖根 `DESIGN.md`：P1。
 - 只改局部组件、且 `prototype-evidence.yaml` 的 `theme_override` 已记录：按官方 severity 评估，不自动升 P1。
-- 暗色模式：本轮未重派生完整暗色色板；暗色对照前若缺少新的 algorithm 派生证据，`final result: blocked`，写明 blocker。
+- 暗色模式：核验派生记录与当前根规范摘要一致，并取得相同 viewport / 主题 / 状态的实际浏览器证据；缺失或漂移时 `final result: blocked`，写明 blocker。历史暗色验证不能代替当前原型或页面的验收。
 
 ## 报告要求
 
 `design-qa.md` 必须写明：
 
 - source visual truth path：根 `DESIGN.md`、治理说明与对应 Token 投影文件
+- 原型证据中 `design_baseline` 的规范与 Token 摘要，以及视觉基线 `cases[].theme` 和截图对应关系
 - 已按本清单核对 Colors/tokens 与 Fonts/typography
 - 与官方默认的差异是否被接受为项目覆盖

package/template/.codex/skills/yss-design-system/references/design-system.md

@@ -88,7 +88,7 @@
 执行规则：
 
 - 间距只使用 `spacing.*`，不要补写未登记的中间值。
-- 默认工作界面叠加一次 compact algorithm；seed 与计算结果从规范源和派生快照读取，不得二次 compact。
+- 默认采用 Data Quality 浅色、32px 控件；仅显式紧凑模式叠加一次 compact algorithm；seed 与计算结果从规范源和派生快照读取，不得二次 compact。
 - 表单、筛选区、工具栏、表格、详情页使用密集但有节奏的布局。
 - 控件圆角不得明显大于容器圆角。
 - 不使用任意 magic number；确需新增尺寸时，先说明为什么 token 不够。
@@ -182,18 +182,16 @@
 React + Ant Design：
 
 - 使用 `ConfigProvider` 注入主题。
-- 默认工作界面使用 `theme.compactAlgorithm`；暗色紧凑模式组合 `theme.darkAlgorithm` 与 `theme.compactAlgorithm`，不手工反转色值或逐组件压缩。
-- seed 与 compact 计算值以 `DESIGN.md` / `tokens.compact.json` 为准；不要重复 compact。
+- 默认采用 Data Quality 浅色与 32px 控件；仅显式紧凑模式使用 `theme.compactAlgorithm`；暗色紧凑模式组合 `theme.darkAlgorithm` 与 `theme.compactAlgorithm`，不手工反转色值或逐组件压缩。
+- seed 与所选主题计算值以 `DESIGN.md` 和对应快照为准；默认使用 `tokens.default.json`，显式紧凑模式才使用 `tokens.compact.json`，不要重复 compact。
 - 优先通过 token、component token、CSS variables、theme algorithm 实现样式。
 - 静态反馈 API 使用 `App`、hook API 或 context holder，避免主题上下文丢失。
 - 暗色模式使用 `darkAlgorithm` 或 `variables.dark.css`。
 - 紧凑模式使用 `compactAlgorithm` 或 `tokens.compact.json`。
 
-实验 Vue + Antdv Next：
+HTML 原型：
 
-- H2 默认先使用 `yss-antdv-next-design` 校验精确版本 fact pack、组件集合与项目 baseline digest。
-- 共享本规范的 semantic token、紧凑密度和验收语义；props、events、slots 与主题 API 只从 Antdv Next fact pack 读取。
-- `yss-antd-design` 只保留为显式 React/AntD 兼容路线；默认 Provider 与兼容 Provider 都不替换生产 `yss-ui` 路线。
+- 使用 `yss-prototype-stage` 的 HTML/CSS/JavaScript adapter，消费项目 semantic token、所选密度和状态合同；生产组件 API 只在下游实现阶段从目标仓实际依赖核验。
 
 YSS UI / Vue：
 
@@ -207,7 +205,7 @@ YSS UI / Vue：
 
 设计评审时检查：
 
-- 是否引用 `docs/design/design.md`。
+- 是否引用根 `DESIGN.md`、治理说明 `docs/design/design.md` 与所选主题快照，并在原型证据中记录摘要。
 - 是否符合中后台定位。
 - 页面清单、主路径、异常路径是否清楚。
 - 状态矩阵是否完整。
@@ -220,7 +218,7 @@ YSS UI / Vue：
 
 - 是否消费 token，而不是硬编码颜色和尺寸。
 - 是否以 semantic token 表达颜色、圆角、阴影和状态层级。
-- 是否使用当前 `DESIGN.md` 与 `tokens.compact.json` 的排版、控件和间距值，且没有重复 compact。
+- 是否使用当前 `DESIGN.md` 与所选主题快照的排版、控件和间距值；默认使用 default，仅显式紧凑模式使用 compact，且没有重复 compact。
 - 是否保留 hover、focus、active、disabled、loading、empty、error 状态。
 - 是否只保留一个 single primary action，并让每个关键操作提供 interaction feedback。
 - 是否在目标字号和背景下复核 accessibility contrast。

package/template/.codex/skills/yss-distributed-id/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yss-distributed-id
-description: Use when 用于 YSS 分布式 ID 组件的接入与排障。当用户提到 Leaf、CosId、号段模式、雪花算法、AutoIdInterceptor、MyBatis 自动注入 ID 或主键生成策略时调用。
+description: "接入或排查 YSS 分布式 ID：Leaf、CosId、号段、雪花算法或 MyBatis 主键注入。"
 ---
 
 # yss-distributed-id

package/template/.codex/skills/yss-dto/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yss-dto
-description: Use when YSS `Result`, `SingleResult`, `MultiResult`, `PageResult`, `PageQuery`, `CommandDTO`, `QueryDTO`, pagination, or response-wrapper boundaries are involved.
+description: "实现或核验 YSS Result、PageResult、PageQuery、CommandDTO、QueryDTO 及 wire 边界。"
 ---
 
 # yss-dto
@@ -91,3 +91,7 @@ description: Use when YSS `Result`, `SingleResult`, `MultiResult`, `PageResult`,
 - DTO/VO 必须消费冻结 OpenAPI/no-impact record 和批准合同，写入合同允许路径。
 - POJO 样板可 `controlled-generation`；校验、权限输入、错误结构和序列化行为必须由对应 `behavior-tdd` 工作单元覆盖。
 - 必须加载合同要求的 `lombok`、`mapstruct` 和 `alibaba-java-code-style`，并按统一 `YSS Skill Execution Result` 返回文件、契约测试和偏离。
+
+## 新脚手架平台约束
+
+消费批准切片架构身份中的 `platform_configuration`，与工程 Manifest 核对后使用对应 YSS 组件。Boot 2.7 使用 `javax` Web/Validation API；Boot 3.5/4.1 使用 `jakarta`。Boot 4 按 Jackson 3、对应自动配置和 starter 适配；不替换 `javax.sql` 等 Java SE 包。平台不一致、兼容条目缺失或候选未验证时回合同编译器阻断，不在业务实现中升级或替换组件。详见 仓库共享合同 `docs/engineering/backend-platforms.md`。

package/template/.codex/skills/yss-excel-mvc/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yss-excel-mvc
-description: Use when 用于 Spring MVC 下的 Excel 导入导出实现。当用户提到 RequestExcel、ResponseExcel、Excel 导入解析、Excel 下载、动态列导出或导入导出接口异常时调用。
+description: "实现或排查 YSS Spring MVC Excel 导入导出、RequestExcel、ResponseExcel 和动态列。"
 ---
 
 # yss-excel-mvc

package/template/.codex/skills/yss-exception/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yss-exception
-description: Use when 用于 YSS exception 组件、统一异常模型、异常处理、错误码和异常 starter 接入排障。
+description: "接入或排查 YSS 统一异常、错误码、异常处理器与 exception starter。"
 ---
 
 # yss-exception
@@ -56,3 +56,7 @@ Read `references/source-index.md` as a path-hint index whenever the task depends
 - Do not invent class names or configuration keys without checking the source index.
 - Do not replace component extension points with business-local framework code.
 - Do not broaden the task into unrelated YSS components unless the user asks.
+
+## 新脚手架平台约束
+
+消费批准切片架构身份中的 `platform_configuration`，与工程 Manifest 核对后使用对应 YSS 组件。Boot 2.7 使用 `javax` Web/Validation API；Boot 3.5/4.1 使用 `jakarta`。Boot 4 按 Jackson 3、对应自动配置和 starter 适配；不替换 `javax.sql` 等 Java SE 包。平台不一致、兼容条目缺失或候选未验证时回合同编译器阻断，不在业务实现中升级或替换组件。详见 仓库共享合同 `docs/engineering/backend-platforms.md`。