okstra 0.179.2 → 0.180.0

package/runtime/python/okstra_ctl/stage_map.py

@@ -7,6 +7,7 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, Iterable
 
+from .final_report_paths import final_report_data_path, is_full_reading_copy_path
 from .md_table import is_separator_row, split_pipe_row
 from .paths import RunRef
 from .plan_run_root import list_implementation_planning_reports
@@ -364,8 +365,8 @@ def parse_stage_map_file(plan_path: Path) -> list[StageMapStage]:
     return _parse_stage_map_markdown(resolved)
 
 
-def schema_v2_report(plan_path: Path) -> dict[str, Any]:
-    """The schema-v2 report record as a whole, `{}` for a v1 markdown path.
+def structured_report(plan_path: Path) -> dict[str, Any]:
+    """계약 2.0·3.0 구조화 리포트를 반환하고 Markdown에는 빈 값을 반환한다.
 
     Public because every caller that must branch on report schema needs it —
     including `validators/validate-implementation-plan-stages.py`, which is a
@@ -381,14 +382,19 @@ def schema_v2_report(plan_path: Path) -> dict[str, Any]:
         data = json.loads(resolved.read_text(encoding="utf-8"))
     except (OSError, UnicodeError, json.JSONDecodeError) as exc:
         raise StageMapError("stage_map", str(exc), str(resolved)) from exc
-    if not isinstance(data, dict) or data.get("schemaVersion") != "2.0":
+    if not isinstance(data, dict) or data.get("schemaVersion") not in {"2.0", "3.0"}:
         return {}
     return data
 
 
+def schema_v2_report(plan_path: Path) -> dict[str, Any]:
+    """기존 호출자를 위한 구조화 리포트 판독 별칭."""
+    return structured_report(plan_path)
+
+
 def _planning_section(markdown_path: Path) -> dict[str, Any]:
     """The report's `implementationPlanning` block, `{}` for v1."""
-    planning = schema_v2_report(markdown_path).get("implementationPlanning")
+    planning = structured_report(markdown_path).get("implementationPlanning")
     return planning if isinstance(planning, dict) else {}
 
 
@@ -412,7 +418,7 @@ def _stage_narratives(value: Any) -> dict[int, dict[str, Any]]:
 
 def load_planning_detail(markdown_path: Path) -> PlanningDetail:
     """Read one report's narrative rows; empty for a schema-v1 report."""
-    report = schema_v2_report(markdown_path)
+    report = structured_report(markdown_path)
     planning = report.get("implementationPlanning")
     if not isinstance(planning, dict) or not planning:
         return PlanningDetail({}, {})
@@ -456,9 +462,34 @@ def stage_map_records(stages: Iterable[StageMapStage]) -> list[dict[str, Any]]:
     ]
 
 
+def _latest_plan_report(task_root: Path) -> Path | None:
+    reports_dir = RunRef.from_task_root(
+        task_root, "implementation-planning"
+    ).reports_dir
+    reports = list_implementation_planning_reports(reports_dir)
+    return reports[0] if reports else None
+
+
+def _snapshot_for(source: Path | None) -> StageMapSnapshot:
+    if source is None:
+        return StageMapSnapshot("missing", "", [])
+    resolved = source.resolve()
+    return StageMapSnapshot(
+        "ready",
+        str(resolved),
+        stage_map_records(parse_stage_map_file(resolved)),
+    )
+
+
 def load_task_stage_map(
     task_root: Path, manifest: dict[str, Any],
 ) -> StageMapSnapshot:
+    """완료된 stage 를 무엇으로 지었는지 답하는 Stage Map.
+
+    carry 사이드카가 가리키는 계획을 우선한다 — 그게 실행이 실제로 따른
+    문서이기 때문이다. "어떤 stage 번호가 이미 쓰였나" 는 다른 질문이며
+    `load_latest_plan_stage_map` 이 답한다.
+    """
     carried = _unique_carry_source_paths(task_root)
     if len(carried) > 1:
         paths = tuple(str(path) for path in carried)
@@ -467,22 +498,19 @@ def load_task_stage_map(
             "implementation carries reference different source plans",
             conflicting_paths=paths,
         )
