Engineering Practices & Agent Rules
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
This page outlines the operating discipline, non-negotiable rules, and architectural standards for developers and coding agents working within the regime-detection repository. The primary goal is to ensure deterministic replay, prevent future-data leakage, and maintain strict adherence to project specifications between V1 and V2 regime engine iterations. These rules serve as the authoritative guide for coding sessions and win on any conflict unless explicitly resolved.
The framework emphasizes high-integrity data handling, extensive validation at layer boundaries, and a "test-first" mentality to maintain the reliability of market regime classification. It incorporates automated enforcement through CI/CD pipelines and custom review rules defined for the Cubic review system.
Sources: AGENTS.md:1-8, cubic.yaml:5-15
Operating Rules for Agents
Coding agents must follow a set of strict protocols to ensure transparency and security. Agents are required to announce their intent before starting work, detailing the files touched and expected outputs. Security is paramount; no secrets or raw payloads should ever be committed or logged.
Workflow and Verification
The workflow is designed to be incremental and verified at every step. Agents must search the codebase before creating new functions and stop at every task boundary to commit and wait for confirmation.
The diagram above illustrates the standard task lifecycle for a coding agent within the repository.
Sources: AGENTS.md:10-25, scripts/validate_agents_md.py:10-20
Failure Mode Mitigation
To prevent common development pitfalls, specific counter-mechanisms are enforced:
| Failure Mode | Counter-Mechanism |
|---|---|
| Wire-first | Entry points must be touched first; signatures must be exercised end-to-end before completion. |
| One home per concept | Centralize utilities and data models; promote helpers rather than duplicating logic. |
| No patch-on-patch | Bugs require a failing test first; delete-before-add bias is encouraged. |
| No confident-wrong | External API claims must be verified via documentation lookups. |
| Real tests only | Internal code must not be mocked; external services use redacted real fixtures. |
Sources: AGENTS.md:27-65
Technical Standards & Quality Gates
The project maintains high standards for technical accuracy, particularly regarding data handling and versioning.
Data Integrity Rules
- UTC Persistence: All stored timestamps must use UTC with timezones. Naive datetimes are banned from storage and comparison.
- Quarantine Strategy: Malformed external data must be quarantined and logged row-by-row. A failure rate >1% triggers an immediate halt.
- Layer Validation: Every layer boundary must have validation, with source-specific models applied before normalization.
Sources: AGENTS.md:19-21, AGENTS.md:73-82
V2 Slice Review Guidelines
Reviewers must flag any V2 implementation that deviates from specific spec sections as a P1 violation. Critical checks include:
- Verbatim adherence to formulas (§4.2), weights (§4.3), and rules (§3.5).
- Prohibition of auto-labeling for HMM/GMM clusters; manual review is required.
- Verification that HMM/GMM outputs are used as evidence (
transition_score.score_components), not final labels. - Ensuring V3 features (e.g., ORCA, SRR, Transformers) are not introduced in V2 slices.
Sources: AGENTS.md:95-115
Automation & Tooling
The repository uses a suite of canonical commands for maintaining code hygiene and type safety. These are enforced both in AGENTS.md and CI workflows.
Canonical Commands
- Formatting:
python -m black --check src tests scripts - Linting:
python -m ruff check . - Type Checking:
python -m pyright - Testing:
python -m pytest -q -m "" -n 8 --cov=src --cov-report=term-missing --cov-fail-under=80
Sources: AGENTS.md:118-124, scripts/validate_agents_md.py:10-20
Dependency and Audit Tools
The project defines specific dependency groups in pyproject.toml for auditing and development:
- Audit Extra: Includes
pip-audit,pydeps,vulture,radon, anddeptry. - Dev Extra: Includes
black,pytest,ruff, andpyright.
Sources: pyproject.toml:27-42
Tech Debt Management
The project tracks technical debt through periodic audits. The primary areas of concern include large orchestrator modules, incomplete typing in evidence models, and the need for incremental Pyright enforcement.
Strategic Priorities
- Expand Pyright coverage beyond the current configuration-only check.
- Migrate plain dictionary payloads to typed evidence models.
- Decompose monolithic orchestrators like
profile_engine.pyand theAcquisitionStore. - Standardize fetch-mode invocation within a registry.
Sources: TECH_DEBT_AUDIT.md:10-30, TECH_DEBT_AUDIT.md:120-150
Conclusion
Adherence to these engineering practices is critical for the stability of the regime-detection engine. By combining strict agent protocols with automated quality gates and transparent tech debt tracking, the project ensures that regime classifications remain deterministic and reliable across all versions.
Sources: AGENTS.md:1-8, TECH_DEBT_AUDIT.md:5-10