ai-delivery-workflow 0.2.2 → 0.4.0

package/docs/PROJECT-MANUAL.zh-CN.md

@@ -1,8 +1,10 @@
 # AI Delivery Workflow 完整项目手册
 
+当前研发生产模型是 `development-seven-node`：`00-bootstrap -> 01-product-shaping -> 02-solution-design -> 03-delivery-readiness -> 04-implementation -> 05-candidate-assurance -> 06-version-closeout`。旧 13 节点仅用于历史 inspect、verify 和显式迁移；新项目和现行生产 Skill 不再生成旧节点 ID。
+
 > 仓库身份：当前源码仓库是工作流维护与发行项目，不是下文所述的业务工作区。不要对当前源码仓库套用双仓初始化、业务项目 bootstrap 或 `.workflow/` 状态恢复；下文双仓契约描述的是安装目标。
 >
-> 当前工作区契约：本手册现行版本只支持“工作流控制仓库 + 一个直接子目录代码仓库”，不支持旧单仓迁移，也不使用 Git submodule。完整规则见 [DUAL-REPOSITORY-WORKSPACE.zh-CN.md](DUAL-REPOSITORY-WORKSPACE.zh-CN.md)。
+> 当前工作区契约：本手册现行运行形态只支持“工作流控制仓库 + 一个直接子目录代码仓库”，也不使用 Git submodule。`migrate` 只转换旧工作流物料布局，不负责把单仓代码历史拆成双仓；双仓建立或绑定规则见 [DUAL-REPOSITORY-WORKSPACE.zh-CN.md](DUAL-REPOSITORY-WORKSPACE.zh-CN.md)。
 
 ```text
 workspace/.git                 工作流 Git
@@ -13,12 +15,14 @@ workspace/code/.git            代码 Git
 
 初始化器会创建缺失的工作流 Git 和代码 Git，或绑定已有代码 Git，或使用 `--code-remote` clone；根 `.gitignore` 精确加入 `/code/`。所有代码扫描和代码 Git 命令只针对配置的代码目录。
 
-初始化器还会合并根 `.gitattributes`，对 `.workflow/**`、项目级 `ai-delivery-*` Skills、`.codex/config.toml`、`AGENTS.md`、`.gitignore` 和 `.gitattributes` 强制 `eol=lf`。这是 checksum 可移植性约束；不会修改嵌套代码仓的换行策略。缺失规则会使 `doctor` 失败，避免 Windows checkout 后正式状态和物料被误判为篡改。
+初始化器还会合并根 `.gitattributes`，对 `.workflow/**`、项目级 `ai-delivery-*` Skills、`.codex/config.toml`、`AGENTS.md`、`.gitignore` 和 `.gitattributes` 强制 `eol=lf`。这是 checksum 可移植性约束；不会修改嵌套代码仓的换行策略。已冻结的旧迭代证据必须在根 `.gitattributes` 中使用精确路径，或“固定迭代目录 + 文件名 glob”的窄 `-text` 规则登记后，才能保留 raw checksum；嵌套或全局 attributes 不能自行获得该例外。产品、控制、工具等其他路径和 `text eol=crlf` 覆盖也不享受该例外。缺失或无效规则会使 `doctor` 失败，避免 Windows checkout 后正式状态和物料被误判为篡改。
 
 > 文档版本：1.0  
-> 适用包版本：`ai-delivery-workflow@0.2.0`
+> 适用包版本：`ai-delivery-workflow@0.4.0`
 > 默认文档语言：简体中文  
 > 文件级索引：[FILE-REFERENCE.zh-CN.md](FILE-REFERENCE.zh-CN.md)  
+> CodeGraph 可选集成：[CODEGRAPH-INTEGRATION.zh-CN.md](CODEGRAPH-INTEGRATION.zh-CN.md)
+> Microcks Mock System：[MOCK-SYSTEM.zh-CN.md](MOCK-SYSTEM.zh-CN.md)
 > 全流程审计物料（历史 V1 与当前契约 V2）：[../audit/README.md](../audit/README.md)
 > 正式状态命令：[STATE-CLI-USER-GUIDE.zh-CN.md](STATE-CLI-USER-GUIDE.zh-CN.md)
 
@@ -121,7 +125,9 @@ AI Delivery Workflow 是一套安装在单个代码仓库内的 AI 研发流程
       hooks/hook-event.mjs        # Hook 事件记录器
       state/                       # 自包含正式状态 CLI 与 YAML 运行时
       evolution/                   # 自包含 Evolution CLI
-      viewer/                      # 可选、只读、可重装的工作流查看器
+      mock/                        # 自包含 Microcks Mock System CLI
+      manager/                     # 正式工作流管理器 runtime 与静态界面
+    mock-system/                   # 隔离的 external/product-backend catalog 与合同定义
     delivery/
       project.yaml                # 项目描述与旧字段兼容回退
       workflow-state.yaml         # 正式流程、Gate、累计研发和生产身份
@@ -145,7 +151,7 @@ AI Delivery Workflow 是一套安装在单个代码仓库内的 AI 研发流程
   .gitattributes                  # 固定工作流受控文本为 LF
 ```
 
-安装器为上述可能为空但必须跨 clone 保留的内容目录，以及 `.workflow/control/` 下的任务、Checkpoint、物料、Gate、版本、发布和事件分片目录创建 `.gitkeep`。这些占位文件属于结构契约；重新克隆后无需再次执行 `init` 即可通过 `doctor`。
+安装器为上述可能为空但必须跨 clone 保留的内容目录，以及 `.workflow/control/` 下的任务、Checkpoint、物料、Gate、版本、发布、事件、迁移和修复分片目录创建 `.gitkeep`。这些占位文件属于结构契约；重新克隆后无需再次执行 `init` 即可通过 `doctor`。`upgrade` 会把旧安装缺失的 `migrations/` 和 `repairs/` 作为 `ensure-directory` 新增项恢复；目录已存在但缺少 `.gitkeep` 时，只以独立 `ensure-directory-marker` 新增项恢复 marker。已存在目录及其中用户物料不属于安装器所有，也不会被替换。
 
 ## 5. 安装、升级与诊断
 
@@ -168,25 +174,15 @@ npx ai-delivery-workflow@latest doctor .
 
 这只会写入当前项目，不会安装全局 skill。
 
-`init` 会同时内置正式状态 CLI 和本地工作流物料查看器，不修改业务项目 `package.json`。安装完成后无需安装额外前端依赖，直接在目标项目运行：
-
-```powershell
-.\.workflow\tools\viewer\start.cmd
-```
+`workspace-directory`、`--workspace-id`、`--code-path`、`--code-id`、三种远程参数、`--dry-run` 和 `--force` 的完整含义、默认值、互斥关系及重复初始化规则见 [CLI 安装参数参考](CLI-PARAMETER-REFERENCE.zh-CN.md)。
 
-或：
+`init` 会同时内置正式状态 CLI 和 Workflow Manager，不修改业务项目 `package.json`，也不需要在业务项目安装额外前端依赖。可只读检查：
 
 ```powershell
-.\.workflow\tools\viewer\start.ps1
-```
-
-macOS/Linux：
-
-```bash
-sh ./.workflow/tools/viewer/start.sh
+npx ai-delivery-workflow@latest manager inspect .
 ```
 
-服务默认监听 `127.0.0.1:4173` 并打开浏览器。可使用 `--port 4180` 指定端口，使用 `--no-open` 禁止自动打开浏览器。查看器只读取 `.workflow/`，不会修改、批准、迁移或删除正式物料。
+Windows 使用 `.\.workflow\tools\manager\start.cmd` 或 `start.ps1` 启动；macOS/Linux 使用 `sh ./.workflow/tools/manager/start.sh`。等价的发行包入口是 `ai-delivery manager serve .`。服务只绑定 `127.0.0.1`；可用 `--port` 固定端口，`--no-open` 禁止自动打开浏览器。19 个 Page 使用正式项目事实，未登记能力明确显示“尚未登记”。旧 `.workflow/tools/viewer/` 和独立 Prototype Review Server 不再安装；旧项目升级时 Viewer 通过带备份的 Receipt 操作移除。
 
 ### 5.3 从本地源码安装到另一个项目
 
@@ -200,91 +196,121 @@ node E:\work\ai\codex\workflow\bin\ai-delivery.mjs doctor E:\path\to\target-proj
 也可先在本仓库执行 `npm pack`，再在目标项目使用生成的 `.tgz`：
 
 ```powershell
-npx --yes --package E:\path\to\ai-delivery-workflow-0.2.0.tgz ai-delivery init .
+npx --yes --package E:\path\to\ai-delivery-workflow-0.4.0.tgz ai-delivery init .
 ```
 
 安装完成后，在目标项目中新建 Codex 任务。不要继续依赖安装前的会话来判断 skill 是否可用。
 
 ### 5.4 预览和处理冲突
 
-只预览，不写文件：
+首次安装只预览、不写文件：
 
 ```bash
 npx ai-delivery-workflow@latest init . --dry-run
 ```
 
-同一发行版本内检测到受管 Skill、Hook 或核心运行时被修改时，默认安装会停止。确认需要采用当前发行基线覆盖这些修改后，才执行：
+安装完成后，升级必须改用独立命令。先执行严格零写预览：
 
 ```bash
-npx ai-delivery-workflow@latest init . --force
+npx ai-delivery-workflow@latest upgrade . --dry-run
 ```
 
-`--force` 会把被替换的受管文件备份到 `.workflow/delivery/runtime/backups/<timestamp>/`。它不会授权覆盖冲突的已批准规范正文；规范冲突必须按规范治理流程处理。
+审阅结构化报告中的 additions、replacements、preserved、preserved_summary、conflicts、backups 和 compatibility 后执行：
 
-当安装器检测到有效安装清单中的包版本发生变化时，会自动备份并升级受管 Skill、Hook、Bootstrap、状态、Evolution 和查看器；产品、架构、体验、迭代、发布、规范及正式状态物料不被替换。升级后仍需执行 `doctor`。
+```bash
+npx ai-delivery-workflow@latest upgrade .
+```
+
+`preserved` 会逐项列出内容未变的受管资产，并最多列出 200 个受管安装资产之外的文件。`preserved_summary` 的 `total_files`、`reported_files` 和 `omitted_files` 汇总后一类文件；`excluded_transient_roots` 列出不参与统计的瞬态根，当前为 `.workflow/delivery/runtime`。明细被省略只限制 JSON 体积，不代表升级会删除或忽略这些业务文件。
+
+升级会把收据和被替换副本写入 `.workflow/delivery/runtime/upgrades/<upgrade-id>/`。它只处理安装清单拥有的受管资产；产品、架构、体验、迭代、发布、规范、正式状态物料、用户配置部分及嵌套代码仓库不被替换。受管副本相对安装清单发生本地漂移时默认停止；只有明确批准采用发行基线后才使用 `upgrade --force`。
 
 安装器不会把降级当作升级。目标包版本早于已安装版本时默认拒绝；只有用户明确批准降级并审阅备份影响后，才可使用 `--force`。
 
-旧项目中的 `.ai-delivery/` 会在升级时先完整备份，再迁入 `.workflow/config/` 和 `.workflow/tools/`；验证失败时旧目录不会删除。`.workflow/tools/viewer/` 是唯一可选工具，删除后不影响核心工作流，重新执行 `init` 即可恢复。
+旧项目兼容迁移属于独立 `migrate` 流程。`upgrade` 只安装迁移能力并在 `prototype_migration.required_follow_up` 报告后续命令，不写 Prototype 迁移目标；真正迁移只在审阅 `migrate --dry-run` 后执行。结构迁移不推断业务完成度，不激活或关闭任务，不改变 scope，也不重写旧事件。错误归档由独立 `repair` 前向事务失效，原归档字节不变。旧 `.workflow/tools/viewer/` 不再是可选安装能力；升级会将其备份并移除，受保护回滚可恢复升级前字节。
 
 ### 5.5 升级
 
 推荐步骤：
 
 1. 提交或备份业务项目当前改动。
-2. 执行新版 `init --dry-run`。
+2. 执行新版 `upgrade --dry-run`。
 3. 审阅 skill、Hook 和模板变化。
 4. 处理规范冲突。
-5. 执行新版 `init`；仅在同版本受管文件冲突且明确采用发行基线时使用 `--force`。
+5. 执行新版 `upgrade`；仅在受管副本漂移且明确采用发行基线时使用 `--force`。
 6. 执行 `doctor`。
-7. 新建 Codex 任务，对 AI 说“继续”；AI 自主调用 Bootstrap 和后续 Skill。
+7. 对旧 schema、旧任务模型或旧 Prototype member/set 执行 `migrate --dry-run`，审阅 schema、任务分组、零/单/多成员计划、terminal/Page/route/file 合并报告、歧义、冲突、anchor 和文件变化。
+8. 只有报告 `can_apply: true` 时执行 `migrate`；任务与 Prototype 冲突使用同一 checksum 绑定决定文件，业务状态冲突先形成独立 repair 决定。
+9. 新建 Codex 任务，对 AI 说“继续”；AI 自主调用 Bootstrap 和后续 Skill。
 
-#### 从旧目录布局迁移
+升级完成但尚未产生新的 schema 2 正式事务时，可以执行 `upgrade . --rollback <upgrade-id>` 恢复升级前受管副本和安装清单。新增正式事务或升级后再次修改受管副本会关闭回滚窗口，此时必须前向修复。
 
-早期项目可能把流程状态放在根目录 `delivery/` 和 `standards/`。升级前必须：
+#### 兼容结构迁移与业务修复
 
-1. 停止所有正在运行的工作流任务并保存 checkpoint。
-2. 将 `delivery/` 移动为 `.workflow/delivery/`。
-3. 将 `standards/` 移动为 `.workflow/standards/`。
-4. 将其他研发流程文档按类型迁入 `.workflow/product/`、`.workflow/architecture/`、`.workflow/experience/` 或 `.workflow/iterations/<iteration-id>/<node-id>/`。
-5. 更新注册表路径、交付物引用和受影响 checksum。
-6. 将 `.gitignore` 中的 `delivery/runtime/` 改为 `.workflow/delivery/runtime/`，不得忽略整个 `.workflow/`。
-7. 确认根目录不再残留旧 `delivery/` 或 `standards/` 后，执行 `init --dry-run`、`init` 和 `doctor`。
+`migrate --dry-run` 是旧 schema、旧全量快照事件、旧任务模型和旧 Prototype member/set 的审阅入口。报告包含源/目标 schema、按语义契约精确匹配的逻辑任务组、需要人工确认的候选族、正式状态/归档冲突、经 pointer、anchor、snapshot 和 revision 校验的可信历史 anchor、`prototype_migration` 零/单/多成员计划，以及精确文件变化。`F/R/T/P/vN` 后缀只提示候选关系；goal、scope、依赖、输出、acceptance 或代码身份不同就不能据此自动合并。显式 `derived_from`/`supersedes` 作为关系边记录，不作为必须相等的普通字段。
 
-安装器检测到旧布局或新旧布局并存时会停止，不会自动移动文件或选择权威状态。
+旧根布局迁移会把 `delivery/`、`control/`、`standards/` 复制到 `.workflow/`，根目录源证据保持原字节；当前布局中的平铺任务会原位增加显式 `attempts`，原字节备份到 `.workflow/control/migrations/<migration-id>/backups/`。manifest 记录每个源、目标和备份的 SHA-256。新增 attempts 只投影既有 lifecycle 事实，不激活或关闭任务，不改变顶层 status、scope、正式 view 或旧事件。
+
+任务族或 Prototype 合并仍有歧义时，使用一份决定文件：`decisions` 来自 `task_grouping.decision_template`，`prototype_decisions` 来自 `prototype_migration.decision_template`。填写 `human:<identity>` actor、逐项 rationale 和 dry-run 返回的稳定身份，再用 `migrate . --decisions <file> --dry-run` 复核。决定文件绑定 `anchors.proposed.source_checksum`；源文件或候选集合变化后必须重新决定。单 Prototype 迁移只在 member 身份、manifest/source/catalog checksum 和目标路径都无歧义时自动应用；多成员按 terminal、Page、route、file 生成合并报告。旧 member/set、关闭或归档 Prototype、Gate 与旧事件保持原字节，新文件只写入 `.workflow/experience/<iteration-id>/`，状态为 `migration-pending-ux-ui`，开放迭代必须冻结新 revision 并重新通过 `UX-UI`。完整字段和操作见 [Prototype 迁移指南](PROTOTYPE-MIGRATION.zh-CN.md)。迁移后尚无新 schema 2 事务且迁移目标字节未漂移时，可以执行 `migrate . --rollback <migration-id>` 删除复制目标并恢复任务备份；一旦产生新事务或目标漂移，回滚 fail-closed，只允许前向修复。
+
+错误版本归档不得直接编辑或删除。使用 `repair --invalidate-archive`，提供 `human:<identity>` actor、原因、RCA evidence 和恢复 evidence。dry-run 返回原归档 tree checksum 与计划事务路径；应用后在 `.workflow/control/repairs/transactions/` 追加带前序 checksum 的事务，并把当前资格投影为 `invalidated`，原 `.workflow/control/archives/versions/<iteration-id>/` 保持逐字节不变。
 
 ### 5.6 CLI 命令
 
 | 命令 | 是否写文件 | 用途 |
 | --- | --- | --- |
 | `ai-delivery init [project]` | 是 | 安装 25 个 Skills、Hook、Bootstrap/状态/Evolution CLI、初始交付模板和默认规范。 |
-| `ai-delivery init [project] --dry-run` | 否 | 预览安装或升级动作。 |
-| `ai-delivery init [project] --force` | 是 | 备份并替换冲突的受管文件。 |
+| `ai-delivery init [project] --dry-run` | 否 | 预览首次安装动作。 |
+| `ai-delivery init [project] --force` | 是 | 首次安装时备份并替换冲突的受管文件。 |
+| `ai-delivery upgrade [project] --dry-run` | 否 | 结构化预览受管资产升级，严格零写。 |
+| `ai-delivery upgrade [project] [--force]` | 是 | 备份并升级安装清单拥有的受管资产。 |
+| `ai-delivery upgrade [project] --rollback <upgrade-id>` | 是 | 在没有后续正式事务或受管漂移时恢复升级前版本。 |
+| `ai-delivery migrate [project] --dry-run` | 否 | 报告 schema、任务分组/歧义、冲突、anchor 和精确文件变化。 |
+| `ai-delivery migrate [project] [--decisions <file>]` | 是 | 在无未决冲突/歧义时复制旧布局、显式化 task attempts 并写迁移清单；不改变业务状态。 |
+| `ai-delivery migrate [project] --rollback <migration-id>` | 是 | 在没有迁移后 schema 2 事务或目标漂移时删除复制目标并恢复任务备份。 |
+| `ai-delivery repair [project] --invalidate-archive <iteration-id> ... [--dry-run]` | 视参数而定 | 预览或追加错误归档的独立前向失效事务；保留原证据字节。 |
+| `ai-delivery compact [project] --dry-run` | 否 | 零写入验证 legacy history、可信 anchor、压缩包计划与预计净释放空间。 |
+| `ai-delivery compact [project]` | 是 | 写入 checksummed gzip archive；从包内完整 replay 到锚定 registry checksum 后才移除 loose shards。 |
 | `ai-delivery inspect [project]` | 否 | 输出机器可读的项目、代码、流程和运行时状态。 |
 | `ai-delivery bootstrap [project]` | 视状态而定 | 初始化空项目或存量项目上下文，或把中断项目路由到恢复。 |
 | `ai-delivery bootstrap [project] --dry-run` | 否 | 预览引导动作。 |
-| `ai-delivery doctor [project]` | 否 | 校验安装清单、关键 skills、Hook 配置和项目文件。 |
+| `ai-delivery doctor [project]` | 否 | 校验发行包表面、安装清单、关键 skills、Hook、运行时和持久项目文件；排除 `.workflow/delivery/runtime`，状态 inspect 使用 16 MiB 有界缓冲并验证 JSON 协议，Git attributes 使用有界批次检查。 |
+| `ai-delivery codegraph setup [project]` | 是 | 显式关闭 telemetry，并为配置中的代码仓初始化本地 CodeGraph 索引。 |
+| `ai-delivery codegraph setup [project] --dry-run` | 否 | 只读验证 `CODEGRAPH_DIR`、索引文件与 Git 边界，只调用 `codegraph --version`，并输出 telemetry、local exclude 和初始化计划。 |
+| `ai-delivery codegraph sync [project]` | 是 | 增量同步已有 CodeGraph 索引并重新验证目标代码仓。 |
+| `ai-delivery codegraph sync [project] --dry-run` | 否 | 只读验证已有索引并输出 local exclude 和同步计划。 |
+| `ai-delivery mock setup [project] [--dry-run]` | 视参数而定 | 探测 Docker/Podman、拉取固定 Microcks digest，并创建隔离的 External Dependency 与 Product Backend Mock catalog；dry-run 零写入。 |
+| `ai-delivery mock start [project] [--dry-run]` | 视参数而定 | 以 in-memory、`--rm` 容器启动 Microcks，只绑定 `127.0.0.1:8585` 并等待健康；健康失败时停止本次容器。 |
+| `ai-delivery mock status [project]` | 否 | 只读组合容器状态与 `/api/health`。 |
+| `ai-delivery mock sync [project] [--dry-run]` | 视参数而定 | 校验两类 Mock 的 kind、owner、批准合同、replacement condition、operation/channel、具名 scenario、dispatcher 输入和合同路径，并同步到本地 Microcks；dry-run 不访问 API。 |
+| `ai-delivery mock freeze [project] --experience <dir> --scenario-pack <yaml> [--dry-run]` | 视参数而定 | 校验 Prototype revision、每个 Review Scene 的唯一 deterministic scenario、受管 UI 实际导出物 checksum、协议/场景 inventory 和数据脱敏；dry-run 返回 candidate checksum，人工确认后写不可变 Pack，正式登记后才具权威性。 |
+| `ai-delivery mock stop [project] [--dry-run]` | 视参数而定 | 停止易失容器，保留 tracked catalog 与合同。 |
+| `ai-delivery manager inspect [project]` | 否 | 输出 CLI、HTTP 与正式界面共用的 `workflow-manager.v1` 投影。 |
+| `ai-delivery manager list/show/export [project] --resource <resource>` | 否 | 读取 `manager`、`contracts`、`facts`、`prototypes`、`prototype-source-snapshots`、`attachments`、`systems`、`mock` 或 `settings`；源码快照按登记的 `source_snapshot_id`/checksum 读取，禁止任意路径；附件按精确 ID/checksum 读取。 |
+| `ai-delivery manager action <action-name> --help` | 否 | 从当前版本化契约显示授权、并发、幂等、plan 和输入字段。 |
+| `ai-delivery manager action <action-name> [project] --input <json-file>` | 是 | 通过 UI 共用应用服务执行受控动作，并返回结构化结果、Receipt 和 Event。 |
+| `ai-delivery manager serve [project] [--port <port>] [--no-open]` | 否 | 只绑定 loopback 并启动正式工作流管理器；不修改正式状态。 |
 | `ai-delivery state <command> --project <project>` | 视子命令而定 | 发行包维护入口；透传正式状态命令。项目执行时优先用项目内 `.workflow/tools/state/state.mjs`。 |
 | `ai-delivery evolve <command> --project <project>` | 视子命令而定 | 记录反馈并治理项目级扩展。项目执行时优先用项目内 `.workflow/tools/evolution/evolve.mjs`。 |
 | `ai-delivery --version` | 否 | 输出包版本。 |
 
+CodeGraph 是可选代码智能适配器。`doctor` 对其缺失或未初始化只输出警告，`init`/`upgrade` 不安装 CLI、MCP 或索引；完整的降级顺序、缓存、telemetry、Windows/WSL 和测试建议边界见 [CodeGraph 可选集成指南](CODEGRAPH-INTEGRATION.zh-CN.md)。
+
+Mock System 使用固定版本与 digest 的 Microcks Uber 镜像，External Dependency Mock 与 Product Backend Mock 始终分离。容器数据库、日志和流量可丢弃，仓库 catalog、合同定义及正式登记的不可变 Mock Scenario Pack 才是可重建输入。生产流量录制、生产凭据和未脱敏个人数据禁止进入 Pack；Product Backend Mock 可驱动 UI 场景但不能满足真实后端或端到端验收。完整操作、安全和验证边界见 [Microcks Mock System 使用指南](MOCK-SYSTEM.zh-CN.md)。
+
 完全未安装的项目不能依靠项目内 skill 自行引导，因为此时 skill 尚不存在。第一次必须先通过 CLI 执行 `init` 或 `bootstrap`。
 
-### 5.7 工作流物料查看器
+### 5.7 Workflow Manager
+
+Workflow Manager 是唯一项目内控制面。P01-P19 汇总七节点状态、需求、任务、测试、交付成果、人工决策、业务项目原型、项目系统、Mock、事件和设置；P13 是从原型审批或路由页面进入的上下文详情页。UI、HTTP 和 `manager list/show/export/action` CLI 使用同一应用服务。
 
-查看器是随 `init` 安装的项目内只读系统，主要提供：
+界面不是任意文件编辑器或命令执行器。原型评论/截图/审核、系统初始化脚本/生命周期、Mock 同步、Gate 决定、需求关系和设置修改只能调用发行白名单动作，按能力验证 actor、expected revision/checksum、幂等键和 plan checksum，并生成 Receipt/Event。完整用法见[工作流管理器使用指南](VIEWER-USER-GUIDE.zh-CN.md)；修改前阅读[工作流管理器维护指南](VIEWER-MAINTENANCE.zh-CN.md)，AI 操作遵循 [Workflow Manager Agent Interface](agents/workflow-manager-agent-interface.md)。
 
-- 按当前迭代和 17 个研发节点查看物料数量与进度；
-- 按状态、类型、节点、Git 变更和全文关键字筛选；
-- 展示物料 ID、版本、更新时间、大小、Git 状态和 SHA-256；
-- 从文档路径引用推导上游与下游关系；
-- 识别正文采用的规范 ID；
-- 格式化预览 Markdown、CSV、JSON、YAML、JSONL、TOML、文本和图片；
-- 在窄屏上把详情区切换为抽屉，保留节点、筛选和物料表主流程。
+### 5.8 项目原型审核
 
-默认只绑定本机回环地址。确需允许局域网访问时可显式传入 `--host`，但必须先评估项目文档的敏感性和终端网络边界。查看器不会提供写接口，也不会读取 `.workflow/` 之外的文件。
+`UX-VS` 在 P11 核对唯一 Visual Standard；冻结并校验 Prototype Revision 后，P12 显示当前迭代完整、可筛选的 Page 队列，P13 显示 Page 的全部 Review Scene、精确路由、评论、截图和审核动作。内容通过受限 iframe 渲染，不能访问父级控制面或直接写正式状态。
 
-完整操作、字段识别、升级和故障处理见[工作流物料查看器使用指南](VIEWER-USER-GUIDE.zh-CN.md)；修改源码、扩展 API 或调整界面前，先阅读[工作流物料查看器维护指南](VIEWER-MAINTENANCE.zh-CN.md)。
+Page 决定和修改要求绑定精确 Revision、Page/Scene 及 checksum。修改要求可反复编辑，AI 开始执行前可废弃；进入执行后锁定。修改 Prototype 后必须形成新 Revision 并重新审核，只有 checksum 完全一致的最新批准可以继续有效。独立 `prototype-review start` 命令已退役。
 
 ## 6. 项目状态识别与自主规划
 
@@ -304,7 +330,7 @@ node .workflow/tools/bootstrap/bootstrap.mjs inspect
 | `workflow-interrupted` | 存在活动、中断、阻塞或依赖就绪任务。 | 先读取 `next_action_owner`；仅 `agent` 转到 checkpoint 恢复，`user/external` 只返回问题或等待条件且零写入。 |
 | `workflow-inconsistent` | 安装不完整、状态损坏、身份冲突或依赖缺失。 | 停止推进，修复一致性问题。 |
 
-`bootstrap` 为新项目生成的文件全部是 `draft`：
+`bootstrap` 为新项目生成的文件全部是 `draft`，通过带 checksum 的 `bootstrap/latest.yaml` 指针发现，但不进入正式 artifact registry，也不产生 artifact event shard：
 
 ```text
 .workflow/delivery/bootstrap/
@@ -329,9 +355,8 @@ flowchart LR
   B["Bootstrap"] --> D["产品发现"]
   D --> P["产品定义"]
   P --> A1["初始架构"]
-  A1 --> LF["可运行低保真原型 / UX-LF"]
   A1 --> PLAT["平台准备"]
-  LF --> VS["视觉系统与框架 / UX-VS"]
+  A1 --> VS["视觉系统与框架 / UX-VS"]
   VS --> UI["可运行正式 UI / UX-UI"]
   UI --> PR["产品与原型统一核对"]
   PR --> A2["架构校准"]
@@ -356,7 +381,7 @@ flowchart LR
 | 1 | 产品发现 `$ai-delivery-define-product` | 用户原始想法、存量观察 | 逐项访谈问题、用户、目标、边界、假设和成功信号 | `discovery-baseline.md`、Gate A 决策 | 人工 Gate A |
 | 2 | 产品定义 `$ai-delivery-define-product` | 已批准发现基线 | 定义终端、功能、关联、故事、验收标准、版本路线和统一术语 | 产品手册、产品基线、终端矩阵、功能表、功能详情、故事、验收标准、版本路线图 | 人工 Gate B |
 | 3 | 初始架构 `$ai-delivery-design-architecture` | 产品基线、终端和质量约束 | 设计应用、技术、数据、安全、部署和可观测架构；选择技术栈 | 初始架构、技术栈清单、接口草案、架构决策 | 重大决策人工批准 |
-| 4 | 体验设计 `$ai-delivery-design-experience` | 产品基线、终端矩阵、功能说明、初始架构 | 选原型工具；制作可运行低保真原型并通过 `UX-LF`；选视觉系统/UI 框架并通过 `UX-VS`；制作可运行正式 UI 并通过 `UX-UI`；逐条记录调整；最后统一核对产品需求 | 三道 Gate、交互契约、Token、框架选型、组件状态、调整/变更集、产品核对、`ui-handoff.yaml` | 工具人工选择；三道体验 Gate 均人工确认；产品核对必须 `aligned` |
+| 4 | 体验设计 `$ai-delivery-design-experience` | 产品基线、终端矩阵、功能说明、初始架构 | 选原型工具；选视觉系统/UI 框架并通过 `UX-VS`；制作生产兼容的可运行 UI 原型并通过 `UX-UI`；逐条记录调整；最后统一核对产品需求 | 两道体验 Gate、交互契约、Token、框架选型、组件状态、调整/变更集、产品核对、`ui-handoff.yaml` | 工具人工选择；两道体验 Gate 均人工确认；产品核对必须 `aligned` |
 | 5 | 架构校准 `$ai-delivery-design-architecture` | 初始架构、ready UI handoff、产品核对、体验变更集 | 校验 UI 框架兼容性、组件/接口/数据和非功能设计，把可执行变更推进到 `ready-for-development` | 最终架构、正式接口契约、组件影响、原型架构接收凭据 | 下游契约验证 |
 | 6 | 平台准备 `$ai-delivery-prepare-platform` | 初始架构、技术栈和交付约束 | 准备构建、CI/CD、环境、配置、制品、观测和回滚能力 | 平台就绪报告、CI、环境台账、配置键清单 | 候选验证前汇合 |
 | 7 | 迭代规划 `$ai-delivery-plan-iteration` | 产品路线、最终架构、ready UI handoff、体验变更集 | 按业务价值、紧迫度、风险和学习价值排序；把可执行体验变更映射到垂直切片 | backlog、垂直切片、来源/原型/体验变更追踪、依赖、迭代计划 | 下游契约验证 |
@@ -393,8 +418,7 @@ flowchart LR
 | Discovery Gate A | 问题、目标用户、边界和成功信号是否可进入产品定义 | AI 先整理发现基线；批准后冻结版本。 |
 | Product Gate B | 产品手册、终端、功能、故事、验收标准、路线图是否完整 | AI 校验全部强制物料；批准后形成产品基线。 |
 | 重大架构决策 | 高影响、难逆转的技术决策是否采用 | AI 给出选项、证据、影响和决策记录。 |
-| 原型工具选择 | 每个原型集成员使用哪个实际可用工具 | AI 先列候选工具和适配理由，人在开始创作前选择。 |
-| `UX-LF` | 可运行低保真原型的布局、交互方式和细节是否通过 | AI 必须提供可实际操作、会产生状态变化的原型，并记录每轮评论和调整。 |
+| 原型工具选择 | 项目唯一 Prototype 使用哪个实际可用工具 | AI 先列候选工具和适配理由，人在开始创作前选择。 |
 | `UX-VS` | 视觉方向、字体、色彩、Token、组件状态和 UI 框架选择是否通过 | AI 根据产品性质与技术架构给出候选和证据，人在正式 UI 制作前确认。 |
 | `UX-UI` | 应用选定系统后的可运行正式 UI 是否通过 | AI 保持已确认交互，记录所有修订，直到最新轮次批准且评论全部终结。 |
 | 生产部署审批 | 是否允许把精确 package hash 部署到指定环境 | AI 必须先列出完整变更和回滚条件。 |
@@ -404,15 +428,24 @@ flowchart LR
 
 ## 9. 原型设计与上下游交接
 
-### 9.1 原型成员和工具
+### 9.1 唯一 Prototype 和工具
 
-一个产品可有多个终端或原型成员。每个成员在开始设计前独立维护：
+一个项目只有一个逻辑 Prototype、一份当前隔离源码和一个当前 Review Shell。多个终端在同一 Prototype 内按 `terminal_id` 分组；只有运行时兼容时才声明独立源码入口和构建命令，不创建成员副本。开始设计前维护：
 
 - `prototype-tool-candidates.csv`：Pencil、Figma、项目内 UI/UX skill 或其他可用工具；
 - `prototype-tool-selection.yaml`：人工选择、版本、能力和限制；
-- `prototype-manifest.yaml` / `prototype-set.yaml`：原型成员身份和版本。
+- `prototype.yaml`：唯一 Prototype 身份、当前源码和 Review Shell；
+- `prototype-revision.yaml`：某次迭代批准目标的不可变 revision；
+- `prototype-terminals.csv`、`prototype-pages.csv`、`prototype-review-scenes.csv`、`prototype-trigger-conditions.csv`、`prototype-routes.csv` 和 `ui-mapping.csv`：所有终端、页面、条件场景、路由和前端关联的唯一规范化登记；
+- `prototype-review-units.csv`：Page、Review Scene 和共享组件到 checksummed 原型源码的 Unit 本体；
+- `prototype-review-unit-pages.csv`：每行一个 Review Unit 到受影响 Page 的规范化关系，不在单字段编码多个 Page ID。
+- `frontend-change-scope.yaml`：随冻结 revision 固定代码根、非空的正式前端根与受管扩展名，以及 shared component / route registry 的精确 Page 影响集。每个 route registry 必须指向单个文件，并记录审批时预期 candidate 文件的 SHA-256；固定 refs 的 `verify-diff` 会直接读取 candidate Git 对象复核，防止同一注册表内新增未审批路由。
+
+正式前端始终执行“Prototype 修改 -> 用户 Page 审核 -> 冻结 revision/scope -> 正式代码修改”。每个 UI 文件首次写入前运行 `ai-delivery frontend-guard check-file`；合并和正式验证从固定 base/head 运行 `ai-delivery frontend-guard verify-diff`，由独立 Git diff 复核，不能用 Hook 成功代替。
+
+AI 必须根据当前项目、终端、交互复杂度、协作需求和可用工具推荐。旧 `prototype-set.yaml` / member manifest 仅允许作为历史只读输入，不得由新流程创建或修改。
 
-AI 必须根据当前项目、终端、交互复杂度、协作需求和可用工具推荐，不得假设所有原型都在同一个工具或文件中。
+旧 member/set 迁移不会直接产生可审核 revision。迁移生成的 `prototype.yaml` 使用 `migration-pending-ux-ui` 且 `current_revision_ref: null`；先整理完整 Prototype、冻结并校验新的 revision，再在 Workflow Manager 的 P12/P13 完成新 `UX-UI`。管理器不会根据迁移记录推断批准。
 
 ### 9.2 页面编号
 
@@ -442,24 +475,23 @@ P01-02-页面名称2
 - `prototype-file-terminals.csv` 管理文件与终端关系；
 - 不允许用“全部页面放在一个无限画布”替代管理。
 
-### 9.4 分阶段可运行原型与确认
+### 9.4 生产兼容原型与确认
 
 视觉或交互终端必须顺序执行：
 
-1. 制作可运行低保真原型，覆盖布局、交互、状态、错误与恢复；不能用静态截图或无行为热区代替；
-2. 人工操作并决定 `UX-LF`，未通过则调整并重新评审；
-3. 定义视觉方向、字体、色彩、间距、响应式、无障碍和组件状态，比较兼容的 UI 框架/Skill/MCP，由人确认 `UX-VS`；
-4. 使用选定系统制作可运行正式 UI，由人确认 `UX-UI`；
-5. 每次调整立即写入 `prototype-adjustment-log.csv`，并关联评论、稳定对象、前后修订、原因、体验变更、需求变更和上下游影响；
-6. 全部原型成为候选后，把累计调整一次性交给产品定义节点，双向核对需求是否被覆盖、原型是否引入未批准行为；
-7. 需求变化生成新产品基线和 Gate B 证据，并使受影响原型失效后重新评审；被拒绝的原型行为必须移除；
-8. 只有 `product-prototype-reconciliation.yaml` 为 `valid/aligned` 才能冻结体验基线。
+1. 定义视觉方向、字体、色彩、间距、响应式、无障碍和组件状态，比较兼容的 UI 框架/Skill/MCP；启动 Workflow Manager，在 P11 展示 Visual Reference，由人确认 `UX-VS`；
+2. 使用选定系统和架构运行时制作生产兼容的可运行 UI 原型，覆盖布局、交互、状态、错误与恢复；不能用静态截图或无行为热区代替；
+3. 人工在 P12/P13 按 Page 操作并决定 `UX-UI`，批准和退回都可添加评论；修改原型后生成新 revision，只有最新批准且完整 checksum 相同的 Page 可继承。受控 Manager 动作写入 Page receipt 和 `UX-UI` Gate decision；
+4. 每次调整立即写入 `prototype-adjustment-log.csv`，并关联评论、稳定对象、前后修订、原因、体验变更、需求变更和上下游影响；
+5. 全部原型成为候选后，把累计调整一次性交给产品定义节点，双向核对需求是否被覆盖、原型是否引入未批准行为；
+6. 需求变化生成新产品基线和 Gate B 证据，并使受影响原型失效后重新评审；被拒绝的原型行为必须移除；
+7. 只有 `product-prototype-reconciliation.yaml` 为 `valid/aligned` 才能冻结体验基线。
 
 只有确实没有视觉界面和用户操作的终端才可把视觉 Gate 标为 `not-applicable`，并必须给出产品终端证据，不能对交互页面使用 `contract-only` 绕过人工确认。
 
 ### 9.5 交接身份
 
-`ui-handoff.yaml` 是唯一的下游就绪入口。它绑定三道体验 Gate、产品核对、交互契约、设计 Token、UI 框架、组件状态、页面组件映射、体验/需求变更和原型集 checksum。架构校准、规划、测试设计、开发和候选验证必须携带同一组 identity/checksum；下游不得直接修改冻结体验物料，也不得通过视觉比对猜测新增或修改。
+`ui-handoff.yaml` 是唯一的下游就绪入口。它绑定两道体验 Gate、产品核对、交互契约、设计 Token、UI 框架、组件状态、页面组件映射、体验/需求变更和原型集 checksum。架构校准、规划、测试设计、开发和候选验证必须携带同一组 identity/checksum；下游不得直接修改冻结体验物料，也不得通过视觉比对猜测新增或修改。
 
 ## 10. 迭代规划、任务拆分和 TDD
 
@@ -505,6 +537,12 @@ P01-02-页面名称2
 
 开发中的 TDD 不替代独立测试。开发者负责证明实现满足公开契约，候选验证节点负责以独立上下文验证整个不可变候选。
 
+### 10.4 Candidate Assurance UI Acceptance
+
+UI Acceptance 是 `05-candidate-assurance` 内的强制验收，不新增正式节点。UI-bearing candidate 必须在 manifest 固定 Prototype revision、UI Mapping 和 Mock Scenario Pack；先运行 `ai-delivery ui-acceptance plan` 生成精确 Scene/viewport 矩阵，再由固定 Playwright/browser/image 环境执行，最后运行 `ui-acceptance verify`。
+
+默认 Web viewport 为 `390x844`、`768x1024`、`1440x900`，默认最大像素差比例为 `0.001`；只有与冻结 Prototype revision checksum 完全一致的 `UX-VS` 已批准 Visual Standard 可覆盖。每项结果必须保留精确 viewport 的 Prototype/Candidate PNG、透明 RGBA changed-pixel Diff mask 及 checksum；验证器会解码图片、独立比较像素并重算比例。协议请求/响应使用与冻结契约及 checksummed Microcks 管理导出一致的确定性 JSON，包含场景选择所需的 path/query/header 参数和命名请求体。验收同时阻塞确定性渲染、交互、WCAG 2.2 AA、键盘、焦点、触控目标、文本溢出、响应式和恢复失败。Product Backend Mock 可触发错误或未完成后端场景，但不能替代真实后端功能或端到端验收；使用时必须另附绑定当前 candidate、非 Mock 环境、不可变部署摘要、契约测试和端到端结果的真实后端证据。任何修复导致 candidate manifest checksum 改变，都返回 `04-implementation` 选择新 candidate，并创建新的 Candidate Assurance attempt。
+
 ## 11. Git、候选版本和回滚
 
 推荐分支模型：
@@ -572,13 +610,17 @@ node .workflow/tools/state/state.mjs inspect
 node .workflow/tools/state/state.mjs verify
 ```
 
-每次 mutation 必须使用 `inspect` 返回的对应 `revision` 作为 `--expected-revision`。物料通过 `artifact register/status` 管理，节点、迭代、候选和发布通过 `transition` 管理，Gate 通过 `gate request/decide` 管理。Gate 决定必须包含明确 `actor`、`rationale` 和已登记 evidence。已登记物料变化时创建新 ID 并使用 `--supersedes`，不能原地覆盖。
+每次 artifact mutation 必须使用 `inspect` 返回的 `artifact_registry.revision` 作为 `--expected-revision`；节点、迭代、候选、发布和 Gate mutation 使用 owning `development_state.revision` 或 `release_state.revision` 作为 `--expected-scope-revision`。`draft/review-draft` 是 registry 外的可变 working file；提交、拒绝、批准、冻结、失败等语义决定才通过 `artifact register` 创建不可变 revision，后续决定使用新 ID 和 `--supersedes`。`artifact status` 只兼容迁移升级前已登记的 draft。节点、迭代、候选和发布通过 `transition` 管理，Gate 通过 `gate request/decide` 管理。Gate 决定必须包含明确 `actor`、`rationale` 和已登记 evidence。
 
-`workflow-state.yaml` schema 2 包含独立的 `development_state` 与 `release_state`。研发由 `iteration-started` 建立，发布仅在用户明确请求后由 `release-started` 建立；两个状态域分别维护 scope ID、局部 revision、节点、Gate、节点尝试和选定物料，因此发布期间仍可继续下一累计版本研发。顶层 revision 只负责审计流串行化，任何一个状态域都不得重置另一个。
+`workflow-state.yaml` schema 2 包含独立的 `development_state` 与 `release_state`。研发由 `iteration-started` 建立，发布仅在用户明确请求后由 `release-started` 建立；两个状态域分别维护 scope ID、局部 revision、节点、Gate、节点尝试和选定物料，因此发布期间仍可继续下一累计版本研发。独立 scope 可在等待同一提交区后分别成功，同一 scope 的过期 writer 必须冲突停止。顶层 revision 只负责审计流串行化，任何一个状态域都不得重置另一个。
 
-状态 CLI 根据流程图元数据校验前置依赖，不采用简单的相邻编号规则。平台准备可与体验设计并行；产品和体验可因原型校正带原因重开；后续迭代可用已登记的成功冻结基线满足未受影响的前置条件。节点完成证据必须处于允许的成功状态，并完成当前节点尝试的强制 Gate。生产审批 Gate ID 固定为 `PRODUCTION-APPROVAL`，不能标记为 `not-required`。
+状态 CLI 根据流程图元数据校验前置依赖，不采用简单的相邻编号规则。`03-delivery-readiness` 内的平台准备可与计划和测试设计并行；Product Shaping 和 Solution Design 可因原型校正带原因重开；后续迭代可用已登记且 identity/checksum 精确匹配的成功冻结基线满足未受影响的前置条件。节点完成证据必须处于允许的成功状态，并完成当前节点尝试的强制 Gate。生产审批 Gate ID 固定为 `PRODUCTION-APPROVAL`，不能标记为 `not-required`。
 
-节点交接、生产审批、部署、版本归档和中断恢复后都必须运行 `verify`。完整命令、revision 冲突恢复和生产规则见[正式状态 CLI 使用指南](STATE-CLI-USER-GUIDE.zh-CN.md)。
+Delivery Readiness 通过 `scope freeze` 将 Slice、需求、验收、任务和物料冻结为带 revision/checksum 的 manifest，并启用 `scope_contract_version: 1`。冻结后，只有明确人工批准的 `scope amend` 可以通过 `--supersedes` 创建下一 revision；`scope warn` 只写入 `warn-only` 和 `reslice_performed: false`，预算超限不会自动重新切片、重排计划或改变验收。旧 scope 没有 `scope_contract_version` 时保持旧契约兼容，不自动迁移。
+
+`inspect.derived_node_states` 根据 task、最新 blocking finding、Gate、artifact、immutable candidate、当前 manifest 与 completion receipt 联合投影正式节点状态，而不是由单个子任务状态直接决定。可能状态为 `pending`、`active`、`waiting`、`blocked`、`ready-to-complete` 和 `completed`。新契约节点只有达到 `ready-to-complete` 才能完成；CLI 随后生成绑定 manifest、任务/物料事实、Gate、candidate、blocking defect、evidence 和 checksum 的不可变 completion receipt。完整 `scope freeze`、`scope amend`、`scope warn` 命令见正式状态指南。
+
+节点交接、生产审批、部署、版本归档和中断恢复后都必须运行 `verify`。最新可信 anchor 建立后，`ai-delivery compact <project> --dry-run` 零写入报告 legacy 全量快照覆盖范围、历史根摘要和预计净释放空间；apply 先写 checksummed gzip archive 和 manifest，从包内完整 replay 到锚定 registry checksum 后才移除 loose shards，之后 `verify --history` 返回 `compacted-history`。`artifact prune` 是另一项保留操作：默认以零写入 dry-run 列出可裁剪 artifact shard，只有显式 `--apply` 才删除前缀并写 retention receipt；其历史模式是 `retained-history`，不能声称重新审计已删除字节。完整命令、revision 冲突恢复和生产规则见[正式状态 CLI 使用指南](STATE-CLI-USER-GUIDE.zh-CN.md)。
 
 ### 13.3 任务登记
 
@@ -593,13 +635,23 @@ node .workflow/tools/state/state.mjs verify
 典型命令：
 
 ```bash
-node .agents/skills/ai-delivery-checkpoint-task/scripts/task-state.mjs init --task-id TASK-01 --iteration-id ITER-01 --node development --skill ai-delivery-develop-iteration --status queued --sequence 1 --goal "任务 1" --next-action "执行任务 1" --next-action-owner agent
+node .agents/skills/ai-delivery-checkpoint-task/scripts/task-state.mjs init --task-id TASK-01 --iteration-id ITER-01 --node 04-implementation --skill ai-delivery-develop-iteration --status queued --sequence 1 --goal "任务 1" --scope SLICE-01 --acceptance AC-01 --responsibility delivery-agent --next-action "执行任务 1" --next-action-owner agent
 node .agents/skills/ai-delivery-checkpoint-task/scripts/task-state.mjs recover --iteration-id ITER-01
-node .agents/skills/ai-delivery-checkpoint-task/scripts/task-state.mjs activate --task-id TASK-01
-node .agents/skills/ai-delivery-checkpoint-task/scripts/task-state.mjs checkpoint --task-id TASK-01 --status checkpointed --completed-step "公开契约已验证" --next-action "实现最小行为"
-node .agents/skills/ai-delivery-checkpoint-task/scripts/task-state.mjs finish --task-id TASK-01 --status completed --actual-output "artifact.yaml" --next-action "恢复迭代并选择下一任务"
+node .agents/skills/ai-delivery-checkpoint-task/scripts/task-state.mjs inspect --task-id TASK-01 --include-closed
+node .agents/skills/ai-delivery-checkpoint-task/scripts/task-state.mjs activate --task-id TASK-01 --phase implementation
+node .agents/skills/ai-delivery-checkpoint-task/scripts/task-state.mjs checkpoint --task-id TASK-01 --status pending-review --phase review --completed-step "公开契约已验证" --next-action "集中收集评审意见"
+node .agents/skills/ai-delivery-checkpoint-task/scripts/task-state.mjs finish --task-id TASK-01 --status failed --phase review --finding-json '{"finding_id":"FIND-01","severity":"blocking","status":"open","summary":"验收分支未覆盖"}' --change-set-json '{"change_set_id":"CHANGESET-01","approval_actor":"product-owner@example.invalid","rationale":"集中修复完整反馈集","finding_ids":["FIND-01"],"allowed_files":["src/acceptance.mjs"],"expected_evidence":["test-report@2"],"review_axes":["standards","spec"],"collection_decision":"fail"}' --time-category review --elapsed-minutes 12 --next-action "合并处理修复集"
+node .agents/skills/ai-delivery-checkpoint-task/scripts/task-state.mjs activate --task-id TASK-01 --new-attempt --phase repair --next-action "执行已批准修复集"
+node .agents/skills/ai-delivery-checkpoint-task/scripts/task-state.mjs finish --task-id TASK-01 --status completed --phase review --finding-json '{"finding_id":"FIND-01","severity":"blocking","status":"resolved","summary":"验收分支已覆盖","evidence":["test-report@2"],"changed_files":["src/acceptance.mjs"],"change_set_id":"CHANGESET-01"}' --actual-output "artifact.yaml" --next-action "恢复迭代并选择下一任务"
+node .agents/skills/ai-delivery-checkpoint-task/scripts/task-state.mjs init --task-id TASK-02 --iteration-id ITER-01 --node 04-implementation --skill ai-delivery-develop-iteration --status queued --goal "扩展后的任务" --scope SLICE-02 --acceptance AC-02 --derived-from TASK-01 --next-action "等待范围批准"
 ```
 
+iteration、node、skill、`goal`、scope、`responsibility`、依赖和 acceptance 未变化时始终复用同一个逻辑任务 ID；重复 `init` 是零写入幂等操作，相同契约换用新 ID 也会被拒绝。只有这些契约字段发生实质变化时才创建新任务，并用 `--derived-from` 或 `--supersedes` 关联。规划、实现、评审、分诊、修复、测试和验证轮次写入同一任务的结构化 attempt/phase，不再通过 F/R/T/P/vN 后缀派生任务树。
+
+评审采用两阶段协议：进入 review phase 时先把固定 diff 或候选保存为 `review_subject_baseline`，再完整收集全部反馈，收集期间不改代码，批准时若 Git 变化则拒绝；然后把全部 open findings 组成已批准 change set，用同一个 `change_set_id` 由实现者集中应用并附证据，最后集中复审。CLI 把固定对象固化为代码修复基线和规范反馈集并计算 checksum；复审中新发现的问题进入下一轮反馈收集和新的批准集，不能偷偷扩大当前修复范围。
+
+`init` 只创建 queued 任务，默认状态也是 queued；其它请求状态会被拒绝。queued 从 0 attempts 开始，只有第一次 activate 会检查依赖并创建 `A1`，queued 不能直接 checkpoint/finish。phase 状态由 task transition 推导，`--phase-status` 会被拒绝。失败 attempt 不满足依赖，原契约重试必须显式使用 `--new-attempt`，成功完成整个逻辑任务后下游才可激活。进入 review phase 时 CLI 固定 `review_subject_baseline`，批准前若 Git 状态变化则拒绝。`--finding-json` 保存 finding ID、严重度、状态、摘要、evidence 和 changed files；记录只追加，同一 finding ID 的最后一条记录构成 task 级最新结论。review phase 用 `--change-set-json` 提供批准人、理由、全部 open finding IDs、允许文件、预期证据、`review_axes` 和 `collection_decision`；CLI 把固定对象固化为 `repair_baseline`、持久化 `feedback_collection` 并计算 `collection_checksum`。resolved 必须引用该批准集内已有 open finding，只能在集中复审的 review phase 写入，并携带预期 evidence；`changed_files` 必须与批准后真实 Git 变化完全一致并位于批准范围内。任一最新 blocking finding 仍为 `open` 时，CLI 拒绝把任务设为 `completed`。`completed/failed/abandoned` 只能通过 `finish` 写入，不能通过 `checkpoint` 绕过关闭校验。`--time-category` 与 `--elapsed-minutes` 成对记录实现、测试、评审、工作流等待和返工耗时。`task-state.mjs inspect` 只读取本地/共享 task、依赖和 attempt 摘要，不恢复 runtime、不写 resume/checkpoint，也不改变 Git。
+
 ### 13.4 恢复顺序
 
 新会话：
@@ -614,9 +666,10 @@ node .agents/skills/ai-delivery-checkpoint-task/scripts/task-state.mjs finish --
 推荐规则：
 
 1. 优先已有 `preparing`、`running`、`checkpointed`、`pending-review`、`blocked` 或 `interrupted` 任务；
-2. 否则选择依赖均为 `completed` 的 `queued` 任务；
-3. 按 `sequence`，再按 `task_id` 排序；
-4. 无可执行任务时返回 `null` 并列出等待依赖。
+2. 否则选择最低 `sequence` 的 `failed` 可重试任务，并显式执行 `activate --new-attempt --phase repair`；
+3. 再否则选择依赖均为 `completed` 的 `queued` 任务；
+4. 每个优先组内按 `sequence`，再按 `task_id` 排序；
+5. 无可执行任务时返回 `null` 并列出等待依赖。
 
 `next_action_owner` 固定为 `agent | user | external`，旧任务默认为 `agent`。它是防止重启时误写状态的执行边界，不是提示性备注。任务 evidence 采用有序集合语义，重复提交同一引用不会追加重复项。
 
@@ -628,16 +681,19 @@ node .agents/skills/ai-delivery-checkpoint-task/scripts/task-state.mjs finish --
 node .agents/skills/ai-delivery-checkpoint-task/scripts/task-state.mjs archive-version --iteration-id ITER-01 --version-status released --release-id REL-01 --evidence "production-verification@1"
 ```
 
-权威归档始终写入 `.workflow/control/archives/versions/<version-id>/`。默认还在被忽略的 runtime 中保留可丢弃详细副本；无需该副本时增加 `--portable-only`。
+权威归档始终写入 `.workflow/control/archives/versions/<version-id>/`。写入前，`archive-version` 必须调用正式状态 CLI 的 `snapshot references`，在最新可信 version-boundary anchor 中验证并投影目标 scope manifest、candidate、Gate decision 和 history anchor；任一项缺失时不得创建归档或删除活动任务。`version-manifest.json.references` 以相对路径和 checksum 引用归档内 task summary、attempt receipt（checksum 覆盖 ref 指向的完整 attempt 值）和上述正式记录，不重复内嵌正文。默认还在被忽略的 runtime 中保留可丢弃详细副本；无需该副本时增加 `--portable-only`。
+
+如果历史归档后来被证明不满足完整 scope，不得修改 `version-manifest.json` 或归档任务。使用顶层 `repair --invalidate-archive` 追加 correction/invalidation 事务；后续资格判断读取该前向事务，审计仍可验证原归档的 tree checksum。
 
 归档条件：
 
-- 版本为 `released` 或明确 `abandoned`；
+- 版本为 `release-ready`、`released` 或明确 `abandoned`；
+- `release-ready` 版本有 immutable candidate ID 和验证证据；
 - `released` 版本有 release ID 和生产验证证据；
 - 该版本所有任务均已关闭；
 - 不存在 queued、running、blocked 或 interrupted 等未关闭任务。
 
-默认恢复不加载已关闭任务详情；归档后恢复命令不扫描归档目录，从而减少上下文占用。审计归档时直接读取 `.workflow/control/archives/versions/<version-id>/`。
+历史统计仍把 completed、failed 和 abandoned 计为 closed；默认恢复不加载 completed/abandoned 详情，但会通过 `retryable_task_ids` 返回 failed 任务，避免在创建新 attempt 前中断后丢失恢复入口。归档后恢复命令不扫描归档目录，从而减少上下文占用。审计归档时直接读取 `.workflow/control/archives/versions/<version-id>/`。
 
 ## 14. 规范沉淀
 
@@ -685,7 +741,7 @@ node .workflow/tools/evolution/evolve.mjs verify
 | `$ai-delivery-bootstrap` | 新会话、陌生仓库、首次引导、中断或状态不明。 |
 | `$ai-delivery-define-product` | 新产品、重要需求、产品范围或术语变化。 |
 | `$ai-delivery-design-architecture` | 产品基线批准后、体验完成后校准，或架构约束变化。 |
-| `$ai-delivery-design-experience` | 初始架构后，依次完成可运行低保真、视觉系统、正式 UI、调整记录和产品统一核对。 |
+| `$ai-delivery-design-experience` | 初始架构后，先从受管 `ref/ui` 选择设计参考并生成可操作 HTML Visual Reference，再用 `ai-delivery visual-standard validate` 验证完整输入后完成 `UX-VS`，随后完成生产兼容原型、`UX-UI`、调整记录和产品统一核对；兼容 React Web 且用户未指定时默认 shadcn 与 Lucide。 |
 | `$ai-delivery-prepare-platform` | 初始架构后并行准备构建、环境、配置和发布平台。 |
 | `$ai-delivery-plan-iteration` | 架构校准后规划或调整迭代优先级与顺序。 |
 | `$ai-delivery-design-tests` | 开发前设计测试策略、原型可测性和公开测试契约。 |
@@ -798,7 +854,7 @@ R00 发布请求
 
 例如生产在 `VER-02`、目标为 `VER-05`，本次新增范围是 `VER-03..VER-05`。目标等于生产版本时允许重新发布，但必须使用新 release ID 并完整重做环境快照、验证和审批。目标早于生产版本时拒绝发布，恢复旧版本必须部署旧镜像 digest。
 
-版本收尾和发布归档都必须通过正式状态 CLI 固化事实。`version-closed` 在 `12-version-closeout` 完成并登记 `release-ready` 物料后更新 `latest_line_version_id`；它不会触发发布。`release-archived` 在 R10 完成并登记 `released` 物料后更新 `production_version_id` 和 `production_release_id`。R09 只能提供已验证身份，不能直接写入生产事实。以上三个字段以 `.workflow/delivery/workflow-state.yaml` 为权威来源，`project.yaml` 仅保留项目描述和旧项目兼容字段。
+版本收尾和发布归档都必须通过正式状态 CLI 固化事实。`version-closed` 在 `06-version-closeout` 完成并登记 `release-ready` 物料后更新 `latest_line_version_id`；它不会触发发布。`release-archived` 在 R10 完成并登记 `released` 物料后更新 `production_version_id` 和 `production_release_id`。R09 只能提供已验证身份，不能直接写入生产事实。以上三个字段以 `.workflow/delivery/workflow-state.yaml` 为权威来源，`project.yaml` 仅保留项目描述和旧项目兼容字段。
 
 版本任务归档写入 `.workflow/control/archives/versions/<version-id>/`，保存版本 Manifest、任务快照和共享 checkpoint。只有可携带归档完整写入后，脚本才移除 `.workflow/control/tasks/` 与 `.workflow/control/checkpoints/` 中该版本的活动分片。普通恢复以及 `--include-closed` 都只扫描活动集合；历史详情必须通过显式审计读取归档。`.workflow/delivery/runtime/archive/` 仅是可丢弃的本地详细副本。
 
@@ -888,12 +944,14 @@ npm test
 npm run audit:verify
 ```
 
-检查 npm 发布内容：
+检查 npm 发布内容和发布阶段规范化：
 
 ```bash
-npm pack --dry-run
+npm --cache .tmp/npm-cache publish --dry-run --access public --registry=https://registry.npmjs.org/
 ```
 
+正式版本选择、Git Tag、2FA、失败版本处理和发布后安装冒烟必须遵循 [npm 版本与发布管理规范](NPM-RELEASE-MANAGEMENT.zh-CN.md)。`npm pack --dry-run` 可用于快速查看文件，但不能替代 `npm publish --dry-run`。
+
 skill 自身还应使用 skill 校验器检查 frontmatter、命名和引用；YAML 产物应使用结构化解析器逐个解析，不应用字符串匹配替代语法校验。
 
 ## 20. 故障排查
@@ -905,6 +963,7 @@ skill 自身还应使用 skill 校验器检查 frontmatter、命名和引用；Y
 | 规范正文冲突 | 不要强制覆盖；调用规范治理流程创建新版本或解决冲突。 |
 | `workflow-inconsistent` | 查看 `inspect` 的 errors、missing files 和依赖问题，修复后再编排。 |
 | 中断后不知道从哪继续 | 先运行只读 Bootstrap inspect。仅当 `next_action_owner: agent` 时运行 `recover --iteration-id <id>` 并读取 `recommended_task_id`；`user/external` 不得 recover。 |
+| failed 后重启未推荐下一任务 | 检查 `retryable_task_ids`；对推荐的原逻辑任务执行 `activate --new-attempt --phase repair`，不得跳到依赖它的 queued 任务。 |
 | 后续任务无法 activate | 其 `depends_on` 任务缺失或未处于 `completed`；修复正式计划和运行时状态。 |
 | Hook 有事件但节点没完成 | 正常现象；Hook 只是审计和心跳，必须由任务快照和正式产物证明完成。 |
 | 发布审批后制品或配置变化 | 原审批失效，重新执行发布准备和生产审批。 |
@@ -913,9 +972,9 @@ skill 自身还应使用 skill 校验器检查 frontmatter、命名和引用；Y
 | `.workflow/delivery/runtime/` 丢失 | 本机恢复信息无法完整重建；跨机器工作前应把该目录保存到受控、加密、受限的状态存储。 |
 | 检测到根目录 `delivery/` 或 `standards/` | 按 5.5 节迁移到 `.workflow/`，更新引用和 checksum；不要用 `--force` 绕过。 |
 | `.workflow/` 被整体忽略 | 删除该忽略规则，只保留 `.workflow/delivery/runtime/`；正式研发文档必须进入版本控制。 |
-| 查看器端口被占用 | 使用 `.\.workflow\tools\viewer\start.cmd --port 4180` 选择其他端口。 |
-| 查看器没有自动打开浏览器 | 读取终端输出中的 URL 手工打开；远程或 CI 环境使用 `--no-open`。 |
-| 查看器没有显示最新物料 | 点击“刷新”；确认文件位于项目 `.workflow/` 且未超过 10,000 项扫描上限。 |
+| Manager 端口被占用 | 省略 `--port` 自动选择，或使用 `manager serve . --port <port>`。 |
+| Manager 没有自动打开浏览器 | 读取终端输出中的 loopback URL 手工打开；CI 环境使用 `--no-open`。 |
+| Manager 没有显示最新事实 | 点击“刷新状态”；确认事实已通过正式接口登记，未登记内容不会生成示例数据。 |
 
 ## 21. 维护规则
 
@@ -924,7 +983,7 @@ skill 自身还应使用 skill 校验器检查 frontmatter、命名和引用；Y
 - 修改主流程或 Gate 时，同步更新第 7、8 节和 `workflow-model.md`；
 - 修改原型契约时，同步更新第 9 节和原型交接测试；
 - 修改 checkpoint 命令或状态时，同步更新第 13 节及恢复示例；
-- 修改 npm 发布文件时，运行 `npm pack --dry-run`；
+- 修改 npm 发布文件时，遵循 `NPM-RELEASE-MANAGEMENT.zh-CN.md` 并运行 `npm publish --dry-run`；
 - 新文档默认中文；
 - 已批准、冻结、发布和 `audit/` 中已归档版本不原地重写。