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

package/toolkit/skills/docs/vendor/dot-codex/adr/0036-task-orchestration-dashboard-experience.md

@@ -0,0 +1,77 @@
+# ADR 0036: Task Orchestration Dashboard Experience
+
+- Status: Superseded
+- Superseded by: `docs/adr/0041-task-orchestration-dashboard-experience.md`
+- Date: 2026-10-31
+- Related: `docs/adr/0035-task-orchestration-ledger.md`, `docs/specs/multi-task-flow/SPEC.md`
+
+## Context
+
+The task-orchestration dashboard serves two different owner jobs. Before any real task starts, the owner primarily checks whether the dependency plan is sound. After execution starts, the owner primarily follows progress, blockers and integration state. The dashboard must make that change of emphasis visible without introducing another source of orchestration state or interrupting a live investigation.
+
+The existing dashboard is a read-only projection of the authoritative ledger. It already exposes the dependency graph, planned and actual timelines, filters, details and native conversation or pull request links. The experience decision therefore governs presentation, interaction and durable UI preferences while preserving the existing data and link contracts.
+
+## Decision
+
+### Phase-aware presentation
+
+Derive one monotonic `编排展示阶段` from the run data:
+
+- `planning` remains active until a real task has an actual start fact.
+- `execution` begins when any real task has started and never reverts.
+- A `starting` state or dispatch claim without an actual start fact does not trigger the transition.
+- Selecting a plan version does not change the run phase.
+
+Keep the existing graph, planned and actual views rather than adding a user- controlled phase mode. On an initial load, planning opens on the dependency graph and execution opens on actual progress. If a live page crosses the phase boundary, retain the current tab, filters, selection, scroll position and focus; show a non-blocking notice with an entry point to actual progress.
+
+Planning emphasizes the dependency graph, planned timeline, readiness and blockers. Execution emphasizes the actual timeline, running state, blockers and integrated work. Neither phase hides the other phase's authoritative data, and the summary uses existing ledger fields rather than inferred completion or remaining-time metrics.
+
+### Workspace and responsive details
+
+Use a calm developer-workspace treatment: neutral chrome, a restrained framed-sheet surface, clear product identity and data-led status colour. Do not add a marketing hero, generic KPI card grid, or permanent application navigation that competes with the orchestration workspace.
+
+Use the following width contract, measured against the `.workspace` content width `W` rather than the browser's outer width:
+
+| Width | Layout contract |
+| - | - |
+| **宽桌面双栏**：`W >= 1356px` | A selected open detail uses a `336px` right inspector with a `20px` gap; the graph/main column retains at least `1000px`. |
+| **中屏品字型**：`768px <= W < 1356px`, usually `768px-1444px` viewport | The graph/view spans the full first row. The second row places tasks on the left and selected details on the right with asymmetric widths; details do not reduce graph width and disappear when there is no selection. At `768px-1119px`, task cards use two columns and controls may wrap. |
+| **窄屏底部抽屉**：Viewport `<768px` | The workspace is one column. Selected details use a bottom drawer capped at `82dvh`; plan and summary surfaces become two-column, and task cards remain horizontally scrollable. |
+
+Closing or clearing the selection removes the detail surface and leaves the main column full width at every band. A fine hovering pointer may show a 250ms preview when no committed detail is open; touch, keyboard and other non-hovering input remain selection-driven. Temporary surfaces support close, `Escape` and backdrop dismissal, and restore the originating focus and scroll position when closed. Selecting another item while a temporary surface is open updates that surface rather than closing it.
+
+The wide detail pane keeps a valid `详情选择` even when a filter hides the object. It clears only when the object is removed or its ID becomes invalid.
+
+Timeline interaction is explicit: ordinary wheel input must not zoom or consume page scrolling; only `Ctrl` + wheel zooms around the pointer. Timeline pan remains available through primary-button drag, and the toolbar buttons remain available for users who do not use wheel gestures.
+
+### Selection, accessibility and motion
+
+Clicking or keyboard-selecting an object commits the detail selection. A fine pointer may show a short, approximately 250ms `详情预览` on graph or timeline objects, but the preview has no actions and never replaces the committed selection. Lists only highlight on hover; touch and keyboard interaction do not depend on hover.
+
+The semantic task and group lists are the complete keyboard and assistive- technology source of truth beside the visual graph. Graph nodes do not create a second node-by-node tab sequence. Temporary detail sheets and drawers move focus into the surface, constrain focus while open, and restore focus on close; the persistent wide pane does not trap focus. Status is conveyed through text and icons, not colour alone, and reduced-motion preferences disable panel, layout and refresh animations.
+
+Task cards and details may show two direct runtime facts already present in the ledger projection: current duration from recorded start/finish timestamps and the latest owner-facing Agent output. Output is projected only from explicit `latest_output`, `assistant_output`, `agent_output`, or assistant-role `message` fields in an event associated with that task. Missing output stays empty; planned output, arbitrary event fields and inferred text are never displayed.
+
+Live refresh preserves the current view context and never auto-scrolls or auto-opens a new object. Keep the last valid snapshot during stale or disconnected states, display connection state and data time, and never replace unknown values with zero. A first-load failure has an explicit error state; reconnection refreshes the projection.
+
+### URL view state
+
+Persist shareable dashboard context in URL query parameters as `URL 视图状态`. The state includes the selected tab, search text, filters, selected plan, selected task or group, detail expansion, graph zoom and timeline window. Defaults are omitted from the canonical URL. Page load and browser back/forward navigation restore valid parameters; unknown or invalid IDs are ignored without blocking the dashboard. URL state contains only stable identifiers and view values, never task data, credentials or service tokens.
+
+URL view state is not written to browser storage, the ledger or the global preference file. Theme is deliberately separate: it is the only current `全局界面偏好`, stored as `ui-preferences.json` under the task-orchestration Skill's global data directory. The preference file includes a schema version and `system`, `light` or `dark` theme value, uses the existing lock and atomic replacement conventions, applies immediately, and falls back to system theme when missing or unreadable.
+
+## Consequences
+
+The dashboard supports both plan review and live execution monitoring without forking the ledger contract or making the owner change modes manually. A shared URL can reproduce the relevant debugging context for another Agent, while global theme preference survives page and Worktree changes without polluting shareable links or orchestration state.
+
+Responsive details require explicit focus restoration and separate wide, medium and narrow interaction tests. The graph remains visually useful while the semantic lists provide a stable accessibility and keyboard contract.
+
+Graph and timeline canvases use the same wheel contract: ordinary wheel input continues page scrolling, while `Ctrl` + wheel is required for viewport zoom. Primary-button drag remains the pan gesture where the underlying view supports it, and explicit zoom controls remain available.
+
+## Rejected Alternatives
+
+- Add a manually switchable planning/execution mode: rejected because the phase is a fact of the run and a second mode can contradict the ledger.
+- Force the live page to jump to actual progress at the phase boundary: rejected because it steals the owner's current investigation context.
+- Persist all view controls in browser storage or the ledger: rejected because it prevents reliable sharing and mixes UI state with authoritative run data.
+- Add a second dashboard state store: rejected because the ledger remains the only orchestration source of truth.
+- Make hover, colour, or the graph canvas the only interaction path: rejected because touch, keyboard and assistive-technology workflows need equivalent semantic controls.

