okstra 0.206.0 → 0.206.1

package/runtime/python/okstra_ctl/profile_show.py

@@ -19,7 +19,7 @@ import sys
 from pathlib import Path
 
 from .paths import find_asset_root
-from .phases.catalog import PhaseAssetError, UnknownTaskType, profile_markdown
+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
 
@@ -29,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:
@@ -77,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/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,24 @@ 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 .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
 
@@ -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_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_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

@@ -41,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,