ai-delivery-workflow 0.5.1 → 0.7.0

package/lib/project-bootstrap.mjs

@@ -8,6 +8,7 @@ import {
   stableValue,
   withFormalStateReadLock,
 } from "./delivery-state.mjs";
+import { readConfirmationSummary } from "./communication-confirmation.mjs";
 import { inspectGitRepository, readWorkspaceConfiguration } from "./workspace.mjs";
 
 const IGNORED_DIRECTORIES = new Set([
@@ -32,6 +33,50 @@ const IGNORED_DIRECTORIES = new Set([
   "target",
 ]);
 const VALID_NEXT_ACTION_OWNERS = new Set(["agent", "user", "external"]);
+const CODEBASE_DOCUMENTATION_FILES = [
+  { path: "AGENTS.md", kind: "agent-entrypoint" },
+  { path: "CODEBASE_GUIDE.md", kind: "maintainer-guide" },
+  { path: "docs/CODEBASE_INDEX.md", kind: "navigation-index" },
+];
+const CODEBASE_DOCUMENTATION_STATUS = new Set(["observed", "approved", "stale"]);
+
+export function inspectConfirmationSummaries(root) {
+  const base = path.join(root, ".workflow", "iterations");
+  const summaries = [];
+  const errors = [];
+  if (!fs.existsSync(base)) return { status: "absent", summaries, errors };
+  const visit = (directory) => {
+    let entries;
+    try { entries = fs.readdirSync(directory, { withFileTypes: true }); } catch (error) {
+      errors.push(`${toPosix(path.relative(root, directory))}: ${error.message}`);
+      return;
+    }
+    for (const entry of entries) {
+      const absolute = path.join(directory, entry.name);
+      if (entry.isDirectory()) visit(absolute);
+      else if (entry.isFile() && entry.name === "confirmation-summary.yaml") {
+        try {
+          const result = readConfirmationSummary(absolute);
+          summaries.push({
+            path: toPosix(path.relative(root, absolute)),
+            checksum: sha256File(absolute),
+            summary_id: result.summary.summary_id,
+            version: result.summary.version,
+            frontier: result.validation.frontier,
+            blocked_proposals: result.validation.blocked_proposals,
+            valid: result.validation.valid,
+            errors: result.validation.errors,
+          });
+          if (!result.validation.valid) errors.push(...result.validation.errors.map((item) => `${toPosix(path.relative(root, absolute))}: ${item}`));
+        } catch (error) {
+          errors.push(`${toPosix(path.relative(root, absolute))}: ${error.message}`);
+        }
+      }
+    }
+  };
+  visit(base);
+  return { status: errors.length ? "invalid" : summaries.length ? "valid" : "absent", summaries, errors };
+}
 
 const SOURCE_EXTENSIONS = new Map([
   [".c", "C"],
@@ -255,6 +300,282 @@ function scanProjectFiles(root, maxFiles = 10_000) {
   };
 }
 
+function hasSensitiveContent(text) {
+  return /BEGIN (?:RSA|OPENSSH|EC|DSA) PRIVATE KEY|(?:AKIA|ASIA)[A-Z0-9]{16}|(?:ghp|github_pat)_[A-Za-z0-9_]{20,}/.test(text)
+    || /(?:password|secret|token|api[_-]?key)\s*[:=]\s*["'][^"']{8,}["']/i.test(text);
+}
+
+function documentationMetadata(text) {
+  const status = text.match(/(?:^|\|)\s*(?:状态|项目状态)\s*\|\s*`?([^|\n`]+)`?/m)?.[1]?.trim().toLowerCase() || null;
+  const sourceCommit = text.match(/(?:适用代码提交|对应代码提交|source_commit)\s*\|\s*`?([^|\n`]+)`?/m)?.[1]?.trim()
+    || text.match(/`source_commit`\s*\|\s*`?([^|\n`]+)`?/m)?.[1]?.trim()
+    || null;
+  const lastReviewed = text.match(/(?:最后核对|last_reviewed)\s*\|\s*`?([^|\n`]+)`?/m)?.[1]?.trim()
+    || text.match(/`last_reviewed`\s*\|\s*`?([^|\n`]+)`?/m)?.[1]?.trim()
+    || null;
+  return { status, source_commit: sourceCommit, last_reviewed: lastReviewed };
+}
+
+function documentationPathEntries(text) {
+  const entries = [];
+  let header = null;
+  for (const [index, line] of text.split(/\r?\n/).entries()) {
+    if (!line.trim().startsWith("|")) continue;
+    const cells = line.split("|").slice(1, -1).map((cell) => cell.trim());
+    if (!cells.length) continue;
+    if (cells.some((cell) => /^(路径|文件)$/.test(cell))) {
+      header = cells;
+      continue;
+    }
+    if (!header || cells.every((cell) => /^:?-{3,}:?$/.test(cell))) continue;
+    const pathIndex = header.findIndex((cell) => /^(路径|文件)$/.test(cell));
+    if (pathIndex < 0 || !cells[pathIndex]) continue;
+    entries.push({ value: cells[pathIndex].replaceAll("`", "").trim(), line: index + 1 });
+  }
+  return entries;
+}
+
+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 = [];
+  const warnings = [];
+  const missing = [];
+  const invalid = [];
+  const stale = [];
+  const statuses = [];
+  if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+    return {
+      status: "missing",
+      files: [],
+      missing: CODEBASE_DOCUMENTATION_FILES.map((item) => item.path),
+      invalid: [],
+      stale: [],
+      sensitive_file_count: 0,
+      errors: [],
+      warnings: ["代码仓库目录不存在，无法发现项目说明书和索引。"],
+    };
+  }
+
+  for (const expected of CODEBASE_DOCUMENTATION_FILES) {
+    const absolute = path.join(root, expected.path);
+    if (!fs.existsSync(absolute)) {
+      missing.push(expected.path);
+      continue;
+    }
+    let stat;
+    try {
+      stat = fs.lstatSync(absolute);
+    } catch (error) {
+      invalid.push({ path: expected.path, reason: `无法读取文件：${error.code || error.message}` });
+      continue;
+    }
+    if (stat.isSymbolicLink()) {
+      invalid.push({ path: expected.path, reason: "说明文件不能是符号链接" });
+      continue;
+    }
+    if (!stat.isFile()) {
+      invalid.push({ path: expected.path, reason: "说明路径必须是普通文件" });
+      continue;
+    }
+    let text;
+    try {
+      text = fs.readFileSync(absolute, "utf8");
+    } catch (error) {
+      invalid.push({ path: expected.path, reason: `无法读取文件：${error.code || error.message}` });
+      continue;
+    }
+    const metadata = documentationMetadata(text);
+    const record = { path: expected.path, kind: expected.kind, ...metadata, bytes: stat.size };
+    files.push(record);
+    if (expected.kind !== "agent-entrypoint") {
+      if (!metadata.status) invalid.push({ path: expected.path, reason: "缺少 status/状态字段" });
+      if (!metadata.source_commit) invalid.push({ path: expected.path, reason: "缺少 source_commit/适用代码提交字段" });
+      if (!metadata.last_reviewed) invalid.push({ path: expected.path, reason: "缺少 last_reviewed/最后核对字段" });
+    }
+    if (metadata.status && !CODEBASE_DOCUMENTATION_STATUS.has(metadata.status)) {
+      invalid.push({ path: expected.path, reason: `status 无效：${metadata.status}` });
+    }
+    if (metadata.status) statuses.push(metadata.status);
+    if (hasSensitiveContent(text)) {
+      invalid.push({ path: expected.path, reason: "疑似包含凭据、私钥或敏感值" });
+    }
+    if (git?.head && metadata.source_commit && !/^<.*>$/.test(metadata.source_commit)
+      && metadata.source_commit !== "-" && metadata.source_commit !== git.head) {
+      stale.push({ path: expected.path, reason: `source_commit ${metadata.source_commit} 与当前 HEAD ${git.head} 不一致` });
+    }
+    if (expected.kind === "maintainer-guide") {
+      for (const heading of ["项目概览", "快速开始", "仓库地图", "工程分层", "工程约定", "变更工作流", "风险和保护边界", "文档维护"]) {
+        if (!new RegExp(`^## .*${heading}`, "m").test(text)) {
+          invalid.push({ path: expected.path, reason: `缺少章节：${heading}` });
+        }
+      }
+    }
+    if (expected.kind === "navigation-index") {
+      for (const field of ["路径", "职责", "主要入口", "关联测试", "风险", "状态", "source_commit", "last_reviewed"]) {
+        if (!text.includes(field)) invalid.push({ path: expected.path, reason: `缺少索引字段：${field}` });
+      }
+      for (const entry of documentationPathEntries(text)) {
+        const value = entry.value;
+        if (!value || value === "-" || /^<.*>$/.test(value) || value.includes("*")) continue;
+        if (path.isAbsolute(value) || value.split("/").includes("..")) {
+          invalid.push({ path: expected.path, reason: `第 ${entry.line} 行路径越界：${value}` });
+          continue;
+        }
+        const target = path.resolve(root, value);
+        const relative = path.relative(root, target);
+        if (relative.startsWith("..") || path.isAbsolute(relative)) {
+          invalid.push({ path: expected.path, reason: `第 ${entry.line} 行路径越界：${value}` });
+          continue;
+        }
+        if (!fs.existsSync(target)) {
+          invalid.push({ path: expected.path, reason: `第 ${entry.line} 行引用路径不存在：${value}` });
+          continue;
+        }
+        if (fs.lstatSync(target).isSymbolicLink()) {
+          invalid.push({ path: expected.path, reason: `第 ${entry.line} 行引用符号链接：${value}` });
+        }
+      }
+    }
+    const seenPaths = new Set();
+    for (const entry of documentationPathEntries(text)) {
+      if (/^<.*>$/.test(entry.value) || entry.value === "-" || entry.value.includes("*")) continue;
+      if (seenPaths.has(entry.value)) {
+        invalid.push({ path: expected.path, reason: `第 ${entry.line} 行重复索引路径：${entry.value}` });
+      }
+      seenPaths.add(entry.value);
+    }
+    for (const link of documentationLinks(text)) {
+      const targetValue = link.split(/[?#]/, 1)[0];
+      if (!targetValue || targetValue.startsWith("#") || /^[a-z][a-z0-9+.-]*:/i.test(targetValue)) continue;
+      if (path.isAbsolute(targetValue) || targetValue.split("/").includes("..")) {
+        invalid.push({ path: expected.path, reason: `Markdown 链接越界：${link}` });
+        continue;
+      }
+      const target = path.resolve(root, path.dirname(expected.path), targetValue);
+      const relative = path.relative(root, target);
+      if (relative.startsWith("..") || path.isAbsolute(relative) || !fs.existsSync(target)) {
+        invalid.push({ path: expected.path, reason: `Markdown 链接路径不存在：${link}` });
+      }
+    }
+  }
+
+  if (missing.length) warnings.push(`缺少代码仓库说明文件：${missing.join(", ")}`);
+  if (invalid.length) errors.push(...invalid.map((item) => `${item.path}: ${item.reason}`));
+  if (stale.length) warnings.push(...stale.map((item) => `${item.path}: ${item.reason}`));
+  const hasTemplatePlaceholders = files.some((file) => file.source_commit?.startsWith("<") || file.status === null);
+  if (new Set(statuses).size > 1) {
+    errors.push(`代码仓库说明文档状态冲突：${[...new Set(statuses)].join(", ")}`);
+  }
+  const status = invalid.length || errors.length
+    ? "invalid"
+    : stale.length
+      ? "stale"
+      : missing.length
+        ? "missing"
+        : statuses.some((value) => value === "stale")
+          ? "stale"
+          : hasTemplatePlaceholders || statuses.some((value) => value === "observed")
+          ? "observed"
+          : "approved";
+  return {
+    status,
+    files,
+    missing,
+    invalid,
+    stale,
+    sensitive_file_count: invalid.filter((item) => item.reason.includes("敏感值")).length,
+    errors,
+    warnings,
+  };
+}
+
 function gitState(root) {
   const run = (args) => spawnSync("git", args, { cwd: root, encoding: "utf8", windowsHide: true });
   const topLevel = run(["rev-parse", "--show-toplevel"]);
@@ -593,8 +914,19 @@ export function inspectProjectState(target) {
     }
   }
 
+  const codeGit = inspectGitRepository(codeRoot);
+  const documentation = inspectCodebaseDocumentation(codeRoot, codeGit);
+  const confirmations = inspectConfirmationSummaries(root);
+  if (confirmations.errors.length) errors.push(...confirmations.errors);
+  codebase.summary.documentation = documentation;
+  codebase.summary.confirmations = confirmations;
+  errors.push(...documentation.errors);
+  const documentationWarnings = documentation.warnings;
+
   let state;
-  if (!installation.detected) {
+  if (errors.length) {
+    state = "workflow-inconsistent";
+  } else if (!installation.detected) {
     state = codebase.summary.has_code ? "codebase-uninitialized" : "empty-uninitialized";
   } else if (!installation.complete || errors.length) {
     state = "workflow-inconsistent";
@@ -604,7 +936,6 @@ export function inspectProjectState(target) {
     state = "workflow-ready";
   }
   const recommendation = recommendationFor(state, workflow, runtime);
-  const codeGit = inspectGitRepository(codeRoot);
   const workflowGit = inspectGitRepository(root);
   const syncWarnings = [];
   if (workflowGit.sync_status === "uncommitted") {
@@ -625,11 +956,12 @@ export function inspectProjectState(target) {
     workflow,
     runtime,
     codebase: codebase.summary,
+    confirmations,
     git: codeGit,
     workflow_git: workflowGit,
     recommendation,
     errors,
-    warnings: [...codebase.warnings, ...syncWarnings],
+    warnings: [...codebase.warnings, ...documentationWarnings, ...syncWarnings],
   };
 }
 
@@ -701,6 +1033,10 @@ function adoptionMarkdown(initialState, scan, result) {
   if (!artifactTypes.some((type) => /architecture.*baseline/.test(type))) gaps.push("缺少经确认的架构基线。");
   if (scan.summary.has_code && !scan.summary.categories.test) gaps.push("未发现可识别的自动化测试文件，需人工核对测试入口。");
   if (!result.git.repository) gaps.push("当前目录不是有效 Git 仓库，分支和提交身份不可用。");
+  const documentation = result.codebase.documentation;
+  if (documentation?.status === "missing") gaps.push("代码仓库说明书或导航索引缺失，需要在维护者确认后补齐。");
+  if (documentation?.status === "invalid") gaps.push("代码仓库说明书或导航索引存在结构、路径或敏感内容问题，Bootstrap 已阻止将其视为可信上下文。");
+  if (documentation?.status === "stale") gaps.push("代码仓库说明书或导航索引相对当前提交过期，需要更新 source_commit 并重新审阅。");
   return `# 存量项目接入评估
 
 ## 探测结论
@@ -712,6 +1048,14 @@ function adoptionMarkdown(initialState, scan, result) {
 - 检测技术：${scan.summary.technologies.join("、") || "未识别"}
 - 排除的敏感文件：${scan.summary.sensitive_file_count}
 
+## 代码仓库说明书与导航
+
+- 状态：\`${documentation?.status || "missing"}\`
+- 已发现：${(documentation?.files || []).filter((item) => item.status !== "missing").map((item) => item.path).join("、") || "无"}
+- 缺失：${(documentation?.missing || []).join("、") || "无"}
+- 失效：${(documentation?.invalid || []).map((item) => item.path).join("、") || "无"}
+- 过期：${(documentation?.stale || []).map((item) => item.path).join("、") || "无"}
+
 ## 上下文边界
 
 本报告只描述代码和仓库的可观察现状。代码行为不是已批准产品需求，自动归纳内容均保持 \`draft\`，必须通过产品和架构流程核对后才能成为正式基线。
@@ -777,6 +1121,7 @@ function writeBootstrapArtifacts(root, initialState, result, sourceScan = null)
     detected_at: result.detected_at,
     repository: result.git,
     codebase: scan.summary,
+    documentation: result.codebase.documentation,
     command_candidates: packageCommands(root, scan.files),
     constraints: [
       "Observed code is not an approved product requirement.",
@@ -833,6 +1178,8 @@ function writeBootstrapArtifacts(root, initialState, result, sourceScan = null)
     workflow: result.workflow,
     runtime: result.runtime,
     codebase: result.codebase,
+    documentation: result.codebase.documentation,
+    confirmations: result.confirmations,
     git: result.git,
     recommendation: result.recommendation,
     errors: result.errors,

package/lib/project-installer.mjs

@@ -8,6 +8,7 @@ import { fileURLToPath } from "node:url";
 import { isSeq, parse as parseYaml, parseDocument, stringify as stringifyYaml } from "yaml";
 import { assertPathInside, atomicWrite, filesUnder } from "./fs-utils.mjs";
 import { inspectCodeGraph } from "./codegraph.mjs";
+import { inspectCodebaseDocumentation, inspectConfirmationSummaries } from "./project-bootstrap.mjs";
 import { executeDeliveryStateCommand } from "./delivery-state.mjs";
 import { inspectHookConfig, managedHookConfigProjection, mergeHookConfig } from "./toml-hooks.mjs";
 import {
@@ -522,7 +523,7 @@ function bootstrapRuntimeSources(packageRoot, sourceTemplate) {
       relative: "bootstrap.mjs",
     },
     ...[
-      "project-bootstrap.mjs", "workspace.mjs", "yaml-runtime.mjs", "delivery-state.mjs",
+      "project-bootstrap.mjs", "communication-confirmation.mjs", "workspace.mjs", "yaml-runtime.mjs", "delivery-state.mjs",
       "history-anchor.mjs", "fs-utils.mjs",
     ].map((name) => ({
       source: path.join(packageRoot, "lib", name),
@@ -1918,6 +1919,28 @@ export function doctorProject(target, options = {}) {
 
   const workflowGit = gitTopLevel(target);
   const codeGit = workspace ? gitTopLevel(workspace.codeRoot) : null;
+  if (workspace) {
+    const documentation = inspectCodebaseDocumentation(workspace.codeRoot);
+    checks.push({
+      ok: documentation.status !== "invalid",
+      required: false,
+      scope: "codebase-documentation",
+      message: documentation.status === "missing"
+        ? "code repository handbook/index are not installed; Bootstrap or maintainers may add them"
+        : `code repository handbook/index status: ${documentation.status}`,
+    });
+    const confirmations = inspectConfirmationSummaries(target);
+    checks.push({
+      ok: confirmations.status !== "invalid",
+      required: false,
+      scope: "communication-confirmation",
+      message: confirmations.status === "absent"
+        ? "no communication confirmation summaries are present"
+        : confirmations.status === "invalid"
+          ? `communication confirmation summaries are invalid: ${confirmations.errors.join("; ")}`
+          : `${confirmations.summaries.length} communication confirmation summary(ies) validate; frontier=${confirmations.summaries.flatMap((item) => item.frontier).join(",") || "empty"}`,
+    });
+  }
   const workflowCommonGit = workflowGit ? gitCommonDirectory(target) : null;
   const codeCommonGit = codeGit && workspace ? gitCommonDirectory(workspace.codeRoot) : null;
   checks.push({
@@ -2075,6 +2098,7 @@ export function doctorProject(target, options = {}) {
   const bootstrapFiles = [
     "bootstrap.mjs",
     "project-bootstrap.mjs",
+    "communication-confirmation.mjs",
     "workspace.mjs",
     "yaml-runtime.mjs",
     "delivery-state.mjs",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-delivery-workflow",
-  "version": "0.5.1",
+  "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
@@ -52,6 +54,10 @@ Treat repository scans as observations, not approved product or architecture tru
 
 Do not replace existing product, architecture, test, or release baselines. Keep the project-state report and related observations outside the formal artifact registry while they remain working drafts, preserve every timestamped bootstrap run, and update only the `.workflow/delivery/bootstrap/latest.yaml` pointer.
 
+### 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. 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
 
 Codex lifecycle Hooks provide audit and heartbeat data only. Versioned Evolution Hooks may return `pass`, `warn`, or an approved `block`, but they never select or complete tasks and never mutate formal workflow state. A bootstrap report may recommend recovery, but `$ai-delivery-checkpoint-task` remains authoritative for task order, dependency readiness, worktree reconciliation, and idempotent continuation. Route pending feedback and extension evaluation to `$ai-delivery-evolve-workflow` only at a task, version, or explicit review safe point.

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
@@ -60,6 +62,8 @@ Checkpoint after every externally meaningful milestone, before a long command, a
 
 Use shared shards and the newest shared checkpoint as the portable recovery source. If local runtime is absent and `next_action_owner` is `agent`, `recover` restores it from shared state. For `user` or `external`, report the wait state without hydration; after the input arrives, `activate` performs the atomic hydration and owner transfer. If local and shared revisions or semantic checksums differ, stop for reconciliation. Inspect both Git repositories before resuming. Report pending `.workflow/delivery/runtime/evolution/pending/` events, but defer their evaluation until the recovered task reaches a safe point.
 
+Confirmation waits persist the summary path, question identity, frontier round, and an idempotent next action. `user` and `external` ownership remains strict zero-mutation wait until explicit input transfer.
+
 Generate a compact recovery report from snapshots, checkpoints, Hook events, Git, and workspace state. Return active work and failed tasks in `retryable_task_ids` by default; use `--include-closed` only when completed or abandoned details are required for an explicit audit. For each iteration, report total, completed, closed, remaining, active, retryable, queued, dependency-ready, and waiting tasks plus one deterministic `recommended_task_id`. Prefer an interrupted or active task, then the lowest-sequence failed task requiring `activate --new-attempt --phase repair`, then the lowest-sequence queued task whose dependencies are all `completed`. Resume only idempotent steps. Re-read production and external systems before any deployment recovery; never replay production deployment automatically.
 
 ## Hook Boundary

package/skills/ai-delivery-checkpoint-task/references/checkpoint-contract.md

@@ -77,6 +77,8 @@ For an installed dual-repository project, `task-state.mjs` resolves `code_branch
 
 `next_action_owner` is required in persisted state and has exactly three values: `agent`, `user`, or `external`; explicit null, empty, boolean, numeric, or unknown values are invalid. `user` and `external` are zero-mutation wait states. `recover` may report shared wait state but must not hydrate local task or resume files for it. After the required input arrives, `activate` requires both `--next-action-owner agent` and a new idempotent `--next-action`; it may atomically hydrate a missing local runtime snapshot from the matching shared shard and transfer ownership in the same transition. Same-revision local and shared content must have identical semantic checksums. Evidence arrays are ordered sets: replaying an already recorded `--evidence` value does not append a duplicate.
 
+When waiting on a confirmation frontier, persist the summary path, `question_id`, `frontier_round`, and summary checksum in checkpoint evidence. Repeated answers are idempotent; superseding a decision appends a new record and never overwrites prior confirmation.
+
 Pass `--state-root` when worktrees must write to one shared primary state directory. Pass `--worktree` during init so the script writes a local `.workflow/delivery/runtime/active-task.json` marker pointing to that state root. Later `checkpoint`, `finish`, and `recover` commands automatically use the marker's shared state root.
 
 Use `finish` only with `completed`, `blocked`, `interrupted`, `failed`, or `abandoned`. Closed statuses `completed`, `failed`, and `abandoned` are rejected by `checkpoint`; use `checkpoint` only for continuing or paused work.

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

@@ -5,30 +5,35 @@ 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
 
 1. Recover or initialize the `06-version-closeout` task through `$ai-delivery-checkpoint-task`.
 2. Run `node .workflow/tools/state/state.mjs verify --history`.
-3. Require a passing immutable candidate, a completed Candidate Assurance receipt for that same candidate, closed version tasks, complete requirement/test/material traceability, and no unresolved blocking defect.
+3. Require a passing immutable candidate, a completed Candidate Assurance receipt for that same candidate, a resolved or superseded product impact assessment bound to the candidate, closed version tasks, complete requirement/test/material traceability, and no unresolved blocking defect.
 4. Read the preceding version lineage and Git policy. Require the candidate to descend from the current `line/<product-id>` head, except for the first version.
 
 ## Close The Version
 
 1. Read `.workflow/config/workspace.yaml`; verify the candidate in the configured code repository and populate `repo_id`, `code_commit`, `source_path`, and SHA-256.
-2. Freeze the candidate commit and create code `version-ready/<version-id>/rN`. Never move or replace an existing Tag; increment `rN` only for a newly verified replacement candidate.
-3. Fast-forward code `line/<product-id>` to the tagged commit. Never advance code `main` here.
-4. Copy the closeout assets into `.workflow/iterations/<version-id>/06-version-closeout/`, populate the code Tag identity, and compute the final manifest SHA-256.
-5. Register the immutable closeout semantic revision directly as `release-ready` with the formal state CLI, and complete `06-version-closeout` with that registered artifact as evidence. Do not register a draft and mutate its status in place.
-6. Commit all version workflow materials and create immutable workflow `workflow-ready/<version-id>/rN` at that exact workflow commit. Record the workflow commit, workflow Tag, and manifest checksum in the lineage index without rewriting the tagged manifest.
-7. Verify both Tags and the manifest checksum. Inspect the current development scope revision, then run `state.mjs transition --expected-scope-revision <revision> --event version-closed --iteration-id <version-id> --artifact-id <closeout-artifact-id>` to update the audited cumulative development identity. Never edit `latest_line_version_id` directly.
-8. Run `state.mjs snapshot create --id <version-id> --reason version-boundary`, then `state.mjs verify --history --since-anchor`. The first trusted anchor performs a full-history audit before creation; later anchors validate the suffix from the previous anchor.
-9. Archive tasks with `task-state.mjs archive-version --version-status release-ready --candidate-id <candidate-id> --evidence <closeout-artifact-id>`. The command must first obtain `snapshot references` from the formal-state CLI and fail before writing if the anchor, scope, or candidate is missing. Verify that the version manifest references checksummed task summaries, complete attempt values, scope, candidate, Gate decisions, and the version-boundary anchor; then checkpoint the Git, anchor, and archive evidence and finish the task.
-10. Invoke `$ai-delivery-evolve-workflow evaluate --safe-point version --iteration-id <version-id>`. Record trial results and decisions, but never use an Evolution result as release intent.
+2. Validate the candidate's codebase handbook and navigation index at the exact code commit. Record their status, checksums, owner, last review, and any stale/invalid findings in closeout evidence; require repair or explicit maintainer acceptance before marking documentation evidence complete.
+3. Freeze the candidate commit and create code `version-ready/<version-id>/rN`. Never move or replace an existing Tag; increment `rN` only for a newly verified replacement candidate.
+4. Fast-forward code `line/<product-id>` to the tagged commit. Never advance code `main` here.
+5. Copy the closeout assets into `.workflow/iterations/<version-id>/06-version-closeout/`, populate the code Tag identity, and compute the final manifest SHA-256.
+6. Register the immutable closeout semantic revision directly as `release-ready` with the formal state CLI, and complete `06-version-closeout` with that registered artifact as evidence. Do not register a draft and mutate its status in place.
+7. Commit all version workflow materials and create immutable workflow `workflow-ready/<version-id>/rN` at that exact workflow commit. Record the workflow commit, workflow Tag, and manifest checksum in the lineage index without rewriting the tagged manifest.
+8. Verify both Tags and the manifest checksum. Inspect the current development scope revision, then run `state.mjs transition --expected-scope-revision <revision> --event version-closed --iteration-id <version-id> --artifact-id <closeout-artifact-id>` to update the audited cumulative development identity. Never edit `latest_line_version_id` directly.
+9. Run `state.mjs snapshot create --id <version-id> --reason version-boundary`, then `state.mjs verify --history --since-anchor`. The first trusted anchor performs a full-history audit before creation; later anchors validate the suffix from the previous anchor.
+10. Archive tasks with `task-state.mjs archive-version --version-status release-ready --candidate-id <candidate-id> --evidence <closeout-artifact-id>`. The command must first obtain `snapshot references` from the formal-state CLI and fail before writing if the anchor, scope, or candidate is missing. Verify that the version manifest references checksummed task summaries, complete attempt values, scope, candidate, Gate decisions, and the version-boundary anchor; then checkpoint the Git, anchor, and archive evidence and finish the task.
+11. Invoke `$ai-delivery-evolve-workflow evaluate --safe-point version --iteration-id <version-id>`. Record trial results and decisions, but never use an Evolution result as release intent.
 
 ## Stop Boundary
 
 Report the release-ready version, code Tag, workflow Tag, manifest checksum, cumulative line head, archived task count, and next planned version. Stop and wait for either the next version iteration or an explicit user release request. Do not invoke release orchestration implicitly.
 
 Read [version-closeout-contract.md](references/version-closeout-contract.md) before writing outputs.
+
+Before closeout, validate the confirmation summary and ensure confirmed product, architecture, standard, and risk decisions have authority references and matching checksums. Deferred or open decisions remain visible in closeout evidence. Closing a version does not imply release intent.

package/skills/ai-delivery-close-version/references/version-closeout-contract.md

@@ -4,6 +4,7 @@
 
 - planned version ID, product ID, predecessor version, and iteration plan;
 - immutable candidate ID, commit, artifact digest, and passing verification decision;
+- resolved or superseded `product-impact-assessment.yaml` bound to the candidate and the aligned product baseline;
 - complete closed-task summary and unresolved-risk statement;
 - current `line/<product-id>` head and applicable standards baseline.
 
@@ -17,4 +18,4 @@ After Candidate Assurance has completed for the same immutable candidate, the `r
 
 ## Failure rules
 
-Block closeout for active tasks, mutable candidates, failed verification, missing materials, Git divergence, an existing tag resolving to another commit, or a candidate that does not include a synchronized production hotfix. Mark affected candidates `stale`; never edit a previously closed version.
+Block closeout for active tasks, mutable candidates, failed verification, missing materials, an unresolved or checksum-drifted product impact assessment, Git divergence, an existing tag resolving to another commit, or a candidate that does not include a synchronized production hotfix. Mark affected candidates `stale`; never edit a previously closed version.