okstra 0.144.0 → 0.146.0

package/runtime/python/okstra_ctl/run.py

@@ -31,6 +31,15 @@ from okstra_project import project_json_path, upsert_project_json
 from okstra_project.state import slugify
 from . import fix_cycles
 from .analysis_packet import build_analysis_packet
+from .analysis_inputs import (
+    ANALYSIS_TASK_TYPES,
+    AnalysisInputError,
+    load_candidate_map,
+    parse_evidence_paths,
+    resolve_analysis_head,
+    resolve_analysis_target,
+    resolve_evidence_inputs,
+)
 from .stage_fix_carry import derive_stage_fix_carry
 from .clarification_items import (
     attached_user_responses_section,
@@ -71,6 +80,7 @@ from okstra_project.dirs import okstra_home
 
 from .run_context import (
     compute_and_write_run_context,
+    refresh_run_context_snapshot,
     write_run_inputs,
 )
 from .seeding import (
@@ -311,6 +321,8 @@ class PrepareInputs:
     task_id: str
     task_type: str
     brief_path: Path  # absolute, already resolved
+    analysis_target: str = ""
+    evidence_inputs_raw: str = ""
     directive: str = ""
     workers_override: str = ""
     lead_model: str = ""
@@ -758,6 +770,8 @@ def _canonical_argv(inp: PrepareInputs, ctx: dict) -> list[str]:
         ("--task-group", inp.task_group),
         ("--task-id", inp.task_id),
         ("--task-brief", str(inp.brief_path)),
+        ("--analysis-target", inp.analysis_target),
+        ("--evidence-inputs", inp.evidence_inputs_raw),
         ("--directive", inp.directive),
         ("--approved-plan", inp.approved_plan_path),
         ("--implementation-option", inp.implementation_option),
@@ -946,6 +960,7 @@ def _validate_prepare_inputs(project_root: Path, inp: PrepareInputs) -> list:
     """Validate pure prepare inputs and return a final-verification stage map."""
     if not project_root.is_dir():
         raise PrepareError(f"project root not found: {project_root}")
+    _validate_analysis_prepare_inputs(project_root, inp)
     if inp.stages and inp.task_type != "release-handoff":
         raise PrepareError(
             "--stages is only meaningful with --task-type release-handoff; "
@@ -1028,6 +1043,41 @@ def _prepare_implementation_approved_plan(inp: PrepareInputs) -> list:
     return _parse_stage_map_into_ctx(inp.approved_plan_path)
 
 
+def _validate_analysis_prepare_inputs(project_root: Path, inp: PrepareInputs) -> None:
+    """Reject invalid analysis inputs before task worktree or run sequence creation."""
+    is_analysis = inp.task_type in ANALYSIS_TASK_TYPES
+    if not is_analysis:
+        if inp.analysis_target:
+            raise PrepareError(
+                f"--analysis-target is only accepted for analysis task types; got {inp.task_type}"
+            )
+        if inp.evidence_inputs_raw:
+            raise PrepareError(
+                f"--evidence-inputs is only accepted for analysis task types; got {inp.task_type}"
+            )
+        return
+    if inp.task_type == "project-analysis":
+        if inp.analysis_target:
+            raise PrepareError("project-analysis does not accept an analysis target")
+        if inp.evidence_inputs_raw:
+            raise PrepareError("project-analysis does not accept evidence inputs")
+        return
+    if inp.task_type == "feature-analysis" and not inp.analysis_target.strip():
+        raise PrepareError("feature-analysis requires --analysis-target")
+    if inp.task_type != "feature-analysis" and inp.analysis_target:
+        raise PrepareError(f"{inp.task_type} does not accept an analysis target")
+    paths = parse_evidence_paths(inp.evidence_inputs_raw, project_root)
+    try:
+        candidates = load_candidate_map(project_root, paths)
+        evidence = resolve_evidence_inputs(
+            project_root, inp.task_type, paths, "0" * 40,
+        )
+        if inp.task_type == "feature-analysis":
+            resolve_analysis_target(inp.analysis_target, evidence, candidates)
+    except AnalysisInputError as exc:
+        raise PrepareError(str(exc)) from exc
+
+
 def _collect_handoff_source_report_rows(
     rows: list, nums: list,
 ) -> list:
@@ -1583,6 +1633,7 @@ def _write_instruction_set_sources(
     reference-expectations 를 기록하고 디렉터리 경로를 돌려준다."""
     instruction_set = Path(ctx["INSTRUCTION_SET_PATH"])
     instruction_set.mkdir(parents=True, exist_ok=True)
+    _write_analysis_evidence_artifact(ctx, instruction_set)
     _write_verification_target_artifact(inp, ctx, instruction_set)
     profile_rendered = profile_content
     if inp.task_type == "implementation":
@@ -1658,10 +1709,43 @@ def _write_instruction_set_sources(
         fix_history_text=fix_cycles.packet_summary(
             fix_cycles.read_rows(Path(ctx["TASK_MANIFEST_PATH"]).parent)),
     )
+    if inp.task_type in ANALYSIS_TASK_TYPES:
+        packet += (
+            "\n## Analysis Evidence\n\n"
+            f"- Analysis evidence: `{ctx['INSTRUCTION_SET_RELATIVE_PATH']}/analysis-evidence.md`\n"
+        )
     (instruction_set / "analysis-packet.md").write_text(packet, encoding="utf-8")
     return instruction_set
 
 
+def _write_analysis_evidence_artifact(ctx: dict, instruction_set: Path) -> None:
+    """Write selected evidence metadata without copying the original reports."""
+    if ctx.get("TASK_TYPE") not in ANALYSIS_TASK_TYPES:
+        return
+    evidence = json.loads(ctx.get("EVIDENCE_INPUTS_JSON", "[]"))
+    lines = [
+        "# Analysis Evidence",
+        "",
+        "Revalidate every cited finding against the current code before relying on it.",
+    ]
+    for item in evidence:
+        lines.extend([
+            "",
+            f"## {item['taskType']} / run {item['runSeq']}",
+            "",
+            f"- Metadata: task key `{item['taskKey']}`, source commit `{item['sourceCommit']}`, relation `{item['relation']}`",
+            f"- Original report: `{item['reportPath']}`",
+            f"- Review status: `{item['reviewStatus']}`",
+            f"- Freshness: `{item['freshness']}`",
+            "- Current-code obligation: revalidate cited findings against the current code.",
+        ])
+    if not evidence:
+        lines.extend(["", "- No evidence reports were selected."])
+    (instruction_set / "analysis-evidence.md").write_text(
+        "\n".join(lines) + "\n", encoding="utf-8",
+    )
+
+
 def _render_lead_prompt_and_snapshot(
     inp: PrepareInputs,
     ctx: dict,
@@ -1744,6 +1828,10 @@ def _persist_run_inputs(
             "relatedTasks": inp.related_tasks_raw,
             "approvedPlanPath": approved_plan_path,
             "clarificationResponsePath": inp.clarification_response_path,
+            "analysisTarget": json.loads(ctx.get("ANALYSIS_TARGET_JSON", "{}")).get(
+                "requestedValue", ""
+            ),
+            "evidenceInputs": json.loads(ctx.get("EVIDENCE_INPUTS_JSON", "[]")),
             "renderOnly": inp.render_only,
         },
     )
@@ -2169,6 +2257,26 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     stage_run_claim = provisioned.stage_run_claim
     stage_arg = provisioned.stage_arg
 
+    analysis_source_commit = ""
+    resolved_evidence = ()
+    resolved_target: dict[str, object] = {}
+    if inp.task_type in ANALYSIS_TASK_TYPES:
+        analysis_root = Path(worktree.path or project_root)
+        evidence_paths = parse_evidence_paths(inp.evidence_inputs_raw, project_root)
+        try:
+            analysis_source_commit = resolve_analysis_head(analysis_root)
+            resolved_evidence = resolve_evidence_inputs(
+                project_root, inp.task_type, evidence_paths, analysis_source_commit,
+            )
+            if inp.task_type == "feature-analysis":
+                resolved_target = resolve_analysis_target(
+                    inp.analysis_target,
+                    resolved_evidence,
+                    load_candidate_map(project_root, evidence_paths),
+                )
+        except AnalysisInputError as exc:
+            raise PrepareError(str(exc)) from exc
+
     ctx = compute_and_write_run_context(
         workspace_root=workspace_root, project_root=project_root,
         project_id=inp.project_id, task_group=inp.task_group, task_id=inp.task_id,
@@ -2189,6 +2297,11 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         "OKSTRA_PLAN_VERIFICATION": (
             "false" if not inp.plan_verification_enabled else ""
         ),
+        "ANALYSIS_SOURCE_COMMIT": analysis_source_commit,
+        "ANALYSIS_TARGET_JSON": json.dumps(resolved_target, ensure_ascii=False),
+        "EVIDENCE_INPUTS_JSON": json.dumps(
+            [item.to_dict() for item in resolved_evidence], ensure_ascii=False,
+        ),
     })
 
     # implementation: override the task-worktree fields with the claimed
@@ -2254,6 +2367,7 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         "RENDER_ONLY": "true" if inp.render_only else "false",
         "OKSTRA_VERSION": installed_version(),
     })
+    refresh_run_context_snapshot(ctx)
     if lead_runtime == "codex":
         ctx["CLAUDE_RESUME_COMMAND_PATH"] = ""
         ctx["CLAUDE_RESUME_COMMAND_RELATIVE_PATH"] = ""
@@ -2328,6 +2442,8 @@ def main(argv: list[str]) -> int:
         ),
     )
     p.add_argument("--directive", default="")
+    p.add_argument("--analysis-target", default="", dest="analysis_target")
+    p.add_argument("--evidence-inputs", default="", dest="evidence_inputs_raw")
     p.add_argument(
         "--fix-cycle", default="", choices=["", "yes", "no"], dest="fix_cycle",
         help=(
@@ -2502,6 +2618,8 @@ def main(argv: list[str]) -> int:
         task_id=args.task_id,
         task_type=args.task_type,
         brief_path=brief_abs,
+        analysis_target=args.analysis_target,
+        evidence_inputs_raw=args.evidence_inputs_raw,
         directive=args.directive,
         workers_override=args.workers_override,
         lead_model=args.lead_model,

package/runtime/python/okstra_ctl/run_context.py

@@ -193,6 +193,20 @@ def compute_and_write_run_context(
     return ctx
 
 
+def refresh_run_context_snapshot(ctx: dict) -> None:
+    """Rewrite a run context after prepare resolves run-scoped inputs."""
+    payload = compact_run_context(ctx)
+    payload["analysis"] = {
+        "sourceCommit": ctx.get("ANALYSIS_SOURCE_COMMIT", ""),
+        "target": json.loads(ctx.get("ANALYSIS_TARGET_JSON", "{}")),
+        "evidenceInputs": json.loads(ctx.get("EVIDENCE_INPUTS_JSON", "[]")),
+    }
+    payload["ANALYSIS_SOURCE_COMMIT"] = ctx.get("ANALYSIS_SOURCE_COMMIT", "")
+    payload["ANALYSIS_TARGET_JSON"] = ctx.get("ANALYSIS_TARGET_JSON", "{}")
+    payload["EVIDENCE_INPUTS_JSON"] = ctx.get("EVIDENCE_INPUTS_JSON", "[]")
+    _atomic_write_json(Path(ctx["RUN_CONTEXT_FILE"]), payload)
+
+
 def write_run_inputs(
     *,
     project_root: Path,
@@ -207,7 +221,7 @@ def write_run_inputs(
     inputs schema (모든 키 optional):
       taskBriefPath, directive, workers, leadModel, claudeModel, codexModel,
       antigravityModel, reportWriterModel, relatedTasks, approvedPlanPath,
-      clarificationResponsePath, renderOnly
+      clarificationResponsePath, analysisTarget, evidenceInputs, renderOnly
     """
     run_manifests_dir = Path(run_manifests_dir)
     path = run_manifests_dir / _run_inputs_filename(task_type_segment, seq)
@@ -227,7 +241,25 @@ def read_run_context(run_manifests_dir: Path, task_type_segment: str,
     if not path.is_file():
         return None
     payload = json.loads(path.read_text(encoding="utf-8"))
-    return hydrate_run_context(payload)
+    context = hydrate_run_context(payload)
+    analysis = payload.get("analysis")
+    if isinstance(analysis, dict):
+        target_json = payload.get("ANALYSIS_TARGET_JSON")
+        if not isinstance(target_json, str):
+            target_json = json.dumps(analysis.get("target", {}), ensure_ascii=False)
+        evidence_json = payload.get("EVIDENCE_INPUTS_JSON")
+        if not isinstance(evidence_json, str):
+            evidence_json = json.dumps(
+                analysis.get("evidenceInputs", []), ensure_ascii=False,
+            )
+        context.update({
+            "ANALYSIS_SOURCE_COMMIT": str(
+                payload.get("ANALYSIS_SOURCE_COMMIT", analysis.get("sourceCommit", ""))
+            ),
+            "ANALYSIS_TARGET_JSON": target_json,
+            "EVIDENCE_INPUTS_JSON": evidence_json,
+        })
+    return context
 
 
 def read_run_inputs(run_manifests_dir: Path, task_type_segment: str,

package/runtime/python/okstra_ctl/schema_excerpt.py

@@ -1,9 +1,9 @@
 """Build a task-type-scoped excerpt of the final-report schema.
 
 The full schema (``schemas/final-report-v1.0.schema.json``) carries the
-deliverable property blocks for ALL task-types (``errorAnalysis``,
-``implementationPlanning``, ``releaseHandoff``, ``implementation``,
-``finalVerification``) plus a
+deliverable property blocks for ALL task-types (``errorAnalysis``, the three
+read-only analysis blocks, ``implementationPlanning``, ``releaseHandoff``,
+``implementation``, and ``finalVerification``) plus a
 ``$defs`` library (~38% of the file) shared across them. A single run only
 authors ONE task-type's data.json, so the report-writer worker only needs
 the common structure + its own task-type's block + the ``$defs`` those
@@ -27,15 +27,21 @@ import re
 # task-type → the per-type deliverable property key it owns. task-types
 # absent from this map (requirements-discovery,
 # improvement-discovery) have no per-type block; their excerpt keeps only
-# the common properties.
+# the non-analysis common properties.
 _TASK_TYPE_PROPERTY = {
     "error-analysis": "errorAnalysis",
+    "project-analysis": "projectAnalysis",
+    "feature-analysis": "featureAnalysis",
+    "change-impact-analysis": "changeImpactAnalysis",
     "implementation-planning": "implementationPlanning",
     "release-handoff": "releaseHandoff",
     "implementation": "implementation",
     "final-verification": "finalVerification",
 }
 _ALL_PER_TYPE_PROPERTIES = frozenset(_TASK_TYPE_PROPERTY.values())
+_ANALYSIS_COMMON_TASK_TYPES = frozenset(
+    {"project-analysis", "feature-analysis", "change-impact-analysis"}
+)
 
 _REF_RE = re.compile(r'"\$ref"\s*:\s*"#/\$defs/([^"]+)"')
 
@@ -100,6 +106,8 @@ def build_schema_excerpt(schema: dict, task_type: str, cut_from_version: str = "
     """
     keep_per_type = _TASK_TYPE_PROPERTY.get(task_type)
     drop_props = _ALL_PER_TYPE_PROPERTIES - ({keep_per_type} if keep_per_type else set())
+    if task_type not in _ANALYSIS_COMMON_TASK_TYPES:
+        drop_props = drop_props | {"analysisCommon"}
 
     props = {
         k: v for k, v in schema.get("properties", {}).items() if k not in drop_props

package/runtime/python/okstra_ctl/user_response.py

@@ -3,8 +3,8 @@
 The sidecar format is documented in ``templates/reports/user-response.template.md``
 and produced byte-identically by ``report_views.serialize_user_response`` (Python)
 and ``templates/reports/report.js`` (browser). This module owns the read side of
-the ``## APPROVAL`` block — the implementation wizard consumes it to offer
-"승인 + 옵션 적용" at the approve-confirm step.
+the ``## APPROVAL`` block used by the implementation wizard and the optional
+``## ANALYSIS REVIEW`` block used by analysis reruns.
 """
 from __future__ import annotations
 
@@ -12,6 +12,7 @@ import argparse
 import datetime as dt
 import json
 import re
+import stat
 import sys
 from dataclasses import dataclass
 from pathlib import Path
@@ -31,6 +32,19 @@ from okstra_ctl.clarification_items import (
 
 _APPROVAL_HEADING_RE = re.compile(r"^## APPROVAL\s*$", re.MULTILINE)
 _NEXT_RESPONSE_HEADING_RE = re.compile(r"^## ", re.MULTILINE)
+_ANALYSIS_REVIEW_HEADING_RE = re.compile(r"^## ANALYSIS REVIEW\s*$", re.MULTILINE)
+_ANALYSIS_SIDECAR_HEADING_RE = re.compile(
+    r"^## (?P<filename>user-response-[^\n]+\.md)\s*$", re.MULTILINE
+)
+_YAML_FRONTMATTER_RE = re.compile(
+    r"\A---[ \t]*\r?\n(?P<body>.*?)(?:\r?\n)---[ \t]*(?:\r?\n|\Z)",
+    re.DOTALL,
+)
+_FRONTMATTER_DELIMITER_RE = re.compile(r"^---[ \t]*$", re.MULTILINE)
+
+
+class UserResponseError(ValueError):
+    """Raised when a user-response sidecar violates its supported format."""
 
 
 @dataclass(frozen=True)
@@ -42,6 +56,296 @@ class UserResponseApprovalRecord:
     seq: str
 
 
+@dataclass(frozen=True)
+class AnalysisReviewRecord:
+    """Validated user review of an analysis report."""
+
+    status: str
+    affected_ids: tuple[str, ...]
+    reason: str
+    additional_evidence: str
+    requested_scope_change: str
+    task_key: str
+    task_type: str
+    source_report: str
+    seq: str
+
+
+_ANALYSIS_REVIEW_STATUSES = frozenset({
+    "accepted",
+    "revision-requested",
+    "rejected",
+})
+_ANALYSIS_REPORT_RE = re.compile(
+    r"^final-report-(?P<task_type>project-analysis|feature-analysis|"
+    r"change-impact-analysis)-(?P<seq>\d{3})\.md$"
+)
+
+
+def _quoted_review_value(block: str, key: str) -> str:
+    match = re.search(
+        rf"^- {re.escape(key)}:\s*\n((?:\s*>.*\n?)+)", block, re.MULTILINE
+    )
+    if not match:
+        return ""
+    return "\n".join(
+        re.sub(r"^\s*>\s?", "", line)
+        for line in match.group(1).splitlines()
+    ).strip()
+
+
+def _sidecar_metadata_value(sidecar_text: str, key: str) -> str:
+    frontmatter = _YAML_FRONTMATTER_RE.match(sidecar_text)
+    if frontmatter is None:
+        return ""
+    match = re.search(
+        rf"^{re.escape(key)}:[ \t]*(\S.*?)[ \t]*$",
+        frontmatter.group("body"),
+        re.MULTILINE,
+    )
+    return match.group(1) if match else ""
+
+
+def _nearest_frontmatter_value(
+    sidecar_text: str, key: str, before_offset: int
+) -> str:
+    delimiters = [
+        match
+        for match in _FRONTMATTER_DELIMITER_RE.finditer(sidecar_text)
+        if match.start() < before_offset
+    ]
+    for opening, closing in reversed(list(zip(delimiters, delimiters[1:]))):
+        body = sidecar_text[opening.end():closing.start()]
+        match = re.search(
+            rf"^{re.escape(key)}:[ \t]*(\S.*?)[ \t]*$",
+            body,
+            re.MULTILINE,
+        )
+        if match:
+            return match.group(1)
+    return _sidecar_metadata_value(sidecar_text, key)
+
+
+def _parsed_created_at(value: str) -> dt.datetime | None:
+    if re.fullmatch(
+        r"\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z",
+        value,
+    ) is None:
+        return None
+    try:
+        parsed = dt.datetime.fromisoformat(value[:-1] + "+00:00")
+    except ValueError:
+        return None
+    if parsed.tzinfo is None:
+        return None
+    return parsed.astimezone(dt.timezone.utc)
+
+
+def _nearest_sidecar_filename(sidecar_text: str, before_offset: int) -> str:
+    headings = [
+        match
+        for match in _ANALYSIS_SIDECAR_HEADING_RE.finditer(sidecar_text)
+        if match.start() < before_offset
+    ]
+    return headings[-1].group("filename") if headings else ""
+
+
+def _authoritative_analysis_review_match(
+    sidecar_text: str, matches: list[re.Match[str]]
+) -> re.Match[str]:
+    candidates: list[tuple[dt.datetime, str, int, re.Match[str]]] = []
+    for match in matches:
+        created_at = _parsed_created_at(
+            _nearest_frontmatter_value(sidecar_text, "created-at", match.start())
+        )
+        if created_at is None:
+            continue
+        candidates.append((
+            created_at,
+            _nearest_sidecar_filename(sidecar_text, match.start()),
+            match.start(),
+            match,
+        ))
+    if not candidates:
+        raise UserResponseError(
+            "ANALYSIS REVIEW requires a valid canonical created-at"
+        )
+    return max(candidates, key=lambda candidate: candidate[:3])[3]
+
+
+def parse_analysis_review(sidecar_text: str) -> AnalysisReviewRecord | None:
+    """Parse the bounded ``## ANALYSIS REVIEW`` block from a sidecar.
+
+    A sidecar without this optional block is not a review.  Once the block is
+    present, status and the fields that make a rejection actionable are
+    validated fail-closed.
+    """
+    matches = list(_ANALYSIS_REVIEW_HEADING_RE.finditer(sidecar_text))
+    if not matches:
+        return None
+    match = _authoritative_analysis_review_match(sidecar_text, matches)
+    block = sidecar_text[match.end():]
+    next_heading = _NEXT_RESPONSE_HEADING_RE.search(block)
+    if next_heading:
+        block = block[:next_heading.start()]
+    status = _field(block, "Status")
+    if status not in _ANALYSIS_REVIEW_STATUSES:
+        raise UserResponseError("ANALYSIS REVIEW Status is invalid")
+    affected = _field(block, "Affected-IDs") or ""
+    affected_ids = tuple(item.strip() for item in affected.split(",") if item.strip())
+    reason = _quoted_review_value(block, "Reason")
+    if status in {"revision-requested", "rejected"} and (not affected_ids or not reason):
+        raise UserResponseError(
+            f"ANALYSIS REVIEW {status} requires Affected-IDs and Reason"
+        )
+    return AnalysisReviewRecord(
+        status=status,
+        affected_ids=affected_ids,
+        reason=reason,
+        additional_evidence=_quoted_review_value(block, "Additional-Evidence"),
+        requested_scope_change=_quoted_review_value(block, "Requested-Scope-Change"),
+        task_key=_nearest_frontmatter_value(
+            sidecar_text, "task-key", match.start()
+        ),
+        task_type=_nearest_frontmatter_value(
+            sidecar_text, "task-type", match.start()
+        ),
+        source_report=_nearest_frontmatter_value(
+            sidecar_text, "source-report", match.start()
+        ),
+        seq=_nearest_frontmatter_value(sidecar_text, "seq", match.start()),
+    )
+
+
+def _matching_analysis_review_sidecars(
+    report_path: Path,
+    sidecar_name: re.Pattern[str],
+) -> tuple[Path, tuple[Path, ...]]:
+    run_dir = report_path.parent.parent
+    responses_dir = run_dir / "user-responses"
+    try:
+        responses_mode = responses_dir.lstat().st_mode
+    except FileNotFoundError:
+        return responses_dir, ()
+    except OSError as exc:
+        raise UserResponseError(
+            f"analysis user-responses directory is unreadable under {run_dir}"
+        ) from exc
+    if not stat.S_ISDIR(responses_mode):
+        raise UserResponseError(
+            f"analysis user-responses must be a real directory under {run_dir}"
+        )
+    try:
+        resolved_run_dir = run_dir.resolve(strict=True)
+        resolved_responses_dir = responses_dir.resolve(strict=True)
+    except OSError as exc:
+        raise UserResponseError(
+            f"analysis user-responses directory is unreadable under {run_dir}"
+        ) from exc
+    if resolved_responses_dir != resolved_run_dir / "user-responses":
+        raise UserResponseError(
+            f"analysis user-responses must stay under {resolved_run_dir}"
+        )
+    try:
+        sidecars = tuple(
+            sorted(
+                (
+                    entry
+                    for entry in responses_dir.iterdir()
+                    if sidecar_name.fullmatch(entry.name)
+                ),
+                key=lambda entry: entry.name,
+            )
+        )
+    except OSError as exc:
+        raise UserResponseError(
+            f"analysis user-responses directory is unreadable under {run_dir}"
+        ) from exc
+    return responses_dir, sidecars
+
+
+def _read_analysis_review_sidecar(sidecar: Path, responses_dir: Path) -> str:
+    try:
+        sidecar_mode = sidecar.lstat().st_mode
+        if not stat.S_ISREG(sidecar_mode):
+            raise OSError("not a regular file")
+        resolved = sidecar.resolve(strict=True)
+        if resolved.parent != responses_dir.resolve(strict=True):
+            raise OSError("outside user-responses")
+        return sidecar.read_text(encoding="utf-8")
+    except (OSError, UnicodeError) as exc:
+        raise UserResponseError(
+            "analysis review sidecar must be a readable regular file under "
+            f"{responses_dir}"
+        ) from exc
+
+
+def _analysis_review_matches_with_valid_created_at(
+    sidecar_text: str,
+) -> list[re.Match[str]]:
+    matches = list(_ANALYSIS_REVIEW_HEADING_RE.finditer(sidecar_text))
+    for match in matches:
+        created_at = _nearest_frontmatter_value(
+            sidecar_text, "created-at", match.start()
+        )
+        if _parsed_created_at(created_at) is None:
+            raise UserResponseError(
+                "ANALYSIS REVIEW requires a valid canonical created-at"
+            )
+    return matches
+
+
+def load_authoritative_analysis_review(
+    report_path: Path,
+    *,
+    expected_task_key: str,
+    expected_task_type: str,
+) -> AnalysisReviewRecord | None:
+    """Load the created-at-latest review attached to one analysis report."""
+    report_match = _ANALYSIS_REPORT_RE.fullmatch(report_path.name)
+    if report_match is None:
+        raise UserResponseError("analysis review source is not an analysis report")
+    sidecar_name = re.compile(
+        rf"^user-response-{re.escape(report_match.group('task_type'))}-"
+        rf"{re.escape(report_match.group('seq'))}(?:-.+)?\.md$"
+    )
+    responses_dir, sidecars = _matching_analysis_review_sidecars(
+        report_path, sidecar_name
+    )
+    if not sidecars:
+        return None
+    attached: list[str] = []
+    for sidecar in sidecars:
+        text = _read_analysis_review_sidecar(sidecar, responses_dir)
+        if _analysis_review_matches_with_valid_created_at(text):
+            attached.append(f"\n## {sidecar.name}\n\n{text.strip()}\n")
+    if not attached:
+        raise UserResponseError(
+            "existing review sidecar has no ANALYSIS REVIEW block"
+        )
+    review = parse_analysis_review("".join(attached))
+    if review is None:
+        raise UserResponseError("analysis review sidecar is unreadable")
+    expected_source = (
+        f"runs/{report_match.group('task_type')}/reports/{report_path.name}"
+    )
+    if review.task_key != expected_task_key:
+        raise UserResponseError(
+            "analysis review task-key does not match report taskKey"
+        )
+    if review.task_type != expected_task_type:
+        raise UserResponseError(
+            "analysis review task-type does not match report taskType"
+        )
+    if review.source_report != expected_source:
+        raise UserResponseError(
+            "analysis review source-report does not match report path"
+        )
+    if review.seq != report_match.group("seq"):
+        raise UserResponseError("analysis review seq does not match report runSeq")
+    return review
+
+
 def parse_user_response_approval(
     sidecar_text: str,
 ) -> Optional[UserResponseApprovalRecord]:
@@ -76,7 +380,9 @@ _RESPONSE_HEADING_RE = re.compile(r"^## (?P<id>[A-Za-z][A-Za-z0-9]*-\d+)\s*$", r
 
 
 def _field(block: str, key: str) -> Optional[str]:
-    m = re.search(rf"^- {re.escape(key)}:\s*(\S.*?)\s*$", block, re.MULTILINE)
+    m = re.search(
+        rf"^- {re.escape(key)}:[ \t]*(\S.*?)[ \t]*$", block, re.MULTILINE
+    )
     return m.group(1) if m else None