ai-delivery-workflow 0.2.2 → 0.4.0

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

@@ -1,235 +1,113 @@
-# 工作流物料查看器使用指南
+# 工作流管理器使用指南
 
-> 适用对象：使用 AI Delivery Workflow 的产品、研发、测试、运维和审阅人员  
-> 适用范围：由 `ai-delivery init` 安装到当前项目的 `.workflow/tools/viewer/`  
-> 数据边界：只读当前项目 `.workflow/`
+> 本文件保留旧 Viewer 指南的路径，避免已有文档链接失效。`0.4.0` 起，Workflow Manager 是唯一项目内控制面；旧 `.workflow/tools/viewer/` 和独立 Prototype Review Server 已退役。
 
-## 1. 查看器解决什么问题
+## 1. 启动
 
-查看器把 `.workflow/` 中按计划版本、发布和节点分散保存的物料汇总为一个本地工作台，用于：
-
-- 分别查看研发流程与独立发布流程、当前生产版本、累计研发线、发布目标和物料数量；
-- 按状态、类型、节点、Git 变更或关键字筛选；
-- 查看物料路径、版本、更新时间、SHA-256 和适用规范；
-- 跟踪文档中可解析的上游、下游文件引用；
-- 预览 Markdown、CSV、JSON、YAML、JSONL、TOML、文本和图片；
-- 在手机或窄屏浏览器中快速审阅。
-
-查看器没有写接口。批准、修改、归档和生产操作仍由对应 Skill 和正式流程完成。
-
-查看器同时提供只读“自进化控制环”摘要，展示反馈、待处理提案、trial、active、高风险生效、回退和 Hook 结果。自进化批准、启停和回退仍必须通过 `$ai-delivery-evolve-workflow` 与 `.workflow/tools/evolution/evolve.mjs` 完成。
-
-## 2. 安装
-
-在目标项目根目录执行：
-
-```bash
-npx ai-delivery-workflow@latest init .
-npx ai-delivery-workflow@latest doctor .
-```
-
-安装完成后会出现：
-
-```text
-.workflow/tools/
-  viewer/
-    server.mjs
-    start.cmd
-    start.ps1
-    start.sh
-    public/
-```
-
-查看器只安装到当前项目，不会写入用户全局 Codex 或 agent skill 目录，也不会修改业务项目的 `package.json`。
-
-运行环境要求：Node.js 18 或更高版本。
-
-## 3. 启动和停止
-
-### 3.1 Windows CMD
-
-在项目根目录运行：
+在已安装 AI Delivery Workflow 的项目根目录运行：
 
 ```powershell
-.\.workflow\tools\viewer\start.cmd
+.\.workflow\tools\manager\start.cmd
 ```
 
-### 3.2 Windows PowerShell
+PowerShell 可使用 `start.ps1`，macOS/Linux 可使用：
 
-```powershell
-.\.workflow\tools\viewer\start.ps1
+```bash
+sh ./.workflow/tools/manager/start.sh
 ```
 
-### 3.3 macOS 或 Linux
+发行包入口等价：
 
 ```bash
