ai-delivery-workflow 0.2.2 → 0.4.0

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

@@ -3,12 +3,16 @@
 > 当前双仓目录、初始化规则、状态分层和 Git 边界见 [DUAL-REPOSITORY-WORKSPACE.zh-CN.md](DUAL-REPOSITORY-WORKSPACE.zh-CN.md)。
 
 > 适用目录：工作流发行仓库  
-> 适用包版本：`ai-delivery-workflow@0.2.0`
+> 适用包版本：`ai-delivery-workflow@0.4.0`
 > 使用方法和完整流程：[PROJECT-MANUAL.zh-CN.md](PROJECT-MANUAL.zh-CN.md)  
-> 查看器使用：[VIEWER-USER-GUIDE.zh-CN.md](VIEWER-USER-GUIDE.zh-CN.md)  
-> 查看器维护：[VIEWER-MAINTENANCE.zh-CN.md](VIEWER-MAINTENANCE.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)
+> Workflow Manager 使用：[VIEWER-USER-GUIDE.zh-CN.md](VIEWER-USER-GUIDE.zh-CN.md)
+>
+> Workflow Manager 维护：[VIEWER-MAINTENANCE.zh-CN.md](VIEWER-MAINTENANCE.zh-CN.md)
 > 正式状态使用：[STATE-CLI-USER-GUIDE.zh-CN.md](STATE-CLI-USER-GUIDE.zh-CN.md)  
 > 正式状态维护：[STATE-CLI-MAINTENANCE.zh-CN.md](STATE-CLI-MAINTENANCE.zh-CN.md)  
+> npm 版本与发布：[NPM-RELEASE-MANAGEMENT.zh-CN.md](NPM-RELEASE-MANAGEMENT.zh-CN.md)
 > 审计物料逐文件说明：[../audit/FILE-GUIDE.zh-CN.md](../audit/FILE-GUIDE.zh-CN.md)
 
 ## 1. 阅读说明
@@ -37,7 +41,7 @@
 | `bin/` | 命令行入口。 | 是 |
 | `lib/` | 安装、Hook TOML 合并、项目识别和引导实现。 | 是 |
 | `skills/` | 25 个可安装的项目级 Skills。 | 是 |
-| `docs/` | 完整项目手册、查看器使用/维护指南和本文。 | 是 |
+| `docs/` | 完整项目手册、Workflow Manager 使用/维护指南和本文。 | 是 |
 | `verification/` | 工作流仓库的通用自动化测试、专项验证器和长期测试辅助程序，纳入 Git，不进入 npm 包。 | 否 |
 | `audit/` | TaskLite 全流程审计物料；其中内嵌测试属于候选包、部署副本或历史快照，不随 `init` 安装。 | 否 |
 | `.tmp/` | 全部临时运行物料，整体忽略，可随时删除。 | 否 |
@@ -54,57 +58,94 @@
 | `audit/generate-dual-repo.mjs` | 创建 `.tmp/dual-repo-e2e/` 真实双 Git 工作区，并生成不含 `.git` 的持久审阅样本。 |
 | `audit/DUAL-REPO-FULL-FLOW/` | 双仓全流程持久物料，包含任务分片、共享 checkpoint、双 Tag 记录、发布、重发、Hotfix 和回滚证据。 |
 | `audit/AUTONOMOUS-GUIDANCE/` | 安装后零命令自主规划与引导的脱敏黑盒审计；保存声明清单、原始 Git 对象证明和四个最小远程快照，区分仓库可复算结论与未获平台签名的运行声明。 |
+| `audit/AUTONOMY-COST/` | 首次 Bootstrap 与重复只读恢复的成本基线；记录上下文字节代理并证明持久工作流状态零增长。 |
 
 ### 3.1 `bin/`
 
 | 文件 | 作用 |
 | --- | --- |
-| `bin/ai-delivery.mjs` | npm `ai-delivery` 可执行入口；解析 `init`、`inspect`、`bootstrap`、`doctor`、`state`、`--dry-run`、`--force` 和版本参数，调用 `lib/` 并设置退出码。 |
+| `bin/ai-delivery.mjs` | npm `ai-delivery` 可执行入口；解析安装、检查、CodeGraph、Mock System、Visual Standard、Prototype revision、Workflow Manager、正式状态和自进化命令，调用 `lib/` 并设置退出码。 |
 | `bin/validate-skills.mjs` | `npm run skills:validate` 的维护命令入口；调用 Skill 校验库、输出汇总或逐条错误并设置退出码，不会被 `init` 复制到业务项目。 |
+| `bin/release-check.mjs` | 维护仓库 npm 发布前后预检；以结构化 JSON 核对版本、Git、测试、审计、registry、2FA、Tag 和外部 `npx`。 |
+| `bin/benchmark-autonomy.mjs` | 在系统临时目录测量首次 Bootstrap 与重复只读恢复检查的耗时、上下文字节和持久物料稳定性。 |
 
 ### 3.2 `lib/`
 
 | 文件 | 作用 |
 | --- | --- |
-| `lib/project-installer.mjs` | 实现项目级安装和诊断。复制 25 个 Skills、本地物料查看器及自包含 Bootstrap/状态/Evolution CLI，创建研发、发布和自进化目录，vendoring YAML 但不修改业务依赖；包版本升级时备份并替换受管资产，同版本冲突仅在 `--force` 时替换，降级默认拒绝。 |
+| `lib/project-installer.mjs` | 实现项目级安装和诊断。复制 25 个 Skills、Workflow Manager 及自包含 Bootstrap/状态/Evolution/Mock CLI，创建研发、发布和自进化目录；升级旧安装时以 Receipt-backed `remove` 备份并移除 Viewer。 |
+| `lib/artifact-files.mjs` | Prototype revision、Manager 审核与 frontend guard 共用的 YAML mapping、SHA-256 和目录包含边界；统一拒绝绝对路径、`..` 和符号链接越界。 |
+| `lib/codegraph.mjs` | CodeGraph 可选适配器；从权威工作区配置解析代码仓，提供只读 doctor 检查和显式 setup/sync，不安装全局 CLI 或 MCP。 |
+| `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-migration.mjs` | 兼容迁移编排器；统一规划旧布局、任务 attempt 与 Prototype member/set 迁移，校验 checksum 绑定人工决定，写 schema 3 清单并提供受保护回滚。 |
+| `lib/prototype-migration.mjs` | 旧 Prototype 迁移器；精确区分零/单/多 member，按 terminal、Page、route、file 合并，保留旧字节，并在无冲突时生成唯一 `PROTOTYPE` 的待 `UX-UI` 目标。 |
 | `lib/project-bootstrap.mjs` | 只读扫描仓库并分类五种项目状态；识别代码、技术、Git、正式工作流和 runtime；为新接入项目生成草稿基线、文件清单、上下文索引、接入评估和引导计划；中断项目直接路由 checkpoint。 |
 | `lib/yaml-runtime.mjs` | 为发行包和安装后的项目内 Bootstrap 运行时解析 YAML；优先使用包依赖，项目内回退到状态 CLI 的 vendored YAML。 |
-| `lib/delivery-state.mjs` | 正式状态公共命令实现；管理物料、节点、Gate、候选和发布，提供 revision、锁、原子写、checksum、审计和 `verify`。 |
+| `lib/delivery-state.mjs` | 正式状态公共命令实现；管理物料、节点、Gate、候选、发布和可信历史锚点，提供 revision、锁、原子写、checksum、例行/增量/全历史校验。 |
 | `lib/evolution.mjs` | 项目级自进化公共命令实现；管理反馈、提案、风险、扩展版本、批准、trial、Hook 调度、回退和 promotion bundle。 |
 | `lib/toml-hooks.mjs` | 使用结构化 TOML 解析和合并项目 Hook 配置；保留既有配置，检查显式禁用和事件注册，避免手工字符串拼接破坏 TOML。 |
 | `lib/skill-validator.mjs` | 校验 25 个 Skill 的 `SKILL.md` frontmatter、目录命名、`agents/openai.yaml` 元数据和中文文档覆盖；使用项目 Node.js `yaml` 依赖，不依赖 Python 或 `PyYAML`。 |
+| `lib/prototype-page-review.mjs` | 计算 Page/Review Scene/路由/Visual Standard/共享组件证据摘要，派生 Page Review Status，并创建、校验和继承不可变 Page review receipt。 |
+| `lib/prototype-review-target.mjs` | Manager、Page Receipt 和 frontend guard 共用的精确 Visual Reference / Prototype revision 目标构建器。 |
+| `lib/workflow-manager.mjs` | Workflow Manager 应用服务、19 Page 目录、CLI/HTTP/静态服务入口、版本化资源查询和动作白名单。 |
+| `lib/workflow-manager-facts.mjs` | 需求、任务、测试、交付成果、事件和反向关系的结构化事实投影。 |
+| `lib/workflow-manager-governance.mjs` | Gate 决策、AI 关系建议/人工确认和设置白名单的受控写服务。 |
+| `lib/workflow-manager-prototypes.mjs` | P07/P11-P17 的冻结原型查询、评论/截图、审核批次、Page 决定、执行锁和废弃墓碑。 |
+| `lib/workflow-manager-systems.mjs` | P08 Project System Registry、分支控制、Docker 文件、初始化脚本和生命周期 plan/apply。 |
+| `lib/workflow-manager-mock.mjs` | P09 协议与场景投影，以及 checksummed Mock 同步 plan/apply。 |
+| `manager/src/` | 19 Page 的 React/TypeScript 源码；使用 Operational Carbon、IBM Plex、Lucide 和 shadcn 风格基础组件。 |
+| `lib/workflow-manager-public/` | `npm run manager:build` 生成并随包发布的 Manager 静态资源；只保留 `index.html` 引用的最终哈希文件。 |
 
 ## 4. 文档
 
 | 文件 | 作用 |
 | --- | --- |
 | `docs/PROJECT-MANUAL.zh-CN.md` | 完整中文项目手册：定位、安装、状态识别、全流程、Gate、原型、TDD、Git、发布、checkpoint、规范、审计、维护和故障排查。 |
+| `docs/CLI-PARAMETER-REFERENCE.zh-CN.md` | CLI 安装参数参考：命令、位置参数、默认值、校验、远程组合、重复初始化和强制替换边界。 |
+| `docs/PROTOTYPE-MIGRATION.zh-CN.md` | 旧 member/set 到唯一 Prototype 的升级/迁移顺序、报告字段、零/单/多成员规则、决定文件、字节保留和在 Manager 重新完成 `UX-UI` 的边界。 |
+| `docs/CODEGRAPH-INTEGRATION.zh-CN.md` | CodeGraph 可选集成指南：适配器边界、doctor、setup/sync、telemetry、降级链、缓存和跨环境风险。 |
+| `docs/MOCK-SYSTEM.zh-CN.md` | Microcks Mock System 指南：镜像身份、生命周期、External/Product Backend 边界、catalog、runtime、安全与验证。 |
 | `docs/FILE-REFERENCE.zh-CN.md` | 本文件，说明发行仓库全部有效文件及同构路径。 |
-| `docs/VIEWER-USER-GUIDE.zh-CN.md` | 查看器用户手册：安装、启动、界面、识别规则、安全边界、升级和故障排查。 |
-| `docs/VIEWER-MAINTENANCE.zh-CN.md` | 查看器维护手册：权威源码、架构、API、推导契约、修改入口、验证流程和完成定义。 |
+| `docs/VIEWER-USER-GUIDE.zh-CN.md` | Workflow Manager 用户手册；保留旧文件名以维持已有链接。 |
+| `docs/VIEWER-MAINTENANCE.zh-CN.md` | Workflow Manager 维护手册；说明权威源码、应用服务、安全边界和完整验收。 |
+| `docs/agents/workflow-manager-agent-interface.md` | Workflow Manager Agent Interface；规定契约发现、受控写入、并发、幂等、plan/apply、Receipt/Event、Outbox 和恢复流程。 |
 | `docs/STATE-CLI-USER-GUIDE.zh-CN.md` | 正式状态 CLI 用户手册：命令、revision、Gate、失败恢复和生产使用规则。 |
 | `docs/STATE-CLI-MAINTENANCE.zh-CN.md` | 正式状态 CLI 维护手册：实现边界、自包含安装、验证契约、测试和完成定义。 |
 | `docs/EVOLUTION-USER-GUIDE.zh-CN.md` | 自进化用户手册：反馈、风险、生命周期、Hook、trial、批准、回退和导出。 |
 | `docs/EVOLUTION-MAINTENANCE.zh-CN.md` | 自进化维护手册：权威源码、安装边界、数据模型、安全限制和验证方法。 |
+| `docs/NPM-RELEASE-MANAGEMENT.zh-CN.md` | npm 版本与发布管理规范：SemVer、Git Tag、发布门槛、2FA、失败处理和发布后验证。 |
+| `docs/MAINTENANCE-VERIFICATION.zh-CN.md` | 发布预检、自主恢复成本基准和 Ed25519 可信平台证明协议的维护说明。 |
 
 ## 5. 永久验证源码
 
 | 文件 | 覆盖内容 |
 | --- | --- |
-| `verification/project-installer.test.mjs` | 项目级安装、Bootstrap 自包含入口、包版本升级、保留既有物料、dry-run、冲突备份、可选查看器隔离、Hook 禁用、路径逃逸防护、CLI init/doctor、中文规范合并和规范正文冲突。 |
+| `verification/project-installer.test.mjs` | 项目级安装、Bootstrap 自包含入口、包版本升级、保留既有物料、Viewer Receipt-backed 移除/回滚、dry-run、冲突备份、Hook、路径边界和 CLI init/doctor。 |
+| `verification/workflow-manager.test.mjs` | Manager CLI/HTTP/UI/安装入口一致性、19 Page 浏览器验收、桌面布局和 Viewer/Review Server 发行收敛。 |
+| `verification/workflow-manager-facts.test.mjs` | 需求、任意相关工作项、任务、测试、交付成果和事件事实投影。 |
+| `verification/workflow-manager-governance.test.mjs` | Gate 评论、AI 关系建议/人工决定和设置安全白名单。 |
+| `verification/workflow-manager-prototypes.test.mjs` | Page/Scene 投影、评论、截图、多轮编辑、审核、执行锁和废弃规则。 |
+| `verification/workflow-manager-systems.test.mjs` | P08 Registry、分支、计划节点、Docker、初始化脚本和生命周期控制。 |
+| `verification/workflow-manager-mock.test.mjs` | P09 协议/场景投影和 Mock 同步 plan/apply。 |
+| `verification/codegraph-integration.test.mjs` | 验证 CodeGraph doctor 可选告警、显式 setup/sync、权威代码仓路径、telemetry、CLI 路由、Agent 降级规则和文档边界。 |
 | `verification/project-bootstrap.test.mjs` | 空项目、存量代码、敏感文件排除、中断恢复、依赖就绪任务、部分安装、缺失 bootstrap skill 和 CLI inspect 只读输出。 |
-| `verification/prototype-handoff.test.mjs` | 原型不可变身份、多终端成员、三道体验 Gate、设计系统、产品核对、稳定 ID、UI handoff 及规划/开发体验变更追踪。 |
+| `verification/prototype-handoff.test.mjs` | 原型不可变身份、多终端成员、两道体验 Gate、设计系统、产品核对、稳定 ID、UI handoff 及规划/开发体验变更追踪。 |
 | `verification/documentation.test.mjs` | 手册存在、README 链接、25 个 Skill 名称、主要文件域、YAML 解析、仓库内容边界和 npm `docs` 发布白名单。 |
 | `verification/skill-validation.test.mjs` | 验证当前 25 个 Skill 通过校验、无效 fixture 被拒绝、`skills:validate` 命令在 npm 包内可达且维护文档完整。 |
 | `verification/release-planner.test.mjs` | 连续版本闭包、同版本重发、倒退、断链、stale、缺 Tag 和 Git 血缘。 |
 | `verification/audit-workflow.test.mjs` | 运行审计总验证器，要求历史 V1 与当前契约 V2 均通过、各归档 15 个任务，并检查 checksum 格式和未发布版本数。 |
 | `verification/autonomous-guidance-evidence.test.mjs` | 验证自主引导证据可离线复算，并拒绝不完整清单、错误 commit tree、被篡改的快照/运行日志和符号链接逃逸。 |
-| `verification/workflow-viewer.test.mjs` | 验证查看器目录扫描、状态与关系推导、HTTP UI、`.workflow/` 读取边界和前后端语法。 |
-| `verification/delivery-state.test.mjs` | 验证正式状态 inspect/verify、物料版本、节点流转、Gate、revision 冲突、checksum 和绕过写入检测。 |
+| `verification/release-check.test.mjs` | 验证发布预检的本地通过、结构化失败和 Tag/提交绑定。 |
+| `verification/autonomy-cost-benchmark.test.mjs` | 验证成本基准的迭代参数、上下文代理和重复恢复零持久增长。 |
+| `verification/delivery-state.test.mjs` | 验证正式状态 inspect/verify、working draft 边界、不可变物料 revision、anchor 保留裁剪、节点流转、Gate、revision 冲突、checksum、重建和绕过写入检测。 |
+| `verification/formal-state-performance.test.mjs` | 以 1000 条脱敏合法 delta 验证 inspect、例行 verify 与锚点后增量历史校验的延迟预算，并单独记录全历史耗时。 |
 | `verification/checkpoint-task-state.test.mjs` | 独立验证 checkpoint、任务依赖、恢复顺序、共享发布和版本归档。 |
+| `verification/version-archive-references.test.mjs` | 隔离验证版本归档以 checksum 引用 task summary、attempt receipt、scope、candidate、Gate 和 history anchor。 |
 | `verification/evolution.test.mjs` | 验证反馈脱敏与幂等、证据门槛、风险抬升、checksum 批准、Hook、冲突、trial 晋升与回退。 |
 | `verification/audit/verify-audit.mjs` | 一键检查审计节点、引用、checksum、部署、发布列车、归档和自主引导证据一致性。 |
-| `verification/audit/verify-autonomous-guidance.mjs` | 复算自主引导结果/运行日志、原始 commit/tree、四个 Git blob 路径归属和任务语义，并报告仓库可验证与平台未认证声明。 |
+| `verification/audit/verify-autonomous-guidance.mjs` | 复算自主引导结果/运行日志、Git 证据和任务语义；缺省保留平台未认证声明，也可用外部受信 Ed25519 公钥验证平台签名。 |
+| `verification/audit/verify-autonomy-cost.mjs` | 校验正式成本基线至少包含三次恢复样本，且持久 checksum、文件数、字节数和语义上下文均稳定。 |
 
 ## 6. Skill 通用结构
 
@@ -138,6 +179,7 @@
 | `skills/ai-delivery-orchestrate/references/workflow-model.md` | 主流程图、状态枚举、运行时层次、人工 Gate、流转规则和恢复规则。 |
 | `skills/ai-delivery-orchestrate/references/formal-state-contract.md` | 正式状态唯一写入口、命令、mutation 顺序、revision 和完整性契约。 |
 | `skills/ai-delivery-orchestrate/assets/project-template/AGENTS.md` | 安装到目标项目根 `AGENTS.md` 的受管说明区块。 |
+| `skills/ai-delivery-orchestrate/assets/project-template/gitignore.template` | npm 可稳定携带的根 `.gitignore` 模板资产；安装器把其中的 runtime 忽略规则与代码仓路径合并到目标根 `.gitignore`，doctor 通过 package surface 和 Skill checksum 校验该资产。 |
 | `skills/ai-delivery-orchestrate/assets/project-template/.gitattributes` | 安装到目标工作流仓库的 LF 属性规则，保证正式状态和物料 checksum 跨平台稳定。 |
 | `skills/ai-delivery-orchestrate/assets/project-template/.workflow/delivery/project.yaml` | 初始项目描述和旧身份字段兼容模板，不是生产事实写入口。 |
 | `skills/ai-delivery-orchestrate/assets/project-template/.workflow/delivery/workflow-state.yaml` | schema 2 正式审计模板；分别保存研发与发布 scope、局部 revision、节点、Gate 和尝试次数，并保存累计研发/生产身份。 |
@@ -153,13 +195,10 @@
 | `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/evolution/index.yaml` | 初始自进化索引，schema 1；不伪造反馈、提案或扩展。 |
-| `skills/ai-delivery-orchestrate/assets/project-template/.workflow/tools/viewer/server.mjs` | 零依赖本地查看器服务；扫描 `.workflow/`，计算状态、关系和 checksum，并提供只读 API 与静态资源。 |
-| `skills/ai-delivery-orchestrate/assets/project-template/.workflow/tools/viewer/start.cmd` | Windows CMD 启动脚本，默认启动并打开本地查看器。 |
-| `skills/ai-delivery-orchestrate/assets/project-template/.workflow/tools/viewer/start.ps1` | PowerShell 启动脚本。 |
-| `skills/ai-delivery-orchestrate/assets/project-template/.workflow/tools/viewer/start.sh` | macOS/Linux Shell 启动脚本。 |
-| `skills/ai-delivery-orchestrate/assets/project-template/.workflow/tools/viewer/public/index.html` | 查看器三栏应用壳、筛选控件、物料表和详情检查器。 |
-| `skills/ai-delivery-orchestrate/assets/project-template/.workflow/tools/viewer/public/app.js` | 前端扫描结果状态、筛选、关系跳转、checksum 复制及 Markdown/CSV/JSON/图片预览交互。 |
-| `skills/ai-delivery-orchestrate/assets/project-template/.workflow/tools/viewer/public/styles.css` | 查看器设计令牌、桌面三栏布局、表格、详情区和移动端响应式样式。 |
+| `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 启动入口。 |
+| `skills/ai-delivery-orchestrate/assets/project-template/.workflow/tools/manager/start.ps1` | PowerShell Manager 启动入口。 |
+| `skills/ai-delivery-orchestrate/assets/project-template/.workflow/tools/manager/start.sh` | macOS/Linux Manager 启动入口。 |
 | `skills/ai-delivery-orchestrate/agents/openai.yaml` | orchestrate 的 Codex 元数据。 |
 
 ### 7.3 `ai-delivery-checkpoint-task`
@@ -221,20 +260,45 @@
 
 | 文件 | 作用 |
 | --- | --- |
-| `skills/ai-delivery-design-experience/SKILL.md` | 管理工具选择、可运行低保真原型、视觉系统/UI 框架、正式 UI、三道人工 Gate、调整记录、产品核对和下游交接。 |
+| `skills/ai-delivery-design-experience/SKILL.md` | 管理设计参考选择、HTML Visual Reference、视觉系统/UI 框架与 `UX-VS`，再管理生产兼容原型、正式 UI 与 `UX-UI`，以及调整记录、产品核对和下游交接。 |
+| `skills/ai-delivery-orchestrate/assets/project-template/ref/ui/` | 安装到项目 `ref/ui/` 的受管 Design Reference Library；包含上游索引、74 份 `DESIGN.md`、MIT `LICENSE` 和固定提交归属。 |
+| `assets/experience-template/design-reference-selection.yaml` | 索引优先、评估两到三个参考、主参考/辅助参考、选择理由与输入校验和模板。 |
+| `assets/experience-template/visual-reference.html` | 在 `UX-VS` 前供用户实际操作的 tokens、组件状态、响应式和无障碍 HTML 视觉参考模板。 |
+| `assets/experience-template/visual-reference-manifest.yaml` | Visual Reference 入口、选择凭据、tokens、组件状态和适用视口的校验和清单。 |
+| `lib/visual-standard.mjs` | 顶层 `visual-standard validate` 的只读失败关闭校验器；验证完整 scoped 输入、许可、框架配置、参考校验和及审批有效期。 |
+| `lib/prototype-revision.mjs` | 顶层 `prototype-revision validate` 的只读失败关闭校验器；验证唯一 Prototype revision、bundle、目录外键、稳定身份和路由/UI Mapping 约束。 |
+| `lib/prototype-review-target.mjs` | Workflow Manager 与 frontend guard 共用的精确 Visual Reference / Prototype revision 审查目标构建器。 |
+| `lib/frontend-guard.mjs` | 单文件 Hook 检查与固定 Git diff 独立复核的只读核心。 |
+| `lib/ui-acceptance.mjs` | Candidate Assurance UI Acceptance 的只读 plan/verify 核心；绑定不可变 candidate，并复核冻结 Scenario Pack、Scene/viewport 与完整证据。 |
+| `lib/png-evidence.mjs` | UI Acceptance 的无依赖 PNG 解码与像素复核核心；校验精确 viewport、Prototype/Candidate 像素和透明 Diff mask。 |
+| `lib/stable-value.mjs` | Mock Scenario Pack 与 UI Acceptance 共用的稳定对象比较和摘要函数。 |
 | `references/experience-contract.md` | 体验基线、页面状态、功能覆盖和原型来源确认契约。 |
-| `references/prototype-management-contract.md` | 原型成员、工具、页面、画布、文件、评审、调整和 checksum 的管理契约。 |
-| `assets/experience-template/prototype-set.yaml` | 多成员原型集的稳定 identity 和版本模板。 |
-| `assets/experience-template/prototype-manifest.yaml` | 单个原型成员及源文件身份模板。 |
+| `references/prototype-management-contract.md` | 单一 Prototype、工具、Page、Review Scene、终端、路由、UI Mapping、评审、调整和 checksum 的管理契约。 |
+| `assets/experience-template/prototype.yaml` | 项目唯一逻辑 Prototype、当前隔离源码和当前 Review Shell 的可变指针模板。 |
+| `assets/experience-template/prototype-revision.yaml` | 每次迭代冻结的不可变 Prototype revision 及全部输入 checksum 模板。 |
+| `assets/experience-template/frontend-change-scope.yaml` | revision-bound 非空正式前端根/UI 扩展名、shared component Page 影响集，以及绑定预期 candidate 文件 SHA-256 的 route registry 影响集。 |
+| `assets/experience-template/prototype-terminals.csv` | 同一 Prototype 内按 `terminal_id` 分组的源码入口、构建命令和路由基址。 |
+| `assets/experience-template/prototype-pages.csv` | `P01`、`P01-01` 等稳定 Page 身份。 |
+| `assets/experience-template/prototype-review-scenes.csv` | `RS0001` 等稳定、可直达的 Review Scene 身份。 |
+| `assets/experience-template/mock-scenario-pack-request.yaml` | 一次 Mock Scenario Pack 冻结请求；绑定 Prototype revision、场景映射、受管 UI 导出、人工 candidate checksum 确认与不可变输出路径。 |
+| `assets/experience-template/mock-scenario-mappings.csv` | 每个 Review Scene 到一个确定性 External Dependency 或 Product Backend Mock scenario 的唯一映射及数据分类/脱敏状态。 |
+| `assets/experience-template/mock-admin-export.yaml` | Microcks 受管 UI 安全导出索引；`artifacts` 绑定 `mock-admin-exports/` 下每个实际 OpenAPI/AsyncAPI 导出物，生产流量、生产凭据和未脱敏个人数据必须全部为 false。 |
+| `assets/experience-template/prototype-review-units.csv` | Page、Review Scene 与共享组件到 checksummed 原型源码的 Review Unit 本体。 |
+| `assets/experience-template/prototype-review-unit-pages.csv` | 每行一个 Review Unit 到受影响 Page 的规范化多对多关系，禁止在单字段编码多个 Page ID。 |
+| `assets/experience-template/prototype-trigger-conditions.csv` | Review Scene 触发条件的唯一规范化目录。 |
+| `assets/experience-template/prototype-routes.csv` | 原型路由与真实生产 Page 路由的唯一目录。 |
+| `assets/experience-template/ui-mapping.csv` | Page/Review Scene、原型路由、生产路由、前端源码和验收 ID 的双向映射。 |
+| `assets/experience-template/prototype-set.yaml` | 旧多成员原型集的历史只读兼容输入；当前流程不生成。 |
+| `assets/experience-template/prototype-manifest.yaml` | 旧原型成员 manifest 的历史只读兼容输入；当前流程不生成。 |
 | `assets/experience-template/prototype-tool-candidates.csv` | 可用原型工具候选及适配分析。 |
-| `assets/experience-template/prototype-tool-selection.yaml` | 每个成员的人工工具选择凭据。 |
-| `assets/experience-template/page-catalog.csv` | `P01`、`P01-01` 等稳定页面目录。 |
+| `assets/experience-template/prototype-tool-selection.yaml` | 项目唯一 Prototype 的人工工具选择凭据。 |
+| `assets/experience-template/page-catalog.csv` | 旧成员 Page 目录的历史只读兼容输入；当前流程使用 `prototype-pages.csv`。 |
 | `assets/experience-template/screen-states.csv` | 页面状态、触发、行为、恢复和无障碍要求。 |
 | `assets/experience-template/feature-screen-coverage.csv` | 功能、终端、流程、页面和状态覆盖。 |
-| `assets/experience-template/canvas-catalog.csv` | 原型画布目录和页面族边界。 |
-| `assets/experience-template/canvas-pages.csv` | 画布与页面显式关系。 |
-| `assets/experience-template/prototype-files.csv` | 原型源文件和修订目录。 |
-| `assets/experience-template/prototype-file-terminals.csv` | 原型文件与目标终端关系。 |
+| `assets/experience-template/canvas-catalog.csv` | 旧成员画布目录的历史只读兼容输入。 |
+| `assets/experience-template/canvas-pages.csv` | 旧画布与 Page 关系的历史只读兼容输入。 |
+| `assets/experience-template/prototype-files.csv` | 旧成员源文件目录的历史只读兼容输入。 |
+| `assets/experience-template/prototype-file-terminals.csv` | 旧成员文件/终端关系的历史只读兼容输入。 |
 | `assets/experience-template/prototype-traceability.csv` | 产品、终端、页面、状态、元素与源修订追踪。 |
 | `assets/experience-template/prototype-review-decision.yaml` | 视觉或交互原型必须执行分阶段人工评审的决定记录。 |
 | `assets/experience-template/prototype-review-sessions.csv` | 人工评审轮次和批准状态。 |
@@ -242,7 +306,6 @@
 | `assets/experience-template/prototype-adjustment-log.csv` | 评论对应的实际原型调整记录。 |
 | `assets/experience-template/prototype-impact-assessment.yaml` | 需求变化和架构影响评估。 |
 | `assets/experience-template/prototype-confirmation.yaml` | 原型来源、完整性和冻结确认。 |
-| `assets/experience-template/low-fidelity-confirmation.yaml` | 可运行低保真原型的 `UX-LF` 人工确认。 |
 | `assets/experience-template/visual-direction.yaml` | 整体色调、字体、密度、图标、响应式和无障碍方向。 |
 | `assets/experience-template/design-tokens.json` | 颜色、字体、间距、尺寸、边框、圆角、阴影、层级、断点和动效 Token。 |
 | `assets/experience-template/ui-framework-candidates.csv` | 与产品性质、架构和可用能力匹配的 UI 框架候选。 |
@@ -251,13 +314,14 @@
 | `assets/experience-template/visual-system-confirmation.yaml` | 视觉系统和框架选型的 `UX-VS` 人工确认。 |
 | `assets/experience-template/interaction-contract.csv` | 触发、前置状态、状态变化、反馈、错误和键盘行为的结构化契约。 |
 | `assets/experience-template/page-component-map.csv` | 页面元素、正式 UI 组件和框架组件的稳定映射。 |
-| `assets/experience-template/formal-ui-confirmation.yaml` | 可运行正式 UI 的 `UX-UI` 人工确认。 |
+| `assets/experience-template/formal-ui-confirmation.yaml` | 绑定精确 Prototype revision、Page/Scene/Review Unit/Visual Standard checksum 与 Page receipt 集合的 `UX-UI` 人工确认。 |
+| `.workflow/delivery/reviews/prototype-pages/<revision-id>/PAGE-REVIEW-<uuid>.yaml` | 安装项目中由 Workflow Manager 受控动作追加的不可变 Page 审核凭据；凭据绑定精确 Revision、Page checksum 和人工决定。 |
 | `assets/experience-template/experience-change-set.csv` | 以稳定 ID 表达新增、修改、停用、取代和未变体验内容。 |
 | `assets/experience-template/experience-change-domains.csv` | 一项体验变更对应布局、交互、视觉、响应式等多个领域的关系表。 |
 | `assets/experience-template/requirement-change-set.csv` | 原型调整中识别出的需求变化及产品处置状态。 |
 | `assets/experience-template/prototype-product-coverage.csv` | 产品需求与原型行为的双向覆盖矩阵。 |
 | `assets/experience-template/product-prototype-reconciliation.yaml` | 全部候选原型完成后的产品统一核对结论。 |
-| `assets/experience-template/experience-baseline.yaml` | 三道 Gate 和产品核对通过后冻结的体验基线清单。 |
+| `assets/experience-template/experience-baseline.yaml` | 两道体验 Gate 和产品核对通过后冻结的体验基线清单。 |
 | `assets/experience-template/ui-handoff.yaml` | 下游唯一就绪入口，绑定所有 Gate、契约、变更和 checksum。 |
 
 本节中省略前缀的 `references/` 和 `assets/` 均位于 `skills/ai-delivery-design-experience/` 下。
@@ -282,7 +346,7 @@
 | `assets/planning-template/vertical-slices.csv` | 可独立验证垂直切片模板。 |
 | `assets/planning-template/slice-sources.csv` | 切片到功能、故事、验收标准的来源追踪。 |
 | `assets/planning-template/slice-dependencies.csv` | 切片先后依赖。 |
-| `assets/planning-template/slice-prototype-traceability.csv` | 切片与原型成员、页面、状态和 checksum 追踪。 |
+| `assets/planning-template/slice-prototype-traceability.csv` | 切片与精确 Prototype revision、Page、Review Scene 和 checksum 追踪。 |
 | `assets/planning-template/slice-experience-change-traceability.csv` | 切片与可执行体验变更、影响和测试范围的追踪。 |
 
 ### 9.3 `ai-delivery-design-tests`
@@ -292,7 +356,7 @@
 | `skills/ai-delivery-design-tests/SKILL.md` | 开发前设计风险测试策略、原型可测性和公开测试契约。 |
 | `references/test-design-contract.md` | 测试策略、测试层次、数据、环境、质量门禁和开发公开接缝契约。 |
 | `assets/test-design-template/iteration-test-contract.md` | 开发与独立测试共同使用的公开行为契约。 |
-| `assets/test-design-template/prototype-test-scope.csv` | 每个相关原型成员的测试范围和显式决定。 |
+| `assets/test-design-template/prototype-test-scope.csv` | 精确 Prototype revision 内各终端/切片的测试范围和显式决定。 |
 | `assets/test-design-template/prototype-test-validation.yaml` | 测试设计对 UI handoff、产品核对、体验变更及原型 identity/checksum 的接收凭据。 |
 
 本节 9.1 至 9.3 中省略前缀的文件均位于对应 skill 目录。
@@ -305,8 +369,9 @@
 | --- | --- |
 | `skills/ai-delivery-develop-iteration/SKILL.md` | 为一个切片动态推导技术工作包和能力角色，协调 TDD、独立审查和候选组装。 |
 | `references/development-contract.md` | 工作包、动态角色、分支、TDD、审查、追踪和候选冻结契约。 |
-| `assets/development-template/task-prototype-traceability.csv` | UI 任务到原型成员、页面、画布、文件、元素和 checksum 的追踪模板。 |
+| `assets/development-template/task-prototype-traceability.csv` | UI 任务到精确 Prototype revision、Page、Review Scene、元素和 checksum 的追踪模板。 |
 | `assets/development-template/task-experience-change-traceability.csv` | 开发任务到体验变更及 create/update/remove/migrate/no-code 动作的追踪。 |
+| `assets/development-template/candidate-manifest.yaml` | 不可变候选代码身份，以及 UI handoff、产品对账、Prototype revision、UI Mapping、Mock Scenario Pack 和任务追踪 checksum 的绑定清单。 |
 
 ### 10.2 `ai-delivery-execute-work-package`
 
@@ -330,6 +395,8 @@
 | --- | --- |
 | `skills/ai-delivery-verify-candidate/SKILL.md` | 在可复现环境中独立验证不可变候选并给出发布建议。 |
 | `references/candidate-verification-contract.md` | 风险测试拆分、覆盖、环境、原型一致性、缺陷和候选决策契约。 |
+| `assets/verification-template/ui-acceptance-request.yaml` | Candidate Assurance active attempt、immutable candidate、Prototype/Scenario Pack、测试策略与 pinned Playwright 环境绑定模板。 |
+| `assets/verification-template/ui-acceptance-results.yaml` | 完整 Scene/viewport UI 验收、Mock 权限、真实后端与 checksummed 执行证据模板。 |
 | `assets/verification-template/test-work-packages.csv` | 动态风险测试工作包模板。 |
 | `assets/verification-template/defects.csv` | 缺陷、根源节点、证据、状态和复验范围模板。 |
 | `assets/verification-template/defect-artifacts.csv` | 缺陷与受影响正式产物的关系模板。 |
@@ -451,12 +518,15 @@
 | `.agents/skills/ai-delivery-*/` | 从包内 `skills/` 复制的项目级能力。 |
 | `.codex/config.toml` | 合并后的项目 Hook 配置。 |
 | `.workflow/config/workspace.yaml` | 工作流仓库与唯一代码仓库的路径、身份、远程和分支契约。 |
-| `.workflow/config/install-manifest.json` | 安装版本、范围、skill 根、`.workflow` 根、Bootstrap、状态、Evolution 与查看器入口、固定 skill 清单，以及受管运行时 SHA-256。 |
+| `.workflow/config/install-manifest.json` | schema 6 安装所有权清单：版本、范围、入口、固定 skill 清单、精确受管资产 SHA-256，以及保留用户内容的合并配置表面。 |
 | `.workflow/tools/hooks/hook-event.mjs` | 本地 Hook 执行文件。 |
 | `.workflow/tools/state/` | 正式状态 CLI、统一状态模块及自包含 YAML 运行时。 |
+| `.workflow/tools/frontend-guard/` | 随安装包管理的自包含原型先行前端守卫；Hook 使用 `check-file`，CI/正式验证使用 `verify-diff`。 |
+| `.workflow/tools/ui-acceptance/` | 随安装包管理的自包含 Candidate Assurance UI Acceptance runtime；提供只读 `plan` 与 `verify`。 |
 | `.workflow/tools/bootstrap/` | 核心自主入口；只读识别项目状态、生成首次引导上下文并输出机器可读路由。 |
-| `.workflow/tools/viewer/` | 随 `init` 安装的只读工作流物料查看系统及启动脚本。 |
+| `.workflow/tools/manager/` | 随 `init` 安装的正式 Workflow Manager runtime、React 静态资源、`AGENT-INTERFACE.md` 与跨平台启动脚本；CLI、HTTP 和界面共享同一应用服务。安装后可执行 `manager.mjs inspect/list/show/export/action`，或使用 `start.cmd`、`start.ps1`、`.workflow/tools/manager/start.sh` 启动；维护仓库入口是 `ai-delivery manager inspect`、`manager list/show/export/action` 和 `manager serve`。 |
 | `.workflow/delivery/runtime/backups/<timestamp>/` | `--force` 替换前备份。 |
+| `.workflow/delivery/runtime/upgrades/<upgrade-id>/receipt.json` | 独立升级收据；记录升级前后 digest、备份路径和正式事件树指纹，供受保护回滚使用。 |
 | `AGENTS.md` 中的 `ai-delivery` 受管区块 | 告诉后续 AI 如何启动、恢复和使用项目流程。 |
 | `.gitattributes` 中的工作流 LF 规则 | 保持 `.workflow/`、项目级 Skills 和根控制文件的字节级 checksum 在 Windows、macOS、Linux 间一致。 |
 | `.workflow/delivery/bootstrap/runs/<id>/` | 项目识别产生的草稿仓库上下文。 |
@@ -466,6 +536,17 @@
 | `.workflow/delivery/runtime/heartbeats/*.json` | 最近 Hook 活动心跳。 |
 | `.workflow/delivery/runtime/resumes/*.md` | 任务恢复摘要。 |
 | `.workflow/control/archives/versions/<version-id>/` | Git 可携带的权威版本任务归档；归档后活动 task/checkpoint 分片从普通恢复范围移除。 |
+| `.workflow/control/migrations/<migration-id>/migration-manifest.json` | schema 3 兼容迁移清单；记录人工/自动任务分组、Prototype 迁移报告、冲突、已验证锚点、源/目标 checksum、真实复制/替换动作和零业务状态推断声明。 |
+| `.workflow/control/migrations/<migration-id>/backups/` | 当前布局平铺任务显式化 attempts 前的逐字节备份；只供受保护迁移回滚使用。 |
+| `.workflow/experience/<iteration-id>/prototype.yaml` | Prototype 迁移生成的唯一当前描述；初始状态 `migration-pending-ux-ui`，在完整新 revision 冻结前 `current_revision_ref` 为 `null`。 |
+| `.workflow/experience/<iteration-id>/prototype-migration.yaml` | 旧 set/member、terminal/Page/route/file 合并、人工决定、保留历史和新 `UX-UI` 政策的不可变迁移记录。 |
+| `.workflow/experience/<iteration-id>/prototype/source/<member-id>/` | 从每个校验通过的旧 member source 逐字节复制的隔离迁移输入；旧 source 本身不修改。 |
+| `.workflow/experience/<iteration-id>/prototype/review-shell/index.html` | 迁移时生成的旧成员导航占位 Shell；不是完整冻结 revision，不能据此批准 `UX-UI`。 |
+| `.workflow/control/repairs/transactions/<sequence>-<repair-id>.json` | 独立前向修复事务链；归档失效记录引用原归档 checksum、人工 actor、原因、RCA 与恢复 evidence，原归档字节不变。 |
+| `.workflow/control/snapshots/formal-state/<anchor-id>/` | 正式状态可信锚点；保存两个当前视图的原字节副本、stream revision、视图与记录链 checksum、JSONL 边界和自校验锚点。 |
+| `.workflow/control/archives/history/artifact-registry/<anchor-id>.json.gz` | `ai-delivery compact` 生成的 legacy full-snapshot 压缩包；内含原 shard 字节、逐项 SHA-256、原历史根摘要、revision 覆盖范围和锚定 registry checksum。 |
+| `.workflow/control/archives/history/artifact-registry/<anchor-id>.yaml` | 压缩包 manifest；绑定 archive checksum、可信 anchor、覆盖范围、原/压缩字节数和自校验 checksum。 |
+| `.workflow/control/retention/artifact-registry/<anchor-id>.yaml` | 显式 `artifact prune --apply` 的不可变保留 receipt；绑定可信 anchor、裁剪 revision、删除数量和聚合 checksum。 |
 | `.workflow/delivery/runtime/archive/` | 可丢弃的本地详细归档副本和索引，不作为跨 clone 的权威来源。 |
 | `.workflow/product/` | 可跨迭代复用的产品基线。 |
 | `.workflow/architecture/` | 可跨迭代复用的架构基线。 |

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

@@ -0,0 +1,51 @@
+# 维护仓库验证工具
+
+本文说明维护与发行仓库新增的发布预检、自主恢复成本基准和可信平台证明协议。这些命令不随 `init` 写入业务项目，也不改变业务项目的研发或发布状态。
+
+## 1. npm 发布预检
+
+```powershell
+npm run release:check -- prepare --version 0.4.0
+npm run release:check -- verify --version 0.4.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` 并返回非零退出码。
+
+`verify` 用于 npm 发布后、推送 Git Tag 前，核对精确版本、`latest`、`bin`、可选 `gitHead`、本地 Tag 与发行提交，并在系统临时目录从维护仓库之外运行 `npx <package>@<version> --version`。
+
+`--scope local` 只用于离线开发和自动化回归测试，执行本地 Git、测试、审计和打包检查，不等价于正式发布门槛。`--root` 可指定其他通用 npm 包根目录；默认是当前目录。JSON 只保留检查结论和脱敏错误摘要，不回显 token、OTP 或 npm profile 正文。
+
+## 2. 自主恢复成本基准
+
+```powershell
+npm run benchmark:autonomy -- --iterations 5
+node bin/benchmark-autonomy.mjs --iterations 5 --output audit/AUTONOMY-COST/baseline.json
+```
+
+命令在系统临时目录创建隔离业务项目，执行一次真实安装和 Bootstrap，通过正式任务 CLI 建立等待用户输入的 checkpoint，然后重复调用 `bootstrapProject` 模拟用户只说“继续”时的恢复路由。报告记录首次 Bootstrap 和每次恢复检查耗时、路由 JSON 的 UTF-8 字节数与 SHA-256、排除 `detected_at` 后的语义上下文 SHA-256，以及重复检查前后 `.workflow/` 的文件数、总字节和目录摘要。
+
+通过条件是重复检查不新增或修改任何持久物料，并且语义上下文稳定。Codex 平台没有向仓库命令暴露每次 Agent 的 LLM token，因此报告明确写入 `llm_token_usage: unavailable`，使用上下文字节数作为仓库可观测代理。耗时受机器、磁盘和安全软件影响，只作为观测值，不作为发行阈值。
+
+## 3. 可信平台证明
+
+自主引导审计验证器支持两种状态：
+
+- `not-provided`：现有历史审计的默认状态，平台行为声明继续标记为 `unattested`；
+- `signed`：由可信运行平台使用 Ed25519 私钥签名，验证时从审计包之外显式传入受信公钥。
+
+```powershell
+node verification/audit/verify-autonomous-guidance.mjs `
+  --audit-root <审计目录> `
+  --trusted-key <可信平台Ed25519公钥PEM>
+```
+
+签名载荷 schema 1 绑定 `audit_id`、被认证的声明 ID，以及每轮运行的 `run_id`、输入 SHA-256、`fork_mode` 和输出 SHA-256。证明文件、描述符 checksum、Ed25519 公钥指纹和签名必须同时一致。公钥必须由审计使用方通过独立可信渠道提供；把公钥或自签名证明随审计包一起提交不能建立信任。
+
+缺少信任根、错误密钥、载荷篡改、证明 checksum 变化、声明清单不完整或运行记录不一致都会使验证失败。维护仓库不会生成或保存平台私钥，也不会把操作员记录自动升级成平台认证事实。
+
+## 4. 维护边界
+
+- 通用命令位于 `bin/`，自动化测试位于 `verification/`。
+- 成本审计的正式基线位于 `audit/AUTONOMY-COST/`；临时项目始终位于系统临时目录或 `.tmp/`。
+- 发布检查、基准和证明验证均不得在本维护仓库执行面向业务项目的 `init`。
+- 所有工具失败后先修复输入或环境，不得手工篡改 JSON 结论绕过门槛。

package/docs/MOCK-SYSTEM.zh-CN.md

@@ -0,0 +1,141 @@
+# Microcks Mock System 使用指南
+
+项目 Mock System 是独立于正式应用的本机协议与报文模拟系统。它使用 Microcks 管理 UI 查看导入的服务、operation/channel、example/scenario 和调用流量；Prototype 与 UI Acceptance 只消费已登记、可重建的 mock 定义，不把内联 fixture 或正式后端当作 Mock System。
+
+## 1. 固定运行身份
+
+发行包固定使用：
+
+```text
+quay.io/microcks/microcks-uber:1.15.0@sha256:97e74ff545d020f9f20141a0edc4ec1a99f32b7bfeacc81aadd47d8ffc642ffe
+```
+
+`setup` 先探测 Docker，再探测 Podman；两者都不可用或 daemon 未启动时明确阻塞。工作流不会自动安装或启动 Docker/Podman，也不会改写用户的全局容器配置。镜像同时固定版本和多架构 manifest digest。
+
+容器使用 Microcks Uber 的 in-memory 数据库，以 `--rm` 运行且不挂载持久卷。管理 UI 和 API 只发布到 `http://127.0.0.1:8585`，不会绑定 `0.0.0.0`。数据库、日志、导入状态、流量和端口占用都是本机可丢弃 runtime；停止或重建后，从仓库定义重新 sync。
+
+## 2. 生命周期
+
+在业务工作区执行：
+
+```bash
+ai-delivery mock setup <workspace>
+ai-delivery mock start <workspace>
+ai-delivery mock status <workspace>
+ai-delivery mock sync <workspace>
+ai-delivery mock stop <workspace>
+ai-delivery mock freeze <workspace> --experience .workflow/experience \
+  --scenario-pack mock-scenario-pack-request.yaml --dry-run
+```
+
+- `mock setup` 拉取固定 digest 镜像，并在缺失时分别创建 tracked External Dependency Mock、Product Backend Mock catalog 与定义目录。
+- `mock start` 启动 loopback-only 易失容器，等待 `GET /api/health` 成功后才返回管理地址；健康检查失败时主动停止本次容器，清理失败也会明确报错。
+- `mock status` 只读组合容器状态与健康状态。
+- `mock sync` 分别校验两类 catalog、合同路径、operation/channel、具名 scenario 和 dispatcher 输入，通过 Microcks 官方 `POST /api/artifact/upload?mainArtifact=true` multipart 接口导入每个唯一合同。
+- `mock freeze` 先以 `--dry-run` 校验 Prototype revision、全部 Review Scene 映射、受管 UI 导出、数据安全和合同，并返回 candidate checksum；人工把该 checksum 写入确认后，移除 `--dry-run` 冻结不可变 Mock Scenario Pack。
+- `mock stop` 停止稳定命名的容器；`--rm` 清理容器运行态，tracked 定义保持不变。
+
+`setup`、`start`、`stop`、`sync` 和 `freeze` 都支持 `--dry-run`。dry-run 可以探测依赖并完整校验输入，但不得 pull、启动/停止容器、访问 Microcks API 或写项目文件。`status` 本身始终只读。
+
+项目内也可执行自包含入口：
+
+```bash
+node .workflow/tools/mock/mock.mjs <setup|start|stop|status|sync> . [--dry-run]
+node .workflow/tools/mock/mock.mjs freeze . --experience .workflow/experience \
+  --scenario-pack mock-scenario-pack-request.yaml [--dry-run]
+```
+
+## 3. 定义与运行态边界
+
+仓库权威输入位于：
+
+```text
+.workflow/mock-system/
+  external-dependencies.yaml
+  product-backends.yaml
+  definitions/external/
+  definitions/product-backend/
+```
+
+`.workflow/mock-system/external-dependencies.yaml` 使用 schema 1。每个 External Dependency Mock 必须包含：
+
+```yaml
+mock_id: EXT-PAYMENTS
+mock_kind: external-dependency
+owner: payments-vendor
+contract_ref: .workflow/mock-system/definitions/external/payments-openapi.yaml
+contract_approval_ref: CONTRACT-APPROVAL-PAYMENTS-0001
+replacement_condition: approved vendor contract is retired
+protocol: http
+operation_or_channel: GET /payments/{paymentId}
+scenario_id: payment-declined
+```
+
+Product Backend Mock 使用 `product-backends.yaml`、`mock_kind: product-backend` 和 `definitions/product-backend/`。每个条目都必须显式记录 mock kind、owner、批准合同凭据 `contract_approval_ref`、`replacement_condition`、协议、operation/channel 与稳定 scenario；两类 catalog 的 `mock_id` 不得冲突。
+
+`contract_ref` 必须位于对应 kind 的定义目录内；绝对路径、`..`、反斜杠和符号链接越界全部拒绝。sync 对相同合同只上传一次，但保留每个 mock/scenario 身份供 Prototype 映射。
+
+schema 1 当前只接受能在零网络 dry-run 中完成身份校验的 OpenAPI 和 AsyncAPI 定义：
+
+- OpenAPI 使用 `METHOD /path` 作为 `operation_or_channel`；`scenario_id` 必须是该 operation 下 response `examples` 的具名键，或无 content response 的 `x-microcks-refs` 身份。自动 `URI_PARTS`、`URI_PARAMS`、`URI_ELEMENTS` 以及显式 `QUERY_HEADER` dispatcher 的每个 path/query/header 输入都必须具有同名 parameter example。无 dispatcher 或使用 `RANDOM`/`SEQUENCE` 时只允许唯一响应场景；`SCRIPT`、`GROOVY`、`JSON_BODY`、`PROXY` 等无法在零网络 dry-run 中静态证明的样式明确阻塞。
+- AsyncAPI 2.x 可使用 channel，或 `PUBLISH|SUBSCRIBE channel`；AsyncAPI 3.x 可使用 channel key/address、operation key，或 `ACTION operationKey`。`scenario_id` 必须来自所选 operation message 的 `examples[].name` 或 Microcks 单键 example 身份。
+- 其他合同格式不会绕过校验，而是明确阻塞。扩展格式前必须先提供同等的本地 operation/scenario 身份校验和日常测试。
+
+`mock sync --dry-run` 在访问 Microcks API 前完成以上校验。只有该命令成功返回的 `mock_id`、`operation_or_channel` 和 `scenario_id` 组合才可进入 Prototype 映射。
+
+External Dependency Mock 只代表产品边界之外的第三方协议。尚未完成但归本产品所有的公共后端合同属于 Product Backend Mock，必须使用独立 catalog 和目录；不得把它登记为 external，也不得用 mock 成功证明真实产品后端正确。
+
+本机可丢弃 runtime 统一位于已忽略的 `.workflow/delivery/runtime/` 或容器内存；不得把 Microcks 数据库、日志、流量或端口状态登记为正式 artifact、event、checkpoint 或 Gate evidence。
+
+## 4. Mock Scenario Pack 冻结与权威边界
+
+体验目录使用 `mock-scenario-pack-request.yaml`、`mock-scenario-mappings.csv` 和 `mock-admin-export.yaml`。每个 active Review Scene 必须且只能映射一个通过合同验证的 `mock_id + mock_kind + scenario_id`；缺失、重复、kind 冲突或未通过 dispatcher 校验都会阻塞冻结。
+
+受管 Microcks UI 中的修改不会直接成为仓库权威输入。先把每个实际 OpenAPI/AsyncAPI 导出定义保存到体验目录的 `mock-admin-exports/`，再由 `mock-admin-export.yaml` 的 `artifacts` 逐项记录 `mock_kind`、`mock_id`、`protocol`、相对 `ref`、`algorithm: sha256` 和精确 `checksum`。freeze 要求每个被 active Review Scene 使用的 Mock 身份恰好有一个导出物，拒绝缺失、重复、未引用或 checksum 漂移，并用 catalog 的 operation/channel 与 scenario 对实际导出内容执行同一协议校验；仅手写来源、时间和安全布尔值不能通过。
+
+`mock-admin-export.yaml` 还必须明确 `production_traffic_recording`、`production_credentials` 和 `unsanitized_personal_data` 都为 `false`。生产流量录制、生产凭据和未脱敏个人数据默认并始终禁止；`data_source: explicit-import` 即使由用户显式导入，也必须使用 `anonymized` 或 `public` 分类，并提供 `sanitization_status: passed` 的脱敏证据。synthetic 数据使用 `sanitization_status: not-required`。
+
+冻结采用两步人工确认：
+
+```bash
+ai-delivery mock freeze . --experience .workflow/experience \
+  --scenario-pack mock-scenario-pack-request.yaml --dry-run
+# 审阅报告后，把 candidate_checksum、human:<identity> 和 decided_at 写入 request
+ai-delivery mock freeze . --experience .workflow/experience \
+  --scenario-pack mock-scenario-pack-request.yaml
+```
+
+输出 `.workflow/experience/mock-scenario-packs/<artifact-id>.yaml` 绑定 Prototype revision、source/review bundle、Review Scene 映射、导出 manifest、每个实际受管 UI 导出物、合同与脱敏证据 checksum，并记录已校验的 scenario inventory。相同路径已有不同内容时拒绝覆盖。冻结文件仍必须以 `artifact_type: mock-scenario-pack`、`status: submitted` 登记其精确文件 checksum 到正式 artifact registry 后才成为权威；dry-run、受管 UI runtime 或未登记文件均不是 Gate evidence。
+
+Product Backend Mock 可驱动 Prototype 与 UI Acceptance 的界面场景，但其 Pack 明确记录 `real_product_backend_evidence: false` 和 `end_to_end_acceptance_evidence: false`。它不能满足真实产品后端功能、合同实现或端到端验收；真实后端可用且通过对应验证时，按 `replacement_condition` 停用该 mock。
+
+## 5. Prototype 使用
+
+1. 先运行 `mock setup` 和 `mock start`。
+2. 按所有权在 external 或 product-backend catalog 登记 kind、owner、批准合同、replacement condition、协议、operation/channel 与稳定 scenario ID。
+3. 先运行 `mock sync --dry-run` 审阅精确合同列表，再运行 `mock sync`。
+4. 为每个 Review Scene 填写唯一 `mock-scenario-mappings.csv` 行，完成导出/数据分类/脱敏后运行 `mock freeze --dry-run`。
+5. 人工确认精确 candidate checksum，冻结并正式登记 Mock Scenario Pack；Prototype revision 与后续 UI Acceptance 使用同一 Pack。
+6. 不得在 Prototype 内临时伪造另一套响应逻辑，也不得把 Product Backend Mock 当作真实后端证据。
+
+管理 UI 位于 `http://127.0.0.1:8585`。Microcks 的 REST mock URL、AsyncAPI channel 和流量视图由导入合同产生；业务应用和正式前端不得把该地址作为生产配置。
+
+## 6. 验证
+
+日常验证使用本地假 Microcks API，覆盖健康失败清理、multipart 报文、OpenAPI/AsyncAPI operation 与 scenario 身份、dispatcher 输入、catalog 校验和零写入 dry-run，不依赖网络或容器：
+
+```bash
+node --test verification/mock-system.test.mjs
+node --test verification/mock-scenario-pack.test.mjs
+```
+
+可选真实容器验证位于 `verification/microcks-real-container.test.mjs`，覆盖 setup、start、健康、导入、mock 调用、export、停止、重启、重新 sync 和容器不存在断言。清理错误不得被吞掉。它默认 skip；只有维护者显式设置 `AI_DELIVERY_REAL_MICROCKS=1` 时才 pull/运行容器。
+
+## 7. 故障处理
+
+- Docker/Podman 缺失：由用户显式安装并启动，再重试；工作流不代装。
+- `start` 健康超时：检查容器日志和 `127.0.0.1:8585` 端口占用，不改为公网绑定。
+- catalog 或合同校验失败：修复 tracked 输入，先重新运行 `sync --dry-run`。
+- fresh runtime 无服务：重新运行 `sync`；不要恢复旧数据库或把数据库提交到 Git。
+- 合同属于本产品：移出 External Dependency Mock，按 Product Backend Mock 契约登记。
+- Pack freeze 阻塞：修复 Review Scene 唯一映射、导出安全声明、脱敏证据或合同；重新 dry-run，并只确认新的 candidate checksum。