docs(tuner): control-plane app spec — consolidated delta over #285/#288 [draft]

[Nibbler1250]

What

Docs-only, draft: docs/tuner-control-plane-app-spec.md — the consolidated spec for the tuner control-plane app, written as a delta on top of #288 (docs/tuner-implementation-and-telemetry.md, which stays the authoritative core spec) and #285 (the control-surface RFC framing).

Why a draft PR

So the spec lives in the repo where it can be reviewed/extended incrementally, rather than in an issue thread. Pick it up whenever you have time — no urgency.

What it adds over #285/#288

• Surface inventory refreshed against everything merged since: watchdog/forensics ([WIP] feat(bus): stall watchdog for wedged PTY sessions — SPEC + detection core (PR 1/3, #296) #297/feat(bus): activate the stall watchdog — forensics + config + wiring (completes PR 1/3, #296) #300/fix(governance): implement watchdog kill escalation (#280) #298), agent-jobs (feat(bus): first-class agent-job primitive — dispatch_job (PR 3/3 of #296) #303), bash-exec guard (feat(hooks): block unsafe inline Bash backgrounding — PreToolUse guard (PR 2/3, #296) #302), kanban (feat(ui): live Kanban board of subagent activity (#294) #299), the tuner subject stack (feat(telemetry): host telemetry over MCP — read-only measurement surface (telemetry__*) [#275 brick 1] #286–feat(tuner): skills subject — reactive + proactive content-patch face [#275 subject 3/3, stacked on #287] #293), and the in-review pieces (feat(tuner): model_routing proactive evidence face [#275 subject 2/3, stacked on #287] #292 proactive reroute — now merged — and feat(plugins): eval-framework-mcp — offline LLM eval harness with 5 judge modes + cascade validation #80 eval framework).
• A dedicated MCP traffic panel (per-server volumes/error-rates/latency, per-tool breakdown, last-N calls, URL-addressable filters, drill-down sheet with chain badge + surrounding-call context, investigate-via-discuss-path design).
• 4 new panels beyond RFC: tuner observability + control surface for the app (commands, displays, visual git tracking) #285's seven: Watchdog/Forensics, Agent-jobs, Bench/Eval, Kanban — plus Config and Discussion pages (the latter is exactly docs(tuner): migration map + full implementation/telemetry reference [#275] #288 §6's discuss path extended into a chat page).
• A build-fast blueprint: stack decision (SvelteKit 5 + FastAPI + SQLite) and 1:1 component/pattern reuse mapping from a battle-tested internal ops dashboard of the same shape (feed, cards, role-gated mutations, live WS).
• /tuner/* API contract sketch and a 4-phase rollout that starts read-only (governance-first: provenance + git trail + safety visible before any mutating surface).

Refs #285, #288.

[TerrysPOV]

@claude /review

[claude]

Claude finished @TerrysPOV's task in 1m 48s —— View job

---

Reviewing PR #308

• Gather context (read diff, read new spec file, cross-checked against docs(tuner): migration map + full implementation/telemetry reference [#275] #288's canonical doc)
• Understand the request (docs review)
• Review content: consistency, accuracy, completeness
• Post review feedback

This is a docs-only draft (docs/tuner-control-plane-app-spec.md, +233), plus the required bump:plugin-version/bump:marketplace-version — both bumps are correctly applied (2.2.191 → 2.2.192 in both files). I cross-checked the telemetry/stream claims (mcp.tool_call, 11-stream contract 1.2.0) against docs/tuner-implementation-and-telemetry.md and they match. Overall a well-organized, clearly-labeled delta doc. Two content nits worth a follow-up commit before this comes out of draft:

1. Panel numbering is out of order and the count no longer matches the header
docs/tuner-control-plane-app-spec.md:82 says "the 7 from #285 + 4 new from recent PRs + 2 new asks", but the "operator asks" section actually lists three items: 12. Config (line 117), 13.5 MCP traffic (line 122), 13. Discussion / Chat (line 150) — that's 3, not 2. On top of the miscount, 13.5 is placed before 13 in the document (MCP traffic appears at line 122, Discussion at line 150), which reads oddly since the numbers imply the opposite order. Looks like the MCP traffic panel was slotted in with a 13.5 placeholder in a later commit without updating the intro count or reordering the section. Worth either renumbering sequentially (12 Config, 13 MCP traffic, 14 Discussion) or at minimum fixing the "2 new asks" → "3 new asks" and moving the MCP traffic block after Discussion so numbers read in order.
Fix this →

2. /tuner/mcp/traffic API contract doesn't cover the filters the panel promises
docs/tuner-control-plane-app-spec.md:189 sketches GET /tuner/mcp/traffic?server=&since=, but the "Interaction model" just above it (lines 133–135) promises composable filters on server, tool, agent, status, time window, and free-text search over error messages. Worth adding tool=, agent=, status=, q= to the contract sketch (or noting they're deferred) so the API section doesn't undersell the panel spec.

Minor: the PR description's "What it adds" bullet list (4 new panels + Config/Discussion) doesn't mention the MCP traffic panel, even though it's a fairly substantial addition (its own numbered panel + a full "Interaction model" subsection + a dedicated API line) added in the two later commits. Worth updating the PR body before merging so reviewers scanning just the description don't miss it.

No functional/build risk here since it's docs-only — nothing to test or run.

[Nibbler1250]

Doc review addressed: panels renumbered sequentially (12 Config / 13 MCP traffic / 14 Discussion), intro count fixed to three new asks, the /tuner/mcp/traffic contract now lists the full filter set from the interaction model (tool/agent/status/q), and the PR description now mentions the MCP traffic panel.

[TerrysPOV]

@claude /review

[claude]

Claude finished @TerrysPOV's task in 42s —— View job

---

Reviewing PR #308 (follow-up)

• Verify the two nits from the previous review were actually addressed
• Re-check consistency of the full doc after the fixes
• Post updated review

Both items from the previous review are cleanly fixed in 0bb4485:

1. Panel numbering — now sequential and matches the intro count: docs/tuner-control-plane-app-spec.md:82 correctly reads "3 new asks", and the panels are in order — 12. Config (line 117), 13. MCP traffic (line 122), 14. Discussion / Chat (line 150). Cross-references are consistent too (§12 at line 162, 13 at line 217, 10/11 at line 225). No stray 13.5 remnants anywhere in the doc.
2. /tuner/mcp/traffic contract — line 189 now lists the full filter set (server=&tool=&agent=&status=&since=&q=), matching the interaction model's promised filters (server, tool, agent, status, time window, free-text search).

The PR description was also updated to mention the MCP traffic panel, as suggested.

Version bumps (.claude-plugin/plugin.json, .claude-plugin/marketplace.json) remain correctly applied at 2.2.192, unchanged since the first pass.

No outstanding issues — this is in good shape to come out of draft whenever you're ready. Docs-only, so no build/test risk.