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

package/toolkit/skills/docs/vendor/dot-codex/design/multi-task-flow/data-and-scripts.md

@@ -0,0 +1,297 @@
+# 编排数据与脚本方案
+
+本文描述新编排 Skill 的数据模型、脚本边界和一致性方案。关联文档：[编排方案](orchestration.md)、[执行方案](execution.md)、[网页模板方案](web-template.md)。
+
+## 设计目标
+
+同一编排中的主 Agent（main Agent）、交付协调者（Delivery coordinator） 和任务 Agent（Task Agent） 共享可读、可恢复的本机 JSON 账本。任务图、状态、事件和操作占用必须来自同一个权威账本；HTML 和 Markdown 要求文档不作为第二份调度状态。范围仅限一个编排，不为其他编排提供全局锁。
+
+Skill 自带 Bun + TypeScript 固定脚本，所有账本操作通过脚本完成。Agent 不直接编辑 JSON；要求 Markdown 可由 Agent 普通编辑，不强制生成或硬校验。脚本接口须支持机器可读的成功、等待、冲突与错误结果，并附可读原因。
+
+## 目录与身份
+
+```text
+<运行时 multi-task-flow Skill 目录>/data/
+├── .gitignore
+└── runs/<编排 ID>/
+    ├── ledger.json            # 唯一权威账本
+    ├── ledger.previous.json   # 上一份完整快照
+    ├── ledger.migration-v1-<request_id>.json # schema v1 迁移前的完整备份
+    ├── locks/                 # 同一编排的本机锁资源
+    ├── requirements/          # Agent 编写的 Markdown
+    └── view/                  # 项目专用的只读页面
+```
+
+运行数据放在实际加载的 `multi-task-flow` Skill 目录内部的 `data/`，不放进目标项目工作区；该目录的 `.gitignore` 是受版本管理的保留文件，内容为 `*` 和 `!.gitignore` 两行，忽略运行数据并保留目录。运行时目录以实际加载的 Skill 目录为基准，不把候选工作区误认为当前运行时。Skill 更新、安装和卸载不得悄然覆盖或删除未完成账本。必须使用明确路径解析和 ID 校验，防止指向其他目录或覆盖已有编排。
+
+编排 ID 不依赖会话 ID；交付单元、子任务、原子任务、事件、计划版本和外部操作各有稳定身份。会话 ID 只在原生会话实际创建后绑定；创建中的临时标识不能冒充已存在的任务会话。fork 后无法确定绑定或控制权时，实际使用时询问主人，未确认前不调度、不切割、不合并。
+
+## 账本契约
+
+下表是账本字段分交付单元；具体结构、状态和脚本接口见本文“账本格式与脚本命令”。未认识的必要语义或不兼容结构不得静默解释为成功。
+
+| 数据 | 最少记录内容 |
+| - | - |
+| 身份与版本 | 格式版本、编排 ID、项目仓库身份、账本单调递增版本、更新时间 |
+| 计划与授权 | 目标、约束、批准事实与授权范围、计划版本、并发目标、切割规则 |
+| 图 | 原子任务、子任务、交付单元、具体依赖和里程碑；各自稳定 ID、名称及归属 |
+| 工作与状态 | 子任务类型、负责人会话绑定、状态、基线、预期范围、验收与证据引用、阻塞和等待原因 |
+| PR 与交付单元 | 父分支、父 PR、子 PR、实际归属及变更历史、切割点 SHA、实际合并身份、follow PR 与收口义务 |
+| 时间 | 计划估时、依据与可信度；真实开始、等待、恢复、结束时间，以及明确时区 |
+| 外部操作 | 操作 ID、类型、目标、发起者、预期版本和 SHA、占用状态、实际结果或待核实状态 |
+| 事件和通知 | 稳定事件 ID、发生与记录时间、来源、结果证据、接收对象、通知确认与待处理状态 |
+| 资源 | 本机服务及端口租约、会话、工作区和清理目标的已知身份及独立收口结果 |
+
+例如，一条事件可表达“某子 PR 的平台合并已核实”，携带任务 ID、PR 身份、实际合并 SHA 和证据引用；其通知状态独立记录。任务开始、阻塞、已集成、已收口及交付单元完成不是同一个状态。缺失身份、时间或证据应明确为未知或待核实，不推断成已完成。
+
+依赖既可指向贡献子 PR 合入，也可指向父 PR 合并、CI、发布、部署或验证等具体事实。子任务的原子任务串行；跨子任务的贡献交接以 PR 合入为准。计划的目标、范围和依赖可以引用人写的要求文档，但要求文档不参与格式硬校验。
+
+## 账本格式与脚本命令
+
+采用 UTF-8 JSON 对象，新的 ledger 使用 `schema_version: 2`；不认识的版本或必需语义拒绝写入。schema v1 默认只能通过规范化读取为内存中的 v2 视图；需要持久升级时，主 Agent（main Agent） 必须显式调用 `orchestrate.ts migrate --input -`，指定准确 `run_id`、owner-only actor、唯一 `request_id` 和当前 `expected_revision`。迁移在维护锁和 run 锁内校验完整 v1 ledger，先保存 `ledger.migration-v1-<request_id>.json` 完整旧快照，再原子替换为 `schema_version: 2`、`contract_version: 1`；迁移新增 request record，因此 `revision` 单调增加 1，记录的 `committed_revision` 与返回 revision 相同。相同 request ID 和 canonical input 只返回已提交结果；不同内容、版本冲突、损坏或不安全路径拒绝写入。缺失的生命周期事实保持 `unknown`，不得伪造 publication 或 merge 通过，也不得由普通更新回写旧文件。所有持久身份为非空 ASCII 稳定 ID，使用字母、数字、`-`、`_`；文件名不得直接使用未经校验的 ID 或用户路径。时间是带 `Z` 的 UTC RFC 3339 字符串；实际发生时间和记账时间分开，未知为 `null`，禁止用当前时间替代未知事实。未知 SHA、链接和会话 ID 一律为 `null`，不生成占位值。
+
+账本顶层字段固定为：
+
+```ts
+type Ledger = {
+  schema_version: 2;
+  source_schema_version: 1 | null;
+  orchestration_id: string;
+  revision: number;                       // 初始为 0，每次成功变更增加 1
+  repository: { provider: string; host: string; owner: string; name: string; target_branch: string };
+  control: { owner_thread_id: string | null; ownership: 'pending' | 'bound' | 'uncertain'; approval_id: string | null };
+  config: { max_running_tasks: number; display_timezone: string; conversation_links_verified: boolean };
+  plans: PlanRevision[];                   // 保留原计划和之后批准的计划
+  active_plan_id: string;
+  groups: Group[];
+  tasks: Task[];
+  follow_prs: FollowPR[];
+  facts: Fact[];                           // 合并、CI、部署等带来源事实
+  operations: Operation[];                 // 包含持久占用及结果
+  milestones: Milestone[];                 // 自由追加，不具备门禁权限
+  events: Event[];
+  requests: RequestRecord[];               // 幂等请求及其已提交结果
+  notifications: Notification[];
+  resources: Resource[];
+  updated_at: string;
+};
+```
+
+初始化后、任务图尚未录入且尚未批准时的账本示例：
+
+```json
+{
+  "schema_version": 2,
+  "source_schema_version": null,
+  "orchestration_id": "run-example",
+  "revision": 0,
+  "repository": {"provider":"github", "host":"github.com", "owner":"example", "name":"project", "target_branch":"main"},
+  "control": {"owner_thread_id":"thread-example", "ownership":"bound", "approval_id":null},
+  "config": {"max_running_tasks":3, "display_timezone":"Asia/Shanghai", "conversation_links_verified":false},
+  "plans": [{"id":"plan-a", "supersedes_id":null, "approval_id":null, "created_at":"2026-01-01T00:00:00Z", "start_at":null, "atoms":[], "atomic_edges":[], "nodes":[], "edges":[], "cut_rules":[], "actions":[]}],
+  "active_plan_id": "plan-a",
+  "groups": [],
+  "tasks": [],
+  "follow_prs": [],
+  "facts": [],
+  "operations": [],
+  "milestones": [],
+  "events": [],
+  "requests": [],
+  "notifications": [],
+  "resources": [],
+  "updated_at": "2026-01-01T00:00:00Z"
+}
+```
+
+此状态只允许编辑计划、查看和批准，不能派发任务。示例中的项目、会话和日期均为示意，不是运行时事实。
+
+各集合以对象 ID 关联，不复制第二份权威任务清单。字段必须存在；未知使用 `null`，不使用空字符串冒充已知值。类型中的具体字段如下：
+
+| 对象 | 字段与约束 |
+| - | - |
+| `PlanRevision` | `id`, `supersedes_id: string \| null`, `approval_id: string \| null`, `created_at`, `start_at: string \| null`, `atoms: AtomicPlan[]`, `atomic_edges: AtomicEdge[]`, `nodes: PlanNode[]`, `edges: Dependency[]`, `cut_rules: CutRule[]`, `actions: PlannedAction[]`；active multi-task initialization requires the envelope to bind the raw-plan digest, `flow_type`, exact task IDs, owned surfaces and batch/task acceptance scopes |
+| `AtomicPlan` | `id`, `title`, `task_id`, `purpose`, `output`；每个原子任务在一个计划版本中只归属一个子任务 |
+| `AtomicEdge` | `id`, `from_atom_id`, `to_atom_id`；先构造并验证原子图，再按 `task_id` 映射为子任务图，禁止映射后形成环 |
+| `PlanNode` | `id`, `kind: 'main_start' \| 'main_end' \| 'group_start' \| 'group_end' \| 'task' \| 'milestone'`, `ref_id: string \| null`, `group_id: string \| null`, `label`, `estimate_minutes: number \| null`, `estimate_basis: string \| null`, `estimate_confidence: 'low' \| 'medium' \| 'high' \| null`；非负整数估时，未知全为 `null` |
+| `Dependency` | `id`, `from_node_id`, `to_node_id`, `requires: 'integrated' \| 'completed' \| 'merged' \| 'ci_passed' \| 'published' \| 'deployed' \| 'verified'`；只有受支持的证据满足对应条件，不把不同里程碑混为一谈 |
+| `CutRule` | `id`, `group_id`, `priority: number`, `required_task_ids: string[]`, `status: 'pending' \| 'claimed' \| 'applied' \| 'cancelled'`；相同交付单元按优先级处理，已应用规则不可重复执行 |
+| `PlannedAction` | `id`, `kind: 'publish_branch' \| 'publish_pr' \| 'release' \| 'deploy'`, `task_id: string \| null`, `group_id: string \| null`, `target_identity`；主人确认时逐项授权，执行目标须完全匹配 |
+| `Lifecycle` | `workspace_ready`, `pr_created`, `pr_merged`, `closed`，值为 `unknown`、`pending`、`passed` 或 `blocked`；交付单元与贡献任务共用，阶段只能由对应 receipt/closeout 推导 |
+| `Group` | `id`, `title`, `agent_thread_id: string \| null`, `state: 'planned' \| 'active' \| 'merged' \| 'closed' \| 'blocked'`, `parent_branch: string \| null`, `parent_pr: ExternalRef \| null`, `cut_sha: string \| null`, `current_sha: string \| null`, `merge_sha: string \| null`, `requirements_path: string \| null`, `lifecycle: Lifecycle`, `atoms: GroupAtom[]`, `coordination_execution: CoordinationExecution` |
+| `Task` | `id`, `title`, `kind: 'contribution' \| 'release' \| 'deployment' \| 'verification' \| 'coordination'`, `group_id`, `thread_id: string \| null`, `state: 'planned' \| 'ready' \| 'starting' \| 'running' \| 'waiting' \| 'blocked' \| 'integrated' \| 'completed' \| 'closed'`, `atoms: Atom[]`, `owned_surfaces: string[]`, `branch: string \| null`, `base_sha: string \| null`, `pr: ExternalRef \| null`, `requirements_path: string \| null`, `started_at: string \| null`, `finished_at: string \| null`, `blocker: string \| null`, `assignment_history: Assignment[]`, `lifecycle: Lifecycle` |
+| `Atom` | `id`, `title`, `status: 'planned' \| 'running' \| 'completed' \| 'blocked'`；按数组顺序串行，原子任务跨子任务依赖必须通过子任务交接点表达 |
+| `GroupAtom` | `id`, `group_id`, `title`, `purpose`, `output`, `lifecycle_stage: 'workspace_ready' \| 'pr_created' \| 'pr_merged' \| 'closed' \| null`, `status: 'planned' \| 'running' \| 'completed' \| 'blocked'`；按交付单元顺序串行，生命周期绑定步骤必须由对应证据驱动 |
+| `CoordinationExecution` | `state: 'unknown' \| 'idle' \| 'running' \| 'waiting' \| 'blocked'`, `reason: string \| null`, `waiting_for_task_ids: string[]`；等待必须显式引用同一交付单元的贡献任务 |
+| `Assignment` | `group_id`, `effective_at`, `reason`, `cut_operation_id: string \| null`；只追加，保持切割前后的归属历史 |
+| `ExternalRef` | `provider`, `repository`, `id`, `url: string \| null`；`url` 仅存实际取得并校验的链接，证据中的 SHA 使用 Git 平台支持的完整对象 ID |
+| `FollowPR` | `id`, `origin_task_id`, `origin_group_id`, `pr: ExternalRef`, `target_branch`, `state: 'open' \| 'merged' \| 'blocked'`, `merge_fact_id: string \| null`, `affected_task_ids: string[]`；归属原交付单元，目标按原父 PR 是否已合并选择 |
+| `ProviderReceipt` | `provider`, `repository`, `resource_type: 'branch' \| 'pr'`, `resource_id`, `branch`, `target_branch`, `base_sha`, `head_sha: string \| null`, `pr`, `state: 'exists' \| 'open' \| 'merged' \| 'absent' \| 'unknown'`, `evidence_ref`；publication resolve 必须保存远端查询得到的完整 receipt，失败/不确定查询分别使用 `absent`/`unknown` |
+| `Fact` | `id`, `kind: 'task_quality' \| 'pr_merged' \| 'branch_published' \| 'pr_published' \| 'ci_passed' \| 'published' \| 'deployed' \| 'verified'`, `subject_id`, `status: 'passed' \| 'failed' \| 'unknown'`, `source`, `observed_at`, `sha: string \| null`, `evidence_ref: string \| null`, optional task-owned quality proof, `receipt: ProviderReceipt \| null`；不同阶段和目标独立记录；贡献任务的 `pr_merged` 必须绑定该任务自己的 child merge receipt，不比较后续父交付单元 SHA；发布或部署产物 SHA 可以因构建产生新对象，但必须由对应 `Operation.receipt_fact_id` 和 `expected_sha` 证明来源 lineage |
+| `Operation` | `id`, `kind: 'dispatch' \| 'merge' \| 'cut' \| 'publish_branch' \| 'publish_pr' \| 'release' \| 'deploy'`, `actor_id`, `target_id`, `status: 'claimed' \| 'succeeded' \| 'failed' \| 'unknown'`, `request: object`, `expected_sha: string \| null`, `receipt_fact_id: string \| null`, `created_at`, `updated_at`；`request` 保留目标身份、原始调用身份及精确预期，不能存凭据 |
+| `Event` | `id`, `type`, `subject_id`, `actor_id`, `occurred_at: string \| null`, `recorded_at`, `data: object`；事件只追加，同一 ID 不同内容视为冲突 |
+| `RequestRecord` | `request_id`, `command`, `canonical_input`, `result`, `committed_revision`；仅保留已提交的非敏感请求和结果，供进程中断后的幂等恢复 |
+| `Notification` | `id`, `event_id`, `recipient_thread_id`, `ledger_status: 'committed'`, `status: 'pending' \| 'sent' \| 'failed' \| 'unknown' \| 'acknowledged'`, `delivery_status: 'pending' \| 'sent' \| 'failed' \| 'unknown'`, `ack_status: 'unacknowledged' \| 'acknowledged'`, `attempts: number`, `last_attempt_id: string \| null`, `last_reconciliation_id: string \| null`, `last_error: string \| null`, `updated_at`；账本提交、平台投递和收件确认彼此独立，发送不等于处理确认 |
+| `Resource` | `id`, `kind: 'conversation' \| 'worktree' \| 'branch' \| 'port' \| 'service'`, `target: string \| null`, `status: 'unknown' \| 'active' \| 'pending' \| 'closed' \| 'not_applicable'`, `evidence_ref: string \| null` |
+
+`Event.type` 的完整枚举由 `lib/schema.ts` 定义。任务时间事件的 `data` 包含 `task_id`、`group_id`、`state`、`reason: string | null`；交付单元事件包含 `group_id`、`state`；`group_atom_updated` 记录 `group_id`、`atom_id`、`state` 和生命周期证据，`group_execution_updated` 记录协调执行状态、原因和等待任务；操作事件包含 `operation_id`、`outcome: string | null`、`fact_id: string | null`；`group_base_reconciled` 必须包含 `operation: "update-branch"`、`branch`、`previous_sha`、`sha`、已登记的 `parent_pr`、provider `source` 和 `evidence_ref`，并证明 `previous_sha` 等于账本原 `current_sha`；`cut_claimed` 必须绑定 `operation_id`、`group_id`、`rule_id` 和 `expected_sha`；`cut_applied` 另含 `cut_sha`、已核实的 `cut_evidence`、`old_group_id`、`old_group_current_sha`、完整的 `old_group_snapshot`、`new_group_id`、`new_group_state`、`new_group_agent_thread_id`、`new_group_parent_branch`、`new_group_parent_pr`、`new_group_cut_sha`、`new_group_current_sha`、`new_group_merge_sha`、`new_group_requirements_path`、完整的 `new_group_snapshot`、`included_task_ids`、`reassigned_task_ids` 和切割前的 `task_snapshots`，用于证明唯一 operation 的切割边界、任务状态和下一交付单元的干净创建状态。`fact_observed` 引用 `fact_id`，`follow_pr_recorded` 引用 `follow_pr_id`，通知事件引用 `notification_id`。这些事实与对象变更须在同一账本更新中提交。
+
+`kind` 和 `type` 由固定脚本限定，页面不可增写。任务的运行中和等待时间区间由有序 `Event` 推导；报告事件必须提供可靠来源，未知结束时间不产生伪造的闭区间。`integrated` 只表示贡献 PR 合入，`completed` 表示该项实际工作完成，`closed` 仅在适用的 follow PR、检查及归档条件满足时记录；资源清理仍分别记账。
+
+### 调用格式
+
+入口为 `bun run <skill>/scripts/orchestrate.ts <command> --input -`，标准输入为一个 JSON 对象；禁止通过命令行传递凭据。输出只有一个 JSON 对象到 stdout，诊断写 stderr。读命令不修改账本；写命令必须先有本编排操作权限，且共同遵循以下信封：
+
+```json
+{
+  "run_id": "run-example",
+  "actor": {"role": "main", "thread_id": "thread-example"},
+  "request_id": "op-example",
+  "expected_revision": 12,
+  "payload": {"task_id": "task-a"}
+}
+```
+
+`role` 限 `main`、`group`、`task`；脚本核对账本绑定的身份和允许操作，主机同一用户的进程不被视为强身份隔离。每次不同命令使用独立 `request_id`，同一外部动作的 claim、resolve 则使用同一个 `operation_id`；重试同一命令沿用其 `request_id`。写入先查 `request_id`：相同 ID 和规范化请求完全一致时返回原结果，即使调用方携带旧 revision；规范化内容为命令、run ID、actor 和 payload，不包括 `expected_revision`。相同 ID 内容不同返回 `ID_CONFLICT`。新请求再比较 revision，不匹配返回 `REVISION_CONFLICT` 且不写入。成功变更一次递增一次 revision；单个事件不能先写状态后写通知再分别成功。
+
+```json
+{"ok": true, "code": "APPLIED", "revision": 13, "result": {"operation_id": "op-example"}}
+```
+
+失败输出 `{"ok":false,"code":"...","revision":null,"message":"...","details":{}}`，不泄露凭据；调用者需重新读取账本获取当前版本。退出码 `0` 成功或幂等重放，`2` 输入无效，`3` 版本或身份冲突，`4` 等待前驱或操作占用，`5` 外部状态未知或恢复阻塞，`6` 本地 I/O 或锁故障。等待和未知不是成功。
+
+### 固定命令
+
+| 命令 | `payload` 的关键字段 | 成功效果 |
+| - | - | - |
+| `init` | `repository`, `config`, `initial_plan`, `groups`, `tasks`，主会话来自 `actor` | 仅接受未绑定且 `planned` 的 group/task（atom 也必须为 `planned`），并要求分支、PR、SHA、时间、阻塞、requirements path 和 assignment history 等运行时身份字段为空；拒绝 dev-plan handoff、digest 或外部计划字段，失败返回 `INVALID_INITIAL_STATE` 或 `INVALID_INPUT` 且不产生 run 目录、锁或 ledger；成功只创建唯一 run 和初始 revision，不创建任务会话 |
+| `binding-resolve` | `owner_decision`, `previous_owner_observation` | 根据主人明确决定和前任会话的停止事实转移控制权；未知 fork 不能自行接管 |
+| `link-verification` | `verified`, `evidence` | 主 Agent（main Agent） 可记录当前候选的一次性会话跳转实测结果及证据引用；证据覆盖且页面合同未变时复用，不重复测试。真实会话 ID 或 canonical anchor 合同缺失时阻塞；缺少可选原生观察本身不阻塞 |
+| `show` | `section`，可为 `summary`、`plan`、`tasks`、`operations`、`notifications`、`full` | 返回一致快照及 revision；无需 `request_id` 或预期 revision |
+| `plan-propose` / `plan-approve` | 前者 `plan`；后者 `plan_id`, `approval_id`, `authorized_actions` | 新增计划版本 / 记录对应主人确认；不自动更改未授权范围 |
+| `dispatch-claim` / `dispatch-group-claim` / `dispatch-bind-request` / `dispatch-resolve` | `task_id` 或 `group_id`, `operation_id`；resolve 另带原生结果或失败证据 | 原子检查依赖和容量、登记原生请求身份并绑定真实 thread ID；未知时保留占用 |
+| `lifecycle-record` / `milestone-record` | 目标类型、目标 ID、阶段或 milestone、资源/证据 | 记录交付单元和贡献任务的 `workspace_ready`，或追加不具备门禁权限的自由 milestone |
+| `publish-branch-claim` / `publish-branch-resolve` | `target_type`, `target_id`, `branch`, `expected_head_sha`, `action_id`, `operation_id`；resolve 加精确 Provider receipt | 独立占用并记录远端分支存在性；必须先有 workspace-ready |
+| `publish-pr-claim` / `publish-pr-resolve` | `target_type`, `target_id`, `branch`, `pr`, `target_branch`, `expected_base_sha`, `expected_head_sha`, `action_id`, `operation_id`；resolve 加精确 Provider receipt | 独立占用并记录远端 PR identity/base/head；必须先有成功 branch receipt |
+| `task-update` | `task_id`, `state`, `occurred_at`, `detail`, `evidence`, 可选 `notification: { mode: 'auto' \| 'deliver' \| 'none', recipient: 'owner' \| { thread_id } }` 或兼容字段 `notify_main: true` | 按状态前提记事件和状态；`auto` 保留 completed/closed 的原默认规则，`deliver` 创建主动通知意图，`none` 不创建，普通阻塞不默认通知主 Agent（main Agent） |
+| `atom-update` | `task_id`, `atom_id`, `state` | 由任务会话按数组顺序更新原子任务状态 |
+| `group-atom-update` | `group_id`, `atom_id`, `state` | 由绑定交付协调者（Delivery coordinator） 或主 Agent（main Agent） 按顺序更新交付单元原子状态；生命周期绑定步骤必须有对应通过证据 |
+| `group-execution-update` | `group_id`, `state`, `reason`, `waiting_for_task_ids` | 明确记录交付协调实际执行、等待、恢复和阻塞；等待贡献任务必须引用同组有效任务 |
+| `group-update` / `group-base` | 前者 `group`，后者 `group_id`, `provider_observation` | 更新交付单元信息或记录首次/同 SHA 的核实分支基线；已建立 SHA 的推进必须使用 `group-base-reconcile` |
+| `group-base-reconcile` | `group_id`, `provider_observation`（`operation: "update-branch"`, `previous_sha`, `sha`, `branch`, `parent_pr`, `source`, `evidence_ref`） | 在无未决 merge/cut operation 时，使用精确 provider 证据原子记录同一父分支的外部 update-branch SHA 推进；不表示 PR 合并 |
+
+| `task-pr` / `task-base` / `task-quality-record` | `task_id` 和 PR、基线或任务 Agent 自证 | v2 下只允许绑定已有 PR publication receipt；任务 Agent 自己记录当前 head/base、验收引用和 checks，不需要交付协调 Agent 审核 child PR |
+
+| `merge-claim` / `merge-resolve` | `operation_id`, `pr`, `target_branch`, `expected_head_sha`, `expected_base_sha`；resolve 加 `outcome`, `provider_evidence`，可选 `notification` 或 `notify_main` | 登记合并占用 / 记录可验证结果；未经核实的结果为 `unknown`；`auto` 只在成功时按原规则创建通知意图 | | `cut-claim` / `cut-apply` | `operation_id`, `group_id`, `rule_id`；apply 加 `cut_sha`, `included_task_ids`, `next_group`, `provider_evidence` | 阻止新合入、等待已有操作 / 原子固定归属、创建下一交付单元及任务归属历史 | | `action-claim` / `action-resolve` | `operation_id`, `kind`, `target`, `expected_identity`；resolve 加 `outcome`, `provider_evidence` | 为已授权发布或部署登记持久占用并记录结果，未知时先核实，不盲目重试 | | `follow-pr-update` | `follow_pr_id`, `origin_task_id`, `origin_group_id`, `pr`, `target_branch`, `affected_task_ids` | 登记 follow PR；后续合并结果通过 `merge-resolve` 记账并保留原交付单元归属 | | `fact-record` | `fact` | 记录核实的非合并、非子 PR 验收事实 | | `notification-deliver` | `notification_id`, `delivery_attempt_id`, `outcome: 'sent' \| 'failed' \| 'unknown'`, `provider_receipt`，失败可带 `error` | 由 CLI 在 Codex Agent API 返回后写回真实结果；`ledger_status` 已提交后，失败不得回滚通知意图；同一 attempt 不得重复记账 | | `notification-send` | 普通请求信封，`payload.notification_id` | `notification-prepare` 的兼容名称：持久领取一条新尝试，返回原生发送参数；主对话发送后显式写回平台回执。只允许 `pending` 或明确 `failed`，`unknown` 必须先对账 | | `notification-reconcile` | 查询形式带 `run_id`, `actor`, 可选 `status`；写入形式另带 `request_id`, `expected_revision`, `notification_id`, `reconciliation_id`, `outcome`, `provider_receipt` | 查询形式列出待处理通知；写入形式只允许核对 `unknown`，不得发送消息，必须由发送方或 `main` 提交平台查询证据 | | `notification-ack` | `notification_id`, `handling_evidence` | 只有 `recipient_thread_id` 对应会话可以确认；`sent` 不自动变成 `acknowledged` | | `view` | 可选 `plan_id` | 生成只读视图，不改变调度状态 | | `group-close` / `run-complete` / `resource-update` | `group_id`、完成证据或 `resource`；`group-close` 可选 `notification` 或 `notify_main` | 核查交付单元和编排的完成条件，分别记录各资源收口；`group-close` 默认按原规则创建通知意图 |
+
+复合通知通过持久领取、原生发送、回执对账完成。记账命令提交 pending 意图后领取唯一 attempt 并设 unknown，返回 should_send、tool_request 和回执 identity；只有新领取者可调用桌面内置 send_message_to_thread。随后 notification-reconcile 必须带相同 delivery_attempt_id 和真实 provider/evidence_ref/message_id，区分 sent、failed、unknown。重放 should_send=false，不重复调用平台；未知结果先对账。历史 CLI 发送的在途文件锁继续保护，原生领取不跨工具调用持有文件锁。通知发送接受不代表已读或实际开工。
+
+### 状态与就绪判定
+
+任务派发检查明确前驱和空闲名额；绑定会话后进入 `starting`，实际开始时进入 `running`。`running → waiting/blocked` 时释放运行名额，恢复前重新检查依赖和容量。交付单元与贡献任务按 `workspace_ready → pr_created → pr_merged → closed` 记录生命周期；workspace-ready 绑定 active worktree/branch Resource，pr-created 只由 `publish_pr` 成功 receipt 推导，pr-merged 只由 `merge-resolve` 成功 receipt 推导，closed 只由现有 closeout 条件推导。贡献任务以核实的子 PR 合入进入 `integrated`，非贡献任务以明确证据进入 `completed`。已集成的后继可以开始；`closed` 还需检查已知 follow PR。失败不自动推导 `completed` 或 `closed`。
+
+同一编排的 `merge-claim` 对同一目标父分支与 `cut-claim` 互斥；切割期间新合入返回等待，已有合入处于未知状态时不能切割。切割 SHA 是归属交接点；后续 follow PR 使原父分支前进时，追加事实、更新 `current_sha` 并刷新合并证据，不更改已切出的归属。新交付单元任务可以继续推进，目标分支和合入须按上一批合入主干后的规则更新。
+
+`cut-claim` 首次成功时即持久登记切割占用，并返回 `APPLIED` 与 `result.drained: false`（有未完成合并）或 `true`（没有未完成合并）；这一步不得返回声称“无写入”的等待错误。已登记的合并仍能写入 `merge-resolve`，新 `merge-claim` 返回等待。主 Agent（main Agent） 在已有占用结束后使用最新 revision 执行 `cut-apply`；若仍有未知合并，则返回等待且不改变归属。`cut-apply` 必须核对平台当前 SHA，并把切割点、已合入集合、下一交付单元及未合入任务重新分配作为一个账本变更提交。
+
+计算理论甘特图时，按依赖拓扑和预计耗时模拟最多 `max_running_tasks` 个任务；同一时刻就绪任务先按解锁后继数量降序，再按计划声明顺序、稳定 ID 排序。没有起点、耗时或必要前驱时间时，对受影响节点保留未知，不将未知按零分钟处理；模拟结果不是外部事实。
+
+### 身份绑定与创建恢复
+
+`control.owner_thread_id` 和每个 `thread_id` 是权威绑定。`init` 只绑定传入的主会话并写入初始账本，不创建 group/task 会话；派发前写 `dispatch-claim` 和唯一操作 ID。调用原生创建工具后，只有真实返回的 thread ID 才能 `dispatch-resolve`；初始输入中的 group/task thread ID 和非 `planned` 运行状态均无效。临时创建确认不是会话 ID，也不能用于通知、链接或归档。
+
+创建调用结果未知时保持 `unknown` 和执行名额占用，先利用运行时返回的原始请求身份及可查询事实核对；当前可用工具尚未证明能查询每一种中断状态。若无法证明成功或失败，保留阻塞并请求主人处理，不释放占用后盲目再次创建。fork 后控制权不明确同样停止写入与派发，待主人确认绑定。
+
+## 脚本接口
+
+固定脚本的命令、输入及返回值定义在本文“账本格式与脚本命令”。能力与所有权如下：
+
+| 操作族 | 输入与行为 |
+| - | - |
+| 初始化与绑定 | 创建唯一编排，绑定仓库和会话；检查已有身份，无法确定 fork 控制权时返回需主人决定 |
+| 计划与图 | 读取或更新已授权计划、原子任务、子任务、交付单元、依赖、切割条件和计划时间；检查依赖环及引用完整性 |
+| 执行与调度 | 原子申请就绪任务执行名额、记录会话创建占用及结果、更新状态和时间；未知创建结果先核实，避免重复派发 |
+| 合并与切割 | 登记、检查、等待和结束操作占用；固化实际 SHA、分配与结果；受影响目标不能并发越过同一编排的切割边界 |
+| 事件与通知 | 写入事件、登记通知需求、列出待处理项、确认处理；按事件 ID 去重并拒绝同 ID 的冲突内容 |
+| 读取与展示 | 输出当前一致版本的只读 JSON 视图；页面订阅更新，不直接写入账本 |
+| 恢复与收口 | 校验账本及快照、列出未决操作、记录平台核实结果、服务和资源清理状态 |
+
+每项写操作都携带编排 ID、调用者身份、稳定操作或事件 ID 及预期账本版本。版本不符时返回冲突，由调用者重新读取当前版本并判断；不得以旧内存快照覆盖新状态。重试同一 ID 且内容一致应返回已有结果；同一 ID 不同内容应拒绝。
+
+脚本只裁决账本中的协调条件，不能替代交付协调者（Delivery coordinator） 对子 PR 的验收，也不能将缺失平台事实视为通过。外部 PR、CI、发布和部署事实须由对应平台操作或查询核实；计划外行为须经过主人决定。
+
+## 写入、锁与崩溃恢复
+
+```text
+读取当前版本
+取得本编排写锁
+  重新读取并校验版本、身份、依赖及操作条件
+  产生包含状态和事件的完整下一份 JSON
+  写入同目录临时文件并持久化
+  原子替换账本，并保留上一份完整快照
+释放写锁
+```
+
+实现使用操作系统支持的进程间锁和同一文件系统内的原子替换。不能用“锁文件存在”或仅凭锁文件时间来判断持锁进程是否失效。锁的创建、持有、超时和进程退出行为需有可复现测试；快照更新和目录持久化按下述顺序执行。
+
+固定实现方案为 Bun 的 `bun:ffi` 加载系统 C 库调用 `flock`，打开不随账本原子替换而更换 inode 的 `<run>/locks/ledger.lock`，用非阻塞排他锁和有界重试取得锁；句柄在 `finally` 中释放，进程退出由操作系统释放。读取系统错误码区分锁忙与其他系统错误，不能把全部失败都当成竞争。锁文件仅由创建该 run 的流程建立，运行中不删除、不换名；不得依据文件存在、PID 或时间直接强制解锁。当前 macOS 使用 `libc.dylib`；Linux 动态库路径须在目标环境探测，无法加载或无法取得锁时停止写入。上述锁只针对同一 run，并非跨编排锁。
+
+在锁内的确定写入顺序：校验当前账本；把当前完整字节写入同目录的 `previous.tmp` 并 `fsync`，原子替换 `ledger.previous.json` 后 `fsync` 目录；将新账本写入唯一同目录临时文件并 `fsync`；原子替换 `ledger.json` 后再次 `fsync` 目录；最后释放锁。临时文件使用独占创建且限制权限。任一步失败返回错误；若 `ledger.json` 已替换但响应未返回，调用者以同一请求 ID 重试，由账本的幂等记录判断，不重新执行外部操作。仅在锁内打开账本并完整读取，避免读取到中间版本。
+
+外部合并不能依靠短期写锁包住整个网络请求。脚本先登记**持久操作占用**，释放写锁后由 Agent 核对平台并执行操作，再以同一操作 ID 写入结果。切割开始时先取得相关目标的切割占用，阻止新的相关合并，并等待已有占用完成或查明；随后固定 SHA 并一次性写入分配变化。
+
+```mermaid
+flowchart TD
+    A[登记合并占用] --> B[核对 PR 与目标 SHA]
+    B --> C[调用平台合并]
+    C --> D{结果是否确定}
+    D -->|是| E[记结果并结束占用]
+    D -->|否或进程中断| F[保留待核实占用]
+    F --> G[查询平台的实际 PR 和合并事实]
+    G --> H[记录结果或保留阻塞]
+```
+
+账本或快照损坏时不得静默回退到可能丢失操作占用的旧版本。恢复需先隔离损坏数据，核对版本、操作占用及平台事实；不能确定时保留阻塞并向主人说明。旧快照用于恢复证据，不自动证明其中未记录的合并没有发生。
+
+## 本机只读服务与通知
+
+服务通过脚本取得一致的账本视图，向浏览器提供初始快照及变更推送；断线重连时发送当前完整版本。页面不得写入账本或运行事实；服务仅额外提供 tokenized 的 `GET/POST /api/preferences`，且只允许写入 schema-1 的全局主题偏好。其余视图、事件和文档接口保持只读。服务仅监听本机，并限制允许的资源和来源；要求文档只按账本中明确引用的路径提供，不能提供任意文件读取。数据中不存放凭据或敏感令牌。
+
+服务启动前按现有全局端口租约流程申请并注册端口；`serve.ts` 负责登记自身 PID、心跳和退出释放自己的服务租约，不接管其他进程或端口。向主人提供可持续访问的 URL 前，Agent 必须确认当前任务由 Codex host 提供且仍被保留的 native background session 和有效租约。Skill 不创建或推断该宿主会话；没有受支持的宿主后台路径时只能保留 live preview。
+
+需要主动通知的事件先提交账本事实和通知意图，再由 CLI 调用 Codex Agent API；确认状态也写入账本。一般阻塞只需记账并留在相应任务或交付单元对话；确实影响调度时才使用 `notification.mode: "deliver"` 通知指定收件会话。断线、发送失败或确认缺失时，待处理通知保留并可通过 `notification-reconcile` 恢复查询；`unknown` 在平台对账前不得直接重试，恢复器不得伪造发送或 ack。
+
+## 验证与待核实技术点
+
+- 模型：无环校验、子任务分组造成的等待、动态切割后的历史归属、显式依赖和条件。
+- 并发：多个进程并发更新、版本冲突、重复事件、同一目标合并与切割竞争、不同目标的合法并发。
+- 恢复：在临时文件写入、替换、占用登记、平台请求和结果记账各阶段中断；验证不会丢失事件、重复派发或盲目重复合并。
+- 身份：创建请求结果未知、实际会话未绑定、fork 控制权不明确及恢复时的平台事实核验。
+- 页面：数据版本一致、推送和断线重连、只读边界、路径限制、链接可用性和端口租约。
+- 已做基础可行性验证：当前 macOS 的 Bun 1.4.4 可通过 `bun:ffi` 调用 `flock`，另一 Bun 进程对同一对象的非阻塞锁请求在锁被持有时失败、释放后成功；当前机器可对目录执行 `fsync`。这不证明其他操作系统、文件系统或全部崩溃恢复场景可靠。
+
+## 对话输出投影
+
+服务只读取 run 内任务绑定的 `thread_id`，通过已有 app-server socket 执行 `initialize`、`initialized` 及只读历史读取，不开放任意对话代理接口。对已绑定且 `thread/loaded/list` 确认存在的会话，可仅传 `threadId`、`excludeTurns: true` 调用 `thread/resume` 加入订阅；不传配置覆盖、历史或路径，不发送消息，不调用 `turn/start`。未加载会话仍只读历史。优先 `thread/items/list` 倒序分页；明确不支持时退回 `thread/turns/list` 的完整 items，旧 `thread/read includeTurns` 仅在确认协议支持时使用。
+
+`latest_agent_output` 包含 `state`（`available | no_conversation | empty | unavailable`）、`text`、`thread_id`、`turn_id`、`message_id`、`phase`、`message_status`、`observed_at` 和 `stale`。快照以服务实例 `output_epoch` 和实例内单调 `output_revision` 标识；内存缓存按 thread 去重，观察结束释放连接。可用的原生通知按 turn/item identity 合并；完整消息覆盖同项增量，历史请求不能覆盖更新的事件或重绑结果。增量推送最多每 100ms 一次，完成与错误立即推送。
+
+为补齐重连和宿主缺少通知时已落盘的回答，观察期间默认每 2 秒补读历史；连接或读取失败按 1、2、4 秒至最多 30 秒退避。补读成功且无新消息不使投影过期，也不产生输出版本变化。该路径不宣称提供原生 delta；旧 `includeTurns` 未获能力证明时保持不可用。
+
+桌面与独立 app-server daemon 可能是不同实例。`CodexDesktopFollower` 只使用当前用户拥有的桌面 IPC socket，按已绑定 thread 发现现有 owner，以跟随通道获取公开 assistant 快照和文本补丁。只支持已核实的 stream version 11；按平台 islands/entries/item 顺序选择消息。保留索引占位但丢弃工具、用户与推理正文；验证 owner 和本地 host，重复旧版本丢弃，revision 缺口重新订阅取得快照。取消绑定及连接结束释放跟随关系；它不暴露任何执行或配置控制请求。
+
+- 会话链接：当前候选已证明真实 ID、原生 `codex://threads/<thread_id>` 锚点合同，并记录了 Codex 原生导航结果，证据见 `skills/multi-task-flow/examples/orchestration-viewer/link-verification.json`。该记录不声称证明宿主浏览器点击桥接；后续候选只有在链接合同或绑定身份变化时才需要新的观察；不得编造链接或自动重复创建。
+
+## 执行配置与创建接口
+
+每个新运行持有一个完整的 `config.execution_profile`。对象的 `execution_profile=null` 独立解析到该默认值；交付单元配置不参与任务解析。`execution_profile_source` 与版本化 `execution_profile_rule` 记录手动选择或类型推荐的来源，推荐只有新对象或显式重新应用时物化。
+
+`execution-profile-update`、`execution-profile-default-update`、`execution-profile-recommend` 与 `execution-profile-migrate` 使用标准 request/revision/owner envelope。CLI 与认证 dashboard 的 `/api/execution-profile` 共用 mutation contract，能力组合来自 app-server `model/list`。缺失默认 pair 的旧运行可以读取，写入须先显式迁移；schema2/contract2 任务缺少 execution policy 键时，普通写入先由 `HISTORICAL_LEDGER_READ_ONLY` 拒绝，独立的 contract maintenance 只能补显式 null，不能推断执行归属、对话或交付事实。
+
+`dispatch-claim` / `dispatch-group-claim` 捕获完整有效 profile，`conversation-create` 绑定唯一 native request ID，再通过独立的 `codex exec --worktree --json` 进程创建、命名和初始化线程。创建 adapter 必须核对返回的实际模型与思考强度；返回值不是请求配置的自我回显。只有真实 thread ID 与匹配 request/operation/profile 的 CLI 证据才能成功绑定。unknown 保留 claim 和已观察到的 thread ID，对账通过 `dispatch-resolve` 记录匹配证据；禁止自动重复创建。初始化首条消息只确认握手并在进程退出后由主对话通过内置 `send_message_to_thread` 发送正式任务。
+
+已有 thread 或尚未明确失败的 native request ID 都冻结对象配置。编辑无 native request 的 claim 时保留旧 pair 与原因、终止旧 claim，并要求重新 claim；运行默认值更新保留已冻结对象的原有效配置。对话创建后的会话内模型调整不进入该账本。
+
+## 主人授权的维护迁移
+
+service 的 `ledger-maintenance-check` / `ledger-maintenance-apply` 提供独立维护边界；它们与 orchestration 的 bound-main migrate、service 的目录导入 migrate 各自独立。合同与完整 execution profile 分别授权；对 schema2/contract2 的历史策略键缺口，`action: "contract"` 把完全缺失的字段声明为 null，部分声明则拒绝，普通 migrate 不扩大范围。维护请求保留准确 owner、revision、源文件摘要、动作摘要、实际维护线程、批准引用和暂停写入声明，不改变控制权。提交使用维护锁、run 锁、完整 `ledger.maintenance-<request_id>.json` 备份、原子替换及 request 幂等；同 ID 异内容拒绝，已提交重放先于旧 revision 校验。源/目标均须被已安装 viewer 读取，未决 claimed/unknown 操作拒绝。详细 JSON 输入及恢复步骤以 Skill 的 shared-viewer 引用为准。

package/toolkit/skills/docs/vendor/dot-codex/design/multi-task-flow/dev-plan-bridge.md

@@ -0,0 +1,41 @@
+# Retired Dev-plan Bridge for Multi-task Flow
+
+> Retired by [ADR 0040](../../adr/0040-dev-plan-standalone-typescript-finalizer.md). This file remains only as read-only historical compatibility documentation. New `$dev-plan` and `$multi-task-flow` flows MUST NOT use this bridge.
+
+## Boundary
+
+`multi-task-flow` is an active top-level `flow_type` in `$dev-plan`. The plan selects exactly one top-level flow skill, `$multi-task-flow`, and carries the owner-facing facts needed to approve a dependency-driven run.
+
+The plan's canonical `batch -> wave -> task` hierarchy is a projection format. It preserves task identity, dependency edges, owned surfaces, dispatch profiles, and acceptance scopes for review. Waves group display and dispatch cohorts; they do not create an implicit global barrier for the runtime scheduler.
+
+## Handoff
+
+After the owner approves the plan, the coordinator passes a transient `dev_plan_handoff_source` to `$multi-task-flow init`. The source contains the owner-supplied opaque raw-plan digest, canonical task surfaces, and canonical acceptance scopes. The runtime bridge derives task IDs from the already parsed canonical plan nodes, computes the acceptance digest, attaches the envelope in memory, and then validates it before `LedgerStore.create`. It does not persist a handoff artifact or reparse owner-facing Markdown. The resulting init payload contains the following `initial_plan.dev_plan_handoff` envelope:
+
+```json
+{
+  "flow_type": "multi-task-flow",
+  "raw_plan_digest": "<owner-supplied opaque sha256 digest>",
+  "acceptance_digest": "<sha256 of the canonical acceptance scopes>",
+  "task_ids": ["task-a", "task-b"],
+  "task_surfaces": [
+    {"task_id": "task-a", "owned_surfaces": ["src/a"]},
+    {"task_id": "task-b", "owned_surfaces": ["src/b"]}
+  ],
+  "acceptance_scopes": [
+    {"acceptance_id": "A1", "scope": "batch:core", "owner_id": "core"},
+    {"acceptance_id": "A2", "scope": "task:task-a", "owner_id": "task-a"},
+    {"acceptance_id": "A3", "scope": "task:task-b", "owner_id": "task-b"}
+  ]
+}
+```
+
+The runtime verifies the envelope's digest shape, task-node identity, exact initial group ownership, repository-relative disjoint owned surfaces, canonical acceptance digest, and complete group/task scope ownership before `LedgerStore.create`. A missing or mismatched envelope fails with `INVALID_PLAN_HANDOFF` and creates no run files. After a dynamic cut, a changed task group requires both the cut event and assignment history. The raw-plan digest is the identity supplied by the approved `$dev-plan` boundary; runtime validates its shape and preserves it but does not derive or authenticate it from Markdown. The ledger is a runtime state store, not a second plan or a replacement for the owner-facing acceptance contract. The coordinator owns group and parent-PR closeout.
+
+Owned-surface comparison is lexical and repository-relative. This runtime boundary does not resolve host filesystem case-folding or symlink aliases; the approval boundary must provide canonical repository-relative paths when host-equivalent aliases matter.
+
+For programmatic callers that already carry an envelope, `init` accepts the equivalent `initial_plan.dev_plan_handoff` form directly. A caller must not send both forms: the source is the single approved-plan-to-runtime transfer boundary.
+
+An individual task may enter `$fast-flow` for its direct PR. That nested flow owns only the task's implementation, validation, review, and direct PR stop condition. It must not alter the parent `flow_type`, create a second top-level flow binding, or claim group completion.
+
+Historical `wave-thread` plans remain a separate replay-only compatibility route and are not upgraded by this bridge.

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

