ai-delivery-workflow 0.6.0 → 0.7.0

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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-delivery-workflow",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "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