ai-delivery-workflow 0.2.2 → 0.4.0

package/README.md

@@ -6,18 +6,23 @@
 
 一套只安装到当前项目的 AI 全流程研发 Skills、Hook、产物契约和 checkpoint 机制。研发版本可以持续递进并归档为 `release-ready`；生产发布由用户独立触发并选择累计截止版本。
 
-体验设计采用分阶段可运行原型：先交付可实际操作的低保真原型并通过人工 `UX-LF`，再确认视觉系统和 UI 框架（`UX-VS`），最后交付可运行正式 UI（`UX-UI`）。每次调整立即记录；全部候选确认后统一与产品需求双向核对。下游只消费 `ui-handoff.yaml` 和结构化 `experience_change_id`，不从截图或视觉差异猜测新增、修改与停用内容。
+体验设计采用生产兼容的可运行原型：先确认视觉系统和 UI 框架（`UX-VS`），再交付覆盖完整交互与状态的正式 UI 原型（`UX-UI`）。每次调整立即记录；全部候选确认后统一与产品需求双向核对。下游只消费 `ui-handoff.yaml` 和结构化 `experience_change_id`，不从截图或视觉差异猜测新增、修改与停用内容。
 
 ## 文档
 
 - [维护仓库 AI 边界](AGENTS.md)
 - [完整中文项目手册](docs/PROJECT-MANUAL.zh-CN.md)
+- [CLI 安装参数参考](docs/CLI-PARAMETER-REFERENCE.zh-CN.md)
+- [CodeGraph 可选集成指南](docs/CODEGRAPH-INTEGRATION.zh-CN.md)
+- [Microcks Mock System 使用指南](docs/MOCK-SYSTEM.zh-CN.md)
 - [双仓工作区使用与维护说明](docs/DUAL-REPOSITORY-WORKSPACE.zh-CN.md)
 - [逐文件参考](docs/FILE-REFERENCE.zh-CN.md)
-- [工作流物料查看器使用指南](docs/VIEWER-USER-GUIDE.zh-CN.md)
-- [工作流物料查看器维护指南](docs/VIEWER-MAINTENANCE.zh-CN.md)
+- [工作流管理器使用指南](docs/VIEWER-USER-GUIDE.zh-CN.md)
+- [工作流管理器维护指南](docs/VIEWER-MAINTENANCE.zh-CN.md)
 - [正式状态 CLI 使用指南](docs/STATE-CLI-USER-GUIDE.zh-CN.md)
 - [正式状态 CLI 维护指南](docs/STATE-CLI-MAINTENANCE.zh-CN.md)
+- [npm 版本与发布管理规范](docs/NPM-RELEASE-MANAGEMENT.zh-CN.md)
+- [维护仓库验证工具：发布预检、成本基准与可信平台证明](docs/MAINTENANCE-VERIFICATION.zh-CN.md)
 - [审计物料：历史 V1、当前契约 V2 与五版本发布列车示例](audit/README.md)
 - [审计物料逐文件用途](audit/FILE-GUIDE.zh-CN.md)
 - [永久验证源码说明](verification/README.zh-CN.md)
