create-yss-spec 3.4.8 → 3.4.10

package/template/docs/process/schemas/stage-tracking.schema.json

@@ -0,0 +1,259 @@
+{
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "feature_id",
+    "checkpoint_ref",
+    "entry_stage",
+    "entry",
+    "items"
+  ],
+  "properties": {
+    "schema_version": {
+      "const": 1
+    },
+    "feature_id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "checkpoint_ref": {
+      "type": "string",
+      "minLength": 1
+    },
+    "entry_stage": {
+      "type": "string",
+      "minLength": 1
+    },
+    "entry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "kind",
+        "ref"
+      ],
+      "properties": {
+        "kind": {
+          "enum": [
+            "parent-ticket",
+            "checkpoint"
+          ]
+        },
+        "ref": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "items": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "id",
+          "kind",
+          "title",
+          "stage",
+          "work_unit",
+          "owner",
+          "scope",
+          "acceptance",
+          "dependencies",
+          "source_refs",
+          "progress",
+          "split_reasons",
+          "completion"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9-]*$"
+          },
+          "kind": {
+            "const": "stage-work-item"
+          },
+          "title": {
+            "type": "string",
+            "minLength": 1
+          },
+          "stage": {
+            "type": "string",
+            "minLength": 1
+          },
+          "work_unit": {
+            "type": "string",
+            "minLength": 1
+          },
+          "owner": {
+            "type": "string",
+            "minLength": 1
+          },
+          "scope": {
+            "type": "string",
+            "minLength": 1
+          },
+          "acceptance": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1
+            },
+            "minItems": 1,
+            "uniqueItems": true
+          },
+          "dependencies": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1
+            },
+            "uniqueItems": true
+          },
+          "source_refs": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "ref",
+                "digest"
+              ],
+              "properties": {
+                "ref": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "digest": {
+                  "type": "string",
+                  "pattern": "^sha256:[0-9a-f]{64}$"
+                }
+              }
+            }
+          },
+          "progress": {
+            "enum": [
+              "pending",
+              "running",
+              "blocked",
+              "completed",
+              "cancelled"
+            ]
+          },
+          "split_reasons": {
+            "type": "array",
+            "items": {
+              "enum": [
+                "different-owner",
+                "independent-acceptance",
+                "blocks-other-work",
+                "cross-stage-deferral"
+              ]
+            },
+            "uniqueItems": true
+          },
+          "completion": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "criterion",
+                "evidence_refs"
+              ],
+              "properties": {
+                "criterion": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "evidence_refs": {
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": [
+                      "ref",
+                      "digest"
+                    ],
+                    "properties": {
+                      "ref": {
+                        "type": "string",
+                        "minLength": 1
+                      },
+                      "digest": {
+                        "type": "string",
+                        "pattern": "^sha256:[0-9a-f]{64}$"
+                      }
+                    }
+                  },
+                  "minItems": 1
+                }
+              }
+            }
+          },
+          "definition_ref": {
+            "type": "string",
+            "minLength": 1
+          },
+          "definition_digest": {
+            "type": "string",
+            "pattern": "^sha256:[0-9a-f]{64}$"
+          },
+          "recheck_required": {
+            "type": "boolean"
+          },
+          "cancellation_reason": {
+            "type": "string",
+            "minLength": 1
+          },
+          "deferred": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "owner",
+              "resolve_by",
+              "receiver",
+              "verification_plan",
+              "decision_ref",
+              "risk",
+              "follow_up_ref"
+            ],
+            "properties": {
+              "owner": {
+                "type": "string",
+                "minLength": 1
+              },
+              "resolve_by": {
+                "type": "string",
+                "format": "date-time"
+              },
+              "receiver": {
+                "type": "string",
+                "minLength": 1
+              },
+              "verification_plan": {
+                "type": "string",
+                "minLength": 1
+              },
+              "decision_ref": {
+                "type": "string",
+                "minLength": 1
+              },
+              "risk": {
+                "type": "string",
+                "minLength": 1
+              },
+              "follow_up_ref": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://yss.dev/schemas/stage-tracking.schema.json",
+  "title": "阶段工作追踪 v1"
+}

package/template/docs/process/stage-tracking.md

@@ -0,0 +1,62 @@
+# Plan / Spec / Design 阶段工作追踪
+
+本合同由主 tracker 与生命周期编排器消费。阶段、注册工作单元及父 Ticket 创建时点以生命周期注册表为准；工作项结构以 `schemas/stage-tracking.schema.json` 为准。
+
+## 启用与职责
+
+`docs/agents/issue-tracker.md` 的 `tracker.lifecycle_tracking_version: 1` 表示项目已启用。新初始化默认启用；attach / sync 保留已有配置，未声明的旧项目不自动启用。只读检查不修改项目；旧项目先 plan 再显式 apply。模板源只维护机制，不在模板根生成产品工作项。
+
+完整研发从 Plan（或接入的最近可信阶段）建立唯一父 Ticket。Design 继续使用 checkpoint / map，不创建工程父 Ticket。Backend / Frontend 只消费已交接资产，不因本协议取得 Plan、Spec 或产品设计的编写权限。Dev 消费主模板的同一协议。
+
+checkpoint 的 `stage_tracking` 是阶段工作项当前进度的唯一机器状态源。父 Ticket、map、远程镜像只引用它。业务 Ticket 与工程切片仍由现有 tracker 管理；本协议不替代 Ticket 五态、业务批准、工作单元结果或实现合同。
+
+## 工作项
+
+同一负责人可连续完成的小工作以内联项记录。不同负责人、独立验收、阻塞其他工作或跨阶段延期时创建 `work-items/<id>.md`，类型为 `stage-work-item`。`issues/` 继续承载各 profile 的业务 Ticket / 实现切片。
+
+工作项包含 ID、标题、阶段、注册工作单元、负责人、范围、验收条件、依赖、源资产摘要、进度和验收证据；独立说明文件不保存 `Status` 或进度。相同 ID 恢复时复用；同 ID 不同定义返回冲突。每项 `source_refs` 绑定实际消费的输入；`completion` 逐条将验收条件关联到可读取且当前的证据摘要，不能以文件存在代替验收。
+
+进度为 `pending / running / blocked / completed / cancelled`。取消要有理由；延期保留未完成进度，并记录风险、负责人、解决时点、接收方、后续引用、验证计划和既有决定引用。延期不绕过原有门禁或风险接受规则。完成要求所有依赖已完成、逐条验收有证据且来源未漂移。阶段工作项不得出现 `ready-for-agent`，也不能绑定为 Slice 的实现 Ticket。
+
+## 推进与恢复
+
+1. 正式写入阶段资产前，先建立 checkpoint 与当前工作项；缺负责人 / 范围 / 验收时保留缺口，不推断历史完成。
+2. 进入当前阶段前检查 `scripts/stage-tracking check`；恢复时同样执行。阻塞、责任变化、资产批准和阶段退出必须回写，普通编辑仍集中记录。
+3. `Workflow Execution Result.checkpoint_ref` 引用当前持久 checkpoint。流转验证读取真实 checkpoint，拒绝仅在结果中自述追踪已完成。
+4. 上游或验收证据摘要变化时，用 `plan --refresh` 生成受影响项回到 pending / recheck_required 的差异，再 apply；旧摘要与证据原样保留。复验后由主控更新源摘要及验收映射，清除 recheck_required。
+5. 流转要求当前工作单元的必需项完成或按原规则延期；跨阶段检查当前阶段。无依赖工作可继续，延期并不使依赖它的工作可执行。
+6. 完成工作项只代表其验收通过，不能替代 Spec、Design 或工程合同批准。
+
+## 公共命令
+
+```sh
+scripts/stage-tracking check --root <项目> --checkpoint docs/.scratch/<feature>/checkpoint.yaml
+scripts/stage-tracking plan --root <项目> --checkpoint docs/.scratch/<feature>/checkpoint.yaml --items <工作项数组.yaml> > <plan.json>
+scripts/stage-tracking apply --root <项目> --plan <plan.json>
+scripts/stage-tracking plan --root <项目> --checkpoint docs/.scratch/<feature>/checkpoint.yaml --refresh > <refresh-plan.json>
+```
+
+check / plan 不写项目。首次 checkpoint 不存在时，plan 从本项目 checkpoint 模板形成草稿。没有明确工作项时输出 gaps，apply 拒绝。items 只登记 pending 项，不把历史产物推断为完成，也不覆盖已有同 ID 项。
+
+apply 复验项目身份、计划摘要、全部观察文件及源证据摘要，备份后写入。写入失败恢复本次已写内容；若检测到后续并发修改，保留文件并报告恢复冲突。备份和失败清单保存在功能包 verification/stage-tracking-migrations 内；不得删除后续执行证据。相同成功计划再次应用返回 unchanged。
+
+远程 tracker 不可用时，父票保留 publication: pending 和 pending_publication_to；本工具不访问远程平台。下游正式化业务票 / 切片时关联本阶段资产与工作项引用，不将已完成设计工作项改写为开发切片。
+
+首次登记的工作项数组示例（路径、负责人、范围与验收按真实任务填写）：
+
+```yaml
+- id: clarify-scope
+  title: 明确本轮范围
+  stage: stage.plan
+  work_unit: work-unit.plan-requirements
+  owner: 当前需求负责人
+  scope: 明确本轮包含与排除的业务行为
+  acceptance:
+    - 范围及至少一个边界例子可供审阅
+  dependencies: []
+  source_refs:
+    - docs/.scratch/example/plan/input.md
+  split_reasons: []
+```
+
+不同负责人和被其他项依赖的工作会自动拆分；独立验收使用 `split_reasons: [independent-acceptance]`。登记只创建 pending 项，不能把输入文件当成已通过的验收证据。启用项目缺少 checkpoint 时，check 返回非零退出码；先审阅并应用登记计划，再进入阶段写入。

