feat: scaffold-verifier + explain operator commands, outcome epilogues, run social card

[abrichr]

Summary

Two read-first operator helpers plus outcome-aware endings, from the growth/operator-tooling lane.

• flow scaffold-verifier <recording|bundle> (new): reads retained action/effect evidence and emits a DRAFT effect-oracle contract (effect_contract.yaml) pre-filled from write-shaped steps — proposed system-of-record read (match selector), expected postcondition fields with explicit TODO markers, observed idempotency key, and a deployment.effects: skeleton matching docs/EFFECT_KIT.md / RestRecordVerifier conventions. Identity-vs-payload splitting reuses compiler.effect_mining helpers so drafts match real mined contracts. Explicitly a draft: loud requires-human-edit header, nothing auto-approved, and a demonstration with no consequential step is REFUSED.
• flow explain <run-dir> (new): pure read-only plain-language summary of a completed run dir — what happened, why the outcome is the safe one (names the exact check that fired for a HALT: refuted effect / identity mismatch / failed postcondition), and the suggested next command (re-run, pair an oracle via scaffold-verifier, or qualify init).
• Outcome-aware epilogues: after non-VERIFIED replay endings, failing lint exits, and non-VERIFIED tutorial runs, a 3-line epilogue prints what happened / why this is the safe behavior / the exact next command. Presentation only — fail-closed semantics and exit codes are byte-identical.
• scripts/social_card.py <run-dir> -o card.png (new): deterministic PHI-free share card from report.json (+receipt.json/bench.json when present): status badge (VERIFIED green / otherwise amber), workflow name, duration median, trials, model-calls line, short artifact SHA-256 footer, openadapt.ai URL. No network; PIL default fonts; ASCII-only glyphs.

Files changed

• openadapt_flow/scaffold_verifier.py (new)
• openadapt_flow/__main__.py (additive subcommand registration + epilogue hooks only)
• openadapt_flow/tutorial.py (epilogue text helpers)
• scripts/social_card.py (new)
• tests/test_scaffold_verifier.py, tests/test_outcome_epilogues.py (new)

README.md, _browser_setup.py, and scripts/install.sh are untouched (owned by another lane).

Verification

• ruff check + ruff format --check (pinned 0.16.3) clean on all changed files
• mypy: new modules clean; repo-wide error count identical to main
• Focused suites green: 25 new tests + tutorial next-steps/break-it + CLI new-commands + report + policy/runtime-validation + 268 replayer/receipt/teach/presentation tests
• Full runnable suite: 4543 passed, 28 skipped; the only failures (17) reproduce identically on a clean checkout of main in this environment (missing optional dev deps / substrate), as do 24 module-collection errors (openadapt_types, benchmark.* shadowing)
• python -m openadapt_flow --help lists both new commands; parser choices diff vs main is exactly {scaffold-verifier, explain} added, nothing removed

Risks / notes

• Epilogues are additive print statements on already-computed outcomes; every exit-code path was regression-tested.
• The drafted YAML intentionally uses {param: name} flow mappings for parameter bindings, mirroring the deployment.yaml conventions in docs/EFFECT_KIT.md.