Files

T

veronica f0d2dd9920 docs(W4): stamp kind and status front matter on 104 live documents

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`.

2026-08-20 19:30:25 -05:00

7.0 KiB

Raw Blame History

kind, status

kind	status
record	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:

Make routing consume the canonical ProviderHealthStatus enum, with healthy and degraded routable and down non-routable, at both routing decision sites.
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

Confirm exact base/branch and inspect every cited source/test anchor plus all direct CommandExecutorService construction sites.
Record baseline gateway and focused routing/commands/MCP test totals.
Add regression tests first and run focused tests to capture expected RED failures.
Apply only the typed routing helper/signature changes and required MCP module/constructor/guard changes; update impossible up fixtures.
Run focused tests, all user-required verification gates, lockfile/scope/diff checks, and record counts.
Obtain independent spec and code/security review; remediate any findings and repeat affected gates.
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.

7.0 KiB Raw Blame History

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