package/template/docs/process/strategic-handoff-package.md

@@ -106,3 +106,11 @@ scripts/strategic-feedback verify-adjudication --root <消费者项目根> <adju
 `gate.strategic-design-handoff-approved` 不要求新的用户回复，也不把旧决定改写为交接决定。产品经理形成完整交接包后，由需求经理独立复核来源批准新鲜度、完整包摘要、风险与范围，并以 Fresh Verification 关闭交接门禁。缺少独立复核、来源批准过期、摘要漂移或验证失败均阻断 finalize。
 
 历史包中的 `strategic-decision-reuse-v1`、`decision_reuse_ref` 和旧门禁批准保持可读，供离线 `verify/import` 复核当时证据。它们不能关闭当前聚合门禁；任何修改、重发或继续流转都必须先完成战略门禁迁移并重新批准。
+
+## 插件接收入口与目标路由
+
+`yss-product-design` 在战略 profile 内完成设计与 Handoff v5 交付，`yss-backend-delivery` 通过 `project-import-design` 调用目标项目的 `scripts/strategic-consumer-entry --root <目标根> --bundle <交付目录或ZIP>`。入口先验证源包与后端路线，再执行既有 import；返回收据和目标工程设计入口，固定 `ready_for_agent: false`。恢复以 `--receipt <项目内收据路径>` 重新验证，查询不导入文件。
+
+源 `work-unit.technical-design` 保留不变，目标主控 `consumer_entry_routes` 持有精确映射；`plan-to-backend` 和完整主模板进入 `work-unit.technical-analysis`，专职后端进入自己的 `work-unit.technical-design`。目标工作单元不存在或超出 profile/职责范围时阻断。后端插件的 scope 只选择 backend-technical-design；源包保留完整前端、协调路线，不宣称已接管或完成。
+
+正式交付目录导入生成 Receipt v3；现有运输 package.zip 按已有协议生成 v2 收据，源包、批准、逻辑摘要仍须完整校验，不能补造 source-delivery-record。消费校验、反馈裁决和 Slice Contract 的实现门禁保持不变。

package/template/docs/user-guide//347/224/250/346/210/267/346/211/213/345/206/214.md

@@ -92,6 +92,8 @@ npx create-yss-harness-frontend@latest init --target-dir ./frontend-project --pr
 
 完整演练见[设备借用贯穿案例](设备借用贯穿案例.md)，后端技术设计见[技术设计用户指南](技术设计用户指南.md)。
 
+已有 Spec、设计、冻结接口或后端交付包时，按[阶段接入与产物复用使用手册](阶段接入与产物复用使用手册.md)从最近可信阶段继续。手册提供可复制指令、前端接收操作、命令及阻塞处理，帮助复用有效上游资产并补齐当前阶段缺口。
+
 ## 接管、同步与恢复
 
 综合 CLI 示例：

package/template/docs/user-guide//347/224/250/346/210/267/346/211/213/345/206/214/347/264/242/345/274/225.md

@@ -5,6 +5,7 @@
 1. [YSS 用户手册](用户手册.md)：四个现行家族的选型、CLI、确认、同步和恢复。
 2. [设备借用贯穿案例](设备借用贯穿案例.md)：战略、后端、前端与统一验收的完整练习。
 3. [技术设计用户指南](技术设计用户指南.md)：批准战略或 Spec 如何进入 DDD / layered-mvc 技术设计和实现合同。
+4. [阶段接入与产物复用使用手册](阶段接入与产物复用使用手册.md)：从已有产物继续，含后端交付后前端接收、准备、开发及恢复步骤。
 
 ## 按职责进入子项目
 

package/template/docs/user-guide//351/230/266/346/256/265/346/216/245/345/205/245/344/270/216/344/272/247/347/211/251/345/244/215/347/224/250/344/275/277/347/224/250/346/211/213/345/206/214.md

@@ -0,0 +1,243 @@
+# 阶段接入与产物复用使用手册
+
+已有需求、设计、冻结接口或交付包时，可以让 `yss-product-lifecycle` 核验这些产物，从最近可信阶段继续。有效的上游成果可以复用；缺失或过期的部分按依赖补齐，不需要默认从 Plan 重做。
+
+本手册面向项目负责人、后端交付人员和前端开发人员，重点演示“后端已交付，前端接着开发”。本文是现行规则的操作说明，不新增阶段或批准入口；规则以[生命周期注册表](../process/lifecycle-registry.yaml)、[流程裁剪规则](../process/harness-process-tailoring.md)和[前后端交付合同](../process/frontend-backend-delivery.md)为准。
+
+## 1. 先确认在哪个项目操作
+
+在承载实际业务的 `project-instance` 中开始，读取本地 `yss-project.yaml`、`AGENTS.md`、根 `CONTEXT.md` 和适用 profile。当前主模板仓库是 `template-source`，用于维护流程和手册，不能在这里生成真实业务 Spec、切片或实现合同。
+
+| 你所在的项目 | 可以接着做什么 |
+|---|---|
+| 综合项目实例 | 由 `yss-product-lifecycle` 核验上游，继续设计、工程契约、Ticket、实现或验证 |
+| 专职前端项目实例 | 按本地主控入口联合接收战略和后端交付，继续前端工程设计、实现与验收 |
+| 专职后端项目实例 | 消费批准的上游资产，完成后端技术设计、实现与交付 |
+| 尚未初始化或接管的代码仓 | 先按[用户手册](用户手册.md)初始化或接管，并登记实现仓库 |
+
+专职项目使用本地已安装的技能与职责规则；不要从主模板复制一个主控 Skill 来替换本地入口。治理仓与代码仓可以分离，代码写入已登记的实现仓及允许路径。
+
+## 2. 最快开始：给 Agent 一段完整指令
+
+把下面尖括号中的内容替换为真实信息。没有的资料写“缺失”，不知道的状态写“待核验”，不必为了开始咨询先填写整套合同。
+
+```text
+使用 yss-product-lifecycle，从已有产物接入本功能。
+
+目标：<本次希望完成的业务行为>
+治理项目根：<project-instance 的绝对路径>
+目标实现仓：<代码仓绝对路径或现有登记引用>
+已有产物：<Spec、设计、交付包、合同等路径>
+批准与验证证据：<可读取引用；没有则写缺失>
+父 Ticket / 切片 / checkpoint：<现有引用；没有则说明>
+希望开始的位置：<前端接收、工程设计、实现或验证>
+本次范围：<功能、页面、切片及不包含的内容>
+
+先只读判断最近可信阶段，给出可以复用的资产、阻塞项和下一工作单元。
+核验上游版本、批准范围及当前证据，不把文件存在视为阶段通过。
+暂不写文件或代码。
+```
+
+如果已决定推进，可以把最后一句替换为：
+
+```text
+完成核验后，在本次范围内继续可执行的工作单元，只补齐缺失项。
+优先核验并延续已有授权；遇到实质变化、必要输入缺失或适用人工决定时，
+展示当前资产、差异与下一动作。满足 ready-for-agent 后才实现代码。
+```
+
+自然语言即可表达入口意图，不要求记忆模式关键字。`route` 表示只读路由，`audit` 表示只读审计，`orchestrate` 表示有界推进，`resume` 表示重建状态后恢复。模式语义见[主控编排说明](../../.agents/skills/yss-product-lifecycle/references/orchestration.md)。指定“从实现开始”只是期望入口，最终仍由当前证据决定。
+
+## 3. 根据手里的产物选择入口
+
+| 已有材料 | 可以请求的下一动作 | 进入下一步前重点核验 |
+|---|---|---|
+| 已批准 Plan / 战略输入 | 继续 Spec | 当前范围、关键未决项、Plan → Spec 入口审阅及真实批准 |
+| 已批准 Spec | 继续产品设计或适用工程分析 | 验收标准、影响面、上游新鲜度；有产品设计影响时完成对应设计 |
+| 已批准页面方案或原型 | 继续工程契约与实现准备 | 页面、状态、权限体验与 Spec 一致；适用技术和接口契约完整 |
+| 冻结接口及工程设计 | 继续 Ticket 与合同准备 | 工程批准、实现仓接入、切片范围及相关 UI 输入 |
+| 完整后端交付包 | 从前端联合接收开始 | 战略与后端版本、目标词汇、UI 基线、场景映射和实际服务条件 |
+| 当前、已批准的前端 Slice Contract | 恢复前端实现 | Ticket、实现计划、依赖、写入范围、适用检查与完整就绪计算 |
+| 已实现代码及当前合同 | 继续审查与验证 | 实际改动与批准范围一致、当前验证证据；已有代码不能补作批准证明 |
+
+这些是常见入口，不是凭材料名称自动流转的对照表。上游资产需要同时满足内容、审查、批准和新鲜度要求。某项确实未命中时，按现行规则记录有原因和证据的 `not-applicable`；某项适用但未完成时，保留阻塞。
+
+## 4. 后端交付后，前端如何继续
+
+### 4.1 后端准备什么
+
+请后端提供由正式工具导出的 Backend Delivery 目录或 ZIP，以及目标环境和必要的访问条件。交付包应绑定当前窄业务切片、战略快照、规则和场景、冻结 OpenAPI、后端 Slice Contract、批准引用、构建部署身份与验证证据。包内不放运行时凭据。
+
+后端可以使用以下指令：
+
+```text
+请为切片 <slice-id> 准备后端交付，供前端接收。
+复用当前批准的战略基线、冻结接口和后端 Slice Contract。
+核验构建、部署、测试数据和成功/失败场景证据，按现有协议准备交付描述。
+从正式 backend-delivery 入口导出目录包及 ZIP，并报告导出路径、版本和摘要。
+缺少源批准、部署身份或预检清单时列出缺口，不伪造记录。
+```
+
+只有 Swagger 链接、源码或接口截图时，先做缺口分析。它们不能单独证明业务范围、UI 输入和当前批准已齐备。
+
+### 4.2 前端接收并复用上游
+
+在前端治理项目中发送；综合项目明确调用 `yss-product-lifecycle`，专职项目按本地主控入口执行：
+
+```text
+请从前端联合接收入口继续。
+后端交付包：<目录或 ZIP 的绝对路径>
+前端治理根：<project-instance 绝对路径>
+前端实现仓：<登记引用或绝对路径>
+本次切片：<slice-id 与业务范围>
+
+先验证交付包，再通过正式工具导入，复用包中的战略、Spec 和冻结接口。
+核对目标根 CONTEXT.md、适用 UI 基线、规则和成功/失败场景映射，
+完成战略预检及最终联合接收；有后端依赖时验证当前服务身份。
+保留已有有效的前端设计，列出缺失项与责任方。
+接收通过后继续前端实现计划、Ticket 和 Slice Contract 准备，
+完成适用批准和 ready-for-agent 计算后再进入实现。
+```
+
+后端导入会把其绑定的战略快照通过现有工具导入 `docs/handoffs/`，并保存后端包于 `docs/backend-deliveries/<delivery-id>/<version>/`。不需要前端把后端设计重新写一遍，但需要完成目标仓词汇对账和自己的场景承接。
+
+导入产生草案，不会自动批准前端资产。已有预检和设计草案应保留；同身份、同版本、不同内容的包会被拒绝。
+
+### 4.3 判断当前能做到哪一步
+
+| 当前结果 | 可以继续 | 尚不能据此认定 |
+|---|---|---|
+| 后端包 `verified` | 导入并准备目标仓接收 | 服务当前可用、前端可以编码 |
+| 前端战略预检通过 | 起草前端工程设计与实现计划 | 前端实现已经获准 |
+| 最终接收返回 `inputs-verified` | 准备、补齐前端实现资产 | `ready-for-agent`；工具此时仍返回 `ready_for_agent: false` |
+| 当前前端合同获准且完整就绪计算通过 | 在批准切片及路径内实现 | 合并、推送或发布获准 |
+| 前端实现及验证完成 | 按流程进行交付验收 | 整个业务切片已经验收或已经发布 |
+
+前端自己的实现准备包括适用的工程与 UI 输入、已校验的 `frontend_implementation_plan`、实现仓接入、正式垂直切片 Ticket 和当前持久化 Slice Implementation Contract。后端 Slice Contract 仅证明后端对应范围，不能代替前端合同。规则见[实现接入](../process/implementation-repo-integration.md)和[前端实现证据模板](../process/templates/frontend-implementation-plan-template.yaml)。
+
+### 4.4 后端还没交付时，前端能做什么
+
+战略输入已齐备时，可以先完成 Frontend Strategic Preflight，并起草工程设计和实现计划。有 Backend/API/Data 依赖的最终接收仍等待对应后端交付；这条路线中的正式编码仍需当前合同获准。
+
+真正的 UI-only 工作可以按影响面使用有证据的 `backend-not-applicable`。不能因为后端暂时没交付，就把实际后端依赖标为不适用。
+
+## 5. 需要手动操作时的命令
+
+以下命令供交付维护人员和 Agent 使用。普通用户可以直接使用第 2、4 节的指令，让 Agent 操作并报告结果。命令中的 `scripts/` 来自当前已安装相应工具的治理项目；不要在未核对 profile 和工具版本时混用其他项目的脚本。
+
+尖括号表示需替换的参数，不要原样粘贴执行。`--source-root`、`--target-root`、`--root` 指向治理项目根；交付描述、预检和接收记录中的引用按各自协议相对该治理根解析。新建后端交付输出目录必须尚不存在。
+
+### 后端导出
+
+在后端治理项目准备好真实交付描述后运行：
+
+```sh
+scripts/backend-delivery export \
+  --source-root <后端治理根绝对路径> \
+  --delivery <相对后端治理根的交付描述路径> \
+  --output <新的交付输出目录绝对路径> \
+  --zip
+```
+
+**既有后端工程身份为 v2 时，必须增加 `--preflight-input <预检清单绝对路径>`。**清单使用 `delivery_kind: backend-delivery`，绑定本次源交付描述和当前摘要；准备方法见[只读交付预检](../process/delivery-preflight.md)。预检失败时按返回的 `recovery` 补证，再从正常导出入口重试。
+
+### 验包与导入
+
+在前端治理项目运行：
+
+```sh
+scripts/backend-delivery verify --bundle <交付目录或ZIP绝对路径>
+
+scripts/backend-delivery import \
+  --bundle <交付目录或ZIP绝对路径> \
+  --target-root <前端治理根绝对路径>
+```
+
+验包成功输出 `result: verified`，并明确 `live_service_checked: false`。记下导入命令返回的真实收据和草案路径；不要自行推测文件名或把草案状态直接改成已批准。
+
+如果当前只有战略包，可先独立验证和导入：
+
+```sh
+scripts/strategic-handoff verify --bundle <战略交付目录或包绝对路径>
+scripts/strategic-handoff import \
+  --bundle <战略交付目录或包绝对路径> \
+  --target-root <前端治理根绝对路径>
+```
+
+后端包已经带入同一战略版本时，无需重复做手工导入。版本兼容按[前后端交付合同](../process/frontend-backend-delivery.md)处理，不通过修改 schema 版本来绕过检查。
+
+### 校验前端接收
+
+先让主控根据真实资产补齐正式 Context Reconciliation、UI 基线和场景承接，完成预检草案：
+
+```sh
+scripts/verify-frontend-strategic-preflight \
+  --root <前端治理根绝对路径> \
+  <相对前端治理根的预检记录路径>
+```
+
+最终接收记录完成核对后，按协议记录 `status: accepted`，再实际运行：
+
+```sh
+scripts/verify-frontend-delivery \
+  --root <前端治理根绝对路径> \
+  --slice <slice-id> \
+  <相对前端治理根的接收记录路径>
+```
+
+最后一项检查会复验输入、场景映射和适用的真实服务身份。`accepted` 字段本身不等于通过。部署不可达、身份不符或证据过期时先处理阻塞；离线验包不能替代这一步。成功后仍需编译、批准前端合同并计算就绪，不能把返回值手改为 `true`。
+
+### 只读查看主控规则
+
+综合项目可以查询实现入口的确定性合同投影：
+
+```sh
+scripts/query-lifecycle-context \
+  --mode route \
+  --work-unit work-unit.slice-implementation \
+  --include modes
+```
+
+此命令只展示规则与路由，不读取业务资产来代替完整就绪判定，也不会批准或执行实现。可用阶段、工作单元和查询键以本地注册表及工具支持为准。
+
+## 6. 已有合同或中断后如何恢复
+
+已有完整前端合同，可以直接提出恢复请求：
+
+```text
+使用 yss-product-lifecycle 恢复切片 <slice-id>。
+checkpoint：<路径>
+前端 Slice Contract：<路径>
+接收记录：<路径>
+目标实现仓：<登记引用>
+
+重新核验当前合同批准、上游摘要、接收绑定、Ticket、实现计划和允许路径。
+前提仍满足时，从第一个未完成且未阻塞的工作单元继续。
+复用未变化的有效资产，不重做已完成的需求和设计；
+发现过期或新影响时，只回到受影响的资产与工作单元处理。
+```
+
+新会话、新机器或新目录不会使旧结论自动有效。恢复必须能读取原始资产与证据；相关输入变化后，先更新接收和依赖合同，再恢复。不同切片使用各自交付身份，避免不相关工作相互阻塞。
+
+## 7. 常见阻塞怎么处理
+
+| 现象 | 应采取的动作 |
+|---|---|
+| 当前仓是 `template-source` | 切换到真实项目实例；不要手改身份字段把模板源伪装成产品仓 |
+| 只有接口文档，没有战略或业务验收 | 请来源方补交业务规则、范围和批准依据，先完成缺口分析 |
+| 交付包导入成功，但仍不能编码 | 查看接收检查、前端计划、Ticket、合同批准和就绪缺口 |
+| 目标词汇与源包冲突 | 完成目标根 `CONTEXT.md` 对账；业务规则冲突回交来源方 |
+| UI 基线缺失或不匹配 | 补适用产品设计；既有 UI 基线仅按其限定条件使用，截图不能自行成为批准 |
+| `preflight-required` | 按只读交付预检合同准备当前源资产清单，并传入 `--preflight-input` |
+| API、包摘要或部署身份不一致 | 核对交付版本，向后端补取同一基线的冻结接口、部署与证据 |
+| 导入了新的同身份后端版本 | 重新接收当前版本，更新绑定并重编译受影响的合同 |
+| 合同出现 `stale`、`drift` 或 `new_impacts` | 停止依赖旧合同的实现，回到受影响的设计、接收或合同编译环节 |
+| 工具缺失、profile 或 schema 不支持 | 按[用户手册](用户手册.md)核对实例固定版本与同步路径，保留现有资料，不混拷脚本或静默降级 |
+
+## 8. 如何判断这次接入已达到目标
+
+要求主控用当前资产报告：复用了哪些上游内容、从哪个工作单元接入、哪些缺口已补齐、还剩哪些阻塞，以及下一动作。需要编码时，必须明确报告目标切片、当前前端合同和 `ready-for-agent` 结论；需要交付时，另提供实际测试、还原验证及独立审查结果。
+
+前端验证使用登记的 `pnpm` 命令，并按适用范围记录截图或视觉回归、状态交互、console warning 和实际退出码。前端完成与整个业务切片完成分别判断；最终业务验收需绑定同一战略、API、后端部署和前端版本。Git 提交、推送、合并与发布仍各自遵守授权边界。
+
+进一步阅读：[完整用户手册](用户手册.md)、[设备借用贯穿案例](设备借用贯穿案例.md)、[技术设计用户指南](技术设计用户指南.md)、[前后端交付合同](../process/frontend-backend-delivery.md)。

