@loomhelm/multi-task-flow 0.2.6 → 0.2.8

package/toolkit/package.json

@@ -2,7 +2,7 @@
   "private": true,
   "type": "module",
   "packageName": "@loomhelm/multi-task-flow",
-  "packageVersion": "0.2.6",
+  "packageVersion": "0.2.8",
   "compatibilityLine": "compat-v1",
   "skillVersion": "2.7.6",
   "repository": {

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

@@ -48,7 +48,15 @@ Skill 自带 Bun + TypeScript 固定脚本，所有账本操作通过脚本完
 
 ## 账本格式与脚本命令
 
-采用 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`，不生成占位值。
+编码与版本。采用 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 只返回已提交结果；不同内容、版本冲突、损坏或不安全路径拒绝写入。所有持久身份为非空 ASCII 稳定 ID，使用字母、数字、`-`、`_`；文件名不得直接使用未经校验的 ID 或用户路径。
+
+未知值与时间。缺失的生命周期事实保持 `unknown`，不得伪造 publication 或 merge 通过，也不得由普通更新回写旧文件。时间是带 `Z` 的 UTC RFC 3339 字符串；实际发生时间和记账时间分开，未知为 `null`，禁止用当前时间替代未知事实。未知 SHA、链接和会话 ID 一律为 `null`，不生成占位值。
 
 账本顶层字段固定为：
 
@@ -108,6 +116,8 @@ type Ledger = {
 
 各集合以对象 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 |
@@ -117,6 +127,11 @@ type Ledger = {
 | `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` |
@@ -124,17 +139,41 @@ type Ledger = {
 | `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`。这些事实与对象变更须在同一账本更新中提交。
+#### 事件数据字段
+
+| 事件范围 | data 字段与约束 |
+| - | - |
+| 任务时间事件 | `task_id`, `group_id`, `state`, `reason: string \| null` |
+| 交付单元事件 | `group_id`, `state` |
+| `group_atom_updated` | `group_id`, `atom_id`, `state` 和生命周期证据 |
+| `group_execution_updated` | `group_id`, 协调执行状态、原因和等待任务 |
+| 操作事件 | `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 的切割边界、任务状态和下一交付单元的干净创建状态 |
+| 事实、follow PR 和通知事件 | `fact_observed` 引用 `fact_id`，`follow_pr_recorded` 引用 `follow_pr_id`，通知事件引用 `notification_id` |
+
+上述事实与对象变更须在同一账本更新中提交。
 
 `kind` 和 `type` 由固定脚本限定，页面不可增写。任务的运行中和等待时间区间由有序 `Event` 推导；报告事件必须提供可靠来源，未知结束时间不产生伪造的闭区间。`integrated` 只表示贡献 PR 合入，`completed` 表示该项实际工作完成，`closed` 仅在适用的 follow PR、检查及归档条件满足时记录；资源清理仍分别记账。
 
@@ -162,27 +201,42 @@ type Ledger = {
 
 ### 固定命令
 
-| 命令 | `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` 默认按原规则创建通知意图 |
+#### 初始化、计划与任务
+
+| 命令 | 字段与效果 |
+| - | - |
+| `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 发送的在途文件锁继续保护，原生领取不跨工具调用持有文件锁。通知发送接受不代表已读或实际开工。
 

package/toolkit/skills/docs-migrate/scripts/_runtime/compatibility_cli.ts

@@ -0,0 +1,12 @@
+import { basename } from "node:path";
+import { docs } from "./compatibility_docs";
+
+export async function runCompatibilityCli(name: string, argv: string[] = process.argv.slice(2)): Promise<number> {
+  const smoke = argv.includes("--compatibility-smoke");
+  const help = argv.includes("--help") || argv.includes("-h");
+  if (help && !smoke) { console.log(`Usage: bun ${name}.ts [options]`); return 0; }
+  const result = docs(basename(name).replace(/\.ts$/, ""), argv.filter(value => value !== "--compatibility-smoke"));
+  if (smoke && (result === 0 || help)) console.log(`SMOKE dispatched=${basename(name).replace(/\.ts$/, "")}`);
+  if (help) { if (result === 0) return 0; console.log(`Usage: bun ${name}.ts [options]`); return 0; }
+  return result;
+}

package/toolkit/skills/docs-migrate/scripts/_runtime/compatibility_docs.ts

@@ -0,0 +1,115 @@
+import { verifyDocLocks } from "./modules/docs/hardware_locks";
+import { ingestExtract } from "./modules/docs/hardware_ingest";
+import { findNextPlan } from "./modules/docs/next_plan";
+import { generateLegacySpecIds } from "./modules/docs/legacy_spec_id";
+import { parseSpecDriftArgs, runSpecDrift } from "./modules/docs/spec_drift";
+import {
+  planSpecsHygiene,
+  planSpecsMigration,
+} from "./modules/docs/spec_migration";
+import { json, option, rootFor } from "./compatibility_shared";
+
+export function docs(name: string, argv: string[]): number {
+  if (name === "verify_doc_locks") {
+    const result = verifyDocLocks(rootFor(argv), {
+      strictPdf: argv.includes("--strict-pdf"),
+      checkPerms: !argv.includes("--no-check-perms"),
+    });
+    result.lines.forEach((line) => console.log(line));
+    return result.exitCode;
+  }
+  if (name === "find_next_plan") {
+    json(findNextPlan(option(argv, "repo", process.cwd())!));
+    return 0;
+  }
+  if (name === "gen_legacy_spec_id") return legacyId(argv);
+  if (name === "specs_migrate_guard") return migrateGuard(argv);
+  if (name === "spec_drift_check") return drift(argv);
+  if (name === "ingest_mineru_extract") return ingest(argv);
+  return 2;
+}
+
+function legacyId(argv: string[]): number {
+  const args: Parameters<typeof generateLegacySpecIds>[0] = {
+    repoRoot: option(argv, "repo", process.cwd())!,
+    legacyCompat: argv.includes("--legacy-compat"),
+    count: Number(option(argv, "count", "1")),
+    length: Number(option(argv, "length", "5")),
+  };
+  const alphabet = option(argv, "alphabet");
+  if (alphabet !== undefined) args.alphabet = alphabet;
+  const result = generateLegacySpecIds(args);
+  process.stdout.write(result.stdout);
+  process.stderr.write(result.stderr);
+  return result.exitCode;
+}
+
+function migrateGuard(argv: string[]): number {
+  const repo = option(argv, "repo", process.cwd())!;
+  const source = option(argv, "source")!;
+  const branch = option(argv, "branch");
+  const legacyId = option(argv, "legacy-id");
+  const topic = option(argv, "topic");
+  const options = {
+    ...(branch === undefined ? {} : { branch }),
+    ...(legacyId === undefined ? {} : { legacyId }),
+    ...(topic === undefined ? {} : { topic }),
+  };
+  const result =
+    option(argv, "mode") === "specs-hygiene"
+      ? planSpecsHygiene(repo, source, {
+          ...options,
+          renameConfirmed: argv.includes("--rename-confirmed"),
+        })
+      : planSpecsMigration(repo, source, options);
+  json(result);
+  return result.blocked_reason ? 1 : 0;
+}
+
+function drift(argv: string[]): number {
+  const parsed = parseSpecDriftArgs(argv);
+  if (parsed.error) {
+    console.error(parsed.error);
+    return 2;
+  }
+  if (parsed.help) {
+    console.log(
+      "Usage: spec_drift_check.ts [--base-ref <ref>] [--spec-path <path>]...",
+    );
+    return 0;
+  }
+  const result = runSpecDrift(parsed.options);
+  json(result);
+  return result.exitCode;
+}
+
+function ingest(argv: string[]): number {
+  try {
+    const args: Parameters<typeof ingestExtract>[0] = {
+      extractPath: option(argv, "extract-path")!,
+      destDir: option(argv, "dest-dir")!,
+      slug: option(argv, "slug")!,
+      overwrite: argv.includes("--overwrite"),
+      addHeader: argv.includes("--add-header"),
+      keepMineruJson: argv.includes("--keep-mineru-json"),
+      writeLock: !argv.includes("--no-write-lock"),
+      lockGenerated: !argv.includes("--writable-generated"),
+      createReadme: !argv.includes("--no-readme"),
+    };
+    for (const [key, flag] of [
+      ["docSubdir", "doc-subdir"],
+      ["sourceUrl", "source-url"],
+      ["docType", "doc-type"],
+      ["vendor", "vendor"],
+      ["part", "part"],
+    ] as const) {
+      const value = option(argv, flag);
+      if (value !== undefined) args[key] = value;
+    }
+    ingestExtract(args).lines.forEach((line) => console.log(line));
+    return 0;
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    return 1;
+  }
+}

package/toolkit/skills/docs-migrate/scripts/_runtime/compatibility_shared.ts

@@ -0,0 +1,230 @@
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import {
+  parseReplayCases,
+  resolveCasePath,
+  runReplayCases,
+} from "./modules/checks/replay";
+
+export type Analyzer = (path: string) => {
+  findings: Array<{ code: string; line: number; message: string }>;
+};
+
+export function option(
+  argv: string[],
+  name: string,
+  fallback?: string,
+): string | undefined {
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === `--${name}`) return argv[index + 1] ?? fallback;
+    if (token?.startsWith(`--${name}=`)) return token.slice(name.length + 3);
+  }
+  return fallback;
+}
+
+export function values(argv: string[], name: string): string[] {
+  const result: string[] = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === `--${name}` && argv[index + 1]) result.push(argv[++index]!);
+    else if (token?.startsWith(`--${name}=`))
+      result.push(token.slice(name.length + 3));
+  }
+  return result;
+}
+
+export function groups(argv: string[], name: string, size: number): string[][] {
+  const result: string[][] = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    if (argv[index] !== `--${name}`) continue;
+    const group = argv.slice(index + 1, index + 1 + size);
+    if (group.length === size) result.push(group);
+    index += size;
+  }
+  return result;
+}
+
+export function positional(argv: string[]): string[] {
+  const skip = new Set([
+    "--repo-root",
+    "--cases",
+    "--path",
+    "--base-sha",
+    "--output-dir",
+    "--repo",
+    "--remote",
+    "--number",
+    "--sha",
+    "--method",
+    "--expected-base",
+    "--expected-head",
+    "--branch",
+    "--title",
+    "--body-file",
+    "--head",
+    "--base",
+    "--run-id",
+    "--expected-sha",
+    "--tag",
+    "--note-file",
+    "--target",
+    "--event",
+    "--text-file",
+    "--context",
+  ]);
+  const result: string[] = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index]!;
+    if (skip.has(token)) {
+      index += 1;
+      continue;
+    }
+    if (!token.startsWith("--")) result.push(token);
+  }
+  return result;
+}
+
+export function replay(
+  argv: string[],
+  analyzer: Analyzer,
+  expectation: "required" | "exact" = "required",
+): number {
+  const casePaths = values(argv, "cases");
+  const paths = positional(argv);
+  if (!casePaths.length && !paths.length) {
+    console.error("at least one replay path is required");
+    return 2;
+  }
+  let exitCode = 0;
+  const summary = argv.includes("--summary");
+  for (const casesPath of casePaths) {
+    const failures = replayCases(casesPath, analyzer, expectation, summary);
+    if (failures.length) {
+      exitCode = 1;
+      for (const failure of failures)
+        console.error(formatCaseMismatch(failure, summary));
+    }
+  }
+  for (const path of paths) {
+    try {
+      const caseFailures = path.endsWith(".txt")
+        ? replayCases(path, analyzer, expectation, summary)
+        : undefined;
+      if (caseFailures !== undefined) {
+        if (caseFailures.length) {
+          exitCode = 1;
+          for (const failure of caseFailures)
+            console.error(formatCaseMismatch(failure, summary));
+        }
+        continue;
+      }
+      const findings = analyzer(path).findings;
+      if (findings.length) {
+        exitCode = 1;
+        if (summary)
+          console.log(`SUMMARY file=${path} ${replaySummary(findings)}`);
+        else
+          findings.forEach((finding) =>
+            console.log(
+              `FINDING file=${path} code=${finding.code} line=${finding.line} msg=${finding.message}`,
+            ),
+          );
+      } else {
+        console.log(
+          summary
+            ? `SUMMARY file=${path} status=PASS total=0`
+            : `PASS file=${path}`,
+        );
+      }
+    } catch (error) {
+      exitCode = 1;
+      console.error(
+        `FAIL file=${path} ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  }
+  return exitCode;
+}
+
+function formatCaseMismatch(
+  failure: ReturnType<typeof runReplayCases>[number],
+  summary: boolean,
+): string {
+  const actual = failure.actualCodes.join(",") || "PASS";
+  if (summary) {
+    return failure.case.expectFail
+      ? `ERROR file=${failure.path} expected finding ${failure.case.expectedCodes.join(",") || "any"} but saw ${actual}`
+      : `ERROR file=${failure.path} expected PASS but saw findings ${actual}`;
+  }
+  return `CASE_MISMATCH file=${failure.path} line=${failure.case.line} expected=${failure.case.expectedCodes.join(",") || (failure.case.expectFail ? "finding" : "pass")} actual=${failure.actualCodes.join(",") || "pass"}`;
+}
+
+function replayCases(
+  casesPath: string,
+  analyzer: Analyzer,
+  expectation: "required" | "exact",
+  summary: boolean,
+): ReturnType<typeof runReplayCases> {
+  const failures: ReturnType<typeof runReplayCases> = [];
+  for (const item of parseReplayCases(casesPath)) {
+    const localPath = resolveCasePath(dirname(casesPath), item.path);
+    const path = existsSync(localPath)
+      ? localPath
+      : resolveCasePath(process.cwd(), item.path);
+    const actual = analyzer(path).findings;
+    const actualCodes = actual.map((finding) => finding.code).sort();
+    const actualCodeSet = [...new Set(actualCodes)];
+    const expectedCodes = [...new Set(item.expectedCodes)].sort();
+    const matches = item.expectFail
+      ? expectation === "exact"
+        ? actualCodes.length === expectedCodes.length &&
+          actualCodes.every((code, index) => code === expectedCodes[index])
+        : expectedCodes.every((code) => actualCodeSet.includes(code))
+      : actualCodes.length === 0;
+    if (summary) console.log(`SUMMARY file=${path} ${replaySummary(actual)}`);
+    else if (actual.length) {
+      for (const finding of actual)
+        console.log(
+          `FINDING file=${path} code=${finding.code} line=${finding.line} msg=${finding.message}`,
+        );
+    } else console.log(`PASS file=${path}`);
+    if (!matches) failures.push({ case: item, actualCodes, path });
+  }
+  return failures;
+}
+
+function replaySummary(
+  findings: Array<{ code: string; line: number }>,
+): string {
+  if (!findings.length) return "status=PASS total=0";
+  const counts = new Map<string, { count: number; line: number }>();
+  for (const finding of findings) {
+    const previous = counts.get(finding.code);
+    counts.set(finding.code, {
+      count: (previous?.count ?? 0) + 1,
+      line: previous?.line ?? finding.line,
+    });
+  }
+  const details = [...counts.entries()]
+    .sort(
+      (left, right) =>
+        left[1].line - right[1].line || left[0].localeCompare(right[0]),
+    )
+    .map(([code, detail]) => `${code}:${detail.count}@${detail.line}`)
+    .join(",");
+  return `status=FINDINGS total=${findings.length} codes=${details}`;
+}
+
+export function rootFor(argv: string[]): string {
+  return resolve(option(argv, "repo-root", process.cwd())!);
+}
+
+export function printList(valuesToPrint: string[], prefix = "FINDING"): number {
+  valuesToPrint.forEach((value) => console.log(`${prefix} ${value}`));
+  return valuesToPrint.length ? 1 : 0;
+}
+
+export function json(value: unknown): void {
+  console.log(JSON.stringify(value, null, 2));
+}