Skip to content

ADR-0013: Placeholder Package Rationalization (Post-v2.0 Proposal)
Status Accepted and ENACTED in v3.0.0 (was: Proposed, deferred post-v2.0)
Date 2026-07-12 (proposed); 2026-07-26 (enacted)
Deciders Chief Software Architect, MineProductivity
Governs The structural placeholder packages under src/mineproductivity/
Related documents ROADMAP.md; docs/governance/ENGINEERING_RULES.md; docs/governance/MIGRATION_GUIDE_v2_to_v3.md; root README.md

Enacted in the v3.0.0 major release. The proposal below was accepted at the first post-v2.0 governance review and carried out as the sanctioned breaking change of the v3.0 major bump. See the Enactment Record at the end of this document for exactly what was removed and retained.

Context

Nine packages under src/mineproductivity/ remain 7-line structural placeholders left from the Phase-0 repository skeleton - each an __init__.py stub with a skeleton-era README.md, no locked Design Specification, no Implementation Checklist, and no code:

benchmark, certification, cli, config, datasets, exceptions, io, typing* , utils, validation.

(*The earlier handoff also named a typing stub; it does not exist in the tree. The actual count is nine.)

The eleven domain packages of the locked architecture (core → … → visualization) plus the three cross-cutting infrastructure packages (registry, plugins, connectors) are all implemented, tested, and released as of v1.11.0. The nine placeholders are the only remaining skeleton artifacts. A production 2.0 that ships nine empty stubs with skeleton READMEs presents an inconsistent, unfinished surface to a first-time reader - but removing packages is itself an architectural change, and the Architecture Stability rule requires that such changes be deliberate, justified, and reviewed, not bundled opportunistically into a certification release.

Decision (proposed, not yet enacted)

Defer any placeholder removal until after v2.0. When a future governance review takes this up, evaluate each placeholder against a single test - does it have a concrete, chartered future purpose that justifies its continued presence as a named package? - and sort them into three groups:

Group A - Retain and eventually implement (clear purpose):

  • cli - a command-line interface is a natural post-architecture application layer with an obvious user-facing purpose. pyproject.toml previously shipped a [project.scripts] entry point for it (removed in v0.7.1 because the target did not exist yet). Retain; implement behind its own Design Specification when scheduled.
  • certification - a conformance/certification suite has a defined role in the Reference Implementation Blueprint (Phase 7). scripts/quality/ provides interim standalone substitutes. Retain; implement when Phase 7 is scheduled.

Group B - Resolve a naming shadow:

  • benchmark (source package) shadows the top-level benchmark/ directory, which already hosts real, run scenarios and reports. The source-package stub serves no purpose the top-level directory does not already serve. Recommend removing the src/mineproductivity/benchmark/ stub (or, if a harness package is later wanted, giving it a distinct name), so the two benchmark locations stop colliding conceptually.

Group C - Remove unless a concrete need is demonstrated:

  • config, io, utils, exceptions, validation, datasets - generic cross-cutting names with no locked specification and no demonstrated need. core already defines its own internal exception hierarchy directly and does not depend on a separate exceptions package; validation is covered within each package; datasets is served by per-package test fixtures. Recommend removal, each recorded in its own follow-up ADR, unless a concrete, specified need arises first.

Consequences

  • If enacted (post-v2.0): a cleaner, fully-intentional package surface; the root README's "24 subsystems" framing and the cross-cutting-layer list updated to match; no dead stubs in a certified platform.
  • If never enacted: the placeholders remain harmless but present a slightly unfinished surface; documentation must continue to describe them honestly as placeholders rather than implying they are usable.
  • In all cases: the v2.0 certification proceeds with the placeholders retained and honestly documented. Their fate is a deliberate, separate, ADR-gated decision - never a silent deletion.

Status Tracking

Superseded by the Enactment Record below: this ADR is now Accepted and Enacted (v3.0.0).

Enactment Record (v3.0.0, 2026-07-26)

Carried out as the sanctioned breaking change of the v3.0 major release:

Removed (7 packages + 1 non-package directory):

  • Group B: benchmark (naming shadow of the top-level benchmark/ directory).
  • Group C: config, io, utils, exceptions, validation, datasets.
  • typing/ — discovered during enactment: not listed originally because the Phase-0 handoff wrongly said it did not exist. In the tree it was a directory containing only a why.txt note, with no __init__.py (not an importable package). It met every removal criterion (no implementation, no imports, no tests, no public value) and shadowed the stdlib typing, so it was removed with the Group C set.

Each removed item had zero import references anywhere in src/tests/ examples, no tests (their tests/unit/<pkg>/ dirs held only an empty __init__.py + README and were removed too), and no doc pages. Their responsibilities already live elsewhere (configuration shape in core.BaseConfiguration; the exception hierarchy in core; benchmarking in the top-level benchmark/ directory; datasets in fixtures and the enterprise generators).

Retained (2 packages):

  • cli — chartered user-facing application layer; implement behind its own Design Specification when scheduled.
  • certification — chartered conformance role in the Reference Implementation Blueprint (Phase 7); scripts/quality/ remains the interim substitute.

Migration: effectively a no-op for real code (nothing imported the removed stubs). See docs/governance/MIGRATION_GUIDE_v2_to_v3.md.