okstra 0.172.0 → 0.173.0

package/runtime/python/okstra_ctl/report_html/render.py

@@ -9,7 +9,7 @@ from pathlib import Path
 import okstra_vendor  # noqa: F401  # registers vendored dependency aliases
 from jinja2 import Environment, FileSystemLoader, StrictUndefined, select_autoescape
 
-from ..final_report_paths import translation_sidecar_path
+from ..final_report_paths import final_report_data_path, translation_sidecar_path
 from ..final_report_schema import load_schema_for_data, validate
 from ..i18n import HTML_DICTIONARY_REL, load_dictionary, make_jinja_global
 from ..report_translation import overlay
@@ -142,11 +142,13 @@ def render_v2_html_view(
     env.filters["paragraphs"] = lambda value: paragraphs(value, anchors)
     response_js = (root / "report.js").read_text(encoding="utf-8")
     base_js = (root / "html/assets/base.js").read_text(encoding="utf-8")
+    source_data = final_report_data_path(Path(run_meta.source_report)).as_posix()
     context = {
         **view.context,
         "runMeta": run_meta,
         "reportMeta": _report_meta(data, run_meta),
         "taskType": view.task_type,
+        "sourceData": source_data,
         "dataSha256": _sha256(data_path),
         "markdownSha256": _sha256(markdown_path),
         "clarificationItems": data.get("clarificationItems", []),
@@ -161,7 +163,7 @@ def render_v2_html_view(
     output_path.write_text(
         inject_report_index(document, label=translate("base.contents")), encoding="utf-8"
     )
-    if context["clarificationItems"]:
+    if context["clarificationItems"] or context.get("directionSelection"):
         # The footer tells the reader to drop the exported file here, so the
         # directory has to exist before they go looking for it.
         user_responses_dir_for_report(data_path).mkdir(parents=True, exist_ok=True)

package/runtime/python/okstra_ctl/report_html/router.py

@@ -8,6 +8,9 @@ from .view_models.error_analysis import build_error_analysis_view
 from .view_models.feature_analysis import build_feature_analysis_view
 from .view_models.final_verification import build_final_verification_view
 from .view_models.improvement_discovery import build_improvement_discovery_view
+from .view_models.implementation_option_selection import (
+    build_implementation_option_selection_view,
+)
 from .view_models.implementation import build_implementation_view
 from .view_models.implementation_planning import build_implementation_planning_view
 from .view_models.project_analysis import build_project_analysis_view
@@ -23,6 +26,7 @@ VIEW_BUILDERS = {
     "requirements-discovery": build_requirements_discovery_view,
     "improvement-discovery": build_improvement_discovery_view,
     "error-analysis": build_error_analysis_view,
+    "implementation-option-selection": build_implementation_option_selection_view,
     "project-analysis": build_project_analysis_view,
     "feature-analysis": build_feature_analysis_view,
     "change-impact-analysis": build_change_impact_analysis_view,

package/runtime/python/okstra_ctl/report_html/view_models/implementation_option_selection.py

@@ -0,0 +1,32 @@
+"""Human-first implementation-direction comparison view."""
+from __future__ import annotations
+
+from ..common import evidence_index
+from ..models import HumanReportView
+
+
+def build_implementation_option_selection_view(data: dict) -> HumanReportView:
+    selection = data["implementationOptionSelection"]
+    context = {
+        "humanSummary": data["humanSummary"],
+        "selection": selection,
+        "directionSelection": (
+            selection if selection["mode"] == "candidate-comparison" else None
+        ),
+        "narrative": selection["userNarrative"],
+        "recommendedOption": next(
+            (
+                option
+                for option in selection["rankedOptions"]
+                if option["id"] == selection["recommendedOptionId"]
+            ),
+            None,
+        ),
+        "evidenceIndex": evidence_index(data),
+    }
+    return HumanReportView(
+        task_type="implementation-option-selection",
+        template_name="html/tasks/implementation-option-selection.template.html",
+        context=context,
+        figures=(),
+    )

package/runtime/python/okstra_ctl/report_html/view_models/implementation_planning.py

@@ -15,6 +15,8 @@ class PlanApprovalState:
     recommended_option: str
     disabled_reason: str
     blocker_ids: tuple[str, ...]
+    show_option_selector: bool = True
+    reentry_command: str = ""
 
 
 def resolve_recommended_option(rec_name: str, names: tuple[str, ...]) -> str:
@@ -32,6 +34,26 @@ def plan_approval_state(data: dict) -> PlanApprovalState | None:
     planning = data.get("implementationPlanning")
     if not isinstance(planning, dict):
         return None
+    blockers = tuple(
+        row["id"]
+        for row in data.get("clarificationItems", [])
+        if row.get("blocks") == "approval"
+        and row.get("status") in {"open", "answered"}
+    )
+    reason = f"{len(blockers)} approval blocker(s) unresolved" if blockers else ""
+    if planning.get("planningContract") == "selected-direction":
+        if planning.get("outcome") == "direction-invalidated" and not reason:
+            reason = "selected direction invalidated"
+        task_key = (data.get("header") or {}).get("taskKey", "")
+        reentry_command = (
+            f"/okstra-run task-key={task_key} "
+            "task-type=implementation-option-selection"
+            if planning.get("outcome") == "direction-invalidated" and task_key
+            else ""
+        )
+        return PlanApprovalState(
+            (), "", reason, blockers, False, reentry_command
+        )
     names = tuple(
         row["name"]
         for row in planning.get("optionCandidates", [])
@@ -40,13 +62,6 @@ def plan_approval_state(data: dict) -> PlanApprovalState | None:
     if not names:
         return None
     recommended = planning.get("recommendedOption", {}).get("name", "")
-    blockers = tuple(
-        row["id"]
-        for row in data.get("clarificationItems", [])
-        if row.get("blocks") == "approval"
-        and row.get("status") in {"open", "answered"}
-    )
-    reason = f"{len(blockers)} approval blocker(s) unresolved" if blockers else ""
     return PlanApprovalState(
         names,
         resolve_recommended_option(recommended, names),
@@ -89,7 +104,7 @@ _OMITTED_FIELDS = (
 
 def build_implementation_planning_view(data: dict) -> HumanReportView:
     planning = data["implementationPlanning"]
-    figure = _stage_figure(planning)
+    figure = _stage_figure(planning) if planning.get("stageMap") else None
     approval = plan_approval_state(data)
     activities = tuple(
         row for row in data.get("agentActivity", []) if isinstance(row, dict)
@@ -104,7 +119,7 @@ def build_implementation_planning_view(data: dict) -> HumanReportView:
     context = {
         "humanSummary": data["humanSummary"],
         "planning": planning,
-        "narrative": planning["userNarrative"],
+        "narrative": planning.get("userNarrative", {}),
         "stageFigure": figure,
         "approval": approval,
         "openDecisions": [
@@ -125,6 +140,6 @@ def build_implementation_planning_view(data: dict) -> HumanReportView:
         "implementation-planning",
         "html/tasks/implementation-planning.template.html",
         context,
-        (figure,),
+        (figure,) if figure is not None else (),
         _OMITTED_FIELDS,
     )

package/runtime/python/okstra_ctl/report_views.py

@@ -111,6 +111,8 @@ class RunMeta:
     task_type: str
     seq: str
     source_report: str  # relative path of the .md the HTML is derived from
+    source_data: str = ""
+    source_data_sha256: str = ""
 
 
 @dataclass(frozen=True)
@@ -154,7 +156,9 @@ def _infer_run_meta_from_body(text: str) -> dict:
 
 def infer_run_meta(report_path: Path, *, task_key: Optional[str] = None,
                    task_type: Optional[str] = None, seq: Optional[str] = None,
-                   source_report: Optional[str] = None) -> RunMeta:
+                   source_report: Optional[str] = None,
+                   source_data: Optional[str] = None,
+                   source_data_sha256: Optional[str] = None) -> RunMeta:
     """Derive a ``RunMeta`` from a final-report path/body, honouring any
     explicit override.
 
@@ -166,11 +170,22 @@ def infer_run_meta(report_path: Path, *, task_key: Optional[str] = None,
     """
     text = report_path.read_text(encoding="utf-8")
     inferred = {**_infer_run_meta_from_path(report_path), **_infer_run_meta_from_body(text)}
+    resolved_source_report = source_report or report_path.name
+    data_path = final_report_data_path(report_path)
+    inferred_source_data = ""
+    inferred_source_data_sha256 = ""
+    if data_path.is_file():
+        inferred_source_data = final_report_data_path(
+            Path(resolved_source_report)
+        ).as_posix()
+        inferred_source_data_sha256 = hashlib.sha256(data_path.read_bytes()).hexdigest()
     return RunMeta(
         task_key=task_key or inferred.get("task_key") or "unknown",
         task_type=task_type or inferred.get("task_type") or "unknown",
         seq=seq or inferred.get("seq") or "000",
-        source_report=source_report or report_path.name,
+        source_report=resolved_source_report,
+        source_data=source_data or inferred_source_data,
+        source_data_sha256=source_data_sha256 or inferred_source_data_sha256,
     )
 
 
@@ -271,6 +286,32 @@ def render_report_view_model(
     sidecar_name = html.escape(model.sidecar_name)
     sidecar_dir = html.escape(model.sidecar_dir)
     run_meta = model.run_meta
+    source_data_json = (
+        f'"source-data":"{html.escape(run_meta.source_data)}",'
+        if run_meta.source_data else ""
+    )
+    source_data_sha256_json = (
+        f'"source-data-sha256":"{html.escape(run_meta.source_data_sha256)}",'
+        if run_meta.source_data_sha256 else ""
+    )
+    reentry_only = bool(
+        model.approval_ctx and model.approval_ctx.reentry_command
+    )
+    export_header = (
+        '  <button type="button" data-action="export-user-response">Export user response</button>\n'
+        if not reentry_only else ""
+    )
+    export_footer = (
+        f'<footer class="report-footer">\n'
+        f'  <button type="button" data-action="export-user-response">Export user response</button>\n'
+        f'  <p class="user-response-hint">Export 클릭 시 <code>{sidecar_name}</code> 가 다운로드됩니다 — '
+        f'<code>{sidecar_dir}</code> 에 저장하면 resume-clarification 이 자동으로 첨부합니다.</p>\n'
+        f'  <pre id="user-response-output" aria-live="polite"></pre>\n'
+        f'  <button type="button" data-action="copy-user-response">Copy</button>\n'
+        f'  <button type="button" data-action="dismiss-user-response" class="user-response-dismiss" aria-label="출력 닫기" title="닫기" hidden>×</button>\n'
+        f'</footer>\n'
+        if not reentry_only else ""
+    )
     return (
         f"<!DOCTYPE html>\n"
         f"<html lang=\"ko\">\n"
@@ -283,24 +324,19 @@ def render_report_view_model(
         f"<body>\n"
         f"<header class=\"report-header\">\n"
         f"  <div>{title}</div>\n"
-        f"  <button type=\"button\" data-action=\"export-user-response\">Export user response</button>\n"
+        f"{export_header}"
         f"</header>\n"
         f"<main>{_reader_dashboard(model.reader_ctx)}{model.body_html}</main>\n"
         f"{_plan_approval_section(model.approval_ctx, run_meta) if model.approval_ctx else ''}"
         f"{_analysis_review_section(model.analysis_review_ctx) if model.analysis_review_ctx else ''}"
-        f"<footer class=\"report-footer\">\n"
-        f"  <button type=\"button\" data-action=\"export-user-response\">Export user response</button>\n"
-        f"  <p class=\"user-response-hint\">Export 클릭 시 <code>{sidecar_name}</code> 가 다운로드됩니다 — "
-        f"<code>{sidecar_dir}</code> 에 저장하면 resume-clarification 이 자동으로 첨부합니다.</p>\n"
-        f"  <pre id=\"user-response-output\" aria-live=\"polite\"></pre>\n"
-        f"  <button type=\"button\" data-action=\"copy-user-response\">Copy</button>\n"
-        f"  <button type=\"button\" data-action=\"dismiss-user-response\" class=\"user-response-dismiss\" aria-label=\"출력 닫기\" title=\"닫기\" hidden>×</button>\n"
-        f"</footer>\n"
+        f"{export_footer}"
         f"<script id=\"run-meta\" type=\"application/json\">"
         f"{{\"task-key\":\"{html.escape(run_meta.task_key)}\","
         f"\"task-type\":\"{html.escape(run_meta.task_type)}\","
         f"\"seq\":\"{html.escape(run_meta.seq)}\","
         f"\"source-report\":\"{html.escape(run_meta.source_report)}\","
+        f"{source_data_json}"
+        f"{source_data_sha256_json}"
         f"\"source-sha256\":\"{model.source_digest}\","
         f"\"response-ids\":{response_ids_json}}}"
         f"</script>\n"
@@ -1062,6 +1098,15 @@ class UserPlanDecision:
     reason: str = ""
 
 
+@dataclass(frozen=True)
+class UserDirectionSelection:
+    option_id: str
+    option_name: str
+    confirmed: bool
+    selection_note: str = ""
+    constraints: str = ""
+
+
 @dataclass(frozen=True)
 class UserResponseAnalysisReview:
     status: str
@@ -1084,6 +1129,44 @@ _PLAN_DECISION_STATUSES = frozenset({
     "rejected",
 })
 
+_DIRECTION_IDENTITY_WHITESPACE = frozenset(
+    "\u0009\u000a\u000b\u000c\u000d"
+    "\u001c\u001d\u001e\u001f\u0020\u0085\u00a0\u1680"
+    "\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200a"
+    "\u2028\u2029\u202f\u205f\u3000\ufeff"
+)
+_DIRECTION_IDENTITY_ERROR = (
+    "DIRECTION SELECTION Option-ID and Option-Name must be "
+    "non-empty single-line values"
+)
+
+
+def _trim_direction_identity(value: str) -> str:
+    start = 0
+    end = len(value)
+    while start < end and value[start] in _DIRECTION_IDENTITY_WHITESPACE:
+        start += 1
+    while end > start and value[end - 1] in _DIRECTION_IDENTITY_WHITESPACE:
+        end -= 1
+    return value[start:end]
+
+
+def normalize_direction_selection_identity(
+    option_id: str, option_name: str,
+) -> tuple[str, str]:
+    if (
+        "\r" in option_id
+        or "\n" in option_id
+        or "\r" in option_name
+        or "\n" in option_name
+    ):
+        raise ValueError(_DIRECTION_IDENTITY_ERROR)
+    normalized_id = _trim_direction_identity(option_id)
+    normalized_name = _trim_direction_identity(option_name)
+    if not normalized_id or not normalized_name:
+        raise ValueError(_DIRECTION_IDENTITY_ERROR)
+    return normalized_id, normalized_name
+
 
 def _quoted_sidecar_field(label: str, value: str) -> str:
     cleaned = value.strip()
@@ -1125,6 +1208,23 @@ def _serialize_plan_decision(decision: UserPlanDecision) -> str:
     return chunk
 
 
+def _serialize_direction_selection(selection: UserDirectionSelection) -> str:
+    option_id, option_name = normalize_direction_selection_identity(
+        selection.option_id, selection.option_name
+    )
+    if not selection.confirmed:
+        raise ValueError("DIRECTION SELECTION requires Confirmed: true")
+    return (
+        "\n## DIRECTION SELECTION\n"
+        "- Status: selected\n"
+        f"- Option-ID: {option_id}\n"
+        f"- Option-Name: {option_name}\n"
+        "- Confirmed: true\n"
+        f"{_quoted_sidecar_field('Selection-Note', selection.selection_note)}"
+        f"{_quoted_sidecar_field('Constraints', selection.constraints)}"
+    )
+
+
 def serialize_user_response(
     *,
     run_meta: RunMeta,
@@ -1132,18 +1232,27 @@ def serialize_user_response(
     created_at: str,
     plan_decision: UserPlanDecision | None = None,
     analysis_review: UserResponseAnalysisReview | None = None,
+    direction_selection: UserDirectionSelection | None = None,
 ) -> str:
     """Return the canonical markdown text the HTML 'Export user
     response' button must produce. Used by validators to confirm that
     pasted sidecar files conform to the schema and that the JS
     serialiser stayed in sync.
     """
+    source_data_lines = ""
+    if run_meta.source_data:
+        source_data_lines += f"source-data: {run_meta.source_data}\n"
+    if run_meta.source_data_sha256:
+        source_data_lines += (
+            f"source-data-sha256: {run_meta.source_data_sha256}\n"
+        )
     head = (
         "---\n"
         f"task-key: {run_meta.task_key}\n"
         f"task-type: {run_meta.task_type}\n"
         f"seq: {run_meta.seq}\n"
         f"source-report: {run_meta.source_report}\n"
+        f"{source_data_lines}"
         "created-by: user\n"
         f"created-at: {created_at}\n"
         "---\n"
@@ -1152,6 +1261,7 @@ def serialize_user_response(
     )
     has_plan_decision = plan_decision is not None
     has_analysis_review = analysis_review is not None
+    has_direction_selection = direction_selection is not None
     body_chunks: list[str] = []
     for e in entries:
         chunk = f"\n## {e.response_id}\n- Kind: {e.kind}\n"
@@ -1162,12 +1272,19 @@ def serialize_user_response(
         if e.rationale:
             chunk += f"- Rationale: {e.rationale.strip()}\n"
         body_chunks.append(chunk)
-    if not entries and not has_plan_decision and not has_analysis_review:
+    if (
+        not entries
+        and not has_plan_decision
+        and not has_analysis_review
+        and not has_direction_selection
+    ):
         body_chunks.append("\n_(No user responses recorded.)_\n")
     if plan_decision is not None:
         body_chunks.append(_serialize_plan_decision(plan_decision))
     if analysis_review is not None:
         body_chunks.append(_serialize_analysis_review(analysis_review))
+    if direction_selection is not None:
+        body_chunks.append(_serialize_direction_selection(direction_selection))
     return head + "".join(body_chunks)
 
 
@@ -1263,6 +1380,8 @@ def plan_approval_context(src_md_path: Path) -> PlanApprovalContext | None:
         recommended_option=state.recommended_option,
         disabled_reason=reason,
         blocker_ids=blocker_ids,
+        show_option_selector=state.show_option_selector,
+        reentry_command=state.reentry_command,
     )
 
 
@@ -1352,6 +1471,16 @@ def _approval_blocked_guidance(ctx: PlanApprovalContext, run_meta: RunMeta) -> s
     """disabled 사유를 화면에서 바로 따라할 수 있는 단계별 안내로 렌더한다.
     핵심: 이 화면에서 답을 입력하는 것만으로는 승인이 풀리지 않으며,
     Export → 저장 → resume-clarification → 재렌더 라운드트립이 필요하다는 것."""
+    if ctx.reentry_command:
+        command = (
+            f"/okstra-run task-key={run_meta.task_key} "
+            "task-type=implementation-option-selection"
+        )
+        return (
+            '<p class="approval-disabled-reason">선택 방향이 무효화되어 이 계획은 '
+            "승인할 수 없습니다. 구현 방향 선택 단계에 다시 진입하세요: "
+            f"<code>{html.escape(command)}</code></p>"
+        )
     if not ctx.blocker_ids:  # unreadable 사유 — 재렌더 외에 따라할 단계가 없다.
         return f'<p class="approval-disabled-reason">{html.escape(ctx.disabled_reason)}</p>'
     sidecar_dir = f"runs/{run_meta.task_type}/user-responses/"
@@ -1379,6 +1508,13 @@ def _approval_blocked_guidance(ctx: PlanApprovalContext, run_meta: RunMeta) -> s
 
 
 def _plan_approval_section(ctx: PlanApprovalContext, run_meta: RunMeta) -> str:
+    if ctx.reentry_command:
+        return (
+            '<section id="plan-approval">\n'
+            "  <h2>선택 방향 무효화</h2>\n"
+            f"  {_approval_blocked_guidance(ctx, run_meta)}\n"
+            "</section>\n"
+        )
     disabled = " disabled" if ctx.disabled_reason else ""
     opts: list[str] = []
     for name in ctx.option_names: