okstra 0.155.0 → 0.157.0

package/runtime/python/okstra_ctl/schedule_semantics.py

@@ -22,20 +22,27 @@ _TASK_FIELDS = {
     "stages",
 }
 _STAGE_FIELDS = {"stageNumber", "title", "dependsOn", "stepCount"}
-_TASK_HEADING_RE = re.compile(
-    r"^###\s+(\d+-\d+)\.\s+(\S+)\s+—(?:\s+.*)?$", re.MULTILINE
-)
+# `### <n>. <human title>` — the heading is a title, not an identifier. The
+# task-id is a machine key; printing it as the reader's heading makes them parse
+# `nestjs-migration-nlpvibe-to-nestjs-and-org-standard-structure` to learn the
+# work is a NestJS migration. Blocks bind to At a Glance by their number.
+_TASK_HEADING_RE = re.compile(r"^###\s+(\d+)\.\s+(\S.*?)\s*$", re.MULTILINE)
 _WORK_BREAKDOWN_HEADER = ["Stage", "Title", "Steps", "Depends On", "Days"]
 _WORK_BREAKDOWN_SEPARATOR = ["---:", "---", "---:", "---", "---:"]
+# No `taskType`: it printed okstra's own phase name at a reader who has no
+# phases, and the per-task Status field already states the same thing in words.
 _AT_A_GLANCE_HEADER = [
-    "#", "Task ID", "Title", "Category", "Priority", "Effort", "Days",
-    "taskType", "Risk", "Phase",
+    "#", "Task ID", "Title", "Category", "Priority", "Effort", "Days", "Risk",
 ]
 _EFFORT_HEADER = ["Size", "Criteria", "Day(s)"]
 _EFFORT_SIZES = {"S", "M", "L", "XL", "XXL"}
 _DAY_NUMBER = r"\d+(?:\.\d+)?"
+# `(est)` marks a range the schedule derived from `step_count` rather than one
+# the plan stated. implementation-planning does not estimate duration, so every
+# range carries it today; the marker is what keeps that visible in the table
+# instead of in a footnote.
 _DAY_RANGE_RE = re.compile(
-    rf"^\s*({_DAY_NUMBER})\s*(?:~|-)\s*({_DAY_NUMBER})\s*$"
+    rf"^\s*({_DAY_NUMBER})\s*(?:~|-)\s*({_DAY_NUMBER})\s*(?:\(est\))?\s*$"
 )
 _EFFORT_TOTAL_RE = re.compile(
     rf"\*\*\d+\s+tasks\s+total\s*/\s*estimated\s+effort:\s*"
@@ -45,10 +52,15 @@ _EFFORT_TOTAL_RE = re.compile(
 _PLAIN_FENCE_RE = re.compile(
     r"^```[ \t]*$\n(.*?)^```[ \t]*$", re.MULTILINE | re.DOTALL
 )
+# A row is `[<TASK-ID> ]Stage <n>  <bar>` and nothing else. The bar's width IS
+# the duration — a trailing `days=` annotation restated the Work Breakdown's Days
+# column, and per-row `! crit` / `est` markers that were identical on every row
+# carried no information at all.
 _GANTT_ROW_RE = re.compile(
-    rf"^\s*(\S+)/S(\d+)\s+.*\bdays=({_DAY_NUMBER})~({_DAY_NUMBER})\s*$"
+    r"^\s*(?:(\S+)\s+)?Stage (\d+)\s+([█]*[░]*)\s*$"
 )
-_GANTT_STAGE_CANDIDATE_RE = re.compile(r"^\s*(\S+)/S(\d+)(?:\s|$)")
+_GANTT_STAGE_CANDIDATE_RE = re.compile(r"^\s*(?:(\S+)\s+)?Stage (\d+)(?:\s|$)")
+_GANTT_AXIS_RE = re.compile(r"^\s*Day:\s*(.+)$")
 _XXL_DAY_RANGE_RE = re.compile(rf"^\s*{_DAY_NUMBER}\s*-\s*$")
 _TASK_SUBSECTION_PREFIXES = (
     "**Problem**:",
@@ -58,6 +70,12 @@ _TASK_SUBSECTION_PREFIXES = (
     "**Rollback**:",
 )
 HALF_DAY = Decimal("0.5")
+# One column is half a day. A whole-day column cannot draw a 2.5-day stage, which
+# is how bars silently rounded away from the Work Breakdown they annotate.
+GANTT_COLUMN_DAYS = HALF_DAY
+# The axis may overshoot the work by less than one tick interval; more than that
+# is dead space that misreads as schedule length.
+_GANTT_AXIS_TICK_DAYS = Decimal("5")
 
 
 class ScheduleSemanticError(ValueError):
@@ -167,7 +185,8 @@ class _AtAGlanceRow:
 class _GanttRow:
     task_id: str
     stage_number: int
-    days: tuple[Decimal, Decimal]
+    filled_cells: int
+    open_cells: int
 
 
 class StageMapSelectionError(ValueError):
@@ -404,12 +423,12 @@ def load_schedule_selection(path: Path) -> tuple[SelectionTask, ...]:
 def _parse_dependencies(
     value: str, task_id: str, stage_number: int,
 ) -> tuple[tuple[tuple[int, bool], ...], str | None]:
-    if value == "—":
+    if value == "None":
         return (), None
     dependencies: list[tuple[int, bool]] = []
     for token in value.split(","):
         normalized = token.strip()
-        match = re.fullmatch(r"(\d+)( \(done\))?", normalized)
+        match = re.fullmatch(r"Stage (\d+)( \(done\))?", normalized)
         if match is None:
             return (), (
                 f"work breakdown: stage {task_id}/S{stage_number} has invalid "
@@ -577,7 +596,7 @@ def _parse_at_a_glance_table(
             task_id = cells[1] if len(cells) > 1 else "<unknown>"
             violations.append(
                 f"At a Glance: noncanonical row for task {task_id} "
-                "requires 10 columns"
+                "requires 8 columns"
             )
             continue
         effort_tokens = cells[5].split()
@@ -602,7 +621,7 @@ def _parse_at_a_glance_rows(
         if split_pipe_row(line) == _AT_A_GLANCE_HEADER
     ]
     if not header_indexes:
-        return [], ["At a Glance: missing canonical 10-column table"]
+        return [], ["At a Glance: missing canonical 8-column table"]
     rows: list[_AtAGlanceRow] = []
     violations: list[str] = []
     for header_index in header_indexes:
@@ -662,18 +681,26 @@ def _validate_at_a_glance_effort(
     missing_task_ids = {
         task.task_id for task in tasks if task.state == "missing"
     }
+    scheduled_task_ids = {
+        task.task_id for task in tasks if task.selected_stages
+    }
     violations: list[str] = []
     for row in glance_rows.values():
-        needs_planning = (
-            row.effort == "XXL" or row.task_id in missing_task_ids
-        )
-        if needs_planning:
+        if row.task_id in missing_task_ids:
             if row.days_text != "[NEEDS-PLANNING]":
                 violations.append(
-                    f"effort: {row.task_id} effort {row.effort} "
+                    f"effort: {row.task_id} has no planning report and "
                     "requires [NEEDS-PLANNING]"
                 )
             continue
+        if row.task_id not in scheduled_task_ids:
+            continue
+        if row.days is None:
+            violations.append(
+                f"effort: {row.task_id} requires a day range in Days — "
+                f"got {row.days_text!r}"
+            )
+            continue
         if row.effort not in effort_ranges:
             violations.append(
                 f"effort: {row.task_id} effort {row.effort} is absent from "
@@ -769,19 +796,23 @@ def _duplicate_heading_violations(
     headings: list[re.Match[str]],
 ) -> list[str]:
     violations: list[str] = []
-    for group, label in ((1, "phase-index"), (2, "task")):
-        values = [heading.group(group) for heading in headings]
-        duplicates = sorted({value for value in values if values.count(value) > 1})
-        for value in duplicates:
-            violations.append(
-                f"work breakdown: duplicate {label} heading {value}"
-            )
+    values = [heading.group(1) for heading in headings]
+    duplicates = sorted({value for value in values if values.count(value) > 1})
+    for value in duplicates:
+        violations.append(
+            f"work breakdown: duplicate task-index heading {value}"
+        )
     return violations
 
 
 def _task_section_blocks(
-    text: str,
+    text: str, ordered_task_ids: list[str],
 ) -> tuple[list[tuple[str, str]], list[str]]:
+    """Bind each `### <n>.` block to the n-th At a Glance row.
+
+    The heading carries a human title, so the task it belongs to comes from its
+    position rather than from an identifier printed at the reader.
+    """
     visible_text = _mask_fenced_text(text)
     headings = list(_TASK_HEADING_RE.finditer(visible_text))
     blocks: list[tuple[str, str]] = []
@@ -796,7 +827,13 @@ def _task_section_blocks(
         )
         if next_section is not None:
             end = heading.end() + next_section.start()
-        blocks.append((heading.group(2), visible_text[heading.end():end]))
+        position = int(heading.group(1))
+        task_id = (
+            ordered_task_ids[position - 1]
+            if 1 <= position <= len(ordered_task_ids)
+            else f"<no At a Glance row {position}>"
+        )
+        blocks.append((task_id, visible_text[heading.end():end]))
     return blocks, _duplicate_heading_violations(headings)
 
 
@@ -848,7 +885,10 @@ def _validate_task_section_coverage(
 def _extract_breakdown_rows(
     text: str,
 ) -> tuple[list[_BreakdownRow], list[str], list[tuple[str, str]]]:
-    blocks, violations = _task_section_blocks(text)
+    glance_rows, _ = _parse_at_a_glance_rows(text)
+    blocks, violations = _task_section_blocks(
+        text, [row.task_id for row in glance_rows]
+    )
     if violations:
         return [], violations, blocks
     rows: list[_BreakdownRow] = []
@@ -986,7 +1026,10 @@ def _expected_selected_stage_days(
         glance_row = glance_rows.get(task.task_id)
         if glance_row is None or not task.selected_stages:
             continue
-        total = effort_ranges.get(glance_row.effort)
+        # XXL has no finite upper bound in the sizing table, so an XXL task is
+        # sized by its own decomposition: the row's own range is the total the
+        # stages divide up.
+        total = effort_ranges.get(glance_row.effort) or glance_row.days
         if total is None:
             continue
         stages = {stage.stage_number: stage for stage in task.stages}
@@ -1053,11 +1096,17 @@ def _parse_effort_total(text: str) -> tuple[Decimal, Decimal] | None:
     )
 
 
-def _finite_task_ranges(
+def _scheduled_task_ranges(
     effort_ranges: dict[str, tuple[Decimal, Decimal] | None],
     tasks: tuple[SelectionTask, ...],
     glance_rows: dict[str, _AtAGlanceRow],
 ) -> list[tuple[Decimal, Decimal]]:
+    """Every in-scope task's day range, including XXL.
+
+    An XXL row has no finite range in the sizing table; it carries its own,
+    summed from its stages. Dropping those rows is what produced a `0.0 ~ 0.0`
+    Effort sum on a schedule whose stages added up to weeks of work.
+    """
     ranges: list[tuple[Decimal, Decimal]] = []
     for task in tasks:
         if task.state == "missing" or not task.selected_stages:
@@ -1065,7 +1114,7 @@ def _finite_task_ranges(
         glance_row = glance_rows.get(task.task_id)
         if glance_row is None:
             continue
-        day_range = effort_ranges.get(glance_row.effort)
+        day_range = effort_ranges.get(glance_row.effort) or glance_row.days
         if day_range is not None:
             ranges.append(day_range)
     return ranges
@@ -1079,8 +1128,8 @@ def _validate_effort_total(
 ) -> list[str]:
     actual = _parse_effort_total(text)
     if actual is None:
-        return ["effort: missing finite Effort sum"]
-    required = _sum_day_ranges(_finite_task_ranges(
+        return ["effort: missing Effort sum"]
+    required = _sum_day_ranges(_scheduled_task_ranges(
         effort_ranges, tasks, glance_rows
     ))
     if actual == required:
@@ -1090,27 +1139,6 @@ def _validate_effort_total(
     ]
 
 
-def _validate_decomposition_notice(
-    text: str,
-    tasks: tuple[SelectionTask, ...],
-    glance_rows: dict[str, _AtAGlanceRow],
-) -> list[str]:
-    has_unplanned_work = (
-        any(task.state == "missing" for task in tasks)
-        or any(row.effort == "XXL" for row in glance_rows.values())
-    )
-    if not has_unplanned_work:
-        return []
-    executive_summary = _section_body(
-        text, "## Executive Summary", 2
-    ).partition("### Effort Sizing Criteria")[0]
-    if "requires further decomposition" in executive_summary.lower():
-        return []
-    return [
-        "effort: Executive Summary requires further decomposition notice"
-    ]
-
-
 def _validate_effort_semantics(
     text: str,
     tasks: tuple[SelectionTask, ...],
@@ -1131,14 +1159,17 @@ def _validate_effort_semantics(
     violations.extend(_validate_effort_total(
         text, effort_ranges, tasks, glance_rows
     ))
-    violations.extend(_validate_decomposition_notice(
-        text, tasks, glance_rows
-    ))
     return violations
 
 
+def _sole_scheduled_task_id(tasks: tuple[SelectionTask, ...]) -> str:
+    """The one task an unqualified `S<n>` row can only mean; '' when ambiguous."""
+    scheduled = [task.task_id for task in tasks if task.selected_stages]
+    return scheduled[0] if len(scheduled) == 1 else ""
+
+
 def _parse_gantt_rows(
-    text: str,
+    text: str, tasks: tuple[SelectionTask, ...],
 ) -> tuple[list[_GanttRow] | None, list[str]]:
     visible_text = _mask_fenced_text(text)
     headings = list(re.finditer(
@@ -1153,6 +1184,7 @@ def _parse_gantt_rows(
     section = _raw_section_body(text, "## Gantt Chart", 2)
     if section is None:
         return None, []
+    sole_task_id = _sole_scheduled_task_id(tasks)
     rows: list[_GanttRow] = []
     violations: list[str] = []
     for fence in _PLAIN_FENCE_RE.finditer(section):
@@ -1161,26 +1193,110 @@ def _parse_gantt_rows(
             if match is None:
                 candidate = _GANTT_STAGE_CANDIDATE_RE.match(line)
                 if candidate is not None:
+                    label = candidate.group(1) or sole_task_id or "<task>"
                     violations.append(
-                        "Gantt: malformed Gantt stage row "
-                        f"{candidate.group(1)}/S{candidate.group(2)} requires "
-                        "canonical days=<lower>~<upper> syntax"
+                        f"Gantt: malformed Gantt stage row {label} Stage "
+                        f"{candidate.group(2)} — a row is a label and a bar, "
+                        "with nothing after it"
                     )
                 continue
-            task_id = match.group(1)
             stage_number = int(match.group(2))
+            task_id = match.group(1) or sole_task_id
+            if not task_id:
+                violations.append(
+                    f"Gantt: row S{stage_number} omits its task-id, which is "
+                    "only allowed when exactly one task is scheduled"
+                )
+                continue
+            bar = match.group(3)
             rows.append(_GanttRow(
                 task_id=task_id,
                 stage_number=stage_number,
-                days=_ordered_day_range(
-                    Decimal(match.group(3)),
-                    Decimal(match.group(4)),
-                    f"Gantt {task_id}/S{stage_number}",
-                ),
+                filled_cells=bar.count("█"),
+                open_cells=bar.count("░"),
             ))
     return rows, violations
 
 
+def _cells_for_days(days: Decimal) -> Decimal:
+    return days / GANTT_COLUMN_DAYS
+
+
+def _breakdown_days(
+    breakdown_rows: list[_BreakdownRow],
+) -> dict[tuple[str, int], tuple[Decimal, Decimal]]:
+    days: dict[tuple[str, int], tuple[Decimal, Decimal]] = {}
+    counts: dict[tuple[str, int], int] = {}
+    for row in breakdown_rows:
+        key = (row.task_id, row.stage_number)
+        counts[key] = counts.get(key, 0) + 1
+        if row.days is not None:
+            days[key] = row.days
+    return {key: value for key, value in days.items() if counts[key] == 1}
+
+
+def _validate_gantt_geometry(
+    rows: list[_GanttRow], breakdown_rows: list[_BreakdownRow],
+) -> list[str]:
+    """A bar's width must be the duration the Work Breakdown gives that stage.
+
+    The bar is compared against the Days column itself rather than a `days=`
+    label beside it: an annotation restating the table can agree with the label
+    while disagreeing with the plan.
+    """
+    days = _breakdown_days(breakdown_rows)
+    violations: list[str] = []
+    for row in rows:
+        day_range = days.get((row.task_id, row.stage_number))
+        if day_range is None:
+            continue
+        lower, upper = day_range
+        expected_filled = _cells_for_days(lower)
+        expected_open = _cells_for_days(upper - lower)
+        if (
+            expected_filled != row.filled_cells
+            or expected_open != row.open_cells
+        ):
+            violations.append(
+                f"Gantt: bar for {row.task_id} Stage {row.stage_number} draws "
+                f"{row.filled_cells}█+{row.open_cells}░ but Work Breakdown says "
+                f"{_format_day_range(day_range)} days, which is "
+                f"{expected_filled:.0f}█+{expected_open:.0f}░ at "
+                f"{GANTT_COLUMN_DAYS} day per column"
+            )
+    return violations
+
+
+def _validate_gantt_axis(
+    text: str, rows: list[_GanttRow], breakdown_rows: list[_BreakdownRow],
+) -> list[str]:
+    section = _raw_section_body(text, "## Gantt Chart", 2)
+    if section is None or not rows:
+        return []
+    ticks: list[Decimal] = []
+    for fence in _PLAIN_FENCE_RE.finditer(section):
+        for line in fence.group(1).splitlines():
+            axis = _GANTT_AXIS_RE.match(line)
+            if axis is not None:
+                ticks = [
+                    Decimal(token) for token in re.findall(r"\d+", axis.group(1))
+                ]
+    if not ticks:
+        return []
+    days = _breakdown_days(breakdown_rows)
+    span = sum(
+        (days[(row.task_id, row.stage_number)][1]
+         for row in rows if (row.task_id, row.stage_number) in days),
+        Decimal("0"),
+    )
+    if span and ticks[-1] > span + _GANTT_AXIS_TICK_DAYS:
+        return [
+            f"Gantt: axis runs to day {ticks[-1]} but the schedule spans at "
+            f"most {span} days — trim the axis to the work"
+        ]
+    return []
+
+
 def _validate_gantt_coverage(
     rows: list[_GanttRow], tasks: tuple[SelectionTask, ...],
 ) -> list[str]:
@@ -1207,28 +1323,6 @@ def _validate_gantt_coverage(
     return violations
 
 
-def _validate_gantt_days(
-    gantt_rows: list[_GanttRow],
-    breakdown_rows: list[_BreakdownRow],
-) -> list[str]:
-    breakdown: dict[tuple[str, int], list[_BreakdownRow]] = {}
-    for row in breakdown_rows:
-        key = (row.task_id, row.stage_number)
-        breakdown.setdefault(key, []).append(row)
-    violations: list[str] = []
-    for row in gantt_rows:
-        key = (row.task_id, row.stage_number)
-        matches = breakdown.get(key, [])
-        if len(matches) != 1 or matches[0].days is None:
-            continue
-        if row.days != matches[0].days:
-            violations.append(
-                f"Gantt: Gantt days for {row.task_id}/S{row.stage_number} "
-                f"require {_format_day_range(matches[0].days)}"
-            )
-    return violations
-
-
 def validate_schedule_semantics(
     text: str, selection_path: Path,
 ) -> list[str]:
@@ -1239,11 +1333,12 @@ def validate_schedule_semantics(
     try:
         rows, violations = _validate_work_breakdowns(text, tasks)
         violations.extend(_validate_effort_semantics(text, tasks, rows))
-        gantt_rows, gantt_violations = _parse_gantt_rows(text)
+        gantt_rows, gantt_violations = _parse_gantt_rows(text, tasks)
         violations.extend(gantt_violations)
         if gantt_rows is not None:
             violations.extend(_validate_gantt_coverage(gantt_rows, tasks))
-            violations.extend(_validate_gantt_days(gantt_rows, rows))
+            violations.extend(_validate_gantt_geometry(gantt_rows, rows))
+            violations.extend(_validate_gantt_axis(text, gantt_rows, rows))
         return violations
     except ScheduleSemanticError as exc:
         return [str(exc)]

package/runtime/python/okstra_ctl/stage_map.py

@@ -47,6 +47,38 @@ class StageMapSnapshot:
     stages: list[dict[str, Any]]
 
 
+# `stepwiseExecution` is what the stage DOES; the other three are what becomes
+# true when it is finished. A schedule carrying only the latter reads as an
+# analysis of a plan rather than the plan itself.
+_PLANNING_STAGE_NARRATIVE_FIELDS = (
+    "sliceValue",
+    "stepwiseExecution",
+    "acceptance",
+    "exitContract",
+)
+_PLANNING_TASK_NARRATIVE_FIELDS = (
+    "rollbackStrategy",
+    "validationChecklist",
+    "crossProjectDependencies",
+    "dependencyMigrationRisk",
+    "recommendedOption",
+)
+
+
+@dataclass(frozen=True)
+class PlanningDetail:
+    """The planning report's narrative rows, carried to a schedule verbatim.
+
+    The Stage Map says which stages exist; these rows say what each one accepts,
+    how it rolls back and what validates it. A consumer without them has to
+    re-summarise a half-megabyte report by hand, which is where a schedule's
+    rollback, verification and risk sections drift away from the plan.
+    """
+
+    stage_narratives: dict[int, dict[str, Any]]
+    task_narratives: dict[str, Any]
+
+
 class StageMapError(Exception):
     def __init__(
         self,
@@ -209,7 +241,14 @@ def parse_stage_map_text(
         raise StageMapError("stage_map", str(exc), source_plan_path) from exc
 
 
-def parse_stage_map_file(path: Path) -> list[StageMapStage]:
+def _parse_stage_map_markdown(path: Path) -> list[StageMapStage]:
+    """Parse the `## 5.5 Stage Map` table out of a schema-v1 report body.
+
+    Private on purpose: a v2 report has no such section, so a caller reaching
+    for this directly gets `section '## 5.5 Stage Map' is missing` on every
+    modern report. `parse_stage_map_file` is the entry point — it reads the
+    structured sidecar when there is one and falls back here when there is not.
+    """
     resolved = Path(path).resolve()
     try:
         text = resolved.read_text(encoding="utf-8")
@@ -218,6 +257,169 @@ def parse_stage_map_file(path: Path) -> list[StageMapStage]:
     return parse_stage_map_text(text, source_plan_path=str(resolved))
 
 
+def _require_data_positive_int(
+    value: Any, field: str, row_number: int, source_plan_path: str,
+) -> int:
+    if not isinstance(value, int) or isinstance(value, bool) or value < 1:
+        raise StageMapError(
+            "stage_map",
+            f"structured Stage Map row {row_number} has invalid {field} {value!r}",
+            source_plan_path,
+        )
+    return value
+
+
+def _require_data_text(
+    value: Any, field: str, row_number: int, source_plan_path: str,
+) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise StageMapError(
+            "stage_map",
+            f"structured Stage Map row {row_number} has invalid {field} {value!r}",
+            source_plan_path,
+        )
+    return value
+
+
+def _parse_data_stage_map_row(
+    value: Any, row_number: int, source_plan_path: str,
+) -> StageMapStage:
+    if not isinstance(value, dict):
+        raise StageMapError(
+            "stage_map",
+            f"structured Stage Map row {row_number} must be an object",
+            source_plan_path,
+        )
+    stage_number = _require_data_positive_int(
+        value.get("stage"), "stage", row_number, source_plan_path
+    )
+    step_count = _require_data_positive_int(
+        value.get("stepCount"), "stepCount", row_number, source_plan_path
+    )
+    title = _require_data_text(
+        value.get("title"), "title", row_number, source_plan_path
+    )
+    depends_on = _require_data_text(
+        value.get("dependsOn"), "dependsOn", row_number, source_plan_path
+    )
+    exit_summary = _require_data_text(
+        value.get("exitContractSummary"),
+        "exitContractSummary",
+        row_number,
+        source_plan_path,
+    )
+    return StageMapStage(
+        stage_number,
+        title,
+        _parse_depends_on(depends_on.strip(), row_number, source_plan_path),
+        step_count,
+        exit_summary,
+    )
+
+
+def _parse_schema_v2_stage_map(
+    data: dict[str, Any], source_plan_path: str,
+) -> list[StageMapStage]:
+    planning = data.get("implementationPlanning")
+    stage_map = planning.get("stageMap") if isinstance(planning, dict) else None
+    if not isinstance(stage_map, list) or not stage_map:
+        raise StageMapError(
+            "stage_map",
+            "structured report requires a non-empty implementationPlanning.stageMap",
+            source_plan_path,
+        )
+    stages = [
+        _parse_data_stage_map_row(value, row_number, source_plan_path)
+        for row_number, value in enumerate(stage_map, start=1)
+    ]
+    _validate_stage_numbers(stages, source_plan_path)
+    return stages
+
+
+def parse_stage_map_file(markdown_path: Path) -> list[StageMapStage]:
+    """Read one report's Stage Map, whichever schema wrote it.
+
+    THE entry point for every caller. A schema-v2 report carries the stage map
+    in its `.data.json` sidecar and has no `## 5.5 Stage Map` section at all, so
+    a caller that parses the markdown directly works only against v1 reports —
+    which is how v2 support landed on one call site and left five reading a
+    section that modern reports do not have.
+    """
+    resolved = Path(markdown_path).resolve()
+    data_path = resolved.with_suffix(".data.json")
+    if not data_path.exists():
+        return _parse_stage_map_markdown(resolved)
+    try:
+        data = json.loads(data_path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
+        raise StageMapError("stage_map", str(exc), str(data_path)) from exc
+    if not isinstance(data, dict):
+        raise StageMapError(
+            "stage_map", "structured report must be an object", str(data_path)
+        )
+    if data.get("schemaVersion") != "2.0":
+        return _parse_stage_map_markdown(resolved)
+    return _parse_schema_v2_stage_map(data, str(data_path))
+
+
+def _planning_section(markdown_path: Path) -> dict[str, Any]:
+    """The schema-v2 sidecar's `implementationPlanning` block, `{}` for v1."""
+    data_path = Path(markdown_path).resolve().with_suffix(".data.json")
+    if not data_path.exists():
+        return {}
+    try:
+        data = json.loads(data_path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
+        raise StageMapError("stage_map", str(exc), str(data_path)) from exc
+    if not isinstance(data, dict) or data.get("schemaVersion") != "2.0":
+        return {}
+    planning = data.get("implementationPlanning")
+    return planning if isinstance(planning, dict) else {}
+
+
+def _stage_narratives(value: Any) -> dict[int, dict[str, Any]]:
+    narratives: dict[int, dict[str, Any]] = {}
+    if not isinstance(value, list):
+        return narratives
+    for row in value:
+        if not isinstance(row, dict):
+            continue
+        number = row.get("stage")
+        if not isinstance(number, int) or isinstance(number, bool):
+            continue
+        narratives[number] = {
+            field: row[field]
+            for field in _PLANNING_STAGE_NARRATIVE_FIELDS
+            if field in row
+        }
+    return narratives
+
+
+def load_planning_detail(markdown_path: Path) -> PlanningDetail:
+    """Read one report's narrative rows; empty for a schema-v1 report."""
+    planning = _planning_section(markdown_path)
+    if not planning:
+        return PlanningDetail({}, {})
+    return PlanningDetail(
+        _stage_narratives(planning.get("stages")),
+        {
+            field: planning[field]
+            for field in _PLANNING_TASK_NARRATIVE_FIELDS
+            if field in planning
+        },
+    )
+
+
+def merge_planning_detail(
+    records: list[dict[str, Any]], detail: PlanningDetail,
+) -> list[dict[str, Any]]:
+    """Join each stage's narrative onto its `stage_map_records` row."""
+    return [
+        {**record, **detail.stage_narratives.get(record["stage_number"], {})}
+        for record in records
+    ]
+
+
 def stage_map_records(stages: Iterable[StageMapStage]) -> list[dict[str, Any]]:
     return [
         {