package/template/scripts/api-contract-decision

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import {parseArgs} from 'node:util';
+import {parseSliceYaml} from './lib/slice-contract.mjs';
+import {hash,safe,write} from './lib/strategic-handoff-io.mjs';
+import {prepareApiContractDecision,migrateApiContractDecision} from './lib/api-contract-decision.mjs';
+import {stringify} from './vendor/yaml.mjs';
+try{
+ const{values,positionals}=parseArgs({allowPositionals:true,options:{root:{type:'string',default:process.cwd()},output:{type:'string'},version:{type:'string'}}});
+ const[command,ref]=positionals;if(positionals.length!==2||!['prepare','migrate'].includes(command)||!values.output)throw Error('用法: api-contract-decision prepare|migrate <输入> --output <新路径> [--root <目录>] [--version v2]');
+ const root=path.resolve(values.root),bytes=fs.readFileSync(safe(root,ref)),input=parseSliceYaml(bytes);
+ const result=command==='prepare'?prepareApiContractDecision(input,{root}):migrateApiContractDecision({ref,version:input.decision_version,impact:input.impact,digest:hash(bytes)},{root,version:values.version});
+ write(root,values.output,stringify(result));
+ console.log(JSON.stringify({result:'draft',ref:values.output,digest:hash(fs.readFileSync(safe(root,values.output))),approval_inherited:false,next:'按现有差异与授权延续协议完成生命周期批准'}));
+}catch(error){console.error(error.message);process.exitCode=1;}

package/template/scripts/backend-standards-coverage

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { parseSliceYaml, selectSliceWorkUnit } from './lib/slice-contract.mjs';
+import { inspectSliceContract } from './lib/slice-execution-preflight.mjs';
+import { inspectMaintenanceCandidate } from './lib/maintenance-candidate.mjs';
+import { compileStandardsCoverage, coverageFile } from './lib/backend-standards-coverage.mjs';
+import { validateBackendReview } from './lib/backend-review.mjs';
+try {
+ const {values}=parseArgs({options:{input:{type:'string'},root:{type:'string'},verify:{type:'boolean'}},strict:true});
+ if(!values.input)throw Error('usage: scripts/backend-standards-coverage --input <review-state.json|yaml> [--root <governance-root>] [--verify]');
+ const root=path.resolve(values.root||'.'),state=parseSliceYaml(fs.readFileSync(path.resolve(values.input),'utf8'));
+ if(values.verify)console.log(JSON.stringify(validateBackendReview(state,{root}),null,2));
+ else {
+  const input=state.review_input;if(!input)throw Error('review_input required');
+  const projectRoot=path.resolve(root,input.project_root||'.');let contract=null,comparison_ref=null;
+  if(input.scope_kind==='change') {
+   const loaded=inspectSliceContract(input.slice_contract_ref,{root,approval_ref:input.approval_ref,work_unit_id:input.work_unit_id});
+   if(!loaded.report.execution_allowed)throw Error(loaded.report.blockers.join('; '));
+   contract=selectSliceWorkUnit(loaded.contract,input.work_unit_id);
+   comparison_ref=input.review_mode==='worktree'?inspectMaintenanceCandidate({manifestPath:coverageFile(projectRoot,input.candidate_snapshot_ref)}).manifest.merge_base:input.review_base_ref;
+  }
+  console.log(JSON.stringify(compileStandardsCoverage({root,projectRoot,contract,scope_kind:input.scope_kind,baseline_binding:input.baseline_binding,comparison_ref,actual_skills:input.actual_skill_impacts||[],responsibility_evidence:input.responsibility_evidence||[]}),null,2));
+ }
+} catch(error){console.error(error.message);process.exitCode=1;}