version: 1

epics:

# ── DONE ────────────────────────────────────────────────────────────────

- id: sandbox-isolation

title: Non-Docker sandbox isolation (Landlock)

status: done

priority: P1

mcp: MCP-34

depends_on: []

note: "Landlock LSM + setrlimit native sandbox for stdio upstreams; no userns (Ubuntu 24.04 safe). Originated from roadmap item #11 (no dedicated spec — 054 is the unrelated security-gateway spec). Code in internal/sandbox/; PRs #754/#759/#768/#781/#782."

tasks:

- id: sandbox-spike

title: Landlock sandbox spike (MCP-34.1)

status: done

mcp: MCP-3232

pr: "#754"

depends_on: []

- id: sandbox-mode-config

title: isolation.mode enum + resolver (MCP-34.2)

status: done

mcp: MCP-3233

pr: "#759"

depends_on: [sandbox-spike]

- id: sandbox-launcher

title: Native sandbox launcher Landlock+rlimits (MCP-34.3)

status: done

mcp: MCP-3234

pr: "#768"

depends_on: [sandbox-mode-config]

- id: sandbox-scanner-parity

title: Scanner-flow parity under sandbox (MCP-34.4)

status: done

mcp: MCP-3235

pr: "#781"

depends_on: [sandbox-launcher, scanner-v2]

- id: sandbox-snap-docker-it

title: snap-docker integration tests + CI (MCP-34.5)

status: done

mcp: MCP-3236

pr: "#782"

depends_on: [sandbox-scanner-parity]

- id: scanner-v2

title: Spec 076 deterministic offline tool-scanner

status: done

priority: P1

mcp: MCP-3574

spec: specs/076-deterministic-tool-scanner

depends_on: []

note: "Deterministic offline signal pipeline replaces ~10%-recall scanner; scan-eval --gate (recall>=0.90 / FP<=5%) in CI."

tasks:

- id: scanner-v2-foundation

title: detect-engine foundation (T1)

status: done

mcp: MCP-3575

pr: "#769"

depends_on: []

- id: scanner-v2-hard-checks

title: 3 hard checks + scanner wiring (US1 MVP)

status: done

mcp: MCP-3576

pr: "#770"

depends_on: [scanner-v2-foundation]

- id: scanner-v2-soft-checks

title: 3 soft checks + patterns confidence (US2)

status: done

mcp: MCP-3577

pr: "#775"

depends_on: [scanner-v2-foundation]

- id: scanner-v2-consensus

title: Consensus risk-score + report transparency (US4)

status: done

mcp: MCP-3578

pr: "#776"

depends_on: [scanner-v2-hard-checks, scanner-v2-soft-checks]

- id: scanner-v2-eval-gate

title: Eval corpus + CI recall/FP gate (US3)

status: done

mcp: MCP-3579

pr: "#777"

depends_on: [scanner-v2-hard-checks]

- id: scanner-v2-docs

title: Tool-scanner detect-engine docs (T22)

status: done

mcp: MCP-3683

pr: "#780"

depends_on: [scanner-v2-eval-gate]

# ── IN REVIEW ───────────────────────────────────────────────────────────

- id: windows-tray

title: Windows native tray app

status: in_review

priority: P2

mcp: MCP-43

depends_on: []

note: "No spec: link — this epic is the native TRAY app; specs/002-windows-installer is the unrelated INSTALLER spec (35/60) and its badge said nothing about tray progress (wrong link removed 2026-07-10). Option C: WebView2 window reusing shipped Web UI. Most exit criteria already ship; gaps = native window, toasts, profile submenu, Win11 smoke. Telemetry: Windows = ~23% of GitHub downloads but only ~4% of active installs (downloads→actives ~12:1 vs macOS ~4:1) — gate WebView2 work on finding the funnel break first."

tasks:

- id: windows-tray-funnel-qa

title: "Windows first-run QA pass (downloads→actives 12:1 vs macOS 4:1 — find the funnel break before WebView2 work)"

status: todo

priority: P2

depends_on: []

- id: windows-tray-window

title: WebView2 native window + profile submenu

status: in_review

mcp: MCP-43

depends_on: [windows-tray-funnel-qa]

# ── BACKLOG: personal-edition polish (NEW priorities) ─────────────────────

- id: ux-audit

title: Web UI + macOS app UX audit

status: todo

priority: P0

depends_on: []

note: "End-to-end UX pass across Web UI and the macOS tray app; the umbrella for the polish push. (No spec yet — 064 is the unrelated agent-fleet glass-cockpit spec.)"

tasks:

- id: ux-audit-webui-sweep

title: Web UI heuristic + Playwright UX sweep

status: todo

depends_on: []

- id: ux-audit-macos-sweep

title: macOS tray app UX sweep (settings parity, flows)

status: todo

spec: specs/037-macos-swift-tray

depends_on: []

- id: action-log-transparency

title: Action log / transparency — info at a glance

status: todo

priority: P1

depends_on: [ux-audit]

note: "Surface the most important activity/security/connection signals at a glance; reduce digging. Vision pillar 'feel control → transparency' — the activity log is a headline feature, polish it and bring it to the tray menu. Builds on the shipped activity-log backend + retention (spec 024, 95% shipped — this epic is the at-a-glance UX on top, not the backend, so 024 is not the progress driver)."

tasks:

- id: sessions-web-ui

title: "Sessions in the Web UI: meaningful session names in the Activity Log filter + the existing /sessions page linked in the sidebar"

status: done

priority: P1

note: "DONE 2026-07-11. Two-sided miss: Activity.vue already read a.metadata?.client_name, but the backend never wrote that field, so the Session filter always fell back to the id suffix ('...139c9'). Meanwhile the client name (MCP initialize clientInfo) has always existed on the session record and is already served by GET /api/v1/sessions. Fixed by joining the two at read time (activity rows already carry session_id as a foreign key) rather than denormalizing the name into the tool-call hot path. Also: a full Sessions.vue page + /sessions route already existed and were simply never linked in the personal-edition sidebar (only the Teams admin menu) — the fix was to unhide a page, not build one. New frontend/src/utils/sessionLabel.ts (+9 tests) handles display names and collision suffixes."

depends_on: []

- id: action-log-glance-view

title: At-a-glance action log view (top signals, health)

status: todo

note: "No spec: link on purpose — 019-activity-webui is the SHIPPED backend+table (72/73 after the 2026-07-10 truth-sync) and would paint this unbuilt UX task ~99% green."

depends_on: []

- id: action-log-tray-menu

title: Activity in the tray menu (recent tool calls + security events, jump to full log)

status: todo

priority: P1

note: "Both trays (Go/systray + Swift) via core REST/SSE only — tray holds no state (see tray-api-purity)."

depends_on: [action-log-glance-view]

- id: tray-menu-open-telemetry

title: "tray_menu_opened counter: Swift menuWillOpen (MCPProxyApp.swift:192) -> lightweight POST /api/v1/telemetry/tray-menu-opened -> registry counter -> heartbeat tray_menu_opened_24h"

status: todo

priority: P2

note: "Menu opens are invisible today: since Spec 048 menuWillOpen rebuilds from SSE state with zero REST calls, and surface_requests['tray'] counts header-stamped REST calls, not opens. Go tray excluded (fyne systray has no open event). Pure counter — passes payload_privacy_test rules. Gives the open-rate baseline for judging action-log-tray-menu."

depends_on: []

- id: action-log-retention-tie-in

title: Tie activity retention/size into the glance view

status: todo

note: "No spec: link on purpose — 073-activity-size-retention is the SHIPPED retention backend (13/14); this task is the glance-view tie-in on top of it."

depends_on: [action-log-glance-view]

- id: analytics-dashboard

title: Analytics dashboard as default page

status: in_progress

priority: P1

spec: specs/069-observability-usage-graphs

depends_on: [ux-audit]

note: "Per-server / per-tool token-drain graphs; make the dashboard the default landing page. 2026-07-10 truth-sync: spec 069 is SHIPPED (25/26 — the only open task is a Playwright verification sweep), so the graphs half is done; only the default-landing half remains."

tasks:

- id: analytics-token-drain-graphs

title: Per-server / per-tool token-drain graphs

status: done

spec: specs/069-observability-usage-graphs

note: "Shipped (spec 069 25/26; remaining task is a Playwright sweep, not a feature). Status corrected by the 2026-07-10 spec-vs-code truth-sync."

depends_on: []

- id: analytics-default-landing

title: Make dashboard the default landing page

