Freeze — MUSEHUB-F7a: HTTP-coverage test spec for overseer-run provenance

Date: 2026-08-11 Step: MUSEHUB-F7a (freeze) → MUSEHUB-F7b (Auto build) Model: Thinking (this artifact) → Auto (F7b builds against it, no redesign) Repo: musehub (MUSE_HUB workspace) — regime muse-only, canonical Muse Authority: docs/MUSEHUB-OVERSEER-HANDOVER.md § "F7 correction"; proposal sha256:01e6a0d4… (changes requested); SD-14; staging deploy remains Tier 3

This document freezes WHAT F7b must assert and HOW it must assert it. It contains no implementation — no test body is written in this session.

Freeze-contract declaration

phase: musehub-f7a-http-coverage
outputs:
- id: f7-http-coverage-spec
  path: docs/reviews/2026-08-11-f7-http-coverage-freeze.md
  frozen: true
frozen_inputs: []
review_stamp:
  reviewed_at: '2026-08-11T20:39:13Z'
  verdict: pass
  reviewer_mode: agent
  reviewer_model: thinking-high
  reviewer_provider: local
  kit_version: 0.1.0
  artifact_digest: sha256:ecf635ee90e6ea4622232a0d414a3e5012056895b5c3b36b8384965ffdb5b420

Document conventions

Problem being frozen

Phase 9A-4 F7 implemented the enrichment endpoint plus six unit tests (tests/unit/test_overseer_provenance_f7.py, F7) on an unmerged Muse feature branch whose proposal has changes requested. F7 is not merged to dev, not deployed, and not live — tools/verify/check_consumer_contract.py:97-103 still carries the path as pending, and docs/MUSEHUB-OVERSEER-HANDOVER.md:198 records it as review-blocked. Every one of those six tests calls the service function directly, so no test crosses the HTTP boundary — the app's route table is unobserved by the suite. That gap is exactly what the reviewer identified, and it is valid.

The reviewer's proposed remedy — adding an explicit app.include_router(...) — is rejected on evidence (see next section). F7b closes the coverage gap and changes no registration.

Verified ground truth (do not re-derive in F7b)

Verified 2026-08-11 by running the app on feat/9a-4-f7-overseer-provenance (recorded in docs/MUSEHUB-OVERSEER-HANDOVER.md:35-52), plus the placement and lifespan facts verified in this session against the working tree:

Branch baseline for F7b (frozen)

The F7 route, service, settings field, and existing unit tests are absent from every other branch — they exist only on feat/9a-4-f7-overseer-provenance @ e5530c6…. F7b therefore has three steps, in this order, on a new feature branch cut from origin/dev (docs/MUSEHUB-OVERSEER-HANDOVER.md:111):

B1 and B2 must each land as their own Muse commit, separate from B3, and both commit refs must be recorded in docs/MUSEHUB-OVERSEER-HANDOVER.md in the closing governance sync. Without distinct commits there is no diff boundary, and exit criterion 2 becomes a judgment call instead of a mechanical check. The baseline for criterion 2 is the recorded B2 ref.

Verify tooling must travel with F7b

Verified this session by enumerating each branch's tree: tools/verify/ contains three files on feat/musehub-overseer-governance and zero on dev, on main, and on feat/9a-4-f7-overseer-provenance. A branch cut from origin/dev therefore has no verify tooling at all, so exit criterion 5 could not run, and the L1 checkpoints that guard the cross-repo /api contract would be absent from the very branch that touches it.

What the carried gates do and do not cover. Established empirically in review round 7 by adding a duplicate root-level include_router and re-running both gates:

The assertion set cannot cover uniqueness either: A1 exercises the /api path, which keeps returning 200 while a duplicate root mount exists.

Therefore, stated plainly: on the F7b branch there is no mechanical guard against the specific change the external reviewer requested. The only control is the frozen prohibition in § "Registration is NOT modified". Extending check_consumer_contract.py to gate registration uniqueness is real, worthwhile work — and it is out of scope for F7b, which may not edit a carried gate (see the prohibition table). It belongs in its own step.

What the carry does buy is that all three L1 checkpoints exist and run on this branch at all, which is a precondition for gating uniqueness later.

F7b carries all seven files, unmodified, as B2:

The wrappers are carried, not just the checkers, because _python_env.sh resolves MUSEHUB_VERIFY_PYTHON → .venv/bin/python → an importing python3 (scripts/verify/_python_env.sh:30-39). That is what makes exit criterion 5 robust rather than dependent on a bare python that is not on PATH in this environment.

