ai-delivery-workflow 0.2.2

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

@@ -0,0 +1,135 @@
+# 正式状态 CLI 维护指南
+
+当前写入顺序为“权威事件分片 -> 全局兼容视图 -> JSONL 事件索引”。`verify` 同时检查事件分片自身 checksum 和最新分片与全局视图是否一致；`rebuild` 从每个 stream 的最新分片恢复 YAML，并按确定顺序重建 JSONL 索引。
+
+## 1. 权威源码与安装结果
+
+| 路径 | 作用 |
+| --- | --- |
+| `lib/delivery-state.mjs` | 正式状态命令、校验、锁、原子写和审计实现 |
+| `bin/ai-delivery.mjs` | 发行包 `state` 子命令透传入口 |
+| `skills/ai-delivery-orchestrate/assets/project-template/.workflow/tools/state/state.mjs` | 安装后的自包含 CLI wrapper |
+| `lib/project-installer.mjs` | 安装 wrapper、状态模块和 vendored `yaml` |
+| `verification/delivery-state.test.mjs` | 正式状态公共命令契约测试 |
+| `verification/project-installer.test.mjs` | 自包含安装、manifest、doctor 和实际执行测试 |
+
+`lib/delivery-state.mjs` 是唯一实现源。安装器复制它，不维护第二份逻辑。wrapper 只注入 YAML adapter、输出 JSON 和设置失败退出码。
+
+## 2. 自包含运行时
+
+目标业务项目不应为了工作流修改自己的 `package.json`。`init` 将以下文件写入：
+
+```text
+.workflow/tools/state/
+  state.mjs
+  delivery-state.mjs
+  vendor/yaml/
+```
+
+`vendor/yaml/package.json` 必须保留，使 CommonJS `dist/*.js` 在业务项目声明 `"type": "module"` 时仍按正确模块类型加载。升级 `yaml` 时要重新运行安装测试和隔离项目测试。
+
+## 3. 状态流
+
+正式状态分为两个独立 revision stream：
+
+- `workflow-state`；
+- `artifact-registry`。
+
+每次 mutation：
+
+1. 获取两个 stream 共用的 formal-state lock，避免并发追加审计事件时相互覆盖；
+2. 读取并比较 `--expected-revision`；
+3. 校验命令输入和跨文件引用；
+4. revision 加一；
+5. 原子替换 YAML；
+6. 向 `state-events.jsonl` 追加包含 stream、revision、事件类型和 `after_checksum` 的审计事件；
+7. 释放锁。
+
+不要在新调用方中解析并重写正式 YAML。调用 `executeDeliveryStateCommand()`，或在已安装项目中执行 `.workflow/tools/state/state.mjs`。bootstrap 已按此边界登记诊断报告。
+
+## 4. 公共接口
+
+稳定 seam：
+
+- `inspect`
+- `verify`
+- `artifact register`
+- `artifact status`
+- `transition`
+- `gate request`
+- `gate decide`
+
+`transition` 还承载两个受约束的里程碑事件：
+
+- `version-closed`：校验已完成的 `12-version-closeout` 和 `release-ready` 物料，只更新 `latest_line_version_id`；
+- `release-archived`：校验已完成的 `R10-release-archive`、`released` 物料和目标生产版本，只更新 `production_version_id`、`production_release_id`。
+
+这些字段属于 `workflow-state` 审计流。不得把 `project.yaml` 变成第二写入口，也不得由查看器、Hook 或 R09 直接回写。
+
+新增行为时遵循一个失败测试、最小实现、单文件测试的 TDD 循环。测试只通过 `executeDeliveryStateCommand()` 或真实 CLI 观察行为，不测试内部函数。
+
+任何新增 mutation 都必须：
+
+- 要求 `--expected-revision`；
+- 使用正确 stream lock；
+- 原子写；
+- 产生审计事件；
+- 返回新 revision；
+- 保持 `verify` 可检测绕过写入；
+- 在用户手册、正式状态契约和相关节点 Skill 中同步说明。
+
+## 5. `verify` 契约
+
+当前校验：
+
+- `workflow-state.schema_version` 为 2（兼容读取 1），`artifact-registry.schema_version` 为 1；
+- revision 为非负整数；
+- revision 1 到当前 revision 的审计事件各出现一次；
+- 当前正式 YAML checksum 与最后审计事件一致；
+- 两个作用域有状态时必须有各自的 `scope_id`，且 active、blocked、completed 节点不重叠、节点位于正确作用域；
+- 物料 ID 和路径唯一；
+- 物料文件存在于 `.workflow/` 内，真实路径不逃逸；
+- 登记 checksum 与当前文件 SHA-256 一致。
+
+JSONL 审计不是外部签名账本。拥有仓库写权限的人可以同时篡改状态和审计文件；高保证环境应把 Git 签名、CI 证明或外部不可变审计存储作为补充，不能宣称本地 checksum 可抵御恶意共同篡改。
+
+## 6. 查看器集成
+
+查看器从 `artifact-registry.yaml` 结构化读取已登记物料。对于路径匹配的物料，注册表中的 ID、status、version 和 node 优先于正文字段；Git 未提交变更仍作为独立的“已变更”状态优先显示。查看器只读，不能调用状态 mutation。
+
+查看器在安装项目中读取同一 vendored YAML；在发行仓库测试环境中回退到包依赖。修改目录关系时同时验证源码模板和安装后运行时。
+
+## 7. Evolution Hook 接线
+
+正式状态 CLI 的物料、Gate 和 transition 写命令会通过安装后的 Evolution runtime 自动发出对应的 `before`、`after`、`failed` 事件。只有 checksum 绑定且人工批准的 `before` 阻断规则可以在写入前停止命令；`after` 和 `failed` 事件只记录结果，不回写正式状态。Evolution runtime 缺失或损坏由 `doctor` 报告，不得通过 Hook 直接修改正式状态文件。
+
+## 8. 验证命令
+
+```bash
+node --test verification/delivery-state.test.mjs
+node --test verification/project-installer.test.mjs
+node --test verification/project-bootstrap.test.mjs
+node --test verification/workflow-viewer.test.mjs
+npm test
+node --test verification/checkpoint-task-state.test.mjs
+npm run audit:verify
+```
+
+还应在隔离目录执行 `init`、`doctor`、项目内 `state inspect` 和 `state verify`，并确认业务 `package.json` 未被修改。
+
+## 9. 完成定义
+
+`workflow-state.yaml` 当前 schema 为 2。修改状态实现时必须保持 schema 1 只读兼容，并分别验证 `development_state` 与 `release_state` 的 scope、局部 revision、节点集合、Gate 集合和节点尝试。流程图不能退化为简单“上一编号节点”判断：平台准备允许并行，体验与产品允许带原因重开，后续迭代允许用成功的冻结基线物料满足未受影响的前置条件。
+
+安装诊断不得从项目内可编辑 manifest 推导可信 Skill 集合。固定 Skill 清单、Skill 目录摘要、Hook 摘要和状态运行时摘要以发行包为准；manifest 必须与发行包一致。`doctor` 还必须运行安装后状态 CLI 的 `inspect` 与 `verify`，并校验 JSON 输出语义。
+
+正式状态相关变更只有在以下条件全部满足后才完成：
+
+- 公共命令测试通过；
+- 安装后的自包含 CLI 实际可运行；
+- bootstrap 等调用方没有直接写正式状态；
+- `doctor` 检查运行时完整；
+- 查看器仍为只读并正确显示注册表状态；
+- 25 个 Skill 通过校验；
+- 审计物料校验和全量测试通过；
+- 用户手册、维护手册、文件索引和相关 Skill 已同步。

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

