weirsoe-party-protocol/docs/ISSUE-302-CANONICAL-LOOP-EVIDENCE.md

Issue #302 Evidence — canonical bluff → guess → reveal → scoreboard regression

Runnable command

python manage.py migrate --noinput
python manage.py smoke_staging --artifact docs/artifacts/issue-302-canonical-loop-smoke.json

migrate is the normal local bootstrap precondition when the database has not been initialized yet; the regression evidence itself is produced by smoke_staging.

What the regression proves

smoke_staging now exercises one full canonical round and fails fast with step-specific diagnostics if any of these break:

1. start_round lands the session in lie and returns a concrete round_question_id.
2. Final submit_lie auto-advances the session to guess and exposes mixed answers containing both the correct answer and player bluffs.
3. Final submit_guess auto-advances the session to reveal and returns the canonical reveal payload.
4. The reveal payload includes:
   • correct answer
   • all lies
   • all guesses
   • fooled-player references for bluff hits
5. The first canonical state read after reveal promotes the session to scoreboard.
6. Scoreboard promotion preserves the same reveal payload and exposes a leaderboard with scoreboard_ready=true.

Artifact shape

When --artifact is provided, the JSON file records:

• the exact smoke command
• session code and round question id
• deterministic guess plan used to produce both bluff hits and one correct guess
• per-step evidence for:
  • create_session
  • join_players
  • start_round
  • auto_guess_transition
  • submit_guesses
  • auto_reveal_transition
  • auto_scoreboard_transition
  • finish_game
• reveal summary (correct_answer, lie/guess counts, fooled-player ids, correct guess player ids)
• promoted scoreboard leaderboard payload

Targeted test coverage

Backend regression coverage lives in lobby/tests.py:

• test_smoke_staging_command_runs_full_flow
• test_smoke_staging_writes_phase_evidence_artifact_when_requested

Together they ensure the command stays runnable in normal workflow and that the evidence artifact contains phase-by-phase proof instead of only a generic pass/fail.

Refs #287 #302