coulomb-social/docs/usecases/README.md

Use-case collection and regression infrastructure

This collection records the jobs people actually do in coulomb.social and keeps established behavior working while it is rebuilt and moved off Bubble. Start with CSOC-UC-008, ReichelAg weekly founder calls: duplicate the full previous protocol, edit the new agenda/notes manually, copy for external email.

Collection

• catalog.md: discovery backlog, including inferred candidates.
• registry.json: executable index of established journeys and required tests.
• reichelag-weekly-call.md: user-confirmed behavior and remaining manual review.
• first-transfer-review.md: real-user migration acceptance walkthrough.
• platform-communication.md: recovery/invitation/notification catalogue and explicit owner-spanning regression gaps under WP-0010.
• tests/usecases/fixtures/: synthetic scenarios; never private protocol content.

Confirmation, regression protection and transfer acceptance are independent. established: true means a user-confirmed behavior contract must keep passing; it does not mean the use case has been accepted for productive transfer. Only the user's review can grant that, with an explicit acceptance reference.

Run the gate

Requires Python 3.12+, uv, Node 20+ and npm. Locked Python/Node dependencies are tracked. First setup (Chromium OS libraries must be available):

uv sync --locked
make setup-usecases
# On a fresh Linux CI runner, install browser OS libraries too:
cd scripts && npx playwright install --with-deps chromium

From the repository root:

make test            # Fast application checks; browser tests explicitly deselected
make test-usecases   # All registered journey tests, including actual browser UI
make test-browser    # Only browser journeys, still validates registry coverage
make check           # Required lint + full application/use-case/browser gate

make check is the release/change validation command. Browser tests are required, not conditionally skipped when Node, Playwright or Chromium is absent. A missing dependency or test mapping fails the gate. JUnit results are written under var/test-results/ (gitignored). The ordinary make test is intentionally the fast iteration command, not proof that all established journeys still work.

The registry validates collected node IDs before deselection: deleting or renaming a protected test, removing its use-case marker, or giving it the wrong browser/fast layer fails with Use-case regression contract failed. Disabling a protected check with skip/xfail is also rejected. Update mappings deliberately when refactoring; do not delete a required behavior to turn a failure green.

What ReichelAg protection covers

Fast test: real application POSTs, full protocol duplication, edit/source independence, rendered clipboard controls and reader access.

Browser test: isolated Django DB and temporary content root; synthetic writer, reader and outsider; actual sign-in/list/page/duplicate/edit/save/reopen screens; real static clipboard script; heading/list export as HTML/plain text; blocked clipboard manual selection; sample rich email-editor consumption; reader mutation and outsider read denial. It checks that browser writes persist and the original protocol remains unchanged. Unexpected external browser requests are blocked.

Clipboard writes are intercepted using native browser ClipboardItem objects; there is no OS clipboard export of private notes, external issuer or email send. The test uses developer sign-in in its isolated test instance. It does not prove production OIDC, restart/backup recovery, actual ReichelAg corpus fidelity, or compatibility with the user's usual mail client. User acceptance separately records the weekly-call/mail-client workflow on revision16. Remaining broader recovery/content/cohort acceptance belongs to WP-0012–0014; WP-0008 is finished.

The smaller node scripts/test-copy-content.mjs check remains available for clipboard component debugging; the required browser gate exercises the actual Django screens instead of substituting a hand-built page.

Private local Visual protection also verifies owner/viewer image bytes and denies outsider, cross-tenant, revoked and archived access. The real-browser journey loads a synthetic one-pixel cover before/after duplication and for the reader; direct outsider image access fails. Traversal, symlinks, disguised HTML and asset overwrite are covered by fast tests. This is local implementation evidence; weekly-call page/list visuals are user-accepted. Wider corpus and content review remain WP-0014-T01 / WP-0013-T02.

The test database is a temporary SQLite file per run/worker. This gives the live server separate database connections for concurrent cover requests rather than sharing one in-memory connection across threads. It remains isolated from developer and production databases; image requests are not serialized or skipped.

Add the next established use case

1. Give it a stable CSOC-UC-NNN ID. Describe actor, goal, original steps, expected outcome, evidence confidence, privacy and migration differences. Keep an inferred case in the catalogue until the user confirms it.
2. Write a synthetic fixture with synthetic: true and matching usecase_id. No real business content, member identifiers, tokens or recordings in fixtures.
3. Add fast and real-browser tests with @pytest.mark.usecase("CSOC-UC-NNN"); browser tests also have @pytest.mark.browser. Use the isolated live-server pattern; drive visible user steps rather than recreating app markup.
4. Register exact test node IDs, narrative/fixture paths and the preserved behavior contract in registry.json; run make check. Established tests cannot skip.
5. Separately record real-user review/transfer acceptance with its receipt. If behavior changes intentionally, update the user-approved contract and tests together; keep unresolved gaps in live work records.

CI and operational boundary

.forgejo/workflows/usecases.yaml requests the existing fleet ubuntu-latest container runner on main pushes, pull requests and manual dispatch. It uses the triggering SHA archive, locked installs, browser OS dependencies and make check. It neither deploys the app nor imports production data. No credentials are embedded; archive checkout needs existing public/read admission.

Local gate success is not a remote CI receipt. Confirm the runner label can run the job and the repository has Actions enabled; preserve reports/artifacts and make usecase-regressions a required merge check through the Forgejo owner lane. That external admission/enforcement work is tracked as CSOC-IN-0005. Until confirmed, the workflow is configured and the local gate is mandatory by this repository's documented process; protected-branch enforcement is not claimed.

Verification receipt — 2026-10-06

• make check: 88 passed, including the actual ReichelAg browser journey.
• make test-usecases equivalent command: 2 passed (fast + browser), 86 deselected.
• JUnit XML: var/test-results/check.xml (88 tests, 0 failures/errors) and usecases.xml (2 tests, 0 failures/errors).
• Deliberately collecting only tests/test_reichelag_workflow.py with --verify-usecases returns exit 4 and identifies the missing browser check.
• Ruff passes changed Python infrastructure/test files; whitespace check passes.
• Remote Forgejo run and merge enforcement are not asserted; CSOC-IN-0005 owns those receipts. Existing repository-wide lint debt remains WP-0008-T07.