okstra 0.175.1 → 0.176.0

package/runtime/python/okstra_ctl/render.py

@@ -30,6 +30,7 @@ from okstra_project.dirs import TASK_MANIFEST_FILENAME, OKSTRA_DIR_NAME, project
 # render_task_manifest 가 동일한 리스트/딕셔너리를 로컬에 중복 정의했는데,
 # 이는 silent drift 위험이 있어 SSOT import 로 통합한다.
 from . import fix_cycles
+from . import next_phase
 from .analysis_inputs import ANALYSIS_TASK_TYPES
 from .application.resolve_assignment import (
     resolve_assignment_runner,
@@ -46,7 +47,7 @@ from .registry.provider_registry import default_provider_registry
 from .path_hints import compact_active_run_context, hydrate_run_context
 from .paths import task_timeline_file
 from .worker_artifacts import artifacts_from_context
-from .workflow import DEFAULT_NEXT_PHASE, PHASE_SEQUENCE
+from .workflow import PHASE_SEQUENCE
 
 
 class TokenRenderError(Exception):
@@ -563,9 +564,10 @@ def _active_workflow(ctx: dict) -> dict:
         "currentPhase": ctx.get("WORKFLOW_CURRENT_PHASE", ""),
         "currentPhaseState": ctx.get("WORKFLOW_CURRENT_PHASE_STATE", ""),
         "lastCompletedPhase": ctx.get("WORKFLOW_LAST_COMPLETED_PHASE", ""),
-        "nextRecommendedPhase": ctx.get("WORKFLOW_NEXT_RECOMMENDED_PHASE", ""),
+        "nextRecommendedPhase": next_phase.promote(
+            ctx.get("WORKFLOW_NEXT_RECOMMENDED_PHASE")
+        ),
         "awaitingApproval": ctx.get("WORKFLOW_AWAITING_APPROVAL", "false") == "true",
-        "routingStatus": ctx.get("WORKFLOW_ROUTING_STATUS", ""),
         "allowedOutputs": ctx.get("PHASE_ALLOWED_OUTPUTS", ""),
         "forbiddenActions": ctx.get("PHASE_FORBIDDEN_ACTIONS", ""),
     }
@@ -917,15 +919,14 @@ def render_task_catalog_discovery(output_path: str, ctx: dict) -> None:
                 "lastCompletedPhase": (workflow or {}).get("lastCompletedPhase", "")
                 if isinstance(workflow, dict)
                 else "",
-                "nextRecommendedPhase": (workflow or {}).get("nextRecommendedPhase", "")
-                if isinstance(workflow, dict)
-                else "",
+                "nextRecommendedPhase": next_phase.promote(
+                    (workflow or {}).get("nextRecommendedPhase")
+                    if isinstance(workflow, dict)
+                    else None
+                ),
                 "awaitingApproval": (workflow or {}).get("awaitingApproval", False)
                 if isinstance(workflow, dict)
                 else False,
-                "routingStatus": (workflow or {}).get("routingStatus", "")
-                if isinstance(workflow, dict)
-                else "",
                 "taskRootPath": s(manifest, "taskRootPath") or rel(task_root),
                 "taskManifestPath": s(manifest, "taskManifestPath")
                 or rel(manifest_path),