@@ -0,0 +1,122 @@
+# 编排执行方案
+
+本文用于审阅新编排 Skill 的运行方式，与[任务编排方案](orchestration.md)配套。目标是使多个 Agent 在同一编排中可靠地共享进度、协调合并与切割，并让主人查看实时状态。数据契约见[数据与脚本方案](data-and-scripts.md)，页面设计见[网页模板方案](web-template.md)。
+
+## 组件与职责
+
+### 主 Agent（main Agent） 的首次交付顺序
+
+收到明确的任务编排请求后，主 Agent（main Agent） 先核对当前会话是否绑定未完成 run；若没有，则构造并校验 planned 任务图，调用 `orchestrate.ts init` 写入正式账本。随后调用 `service.ts ensure` 和 `service.ts login`，按 `skills/multi-task-flow/SKILL.md` 的 Dashboard browser route 使用当前宿主可用的内置浏览器打开对应 run 页面，确认真实 revision、任务节点和依赖。任务保持 `planned`，除非主人另行授权派发或外部操作。
+
+proposal、Markdown requirements 和 Mermaid 只能作为输入或补充材料，不能作为首次交付。任一步骤失败都必须报告具体阶段、命令结果和阻塞。
+
+```mermaid
+flowchart LR
+    U[主人] --> MAIN[主 Agent（main Agent）：调度与记账]
+    MAIN --> GROUP[交付协调者（Delivery coordinator）：父 PR 与子 PR 验收]
+    MAIN --> TASK[任务 Agent（Task Agent）：贡献或交付子任务]
+    GROUP --> SCRIPT[Bun + TypeScript 固定脚本]
+    TASK --> SCRIPT
+    MAIN --> SCRIPT
+    SCRIPT --> DATA[JSON 账本及快照]
+    DATA --> SERVER[本机只读服务]
+    SERVER --> UI[HTML：流程图与两张甘特图]
+    GROUP --> PLATFORM[代码托管、CI、发布与部署平台]
+    TASK --> PLATFORM
+```
+
+主 Agent（main Agent） 创建和直接管理交付协调者（Delivery coordinator）、任务 Agent（Task Agent），维护全局依赖、归属和收口。交付协调者（Delivery coordinator） 只是主 Agent（main Agent） 委派的交付单元级协调者，负责父 PR、贡献子 PR 的验收及合并条件；任务 Agent（Task Agent） 负责所属子任务和相关 follow PR。贡献、发布、部署、验证和协调任务都按需调度；非贡献任务无需强制创建 PR。交付单元是虚拟整合边界，不是原生会话层级，也不转移主 Agent（main Agent） 的直接管理权。
+
+实际 PR、CI、发布和部署状态以对应平台事实为准。账本记录计划、协调状态与证据引用，不因记录一条事件就自行证明外部操作成功。
+
+## 首个交付单元
+
+主对话保留前期 SPEC、ADR 和任务编排的原工作区，在初始化 planned bootstrap 后直接承担首个父 PR 的完整协调职责。账本通过 `delivery_unit_kind=bootstrap`、`owner_kind=main` 表达该边界，以 run 的 `control.owner_thread_id` 解析实际 owner，而不伪造 group dispatch。后续 regular 单元通过正常 dispatch 绑定独立会话。bootstrap 的子任务仍可并行运行，父 PR 的验收、合并、CI 和收口条件保持一致。
+
+新增约束在完整账本校验执行，计划修订会比较已有单元的类型、owner 和会话绑定。当前版本拒绝既有单元原地转移所有权；需要改变职责边界时保留旧 run 的真实历史，由主人明确决定新的编排，不把 task-migrate 当作 group 所有权迁移。
+
+## 本机数据与工具
+
+在运行时 `multi-task-flow` Skill 目录内部建立 `data/` 及其 `.gitignore`，目录本身保留，运行数据不进入版本控制。每个编排使用独立、稳定的编排 ID；会话 ID 与编排 ID 分别记录，通过绑定信息关联。
+
+```text
+<multi-task-flow Skill 目录>/data/
+├── .gitignore
+└── runs/<编排 ID>/
+    ├── ledger.json           # 计划、当前状态和事件
+    ├── ledger.previous.json  # 上一份完整快照
+    ├── requirements/         # 交付单元和任务的 Markdown 要求
+    └── view/                 # 该编排的 HTML、JS 和 CSS
+```
+
+目录名和内部格式由实现确定。Skill 自带模板及 Bun + TypeScript 脚本；安装或更新 Skill 时须保留未完成的运行数据。当前方案只考虑所有相关会话在同一台机器上运行。
+
+JSON 必须通过固定脚本读取和修改，Agent 不直接编辑。脚本提供任务和交付单元的状态更新、事件与通知、操作占用、切割和会话绑定等操作；具体接口见[数据与脚本方案](data-and-scripts.md)。Markdown 要求文档由 Agent 按需编写维护，不要求脚本生成或做硬校验。
+
+## 记账与恢复
+
+每次修改通过同一编排内的锁串行化：读取最新账本，检查版本和必要条件，将状态和事件一起写入临时文件，并原子替换账本；保留上一份完整快照。记录稳定的事件 ID，重复事件不得重复派发或重复推进。损坏或版本不一致时停止写入并报告，不能自行猜测恢复结果。
+
+文件锁只保护账本写入；它的释放不代表外部操作完成。合并、切割等跨步骤操作还需要账本中的**持久操作占用**，记录目标、身份和进度。进程中断后先核实外部平台事实，再恢复、结束或重新安排操作；结果未知时不得盲目重试。
+
+计划批准时记录实际授权范围。执行时以明确授权、当前目标、SHA、检查和验收证据为前提。未授权的计划外外部操作或范围变化不能由账本自行批准。
+
+## 合并与动态切割的协调
+
+同一编排中的任务 Agent（Task Agent） 和交付协调者（Delivery coordinator），无论执行什么 PR 合并，都要先通过固定脚本检查账本、目标和状态，取得相应操作占用；需要等待时登记等待或通知需求。
+
+```mermaid
+sequenceDiagram
+    participant A as 执行 Agent
+    participant L as 账本脚本
+    participant P as 代码托管平台
+    A->>L: 检查归属、状态并登记合并占用
+    L-->>A: 允许、等待或需要协调
+    A->>P: 核对实时 PR、基线和检查后合并
+    P-->>A: 返回合并结果
+    A->>L: 记录外部结果并结束占用
+```
+
+动态切割使用同一协调机制：先阻止新的相关合并占用，等待已登记的相关合并得到明确结果，核对父分支 SHA，再原子记录切割、实际归属和下一交付单元待办；尚未完成的贡献任务转入下一交付单元，已切出的交付单元的发布、部署和验证等后续任务留在原交付单元。任务继续执行，下一父分支按编排方案在主干合并后建立。外部状态若与账本不符，暂停受影响操作并核实。若代码托管平台因 update-branch 推进同一父分支，交付协调者（Delivery coordinator） 必须通过 `group-base-reconcile` 提供旧 SHA、新 SHA、同一父 PR、分支、provider 和 update-branch 证据；该记录不会伪装成 merge/follow PR，受影响任务仍需按新的 `current_sha` 重新建立基线。
+
+锁和协调仅覆盖同一个编排，不对其他编排或项目建立全局限制。即使如此，执行前仍须核对实时平台状态，处理目标分支漂移或代码冲突。
+
+## 通知、阻塞与用户介入
+
+需要通知主 Agent（main Agent） 的关键事件先记到账本，之后发送，并记录处理确认。包括会话创建成功、PR 合入、任务完成，以及需要调度的其他变化。通知失败或会话中断时，待处理通知保留；恢复后按事件 ID 去重处理。
+
+一般阻塞不必主动通知主 Agent（main Agent）：交付协调者（Delivery coordinator） 或任务 Agent（Task Agent） 将状态和原因写入账本，在自己的对话中等待主人；主人可从 HTML 或 Agent 界面进入相应会话处理。确实需要主 Agent（main Agent） 重新调度时，才通知主 Agent（main Agent）。等待期间可释放执行名额，但依赖它的后继不能因此启动。
+
+主人可直接在交付单元或任务对话中作决定。若变更影响其他任务的范围、依赖、验收或调度，相关 Agent 先记账并通知主 Agent（main Agent） 协调；仅影响本任务内部执行的决定由该 Agent 处理。交付协调者（Delivery coordinator） 的验收职责来自主 Agent（main Agent） 委派，不改变主 Agent（main Agent） 的直接管理权。
+
+follow PR 合入后，负责它的 Agent 通知主 Agent（main Agent）；主 Agent（main Agent） 再通知受影响且尚未完成的任务 Agent（Task Agent） 更新基线。任务“已集成”与“已收口”分开记录：前者可解锁后继，后者要求相关检查和已知 follow PR 结束后才归档会话、清理资源。
+
+## 页面与本机服务
+
+Skill 提供以 daisyUI 和 Tailwind CSS 为基础的模板，尽量使用单个 HTML 和少量 JS、CSS。图形依赖及是否使用前端框架由实现时按实际需要选择。每次编排从共享模板生成自己的页面，主 Agent（main Agent） 可按项目调整外观和展示；模板保持不变，页面不能隐藏依赖、阻塞和实际进度等关键信息。
+
+由 Bun 启动只监听本机的只读服务，从账本提供当前视图并推送后续更新。服务使用端口租约；`serve.ts` 在 registry 锁内原子校验预分配租约，拒绝已有 owner 的重复启动，持锁绑定 listener，并只在 listener 确认后登记自身 PID，运行期间心跳，退出时只释放自身服务租约。连接中断时页面明确显示，不能把旧信息冒充实时信息。页面支持流程图、理论和实际甘特图、筛选、详情，以及对话、PR 和要求文档链接。技术实现须验证各类链接在实际运行环境中可打开。
+
+Agent/host 负责取得并保留真正的 Codex native background session；Skill 只接收宿主实际提供的 `agent_session` 元数据，不创建、猜测或用可见终端/前台 exec 替代它。没有受支持的宿主后台路径时，服务只能用于当前回合验证，不能交付 owner-facing URL。
+
+页面不修改账本，也不执行派发、切割或合并；外部状态仍通过对应平台核实。理论安排保留计划版本及估时依据，实际视图使用已记录的真实时间。
+
+## 绑定、完成与清理
+
+编排 ID 独立于会话 ID。fork 或恢复后，如果可验证的信息不足以确定是继续原编排、转移控制权还是开始独立编排，实际需要使用账本时询问主人；控制权不明确期间暂停派发、切割和合并，避免两个主 Agent（main Agent） 同时驱动同一编排。
+
+交付单元完成需满足父 PR 合并、相关 CI、计划中的后续任务和已知 follow PR；全部交付单元和主任务条件完成后才报告全部完成。完成后先保留账本和页面供主人查看；主人确认查看或明确执行收口时，停止服务并只清理该编排的数据目录。未完成或需要恢复的记录保留，其他编排不受影响。
+
+## 对话创建与桌面交接
+
+本节规定本机 CLI 创建与桌面交接合同；ADR 0046 替代 ADR 0044 的创建传输决定。源码测试不能替代当前候选的桌面接管实证。
+
+组对话与任务对话统一通过独立 CLI 进程的 `codex exec --worktree --json` 创建，沿用账本锁定的模型和推理配置、dispatch claim、请求身份和结果对账机制。覆盖范围为本机；远程主机创建另行设计。桌面能识别实际线程和工作区是验收依据，`project_id` 为空不单独判失败。
+
+每个组建立基线前获取远程主干，固定并记录具体 commit SHA；获取失败暂停该组派发，不退回旧缓存或当前 checkout 的 HEAD。子任务在 Codex 创建的工作区内对齐所属组父分支的已核验 commit，以继承组内已完成的依赖。远程主干后续更新通过显式同步推进，不自动移动已有工作区的基线。`--worktree` 默认起点只记录为 initial_head；创建成功不要求它已对齐开发基线。正式工作回合内安全对齐基线，通过 workspace readiness 后才能进入 running。
+
+创建与正式工作分开。CLI 首轮仅回复初始化确认，不调用工具或执行实际任务；取得真实线程 ID，确认独立 worktree 与起始 commit、初始化回合完成且 CLI 退出后，才完成创建成功的账本绑定。主对话随后通过桌面内置 `send_message_to_thread` 发送正式工作指令与后续调度消息，不以外部 CLI 启动长时间工作回合。发送接受、账本绑定与实际开工分别记录，不将消息接受视为任务已经运行。
+
+发送通道的桌面接管行为须实测。目标是缩短 CLI 持有时间，本次不要求解决外部运行回合的底层占用机制；若内置发送仍导致桌面无法接管，应明确报告限制，不静默退回长时间 CLI 执行。CLI 创建过程超时、进程异常或结果不明时保留 claim，核对真实线程、工作区与回合状态后恢复，不自动重复创建。
+
+新方式适用于升级后尚未发起的创建操作，包括既有运行后续新建的任务。已有对话保留线程和工作区，结果不明的历史创建先对账，不自动重建、迁移或打断正在运行的 CLI 回合。

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

@@ -0,0 +1,106 @@
+# 任务编排方案
+
+本文用于审阅新编排 Skill 的设计。它描述如何从需求得到可调度的任务图，不授权启动实际贡献、创建 PR 或发布。执行和恢复机制见[执行方案](execution.md)。
+
+## 目标与范围
+
+新 Skill 服务于一个包含一个或多个父 PR 的交付任务。它先建立原子任务关系，再组织子任务与父 PR，按照依赖和实际进度调度。目标是在尽早交付可发布成果的同时，控制并发、冲突和协调成本。
+
+该 Skill 与历史协调会话并存。历史会话保持原样；新方案不使用旧调度语义，也不自动迁移旧会话。PR、发布、部署和清理等专项操作继续复用对应流程。
+
+## 编排单元
+
+| 单元 | 含义 | 主要责任 |
+| - | - | - |
+| 主任务 | 一次完整交付的编排 | 主 Agent（main Agent） 建模、创建会话、调度并汇总完成状态 |
+| 交付单元 | 共享父分支和父 PR 路径的子任务虚拟整合单元 | 主 Agent（main Agent） 直接管理；交付协调者（Delivery coordinator） 受委派处理交付单元级父 PR 协调、子 PR 验收和收口证据 |
+| 子任务 | 可独立调度和追踪的工作 | 任务 Agent（Task Agent） 按需执行；贡献任务通常对应一个子 PR，非贡献任务对应操作目标和完成证据 |
+| 原子任务 | 编排时不可再拆分的最小工作单元 | 在所属子任务内串行完成，不要求是功能上的绝对原子 |
+
+交付协调者（Delivery coordinator） 和任务 Agent（Task Agent） 是平级会话，均由主 Agent（main Agent） 按需创建和直接管理。交付单元是账本中的虚拟整合边界，不是原生会话的父子层级；`group_id` 只表达任务的虚拟分组、父 PR 路径和批次验收范围。交付协调者（Delivery coordinator） 负责在主 Agent（main Agent） 授权范围内执行交付单元级父 PR 协调、贡献子 PR 验收和合并条件判断；实际合并由获得相应授权的 Agent 执行。主 Agent（main Agent） 仍保留任务调度、账本、跨交付单元依赖、范围变更和最终收口控制，不因绑定交付协调者（Delivery coordinator） 而转移直接管理权。
+
+## 从原子任务到任务图
+
+1. 明确目标、非目标、验收条件、交付边界和项目基线。
+2. 拆分原子任务，标注各自产出及真实前驱和后继，检查依赖图无环。
+3. 将适合连续完成的一个或多个原子任务组合为子任务，写明目标、范围、依赖、产出、验收和预计修改范围。
+4. 将子任务虚拟分配到一个或多个交付单元，并建模共享父分支上的父 PR 合并、CI、发布、部署、验证和其他后续工作；该分配不建立原生会话父子关系，也不转移主 Agent（main Agent） 的直接管理权。
+5. 按实际依赖和全局并发目标计算理论安排，展示等待与切割选择的成本；主人批准后执行。
+
+子任务内部的原子任务串行执行。跨子任务的贡献依赖以子 PR 合入为交接点，不对外开放未合入的中间成果。
+
+例如，A1 → B1 → A2 中，A1 和 A2 不能放在同一个子任务：否则 B1 既要等待 A 的子 PR 合入，又要在 A2 之前执行。必须将 A1、A2 分为两个子任务。
+
+若 B1 只依赖 A1，A1 和 A2 则可以组合，但 B1 必须等待 A1、A2 一起完成并合入。编排应展示这项额外等待，权衡拆分 PR 的成本和并行收益；允许组合不等于默认组合。
+
+## 依赖与调度
+
+```mermaid
+flowchart LR
+    S[主任务开始] --> G1[交付单元一开始]
+    G1 --> A[贡献任务 A]
+    G1 --> B[贡献任务 B]
+    A -->|子 PR 合入| C[贡献任务 C]
+    B --> M[父 PR 合并]
+    C --> M
+    M --> CI[主干 CI]
+    CI --> D[部署与验证子任务]
+    D --> E1[交付单元一结束]
+    E1 --> F[主任务结束]
+```
+
+上图是示例：C 的前驱满足后即可开工，不需要等待无关的 B。父 PR 合并前仍须满足该交付单元的实际合并条件。
+
+- 只根据明确的子任务或里程碑依赖决定开工时机，不设波次或全局波次屏障。
+- 整个主任务默认同时运行三个任务，可在计划中调整。交付协调者（Delivery coordinator）、主 Agent（main Agent） 和单纯等待外部 CI 的工作不占运行名额；等待主人回复的任务可释放名额。
+- 就绪任务优先考虑能够解除更多后继阻塞的工作，同时尊重资源、基线和实际风险。
+- 多个交付单元可以并行。交付单元之间不自动建立笼统依赖；需要时指向具体的子任务、主干合并、发布、部署或验证节点。
+- 若交付单元 B 的贡献依赖交付单元 A 的代码，B 的父分支须基于包含 A 父 PR 主干合并结果的已验证 SHA；若还依赖 A 的部署或验证，还须等待相应节点。
+- 预计修改范围显著冲突时，优先调整任务边界或安排顺序。轻微重叠不禁止并行；预期外的重叠可以通过更新基线、解决冲突和重新验证处理。
+- 失败或阻塞只阻止其依赖后继；其他就绪任务可以继续。阻塞不自动变成完成或跳过。
+
+## 父 PR 与动态切割
+
+计划可直接声明多个父 PR，也可先将相关子任务安排到一个缺省父 PR，并为动态切割声明一个或多个有序条件。满足条件后，当前缺省父 PR 按实际已合入进度切出，未合入的进行中和未开始任务转入下一缺省父 PR。
+
+```mermaid
+flowchart TD
+    P[缺省父 PR：A、B、C、D] --> T{A、B 已完成且满足切割条件}
+    T --> X[固定当前父分支 SHA]
+    X --> P1[动态父 PR：已合入成果]
+    X --> P2[下一缺省父 PR：未合入的 C、D]
+    P1 --> M[合入主干]
+    M --> BASE[以合并后的主干 SHA 建立下一父分支]
+    BASE --> R[更新 C 的基线和 PR 目标]
+    R --> P2
+```
+
+- 切割时短暂暂停该父分支的子 PR 合入，以已核实的父分支 SHA 作为交接点；其他贡献可继续。
+- 当前交付单元包含该 SHA 实际已有的成果；尚未完成的贡献任务归入下一交付单元，进行中的任务 Agent（Task Agent） 保留原会话。已切出的交付单元的发布、部署和验证等后续任务保留在原交付单元，待该交付单元父 PR 合并后按依赖执行。
+- 进行中的贡献任务可继续推进；下一父分支在前一动态父 PR 合入主干后，基于包含该合并的 SHA 建立。随后更新已有子 PR 的基线和目标并重新验证；暂不向尚未就绪的下一父分支合入。
+- 原交付协调者（Delivery coordinator） 在主 Agent（main Agent） 的委派范围内继续处理已切出的父 PR 及其收口证据；下一交付协调者（Delivery coordinator） 按需创建，主 Agent（main Agent） 始终保留直接管理权。
+- 可以计划多个有序切割条件；每次切割后按剩余任务重新计算，防止重复切割。创建动态父 PR 不需要等待 follow PR。
+- 父 PR 的提交记录可以包含原定内容以外的记录。交付协调者（Delivery coordinator） 应核对实际差异：已有基线历史或不扩大已批准范围的内容可以继续；引入未批准的功能或行为时请主人决定。
+
+如果原父 PR 尚未合入主干，后续 follow PR 可以继续指向原父分支，从而使其 SHA 前进。切割时的 SHA 是**任务归属的交接记录**，不永久冻结最终合并 SHA；follow PR 合入后更新当前 SHA，并在父 PR 合并前重新检查实际差异、CI 和证据，已切出的任务归属不随之改变。
+
+## 交付与完成
+
+贡献子 PR 合入后，子任务进入“已集成”，可解锁相应后继。任务会话在相关检查和已知 follow PR 完成后才“已收口”，避免过早归档；不为假设中可能出现的 follow PR 无限等待。
+
+原父 PR 尚未合入主干时，针对其成果的 follow PR 指向原父分支；原父 PR 已合入时，follow PR 指向主干。follow PR 合入后通知主 Agent（main Agent）；如影响尚未完成的任务，由主 Agent（main Agent） 通知有关任务 Agent（Task Agent） 更新基线。已发现、属于本次交付的 follow PR 在完成前阻止相关交付单元收口。
+
+交付单元的结束条件包含父 PR 合入、相关 CI 通过、计划中的合并后任务及已知 follow PR 完成。所有交付单元和主任务要求均完成后，主 Agent（main Agent） 才报告全部完成。
+
+主人批准完整编排计划时，可以同时授权计划中明确列出的合并、发布和部署；执行仍核对实际目标、SHA 和检查结果。计划未覆盖的发布、部署或范围变化须另行决定。
+
+## 图与时间安排
+
+页面呈现主任务开始和结束、交付单元开始和结束、贡献任务及交付单元的发布、部署、验证等后续节点。依赖图展示真实前驱与后继；颜色或其他可辨识方式标明子任务与父 PR 的归属，动态切割后展示实际归属。
+
+提供两张甘特图：
+
+- **理论安排**：根据任务依赖、全局并发上限和有依据的预计耗时计算，标明估时依据与可信度；无法估计时标为未知，不虚构日期。计划调整保留原安排并产生新安排供对照。
+- **实际进度**：展示真实开始、完成及等待时间；未发生的事件不填成事实。
+
+页面可筛选、展开依赖、查看任务详情，并打开任务对话、PR 和要求文档。它是只读视图，不直接派发任务或执行合并。