ai-delivery-workflow 0.2.2 → 0.4.0

package/docs/agents/workflow-manager-agent-interface.md

@@ -0,0 +1,145 @@
+# Workflow Manager Agent Interface
+
+本文规定 AI 通过发行包提供的受限 CLI 操作 Workflow Manager 的固定流程。动作名称、输入字段和版本化 JSON Schema 的唯一事实源是 `workflow-manager.contracts.v1`；本文只规定调用顺序、证据检查和恢复方式。
+
+## 1. 接口边界
+
+Agent Interface 与 UI、HTTP 使用同一应用服务和业务规则。AI 可以读取正式资源、提出关系建议、执行已授权的受控动作并检查结果。AI 不得直接修改 YAML、不得执行任意 shell、不得把浏览器自动化或一次性仓库脚本当作正式接口，也不得绕过 Prototype-first、人审 Gate、Revision/checksum 或分支限制。
+
+维护仓库使用 `node bin/ai-delivery.mjs manager ...`；安装后的业务项目使用 `node .workflow/tools/manager/manager.mjs ...`。以下步骤中的 `manager` 代表上述任一入口。
+
+## 2. 固定调用流程
+
+### 2.1 先读取契约
+
+```text
+manager list --resource contracts
+manager action <action-name> --help
+```
+
+确认返回的 `schema_version` 是调用方支持的 `workflow-manager.contracts.v1`，再从动作契约读取 `authorization`、`concurrency`、`retry`、`planning`、`input_schema` 和 `output_schema`。未知 Schema 或未知动作立即 fail-closed。
+
+完成条件：已选动作存在，actor 类型、必填字段、并发模式和是否需要 plan 均明确。
+
+### 2.2 读取目标资源
+
+使用 `manager list|show|export --resource <resource>` 读取当前事实。可用资源由 `manager --help` 和 `contracts` 资源共同发现；`attachments` 的单项读取还要求精确附件编号与 checksum。
+
+记录目标的稳定身份、项目/工作区、分支、迭代、实体 Revision、集合 `expected_revision`、`expected_checksum`，或正式状态的 `expected_scope_revision`。不得从旧聊天记录猜测这些字段。
+
+完成条件：精确目标及当前并发令牌来自本次读取。
+
+### 2.2.1 Prototype Revision v2 资源上下文
+
+`manager list|show|export --resource prototypes` 返回 `workflow-manager.prototypes.v2`。每个响应都带有 `context`，其中固定包含 `project`、`workspace`、当前 `branch`、`iteration_id`、`prototype_revision_id`、`prototype_revision_checksum` 和 `terminal_id`；这些值是本次读取的范围，不得由调用方补写或猜测。
+
+已登记 Revision 还包含 `catalog_schema_version`、`terminals` 与 `catalog_summary`。`catalog_summary` 记录 Component Registration、Data Contract、Component Candidate、component binding、implementation mapping 和 Source Inspection Snapshot 的登记数量。`terminals` 是独立 Logical Terminal 的稳定身份和生命周期，而不是视口或权限场景。
+
+读取 P07、P11-P17 对应的 Project Prototype 事实时，显式传入 `--terminal-id all` 或一个本次响应 `terminals` 中的 `terminal_id`：
+
+```text
+manager show --resource prototypes --terminal-id all
+manager show --resource prototypes --terminal-id TERM-WEB
+```
+
+HTTP 使用同名查询参数 `terminal_id`。响应的 `terminal_scope` 与 `context.terminal_id` 说明实际范围；单终端范围只返回该终端所属的 Page、Review Scene 和路由，`terminals` 注册表仍完整返回以支持下一次选择。未知或格式错误的终端统一返回 `{ "error": { "code": "prototype-terminal-invalid", "message": "..." } }`，不得退回到 `all`、首个终端、首个 Page 或首个 Scene。恢复时重新读取终端注册表并使用已登记身份重试。
+
+`prototype-change-request-create`、`prototype-review-batch-finalize` 和 `prototype-page-review-apply` 都要求精确 `terminal_id`。调用方还必须使 Page 与可选 Review Scene 同属该终端；跨终端输入 fail-closed。修改要求、审核批次、Page Receipt 以及相应 Workflow Manager Receipt/Event 都保留终端事实，因此后续编辑、附件、执行或废弃会重新验证已有目标，不能跨终端漂移。
+
+当请求显式 `--revision` 时，即使 `UX-VS` 尚未批准，Manager 也先验证该 Revision；无效、旧格式、缺少目录或 checksum 漂移的 Revision 一律返回 `{ "error": { "code": "prototype-revision-invalid", "message": "..." } }`。包内 CLI、安装后 CLI 与 HTTP 使用同一错误结构。恢复时不要回退到默认 Revision：修复或重新读取确切 Revision 后重试。
+
+### 2.2.2 P14-P17 终端范围追踪与恢复
+
+P14 路由目录与 P15 路由关系的 P13 跳转必须同时携带 `page`、可选 `projectScene`、`terminal_id`、`revision` 和 `expected_checksum`。P13 用同一份 `prototypes` 资源请求验证该 Revision；CLI 使用 `--revision` 与 `--expected-checksum`，HTTP 使用 `revision` 与 `expected_checksum`。请求的 descriptor checksum 不等于当前读取的 `prototype_revision_checksum` 时，CLI、HTTP 和 UI 都返回或显示 `{ "error": { "code": "prototype-revision-invalid", "message": "Prototype revision checksum mismatch." } }`，不得展示默认 Revision 或改用同名 Page。
+
+P16 在 `terminal_scope` 内只返回该终端的 `change_requests`、`review_batches` 与 `discarded_tombstones`。每条记录保留 `prototype_revision_id`、`prototype_revision_checksum`、`terminal_id`、Page/Scene 身份、状态、Revision、时间及执行状态；已废弃要求只保留墓碑身份、批次、时间和理由，正文与附件不再是可执行输入。调用方不得将一个终端的批次、执行或墓碑推断到另一个终端。
+
+P17 的 `revision_history` 是只读的冻结 Revision 证据。每条可用记录包含稳定的 `path`、descriptor `checksum`、`prototype_revision_id`、`terminal_id`、`catalog_summary` 和 `revision_diff`；差异集合至少覆盖 `terminals`、`pages`、`review_scenes`、`trigger_conditions`、`routes`、`ui_mapping`、`review_units`、`review_unit_pages` 及已登记的组件、数据和源码快照事实。`draft` 后继 Revision 不是不可变历史，不会出现在该列表。
+
+### 2.2.3 Source Inspection Snapshot 受控读取
+
+源码审查只通过 `prototype-source-snapshots` 资源读取，不接受 `source_ref`、本地路径或命令参数：
+
+```text
+manager show --resource prototype-source-snapshots --terminal-id TERM-WEB \
+  --revision prototype/revisions/PROTOTYPE-REVISION-0001/prototype-revision.yaml \
+  --expected-checksum <sha256>
+manager show --resource prototype-source-snapshots --source-snapshot-id SRC-P01-IMPLEMENTATION \
+  --terminal-id TERM-WEB --page-id P01 --revision <relative-revision> \
+  --expected-checksum <sha256>
+```
+
+每次请求都必须带精确 `revision` 与 `expected_checksum`；缺任一字段时不会回退到当前 Revision。列表响应只包含 Revision 明确登记的 `source_snapshot_id`、`asset_kind`、Page/Scene/Terminal 范围、相对 `source_ref`、checksum、语言和 `scene_branch`。带 `source_snapshot_id` 的响应才包含只读 `content` 及其只读标记，并再次校验来源文件 checksum。请求合法 Scene 时可以同时看到该 Page 的共享主实现和该 Scene 的状态分支；页面和 Scene 身份及其 Terminal/Page 关系会先验证。跨终端、跨 Page/Scene、坏 checksum、未登记身份和任意路径参数统一 fail-closed。CLI、HTTP 的 `/api/v1/resources/prototype-source-snapshots`（以及按 ID 的只读别名）与 UI 使用同一应用服务和错误结构。
+
+P14 生成的源码入口必须携带 `page`、可选 `projectScene`、`terminal_id`、`revision`、`expected_checksum`、`tab=source` 和登记的 `source_snapshot_id`。P13 源码模式只显示这些快照的内容、Scene 分支和验收映射，不提供路径输入、编辑、下载执行或命令入口。
+
+`inspection_status: "unavailable"` 表示一个冻结历史 descriptor 不能通过正式 `validatePrototypeRevision`，但其路径与可读取的 descriptor checksum 仍作为恢复锚点返回。其 `inspection_error` 使用 `prototype-revision-invalid` 代码；后续可用记录的 `revision_diff.status: "history-gap"` 不跨该断点推断差异。先修复或重新读取明确 Revision，再以同一 `terminal_id`、`revision` 和 `expected_checksum` 重试；在断点存在时不得把后续基线误报为连续比较。
+
+### 2.3 构造输入
+
+输入必须严格符合动作 `input_schema`，不带额外字段。actor 使用契约允许的 `human:<identity>` 或 `agent:<identity>`；需要人审的动作只有真实人工决定后才使用 human actor。
+
+每次逻辑意图生成一个 `idempotency_key`。网络或进程中断后的同意图重试复用原键；改变目标、正文、计划或决定时生成新键。更新单个实体时同时携带实体 Revision；更新集合时携带 `expected_revision` 与 `expected_checksum`。
+
+完成条件：输入通过动作 Schema，且身份、actor、并发令牌和幂等键均绑定当前意图。
+
+### 2.4 执行计划
+
+契约的 `planning.mode` 为 `required-before-apply` 时，先执行对应 `*-plan` 动作。plan 是 dry-run：它可以读取和校验，但不修改正式状态。核对影响实体、分支、文件、进程或 Mock 定义后，保存返回的 plan checksum。
+
+apply 必须携带相同意图和精确 `expected_plan_checksum`。输入、目标 Revision/checksum、分支或外部状态发生变化时旧计划失效，重新读取资源并生成新计划。
+
+P10 设置更新固定使用 `settings-update-plan` 后接 `settings-update-apply`，不提供绕过计划的直接更新动作。plan 只返回受影响偏好、预期 Revision 和 checksum；UI 或 Agent 对任一设置输入的修改都会使旧 plan 失效。apply 还必须携带该 plan 的 `expected_plan_checksum`，并产生同一事务中的 Receipt 与 Event。
+
+完成条件：计划影响已核对，apply 输入绑定当前计划 checksum。
+
+### 2.5 执行变更
+
+把 JSON 输入保存到工作区内受控临时文件，调用：
+
+```text
+manager action <action-name> --input <json-file>
+```
+
+接口先校验 Schema、actor、合法转换、Revision/checksum、plan checksum 和幂等语义，再通过与 UI 相同的应用服务提交。任何 stale、checksum mismatch、target drift、非法状态转换或权限错误都保持 fail-closed。
+
+完成条件：命令返回结构化 `outcome`，没有依靠界面文案推断成功。
+
+### 2.6 核对结果
+
+成功 mutation 必须返回或可定位不可变 Receipt 与 Event。核对 actor、时间、输入 Revision/checksum、受影响身份、outcome 和错误明细，再重新读取目标资源及事件资源，确认投影与 Receipt/Event 一致。
+
+`idempotent-replay` 表示同一 `idempotency_key` 的既有结果被安全返回，不代表再次执行了写入。无 Receipt/Event、资源投影不一致或事件不可查询时，不得把动作报告为完成。
+
+完成条件：结构化结果、Receipt、Event 和重读投影四者一致。
+
+## 3. Outbox 与恢复
+
+Workflow Manager 的事务层先准备业务写入、Receipt 与 Event，再原子提交；Outbox 表示提交后可观察的不可变事件记录，不是第二写入口。调用方不得直接编辑、删除或重放 Outbox 文件来改变业务状态。
+
+| 情况 | 恢复动作 |
+| --- | --- |
+| 响应丢失或客户端超时 | 使用原 `idempotency_key` 重试同一输入；接受 `idempotent-replay`，随后重读资源和 Event。 |
+| `stale` Revision/checksum | 不覆盖；重新读取资源，重新评估意图，使用新并发令牌和新幂等键。 |
+| plan checksum 失效 | 重新执行 plan、核对新影响，再用新 `expected_plan_checksum` apply。 |
+| P10 设置输入在 plan 后改变 | 丢弃旧 `settings-update-plan` 结果，重新读取设置并生成新 plan；不得复用旧 checksum。 |
+| 分支或目标漂移 | 切回已登记且受信任的当前分支/工作区，或停止并交给人工；不得降级为任意命令。 |
+| Schema/动作未知 | 升级调用方或工作流包后重新读取 `contracts`；保持 fail-closed。 |
+| Receipt/Event 与投影不一致 | 停止后续写入，保留原输入和幂等键，运行只读检查并交给维护者恢复事务。 |
+| 人工决定缺失 | 停止；AI 建议保持 suggested，不能登记成 confirmed、approved 或 completed。 |
+
+## 4. 可变性
+
+需求、任务、测试用例和设置通过版本化动作更新；测试执行、审核批次、Page Receipt、审批、Receipt 和 Event 是不可变证据。原型修改要求在进入 AI 执行前可以追加修订或按契约废弃；执行开始后只能追加执行尝试、结果或由新 Revision 取代，不能原地覆盖历史。
+
+项目系统和 Mock 的多实体操作必须 plan/apply。项目系统生命周期只允许 Registry 声明的受限命令；初始化脚本只允许 Registry 管理的项目内路径。Mock 同步只处理已登记协议和场景，不提供任意文件编辑或外部系统权限。
+
+## 5. 最小核对清单
+
+- 契约 Schema、动作和资源已从当前安装读取。
+- actor 与真实授权一致。
+- 稳定身份及 Revision/checksum 来自本次读取。
+- 多实体动作已有当前 plan 和 `expected_plan_checksum`。
+- 重试复用原 `idempotency_key`，新意图使用新键。
+- 结果、Receipt、Event 与重读投影一致。
+- 原型修改、人审 Gate、分支和 Mock 边界没有被绕过。

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