Carrying F7 forward is not a registration change. It reproduces the already-reviewed F7 diff — including musehub/api/routes/musehub/overseer_provenance.py — byte-for-byte apart from the Settings conflict resolution. The prohibitions in the next section and exit criterion 2 are measured against the post-B2 baseline, not against dev: after B1 and B2, the F7b diff must add exactly one file and nothing else.

Registration is NOT modified — frozen prohibitions

F7b is a test-only change. The following are hard prohibitions; violating any of them fails build verification regardless of test results:

Frozen HOW — mechanism

Frozen WHAT — the four pinned assertions

Exactly four test cases. Each issues an anonymous GET (no Authorization header).

A1 — prefixed path returns 200 with the asserted envelope

Assert the response body against the serializer at musehub/services/musehub_overseer_provenance.py:69-84, 111-127 (F7):

All thirteen record values are pinned, so the expected record is a complete mapping that A2 can reuse verbatim. Ten values come from the seeded fixture at musehub/services/musehub_overseer_provenance.py:89-100 (F7); the remaining three — schema, contractVersion, and untrusted — are serializer constants injected at musehub/services/musehub_overseer_provenance.py:69-84 (F7) and are not fixture fields.

The envelope is asserted over HTTP, not by calling the service — that is the whole point of F7b. Two exactness requirements make content-freeness mechanically checkable rather than a judgment call:

• The top-level key set must equal exactly {schema, record}.
• The record key set must equal exactly these thirteen keys, matching musehub/services/musehub_overseer_provenance.py:69-84 (F7): schema, contractVersion, runRef, reviewTrayOutcomeRef, outcome, constitutionVersion, agentVersionRef, workerModelFamily, checkerModelFamily, externalRef, actorHash, producedAt, untrusted.

Equality — not "these two content keys are absent" — is what makes the assertion fail if any future change adds prompt text, completion text, or any other request/response body field to the wire.

A2 — percent-encoded ref returns 200 with a decoded ref

The request must be issued with the literal encoded segment flow_run%3Afixture-overseer-001 (this is the form the Scooling adapter sends). Assert 200 and that record.runRef equals the decoded flow_run:fixture-overseer-001. The decode happens in the ASGI layer before routing; F7b asserts the observable outcome and must not re-implement or bypass encoding.

A2 additionally carries the data-integrity burden, because the frozen definition order places it after A3's unknown-ref lookup. A2 must therefore assert the whole record — mapping equality against the complete expected record of A1, all thirteen keys and all thirteen values — not merely the run ref. This is what proves the miss in A3 neither evicted nor mutated store state. Value equality is required, not just a 200: the shape validator at musehub/services/musehub_overseer_provenance.py:47-66 (F7) does not inspect produced_at and only length-checks external_ref, so a mutation of those fields would still return 200 and would slip past a status-only check.

A3 — unknown ref returns 404

Use a ref that satisfies the ref pattern at musehub/services/musehub_overseer_provenance.py:18 (F7) but is absent from the store, so the assertion proves a store miss rather than a pattern rejection. Assert 404 — never 200, never 5xx.

A4 — posture off returns 404 (fail-closed)

With the posture set to disabled and the known-good fixture ref from A1, assert 404. Two further requirements:

• The status must be 404, not 403 and not 5xx — the gate at musehub/api/routes/musehub/overseer_provenance.py:16-18 (F7) hides existence rather than advertising a forbidden resource.
• The response body must not contain the record or any of its fields — no leakage of runRef, outcome, or actorHash when the posture is off.

Using the ref that A1 proves exists is essential: it distinguishes "the gate closed the door" from "the row was missing anyway".

Fail-closed rules (frozen)

Test matrix — seven-tier coverage

