okstra 0.205.1 → 0.206.0

package/runtime/python/okstra_ctl/render_final_report.py

@@ -42,9 +42,10 @@ from typing import Any
 # registers ``markupsafe`` and ``jinja2`` aliases in ``sys.modules`` so
 # downstream ``from jinja2 import ...`` resolves to the vendored copy.
 import okstra_vendor  # noqa: F401 — side effect: sys.modules aliases
-from jinja2 import ChainableUndefined, Environment, FileSystemLoader
+from jinja2 import ChainableUndefined, Environment
 
 from okstra_ctl.clarification_items import USER_INPUT_BLOCKS, progress_blocking_ids
+from okstra_ctl.report_template_loader import report_template_loader
 from okstra_ctl.final_report_schema import (
     SchemaError,
     load_schema_for_data,
@@ -523,7 +524,7 @@ def _build_environment(template_dir: Path) -> Environment:
     # the renderer can't tell "the writer forgot this required field"
     # from "this field is intentionally absent on this task-type".
     env = Environment(
-        loader=FileSystemLoader(str(template_dir)),
+        loader=report_template_loader(template_dir),
         undefined=ChainableUndefined,
         trim_blocks=True,
         lstrip_blocks=True,

package/runtime/python/okstra_ctl/report_assembly.py

@@ -32,6 +32,7 @@ from .implementation_direction import (
     validate_selected_direction_plan,
 )
 from .paths import task_dir
+from .phases.final_verification.report import verification_scope
 from .report_projections import (
     ReportProjectionError,
     project_convergence,
@@ -40,7 +41,7 @@ from .report_projections import (
     project_token_usage,
 )
 from .scope_provenance import parse_source
-from .verification_target import read_verification_target
+
 from .write_policy import planned_path_declaration_errors
 
 
@@ -355,8 +356,7 @@ def _verification_scope(project_root: Path, manifest: Mapping[str, Any]) -> str:
     relative = str(manifest.get("verificationTargetPath") or "").strip()
     if not relative:
         return ""
-    target = read_verification_target(project_root, relative)
-    return str((target or {}).get("scope") or "").strip()
+    return verification_scope(project_root, relative)
 
 
 def _clarification_carry_in(

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

@@ -7,7 +7,7 @@ import sys
 from pathlib import Path
 
 import okstra_vendor  # noqa: F401  # registers vendored dependency aliases
-from jinja2 import Environment, FileSystemLoader, StrictUndefined, select_autoescape
+from jinja2 import Environment, StrictUndefined, select_autoescape
 
 from ..final_report_paths import final_report_data_path, translation_sidecar_path
 from ..final_report_schema import load_schema_for_data, validate
@@ -16,6 +16,7 @@ from ..report_translation import overlay
 from ..report_view_artifacts import user_responses_dir_for_report
 from ..usage_cells import format_duration_ms
 from ..json_boundary import load_owned_object
+from ..report_template_loader import report_template_loader
 from .common import anchor_index, worker_finding_links
 from .context_links import (
     approved_plan_links,
@@ -145,7 +146,7 @@ def render_v2_html_view(
     route = resolve_html_route(run_meta.task_type)
     view = route.view_builder(data)
     root = _templates_root(templates_root)
-    env = Environment(loader=FileSystemLoader(str(root)), autoescape=select_autoescape(("html",)), undefined=StrictUndefined)
+    env = Environment(loader=report_template_loader(root), autoescape=select_autoescape(("html",)), undefined=StrictUndefined)
     env.policies["json.dumps_kwargs"] = {"sort_keys": True, "ensure_ascii": False}
     # Binding the index here is what lets a template cite an id without
     # threading the index through every macro and call site. The record's

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

@@ -1,46 +1,22 @@
 """Fail-closed task-type routing for schema-v2 HTML views."""
 from __future__ import annotations
 
+import importlib
+
+from ..phases.catalog import UnknownTaskType, view_builder_import
 from ..report_contract import html_template_for
 from .models import HtmlRoute
-from .view_models.change_impact_analysis import build_change_impact_analysis_view
-from .view_models.error_analysis import build_error_analysis_view
-from .view_models.technical_verification import build_technical_verification_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
-from .view_models.release_handoff import build_release_handoff_view
-from .view_models.requirements_discovery import build_requirements_discovery_view
 
 
 class HtmlRenderError(ValueError):
     """Raised when a v2 task has no dedicated human view."""
 
 
-VIEW_BUILDERS = {
-    "technical-verification": build_technical_verification_view,
-    "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,
-    "implementation-planning": build_implementation_planning_view,
-    "implementation": build_implementation_view,
-    "final-verification": build_final_verification_view,
-    "release-handoff": build_release_handoff_view,
-}
-
-
 def resolve_html_route(task_type: str) -> HtmlRoute:
-    builder = VIEW_BUILDERS.get(task_type)
-    if builder is None:
-        raise HtmlRenderError(f"no v2 html view builder for {task_type}")
+    """선택한 작업 유형의 표시 함수만 적재한다."""
+    try:
+        module_name, function_name = view_builder_import(task_type)
+    except UnknownTaskType as exc:
+        raise HtmlRenderError(f"no v2 html view builder for {task_type}") from exc
+    builder = getattr(importlib.import_module(module_name), function_name)
     return HtmlRoute(template_name=html_template_for(task_type), view_builder=builder)

package/runtime/python/okstra_ctl/report_template_loader.py

@@ -0,0 +1,35 @@
+"""보고서 템플릿 로더.
+
+이전된 단계의 본문은 단계 ``report_assets/`` 에 있고, 공통 레이아웃과
+매크로는 ``templates/reports`` 에 남는다. 논리 이름은 그대로다.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import okstra_vendor  # noqa: F401  # registers vendored dependency aliases
+from jinja2 import BaseLoader, FileSystemLoader, TemplateNotFound
+
+from .phases.catalog import migrated_report_template
+
+
+class ReportTemplateLoader(BaseLoader):
+    """논리 템플릿 이름을 단계 정본 또는 공통 템플릿 트리에서 연다."""
+
+    def __init__(self, templates_root: Path) -> None:
+        self._root = templates_root
+        self._fallback = FileSystemLoader(str(templates_root))
+
+    def get_source(self, environment, template):
+        physical = migrated_report_template(self._root.parent.parent, template)
+        if physical is None:
+            return self._fallback.get_source(environment, template)
+        if not physical.is_file():
+            raise TemplateNotFound(template)
+        source = physical.read_text(encoding="utf-8")
+        mtime = physical.stat().st_mtime
+        return source, str(physical), lambda: physical.stat().st_mtime == mtime
+
+
+def report_template_loader(templates_root: Path) -> ReportTemplateLoader:
+    return ReportTemplateLoader(templates_root)

package/runtime/python/okstra_ctl/report_views.py

@@ -30,9 +30,10 @@ import hashlib
 import html
 import json
 import re
+from collections.abc import Mapping
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Iterable, Optional
+from typing import Any, Iterable, Optional
 
 from .user_response_values import (  # noqa: F401 — 재노출(값 타입은 leaf 소유)
     UserPlanDecision,
@@ -1164,6 +1165,21 @@ def normalize_direction_selection_identity(
     return normalized_id, normalized_name
 
 
+def direction_candidate_ineligibility(option: Mapping[str, Any]) -> str:
+    """Why a ranked candidate cannot become the planning direction, or ``""``.
+
+    The planning gate (`implementation_direction._selected_option`) and the
+    in-session picker (`user_response.set_direction_selection`) share this rule,
+    so a candidate the picker accepts is one the gate accepts.
+    """
+    coverage = option.get("coverageSummary")
+    if not isinstance(coverage, Mapping) or coverage.get("coverageVerdict") != "exact":
+        return "selected candidate must have exact coverage"
+    if option.get("safetyBlockers") or option.get("unresolvedFeasibilityFacts"):
+        return "selected candidate has a safety blocker"
+    return ""
+
+
 def _quoted_sidecar_field(label: str, value: str) -> str:
     cleaned = value.strip()
     if not cleaned:

package/runtime/python/okstra_ctl/run.py

@@ -19,7 +19,6 @@ from .technical_verification import (
     write_technical_verification_input,
 )
 
-import hashlib
 from argparse import (
     Action,
     ArgumentError,
@@ -217,6 +216,15 @@ from .workers import (
 from .workflow import compute_workflow_state, load_phase_forbidden
 from .locks import worktree_provision_mutex
 from . import stage_targets as _stage_targets
+from .phases.catalog import PhaseAssetError, profile_markdown, resolve_include
+from .phases.final_verification.target import acquire_final_verification_target
+from .phases.final_verification.entry import (
+    apply_verification_target,
+    reject_prepare_flags,
+    single_stage_worktree,
+    verification_target_request,
+    write_verification_target_snapshot,
+)
 from .plan_run_root import plan_run_root_from_approved_plan
 from . import implementation_stage as _implementation_stage
 from .work_categories import resolve_work_category
@@ -1215,8 +1223,11 @@ _HTML_COMMENT = re.compile(r"<!--.*?-->", re.DOTALL)
 def _expand_profile_includes(profile_path: Path, _depth: int = 0) -> str:
     """Resolve `{{INCLUDE:<name>}}` directives in a profile file.
 
-    Includes are resolved relative to the profile's directory. A maximum
-    recursion depth of 4 prevents accidental cycles; the included file
+    `phases.catalog.resolve_include` picks the search root: an unmigrated
+    profile resolves beside itself, and a phase package's `profile.md`
+    resolves through the logical paths of the asset root that holds it.
+    Recursion stops at depth 4
+    so a cycle fails instead of looping; the included file
     contents replace the directive line in-place. Missing include targets
     raise PrepareError so a bad reference fails fast instead of silently
     leaving a `{{INCLUDE:...}}` token in the rendered profile.
@@ -1235,7 +1246,10 @@ def _expand_profile_includes(profile_path: Path, _depth: int = 0) -> str:
 
     def _sub(match: "re.Match[str]") -> str:
         target_name = match.group(1).strip()
-        target = profile_path.parent / target_name
+        try:
+            target = resolve_include(profile_path, target_name)
+        except PhaseAssetError as exc:
+            raise PrepareError(str(exc)) from exc
         if not target.is_file():
             raise PrepareError(
                 f"profile include target missing: {target} (referenced from {profile_path})"
@@ -1289,7 +1303,10 @@ class _ResolvedAssets:
 
 def _resolve_runtime_assets(workspace_root: Path, inp: PrepareInputs) -> _ResolvedAssets:
     """task-type 별 profile + 공통 템플릿/스킬/validator 경로를 해소하고 존재를 확인한다."""
-    profile_file = workspace_root / "prompts" / "profiles" / f"{inp.task_type}.md"
+    try:
+        profile_file = profile_markdown(workspace_root, inp.task_type)
+    except PhaseAssetError as exc:
+        raise PrepareError(str(exc)) from exc
     if not profile_file.is_file():
         raise PrepareError(
             f"analysis profile file not found for task-type {inp.task_type}: "
@@ -1438,18 +1455,10 @@ def _validate_prepare_inputs(project_root: Path, inp: PrepareInputs) -> list:
                 "--approved-plan <path-to-final-report.md>"
             )
         if inp.task_type == "final-verification":
-            # final-verification 에서 --approve / --implementation-option 은
-            # 의미가 없다 (승인은 implementation 진입 시 이미 끝났다).
-            if inp.approve_plan_ack:
-                raise PrepareError(
-                    "--approve is only meaningful with --task-type implementation "
-                    "and --approved-plan <path>"
-                )
-            if inp.implementation_option:
-                raise PrepareError(
-                    "--implementation-option is only meaningful with --task-type "
-                    "implementation and --approved-plan <path>"
-                )
+            reject_prepare_flags(
+                approve_plan_ack=inp.approve_plan_ack,
+                implementation_option=inp.implementation_option,
+            )
             ctx_stage_map = _parse_stage_map_into_ctx(inp.approved_plan_path)
     else:
         if inp.approve_plan_ack:
@@ -3460,139 +3469,6 @@ def _git_out(cwd, *args) -> str:
     return r.stdout.strip() if r.returncode == 0 else ""
 
 
-def _single_stage_final_verification_worktree(inp: "PrepareInputs") -> WorktreeProvision:
-    """Placeholder until the selected stage registry row is resolved."""
-    return WorktreeProvision(
-        status="deferred-final-verification",
-        note=(
-            "final-verification single-stage uses the selected implementation "
-            "stage worktree from the registry"
-        ),
-    )
-
-
-def _format_integration(integ) -> str:
-    """stage 자동 통합 결과를 사람이 읽을 한국어 마크다운 블록으로 만든다."""
-    def _csv(xs):
-        return ", ".join(str(x) for x in xs) if xs else "없음"
-
-    skipped = "; ".join(f"stage {n}({why})" for n, why in integ.teardown_skipped)
-    lines = [
-        "- **Stage 자동 통합 결과** (whole-task final-verification):",
-        "- **머지된 stage:** " + _csv(integ.merged),
-        "- **이미 머지됨:** " + _csv(integ.already_merged),
-        "- **정리(teardown)된 stage:** " + _csv(integ.torn_down),
-        "- **정리 보류:** " + (skipped or "없음"),
-    ]
-    for w in integ.warnings:
-        lines.append("- **경고:** " + w)
-    return "\n".join(lines)
-
-
-def _final_verification_target_request(
-    inp: "PrepareInputs",
-    ctx_stage_map: list[dict],
-) -> _stage_targets.FinalVerificationTargetRequest:
-    stage = (
-        int(inp.stage)
-        if inp.stage and inp.stage != "auto"
-        else None
-    )
-    return _stage_targets.FinalVerificationTargetRequest(
-        project_root=Path(inp.project_root),
-        project_id=inp.project_id,
-        task_group=inp.task_group,
-        task_id=inp.task_id,
-        work_category=inp.work_category,
-        approved_plan_path=Path(inp.approved_plan_path),
-        stage=stage,
-        stage_map=tuple(ctx_stage_map),
-    )
-
-
-def _apply_final_verification_target(
-    ctx: dict,
-    acquisition: _stage_targets.FinalVerificationTargetAcquisition,
-) -> None:
-    """Translate acquired domain facts into render-context fields."""
-    target = acquisition.target
-    if target.scope == "single-stage":
-        stage = target.stages[0]
-        ctx["EXECUTOR_WORKTREE_PATH"] = target.worktree_path
-        ctx["EXECUTOR_WORKTREE_BRANCH"] = acquisition.worktree_branch
-        ctx["EXECUTOR_WORKTREE_BASE_REF"] = target.base
-        ctx["EXECUTOR_WORKTREE_STATUS"] = "reused-stage"
-        ctx["EXECUTOR_WORKTREE_NOTE"] = (
-            f"final-verification uses implementation stage {stage} worktree"
-        )
-    if acquisition.integration_result is not None:
-        ctx["STAGE_INTEGRATION"] = _format_integration(
-            acquisition.integration_result
-        )
-    if acquisition.relocations:
-        moved = "\n".join(
-            f"- stage {row['stage']}: `{row['from']}` → `{row['to']}`"
-            for row in acquisition.relocations
-        )
-        ctx["STAGE_INTEGRATION"] = (
-            f"{ctx.get('STAGE_INTEGRATION', '')}\n"
-            "Nested stage worktrees moved out of the verification worktree "
-            "(registry updated; contents and branches unchanged):\n"
-            f"{moved}"
-        ).strip()
-    diff_stat = _git_out(target.worktree_path, "diff", "--stat",
-                         f"{target.base}..{target.head}")
-    ctx["VERIFICATION_SCOPE"] = target.scope
-    ctx["VERIFICATION_WORKTREE_PATH"] = target.worktree_path
-    ctx["VERIFICATION_BASE_REF"] = target.base
-    ctx["VERIFICATION_HEAD_REF"] = target.head
-    ctx["VERIFICATION_TARGET"] = _format_verification_target(target, diff_stat)
-
-
-def _format_verification_target(
-    target: _stage_targets.FinalVerificationTarget,
-    diff_stat: str,
-) -> str:
-    reports = "\n".join(
-        f"  - stage {s}: `{rp or '(report_path unrecorded)'}`"
-        for s, rp in zip(target.stages, target.reports)
-    )
-    return (
-        f"- **Verification scope:** `{target.scope}`\n"
-        f"- **Worktree:** `{target.worktree_path}`\n"
-        f"- **Verification base ref:** `{target.base}`\n"
-        f"- **Verification head ref:** `{target.head}`\n"
-        f"- **Stages under verification:** {target.stages}\n"
-        f"- **Source implementation reports:**\n{reports}\n"
-        f"- **Verification diff stat:**\n```\n{diff_stat}\n```"
-    )
-
-
-def write_verification_target_snapshot(
-    instruction_set: Path,
-    target_markdown: str,
-) -> tuple[Path, str]:
-    """Persist one normalized final-verification target and return its digest."""
-    normalized = target_markdown.replace("\r\n", "\n").replace("\r", "\n")
-    normalized = normalized.rstrip() + "\n"
-    digest = "sha256:" + hashlib.sha256(normalized.encode("utf-8")).hexdigest()
-    path = instruction_set / "verification-target.md"
-    # 계산 규칙을 값과 함께 적는다. 워커는 이 다이제스트를 프롬프트 앵커로도
-    # 받는데, 규칙을 모르면 파일 전체 바이트로 재고 반드시 불일치를 본다 —
-    # 실측(2026-08-26): 그렇게 잰 검증자가 스냅샷이 변조됐다고 보고했다.
-    # 다이제스트 줄은 줄머리 앵커로 잘리므로(`_TARGET_DIGEST_RE`) 그 뒤에
-    # 붙는 이 줄은 본문에 들어가지 않는다.
-    path.write_text(
-        normalized
-        + f"- **Verification target digest:** `{digest}`\n"
-        + "- **Digest rule:** `sha256` of the text above this line, with CRLF "
-          "and CR normalized to LF, trailing whitespace stripped, and exactly "
-          "one closing newline. This line and the digest line are not covered.\n",
-        encoding="utf-8",
-    )
-    return path, digest
-
-
 def _write_verification_target_artifact(
     inp: PrepareInputs,
     ctx: dict,
@@ -4595,7 +4471,7 @@ def _provision_task_and_stage(
         okstra_home(), inp.project_id, task_group_segment, task_id_segment,
     ):
         if inp.task_type == "final-verification" and inp.stage and inp.stage != "auto":
-            worktree = _single_stage_final_verification_worktree(inp)
+            worktree = single_stage_worktree()
             # Single-stage final-verification namespaces its run path under
             # runs/final-verification/stage-<N> (same isolation as
             # implementation) so concurrent per-stage verifications never
@@ -5053,10 +4929,26 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         ctx["CLAUDE_RESUME_COMMAND_RELATIVE_PATH"] = ""
         ctx["CLAUDE_RESUME_COMMAND_FILENAME"] = ""
     if inp.task_type == "final-verification":
-        acquisition = _stage_targets.acquire_final_verification_target(
-            _final_verification_target_request(inp, ctx_stage_map)
+        acquisition = acquire_final_verification_target(
+            verification_target_request(
+                project_root=inp.project_root,
+                project_id=inp.project_id,
+                task_group=inp.task_group,
+                task_id=inp.task_id,
+                work_category=inp.work_category,
+                approved_plan_path=inp.approved_plan_path,
+                stage=inp.stage,
+                stage_map=ctx_stage_map,
+            )
+        )
+        target = acquisition.target
+        diff_stat = _git_out(
+            target.worktree_path,
+            "diff",
+            "--stat",
+            f"{target.base}..{target.head}",
         )
-        _apply_final_verification_target(ctx, acquisition)
+        apply_verification_target(ctx, acquisition, diff_stat)
 
     _write_bundle_artifacts(
         inp, ctx, project_root, lead_runtime, claude_session_id,