ai-delivery-workflow 0.4.0 → 0.5.1

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

@@ -1,10 +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。
+当前研发生产模型是 `development-seven-node`：`00-bootstrap -> 01-product-shaping -> 02-solution-design -> 03-delivery-readiness -> 04-implementation -> 05-candidate-assurance -> 06-version-closeout`。新项目和现行生产 Skill 只生成这些节点 ID。
 
 > 仓库身份：当前源码仓库是工作流维护与发行项目，不是下文所述的业务工作区。不要对当前源码仓库套用双仓初始化、业务项目 bootstrap 或 `.workflow/` 状态恢复；下文双仓契约描述的是安装目标。
 >
-> 当前工作区契约：本手册现行运行形态只支持“工作流控制仓库 + 一个直接子目录代码仓库”，也不使用 Git submodule。`migrate` 只转换旧工作流物料布局，不负责把单仓代码历史拆成双仓；双仓建立或绑定规则见 [DUAL-REPOSITORY-WORKSPACE.zh-CN.md](DUAL-REPOSITORY-WORKSPACE.zh-CN.md)。
+> 当前工作区契约：本手册现行运行形态只支持“工作流控制仓库 + 一个直接子目录代码仓库”，也不使用 Git submodule。双仓建立或绑定规则见 [DUAL-REPOSITORY-WORKSPACE.zh-CN.md](DUAL-REPOSITORY-WORKSPACE.zh-CN.md)。
 
 ```text
 workspace/.git                 工作流 Git
@@ -18,7 +18,7 @@ workspace/code/.git            代码 Git
 初始化器还会合并根 `.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.4.0`
+> 适用包版本：`ai-delivery-workflow@0.5.1`
 > 默认文档语言：简体中文  
 > 文件级索引：[FILE-REFERENCE.zh-CN.md](FILE-REFERENCE.zh-CN.md)  
 > CodeGraph 可选集成：[CODEGRAPH-INTEGRATION.zh-CN.md](CODEGRAPH-INTEGRATION.zh-CN.md)
@@ -96,7 +96,7 @@ AI Delivery Workflow 是一套安装在单个代码仓库内的 AI 研发流程
 
 维护仓库的通用、长期验证源码统一位于根 `verification/` 并纳入 Git。业务项目的应用自动化测试位于代码仓库 `<code_repository.path>`，沿用该仓库已有框架、命名和原生测试目录，不得写入 `.workflow/`。
 
-`audit/` 候选包、部署副本和历史审计快照中内嵌的测试文件属于审计物料，可保留原路径；验证这些物料的维护入口位于根 `verification/`。本维护仓库的一切临时仓库、日志、缓存、报告、认证辅助文件和单次场景脚本统一放入被忽略的 `.tmp/`。
+`prototypes/` 保存已确认、可重复启动的设计原型及其伴随夹具；它们纳入维护仓库版本控制，但不等于正式产品前端，也不随安装器部署。`audit/` 候选包、部署副本和历史审计快照中内嵌的测试文件属于审计物料，可保留原路径；验证这些物料的维护入口位于根 `verification/`。本维护仓库的一切临时仓库、日志、缓存、报告、认证辅助文件和单次场景脚本统一放入被忽略的 `.tmp/`。
 
 ## 4. 工作流组成
 
@@ -108,6 +108,7 @@ AI Delivery Workflow 是一套安装在单个代码仓库内的 AI 研发流程
 | 安装与引导库 | `lib/` | 合并项目配置、识别项目状态、生成存量代码上下文。 |
 | 项目 skills | `skills/ai-delivery-*` | 定义各研发节点的输入、过程、输出、Gate 和失败路由。 |
 | 审计与验证 | `audit/`、`verification/` | 保留历史 V1 执行证据，以 ITER-V2 验证当前契约，并用通用测试验证安装、引导和原型交接；两者均不随 `init` 安装。 |
+| 可版本化设计原型 | `prototypes/` | 保存 Workflow Manager 原型及其业务页面夹具；纳入 Git，不进入 npm 包或安装目标。 |
 | 临时运行物料 | `.tmp/` | 保存测试工作区、缓存、日志、报告、临时 Git 仓库、打包文件和单次场景脚本，整体忽略且可随时删除。 |
 
 安装到业务项目后，主要目录如下：
@@ -129,7 +130,7 @@ AI Delivery Workflow 是一套安装在单个代码仓库内的 AI 研发流程
       manager/                     # 正式工作流管理器 runtime 与静态界面
     mock-system/                   # 隔离的 external/product-backend catalog 与合同定义
     delivery/
-      project.yaml                # 项目描述与旧字段兼容回退
+      project.yaml                # 项目描述与当前配置
       workflow-state.yaml         # 正式流程、Gate、累计研发和生产身份
       artifact-registry.yaml      # 正式物料注册表
       state-events.jsonl          # 正式状态审计事件
@@ -151,7 +152,7 @@ AI Delivery Workflow 是一套安装在单个代码仓库内的 AI 研发流程
   .gitattributes                  # 固定工作流受控文本为 LF
 ```
 
-安装器为上述可能为空但必须跨 clone 保留的内容目录，以及 `.workflow/control/` 下的任务、Checkpoint、物料、Gate、版本、发布、事件、迁移和修复分片目录创建 `.gitkeep`。这些占位文件属于结构契约；重新克隆后无需再次执行 `init` 即可通过 `doctor`。`upgrade` 会把旧安装缺失的 `migrations/` 和 `repairs/` 作为 `ensure-directory` 新增项恢复；目录已存在但缺少 `.gitkeep` 时，只以独立 `ensure-directory-marker` 新增项恢复 marker。已存在目录及其中用户物料不属于安装器所有，也不会被替换。
+安装器为上述可能为空但必须跨 clone 保留的内容目录，以及 `.workflow/control/` 下的任务、Checkpoint、物料、Gate、版本、发布、事件和修复分片目录创建 `.gitkeep`。这些占位文件属于结构契约；重新克隆后无需再次执行 `init` 即可通过 `doctor`。已存在目录及其中用户物料不属于安装器所有，也不会被替换。
 
 ## 5. 安装、升级与诊断
 
@@ -182,7 +183,7 @@ npx ai-delivery-workflow@latest doctor .
 npx ai-delivery-workflow@latest manager inspect .
 ```
 
-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 操作移除。
+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 使用正式项目事实，未登记能力明确显示“尚未登记”。
 
 ### 5.3 从本地源码安装到另一个项目
 
@@ -215,7 +216,7 @@ npx ai-delivery-workflow@latest init . --dry-run
 npx ai-delivery-workflow@latest upgrade . --dry-run
 ```
 
-审阅结构化报告中的 additions、replacements、preserved、preserved_summary、conflicts、backups 和 compatibility 后执行：
+审阅结构化报告中的 additions、replacements、preserved、preserved_summary、conflicts 和 backups 后执行：
 
 ```bash
 npx ai-delivery-workflow@latest upgrade .
@@ -227,7 +228,7 @@ npx ai-delivery-workflow@latest upgrade .
 
 安装器不会把降级当作升级。目标包版本早于已安装版本时默认拒绝；只有用户明确批准降级并审阅备份影响后，才可使用 `--force`。
 
-旧项目兼容迁移属于独立 `migrate` 流程。`upgrade` 只安装迁移能力并在 `prototype_migration.required_follow_up` 报告后续命令，不写 Prototype 迁移目标；真正迁移只在审阅 `migrate --dry-run` 后执行。结构迁移不推断业务完成度，不激活或关闭任务，不改变 scope，也不重写旧事件。错误归档由独立 `repair` 前向事务失效，原归档字节不变。旧 `.workflow/tools/viewer/` 不再是可选安装能力；升级会将其备份并移除，受保护回滚可恢复升级前字节。
+升级只处理当前 `.workflow` 安装契约。发现旧布局、旧 schema 或受管文件漂移时，`upgrade --dry-run` 报告冲突并保持只读；明确的归档完整性问题使用 `repair --invalidate-archive` 前向修复，原证据字节保持不变。
 
 ### 5.5 升级
 
@@ -239,19 +240,11 @@ npx ai-delivery-workflow@latest upgrade .
 4. 处理规范冲突。
 5. 执行新版 `upgrade`；仅在受管副本漂移且明确采用发行基线时使用 `--force`。
 6. 执行 `doctor`。
-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。
+7. 新建 Codex 任务，对 AI 说“继续”；AI 自主调用 Bootstrap 和后续 Skill。
 
 升级完成但尚未产生新的 schema 2 正式事务时，可以执行 `upgrade . --rollback <upgrade-id>` 恢复升级前受管副本和安装清单。新增正式事务或升级后再次修改受管副本会关闭回滚窗口，此时必须前向修复。
 
-#### 兼容结构迁移与业务修复
-
-`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>/` 保持逐字节不变。
 
@@ -265,12 +258,7 @@ npx ai-delivery-workflow@latest upgrade .
 | `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` | 否 | 预览引导动作。 |
@@ -304,7 +292,7 @@ Mock System 使用固定版本与 digest 的 Microcks Uber 镜像，External Dep
 
 Workflow Manager 是唯一项目内控制面。P01-P19 汇总七节点状态、需求、任务、测试、交付成果、人工决策、业务项目原型、项目系统、Mock、事件和设置；P13 是从原型审批或路由页面进入的上下文详情页。UI、HTTP 和 `manager list/show/export/action` CLI 使用同一应用服务。
 
-界面不是任意文件编辑器或命令执行器。原型评论/截图/审核、系统初始化脚本/生命周期、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)。
+界面不是任意文件编辑器或命令执行器。原型评论/截图/审核、系统初始化脚本/生命周期、Mock 同步、Gate 决定、需求关系和设置修改只能调用发行白名单动作，按能力验证 actor、expected revision/checksum、幂等键和 plan checksum，并生成 Receipt/Event。AI 操作遵循 [Workflow Manager Agent Interface](agents/workflow-manager-agent-interface.md)。
 
 ### 5.8 项目原型审核
 
@@ -443,9 +431,8 @@ flowchart LR
 
 正式前端始终执行“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 必须根据当前项目、终端、交互复杂度、协作需求和可用工具推荐。新流程统一使用 `prototype-revision-catalog.v2`，由 Workflow Manager 读取和审核。
 
-旧 member/set 迁移不会直接产生可审核 revision。迁移生成的 `prototype.yaml` 使用 `migration-pending-ux-ui` 且 `current_revision_ref: null`；先整理完整 Prototype、冻结并校验新的 revision，再在 Workflow Manager 的 P12/P13 完成新 `UX-UI`。管理器不会根据迁移记录推断批准。
 
 ### 9.2 页面编号
 
@@ -465,15 +452,14 @@ P01-02-页面名称2
 - 页面显示名称可以调整，但稳定 ID 不复用；
 - 功能、终端、页面、状态、画布、文件和具体元素使用显式关系表追踪。
 
-### 9.3 画布和文件
+### 9.3 页面、路由和映射
 
-- 同一主页面及其派生子页面可以放在同一画布族；
-- 无关主页面应拆为独立画布或原型文件；
-- `canvas-catalog.csv` 管理画布；
-- `canvas-pages.csv` 管理画布与页面关系；
-- `prototype-files.csv` 管理原型源文件；
-- `prototype-file-terminals.csv` 管理文件与终端关系；
-- 不允许用“全部页面放在一个无限画布”替代管理。
+- `prototype-pages.csv` 管理稳定 Page 身份；
+- `prototype-review-scenes.csv` 管理可审核状态；
+- `prototype-trigger-conditions.csv` 管理场景触发条件；
+- `prototype-routes.csv` 管理原型与生产路由；
+- `ui-mapping.csv` 绑定页面、路由、前端源码和验收 ID；
+- 不允许用未登记的画布、文件或路由替代规范化关系。
 
 ### 9.4 生产兼容原型与确认
 
@@ -549,10 +535,13 @@ UI Acceptance 是 `05-candidate-assurance` 内的强制验收，不新增正式
 
 | Git 对象 | 作用 |
 | --- | --- |
-| `main` | 受保护、可发布的集成基线。 |
-| 迭代分支 | 汇总一个迭代版本的已审查工作包。 |
+| `main` | 受保护的生产成功历史，只在生产验证通过后精确快进到已部署候选。 |
+| `line/<product-id>` | 产品的累计研发线，可领先于 `main`；首个计划版本开始时从当时的 `main` 创建，之后版本都从它开始。 |
+| `version/<version-id>-<slug>` | 汇总一个计划版本的已审查工作包。 |
 | 工作包分支 / worktree | 隔离单个技术任务，缩小 AI 上下文和冲突范围。 |
 | hotfix 分支 | 修复已存在的生产行为问题。 |
+| `release/<release-id>-<slug>` | 从 R00 固定的 `main` 快照创建；增量发布精确合入一个目标 `version-ready` Tag，同版本重发复用该快照而不新增合并。 |
+| `release-fix/<release-id>/<defect-id>` | 从活动发布候选创建的隔离纠正分支，成功发布后受控回写到产品研发线。 |
 | 不可变 release Tag | 绑定已冻结发布版本。 |
 
 原则：
@@ -561,13 +550,15 @@ UI Acceptance 是 `05-candidate-assurance` 内的强制验收，不新增正式
 - 同一任务的多个 worktree 指向同一个主 `state_root`；
 - 候选失败、发布记录、Tag 和部署记录都保留，不覆盖历史；
 - 生产转换串行化，同一时间只推进一个生产发布；
+- `product-id` 是在首次 bootstrap 的项目身份基线中冻结的稳定产品线标识，不是 release、版本或仓库显示名称。只在该产品首次进入计划版本时从当前 `main` 创建一次 `line/<product-id>`；后续版本不得重新从 `main` 拉线。新建 line 仅允许显式产品拆分或新的稳定产品身份；
+- R00 记录的 `main` commit 是发布候选的不可变基线。它移动或某个候选遗漏已成功发布的 release-fix 时，候选为 `stale`，必须重建；
 - Git 分支不承担生产回滚。
 
 生产回滚使用上一个稳定镜像 digest 或发布清单中声明的等价不可变制品。回滚是一次新的部署状态转换，必须有执行和验证记录。没有历史稳定镜像时，发布准备必须明确替代策略，如停止服务并移除首版部署，不能虚构镜像回滚能力。
 
 ## 12. 发布、上线交付清单和生产部署
 
-每次生产部署只对应一个迭代版本。发布准备必须列出本次所有实际变更，包括但不限于：
+每次生产部署对应一个不可变 release candidate 和一个目标版本；该目标可以代表连续累计版本闭包。发布准备必须列出本次所有实际变更，包括但不限于：
 
 - 产品需求、功能、故事和验收标准；
 - 终端、页面、原型和交互状态；
@@ -594,6 +585,20 @@ UI Acceptance 是 `05-candidate-assurance` 内的强制验收，不新增正式
 
 生产部署始终是独立节点。候选测试通过不等于已部署，部署完成也不等于已发布；只有生产验证输出 `released`，迭代才可关闭和归档。
 
+独立发布的 Git 顺序固定为：
+
+```text
+R00 记录请求时 main 的精确 commit
+-> R01/R02 校验该快照未漂移、连续版本闭包和目标 version-ready Tag
+-> R04 从该 main 快照创建 release 分支，增量发布以 --no-ff 精确合入一个目标 Tag，同版本重发不新增合并
+-> R05-R07 对该合并提交验证、冻结 release Tag 和审批
+-> R08 部署该精确候选
+-> R09 验证成功后将 main 精确快进到已部署候选
+-> R10 将已成功发布的 release-fix 受控同步到 line，并归档
+```
+
+中间版本 Tag 只提供闭包和物料追溯，不重复合入 release 分支。`main` 在候选准备、验证、审批或部署前发生变化时，不得更新旧候选的基线，保留证据并以新的 R00 请求重建。`release-fix/*` 只能从活动候选创建；成功生产验证后必须在 R10 前通过受控操作合入 `line/<product-id>`，写入 `applied` 或幂等 `idempotent` receipt，并把未包含该修复的 release-ready 候选标为 `stale`。版本 Tag、版本 Manifest 和 release Tag 均不可重写。
+
 ## 13. Checkpoint、Hook 和中断恢复
 
 ### 13.1 两类受控状态
@@ -610,17 +615,17 @@ node .workflow/tools/state/state.mjs inspect
 node .workflow/tools/state/state.mjs verify
 ```
 
-每次 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。
+每次 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`。节点、迭代、候选和发布通过 `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、节点尝试和选定物料，因此发布期间仍可继续下一累计版本研发。独立 scope 可在等待同一提交区后分别成功，同一 scope 的过期 writer 必须冲突停止。顶层 revision 只负责审计流串行化，任何一个状态域都不得重置另一个。
 
 状态 CLI 根据流程图元数据校验前置依赖，不采用简单的相邻编号规则。`03-delivery-readiness` 内的平台准备可与计划和测试设计并行；Product Shaping 和 Solution Design 可因原型校正带原因重开；后续迭代可用已登记且 identity/checksum 精确匹配的成功冻结基线满足未受影响的前置条件。节点完成证据必须处于允许的成功状态，并完成当前节点尝试的强制 Gate。生产审批 Gate ID 固定为 `PRODUCTION-APPROVAL`，不能标记为 `not-required`。
 
-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` 时保持旧契约兼容，不自动迁移。
+Delivery Readiness 通过 `scope freeze` 将 Slice、需求、验收、任务和物料冻结为带 revision/checksum 的 manifest，并启用 `scope_contract_version: 1`。冻结后，只有明确人工批准的 `scope amend` 可以通过 `--supersedes` 创建下一 revision；`scope warn` 只写入 `warn-only` 和 `reslice_performed: false`，预算超限不会自动重新切片、重排计划或改变验收。
 
 `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)。
+节点交接、生产审批、部署、版本归档和中断恢复后都必须运行 `verify`。`artifact prune` 默认以零写入 dry-run 列出可裁剪 artifact shard，只有显式 `--apply` 才删除前缀并写 retention receipt；其历史模式是 `retained-history`，不能声称重新审计已删除字节。完整命令、revision 冲突恢复和生产规则见[正式状态 CLI 使用指南](STATE-CLI-USER-GUIDE.zh-CN.md)。
 
 ### 13.3 任务登记
 
@@ -854,7 +859,9 @@ R00 发布请求
 
 例如生产在 `VER-02`、目标为 `VER-05`，本次新增范围是 `VER-03..VER-05`。目标等于生产版本时允许重新发布，但必须使用新 release ID 并完整重做环境快照、验证和审批。目标早于生产版本时拒绝发布，恢复旧版本必须部署旧镜像 digest。
 
-版本收尾和发布归档都必须通过正式状态 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` 仅保留项目描述和旧项目兼容字段。
+R00 同时固定当时 `main` 的 commit。R04 通过 `release-git.mjs create-candidate` 携带 `--expected-main`、精确 `--source-tag/--source-commit`、`--receipt` 和 `--apply` 从该 commit 创建 `release/<release-id>-<slug>`。增量发布只以 `--no-ff` 合入目标 `version-ready/<version-id>/rN` Tag，得到唯一候选合并提交；同版本重发要求该 Tag 已在快照历史中，候选就是快照且不新增合并。R09 成功时先生成机器可读 `production-verification.json`（固定 `operation: production-verification-decision`、release ID、R00 基线、已验证和已部署候选），再通过 `release-git.mjs promote` 携带 `--production-verification` 把 `main` 从该原始快照快进到同一个已部署提交。若 `main` 已变化、候选提交不一致，或目标 Tag 不满足相应的增量/同版本 ancestry，停止并新建发布请求，不能拿当前分支头继续。发布修复在成功验证后、R10 归档前准备 schema 2 产品线级 `candidate-inventory.json`：根部固定 `scope: product-line`、`product_id`、`line_branch` 和 active candidate，每个候选固定自己的 `release_id`、ID、commit/status，根部不得定义 release ID。用 `release-git.mjs sync-release-fix` 携带 `--production-verification`、前代 `--candidate-inventory`、不同路径的 `--successor-candidate-inventory` 和 `--expected-line` 同步进 `line/<product-id>`；输入库存不改写，脚本把跨产品线派生的 stale 更新写入 successor，并在回执中绑定两份库存。stale 候选由脚本派生并写入带 release ID 的 `candidate_status_updates`，不接受调用方传入 stale 列表。已经存在于 line 时仍写入显式 `idempotent` receipt，且只能复用字节完全一致的 successor；任何遗漏修复的可选候选不能继续发布。
+
+版本收尾和发布归档都必须通过正式状态 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/` 仅是可丢弃的本地详细副本。
 
@@ -906,7 +913,7 @@ R00 发布请求
 
 ## 19. 本仓库开发与验证
 
-本工作流维护仓库的通用自动化测试、专项验证器和长期测试辅助程序必须位于根 `verification/` 并纳入 Git；`audit/` 保存可审阅流程物料和历史快照，不保存维护测试入口；一切可丢弃运行物写入整体忽略的 `.tmp/`。这些维护仓库目录不写入安装目标模板，也不替业务代码仓库决定测试目录或版本控制策略。
+本工作流维护仓库的通用自动化测试、专项验证器和长期测试辅助程序必须位于根 `verification/` 并纳入 Git；`audit/` 保存可审阅流程物料和历史快照，不保存维护测试入口；`prototypes/` 保存可版本化设计原型；一切可丢弃运行物写入整体忽略的 `.tmp/`。这些维护仓库目录不写入安装目标模板，也不替业务代码仓库决定测试目录或版本控制策略。
 
 安装依赖：
 

package/docs/STATE-CLI-MAINTENANCE.zh-CN.md

@@ -1,8 +1,8 @@
 # 正式状态 CLI 维护指南
 
-当前生产图是 `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`、`rebuild` 和显式迁移继续消费历史记录；所有新任务、物料登记、transition、candidate、版本收尾和 Gate mutation 在写入及 Hook dispatch 前拒绝。`R00-release-request` 至 `R10-release-archive` 继续允许写入。
+当前生产图是 `development-seven-node`：`00-bootstrap -> 01-product-shaping -> 02-solution-design -> 03-delivery-readiness -> 04-implementation -> 05-candidate-assurance -> 06-version-closeout`。`R00-release-request` 至 `R10-release-archive` 继续允许写入。
 
-正式状态写入会先完整暂存权威事件分片、全局兼容视图和 JSONL 事件索引，持久化 prepared journal，再提交各目标并写入 committed marker；同步异常时恢复原文件，进程中断后由下一次受锁 mutation 或 `rebuild` 幂等恢复。`inspect`、`verify`、Bootstrap 诊断与 Workflow Manager 正式状态读取期间获取与 mutation 共用的 formal-state lock；活动 writer、其他 reader 或未恢复 journal 均使读取 fail-closed，避免检查通过后又读到混合 revision。只读调用方不得接管死锁或执行事务恢复。日常 `verify` 不遍历历史分片，只校验当前视图、JSONL 索引、物料和状态不变量；显式 `verify --history` 还检查全部事件分片的连续性、元数据、记录 checksum、schema 2 checksum 链以及最新 replay 结果与全局视图的一致性。`rebuild` 按 revision replay 每个 stream，并按确定顺序重建 JSONL 索引。
+正式状态写入会先完整暂存权威事件分片、当前视图和 JSONL 事件索引，持久化 prepared journal，再提交各目标并写入 committed marker；同步异常时恢复原文件，进程中断后由下一次受锁 mutation 或 `rebuild` 幂等恢复。`inspect`、`verify`、Bootstrap 诊断与 Workflow Manager 正式状态读取期间获取与 mutation 共用的 formal-state lock；活动 writer、其他 reader 或未恢复 journal 均使读取 fail-closed，避免检查通过后又读到混合 revision。只读调用方不得接管死锁或执行事务恢复。日常 `verify` 不遍历历史分片，只校验当前视图、JSONL 索引、物料和状态不变量；显式 `verify --history` 还检查全部事件分片的连续性、元数据、记录 checksum、schema 2 checksum 链以及最新 replay 结果与全局视图的一致性。`rebuild` 按 revision replay 每个 stream，并按确定顺序重建 JSONL 索引。
 
 ## 1. 权威源码与安装结果
 
@@ -42,14 +42,14 @@ artifact registry 与 workflow state 的新 mutation 都使用 schema 2 增量
 每次 mutation：
 
 1. 获取 mutation 与只读正式状态快照共用的 formal-state lock，避免并发追加或读取时观察到部分提交；
-2. artifact 读取并比较 `--expected-revision`；workflow 读取并比较 owning scope 的 `--expected-scope-revision`，旧顶层参数只作兼容；
+2. artifact 读取并比较 `--expected-revision`；workflow 读取并比较 owning scope 的 `--expected-scope-revision`；
 3. 校验命令输入和跨文件引用；
 4. 每个受影响 aggregate 的 revision 分别加一；
-5. 生成同一语义动作涉及的全部事件分片、当前 YAML、兼容视图和下一版 JSONL 的完整暂存内容，并对每个原文件和新文件记录 checksum；
+5. 生成同一语义动作涉及的全部事件分片、当前 YAML 和下一版 JSONL 的完整暂存内容，并对每个原文件和新文件记录 checksum；
 6. 持久化一个 prepared journal，再替换全部目标；捕获到异常时按 checksum 恢复整个写集合；
 7. 所有目标替换完成后持久化 committed marker，再清理备份、暂存文件和 journal；
 8. 进程中断后，下一次受锁 mutation 或 `rebuild` 回滚 prepared journal，或验证并清理 committed journal；锁持有进程仍存活时拒绝接管；
-9. schema 2 事务把前一分片 `record_checksum` 写入 `previous_checksum`，旧分片没有记录 checksum 时使用其规范化记录 checksum 作为链锚；scope start 的 `project.yaml` 兼容字段与 workflow shard、当前视图、JSONL 同事务提交；物料交接的 workflow/artifact 分片共享事务 ID；
+9. schema 2 事务把前一分片 `record_checksum` 写入 `previous_checksum`；scope start 的项目身份与 workflow shard、当前视图、JSONL 同事务提交；物料交接的 workflow/artifact 分片共享事务 ID；
 10. 释放锁。
 
 不要在新调用方中解析并重写正式 YAML。调用 `executeDeliveryStateCommand()`，或在已安装项目中执行 `.workflow/tools/state/state.mjs`。bootstrap 已按此边界登记诊断报告。
@@ -62,8 +62,6 @@ artifact registry 与 workflow state 的新 mutation 都使用 schema 2 增量
 - `verify`
 - `snapshot create`
 - `artifact register`
-- `artifact status`
-- `artifact compact`（顶层 `ai-delivery compact --dry-run` 为零写入；apply 先验证压缩归档再移除 loose history）
 - `artifact prune`（默认零写入 dry-run，显式 `--apply` 才执行保留裁剪）
 - `transition`
 - `gate request`
@@ -92,7 +90,7 @@ artifact registry 与 workflow state 的新 mutation 都使用 schema 2 增量
 
 日常 `verify` 校验：
 
-- `workflow-state.schema_version` 为 2（兼容读取 1），`artifact-registry.schema_version` 为 1；
+- `workflow-state.schema_version` 为 2，`artifact-registry.schema_version` 为 1；
 - revision 为非负整数；
 - revision 1 到当前 revision 的审计事件各出现一次；
 - 当前正式 YAML checksum 与最后审计事件一致；
@@ -105,7 +103,7 @@ artifact registry 与 workflow state 的新 mutation 都使用 schema 2 增量
 
 `snapshot references --iteration-id <id> [--candidate-id <id>]` 是版本归档唯一可信引用投影。它复用正式状态模块的 anchor 校验，在同一读锁内验证 pointer、anchor、快照、scope manifest 与 candidate，并为 Gate decision 生成 canonical checksum。checkpoint 任务脚本只能消费该 JSON 输出，不得复制 anchor 校验逻辑。
 
-已有锚点时，日常 `verify` 验证锚点与快照 checksum、当前正式视图和 JSONL 后缀，不读取事件分片或解压历史归档。`verify --history --since-anchor` 额外要求锚点后每个 stream 的分片数量与 revision 差一致，后缀 revision 各出现一次，分片元数据与 JSONL 后缀一致，记录 checksum 和 checksum 链连续，并从锚点快照 replay 到当前正式视图。没有 compaction/retention 时，`verify --history` 保持完整历史审计：要求每个 stream 的分片数量与当前 revision 一致，revision 1 到当前 revision 各出现一次，并 replay 全部旧快照与 delta。`artifact compact` 只选择最新可信 anchor 覆盖的 legacy `after_value` shards；dry-run 零写入计算 root digest、coverage 和净释放空间，apply 先写 gzip bundle/manifest、重新校验所有 entry checksum 并 replay 到锚定 registry checksum，验证失败不得移动 loose 文件。成功后 `verify --history` 返回 `compacted-history` 并审计归档包与保留后缀。`artifact prune` 则删除 anchor 前缀并写 `.workflow/control/retention/artifact-registry/<anchor-id>.yaml` receipt；其 `verify --history` 返回 `retained-history`，不能伪称重新审计已删除字节。`rebuild` 以 anchor 原字节快照为基线，不得从 revision 0 replay 或重写仍承担 anchor 边界的 JSONL 索引。
+已有锚点时，日常 `verify` 验证锚点与快照 checksum、当前正式视图和 JSONL 后缀，不读取事件分片。`verify --history --since-anchor` 额外要求锚点后每个 stream 的分片数量与 revision 差一致，后缀 revision 各出现一次，分片元数据与 JSONL 后缀一致，记录 checksum 和 checksum 链连续，并从锚点快照 replay 到当前正式视图。`verify --history` 要求每个 stream 的分片数量与当前 revision 一致，revision 1 到当前 revision 各出现一次，并 replay 全部事件与 delta。`artifact prune` 删除 anchor 前缀并写 `.workflow/control/retention/artifact-registry/<anchor-id>.yaml` receipt；其 `verify --history` 返回 `retained-history`，不能伪称重新审计已删除字节。`rebuild` 以 anchor 快照为基线并重建 JSONL 索引。
 
 JSONL 审计不是外部签名账本。拥有仓库写权限的人可以同时篡改状态和审计文件；高保证环境应把 Git 签名、CI 证明或外部不可变审计存储作为补充，不能宣称本地 checksum 可抵御恶意共同篡改。
 
@@ -135,7 +133,7 @@ npm run audit:verify
 
 ## 9. 完成定义
 
-`workflow-state.yaml` 当前 schema 为 2。修改状态实现时必须保持 schema 1 只读兼容，并分别验证 `development_state` 与 `release_state` 的 scope、局部 revision、节点集合、Gate 集合和节点尝试。流程图不能退化为简单“上一编号节点”判断：平台准备允许并行，体验与产品允许带原因重开，后续迭代允许用成功的冻结基线物料满足未受影响的前置条件。
+`workflow-state.yaml` 当前 schema 为 2。修改状态实现时必须分别验证 `development_state` 与 `release_state` 的 scope、局部 revision、节点集合、Gate 集合和节点尝试。流程图不能退化为简单“上一编号节点”判断：平台准备允许并行，体验与产品允许带原因重开，后续迭代允许用成功的冻结基线物料满足未受影响的前置条件。
 
 独立 aggregate 的 writer 仍通过共享提交区串行更新 JSONL 和全局视图，但使用各自的 aggregate revision：最多等待可识别的活动事务 30 秒，获取锁后重新读取并可分别成功。同一 aggregate 的 writer 在等待后必须因 revision conflict fail-closed。未知格式锁和只读入口不等待、不恢复，遇到 live lock 或 journal 立即失败。
 

package/docs/STATE-CLI-USER-GUIDE.zh-CN.md

@@ -1,10 +1,10 @@
 # 正式状态 CLI 使用指南
 
-当前研发生产模型是 `development-seven-node`：`00-bootstrap -> 01-product-shaping -> 02-solution-design -> 03-delivery-readiness -> 04-implementation -> 05-candidate-assurance -> 06-version-closeout`。生产 Skill 为新任务、物料和 transition 使用这些节点 ID。旧 13 个研发节点仅保留只读兼容：`inspect`、`verify`、`rebuild` 和显式迁移可读取历史记录；新任务、物料登记、transition、candidate、版本收尾和 Gate 写入全部拒绝。`R00-release-request` 至 `R10-release-archive` 继续允许写入。
+当前研发生产模型是 `development-seven-node`：`00-bootstrap -> 01-product-shaping -> 02-solution-design -> 03-delivery-readiness -> 04-implementation -> 05-candidate-assurance -> 06-version-closeout`。生产 Skill 为新任务、物料和 transition 使用这些节点 ID。`R00-release-request` 至 `R10-release-archive` 继续允许写入。
 
 ## 可重建视图
 
-正式状态 mutation 会生成 `.workflow/control/events/<stream>/<revision>-<event-id>.yaml` 权威事件分片，并与 `workflow-state.yaml` 或 `artifact-registry.yaml` 当前视图及 `state-events.jsonl` 索引作为一组提交。workflow 与 artifact mutation 都使用 schema 2 增量事务：事件只保存顶层元数据和受影响的 scope 或物料，不再嵌入完整视图；scope start 还把 `project.yaml` 兼容身份纳入同一事务。带已登记 evidence 的 transition/Gate 会在同一事务中同时生成 workflow delta 和 artifact handoff delta，并向 registry 顶层 `handoffs` 追加独立关系；已登记 artifact revision 的字段保持不变。提交前会在 `.workflow/delivery/runtime/formal-state-locks/` 写入恢复 journal；`inspect`、`verify`、Bootstrap 诊断及 Workflow Manager 正式状态读取期间持有同一把 formal-state lock，遇到并发 mutation 或未恢复 journal 时 fail-closed，不会返回混合 revision。mutation writer 最多等待可识别的活动提交 30 秒，获取锁后重新读取并校验自己的 aggregate revision。下一次 mutation 或 `rebuild` 根据 commit marker 回滚 prepared 事务或清理 committed 事务。旧的完整快照分片保持只读兼容且不会在首次追加新事务时被改写。视图丢失或损坏时执行：
+正式状态 mutation 会生成 `.workflow/control/events/<stream>/<revision>-<event-id>.yaml` 权威事件分片，并与 `workflow-state.yaml` 或 `artifact-registry.yaml` 当前视图及 `state-events.jsonl` 索引作为一组提交。workflow 与 artifact mutation 都使用 schema 2 增量事务：事件只保存顶层元数据和受影响的 scope 或物料，不再嵌入完整视图；scope start 同时固化项目身份。带已登记 evidence 的 transition/Gate 会在同一事务中同时生成 workflow delta 和 artifact handoff delta，并向 registry 顶层 `handoffs` 追加独立关系；已登记 artifact revision 的字段保持不变。提交前会在 `.workflow/delivery/runtime/formal-state-locks/` 写入恢复 journal；`inspect`、`verify`、Bootstrap 诊断及 Workflow Manager 正式状态读取期间持有同一把 formal-state lock，遇到并发 mutation 或未恢复 journal 时 fail-closed，不会返回混合 revision。mutation writer 最多等待可识别的活动提交 30 秒，获取锁后重新读取并校验自己的 aggregate revision。下一次 mutation 或 `rebuild` 根据 commit marker 回滚 prepared 事务或清理 committed 事务。视图丢失或损坏时执行：
 
 ```powershell
 node .workflow/tools/state/state.mjs rebuild
@@ -153,7 +153,7 @@ node .workflow/tools/state/state.mjs artifact register \
   --supersedes ART-PRODUCT-001
 ```
 
-`draft` 和 `review-draft` 不得登记。新登记的 submitted、rejected、approved、frozen、failed 和 superseded revision 都不可原地修改；`artifact status` 只用于把升级前已登记的遗留 draft 携带 evidence 一次性迁移为正式状态。`--path` 必须是项目相对路径，以 `.workflow/` 开头，且真实文件不能通过符号链接逃逸。重复 ID、重复受控版本和正式 revision 重写会被拒绝。成功命令会原子提交 delta 分片、当前 registry 和 JSONL 索引；任一目标无法暂存或替换时立即回滚。若进程在提交窗口中断，`inspect` 和 `verify` 会拒绝读取半提交状态；重试 mutation 或运行 `rebuild` 会先恢复 journal，再继续命令。
+`draft` 和 `review-draft` 不得登记。新登记的 submitted、rejected、approved、frozen、failed 和 superseded revision 都不可原地修改。`--path` 必须是项目相对路径，以 `.workflow/` 开头，且真实文件不能通过符号链接逃逸。重复 ID、重复受控版本和正式 revision 重写会被拒绝。成功命令会原子提交 delta 分片、当前 registry 和 JSONL 索引；任一目标无法暂存或替换时立即回滚。若进程在提交窗口中断，`inspect` 和 `verify` 会拒绝读取半提交状态；重试 mutation 或运行 `rebuild` 会先恢复 journal，再继续命令。
 
 可信 history anchor 建立后，可先零写入预览可裁剪的 artifact shard：
 
@@ -164,15 +164,6 @@ node .workflow/tools/state/state.mjs artifact prune --apply
 
 默认命令只返回计划，不创建目录、receipt 或时间戳。只有显式 `--apply` 才删除 anchor 已覆盖的 `.workflow/control/events/artifact-registry/` 分片，并在 `.workflow/control/retention/artifact-registry/<anchor-id>.yaml` 写入一条带 checksum 的保留决策；anchor 后的分片和 JSONL 边界继续保留。裁剪后 `verify --history` 返回 `retained-history`，从最新可信 anchor 验证剩余链，不再声称重新审计了已删除的前缀；`rebuild` 同样从 anchor 快照开始 replay。
 
-legacy full-snapshot history 需要保留可重放原字节时，不使用 prune，而由发行包执行独立 compact：
-
-```bash
-ai-delivery compact <project-root> --dry-run
-ai-delivery compact <project-root>
-```
-
-dry-run 严格零写入，返回 anchor、revision 覆盖范围、原历史根摘要、loose/archive 字节数和预计净释放空间。apply 把 anchor 覆盖的 legacy `after_value` shards 写入 `.workflow/control/archives/history/artifact-registry/<anchor-id>.json.gz`，manifest 绑定 bundle checksum、每个原文件、coverage 和锚定 registry checksum。CLI 从落盘 bundle 解压并完整 replay，只有 replay checksum 与 anchor 完全一致才移除 loose shards；失败时不移除任何 loose history。压缩后 `verify --history` 返回 `compacted-history` 并重新校验 archive、entry、anchor 与 replay；第一条后续 delta 从 anchor 的记录链头继续。
-
 版本归档前由 `task-state.mjs archive-version` 内部调用以下只读投影；通常不需要人工单独执行：
 
 ```bash
@@ -209,7 +200,7 @@ node .workflow/tools/state/state.mjs transition \
   --production-version-id <version-id>
 ```
 
-`version-closed` 要求 `06-version-closeout` 已完成，且物料来自该节点并处于 `release-ready`；它更新 `latest_line_version_id`。`release-archived` 要求 `R10-release-archive` 已完成，且物料来自该节点并处于 `released`；它更新 `production_version_id` 和 `production_release_id`。三个字段的权威来源都是 `workflow-state.yaml`，不得直接编辑；`project.yaml` 中的旧字段只用于兼容读取。
+`version-closed` 要求 `06-version-closeout` 已完成，且物料来自该节点并处于 `release-ready`；它更新 `latest_line_version_id`。`release-archived` 要求 `R10-release-archive` 已完成，且物料来自该节点并处于 `released`；它更新 `production_version_id` 和 `production_release_id`。三个字段的权威来源都是 `workflow-state.yaml`，不得直接编辑。
 
 Gate 请求：
 
@@ -236,7 +227,6 @@ node .workflow/tools/state/state.mjs gate decide \
 
 决定必须保留请求时的全部 evidence，并明确记录 `actor` 和 `rationale`。AI 文本、Hook、Manager 页面成功提示或命令成功不能替代正式批准凭证。非视觉体验范围把 UX Gate 设为 `not-required` 时，还必须附加来自 `01-product-shaping`、状态成功且 `artifact_type` 包含 `terminal` 的已登记证据；推荐统一使用 `product-terminal-scope`。
 
-`UX-LF` 已从当前契约退役。新的 request 和 decide 会在写入前拒绝；历史记录仍可 inspect、verify 和 rebuild。升级 dry-run 会在 `contract_retirement.affected_iterations` 中列出开放 scope 的 pending `UX-LF`，正式升级由 `system:package-upgrade` 追加 `gate-contract-retired` 事件和 checksum 回执，不创建人工 Gate 决定，也不改写关闭迭代或归档。
 
 ## 7. revision 冲突与失败恢复
 
@@ -253,10 +243,10 @@ node .workflow/tools/state/state.mjs gate decide \
 
 ## 8. 生产阶段
 
-研发与发布使用两个独立状态域：`development_state.scope_id` 由 `iteration-started` 建立，`release_state.scope_id` 由用户明确发布后执行 `release-started` 建立。两者分别保存局部 revision、活动/阻塞/完成节点、Gate、节点尝试次数和选定物料；局部 revision 用于 workflow 乐观并发，顶层 `workflow_state.revision` 只负责审计串行化并保留旧参数兼容。
+研发与发布使用两个独立状态域：`development_state.scope_id` 由 `iteration-started` 建立，`release_state.scope_id` 由用户明确发布后执行 `release-started` 建立。两者分别保存局部 revision、活动/阻塞/完成节点、Gate、节点尝试次数和选定物料；局部 revision 用于 workflow 乐观并发，顶层 `workflow_state.revision` 只负责审计串行化。
 
 `node-started` 会验证流程图前置条件。当前迭代未执行的前置节点，可以用来自该节点且处于成功状态的已登记基线物料作为 evidence；这用于后续迭代只重访受影响基线。重新打开已完成节点必须提供 `--reason`，并产生新的节点尝试，旧 Gate 决定不能批准新一轮输出。
 
-`node-completed` 只接受成功状态物料，并检查当前尝试的必需 Gate：`GATE-A`、`GATE-B`、`UX-VS`、`UX-UI` 和 `PRODUCTION-APPROVAL`。只有确实无视觉交互的体验范围可以依据产品终端证据把活动 UX Gate 决定为 `not-required`；Gate A、Gate B 和生产审批必须为 `approved`。历史 `12-release-preparation` 至 `16-version-archive` 只允许登记和读取审计物料，新的 transition 和 Gate 命令会拒绝这些节点。
+`node-completed` 只接受成功状态物料，并检查当前尝试的必需 Gate：`GATE-A`、`GATE-B`、`UX-VS`、`UX-UI` 和 `PRODUCTION-APPROVAL`。只有确实无视觉交互的体验范围可以依据产品终端证据把活动 UX Gate 决定为 `not-required`；Gate A、Gate B 和生产审批必须为 `approved`。
 
-每个节点交接、生产审批和部署前运行日常 `verify`；版本收尾和发布归档还必须运行 `verify --history`。新研发流程使用 `06-version-closeout` 和 `release-ready`；完成该节点后通过 `version-closed` 记录累计研发版本，但不得创建任何 R 节点。独立发布使用 `R00-release-request` 至 `R10-release-archive`；启动 R00 时必须提供节点为 R00、状态成功且 `artifact_type: release-request` 的显式用户请求物料。R09 只产生生产验证结论，R10 完成并登记 `released` 归档物料后，才通过 `release-archived` 正式回写生产版本和 release ID。发布选择只能引用精确不可变 `version-ready` Tag 和已登记版本物料，生产审批只发生在 R07，并绑定精确 release ID、包 checksum、镜像 digest、配置、迁移、环境和回滚镜像；任一项变化均创建新发布候选并重新审批。
+每个节点交接、生产审批和部署前运行日常 `verify`；版本收尾和发布归档还必须运行 `verify --history`。新研发流程使用 `06-version-closeout` 和 `release-ready`；完成该节点后通过 `version-closed` 记录累计研发版本，但不得创建任何 R 节点。独立发布使用 `R00-release-request` 至 `R10-release-archive`；启动 R00 时必须提供节点为 R00、状态成功且 `artifact_type: release-request` 的显式用户请求物料，并固定请求时 `main` 的 `expected_main`。R04 必须以 `release-git.mjs create-candidate` 的 `--expected-main`、精确 `--source-tag/--source-commit`、`--receipt` 和 `--apply` 从该快照创建 release 分支。增量发布只以 `--no-ff` 合入一个精确不可变 `version-ready` Tag；同版本重发在目标 Tag 已包含于快照时不新增合并，候选就是该快照。候选、审批和部署都绑定该精确候选提交。R09 成功结论先写入带 `operation: production-verification-decision` 的机器 JSON，再通过 `release-git.mjs promote --production-verification <R09-json>` 触发受控的精确 `main` 快进；R10 在归档前准备 schema 2 的产品线级 `candidate-inventory.json`，其根部固定 `scope: product-line`、`product_id`、`line_branch` 和 active candidate，每项候选保留自己的 `release_id`、commit/status。以 `sync-release-fix --expected-line --production-verification <R09-json> --candidate-inventory <predecessor-R10-json> --successor-candidate-inventory <new-R10-json> --receipt --apply` 受控同步每个成功的 release-fix 到 `line/<product-id>`；脚本只写入新的不可变 successor 库存，在回执中绑定前代/后代库存，并派生、登记带 release ID 的 `stale_candidate_ids` 与 `candidate_status_updates`。main 漂移、候选不一致或遗漏已成功 fix 都使候选 stale。R10 完成并登记 `released` 归档物料后，才通过 `release-archived` 正式回写生产版本和 release ID。生产审批只发生在 R07，并绑定精确 release ID、main 基线、source Tag/commit、候选 commit/Tag、包 checksum、镜像 digest、配置、迁移、环境和回滚镜像；任一项变化均创建新发布候选并重新审批。

package/docs/adr/0006-product-line-candidate-inventory.md

@@ -0,0 +1,20 @@
+---
+status: accepted
+---
+
+# Product-line candidate inventory and release-fix synchronization
+
+Release candidates are a product-line concern, not a private list attached to one release directory. R10 therefore freezes a schema-2 candidate inventory scoped by `product_id` and `line_branch`; each candidate retains the `release_id` that created it. The inventory has no root `release_id`, so one line can be audited across successive releases and redeploys.
+
+## Decision
+
+`release-git.mjs sync-release-fix` accepts an immutable predecessor inventory and, with `--apply`, a distinct `--successor-candidate-inventory` path. It validates the R09 `released` decision, the active and verified candidates, the expected line head, and the product-line identity before changing a Git ref. Selectable candidates anywhere in that inventory that do not contain the verified fix are derived as `stale`; callers cannot provide that list. The operation merges the exact fix commit into `line/<product-id>`, writes the successor inventory, and records both inventory evidence bindings plus the derived updates in its receipt. When the active candidate becomes stale, the successor points at the verified candidate.
+
+The predecessor is never rewritten. A retry is idempotent only when the line already contains the fix and the existing successor is byte-identical to the controlled output. Failed deployment, rollback, or an unresolved human decision leaves `main`, `line`, and all immutable inventories unchanged.
+
+## Consequences
+
+- Candidate status history is durable and can be followed through predecessor/successor checksums rather than inferred from branch heads.
+- A release-fix can invalidate candidates from earlier releases on the same product line without erasing their release identities; already `stale` or `released` candidates are not rewritten.
+- R10 callers must allocate a new successor path and register its receipt before archive completion.
+- Consumers of the old release-scoped schema must migrate to schema 2; the protected operation rejects a root `release_id` or a missing candidate-level `release_id`.

package/docs/agents/domain.md

@@ -1,12 +1,37 @@
 # Domain Docs
 
+工程技能探索本仓库时应遵循以下领域文档规则。
+
+## 探索前读取
+
+- 根目录 `CONTEXT.md`；如果存在 `CONTEXT-MAP.md`，则按其指向读取相关上下文
+- 与目标区域相关的 `docs/adr/`
+
+文件不存在时直接继续，不预先建议创建；`/domain-modeling` 会在术语或决策真正确定时按需创建。
+
+## 文件布局
+
 本仓库采用 single-context 布局：
 
-- 领域术语：根目录 `CONTEXT.md`
-- 架构决策：根目录 `docs/adr/`
+```text
+/
+├── CONTEXT.md
+├── docs/adr/
+│   ├── 0001-<decision>.md
+│   └── 0002-<decision>.md
+└── src/
+```
+
+## 使用术语表
+
+Issue 标题、重构提案、假设和测试名称中的领域概念，应使用 `CONTEXT.md` 定义的术语。不要使用术语表明确排除的同义词。
+
+如果所需概念不在术语表中，应记录为领域建模缺口，而不是自行引入新名称。
+
+## 标记 ADR 冲突
+
+如果输出与现有 ADR 冲突，必须明确指出，例如：
 
-探索代码前读取存在的 `CONTEXT.md`，并读取与目标区域有关的 ADR。
-文件不存在时直接继续，不主动创建；由领域建模流程按需生成。
+> 与 ADR-0007 冲突，但值得重新讨论，因为……
 
-输出中的领域概念使用 `CONTEXT.md` 定义的术语，避免引入被明确
-排除的同义词。若输出与现有 ADR 冲突，必须明确指出冲突及理由。
+不得静默覆盖既有 ADR。

package/docs/agents/issue-tracker.md

@@ -1,27 +1,26 @@
-# Issue Tracker
+# Issue tracker: Local Markdown
 
-本仓库使用 Gitee Issues 跟踪任务：
+本仓库的 Issue 和规格使用 `.scratch/` 下的 Markdown 文件记录。
 
-- 仓库：`hzr1348/work-flow`
-- API：`https://gitee.com/api/v5`
-- Swagger：`https://gitee.com/api/v5/swagger`
-- PR 不作为任务请求入口。
+## 约定
 
-## Authentication
+- 一个功能使用一个目录：`.scratch/<feature-slug>/`
+- 规格文件：`.scratch/<feature-slug>/spec.md`
+- 实现任务按文件拆分：`.scratch/<feature-slug>/issues/<NN>-<slug>.md`，从 `01` 编号
+- 每个任务文件顶部附近使用 `Status:` 行记录 triage 状态
+- 评论和对话记录追加在文件底部的 `## Comments` 标题下
 
-令牌只从环境变量 `GITEE_TOKEN` 读取，请求头使用：
+## 技能要求发布到 Issue tracker 时
 
-`Authorization: token <PAT>`
+在 `.scratch/<feature-slug>/` 下创建文件；目录不存在时一并创建。
 
-令牌不得写入 URL、输出、日志、脚本或仓库文件。
+## 技能要求获取任务时
 
-## Execution
+直接读取引用的文件路径；用户通常会提供路径或任务编号。
 
-每个新会话首次访问时，先调用 `GET /user`。预期账号为
-`hzr1348`，用户 ID 为 `17347733`；身份不符时停止。
+## Wayfinding 操作
 
-写操作必须先读取并确认目标，获得当前请求授权后执行，再重新读取
-目标验证结果。Swagger 页面只用于查阅，实际请求使用 API endpoint。
-
-Gitee MCP 返回 `401 Access token is wrong type` 时使用 REST API。
-网络沙箱阻止请求时，为目标 Gitee API 请求申请网络权限。
+- Map：`.scratch/<effort>/map.md`
+- 子任务：`.scratch/<effort>/issues/NN-<slug>.md`
+- 阻塞关系：在任务顶部使用 `Blocked by: NN, NN`
+- Frontier：按编号优先选择开放、未阻塞且未认领的任务

package/docs/agents/triage-labels.md

@@ -1,11 +1,11 @@
 # Triage Labels
 
-| Canonical role    | Gitee label      | Meaning            |
-| ----------------- | ----------------- | ------------------ |
-| `needs-triage`    | `needs-triage`    | 等待维护者评估     |
-| `needs-info`      | `needs-info`      | 等待补充信息       |
+| Canonical role | Label | Meaning |
+| --- | --- | --- |
+| `needs-triage` | `needs-triage` | 等待维护者评估 |
+| `needs-info` | `needs-info` | 等待补充信息 |
 | `ready-for-agent` | `ready-for-agent` | 可交给自主代理执行 |
-| `ready-for-human` | `ready-for-human` | 需要人工实现       |
-| `wontfix`         | `wontfix`         | 不会处理           |
+| `ready-for-human` | `ready-for-human` | 需要人工实现 |
+| `wontfix` | `wontfix` | 不会处理 |
 
-技能提到 canonical role 时，使用表中对应的 Gitee label。
+技能提到 canonical role 时，使用表中对应的 Label。