okstra 0.146.0 → 0.147.0

package/runtime/python/okstra_ctl/report_views.py

@@ -35,6 +35,11 @@ from pathlib import Path
 from typing import Iterable, Optional
 
 from .final_report_paths import final_report_data_path
+from .report_html.view_models.implementation_planning import (
+    PlanApprovalState,
+    plan_approval_state,
+    resolve_recommended_option,
+)
 from .report_view_artifacts import html_view_path, user_responses_dir_for_report
 
 
@@ -1142,16 +1147,7 @@ def report_has_clarification_items(src_md: str) -> bool:
     )
 
 
-@dataclass(frozen=True)
-class PlanApprovalContext:
-    """Plan Approval 위젯 렌더 입력. ``disabled_reason`` 이 비어 있지 않으면
-    위젯은 disabled 로 렌더된다 (run-prep 승인 게이트와 동일한 fail-closed 기준).
-    ``blocker_ids`` 는 §1 미해소 승인-차단 항목 ID 목록 — 화면 안내가 사용자에게
-    '어느 항목을 답해야 하는지' 를 보여주는 데 쓴다 (unreadable 사유면 빈 튜플)."""
-    option_names: tuple[str, ...]
-    recommended_option: str
-    disabled_reason: str
-    blocker_ids: tuple[str, ...]
+PlanApprovalContext = PlanApprovalState
 
 
 def _load_report_data(src_md_path: Path) -> dict | None:
@@ -1210,31 +1206,21 @@ def plan_approval_context(
     data = _load_report_data(src_md_path)
     if data is None:
         return None
-    planning = data.get("implementationPlanning")
-    if not isinstance(planning, dict):
+    state = plan_approval_state(data)
+    if state is None:
         return None
-    names = tuple(
-        c.get("name", "")
-        for c in (planning.get("optionCandidates") or [])
-        if isinstance(c, dict) and c.get("name")
-    )
-    if not names:
-        return None
-    rec = planning.get("recommendedOption")
-    rec_name = rec.get("name") or "" if isinstance(rec, dict) else ""
-    recommended = _resolve_recommended_option(rec_name, names)
     scan = scan_approval_gate(src_text)
-    blocker_ids: tuple[str, ...] = ()
+    blocker_ids = state.blocker_ids
+    reason = state.disabled_reason
     if scan.unreadable_reason:
+        blocker_ids = ()
         reason = "§1 승인 게이트를 읽을 수 없어 승인이 비활성화되었습니다 — 보고서를 재렌더하세요."
     elif scan.blockers:
         blocker_ids = tuple(b.row_id for b in scan.blockers)
         reason = f"§1 승인 차단 항목 {len(scan.blockers)}건 미해소"
-    else:
-        reason = ""
     return PlanApprovalContext(
-        option_names=names,
-        recommended_option=recommended,
+        option_names=state.option_names,
+        recommended_option=state.recommended_option,
         disabled_reason=reason,
         blocker_ids=blocker_ids,
     )
@@ -1318,22 +1304,8 @@ def _approval_label(data: dict, approval_ctx: PlanApprovalContext | None) -> str
 
 
 def _resolve_recommended_option(rec_name: str, names: tuple[str, ...]) -> str:
-    """``recommendedOption.name`` 을 후보 이름에 맞춘다. 정확 일치가 없으면
-    접두 일치(후보가 ``(RECOMMENDED)`` 같은 표식 접미를 더 달고 있는 흔한 경우)를
-    허용하되, 후보 이름이 서로의 접두여서 둘 이상이 매칭되면 모호하므로 채택하지
-    않고 첫 후보로 폴백한다 — 임의의 한 후보를 권장으로 잘못 표시하느니 결정적인
-    폴백이 낫다. 항상 정확히 한 옵션이 selected 가 되어 브라우저 자동선택분의 묵시
-    Export 를 차단한다."""
-    if rec_name in names:
-        return rec_name
-    if rec_name:
-        matches = [
-            name for name in names
-            if name.startswith(rec_name) or rec_name.startswith(name)
-        ]
-        if len(matches) == 1:
-            return matches[0]
-    return names[0]
+    """Compatibility wrapper for the shared v2 approval-state resolver."""
+    return resolve_recommended_option(rec_name, names)
 
 
 def _approval_blocked_guidance(ctx: PlanApprovalContext, run_meta: RunMeta) -> str:

package/runtime/python/okstra_ctl/run.py

@@ -53,13 +53,14 @@ from .material import (
     related_tasks_inline,
     resolve_related_tasks,
 )
-from .final_report_schema import load_schema
+from .final_report_schema import load_schema_version
 from .final_report_paths import final_report_data_path as _final_report_data_path
 from .lead_events import LeadEvent, append_lead_event
 from .lead_runtime import ALLOWED_LEAD_RUNTIMES
 from .model_discovery import normalize_execution_for_dispatch
 from .models import ModelAssignment, default_model, resolve_model_metadata
 from .schema_excerpt import build_schema_excerpt
+from .report_contract import CURRENT_REPORT_SCHEMA_VERSION
 from .path_resolve import relative_to_project_root, resolve_user_file
 from .render import (
     apply_lead_prompt_defaults,
@@ -264,11 +265,14 @@ def _set_data_json_approved_true_if_present(path: Path) -> bool:
     try:
         from .render_final_report import (
             FinalReportRenderError,
-            find_default_template,
+            find_default_template_for_data,
             render,
         )
 
-        rendered = render(data, template_path=find_default_template())
+        rendered = render(
+            data,
+            template_path=find_default_template_for_data(data),
+        )
     except FinalReportRenderError as exc:
         raise PrepareError(
             f"--approve could not re-render approved plan from data.json: {exc}"
@@ -892,7 +896,7 @@ def _resolve_runtime_assets(workspace_root: Path, inp: PrepareInputs) -> _Resolv
         workspace_root / "templates" / "project-docs" / "task-index.template.md"
     )
     final_report_template = (
-        workspace_root / "templates" / "reports" / "final-report.template.md"
+        workspace_root / "templates" / "reports" / "final-report-v2.template.md"
     )
     lead_contract = workspace_root / "prompts" / "lead" / "okstra-lead-contract.md"
     run_validator = workspace_root / "validators" / "validate-run.py"
@@ -1766,7 +1770,7 @@ def _render_lead_prompt_and_snapshot(
         str(final_report_template), ctx["FINAL_REPORT_TEMPLATE_PATH"], ctx,
     )
     # Per-task-type schema excerpt for the report-writer worker. The full
-    # schema validates the data.json post-hoc (load_schema); the worker only
+    # schema validates the data.json post-hoc; the worker only
     # needs the common structure + this run's task-type block, so we write a
     # scoped excerpt into the instruction-set rather than make the worker read
     # the whole 44 KB / all-task-types schema (whose repo `schemas/...` path is
@@ -1779,7 +1783,9 @@ def _render_lead_prompt_and_snapshot(
     # validation runs against the full schema regardless.
     try:
         _excerpt = build_schema_excerpt(
-            load_schema(), inp.task_type, installed_version()
+            load_schema_version(CURRENT_REPORT_SCHEMA_VERSION),
+            inp.task_type,
+            installed_version(),
         )
         Path(ctx["FINAL_REPORT_SCHEMA_PATH"]).write_text(
             json.dumps(_excerpt, indent=2, ensure_ascii=False) + "\n",

package/runtime/python/okstra_ctl/schema_excerpt.py

@@ -24,21 +24,10 @@ from __future__ import annotations
 import json
 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 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())
+from .report_contract import TASK_TYPE_DATA_PROPERTY
+
+
+_ALL_PER_TYPE_PROPERTIES = frozenset(TASK_TYPE_DATA_PROPERTY.values())
 _ANALYSIS_COMMON_TASK_TYPES = frozenset(
     {"project-analysis", "feature-analysis", "change-impact-analysis"}
 )
@@ -104,7 +93,7 @@ def build_schema_excerpt(schema: dict, task_type: str, cut_from_version: str = "
     itself in between, so a mismatch is what turns an opaque "additional
     property … not allowed" into "the bundle excerpt is from an older okstra".
     """
-    keep_per_type = _TASK_TYPE_PROPERTY.get(task_type)
+    keep_per_type = TASK_TYPE_DATA_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"}
@@ -130,10 +119,11 @@ def build_schema_excerpt(schema: dict, task_type: str, cut_from_version: str = "
         for k, v in schema.items()
         if k not in ("properties", "allOf", "$defs", "required", "description")
     }
+    schema_id = schema.get("$id", "the full final-report schema")
     excerpt["description"] = (
         f"Per-task-type excerpt of the okstra final-report schema, scoped to "
         f"`{task_type}`. Reading aid for the report-writer worker — validation "
-        f"runs against the full schema (schemas/final-report-v1.0.schema.json)."
+        f"runs against the full schema ({schema_id})."
     )
     excerpt["properties"] = props
     excerpt["required"] = [