Skip to content

docs(spec): day-two activation (E3) - #1712

Draft
Dumbris wants to merge 9 commits into
mainfrom
claude/spec-day-two-activation-1fad2a
Draft

Dumbris wants to merge 9 commits into
mainfrom
claude/spec-day-two-activation-1fad2a

Conversation

@Dumbris

@Dumbris Dumbris commented Oct 20, 2026 •

Copy link
Copy Markdown
Member

Design-only PR for growth experiment E3, day-two activation: Spec 122 in specs/122-day-two-activation/ (it was drafted as 119). It contains no code. Implementation is split into five PRs (plan.md D7).

What the spec does

  • First-run starter (US1/US2). A fresh install with zero indexed tools gets a pre-selected starter in the wizard's Servers step: time via uvx, or sequentialthinking via npx as the fallback. It goes through the unchanged catalog door, so it is quarantined by default. The card shows the exact command and the isolation mode, and nothing runs until the user clicks "Add and inspect". The user then approves the captured tools in place, bound to the review (Spec 117 expected_hashes + expected_incarnation). Nothing is auto-approved. fetch and everything are excluded, because everything ships get-env, which dumps all environment variables. The same offer appears, not pre-selected, on Web Home and on the native Home.
  • Second client (US3). Once one client is connected, the wizard and the native Connect sheet list the other clients they detected, using the stat-only Spec 075 payload. Each write is a per-client, previewed action.
  • Weekly "what MCPProxy did" (US4). An additive digest on GET /activity/summary, shown as a Web Home card, a tray glance line and mcpproxy activity summary --since 7d. It reports calls brokered by client, tool changes held for review, blocks by class (quarantine / profile / other), and calls with secrets detected. Everything is computed locally.
  • Telemetry (US5). The next telemetry schema (17 on today's main) adds a closed-enum day_two object plus activation.first_tool_indexed_ever. There are no new identifiers, and the PII scan rejects unknown keys and values. This part ships first (PR-A), so baseline data exists before the UI does.

Success bar: at least 82% of new installs reach tools-indexed (same heartbeat-sampled instrument as the 71.5% baseline), and D7 on the IP key is at least 18%. The kill rule is in the spec.

Changes after the reviews (2026-10-25 merge with main), not re-reviewed

  • Renumbered 119 → 122. Main gained specs/119-scan-default-trust, and 120 and 121 are claimed by other branches.
  • Telemetry bump 15 → 17. Main is at schema 16 after 101-tpa-db.
  • The starter follows the new scan default trust mode (Spec 119). A clean admission scan unquarantines it through the unchanged door, and the step goes straight to "ready". Under manual, or after a non-clean verdict, the in-place bound approval applies. FR-003, FR-006, A2 and US1 scenario 8 were updated accordingly. The starter still adds no trust path of its own.

Riskiest assumption

The spec assumes that the 36% vs 66% one-and-done gap between installs that index a tool and those that don't is caused by having a working tool. It could instead reflect intent: people who add a real server already had a reason to come back. A time starter will lift "tools indexed" almost mechanically, so the primary metric can move while retention does not (a Goodhart risk). That is why D7 is co-primary, why the kill rule requires both metrics to move, and why first_tool_indexed_ever is reported separately from the baseline-comparable tool_count series. A second risk is that the explicit approval click becomes the new drop-off. It is measured (approval_abandoned, measured from capture completion), but by design there is no auto-approve fallback.

Cross-model review (OpenCode github-copilot/gpt-6.1-sol, --variant high)

Artifact Round Verdict Notes
spec.md r1 REQUEST_CHANGES 12 findings, all verified and fixed: informed consent before code runs, no scan-mode admission path, audited allowlist, day-0 and launcher denominators, comparable SC-001 instrument, hold-entry semantics, dispatch-based "brokered", coverage watermark, scoped authz, view counters, sticky second-client facts
spec.md r2 REQUEST_CHANGES 5: SC-004 instrument, launcher denominator, entered_hold, upgrade observation, reference registry override fail-closed
spec.md r3 APPROVE
plan r1 REQUEST_CHANGES 14: auth on the starter POST, an atomic resolve→add snapshot, native incarnation binding, lossless fact recording, startup anchor, a telemetry-independent facts loop, an explicit dispatched fact, post-dispatch blocks, R8 emit sites, abandonment clock, per-client connect mode, unchanged wizard completion, response envelopes
plan r2 REQUEST_CHANGES 9 open: commit-time evidence bound to incarnation, capture-completion evidence, limiter sheds, unpaired profile refusals, quickstart assertions
plan r3 REQUEST_CHANGES 6 new: sandbox quarantine typed reason, native starter state machine (no blind approve), native marks, edition guards, PR-B verification scope, digest.window
plan r4 REQUEST_CHANGES 3: quickstart request correlation, installation-wide watermark leaking to scoped callers, blocked prompts/get counted as a response block
plan r5 REQUEST_CHANGES 1: quickstart CLI not pinned to the scratch instance
plan r6 APPROVE

I verified every finding against the code before fixing it. None was rejected as a false positive. The plan took 6 of the 10 allowed rounds.

speckit.analyze: 100% FR coverage (32 FRs → 78 tasks in 7 phases mapped to 5 PRs). It found one CRITICAL, now recorded: constitution IV says Docker by default, but the product default is off. This is pre-existing and recorded in the plan's Complexity Tracking. The starter follows the global setting and does not widen it. There was also 1 MEDIUM enum gap and 2 LOW items, all fixed.

Assumptions made without asking (zero-interruption policy)

All of them are in spec.md "Clarifications" / "Assumptions" and in research.md R1-R12. The main ones:

  • the experiment is a pre/post cohort comparison, with no randomised holdout, because n is too small;
  • the starter is quarantined and approved in place, because no catalog marker grants trust;
  • "calls brokered" means dispatched upstream calls only;
  • the personal edition only.

Follow-ups (not in this PR)

  • O1: an embedded in-process starter, if launcher_missing is above 15%.
  • O2: a weekly OS notification.
  • O4: pin the audited starter version.
  • O5: a product decision on the global Docker-isolation default. It conflicts with constitution IV and predates this spec.

@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Oct 20, 2026 •

Copy link
Copy Markdown

Deploying mcpproxy-docs with  Cloudflare Pages  Cloudflare Pages

Latest commit: 0740964
Status: ✅  Deploy successful!
Preview URL: https://4375681d.mcpproxy-docs.pages.dev
Branch Preview URL: https://claude-spec-day-two-activati.mcpproxy-docs.pages.dev

View logs

@Dumbris Dumbris changed the title Spec: day-two activation (E3) docs(spec): day-two activation (E3) Oct 20, 2026
@codecov-commenter

Copy link
Copy Markdown

⚠️ Please install the 'codecov app svg image' to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@github-actions

github-actions Bot commented Oct 20, 2026 •

Copy link
Copy Markdown
Contributor

📦 Build Artifacts

Workflow Run: View Run
Branch: claude/spec-day-two-activation-1fad2a

Available Artifacts

  • archive-darwin-amd64 (32 MB)
  • archive-darwin-arm64 (29 MB)
  • archive-linux-amd64 (20 MB)
  • archive-linux-arm64 (18 MB)
  • archive-windows-amd64 (32 MB)
  • archive-windows-arm64 (28 MB)
  • frontend-dist-pr (0 MB)
  • installer-dmg-darwin-amd64 (28 MB)
  • installer-dmg-darwin-arm64 (25 MB)
  • smart-mcp-proxymcpproxy-goHFCW70.dockerbuild (0 MB)

How to Download

Option 1: GitHub Web UI (easiest)

  1. Go to the workflow run page linked above
  2. Scroll to the bottom "Artifacts" section
  3. Click on the artifact you want to download

Option 2: GitHub CLI

gh run download 40331489668 --repo smart-mcp-proxy/mcpproxy-go

Note: Artifacts expire in 14 days.

…aude/spec-day-two-activation-1fad2a

# Conflicts:
#	ROADMAP.md
…schema 17, scan default trust)

main gained specs/119-scan-default-trust (number collision; 120/121 are claimed by
other branches) and telemetry schema 16 (101-tpa-db). The spec moves to 122,
its telemetry bump becomes schema 17, and the starter flow now covers the scan
default: a clean admission scan unquarantines through the unchanged door.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants