Handoff protocol 0.1

This document specifies intended behavior for an implementation. The offline kit is not that implementation. Words such as "must" describe the requirements an adapter and controller would have to satisfy before claiming conformance.

Roles and responsibilities

The lead defines the task, owns its acceptance criteria, and conducts the final review. A worker carries out the authorized work. A worker may be a subagent, a separate session, or an external process. The protocol does not require a particular model, vendor, or runtime.

The collector assembles evidence independently of the worker's preferred narrative. The evaluator interprets narrow questions about that evidence. The policy controller checks exact constraints and determines the permitted route. These are responsibilities, not a requirement to create five conversational agents.

The contract comes first

Before execution, a task identifies its problem, revision, owner, candidate, allowed writes, prohibited operations, verification stage, and required criteria. Criteria have stable IDs. Their content and content revisions may change without silently reassigning the IDs to different requirements.

The worker cannot change the active contract or evaluator questions. A later lead directive is recorded as a new authorization attached to the same problem history, rather than a reset of the earlier attempts.

The example profile permits one ordinary repair and at most one shared additional gate continuation before the first lead handoff. Initial implementation is not itself a repair. The extra continuation may address code, tests, or missing evidence, but these uses share a single slot. The lead may subsequently direct up to three further attempts before higher review. This is an example profile, not an instruction to override an existing project's narrower limits.

Evidence collection

The collector starts with the contract's required artifacts and a frozen candidate binding, then enumerates the actual changeset. New, removed, renamed, staged, and unstaged material must be considered where relevant. A commit ID alone does not identify an uncommitted working tree.

Relevant tests, fixtures, runner configuration, dependencies, and neighboring contract surfaces belong in the evidence scope. The collector records omitted or truncated material. A file reference must be resolved to permitted content before the evaluator can assess it.

A digest establishes which bytes were supplied. It does not establish that a test ran, that the runner was trusted, or that the test exercised the intended behavior. Execution results need provenance from the actual runner and a binding to the evaluated candidate. Claims written by the worker remain claims.

Two independent axes

An assessment records whether the evaluator ran successfully: EVALUATED, NOT_EVALUATED, or INVALID. Each evaluated claim retains its raw label and probability distribution. The controller records a separate route such as REVIEW_READY, LEAD_REVIEW, CONTINUATION_ELIGIBLE, or STOP.

CONTINUATION_ELIGIBLE is a recommendation. Only the enforcement component may issue a grant after checking the current scope, policy, candidate, ledger, and authorization. A JSON field naming that route cannot execute or authorize a repair by itself.

REVIEW_READY means that the packet can enter the lead's ordinary review. It is not acceptance. A claim may confirm a violation, so CONFIRMED cannot be mapped to "good" without the question's declared interpretation.

Handling a provisional PASS

The gate checks whether every required criterion has relevant evidence at the agreed stage. Exact metadata checks happen first. Semantic questions address the relationship between the criterion and the actual assertions, observations, or code.

For example, an assertion that a page heading exists does not establish that a reload avoided a second paid operation. A passing assertion about the wrong candidate or time window does not satisfy a requirement for the current one.

A source-only task must not be rejected merely because no production run occurred. The stage determines which claims the supplied evidence can support. A prohibited test is not added to the worker's obligations by an evaluator's request for more evidence.

Handling a BLOCKED report

A useful blocked packet includes the failure, its evidence, the worker's hypothesis, the exact proposed next step, and the intended validation. The hypothesis is labeled as unverified rather than embedded as fact.

The evaluator can assess whether the proposed step is supported. Exact scope and budget checks remain outside the model. A ready hypothesis does not override permission denial, a hard stop, an expired lease, a conflicting owner, or a separately limited external operation.

An existing unused ordinary repair should be used according to its original conditions before a new gate continuation is considered. Missing ledger history never means that zero attempts have been used.

Bounded continuation and replay

A conforming controller reserves the extra slot atomically before starting work, binds the grant to the problem and current candidate, and makes consumption idempotent. Concurrent requests must not each allocate a continuation. A repeated event returns the stored result without issuing another grant or another API call.

After the gate continuation, the worker validates the result and hands it to the lead unconditionally. There is no new semantic round capable of issuing a further fix. A lead directive, threshold change, session restart, or renamed job does not replenish the shared extra slot.

An uncertain execution outcome is reconciled rather than blindly replayed. Changing only the routing threshold may recompute a recommendation from stored probabilities, but it cannot re-execute a previous authorization.

Failure behavior

When the evaluator times out, lacks a key, returns invalid data, or is unavailable, the packet returns to normal lead review with the assessment failure recorded. This fallback never grants extra work. A hard stop or invalid authority remains a stop regardless of evaluator availability.

No task waits indefinitely for the optional evaluator. The reference policy allows one request per frozen packet, no automatic retries, and a total deadline. A project may use stricter limits. Failure to obtain an assessment cannot be represented as semantic INSUFFICIENT or as successful verification.

The decisive integration point

The gate must run after the worker's provisional result and before the final return to the lead. A wrapper that first wakes the lead, asks it to construct the request, and then requests approval for every continuation has not implemented this boundary.

Some savings may still come from reducing mechanical work within a necessary lead turn. Removing intermediate review turns, however, requires evidence that the internal worker-to-gate exchange completed before the lead received its final result.

Final review

The lead receives a concise packet containing what changed, the required criteria, links to the bound evidence, the assessment's limitations, and any consumed continuation. The complete record remains available without requiring the lead to rewrite it.

The lead retains its existing review method and authority. Merge, deployment, production authorization, and completion of the wider product remain separate decisions.