@ngocsangairvds/vsaf 3.2.13 → 3.2.15

package/tools/vds-scripts/progress_report_orchestrator/src/progress_report_orchestrator/pipeline/report.py

@@ -1,1256 +0,0 @@
-"""Structural report generator — Phase 5 of the progress pipeline.
-
-Produces a ProgressReport from a completed list of FRAssessments and
-renders it to either Markdown or JSON, saved under
-``output_dir/<project_key>/YYYY-MM-DD[.md|.json]``.
-
-Covers spec §3 report structure:
-  sections 1-6 (FR-level assessment table)
-  executive summary
-  risk register
-"""
-
-from __future__ import annotations
-
-import json
-from datetime import UTC, datetime
-from pathlib import Path
-from typing import Literal
-
-import structlog
-
-from progress_report_orchestrator.models.analysis import FRAssessment, RepoAnalysis
-from progress_report_orchestrator.models.report import (
-    ClusterAnalysis,
-    DimensionCoverageRecord,
-    FRDelta,
-    ProgressReport,
-    ReportDelta,
-    ReportSection,
-    RiskItem,
-)
-from progress_report_orchestrator.models.topology import FRModule, ProjectTopology
-from progress_report_orchestrator.recommendations import (
-    RecommendationContext,
-    RecommendationEngine,
-)
-
-log = structlog.get_logger(__name__)
-
-
-# ---------------------------------------------------------------------------
-# Risk identification
-# ---------------------------------------------------------------------------
-
-
-def _identify_risks(a: FRAssessment) -> list[RiskItem]:
-    """Derive RiskItems from a completed FRAssessment."""
-    risks: list[RiskItem] = []
-
-    if not a.service_exists:
-        risks.append(
-            RiskItem(
-                fr_id=a.fr_id,
-                dimension="service_existence",
-                severity="high",
-                description=(
-                    f"{a.fr_id}: No service implementation found in cache "
-                    f"(repos: {[r.repo_slug for r in a.repo_analyses] or 'none'})."
-                ),
-            )
-        )
-
-    if not a.doc_chain_complete:
-        risks.append(
-            RiskItem(
-                fr_id=a.fr_id,
-                dimension="doc_coverage",
-                severity="medium",
-                description=(
-                    f"{a.fr_id}: Incomplete documentation chain — "
-                    "one or more of BRD / PRD / SRS / Architecture docs is missing."
-                ),
-            )
-        )
-
-    if not a.brd_traced:
-        risks.append(
-            RiskItem(
-                fr_id=a.fr_id,
-                dimension="brd_traceability",
-                severity="medium",
-                description=(
-                    f"{a.fr_id}: BRD traceability missing — no BRD section entry with a valid line range found."
-                ),
-            )
-        )
-
-    if a.code_activity_score < 30:
-        severity = "low" if a.code_activity_score >= 10 else "medium"
-        risks.append(
-            RiskItem(
-                fr_id=a.fr_id,
-                dimension="code_activity",
-                severity=severity,
-                description=(
-                    f"{a.fr_id}: Low code activity score ({a.code_activity_score:.1f}/100) over the last 30 days."
-                ),
-            )
-        )
-
-    if a.test_coverage_score < 20:
-        risks.append(
-            RiskItem(
-                fr_id=a.fr_id,
-                dimension="test_coverage",
-                severity="medium",
-                description=(f"{a.fr_id}: Low test coverage score ({a.test_coverage_score:.1f}/100)."),
-            )
-        )
-
-    # Dim 7 — architecture compliance (only present in full mode)
-    if a.architecture_compliance is not None and a.architecture_compliance < 50:
-        severity = "high" if a.architecture_compliance < 25 else "medium"
-        risks.append(
-            RiskItem(
-                fr_id=a.fr_id,
-                dimension="architecture_compliance",
-                severity=severity,
-                description=(
-                    f"{a.fr_id}: Low architecture compliance score "
-                    f"({a.architecture_compliance:.1f}/100) — hexagonal/clean architecture "
-                    "violations detected.  Review domain/infrastructure layer separation."
-                ),
-            )
-        )
-
-    # Dim 8 — endpoint coverage (only present in full mode)
-    if a.endpoint_coverage is not None and a.endpoint_coverage < 60:
-        severity = "high" if a.endpoint_coverage < 30 else "medium"
-        risks.append(
-            RiskItem(
-                fr_id=a.fr_id,
-                dimension="endpoint_coverage",
-                severity=severity,
-                description=(
-                    f"{a.fr_id}: Low endpoint coverage score "
-                    f"({a.endpoint_coverage:.1f}/100) — SRS-specified endpoints are not "
-                    "all implemented.  Check use-case specifications against controller mappings."
-                ),
-            )
-        )
-
-    return risks
-
-
-# ---------------------------------------------------------------------------
-# Report assembly
-# ---------------------------------------------------------------------------
-
-
-def build_report(
-    assessments: list[FRAssessment],
-    topology: ProjectTopology,
-    run_id: str,
-    project_key: str,
-    bmad_repo: str,
-) -> ProgressReport:
-    """Assemble a ProgressReport from completed FRAssessments."""
-    overall = sum(a.overall_score for a in assessments) / len(assessments) if assessments else 0.0
-
-    # Build FR module lookup for recommendation context
-    fr_module_map: dict[str, FRModule] = {m.fr_id: m for m in topology.fr_modules}
-    engine = RecommendationEngine()
-
-    sections: list[ReportSection] = []
-    all_risks: list[RiskItem] = []
-
-    for a in assessments:
-        risks = _identify_risks(a)
-        fr_module = fr_module_map.get(a.fr_id)
-        ctx = RecommendationContext(
-            assessment=a,
-            fr=fr_module,
-        )
-        recs = engine.generate(ctx)
-        sections.append(
-            ReportSection(
-                fr_id=a.fr_id,
-                assessment=a,
-                risks=risks,
-                recommendations=recs,
-            )
-        )
-        all_risks.extend(risks)
-
-    return ProgressReport(
-        run_id=run_id,
-        project_key=project_key,
-        bmad_repo=bmad_repo,
-        generated_at=datetime.now(UTC).isoformat(),
-        overall_score=round(overall, 2),
-        sections=sections,
-        risks=all_risks,
-    )
-
-
-# ---------------------------------------------------------------------------
-# TSK-D.1: Delta computation
-# ---------------------------------------------------------------------------
-
-
-def compute_delta(
-    assessments: list[FRAssessment],
-    current_overall: float,
-    previous_scores: dict[str, float],
-    previous_run_id: str | None,
-) -> ReportDelta | None:
-    """Compute per-FR and overall deltas between this run and the previous one.
-
-    Returns ``None`` when *previous_scores* is empty (first run or no prior
-    completed run found in the DB).
-    """
-    if not previous_scores:
-        return None
-
-    current_ids = {a.fr_id for a in assessments}
-    prev_ids = set(previous_scores)
-
-    fr_deltas: list[FRDelta] = [
-        FRDelta(
-            fr_id=a.fr_id,
-            previous_score=previous_scores[a.fr_id],
-            current_score=a.overall_score,
-            change=round(a.overall_score - previous_scores[a.fr_id], 2),
-        )
-        for a in assessments
-        if a.fr_id in previous_scores
-    ]
-
-    prev_overall = round(sum(previous_scores.values()) / len(previous_scores), 2)
-    overall_change = round(current_overall - prev_overall, 2)
-
-    # TSK-M.3: Populate regression / improvement buckets (FR-Q9)
-    regressed = [d for d in fr_deltas if d.change <= REGRESSION_MINOR]
-    improved = [d for d in fr_deltas if d.change >= -REGRESSION_MINOR]
-    critical = [d for d in regressed if d.change <= REGRESSION_CRITICAL]
-
-    return ReportDelta(
-        previous_run_id=previous_run_id,
-        previous_overall=prev_overall,
-        current_overall=current_overall,
-        overall_change=overall_change,
-        fr_deltas=fr_deltas,
-        new_frs=sorted(current_ids - prev_ids),
-        removed_frs=sorted(prev_ids - current_ids),
-        regressed_frs=regressed,
-        improved_frs=improved,
-        critical_regressions=critical,
-    )
-
-
-# ---------------------------------------------------------------------------
-# Markdown renderer
-# ---------------------------------------------------------------------------
-
-_SEVERITY_ICON: dict[str, str] = {"high": "🔴", "medium": "🟡", "low": "🟢"}
-_SEVERITY_SORT: dict[str, int] = {"high": 0, "medium": 1, "low": 2}
-
-
-def _severity_icon(severity: str) -> str:
-    return _SEVERITY_ICON.get(severity, "⚪")
-
-
-def _score_bar(score: float, width: int = 10) -> str:
-    filled = min(int(score / (100 / width)), width)
-    return "█" * filled + "░" * (width - filled)
-
-
-def _render_trend_section(delta: ReportDelta) -> list[str]:
-    """Render the '## Trend vs Previous Run' markdown section (TSK-D.1)."""
-    lines: list[str] = ["## Trend vs Previous Run", ""]
-
-    if delta.overall_change is not None and delta.previous_overall is not None:
-        arrow = "↑" if delta.overall_change > 0.0 else ("↓" if delta.overall_change < 0.0 else "→")
-        change_str = f"{arrow} {abs(delta.overall_change):.1f}"
-        lines += [
-            "| Metric | Previous | Current | Change |",
-            "|--------|----------|---------|--------|",
-            f"| Overall score | {delta.previous_overall:.1f} | {delta.current_overall:.1f} | {change_str} |",
-            "",
-        ]
-
-    improved = sorted([d for d in delta.fr_deltas if d.change > 1.0], key=lambda d: -d.change)
-    regressed = sorted([d for d in delta.fr_deltas if d.change < -1.0], key=lambda d: d.change)
-
-    if improved or regressed:
-        lines += ["**FR Score Changes:**", ""]
-        for d in improved:
-            lines.append(f"- ↑ `{d.fr_id}`: {d.previous_score:.1f} → {d.current_score:.1f} (+{d.change:.1f})")
-        for d in regressed:
-            lines.append(f"- ↓ `{d.fr_id}`: {d.previous_score:.1f} → {d.current_score:.1f} ({d.change:.1f})")
-        lines.append("")
-
-    if delta.new_frs:
-        lines.append(f"**New FRs (not in previous run):** {', '.join(f'`{f}`' for f in delta.new_frs)}")
-        lines.append("")
-    if delta.removed_frs:
-        lines.append(f"**Removed FRs:** {', '.join(f'`{f}`' for f in delta.removed_frs)}")
-        lines.append("")
-
-    # TSK-M.4: Regression subsections (FR-Q9)
-    if delta.critical_regressions:
-        lines += ["### 🔴 Critical Regressions (Δ ≤ −15)", ""]
-        for d in delta.critical_regressions:
-            lines.append(f"- `{d.fr_id}`: {d.previous_score:.1f} → {d.current_score:.1f} (Δ {d.change:.1f})")
-        lines.append("")
-
-    critical_ids = {d.fr_id for d in delta.critical_regressions}
-    minor_only = [d for d in delta.regressed_frs if d.fr_id not in critical_ids]
-    if minor_only:
-        lines += ["### 🟡 Minor Regressions (−15 < Δ ≤ −5)", ""]
-        for d in minor_only:
-            lines.append(f"- `{d.fr_id}`: {d.previous_score:.1f} → {d.current_score:.1f} (Δ {d.change:.1f})")
-        lines.append("")
-
-    if delta.improved_frs:
-        lines += ["### 🟢 Improvements (Δ ≥ +5)", ""]
-        for d in delta.improved_frs:
-            lines.append(f"- `{d.fr_id}`: {d.previous_score:.1f} → {d.current_score:.1f} (Δ +{d.change:.1f})")
-        lines.append("")
-
-    lines += ["---", ""]
-    return lines
-
-
-# ---------------------------------------------------------------------------
-# TSK-J.3: Dimension coverage + score distribution (shared by markdown & JSON)
-# ---------------------------------------------------------------------------
-
-
-_COVERAGE_THRESHOLD: float = 60.0  # numeric dim pass threshold
-
-
-def _dim_status(pass_rate: float) -> str:
-    """Map pass_rate in [0,1] to a status label for DimensionCoverageRecord."""
-    if pass_rate >= 0.8:
-        return "green"
-    if pass_rate > 0.5:
-        return "yellow"
-    return "red"
-
-
-def _compute_dimension_coverage(assessments: list[FRAssessment]) -> list[DimensionCoverageRecord]:
-    """Compute per-dimension dual-metric (avg score + pass rate) across all FRs.
-
-    Boolean dims (service, docs, brd): pass = True; avg_score = pass_rate * 100.
-    Numeric dims (activity, test_coverage): pass = score >= 60; avg_score = mean.
-    LLM dims (architecture, endpoint): only included when ≥ 1 FR has non-None value;
-      total_count = count of non-None values.
-
-    Returns records in _DIMENSION_LABELS order for stable rendering.
-    """
-    n = len(assessments)
-    if n == 0:
-        return []
-
-    records: list[DimensionCoverageRecord] = []
-
-    # Boolean dims
-    for key, label in [
-        ("service_exists", _DIMENSION_LABELS["service_exists"]),
-        ("doc_chain_complete", _DIMENSION_LABELS["doc_chain_complete"]),
-        ("brd_traced", _DIMENSION_LABELS["brd_traced"]),
-    ]:
-        pass_count = sum(1 for a in assessments if getattr(a, key))
-        pass_rate = round(pass_count / n, 3)
-        records.append(
-            DimensionCoverageRecord(
-                key=key,
-                label=label,
-                avg_score=round(pass_rate * 100, 2),
-                pass_count=pass_count,
-                total_count=n,
-                pass_rate=pass_rate,
-                status=_dim_status(pass_rate),
-            )
-        )
-
-    # Numeric dims
-    for key, attr, label in [
-        ("code_activity_avg", "code_activity_score", _DIMENSION_LABELS["code_activity_avg"]),
-        ("test_coverage_avg", "test_coverage_score", _DIMENSION_LABELS["test_coverage_avg"]),
-    ]:
-        scores = [getattr(a, attr) for a in assessments]
-        avg = round(sum(scores) / n, 2)
-        pass_count = sum(1 for s in scores if s >= _COVERAGE_THRESHOLD)
-        pass_rate = round(pass_count / n, 3)
-        records.append(
-            DimensionCoverageRecord(
-                key=key,
-                label=label,
-                avg_score=avg,
-                pass_count=pass_count,
-                total_count=n,
-                pass_rate=pass_rate,
-                status=_dim_status(pass_rate),
-            )
-        )
-
-    # LLM dims (optional — only when data present)
-    for key, attr, label in [
-        ("architecture_compliance_avg", "architecture_compliance", _DIMENSION_LABELS["architecture_compliance_avg"]),
-        ("endpoint_coverage_avg", "endpoint_coverage", _DIMENSION_LABELS["endpoint_coverage_avg"]),
-    ]:
-        values = [getattr(a, attr) for a in assessments if getattr(a, attr) is not None]
-        if not values:
-            continue
-        avg = round(sum(values) / len(values), 2)
-        pass_count = sum(1 for v in values if v >= _COVERAGE_THRESHOLD)
-        pass_rate = round(pass_count / len(values), 3)
-        records.append(
-            DimensionCoverageRecord(
-                key=key,
-                label=label,
-                avg_score=avg,
-                pass_count=pass_count,
-                total_count=len(values),
-                pass_rate=pass_rate,
-                status=_dim_status(pass_rate),
-            )
-        )
-
-    return records
-
-
-def _coverage_records_to_dict(records: list[DimensionCoverageRecord]) -> dict[str, float]:
-    """Convert DimensionCoverageRecord list to flat dict for JSON backward compatibility.
-
-    Boolean dims emit pass_rate (in [0,1]); numeric/LLM dims emit avg_score.
-    Keys match the pre-TSK-L.4 format produced by the old _compute_dimension_coverage.
-    """
-    _BOOL_KEYS = {"service_exists", "doc_chain_complete", "brd_traced"}
-    return {rec.key: round(rec.pass_rate, 3) if rec.key in _BOOL_KEYS else round(rec.avg_score, 2) for rec in records}
-
-
-def _compute_score_distribution(assessments: list[FRAssessment]) -> dict[str, int]:
-    """Bucket FRs into 🟢 high (≥60), 🟡 medium (30-60), 🔴 low (<30)."""
-    high = medium = low = 0
-    for a in assessments:
-        if a.overall_score >= 60:
-            high += 1
-        elif a.overall_score >= 30:
-            medium += 1
-        else:
-            low += 1
-    return {"high": high, "medium": medium, "low": low}
-
-
-# ---------------------------------------------------------------------------
-# TSK-L.1: Valence gap heuristic — NOT statistical bimodality. See ADR-Q7.
-# ---------------------------------------------------------------------------
-
-MIN_N_FOR_VALENCE_GAP: int = 10
-MIN_PEAK_SHARE: float = 0.25
-
-# ---------------------------------------------------------------------------
-# TSK-M.1: Trend regression thresholds (FR-Q9)
-# Negative values so bucket comparisons read as: d.change <= REGRESSION_CRITICAL
-# ---------------------------------------------------------------------------
-
-REGRESSION_CRITICAL: int = -15  # change ≤ -15 → critical regression
-REGRESSION_MINOR: int = -5  # -15 < change ≤ -5 → minor regression
-
-
-def _check_quality_gate(
-    score: float,
-    *,
-    fail_under: float | None,
-    has_critical_regression: bool,
-    fail_on_regression: bool,
-) -> int:
-    """Return exit code for quality gate: 0 (pass/no gates) or 2 (gate FAILED).
-
-    Exit 2 distinguishes gate failures from runtime errors (exit 1).
-    Callers should ``raise typer.Exit(code)`` when code == 2.  FR-Q10.
-    """
-    if fail_under is not None and score < fail_under:
-        return 2
-    if fail_on_regression and has_critical_regression:
-        return 2
-    return 0
-
-
-def _detect_valence_gap(distribution: dict[str, int]) -> bool:
-    """Return True when score distribution has a valence gap.
-
-    Rules (all must hold):
-      1. total_frs >= 10 (minimum-N — below this, claim is statistically meaningless)
-      2. medium == 0
-      3. high > 0 AND low > 0
-      4. min(high, low) / total >= 0.25 (dominance guard)
-
-    This is a UX heuristic for two-population detection, NOT statistical
-    bimodality. See ADR-Q7 for rationale and terminology decision.
-    """
-    high = distribution.get("high", 0)
-    medium = distribution.get("medium", 0)
-    low = distribution.get("low", 0)
-    total = high + medium + low
-    if total < MIN_N_FOR_VALENCE_GAP:
-        return False
-    if medium != 0:
-        return False
-    if high == 0 or low == 0:
-        return False
-    return min(high, low) / total >= MIN_PEAK_SHARE
-
-
-# Human-readable labels for dimension_coverage keys (matches order in _compute_dimension_coverage)
-_DIMENSION_LABELS: dict[str, str] = {
-    "service_exists": "Service existence",
-    "doc_chain_complete": "Doc chain complete",
-    "brd_traced": "BRD traced",
-    "code_activity_avg": "Code activity (avg)",
-    "test_coverage_avg": "Test coverage (avg)",
-    "architecture_compliance_avg": "Architecture compliance (avg)",
-    "endpoint_coverage_avg": "Endpoint coverage (avg)",
-}
-
-
-# ---------------------------------------------------------------------------
-# TSK-L.6: Valence-gap cluster stratification
-# ---------------------------------------------------------------------------
-
-# Dimension names for blocker analysis — match RiskItem.dimension naming convention.
-_BLOCKER_DIMS: dict[str, str] = {
-    "service_existence": "service_exists",
-    "doc_coverage": "doc_chain_complete",
-    "brd_traceability": "brd_traced",
-}
-_BLOCKER_NUMERIC: dict[str, str] = {
-    "code_activity": "code_activity_score",
-    "test_coverage": "test_coverage_score",
-}
-
-
-def _stratify_bimodal(
-    assessments: list[FRAssessment],
-    recommendations_by_fr: dict[str, list],
-) -> dict[str, ClusterAnalysis]:
-    """Stratify FRs into high (≥60) and low (<30) score clusters.
-
-    Returns dict with ``"high"`` and ``"low"`` ClusterAnalysis entries.
-    Each cluster's dominant_blocker is the dimension with the lowest
-    pass-rate within that population (threshold = _COVERAGE_THRESHOLD for
-    numeric dims, True for boolean dims).
-    """
-    high_group = [a for a in assessments if a.overall_score >= 60]
-    low_group = [a for a in assessments if a.overall_score < 30]
-
-    def _blocker(group: list[FRAssessment]) -> str:
-        if not group:
-            return ""
-        n = len(group)
-        pass_rates: dict[str, float] = {}
-        for dim_name, attr in _BLOCKER_DIMS.items():
-            pass_rates[dim_name] = sum(1 for a in group if getattr(a, attr)) / n
-        for dim_name, attr in _BLOCKER_NUMERIC.items():
-            pass_rates[dim_name] = sum(1 for a in group if getattr(a, attr) >= _COVERAGE_THRESHOLD) / n
-        return min(pass_rates, key=pass_rates.__getitem__)
-
-    def _top_rec_fr(group: list[FRAssessment]) -> str | None:
-        best_score = -1.0
-        best_fr: str | None = None
-        for a in group:
-            for rec in recommendations_by_fr.get(a.fr_id, []):
-                if rec.impact_score > best_score:
-                    best_score = rec.impact_score
-                    best_fr = a.fr_id
-        return best_fr
-
-    return {
-        "high": ClusterAnalysis(
-            label="high",
-            fr_ids=[a.fr_id for a in high_group],
-            avg_score=round(sum(a.overall_score for a in high_group) / len(high_group), 2) if high_group else 0.0,
-            dominant_blocker=_blocker(high_group),
-            top_recommendation_fr=_top_rec_fr(high_group),
-        ),
-        "low": ClusterAnalysis(
-            label="low",
-            fr_ids=[a.fr_id for a in low_group],
-            avg_score=round(sum(a.overall_score for a in low_group) / len(low_group), 2) if low_group else 0.0,
-            dominant_blocker=_blocker(low_group),
-            top_recommendation_fr=_top_rec_fr(low_group),
-        ),
-    }
-
-
-_BOOL_DIM_KEYS: frozenset[str] = frozenset({"service_exists", "doc_chain_complete", "brd_traced"})
-
-
-# ---------------------------------------------------------------------------
-# TSK-L.8: Unicode sparkline helper
-# ---------------------------------------------------------------------------
-
-_SPARK_CHARS = "▁▂▃▄▅▆▇█"  # U+2581 – U+2588
-
-
-def _render_sparkline(values: list[float], max_value: float = 100.0) -> str:
-    """Render a unicode sparkline from a list of values.
-
-    Returns ``"—"`` when fewer than 2 values are present (no trend to show).
-    Clamps negative values to 0 before scaling.
-    """
-    if len(values) < 2:
-        return "—"
-    n = len(_SPARK_CHARS) - 1
-    return "".join(_SPARK_CHARS[min(n, int(round(max(0.0, v) / max_value * n)))] for v in values)
-
-
-_STATUS_ICON: dict[str, str] = {"green": "🟢", "yellow": "🟡", "red": "🔴"}
-
-
-def _render_dimension_coverage(
-    coverage: list[DimensionCoverageRecord],
-    trend_data: dict[str, list[float]] | None = None,
-) -> list[str]:
-    """Render the Dimension Coverage markdown table (5-column dual-metric, TSK-L.5/L.8).
-
-    Columns: Dimension | Avg Score | Pass Rate (≥60) | Status | Trend
-    Boolean dims: avg_score = pass_rate*100 shown as percentage;
-    numeric/LLM dims: avg_score shown as X.X/100 and pass_rate shown as X/Y (Z%).
-    Trend column shows a unicode sparkline when ≥2 historical values exist, else ``—``.
-    """
-    if not coverage:
-        return []
-    lines: list[str] = [
-        "### Dimension Coverage",
-        "",
-        "| Dimension | Avg Score | Pass Rate (≥60) | Status | Trend |",
-        "|:----------|----------:|----------------:|:------:|:-----:|",
-    ]
-    for rec in coverage:
-        icon = _STATUS_ICON.get(rec.status, "⚪")
-        if rec.key in _BOOL_DIM_KEYS:
-            pct = int(round(rec.pass_rate * 100))
-            avg_display = f"{pct}%"
-            rate_display = f"{rec.pass_count}/{rec.total_count} ({pct}%)"
-        else:
-            avg_display = f"{rec.avg_score:.1f}/100"
-            rate_pct = int(round(rec.pass_rate * 100))
-            rate_display = f"{rec.pass_count}/{rec.total_count} ({rate_pct}%)"
-        history = (trend_data or {}).get(rec.key, [])
-        spark = _render_sparkline(history)
-        lines.append(f"| {rec.label} | {avg_display} | {rate_display} | {icon} | {spark} |")
-    lines.append("")
-    return lines
-
-
-def _render_dimension_coverage_phase3(coverage: list[DimensionCoverageRecord]) -> list[str]:
-    """Render the Phase 3 compatible 2-column Dimension Coverage table.
-
-    Used by mode='standard' to maintain byte-identical output vs the Phase 3 baseline.
-    Format: | Dimension | Value |
-    Boolean dims: "{pct}% ({pct}/100)"; numeric dims: "{avg:.1f}/100"
-    """
-    if not coverage:
-        return []
-    lines: list[str] = [
-        "### Dimension Coverage",
-        "",
-        "| Dimension | Value |",
-        "|-----------|-------|",
-    ]
-    for rec in coverage:
-        if rec.key in _BOOL_DIM_KEYS:
-            pct = int(round(rec.pass_rate * 100))
-            value = f"{pct}% ({pct}/100)"
-        else:
-            value = f"{rec.avg_score:.1f}/100"
-        lines.append(f"| {rec.label} | {value} |")
-    lines.append("")
-    return lines
-
-
-def _render_score_distribution(distribution: dict[str, int], total: int) -> list[str]:
-    """Render the ## Score Distribution markdown table with 🟢🟡🔴 tiers."""
-    if total == 0:
-        return []
-    high = distribution.get("high", 0)
-    medium = distribution.get("medium", 0)
-    low = distribution.get("low", 0)
-    return [
-        "### Score Distribution",
-        "",
-        "| Tier | Threshold | FRs | Share |",
-        "|------|-----------|-----|-------|",
-        f"| 🟢 High | ≥ 60 | {high} | {high / total * 100:.0f}% |",
-        f"| 🟡 Medium | 30 – 60 | {medium} | {medium / total * 100:.0f}% |",
-        f"| 🔴 Low | < 30 | {low} | {low / total * 100:.0f}% |",
-        "",
-    ]
-
-
-# ---------------------------------------------------------------------------
-# TSK-J.1: FR × Dimension heatmap
-# ---------------------------------------------------------------------------
-
-
-def _render_heatmap(assessments: list[FRAssessment]) -> str:
-    """Render a markdown FR × Dimension heatmap table.
-
-    Boolean dimensions use ✅/❌; numeric dimensions show rounded values;
-    ``None`` (structural-mode skipped) shows ``N/A``.
-    """
-    if not assessments:
-        return ""
-
-    lines: list[str] = [
-        "## Dimension Heatmap",
-        "",
-        "| FR | Service | Doc Chain | BRD | Code Activity | Test Coverage | Arch | Endpoints |",
-        "|----|---------|-----------|-----|---------------|---------------|------|-----------|",
-    ]
-    for a in assessments:
-        arch = f"`{a.architecture_compliance:.0f}`" if a.architecture_compliance is not None else "N/A"
-        ep = f"`{a.endpoint_coverage:.0f}`" if a.endpoint_coverage is not None else "N/A"
-        lines.append(
-            f"| {a.fr_id} "
-            f"| {'✅' if a.service_exists else '❌'} "
-            f"| {'✅' if a.doc_chain_complete else '❌'} "
-            f"| {'✅' if a.brd_traced else '❌'} "
-            f"| `{a.code_activity_score:.0f}` "
-            f"| `{a.test_coverage_score:.0f}` "
-            f"| {arch} "
-            f"| {ep} |"
-        )
-    return "\n".join(lines)
-
-
-# ---------------------------------------------------------------------------
-# TSK-J.2: Per-repo health summary
-# ---------------------------------------------------------------------------
-
-
-def _render_repo_health(assessments: list[FRAssessment]) -> str:
-    """Render a markdown per-repo health table, deduplicating shared repos.
-
-    Health indicator:
-      🟢 test_files / (java_files + ts_files) >= 0.3
-      🔴 ratio < 0.1 (or no source files at all)
-      🟡 otherwise
-    """
-    seen: set[str] = set()
-    repos_ordered: list[RepoAnalysis] = []
-    for a in assessments:
-        for repo in a.repo_analyses:
-            if repo.repo_slug not in seen:
-                seen.add(repo.repo_slug)
-                repos_ordered.append(repo)
-
-    if not repos_ordered:
-        return ""
-
-    lines: list[str] = [
-        "## Repository Health",
-        "",
-        "| Repository | Java | TS | Tests | Ratio | Health |",
-        "|------------|------|----|-------|-------|--------|",
-    ]
-    for repo in repos_ordered:
-        total_files = repo.java_files + repo.ts_files
-        ratio = repo.test_files / total_files if total_files > 0 else 0.0
-        if ratio >= 0.3:
-            health = "🟢"
-        elif ratio < 0.1:
-            health = "🔴"
-        else:
-            health = "🟡"
-        lines.append(
-            f"| `{repo.repo_slug}` "
-            f"| {repo.java_files} "
-            f"| {repo.ts_files} "
-            f"| {repo.test_files} "
-            f"| `{ratio:.2f}` "
-            f"| {health} |"
-        )
-    return "\n".join(lines)
-
-
-def _render_exec_mode(report: ProgressReport) -> str:
-    """Render exec mode: ≤20 non-blank lines — score + FR count + top risks (FR-Q11)."""
-    high = sum(1 for r in report.risks if r.severity == "high")
-    medium = sum(1 for r in report.risks if r.severity == "medium")
-    total = len(report.sections)
-    lines: list[str] = [
-        f"# {report.project_key} — Score: {report.overall_score:.1f}/100",
-        "",
-        f"FRs assessed: {total} | 🔴 High risks: {high} | 🟡 Medium risks: {medium}",
-        "",
-    ]
-    all_recs = sorted(
-        (rec for sec in report.sections for rec in sec.recommendations),
-        key=lambda r: r.impact_score,
-        reverse=True,
-    )
-    for i, rec in enumerate(all_recs[:3], 1):
-        lines.append(f"{i}. [{rec.dimension}] {rec.summary}")
-    return "\n".join(lines)
-
-
-def _render_summary_mode(report: ProgressReport) -> str:
-    """Render summary mode: ≤100 non-blank lines — header + distribution + FR table (FR-Q11)."""
-    assessments = [sec.assessment for sec in report.sections]
-    distribution = _compute_score_distribution(assessments)
-    total = len(assessments)
-    high = distribution.get("high", 0)
-    medium = distribution.get("medium", 0)
-    low = distribution.get("low", 0)
-    high_risks = sum(1 for r in report.risks if r.severity == "high")
-    med_risks = sum(1 for r in report.risks if r.severity == "medium")
-    lines: list[str] = [
-        f"# Progress Report — {report.project_key}",
-        "",
-        f"**Generated**: {report.generated_at}  ",
-        f"**Run ID**: `{report.run_id}`  ",
-        "",
-        "## Executive Summary",
-        "",
-        "| Metric | Value |",
-        "|--------|-------|",
-        f"| FRs assessed | {total} |",
-        f"| Overall score | **{report.overall_score:.1f} / 100** |",
-        f"| 🔴 High risks | {high_risks} |",
-        f"| 🟡 Medium risks | {med_risks} |",
-        "",
-        "### Score Distribution",
-        "",
-        "| Tier | FRs | Share |",
-        "|------|-----|-------|",
-        f"| 🟢 High (≥ 60) | {high} | {high / total * 100:.0f}% |" if total else "| 🟢 High (≥ 60) | 0 | 0% |",
-        f"| 🟡 Medium (30–60) | {medium} | {medium / total * 100:.0f}% |"
-        if total
-        else "| 🟡 Medium (30–60) | 0 | 0% |",
-        f"| 🔴 Low (< 30) | {low} | {low / total * 100:.0f}% |" if total else "| 🔴 Low (< 30) | 0 | 0% |",
-        "",
-        "## FR Overview",
-        "",
-        "| FR | Score | Service | Top Risk |",
-        "|----|-------|---------|----------|",
-    ]
-    for sec in report.sections:
-        a = sec.assessment
-        svc = "✅" if a.service_exists else "❌"
-        top_risk = sec.risks[0].description[:60] + "…" if sec.risks else "—"
-        lines.append(f"| {a.fr_id} | {a.overall_score:.1f} | {svc} | {top_risk} |")
-    return "\n".join(lines)
-
-
-def render_markdown(
-    report: ProgressReport,
-    trend_data: dict[str, list[float]] | None = None,
-    mode: str = "full",
-) -> str:
-    """Render a ProgressReport to a markdown string.
-
-    Args:
-        report: The completed progress report.
-        trend_data: Optional pre-fetched dimension trend history mapping
-            ``DimensionCoverageRecord.key`` to a list of historical avg scores
-            (oldest first). Pass ``None`` (default) when no DB is available;
-            the Trend column will render ``—`` for all dimensions.
-        mode: Progressive disclosure tier — "exec" (≤20 lines), "summary" (≤100 lines),
-            "standard" (Phase 3 byte-identical, default), "full" (all Phase 4 sections).
-    """
-    if mode == "exec":
-        return _render_exec_mode(report)
-    if mode == "summary":
-        return _render_summary_mode(report)
-
-    lines: list[str] = []
-
-    high = sum(1 for r in report.risks if r.severity == "high")
-    medium = sum(1 for r in report.risks if r.severity == "medium")
-    total_recs = sum(len(sec.recommendations) for sec in report.sections)
-
-    lines += [
-        f"# Progress Report — {report.project_key}",
-        "",
-        f"**Generated**: {report.generated_at}  ",
-        f"**Run ID**: `{report.run_id}`  ",
-        f"**Source**: `{report.bmad_repo}`  ",
-        "",
-        "---",
-        "",
-        "## Executive Summary",
-        "",
-        "| Metric | Value |",
-        "|--------|-------|",
-        f"| FRs assessed | {len(report.sections)} |",
-        f"| Overall score | **{report.overall_score:.1f} / 100** |",
-        f"| 🔴 High risks | {high} |",
-        f"| 🟡 Medium risks | {medium} |",
-        f"| Recommendations | {total_recs} |",
-        "",
-    ]
-
-    # Top-3 actionable items — cross-FR, sorted by impact_score descending
-    all_recs = sorted(
-        (rec for sec in report.sections for rec in sec.recommendations),
-        key=lambda r: r.impact_score,
-        reverse=True,
-    )
-    top3 = all_recs[:3]
-    if top3:
-        lines += ["### Top 3 Actionable Items", ""]
-        for i, rec in enumerate(top3, 1):
-            lines.append(f"{i}. **[{rec.dimension}]** {rec.summary} _(+{rec.impact_score:.1f} pts)_")
-        lines.append("")
-
-    # --- TSK-J.3a/b: Dimension coverage + score distribution ---
-    assessments = [sec.assessment for sec in report.sections]
-    coverage = _compute_dimension_coverage(assessments)
-    if mode == "full":
-        coverage_lines = _render_dimension_coverage(coverage, trend_data)
-    else:
-        coverage_lines = _render_dimension_coverage_phase3(coverage)
-    if coverage_lines:
-        lines += coverage_lines
-
-    distribution = _compute_score_distribution(assessments)
-    dist_lines = _render_score_distribution(distribution, len(assessments))
-    if dist_lines:
-        lines += dist_lines
-
-    # --- TSK-L.2 + TSK-L.7: Valence gap callout + stratified cluster sub-reports (full only) ---
-    if mode == "full" and _detect_valence_gap(distribution):
-        high_n = distribution.get("high", 0)
-        low_n = distribution.get("low", 0)
-        lines += [
-            "> **⚠ Bimodal distribution detected**",
-            ">",
-            f"> Score splits into high-performers ({high_n} FRs ≥ 60) and low-performers ({low_n} FRs < 30) with no medium tier.",
-            ">",
-            "> **Remediation**: Stratify the analysis by service-exists before",
-            "> interpreting dimension averages. The mean hides the split.",
-            "",
-        ]
-        # TSK-L.7: cluster sub-reports
-        recs_by_fr: dict[str, list] = {sec.fr_id: sec.recommendations for sec in report.sections}
-        clusters = _stratify_bimodal(assessments, recs_by_fr)
-        for label, icon, cluster in [
-            ("high", "🟢", clusters["high"]),
-            ("low", "🔴", clusters["low"]),
-        ]:
-            if not cluster.fr_ids:
-                continue
-            top_fr_note = f" | Top rec: `{cluster.top_recommendation_fr}`" if cluster.top_recommendation_fr else ""
-            lines += [
-                f"### {icon} {label.capitalize()}-Cluster Analysis",
-                "",
-                f"**FRs ({len(cluster.fr_ids)}):** {', '.join(f'`{f}`' for f in cluster.fr_ids)}",
-                f"**Avg score:** {cluster.avg_score:.1f}/100 | **Dominant blocker:** `{cluster.dominant_blocker}`{top_fr_note}",
-                "",
-            ]
-
-    # --- TSK-J.1: Dimension heatmap (cross-FR overview) ---
-    heatmap_md = _render_heatmap(assessments)
-    if heatmap_md:
-        lines += ["---", "", heatmap_md, ""]
-
-    # --- TSK-J.2: Per-repo health summary ---
-    repo_health_md = _render_repo_health(assessments)
-    if repo_health_md:
-        lines += ["---", "", repo_health_md, ""]
-
-    lines += [
-        "---",
-        "",
-        "## FR Assessments",
-        "",
-    ]
-
-    # --- Trend section (TSK-D.1) ---
-    if report.delta is not None:
-        lines += _render_trend_section(report.delta)
-
-    for sec in report.sections:
-        a = sec.assessment
-        lines += [
-            f"### {a.fr_id}",
-            "",
-            f"**Score**: `{a.overall_score:.1f}/100` `[{_score_bar(a.overall_score)}]`",
-            "",
-            "| # | Dimension | Status |",
-            "|---|-----------|--------|",
-            f"| 1 | Service existence | {'✅' if a.service_exists else '❌'} |",
-            f"| 2 | Doc chain complete | {'✅' if a.doc_chain_complete else '❌'} |",
-            f"| 3 | BRD traced | {'✅' if a.brd_traced else '❌'} |",
-            f"| 4 | Code activity | `{a.code_activity_score:.1f}/100` |",
-            "| 5 | Code size | _(informational only)_ |",
-            f"| 6 | Test coverage | `{a.test_coverage_score:.1f}/100` |",
-        ]
-
-        if a.architecture_compliance is not None:
-            lines.append(f"| 7 | Architecture compliance | `{a.architecture_compliance:.1f}/100` |")
-        else:
-            lines.append("| 7 | Architecture compliance | _(skipped — structural mode)_ |")
-
-        if a.endpoint_coverage is not None:
-            lines.append(f"| 8 | Endpoint coverage | `{a.endpoint_coverage:.1f}/100` |")
-        else:
-            lines.append("| 8 | Endpoint coverage | _(skipped — structural mode)_ |")
-
-        lines.append("")
-
-        if a.repo_analyses:
-            lines += ["**Repositories:**", ""]
-            for repo in a.repo_analyses:
-                icon = "✅" if repo.has_code else ("⚠️" if repo.exists else "❌")
-                lines.append(f"- {icon} `{repo.repo_slug}`  (Java: {repo.java_files}, TS: {repo.ts_files})")
-            lines.append("")
-
-        if sec.risks:
-            lines += ["**Risks:**", ""]
-            for risk in sec.risks:
-                lines.append(f"- {_severity_icon(risk.severity)} {risk.description}")
-            lines.append("")
-
-        if sec.recommendations:
-            lines += ["**Recommendations:**", ""]
-            for rec in sec.recommendations:
-                lines.append(f"- {rec.summary}")
-            lines.append("")
-
-        lines += ["---", ""]
-
-    if report.risks:
-        lines += [
-            "## Risk Register",
-            "",
-            "| FR | Dimension | Severity | Description |",
-            "|----|-----------|----------|-------------|",
-        ]
-        for risk in sorted(report.risks, key=lambda r: _SEVERITY_SORT.get(r.severity, 9)):
-            icon = _severity_icon(risk.severity)
-            lines.append(f"| {risk.fr_id} | {risk.dimension} | {icon} {risk.severity} | {risk.description} |")
-        lines.append("")
-
-    return "\n".join(lines)
-
-
-# ---------------------------------------------------------------------------
-# JSON renderer
-# ---------------------------------------------------------------------------
-
-
-def render_json(report: ProgressReport) -> str:
-    """Render a ProgressReport to a JSON string."""
-
-    def _section_dict(sec: ReportSection) -> dict:
-        a = sec.assessment
-        return {
-            "fr_id": sec.fr_id,
-            "overall_score": a.overall_score,
-            "dimensions": {
-                "service_exists": a.service_exists,
-                "service_has_code": a.service_has_code,
-                "doc_chain_complete": a.doc_chain_complete,
-                "brd_traced": a.brd_traced,
-                "code_activity_score": a.code_activity_score,
-                "test_coverage_score": a.test_coverage_score,
-                "architecture_compliance": a.architecture_compliance,
-                "endpoint_coverage": a.endpoint_coverage,
-            },
-            "risks": [
-                {
-                    "dimension": r.dimension,
-                    "severity": r.severity,
-                    "description": r.description,
-                }
-                for r in sec.risks
-            ],
-            "recommendations": [
-                {
-                    "dimension": r.dimension,
-                    "severity": r.severity,
-                    "impact_score": r.impact_score,
-                    "summary": r.summary,
-                    "detail": r.detail,
-                    "target_value": r.target_value,
-                    "current_value": r.current_value,
-                }
-                for r in sec.recommendations
-            ],
-            "repos": [
-                {
-                    "slug": repo.repo_slug,
-                    "exists": repo.exists,
-                    "has_code": repo.has_code,
-                    "java_files": repo.java_files,
-                    "ts_files": repo.ts_files,
-                }
-                for repo in a.repo_analyses
-            ],
-        }
-
-    top_actions = sorted(
-        (rec for sec in report.sections for rec in sec.recommendations),
-        key=lambda r: r.impact_score,
-        reverse=True,
-    )[:3]
-
-    assessments = [s.assessment for s in report.sections]
-
-    # TSK-J.4: heatmap records — one dict per FR
-    heatmap_records = [
-        {
-            "fr_id": a.fr_id,
-            "service_exists": a.service_exists,
-            "doc_chain_complete": a.doc_chain_complete,
-            "brd_traced": a.brd_traced,
-            "code_activity_score": a.code_activity_score,
-            "test_coverage_score": a.test_coverage_score,
-            "architecture_compliance": a.architecture_compliance,
-            "endpoint_coverage": a.endpoint_coverage,
-        }
-        for a in assessments
-    ]
-
-    # TSK-J.4: repo_health records — deduplicated per repo slug
-    seen_slugs: set[str] = set()
-    repo_health_records: list[dict] = []
-    for a in assessments:
-        for repo in a.repo_analyses:
-            if repo.repo_slug in seen_slugs:
-                continue
-            seen_slugs.add(repo.repo_slug)
-            total_files = repo.java_files + repo.ts_files
-            ratio = repo.test_files / total_files if total_files > 0 else 0.0
-            repo_health_records.append(
-                {
-                    "slug": repo.repo_slug,
-                    "java_files": repo.java_files,
-                    "ts_files": repo.ts_files,
-                    "test_files": repo.test_files,
-                    "test_ratio": round(ratio, 3),
-                    "health": "green" if ratio >= 0.3 else ("red" if ratio < 0.1 else "yellow"),
-                }
-            )
-
-    # TSK-J.4 + J.3: shared helpers for dimension_coverage and score_distribution
-    coverage_records = _compute_dimension_coverage(assessments)
-    dimension_coverage = _coverage_records_to_dict(coverage_records)
-    score_distribution = _compute_score_distribution(assessments)
-
-    # TSK-L.3: valence-gap warning dict — always present, detected key is bool
-    # Per FR-Q7, when detected the JSON payload includes stratified cluster data.
-    _gap_detected = _detect_valence_gap(score_distribution)
-    _high_n = score_distribution.get("high", 0)
-    _low_n = score_distribution.get("low", 0)
-    bimodal_warning: dict = {
-        "detected": _gap_detected,
-        "high_count": _high_n if _gap_detected else None,
-        "low_count": _low_n if _gap_detected else None,
-        "interpretation": (
-            f"Score splits into high-performers ({_high_n} FRs ≥ 60) and "
-            f"low-performers ({_low_n} FRs < 30) with no medium tier."
-        )
-        if _gap_detected
-        else None,
-    }
-    if _gap_detected:
-        # Compute stratified sub-reports (mirrors markdown rendering path)
-        recs_by_fr: dict[str, list] = {sec.fr_id: sec.recommendations for sec in report.sections}
-        clusters = _stratify_bimodal(assessments, recs_by_fr)
-        bimodal_warning["stratification_variable"] = "service_exists"
-        bimodal_warning["high_cluster"] = {
-            "label": clusters["high"].label,
-            "fr_ids": list(clusters["high"].fr_ids),
-            "avg_score": clusters["high"].avg_score,
-            "dominant_blocker": clusters["high"].dominant_blocker,
-            "top_recommendation_fr": clusters["high"].top_recommendation_fr,
-        }
-        bimodal_warning["low_cluster"] = {
-            "label": clusters["low"].label,
-            "fr_ids": list(clusters["low"].fr_ids),
-            "avg_score": clusters["low"].avg_score,
-            "dominant_blocker": clusters["low"].dominant_blocker,
-            "top_recommendation_fr": clusters["low"].top_recommendation_fr,
-        }
-
-    payload = {
-        "run_id": report.run_id,
-        "project_key": report.project_key,
-        "bmad_repo": report.bmad_repo,
-        "generated_at": report.generated_at,
-        "overall_score": report.overall_score,
-        "fr_count": len(report.sections),
-        "top_actions": [
-            {
-                "dimension": r.dimension,
-                "severity": r.severity,
-                "impact_score": r.impact_score,
-                "summary": r.summary,
-                "detail": r.detail,
-                "target_value": r.target_value,
-                "current_value": r.current_value,
-            }
-            for r in top_actions
-        ],
-        "heatmap": heatmap_records,
-        "repo_health": repo_health_records,
-        "dimension_coverage": dimension_coverage,
-        "score_distribution": score_distribution,
-        "bimodal_warning": bimodal_warning,
-        "sections": [_section_dict(s) for s in report.sections],
-        "risks": [
-            {
-                "fr_id": r.fr_id,
-                "dimension": r.dimension,
-                "severity": r.severity,
-                "description": r.description,
-            }
-            for r in report.risks
-        ],
-    }
-    return json.dumps(payload, indent=2, ensure_ascii=False)
-
-
-# ---------------------------------------------------------------------------
-# File output
-# ---------------------------------------------------------------------------
-
-
-def write_report(
-    report: ProgressReport,
-    output_dir: Path,
-    project_key: str,
-    fmt: Literal["markdown", "json"] = "markdown",
-    mode: str = "standard",
-) -> Path:
-    """Write the report to ``output_dir/<project_key>/YYYY-MM-DD[.md|.json]``.
-
-    Updates ``report.output_path`` in-place and returns the destination path.
-    """
-    date_str = report.generated_at[:10]
-    dest_dir = output_dir / project_key
-    dest_dir.mkdir(parents=True, exist_ok=True)
-
-    ext = ".md" if fmt == "markdown" else ".json"
-    dest = dest_dir / f"{date_str}{ext}"
-
-    content = render_markdown(report, mode=mode) if fmt == "markdown" else render_json(report)
-    dest.write_text(content, encoding="utf-8")
-    report.output_path = str(dest)
-
-    log.info(
-        "report_written",
-        path=str(dest),
-        format=fmt,
-        fr_count=len(report.sections),
-        overall_score=report.overall_score,
-    )
-    return dest