okstra 0.144.0 → 0.145.0

package/runtime/python/okstra_ctl/analysis_inputs.py

@@ -0,0 +1,369 @@
+"""Shared evidence resolution for read-only analysis sidetracks."""
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import Mapping, Sequence
+
+from .final_report_paths import final_report_data_path
+from .paths import task_manifest_file
+from .user_response import (
+    UserResponseError,
+    load_authoritative_analysis_review,
+)
+
+
+ANALYSIS_TASK_TYPES = (
+    "project-analysis",
+    "feature-analysis",
+    "change-impact-analysis",
+)
+
+
+class AnalysisInputError(ValueError):
+    """Raised when a report cannot safely serve as analysis evidence."""
+
+
+@dataclass(frozen=True)
+class AnalysisReportCandidate:
+    report_path: Path
+    task_key: str
+    task_type: str
+    created_at: str
+    run_seq: str
+    source_commit: str
+    review_status: str
+    feature_index: tuple[object, ...]
+
+
+@dataclass(frozen=True)
+class ResolvedEvidenceInput:
+    report_path: Path
+    task_key: str
+    task_type: str
+    run_seq: str
+    source_commit: str
+    review_status: str
+    relation: str
+    freshness: str
+
+    def to_dict(self) -> dict[str, str]:
+        return {
+            "taskKey": self.task_key,
+            "taskType": self.task_type,
+            "reportPath": str(self.report_path),
+            "runSeq": self.run_seq,
+            "sourceCommit": self.source_commit,
+            "relation": self.relation,
+            "freshness": self.freshness,
+            "reviewStatus": self.review_status,
+        }
+
+
+_EVIDENCE_RELATION_BY_TYPES = {
+    ("feature-analysis", "project-analysis"): "project-context",
+    ("change-impact-analysis", "project-analysis"): "project-context",
+    ("change-impact-analysis", "feature-analysis"): "feature-baseline",
+}
+_REPORT_NAME_RE = re.compile(r"^final-report-.+-(?P<run_seq>[^-]+)\.md$")
+_FEATURE_ID_RE = re.compile(r"PF-\d{3}")
+_FULL_COMMIT_RE = re.compile(r"[0-9a-f]{40}")
+_RUN_SEQ_RE = re.compile(r"[0-9]{3}")
+_CREATED_AT_RE = re.compile(r"\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z")
+
+
+def parse_evidence_paths(
+    raw_paths: str, project_root: Path | None = None,
+) -> tuple[Path, ...]:
+    """Parse a comma-separated evidence selection in its supplied order."""
+    root = project_root.resolve() if project_root else None
+    paths: list[Path] = []
+    for raw_path in raw_paths.split(","):
+        value = raw_path.strip()
+        if not value:
+            continue
+        path = Path(value).expanduser()
+        if root and not path.is_absolute():
+            path = root / path
+        paths.append(path.resolve())
+    return tuple(paths)
+
+
+def load_candidate_map(
+    project_root: Path, report_paths: Sequence[Path],
+) -> dict[Path, AnalysisReportCandidate]:
+    """Load canonical metadata for every explicitly selected report."""
+    return {
+        candidate.report_path: candidate
+        for candidate in (
+            load_analysis_report_candidate(project_root, report_path)
+            for report_path in report_paths
+        )
+    }
+
+
+def resolve_analysis_head(analysis_root: Path, task_type: str = "") -> str:
+    """Return an analysis worktree's immutable HEAD, or reject an invalid one."""
+    if task_type and task_type not in ANALYSIS_TASK_TYPES:
+        return ""
+    try:
+        result = subprocess.run(
+            ["git", "-C", str(analysis_root), "rev-parse", "HEAD"],
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+    except (OSError, subprocess.CalledProcessError) as exc:
+        raise AnalysisInputError(
+            f"cannot resolve analysis source commit: {analysis_root}"
+        ) from exc
+    return _validated_commit(result.stdout.strip(), "analysis source commit")
+
+
+def _resolved_within(path: Path, root: Path, description: str) -> Path:
+    resolved = path.resolve()
+    try:
+        resolved.relative_to(root)
+    except ValueError as exc:
+        raise AnalysisInputError(f"{description} must be under {root}") from exc
+    return resolved
+
+
+def _required_string(data: Mapping[str, object], key: str, context: str) -> str:
+    value = data.get(key)
+    if not isinstance(value, str) or not value:
+        raise AnalysisInputError(f"data.json {context}.{key} must be a non-empty string")
+    return value
+
+
+def _validated_commit(value: str, field: str) -> str:
+    if not _FULL_COMMIT_RE.fullmatch(value):
+        raise AnalysisInputError(
+            f"{field} must be a 40-character lowercase hexadecimal commit"
+        )
+    return value
+
+
+def _validated_created_at(value: str) -> str:
+    if _CREATED_AT_RE.fullmatch(value) is None:
+        raise AnalysisInputError(
+            "data.json header.createdAt must use YYYY-MM-DDTHH:MM:SSZ"
+        )
+    try:
+        datetime.strptime(value, "%Y-%m-%dT%H:%M:%SZ")
+    except ValueError as exc:
+        raise AnalysisInputError("data.json header.createdAt is invalid") from exc
+    return value
+
+
+def _report_path_metadata(project_root: Path, report_path: Path) -> tuple[Path, str, str]:
+    okstra_root = project_root.resolve() / ".okstra"
+    relative = report_path.relative_to(okstra_root)
+    parts = relative.parts
+    if (
+        len(parts) != 7
+        or parts[0] != "tasks"
+        or parts[3] != "runs"
+        or parts[5] != "reports"
+    ):
+        raise AnalysisInputError("report path is not an analysis run report")
+    return report_path.parents[3], parts[4], parts[6]
+
+
+def _task_key_from_manifest(task_root: Path, okstra_root: Path) -> str:
+    manifest_path = _resolved_within(
+        task_manifest_file(task_root), okstra_root, "task manifest path"
+    )
+    try:
+        manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise AnalysisInputError(f"cannot read task manifest: {manifest_path}") from exc
+    if not isinstance(manifest, dict):
+        raise AnalysisInputError("task manifest must contain an object")
+    return _required_string(manifest, "taskKey", "task manifest")
+
+
+def load_analysis_report_candidate(
+    project_root: Path, report_path: Path
+) -> AnalysisReportCandidate:
+    """Load one report only after validating its path and canonical metadata."""
+    root = project_root.resolve()
+    okstra_root = root / ".okstra"
+    report = _resolved_within(report_path, okstra_root, "report path")
+    if not report.is_file():
+        raise AnalysisInputError(f"report does not exist: {report}")
+    task_root, path_task_type, filename = _report_path_metadata(root, report)
+    filename_match = _REPORT_NAME_RE.fullmatch(filename)
+    if not filename_match:
+        raise AnalysisInputError("report filename is not a final report")
+    data_path = _resolved_within(final_report_data_path(report), okstra_root, "data.json path")
+    try:
+        data = json.loads(data_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise AnalysisInputError(f"cannot read data.json: {data_path}") from exc
+    if not isinstance(data, dict):
+        raise AnalysisInputError("data.json must contain an object")
+    header = data.get("header")
+    common = data.get("analysisCommon")
+    if not isinstance(header, dict) or not isinstance(common, dict):
+        raise AnalysisInputError("data.json requires header and analysisCommon objects")
+    task_key = _required_string(header, "taskKey", "header")
+    task_type = _required_string(header, "taskType", "header")
+    created_at = _validated_created_at(
+        _required_string(header, "createdAt", "header")
+    )
+    run_seq = _required_string(common, "runSeq", "analysisCommon")
+    if not _RUN_SEQ_RE.fullmatch(run_seq):
+        raise AnalysisInputError("data.json analysisCommon.runSeq must be 3-digit")
+    source_commit = _validated_commit(
+        _required_string(common, "sourceCommit", "analysisCommon"),
+        "sourceCommit",
+    )
+    if task_key != _task_key_from_manifest(task_root, okstra_root):
+        raise AnalysisInputError("data.json header.taskKey does not match task manifest")
+    if task_type != path_task_type:
+        raise AnalysisInputError("data.json header.taskType does not match report path")
+    if filename != f"final-report-{task_type}-{run_seq}.md":
+        raise AnalysisInputError("data.json analysisCommon.runSeq does not match report filename")
+    feature_index: Sequence[object] = ()
+    if task_type == "project-analysis":
+        project_analysis = data.get("projectAnalysis")
+        if not isinstance(project_analysis, dict):
+            raise AnalysisInputError("data.json projectAnalysis must be an object")
+        feature_index = project_analysis.get("featureIndex")
+        if not isinstance(feature_index, list):
+            raise AnalysisInputError(
+                "data.json projectAnalysis.featureIndex must be a list"
+            )
+    try:
+        review = load_authoritative_analysis_review(
+            report,
+            expected_task_key=task_key,
+            expected_task_type=task_type,
+        )
+    except UserResponseError as exc:
+        raise AnalysisInputError(f"invalid review sidecar: {exc}") from exc
+    review_status = review.status if review is not None else "unreviewed"
+    return AnalysisReportCandidate(
+        report_path=report,
+        task_key=task_key,
+        task_type=task_type,
+        created_at=created_at,
+        run_seq=run_seq,
+        source_commit=source_commit,
+        review_status=review_status,
+        feature_index=tuple(feature_index),
+    )
+
+
+def list_evidence_candidates(
+    project_root: Path, consumer_task_type: str, relation: str
+) -> list[AnalysisReportCandidate]:
+    """Return accepted, compatible reports in deterministic newest-first order."""
+    root = project_root.resolve()
+    compatible_types = [
+        source_type
+        for (consumer, source_type), allowed_relation in _EVIDENCE_RELATION_BY_TYPES.items()
+        if consumer == consumer_task_type and allowed_relation == relation
+    ]
+    if not compatible_types:
+        return []
+    reports_root = root / ".okstra" / "tasks"
+    candidates: list[AnalysisReportCandidate] = []
+    for report in reports_root.glob("*/*/runs/*/reports/*.md"):
+        try:
+            candidate = load_analysis_report_candidate(root, report)
+        except AnalysisInputError:
+            continue
+        if candidate.task_type in compatible_types and candidate.review_status == "accepted":
+            candidates.append(candidate)
+    candidates.sort(
+        key=lambda candidate: (
+            candidate.task_key,
+            -int(candidate.run_seq),
+            str(candidate.report_path),
+        )
+    )
+    candidates.sort(key=lambda candidate: candidate.created_at, reverse=True)
+    return candidates
+
+
+def resolve_evidence_inputs(
+    project_root: Path,
+    consumer_task_type: str,
+    report_paths: Sequence[Path],
+    current_commit: str,
+) -> tuple[ResolvedEvidenceInput, ...]:
+    """Validate the explicit evidence selection that a consumer will use."""
+    _validated_commit(current_commit, "current_commit")
+    resolved: list[ResolvedEvidenceInput] = []
+    seen: set[Path] = set()
+    for report_path in report_paths:
+        candidate = load_analysis_report_candidate(project_root, report_path)
+        if candidate.report_path in seen:
+            raise AnalysisInputError(f"duplicate evidence report: {candidate.report_path}")
+        seen.add(candidate.report_path)
+        relation = _EVIDENCE_RELATION_BY_TYPES.get(
+            (consumer_task_type, candidate.task_type)
+        )
+        if relation is None:
+            raise AnalysisInputError(
+                f"evidence relation is not allowed: {consumer_task_type} <- {candidate.task_type}"
+            )
+        if candidate.review_status in {"revision-requested", "rejected"}:
+            raise AnalysisInputError(
+                f"evidence report has {candidate.review_status} review status"
+            )
+        resolved.append(ResolvedEvidenceInput(
+            report_path=candidate.report_path,
+            task_key=candidate.task_key,
+            task_type=candidate.task_type,
+            run_seq=candidate.run_seq,
+            source_commit=candidate.source_commit,
+            review_status=("accepted" if candidate.review_status == "accepted" else "user-unverified"),
+            relation=relation,
+            freshness="exact" if candidate.source_commit == current_commit else "stale",
+        ))
+    return tuple(resolved)
+
+
+def resolve_analysis_target(
+    raw_target: str,
+    evidence_inputs: Sequence[ResolvedEvidenceInput],
+    candidates: Mapping[Path, AnalysisReportCandidate],
+) -> dict[str, object]:
+    """Normalize a feature-index identifier or a non-empty free-text target."""
+    target = raw_target.strip()
+    if not target:
+        raise AnalysisInputError("analysis target must not be empty")
+    if not _FEATURE_ID_RE.fullmatch(target):
+        return {"inputMode": "free-text", "requestedValue": target}
+    matches: list[dict[object, object]] = []
+    for evidence in evidence_inputs:
+        if evidence.relation != "project-context":
+            continue
+        candidate = candidates.get(evidence.report_path)
+        if candidate is None:
+            candidate = next(
+                (value for path, value in candidates.items() if path.resolve() == evidence.report_path),
+                None,
+            )
+        if candidate is None:
+            continue
+        matches.extend(
+            feature for feature in candidate.feature_index
+            if isinstance(feature, dict) and feature.get("id") == target
+        )
+    if len(matches) != 1:
+        raise AnalysisInputError(
+            f"exactly one project-context feature must match {target}"
+        )
+    return {
+        "inputMode": "feature-index",
+        "requestedValue": target,
+        "feature": dict(matches[0]),
+    }

package/runtime/python/okstra_ctl/clarification_items.py

@@ -372,6 +372,79 @@ def user_response_sidecars(source: Path) -> list[Path]:
     )
 
 
+_ANALYSIS_REPORT_NAME_RE = re.compile(
+    r"^final-report-(?P<task_type>project-analysis|feature-analysis|"
+    r"change-impact-analysis)-(?P<seq>\d{3})\.md$"
+)
+_SIDECAR_FRONTMATTER_RE = re.compile(
+    r"\A---[ \t]*\r?\n(?P<body>.*?)(?:\r?\n)---[ \t]*(?:\r?\n|\Z)",
+    re.DOTALL,
+)
+_ANALYSIS_REVIEW_HEADING_RE = re.compile(
+    r"^## ANALYSIS REVIEW\s*$", re.MULTILINE
+)
+
+
+def _sidecar_frontmatter_value(text: str, key: str) -> str:
+    match = _SIDECAR_FRONTMATTER_RE.match(text)
+    if match is None:
+        return ""
+    value = re.search(
+        rf"^{re.escape(key)}:\s*(\S.*?)\s*$",
+        match.group("body"),
+        re.MULTILINE,
+    )
+    return value.group(1) if value else ""
+
+
+def _sidecars_for_attachment(source: Path) -> list[Path]:
+    sidecars = user_response_sidecars(source)
+    report_match = _ANALYSIS_REPORT_NAME_RE.fullmatch(source.name)
+    if report_match is None:
+        return sidecars
+    expected_source = (
+        f"runs/{report_match.group('task_type')}/reports/{source.name}"
+    )
+    ordinary: list[Path] = []
+    candidates: list[tuple[Path, str]] = []
+    for sidecar in sidecars:
+        try:
+            text = sidecar.read_text(encoding="utf-8")
+        except OSError:
+            ordinary.append(sidecar)
+            continue
+        if _ANALYSIS_REVIEW_HEADING_RE.search(text) is None:
+            ordinary.append(sidecar)
+            continue
+        source_report = _sidecar_frontmatter_value(text, "source-report")
+        seq = _sidecar_frontmatter_value(text, "seq")
+        if source_report and source_report != expected_source:
+            continue
+        if seq and seq != report_match.group("seq"):
+            continue
+        candidates.append((sidecar, text))
+
+    from okstra_ctl.user_response import UserResponseError, parse_analysis_review
+
+    valid: list[Path] = []
+    malformed: list[Path] = []
+    for sidecar, text in candidates:
+        try:
+            review = parse_analysis_review(text)
+        except UserResponseError:
+            malformed.append(sidecar)
+            continue
+        if review is not None and (
+            review.source_report == expected_source
+            and review.seq == report_match.group("seq")
+        ):
+            valid.append(sidecar)
+        else:
+            malformed.append(sidecar)
+    selected = valid if valid else malformed
+    return sorted([*ordinary, *selected])
+
+
 def _sidecar_answers(source: Path) -> dict[str, str]:
     """`user-responses/` 사이드카들의 답변을 `{clarification-id: value}` 로 모은다.
 
@@ -399,7 +472,7 @@ def attached_user_responses_section(source: Path) -> str:
     첨부할 때 쓴다. `clarification_response_with_sidecars` 와 같은 직렬화 포맷을
     한 곳에서 만들어 두 carry-in 경로가 갈라지지 않게 한다.
     """
-    sidecars = user_response_sidecars(source)
+    sidecars = _sidecars_for_attachment(source)
     if not sidecars:
         return ""
     parts = ["# Attached User Responses\n"]

package/runtime/python/okstra_ctl/render.py

@@ -29,6 +29,7 @@ from okstra_project.dirs import TASK_MANIFEST_FILENAME, OKSTRA_DIR_NAME, project
 # render_task_manifest 가 동일한 리스트/딕셔너리를 로컬에 중복 정의했는데,
 # 이는 silent drift 위험이 있어 SSOT import 로 통합한다.
 from . import fix_cycles
+from .analysis_inputs import ANALYSIS_TASK_TYPES
 from .paths import okstra_home
 from .lead_runtime import lead_runtime_info
 from .path_hints import compact_active_run_context, hydrate_run_context
@@ -874,6 +875,45 @@ def _required_worker_roles(ctx: dict, reviewers: list[str]) -> list[dict]:
     ]
 
 
