镜像自 HugoXK/LaunchPad@5cfa983 · upstream · 在 GitHub 上编辑 docs/task-coordination.md ↗

On-demand task coordination

Task scope is an initial plan. Ordinary scope differences are explained by Dev, checked by Review and judged by QA; they do not require a coordinator. Explicit user constraints and platform capabilities remain binding.

A Task Manager can use list_project_tasks and request_task_coordination for a concrete cross-task dependency or shared-contract issue. The request contains an idempotency key, problem, proposal, same-project task IDs and persistent references. It is written before the source task yields with waiting_coordination. It does not wait for the model while holding a project execution slot.

CoordinationWorker runs only queued explicit requests, one per project in the running control plane. The Coordinator is a controller role with a distinct restricted policy, a native control-plane harness by default, its own role session and retained run/snapshot history. It can read the offered task records and submit advice. It cannot edit code, goals, criteria, permissions, acceptance, task completion or GitHub state. The existing Pi Task Manager remains supported. Existing V2 capability pins are not silently expanded; an older controller policy can be explicitly updated to controller-coordination through normal role configuration/apply. Legacy configurations and new controllers use that policy. A missing Coordinator definition in an older V2 configuration gets the default restricted definition.

The result is a set of concrete notices. Each captures the task contract revision and candidate observed by the Coordinator. Notices do not mutate running tasks or in-flight QA. At a safe submission/acceptance boundary, unresolved notices or a changed coordination context prevent publishing with the old candidate/QA. The task resumes on the same role context, reads notices and acknowledges adopted, not_applicable or disputed with reasons. A new submission binds the current notice/feedback version and gets independent QA, even if the code tree is unchanged. Original policy observations can still be reused when applicable. Old decisions remain history. Delivered tasks retain their historical completion; advice for them is recorded as a followup requirement for the source Task Manager, not an automatic reopening of a merged PR.

An objection requeues that explicit request for the Coordinator. Repeated unresolved rounds stop for an explicit human decision after the bounded attempt limit. Model/tool failures retry up to three attempts with backoff, then expose failed. Explicit human decisions remain needs_human. QA may attach a structured coordination request to its needs_human verdict when the specific issue is actually cross-task; the original verdict is retained, and the framework schedules coordination before waiting for a person. An ordinary fix or extra file must instead return to execution. There is no global inactivity scanner or blanket automatic escalation.

SQLite tables:

task_history retains request, notices, feedback, failures and continuation events; Coordinator role runs use the existing run/snapshot tables. Restart recovers unfinished claims and marks abandoned Coordinator runs interrupted. Replays deduplicate requests and notices. Operators may query GET /api/tasks/:id/coordination and retry a failed/human-wait request with POST /api/tasks/:id/coordination/:request_id/retry, supplying any new instructions via the existing task instruction API. Retries do not approve a delivery.

Regression coverage uses real SQLite and native role execution with a controlled HTTP model. It includes an actual child-process kill during a Coordinator model request, restart continuation, same-project isolation, safe acknowledgement, stale QA rejection and an independent task dispatching while coordination waits. This is not a claim of live Codex/OpenToday acceptance on the new implementation. The running #178 experiment is not silently upgraded by these PRs.

For an actual dependency adjustment, Task Manager can call wait_for_tasks with same-project task IDs, delivered or merged, and a reason. The framework persists the declared wait, rejects cycles and releases the execution slot. Only those explicit dependencies are checked. Delivery/merge resumes the same task; a failed/cancelled/replanning prerequisite wakes it with the blocker facts so it can coordinate instead of silently waiting forever. This does not infer a project-wide plan or scan for inactivity.

Progressive parent/child tasks

The Task Manager decides when decomposition is useful. The repository’s skills/roadmap-decomposition/SKILL.md supplies the method when configured as an ordinary Skill bundle and bound to the Manager; it is not an automatically injected catalog entry. create_task(as_child=true) creates an explicit child in the same project, running the normal project team with its existing authority; ordinary task origins and acceptance follow-ups are not implicitly children. execute=false records unready work without queuing it. The parent decides dependencies and starts work through existing task management; there is no DAG scheduler.

read_child_tasks returns children, their QA/artifact references and durable return events. After handling events, wait_for_children(after_event_id, reason) acknowledges that cursor and yields the parent execution slot until any new child result, successful or not. Other children continue. Failure, cancellation, supersession, explicit pause or help can return control; internal retries and tool completions do not. Already returned results are immediately visible even if they arrived before waiting. A parent with no executing children is not parked on old results. Cancellation is not reversed by a late child result.

