CLUE-550 Stage 3b: Sort Work + workspace UI for class-wide documents

[scytacki]

CLUE-550 Stage 3b — Sort Work + workspace UI

Stage 3 of the class-wide collaborative documents work. Stage 2 created the Driving Question Board but showed nothing; this PR makes it visible, sectioned, titled, and editable.

Stage 3a (#2940) has merged, so this PR targets master and holds only the Stage 3b half. 3a was split out of this branch and carried offeringId onto both metadata types, the thumbnail and title bar reading concurrent, and the split of a document's owning group (groupId) from its owning user's group (groupIdOfUserOwner). This PR's container guard builds on the first of those, and its owner guard on the last. Together the two replace the earlier single 47-file PR #2935, which can be closed.

The design spec is committed at docs/superpowers/specs/2026-07-27-clue-550-stage-3-sort-work-ui-design.md and is the document to review alongside the code. Note that the spec records the design as it stood when written — several names changed during implementation (see "The axis-modeling checkpoint" below), and docs/document-axes/ is the current-state record. The roadmap at docs/document-axes/README.md flips kind to done and records the read side of owner, container, and curriculum.

⚠️ This supersedes the edit predicate that shipped in PR #2930

PR #2930 (CLUE-525) landed canUserEditDocument on master while this work was in flight, and the base branch has since merged it. This PR replaces its semantics, and the two disagree on a real case, so it is flagged here rather than left to be discovered in review.

	CLUE-525, now on master	this PR
collaborative test	type === GroupDocument	the stored concurrent axis
group membership	groupId === user.currentGroupId	the document's owner uid vs user.userIdForGroupDocuments
metadata vs. document	read field by field	one source chosen outright
published documents	editable by the publisher	never editable by anyone
researchers	editable where owned	never given an edit affordance
class-wide documents	not addressed	editable by any member of the class

The group-membership row is the one that changes behavior. A group id is unique only within an offering, so groupId === user.currentGroupId matches across offerings — group 3 of a past assignment is a different set of students, and its document still satisfies the test. That reaches real documents, because Sort Work's "All" filter lists everything a class has produced, including documents from offerings it has moved on from. Comparing owner uids is exact instead: group_<offeringId>_<groupId> carries the offering, so two same-numbered groups can never be confused.

The merge resolution therefore removed CLUE-525's describe("canUserEditDocument") block from document-utils.test.ts: two of its cases assert the superseded contract, most directly "prefers the metadata groupId over the document's" → true, against this PR's "does not treat a document model's groupId as evidence of group ownership" → false. Every other case that block covered is covered here. The one case it uniquely had — a group document reached through the document rather than its metadata — was ported to the new contract rather than dropped.

The axis-modeling checkpoint, resolved

The project deferred "does scope need a helper, and if so what shape?" to its richest consumer. Working through Stage 3's five consumers produced two findings.

First, "scope" was three questions wearing one name. It has been split into owner (who the document belongs to), container (where it is kept: class → classUnit → offering), and curriculum (what it is about: nothing → unit → investigation → problem). Every consumer turned out to want exactly one of them, and picking the wrong one is a live defect rather than a style question:

Consumer	Branched on before	What it actually asks
Workspace title bar	document.isGroup	kind → registry presentation
Thumbnail treatment	type === GroupDocument	concurrent → collaborative styling
Edit gate	uid === user.id	concurrent, then the document's owner and container
Sort Work listener	—	curriculum breadth: a whole-unit document must survive a problem filter
byGroup / byName sectioning	type === GroupDocument	which owner the document belongs to

The listener is the sharpest illustration. It fetches documents about a whole unit, and it must not be shaped as a container question: an exemplar is kept in the classUnit container but is about a problem, so a container-shaped query would surface exemplars from every problem in a unit whenever a student was on any one of them.

Second, the answer is narrow named guards — no level enum and no unified struct. src/models/document/document-axes.ts holds hasGroupOwner, hasClassOwner, isInClassUnitContainer, and getCurriculumLabel, each reading only its own axis's stored fields — no type, no kind, no registry. That last point is load-bearing: Sort Work's "All" filter lists documents from other units, whose kinds were never registered this session, so a registry lookup would silently misfile them. The decision record, the field-by-shape table, and what is not covered yet are in docs/document-axes/reading-axes-in-code.md.

On the creation side the kind registry declares ownerType (user / group / class) and containerType (class / classUnit / offering). There is deliberately no group container level — a group document is kept in the offering alongside the problem documents its members write, and what makes it the group's is its owner.

What's in the PR

Axes

1. Axis guards and the owner/container/curriculum split (document-axes.ts, document-kinds.ts), per the checkpoint above. On the creation side the kind registry declares ownerType and containerType; on the read side, narrow guards over stored fields.
2. Explicit-null curriculum fields — the classUnit container stamps investigation: null, problem: null rather than omitting them, following the convention the rules already encode (hasPresentField treats a null field as absent). Firestore cannot match a missing field, so this is what makes "about a unit but not a problem" queryable.
3. A group owner is read off the uid, testing the group_ prefix its minter used, symmetric with hasClassOwner and its class_. That leaves the uid the single authority on who a document belongs to; the stored groupId now carries only Sort Work's group label and the two queries that retire with the canonical-pointer migration.

Sort Work

4. A whole-unit listener — a sibling of the existing unit-less listener, active only under the Investigation/Problem filters, querying unit in <variants> && investigation == null. It names no type and no kind. Equality-only, so no composite index. It is a curriculum query, not a container one: an exemplar is kept in the classUnit container but is about a problem, so a container-shaped query would surface exemplars from every problem in a unit whenever a student was on any one of them.
5. Sectioning by owner — byGroup gets a "Whole Class" section ahead of the numbered groups; byName files class-wide documents under "No Name". Ordering comes from structured sort keys instead of parseInt-ing the display label — which mattered because the group term is translatable per unit and "Whole Class" contains no digits.
6. A cross-offering defect fixed. Sort Work's "All" filter spans every offering a class has worked through, and byName resolved a group document's members by bare group id. Group 3 of a past assignment is a different set of students, so its document was attributed to this offering's group 3 — or dropped from the sort when no group of that number existed here. Resolution now goes through getGroupByOwnerId, which builds the whole owner id and compares; a document from another offering gets its own section, labelled by where the work came from (Groups from sas-2.4).

Workspace

7. Titling a class-wide document from another unit — the kind registry resolves slot titles, with a fallback naming a document whose declaring unit's config is not loaded (Driving Question Board (sas-2.4)), and a unit-declared title is scoped to its own unit so two units declaring the same kind don't borrow each other's wording.
8. One shared edit predicate — canUserEditDocument in document-utils.ts, beside its sibling isDocumentAccessibleToUser, replacing two divergent inline gates (Sort Work's ownership-only check and the resources pane's tab check).

Firestore rules

9. Canonical slots addressed as container + owner + label. A pointer path is now canonical/v1/classes/<classHash>/(offerings/<offeringId>|units/<unit>)/owners/<uid>/slots/<label>, built segment-by-segment from the document's own fields on both sides (getCanonicalPointerPath and the rules' canonicalPointerPath). Each container names only itself, so a new container level can be added later without moving pointers that already exist — they are immutable by rule. Taking the owner segment straight from uid removed the last reference to groupId anywhere in firestore.rules.
10. History-write rules for synthetic owners + a guard on the concurrent field's write path (see below).

Security: two defects found and fixed during review

Both were defects in the plan, caught before merge, and both have regression tests.

The edit predicate initially granted Edit on the user's own published documents. A publication's uid is the publisher, so the ownership arm matched in the Class Work tab where the old tab-based gate had withheld it. Not a write hole (published documents are forced read-only downstream) but a dead button, and it contradicted a live Cypress assertion in nav_panel_test_spec.js. Now excluded via isPublishedType, with researchers denied explicitly.

The history-write rule was forgeable. Gating on concurrent was unsound because concurrent was not a read-only field: any class member could update a classmate's document with {concurrent: true} and thereby grant themselves — and the whole class — read and append on that document's private history. Fixed at the write path rather than the read path: concurrentChangeOk() permits concurrent to change only on type == "group" documents, and type is itself read-only so it cannot be flipped first.

That write allowance is transitional — it exists only because two backfill paths merge-update concurrent onto existing group documents. Once the migration is complete it should be removed so concurrent becomes settable only at creation, and the create path should be constrained too (isValidDocumentCreateRequest currently checks neither concurrent nor uid). Breadcrumbs to that effect are in firestore.rules, the backfill script, and both design specs.

Separately, getDocumentOwner now throws for an unregistered kind rather than defaulting to the creating user. Defaulting would hand a group's or a class's document to whoever created it and — because a canonical slot is addressed by its owner — file it in that user's slot instead of the shared one, both silently. Two existing tests were relying on the default; they now register the kind, as production does.

