okstra 0.143.0 → 0.145.0

package/runtime/validators/validate_analysis_report.py

@@ -0,0 +1,864 @@
+"""Cross-field validation for structured read-only analysis reports."""
+from __future__ import annotations
+
+import json
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+
+# scripts/ (repo) and python/ (installed under ~/.okstra/lib) are sibling
+# source roots, so standalone validator execution must add the one that exists.
+_VALIDATORS_DIR = Path(__file__).resolve().parent
+for _ssot_dir in (_VALIDATORS_DIR.parent / "scripts", _VALIDATORS_DIR.parent / "python"):
+    if _ssot_dir.is_dir() and str(_ssot_dir) not in sys.path:
+        sys.path.insert(0, str(_ssot_dir))
+
+from okstra_ctl.analysis_inputs import ANALYSIS_TASK_TYPES
+from okstra_ctl.final_report_paths import final_report_data_path
+from okstra_ctl.paths import RunRef
+from okstra_ctl.report_views import analysis_review_context
+from okstra_ctl.user_response import UserResponseError, parse_analysis_review
+
+
+_ANALYSIS_BLOCKS = {
+    "projectAnalysis",
+    "featureAnalysis",
+    "changeImpactAnalysis",
+}
+_EVIDENCE_COLLECTIONS = {
+    "project-analysis": (
+        "components",
+        "dependencies",
+        "entryPoints",
+        "dataStores",
+        "externalSystems",
+        "featureIndex",
+    ),
+    "feature-analysis": (
+        "flows",
+        "domainRules",
+        "stateChanges",
+        "externalInteractions",
+    ),
+    "change-impact-analysis": (
+        "preservedBehaviors",
+        "impactItems",
+        "dependencyBlastRadius",
+        "testImpact",
+        "operationalImpact",
+    ),
+}
+_ANALYSIS_PARENT_KEYS = {
+    "project-analysis": "projectAnalysis",
+    "feature-analysis": "featureAnalysis",
+    "change-impact-analysis": "changeImpactAnalysis",
+}
+_ANALYSIS_WORKER_ROLES = {
+    "Claude worker",
+    "Codex worker",
+    "Antigravity worker",
+}
+_FINAL_ANALYSIS_REPORT_RE = re.compile(
+    r"^final-report-(?P<task_type>project-analysis|feature-analysis|"
+    r"change-impact-analysis)-(?P<seq>\d{3})\.md$"
+)
+
+
+@dataclass(frozen=True)
+class AnalysisValidationResult:
+    errors: tuple[str, ...]
+
+    @property
+    def ok(self) -> bool:
+        return not self.errors
+
+
+@dataclass(frozen=True)
+class AnalysisTaskIdentity:
+    task_key: str
+    project_id: str
+    task_group: str
+    task_id: str
+
+
+@dataclass(frozen=True)
+class SourceAnalysisAuthority:
+    task_root: Path
+    source_report: Path
+    source_seq: str
+    current_identity: AnalysisTaskIdentity
+
+
+def validate_analysis_snapshot(
+    data: dict, run_manifest: dict, errors: list[str]
+) -> None:
+    common = data.get("analysisCommon") or {}
+    if common.get("sourceCommit") != run_manifest.get("analysisSourceCommit"):
+        errors.append(
+            "analysisCommon.sourceCommit must equal run-manifest.analysisSourceCommit"
+        )
+    if common.get("evidenceInputs") != run_manifest.get("evidenceInputs"):
+        errors.append(
+            "analysisCommon.evidenceInputs must equal run-manifest.evidenceInputs "
+            "in the same order and with the same values"
+        )
+    scope = common.get("scope") or {}
+    if scope.get("resolvedTarget") != run_manifest.get("analysisTarget"):
+        errors.append(
+            "analysisCommon.scope.resolvedTarget must equal run-manifest.analysisTarget"
+        )
+
+
+def _normalized_project_path(path: object) -> PurePosixPath | None:
+    if not isinstance(path, str):
+        return None
+    raw = path.strip().rstrip("/")
+    if not raw or raw == "." or raw.startswith("/"):
+        return None
+    if any(part in {"", ".", ".."} for part in raw.split("/")):
+        return None
+    normalized = PurePosixPath(raw)
+    if normalized.is_absolute():
+        return None
+    return normalized
+
+
+def _path_is_included(path: object, included_paths: list[object]) -> bool:
+    candidate = _normalized_project_path(path)
+    if candidate is None:
+        return False
+    for raw in included_paths:
+        included = _normalized_project_path(raw)
+        if included is not None and (
+            candidate == included or included in candidate.parents
+        ):
+            return True
+    return False
+
+
+def _validate_included_paths(included_paths: list[object], errors: list[str]) -> None:
+    for index, path in enumerate(included_paths):
+        if _normalized_project_path(path) is None:
+            errors.append(
+                f"analysisCommon.scope.includedPaths[{index}] must be a non-empty "
+                "project-relative path without `.` or `..` segments"
+            )
+
+
+def _validate_evidence_rows(
+    parent: dict,
+    collection: str,
+    prefix: str,
+    included_paths: list[object],
+    errors: list[str],
+) -> None:
+    for row_index, row in enumerate(parent.get(collection) or []):
+        evidence = row.get("currentCodeEvidence") if isinstance(row, dict) else None
+        if not evidence:
+            errors.append(
+                f"{prefix}.{collection}[{row_index}].currentCodeEvidence must "
+                "contain current-code path and line evidence; sourceReportRefs "
+                "alone are insufficient"
+            )
+            continue
+        for evidence_index, item in enumerate(evidence):
+            path = item.get("path") if isinstance(item, dict) else None
+            if not _path_is_included(path, included_paths):
+                errors.append(
+                    f"{prefix}.{collection}[{row_index}].currentCodeEvidence"
+                    f"[{evidence_index}].path must be a normalized path inside "
+                    "analysisCommon.scope.includedPaths"
+                )
+
+
+def _validate_all_current_code_evidence(
+    task_type: str, data: dict, errors: list[str]
+) -> None:
+    common = data.get("analysisCommon") or {}
+    included_paths = ((common.get("scope") or {}).get("includedPaths") or [])
+    _validate_included_paths(included_paths, errors)
+    _validate_evidence_rows(
+        common, "confirmedFacts", "analysisCommon", included_paths, errors
+    )
+    parent_key = _ANALYSIS_PARENT_KEYS[task_type]
+    parent = data.get(parent_key) or {}
+    for collection in _EVIDENCE_COLLECTIONS[task_type]:
+        _validate_evidence_rows(
+            parent, collection, parent_key, included_paths, errors
+        )
+    feature = (((common.get("scope") or {}).get("resolvedTarget") or {}).get(
+        "feature"
+    ) or {})
+    if feature:
+        _validate_evidence_rows(
+            {"feature": [feature]},
+            "feature",
+            "analysisCommon.scope.resolvedTarget",
+            included_paths,
+            errors,
+        )
+
+
+def _validate_project_semantics(data: dict, errors: list[str]) -> None:
+    common = data.get("analysisCommon") or {}
+    included = ((common.get("scope") or {}).get("includedPaths") or [])
+    analysis = data.get("projectAnalysis") or {}
+    for row in analysis.get("featureIndex") or []:
+        if not isinstance(row, dict):
+            continue
+        entry = row.get("representativeEntryPoint") or {}
+        if not _path_is_included(entry.get("path"), included):
+            errors.append(
+                f"projectAnalysis.featureIndex `{row.get('id') or '?'}` representative "
+                "entry point must be inside analysisCommon.scope.includedPaths"
+            )
+
+
+def _validate_feature_semantics(data: dict, errors: list[str]) -> None:
+    analysis = data.get("featureAnalysis") or {}
+    common_target = (((data.get("analysisCommon") or {}).get("scope") or {}).get(
+        "resolvedTarget"
+    ) or {})
+    feature_target = analysis.get("target") or {}
+    for field in ("inputMode", "requestedValue"):
+        if feature_target.get(field) != common_target.get(field):
+            errors.append(
+                f"featureAnalysis.target.{field} must match "
+                f"analysisCommon.scope.resolvedTarget.{field}"
+            )
+    resolved_feature = common_target.get("feature") or {}
+    if common_target.get("inputMode") == "feature-index" and (
+        feature_target.get("featureId") != resolved_feature.get("id")
+    ):
+        errors.append(
+            "featureAnalysis.target.featureId must match the resolved feature id"
+        )
+
+
+def _validate_change_impact_semantics(data: dict, errors: list[str]) -> None:
+    analysis = data.get("changeImpactAnalysis") or {}
+    allowed = {"constraint", "unknown"}
+    for index, row in enumerate(analysis.get("planningInputs") or []):
+        if not isinstance(row, dict):
+            continue
+        for field in sorted(set(row) - allowed):
+            errors.append(
+                f"changeImpactAnalysis.planningInputs[{index}] forbids `{field}`; "
+                "planning inputs may contain constraints and unknowns only"
+            )
+
+
+def _required_worker_roles(
+    run_manifest: dict, errors: list[str]
+) -> tuple[str, ...]:
+    contract = run_manifest.get("teamContract")
+    entries = (
+        contract.get("requiredWorkerRoles")
+        if isinstance(contract, dict)
+        else None
+    )
+    if not isinstance(entries, list) or not entries:
+        errors.append(
+            "run-manifest.teamContract.requiredWorkerRoles must be a non-empty "
+            "array of worker contract objects"
+        )
+        return ()
+    roles: list[str] = []
+    for index, entry in enumerate(entries):
+        role = entry.get("role") if isinstance(entry, dict) else None
+        if (
+            not isinstance(role, str)
+            or not role.strip()
+            or role != role.strip()
+        ):
+            errors.append(
+                "run-manifest.teamContract.requiredWorkerRoles"
+                f"[{index}].role must be an exact non-empty string"
+            )
+            return ()
+        if role in roles:
+            errors.append(
+                "run-manifest.teamContract.requiredWorkerRoles must not contain "
+                f"duplicate role `{role}`"
+            )
+            return ()
+        roles.append(role)
+    return tuple(roles)
+
+
+def _required_worker_rows(data: dict, required_roles: tuple[str, ...]) -> list[dict]:
+    required = set(required_roles)
+    return [
+        row
+        for row in data.get("executionStatus") or []
+        if isinstance(row, dict) and row.get("role") in required
+    ]
+
+
+def _scope_confirmation_status(
+    run_manifest: dict, errors: list[str]
+) -> str | None:
+    snapshot = run_manifest.get("analysisScopeConfirmation")
+    if not isinstance(snapshot, dict):
+        errors.append(
+            "run-manifest.analysisScopeConfirmation must be a pre-dispatch "
+            "brief confirmation snapshot"
+        )
+        return None
+    task_brief_path = snapshot.get("taskBriefPath")
+    status = snapshot.get("status")
+    brief_sha256 = snapshot.get("briefSha256")
+    valid = True
+    if (
+        not isinstance(task_brief_path, str)
+        or not task_brief_path
+        or task_brief_path != run_manifest.get("taskBriefPath")
+    ):
+        errors.append(
+            "run-manifest.analysisScopeConfirmation.taskBriefPath must equal "
+            "run-manifest.taskBriefPath"
+        )
+        valid = False
+    if status not in {"complete", "partial", "pending", "skipped"}:
+        errors.append(
+            "run-manifest.analysisScopeConfirmation.status must be one of "
+            "complete, partial, pending, skipped"
+        )
+        valid = False
+    if not isinstance(brief_sha256, str) or re.fullmatch(
+        r"[0-9a-f]{64}", brief_sha256
+    ) is None:
+        errors.append(
+            "run-manifest.analysisScopeConfirmation.briefSha256 must be a "
+            "lowercase SHA-256 hex digest"
+        )
+        valid = False
+    return status if valid else None
+
+
+def _validate_analysis_verdict(
+    data: dict,
+    required_roles: tuple[str, ...],
+    reporter_confirmation: str | None,
+    errors: list[str],
+) -> None:
+    common = data.get("analysisCommon") or {}
+    scope = common.get("scope") or {}
+    worker_rows = _required_worker_rows(data, required_roles)
+    worker_blocked = not any(row.get("status") == "completed" for row in worker_rows)
+    scope_blocked = reporter_confirmation != "complete"
+    unresolved_review = any(
+        isinstance(row, dict) and row.get("outcome") == "still-unresolved"
+        for row in common.get("analysisReviewResolution") or []
+    )
+    partial = unresolved_review or bool(scope.get("unscannedPaths")) or any(
+        isinstance(row, dict) and row.get("affectsVerdict") is True
+        for row in common.get("unknowns") or []
+    )
+    expected = "blocked" if worker_blocked or scope_blocked else (
+        "analysis-partial" if partial else "analysis-complete"
+    )
+    actual = {
+        str((data.get("verdictCard") or {}).get("verdictToken") or ""),
+        str((data.get("finalVerdict") or {}).get("verdictToken") or ""),
+    }
+    if actual == {expected}:
+        return
+    reasons = []
+    if worker_blocked:
+        reasons.append("required analysis workers produced zero completed results")
+    if scope_blocked:
+        reasons.append("brief frontmatter reporter-confirmations is not complete")
+    if partial:
+        reasons.append(
+            "a still-unresolved review resolution, unscannedPaths, or an "
+            "affectsVerdict unknown remains"
+        )
+    detail = "; ".join(reasons) or "the analysis scope is fully scanned"
+    errors.append(f"verdict must be `{expected}` because {detail}")
+
+
+def _validate_scope_before_dispatch(
+    data: dict,
+    required_roles: tuple[str, ...],
+    reporter_confirmation: str | None,
+    errors: list[str],
+) -> None:
+    if reporter_confirmation == "complete":
+        return
+    dispatched = any(
+        row.get("status") != "not-run"
+        for row in _required_worker_rows(data, required_roles)
+    )
+    if dispatched:
+        errors.append(
+            "required analysis workers were dispatched before "
+            "reporter-confirmations: complete was recorded"
+        )
+
+
+def validate_analysis_semantics(
+    task_type: str,
+    data: dict,
+    run_manifest: dict,
+    reporter_confirmation: str | None,
+    errors: list[str],
+) -> None:
+    required_roles = _required_worker_roles(run_manifest, errors)
+    analysis_worker_roles = tuple(
+        role for role in required_roles if role in _ANALYSIS_WORKER_ROLES
+    )
+    _validate_all_current_code_evidence(task_type, data, errors)
+    if task_type == "project-analysis":
+        _validate_project_semantics(data, errors)
+    elif task_type == "feature-analysis":
+        _validate_feature_semantics(data, errors)
+    elif task_type == "change-impact-analysis":
+        _validate_change_impact_semantics(data, errors)
+    _validate_scope_before_dispatch(
+        data, analysis_worker_roles, reporter_confirmation, errors
+    )
+    _validate_analysis_verdict(
+        data, analysis_worker_roles, reporter_confirmation, errors
+    )
+
+
+def _actual_analysis_task_type(
+    data: dict, run_manifest: dict, errors: list[str]
+) -> str:
+    header = data.get("header")
+    reported = str(header.get("taskType") or "") if isinstance(header, dict) else ""
+    actual = str(run_manifest.get("taskType") or "")
+    if actual and reported != actual:
+        errors.append(
+            "header.taskType must equal run-manifest.taskType "
+            f"(`{reported}` != `{actual}`)"
+        )
+    present_blocks = sorted(_ANALYSIS_BLOCKS.intersection(data))
+    if actual not in ANALYSIS_TASK_TYPES and present_blocks:
+        errors.append(
+            "non-analysis run must not contain analysis-only blocks: "
+            + ", ".join(present_blocks)
+        )
+    return actual
+
+
+def _analysis_task_root(
+    report_path: Path, project_root: Path, errors: list[str]
+) -> Path | None:
+    try:
+        run_ref = RunRef.from_report_path(report_path)
+    except ValueError:
+        errors.append(
+            "current analysis report path cannot resolve its task root"
+        )
+        return None
+    if run_ref.stage is not None:
+        errors.append(
+            "current analysis report path cannot resolve its task root"
+        )
+        return None
+    if report_path.parent.resolve() != run_ref.reports_dir.resolve():
+        errors.append(
+            "current analysis report path cannot resolve its task root"
+        )
+        return None
+    task_root = run_ref.task_root.resolve()
+    try:
+        task_root.relative_to(project_root.resolve())
+    except ValueError:
+        errors.append("current analysis report task root escapes the project root")
+        return None
+    return task_root
+
+
+def _contained_source_report(
+    source_report: str,
+    task_root: Path,
+    errors: list[str],
+) -> Path | None:
+    if not source_report:
+        errors.append("ANALYSIS REVIEW source-report is required")
+        return None
+    relative = Path(source_report)
+    if relative.is_absolute():
+        errors.append("ANALYSIS REVIEW source-report must be task-relative")
+        return None
+    if ".." in PurePosixPath(source_report).parts:
+        errors.append("ANALYSIS REVIEW source-report must not contain `..`")
+        return None
+    resolved = (task_root / relative).resolve()
+    try:
+        resolved.relative_to(task_root)
+    except ValueError:
+        errors.append("ANALYSIS REVIEW source-report escapes the task root")
+        return None
+    return resolved
+
+
+def _current_analysis_task_identity(
+    data: dict,
+    task_root: Path,
+    run_manifest_task_key: str,
+    errors: list[str],
+) -> AnalysisTaskIdentity | None:
+    header = data.get("header")
+    frontmatter = data.get("frontmatter")
+    if not isinstance(header, dict) or not isinstance(frontmatter, dict):
+        errors.append("current analysis data must define its task identity")
+        return None
+    task_key = header.get("taskKey")
+    project_id = frontmatter.get("projectId")
+    task_group = frontmatter.get("taskGroup")
+    task_id = frontmatter.get("taskId")
+    values = (task_key, project_id, task_group, task_id, run_manifest_task_key)
+    if any(not isinstance(value, str) or not value for value in values):
+        errors.append("current analysis task identity must be complete")
+        return None
+    identity = AnalysisTaskIdentity(
+        task_key=task_key,
+        project_id=project_id,
+        task_group=task_group,
+        task_id=task_id,
+    )
+    if identity.task_key != run_manifest_task_key:
+        errors.append("current header.taskKey must equal run-manifest.taskKey")
+    if identity.task_key != (
+        f"{identity.project_id}:{identity.task_group}:{identity.task_id}"
+    ):
+        errors.append("current report task identity fields must equal header.taskKey")
+    if (identity.task_group, identity.task_id) != (
+        task_root.parent.name,
+        task_root.name,
+    ):
+        errors.append("current report task identity must match its task root")
+    return identity
+
+
+def _validate_source_analysis_task_identity(
+    source_header: dict,
+    source_frontmatter: dict,
+    current: AnalysisTaskIdentity,
+    errors: list[str],
+) -> None:
+    expected_fields = (
+        (source_header, "taskKey", current.task_key, "header.taskKey"),
+        (
+            source_frontmatter,
+            "projectId",
+            current.project_id,
+            "frontmatter.projectId",
+        ),
+        (
+            source_frontmatter,
+            "taskGroup",
+            current.task_group,
+            "frontmatter.taskGroup",
+        ),
+        (source_frontmatter, "taskId", current.task_id, "frontmatter.taskId"),
+    )
+    for block, key, expected, label in expected_fields:
+        if block.get(key) != expected:
+            errors.append(
+                f"ANALYSIS REVIEW source {label} must match current task identity"
+            )
+
+
+def _validate_source_analysis_lineage(
+    task_root: Path,
+    source: Path,
+    current_match: re.Match[str],
+    source_match: re.Match[str],
+    data: dict,
+    current_task_type: str,
+    review_seq: str,
+    report_path: Path,
+    errors: list[str],
+) -> None:
+    current_seq = current_match.group("seq")
+    source_seq = source_match.group("seq")
+    current_common = data.get("analysisCommon")
+    if current_match.group("task_type") != current_task_type:
+        errors.append(
+            "current analysis report filename task type must equal the current task type"
+        )
+    if not isinstance(current_common, dict) or current_common.get("runSeq") != current_seq:
+        errors.append(
+            "current analysisCommon.runSeq must match the current report filename"
+        )
+    expected_parent = RunRef.from_task_root(
+        task_root, current_task_type
+    ).reports_dir.resolve()
+    if source.parent != expected_parent:
+        errors.append(
+            "ANALYSIS REVIEW source report must belong to the current task and analysis type"
+        )
+    if source_match.group("task_type") != current_task_type:
+        errors.append(
+            "ANALYSIS REVIEW source analysis task type must match the current analysis task type"
+        )
+    if review_seq != source_seq:
+        errors.append("ANALYSIS REVIEW review seq must match the source report seq")
+    if source == report_path.resolve() or int(source_seq) >= int(current_seq):
+        errors.append("ANALYSIS REVIEW source report must predate the current report")
+
+
+def _source_analysis_authority(
+    source_report: str,
+    review_seq: str,
+    data: dict,
+    current_task_type: str,
+    current_task_key: str,
+    report_path: Path,
+    project_root: Path,
+    errors: list[str],
+) -> SourceAnalysisAuthority | None:
+    initial_error_count = len(errors)
+    task_root = _analysis_task_root(report_path, project_root, errors)
+    if task_root is None:
+        return None
+    source = _contained_source_report(source_report, task_root, errors)
+    if source is None:
+        return None
+    current_match = _FINAL_ANALYSIS_REPORT_RE.fullmatch(report_path.name)
+    source_match = _FINAL_ANALYSIS_REPORT_RE.fullmatch(source.name)
+    if current_match is None:
+        errors.append("current analysis report filename is invalid")
+        return None
+    if source_match is None:
+        errors.append("ANALYSIS REVIEW source report filename is invalid")
+        return None
+    current_identity = _current_analysis_task_identity(
+        data, task_root, current_task_key, errors
+    )
+    if current_identity is None:
+        return None
+    _validate_source_analysis_lineage(
+        task_root,
+        source,
+        current_match,
+        source_match,
+        data,
+        current_task_type,
+        review_seq,
+        report_path,
+        errors,
+    )
+    if len(errors) != initial_error_count:
+        return None
+    return SourceAnalysisAuthority(
+        task_root=task_root,
+        source_report=source,
+        source_seq=source_match.group("seq"),
+        current_identity=current_identity,
+    )
+
+
+def _load_source_analysis_payload(
+    authority: SourceAnalysisAuthority,
+    errors: list[str],
+) -> dict | None:
+    source_data = final_report_data_path(authority.source_report).resolve()
+    try:
+        source_data.relative_to(authority.task_root)
+    except ValueError:
+        errors.append("ANALYSIS REVIEW source data escapes the task root")
+        return None
+    if not authority.source_report.is_file() or not source_data.is_file():
+        errors.append("ANALYSIS REVIEW source report has no analysis data")
+        return None
+    try:
+        source_payload = json.loads(source_data.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        errors.append("ANALYSIS REVIEW source report has no analysis data")
+        return None
+    if not isinstance(source_payload, dict):
+        errors.append("ANALYSIS REVIEW source report has no analysis data")
+        return None
+    blocks = (
+        source_payload.get("header"),
+        source_payload.get("frontmatter"),
+        source_payload.get("analysisCommon"),
+    )
+    if not all(
+        isinstance(block, dict) for block in blocks
+    ):
+        errors.append("ANALYSIS REVIEW source report has no analysis data")
+        return None
+    return source_payload
+
+
+def _source_analysis_payload_matches_authority(
+    source_payload: dict,
+    authority: SourceAnalysisAuthority,
+    current_task_type: str,
+    errors: list[str],
+) -> bool:
+    initial_error_count = len(errors)
+    source_header = source_payload["header"]
+    source_frontmatter = source_payload["frontmatter"]
+    source_common = source_payload["analysisCommon"]
+    source_types = (
+        source_header.get("taskType"),
+        source_frontmatter.get("taskType"),
+    )
+    _validate_source_analysis_task_identity(
+        source_header,
+        source_frontmatter,
+        authority.current_identity,
+        errors,
+    )
+    if any(source_type not in ANALYSIS_TASK_TYPES for source_type in source_types):
+        errors.append(
+            "ANALYSIS REVIEW source analysis task type must belong to ANALYSIS_TASK_TYPES"
+        )
+    if any(source_type != current_task_type for source_type in source_types):
+        errors.append(
+            "ANALYSIS REVIEW source analysis task type must match the current analysis task type"
+        )
+    if source_common.get("runSeq") != authority.source_seq:
+        errors.append(
+            "ANALYSIS REVIEW source analysisCommon.runSeq must match the source report seq"
+        )
+    return len(errors) == initial_error_count
+
+
+def _source_analysis_selector_ids(
+    source_report: str,
+    review_seq: str,
+    data: dict,
+    current_task_type: str,
+    current_task_key: str,
+    report_path: Path,
+    project_root: Path,
+    errors: list[str],
+) -> set[str] | None:
+    authority = _source_analysis_authority(
+        source_report,
+        review_seq,
+        data,
+        current_task_type,
+        current_task_key,
+        report_path,
+        project_root,
+        errors,
+    )
+    if authority is None:
+        return None
+    source_payload = _load_source_analysis_payload(authority, errors)
+    if source_payload is None:
+        return None
+    if not _source_analysis_payload_matches_authority(
+        source_payload, authority, current_task_type, errors
+    ):
+        return None
+    context = analysis_review_context(authority.source_report)
+    if context is None:
+        errors.append("ANALYSIS REVIEW source report has no analysis data")
+        return None
+    return set(context.selector_ids)
+
+
+def validate_analysis_review_resolution(
+    data: dict,
+    clarification_text: str,
+    errors: list[str],
+    *,
+    report_path: Path | None = None,
+    project_root: Path | None = None,
+    current_task_type: str = "",
+    current_task_key: str = "",
+) -> None:
+    resolutions = (data.get("analysisCommon") or {}).get(
+        "analysisReviewResolution"
+    ) or []
+    resolution_rows = [row for row in resolutions if isinstance(row, dict)]
+    by_id = {str(row.get("affectedId") or ""): row for row in resolution_rows}
+    confirmed_ids = {
+        str(row.get("id") or "")
+        for row in (data.get("analysisCommon") or {}).get("confirmedFacts") or []
+        if isinstance(row, dict)
+    }
+    for affected_id, row in by_id.items():
+        if row.get("outcome") == "still-unresolved" and affected_id in confirmed_ids:
+            errors.append(
+                f"`{affected_id}` remains refuted but is still present in confirmedFacts"
+            )
+    try:
+        review = parse_analysis_review(clarification_text) if clarification_text else None
+    except UserResponseError as exc:
+        errors.append(f"analysis review input is invalid: {exc}")
+        return
+    if review is None:
+        if resolutions:
+            errors.append(
+                "analysisReviewResolution must be empty when no prior analysis review exists"
+            )
+        return
+    reviewed_ids = list(review.affected_ids)
+    resolution_ids = [str(row.get("affectedId") or "") for row in resolution_rows]
+    for affected_id in sorted(set(reviewed_ids)):
+        if reviewed_ids.count(affected_id) > 1:
+            errors.append(f"ANALYSIS REVIEW has duplicate Affected-IDs `{affected_id}`")
+    for affected_id in sorted(set(resolution_ids)):
+        if resolution_ids.count(affected_id) > 1:
+            errors.append(
+                f"analysisReviewResolution has duplicate reviewed id `{affected_id}`"
+            )
+    reviewed_set = set(reviewed_ids)
+    resolution_set = set(resolution_ids)
+    if report_path is not None and project_root is not None:
+        source_ids = _source_analysis_selector_ids(
+            review.source_report,
+            review.seq,
+            data,
+            current_task_type,
+            current_task_key,
+            report_path,
+            project_root,
+            errors,
+        )
+        if source_ids is not None:
+            for affected_id in sorted(reviewed_set - source_ids):
+                errors.append(
+                    f"ANALYSIS REVIEW Affected-ID `{affected_id}` is not present "
+                    "in source analysis data"
+                )
+    for affected_id in sorted(reviewed_set - resolution_set):
+        errors.append(
+            f"analysisReviewResolution is missing reviewed id `{affected_id}`"
+        )
+    for affected_id in sorted(resolution_set - reviewed_set):
+        errors.append(
+            f"analysisReviewResolution has unknown reviewed id `{affected_id}`"
+        )
+
+
+def validate_analysis_report(
+    *,
+    data: dict,
+    report_path: Path,
+    project_root: Path,
+    run_manifest: dict,
+    clarification_text: str,
+) -> AnalysisValidationResult:
+    errors: list[str] = []
+    task_type = _actual_analysis_task_type(data, run_manifest, errors)
+    if task_type not in ANALYSIS_TASK_TYPES:
+        return AnalysisValidationResult(errors=tuple(errors))
+    reporter_confirmation = _scope_confirmation_status(run_manifest, errors)
+    validate_analysis_snapshot(data, run_manifest, errors)
+    validate_analysis_semantics(
+        task_type, data, run_manifest, reporter_confirmation, errors
+    )
+    validate_analysis_review_resolution(
+        data,
+        clarification_text,
+        errors,
+        report_path=report_path,
+        project_root=project_root,
+        current_task_type=task_type,
+        current_task_key=str(run_manifest.get("taskKey") or ""),
+    )
+    return AnalysisValidationResult(errors=tuple(errors))