create-yss-spec 3.4.9 → 3.5.0

package/template/.cursor/skills/yss-openapi-draft-review/SKILL.md

@@ -5,6 +5,8 @@ description: "审查 YSS OpenAPI Draft 的需求覆盖、页面动作、响应
 
 # YSS OpenAPI Draft Review
 
+已有生命周期资产优先用 `scripts/contract view <资产> --kind <类型>` 阅读；执行任务用 `--profile task --unit <ID>`，绑定与校验明细用 `--profile full`。视图不授予执行权限，仍按本 Skill 的原始来源和批准门禁处理。类型、准备和迁移见 `docs/process/contract-reading.md`。
+
 Use this skill after OpenAPI Draft creation and before Engineering Baseline / YSS DDD Review. It is a fail-closed contract review skill for design-time OpenAPI files under `docs/.scratch/<feature>/api/`; it does not bundle JSON or generate Orval clients.
 
 ## Required Inputs

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

@@ -5,6 +5,8 @@ description: "维护、校验、冻结或导出 YSS OpenAPI 3.1 设计合同；
 
 # YSS OpenAPI Governance
 
+已有生命周期资产优先用 `scripts/contract view <资产> --kind <类型>` 阅读；执行任务用 `--profile task --unit <ID>`，绑定与校验明细用 `--profile full`。视图不授予执行权限，仍按本 Skill 的原始来源和批准门禁处理。类型、准备和迁移见 `docs/process/contract-reading.md`。
+
 本 skill 负责 YSS OpenAPI 的 **YAML-first** 工作流：
 
 ```text
@@ -114,3 +116,5 @@ pnpm exec redocly bundle \
 ## 输出契约
 
 执行治理或导出时，按 [输出契约](references/governance-output.md) 记录 YAML 权威、当前校验证据、JSON 派生与交接。不能只给自然语言完成声明；未冻结时不生成可供实现消费的 JSON。
+
+API Contract Decision 可用 `scripts/api-contract-decision prepare` 自动生成来源摘要；v1 显式迁移用 `migrate --version <新版本> --output <新路径>`。候选保持 draft，审查、Freeze 绑定和工程契约批准仍由现有生命周期核验。

package/template/.cursor/skills/yss-product-lifecycle/SKILL.md

@@ -1,11 +1,13 @@
 ---
 name: yss-product-lifecycle
-description: 编排 YSS 产品或模块从机会调研到 Spec、原型、技术契约、垂直切片实现、审查、发布和复盘；当阶段、产物、门禁或 YSS skill 不清晰时使用。
+description: 编排 YSS 研发全生命周期；当阶段、产物、门禁或 Skill 路由不清晰时使用。
 ---
 
 # YSS Product Lifecycle
 
-生命周期单一主控：识别请求、仓库身份和最近可信阶段，计算可执行 frontier，派发并验收工作单元；业务设计、实现和独立审查交给专项 skill。
+合同阅读：`scripts/contract view`；见 `docs/process/contract-reading.md`。
+
+主控识别请求、仓库身份和可信阶段，计算 frontier、派发与验收工作单元；专项 Skill 负责设计、实现和独立审查。
 
 文档按 `document_writing` 条件调用 `i-have-adhd`，并传递 `docs/process/document-writing.md` 规范。
 
@@ -21,7 +23,7 @@ description: 编排 YSS 产品或模块从机会调研到 Spec、原型、技术
 | 数字人角色、运行时和会签策略 | `docs/agents/digital-human-roles.yaml` |
 | 影响面、裁剪和模板维护强度 | `docs/process/harness-process-tailoring.md`、`docs/process/maintenance-intensity.yaml` |
 
-使用 `scripts/query-lifecycle-context` 获取确定性 JSON 投影，不要为普通路由整份读取编排合同：
+用 `scripts/query-lifecycle-context` 查询合同：
 
 ```bash
 scripts/query-lifecycle-context --mode route --stage stage.plan --work-unit work-unit.plan-requirements --include execution_efficiency
@@ -54,6 +56,8 @@ Plan 入口读取 `docs/plan/README.md` 和 `docs/process/plan-migration.md`，
 
 聚合批准见 `gate_consolidation`。普通功能默认一个独立审查者，按能力缺口、冲突或外部制度增员；相邻检查组合审查、逐项留证。
 
+项目职责与后端终点见 `execution_scopes`；恢复、编译和派发必须复验。保留产品设计门禁，后端交付不等于业务完成或发布。
+
 ### 用户决定
 
 按角色表 `user_decision_policy` 和 `references/user-decisions.md` 先展示可审阅资产、范围、风险及后续动作，再取得提问者或其指定生物人的原始回复。数字人、超时和默认项不能代答。已有授权优先用 `continuation_ref` 核验延续；未知/实质变化或强制审批缺失才重新决定。缺陷和缺证据阻断，建议记待办；合同、验证及外部动作授权仍须满足。
@@ -71,7 +75,7 @@ Plan 入口读取 `docs/plan/README.md` 和 `docs/process/plan-migration.md`，
 5. 先对照用户目标逐项验收，检查遗漏诉求、错误假设与尚未解决的问题，再验收 `Workflow Execution Result`：工作单元、合同、允许写路径、`context_reconciliation`、证据、实际验证、延期 seam、漂移和下一路由必须可核验。实现派发额外绑定当前 Slice Implementation Contract v3；其他阶段不得伪造该合同。
 6. 在授权边界内继续下一工作单元；遇到人工决定、新授权、证据冲突、专项失败或合并/发布结论时暂停。暂停不得阻断无依赖的独立工作。
 
-每个 `project-instance` 工作单元在申请批准或流转前，先把稳定术语回写到根目录唯一 `CONTEXT.md`，并生成通过校验的 `context_reconciliation`。候选术语、错误路径、摘要漂移或未决冲突必须阻断。质量标准只由 `engineering-baseline` 定义一次；高风险影响按裁剪合同补充反证和残余风险。
+每个 `project-instance` 工作单元批准或流转前，回写稳定术语到唯一根 `CONTEXT.md`，并生成通过校验的 `context_reconciliation`。候选术语、错误路径、摘要漂移或未决冲突必须阻断。质量标准只由 `engineering-baseline` 定义一次；高风险影响按裁剪合同补充反证和残余风险。
 
 ## 面向业务角色
 
@@ -85,10 +89,12 @@ Plan → Spec（含正式草稿、恢复与显式 `to-spec`）写入前，按 `d
 
 ## 结果与暂停
 
-普通咨询直接回答，不创建流程产物；复杂请求简述目标与下一步。实际工作单元仍记录完整结果，按适用边界同步，对外仅展示当前决定所需信息。
+咨询直接回答；工作单元保留完整结果，对外仅展示当前决定所需信息。
 
 工作单元结果至少包含：模式、仓库身份、当前阶段和工作单元、影响面、资产与门禁状态、证据、新鲜度、Ticket/垂直切片/合同状态、`ready-for-agent` 结论、阻塞项、本轮动作、下一工作单元、暂停或继续理由、Ticket 同步和 Git checkpoint 判断。
 
 暂停会签时追加门禁 ID、`role_id`、`runtime_id`、会签文件路径、推荐答案和恢复动作；恢复前运行适用验证器。只有同一候选快照通过全部适用审查轴与 fresh verification，才能提出合并、发布或完成结论；发布仍须生物人决定。
 
 专项合同加载索引见 `references/orchestration.md`。
+
+Plan / Spec / Design 追踪按 `docs/process/stage-tracking.md`。

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

@@ -53,7 +53,7 @@ review_verification:
 
 checkpoint_policy:
   strategy: consolidated
-  flush_on: [human_pause, handoff, implementation_entry, merge, release]
+  flush_on: [stage_exit, human_pause, handoff, implementation_entry, merge, release]
   flush_immediately_on: [blocked, responsibility_changed, asset_approval]
   preserve_stage_causality: true
   required_stage_trace_fields: [stage, upstream_refs, artifact_refs, gate_decisions, downstream_impacts]
@@ -286,7 +286,7 @@ task_package:
 # may prepare, validate and accept their results, but cannot invoke them or create
 # their formal artifacts on their behalf.
 matt_invocation_boundary:
-  user_invoked_skills: [grill-me, grill-with-docs, handoff, implement, improve-codebase-architecture, setup-matt-pocock-skills, to-questionnaire, to-spec, to-tickets, triage, wait-what, wayfinder]
+  user_invoked_skills: [grill-with-docs, handoff, implement, improve-codebase-architecture, setup-matt-pocock-skills, to-questionnaire, to-spec, to-tickets, triage, wait-what, wayfinder]
   lifecycle_managed_user_entries: [setup-matt-pocock-skills, grill-with-docs, to-spec, to-tickets, implement]
   model_invoked_skills: [code-review, codebase-design, diagnosing-bugs, domain-modeling, grilling, prototype, resolving-merge-conflicts, tdd, writing-for-agents, yss-research]
   lifecycle_allowed_model_invoked_skills: [code-review, codebase-design, diagnosing-bugs, domain-modeling, grilling, prototype, tdd, yss-research]
@@ -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: [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-mvc-design, yss-mvc-data-analysis-project-initializer, yss-backend-scaffold-parent, 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]
+  retired_shared_skills: [yss-antd-design, yss-antdv-next-design, ask-matt, batch-grill-me, 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-mvc-design, yss-mvc-data-analysis-project-initializer, yss-backend-scaffold-parent, 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:
@@ -481,6 +481,15 @@ work_unit_routes:
     skills: [yss-ui, yss-design-system, code-review]
     applies_when: ui_impact
     not_applicable_reason: no_ui_impact
+  work-unit.backend-delivery:
+    native: {source: yss-product-lifecycle, skill: yss-product-lifecycle, invocation_mode: model-invoked}
+    primary_skill: yss-product-lifecycle
+    supporting_skills: [code-review]
+    skills: [yss-product-lifecycle, code-review]
+    applies_when: execution_scope_plan_to_backend
+    not_applicable_reason: outside_plan_to_backend_execution_scope
+    verifier: scripts/complete-backend-delivery
+    completion: current-source-and-exported-package-verified
   work-unit.code-review:
     native: {source: yss-product-lifecycle, skill: code-review, invocation_mode: model-invoked}
     primary_skill: code-review
@@ -628,6 +637,11 @@ transition_graph:
     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]
+    work-unit.slice-implementation: [work-unit.frontend-implementation-verification, work-unit.code-review]
+    work-unit.frontend-implementation-verification: [work-unit.code-review]
+    work-unit.code-review: [work-unit.release-and-retrospective, work-unit.slice-implementation, work-unit.backend-delivery]
+    work-unit.backend-delivery: []
+    work-unit.release-and-retrospective: []
   forbidden_shortcuts:
     - {from: work-unit.spec-synthesis, to: work-unit.implementation-repository-preparation}
     - {from: work-unit.prototype-design, to: work-unit.implementation-repository-preparation}
@@ -1030,6 +1044,7 @@ ready_for_agent:
   parent_ticket_as_implementation_ref: forbidden
 
 frontend_implementation_plan:
+  scope_interpretation: product_ui_impact_requires_design_but_only_owned_frontend_implementation_requires_this_plan
   applies_when: [ui_impact]
   required_before: [ready_for_agent]
   required: [prototype_ref, spec_ref, visual_baseline, route_and_page_inventory, baseline_case_ids, desktop_viewport, narrow_viewport, state_cases, pnpm_commands]
@@ -1061,7 +1076,7 @@ impact_propagation:
     targets:
       - {kind: artifact, name: product-design, level: direct, when: ui_impact}
       - {kind: artifact, name: prototype, level: direct, when: ui_impact}
-      - {kind: gate, name: requirement-freeze, level: direct, when: ui_impact}
+      - {kind: gate, name: gate.product-design-approved, level: direct, when: ui_impact}
       - {kind: artifact, name: openapi-draft, level: transitive, when: api_impact}
       - {kind: gate, name: openapi-freeze, level: transitive, when: api_impact}
       - {kind: artifact, name: vertical-slice-tickets, level: transitive, when: always}
@@ -1082,7 +1097,8 @@ impact_propagation:
       - {kind: artifact, name: product-design, level: direct, when: ui_impact}
       - {kind: artifact, name: system-architecture, level: direct, when: always}
       - {kind: artifact, name: data-architecture, level: direct, when: data_impact}
-      - {kind: gate, name: requirement-freeze, level: direct, when: always}
+      - {kind: gate, name: gate.spec-baseline-approved, level: direct, when: always}
+      - {kind: gate, name: gate.product-design-approved, level: direct, when: ui_impact}
       - {kind: artifact, name: openapi-draft, level: transitive, when: api_impact}
       - {kind: gate, name: design-review, level: transitive, when: always}
       - {kind: gate, name: openapi-freeze, level: transitive, when: api_impact}
@@ -1196,3 +1212,50 @@ gate_consolidation:
   invalidation: affected_dependencies_or_authorization_change_only
   historical_gate_records: read_only_no_automatic_approval_migration
   verifier: scripts/verify-lifecycle-checkpoint
+
+# 项目 opt-in 只选择此权威策略，不能传入自定义工作单元白名单。
+execution_scopes:
+  plan-to-backend:
+    activation_ref: .yss-execution-scope.yaml
+    validator: scripts/lib/lifecycle-execution-scope.mjs
+    terminal_work_unit: work-unit.backend-delivery
+    terminal_record: .yss-backend-delivery.json
+    allowed_work_units: [work-unit.entry-triage, work-unit.plan-opportunity, work-unit.plan-requirements, work-unit.domain-strategy-design, work-unit.stage-decision, work-unit.spec-synthesis, work-unit.prototype-design, work-unit.technical-analysis, work-unit.implementation-repository-preparation, work-unit.scaffold-generation, work-unit.ticket-decomposition, work-unit.slice-implementation, work-unit.code-review, work-unit.backend-delivery]
+    route_overrides:
+      work-unit.code-review: [work-unit.slice-implementation, work-unit.backend-delivery]
+      work-unit.slice-implementation: [work-unit.code-review]
+      work-unit.backend-delivery: []
+    product_ui_design: retain-all-triggered-gates
+    implementation_delivery_roles: [backend]
+    implementation_ui_impact: false
+    downstream_frontend_required_when_product_ui_impact: [owner, ticket_ref, verification_plan, target_version]
+    consumer_capabilities: [backend-technical-design]
+    completion_claim: backend-delivery-only
+    business_completion: forbidden
+    release: forbidden
+    resume: revalidate-current-scope-approvals-and-delivery
+
+# Package wire IDs remain immutable; each target resolves its own executable entry.
+consumer_entry_routes:
+  yss-full-lifecycle:
+    backend-technical-design:
+      source_work_unit: work-unit.technical-design
+      target_work_unit: work-unit.technical-analysis
+  plan-to-backend:
+    backend-technical-design:
+      source_work_unit: work-unit.technical-design
+      target_work_unit: work-unit.technical-analysis
+  harness.backend-delivery:
+    backend-technical-design:
+      source_work_unit: work-unit.technical-design
+      target_work_unit: work-unit.technical-design
+
+stage_tracking:
+  contract: docs/process/stage-tracking.md
+  schema: docs/process/schemas/stage-tracking.schema.json
+  verifier: scripts/stage-tracking
+  configuration: tracker.lifecycle_tracking_version
+  machine_state_owner: checkpoint.stage_tracking
+  transition_checkpoint_ref: checkpoint_ref
+  flush_on: [stage_exit, blocked, responsibility_changed, asset_approval]
+  preserves: [ticket-state, gate-approval, profile-scope]

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

@@ -4,14 +4,14 @@
 
 1. 按 `orchestration-contract.yaml.request_triage` 理解请求并选择模式，再识别仓库身份、任务规模和影响面；问题理解与澄清细节见 [请求分诊协议](request-triage.md)。
 2. `setup readiness`：每个任务只执行一次，核对 tracker、五态标签和领域文档布局，并在本轮缓存结果；仅在 tracker、主远端、真实标签或配置变化时重查。
-3. 加载父 Ticket/checkpoint 与真实资产，计算最近可信阶段。
+3. 加载父 Ticket/checkpoint 与真实资产，计算最近可信阶段；按 `docs/process/stage-tracking.md` 登记、恢复并核验当前阶段工作项，写入前确保 checkpoint 已持久化，工作单元结果带 checkpoint_ref。
 4. 评估资产、门禁和 `stale`，选择第一个未阻塞工作单元。进入 `work-unit.slice-implementation` 前，必须先通过 `scripts/lib/lifecycle-transition.mjs` 的 Ticket 正式化、垂直切片绑定和合法 `next_route` 校验；父 Ticket、缺少垂直切片或 `ready-for-human` 的切片一律 `blocked`。
 5. 执行最小生命周期工作单元：主控先按 `docs/process/schemas/digital-human-task-package.schema.json` 编译并校验任务包，再只实际调用允许的 model-invoked skill；原生工作单元可直接持有正式资产，Matt 兼容 user-invoked skill 仅作为 workflow reference，仍由用户显式启动。将结果归一化为 `Workflow Execution Result`，验收输出并回写状态与证据。任务包的 `contract.kind` 按工作单元选择；只有实现子任务使用 `slice-implementation` 并消费 Slice Implementation Contract，其他阶段不伪造该合同。
 6. 若仍在授权和自动推进边界内，回到第 3 步；否则暂停。
 
 不要仅输出下一个提示词后结束 `orchestrate`/`resume`。不要因进入业务代码阶段而退出主控；应把实现交给专项 skill，并在返回后继续核验。
 
-连续阶段自动推进时累积 Ticket 同步和 Git 判断证据，在人工暂停、handoff、进入实现、合并或发布边界集中 checkpoint。发生阻塞、责任人变化或资产需要单独批准时立即落 checkpoint，不因合并记录而丢失阶段因果关系。
+连续阶段自动推进时累积 Ticket 同步和 Git 判断证据，在阶段退出、人工暂停、handoff、进入实现、合并或发布边界集中 checkpoint。发生阻塞、责任人变化或资产需要单独批准时立即落 checkpoint，不因合并记录而丢失阶段因果关系。
 
 ## 执行成本
 

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

@@ -83,17 +83,17 @@ Git 动作分别保存 `commit_authorized`、`commit_scope`、`commit_authorizat
 lifecycle:
   schema_version: 1
   mode: resume
