Plan: IP-105 Runtime Adoption Telemetry

Initial Situation

IP-105 is unblocked by completed IP-102. API/contract currently support authenticated baseline metadata only. DB persistence has Better Auth tables. CLI has value-event points but no telemetry emitter.

Solution Shape

Define typed telemetry contract first, then DB schema/service, then API ingestion, then CLI best-effort emitters. Keep source facts safe and leave adoption UI to M4.5.

Inner Skill Phases

• $grill-me: no live question needed; scope is locked by Linear and reference docs.
• $parallel-research: used for API/contract/db/CLI surface discovery.
• $swarm-planner: split into contract, persistence, API, CLI, docs validation.
• $tdd: tests first for event schema and API ingestion; CLI emission tests before command wiring where practical.

Tasks

T105-1: Add telemetry contract and event schema

• depends_on: []
• location: packages/contract/src
• description: Add approved event-name union, telemetry payload schemas, typed errors, and HttpApi group for ingestion.
• validation: bun run test --filter=@punks/contract; OpenAPI paths include telemetry endpoint; non-approved event names fail schema decode.
• status: Planned
• log:
• files edited/created:
• backlog_item_id: IP-131
• backlog_item_url: https://linear.app/devpunks/issue/IP-131/backend-records-trusted-baseline-usage-events
• relation_mode: native
• assigned_skills: [effect-authoring, effect-best-practices, quality-types, tdd, simplify]
• tdd_target: Decoding a telemetry payload accepts only the five approved event names and required safe metadata.
• review_mode: cli

T105-2: Add telemetry persistence model

• depends_on: [T105-1]
• location: packages/db/src/schema
• description: Add project_usage, observed_repository, and cli_usage_event schema tables with indexes and explicit migration note/status.
• validation: bun run check-types --filter=@punks/db; schema exports compile; migration deferral or generated migration is documented.
• status: Planned
• log:
• files edited/created:
• backlog_item_id: IP-131
• backlog_item_url: https://linear.app/devpunks/issue/IP-131/backend-records-trusted-baseline-usage-events
• relation_mode: native
• assigned_skills: [effect-authoring, effect-best-practices, quality-types, tdd, simplify]
• tdd_target: Type-level schema exports expose the ProjectUsage -> ObservedRepository -> CliUsageEvent relationships.
• review_mode: cli

T105-3: Implement API telemetry ingestion service

• depends_on: [T105-2]
• location: apps/api/src
• description: Add Effect service/layer for telemetry ingestion, auth boundary, allowed event filtering, source/noise classification, idempotency, and tests.
• validation: bun run test --filter=@punks/api; unauthorized requests fail; approved events persist or are accepted by test layer; noisy/duplicate events do not inflate stats.
• status: Planned
• log:
• files edited/created:
• backlog_item_id: IP-131, IP-132
• backlog_item_url: https://linear.app/devpunks/issue/IP-131/backend-records-trusted-baseline-usage-events
• relation_mode: native
• assigned_skills: [effect-authoring, effect-backend-structure, effect-best-practices, quality-types, tdd, simplify]
• tdd_target: An authenticated API request with cli.scaffold.setup.completed succeeds once and duplicate/noisy replays are filtered.
• review_mode: cli

T105-4: Add CLI telemetry emitter and first event hooks

• depends_on: [T105-3]
• location: apps/cli/src
• description: Add best-effort control-plane telemetry client, safe repo/git metadata collection, environment flags, and emitters after successful auth login, artifact pull, scaffold setup, and update apply.
• validation: focused CLI tests for emission success/failure/no-op; punks --help; built CLI smoke where relevant.
• status: Planned
• log:
• files edited/created:
• backlog_item_id: IP-131, IP-132
• backlog_item_url: https://linear.app/devpunks/issue/IP-132/telemetry-filters-local-debug-test-and-retry-noise
• relation_mode: native
• assigned_skills: [effect-authoring, quality-types, tdd, simplify]
• tdd_target: A successful scaffold setup triggers a single best-effort telemetry submission; a failed/no-op run submits nothing and command success is not blocked by telemetry failure.
• review_mode: cli

T105-5: Document telemetry boundary and validate closeout

• depends_on: [T105-4]
• location: docs/README.md, docs/reference/harness-intelligence.md, wiki specs
• description: Update product telemetry docs, M4.5 boundary notes, implementation notes, issue matrix, and validation evidence.
• validation: git diff --check; bun run check; bun run check-types; targeted tests; full bun run test if feasible.
• status: Planned
• log:
• files edited/created:
• backlog_item_id: IP-105
• backlog_item_url: https://linear.app/devpunks/issue/IP-105/track-adoption-through-runtime-telemetry
• relation_mode: native
• assigned_skills: [docs-ingest-phase, review-phase, turborepo, simplify]
• tdd_target: IP-131/IP-132 acceptance table maps to tests and docs evidence.
• review_mode: cli

Dependency Graph

T105-1 -> T105-2 -> T105-3 -> T105-4 -> T105-5

Validation Gates

• Gate 1: Contract only allows approved value events.
• Gate 2: Persistence model represents ProjectUsage aggregate.
• Gate 3: API filters noise and accepts happy-path events.
• Gate 4: CLI emits best-effort events only after success.
• Gate 5: Docs preserve OTel/backoffice/product telemetry boundaries.

Risks

• Migration tooling gap. Mitigation: generate if tooling exists; otherwise record explicit migration deferral.
• Identity incompleteness. Mitigation: support current authenticated operator id through the Better Auth bearer/device flow.
• Privacy leakage. Mitigation: sanitize remotes and record only safe facts.

Unresolved Questions

• Migration generation is open pending current DB tooling inspection during implementation.