okstra 0.205.1 → 0.206.1

package/runtime/python/okstra_ctl/profile_show.py

@@ -19,6 +19,7 @@ import sys
 from pathlib import Path
 
 from .paths import find_asset_root
+from .phases.catalog import PhaseAssetError, UnknownTaskType, profile_markdown, profile_sidecar
 from .role_requirements import RoleProfileError, load_role_profile
 from .run import PrepareError, _expand_profile_includes
 
@@ -28,7 +29,7 @@ _PROFILES_REL = ("prompts", "profiles")
 # `prompts/profiles/_implementation-executor.md`. Reading the list from the
 # profile body rather than hard-coding it here is deliberate: a list in code
 # goes stale the moment a profile adds a sidecar, and does so silently.
-_SIDECAR_RE = re.compile(r"`(prompts/profiles/_[\w-]+\.md)`")
+_SIDECAR_RE = re.compile(r"`((?:prompts/profiles|scripts/okstra_ctl/phases/implementation/instructions)/_[\w-]+\.md)`")
 
 
 def workspace_root(start: Path | None = None) -> Path:
@@ -44,7 +45,12 @@ def workspace_root(start: Path | None = None) -> Path:
 
 
 def profile_path(root: Path, task_type: str) -> Path:
-    path = root.joinpath(*_PROFILES_REL, f"{task_type}.md")
+    try:
+        path = profile_markdown(root, task_type)
+    except UnknownTaskType as exc:
+        raise PrepareError(f"unknown task-type: {task_type}") from exc
+    except PhaseAssetError as exc:
+        raise PrepareError(str(exc)) from exc
     if not path.is_file():
         raise PrepareError(f"unknown task-type: {task_type} (no {path})")
     return path
@@ -71,7 +77,7 @@ def sidecar_bodies(root: Path, profile_text: str) -> list[str]:
         if relative in seen:
             continue
         seen.add(relative)
-        path = root / relative
+        path = profile_sidecar(root, relative)
         if not path.is_file():
             continue
         body = _expand_profile_includes(path)

package/runtime/python/okstra_ctl/render.py

@@ -17,6 +17,8 @@ session id 등) 를 덧붙여 전달한다.
 
 from __future__ import annotations
 
+from .phases.catalog import profile_sidecar
+
 import hashlib
 import json
 import re
@@ -2632,7 +2634,7 @@ def inject_lead_prompt_computed_tokens(ctx: dict) -> None:
         home_prompts / "lead" / "convergence.md"
     )
     plan_body_verification_path = ctx.get("OKSTRA_PLAN_BODY_VERIFICATION_PATH") or str(
-        home_prompts / "lead" / "plan-body-verification.md"
+        profile_sidecar(home_prompts.parent, "prompts/lead/plan-body-verification.md")
     )
     report_writer_path = ctx.get("OKSTRA_REPORT_WRITER_PATH") or str(
         home_prompts / "lead" / "report-writer.md"
@@ -2971,7 +2973,12 @@ def render_template_with_ctx(template_path: str, output_path: str, ctx: dict) ->
     Optional defaults (VALIDATION_STATUS etc.) should be filled by calling
     `apply_lead_prompt_defaults(ctx)` in the same setup step.
     """
-    template = Path(template_path).read_text(encoding="utf-8")
+    from .phases.catalog import migrated_report_template
+
+    source = Path(template_path)
+    if source.parent.name == "reports" and source.parent.parent.name == "templates":
+        source = migrated_report_template(source.parent.parent.parent, source.name) or source
+    template = source.read_text(encoding="utf-8")
 
     fm_ctx = dict(ctx)
     fm_ctx.setdefault("DOC_TYPE", _doc_type_from_template_path(template_path))

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

@@ -2,9 +2,10 @@
 from __future__ import annotations
 
 import copy
-import json
 import os
 import tempfile
+from okstra_ctl.phases.implementation_planning.validation import validate_selected_direction_plan
+
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, Callable, Mapping, Sequence
@@ -25,22 +26,25 @@ from .report_synthesis_packet import (
 )
 from .conformance import strip_stage_declaration_label
 from .design_prep import DesignPrepError, materialize_design_prep_requests
-from .implementation_options import validate_blocked_answer_channel
-from .technical_verification import validate_technical_verification_report
+from .phases.implementation_option_selection.validation import validate_blocked_answer_channel
+from .phases.technical_verification.validation import validate_technical_verification_report
+from .report_routing import technical_verification_routing_errors
 from .implementation_direction import (
     load_selected_direction_snapshot,
-    validate_selected_direction_plan,
 )
 from .paths import task_dir
+from .phases.final_verification.report import verification_scope
 from .report_projections import (
     ReportProjectionError,
     project_convergence,
-    project_design,
     project_execution,
     project_token_usage,
 )
-from .scope_provenance import parse_source
-from .verification_target import read_verification_target
+from .phases.implementation_planning.report import (
+    attach_design_snapshot, _sync_human_summary_with_plan_body_gate,
+    _fill_end_state_coverage,
+)
+
 from .write_policy import planned_path_declaration_errors
 
 
@@ -355,8 +359,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(
@@ -689,15 +692,9 @@ def _attach_machine_planning(
     if design_row is None:
         return
     try:
-        design = project_design(planning, _read_json(design_row))
+        attach_design_snapshot(planning, _read_json(design_row))
     except ReportProjectionError as exc:
         _fail(design_row.owner, design_row.path, "$", exc)
-    planning["designPreparation"] = design["designPreparation"]
-    stages = {row.get("stage"): row for row in planning.get("stages") or [] if isinstance(row, dict)}
-    for coverage in design["stageCoverage"]:
-        stage = stages.get(coverage.get("stage"))
-        if stage is not None:
-            stage["designSurfaceCoverage"] = coverage.get("rows") or []
     verification_row = inputs.get("plan-body-verification")
     if verification_row is None:
         return
@@ -717,83 +714,6 @@ def _attach_machine_planning(
     _sync_human_summary_with_plan_body_gate(data, projection)
 
 
-def _sync_human_summary_with_plan_body_gate(
-    data: dict[str, Any], projection: Mapping[str, Any],
-) -> None:
-    """게이트가 통과했는데 내러티브가 unseeded 로 남으면 사람용 칸을 맞춘다.
-
-    report-writer 는 PBV 전에 쓰고, 조립이 게이트를 덮어씌운다. blockers 와
-    nextStep 이 그때의 문장을 그대로 두면 통과한 계획이 아직 검증 전으로 보인다.
-    """
-    gate = str(projection.get("gateResult") or "")
-    if gate not in {"passed", "passed-with-dissent"}:
-        return
-    summary = data.get("humanSummary")
-    if isinstance(summary, dict) and isinstance(summary.get("blockers"), list):
-        summary["blockers"] = [
-            row for row in summary["blockers"]
-            if "unseeded" not in str(row).lower()
-        ]
-    card = data.get("verdictCard")
-    if not isinstance(card, dict):
-        return
-    next_step = str(card.get("nextStep") or "")
-    lowered = next_step.lower()
-    if "unseeded" not in lowered and "seed" not in lowered:
-        return
-    next_step = (
-        "Plan-body verification passed. Do not start implementation "
-        "until `frontmatter.approved` is true."
-    )
-    card["nextStep"] = next_step
-    final = data.get("finalVerdict")
-    if isinstance(final, dict):
-        final["nextStep"] = next_step
-
-
-def _fill_end_state_coverage(data: dict[str, Any]) -> None:
-    """writer 가 못 쓴 endStateCoverage 를 requirementCoverage brief:EB-001 에서 채운다.
-
-    내러티브 스키마가 이 칸을 열어 주면 writer 가 쓸 수 있다. 비어 있으면
-    validate-run 이 brief id 마다 한 행을 요구하므로 조립이 채운다.
-    """
-    existing = data.get("endStateCoverage")
-    if isinstance(existing, list) and existing:
-        return
-    planning = data.get("implementationPlanning")
-    if not isinstance(planning, dict):
-        return
-    derived = _end_state_rows_from_requirement_coverage(planning)
-    if derived:
-        data["endStateCoverage"] = derived
-
-
-def _end_state_rows_from_requirement_coverage(
-    planning: Mapping[str, Any],
-) -> list[dict[str, Any]]:
-    rows: list[dict[str, Any]] = []
-    seen: set[str] = set()
-    for item in planning.get("requirementCoverage") or []:
-        if not isinstance(item, Mapping):
-            continue
-        ref = parse_source(str(item.get("source") or ""))
-        if not ref.is_end_state_id or ref.value in seen:
-            continue
-        seen.add(ref.value)
-        status = str(item.get("status") or "")
-        row: dict[str, Any] = {
-            "id": ref.value,
-            "disposition": "addressed" if status == "covered" else "deferred",
-            "coveredBy": str(item.get("id") or item.get("coveredBy") or ""),
-        }
-        if row["disposition"] != "addressed":
-            row["rationale"] = (
-                f"requirementCoverage `{item.get('id')}` status is `{status or 'empty'}`."
-            )
-        rows.append(row)
-    return rows
-
-
 def _schema_owner(error: str) -> str:
     field = error.split(" ", 1)[0]
     owners = {
@@ -897,6 +817,7 @@ def assemble_report(
     target = Path(value)
     target = target if target.is_absolute() else project_root / target
     verification_errors = validate_technical_verification_report(data, target, project_root)
+    verification_errors.extend(technical_verification_routing_errors(data))
     if verification_errors:
         raise ReportAssemblyError(tuple(
             AssemblyIssue("report-writer", str(target), "technicalVerification", error)

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

@@ -247,7 +247,7 @@ def approved_plan_links(
     except JsonBoundaryError:
         return {}
     from .common import anchor_index
-    from .view_models.implementation_planning import ANCHORED_FIELDS
+    from okstra_ctl.phases.implementation_planning.report import ANCHORED_FIELDS
 
     page = html_view_path(record)
     href = Path(os.path.relpath(page, data_path.resolve().parent)).as_posix()

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_projections.py

@@ -4,10 +4,8 @@ from __future__ import annotations
 from okstra_token_usage.blocks import accounting_workers
 
 import json
-from copy import deepcopy
-from typing import Any, Mapping, Sequence
+from typing import Any, Mapping
 
-from .design_surfaces import DesignSurfaceTrigger, detect_design_surfaces
 from .report_contract import execution_roles_from_manifest
 from .usage_cells import duration_ms_from_bounds
 
@@ -220,39 +218,6 @@ def project_token_usage(team_state: Mapping[str, Any]) -> dict[str, Any]:
     }
 
 
-def _trigger_rows(trigger: DesignSurfaceTrigger) -> list[dict[str, Any]]:
-    return [
-        {"step": item.step, "field": item.field, "match": item.match}
-        for item in trigger.evidence
-    ]
-
-
-def project_design(
-    planning: Mapping[str, Any], detector_snapshot: Mapping[str, Any],
-) -> dict[str, Any]:
-    """탐지 결과가 실제 계획 표면과 일치할 때만 설계 블록을 반환한다."""
-    triggers = detect_design_surfaces(planning)
-    expected = {(row.stage, row.kind): _trigger_rows(row) for row in triggers}
-    coverage = detector_snapshot.get("stageCoverage")
-    coverage = coverage if isinstance(coverage, list) else []
-    actual: dict[tuple[int, str], list[dict[str, Any]]] = {}
-    for stage in coverage:
-        if not isinstance(stage, Mapping):
-            raise ReportProjectionError("owner=design-surface-detector invalid stageCoverage row")
-        for row in stage.get("rows") or []:
-            if isinstance(row, Mapping):
-                actual[(int(stage.get("stage") or 0), str(row.get("kind") or ""))] = list(row.get("triggerEvidence") or [])
-    if expected != actual:
-        raise ReportProjectionError("owner=design-surface-detector trigger coverage mismatch")
-    preparation = detector_snapshot.get("designPreparation")
-    if not isinstance(preparation, Mapping):
-        raise ReportProjectionError("owner=design-surface-detector missing designPreparation")
-    return {
-        "designPreparation": deepcopy(dict(preparation)),
-        "stageCoverage": deepcopy(coverage),
-    }
-
-
 def _round_history(state: Mapping[str, Any]) -> dict[str, Any]:
     if not (state.get("config") or {}).get("enabled", True):
         return {"disabled": True}

package/runtime/python/okstra_ctl/report_routing.py

@@ -0,0 +1,23 @@
+"""보고서 생산 단계와 분리된 공통 이동 적합성 검사."""
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+
+def technical_verification_routing_errors(data: Mapping[str, Any]) -> list[str]:
+    """기술 검증의 후속 목적지가 후보 비교인지 검사하며 목적지를 추론하지 않는다."""
+    if (data.get("header") or {}).get("taskType") != "technical-verification":
+        return []
+    block = data.get("technicalVerification") or {}
+    if (block.get("routing") or {}).get("nextTaskType") != "implementation-option-selection":
+        return ["technical verification returns only to implementation-option-selection"]
+    return []
+
+
+def fanout_routing_errors(packet_name: str, target: str | None) -> list[str]:
+    """작업 분해 패킷의 후속 단계가 허용된 값인지 검사한다."""
+    allowed = ("error-analysis", "implementation-option-selection")
+    if target not in allowed:
+        return [f"{packet_name}: recommended-next-phase not in {allowed}"]
+    return []

package/runtime/python/okstra_ctl/report_synthesis_packet.py

@@ -15,22 +15,14 @@ from okstra_token_usage.blocks import accounting_workers
 
 from .analysis_packet import reference_source_extracts
 from .json_boundary import JsonBoundaryError, load_owned_object, write_owned_object_atomic
-from .implementation_options import (
-    CANDIDATE_COMPARISON_ROUTING,
-    EVALUATION_CRITERIA,
-    MAX_CRITERION_VALUE,
-    MAX_RANKED_OPTIONS,
-    MAX_RAW_CANDIDATES_PER_ANALYSER,
-    MIN_CRITERION_VALUE,
-    MIN_FEASIBLE_VOTES,
-    NO_VALID_OPTIONS_ROUTING,
+from .phases.implementation_option_selection.authoring import (
+    requirement_instructions as selection_requirement_instructions,
 )
 from .report_narrative import writer_owned_data, writer_owned_schema
 from .schema_excerpt import build_schema_excerpt
 from .stage_ledger import build_stage_ledger
 from .scope_provenance import brief_end_state_id_sequence
 
-from .exact_coverage import COVERAGE_VERDICT_PRECEDENCE
 from .final_report_schema import follow_up_task_rules, task_block_rules, verdict_token_rule
 from .report_contract import TASK_TYPE_DATA_PROPERTY
 from .report_markdown import humanise
@@ -251,70 +243,9 @@ class ReportSynthesisPacket:
             return self._planning_requirement_instructions()
         if self.task_type != "implementation-option-selection":
             return []
-        criteria = ", ".join(f"`{item}`" for item in EVALUATION_CRITERIA)
-        requirement_ids = ", ".join(
-            f"`{item}`" for item in self.original_requirement_ids
-        )
-        analysers = ", ".join(
-            f"`{item}`" for item in self.participating_analysers
+        return selection_requirement_instructions(
+            self.original_requirement_ids, self.participating_analysers,
         )
-        return [
-            f"Original requirement ids, in order: {requirement_ids}.",
-            f"Participating analysers: {analysers}.",
-            f"Evaluation criteria, in exact order: {criteria}.",
-            "Every `rankedOptions` and `candidateAudit` row must contain one "
-            "`requirementCoverage` row per original requirement id and one "
-            "`criterionScores` row per evaluation criterion. Weights and scores "
-            f"are integers from {MIN_CRITERION_VALUE} through {MAX_CRITERION_VALUE}; "
-            "`weightedScore` is the recalculated weighted mean.",
-            "`proposedBy` names exactly one participating analyser id, never a "
-            "list. Counting `rankedOptions` and `candidateAudit` together, each "
-            f"analyser may propose at most {MAX_RAW_CANDIDATES_PER_ANALYSER} raw "
-            "candidates and the run may hold at most "
-            f"{MAX_RAW_CANDIDATES_PER_ANALYSER} times the analyser count.",
-            "`coverageSummary` is recalculated from the row's `requirementCoverage` "
-            "statuses and `scopeCommitments`, and every field must equal the "
-            "recalculation: `totalCount` = number of original requirement ids; "
-            "`coveredCount` = rows with status `covered`; `coveragePercent` = "
-            "round(coveredCount / totalCount * 100, 2); `unmappedCommitments` = "
-            "commitment ids whose `requirementIds` is empty or names an id outside "
-            "the original set; `scopePrecisionPercent` = round((commitments - "
-            "unmapped) / commitments * 100, 2); `contradictedRequirements` = "
-            "original ids with status `contradicted`, in original order; "
-            "`coverageVerdict` = the first that applies of "
-            + ", ".join(f"`{verdict}`" for verdict in COVERAGE_VERDICT_PRECEDENCE)
-            + " (any contradicted; coveredCount below totalCount; any unmapped; "
-            "otherwise).",
-            "A ranked option is valid only when every participating analyser "
-            "supplied one feasibility vote, at least "
-            f"{MIN_FEASIBLE_VOTES} votes are `feasible`, and both `safetyBlockers` "
-            "and `unresolvedFeasibilityFacts` are empty.",
-            ("Classify each `unresolvedFeasibilityFacts` entry with `resolutionKind`: "
-            "`user-decision` requires nonempty `clarificationRefs` linking that fact "
-            "to actual C-NNN records, including answered records; `technical-verification` "
-            "requires no user question. Preserve the fact, whyItMatters, and evidence. "
-            "Historical unclassified facts remain readable but require classification "
-            "before blocked report reassembly. Saving does not lift blocked routing."),
-            ("After a linked decision is answered, preserve its disposition and selected "
-            "value. Update humanSummary.actions, verdictCard.nextStep, and selection "
-            "guidance to name remaining technical verification separately from unanswered "
-            "user decisions; never reopen an answered question to permit saving."),
-            "Each `feasibilityVotes` row states that analyser's own verdict, "
-            "rationale, and strongest counterevidence as its result gives them. "
-            "Two non-`uncertain` votes with identical rationale and "
-            "counterevidence are rejected as one worker's text copied under "
-            "another's name.",
-            f"Rank at most {MAX_RANKED_OPTIONS} valid options by descending "
-            "`requirement-fit`, `correctness-risk`, `architecture-fit`, "
-            "`weightedScore`, then id. With valid options set routing to "
-            f"`{CANDIDATE_COMPARISON_ROUTING}`; without a valid option use "
-            f"`{NO_VALID_OPTIONS_ROUTING}`.",
-            "In `candidate-comparison`, keep `preselectedDirection` null and do "
-            "not route directly to `implementation-planning`. In "
-            "`preselected-validation`, emit exactly one validated option, an empty "
-            "`candidateAudit`, a cited `preselectedDirection`, and routing "
-            "`implementation-planning`.",
-        ]
 
     def _planning_requirement_instructions(self) -> list[str]:
         """계획 저작 계약에 브리프 요구사항 id 순서를 박아 넣는다.

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_validation_identity.py

@@ -0,0 +1,38 @@
+"""보고서 검증 시 파일 이름에서 실행 식별자를 읽는다."""
+
+from pathlib import Path
+import re
+
+_REPORT_BASENAME_SEQ_RE = re.compile(r"-(?P<seq>\d{3})(?:\.data)?\.(?:md|json)$")
+
+
+_REPORT_BASENAME_TASK_TYPE_RE = re.compile(
+    r"^final-report-(?P<task_type>[a-z][a-z-]*?)-\d{3}(?:\.data)?\.(?:md|json)$"
+)
+
+
+def _report_run_seq(report_path: Path) -> str | None:
+    """This run's seq, read off `final-report-<task-type>-<seq>.md`. ``None``
+    when the name does not carry one, so callers fall back to not filtering
+    rather than silently checking nothing."""
+    match = _REPORT_BASENAME_SEQ_RE.search(report_path.name)
+    return match.group("seq") if match else None
+
+
+def _report_task_type(report_path: Path) -> str:
+    """This run's task type, read off `final-report-<task-type>-<seq>`.
+
+    The report's own `header.taskType` is the first source, but it is not
+    always reachable. `report_narrative._allowed_top_level()` has no `header` —
+    it is not a writer-owned block — so a gate scored from a narrative, which is
+    the only input a report-contract-3.0 run has before assembly, carries no
+    task type at all. Globbing with an empty one matched nothing and reported
+    every verdict as unbacked under a `runs//worker-results/` path.
+
+    The filename carries it in every caller: the full-run path passes the report
+    itself, and `_report_path_for_state` builds the same canonical name from the
+    state file. Returns `""` when the name does not carry one, so a caller can
+    tell "not resolvable" from a real task type.
+    """
+    match = _REPORT_BASENAME_TASK_TYPE_RE.match(report_path.name)
+    return match.group("task_type") if match else ""

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,
@@ -40,7 +41,7 @@ from .user_response_values import (  # noqa: F401 — 재노출(값 타입은 le
 )
 from .final_report_paths import final_report_data_path
 from .json_boundary import JsonBoundaryError, load_owned_object
-from .report_html.view_models.implementation_planning import (
+from .plan_approval import (
     PlanApprovalState,
     plan_approval_state,
     resolve_recommended_option,
@@ -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: