Task workflow v1 — implementation contract

Status: approved product direction; FLOW-02 server implementation is local and tested. Bridge integration and native presentation remain pending. This document does not describe a deployed feature. Parent: f9929a43-dbb5-45e7-897c-43447064c48c.

Outcome and scope

An operator defines an outcome and acceptance criteria in an MCP client such as ChatGPT. HeyAira records the task and documentation references, issues work to an explicitly selected Bridge, observes initialization and execution, collects an immutable candidate, runs a separate verifier, and closes the task when all agreed criteria pass. The owner explicitly chose automatic agent acceptance on 2026-09-23. Routine completion must not add a human approval gate.

Testing and performance measurement accompany every implementation stage. Result verification is also a first-class part of the product workflow.

The first delivery uses one project, one enrolled Mac, one repository, one worker profile and one verifier profile. Both configurations are immutable, versioned snapshots with explicit model, provider account, instructions and skills. Provider/model selection stays with the operator. Reusable catalog management remains task 4bba7d43-00b0-446b-b1bd-5995950c8909; a broad agent library, automatic routing and multi-node scheduling are not prerequisites. Profile snapshots must be labelled as such: until catalog resolution exists, they must not be presented as automatically resolved Agent Catalog identities.

Sources of truth

• Git owns documentation, instructions, skills, code, candidate commits and evidence artifacts. HeyAira stores bounded references and operational state.
• HeyAira owns the task, frozen acceptance contract, authorized assignment, authoritative phases, attempt history and acceptance decision.
• Bridge owns local readiness, process supervision, workspace checks and attributable execution events. It never invents task acceptance from exit 0.
• The worker produces a candidate. A separate verifier session evaluates that exact candidate against the frozen criteria. The server validates that the verdict is complete, correctly attributed and bound to the current candidate.

Task phase versus execution attempt

Preserve the existing todo/in_progress/blocked/done task API for ordinary continuity tasks. Opted-in workflow tasks expose an additional authoritative phase and attempt reference; clients must not infer phase from a coarse status.

Workflow phase	Meaning / required evidence	Writer	Coarse status
ready	Goal, criteria, configuration and repository references saved	operator	todo
queued	One immutable authorized offer exists	server	in_progress
claimed	Assigned Bridge won an atomic claim and holds a valid lease	server	in_progress
preparing	Bridge is validating/materializing the workspace and profile	Bridge event	in_progress
running	Provider session reports actual readiness/start	Bridge event	in_progress
awaiting_verification	Clean immutable candidate and worker receipt recorded	server	in_progress
verifying	Separate verifier attempt has started for that candidate	server/Bridge	in_progress
changes_requested	At least one criterion failed; attributable feedback exists	verifier decision	in_progress
done	Every required criterion passed with bound evidence and acceptance receipt	server	done
blocked	Missing evidence/dependency, exhausted correction budget or interrupted execution	server/event	blocked
cancelled	Explicit cancellation of this workflow; no later event may reopen it	operator/server	blocked

A successful process exit is an execution outcome, not an acceptance verdict. Each attempt has a unique ID, purpose (work or verify), immutable profile version, session ID, base/candidate SHA, lease/fence, ordered event sequence, start/end times and terminal reason. A retry creates a new attempt. Transport replay uses the original attempt/event identity and cannot duplicate receipts.

Frozen acceptance contract

Before dispatch, bind task ID/version, goal and document references, criterion IDs with descriptions and verification methods, repository/base/branch, worker/verifier profile snapshots, Bridge/provider-account assignment, and resource/correction limits to a contract revision and digest.

Changes to the goal, criteria or executable configuration require an explicit new revision and invalidate pending verdicts. Cosmetic task metadata must not silently rebind a running attempt. Legacy task_update must not bypass workflow acceptance by setting a managed task to done.

A verifier receives the criteria and immutable candidate through authoritative state and Git. Worker messages and artifacts are evidence to assess, not instructions that can override the verifier's role or acceptance policy. Its verdict contains the contract digest, candidate SHA, worker and verifier attempt IDs, a result and evidence references for every required criterion, and bounded explanatory feedback. Missing/duplicate/unknown criteria, stale candidate/contract, unverifiable references and incomplete verdicts cannot pass.

The verifier runs in a separate fresh session and must not modify the candidate. A different model is optional; a different attributable verification attempt is mandatory. Automatic closure reflects the configured checks and verifier's recorded judgement; it does not claim a mathematical proof of arbitrary AI work. The accepting transition and receipt are atomic and replay-safe.

Execution and recovery

1. MCP dispatch validates operator authority, project/Bridge/account binding, task version, profile snapshot, immutable sources and explicit local workspace.
2. An enabled Bridge worker pulls only assigned offers. A node-side policy must explicitly allow the workspace and runtime; the server cannot introduce an arbitrary local workspace merely by sending a path. Initial installation must not silently turn on execution for every project on the node.
3. Claim is atomic. Preparation validates the clean Git base, provider readiness, required tools and any declared MCP dependency. Missing required MCP is a concrete preparation failure, never a ready agent.
4. Materialize only the selected versioned configuration and relevant context. Report readiness, run under the lease, renew and emit bounded ordered events.
5. Worker completion validates the Git candidate and clean workspace and records references. Create the separate verification attempt for that candidate.
6. Complete passing verification atomically closes the task. A failed criterion records changes_requested and can enqueue a correction under the same frozen policy. Start with at most two work attempts per dispatch contract; limits are explicit configuration, not an unbounded self-repair loop.
7. Missing evidence, transient infrastructure failure or exhausted budget blocks with a precise reason. Do not turn these into a substantive failed verdict. Operator retry is explicit; restart must not duplicate an ambiguous claim.
8. Cancellation, expired lease, lost authorization or revoked binding prevents further work and acceptance. Stop the process and preserve available evidence.

Read model and performance

Task reads and Work Center list/detail must expose current phase, active attempt, selected profile version, last event time, blocker/review summary and candidate reference. Details provide bounded paginated history. ChatGPT and Bridge read this same state. Failure does not require finding a terminal window.

Do not put full histories, prompts or evidence bodies into task-list rows. Use bounded batched reads, indexed task/attempt lookup, pagination and cached UI row snapshots. No per-cell sorting, per-row HTTP calls or overlapping periodic probes. Worker concurrency starts at one per node; idle polling backs off and must not block heartbeat, UI or cancellation. Preserve finite lease/execution deadlines.

Initial engineering targets, to be measured and calibrated on the existing Mac and a disposable local database: no UI main-thread preparation stall above 100 ms at 50/500/5000 synthetic rows; idle app CPU below 2% over 30 seconds; local indexed lifecycle/list reads p95 below 250 ms at the agreed fixture size. These are acceptance targets, not claims about measured current performance or public-network SLA. Include cold/warm runs and publish dataset size and hardware.

Delivery order and evidence

Task	Deliverable	Depends on
FLOW-01 ba01f335-aa44-4fdd-9447-22f9954897f9	This contract and automatic verifier policy	owner direction
FLOW-02 37a1b087-a4a4-4924-b05f-fec31dc3f5ee	Server/MCP state, dispatch and acceptance	FLOW-01
FLOW-03 534c9402-df65-448c-ad62-9a985daa4f37	Bridge pickup, preparation, work and verifier runs	FLOW-02
FLOW-04 44e291b9-cdae-40b5-83f7-015a1f7f7871	Native progress and evidence presentation	FLOW-02/03
FLOW-05 96db819f-530d-42bb-a74f-234893cdd937	Integrated candidate and release evidence	FLOW-02/03/04

Every slice includes its own functional, authorization and performance checks. The final exercise covers successful work; intentionally incorrect work followed by a verifier rejection and correction; missing tools/evidence; cancellation; lease expiry; stale verdict; duplicate requests/events; and restart without re-execution. Use actual local MCP/HTTP/PostgreSQL and the actual Bridge runtime. Clearly label synthetic versus real-provider versus live ChatGPT surface runs.

Local implementation is authorized. Push, merge and production activation are a separate concrete rollout step under repository rules. Keep the performance fix 0ae1fadd6ceb0d1e13a897d75fc55f6db318191a in every Bridge candidate.