create-yss-spec 3.3.7 → 3.4.1

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

@@ -1,114 +1,130 @@
 # YSS 用户手册
 
-面向首次使用与已有项目升级的操作者。本仓是模板源；从模板生成项目实例后再保存真实业务材料。先选对职责，再让 Agent 根据本仓规则执行。
+本手册帮助项目负责人选择模板、创建或接管项目，并判断 Agent 何时可以继续工作。本仓是 `template-source`；真实业务材料只能写入由 CLI 生成或接管的 `project-instance`。
 
-## 先选项目
+## 选择项目家族
 
-| 你的任务 | 选择 | 创建与更新入口 |
+| 你的责任 | 模板与 CLI | 本地终点 |
 |---|---|---|
-| 从想法到发布，统一管理整个业务切片 | 综合模板 `yss-spec-project-template` | `create-yss-spec`：初始化、attach、sync |
-| 澄清业务、Spec、原型并交接研发 | 战略模板 `yss-harness-design-agent` | `create-yss-harness-design`：初始化；无 attach/sync |
-| 接收已批准上游，统一组织研发 | 通用研发模板 `yss-harness-dev-agent` | `create-yss-harness-dev`：初始化、attach、sync |
-| 独立团队承担后端并输出交付包 | 后端模板 `yss-harness-backend-agent` | `create-yss-harness-backend`：init、attach、sync（首版候选） |
-| 接收战略及后端交付，承担前端 | 前端模板 `yss-harness-frontend-agent` | `create-yss-harness-frontend`：init、attach、sync（首版候选） |
+| 统一管理从业务问题到实现、验证和发布 | `yss-spec-project-template` / `create-yss-spec` | 完整业务切片验收 |
+| 澄清业务、形成 Spec、页面方案和战略交接 | `yss-harness-design-agent` / `create-yss-harness-design` | Strategic Design Handoff |
+| 设计并实现后端、冻结接口并输出后端交付 | `yss-harness-backend-agent` / `create-yss-harness-backend` | Backend Delivery |
+| 联合接收战略和后端交付、实现并验收前端 | `yss-harness-frontend-agent` / `create-yss-harness-frontend` | Frontend Acceptance |
 
-通用研发和前后端专职是可选择的组织方式，不要求现有通用项目迁移。采用专职路线时，登记一个统一管理方汇总业务切片，不能把两端自报完成直接相加当作业务验收。
+专职路线通常按“战略 → 后端 → 前端 → 统一业务验收”接力。每个子项目只确认自己的职责完成；统一管理方绑定同一战略、接口、部署和前端版本后，才能判断整个业务切片是否完成。
 
-完整协作可以采用“战略 → 后端交付 → 前端联合接收 → 统一业务验收”。综合或通用研发也可承担协调职责，具体责任人和仓库由项目登记，不凭目录推断。
+既有 `yss-harness-dev-agent` / `create-yss-harness-dev` 实例继续按其固定版本和本地 README 维护。本家族已退出当前项目选型，不自动迁移到综合、后端或前端家族，也不能通过修改 metadata 转换身份。
 
-## 安装和首次创建
+## CLI 能力与写入方式
 
-先确认 Node.js 与 npm 可用，命令要求以所选 CLI README 为准。首次使用推荐下列已发布渠道，三条命令只选择与你职责匹配的一条：
+先运行所用包的 `--version` 和 `--help`；源码候选版本、npm 已发布版本和实例记录的模板快照是三个不同事实。
 
-```bash
-npm create yss-spec@latest
-npm create yss-harness-design@latest
-npm create yss-harness-dev@latest
-```
+| 能力 | `create-yss-spec` | 战略、后端、前端专职 CLI |
+|---|---|---|
+| init | 默认命令；写入新目录 | `init`；只接受不存在或空目录 |
+| attach | 必须显式选择 `--dry-run` 或 `--apply` | 默认预览；`--apply` 写入 |
+| sync | 默认写入；`--dry-run`、`--plan`、`--json` 只读 | 默认预览；`--apply` 写入 |
+| diff / doctor | 支持，只读 | 支持，只读 |
+| recover | 无独立命令；失败由事务回滚 | 默认只读诊断；`recover --apply` 恢复未完成事务 |
+| prune | `sync --prune` | `sync --plan --prune` 预览，`sync --apply --prune` 写入 |
+| update / upgrade | 只更新 CLI 程序 | 只更新 CLI 程序 |
 
-本手册描述 GitHub 当前实现。`@latest` 指 npm 已发布版本，其模板快照可能落后于 GitHub。使用前运行 `npm view <包名> version` 核对；包名占位符须替换。未发布的候选不能用对应的 npm 版本号直接安装。
+`--prune` 只删除仍与可信旧 baseline 相同的退出分发文件。用户改过的旧文件会保留并报告；`--force` 也不能放宽删除、身份、Git、gitlink 或路径安全条件。
 
-要使用尚未发布的手册版本，从对应 CLI 的 GitHub 固定提交检出，按该仓 README 的候选包步骤构建；检查 `template.snapshot.json` 的 `templateCommit` 与包版本。CLI 初始化使用包内快照，不会实时拉取最新模板。不同家族的快照和版本号分别记录。
+## 安装、创建与核对
 
-前后端专职分别使用 `create-yss-harness-backend` / `create-yss-harness-frontend` 首版候选。发布前先从同名 CLI 仓的实际 tgz 安装验收；npm 可用状态以 registry 为准。
+先确认 npm 中确有需要的版本：
 
 ```sh
-npx create-yss-harness-backend@latest init --target-dir /absolute/path/to/new-project --project-name 设备借用
-npx create-yss-harness-frontend@latest attach --target-dir /absolute/path/to/existing-project
+npm view create-yss-spec version
+npm view create-yss-harness-design version
+npm view create-yss-harness-backend version
+npm view create-yss-harness-frontend version
 ```
 
-init 只创建不存在或空目录；attach / sync 默认只预览，写入要求 `--apply`。旧仓内脚本实例不兼容，不提供 metadata 转换；新实例记录 schema v2 的模板/core来源与受管基线。冲突整次暂停，显式备份覆盖可用 `--apply --force`，但身份、业务文件和路径保护不可绕过。
+再选择一个家族创建项目，例如：
+
+```sh
+npm create yss-spec@latest
+npx create-yss-harness-design@latest init --target-dir ./design-project --project-name 设备借用 --business-domain 内部设备管理
+npx create-yss-harness-backend@latest init --target-dir ./backend-project --project-name 设备借用 --business-domain 内部设备管理
+npx create-yss-harness-frontend@latest init --target-dir ./frontend-project --project-name 设备借用 --business-domain 内部设备管理
+```
+
+`@latest` 取得 npm 已发布包，不保证等于 GitHub 当前源码。候选包必须从对应 CLI 仓库构建实际 tgz，并核对 `package.json`、`template.snapshot.json` 的 `templateCommit`、来源状态和摘要；CLI 使用包内快照，不会运行时拉取模板仓。
+
+初始化或 attach 后检查：
 
-初始化后检查 yss-project.yaml 为 `project-instance`、对应家族 metadata 和 docs/user-guide/用户手册索引.md；进入生成目录再开启 Agent。
+1. `yss-project.yaml` 是 `project-instance`。
+2. 只存在本家族 metadata，且 profile 与职责一致。
+3. 根 `CONTEXT.md`、`AGENTS.md` 和 `docs/user-guide/用户手册索引.md` 可读。
+4. Git 状态、实现仓登记、验证命令和回滚点符合项目实际情况。
 
 ## 第一次让 Agent 工作
 
-先在生成的项目实例中打开 Agent，发送：
+在生成的项目实例中发送：
 
 ```text
-请先只读检查 yss-project.yaml、根 CONTEXT.md、AGENTS.md，以及存在的 harness-profile.yaml。
+请先只读检查 yss-project.yaml、根 CONTEXT.md、AGENTS.md 和 harness-profile.yaml。
 告诉我本仓职责、当前可信阶段、上游输入、缺失证据和下一步。
-发现身份不合法或输入过期时停止并给出恢复办法；先不要写代码。
+发现身份非法、输入过期或职责越界时停止并给出恢复办法；先不要写代码。
 ```
 
-成功时应得到明确的仓库身份和可追踪输入，不是泛泛的开发计划。`template-source` 只能维护可复用模板；真实业务必须在 `project-instance` 中记录。真实业务词汇只登记在实例根 `CONTEXT.md`，不复制本手册示例当作已确认事实。
+正确结果应说明当前事实、阻塞责任和下一动作。模板文件存在、导入成功、验证包摘要成功或 Agent 自报完成，都不能替代当前批准和 Fresh Verification。
 
-## 用户确认什么
+## 用户需要确认什么
 
-| 看到的材料 | 你需要判断 | 确认后的边界 |
+| 看到的材料 | 需要判断 | 确认后的边界 |
 |---|---|---|
-| 目标、范围、规则及反例 | 是否符合业务、哪些不做 | 允许继续设计；不自动批准实现 |
-| 页面流程、状态与视觉基线 | 成功、失败、权限和恢复是否完整 | 形成对应产品设计输入 |
-| 工程/接口/脚手架方案 | 责任、兼容、数据和回滚是否可接受 | 按本仓角色政策完成适用会签 |
-| 当前 Slice Contract | 写哪些仓库与路径、怎么验收 | 必要门禁通过后才能实施 |
-| 本轮验证和发布方案 | 覆盖、风险、回滚和交付范围 | 发布及外部承诺仍需生物人 |
+| 目标、范围、规则及反例 | 业务是否正确、哪些不做 | 允许继续设计，不自动批准实现 |
+| 页面流程、状态和视觉基线 | 成功、失败、权限与恢复是否完整 | 形成当前产品设计输入 |
+| 架构、接口和脚手架方案 | 责任、兼容、数据和回滚是否可接受 | 完成对应工程会签 |
+| 当前 Slice Contract | 写哪些仓库与路径、如何验收 | 门禁通过后才允许实施 |
+| 本轮验证和发布方案 | 覆盖、风险、回滚和交付范围 | 发布与外部承诺仍需生物人 |
 