-  stage: system-data-architecture-and-contract-review
-  status: blocked
+  stage: stage.spec-architecture
+  status: needs-human
 workflow:
   matt_flow: main
-  active_skill: yss-openapi-draft-review
+  active_skill: yss-product-lifecycle
   status: paused
 artifacts:
-  spec: {status: approved, ref: docs/.scratch/example/spec.md}
+  spec: {status: ready-for-human, ref: docs/.scratch/example/spec.md}
   openapi: {status: stale, ref: docs/.scratch/example/api/example.yaml, stale_by: [spec]}
 gates:
-  openapi_freeze: {status: stale}
+  gate.spec-baseline-approved: {status: needs-human}
 tracker:
   kind: local-markdown
   root: docs/.scratch
@@ -101,10 +101,10 @@ tracker:
   role: ready-for-human
 pause:
   reason_code: human-gate
-  gate_ref: requirement-freeze
+  gate_ref: gate.spec-baseline-approved
   owner_or_authority: product-owner
-  resume_condition: requirement-freeze-approved
-  next_work_unit: api-impact-assessment
+  resume_condition: gate.spec-baseline-approved approved
+  next_work_unit: work-unit.technical-analysis
 ```
 
 ## Schema 兼容与迁移

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

@@ -5,6 +5,8 @@ description: Use when a YSS feature has product-design impact on a primary flow,
 
 # YSS Prototype Stage
 
+已有生命周期资产优先用 `scripts/contract view <资产> --kind <类型>` 阅读；执行任务用 `--profile task --unit <ID>`，绑定与校验明细用 `--profile full`。视图不授予执行权限，仍按本 Skill 的原始来源和批准门禁处理。类型、准备和迁移见 `docs/process/contract-reading.md`。
+
 把产品设计影响收敛为跨 Agent 一致的原型交付物、证据和生命周期回流合同。它不替代 `yss-product-lifecycle` 的门禁裁决，也不把原型当作生产前端代码。
 
 文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `docs/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。
@@ -51,7 +53,7 @@ Design QA 合并 visual、layout、interaction、content、accessibility、cross
 ## 按需读取
 
 - 档位、上游融合与迁移：[prototype-profile-routing.md](references/prototype-profile-routing.md)
-- 渲染适配、fact pack 与命令：[product-design-adapter.md](references/product-design-adapter.md)
+- 离线渲染适配与命令：[product-design-adapter.md](references/product-design-adapter.md)
 - 证据模板：`docs/design/templates/prototype-evidence-template.yaml`
 - Visual Baseline 模板与 schema：`docs/design/templates/visual-baseline-template.yaml`、`docs/design/schemas/visual-baseline.schema.json`
 
@@ -59,7 +61,7 @@ Design QA 合并 visual、layout、interaction、content、accessibility、cross
 
 - 把 H1/H2 当作低/高保真；把离线 HTML 降为静态截图，或继续要求 Provider、Node starter、预先生成图片。
 - 低保真未评审就选择技术栈；用主观评分代替确定性触发规则。
-- 空填 lockfile/fact pack；把自身生成图当成独立来源，或宣称已验证生产真实组件。
+- 编造组件版本或构建来源；把自身生成图当成独立来源，或宣称已验证生产真实组件。
 - 重复抄写机器可采集的版本、digest、截图和 console；创建第二份状态机、QA 或 handoff 资产。
 - 把原型源码直接复制进生产，或在原型阶段调用 `yss-ui`。
 

