Final Handoff Contract

Load this common contract plus the matching required supplement for every workflow disposition, including terminal and exact caller output. Other workflows need no supplement.

Workflow	Required supplement
code-review	Code Review handoff
code-remediate	Remediation handoff
challenge-resolve	Challenge handoff
release	Release handoff

The post-gate presentation checkpoint makes the workflow's final user-facing structure executable. Artifact workflows must write <run-directory>/final-handoff.json, render it with PLUGIN_ROOT/bin/python PLUGIN_ROOT/shared/final_handoff.py render --handoff <run-directory>/final-handoff.json --out-final <run-directory>/final.md --out-validation <run-directory>/final-handoff.validation.json, bind returned digests under result.metadata.final_handoff, pass all skill-specific and shared artifact validators, promote the candidate, then emit validated final.md bytes verbatim, subject only to Nested review delivery. Never manually reconstruct or summarize the response after validation.

Rendered section and table labels use portable Markdown bold text such as **Outcome** and **Verification**. Never emit ATX/Setext headings, ANSI color escapes, or renderer-specific HTML styling; final reports must stay compact and readable in monochrome terminals, saved Markdown, plain logs.

Author outcome.summary as a short introductory sentence. Prefer short labelled bullets in outcome.title for parallel status facts and counts; keep verification, remaining actions and report links in their own existing fields. Distinguish completed report validation from remediation closure and passing checks. Emit the validated tables for every workflow, including clean, single-result, partial and blocked outcomes; never replace them with a dense prose recap. Tables and stable labels anchor human reading; use numbered steps for ordered actions and bullets for parallel facts. Exact caller-contract output stays exact.

This is a post-gate checkpoint, not a sixth quality gate. Order is fixed: five gates; final-handoff creation and rendering; result candidate using schema 3 for every current Code Review disposition or schema 2 for other skills; skill validator; shared validator including final_handoff.py check; candidate promotion; verbatim final output or the nested delivery below. A failure in the checkpoint blocks promotion and completion.

Nested review delivery

Apply when code-remediate is waiting for an already-approved fresh review or producer recovery of its unchanged PR target in the same remediation run. Fresh review runs the normal full code-review workflow end-to-end; report recovery follows its compatibility assessment, reusing only authentic still-valid evidence and completing the same producer validation, promotion and completion gates. This changes delivery only, not authorization, review coverage or any completion gate; it is not a caller-contract schema override.

1. Capture the successful completion stdout after find-review-report.py --complete-run <review-run-directory> succeeds. Keep the rendered final.md and all validated review artifacts intact.
2. Return the exact canonical <review-run-directory>/result.json path and producer evidence coordinates to the waiting remediation; never extract the path from rendered prose. Do not send a standalone review-only final answer and do not end the parent turn at this boundary.
3. Resume that same remediation's report admission using the returned path. Its explicit-result validator still checks current eligibility, including internal newest-run lookup; concurrent supersession rejects admission rather than substituting another report. Completed assessed nonapproval reports remain eligible under normal intake rules; unavailable, closed, failed or incomplete completion never supplies admitted findings. An ineligible returned result follows the remediation's owning status decision without automatically restarting review or rediscovering another report. A genuinely changed blocker may require an explicit New review or Resume last one choice under that decision; retain prior authorization and stopped-route limits.
4. Continue remediation through its normal source collection, inventory, selection, fixes and closing gates. A branch or SHA mismatch returns to Source drift recovery, not a review-only final answer. Remediation remains incomplete until its own required closure is verified. Never ask the user to restore the branch or send another message merely to continue already-authorized safe recovery. Only the owning remediation's completed handoff ends the combined workflow; real missing decisions, denied capabilities and bounded recovery stops still apply.

Standalone review still emits successful completion stdout verbatim. A nested review retains the same final bytes as completion evidence, without replacing the parent's requested remediation outcome.

Schema

final-handoff.json has exactly these top-level fields: schema_version, skill, branch, outcome, tables, source_records, source_coverage, verification, remaining, next_steps, confidence, artifacts, caller_contract. Schema version is 1. The helper's executable validation is authoritative for nested types, closed vocabularies, exact columns, row/source uniqueness, completeness counts, confidence bands, closure evidence, branch-specific table rules.

All new current handoffs use presentation_version=13, including assessed Code Review and remediation. Readers also admit supported version-8/9/10/11/12 candidates; a cosmetic version upgrade alone never requires repeating remediation. Versions 1–12 retain their exact rendered bytes, and an omitted version retains the v1 compatibility path. Version 13 renders unresolved actions as Owner | Issue | Action and visible verification checks as Check | Status | Evidence tables. Keep summaries as prose, confidence explanations as bullets and artifacts as links; machine CLI output and exact caller contracts stay unchanged. Both tables use the same lossless path externalization as result tables, including multiline and escaped cell text. Version 12 places numbered unresolved actions after artifacts, except for closed and exact caller-contract branches. Version 10 adds the bound concrete resolution reason to each remediation table row, including single-item runs, while retaining version 9’s other presentation behavior. Version 11 adds compact display-only terminal status tables while retaining version 10 remediation resolution explanations. Version 9 preserves complete machine records and adds readable numbered next actions with owners, separated status/action paragraphs, confidence bullets for every workflow, exact duplicate limit/gap coalescing that preserves closure details, and clickable verification/artifact links. It keeps all file paths out of every rendered table cell, including paths embedded in Evidence, Artifact, Surface, or mixed evidence/action cells. For angle-bracket links, simple inline links and recognized quoted paths, retain adjacent prose in the table and list each destination below as - <item>: <file-path>. For ambiguous plain cells, unclassified code spans, or complex inline targets outside that bounded syntax, retain the complete cell verbatim in an item-and-column labelled detail list with a short table reference, as described below. Strip a path-only Evidence column from the rendered table; retain the source column and exact evidence in machine records. Never discard or normalize a path, evidence text, or action while moving it. The complete machine outcome, verification, remaining, next_steps, and table records stay unchanged. Exact caller-contract output stays exact.

Normal artifact workflows use branch=standard; code-review uses assessed, unavailable, or closed. An explicitly requested exact caller output uses caller-contract, records requested format and evidence, forbids normal tables, emits only caller_contract.output. Never infer this override merely because concise output would be convenient.

For normal table branches, every material finding, decision, changed surface, experiment, recommendation, or source-owned remediation item must have one stable row ID. source_records is the complete source ledger; each table row names its represented source IDs; source_coverage.omitted_source_records_total must be zero. A table may carry ordered details entries with exactly id and text; every detail ID must be unique, referenced as [<id>] by cell in that table, with the renderer placing definitions immediately below the table. Detail definitions already outside tables retain their original prose and references. Remaining work names the related row ID, item, owner, next action; next_steps contains exactly the remaining row IDs. Terminal code-review branches contain no machine tables or source records; presentation 11 derives a display-only Field | Value status table without source judgments. Historical presentations retain their exact bytes.

verification preserves all five gate records in canonical order, uses the corresponding gate stdout artifact path as evidence. confidence.score, gaps, gap closure status/evidence/rationale, limits must exactly reconcile with the result's confidence metadata. artifacts must include the candidate/final result path.

New confidence output follows Confidence Deduction Accounting. In existing gap/limit strings, prefix each freeform description with its contribution: (-0.NN) Description. Keep matching closure labels in result metadata and handoff records identical; never append the deduction after the description. Preserve exact canonical gap identities required by workflow validators; when a fixed label cannot change, show its contribution in existing closure evidence/rationale displayed by the renderer instead. If both gap identity and closure text are fixed, preserve those records and put the contribution in an editable corresponding existing limit string, explicitly referencing the same gap and counting it once. Keep score, identity, and contribution consistent before rendering. A repeated limit references its gap label and counts once. Version 9 displays an exactly matching limit/gap label once while retaining the gap status and closure details; distinct limits remain separate bullets. This uses existing string fields without new schema fields. Historical rendered bytes and historical result compatibility remain unchanged.

For presentation 12 Code Review unavailable output, and for later presentations, confidence assesses correctness of the delivered failure report and its production and checks. Select the numeric score as an evidence-backed operator judgment; do not deduct for an unreviewed PR merely because collection stopped. Keep the prior unavailable profile readable for earlier presentations. The PR scope limit is (-0.00) PR correctness was not assessed.; when checkout state is retained use (-0.00) PR correctness was not assessed; inspect local checkout state before retrying. instead. A second limit is (-0.00) Confidence is a subjective judgment of report correctness and its production and checks. Keep initial_confidence and final_confidence equal to the selected two-decimal score and set its existing band. Evidence begins with Confidence assesses the correctness of this failure report and its production and checks; the score is a subjective judgment. followed by the existing canonical collection/checkout evidence. Keep recovery_actions as Stopped before source review.

Record each material limitation separately in confidence_gaps with its two-decimal contribution and an unresolved matching closure. Supported category No command-failure.json was retained. is valid only when command-failure.json is absent; its rationale is No command-failure.json was retained; pr-error.txt records the classification. Other diagnostics may exist. Supported category Checkout state is changed or unknown. requires the validated checkout-state.json record; its rationale is checkout-state.json records the changed-or-unknown checkout state. Do not automatically deduct for either observation: judge whether it materially limits correctness of this report. Use the single optional category Residual uncertainty in the failure report and its production and checks. only for an unexplained shortfall, with rationale The retained records do not establish every aspect of report correctness; this is the operator's subjective judgment, not a substitute for a known gap. Unique contributions sum to exactly 1.00 - score and each follows (-0.NN); retain zero-deduction known limitations too. A 0.00 score is representable only when distinct supported gaps legitimately sum to 1.00 without a single (-1.00) contribution. If it is not representable, stop and disclose the limitation; never invent another gap. If a known material limitation cannot be represented by these categories, stop and state the limitation rather than hiding it in a residual. Validation checks declared facts, source paths and arithmetic; it cannot detect an omitted judgment, establish independent authenticity of local artifacts, or calibrate the score. Preserve existing low-confidence failed-check rules.