-具体批准身份和门禁以本仓 `docs/agents/digital-human-roles.yaml`、`docs/process/lifecycle-registry.yaml` 为准。Agent 起草、自报通过或文件中写 `approved` 均不能代替真实批准。`ready-for-human` 是待指定会签；只有可直接实施的切片才使用 `ready-for-agent`。
+批准身份、范围和失效条件以本地 `digital-human-roles.yaml` 与 `lifecycle-registry.yaml` 为准。编译器只起草合同；`inputs-verified` 只允许继续准备计划和合同；只有当前合同获准、阻塞清除的切片才可进入 `ready-for-agent`。
 
-## 按路线推进
+## 当前工作主线
 
-综合模板按本仓生命周期从分诊、Plan、Spec/功能架构、产品设计、工程契约、Ticket、切片推进到验证与发布。战略模板在业务交接停止；通用研发从批准上游接入；专职两端按交付合同接力。
+综合模板从分诊、Plan、Spec、产品设计、工程契约、Ticket、实现推进到验证与发布。战略模板在业务交接停止；后端模板消费批准战略并输出可核验后端交付；前端模板联合接收战略、后端、API、数据和 UI 输入后实施前端。
 
-每一步都让 Agent 说明：消费了哪些当前输入、准备了什么、缺谁确认、怎样检查结果。具体阶段和门禁从本仓注册表读取，不把别的模板阶段编号复制进本仓。
+涉及交付前提时，先运行只读 `scripts/preflight-delivery`。它只验证原始输入，不初始化项目、不运行构建、不启动服务、不生成批准或收据。导出、导入和实现边界仍要重新验证当前资产。
 
-跟随 [设备借用贯穿案例](设备借用贯穿案例.md) 练习；战术建模说明见 [战术设计指南](战术设计子项目用户手册.md)。
+完整演练见[设备借用贯穿案例](设备借用贯穿案例.md)，后端技术设计见[技术设计用户指南](技术设计用户指南.md)。
 
-## 已有项目接管与升级
+## 接管、同步与恢复
 
-只有综合/通用研发提供 attach 和 sync。先保存可恢复的 Git 基线，再选择对应包执行；以下是综合示例，通用研发仅将包名替换为 `create-yss-harness-dev`：
+综合 CLI 示例：
 
-```bash
-npx create-yss-spec@latest attach --target-dir . --project-name "设备借用" --business-domain "内部设备管理" --dry-run
-npx create-yss-spec@latest attach --target-dir . --project-name "设备借用" --business-domain "内部设备管理" --apply
+```sh
+npx create-yss-spec@latest attach --target-dir . --project-name 设备借用 --business-domain 内部设备管理 --dry-run
+npx create-yss-spec@latest attach --target-dir . --project-name 设备借用 --business-domain 内部设备管理 --apply
 npx create-yss-spec@latest sync --target-dir . --dry-run
 npx create-yss-spec@latest sync --target-dir .
