--- name: resolve-handoff description: Emit the complete Resolve handoff with exact modes, outcomes, test evidence, and publication state. --- ## Output — the resolution handoff The **last thing in your final message** must be exactly one fenced ```json code block — the machine-readable handoff, parsed by taking the last ```json fence in the message. Same discipline as repro-agent: - Write whatever prose summary you like above it, but the ```json block is the **last chunk** of the message, with nothing after its closing fence. Do not split the handoff across multiple sections or emit a second data block. - **One exception (author path):** you also emit an *interim* handoff right after opening the PR (Step 3.5) so the workflow can post the PR link to Linear before Step 4 finishes. That is fine — the caller reads the **last** valid handoff in the session, so this final one supersedes the interim block. The interim block carries `pr_url` + a provisional `outcome`; this final block is authoritative. - Emit it as **JSON**, never YAML. Include **every** key below, always, even when a value is empty (`""`, `[]`). - `mode` must be exactly `"reviewed_existing_pr"`, `"authored_fix"`, or `"review_remediation"` — which entry path you took. - `outcome` must be **exactly one** of the string literals `"fixed"`, `"partially_fixed"`, `"not_fixed"`, `"nothing_to_fix"`, `"needs_more_info"` — lowercase, no other wording. This is the field the caller reads, so it must match verbatim. ```json { "bug_url": "https://github.com/omnigent-ai/omnigent/issues/1234", "mode": "authored_fix", "outcome": "fixed", "problem_summary": "People see internal catalog IDs in the model picker instead of readable model names.", "solution_summary": "The model picker now shows a friendly name for every model.", "root_cause": "picker rendered raw catalog IDs because format_label() was never called on the option list", "fix_summary": "call format_label() when building picker options in web/src/model/picker.tsx", "review_body": "", "files_changed": ["web/src/model/picker.tsx"], "facets": [ {"symptom": "picker display", "outcome": "fixed", "test_transition": "test_1234 failed: raw IDs shown → passes: friendly labels"}, {"symptom": "catalog default", "outcome": "nothing_to_fix", "test_transition": "already_fixed in #3448; skipped"} ], "tests": { "e2e": "", "added": ["tests/web/model/test_picker_label.py::test_display_label"] }, "recordings": [ {"surface": "web", "kind": "before", "path": "recordings/1234/before-picker.webm", "format": "webm", "capture_mode": "playwright_ui", "caption": "open the model picker → select the catalog → picker shows raw IDs"}, {"surface": "web", "kind": "after", "path": "recordings/1234/after-picker.webm", "format": "webm", "capture_mode": "playwright_ui", "caption": "open the model picker → select the catalog → picker now shows friendly names"} ], "recording_unavailable_reason": "", "test_audit": "Reused the display-label regression; the same assertions fail on base and pass on head. Browser reproduction evidence is staged in .omnigent/repro-evidence/; workflow upload is pending at , artifact resolve-bundle-, path repro-evidence/. No additional browser boundary was found.", "impact_assessment": { "base_sha": "", "head_sha": "", "worktree_state": "clean", "risks": [ { "files": ["web/src/model/picker.tsx"], "behavior": "Changing labels can alter model selection or restoration", "consumers": ["model picker", "restored sessions"], "invariant": "Selections and restored sessions retain the same model IDs", "check": "", "result": "passed", "evidence": "" } ], "uncovered_boundaries": [], "not_applicable_reason": "" }, "remaining_work": [], "hermetic_check": "test_picker_label re-run with ambient env vars set — still passes", "pr_url": "https://github.com/omnigent-ai/omnigent/pull/4200", "reviewed_pr_url": "", "pushed_branch": "", "ci_status": "green (all required checks pass)", "polly_review": "clean on : fixed null-deref; fresh review has no findings", "ocr_review": "clean on : no findings", "review_cycle": { "head_sha": "", "fingerprint": "", "dispositions": [ {"key": "comment:", "status": "addressed", "reason": "Finding 1: null-deref fixed in ; passes. Finding 2: suggested fallback already exists at and is covered by , so not needed."} ] }, "ui_preview": "labeled ui-preview on every PR; preview at https://…; posted connect instructions", "validation_surface": "server", "validation_prompt": "Reproduce and validate a bug fix. Steps: open the model picker in the catalog view… Before this fix, raw catalog IDs were shown. Confirm the fix by checking that friendly labels appear. Report whether each step now behaves correctly.", "maintainer_review": "requested review from @PattaraS (issue assignee)", "review_fingerprint": "", "handled_review_ids": [], "last_pushed_sha": "", "session_id": "dc59e331-..." } ``` Field meanings: For modes that drive an open PR, `fixed` also requires the Step 4.3 live gate to pass. Interim and workflow-owned implementation handoffs do not certify PR readiness; name pending publication/review steps in `remaining_work`. - `bug_url` — the bug link, carried through from the recovered handoff. - `mode` — `reviewed_existing_pr` (Step 2A: a candidate PR existed, you reviewed it and kept it as the fix) or `authored_fix` (Step 2B: you wrote the fix). Use `authored_fix` when you started from an existing PR but opened your own — for **either** reason: its approach wasn't viable (2A.5), or its approach was fine but it was an unpushable **fork PR that needed a fix** so you took it over (Step 4 preamble). In both cases name the reviewed/forked PR in your prose and `reviewed_pr_url` so the two stay linked. Use `review_remediation` only when the input supplied `review_pr`; in that mode preserve the existing PR and branch and address its requested changes directly. - `review_fingerprint` / `handled_review_ids` / `last_pushed_sha` — populated in review-remediation mode for scanner deduplication and workflow retry recovery; otherwise `""`, `[]`, and `""`. - `outcome` — overall: `fixed` (every live facet resolved and proven — by your fix or by the reviewed PR — and the shared impact assessment has no unresolved required checks), `partially_fixed`, `not_fixed` (couldn't resolve, or the reviewed PR doesn't fix it), `nothing_to_fix` (recovered verdict was `already_fixed`/`not_reproduced`, or the 2B.1 audit showed `main` has since fixed it — name the fixing commit and recommend closing the ticket), or `needs_more_info` (couldn't recover a reliable reproduction, evidence is unsafe, required inputs/authorization are missing, or setup/environment blocks verification). When intended behavior is ambiguous, follow `resolve-investigate`: a supported proposal with an unresolved design choice is `partially_fixed`, with the choice in `remaining_work`. Do not describe it as a proven fix. - `problem_summary` / `solution_summary` — the two user-facing paragraphs shown prominently in the Linear update under **What's the problem?** and **How is it fixed?** Write plain, natural English for someone who uses the product but has not read the code. `problem_summary` describes what the person experiences and why it matters. `solution_summary` describes the corrected behavior and result. Keep implementation symbols, filenames, commit/merge bookkeeping, test lists, and CI details out of both fields; those belong in the technical fields below. Include both fields even for review mode and no-change outcomes. - `root_cause` / `fix_summary` / `files_changed` — the cause and the change. These are the technical details shown under **Additional notes** and used by publication/review fallbacks, so concrete symbols and filenames are welcome. In review mode, describe the reviewed PR's approach and leave `files_changed` empty (you changed nothing). Distinguish the observed symptom from the supported cause; include sources for historical intent, competing explanations checked, and any proposed policy change. Identify the real configuration path exercised and any substituted components. If the test assumes the suspected cause, retain it as a hypothesis and carry the missing proof into the outcome and `remaining_work`, following `resolve-investigate`. State missing evidence plainly; never include credentials. - `review_body` — the PR-facing review text from Step 2A. Fill it in for `reviewed_existing_pr`, including workflow-owned publication; use `""` in other modes. State the verdict and reason first, then separate the proof and any remaining action into short bullets. Do not paste `root_cause`, `fix_summary`, `ci_status`, or `polly_review` wholesale. The workflow publisher posts this field verbatim before adding the tested commit and marker, so it must stand alone as a useful review. Encode paragraph and bullet breaks as `\n` within the JSON string. - `facets` — per-facet, mirroring the recovered breakdown: each with its own `outcome` and a `test_transition` (the fail→pass proof, or why it was skipped). - `tests` — selected permanent regression coverage. `e2e` is the retained e2e path, or `""` when none is needed. `added` keeps its legacy name but lists the other selected checks, including reused unchanged tests or extensions to an existing module. Each entry must be a bare repository-relative path or test node ID that resolves on the committed candidate. Do not append labels such as `(reused unchanged)`, shell commands, or result summaries; put those in `test_audit`. Before handing off, check the file portion of every reference against the committed tree and use the same node IDs as the executed checks. Do not list artifact-only reproduction paths here. In comment-only review, keep the existing review procedure and do not commit temporary test source. Use `test_audit` for brief selection reasoning: reused/retained tests, why any new permanent e2e is necessary, and gaps. For reproduction-only evidence, give the run URL/artifact/path or verified persistent local path from 2B.4, plus its retention status; identify pending uploads and unresolved retention. - `recordings` — your after-fix clips (`kind: "after"`) and any recovered before-clips, using `{surface, kind, path, format, capture_mode, caption}`. Follow the recording rules in Step 2B.5 on both author and review runs; in review mode, record the reviewed PR head. Keep recovered before-clips and captions unchanged. Each after-clip's caption lists the actions shown, ending with the corrected behavior. A missing before-clip is not a reason to skip the after-clip. Use `[]` only for internal/API-only results with no visible user interaction, or when recording is blocked as described above. - `recording_unavailable_reason` — leave empty when every expected clip is present. Otherwise explain each missing clip: - For internal/API-only results, say there is no visible user interaction and put the written before/after evidence in the PR Demo section. - For a recording failure, name the missing tool or the environment problem. Text-only CLI output is not a reason to skip recording. - Do not substitute a video of test output or a made-up demonstration. Missing or rejected footage must not block the fix or PR. - `test_audit` — required in both author and review modes for reproduction-driven runs. Record the shared repro audit: patch-scope concerns, whether the original test was accepted/repaired/rejected and why, exact before/after revisions and commands, relevant environment/feature gates, behavioral fail→pass evidence, and any blockers. Preserve original evidence when repairing a test. A restored artifact or a green candidate run alone is not an audit. - `impact_assessment` — required in every mode. Use the shared impact assessment above. `base_sha` is the target branch tip used for the comparison; the full diff starts at its merge-base with `head_sha`. `worktree_state` records tested dirt and content hashes, not just the final clean status. Each `risks` entry maps changed files and affected consumers to a preserved invariant, check, result, and evidence. Include required checks that failed or could not run; explain their gaps in `uncovered_boundaries`. Use empty SHAs/state only when stopping before a candidate can be identified, with `not_applicable_reason`. Otherwise leave that reason empty unless the inspected diff has no behavioral impact. This narrative does not certify execution or replace `test_audit`. - `remaining_work` — a list of specific unresolved behavior, required checks, or delivery steps for `partially_fixed`; empty when none remain. Resolved original facets do not hide a regression or an uncovered required boundary. - `hermetic_check` — the result of the Step 2B.5 hostile-env re-run when the diff touched env-derived defaults: which added/edited tests you re-ran with ambient vars set and that they still passed. Empty string when not applicable (no such test in the diff). - `pr_url` — the PR you **opened** (author mode), including a draft proposal identified as such in `fix_summary`. Empty in review mode, when `skip_push` was set, or if you stopped before opening one. - `reviewed_pr_url` — the existing PR you **reviewed** (review mode), or the fork PR you **took over** into your own (fork takeover — `pr_url` is then yours). Empty when you authored from scratch with no upstream PR. - `pushed_branch` — the local branch holding the committed fix that you did **not** push because `skip_push` was set (author mode). Empty otherwise. A human pushes and opens the PR from it. - `ci_status` — the result of the Step 4.2 CI loop (run on **both** paths now): `green` when the checks you're responsible for pass, otherwise the failing checks and whether each was diff-caused vs pre-existing/flaky/infra. If a fork PR needed a fix and you took over into your own PR, this reflects **your** PR's checks. Empty when `skip_push` was set or you stopped before there was a PR to land. - `polly_review` / `ocr_review` — each reviewer's current-head result, rounds, run/comment links, fixes, and individually justified invalid/not-needed findings (including non-blocking notes). Missing, stale, skipped, failed, or undispatched reviews are explicitly incomplete and block readiness/approval. Empty when the publication mode skips Step 4; that does not mean the PR is ready to merge. - `review_cycle` — the Step 4.3 snapshot receipt: `head_sha`, `fingerprint`, and `dispositions`. Include one record per feedback `key` from the snapshot, with `status` (`addressed`, `invalid`, or `not_needed`) and a nonempty `reason` explaining every finding in that document with commit/test/code evidence. Mixed dispositions in one summary belong individually in its `reason`; use `addressed` for the document when all its findings are settled. Revalidate after new feedback or a push. The live checker verifies coverage and freshness, not whether the reasoning is correct. Use `{}` when Step 4 has not run (interim, local-only, or workflow-owned author publication); preserve partial receipts and name missing reviews/findings in `remaining_work` if the loop is blocked. - `ui_preview` — the result of Step 4.1 (run on every PR, not just frontend fixes): the **preview URL** (verbatim, so the ticket write-back can surface it and a reviewer can `omnigent claude -p '' --server `), or why it failed to deploy (e.g. workspace secrets not configured, or the label couldn't be applied under your identity). Empty when no PR was opened. - `validation_surface` — which side the fix runs on, from Step 4.1: `server` (the preview build carries it; `--server ` validates it), `runner` (runs in the runner/host process, so only a local `gh pr checkout` + `--server ''` build validates it — the preview's local runner is unfixed), or `both` (spans both — treat like `runner`). Judge from `files_changed`; default `server`, use `both` when unsure. Tells the write-back which command to render. - `validation_prompt` — the Step 4.4 paste-to-an-agent prompt that reproduces the journey and confirms the fix. Empty when no PR was opened, except for workflow-owned author publication: in that mode no PR exists during the agent session, but this field must retain the deferred prompt for the publisher and Linear write-back. - `maintainer_review` — who you requested review from in Step 4.5 (the issue assignee(s)), or why you couldn't (no assignee / assignee is the author, and what you did instead). Empty when no PR was opened. - `session_id` — the repro session you consumed, carried through so the chain is traceable. Directly published author runs and review runs end the same way: the PR you're landing (one you opened, or an existing in-repo PR you reviewed and kept) has a preview, green CI, settled current-head Polly and OCR reviews, a live-validation command, and the maintainer tagged (Step 4) — or a concrete blocker or actual execution deadline has left an explicitly incomplete, resumable handoff. The difference is only how a fix lands (push directly, or — for an unpushable fork PR that needs changes — take over into your own PR carrying the contributor's commits), and that the direct author path opens a PR while the review path adopts an existing one. Workflow-owned author publication ends after the validated body, deferred validation prompt, and final handoff are prepared; the publisher owns the post-publication loop. A direct draft proposal instead ends with the incomplete handoff in `resolve-publish`; it makes no readiness or independent-review claim. `skip_push` and `needs_more_info` runs end earlier, with no PR to land. In every mode, **you do not merge.**