status: todo

spec: specs/039-connect-and-dashboard

depends_on: [analytics-token-drain-graphs]

- id: registries-search-add

title: Registries — easier search + add-server

status: done

priority: P1

spec: specs/070-registry-easy-upstream-add

depends_on: []

note: "Lower the friction of finding a server in a registry and adding it; lean on the official registry protocol work. 2026-07-10 truth-sync: both children shipped — spec 070 is 21/24 (the 3 open tasks are pre-PR chores: worktree baseline, run gates, apply gate decisions) and 071 is 12/12. depends_on [ux-audit] dropped: a done epic cannot depend on a todo one."

tasks:

- id: registries-search-ux

title: Improved registry search UX

status: done

spec: specs/070-registry-easy-upstream-add

note: "Shipped (spec 070 21/24; remaining tasks are process chores, not features). Status corrected by the 2026-07-10 spec-vs-code truth-sync."

depends_on: []

- id: registries-official-protocol

title: Official registry protocol integration

status: done

spec: specs/071-official-registry-protocol

note: "Spec 071 shipped 12/12 (official MCP registry v0.1 protocol adopted, #572)."

depends_on: []

- id: scanner-simplification

title: Scanner simplification (deterministic default, opt-in deep scan)

status: done

priority: P1

spec: specs/077-scanner-simplification

depends_on: [scanner-v2]

note: "Make the Spec 076 detect engine the always-on offline default; demote Docker scanners + source extraction to opt-in deep scan that never blocks/degrades the baseline; single unified report. COMPLETE: US1 #786, US2 #792, US4 #794, US3 + deep-scan trust fixes + docs truth sweep (T037-T039) #793 — all merged; shipped in v0.47.0-rc.2. Remaining 4 unchecked tasks in tasks.md are documented scope-outs. First of the 5 personal-edition polish verticals."

tasks:

- id: scanner-simpl-baseline

title: "US1: deterministic offline baseline default + curated hard phrase_injection check (delete duplicate legacy rules)"

status: done

pr: "#786"

depends_on: []

- id: scanner-simpl-unified-report

title: "US2: single merged report + cross-scanner consensus confidence"

status: done

pr: "#792"

depends_on: [scanner-simpl-baseline]

- id: scanner-simpl-deep-optin

title: "US3: opt-in deep scan (off by default), never blocks/degrades baseline; config migration"

status: done

pr: "#793"

depends_on: [scanner-simpl-baseline, scanner-simpl-unified-report]

- id: scanner-simpl-notifications

title: "US4: collapse scan-notification storm into one debounced settled event (MCP-2207)"

status: done

pr: "#794"

depends_on: [scanner-simpl-unified-report]

- id: scanner-simpl-deepscan-fixes

title: "Deep-scan trust fixes: nil-Security gating bug (source fetch runs with deep scan off on default configs), FR-014 verdict inversion (Dangerous deep finding < Warning), surface silently-skipped Docker scanners (non-nil deep_scan descriptor + CLI hint on security enable)"

status: done

pr: "#793"

priority: P1

depends_on: [scanner-simpl-deep-optin]

- id: tpa-db

title: "tpa-db: versioned TPA signature database for the offline scanner"

status: todo

priority: P1

depends_on: [scanner-simplification]

note: "Vision pillar 'feel protected': the deterministic detect engine (Spec 076/077) ships with built-in checks but no updatable knowledge of in-the-wild Tool Poisoning Attacks. Build a versioned, offline-first signature/pattern database (known TPA campaigns, malicious phrase corpora, IoC hashes) that the engine consumes — bundled with the binary, refreshable out-of-band, community-contributable, and guarded by the existing scan-eval recall/FP CI gate."

tasks:

- id: tpa-db-format

title: "Signature DB format + loader (versioned, signed, bundled default)"

status: todo

depends_on: []

- id: tpa-db-corpus

title: "Seed corpus: catalog known public TPA campaigns/patterns into the DB"

status: todo

depends_on: [tpa-db-format]

- id: tpa-db-refresh

title: "Out-of-band refresh (offline-friendly: manual file drop + optional fetch), eval-gated"

status: todo

depends_on: [tpa-db-format]

- id: remote-access-tunnel

title: Remote access tunnel (feature-flagged MVP, spec 089)

status: todo

priority: P2

