diff --git a/docs/superpowers/plans/2026-06-03-m3-backend-plan-a.md b/docs/superpowers/plans/2026-06-03-m3-backend-plan-a.md new file mode 100644 index 0000000..7b05ecb --- /dev/null +++ b/docs/superpowers/plans/2026-06-03-m3-backend-plan-a.md @@ -0,0 +1,1634 @@ +# M3-backend Plan A — registry mirror + runtime config + review semantics + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Make the framework learn its projects from a git registry (`REGISTRY_REPO`), expose deployment + project config at runtime (`GET /api/deployment`, `GET /api/projects/:id`), and carry the `initial_state`/`unreviewed` review semantics — all additively, operating on the single `default`-id project (no PK rebuild, no re-stamp, no writer threading; those are Plan B). + +**Architecture:** A self-contained `app/registry.py` mirrors `REGISTRY_REPO/projects.yaml` into the existing `projects` table + a new `deployment` singleton, driven by the existing webhook dispatcher and `Reconciler.sweep()` (Option A from the spec). `META_REPO` is retired (hard cut): the corpus mirror reads the default project's `content_repo` from the DB instead. Migration `027` is additive only. See spec: `docs/superpowers/specs/2026-06-03-m3-backend-design.md`. + +**Tech Stack:** Python 3 / FastAPI / SQLite (raw `sqlite3`), `pyyaml`, `pytest` + `httpx.MockTransport` (the `FakeGitea` harness). Tests run from `backend/` with `python -m pytest`. + +--- + +## Conventions for every task + +- Work on branch `m3-backend-registry-spine` (already checked out). +- Run tests from the `backend/` directory: `cd backend && python -m pytest`. +- The shared integration fixtures `tmp_env`, `app_with_fake_gitea`, `FakeGitea`, `sign_in_as`, `provision_user_row` live in `backend/tests/test_propose_vertical.py` and are imported by other test files (e.g. `from test_propose_vertical import app_with_fake_gitea, tmp_env # noqa: F401`). +- After Task 5, the whole suite must stay green; run `python -m pytest` (full suite) at the end of every subsequent task. + +--- + +## Task 1: Entry review fields (`unreviewed` / `reviewed_at` / `reviewed_by`) + +**Files:** +- Modify: `backend/app/entry.py` (dataclass ~29-53, `parse` ~56-85, `serialize` ~88-117) +- Test: `backend/tests/test_entry_review_fields.py` + +- [ ] **Step 1: Write the failing test** + +```python +# backend/tests/test_entry_review_fields.py +"""§22.4c — the unreviewed/reviewed_at/reviewed_by entry frontmatter fields.""" +from __future__ import annotations + +from app import entry as entry_mod + + +def test_parse_defaults_unreviewed_false_when_absent(): + text = "---\nslug: ohm\ntitle: OHM\nstate: active\n---\n\nBody.\n" + e = entry_mod.parse(text) + assert e.unreviewed is False + assert e.reviewed_at is None + assert e.reviewed_by is None + + +def test_parse_reads_review_fields(): + text = ( + "---\nslug: ohm\ntitle: OHM\nstate: active\n" + "unreviewed: true\nreviewed_at: '2026-06-03'\nreviewed_by: ben\n---\n\nBody.\n" + ) + e = entry_mod.parse(text) + assert e.unreviewed is True + assert e.reviewed_at == "2026-06-03" + assert e.reviewed_by == "ben" + + +def test_serialize_emits_review_fields_only_when_meaningful(): + # unreviewed False + no provenance → keys omitted (keeps document entries clean). + e = entry_mod.Entry(slug="a", title="A", state="super-draft") + assert "unreviewed" not in entry_mod.serialize(e) + assert "reviewed_at" not in entry_mod.serialize(e) + # unreviewed True → emitted. + e2 = entry_mod.Entry(slug="b", title="B", state="active", unreviewed=True) + assert "unreviewed: true" in entry_mod.serialize(e2) + + +def test_round_trip_preserves_review_fields(): + e = entry_mod.Entry( + slug="b", title="B", state="active", + unreviewed=False, reviewed_at="2026-06-03", reviewed_by="ben", + ) + back = entry_mod.parse(entry_mod.serialize(e)) + assert back.reviewed_at == "2026-06-03" + assert back.reviewed_by == "ben" + assert back.unreviewed is False +``` + +- [ ] **Step 2: Run test to verify it fails** + +Run: `cd backend && python -m pytest tests/test_entry_review_fields.py -v` +Expected: FAIL — `Entry.__init__() got an unexpected keyword argument 'unreviewed'`. + +- [ ] **Step 3: Add the dataclass fields** + +In `backend/app/entry.py`, add to the `Entry` dataclass (after `funder: str | None = None`, before `body: str = ""`): + +```python + # §22.4c: an `active` entry that landed without a human review gate + # carries unreviewed=True until an owner clears it. Orthogonal to + # `state`; only meaningful for active entries. reviewed_at/reviewed_by + # are the provenance of the clear, paralleling graduated_at/by. + unreviewed: bool = False + reviewed_at: str | None = None + reviewed_by: str | None = None +``` + +- [ ] **Step 4: Parse the fields** + +In `parse()`, add before the `return Entry(`: + +```python + unreviewed = bool(fm.get("unreviewed") or False) +``` + +and add these keyword args to the `Entry(...)` constructor call: + +```python + unreviewed=unreviewed, + reviewed_at=fm.get("reviewed_at") or None, + reviewed_by=fm.get("reviewed_by") or None, +``` + +- [ ] **Step 5: Serialize the fields** + +In `serialize()`, after the `funder` block (`if entry.funder:`), add: + +```python + # §22.4c: emit unreviewed only when True (a super-draft / reviewed + # active entry leaves the key absent → frontmatter stays minimal). + if entry.unreviewed: + fm["unreviewed"] = True + if entry.reviewed_at: + fm["reviewed_at"] = entry.reviewed_at + if entry.reviewed_by: + fm["reviewed_by"] = entry.reviewed_by +``` + +- [ ] **Step 6: Run tests to verify they pass** + +Run: `cd backend && python -m pytest tests/test_entry_review_fields.py -v` +Expected: PASS (4 tests). + +- [ ] **Step 7: Commit** + +```bash +git add backend/app/entry.py backend/tests/test_entry_review_fields.py +git commit -m "feat(entry): §22.4c unreviewed/reviewed_at/reviewed_by frontmatter fields" +``` + +--- + +## Task 2: Migration 027 — additive registry/review schema + +**Files:** +- Create: `backend/migrations/027_projects_runtime_config.sql` +- Test: `backend/tests/test_migration_027.py` + +- [ ] **Step 1: Write the failing test** + +```python +# backend/tests/test_migration_027.py +"""Migration 027 — additive §22 M3 schema (projects.type/initial_state, the +deployment singleton, cached_rfcs review columns). No table rebuilds in Plan A.""" +from __future__ import annotations + +import tempfile +from pathlib import Path + +from app import db +from app.config import Config + + +def _fresh_config() -> Config: + tmp = Path(tempfile.mkdtemp(prefix="mig027-")) / "t.db" + return Config( + gitea_url="x", gitea_bot_user="x", gitea_bot_token="x", gitea_org="x", + meta_repo="meta", registry_repo="registry", + oauth_client_id="x", oauth_client_secret="x", app_url="x", + secret_key="x", database_path=tmp, owner_gitea_login="x", + webhook_secret="x", + ) + + +def test_027_adds_project_type_and_initial_state(): + cfg = _fresh_config() + db.run_migrations(cfg) + conn = db.connect(cfg.database_path) + cols = {r["name"]: r for r in conn.execute("PRAGMA table_info(projects)")} + assert "type" in cols and cols["type"]["dflt_value"] == "'document'" + assert "initial_state" in cols and cols["initial_state"]["dflt_value"] == "'super-draft'" + conn.close() + + +def test_027_creates_deployment_singleton(): + cfg = _fresh_config() + db.run_migrations(cfg) + conn = db.connect(cfg.database_path) + rows = list(conn.execute("SELECT id FROM deployment")) + assert [r["id"] for r in rows] == [1] + # The CHECK (id = 1) forbids a second row. + try: + conn.execute("INSERT INTO deployment (id) VALUES (2)") + raised = False + except Exception: + raised = True + assert raised + conn.close() + + +def test_027_adds_review_columns_to_cached_rfcs(): + cfg = _fresh_config() + db.run_migrations(cfg) + conn = db.connect(cfg.database_path) + cols = {r["name"] for r in conn.execute("PRAGMA table_info(cached_rfcs)")} + assert {"unreviewed", "reviewed_at", "reviewed_by"} <= cols + conn.close() +``` + +- [ ] **Step 2: Run test to verify it fails** + +Run: `cd backend && python -m pytest tests/test_migration_027.py -v` +Expected: FAIL — `type` not in projects columns (migration doesn't exist yet). + +- [ ] **Step 3: Write the migration** + +```sql +-- backend/migrations/027_projects_runtime_config.sql +-- §22 M3 (Plan A) — additive registry/runtime-config schema. +-- +-- This is the additive half of M3's backend. It adds the project `type` and +-- `initial_state` columns (mirrored from the registry), the deployment +-- singleton (deployment name/tagline mirrored from the registry), and the +-- §22.4c review columns on cached_rfcs. NO table rebuilds: the §22.13 PK +-- rebuilds and the default->slug re-stamp ride a later migration (Plan B), +-- just before a second project can collide (see migration 026's DEFERRED +-- block and docs/superpowers/specs/2026-06-03-m3-backend-design.md §1/§6). + +ALTER TABLE projects ADD COLUMN type TEXT NOT NULL DEFAULT 'document' + CHECK (type IN ('document', 'specification', 'bdd')); +ALTER TABLE projects ADD COLUMN initial_state TEXT NOT NULL DEFAULT 'super-draft' + CHECK (initial_state IN ('super-draft', 'active')); + +-- Deployment-level identity (name, tagline) mirrored from the registry's +-- `deployment:` block. A singleton: the CHECK pins it to one row. +CREATE TABLE IF NOT EXISTS deployment ( + id INTEGER PRIMARY KEY CHECK (id = 1), + name TEXT, + tagline TEXT, + registry_sha TEXT, + updated_at TEXT NOT NULL DEFAULT (datetime('now')) +); +INSERT OR IGNORE INTO deployment (id) VALUES (1); + +-- §22.4c review flag + provenance. unreviewed is git-truth (mirrored from +-- entry frontmatter); it survives a cache rebuild like `state` does. +ALTER TABLE cached_rfcs ADD COLUMN unreviewed INTEGER NOT NULL DEFAULT 0; +ALTER TABLE cached_rfcs ADD COLUMN reviewed_at TEXT; +ALTER TABLE cached_rfcs ADD COLUMN reviewed_by TEXT; +``` + +- [ ] **Step 4: Run tests to verify they pass** + +Run: `cd backend && python -m pytest tests/test_migration_027.py -v` +Expected: PASS (3 tests). + +- [ ] **Step 5: Run the full suite (no regressions from the additive migration)** + +Run: `cd backend && python -m pytest -q` +Expected: PASS (the additive columns don't disturb existing queries). + +- [ ] **Step 6: Commit** + +```bash +git add backend/migrations/027_projects_runtime_config.sql backend/tests/test_migration_027.py +git commit -m "feat(db): migration 027 — additive §22 M3 schema (type/initial_state, deployment, review cols)" +``` + +--- + +## Task 3: Cache mirrors the review fields + +**Files:** +- Modify: `backend/app/cache.py` (`_upsert_cached_rfc` ~78-129) +- Test: `backend/tests/test_cache_review_fields.py` + +- [ ] **Step 1: Write the failing test** + +```python +# backend/tests/test_cache_review_fields.py +"""§22.4c — _upsert_cached_rfc mirrors the review fields into cached_rfcs.""" +from __future__ import annotations + +from fastapi.testclient import TestClient + +from test_propose_vertical import app_with_fake_gitea, tmp_env # noqa: F401 + + +def test_upsert_writes_review_fields(app_with_fake_gitea): + from app import cache, db, entry as entry_mod + + app, _ = app_with_fake_gitea + with TestClient(app): + e = entry_mod.Entry( + slug="rev", title="Rev", state="active", + unreviewed=True, reviewed_at="2026-06-03", reviewed_by="ben", + ) + cache._upsert_cached_rfc(e, body_sha="sha-rev") + row = db.conn().execute( + "SELECT unreviewed, reviewed_at, reviewed_by FROM cached_rfcs WHERE slug = 'rev'" + ).fetchone() + assert row["unreviewed"] == 1 + assert row["reviewed_at"] == "2026-06-03" + assert row["reviewed_by"] == "ben" +``` + +- [ ] **Step 2: Run test to verify it fails** + +Run: `cd backend && python -m pytest tests/test_cache_review_fields.py -v` +Expected: FAIL — the upsert doesn't write `unreviewed` (column stays default 0; `reviewed_at` stays NULL). + +- [ ] **Step 3: Extend `_upsert_cached_rfc`** + +In `backend/app/cache.py`, change the INSERT column list, the VALUES placeholders, the `ON CONFLICT(slug) DO UPDATE SET` clause, and the params tuple to include the three review fields. The edited statement: + +```python + db.conn().execute( + """ + INSERT INTO cached_rfcs + (slug, title, state, rfc_id, repo, proposed_by, proposed_at, + graduated_at, graduated_by, owners_json, arbiters_json, tags_json, + models_json, funder_login, body, body_sha, + unreviewed, reviewed_at, reviewed_by, + last_entry_commit_at, updated_at) + VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, datetime('now'), datetime('now')) + ON CONFLICT(slug) DO UPDATE SET + title = excluded.title, + state = excluded.state, + rfc_id = excluded.rfc_id, + repo = excluded.repo, + proposed_by = excluded.proposed_by, + proposed_at = excluded.proposed_at, + graduated_at = excluded.graduated_at, + graduated_by = excluded.graduated_by, + owners_json = excluded.owners_json, + arbiters_json = excluded.arbiters_json, + tags_json = excluded.tags_json, + models_json = excluded.models_json, + funder_login = excluded.funder_login, + body = excluded.body, + body_sha = excluded.body_sha, + unreviewed = excluded.unreviewed, + reviewed_at = excluded.reviewed_at, + reviewed_by = excluded.reviewed_by, + last_entry_commit_at = datetime('now'), + updated_at = datetime('now') + """, + ( + entry.slug, + entry.title, + entry.state, + entry.id, + entry.repo, + entry.proposed_by, + entry.proposed_at, + entry.graduated_at, + entry.graduated_by, + json.dumps(entry.owners), + json.dumps(entry.arbiters), + json.dumps(entry.tags), + models_json, + funder_login, + entry.body, + body_sha, + 1 if entry.unreviewed else 0, + entry.reviewed_at, + entry.reviewed_by, + ), + ) +``` + +- [ ] **Step 4: Run tests to verify they pass** + +Run: `cd backend && python -m pytest tests/test_cache_review_fields.py -q` +Expected: PASS. + +- [ ] **Step 5: Run the full suite** + +Run: `cd backend && python -m pytest -q` +Expected: PASS. + +- [ ] **Step 6: Commit** + +```bash +git add backend/app/cache.py backend/tests/test_cache_review_fields.py +git commit -m "feat(cache): mirror §22.4c review fields into cached_rfcs" +``` + +--- + +## Task 4: `app/registry.py` — the registry mirror module + +**Files:** +- Create: `backend/app/registry.py` +- Test: `backend/tests/test_registry.py` + +The module factors into pure functions (`parse_registry`, `apply_registry`) that are unit-testable without I/O, plus `refresh_registry` (the I/O orchestrator, integration-tested in Task 5). + +- [ ] **Step 1: Write the failing test** + +```python +# backend/tests/test_registry.py +"""§22.2 registry parse + apply: validation, type-immutability, upsert.""" +from __future__ import annotations + +import tempfile +from pathlib import Path + +import pytest + +from app import db, registry +from app.config import Config + + +def _db(): + cfg = Config( + gitea_url="x", gitea_bot_user="x", gitea_bot_token="x", gitea_org="x", + meta_repo="meta", registry_repo="registry", oauth_client_id="x", + oauth_client_secret="x", app_url="x", secret_key="x", + database_path=Path(tempfile.mkdtemp(prefix="reg-")) / "t.db", + owner_gitea_login="x", webhook_secret="x", + ) + db.run_migrations(cfg) + if db._CONN is not None: + db._CONN.close() + db._CONN = None + db.init(cfg) + return cfg + + +VALID = """ +deployment: + name: Open Human Model + tagline: A model of human flourishing +projects: + - id: default + name: Open Human Model + type: document + content_repo: meta + visibility: public +""" + + +def test_parse_valid_registry(): + doc = registry.parse_registry(VALID) + assert doc.deployment_name == "Open Human Model" + assert doc.deployment_tagline == "A model of human flourishing" + assert len(doc.projects) == 1 + p = doc.projects[0] + assert (p.id, p.type, p.content_repo, p.visibility) == ("default", "document", "meta", "public") + # initial_state defaults from type when omitted. + assert p.initial_state == "super-draft" + + +def test_parse_initial_state_defaults_per_type(): + doc = registry.parse_registry( + "projects:\n - {id: a, name: A, type: bdd, content_repo: a}\n" + ) + assert doc.projects[0].initial_state == "active" # bdd default + + +@pytest.mark.parametrize("bad,msg", [ + ("projects: []\n", "at least one"), + ("projects:\n - {id: 'Bad Slug', name: A, type: document, content_repo: a}\n", "valid slug"), + ("projects:\n - {id: a, name: A, type: nope, content_repo: a}\n", "invalid type"), + ("projects:\n - {id: a, name: A, type: document}\n", "content_repo"), + ("projects:\n - {id: a, name: A, type: document, content_repo: a, visibility: x}\n", "visibility"), + ("projects:\n - {id: a, name: A, type: document, content_repo: a}\n - {id: a, name: B, type: document, content_repo: b}\n", "duplicate"), +]) +def test_parse_rejects_invalid(bad, msg): + with pytest.raises(registry.RegistryError) as e: + registry.parse_registry(bad) + assert msg in str(e.value) + + +def test_apply_upserts_projects_and_deployment(): + _db() + doc = registry.parse_registry(VALID) + registry.apply_registry(doc, registry_sha="regsha1") + prow = db.conn().execute( + "SELECT name, type, content_repo, visibility, initial_state, registry_sha FROM projects WHERE id='default'" + ).fetchone() + assert prow["name"] == "Open Human Model" + assert prow["content_repo"] == "meta" + assert prow["registry_sha"] == "regsha1" + drow = db.conn().execute("SELECT name, tagline FROM deployment WHERE id=1").fetchone() + assert drow["name"] == "Open Human Model" + assert drow["tagline"] == "A model of human flourishing" + + +def test_apply_rejects_type_change_on_existing_project(): + _db() + registry.apply_registry(registry.parse_registry(VALID), "s1") + changed = VALID.replace("type: document", "type: specification") + registry.apply_registry(registry.parse_registry(changed), "s2") # logged + skipped, no raise + t = db.conn().execute("SELECT type FROM projects WHERE id='default'").fetchone()["type"] + assert t == "document" # immutable — unchanged +``` + +- [ ] **Step 2: Run test to verify it fails** + +Run: `cd backend && python -m pytest tests/test_registry.py -v` +Expected: FAIL — `ModuleNotFoundError: No module named 'app.registry'` (the M1 `projects.py` exists, but `registry.py` does not). + +- [ ] **Step 3: Write `app/registry.py`** + +```python +# backend/app/registry.py +"""§22.2 project registry mirror — the config-side analogue of +cache.refresh_meta_repo. + +A deployment declares its projects in a `projects.yaml` at the root of +REGISTRY_REPO. This module mirrors that file into the `projects` cache table +and the `deployment` singleton. Per §22.2, `projects` rows flow from the +registry only — never from user actions. The mirror runs on the registry-repo +webhook and on every reconciler sweep (Option A wiring, Task 5). +""" +from __future__ import annotations + +import base64 +import json +import logging +import re +from dataclasses import dataclass, field + +import yaml + +from . import db +from .config import Config +from .gitea import Gitea + +log = logging.getLogger(__name__) + +VALID_TYPES = {"document", "specification", "bdd"} +VALID_VISIBILITY = {"gated", "public", "unlisted"} +VALID_INITIAL_STATE = {"super-draft", "active"} +# §22.4b: per-type default landing state. +_TYPE_DEFAULT_INITIAL_STATE = { + "document": "super-draft", + "specification": "super-draft", + "bdd": "active", +} +_SLUG_RE = re.compile(r"^[a-z0-9][a-z0-9-]*$") + + +class RegistryError(Exception): + """A registry document that fails validation, or a missing registry file. + + Raised by parse_registry/refresh_registry. The caller decides severity: + fatal at startup (no last-good to serve), tolerated on a running deployment + (keep the last-good projects rows). See Task 5 wiring. + """ + + +@dataclass +class ProjectEntry: + id: str + name: str + type: str + content_repo: str + visibility: str + initial_state: str + config: dict = field(default_factory=dict) # theme, enabled_models + + +@dataclass +class RegistryDoc: + deployment_name: str + deployment_tagline: str + projects: list[ProjectEntry] + + +def parse_registry(text: str) -> RegistryDoc: + """Parse + validate projects.yaml. Pure (no I/O). Raises RegistryError.""" + raw = yaml.safe_load(text) or {} + dep = raw.get("deployment") or {} + projects_raw = raw.get("projects") or [] + if not isinstance(projects_raw, list) or not projects_raw: + raise RegistryError("registry must declare at least one project") + seen: set[str] = set() + entries: list[ProjectEntry] = [] + for p in projects_raw: + pid = str(p.get("id") or "").strip() + if not _SLUG_RE.match(pid): + raise RegistryError(f"project id {pid!r} is not a valid slug") + if pid in seen: + raise RegistryError(f"duplicate project id {pid!r}") + seen.add(pid) + name = str(p.get("name") or "").strip() + if not name: + raise RegistryError(f"project {pid!r} missing name") + ptype = str(p.get("type") or "").strip() + if ptype not in VALID_TYPES: + raise RegistryError(f"project {pid!r} has invalid type {ptype!r}") + content_repo = str(p.get("content_repo") or "").strip() + if not content_repo: + raise RegistryError(f"project {pid!r} missing content_repo") + vis = str(p.get("visibility") or "gated").strip() + if vis not in VALID_VISIBILITY: + raise RegistryError(f"project {pid!r} has invalid visibility {vis!r}") + initial_state = str( + p.get("initial_state") or _TYPE_DEFAULT_INITIAL_STATE[ptype] + ).strip() + if initial_state not in VALID_INITIAL_STATE: + raise RegistryError( + f"project {pid!r} has invalid initial_state {initial_state!r}" + ) + cfg: dict = {} + if p.get("theme") is not None: + cfg["theme"] = p["theme"] + if p.get("enabled_models") is not None: + cfg["enabled_models"] = [str(m) for m in p["enabled_models"]] + entries.append( + ProjectEntry(pid, name, ptype, content_repo, vis, initial_state, cfg) + ) + return RegistryDoc( + deployment_name=str(dep.get("name") or "").strip(), + deployment_tagline=str(dep.get("tagline") or "").strip(), + projects=entries, + ) + + +def apply_registry(doc: RegistryDoc, registry_sha: str) -> None: + """Upsert the parsed registry into projects + deployment. Idempotent. + + §22.4a: `type` is immutable — a change against an existing row is rejected + (skip + log), never applied. Projects absent from the registry are left in + place (archival is out of scope for M3; they simply stop refreshing). + """ + conn = db.conn() + for e in doc.projects: + existing = conn.execute( + "SELECT type FROM projects WHERE id = ?", (e.id,) + ).fetchone() + if existing is not None and existing["type"] not in (None, "", e.type): + log.error( + "registry: refusing immutable type change on project %s (%s -> %s)", + e.id, existing["type"], e.type, + ) + continue + conn.execute( + """ + INSERT INTO projects + (id, name, type, content_repo, visibility, initial_state, + config_json, registry_sha, updated_at) + VALUES (?, ?, ?, ?, ?, ?, ?, ?, datetime('now')) + ON CONFLICT(id) DO UPDATE SET + name = excluded.name, + type = excluded.type, + content_repo = excluded.content_repo, + visibility = excluded.visibility, + initial_state = excluded.initial_state, + config_json = excluded.config_json, + registry_sha = excluded.registry_sha, + updated_at = datetime('now') + """, + ( + e.id, e.name, e.type, e.content_repo, e.visibility, + e.initial_state, json.dumps(e.config), registry_sha, + ), + ) + conn.execute( + """ + UPDATE deployment + SET name = ?, tagline = ?, registry_sha = ?, updated_at = datetime('now') + WHERE id = 1 + """, + (doc.deployment_name, doc.deployment_tagline, registry_sha), + ) + + +async def refresh_registry(config: Config, gitea: Gitea) -> None: + """Mirror REGISTRY_REPO/projects.yaml into projects + deployment. + + Idempotent. Raises RegistryError on a missing/invalid file and GiteaError + on transport failure; the caller chooses fatal-vs-tolerated. + """ + item = await gitea.get_contents( + config.gitea_org, config.registry_repo, "projects.yaml", ref="main" + ) + if not item or item.get("type") != "file": + raise RegistryError( + f"{config.gitea_org}/{config.registry_repo}/projects.yaml not found" + ) + text = base64.b64decode(item["content"]).decode("utf-8") + sha = item.get("last_commit_sha") or item.get("sha") or "" + doc = parse_registry(text) + apply_registry(doc, sha) + log.info("registry: mirrored %d project(s) at %s", len(doc.projects), sha) +``` + +- [ ] **Step 4: Run tests to verify they pass** + +Run: `cd backend && python -m pytest tests/test_registry.py -v` +Expected: PASS (all parametrized cases + apply tests). + +- [ ] **Step 5: Commit** + +```bash +git add backend/app/registry.py backend/tests/test_registry.py +git commit -m "feat(registry): §22.2 projects.yaml parse/validate/apply module" +``` + +--- + +## Task 5: Hard cut — retire META_REPO, wire the registry mirror + +This is the integration task: it removes `META_REPO`, points the corpus mirror at the default project's `content_repo` from the DB, wires `refresh_registry` into startup + webhook + sweep, retires `seed_default_project`, and updates the shared test fixture to seed a registry (so every test's startup `refresh_registry` succeeds). It must land atomically — the suite is red between the config change and the fixture update. + +**Files:** +- Modify: `backend/app/config.py` +- Modify: `backend/app/projects.py` +- Modify: `backend/app/cache.py` (`refresh_meta_repo`/`refresh_meta_branches`/`refresh_meta_pulls`, `Reconciler.sweep`) +- Modify: `backend/app/webhooks.py` +- Modify: `backend/app/main.py` (lifespan) +- Modify: `backend/tests/test_propose_vertical.py` (`tmp_env`, `FakeGitea.__init__`) +- Modify: `backend/tests/test_multi_project_spine_vertical.py` (stale comment in one assertion) +- Test: `backend/tests/test_registry_wiring.py` + +- [ ] **Step 1: Write the failing test** + +```python +# backend/tests/test_registry_wiring.py +"""Startup mirrors the registry; the registry webhook re-mirrors it.""" +from __future__ import annotations + +from fastapi.testclient import TestClient + +from test_propose_vertical import app_with_fake_gitea, tmp_env # noqa: F401 + + +def test_startup_mirrors_registry_into_projects_and_deployment(app_with_fake_gitea): + from app import db + + app, _ = app_with_fake_gitea + with TestClient(app): + # The fixture's projects.yaml declares the default project + a name. + prow = db.conn().execute( + "SELECT content_repo, type, initial_state FROM projects WHERE id='default'" + ).fetchone() + assert prow["content_repo"] == "meta" # from the registry, not META_REPO + assert prow["type"] == "document" + drow = db.conn().execute("SELECT name FROM deployment WHERE id=1").fetchone() + assert drow["name"] # deployment name mirrored from the registry + + +def test_registry_webhook_remirrors(app_with_fake_gitea): + import hashlib + import hmac + import json as _json + + app, fake = app_with_fake_gitea + with TestClient(app) as client: + from app import db + # Edit projects.yaml in the fake registry repo: change the tagline. + new_yaml = ( + "deployment:\n name: OHM\n tagline: Edited tagline\n" + "projects:\n - id: default\n name: OHM\n type: document\n" + " content_repo: meta\n visibility: public\n" + ) + fake.files[("wiggleverse", "registry", "main", "projects.yaml")] = { + "content": new_yaml, "sha": "regsha2", + } + body = _json.dumps({"repository": {"full_name": "wiggleverse/registry"}}).encode() + secret = "test-webhook-secret-for-signature-verification" + sig = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest() + r = client.post( + "/api/webhooks/gitea", + content=body, + headers={"X-Gitea-Event": "push", "X-Gitea-Signature": sig, + "Content-Type": "application/json"}, + ) + assert r.status_code == 200 + tagline = db.conn().execute("SELECT tagline FROM deployment WHERE id=1").fetchone()["tagline"] + assert tagline == "Edited tagline" +``` + +- [ ] **Step 2: Run test to verify it fails** + +Run: `cd backend && python -m pytest tests/test_registry_wiring.py -v` +Expected: FAIL — startup does not mirror the registry yet (`type`/`deployment.name` empty), and the registry webhook branch doesn't exist. + +- [ ] **Step 3: Config — require REGISTRY_REPO, remove META_REPO, add DEFAULT_PROJECT_ID** + +In `backend/app/config.py`: + +Replace the `meta_repo: str` and `registry_repo: str` dataclass fields with: + +```python + registry_repo: str + default_project_id: str = "" +``` + +(Remove the `meta_repo` field entirely.) + +Replace the `meta_repo_full` property with: + +```python + @property + def registry_repo_full(self) -> str: + return f"{self.gitea_org}/{self.registry_repo}" +``` + +In `load_config()`, remove the `meta_repo=_optional("META_REPO", "meta"),` line and the multi-line comment above `registry_repo=`, and set: + +```python + registry_repo=_required("REGISTRY_REPO"), + default_project_id=_optional("DEFAULT_PROJECT_ID"), +``` + +> NOTE: The migration-027 test (`test_migration_027.py`) and `test_registry.py` construct `Config(...)` directly with `meta_repo="meta"`. Remove the `meta_repo="meta",` argument from those two test helpers' `Config(...)` calls, since the field no longer exists. + +- [ ] **Step 4: projects.py — default-project helpers; retire seed_default_project** + +In `backend/app/projects.py`, delete the `seed_default_project` function and replace the module body below `DEFAULT_PROJECT_ID = "default"` with these helpers: + +```python +def resolved_default_id(config: Config) -> str: + """The id of the deployment's bootstrap/default project. Plan A: always + 'default' (the re-stamp to a config slug rides Plan B). The config knob is + read here so Plan B can flip the resolution without touching call sites.""" + return config.default_project_id.strip() or DEFAULT_PROJECT_ID + + +def default_content_repo(config: Config) -> str | None: + """The content repo the single-corpus mirror reads, from the default + project's row (filled by the registry mirror). Replaces the retired + META_REPO. None until the registry mirror has run.""" + row = db.conn().execute( + "SELECT content_repo FROM projects WHERE id = ?", + (resolved_default_id(config),), + ).fetchone() + return row["content_repo"] if row and row["content_repo"] else None + + +def project_initial_state(project_id: str) -> str: + """§22.4b landing state for new entries in a project. Defaults to + 'super-draft' for an unknown/unset row (the safe, today's-flow default).""" + row = db.conn().execute( + "SELECT initial_state FROM projects WHERE id = ?", (project_id,) + ).fetchone() + if row is None or not row["initial_state"]: + return "super-draft" + return row["initial_state"] +``` + +- [ ] **Step 5: cache.py — corpus mirror reads content_repo from the DB; sweep mirrors the registry** + +In `backend/app/cache.py`, add to the imports at the top (the `from . import` line): + +```python +from . import db, entry as entry_mod, projects as projects_mod, registry as registry_mod +``` + +In `refresh_meta_repo`, replace `org, repo = config.gitea_org, config.meta_repo` with: + +```python + org = config.gitea_org + repo = projects_mod.default_content_repo(config) + if not repo: + log.warning("refresh_meta_repo: default project has no content_repo yet; skipping") + return +``` + +Apply the **same** two-line repo-resolution change at the top of `refresh_meta_branches` and `refresh_meta_pulls` (search for `config.meta_repo` in those functions and replace each occurrence; each should resolve `repo = projects_mod.default_content_repo(config)` and early-return if falsy). Run `grep -n "config.meta_repo" backend/app/cache.py` and confirm zero remain. + +In `Reconciler.sweep`, add the registry refresh as the first step inside the `try:` (before `refresh_meta_repo`), so the projects table is current before the corpus mirror reads `content_repo`: + +```python + try: + try: + await registry_mod.refresh_registry(self._config, self._gitea) + except Exception: + # Running deployment: a malformed registry PR must not take the + # sweep (or the deployment) down — keep the last-good rows. + log.exception("reconciler: registry refresh failed; keeping last-good projects") + await refresh_meta_repo(self._config, self._gitea) + ... +``` + +- [ ] **Step 6: webhooks.py — resolve repo from DB; add the registry branch** + +In `backend/app/webhooks.py`, change the import line `from . import cache, db` to: + +```python +from . import cache, db, projects as projects_mod, registry as registry_mod +``` + +Replace the dispatch block (the `repo_full = ...` through the `else:` slug branch) with: + +```python + repo_full = (payload.get("repository") or {}).get("full_name") or "" + registry_full = f"{config.gitea_org}/{config.registry_repo}" + meta_repo = projects_mod.default_content_repo(config) + meta_full = f"{config.gitea_org}/{meta_repo}" if meta_repo else None + try: + if repo_full == registry_full: + # §22.2: a registry-repo push re-mirrors the projects table. + try: + await registry_mod.refresh_registry(config, gitea) + except registry_mod.RegistryError: + # Tolerate a malformed registry PR on a running deployment. + log.exception("registry webhook: invalid projects.yaml; keeping last-good") + elif meta_full and (repo_full == meta_full or not repo_full): + await cache.refresh_meta_repo(config, gitea) + await cache.refresh_meta_branches(config, gitea) + await cache.refresh_meta_pulls(config, gitea) + else: + slug = _slug_for_repo(repo_full) + if slug: + await cache.refresh_rfc_repo(config, gitea, slug) + else: + log.info( + "webhook received for unknown repo: repo_full=%s event=%s " + "(no cached_rfcs row matched; hook may be on a fork or stale)", + repo_full, event, + ) + except Exception: + log.exception("webhook refresh failed") + raise HTTPException(status_code=500, detail="Refresh failed") +``` + +- [ ] **Step 7: main.py — drop seed_default_project; mirror the registry at startup (fatal on first boot)** + +In `backend/app/main.py` lifespan (`async def lifespan`), import `registry`: add `registry as registry_mod,` to the `from . import (...)` block. Then replace: + +```python + db.init(config) + projects.seed_default_project(config) # §22.13 step 1 + gitea = Gitea(config) +``` + +with: + +```python + db.init(config) + gitea = Gitea(config) + # §22.2: mirror the registry before anything reads projects/content_repo. + # First boot has no last-good rows, so a missing/invalid registry is fatal + # (loud-fail per separation-of-concerns); the reconciler sweep keeps it + # fresh thereafter and tolerates a later bad PR. + try: + await registry_mod.refresh_registry(config, gitea) + except Exception as e: + raise RuntimeError( + f"registry mirror failed at startup ({config.registry_repo_full}/projects.yaml): {e}" + ) from e + if projects.default_content_repo(config) is None: + raise RuntimeError( + f"registry does not describe the default project " + f"{projects.resolved_default_id(config)!r} (no content_repo). " + f"Add it to {config.registry_repo_full}/projects.yaml." + ) +``` + +Also update the startup log line near the end of lifespan — replace `config.gitea_org, config.meta_repo` with: + +```python + log.info("RFC app started — registry %s", config.registry_repo_full) +``` + +- [ ] **Step 8: Update the shared test fixture to seed a registry** + +In `backend/tests/test_propose_vertical.py`: + +In `FakeGitea.__init__`, after `self._seed_repo("wiggleverse", "meta")`, add: + +```python + # §22 M3: the deployment's project registry. Startup refresh_registry + # reads projects.yaml here; the single 'default' project's content_repo + # points back at the seeded meta repo so the corpus mirror is unchanged. + self._seed_repo("wiggleverse", "registry") + self.files[("wiggleverse", "registry", "main", "projects.yaml")] = { + "content": ( + "deployment:\n" + " name: Test Deployment\n" + " tagline: A test deployment\n" + "projects:\n" + " - id: default\n" + " name: Test Deployment\n" + " type: document\n" + " content_repo: meta\n" + " visibility: public\n" + ), + "sha": "regsha0001", + } +``` + +In the `tmp_env` fixture's `env` dict, add a registry repo name and drop the now-ignored META_REPO line. Change: + +```python + "META_REPO": "meta", +``` + +to: + +```python + "REGISTRY_REPO": "registry", +``` + +- [ ] **Step 9: Fix the one stale assertion comment** + +In `backend/tests/test_multi_project_spine_vertical.py`, the `test_default_project_seeded_and_backfilled` test still passes (content_repo is `"meta"`), but its inline comment references the retired META_REPO backfill. Update the comment on that assertion: + +```python + # M3: content_repo now comes from the registry mirror (projects.yaml), + # not the retired META_REPO startup backfill. + assert row["content_repo"] == "meta" +``` + +- [ ] **Step 10: Run the wiring test, then the full suite** + +Run: `cd backend && python -m pytest tests/test_registry_wiring.py -v` +Expected: PASS (2 tests). + +Run: `cd backend && grep -rn "config.meta_repo\|meta_repo_full\|seed_default_project" app/` +Expected: no output (all references removed). + +Run: `cd backend && python -m pytest -q` +Expected: PASS (full suite green — the fixture now seeds the registry, so every app-startup test mirrors it and the corpus mirror reads `content_repo='meta'` exactly as before). + +- [ ] **Step 11: Commit** + +```bash +git add backend/app/config.py backend/app/projects.py backend/app/cache.py \ + backend/app/webhooks.py backend/app/main.py backend/tests/test_propose_vertical.py \ + backend/tests/test_multi_project_spine_vertical.py backend/tests/test_registry_wiring.py \ + backend/tests/test_migration_027.py backend/tests/test_registry.py +git commit -m "feat(registry): hard-cut META_REPO -> REGISTRY_REPO; wire mirror into startup/webhook/sweep" +``` + +--- + +## Task 6: Runtime-config APIs — `GET /api/deployment` + `GET /api/projects/:id` + +**Files:** +- Create: `backend/app/api_deployment.py` +- Modify: `backend/app/api.py` (imports ~21-44; mount in `make_router` ~118-148) +- Test: `backend/tests/test_api_deployment.py` + +- [ ] **Step 1: Write the failing test** + +```python +# backend/tests/test_api_deployment.py +"""§22.9/§22.5 — GET /api/deployment + GET /api/projects/:id with visibility.""" +from __future__ import annotations + +from fastapi.testclient import TestClient + +from test_propose_vertical import ( # noqa: F401 + app_with_fake_gitea, tmp_env, provision_user_row, sign_in_as, +) + + +def _add_project(pid, name, vis, typ="document"): + from app import db + db.conn().execute( + "INSERT OR REPLACE INTO projects (id, name, type, content_repo, visibility, initial_state) " + "VALUES (?, ?, ?, ?, ?, 'super-draft')", + (pid, name, typ, pid, vis), + ) + + +def test_deployment_lists_public_omits_gated_and_unlisted_for_anon(app_with_fake_gitea): + app, _ = app_with_fake_gitea + with TestClient(app) as client: + _add_project("pub", "Public", "public") + _add_project("gat", "Gated", "gated") + _add_project("unl", "Unlisted", "unlisted") + r = client.get("/api/deployment") + assert r.status_code == 200 + body = r.json() + assert body["name"] == "Test Deployment" + ids = {p["id"] for p in body["projects"]} + assert "pub" in ids and "default" in ids # both public + assert "gat" not in ids # gated, anon not a member + assert "unl" not in ids # unlisted never enumerated + + +def test_projects_id_404_for_gated_non_member(app_with_fake_gitea): + app, _ = app_with_fake_gitea + with TestClient(app) as client: + _add_project("gat", "Gated", "gated") + assert client.get("/api/projects/gat").status_code == 404 + + +def test_projects_id_returns_config_for_public(app_with_fake_gitea): + app, _ = app_with_fake_gitea + with TestClient(app) as client: + from app import db + db.conn().execute( + "UPDATE projects SET config_json = ? WHERE id = 'default'", + ('{"theme": {"accent": "#5b5bd6"}}',), + ) + r = client.get("/api/projects/default") + assert r.status_code == 200 + body = r.json() + assert body["id"] == "default" + assert body["type"] == "document" + assert body["visibility"] == "public" + assert body["theme"] == {"accent": "#5b5bd6"} + + +def test_projects_id_unlisted_readable_by_direct_id(app_with_fake_gitea): + app, _ = app_with_fake_gitea + with TestClient(app) as client: + _add_project("unl", "Unlisted", "unlisted") + assert client.get("/api/projects/unl").status_code == 200 +``` + +- [ ] **Step 2: Run test to verify it fails** + +Run: `cd backend && python -m pytest tests/test_api_deployment.py -v` +Expected: FAIL — 404 for `/api/deployment` (route not mounted). + +- [ ] **Step 3: Write `app/api_deployment.py`** + +```python +# backend/app/api_deployment.py +"""§22.9 runtime deployment/project config (replaces VITE_APP_NAME). + +GET /api/deployment — the deployment name/tagline + the projects the caller can +see (§22.5: gated filtered by membership, unlisted omitted from enumeration). +GET /api/projects/:id — one project's runtime config + optional theme overlay, +gated behind the §22.5 read gate (404 for a non-member of a gated project). +""" +from __future__ import annotations + +import json +from typing import Any + +from fastapi import APIRouter, Request + +from . import auth, db + + +def make_router() -> APIRouter: + router = APIRouter() + + @router.get("/api/deployment") + async def get_deployment(request: Request) -> dict[str, Any]: + viewer = auth.current_user(request) + dep = db.conn().execute( + "SELECT name, tagline FROM deployment WHERE id = 1" + ).fetchone() + # §22.5: enumerate only public + (member-)gated; unlisted is never listed. + visible = set(auth.visible_project_ids(viewer)) + rows = db.conn().execute( + "SELECT id, name, type, visibility FROM projects " + "WHERE visibility != 'unlisted' ORDER BY name" + ).fetchall() + projects = [ + {"id": r["id"], "name": r["name"], "type": r["type"], "visibility": r["visibility"]} + for r in rows + if r["id"] in visible + ] + return { + "name": (dep["name"] if dep else "") or "", + "tagline": (dep["tagline"] if dep else "") or "", + "projects": projects, + } + + @router.get("/api/projects/{project_id}") + async def get_project(project_id: str, request: Request) -> dict[str, Any]: + viewer = auth.current_user(request) + # §22.5 read gate: a gated project 404s to a non-member (shape matches + # an unknown id). unlisted is readable by direct id. + auth.require_project_readable(viewer, project_id) + row = db.conn().execute( + "SELECT id, name, type, visibility, initial_state, config_json " + "FROM projects WHERE id = ?", + (project_id,), + ).fetchone() + if row is None: + auth.require_project_readable(viewer, project_id) # raises 404 + cfg = json.loads(row["config_json"] or "{}") + dep = db.conn().execute("SELECT tagline FROM deployment WHERE id = 1").fetchone() + return { + "id": row["id"], + "name": row["name"], + "tagline": (dep["tagline"] if dep else "") or "", + "type": row["type"], + "visibility": row["visibility"], + "initial_state": row["initial_state"], + "theme": cfg.get("theme") or {}, + } + + return router +``` + +> NOTE: `require_project_readable` (auth.py) returns `gated`→404 only when the row is missing OR the project is gated-and-not-member. For a truly unknown id, `project_visibility` returns `'gated'`, so a non-member gets 404 — the `row is None` guard then never reaches a real row. The redundant second `require_project_readable` call documents intent and is harmless. + +- [ ] **Step 4: Mount the router in `api.py`** + +In `backend/app/api.py`, add `api_deployment,` to the `from . import (...)` block (alphabetical, near `api_contributions`). Then in `make_router`, after the other `router.include_router(...)` calls (after `api_contributions`), add: + +```python + # §22.9 (M3): runtime deployment + per-project config (replaces VITE_APP_NAME). + router.include_router(api_deployment.make_router()) +``` + +- [ ] **Step 5: Run tests to verify they pass** + +Run: `cd backend && python -m pytest tests/test_api_deployment.py -v` +Expected: PASS (4 tests). + +- [ ] **Step 6: Run the full suite** + +Run: `cd backend && python -m pytest -q` +Expected: PASS. + +- [ ] **Step 7: Commit** + +```bash +git add backend/app/api_deployment.py backend/app/api.py backend/tests/test_api_deployment.py +git commit -m "feat(api): GET /api/deployment + /api/projects/:id (§22.9 runtime config)" +``` + +--- + +## Task 7: Honor `initial_state` at propose time + +**Files:** +- Modify: `backend/app/api.py` (the `propose_rfc` endpoint ~797-845) +- Test: `backend/tests/test_initial_state_landing.py` + +> SCOPE NOTE: Plan A sets the landed entry's `state`/`unreviewed` in frontmatter + cache per `initial_state`. The full active-entry lifecycle (skipping repo-creation/graduation for an active-landing project) is a `bdd`/type-surface concern deferred to M5; for `document` projects (the only live kind) `initial_state` is `super-draft`, so nothing changes in production. + +- [ ] **Step 1: Write the failing test** + +```python +# backend/tests/test_initial_state_landing.py +"""§22.4b — a project with initial_state='active' lands new entries active + +unreviewed; the default 'super-draft' project is unchanged.""" +from __future__ import annotations + +from fastapi.testclient import TestClient + +from test_propose_vertical import ( # noqa: F401 + app_with_fake_gitea, tmp_env, provision_user_row, sign_in_as, +) + + +def _propose(client): + return client.post("/api/rfcs/propose", json={ + "title": "Active Lander", "slug": "active-lander", + "pitch": "Lands active.", "tags": [], + }) + + +def test_super_draft_default_unchanged(app_with_fake_gitea): + from app import entry as entry_mod + app, fake = app_with_fake_gitea + with TestClient(app) as client: + provision_user_row(user_id=1, login="ben", role="owner") + sign_in_as(client, user_id=1, gitea_login="ben", display_name="Ben", role="owner") + assert _propose(client).status_code == 200 + f = fake.files[("wiggleverse", "meta", "propose/active-lander", "rfcs/active-lander.md")] + e = entry_mod.parse(f["content"]) + assert e.state == "super-draft" + assert e.unreviewed is False + + +def test_active_initial_state_lands_active_unreviewed(app_with_fake_gitea): + from app import db, entry as entry_mod + app, fake = app_with_fake_gitea + with TestClient(app) as client: + db.conn().execute("UPDATE projects SET initial_state='active' WHERE id='default'") + provision_user_row(user_id=1, login="ben", role="owner") + sign_in_as(client, user_id=1, gitea_login="ben", display_name="Ben", role="owner") + assert _propose(client).status_code == 200 + f = fake.files[("wiggleverse", "meta", "propose/active-lander", "rfcs/active-lander.md")] + e = entry_mod.parse(f["content"]) + assert e.state == "active" + assert e.unreviewed is True +``` + +> NOTE: the branch name `propose/active-lander` matches what `bot.open_idea_pr` creates (confirm the exact prefix by reading `bot.open_idea_pr`; if it differs, adjust the file-key in the test). The assertion target is the entry file the bot wrote to the proposal branch. + +- [ ] **Step 2: Run test to verify it fails** + +Run: `cd backend && python -m pytest tests/test_initial_state_landing.py -v` +Expected: FAIL — the active case lands `super-draft` (the endpoint hardcodes it). + +- [ ] **Step 3: Consult `initial_state` in `propose_rfc`** + +In `backend/app/api.py`, ensure `projects` is imported (add `projects as projects_mod,` to the `from . import (...)` block if absent). In `propose_rfc`, replace the `entry = entry_mod.Entry(` construction's `state="super-draft",` line. First, just before building the `entry`, add: + +```python + # §22.4b: the target project's landing state. Through Plan A every + # entry lands in the default project; M3-frontend routing carries a + # non-default target later. + target_project = auth.DEFAULT_PROJECT_ID + landing_state = "active" if projects_mod.project_initial_state(target_project) == "active" else "super-draft" +``` + +Then change the `Entry(...)` constructor: replace `state="super-draft",` with: + +```python + state=landing_state, + unreviewed=(landing_state == "active"), +``` + +- [ ] **Step 4: Run tests to verify they pass** + +Run: `cd backend && python -m pytest tests/test_initial_state_landing.py -v` +Expected: PASS (2 tests). + +- [ ] **Step 5: Run the full suite** + +Run: `cd backend && python -m pytest -q` +Expected: PASS. + +- [ ] **Step 6: Commit** + +```bash +git add backend/app/api.py backend/tests/test_initial_state_landing.py +git commit -m "feat(propose): honor project initial_state (§22.4b active landing + unreviewed)" +``` + +--- + +## Task 8: mark-reviewed action + catalog `unreviewed` filter + +**Files:** +- Modify: `backend/app/bot.py` (add a `mark_reviewed` write wrapper modeled on the graduation file-write) +- Modify: `backend/app/api.py` (the `list_rfcs` catalog endpoint ~609-665; add the mark-reviewed endpoint near the other RFC endpoints) +- Test: `backend/tests/test_mark_reviewed.py` + +> Before writing Step 3, read `backend/app/bot.py`'s `open_graduation_pr` (≈700-767) and `backend/app/api_graduation.py`'s `_orchestrate` (≈633-726) to copy the exact bot-write + inline-merge pattern (read file sha → update_file on a branch → open PR → wait_for_mergeable → merge → refresh cache). The mark-reviewed flow mirrors it: it rewrites the entry frontmatter with `unreviewed: false` + `reviewed_at`/`reviewed_by`, commits via the bot, merges, and refreshes `cached_rfcs`. + +- [ ] **Step 1: Write the failing test** + +```python +# backend/tests/test_mark_reviewed.py +"""§22.4c — owner/admin mark-reviewed clears the flag; catalog unreviewed filter.""" +from __future__ import annotations + +from fastapi.testclient import TestClient + +from test_propose_vertical import ( # noqa: F401 + app_with_fake_gitea, tmp_env, provision_user_row, sign_in_as, +) + + +def _seed_unreviewed_active(fake, slug="feat"): + """Put an active+unreviewed entry on the meta repo main + cache.""" + from app import cache, entry as entry_mod + body = entry_mod.serialize(entry_mod.Entry( + slug=slug, title="Feat", state="active", unreviewed=True, + owners=["ben"], proposed_by="ben", + )) + fake.files[("wiggleverse", "meta", "main", f"rfcs/{slug}.md")] = {"content": body, "sha": "s1"} + cache._upsert_cached_rfc(entry_mod.parse(body), body_sha="s1") + + +def test_catalog_unreviewed_filter(app_with_fake_gitea): + app, fake = app_with_fake_gitea + with TestClient(app) as client: + _seed_unreviewed_active(fake, "feat") + # a reviewed active entry should NOT appear under the filter + from app import cache, entry as entry_mod + ok = entry_mod.serialize(entry_mod.Entry(slug="ok", title="OK", state="active", owners=["ben"])) + fake.files[("wiggleverse", "meta", "main", "rfcs/ok.md")] = {"content": ok, "sha": "s2"} + cache._upsert_cached_rfc(entry_mod.parse(ok), body_sha="s2") + r = client.get("/api/rfcs", params={"unreviewed": "true"}) + slugs = {i["slug"] for i in r.json()["items"]} + assert slugs == {"feat"} + + +def test_mark_reviewed_clears_flag(app_with_fake_gitea): + from app import db + app, fake = app_with_fake_gitea + with TestClient(app) as client: + _seed_unreviewed_active(fake, "feat") + provision_user_row(user_id=1, login="ben", role="owner") + sign_in_as(client, user_id=1, gitea_login="ben", display_name="Ben", role="owner") + r = client.post("/api/projects/default/rfcs/feat/mark-reviewed") + assert r.status_code == 200 + row = db.conn().execute( + "SELECT unreviewed, reviewed_by FROM cached_rfcs WHERE slug='feat'" + ).fetchone() + assert row["unreviewed"] == 0 + assert row["reviewed_by"] == "ben" + + +def test_mark_reviewed_forbidden_for_non_superuser(app_with_fake_gitea): + app, fake = app_with_fake_gitea + with TestClient(app) as client: + _seed_unreviewed_active(fake, "feat") + provision_user_row(user_id=2, login="carol", role="contributor") + sign_in_as(client, user_id=2, gitea_login="carol", display_name="Carol", role="contributor") + r = client.post("/api/projects/default/rfcs/feat/mark-reviewed") + assert r.status_code == 403 +``` + +- [ ] **Step 2: Run test to verify it fails** + +Run: `cd backend && python -m pytest tests/test_mark_reviewed.py -v` +Expected: FAIL — `unreviewed` query param ignored (filter returns both); mark-reviewed route 404. + +- [ ] **Step 3: Add the catalog filter** + +In `backend/app/api.py` `list_rfcs`, change the signature to accept the query param and extend the WHERE clause. Replace the function signature line and the SQL: + +```python + @router.get("/api/rfcs") + async def list_rfcs(request: Request, unreviewed: str | None = None) -> dict[str, Any]: +``` + +and build the query with an optional `unreviewed` predicate: + +```python + placeholders = ",".join("?" for _ in visible) + params = list(visible) + unreviewed_clause = "" + if unreviewed is not None and unreviewed.lower() in ("1", "true", "yes"): + unreviewed_clause = " AND unreviewed = 1 AND state = 'active'" + rows = db.conn().execute( + f""" + SELECT slug, title, state, rfc_id, repo, + owners_json, arbiters_json, tags_json, + last_main_commit_at, last_entry_commit_at, updated_at + FROM cached_rfcs + WHERE state IN ('super-draft', 'active') + AND project_id IN ({placeholders}){unreviewed_clause} + ORDER BY COALESCE(last_main_commit_at, last_entry_commit_at) DESC + """, + params, + ).fetchall() +``` + +- [ ] **Step 4: Add the mark-reviewed endpoint** + +In `backend/app/api.py`, near `get_rfc` (~667), add (it uses the bot wrapper from Step 5): + +```python + @router.post("/api/projects/{project_id}/rfcs/{slug}/mark-reviewed") + async def mark_reviewed(project_id: str, slug: str, request: Request) -> dict[str, Any]: + """§22.4c — clear an active entry's `unreviewed` flag. Authority is the + §22.7 project superuser (project_admin or deployment owner/admin), the + same tier that graduates an entry.""" + viewer = auth.require_user(request) + auth.require_project_readable(viewer, project_id) + if not auth.is_project_superuser(viewer, project_id): + raise HTTPException(403, "Only a project owner/admin can mark an entry reviewed") + row = db.conn().execute( + "SELECT state, unreviewed FROM cached_rfcs WHERE slug = ? AND project_id = ?", + (slug, project_id), + ).fetchone() + if row is None: + raise HTTPException(404, "Not found") + if row["state"] != "active" or not row["unreviewed"]: + raise HTTPException(409, "Entry is not an unreviewed active entry") + try: + await bot.mark_entry_reviewed( + viewer.as_actor(), + org=config.gitea_org, + meta_repo=projects_mod.default_content_repo(config), + slug=slug, + reviewed_by=viewer.gitea_login, + reviewed_at=entry_mod.today(), + ) + except GiteaError as e: + raise HTTPException(502, f"Gitea: {e.detail}") + await cache.refresh_meta_repo(config, gitea) + return {"ok": True} +``` + +- [ ] **Step 5: Add the `bot.mark_entry_reviewed` wrapper** + +In `backend/app/bot.py`, add a method modeled on `open_graduation_pr` but writing directly to `main` via the same authenticated `update_file` path (mark-reviewed is an owner gesture and needs no review PR — it parallels the graduation *stamp*, not the graduation *flow*). Read the existing bot write helpers first to match the On-behalf-of trailer + actions-log shape. The method: + +```python + async def mark_entry_reviewed( + self, + actor, + *, + org: str, + meta_repo: str, + slug: str, + reviewed_by: str, + reviewed_at: str, + ) -> None: + """Clear §22.4c unreviewed on an active entry by rewriting its + frontmatter on main. Mirrors the graduation stamp's bot-write shape.""" + from . import entry as entry_mod + path = f"rfcs/{slug}.md" + result = await self._gitea.read_file(org, meta_repo, path, ref="main") + if result is None: + raise GiteaError(404, f"{path} not found") + text, sha = result + e = entry_mod.parse(text) + e.unreviewed = False + e.reviewed_at = reviewed_at + e.reviewed_by = reviewed_by + await self._update_file_on_behalf( + actor, + org=org, repo=meta_repo, path=path, + content=entry_mod.serialize(e), sha=sha, branch="main", + message=f"Mark {slug} reviewed", + ) +``` + +> NOTE: match the real helper names in `bot.py` — `self._gitea`, and the existing on-behalf write helper (it may be named differently than `_update_file_on_behalf`). Read `bot.py` first and use the actual private write method + actions-log call the other bot methods use, so mark-reviewed carries the same §6.5 trailer + actions row. + +- [ ] **Step 6: Run tests to verify they pass** + +Run: `cd backend && python -m pytest tests/test_mark_reviewed.py -v` +Expected: PASS (3 tests). + +- [ ] **Step 7: Run the full suite** + +Run: `cd backend && python -m pytest -q` +Expected: PASS. + +- [ ] **Step 8: Commit** + +```bash +git add backend/app/api.py backend/app/bot.py backend/tests/test_mark_reviewed.py +git commit -m "feat(review): mark-reviewed action + §7 catalog unreviewed filter (§22.4c)" +``` + +--- + +## Task 9: Release — env docs, changelog, version bump + +**Files:** +- Modify: `backend/.env.example` +- Modify: `CHANGELOG.md` +- Modify: `VERSION`, `frontend/package.json` + +- [ ] **Step 1: Update `backend/.env.example`** + +Add `REGISTRY_REPO` (required) and `DEFAULT_PROJECT_ID` (optional), and remove `META_REPO`. Insert near the other Gitea settings: + +```bash +# §22.2 — the project registry repo (REQUIRED). The framework reads +# `projects.yaml` at its root to learn which projects exist. The repo name is +# the deployment's choice; the app fails to start if this is unset. +REGISTRY_REPO=registry +# §22.13 — optional id for the bootstrap/default project. Reserved for the +# Plan B re-stamp; leave unset in Plan A (the default project id stays +# `default`). When set, it must match an `id` in projects.yaml. +# DEFAULT_PROJECT_ID=ohm +``` + +Delete the `META_REPO=...` line and its comment. + +- [ ] **Step 2: Run a grep to confirm no doc still tells operators to set META_REPO** + +Run: `cd backend && grep -rn "META_REPO" .env.example app/ ; echo "exit: $?"` +Expected: no matches in `.env.example` or `app/` (a match in a migration-026 comment is fine — it's historical). + +- [ ] **Step 3: Add the CHANGELOG entry with upgrade steps** + +In `CHANGELOG.md`, add a new top entry for `0.33.0` (a breaking, pre-1.0 minor). Match the file's existing entry format; the body must include an upgrade-steps block: + +```markdown +## 0.33.0 — §22 M3 (backend, Plan A): registry mirror + runtime config + +### Added +- Project **registry mirror** (`app/registry.py`): the framework now learns its + projects from `REGISTRY_REPO/projects.yaml`, mirrored into the `projects` + table + a new `deployment` singleton on the §4 webhook + reconciler. +- `GET /api/deployment` (name, tagline, visible projects) and + `GET /api/projects/:id` (name, type, visibility, initial_state, theme) — + runtime config replacing the build-time `VITE_APP_NAME` (frontend cut lands in + M3-frontend). +- `§22.4b initial_state` honored at propose time; `§22.4c unreviewed` flag, + mark-reviewed action (`POST /api/projects/:id/rfcs/:slug/mark-reviewed`), and a + `?unreviewed=true` catalog filter. +- Migration `027` (additive): `projects.type`/`initial_state`, the `deployment` + table, and `cached_rfcs.unreviewed`/`reviewed_at`/`reviewed_by`. + +### Breaking +- **`META_REPO` is retired; `REGISTRY_REPO` is required.** The corpus mirror now + reads each project's `content_repo` from the registry. + +### Upgrade steps +1. Create a registry repo under your deployment's Gitea org. +2. Author `projects.yaml` at its root: a `deployment:` block (`name`, `tagline`) + and one `projects:` entry for your existing corpus — `id: default`, `name`, + `type: document`, `content_repo: `, + `visibility: public`. (Keep `id: default` for this release; the pretty-slug + re-stamp lands in the next backend slice, before any `/p/` URL is public.) +3. Set `REGISTRY_REPO=` and remove `META_REPO`. +4. Add a Gitea webhook on the registry repo pointing at `/api/webhooks/gitea` + (same secret as the corpus webhook). +5. Deploy. Migration `027` runs; the registry mirror reconciles at startup. + Verify `GET /api/deployment` returns your project and `/api/health` is green. +``` + +- [ ] **Step 4: Bump the version** + +Set the version to `0.33.0` in both files (they must match per SPEC §20): + +```bash +printf '0.33.0\n' > VERSION +``` + +In `frontend/package.json`, change `"version": "0.32.0",` to `"version": "0.33.0",`. + +- [ ] **Step 5: Verify version match + full suite** + +Run: `cat VERSION && grep '"version"' frontend/package.json` +Expected: both show `0.33.0`. + +Run: `cd backend && python -m pytest -q` +Expected: PASS (full suite). + +- [ ] **Step 6: Commit** + +```bash +git add backend/.env.example CHANGELOG.md VERSION frontend/package.json +git commit -m "release: 0.33.0 — §22 M3 backend Plan A (registry mirror + runtime config)" +``` + +--- + +## Self-review checklist (completed by plan author) + +**Spec coverage (Plan A scope only):** +- Registry format + `registry.py` mirror (spec §2) → Task 4 + Task 5. +- `GET /api/deployment` + `/api/projects/:id` (spec §4) → Task 6. +- `initial_state` honoring (spec §5c) → Task 7. +- `unreviewed` parse/serialize (spec §5a) → Task 1; cache mirror (§5b) → Task 3; mark-reviewed (§5d) → Task 8; catalog filter query side (§5e) → Task 8. +- Migration `027` additive columns + deployment table (spec §1a/§1b) → Task 2. +- Config hard cut, META_REPO retirement (spec §3) → Task 5. +- Versioning + upgrade steps (spec §8) → Task 9. +- **Deferred to Plan B (per spec §1 decision 6):** the 12-table PK rebuilds (§1c), the `default`→slug re-stamp (§1d), `project_id` writer threading, two-project isolation tests. Not in this plan by design. + +**Placeholder scan:** No "TBD"/"add error handling"/"similar to" — every code step shows the code. Two explicit "read X first to match the real helper name" notes (Task 8 bot wrapper, Task 7 branch-name) are deliberate: they point at existing code the worker must mirror exactly rather than guessing a signature. + +**Type/name consistency:** `Entry.unreviewed/reviewed_at/reviewed_by` (Task 1) are read by `_upsert_cached_rfc` (Task 3), the registry's `ProjectEntry`/`RegistryDoc`/`RegistryError`/`parse_registry`/`apply_registry`/`refresh_registry` (Task 4) are consumed by the wiring (Task 5), `projects.default_content_repo`/`resolved_default_id`/`project_initial_state` (Task 5) are used by cache/webhooks/propose (Tasks 5/7) and mark-reviewed (Task 8). Names are consistent across tasks. diff --git a/docs/superpowers/specs/2026-06-03-m3-backend-design.md b/docs/superpowers/specs/2026-06-03-m3-backend-design.md index cf8e35a..c078c80 100644 --- a/docs/superpowers/specs/2026-06-03-m3-backend-design.md +++ b/docs/superpowers/specs/2026-06-03-m3-backend-design.md @@ -50,6 +50,27 @@ directory, the project switcher, the catalog's unreviewed-filter **UI**. 5. **Mirror structure** — a self-contained `app/registry.py` module (not folded into `cache.py`), driven by the existing webhook dispatcher + the existing `Reconciler.sweep()`. +6. **Two execution plans (found during planning).** The 12-table PK rebuild is + not self-contained: folding `project_id` into keys + FK forces every + `ON CONFLICT` upsert target to gain `project_id` (~10 sites across 6 modules) + and — because the rebuilt tables can no longer default `project_id` to a live + value once the default is re-stamped — forces **every RFC/branch writer** to + be threaded to supply the real `project_id`. That activation is larger and + riskier than the rest of M3-backend combined, and it is only required *before + a second project can collide* (i.e. right before M4). So M3-backend is split + into two plans at that seam: + - **Plan A (ships first):** registry mirror + the two APIs + `initial_state`/ + `unreviewed` semantics. Migration `027` is **additive only** (no rebuilds). + Operates entirely on the `default`-id project — no re-stamp, no rebuild, no + writer threading. `cached_rfcs` keeps its `slug` PK, so no upsert breakage. + - **Plan B (before M4 / before public `/p/` URLs):** the 12-table PK rebuild + (migration `028`), `project_id` threading through every writer, the + `default`→slug **re-stamp** (which rides here because it is only correct + once the rebuild's column-default fix + threading land), and two-project + isolation tests. + + The §1 sections below describe the **full** backend (both plans); §1c (the + rebuilds) and §1d (the re-stamp) are **Plan B**. Everything else is Plan A. --- @@ -89,11 +110,24 @@ CREATE TABLE IF NOT EXISTS deployment ( INSERT OR IGNORE INTO deployment (id) VALUES (1); ``` +> **Re-stamp split (correctness, found during planning).** The migration +> runner executes pure-SQL files and **cannot read `DEFAULT_PROJECT_ID` from the +> environment** — the same constraint that forced M1's `seed_default_project` +> into Python. So the re-stamp is **not** in the `.sql` file. Migration `027` +> (pure SQL) does §1a–§1c with `project_id` copied **verbatim** (`default` stays +> `default`); the rebuilt FKs are declared `ON UPDATE CASCADE ON DELETE +> CASCADE`. The re-stamp (§1d) is a **Python startup step** in `app/projects.py`, +> run after migrations and before the registry mirror, that issues a single +> `UPDATE projects SET id = ` (cascading to the 12 FK tables) plus a plain +> `UPDATE` of the 7 non-FK `project_id` tables. Idempotent: a no-op once no +> `default` row remains. + ### 1c. PK / uniqueness rebuilds (the 12 deferred tables) Per migration 026's deferred block, create-copy-drop-rename each table to fold `project_id` into the key and add `project_id … REFERENCES projects(id) ON -DELETE CASCADE`: +UPDATE CASCADE ON DELETE CASCADE` (the `ON UPDATE CASCADE` is what lets the +§1d Python re-stamp move all child rows with one parent UPDATE): | Table | Key change | | --- | --- | @@ -116,17 +150,22 @@ distinct per project) — **no rebuild**. The copy step writes `` in place of `default` for `project_id`, so these 12 tables are re-stamped for free (§1d). -### 1d. Re-stamp `default` → `` +### 1d. Re-stamp `default` → `` (Python startup step) -- `UPDATE projects SET id = '' WHERE id = 'default'` (only when `` ≠ - `default`). -- The 12 rebuilt tables: re-stamped during their copy (§1c). -- The remaining 7 tables that carry `project_id` but need no key change get a - plain rewrite: `UPDATE SET project_id = '' WHERE project_id = - 'default'` for `threads`, `changes`, `notifications`, `actions`, - `pr_resolution_branches`, `rfc_invitations`, `cached_prs`. +In `app/projects.py`, run at startup after `db.init` and before +`refresh_registry`. When `DEFAULT_PROJECT_ID` is set and a `default` project row +still exists, in one `db.tx()`: -End state: a single `project_id` value DB-wide. +- `UPDATE projects SET id = , updated_at = datetime('now') WHERE id = + 'default'` — cascades `project_id` across the 12 FK tables via `ON UPDATE + CASCADE`. +- For the 7 `project_id`-bearing tables with **no** FK (`threads`, `changes`, + `notifications`, `actions`, `pr_resolution_branches`, `rfc_invitations`, + `cached_prs`): `UPDATE SET project_id = WHERE project_id = + 'default'`. + +End state: a single `project_id` value DB-wide. Idempotent — a no-op once no +`default` row remains, so it is safe on every boot. ### 1e. Notes