ai-delivery-workflow 0.2.2 → 0.4.0

package/docs/CLI-PARAMETER-REFERENCE.zh-CN.md

@@ -0,0 +1,346 @@
+# CLI 安装参数参考
+
+本文说明 `ai-delivery-workflow` 安装、检查和自主引导相关的顶层 CLI 参数。它适用于安装后的业务项目，不用于初始化本维护仓库。正式状态和自进化子命令分别见[正式状态 CLI 使用指南](STATE-CLI-USER-GUIDE.zh-CN.md)与[自进化使用指南](EVOLUTION-USER-GUIDE.zh-CN.md)。
+
+## 1. 调用格式
+
+```text
+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 <rca-ref> --evidence <recovery-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 [workspace-directory] --request <relative-yaml>
+ai-delivery ui-acceptance verify [workspace-directory] --request <relative-yaml>
+                                     --results <relative-yaml>
+ai-delivery manager inspect [workspace-directory]
+ai-delivery manager <list|show|export> [workspace-directory] --resource <resource>
+                                             [--terminal-id all|<terminal-id>]
+ai-delivery manager action <action-name> [workspace-directory] --input <json-file>
+ai-delivery manager action <action-name> --help
+ai-delivery manager serve [workspace-directory] [--port <port>] [--no-open]
+ai-delivery --help
+ai-delivery --version
+```
+
+从 npm 调用时，`ai-delivery` 由 `npx ai-delivery-workflow@<版本>` 提供：
+
+```powershell
+npx ai-delivery-workflow@latest init .
+npx ai-delivery-workflow@0.4.0 doctor .
+```
+
+`@latest` 表示 npm 的当前稳定 dist-tag；固定版本用于可重复安装。`.` 表示当前目录。PowerShell 行末反引号 `` ` `` 只是续行符，不是 CLI 参数。
+
+## 2. 命令
+
+| 命令 | 作用 | 是否可能写入 |
+| --- | --- | --- |
+| `init` | 仅首次安装 25 个项目级 Skill、Hook、自包含 CLI、Workflow Manager 和工作流目录，并初始化或绑定两套独立 Git。已有安装清单时拒绝执行。 | 是 |
+| `upgrade` | 预览、应用或回滚安装清单声明的受管副本；不初始化 Git，不写业务物料、用户配置部分或嵌套代码仓库。 | 视参数而定 |
+| `migrate` | 预览、登记或回滚兼容结构及旧 Prototype member/set 迁移；报告 schema、任务分组、Prototype 合并、冲突、锚点和文件变化，不推断业务状态。 | 视参数而定 |
+| `repair` | 追加独立的前向归档失效事务；原归档证据保持逐字节不变。 | 视参数而定 |
+| `compact` | 把可信 anchor 覆盖的 legacy registry 全量快照打包为 checksummed gzip archive；精确 replay 验证通过后才移除 loose shards。 | 视参数而定 |
+| `inspect` | 只读识别工作区、两套 Git、安装完整性、正式状态和任务恢复建议。 | 否 |
+| `bootstrap` | 根据只读检查决定初始化缺失工作流、恢复 Agent 责任任务或停在用户/外部输入边界。 | 视路由而定 |
+| `doctor` | 校验受管文件 checksum、Skill、Hook、CLI、Workflow Manager、必需目录和持久项目配置；排除本地 runtime。 | 否 |
+| `codegraph setup` | 对权威代码仓关闭 CodeGraph telemetry、按当前 `CODEGRAPH_DIR` 登记本地 ignore 并显式初始化索引；不安装 CLI 或全局 MCP。 | 是；`--dry-run` 时否 |
+| `codegraph sync` | 增量同步已有 CodeGraph 索引并重新验证索引目标。 | 是；`--dry-run` 时否 |
+| `mock setup` | 探测 Docker/Podman、拉取固定 digest 的 Microcks，并初始化隔离的 tracked External Dependency 与 Product Backend Mock catalog；不自动安装容器引擎。 | 是；`--dry-run` 时否 |
+| `mock start` | 以 `--rm`、in-memory 模式启动 Microcks，只发布到 `127.0.0.1:8585` 并等待健康；健康失败时停止本次容器。 | 是；`--dry-run` 时否 |
+| `mock stop` | 停止稳定命名的易失容器，不删除 tracked 定义。 | 是；`--dry-run` 时否 |
+| `mock status` | 只读报告容器与 Microcks 健康状态。 | 否 |
+| `mock sync` | 校验两类 catalog 的 kind、owner、批准合同、replacement condition、operation/channel、具名 scenario 与 dispatcher 输入，通过本地 API 导入唯一合同。 | 访问本地 API；`--dry-run` 时否 |
+| `mock freeze` | 校验 Prototype revision、全部 Review Scene 唯一场景映射、受管 UI 实际导出物的 SHA-256 与协议/场景 inventory、数据分类/脱敏及批准合同；dry-run 返回待人工确认的 candidate checksum，应用时写不可变 Scenario Pack。 | 是；`--dry-run` 时否 |
+| `visual-standard validate` | 只读验证 UX-VS 的设计参考、许可、Visual Reference、组件配置、本地适配、完整输入校验和及审批有效期。 | 否 |
+| `prototype-revision validate` | 只读验证唯一 Prototype 的冻结 revision、源码树、Review Shell bundle、稳定身份、规范化目录、路由关系和 UI Mapping。 | 否 |
+| `frontend-guard check-file` | 在单个正式 UI 文件写入前，只读校验冻结 revision、frontend scope、UI Mapping 与当前 Page receipt。 | 否 |
+| `frontend-guard verify-diff` | 从嵌套代码仓固定 base/head 独立读取 Git diff，并重新校验全部 UI 路径的批准与映射。 | 否 |
+| `ui-acceptance plan` | 在 Candidate Assurance 内只读校验不可变 candidate、Prototype/UX-VS/Page receipt、UI Mapping、Scenario Pack 和测试策略，并生成确定性 Scene/viewport 执行矩阵。 | 否 |
+| `ui-acceptance verify` | 对执行矩阵逐项复核视觉、交互、无障碍、响应式、恢复、协议和 Mock 权限证据；通过后返回 candidate-bound pass 报告。 | 否 |
+| `manager inspect` | 从正式状态 CLI 构建版本化的工作流管理器只读投影；CLI、HTTP 与界面使用同一应用服务。 | 否 |
+| `manager list/show/export --resource <resource>` | 读取 `manager`、`contracts`、`facts`、`prototypes`、`prototype-source-snapshots`、`attachments`、`systems`、`mock` 或 `settings` 结构化资源；三种动词使用同一事实投影。`attachments` 只接受精确附件 ID 与 checksum；`prototype-source-snapshots` 只接受登记的 `source_snapshot_id`，禁止任意路径。读取 `prototypes` 或源码快照时可用 `--terminal-id all` 或已登记的精确 Logical Terminal 身份限定 Page、Review Scene 和路由范围；未知身份会失败，不会回退。 | 否 |
+| `manager action <action-name> --input <json-file>` | 执行发行白名单内的原型审核、系统、Mock、Gate、关系或设置动作；按能力校验 actor、revision/checksum、幂等键和 plan checksum，并写 Receipt/Event。 | 是 |
+| `manager action <action-name> --help` | 从当前 `workflow-manager.contracts.v1` 契约生成动作授权、并发、幂等、plan 和输入字段帮助。 | 否 |
+| `manager serve` | 只绑定 `127.0.0.1` 并启动工作流管理器桌面界面；默认打开浏览器。 | 启动本机进程，不修改正式状态 |
+| `state` | 进入正式状态 CLI；参数不由本页的顶层解析器处理。 | 取决于子命令 |
+| `evolve` | 进入项目级自进化 CLI；参数不由本页的顶层解析器处理。 | 取决于子命令 |
+| `help` 或 `--help` | 输出顶层帮助。 | 否 |
+| `--version` | 输出 npm 包版本。 | 否 |
+
+省略命令时顶层 CLI 默认使用 `init`，但为了审阅和日志清晰，安装命令应显式写出 `init`。
+
+## 3. 位置参数
+
+### 3.1 `workspace-directory`
+
+- 适用命令：`init`、`upgrade`、`migrate`、`repair`、`compact`、`inspect`、`bootstrap`、`doctor`、`codegraph setup`、`codegraph sync`、`mock setup`、`mock start`、`mock stop`、`mock status`、`mock sync`、`mock freeze`、`visual-standard validate`、`prototype-revision validate`、`frontend-guard check-file`、`frontend-guard verify-diff`、`ui-acceptance plan`、`ui-acceptance verify`、`manager inspect/list/show/export/action/serve`。
+- 含义：目标业务项目根目录，也是外层工作流 Git 根目录。
+- 默认值：当前工作目录。
+- 可以使用相对路径或绝对路径；CLI 会转换为绝对路径。
+- 目标目录必须存在，并且不得是用户主目录、全局 `.codex` 或 `.agents` 目录。
+- 当前维护仓库不是安装目标，不得在仓库根执行面向业务项目的 `init` 或 `bootstrap`。
+
+`codegraph setup` 和 `codegraph sync` 接受 `--dry-run`。该模式只读取 `CODEGRAPH_DIR`、索引文件与 Git 边界，调用 `codegraph --version` 并输出 `planned_actions`；不调用 `status`，也不执行 telemetry、local exclude、init 或 sync 写入。
+
+`mock setup/start/stop/sync/freeze` 接受 `--dry-run`。setup dry-run 只探测容器引擎并报告固定镜像与双 catalog 计划；start/stop 只报告容器命令；sync 完整校验 catalog 与合同并报告 `planned_contracts`，但不访问 Microcks API；freeze 校验 `--experience` 下由 `--scenario-pack` 指定的 request，返回精确 candidate checksum 且零写入。应用 freeze 要求 `human:<identity>` 对该 checksum 的人工批准，输出仍须正式登记才具权威性。`mock status` 始终只读。完整边界见 [MOCK-SYSTEM.zh-CN.md](MOCK-SYSTEM.zh-CN.md)。
+
+`visual-standard validate` 要求 `--experience` 指向工作区内的体验产物相对目录，并始终使用当前时间复核审批有效期。命令只读且不允许调用者覆盖校验时间；引用缺失、许可遗漏、校验和漂移、组件选择不完整或审批过期时以非零状态失败。
+
+`prototype-revision validate` 同时要求 `--experience` 指向体验产物目录、`--revision` 指向该目录内的 revision YAML。命令只读校验单一 Prototype 身份、冻结状态、源码树和 review bundle SHA-256、Page/Review Scene 稳定 ID、终端分组、触发条件、原型/生产路由、UI Mapping 外键，以及 checksummed Review Unit 与独立 Unit-Page 关联目录；任何 Review Scene 伪造生产路由、重复身份/关系、遗漏 active Page/Review Scene Review Unit 或 checksum 漂移都以非零状态失败。
+
+`frontend-guard check-file` 默认读取 `.workflow/experience` 当前 revision，也可显式传入 `--experience` 与 `--revision`。`--path` 可为工作区相对路径或绝对路径；不在 revision-bound frontend roots 内的文件不进入 UI 守卫。frontend roots 与 UI 扩展名列表都不得为空；每个 active UI Mapping、shared component 和 route registry 的 source ref 都必须实际落入这些根和扩展名规则，否则整个 scope 无效而不是静默跳过。受管 UI 文件必须精确命中 active UI Mapping，或命中 `frontend-change-scope.yaml` 中声明 Page 影响集的 shared component / route registry。每个 route registry 必须是单个文件并绑定审批时预期 candidate 内容的 SHA-256；`verify-diff` 从 `--head` Git 对象读取该文件复核。每个受影响 Page 都必须由当前 checksum-valid receipt 推导为 `approved`。
+
+`frontend-guard verify-diff` 要求 `--base`，`--head` 默认 `HEAD`；它在 scope 固定的嵌套代码仓执行三点 Git diff 并复用相同校验核心。命令不读取 Hook 日志，不写状态或收据；CI 和正式验证必须执行它，即使本地 Hook 被绕过或 `check-file` 曾通过。
+
+`ui-acceptance plan` 与 `verify` 都只读，且只在 active `05-candidate-assurance` attempt 上接受 `ui-acceptance-request.yaml` 绑定的 immutable candidate。plan 从 candidate traceability 推导受影响 Page/Review Scene，默认使用 `390x844`、`768x1024`、`1440x900` 与 `max_diff_pixel_ratio: 0.001`；只有与 frozen Prototype revision checksum 一致的已批准 Visual Standard 才可覆盖。plan 会重新校验 Scenario Pack candidate、人审、场景映射、协议契约和 Microcks 管理导出。verify 要求每个执行单元都有精确 viewport 的 checksummed Prototype/Candidate PNG 与透明 RGBA Diff mask，并解码图片独立重算 pixel counts；确定性 JSON 协议证据必须匹配冻结契约期望及其场景选择参数。交互、WCAG 2.2 AA、键盘、焦点、触控目标、文本溢出、响应式和恢复均为阻塞项。External Dependency Mock 必须由批准测试策略显式允许；Product Backend Mock 只可驱动渲染，使用时必须另附绑定当前 candidate、非 Mock 环境、部署摘要、契约与端到端结果的真实 product backend 验收。candidate manifest checksum 变化会使旧计划与结果失败，修复必须返回 `04-implementation` 并新建 Candidate Assurance attempt。
+
+`manager inspect` 输出 `workflow-manager.v1` JSON，只从 `state inspect.derived_node_states` 取得节点状态。`manager list/show/export` 读取 `manager`、`contracts`、`facts`、`prototypes`、`prototype-source-snapshots`、`attachments`、`systems`、`mock` 或 `settings`；源码快照资源只接受登记的 `source_snapshot_id`，不接受任意路径。`manager action` 只接受发行白名单动作和项目内 JSON 输入。先运行 `manager --help` 发现当前动作，再运行 `manager action <action-name> --help` 读取由 `workflow-manager.contracts.v1` 生成的输入要求。`manager serve` 提供同一应用服务的 `/api/v1` 与 19 Page React 界面，只绑定 loopback，端口只允许 `1..65535` 且拒绝端口 `80`；`--no-open` 只禁止唤起浏览器。安装后也可直接执行 `.workflow/tools/manager/manager.mjs inspect/list/show/export/action`，并先读取 `.workflow/tools/manager/AGENT-INTERFACE.md`；Windows 使用 `.workflow/tools/manager/start.cmd` 或 `start.ps1`，macOS/Linux 使用 `.workflow/tools/manager/start.sh`。所有 Page 使用正式事实；缺失数据明确显示“尚未登记”。产品内容通过受控路径装载到 sandbox iframe，相对资源可运行，但内容脚本不能访问父级 Manager。目录越界、未知资源/动作、过大请求体、stale revision/checksum 或 target drift 均失败关闭。
+
+## 4. `init` 值参数
+
+| 参数 | 含义 | 默认值或省略行为 |
+| --- | --- | --- |
+| `--workspace-id <id>` | 工作区稳定身份，并生成外层工作流分支 `workflow/<id>`。 | 新项目根据目录名推导；已有项目保留配置值。 |
+| `--code-path <directory>` | 内层代码 Git 在工作区中的直接子目录。 | 新项目为 `code`；已有项目保留配置值。 |
+| `--code-id <id>` | 代码仓库逻辑身份 `repo_id`，供任务、版本、Tag、候选和发布物料追踪。 | 新项目为 `app`；已有项目保留配置值。 |
+| `--code-remote <url-or-path>` | 代码 Git 的 `origin`；代码目录不存在且远程非空时克隆 `main`。 | 不配置远程。 |
+| `--workflow-remote <url-or-path>` | 外层工作流 Git 的 `origin`，使用 `workflow/<workspace-id>` 分支。 | 不配置远程。 |
+| `--shared-remote <url-or-path>` | 让两个独立 Git 根使用同一 `origin`，但仍保持不同分支命名空间和提交历史。 | 不配置远程。 |
+
+值参数后必须紧跟非空值。未知的 `--option` 或缺失值会被拒绝。
+
+### 4.1 `--workspace-id`
+
+- 必须为 1 至 64 个字符；
+- 只能包含小写 ASCII 字母、数字、点、下划线和连字符；
+- 必须以字母或数字开头、结尾；
+- 合法示例：`tasklite`、`team-duty-v2`、`product_01`；
+- 非法示例：`TeamDuty`、`-tasklite`、包含中文或空格的 ID。
+
+省略时，安装器把目录名转为小写，将不支持的字符替换为连字符并去除首尾连字符；结果仍不合法时停止。工作区 ID 是 Git 分支身份，进入共享历史后不应随意改变。
+
+### 4.2 `--code-path`
+
+- 必须是相对于工作区根的一个直接子目录；
+- 不接受绝对路径、`.`、`..` 或 `apps/code` 等多层路径；
+- 不能使用 `.git`、`.workflow`、`.ai-delivery`、`.agents`、`.codex` 等保留名称；
+- 不能指向符号链接；
+- 目录非空时必须已经是以该目录为根的独立 Git 仓库；
+- 不支持 Git submodule、linked worktree，且不能与外层工作流 Git 共用 Git common directory。
+
+外层 `.gitignore` 会精确忽略该目录。代码仓库不跟踪父目录，工作流仓库也不跟踪代码内容。
+
+### 4.3 `--code-id`
+
+`code-id` 是逻辑身份，不是目录、远程或分支名称。当前 CLI 要求提供非空值，但不额外限制字符集；为保证 YAML、CSV、Tag 和跨系统追踪稳定，建议使用小写 ASCII 字母、数字和连字符，例如 `tasklite-app`。
+
+一旦产生任务、版本或发布物料，`repo_id` 应保持不变。显式改变它会影响现有引用，必须先完成影响分析，不能把改名当作普通重装。
+
+### 4.4 远程参数
+
+远程值可以是 Git URL，也可以是可访问的本地仓库路径。初始化器会读取远程 heads：
+
+- 非空代码远程必须存在 `main`，否则拒绝绑定；
+- 工作流远程已有 `workflow/<workspace-id>` 时会提取并跟踪该分支；
+- 本地已有 `origin` 与请求远程不一致时拒绝覆盖；
+- `--shared-remote` 不能与 `--code-remote` 或 `--workflow-remote` 同时使用；
+- 共用远程不等于共用 Git 根，外层和内层仍必须各自拥有独立 `.git`。
+
+### 4.5 `--decisions`
+
+- 仅适用于 `migrate`；
+- 指向 YAML 或 JSON 人工任务分组与 Prototype 合并决定文件；
+- 文件必须包含 `schema_version: 1`、dry-run 返回的 `anchors.proposed.source_checksum`、`human:<identity>` actor，以及 `decisions` 和 `prototype_decisions` 两个列表；没有对应歧义时保留空列表；
+- 每项决定使用 `keep-separate`，或使用带 `canonical_source_task_id` 的 `group`；两者都必须逐项绑定 dry-run 返回的 `source_task_ids` 并提供 rationale；
+- 每项 Prototype 决定使用 `choose-member`，逐项绑定 `conflict_id`、该冲突列出的 `member_id` 并提供 rationale；
+- 源 checksum、候选任务或决定格式变化时 fail-closed，必须重新 dry-run 和审阅。
+
+## 5. 布尔选项
+
+### 5.1 `--dry-run`
+
+- 适用命令：`init`、`upgrade`、`migrate`、`repair`、`compact`、`bootstrap`、`codegraph setup`、`codegraph sync`；
+- 只返回计划动作，不写文件、不创建 Git 仓库、不修改远程；
+- `upgrade --dry-run` 返回结构化 JSON，包括 additions、replacements、preserved、preserved_summary、conflicts、backups、compatibility、`contract_retirement` 中受 pending `UX-LF` 影响的开放迭代，以及只报告、不应用的 `prototype_migration` follow-up；`preserved` 中受管安装资产之外的明细最多为 200 条，完整计数和排除的 `.workflow/delivery/runtime` 瞬态根见 `preserved_summary`，省略明细不改变保留行为；
+- `migrate --dry-run` 返回 schemas、task_grouping、`prototype_migration`、conflicts、anchors、file_changes 和 `can_apply`；Prototype 报告精确区分零、单、多旧成员，并按 terminal、Page、route、file 给出合并结果；`repair --dry-run` 返回目标归档 checksum 与计划事务路径；`compact --dry-run` 返回 anchor、legacy revision 覆盖范围、原历史根摘要、loose/archive 字节数和预计净释放空间；
+- 用于安装、升级、迁移和冲突处理前审阅；
+- `inspect` 和 `doctor` 本身只读，不需要该参数。
+
+### 5.2 `--force`
+
+- 适用命令：`init`、`upgrade`、`bootstrap`；
+- `init`/`bootstrap` 的首次安装冲突备份到 `.workflow/delivery/runtime/backups/<timestamp>/`；`upgrade` 的备份随收据写入 `.workflow/delivery/runtime/upgrades/<upgrade-id>/`；
+- 可处理受管文件 checksum 冲突，以及用户明确批准的包版本降级；
+- 不会覆盖冲突的已批准规范正文；
+- 不会绕过远程冲突、非法代码路径、非空非 Git 目录、双 Git 共根、状态不一致或安全 Gate；
+- 必须先执行 `--dry-run` 并审阅影响，不能作为通用修复开关。
+
+`--dry-run --force` 可以预览强制替换计划，但不会实际备份或替换。
+
+## 6. 独立升级与回滚
+
+- 公开 `init` 只用于首次安装；已有安装清单时返回非零退出码并指向 `upgrade`。
+- `upgrade --dry-run` 严格零写，不创建收据目录，也不初始化或修改任一 Git 仓库。
+- `upgrade --dry-run` 不遍历 `.workflow/delivery/runtime` 瞬态根；受管安装资产之外的文件只在 `preserved` 中报告前 200 条，并由 `preserved_summary` 汇总完整数量。
+- `upgrade` 只安装迁移能力、处理旧 Gate 契约退休并报告 Prototype follow-up；不会写入 `.workflow/experience/<iteration-id>/` 的迁移目标。
+- 普通升级只替换清单拥有的 Skill、Hook、状态/Bootstrap/Evolution/Manager 运行时和受管配置贡献；保留产品、架构、体验、迭代、发布、规范、正式状态、用户配置部分和代码仓库。旧安装的 Viewer 作为带备份和 checksum 的 `remove` 操作进入升级 Receipt，受保护回滚可恢复原字节。
+- `upgrade` 会以 `ensure-directory` 新增项恢复旧安装缺失的 `.workflow/control/migrations/` 和 `.workflow/control/repairs/`；目录已存在但缺 `.gitkeep` 时，以 `ensure-directory-marker` 新增项只恢复 marker。已存在目录及其中用户物料不归安装器所有。
+- 受管副本相对安装清单发生本地漂移时列为 conflict；只有明确批准后才使用 `--force`。
+- 应用成功后返回 `upgrade_id`，备份和 `receipt.json` 位于 `.workflow/delivery/runtime/upgrades/<upgrade-id>/`。
+- `upgrade --rollback <upgrade-id>` 会恢复升级前受管副本和安装清单。升级后只要新增了 schema 2 正式事务或受管副本再次漂移，回滚就 fail-closed，并要求前向修复。
+
+## 7. 常用组合
+
+### 7.1 兼容迁移与前向修复
+
+先完成受管资产升级，再预览结构迁移：
+
+```powershell
+npx ai-delivery-workflow@latest migrate . --dry-run
+npx ai-delivery-workflow@latest migrate .
+```
+
+`migrate` 只在 `can_apply: true` 时应用。旧根布局的 `delivery/`、`control/`、`standards/` 被复制到 `.workflow/`，源文件保持逐字节不变；平铺任务在目标布局或原位任务 shard 中增加显式 `attempts`，替换前字节备份到 `.workflow/control/migrations/<migration-id>/backups/`。任务后缀只作为候选族提示；goal、scope、依赖、输出、验收或代码身份不一致时保留为人工歧义。
+
+存在歧义时，根据 dry-run 的 `task_grouping.decision_template` 创建决定文件并重新预览：
+
+```yaml
+schema_version: 1
+source_checksum: <dry-run anchors.proposed.source_checksum>
+actor: human:delivery-owner
+decisions:
+  - family: TASK-WP02
+    action: keep-separate
+    source_task_ids: [TASK-WP02-F1, TASK-WP02-F2, TASK-WP02-R1]
+    rationale: review 使用不同验收证据，不属于同一重试契约
+prototype_decisions:
+  - conflict_id: PROTO-CONFLICT-0123456789ABCDEF
+    action: choose-member
+    member_id: PROTO-WEB
+    rationale: 该成员是此稳定身份的已确认权威来源
+```
+
+```powershell
+npx ai-delivery-workflow@latest migrate . --decisions .\migration-decisions.yaml --dry-run
+npx ai-delivery-workflow@latest migrate . --decisions .\migration-decisions.yaml
+```
+
+Prototype 迁移中，合法零成员返回 `not-required`；单成员只在身份和所有 checksum 无歧义时自动迁移；多成员按 terminal、Page、route、file 合并，相同稳定身份的不同定义会阻塞并要求 `prototype_decisions`。旧 member/set、关闭或归档证据、Gate 和旧事件保持原字节；新内容只写入 `.workflow/experience/<iteration-id>/`，且开放迭代必须冻结新 revision 并重新通过 `UX-UI`。迁移生成的 `current_revision_ref: null` 不能直接交给 `prototype-review` 审批。完整说明见 [Prototype 迁移指南](PROTOTYPE-MIGRATION.zh-CN.md)。
+
+迁移不激活或关闭任务、不推断节点/版本完成、不修改 scope，也不重写旧事件。迁移后没有新增 schema 2 事务且迁移生成/替换的字节未漂移时，可用 `migrate . --rollback <migration-id>` 删除复制目标并恢复任务备份；出现新事务或字节漂移后只能前向修复。
+
+结构迁移和业务修复完成后，legacy 全量快照历史仍保持原位。只有维护者明确要求时才先预览压缩：
+
+```powershell
+npx ai-delivery-workflow@latest compact . --dry-run
+npx ai-delivery-workflow@latest compact .
+```
+
+apply 会把 anchor 覆盖的 legacy `artifact-registry` shards 原字节编码进 `.workflow/control/archives/history/artifact-registry/<anchor-id>.json.gz`，并写同名 checksum manifest。命令从 archive 重新解压并完整 replay，只有最终 registry checksum 与可信 anchor 完全一致后才移除 loose shards；任一 schema、entry、bundle、anchor 或 replay 校验失败都保持 loose history 不变。之后 `verify --history` 返回 `compacted-history` 并验证压缩包与锚点，新事务从锚点记录链头继续。
+
+错误归档使用独立命令：
+
+```powershell
+npx ai-delivery-workflow@latest repair . `
+  --invalidate-archive ITER-0001 `
+  --reason "归档早于已批准 Slice 完成" `
+  --actor human:delivery-owner `
+  --evidence RCA-PREMATURE-ARCHIVE `
+  --evidence RECOVERY-ITER-0001 `
+  --dry-run
+```
+
+审阅后移除 `--dry-run` 应用。命令要求至少两条 evidence，追加 `.workflow/control/repairs/transactions/` 中的 checksum 链式事务，并把该归档的当前资格投影为 `invalidated`；原 `.workflow/control/archives/versions/<iteration-id>/` 不会被改写或删除。
+
+最小项目级安装：
+
+```powershell
+npx ai-delivery-workflow@latest init . --workspace-id tasklite --code-path code --code-id tasklite-app
+npx ai-delivery-workflow@latest doctor .
+```
+
+### 7.2 `init` 后补绑远程仓库
+
+项目最初只在本地初始化时，可以先预览补绑结果，再使用同一条 `init` 命令写入两个 Git 根的 `origin`：
+
+```powershell
+npx ai-delivery-workflow@latest init . `
+  --workflow-remote git@gitee.com:example/tasklite-workflow.git `
+  --code-remote git@gitee.com:example/tasklite-code.git `
+  --dry-run
+
+npx ai-delivery-workflow@latest init . `
+  --workflow-remote git@gitee.com:example/tasklite-workflow.git `
+  --code-remote git@gitee.com:example/tasklite-code.git
+```
+
+补绑只设置 `origin` 并更新 `.workflow/config/workspace.yaml`，不会自动推送。首次推送必须分别在两个 Git 根执行：
+
+```powershell
+git push -u origin workflow/tasklite
+git -C code push -u origin main
+```
+
+其中 `workflow/tasklite` 应替换为配置文件中的 `workflow_repository.branch`，`code` 应替换为 `code_repository.path`。推送前先运行 `inspect`；如果 `ahead`、`behind` 同时大于零，表示本地与远端已经分叉，应先人工选择合并或变基策略，不要使用强制推送。远程非空时，代码远程必须存在 `main`；本地已有不同 `origin` 时命令会拒绝覆盖。绑定共享远程时使用 `--shared-remote`，不要同时提供另外两个远程参数。
+
+工作流和代码使用不同远程：
+
+```powershell
+npx ai-delivery-workflow@latest init . `
+  --workspace-id tasklite `
+  --code-path code `
+  --code-id tasklite-app `
+  --workflow-remote git@gitee.com:example/tasklite-workflow.git `
+  --code-remote git@gitee.com:example/tasklite-code.git
+```
+
+两个 Git 根共用一个远程：
+
+```powershell
+npx ai-delivery-workflow@latest init . `
+  --workspace-id tasklite `
+  --code-path code `
+  --code-id tasklite-app `
+  --shared-remote git@gitee.com:example/tasklite.git
+```
+
+先预览再确认替换受管文件：
+
+```powershell
+npx ai-delivery-workflow@latest upgrade . --dry-run
+npx ai-delivery-workflow@latest upgrade .
+npx ai-delivery-workflow@latest doctor .
+```
+
+只读检查和自主引导：
+
+```powershell
+npx ai-delivery-workflow@latest inspect .
+npx ai-delivery-workflow@latest bootstrap . --dry-run
+npx ai-delivery-workflow@latest bootstrap .
+```
+
+安装完成后应重新创建 Codex 任务，使项目级 Skill 和 Hook 信任状态重新加载。此后用户直接说“开始”“继续”“下一步”或描述需求，由 AI 自主选择内部 Skill 和 CLI。
+
+完整工作区结构和 Git 行为见[双仓工作区说明](DUAL-REPOSITORY-WORKSPACE.zh-CN.md)，整个系统的使用顺序见[完整项目手册](PROJECT-MANUAL.zh-CN.md)。

package/docs/CODEGRAPH-INTEGRATION.zh-CN.md

@@ -0,0 +1,89 @@
+# CodeGraph 可选集成指南
+
+CodeGraph 在 AI Delivery Workflow 中是代码智能适配器，用于定位符号、读取调用链和评估变更影响。它不属于正式状态机，不产生工作流节点、Gate、artifact registry 记录、事件、checkpoint、安装清单项或版本归档。
+
+## 1. 集成边界
+
+- 权威目标始终是 `.workflow/config/workspace.yaml` 中 `code_repository.path` 指向的代码仓库。
+- 当前进程 `CODEGRAPH_DIR` 指向的目录是代码仓内的本地可重建索引。工作流只接受专用名称 `.codegraph` 或 `.codegraph-*`，默认值是 `.codegraph/`；setup 把对应的根锚定目录（例如 `/.codegraph/` 或 `/.codegraph-win/`）写入该代码仓的本地 `.git/info/exclude`，不会修改受跟踪的业务文件。
+- `init` 和 `upgrade` 不安装 CodeGraph，也不初始化索引。
+- CodeGraph setup 不执行 `codegraph install`，不会修改 Codex、Cursor 或其他 Agent 的全局 MCP 配置。
+- CLI、索引或语言支持缺失时，Agent 降级到 Semble，再使用 `rg` 和定点源码读取；正式工作流继续运行。
+
+## 2. 前提
+
+CodeGraph CLI 是外部依赖，需要由用户显式安装并决定是否配置 MCP。工作流只检测 `codegraph` 命令，不把 `@colbymchenry/codegraph` 加入自身运行时依赖，也不代替用户升级第三方工具。
+
+先运行只读诊断：
+
+```powershell
+npx ai-delivery-workflow@latest doctor .
+```
+
+`doctor` 不调用可能打开 SQLite 的 `codegraph status`。它以 5 秒上限调用只读的 `codegraph --version`，并从 `CODEGRAPH_DIR`、索引目录和 `codegraph.db` 是否存在、真实路径、代码仓本地 Git 目录、effective ignore 与 tracked paths 做只读检查。CLI 不存在、探测超时、索引未初始化、索引路径越界、索引未被 Git ignore 或索引内存在已跟踪文件时输出 `WARN`，不会使工作流诊断失败；索引文件存在且隔离边界有效时输出 `PASS`。数据库健康度在实际 CodeGraph 查询时由 CodeGraph 自身判断，失败后仍按降级链继续。
+
+## 3. 显式初始化
+
+只有用户明确选择使用 CodeGraph 时才运行：
+
+```powershell
+npx ai-delivery-workflow@latest codegraph setup .
+```
+
+先预览可写动作时使用：
+
+```powershell
+npx ai-delivery-workflow@latest codegraph setup . --dry-run
+```
+
+`--dry-run` 只读取 `CODEGRAPH_DIR`、索引文件、Git 边界并调用 `codegraph --version`，返回 `planned_actions`；它不会调用 `codegraph status`、关闭 telemetry、写入 `.git/info/exclude`、打开 SQLite、创建索引或同步索引。
+
+setup 按以下顺序执行：
+
+1. 从权威工作区配置解析代码仓库。
+2. 从当前 `CODEGRAPH_DIR` 推导专用索引目录，校验其词法路径与真实路径，并确认代码仓拥有本地 Git 目录且索引中没有已跟踪文件。
+3. 调用 `codegraph --version` 确认 CLI 可用；索引是否初始化按 CodeGraph 的目录加 `codegraph.db` 规则只读判断。
+4. 在代码仓本地 Git exclude 中登记索引目录，使用 `git check-ignore` 验证规则实际生效；失败时恢复原 exclude。
+5. 执行 `codegraph telemetry off`，默认关闭匿名 telemetry。
+6. 仅在尚未初始化时执行 `codegraph init <code-repository>`。
+7. 写操作完成后才调用 `status --json`，确认代码仓和索引路径均未改变，并再次验证 ignored/untracked 边界。
+
+setup 不安装 CLI 或 MCP。CLI 缺失、代码仓不是独立 Git 根、`CODEGRAPH_DIR` 不是 `.codegraph`/`.codegraph-*` 专用目录、真实路径越界、索引未被 effective ignore、索引包含 Git 已跟踪文件、初始化失败或最终索引路径不匹配时返回非零退出码。工作流不会自动删除索引，也不会执行 `git rm --cached`；已跟踪索引必须由用户先显式处理。
+
+## 4. 增量同步
+
+代码变化后可以显式同步：
+
+```powershell
+npx ai-delivery-workflow@latest codegraph sync .
+```
+
+sync 要求索引已经初始化，执行 `codegraph sync <code-repository>` 后重新验证状态。`codegraph sync . --dry-run` 只报告本地 exclude 和同步计划，不执行写入或同步。工作流运行实际命令时通过 `CODEGRAPH_TELEMETRY=0` 禁用本次命令的 telemetry。CodeGraph 自身的文件监听和 debounce 行为仍由其版本负责。
+
+## 5. Agent 使用顺序
+
+解析代码或评估影响时使用以下顺序：
+
+1. MCP 可用且索引健康：`codegraph_explore`，`projectPath` 使用代码仓绝对路径。
+2. MCP 不可用但 CLI 可用：`codegraph explore "<query>" --path <code-repository>`。
+3. CodeGraph 不可用或失败：Semble。
+4. 需要全部字面量命中或进一步核实时：`rg` 和定点读取源码。
+
+CodeGraph 返回的符号、调用链和影响关系用于导航；最终结论以实际源码、配置和测试结果为准。
+
+## 6. 测试影响分析
+
+`codegraph affected` 可以生成推荐测试建议，但当前版本不把它接入正式 Gate，也不允许据此缩减既有必跑测试。引入门禁前必须先用真实变更样本评估漏报率、跨语言准确性和索引陈旧风险。
+
+## 7. Windows 与 WSL
+
+Windows 与 WSL 共用同一个 checkout 时，不应共享同一 SQLite 索引。分别把 `CODEGRAPH_DIR` 设置为代码仓下不同的专用直接子目录，例如 `.codegraph-win` 和 `.codegraph-wsl`；setup 会按当前进程环境分别登记本地 exclude，并在写操作后核对 `status.indexPath`。两个索引都必须保持本地、可重建和未跟踪。
+
+## 8. 故障处理
+
+- `doctor` 为 `WARN`：继续使用降级搜索链，按需由用户决定是否 setup。
+- setup 报 CLI 不存在：用户先安装 CodeGraph，再重新执行 setup。
+- status 或 sync 失败：保留现有索引字节，检查 CodeGraph 自身输出；工作流不自动执行 `uninit`、`index --force` 或升级。
+- 索引陈旧：运行 `codegraph sync`；仍异常时按 CodeGraph 官方恢复方式处理。
+
+CodeGraph 故障不会触发正式状态修复、任务重试、重新切片或工作流迁移。

package/docs/DUAL-REPOSITORY-WORKSPACE.zh-CN.md

@@ -44,7 +44,7 @@ node bin/ai-delivery.mjs init C:\work\tasklite --workspace-id tasklite --code-pa
 
 工作流仓库使用 `workflow/tasklite`，代码仓库使用 `main` 及各研发、发布分支；两者虽然 origin 相同，但 Git 根和提交历史职责独立。
 
-升级仍含 `.ai-delivery/` 的旧项目时，`init` 会先把旧目录完整备份到 `.workflow/delivery/runtime/backups/<timestamp>/legacy-ai-delivery/`，再迁移配置、状态 CLI、Hook 和查看器。只有新核心文件验证完成后才删除旧目录；失败时保留旧目录和备份。迁移成功后 `.workflow/config/workspace.yaml` 是唯一权威配置，不再双写或回退读取旧路径。
+升级仍含 `.ai-delivery/` 的旧项目时，安装器会先把旧目录完整备份到 `.workflow/delivery/runtime/backups/<timestamp>/legacy-ai-delivery/`，再迁移配置、状态 CLI、Hook 和 Workflow Manager；旧 Viewer 随迁移备份后移除。只有新核心文件验证完成后才删除旧目录；失败时保留旧目录和备份。迁移成功后 `.workflow/config/workspace.yaml` 是唯一权威配置，不再双写或回退读取旧路径。
 
 如果 `code/` 已是独立 Git 仓库，初始化器会绑定它。以下情况会拒绝：非空但不是 Git 的代码目录、绝对路径或多层路径、越界路径、符号链接、与工作流仓库相同的 Git 根。
 
@@ -114,7 +114,7 @@ node bin/ai-delivery.mjs doctor <workspace>
 node bin/ai-delivery.mjs state verify --project <workspace>
 ```
 
