Future State Proposals

Tags contributor architecture

These documents describe the intended end state for high-impact cleanup and refactoring TODOs. Each proposal is tied to a planning item under _project/TODO/main/planning/ and makes the destination architecture explicit: what gets pruned, excluded from the wheel, or reorganized within BenchBox.

Sequencing and Priority

Not all proposals should be pursued simultaneously. Adversarial review established the following priority tiers based on coupling analysis, effort, and evidence of need:

Tier 1: Act now (small effort, clear value):

  • artifactlinks: Dead code with zero consumers. Prune.

  • benchbox-maintainer: Near-zero coupling. Remove entry point and exclude from wheel.

  • benchbox-experimental: Namespace hygiene for 5 misplaced subsystems.

Tier 2: Act when prerequisites are met:

  • MCP APIs: Already an optional extra. Formalize 3 internal API refs as public exports. Defer distribution split until post-v1.0.

  • Monitoring: Light coupling but no second consumer. Gate behind benchbox[monitoring] optional extra first.

Two proposals were discarded during adversarial review:

  • sqlplankit (query-plan extraction): 37-file blast radius, shared-type boundary problem (QueryPlanDAG embedded in core result model), no external demand. Internal boundary improvements can be done without a package split.

  • todo-dag: _project/ does not ship to users, no second consumer exists. Extracting a package for single-repo contributor tooling is package sprawl.

Proposals