Add staged classroom simulation and debrief orchestration

AGENTS.md

@@ -35,7 +35,7 @@ See `docs/REPOSITORY-OPERATIONS.md#delivery-resilience-for-ai-assisted-work` for
 
 ## Long-running Classroom Program
 
-The Standalone / Student / Instructor program is tracked by #288. Any work touching experience roles, classes, classroom workspaces, instructor observation, coaching, or protected Case Studies must read `docs/classroom-architecture.md`, `docs/classroom-roadmap.md`, and `docs/classroom-workstream.md` before editing. Class/API authorization work must additionally read `docs/classroom-api.md` and `api/AGENTS.md`.
+The Standalone / Student / Instructor program is tracked by #288. Any work touching experience roles, classes, classroom workspaces, instructor observation, coaching, or protected Case Studies must read `docs/classroom-architecture.md`, `docs/classroom-roadmap.md`, and `docs/classroom-workstream.md` before editing. Class/API authorization work must additionally read `docs/classroom-api.md` and `api/AGENTS.md`. Staged exercise/debrief work under #313 must also read `docs/classroom-staged-simulation.md`.
 
 Classroom invariants:
 
@@ -48,6 +48,7 @@ Classroom invariants:
 - student credentials never provide class/workspace enumeration;
 - Case Study unlock passwords are pedagogy, not authentication;
 - protected Case Study metadata/payloads are server-gated, absent from public browser/static assets, and authored `templates/*.json` remains excluded from Vercel deployment; `src/templates.manifest.js` is Standard-only and browser code must never import `api/protected-case-studies.manifest.js`.
+- staged simulation content follows `docs/classroom-staged-simulation.md`: future-stage and Instructor-only material are server-withheld, complete protected Case Study `state` cannot bypass an active staged release, and exercise/checkpoint state never enters Intake serialization;
 - public Vercel static output comes only from generated `dist/`; never set `outputDirectory` back to `.` or otherwise expose repository docs/tests/scripts/AGENTS/authoring files. `scripts/build-vercel-public.mjs` owns the allowlisted browser bundle and is part of the canonical quality gate.
 
 Every classroom PR must update `docs/classroom-workstream.md` before handoff with its issue, PR/base dependency, current HEAD, completed/incomplete work, validation, risks, and exact next action. For stacked PRs, state the merge order and never describe an unmerged dependent PR as independently mergeable.

README.md

@@ -127,6 +127,8 @@ The database stores only SHA-256 capability hashes. `CLASS_EXPIRY_DAYS` optional
 
 See `docs/classroom-api.md` for the endpoint/capability matrix and `SECURITY.md` for the security boundary. Instructor observation is implemented through the separate GET-only `/api/classes/observe` path, authorized by the Instructor class capability after class/workspace ownership is proven. It never resolves through the editable workspace-alias path.
 
+#313 staged simulation is implemented end-to-end on the active classroom branch. Protected Case Studies may carry an explicit server-only `simulation` definition; additive Neon tables persist class exercise lifecycle, optional releases, workspace readiness, and immutable debrief checkpoints. Running exercises pin the staged-definition version plus a definition fingerprint and inherit the owning class expiry. Instructor APIs/UI support staged selection, Start/Pause/Resume, controlled evidence release, debrief, explicit edit freeze/unfreeze, checkpoint inspection, Advance, and Complete. Student staged reads use the stable class-session capability, expose only current/cumulative Student-safe material, support Ready/Resume Working, and project frozen debrief Intake read-only while the server enforces writes with HTTP 423. These tables and clients do **not** duplicate live Intake state: collaboration workspaces remain the only live snapshot/revision source of truth, checkpoint snapshots are historical read-only evidence, and Classroom exercise/session state stays outside Intake persistence/export/summary. Production official Case Study stage content remains intentionally unauthored until authoritative material is supplied.
+
 ### Conflict recovery and two-window testing
 
 Updates use optimistic revision control: each complete snapshot retains the revision observed when it was captured. Text edits wait about 300 ms so typing is responsive, blur flushes pending text, and completed select, checkbox, radio, and button-driven changes save immediately where the owning control is identifiable. Only one PUT is sent at a time; edits made during that request collapse to the latest snapshot and follow the successful response at its returned revision. A stale write receives HTTP 409 and cannot overwrite the newer row.

SECURITY.md

@@ -33,6 +33,10 @@ Protected Case Study delivery is a separate server boundary. The public browser
 
 Protected Case Study catalog responses contain metadata only; payloads are selected in authenticated POST bodies, not query strings. All protected Case Study responses use `Cache-Control: no-store` and `Referrer-Policy: no-referrer`. The rotating mode password remains a pedagogical progression control and is **not** an authentication boundary.
 
+For #313 staged simulation, Student progressive disclosure is server-side authorization, not UI hiding. A Student class-session may receive only the cumulative Student-safe release through the current exercise stage. Future-stage material, Instructor facilitation/model/exemplar material, and the complete protected Case Study source `state` must not be returned through the staged Student endpoint. If a class has a staged exercise record for a Case Study, Student full-payload retrieval for that case is blocked even after exercise completion unless a future explicit reveal contract is added.
+
+Staged Student edit freeze is also server-enforced. When the represented class's current exercise has `student_editing_enabled=false`, an active `classroom-student` alias may still GET the collaboration workspace and maintain presence, but `PUT /api/workspaces/session` returns HTTP **423** with code `classroom-editing-locked`. The write must not mutate snapshot or revision. Production enforcement repeats the lock predicate atomically inside the workspace UPDATE to close check-then-write races. Standalone/primary collaboration tokens and classes with no current staged exercise are not subject to this Classroom lock.
+
 Authored JSON under `templates/*.json` is build-time source and is excluded from Vercel uploads with `.vercelignore`. Production must use committed generated manifests and run `npm run verify:protected-cases`; do not change the Vercel build back to a command that needs excluded authoring JSON. The verifier must remain in the canonical quality gate and must prove protected IDs/names are absent from public browser runtime assets.
 
 Public static delivery is also an explicit allowlist boundary. `scripts/build-vercel-public.mjs` emits only browser runtime files plus the intentionally public `docs/eula.md` to `dist/`, and Vercel must keep `outputDirectory: "dist"`. Never return static output to the repository root: production previously exposed internal Markdown and build scripts when `outputDirectory` was `.`. Other `docs/`, `tests/`, `scripts/`, AGENTS files, authoring material, and repository metadata must not be public assets.

api/AGENTS.md

@@ -133,3 +133,32 @@ Rules:
 - assignment changes use optimistic `assignment_revision` checks; a conflicting update may leave old access revoked, but must never leave old access valid or remap it to a new workspace.
 - stale presence cleanup after reassignment uses internal workspace identity, not the revoked bearer token.
 - individual live workspaces remain single-participant; cross-class destination assignment is rejected generically.
+
+## #313 staged simulation direction
+
+Read `docs/classroom-staged-simulation.md` before modifying exercise/stage/protected-resource behavior.
+
+Rules:
+- exercise lifecycle is class-scoped Instructor authority and remains separate from Intake snapshots, collaboration revision, and coaching revision;
+- Student staged exercise reads authenticate with the stable Student class-session capability and return only the represented learner's class-level release/readiness context;
+- a Student class-session token still does **not** authorize collaboration edits;
+- future-stage material and Instructor-only facilitation/model/exemplar content must be omitted server-side from Student responses;
+- never ship a complete staged Case Study to the browser and rely on UI hiding for progressive disclosure;
+- existing protected Case Study `state` is complete source/exemplar material; when that case is the active staged exercise, the Student full-payload route must not bypass staged release;
+- optional content release, debrief, and stage advance are Instructor-only and optimistic-revision protected;
+- Student/team Ready state resolves the participant's current assignment server-side; stale pre-reassignment authority cannot mutate old-team exercise state;
+- beginning debrief must capture idempotent immutable workspace checkpoints before any optional post-debrief edits;
+- if Student editing is frozen, enforce it on the `classroom-student` collaboration snapshot write path; UI read-only projection alone is not authority;
+- frozen Student snapshot PUT uses HTTP 423 with stable code `classroom-editing-locked`; the rejected request must not advance collaboration revision;
+- the real workspace mutation must repeat the Classroom freeze predicate atomically with the UPDATE so a freeze racing a Student save fails closed; a preflight policy check alone is insufficient;
+- Classroom freeze must not block workspace GET, presence, Instructor observation/coaching, Student staged reads/readiness, or Standalone/primary collaboration tokens;
+- Pause/Resume preserve the current Student editing policy. Only stage debrief defaults and explicit Instructor debrief `set-editing` may change that policy;
+- late joiners receive only the current cumulative Student release; reassignment changes workspace Intake/readiness, not class exercise stage;
+- exercise persistence uses one non-completed exercise per class initially, optimistic `exercise_revision`, idempotent optional releases, workspace-scoped readiness, immutable first-write-wins debrief checkpoints, and class-bounded expiry;
+- every running exercise pins the staged simulation version plus a definition fingerprint; later API reads/mutations must fail closed if the current protected definition does not match;
+- checkpoint snapshots are facilitation evidence only and must never overwrite or become the live collaboration snapshot automatically;
+- normal Instructor exercise payloads must expose checkpoint **metadata only**; snapshot bytes require the explicit Instructor-only current-stage debrief checkpoint read and must remain class/workspace/stage scoped;
+- the checkpoint read is GET-only, must never mint workspace edit authority, and must reject Student/join/assignment/unrelated-class authority without leaking whether another team's checkpoint exists;
+- `student_editing_enabled=false` is now a server-enforced security boundary for `classroom-student` snapshot PUT; preserve that invariant when changing exercise or collaboration code;
+- do not create production stage definitions from guessed official case boundaries. Synthetic deterministic staged content is acceptable in tests until authoritative material is supplied.
+