@loomhelm/multi-task-flow 0.0.0-stage → 0.2.1

package/toolkit/skills/docs/vendor/dot-codex/design/multi-task-flow/plan-revision-and-change-audit.md

@@ -0,0 +1,99 @@
+# Multi Task Flow 计划修订与阶段审计设计
+
+本文说明 Multi Task Flow 如何区分设计阶段和实现阶段的计划调整，如何保留计划与任务的历史，以及如何从同一份可执行合同生成 runtime、dashboard 和 LLM 所需语义。本文只描述本地编排边界，不授权启动会话、创建 PR、发布或部署。
+
+## 核心维度
+
+`execution_phase`、`plan_lifecycle`、`active_plan_id` 和 `execution_plan_id` 是互相独立的事实。
+
+```text
+execution_phase: planning | implementation
+plan_lifecycle: proposed | approved | superseded | abandoned
+active_plan_id: 当前选择的候选版本
+execution_plan_id: 当前实际支配调度的已批准版本
+```
+
+阶段只由真实 `task_started` 事件决定：首个事件前是 `planning`，之后永久是 `implementation`。dispatch claim、会话创建、`starting` 和计划选择都不触发阶段切换。
+
+高影响修订提出后，`active_plan_id` 可以指向 `proposed` 候选，而 `execution_plan_id` 继续指向旧的 `approved` 版本。批准时原子切换两个指针并把旧版本标记为 `superseded`；放弃时把候选标记为 `abandoned` 并恢复旧指针。
+
+## 变更判定
+
+runtime 根据规范化 diff 推导变更级别，调用方不得在请求中自报级别。
+
+| 阶段与变化 | `change_class` | 理由 | 证据 | 重新批准 | 调度 |
+| - | - | - | - | - | - |
+| 尚无 `task_started` 的计划内容变化 | `planning_revision` | 可选 | 可选 | 必须 | 候选未批准前不调度 |
+| 实现阶段仅改标题、说明、标签或估时 | `implementation_low_impact` | 必须 | 可选 | 不需要 | 不暂停 |
+| 实现阶段改依赖、归属、owned surfaces、基线、验收、父 PR、发布或部署动作 | `implementation_high_impact` | 必须 | 必须 | 必须 | 只暂停受影响任务及其后继 |
+| 仅改 dashboard 展示、筛选、缩放或 URL 状态 | 无账本修订 | 不需要 | 不需要 | 不需要 | 不改变调度事实 |
+
+任何修订都必须有非空 canonical diff。实现阶段的理由是结构化对象，至少包含 `category`、`summary`、`evidence_refs` 和 `impact`；高影响修订的 `evidence_refs` 非空。缺少理由、证据或 diff 时，在账本变更前拒绝请求。
+
+## 不可变快照与任务迁移
+
+计划内容在提出后不可原地修改。计划修订保存新增、删除和修改的路径及旧/新值，并记录受影响的 task、node、edge、暂停对象、理由与批准要求。
+
+已产生 `task_started` 的任务不能通过计划请求改写 runtime 状态或任务边界。需要改变边界时：
+
+1. 新任务使用新 ID、`planned` 状态、`active` 处置和新的 `base_sha`。
+2. 旧任务保留状态、开始时间、事件、事实、证据和责任历史，并标记 `disposition=superseded`。
+3. `task_migration_recorded` 记录旧/新 ID、理由、证据、继承与未继承产出、新基线、关联计划修订和迁移时间。
+
+任务 `state` 表示执行进度；`disposition` 表示责任身份。两者不能互相替代。
+
+## 自解释合同
+
+`skills/multi-task-flow/lib/schema.ts` 是唯一执行合同源。相邻的 `contract.ts` 只提供该合同的元数据、JSON Schema 和按操作裁剪的 `localSemanticProjection`，不建立第二套字段解析器。
+
+同一合同提供：
+
+- Zod runtime 校验和跨字段不变量；
+- JSON Schema；
+- dashboard/API 的稳定字段投影；
+- 当前操作所需的 LLM 局部语义，包括阶段、候选/执行计划、生命周期、变更级别、受影响对象、理由/证据要求、批准影响、允许转换、正例和反例。
+
+`schema_version` 表示存储结构；`contract_version` 表示领域语义。旧账本缺少新字段时只做确定性的读取归一化；语义无法安全归一化时必须拒绝，不能静默猜测。
+
+## Dashboard 投影
+
+View 必须独立输出：
+
+- `execution_phase`；
+- `active_plan_id` 与 `execution_plan_id`；
+- active plan 的 `lifecycle`；
+- `change_class`、canonical diff、理由/证据要求和批准状态；
+- 任务 `disposition`、`is_held` 与 `hold_reason`。
+
+高影响候选尚未批准时，hold 只对受影响任务及其后继生效；批准后暂停列表作为审计历史保留，但不能继续阻塞 ready。页面不能把 `active_plan_id`、`starting`、dispatch claim 或末节点名称当成实际完成。
+
+## Loomhelm v2 到 v3 回放
+
+回放的 v2/v3 均没有 `task_started`、运行操作或外部事实，因此四条依赖删除必须得到：
+
+```text
+execution_phase: planning
+change_class: planning_revision
+reason_required: false
+diff_required: true
+approval_required: true
+```
+
+canonical diff 必须包含：
+
+```text
+session-resume -> query-layer
+server-read-path -> query-layer
+query-layer -> ui-regression
+ui-regression -> docs
+```
+
+只要加入任一真实 `task_started` 事实，同一删除就变为 `implementation_high_impact`，缺少理由或证据必须被拒绝；候选提出期间旧 `execution_plan_id` 保持不变，批准后才切换。
+
+## 操作边界与恢复
+
+- 修订操作通过账本原子事务执行，失败不能留下半个计划、事件或指针状态。
+- 同一 `request_id` 只能重放同一 canonical input；事件 ID 在一个请求产生多个事件时使用稳定后缀保持唯一。
+- 待批准高影响修订期间禁止再次提出候选；无关任务仍按旧 execution plan 运行。
+- `plan-abandon` 是恢复旧执行计划的唯一显式路径；不能通过直接改指针绕过事件。
+- 所有分类、hold 和迁移结论都由本地确定性回放证明，不以真实外部 PR 或手动 workflow 作为唯一证据。

