ai-delivery-workflow 0.5.1 → 0.6.0

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

@@ -3,7 +3,7 @@
 > 当前双仓目录、初始化规则、状态分层和 Git 边界见 [DUAL-REPOSITORY-WORKSPACE.zh-CN.md](DUAL-REPOSITORY-WORKSPACE.zh-CN.md)。
 
 > 适用目录：工作流发行仓库  
-> 适用包版本：`ai-delivery-workflow@0.5.1`
+> 适用包版本：`ai-delivery-workflow@0.6.0`
 > 使用方法和完整流程：[PROJECT-MANUAL.zh-CN.md](PROJECT-MANUAL.zh-CN.md)  
 > CLI 安装参数：[CLI-PARAMETER-REFERENCE.zh-CN.md](CLI-PARAMETER-REFERENCE.zh-CN.md)
 > CodeGraph 可选集成：[CODEGRAPH-INTEGRATION.zh-CN.md](CODEGRAPH-INTEGRATION.zh-CN.md)

package/docs/MAINTENANCE-VERIFICATION.zh-CN.md

@@ -5,8 +5,8 @@
 ## 1. npm 发布预检
 
 ```powershell
-npm run release:check -- prepare --version 0.5.1
-npm run release:check -- verify --version 0.5.1 --commit <40位提交ID>
+npm run release:check -- prepare --version 0.6.0
+npm run release:check -- verify --version 0.6.0 --commit <40位提交ID>
 ```
 
 `prepare` 默认执行 `full` 检查：清单与锁文件版本、`main`、干净工作树、Tag 可用性、全量测试、25 个 Skill、审计验证、`npm pack --dry-run`、`npm publish --dry-run`、官方 registry、版本未占用、npm 身份和 `auth-and-writes` 2FA。两个 dry-run 还必须返回一致的包名、版本、文件清单、文件数量和制品摘要；本包必须包含 `bin/`、`docs/`、`lib/`、`skills/` 及有效的 `bin.ai-delivery`。任一项失败都会输出 `decision: fail` 并返回非零退出码。

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

@@ -18,7 +18,7 @@ workspace/code/.git            代码 Git
 初始化器还会合并根 `.gitattributes`，对 `.workflow/**`、项目级 `ai-delivery-*` Skills、`.codex/config.toml`、`AGENTS.md`、`.gitignore` 和 `.gitattributes` 强制 `eol=lf`。这是 checksum 可移植性约束；不会修改嵌套代码仓的换行策略。已冻结的旧迭代证据必须在根 `.gitattributes` 中使用精确路径，或“固定迭代目录 + 文件名 glob”的窄 `-text` 规则登记后，才能保留 raw checksum；嵌套或全局 attributes 不能自行获得该例外。产品、控制、工具等其他路径和 `text eol=crlf` 覆盖也不享受该例外。缺失或无效规则会使 `doctor` 失败，避免 Windows checkout 后正式状态和物料被误判为篡改。
 
 > 文档版本：1.0  
-> 适用包版本：`ai-delivery-workflow@0.5.1`
+> 适用包版本：`ai-delivery-workflow@0.6.0`
 > 默认文档语言：简体中文  
 > 文件级索引：[FILE-REFERENCE.zh-CN.md](FILE-REFERENCE.zh-CN.md)  
 > CodeGraph 可选集成：[CODEGRAPH-INTEGRATION.zh-CN.md](CODEGRAPH-INTEGRATION.zh-CN.md)

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

@@ -7,7 +7,7 @@
 ## 1. 当前基线
 
 - 当前仓库是 `ai-delivery-workflow` 的维护与发行源码仓库，不是安装了工作流的业务项目。
