CLUE-610: Sort Work + workspace UI for class-wide documents

[scytacki]

Sort Work + workspace UI for class-wide documents

The groundwork already merged to master creates the Driving Question Board but surfaces it nowhere; this PR makes it visible, sectioned, titled, and editable.

The presentation half (#2940) has merged, so this PR targets master and holds the remaining half. That PR 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-610-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 this PR'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.

The path already moved once, in 7.4.0, which is now on production: pointers live there at canonical/v1/…/classes/<context_id>/(offerings/<offeringId>/groups/<groupId> | units/<unit>)/slots/<label>. This PR moves it a second time, inserting an owners/<uid> segment. So unlike the first move, this one denies a path that production code is running against today.

These rules delete the 7.4.0 match blocks (offerings/{offeringId}/groups/{groupId}/slots/{label} and units/{unit}/slots/{label}) 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

---

Replaces #2942, which was opened from the previous branch name; its review discussion stays readable there.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 92.89100% with 15 lines in your changes missing coverage. Please review.
✅ Project coverage is 70.01%. Comparing base (729efc2) to head (c5cd8c9).
⚠️ Report is 60 commits behind head on master.

Files with missing lines	Patch %	Lines
scripts/backfill-group-document-axes.ts	66.66%	12 Missing ⚠️
src/utilities/sort-document-utils.ts	89.65%	3 Missing ⚠️

❗ There is a different number of reports uploaded between BASE (729efc2) and HEAD (c5cd8c9). Click for more details.

HEAD has 15 uploads less than BASE

Flag	BASE (729efc2)	HEAD (c5cd8c9)
cypress-regression	15	0

Additional details and impacted files

@@             Coverage Diff             @@
##           master    #2949       +/-   ##
===========================================
- Coverage   86.07%   70.01%   -16.06%     
===========================================
  Files         977      973        -4     
  Lines       55744    55828       +84     
  Branches    14695    14731       +36     
===========================================
- Hits        47979    39089     -8890     
- Misses       7748    16704     +8956     
- Partials       17       35       +18     

Flag	Coverage Δ
cypress-regression	?
cypress-smoke	41.76% <54.60%> (+0.10%)	⬆️
jest	56.70% <90.52%> (+0.14%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[cypress]

collaborative-learning    Run #19746

Run Properties:   Passed #19746  •  c5cd8c954b: docs: name the design spec for the story that carries it [CLUE-610]

Project	collaborative-learning
Branch Review	CLUE-610-class-wide-documents
Run status	Passed #19746
Run duration	03m 07s
Commit	c5cd8c954b: docs: name the design spec for the story that carries it [CLUE-610]
Committer	Scott Cytacki
View all properties for this run ↗︎

---

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

[Copilot]

Pull request overview

Implements the “Sort Work + workspace UI for class-wide documents” work by formalizing document axes (owner/container/curriculum), using them to drive Sort Work sectioning/listeners and edit gating, and updating canonical-pointer addressing + Firestore rules to align with the new slot model.

Changes:

• Added axis guards (document-axes.ts) and updated kind registry APIs to declare ownerType + containerType, including unit-scoped kind titling fallbacks.
• Updated Sort Work queries/sectioning/sorting to surface class-wide docs under Investigation/Problem filters and to section by owner (“Whole Class” / “No Name”) without parsing translated labels.
• Migrated canonical pointer paths to .../owners/<uid>/slots/<label>, updated Firestore rules + emulator tests, and added a backfill script to normalize axes on existing group-typed docs.

Reviewed changes

Copilot reviewed 34 out of 34 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/utilities/sort-document-utils.ts	Adds structured sort keys and new section-label constants; replaces label-parsing sort logic.
src/utilities/sort-document-utils.test.ts	Adds unit tests for the new group-section ordering behavior.
src/models/stores/user.ts	Uses shared getGroupOwnerId() and makes group-owner uid undefined when lacking offering/group context.
src/models/stores/sorted-documents.ts	Adds whole-unit Firestore listener to keep unit-level class-wide docs visible under narrower filters.
src/models/stores/sorted-documents.test.ts	Tests whole-unit listener registration, merge/dedupe behavior, disposal, and clearing on filter change.
src/models/stores/groups.ts	Stores offeringId alongside groups and adds getGroupByOwnerId() to prevent cross-offering group mis-resolution.
src/models/stores/groups.test.ts	Tests getGroupByOwnerId() and offeringId persistence on DB refresh.
src/models/stores/document-group.ts	Sections by owner axis (Whole Class / group / none; No Name / other-assignment / students) and passes sort keys to comparators.
src/models/stores/document-group.test.ts	Expands coverage for class-wide docs and cross-offering group docs in sectioning + ordering.
src/models/document/document.ts	Ensures metadata includes context_id for permission checks and axis reads.
src/models/document/document-utils.ts	Introduces unified canUserEditDocument() predicate and adds fallback titling for unresolved kinds across units.
src/models/document/document-utils.test.ts	Adds/updates tests for cross-unit class-wide titling and expanded edit-permission matrix (student/teacher/researcher, published, exemplar, etc.).
src/models/document/document-kinds.ts	Replaces scopeType with containerType, adds owner-field stamping, unit-scoped kind titles, and “kind label” fallback.
src/models/document/document-kinds.test.ts	Updates registry tests for owner/location fields, new error behavior for unregistered kind owner resolution, and kind-label/title behavior.
src/models/document/document-axes.ts	Adds leaf-module axis guards (hasGroupOwner, hasClassOwner, isInClassUnitContainer) + curriculum label helper.
src/models/document/document-axes.test.ts	Pins axis-guard behavior across the main stored document shapes (personal/problem/group/exemplar/class-wide/legacy).
src/lib/scoped-document-pointers.ts	Changes canonical-pointer addressing to container + owner + label; removes groupId segment.
src/lib/scoped-document-pointers.test.ts	Tests new canonical-pointer path shapes and owner disambiguation.
src/lib/db.ts	Derives canonical pointer paths from container + owner; stamps owner/location fields via registry; registers unit-scoped class-wide kinds with unit identity.
src/lib/db.test.ts	Updates metadata stamping expectations (explicit null curriculum fields) and ensures registered-kind owner derivation behavior.
src/lib/db-listeners/db-groups-listener.ts	Passes offeringId into groups store updates to support owner-id resolution.
src/components/navigation/document-view.tsx	Uses canUserEditDocument() for consistent Edit-button gating in the workspace.
scripts/backfill-group-document-axes.ts	Replaces prior concurrent-only backfill with two-pass normalization for group-typed docs (concurrent/kind; null curriculum fields).
scripts/backfill-group-document-axes.test.ts	Unit tests backfill selection, idempotence, and safety (never stamping kind:"group" onto class-wide docs).
scripts/backfill-group-concurrent.ts	Removed (superseded by backfill-group-document-axes.ts).
scripts/backfill-group-concurrent.test.ts	Removed (superseded by backfill-group-document-axes.test.ts).
firestore.rules	Updates canonical-pointer path construction, adds transitional concurrent write guard, and grants history access for concurrent docs via class membership.
firebase-test/src/documents-rules.test.ts	Adds regression tests for concurrent-forgery prevention and concurrent-doc history access.
firebase-test/src/canonical-pointers-rules.test.ts	Updates canonical pointer paths/tests to include explicit owner segment and adds owner-mismatch negative coverage.
docs/superpowers/specs/2026-07-27-clue-610-sort-work-ui-design.md	Adds design spec documenting axis split, query/sectioning, edit gating, and rules changes.
docs/document-metadata/metadata-fields.md	Updates metadata field docs for canonical slot ownership and offeringId implications.
docs/document-axes/README.md	Updates roadmap/status and records the new owner/container/curriculum modeling and canonical-slot addressing.
docs/document-axes/reading-axes-in-code.md	New doc describing current guard-based axis reads and stored-shape table.
docs/document-axes/axes.md	Updates conceptual axis definitions to separate owner/container/curriculum and records dynamic kind constraints.

---

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