[alvarohulse]

Summary

Adds a production proofshot replay workflow for turning a stabilized browser flow into repeatable reviewer evidence. Versioned replay cases are validated before browser startup, use exact session routing, reject ephemeral @eN references, require an explicit behavioral assertion and screenshot, and succeed only when canonical evidence reports PASS.

This also hardens recording finalization, recovery ownership, evidence verdicts, public redaction, and PR artifact formatting so interrupted or incomplete sessions fail closed without weakening unrelated session isolation.

What Changed

• Added versioned replay cases, controlled agent-browser command execution, sanitized human-testing instructions, and fresh-session replay orchestration.
• Preserved the approved verdict contract: assertion or fatal failures are FAIL; nonfatal console/network or evidence-trust problems are INCOMPLETE; clean asserted evidence is PASS.
• Made recording finalization wait for five seconds of stable positive size, retain recovery ownership for unverified media, and keep physical trimming separate from canonical timeline offsets.
• Added replay video, screenshot, verdict, and human-testing output to curated PR evidence.
• Removed unsupported token and cost estimates from reviewer output.

Risk Assessment

Moderate internal-tool risk. The change affects replay, session recovery, verdict generation, and evidence publication, but does not alter a target application's behavior. Lifecycle integration coverage, repeated environment-runtime executions, FFmpeg integration, and a fresh end-to-end replay exercise the changed contracts.

Testing

Static Testing

• npm run build — passed.
• npm test — 36 files and 599 tests passed in 165.23 seconds.
• npm run test:ffmpeg — passed; finalized video was trimmed and converted to MP4.
• npm test -- src/environment/runtime.test.ts — 20/20 independent retry-disabled processes passed in 123 seconds.
• GitHub Actions Build and Test — passed at the final PR head.

Reviewer Testing

1. Create a version 1 replay case with stable CSS selectors, one assertion, one screenshot, and high-level human instructions.
2. Run proofshot replay <case-file> against a small local page.
3. Confirm it starts a fresh isolated session, routes every action to that exact session, emits USER_TESTING.md, and finishes with PASS.
4. Replace a selector with @e1 and confirm validation rejects the case before creating a session.

Evidence

• Fresh replay verdict: PASS.
• Recording: 3-second finalized MP4.
• Screenshots: 1 curated PNG.
• Errors: 0 console errors and 0 server errors.
• Isolation: rejected replay input did not disturb concurrent sessions.

Related Work

• Measure the exploration-to-review workflow on representative UI changes #10 — Measure the exploration-to-review workflow on representative UI changes
• Verify interrupted and concurrent ProofShot sessions on the deployed release #11 — Verify interrupted and concurrent ProofShot sessions on the deployed release
• Choose ownership for browser exploration, proof replay, and E2E coverage #12 — Choose ownership for browser exploration, proof replay, and E2E coverage
• Define the reviewer evidence and human testing handoff #13 — Define the reviewer evidence and human testing handoff
• Prototype a deterministic fresh replay contract for stabilized flows #14 — Prototype a deterministic fresh replay contract for stabilized flows