Epic: Stub Package Cleanup — Remove Ghost Packages and Empty Stub Modules #946

New issue

Open

opened 2026-03-14 03:15:38 +00:00 by freemo · 0 comments

freemo commented

2026-03-14 03:15:38 +00:00

Owner

Background and Context

A codebase audit revealed several packages that exist only as empty stubs or ghost artifacts with no functional code. These packages occupy namespace, confuse IDE tooling, and misrepresent the implementation status of the system.

Specifically:

src/cleveragents/acp/ — Ghost package containing only __pycache__/ with 9 orphaned .pyc files and no .py source files. The ACP (Agent Communication Protocol) module was superseded by the A2A protocol (ADR-047) but was never properly removed.
src/cleveragents/runtime/ — Empty stub package with only __init__.py containing __all__ = [].
src/cleveragents/domain/repositories/ — Empty stub package with only __init__.py containing __all__ = [].
src/cleveragents/domain/plans/ — Empty stub package with only __init__.py containing __all__ = [].
src/cleveragents/application/workflows/ — Empty stub package with only __init__.py containing __all__ = [].

Per the specification and CONTRIBUTING.md, no half-done or placeholder implementations should exist in the source tree. Each of these must be either properly implemented (if the spec requires them) or cleanly removed (if they are dead code).

Expected Behavior

The source tree contains no ghost packages, no orphaned .pyc files without corresponding .py sources, and no empty stub packages that serve no architectural purpose. Every package in the source tree either contains functional code or is removed.

Acceptance Criteria

acp/ directory is fully removed including all __pycache__/ contents
runtime/ is either implemented per spec or removed with imports updated
domain/repositories/ is either implemented per spec or removed with imports updated
domain/plans/ is either implemented per spec or removed with imports updated
application/workflows/ is either implemented per spec or removed with imports updated
No orphaned .pyc files remain anywhere in the source tree without corresponding .py files
All import references to removed packages are updated or removed
nox passes (all default sessions) after cleanup

Definition of Done

This Epic is complete when all child issues are closed and merged. No ghost packages or empty stub packages remain in the source tree, and all tests pass.

## Background and Context A codebase audit revealed several packages that exist only as empty stubs or ghost artifacts with no functional code. These packages occupy namespace, confuse IDE tooling, and misrepresent the implementation status of the system. Specifically: - **`src/cleveragents/acp/`** — Ghost package containing only `__pycache__/` with 9 orphaned `.pyc` files and no `.py` source files. The ACP (Agent Communication Protocol) module was superseded by the A2A protocol (ADR-047) but was never properly removed. - **`src/cleveragents/runtime/`** — Empty stub package with only `__init__.py` containing `__all__ = []`. - **`src/cleveragents/domain/repositories/`** — Empty stub package with only `__init__.py` containing `__all__ = []`. - **`src/cleveragents/domain/plans/`** — Empty stub package with only `__init__.py` containing `__all__ = []`. - **`src/cleveragents/application/workflows/`** — Empty stub package with only `__init__.py` containing `__all__ = []`. Per the specification and CONTRIBUTING.md, no half-done or placeholder implementations should exist in the source tree. Each of these must be either properly implemented (if the spec requires them) or cleanly removed (if they are dead code). ## Expected Behavior The source tree contains no ghost packages, no orphaned `.pyc` files without corresponding `.py` sources, and no empty stub packages that serve no architectural purpose. Every package in the source tree either contains functional code or is removed. ## Acceptance Criteria - [ ] `acp/` directory is fully removed including all `__pycache__/` contents - [ ] `runtime/` is either implemented per spec or removed with imports updated - [ ] `domain/repositories/` is either implemented per spec or removed with imports updated - [ ] `domain/plans/` is either implemented per spec or removed with imports updated - [ ] `application/workflows/` is either implemented per spec or removed with imports updated - [ ] No orphaned `.pyc` files remain anywhere in the source tree without corresponding `.py` files - [ ] All import references to removed packages are updated or removed - [ ] `nox` passes (all default sessions) after cleanup ## Definition of Done This Epic is complete when all child issues are closed and merged. No ghost packages or empty stub packages remain in the source tree, and all tests pass.

Rows
Columns