feat(cwg): integrate JATOS sealed-dyad lobby

.gitignore

@@ -0,0 +1 @@
+dist/

JATOS-ADAPTER-VALIDATION.md

@@ -0,0 +1,82 @@
+# JATOS adapter validation record
+
+Status: **validated at the adapter boundary; C&WG integration not yet validated.**
+
+This is the repository-side record of the live validation of
+[`jspsych/jspsych-multiplayer` PR #88](https://github.com/jspsych/jspsych-multiplayer/pull/88).
+It is deliberately more than a link to the upstream PR: C&WG relies on the observed lifecycle
+ordering below, so the evidence and its limits need to travel with the study integration work.
+
+## Scope and evidence
+
+The probe was a direct adapter-only JATOS group study. It did **not** load jsPsych core,
+multiplayer plugins, or either reference-game build. Therefore it establishes the adapter's
+group/presence behavior, but not compatibility with the C&WG timeline.
+
+The live probe observed:
+
+- A and B received the same JATOS group ID.
+- Every presence-event snapshot matched an independent `getPresence()` read.
+- Either participant could seal the group.
+- Once sealed, A's departure did not allow C to replace A in B's group; C was placed in a new
+  group instead.
+- Explicit disconnect completed in order: local disconnect, then left group, then promise
+  resolution.
+- On a member departure, the remaining peer received `member-leave` before `member-close`.
+  In that interval the leaver was absent from assigned membership but still appeared in open
+  channels.
+
+The upstream PR documents this ordering and has 44 passing adapter tests at the time of this
+record. The live probe and those upstream tests are the evidence for the claims above; a passing
+C&WG structural test must not be represented as equivalent evidence.
+
+## C&WG integration contract
+
+The C&WG integration must:
+
+1. derive both `dyad_id` and the deterministic schedule seed from the shared JATOS group ID;
+2. wait for two *assigned live members*, then seal successfully before role assignment;
+3. treat membership and leave events as authoritative for admission and departure decisions;
+4. never use open-channel count alone to infer that a departed member remains part of the dyad;
+5. retain the existing timeout-plus-silence rule only as a fallback while full-study disconnect
+   behavior is being verified; and
+6. send every pre-task failure through one existing no-match terminal route.
+
+## Explicit dependency and merge gate
+
+The C&WG branch is pinned to `jspsych/jspsych-multiplayer` PR #88 commit
+[`466fe5f486e2cbff4259b41e14d2fd7f63c5ea9a`](https://github.com/jspsych/jspsych-multiplayer/commit/466fe5f486e2cbff4259b41e14d2fd7f63c5ea9a).
+The adapter's IIFE build exposes `jsPsychAdapterMultiplayerJatos` and its source defines the
+`groupId`, `getPresence()`, `subscribePresence()`, and `sealGroup()` APIs used by this plan.
+
+PR #88 does not commit its generated `dist/` files. When the study first loads this adapter, rebuild
+`packages/adapter-multiplayer-jatos/dist/index.browser.min.js` from that exact commit and vendor the
+result with provenance, rather than linking an unpinned branch URL or hand-editing a bundle.
+
+The published npm package `@jspsych-multiplayer/adapter-multiplayer-jatos@0.1.0` is **not** an
+interchangeable substitute. Its source commit is
+`6e13f54805a2832e9a0969cf4898cd48ac6658d3`; inspection of its browser bundle found the base
+adapter contract only, without the PR #88 presence and group-sealing APIs. Do not use it for this
+integration.
+
+Do not claim launch readiness while the PR #88 dependency is unpublished.
+
+Before merging or piloting the C&WG integration, run the full study against that pinned artifact in
+a deployed JATOS group study and demonstrate:
+
+- shared group-derived seed and dyad ID for both partners;
+- seal-before-role behavior for a normal pair;
+- no-match routing when a peer leaves before sealing;
+- no replacement in a sealed group after a task peer leaves; and
+- exactly one terminal screen and one cleanup path per participant.
+
+## Still owned upstream
+
+These adapter hardening cases remain in PR #88 and are not evidence supplied by the probe above:
+
+- transient reconnect;
+- pending-join versus lobby-timeout race; and
+- failed leave.
+
+Until their behavior is documented and tested upstream, C&WG must preserve its bounded lobby and
+defensive terminal routing rather than assuming an adapter operation is infallible.

README.md

@@ -48,13 +48,26 @@ These currently run on `adapter-multiplayer-local` (no backend needed) for two-t
    into a second tab so a second player joins.
 4. The first tab becomes the director, the second the matcher.
 
-For a paid Prolific run, swap `adapter-multiplayer-local` for
-[`adapter-multiplayer-firebase`](https://github.com/jspsych/jspsych-multiplayer/tree/main/packages/adapter-multiplayer-firebase)
-(one script-tag swap, see the header comment in each file) plus a real waiting room for pairing.
+The local adapter is only for two-tab piloting. The proposed paid-run path for C&WG is now JATOS
+group studies, using the JATOS adapter work in
+[`jspsych-multiplayer` PR #88](https://github.com/jspsych/jspsych-multiplayer/pull/88). It is not a
+script-tag swap: the study must derive its shared schedule seed and dyad ID from the JATOS group,
+admit two live members, seal that group before role assignment, and retain bounded no-match and
+dropout exits. The adapter dependency remains unpublished and must be pinned to an exact upstream
+commit until it is merged and released. See
+[`JATOS-ADAPTER-VALIDATION.md`](JATOS-ADAPTER-VALIDATION.md) for the live adapter evidence,
+observed leave-event ordering, and the C&WG integration gates.
 
 **Note on package versions:** the `@jspsych-multiplayer/*` package script tags below are pinned to
 `0.1.0` on jsDelivr, but those packages are not yet published to npm — publishing is gated on
 [jspsych-multiplayer PR #35](https://github.com/jspsych/jspsych-multiplayer/pull/35) ("Version
 Packages") merging. Until then, either build the packages from a local checkout of
 jspsych-multiplayer and swap in relative `dist/` paths, or wait for the publish and confirm the
 pinned version still matches.
+
+## JATOS smoke-test package
+
+Run `node scripts/build-jatos-cwg.mjs` to create `dist/reference-game-cwg-jatos.jzip` for import
+into JATOS. It packages the C&WG page, tangram assets, and pinned JATOS adapter, and configures a
+two-active-member group batch with no historical-member cap. It is a deployment smoke test, not a
+paid-study package.