# P3-R1 — Routing Health Enum + `/mcp` Wiring Scratchpad

**Task:** P3 hands-on acceptance blockers #1 and #5
**Mission:** `mvp-20260312` (active)
**Branch:** `feat/webui-p3r1-routing-mcp` from `origin/next`
**Required base:** `20718b5a273d243363a4f5cbef5bbf692a805bdb`
**Tracking ref:** Direct P3-R1 author brief; no provider issue supplied; no PR or merge authorized
**Started:** 2026-08-11T14:52:52-05:00

## Objective

Fix exactly two P3 acceptance blockers:

1. Make routing consume the canonical `ProviderHealthStatus` enum, with `healthy` and `degraded` routable and `down` non-routable, at both routing decision sites.
2. Wire `McpClientModule` into `CommandsModule`, make `McpClientService` required, remove the unreachable unavailable-service branch, and prove `/mcp status` reaches the client.

Explicitly excluded: provider registry/adapters, `provider.service.ts`, `agent.service.ts`, `chat.gateway.ts`, fallback membership, task classification, selector UI, conversation resume, reload UX, WS/origin/handshake behavior, dependencies/lockfile, and `apps/web/**` changes.

## Plan

1. Confirm exact base/branch and inspect every cited source/test anchor plus all direct `CommandExecutorService` construction sites.
2. Record baseline gateway and focused routing/commands/MCP test totals.
3. Add regression tests first and run focused tests to capture expected RED failures.
4. Apply only the typed routing helper/signature changes and required MCP module/constructor/guard changes; update impossible `up` fixtures.
5. Run focused tests, all user-required verification gates, lockfile/scope/diff checks, and record counts.
6. Obtain independent spec and code/security review; remediate any findings and repeat affected gates.
7. Commit conventionally, run the pre-push queue guard, and push only the feature branch (no PR or merge).

## Budget

No explicit token cap supplied. Working soft cap: **30K tokens**, based on two bounded gateway bug fixes, focused TDD, full gateway/root verification, independent review, and branch delivery. One coding worker will execute serially; reviews will be independent and serial to avoid worktree collisions.

## Startup Evidence

- `git fetch origin` rc=0.
- `origin/next` confirmed exactly `20718b5a273d243363a4f5cbef5bbf692a805bdb`.
- Local and remote `feat/webui-p3r1-routing-mcp` were absent before creation.
- Branch creation rc=0; HEAD equals the required base.
- Harness-owned `.mosaic/orchestrator/session.lock` was already dirty and remains excluded from staging/commit.

## Baseline Evidence

- Gateway full suite: rc=0; **64 files / 693 tests passed**, 7 files / 17 tests skipped (71 files / 710 tests total).
- Routing sub-suite (`src/agent/routing`): rc=0; **3 files / 105 tests passed**.
- Commands/MCP sub-suite (`src/commands`, `src/mcp-client`): rc=0; **6 files / 76 tests passed**.

## TDD and Implementation Evidence

- Routing RED: after canonical fixture/test changes but before the service fix, focused routing run returned rc=1 with **15 failed / 91 passed (106)** because the old `up`/`ok` gates rejected `healthy` and `degraded`.
- Routing GREEN: canonical `ProviderHealthStatus` map types, one `isRoutable` helper, and both comparison sites corrected; focused routing suite passed.
- MCP behavior test now drives `/mcp status` through a required mock client and asserts the client is called, success is returned for zero servers, and the former unavailable message is absent.
- MCP wiring mutation RED used the final `Reflect.getMetadata('imports', CommandsModule)` assertion with only the production `McpClientModule` import/registration temporarily removed: rc=1, exact failure `expected [GCModule, …] to include McpClientModule`.
- MCP wiring GREEN after byte-for-byte production restoration: rc=0. Temporary mutation did not remain.
- Every direct `new CommandExecutorService(...)` test construction now supplies a non-null MCP client mock.
- Initial Codex worker launch failed rc=1 from missing OpenAI bearer authentication. First Mosaic Claude launch failed rc=1 because Distrobox-local runtime contracts were absent; retry with the supported host `MOSAIC_HOME=/home/jwoltje/.config/mosaic` succeeded.

## Review Evidence

- Independent spec review: **approve**, 0 blockers, scope OK.
- Independent code/security review: **approve**, 0 blockers, 0 critical/high security findings. It suggested an actual module-wiring assertion, which was added with valid mutation RED/GREEN evidence.
- Independent final re-review after remediation: **approve**, 0 blockers, 0 critical/high security findings, no remaining findings.
- Optional missing-provider/`undefined` test suggestion was not adopted: the brief explicitly requires the three canonical statuses (`healthy`, `degraded`, `down`) and forbids scope expansion; runtime behavior for absent keys remains `undefined` → non-routable through the required helper signature.

## Documentation Assessment

- `docs/PRD.md` already requires provider fallback/routing and MCP capability; this increment restores implementation to those existing contracts.
- No public API endpoint, payload schema, auth/permission rule, navigation, deployment procedure, or new user workflow changes. OpenAPI, endpoint index, user/admin/developer guides, and sitemap are therefore N/A for this bounded repair.
- This append-only scratchpad is the implementation, TDD, review, and verification record. Canonical docs remain in-repo; no publishing action is in scope.

## Final Verification Evidence

All required and repository-situational gates completed with rc=0:

| Gate | Result |
| --- | --- |
| `pnpm install --frozen-lockfile` | rc=0 |
| Gateway typecheck | rc=0 |
| Gateway lint | rc=0 |
| Routing focused suite | rc=0; 3 files / 106 tests |
| Commands/MCP focused suite | rc=0; 6 files / 78 tests |
| Gateway full suite | rc=0; 64 files / 696 tests passed; 7 files / 17 tests skipped |
| Gateway build | rc=0 |
| Root typecheck | rc=0; 45/45 tasks |
| Web test | rc=0; 19 files / 154 tests |
| Root lint | rc=0; 25/25 tasks |
| Root format check | rc=0 |
| `git diff --check` | rc=0 |

- Gateway suite before→after: **693→696 passing tests**; skipped remained 17 (total 710→713).
- Routing focused before→after: **105→106 passing tests**.
- Commands/MCP focused before→after: **76→78 passing tests**.
- `pnpm-lock.yaml` SHA-256 before/after frozen install: `9acaa89d213b3281e757b6edf6fdb8727176570d725b78a0de234c61a7f3c332`; diff versus `origin/next` rc=0.
- Verified no changed path under `apps/web/**`, provider service/adapters, `agent.service.ts`, `chat.gateway.ts`, or lockfile.
- Verified both `McpClientModule` production wiring lines remain and no impossible `up`/`ok` routing status checks/fixtures remain.
- Verified code/test diff SHA-256: `27b41a855084b9dd85a7bc2a79fa3251d114ee226a4f1b835e65134c25a4f5a8`.

## Delivery State

Implementation, testing, documentation assessment, and independent review are complete. Remaining authorized actions: format this final scratchpad append, create one conventional commit, run the required push queue guard, and push only `feat/webui-p3r1-routing-mcp`; no PR or merge.