Add retained run report helpers

src/guide_board/retention.py

@@ -73,6 +73,47 @@ def list_retained_runs(runs_dir: Path) -> list[dict[str, Any]]:
     return sorted(summaries, key=lambda item: item.get("created_at", ""), reverse=True)
 
 
+def select_retained_run(
+    runs_dir: Path,
+    run_id: str | None = None,
+    target_profile_ref: str | None = None,
+    assessment_profile_ref: str | None = None,
+) -> dict[str, Any] | None:
+    """Return the exact or latest retained run matching the optional selection."""
+    for run in list_retained_runs(runs_dir):
+        if run_id and run.get("run_id") != run_id:
+            continue
+        if target_profile_ref and run.get("target_profile_ref") != target_profile_ref:
+            continue
+        if assessment_profile_ref and run.get("assessment_profile_ref") != assessment_profile_ref:
+            continue
+        return run
+    return None
+
+
+def retained_run_report_paths(run: dict[str, Any]) -> dict[str, str]:
+    """Return stable report paths for a retained run summary."""
+    run_dir_value = run.get("run_dir")
+    if not isinstance(run_dir_value, str) or not run_dir_value:
+        raise ValueError("retained run summary is missing run_dir")
+
+    run_dir = Path(run_dir_value)
+    paths: dict[str, str] = {}
+    report_refs = run.get("report_refs", [])
+    if isinstance(report_refs, list):
+        for raw_ref in report_refs:
+            if not isinstance(raw_ref, str) or not raw_ref:
+                continue
+            ref = Path(raw_ref)
+            key = ref.stem.replace("-", "_")
+            paths[key] = str(run_dir / ref)
+
+    paths.setdefault("assessment_package", str(run_dir / "reports" / "assessment-package.json"))
+    paths.setdefault("report", str(run_dir / "reports" / "report.md"))
+    paths.setdefault("retention_summary", str(run_dir / "retention-summary.json"))
+    return dict(sorted(paths.items()))
+
+
 def build_trend_summary(
     runs_dir: Path,
     retained_runs: list[dict[str, Any]] | None = None,