spec: specs/089-remote-access-tunnel

depends_on: [tpa-db, ux-audit, analytics-dashboard]

note: "One-button Web UI exposure of /mcp via external tunnel binary (cloudflared quick tunnel first) so Claude custom connectors (all tiers incl. Free, syncs to iOS/Android) can reach local MCP servers (e.g. Obsidian) — behind a feature flag, off by default, mandatory OAuth 2.1+PKCE+DCR gate, per-server exposure allowlist, remote-origin activity logging. Research: docs/research/remote-access-tunnel-research-2026-07-29.html (25/25 claims verified; niche unoccupied — Docker MCP Gateway lacks it). Sequenced after tpa-db (+ shipped scanner work 086-088), macOS tray redesign (ux-audit) and analytics-dashboard per owner decision 2026-07-29. No hosted relay/payments in MVP."

tasks:

- id: tunnel-oauth-gate

title: "OAuth 2.1 authorization-server gate for tunnel-origin traffic (PKCE, DCR, Anthropic callback allowlist, token lifecycle/revocation)"

status: todo

depends_on: []

- id: tunnel-orchestration

title: "cloudflared quick-tunnel orchestration (detect/launch/supervise/parse URL) + feature flag + never-auto-start"

status: todo

depends_on: []

- id: tunnel-exposure-allowlist

title: "Per-server exposure allowlist (default none; quarantined non-exposable; hot-reload)"

status: todo

depends_on: [tunnel-oauth-gate]

- id: tunnel-webui-tray

title: "Web UI open/close button + URL/QR/instructions + warning banner; tray active-state indicator; remote-origin activity marker"

status: todo

depends_on: [tunnel-orchestration, tunnel-exposure-allowlist]

# ── TELEMETRY-DRIVEN REPLAN (2026-07-02) ──────────────────────────────────

- id: upgrade-nudge

title: Upgrade awareness & guided update

status: done

priority: P0

spec: specs/079-upgrade-nudge

depends_on: []

note: "Corrected CI-filtered telemetry (2026-07-02): ~60% of last-14d active installs run pre-v0.40; latest stable v0.46.0 only 18.7%. Turn the existing internal/updatecheck background poll into a universal, non-intrusive, channel-aware upgrade nudge across every surface. Never blocks/modals; silent offline/CI."

tasks:

- id: upgrade-nudge-status-log

title: "US1 slice: update availability in mcpproxy status + deduped startup log"

status: done

pr: "#798"

depends_on: []

- id: upgrade-nudge-surfacing

title: "US1 remainder: dismissible Web UI banner + update_check config block"

status: done

pr: "#805"

depends_on: [upgrade-nudge-status-log]

- id: upgrade-nudge-channel

title: "US2: channel-aware guided update command (brew/dmg/deb/rpm/docker/go-install detection, build-time channel marker)"

status: done

pr: "#818"

note: "Install-channel detector (build marker + conservative heuristics; ambiguity->unknown), guided command only for brew/deb/rpm/go-install (generic fallback elsewhere, zero wrong-command risk), additive API fields (FR-021), status/doctor/banner surfaces; markers stamped in Docker + Windows-installer build paths only (single-binary matrix intentionally unstamped)."

depends_on: [upgrade-nudge-surfacing]

- id: upgrade-nudge-quiet

title: "US3: operator control + CI/offline quiet + no prerelease downgrade nudges"

status: done

pr: "#911"

depends_on: [upgrade-nudge-surfacing]

- id: connect-trust

title: "Connect step trust: preview, visible backup, one-click undo"

status: done

priority: P0

spec: specs/078-connect-trust-preview

depends_on: []

note: "Legacy wizard telemetry APPEARED to show 72.4% of engaged users skipping the connect step - debunked 2026-07-06: an instrumentation artifact, genuine never-connected skip = 0% (the wizard stamped skipped on users who connected via ConnectModal/CLI/manual config); real cliff is one-and-done installs ~48% (day-1 return 31%, identity-deduped 2026-07-10), see specs/080. Completers retain ~50% at two weeks vs 6% for non-engaged (correlation with engagement, not causation by the connect step). Backups already exist (internal/connect/backup.go) but are invisible in the Web UI. Close the trust gap: preview the exact config diff, surface the backup, offer one-click undo, explain the macOS TCC prompt."

tasks:

- id: connect-trust-preview

title: "US1: preview API + wizard diff UI (exact entry, API-key masking)"

status: done

pr: "#802"

depends_on: []

- id: connect-trust-backup-visibility

title: "US1: surface backup_path in Web UI + retention policy"

status: done

pr: "#799"

depends_on: []

- id: connect-trust-undo

title: "US2: one-click undo/disconnect in wizard"

status: done

pr: "#804"

depends_on: []

- id: connect-trust-tcc-copy

title: "US2: pre-emptive macOS TCC explanation in wizard"

status: done

pr: "#910"

depends_on: []

- id: telemetry-identity

title: "Telemetry identity & data quality (machine_id + CI-filter hardening)"

status: in_progress

priority: P1

depends_on: []

note: "2026-07-11 source audit: the CLIENT half is DONE and RELEASED — the old framing ('add a hashed machine_id (schema v6)') is stale. machine_id (HMAC-SHA256 of the OS machine id, internal/telemetry/machine_id.go) is emitted unconditionally in every heartbeat (telemetry.go:789; telemetry is opt-out) and shipped in v0.47.0; the client schema is already v7, a version past the v6 this note described; CI is filtered client-side by disabling telemetry outright (env_overrides.go). Worker verified live in prod 2026-07-07 (machine_id 100% populated). The audit also found that the 79%-unknown launch_source was a CLIENT bug misfiled to mcpproxy-dash — a dashboard cannot display a value the client is incapable of sending. That is now fixed (see telemetry-launchsource-tray). Remaining: dashboard consumption (mcpproxy-dash) + snapshot-cron alerting."

tasks:

- id: telemetry-machineid-client

title: "Hashed machine_id in heartbeat (schema v6)"

status: done

pr: "https://github.com/smart-mcp-proxy/mcpproxy-go/pull/796"

depends_on: []

- id: telemetry-machineid-worker

title: "Worker migration: machine_id column + extraction (repo mcpproxy-telemetry)"

status: done

pr: "mcpproxy-telemetry#3"

note: "Verified LIVE in prod 2026-07-07: remote D1 migration 0006 applied, worker deployed 2026-07-03 (right after 53811ed), v7 heartbeats populating machine_id 100% (64-char HMAC hex, distinct installs), vitest 129/129. No further worker work needed; dashboard consumption is the remaining child."

depends_on: [telemetry-machineid-client]

- id: telemetry-launchsource-tray

title: "Emit launch_source=tray — the 'tray' value was UNREACHABLE in the client, and that (not the dashboard) was the 79%-unknown root cause"

status: done

priority: P1

note: "FIXED 2026-07-11. Was: defaultHandshakeChecker.LaunchedViaTray() hardcoded `return false` and neither tray told the core it had spawned it, so a tray-spawned core (parent = the tray app, not launchd -> not login_item; no TTY -> not cli) fell through to 'unknown'. Now both trays (Swift CoreProcessManager.swift + Go buildCoreEnvironment) stamp MCPPROXY_LAUNCHED_BY=tray on the core they spawn, and DetectLaunchSource honours it. MCPPROXY_LAUNCHED_BY=installer still outranks it, so first-run attribution is unchanged; unrecognised values are ignored. NOTE for the dash: 'unknown' counts before/after this fix are NOT comparable — segment by version."

depends_on: []

- id: telemetry-machineid-dash

title: "Dashboard identityExpr prefers machine_id; exclude %-dev versions from human cohort (repo mcpproxy-dash)"

status: todo

note: "'fix launch_source 79% unknown' was REMOVED from this task on 2026-07-11 and moved to telemetry-launchsource-tray — it was a mcpproxy-go client bug, not a dashboard one."

depends_on: [telemetry-machineid-worker, telemetry-launchsource-tray]

- id: telemetry-snapshot-alerting

title: "Alerting on external-downloads snapshot cron (34-day outage went unnoticed)"

status: todo

depends_on: []

- id: release-qa-gate

title: "Release qualification gate (auto-QA matrix blocks the tag)"

status: in_progress

priority: P0

spec: specs/081-release-qa-gate

depends_on: []