@@ -0,0 +1,205 @@
+# 工作流与工作流管理器阶段现状
+
+更新时间：2026-08-21
+
+本文是继续设计、实现或审核 Workflow Manager 时的阶段入口。它区分已经进入正式工作流源码的能力、已经接受但尚未实现的产品决策、仅在隔离原型中验证的交互，以及仍未完成的事项。领域术语以根目录 `CONTEXT.md` 为准，不以本文替代 ADR、正式状态契约或 Issue。
+
+## 1. 当前基线
+
+- 当前仓库是 `ai-delivery-workflow` 的维护与发行源码仓库，不是安装了工作流的业务项目。
+- 当前实施分支为 `codex/workflow-manager-foundation`；Workflow Manager 实现在 `ae70304`，外部 Issue 收尾在 `e727af1`。`0.4.0` 的最终候选身份、校验和及生命周期证据记录在维护仓库的 `audit/WORKFLOW-MANAGER-P0-P1-P2-CLOSURE.md`；该记录不随安装包分发，候选包和展开验证工作区保留在被忽略的 `.tmp/`。工作树仍包含用户维护的文档和参考资料变更。
+- 正式维护源码位于 `bin/`、`lib/`、`skills/`、`docs/`、`verification/` 和 `audit/`。
+- Workflow Manager 设计原型位于 `.tmp/workflow-manager-prototype/`，属于可重建临时物料，不进入发行包，也不等于正式前端已经实现。
+
+## 2. 已进入正式工作流源码
+
+### 2.1 七节点研发流程
+
+正式研发生产路线已经收敛为：
+
+```text
+00-bootstrap
+  -> 01-product-shaping
+  -> 02-solution-design
+  -> 03-delivery-readiness
+  -> 04-implementation
+  -> 05-candidate-assurance
+  -> 06-version-closeout
+```
+
+- `00-bootstrap` 建立或恢复项目上下文基线。首次初始化后，后续会话只做恢复和只读检查；它不定义产品、架构或 UI，不启动中间件，也不实现或发布功能。
+- `01` 至 `03` 是设计流程，`04` 至 `06` 是开发流程。
+- `03-delivery-readiness` 冻结 Slice、需求、验收、必需任务和必需物料；`04-implementation` 生成不可变候选版本；`05-candidate-assurance` 对绑定的候选版本做完整验证；`06-version-closeout` 形成 `release-ready` 版本物料。
+- 历史十三节点研发模型只读兼容；新任务、物料、流转、候选版本、Gate 和版本收尾不得再写入旧节点。
+- `R00` 至 `R10` 是独立发布流程。当前 Workflow Manager 原型暂不展示发布模块，但正式状态契约仍保留该流程。
+
+### 2.2 正式节点状态
+
+正式节点状态不是人工选择，也不能只由一个子任务状态决定。`state inspect` 的 `derived_node_states` 综合以下事实派生：
+
+- 当前冻结 Scope Manifest；
+- 稳定任务及其 attempts、phases 和最新阻塞发现；
+- 强制 Gate 决定；
+- 已登记物料及 checksum；
+- 当前不可变候选版本；
+- 节点完成凭证。
+
+可见状态为 `pending`、`active`、`waiting`、`blocked`、`ready-to-complete` 和 `completed`。受新契约治理的节点只能从 `ready-to-complete` 完成，并生成绑定上述事实的不可变 completion receipt。
+
+### 2.3 Slice、任务和历史
+
+- Delivery Readiness 后使用 `scope freeze` 冻结范围；只有明确人工批准的 `scope amend` 可以改变范围。
+- Slice 超出逻辑任务数、活跃工时、墙钟时长或阻塞修复轮次预算时，只执行 `scope warn`。其结果固定为 `warn-only` 和 `reslice_performed: false`，不会自动重新切片、重排计划或改变验收。
+- 任务使用一个稳定任务 ID，并在任务内部记录 attempt 和 phase。过去的 `F/R/T/P/vN` 后缀任务模式已被替代。
+- 物料登记、事件分片、可信快照、历史校验、prune 和 compact 已进入正式源码；正式 revision 和审核凭证不可原地覆盖。
+
+### 2.4 原型优先 UI 治理
+
+- 不再使用 UX-LF。`UX-VS` 负责视觉规范确认，`UX-UI` 负责正式原型审核，两者归入 `02-solution-design`。
+- 所有用户可见 UI 修改都遵守“先修改隔离 Prototype -> 用户确认 -> 再修改正式前端”，不存在小改、紧急修复或业务逻辑调整例外。
+- 一个项目只有一个逻辑 Prototype。Page 是稳定路由页面，Review Scene 是 Page 的可审核状态；原型必须列出错误、空态、权限、恢复等正式系统中只在条件满足时出现的状态。
+- 页面级 Prototype 审核、Revision/checksum 绑定、Review Shell、Page Receipt、正式前端守卫和 Candidate Assurance UI Acceptance 已进入维护源码。
+- 一个 Page 可以反复修改和审核；每轮使用新的 Prototype Revision、审核批次和 checksum，历史轮次不可覆盖。
+- 修改要求尚未进入 AI 执行且没有 Prototype Adjustment 时可由人确认废弃。AI 已读取但尚未执行仍可废弃；废弃正文和附件退出执行范围，只保留审计墓碑。
+- P14 到 P13 的 Source Inspection Snapshot 受控审查已进入正式源码。新版 catalog 为每个页面主实现、Scene 状态分支和验收资产登记稳定身份、终端/Page/Scene 范围、相对来源、语言、作用和 checksum；CLI、HTTP 与 UI 共用只读快照服务，拒绝任意路径、编辑、执行、未登记身份、跨终端目标和来源 checksum 漂移。
+
+### 2.5 Mock、CodeGraph 和升级
+
+- Microcks 是默认项目级 Mock System。External Dependency Mock 和 Product Backend Mock 分开管理；协议定义和 Mock Scenario Pack 可版本化，运行数据库、流量和日志可丢弃。
+- CodeGraph 是可选、可降级的代码导航适配器。工作流只管理项目索引，不安装全局 MCP；不可用时降级到 Semble 和 `rg`，其分析结果不能替代正式 Gate 或既定测试集。
+- 面向旧项目的 Prototype 迁移、UX-LF 契约退役、升级保护报告、UI Acceptance 迁移和历史压缩均已有正式实现和验证。
+
+## 3. 已实现的 Workflow Manager 契约
+
+### 3.1 产品边界
+
+项目绑定的 Workflow Manager 已取代 Workflow Viewer 和独立的用户可见 Review Server。它负责工作流状态、合法流转、人工决策、项目原型审核、项目系统、Mock、需求、任务、测试、交付成果、事件和设置。
+
+Workflow Manager 不是任意命令执行器、文件编辑器或 AI 执行器。它只暴露有契约的读取和变更动作；直接 YAML 修改、任意 shell、任意文件路径和绕过 Gate 均不属于产品能力。
+
+### 3.2 AI 协作契约
+
+Workflow Manager 从一开始就是人和 AI 共同使用的控制面。UI 与 Workflow Manager Agent Interface 必须调用同一应用服务和业务规则：
+
+- 每个读取能力提供稳定编号、项目/工作区/分支/迭代/Revision/checksum 上下文，以及版本化 JSON 的 `list`、`show`、`inspect` 或 `export` 命令。
+- 每个写能力提供 package-delivered CLI/脚本、精确目标、expected revision/checksum、必要的 dry-run/plan、幂等语义、结构化结果、Receipt 和不可变事件。
+- AI 可以发现关系、检查覆盖缺口、分析影响和执行经授权的受控动作；AI 建议不能自动成为正式关联，也不能自动修改需求、任务或节点状态。
+- 浏览器自动化不是正式 Agent Interface，临时仓库脚本也不能替代发行包提供的受控接口。
+
+### 3.3 视觉与技术方向
+
+- 已接受的视觉规范为 Operational Carbon：IBM Plex、白色/浅灰平面层级、1px 分隔线、0-2px 圆角、蓝色仅用于主操作和选中、显式语义状态色。
+- 正式目标为桌面端 `1280x720` 和 `1440x900`，最小宽度 `1180px`；移动端不在范围内。
+- 默认 UI 组件体系为 shadcn，图标统一使用 Lucide，管理界面使用中文。界面避免直接显示用户难以理解的术语，例如将 Artifact 表达为“交付成果”或具体业务物料名称。
+
+### 3.4 页面与导航
+
+当前设计包含 19 个固定且唯一的 Page 编号。编号只允许追加，不得重排或复用；Review Scene 使用 `Pxx-Syy`，管理器 Global Surface 使用 `Gxx/Gxx-Syy`，业务项目原型使用独立的 `APP-Pxx/APP-Pxx-Syy` 编号域。
+
+| 模块 | 页面 |
+| --- | --- |
+| 工作台 | `P01` 工作台 |
+| 交付管理 | `P02` 开发工作流、`P19` 产品需求、`P03` 任务执行、`P18` 测试用例、`P04` 交付成果 |
+| 人工决策 | `P06` 决策收件箱 |
+| 项目原型 | `P07` 项目原型概览、`P11` 视觉规范、`P12` 原型审批、`P13` 页面审核详情、`P16` 修改要求、`P14` 页面路由、`P15` 路由关系、`P17` 修订记录 |
+| 运行环境 | `P08` 项目系统、`P09` 模拟服务 |
+| 记录与追踪 | `P05` 操作与变更记录 |
+| 系统 | `P10` 设置 |
+
+`P13` 是上下文详情页，从 `P12`、`P14`、`P15` 或 `P17` 进入，不作为固定子菜单项。`P07-S06` 至 `P07-S18` 已永久退役且编号永不复用。
+
+### 3.5 页面职责
+
+- `P01` 只回答“当前最需要关注什么、下一步去哪里”，不复制完整工作流或决策事实。
+- `P02` 展示七节点、所选节点的工作内容、状态依据、合法流转和事实页下钻入口。任务、交付成果、事件/运行凭证和人工决策共同形成状态输入。
+- `P03` 管理稳定任务、attempt、phase、依赖、验收、计划输出、下一行动和恢复入口。
+- `P04` 管理交付成果版本、checksum、路径、生成方、有效性和引用关系。
+- `P05` 保存不可变操作与变更历史，不直接修改当前状态。
+- `P06` 没有决策超时；批准和退回都允许附加可选评论并供 AI 读取。UX 决策在 P11/P12 完成，P06 只提供摘要和入口。
+- `P18` 管理测试用例版本和执行记录。Delivery Readiness 确定必需用例，Implementation 实现自动化，Candidate Assurance 对绑定候选版本执行完整验证。
+- `P19` 使用通用关系模型连接需求与任意相关任务、原型、测试、交付成果、决定和事件，不把“前端任务/后端任务”写死为分类。
+
+### 3.6 项目原型审核
+
+- `P07` 只汇总当前迭代的视觉规范、Page/Scene 审核覆盖、修改要求、路由完整性和 Revision 有效性。
+- `P12` 提供当前迭代完整、可筛选的业务 Page 队列；`P13` 完整显示一个 Page 的所有 Review Scene、准确路由、绑定身份和审核动作。
+- 打开 Scene 只切换目标，不算完成审核；明确记录绑定 checksum 的 Scene 审核事实后才计入覆盖。全部必审 Scene 有效后才能生成 Page Receipt。
+- 修改要求支持文字和截图，草稿可多次编辑；审核批次固定后不可修改。用户在其使用的任意 AI 对话中说“按要求修改”或指定编号，AI 才读取已完成批次并开始调整。
+- `P14` 是路由目录，`P15` 是由目录派生的路由关系图。P14/P15 节点可携带 Page、Scene、Logical Terminal、Revision、Prototype Revision checksum 和 Source Inspection Snapshot 身份跳转到 P13；P13 的源码模式只显示登记快照和 Scene 验收映射。
+- `P16` 展示修改要求、审核批次、AI 读取、执行尝试和调整结果；`P17` 展示跨 Revision 的时间线和差异。
+
+### 3.7 项目系统与 Mock
+
+- `P08` 的架构视图和列表视图分为两个 Tab。架构拓扑来自声明的预期架构，即使节点尚未实现或启动也必须显示；未实现节点使用虚线状态，注册实现后才允许跳转和受控管理。
+- 项目系统随 Workspace/Git 分支绑定。当前分支实例可以在验证所有权和 Trust 后执行受限生命周期动作；其他分支只展示只读快照。
+- 中间件类型由 Project System Registry 声明，不写死为 MySQL 或 Redis。中间件可登记有序初始化脚本，包括工作流生成的默认脚本和用户添加脚本。添加时既可选择本地文本文件，也可直接填写文件名和脚本文本；导入后仍可编辑，列表中的现有脚本也都允许再次打开修改。正式实现必须受控持久化修改、重算 checksum，并生成不可变事件和运行凭证。
+- 用户未指定本地 Project System 的启动方式时默认采用 Docker。P08 必须展示启动方式及来源，并允许只读查看 Registry 已登记的项目内 `Dockerfile`、Compose 等 Docker 启动文件及其 checksum；未实现节点不得生成虚假文件或提供启动操作。
+- `P09` 以易读方式展示当前协议、操作、触发条件、正常/业务异常/系统异常场景、模拟报文结果和来源协议文件。AI 后续通过受控脚本同步和管理定义，P09 保留人工查看、确认和排错入口。
+
+## 4. 正式原型与实现现状
+
+正式实现绑定的原型基线已晋级为 `wm-prototype-r33`，checksum `f98e7595`，包含 19 个 Page、126 个已分配 Scene、113 个活动 Scene、13 个永久退役 Scene，以及 1 个 Global Surface。原型使用 React、Vite、shadcn 风格组件和 Lucide，并在桌面尺寸上反复验证。
+
+已在原型中确认的重点包括：
+
+- P02 分离项目上下文入口、设计流程和开发流程；节点工作列表具有列头、稳定列宽和事实页跳转。
+- P07 与工作流管理器自身原型分离，只管理业务项目 Prototype。
+- P08 分支上下文、架构/列表 Tab、未实现拓扑节点、动态中间件和初始化脚本管理。
+- P08 在用户未指定时使用 Docker 默认启动方式，并按系统展示 Registry 登记的 Dockerfile/Compose 启动文件、来源、checksum 和只读内容预览。
+- P08 初始化脚本支持导入本地文本文件、导入后继续编辑、直接新建文本，以及重新编辑列表中的系统生成和用户脚本；修改后明确显示“已修改”和“待重新计算”。
+- P09 易读协议场景列表和协议文件入口。
+- P13 多轮页面审核、文字和截图修改要求、Scene 覆盖凭证、废弃未执行要求、已执行锁定状态，以及登记 Source Inspection Snapshot 的只读主实现/状态分支/验收映射。
+- P15 可点击的业务页面路由关系图。
+- P19 需求到通用相关工作项的双向下钻和 AI 建议状态。
+
+原型源码已冻结为 `wm-prototype-r33@f98e7595`；P08 脚本新增、导入、导入后编辑、既有脚本修改，以及 r33 的 P14 → P13 源码审查上下文和两个桌面视口已验证通过。维护者于 2026-08-21 确认 UX-VS/UX-UI 审核通过，本次 Prototype-to-Frontend 晋级已同步正式 Manager 的公开基线和 Candidate Assurance 断言。19 个 Page 已进入 React 正式实现；原型若再次修改，必须先形成新 Revision、完成用户审核，再继续对应前端修改。
+
+当前正式浏览器测试遍历全部 19 个 Page，验证 P12 筛选、P13 Scene/Ctrl+V/保存、P14/P15 深链、P14 -> P13 Source Inspection Snapshot、P08 双 Tab/计划节点、P02 列头以及 `1280x720`、`1440x900` 无横向溢出或关键面板重叠；应用控制台无 error/warn。Manager 定向套件 97/97 通过，最终 `index.html` 引用的哈希资源已登记到 Git 索引。
+
+### 4.1 `0.4.0` 候选验证
+
+- 当前 P0/P1/P2 候选包的精确路径、SHA-256、文件数和生命周期报告由维护仓库的 `audit/WORKFLOW-MANAGER-P0-P1-P2-CLOSURE.md` 固定登记。审计记录不在 npm 包范围内，因此不会导致候选包自引用；实际 tarball 和展开验证工作区仍保留在 `.tmp/`。
+- 隔离新安装的 Doctor 除可选 CodeGraph 提示外全部通过；安装后 Manager 的主页、健康检查、`workflow-manager.v1` Schema、19 个 Page、七节点投影、25 个可发现受控动作和 r33 Prototype 投影均已实测。
+- 隔离 `0.3.0` 项目的升级、迁移 dry-run、正式升级及回滚已实测。升级 Receipt 为 `UPGRADE-20260812T221812525Z-cde0bf7d`；回滚恢复 `0.3.0`、全部 7 个 Viewer 文件和升级前两个 Git 工作树状态，移除 Manager，并把 Receipt 标记为 `rolled_back`。升级前 Viewer 摘要为 `5cfb8de36f36ccf8149e6f8047e85e48b573a52ef28e67adf35d675497148369`。
+- 候选包已对 `E:\work\ai\codex\tushare` 执行 `doctor`、`upgrade --dry-run` 和 `migrate --dry-run`，没有执行正式 apply。Doctor 识别出该旧安装已有的受管 Skill/运行时完整性漂移；升级计划没有受管资产冲突、不写代码仓库，并计划新增 Manager、替换 8 处受管资产、移除 Viewer。每个 dry-run 前后的工作流 Git 状态摘要一致。维护者于 2026-08-21 明确取消 `tushare` 正式升级/迁移；该项目保持只读，不得再次尝试 apply 或 force。
+- `tushare` 当前不能直接迁移：一个旧 Prototype 来源文件与清单 checksum 不一致，183 个历史任务中有 24 个任务家族需要人工判断语义分组。迁移正确返回 `can_apply=false` 且没有修改业务状态；不得把该结果改写成迁移已就绪，也不得使用 force 绕过人工决策。
+
+### 4.2 v2 Prototype catalog Candidate Assurance
+
+- 新安装交付把 v2 Prototype Revision 的运行时、Manager、Agent Interface、Experience Skill 和全部必需 catalog 模板列为包表面。`doctor` 在包表面缺失时立即失败，不再继续计算会因缺失运行时而崩溃的受管资产摘要。
+- 新的生产路径只接受 `prototype-revision-catalog.v2`。Experience Skill、Project Template、安装后的 Manager 与 Candidate Assurance 都从同一 Revision/checksum 读取事实；缺少任一必需 catalog 的旧 Revision 被 CLI、HTTP 和 UI 确定性拒绝。`prototype-set.yaml` 及 member 文件仍保留为只读迁移输入，明确标记 `compatibility_mode: read-only-legacy` 和 `current_flow_output: false`，不得作为新流程输出或兼容回退。
+- `verification/workflow-manager.test.mjs` 的隔离 Candidate Assurance 用当前工作树实际执行 `npm pack`，在 `.tmp/` 的独立 consumer 安装 tarball，并由安装后的 `ai-delivery init` 与 `doctor` 建立项目。它用多 Logical Terminal 的 v2 fixture 证明安装后的 Manager CLI、HTTP 和 P07/P11-P17 浏览器 UI 读取同一 Prototype Revision 身份和 checksum：每个 Web UI 请求和返回都显式为 `TERM-WEB`，P12 的 `TERM-ADMIN` 路由实际显示 Admin 目标而不回退到 Web。Component Candidate 通过 P11 提交 `candidate -> under-review`、已安装 CLI 提交 `under-review -> registered`、HTTP 提交 `registered -> modified`；每次 apply 均产生 Receipt/Event，CLI 与 HTTP 均重放同一幂等键。初始 CLI/HTTP 计划仍返回相同 plan/successor；删除 v2 `components` catalog 后，三种入口返回相同受控拒绝。测试覆盖 `1280x720` 与 `1440x900` 桌面视口，且有效 Revision 路径没有浏览器 console error/warn。
+- 可重建证据和边界记录在 `audit/WORKFLOW-MANAGER-V2-CANDIDATE-ASSURANCE.md`。它不声明新的 npm 发布或替代 `audit/WORKFLOW-MANAGER-P0-P1-P2-CLOSURE.md` 的历史候选身份；生成的 tarball、consumer、缓存和浏览器临时文件都留在被忽略的 `.tmp/` 并在测试结束后删除。
+
+## 5. 开放事项
+
+### 2026-08-18 Issue 快照
+
+以下状态已通过 Gitee API 以 `hzr1348`（ID `17347733`）回读确认：
+
+- `IK8BA0` 至 `IK8BA5` 的完成评论已写入并读回，评论编号为 `50884717` 至 `50884722`；每条评论绑定相应页面、应用服务、测试与候选证据。
+- `IK8B9Z` 与 `IK8B9U` 的实现/规格完成评论已读回，编号为 `50884723`、`50884724`。
+- `IK6HCD`、`IK89SN` 与 `IK6HCE` 的替代或完成说明已读回，编号为 `50884726`、`50884727`、`50884729`；前两项分别由 Manager 收敛和 P13 附件能力覆盖，候选验证由 `IK8BA5` 覆盖。
+- Gitee v5 仓库 Issue 路由只声明 `OPTIONS, GET, HEAD`，不提供状态写入方法。因此在用户明确确认后，通过已登录的 Gitee 网页将上述 11 个 Issue 设为“已关闭”，并再次用 API v5 回读。每项均返回 `state: rejected`，这是 Gitee API 对网页“已关闭”状态的表示；关闭时间依次为 23:02:20 至 23:11:32（+08:00）。外部收尾门已满足。
+
+### 已关闭的历史 Issue
+
+- [IK89SN](https://gitee.com/hzr1348/work-flow/issues/IK89SN)：P13 已实现 `Ctrl+V` 粘贴图片、持久化、checksum 绑定和 AI 可读附件接口。
+- [IK6HCD](https://gitee.com/hzr1348/work-flow/issues/IK6HCD)：由 Workflow Manager 收敛旧 Viewer 的状态投影需求，避免继续建设重复产品。
+- [IK6HCE](https://gitee.com/hzr1348/work-flow/issues/IK6HCE)：`0.4.0` 候选包、隔离升级/迁移/回滚及 tushare dry-run 均已验证；正式 apply 与发布仍属于独立人工 Gate。
+
+### 下一阶段顺序
+
+1. P0/P1/P2 及 Prototype 治理 01–07 已完成；实现提交为 `ae70304`，后续 v2 Candidate Assurance 收尾提交为 `db8abfb`，候选验证与 11 个 Gitee Issue 收尾均已完成。
+2. `tushare` 正式升级/迁移已按维护者指示取消并保持只读；不得把历史 dry-run 改写为 apply 许可。
+3. r33 晋级改变了当前源码候选内容，历史 `0.4.0` r8 候选证据仍不可变且不能复用。npm 发布需在干净且同步的 `main` 上重新生成候选并通过 `release:check`、账号/2FA 与人工发布 Gate。
+
+## 6. 继续工作时必须读取的来源
+
+- 领域语言：`CONTEXT.md`
+- 原型优先：`docs/adr/0001-prototype-first-ui-governance.md`
+- Mock 决策：`docs/adr/0002-microcks-as-default-mock-system.md`
+- Workflow Manager 与 AI 接口：`docs/adr/0003-workflow-manager-governed-control-surface.md`
+- 视觉规范：`docs/adr/0004-operational-carbon-visual-standard.md`
+- 项目原型页面化：`docs/adr/0005-prototype-management-as-routed-pages.md`
+- 当前临时原型说明：`.tmp/workflow-manager-prototype/README.md`

package/lib/artifact-files.mjs

@@ -0,0 +1,47 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { parse as parseYaml } from "./yaml-runtime.mjs";
+
+export function resolveContainedPath(root, relative, label) {
+  if (!relative || path.isAbsolute(relative)) throw new Error(`${label} must be a relative path.`);
+  const normalized = String(relative).replaceAll("\\", "/");
+  if (normalized.split("/").some((part) => part === "..")) {
+    throw new Error(`${label} resolves outside its allowed directory.`);
+  }
+  const resolvedRoot = path.resolve(root);
+  const resolved = path.resolve(resolvedRoot, normalized);
+  const relation = path.relative(resolvedRoot, resolved);
+  if (relation === ".." || relation.startsWith(`..${path.sep}`)) {
+    throw new Error(`${label} resolves outside its allowed directory.`);
+  }
+  if (fs.existsSync(resolvedRoot)) {
+    const realRoot = fs.realpathSync(resolvedRoot);
+    let existing = resolved;
+    while (!fs.existsSync(existing) && existing !== resolvedRoot) existing = path.dirname(existing);
+    const realRelation = path.relative(realRoot, fs.realpathSync(existing));
+    if (realRelation === ".." || realRelation.startsWith(`..${path.sep}`)) {
+      throw new Error(`${label} resolves outside its allowed directory through a symbolic link.`);
+    }
+  }
+  return resolved;
+}
+
+export function readYamlMapping(file, label) {
+  if (!fs.existsSync(file) || !fs.statSync(file).isFile()) throw new Error(`${label} is missing: ${file}`);
+  const value = parseYaml(fs.readFileSync(file, "utf8"));
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} must contain a YAML mapping.`);
+  }
+  return value;
+}
+
+export function requireSha256(value, label) {
+  const checksum = String(value || "");
+  if (!/^[a-f0-9]{64}$/.test(checksum)) throw new Error(`${label} checksum is missing or invalid.`);
+  return checksum;
+}
+
+export function sha256File(file) {
+  return crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex");
+}