@@ -1191,27 +1192,31 @@ def _derive_phase_states(existing_workflow: dict, ctx: dict) -> tuple[dict, str,
 
 
 def _derive_next_recommended_phase(
-    current_phase: str, current_phase_state: str, existing_workflow: dict, ctx: dict
-) -> str:
-    """canonical next phase 를 deterministic 하게 결정한다.
-
-    `current_phase` 가 terminal-success(`completed`) 가 아니면 그 자리에 머무르도록
-    recommend 한다. `prepared` / `in-progress` / `blocked` / `error` /
-    `contract-violated` 상태에서 다음 phase 로 미리 advance 하면 wizard(와 사람)
-    가 현재 phase 를 끝난 것으로 오인한다. (Historical bug: implementation 이
-    `prepared` 상태로 provision 됐을 때 wizard 가 `final-verification` 을 기본
-    task_type 으로 추천했다.)"""
-    canonical_next = DEFAULT_NEXT_PHASE.get(current_phase) or ctx.get(
-        "WORKFLOW_NEXT_RECOMMENDED_PHASE", "unknown"
+    existing_workflow: dict, current_phase_state: str
+) -> dict:
+    """prepare 시점의 포인터를 만든다.
+
+    대상 phase 는 리드가 정한다. prepare 는 그 값을 보존하고 진행 가능 여부만
+    내린다 — 실행이 아직 안 끝났는데 다음을 제안하면 위저드가 현재 phase 를
+    끝난 것으로 오인한다. (기록된 사례: implementation 이 `prepared` 로
+    준비됐을 때 위저드가 `final-verification` 을 기본 task_type 으로 추천했다.)
+
+    현재 phase 가 `completed` 면 그 오인이 성립하지 않으므로 포인터를 승격만 해서
+    그대로 돌려준다. 내리는 대상도 `ready` 하나뿐이다 — `pending` · `blocked` ·
+    `terminal` 은 애초에 착수를 부르지 않는 상태라 내려봐야 얻는 것이 없고,
+    리드가 판단해 적은 `blocked`(사람이 봐야 하는 상태)와 `terminal`(생애주기
+    종료)을 `pending`("아직 아무도 정하지 않음")으로 지워버린다.
+    """
+    pointer = next_phase.promote(existing_workflow.get("nextRecommendedPhase"))
+    if current_phase_state == "completed":
+        return pointer
+    if pointer["status"] != next_phase.STATUS_READY:
+        return pointer
+    return next_phase.make(
+        phase=pointer["phase"],
+        status=next_phase.STATUS_PENDING,
+        rationale=pointer["rationale"],
     )
-    existing_next = existing_workflow.get("nextRecommendedPhase") or ""
-    if current_phase_state not in {"completed"}:
-        # 아직 끝나지 않음 — 같은 phase 를 추천한다. sequence 상 더 앞을 가리키는
-        # stale existing_next 는 무시하고, 같은 current_phase 를 가리키는 값만 존중.
-        return current_phase
-    if existing_next and existing_next != current_phase:
-        return existing_next
-    return canonical_next
 
 
 def _derive_latest_pointers(existing: dict, ctx: dict, current_report_relative: str) -> dict:
@@ -1320,14 +1325,11 @@ def render_task_manifest(manifest_path: str, ctx: dict) -> None:
         "WORKFLOW_WORK_CATEGORY", "unknown"
     )
     next_recommended_phase = _derive_next_recommended_phase(
-        current_phase, current_phase_state, existing_workflow, ctx
+        existing_workflow, current_phase_state
     )
     last_completed_phase = existing_workflow.get("lastCompletedPhase") or ctx.get(
         "WORKFLOW_LAST_COMPLETED_PHASE", ""
     )
-    routing_status = existing_workflow.get("routingStatus") or ctx.get(
-        "WORKFLOW_ROUTING_STATUS", "not-applicable"
-    )
     awaiting_approval = existing_workflow.get("awaitingApproval")
     if not isinstance(awaiting_approval, bool):
         awaiting_approval = ctx.get("WORKFLOW_AWAITING_APPROVAL", "false") == "true"
@@ -1399,7 +1401,6 @@ def render_task_manifest(manifest_path: str, ctx: dict) -> None:
             "lastCompletedPhase": last_completed_phase,
             "nextRecommendedPhase": next_recommended_phase,
             "awaitingApproval": awaiting_approval,
-            "routingStatus": routing_status,
             "lastSafeCheckpoint": last_safe_checkpoint,
         },
         "artifacts": {
@@ -1746,16 +1747,13 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
             "lastCompletedPhase": workflow.get(
                 "lastCompletedPhase", ctx.get("WORKFLOW_LAST_COMPLETED_PHASE", "")
             ),
-            "nextRecommendedPhase": workflow.get(
-                "nextRecommendedPhase", ctx.get("WORKFLOW_NEXT_RECOMMENDED_PHASE", "")
+            "nextRecommendedPhase": next_phase.promote(
+                workflow.get("nextRecommendedPhase")
             ),
             "awaitingApproval": workflow.get(
                 "awaitingApproval",
                 ctx.get("WORKFLOW_AWAITING_APPROVAL", "false") == "true",
             ),
-            "routingStatus": workflow.get(
-                "routingStatus", ctx.get("WORKFLOW_ROUTING_STATUS", "")
-            ),
             "lastSafeCheckpoint": workflow.get("lastSafeCheckpoint", {}),
         },
         "teamContract": {
@@ -2051,9 +2049,10 @@ def render_timeline(timeline_path: str, ctx: dict) -> None:
                 "currentPhaseState": workflow.get("currentPhaseState", ""),
                 "phaseStates": workflow.get("phaseStates", {}),
                 "lastCompletedPhase": workflow.get("lastCompletedPhase", ""),
-                "nextRecommendedPhase": workflow.get("nextRecommendedPhase", ""),
+                "nextRecommendedPhase": next_phase.promote(
+                    workflow.get("nextRecommendedPhase")
+                ),
                 "awaitingApproval": workflow.get("awaitingApproval", False),
-                "routingStatus": workflow.get("routingStatus", ""),
                 "lastSafeCheckpoint": workflow.get("lastSafeCheckpoint", {}),
             },
     }
