rfc-app/docs/superpowers/specs/2026-06-03-m3-design.md

# M3 — Registry mirror + routing + runtime branding — design

**Date:** 2026-06-03
**Spec basis:** `docs/design/multi-project-spec.md` §22, Part C slice **M3**
**Status:** design, pending plan

## Goal

Carry §22 slice **M3** end-to-end: turn the framework from single-project
(the N=1 default at the legacy corpus root) into genuinely multi-project —
projects declared in a registry, reachable at `/p/<project>/`, branded at
runtime. M3 is the slice that makes a *second, named* project reachable by
URL at all.

**Driving objective:** stand up the deployment's `bdd` "planner" project,
reachable at `https://rfc.wiggleverse.org/p/bdd/` as an **`unlisted`**
project (readable by direct link; not in the directory). After **M3c** the
planner is navigable; after **M3d** its entries land `active` (the behavior a
planner wants). The planner's `bdd`-specific scenario/coverage *surface* is
**M5**, out of scope here.

> Note on the original URL ask `/bdd/{PLANNER_TOKEN}/`: resolved to the
> existing §22 model — `bdd` is an `unlisted` project at `/p/bdd/`; the
> "token" is just the shareable link (the unguessable slug). No token-gate
> feature is built; `unlisted` visibility already exists (gated in M2).

## Decisions

### Already resolved upstream (commit `ad2ece1`, §22.13/§22.10/§22.4)
1. **Default project `id`** = config-derived slug
   (`DEFAULT_PROJECT_ID` > slug(deployment name) > `default`). M1's `default`
   bootstrap id is **re-stamped** to it in M3 before any `/p/` URL is public.
2. **Entry segment** = generic `/p/<project>/e/<slug>` for every type; the
   noun (RFC/Spec/Feature) is a type-driven UI label, not in the path.
3. **Legacy `RFC-NNNN`** = frozen, read-only display label in frontmatter;
   never used for routing/lookup; never assigned to new entries.

### Resolved in this brainstorm
4. **Plan slicing** — M3 is delivered as a **foundation plan (M3-0) + four
   sequential feature sub-plans (M3a–M3d)**, each its own branch off `main`,
   its own review checkpoint, its own merge. Lower risk for the live OHM
   deployment than one long-running branch.