The normal task record includes children; trace lineage includes decomposition. read_managed_task reads owned child facts; execution roles can use read_related_artifact for immutable parent/child/sibling files with explicit acceptance status. Source authorization and project boundaries still apply. Child completion never completes the parent: its integrated outcome needs independent QA.

The opt-in test/roadmap.live.test.mjs exercises a real Manager's own decomposition, workers and fresh QA against isolated Git/runner/SQLite with controlled GitHub. Set BOT_ROADMAP_RUNTIME to a private output directory, BOT_ROADMAP_MODEL_DB / BOT_ROADMAP_MODEL_KEY to a private model configuration database/key (model id manager-model), and optionally BOT_ROADMAP_WORKER_HARNESS=codex / BOT_ROADMAP_CODEX_CONFIG for real Codex workers. Run with Node 22: node --test --test-name-pattern='live roadmap' test/roadmap.live.test.mjs. Normal test sets exclude live tests. Source/test artifacts are the delivery endpoint in this case; it does not claim real remote PR integration.

One generic task, granted writes and parent association

Every task create_task (or POST /api/tasks, a Feishu group, the console) creates is one generic task (#814): a goal, criteria, the executor and the writes it is granted. What it delivers is up to its executor, which calls a delivery tool when the work needs one: submit_report always; open_pull_request (fixed candidate, the project's test command, independent QA unless the project turned that gate off, then the Publisher opens or updates the bot PR), post_review (a COMMENT review on a pull request) and github_write (comments, labels, Issues) only while the task holds the matching write pull_request, review or github. Each call checks the grant, the project's capability ceiling and switches and the source's ceiling at that moment; a refusal returns to the executor with its code and the missing condition, and nothing is written. intent="development" and endpoint="reviewable_pull_request" are still accepted and grant pull_request. These tasks need no fabricated Issue number.

The Manager changes a running task's writes with grant_writes(task_id, writes, reason): widening stays within the project's ceiling and switches, the task's source and the Manager's own authority, and is audited (task.grant_writes); narrowing applies at the next call. A Task Manager coordinating a report that turns out to need a code change grants pull_request and delegates the executor again, so the same task opens the PR. A person who manages the project's tasks can do the same with POST /api/tasks/:id/writes. The task details show the granted writes, how they changed and which delivery tools each run started with. Tasks created before #814 (task.development, and requests whose endpoint was fixed at creation) finish on their old path and cannot be granted writes.

as_child=true adds only the explicit parent relationship and return notification. It does not choose a different execution engine or grant writes. Task Managers default to the project team whether the task is independent or a child. Existing source/executor ceilings, project development switches, QA and merge authorization remain effective. A refused creation returns a structured tool observation with created=false and a concrete next action; the Manager can continue coordinating. Cancellation and source-authority failures still stop through their original guards. Old creation replay keys remain recognized.

Facts for agent decisions

When a dependency has been delivered but a checkout lacks it or fetch is unavailable, Manager/Dev may inspect persistent records and read_related_artifact when offered. This is an optional route, not a required first step or permission to change another task. Handoffs can include known task/artifact refs; the worker chooses how to obtain and verify applicable content, retaining its source, version and acceptance status.

Task context and role recovery include a bounded facts section: contract ref, candidate/evidence versions, acceptance binding, workspace checkpoint, recorded publication and recent failures/verifications. Historical approval is not approval of a changed checkout. Full observations remain in the original records. Revision/plan errors return submitted and current values; evidence errors list offered sources and discovery routes. Shared publication/version facts can be paged via read_managed_task(source=...); the Task Manager may read all retained worker records of its own task; other-task access retains its existing scope. These are facts for choosing reads, reuse, retry, verification, coordination or help, not an automatic diagnosis, retry limit or additional blocking step.

Publication facts and recovery

read_publication_context is an on-demand, task-scoped read for Manager and worker entries, including Manager recovery. It distinguishes a created Git commit from a confirmed branch update and PR head. Current remote reads carry observation times; an unavailable read is unknown, and old confirmations remain historical facts. Paged attempt refs and branch-operation refs expand through read_task_record; context carries the discovery route rather than all receipts.

Branch operations are bound to candidate content, expected parent/head, title, date and destination. New candidates do not reuse an earlier QA revision's successful receipt; retries of one operation retain their identity. A branch receipt must match the request, and remote_sha is written only after branch confirmation. Legacy remote_sha alone is not confirmation. Real head divergence preserves the candidate and returns to the existing Manager recovery entry for investigation, resumption, coordination or help, rather than automatically superseding the task. Authorization, ownership, Git fast-forward checks, independent QA and merge policy still apply.

Post-QA follow-up planning uses search_project_tasks(query, task_id, offset) for project task discovery. read_task_record(ref) retains its single meaning across entry points; it reads a retained record by reference.