mainark

Agent handoff (MAI-36)

Structured implementer → reviewer communication for the existing PR review path.

Completion boundary

MAI-36 is complete when implementer → reviewer handoffs are structured, auditable, immutable per run, and consumed by the existing review path. It does not establish a general-purpose Mainark messaging protocol.

Principle

Artifacts for facts. Structured messages for state. Natural language for reasoning that would be expensive to reconstruct.

Handoff finalization observes and packages evidence; it does not create validation evidence by default.

Trust boundary

Agent-authored (ImplementHandoffPartial)Mainark-authored (ReviewRequestHandoff)
claims, uncertainty, context.abandonedApproaches, request.focustype, task, producer, intent, artifacts, state, validation, request.action

The implementer writes .mainark/handoff-<ID>.partial.json only. Mainark validates, enriches, and persists the full handoff.

Artifact paths

PathRole
.mainark/handoffs/<ID>/<runId>.jsonImmutable canonical record for one implement run
.mainark/handoff-<ID>.jsonLatest pointer (convenience; not audit history)
.mainark/handoff-<ID>.partial.jsonAgent input consumed at finalize

agent_runs.metadata_json.handoffPath points at the immutable file.

Review consumption

cli/claude-review-pr.sh resolves the handoff via src/cli/resolveHandoffForReview.ts and injects it into the Claude prompt.

  • The ticket / AC remain source of truth.
  • intent is a projection of the task description for convenience.
  • Claims are untrusted — the reviewer verifies or falsifies using git diff and tests.
  • Missing handoff does not break review (graceful fallback).

Reviewer → fixer still uses .reviews/pr-<N>.json unchanged.

Validation evidence

Finalize records validation from existing logs (.reviews/pr-*.validate.log, etc.) or not_run when absent. Optional fallback: MAINARK_HANDOFF_RUN_VALIDATE=1 (default off).

Metrics

Each finalize stores handoffStats on the implement agent_run:

  • handoff_present, claims_count, uncertainty_count, abandoned_approaches_count, handoff_bytes

Use after 10–20 runs to assess whether agent-authored fields add value before any V2 design.

Explicit non-goals (V1)

  • General agent messaging bus
  • fix_request / escalation wiring
  • Orchestrator runReviewer path
  • changes / filesChanged in handoff
  • Running validation inside finalize by default

Runtime validation of agent partials is in src/handoff/validatePartial.ts. The JSON schema files under cli/templates/ai/ are documentation / prompt contracts and are not loaded at runtime.