Classroom follow-on: Instructor-orchestrated case simulation and staged debrief

Goal

Evolve Classroom from a collaboration/observation tool into an Instructor-led simulation environment where a class can work through a Case Study in controlled stages, use Intake to document reasoning, receive coaching, debrief together, and then advance to the next portion of the case.

This builds on #312 (live class, roster, teams, reassignment). #312 should provide the live class and team-management substrate; this issue owns exercise orchestration.

Intended teaching experience

A representative class flow:

Instructor starts or resumes a live class.
Instructor selects a Case Study/exercise.
Instructor starts Stage 1.
Students see only the case pages/evidence released for Stage 1, alongside their editable Intake.
Students/teams analyze the situation and document their thinking in Intake.
Instructor monitors all teams through the classroom dashboard and provides field-level coaching where useful.
Instructor pauses the exercise for a class debrief.
Student editing can optionally be frozen or left open according to exercise design.
Instructor reviews the expected reasoning / teaching points for the stage and can compare team responses at a high level.
Instructor marks the stage complete and releases the next case pages/evidence.
Students continue using the same Intake artifact, preserving their reasoning/results across stages.
Final debrief can compare the class's analysis, decision, actions, and results against the intended case learning objectives.

The Instructor should be able to run the experience without manually telling everyone which PDF page to open or which secret/code to enter at each transition.

Core domain concepts

Additive concepts should include something like:

Classroom Exercise

class ID
Case Study ID
exercise status: draft | active | paused | completed
current stage
started/completed timestamps
Instructor-controlled options

Exercise Stage

stable stage ID
title / Instructor notes
Student-facing case content/evidence released at this stage
relevant Intake areas/process expectations
optional time guidance
optional debrief prompts
optional model/teaching reference visible to Instructor only
completion/advance rules

Team/Student Stage State

current authorized exercise stage
acknowledgement/read state if useful
workspace revision at stage checkpoints
optional submitted/ready-for-debrief flag

Do not put exercise credentials or Instructor-only solution material inside normal Intake snapshots.

Instructor controls

The Instructor experience should eventually support:

select Case Study;
start exercise;
start/pause/resume/end a stage;
release the next case page/evidence set;
optionally reveal a hint or supplemental evidence;
optionally freeze/unfreeze Student editing during a debrief;
see which teams have started / are active / are ready;
jump directly into any team's read-only Intake;
see coaching indicators and changed-since-review state;
start a class debrief view;
advance all teams together;
handle late joiners by placing them into the current stage safely;
handle team reassignment without resetting exercise progression.

Student experience

During an active exercise, Student should have a coherent workspace with:

current Case Study title and current stage;
only the case material currently released by the Instructor;
an easy way to reference released case pages/evidence while continuing to work in Intake;
clear indication when the Instructor pauses the exercise or begins debrief;
continuity of the same Intake across stages;
no access to future case pages, Instructor notes, model answers, or unreleased evidence;
automatic stage transition when the Instructor advances the class.

A split-pane, drawer, side panel, or responsive equivalent may be appropriate so students do not have to leave Intake to reread the case. The exact UX should be validated with real browser tests rather than assumed.

Debrief model

The debrief should not simply overwrite Student work with a model answer.

Preferred principles:

preserve the Student/team Intake exactly as their work product;
allow the Instructor to discuss expected reasoning, key distinctions, and likely conclusions separately;
optionally highlight fields/rows that map to stage learning objectives;
reuse the coaching channel for targeted feedback;
permit a stage-level "ready for debrief" or checkpoint state without turning Intake into a graded LMS;
retain enough stage/checkpoint evidence to discuss what changed after the debrief.

Potential future views:

class heatmap / progress summary by team and coachable target;
compare teams on selected Intake fields;
Instructor reveal of exemplar reasoning;
stage-specific debrief prompts and facilitation notes.

Case content model

Protected Case Study delivery from #295 remains the security boundary.

Future staged Case Studies should support:

Instructor-visible complete case definition;
Student-visible content segmented by stage;
future-stage material withheld server-side, not merely hidden in the DOM;
Instructor-only facilitation notes / teaching points;
stage-linked images, documents, tables, or evidence;
optional answer/rationale material never sent to Student clients before authorization/reveal.

Do not solve this by shipping the whole case to the browser and hiding sections with CSS.

Best-practice simulation principles

Design toward:

progressive disclosure — reveal information in deliberate increments;
shared pacing with local work — teams work independently but Instructor controls major stage transitions;
clear stage objectives — students know what they are trying to accomplish without being handed the answer;
observable work products — Intake captures reasoning, not just final answers;
facilitated debrief before reveal — discussion happens before model/exemplar content is shown;
late-join resilience — a late participant enters the class at the current stage;
reassignment resilience — moving a Student between teams does not expose unreleased content or destroy prior team work;
accessibility — all stage controls and case material remain keyboard/screen-reader usable;
determinism for teaching — Instructor can pause/advance intentionally and the class does not race ahead because of client timing.

Security/invariants

Future-stage Student content is server-gated.
Instructor-only solution/debrief content is never sent to Student clients until explicitly released, if ever.
Student cannot advance exercise stage.
Student cannot enumerate other teams or retrieve their Intake.
Instructor can control only the represented class.
Exercise state is separate from Intake serialization.
Team reassignment does not merge Intake snapshots automatically.
Protected Case Study public/static boundary from Classroom 7/8: Server-gated Case Study catalog and payload delivery #295 remains intact.
Standalone remains unaffected.

Suggested implementation sequence

Classroom follow-on: Instructor-run live class, roster, and dynamic team management #312: live class creation, one-code Student admission, waiting roster, team creation/reassignment.
Exercise domain/API: class exercise + stage state, Instructor start/pause/advance.
Stage-aware protected content delivery.
Student stage-aware case panel integrated beside Intake.
Instructor exercise console with team progress/navigation.
Debrief/checkpoint UX.
Browser E2E for staged reveal, pause, late join, reassignment, and unauthorized future-stage access.
Accessibility and facilitator workflow validation.

Relationship to current Classroom program

Parent vision: Classroom experience program: Standalone, Student, and Instructor #288.
Depends heavily on Classroom follow-on: Instructor-run live class, roster, and dynamic team management #312.
Reuses Classroom 5/8: Instructor class dashboard and read-only live workspace observer #293 observer, Classroom 6/8: Field-level coaching feedback channel and student feedback UI #294 coaching, and Classroom 7/8: Server-gated Case Study catalog and payload delivery #295 protected-resource delivery.
Classroom 8/8: Browser E2E, accessibility, and CI protection for role/classroom journeys #296/Add critical-path Playwright and accessibility regression suite #279 should finish the present browser-quality foundation first.
This issue is deliberately a follow-on rather than expanding PR Add Classroom browser E2E and accessibility coverage #308.

Definition of done

An Instructor can run a complete staged Case Study exercise from one classroom console: create/start the exercise, release case information stage by stage, monitor and coach teams, conduct debrief checkpoints, advance the class together, support late joiners/team moves, and complete the exercise without exposing unreleased case or solution content to Students.

Active implementation

Draft PR: Add staged classroom simulation and debrief orchestration #315 — Add staged classroom simulation and debrief orchestration.
Branch: feature/classroom-staged-simulation.
Base: Classroom follow-on: Instructor-run live class, roster, and dynamic team management #312 / PR Add Instructor-run live classroom management #314 merge b141d55050207e4cf7ce842a4452a220a5268968.
Canonical contract: docs/classroom-staged-simulation.md.
Architecture checkpoint: 808bdfaa74e7e6a11a88173ee43c5c86d9a8da51.
Governance checkpoint head: 8f158aa58ba70b188e4b4bfe28490499f1279a4c.

Decided architecture

exercise/stage orchestration is class-level and separate from Intake/collaboration/coaching state;
Student stage reads use Student class-session authority; collaboration edits remain assignment-workspace authority;
future-stage and Instructor-only content is server-withheld, never browser-hidden;
complete protected Case Study state is source/exemplar material and is not the staged Student feed;
staged cases require explicit server-only simulation definitions; no automatic/guessed staging of official cases;
active staged case full-payload Student retrieval must be closed as an authorization bypass;
team readiness belongs to the workspace;
begin-debrief captures immutable workspace checkpoints before optional post-debrief edits;
edit freeze is not complete unless the Student collaboration write route enforces it server-side;
late join receives current release; reassignment preserves class stage but destination team Intake/readiness wins;
lifecycle mutations use optimistic exercise revision;
synthetic deterministic stage content is used for infrastructure tests until authoritative production case content is supplied/reviewed.

Completed Tranche 2 — staged Case Study authoring schema

implementation checkpoint: af6b6f21a8e4f25f014a8362857a1c15e252775b;
documentation checkpoint: ccae0a1800b7e2dd269c2da19ad095685698db1e;
optional simulation definitions are protected Case Study-only and remain server-side;
Student and Instructor content are structurally separate with validated stable IDs and cross-references;
unsafe arbitrary fields/URLs, duplicate/colliding IDs, bad references, double release, and orphan content are rejected;
existing non-staged Case Studies remain compatible;
no official production case stages were invented;
validation: 260 tests / 259 pass / 0 fail / 1 intentional skip, required Browser E2E 26 passed / 8 intentional skips / 0 failed, Template Manifest Guard and Dependency Review green.

Completed Tranche 3 — exercise persistence / repository

implementation checkpoint: c01dfff2f2bd1f9d7625901860210cc00eee7051;
documentation checkpoint: 457cb50edd94e355a9e7ec83f11972590da6b4b7;
additive exercise/release/workspace-state/checkpoint schema;
one open exercise per class with class-bounded retention;
pinned staged-definition version + fingerprint;
optimistic exercise lifecycle revision;
idempotent optional release with one revision increment only for a new release;
Student class-session/current-workspace readiness semantics;
team readiness stays with the workspace across reassignment;
Waiting cannot mark workspace Ready;
immutable first-write-wins debrief checkpoints with snapshot isolation;
class/workspace scoping and no Intake merge/copy;
deterministic in-memory repository parity;
final validation on documentation head 457cb50edd94e355a9e7ec83f11972590da6b4b7: 265 tests / 264 pass / 0 fail / 1 intentional skip, required Browser E2E 26 passed / 8 intentional skips / 0 failed, CI/CodeQL/Dependency Review/Template Manifest Guard all green.

Completed Tranche 4 — exercise APIs / authorization

implementation/security-test checkpoint: 5afc0041db89348d97ca0986cab89491765d0e00;
documentation checkpoint: 2282925ce7f5f52609f85bb0a8610856ecf87653;
Instructor staged exercise create/read/lifecycle API with optimistic revision;
current-stage optional release and immutable debrief checkpoint capture;
Student class-session current released-content read with future/Instructor content withheld server-side;
Student current-workspace readiness with server-observed revision and reassignment race protection;
staged definition version/fingerprint drift fails closed;
Student complete protected payload bypass is blocked for a staged class/case, including after completion;
no claimed edit freeze yet; Tranche 4 exposes editFreezeEnforced: false;
validation: 273 tests / 272 pass / 0 fail / 1 intentional skip, required Browser E2E 26 passed / 8 intentional skips / 0 failed, all required repository gates green.

Completed Tranche 5 — server-enforced Student editing policy

implementation checkpoint: 261b28d488538964ccd73132ed568d73628f6411;
documentation checkpoint: 1a0b316fabfb46f07267acbc6393b3a1ad2c7edc;
Classroom Student snapshot PUT is server-gated by current exercise edit policy;
frozen write contract is HTTP 423 + classroom-editing-locked;
frozen writes cannot mutate snapshot/revision, including freeze/write races because production SQL repeats the lock predicate atomically;
GET/presence/observer/coaching/staged-read/readiness remain available;
Standalone and no-exercise Classroom behavior remain unchanged;
Stage debrief default policy is applied and Instructor can revision-safely freeze/unfreeze during debrief;
Pause/Resume preserve the current editing policy;
validation: 274 tests / 273 pass / 0 fail / 1 intentional skip, required Browser E2E 26 passed / 8 intentional skips / 0 failed, all required repository gates green.

Completed Tranche 6A — Instructor exercise console foundation

GET /api/classes/exercise discovers only explicitly staged Case Studies through summary-only availableCaseStudies;
discovery does not return simulation, protected source state, future Student material, or Instructor-only facilitation content;
memory-only src/classroomExerciseInstructor.js is connected to the Instructor class lifecycle;
existing live Instructor dashboard contains the Class exercise console shell.

Completed Tranche 6B — staged Case Study selection and draft creation

accessible staged Case Study selector is populated only from authorized staged discovery;
Create draft sends only the selected caseStudyId;
successful creation and idempotent existing-draft reuse hydrate the represented server exercise without local persistence;
selector/create become disabled once an exercise exists;
409 create conflicts trigger authoritative GET refresh instead of automatic mutation retry;
controller public state sanitizes protected case data and never exposes the Instructor capability;
deterministic browser acceptance uses only a synthetic staged test case, proves draft create, then reloads and resumes that server-owned draft;
selector/label/options are explicitly local-only and summary-excluded; Classroom exercise setup does not enter Intake persistence or Copy & Paste Summary;
no official production Case Study staging was invented;
four-browser acceptance timeout was raised from 30s to 45s because its prior green runtime was already 26.1s before the additional exercise bootstrap request; no assertions were removed.

Completed Tranche 6C — Start/Pause/Resume and current-stage Instructor context

Start is draft-only, Pause is active-only, Resume is paused-only;
lifecycle PATCH uses the currently observed exerciseRevision;
optimistic 409 conflicts reload authoritative state instead of replaying stale intent;
current stage title, Student objective, suggested time, and stage-referenced Instructor-only facilitation render after Start;
Pause is clearly class pacing and does not imply Student editing freeze;
synthetic browser fixture and focused controller tests cover revision progression and conflicts;
browser acceptance covers Start -> Pause -> Resume -> reload;
the pre-existing four-browser acceptance timeout is narrowly raised to 45s; no assertions are removed.

Completed Tranche 6D — optional evidence release and team readiness/progress

current-stage optional Student evidence only; future-stage optional content is not rendered as an Instructor release control;
revision-safe release-content with idempotent already-released replay and authoritative refresh for stale new releases;
Ready/Working progress from current-stage Instructor-authorized workspaceState;
progress rows reuse existing Instructor observer/coaching navigation;
release/readiness/progress remain memory-only and summary-excluded;
real-browser acceptance proves release, persisted Released state, Ready progress, and observer navigation;
Instructor rail nested scrolling was corrected so workspace rows remain actually clickable as the console grows;
validation: 285 tests / 284 pass / 0 fail / 1 intentional skip, required Browser E2E 26 passed / 8 intentional skips / 0 failed, all required repository gates green on 2c8145b....

Completed Tranche 6E — Begin Debrief, checkpoint review, editing policy, and compact class rail

revision-safe Begin Debrief from active current-stage work;
immutable checkpoint status shown as workspace + captured collaboration revision only; snapshot bodies are not exposed through controller public state;
authoritative studentEditingEnabled presentation separated from Pause/Resume;
debrief-only Freeze/Allow Editing with revision-safe set-editing, while the existing HTTP 423 server guard remains the enforcement boundary;
409 mutations authoritative-refresh without replay;
observer/coaching remains available through debrief/freeze;
Instructor class/team rail now has accessible collapse/expand; <=700px defaults to a compact collapsed class header and reopens through the real control;
broader Notes/mobile alignment is tracked: prefer compact discoverable launchers/default-collapsed behavior over hiding either workspace;
validation: 288 tests / 287 pass / 0 fail / 1 intentional skip, required Browser E2E 26 passed / 8 intentional skips / 0 failed, all required repository gates green on 61aa582...;
durable documentation checkpoint: 41c2bdd....

