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):

```bash
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:

```bash
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.