-安装后，用户只需在项目根对 AI 说“开始”“继续”“下一步”或直接描述需求；AI 自主调用项目内 Bootstrap、Checkpoint 和后续 Skills。项目内 `inspect` 同时报告工作流 Git 和代码 Git 的 branch、head、dirty paths、upstream 同步状态，以及共享任务/checkpoint 恢复建议。查看器展示两套 Git、未提交或未推送警告、研发和发布双轨，以及代码 Tag、工作流 Tag、Manifest checksum 的追踪关系。
+安装后，用户只需在项目根对 AI 说“开始”“继续”“下一步”或直接描述需求；AI 自主调用项目内 Bootstrap、Checkpoint 和后续 Skills。项目内 `inspect` 同时报告工作流 Git 和代码 Git 的 branch、head、dirty paths、upstream 同步状态，以及共享任务/checkpoint 恢复建议。Workflow Manager 展示工作区与代码仓分支上下文、正式七节点状态、需求、任务、测试、交付成果、决策、原型、项目系统、Mock 和不可变事件；未登记关系不会靠标题相似度猜测。
 
 ## 7. 全流程样本
 

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

@@ -7,7 +7,7 @@
 | `lib/evolution.mjs` | 状态机、风险、checksum、trial、Hook 调度和导出实现 |
 | `skills/ai-delivery-orchestrate/assets/project-template/.workflow/tools/evolution/evolve.mjs` | 安装后自包含 wrapper |
 | `skills/ai-delivery-evolve-workflow/` | AI 交互、证据门槛和治理契约 |
