04 — roadmap.py Decomposition: Moderate Clusters + v7-Path Engine
Goal
Continue the roadmap/ subpackage extraction (Section 03 prerequisite):
the 15 moderate-coupling clusters (markdown-path Step 0/2.5/3/4-adjacent
helpers + autopilot-cure/loop-detection machinery) and the 5 v7-route-native
clusters that together mirror, for the v7 path, what Section 05’s
_step_5_emit_focus does for the markdown path.
Design flag (surface, do not silently resolve)
_enrich_route_envelope_for_execution (v7 path, this section) and
_step_5_emit_focus (markdown path, Section 05) are STRUCTURALLY parallel
implementations of “attach every enrichment before handing off to
execution” — both call into the grind/livelock/ledger-debt/criteria-gap
enrichers. This split organizes them as separate clusters (matching their
current separate identities) but does NOT unify them. Whether they are
drifting duplicates of one policy or genuinely separate legacy/current
paths is a real design question the plan defers to a /tp-help consult
at Section 04’s close (below) — record the reviewers’ verdict in this
section’s HISTORY, and file a follow-up bug if they judge it a genuine
LEAK:algorithmic-duplication requiring unification (do not unify inline
without that consult; the two functions’ call graphs are large enough that
an unreviewed merge risks silent behavior drift).
Cluster -> submodule mapping — this section’s scope
| Submodule | Responsibility | ~Lines | Key symbols |
|---|---|---|---|
roadmap_v7_serve_directives.py | v7 section-scope resolution + review-state reads + intel-heal wiring | ~330 | _resolve_v7_section, _recorded_review_state, _attach_serve_directives |
roadmap_route_envelope_enrichment.py | THE v7 execution-handoff enrichment engine | 694 | _enrich_route_envelope_for_execution |
roadmap_v7_cross_scope_block_wait.py | v7-specific cross-scope block-wait check | ~54 | _v7_cross_scope_block_wait |
roadmap_grind_livelock_guards.py | Convergence sum-type + grind/livelock/route-progress trip detectors | ~740 | _LivelockConvergence, _grind_liveness_route_or_none, _route_progress_trip_or_none |
roadmap_ledger_debt_enrichment.py | Ledger-append-debt directive attach + cross-plan-deferred enrichment | ~245 | _attach_ledger_debt_to_handoff, autopilot_completion_quarantine_route |
roadmap_criteria_mission_gap.py | Criteria-gap / mission-fit-gap route branch | ~330 | _enrich_criteria_gap_envelope, _enrich_mission_fit_gap_envelope |
roadmap_route_dispatch.py | v7 route-dispatch core + legacy v6 shim + close-deferred sweep | ~450 | _route_dispatch, _route_dispatch_v6_legacy, _sweep_close_deferred_gates |
roadmap_step0_menu.py | Step 0 raw-invocation menu mode | ~340 | _step_0_menu, _step_0_dispatch, _step_0_ask_user |
roadmap_step2_marker_resume.py | Step 2.5/2.6 mid-pipeline marker + section-close-commit resume | ~150 | _step_2_5_check_marker, _step_2_6_section_close_commit |
roadmap_redispatch_loop_detector.py | Flip-anomaly + redispatch-loop check wiring | ~150 | _check_flip_anomaly_for_target, _check_redispatch_loop |
roadmap_autopilot_cure_scratch.py | Scratch-dir path resolvers + work-subsection filters shared by every autopilot cure | ~140 | _plan_scratch_subdir, _work_subsections, _live_incomplete_work_subsections |
roadmap_autopilot_cure_gates.py | Cap-checked cure decision wrappers | ~590 | _AutopilotCureKind, _run_autopilot_cure_dispatch, _maybe_autopilot_deadlock_cure |
roadmap_redispatch_loop_cure.py | Redispatch-loop autopilot cure + review-plan loop guard | ~218 | _attempt_redispatch_loop_autopilot_cure, _review_plan_loop_guard |
roadmap_step3_auto_dispatch.py | Step 3 auto-dispatch + commit-push-halt handling + gate escalation | ~765 | _step_3_auto_dispatch, handle_commit_push_halt, _step_3_escalate |
roadmap_phase_emission_glue.py | subsection_phases feature-flag path: tp-dev applicability, phase-action emission | ~410 | _compute_tp_dev_applicability, _emit_phase_action, _build_dispatch_agent_inputs |
Work items
- Extract
roadmap_v7_serve_directives.py,roadmap_route_envelope_enrichment.py,roadmap_v7_cross_scope_block_wait.py,roadmap_grind_livelock_guards.py,roadmap_ledger_debt_enrichment.py,roadmap_criteria_mission_gap.py,roadmap_route_dispatch.py(the v7-path cluster) out ofroadmap/_legacy.py;roadmap/__init__.pyre-exports every moved name; fullscripts/plan_orchestrator/testssuite green; commit. Run the/tp-helpdesign-flag consult above BEFORE this work item’s commit lands; record the verdict in this section’s HISTORY. - Extract
roadmap_step0_menu.py,roadmap_step2_marker_resume.py,roadmap_redispatch_loop_detector.py,roadmap_autopilot_cure_scratch.py,roadmap_autopilot_cure_gates.py,roadmap_redispatch_loop_cure.py,roadmap_step3_auto_dispatch.py,roadmap_phase_emission_glue.py(the markdown-path moderate cluster) out ofroadmap/_legacy.py;roadmap/__init__.pyre-exports every moved name; full suite green; commit.
Items
- FIRST, before any extraction in this section: file a follow-up bug via /add-bug for the LEAK:algorithmic-duplication question flagged in the ‘Design flag’ note above (_enrich_route_envelope_for_execution vs _step_5_emit_focus structural parallelism) — per /tp-help opencode-F3 (Major, atam: tradeoff_point), the follow-up anchor must exist NOW, not only recorded in HISTORY at this section’s close, so the deferred unification question survives regardless of how this section’s close-time consult goes.