veronica
f0d2dd9920
Applies the document contract from
docs/plans/2026-08-20_stack-docs-flatten-and-alignment.md section 3, partially:
`kind` and `status` only. `parent` is deliberately held until the flatten in
section 4 lands, so that 127 documents do not have to be re-pointed by hand
when docs/fleet/NORTH_STAR.yaml moves to docs/NORTH_STAR.yaml.
Scope, measured on origin/next at 63069149:
127 live docs = all *.md under docs/ minus docs/archive/ minus docs/_old_structure/
104 stamped here
19 held operator judgement (plan section 9), worklist in the same PR
3 held the SUPERSEDED TASKS.md stamps, which cite the moving path
1 untouched docs/fleet/FLEET-DOCTRINE.md, already stamped in W1
Kinds applied: 54 guide, 34 record, 9 spec, 6 tracking, 1 projection.
Every row carries a confidence and a one-line rationale in the worklist.
Two collisions with the existing state, both flagged rather than resolved:
1. docs/README.md:150-160 already documents a front-matter convention
(title/type/audience/status/source_of_truth) with its own allowed values.
It is applied to 4 of 127 files. Its `status` vocabulary is
current|draft|deprecated|historical; the new contract's is active|superseded-by.
The key collides. This commit lets the new contract win and rewrites
`status: current` to `status: active` on those 4 files, keeping their other
legacy keys untouched. No code reads any of them: `git grep source_of_truth`
outside docs/ returns nothing. docs/README.md still prescribes the old
convention and is an operator row, so it is not edited here.
2. Two of the plan's 20 operator rows are YAML files, not markdown
(docs/fleet/examples/roster-v2.yaml, docs/openapi-tess.yaml), and the
contract's front-matter form has no defined meaning for a .yaml document.
That gap also applies to docs/fleet/NORTH_STAR.yaml, the source of truth
itself. Raised in the worklist.
A third row from the plan, docs/fleet/north-star.md, no longer exists: W1
renamed it to docs/fleet/FLEET-DOCTRINE.md.
Verification: 104/104 parse with the expected kind and status in front matter;
the check was shown to reject a wrong kind before it was trusted. The diff
removes 4 lines total, all of them `status: current`.
105 lines
7.0 KiB
Markdown
105 lines
7.0 KiB
Markdown
---
|
|
kind: record
|
|
status: active
|
|
---
|
|
|
|
# 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.
|