-- 当前正式源码候选版本为 `0.5.1`（待完成发布 Gate）；上一版 `0.5.0` 的提交、Git tag、npm 包身份及 Workflow Manager 的历史 `0.4.0` 候选身份、校验和和生命周期证据仍记录在维护仓库的 `audit/WORKFLOW-MANAGER-P0-P1-P2-CLOSURE.md`，这些历史记录不可改写。候选包和展开验证工作区保留在被忽略的 `.tmp/`。
+- 当前正式源码候选版本为 `0.6.0`（待完成发布 Gate）；上一版 `0.5.1` 的提交、Git tag、npm 包身份及 Workflow Manager 的历史 `0.4.0` 候选身份、校验和和生命周期证据仍记录在维护仓库的 `audit/WORKFLOW-MANAGER-P0-P1-P2-CLOSURE.md`，这些历史记录不可改写。候选包和展开验证工作区保留在被忽略的 `.tmp/`。
 - 正式维护源码位于 `bin/`、`lib/`、`skills/`、`docs/`、`verification/` 和 `audit/`。
 - Workflow Manager 设计原型位于 `prototypes/workflow-manager/`，业务项目原型夹具位于 `prototypes/order-ops-business/`。两者是可版本化设计资产，不进入发行包，也不等于正式前端已经实现；运行时依赖、构建产物和一次性验证工作区仍放在 `.tmp/`。
 

package/lib/communication-confirmation.mjs

