"Telemetry implementation backlog 2026"

Telemetry implementation backlog 2026

Use this as the single execution checklist for telemetry unification. Check items off in PRs; link PRs from commit messages or issue trackers as your team prefers.

SSOT hierarchy: telemetry-trust-ssot > this backlog > crate code.

Phase 0 — SSOT and documentation convergence

0.A Contributor entry points

  • AGENTS.md — add bullet linking telemetry-trust-ssot, telemetry-implementation-blueprint-2026, and research doc.
  • docs/src/contributors/contributor-hub.md — optional one-line pointer to telemetry SSOT if hub lists architecture SSOTs.
  • docs/src/contributors/documentation-governance.md — add telemetry doc family to maintenance table if required by project rules.

0.B Environment variables SSOT

  • docs/src/reference/env-vars.md — add VOX_BENCHMARK_TELEMETRY row (CLI → research_metrics benchmark_event).
  • docs/src/reference/env-vars.md — add VOX_SYNTAX_K_TELEMETRY row (fallback to benchmark flag per benchmark_telemetry.rs).
  • docs/src/reference/env-vars.md — cross-link telemetry-metric-contract from new rows.
  • docs/src/reference/env-vars.md — verify VOX_MESH_CODEX_TELEMETRY, VOX_MCP_LLM_COST_EVENTS, context lifecycle vars cross-link telemetry-trust-ssot.
  • docs/src/reference/orchestration-unified.md — dedupe or point to env-vars for benchmark/syntax-k if duplicated.
  • docs/src/reference/mens-training.md — ensure benchmark/syntax-k pointers remain consistent with env-vars.

0.C Core reference docs

  • docs/src/reference/telemetry-metric-contract.md — add “Related SSOT” block: trust-ssot, taxonomy, retention-sensitivity, client-disclosure.
  • docs/src/reference/cli.md — add pointer to telemetry-trust-ssot next to cost-event and mesh telemetry sections.
  • docs/src/architecture/completion-policy-ssot.md — add pointer to telemetry-retention-sensitivity-ssot for ci_completion_* classification.
  • docs/src/architecture/voxdb-connect-policy.md — note optional DB and impact on telemetry availability (no writes when DB absent).

0.D Book index and architecture map

  • docs/src/SUMMARY.md — link telemetry-trust-ssot, taxonomy, retention-sensitivity, client-disclosure, blueprint, backlog.
  • docs/src/architecture/architecture-index.md — list new SSOTs under Current architecture and SSOT.
  • docs/src/architecture/research-index.md — link blueprint + backlog under planning or research follow-ups.
  • docs/src/architecture/telemetry-unification-research-findings-2026.md — add “Implementation” see-also to new SSOT pages.

0.E VS Code packaging

Phase 1 — Taxonomy and contract registry

1.A contracts/index.yaml

  • Register each telemetry JSON Schema with stable id and enforced_by where applicable.
  • Add index entries for contracts/telemetry/completion-*.v1.schema.json if any row missing.
  • Add index entry for contracts/orchestration/context-lifecycle-telemetry.schema.json with description “orchestrator tracing fields”.
  • Add index pattern for future contracts/telemetry/usage-event-*.schema.json (placeholder row or ADR note).

1.B Taxonomy document parity

  • docs/src/architecture/telemetry-taxonomy-contracts-ssot.md — fill owner_crate column for each shipped METRIC_TYPE_*.
  • Map contracts/eval/syntax-k-event.schema.json to syntax_k_event in taxonomy table.
  • Map contracts/communication/interruption-decision.schema.json to attention/interruption plane.

1.C Schema drift CI

  • crates/vox-cli/src/commands/ci/run_body_helpers/data_ssot_guards.rs — extend guards so every METRIC_TYPE_* constant is mentioned in telemetry-metric-contract or taxonomy SSOT.
  • crates/vox-cli/src/commands/ci/command_compliance/mod.rs — ensure completion telemetry schemas stay verified when index changes.

Phase 2 — Retention and sensitivity

2.A retention-policy.yaml

  • Add ci_completion_run with kind, days/ms_days, time_column (e.g. finished_at), rationale in YAML.
  • Add ci_completion_finding retention row if distinct TTL desired (or cascade via run FK).
  • Add ci_completion_detector_snapshot retention row if distinct TTL desired (or cascade via run FK).
  • Add ci_completion_suppression retention row (may be keep_forever or long TTL; document rationale).
  • Document conflict resolution if completion rows must be manual for compliance.

