cs249r_book/tinytorch/tests/milestones/API.md

Milestone System API

Source of Truth

tito.commands.milestone.MILESTONE_SCRIPTS is the canonical milestone table. It defines IDs, names, required modules, scripts, descriptions, and historical context.

tests/milestones/milestone_tracker.py is a compatibility layer for older test hooks. It imports MILESTONE_SCRIPTS rather than maintaining a separate milestone taxonomy.

State Files

The current CLI state lives under .tito/:

• .tito/progress.json: module progress, including completed_modules
• .tito/milestones.json: milestone readiness and completion state

Legacy code should not write milestone state outside the project .tito/ directory.

Public Compatibility Functions

check_module_export(module_name: str, console=None) -> dict

Marks a completed module in .tito/progress.json, checks whether any milestones are newly ready, writes .tito/milestones.json, and returns:

{
    "newly_unlocked": ["01"],
    "messages": ["Milestone ready to run ..."]
}

show_progress()

Prints milestone readiness based on .tito/progress.json and .tito/milestones.json.

list_tests()

Prints ready milestone run commands, such as:

tito milestone run 03

CLI Integration

Current user-facing commands are implemented in tito/commands/milestone.py:

tito milestone list
tito milestone status
tito milestone info 03
tito milestone run 03

tito module complete also checks milestone readiness after recording module completion. That code should use the canonical MILESTONE_SCRIPTS table, not a duplicated list of requirements.

Adding or Changing Milestones

1. Update MILESTONE_SCRIPTS.
2. Add or rename scripts under milestones/.
3. Update test_milestones_smoke.py for import/model construction coverage.
4. Update test_milestones_run.py for release-run coverage.
5. Update milestone READMEs and Quarto pages.

Keep command examples singular: use tito milestone.