Project Roadmap & Milestones

Relevant source files

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

• ROADMAP.md
• PROJECTS.md
• infrastructure_planning/milestone_0_tasks.md
• infrastructure_planning/milestone_25_tasks.md
• infrastructure_planning/milestone_50_tasks.md
• copilot-instructions.md
• GAD.md

The NeuralDBG roadmap defines a structured path for the development of a causal inference engine for deep learning. The project is governed by strict progress gates and architectural principles designed to move from initial user validation to a hardened, compiler-aware MVP (Minimum Viable Product). The roadmap emphasizes "Hub & Spokes" architecture, where core business logic remains isolated from external infrastructure dependencies.

Development is divided into specific percentage-based milestones (25%, 50%, 75%, 90%, 95%), each serving as a "Hard Milestone Lock." At these points, development must stop until specific validation criteria—including user research (The Mom Test) and marketing metrics—are met.

Sources: ROADMAP.md:1-10, copilot-instructions.md:20-50, GAD.md:15-30

Project Organization and Architecture

The project follows a "Hub & Spokes" architectural principle to ensure modularity and reversibility of design decisions. This structure isolates the core causal inference engine from external tools like PyTorch, experiment trackers, and CI/CD pipelines.

Architectural Structure

Component	Responsibility	Relevant Files
Core (Hub)	Pure business logic, foundational data structures, and stable engine code.	neuraldbg.py
Adapters (Spokes)	External dependencies including APIs, Databases, and UI frameworks.	demo_vanishing_gradients.py, GitHub Actions
Infrastructure	CI/CD gates, hermetic Docker workspaces, and MLOps pipelines.	infrastructure_planning/

The following diagram illustrates the relationship between the stable core and the interchangeable external adapters:

This diagram shows the "Hub & Spokes" architecture where the core logic is protected from the noise of external dependency churn.

Sources: copilot-instructions.md:52-65, infrastructure_planning/milestone_0_tasks.md:65-80

Milestone Roadmap (MVP Phase)

The MVP phase is a 5-week schedule (Feb 25 - Mar 31, 2026) targeting 50% progress completion. Progress is calculated based on weighted components including core functionality (40%), test coverage (20%), and documentation (10%).

Phase 1: Core Validation (10% → 25%)

Focused on validating existing implementation against established criteria and achieving a baseline of 60% test coverage. Key tasks include adding unit tests for explaining exploding gradients and dead neurons, and verifying demo_vanishing_gradients.py.

Phase 2: Compiler-Aware Hardening (25% → 35%)

Ensures the engine survives torch.compile optimization. This requires validating that hooks persist after compilation and that no tensor inspection occurs in hot paths.

Phase 3: Demo & Documentation (35% → 45%)

Focuses on the inference flow documentation and creating clear failure scenarios for the demo script. This involves creating INFERENCE_FLOW.md to document causal compression algorithms.

Phase 4: Security & CI/CD (45% → 50%)

Hardens the project through security scans (bandit, safety) and ensures pre-commit hooks are enforced across all commits.

Sources: ROADMAP.md:13-68

Infrastructure and DevOps Milestones

Infrastructure tasks are generated at every milestone (10%, 25%, 50%, etc.) to ensure reliability and automation. These tasks are documented as Linear issues for tracking.

Milestone 0: Initial Setup

The goal of Milestone 0 is to establish the "Cloud CI/CD Gate," acting as an unbreakable digital bouncer for code quality.

Task	Description	ROI Estimation
Cross-Platform CI/CD	GitHub Actions running on Linux and Windows runners.	Saves ~2 hours/week
Experiment Tracking	MLflow/W&B integration for gradient tracking.	Saves ~3 hours/iteration
Dockerization	Standardized Dockerfile for PyTorch environments.	Saves ~4-5 hours onboarding

The sequence diagram demonstrates the CI/CD "Gate" concept where code is only merged if it passes automated quality and security checks.

Sources: infrastructure_planning/milestone_0_tasks.md:15-60, infrastructure_planning/milestone_25_tasks.md:5-25

Milestone 25: Reliability & Reproducibility

At 25% progress, focus shifts to enforcing standards through local hooks and hermetic environments.

• Pre-commit Hooks: Enforcement of black, isort, flake8, and bandit locally.
• Hermetic Testing: Running pytest within Docker to eliminate environment-specific errors.
• Windows Verification: PowerShell scripts to verify builds on Windows systems (Rule 17).

Sources: infrastructure_planning/milestone_25_tasks.md:1-35

Milestone 50: MLOps Integration

At 50% progress, focus moves to persistent history and data versioning.

• DVC Setup: Data Version Control for synthetic datasets used in debugging.
• MLflow Logging: Automated logging of SemanticEvent objects and causal hypotheses.
• Resource Profiling: Capturing memory spikes and GPU utilization during training failures.

Sources: infrastructure_planning/milestone_50_tasks.md:1-35

Validation and Progress Gates

The project strictly adheres to mandatory validation milestones. Development MUST stop at 25%, 50%, 75%, 90%, and 95% until specific criteria are met.

Milestone	Required Validation
25%	Mom Test follow-up (3+ users), Landing page metrics.
50%	Mom Test validation (5+ new users), Conversion metrics.
90%	Final Mom Test, Launch readiness verification.

Progress Scoring Methodology

NeuralDBG uses a pessimistic scoring methodology. If a feature is 50% done, it is scored at 30% to account for technical debt and documentation needs. A project is only 100% when:

1. Core features are working.
2. Test coverage is ≥ 60%.
3. Security scans pass (bandit, safety).
4. CI/CD pipeline is fully configured.

Sources: copilot-instructions.md:160-200, GAD.md:100-115

Project Roadmap Summary

The roadmap ensures that NeuralDBG matures from a research tool into a hardened engine. By prioritizing causal inference over simple metric tracking and enforcing strict validation gates, the project maintains high standards for technical accuracy and user value. The transition from MVP to post-MVP will only occur after the core training dynamics analysis is verified as reliable across deep architectures.

Sources: ROADMAP.md:70-85, PROJECTS.md:1-10