+npx create-yss-spec@latest sync --target-dir . --plan --prune
 ```
 
-attach 用于尚未由对应 CLI 管理的既有项目；已存在本家族 metadata 时使用 sync。不要把上面四条不加区分连续执行。正常 sync 保留用户修改并报告 conflict、unsafe 和上游删除项；先审阅实际计划再决定如何处理冲突。源码、.git、gitlink 和挂载点按现有保护规则保留。
-
-`update`/`upgrade` 更新 CLI 程序，`sync` 更新实例受管模板，两者不同。事务校验失败会回滚本轮文件写入；成功后的撤销使用自己保存的 Git 基线或备份，不用旧 CLI 强制反向同步。
-
-战略和专职实例本次没有自动 sync/原地迁移：用同家族新目录比较受管资产，按计划迁移，重验输入和合同，保留原实例回滚。不能跨 profile 覆盖。
+专职 CLI 示例：
 
-五家族由 `.yss-template.json`、`.yss-harness-design.json`、`.yss-harness-dev.json`、`.yss-harness-backend.json`、`.yss-harness-frontend.json` 及 profile 判定。不得删除或伪造 metadata 来切换家族。
+```sh
+npx create-yss-harness-backend@latest attach --target-dir .
+npx create-yss-harness-backend@latest attach --target-dir . --apply
+npx create-yss-harness-backend@latest sync --target-dir . --plan --prune
+npx create-yss-harness-backend@latest sync --target-dir . --apply --prune
+npx create-yss-harness-backend@latest recover --target-dir .
+```
 
-异族、多重身份、损坏 metadata、未知或矛盾 profile 会在规划/写入前被拒绝；`--force` 不能绕过，`--dry-run` 同样检查。只有在身份及路径检查通过后，force 才按该命令的覆盖语义生效。遇到拒绝先核对所用家族和目标路径，保留原目录，不用战略 init 强制替代升级。
+attach 用于尚未由该家族管理的普通项目；已有本家族 metadata 时使用 sync。先审阅计划，再选择写入命令。旧 repository-local 实例、未知 schema、多重或异族身份按 CLI 输出处理，不删除 metadata 伪装普通目录。
 
 ## 常见卡点
 
-| 现象 | 下一步 |
+| 现象 | 处理 |
 |---|---|
-| Agent 立即开始写代码 | 要求只读分诊，展示当前合同和允许路径 |
-| 文件已有但无法继续 | 检查批准、摘要、依赖和 Fresh Verification，不只看文件存在 |
-| 前端输入已验证仍不能实现 | inputs-verified 只放行计划/合同准备，先完成合同批准 |
-| --force 仍失败 | 查家族、身份、unsafe 与 gitlink，不能靠删 metadata 绕过 |
-| npm 创建后没有本手册更新 | 核对 npm 版本与包内模板 SHA，使用已核验候选包或等待正式发布 |
-| 独立子项目自报完成 | 统一管理方核对跨仓版本及业务端到端证据 |
-
-## 团队与维护者
-
-业务人员确认规则和页面；架构与研发落实到冻结接口、当前合同和实际实现仓；Reviewer 独立核验。运行时代码默认进入登记的独立仓，前端优先 pnpm，后端优先根 ./mvnw；缺工具时记录受控例外与实际命令。
-
-模板维护者先读 [AGENTS.md](../../AGENTS.md) 和 [流程裁剪](../process/harness-process-tailoring.md)，维护 canonical 事实与生成投影，运行分级验证。维护流程不混入用户的日常业务步骤。
-
-各模板与 CLI 专项手册见 [用户手册索引](用户手册索引.md)。
+| Agent 立即写代码 | 要求只读分诊，展示当前合同、允许路径和批准证据 |
+| 包验证成功仍不能实现 | 继续完成目标词汇对账、接收、计划和合同批准 |
+| `--force` 仍失败 | 修复身份、冲突、unsafe 路径或 gitlink，不绕过保护 |
+| npm 包缺少新手册 | 比对 npm 版本、CLI 版本和模板 snapshot |
+| 旧手册仍在实例 | 先用 `sync --plan --prune` 判断是否可安全清理 |
+| 单个子项目自报完成 | 由统一管理方核对跨仓版本和端到端业务证据 |
+
+各家族入口见[用户手册索引](用户手册索引.md)。模板维护者另读根 [AGENTS.md](../../AGENTS.md) 和[流程裁剪](../process/harness-process-tailoring.md)。

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

@@ -2,17 +2,16 @@
 
 ## 第一次使用
 
-1. [YSS 用户手册](用户手册.md)：五类项目选型、首次创建、确认与升级。
-2. [设备借用贯穿案例](设备借用贯穿案例.md)：输入、提示词、命令、成功标准及异常恢复。
-3. [战术设计指南](战术设计子项目用户手册.md)：批准战略如何落到设计和测试。
+1. [YSS 用户手册](用户手册.md)：四个现行家族的选型、CLI、确认、同步和恢复。
+2. [设备借用贯穿案例](设备借用贯穿案例.md)：战略、后端、前端与统一验收的完整练习。
+3. [技术设计用户指南](技术设计用户指南.md)：批准战略或 Spec 如何进入 DDD / layered-mvc 技术设计和实现合同。
 
-## 专项路线
+## 按职责进入子项目
 
-- [战略：澄清、设计、交接](https://github.com/iloveZzz/yss-harness-design-agent/blob/main/docs/user-guide/用户手册索引.md)
-- [通用研发：接收、合同、实现与验证](https://github.com/iloveZzz/yss-harness-dev-agent/blob/main/docs/user-guide/用户手册索引.md)
-- [后端：接口、实现与交付](https://github.com/iloveZzz/yss-harness-backend-agent/blob/main/docs/user-guide/用户手册索引.md)
-- [前端：联合接收、页面与验收](https://github.com/iloveZzz/yss-harness-frontend-agent/blob/main/docs/user-guide/用户手册索引.md)
+- [战略设计](https://github.com/iloveZzz/yss-harness-design-agent/blob/main/docs/user-guide/用户手册索引.md)
+- [后端交付](https://github.com/iloveZzz/yss-harness-backend-agent/blob/main/docs/user-guide/用户手册索引.md)
+- [前端接收与验收](https://github.com/iloveZzz/yss-harness-frontend-agent/blob/main/docs/user-guide/用户手册索引.md)
 
-跨项目导航使用 GitHub 链接；生成实例不需要兄弟仓或 submodules 目录。链接指向各仓 main，实际执行仍核对本地 profile、包版本和固定模板 SHA。
+既有通用研发实例按其固定版本和本地 README 维护，不再作为新项目入口。生成实例通过 GitHub 链接跨项目导航，但实际操作以本地 profile、CLI `--help`、包版本和模板 snapshot 为准。
 
-CLI 参数详解：[综合 CLI](https://github.com/iloveZzz/create-yss-spec/blob/main/docs/user-guide/create-yss-spec-cli-guide.md)、[战略 CLI](https://github.com/iloveZzz/create-yss-harness-design)、[研发 CLI](https://github.com/iloveZzz/create-yss-harness-dev)。组件工具专项见 [YSS UI MCP](yss-ui-mcp.md)。
+CLI 详解：[综合 CLI](https://github.com/iloveZzz/create-yss-spec/blob/main/docs/user-guide/create-yss-spec-cli-guide.md)、[战略 CLI](https://github.com/iloveZzz/create-yss-harness-design)、[后端 CLI](https://github.com/iloveZzz/create-yss-harness-backend)、[前端 CLI](https://github.com/iloveZzz/create-yss-harness-frontend)。组件专项见 [YSS UI MCP](yss-ui-mcp.md)。

package/template/docs/user-guide//350/256/276/345/244/207/345/200/237/347/224/250/350/264/257/347/251/277/346/241/210/344/276/213.md

@@ -1,4 +1,4 @@
-# 内部设备借用：贯穿五类项目的教学案例
+# 内部设备借用：贯穿四个现行家族的教学案例
 
 本文是虚构教学说明，不是已批准 Spec、真实交付包或可直接执行的产品合同。示例路径、规则和标识由学习者在独立 `project-instance` 中确认后落盘；模板源不登记这些业务词汇。
 
@@ -17,7 +17,7 @@
 
 ## 1. 选择工作组织
 
-综合模板可承载从澄清到业务验收的管理资产。战略模板只负责上游方案；研发既可以交给通用研发模板，也可以交给后端/前端专职模板。后两者必须登记统一管理方及独立实现仓，不把源代码复制进模板。
+综合模板可承载从澄清到业务验收的管理资产。战略模板只负责上游方案，后端和前端模板按交付协议接力；专职路线必须登记统一管理方及独立实现仓，不把源代码复制进模板。既有通用研发实例只按原固定版本维护，不作为本案例的新建路线。
 
 ## 2. 战略方形成可交接输入
 
@@ -29,18 +29,19 @@
 列出准备交接的规则、关键场景、版本、批准证据和研发待决事项。
 ```
 
