create-yss-spec 3.3.8 → 3.4.3

package/template/.pi/skills/yss-implementation-contract-compiler/references/slice-implementation-contract-v2.md

@@ -0,0 +1,214 @@
+# Slice v2 历史读取与显式迁移
+
+本页仅描述旧格式。新合同使用 [Slice v3](slice-implementation-contract.md)；v2 保留原验证和过期判定，修改时显式生成新版本，不继承批准。
+
+# Slice Implementation Contract
+
+后端合同还必须绑定 `architecture_identity`（schema 见 `docs/process/schemas/backend-architecture-identity.schema.json`），并与工程基线、登记和 Manifest 一致。将同一身份复制到 `resolution`、backend 工作单元和执行结果；Profile 的成熟度/Recipe 来源是技能注册表，draft 不得 ready-for-agent。旧 backend.domain-behavior/persistence-mybatis/http-api Recipe 只读退役，重新编译时显式选择 backend.ddd-* 或 backend.mvc-*。
+
+`yss-implementation-contract-compiler` 生成草案；`yss-product-lifecycle` 核验、批准并持久化。合同缺少必填字段时状态为 `blocked`。schema v1 已停止支持，必须重新编译为 v2，不提供自动升级。
+
+采用专职前端 profile 时，`frontend.delivery` 绑定 `{acceptance_ref, digest}`，来自 `scripts/verify-frontend-delivery` 的当前结果；也可由 `resolution.frontend_delivery` 承载，两处并存时必须一致。正式执行从持久化合同读取并重验输入。细则见 `docs/process/frontend-backend-delivery.md`。
+
+```yaml
+slice_contract:
+  schema_version: 2
+  contract_id:
+  contract_version: 1
+  slice_id:
+  status: draft
+  suggested_owner_role_id: # role.frontend-engineer | role.backend-engineer | role.test-engineer；编译器只建议，生命周期编排器派活并批准
+  lifecycle_refs:
+    spec:
+    ticket:
+    requirement_freeze:
+    low_fidelity_review:
+    prototype_review:
+    prototype_profile_decision:
+    prototype_deliverable:
+    prototype_deliverable_verification:
+    prototype_confirmation:
+    openapi_freeze_or_no_impact:
+    architecture_review:
+    data_architecture:
+    engineering_baseline:
+    technical_design: # 阅读引用；与 resolution.technical_design.ref 指向同一文件
+    tactical_design: # 旧 DDD 引用兼容
+    build_architecture_checklist:
+    implementation_repository:
+    frontend_repository:
+    backend_repository:
+    maven_wrapper:
+  readiness:
+    blockers: []
+    stale_inputs: []
+    not_applicable:
+      - item:
+        reason:
+  resolution:
+    technical_design: # 有技术设计影响时由编译器绑定，DDD / MVC 共用
+      ref:
+      version:
+      digest: # 已持久化合同原始字节摘要
+    required_capabilities: []
+    required_skills: []
+    recipe_ids: []
+    conditions: []
+    reason_chains: {}
+    registry_digest: # sha256 of normalized docs/agents/yss-skill-registry.yaml
+    compiler_contract_digest: # sha256 of normalized compiler-contract.yaml
+    compiled_at:
+    freshness: current # digest 变化后为 stale
+  common:
+    impacted_areas: []
+    implementation_path_policy: harness-apps-multi-project # or external-repository-native | git-submodule-harness-apps
+    project_roots: []
+    required_capabilities: []
+    required_skills: []
+    optional_skills: []
+    unavailable_skills:
+      - skill:
+        provider:
+        fallback: blocked | approved-equivalent
+        resolution:
+    allowed_write_paths: []
+    forbidden_patterns: []
+    expected_evidence_files: []
+    verification_commands: []
+    human_review_points: []
+    full_reroute_triggers: []
+    quality_baseline_ref:
+    context_plan:
+      required_context_refs: []
+      on_demand_context_refs: []
+      context_stop_rule: minimal-sufficient-evidence
+      missing_context_action: blocked # or reroute
+    doubt_driven_review:
+      status: not-applicable # or required / completed / blocked
+      trigger_impacts: []
+      claim:
+      counterclaim:
+      evidence_refs: []
+      residual_risks: []
+      reviewer_ref:
+  frontend:
+    status: not-applicable
+    required_skills: []
+    approved_prototype_ref:
+    state_matrix_ref:
+    visual_baseline_ref:
+    visual_baseline_case_ids: []
+    generated_api_client_ref:
+    allowed_write_paths: []
+    component_test_seams: []
+    e2e_paths: []
+  backend:
+    status: not-applicable
+    affected_layers: []
+    component_impacts: []
+    required_skills: []
+    application_boundary:
+    transaction_boundary:
+    persistence_strategy:
+    tactical_design_ref:
+    tactical_design_version:
+    aggregate_refs: []
+    invariant_refs: []
+    state_behavior_refs: []
+    gateway_boundary_ref:
+    domain_test_seams: []
+    application_test_seams: []
+    tactical_ddd:
+      status: not-applicable
+      tactical_design_ref:
+      tactical_design_version:
+      aggregate_refs: []
+      invariant_refs: []
+      state_behavior_refs: []
+      gateway_boundary_ref:
+      domain_test_seams: []
+      application_test_seams: []
+    allowed_write_paths: []
+    forbidden_patterns: []
+    expected_evidence_files: []
+    seam_deferred: []
+    verification_commands: []
+  contract:
+    api_impact: false
+    freeze_ref:
+    no_api_impact_ref:
+    generated_clients: []
+    contract_tests: []
+    regeneration_commands: []
+  cross_repo:
+    repositories: []
+    delivery_order: []
+    integration_verification: []
+    rollback_order: []
+  work_units:
+    - id: slice-frontend
+      role_id: role.frontend-engineer
+      runtime_id: runtime.skill-projection
+      execution_state: Worker
+      workflow_status: not-started
+      task_package_ref:
+      contract_id: # must equal slice_contract.contract_id
+      contract_version: # must equal slice_contract.contract_version
+      downstream_consumers: []
+      convergence_ref:
+      work_unit:
+        behavior:
+        primary_skill:
+        supporting_skills: []
+        tdd_mode: behavior-tdd
+        allowed_write_paths: []
+        expected_evidence: []
+        verification_commands: []
+    - id: slice-backend
+      role_id: role.backend-engineer
+      runtime_id: runtime.skill-projection
+      execution_state: Worker
+      workflow_status: not-started
+      task_package_ref:
+      contract_id:
+      contract_version:
+      downstream_consumers: []
+      convergence_ref:
+      work_unit:
+        behavior:
+        primary_skill:
+        supporting_skills: []
+        tdd_mode: behavior-tdd
+        allowed_write_paths: []
+        expected_evidence: []
+        verification_commands: []
+```
+
+工作单元：
+
+```yaml
+work_unit:
+  id:
+  behavior:
+  primary_skill:
+  supporting_skills: []
+  tdd_mode: behavior-tdd
+  allowed_write_paths: []
+  expected_evidence: []
+  verification_commands: []
+  controlled_generation:
+    exception_reason:
+    generator:
+    generator_inputs: []
+    expected_files: []
+    verification_commands: []
+    behavior_tests_after_generation: []
+```
+
+`controlled_generation` 仅在 `tdd_mode: controlled-generation` 时必填；其他模式标记 `not-applicable`。明确写入需求的权限业务行为仍使用 `behavior-tdd`；API schema 与 database schema 分别触发契约或数据架构回退，不得用一个含糊的 schema 类型决定路线。
+
+`work_units` 中的前端、后端和测试任务是切片级子任务，不是新的生命周期阶段。每个子任务必须引用独立任务包；任务包只能消费同一份已批准且版本当前的 Slice Contract。`workflow_status` 追踪执行过程，不能替代生命周期状态；`contract_id`、`contract_version` 或 resolution digest 不一致时必须阻断并回到实现合同编译器。
+
+一个切片可以组合多个窄 Recipe，但只计算一次闭包。Recipe 只能引用 capability；合同同时冻结 `required_capabilities`、`required_skills`、完整原因链和 Registry/Compiler digest。任一 digest 或 Visual Baseline 版本 / digest 改变时，当前合同标记 `stale`，重新编译后仍须由 `yss-product-lifecycle` 再批准。UI 切片只消费 `visual_baseline_case_ids` 指定的图片，并先读取 manifest 与语义引用，禁止按目录 glob 猜测图片含义。
+
+技术设计编译绑定使用 `technical_design: {ref, version, digest}` 与 `slice_id`，校验器规则见 `yss-technical-design/references/technical-design-contract.md`。`backend.tactical_ddd` 仅适用于 `domain-driven`；MVC 消费共同技术设计绑定与 `design` 的用例、规则、事务和测试 seam，不填聚合或 Gateway 字段。

package/template/.pi/skills/yss-implementation-contract-compiler/references/slice-implementation-contract.md

@@ -1,210 +1,72 @@
-# Slice Implementation Contract
-
-后端合同还必须绑定 `architecture_identity`（schema 见 `docs/process/schemas/backend-architecture-identity.schema.json`），并与工程基线、登记和 Manifest 一致。将同一身份复制到 `resolution`、backend 工作单元和执行结果；Profile 的成熟度/Recipe 来源是技能注册表，draft 不得 ready-for-agent。旧 backend.domain-behavior/persistence-mybatis/http-api Recipe 只读退役，重新编译时显式选择 backend.ddd-* 或 backend.mvc-*。
-
-`yss-implementation-contract-compiler` 生成草案；`yss-product-lifecycle` 核验、批准并持久化。合同缺少必填字段时状态为 `blocked`。schema v1 已停止支持，必须重新编译为 v2，不提供自动升级。
-
-采用专职前端 profile 时，`frontend.delivery` 绑定 `{acceptance_ref, digest}`，来自 `scripts/verify-frontend-delivery` 的当前结果；也可由 `resolution.frontend_delivery` 承载，两处并存时必须一致。正式执行从持久化合同读取并重验输入。细则见 `docs/process/frontend-backend-delivery.md`。
-
-```yaml
-slice_contract:
-  schema_version: 2
-  contract_id:
-  contract_version: 1
-  slice_id:
-  status: draft
-  suggested_owner_role_id: # role.frontend-engineer | role.backend-engineer | role.test-engineer；编译器只建议，生命周期编排器派活并批准
-  lifecycle_refs:
-    spec:
-    ticket:
-    requirement_freeze:
-    low_fidelity_review:
-    prototype_review:
-    prototype_profile_decision:
-    prototype_deliverable:
-    prototype_deliverable_verification:
-    prototype_confirmation:
-    openapi_freeze_or_no_impact:
-    architecture_review:
-    data_architecture:
-    engineering_baseline:
-    technical_design: # 阅读引用；与 resolution.technical_design.ref 指向同一文件
-    tactical_design: # 旧 DDD 引用兼容
-    build_architecture_checklist:
-    implementation_repository:
-    frontend_repository:
-    backend_repository:
-    maven_wrapper:
-  readiness:
-    blockers: []
-    stale_inputs: []
-    not_applicable:
-      - item:
-        reason:
-  resolution:
-    technical_design: # 有技术设计影响时由编译器绑定，DDD / MVC 共用
-      ref:
-      version:
-      digest: # 已持久化合同原始字节摘要
-    required_capabilities: []
-    required_skills: []
-    recipe_ids: []
-    conditions: []
-    reason_chains: {}
-    registry_digest: # sha256 of normalized docs/agents/yss-skill-registry.yaml
-    compiler_contract_digest: # sha256 of normalized compiler-contract.yaml
-    compiled_at:
-    freshness: current # digest 变化后为 stale
-  common:
-    impacted_areas: []
-    implementation_path_policy: harness-apps-multi-project # or external-repository-native | git-submodule-harness-apps
-    project_roots: []
-    required_capabilities: []
-    required_skills: []
-    optional_skills: []
-    unavailable_skills:
-      - skill:
-        provider:
-        fallback: blocked | approved-equivalent
-        resolution:
-    allowed_write_paths: []
-    forbidden_patterns: []
-    expected_evidence_files: []
-    verification_commands: []
-    human_review_points: []
-    full_reroute_triggers: []
-    quality_baseline_ref:
-    context_plan:
-      required_context_refs: []
-      on_demand_context_refs: []
-      context_stop_rule: minimal-sufficient-evidence
-      missing_context_action: blocked # or reroute
-    doubt_driven_review:
-      status: not-applicable # or required / completed / blocked
-      trigger_impacts: []
-      claim:
-      counterclaim:
-      evidence_refs: []
-      residual_risks: []
-      reviewer_ref:
-  frontend:
-    status: not-applicable
-    required_skills: []
-    approved_prototype_ref:
-    state_matrix_ref:
-    visual_baseline_ref:
-    visual_baseline_case_ids: []
-    generated_api_client_ref:
-    allowed_write_paths: []
-    component_test_seams: []
-    e2e_paths: []
-  backend:
-    status: not-applicable
-    affected_layers: []
-    component_impacts: []
-    required_skills: []
-    application_boundary:
-    transaction_boundary:
-    persistence_strategy:
-    tactical_design_ref:
-    tactical_design_version:
-    aggregate_refs: []
-    invariant_refs: []
-    state_behavior_refs: []
-    gateway_boundary_ref:
-    domain_test_seams: []
-    application_test_seams: []
-    tactical_ddd:
-      status: not-applicable
-      tactical_design_ref:
-      tactical_design_version:
-      aggregate_refs: []
-      invariant_refs: []
-      state_behavior_refs: []
-      gateway_boundary_ref:
-      domain_test_seams: []
-      application_test_seams: []
-    allowed_write_paths: []
-    forbidden_patterns: []
-    expected_evidence_files: []
-    seam_deferred: []
-    verification_commands: []
-  contract:
-    api_impact: false
-    freeze_ref:
-    no_api_impact_ref:
-    generated_clients: []
-    contract_tests: []
-    regeneration_commands: []
-  cross_repo:
-    repositories: []
-    delivery_order: []
-    integration_verification: []
-    rollback_order: []
-  work_units:
-    - id: slice-frontend
-      role_id: role.frontend-engineer
-      runtime_id: runtime.skill-projection
-      execution_state: Worker
-      workflow_status: not-started
-      task_package_ref:
-      contract_id: # must equal slice_contract.contract_id
-      contract_version: # must equal slice_contract.contract_version
-      downstream_consumers: []
-      convergence_ref:
-      work_unit:
-        behavior:
-        primary_skill:
-        supporting_skills: []
-        tdd_mode: behavior-tdd
-        allowed_write_paths: []
-        expected_evidence: []
-        verification_commands: []
-    - id: slice-backend
-      role_id: role.backend-engineer
-      runtime_id: runtime.skill-projection
-      execution_state: Worker
-      workflow_status: not-started
-      task_package_ref:
-      contract_id:
-      contract_version:
-      downstream_consumers: []
-      convergence_ref:
-      work_unit:
-        behavior:
-        primary_skill:
-        supporting_skills: []
-        tdd_mode: behavior-tdd
-        allowed_write_paths: []
-        expected_evidence: []
-        verification_commands: []
-```
+# Slice Implementation Contract v3
+
+YAML 是唯一权威合同。Agent 从已确认上游整理草案；用户确认目标、范围、验收和关键取舍；独立专业审查核验工程约束，生命周期主控关闭 `gate.slice-contract-approved`。新合同使用 schema v3；[v2](slice-implementation-contract-v2.md) 保留原规则读取和校验，schema v1 继续拒绝。
+
+结构权威为 `docs/process/schemas/slice-implementation-contract-v3.schema.json`。Registry、编译规则与 Execution Result 继续使用各自版本；Slice v3 不要求它们一同升级。
+
+## 只保存一次
+
+| 分组 | 填写内容 | 不再重复填写 |
+|---|---|---|
+| 身份 | schema_version、contract_id、contract_version、slice_id、status | 任务内不复制合同身份 |
+| basis | 上游 ref、原字节 digest、已知 version 和适用 approval_ref | 同一文件用本组键名别名，不复制 Spec、技术设计正文 |
+| scope | 影响面、工程根、写边界及本切片约束 | 子合同不再保存同一 Skill、路径、命令 |
+| applicability | frontend/backend/api/cross_repo 的 required 或带理由的 not-applicable | 不适用的 extensions 整段省略；缺信息不能省略 |
+| resolution | 冻结 capability、Skill、Recipe、条件、Registry/Compiler 摘要及适用架构身份 | 原因链、编译时间、实时 freshness 不进入权威合同 |
+| acceptance | 本切片验收 ID 对应 basis 来源和 locator | 验收正文仍在 Ticket / Spec |
+| verification | 命令、cwd、test_seams、expected_evidence、acceptance_refs | 工作单元通过 verification_refs 选择；required_for_all 自动继承 |
+| work_units | 行为、角色、主辅 Skill、TDD 模式、验收和验证引用 | 写路径默认继承 scope，只能收窄；runtime、派发和进度留在任务包 |
+| extensions | 适用 frontend/backend/api/cross_repo 的独有信息 | 后端设计用 design_refs 定位；仅切片新增约束进入 backend.constraints |
+
+`basis` 别名必须可解析且无循环。所有引用先校验原字节摘要；已知版本必须绑定。locator 支持唯一文字/稳定 ID、`lines:起始-结束`、结构化资产的 `pointer:/design/...`；歧义或缺失阻断。行区间绑定文件摘要，源内容变化后必须重新核验。
 
-工作单元：
-
-```yaml
-work_unit:
-  id:
-  behavior:
-  primary_skill:
-  supporting_skills: []
-  tdd_mode: behavior-tdd
-  allowed_write_paths: []
-  expected_evidence: []
-  verification_commands: []
-  controlled_generation:
-    exception_reason:
-    generator:
-    generator_inputs: []
-    expected_files: []
-    verification_commands: []
-    behavior_tests_after_generation: []
+scope.implementation_path_policy 保留 `external-repository-native`、`harness-apps-multi-project`、`git-submodule-harness-apps`；gitlink 登记、attached HEAD 和禁止覆盖的边界仍按原仓库接入规则校验。
+
+每项验收必须映射到工作单元与验证。每条验证指定已登记工程内的 cwd；多工程工作单元明确 project_root。跨仓扩展保留交付、联合验证和回滚顺序，数组顺序不能排序消除。任务所选 Skill 必须属于冻结闭包；共享约束始终继承。
+
+## 准备和查看
+
+```sh
+scripts/slice-contract prepare <ticket.md> --input <本切片补充.yaml> --output <新合同.yaml> --root <治理根>
+scripts/slice-contract view <合同.yaml> --root <治理根>
+scripts/slice-contract view <合同.yaml> --unit <work-unit-id> --root <治理根>
+scripts/slice-contract diff <旧合同.yaml> <新合同.yaml> --root <治理根>
+scripts/slice-contract migrate <旧v2.yaml> --input <迁移补充.yaml> --output <新v3.yaml> --root <治理根>
 ```
 
-`controlled_generation` 仅在 `tdd_mode: controlled-generation` 时必填；其他模式标记 `not-applicable`。明确写入需求的权限业务行为仍使用 `behavior-tdd`；API schema 与 database schema 分别触发契约或数据架构回退，不得用一个含糊的 schema 类型决定路线。
+`--input` 只传 `sources` 来源选择、`refinements` 新增细化，以及需要时的 checkpoint_ref / approved_slice。可直接调用 `prepareSliceImplementationContract`，避免另存补充文件；临时补充不是批准或执行合同。Ticket 已有 `slice_implementation` frontmatter 或 checkpoint 中同名事实时自动读取，不要求补录全部合同。普通 Markdown Ticket 的验收列表自动按原行定位；其他非结构化语义由 Agent 带来源整理，仍需专业审查。
+
+先复用登记中的工程根和基线中的架构身份。登记写范围仅为上限，不能当作切片授权。多来源冲突、未明影响和缺少必要资产输出具体 blocker。输入变化不能用最后覆盖处理；先修正来源或重新确定切片细化。
+
+输出为 `{slice_contract, report}`；report 包含来源、缺口、原因链和检查结果，不是第二份合同。`persistSliceDraft` 只写新路径，保存前复核读取过的来源，不覆盖既有草案或已批准合同。CLI `verify` 只检查合同与来源，不证明批准有效。
+
+审阅视图展示交付行为、范围、验收、取舍与风险，任务视图附完整全局和专项约束。Markdown 和结构化视图同源，携带合同 ID、版本与原字节摘要，不可反向作为执行授权。差异按原字节与结构比较，未知字段、缺少旧来源快照或来源漂移明确显示，不自动判定用户授权可以延续。
+
+## 审查、批准与派发
+
+- 默认一名有对应能力的独立专业审查者，核验范围、验收覆盖、工程约束和验证充分性。相邻检查可共用现有 review-bundle；不重复要求用户审阅工程字段。
+- 当前合同的工程审查使用现有 `check.design-reviewed` 会签记录，绑定 `subject_ref`、无前缀 subject_digest、artifact_bindings，以及不同的 principal_ref / drafter_principal_ref；findings 为明确数组。未关闭缺陷、缺证据和重要风险阻断，建议须有 follow_up。
+- 生命周期把审查记录引用放入 Slice gate 的 evidence_refs。合同最终字节（包含生命周期设置的状态）冻结后绑定审查和 checkpoint；单独的 `status: approved` 不授予执行权。
+- 用户决定沿用现有 user-decisions 协议：已覆盖且无实质变化时复用，缺失确认或决定变化才集中询问。Spec 确认不自动升级为实施授权，不改写原回复。
+- `compileSliceTaskPackage` 只从已批准原始 YAML 生成任务包，角色 Skill 来自 `taskPackageDefaults`；运行时身份在派发时选择。已有任务包 schema 不变，`contract.gate_refs` 为唯一当前批准 checkpoint 引用。
+- 批准、范围、派发、freshness 和结果核验共用 `normalizeSliceContract`；展开只在内存发生。执行结果仍是 v2，并用 verification_results 的 cwd 证明命令执行位置；任务验收需要全部声明命令、实际结果及可读预期证据。
+
+## 兼容与迁移
+
+v2 不自动改写，也不忽略旧 Compiler/Registry 摘要漂移。显式迁移要求新 contract_version，输出草案并重新计算冻结结果；不继承旧批准。重复字段冲突、未映射约束、模糊验收映射和子合同独有边界均阻断并列明恢复动作。v2 runtime / workflow 状态不进入 v3 合同，保留在原文件和现有任务证据中。
+
+本试点不改技术设计、脚手架、审批记录、交付合同结构，不新增管理页面或跨进程缓存。
+
+## 第二轮增量规则
+
+新草案的 `ticket_policy` 声明 `frozen-requirements` / `tracker-or-task-package`，Ticket 必须有 requirement_version 或显式绑定版本。冻结后进度、验收结果、会签与重路由记录进入现有 tracker / 任务包；需求改动生成新版本，不重新解释旧合同的绑定。审阅视图分别显示冻结时状态与当前状态的读取位置。
+
+明确 `scope.risk_level` 后，准备器绑定生命周期注册表和裁剪依据，并从注册表已发布架构审查的 trigger 条件计算 `applicability.checks`。缺少该声明的旧 v3 保留原保守材料要求。已有 UI 承接须声明 `frontend.baseline_kind: existing-ui-baseline` 与 `ui_change: none`，绑定已有观测包和前端交付验收；UI 变化仍走产品设计证据。未知影响、必要证据缺失和外部强制审批不能裁掉。
+
+准备报告按来源发现、独立检查、依赖检查和组装给出诊断；blocker 的稳定 code、field、source_ref、responsibility 与 recovery 可用于一次回交。责任类别为 agent、professional-review、user-decision。依赖缺失的下游标记 not-executed。报告随草案保存为 `.preparation.json`，绑定 YAML 原始字节；阻断草案只显示诊断，不能批准或执行。报告 metrics 只记录本次实测准备耗时，未观测的补材料轮次与人工确认次数为 null，不把夹具当成真实工时收益。
 
-`work_units` 中的前端、后端和测试任务是切片级子任务，不是新的生命周期阶段。每个子任务必须引用独立任务包；任务包只能消费同一份已批准且版本当前的 Slice Contract。`workflow_status` 追踪执行过程，不能替代生命周期状态；`contract_id`、`contract_version` 或 resolution digest 不一致时必须阻断并回到实现合同编译器。
+多工程新草案在 `basis.repository_preparation` 绑定现有 schema v2 多项目准备结果。`extensions.cross_repo.repository_bindings` 以工程根为键，仅引用 basis 中各工程的 implementation_repository、engineering_baseline、manifest、technical_design 或 frontend_delivery；不复制文件事实。可用 recipe_refs / capability_refs 选择全局编译输入中的适用项。逐仓登记、基线身份、写上限、设计与编译约束都必须满足；所有工作单元显式选择 project_root。delivery_order 与 rollback_order 完整列出工程根；integration_verification 引用 verification 的 ID，联合验证用 cwd 和 dependency_roots 明确位置及依赖。
 
-一个切片可以组合多个窄 Recipe，但只计算一次闭包。Recipe 只能引用 capability；合同同时冻结 `required_capabilities`、`required_skills`、完整原因链和 Registry/Compiler digest。任一 digest 或 Visual Baseline 版本 / digest 改变时，当前合同标记 `stale`，重新编译后仍须由 `yss-product-lifecycle` 再批准。UI 切片只消费 `visual_baseline_case_ids` 指定的图片，并先读取 manifest 与语义引用，禁止按目录 glob 猜测图片含义。
+跨仓 `createApprovedExecutionContext` / `createApprovedRecompilationContext` 使用 `work_unit_id`，歧义阻断。Execution Result 保持 schema v2，跨仓 changed_files / evidence_files 使用 `{path, project_root}`；证据文件从所属工程读取，verification_results 必须携带真实 cwd 和适用 dependency_roots。单仓旧调用继续兼容。接收端重读来源批准与编译摘要并检查角色范围，不能用本地默认编译结果替换不支持的来源版本。
 
-技术设计编译绑定使用 `technical_design: {ref, version, digest}` 与 `slice_id`，校验器规则见 `yss-technical-design/references/technical-design-contract.md`。`backend.tactical_ddd` 仅适用于 `domain-driven`；MVC 消费共同技术设计绑定与 `design` 的用例、规则、事务和测试 seam，不填聚合或 Gateway 字段。
+来源别名在单次读取内合并，审阅复用本次规范化的来源快照；没有外部可传入的缓存对象。执行边界始终重新读取。差异的 scope / acceptance / authorization / engineering-detail 分类附原字节证据与待审查说明；presentation-only 也不授予批准或确认语义等价。

package/template/.pi/skills/yss-layered-mvc-scaffold-generator/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yss-layered-mvc-scaffold-generator
-description: 用于在生命周期已批准的脚手架合同下生成通用 YSS Java 8 分层 MVC 后端工程；核心模块为 server、service、repository，并按能力确定性增加 adapter、client、feign-client。
+description: 用于在生命周期已批准的脚手架合同下生成按批准 Spring Boot / Java 平台生成通用 YSS 分层 MVC 后端工程；核心模块为 server、service、repository，并按能力确定性增加 adapter、client、feign-client。
 ---
 
 # YSS Layered MVC Scaffold Generator
@@ -11,18 +11,31 @@ description: 用于在生命周期已批准的脚手架合同下生成通用 YSS
 
 - backend `scaffold_status=required`，目标目录已确认且不存在。
 - `scaffold-architecture-decisions.yaml` 中对应项目已达到 `lifecycle-approved`，确认架构为 `layered-mvc`。
-- `yss-implementation-contract-compiler` 已编译统一 Project Scaffold Contract schema v4；已批准且当前的后端 schema v3 可完成兼容生成。合同须由生命周期批准并持久化。
+- `yss-implementation-contract-compiler` 已编译统一 Project Scaffold Contract schema v4，并绑定批准且当前的 Technical Design、Data Architecture Decision v1、API Contract Decision v1 和真实工程合同批准记录。API `required` 时 Draft、Validation、独立 Review、Freeze 与工程批准必须绑定同一 OpenAPI YAML 字节；`not-applicable` 时必须有评估、原因和证据且不得携带占位资产。合同须由生命周期批准并持久化。
 - 合同中的 `decision_id`、文件 digest、Profile、能力闭包、写路径和验证命令仍为当前版本。
 
 任一条件缺失时返回 `blocked`。本生成器无交互、无默认回退；用户选择由 `yss-product-lifecycle` 在 `work-unit.technical-analysis` 的工程基线内完成。
 
+## Spring Boot / Java 平台选择
+
+调用本技能时先展示 `scripts/backend-platforms` 的精确版本清单及兼容状态。由生命周期编排器把架构、Spring Boot、Java 和 YSS 父 POM/BOM 合并展示并取得真实用户确认；生成器不提问、不猜版本、不使用 `x` 或 `latest`。已有批准且当前的选择展示摘要后复用。
+
+- 候选平台：Boot 2.7.18 / Java 8，Boot 3.5.16 / Java 17 或 21，Boot 4.1.1 / Java 17 或 21。新 Boot 默认推荐 Java 17；候选不等于可生成。
+- 独立子项目可继承主项目组合或覆盖，必须逐项目确认（允许一次确认明确列出的项目）；同一 Maven Reactor 使用一个平台。
+- 只开放共享兼容清单中已有真实 YSS 构建、依赖和启动证据的组合。缺少兼容父 POM、BOM、starter 或相应能力证据即 `blocked`；不替换官方组件、不降级回退。
+- 新生成合同必须有 `platform_configuration` v2，与架构决策、Maven 坐标及兼容条目摘要一致。Boot、Java、YSS 坐标或依赖配方变化时回生命周期重新确认并编译合同；仅追加同配置验证记录不重复确认，仍核验证据有效性。
+- Spring MVC、Servlet、Validation、Jackson 和 starter 坐标消费共享平台清单；Boot 3.5 / 4.1 拒绝 Java 8/11。Jakarta 转换不包括 `javax.sql` 等 Java SE API。
+- 平台候选维护验证产物标记 `platform_verification=candidate`，不能交给业务生成、升级完成等级或进入首切片验证。测试夹具不证明 YSS 兼容。
+
+版本清单、合同字段、候选验证和支持晋级规则见 仓库共享合同 `docs/engineering/backend-platforms.md`。
+
 ## 架构与 Profile
 
 - 固定核心模块：`server`、`service`、`repository`。
 - `external-integration` 增加 `adapter`。
 - `published-client` 增加 `client`。
 - `feign-client` 增加 `client`、`feign-client`。
-- 固定平台：Java 8、Spring Boot 2.7、`javax`、YSS BOM、MyBatis-Plus。
+- 平台来自批准的 `platform_configuration`；保留 YSS BOM、MyBatis-Plus，不固定单一 Boot/Java/Validation 命名空间。
 - 固定 architecture_profile=layered-mvc-service；verification_database=h2、production_database=not-bound。测试使用 H2，本地运行显式启用 scaffold-local；不引入外部驱动/数据源。
 
 能力解析规则、模块职责和依赖方向见 [architecture.md](references/architecture.md)。生成器必须同时校验 `requested_capabilities` 与 `resolved_modules`，不得自行补猜模块。
@@ -55,7 +68,7 @@ node scripts/generate_and_verify_scaffold.mjs \
 
 ## 硬约束
 
-- 接受统一 schema v4，兼容已批准后端 schema v3；验证器接受对应 Manifest v3/v4。历史 v2 只读兼容，不用于新生成。
+- 新生成只接受包含 API Contract Decision 的统一 schema v4；缺 API 字段的预发布 v4 不得静默接受。验证器可只读检查历史 Manifest v3，恢复必须另行完成所有权审计、技术/数据/API 设计补齐与当前批准。历史 v2/v3 均不用于新生成。
 - `architecture_family` 必须为 `layered-mvc`，`generator_skill` 必须为本 skill。
 - 目标存在、`--force`、旧项目迁移、模板升级均为 `unsupported`。
 - Harness 内只允许以 `apps/backend/` 为输出父容器；外部实现仓库使用已登记真实路径。

package/template/.pi/skills/yss-layered-mvc-scaffold-generator/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "YSS Layered MVC Scaffold Generator"
   short_description: "Generate an approved YSS layered MVC backend skeleton."
-  default_prompt: "Use $yss-layered-mvc-scaffold-generator only after a user-confirmed scaffold architecture decision and a lifecycle-approved schema v3 scaffold contract."
+  default_prompt: "Use $yss-layered-mvc-scaffold-generator only after a user-confirmed architecture decision and a lifecycle-approved schema v4 scaffold contract with approved technical and data design prerequisites."