@@ -2239,15 +2238,15 @@ def render_task_index(template_path: str, output_path: str, ctx: dict) -> None:
             "lastCompletedPhase", ctx.get("WORKFLOW_LAST_COMPLETED_PHASE", "")
         )
         or "--",
-        "{{WORKFLOW_NEXT_RECOMMENDED_PHASE}}": workflow.get(
-            "nextRecommendedPhase", ctx.get("WORKFLOW_NEXT_RECOMMENDED_PHASE", "")
-        ),
+        # 토큰은 사람이 읽는 한 줄이라 문자열이어야 한다. 포인터의 `status` 는
+        # 같은 페이지의 다른 줄이 아니라 소비자 로직이 읽는다.
+        "{{WORKFLOW_NEXT_RECOMMENDED_PHASE}}": next_phase.promote(
+            workflow.get("nextRecommendedPhase")
+        )["phase"]
+        or "--",
         "{{WORKFLOW_AWAITING_APPROVAL}}": "yes"
         if workflow.get("awaitingApproval", False)
         else "no",
-        "{{WORKFLOW_ROUTING_STATUS}}": workflow.get(
-            "routingStatus", ctx.get("WORKFLOW_ROUTING_STATUS", "")
-        ),
         "{{WORKFLOW_PHASE_STATE_LINES}}": "\n".join(phase_state_lines),
         "{{WORKFLOW_LAST_SAFE_CHECKPOINT_LINES}}": "\n".join(checkpoint_lines),
         "{{FIX_CYCLES_SUMMARY}}": _fix_cycles_index_line(task_manifest),

package/runtime/python/okstra_ctl/role_requirements.py

@@ -14,19 +14,19 @@ class RoleProfileError(ValueError):
 @dataclass(frozen=True)
 class RoleRequirement:
     role: str
-    count: int
+    min_count: int
+    recommended_count: int
+    max_count: int
     duty: str
-    optional_count: int = 0
-    min_distinct_providers: int | None = None
     dynamic: bool = False
 
-    def signature(self) -> tuple[str, int, int, str, int | None, bool]:
+    def signature(self) -> tuple[str, int, int, int, str, bool]:
         return (
             self.role,
-            self.count,
-            self.optional_count,
+            self.min_count,
+            self.recommended_count,
+            self.max_count,
             self.duty,
-            self.min_distinct_providers,
             self.dynamic,
         )
 
@@ -35,16 +35,12 @@ class RoleRequirement:
 class RoleProfile:
     roles: tuple[RoleRequirement, ...]
 
-    def role_signature(self) -> tuple[tuple[str, int, int, str, int | None, bool], ...]:
+    def role_signature(self) -> tuple[tuple[str, int, int, int, str, bool], ...]:
         return tuple(requirement.signature() for requirement in self.roles)
 
 
-_REQUIRED_FIELDS = frozenset({"role", "count", "duty"})
-_ALLOWED_FIELDS = _REQUIRED_FIELDS | {
-    "optionalCount",
-    "minDistinctProviders",
-    "dynamic",
-}
+_REQUIRED_FIELDS = frozenset({"role", "min", "recommended", "max", "duty"})
+_ALLOWED_FIELDS = _REQUIRED_FIELDS | {"dynamic"}
 
 
 def load_role_profile(path: Path) -> RoleProfile:
