okstra 0.143.0 → 0.145.0

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/self_mock_signals.py

@@ -0,0 +1,183 @@
+"""Self-mock signal SSOT: language-keyed regexes for detecting self-mocked tests.
+
+Every entry is a port of one bullet from the matching
+`prompts/coding-preflight/languages/<lang>.md` "Self-mock signals to refuse"
+section. `doc_keyword` is the literal substring of that doc which the signal was
+derived from, so the drift guard can fail when the doc and this module diverge.
+Detector and guard MUST import from here; re-defining a pattern elsewhere
+violates the single-reference-point rule.
+
+Patterns stay narrow on purpose — a missed self-mock is cheaper than a false
+accusation, which teaches users to ignore the gate. Narrow means matching only
+the syntactic shape "stub the subject's own method, then assert the stub", plus
+reaching into the subject's privates. Which object is the subject is never
+inferred from naming beyond the literal `sut` token; a `<var>` capture in a
+pattern exists for hit reporting, not for subject identification.
+
+Four documented shapes are deliberately left to the mutation gate because
+deciding them needs subject identity that no regex has:
+
+- Kotlin `mockkObject(SomeSingleton)` / `mockkStatic(...)` and Java
+  `MockedStatic<SomeUtil>` are the anti-pattern only when the mocked singleton
+  *is* the unit under test, and are legitimate boundary fakes otherwise.
+- Python `patch.object(Calculator, "_compute")` names a class, and a class name
+  alone does not say whether it is the subject or a collaborator. Only patching
+  the test instance itself (`patch.object(self, ...)`) is unambiguous, so that is
+  all `patch-sut-method` matches — `patch.object(self.service, "fetch")` patches
+  a collaborator reached through `self` and must stay silent.
+- TypeScript `jest.spyOn(FooService.prototype, ...)` counts only when that class
+  is the spec file's own subject (`javascript-typescript.md:70` scopes it to
+  "in `foo.service.spec.ts`"). Without that scoping every prototype spy matches,
+  including the standard `Date.prototype` / `Repository.prototype` /
+  `HTMLElement.prototype` stubs of collaborators and the environment.
+"""
+from __future__ import annotations
+
+import posixpath
+import re
+from collections import namedtuple
+
+Signal = namedtuple("Signal", "name pattern doc_keyword")
+
+
+def selfmock_path_key(path: str) -> str:
+    """Fold one self-mock path into the spelling every consumer compares on.
+
+    Three producers name the same file and none of them agrees on spelling: the
+    report's §5.7.3 rows, the detector's `--test-file` arguments, and the
+    hand-authored waiver file. All three start from `git diff --name-only` in the
+    worktree cwd, so this folds only the drift that survives that shared origin —
+    Windows separators, a leading `./`, duplicated slashes. A single definition
+    is load-bearing: a waiver that normalizes differently from the coverage check
+    would clear one gate while tripping the other.
+    """
+    return posixpath.normpath(path.strip().replace("\\", "/"))
+
+
+def waiver_entry_key(entry: dict, discriminator: str) -> tuple:
+    """The `(file, line, <discriminator>)` triple a waiver is matched on.
+
+    Both gates match this way — gate A on `signal`, gate B on `mutant` — so the
+    mechanics live here rather than being written twice. Two spellings of "is
+    this the same finding?" could disagree, and a waiver would clear one gate
+    while leaving the other failing.
+
+    The line is coerced to `int` when it can be: the waiver file is typed by
+    hand, and a quoted `"12"` is a JSON typo, not a different finding. Everything
+    else is compared as written, so a near-miss waiver fails to match and its
+    finding keeps failing the run.
+    """
+    line = entry.get("line")
+    if isinstance(line, str) and line.strip().isdigit():
+        line = int(line)
+    return (
+        selfmock_path_key(str(entry.get("file", ""))),
+        line,
+        entry.get(discriminator),
+    )
+
+
+def partition_waived_entries(
+    findings: list[dict], waivers: list[dict], discriminator: str
+) -> tuple[list[dict], list[dict]]:
+    """Split findings into `(still failing, waived)` on the shared key.
+
+    A waived row carries the acknowledgement fields alongside the detector's own
+    spelling of the finding, so the sidecar records both what was found and who
+    accepted it.
+
+    Note what this does NOT do: it never inspects `reason` or `acknowledgedBy`.
+    Matching and adjudicating are deliberately separate — an entry with no
+    acknowledgement is carried through so `validate-run.py` can block on it,
+    instead of being dropped here where the run that produced the finding would
+    be excusing itself.
+    """
+    by_key = {waiver_entry_key(w, discriminator): w for w in waivers}
+    remaining: list[dict] = []
+    waived: list[dict] = []
+    for finding in findings:
+        waiver = by_key.get(waiver_entry_key(finding, discriminator))
+        if waiver is None:
+            remaining.append(finding)
+        else:
+            waived.append({**waiver, **finding})
+    return remaining, waived
+
+
+SIGNALS: dict[str, list[Signal]] = {
+    "ts_js": [
+        # `sut` must be the whole spy target: `jest.spyOn(sut.repo, 'find')`
+        # stubs a collaborator reached through the subject, which is fine.
+        Signal("spyOn-sut",
+               re.compile(r"jest\.spyOn\(\s*sut\s*,[^)]*\)\.(mockReturnValue|mockResolvedValue|mockImplementation)"),
+               "jest.spyOn(sut"),
+        Signal("assign-sut-fn",
+               re.compile(r"\bsut\.\w+\s*=\s*(jest|vi)\.fn"),
+               "sut.calculateTotal = jest.fn"),
+        Signal("private-reach",
+               re.compile(r"\(\s*sut\s+as\s+any\s*\)\.\w+|sut\[['\"]\w+['\"]\]\("),
+               "(sut as any).privateMethod"),
+    ],
+    "python": [
+        # The leading \b keeps ordinary methods ending in "patch" out —
+        # `dispatch(self, request)` and `apply_patch(self, diff)` are not patches.
+        Signal("patch-sut-method",
+               re.compile(r"\bpatch(?:\.object)?\(\s*self\s*,"),
+               "unittest.mock.patch"),
+        # `obj` is the doc's placeholder, not a subject marker: `obj._meta` is
+        # everyday Django. Only the literal `sut` token identifies the subject.
+        Signal("private-reach",
+               re.compile(r"\bsut\._\w+"),
+               "obj._internal"),
+    ],
+    "kotlin": [
+        Signal("spyk-sut",
+               re.compile(r"\bspyk\(\s*sut\b"),
+               "spyk(sut)"),
+        # The argument list allows one level of nesting so MockK matchers
+        # (`any()`, `eq(1)`) inside the stubbed call still match.
+        Signal("every-sut-returns",
+               re.compile(r"\bevery\s*\{\s*sut\.\w+\((?:[^()]|\([^()]*\))*\)\s*\}\s*returns"),
+               "every { sut.someMethod() } returns"),
+        Signal("coevery-sut-returns",
+               re.compile(r"\bcoEvery\s*\{\s*sut\.\w+\((?:[^()]|\([^()]*\))*\)\s*\}\s*returns"),
+               "coEvery { sut.suspendMethod() } returns"),
+        Signal("private-reach",
+               re.compile(r"\bcallPrivateFunc\b|\bsut\.javaClass\.getDeclared(?:Method|Field)\s*\("),
+               "callPrivateFunc"),
+    ],
+    "rust": [
+        # `let sut = MockFoo::new()` makes the subject itself a generated mock.
+        Signal("sut-is-mock",
+               re.compile(r"\blet\s+(?:mut\s+)?sut\s*=\s*Mock\w+::"),
+               "same struct under test"),
+        Signal("expect-on-sut",
+               re.compile(r"\bsut\s*\.\s*expect_\w+\(\)"),
+               "expect_helper().returning"),
+        Signal("private-reach",
+               re.compile(r"#\[cfg\(test\)\]\s*pub\b"),
+               "#[cfg(test)] pub"),
+    ],
+    "java": [
+        # Both annotations must decorate the SAME field — only other annotations
+        # may sit between them. Two adjacent fields each carrying one of the two
+        # is the ordinary `@Spy` collaborator + `@InjectMocks` subject layout.
+        Signal("injectmocks-spy",
+               re.compile(r"@(?:Spy|InjectMocks)\b(?:\s*@\w+(?:\([^)]*\))?)*\s*@(?:InjectMocks|Spy)\b"),
+               "@InjectMocks"),
+        # Both branches target the subject: a spy of a collaborator and
+        # `doReturn(...).when(collaboratorSpy)` are the doc's "What's fine".
+        Signal("spy-sut-stub",
+               re.compile(r"\bMockito\.spy\(\s*\w*[sS]ut\b|\bdoReturn\([^;]*\)\s*\.when\(\s*\w*[sS]ut\b"),
+               "Mockito.spy(realSut)"),
+        Signal("private-reach",
+               re.compile(r"\bReflectionTestUtils\.(?:setField|getField|invokeMethod)\(\s*\w*[sS]ut\b"),
+               "ReflectionTestUtils.setField(sut"),
+    ],
+}
+
+EXT_TO_LANG: dict[str, str] = {
+    ".py": "python", ".ts": "ts_js", ".tsx": "ts_js",
+    ".js": "ts_js", ".jsx": "ts_js", ".mjs": "ts_js",
+    ".kt": "kotlin", ".kts": "kotlin", ".rs": "rust", ".java": "java",
+}

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