okstra 0.186.7 → 0.187.0

package/runtime/python/okstra_ctl/render.py

@@ -48,8 +48,14 @@ from .path_hints import compact_active_run_context, hydrate_run_context
 from .paths import task_timeline_file
 from .json_boundary import JsonBoundaryError, load_owned_object, write_owned_object_atomic
 from .report_contract import CURRENT_REPORT_SCHEMA_VERSION
-from .worker_artifacts import artifacts_from_context
-from .workflow import PHASE_SEQUENCE
+from .report_language import resolve_report_language
+from .validation_contract import CURRENT_VALIDATION_CONTRACT_VERSION
+from .worker_artifacts import (
+    artifacts_from_context,
+    worker_provider_id,
+    worker_role_suffix,
+)
+from .workflow import PHASE_SEQUENCE, phase_position
 
 
 class TokenRenderError(Exception):
@@ -152,7 +158,7 @@ def _runtime_resolution(ctx: dict) -> dict:
     raw = ctx.get("RUNTIME_RESOLUTION_JSON", "") or "{}"
     try:
         payload = json.loads(raw)
-    except Exception:
+    except (ValueError, TypeError):
         return {}
     return payload if isinstance(payload, dict) else {}
 
@@ -350,8 +356,11 @@ def _lead_assignment(ctx: dict) -> dict:
             candidate = json.loads(raw)
             if isinstance(candidate, dict):
                 parsed = candidate
-        except json.JSONDecodeError:
-            pass
+        except json.JSONDecodeError as exc:
+            # 조용히 넘기면 ctx 폴백으로 만든 *다른* lead assignment 가 매니페스트에
+            # 실린다. 호출자는 그 둘을 구별할 수 없으므로 여기서 한 줄 남긴다.
+            print(f"render: LEAD_ASSIGNMENT_JSON is not valid JSON, "
+                  f"falling back to ctx fields ({exc})", file=sys.stderr)
     source = parsed or {}
     provider, runner = _resolved_lead_assignment(
         ctx,
@@ -433,8 +442,11 @@ def _worker_assignments(ctx: dict) -> list[dict]:
             parsed = json.loads(raw)
             if isinstance(parsed, list) and all(isinstance(row, dict) for row in parsed):
                 return [_resolved_worker_assignment(ctx, row) for row in parsed]
-        except json.JSONDecodeError:
-            pass
+        except json.JSONDecodeError as exc:
+            # lead assignment 와 같은 이유 — 폴백으로 만든 로스터는 요청된 것과
+            # 다른데 반환값만 봐서는 구별되지 않는다.
+            print(f"render: WORKER_ASSIGNMENTS_JSON is not valid JSON, "
+                  f"falling back to the worker catalog ({exc})", file=sys.stderr)
     catalog = _worker_catalog(ctx, include_assignments=False)
     return [
         {
@@ -491,7 +503,7 @@ def _worker_catalog(ctx: dict, *, include_assignments: bool = True) -> dict:
             "workerId": worker_id,
             "role": (
                 "Report writer worker" if worker_id == "report-writer"
-                else f"{provider_spec(worker_id).display_label} worker"
+                else _roster_role_label(provider_info.display_label, worker_id)
             ),
             "agent": provider,
             "agentLabel": provider_info.display_label,
@@ -510,15 +522,30 @@ def _worker_catalog(ctx: dict, *, include_assignments: bool = True) -> dict:
     return catalog
 
 
+def _roster_role_label(display_label: str, worker_id: str) -> str:
+    """team-state 로스터 행의 역할 라벨.
+
+    한 provider 가 슬롯 하나만 채우면 종전 그대로 `<Provider> worker` 다.
+    두 슬롯 이상이면 worker_id 에 붙은 역할이 라벨에도 그대로 온다
+    (`Claude implementer`, `Claude verifier`, `Claude verifier 2`) —
+    라벨이 겹치면 validate-run 이 `duplicate worker role detected` 로 런을
+    실패시키므로, id 를 가르는 그 접미사가 라벨도 가른다.
+    """
+    suffix = worker_role_suffix(worker_id)
+    if not suffix:
+        return f"{display_label} worker"
+    return f"{display_label} {suffix.replace('-', ' ')}"
+
+
 def _fallback_worker_provider(ctx: dict, worker_id: str) -> str:
     if worker_id == "report-writer":
         return ctx.get("REPORT_WRITER_PROVIDER", "") or "claude"
-    return worker_id
+    return worker_provider_id(worker_id)
 
 
 def _legacy_worker_model(ctx: dict, worker_id: str) -> tuple[str, str]:
     token = "REPORT_WRITER" if worker_id == "report-writer" else (
-        worker_id.upper().replace("-", "_")
+        worker_provider_id(worker_id).upper().replace("-", "_")
     )
     return (
         ctx.get(f"{token}_WORKER_MODEL", ctx.get(f"{token}_MODEL", "")),
@@ -878,7 +905,7 @@ def render_task_catalog_discovery(output_path: str, ctx: dict) -> None:
     for manifest_path in sorted(tasks_root.rglob(TASK_MANIFEST_FILENAME)):
         try:
             manifest = load_owned_object(manifest_path, artifact="task manifest")
-        except Exception:
+        except JsonBoundaryError:
             continue
         if not isinstance(manifest, dict):
             continue
@@ -896,7 +923,7 @@ def render_task_catalog_discovery(output_path: str, ctx: dict) -> None:
         if timeline_file.is_file():
             try:
                 payload = load_owned_object(timeline_file, artifact="task timeline")
-            except Exception:
+            except JsonBoundaryError:
                 payload = {}
             runs = payload.get("runs", []) if isinstance(payload, dict) else []
             if isinstance(runs, list):
@@ -988,7 +1015,7 @@ def render_latest_task_discovery(output_path: str, ctx: dict) -> None:
             task_manifest = load_owned_object(
                 task_manifest_path, artifact="task manifest"
             )
-        except Exception:
+        except JsonBoundaryError:
             task_manifest = {}
     workflow = (
         task_manifest.get("workflow")
@@ -1103,8 +1130,12 @@ def migrate_legacy_run_artifacts(ctx: dict) -> None:
                     if entry.read_bytes() == destination.read_bytes():
                         entry.unlink()
                         path_rewrites[old_relative] = new_relative
-                except Exception:
-                    pass
+                except OSError as exc:
+                    # 읽지 못하면 두 파일이 같은지 알 수 없어 옛 경로를 남긴다.
+                    # 조용히 두면 이관이 끝난 것처럼 보이므로 이유를 남긴다.
+                    print(f"render: cannot compare legacy artifact {entry} with "
+                          f"{destination}, leaving it in place ({exc})",
+                          file=sys.stderr)
                 break
             shutil.move(str(entry), str(destination))
             path_rewrites[old_relative] = new_relative
@@ -1117,7 +1148,7 @@ def migrate_legacy_run_artifacts(ctx: dict) -> None:
             continue
         try:
             original = path.read_text(encoding="utf-8")
-        except Exception:
+        except OSError:
             continue
         updated = _rewrite_path_refs(original, path_rewrites)
         if updated != original:
@@ -1310,17 +1341,30 @@ def _derive_latest_pointers(existing: dict, ctx: dict, current_report_relative:
                     "latestResumeCommandPath", existing.get("latestResumeCommandPath", "")
                 ),
             },
-            "latestRunPath": existing.get("latestRunPath", "")
-            or ctx.get("LATEST_RUN_RELATIVE_PATH", ""),
-            "latestRunStatus": existing.get("latestRunStatus", "")
-            or ctx.get("CURRENT_RUN_STATUS", ""),
-            "latestRunPromptsPath": existing.get("latestRunPromptsPath", "")
-            or ctx.get("RUN_PROMPTS_RELATIVE_PATH", ""),
+            # `--render-only` 은 옛 run 을 다시 그리는 것이 아니라 **새 run 을
+            # 준비**한다(새 run-manifest 기록, 타임라인 갱신). 그래서 run 디렉터리
+            # ·프롬프트·team-state·상태는 이번에 만들어진 것이 최신이다. 기존값을
+            # 우선하면 `latest` 라는 이름의 필드가 최초로 들어온 값에 영구히 묶인다
+            # — 실측(`fontsninja-nlpvibe`): implementation 의 stage run 이 전부
+            # `renderOnly: true` 라 stage 10 까지 돌고도 `latestRunPath` 가
+            # `stage-1`, `latestRunStatus` 가 그때의 `contract-violated` 로 남았다.
+            "latestRunPath": ctx.get("LATEST_RUN_RELATIVE_PATH", "")
+            or existing.get("latestRunPath", ""),
+            "latestRunStatus": ctx.get("CURRENT_RUN_STATUS", "")
+            or existing.get("latestRunStatus", ""),
+            "latestRunPromptsPath": ctx.get("RUN_PROMPTS_RELATIVE_PATH", "")
+            or existing.get("latestRunPromptsPath", ""),
+            # 리포트만 반대다. render-only 는 최종 리포트를 만들지 않으므로
+            # `current_report_relative` 는 아직 없는 파일을 가리킬 수 있다.
+            # 마지막으로 실재했던 리포트를 지키는 쪽이 옳다.
             "latestReportRecordPath": existing.get("latestReportRecordPath", "")
             or current_report_relative,
-            "latestTeamStatePath": existing.get("teamStatePath", "")
-            or ctx.get("TEAM_STATE_RELATIVE_PATH", ""),
-            "latestResumeCommandPath": existing.get("latestResumeCommandPath", ""),
+            "latestTeamStatePath": ctx.get("TEAM_STATE_RELATIVE_PATH", "")
+            or existing.get("teamStatePath", ""),
+            "latestResumeCommandPath": ctx.get(
+                "CLAUDE_RESUME_COMMAND_RELATIVE_PATH", ""
+            )
+            or existing.get("latestResumeCommandPath", ""),
         }
     return {
         "lastSafeCheckpoint": {
@@ -1350,7 +1394,7 @@ def render_task_manifest(manifest_path: str, ctx: dict) -> None:
     if path.exists():
         try:
             existing = load_owned_object(path, artifact="task manifest")
-        except Exception:
+        except JsonBoundaryError:
             existing = {}
     reviewers = _resolve_workers(ctx)
     worker_dispatch_plan = _worker_dispatch_plan(ctx)
@@ -1672,7 +1716,7 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
             task_manifest = load_owned_object(
                 task_manifest_path, artifact="task manifest"
             )
-        except Exception:
+        except JsonBoundaryError:
             task_manifest = {}
     reviewers = _resolve_workers(ctx)
     worker_dispatch_plan = _worker_dispatch_plan(ctx)
@@ -1706,7 +1750,14 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
         "taskKey": ctx.get("TASK_KEY", ""),
         "taskType": ctx.get("TASK_TYPE", ""),
         "runTimestamp": ctx.get("RUN_TIMESTAMP_ISO", ""),
-        "reportLanguage": ctx.get("REPORT_LANGUAGE", "en") or "en",
+        # 리포트 언어의 유일한 해석기. 예전에는 아무도 채우지 않는
+        # `REPORT_LANGUAGE` 를 읽어 항상 "en" 이 나왔고, report-writer 프롬프트만
+        # `resolve_report_language()` 를 써서 프롬프트는 ko, 매니페스트는 en 으로
+        # 갈렸다. 리포트 조립은 이 매니페스트 값을 `meta.reportLanguage` 로
+        # 그대로 옮기므로, 갈라진 쪽이 사람이 읽는 언어를 결정했다.
+        "reportLanguage": resolve_report_language(
+            Path(ctx.get("PROJECT_ROOT", "")), task_manifest, {}
+        ),
         "leadModel": ctx.get("LEAD_MODEL", ""),
         # Every other path in this manifest is project-relative; this is the
         # anchor they resolve against. Convergence reads it to place run
@@ -1783,6 +1834,7 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
         "approvalDecisionsPath": ctx.get("APPROVAL_DECISIONS_RELATIVE_PATH", ""),
         "designPreparationPath": ctx.get("DESIGN_PREPARATION_RELATIVE_PATH", ""),
         "planBodyVerificationPath": ctx.get("PLAN_BODY_VERIFICATION_STATE_RELATIVE_PATH", ""),
+        "incrementalDecisionPath": ctx.get("INCREMENTAL_DECISION_STATE_RELATIVE_PATH", ""),
         "expectedStatusPath": ctx.get("FINAL_STATUS_RELATIVE_PATH", ""),
         "teamStatePath": ctx.get("TEAM_STATE_RELATIVE_PATH", ""),
         "activeRunContextPath": ctx.get("ACTIVE_RUN_CONTEXT_RELATIVE_PATH", ""),
@@ -1877,6 +1929,12 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
             payload["activityContractVersion"] = existing_run_manifest[
                 "activityContractVersion"
             ]
+    if not run_manifest_exists:
+        payload["validationContractVersion"] = CURRENT_VALIDATION_CONTRACT_VERSION
+    elif "validationContractVersion" in existing_run_manifest:
+        payload["validationContractVersion"] = existing_run_manifest[
+            "validationContractVersion"
+        ]
     payload["reportContracts"] = (
         ["implementation-design-prep-v1"]
         if ctx.get("TASK_TYPE") == "implementation-planning"
@@ -2100,7 +2158,7 @@ def render_timeline(timeline_path: str, ctx: dict) -> None:
             task_manifest = load_owned_object(
                 task_manifest_path, artifact="task manifest"
             )
-        except Exception:
+        except JsonBoundaryError:
             task_manifest = {}
     reviewers = _resolve_workers(ctx)
     catalog = _worker_catalog(ctx)
@@ -2109,7 +2167,7 @@ def render_timeline(timeline_path: str, ctx: dict) -> None:
     if path.exists():
         try:
             existing = load_owned_object(path, artifact="task timeline")
-        except Exception:
+        except JsonBoundaryError:
             existing = {}
     runs = existing.get("runs", [])
     current_run_manifest_path = ctx.get("RUN_MANIFEST_PATH", "")
@@ -2206,7 +2264,7 @@ def render_task_index(template_path: str, output_path: str, ctx: dict) -> None:
             task_manifest = load_owned_object(
                 task_manifest_path, artifact="task manifest"
             )
-        except Exception:
+        except JsonBoundaryError:
             task_manifest = {}
     workflow = (
         task_manifest.get("workflow", {})
@@ -2349,6 +2407,12 @@ def render_task_index(template_path: str, output_path: str, ctx: dict) -> None:
         "{{WORKFLOW_CURRENT_PHASE_STATE}}": workflow.get(
             "currentPhaseState", ctx.get("WORKFLOW_CURRENT_PHASE_STATE", "")
         ),
+        # 매니페스트가 아니라 phase 이름에서 파생한다 — 자리표시자가 아니라
+        # 결정론적 값이라 물려받을 이유가 없다.
+        "{{WORKFLOW_PHASE_POSITION}}": phase_position(
+            str(workflow.get("currentPhase", ctx.get("WORKFLOW_CURRENT_PHASE", "")))
+        )
+        or "--",
         "{{WORKFLOW_LAST_COMPLETED_PHASE}}": workflow.get(
             "lastCompletedPhase", ctx.get("WORKFLOW_LAST_COMPLETED_PHASE", "")
         )
@@ -2661,7 +2725,9 @@ def inject_lead_prompt_computed_tokens(ctx: dict) -> None:
         "- For native in-process dispatch, use the same canonical initial-prompt headers, "
         "persist the assigned prompt history through `write_artifact`, and apply "
         "the adapter-declared `lazy-path-reference` delivery mode before starting the "
-        "worker. This native path does not apply to reverify or critic dispatches.\n"
+        "worker. The dispatch payload is a summon message carrying the persisted "
+        "prompt path and the instruction to read that document in full — never the "
+        "prompt body. This native path does not apply to reverify or critic dispatches.\n"
         "- Use `await_workers` through the selected adapter and confirm terminal state "
         "plus every required Result Path. File presence alone is never a signal to "
         "skip; worker selection and skipped status come from `team-state`.\n"

package/runtime/python/okstra_ctl/render_final_report.py

@@ -482,15 +482,15 @@ def _enforce_schema(data: dict) -> dict | None:
 _DISPLAY_CONCRETE_CLAUDE = {
     "fable": "claude-fable-5",
     "opus": "claude-opus-5",
-    "sonnet": "claude-sonnet-4-6",
+    "sonnet": "claude-sonnet-5",
     "haiku": "claude-haiku-4-5",
 }
 
 
 def _model_detail(display: Any) -> str:
-    """모델 display alias(예: 'opus')를 'opus (claude-opus-4-7)' 형태로 상세화한다.
+    """모델 display alias(예: 'opus')를 'opus (claude-opus-5)' 형태로 상세화한다.
 
-    lead·report-writer 헤더 모델은 항상 claude provider 다. 구체 alias('opus-4-7'
+    lead·report-writer 헤더 모델은 항상 claude provider 다. 구체 alias('opus-5'
     등)는 claude 매핑의 실행 ID 를, 일반 alias('opus' 등)는 표시 전용
     `_DISPLAY_CONCRETE_CLAUDE` 의 권장 구체버전을 병기한다. 어느 쪽에도 없는 값
     (이미 실행 ID 이거나 'default' 등)은 원본을 그대로 돌려준다. 바깥 백틱은
@@ -638,10 +638,6 @@ def render_execution_roles_markdown(data: dict) -> str:
     return "\n".join(lines)
 
 
-def render_execution_roles_html(data: dict) -> str:
-    return render_execution_roles_markdown(data)
-
-
 def _with_optional_defaults(data: dict) -> dict:
     """Render context with schema-optional fields filled in.