okstra 0.175.1 → 0.176.0

package/runtime/python/okstra_ctl/legacy_model_selection.py

@@ -83,7 +83,8 @@ def normalize_model_selection_inputs(
         report_writer_model=report_writer_model,
         provider_models=provider_models,
     )
-    _reject_source_conflicts(counts, models, legacy)
+    # 같은 값이면 정본을 남기고 레거시를 접는다. 다르면 prepare 전에 거부.
+    legacy = _reconcile_legacy_with_canonical(counts, models, legacy)
     merged_counts = {**counts, **legacy.role_counts}
     merged_models = {**models, **legacy.role_models}
     _validate_selection(profile, merged_counts, merged_models, counts)
@@ -171,7 +172,7 @@ def _legacy_selection(
         constraints[initial.role] = providers
         report_writer = _requirement(profile, "report-writer")
         if report_writer is not None:
-            counts["report-writer"] = report_writer.count
+            counts["report-writer"] = report_writer.recommended_count
         sources.append("--workers")
     worker_values = _parse_worker_models(worker_model, provider_models)
     if worker_values and initial is not None:
@@ -215,18 +216,14 @@ def _validate_legacy_workers(
     requirement: RoleRequirement,
     providers: tuple[str, ...],
 ) -> None:
-    maximum = requirement.count + requirement.optional_count
-    diversity = requirement.min_distinct_providers
-    if diversity is not None and len(set(providers)) < diversity:
-        raise ModelSelectionInputError(
-            "legacy --workers roster violates "
-            f"minDistinctProviders={diversity}; select at least {diversity} "
-            "providers or migrate to --role-model"
-        )
-    if len(providers) < requirement.count or len(providers) > maximum:
+    # minDistinctProviders 제거. 모델 참조 중복 거부는 Task 2.
+    if (
+        len(providers) < requirement.min_count
+        or len(providers) > requirement.max_count
+    ):
         raise ModelSelectionInputError(
             f"legacy --workers selects {len(providers)} {requirement.role} instances; "
-            f"profile requires {requirement.count}..{maximum}"
+            f"profile requires {requirement.min_count}..{requirement.max_count}"
         )
 
 
@@ -295,23 +292,109 @@ def _add_simple_legacy_roles(
         sources.append("executor")
 
 
-def _reject_source_conflicts(
+def _reconcile_legacy_with_canonical(
     canonical_counts: Mapping[str, int],
     canonical_models: Mapping[str, tuple[str, ...]],
     legacy: CanonicalModelSelection,
-) -> None:
+) -> CanonicalModelSelection:
+    """충돌하는 레거시 입력을 거부하고, 같은 값 겹침은 정본만 남긴다."""
     canonical_roles = set(canonical_counts) | set(canonical_models)
     legacy_roles = (
         set(legacy.role_counts)
         | set(legacy.provider_constraints)
         | set(legacy.legacy_model_values)
     )
-    conflicts = sorted(canonical_roles & legacy_roles)
-    if conflicts:
-        raise ModelSelectionInputError(
-            "canonical and legacy model selections conflict for role "
-            f"{conflicts[0]!r}"
+    overlap = sorted(canonical_roles & legacy_roles)
+    if not overlap:
+        return legacy
+
+    counts = dict(legacy.role_counts)
+    constraints = dict(legacy.provider_constraints)
+    values = {
+        role: dict(models)
+        for role, models in legacy.legacy_model_values.items()
+    }
+    for role in overlap:
+        if not _legacy_matches_canonical(
+            role,
+            canonical_counts,
+            canonical_models,
+            legacy,
+        ):
+            raise ModelSelectionInputError(
+                "canonical and legacy model selections conflict for role "
+                f"{role!r}"
+            )
+        # 정본 모델이 있으면 레거시 공급자 제약을 접어 materialize 덮어쓰기를 막는다.
+        if role in canonical_models:
+            constraints.pop(role, None)
+            values.pop(role, None)
+        if role in canonical_counts:
+            counts.pop(role, None)
+    return CanonicalModelSelection(
+        counts,
+        {},
+        constraints,
+        values,
+        legacy.legacy_sources,
+    )
+
+
+def _legacy_matches_canonical(
+    role: str,
+    canonical_counts: Mapping[str, int],
+    canonical_models: Mapping[str, tuple[str, ...]],
+    legacy: CanonicalModelSelection,
+) -> bool:
+    """레거시(--workers 등)가 변환 후 정본과 같은 값으로 수렴하는지 본다."""
+    leg_count = legacy.role_counts.get(role)
+    can_count = canonical_counts.get(role)
+    if can_count is not None and leg_count is not None and can_count != leg_count:
+        return False
+
+    leg_providers = legacy.provider_constraints.get(role)
+    can_models = canonical_models.get(role)
+    if can_models is not None and leg_providers is not None:
+        can_providers = tuple(
+            _provider_from_model_ref(model_ref) for model_ref in can_models
         )
+        if can_providers != tuple(
+            provider.lower() for provider in leg_providers
+        ):
+            return False
+        # 워커 목록은 칸 전체 순서다. 칸 수가 다르면 다른 선택이다.
+        if len(can_models) != len(leg_providers):
+            return False
+        leg_models = legacy.legacy_model_values.get(role, {})
+        for provider, model_ref in zip(leg_providers, can_models):
+            explicit = leg_models.get(provider)
+            if not explicit:
+                continue
+            model_id = (
+                model_ref.split("/", 1)[1] if "/" in model_ref else model_ref
+            )
+            if explicit != model_id and model_ref != f"{provider}/{explicit}":
+                return False
+        return True
+
+    if can_count is not None and leg_providers is not None:
+        if can_count != len(leg_providers):
+            return False
+    if (
+        can_models is not None
+        and leg_count is not None
+        and leg_providers is None
+        and len(can_models) > leg_count
+    ):
+        return False
+    return True
+
+
+def _provider_from_model_ref(model_ref: str) -> str:
+    provider, separator, _model = model_ref.partition("/")
+    if separator:
+        return provider.strip().lower()
+    return model_ref.strip().lower()
 
 
 def _validate_selection(
@@ -321,7 +404,7 @@ def _validate_selection(
     explicit_counts: Mapping[str, int],
 ) -> None:
     requirements = {row.role: row for row in profile.roles if not row.dynamic}
-    requirements["leader"] = RoleRequirement("leader", 1, "lead")
+    requirements["leader"] = RoleRequirement("leader", 1, 1, 1, "lead")
     for role in sorted(set(counts) | set(models)):
         requirement = requirements.get(role)
         if requirement is None:
@@ -334,7 +417,7 @@ def _validate_selection(
             requirement,
             explicit=role in explicit_counts,
         )
-        selected_count = counts.get(role, requirement.count)
+        selected_count = counts.get(role, requirement.recommended_count)
         model_count = len(models.get(role, ()))
         if model_count > selected_count:
             if role not in explicit_counts:
@@ -357,18 +440,19 @@ def _validate_role_count(
     if role not in counts:
         return
     count = counts[role]
-    maximum = requirement.count + requirement.optional_count
-    if explicit and requirement.optional_count == 0:
+    fixed = requirement.min_count == requirement.max_count
+    if explicit and fixed:
         raise ModelSelectionInputError(
             f"role {role!r} has a fixed quantity and cannot receive --role-count"
         )
-    if requirement.optional_count == 0 and count != requirement.count:
+    if fixed and count != requirement.min_count:
         raise ModelSelectionInputError(
-            f"role {role!r} has a fixed quantity of {requirement.count}"
+            f"role {role!r} has a fixed quantity of {requirement.min_count}"
         )
-    if count < requirement.count or count > maximum:
+    if count < requirement.min_count or count > requirement.max_count:
         raise ModelSelectionInputError(
-            f"role {role!r} count must be in {requirement.count}..{maximum}: {count}"
+            f"role {role!r} count must be in "
+            f"{requirement.min_count}..{requirement.max_count}: {count}"
         )
 
 
@@ -382,6 +466,7 @@ def serialize_host_session_context(context: HostSessionContext) -> str:
     payload = {
         "availableFunctions": sorted(context.available_functions),
         "currentModel": {
+            "effort": current.effort,
             "level": current.level,
             "normalizedModelRef": current.normalized_model_ref,
             "observedModel": current.observed_model,
@@ -439,6 +524,8 @@ def _deserialize_attestation(raw: object) -> CurrentSessionModelAttestation:
     )
     observed = _nullable_string(raw, "observedModel")
     normalized = _nullable_string(raw, "normalizedModelRef")
+    # 키 없으면 null. 호스트 어댑터가 아직 안 채운 경우를 허용한다.
+    effort = _nullable_string(raw, "effort")
     if level == "unknown" and (observed is not None or normalized is not None):
         raise ModelSelectionInputError("unknown currentModel must use null model fields")
     if level != "unknown" and normalized is None:
@@ -451,6 +538,7 @@ def _deserialize_attestation(raw: object) -> CurrentSessionModelAttestation:
         normalized,
         level,
         source,
+        effort,
     )
 
 

package/runtime/python/okstra_ctl/manager_sync.py

@@ -5,6 +5,7 @@ from pathlib import Path
 
 from okstra_project import TASKS_RELATIVE, StateError, parse_task_key, read_task_catalog, read_task_manifest, slugify
 
+from . import next_phase
 from .manager_paths import children_json_path, projects_json_path, snapshots_json_path, task_manifest_path
 from .manager_store import _now_iso, _read_json, _read_json_default, _write_json
 
@@ -84,7 +85,9 @@ def _snapshot_child(project_root: Path, child: dict) -> dict:
         "currentPhase": str(workflow.get("currentPhase") or ""),
         "currentPhaseState": str(workflow.get("currentPhaseState") or ""),
         "lastCompletedPhase": str(workflow.get("lastCompletedPhase") or ""),
-        "nextRecommendedPhase": str(workflow.get("nextRecommendedPhase") or ""),
+        "nextRecommendedPhase": next_phase.promote(
+            workflow.get("nextRecommendedPhase")
+        ),
         "latestRunStatus": str(manifest.get("latestRunStatus") or manifest.get("currentStatus") or ""),
         "latestReportPath": str(manifest.get("latestReportPath") or ""),
         "finalVerdict": str(outcome.get("finalVerdict") or ""),

package/runtime/python/okstra_ctl/next_phase.py

@@ -0,0 +1,236 @@
+"""다음 Phase 포인터의 shape · 승격 · 투영 SSOT.
+
+포인터는 `{phase, status, rationale}` 구조체다. 저작은 리드(report-writer)가
+하고, Phase 7 검증기가 리포트의 Phase 라우팅과 대조해 어긋나면 정정한다.
+이 모듈은 세 가지만 소유한다 — 구조체 판별, 구형 문자열 승격, 리포트 투영.
+다음 phase 를 계산하는 다른 알고리즘을 다시 만들지 않는다.
+"""
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+STATUS_READY = "ready"
+STATUS_PENDING = "pending"
+STATUS_BLOCKED = "blocked"
+STATUS_TERMINAL = "terminal"
+
+POINTER_STATUSES = frozenset(
+    {STATUS_READY, STATUS_PENDING, STATUS_BLOCKED, STATUS_TERMINAL}
+)
+
+# 구형 문자열 포인터가 쓰던 센티널 → status. 이 표는 승격에만 쓰이며
+# 새 포인터를 만드는 데는 절대 쓰지 않는다.
+_LEGACY_SENTINELS = {
+    "": STATUS_PENDING,
+    "unknown": STATUS_PENDING,
+    "pending-routing-decision": STATUS_PENDING,
+    "pending-release-handoff": STATUS_PENDING,
+    "done-or-follow-up": STATUS_TERMINAL,
+}
+
+# 라우팅 필드가 없어 항상 terminal 인 task-type.
+_TERMINAL_TASK_TYPES = frozenset({"release-handoff"})
+
+# 라우팅 필드가 없어 항상 pending 인 사이드트랙 task-type.
+_SIDETRACK_TASK_TYPES = frozenset(
+    {
+        "improvement-discovery",
+        "project-analysis",
+        "feature-analysis",
+        "change-impact-analysis",
+    }
+)
+
+# project() 가 명시 분기로 다루는 task-type 전체를 손으로 적은 선언.
+# project() 는 이 집합을 읽지 않는다 — 분기는 아래에 그대로 나열돼 있다.
+#
+# 이 집합을 대조하는 계약 테스트는 PHASE_SEQUENCE 에 있으면서 여기 없는 phase 만
+# 잡아낸다. 선언 두 개를 비교하는 것이므로, 여기에 이름을 적고 project() 에 분기를
+# 안 넣으면 그 phase 는 여전히 pending 폴백으로 조용히 흐른다. 분기의 실재는
+# tests/contract/test_next_phase_projection.py 의
+# test_project_has_a_live_branch_for_every_lifecycle_phase 가 정상 리포트를 실제로
+# 투영해 확인한다.
+HANDLED_TASK_TYPES = frozenset(
+    _TERMINAL_TASK_TYPES
+    | _SIDETRACK_TASK_TYPES
+    | {
+        "requirements-discovery",
+        "error-analysis",
+        "implementation-option-selection",
+        "implementation-planning",
+        "implementation",
+        "final-verification",
+    }
+)
+
+# implementation-option-selection 의 routing enum 중 phase 가 아닌 값.
+_OPTION_SELECTION_NON_PHASE = {
+    "pending-direction-selection": STATUS_PENDING,
+    "blocked": STATUS_BLOCKED,
+}
+
+# final-verification 의 routing enum 중 phase 이름이 아니라 phase 에 붙은 범위
+# 한정자인 값 → 실제로 실행할 phase. `release-handoff(stage-group)` 은 넘길 stage
+# 묶음을 좁힌다는 뜻이지 다른 phase 가 아니다. 범위는 위저드의 handoff_stage_pick
+# 이 따로 묻는다. 토큰을 그대로 phase 에 두면 `autofill_task_type` 이 그 문자열을
+# 셸에 TASK_TYPE 으로 건네는데, 그런 task-type 은 존재하지 않는다.
+_FINAL_VERIFICATION_PHASE_ALIASES = {
+    "release-handoff(stage-group)": "release-handoff",
+}
+
+
+def make(
+    phase: str = "", status: str = STATUS_PENDING, rationale: str = ""
+) -> dict[str, str]:
+    """포인터 구조체 하나를 만든다. status 가 허용 집합 밖이면 거부한다."""
+    if status not in POINTER_STATUSES:
+        raise ValueError(f"unknown next-phase status: {status!r}")
+    return {"phase": phase, "status": status, "rationale": rationale}
+
+
+def is_pointer(value: Any) -> bool:
+    """value 가 유효한 포인터 구조체인지."""
+    return (
+        isinstance(value, Mapping)
+        and isinstance(value.get("phase"), str)
+        and value.get("status") in POINTER_STATUSES
+        and isinstance(value.get("rationale"), str)
+    )
+
+
+def promote(value: Any) -> dict[str, str]:
+    """구형 문자열·None 을 포인터로 올린다.
+
+    이미 포인터인 입력은 같은 값을 담은 새 dict 로 돌려준다 — 입력을 그대로
+    돌려주지 않는다. 호출부가 반환값을 그 자리에서 변형해도 manifest 원본이
+    오염되지 않아야 하기 때문이다.
+
+    pre-v1 무호환 원칙의 의도적 예외다. 근거는 업그레이드를 가로지르는
+    진행 중 태스크가 영구히 막히는 기존 사례 — ADR-0004 Consequences.
+    """
+    if is_pointer(value):
+        return {
+            "phase": value["phase"],
+            "status": value["status"],
+            "rationale": value["rationale"],
+        }
+    if not isinstance(value, str):
+        return make()
+    text = value.strip()
+    if text in _LEGACY_SENTINELS:
+        return make(status=_LEGACY_SENTINELS[text])
+    return make(phase=text, status=STATUS_READY)
+
+
+def autofill_task_type(manifest: Mapping[str, Any]) -> str:
+    """매니페스트의 포인터에서 바로 실행 가능한 task-type 을 뽑는다.
+
+    `ready` 가 아니면 빈 문자열이다. 셸 진입점의 autofill 이 이 함수를 쓴다.
+    """
+    workflow = manifest.get("workflow")
+    if not isinstance(workflow, Mapping):
+        return ""
+    pointer = promote(workflow.get("nextRecommendedPhase"))
+    return pointer["phase"] if pointer["status"] == STATUS_READY else ""
+
+
+def project(report_data: Mapping[str, Any]) -> dict[str, str]:
+    """리포트 data.json 하나를 포인터로 투영한다.
+
+    라우팅 판단의 옳고 그름은 다루지 않는다. 리포트가 이미 내린 판단을
+    옮기기만 한다. 규칙표는 이 프로젝트의 구현 계획 문서에 있다.
+    """
+    header = report_data.get("header")
+    task_type = ""
+    if isinstance(header, Mapping):
+        task_type = str(header.get("taskType") or "")
+
+    if task_type in _TERMINAL_TASK_TYPES:
+        return make(status=STATUS_TERMINAL)
+    if task_type in _SIDETRACK_TASK_TYPES:
+        return make(status=STATUS_PENDING)
+
+    if task_type == "requirements-discovery":
+        return _from_nested_routing(report_data, "requirementsDiscovery")
+    if task_type == "error-analysis":
+        return _from_nested_routing(report_data, "errorAnalysis")
+    if task_type == "implementation-option-selection":
+        return _from_option_selection(report_data)
+    if task_type == "implementation-planning":
+        return _from_planning(report_data)
+    if task_type == "implementation":
+        return _from_target(report_data, "implementation")
+    if task_type == "final-verification":
+        return _from_final_verification(report_data)
+    return make(status=STATUS_PENDING)
+
+
+def _block(report_data: Mapping[str, Any], key: str) -> Mapping[str, Any]:
+    block = report_data.get(key)
+    return block if isinstance(block, Mapping) else {}
+
+
+def _from_nested(
+    report_data: Mapping[str, Any],
+    block_key: str,
+    routing_key: str,
+    target_key: str,
+) -> dict[str, str]:
+    """블록 → 라우팅 → 대상 phase 로 두 단 내려가 읽는 공용 판독부.
+
+    대상이 문자열이 아니면 결측과 똑같이 취급한다. 문자열이 아닌 값을 str() 로
+    강제하면 dict repr 같은 것이 phase 이름 자리에 들어앉고, status 는 ready 가
+    되어 소비자에게 "지금 시작 가능한 phase" 로 읽힌다. 결측은 pending 에서
+    무해하게 멈추지만 이쪽은 존재하지 않는 phase 로 소비자를 보낸다.
+    """
+    routing = _block(report_data, block_key).get(routing_key)
+    target = ""
+    if isinstance(routing, Mapping):
+        raw = routing.get(target_key)
+        target = raw.strip() if isinstance(raw, str) else ""
+    if not target:
+        return make(status=STATUS_PENDING)
+    return make(phase=target, status=STATUS_READY)
+
+
+def _from_nested_routing(report_data: Mapping[str, Any], key: str) -> dict[str, str]:
+    return _from_nested(report_data, key, "routing", "nextTaskType")
+
+
+def _from_option_selection(report_data: Mapping[str, Any]) -> dict[str, str]:
+    # 이 phase 의 routing 은 문자열 enum 이다. 이웃 두 phase 가 쓰는 중첩 dict 가
+    # 잘못 들어오면 결측과 똑같이 취급한다 — str() 로 강제하면 dict repr 이 phase
+    # 이름이 되어 ready 로 나간다.
+    raw = _block(report_data, "implementationOptionSelection").get("routing")
+    routing = raw.strip() if isinstance(raw, str) else ""
+    if routing in _OPTION_SELECTION_NON_PHASE:
+        return make(status=_OPTION_SELECTION_NON_PHASE[routing])
+    if not routing:
+        return make(status=STATUS_PENDING)
+    return make(phase=routing, status=STATUS_READY)
+
+
+def _from_planning(report_data: Mapping[str, Any]) -> dict[str, str]:
+    outcome = str(_block(report_data, "implementationPlanning").get("outcome") or "")
+    if outcome == "plan-ready":
+        return make(phase="implementation", status=STATUS_READY)
+    if outcome == "direction-invalidated":
+        return make(phase="implementation-option-selection", status=STATUS_READY)
+    return make(status=STATUS_PENDING)
+
+
+def _from_target(report_data: Mapping[str, Any], key: str) -> dict[str, str]:
+    return _from_nested(report_data, key, "routingRecommendation", "target")
+
+
+def _from_final_verification(report_data: Mapping[str, Any]) -> dict[str, str]:
+    pointer = _from_target(report_data, "finalVerification")
+    if pointer["phase"] == "done":
+        return make(status=STATUS_TERMINAL)
+    if pointer["phase"] in _FINAL_VERIFICATION_PHASE_ALIASES:
+        return make(
+            phase=_FINAL_VERIFICATION_PHASE_ALIASES[pointer["phase"]],
+            status=pointer["status"],
+            rationale=pointer["rationale"],
+        )
+    return pointer

package/runtime/python/okstra_ctl/ports/worker_runtime.py

@@ -0,0 +1,26 @@
+"""Port for opening, closing, and signalling a worker execution surface."""
+from __future__ import annotations
+
+from typing import Protocol
+
+from ..domain.worker_runtime import (
+    ProgressEvent,
+    RuntimeHandle,
+    WorkerSpawnRequest,
+)
+
+
+class WorkerRuntimePort(Protocol):
+    surface: str
+
+    def spawn(self, request: WorkerSpawnRequest) -> RuntimeHandle: ...
+
+    def close(self, handle: RuntimeHandle) -> None: ...
+
+    def wait(self, handle: RuntimeHandle) -> int: ...
+
+    def terminate(self, handle: RuntimeHandle) -> None: ...
+
+    def notify(self, event: ProgressEvent) -> None: ...
+
+    def restore_lead(self) -> None: ...

package/runtime/python/okstra_ctl/recap.py

@@ -11,6 +11,7 @@ import json
 import sys
 from pathlib import Path
 
+from okstra_ctl import next_phase
 from okstra_ctl.clarification_items import sidecar_answers, user_response_sidecars
 from okstra_ctl.ids import slugify_task_segment
 from okstra_ctl.incremental_scope import preview_link_availability_for_report
@@ -108,7 +109,9 @@ def assemble_recap(task_root: Path, project_root: Path) -> dict:
             "fromPhase": prev_phase,
             "toPhase": cur,
             "lastCompletedPhase": snap.get("lastCompletedPhase", ""),
-            "nextRecommendedPhase": snap.get("nextRecommendedPhase", ""),
+            "nextRecommendedPhase": next_phase.promote(
+                snap.get("nextRecommendedPhase")
+            ),
             "reportPath": run.get("reportPath", ""),
         })
         prev_phase = cur