package/toolkit/skills/docs/vendor/dot-codex/adr/0037-dev-plan-multi-task-flow-routing.md

@@ -0,0 +1,20 @@
+# ADR 0037: Route Multi-task Flow Through Dev-plan
+
+- Status: Superseded by [0040: Keep Dev-plan Standalone and Move Its Implementation to TypeScript](0040-dev-plan-standalone-typescript-finalizer.md)
+- Related: `docs/adr/0035-task-orchestration-ledger.md`
+
+## Context
+
+The repository has an active `$multi-task-flow` coordinator with a dependency graph, runtime ledger, task conversations, child PRs, and parent-PR closeout. Treating it as outside `dev-plan` routing makes a plan lose the very facts that the coordinator needs to start safely and encourages a silent downgrade to one direct task. The retired `wave-thread` route is a compatibility concern, but it is not the same runtime model.
+
+## Decision
+
+Register `multi-task-flow` as an active top-level `flow_type` in `$dev-plan`. The raw plan binds exactly one top-level `$multi-task-flow` skill, preserves at least two task nodes and explicit dependency, ownership, and acceptance facts, and is rejected when it collapses to a single direct `main-agent` task.
+
+Reuse the existing canonical v2 `batch -> wave -> task` plan syntax as the owner-facing projection format. For multi-task flow, waves are display and dispatch cohorts; the runtime ledger's explicit dependency graph is authoritative after approval. A task-local `$fast-flow` may run the task's direct PR stages without becoming another top-level flow or taking parent closeout ownership.
+
+The approved plan crosses into runtime through a transient bridge source and a `dev_plan_handoff` envelope persisted on the initial plan revision. The bridge receives the owner-supplied opaque raw-plan digest, derives the exact task IDs from the already parsed canonical plan, computes the acceptance digest, and attaches the envelope in memory before `init`; it does not persist a second planning artifact or reparse Markdown. Runtime initialization rejects missing or mismatched bindings before creating the ledger.
+
+## Consequences
+
+`dev-plan` routing, shell contract checks, TypeScript validation, projection, and fixtures must all recognize the active multi-task route. Historical `wave-thread` Markdown remains rejected while historical JSONL remains replayable. There is one plan-to-ledger handoff and one runtime ledger, so the owner-facing plan and runtime state do not form competing coordination systems. The raw-plan digest remains an owner-facing identity; runtime verifies the provided digest shape and the complete structural mapping rather than silently re-parsing Markdown during ledger creation. Owned-surface comparison is lexical and repository-relative; runtime does not resolve host filesystem case-folding or symlink aliases. The approval boundary must provide canonical repository-relative paths when host-equivalent aliases matter.

package/toolkit/skills/docs/vendor/dot-codex/adr/0038-direct-review-terra-profile.md

@@ -0,0 +1,27 @@
+# ADR 0038: Direct Review Terra Profile
+
+- Status: Accepted
+- Date: 2026-11-02
+- Supersedes: Direct Review portion of [0032 Flow-Scoped Model Profile Allowlists](0032-flow-scoped-model-profile-allowlists.md)
+- Related: `docs/specs/workflow-agent-model-selection/SPEC.md`
+
+## Context
+
+The direct-review policy needs a higher-effort profile for special and high-risk lanes. The previous fifth and sixth profiles both used `gpt-6.1-sol`, which did not provide the requested model/effort separation for those lanes.
+
+## Decision
+
+Keep the Code Review allowlist ordered and lane-local, changing only its final two profiles:
+
+1. `gpt-6-luna + high`
+2. `gpt-6-luna + max`
+3. `gpt-5.6-luna + xhigh`
+4. `gpt-5.6-luna + max`
+5. `gpt-6.1-terra + xhigh`
+6. `gpt-6.1-sol + medium`
+
+The runtime direct-review capability table and autonomous model set include `gpt-6.1-terra + xhigh`. Owner-specified complete model/effort overrides keep their existing exact-forwarding behavior.
+
+## Consequences
+
+Special and high-risk review selection now distinguishes the Terra xhigh and Sol medium profiles. The active workflow Specs, runtime policy, tests, and review contract must retain the same ordered list.

package/toolkit/skills/docs/vendor/dot-codex/adr/0039-fresh-dispatch-title-contract.md