@@ -0,0 +1,186 @@
+# 正式状态 CLI 使用指南
+
+## 可重建视图
+
+每次正式状态 mutation 会先写入 `.workflow/control/events/<stream>/<revision>-<event-id>.yaml` 权威事件分片，再刷新兼容的 `workflow-state.yaml`、`artifact-registry.yaml` 和 `state-events.jsonl` 视图。视图丢失或损坏时执行：
+
+```powershell
+node .workflow/tools/state/state.mjs rebuild
+node .workflow/tools/state/state.mjs verify
+```
+
+`rebuild` 不从聊天记录推断状态，只读取不可变事件分片。没有事件分片的历史项目保持原视图不变。
+
+> 适用入口：`.workflow/tools/state/state.mjs`  
+> 适用范围：正式流程、物料、Gate、候选和发布状态
+
+## 1. 为什么必须使用脚本
+
+`.workflow/delivery/workflow-state.yaml` 和 `.workflow/delivery/artifact-registry.yaml` 是研发流程的控制面，不是普通说明文档。通过脚本修改可以统一完成：
+
+- revision 乐观并发控制；
+- 文件锁和原子替换；
+- 物料 SHA-256 登记；
+- Gate 证据和决策人校验；
+- 节点状态不变量校验；
+- `.workflow/delivery/state-events.jsonl` 审计记录；
+- 中断后通过 `inspect` 和 `verify` 恢复可信上下文。
+
+禁止直接编辑上述两个 YAML、审计 JSONL，以及 `.workflow/delivery/runtime/` 下的任务状态。脚本失败时应修复输入、revision 冲突或脚本问题，不得手工绕过。
+
+## 2. 两个状态脚本的边界
+
+| 状态 | 唯一写入口 |
+| --- | --- |
+| 正式流程、物料、Gate、候选、发布 | `node .workflow/tools/state/state.mjs ...` |
+| 任务、checkpoint、恢复、活动任务、版本归档 | `node .agents/skills/ai-delivery-checkpoint-task/scripts/task-state.mjs ...` |
+
+Hook 只记录脱敏生命周期事件和心跳，不得修改两类状态，也不得推断完成或批准。
+
+## 3. 标准操作顺序
+
+1. 先通过只读 Bootstrap inspect 读取 `next_action_owner`；仅当它为 `agent` 时才用 `task-state.mjs recover` 恢复并激活 `recommended_task_id`。`user/external` 等待态禁止写入；收到所需输入后，用带新 `--next-action` 的 `activate --next-action-owner agent` 原子恢复本机 runtime 并接管任务。
+2. 在 `.workflow/` 写入并验证本节点交付物。
+3. 运行 `inspect`，取得 `workflow_state.revision` 和 `artifact_registry.revision`。
+4. 登记物料或更新物料状态。
+5. 需要 Gate 时提交请求并记录明确决定。
+6. 使用已登记物料作为 evidence 完成节点流转。
+7. 运行 `verify`。
+8. 将物料 ID、revision 和验证结果写入任务 checkpoint 或完成记录。
+
+## 4. 只读命令
+
+```bash
+node .workflow/tools/state/state.mjs inspect
+node .workflow/tools/state/state.mjs verify
+```
+
+`inspect` 返回规范化后的项目、流程和注册表状态，不写文件。`verify` 校验 Schema、revision、节点互斥、物料 ID/路径唯一性、路径边界、物料 checksum、审计 revision 连续性和正式状态文件最后 checksum。
+
+也可由发行包维护者运行：
+
+```bash
+ai-delivery state inspect --project <project-root>
+ai-delivery state verify --project <project-root>
+```
+
+项目执行和恢复时优先使用项目内 `.workflow/tools/state/state.mjs`，确保命令版本与项目安装版本一致。
+
+## 5. 物料命令
+
+首次登记：
+
+```bash
+node .workflow/tools/state/state.mjs artifact register \
+  --expected-revision 0 \
+  --id ART-PRODUCT-001 \
+  --artifact-type product-baseline \
+  --path .workflow/iterations/ITER-01/02-product-definition/product-baseline.yaml \
+  --node 02-product-definition \
+  --status draft \
+  --version 1.0.0 \
+  --producer-skill ai-delivery-define-product
+```
+
+更新生命周期：
+
+```bash
+node .workflow/tools/state/state.mjs artifact status \
+  --expected-revision 1 \
+  --id ART-PRODUCT-001 \
+  --status approved \
+  --evidence GATE-B-DECISION-001
+```
+
+已登记内容发生变化时，创建新文件和新 ID：
+
+```bash
+node .workflow/tools/state/state.mjs artifact register \
+  --expected-revision 2 \
+  --id ART-PRODUCT-002 \
+  --path .workflow/iterations/ITER-01/02-product-definition/product-baseline-v2.yaml \
+  --node 02-product-definition \
+  --status draft \
+  --version 2.0.0 \
+  --supersedes ART-PRODUCT-001
+```
+
+`--path` 必须是项目相对路径，以 `.workflow/` 开头，且真实文件不能通过符号链接逃逸。重复 ID、重复受控版本、无 evidence 的状态变更和 terminal 状态重写会被拒绝。
+
+## 6. 流程和 Gate 命令
+
+启动与完成节点：
+
+```bash
+node .workflow/tools/state/state.mjs transition --expected-revision 0 --event node-started --iteration-id ITER-01 --node 02-product-definition
+node .workflow/tools/state/state.mjs transition --expected-revision 1 --event node-completed --iteration-id ITER-01 --node 02-product-definition --evidence ART-PRODUCT-002
+```
+
+阻塞与解除阻塞必须提供原因。新迭代使用 `iteration-started` 和规划 evidence。候选与发布分别使用 `candidate-selected`、`release-selected` 和已登记的不可变制品 ID。
+
+版本完成和发布归档还需要两个里程碑事件。它们不启动发布，只把已由节点和物料证明的事实写入审计状态：
+
+```bash
+node .workflow/tools/state/state.mjs transition \
+  --expected-revision <revision> \
+  --event version-closed \
+  --iteration-id <version-id> \
+  --artifact-id <closeout-artifact-id>
+
+node .workflow/tools/state/state.mjs transition \
+  --expected-revision <revision> \
+  --event release-archived \
+  --iteration-id <release-id> \
+  --artifact-id <release-archive-artifact-id> \
+  --production-version-id <version-id>
+```
+
+`version-closed` 要求 `12-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` 中的旧字段只用于兼容读取。
+
+Gate 请求：
+
+```bash
+node .workflow/tools/state/state.mjs gate request \
+  --expected-revision 1 \
+  --gate-id GATE-B \
+  --iteration-id ITER-01 \
+  --node 02-product-definition \
+  --evidence ART-PRODUCT-002
+```
+
+Gate 决定：
+
+```bash
+node .workflow/tools/state/state.mjs gate decide \
+  --expected-revision 2 \
+  --gate-id GATE-B \
+  --decision approved \
+  --actor human:product-manager \
+  --rationale "范围、终端和验收标准已核对" \
+  --evidence ART-PRODUCT-002
+```
+
+决定必须保留请求时的全部 evidence，并明确记录 `actor` 和 `rationale`。AI 文本、Hook、查看器操作或命令成功不能替代批准。非视觉体验范围把 UX Gate 设为 `not-required` 时，还必须附加来自 `02-product-definition`、状态成功且 `artifact_type` 包含 `terminal` 的已登记证据；推荐统一使用 `product-terminal-scope`。
+
+## 7. revision 冲突与失败恢复
+
+每个 mutation 都必须传 `--expected-revision`。收到 revision conflict 时：
+
+1. 停止当前写入，不自动递增数字重试。
+2. 重新运行 `inspect`。
+3. 比较他人已写入的状态、物料和审计事件。
+4. 判断当前动作是否仍需要、是否冲突或是否应生成新版本。
+5. 使用新的当前 revision 执行经过重新确认的命令。
+6. 运行 `verify`。
+
+`verify` 失败时，根据错误修复物料或控制面。物料 checksum 不一致通常表示登记后被修改，应恢复原文件或创建新版本；audit checksum 不一致表示正式状态文件可能绕过脚本被修改，应从可信审计、版本控制和交付证据恢复，不能继续流转。
+
+## 8. 生产阶段
+
+研发与发布使用两个独立状态域：`development_state.scope_id` 由 `iteration-started` 建立，`release_state.scope_id` 由用户明确发布后执行 `release-started` 建立。两者分别保存局部 revision、活动/阻塞/完成节点、Gate、节点尝试次数和选定物料；顶层 `workflow_state.revision` 仍用于 `--expected-revision` 和审计串行化。
+
+`node-started` 会验证流程图前置条件。当前迭代未执行的前置节点，可以用来自该节点且处于成功状态的已登记基线物料作为 evidence；这用于后续迭代只重访受影响基线。重新打开已完成节点必须提供 `--reason`，并产生新的节点尝试，旧 Gate 决定不能批准新一轮输出。
+
+`node-completed` 只接受成功状态物料，并检查当前尝试的必需 Gate：`GATE-A`、`GATE-B`、`UX-LF`、`UX-VS`、`UX-UI` 和 `PRODUCTION-APPROVAL`。只有确实无视觉交互的体验范围可以依据产品终端证据把 UX Gate 决定为 `not-required`；Gate A、Gate B 和生产审批必须为 `approved`。历史 `12-release-preparation` 至 `16-version-archive` 只允许登记和读取审计物料，新的 transition 和 Gate 命令会拒绝这些节点。
+
+版本收尾、每个发布节点交接、生产审批、部署和发布归档前必须运行 `verify`。新研发流程使用 `12-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、配置、迁移、环境和回滚镜像；任一项变化均创建新发布候选并重新审批。