+def _reporter_confirmation_status(brief_bytes: bytes) -> str:
+    try:
+        lines = brief_bytes.decode("utf-8").splitlines()
+    except UnicodeDecodeError:
+        return ""
+    if not lines or lines[0].strip() != "---":
+        return ""
+    for line in lines[1:]:
+        if line.strip() == "---":
+            break
+        key, separator, value = line.partition(":")
+        if separator and key.strip() == "reporter-confirmations":
+            return value.strip().strip("'\"").lower()
+    return ""
+
+
+def _analysis_scope_confirmation_snapshot(ctx: dict) -> dict | None:
+    if ctx.get("TASK_TYPE") not in ANALYSIS_TASK_TYPES:
+        return None
+    brief_path = Path(ctx.get("BRIEF_FILE_PATH", ""))
+    try:
+        brief_bytes = brief_path.read_bytes() if brief_path.is_file() else None
+    except OSError:
+        brief_bytes = None
+    return {
+        "taskBriefPath": ctx.get("BRIEF_RELATIVE_PATH", ""),
+        "status": (
+            _reporter_confirmation_status(brief_bytes)
+            if brief_bytes is not None
+            else ""
+        ),
+        "briefSha256": (
+            hashlib.sha256(brief_bytes).hexdigest()
+            if brief_bytes is not None
+            else ""
+        ),
+    }
+
+
 def _derive_phase_states(existing_workflow: dict, ctx: dict) -> tuple[dict, str, str]:
     """phaseStates dict + (current_phase, current_phase_state) 를 도출한다.
 
@@ -1204,9 +1244,8 @@ def _build_convergence_block(ctx: dict) -> dict:
     - `enabled` default True
     - `maxRounds` default 1 for `requirements-discovery`, 2 otherwise
     - `verificationMode` default "lightweight"
-    - `adversarial` default True for `requirements-discovery` / `error-analysis` /
-      `implementation-planning` (forces `verificationMode` to "full-reanalysis"),
-      False otherwise
+    - `adversarial` default True for discovery, planning, and analysis task types
+      (forces `verificationMode` to "full-reanalysis"), False otherwise
     - `planBodyVerification` is implementation-planning specific; the key is
       always emitted (dead-letter on other phases) so the schema stays stable.
       Its `selfFixMaxRounds` default 3 bounds the report-writer self-fix loop
@@ -1222,7 +1261,14 @@ def _build_convergence_block(ctx: dict) -> dict:
     """
     task_type = ctx.get("TASK_TYPE", "")
     default_max_rounds = 1 if task_type == "requirements-discovery" else 2
-    adversarial_phases = {"requirements-discovery", "error-analysis", "implementation-planning"}
+    adversarial_phases = {
+        "requirements-discovery",
+        "error-analysis",
+        "implementation-planning",
+        "project-analysis",
+        "feature-analysis",
+        "change-impact-analysis",
+    }
     is_adversarial = task_type in adversarial_phases
     raw_plan_verify = (ctx.get("OKSTRA_PLAN_VERIFICATION", "") or "").strip().lower()
     plan_verify_enabled = raw_plan_verify != "false"
@@ -1257,6 +1303,20 @@ def _build_convergence_block(ctx: dict) -> dict:
 
 
 def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
+    run_manifest_file = Path(run_manifest_path)
+    existing_run_manifest = {}
+    if run_manifest_file.is_file():
+        try:
+            loaded_run_manifest = json.loads(
+                run_manifest_file.read_text(encoding="utf-8")
+            )
+            existing_run_manifest = (
+                loaded_run_manifest
+                if isinstance(loaded_run_manifest, dict)
+                else {}
+            )
+        except (OSError, json.JSONDecodeError):
+            existing_run_manifest = {}
     task_manifest_path = Path(ctx.get("TASK_MANIFEST_PATH", ""))
     task_manifest = {}
     if task_manifest_path.exists():
@@ -1330,6 +1390,14 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
         "teamStatePath": ctx.get("TEAM_STATE_RELATIVE_PATH", ""),
         "activeRunContextPath": ctx.get("ACTIVE_RUN_CONTEXT_RELATIVE_PATH", ""),
         "analysisPacketPath": ctx.get("ANALYSIS_PACKET_RELATIVE_PATH", ""),
+        "analysisEvidencePath": (
+            ctx.get("INSTRUCTION_SET_RELATIVE_PATH", "") + "/analysis-evidence.md"
+            if ctx.get("TASK_TYPE") in {"project-analysis", "feature-analysis", "change-impact-analysis"}
+            else ""
+        ),
+        "analysisSourceCommit": ctx.get("ANALYSIS_SOURCE_COMMIT", ""),
+        "analysisTarget": json.loads(ctx.get("ANALYSIS_TARGET_JSON", "{}")),
+        "evidenceInputs": json.loads(ctx.get("EVIDENCE_INPUTS_JSON", "[]")),
         "verificationTargetPath": ctx.get("VERIFICATION_TARGET_RELATIVE_PATH", ""),
         "verificationTargetDigest": ctx.get("VERIFICATION_TARGET_DIGEST", ""),
         "workerResultsDirectoryPath": ctx.get("WORKER_RESULTS_RELATIVE_PATH", ""),
@@ -1403,6 +1471,11 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
         "renderOnly": ctx.get("RENDER_ONLY", ""),
         "createdAt": ctx.get("RUN_TIMESTAMP_ISO", ""),
     }
+    scope_confirmation = existing_run_manifest.get("analysisScopeConfirmation")
+    if "analysisScopeConfirmation" not in existing_run_manifest:
+        scope_confirmation = _analysis_scope_confirmation_snapshot(ctx)
+    if scope_confirmation is not None:
+        payload["analysisScopeConfirmation"] = scope_confirmation
     if ctx.get("FIX_CYCLE_ID"):
         payload["fixCycleId"] = ctx["FIX_CYCLE_ID"]
     payload["reportContracts"] = (

package/runtime/python/okstra_ctl/render_final_report.py

@@ -67,7 +67,7 @@ class FinalReportRenderError(RuntimeError):
 
 
 def _format_int(value: Any) -> str:
-    if value is None:
+    if value is None or not isinstance(value, (str, int, float)):
         return "--"
     try:
         return f"{int(value):,}"
@@ -76,7 +76,7 @@ def _format_int(value: Any) -> str:
 
 
 def _format_usd(value: Any) -> str:
-    if value is None:
+    if value is None or not isinstance(value, (str, int, float)):
         return "--"
     try:
         return f"${float(value):.2f}"
@@ -85,7 +85,7 @@ def _format_usd(value: Any) -> str:
 
 
 def _format_duration_ms(value: Any) -> str:
-    if value is None:
+    if value is None or not isinstance(value, (str, int, float)):
         return "--"
     try:
         ms = int(value)
@@ -583,10 +583,16 @@ def resolve_report_language(data: dict, *, override: str | None) -> str:
 # through, `| length` raises on it, and both `x` and `not x` evaluate true. So a
 # template cannot test for absence at all, and the value has to arrive filled.
 _OPTIONAL_ARRAY_DEFAULTS = ("endStateCoverage",)
+_OPTIONAL_ANALYSIS_DEFAULTS = (
+    "analysisCommon",
+    "projectAnalysis",
+    "featureAnalysis",
+    "changeImpactAnalysis",
+)
 
 
 def _with_optional_defaults(data: dict) -> dict:
-    """Render context with schema-optional arrays filled in.
+    """Render context with schema-optional fields filled in.
 
     Keeps the schema field optional — an omitted `endStateCoverage` stays absent
     in data.json, which is what the run validator reads to tell a legacy brief
@@ -597,6 +603,9 @@ def _with_optional_defaults(data: dict) -> dict:
     for key in _OPTIONAL_ARRAY_DEFAULTS:
         if not isinstance(filled.get(key), list):
             filled[key] = []
+    for key in _OPTIONAL_ANALYSIS_DEFAULTS:
+        if not isinstance(filled.get(key), dict):
+            filled[key] = None
     return filled