-| `lib/project-installer.mjs` | 运行时复制、manifest schema 5、升级和 doctor |
+| `lib/project-installer.mjs` | 运行时复制、manifest schema 6、独立升级/回滚和 doctor |
 | `verification/evolution.test.mjs` | 公共 CLI 行为测试 |
 
 不要修改临时安装项目中的 `.workflow/tools/evolution/` 后再复制回维护仓库。`lib/evolution.mjs` 是行为权威，安装副本由 `init` 生成。
@@ -21,7 +21,7 @@
 .workflow/tools/evolution/evolution-runtime.mjs
 ```
 
-它复用 `.workflow/tools/state/vendor/yaml/`，不修改业务项目 `package.json`。安装清单 schema 5 保存 Evolution CLI 路径、Hook 协议版本和运行时 SHA-256。schema 4 项目重新执行 `init` 时升级受管运行时，同时保留既有工作流物料。
+它复用 `.workflow/tools/state/vendor/yaml/`，不修改业务项目 `package.json`。安装清单保存 Evolution CLI 路径、Hook 协议版本、受管运行时 SHA-256、Workflow Manager 和合并配置表面。已安装项目通过独立 `upgrade --dry-run` 审阅并执行升级，不重复运行 `init`；旧 schema 必须先经过兼容迁移或状态修复。
 
 ## 3. 数据一致性
 
@@ -39,7 +39,7 @@
 1. `HIGH_CAPABILITIES` 或 `MEDIUM_CAPABILITIES`；
 2. Skill 契约和用户指南；
 3. 风险抬升测试；
-4. 查看器展示需要的新状态。
+4. Workflow Manager 事实投影需要展示的新状态。
 
 `block` 或 `.mjs` entrypoint 永远派生为 high。Node 18 没有可依赖的强安全沙箱，因此不要在文档或代码中宣称脚本被完全隔离。
 
@@ -49,9 +49,9 @@ Hook schema 1 要求 `event_id`、`idempotency_key`、`event_type`、时间、sc
 
 `skills/ai-delivery-checkpoint-task/scripts/hook-event.mjs` 是安装源；项目模板内同名文件是审阅副本，两者必须保持一致。Checkpoint 的 `task-state.mjs` 和正式状态 CLI 会主动发出业务协议事件；Codex 原生生命周期事件只记录 heartbeat。带 `schema_version: 1` 和 `event_type` 的 Evolution 事件才会进入扩展调度。
 
-## 6. 查看器
+## 6. Workflow Manager
 
-查看器只解析 `.workflow/evolution/index.yaml` 和 Git 跟踪的 evolution 文件。不得扫描 `.workflow/delivery/runtime/evolution/`，不得新增写 API。修改自进化摘要时同步验证桌面和移动端布局。
+Workflow Manager 只展示正式、可共享的 Evolution 摘要；不得扫描 `.workflow/delivery/runtime/evolution/` 原始队列，也不得在 Manager 中复制批准、启用或回退实现。正式 Evolution 写入继续由 `evolve.mjs` 治理。修改摘要时同步验证两个支持的桌面视口。
 
 ## 7. 验证
 
@@ -60,7 +60,7 @@ Hook schema 1 要求 `event_id`、`idempotency_key`、`event_type`、时间、sc
 ```bash
 node --test verification/evolution.test.mjs
 node --test verification/project-installer.test.mjs
-node --test verification/workflow-viewer.test.mjs
+node --test verification/workflow-manager*.test.mjs
 npm run skills:validate
 ```
 
@@ -72,4 +72,4 @@ npm run audit:verify
 npm run pack:check
 ```
 
-还应在隔离项目执行 `init`、项目内 `evolve inspect/verify`、`doctor`，删除查看器和扩展后复核核心工作流仍可运行。
+还应在隔离项目执行 `init`、项目内 `evolve inspect/verify`、`doctor` 和 Manager 启动，并在扩展缺失时复核核心工作流仍可运行。

package/docs/EVOLUTION-USER-GUIDE.zh-CN.md

@@ -155,6 +155,6 @@ node .workflow/tools/evolution/evolve.mjs export --extension-id EXT-001 --versio
 
 `export` 只在 `.workflow/evolution/promotion/` 生成脱敏、本地 bundle，不会上传或发送到维护仓库、其他项目或外部服务。
 
-## 9. 查看器
+## 9. Workflow Manager
 
-查看器的“自进化控制环”区域展示反馈、待处理提案、trial、active、高风险生效、回退和 Hook 结果数量。所有治理物料仍可在物料表中筛选和预览。查看器没有批准、启用、回退或导出接口。
+Workflow Manager 可以展示反馈、待处理提案、trial、active、高风险生效、回退和 Hook 结果的正式摘要。批准、启用、回退和导出仍由项目内 Evolution CLI 执行；Manager 不复制其状态机，也不读取 runtime 原始队列。