-    if carried:
-        source = carried[0]
-    else:
-        reports_dir = RunRef.from_task_root(
-            task_root, "implementation-planning"
-        ).reports_dir
-        reports = list_implementation_planning_reports(reports_dir)
-        source = reports[0] if reports else None
-    if source is None:
-        return StageMapSnapshot("missing", "", [])
-    resolved = source.resolve()
-    return StageMapSnapshot(
-        "ready",
-        str(resolved),
-        stage_map_records(parse_stage_map_file(resolved)),
-    )
+    source = carried[0] if carried else _latest_plan_report(task_root)
+    return _snapshot_for(source)
+
+
+def load_latest_plan_stage_map(task_root: Path) -> StageMapSnapshot:
+    """이 task 의 최신 계획 리포트가 선언한 Stage Map.
+
+    번호 점유의 판정 기준이다. ADR-0015 는 stage 번호를 append-only 로 두고
+    새 stage 를 `max+1` 로 붙이라고 정하는데, 그 `max` 는 최신 계획에서만
+    나온다 — 완료된 stage 를 지을 때 쓴 계획 뒤에 stage 를 덧붙인 계획이
+    있으면 그 번호들도 이미 점유된 상태다.
+    """
+    return _snapshot_for(_latest_plan_report(task_root))
 
 
 def _unique_carry_source_paths(task_root: Path) -> list[Path]:
@@ -495,10 +523,30 @@ def _unique_carry_source_paths(task_root: Path) -> list[Path]:
             continue
         value = carry.get("sourcePlanPath") if isinstance(carry, dict) else None
         if isinstance(value, str) and value:
-            paths.add(_resolve_plan_path(task_root, value).resolve())
+            # carry 의 이 값은 executor 워커가 손으로 적는 자유 문자열이고,
+            # `--approved-plan` 이 레코드 전용으로 조여지기 전에 준비된 run 은
+            # 읽기본(`.md`) 경로를 남겼다. v2 리포트의 `.md` 에는 Stage Map
+            # 섹션이 없으므로 그대로 읽으면 원장이 통째로 사라진다. 같은 legacy
+            # 포인터 정규화를 run-index·타임라인 소비자는 이미 하고 있다.
+            # 읽는 쪽에서만 낮춘다 — 동결된 carry 사이드카는 고치지 않는다.
+            paths.add(_carry_source_path(task_root, value))
     return sorted(paths, key=str)
 
 
+def _carry_source_path(task_root: Path, value: str) -> Path:
+    """carry 가 가리키는 계획의 읽을 경로.
+
+    레코드 형제가 실재할 때만 읽기본(`.md`)을 레코드로 낮춘다. schema-v1 계획은
+    레코드가 아예 없고 마크다운이 유일한 정본이므로, 무조건 낮추면 v1 태스크의
+    Stage Map 을 없는 파일에서 찾게 된다.
+    """
+    resolved = _resolve_plan_path(task_root, value).resolve()
+    if not is_full_reading_copy_path(resolved):
+        return resolved
+    record = final_report_data_path(resolved)
+    return record if record.is_file() else resolved
+
+
 def _resolve_plan_path(task_root: Path, value: str) -> Path:
     path = Path(value)
     if path.is_absolute():

package/runtime/python/okstra_ctl/team.py

@@ -81,7 +81,7 @@ def _add_dispatch_parser(sub) -> None:
     parser.add_argument("--workers", default="")
     parser.add_argument("--jobs-file", default="")
     parser.add_argument("--dry-run", action="store_true")
-    parser.add_argument("--idle-timeout-seconds", type=int, default=600)
+    parser.add_argument("--idle-timeout-seconds", type=int, default=None)
     parser.add_argument("--dispatch-kind", default="initial")
 
 

package/runtime/python/okstra_ctl/worker_dispatch.py

@@ -76,7 +76,7 @@ def _parser() -> argparse.ArgumentParser:
     parser.add_argument("--okstra-bin", default="")
     parser.add_argument("--workers", default="")
     parser.add_argument("--dry-run", action="store_true")
-    parser.add_argument("--idle-timeout-seconds", default="600")
+    parser.add_argument("--idle-timeout-seconds", default="")
     parser.add_argument("--dispatch-kind", default="initial")
     parser.add_argument("--jobs-file", default="")
     return parser
@@ -86,7 +86,10 @@ def _parse_workers(raw: str) -> list[str]:
     return [item.strip() for item in raw.split(",") if item.strip()]
 
 
-def _parse_idle_timeout(raw: str) -> int:
+def _parse_idle_timeout(raw: str) -> int | None:
+    """명시된 예산, 또는 역할이 정하게 두는 ``None``."""
+    if not raw:
+        return None
     try:
         value = int(raw)
     except ValueError as exc:

package/runtime/python/okstra_ctl/worker_prompt_body.py

@@ -91,6 +91,10 @@ def report_writer_prompt_body(
     report_language: str,
 ) -> list[str]:
     """Render the provider-neutral body for the report-writer audience."""
+    if str(manifest.get("reportContractVersion") or "") == "3.0":
+        return _report_writer_v3_body(
+            manifest, active_context, team_state, model, report_language
+        )
     return [
         f"**Model:** Report writer worker, {model}",
         f"**Report Language:** {report_language}",
@@ -124,6 +128,37 @@ def report_writer_prompt_body(
     ]
 
 
+def _report_writer_v3_body(
+    manifest: Mapping[str, Any],
+    active_context: Mapping[str, Any],
+    team_state: Mapping[str, Any],
+    model: str,
+    report_language: str,
+) -> list[str]:
+    return [
+        f"**Model:** Report writer worker, {model}",
+        f"**Report Language:** {report_language}",
+        "",
+        "# Report Writer Worker Dispatch",
+        "",
+        "## Task",
+        f"- Task key: `{_require_string(manifest, 'taskKey')}`",
+        f"- Task type: `{_require_string(manifest, 'taskType')}`",
+        "",
+        "## Inputs",
+        *report_writer_input_lines(manifest, active_context, team_state),
+        "",
+        mcp_pointer_line(),
+        "",
+        "## Output Contract",
+        "You are the author of the report narrative Markdown at Result Path.",
+        "Write the worker-result pointer at Worker Result Path.",
+        "Maintain the separate audit sidecar at Audit sidecar path.",
+        "Do not write the final report record or another owner's input ledger.",
+        "Do not return the report inline.",
+    ]
+
+
 def report_writer_input_lines(
     manifest: Mapping[str, Any],
     active_context: Mapping[str, Any],

package/runtime/python/okstra_ctl/worker_prompt_policy.py

@@ -120,9 +120,7 @@ def resolve_prompt_plan(
     # that are *supposed* to differ and fail every critic-enabled run.
     analysis_equality_group = None if dispatch_kind == "critic" else "analysis-core"
     analysis_duty: AgentAudience = (
-        "acceptance-critic"
-        if dispatch_kind == "critic" and task_type == "final-verification"
-        else "scope-critic"
+        critic_duty_for_task_type(task_type)
         if dispatch_kind == "critic"
         else "acceptance-verifier"
         if task_type == "final-verification"
@@ -232,6 +230,36 @@ def _worker_facing_headers(
     return (*ERRORS_PATH_HEADERS, *required_headers)
 
 
+# 하나의 run 이 실제로 디스패치할 수 있는 critic 은 한 종류다. 판정은 task type
+# 만의 함수이므로 여기 한 번만 적고, 로스터 등록과 프롬프트 정체성 검사가 같은
+# 값을 읽는다 — 로스터가 실행될 수 없는 critic 행을 하나 더 들고 있으면 provider
+# 로만 만든 role 라벨이 겹쳐 validate-run 의 중복 역할 검사에 걸린다.
+CRITIC_DUTY_BY_ASSIGNMENT_SEGMENT: dict[str, AgentAudience] = {
+    "scope": "scope-critic",
+    "acceptance": "acceptance-critic",
+}
+
+
+def critic_duty_for_task_type(task_type: str) -> AgentAudience:
+    """이 task type 의 critic 직무."""
+    return (
+        "acceptance-critic"
+        if task_type == "final-verification"
+        else "scope-critic"
+    )
+
+
+def critic_assignment_ref(task_type: str) -> str:
+    """이 task type 이 등록할 유일한 critic 배정 참조."""
+    duty = critic_duty_for_task_type(task_type)
+    segment = next(
+        key
+        for key, value in CRITIC_DUTY_BY_ASSIGNMENT_SEGMENT.items()
+        if value == duty
+    )
+    return f"critic/{segment}"
+
+
 def _executor_worker_id(manifest: Mapping[str, Any]) -> str | None:
     team_contract = manifest.get("teamContract")
     if not isinstance(team_contract, Mapping):