@@ -140,20 +136,26 @@ def _validate_requirement(
         errors.append(f"{prefix} has unknown field {field}")
 
     role = _validate_role(raw.get("role", ""), prefix, errors)
-    count = _validate_non_negative_integer(raw.get("count", ""), "count", prefix, errors)
-    duty = _validate_duty(raw.get("duty", ""), role, prefix, errors)
-    optional_count = _validate_non_negative_integer(
-        raw.get("optionalCount", "0"), "optionalCount", prefix, errors,
+    min_count = _validate_non_negative_integer(
+        raw.get("min", ""), "min", prefix, errors,
+    )
+    recommended_count = _validate_non_negative_integer(
+        raw.get("recommended", ""), "recommended", prefix, errors,
+    )
+    max_count = _validate_non_negative_integer(
+        raw.get("max", ""), "max", prefix, errors,
     )
-    diversity = _validate_diversity(raw.get("minDistinctProviders"), prefix, errors)
+    duty = _validate_duty(raw.get("duty", ""), role, prefix, errors)
     dynamic = _validate_dynamic(raw.get("dynamic", "false"), prefix, errors)
-    if diversity is not None and diversity > count + optional_count:
-        errors.append(f"{prefix} minDistinctProviders must not exceed count + optionalCount")
-    if dynamic and (count != 0 or optional_count != 0):
-        errors.append(f"{prefix} dynamic roles must have count and optionalCount of zero")
-    if dynamic and diversity is not None:
-        errors.append(f"{prefix} dynamic roles must not declare minDistinctProviders")
-    return RoleRequirement(role, count, duty, optional_count, diversity, dynamic)
+    if not (min_count <= recommended_count <= max_count):
+        errors.append(f"{prefix} min must be <= recommended <= max")
+    if dynamic and (min_count != 0 or recommended_count != 0 or max_count != 0):
+        errors.append(
+            f"{prefix} dynamic roles must have min, recommended, and max of zero"
+        )
+    return RoleRequirement(
+        role, min_count, recommended_count, max_count, duty, dynamic,
+    )
 
 
 def _validate_role(raw: str, prefix: str, errors: list[str]) -> str:
@@ -187,15 +189,6 @@ def _validate_non_negative_integer(raw: str, field: str, prefix: str, errors: li
     return value
 
 
-def _validate_diversity(raw: str | None, prefix: str, errors: list[str]) -> int | None:
-    if raw is None:
-        return None
-    value = _validate_non_negative_integer(raw, "minDistinctProviders", prefix, errors)
-    if value == 0:
-        errors.append(f"{prefix} minDistinctProviders must be at least one")
-    return value
-
-
 def _validate_dynamic(raw: str, prefix: str, errors: list[str]) -> bool:
     if raw == "true":
         return True

package/runtime/python/okstra_ctl/rollup.py

@@ -14,6 +14,7 @@ import json
 import sys
 from pathlib import Path
 
+from okstra_ctl import next_phase
 from okstra_ctl.error_log_core import glob_error_logs, parse_records
 from okstra_ctl.time_report import aggregate_time, load_runs
 from okstra_project import (
@@ -80,7 +81,9 @@ def _collect_task(entry: dict, project_root: Path) -> dict:
         "workStatus": entry.get("workStatus", "") or "unknown",
         "currentPhase": entry.get("currentPhase", ""),
         "currentPhaseState": entry.get("currentPhaseState", ""),
-        "nextRecommendedPhase": entry.get("nextRecommendedPhase", ""),
+        "nextRecommendedPhase": next_phase.promote(
+            entry.get("nextRecommendedPhase")
+        ),
         "latestRunStatus": entry.get("latestRunStatus", ""),
         "updatedAt": entry.get("updatedAt", ""),
         "reportPath": entry.get("latestReportPath", ""),

package/runtime/python/okstra_ctl/run.py

@@ -1782,7 +1782,7 @@ def _resolve_roster(inp: PrepareInputs, profile_file: Path) -> tuple[list[str],
     except RoleProfileError as exc:
         raise PrepareError(str(exc)) from exc
     requires_report_writer = any(
-        row.role == "report-writer" and row.count == 1
+        row.role == "report-writer" and row.min_count == 1
         for row in role_profile.roles
     )
     if requires_report_writer and "report-writer" not in workers:
@@ -1799,7 +1799,7 @@ def _profile_requires_executor(profile_file: Path) -> bool:
     except RoleProfileError as exc:
         raise PrepareError(str(exc)) from exc
     return any(
-        requirement.role == "implementer" and requirement.count > 0
+        requirement.role == "implementer" and requirement.min_count > 0
         for requirement in profile.roles
     )
 
@@ -2088,7 +2088,7 @@ def _roles_requiring_defaults(
             continue
         desired = selection.role_counts.get(
             requirement.role,
-            requirement.count,
+            requirement.recommended_count,
         )
         explicit = _explicit_selection_count(selection, requirement.role)
         if explicit < desired:
@@ -2150,7 +2150,7 @@ def _needs_profile_worker_candidates(
             continue
         desired = selection.role_counts.get(
             requirement.role,
-            requirement.count,
+            requirement.recommended_count,
         )
         explicit = _explicit_selection_count(selection, requirement.role)
         has_scoped_default = (
@@ -2219,7 +2219,10 @@ def _resolver_role_counts(
     adjustable = {
         requirement.role
         for requirement in profile.roles
-        if not requirement.dynamic and requirement.optional_count > 0
+        if (
+            not requirement.dynamic
+            and requirement.min_count < requirement.max_count
+        )
     }
     return {role: count for role, count in counts.items() if role in adjustable}
 

package/runtime/python/okstra_ctl/stage_fix_carry.py

@@ -84,10 +84,26 @@ def derive_stage_fix_carry(
             str(row.get("discrepancy") or row.get("verifier") or "")
             for row in failed
         ],
-        routing_recommendation=str(impl.get("routingRecommendation") or ""),
+        routing_recommendation=_routing_line(impl.get("routingRecommendation")),
     )
 
 
+def _routing_line(value: object) -> str:
+    """구조체 라우팅을 캐리 프롬프트에 실을 한 줄로 편다.
+
+    리포트의 `implementation.routingRecommendation` 은 `{target, rationale}`
+    구조체다. dict 를 str() 로 강제하면 executor 프롬프트에 파이썬 dict repr 이
+    그대로 실려 사람도 모델도 읽을 수 없는 줄이 된다.
+    """
+    if not isinstance(value, dict):
+        return ""
+    target = str(value.get("target") or "").strip()
+    rationale = str(value.get("rationale") or "").strip()
+    if target and rationale:
+        return f"{target} — {rationale}"
+    return target or rationale
+
+
 def _latest_report(stage_run_dir: Path) -> Path | None:
     reports_dir = stage_run_dir / "reports"
     if not reports_dir.is_dir():

package/runtime/python/okstra_ctl/team.py

@@ -163,10 +163,21 @@ def _teardown(args) -> int:
     if args.dry_run:
         _emit_teardown(args.json, panes)
         return 0
-    if _is_cmux_run(manifest):
+    from .adapters.runtime.assembly import port_for, runtime_chain
+    from .domain.worker_runtime import RuntimeHandle, SURFACE_CMUX_PANE
+
+    chain = runtime_chain(_manifest_backend(manifest))
+    # cli-wrapper chains have no cmux port; leftover paneIds must not KeyError.
+    if panes and any(port.surface == SURFACE_CMUX_PANE for port in chain):
+        closer = port_for(chain, SURFACE_CMUX_PANE)
         for pane in panes:
-            cmux.close_surface(pane["paneId"])
-        _restore_lead_width()
+            closer.close(
+                RuntimeHandle(SURFACE_CMUX_PANE, pane["paneId"], False)
+            )
+    try:
+        chain[0].restore_lead()
+    except (OSError, subprocess.SubprocessError, RuntimeError) as exc:
+        print(f"okstra team: could not restore the lead's width: {exc}", file=sys.stderr)
     _mark_teardown_errors(team_state_path)
     _emit_teardown(args.json, panes)
     return 0
@@ -280,21 +291,6 @@ def _append_pane(panes: list[dict[str, str]], seen: set[str], pane_id: str, kind
         seen.add(pane_id)
 
 
-def _restore_lead_width() -> None:
-    """Give the lead back the width the reclaimed panes left behind.
-
-    Reported rather than raised: teardown's contract is to reclaim the run's
-    panes and print what it reclaimed, and a failed resize must not cost the
-    caller that record — the panes are already closed by the time this runs.
-    Reported rather than swallowed, because a width failure nobody is told
-    about is what left the lead at 18 columns unnoticed.
-    """
-    try:
-        cmux.restore_lead_width()
-    except (OSError, subprocess.SubprocessError, RuntimeError) as exc:
-        print(f"okstra team: could not restore the lead's width: {exc}", file=sys.stderr)
-
-
 def _mark_teardown_errors(team_state_path: Path) -> None:
     def mark(payload: dict[str, Any]) -> bool:
         changed = False