package/template/.cursor/skills/yss-prototype-stage/scripts/visual-baseline-contract.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { createHash } from "node:crypto";
-import { existsSync } from "node:fs";
-import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { existsSync, readFile, readdir } from "../../../../scripts/lib/validation-phase.mjs";
+import { mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { parseDocument, stringify } from "../../../../scripts/vendor/yaml.mjs";

package/template/.cursor/skills/yss-repository/SKILL.md

@@ -29,6 +29,7 @@ description: 用于按批准的 YSS 架构与持久化合同实现或重构 PO
 <a id="repository.mapping"></a>
 <!-- yss-rule {"id":"repository.mapping","when":"persistence","level":"mandatory","evidence":"code-and-verification"} -->
 - 数据合同必须显式覆盖主键、逻辑删除、审计字段、空值、枚举/值对象映射和敏感字段；动态排序、分组与过滤必须使用批准白名单和参数绑定。
+- 数据合同选择 YSS 分布式主键时，记录已选 `component.distributed-id` 绑定、Segment/Snowflake 策略、实体主键类型与批量插入路径，并消费 `yss-distributed-id` 的当前平台证据；不由 Repository 自行切换算法或创建发号合同。
 <a id="repository.transaction"></a>
 <!-- yss-rule {"id":"repository.transaction","when":"persistence","level":"mandatory","evidence":"code-and-verification"} -->
 - 事务归所选 Profile 的用例边界。Repository/Gateway Adapter 不临时新增业务事务，也不把数据库异常原文或凭据暴露给上层。

package/template/.cursor/skills/yss-stage-decision/SKILL.md

@@ -5,6 +5,8 @@ description: 编排 Plan 到 Spec 入口的方案决策与业务边界、协作
 
 # YSS Stage Decision
 
+已有生命周期资产优先用 `scripts/contract view <资产> --kind <类型>` 阅读；执行任务用 `--profile task --unit <ID>`，绑定与校验明细用 `--profile full`。视图不授予执行权限，仍按本 Skill 的原始来源和批准门禁处理。类型、准备和迁移见 `docs/process/contract-reading.md`。
+
 `yss-stage-decision` 是由生命周期主控调度的上游决策技能，负责把需求、产品、商务输入和业务边界与规则设计结果整理成可审查、可版本化、可被下游消费的方案决策包。它不替代生命周期主控，也不生成产品代码、原型、OpenAPI 或垂直切片 Ticket。
 
 文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `docs/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。

package/template/.cursor/skills/yss-tactical-design/SKILL.md

@@ -5,6 +5,8 @@ description: 在 YSS 技术分析阶段将批准的战略领域输入细化为
 
 # yss-tactical-design
 
+已有生命周期资产优先用 `scripts/contract view <资产> --kind <类型>` 阅读；执行任务用 `--profile task --unit <ID>`，绑定与校验明细用 `--profile full`。视图不授予执行权限，仍按本 Skill 的原始来源和批准门禁处理。类型、准备和迁移见 `docs/process/contract-reading.md`。
+
 本 skill 负责 DDD 战术设计，不新增生命周期主阶段，也不替代 `yss-stage-decision` 或 `yss-domain`。
 
 ## 适用边界

package/template/.cursor/skills/yss-technical-design/SKILL.md

@@ -5,6 +5,8 @@ description: 在 YSS 技术分析中统一承接需求与战略输入，按已
 
 # YSS 技术设计
 
+已有生命周期资产优先用 `scripts/contract view <资产> --kind <类型>` 阅读；执行任务用 `--profile task --unit <ID>`，绑定与校验明细用 `--profile full`。视图不授予执行权限，仍按本 Skill 的原始来源和批准门禁处理。类型、准备和迁移见 `docs/process/contract-reading.md`。
+
 由 `yss-product-lifecycle` 调度，负责 `work-unit.technical-analysis` 的技术设计，不另起生命周期、不生成生产代码。生命周期维护批准和状态；`yss-implementation-contract-compiler` 消费批准且当前的设计，起草实现合同。
 
 文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `docs/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。

package/template/.cursor/skills/yss-technical-design/scripts/engineering-design.mjs

@@ -1,5 +1,5 @@
 import path from 'node:path';
-import {readFileSync} from 'node:fs';
+import {readFileSync} from '../../../../scripts/lib/validation-phase.mjs';
 import {ensure,read,safe,hash} from '../../../../scripts/lib/strategic-handoff-io.mjs';
 const beneath=(ref,scope)=>ref===scope||ref.startsWith(`${scope}/`);
 export function validateEngineeringDesign(data,{root}) {

package/template/.cursor/skills/yss-technical-design/scripts/validate-technical-design.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { readFileSync } from 'node:fs';
+import { readFileSync, withValidationPhase, validationDependencies } from '../../../../scripts/lib/validation-phase.mjs';
 import { validateEngineeringDesign } from './engineering-design.mjs';
 import { createApprovedExecutionContext, assertApprovedExecutionContext } from '../../../../scripts/lib/approved-execution-context.mjs';
 import { verifyArchitectureEvidence } from '../../../../scripts/lib/backend-architecture.mjs';
@@ -42,8 +42,8 @@ function validateMvc(design) {
   if (!design.integration_catalog.length) ensure(text(design.integration_not_applicable_reason), '无外部集成必须说明原因');
 }
 
-export function verifyArchitecture(data, root, {execution,sliceRef}={}) {
-  if(execution)assertApprovedExecutionContext(execution,{root,technicalDesign:data,sliceId:sliceRef});
+export function verifyArchitecture(data, root, {execution,sliceRef,readOnly=false}={}) {
+  if(execution)assertApprovedExecutionContext(execution,{root,technicalDesign:data,sliceId:sliceRef,readOnly});
   const binding = data.architecture;
   const file = safe(root, binding.decision_ref);
   ensure(hash(readFileSync(file)) === binding.decision_digest, '架构来源摘要漂移');
@@ -63,7 +63,7 @@ export function verifyArchitecture(data, root, {execution,sliceRef}={}) {
     ensure(!['stale','blocked'].includes(record.status) && !['stale','blocked'].includes(entry.status), '工程登记已失效');
     if (entry.architecture_identity?.schema_version === 2) {
       ensure(entry.architecture_evidence?.engineering_baseline && entry.architecture_evidence?.manifest, '既有工程登记缺少原始工程证据引用');
-      verifyArchitectureEvidence(entry.architecture_identity, { ...entry.architecture_evidence, repository_registration: { ref: binding.decision_ref, digest: binding.decision_digest } }, { root, execution });
+      verifyArchitectureEvidence(entry.architecture_identity, { ...entry.architecture_evidence, repository_registration: { ref: binding.decision_ref, digest: binding.decision_digest } }, { root, execution, readOnly });
     }
   }
 }
@@ -111,7 +111,7 @@ export async function validateTechnicalDesign(data, { root = process.cwd(), slic
   ensure(data.digest === technicalDigest(data), '技术设计合同摘要不匹配');
   ensure(!['stale','blocked','drift','new_impacts'].includes(data.status), '设计状态不可消费');
   if (sliceRef) ensure(data.status === 'approved', '切片只能消费 approved 设计');
-  verifyArchitecture(data, root, {execution,sliceRef});
+  verifyArchitecture(data, root, {execution,sliceRef,readOnly});
   ensure(data.inputs.some(item => item.kind === 'context' && item.ref === 'CONTEXT.md') && data.inputs.some(item => item.kind === 'spec'), '共同输入缺少根 CONTEXT.md 或 Spec');
   for (const input of data.inputs) ensure(hash(readFileSync(safe(root, input.ref))) === input.digest, `输入摘要漂移: ${input.ref}`);
   for (const ref of data.evidence_refs) safe(root, ref);
@@ -135,12 +135,15 @@ export async function validateTechnicalDesign(data, { root = process.cwd(), slic
 }
 
 async function main() {
-  const { values, positionals } = parseArgs({ allowPositionals: true, options: { root: { type: 'string', default: process.cwd() }, slice: { type: 'string' }, 'legacy-ddd': { type: 'boolean', default: false }, 'read-only': {type:'boolean',default:false}, 'work-unit': {type:'string'}, 'approved-slice': {type:'string'}, 'approved-slice-digest': {type:'string'}, 'approved-slice-approval': {type:'string'} } });
+  const { values, positionals } = parseArgs({ allowPositionals: true, options: { root: { type: 'string', default: process.cwd() }, slice: { type: 'string' }, 'legacy-ddd': { type: 'boolean', default: false }, 'read-only': {type:'boolean',default:false}, 'validation-dependencies': {type:'boolean',default:false}, 'work-unit': {type:'string'}, 'approved-slice': {type:'string'}, 'approved-slice-digest': {type:'string'}, 'approved-slice-approval': {type:'string'} } });
   ensure(positionals.length === 1, '用法: validate-technical-design.mjs <合同> --root <项目根> [--slice <ID>] [--legacy-ddd]');
   const approvedOptions=['approved-slice','approved-slice-digest','approved-slice-approval'];
   ensure(!approvedOptions.some(key=>values[key])||approvedOptions.every(key=>values[key]),'执行增量必须完整给出持久化 Slice、字节摘要及本地批准引用');
-  const execution=values['approved-slice']?createApprovedExecutionContext({ref:values['approved-slice'],digest:values['approved-slice-digest'],approval_ref:values['approved-slice-approval']},{root:values.root,work_unit_id:values['work-unit']}):undefined;
+  const output=await withValidationPhase({root:values.root,purpose:'technical-design',slice_id:values.slice,work_unit_id:values['work-unit'],readOnly:values['read-only']},async()=>{
+  const execution=values['approved-slice']?createApprovedExecutionContext({ref:values['approved-slice'],digest:values['approved-slice-digest'],approval_ref:values['approved-slice-approval']},{root:values.root,work_unit_id:values['work-unit'],readOnly:values['read-only']}):undefined;
   const result = await validateTechnicalDesign(read(path.resolve(positionals[0])), { root: values.root, sliceRef: values.slice, legacyDdd: values['legacy-ddd'], readOnly:values['read-only'], execution });
-  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  return values['validation-dependencies']?{...result,validation_dependencies:validationDependencies()}:result;
+  });
+  process.stdout.write(`${JSON.stringify(output, null, 2)}\n`);
 }
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) main().catch(error => { process.stderr.write(`${JSON.stringify({ result: 'blocked', errors: [error.message] })}\n`); process.exitCode = 1; });

package/template/.pi/skills/yss-cache/SKILL.md

@@ -10,8 +10,8 @@ description: "接入或排查 YSS QueryCache、UpdateCache、ClearCache、TTL、
 ## 工作流
 
 1. 按 `yss-skill-source-index-refresh/references/source-location.md` 定位真实源码。当前工作区有 `.codegraph/` 时先用 CodeGraph；否则读取 [source-index.md](references/source-index.md) 后用符号或 Maven 模块搜索。
-2. 识别使用模型：Spring Cache 单后端路由、Redis 故障降级，或 JetCache local + remote。不要混用三者的行为假设。
-3. 明确缓存名、key、TTL、更新/删除路径、跨节点一致性和序列化兼容要求。
+2. 识别使用模型：Spring Cache 单后端路由、Redis 故障处理，或独立的 JetCache local + remote。`fail-fast`/`bypass`/`fallback` 是当前 Boot 3 Redis 契约；Boot 2 以其独立源码索引为准，不要混用两代或三种模型的行为假设。
+3. 明确缓存名、key、区域 TTL/容量/空值策略、更新/删除路径、跨节点一致性和序列化兼容要求。
 4. 先检查现有依赖、启动注解、配置和注解用法，再决定修改业务代码、配置还是组件。
 5. 修改后执行对应 reference 的验证；组件跨模块修改必须从父 reactor 构建，不要依赖本地旧 SNAPSHOT。
 
@@ -20,13 +20,14 @@ description: "接入或排查 YSS QueryCache、UpdateCache、ClearCache、TTL、
 - 新增查询缓存时同时覆盖更新、删除和状态变更的失效路径。
 - key 必须稳定并显式包含租户、机构、账套等隔离维度；不要依赖 DTO 的不稳定序列化结果。
 - 不要把 Redis fallback 当作正常二级缓存。Caffeine fallback 存在节点间不一致窗口。
-- 不要声称纯 Redis 后端会广播本地缓存失效。只有确认 JetCache 配置了 local、remote 和 broadcast channel 后才能作此判断。
+- 不要声称纯 Redis 后端会广播本地缓存失效。JetCache 即使存在 broadcast channel 配置，也须验证实际 local/remote 实例和同步开关后才能作此判断。
 - 不要在没有双读、版本前缀、灰度清理或迁移窗口时修改 serializer、key prefix 或 cache name。
 - 不明确一致性要求时，不默认启用本地缓存或 fallback。
 
 ## 按场景读取
 
 - 模块、后端选择或多级缓存边界：[architecture.md](references/architecture.md)
+- JetCache 包装器、`QuickConfig`、跨 JVM 失效与故障边界：[jetcache.md](references/jetcache.md)
 - 新增或修改缓存注解、SpEL、空 key、全量清理：[annotations.md](references/annotations.md)
 - 依赖、启动注解、TTL、Caffeine/Hazelcast、Bean backoff：[configuration.md](references/configuration.md)
 - Redis 单机、哨兵、集群、认证、SSL、超时、Jedis pool：[redis-topology.md](references/redis-topology.md)
@@ -38,10 +39,10 @@ description: "接入或排查 YSS QueryCache、UpdateCache、ClearCache、TTL、
 ## 工具
 
 - `scripts/inspect-cache-usage.sh <project-root>`：只读扫描消费项目；发现阻断缺陷返回 1，输入或环境错误返回 2。
-- `scripts/verify-cache-component.sh [--source-root PATH] [--consumer-root PATH --consumer-module MODULE]`：验证组件、真实 Redis、Java 8 字节码及可选消费模块。
+- `scripts/verify-cache-component.sh --platform-line <boot2-java8|boot3-java17> [--source-root PATH] [--consumer-root PATH --consumer-module MODULE]`：从匹配的平台源码根干净构建，验证组件、可用时的真实 Redis、对应 Java 字节码及可选消费模块。
 - `scripts/check-skill-freshness.sh <boot2-java8|boot3-java17> [source-root]`：比较所选平台线的技能契约与当前组件源码；发现平台错配或漂移返回 1。
 
-当组件源码变化后，用 `yss-skill-source-index-refresh` 刷新 [source-index.md](references/source-index.md)，再运行 freshness 检查。不要手工修改生成索引。
+本 Skill 中新增的 `failure-mode`、区域策略和 `empty-key-eviction` 指引针对当前 Boot 3 组件；Boot 2 的精确配置与默认值须查其独立索引及源码。组件源码形成干净、固定的来源后，用 `yss-skill-source-index-refresh` 刷新所选平台的生成索引，再运行 freshness 检查。`source-index.md` 是平台选择页；不要手工修改生成索引或把 dirty 工作树的观察说成已核验事实。
 
 ## 平台与源码门禁
 

package/template/.pi/skills/yss-cache/references/annotations.md

@@ -1,5 +1,7 @@
 # 注解契约
 
+以下 `empty-key-eviction` 可配置行为针对当前 Boot 3 / Java 17 组件；Boot 2 的空 key 处理以其独立源码索引和当前源码为准。
+
 ## 映射
 
 - `@QueryCache` -> Spring `CacheableOperation`。
@@ -28,7 +30,7 @@ public void delete(String tenantId, Long planId) { ... }
 ```
 
 - 未配置 key 时由 Spring KeyGenerator 生成；无参数方法会得到 `SimpleKey.EMPTY`。
-- 当前 YSS 拦截器将 `SimpleKey.EMPTY` 视为全量清理。需要单 key 清理时必须给出稳定 key。
+- 当前 Boot 3 的 `yss.cache.empty-key-eviction=legacy-clear`（默认）把 `SimpleKey.EMPTY` 当作清区；`evict` 时只删该 key。迁移前核对原有无参数清理调用及实际属性，不能把默认行为说成所有配置下的不变量。
 - 全量清理优先显式写 `allEntries=true`，不要依赖偶然 key 形态。
 - 集合参数先稳定排序；null、大小写和空白必须归一化。
 

package/template/.pi/skills/yss-cache/references/architecture.md

@@ -1,12 +1,14 @@
 # 架构与选择
 
+以下模型划分适用于接入决策；具体配置、默认值及跨节点行为按所选平台线的当前源码核验。本轮新增的 Redis 故障模式、区域策略和 JetCache 运行证据属于 Boot 3 当前组件。
+
 ## 三种模型
 
 | 模型 | 行为 | 一致性边界 |
 |---|---|---|
 | Spring Cache 后端路由 | `yss.cache.active-type` 在 Redis、Caffeine、Hazelcast 中选择一个 Provider | 同一时刻是单后端，不是多级缓存 |
 | Redis fallback | Redis 故障时可临时改用另一个 Provider | 是故障降级；Caffeine 会产生节点间不一致窗口 |
-| JetCache | 独立扩展，可配置 local + remote | 只有实际配置 broadcast channel 才能认为本地失效会同步 |
+| JetCache | 独立扩展，可配置 local + remote | broadcast channel 配置本身不证明包装器已启用跨 JVM 本地失效同步 |
 
 ## 模块
 
@@ -22,4 +24,4 @@
 - 跨节点共享且不接受节点本地旧值：使用纯 Redis。
 - 读多写少并允许短暂节点差异：可选择 Caffeine。
 - Redis 故障期间业务可用性高于缓存一致性：评估后启用 fallback。
-- 需要 local + remote：先确认 JetCache 的 local、remote、序列化和广播配置，不要只看依赖名称。
+- 需要 local + remote：按 [JetCache 专项参考](jetcache.md) 核对实际创建的 Cache、配置来源及首次创建参数，并用跨 JVM 测试证明同步，不要只看依赖或 `bootstrap.yml`。

package/template/.pi/skills/yss-cache/references/configuration.md

@@ -13,20 +13,23 @@
 
 ## 公共属性
 
+以下示例及 `failure-mode`、区域策略、空值策略说明针对当前 Boot 3 / Java 17 组件。Boot 2 / Java 8 维护须先核对其独立源码索引与匹配源码，不套用这些新属性或默认值。
+
 ```yaml
 yss:
   cache:
     active-type: redis       # redis | caffeine | hazelcast
     default-ttl: 1h
+    failure-mode: fail-fast  # fail-fast | bypass | fallback；仅 active-type=redis
     redis:
       fallback-enabled: false
       fallback-type: caffeine
       clear-fallback-on-recovery: true
 ```
 
-- Redis 动态 cache 和 Caffeine 默认 TTL 使用 `yss.cache.default-ttl`。
-- `CacheKeyCode` 中声明的 TTL 覆盖默认 TTL。
-- Caffeine 的 `spring.cache.caffeine.spec` 可覆盖默认构建规格，修改前检查项目现有配置。
+- `failure-mode` 默认 fail-fast；旧 `redis.fallback-enabled=true` 仍映射 fallback，同时配置为冲突值会拒绝启动。bypass 仅将 Redis 连接/资源故障的查询视为 miss，显式写入和失效仍报告错误；业务与序列化异常不降级。fallback 仅可选择已安装的 Caffeine，不是默认二级缓存。
+- 区域 `yss.cache.regions[区域名]` 可逐字段设置 `ttl`、`caffeine-maximum-size`、`null-policy`。TTL 以区域值优先；Caffeine 用户显式过期策略、`CacheKeyCode` 与 `default-ttl` 的实际优先级按当前组件源码核对。`null-policy=cache` 必须指定正的区域 TTL；`skip` 不等于删除旧值，`reject` 的契约错误不能吞成 Redis 故障。
+- Caffeine `spring.cache.caffeine.spec`、自定义 Builder/Loader 与区域覆盖的组合可能无法表达；核对当前组件的启动拒绝条件。自定义 CacheManager/Provider 时需证明区域策略真实生效，不能因配置存在就宣称 TTL、容量或空值策略已应用。
 - Hazelcast 不在 starter 生产依赖中；使用时显式引入模块并配置 `active-type=hazelcast`。
 
 ## 自定义 Bean

package/template/.pi/skills/yss-cache/references/jetcache.md

@@ -0,0 +1,21 @@
+# JetCache 独立接入与验证
+
+本页记录当前 Boot 3 / Java 17 `yss-component-jetcache` 工作树的接入判断；Boot 2 的精确能力以其平台索引和匹配源码为准。JetCache 与 YSS Spring Cache 是两条独立入口，不继承 `yss.cache.active-type`、区域 TTL 或 Redis `failure-mode`。
+
+## 先确认实际入口
+
+- 检查运行时上游 `CacheManager`、local/remote builder、应用自己的 JetCache 配置及实际创建的 area/name。依赖 JAR 中有 `bootstrap.yml` 不证明应用加载了它；无有效 local builder 时，LOCAL 请求可能在运行时失败。
+- 组件兼容包装器的两参数 `getCache` 默认 TTL 为 5 分钟，重载接收 `Duration`；它不设置 `syncLocal`、loader 或刷新策略。包装器的类型映射也不证明 LOCAL 实际采用 Caffeine。需要这些能力时核对原生 `QuickConfig` 与上游管理器。
+- 管理器按 area/name 复用已创建缓存。类型、TTL、`syncLocal` 等参数在第一次创建时确定，后续 `getOrCreateCache` 不会重建同名缓存；修改配置须使用新名称或明确的生命周期切换。
+
+## 跨 JVM 本地失效
+
+原生 `QuickConfig` 选择 `BOTH`、设置 `syncLocal(true)`，并为所有参与节点配置兼容的 `jetcache.remote.default.broadcastChannel`、编码及相同 area/name。包装器即使存在广播频道也不会自行开启 `syncLocal`；缺频道时不能据 `syncLocal(true)` 宣称已同步。
+
+验收时启动两个独立 JVM，在两端创建同名缓存，确认广播订阅实际建立后，从一端更新和删除并观察另一端本地值失效；同时用未同步的对照缓存确认失效范围。广播是异步通知，不承诺强一致或断连期间的持久补偿。
+
+## 故障与数据格式
+
+- 读取 `CacheResult` 状态来区分未命中和故障；便利 `get`/`getValue` 可能将远端故障折叠为 `null`。REMOTE 与 BOTH 的故障结果也不同，不能套用主线 Redis 的 fail-fast/bypass/fallback。
+- JetCache Java 编码保存 `CacheValueHolder`，与 Spring RedisCache 的 JDK 业务值及 RedisTemplate 的 Jackson 值不同。缓存名称、key 前缀或 serializer 迁移前，核对实际物理 key 和兼容方案，避免混写。
+- 包装器不提供主线缓存的事务后提交协调。刷新须核对原生 loader 与 refresh policy 是否同时配置；本轮未验证多节点刷新去重、断连补偿或生产 SLA。

package/template/.pi/skills/yss-cache/references/redis-fallback.md

@@ -1,11 +1,13 @@
 # Redis 故障降级与恢复
 
+以下故障模式和脏 Redis 区域恢复顺序是当前 Boot 3 / Java 17 组件契约。Boot 2 / Java 8 的故障处理和恢复默认值须单独核对其索引及源码。
+
 ## 状态流
 
 ```text
 Redis 健康 -> 命令或健康检查失败 -> 标记不健康 -> 跳过 Redis
 -> 可选 fallback -> 周期健康检查 -> Redis 可连接
--> 清理脏 Redis cache 与本地 fallback cache -> 恢复 Redis
+-> 清理脏 Redis cache；按配置清理本地 fallback cache -> 恢复 Redis
 ```
 
 - fallback 默认关闭，默认目标是 Caffeine。
@@ -13,11 +15,11 @@ Redis 健康 -> 命令或健康检查失败 -> 标记不健康 -> 跳过 Redis
 - Redis 命令级连接故障也会立即报告不健康，不必等待下一轮检查。
 - 只读 fallback 不标记 Redis cache 为脏。
 - put、putIfAbsent、evict、clear、invalidate 和 valueLoader 产生的回退写入会标记为脏。
-- 恢复时先清理降级期间发生写操作的 Redis cache，再清理本地 fallback cache。
+- 恢复时始终先清理降级期间发生写操作的 Redis cache；`clear-fallback-on-recovery=true` 时还清理本地 fallback cache。
 - Redis 失效失败时继续保持不健康状态并在后续检查重试，不能提前切回旧 Redis 数据。
 
 ## 一致性判断
 
 - Caffeine fallback 是每节点独立数据，不能保证跨节点读到相同值。
-- `clear-fallback-on-recovery=false` 会跳过恢复清理，可能重新暴露 Redis 旧值；除非业务明确接受，不要关闭。
+- `clear-fallback-on-recovery=false` 只跳过本地备用缓存清理，不跳过脏 Redis 区域失效。Redis 失效失败时不切回；关闭本地清理仍须评估后续备用使用时的本地旧值窗口。
 - 强一致、锁、幂等状态或余额类数据不应依赖缓存 fallback 保证正确性。