-用户逐项核对业务和页面。预期输出为本仓合同要求的已批准战略资产、根词汇、交接描述及证据闭包，不能只交聊天摘要。战略方不在此生成后端工程或冻结工程 API。
+用户逐项核对业务和页面。预期输出为本仓合同要求的已批准战略资产、根词汇、交接描述及证据闭包，不能只交聊天摘要。战略方不在此生成后端工程或冻结工程 API。UI 有变化时交付已批准原型；确认无 UI 变化的既有工程使用 `existing-ui-baseline`，不能用截图把既有界面伪装成原型。
 
 由 Agent 给出实际交接描述路径后，在战略实例执行以下命令。尖括号必须替换为真实路径，输出目录须新建；`--handoff` 是相对源实例的文件路径。
 
 ```bash
-node scripts/strategic-handoff export --source-root . --handoff <交接描述相对路径> --output <新包目录> --zip
+node scripts/preflight-delivery --input <战略预检输入.json> --stage export --json
+node scripts/strategic-handoff finalize --source-root . --handoff <Handoff-v5相对路径> --zip
 node scripts/strategic-handoff verify --bundle <包目录或ZIP>
 ```
 
-预期验包输出 `result: verified` 及包摘要；缺证据或被修改的包会失败。把完整目录/ZIP交给下游，保留版本与摘要，不手改包内文件。
+预检输入使用 `delivery_kind: strategic-handoff`，绑定交接描述和当前 UI 基线。预期验包输出 `result: verified` 及包摘要；缺证据或被修改的包会失败。把完整目录/ZIP 交给下游，保留版本与摘要，不手改包内文件。
 
-## 3. 后端或通用研发接收
+## 3. 后端接收
 
 在接收实例运行：
 
@@ -52,11 +53,11 @@ node scripts/strategic-handoff import --bundle <包目录或ZIP> --target-root .
 ```text
 请读取导入收据和包内规则/场景，核对本仓根 CONTEXT.md 并形成正式对账。
 为“已批准申请领用设备”逐项登记承接、冲突和依赖。
-按当前流程准备战术设计、API Draft/Freeze 和后端 Slice Contract，
+按当前流程核对既有工程身份，准备技术设计、API Draft/Freeze 和后端 Slice Contract，
 登记真实实现仓、验证命令和回滚点。合同获准前只准备材料，不写代码。
 ```
 
-预期保存导入收据、目标词汇对账、规则/场景承接与当前合同；导入成功不会自动批准这些资产。设备占用竞争应落实到设计与可执行测试，不能只在页面禁用按钮。API 变化回到冻结流程。后端专职只承担后端；通用研发按本仓合同承担实际受影响的两端工作。
+预期保存导入收据、目标词汇对账、规则/场景承接与当前合同；导入成功不会自动批准这些资产。既有 Java/Maven 工程需要 repository registration、engineering baseline 和 observation manifest 三份当前原始证据。设备占用竞争应落实到设计与可执行测试，不能只在页面禁用按钮；API 变化回到冻结流程。
 
 ## 4. 后端交付当前切片
 
@@ -70,11 +71,12 @@ node scripts/strategic-handoff import --bundle <包目录或ZIP> --target-root .
 在后端实例执行（交付描述已由实际证据形成）：
 
 ```bash
+node scripts/preflight-delivery --input <后端预检输入.json> --stage export --json
 node scripts/backend-delivery export --source-root . --delivery <交付描述相对路径> --output <新交付包目录> --zip
 node scripts/backend-delivery verify --bundle <交付包目录或ZIP>
 ```
 