-sh ./.workflow/tools/viewer/start.sh
+ai-delivery manager serve .
 ```
 
-默认行为：
+服务只绑定 `127.0.0.1`，默认自动选择可用端口并打开浏览器。传入 `--port <port>` 固定端口，传入 `--no-open` 禁止自动打开。终端按 `Ctrl+C` 停止。
 
-- 监听 `127.0.0.1:4173`；
-- 自动打开默认浏览器；
-- 扫描启动脚本所在项目的 `.workflow/`；
-- 在终端输出项目路径和访问 URL。
+## 2. 页面
 
-在启动终端中按 `Ctrl+C` 停止服务。
+管理器提供 19 个固定 Page。`P13` 是从原型审批、路由或修订页面进入的上下文详情页，不在固定导航中。
 
-## 4. 常用启动参数
-
-启动脚本会把参数原样传给 `server.mjs`。
-
-| 需求 | 示例 |
+| 模块 | 页面 |
 | --- | --- |
-| 不自动打开浏览器 | `.\.workflow\tools\viewer\start.cmd --no-open` |
-| 更换端口 | `.\.workflow\tools\viewer\start.cmd --port 4180` |
-| 指定监听地址 | `.\.workflow\tools\viewer\start.cmd --host 127.0.0.1` |
-| 临时查看另一项目 | `node .\.workflow\tools\viewer\server.mjs --project E:\path\to\project` |
-
-也可使用环境变量：
-
-| 环境变量 | 默认值 | 作用 |
-| --- | --- | --- |
-| `AI_DELIVERY_VIEWER_HOST` | `127.0.0.1` | 监听地址 |
-| `AI_DELIVERY_VIEWER_PORT` | `4173` | 监听端口 |
-
-显式命令行参数优先于环境变量。
+| 工作台 | `P01` 工作台 |
+| 交付管理 | `P02` 开发流程、`P19` 产品需求、`P03` 执行任务、`P18` 测试用例、`P04` 交付成果 |
+| 人工决策 | `P06` 待办决策 |
+| 项目原型 | `P07` 项目原型、`P11` 视觉规范、`P12` 原型审批、`P13` 页面审核、`P14` 页面路由、`P15` 路由关系、`P16` 修改要求、`P17` 修订记录 |
+| 运行环境 | `P08` 项目系统、`P09` 模拟服务 |
+| 记录与设置 | `P05` 操作与变更记录、`P10` 设置 |
 
-不要把监听地址改成 `0.0.0.0` 后直接暴露到不可信网络。.workflow 可能包含架构、环境、发布和生产证据。
+没有登记的项目事实统一显示“尚未登记”，管理器不会生成示例任务、系统、中间件、协议或需求。
 
-## 5. 界面说明
+## 3. 原型审核
 
-### 5.1 顶部工具栏
+1. 在 `P11` 核对当前项目唯一视觉规范。
+2. 在 `P12` 按页面编号、名称、路由和审核状态筛选当前迭代全部 Page。
+3. 进入 `P13`，切换 Page 的 Review Scene，查看冻结原型内容。
+4. 在独立评论区域输入修改要求；可按 `Ctrl+V` 粘贴 PNG、JPEG 或 WebP 截图。
+5. 保存修改要求，或附加可选评论后执行“退回修改”或“审核通过”。
 
-- 项目名称来自 `.workflow/delivery/project.yaml`；
-- 迭代选择器用于切换当前或历史迭代；
-- 搜索框匹配标题、路径、物料 ID、类型、节点和规范 ID；
-- “刷新”重新扫描磁盘，不需要重启服务；
-- 最近扫描时间表示本次目录扫描完成时间。
+修改要求可在 AI 开始执行前反复编辑或废弃。AI 开始执行后内容锁定。所有决定、附件和修改要求都绑定精确 Prototype Revision、Page/Scene 和 checksum；原型内容由受限 iframe 提供，不能直接修改正式状态。
 
-可使用 `Ctrl+K` 或 `Command+K` 聚焦搜索框。
+## 4. 项目系统
 
-### 5.2 工作流节点
+`P08` 的架构视图和列表视图是两个独立 Tab：
 
-左侧按“治理、研发流程、发布流程、历史兼容”分组展示节点。新流程包含 13 个研发节点和 11 个发布节点；只有存在历史物料时才显示旧发布节点。
+- Project System Registry 声明的所有应用、服务和中间件都会显示；尚未实现的节点以虚线状态显示。
+- 当前分支拥有且已实现的节点才开放受控生命周期动作；其他分支和未实现节点只读。
+- 用户未指定启动方式时默认使用 Docker。登记的 Dockerfile 或 Compose 文件可查看路径、checksum 和文本。
+- 初始化脚本可直接新建或修改文本，也可从 Registry 允许的项目内目录导入本地文件。
 
-点击节点可以筛选，再次点击同一节点可取消筛选。移动端使用横向节点栏。
+生命周期和脚本写入先生成计划，再校验 expected revision/checksum 后应用，并产生不可变 Receipt 与事件。界面不提供任意命令、任意文件路径或 YAML 编辑能力。
 
-### 5.3 研发与发布进度
+## 5. 模拟服务和人工决策
 
-顶部摘要显示当前生产版本、累计研发线、待发布版本数、发布目标和发布模式。当前生产版本、生产 release ID 和累计研发版本优先读取 `workflow-state.yaml` 的审计字段，旧 `project.yaml` 字段仅作兼容回退。下方两条独立轨道分别计算研发与当前发布进度。只有节点存在物料且这些物料全部为成功状态时，节点才计为完成；`frozen`、`immutable`、`deployed` 和 `archived` 均属于正式成功状态。
+`P09` 以可读方式展示 External Dependency 与 Product Backend Mock 的协议、操作、触发条件、正常/业务异常/系统异常场景、报文和来源文件。同步定义使用受控 plan/apply 动作，不能替代真实后端或端到端验收。
 
-进度百分比用于快速浏览，不替代 Gate、审批记录或版本归档证明。
+`P06` 展示当前需要人工决定的正式 Gate。批准和退回都可添加评论供 AI 读取；不存在自动超时。视觉规范和 Page 审核仍分别在 `P11`、`P12/P13` 完成，P06 只提供汇总入口。
 
-### 5.4 筛选和物料表
+## 6. AI 接口
 
-支持：
+UI、HTTP 和 CLI 使用同一应用服务。AI 应优先使用结构化接口，而不是浏览器自动化：
 
-- 状态；
-- 文件类型；
-- 节点；
-- 仅看 Git 变更；
-- 全文关键字。
-
-点击“重置”清空筛选。表中点击一行会打开详情；键盘聚焦行后可使用 `Enter` 或空格打开。
-
-### 5.5 详情和预览
-
-详情区显示：
-
-- 节点、类型、版本、物料 ID、更新时间和大小；
-- Git 状态和迭代；
-- 上游、下游文件引用；
-- SHA-256；
-- 正文中识别到的 `STD-*` 规范 ID；
-- 格式化预览或原文。
-
-点击上游或下游引用可以跳转到对应物料。按 `Escape` 或点击关闭按钮关闭详情。
-
-## 6. 查看器如何识别物料
-
-查看器递归扫描当前项目 `.workflow/`，符号链接不会被跟随。用于让 Git 保留空目录的 `.gitkeep` 是结构占位文件，不会出现在物料、迭代、发布或节点计数中。被 Git 忽略的 `.workflow/delivery/runtime/` 保存本机活动任务、心跳、锁、Evolution 原始队列和安装备份，也不会作为正式物料扫描；`.workflow/evolution/` 和 `.workflow/extensions/` 中的脱敏治理物料会正常显示。
-
-常用识别规则：
-
-| 信息 | 优先来源 |
-| --- | --- |
-| 项目 | `.workflow/delivery/project.yaml` |
-| 当前迭代 | `workflow-state.yaml` 的 `development_state.scope_id`；旧 schema 回退到顶层 `iteration_id`，最后才使用 `project.yaml.current_iteration_id` |
-| 生产与累计研发身份 | `workflow-state.yaml` 的 `production_version_id`、`production_release_id`、`latest_line_version_id`；其次才是 `project.yaml` 兼容字段 |
-| 节点 | 已登记物料优先使用 `artifact-registry.yaml` 的 `node`；否则使用路径或正文字段 |
-| 标题 | Markdown 一级标题，其次是 `title`、`name`、物料 ID，最后是文件名 |
-| 状态 | Git 变更优先；已登记物料其次使用注册表 `status`；最后读取正文状态字段 |
-| 版本 | 已登记物料优先使用注册表 `version`；否则读取正文版本字段 |
-| 物料 ID | 已登记物料优先使用注册表 ID；否则读取正文 ID 字段 |
-| 规范 | 正文中的 `STD-[A-Z0-9-]+` |
-| 关系 | 正文中指向已存在 `.workflow/...` 文件的路径引用 |
-
-建议在正式物料中使用稳定路径和明确字段。只写自然语言而没有路径或字段时，查看器不会猜测关系和状态。
-
-查看器不会修改状态。需要更新正式状态时使用 `.workflow/tools/state/state.mjs`，详见[正式状态 CLI 使用指南](STATE-CLI-USER-GUIDE.zh-CN.md)。
-
-## 7. 文件和预览限制
-
-- 单次最多扫描 10,000 个文件，超过后界面会提示结果已截断；
-- 文本预览上限为 2 MiB；
-- 大于 2 MiB 的文本仍可出现在目录中，但不能在线预览；
-- 图片支持 GIF、JPEG、PNG 和 WebP；
-- PDF 可被登记和筛选，但当前不提供内嵌预览；
-- CSV 格式化预览最多展示前 200 行；
-- 查看器按请求重新生成目录数据，不维护独立数据库。
-
-## 8. 安全边界
-
-查看器具备以下固定边界：
-
-- 仅接受 HTTP `GET`；
-- 文档和图片读取路径必须位于当前项目 `.workflow/`；
-- 拒绝 `..` 等路径穿越；
-- 静态资源只能来自内置 `public/`；
-- 默认只绑定本机回环地址；
-- 静态页面带 CSP、`nosniff` 和无引用来源策略；
-- 不提供修改、上传、删除、审批或部署接口。
+```bash
+ai-delivery manager inspect .
+ai-delivery manager list . --resource facts
+ai-delivery manager show . --resource prototypes
+ai-delivery manager export . --resource systems
+ai-delivery manager action <action-name> . --input <project-relative-json>
+```
 
-浏览器能看到的内容仍受当前操作系统用户权限控制。不要在不可信机器上运行包含敏感生产物料的项目。
+资源仅限 `manager`、`facts`、`prototypes`、`systems`、`mock`、`settings`。动作仅限发行包白名单，并要求精确身份、actor、expected revision/checksum、幂等键及所需的 plan checksum。AI 建议关系不会自动成为正式关系，也不能直接改变任务或节点状态。
 
-## 9. 升级查看器
+## 7. 安全边界
 
-查看器是安装器受管目录。升级前先预览：
+- 只绑定本机回环地址；不支持局域网监听参数。
+- 请求体有固定大小上限，未知资源和动作确定性拒绝。
+- 文件读取和导入只能落在业务项目及 Registry 声明的受控路径内。
+- 正式节点状态始终由正式状态事实派生，不能在管理器中手工改写。
+- 原型修改、用户确认、正式前端修改的顺序始终强制执行。
+- 页面面向桌面端 `1280x720` 和 `1440x900`；移动端不在支持范围内。
 
-```bash
-npx ai-delivery-workflow@latest init . --dry-run
-```
+## 8. 升级
 
-如果目标项目中的 `.workflow/tools/viewer/` 与新版不同，默认会停止并报告冲突。确认采用新版后执行：
+升级前先预览：
 
 ```bash
