# MuseHub Overseer Handover

**Living relay for MuseHub enrichment + Knowtation-domain staging work** in the
MUSE_HUB workspace. Paste the **NEXT SESSION** block into a fresh chat.

**Not Scooling product order.** For Scooling product sequencing, use
`~/scooling/docs/OVERSEER-HANDOVER.md` (`ok workspace check-next`).

**Roadmap authority:** `docs/MUSEHUB-ROADMAP.md` (also under `musehub/docs/` when
committing in the musehub Muse tree).

---

<!-- overseer:next role=enrichment lane=product status=live -->
## NEXT SESSION — MUSEHUB-PROD-CLOSEOUT (PRIMARY)

**Date:** 2026-08-25  
**Model:** **Operator + Gabriel**  
**Constellation:** MuseHub is **enrichment** in `scooling-stack`. Production explore is
**live** (Gabriel). Scooling also queues **CODEX-HARNESS-a** (OpenAI Codex harness +
app-server — **not** codecs) in parallel.

### Production snapshot (Gabriel 2026-08-25 — operator-relayed)

| Item | Status |
| --- | --- |
| **Live URL** | [https://musehub.ai/explore](https://musehub.ai/explore) |
| **How it shipped** | Crane-copy staging-validated image → Production ECR; prod `.env` on instance; migrations; `/healthz` 200 inside instance; EIP check then DNS |
| **Deploy path** | Existing single push script (staging) now also drives prod builds |
| **AWS identity** | Org + Management account + MuseHub-Workforce + Google SAML/SCIM (3 users). See Scooling `docs/reviews/2026-08-22-musehub-aws-foundation-status.md` |
| **Still open** | Aaron Identity Center permission set + `IMAGE_TAG` deploy; Gabriel self-register; scooling unpack 502; mark AWS mail **Not spam** |
| **Users + repos (this session)** | `aaronrene` registered. knowtation `@700fafdd…` live. scooling listed, history unpack 502. Explore **2 repositories**. |
| **F7b** | Still BUILT not DONE — no `include_router`; not merged |

Scooling evidence: `~/scooling/docs/reviews/2026-08-25-musehub-production-live.md`.

### THE ONE NEXT STEP — **Model: Operator + Gabriel**

```text
MUSEHUB-PROD-CLOSEOUT remainder. Explore lists 2 repos (knowtation live;
scooling unpack 502). Get Aaron Identity Center permission sets + IMAGE_TAG
deploy via existing push.sh (no rebuild). Gabriel: muse auth register on
musehub.ai. Operator: mark AWS + aws-production@ / aws-nonproduction@ +
gabriel@ mail Not spam. Raise unpack-mpack origin timeout for scooling.

Do NOT: rebuild the prod image (crane copy already done); invent SOCIAL live;
mark F7b DONE without merge+deploy+spot-check+BV; apply include_router.
```

### Follow-on — F7b closeout (after Aaron can deploy)

Was PRIMARY 2026-08-11. Still required as a **software** row; no longer the infra blocker.

---

## NEXT SESSION — Gabriel re-review F7b → merge/deploy → spot-check (follow-on)

**Date:** 2026-08-11  
**Model:** **Operator** (Gabriel re-review / merge / deploy) then **thinking-high** (`/build-verification-review` before DONE)  
**Constellation:** MuseHub is **enrichment** in `scooling-stack`. Scooling product
PRIMARY is also MuseHub gate (see Scooling board) — this file owns MuseHub HOW.

### Assessment snapshot (verified 2026-08-11 — F7b build landed)

| Item | Evidence |
| --- | --- |
| **Staging `dev` tip** | `sha256:632c4ee4285e…` — Gabriel merge `feat/opengraph-repo-cards` (musehub#129) + `#168` scroll-lock fix in history |
| **F7b branch** | `feat/f7b-http-coverage` — tip `@ e2fffbbb…` (B3); **not DONE** until merge + deploy + live spot-check |
| **B1** | `sha256:417c976b…` — merge F7 onto `dev`; resolve `config.py::Settings` (field preserved: default `disabled`, alias `MUSEHUB_OVERSEER_PROVENANCE_ENRICHMENT`); OpenGraph kept |
| **B2 (diff baseline)** | `sha256:dae5f056…` — seven verify-tooling files verbatim from `feat/musehub-overseer-governance`, mode `100644` |
| **B3** | `sha256:e2fffbbb…` — only authored add vs B2: `tests/unit/test_overseer_provenance_f7_http.py` (A1, A3, A2, A4) |
| **Registration** | **unchanged** — no `include_router`, no edit to `api/routes/musehub/__init__.py` |
| **Tests (Postgres DOWN)** | `10 passed` — 4 HTTP + 6 pre-existing unit; pytest output sha256 `cd093819…` |
| **Gates** | `bash scripts/verify/{verify_app_imports,verify_routes_registered,verify_consumer_contract}.sh` all exit **0**; consumer prints **NOTE:** served-but-pending (not PENDING) |
| **OpenAPI** | exactly `GET /api/overseer-run-provenance/{run_ref}` (`operationId=getOverseerRunProvenance`) |
| **AWS Aaron deploy** | `AWS_PROFILE=musehub-infra` **missing** — Gabriel deploys after merge |
| **F7 proposal** | [sha256:01e6a0d4…](https://staging.musehub.ai/gabriel/musehub/proposals/sha256:01e6a0d4ca543a6a11eeeecd4fa9eca259c0d2ad625954b5465de30a30163c83) — evidence reply owed/posted after F7b; **do not** apply `include_router` |
| **KD-6b** | [issue #169](https://staging.musehub.ai/gabriel/musehub/issues/169) — fix on `feat/kd-6b`; still needs rebase onto `dev` after F7 path |
| **F7c uniqueness** | **QUEUED** — F7b does not gate duplicate root mounts |

### F7 correction — the requested `include_router` would break the endpoint

Verified by **running** the app on `feat/9a-4-f7-overseer-provenance`, not by reading it:

| Check | Result |
| --- | --- |
| `app.openapi()` paths matching `overseer` | exactly `GET /api/overseer-run-provenance/{run_ref}` — **already registered** |
| `include_router` for it in `main.py` | **none** — mounted by auto-discovery in `api/routes/musehub/__init__.py` (header: **DO NOT EDIT THIS FILE**) via `main.py:456` `prefix="/api"` |
| `TestClient` prefixed path | **200**, envelope `musehub.overseer_run_provenance_envelope/v0` |
| `TestClient` percent-encoded ref (`flow_run%3A…`, what Scooling sends) | **200**, `runRef` decoded |
| `TestClient` unknown ref | **404** |
| Wildcard ordering | already safe — sort key pins `repos` last: `overseer_provenance` index **17**, `repos` index **51** of 52 |
| Adding the explicit call | module is **not** in `_DIRECT_REGISTERED` → double-registers at root without `/api`, duplicate `operationId`s; `museHubRepoTransport.ts:481` requires `/api` and **throws** otherwise |
| `GET /overseer-run-provenance/…` (unprefixed) today | **422**, not 404 — the repo wildcard already claims that namespace |

**Real gap:** no F7 test crosses the HTTP boundary. Fix = add the test, change **no**
registration. The route needs `app.dependency_overrides[get_db]` because `optional_token`
pulls `get_db` in transitively; without it every request **500s**. No Postgres required.

### F7 proposal — reviewer's actual words + holding reply posted 2026-08-11

Gabriel's review (`changes_requested`, 2026-08-09) reasoned from **`rg overseer musehub/main.py`
returning zero matches**, concluding the router is never mounted. That grep is a false negative
by design: `api/routes/musehub/__init__.py:69-78` (F7) imports every sibling module with a
`router` into one aggregate, and `main.py:456` (F7) mounts that aggregate at `prefix="/api"`, so
no per-module mention appears in `main.py`. He also asked for the router to be moved to the
**root-level** fixed-path block — that is the double-registration + wrong-path failure.

His wildcard analysis **is** right for the unprefixed path (it is claimed by
`/{owner}/{repo_slug}`, returning 422), and his TestClient request **is** the correct remedy.

**Holding comment posted 2026-08-11** on proposal `sha256:01e6a0d4…` (`muse hub proposal
comment create`; verified present via `comment list` — 1 comment by `aaronrene`). It states the
registration evidence with branch-correct citations, asks him **not** to apply the
`include_router`, and commits to posting openapi + test evidence after F7b. F7b owes the
**evidence** reply, not a repeat of this one.

### F7a — spec frozen 2026-08-11 (freeze review `pass`)

**`docs/reviews/2026-08-11-f7-http-coverage-freeze.md`** (`frozen: true`, stamped
`verdict: pass`, digest `sha256:3631d0f7…`) is the authority for F7b. Do **not** redesign
against it; disagreement is a stop-and-report.

| Item | Frozen decision |
| --- | --- |
| Reviews | 5 rounds, 9 findings resolved (1 BLOCKER, 4 MAJOR, 4 MINOR), then `pass`; mechanical `ok check-ok` 0 findings |
| New file | `tests/unit/test_overseer_provenance_f7_http.py` — exactly four cases, defined in order **A1, A3, A2, A4** |
| Why `tests/unit/` | `tests/unit/conftest.py:15-18` no-ops the session-scoped autouse Postgres fixture at `tests/conftest.py:203-247`. Verified with Postgres down: `tests/unit/…` 9 passed in 0.09s; `tests/test_api_contracts.py` errors with connection refused on 5434 |
| Client | `TestClient(app)` **not** entered as a context manager — the lifespan at `musehub/main.py:138-152` calls `init_db()` and would need Postgres |
| Override | `app.dependency_overrides[get_db]` only; overriding the auth dependencies is **forbidden**. Pop the single key in teardown, never `.clear()` |
| Posture | `monkeypatch.setattr` on the settings attribute (not the env var); compile-time `OVERSEER_PROVENANCE_ENRICHMENT_AUTHORIZED` untouched |
| Branch shape | **B1** carry F7 commits + resolve `config.py::Settings`; **B2** carry the seven verify-tooling files verbatim; **B3** add the test file. B1 and B2 are each their **own** Muse commit (record both refs here). Exit criterion 2 is the **B2**→tip diff |
| Amended | **Rounds 6–8 after the first `pass`** — digest is now `sha256:ecf635ee…`. Round 7 caught that criterion 5 named `tools/verify/` scripts present on **no** branch F7b is cut from, so it was unexecutable; and that the artifact wrongly claimed those gates covered registration uniqueness. They do not: a duplicate root mount leaves both gates at exit 0 with identical digests. Tooling is now carried (B2) for the coverage it **does** provide; the uniqueness gap is recorded and named as follow-up |

### KD-6b — applied and verified 2026-08-11

Reviewer's diagnosis was exactly right. `Form(...)` is resolved at **import time**, so the
missing package took down the whole app, not just the vault.

| Check | Result |
| --- | --- |
| Before | `from musehub.main import app` → `RuntimeError: Form data requires "python-multipart" to be installed` |
| After | imports cleanly, **53 routes**, vault pages registered |
| Transitive? | no — `pip show python-multipart` → `Required-by:` empty, so it must be declared |
| Declared in | **both** `requirements.txt` and `pyproject.toml` (`>=0.0.32`) |
| `pytest --co` before | **0** collectable — `tests/conftest.py` imports the app, so collection failed repo-wide |
| `pytest --co` after | **7052** tests collect, **0** errors |
| `tests/test_kd6_vault_ui.py` | **22 passed, 1 skipped**, 1 failed only on a missing Playwright browser binary (`BrowserType.launch: Executable doesn't exist`) — environmental |

**Why two dependency files matter:** `Dockerfile:25,37` builds wheels from
`requirements.txt` (so the deployed container lacked it — that is the crash), while
`workflows/ci.yml:21` installs `pip install -e ".[dev]"` from `pyproject.toml`. Audited the
rest: otherwise identical apart from `muse` / `muse_contracts`, which are deliberately
bind-mounted.

**Why no gate caught it:** the tests were sufficient — 45 files import the app — but were
run in an environment that happened to have the package. And CI's install step **cannot
succeed on a clean runner**: `[dev]` requires `muse>=0.2.0` and `muse_contracts>=0.2.0`,
neither on PyPI (both bind-mounted in `docker-compose.override.yml`). The gate that would
have caught #169 is unable to run. `scripts/verify/verify_app_imports.sh` now covers this
locally.

### Local environment (this was the real blocker on reviewing either branch)

The compose stack **exists** — `musehub_postgres`, `musehub_minio`, `musehub_worker` and
friends are present, just stopped. Tests expect Postgres on `127.0.0.1:5434`, which is
exactly what compose maps.

```bash
docker compose up -d postgres        # gives tests the DB they expect on :5434
# Python: .venv must be 3.14 (pyproject requires >=3.14; 3.13 is rejected)
# muse_contracts is a dev extra NOT on PyPI — install base deps + pytest/httpx +
# factory-boy/pytest-asyncio/pytest-xdist, plus ~/MUSE_HUB/muse editable.
# Playwright E2E additionally needs: playwright install chromium
```

### Product order (cross-repo)

| | |
| --- | --- |
| **Scooling Apple chapter** | **CLOSED 2026-08-11** — APPLE-7-ship PARKED secondary |
| **Scooling PRIMARY** | MuseHub gate — prefer **code fixes** before waiting on Aaron AWS |
| **Knowtation** | Does not own F7/KD; F7 not required for Apple |

### THE ONE NEXT STEP — Gabriel re-review / merge / deploy (Operator)

```text
Step: MUSEHUB-F7b-CLOSEOUT — Re-review proposal #9; merge feat/f7b-http-coverage; deploy; spot-check
Model: Operator (Gabriel) then thinking-high for /build-verification-review before DONE
Repo: ~/MUSE_HUB/musehub
Branch: feat/f7b-http-coverage @ e2fffbbb…
Frozen spec: docs/reviews/2026-08-11-f7-http-coverage-freeze.md (digest sha256:ecf635ee…)
Proposal: sha256:01e6a0d4… — evidence reply posted (openapi + TestClient)

Do exactly:
1. Re-review proposal #9. Do NOT add include_router — registration is already
   correct via auto-discovery at /api/overseer-run-provenance/{run_ref}.
2. Merge feat/f7b-http-coverage → Muse staging dev (Tier 3).
3. Deploy staging (Aaron has no musehub-infra AWS profile).
4. Live spot-check GET /api/overseer-run-provenance/flow_run:fixture-overseer-001
   with posture enabled → 200 envelope.
5. Fresh thinking-high chat: /build-verification-review against the freeze
   BEFORE marking F7b DONE in MUSEHUB-ROADMAP.
6. Flip consumer-contract overseer template from pending → required only after
   merge to dev (tools/verify/check_consumer_contract.py:97-103).
7. Then KD-6b rebase onto current dev (#169).

Do NOT: mark F7 DONE without merge+deploy+spot-check+BV pass;
  apply include_router; touch KD-6b in the same tip before F7 lands;
  feature→GitHub-main; invent Aaron AWS pass.

Known gap remains F7c: registration uniqueness is ungated.
```

### After F7 review-fix — KD-6b multipart (#169)

```text
Step: MUSEHUB-KD-6B-REBASE — Rebase the applied multipart fix onto dev
Model: Auto
Repo: ~/MUSE_HUB/musehub
Prior: feat/kd-6b @ c04414e…; issue #169

Steps 2 and 4 below are DONE (2026-08-11) — see "KD-6b — applied and
verified" above. Do not redo them; verify and carry them forward.

Do exactly:
1. Rebase / merge feat/kd-6b onto current origin/dev. Our recorded count was
   27 conflicts (mostly main.py import symbols) — RE-CHECK, dev has moved.
2. DONE: python-multipart>=0.0.32 declared in requirements.txt AND
   pyproject.toml. Keep both; they feed Dockerfile and CI respectively.
3. Preserve the vault path-traversal + domain-gating behaviour through the
   conflict resolution — reviewer called it solid; do not lose it to a
   mechanical merge.
4. DONE: app imports (53 routes); pytest collects 7052 with 0 errors;
   tests/test_kd6_vault_ui.py 22 passed / 1 skipped. Re-run after rebase.
   For the Playwright case: playwright install chromium.
5. Push; Gabriel deploy (Aaron has no AWS profile); then KD-VERIFY-STAGING.

Do NOT: drop either dependency declaration; mark the Knowtation domain live
  before KD-VERIFY-STAGING spot-check; feature→GitHub-main.
```

### Parked until code lands

| Tip | Status |
| --- | --- |
| **F7 staging deploy (Aaron)** | AWS `musehub-infra` missing — Gabriel may deploy after merge |
| **KD-VERIFY-STAGING** | Needs KD-6b live after #169 fix |
| **Prod-readiness #149–#167** | Gabriel track — do not block F7/KD |

### Paste-ready — KD-VERIFY-STAGING (after live KD-6b deploy)

```bash
# A. Confirm live site serves KD-6b routes (browser)
# B. Re-push gabriel-muse auth fix if needed
# C. Push smoke vault via gabriel-muse PYTHONPATH only
# D. Optional remote attest — local verify still authoritative
```

Frozen CLI recipe: hub auth = `~/MUSE_HUB/muse`; vault ops =
`PYTHONPATH=~/MUSE_HUB/gabriel-muse` + gabriel-muse `.venv/bin/muse`.

---

## Done recently (MuseHub domain)

| Item | Status |
| --- | --- |
| **OpenGraph #129** | **DONE** on staging `dev` @ `632c4ee…` (Gabriel merge 2026-08-09) |
| **#168 scroll-lock** | **DONE** live on staging (Gabriel) |
| **KD-6b Muse history** | **DONE** @ `c04414e…` — not live until #169 + deploy |
| **F7 Muse history** | **BUILT on `feat/f7b-http-coverage`** @ `e2fffbbb…` (B1 `417c976b` / B2 `dae5f056` / B3) — **not DONE** until Gabriel merge+deploy+spot-check + thinking-high BV |
| **F7a spec freeze** | **DONE 2026-08-11** — `docs/reviews/2026-08-11-f7-http-coverage-freeze.md`, freeze review **`pass`** (amended digest `sha256:ecf635ee…`) |
| **Assessment closeout** | **DONE 2026-08-11** |

## Change log

- **2026-08-25** — **MUSEHUB-PROD-CLOSEOUT PARTIAL.** Agent-fetched explore **200** / healthz **200**. `aaronrene` registered on `musehub.ai`. knowtation `main` `@700fafdd…` live (1103 commits). scooling created + listed; unpack **502**. Explore **2 repositories**. Aaron Identity Center / deploy **blocked** (`aaron-admin` / `368456393936`). Mail Not spam unverified. F7b: no `include_router`; not merged. KD-6b not started.
- **2026-08-11** — **F7b Auto BUILT** on `feat/f7b-http-coverage` (not DONE). B1
  `417c976b…` Settings resolved; B2 `dae5f056…` seven verify files verbatim; B3
  `e2fffbbb…` HTTP TestClient A1/A3/A2/A4. Postgres-down: 10 passed. Three gates
  exit 0 with consumer **NOTE:** served-but-pending. Registration untouched.
  Evidence reply for proposal `sha256:01e6a0d4…`. NEXT = Gabriel re-review /
  merge / deploy / spot-check; thinking-high BV before roadmap DONE; F7c still queued.
- **2026-08-11** — **Holding reply posted on proposal `sha256:01e6a0d4…`.** Read Gabriel's
  actual review body (he grepped `main.py` for `overseer`; that is a false negative under
  aggregate auto-discovery). Reply accepts the HTTP-coverage point, refuses the
  `include_router` with branch-correct citations, and asks him to hold. Note: the
  `tools/verify/` gates are **not** on `dev` or `main` — only on
  `feat/musehub-overseer-governance` — so the reply cites a reproducible one-liner instead.
- **2026-08-11** — **F7a freeze AMENDED (rounds 6–8), digest `sha256:ecf635ee…`.** Fetching the
  paste prompt exposed that exit criterion 5 invoked `tools/verify/` scripts that exist on
  **only** `feat/musehub-overseer-governance` — 0 files on `dev`, `main`, and the F7 branch — so
  the criterion could not run on any branch F7b would be cut from. Five earlier review rounds
  missed it. Worse, the out-of-scope table used those absent scripts to justify not asserting
  registration uniqueness. Round 7 then disproved the fix's own premise: carrying the gates does
  **not** gate uniqueness — a duplicate root-level `include_router` leaves both gates at exit 0
  with byte-identical `ARTIFACT_SHA256` digests, since one is a presence test over three
  hardcoded templates and the other a reachability test, and FastAPI's duplicate `operationId`
  is a warning, not an exception. The tooling is still carried (B2) for the reachability and
  `/api`-presence coverage it genuinely provides; the uniqueness gap is now stated plainly in
  the spec and named as its own follow-up step. Also fixed: wrappers are mode `100644` and need
  `bash` (a bare path exits 126), and a stale `.venv` yields exit 2 that must not be misread as
  an app defect.
- **2026-08-11** — **F7a freeze DONE.** Froze the HTTP-coverage test spec in
  `docs/reviews/2026-08-11-f7-http-coverage-freeze.md` (`frozen: true`, stamped
  `pass`). Registration is explicitly **not** modified — verified in-session that
  `main.py` and `api/routes/musehub/__init__.py` contain no overseer reference on the
  F7 branch, so carrying F7 forward is not a registration change. Also verified that
  `tests/unit/` runs DB-free while `tests/` root does not, and that plain
  `TestClient(app)` skips the `init_db()` lifespan. NEXT = **F7b Auto**.
- **2026-08-11** — Assessment closeout. Staging `dev` @ `632c4ee…` (opengraph
  merged). Gabriel requested F7 `include_router` + TestClient; KD-6b blocked on
  `python-multipart` (#169). Aaron AWS still missing. NEXT = **F7 review-fix**
  on a new branch from `origin/dev`. Scooling Apple chapter CLOSED; product
  PRIMARY = MuseHub gate.
- **2026-07-31** — Prior dual-block (F7 AWS + KD-VERIFY Gabriel); product_order
  was SEC-KN-4c.
- **2026-07-10** — KD-STAGING Thinking freeze PARTIAL; NEXT was KD-VERIFY-STAGING.