feat(launchpad): ADJUDICATION.md -- the verdict contract (#118 STEP 1)

[serina-mcfall]

Summary

Adds ADJUDICATION.md, the normative verdict contract for #118 (adjudication pass over every reported finding), plus a documentation correction to its year-old implementation plan against #117's now-merged state.

Related issue

Refs #118

Issue type

Task

---

Agent provenance

Field	Value
Harness / provider	Claude Code
Model	claude-sonnet-5
Session reference	N/A - this harness does not expose a run id/URL
Initiating human	@serina-mcfall

Objective

launchpad/review-agent/ADJUDICATION.md: the contract #119 will read once #118's adjudication stage runs — verdict enum, six added finding fields, escalate-never-approve prohibitions, the nine-key adjudication block, dedupe, total refutation, and containment pass-through.

Impacted components

launchpad/review-agent/ADJUDICATION.md (new)
launchpad/review-agent/CONTAINMENT.md (one-line: point #118's existing table row at the new document)
launchpad/plans/2026-08-13-issue-118-adjudication.md (documentation correction — see Approach)

Approach and rejected alternatives

Before writing STEP 1, dispatched independent research to re-verify the existing 2026-08-13 plan's factual claims against the actual current codebase, given this repo's own established citation-rot problem (plan documents pin line numbers, file states, and measurements that drift as the branch moves). Found the plan's entire risk framing stale: its ALREADY TRUE and BUDGET sections say "#117's tree does not exist as code at all" and "the producer of this stage's input does not exist" — both were true 2026-08-13, both are now false (all 12 of #117's steps are built, 11 of 12 merged). Corrected in place, struck through per the plan's own established convention rather than deleted, ahead of any implementation.

Did not correct CONTAINMENT.md's existing #118 table row prescription (must call contain.findings_for(surfaces, nonce)), even though the plan's own research identifies it as unsatisfiable from this stage's actual JSON-on-stdin input — the plan's OPEN section explicitly marks that correction as "not for a builder to decide," deferred to whoever owns #120. Added only a cross-reference to ADJUDICATION.md in that row's label, and stated the mismatch plainly in the new document instead of silently resolving it.

Verification

Command run:

cd launchpad/review-agent && python3 -m unittest test_recordings test_fixtures test_injection_clause test_run_dimensions test_findings

Raw output:

.........................................................................................................................
----------------------------------------------------------------------
Ran 121 tests in 0.588s

OK

(Documentation-only change; this confirms nothing else in the tree was disturbed.)

• Tests or checks were run and the raw output is pasted above
• The diff is confined to the scope of the linked issue
• No secrets, keys, tokens or hostnames were added to tracked files

Not verified

• No code exists yet for task: adjudication pass over every reported finding #118 (verdicts.py, run_adjudication.py) — this PR is the contract document only (STEP 1 of the plan's 12).
• Did not attempt to resolve the CONTAINMENT.md table-row mismatch (see Approach) — deliberately left for task: treat all pull request content as untrusted data #120's owner.

Security implications

None. Documentation only — no new code path, no new credential, no new network access.

Escalations

• This is a stacked PR (base: feat/review-agent-recordings-v2 / PR feat(launchpad): fifteen recorded reviewer outputs for the deterministic suite (#117 STEP 8) #252, itself open). Should not merge before feat(launchpad): fifteen recorded reviewer outputs for the deterministic suite (#117 STEP 8) #252.
• One Medium and one Low finding from independent review were fixed before commit (a dangling cross-reference to a section that didn't exist yet — fixed by adding a proper ## Dedupe section; an overstated claim about what findings_out == findings_in alone proves — reworded to point at the actual binding guarantee, finding_id set-equality). No residual findings.

[benmitchell11]

Read the full document. This is a rigorous normative contract — the fail-closed default (UNPROVEN, never REFUTED), the deterministic dedupe/survivor tie-break, and the "escalate never approve" section's honest acknowledgment that free-text fields (verdict_evidence, severity_reason, notes) aren't mechanically constrained yet, with the exposure explicitly scoped to "nil until #119 renders them" rather than papered over, are all the right calls.

Verified the two claimed doc edits directly against the diff:

• The plan-doc correction genuinely uses the strikethrough-not-delete convention throughout, with each correction dated and backed by a real command (git rev-list --left-right --count, git ls-tree, find -iname "*adjudic*") rather than asserted. The BUDGET section's correction is honest about inverting the actual risk (real recorded output now exists; the risk is consuming it correctly, not synthesizing from nothing).
• CONTAINMENT.md's change is exactly the one line claimed — points the #118 table row at ADJUDICATION.md without touching the underlying contain.findings_for(surfaces, nonce) prescription that STEP 118 structurally can't satisfy (stdin JSON, no Surface dict). Correctly left for #120's owner rather than silently resolved here, and ADJUDICATION.md's own "Containment findings are passed through" section states the mismatch plainly instead of hiding it.

Confirmed the stacking: base is feat/review-agent-recordings-v2 (#252), which I've now independently verified and approved — so this one's dependency is satisfied. Should still merge after #252, per the PR's own escalation note. Approving.

The base branch was changed.

[serina-mcfall]

Automated review — #118 STEP 1 (ADJUDICATION.md)

Not an independent cross-model review. Both the review-code pass and the review-adjudicate pass below ran on Claude (two fresh contexts, one review then one adjudication) — no Codex pass. Treat this as a self-consistency check, not the cross-model verification this issue chain's own culture calls for elsewhere.

Method: review-code against the diff. Note the diff GitHub renders for this PR is stale — its merge-base predates #252, which has since merged — so it looks far larger than it is. Verified via git merge-tree against current origin/launchpad: only three files actually changed content — launchpad/plans/2026-08-13-issue-118-adjudication.md, launchpad/review-agent/ADJUDICATION.md (new), launchpad/review-agent/CONTAINMENT.md (one line). A second, independent fresh context then ran review-adjudicate against every finding from the first pass, re-checking each against the merged code rather than trusting the reviewer's read.

CI is green (scripts, check, adr-boundary, audit, controls, Detect Changed Paths, Dead Token Reference Guard all pass).

Confirmed findings, ranked

1. High — ADJUDICATION.md never declares the top-level stages key this stage must produce (plan STEP 4) and that #119 depends on to banner an incomplete run — despite the doc opening by billing itself as "the document #119 reads to know what arrives."
2. Medium — ADJUDICATION.md (§ Containment findings) says #117 places contain.findings_for()'s return "into the merged document's containment key." It actually goes into containment.findings; containment also carries a seven-key states map that findings_for() never returns.
3. Medium — the plan's "PR #252, open" / recordings "pending #252" language is stale: #252 merged as 30c0669ca, ahead of this PR.
4. Medium — the out-of-ladder severity fallback in ADJUDICATION.md says only "the nearest legal value," undefined. The plan's STEP 6 is precise (reported_severity if legal, else Blocker) and that precision didn't carry into the contract document a future implementer will actually read.
5. Low — CONTAINMENT.md's existing #118 table row was annotated with a doc link rather than given the new row STEP 1's done-when literally asks for. Substance met, letter of the done-when not.
6. Low — the plan's ls-tree inventory of launchpad/review-agent/ reads as exhaustive but omits roughly 20 files, including run_controls.py, which STEP 10 depends on registering into.
7. Low — ADJUDICATION.md states #119's sort/render behaviour (.get(severity, 9), which fields it renders) as settled fact; #119 is still an unmerged, actively-revised plan, not merged code.

Disputed — left for a human call, not resolved either way

One finding split the two independent passes:

• Blocker (reviewer) vs. Refuted (adjudicator) — ADJUDICATION.md's claim that input validation already guarantees reported_severity is legal before this stage touches it.
  • Reviewer's evidence: ran findings.validate() against a document carrying a field literally named reported_severity: "Info" — got [] (accepted).
  • Adjudicator's rebuttal: that test doesn't apply — #117's input document has no field named reported_severity at all; that name is introduced only by this stage's own output. The field that actually needs guarding on input is severity, and findings.validate() does reject severity: "Info" (confirmed by both passes).
  • What both passes agree on: the wording in ADJUDICATION.md and the plan's own STEP 3 done-when both write "an input carrying reported_severity: 'Info'" — a field name that can't exist on #117's actual output. Whether that's harmless shorthand (adjudicator's read) or a contract ambiguous enough that STEP 3's implementer validates the wrong field name and ships the gap the reviewer describes (reviewer's read) isn't something either pass could settle with more evidence — both already ran the code. Flagging rather than picking a side.

Not evaluated

No UI/accessibility surface — this PR is a markdown spec, no code yet. No tests to review. No mutation/control coverage — STEP 1 doesn't build the suite (that's STEP 10/11).

[benmitchell11]

Re-reviewing after my earlier approval was dismissed by the rebase/new commits. serina-mcfall's own review-adjudicate pass (posted as a COMMENTED review) caught real things my first pass missed — the missing top-level stages entry in particular is a genuine High, and the containment.findings vs containment distinction is a real precision gap. Good catch on both, and on the disputed reported_severity-vs-severity field-name ambiguity, which was a legitimately confusing sentence even if not a functional gap.

Verified the fix commit (46acd273e) against all 7 confirmed findings plus the disputed one directly in the diff, not just the commit message's claim:

1. High (missing stages key) — fixed, new "## The stages entry" section added, correctly scoped (one entry per stage, never overwrites an existing adjudication entry, ties status to nonce/total-refutation/verdict-completeness).
2. Medium (containment.findings vs containment) — fixed, now explicit that containment also carries the states map.
3. Medium (stale "#252 open") — fixed, dated correction added.
4. Medium ("nearest legal value" undefined) — fixed, now states the precise reported_severity-else-Blocker rule.
5. Low (new row vs annotation) — fixed, wording now matches what was actually implemented.
6. Low (incomplete file inventory) — fixed, now stated as a summary, not exhaustive.
7. Low (#119 settled-fact language) — fixed, attributed to #119's plan rather than stated as fact.
8. Disputed Blocker/Refuted — resolved with clear reasoning (reported_severity genuinely cannot appear on input; the wording was misleading, not a functional gap) and reworded throughout both files consistently.

Ran the tests myself in an isolated worktree rather than trusting the commit message: test_findings.py 36/36. run_controls.py shows 12/13 — the 1 failure is check_step3.py, the same pre-existing Windows-only bug I found and filed separately while reviewing #252, unrelated to this diff. Approving.

[serina-mcfall]

Review findings resolved — commit 46acd273e

All 8 open items from the earlier review-adjudicate pass are addressed in 46acd273e (docs-only; run_controls.py 13/13 and test_findings.py 36/36 both pass unchanged).

The disputed Blocker (input-validation claim, reported_severity: "Info"): checked directly against findings.py and Finding.as_dict() — reported_severity cannot appear on real #117 input at all; that name is introduced by this stage's own output. The guarantee that actually matters (an out-of-ladder severity value is rejected on input) does hold. Not a real gap. The wording naming a field that can't exist on input was genuinely misleading, though, and is corrected in both ADJUDICATION.md and the plan — now describing an out-of-ladder severity value, never a literal reported_severity field on input.

The 7 confirmed findings:

• High — added the missing ## The stages entry section to ADJUDICATION.md, documenting the top-level stages manifest entry this stage must produce.
• Medium — fixed: contain.findings_for()'s return lands in containment.findings, not the whole containment key (which also carries the states map).
• Medium — fixed the stale "feat(launchpad): fifteen recorded reviewer outputs for the deterministic suite (#117 STEP 8) #252, open" references in the plan now that feat(launchpad): fifteen recorded reviewer outputs for the deterministic suite (#117 STEP 8) #252 has merged.
• Medium — replaced the undefined "nearest legal value" severity fallback with the precise rule: reported_severity when legal, Blocker when not (defence in depth only, since input validation already guarantees reported_severity arrives legal).
• Low — reworded STEP 1's done-when from "a new row" to "annotating the existing row," matching what was actually implemented in CONTAINMENT.md.
• Low — noted the plan's file-inventory list is a summary, not exhaustive (omits run_controls.py, check_*.py, test_*.py).
• Low — stopped stating task: publish exactly one PR review comment, and re-review on push #119's sort behaviour as settled fact (#119's plan states it sorts with...) since task: publish exactly one PR review comment, and re-review on push #119 is still unmerged.

🤖 Drafted by Claude Code for @serina-mcfall. Claude-only pass — no independent Codex cross-model check on this specific fix commit.