ai-delivery-workflow 0.6.0 → 0.7.1

package/docs/CLI-PARAMETER-REFERENCE.zh-CN.md

@@ -58,6 +58,7 @@ npx ai-delivery-workflow@0.4.0 doctor .
 | `repair` | 追加独立的前向归档失效事务；原归档证据保持逐字节不变。 | 视参数而定 |
 | `inspect` | 只读识别工作区、两套 Git、安装完整性、正式状态和任务恢复建议。 | 否 |
 | `bootstrap` | 根据只读检查决定初始化缺失工作流、恢复 Agent 责任任务或停在用户/外部输入边界。 | 视路由而定 |
+| `node .workflow/tools/bootstrap/bootstrap.mjs project-index` | 从代码仓库 `docs/CODEBASE_INDEX.md` 生成工作流仓库内的 `codebase-index.yaml` 派生投影，并记录源文件 checksum。 | 是；输出路径必须在代码仓库之外 |
 | `doctor` | 校验受管文件 checksum、Skill、Hook、CLI、Workflow Manager、必需目录和持久项目配置；排除本地 runtime。 | 否 |
 | `codegraph setup` | 对权威代码仓关闭 CodeGraph telemetry、按当前 `CODEGRAPH_DIR` 登记本地 ignore 并显式初始化索引；不安装 CLI 或全局 MCP。 | 是；`--dry-run` 时否 |
 | `codegraph sync` | 增量同步已有 CodeGraph 索引并重新验证索引目标。 | 是；`--dry-run` 时否 |

package/docs/FILE-REFERENCE.zh-CN.md

@@ -79,7 +79,7 @@
 | `lib/mock-system.mjs` | Microcks 项目适配器；固定镜像版本与 digest，管理并在健康失败时清理 loopback 易失容器，隔离 `external-dependencies.yaml` 与 `product-backends.yaml`，校验 OpenAPI/AsyncAPI operation、channel、具名 scenario 与 dispatcher 输入，并通过 multipart 本地 API 同步合同。 |
 | `lib/mock-scenario-pack.mjs` | Mock Scenario Pack 冻结器；绑定 Prototype revision、全部 Review Scene 唯一映射、受管 UI 实际导出物及其协议/场景 inventory、合同和脱敏证据 checksum，执行人工 candidate checksum 确认并拒绝覆盖不可变 Pack。 |
 | `lib/project-repair.mjs` | 归档完整性前向修复器；校验人工 actor、原因和证据，追加 checksum 链式失效事务并保留原归档字节。 |
-| `lib/project-bootstrap.mjs` | 只读扫描仓库并分类五种项目状态；识别代码、技术、Git、正式工作流和 runtime；为新接入项目生成草稿基线、文件清单、上下文索引、接入评估和引导计划；中断项目直接路由 checkpoint。 |
+| `lib/project-bootstrap.mjs` | 只读扫描仓库并分类五种项目状态；识别代码、技术、Git、正式工作流和 runtime；为新接入项目生成草稿基线、文件清单、上下文索引、接入评估和引导计划；从代码仓库 `docs/CODEBASE_INDEX.md` 生成带 checksum 的工作流仓库机器投影；中断项目直接路由 checkpoint。 |
 | `lib/yaml-runtime.mjs` | 为发行包和安装后的项目内 Bootstrap 运行时解析 YAML；优先使用包依赖，项目内回退到状态 CLI 的 vendored YAML。 |
 | `lib/delivery-state.mjs` | 正式状态公共命令实现；管理物料、节点、Gate、候选、发布和可信历史锚点，提供 revision、锁、原子写、checksum、例行/增量/全历史校验。 |
 | `lib/evolution.mjs` | 项目级自进化公共命令实现；管理反馈、提案、风险、扩展版本、批准、trial、Hook 调度、回退和 promotion bundle。 |
@@ -189,7 +189,7 @@
 | `skills/ai-delivery-orchestrate/assets/project-template/.workflow/tools/hooks/hook-event.mjs` | 完整项目模板中的 Hook 记录器副本；与 checkpoint skill 的脚本保持一致，供整体模板审阅。 |
 | `skills/ai-delivery-orchestrate/assets/project-template/.workflow/tools/state/state.mjs` | 安装后正式状态 CLI wrapper；使用 vendored YAML 调用统一状态模块。 |
 | `skills/ai-delivery-orchestrate/assets/project-template/.workflow/tools/evolution/evolve.mjs` | 安装后 Evolution CLI wrapper；复用状态运行时 vendored YAML 并调用统一 Evolution 模块。 |
-| `skills/ai-delivery-orchestrate/assets/project-template/.workflow/tools/bootstrap/bootstrap.mjs` | 安装后自主入口 wrapper；提供不依赖全局命令的只读识别和引导上下文生成。 |
+| `skills/ai-delivery-orchestrate/assets/project-template/.workflow/tools/bootstrap/bootstrap.mjs` | 安装后自主入口 wrapper；提供不依赖全局命令的只读识别、引导上下文生成和 `project-index` 机器投影命令。 |
 | `skills/ai-delivery-orchestrate/assets/project-template/.workflow/evolution/index.yaml` | 初始自进化索引，schema 1；不伪造反馈、提案或扩展。 |
 | `skills/ai-delivery-orchestrate/assets/project-template/.workflow/tools/manager/manager.mjs` | 安装后 Workflow Manager wrapper；从受管 runtime 调用同一应用服务。 |
 | `skills/ai-delivery-orchestrate/assets/project-template/.workflow/tools/manager/start.cmd` | Windows CMD Manager 启动入口。 |

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

@@ -262,6 +262,7 @@ npx ai-delivery-workflow@latest upgrade .
 | `ai-delivery inspect [project]` | 否 | 输出机器可读的项目、代码、流程和运行时状态。 |
 | `ai-delivery bootstrap [project]` | 视状态而定 | 初始化空项目或存量项目上下文，或把中断项目路由到恢复。 |
 | `ai-delivery bootstrap [project] --dry-run` | 否 | 预览引导动作。 |
