Description
PR #3401 (Apr 2026, "refactor(code-quality): typed errors, test module gating, deferred TODO markers") introduced a cluster of six deliberately-deferred architecture decisions as in-code TODO markers. None are tracked as GitHub issues, so they have zero visibility outside source — a contributor triaging tech-debt via gh issue list would never find them.
This is a lightweight pointer issue only. Each marker already carries full rationale, target design, and blocking dependencies in its own doc comment — do not re-derive or expand that scope here. In particular, A2 explicitly states any typestate-builder work needs its own SDD spec and must be split across >= 4 PRs; this issue does not commit to that work, it only makes the cluster discoverable.
Markers
| Marker |
Location |
One-line summary |
| A1 |
(no dedicated marker — referenced only as a blocker inside A2's doc comment) |
Agent<C> god-object decomposition (25+ sub-states); must land before A2 can proceed |
| A2 |
crates/zeph-core/src/agent/builder.rs:22 |
Replace the fake builder pattern on Agent<C> with a phantom-typestate AgentBuilder<C, State>; blocked by A1 |
| A3 |
crates/zeph-core/src/channel.rs:232 |
Split the monolithic Channel trait into focused sub-traits |
| D1 |
crates/zeph-llm/src/any.rs:17 |
Migrate call sites from AnyProvider to Arc<dyn LlmProviderDyn> |
| D2 |
crates/zeph-tools/src/executor.rs:672 |
Consolidate ToolExecutor and ErasedToolExecutor |
| G3 |
crates/zeph-tools/src/executor.rs:658 |
Tower-style tool middleware stack |
| D4 |
crates/zeph-config/src/lib.rs:10 |
Typed config presets |
Why
Filed during CI-1437 architecture review (zeph-core/agent/builder.rs audit) — see .local/testing/journal/ci-1437.md "Architecture & Code Quality" section for the discovery context. A2's doc comment references "critic review §C1" for further rationale; consult that and each marker's own comment before scoping any implementation work.
Environment
Description
PR #3401 (Apr 2026, "refactor(code-quality): typed errors, test module gating, deferred TODO markers") introduced a cluster of six deliberately-deferred architecture decisions as in-code TODO markers. None are tracked as GitHub issues, so they have zero visibility outside source — a contributor triaging tech-debt via
gh issue listwould never find them.This is a lightweight pointer issue only. Each marker already carries full rationale, target design, and blocking dependencies in its own doc comment — do not re-derive or expand that scope here. In particular,
A2explicitly states any typestate-builder work needs its own SDD spec and must be split across >= 4 PRs; this issue does not commit to that work, it only makes the cluster discoverable.Markers
Agent<C>god-object decomposition (25+ sub-states); must land before A2 can proceedcrates/zeph-core/src/agent/builder.rs:22Agent<C>with a phantom-typestateAgentBuilder<C, State>; blocked by A1crates/zeph-core/src/channel.rs:232Channeltrait into focused sub-traitscrates/zeph-llm/src/any.rs:17AnyProvidertoArc<dyn LlmProviderDyn>crates/zeph-tools/src/executor.rs:672ToolExecutorandErasedToolExecutorcrates/zeph-tools/src/executor.rs:658crates/zeph-config/src/lib.rs:10Why
Filed during CI-1437 architecture review (
zeph-core/agent/builder.rsaudit) — see.local/testing/journal/ci-1437.md"Architecture & Code Quality" section for the discovery context.A2's doc comment references "critic review §C1" for further rationale; consult that and each marker's own comment before scoping any implementation work.Environment