@@ -0,0 +1,177 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { parse as parseYaml, stringify as stringifyYaml } from "./yaml-runtime.mjs";
+
+export const CONFIRMATION_STATUSES = new Set(["proposed", "confirmed", "rejected", "deferred", "superseded"]);
+export const CONFIRMATION_CATEGORIES = new Set([
+  "observed_fact", "business_fact", "business_decision", "domain_term", "business_constraint",
+  "architecture_decision", "standard_decision", "risk", "assumption", "open_question",
+  "execution_fact", "execution_decision",
+]);
+export const NEXT_ACTION_OWNERS = new Set(["agent", "user", "external"]);
+
+const CLOSED_STATUSES = new Set(["confirmed", "rejected", "superseded"]);
+const ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/;
+
+function text(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+function list(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+function addError(errors, location, message) {
+  errors.push(`${location}: ${message}`);
+}
+
+function stableValue(value) {
+  if (Array.isArray(value)) return value.map(stableValue);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.keys(value).sort().map((key) => [key, stableValue(value[key])]));
+  }
+  return value;
+}
+
+function sameRecord(left, right) {
+  return JSON.stringify(stableValue(left)) === JSON.stringify(stableValue(right));
+}
+
+function recordIsClosed(record, byId, visiting = new Set()) {
+  if (!record) return false;
+  if (record.status !== "superseded") return CLOSED_STATUSES.has(record.status);
+  if (!record.superseded_by || visiting.has(record.confirmation_id)) return false;
+  visiting.add(record.confirmation_id);
+  const replacement = byId.get(record.superseded_by);
+  return Boolean(replacement) && recordIsClosed(replacement, byId, visiting);
+}
+
+function detectCycles(records, byId, errors) {
+  const visiting = new Set();
+  const visited = new Set();
+  const visit = (record) => {
+    if (visited.has(record.confirmation_id)) return;
+    if (visiting.has(record.confirmation_id)) {
+      addError(errors, `records.${record.confirmation_id}`, "dependency cycle detected");
+      return;
+    }
+    visiting.add(record.confirmation_id);
+    for (const dependencyId of list(record.depends_on)) {
+      const dependency = byId.get(dependencyId);
+      if (dependency) visit(dependency);
+    }
+    visiting.delete(record.confirmation_id);
+    visited.add(record.confirmation_id);
+  };
+  records.forEach(visit);
+}
+
+export function validateConfirmationSummary(summary, options = {}) {
+  const errors = [];
+  const warnings = [];
+  if (!summary || typeof summary !== "object" || Array.isArray(summary)) {
+    return { valid: false, errors: ["summary: must be a mapping"], warnings: [], frontier: [], blocked_proposals: [] };
+  }
+  if (summary.schema_version !== 1) addError(errors, "schema_version", "must equal 1");
+  for (const field of ["summary_id", "node", "iteration_id", "owner", "source_revision", "updated_at"]) {
+    if (!text(summary[field])) addError(errors, field, "must be a non-empty string");
+  }
+  if (!ID_PATTERN.test(String(summary.summary_id || ""))) addError(errors, "summary_id", "has invalid format");
+  if (!Number.isInteger(summary.version) || summary.version < 1) addError(errors, "version", "must be a positive integer");
+  if (!Number.isInteger(summary.frontier_round) || summary.frontier_round < 1) addError(errors, "frontier_round", "must be a positive integer");
+  if (!Array.isArray(summary.records)) addError(errors, "records", "must be an array");
+  const records = list(summary.records);
+  const byId = new Map();
+  records.forEach((record, index) => {
+    const prefix = `records[${index}]`;
+    if (!record || typeof record !== "object" || Array.isArray(record)) {
+      addError(errors, prefix, "must be a mapping");
+      return;
+    }
+    if (!text(record.confirmation_id) || !ID_PATTERN.test(record.confirmation_id || "")) addError(errors, `${prefix}.confirmation_id`, "must be a stable ID");
+    if (byId.has(record.confirmation_id)) addError(errors, `${prefix}.confirmation_id`, "must be unique");
+    else byId.set(record.confirmation_id, record);
+    if (!text(record.question_id) || !ID_PATTERN.test(record.question_id || "")) addError(errors, `${prefix}.question_id`, "must be a stable ID");
+    if (!CONFIRMATION_CATEGORIES.has(record.category)) addError(errors, `${prefix}.category`, "is not an allowed category");
+    if (!CONFIRMATION_STATUSES.has(record.status)) addError(errors, `${prefix}.status`, "is not an allowed status");
+    if (!Number.isInteger(record.frontier_round) || record.frontier_round < 1) addError(errors, `${prefix}.frontier_round`, "must be a positive integer");
+    if (!text(record.question)) addError(errors, `${prefix}.question`, "must be provided");
+    if (!text(record.recommendation)) addError(errors, `${prefix}.recommendation`, "must be provided");
+    if (!Array.isArray(record.depends_on)) addError(errors, `${prefix}.depends_on`, "must be an array");
+    if (!Array.isArray(record.evidence_refs)) addError(errors, `${prefix}.evidence_refs`, "must be an array");
+    if (!Array.isArray(record.authority_refs)) addError(errors, `${prefix}.authority_refs`, "must be an array");
+    if (!NEXT_ACTION_OWNERS.has(record.next_action_owner)) addError(errors, `${prefix}.next_action_owner`, "must be agent, user, or external");
+    if (!text(record.next_action)) addError(errors, `${prefix}.next_action`, "must be explicit and idempotent");
+    if (record.status === "proposed" && record.decision !== null && record.decision !== undefined) addError(errors, `${prefix}.decision`, "must be null while proposed");
+    if (["confirmed", "rejected"].includes(record.status)) {
+      if (!text(record.decision)) addError(errors, `${prefix}.decision`, "is required after a decision");
+      if (!text(record.actor)) addError(errors, `${prefix}.actor`, "is required after a decision");
+      if (!text(record.confirmed_at)) addError(errors, `${prefix}.confirmed_at`, "is required after a decision");
+      if (!list(record.authority_refs).length && !options.allowUnlinkedConfirmed) addError(errors, `${prefix}.authority_refs`, "must point to the owning artifact or handoff");
+    }
+    if (["observed_fact", "execution_fact"].includes(record.category) && !list(record.evidence_refs).length) addError(errors, `${prefix}.evidence_refs`, "is required for an observed fact");
+    if (record.status === "deferred" && record.next_action_owner === "agent") addError(errors, `${prefix}.next_action_owner`, "deferred decisions require user or external ownership");
+    if (record.status === "superseded" && !text(record.supersedes) && !text(record.superseded_by)) addError(errors, prefix, "must point to a replacement or predecessor");
+  });
+
+  for (const record of records) {
+    for (const dependencyId of list(record.depends_on)) {
+      if (!byId.has(dependencyId)) addError(errors, `records.${record.confirmation_id}.depends_on`, `unknown dependency ${dependencyId}`);
+      if (dependencyId === record.confirmation_id) addError(errors, `records.${record.confirmation_id}.depends_on`, "cannot depend on itself");
+    }
+    if (record.supersedes && !byId.has(record.supersedes)) addError(errors, `records.${record.confirmation_id}.supersedes`, `unknown record ${record.supersedes}`);
+    if (record.superseded_by && !byId.has(record.superseded_by)) addError(errors, `records.${record.confirmation_id}.superseded_by`, `unknown record ${record.superseded_by}`);
+  }
+  detectCycles(records, byId, errors);
+  const frontier = records.filter((record) => record.status === "proposed"
+    && list(record.depends_on).every((dependencyId) => recordIsClosed(byId.get(dependencyId), byId)));
+  const blockedProposals = records.filter((record) => record.status === "proposed" && !frontier.includes(record));
+  if (summary.shared_understanding === true && frontier.length) addError(errors, "shared_understanding", "cannot be true while frontier is non-empty");
+  if (summary.shared_understanding === true && blockedProposals.length) addError(errors, "shared_understanding", "cannot be true while a proposed decision is blocked");
+  if (summary.shared_understanding === true) {
+    if (!text(summary.shared_understanding_actor)) addError(errors, "shared_understanding_actor", "is required after user confirmation");
+    if (!text(summary.shared_understanding_confirmed_at)) addError(errors, "shared_understanding_confirmed_at", "is required after user confirmation");
+  }
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+    frontier: frontier.map((record) => record.confirmation_id),
+    blocked_proposals: blockedProposals.map((record) => record.confirmation_id),
+  };
+}
+
+export function readConfirmationSummary(file, options = {}) {
+  const absolute = path.resolve(file);
+  const bytes = fs.readFileSync(absolute);
+  const summary = parseYaml(bytes.toString("utf8"));
+  return {
+    file: absolute,
+    checksum: crypto.createHash("sha256").update(bytes).digest("hex"),
+    summary,
+    validation: validateConfirmationSummary(summary, options),
+  };
+}
+
+export function writeConfirmationSummary(file, summary) {
+  const validation = validateConfirmationSummary(summary);
+  if (!validation.valid) throw new Error(`Invalid confirmation summary:\n${validation.errors.join("\n")}`);
+  const absolute = path.resolve(file);
+  if (fs.existsSync(absolute)) {
+    const existing = readConfirmationSummary(absolute, { allowUnlinkedConfirmed: false });
+    if (existing.summary.summary_id !== summary.summary_id) throw new Error("summary_id cannot change for an existing confirmation summary");
+    if (summary.version < existing.summary.version) throw new Error("confirmation summary version cannot move backwards");
+    const incoming = new Map(list(summary.records).map((record) => [record.confirmation_id, record]));
+    for (const record of list(existing.summary.records)) {
+      if (CLOSED_STATUSES.has(record.status) && incoming.has(record.confirmation_id)
+        && !sameRecord(record, incoming.get(record.confirmation_id))) {
+        throw new Error(`closed confirmation ${record.confirmation_id} is immutable; append a superseding record`);
+      }
+    }
+    if (summary.version === existing.summary.version && sameRecord(existing.summary, summary)) return validation;
+  }
+  fs.mkdirSync(path.dirname(absolute), { recursive: true });
+  fs.writeFileSync(absolute, stringifyYaml(summary), "utf8");
+  return validation;
+}

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,199 @@ 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());
+}
+
+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 +831,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 +853,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 +873,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 +950,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 +965,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 +1038,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 +1095,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.6.0",
   "description": "Project-scoped Codex skills and hooks for artifact-driven AI software delivery",
   "type": "module",
   "repository": {

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

@@ -52,6 +52,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. Never infer an approved rule from the generated inventory, and never overwrite these files 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

@@ -60,6 +60,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