Migration

scripts/backfill-group-concurrent.ts → scripts/backfill-group-document-axes.ts, now normalizing the stored axes of every type: "group" document in two passes selected so they cover disjoint sets:

pass	selects	stamps
existing	has a groupId, missing concurrent	{ concurrent: true, kind: "group" }
new	no groupId, missing curriculum fields	{ investigation: null, problem: null }

Selecting on groupId rather than on the value being written matters: a class-wide document stamped kind: "group" would break both its title resolution and its canonical-pointer slot, since the slot label is the kind.

Firestore rules deployment sequencing

The rules can be deployed before the code, in the usual order. Two parts of this change look at first like they might not allow that. Neither does, and the reasons are worth recording because both are non-obvious from the diff.

1. The history rule is purely additive.

The new arm is isConcurrentClassDocument(), gated on concurrent (not on canonical). Pre-existing group documents don't carry concurrent until a backfill runs, and the backfill only ships with this code — which reads like a catch-22 against a rules-first deploy: the rules would depend on a field nothing in production writes yet.

It isn't one. Under the rules on production today, history create and read are gated by isAuthed() && userOwnsDocument(), and userOwnsDocument() compares the document's uid to the caller's platform_user_id. Every group document's uid is the synthetic group_<offeringId>_<groupId>, which never equals a real user id — so no user can create or read group-document history in the authed domain today. The new arm can only widen that, and widens it to nothing while concurrent is absent. Deploying it early takes nothing away and enables nothing that is not already inert.

2. The canonical-pointer path move denies a path production code still uses — and that is fine.

This move landed in Stage 2 rather than here, but none of Stages 1–3 is on production yet, so whichever deploy carries this branch carries it too.

Production code reads and writes pointers at classes/<classHash>/offerings/<offeringId>/groups/<groupId>/canonical/<label>. These rules delete that match block and grant only the canonical/v1/…/owners/<uid>/slots/<label> layout above; anything unmatched falls through to the top-level default-deny. Confirmed against the emulator — under these rules a class member's read and create at the legacy path are both denied. So between the rules deploy and the code release, a client on current code would take a permission-denied on the first step of getOrCreateCanonicalDocument, the pointerRef.get(). Nothing catches it, so getOrCreateGroupDocument() would reject.

That costs nothing, because group documents are not released in the authed domains. They are opt-in per unit via groupDocumentsEnabled, which defaults off; the only unit enabling it is demo/units/qa, and the demo partition has its own recursive-wildcard allow read, write: if isAuthed(), so it is unaffected by the authed pointer paths in either deploy order — as are dev, qa, and test. The authed-domain group-document path is already non-functional, per the history rule above. Denying the legacy pointer path breaks it further, not something that works.

So no dual-path rules release is needed. The rules do not have to carry both the legacy and the canonical/v1 pointer blocks through a transition window: deploy the rules, release the code after.

Existing legacy-path pointers need no migration either. The new code never consults them — with no v1 pointer present, getOrCreateCanonicalDocument falls through to findLegacyGroupDocument, which queries the documents collection by context_id/offeringId/groupId, finds the same group document, and claims a v1 pointer for it. The document's existing canonical label is rewritten to the same value, which canonicalFieldOk permits as a no-op change. The old pointers are simply abandoned.

Testing

Full suite green: 3591 Jest tests plus the emulator rules suite. check:types and lint:build clean.

New coverage includes the axis guards across every stored document shape, sectioning and sort-key ordering, the cross-offering group cases (attribution, the missing-group-number case, and section ordering), the whole-unit listener (registration per filter, dedupe, disposal, clearing on filter change), the edit predicate across all arms including negative cases, and rules tests for the owner segment of a canonical slot plus synthetic-owner history writes and the escalation that a class member cannot flip a classmate's document to concurrent.

Three verification notes, since none is visible in the diff:

• The emulator suite must be run with --runInBand. The eight suites share one emulator and reset state per test, so running them in parallel produces ~51 spurious failures. firebase-test/package.json's test script does not pass the flag — pre-existing, and worth its own fix.
• The new rules tests were checked for discrimination, not just for passing: hardcoding the owner segment in canonicalPointerPath fails all three claim tests, and the guards' behavior tests fail when a guard is stubbed out.
• The split from PR CLUE-550 Stage 3: Sort Work + workspace UI for class-wide documents #2935 was verified by tree equality at the time it was made: the two branches' tips were byte-identical (git diff between them empty), so nothing changed behaviorally in the reorganization. They have since diverged, as this branch has merged master several times.