5. **Branding cutover** — **hard cut + loud failure.** Frontend reads the
   deployment/project name only from `GET /api/deployment`; `VITE_APP_NAME`
   is removed from the frontend; `REGISTRY_REPO` becomes **required** at
   startup (per CLAUDE.md's loud-failure rule).
6. **Registry mirror mechanism** — follow the **existing §4.1 cache pattern**
   (`Reconciler.sweep()` + webhook writer, reading via the Gitea API), not a
   new mechanism (no local clone, no separate service).
7. **Test strategy** — adopt the handbook's **§10.3 two-tier testing**
   standard. Build the **Tier-1 local-Docker suite first** as M3-0; each
   feature sub-plan adds unit/integration/functional/e2e coverage on top.
   Tier-2 (PPE) is a separate flotilla/Stage-2 task (below).
8. **Deployment stage** — OHM is **Stage 1** (pre-v1, single prod VM,
   forward-only migrations). So M3a's table-rebuild migration is allowed as
   **one forward-only migration**. The §10.2 expand/contract rule is recorded
   as a **future Stage-2 obligation**, not a constraint on M3a today.

## Decomposition

Order is dependency-driven: **M3-0 → M3a → M3b → M3c → M3d.**

### M3-0 — Test & local-env foundation (the §10.3 Tier-1 suite)
Greenfield; lands before feature work so every sub-plan can be verified at
all levels. Reuses the existing in-process `app_with_fake_gitea` fixture seam
where possible.

- **Docker local stack** (`docker compose`): backend (FastAPI) + built
  frontend + **fresh SQLite** + **Mailpit** (mail sink for OTC/invite flows)
  + a disposable/stub Gitea for content **and** registry repos.
  - *Open design point for the M3-0 plan:* promote the in-process
    `fake_gitea` double into a small standalone HTTP stub vs. run real Gitea
    in a container. Decide in M3-0's own plan.
- **Frontend unit:** add **Vitest** + testing-library to
  `frontend/package.json` (none today).
- **E2E:** add **Playwright**, suite **environment-agnostic** —
  parameterized by `BASE_URL` + the **mail-sink API URL** (§10.3). Default
  target = localhost Docker; PPE host when `BASE_URL` is set to `ppe.<host>`.
  One smoke spec: load `/` directory → open a project → view an entry.
- **Tier-2 / PPE is NOT built here.** Standing up `rfc-app-ppe.<base>` (its
  own micro VM, own gcloud project, own isolated Gitea, always-pass Turnstile
  keys) is a **flotilla operator task** in the deployment tooling, tracked
  separately. The suite is written to point at it once it exists.

### M3a — Schema migration + default-id restamp *(foundation; runs against live OHM data)*
- **Migration `027`** (next number after `026`): create-copy-drop-rename for
  the 12 tables enumerated in the `026_projects.sql` header, folding
  `project_id` into each PK/UNIQUE key and adding the `project_id` FK →
  `projects(id)`. (`cached_prs` needs no rebuild — already globally unique.)
- Additive `type` + `initial_state` columns on `projects`.
- **Restamp** (§22.13 step 1): default project `id` `default` →
  config-derived slug, cascaded across every `project_id` FK. Idempotent.
- **Live-data safety (Stage 1):** back up prod SQLite; rehearse on a copy of
  prod; assert per-table row-count parity; FK enforcement on. Forward-only;
  brief restart blip acceptable per §9.
- *Gate: until this lands, a second project can collide with the first.*

### M3b — Registry mirror
- `REGISTRY_REPO` **required** at startup (loud failure if unset).
- `refresh_registry()` in `cache.py`: read `projects.yaml` from
  `REGISTRY_REPO` via the Gitea API; upsert `projects` rows (`id`, `name`,
  `content_repo`, `type`, `visibility`, `initial_state`,
  `enabled_models`/`theme` → `config_json`, `registry_sha`); cache deployment
  `name`/`tagline`. Rows never written from user actions.
- Webhook branch in `webhooks.py` on push to `REGISTRY_REPO`;
  `Reconciler.sweep()` calls `refresh_registry()`.

### M3c — Routing + redirects + runtime branding *(planner becomes navigable)*
- Backend: `GET /api/deployment` (name, tagline, visible projects per §22.5),
  `GET /api/projects/:id` (name, tagline, type, philosophy pointer, theme);
  `/p/<project>` scoping on RFC routes.
- Frontend: `/p/<project>/` prefix + `/e/<slug>` segment; **308 redirects**
  off old corpus-root URLs (`/rfc/<slug>` → `/p/<default-id>/e/<slug>`, etc.);
  **hard cut** off `VITE_APP_NAME` to runtime branding; per-project `theme`
  token overlay; deployment **directory** at `/`; project **switcher**.

### M3d — Landing-state + review behavior
- `initial_state=active` creation path: land a new entry `active`, stamp
  `unreviewed`, skip the graduate gate when the project says so.
- `unreviewed` frontmatter fields mirrored into `cached_rfcs`; owner/admin
  **mark-reviewed** action; §7 catalog **unreviewed filter** querying the
  cached column; type-driven entry noun in chrome.

## Test coverage per sub-plan (all four levels)

- **M3a** — migration unit/integration: fresh DB **and** copy-of-prod
  fixture; row-count parity; FK enforcement; restamp idempotence.
- **M3b** — reconciler unit (yaml parse, upsert, `registry_sha`) +
  integration (webhook → `projects` rows) on the Docker stub Gitea.
- **M3c** — backend functional (`/api/deployment`, `/api/projects/:id`, 308
  redirects, `/p` scoping) + frontend unit (branding/theme from API) + **e2e**
  (directory → project → entry nav; old-URL redirect resolves).
- **M3d** — backend functional (active landing, `unreviewed`, mark-reviewed,
  filter) + **e2e** (unreviewed filter, mark-reviewed action).

## Out of scope / dependencies

- **M4** (second-project acceptance pass), **M5** (`bdd` scenario/coverage
  surface — the planner's type-specific UI), **M6/M7**.
- **PPE standup** (`rfc-app-ppe.<base>`) — flotilla operator task; prerequisite
  to running the suite's Tier-2 gate, not framework code.
- **Org-wide testing-standard activation** — §10.3 already *is* the canonical
  standard; it should not be duplicated into per-repo memory. Recommended
  follow-up (separate, in the engineering repo + dev plugin): have
  `wgl-coding-session-init` read app.json and, for apps that deploy the §8
  standard stack, surface §10.3 + check whether the Tier-1 suite exists. Not
  part of M3.