Tech Debt Audit & Future Migrations

Relevant source files

The following files were used as context for generating this wiki page:

• TECH_DEBT_AUDIT.md
• AGENTS.md
• scripts/publish_canonical_snapshot.py
• scripts/run_v2_shadow_ab_gate.py
• scripts/audit_step1_harness.py
• pyproject.toml
• scripts/validate_agents_md.py

Introduction

The Tech Debt Audit and Future Migrations framework represents a systematic approach to maintaining the health and integrity of the regime-detection repository. As of May 2026, the project has transitioned to a unified V1 and V2 engine, necessitating rigorous checks to prevent regression in V1 frozen replay models while enabling the expansion of V2 capabilities. The audit process focuses on typed model boundaries, data acquisition artifact contracts, and the decoupling of large orchestration modules.

The primary objective is to manage the coupled relationship between the runtime classifier, data acquisition systems, and operational scripts. By identifying high-priority implementation tasks—such as expanding pyright coverage and hardening evidence model typing—the project aims to reduce the "blast radius" of changes to persistent state and acquisition stores.

Sources: TECH_DEBT_AUDIT.md:1-25, pyproject.toml:1-15

Core Mental Model & Product Boundaries

The project architecture is divided into three distinct products, each with its own technical debt profiles and migration requirements.

Product	Components	Primary Debt/Risk
Runtime Classifier	MarketContext, Features, Axis Series, Pydantic models	Typed contract drift, untyped dict payloads in timeline outputs.
Data Acquisition	Event sources, Fetch scripts, Artifact Store	Large orchestration modules, lack of retry logic in live fetches.
Operational Scripts	Calibration, Walk-forward gates, Shadow checks	Runtime product surface used as "scripts," monkeypatching-heavy.

Sources: TECH_DEBT_AUDIT.md:27-38, scripts/run_v2_shadow_ab_gate.py:1-20

Product Relationship Flow

The following diagram illustrates how data flows between the products and where audit boundaries are enforced.

Critical Tech Debt Findings (P1 Severity)

High-priority issues currently being addressed involve type enforcement and evidence model integrity.

Type System Enforcement

Currently, pyright coverage is limited to src/regime_detection/config.py in CI, leading to over 700 errors across the rest of the codebase. This allows typed contract drift to accumulate in runtime, data, and script modules.
Sources: TECH_DEBT_AUDIT.md:65-72, pyproject.toml:76-85, scripts/validate_agents_md.py:15-30

Evidence Model Hardening

Evidence models are partially typed, with many inheriting from RootModel[dict[str, Any]]. This prevents pyright from enforcing field contracts and leads to runtime validation errors when tests pass empty or malformed evidence shapes.
Sources: TECH_DEBT_AUDIT.md:73-86, scripts/run_v2_shadow_ab_gate.py:59-100

Feature Store & Axis Builders

The FeatureStore registry relies on a string-keyed dict[str, Any] bus for final assembly, increasing the risk of late-caught errors. Additionally, while axis implementation moved out of axis_series.py, the new axis_builders/series.py remains a large, highly-coupled module.
Sources: TECH_DEBT_AUDIT.md:87-104

V2 Migration & Shadow Gates

The transition to V2 features (such as HMM/GMM clustering and network fragility) is governed by strict "Shadow A/B" gates to ensure V1 stability.

Shadow A/B Gate Protocol

The §9.3 60-session shadow A/B gate simulates live performance by classifying sessions in both v1-mode and full-v2-mode.

• V1 Fields: Must stay identical (Zero diffs allowed).
• V2 Fields: Expected to differ as new enrichments are activated.

Artifact Canonicalization

To solve manifest-sha-drift, a publication workflow has been established to ensure data integrity across environments.

The Canonicalization Workflow

1. Read: Load Parquet bytes.
2. Sort: Sort rows ascending by all sortable columns.
3. Strip: Remove schema metadata (e.g., pandas round-trip headers).
4. Standardize: Apply Snappy compression and microsecond timestamp coercion.
5. Hash: Recompute SHA256 and update manifest.

Sources: scripts/publish_canonical_snapshot.py:50-100, scripts/publish_canonical_snapshot.py:130-150

Audit Instrumentation (Step 1 Harness)

The audit_step1_harness.py provides a fail-open mechanism to capture provenance without blocking business logic. It tracks:

• Runner Identity: Name, repo root, and git head.
• Manifest Provenance: Path and materialization status.
• Bypass Classes: Identifies when standard manifest paths are circumvented (e.g., CLI overrides).
• Cross-Worktree Drift: Computes SHA256 for all source files in src/regime_detection and src/regime_data_fetch.

Sources: scripts/audit_step1_harness.py:1-60

Future Migration Roadmap

The following tasks are prioritized for the next development cycle to resolve open debt:

1. Task 1: Profiler Hook Fix - Repair timing hooks broken by the axis-series split.
2. Task 2: Typed Evidence Slice - Replace dict fallbacks with explicit Pydantic models.
3. Task 3: Feature-Store Typing - Move from dict[str, Any] to a typed intermediate state for feature assembly.
4. Task 4: Fetch-Mode Invocation - Move dispatch logic into the FETCH_MODE_REGISTRY.
5. Task 5: Pyright Ratchet - Incrementally expand strict type checking across the src/ directory.

Sources: TECH_DEBT_AUDIT.md:144-200

Summary

The regime-detection system is currently in a state of high functional health but carries significant technical debt in its type system and module coupling. The implementation of V2 shadow gates and the Step 1 Audit Harness provides the necessary safety nets for ongoing migrations. Success in future cycles depends on the successful transition from loose dict-based evidence to a strictly typed architecture, ensuring the stability of both V1 frozen replays and new V2 capabilities.