create-yss-spec 3.3.8 → 3.4.1

package/template/.pi/skills/yss-layered-mvc-scaffold-generator/scripts/scaffold-generator.test.mjs

@@ -7,6 +7,7 @@ import os from "node:os";
 import path from "node:path";
 import test from "node:test";
 import { fileURLToPath } from "node:url";
+import { attachDesignPrerequisites } from "../../../../scripts/fixtures/backend-scaffold/design-prerequisites.mjs";
 
 const script = path.join(path.dirname(fileURLToPath(import.meta.url)), "generate_scaffold.mjs");
 const digest = (value) => `sha256:${createHash("sha256").update(value).digest("hex")}`;
@@ -18,7 +19,7 @@ const capabilityModules = {
   combined: { capabilities: ["external-integration", "feign-client"], modules: ["server", "service", "repository", "adapter", "client", "feign-client"] }
 };
 
-async function fixture(t, { profile = capabilityModules.basic, architectureProfile = "layered-mvc-service", skillId = "yss-layered-mvc-scaffold-generator", schemaVersion = 3 } = {}) {
+async function fixture(t, { profile = capabilityModules.basic, architectureProfile = "layered-mvc-service", skillId = "yss-layered-mvc-scaffold-generator", schemaVersion = 4, dataImpact = "not-applicable", apiImpact = "not-applicable" } = {}) {
   const root = await mkdtemp(path.join(os.tmpdir(), "yss-layered-mvc-"));
   t.after(() => rm(root, { recursive: true, force: true }));
   const output = path.join(root, "backend");
@@ -33,7 +34,7 @@ async function fixture(t, { profile = capabilityModules.basic, architectureProfi
     schema_version: schemaVersion,
     kind: "project-scaffold-contract",
     delivery_role: "backend",
-    scaffold_kind: "backend-layered-mvc",
+    scaffold_kind: architectureProfile === "mvc-data-analysis-v1" ? "backend-mvc-data-analysis" : "backend-layered-mvc",
     repository_scope: "external-repository",
     init_git: false,
     contract_id: "scaffold.demo-service.v1",
@@ -43,7 +44,7 @@ async function fixture(t, { profile = capabilityModules.basic, architectureProfi
     compiler_draft_ref: "compiler://demo/1",
     lifecycle_approval_ref: "approval://demo/1",
     persisted_ref: "contract://demo/1",
-    current_version: 1,
+    current_version: schemaVersion === 4 ? true : 1,
     implementation_repository: "external",
     backend_repository: "external",
     scaffold_status: "required",
@@ -65,10 +66,11 @@ async function fixture(t, { profile = capabilityModules.basic, architectureProfi
     work_unit: { id: "scaffold.demo", behavior: "project-scaffold", primary_skill: skillId, supporting_skills: ["yss-implementation-contract-compiler"], tdd_mode: "controlled-generation", allowed_write_paths: ["."], expected_evidence: [".yss/scaffold-generation.json"], verification_commands: ["./mvnw validate", "./mvnw test", "./mvnw package"], controlled_generation: true },
     generation_policy: { mode: "initialize-only", existing_target: "unsupported", old_project_migration: "unsupported", template_upgrade: "unsupported" }
   };
+  const design = attachDesignPrerequisites(root, contract, { dataImpact, apiImpact });
   const contractFile = path.join(root, "contract.json");
   await writeFile(contractFile, `${JSON.stringify(contract, null, 2)}\n`);
   const args = ["--project-name", "demo-service", "--base-package", "com.yss.demo", "--output-dir", output, "--contract-file", contractFile, "--contract-id", contract.contract_id, "--contract-version", "1", "--approval-ref", contract.lifecycle_approval_ref, "--compiler-draft-ref", contract.compiler_draft_ref, "--persisted-ref", contract.persisted_ref, "--group-id", "com.yss.demo", "--project-version", "1.0.0-SNAPSHOT", "--parent-group-id", "com.yss.cloud", "--parent-artifact-id", "yss-cloud-microservice", "--parent-version", "2.0.0-SNAPSHOT", "--yss-components-version", "2.0.0-SNAPSHOT"];
-  return { root, output, decisionFile, contractFile, contract, args, project: path.join(output, "demo-service") };
+  return { root, output, decisionFile, contractFile, contract, design, args, project: path.join(output, "demo-service") };
 }
 
 test("数据分析初始化生成 H2 六模块和独立治理信封", async (t) => {
@@ -102,14 +104,100 @@ test("旧数据库和 Mock 参数在写入前被拒绝", async (t) => {
   }
 });
 
-test("统一 Project Scaffold Contract v4 可生成 Layered MVC 后端并保留 v4 Manifest", async (t) => {
-  const data = await fixture(t, { schemaVersion: 4 });
-  data.contract.current_version = true;
-  await writeFile(data.contractFile, JSON.stringify(data.contract));
+test("统一 Project Scaffold Contract v4 可生成 Layered MVC 后端并保留设计门禁", async (t) => {
+  const data = await fixture(t);
   const result = spawnSync(process.execPath, [script, ...data.args], { encoding: "utf8" });
   assert.equal(result.status, 0, result.stderr);
   const manifest = JSON.parse(await readFile(path.join(data.project, ".yss/scaffold-generation.json"), "utf8"));
   assert.equal(manifest.schema_version, 4);
+  assert.equal(manifest.design_prerequisites.data_architecture_decision.impact, "not-applicable");
+});
+
+test("数据影响为 required 时绑定数据架构后可生成 Layered MVC 后端", async (t) => {
+  const data = await fixture(t, { dataImpact: "required" });
+  const result = spawnSync(process.execPath, [script, ...data.args], { encoding: "utf8" });
+  assert.equal(result.status, 0, result.stderr);
+  const manifest = JSON.parse(await readFile(path.join(data.project, ".yss/scaffold-generation.json"), "utf8"));
+  assert.equal(manifest.design_prerequisites.data_architecture_decision.impact, "required");
+});
+
+test("API 影响为 required 时绑定同字节 Draft、Validation、Review 和 Freeze 后可生成 Layered MVC 后端", async (t) => {
+  const data = await fixture(t, { apiImpact: "required" });
+  const result = spawnSync(process.execPath, [script, ...data.args], { encoding: "utf8" });
+  assert.equal(result.status, 0, result.stderr);
+  const manifest = JSON.parse(await readFile(path.join(data.project, ".yss/scaffold-generation.json"), "utf8"));
+  assert.equal(manifest.design_prerequisites.api_contract_decision.impact, "required");
+});
+
+test("缺少设计门禁时在写文件前拒绝 Layered MVC 新生成", async (t) => {
+  const data = await fixture(t);
+  delete data.contract.design_prerequisites;
+  await writeFile(data.contractFile, JSON.stringify(data.contract));
+  const result = spawnSync(process.execPath, [script, ...data.args], { encoding: "utf8" });
+  assert.notEqual(result.status, 0);
+  assert.match(result.stderr, /design_prerequisites|Technical Design/);
+  await assert.rejects(stat(data.project), { code: "ENOENT" });
+});
+
+test("技术和数据设计齐全但缺少 API Decision 时在写文件前拒绝 Layered MVC 新生成", async (t) => {
+  const data = await fixture(t);
+  delete data.contract.design_prerequisites.api_contract_decision;
+  await writeFile(data.contractFile, JSON.stringify(data.contract));
+  const result = spawnSync(process.execPath, [script, ...data.args], { encoding: "utf8" });
+  assert.notEqual(result.status, 0);
+  assert.match(result.stderr, /API Contract Decision|api_contract_decision/);
+  await assert.rejects(stat(data.project), { code: "ENOENT" });
+});
+
+test("API Draft、Validation、Review 或工程批准异常时均在零写入状态阻断 Layered MVC", async (t) => {
+  const mutations = [
+    async (data) => writeFile(data.design.openapi.file, "\n# drift\n", { flag: "a" }),
+    async (data) => {
+      const decision = JSON.parse(await readFile(data.design.api.file, "utf8"));
+      const file = path.join(data.root, decision.validation_record.ref);
+      const record = JSON.parse(await readFile(file, "utf8"));
+      record.status = "blocked";
+      record.toolchain.exit_code = 1;
+      record.checks.lint = "blocked";
+      await writeFile(file, `${JSON.stringify(record, null, 2)}\n`);
+      decision.validation_record.digest = digest(await readFile(file));
+      await writeFile(data.design.api.file, `${JSON.stringify(decision, null, 2)}\n`);
+      data.contract.design_prerequisites.api_contract_decision.digest = digest(await readFile(data.design.api.file));
+      await writeFile(data.contractFile, `${JSON.stringify(data.contract, null, 2)}\n`);
+    },
+    async (data) => {
+      const decision = JSON.parse(await readFile(data.design.api.file, "utf8"));
+      const file = path.join(data.root, decision.draft_review.ref);
+      const review = JSON.parse(await readFile(file, "utf8"));
+      review.result = "blocked";
+      review.blocking_findings = ["breaking response"];
+      await writeFile(file, `${JSON.stringify(review, null, 2)}\n`);
+      decision.draft_review.digest = digest(await readFile(file));
+      await writeFile(data.design.api.file, `${JSON.stringify(decision, null, 2)}\n`);
+      data.contract.design_prerequisites.api_contract_decision.digest = digest(await readFile(data.design.api.file));
+      await writeFile(data.contractFile, `${JSON.stringify(data.contract, null, 2)}\n`);
+    },
+    async (data) => {
+      const approval = JSON.parse(await readFile(data.design.approval.file, "utf8"));
+      approval.subject_ref = "approval://self-asserted";
+      await writeFile(data.design.approval.file, `${JSON.stringify(approval, null, 2)}\n`);
+    },
+  ];
+  for (const mutate of mutations) {
+    const data = await fixture(t, { apiImpact: "required" });
+    await mutate(data);
+    const result = spawnSync(process.execPath, [script, ...data.args], { encoding: "utf8" });
+    assert.notEqual(result.status, 0, result.stderr);
+    await assert.rejects(stat(data.project), { code: "ENOENT" });
+  }
+});
+
+test("schema v3 只读兼容但禁止用于 Layered MVC 新生成", async (t) => {
+  const data = await fixture(t, { schemaVersion: 3 });
+  const result = spawnSync(process.execPath, [script, ...data.args], { encoding: "utf8" });
+  assert.notEqual(result.status, 0);
+  assert.match(result.stderr, /Project Scaffold Contract v4|新生成/);
+  await assert.rejects(stat(data.project), { code: "ENOENT" });
 });
 
 test("可选离线 Maven 可行性检查（不替代受控仓库验收）", { skip: process.env.YSS_BACKEND_OFFLINE_PROBE !== "1" }, async (t) => {
@@ -129,7 +217,7 @@ for (const database of ["h2"]) {
     const result = spawnSync(process.execPath, [script, ...data.args], { encoding: "utf8" });
     assert.equal(result.status, 0, result.stderr);
     const manifest = JSON.parse(await readFile(path.join(data.project, ".yss/scaffold-generation.json"), "utf8"));
-    assert.equal(manifest.schema_version, 3);
+    assert.equal(manifest.schema_version, 4);
     assert.equal(manifest.architecture_family, "layered-mvc");
     assert.equal(manifest.profiles.verification_database, database);
     assert.equal(manifest.profiles.production_database, "not-bound");

package/template/.pi/skills/yss-mvc-data-analysis-project-initializer/SKILL.md

@@ -5,11 +5,11 @@ description: 在生命周期批准的初始化合同下创建独立 Git 管理
 
 # 数据分析 MVC 项目初始化
 
-这是 `work-unit.service-project-initialization` 的执行器，不是通用 MVC 脚手架。通用 MVC 使用 `yss-layered-mvc-scaffold-generator`；DDD 使用 `yss-ddd-scaffold-generator`。旧 `yss-mvc-scaffold-generator` 已退役且不提供自动别名。
+这是 `work-unit.service-project-initialization` 的执行器，不是通用 MVC 脚手架。通用 MVC 使用 `yss-layered-mvc-scaffold-generator`；DDD 使用 `yss-ddd-scaffold-generator`。历史数据分析初始化入口不提供自动别名，迁移关系只在 `docs/agents/skill-migrations.md` 记录。
 
 ## 执行合同
 
-- 必须有生命周期批准且当前的 schema v3 scaffold contract，绑定 `architecture_profile=mvc-data-analysis-v1`、本生成器及已批准的架构决策。
+- 必须有生命周期批准且当前的 schema v4 scaffold contract，绑定 `architecture_profile=mvc-data-analysis-v1`、本生成器、已批准的架构决策、Technical Design、Data Architecture Decision v1 和真实工程合同批准记录。
 - 固定 server/core/client/repository/adapter/feign-client；core 是薄应用层，规则见 `docs/agents/backend-architecture-profiles.md`。不生成业务接口、SQL、DDL、Mock、生产数据库配置或额外数据源。
 - `verification_database=h2` / `production_database=not-bound`；Java 8 / Boot 2.7 / javax。目标不存在，禁止覆盖、迁移、自动提交和推送。
 - 合同必须包含 `context_handoff_ref`、`context_handoff_digest`：批准交接的完整根 CONTEXT.md（含 schema frontmatter），不得用跨仓路径替代本仓词汇表。初始化只复制已确认内容，不创造业务术语；父项目只保留服务引用和 handoff 证据。

package/template/.pi/skills/yss-mvc-data-analysis-project-initializer/scripts/generate_project.mjs

@@ -71,7 +71,7 @@ export async function initialize(options) {
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
   try {
     const options = parseArgs(process.argv.slice(2));
-    if (options.help) process.stdout.write("使用批准的 MVC schema v3 合同与 Maven 坐标参数；输出独立数据分析项目，无数据库/Mock 选项。\n");
+    if (options.help) process.stdout.write("使用批准且绑定技术/数据设计的 MVC schema v4 合同与 Maven 坐标参数；输出独立数据分析项目，无数据库/Mock 选项。\n");
     else await initialize(options);
   } catch (error) { process.stderr.write(`数据分析项目初始化失败: ${error.message}\n`); process.exitCode = 1; }
 }

package/template/.pi/skills/yss-openapi-governance/SKILL.md

@@ -32,6 +32,7 @@ YSS DTO 的可复用 HTTP/JSON 映射由 `.agents/skills/yss-dto/references/open
 - 在 `docs/.scratch/<feature>/api/<feature>-validation.yaml` 持久化结构校验记录，并用 `scripts/verify-openapi-draft-validation-record` 复核当前 YAML SHA-256、锁定的 Redocly 版本、实际命令、退出码、执行时间和证据引用。
 - 在 OpenAPI Freeze 后，用锁定的 Redocly CLI 将 YAML bundle 为 JSON，并记录可重现证据。
 - 维护治理记录、Freeze 记录和 JSON 派生记录。
+- 在技术分析中生成 `api-contract-decision-v1`：有 API 影响时以原始字节摘要闭包绑定权威 YAML、Validation、独立 Draft Review 和 Freeze；无 API 影响时绑定影响评估、明确原因和至少一项可读证据，且不得生成空占位资产。
 - Spec Delta 影响存在时，在 `docs/.scratch/<feature>/spec-delta/` 记录与冻结 YAML 的关系；没有影响时明确记录 `not-applicable`。
 
 不使用本 skill 来替代：
@@ -80,6 +81,7 @@ pnpm exec redocly bundle \
    - 将通过 verifier 且 SHA-256 与当前 YAML 一致的 validation record 交给 `yss-openapi-draft-review`。缺锁定 lint 时可以先做语义预审，但独立 Review 总结果必须为 `Blocked`；不能用“Freeze 前补 lint”支持 `Approved`。
    - YAML、validation record 或 lint ruleset 变化后，旧结构证据与旧 Review 立即失效，必须重新校验和审查。阻断项未关闭前，YAML 仍是 review-only Draft，不得生成生产客户端。
    - Freeze 记录必须引用 YAML 路径、Git ref（如适用）和 YAML SHA-256。冻结后 API 行为变更必须先回到 YAML Draft 与审查。
+   - 将同一 YAML 的版本与摘要、validation record、独立 Review 和 Freeze 写入 API Contract Decision v1。`gate.engineering-contract-approved` 一次批准同时绑定 Technical Design、Data Architecture Decision、API Contract Decision；API `required` 时还必须直接绑定冻结 YAML。不得另造字符串 URI 或仅凭 `status: approved` 关闭门禁。
 
 4. **从冻结 YAML 派生 JSON**
    - 使用上面的锁定 `redocly bundle` 命令生成 `docs/.scratch/<feature>/api/<feature>.json`，JSON 不纳入人工编辑面。

package/template/.pi/skills/yss-product-lifecycle/references/orchestration-contract.yaml

@@ -28,7 +28,7 @@ service_project_initialization:
   skill: yss-mvc-data-analysis-project-initializer
   architecture_profile: mvc-data-analysis-v1
   context_inputs: [context_handoff_ref, context_handoff_digest]
-  approval: current-schema-v3-scaffold-contract-and-user-confirmed-architecture
+  approval: current-schema-v4-scaffold-contract-with-approved-technical-and-data-design
   parent_ownership: service-references-and-handoff-only
   child_ownership: independent-git-project-instance-root-context-and-lifecycle
 supported_state_schema_versions: [1]
@@ -299,7 +299,7 @@ skill_source_contract:
   lock_version: 3
   source_revisions_required: [mattpocock/skills, iloveZzz/yss-ui]
   adaptation_ref_required_when_effective_diff: true
-  retired_shared_skills: [ask-matt, batch-grill-me, dispatching-parallel-agents, loop-me, migrate-to-shoehorn, product-design-prototype, prototype-page-acceptance, scaffold-exercises, setup-pre-commit, setup-ts-deep-modules, teach, writing-beats, writing-fragments, writing-shape, yss-dictionary, yss-jdbc, yss-log, yss-microapp-commit, yss-page-module-development, yss-taskflow, yss-backend-scaffold-application, yss-backend-scaffold-domain, yss-backend-scaffold-infrastructure, yss-backend-scaffold-web]
+  retired_shared_skills: [yss-antd-design, yss-antdv-next-design, ask-matt, batch-grill-me, dispatching-parallel-agents, loop-me, migrate-to-shoehorn, product-design-prototype, prototype-page-acceptance, scaffold-exercises, setup-pre-commit, setup-ts-deep-modules, teach, writing-beats, writing-fragments, writing-shape, yss-components, yss-dictionary, yss-jdbc, yss-log, yss-microapp-commit, yss-mvc-scaffold-generator, yss-page-module-development, yss-taskflow, yss-backend-scaffold-application, yss-backend-scaffold-domain, yss-backend-scaffold-infrastructure, yss-backend-scaffold-web, yss-backend-scaffold-adapter, yss-application-layer-reference, yss-domain-layer-reference, yss-infrastructure-layer-reference, yss-web-layer-reference]
 
 # 生命周期默认走原生工作单元；Matt user-invoked skill 仅保留为兼容入口。
 lifecycle_native_entries:
@@ -357,8 +357,8 @@ work_unit_routes:
   work-unit.prototype-design:
     native: {source: yss-product-lifecycle, skill: yss-product-lifecycle, invocation_mode: model-invoked}
     primary_skill: yss-prototype-stage
-    supporting_skills: [prototype-review, yss-design-system, product-design:index, yss-antdv-next-design, yss-antd-design]
-    skills: [prototype-review, yss-design-system, yss-prototype-stage, product-design:index, yss-antdv-next-design, yss-antd-design]
+    supporting_skills: [prototype-review, yss-design-system, product-design:index]
+    skills: [prototype-review, yss-design-system, yss-prototype-stage, product-design:index]
     execution_order: [yss-design-system, low-fidelity-assets, prototype-review, prototype-profile-routing, profile-adapter-build, browser-design-qa-accessibility, user-confirmation]
     profile_routing_ref: .agents/skills/yss-prototype-stage/references/prototype-profile-routing.md
     prototype_adapter_ref: .agents/skills/yss-prototype-stage/references/product-design-adapter.md
@@ -370,7 +370,7 @@ work_unit_routes:
         H1: {kind: visual-review, adapter: static-html, node_runtime_required: false, antd_facts: not-applicable}
         H2: {kind: flow-review, adapter: runnable-flow, react_antd: supported-not-required, antd_facts: conditional}
     implementation_handoff: {production_component_assumptions: required-array, verification_targets: frontend-implementation-only}
-    version_boundary: {h2_design_standard: vue-antdv-next-default-react-antd-explicit-compatibility, prototype_must_not_call: yss-ui, production_version_source: implementation-lockfile}
+    version_boundary: {h2_design_standard: html-css-js-offline, prototype_must_not_call: yss-ui, production_version_source: implementation-lockfile}
     human_gate: gate.product-design-approved
     applies_when: product_design_impact
     not_applicable_reason: no_ui_or_product_design_impact
@@ -380,7 +380,8 @@ work_unit_routes:
     supporting_skills: [yss-openapi-governance, yss-openapi-draft-review, codebase-design, implementation-repo-onboarding, yss-implementation-contract-compiler]
     skills: [yss-technical-design, yss-openapi-governance, yss-openapi-draft-review, codebase-design, implementation-repo-onboarding, yss-implementation-contract-compiler]
     technical_design:
-      applies_when: backend_technical_design_impact
+      applies_when: backend_delivery_impact
+      new_backend_repository: required
       architecture_source: confirmed-project-architecture-before-branch-design
       branches:
         domain-driven: yss-tactical-design
@@ -393,6 +394,25 @@ work_unit_routes:
       statuses: [draft, ready-for-human, approved, blocked, stale, drift, new_impacts, not-applicable]
       approved_by: yss-product-lifecycle
       forbidden: [self-approval, ready-for-agent, production-code-generation]
+    data_architecture_decision:
+      schema_version: 1
+      applies_when: backend_delivery_impact
+      impact_modes: [required, not-applicable]
+      required: [impact_assessment_ref, impact_assessment_digest, evidence_refs]
+      required_when_data_impact: [data_architecture_ref, data_architecture_digest, review_evidence_refs]
+      not_applicable_requires: [explicit_reason, evidence_refs]
+      empty_data_architecture_document: forbidden
+    api_contract_decision:
+      schema_version: 1
+      impact_modes: [required, not-applicable]
+      required: [impact_assessment_ref, impact_assessment_digest, evidence_refs]
+      required_when_api_impact: [openapi_ref, openapi_version, openapi_digest, validation_record_ref, validation_record_digest, draft_review_ref, draft_review_digest, freeze_version, freeze_time]
+      same_draft_bytes_required_across: [openapi, validation, draft-review, freeze, engineering-approval]
+      validation_requires: [openapi-3.1, locked-redocly, exit-code-zero, all-checks-passed]
+      review_requires: [approved, no-blocking-findings, independent-review-evidence]
+      not_applicable_requires: [explicit_reason, evidence_refs]
+      placeholder_assets: forbidden
+      atomic_approval_gate: gate.engineering-contract-approved
     human_gate: gate.engineering-contract-approved
     applies_when: technical_or_contract_impact
     not_applicable_reason: no_technical_or_contract_impact
@@ -406,6 +426,8 @@ work_unit_routes:
     decision_boundary: scaffold-choice
     completion_states: [existing-and-onboarded, initialized-and-verified, not-applicable]
     automatic_check: check.implementation-repositories-ready
+    result_schema_version: 2
+    backend_design_prerequisites_required: [technical_design, data_architecture_decision, api_contract_decision, engineering_contract_approval_ref]
     must_complete_before: work-unit.ticket-decomposition
   work-unit.ticket-decomposition:
     native: {source: yss-product-lifecycle, skill: yss-product-lifecycle, invocation_mode: model-invoked}
@@ -428,7 +450,7 @@ work_unit_routes:
       page_orchestration_skill: yss-ui-business-page-generation
       conditional_skills:
         api_impact: [yss-api-integration]
-        formily_impact: [yss-formily, formily-foundation, formily-linkage-effects, formily-mode-slot-detail, formily-step-flow]
+        formily_impact: [yss-formily]
         table_impact: [ytable-usage, yedit-table-usage]
         tree_impact: [ytree-usage]
         height_impact: [yss-use-table-height, yss-use-tree-height]
@@ -565,10 +587,13 @@ implementation_repository_preparation:
     remote_repository_creation: explicit-authorization-only
     approved_project_scaffold_contract_required: true
     frontend_contract_minimum_schema_version: 4
-    backend_contract_compatibility_schema_versions: [3, 4]
+    backend_new_generation_schema_version: 4
+    backend_historical_read_only_schema_versions: [3]
     target_policy: nonexistent-or-empty
     force_overwrite: forbidden
-    completion_requires: [scaffold_manifest_ref, scaffold_verification]
+    completion_requires: [scaffold_manifest_ref, scaffold_verification, technical_design, data_architecture_decision, api_contract_decision, engineering_contract_approval_ref]
+    legacy_v3_requires: [legacy_reconciliation, unchanged_mechanical_ownership, completed_technical_data_api_prerequisites, recovery_approval]
+    premature_implementation: blocked-preserve-files
   aggregate_result:
     required: [result, current_version, projects, evidence_refs]
     result: completed
@@ -591,12 +616,14 @@ transition_graph:
     work-unit.plan-requirements: [work-unit.domain-strategy-design, work-unit.stage-decision, work-unit.spec-synthesis]
     work-unit.domain-strategy-design: [work-unit.stage-decision, work-unit.spec-synthesis]
     work-unit.stage-decision: [work-unit.spec-synthesis]
-    work-unit.spec-synthesis: [work-unit.prototype-design, work-unit.technical-analysis, work-unit.implementation-repository-preparation]
-    work-unit.prototype-design: [work-unit.technical-analysis, work-unit.implementation-repository-preparation]
+    work-unit.spec-synthesis: [work-unit.prototype-design, work-unit.technical-analysis]
+    work-unit.prototype-design: [work-unit.technical-analysis]
     work-unit.technical-analysis: [work-unit.implementation-repository-preparation]
     work-unit.implementation-repository-preparation: [work-unit.ticket-decomposition]
     work-unit.ticket-decomposition: [work-unit.slice-implementation]
   forbidden_shortcuts:
+    - {from: work-unit.spec-synthesis, to: work-unit.implementation-repository-preparation}
+    - {from: work-unit.prototype-design, to: work-unit.implementation-repository-preparation}
     - {from: work-unit.spec-synthesis, to: work-unit.slice-implementation}
     - {from: work-unit.prototype-design, to: work-unit.slice-implementation}
     - {from: work-unit.technical-analysis, to: work-unit.slice-implementation}
@@ -789,7 +816,7 @@ backend_scaffold:
   scaffold_statuses: [existing, required, initialized]
   required_status: required
   sequence:
-    after: [prototype_review, prototype_verification, antd_cli_verification, browser_verification, prototype_confirmation, engineering_baseline]
+    after: [prototype_review, prototype_verification, offline_html_verification, browser_verification, prototype_confirmation, engineering_baseline]
     before_generator: [scaffold-architecture-decision-user-confirmed, scaffold-architecture-decision-lifecycle-approved, yss-implementation-contract-compiler-scaffold-contract, lifecycle-approve-scaffold-contract]
     before: [business_code_generation, implement]
   generator_routes:
@@ -830,10 +857,11 @@ backend_scaffold:
     unsupported_inputs:
       schema_v1: reject-no-auto-upgrade
       schema_v2_new_generation: reject-no-auto-upgrade
+      schema_v3_new_generation: reject-historical-read-only
       slice_id: forbidden-as-scaffold-identity
       existing_project: reject-no-scaffold-migration
-  required_inputs: [implementation_repository, backend_repository, scaffold_status, scaffold_target_confirmed, scaffold_request_id, target_output_dir, project_name, base_package, architecture_family, generator_skill, decision_ref, decision_id, decision_digest, maven_group_id, project_version, parent_group_id, parent_artifact_id, parent_version, yss_components_version, architecture_profile, persistence_profile, verification_database, production_database, platform_profile, validation_namespace, dto_placement, repository_profile, requested_capabilities, resolved_modules, resolution_version, scaffold_contract_file, scaffold_contract_draft, scaffold_contract_id, scaffold_contract_version, scaffold_contract_status, scaffold_contract_approved, scaffold_contract_compiler_draft_ref, scaffold_contract_lifecycle_approval_ref, scaffold_contract_persisted, scaffold_contract_persisted_ref, scaffold_contract_current_version]
-  required_evidence: [scaffold_architecture_decision, user_confirmation_ref, decision_digest, generator_inputs, expected_files, scaffold_generation_manifest_v3, generated_project_structure, generation_execution_result, verification_execution_result, architecture_rules, ./mvnw_validate, ./mvnw_test, ./mvnw_package, yss_skill_execution_result]
+  required_inputs: [implementation_repository, backend_repository, scaffold_status, scaffold_target_confirmed, scaffold_request_id, target_output_dir, project_name, base_package, architecture_family, generator_skill, decision_ref, decision_id, decision_digest, technical_design_ref, technical_design_version, technical_design_digest, data_architecture_decision_ref, data_architecture_decision_version, data_architecture_decision_digest, engineering_contract_approval_ref, maven_group_id, project_version, parent_group_id, parent_artifact_id, parent_version, yss_components_version, architecture_profile, persistence_profile, verification_database, production_database, platform_profile, validation_namespace, dto_placement, repository_profile, requested_capabilities, resolved_modules, resolution_version, scaffold_contract_file, scaffold_contract_draft, scaffold_contract_id, scaffold_contract_version, scaffold_contract_status, scaffold_contract_approved, scaffold_contract_compiler_draft_ref, scaffold_contract_lifecycle_approval_ref, scaffold_contract_persisted, scaffold_contract_persisted_ref, scaffold_contract_current_version]
+  required_evidence: [scaffold_architecture_decision, user_confirmation_ref, decision_digest, technical_design, data_architecture_decision, engineering_contract_approval, generator_inputs, expected_files, scaffold_generation_manifest_v4, generated_project_structure, generation_execution_result, verification_execution_result, architecture_rules, ./mvnw_validate, ./mvnw_test, ./mvnw_package, yss_skill_execution_result]
   generation_options:
     with_example: false
     force: forbidden-by-default
@@ -1111,7 +1139,7 @@ prototype_modes:
     replaces_yss_high_fidelity: false
   yss_high_fidelity:
     asset: ant_design_v6_html
-    required: [prototype_mode, prototype_review, antd_cli_verification, browser_verification, prototype_evidence, user_confirmation]
+    required: [prototype_mode, prototype_review, offline_html_verification, browser_verification, prototype_evidence, user_confirmation]
     purpose: product_design_review
     replaces_matt_logic: false
 

package/template/.pi/skills/yss-product-lifecycle/references/orchestration.md

@@ -43,9 +43,9 @@ Matt phase boundary 是工作阶段之间的上下文决策，不是新的生命
 
 `prototype_confirmation` 通过后，先判断实现仓库登记中的 backend `scaffold_status`。当状态为 `required` 时，在工程基线中先完成脚手架架构选择：Agent 按领域复杂度给出 `domain-driven` / `layered-mvc` 推荐和依据，本体选择作为子项目预填默认值，用户通过批量表确认全部项目或逐项覆盖。选择写入 `scaffold-architecture-decisions.yaml`；处于 `undecided`、`recommended`、`awaiting-user-decision` 或 `stale` 时必须阻断，不得默认 DDD，也不得在生成器内交互。
 
-选择达到 `lifecycle-approved` 且 digest 当前后，由 `yss-implementation-contract-compiler` 编译脚手架 schema v3 `controlled-generation` 工作单元合同，生命周期批准并持久化后才能运行对应生成器。顺序为：工程基线与架构推荐 → 用户确认与选择持久化 → 实现合同编译器脚手架合同 draft → 生命周期批准/持久化 → `domain-driven` 使用 `yss-ddd-scaffold-generator` 或 `layered-mvc` 使用 `yss-layered-mvc-scaffold-generator` → 对应基线/Manifest v3 校验 → 实现合同编译器业务合同重编译。`existing` / `initialized` 不重复生成；架构转换必须单独立项。
+选择达到 `lifecycle-approved` 且 digest 当前后，先完成批准且当前的 Technical Design、Data Architecture Decision v1 和 API Contract Decision v1。数据与 API 均按影响强制：命中则绑定设计及评审闭包，未命中则绑定评估、明确原因和证据。再由 `yss-implementation-contract-compiler` 编译脚手架 schema v4 `controlled-generation` 工作单元合同。顺序为：工程基线与架构推荐 → 用户确认与选择持久化 → 技术/数据/API 设计 → 工程合同原子批准 → 脚手架合同持久化 → `domain-driven` 使用 `yss-ddd-scaffold-generator` 或 `layered-mvc` 使用 `yss-layered-mvc-scaffold-generator` → 对应基线/Manifest v4 校验 → 仓库准备 v2 → 实现合同编译器业务合同重编译。`existing` / `initialized` 不重复生成；架构转换必须单独立项。schema v3 只允许历史 Manifest 的只读恢复审计，不得新生成。
 
-脚手架工作单元必须使用结构化 schema v3 合同 JSON，至少记录 `contract_id`、`contract_version`、`scaffold_request_id`、`architecture_family`、`generator_skill`、`decision_ref/id/digest`、Profile、能力模块闭包、实现合同编译器 draft 引用、生命周期批准引用、持久化引用、当前版本、允许写路径、预期证据文件和验证命令；不得使用 `slice_id` 伪造工程基线身份。生成器必须读取合同和决策文件并校验状态、digest、版本、skill、工作模式与固定命令。三条 Wrapper 命令必须由受控工作单元真实执行，逐条留存 `exit_code`、`duration_ms`、stdout/stderr 引用和执行时间；生成器打印的下一步命令不构成证据。非空目标、`--force`、旧项目迁移和模板升级均阻断。脚手架不得生成业务规则、状态机、权限、事务、复杂查询、错误映射、用户可见行为或示例业务 API；`validate` 通过、输出目录存在或生成器成功都不是生命周期批准、架构放行或 `ready-for-agent`。
+脚手架工作单元必须使用结构化 schema v4 合同 JSON，除工程身份、架构决定、Profile、模块闭包、允许路径和验证命令外，必须以原始字节 digest 绑定 Technical Design、Data Architecture Decision v1、API Contract Decision v1 和 `gate.engineering-contract-approved` 的真实批准记录。API `required` 时 Draft、Validation、独立 Review、Freeze 与工程批准必须绑定同一 OpenAPI YAML 字节；`not-applicable` 时不得携带空占位资产。生成器在创建输出目录前读取并校验所有引用、版本、主体、gate、批准范围、资产绑定与摘要；虚构 URI、字符串自证或仅有 `status: approved` 均无效。三条 Wrapper 命令必须由受控工作单元真实执行并留存证据。非空目标、`--force`、旧项目迁移和模板升级均阻断。脚手架不得生成 Controller、Repository 实现、SQL、领域行为、业务规则、状态机、权限、事务、复杂查询、错误映射、用户可见行为或示例业务 API；`empty-scaffold-verified` 仍不是 `ready-for-agent`。
 
 脚手架完成后，所有后续生成的后端代码仍必须重新消费当前版本的批准 Slice Implementation Contract、YSS skill 依赖闭包、允许写路径、预期证据和 Execution Result。业务行为使用 `behavior-tdd`；只有机械结构、样板、配置和冻结客户端使用 `controlled-generation`。缺少合同、skill、证据或实际验证时立即阻断；生成范围从机械内容变成业务行为时触发完整重路由。
 

package/template/.pi/skills/yss-product-lifecycle/references/state-model.md

@@ -54,7 +54,7 @@ AND Slice Implementation Contract 的 `ticket_ref` 与 `vertical_slice_ticket_re
 AND 当前工作单元消费的 contract_id/version 与最新批准版本一致
 AND Backend Slice Implementation Contract（后端适用）和 Build Architecture Checklist 已完成
 AND backend 影响且 scaffold_status=required 时，脚手架架构选择已由用户确认并达到 lifecycle-approved、兼容 schema v3 或统一 schema v4 合同与 Manifest 当前、对应 DDD / Layered MVC 基线、Wrapper 验证和 实现合同编译器重编译均已完成
-AND frontend 影响且无已有工程时，统一 schema v4 Project Scaffold Contract 已批准、持久化且当前，模板 commit 已锁定，`pnpm install --frozen-lockfile` 与工程基线要求的 lint/type-check/build 已实际通过
+AND frontend 影响且无已有工程时，统一 schema v4 Project Scaffold Contract 已批准、持久化且当前，模板 bundled manifest 摘要或 Git commit 已锁定，`pnpm install --frozen-lockfile` 与工程基线要求的 lint/type-check/build 已实际通过
 AND 所有后续生成代码均绑定主 YSS skill、依赖闭包、允许写路径、预期证据和 YSS Skill Execution Result
 AND UI 影响切片的前端实现还原计划已通过 schema 校验、`template=false`、`status=approved`，且基线引用可读取
 ```

package/template/.pi/skills/yss-prototype-stage/SKILL.md

@@ -19,30 +19,30 @@ description: Use when a YSS feature has product-design impact on a primary flow,
 - 先读取 Spec、产品总体设计、`CONTEXT.md`、`yss-design-system`，再按 `DESIGN.md` → `docs/design/design.md` → `docs/design/tokens/*` 顺序消费设计基线，形成交互说明、低保真页面/流程和状态矩阵。
 - 用独立 `prototype-review` 评审低保真与状态；未通过不得选择档位或构建原型交付物。
 - 按 [原型档位路由](references/prototype-profile-routing.md) 选择 H1/H2 中满足当前决策风险的最低档位。没有充分证据时默认 H2。
-- Codex 按档位消费 `product-design:index` 的 focused workflow；H1 可直接走静态适配器，H2 使用 `get-context/image-to-code/design-qa`。其他 Agent 必须交付等价合同资产。
+- 默认以 `DESIGN.md`、交互说明和状态矩阵进入 YSS HTML 适配器；有已选视觉稿时才条件调用 `product-design:index` 的还原 workflow。规范直出不调用要求先有图片的 `prototype/image-to-code/design-qa`；六轴 QA 仍由本阶段合同持有，所有 Agent 交付等价证据。
 - `high-fidelity-html-prototype` 仅为历史兼容入口；新资产统一为 `artifact.prototype-deliverable`、Prototype Evidence schema v4 与 Visual Baseline schema v1。
 
 ## 执行顺序
 
 1. 形成交互说明、低保真与状态矩阵；状态至少包含事件、转换、guard、动作与可退出路径。
 2. 完成独立 `prototype-review`，提取仍需由原型回答的风险。
-3. 计算并记录 `prototype_profile`。新视觉方向或信息架构不确定时执行三方案 ideation；复用已批准模式时记录 `not-applicable` 与 source visual。
-4. H1 用 `prototype-contract.mjs prepare-static` 生成无 Node 运行时的静态适配器；H2 按 `references/product-design-adapter.md` 构建可运行流程。
+3. 计算并记录 `prototype_profile`。新视觉方向或信息架构不确定时比较三个候选方案并由用户选择；可用低保真或 HTML 比较，图片 ideation 按需使用。已有规范和页面模式足够时记录 `not-applicable`、规范依据与理由。
+4. H1 使用 `prototype-contract.mjs prepare-static`；H2 默认使用 `prepare-flow`，条件真实组件路线使用 `build-antd-prototype.mjs`。二者都交付 `index.html` 与本地 CSS/JS/资源。按 `references/product-design-adapter.md` 完成场景、离线复验和 `seal-project`，不把 starter 示例当作业务验收。
 5. 自动采集版本、digest、视口、截图、console 与扫描结果。截图按 `route + page + state + viewport + theme + locale + data_scenario` 写入 `Visual Baseline Bundle`，执行 `visual-baseline-contract.mjs seal` 后由 feature 级 schema v4 `prototype-evidence.yaml` 引用；人工只补决策、风险、允许差异和用户确认。
 6. 以统一六轴 Design QA 和档位验证矩阵完成浏览器/无障碍验证。用户确认后才可校准 Spec、分析 API 影响或进入 实现合同编译器 readiness。
 
 ## 档位边界
 
 - H1 `visual-review`：浏览器可复验的 HTML/CSS/少量 JS 或设计工具导出；不得要求 `package.json`、lockfile、Node 或 AntD CLI。
-- H2 `flow-review`：主流程与关键异常状态可操作；Vue 3/Vite + Antdv Next 是受支持默认。React/Vite + Ant Design v6 仅作为显式兼容路线；只消费与实际 `component_basis` 匹配的精确版本事实或 fresh fact pack。
+- H2 `flow-review`：默认使用 `html-css-js`，主流程与关键异常状态可操作；场景可重复触发并重置。制作阶段允许必要工具，接收者无需安装 Node 或组件库，也不依赖网络。复杂控件只模拟当前决策需要的行为；简化会改变关键结论时，按 AntD 集成说明选择预构建真实控件；仍无法支撑的部分列为 gap 并回到设计澄清。
 - 原型代码默认 throwaway；可复用的是项目 Token、组件语义映射、状态、测试场景和验收标准。任何源码进入生产仍需 实现合同编译器、Slice Contract 和 TDD。
 - 原型阶段不得调用 `yss-ui`，不得读取生产组件 API 来制造“真实组件原型”。需要核验真实 YSS/AntDV 组件的事项写入 `implementation_handoff`，由前端实现计划、已批准切片的实现和实现还原验证负责。
 
 ## 事实、QA 与确认
 
-优先级固定为：项目根 `DESIGN.md` 规范 Token / 组件变体 → `docs/design/design.md` 治理解释 → `docs/design/tokens/*` 派生快照 → 当前功能语义 → 相关上游组件事实。H2 默认通过 `yss-antdv-next-design` 使用 Antdv Next exact-version fact pack；只有显式选择 `react-antd-6` 时才调用 `yss-antd-design`。fact pack 仅在精确版本、组件集合、根 `DESIGN.md` digest 和项目 Token digest 均匹配且无新 API 疑问时可复用；否则做增量查询。`antd lint/doctor` 只对 React 兼容路线的相关源文件执行。
+优先级固定为：根 `DESIGN.md` 规范 Token / 组件变体 → `docs/design/design.md` 治理解释 → `docs/design/tokens/*` 派生快照。行为由 Spec、交互说明与状态矩阵定义。HTML 消费包内 Token CSS，保存根规范与 Token 摘要，不再调用组件 Provider 或采集新的 fact pack。标准格式与工具版本沿用项目锁定值，不跟随上游 main 自动升级。
 
-Design QA 合并 visual、layout、interaction、content、accessibility、cross-platform 六轴，不再建立第二份评审。所有档位至少证明 desktop/narrow 非空渲染、项目 Token、console 和基础键盘/焦点/对比度；H2 追加主流程、关键异常、200% zoom/reduced motion 与按风险视觉回归。图片是视觉基准而非唯一事实来源；模型必须从 `visual-baseline.yaml` 的 `case_id` 读取对应语义引用，禁止靠目录 glob 猜测页面含义。
+Design QA 合并 visual、layout、interaction、content、accessibility、cross-platform 六轴，不再建立第二份评审。所有档位至少证明 desktop/narrow 非空渲染、项目 Token、console 和基础键盘/焦点/对比度；H2 追加主流程、关键异常、200% zoom/reduced motion 与按风险视觉回归。规范直出使用 `design_qa.mode=design-contract`，对照规范和实际计算样式审查；已有视觉稿使用 `visual-comparison`，对照同视口同状态源图。首版截图在审查和用户确认后冻结，不能与自身对比来证明符合规范。图片是视觉基准而非唯一事实来源；模型必须从 `visual-baseline.yaml` 的 `case_id` 读取对应语义引用，禁止靠目录 glob 猜测页面含义。
 
 用户确认必须绑定提问者或其明确指定负责人的原始回复，使用生命周期 `user_decision_policy` 和统一用户决定记录；产品数字人只提供确认建议，不能代答。正式证据追加 `user_decision_ref/decision_subject_ref`，校验原型、视觉基线和操作范围与用户所见快照一致。用户确认只描述原型确认了什么、哪些范围可操作、哪些为模拟或 gap，以及接受/拒绝结论；不要求用户确认技术栈、CLI 或构建细节。
 
@@ -57,9 +57,9 @@ Design QA 合并 visual、layout、interaction、content、accessibility、cross
 
 ## 常见错误
 
-- 继续把 React/AntD 当作 H2 默认，或把单个 HTML 文件当成所有档位的答案。
+- 把 H1/H2 当作低/高保真；把离线 HTML 降为静态截图，或继续要求 Provider、Node starter、预先生成图片。
 - 低保真未评审就选择技术栈；用主观评分代替确定性触发规则。
-- H1 伪造 lockfile/AntD 段，或 H2 声称已验证生产 YSS/AntDV 真实组件。
+- 空填 lockfile/fact pack；把自身生成图当成独立来源，或宣称已验证生产真实组件。
 - 重复抄写机器可采集的版本、digest、截图和 console；创建第二份状态机、QA 或 handoff 资产。
 - 把原型源码直接复制进生产，或在原型阶段调用 `yss-ui`。
 
@@ -71,3 +71,7 @@ Design QA 合并 visual、layout、interaction、content、accessibility、cross
 通过 `gate.product-design-approved` 的现有用户决定协议确认当前基线 manifest 原字节，Handoff v5 明确声明 `ui_baseline_kind: existing-ui-baseline`。截图、代码可运行或旧原型批准都不能替代该确认；本技能只能准备审阅资产，不代答或批准。发现任何 UI 改动，包括后端行为导致的体验变化，回到上述原型流程；新设计继续保留现有原型与验证要求。
 
 消费者以 `scripts/preflight-delivery` 检查交付前提，再由 `scripts/lib/ui-baseline.mjs` 分派原型与既有基线。前端使用 Strategic Preflight v2 和 Delivery Acceptance v3 的通用 `baseline_case_ids` 承接；通过仅说明输入可核验，不授予写代码权限。
+
+## AntD 组件补充
+
+消费 [组件集成说明](references/antd-integration.md) 与 [组件索引](references/antd-component-catalog.json)：默认原生 HTML，复杂交互确实影响评审结论时记录理由并选 `react-antd-prebuilt`。`--pattern workbench` 提供查询列表、详情、编辑和失败恢复 starter；真实 AntD 在独立作者目录按固定 lock 预构建，交付包仍离线运行、接收者无需 Node。两条路线统一根 DESIGN.md、六轴 QA、场景重置及当前用户确认，不恢复 Provider 技能、不证明生产 YSS 组件兼容。

package/template/.pi/skills/yss-prototype-stage/assets/antd-authoring/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "yss-antd-prototype-authoring",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "packageManager": "pnpm@10.15.0",
+  "dependencies": {
+    "antd": "6.6.4",
+    "react": "19.2.4",
+    "react-dom": "19.2.4"
+  },
+  "devDependencies": {
+    "esbuild": "0.28.2",
+    "@ant-design/cli": "6.6.4"
+  }
+}