@@ -0,0 +1,13 @@
+# ADR 0039: Fresh Dispatch Task Title Contract
+
+- Status: Accepted
+- Date: 2026-11-02
+- Related: `skills/fresh-thread-dispatch/SKILL.md`, `skills/fresh-thread-dispatch/references/handoff-envelope.md`
+
+Fresh dispatch currently omits the native `create_thread.title` field when the owner did not provide a title. The platform then derives a user-facing title from the structured handoff prompt, exposing the `Goal` protocol label and copying a long task sentence. This makes the task list harder to scan and couples user-facing metadata to the prompt envelope.
+
+Resolve and pass a task title explicitly for every fresh dispatch. An explicit owner title has priority and may receive only whitespace normalization; an overlong explicit title must not be silently truncated. Otherwise derive the title only from the transferred task intent, using the primary outcome rather than the full sequence of investigation, implementation, and verification steps. Use the concise `action + subject + decision boundary` form, target no more than 24 Unicode code points, and enforce a 32-code-point hard limit for generated titles. Remove protocol labels, skill references, URLs, paths, acceptance details, and execution context from the generated result. If no meaningful title can be derived, use `移交任务`.
+
+The full handoff prompt remains structured and complete; title generation must not parse or infer from `Verified context`, `Scope and constraints`, or `Execution and stop condition`. The request builder only validates and forwards the resolved title. The rule applies only to fresh dispatch and does not alter other thread-creation or existing-thread title behavior.
+
+Examples include `审查 CONSOLE_RUNTIME 必要性`, `设计运行时配置下发`, and `修复移动端发布布局`. The implementation must test explicit-title forwarding, Goal-based derivation, protocol and metadata exclusion, semantic shortening, the `移交任务` fallback, and preservation of ledger metadata boundaries.

package/toolkit/skills/docs/vendor/dot-codex/adr/0040-dev-plan-standalone-typescript-finalizer.md

@@ -0,0 +1,25 @@
+# ADR 0040: Keep Dev-plan Standalone and Move Its Implementation to TypeScript
+
+- Status: Accepted
+- Supersedes: [0037: Route Multi-task Flow Through Dev-plan](0037-dev-plan-multi-task-flow-routing.md)
+- Related: [0032: One Finalization Gate for Dev-plan Owner Review](0032-dev-plan-single-finalization-gate.md), [0033: Bun + TypeScript Script Runtime](0033-bun-typescript-script-runtime.md), [0034: Trusted Bun CLI Launch Boundary](0034-bun-cli-launch-boundary.md)
+
+## Context
+
+`$dev-plan` is a temporary plan validation and owner-review capability. It must not become a runtime coordinator or exchange machine contracts with `$multi-task-flow`. The current routing and handoff design binds the two Skills and lets runtime initialization accept a plan-shaped input without proving that the standalone dev-plan finalizer passed it. The existing Bun launch boundary also requires a trusted pre-main environment scrub for sensitive candidate-input CLIs.
+
+## Decision
+
+`$dev-plan` is a standalone flow. Its only public operation is its own TypeScript finalizer, which runs the canonical dev-plan checker, derives the owner-facing projection from the same parsed facts, and returns exactly one `pass` or `reject` result. A passing result emits one transient `<proposed_plan>` and then stops.
+
+`$dev-plan` MUST NOT invoke, import, route to, or exchange handoff fields with `$multi-task-flow`. It MUST NOT create or update a runtime ledger, task conversation, digest, handoff envelope, dashboard state, or other execution artifact.
+
+`$multi-task-flow` remains an independent Skill with its own input contract and runtime validation. Historical records that contain the old binding remain read-only compatibility data; new runs MUST NOT create a dev-plan binding.
+
+All checker, parser, projection, and finalizer logic moves to TypeScript running under the pinned Bun runtime. A minimal `plan-cli.sh` launcher remains only as the trusted boundary required by ADR 0034: it clears `BUN_OPTIONS` and `NODE_OPTIONS`, forwards arguments and stdin, and `exec`s the TypeScript entrypoint. It contains no dev-plan logic.
+
+The old shell checker and shell finalizer implementations are removed. Documentation and tests use the TypeScript finalizer as the canonical interface, with the launcher treated as a security boundary rather than a second implementation.
+
+## Consequences
+
+The dev-plan contract, checker, projection, and tests have one implementation language and one finalization boundary. Multi-task runtime changes cannot silently alter dev-plan behavior, and a successful dev-plan response cannot start runtime execution. The repository must remove active dev-plan/multi-task handoff references, migrate shell fixtures to TypeScript, and retain hostile-environment coverage for the thin launcher.

package/toolkit/skills/docs/vendor/dot-codex/adr/0040-phase-aware-plan-revision-audit.md

@@ -0,0 +1,35 @@
+---
+status: accepted
+---
+
+# ADR 0039：阶段感知的计划修订与审计
+
+## 背景
+
+Multi Task Flow 需要允许实现开始前合理地调整任务图，也需要在实现开始后保留可追溯的修改理由。相同的依赖删除在两个阶段的风险不同：把它们视为同一种修改会让设计阶段过度繁琐，或让实现阶段可以静默改变执行图。
+
+## 决策
+
+将 `execution_phase` 与 `plan_lifecycle` 分开建模。阶段在首个真实 `task_started` 事件前为 `planning`，之后永久为 `implementation`。dispatch、会话创建、`starting` 和计划选择不改变阶段。
+
+每次计划内容修订都创建不可变版本和规范化 diff。设计阶段允许省略理由，但必须保存 diff 并重新批准。实现阶段低影响变化必须说明理由，不暂停任务且不重新批准。实现阶段高影响变化必须有结构化理由和证据，创建候选版本，暂停受影响后继并等待 owner 批准。
+
+使用双指针表达“选中的候选”和“实际执行中的批准版本”：高影响候选期间 `active_plan_id` 前进，`execution_plan_id` 保留旧版本；批准时原子切换并 supersede 旧版本；放弃时恢复旧版本。
+
+已开始任务禁止原地重写。若任务边界需要调整，使用新任务 ID 承接后续工作，旧任务保留全部事件、事实、证据和责任历史，并生成迁移记录。
+
+使用一份自解释 Zod 合同作为 runtime 校验、JSON Schema、dashboard 投影和 LLM 局部语义投影的共同来源。`schema_version` 与 `contract_version` 分别表达存储结构和领域语义。
+
+## 后果
+
+- 设计阶段仍可快速重排任务，但不会丢失旧版本和依赖 diff。
+- 实现阶段的高影响变更会明确阻塞范围、理由、证据和批准边界。
+- dashboard 与 LLM 不再把候选计划、执行计划和阶段混为一个“当前状态”。
+- 任务迁移保留事实但增加了明确的账本记录要求。
+- 字段说明、示例和不变量由可执行合同投影产生；长期取舍写入 ADR，但 ADR 不复制字段字典。
+
+## 拒绝的替代方案
+
+- 不使用单一 `active_plan_id` 推断执行计划，因为它无法表达待批准的高影响候选。
+- 不允许调用方自报 `implementation_low_impact`，因为依赖、基线和动作变化必须由 runtime 根据 diff 识别。
+- 不通过覆盖已开始任务来实现迁移，因为这会破坏开始事实与证据的审计链。

package/toolkit/skills/docs/vendor/dot-codex/adr/0041-contribution-tasks-and-delivery-units.md

@@ -0,0 +1,7 @@
+# Contribution tasks and delivery units
+
+Use **Contribution task** for repository changes delivered through a child PR, including code, documentation, tests, and configuration. Use **Verification**, **Release**, **Deployment**, and **Coordination** for work whose completion is established by its corresponding evidence rather than a child PR.
+
+Call the virtual parent-branch and parent-PR integration boundary a **Delivery unit**. It is a ledger grouping and acceptance boundary, not a native conversation hierarchy or a second controller: the main Agent directly manages every task and delivery unit, while a Delivery coordinator acts only within delegated scope. A contribution child PR targets the current delivery-unit parent branch; the delivery-unit parent PR targets the repository target branch.
+
+The canonical names remove the ambiguity of “development” and “other” while preserving unfinished ledgers: the validator may read those two legacy values, while new fixtures and plans use the canonical kinds. Internal `group` and `group_id` field names remain for ledger compatibility.

package/toolkit/skills/docs/vendor/dot-codex/adr/0041-task-orchestration-dashboard-experience.md

@@ -0,0 +1,77 @@
+# ADR 0041: Task Orchestration Dashboard Experience
+
+- Status: Accepted
+- Date: 2026-11-04
+- Supersedes: `docs/adr/0036-task-orchestration-dashboard-experience.md`
+- Related: `docs/adr/0035-task-orchestration-ledger.md`, `docs/specs/multi-task-flow/SPEC.md`
+
+## Context
+
+The task-orchestration dashboard serves two different owner jobs. Before any real task starts, the owner primarily checks whether the dependency plan is sound. After execution starts, the owner primarily follows progress, blockers and integration state. The dashboard must make that change of emphasis visible without introducing another source of orchestration state or interrupting a live investigation.
+
+The existing dashboard is a read-only projection of the authoritative ledger. It already exposes the dependency graph, planned and actual timelines, filters, details and native conversation or pull request links. The experience decision therefore governs presentation, interaction and durable UI preferences while preserving the existing data and link contracts.
+
+## Decision
+
+### Phase-aware presentation
+
+Derive one monotonic `编排展示阶段` from the run data:
+
+- `planning` remains active until a real task has an actual start fact.
+- `execution` begins when any real task has started and never reverts.
+- A `starting` state or dispatch claim without an actual start fact does not trigger the transition.
+- Selecting a plan version does not change the run phase.
+
+Keep the existing graph, planned and actual views rather than adding a user- controlled phase mode. On an initial load, planning opens on the dependency graph and execution opens on actual progress. If a live page crosses the phase boundary, retain the current tab, filters, selection, scroll position and focus; show a non-blocking notice with an entry point to actual progress.
+
+Planning emphasizes the dependency graph, planned timeline, readiness and blockers. Execution emphasizes the actual timeline, running state, blockers and integrated work. Neither phase hides the other phase's authoritative data, and the summary uses existing ledger fields rather than inferred completion or remaining-time metrics.
+
+### Workspace and responsive details
+
+Use a calm developer-workspace treatment: neutral chrome, a restrained framed-sheet surface, clear product identity and data-led status colour. Do not add a marketing hero, generic KPI card grid, or permanent application navigation that competes with the orchestration workspace.
+
+Use the following width contract, measured against the `.workspace` content width `W` rather than the browser's outer width:
+
+| Width | Layout contract |
+| - | - |
+| **宽桌面双栏**：`W >= 1356px` | A selected open detail uses a `336px` right inspector with a `20px` gap; the graph/main column retains at least `1000px`. |
+| **中屏品字型**：`768px <= W < 1356px`, usually `768px-1444px` viewport | The graph/view spans the full first row. The second row places tasks on the left and selected details on the right with asymmetric widths; details do not reduce graph width and disappear when there is no selection. Grid cards and board group columns share stable 243–360px outer tracks; nested board cards naturally subtract group padding and borders. The inspector has absolute 243–740px limits and absorbs the remainder after maximizing complete task tracks. Detail toggles must not resize the tracks. Controls may wrap. |
+| **窄屏底部抽屉**：Viewport `<768px` | The workspace is one column. Selected details use a bottom drawer capped at `82dvh`; plan and summary surfaces become two-column, and task cards remain horizontally scrollable. |
+
+Closing or clearing the selection removes the detail surface and leaves the main column full width at every band. A fine hovering pointer may show a 250ms preview when no committed detail is open; touch, keyboard and other non-hovering input remain selection-driven. Temporary surfaces support close, `Escape` and backdrop dismissal, and restore the originating focus and scroll position when closed. Selecting another item while a temporary surface is open updates that surface rather than closing it.
+
+The wide detail pane keeps a valid `详情选择` even when a filter hides the object. It clears only when the object is removed or its ID becomes invalid.
+
+Timeline interaction is explicit: ordinary wheel input must not zoom or consume page scrolling; only `Ctrl` + wheel zooms around the pointer. Timeline pan remains available through primary-button drag, and the toolbar buttons remain available for users who do not use wheel gestures.
+
+### Selection, accessibility and motion
+
+Clicking or keyboard-selecting an object commits the detail selection. A fine pointer may show a short, approximately 250ms `详情预览` on graph or timeline objects, but the preview has no actions and never replaces the committed selection. Lists only highlight on hover; touch and keyboard interaction do not depend on hover.
+
+The semantic task and group lists are the complete keyboard and assistive- technology source of truth beside the visual graph. Graph nodes do not create a second node-by-node tab sequence. Temporary detail sheets and drawers move focus into the surface, constrain focus while open, and restore focus on close; the persistent wide pane does not trap focus. Status is conveyed through text and icons, not colour alone, and reduced-motion preferences disable panel, layout and refresh animations.
+
+Task cards and details may show two direct runtime facts already present in the ledger projection: current duration from recorded start/finish timestamps and the latest owner-facing Agent output. Output is projected only from explicit `latest_output`, `assistant_output`, `agent_output`, or assistant-role `message` fields in an event associated with that task. Missing output stays empty; planned output, arbitrary event fields and inferred text are never displayed.
+
+Live refresh preserves the current view context and never auto-scrolls or auto-opens a new object. Keep the last valid snapshot during stale or disconnected states, display connection state and data time, and never replace unknown values with zero. A first-load failure has an explicit error state; reconnection refreshes the projection.
+
+### URL view state
+
+Persist shareable dashboard context in URL query parameters as `URL 视图状态`. The state includes the selected tab, search text, filters, selected plan, selected task or group, detail expansion and timeline window. Graph zoom remains an interaction-local control and is omitted from generated URLs; legacy zoom parameters remain readable. Defaults are omitted from the canonical URL. Page load and browser back/forward navigation restore valid parameters; unknown or invalid IDs are ignored without blocking the dashboard. URL state contains only stable identifiers and view values, never task data, credentials or service tokens.
+
+URL view state is not written to browser storage, the ledger or the global preference file. Theme is deliberately separate: it is the only current `全局界面偏好`, stored as `ui-preferences.json` under the task-orchestration Skill's global data directory. The preference file includes a schema version and `system`, `light` or `dark` theme value, uses the existing lock and atomic replacement conventions, applies immediately, and falls back to system theme when missing or unreadable.
+
+## Consequences
+
+The dashboard supports both plan review and live execution monitoring without forking the ledger contract or making the owner change modes manually. A shared URL can reproduce the relevant debugging context for another Agent, while global theme preference survives page and Worktree changes without polluting shareable links or orchestration state.
+
+Responsive details require explicit focus restoration and separate wide, medium and narrow interaction tests. The graph remains visually useful while the semantic lists provide a stable accessibility and keyboard contract.
+
+Graph and timeline canvases use the same wheel contract: ordinary wheel input continues page scrolling, while `Ctrl` + wheel is required for viewport zoom. Primary-button drag remains the pan gesture where the underlying view supports it, and explicit zoom controls remain available.
+
+## Rejected Alternatives
+
+- Add a manually switchable planning/execution mode: rejected because the phase is a fact of the run and a second mode can contradict the ledger.
+- Force the live page to jump to actual progress at the phase boundary: rejected because it steals the owner's current investigation context.
+- Persist all view controls in browser storage or the ledger: rejected because it prevents reliable sharing and mixes UI state with authoritative run data.
+- Add a second dashboard state store: rejected because the ledger remains the only orchestration source of truth.
+- Make hover, colour, or the graph canvas the only interaction path: rejected because touch, keyboard and assistive-technology workflows need equivalent semantic controls.

package/toolkit/skills/docs/vendor/dot-codex/adr/0042-shared-orchestration-viewer.md

@@ -0,0 +1,13 @@
+# 按本机用户共享编排展示服务
+
+主人已确认本决策，作为后续实现依据；确认范围仅为设计。
+
+同一台电脑、同一 OS 用户的所有 multi-task-flow 编排共用一个展示服务，生命周期独立于 Agent 对话，以降低资源占用并消除逐对话管理网页进程的职责。服务提供运行列表、各运行仪表盘与实时数据展示；调度决策与账本写入继续由主 Agent 和现有 CLI 负责，避免将共享展示进程扩大为持有所有编排执行权限的后台协调器。
+
+不同 OS 用户分别隔离，本决策不包含跨机器或多人访问。服务默认不自启动，Agent 按需请求启动或复用并续期使用租约，无有效使用需求时由服务按 TTL 自行退出。正式数据位于独立于代码安装和 CODEX_HOME 的用户级固定数据根，开发测试数据隔离；软件升级与回滚由主人显式维护，允许短暂断线。
+
+后台采用无需管理员权限的用户级按需托管，统一 CLI 提供启动复用、续期与释放。Agent 租约按主会话与运行区分，默认 TTL 60 分钟；浏览器也可独立续期。最后一份有效租约到期时退出，崩溃后由下一次使用恢复。
+
+正式数据根为 `~/.local/share/multi-task-flow/`。单例提供固定 loopback 入口，通过 `/runs/<run_id>/` 区分运行、`?plan=<plan_id>` 区分计划；凭据不进入运行链接。正式环境只运行一个软件版本，兼容范围显式公布，不兼容数据按运行单独报告，不通过另起旧服务解决。
+
+保留由同一服务提供的每运行自定义 view，并要求明确资源兼容合同。代码升级与账本迁移分离，旧运行保留身份并输出新链接映射，不维持旧端口或旧进程。完整合同见 [共享编排展示服务设计](../design/multi-task-flow/shared-viewer.md)；本决策不授权安装或变更运行服务。

package/toolkit/skills/docs/vendor/dot-codex/adr/0043-composite-notification-delivery.md

@@ -0,0 +1,9 @@
+# 复合通知投递
+
+任务和编排事实先创建持久化的通知意图，再由 `orchestrate.ts` 的复合命令直接调用 Codex app-server 完成平台投递并记录结果。这样可以把已提交的账本事实、平台投递和收件确认分开，在 Agent turn 中断后仍可恢复，也不要求每个 Agent 手工编排记账与发消息的顺序。账本合同保持平台中立，当前 adapter 通过官方 Unix WebSocket 控制面调用 `turn/start` 连接当前 Codex 会话。
+
+## 后果
+
+- 账本更新成功后，投递结果可以是 pending、failed 或 unknown，且必须能够恢复处理。
+- 投递成功永远不等同于收件确认；只有已绑定的收件会话可以确认。
+- adapter 边界未来可以支持其他 Agent 平台，而不改变通知状态语义。

package/toolkit/skills/docs/vendor/dot-codex/adr/0043-external-source-viewer.md

@@ -0,0 +1,16 @@
+# ADR 0043: External source directory viewer
+
+## Decision
+
+The shared viewer exposes a generic read-only source-directory view. An operator may provide an absolute run-data directory; the service validates the directory and assigns a random `view-<id>` run identity. The identity is a presentation mapping only and never becomes an orchestration run or ledger authority.
+
+The mapping reads the source directory directly, is served by the existing single user service, and is protected by the same local authentication and browser lease. It is removed when its view lease expires. The source directory is never modified, copied into formal `data/runs`, or included in scheduling, renewal, migration, or write APIs.
+
+Examples use this generic capability; there is no example-specific service mode or demo branch.
+
+## Consequences
+
+- Every view must retain the canonical source path and a filesystem identity so replacement or symlink traversal fails closed.
+- The mapping must be bounded by an explicit read-only lease and must not keep the service alive after the viewer closes.
+- URLs contain only the generated view identity; source paths and credentials stay out of URLs and ordinary logs.
+- A source directory with an unsupported ledger contract is rejected with a readable compatibility error.

package/toolkit/skills/docs/vendor/dot-codex/adr/0044-multi-task-execution-profile-and-cli-conversation-creation.md

@@ -0,0 +1,28 @@
+# ADR 0044：Multi-task Flow 执行配置与 CLI 对话创建
+
+- Status: accepted
+- Date: 2026-11-05
+- Related: `docs/specs/multi-task-flow/SPEC.md`, `docs/adr/0032-flow-scoped-model-profile-allowlists.md`, `docs/adr/0035-task-orchestration-ledger.md`
+
+## 背景
+
+编排需要在创建交付单元和任务对话前确定模型与思考强度。Agent 内置创建工具的模型限制与编排需要不一致；网页需要支持创建前调整，同时保证调度安全与审计事实完整。
+
+## 决定
+
+- 将模型和思考强度表示为完整 `execution_profile`。对象配置必须整体为空（使用运行默认值），或同时包含两个字段。
+- 每个运行只有一个全局默认值。交付单元和任务独立覆盖，互不继承。
+- 正式创建通过 multi-task-flow CLI 领域命令调用 Codex app-server 控制面。CLI 负责能力校验、native request identity、实际创建和 dispatch resolve 证据。
+- 取得 native request ID 后冻结对象配置；明确失败经过对账后可以修正配置并重新 claim。unknown 保留占用，禁止直接重试。
+- 创建前修改配置必须终止旧的未提交 claim，记录旧配置和原因，并要求重新 claim。
+- 对话创建后的内部模型或思考等级调整属于会话本身，不回写编排账本、不触发计划修订；编排不得主动重设已创建对话的配置。
+
+## 备选方案
+
+- 直接使用 Agent 内置工具：模型限制不符合编排需要，拒绝。
+- 由交付单元提供任务默认值：会在平级对象之间引入隐式耦合，拒绝。
+- 创建后主动调整配置：会修改已运行会话并导致创建证据失真，拒绝。
+
+## 影响
+
+账本与网页需要表达配置来源、编辑和冻结状态。旧运行必须显式迁移，缺少默认值时只读。CLI 成为正式创建边界，并须在重试前对账不确定结果；会话内部后续配置变化不属于本功能的追踪范围。

package/toolkit/skills/docs/vendor/dot-codex/adr/0045-viewer-compatibility-and-maintenance.md

@@ -0,0 +1,19 @@
+# 0045：共享展示兼容与维护迁移
+
+- Status: accepted
+
+## 背景
+
+共享展示服务必须保留历史，但历史账本不一定需要继续写入。旧预检同时要求所有合同可读和可写，将历史展示升级耦合到了绑定 main 的持久迁移；业务结束、会话归档与账本收口并不等价。
+
+## 决定
+
+对所有保留 run 保持读取兼容，比较当前与目标构建的写入能力，仅新增写入降级需要准确报告确认。归档与租约不作为权限来源。合同与执行配置维护迁移分别提供只读预检和显式应用，保留 owner，记录实际维护身份，普通 main 写入权限不变。
+
+沿用同 OS 用户维护信任边界。主人批准引用与暂停写入声明是审计记录，不是独立认证；不新增人工令牌系统。迁移前暂停旧写入器，维护锁再 run 锁内验证版本、摘要、未决操作和展示兼容，完整备份后原子提交。
+
+## 备选与影响
+
+仅完成 run 可只读会再次依赖历史收口质量；只查目标 readable 而忽略新增写入降级会静默损失能力；恢复原会话迁移则将维护生命周期绑定业务会话。以上均不采用。同用户强认证需要另一个授权系统，不属于此边界。
+
+必须先安装可读源与目标的过渡构建再迁移。迁移后回滚须重新检查当前数据，不能用旧备份覆盖新写入。合作锁不防止同用户手工修改或不遵循协议的旧程序。

package/toolkit/skills/docs/vendor/dot-codex/adr/0046-native-worktree-desktop-handoff.md

@@ -0,0 +1,24 @@
+# ADR 0046：原生工作区创建与桌面交接
+
+- Status: accepted
+- Date: 2026-11-07
+- Supersedes: ADR 0044 的 app-server 创建传输决定；完整执行配置、冻结和未知结果对账规则继续有效。
+- Related: `../specs/multi-task-flow/SPEC.md`、`../design/multi-task-flow/execution.md`
+
+## 背景
+
+app-server 的 thread/start 不封装 Codex 原生工作区创建。外部 CLI 工作回合运行期间，桌面可能显示其他应用占用；让 CLI 执行完整任务会延长交接等待。桌面 create_thread 的模型限制不满足账本配置。
+
+## 决定
+
+由独立 codex exec --worktree --json 创建并初始化，工作区归属由 Codex 管理。完整透传锁定模型和推理配置，首轮仅确认初始化，不执行正式工作。收到身份立即落账，核验工作区、配置、回合完成、正常退出后绑定。标题通过不启动回合的命名接口设置。
+
+主对话在绑定后使用内置 send_message_to_thread 发正式任务。通知先持久领取 attempt，再调用工具并写回真实回执；unknown 禁止重发。旧 CLI 在途锁继续保护，不干预旧回合。
+
+接受 Codex 默认工作区起点，保留 initial_head。组在正式工作回合 fetch 远程主干，子任务继承组父分支 SHA；仅在本次新建、干净且归属明确的工作区对齐并通过 readiness 后开工。创建成功不要求提前达到目标 commit。
+
+## 取舍与验收
+
+不让脚本创建 Git worktree，也不引入临时基线 checkout。这个选择减少自有工作区元数据和双工作区生命周期，同时把基线安全检查交给有正式合同的工作 Agent。绑定、消息接受、基线就绪和实际开工分开审计。
+
+本次不解决外部回合的底层占用机制。必须实测 CLI 退出后原生消息能否让桌面接管；无法观察或失败时阻塞验收，不静默退回长期 CLI。历史 thread/start 和 create_thread 证据保留，不自动迁移真实数据，不重建已有线程。

package/toolkit/skills/docs/vendor/dot-codex/agents/issue-tracker.md

@@ -0,0 +1,5 @@
+# 多任务协调
+
+多任务开发使用 `$multi-task-flow`，由独立运行时 ledger 管理任务、依赖与生命周期。任务内的直接 PR 使用 `$fast-flow` 和共享工程工作流。
+
+Wave Thread 的 Skill、历史状态读取、事件回放和 CLI 已移除；历史对话状态不再由本仓库恢复或迁移。

package/toolkit/skills/docs/vendor/dot-codex/design/multi-task-flow/dashboard-requirements.md

@@ -0,0 +1,103 @@
+# 编排仪表盘展示需求
+
+## 范围与依据
+
+本文记录截图批注及需求访谈中已确认的展示行为，覆盖页面宽度利用、规范术语、交付单元卡片进度和原子任务详情。本文不授权运行时部署、远端写入或任务派发，也不表示界面或账本模型已经实现这些行为。
+
+参考页面：`http://127.0.0.1:61190/runs/cvm-analytics-module-postgres-01a1a6d5/?tab=planned&layout=grid&plan=analytics-module-plan-viewer-compat&selected=task%3AC0`。截图中实际选中的详情为“连续消费与幂等接收”，验收应同时覆盖 URL 指定选择和切换选择后的状态。
+
+## 规范术语
+
+沿用 [PR #242](https://github.com/IvanLi-CN/dot-codex/pull/242) 和 [术语表](../../../GLOSSARY.md) 的约定：面向用户使用“交付单元”，不使用“组”或“交付任务”代称；仓库变更任务使用“贡献任务”。内部兼容字段 `group`、`group_id` 不因文案调整而改名。
+
+标题、所属关系、筛选项、提示和可访问名称应一致。截图中的“组”“所属组”“开发 development”等旧文案需要核对页面实际加载版本，不能仅凭候选源码已修改就认定运行页面已修复。
+
+## 页面可用宽度
+
+批注指出的是整个页面内容右侧的空白带，不是时间线坐标范围内部的空白。排查外层容器、边距和布局占位，使图表区及下方任务与详情区域合理利用页面宽度；保留必要页面边距，并遵守已有卡片宽度和响应式布局约定。
+
+验收需在截图对应布局及相邻响应式断点检查整个页面右边界，覆盖详情打开和关闭、网格和看板模式。不得用扩大时间线日期范围掩盖外层空白，也不得通过拉伸任务卡片破坏已有尺寸契约。空白的具体根因留待实现时验证。
+
+## 交付单元卡片
+
+交付单元卡片保留名称及其他现有信息，不直接显示贡献任务名称、列表或其内部原子任务。原子任务进度仅来自交付单元自身的清单和状态，不从贡献任务数量、完成比例或内部步骤推算。
+
+交付单元原子任务按计划配置并串行执行。默认步骤为“准备父分支 → 创建父 PR → 验收集成结果 → 合并父 PR → 收口”，可按计划调整；发布、部署等已独立建模的任务不自动重复加入。
+
+| 情形 | 展示规则或示例 |
+| - | - |
+| 进行中 | `2/5 · 创建父 PR`，数字表示当前步骤序号与步骤总数 |
+| 尚未开始 | `0/5 · 待开始` |
+| 阻塞 | 显示对应步骤、序号与总数，并明确标记“阻塞” |
+| 全部完成 | `5/5 · 已完成` |
+| 旧账本未配置清单 | `未配置原子任务`，不伪造进度或执行历史 |
+
+交付协调者（Delivery coordinator） 更新执行状态；已有生命周期证据约束的步骤必须由相应证据确认完成。例如父 PR 合并步骤须关联已核实的合并记录。原子任务进度不得绕过现有验收、合并和收口门禁。
+
+## 等待贡献任务的状态图标
+
+交付单元对话正在等待贡献任务时，卡片状态图标必须使用独立的等待动画，不再使用代表正在执行的旋转图标。状态文字明确显示“等待贡献任务”，详情中的对应状态保持一致；交付单元整体仍未完成，不意味着协调对话正在执行工作，也不因正常等待而判为阻塞。
+
+等待状态须依据明确的运行事实或等待原因，不得仅凭存在未完成贡献任务推断。协调对话实际恢复执行后，图标与文字随状态切换；缺少可靠事实时不得伪造等待原因。状态读取与投影需区分交付单元整体状态及协调对话执行状态。
+
+等待动画采用沙漏轻微明暗交替。等待语义同时通过图形和文字表达，不只依赖颜色或运动；减少动态效果模式下显示静态沙漏和状态文字。验收覆盖执行、等待贡献任务、恢复执行及真正阻塞之间的切换。
+
+## 原子任务详情与依赖
+
+选中任务时，详情按执行顺序列出该任务自身的全部原子任务，至少展示名称与状态，并高亮当前项。选中交付单元时，原子任务区域展示该交付单元自身的清单，不以贡献任务清单替代。
+
+原子任务依赖通过悬浮或长按 tooltip 展示，内容为依赖任务列表及各项状态；键盘聚焦也应能读取相同信息。该展示基于已有依赖事实，不增加跨任务中间成果交接权限。
+
+原子任务清单与依赖列表复用状态行组件，按“状态图标、名称、完成时间”排列，名称可换行，时间靠右。完成时间只取对应对象的真实完成记录，没有记录时不显示。依赖条件和路径说明位于该项下方，不与名称分列挤压。
+
+## 本地时间展示
+
+时间点统一使用浏览器当前时区，不使用账本配置时区覆盖浏览器。本规则用于完成时间、任务详情与悬浮预览中的开始及完成时间，以及页头的数据更新时间；持续用时仍显示时长，时间轴刻度仍表示日期坐标。
+
+距现在小于12小时的时间点显示24小时制时分；满12小时且小于7天显示“12小时前”“3天前”等相对时间；满7天显示月日时分。未来时间显示月日时分，避免误写成过去时间。页面每分钟刷新时间展示，缺失和无效时间不显示占位值。
+
+时间展示复用时间组件；悬浮或键盘聚焦时间时，通过 tooltip 显示含年份和秒的完整本地绝对时间，不显示时区名称。时间 tooltip 在依赖 tooltip 内打开时保留父层依赖列表。
+
+## 卡片悬浮时间与独立信息浮层
+
+本节适用于网格、看板布局中的任务卡片和交付单元卡片。每张卡片仅展示自身绑定的对话、PR 和计时信息；首个交付单元沿用既有主对话绑定规则。时间悬浮于卡片右下角，不参与文档流，不独占一行，不撑高卡片，允许与最新回答重叠。
+
+对话图标、PR 图标和时间分别作为独立触发区，各自展示可移入操作的信息浮层，同一时刻只打开其中一个。悬停展示浮层，点击对话或 PR 图标仍直接打开对应页面。指针移入浮层后保持打开，离开触发区和浮层后短暂延迟关闭，保证指针能够跨越两者间隙。键盘聚焦可打开并进入浮层操作，Escape 关闭；触屏长按打开。浮层内复制、链接和滚动操作不得触发卡片选中或卡片跳转。
+
+浮层按可用空间自动定位，优先出现在触发点上方，空间不足时出现在下方；左右边界保持在视口内。上下空间均不足时限制高度并在内部滚动。承载按钮、链接等操作时，应提供支持键盘进入和操作的可访问语义。
+
+输出正文、输出空状态、任务与交付单元标题、进度文字不得另加全文或重复文字 tooltip；对话与 PR 图标不得在专用资源浮层之外叠加普通文字 tooltip。普通卡片悬浮预览只展示任务事实，不展示对话正文或输出空状态；宽度上限280px且不超出视口。除对话、PR、时间三个专用触发区外，其余卡片区域仍保留普通悬浮预览。
+
+### 对话浮层
+
+回答区头部左侧显示消息气泡图标，右侧显示消息自身发送时间，缺失时明确不可用，不使用抓取时间替代。显示真实对话 ID、真实对话标题，以及绑定对话中最新一条助手消息的完整内容，包含正在生成的内容并持续更新，生成中明确标记状态。ID 和标题分别提供复制操作及简短成功反馈；不提供复制回答按钮，回答正文仍可选择文字。不得使用卡片摘要冒充完整消息，也不得将卡片标题冒充对话标题。
+
+浮层出现在上方时，回答区域在上，ID、标题及复制入口在下；出现在下方时，ID、标题及复制入口在上，回答区域在下。身份信息和复制入口始终位于靠近触发点的一端，长回答只在回答区域内部滚动。生成中更新保留用户当前阅读位置，不强制滚动到底部。
+
+### PR 浮层
+
+PR 信息由服务程序通过 `gh` 查询，展示 PR 编号、标题、链接、Open／Closed／Merged 状态、是否存在合并冲突，以及 CI 汇总与各项检查结果。PR 编号和链接分别支持复制，链接可打开对应页面。CI 区分运行中、成功、失败、未配置和未知，不把未知视为成功。
+
+打开浮层时先展示已有缓存，由服务端按需刷新；显示数据更新时间、过期和刷新失败状态。有旧数据时保留并标记过期，提供手动刷新入口。刷新仅查询状态，不产生合并、重跑检查等远端副作用。
+
+### 时间浮层
+
+时间浮层使用独立紧凑宽度，上限288px且不超出视口，不沿用对话和 PR 浮层的480px宽度；标签列60px、列间距12px，数值右对齐。
+
+展示开始时间、已用时、排期用时、已用时占排期的百分比；完成后可展示实际结束时间。绝对时间使用浏览器当前时区，包含完整日期和秒，不显示时区名称。
+
+已用时从首次实际开始计算至当前时刻，包含等待、阻塞和暂停；完成后冻结为首次开始至实际结束的经过时间，不将其描述为有效劳动工时。排期用时为计划结束减计划开始。用时占比为 `已用时 ÷ 排期用时 × 100%`；超过排期时同时显示超出比例，例如已用15分钟、排期10分钟，显示“已用150%，超出50%”。排期缺失、为零或无效时不计算比例，不伪造排期。
+
+### 缺失数据与验收
+
+未绑定对话或 PR、尚未开始、读取失败时仍允许打开说明浮层，分别显示“尚未关联对话／PR”“尚未开始”“读取失败”等真实状态。缺失字段不伪造，也不提供无效复制或跳转入口；尚未开始时不显示虚构的开始时间或已用比例。
+
+验收覆盖两类卡片及两种布局：时间不占行且不撑高卡片；三个触发区互不串用内容；指针跨越间隙及移入浮层后可持续操作；键盘和触屏可访问；浮层内部操作不误触卡片。覆盖上下定位、视口四边、窄屏、长标题和长回答，验证身份信息靠近触发点、回答独立滚动及生成更新不打断阅读。
+
+数据验收覆盖最新助手消息生成中与已完成、无消息与读取失败、复制 ID 和标题；覆盖 PR 缓存、刷新成功与失败、已合并、已关闭、存在冲突及各类 CI 状态；覆盖计时未开始、运行、等待、暂停、完成、超期和缺失／无效排期。PR 查询须确由服务程序通过 `gh` 执行，刷新不得改变远端状态。
+
+## 数据模型与验收边界
+
+现有 `Task.atoms` 和计划 `AtomicPlan.task_id` 将原子任务归属于编排子任务；现有 `Group` 没有独立原子任务清单。因此交付单元原子任务需要扩展计划与账本模型、状态更新和读取投影，不能仅调整前端文案。具体字段与兼容迁移方案由实现阶段设计，旧账本不自动补造执行事实。
+
+验收应证明交付单元进度与贡献任务进度相互独立，任务详情归属正确，tooltip 中的依赖及状态与账本一致；同时核对未开始、进行中、阻塞、全部完成和未配置清单的显示。整个页面右侧空白、术语一致性及现有响应式尺寸契约均需在实现后验证。