About batches
A batch runs the loop over many Issues. A deterministic batch controller:
- starts ready work within declared capacity;
- holds work whose dependencies or conflicts are not clear;
- keeps scheduling as tasks finish or fail;
- completes only when every obligation has an accepted disposition.
Each task inside a batch keeps the single-task contract unchanged. Its brief freezes at its own dispatch, against the plan current at that moment. The batch controller does not run Developer turns, judge reviews or reimplement task recovery.
A batch of backlog Issues is capacity scheduling only, since backlog Issues declare no dependency edges.
| Role | In a batch |
|---|---|
| Batch controller | Computes eligibility, starts tasks within capacity, holds, completes |
| Operator | Starts an authorized planned batch, inspects status and waits, requests a hold, continuation or cancellation |
| Execution Planner | Proposes a versioned correction when a running task proves its plan wrong. See Roles. |
| Principal | Decides dropped obligations, goal expansion, irreversible trade-offs and unresolved conflicts across batches |
| Developer, Reviewer, Security | Unchanged; each task runs the loop |
How it works
- 1
Start
The controller checks the plan and the caller, records the run, then starts.
- 2
Compute eligibility
After every relevant change, the controller works out which tasks are ready.
- 3
Start ready tasks within capacity
Ready tasks start up to the declared limit. Everything else waits, visibly.
- 4
Integrate task results
Each task reports typed observations back to the batch.
- 5
Complete
The batch completes only when every obligation has a valid terminal disposition.
Start
To start, a batch needs a complete plan, an authorized caller, stable task identities, a readable plan version and a valid host and capability allocation.
Before starting any task, it refuses:
- a missing or malformed plan;
- a dependency cycle;
- an unresolved collision declaration;
- a duplicate active batch identity;
- an unverified execution capability.
Before acknowledging the start, the controller records the batch-run identity, plan version and digest, task identities, policy version, capacity settings, owner epoch and start intent. Repeating the same request returns the same run. Starting a batch never creates missing tasks or invents dependency edges.
Eligibility
On start and after every relevant transition, the controller reads one consistent snapshot. A task is ready only when:
- it is planned and not terminal;
- every required dependency has the declared acceptable outcome;
- no conflicting task or collision-domain reservation is active, including in another batch;
- no hold, unresolved blocker, stale plan revision or uncertain effect forbids the start;
- a capable host and a capacity slot are reserved;
- its own preparation and dispatch gates pass.
Ready tasks start up to the declared limit, in a recorded, stable tie-break order.
- Running out of capacity is a visible wait, not a failure.
- A failed dependency leaves a named wait or a terminal decision. Work is never silently skipped.
- A task waiting for a human action does not satisfy a dependency that needs that action's verified result.
- A dispatch claim is created before launch, so a retry cannot start a second worker on a task.
States
| Level | States |
|---|---|
| Batch | planned, starting, active, waiting_, quiescing, held, completing, completed, failed, cancelling, cancelled |
| Task disposition | ready, running, waiting_, waiting_conflict, waiting_capacity, waiting_host, waiting_plan, held, terminal |
A hold records the target tasks, the reason, the requester, the plan version and a hold identity. It takes effect only when the task controller acknowledges it at a safe point.
A batch stays active while one task waits for a person, if unrelated tasks can proceed.
Task integration
The batch controller uses the public single-task operations: start, status, hold, resume and cancel. Tasks report typed observations: started, progressing, plan_blocker, infrastructure_, held, ready_for_human, completed, failed, cancelled, uncertain_effect.
A plan blocker holds only the affected task and work proven to conflict with it.
Completion
The batch completes only when:
- every obligation has a valid terminal disposition;
- every required human landing action was observed;
- no hold, blocker, disputed revision, uncertain effect or decision remains.
A task waiting for the Principal's merge is not completed.
The Execution Planner
When a running task proves its plan wrong, the Execution Planner proposes a fix to the plan.
When a worker raises a plan blocker
A worker raises a plan blocker only when the task contract prevents correct work: a wrong objective, boundary, Surface, source, dependency, ownership, test obligation, stop condition or sibling interaction. The blocker names the clause, the observed facts, the safe action it attempted and the decision it requests.
Infrastructure, credentials, red checks and ordinary difficulty are not plan blockers.
What the Execution Planner can do
The Execution Planner is a fresh, isolated attempt. It can read the blocker packet, the task's version history, the batch plan and the states of sibling tasks. It has no Developer write access and no authority to publish reviews, land work or rule.
It returns one of: reject_blocker, propose_change, request_, request_human, cannot_resolve.
| Kind | Tools |
|---|---|
| Read | batch_read, task_, task_run_read, related_, evidence_read, change_ |
| Proposal | plan_, plan_, work_, coordination_, human_, blocker_reject |
Rules for a plan change
- It targets the exact plan version inspected.
- It accounts for every objective and keeps the dependency graph acyclic.
- It passes the same gates as an initial plan.
- It waits for safe points, marks superseded evidence stale, and records the old and new versions.
- Dropping or weakening an objective needs a human.
The controller applies a change under a short fenced claim; a stale submission gets a conflict. The old instruction version stays immutable. A task continues only with proof of compatibility; otherwise a linked new run generation starts.
Gates
Each task passes the loop's gates, and dispatch- refuses a single task whose dependencies or conflicts are not ready.
The batch design adds:
- the start refusals above (cycle, collision, duplicate identity, capability);
- per-task eligibility;
- for plan revisions, the same rendering, source, Surface, documentation, conflict and dispatch gates as an initial plan.
Configuration
The design names a declared capacity and capacity constraints in the batch plan, but defines no configuration key.
What gets logged
The design requires each conformance scenario to record telemetry correlation and to be tested with event delivery turned off, to prove telemetry is not control state.