ai-delivery-workflow 0.5.1 → 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

@@ -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)
@@ -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/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)
@@ -262,6 +262,7 @@ npx ai-delivery-workflow@latest upgrade .
 | `ai-delivery inspect [project]` | 否 | 输出机器可读的项目、代码、流程和运行时状态。 |
 | `ai-delivery bootstrap [project]` | 视状态而定 | 初始化空项目或存量项目上下文，或把中断项目路由到恢复。 |
 | `ai-delivery bootstrap [project] --dry-run` | 否 | 预览引导动作。 |
+| `node .workflow/tools/bootstrap/bootstrap.mjs project-index [project] [--output <path>]` | 是（写入工作流仓库） | 读取代码仓库唯一事实源 `docs/CODEBASE_INDEX.md`，生成带 `source_checksum` 的 `.workflow/delivery/bootstrap/codebase-index.yaml` 机器投影；投影不得写回代码仓库。 |
 | `ai-delivery doctor [project]` | 否 | 校验发行包表面、安装清单、关键 skills、Hook、运行时和持久项目文件；排除 `.workflow/delivery/runtime`，状态 inspect 使用 16 MiB 有界缓冲并验证 JSON 协议，Git attributes 使用有界批次检查。 |
 | `ai-delivery codegraph setup [project]` | 是 | 显式关闭 telemetry，并为配置中的代码仓初始化本地 CodeGraph 索引。 |
 | `ai-delivery codegraph setup [project] --dry-run` | 否 | 只读验证 `CODEGRAPH_DIR`、索引文件与 Git 边界，只调用 `codegraph --version`，并输出 telemetry、local exclude 和初始化计划。 |
@@ -308,6 +309,14 @@ Page 决定和修改要求绑定精确 Revision、Page/Scene 及 checksum。修
 node .workflow/tools/bootstrap/bootstrap.mjs inspect
 ```
 
+代码仓库说明索引由维护者编辑 `docs/CODEBASE_INDEX.md`。需要给 Agent 或工具快速读取时，在工作流仓库根目录执行：
+
+```powershell
+node .workflow/tools/bootstrap/bootstrap.mjs project-index <project>
+```
+
+该命令只生成派生 YAML，消费者必须校验 `source_checksum`；不要直接编辑投影或把投影复制回代码仓库。
+
 引导器只返回以下五种状态之一：
 
 | 状态 | 含义 | 推荐动作 |

package/docs/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;
+}