2.B Documentation

  • docs/src/architecture/telemetry-retention-sensitivity-ssot.md — replace “gap” language with actual TTLs once YAML updated.
  • docs/src/reference/cli.md — vox db prune-plan help text cross-link retention SSOT if not already.

2.C Tests

  • crates/vox-cli tests — prune-plan includes new tables (integration or unit on YAML parse).
  • crates/vox-db — verify prune SQL exists for new completion tables if added to policy.

Phase 3 — Producer audit and code alignment (vox-db)

  • crates/vox-db/src/research_metrics_contract.rs — document each METRIC_TYPE_* in module rustdoc with sensitivity class.
  • crates/vox-db/src/benchmark_telemetry.rs — ensure metadata size respects RESEARCH_METRICS_METADATA_JSON_MAX_BYTES.
  • crates/vox-db/src/syntax_k_telemetry.rs — align metadata with contracts/eval/syntax-k-event.schema.json.
  • crates/vox-db/src/socrates_telemetry.rs — classify socrates_surface vs memory_hybrid_fusion in comments.
  • crates/vox-db/src/questioning_telemetry.rs — classify questioning rows (S1/S2) in rustdoc.
  • crates/vox-db/src/populi_control_telemetry.rs — document mesh token is never stored in metadata.
  • crates/vox-db/src/workflow_journal.rs — classify workflow journal entries vs usage telemetry.
  • crates/vox-db/src/store/ops_codex/codex_metrics_packages.rs — document append_research_metric as canonical write path.
  • crates/vox-db/src/store/ops_completion.rs — add rustdoc: workspace-adjacent data class.
  • crates/vox-db/src/schema/domains/ci_completion.rs — column-level comments for path/fingerprint sensitivity.

Phase 3 — Producer audit (vox-cli)

  • crates/vox-cli/src/benchmark_telemetry.rs — document env precedence in file header; link env-vars SSOT.
  • crates/vox-cli/src/commands/ci/build_timings.rs — confirm writes only when opt-in; document.
  • crates/vox-cli/src/commands/ci/completion_quality.rs — document ingest path and data class.
  • crates/vox-cli/src/commands/mens/watch_telemetry.rs — link telemetry_schema.rs keys to data-ssot-guards contract.
  • crates/vox-cli/src/commands/db_research/reliability.rs — operator UX: warn when dumping S2 fields.
  • crates/vox-cli/src/commands/db_cli/core_subcommands.rs — help text references trust-ssot for research_metrics.
  • crates/vox-cli/src/codex_cmd.rs — Socrates aggregate JSON: classify as operator diagnostic.

Phase 3 — Producer audit (vox-mcp)

  • crates/vox-orchestrator/src/mcp_tools/llm_bridge/infer.rs — document VOX_MCP_LLM_COST_EVENTS defaulting when DB absent.
  • crates/vox-orchestrator/src/mcp_tools/server/lifecycle.rs — classify record_attention_event persistence path (not usage telemetry unless explicitly scoped).
  • crates/vox-orchestrator/src/mcp_tools/tools/task_tools.rs — context lifecycle policy side effects documented.
  • crates/vox-orchestrator/src/mcp_tools/tools/benchmark_tools.rs — tool descriptions reference trust-ssot.
  • crates/vox-orchestrator/src/mcp_tools/tools/chat_socrates_meta.rs — record_socrates_surface_event classification.
  • crates/vox-orchestrator/src/mcp_tools/tools/repo_catalog_tools.rs — benchmark record path gated and documented.
  • crates/vox-orchestrator/src/mcp_tools/dei_tools/orchestrator_snapshot.rs — mesh snapshot telemetry classification.
  • crates/vox-orchestrator/src/mcp_tools/tools/questioning_tools.rs — attention events vs questioning DB tables.
  • crates/vox-orchestrator/src/mcp_tools/a2a.rs — attention debit events documented.
  • crates/vox-orchestrator/src/mcp_tools/tools/dispatch.rs — ensure prepare_mcp_tool_args_for_storage applied on all persistence paths.
  • crates/vox-mcp/tests/tool_dispatch_tests.rs — add cases for any new redaction rules.

Phase 3 — Producer audit (vox-orchestrator)

  • crates/vox-orchestrator/src/context_lifecycle.rs — link context-lifecycle-telemetry.schema.json in module docs.
  • crates/vox-orchestrator/src/mesh_federation_poll.rs — document mesh_exec_lease_reconcile telemetry gate.
  • crates/vox-orchestrator/src/config/orchestrator_fields.rs — env flags for lifecycle shadow/enforce cross-link env-vars.
  • crates/vox-orchestrator/src/attention/interruption_policy.rs — document serialization for interruption-decision contract.
  • crates/vox-orchestrator/tests/context_lifecycle_telemetry_fixtures.rs — keep fixtures synced with schema changes.

Phase 3 — Producer audit (vox-populi / Mens)

  • crates/vox-populi/src/mens/tensor/telemetry_schema.rs — each key documented with S0/S1.
  • crates/vox-populi/src/mens/tensor/candle_qlora_train/db_thread.rs — training events vs product telemetry.
  • crates/vox-populi/src/transport/handlers.rs — privacy_class behavior documented.

Phase 3 — Producer audit (vox-ludus)

  • crates/vox-ludus/src/mcp_privacy.rs — reference generalized redaction policy when introduced.
  • crates/vox-ludus/src/config_gate.rs — VOX_LUDUS_MCP_TOOL_ARGS values documented in env-vars.

Phase 3 — Producer audit (vox-compiler / Syntax-K)

  • crates/vox-compiler/src/syntax_k.rs — telemetry hook calls documented; link syntax-k-event schema.

Phase 3 — Producer audit (vox-orchestrator / other)

  • crates/vox-dei/src/route_telemetry.rs — classify metrics; link taxonomy SSOT.
  • crates/vox-dei/src/lib.rs — any exports documented.

Phase 3 — Content-bearing stores (classification only, no merge into usage telemetry)

  • crates/vox-db/src/codex_chat.rs — rustdoc: S3 content plane.
  • crates/vox-db/src/store/ops_mcp_diagnostics.rs — transcript inserts S3.
  • crates/vox-db/src/schema/domains/agents.rs — table groups: telemetry vs content (comment block).

Phase 4 — Client disclosure and UX

  • vox-vscode/webview-ui/src/index.tsx — evaluate tab id="telemetry" rename vs display label-only change; document breaking change if any.
  • vox-vscode/webview-ui/src/components/Dashboard.tsx — user-visible strings reviewed against client-disclosure SSOT.
  • vox-vscode/package.json — contribution settings descriptions reference trust SSOT where debug flags exposed.
  • docs/src/reference/vscode-mcp-compat.md — cross-link telemetry-client-disclosure-ssot.

Phase 5 — Operations catalog and CLI registry

  • contracts/operations/catalog.v1.yaml — ensure every telemetry-related vox ci / vox db op used in guards is catalogued.
  • contracts/cli/command-registry.yaml — regenerate after any new CLI surface (vox ci capability-sync --write workflow per project rules).
  • docs/src/architecture/operations-catalog-ssot.md — pointer to telemetry backlog if present.

Phase 6 — CI workflow

  • .github/workflows/ci.yml — confirm data-ssot-guards / ssot-drift runs on PRs; add step if missing.
  • Document in docs/src/ci/command-compliance-ssot.md any new mandatory gate.

Phase 7 — Optional central sink (future)

  • ADR: remote telemetry upload, data residency, opt-in UX — ADR 023.
  • crates/vox-clavis/src/lib.rs — SecretId for upload URL + bearer token (VoxTelemetryUploadUrl, VoxTelemetryUploadToken); CLI uses resolve_secret only.
  • Queue module: crates/vox-cli/src/telemetry_spool.rs — local spool, export, enqueue, delete-after-ack on HTTP 2xx.
  • Rate limit and payload signer specification in SSOT — telemetry-remote-sink-spec.
  • CLI: vox telemetry status|export|enqueue|upload (catalog + generated registries).

Phase 8 — CHANGELOG and release discipline

  • CHANGELOG.md — process note: telemetry-affecting changes use the Telemetry subsection under [Unreleased].
  • Maintainer pointer: command-compliance SSOT — verify telemetry SSOT links when touching metric contracts or upload behavior.

Completion criteria (definition of done)

  • All Phase 0–4 items checked for minimal viable trust convergence.
  • Phase 5–6 complete before any default remote upload ships (no default upload in product; vox telemetry upload remains explicit).
  • Phase 7 technical guardrails documented in ADR 023; organization legal/security sign-off for production ingest remains operator responsibility (called out in ADR).