-npx ai-delivery-workflow@latest init . --force
-npx ai-delivery-workflow@latest doctor .
+npx ai-delivery-workflow@latest upgrade . --dry-run
 ```
 
-`--force` 会先把旧查看器备份到 `.workflow/delivery/runtime/backups/<timestamp>/`。
-查看器是可选工具。直接删除 `.workflow/tools/viewer/` 只会停止浏览功能，不影响状态 CLI、Hook、Checkpoint、恢复、研发和发布；此时 `doctor` 输出 `WARN` 但保持成功退出。再次执行 `init` 会重装查看器且不改写正式工作流状态。
-
-不要直接把业务项目中的查看器修改复制回发行仓库。发行源码的唯一权威位置见[查看器维护指南](VIEWER-MAINTENANCE.zh-CN.md)。
+`0.4.0` 升级会把旧 Viewer 作为带备份的 `remove` 操作登记到升级 Receipt。回滚仍受正式事件树与受管文件完整性保护，并可恢复该旧目录。新安装和升级后的安装清单只登记 Manager，不再登记 `viewer_root` 或 `viewer_start`。
 
-## 10. 常见问题
+## 9. 故障处理
 
 | 现象 | 处理 |
 | --- | --- |
-| 端口被占用 | 使用 `--port 4180`，或停止原来占用端口的进程。 |
-| 浏览器没有自动打开 | 打开终端输出的 URL，或去掉 `--no-open`。 |
-| 页面没有最新文件 | 点击“刷新”，确认文件已写入 `.workflow/`。 |
-| 项目或迭代名称不正确 | 检查 `.workflow/delivery/project.yaml` 和 `workflow-state.yaml`。 |
-| 物料落在“未分配” | 按规范调整目录，或补充 `node_id`。 |
-| 状态显示“未标记” | 增加受支持的状态字段和值。 |
-| 没有上下游关系 | 使用指向真实文件的 `.workflow/...` 或相对路径引用。 |
-| 文本无法预览 | 检查扩展名、文件大小和 UTF-8 编码。 |
-| `doctor` 报告查看器不完整 | 先执行 `init --dry-run`，确认后用 `init --force` 修复受管副本。 |
-
-## 11. 相关文档
-
-- [完整项目手册](PROJECT-MANUAL.zh-CN.md)
-- [查看器维护指南](VIEWER-MAINTENANCE.zh-CN.md)
-- [逐文件参考](FILE-REFERENCE.zh-CN.md)
-- [全流程审计物料](../audit/README.md)
+| 端口被占用 | 省略 `--port` 自动选取，或指定另一个端口。 |
+| 浏览器没有自动打开 | 打开终端输出的 loopback URL，或确认未使用 `--no-open`。 |
+| 页面显示“尚未登记” | 登记对应正式事实；不要在界面制造演示数据。 |
+| 修改后未刷新 | 点击页面“刷新状态”；操作成功反馈会保留到新数据加载完成。 |
+| 操作返回 revision/checksum mismatch | 重新刷新，基于最新事实重新生成 plan，禁止强行覆盖。 |
+| `doctor` 报告旧 Viewer 漂移 | 先审阅 `upgrade --dry-run`，再由升级 Receipt 受控移除。 |
+
+相关文档：[完整项目手册](PROJECT-MANUAL.zh-CN.md)、[维护指南](VIEWER-MAINTENANCE.zh-CN.md)、[CLI 参数参考](CLI-PARAMETER-REFERENCE.zh-CN.md)、[逐文件参考](FILE-REFERENCE.zh-CN.md)。

package/docs/adr/0001-prototype-first-ui-governance.md

@@ -0,0 +1,3 @@
+# Prototype-first UI governance
+
+All user-visible UI changes use one approved Visual Standard and must update an isolated, production-compatible Prototype before production frontend code changes; there is no emergency or small-change exception. The workflow removes the low-fidelity UX stage, exposes every Page and Review Scene through a Review Shell, and records revision-bound Page approvals through a local Review Server before implementation. Agent Hooks and Git/CI validation block unapproved frontend changes, while Candidate Assurance verifies prototype-to-frontend consistency. This deliberately accepts additional prototype maintenance and enforcement infrastructure in exchange for preventing hidden UI states, design drift, and production-first changes that cannot be reviewed coherently.

package/docs/adr/0002-microcks-as-default-mock-system.md

@@ -0,0 +1,3 @@
+# Microcks as the default Mock System
+
+Use Microcks as the default project-scoped Mock System because the workflow requires a separate management UI, versionable API and message artifacts, automation interfaces, local container operation, and broader protocol coverage than HTTP-only tools provide. Mock definitions exported to the workflow repository remain authoritative while the Microcks runtime database and traffic logs are disposable; unsupported raw or private protocols require an explicit extension decision rather than silently adding a second Mock System. This accepts a heavier container dependency than Mockoon, WireMock, or Prism in exchange for one managed service-virtualization surface.

package/docs/adr/0003-workflow-manager-governed-control-surface.md

@@ -0,0 +1,46 @@
+---
+status: accepted
+---
+
+# Workflow Manager as the governed control surface
+
+Replace the read-only Workflow Viewer and separate user-facing Review Server with one project-bound Workflow Manager. It owns Decision Inbox, Review Center, Project System Console, and valid workflow transitions, while the Prototype-owned Review Shell only renders requested Page and Review Scene content inside the review sandbox. This supersedes the Review Server ownership described in ADR 0001 but retains its prototype-first rule and immutable, checksum-bound decisions; the Manager deliberately exposes only contracted actions and never arbitrary commands, file editing, direct YAML editing, or Agent execution.
+
+This accepts a larger local application and stricter capability boundaries in exchange for one coherent human decision surface, auditable state transitions, and removal of duplicated review/runtime products.
+
+## AI collaboration contract
+
+Workflow Manager is designed for human and AI collaboration. Its UI and Agent Interface are two clients of the same application services and authorization rules. A UI capability is incomplete until the corresponding bounded Agent Interface is implemented and verified.
+
+Every readable manager capability must provide:
+
+- stable entity identities and explicit project, workspace, branch, iteration, revision, and checksum context;
+- a documented `list`, `show`, `inspect`, or `export` command with versioned JSON output;
+- discoverable links between requirements, tasks, tests, Prototype Pages and Review Scenes, artifacts, decisions, events, Project Systems, and Mock scenarios;
+- explicit lifecycle and mutability metadata so an agent can distinguish editable state from immutable evidence;
+- deterministic errors and exit codes suitable for automated recovery.
+
+Every mutating manager capability must additionally provide:
+
+- a package-delivered CLI or script adapter; one-off repository scripts are not the product interface;
+- an exact target identity plus expected revision or checksum for optimistic concurrency control;
+- `plan` or `--dry-run` support when an action can affect multiple entities, files, processes, dependencies, or Mock definitions;
+- idempotency or an idempotency key for retryable requests;
+- the same validation, authorization, and legal-transition checks used by the UI;
+- a structured result and receipt containing actor, time, input revision, affected identities, outcome, and error details;
+- an immutable event that allows the UI, workflow state, and later agents to observe the result.
+
+The first implementation must cover the entire manager surface, including workflow inspection and legal transitions, requirements, tasks, test cases and runs, artifact registration, human decisions with comments, Prototype review and change requests, Project System observation and lifecycle plans, Mock contract and scenario management, event queries, and governed settings.
+
+Material being agent-operable does not make it directly overwritable. Immutable approvals, receipts, review batches, approved Prototype revisions, and audit events are operated through append, supersede, discard-before-execution, or legal state-transition commands. The Agent Interface never grants arbitrary shell execution, arbitrary operating-system access, raw file editing, direct YAML mutation, or permission to bypass the Prototype-first and human-approval rules.
+
+## Implementation completion
+
+A Workflow Manager feature is complete only when all of the following exist:
+
+1. The UI behavior and its bounded application-service operation.
+2. A CLI or script command that invokes the same operation without browser automation.
+3. Versioned input and output schemas with stable identifiers.
+4. Authorization, checksum or revision validation, and receipt emission where applicable.
+5. Automated parity tests proving that UI and Agent Interface results are derived from the same state transition.
+6. Command help and an Agent-facing reference that identifies readable fields, legal actions, and recovery behavior.

package/docs/adr/0004-operational-carbon-visual-standard.md

@@ -0,0 +1,9 @@
+---
+status: accepted
+---
+
+# Operational Carbon as the Workflow Manager visual standard
+
+Use Visual Reference 02, derived from IBM Carbon, as the approved Operational Carbon Visual Standard shared by Workflow Manager, the isolated Prototype, and production frontend UI Acceptance. It uses IBM Plex, Lucide icons, white and light-gray planar hierarchy, 0-2px radii, 1px hairlines, blue only for primary actions and selection, and explicit semantic status colors; desktop acceptance targets are 1440x900 and 1280x720 with a minimum supported width of 1180px, and mobile is outside scope.
+
+This favors dense, scan-oriented operational clarity and direct prototype-to-production comparison over expressive styling, decorative cards, shadows, or separate prototype and production design languages.

package/docs/adr/0005-prototype-management-as-routed-pages.md

@@ -0,0 +1,7 @@
+---
+status: accepted
+---
+
+# Prototype Management as independently routed pages
+
+Model Prototype Management as a Workflow Manager navigation module with `P07` as its overview and `P11` through `P17` as independently routed Pages for visual standards, the review queue, Page review, route catalog, route graph, change requests, and revision history. Review Scenes describe conditions of one Page and never act as feature destinations; the former functional Scenes `P07-S06` through `P07-S18` are therefore retired without reusing their fixed identifiers. This accepts a larger Page and route manifest in exchange for stable deep links, clear workspace ownership, complete per-Page state review, and a strict boundary between Workflow Manager Pages and the `APP-Pxx` Project Prototype being governed.

package/docs/agents/domain.md

@@ -0,0 +1,12 @@
+# Domain Docs
+
+本仓库采用 single-context 布局：
+
+- 领域术语：根目录 `CONTEXT.md`
+- 架构决策：根目录 `docs/adr/`
+
+探索代码前读取存在的 `CONTEXT.md`，并读取与目标区域有关的 ADR。
+文件不存在时直接继续，不主动创建；由领域建模流程按需生成。
+
+输出中的领域概念使用 `CONTEXT.md` 定义的术语，避免引入被明确
+排除的同义词。若输出与现有 ADR 冲突，必须明确指出冲突及理由。

package/docs/agents/issue-tracker.md

@@ -0,0 +1,27 @@
+# Issue Tracker
+
+本仓库使用 Gitee Issues 跟踪任务：
+
+- 仓库：`hzr1348/work-flow`
+- API：`https://gitee.com/api/v5`
+- Swagger：`https://gitee.com/api/v5/swagger`
+- PR 不作为任务请求入口。
+
+## Authentication
+
+令牌只从环境变量 `GITEE_TOKEN` 读取，请求头使用：
+
+`Authorization: token <PAT>`
+
+令牌不得写入 URL、输出、日志、脚本或仓库文件。
+
+## Execution
+
+每个新会话首次访问时，先调用 `GET /user`。预期账号为
+`hzr1348`，用户 ID 为 `17347733`；身份不符时停止。
+
+写操作必须先读取并确认目标，获得当前请求授权后执行，再重新读取
+目标验证结果。Swagger 页面只用于查阅，实际请求使用 API endpoint。
+
+Gitee MCP 返回 `401 Access token is wrong type` 时使用 REST API。
+网络沙箱阻止请求时，为目标 Gitee API 请求申请网络权限。

package/docs/agents/triage-labels.md

@@ -0,0 +1,11 @@
+# Triage Labels
+
+| Canonical role    | Gitee label      | Meaning            |
+| ----------------- | ----------------- | ------------------ |
+| `needs-triage`    | `needs-triage`    | 等待维护者评估     |
+| `needs-info`      | `needs-info`      | 等待补充信息       |
+| `ready-for-agent` | `ready-for-agent` | 可交给自主代理执行 |
+| `ready-for-human` | `ready-for-human` | 需要人工实现       |
+| `wontfix`         | `wontfix`         | 不会处理           |
+
+技能提到 canonical role 时，使用表中对应的 Gitee label。

package/docs/agents/workflow-manager-acceptance-matrix.md

@@ -0,0 +1,93 @@
+# Workflow Manager P0/P1/P2 acceptance matrix
+
+Updated: 2026-08-21
+
+This matrix is the completion ledger for P0/P1/P2. `covered` means current automated, release, or externally read-back evidence exercises the requirement. A route registration or placeholder does not count as a Page implementation.
+
+## Shared contract
+
+| Requirement | Current implementation | Executable evidence | Status |
+| --- | --- | --- | --- |
+| One installed control surface | Manager runtime, React assets and cross-platform launchers; no Viewer on new install | `verification/workflow-manager.test.mjs`, `verification/project-installer.test.mjs` | covered |
+| CLI/HTTP/UI parity | all call `workflow-manager.mjs` resources/actions | package, installed CLI and HTTP equality tests | covered |
+| Seven-node formal state | P01/P02 derive only from `state inspect.derived_node_states` | delivery-state and browser tests | covered |
+| Stable context | workspace, project, branch, iteration, revision and checksum fields | Manager inspect/resource tests | covered |
+| No invented facts | empty/not-registered projections remain explicit | facts, systems, Mock and browser tests | covered |
+| Governed writes | fixed action allowlist, actor, revision/checksum, idempotency and plan checksum as applicable | governance, prototypes, systems and Mock tests | covered |
+| Receipts and events | all stateful Manager actions use formal service or write immutable Receipt/Event | module-specific tests | covered |
+| Desktop visual contract | Chinese Operational Carbon, IBM Plex, Lucide; 1280x720 and 1440x900 | 19 Page browser acceptance | covered |
+| Package installation lifecycle | new install, Viewer remove/backup/rollback, installed Manager | installer and Manager tests | covered |
+| `0.4.0` candidate and target project | package, isolated install/upgrade/migrate/rollback, tushare read-only preflight | candidate SHA-256, isolated receipts, installed Manager probes and target-project dry-run summaries below | covered |
+
+## Page delivery
+
+| Page | Responsibility | Resource/action contract | Browser evidence | Status |
+| --- | --- | --- | --- | --- |
+| P01 | attention and next action | manager projection | direct load | covered |
+| P02 | seven nodes, work, state evidence and transition rules | manager projection | node selection, Tabs, headers and drill-down | covered |
+| P03 | stable tasks, attempts, phases and recovery | facts | all-Page traversal | covered |
+| P04 | deliverable versions, checksums and references | facts | all-Page traversal | covered |
+| P05 | immutable operation/change history | facts | all-Page traversal | covered |
+| P06 | Gate inbox and optional comments | facts + `gate-decision-apply` | all-Page traversal | covered |
+| P07 | current project Prototype overview | prototypes | all-Page traversal | covered |
+| P08 | architecture/list, branches, Docker, scripts and lifecycle | systems + script/lifecycle plan/apply | Tabs, implemented/planned nodes and list | covered |
+| P09 | readable protocols and Mock scenarios | mock + sync plan/apply | all-Page traversal | covered |
+| P10 | fixed safety rules and preferences | settings + `settings-update-plan` / `settings-update-apply` | all-Page traversal and checksum-bound plan/apply | covered |
+| P11 | single Visual Standard | prototypes | all-Page traversal | covered |
+| P12 | filterable current-iteration Page queue | prototypes | filter and P13 navigation | covered |
+| P13 | Page/Scene review, text/screenshots and decisions | prototype actions | Scene switch, Ctrl+V, save and desktop layout | covered |
+| P14 | Page/Scene route catalog | prototypes | all-Page traversal | covered |
+| P15 | clickable route relationship graph | prototypes | Scene deep link to P13 | covered |
+| P16 | repeated change requests and execution lock | prototype actions | all-Page traversal | covered |
+| P17 | immutable revision history | prototypes | all-Page traversal | covered |
+| P18 | test cases and runs | facts | all-Page traversal | covered |
+| P19 | requirements and generic related work | facts + relationship actions | all-Page traversal | covered |
+
+`P13` is contextual and absent from fixed navigation. Page identifiers are fixed and unique; new Pages append identities without reusing retired numbers.
+
+## Legacy convergence
+
+| Surface | Current evidence | Status |
+| --- | --- | --- |
+| Workflow Viewer | template/runtime/tests removed; new manifest omits Viewer; old Viewer is Receipt-backed `remove` and rollback restore | covered |
+| User-visible Prototype Review Server | CLI/server/static shell/tests removed; target and Page Receipt internals retained for Manager | covered |
+| Public documentation | current guides route users and agents to Manager P11/P12/P13 | covered |
+| Historical 13-node state | read-only state compatibility remains; Manager exposes only seven-node producer model | covered |
+
+## `0.4.0` candidate evidence
+
+The canonical candidate identity, SHA-256, file count, source commit, and lifecycle report are recorded in the maintenance-repository file `audit/WORKFLOW-MANAGER-P0-P1-P2-CLOSURE.md`. The archive and expanded lifecycle workspace remain in ignored `.tmp/`; the audit record is outside the npm package, so the archive does not self-reference its own checksum.
+
+- A fresh isolated project passed Doctor except for the optional CodeGraph warning. The historical r8 candidate returned HTTP 200, health `true`, schema `workflow-manager.v1`, 19 Pages, seven nodes, Prototype `wm-prototype-r24@4452c605`, and 25 discoverable governed actions.
+- An isolated `0.3.0` project produced an upgrade plan with zero conflicts, one Manager addition, eight managed replacements, one Viewer removal, and no code-repository write. Applying the upgrade produced Receipt `UPGRADE-20260812T221812525Z-cde0bf7d`.
+- Rolling back that Receipt restored manifest version `0.3.0`, restored all seven Viewer files, removed Manager, changed the Receipt status to `rolled_back`, and left both isolated Git worktrees byte-for-byte clean against their pre-upgrade commits. The recorded pre-upgrade Viewer digest remains `5cfb8de36f36ccf8149e6f8047e85e48b573a52ef28e67adf35d675497148369`.
+- Against `E:\work\ai\codex\tushare`, `doctor`, `upgrade --dry-run`, and `migrate --dry-run` completed without formal apply. Doctor reported the existing pre-upgrade managed-runtime drift; the upgrade plan has one addition, eight replacements and one removal with zero managed-asset conflicts and `code_repository.write_planned=false`. Each dry-run was bracketed by an identical current-state Git status digest.
+- The `tushare` migration preflight deliberately returned `can_apply=false`: one legacy Prototype source checksum conflicts with its manifest and 24 task families require human semantic-grouping decisions across 183 historical tasks. No business state was changed. This is the required fail-closed result, not authorization to apply or force migration.
+- The maintainer cancelled the formal `tushare` upgrade/migration on 2026-08-21. The target remains read-only; the failed-closed migration plan is retained as evidence and must not be forced into an apply.
+
+The current formal Manager baseline has since been promoted to `wm-prototype-r33@f98e7595` through the independent Prototype-to-Frontend gate. The historical `0.4.0` candidate above remains bound to r24 and is immutable evidence; it does not contain the r33 promotion and cannot be reused for npm publication. A new release candidate is required before publication.
+
+## v2 Prototype catalog Candidate Assurance
+
+This addendum covers the destructive v2 Prototype Revision contract. It does not replace the immutable `0.4.0` candidate identity above or authorize npm publication.
+
+| Requirement | Executable evidence | Status |
+| --- | --- | --- |
+| Package delivery fails closed when a v2 Manager/catalog dependency is absent | `doctor treats v2 Prototype catalog delivery dependencies as required package surface` in `verification/project-installer.test.mjs` | covered |
+| Fresh tarball installation delivers v2-only Manager/Experience material | `isolated package Candidate Assurance binds v2 Revision facts across installed CLI, HTTP, and P07/P11-P17` in `verification/workflow-manager.test.mjs` runs `npm pack`, consumer install, `init`, and `doctor` | covered |
+| P07 and P11-P17 use one Revision fact through installed CLI, HTTP, and UI | the same isolated test compares installed CLI/HTTP JSON, verifies each Web browser request and response is `TERM-WEB` scoped, and proves P12 renders the independent `TERM-ADMIN` target at `1280x720` and `1440x900` | covered |
+| Component Candidate lifecycle write is controlled across Agent and UI service boundaries | the same isolated test runs P11 `candidate -> under-review`, installed CLI `under-review -> registered`, and HTTP `registered -> modified`; each apply emits a Receipt/event and both Agent clients replay idempotently | covered |
+| Old catalog input has no compatibility fallback | the same isolated test removes the required `components` catalog and verifies matching CLI/HTTP errors plus the P13 controlled error state | covered |
+
+`prototype-set.yaml` and its members are retained only as read-only migration inputs. New Experience production uses `prototype-revision-catalog.v2`; no new install, Manager read model, or Candidate Assurance path emits a legacy set.
+
+## Release gate
+
+P0/P1/P2 completes only after all of the following are current and green:
+
+1. `node --test verification/workflow-manager*.test.mjs` and the full `npm test` suite.
+2. `npm run manager:build`, `npm run skills:validate`, `npm run pack:check`, and `git diff --check`.
+3. Final `index.html` asset references are Git-tracked and present in the tarball.
+4. A `0.4.0` candidate passes isolated new install, upgrade, migrate dry-run, rollback and installed Manager CLI/API/UI checks.
+5. The candidate passes `doctor`, `upgrade --dry-run`, and `migrate --dry-run` against `E:\work\ai\codex\tushare` without formal apply.
+6. Gitee P0/P1/P2 Issues contain the same evidence, duplicate tickets are merged or closed, dependencies are corrected, and every write is read back. This is covered: `IK8BA0` through `IK8BA5`, `IK8B9Z`, `IK8B9U`, `IK6HCD`, `IK89SN`, and `IK6HCE` were closed in the Gitee UI after explicit user confirmation and API v5 subsequently returned `state: rejected` for each, which is Gitee's API representation of the UI's “已关闭” status.