| Tier | Coverage for this slice | Where | | --- | --- | --- | | unit | Service logic: envelope shape, unknown ref, malformed ref, posture on/off, seed validation | Existing six tests, tests/unit/test_overseer_provenance_f7.py (F7) — unchanged by F7b | | integration | The gap this freeze closes — A1–A4 across the HTTP boundary through the real app route table, real router registration, and the real optional-auth dependency. Module reachability and /api-prefixed contract presence are covered alongside it by the gates carried in B2. Registration uniqueness is covered by nothing on this branch — neither the assertions nor the gates detect a duplicate root mount (§ "Verify tooling must travel with F7b"); it rests on a prohibition, and closing it is a named follow-up | New tests/unit/test_overseer_provenance_f7_http.py + tools/verify/check_consumer_contract.py:130-131 | | e2e | Live staging spot-check of the prefixed path after merge + deploy | Out of scope — Tier 3. Tracked in docs/MUSEHUB-OVERSEER-HANDOVER.md:169-175; must not be simulated or claimed by F7b | | stress | Not applicable and deliberately omitted: the handler is a read-only in-memory dictionary lookup with no I/O, no connection pool, and no shared mutable state. A loop over the same lookup would assert nothing about production load, whose real limits are the ASGI server and DB pool that this slice does not use | | data-integrity | A GET must not mutate the store: with the frozen definition order A1, A3, A2, A4, the unknown-ref lookup (A3) runs before A2's seeded-ref read, and A2 asserts the full record — exact key set plus every field value — so a miss that evicted or mutated state fails A2. Record-shape rejection is already covered by the seed-validation unit test | Definition-order row in the mechanism table; the full-record requirement in § A2 | | performance | No timing gate. The four cases run in-process with no DB and no network; the meaningful budget is that the whole new file stays in the sub-second range that tests/unit/ already exhibits (9 tests in 0.09 s, measured this session). F7b must not add a wall-clock assertion that would flake on loaded CI | | security | A4 proves fail-closed on posture off with no body leakage; anonymous access is exercised through the real optional-auth dependency (only the DB session is overridden, never the auth dependencies); no secrets, tokens, or credentials appear in the new file; no path-traversal surface — the ref is pattern-validated server-side | A4 + the override prohibitions above |

Every freeze-review finding on this artifact MUST cite file+line (SPEC §6).

Ground-truth edge

F7b (Auto) may treat this document as ground truth for the scoped work without re-deriving it: it must not re-litigate the registration question, re-measure the discovery ordering, or redesign the assertion set. Any disagreement with a frozen decision is a stop-and-report, not a redesign.

This is a side-check freeze under the Check OK path; it does not open a new docs.lanes baton.

Out of scope for F7b (named, not silently dropped)

Exit criteria for F7b (mechanical, no judgment)

1. Exactly one new authored file, tests/unit/test_overseer_provenance_f7_http.py, containing exactly the four cases A1–A4, defined in the frozen order A1, A3, A2, A4.
2. Measured as the diff between the recorded B2 commit ref and the F7b tip, the F7b diff adds exactly that one file and touches no file under musehub/api/routes/, no musehub/main.py, and no conftest.py — governance docs excepted.
3. With Postgres not running, both files pass: .venv/bin/python -m pytest tests/unit/test_overseer_provenance_f7_http.py tests/unit/test_overseer_provenance_f7.py -q
4. The six pre-existing F7 unit tests still pass unmodified.
5. All three carried gates exit 0, invoked through their wrappers so interpreter resolution is the tooling's own concern. The four scripts/verify/ files are mode 100644 in the Muse tree with no execute bit, so they must be invoked via bash — a bare scripts/verify/… path exits 126 (permission denied), which is not a pass: bash scripts/verify/verify_app_imports.sh, bash scripts/verify/verify_routes_registered.sh, bash scripts/verify/verify_consumer_contract.sh. Do not chmod +x them — the prohibition table forbids modifying a carried file, and criterion 6 pins mode as well as content. After B1 the consumer-contract gate must take its served-but-pending branch, printing the NOTE: … is now served but still marked pending line at tools/verify/check_consumer_contract.py:135-139 — not the PENDING: … not yet merged to dev line at :150, which is the pre-B1 output and does not satisfy this criterion. Exit 3 means no interpreter could import the app (scripts/verify/_python_env.sh:41-58) and is not a pass. Exit 2 means the app failed to import under the resolved interpreter (tools/verify/check_routes_registered.py:113-116, tools/verify/check_consumer_contract.py:113-116); because _python_env.sh:36-37 selects .venv/bin/python on the executable bit alone without applying the _verify_can_import guard it uses for the python3 fallback at :38, a stale .venv also produces exit 2. Confirm with ${PY} -c 'import musehub.main' before reporting exit 2 as a code defect.
6. The seven files carried in B2 are byte-identical to their feat/musehub-overseer-governance versions — verifiable by comparing each against muse cat --at feat/musehub-overseer-governance <path> — and unchanged in mode, which muse cat cannot show: confirm the four scripts/verify/ files are still 100644 via muse ls-tree -r feat/musehub-overseer-governance compared against the F7b tree. Content comparison alone would pass a chmod +x.
7. /build-verification-review reaches pass before any DONE claim — green tests alone are not sufficient.

Tier authority

Escalation categories that stop the review loop: security, irreversible, real_money, gates_tier3.

Review record