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.
{
"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.mp4", "format": "mp4",
"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 <workflow run URL>, artifact resolve-bundle-<run-id>, path repro-evidence/. No additional browser boundary was found.",
"impact_assessment": {
"base_sha": "<full target-branch tip SHA>",
"head_sha": "<full candidate 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": "<exact command exercising selection and session restoration>",
"result": "passed",
"evidence": "<retained output reference, tested build and environment>"
}
],
"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 <full candidate HEAD SHA>: fixed null-deref; fresh review has no findings",
"ocr_review": "clean on <full candidate HEAD SHA>: no findings",
"review_cycle": {
"head_sha": "<full candidate HEAD SHA>",
"fingerprint": "<fingerprint from the final review snapshot>",
"dispositions": [
{"key": "comment:<id>", "status": "addressed", "reason": "Finding 1: null-deref fixed in <commit>; <test> passes. Finding 2: suggested fallback already exists at <path:line> and is covered by <test>, 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.
When the incident cause is unverified, start root_cause with that fact. Describe
the tested mechanism separately from the hypothesis that it caused the incident;
do not claim that incident link elsewhere in the summary. In test_audit, include
the governing-definition citation and real configured-path observation requested
by resolve-investigate, or the specific missing evidence; do not defer a
feasible check merely to finish.
Before finalizing test_audit, verify an actual defining-source read and the
file, symbol and value for each governing shared definition. If none exists,
record the bounded search; a filename or caller reference alone is insufficient.
Execute missing feasible reads and keep unresolved definition gaps explicit.
Distinguish observed effects from expected downstream behavior: unexercised
reconnect or recovery paths remain unverified in every summary field.
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}.
Point each new clip's path at the inspected MP4 with timed captions burned
in using dev/caption_recording.py per dev/recording-lanes.md. If captioning
was blocked, retain the usable clip and disclose the blocker in evidence.
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 '<prompt>' --server <url>), 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 <preview> 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.
1---2name: resolve-handoff3description: Emit the complete Resolve handoff with exact modes, outcomes, test evidence, and publication state.4metadata:5 source: https://skillmd.com/skills/tuyv/resolve-handoff6---78## Output — the resolution handoff910The **last thing in your final message** must be exactly one fenced ```json code11block — the machine-readable handoff, parsed by taking the last ```json fence in12the message. Same discipline as repro-agent:1314- Write whatever prose summary you like above it, but the ```json block is the15 **last chunk** of the message, with nothing after its closing fence. Do not16 split the handoff across multiple sections or emit a second data block.17- **One exception (author path):** you also emit an *interim* handoff right after18 opening the PR (Step 3.5) so the workflow can post the PR link to Linear before19 Step 4 finishes. That is fine — the caller reads the **last** valid handoff in20 the session, so this final one supersedes the interim block. The interim block21 carries `pr_url` + a provisional `outcome`; this final block is authoritative.22- Emit it as **JSON**, never YAML. Include **every** key below, always, even when23 a value is empty (`""`, `[]`).24- `mode` must be exactly `"reviewed_existing_pr"`, `"authored_fix"`, or25 `"review_remediation"` — which entry path you took.26- `outcome` must be **exactly one** of the string literals `"fixed"`,27 `"partially_fixed"`, `"not_fixed"`, `"nothing_to_fix"`, `"needs_more_info"` —28 lowercase, no other wording. This is the field the caller reads, so it must29 match verbatim.3031```json32{33 "bug_url": "https://github.com/omnigent-ai/omnigent/issues/1234",34 "mode": "authored_fix",35 "outcome": "fixed",36 "problem_summary": "People see internal catalog IDs in the model picker instead of readable model names.",37 "solution_summary": "The model picker now shows a friendly name for every model.",38 "root_cause": "picker rendered raw catalog IDs because format_label() was never called on the option list",39 "fix_summary": "call format_label() when building picker options in web/src/model/picker.tsx",40 "review_body": "",41 "files_changed": ["web/src/model/picker.tsx"],42 "facets": [43 {"symptom": "picker display", "outcome": "fixed", "test_transition": "test_1234 failed: raw IDs shown → passes: friendly labels"},44 {"symptom": "catalog default", "outcome": "nothing_to_fix", "test_transition": "already_fixed in #3448; skipped"}45 ],46 "tests": {47 "e2e": "",48 "added": ["tests/web/model/test_picker_label.py::test_display_label"]49 },50 "recordings": [51 {"surface": "web", "kind": "before", "path": "recordings/1234/before-picker.webm", "format": "webm",52 "capture_mode": "playwright_ui",53 "caption": "open the model picker → select the catalog → picker shows raw IDs"},54 {"surface": "web", "kind": "after", "path": "recordings/1234/after-picker.mp4", "format": "mp4",55 "capture_mode": "playwright_ui",56 "caption": "open the model picker → select the catalog → picker now shows friendly names"}57 ],58 "recording_unavailable_reason": "",59 "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 <workflow run URL>, artifact resolve-bundle-<run-id>, path repro-evidence/. No additional browser boundary was found.",60 "impact_assessment": {61 "base_sha": "<full target-branch tip SHA>",62 "head_sha": "<full candidate HEAD SHA>",63 "worktree_state": "clean",64 "risks": [65 {66 "files": ["web/src/model/picker.tsx"],67 "behavior": "Changing labels can alter model selection or restoration",68 "consumers": ["model picker", "restored sessions"],69 "invariant": "Selections and restored sessions retain the same model IDs",70 "check": "<exact command exercising selection and session restoration>",71 "result": "passed",72 "evidence": "<retained output reference, tested build and environment>"73 }74 ],75 "uncovered_boundaries": [],76 "not_applicable_reason": ""77 },78 "remaining_work": [],79 "hermetic_check": "test_picker_label re-run with ambient env vars set — still passes",80 "pr_url": "https://github.com/omnigent-ai/omnigent/pull/4200",81 "reviewed_pr_url": "",82 "pushed_branch": "",83 "ci_status": "green (all required checks pass)",84 "polly_review": "clean on <full candidate HEAD SHA>: fixed null-deref; fresh review has no findings",85 "ocr_review": "clean on <full candidate HEAD SHA>: no findings",86 "review_cycle": {87 "head_sha": "<full candidate HEAD SHA>",88 "fingerprint": "<fingerprint from the final review snapshot>",89 "dispositions": [90 {"key": "comment:<id>", "status": "addressed", "reason": "Finding 1: null-deref fixed in <commit>; <test> passes. Finding 2: suggested fallback already exists at <path:line> and is covered by <test>, so not needed."}91 ]92 },93 "ui_preview": "labeled ui-preview on every PR; preview at https://…; posted connect instructions",94 "validation_surface": "server",95 "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.",96 "maintainer_review": "requested review from @PattaraS (issue assignee)",97 "review_fingerprint": "",98 "handled_review_ids": [],99 "last_pushed_sha": "",100 "session_id": "dc59e331-..."101}102```103104Field meanings:105106For modes that drive an open PR, `fixed` also requires the Step 4.3 live gate107to pass. Interim and workflow-owned implementation handoffs do not certify PR108readiness; name pending publication/review steps in `remaining_work`.109110- `bug_url` — the bug link, carried through from the recovered handoff.111- `mode` — `reviewed_existing_pr` (Step 2A: a candidate PR existed, you reviewed112 it and kept it as the fix) or `authored_fix` (Step 2B: you wrote the fix). Use113 `authored_fix` when you started from an existing PR but opened your own — for114 **either** reason: its approach wasn't viable (2A.5), or its approach was fine115 but it was an unpushable **fork PR that needed a fix** so you took it over (Step116 4 preamble). In both cases name the reviewed/forked PR in your prose and117 `reviewed_pr_url` so the two stay linked.118 Use `review_remediation` only when the input supplied `review_pr`; in that mode119 preserve the existing PR and branch and address its requested changes directly.120- `review_fingerprint` / `handled_review_ids` / `last_pushed_sha` — populated in121 review-remediation mode for scanner deduplication and workflow retry recovery;122 otherwise `""`, `[]`, and `""`.123- `outcome` — overall: `fixed` (every live facet resolved and proven — by your fix124 or by the reviewed PR — and the shared impact assessment has no unresolved125 required checks), `partially_fixed`, `not_fixed` (couldn't resolve, or the126 reviewed PR doesn't fix it), `nothing_to_fix` (recovered verdict was127 `already_fixed`/`not_reproduced`, or the 2B.1 audit showed `main` has since128 fixed it — name the fixing commit and recommend closing the ticket), or129 `needs_more_info` (couldn't recover a reliable reproduction, evidence is unsafe,130 required inputs/authorization are missing, or setup/environment blocks verification).131 When intended behavior is ambiguous, follow `resolve-investigate`: a supported132 proposal with an unresolved design choice is `partially_fixed`, with the choice133 in `remaining_work`. Do not describe it as a proven fix.134- `problem_summary` / `solution_summary` — the two user-facing paragraphs shown135 prominently in the Linear update under **What's the problem?** and **How is it136 fixed?** Write plain, natural English for someone who uses the product but has137 not read the code. `problem_summary` describes what the person experiences and138 why it matters. `solution_summary` describes the corrected behavior and result.139 Keep implementation symbols, filenames, commit/merge bookkeeping, test lists,140 and CI details out of both fields; those belong in the technical fields below.141 Include both fields even for review mode and no-change outcomes.142- `root_cause` / `fix_summary` / `files_changed` — the cause and the change.143 These are the technical details shown under **Additional notes** and used by144 publication/review fallbacks, so concrete symbols and filenames are welcome.145 In review mode, describe the reviewed PR's approach and leave `files_changed`146 empty (you changed nothing).147 Distinguish the observed symptom from the supported cause; include sources for148 historical intent, competing explanations checked, and any proposed policy149 change. Identify the real configuration path exercised and any substituted150 components. If the test assumes the suspected cause, retain it as a hypothesis151 and carry the missing proof into the outcome and `remaining_work`, following152 `resolve-investigate`. State missing evidence plainly; never include credentials.153 When the incident cause is unverified, start `root_cause` with that fact. Describe154 the tested mechanism separately from the hypothesis that it caused the incident;155 do not claim that incident link elsewhere in the summary. In `test_audit`, include156 the governing-definition citation and real configured-path observation requested157 by `resolve-investigate`, or the specific missing evidence; do not defer a158 feasible check merely to finish.159 Before finalizing `test_audit`, verify an actual defining-source read and the160 file, symbol and value for each governing shared definition. If none exists,161 record the bounded search; a filename or caller reference alone is insufficient.162 Execute missing feasible reads and keep unresolved definition gaps explicit.163 Distinguish observed effects from expected downstream behavior: unexercised164 reconnect or recovery paths remain unverified in every summary field.165- `review_body` — the PR-facing review text from Step 2A. Fill it in for166 `reviewed_existing_pr`, including workflow-owned publication; use `""` in167 other modes. State the verdict and reason first, then separate the proof and168 any remaining action into short bullets. Do not paste `root_cause`,169 `fix_summary`, `ci_status`, or `polly_review` wholesale. The workflow publisher170 posts this field verbatim before adding the tested commit and marker, so it171 must stand alone as a useful review. Encode paragraph and bullet breaks as172 `\n` within the JSON string.173- `facets` — per-facet, mirroring the recovered breakdown: each with its own174 `outcome` and a `test_transition` (the fail→pass proof, or why it was skipped).175- `tests` — selected permanent regression coverage. `e2e` is the retained e2e176 path, or `""` when none is needed. `added` keeps its legacy name but lists the177 other selected checks, including reused unchanged tests or extensions to an178 existing module. Each entry must be a bare repository-relative path or test179 node ID that resolves on the committed candidate. Do not append labels such180 as `(reused unchanged)`, shell commands, or result summaries; put those in181 `test_audit`. Before handing off, check the file portion of every reference182 against the committed tree and use the same node IDs as the executed checks.183 Do not list artifact-only reproduction paths here. In comment-only review,184 keep the existing review procedure and do not commit temporary test source.185 Use `test_audit` for brief selection reasoning: reused/retained tests, why any186 new permanent e2e is necessary, and gaps. For reproduction-only evidence, give187 the run URL/artifact/path or verified persistent local path from 2B.4, plus188 its retention status; identify pending uploads and unresolved retention.189- `recordings` — your after-fix clips (`kind: "after"`) and any recovered190 before-clips, using `{surface, kind, path, format, capture_mode, caption}`.191 Point each new clip's `path` at the inspected MP4 with timed captions burned192 in using `dev/caption_recording.py` per `dev/recording-lanes.md`. If captioning193 was blocked, retain the usable clip and disclose the blocker in `evidence`.194 Follow the recording rules in Step 2B.5 on both author and review runs; in195 review mode, record the reviewed PR head. Keep recovered before-clips and196 captions unchanged. Each after-clip's caption lists the actions shown, ending197 with the corrected behavior. A missing before-clip is not a reason to skip198 the after-clip. Use `[]` only for internal/API-only results with no visible199 user interaction, or when recording is blocked as described above.200- `recording_unavailable_reason` — leave empty when every expected clip is201 present. Otherwise explain each missing clip:202203 - For internal/API-only results, say there is no visible user interaction204 and put the written before/after evidence in the PR Demo section.205 - For a recording failure, name the missing tool or the environment problem.206 Text-only CLI output is not a reason to skip recording.207 - Do not substitute a video of test output or a made-up demonstration.208 Missing or rejected footage must not block the fix or PR.209- `test_audit` — required in both author and review modes for reproduction-driven210 runs. Record the shared repro audit: patch-scope concerns, whether the original211 test was accepted/repaired/rejected and why, exact before/after revisions and212 commands, relevant environment/feature gates, behavioral fail→pass evidence,213 and any blockers. Preserve original evidence when repairing a test. A restored214 artifact or a green candidate run alone is not an audit.215- `impact_assessment` — required in every mode. Use the shared impact assessment216 above. `base_sha` is the target branch tip used for the comparison; the full217 diff starts at its merge-base with `head_sha`. `worktree_state` records tested218 dirt and content hashes, not just the final clean status. Each `risks` entry219 maps changed files and affected consumers to a preserved invariant, check,220 result, and evidence. Include required checks that failed or could not run;221 explain their gaps in `uncovered_boundaries`. Use empty SHAs/state only when222 stopping before a candidate can be identified, with `not_applicable_reason`.223 Otherwise leave that reason empty unless the inspected diff has no behavioral224 impact. This narrative does not certify execution or replace `test_audit`.225- `remaining_work` — a list of specific unresolved behavior, required checks, or226 delivery steps for `partially_fixed`; empty when none remain. Resolved original227 facets do not hide a regression or an uncovered required boundary.228- `hermetic_check` — the result of the Step 2B.5 hostile-env re-run when the diff229 touched env-derived defaults: which added/edited tests you re-ran with ambient230 vars set and that they still passed. Empty string when not applicable (no such231 test in the diff).232- `pr_url` — the PR you **opened** (author mode), including a draft proposal233 identified as such in `fix_summary`. Empty in review234 mode, when `skip_push` was set, or if you stopped before opening one.235- `reviewed_pr_url` — the existing PR you **reviewed** (review mode), or the fork236 PR you **took over** into your own (fork takeover — `pr_url` is then yours).237 Empty when you authored from scratch with no upstream PR.238- `pushed_branch` — the local branch holding the committed fix that you did239 **not** push because `skip_push` was set (author mode). Empty otherwise. A human240 pushes and opens the PR from it.241- `ci_status` — the result of the Step 4.2 CI loop (run on **both** paths now):242 `green` when the checks you're responsible for pass, otherwise the failing checks243 and whether each was diff-caused vs pre-existing/flaky/infra. If a fork PR needed244 a fix and you took over into your own PR, this reflects **your** PR's checks.245 Empty when `skip_push` was set or you stopped before there was a PR to land.246- `polly_review` / `ocr_review` — each reviewer's current-head result, rounds,247 run/comment links, fixes, and individually justified invalid/not-needed findings248 (including non-blocking notes). Missing, stale, skipped, failed, or undispatched249 reviews are explicitly incomplete and block readiness/approval. Empty when the250 publication mode skips Step 4; that does not mean the PR is ready to merge.251- `review_cycle` — the Step 4.3 snapshot receipt: `head_sha`, `fingerprint`, and252 `dispositions`. Include one record per feedback `key` from the snapshot, with253 `status` (`addressed`, `invalid`, or `not_needed`) and a nonempty `reason`254 explaining every finding in that document with commit/test/code evidence.255 Mixed dispositions in one summary belong individually in its `reason`; use256 `addressed` for the document when all its findings are settled. Revalidate257 after new feedback or a push. The live checker verifies coverage and freshness,258 not whether the reasoning is correct. Use `{}` when Step 4 has not run (interim,259 local-only, or workflow-owned author publication); preserve partial receipts260 and name missing reviews/findings in `remaining_work` if the loop is blocked.261- `ui_preview` — the result of Step 4.1 (run on every PR, not just frontend fixes):262 the **preview URL** (verbatim, so the ticket write-back can surface it and a263 reviewer can `omnigent claude -p '<prompt>' --server <url>`), or why it failed to264 deploy (e.g. workspace secrets not configured, or the label couldn't be265 applied under your identity). Empty when no PR was opened.266- `validation_surface` — which side the fix runs on, from Step 4.1: `server` (the267 preview build carries it; `--server <preview>` validates it), `runner` (runs in268 the runner/host process, so only a local `gh pr checkout` + `--server ''` build269 validates it — the preview's local runner is unfixed), or `both` (spans both —270 treat like `runner`). Judge from `files_changed`; default `server`, use `both`271 when unsure. Tells the write-back which command to render.272- `validation_prompt` — the Step 4.4 paste-to-an-agent prompt that reproduces the273 journey and confirms the fix. Empty when no PR was opened, except for274 workflow-owned author publication: in that mode no PR exists during the agent275 session, but this field must retain the deferred prompt for the publisher and276 Linear write-back.277- `maintainer_review` — who you requested review from in Step 4.5 (the issue278 assignee(s)), or why you couldn't (no assignee / assignee is the author, and279 what you did instead). Empty when no PR was opened.280- `session_id` — the repro session you consumed, carried through so the chain is281 traceable.282283Directly published author runs and review runs end the same way: the PR you're284landing (one you opened, or an existing in-repo PR you reviewed and kept) has a285preview, green CI, settled current-head Polly and OCR reviews, a live-validation286command, and the maintainer tagged (Step 4) — or a concrete blocker or actual287execution deadline has left an explicitly incomplete, resumable handoff. The difference is only how288a fix lands (push directly, or — for an unpushable fork PR that needs changes —289take over into your own PR carrying the contributor's commits), and that the direct author path opens a PR while the290review path adopts an existing one. Workflow-owned author publication ends after291the validated body, deferred validation prompt, and final handoff are prepared;292the publisher owns the post-publication loop. A direct draft proposal instead293ends with the incomplete handoff in `resolve-publish`; it makes no readiness or294independent-review claim. `skip_push` and `needs_more_info`295runs end earlier, with no PR to land. In every mode, **you do not merge.**