Completed Tranche 6F — Advance/Complete and Instructor-console lifecycle completion

Advance is available only from active non-final debrief and follows the protected authored stage sequence;
Advance and Complete both use the currently observed exerciseRevision; stale lifecycle intent is never replayed after 409;
Advance returns the next authored stage to work with Student editing restored and renders that stage's current Instructor context;
Complete is available only from final-stage active debrief;
Completed is terminal UI, hides further lifecycle/edit-policy mutations, preserves final checkpoint review, and explicitly releases no additional Student/Instructor-only/exemplar/full protected Case Study material;
the deterministic browser case now has two synthetic stages and preserves prior-stage checkpoints;
real-browser acceptance proves Stage 1 -> debrief -> Advance -> Stage 2 -> debrief -> Complete -> reload with observer continuity;
validation: 290 tests / 289 pass / 0 fail / 1 intentional skip, required Browser E2E 26 passed / 8 intentional skips / 0 failed, all required repository gates green on e2f5534...;
durable documentation checkpoint: f36be4da....

Completed Tranche 7A — Student current-stage case-reference foundation

dedicated Student staged-exercise client uses the stable live Student class-session capability, not assignment/workspace authority;
workspace reassignment no longer tears down staged case reference authority;
only Student-authorized case summary, current stage/objective, phase/editing state, and cumulative released Student-safe content reach the reference DOM/public state;
future-stage and Instructor-only material are discarded client-side in addition to being withheld by the production Student endpoint;
staged content/capability stay memory-only and out of Intake/browser storage/summary/export/URL state;
mobile case reference defaults collapsed;
real-browser acceptance uncovered the pre-existing fixed team/Notes dock overlapping the mobile reference control; Student narrow layout now puts that dock in normal document flow, with no forced-click workaround;
browser acceptance proves Stage 1 released content appears, Stage 2/Instructor material does not, reload resumes server state, and the staged endpoint uses the stable Student session capability;
validation: 295 tests / 294 pass / 0 fail / 1 intentional skip, required Browser E2E 26 passed / 8 intentional skips / 0 failed, all required repository gates green on 91d7029...;
durable documentation checkpoint: 4605fff....

Completed Tranche 7B — Student Ready / Resume Working

readiness is available only during active work with a current assignment;
Student uses only the stable class-session capability for PUT /api/classes/exercise/student/ready, sending exactly { ready: boolean };
Ready displays the server-captured collaboration revision and Resume Working clears readiness;
assignment/phase conflicts authoritative-refresh without replaying stale intent;
focused/browser coverage proves exact stable-session requests and Ready -> Resume Working;
implementation spans e43b84c... through 247479f..., with browser acceptance through d311b7b....

Completed Tranche 7C — frozen-debrief Student Intake projection

authoritative frozen debrief state projects Student Intake read-only while server HTTP 423 remains the actual authorization boundary;
original control state restores on Allow Editing, advance/completion, staged-context loss, or disconnect;
paused frozen debrief remains read-only;
Leave Class remains available;
Notes freeze with Intake because Notes are serialized into the collaborative snapshot;
integrated browser acceptance uses real Instructor Begin Debrief -> Student frozen Intake -> Allow Editing -> restored Intake;
implementation spans 8d70e84... through 50435c3...;
durable documentation checkpoint: 636419a9a49cda92e57036ad990e814550aa1081.

Completed Tranche 8A — immutable checkpoint inspection versus current live work

normal exercise payloads carry checkpoint metadata only; explicit Instructor-only GET retrieves one current-stage debrief snapshot;
checkpoint read is class/workspace/stage scoped, GET-only, and never mutates or restores collaboration state;
snapshot bytes remain transient and outside controller public state / Intake persistence / export / summary / resume;
existing Instructor observer renderer presents the immutable captured revision and pauses live polling/coaching while historical evidence is displayed;
explicit View current live Intake restores a fresh live observer view;
focused and integrated browser coverage protects metadata-only listing, Instructor-only access, Student rejection, historical-vs-live rendering, and return-to-live behavior;
implementation spans 0ce4b8d... through 8530128..., with browser isolation/stabilization through 04587bf...;
repository quality baseline: 302 tests / 301 pass / 0 fail / 1 intentional skip.