-预期 `verified`，但 `live_service_checked: false`：这里只验证快照，不能证明环境当前可用。交付包含战略绑定、冻结接口、批准合同、构建部署及成功/失败验证；不把账号密码装入包。实际 API 和版本探测由已登记环境提供，不凭手册假设已有固定端点。
+后端预检输入使用 `delivery_kind: backend-delivery`，绑定工程身份、技术设计、冻结接口、批准合同、实际制品、部署证据和后端交付源记录。预期 `verified`，但离线验包不能证明环境当前可用。交付不包含账号密码；实际 API 和版本探测由已登记环境提供。
 
 ## 5. 前端联合接收与准备
 
@@ -82,6 +84,7 @@ node scripts/backend-delivery verify --bundle <交付包目录或ZIP>
 
 ```bash
 node scripts/backend-delivery import --bundle <交付包目录或ZIP> --target-root .
+node scripts/preflight-delivery --input <前端接收预检输入.json> --stage accept --json
 ```
 
 战略快照随交付链导入，后端包与战略包分别验证。导入产生接收草稿；核对目标词汇、规则/场景、接口和视觉用例后才能形成正式接收记录。
@@ -99,7 +102,7 @@ node scripts/backend-delivery import --bundle <交付包目录或ZIP> --target-r
 node scripts/verify-frontend-delivery --root . --slice <切片ID> <接收记录相对路径>
 ```
 
-成功是 `inputs-verified` 且 `ready_for_agent: false`。这允许准备计划和合同，正式编码仍须批准且当前的 Slice Contract。前端实现消费冻结 API；发现业务/API缺口回交维护方，不在前端仓悄悄重定义。
+成功是 `inputs-verified` 且 `ready_for_agent: false`。这允许准备前端工程设计、实现计划和合同，正式编码仍须批准且当前的 Slice Contract。Handoff v5 必须明确 `prototype`、`existing-ui-baseline` 或有原因的 `not-applicable`；发现业务、API 或 UI 基线缺口时回交维护方，不在前端仓悄悄重定义。
 
 ## 6. 实现、联调与业务验收
 

package/template/scripts/audit-legacy-backend-scaffold

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import process from "node:process";
+import { auditLegacyBackendScaffold } from "./lib/legacy-backend-scaffold-audit.mjs";
+
+function parse(argv) {
+  const options = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === "--project-root") options.projectRoot = argv[++index];
+    else if (token === "--manifest-ref") options.manifestRef = argv[++index];
+    else if (token === "--help" || token === "-h") options.help = true;
+    else throw new TypeError(`不支持的参数: ${token}`);
+  }
+  if (!options.help && !options.projectRoot) throw new TypeError("缺少 --project-root");
+  return options;
+}
+
+try {
+  const options = parse(process.argv.slice(2));
+  if (options.help) process.stdout.write("用法: scripts/audit-legacy-backend-scaffold --project-root <path> [--manifest-ref .yss/scaffold-generation.json]\n");
+  else {
+    const result = await auditLegacyBackendScaffold(options.projectRoot, { manifestRef: options.manifestRef });
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    if (result.status === "blocked") process.exitCode = 2;
+  }
+} catch (error) {
+  process.stderr.write(`❌ 历史后端脚手架审计失败: ${error.message}\n`);
+  process.exitCode = 1;
+}

package/template/scripts/backend-delivery

@@ -2,13 +2,29 @@
 import { parseArgs } from 'node:util';
 import path from 'node:path';
 import { exportBackendDelivery, openBackendDelivery, importBackendDelivery } from './lib/backend-delivery.mjs';
+import { read, safe, ensure } from './lib/strategic-handoff-io.mjs';
+
+async function preflightExport(values) {
+  const root=path.resolve(values['source-root']),delivery=read(safe(root,values.delivery));
+  const document=read(safe(root,delivery.slice_contract.ref)),contract=document.slice_contract||document;
+  const identity=contract.resolution?.architecture_identity||contract.backend?.architecture_identity||contract.architecture_identity;
+  ensure(identity?.schema_version!==2||values['preflight-input'],'preflight-required: 既有工程身份 v2 导出必须提供 --preflight-input <file>；先按 docs/process/delivery-preflight.md 准备源资产清单并执行 export 阶段只读预检');
+  if(!values['preflight-input'])return;
+  const {preflightDelivery}=await import('./lib/delivery-preflight.mjs');
+  const input=read(path.resolve(values['preflight-input']));
+  ensure(!input.delivery_kind||input.delivery_kind==='backend-delivery','preflight-scope-conflict: 后端导出只能使用 backend-delivery 清单');
+  ensure(path.resolve(root,input.governance_root||'.')===root,'preflight-scope-conflict: 预检治理根与导出来源不同');
+  ensure(input.assets?.backend_delivery?.ref===values.delivery,'preflight-scope-conflict: 预检未绑定本次导出的 delivery 源文件');
+  const result=await preflightDelivery({...input,delivery_kind:'backend-delivery'},{stage:'export',root});
+  if(result.exit_code!==0){const error=new TypeError('delivery-preflight-blocked: 请按每项 recovery 补证，再从正常导出入口重试');error.preflight=result;throw error;}
+}
 try {
-  const {values,positionals}=parseArgs({allowPositionals:true,options:{'source-root':{type:'string'},delivery:{type:'string'},output:{type:'string'},zip:{type:'boolean'},bundle:{type:'string'},'target-root':{type:'string'}}});
+  const {values,positionals}=parseArgs({allowPositionals:true,options:{'source-root':{type:'string'},delivery:{type:'string'},output:{type:'string'},zip:{type:'boolean'},bundle:{type:'string'},'target-root':{type:'string'},'preflight-input':{type:'string'}}});
   if(positionals.length!==1)throw new TypeError('必须指定 export / verify / import');
   let result;
-  if(positionals[0]==='export'&&values['source-root']&&values.delivery&&values.output)result=await exportBackendDelivery({sourceRoot:values['source-root'],deliveryRef:values.delivery,output:values.output,zip:values.zip});
+  if(positionals[0]==='export'&&values['source-root']&&values.delivery&&values.output){await preflightExport(values);result=await exportBackendDelivery({sourceRoot:values['source-root'],deliveryRef:values.delivery,output:values.output,zip:values.zip});}
   else if(positionals[0]==='verify'&&values.bundle)result=await openBackendDelivery(path.resolve(values.bundle),b=>({result:'verified',delivery_id:b.delivery.delivery_id,version:b.delivery.version,bundle_digest:b.manifest.bundle_digest,live_service_checked:false}));
   else if(positionals[0]==='import'&&values.bundle&&values['target-root'])result=await importBackendDelivery({bundle:path.resolve(values.bundle),targetRoot:values['target-root']});
-  else throw new TypeError('用法: backend-delivery export --source-root <repo> --delivery <ref> --output <new-dir> [--zip] | verify --bundle <dir|zip> | import --bundle <dir|zip> --target-root <repo>');
+  else throw new TypeError('用法: backend-delivery export --source-root <repo> --delivery <ref> --output <new-dir> [--preflight-input <file>] [--zip] | verify --bundle <dir|zip> | import --bundle <dir|zip> --target-root <repo>');
   process.stdout.write(`${JSON.stringify(result,null,2)}\n`);
-} catch(error) { process.stderr.write(`${JSON.stringify({result:'blocked',error:error.message})}\n`);process.exitCode=1; }
+} catch(error) { process.stderr.write(`${JSON.stringify({result:'blocked',error:error.message,...(error.preflight?{preflight:error.preflight}:{})})}\n`);process.exitCode=1; }

package/template/scripts/lib/api-contract-decision.mjs

@@ -0,0 +1,49 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseDocument } from "../vendor/yaml.mjs";
+import { validateJsonSchema } from "./json-schema.mjs";
+import { openApiDigest, resolveOpenApiRef, validateOpenApiDraftValidationRecord } from "./openapi-draft-validation.mjs";
+
+const TEMPLATE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+const SCHEMA = path.join(TEMPLATE_ROOT, "docs/process/schemas/api-contract-decision.schema.json");
+const fail = (message) => { throw new TypeError(message); };
+const readBound = (root, ref, label) => {
+  const file = resolveOpenApiRef(root, ref);
+  const bytes = readFileSync(file);
+  return { file, bytes, digest: openApiDigest(bytes), label };
+};
+const requireDigest = (asset, expected) => { if (asset.digest !== expected) fail(`${asset.label}摘要漂移`); };
+
+export function validateApiContractDecision(binding, { root = TEMPLATE_ROOT } = {}) {
+  if (!binding || !binding.ref || !binding.version || !binding.digest || !["required", "not-applicable"].includes(binding.impact)) fail("缺少 API Contract Decision 当前版本绑定");
+  const projectRoot = path.resolve(root);
+  const decisionAsset = readBound(projectRoot, binding.ref, "API Contract Decision");
+  requireDigest(decisionAsset, binding.digest);
+  const document = parseDocument(decisionAsset.bytes.toString("utf8"), { uniqueKeys: true, maxAliasCount: 0 });
+  if (document.errors.length) fail(`API Contract Decision 无法解析: ${document.errors[0].message}`);
+  const decision = document.toJS({ maxAliasCount: 0 });
+  validateJsonSchema(decision, SCHEMA, { cwd: TEMPLATE_ROOT, label: "API Contract Decision v1" });
+  if (decision.decision_version !== binding.version || decision.impact !== binding.impact) fail("API Contract Decision 版本或影响结论与合同不一致");
+  requireDigest(readBound(projectRoot, decision.assessment_ref, "API 影响评估"), decision.assessment_digest);
+  for (const ref of decision.evidence_refs) readBound(projectRoot, ref, "API Decision 证据");
+  if (decision.impact === "not-applicable") return { decision, binding: { ref: binding.ref, version: binding.version, digest: binding.digest, impact: decision.impact } };
+
+  const draft = readBound(projectRoot, decision.openapi.ref, "OpenAPI YAML");
+  requireDigest(draft, decision.openapi.digest);
+  const validation = readBound(projectRoot, decision.validation_record.ref, "OpenAPI Validation");
+  requireDigest(validation, decision.validation_record.digest);
+  const review = readBound(projectRoot, decision.draft_review.ref, "OpenAPI Draft Review");
+  requireDigest(review, decision.draft_review.digest);
+  const reviewDocument = parseDocument(review.bytes.toString("utf8"), { uniqueKeys: true, maxAliasCount: 0 });
+  if (reviewDocument.errors.length) fail(`OpenAPI Draft Review 无法解析: ${reviewDocument.errors[0].message}`);
+  const reviewRecord = reviewDocument.toJS({ maxAliasCount: 0 });
+  if (reviewRecord?.result !== "approved" || !Array.isArray(reviewRecord.blocking_findings) || reviewRecord.blocking_findings.length > 0) fail("OpenAPI Draft Review 实际记录未批准或仍有阻断项");
+  if (reviewRecord.draft_ref !== decision.openapi.ref || reviewRecord.draft_digest !== decision.openapi.digest) fail("OpenAPI Draft Review 实际记录未绑定当前权威 YAML");
+  for (const ref of decision.draft_review.evidence_refs) readBound(projectRoot, ref, "OpenAPI Draft Review 证据");
+  const validated = validateOpenApiDraftValidationRecord(validation.file, { root: projectRoot });
+  if (validated.record.draft.ref !== decision.openapi.ref || validated.draftDigest !== decision.openapi.digest) fail("OpenAPI Validation 未绑定当前权威 YAML");
+  if (decision.draft_review.draft_ref !== decision.openapi.ref || decision.draft_review.draft_digest !== decision.openapi.digest || decision.draft_review.blocking_findings.length) fail("OpenAPI Draft Review 未批准当前权威 YAML");
+  if (decision.freeze.version !== decision.openapi.version || decision.freeze.draft_ref !== decision.openapi.ref || decision.freeze.draft_digest !== decision.openapi.digest) fail("OpenAPI Freeze 未绑定当前权威 YAML 版本和摘要");
+  return { decision, openapi: decision.openapi, binding: { ref: binding.ref, version: binding.version, digest: binding.digest, impact: decision.impact } };
+}

package/template/scripts/lib/api-contract-decision.test.mjs

@@ -0,0 +1,69 @@
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { validateApiContractDecision } from "./api-contract-decision.mjs";
+
+const digest = (bytes) => `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+
+function write(root, ref, value) {
+  const file = path.join(root, ref);
+  mkdirSync(path.dirname(file), { recursive: true });
+  writeFileSync(file, typeof value === "string" ? value : `${JSON.stringify(value, null, 2)}\n`);
+  return { ref, file, digest: digest(readFileSync(file)) };
+}
+
+function notApplicableFixture() {
+  const root = mkdtempSync(path.join(os.tmpdir(), "api-contract-decision-"));
+  const assessment = write(root, "api-impact.json", { api: false, project_id: "demo" });
+  const evidence = write(root, "api-impact-evidence.md", "无 API 影响证据。\n");
+  const decision = {
+    schema_version: 1,
+    kind: "api-contract-decision",
+    decision_id: "api-contract.demo",
+    decision_version: "v1",
+    status: "approved",
+    current_version: true,
+    impact: "not-applicable",
+    assessment_ref: assessment.ref,
+    assessment_digest: assessment.digest,
+    evidence_refs: [evidence.ref],
+    reason: "不新增或修改 HTTP、消息或集成接口",
+  };
+  const asset = write(root, "api-contract-decision.json", decision);
+  return { root, assessment, evidence, decision, asset, binding: { ref: asset.ref, version: "v1", digest: asset.digest, impact: "not-applicable" } };
+}
+
+test("API not-applicable 决定必须绑定影响评估、原因和可读证据", () => {
+  const data = notApplicableFixture();
+  try {
+    assert.equal(validateApiContractDecision(data.binding, { root: data.root }).decision.impact, "not-applicable");
+    for (const mutation of [
+      (value) => { delete value.reason; },
+      (value) => { value.evidence_refs = []; },
+      (value) => { value.openapi = { id: "openapi.demo", ref: "empty.yaml", version: "v1", digest: `sha256:${"0".repeat(64)}` }; },
+    ]) {
+      const value = structuredClone(data.decision);
+      mutation(value);
+      const changed = write(data.root, "api-contract-decision.json", value);
+      assert.throws(() => validateApiContractDecision({ ...data.binding, digest: changed.digest }, { root: data.root }));
+    }
+  } finally {
+    rmSync(data.root, { recursive: true, force: true });
+  }
+});
+
+test("API Decision 或影响评估原始字节漂移即失效", () => {
+  const data = notApplicableFixture();
+  try {
+    writeFileSync(data.asset.file, "\n", { flag: "a" });
+    assert.throws(() => validateApiContractDecision(data.binding, { root: data.root }), /摘要漂移/);
+    const restored = write(data.root, data.asset.ref, data.decision);
+    writeFileSync(data.assessment.file, "\n", { flag: "a" });
+    assert.throws(() => validateApiContractDecision({ ...data.binding, digest: restored.digest }, { root: data.root }), /摘要漂移/);
+  } finally {
+    rmSync(data.root, { recursive: true, force: true });
+  }
+});