package/toolkit/skills/docs/vendor/dot-codex/design/multi-task-flow/shared-viewer.md

@@ -0,0 +1,129 @@
+# 共享编排展示服务
+
+主人已确认本设计，作为后续实现依据。确认范围仅为设计，不包含实现、安装、服务启动、升级或数据迁移授权。
+
+## 已确定的边界
+
+同一台电脑、同一 OS 用户共用一个展示服务，覆盖所有项目、主任务和 Codex 会话。服务生命周期独立于对话；不同 OS 用户隔离，不包含跨机器或多人访问。
+
+服务负责运行列表、各运行仪表盘和实时数据展示。主 Agent（main Agent） 与 CLI 继续负责调度、派发和账本写入。共享展示服务不是运行时执行权的所有者。
+
+## 启动与维护边界
+
+服务默认不随登录或开机自启动。Agent 使用时通过统一入口按需请求启动或复用单例，并续期使用租约；服务内部维护有效租约集合，不使用需要对称增减的引用计数。
+
+Agent 租约按主会话 ID 与 run ID 区分，默认 TTL 为 60 分钟且可配置。相关 CLI 操作自动续期，长时间等待可显式续期；某个任务释放或过期不影响其他任务，未完成账本本身不保活服务。续期只影响展示服务寿命，不授予账本写权限或主控制权。
+
+浏览器也可持有并定期续期独立使用租约，默认每 60 秒续期，TTL 为 5 分钟。关闭页面或暂停通信后自然过期，最后一份有效租约到期时服务自行退出；恢复页面时重新连接，若服务已退出则提示先 ensure。
+
+只为存在页面订阅的运行开启实时监听，无订阅时释放 watcher；首页读取轻量摘要，历史运行不各自常驻 watcher。退出不删除运行数据。
+
+首期为 macOS 无需管理员权限的本机用户级按需托管，使用当前用户域的 launchd 服务，不使用系统域或 sudo，不设置登录即启动或退出即无条件拉起。统一 CLI 提供 ensure/renew/release，负责并发启动去重与健康检查；意外崩溃后由下一次 ensure 恢复。若用户域托管受本机策略限制，应报告具体障碍，不自动提升权限或改用其他托管栈。其他平台需要独立托管适配。
+
+正式运行数据使用独立于 Skill 安装目录、候选工作树和 CODEX_HOME 的用户级固定数据根。所有正式 CLI 使用该数据根；开发测试使用隔离数据根，不自动进入正式运行列表。现有数据迁移需单独确认准确来源，不自动扫描或搬迁其他安装的数据。
+
+安装、升级与回滚由主人显式执行统一维护命令，普通 Agent 对话不得触发升级。升级前校验兼容性和构建产物，预检失败保留旧服务；允许切换时短暂断线并自动重连，不要求零停机。
+
+服务代码升级与账本迁移分离。代码升级只切换已验证的构建，健康检查失败恢复旧构建；会导致数据或写入方不兼容时预检阻止升级。数据迁移使用独立显式命令，在暂停相关写入、备份与校验后执行。旧目录导入遇到相同 run ID 但内容不同时拒绝覆盖。已有新写入时不得通过恢复旧备份盲目回滚。
+
+## 已有身份合同
+
+`run_id` 对应账本的 `orchestration_id`，标识一次编排运行；`control.owner_thread_id` 标识负责它的主会话。二者不可互换。
+
+计划版本由计划 ID 标识，`active_plan_id` 和 `execution_plan_id` 分别表达选择与执行事实。账本 `revision`、`schema_version` 和 `contract_version` 各有独立含义，不代替服务软件版本或 API 版本。
+
+## 数据目录与运行发现
+
+用户级根目录为 `~/.local/share/multi-task-flow/`，其中 `config/` 保存固定端口和服务配置，`data/runs/<run_id>/` 保存账本及运行资源，`releases/<build_id>/` 保存不可变构建，`state/` 保存实例身份、锁和租约。根目录不从调用方 CODEX_HOME 或工作树推导。
+
+正式 CLI 直接在统一数据根创建或访问运行，服务发现该目录下的运行；不递归扫描其他安装或项目目录。运行列表只是可重建的展示索引，不成为第二份账本。一个运行损坏或不兼容不能阻止其他运行展示。
+
+开发测试必须使用不同数据根、端口和实例身份，不读取正式凭据或自动加入正式列表。日志采用有界轮转，不记录登录凭据或完整敏感 URL；日志具体位置及限额可由实现配置，但不能无界增长。
+
+## 自定义视图
+
+一个 Web 服务、一个监听入口，通过 `/runs/<run_id>/` 区分编排。默认使用共享模板，保留每个运行的自定义 view，由同一服务提供该运行目录内的资源，不为自定义 view 启动另一个服务。
+
+自定义资源必须声明适用的 API 与前端合同；不兼容时提示并回退共享模板，不执行不兼容资源。旧 view 文件保留，缺少兼容声明时不能猜测兼容。继续限制路径与符号链接访问，禁止通过资源路由读取其他目录。
+
+所有正式运行属于同一本机用户信任范围，URL path 用于运行选择，不作为脚本安全隔离边界。
+
+## URL 与本地访问
+
+正式编排交付要求 Agent 按 `skills/multi-task-flow/SKILL.md` 的 Dashboard browser route 使用当前宿主可用的内置浏览器打开对应 run 页面。页面通过 SSE revision 事件和 heartbeat 重新取得完整快照；正常 ledger 修订保持同一页面和 URL 上下文即可显示新 revision。只有连接中断、服务重启或登录会话过期时才重新连接或导航，并明确显示 stale/disconnected 状态。
+
+使用固定 loopback 端口，首页列出所有正式运行；运行路径为 `/runs/<run_id>/`，指定计划使用 `?plan=<plan_id>`，默认计划省略该参数。端口冲突时明确报错，不自动改端口，也不接管其他进程。服务退出后须先调用 ensure 再访问旧链接，不另设常驻网页启动器。
+
+首次显式安装通过端口管理器选定可用高位端口并保存，之后启动显式申请该端口。配置保存固定端口偏好，端口注册表只保存运行期间的活动租约；停机释放活动租约，不宣称永久占用端口。端口只在显式维护时变更，并须报告对旧链接的影响。
+
+端口租约属于独立的用户级服务 scope，不属于任何 run 或候选工作树。使用统一的正式端口注册表，不能随着调用方 CODEX_HOME 改变注册表。启动在持锁状态下完成租约认领、监听与 PID 记录；退出只释放自身 PID 对应的活动租约，不清理调用方工作树或其他服务。
+
+仅监听 `127.0.0.1`，继续校验 Host/Origin。用户级持久凭据在重启与升级后保持，运行和计划链接不含凭据。CLI 提供一次性浏览器登录入口，登录后使用本地会话；首次登录或清除浏览器数据后需重新获取入口。凭据撤销与轮换由显式维护命令完成。一次性入口只用于授权，不是运行链接。
+
+## 版本兼容
+
+正式环境始终只有一个服务软件版本，不为旧任务启动另一个服务。服务公布构建身份、API 支持范围与可读 schema/contract 组合；首期支持当前与上一 API 主版本，历史账本通过明确支持的只读适配器展示。兼容矩阵需列举具体版本，不能只根据软件版本号推断数据可读性。
+
+不支持的运行单独显示原因，不影响其他运行。CLI 与服务不兼容时明确报错，不自动升级或修改账本。只读展示兼容不等于 CLI 可安全写入旧账本，写入仍须遵守对应数据合同。
+
+服务软件版本、构建 ID、API 主版本、前端合同、账本 schema/contract、账本 revision 和计划 ID 各自独立。API 支持范围只涵盖已发布的当前及上一主版本；首个 API 主版本不存在时不虚构上一版本。构建标识应能定位源码与实际发布产物，不能只报告候选工作树的 Git HEAD。
+
+Skill/CLI 更新与服务更新独立。ensure 对已安装构建执行兼容握手和启动复用，不现场构建、不安装依赖、不替换构建；服务未安装时报告维护入口。正式构建及其运行时依赖必须由维护命令验证，不依赖某个 Agent 的工作目录或临时环境。
+
+## 单例与租约并发约束
+
+启动、退出和维护使用用户级稳定实例锁；多个 ensure 竞争时仅一个负责启动，其他等待就绪并验证真实实例身份，不能以发现 PID 就视为健康。实例身份包含启动代次，旧实例的退出或租约释放不能修改新实例。
+
+空闲退出前在同一生命周期锁下重新检查有效租约并停止接收新租约，避免最后租约到期与新 ensure 并发导致错误退出。ensure 遇到退出中的实例等待退出后再启动；续期失败必须可见，不能宣称保活成功。睡眠后重新检查到期时间，不把无限期失联当作使用需求。
+
+服务重启或升级不重置持久凭据；有效使用租约在切换后保留原到期时间，不凭重启无限延长。浏览器通过断线重连恢复订阅；崩溃恢复依靠下一次 ensure，浏览器本身不拥有启动进程权限。
+
+Agent 使用租约、浏览器使用租约与端口活动租约是三种不同资源。release 只释放指定使用者的租约；单个 run 完成或归档不得停止共享服务，也不得释放其他使用者的租约。
+
+## 维护与迁移接口
+
+以下是语义命令合同，最终 CLI 拼写可按仓库入口统一。
+
+| 使用者 | 命令 | 行为 |
+| - | - | - |
+| Agent | ensure | 握手、启动或复用已安装实例，为指定主会话和运行续期，返回无凭据运行 URL |
+| Agent | renew / release | 续期或释放自身使用租约，不授予主控制权 |
+| Agent 或主人 | status / doctor | 显示实际构建、兼容范围、端口、健康、租约与诊断，不自动修复或升级 |
+| Agent 或主人 | login | 生成短时、单次使用的本地浏览器登录入口，不在普通状态输出泄露凭据 |
+| 主人显式维护 | install / upgrade / rollback | 安装托管定义、验证构建、切换或恢复服务代码，不隐式迁移账本 |
+| 主人显式维护 | import / migrate | 指定准确来源与目标，暂停相关写入，备份、校验并迁移数据 |
+| 主人显式维护 | credential rotate / revoke | 更新或撤销凭据及相关登录会话 |
+
+升级应预检现存数据、自定义视图和已登记调用方合同。无法预知的离线旧 CLI 在下次调用时仍须握手并独立拒绝不兼容操作，不宣称一次预检覆盖所有未来调用。维护切换与运行写入通过明确的协调边界避免竞态；真正改写账本的操作必须取得对应写锁。
+
+导入保留 run ID 和 plan ID，输出旧运行到新稳定 URL 的映射。相同 ID 且内容不同则拒绝；可证明相同的重复导入应幂等，不重复创建运行。不继续维持旧端口、旧进程或重定向服务，旧临时书签需替换。
+
+旧数据不自动删除。迁移必须隔离旧写入，旧来源封存为非活动备份或转为迁移指引，不允许保留两份可继续调度的权威账本。仅在新 CLI 里检查标记不足以约束旧二进制；无法确认旧写入已隔离时应拒绝迁移。具体路径变更、封存与停止旧进程都属于显式迁移目标，不能宽泛处理其他运行。
+
+## 验收场景
+
+- 两个项目、多个主会话并发 ensure，正式环境只产生一个监听进程，分别显示各自运行。
+- 单个 Agent 退出、释放或到期不影响其他有效租约；最后有效租约到期后服务退出且数据保留。
+- 浏览器续期可独立保活；暂停超过 TTL 后允许退出，页面恢复时明确显示连接状态。
+- 重启、升级后端口与运行 URL 不变；端口被外部占用时报告冲突，不换端口或接管进程。
+- 升级失败恢复旧构建；不兼容写入被拒绝，不以恢复旧备份覆盖新写入。
+- 旧计划、自定义 view 和不兼容运行分别按兼容合同展示，不相互阻塞。
+- 登录凭据不出现在运行链接、普通状态输出或日志；一次性入口不能重复兑换。
+- 数据导入不造成重复 run、覆盖冲突或两个可写权威来源。
+- 正式服务从任意工作树使用同一固定数据根；测试实例与正式实例隔离。
+
+## 现行合同的衔接
+
+现行服务绑定单个运行、端口与随机 token；长期 owner-facing URL 要求由 Agent/host 持有原生后台会话。新方案须对这一用户级正式服务新增明确的系统托管合同，以真实 launchd 实例与健康检查作为后台存续证据，不填写虚构的 agent_session；其他临时预览继续遵守原有合同。不能沿用逐运行退出时关闭共享进程的行为。
+
+数据当前默认位于安装 Skill 的 `data/runs/`。安装目录与候选工作树可能具有不同代码，实际服务必须有可查询的软件构建身份。此处记录迁移约束，不授权运行数据迁移或服务安装。
+
+后续实现需同步 multi-task-flow 的 Skill、主题 Spec 与数据/网页设计，以及 global-port-manager 和顶层 AGENTS 的用户级服务例外；不恢复已退役的通用服务管理栈。本文件记录已确认的访谈决策与实现约束，不是执行计划，也不替代现行运行入口。
+
+## 兼容升级与维护迁移
+
+所有保留 run 都参与读取兼容检查，归档、业务完成和租约分别表达不同事实。已有只读合同不要求可写；仅当前构建可写而目标不可写时，需对绑定完整源/目标构建与账本摘要的报告逐次确认。不可读、损坏及自定义 view 合同不兼容在停服前拒绝，确认不能绕过。安装无旧构建时只要求读取兼容；回滚同样重新检查现有数据。
+
+维护合同与 profile 迁移采用独立 check/apply CLI，保留原 owner，实际维护身份、主人批准引用和准确动作进入 request 审计。普通 main 权限不变，不要求恢复归档业务会话。主人暂停旧写入器后，维护锁再 run 锁内复核身份、revision、摘要及无 claimed/unknown 操作，完整备份后原子单次提交。先部署可读源/目标合同的 viewer，再迁移；合同先于独立 profile 迁移。配置组合仍通过 app-server 验证，不补造历史模型。合作锁不隔离同用户手工写入，批准引用不是独立认证。
+
+精确命令和恢复步骤见 Skill 的 `references/shared-viewer.md`；架构取舍见 ADR 0045。

package/toolkit/skills/docs/vendor/dot-codex/design/multi-task-flow/web-template.md

@@ -0,0 +1,161 @@
+# 任务编排网页模板方案
+
+本文描述新编排 Skill 的只读可视化模板。关联文档：[编排方案](orchestration.md)、[执行方案](execution.md)、[数据与脚本方案](data-and-scripts.md)。
+
+## 目标与边界
+
+让主人不必逐个打开 Agent 会话，即可理解编排结构、真实进度、等待原因、交付关系和下一步。页面展示账本提供的已知事实；它不是调度器，不提供合并、派发、审批、切割或直接编辑账本的按钮。唯一允许的服务端写入是明确选择主题时写入全局界面偏好。
+
+模板由 Skill 提供，每次编排生成独立的项目页面。主 Agent（main Agent） 可根据项目调整配色、布局、名称及补充信息，但依赖、阻塞、实际状态、数据更新时间和连接状态必须仍可辨认。共享模板不随单个项目的调整而改变。
+
+## 信息架构
+
+```text
+编排控制台
+├── 顶栏：主任务、项目、整体状态、账本更新时间、连接状态
+├── 概览：就绪 / 执行 / 阻塞 / 已集成 / 已收口，以及当前并发
+├── 视图切换
+│   ├── 依赖图：主任务、交付单元、贡献及后续任务、里程碑
+│   ├── 理论甘特图：指定计划版本与估时
+│   └── 实际甘特图：已发生的时间和等待
+├── 筛选：交付单元、状态、任务类型；搜索任务名或 ID
+└── 详情：目标、负责人会话、前驱后继、PR、要求、证据、阻塞
+```
+
+概览以实际账本事实计算；统计项须可追溯到可见任务，不把未开始、未知或等待当作成功。页面清楚区分“子 PR 已集成”“任务已收口”和“交付单元及主任务已完成”。用户能看到交付单元与其父 PR、任务与所属交付单元的关系，并能打开已核实可用的会话、PR 和 Markdown 要求链接。
+
+宽桌面参考布局（`W >= 1356px`）：
+
+```text
+项目名称 / 主任务                      数据版本 连接状态
+就绪 2    执行 3/3    阻塞 1    已集成 4    已收口 2
+────────────────────────────────────────────────────────
+依赖图 | 理论甘特图 | 实际甘特图      搜索  交付单元筛选  状态筛选
+─────────────────────────────────┬──────────────────────
+                                 │ 任务详情
+ 主任务开始 → 交付单元 A → 任务 A ─┐   │ 当前状态、所属交付单元
+                   → 任务 B ─┼→  │ 目标、依赖、证据
+ 主任务开始 → 交付单元 B → 验证任务 ┘   │ PR / 会话 / 要求文档
+                                 │ 阻塞原因、时间记录
+─────────────────────────────────┴──────────────────────
+```
+
+详情布局按 `.workspace` 的可用内容宽度 `W` 决定；不能只按浏览器外框宽度判断。固定详情栏需要满足 `W - 20px 间距 - 336px 详情栏 >= 1000px`，因此网格模式的最小 `W` 是 `1356px`。详情关闭时所有宽度都只显示主内容区；有选择且打开详情时，按照以下矩阵布局：
+
+尺寸契约必须区分外层轨道与嵌套内容：网格任务卡片的宽度最小为 `243px`、最大为 `360px`；中屏看板的交付单元列与网格任务卡片同宽，列内任务卡片扣除左右内边距和边框后自然更窄，范围为 `221px–338px`。中屏详情卡片使用绝对宽度边界：最小 `243px`，最大 `740px`。边界在设计时参考网格任务卡片的最小值 243px、最大值 360px 得出（上限为 2×360px+20px）；运行时不能根据当前卡片宽度重新计算上下限。宽桌面使用固定 `336px` 详情栏；中屏详情栏在固定的 243–740px 范围内吸收任务区余量，上限不代表默认宽度；窄屏详情改为横跨容器的底部抽屉，宽度为容器可用宽度（不再参与并排列宽），最大高度为 `82dvh`。打开或关闭详情不得改变任务卡片的宽度，只允许改变列数、换行或任务区滚动状态。
+
+中屏品字型共享一套 CSS 容器轨道。令工作区内容宽度为 `W`，卡片和工作区间距均为 `G=20px`，整行列数为 `N=floor((W+G)/(243px+G))`，卡片宽度为 `C=(W+G)/N-G`。使用 `.main` 的 `container-type:inline-size`、`100cqw`、`round(down, …)` 和 `calc()` 计算；中屏脚本不写内联宽度。详情关闭时使用 N 个 C 宽轨道；详情打开时，先预留详情绝对最小宽度 243px 和一个工作区间距，再尽可能放入完整任务轨道：`K=max(1,floor((W-243px)/(C+G)))`，左侧宽度为 `K×(C+G)−G`，右侧在绝对 243–740px 边界内吸收剩余宽度。不能为追求更宽详情而少放一列本来能容纳的任务。两种状态的 C 完全相同，网格任务区不存在不足一列的尾部空白；详情宽度不固定为当前卡片的一倍或两倍。在当前均分轨道布局下，余量恰好可能与一条轨道接近，这是空间分配的结果，并非详情的相对尺寸约束。
+
+看板模式复用的是外层轨道宽度 C，而非内嵌任务卡片宽度。每个交付单元列宽为 C，与网格任务卡片完全相同；列内任务卡片使用容器自然宽度 `C − 22px`（左右内边距各 10px、边框各 1px），不单独设置最小宽度把列撑大。列间距为 20px，横向不再叠加看板容器内边距；使用固定的 `grid-auto-columns`，不使用会随左侧任务区收缩的 `minmax()` 轨道。详情打开后看板列和内部任务卡片都不得变宽或变窄；空间不足时仅看板容器横向滚动。中屏根滚动容器使用 `scrollbar-gutter: stable`，避免详情高度或布局切换引起纵向滚动条显隐，进而改变容器宽度和卡片列数。
+
+浏览器验收需测量实际 DOM，而非只检查 CSS 字符串或自比较公式。打开/关闭详情后卡片宽度差应小于 1px；网格任务首行最右卡片与任务容器右边界差应小于 1px；看板所有交付单元列宽差也应小于 1px；同一视口、同一详情状态下，看板交付单元列必须与网格任务卡片同宽（差小于 1px），内嵌任务卡片比交付单元列小 22px（差小于 1px）。可见列数能容纳全部交付单元时不应产生横向滚动；交付单元数超过可见轨道数时仅看板内部横向滚动，不得使整页横向溢出；详情宽度应在绝对 243–740px 内；若再增加一列任务及其间距后仍能为详情保留 243px，则当前布局不合格，不能默认把详情扩成双列宽。
+
+| 可用内容宽度 / 视口档位 | 主内容与图表 | 详情状态 | 任务区与顶部控件 |
+| - | - | - | - |
+| **宽桌面双栏**：`W >= 1356px`（通常约 `>=1445px` 视口） | 主内容与详情使用两列网格；主列至少 `1000px`，图表不被详情压缩到阈值以下 | 右侧固定 `336px` inspector，间距 `20px`；详情关闭时主内容占满，详情打开后才插入右栏 | 桌面无详情时网格卡片按 `243px` 最小单元自适应铺满；详情打开后切换为固定 `243px` 轨道，按 1 倍或 2 倍等整数个卡片单元换行 |
+| **中屏品字型**：`768px <= W < 1356px`，通常对应 `768px–1444px` 视口 | 图表区域横跨整行；图表下方再分为任务与详情两列，图表宽度不被详情占用 | 详情位于下方右列，任务位于下方左列；未选中时不保留详情列，任务容器占满；详情打开后才增加右列 | 看板按交付单元生成固定宽度列，左对齐并允许内部横向滚动；网格显隐详情均使用相同的容器计算轨道 C；打开详情后在保留详情至少 243px 的条件下最大化左侧完整列数，详情以绝对 243–740px 边界吸收余量；筛选器允许换行 |
+| **窄屏底部抽屉**：视口 `<768px` | 单列滚动；图表按容器宽度渲染，不能与详情并排 | 底部 drawer，宽度为容器可用宽度，最大高度 `82dvh`，带遮罩、抓手、关闭按钮和 Escape/背景关闭 | 阶段与计划信息两列；状态摘要两列并将最后一项跨满；任务看板横向滚动，搜索和筛选器分行 |
+
+中屏详情位于图表下方的右列，与左侧任务列组成品字型结构；它不参与图表行的宽度计算。支持 hover 的细指针在未打开详情时保留约 250ms 悬浮预览；触屏、键盘和不支持 hover 的输入不依赖悬浮预览。临时详情面板支持 Escape、背景点击、焦点移入和关闭后焦点恢复；语义列表是键盘和辅助技术的事实来源。点击节点、列表项或时间条更新同一详情；筛选不会改变账本，也不会清除仍然有效但被隐藏的详情选择。视觉上以中性色工作台为底，交付单元区分使用蓝、青、赭等可辨识色，阻塞、进行中和完成另用文字和图标表达，不依赖单一色相。
+
+当前模板采用 data-terminal 开发者控制台：顶栏承载产品标识、仓库范围、连接状态、数据时间、当前计划版本和主题选择；版本菜单中的每个版本都是带 `href` 的超链接，普通选择更新 URL，浏览器新窗口或新标签沿用原生链接行为，当前版本作为默认值时省略 `plan` 参数。状态摘要以分隔式数据表面呈现。视图工作区使用技术标签、下划线 tabs、紧凑筛选、搜索和时间线/依赖图表面；右侧 inspector 用结构化字段承载原生会话、PR、需求和依赖事实。产品脸来自任务编排的蓝色选中线、Public Sans 正文和 IBM Plex Mono 的 ID/计数；颜色只落在数据和状态标记上，不装饰 chrome。窄屏详情改为带遮罩的底部抽屉，并保留抓手、关闭按钮和焦点恢复；浅色与深色主题共享同一层级和状态语义。模板不使用渐变、玻璃拟态、装饰性光球或营销式首屏。
+
+### 阶段与可分享视图状态
+
+阶段由任务真实开始事实派生：当所有任务的 `started_at` 都为空时为“编排阶段”，只要任一任务存在 `started_at` 就转为“执行阶段”且不回退。首次没有 URL `tab` 时，编排阶段默认依赖图，执行阶段默认实际进度；实时刷新中的阶段转移保留用户已选标签、筛选、选择、滚动和焦点，只显示提示并提供跳转入口。
+
+- URL 是排查上下文的分享载体，不是运行数据存储。规范参数为 `tab`、`layout`（`board` 为默认值，`grid` 可分享）、`q`、`group`、`state`、`kind`、`plan`、`selected`（`task:<id>` 或 `group:<id>`）、`detail`、`plannedStart`、`plannedEnd`、`actualStart`、`actualEnd`。图表缩放属于临时界面状态，不写入 URL；默认值省略，变化使用 `history.replaceState`，浏览器前进后退通过 `popstate` 恢复；无效 ID、非法时间值忽略。选中对象即使被筛选隐藏仍保留，只有对象删除或 ID 失效才清除。任务数据、凭据和服务 token 永不写入 URL。
+
+主题是唯一的全局界面偏好，存放于全局数据根的 `ui-preferences.json`，不使用 localStorage、cookie、浏览器数据库、账本或 Worktree。文件 schema 为 `{ "schema_version": 1, "theme": "system" | "light" | "dark" }`，由独占 OS lock、`0600` 文件权限和 atomic replace 保护；文件缺失或损坏仅回退到 `system`，不会自动修复。
+
+## 依赖图
+
+图包含主任务开始和结束、各交付单元开始和结束、贡献任务、父 PR 合并、CI、按需发布、部署和验证等节点，以及需要展示的 follow PR。边表达具体前驱条件，不因图形分组隐含组与交付单元之间的依赖。
+
+交付单元内任务共享颜色或其他标识，并配有文本标签；颜色不是唯一信息来源。节点展示名称、类型与当前状态，点击或键盘选中可查看详情和前驱后继。支持缩放、平移、定位当前任务和聚焦依赖路径；节点较多时可筛选或折叠交付单元，同时保留所选节点的关键依赖提示。动态切割后显示当前分组，并可查看计划中保留的历史归属。
+
+依赖图使用 Cytoscape.js 和 `cytoscape-dagre` 的有向图布局；节点在同一平面布局，以颜色及文字表达交付单元归属，避免把视觉分组当作依赖。依赖库在本机打包。Cytoscape 使用画布渲染，因此同时提供基于同一节点数据的键盘可操作列表；图边、交付单元与动态切割的可读性由验收验证。参考 [Cytoscape Dagre 官方仓库](https://github.com/cytoscape/cytoscape.js-dagre)。
+
+依赖图与时间轴统一采用显式缩放手势：普通滚轮不缩放并继续驱动页面滚动，只有 `Ctrl` 加滚轮才缩放；拖拽平移与工具栏缩放按钮继续可用。
+
+## 两张甘特图
+
+|  | 理论安排 | 实际进度 |
+| - | - | - |
+| 数据 | 已批准计划或选择的计划版本、依赖、估时及可信度 | 实际开始、等待、恢复和结束事件 |
+| 日期 | 基于明确的起点、耗时和并发条件计算；未知则显示未知 | 仅显示已发生的时间；未开始不伪造起止时间 |
+| 变化 | 保留原计划，可切换调整后的计划版本 | 随事件更新，不覆盖历史事实 |
+| 展示 | 交付单元归属、依赖和关键等待；估算不是承诺 | 交付单元归属、运行与等待区间；缺失事件标为未知 |
+
+两张图共享任务身份、分组和筛选，但不把预计时间写进实际记录。任务状态变化与时间戳采用账本事实；浏览器本地时间显示时提供时区，数据存储使用明确的时间基准。动态切割后，实际图应保留任务在不同交付单元下的时间和归属变化，不重写历史。
+
+实际图中正在执行但尚无结束时间的区间可以延伸至浏览器当前时间，并明确标注“进行中”；该末端只是显示坐标，不能写入完成时间。未知起点或无时间证据的任务放在“时间未知”列表，不绘制虚构的时间条。
+
+两张甘特图使用 `vis-timeline` 的分组和时间区间能力，统一设置 `editable: false`；无确定起点的任务列在未知时间区域，不向组件传入虚构日期。每个任务一行，使用同一组颜色及文字标签；运行和等待以不同区间样式表达。依赖详情通过任务选择与侧栏呈现，不依赖组件自动生成依赖箭头。参考 [vis-timeline 官方接口](https://github.com/visjs/vis-timeline/blob/master/docs/timeline/index.html)。
+
+时间轴手势必须保持可预期：普通滚轮回到页面滚动，不缩放也不抢占页面滚动；只有按住 `Ctrl` 再滚轮才缩放时间范围，并以指针所在时间为中心。主按钮拖拽继续负责平移，工具栏缩放与适应范围按钮作为显式替代入口。
+
+## 状态与交互
+
+- **加载中**：保留页面结构并显示加载状态；不得显示凭空推断的数据。
+- **空计划**：显示尚无任务的状态，不绘制假的示例数据。
+- **等待或阻塞**：列出原因、等待对象、当前会话链接和最近更新时间；不自动把阻塞推送给主 Agent（main Agent）。
+- **连接中断**：保留最后一次已加载的视图，明确标为过期并显示最后更新时间；重连后以最新版本替换。
+- **数据不完整或损坏**：展示可定位的错误及恢复入口信息；不得将未知当作通过，也不得在页面内自行修复账本。
+- **长名称与大图**：名称可换行、截断并提供完整详情；在窄屏优先展示列表和详情，图可平移或切换视图，不能相互遮挡。
+- **可访问性**：键盘可达的视图切换、筛选和节点详情；状态有文字与图标，控件有可访问名称，满足正常对比度和缩放需求。
+
+## 技术结构
+
+```text
+<Skill 模板资源>/
+├── index.html
+├── app.js                    # 页面状态、筛选、详情和连接状态
+├── graph.js                  # 依赖图布局与交互
+├── timeline.js               # 理论与实际甘特图
+└── app.css                   # 编译后的 Tailwind + daisyUI 与项目样式
+```
+
+使用原生 TypeScript 模块编译为浏览器 JavaScript，不引入 React 或其他前端框架；数据使用 Cytoscape.js、`cytoscape-dagre`、`vis-timeline` 的公开接口传入。构建时使用 Bun 打包脚本，Tailwind CSS 与 daisyUI 编译为本地 CSS，依赖版本及构建锁文件随 Skill 维护。文件划分允许构建时合并，运行时为一个 HTML、少量 JS 和 CSS，不依赖在线 CDN。主 Agent（main Agent） 按项目生成或调整该编排专属页面，不修改运行中的共享模板。
+
+本机 Bun 服务提供初始只读视图和变更推送；接口、版本和安全约束见本文“服务接口与更新”。服务重连时重新获取完整、带账本版本的视图，不能只靠可能丢失的增量。浏览器不得直接修改账本；主题偏好使用同一 tokenized loopback 服务的专用接口。
+
+**会话链接的验收约束**：页面使用 Codex 原生支持的 `codex://threads/<thread_id>` 形式，并在当前浏览上下文中导航，不强制新窗口。原生会话锚点只设置 `href`，不添加 `target` 或 `rel`，以保持与 Codex 页面原生协议桥接的兼容性；HTTPS 外部链接仍使用 `rel="noopener noreferrer"`。提交的演示数据使用本机已存在的真实会话 ID，并在 `examples/orchestration-viewer/link-verification.json` 中保留一次性原生导航结果；当前候选复用该证据，不因页面未变而重复点击。浏览器到桌面应用的协议桥接由 Codex 宿主负责，不作为本 Skill 的独立硬门禁，也不把原生导航证据表述为浏览器点击证据。
+
+## 服务接口与更新
+
+本机服务由 `bun run <skill>/scripts/serve.ts --run <id> --scope-id <scope> --service <service> --port <leased-port> [--agent-session <host-provided-id>]` 启动，先申请当前编排服务的端口租约，只绑定 `127.0.0.1`。脚本登记自身 PID、心跳并在停止时仅释放自己的服务租约；Agent/host 负责创建和保留真正的原生后台会话，Skill 不得从进程或可见终端猜测会话。项目定制的资源放在该 run 的 `view/`，使用 `--custom-view` 加载。对外展示的 URL 必须同时对应活动租约和仍存活的宿主 native background session；没有受支持的宿主后台路径时只能用于当前回合验证。
+
+服务启动时生成至少 128 位随机访问令牌，URL 前缀为 `/s/<token>/`；令牌不写进账本、日志或项目文件。只有携带有效前缀的请求可读取页面和数据；严格检查 Host 为当前绑定的 `127.0.0.1:<port>`，拒绝非本机连接和跨源请求。响应设置 `Cache-Control: no-store`、`Referrer-Policy: no-referrer`、`X-Content-Type-Options: nosniff`，所有显示的任务文本按文本处理，禁止注入 HTML。令牌和本机服务并不提供跨用户的强身份隔离。
+
+| 方法与相对路径 | 响应 | 规则 |
+| - | - | - |
+| `GET /` | 编排专用 HTML | 只读；本地脚本和样式使用同令牌前缀 |
+| `GET /assets/<name>` | 打包后的 JS 或 CSS | 仅允许模板声明的静态文件，不接受任意路径 |
+| `GET /api/view?plan=<id>` | `{ "revision": 12, "generated_at": "...Z", "active_plan_id": "plan-a", "view": { ... } }` | 快照来自账本一致读取；计划 ID 无效返回 `404`；`active_plan_id` 用于省略当前计划而保留历史计划 URL 状态 |
+| `GET /api/events` | `text/event-stream` | 连接时发送 `revision`，之后发送变更；事件只携带 revision，页面重新获取完整视图 |
+| `GET /api/document/<id>` | 经登记的 Markdown 文本 | 仅允许账本登记且在该 run 的 `requirements/` 中的常规文件；拒绝目录穿越和符号链接越界 |
+| `GET /api/preferences` | `{ "schema_version": 1, "theme": "system" }` | 读取全局 UI 偏好；缺失或损坏回退 `system` |
+| `POST /api/preferences` | schema-1 偏好 | 只接受精确 `{ "theme": "system" | "light" | "dark" }`；不触碰账本 |
+| 其他方法或路径 | `404` 或 `405` | 无账本写接口、执行接口或通用文件代理 |
+
+`view` 包含 `orchestration`、`groups`、`nodes`、`edges`、`tasks`、`follow_prs`、`planned_intervals`、`actual_intervals`、`actual_milestones`、`plan_warnings` 和 `warnings`，各项使用账本稳定 ID 关联；不包含访问令牌或凭据。`plan_warnings` 是当前选定计划的只读合同告警，例如缺少计划时间基线时说明理论安排无法计算；它不改变 `planned_intervals` 的未知值。`tasks[].latest_agent_output` 来自绑定对话的独立只读投影，`latest_output` 仅保留为同源文本兼容字段，不再读取账本事件。三处输出使用 `textContent`，仅在展示层截断，详情保留语义换行。PR HTTPS URL 按仓库主机校验，文档路径由服务构造；已知会话提供链接，实际跳转结果由验收记录。外部链接使用 `rel="noopener noreferrer"`。
+
+服务监听 run 目录的账本原子替换事件并推送 revision，客户端收到后重新取完整快照，只应用 revision 不低于当前值的响应；初始连接及每次重连均先取完整快照。SSE 心跳同时核对账本 revision，以补偿可能丢失的文件通知；连接或目录监听异常时显示“连接中断 / 数据可能过期”及最后核验时间。服务的版本核对不查询 Agent，也不代替关键操作前的平台核实。不得把“服务器在线”显示为“平台事实已核实”。
+
+如果页面脚本经过主 Agent（main Agent） 项目化修改，仍须满足上述只读接口、安全约束、版本检查和关键状态展示。页面代码不能改变服务的静态路径白名单或绕过令牌检查。
+
+## 验收场景
+
+1. 示例包含两个交付单元、并行任务、跨交付单元里程碑依赖、阻塞、后续验证和 follow PR；图中的关系与账本一致。
+2. 切割后，原交付单元与下一交付单元、实际已合入和未合入任务、父 PR 和任务会话归属正确更新。
+3. 实际图仅显示已有时间，未知估时或未开始任务不会显示成已完成；两个计划版本可比较。
+4. 同时打开两个页面，记账后均能更新；断线期间明确过期，重连后与当前账本一致。
+5. 桌面和手机视口中名称、图、工具栏、详情和状态不遮挡；键盘可操作，颜色与文字共同表达状态。
+6. 对话、PR 和要求文档链接在真实运行环境中逐一验证；不可用或尚未创建的目标明确显示为不可用，不生成猜测链接。
+
+任务区域标题与对象布局切换共用一行，标题靠左，任务数量和看板/网格按钮靠右；看板模式放在“任务”标题行，网格模式放在最上方的“交付单元”标题行。“交付单元”标题右侧不重复显示交付单元数量，不保留独立的布局工具栏行。切换布局移动同一个控件节点，保留按钮事件与焦点。
+
+对象布局的两个图标按钮在鼠标悬停和键盘聚焦时展示说明 tooltip：看板为“看板布局：按组分列展示任务”，网格为“网格布局：平铺展示任务”。提示通过 `aria-describedby` 关联对应按钮，不参与标题行尺寸计算。
+
+最新输出通过 `agent-output` SSE 推送独立快照（`output_epoch`、`output_revision`、`outputs`）；`api/view` 同时提供相同版本和投影。客户端拒绝旧版本及已退休的服务 epoch，只局部修改输出 DOM。任务重绑清空旧内容；断线重连按 1、2、4 秒至最多 30 秒退避。连接正常且没有消息不标记过期。时长字段只显示纯时间，任务卡片不再显示“当前用时”标签，执行状态单独表达。