+| `node .workflow/tools/bootstrap/bootstrap.mjs project-index [project] [--output <path>]` | 是（写入工作流仓库） | 读取代码仓库唯一事实源 `docs/CODEBASE_INDEX.md`，生成带 `source_checksum` 的 `.workflow/delivery/bootstrap/codebase-index.yaml` 机器投影；投影不得写回代码仓库。 |
 | `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 和初始化计划。 |
@@ -308,6 +309,14 @@ Page 决定和修改要求绑定精确 Revision、Page/Scene 及 checksum。修
 node .workflow/tools/bootstrap/bootstrap.mjs inspect
 ```
 
+代码仓库说明索引由维护者编辑 `docs/CODEBASE_INDEX.md`。需要给 Agent 或工具快速读取时，在工作流仓库根目录执行：
+
+```powershell
+node .workflow/tools/bootstrap/bootstrap.mjs project-index <project>
+```
+
+该命令只生成派生 YAML，消费者必须校验 `source_checksum`；不要直接编辑投影或把投影复制回代码仓库。
+
 引导器只返回以下五种状态之一：
 
 | 状态 | 含义 | 推荐动作 |

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

@@ -2,7 +2,7 @@
 
 当前生产图是 `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；只读调用方只对能够解析且确认 `pid` 仍存活的活动 writer 做有限等待，以避免并发读取观察到混合 revision；未知格式锁、失联 writer、其他 reader 或未恢复 journal 均立即 fail-closed。只读调用方不得接管死锁或执行事务恢复。日常 `verify` 不遍历历史分片，只校验当前视图、JSONL 索引、物料和状态不变量；显式 `verify --history` 还检查全部事件分片的连续性、元数据、记录 checksum、schema 2 checksum 链以及最新 replay 结果与全局视图的一致性。`rebuild` 按 revision replay 每个 stream，并按确定顺序重建 JSONL 索引。
 
 ## 1. 权威源码与安装结果
 
@@ -135,7 +135,7 @@ npm run audit:verify
 
 `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 立即失败。
+独立 aggregate 的 writer 仍通过共享提交区串行更新 JSONL 和全局视图，但使用各自的 aggregate revision：最多等待可识别的活动事务 30 秒，获取锁后重新读取并可分别成功。同一 aggregate 的 writer 在等待后必须因 revision conflict fail-closed。只读入口仅等待可证明仍存活的活动 writer；未知格式锁、失联 writer 和 journal 均不等待、不恢复，立即 fail-closed。
 
 安装诊断不得从项目内可编辑 manifest 推导可信 Skill 集合。固定 Skill 清单、Skill 目录摘要、Hook 摘要和状态运行时摘要以发行包为准；manifest 必须与发行包一致。`doctor` 还必须运行安装后状态 CLI 的 `inspect` 与 `verify`，并校验 JSON 输出语义。
 

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

@@ -4,7 +4,7 @@
 
 ## 可重建视图
 
-正式状态 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 事务。视图丢失或损坏时执行：
+正式状态 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，仅对可解析且确认 writer `pid` 仍存活的活动 mutation 做有界等待，不会返回混合 revision。未知格式锁、失联 writer、其他 reader 或未恢复 journal 均立即 fail-closed。mutation writer 最多等待可识别的活动提交 30 秒，获取锁后重新读取并校验自己的 aggregate revision。下一次 mutation 或 `rebuild` 根据 commit marker 回滚 prepared 事务或清理 committed 事务。视图丢失或损坏时执行：
 
 ```powershell
 node .workflow/tools/state/state.mjs rebuild

package/docs/agents/workflow-manager-current-state.md

@@ -1,13 +1,13 @@
 # 工作流与工作流管理器阶段现状
 
-更新时间：2026-08-22
+更新时间：2026-08-23
 
 本文是继续设计、实现或审核 Workflow Manager 时的阶段入口。它区分已经进入正式工作流源码的能力、已经接受但尚未实现的产品决策、仅在隔离原型中验证的交互，以及仍未完成的事项。领域术语以根目录 `CONTEXT.md` 为准，不以本文替代 ADR、正式状态契约或 Issue。
 
 ## 1. 当前基线
 
 - 当前仓库是 `ai-delivery-workflow` 的维护与发行源码仓库，不是安装了工作流的业务项目。
-- 当前正式源码候选版本为 `0.6.0`（待完成发布 Gate）；上一版 `0.5.1` 的提交、Git tag、npm 包身份及 Workflow Manager 的历史 `0.4.0` 候选身份、校验和和生命周期证据仍记录在维护仓库的 `audit/WORKFLOW-MANAGER-P0-P1-P2-CLOSURE.md`，这些历史记录不可改写。候选包和展开验证工作区保留在被忽略的 `.tmp/`。
+- 当前维护基线的包版本为 `0.7.1`，本轮维护提交按 PATCH 版本完成发行闭环；对应发行提交、Git tag `v0.7.1` 和 npm 包身份由发布预检与发布后验证固定。`0.4.0`、`0.5.0`、`0.5.1`、`0.6.0` 和 `0.7.0` 的提交、Git tag、npm 包身份及校验和/生命周期证据均属于历史记录，仍保存在 `audit/` 中且不可改写；候选包和展开验证工作区保留在被忽略的 `.tmp/`。
 - 正式维护源码位于 `bin/`、`lib/`、`skills/`、`docs/`、`verification/` 和 `audit/`。
 - Workflow Manager 设计原型位于 `prototypes/workflow-manager/`，业务项目原型夹具位于 `prototypes/order-ops-business/`。两者是可版本化设计资产，不进入发行包，也不等于正式前端已经实现；运行时依赖、构建产物和一次性验证工作区仍放在 `.tmp/`。
 
@@ -156,17 +156,17 @@ Workflow Manager 从一开始就是人和 AI 共同使用的控制面。UI 与 W
 
 当前正式浏览器测试遍历全部 19 个 Page，验证 P12 筛选、P13 Scene/Ctrl+V/保存、P14/P15 深链、P14 -> P13 Source Inspection Snapshot、P08 双 Tab/计划节点、P02 列头以及 `1280x720`、`1440x900` 无横向溢出或关键面板重叠；应用控制台无 error/warn。Manager 定向套件 97/97 通过，最终 `index.html` 引用的哈希资源已登记到 Git 索引。
 
-### 4.1 `0.4.0` 候选验证
+### 4.1 历史 `0.4.0` 候选验证
 
 - 当前 P0/P1/P2 候选包的精确路径、SHA-256、文件数和生命周期报告由维护仓库的 `audit/WORKFLOW-MANAGER-P0-P1-P2-CLOSURE.md` 固定登记。审计记录不在 npm 包范围内，因此不会导致候选包自引用；实际 tarball 和展开验证工作区仍保留在 `.tmp/`。
 - 隔离新安装的 Doctor 除可选 CodeGraph 提示外全部通过；安装后 Manager 的主页、健康检查、`workflow-manager.v1` Schema、19 个 Page、七节点投影、25 个可发现受控动作和 r33 Prototype 投影均已实测。
 
-### 4.2 v2 Prototype catalog Candidate Assurance
+### 4.2 历史 v2 Prototype catalog Candidate Assurance
 
 - 新安装交付把 v2 Prototype Revision 的运行时、Manager、Agent Interface、Experience Skill 和全部必需 catalog 模板列为包表面。`doctor` 在包表面缺失时立即失败，不再继续计算会因缺失运行时而崩溃的受管资产摘要。
 - 新的生产路径只接受 `prototype-revision-catalog.v2`。Experience Skill、Project Template、安装后的 Manager 与 Candidate Assurance 都从同一 Revision/checksum 读取事实；缺少任一必需 catalog 时由 CLI、HTTP 和 UI 确定性拒绝。
 - `verification/workflow-manager.test.mjs` 的隔离 Candidate Assurance 用当前工作树实际执行 `npm pack`，在 `.tmp/` 的独立 consumer 安装 tarball，并由安装后的 `ai-delivery init` 与 `doctor` 建立项目。它用多 Logical Terminal 的 v2 fixture 证明安装后的 Manager CLI、HTTP 和 P07/P11-P17 浏览器 UI 读取同一 Prototype Revision 身份和 checksum：每个 Web UI 请求和返回都显式为 `TERM-WEB`，P12 的 `TERM-ADMIN` 路由实际显示 Admin 目标而不回退到 Web。Component Candidate 通过 P11 提交 `candidate -> under-review`、已安装 CLI 提交 `under-review -> registered`、HTTP 提交 `registered -> modified`；每次 apply 均产生 Receipt/Event，CLI 与 HTTP 均重放同一幂等键。初始 CLI/HTTP 计划仍返回相同 plan/successor；删除 v2 `components` catalog 后，三种入口返回相同受控拒绝。测试覆盖 `1280x720` 与 `1440x900` 桌面视口，且有效 Revision 路径没有浏览器 console error/warn。
-- 可重建证据和边界记录在 `audit/WORKFLOW-MANAGER-V2-CANDIDATE-ASSURANCE.md`。它不替代 `audit/WORKFLOW-MANAGER-P0-P1-P2-CLOSURE.md` 的历史候选身份；`0.5.0` 发布时的源码已通过完整 `release:check`、npm 2FA Gate 并发布。生成的 tarball、consumer、缓存和浏览器临时文件都留在被忽略的 `.tmp/` 并在测试结束后删除。
+- 可重建证据和边界记录在 `audit/WORKFLOW-MANAGER-V2-CANDIDATE-ASSURANCE.md`。它不替代 `audit/WORKFLOW-MANAGER-P0-P1-P2-CLOSURE.md` 的历史候选身份；其中记录的 `0.5.0` 发布闭环属于历史证据，不代表当前 HEAD 已执行发布。生成的 tarball、consumer、缓存和浏览器临时文件都留在被忽略的 `.tmp/` 并在测试结束后删除。
 
 ## 5. 开放事项
 
@@ -189,7 +189,7 @@ Workflow Manager 从一开始就是人和 AI 共同使用的控制面。UI 与 W
 
 1. P0/P1/P2 及 Prototype 治理 01–07 已完成；实现提交为 `ae70304`，后续 v2 Candidate Assurance 收尾提交为 `db8abfb`，候选验证与 11 个 Gitee Issue 收尾均已完成。
 2. 后续变更继续沿当前 `.workflow/`、schema 2 与 v2 Prototype Revision 契约推进。
-3. r33 晋级改变了当前源码候选内容，历史 `0.4.0` r8 候选证据仍不可变且不能复用；该变更已在 `0.5.0` 中完成发布闭环。后续发布仍需从干净且同步的 `main` 重新生成候选，并通过 `release:check`、账号/2FA 与人工发布 Gate。
+3. r33 晋级改变了当时的源码候选内容，历史 `0.4.0` r8 候选证据仍不可变且不能复用；该变更当时已在 `0.5.0` 中完成发布闭环。本轮 `0.7.1` 维护提交已通过 `release:check`、账号/2FA 和发布后验证；后续发布仍需从干净且同步的 `main` 重新生成候选。
 
 ## 6. 继续工作时必须读取的来源
 

package/lib/delivery-state.mjs

@@ -330,6 +330,7 @@ function pauseForLockRetry() {
 function withLock(files, stream, action, lockOptions = {}) {
   const recover = lockOptions.recover !== false;
   const waitForActive = lockOptions.waitForActive === true;
+  let waitNotified = false;
   const maximumAttempts = waitForActive ? Number.POSITIVE_INFINITY : 3;
   const waitDeadline = waitForActive
     ? Date.now() + (lockOptions.waitTimeoutMs ?? ACTIVE_LOCK_WAIT_TIMEOUT_MS)
@@ -351,10 +352,20 @@ function withLock(files, stream, action, lockOptions = {}) {
     } catch (error) {
       if (error.code !== "EEXIST") throw error;
       if (recover && removeAbandonedLock(lockFile)) continue;
-      if (waitForActive && isWaitableFormalLock(lockFile) && Date.now() < waitDeadline) {
+      if (waitForActive
+        && isWaitableFormalLock(lockFile, { allowInitializing: stream !== "formal-state-read" })
+        && Date.now() < waitDeadline) {
+        if (!waitNotified && typeof lockOptions.onWait === "function") {
+          waitNotified = true;
+          lockOptions.onWait({ lockFile, stream });
+        }
         pauseForLockRetry();
         continue;
       }
+      // A live writer can release the lock between the failed open and metadata
+      // inspection. Retry that narrow race; an existing malformed/orphaned lock
+      // still falls through to the fail-closed error below.
+      if (waitForActive && !fs.existsSync(lockFile) && Date.now() < waitDeadline) continue;
       throw new Error(`Formal state is locked while updating: ${stream}`);
     }
   }
@@ -371,19 +382,28 @@ function withLock(files, stream, action, lockOptions = {}) {
   }
 }
 
-function isWaitableFormalLock(lockFile) {
+function isWaitableFormalLock(lockFile, { allowInitializing = false } = {}) {
   try {
     const content = fs.readFileSync(lockFile, "utf8");
     try {
       const owner = JSON.parse(content);
-      return typeof owner.stream === "string" && owner.stream.length > 0;
+      if (typeof owner.stream !== "string" || owner.stream.length === 0
+        || owner.stream === "formal-state-read"
+        || !Number.isInteger(owner.pid) || owner.pid <= 0) return false;
+      try {
+        process.kill(owner.pid, 0);
+        return true;
+      } catch (error) {
+        return error.code === "EPERM";
+      }
     } catch {
+      if (!allowInitializing) return false;
       const ageMs = Date.now() - fs.statSync(lockFile).mtimeMs;
       return ageMs >= 0 && ageMs < LOCK_METADATA_INITIALIZATION_TIMEOUT_MS;
     }
   } catch (error) {
     // The owner may release the lock between our failed open and metadata read.
-    return error.code === "ENOENT";
+    return false;
   }
 }
 
@@ -935,8 +955,12 @@ function assertNoPendingTransaction(files) {
   }
 }
 
-function withReadableFormalState(files, action) {
-  return withLock(files, "formal-state-read", action, { recover: false });
+function withReadableFormalState(files, action, lockOptions = {}) {
+  return withLock(files, "formal-state-read", action, {
+    recover: false,
+    waitForActive: true,
+    onWait: lockOptions.onWait,
+  });
 }
 
 function withZeroWriteFormalState(files, action) {
@@ -2533,7 +2557,10 @@ function transitionWorkflow(files, flags, options) {
     });
     if (completionReceipt) result.completion_receipt = completionReceipt;
     return result;
-  }, { waitForActive: flags.has("--expected-scope-revision") });
+  }, {
+    waitForActive: flags.has("--expected-scope-revision"),
+    onWait: options.onLockWait,
+  });
 }
 
 function registeredEvidence(files, evidence, options, node = null) {
@@ -3208,6 +3235,7 @@ export function executeDeliveryStateCommand(argv, options = {}) {
           history: flags.has("--history"),
           sinceAnchor: flags.has("--since-anchor"),
         }),
+        { onWait: options.onLockWait },
       );
     } else if (command === "snapshot" && positional[1] === "create") {
       result = createFormalSnapshot(files, flags, options);
@@ -3234,7 +3262,7 @@ export function executeDeliveryStateCommand(argv, options = {}) {
           scope_manifest: currentScopeManifest(workflowState.development_state),
           derived_node_states: deriveNodeStates(files, workflowState, artifactRegistry, options),
         };
-      });
+      }, { onWait: options.onLockWait });
     } else {
       throw new Error(
         "Use inspect, verify, rebuild, snapshot create, artifact register/prune, scope freeze/amend/warn, "

package/lib/project-bootstrap.mjs

@@ -339,6 +339,89 @@ function documentationLinks(text) {
   return [...text.matchAll(/\[[^\]]*\]\(([^)]+)\)/g)].map((match) => match[1].trim());
 }
 
+const INDEX_FIELD_ALIASES = new Map([
+  ["路径", "path"], ["文件", "path"], ["职责", "purpose"], ["用途", "purpose"],
+  ["主要入口", "entrypoints"], ["入口", "entrypoints"], ["关联测试", "tests"], ["测试/验证", "tests"],
+  ["关键依赖或被依赖模块", "dependencies"], ["允许依赖", "dependencies"], ["依赖", "dependencies"],
+  ["风险", "risk"], ["生成或外部维护", "generated"], ["生成", "generated"],
+  ["维护责任", "owner"], ["维护状态", "status"], ["状态", "status"],
+  ["适用代码提交", "source_commit"], ["source_commit", "source_commit"],
+  ["最后核对", "last_reviewed"], ["last_reviewed", "last_reviewed"],
+  ["正式依据", "references"], ["references", "references"],
+]);
+
+function markdownCells(line) {
+  return line.split("|").slice(1, -1).map((cell) => cell.trim().replaceAll("`", ""));
+}
+
+function projectIndexRows(text) {
+  const rows = [];
+  let section = null;
+  let header = null;
+  for (const [lineIndex, line] of text.split(/\r?\n/).entries()) {
+    const heading = line.match(/^#{2,6}\s+(.+?)\s*#*$/);
+    if (heading) {
+      section = heading[1].trim();
+      header = null;
+      continue;
+    }
+    if (!line.trim().startsWith("|")) {
+      if (line.trim()) header = null;
+      continue;
+    }
+    const cells = markdownCells(line);
+    if (!cells.length || cells.every((cell) => /^:?-{3,}:?$/.test(cell))) continue;
+    if (cells.some((cell) => INDEX_FIELD_ALIASES.has(cell))) {
+      header = cells;
+      continue;
+    }
+    if (!header) continue;
+    const row = { section, source_line: lineIndex + 1 };
+    header.forEach((name, index) => {
+      const key = INDEX_FIELD_ALIASES.get(name);
+      if (key && cells[index] !== undefined && cells[index] !== "") row[key] = cells[index];
+    });
+    if (row.path && !/^<.*>$/.test(row.path) && row.path !== "-") rows.push(row);
+  }
+  return rows;
+}
+
+export function projectCodebaseIndex(codeRoot, outputFile = null) {
+  const root = path.resolve(codeRoot);
+  const indexFile = path.join(root, "docs", "CODEBASE_INDEX.md");
+  if (!fs.existsSync(indexFile)) throw new Error("docs/CODEBASE_INDEX.md does not exist");
+  const documentation = inspectCodebaseDocumentation(root, inspectGitRepository(root));
+  if (documentation.invalid.length) {
+    throw new Error(`CODEBASE_INDEX.md is invalid:\n${documentation.invalid.map((item) => `${item.path}: ${item.reason}`).join("\n")}`);
+  }
+  const bytes = fs.readFileSync(indexFile);
+  const text = bytes.toString("utf8");
+  const metadata = documentation.files.find((file) => file.path === "docs/CODEBASE_INDEX.md") || documentationMetadata(text);
+  const rows = projectIndexRows(text);
+  if (!rows.length) throw new Error("CODEBASE_INDEX.md contains no concrete index rows");
+  // The code repository is a nested child of the workflow workspace. Keep the
+  // derived projection beside it, never inside the code repository itself.
+  const defaultWorkspaceRoot = path.dirname(root);
+  const destination = path.resolve(outputFile || path.join(defaultWorkspaceRoot, ".workflow", "delivery", "bootstrap", "codebase-index.yaml"));
+  const relative = path.relative(root, destination);
+  if (!relative.startsWith("..") && !path.isAbsolute(relative)) {
+    throw new Error("machine projection must be written outside the code repository");
+  }
+  const projection = {
+    schema_version: 1,
+    projection_type: "codebase-index",
+    source_of_truth: "docs/CODEBASE_INDEX.md",
+    source_checksum: sha256File(indexFile),
+    source_commit: metadata.source_commit || null,
+    last_reviewed: metadata.last_reviewed || null,
+    status: documentation.status,
+    generated_at: new Date().toISOString(),
+    entries: rows,
+  };
+  atomicWrite(destination, stringifyYaml(projection, { lineWidth: 0 }));
+  return { output: toPosix(destination), source: "docs/CODEBASE_INDEX.md", source_checksum: projection.source_checksum, status: projection.status, entry_count: rows.length };
+}
+
 export function inspectCodebaseDocumentation(root, git = inspectGitRepository(root)) {
   const files = [];
   const errors = [];

package/lib/project-installer.mjs

@@ -243,8 +243,13 @@ function managedFilesEqual(left, right) {
 
 function directoryDigest(root) {
   const hash = crypto.createHash("sha256");
-  for (const file of filesUnder(root)) {
-    const relative = path.relative(root, file).replaceAll("\\", "/");
+  const entries = filesUnder(root)
+    .map((file) => ({
+      file,
+      relative: path.relative(root, file).replaceAll("\\", "/"),
+    }))
+    .sort((left, right) => left.relative.localeCompare(right.relative));
+  for (const { file, relative } of entries) {
     hash.update(relative);
     hash.update("\0");
     hash.update(normalizedManagedContent(file));
@@ -292,8 +297,14 @@ function exactPathDigest(target) {
 
 function sourceSetDigest(sources) {
   const hash = crypto.createHash("sha256");
-  for (const item of [...sources].sort((left, right) => left.relative.localeCompare(right.relative))) {
-    hash.update(item.relative.replaceAll("\\", "/"));
+  const entries = [...sources]
+    .map((item) => ({
+      item,
+      relative: item.relative.replaceAll("\\", "/"),
+    }))
+    .sort((left, right) => left.relative.localeCompare(right.relative));
+  for (const { item, relative } of entries) {
+    hash.update(relative);
     hash.update("\0");
     hash.update(normalizedManagedContent(item.source));
     hash.update("\0");

package/lib/workspace.mjs

@@ -113,7 +113,10 @@ function initializeWorkflowRepository(workspaceRoot, branch, remote, heads, acti
     const current = gitBranch(workspaceRoot);
     if (current !== branch) {
       if (gitHasCommit(workspaceRoot)) {
-        throw new Error(`Existing workflow repository must already use ${branch}; automatic branch changes are not supported.`);
+        throw new Error(
+          `Existing workflow repository must already use ${branch}; automatic branch changes are not supported. `
+          + `Create or switch to the required branch with 'git switch -c ${branch}' and rerun init.`,
+        );
       }
       if (!dryRun) runGit(workspaceRoot, ["symbolic-ref", "HEAD", `refs/heads/${branch}`]);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-delivery-workflow",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "Project-scoped Codex skills and hooks for artifact-driven AI software delivery",
   "type": "module",
   "repository": {

package/skills/ai-delivery-assemble-release/SKILL.md

@@ -5,6 +5,10 @@ description: Calculate a selected release target's continuous cumulative version
 
 # Assemble Release
 
+Apply the shared confirmation protocol from `../ai-delivery-orchestrate/references/communication-confirmation-contract.md`; release-selection and material exceptions must be recorded in the release confirmation summary before they can affect the candidate.
+
+When release material aggregation exposes a missing decision or exception, record it in the release confirmation summary and keep the candidate blocked until the owning artifact is updated.
+
 Produce a deterministic release selection and auditable material package. Do not approve or deploy it.
 
 ## Select The Version Closure

package/skills/ai-delivery-bootstrap/SKILL.md

@@ -5,6 +5,8 @@ description: Inspect a project before normal AI delivery execution, classify emp
 
 # Bootstrap AI Delivery
 
+When Bootstrap needs a business or maintainer decision, use `../ai-delivery-orchestrate/references/communication-confirmation-contract.md` to create the first frontier question. Keep repository observations evidence-backed and route business intent to `01-product-shaping`.
+
 Establish enough verified project context to resume or begin work without relying on chat history.
 
 ## Dual-Repository Workspace
@@ -54,7 +56,7 @@ Do not replace existing product, architecture, test, or release baselines. Keep
 
 ### Codebase Handbook Discovery
 
-For the configured nested code repository, inspect `AGENTS.md`, `CODEBASE_GUIDE.md`, and `docs/CODEBASE_INDEX.md` as read-only maintainer documents. The report records `observed`, `approved`, or `stale`; missing files are a warning, while malformed, path-invalid, symlink, or sensitive-content findings fail closed. Compare each declared `source_commit` with the code repository HEAD. Never infer an approved rule from the generated inventory, and never overwrite these files during bootstrap or upgrade.
+For the configured nested code repository, inspect `AGENTS.md`, `CODEBASE_GUIDE.md`, and `docs/CODEBASE_INDEX.md` as read-only maintainer documents. The report records `observed`, `approved`, or `stale`; missing files are a warning, while malformed, path-invalid, symlink, or sensitive-content findings fail closed. Compare each declared `source_commit` with the code repository HEAD. When a structured consumer needs navigation, run the explicit `project-index` command to generate `.workflow/delivery/bootstrap/codebase-index.yaml` from the Markdown index and verify its source checksum before use. Never infer an approved rule from the generated inventory or projection, and never overwrite the code-repository documents during bootstrap or upgrade.
 
 ## Resume Boundary
 

package/skills/ai-delivery-checkpoint-task/SKILL.md

@@ -5,6 +5,8 @@ description: Persist, checkpoint, finish, recover, and archive version-scoped AI
 
 # Checkpoint Delivery Task
 
+When a task is waiting on a user or external confirmation, persist the summary path, question ID, frontier round, and checksum from the shared communication protocol. Recovery remains zero-mutation until ownership transfers to `agent`.
+
 Treat explicit task snapshots as authoritative. Treat Hook events as an audit trail and heartbeat, never as proof that a stage completed.
 
 ## Artifact Location

package/skills/ai-delivery-close-version/SKILL.md

@@ -5,6 +5,8 @@ description: Close an independently verified planned version without publishing
 
 # Close Planned Version
 
+When closeout finds an unresolved decision or exception, validate the current `confirmation-summary.yaml` through `../ai-delivery-orchestrate/scripts/confirmation-state.mjs`; link confirmed decisions to closeout evidence and keep release intent separate.
+
 Finish one planned version and stop before release. Never start a release from this skill.
 
 ## Preflight

package/skills/ai-delivery-define-product/SKILL.md

@@ -5,6 +5,8 @@ description: Discover and define a product through a guided interview, then prod
 
 # Define Product
 
+Use `../ai-delivery-orchestrate/references/communication-confirmation-contract.md` for every business decision, domain term, constraint, risk, and open question. Recompute the frontier after each answer and write confirmed knowledge into the product manual or baseline before Gate A/B.
+
 Turn an initial idea into two human-approved baselines without inventing unresolved business decisions.
 
 ## Artifact Location

package/skills/ai-delivery-deploy-production/SKILL.md

@@ -5,6 +5,8 @@ description: Execute R08 production deployment of one human-approved immutable r
 
 # Deploy Production
 
+Production deployment questions use the shared confirmation protocol and the exact release summary. Require explicit `PRODUCTION-APPROVAL`; never infer deployment authorization from a passing candidate.
+
 Execute the approved plan exactly. Do not rebuild, patch, add unlisted items, change configuration ad hoc, or decide that the release succeeded.
 
 ## Artifact Location

package/skills/ai-delivery-design-architecture/SKILL.md

@@ -5,6 +5,8 @@ description: Design and reconcile a coherent application, technical, data, secur
 
 # Design Architecture
 
+Use `../ai-delivery-orchestrate/references/communication-confirmation-contract.md` for architecture decisions, quality-budget exceptions, product-impact findings, and risk acceptance. Link confirmed records to the architecture baseline or Gate before handoff.
+
 Use one skill with `initial` and `reconcile` modes so coupled architecture views remain consistent.
 
 ## Artifact Location

package/skills/ai-delivery-design-experience/SKILL.md

@@ -5,6 +5,8 @@ description: Select prototype and UI tools, define a confirmed visual system, pr
 
 # Design Experience
 
+Use `../ai-delivery-orchestrate/references/communication-confirmation-contract.md` for prototype, terminal, interaction, visual-system, and product-impact decisions. A Page review or chat answer is not authoritative until its receipt and owning artifact are linked.
+
 Design complete user experiences for the terminals selected by product and implemented by architecture.
 
 ## Artifact Location

package/skills/ai-delivery-design-tests/SKILL.md

@@ -5,6 +5,8 @@ description: Validate confirmed prototype testability and define the overall rel
 
 # Design Tests
 
+When test policy, quality budget, exception, or residual-risk choices need confirmation, use `../ai-delivery-orchestrate/references/communication-confirmation-contract.md` and link the answer to the test contract. Proposed or deferred records never count as test approval.
+
 Create a durable release strategy once and detailed test inputs just in time for the next slice.
 
 ## Artifact Location

package/skills/ai-delivery-develop-iteration/SKILL.md

@@ -5,6 +5,8 @@ description: Orchestrate implementation of one planned vertical slice from an ex
 
 # Develop Iteration
 
+When implementation exposes ambiguity, use `../ai-delivery-orchestrate/references/communication-confirmation-contract.md` and append one record to the owning node summary. A user or external wait is zero-mutation; chat cannot expand the package scope.
+
 Derive technical tasks just in time. Do not predefine frontend, backend, database, or other roles unless the selected slice and architecture require them.
 
 ## Artifact Location

package/skills/ai-delivery-evolve-workflow/SKILL.md

@@ -5,6 +5,8 @@ description: Record explicit workflow feedback and objective delivery signals, e
 
 # Evolve The Project Workflow
 
+Workflow improvement proposals use the shared confirmation summary for explicit maintainer acceptance; an observation or AI recommendation never activates an extension by itself.
+
 Use the project Evolution CLI for every feedback, proposal, extension, trial, and decision state change. Never edit `.workflow/evolution/index.yaml` or registered extension state directly.
 
 ## Capture Feedback

package/skills/ai-delivery-execute-work-package/SKILL.md

@@ -5,6 +5,8 @@ description: Execute one architecture-constrained technical work package against
 
 # Execute Technical Work Package
 
+When execution needs a behavior, scope, or risk decision, use `../ai-delivery-orchestrate/references/communication-confirmation-contract.md`, append the question to the owning summary, and wait without modifying source or formal state while ownership is `user` or `external`.
+
 Implement only the assigned package. Do not broaden scope, choose a different stack, approve your own change, or repair unrelated defects.
 
 ## Artifact Location

package/skills/ai-delivery-manage-standards/SKILL.md

@@ -5,6 +5,8 @@ description: Capture, classify, approve, version, resolve, and apply durable pro
 
 # Manage Standards
 
+Record proposed standards, exceptions, and maintainer decisions through the shared confirmation protocol; link confirmed `standard_decision` records to the standards baseline or approval receipt.
+
 Persist durable rules in the repository instead of relying on chat history. Do not silently turn a preference, suggestion, or one-time instruction into a standard.
 
 ## Artifact Location

package/skills/ai-delivery-orchestrate/SKILL.md

@@ -121,3 +121,5 @@ Read [workflow-model.md](references/workflow-model.md) for the state graph, gate
 Read [formal-state-contract.md](references/formal-state-contract.md) before mutating formal state.
 Read [codebase-document-contract.md](references/codebase-document-contract.md) when creating, reviewing, or locating the code repository's `AGENTS.md`, `CODEBASE_GUIDE.md`, or `docs/CODEBASE_INDEX.md`.
 Read [communication-confirmation-contract.md](references/communication-confirmation-contract.md) when a node asks for, records, resumes, or audits a user/external decision. Validate summaries with `scripts/confirmation-state.mjs`; this index never replaces the owning product, architecture, standards, task, Gate, or formal-state artifact.
+
+All development nodes (`00-bootstrap` through `06-version-closeout`) and release nodes (`R00` through `R10`) inherit this protocol. Each node must load its version-scoped `confirmation-summary.yaml` at preflight, keep one frontier round active, persist user/external waits as zero-mutation states, and write confirmed knowledge into the node's owning artifact before handoff.

package/skills/ai-delivery-orchestrate/assets/project-template/.workflow/tools/bootstrap/bootstrap.mjs

@@ -1,13 +1,14 @@
 #!/usr/bin/env node
 
 import path from "node:path";
-import { bootstrapProject, inspectProjectState } from "./project-bootstrap.mjs";
+import { bootstrapProject, inspectProjectState, projectCodebaseIndex } from "./project-bootstrap.mjs";
 
 function usage() {
   return [
     "Usage:",
     "  node .workflow/tools/bootstrap/bootstrap.mjs inspect [project]",
     "  node .workflow/tools/bootstrap/bootstrap.mjs bootstrap [project] [--dry-run]",
+    "  node .workflow/tools/bootstrap/bootstrap.mjs project-index [project] [--output path]",
   ].join("\n");
 }
 
@@ -17,12 +18,16 @@ try {
   if (command === "--help" || command === "help") {
     process.stdout.write(`${usage()}\n`);
   } else {
-    const projectArg = args.find((value, index) => index > 0 && !value.startsWith("--"));
+    const projectArg = args.find((value, index) => index > 0 && !value.startsWith("--") && args[index - 1] !== "--output");
     const target = path.resolve(projectArg || process.cwd());
+    const outputIndex = args.indexOf("--output");
+    const output = outputIndex >= 0 ? args[outputIndex + 1] : null;
     const result = command === "inspect"
       ? inspectProjectState(target)
       : command === "bootstrap"
         ? bootstrapProject(null, target, { dryRun: args.includes("--dry-run") })
+        : command === "project-index"
+          ? projectCodebaseIndex(path.resolve(target, inspectProjectState(target).workspace?.code_repository?.path || "code"), output ? path.resolve(target, output) : null)
         : null;
     if (!result) throw new Error(`Unknown command: ${command}\n\n${usage()}`);
     process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);

package/skills/ai-delivery-orchestrate/references/codebase-document-contract.md

@@ -16,7 +16,7 @@ code/
 - `AGENTS.md` is a short agent entrypoint. It contains only high-priority rules and conditional pointers into the handbook and index.
 - `docs/CODEBASE_INDEX.md` is the human-readable navigation map for directories, modules, entrypoints, tests, dependencies, risks, and maintenance ownership.
 
-The first release uses Markdown as the source of truth. A YAML or database projection is out of scope until a real consumer and synchronization contract exist.
+`docs/CODEBASE_INDEX.md` remains the single source of truth. When a CLI, CodeGraph adapter, or validator needs structured input, generate the read-only machine projection with `node .workflow/tools/bootstrap/bootstrap.mjs project-index <project>`. The projection is written to the workflow repository at `.workflow/delivery/bootstrap/codebase-index.yaml`, includes the source checksum and status, and is never edited directly or copied back into Markdown.
 
 ## Authority
 
@@ -77,6 +77,7 @@ Directory-level rows are the default. Use file-level rows for entrypoints, cross
 - A missing, stale, conflicting, or path-invalid entry must be reported before code modification relies on it.
 - Never put credentials, private keys, production data, or large source excerpts in these files.
 - `init` and `upgrade` must preserve existing code-repository documentation. Any creation or revision must be explicit, reviewable, and attributable to the owning workflow task.
+- A projection with a checksum mismatch, invalid source index, or stale source commit is unusable until the Markdown source is reviewed and regenerated.
 
 ## Writing quality
 
@@ -89,3 +90,4 @@ Prefer short paragraphs, tables, links, and concrete examples. Put the answer be
 - Commands are verified from repository configuration or a recorded validation run.
 - All paths resolve inside the code repository and all status/commit metadata is current.
 - Conflicts with workflow architecture or standards are explicitly linked and not silently resolved in prose.
+- Any machine consumer reads the generated projection only after verifying `source_checksum` against the current Markdown source.

package/skills/ai-delivery-orchestrate/references/communication-confirmation-contract.md

@@ -37,6 +37,23 @@ Each record has a stable `confirmation_id`, a `question_id`, a `frontier_round`,
 
 The default interaction policy is one user decision per round. Multiple questions may be presented together only when they are independent, low-risk, and the summary explicitly records the grouping rationale.
 
+## All-node integration
+
+Every formal development and release node uses this same protocol when a user or external decision is needed. The node-specific authority remains the owner shown below:
+
+| Node | Questions and knowledge to capture | Authority / return path |
+| --- | --- | --- |
+| `00-bootstrap` | observed repository facts, missing context, first product frontier | Bootstrap report; business choices return to `01-product-shaping` |
+| `01-product-shaping` | users, goals, scope, terminals, domain terms, business rules, priority, risk acceptance | discovery/product baseline and `GATE-A`/`GATE-B` |
+| `02-solution-design` | architecture tradeoffs, UX choices, new terminals, non-functional impact, product-impact assessment | architecture/experience baseline, UX Gates, or product return |
+| `03-delivery-readiness` | Slice boundaries, dependencies, environments, test policy, budget exceptions | scope manifest, test/platform contracts, or scope amend |
+| `04-implementation` | behavior ambiguity, implementation constraints, risk acceptance, allowed-file changes | task evidence, approved change set, or owning-node return |
+| `05-candidate-assurance` | exceptions, residual risk, test gaps, candidate acceptance | review/verification evidence or producer return |
+| `06-version-closeout` | unresolved decisions, release readiness, archive exceptions | version manifest/closeout; release intent remains separate |
+| `R00`-`R10` release | release intent, target selection, eligibility exceptions, production approval, deployment/rollback decisions | release artifacts, `PRODUCTION-APPROVAL`, production evidence |
+
+At node entry, read the current summary before asking a question. After each answer, append or supersede the record, recompute the frontier, and link the decision to its authority artifact before advancing. A node may continue without a question only when its evidence proves the decision is agent-verifiable or an approved baseline is unchanged.
+
 ## Shared understanding
 
 Set `shared_understanding: true` only after the current frontier is empty and the user has confirmed the summary. `deferred` and `open_question` records may remain, but each must identify an owner and an idempotent `next_action`. A node must not perform an action that depends on an unresolved decision.

package/skills/ai-delivery-orchestrate-release/SKILL.md

@@ -5,6 +5,8 @@ description: Orchestrate a production release independently from iteration deliv
 
 # Orchestrate Independent Release
 
+Release nodes use the shared confirmation protocol for explicit release intent, target selection, eligibility exceptions, production approval, deployment, rollback, and archive decisions. User/external waits are zero-mutation and never replay production actions.
+
 Coordinate `R00` through `R10`. Never infer release intent from completed versions or start production work from normal iteration orchestration.
 
 ## Start From Explicit Intent

package/skills/ai-delivery-plan-iteration/SKILL.md

@@ -5,6 +5,8 @@ description: Plan an agile AI delivery iteration by prioritizing business outcom
 
 # Plan Iteration
 
+When scope, priority, dependency, budget, or acceptance choices need confirmation, use `../ai-delivery-orchestrate/references/communication-confirmation-contract.md` and the version-scoped `confirmation-summary.yaml`. Recompute the frontier after each answer and keep unresolved business choices out of `scope freeze`.
+
 Plan business capability increments. Do not pre-split work into fixed frontend, backend, database, or human-role silos.
 
 ## Artifact Location

package/skills/ai-delivery-prepare-platform/SKILL.md

@@ -5,6 +5,8 @@ description: Prepare the delivery and operations platform required to build, tes
 
 # Prepare Delivery Platform
 
+When a platform, environment, dependency, cost, or risk choice needs a user or external decision, read `../ai-delivery-orchestrate/references/communication-confirmation-contract.md`, update the current `confirmation-summary.yaml`, and wait without mutation while ownership is `user` or `external`.
+
 Run as a parallel stream after initial architecture and join application development before independent candidate verification.
 
 ## Artifact Location

package/skills/ai-delivery-prepare-release/SKILL.md

@@ -5,6 +5,8 @@ description: Prepare an independently verified multi-version or same-version rel
 
 # Prepare Release
 
+Use `../ai-delivery-orchestrate/references/communication-confirmation-contract.md` for release intent, target selection, exception, rollback, and external-side-effect questions. Version completion never substitutes for explicit release intent.
+
 Create an auditable release package. Do not deploy production.
 
 ## Artifact Location

package/skills/ai-delivery-review-change/SKILL.md

@@ -5,6 +5,8 @@ description: Independently review a technical work-package change against approv
 
 # Review Change
 
+When review feedback requires an exception, risk acceptance, or scope decision, use `../ai-delivery-orchestrate/references/communication-confirmation-contract.md`; link the confirmed result to the approved `change_set_id` or return it to the owning producer.
+
 Review independently from the implementation context. Do not edit product code or approve a change with unresolved blocking findings.
 
 ## Artifact Location

package/skills/ai-delivery-validate-artifacts/SKILL.md

@@ -5,6 +5,8 @@ description: Validate AI delivery artifacts, registries, baselines, CSV relation
 
 # Validate Delivery Artifacts
 
+When validation finds an unresolved decision, read the version-scoped `confirmation-summary.yaml` and validate it with `../ai-delivery-orchestrate/scripts/confirmation-state.mjs`. Report the owning producer and keep the handoff blocked; validators do not decide business or risk acceptance.
+
 Validate contracts without repairing producer-owned content.
 
 ## Artifact Location

package/skills/ai-delivery-verify-candidate/SKILL.md

@@ -5,6 +5,8 @@ description: Independently verify an immutable iteration or release candidate ag
 
 # Verify Candidate
 
+When candidate assurance needs exception, residual-risk, or release-recommendation input, use `../ai-delivery-orchestrate/references/communication-confirmation-contract.md`. Do not turn missing evidence into a confirmation; unresolved records keep the candidate `blocked`.
+
 Validate the assembled system independently. Never modify product code, migrations, infrastructure, or configuration while acting as verifier.
 
 ## Artifact Location

package/skills/ai-delivery-verify-production/SKILL.md

@@ -5,6 +5,10 @@ description: Independently verify an R08 production deployment, decide release s
 
 # Verify Production
 
+Apply the shared confirmation protocol from `../ai-delivery-orchestrate/references/communication-confirmation-contract.md`; production exceptions and residual-risk acceptance must be recorded in the confirmation summary before closeout.
+
+Record production verification exceptions, rollback acceptance, and residual-risk decisions in the release confirmation summary; link them to the immutable deployment evidence before closeout.
+
 Keep deployment execution separate from release success.
 
 ## Artifact Location