Megatron Impact Mapper

Hard Gate

1. user-supplied mapping
2. a known rule in branch-alignment.md
3. a repository-local document or commit that states the mapping clearly

Core Rules

• Treat

  MindSpeed branch <-> Megatron branch

  alignment as mandatory for strict migration mode.
• Use only official repositories as the source of truth for first-pass analysis.
• Distinguish between

  strict migration mode

  and

  exploration mode

  .
• For

  megatron main

  , prefer exploration mode unless the user explicitly chooses a compatible MindSpeed baseline for comparison.
• Separate three outcomes: already adapted, likely adaptable but missing, not worth adapting now.
• Do not stop at "candidate paths" when a feature is clearly migration-worthy. Break the feature into implementation targets that correspond to the upstream implementation units.

Workflow

1. Resolve the MindSpeed branch.
2. Resolve the mapped Megatron baseline branch.
3. Compare the baseline against the target Megatron branch or change-set.
4. For each relevant Megatron event, search for corresponding MindSpeed modules, wrappers, configs, launch paths, and tests.
5. Map upstream implementation units onto local implementation targets.
6. Produce an impact report with confidence, rationale, and implementation scope.
7. Allow handoff to migration generation only for high-confidence impact items.

Required Output

impact_report

{
  "mindspeed_branch": "master",
  "megatron_base_branch": "core_v0.12.1",
  "megatron_target_branch": "core_v0.15.3",
  "mode": "strict",
  "items": [
    {
      "event_title": "Add feature X",
      "status": "likely_missing",
      "confidence": 0.78,
      "candidate_paths": ["mindspeed/path_a.py", "mindspeed/path_b.py"],
      "reason": "Short factual rationale",
      "primary_commit": "sha1",
      "upstream_changed_files": ["megatron/path_a.py", "megatron/path_b.py"],
      "implementation_targets": [
        {
          "name": "Expose config on MindSpeed side",
          "source_unit": "Expose new config flag",
          "candidate_paths": ["mindspeed/arguments.py"],
          "required_change": "Add argument or YAML surface",
          "confidence": 0.82
        },
        {
          "name": "Port runtime behavior",
          "source_unit": "Add runtime behavior",
          "candidate_paths": ["mindspeed/training.py", "mindspeed/core/training.py"],
          "required_change": "Recreate the training shutdown logic locally",
          "confidence": 0.67
        }
      ],
      "covered_units": ["Expose config on MindSpeed side"],
      "missing_units": ["Port runtime behavior"]
    }
  ]
}

Decision Rules

• If alignment is unresolved: report only.
• If alignment is resolved but implementation targets are weakly supported: report plus implementation plan, not direct edits.
• If alignment and implementation targets are both high confidence: allow migration patch generation.
• If an item has only one touched local file but the upstream event clearly spans multiple implementation units, mark the uncovered units explicitly instead of pretending the feature is fully mapped.

References

• Read branch-alignment.md before doing any strict migration work.
• Read mindspeed-focus-areas.md when searching for candidate adaptation paths.
• Run resolve_branch_alignment.py to deterministically classify a branch pair as

  strict

  ,

  exploration

  , or

  unresolved

  .
• Run scan_mindspeed_paths.py to search the official MindSpeed repository on a specific branch for likely adaptation points using feature names, file names, symbols, or config keys.
• Run map_implementation_targets.py to convert upstream implementation units into local MindSpeed implementation targets before patch generation.
• Hand off only approved items to $megatron-migration-generator.