Agent Orchestrator v2 Coordinated Execution¶

Purpose: - define the post-human-signoff operating model for coordinated multi-agent work, - turn the current manual queue/worktree/review process into an explicit coordinator loop, - keep merge and release authority auditable while allowing role agents to proceed without repeated human scheduling.

Scope: - This is the v2 execution contract for GPUaaS agent coordination. - It builds on Agent_Orchestrator_v1.md, Agent_Queue_Structured_Store_v1.md, Multi_Agent_Lane_Worktrees_v1.md, Multi_Agent_Review_Model.md, and Task_Authoring_Standard.md. - It does not implement auto-dispatch, unattended merge, or release promotion by itself.

1. Operating Intent¶

The human owner remains the product and architecture authority. After a design, architecture, or operational plan is approved, the coordinator becomes the execution authority for converting that approval into queued, dependency-safe work.

Target loop: 1. Human signs off architecture, product intent, or operational plan. 2. Coordinator decomposes the approved plan into a task pack. 3. Coordinator validates dependency order and role ownership. 4. Coordinator dispatches role agents into isolated worktrees. 5. Agents implement one bounded task at a time and record structured evidence. 6. Coordinator routes review, verifies gates, and marks work merge-ready. 7. Coordinator merges to master only after required checks and reviews pass. 8. Release promotion remains human-gated unless a later policy explicitly changes it.

This model makes the coordinator responsible for execution flow, not for replacing architecture judgment.

2. Authority Boundaries¶

Human owner: - approves product, UX, architecture, security, and release-risk decisions, - approves exceptions to queue dependency order, - approves promotion to release/platform-control, - resolves disputes where the queue, contracts, and implementation intent conflict.

Coordinator: - owns queue hygiene, dependency ordering, and role assignment after signoff, - creates or updates task packs from approved designs, - starts, resumes, pauses, or redirects role agents, - enforces handoff evidence and review routing, - decides when a branch is merge-ready, - performs merge to master when all gates pass.

Role agents: - own implementation inside their assigned role/lane scope, - must not expand task scope without updating the queue or getting coordinator approval, - must record exact evidence before requesting review or merge, - must stop on contract ambiguity, dependency mismatch, or unexpected local worktree drift.

Review agents: - D-arch reviews architecture and contract impact, - E-governance reviews process, quality, security posture, and gate adequacy, - review agents do not become the source of task authority; the queue remains authoritative.

3. Coordinator State Machine¶

The v2 coordinator tracks task execution with an explicit state machine:

ready -> claimed -> running -> needs_review -> changes_requested -> running
                                      \-> verified -> merge-ready -> merged -> done

ready -> blocked
claimed -> blocked
running -> blocked
running -> failed
needs_review -> blocked
merge-ready -> blocked

State meanings: - ready: dependencies are done, task definition is valid, and role/lane capacity exists. - claimed: coordinator assigned an owner, branch, role, and optional lane. - running: an agent is actively implementing or validating the task. - needs_review: implementation evidence is present and review routing has been evaluated. - changes_requested: a reviewer or coordinator found required changes. - verified: required tests, evidence, and reviews passed. - merge-ready: branch is rebased, queue/git checks pass, and coordinator can merge. - merged: implementation commit is reachable from master. - done: queue state includes merged commit, completion date, and handoff evidence. - blocked: execution is paused by dependency, policy, environment, or human decision. - failed: coordinator could not complete the task through normal recovery.

The queue store must reject done unless the task has passed through evidence capture. The store may allow emergency overrides, but every override must record actor, reason, and rollback or follow-up action.

4. Task Pack Decomposition¶

After signoff, the coordinator creates a task pack instead of one broad task.

Recommended slices: - ARCH: contract, architecture, ADR, or operating-model decision. - A-backend: services, workers, API handlers, generated server artifacts, backend tests. - B-ui: web UX implementation, frontend API consumption, component tests, e2e slices. - C-ops: runbooks, CI, release checks, observability, platform validation, queue hygiene. - D-arch: architecture and contract review. - E-governance: governance, security, gate, and evidence review.

Task pack rules: - Every implementation task has executable acceptance_checks. - Dependency edges encode merge order before dispatch. - Contract or architecture tasks merge before dependent implementation tasks. - UI tasks must not assume unmerged backend behavior. - Ops validation tasks should depend on the runtime path they validate. - Review tasks are generated automatically when changed paths require review.

5. Queue And Store Model¶

Agent_Queue_Structured_Store_v1.md remains the source-of-truth split: - YAML owns stable task definition and human-reviewable instructions. - SQLite owns mutable execution state and history.

V2 adds coordinator-owned state but does not make git authority ambiguous.

Required store additions: - handoff records, - review records, - command/evidence records, - optional session records, - optional task-pack and parent/child task records, - optional lane records when V2 lane concurrency is activated.

Live SQLite state must not be committed. Human-readable snapshots are exported at handoff, archive, major planning transitions, or explicit governance evidence capture.

6. Handoff And Evidence Records¶

The coordinator must store structured handoff evidence before review or merge.

Minimum handoff fields: - task_id - role - owner - branch - commit_sha - changed_files - acceptance_commands - acceptance_results - started_at - completed_at - residual_risks - blockers - next_recommended_slice

Defect tasks additionally require: - root cause statement, - owning layer/file, - proof command covering the root-cause path.

Evidence records should preserve exact commands and result status. Long raw logs can live outside the queue DB if the handoff stores a stable path or artifact reference.

7. Review Routing¶

The coordinator evaluates review routing when a task enters needs_review.

Mandatory D-arch and E-governance review applies when changed files include: - doc/api/openapi.draft.yaml - doc/api/asyncapi.draft.yaml - doc/api/openapi/** - doc/api/asyncapi/** - doc/architecture/** - doc/governance/** - scripts/ci/** - security, auth, billing, provisioning, terminal, node-agent, or release-runtime paths listed in task policy.

Review records must include: - reviewer role, - reviewer identity, - reviewed commit, - findings, - severity, - fix status, - residual risk, - same-model exception note when review diversity is unavailable.

No self-approval: - an implementation lane cannot approve its own critical-scope change, - D-arch and E-governance must review each other's governance/architecture changes, - same-model review is allowed only with an explicit exception note.

8. Dispatch And Session Adapter¶

The v2 coordinator may use tmux, Zellij, or another runner through a session adapter.

Session adapter responsibilities: - create or resume a role/lane session in the correct worktree, - inject the role startup prompt and task context, - expose current session status, - capture transcript or log pointers, - support pause, resume, and interrupt, - prevent work from starting in the wrong branch or directory.

The adapter must treat roles as configuration. GPUaaS roles such as A-backend, B-ui, C-ops, D-arch, and E-governance are repo config, not core product logic.

Coordinator dispatch is allowed only when: - task state is ready, - dependencies are done, - role/lane capacity is available, - role preflight passes, - branch is based on current origin/master, - no unrelated local modifications exist in the target lane worktree.

9. Merge-Ready Gate¶

The coordinator can mark a task merge-ready only after: - all acceptance checks pass, - required reviews are complete, - handoff evidence is recorded, - branch is rebased on origin/master, - queue validation passes, - queue/git consistency passes, - generated files are present when contracts changed, - changed files fit the task scope or the queue was updated to include the expanded scope.

Merge command behavior: - merge to master with fast-forward only, - do not merge master repeatedly into role branches, - record merged commit in queue state, - mark task done only after merged commit is reachable from master.

Release policy: - promotion to release/platform-control remains human-gated, - coordinator may prepare release evidence and recommend promotion, - coordinator must use Platform_Control_Release_Promotion_Policy.md for promotion flow, - release-only fixes remain forbidden outside documented incident exceptions.

10. Failure And Recovery¶

Blocked states are used when progress requires an external decision or dependency. Failed states are used when the coordinator cannot recover automatically.

Examples: - dependency not done: blocked - contract ambiguity: blocked - lane worktree contains unrelated modifications: blocked - required tests fail from product defect: changes_requested or running - required tests fail from environment outage: blocked - agent session crashes before evidence: failed or running after resume, depending on recovery - merge conflict: blocked until dependency order or contract ownership is resolved

Every blocked or failed transition records: - actor, - reason, - blocker task or issue reference when known, - next required decision or command.