note: "Attacks the return cliff (48% of installs are one-and-done; day-1 return 31% — corrected 2026-07-10, identity-deduped; the earlier '17.7% day-2' figure was un-deduped anonymous_id churn) and the one conceded competitor advantage: stability. No release tag until the surface x server-type matrix (MCP/REST/CLI/Web UI x stdio/http/sse/docker/oauth) plus invariants (activity-log/token counters move, quarantine flow, reconnect survival, in-place upgrade) pass automatically; macOS app smoke is advisory until promoted (3 consecutive passes, spec 081 US4). Assembles existing assets: test-api-e2e.sh, Playwright sweep, scan-eval gate, mcpproxy-ui-test."

tasks:

- id: release-qa-gate-matrix

title: "T1: tag-blocking release-gate workflow: server-type matrix (stdio/http/sse/docker/oauth) + invariants (activity-log/request-id, token+telemetry counters, quarantine flow, reconnect, upgrade-in-place), publish jobs gated on the verdict, scan-eval unconditional on tags"

status: done

pr: "#819"

priority: P0

note: "release-qa-gate.yml (reusable) gates all publish jobs in release.yml + prerelease.yml; cmd/mcpfixture (stdio/http/sse) + docker fixture image, cmd/release-gate driver (matrix+invariants+upgrade-in-place), internal/gatereport merger (no silent skips, reserved T2/T3/T4 not-run slots). Gate ran green end-to-end in CI. Found+fixed a real bug: POST /api/v1/servers dropped per-server isolation override. Deviations documented: FR-003 suite-race uses -short+-skip variant; FR-011 caller X-Request-Id not persisted on tool_call activity (driver correlates via nonce+core id)."

depends_on: []

- id: release-qa-gate-playwright

title: "T2: wire the Playwright Web UI sweep into the gate (currently manual-trigger only)"

status: todo

priority: P2

depends_on: [release-qa-gate-matrix]

- id: release-qa-gate-macos

title: "T3: macOS app smoke on a macos runner, advisory until 3 consecutive passes (today zero CI automation for the tray app)"

status: todo

priority: P3

depends_on: [release-qa-gate-matrix]

- id: release-qa-gate-consistency

title: "T4: surface-state consistency check (tray/Web UI/CLI agree with core on server states)"

status: todo

priority: P3

depends_on: [release-qa-gate-matrix]

- id: telemetry-v7-churn

title: "Telemetry v7: honest funnel + churn instrumentation"

status: in_progress

priority: P1

spec: specs/080-telemetry-v7-churn

depends_on: []

note: "2026-07-06 recheck DEBUNKED the 72.4% connect-skip story: genuine never-connected skip = 0% (wizard dismiss stamped 'skipped' on users who connected via ConnectModal/CLI/manual config). 2026-07-10 recheck debunked the OTHER two spec-080 headline metrics as well: 'day-2 return 17.7%' was un-deduped anonymous_id churn (true, identity-deduped: one-and-done 48%, day-1 return 31%, day-7 16.6% — matches dashboard); '42% retrieve_tools -> 16% real call' was lifetime-flag vs windowed-counter asymmetry (true conversion ~90%; missing piece is a first_real_tool_call_ever activation flag). Real cliff = 48% one-and-done. 2026-07-11 source audit + fix: ALL of spec 080 is shipped and released in v0.47.0 (#813) — T1 wizard completed_external, T2 funnel fields, T3 pre-churn snapshot, US4 schema v7. The previous note claimed 'only cross-repo churn analytics (T4) remains'; that was WRONG — first_real_tool_call_ever had ZERO occurrences in Go code and was in-repo CLIENT work. It is now implemented, so the retrieve->call funnel is finally measurable lifetime-vs-lifetime. P0->P1: only cross-repo T4 now remains."

tasks:

- id: telemetry-v7-wizard-fix

title: "T1: wizard metric fix - on dismiss record connect step as completed_external (not skipped) when the user already connected via another path"

status: done

pr: "#813"

depends_on: []

- id: telemetry-v7-funnel-fields

title: "T2: funnel observability fields (wizard_shown, web_ui_opened counter, days_since_install, active_days_30d)"

status: done

pr: "#813"

depends_on: []

- id: telemetry-v7-prechurn-snapshot

title: "T3: pre-churn snapshot (previous_shutdown clean|crash via BBolt flag, last_error_code) so the final heartbeat doubles as cause-of-death"

status: done

pr: "#813"

depends_on: []

- id: telemetry-v7-realcall-flag

title: "first_real_tool_call_ever activation flag (symmetric to first_retrieve_tools_call_ever) so the retrieve->call funnel step is measurable lifetime-vs-lifetime"

status: done

priority: P1

note: "Root cause of the debunked 42%->16% cliff: retrieve step had a lifetime BBolt flag, real-call step only windowed per-day counters. DONE 2026-07-11: activationKeyFirstRealToolCallEver + ActivationState.FirstRealToolCallEver + MarkFirstRealToolCall (internal/telemetry/activation.go), stamped from recordUpstreamTool (internal/server/mcp.go) — the shared entry point every call_tool_* variant already runs. Additive boolean in the activation bucket, no schema bump. Tested that retrieve_tools does NOT set it (builtin, not an upstream call)."

depends_on: []

- id: telemetry-v7-churn-events

title: "T4: cross-repo churn_events materialization + dash Churn page with H1-H4 hypothesis signatures (repos mcpproxy-telemetry / mcpproxy-dash; tracked here for DAG visibility, out of scope of spec 080)"

status: todo

depends_on: [telemetry-v7-wizard-fix, telemetry-v7-funnel-fields, telemetry-v7-prechurn-snapshot, telemetry-machineid-worker]

- id: tray-api-purity

title: "Tray↔core decoupling: socket/REST API only, no config-file reads"

status: done

priority: P2

depends_on: []

note: "Architecture rule (CLAUDE.md): the tray holds no state and talks to the core only via socket/REST + SSE. 2026-07-11 source-of-truth re-audit + fix: Swift tray was already clean (MCPProxyApp.swift opens the config in an external editor, never parses it); the Go tray's update-check gate was already reworked to core-API gating (#805). The last violation — config.LoadFromFile in the Go tray's OAuth login path, live since ff03db92 (2026-05-18, #477) — turned out to be FUNCTIONALLY DEAD: the loaded config fed only two debug log lines, while the actual trigger was already the core-API TriggerOAuthLogin. Deleted rather than ported to REST. Bootstrap reads (socket path, config PATH without parsing, CA cert) are allowed and remain. Now enforced by a test so the rule cannot silently rot."

tasks:

- id: tray-oauth-config-read

title: "Delete the dead config read in the Go tray OAuth path (config.LoadFromFile) + drop the now-unused internal/config import. GetConfigPath stays on the interface — openConfigDir still needs the path to reveal the dir in the file manager."

status: done

priority: P2

depends_on: []

- id: tray-config-import-guard

title: "Test guard (internal/tray/config_import_guard_test.go) failing any tray-side call to config.LoadFromFile/Load/SaveConfig/... Parses source on disk, so a violation cannot hide behind an inactive build tag. Bans config FILE I/O, not the config package — cmd/mcpproxy-tray legitimately references the config.LogConfig type for its own logger."

status: done

priority: P2

depends_on: [tray-oauth-config-read]

- id: planning-hygiene

title: Planning/docs truth automation

status: todo

priority: P2

depends_on: []

note: "Automate the consistency checks this very audit had to do by hand: roadmap vs GitHub PR state, tasks.md updates on implementation PRs, volatile CLAUDE.md/README facts, and quickstart contract tests."

tasks:

- id: hygiene-roadmap-github-check

title: "gen-roadmap --check-github: cross-check roadmap.yaml statuses vs gh PR state + dangling spec links"

status: done

pr: "#800"

depends_on: []

- id: hygiene-tasks-reconcile

title: "CI rule: PR touching specs/<id> implementation paths must update tasks.md"

status: todo

depends_on: []

- id: hygiene-spec-evidence-check

title: "scripts/check-spec-evidence.py: deterministic check that every TICKED task cites code that exists"

status: done

priority: P1

note: "Report-only by design. A bare path-existence gate would be ~98% noise: of the 51 missing paths cited by ticked tasks, 50 NEVER existed in git history (speckit cites planned paths; code lands elsewhere). Classifies RELOCATED (stale path, high/medium confidence) vs REMOVED vs UNRESOLVED, and demotes path complaints when a distinctive cited symbol is found. Also surfaces `possibly_built` (unticked, evidence present). --json feeds hygiene-spec-gardener."

depends_on: []

- id: hygiene-spec-gardener

title: "Weekly cloud routine: LLM judges only the residue the evidence-check cannot decide, opens/updates one propose-only PR"

status: in_progress

priority: P2

note: "Claude cloud routine 'spec-roadmap gardener' (trig_014GkHno4XSTobu8ViJV7Sno), Mondays 05:07 UTC. Branch claude/spec-gardener (the `claude/` prefix is what the cloud git-proxy allows to push without unrestricted-branch-push). Guardrails: never pushes main; never auto-applies un-ticks (they go in the PR body for a human); evidence required per tick; adversarial refutation pass; 40-tick cap per run. Blocked in practice until check-spec-evidence.py lands on main — the routine no-ops until then."

depends_on: [hygiene-spec-evidence-check]

- id: hygiene-docs-facts

title: "Generate volatile CLAUDE.md/README facts (Go version, built-in tool list, sample config) from code with --check"

status: todo

depends_on: []

- id: hygiene-quickstart-contract

title: "Run top quickstart.md scenario per spec as contract test in test-api-e2e.sh"

status: todo

depends_on: []

# ── PARKED epics (intentionally on hold) ──────────────────────────────────

- id: marketplace

title: Server marketplace

status: todo

parked: true

priority: P3

mcp: MCP-37

depends_on: []

note: "PARKED. ~60% already ships (browse/search/one-click add). No spec yet; gaps tracked as MCP-3246..3250 (tray entries, metadata, telemetry). (070 is the registries-search-add spec, not a marketplace spec.)"

- id: siem

title: Audit SIEM integration

status: todo

parked: true

priority: P3

mcp: MCP-39

depends_on: []

note: "PARKED. Splunk HEC / Elastic _bulk / syslog shippers reusing JSONL export pipeline."

- id: paid-tier

title: Paid-tier MVP (billing / seats / license)

status: todo

parked: true

priority: P3

mcp: MCP-40

depends_on: []

note: "PARKED. Server-edition revenue motion: Ed25519 license tokens, seats, Stripe checkout. Behind //go:build server."

- id: sdk-v1-migration

title: SDK v1 migration

status: todo

parked: true

priority: P3

depends_on: []

note: "PARKED. Migrate to the v1 MCP Go SDK surface."

- id: sso

title: SSO (server edition)

status: todo

parked: true

priority: P3

depends_on: []

note: "PARKED. Single sign-on for the multi-user server edition."

# ── MERGED-BUT-UNIMPLEMENTED specs (cross-spec audit 2026-07-01) ───────────

# These specs are checked into specs/ but materially absent from code. Most

# "drafted/0%" specs are actually SHIPPED (stale tasks.md checkboxes) — these

# are the genuinely-unbuilt ones. See docs/personal-edition-polish.md audit.

- id: mcp-2026-upgrade

title: MCP protocol upgrade to 2026-07-28 revision

status: blocked

priority: P3

spec: specs/058-mcp-2026-upgrade

depends_on: []

note: "BLOCKED on mcp-go shipping 2026-07-28 (pinned v0.55.x tops out at 2025-11-25). CROSS-SPEC CONFLICT: FR-012 forbids per-connection */list variation; SHIPPED Spec 057 selects toolset by URL path /mcp/p/<slug>. Must reconcile at plan time (058 spec now carries a Cross-Spec Reconciliation note). 028 agent-token scoping is already compatible (header-carried)."

- id: security-gateway-cd

title: Security gateway Tracks C/D (per-arg least-privilege + signature provenance)

status: todo

priority: P3

spec: specs/054-mcp-security-gateway

depends_on: []

note: "Track A→Spec 056, Track B→Spec 059 (both shipped). UNBUILT: Track C per-ARGUMENT allow-listing (per-tool scope exists in mcp_direct_scope.go); Track D provenance + human-readable signature diff (SHA-256 pinning exists via Spec 032). Build ON 032/028, don't re-implement; honor the rug-pull re-quarantine interaction rule vs 032 auto-approve."

- id: discovery-eval-harness

title: Discovery-quality eval harness (Spec 065 second half)

status: todo

priority: P3

spec: specs/065-evaluation-foundation

depends_on: []

note: "Security recall/FP half SHIPPED (cmd/scan-eval, backs Spec 076/077 gate). UNBUILT: the discovery-quality (retrieve_tools recall) eval harness."