Not done — for the reviewer

• Manual two-student end-to-end check has not been run. The checklist is in the design spec; the two items no automated test covers are the two-student concurrent edit round-trip and the workspace title bar.
• Eager-open cost is ~670–730ms per unit load on the fast path, measured against a live dev server. Only demo/units/qa declares a slot today, so no production unit pays it. The fix is specified in the spec (defer the open, not the get-or-create) and wants its own ticket.
• Whether to drop the stored groupId is deliberately deferred. Nothing asks it the owner question anymore, but byGroup still uses it for a section label, and it does so in a way that intentionally ignores the offering: a group-3 document from a past assignment shares "Group 3" with this one's, which matches students carrying groups forward between offerings. Removing the field forces a behavior decision there, which is the real gate — not any remaining code cleanup.
• Deliberate deviation from PR CLUE-550: auto-generate a class-wide Driving Question Board per unit #2890: its absolutely-positioned centered DQB title bar is not ported — it is cosmetic and would hardcode a kind in CSS, which cuts against making "add another class-wide document" a configuration change.

🤖 Generated with Claude Code

[cypress]

collaborative-learning    Run #19723

Run Properties:   Failed #19723  •  1b115f282a: fix: allow only setting concurrent, and require the offering with groups [CLUE-5...

Project	collaborative-learning
Branch Review	CLUE-550-stage-3b-axes-sortwork
Run status	Failed #19723
Run duration	12m 48s
Commit	1b115f282a: fix: allow only setting concurrent, and require the offering with groups [CLUE-5...
Committer	Scott Cytacki
View all properties for this run ↗︎

---

Test results
Failures	4
Flaky	2
Pending	5
Skipped	0
Passing	216
View all changes introduced in this branch ↗︎

---

Tests for review

  document_tests/tiles_copy_test_spec.js • 1 failed test • Regression tests

View Output

Test		Artifacts
Test copy tiles from one document to other document > Verifies copy button states based on tile selection		Test Replay Screenshots

  teacher_tests/teacher_sort_work_view_1_spec.js • 1 failed test • Regression tests

View Output

Test		Artifacts
SortWorkView Tests > should open SortWorkView tab and interact with it		Test Replay Screenshots

  teacher_tests/teacher_sort_work_view_3_spec.js • 1 failed test • Regression tests

View Output

Test		Artifacts
SortWorkView Tests > should open Sort Work tab and test secondary sort functionality		Test Replay Screenshots

  teacher_tests/teacher_sort_work_view_6_spec.js • 1 failed test • Regression tests

View Output

Test		Artifacts
SortWorkView Tests > should retain selection state when going between sort options and viewing a sorted document		Test Replay Screenshots

  document_tests/group_test_spec.js • 1 flaky test • Regression tests

View Output

Test		Artifacts
Test group functionalities > 4-up view tests		Test Replay Screenshots

  teacher_tests/history_playback_spec.js • 1 flaky test • Regression tests

View Output

Test		Artifacts
History Playback > verify playback icon not displayed for student		Test Replay Screenshots

[scytacki]

If the stage 2 PR makes it to production before this 3b PR, we should consider keeping old class-wide documents working. That would probably mean bumping the version string in the canonical pointer paths and updating the code to handle both versions. Hopefully we won't have to do that.

[scytacki]

Consider switching default group doc canonical label to just being its kind. We'll probably need each document to have a different title at least and doing that currently means giving it a new kind. If we changed the title approach so it wasn't based on the kind, which has other benefits, then it would be reasonable to keep the slot label separate from the kind.

[Copilot]

Pull request overview

This PR advances CLUE’s class-wide collaborative documents work (CLUE-550 Stage 3b) by formalizing “axes” (owner/container/curriculum) as field-based guards, updating Sort Work to properly surface and section class-wide documents, unifying edit gating, and migrating canonical pointer addressing/rules to a container+owner+label model (with supporting backfill tooling and rule tests).

Changes:

• Introduces document-axis guards and updates document kind registry/creation to stamp owner + location fields consistently (incl. explicit-null curriculum fields for unit-scoped docs).
• Updates Sort Work grouping/sorting/listening to properly include class-wide documents under Investigation/Problem filters and to section by owner (with sort keys instead of parsing labels).
• Migrates canonical pointer paths and Firestore rules/tests to use container + owner + label; adds/updates backfill script and strengthens history authorization for synthetic owners.

Reviewed changes

Copilot reviewed 34 out of 34 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/utilities/sort-document-utils.ts	Adds section label constants, sort-key types, and new section-sorting helpers (group/name).
src/utilities/sort-document-utils.test.ts	Adds unit tests for new group-section ordering behavior.
src/models/stores/user.ts	Uses shared getGroupOwnerId() and makes userIdForGroupDocuments return undefined when not applicable.
src/models/stores/sorted-documents.ts	Adds whole-unit Firestore listener/map to keep unit-level docs visible under narrower filters, with dedupe.
src/models/stores/sorted-documents.test.ts	Adds tests for the whole-unit listener lifecycle, dedupe, and clearing behavior.
src/models/stores/groups.ts	Adds offeringId tracking and getGroupByOwnerId() to resolve group documents safely across offerings.
src/models/stores/groups.test.ts	Tests new offering-aware owner-id resolution and offeringId recording.
src/models/stores/document-group.ts	Reworks Sort Work sectioning by owner axes; uses structured sort keys and handles cross-offering group docs.
src/models/stores/document-group.test.ts	Updates/expands tests for new sectioning rules (Whole Class / No Name / cross-offering).
src/models/document/document.ts	Ensures metadata includes context_id for document-only permission/title paths.
src/models/document/document-utils.ts	Unifies edit gating in canUserEditDocument(); improves fallback titling for unregistered kinds.
src/models/document/document-utils.test.ts	Adds extensive tests for class-wide/cross-unit titles and the new edit predicate contract.
src/models/document/document-kinds.ts	Renames scope→container concepts, adds unit-scoped titles, owner/location stamping helpers, and registry-free kind labels.
src/models/document/document-kinds.test.ts	Updates tests for owner/location behavior, unit-scoped titles, kind labels, and stricter owner resolution.
src/models/document/document-axes.ts	New: field-only guards for owner/container axes + curriculum labeling utilities.
src/models/document/document-axes.test.ts	New: tests pinning guards/labeling across stored document shapes.
src/lib/scoped-document-pointers.ts	Changes pointer addressing to container + owner + label (ICanonicalSlot) and updates path builder.
src/lib/scoped-document-pointers.test.ts	Updates/extends tests for owner-segmented pointer paths and container omission for class-level slots.
src/lib/db.ts	Updates canonical get-or-create to derive pointer path owner from kind; stamps owner/location fields; registers unit-declared kinds with unit context.
src/lib/db.test.ts	Updates tests for class-wide document stamping and owner-resolution assumptions.
src/lib/db-listeners/db-groups-listener.ts	Passes offeringId through to groups.updateFromDB() for offering-aware resolution.
src/components/navigation/document-view.tsx	Switches Edit button gating to shared canUserEditDocument().
scripts/backfill-group-document-axes.ts	New: combined backfill for group-typed docs (concurrent/kind for group-owned; null curriculum for class-wide).
scripts/backfill-group-document-axes.test.ts	New: unit tests for dual-pass backfill selection, safety, and idempotence.
scripts/backfill-group-concurrent.ts	Removed: superseded by combined group-document-axes backfill script.
scripts/backfill-group-concurrent.test.ts	Removed: superseded by combined group-document-axes backfill tests.
firestore.rules	Updates canonical pointer rules to container+owner pathing; adds concurrent write guard and concurrent-history authorization.
firebase-test/src/documents-rules.test.ts	Adds rules regressions for concurrent forgery prevention and synthetic-owner history access.
firebase-test/src/canonical-pointers-rules.test.ts	Updates pointer paths for owner-segmented slots; expands integrity tests for owner isolation.
docs/superpowers/specs/2026-07-27-clue-550-stage-3-sort-work-ui-design.md	Adds design spec covering stage 3 behavior and rationale.
docs/document-metadata/metadata-fields.md	Updates metadata field docs for canonical slot semantics and offeringId/runtime notes.
docs/document-axes/README.md	Updates roadmap/status and adds link to “reading axes in code” doc.
docs/document-axes/reading-axes-in-code.md	New: documents current guard helpers, stored shapes, and known gaps.
docs/document-axes/axes.md	Expands/refines axes model (splitting container vs curriculum, etc.) and updates tables accordingly.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[scytacki]

This is replaced by #2949