Completed Tranche 9 — integrated staged acceptance

late join, reassignment/stale-authority cutoff, workspace-scoped readiness, direct frozen-write 423 non-mutation, progressive-disclosure/full-payload denial, mobile Student/Instructor staged UX, accessibility, and checkpoint-vs-live comparison are browser-covered;
implementation/security acceptance ends at 89a5321a750606cff6fbf34ccf75ef40dc3def07;
validation: 302 tests / 301 pass / 0 fail / 1 intentional skip, Browser E2E 28 passed / 10 intentional skips / 0 failed / 0 flaky, all required gates green.

Completed Tranche 10 — final audit / merge readiness

full Classroom follow-on: Instructor-orchestrated case simulation and staged debrief #313 branch, authorization boundaries, staged-content disclosure, freeze semantics, schema/retention/rollback, public manifests/Vercel output, capability non-persistence, Standalone compatibility, and documentation were reconciled;
README/API/roadmap stale tranche language was corrected;
no production official Case Study staged definition was introduced;
PR Add staged classroom simulation and debrief orchestration #315 has no unresolved review threads, is mergeable, and the final audited head is 8974519108d6735383b8358373d005188501a785;
final head validation: repository quality 302/301/0/1, Browser E2E 28 passed / 10 intentional skips / 0 failed, CI/CodeQL/Dependency Review/Template Manifest Guard all green.

Status

Implementation is complete and PR #315 is ready for review. Keep this issue open until the PR is merged. Do not infer or add official production Case Study staging until authoritative material is supplied and reviewed.

Follow-on roadmap after closeout

The #313 orchestration engine is complete. Remaining production/facilitation work is tracked separately:

Classroom follow-on: Protected staged case assets and rich Student case rendering #316 — protected staged case assets and rich Student case rendering (next / P0);
Classroom follow-on: Author and validate the first production staged KT Case Study #317 — first production staged KT Case Study from authoritative reviewed source material;
Classroom follow-on: Universal Intake target identity and staged guidance/coaching #318 — stage-linked Intake guidance + complete coachable target identity;
Classroom follow-on: Instructor class debrief comparison and progress view #319 — Instructor class debrief comparison/progress view;
Classroom UX follow-on: Join sharing and compact mobile workspace chrome #320 — join sharing/QR + compact mobile workspace chrome.

Close #313 when PR #315 merges. The next implementation issue is #316.

Published / merged

PR #315 was squash-merged to main as 7c6afa4069ac5de5eae8ec0c9b0959084650c93a.

#313 is complete and closed. The staged orchestration engine is now the main baseline.

Next roadmap:

Classroom follow-on: Protected staged case assets and rich Student case rendering #316 — protected staged assets + rich Student rendering (next / P0);
Classroom follow-on: Author and validate the first production staged KT Case Study #317 — first production staged KT Case Study from authoritative reviewed source material;
Classroom follow-on: Universal Intake target identity and staged guidance/coaching #318 — stage-linked Intake guidance + complete coachable target identity;
Classroom follow-on: Instructor class debrief comparison and progress view #319 — Instructor class debrief comparison/progress;
Classroom UX follow-on: Join sharing and compact mobile workspace chrome #320 — join sharing/QR + compact mobile workspace chrome.

Do not author production official staged Case Study content before #316 and source review.

Production publish closeout

The #313 implementation merged in PR #315 and is now production-published after #321 / PR #322 restored the Vercel function budget. Production deployment for exact merged-main SHA 21bff1d1c5a70caff0aa94aadd58abcb0644f397 reached READY with a clean runtime-error scan. Remaining production-case capability gaps are tracked in #316–#320; the immediate next issue is #316.

Add staged classroom simulation and debrief orchestration (#315)

Refresh Classroom production handoff and roadmap (#323)

Classroom follow-on: Instructor-orchestrated case simulation and staged debrief #313

Description