ai-delivery-workflow 0.2.2

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

@@ -0,0 +1,931 @@
+# AI Delivery Workflow 完整项目手册
+
+> 仓库身份：当前源码仓库是工作流维护与发行项目，不是下文所述的业务工作区。不要对当前源码仓库套用双仓初始化、业务项目 bootstrap 或 `.workflow/` 状态恢复；下文双仓契约描述的是安装目标。
+>
+> 当前工作区契约：本手册现行版本只支持“工作流控制仓库 + 一个直接子目录代码仓库”，不支持旧单仓迁移，也不使用 Git submodule。完整规则见 [DUAL-REPOSITORY-WORKSPACE.zh-CN.md](DUAL-REPOSITORY-WORKSPACE.zh-CN.md)。
+
+```text
+workspace/.git                 工作流 Git
+workspace/.workflow/           正式物料和共享状态
+workspace/.workflow/config/workspace.yaml
+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 后正式状态和物料被误判为篡改。
+
+> 文档版本：1.0  
+> 适用包版本：`ai-delivery-workflow@0.2.0`
+> 默认文档语言：简体中文  
+> 文件级索引：[FILE-REFERENCE.zh-CN.md](FILE-REFERENCE.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)
+
+## 1. 项目是什么
+
+AI Delivery Workflow 是一套安装在单个代码仓库内的 AI 研发流程。它把从需求发现到生产验证的工作拆成可验证节点，以版本化产物作为节点之间的输入和输出，并通过项目级 skills、Hook、状态文件和 checkpoint 让 AI 可以在不同会话中继续工作。
+
+它解决的不是“让 AI 扮演一组固定岗位”，而是以下问题：
+
+- 每个节点必须读取哪些已确认输入；
+- 产出哪些人和机器都能审阅的交付物；
+- 哪些决定必须由人完成；
+- 下游如何验证上游，而不是默认相信上游；
+- 一个迭代中断后，如何从持久化状态继续；
+- 发布、部署和回滚如何绑定同一不可变版本；
+- 对话中形成的新规范如何沉淀，并在后续任务中生效。
+
+本项目本身是“工作流发行包”。安装后，目标业务仓库才是工作流的运行场所。
+
+## 2. 适用范围与边界
+
+适合：
+
+- 从零开始的最小前后端项目；
+- 已有代码但缺少结构化研发上下文的存量项目；
+- 需要 AI 连续完成产品、架构、体验、测试、开发和上线工作的项目；
+- 需要产物追踪、人工关键决策、任务恢复和版本归档的项目。
+
+当前边界：
+
+- 不替代代码托管、CI、镜像仓库、密钥系统或生产平台；
+- 不自动授予生产权限；
+- 不把 Hook 事件当成任务完成证明；
+- 不自动重放生产部署、数据库迁移、付款、通知或破坏性动作；
+- 不把项目 skills 安装到用户全局目录；
+- 不预设“前端工程师”“服务端工程师”等固定角色，开发能力由需求、架构和工作包动态推导。
+
+## 3. 核心设计原则
+
+### 3.1 产物驱动
+
+每个节点都接收带稳定 ID、版本和状态的正式产物，并输出下一节点可验证的正式产物。聊天内容只用于交互，不作为唯一事实来源。
+
+### 3.2 角色动态化
+
+流程节点代表责任边界，不等于传统岗位。产品定义、架构设计、测试设计等节点有明确职责；开发阶段则根据功能、终端、技术栈、组件和风险动态生成能力角色及技术工作包。
+
+### 3.3 下游验证
+
+普通节点交接不要求人工逐件批准，由下游按契约验证输入。关键业务或不可逆决定保留人工 Gate，见第 8 节。
+
+### 3.4 基线不可变
+
+已批准、冻结、发布或归档的产物不得原地修改。发生变化时创建新版本，标记受影响的下游产物为 `stale`，只重做受影响链路。
+
+### 3.5 版本是归档单位
+
+一次生产部署对应一个迭代版本。任务可以单独完成，但不能单独归档；生产验证成功或版本明确放弃后，才把整个迭代的所有已关闭任务归档。
+
+### 3.6 默认中文
+
+面向人的文档默认使用简体中文。命令、路径、代码标识、Schema 字段、枚举值、协议名和引用原文保持原样。
+
+### 3.7 文档集中存放
+
+所有研发流程文档默认写入项目根目录 `.workflow/`。控制状态放在 `.workflow/delivery/`，规范放在 `.workflow/standards/`，长期产品、架构和体验基线分别放在 `.workflow/product/`、`.workflow/architecture/` 和 `.workflow/experience/`，迭代节点交付物默认放在 `.workflow/iterations/<iteration-id>/<node-id>/`。
+
+应用源码、自动化测试源码、依赖清单、仓库配置、镜像、发布二进制及其他非文档制品保留在其原生位置；描述这些制品身份、digest、变更、部署、验证和回滚的文档仍必须进入 `.workflow/`。`.workflow/` 默认纳入版本控制，只有 `.workflow/delivery/runtime/` 加入 Git 忽略。
+
+### 3.8 测试集中存放
+
+维护仓库的通用、长期验证源码统一位于根 `verification/` 并纳入 Git。业务项目的应用自动化测试位于代码仓库 `<code_repository.path>`，沿用该仓库已有框架、命名和原生测试目录，不得写入 `.workflow/`。
+
+`audit/` 候选包、部署副本和历史审计快照中内嵌的测试文件属于审计物料，可保留原路径；验证这些物料的维护入口位于根 `verification/`。本维护仓库的一切临时仓库、日志、缓存、报告、认证辅助文件和单次场景脚本统一放入被忽略的 `.tmp/`。
+
+## 4. 工作流组成
+
+安装包由四层组成：
+
+| 层 | 位置 | 作用 |
+| --- | --- | --- |
+| CLI | `bin/ai-delivery.mjs` | 安装、检查、引导和诊断目标项目。 |
+| 安装与引导库 | `lib/` | 合并项目配置、识别项目状态、生成存量代码上下文。 |
+| 项目 skills | `skills/ai-delivery-*` | 定义各研发节点的输入、过程、输出、Gate 和失败路由。 |
+| 审计与验证 | `audit/`、`verification/` | 保留历史 V1 执行证据，以 ITER-V2 验证当前契约，并用通用测试验证安装、引导和原型交接；两者均不随 `init` 安装。 |
+| 临时运行物料 | `.tmp/` | 保存测试工作区、缓存、日志、报告、临时 Git 仓库、打包文件和单次场景脚本，整体忽略且可随时删除。 |
+
+安装到业务项目后，主要目录如下：
+
+```text
+<project-root>/
+  .agents/skills/ai-delivery-*/   # 25 个项目级 Skills
+  .codex/config.toml              # 项目级 Codex Hook 配置
+  .workflow/
+    config/
+      workspace.yaml              # 双仓绑定的唯一权威配置
+      install-manifest.json       # 安装清单
+    tools/
+      bootstrap/                   # 自包含项目识别与自主入口
+      hooks/hook-event.mjs        # Hook 事件记录器
+      state/                       # 自包含正式状态 CLI 与 YAML 运行时
+      evolution/                   # 自包含 Evolution CLI
+      viewer/                      # 可选、只读、可重装的工作流查看器
+    delivery/
+      project.yaml                # 项目描述与旧字段兼容回退
+      workflow-state.yaml         # 正式流程、Gate、累计研发和生产身份
+      artifact-registry.yaml      # 正式物料注册表
+      state-events.jsonl          # 正式状态审计事件
+      standards-baseline.yaml     # 当前规范基线
+      bootstrap/                  # 引导扫描产生的上下文
+      runtime/                    # 被忽略的本地任务、心跳、活动标记与备份
+    control/                      # 可共享任务、Checkpoint、Gate、版本与发布分片
+    standards/                    # 项目规范
+    evolution/                    # 反馈、提案、试验和决策
+    extensions/                   # 已注册项目级扩展版本
+    product/                      # 长期产品基线
+    architecture/                 # 长期架构基线
+    experience/                   # 长期体验基线
+    iterations/                   # 迭代节点交付物
+    releases/                     # 独立发布交付物
+  code/                           # 被外层 Git 忽略的独立代码 Git 仓库
+  AGENTS.md                       # AI 工作说明
+  .gitignore                      # 精确忽略 code/ 与本地 runtime
+  .gitattributes                  # 固定工作流受控文本为 LF
+```
+
+安装器为上述可能为空但必须跨 clone 保留的内容目录，以及 `.workflow/control/` 下的任务、Checkpoint、物料、Gate、版本、发布和事件分片目录创建 `.gitkeep`。这些占位文件属于结构契约；重新克隆后无需再次执行 `init` 即可通过 `doctor`。
+
+## 5. 安装、升级与诊断
+
+### 5.1 前提
+
+- Node.js `>=18`；
+- 目标目录已经存在；
+- 对目标项目目录有写权限；
+- 目标不得是用户主目录、`~/.codex` 或 `~/.agents`；
+- 安装完成后允许重新启动一个 Codex 任务，以刷新项目级 skill 发现和 Hook 信任。
+
+### 5.2 从 npm 仓库安装到当前项目
+
+在目标业务项目根目录执行：
+
+```bash
+npx ai-delivery-workflow@latest init .
+npx ai-delivery-workflow@latest doctor .
+```
+
+这只会写入当前项目，不会安装全局 skill。
+
+`init` 会同时内置正式状态 CLI 和本地工作流物料查看器，不修改业务项目 `package.json`。安装完成后无需安装额外前端依赖，直接在目标项目运行：
+
+```powershell
+.\.workflow\tools\viewer\start.cmd
+```
+
+或：
+
+```powershell
+.\.workflow\tools\viewer\start.ps1
+```
+
+macOS/Linux：
+
+```bash
+sh ./.workflow/tools/viewer/start.sh
+```
+
+服务默认监听 `127.0.0.1:4173` 并打开浏览器。可使用 `--port 4180` 指定端口，使用 `--no-open` 禁止自动打开浏览器。查看器只读取 `.workflow/`，不会修改、批准、迁移或删除正式物料。
+
+### 5.3 从本地源码安装到另一个项目
+
+开发或尚未发布到 npm 时，可直接调用本仓库 CLI：
+
+```powershell
+node E:\work\ai\codex\workflow\bin\ai-delivery.mjs init E:\path\to\target-project
+node E:\work\ai\codex\workflow\bin\ai-delivery.mjs doctor E:\path\to\target-project
+```
+
+也可先在本仓库执行 `npm pack`，再在目标项目使用生成的 `.tgz`：
+
+```powershell
+npx --yes --package E:\path\to\ai-delivery-workflow-0.2.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
+```
+
+`--force` 会把被替换的受管文件备份到 `.workflow/delivery/runtime/backups/<timestamp>/`。它不会授权覆盖冲突的已批准规范正文；规范冲突必须按规范治理流程处理。
+
+当安装器检测到有效安装清单中的包版本发生变化时，会自动备份并升级受管 Skill、Hook、Bootstrap、状态、Evolution 和查看器；产品、架构、体验、迭代、发布、规范及正式状态物料不被替换。升级后仍需执行 `doctor`。
+
+安装器不会把降级当作升级。目标包版本早于已安装版本时默认拒绝；只有用户明确批准降级并审阅备份影响后，才可使用 `--force`。
+
+旧项目中的 `.ai-delivery/` 会在升级时先完整备份，再迁入 `.workflow/config/` 和 `.workflow/tools/`；验证失败时旧目录不会删除。`.workflow/tools/viewer/` 是唯一可选工具，删除后不影响核心工作流，重新执行 `init` 即可恢复。
+
+### 5.5 升级
+
+推荐步骤：
+
+1. 提交或备份业务项目当前改动。
+2. 执行新版 `init --dry-run`。
+3. 审阅 skill、Hook 和模板变化。
+4. 处理规范冲突。
+5. 执行新版 `init`；仅在同版本受管文件冲突且明确采用发行基线时使用 `--force`。
+6. 执行 `doctor`。
+7. 新建 Codex 任务，对 AI 说“继续”；AI 自主调用 Bootstrap 和后续 Skill。
+
+#### 从旧目录布局迁移
+
+早期项目可能把流程状态放在根目录 `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`。
+
+安装器检测到旧布局或新旧布局并存时会停止，不会自动移动文件或选择权威状态。
+
+### 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 inspect [project]` | 否 | 输出机器可读的项目、代码、流程和运行时状态。 |
+| `ai-delivery bootstrap [project]` | 视状态而定 | 初始化空项目或存量项目上下文，或把中断项目路由到恢复。 |
+| `ai-delivery bootstrap [project] --dry-run` | 否 | 预览引导动作。 |
+| `ai-delivery doctor [project]` | 否 | 校验安装清单、关键 skills、Hook 配置和项目文件。 |
+| `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` | 否 | 输出包版本。 |
+
+完全未安装的项目不能依靠项目内 skill 自行引导，因为此时 skill 尚不存在。第一次必须先通过 CLI 执行 `init` 或 `bootstrap`。
+
+### 5.7 工作流物料查看器
+
+查看器是随 `init` 安装的项目内只读系统，主要提供：
+
+- 按当前迭代和 17 个研发节点查看物料数量与进度；
+- 按状态、类型、节点、Git 变更和全文关键字筛选；
+- 展示物料 ID、版本、更新时间、大小、Git 状态和 SHA-256；
+- 从文档路径引用推导上游与下游关系；
+- 识别正文采用的规范 ID；
+- 格式化预览 Markdown、CSV、JSON、YAML、JSONL、TOML、文本和图片；
+- 在窄屏上把详情区切换为抽屉，保留节点、筛选和物料表主流程。
+
+默认只绑定本机回环地址。确需允许局域网访问时可显式传入 `--host`，但必须先评估项目文档的敏感性和终端网络边界。查看器不会提供写接口，也不会读取 `.workflow/` 之外的文件。
+
+完整操作、字段识别、升级和故障处理见[工作流物料查看器使用指南](VIEWER-USER-GUIDE.zh-CN.md)；修改源码、扩展 API 或调整界面前，先阅读[工作流物料查看器维护指南](VIEWER-MAINTENANCE.zh-CN.md)。
+
+## 6. 项目状态识别与自主规划
+
+每次新会话或进入陌生仓库，AI 会先运行项目内只读识别；用户无需执行该命令：
+
+```bash
+node .workflow/tools/bootstrap/bootstrap.mjs inspect
+```
+
+引导器只返回以下五种状态之一：
+
+| 状态 | 含义 | 推荐动作 |
+| --- | --- | --- |
+| `empty-uninitialized` | 无完整工作流，也无代码证据。 | 安装工作流，进入产品发现，引导用户说明问题、用户和成功标准。 |
+| `codebase-uninitialized` | 有代码证据，但无完整工作流。 | 安装并生成草稿代码上下文，由用户校正后进入产品发现。 |
+| `workflow-ready` | 安装完整，无可恢复任务。 | 根据正式产物和 Gate 状态选择下一节点。 |
+| `workflow-interrupted` | 存在活动、中断、阻塞或依赖就绪任务。 | 先读取 `next_action_owner`；仅 `agent` 转到 checkpoint 恢复，`user/external` 只返回问题或等待条件且零写入。 |
+| `workflow-inconsistent` | 安装不完整、状态损坏、身份冲突或依赖缺失。 | 停止推进，修复一致性问题。 |
+
+`bootstrap` 为新项目生成的文件全部是 `draft`：
+
+```text
+.workflow/delivery/bootstrap/
+  latest.yaml
+  runs/<bootstrap-run-id>/
+    project-state-report.yaml
+    repository-baseline.yaml
+    codebase-inventory.csv
+    context-index.csv
+    adoption-assessment.md
+    bootstrap-plan.yaml
+```
+
+这些文件描述“仓库里观察到了什么”，不代表“产品应该做什么”。存量代码不能绕过产品发现直接进入开发。
+
+扫描会忽略 Git 元数据、工作流自身目录、依赖缓存、构建输出、覆盖率、虚拟环境和 vendor 目录，并从上下文产物中排除密钥及明显敏感文件。
+
+## 7. 完整研发流程
+
+```mermaid
+flowchart LR
+  B["Bootstrap"] --> D["产品发现"]
+  D --> P["产品定义"]
+  P --> A1["初始架构"]
+  A1 --> LF["可运行低保真原型 / UX-LF"]
+  A1 --> PLAT["平台准备"]
+  LF --> VS["视觉系统与框架 / UX-VS"]
+  VS --> UI["可运行正式 UI / UX-UI"]
+  UI --> PR["产品与原型统一核对"]
+  PR --> A2["架构校准"]
+  A2 --> PLAN["迭代规划"]
+  PLAN --> TEST["测试设计"]
+  TEST --> DEV["开发实现"]
+  DEV --> REVIEW["独立变更审查"]
+  REVIEW --> VERIFY["候选验证"]
+  PLAT --> VERIFY
+  VERIFY --> RELEASE["发布准备"]
+  RELEASE --> APPROVE["生产审批"]
+  APPROVE --> DEPLOY["生产部署"]
+  DEPLOY --> PROD["生产验证"]
+  PROD --> ARCHIVE["版本归档"]
+```
+
+### 7.1 节点流转物料
+
+| 序号 | 节点 / skill | 主要输入 | 必需过程 | 主要输出 | 放行方式 |
+| ---: | --- | --- | --- | --- | --- |
+| 0 | 引导 `$ai-delivery-bootstrap` | 仓库、安装和运行时状态 | 只读扫描、状态分类、敏感文件排除、恢复判断 | 项目状态报告、代码清单、上下文索引、引导计划 | 状态契约 |
+| 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` |
+| 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、垂直切片、来源/原型/体验变更追踪、依赖、迭代计划 | 下游契约验证 |
+| 8 | 测试设计 `$ai-delivery-design-tests` | 迭代切片、架构、ready UI handoff、交互/组件状态、体验变更 | 按 `experience_change_id` 设计行为、视觉回归、响应式、无障碍、数据、环境和质量门禁 | 测试策略、迭代测试契约、体验变更测试追踪、质量门禁、原型测试收据 | 下游契约验证 |
+| 9 | 开发实现 `$ai-delivery-develop-iteration` | 切片、架构、ready UI handoff、体验变更、公开测试契约 | 按结构化变更拆工作包和 `create/update/remove/migrate/no-code` 动作；逐包 TDD；组装候选 | 技术工作包、任务-体验变更追踪、代码、TDD 证据、候选清单 | 工作包验证 |
+| 10 | 变更审查 `$ai-delivery-review-change` | 工作包变更、需求、架构、规范和测试证据 | 由独立上下文审查行为、架构、质量、安全和测试 | 审查报告、发现清单、审查决策 | 阻断问题关闭 |
+| 11 | 候选验证 `$ai-delivery-verify-candidate` | 不可变候选、平台环境、产品、架构、原型和测试契约 | 动态拆风险测试包，独立执行功能、集成、端到端及非功能验证 | 测试工作包、覆盖矩阵、证据、缺陷和候选决策 | 独立验证通过 |
+| 12 | 发布准备 `$ai-delivery-prepare-release` | 已验证候选、完整变更集 | 冻结版本，核对所有需求、架构、代码、镜像、配置、数据和运维变更，验证回滚 | 发布清单、上线交付清单、变更覆盖、回滚就绪说明 | 进入生产审批 |
+| 13 | 生产审批 | 精确发布 ID、目标环境、制品 digest 和计划 | 人工核对本次迭代的完整部署包 | `approval.yaml` | 人工批准 |
+| 14 | 生产部署 `$ai-delivery-deploy-production` | 未变化的已批准发布包 | 独立执行部署、记录每步结果，不混入开发或测试职责 | 部署计划、部署记录、部署证据、环境台账更新 | 技术执行结果 |
+| 15 | 生产验证 `$ai-delivery-verify-production` | 部署记录、发布清单、生产验证计划 | 独立验证技术和业务信号，决定发布、回滚或失败路由 | 生产验证报告、烟雾证据、发布决策 | `released` 或失败路由 |
+| 16 | 版本归档 `$ai-delivery-checkpoint-task` | `released` 或 `abandoned` 版本及全部关闭任务 | 核对证据，复制任务、checkpoint、事件和恢复摘要，写轻量索引 | 版本清单、版本索引、任务索引和归档详情 | 归档契约 |
+
+### 7.2 为什么先架构再体验
+
+产品定义中的“渠道与终端范围矩阵”和“功能-终端关联”先明确要设计哪些终端。初始架构随后给出技术能力、接口边界、安全、部署和性能约束，体验设计据此产出可实现的原型。原型完成后再做架构校准，吸收页面状态和交互产生的真实技术影响。
+
+因此顺序是：
+
+```text
+产品定义 -> 初始架构 -> 体验设计 -> 架构校准
+```
+
+### 7.3 领域语言
+
+本流程不引入完整 DDD 战术建模。产品手册必须维护领域术语和统一业务语言，产品、架构、体验、测试、代码和上线文档使用同一组规范术语。术语变化属于产品基线变化，必须做下游影响分析。
+
+## 8. 人工 Gate
+
+当前必须由人作出决定的项目：
+
+| Gate | 人工决定 | AI 在决定前后做什么 |
+| --- | --- | --- |
+| Discovery Gate A | 问题、目标用户、边界和成功信号是否可进入产品定义 | AI 先整理发现基线；批准后冻结版本。 |
+| Product Gate B | 产品手册、终端、功能、故事、验收标准、路线图是否完整 | AI 校验全部强制物料；批准后形成产品基线。 |
+| 重大架构决策 | 高影响、难逆转的技术决策是否采用 | AI 给出选项、证据、影响和决策记录。 |
+| 原型工具选择 | 每个原型集成员使用哪个实际可用工具 | AI 先列候选工具和适配理由，人在开始创作前选择。 |
+| `UX-LF` | 可运行低保真原型的布局、交互方式和细节是否通过 | AI 必须提供可实际操作、会产生状态变化的原型，并记录每轮评论和调整。 |
+| `UX-VS` | 视觉方向、字体、色彩、Token、组件状态和 UI 框架选择是否通过 | AI 根据产品性质与技术架构给出候选和证据，人在正式 UI 制作前确认。 |
+| `UX-UI` | 应用选定系统后的可运行正式 UI 是否通过 | AI 保持已确认交互，记录所有修订，直到最新轮次批准且评论全部终结。 |
+| 生产部署审批 | 是否允许把精确 package hash 部署到指定环境 | AI 必须先列出完整变更和回滚条件。 |
+| 规范治理 | 新增、修改、废弃或例外是否生效 | AI 起草版本化规范，批准后注册并固定版本。 |
+
+除上述 Gate 外，中间交付默认由下游按契约验证，不要求额外人工确认。
+
+## 9. 原型设计与上下游交接
+
+### 9.1 原型成员和工具
+
+一个产品可有多个终端或原型成员。每个成员在开始设计前独立维护：
+
+- `prototype-tool-candidates.csv`：Pencil、Figma、项目内 UI/UX skill 或其他可用工具；
+- `prototype-tool-selection.yaml`：人工选择、版本、能力和限制；
+- `prototype-manifest.yaml` / `prototype-set.yaml`：原型成员身份和版本。
+
+AI 必须根据当前项目、终端、交互复杂度、协作需求和可用工具推荐，不得假设所有原型都在同一个工具或文件中。
+
+### 9.2 页面编号
+
+页面使用稳定编号：
+
+```text
+P01-页面名称A
+P02-页面名称B
+P01-01-页面名称1
+P01-02-页面名称2
+```
+
+规则：
+
+- 主页面编号为 `P01`、`P02`；
+- 子页面继承主页面编号，如 `P01-01`；
+- 页面显示名称可以调整，但稳定 ID 不复用；
+- 功能、终端、页面、状态、画布、文件和具体元素使用显式关系表追踪。
+
+### 9.3 画布和文件
+
+- 同一主页面及其派生子页面可以放在同一画布族；
+- 无关主页面应拆为独立画布或原型文件；
+- `canvas-catalog.csv` 管理画布；
+- `canvas-pages.csv` 管理画布与页面关系；
+- `prototype-files.csv` 管理原型源文件；
+- `prototype-file-terminals.csv` 管理文件与终端关系；
+- 不允许用“全部页面放在一个无限画布”替代管理。
+
+### 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` 才能冻结体验基线。
+
+只有确实没有视觉界面和用户操作的终端才可把视觉 Gate 标为 `not-applicable`，并必须给出产品终端证据，不能对交互页面使用 `contract-only` 绕过人工确认。
+
+### 9.5 交接身份
+
+`ui-handoff.yaml` 是唯一的下游就绪入口。它绑定三道体验 Gate、产品核对、交互契约、设计 Token、UI 框架、组件状态、页面组件映射、体验/需求变更和原型集 checksum。架构校准、规划、测试设计、开发和候选验证必须携带同一组 identity/checksum；下游不得直接修改冻结体验物料，也不得通过视觉比对猜测新增或修改。
+
+## 10. 迭代规划、任务拆分和 TDD
+
+### 10.1 先规划业务切片
+
+迭代规划按业务结果排序，不先拆“前端任务”和“服务端任务”。它输出可独立验证的垂直切片、来源、依赖和版本顺序。
+
+优先级至少考虑：
+
+- 业务价值；
+- 紧迫度；
+- 风险降低；
+- 学习价值；
+- 前置依赖；
+- 版本准入和退出条件。
+
+### 10.2 开发时再拆技术工作包
+
+进入开发后，AI 根据切片、架构、终端、原型和测试接缝动态拆分技术任务。例如某个版本可能需要 Web、API、数据迁移和构建能力，也可能只有一个脚本任务。技术栈由最终架构下发。
+
+每个工作包必须声明：
+
+- 稳定任务 ID、目标和范围；
+- 所需能力角色；
+- 依赖和可并行关系；
+- 允许修改的文件或模块；
+- 技术栈和执行命令；
+- 原型页面、状态和元素引用；
+- `experience_change_id`、变更类型和 `create/update/remove/migrate/no-code` 实施动作；
+- 公开测试接缝；
+- 预期交付物和完成证据。
+
+### 10.3 TDD
+
+开发工作包采用 Red-Green-Refactor：
+
+1. 从公开测试契约选择本工作包义务；
+2. 先写或运行会失败的测试，保存 Red 证据；
+3. 实现最小行为使测试通过，保存 Green 证据；
+4. 在测试保护下重构；
+5. 运行工作包范围和必要回归；
+6. 交给独立变更审查。
+
+开发中的 TDD 不替代独立测试。开发者负责证明实现满足公开契约，候选验证节点负责以独立上下文验证整个不可变候选。
+
+## 11. Git、候选版本和回滚
+
+推荐分支模型：
+
+| Git 对象 | 作用 |
+| --- | --- |
+| `main` | 受保护、可发布的集成基线。 |
+| 迭代分支 | 汇总一个迭代版本的已审查工作包。 |
+| 工作包分支 / worktree | 隔离单个技术任务，缩小 AI 上下文和冲突范围。 |
+| hotfix 分支 | 修复已存在的生产行为问题。 |
+| 不可变 release Tag | 绑定已冻结发布版本。 |
+
+原则：
+
+- 工作包合并前必须通过独立变更审查；
+- 同一任务的多个 worktree 指向同一个主 `state_root`；
+- 候选失败、发布记录、Tag 和部署记录都保留，不覆盖历史；
+- 生产转换串行化，同一时间只推进一个生产发布；
+- Git 分支不承担生产回滚。
+
+生产回滚使用上一个稳定镜像 digest 或发布清单中声明的等价不可变制品。回滚是一次新的部署状态转换，必须有执行和验证记录。没有历史稳定镜像时，发布准备必须明确替代策略，如停止服务并移除首版部署，不能虚构镜像回滚能力。
+
+## 12. 发布、上线交付清单和生产部署
+
+每次生产部署只对应一个迭代版本。发布准备必须列出本次所有实际变更，包括但不限于：
+
+- 产品需求、功能、故事和验收标准；
+- 终端、页面、原型和交互状态；
+- 应用、技术、数据、安全和部署架构；
+- 源码、依赖、构建产物和数据库变更；
+- Docker/OCI 镜像及 digest；
+- 环境变量、配置文件、密钥引用和开关；
+- 基础设施、权限、网络、监控和告警；
+- 测试报告、已知限制和风险接受；
+- 发布说明、操作步骤、验证步骤和回滚步骤。
+
+`delivery-items.csv` 按实际情况记录交付物。不存在 Docker 镜像时应标记不适用并说明实际制品，不能为了模板完整而虚构镜像。
+
+生产审批绑定：
+
+- 精确迭代和 release ID；
+- 精确目标环境；
+- 精确 package hash / image digest；
+- 完整交付清单；
+- 部署和验证计划；
+- 回滚制品及条件。
+
+审批后任一绑定项变化，原审批失效，必须重新准备和审批。
+
+生产部署始终是独立节点。候选测试通过不等于已部署，部署完成也不等于已发布；只有生产验证输出 `released`，迭代才可关闭和归档。
+
+## 13. Checkpoint、Hook 和中断恢复
+
+### 13.1 两类受控状态
+
+- 正式状态：`.workflow/delivery/workflow-state.yaml`、`artifact-registry.yaml` 和 `state-events.jsonl`，唯一写入口是 `.workflow/tools/state/state.mjs`；
+- runtime 状态：`.workflow/delivery/runtime/` 中的任务快照、checkpoint、恢复摘要、活动标记和版本归档，唯一写入口是 `task-state.mjs`。
+
+Hook 只记录生命周期和心跳，不能证明产物已完成，也不能修改任一受控状态。禁止直接编辑受控文件；脚本失败时必须处理原因，不得手工绕过。
+
+### 13.2 正式流程、物料和 Gate
+
+```bash
+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`，不能原地覆盖。
+
+`workflow-state.yaml` schema 2 包含独立的 `development_state` 与 `release_state`。研发由 `iteration-started` 建立，发布仅在用户明确请求后由 `release-started` 建立；两个状态域分别维护 scope ID、局部 revision、节点、Gate、节点尝试和选定物料，因此发布期间仍可继续下一累计版本研发。顶层 revision 只负责审计流串行化，任何一个状态域都不得重置另一个。
+
+状态 CLI 根据流程图元数据校验前置依赖，不采用简单的相邻编号规则。平台准备可与体验设计并行；产品和体验可因原型校正带原因重开；后续迭代可用已登记的成功冻结基线满足未受影响的前置条件。节点完成证据必须处于允许的成功状态，并完成当前节点尝试的强制 Gate。生产审批 Gate ID 固定为 `PRODUCTION-APPROVAL`，不能标记为 `not-required`。
+
+节点交接、生产审批、部署、版本归档和中断恢复后都必须运行 `verify`。完整命令、revision 冲突恢复和生产规则见[正式状态 CLI 使用指南](STATE-CLI-USER-GUIDE.zh-CN.md)。
+
+### 13.3 任务登记
+
+在执行一个已知任务组前，先把整组任务登记为 `queued`，包含 `sequence` 和 `depends_on`。这样，10 个任务完成 5 个后中断，新会话可以计算第 6 个任务，而不是重新执行或依赖聊天记忆。
+
+安装后的脚本路径是：
+
+```text
+.agents/skills/ai-delivery-checkpoint-task/scripts/task-state.mjs
+```
+
+典型命令：
+
+```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 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 "恢复迭代并选择下一任务"
+```
+
+### 13.4 恢复顺序
+
+新会话：
+
+1. `$ai-delivery-bootstrap` 或 `inspect` 识别项目；
+2. 读取 `runtime.next_action_owner`、`next_action` 和 `recommended_task_id`；
+3. 若责任方为 `user`，原样提出记录的问题并停止，期间不执行 recover、activate、checkpoint、正式状态、物料或 Git 写入；
+4. 若责任方为 `external`，只报告等待条件并停止；
+5. 仅当责任方为 `agent` 时执行 `recover --iteration-id <id>`，并对照分支、worktree、脏文件、产物、外部系统和证据校准；
+6. 激活推荐任务，从记录的幂等 `next_action` 继续。用户或外部输入到达后，先通过 CLI 同时提供 `--next-action-owner agent` 和新的幂等 `--next-action`。
+
+推荐规则：
+
+1. 优先已有 `preparing`、`running`、`checkpointed`、`pending-review`、`blocked` 或 `interrupted` 任务；
+2. 否则选择依赖均为 `completed` 的 `queued` 任务；
+3. 按 `sequence`，再按 `task_id` 排序；
+4. 无可执行任务时返回 `null` 并列出等待依赖。
+
+`next_action_owner` 固定为 `agent | user | external`，旧任务默认为 `agent`。它是防止重启时误写状态的执行边界，不是提示性备注。任务 evidence 采用有序集合语义，重复提交同一引用不会追加重复项。
+
+生产和外部动作恢复前必须重新读取真实状态和授权，禁止自动重放。
+
+### 13.5 归档
+
+```bash
+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`。
+
+归档条件：
+
+- 版本为 `released` 或明确 `abandoned`；
+- `released` 版本有 release ID 和生产验证证据；
+- 该版本所有任务均已关闭；
+- 不存在 queued、running、blocked 或 interrupted 等未关闭任务。
+
+默认恢复不加载已关闭任务详情；归档后恢复命令不扫描归档目录，从而减少上下文占用。审计归档时直接读取 `.workflow/control/archives/versions/<version-id>/`。
+
+## 14. 规范沉淀
+
+对话中出现可复用规则时，调用 `$ai-delivery-manage-standards`：
+
+1. 判断它是一次性决定还是持续规范；
+2. 起草稳定 ID、版本、适用范围、规则、理由和验证方式；
+3. 由人批准新增、修改、废弃或例外；
+4. 写入 `.workflow/standards/` 并登记 `.workflow/standards/index.yaml`；
+5. 当前任务把采用版本固定到 `.workflow/delivery/standards-baseline.yaml`；
+6. 后续 AI 在执行前解析并应用相应规范。
+
+规范冲突不能由安装器或下游节点静默覆盖。批准基线变化后，应评估对在途产物的影响。
+
+默认安装的规范包括：`STD-DOC-LANG-001`（默认中文）、`STD-ARTIFACT-PATH-001`（工作流文档路径）和 `STD-TEST-LOCATION-001`（应用测试遵循代码仓库原生约定）。
+
+### 14.1 项目级工作流自进化
+
+明确的用户意见由 `$ai-delivery-evolve-workflow` 自动记录为脱敏反馈，并返回 `FDB-*`。重复失败、返工和 Gate 驳回可以作为客观信号；单次 AI 推测只允许保存为 `ai-observation`，不能单独形成提案。
+
+自进化只在任务完成、版本收尾或显式 review 时评估：
+
+```text
+observed → proposed → trial → active
+                       ├→ disabled / rolled-back
+                       └→ rejected / superseded / expired
+```
+
+低风险非阻断扩展可自动试运行，并在三次适用执行或一个完整迭代后按指标自动启用。改变路由、模板和校验行为属于中风险；脚本、阻断、Git、部署、安全、权限和外部系统属于高风险。中高风险必须取得绑定扩展版本与 SHA-256 的明确人工批准。
+
+```bash
+node .workflow/tools/evolution/evolve.mjs inspect
+node .workflow/tools/evolution/evolve.mjs evaluate --safe-point task
+node .workflow/tools/evolution/evolve.mjs verify
+```
+
+原始事件和 staging 位于被忽略的 `.workflow/delivery/runtime/evolution/`；脱敏反馈、提案、实验、决策和已注册扩展纳入工作流 Git。扩展不得修改受管 Skill、状态 CLI、Hook、人工 Gate 或项目规范。详见[自进化使用指南](EVOLUTION-USER-GUIDE.zh-CN.md)。
+
+## 15. 25 个 Skills 如何使用
+
+### 15.1 主流程 skills
+
+| Skill | 调用时机 |
+| --- | --- |
+| `$ai-delivery-bootstrap` | 新会话、陌生仓库、首次引导、中断或状态不明。 |
+| `$ai-delivery-define-product` | 新产品、重要需求、产品范围或术语变化。 |
+| `$ai-delivery-design-architecture` | 产品基线批准后、体验完成后校准，或架构约束变化。 |
+| `$ai-delivery-design-experience` | 初始架构后，依次完成可运行低保真、视觉系统、正式 UI、调整记录和产品统一核对。 |
+| `$ai-delivery-prepare-platform` | 初始架构后并行准备构建、环境、配置和发布平台。 |
+| `$ai-delivery-plan-iteration` | 架构校准后规划或调整迭代优先级与顺序。 |
+| `$ai-delivery-design-tests` | 开发前设计测试策略、原型可测性和公开测试契约。 |
+| `$ai-delivery-develop-iteration` | 对一个已计划垂直切片进行技术拆分和候选组装。 |
+| `$ai-delivery-execute-work-package` | 执行一个边界明确的技术工作包并实施 TDD。 |
+| `$ai-delivery-review-change` | 工作包合并前或修复后做独立变更审查。 |
+| `$ai-delivery-verify-candidate` | 开发候选与平台环境汇合后进行独立验证。 |
+| `$ai-delivery-execute-test` | 执行一个独立风险测试工作包。 |
+| `$ai-delivery-close-version` | 迭代候选验证通过后冻结计划版本、推进累计研发线并归档任务；不发布。 |
+| `$ai-delivery-orchestrate-release` | 用户明确提出发布后选择截止版本并编排 R00 至 R10。 |
+| `$ai-delivery-assemble-release` | 计算连续版本闭包、校验不可变 Tag 与 Git 血缘并汇总发布物料。 |
+| `$ai-delivery-prepare-release` | R05 发布验证通过后在 R06 准备完整上线清单；不审批、不部署。 |
+| `$ai-delivery-deploy-production` | 精确发布包获人工审批后独立执行生产部署。 |
+| `$ai-delivery-verify-production` | 每次生产部署或回滚后独立验证。 |
+
+### 15.2 横切 skills
+
+| Skill | 调用时机 |
+| --- | --- |
+| `$ai-delivery-orchestrate` | 协调完整流程、决定下一节点、处理变更影响和状态报告。 |
+| `$ai-delivery-checkpoint-task` | 任务前后、里程碑、中断、恢复和版本归档。 |
+| `$ai-delivery-validate-artifacts` | 每次节点流转前、产物变化后或状态不一致时。 |
+| `$ai-delivery-triage-failure` | 测试、环境、需求、架构、发布或生产失败时确定回流节点。 |
+| `$ai-delivery-manage-git` | 创建、校验、合并、冻结、标记和清理 Git 状态。 |
+| `$ai-delivery-manage-standards` | 对话形成规范、规范变化、例外或冲突时。 |
+| `$ai-delivery-evolve-workflow` | 用户提出工作流意见、重复问题达到门槛、任务或版本到达安全点、扩展需要批准或回退时。 |
+
+用户不需要记住或手工串起任何 specialist Skill 和工作流命令。`init` 完成后，在项目根目录开启新的 AI 会话，使用普通自然语言即可：
+
+```text
+开始
+继续这个项目
+现在做到哪一步了？
+我想做一个团队值班交接系统
+我要发布已经完成的版本
+```
+
+AI 必须在后台自主选择 `$ai-delivery-bootstrap`、编排、checkpoint、专业节点和发布 Skill，并自行运行项目内 CLI。用户只回答业务问题、审阅交付物、决定人工 Gate 和批准外部副作用；AI 不得要求用户复制命令、选择 Skill 或记忆流程节点。安装后的只读入口是 `node .workflow/tools/bootstrap/bootstrap.mjs inspect`，它不依赖全局 `ai-delivery` 命令。若只读结果表明 `next_action_owner: user`，AI 只能返回已记录的问题，重复说“继续”也不得增加 attempt、revision、evidence 或 checkpoint。
+
+## 16. 常见使用场景
+
+### 16.1 空目录创建新产品
+
+```bash
+npx ai-delivery-workflow@latest bootstrap .
+npx ai-delivery-workflow@latest doctor .
+```
+
+新建 Codex 任务后：
+
+```text
+调用 $ai-delivery-bootstrap 读取引导结果，从产品发现开始。
+一次只向我确认一个需要人工决定的问题。
+```
+
+### 16.2 已有代码首次接入
+
+```bash
+npx ai-delivery-workflow@latest inspect .
+npx ai-delivery-workflow@latest bootstrap .
+```
+
+先审阅：
+
+- `.workflow/delivery/bootstrap/latest.yaml`；
+- 本次 run 的 `adoption-assessment.md`；
+- `repository-baseline.yaml`；
+- `codebase-inventory.csv`；
+- `context-index.csv`。
+
+让用户纠正“观察事实”后，仍从产品发现建立“目标意图”。
+
+### 16.3 已安装项目继续执行
+
+```text
+调用 $ai-delivery-bootstrap 和 $ai-delivery-orchestrate。
+从 checkpoint 的 recommended_task_id 继续，不根据聊天记录猜测。
+```
+
+### 16.4 完成一个计划版本
+
+顺序固定为：
+
+```text
+候选验证通过
+-> 版本收尾和不可变 version-ready Tag
+-> line/<product-id> 快进
+-> release-ready
+-> 整个计划版本任务归档
+-> 停止并等待下一版本或用户发布请求
+```
+
+### 16.5 独立发布多个已完成版本
+
+用户明确选择发布截止版本后：
+
+```text
+R00 发布请求
+-> R01 版本选择和连续闭包
+-> R02 发布资格
+-> R03 物料整合
+-> R04 发布候选
+-> R05 发布验证
+-> R06 发布准备
+-> R07 人工生产审批
+-> R08 独立生产部署
+-> R09 独立生产验证
+-> R10 发布归档
+```
+
+例如生产在 `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` 仅保留项目描述和旧项目兼容字段。
+
+版本任务归档写入 `.workflow/control/archives/versions/<version-id>/`，保存版本 Manifest、任务快照和共享 checkpoint。只有可携带归档完整写入后，脚本才移除 `.workflow/control/tasks/` 与 `.workflow/control/checkpoints/` 中该版本的活动分片。普通恢复以及 `--include-closed` 都只扫描活动集合；历史详情必须通过显式审计读取归档。`.workflow/delivery/runtime/archive/` 仅是可丢弃的本地详细副本。
+
+## 17. AI 新会话读取顺序
+
+后续 AI 进入项目时，应按以下顺序加载最少但足够的上下文：
+
+1. 根 `AGENTS.md`；
+2. 本手册和文件参考；
+3. `.workflow/delivery/project.yaml`；
+4. `.workflow/delivery/workflow-state.yaml`；
+5. `.workflow/delivery/artifact-registry.yaml`；
+6. `.workflow/standards/index.yaml` 和 `.workflow/delivery/standards-baseline.yaml` 指向的规范；
+7. `$ai-delivery-bootstrap` 的只读识别结果；
+8. `recover` 返回的当前推荐任务及其 `resume.md`；
+9. 推荐任务声明的精确输入产物；
+10. 只有在审计时才加载已关闭或已归档任务详情。
+
+不要先遍历全部审计物料、全部历史归档或全部聊天记录。正式状态、推荐任务和输入引用足以决定下一步。
+
+## 18. 全流程审计物料
+
+`audit/` 使用最小前后端系统 TaskLite 保存两类证据。它只属于本维护仓库，不随 `init` 安装到业务项目：
+
+- Node.js HTTP 服务；
+- 原生浏览器 Web 前端；
+- 任务创建和列表 API；
+- 根目录编号 `00` 至 `16` 是历史 V1：完成了当时版本的产品、架构、体验、规划、测试、TDD、审查、候选验证、发布、部署、生产验证和归档；
+- `audit/ITER-V2/` 是当前契约示例：在 V1 不可变基线上交付“完成任务”，补齐最新原型管理、上下游接收凭据和当前验证规则；
+- `audit/RELEASE-TRAIN-DEMO/` 演示五个严格递进版本、生产停在 VER-02、统一发布至 VER-05，以及同版本重新发布。
+- `audit/AUTONOMOUS-GUIDANCE/` 保存零命令引导黑盒证据；远程 commit/tree 与四个关键 Git blob 的路径归属可离线复算，`fork_turns`、输入边界和未要求命令等平台行为在没有可信平台签名时明确保持 `unattested`。
+
+历史 V1 只能证明当时契约下的执行记录，不能单独证明当前 25 个 Skills 的完整符合性。当前规范来源始终是 `skills/**/SKILL.md`、对应 `references/` 和 `assets/`。
+
+推荐阅读：
+
+1. [../audit/README.md](../audit/README.md)：示例入口和运行方式；
+2. [../audit/FILE-GUIDE.zh-CN.md](../audit/FILE-GUIDE.zh-CN.md)：`audit/` 中每个文件的用途；
+3. [../audit/REVIEW-CHECKLIST.md](../audit/REVIEW-CHECKLIST.md)：人工审阅清单；
+4. [../audit/V1-CONTRACT-COMPATIBILITY.md](../audit/V1-CONTRACT-COMPATIBILITY.md)：历史 V1 与当前契约的差异；
+5. `audit/00-governance/material-index.csv`：历史 V1 的主要流转物料；
+6. 按根目录 `01` 至 `16` 审阅历史 V1；
+7. 按 `audit/ITER-V2/` 的编号顺序审阅当前契约 V2；
+8. 最后运行 `npm run audit:verify`。
+
+自主引导专项校验也可单独运行 `node verification/audit/verify-autonomous-guidance.mjs`。该命令验证仓库快照、摘要、Git blob OID 和任务语义，但不会把维护者记录的平台运行声明当作独立认证事实。
+
+审计目录中的 V1 已归档，不应原地修改。流程契约演进和新功能通过新的迭代版本及产物版本体现。
+
+## 19. 本仓库开发与验证
+
+本工作流维护仓库的通用自动化测试、专项验证器和长期测试辅助程序必须位于根 `verification/` 并纳入 Git；`audit/` 保存可审阅流程物料和历史快照，不保存维护测试入口；一切可丢弃运行物写入整体忽略的 `.tmp/`。这些维护仓库目录不写入安装目标模板，也不替业务代码仓库决定测试目录或版本控制策略。
+
+安装依赖：
+
+```bash
+npm install
+```
+
+单独校验全部 25 个项目级 Skill：
+
+```bash
+npm run skills:validate
+```
+
+该命令执行 `bin/validate-skills.mjs`，由 `lib/skill-validator.mjs` 提供校验逻辑，并复用项目已锁定的 Node.js `yaml` 依赖，不要求 Python 或 `PyYAML`。这两个文件随 npm 包发布，保证维护命令在打包后仍可执行，但 `init` 不会把它们复制到业务项目。校验范围包括：
+
+1. `skills/` 必须恰好包含 25 个 Skill 目录；
+2. 每个 `SKILL.md` 必须存在，并具有可解析的 YAML frontmatter；
+3. frontmatter 的字段、`name`、`description`、hyphen-case、长度和目录名一致性必须符合 Skill 契约；
+4. 每个 `agents/openai.yaml` 必须存在并提供非空的 `display_name`、`short_description` 和 `default_prompt`，默认提示必须引用对应 `$skill-name`；
+5. `PROJECT-MANUAL.zh-CN.md` 和 `FILE-REFERENCE.zh-CN.md` 必须覆盖每个 Skill。
+
+校验失败时命令逐条输出文件和原因，并返回非零退出码。应修复 Skill 或文档后重新执行，不得跳过校验，也不需要为此安装全局 Python 依赖。`verification/skill-validation.test.mjs` 还使用无效 fixture 证明校验器确实能够拒绝错误输入，避免只对当前文件做恒真检查。
+
+执行自动化测试：
+
+```bash
+npm test
+```
+
+`npm test` 会自动包含 `verification/skill-validation.test.mjs`；`npm run skills:validate` 用于需要快速、独立检查 Skill 集合的场景。两者都只属于当前工作流维护仓库，不会复制到安装后的业务项目。
+
+执行审计物料一致性校验：
+
+```bash
+npm run audit:verify
+```
+
+检查 npm 发布内容：
+
+```bash
+npm pack --dry-run
+```
+
+skill 自身还应使用 skill 校验器检查 frontmatter、命名和引用；YAML 产物应使用结构化解析器逐个解析，不应用字符串匹配替代语法校验。
+
+## 20. 故障排查
+
+| 现象 | 原因与处理 |
+| --- | --- |
+| 新会话找不到 `$ai-delivery-*` | 确认 `.agents/skills/` 存在，运行 `doctor`，然后重新启动 Codex 任务。 |
+| `init` 报 managed file conflict | 先运行 `--dry-run` 审阅；确认替换后用 `--force`，备份位于 `.workflow/delivery/runtime/backups/`。 |
+| 规范正文冲突 | 不要强制覆盖；调用规范治理流程创建新版本或解决冲突。 |
+| `workflow-inconsistent` | 查看 `inspect` 的 errors、missing files 和依赖问题，修复后再编排。 |
+| 中断后不知道从哪继续 | 先运行只读 Bootstrap inspect。仅当 `next_action_owner: agent` 时运行 `recover --iteration-id <id>` 并读取 `recommended_task_id`；`user/external` 不得 recover。 |
+| 后续任务无法 activate | 其 `depends_on` 任务缺失或未处于 `completed`；修复正式计划和运行时状态。 |
+| Hook 有事件但节点没完成 | 正常现象；Hook 只是审计和心跳，必须由任务快照和正式产物证明完成。 |
+| 发布审批后制品或配置变化 | 原审批失效，重新执行发布准备和生产审批。 |
+| 候选验证失败 | 调用 `$ai-delivery-triage-failure`，把证据送回真正拥有问题的产品、体验、架构、平台、开发或测试设计节点。 |
+| 生产需要回滚 | 部署上一个稳定镜像 digest，再独立执行生产验证；不要创建“回滚分支”。 |
+| `.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 项扫描上限。 |
+
+## 21. 维护规则
+
+- 新增或删除 skill 时，同步更新本手册、第 15 节和文件参考；
+- 修改 CLI 时，同步更新第 5 节；
+- 修改主流程或 Gate 时，同步更新第 7、8 节和 `workflow-model.md`；
+- 修改原型契约时，同步更新第 9 节和原型交接测试；
+- 修改 checkpoint 命令或状态时，同步更新第 13 节及恢复示例；
+- 修改 npm 发布文件时，运行 `npm pack --dry-run`；
+- 新文档默认中文；
+- 已批准、冻结、发布和 `audit/` 中已归档版本不原地重写。
+
+本手册说明“如何使用和维护整个系统”；逐文件职责见 [FILE-REFERENCE.zh-CN.md](FILE-REFERENCE.zh-CN.md)。