@@ -31,6 +36,27 @@ npx ai-delivery-workflow@latest init <workspace> --code-path code --code-id app
 npx ai-delivery-workflow@latest doctor <workspace>
 ```
 
+已由用户安装 CodeGraph CLI 时，可显式为配置中的代码仓初始化或同步本地索引：
+
+```bash
+npx ai-delivery-workflow@latest codegraph setup <workspace>
+npx ai-delivery-workflow@latest codegraph sync <workspace>
+```
+
+该能力是可降级的代码导航适配器，不进入正式状态或 Gate，也不会安装全局 MCP。完整边界见 [CodeGraph 可选集成指南](docs/CODEGRAPH-INTEGRATION.zh-CN.md)。
+
+需要为 Prototype 模拟第三方协议时，显式初始化并启动项目级 Microcks，再从 tracked External Dependency Mock catalog 同步合同：
+
+```bash
+npx ai-delivery-workflow@latest mock setup <workspace>
+npx ai-delivery-workflow@latest mock start <workspace>
+npx ai-delivery-workflow@latest mock sync <workspace>
+npx ai-delivery-workflow@latest mock freeze <workspace> --experience .workflow/experience \
+  --scenario-pack mock-scenario-pack-request.yaml --dry-run
+```
+
+系统只绑定 loopback，运行数据库与流量可丢弃，不自动安装 Docker/Podman。External Dependency 与 Product Backend Mock 使用隔离 catalog；每个 Review Scene 经合同和脱敏校验映射到唯一 scenario，受管 UI 的实际导出定义以 checksum 绑定并通过同一协议/场景校验后，才可在人工确认 candidate checksum 后冻结、正式登记为不可变 Mock Scenario Pack。Product Backend Mock 不构成真实后端或端到端验收证据。完整契约见 [Microcks Mock System 使用指南](docs/MOCK-SYSTEM.zh-CN.md)。
+
 安装器会把 25 个 Skills 写入 `.agents/skills/`，把项目 Hook 合并到 `.codex/config.toml`，安装本地 Hook 记录器，并创建 `.workflow/iterations/`、`.workflow/releases/` 与项目级自进化控制环。所有研发流程文档默认写入 `.workflow/`；源码、自动化测试源码、仓库配置、镜像和二进制制品保留在各自原位置。安装器会保留既有项目配置，并在受管文件冲突时停止。
 
 安装器会在需要跨 Git clone 保留的空工作流目录中写入 `.gitkeep`，包括产品、架构、体验、迭代、发布及共享控制分片目录。删除这些占位文件会导致空目录不进入 Git，重新克隆后的 `doctor` 将判定核心结构缺失。
@@ -47,9 +73,9 @@ node .workflow/tools/state/state.mjs verify
 
 日常使用无需记忆这些命令。用户在项目根目录对 AI 说“开始”“继续”“下一步”或直接描述需求即可；AI 根据项目内 `AGENTS.md` 和 Skills 自主调用 Bootstrap、Checkpoint、专业节点与发布流程，用户只负责业务回答和人工 Gate。中断任务通过 `next_action_owner` 区分 AI、用户和外部责任方；等待用户或外部输入时只读恢复，不得重复增加 attempt、revision、evidence 或 checkpoint。
 
-正式状态 schema 2 将研发与发布拆成 `development_state` 和 `release_state`。研发使用 `iteration-started`，用户明确发起发布后使用 `release-started`；两者分别维护 scope、节点、Gate 和局部 revision，可并行推进且互不重置。状态 CLI 同时强制节点依赖、成功证据和当前节点尝试的必需 Gate。
+正式状态 schema 2 将研发与发布拆成 `development_state` 和 `release_state`。研发使用 `iteration-started`，用户明确发起发布后使用 `release-started`；两者分别维护 scope、节点、Gate 和局部 revision，可基于各自 revision 并发推进且互不重置，同一 scope 的过期 writer 会 fail-closed。workflow 与 artifact mutation 使用统一的 schema 2 增量事务和崩溃恢复 journal；带已登记 evidence 的 transition/Gate 会在同一跨 aggregate 事务中同步登记物料交接历史。状态 CLI 同时强制节点依赖、成功证据和当前节点尝试的必需 Gate。
 
-版本归档的可携带权威位置是 `.workflow/control/archives/versions/<version-id>/`。归档成功后，对应任务和 checkpoint 会从活动集合移出，后续 `recover` 不再加载它们。`doctor` 使用发行包固定的 25 个 Skill 与受管 Hook、Bootstrap、状态和 Evolution 运行时摘要进行完整性检查，并实际执行只读 `inspect/verify` 冒烟验证；查看器仍是可选工具。
+版本归档的可携带权威位置是 `.workflow/control/archives/versions/<version-id>/`。归档成功后，对应任务和 checkpoint 会从活动集合移出，后续 `recover` 不再加载它们。`doctor` 使用发行包固定的 25 个 Skill 与受管 Hook、Bootstrap、状态、Evolution 和 Workflow Manager 运行时摘要进行完整性检查，并实际执行只读 `inspect/verify` 冒烟验证。
 
 安装后的工作流通过 `$ai-delivery-evolve-workflow` 在安全点记录反馈、聚合重复信号、试运行项目级扩展并按指标自动启用或回退。扩展只存在于 `.workflow/extensions/`，不能修改受管核心、正式状态、人工 Gate 或已批准规范。完整用法见[自进化使用指南](docs/EVOLUTION-USER-GUIDE.zh-CN.md)。
 
@@ -57,14 +83,17 @@ node .workflow/tools/state/state.mjs verify
 
 累计研发版本、当前生产版本和当前生产 release ID 的权威来源是 `.workflow/delivery/workflow-state.yaml` 中经审计事件写入的 `latest_line_version_id`、`production_version_id` 和 `production_release_id`。版本收尾使用 `version-closed`，发布归档使用 `release-archived`；`project.yaml` 中的同名旧字段只作兼容回退。
 
-安装完成后直接启动项目内的工作流物料查看器：
+正式工作流管理入口是工作流管理器。它通过同一个应用服务向 CLI、HTTP 和 React 界面投影正式状态，节点状态只来自 `state inspect.derived_node_states`：
 
 ```powershell
-.\.workflow\tools\viewer\start.cmd
+npx ai-delivery-workflow@latest manager inspect .
+npx ai-delivery-workflow@latest manager list . --resource contracts
+.\.workflow\tools\manager\start.cmd
 ```
 
-查看器默认打开 `http://127.0.0.1:4173`，实时扫描当前项目 `.workflow/`，分别展示研发和发布轨道、生产版本、累计研发版本、发布范围、物料关系、checksum 与文档预览。它不修改正式产物。
-查看器是 `.workflow/tools/` 下的可选只读工具；删除 `.workflow/tools/viewer/` 不影响状态 CLI、Checkpoint、恢复、研发或发布，再次执行 `init` 可重装查看器。
+macOS/Linux 使用 `sh ./.workflow/tools/manager/start.sh`。也可运行 `npx ai-delivery-workflow@latest manager serve . --no-open`；服务只绑定 loopback。P01-P19 共 19 个固定 Page 均连接真实项目投影，P13 作为上下文详情页从原型审批或路由页面进入。未登记事实明确显示“尚未登记”，不会填充演示数据。AI 先从 `contracts` 资源和 `manager action <action-name> --help` 发现当前 Schema；安装后完整流程位于 `.workflow/tools/manager/AGENT-INTERFACE.md`。原型评论/截图/审核、项目系统脚本/生命周期、Mock 同步、Gate 决定、关系确认和设置修改只通过白名单动作执行，并校验 actor、revision/checksum、幂等键及所需的 plan checksum。
+
+旧 `.workflow/tools/viewer/` 和独立 Prototype Review Server 已退役。新安装不再包含它们；旧项目升级时，Viewer 由带备份和 checksum 的 `remove` 操作登记，受保护回滚可以恢复升级前字节。
 
 研发完成不会自动上线。用户需要发布时明确选择截止版本：
 
@@ -86,20 +115,20 @@ npx ai-delivery-workflow@latest inspect .
 npx ai-delivery-workflow@latest bootstrap .
 ```
 
-预览或明确替换冲突的受管文件：
+首次安装完成后，预览或升级受管文件：
 
 ```bash
-npx ai-delivery-workflow@latest init . --dry-run
-npx ai-delivery-workflow@latest init . --force
+npx ai-delivery-workflow@latest upgrade . --dry-run
+npx ai-delivery-workflow@latest upgrade .
 ```
 
-`--force` 会先备份到 `.workflow/delivery/runtime/backups/`。初始化完成后请新建 Codex 任务，使项目级 skills 和 Hook 信任状态重新加载。
+`init` 只允许首次安装；已有 `.workflow/config/install-manifest.json` 时必须使用 `upgrade`。升级 dry-run 输出 additions、replacements、preserved、preserved_summary、conflicts、backups 和 compatibility，且严格零写。`preserved` 中受管安装资产之外的明细最多报告 200 条，完整的总数、已报告数、省略数和排除的瞬态根见 `preserved_summary`；省略仅限制报告体积，不会删除文件。正式升级只替换安装清单声明的受管副本，保留业务物料、用户配置部分和嵌套代码仓库，并把收据和备份写入 `.workflow/delivery/runtime/upgrades/<upgrade-id>/`。在升级后尚未新增正式事务时，可执行 `upgrade . --rollback <upgrade-id>`；否则必须前向修复。初始化或升级完成后请新建 Codex 任务，使项目级 skills 和 Hook 信任状态重新加载。
 
 旧项目如仍使用根目录 `delivery/` 和 `standards/`，需先迁移为 `.workflow/delivery/` 和 `.workflow/standards/`，同步更新产物引用与 checksum 后再执行 `init`。安装器不会在新旧两套状态之间自动选择权威来源。
 
 ## 仓库内容边界
 
-本工作流维护仓库把长期资产分为源码、永久验证源码和审计物料。安装器、状态 CLI、Hook、Skill、查看器等通用自动化验证统一位于 `verification/` 并纳入 Git；可重建的全流程交付证据与历史快照位于 `audit/` 并纳入 Git，但不会被 `init` 安装到业务项目。
+本工作流维护仓库把长期资产分为源码、永久验证源码和审计物料。安装器、状态 CLI、Hook、Skill、Workflow Manager 等通用自动化验证统一位于 `verification/` 并纳入 Git；可重建的全流程交付证据与历史快照位于 `audit/` 并纳入 Git，但不会被 `init` 安装到业务项目。
 
 所有测试工作区、缓存、日志、报告、临时 Git 仓库、npm cache、打包产物、认证辅助文件和绑定单次演练的脚本统一放入 `.tmp/`。根 `.gitignore` 整体忽略 `/.tmp/`，其中任何内容都不得作为权威源码或审计证据。`audit/` 候选包、部署副本和历史快照内嵌的应用测试属于审计物料，可保留原路径；执行这些校验的维护入口位于 `verification/`。
 
@@ -107,6 +136,8 @@ npx ai-delivery-workflow@latest init . --force
 npm test
 npm run skills:validate
 npm run audit:verify
+npm run benchmark:autonomy -- --iterations 5
+npm run release:check -- prepare --version <version>
 ```
 
 `npm run skills:validate` 使用项目已有的 Node.js `yaml` 依赖校验全部 25 个 Skill，无需 Python 或 `PyYAML`。它检查 `SKILL.md` frontmatter、目录名称、`agents/openai.yaml` 界面元数据，以及项目手册和文件参考中的 Skill 覆盖关系；任一错误都会返回非零退出码。该校验只属于本维护仓库，不会安装到业务项目。

package/bin/ai-delivery.mjs

@@ -4,10 +4,18 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { runCodeGraphAction } from "../lib/codegraph.mjs";
+import { runMockSystemAction } from "../lib/mock-system.mjs";
 import { executeDeliveryStateCommand } from "../lib/delivery-state.mjs";
 import { dispatchEvolutionHookEvent, executeEvolutionCommand } from "../lib/evolution.mjs";
-import { doctorProject, initProject } from "../lib/project-installer.mjs";
+import { doctorProject, initProject, upgradeProject } from "../lib/project-installer.mjs";
 import { bootstrapProject, inspectProjectState } from "../lib/project-bootstrap.mjs";
+import { migrateProject, repairProject } from "../lib/project-migration.mjs";
+import { validateVisualStandard } from "../lib/visual-standard.mjs";
+import { validatePrototypeRevision } from "../lib/prototype-revision.mjs";
+import { runFrontendGuardCommand } from "../lib/frontend-guard.mjs";
+import { runUiAcceptanceCommand } from "../lib/ui-acceptance.mjs";
+import { WorkflowManagerError, renderWorkflowManagerCommandHelp, runWorkflowManagerCommand } from "../lib/workflow-manager.mjs";
 
 const packageRoot = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
 const packageJson = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"));
@@ -17,30 +25,63 @@ function usage() {
 
 Usage:
   ai-delivery init [workspace-directory] [--workspace-id id] [--code-path code] [--code-id app] [--code-remote <url>] [--workflow-remote <url>] [--shared-remote <url>] [--dry-run] [--force]
+  ai-delivery upgrade [workspace-directory] [--dry-run] [--force]
+  ai-delivery upgrade [workspace-directory] --rollback <upgrade-id>
+  ai-delivery migrate [workspace-directory] [--decisions <file>] [--dry-run]
+  ai-delivery migrate [workspace-directory] --rollback <migration-id>
+  ai-delivery repair [workspace-directory] --invalidate-archive <iteration-id> --reason <text> --actor human:<identity> --evidence <ref> --evidence <ref> [--dry-run]
+  ai-delivery compact [workspace-directory] [--dry-run]
   ai-delivery inspect [workspace-directory]
   ai-delivery bootstrap [workspace-directory] [--dry-run] [--force]
   ai-delivery doctor [workspace-directory]
+  ai-delivery codegraph <setup|sync> [workspace-directory] [--dry-run]
+  ai-delivery mock <setup|start|stop|status|sync> [workspace-directory] [--dry-run]
+  ai-delivery mock freeze [workspace-directory] --experience <relative-directory> --scenario-pack <relative-yaml> [--dry-run]
+  ai-delivery visual-standard validate [workspace-directory] --experience <relative-directory>
+  ai-delivery prototype-revision validate [workspace-directory] --experience <relative-directory> --revision <relative-yaml>
+  ai-delivery frontend-guard check-file [workspace-directory] --path <frontend-file> [--experience <relative-directory>] [--revision <relative-yaml>]
+  ai-delivery frontend-guard verify-diff [workspace-directory] --base <git-ref> [--head <git-ref>] [--experience <relative-directory>] [--revision <relative-yaml>]
+  ai-delivery ui-acceptance <plan|verify> [workspace-directory] --request <relative-yaml> [--results <relative-yaml>]
+  ai-delivery manager inspect [workspace-directory]
+  ai-delivery manager <list|show|export> [workspace-directory] --resource <manager|contracts|facts|prototypes|prototype-source-snapshots|attachments|systems|mock|settings> [--terminal-id all|<terminal-id>]
+  ai-delivery manager action <action-name> [workspace-directory] --input <json-file>
+  ai-delivery manager serve [workspace-directory] [--port <port>] [--no-open]
   ai-delivery state <state-command> [options]
   ai-delivery evolve <evolution-command> [options]
   ai-delivery --version
 
 Commands:
   init     Create a workflow repository and bind or create one nested code repository
+  upgrade  Preview, apply, or roll back project-scoped managed installation assets
+  migrate  Preview or apply structural compatibility migration without business-state repair
+  repair   Append an explicit forward correction without rewriting historical evidence
+  compact  Archive anchored legacy history and remove loose snapshots only after verified replay
   inspect  Detect workspace, code repository, workflow, and runtime state without writes
   bootstrap  Initialize missing workflow context or route recovery safely
   doctor   Validate the current project-scoped installation
+  codegraph  Set up or synchronize the optional code repository index
+  mock     Manage the local-only Microcks Mock System and tracked definitions
+  visual-standard  Validate the exact UX-VS inputs and approval before Gate completion
+  prototype-revision  Validate one immutable revision of the single project Prototype
+  frontend-guard  Enforce approved Prototype Page coverage before production frontend edits
+  ui-acceptance  Plan and verify Candidate Assurance UI evidence against immutable inputs
+  manager  Inspect the shared Workflow Manager projection or start its loopback UI
   state    Inspect, verify, and mutate formal workflow state through the guarded CLI
   evolve   Record feedback and govern project-local workflow extensions
 
 Options:
   --dry-run  Show planned changes without writing files
   --force    Back up and replace conflicting managed files
+  --rollback  Restore one upgrade or migration before any later formal transaction
+  --decisions  Apply checksum-bound human task-grouping decisions from a YAML or JSON file
   --code-path  Nested code repository directory (default: code)
   --code-id    Stable code repository identifier (default: app)
   --code-remote  Clone this remote when the code directory does not exist
   --workflow-remote  Configure the workflow repository origin
   --shared-remote  Configure both independent repositories with the same origin
   --workspace-id  Stable ID used by workflow/<workspace-id>
+  --port  Loopback port for the selected local UI
+  --no-open  Start the selected local UI without opening a browser
 `;
 }
 
@@ -48,10 +89,19 @@ function parseArgs(argv) {
   const flags = new Set();
   const options = new Map();
   const positional = [];
-  const booleanOptions = new Set(["--dry-run", "--force", "--help", "--version"]);
+  const booleanOptions = new Set(["--dry-run", "--force", "--help", "--version", "--no-open"]);
   const valueOptions = new Set([
     "--code-path", "--code-id", "--code-remote", "--workflow-remote", "--shared-remote", "--workspace-id",
+    "--rollback", "--decisions",
+    "--invalidate-archive", "--reason", "--actor", "--evidence", "--experience", "--revision", "--port",
+    "--scenario-pack",
+    "--path",
+    "--base", "--head",
+    "--request", "--results",
+    "--resource", "--input", "--experience", "--branch", "--attachment-id", "--expected-checksum", "--terminal-id",
+    "--source-snapshot-id", "--source-ref", "--page-id", "--review-scene-id",
   ]);
+  const repeatableOptions = new Set(["--evidence"]);
   for (let index = 0; index < argv.length; index += 1) {
     const value = argv[index];
     if (booleanOptions.has(value)) {
@@ -59,7 +109,12 @@ function parseArgs(argv) {
     } else if (valueOptions.has(value)) {
       const optionValue = argv[index + 1];
       if (!optionValue || optionValue.startsWith("--")) throw new Error(`Missing value for ${value}`);
-      options.set(value, optionValue);
+      if (repeatableOptions.has(value)) {
+        const existing = options.get(value);
+        options.set(value, [...(Array.isArray(existing) ? existing : existing ? [existing] : []), optionValue]);
+      } else {
+        options.set(value, optionValue);
+      }
       index += 1;
     } else if (value.startsWith("--")) {
       throw new Error(`Unknown option: ${value}`);
@@ -70,6 +125,8 @@ function parseArgs(argv) {
   return { flags, options, positional };
 }
 
+let managerCommand = false;
+
 try {
   const rawArgs = process.argv.slice(2);
   if (rawArgs[0] === "state" || rawArgs[0] === "evolve") {
@@ -89,13 +146,25 @@ try {
   } else {
     const { flags, options, positional } = parseArgs(rawArgs);
     if (flags.has("--help") || positional[0] === "help") {
-    process.stdout.write(usage());
+      if (positional[0] === "manager") {
+        const actionName = positional[1] === "action" ? positional[2] : null;
+        process.stdout.write(`${renderWorkflowManagerCommandHelp(actionName, { command: "ai-delivery manager" })}\n`);
+      } else {
+        process.stdout.write(usage());
+      }
     } else if (flags.has("--version")) {
       process.stdout.write(`${packageJson.version}\n`);
     } else {
       const command = positional[0] || "init";
-      const target = path.resolve(positional[1] || process.cwd());
+      managerCommand = command === "manager";
+      const nestedTargetCommand = command === "codegraph" || command === "visual-standard"
+        || command === "mock" || command === "prototype-revision"
+        || command === "frontend-guard" || command === "ui-acceptance" || command === "manager";
+      const target = path.resolve(positional[nestedTargetCommand ? 2 : 1] || process.cwd());
       if (command === "init") {
+        if (fs.existsSync(path.join(target, ".workflow", "config", "install-manifest.json"))) {
+          throw new Error("ai-delivery-workflow is already installed; use the upgrade command for managed installation changes.");
+        }
         const report = initProject(packageRoot, target, {
           dryRun: flags.has("--dry-run"),
           force: flags.has("--force"),
@@ -109,9 +178,43 @@ try {
         });
         process.stdout.write(`${report.summary}\n`);
         for (const item of report.actions) process.stdout.write(`- ${item}\n`);
+      } else if (command === "upgrade") {
+        const report = upgradeProject(packageRoot, target, {
+          dryRun: flags.has("--dry-run"),
+          force: flags.has("--force"),
+          packageVersion: packageJson.version,
+          rollback: options.get("--rollback") || null,
+        });
+        process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
       } else if (command === "inspect") {
         const report = inspectProjectState(target);
         process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+      } else if (command === "migrate") {
+        const report = migrateProject(target, {
+          dryRun: flags.has("--dry-run"),
+          rollback: options.get("--rollback") || null,
+          decisions: options.get("--decisions") || null,
+        });
+        process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+      } else if (command === "repair") {
+        const report = repairProject(target, {
+          dryRun: flags.has("--dry-run"),
+          invalidateArchive: options.get("--invalidate-archive"),
+          reason: options.get("--reason"),
+          actor: options.get("--actor"),
+          evidence: options.get("--evidence") || [],
+        });
+        process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+      } else if (command === "compact") {
+        const stateArgs = ["artifact", "compact", "--project", target];
+        if (!flags.has("--dry-run")) stateArgs.push("--apply");
+        const report = executeDeliveryStateCommand(stateArgs, {
+          yaml: {
+            parse: parseYaml,
+            stringify: (value) => stringifyYaml(value, { lineWidth: 0 }),
+          },
+        });
+        process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
       } else if (command === "bootstrap") {
         const report = bootstrapProject(packageRoot, target, {
           dryRun: flags.has("--dry-run"),
@@ -127,12 +230,84 @@ try {
           process.stdout.write(`${outcome} ${check.message}\n`);
         }
         if (!report.ok) process.exitCode = 1;
+      } else if (command === "codegraph") {
+        const report = runCodeGraphAction(target, positional[1], {
+          dryRun: flags.has("--dry-run"),
+        });
+        process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+      } else if (command === "mock") {
+        const report = await runMockSystemAction(target, positional[1], {
+          dryRun: flags.has("--dry-run"),
+          experience: options.get("--experience"),
+          scenarioPack: options.get("--scenario-pack"),
+        });
+        process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+      } else if (command === "visual-standard" && positional[1] === "validate") {
+        const report = validateVisualStandard(target, {
+          experience: options.get("--experience"),
+        });
+        process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+      } else if (command === "prototype-revision" && positional[1] === "validate") {
+        const report = validatePrototypeRevision(target, {
+          experience: options.get("--experience"),
+          revision: options.get("--revision"),
+        });
+        process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+      } else if (command === "frontend-guard") {
+        const report = runFrontendGuardCommand(target, positional[1], {
+          path: options.get("--path"),
+          experience: options.get("--experience"),
+          revision: options.get("--revision"),
+          base: options.get("--base"),
+          head: options.get("--head"),
+        });
+        process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+      } else if (command === "ui-acceptance") {
+        const report = runUiAcceptanceCommand(target, positional[1], {
+          request: options.get("--request"),
+          results: options.get("--results"),
+        });
+        process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+      } else if (command === "manager") {
+        const managerAction = positional[1];
+        const actionName = managerAction === "action" ? positional[2] : null;
+        const managerTarget = managerAction === "action"
+          ? path.resolve(positional[3] || process.cwd())
+          : target;
+        const inputFile = options.get("--input");
+        const input = inputFile ? JSON.parse(fs.readFileSync(path.resolve(inputFile), "utf8")) : undefined;
+        const result = await runWorkflowManagerCommand(packageRoot, managerTarget, managerAction, {
+          port: options.get("--port"),
+          open: !flags.has("--no-open"),
+          resource: options.get("--resource"),
+          experience: options.get("--experience"),
+          revision: options.get("--revision"),
+          branch: options.get("--branch"),
+          attachmentId: options.get("--attachment-id"),
+          expectedChecksum: options.get("--expected-checksum"),
+          terminalId: options.get("--terminal-id"),
+          sourceSnapshotId: options.get("--source-snapshot-id"),
+          sourceRef: options.get("--source-ref"),
+          pageId: options.get("--page-id"),
+          reviewSceneId: options.get("--review-scene-id"),
+          actionName,
+          input,
+        });
+        const report = result?.report || result;
+        process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
       } else {
         throw new Error(`Unknown command: ${command}\n\n${usage()}`);
       }
     }
   }
 } catch (error) {
-  process.stderr.write(`ai-delivery: ${error.message}\n`);
+  if (managerCommand) {
+    process.stderr.write(`${JSON.stringify({
+      error: {
+        code: error instanceof WorkflowManagerError ? error.code : "invalid-request",
+        message: error?.message || "Workflow Manager request failed",
+      },
+    })}\n`);
+  } else process.stderr.write(`ai-delivery: ${error.message}\n`);
   process.exitCode = 1;
 }

package/bin/benchmark-autonomy.mjs

@@ -0,0 +1,217 @@
+#!/usr/bin/env node
+
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { performance } from "node:perf_hooks";
+import { fileURLToPath } from "node:url";
+import { bootstrapProject } from "../lib/project-bootstrap.mjs";
+import { initProject } from "../lib/project-installer.mjs";
+
+const packageRoot = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const temporaryRoot = path.join(packageRoot, ".tmp");
+
+function parseArguments(argv) {
+  const options = { iterations: 5, output: null };
+  while (argv.length) {
+    const key = argv.shift();
+    if (!new Set(["--iterations", "--output"]).has(key)) throw new Error(`unknown option: ${key}`);
+    const value = argv.shift();
+    if (!value || value.startsWith("--")) throw new Error(`missing value for ${key}`);
+    options[key.slice(2)] = key === "--iterations" ? Number(value) : path.resolve(value);
+  }
+  if (!Number.isInteger(options.iterations) || options.iterations < 1 || options.iterations > 100) {
+    throw new Error("--iterations must be an integer from 1 to 100");
+  }
+  return options;
+}
+
+function sha256(value) {
+  return crypto.createHash("sha256").update(value).digest("hex");
+}
+
+function filesUnder(directory) {
+  if (!fs.existsSync(directory)) return [];
+  return fs.readdirSync(directory, { withFileTypes: true })
+    .flatMap((entry) => {
+      const absolute = path.join(directory, entry.name);
+      return entry.isDirectory() ? filesUnder(absolute) : [absolute];
+    })
+    .sort((left, right) => left.localeCompare(right));
+}
+
+function durableSnapshot(project) {
+  const workflowRoot = path.join(project, ".workflow");
+  const files = filesUnder(workflowRoot);
+  const hash = crypto.createHash("sha256");
+  let bytes = 0;
+  for (const file of files) {
+    const relative = path.relative(workflowRoot, file).replaceAll("\\", "/");
+    const content = fs.readFileSync(file);
+    bytes += content.length;
+    hash.update(`${relative}\0${content.length}\0`);
+    hash.update(content);
+  }
+  return { checksum: hash.digest("hex"), file_count: files.length, bytes };
+}
+
+function withoutVolatileFields(value) {
+  if (Array.isArray(value)) return value.map(withoutVolatileFields);
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(Object.entries(value)
+    .filter(([key]) => key !== "detected_at")
+    .map(([key, child]) => [key, withoutVolatileFields(child)]));
+}
+
+function runChecked(program, args, cwd) {
+  const result = spawnSync(program, args, { cwd, encoding: "utf8", windowsHide: true });
+  if (result.status !== 0) {
+    throw new Error(`${path.basename(program)} ${args.join(" ")} failed: ${result.stderr || result.stdout}`);
+  }
+  return result.stdout.trim();
+}
+
+function prepareRecoveryCheckpoint(project) {
+  const codeRoot = path.join(project, "code");
+  runChecked("git", ["config", "user.email", "benchmark@example.invalid"], codeRoot);
+  runChecked("git", ["config", "user.name", "Autonomy Benchmark"], codeRoot);
+  fs.writeFileSync(path.join(codeRoot, "README.md"), "autonomy benchmark\n", "utf8");
+  runChecked("git", ["add", "README.md"], codeRoot);
+  runChecked("git", ["commit", "-m", "initialize benchmark code"], codeRoot);
+  const taskCli = path.join(
+    project, ".agents", "skills", "ai-delivery-checkpoint-task", "scripts", "task-state.mjs",
+  );
+  const stateRoot = ["--state-root", project];
+  const initializedTask = JSON.parse(runChecked(process.execPath, [
+    taskCli, "init",
+    "--task-id", "TASK-BENCHMARK-RECOVERY",
+    "--iteration-id", "BENCHMARK-001",
+    "--node", "01-product-shaping",
+    "--skill", "ai-delivery-define-product",
+    "--goal", "Resume the recorded product discovery question",
+    "--branch", "main",
+    "--worktree", codeRoot,
+    "--status", "queued",
+    "--next-action", "Ask the recorded business question",
+    "--next-action-owner", "agent",
+    ...stateRoot,
+  ], codeRoot));
+  runChecked(process.execPath, [
+    taskCli, "activate",
+    "--task-id", "TASK-BENCHMARK-RECOVERY",
+    ...stateRoot,
+  ], codeRoot);
+  runChecked(process.execPath, [
+    taskCli, "finish",
+    "--task-id", "TASK-BENCHMARK-RECOVERY",
+    "--status", "blocked",
+    "--blocker", "Waiting for a business answer",
+    "--next-action", "Confirm the primary business problem",
+    "--next-action-owner", "user",
+    ...stateRoot,
+  ], codeRoot);
+  return initializedTask.node;
+}
+
+function runAutonomyBenchmark(options) {
+  const packageVersion = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8")).version;
+  fs.mkdirSync(temporaryRoot, { recursive: true });
+  const project = fs.mkdtempSync(path.join(temporaryRoot, "ai-delivery-autonomy-benchmark-"));
+  try {
+    const bootstrapStarted = performance.now();
+    const bootstrap = bootstrapProject(packageRoot, project, {
+      packageVersion,
+      initProject,
+    });
+    const bootstrapElapsed = performance.now() - bootstrapStarted;
+    const recoveryTaskNode = prepareRecoveryCheckpoint(project);
+    const before = durableSnapshot(project);
+    const samples = [];
+    for (let index = 0; index < options.iterations; index += 1) {
+      const started = performance.now();
+      const route = bootstrapProject(packageRoot, project, { packageVersion });
+      const elapsed = performance.now() - started;
+      const inspection = route.inspection;
+      const payload = Buffer.from(JSON.stringify(route), "utf8");
+      const semanticPayload = Buffer.from(JSON.stringify(withoutVolatileFields(route)), "utf8");
+      samples.push({
+        sequence: index + 1,
+        elapsed_ms: Number(elapsed.toFixed(3)),
+        state: inspection.state,
+        recommended_skill: inspection.recommendation?.skill || null,
+        recommended_task_id: inspection.runtime?.recommended_task_id || null,
+        next_action_owner: inspection.runtime?.next_action_owner || null,
+        deferred_to_user: route.deferred_to_user,
+        context_bytes: payload.length,
+        context_sha256: sha256(payload),
+        semantic_context_sha256: sha256(semanticPayload),
+      });
+    }
+    const after = durableSnapshot(project);
+    const semanticChecksums = new Set(samples.map((sample) => sample.semantic_context_sha256));
+    const invariants = {
+      durable_checksum_stable: before.checksum === after.checksum,
+      durable_file_count_stable: before.file_count === after.file_count,
+      semantic_context_checksum_stable: semanticChecksums.size === 1,
+      durable_growth_bytes: after.bytes - before.bytes,
+    };
+    const decision = Object.entries(invariants).every(([key, value]) =>
+      key === "durable_growth_bytes" ? value === 0 : value === true) ? "pass" : "fail";
+    return {
+      schema_version: 1,
+      benchmark: "autonomous-bootstrap-and-recovery-inspection",
+      generated_at: new Date().toISOString(),
+      workflow_version: packageVersion,
+      environment: { node: process.version, platform: process.platform, architecture: process.arch },
+      methodology: {
+        llm_token_usage: "unavailable",
+        context_cost_proxy: "UTF-8 byte length of bootstrapProject recovery-route JSON",
+        volatile_fields_excluded_from_semantic_checksum: ["detected_at"],
+        durable_scope: ".workflow/ after first Bootstrap and a user-owned checkpoint",
+      },
+      bootstrap: {
+        elapsed_ms: Number(bootstrapElapsed.toFixed(3)),
+        initial_state: bootstrap.initial_state,
+        resulting_state: bootstrap.resulting_state,
+        initialized: bootstrap.initialized,
+        artifacts_written: bootstrap.artifacts_written,
+        durable_after: before,
+      },
+      recovery: {
+        route: "bootstrapProject-user-owned-checkpoint",
+        task_node: recoveryTaskNode,
+        iterations: options.iterations,
+        elapsed_total_ms: Number(samples.reduce((total, sample) => total + sample.elapsed_ms, 0).toFixed(3)),
+        context_bytes_min: Math.min(...samples.map((sample) => sample.context_bytes)),
+        context_bytes_max: Math.max(...samples.map((sample) => sample.context_bytes)),
+        samples,
+      },
+      durable_before_recovery: before,
+      durable_after_recovery: after,
+      invariants,
+      decision,
+      limitations: [
+        "The Codex runtime does not expose per-subagent LLM token usage to this repository command.",
+        "Elapsed time is environment-dependent and is recorded as an observation, not a release threshold.",
+      ],
+    };
+  } finally {
+    fs.rmSync(project, { recursive: true, force: true });
+  }
+}
+
+try {
+  const options = parseArguments(process.argv.slice(2));
+  const report = runAutonomyBenchmark(options);
+  const text = `${JSON.stringify(report, null, 2)}\n`;
+  if (options.output) {
+    fs.mkdirSync(path.dirname(options.output), { recursive: true });
+    fs.writeFileSync(options.output, text, "utf8");
+  }
+  process.stdout.write(text);
+  if (report.decision !== "pass") process.exitCode = 1;
+} catch (error) {
+  process.stderr.write(`${error.message}\n`);
+  process.exitCode = 2;
+}