Report workflow completion separately from the reviewed change's readiness. For Code Review, successful validation, promotion and --complete-run mean the review completed even when result.status=fail records failed quality gates or a nonapproval recommendation. State “Review completed; the change still needs work” with the failed gates and required fixes. Reserve “Review not complete” for an unmet review lifecycle checkpoint; never infer it from status=fail alone.

Every user-facing report defaults to a concrete recommended next action and its owner, including progress reports and unvalidated process failures. Perform already-authorized next work instead of asking for permission again. For incomplete work, state the exact resume condition and what can continue; when the requested goal is complete and no action remains, say so without inventing work. Use existing remaining and next_steps fields for validated artifacts; preserve historical rendered bytes and exact caller-output contracts.

For presentation 12 and later, a failed or timed-out result must include a remaining item and next step with a responsible owner; the shared result validator enforces this before promotion and on revalidation. Closed and exact caller-contract branches keep their existing exceptions, and successful results need no invented follow-up.

Every pause follows Actionable Pauses, including terminal review unavailability and assessed review with a withheld executable check. Use existing fields: outcome.summary states the stopped action, concrete cause/evidence, governing rule; the related remaining entry names continuing work in item, the responsible actor in owner, feasible recovery plus exact resume condition in next_action. Keep that entry in next_steps. For assessed code review, whose outcome is a fixed recommendation, place the complete explanation in the related remaining item and canonical operational blocker when applicable. An exact caller contract must preserve the same explanation within its allowed output. Never reduce handoff to an error code, generic approval request, or instruction to retry unchanged after deterministic failure.

Use the existing next_action text for recommended recovery, pending decision identity, consequences, resume condition. When a decision is needed, follow User Questions: show required context first, then let one native control own the live question and choices; only the plain-chat fallback includes them in next_action. Keep the exact original question, accepted answers, scope binding, actual response in existing durable workflow notes without extending closed schemas. Never duplicate a native question in rendered final Markdown. Distinguish continuing work from work paused until a specific condition; never imply a temporary process failure permanently blocks the goal. Keep canonical branch wording, schemas, evidence bindings, historical bytes unchanged. An unvalidated process pause follows the same guidance without claiming a validated final handoff. After the plain-English opening, render a compact Checkpoint | Status | Evidence / next action table naming completed work, the exact unmet checkpoint, retained evidence and the owner/resume condition. Mark preliminary evidence explicitly and keep paths immediately below the table. Do not fabricate findings, source judgments, passing gates or promotion. Preserve any supported preliminary source snapshot as an explicitly unvalidated reading anchor; missing fields say unverified. An accepted pending async question still yields immediately without a final or status handoff.

Plain cells mixing file references with words, spaces, or punctuation, unclassified filename-like tokens, and unmarked slash expressions that could be relative paths or prose are ambiguous. Recognize complete tokens only; an unfamiliar extension or filename spelling must never produce a shortened destination. The renderer moves the entire cell verbatim to an item-and-column labelled detail list and leaves a short table reference; it never guesses path boundaries or discards action words. Use Markdown links or backticks when exact path boundaries are known: recognized references move to file lists while adjacent prose remains in the table. Visible link labels undergo the same ambiguity checks as prose; a path-bearing label and its destination remain together in the complete-cell detail, including when they differ. Ordinary human labels retain their adjacent table prose. A code span that cannot be classified as a path, including an unfamiliar basename or complex backtick delimiter, uses the same complete-cell detail fallback; preserve its action context without inventing a filename or restricting valid filesystem names. This automatic fallback preserves source records and never asks for a formatting decision.

Exact table columns

Use the active skill's Output Contract columns, enforced by the handoff helper. Supplements add their workflow's table rules.

Result compatibility

write-result.py creates schema-2 results for other skills and schema-3 results for every current Code Review disposition. It requires metadata.final_handoff with schema version, three sibling paths, two SHA-256 digests, and branch. validate-artifacts.py checks those paths, exact rendered bytes, digests, gates, confidence, result artifact reference, and workflow-specific reconciliation. Historical results with no schema_version are read as schema 1 and remain valid without final-handoff artifacts; new results cannot opt into that compatibility path because the writer emits schema 2 or 3.

Transport limit and manager exception

The checkpoint proves the complete response bytes the workflow must emit or retain under nested review delivery, but the current host has no post-send transcript hook that can prove chat transport reproduced them. Treat any later manual rewrite as a contract violation; a future host transcript hook may close this residual transport gap without changing artifact schema.

agent-shims remains a documented lifecycle exception because it has no canonical .reports result artifact, is excluded from the artifact/calibration roster. Its final chat contract remains advisory until that manager gains a canonical run/result lifecycle; never claim executable final-response validation for it.