okstra 0.202.0 → 0.205.0

package/runtime/python/okstra_ctl/report_synthesis_packet.py

@@ -27,6 +27,7 @@ from .implementation_options import (
 )
 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
@@ -78,6 +79,10 @@ class ReportSynthesisPacket:
     participating_analysers: tuple[str, ...] = ()
     # 증분 판정. 저작 계약이 이번 run 의 stage 번호를 말할 수 있는 유일한 출처다.
     incremental_decision: dict[str, Any] | None = None
+    # 증분이 아닌 재계획이 이어받아야 하는 이전 계획의 stage 번호. 증분 판정과
+    # 배타적이다 — 둘이 함께 실리면 같은 stage 에 "그대로 옮겨라" 와 "다시
+    # 써라" 가 동시에 도달한다.
+    prior_plan_carry: dict[str, Any] | None = None
     # 넘겨받은 완성 리포트 스키마에서 뽑은 값. 작성자는 스키마 가지를 읽지 않으므로
     # 여기 적어 줘야 도달한다(2026-09-02 실측: `Human Summary` 절 누락, `Verdict
     # Token` 에 `analysis-complete` — 둘 다 HTML 렌더에서야 거절됐다).
@@ -106,20 +111,83 @@ class ReportSynthesisPacket:
         판정을 아는 여기뿐이다.
         """
         decision = self.incremental_decision
-        if not decision:
-            return []
-        carried = ", ".join(str(stage) for stage in decision.get("carryStages", []))
-        reverify = ", ".join(str(stage) for stage in decision.get("reverifyStages", []))
+        if decision:
+            return self._incremental_carry_instructions(decision)
+        if self.prior_plan_carry:
+            return self._prior_plan_carry_instructions(self.prior_plan_carry)
+        return []
+
+    def _incremental_carry_instructions(
+        self, decision: Mapping[str, Any],
+    ) -> list[str]:
+        carry_stages = [
+            stage for stage in decision.get("carryStages", []) if isinstance(stage, int)
+        ]
+        reverify_stages = [
+            stage
+            for stage in decision.get("reverifyStages", [])
+            if isinstance(stage, int)
+        ]
+        carried = ", ".join(str(stage) for stage in carry_stages)
+        # 이월 전부·재검증 0건(`--carry-all-reason`)이 정상 판정이다. 번호 목록을
+        # 그대로 끼워 넣으면 "Author only stage(s) ." 가 되어, 덧붙이러 온 run 에게
+        # stage 를 하나도 쓰지 말라고 지시한다.
+        authoring = (
+            f"Author only stage(s) {', '.join(str(s) for s in reverify_stages)}."
+            if reverify_stages
+            else "Re-author none of them; a stage you add takes the next number "
+            f"after {max(carry_stages, default=0)}."
+        )
         return [
             "This run is an incremental re-plan. Record the decision verbatim as "
             "`implementationPlanning.incrementalDecision` with keys mode, "
             "reverifyStages, carryStages, reason.",
             f"Copy stage rows {carried} from the \"{CARRIED_STAGES_LABEL}\" source "
             f"into `implementationPlanning.stages` unchanged - every field, byte for "
-            f"byte. Author only stage(s) {reverify}. `okstra incremental-carry` "
+            f"byte. {authoring} `okstra incremental-carry` "
             f"rejects a carried stage that changed or is missing.",
         ]
 
+    def _prior_plan_carry_instructions(
+        self, carry: Mapping[str, Any],
+    ) -> list[str]:
+        """이전 계획의 번호를 다시 선언하게 하는 지시.
+
+        ADR-0015 는 stage 번호를 append-only 로 두고, 계획 파서는 발행된 모든
+        계획의 행이 1..N 이기를 요구한다(`stage_map._validate_stage_numbers`).
+        이전 stage 를 싣지 않은 리포트는 두 규칙을 동시에 만족시킬 수 없어,
+        `okstra prepare` 가 구현 run 을 거절하고 Stage 원장이 읽히지 않는다.
+        """
+        taken = [s for s in carry.get("stages", []) if isinstance(s, int)]
+        done = [s for s in carry.get("doneStages", []) if isinstance(s, int)]
+        if not taken:
+            return []
+        reauthorable = [stage for stage in taken if stage not in set(done)]
+        lines = [
+            "This task already has a plan on disk, so stage number(s) "
+            f"{', '.join(str(s) for s in taken)} are taken. "
+            "`implementationPlanning.stages` and `implementationPlanning.stageMap` "
+            "MUST declare every one of them in ascending order with no gap, and a "
+            f"stage you add takes the next number after {max(taken)}. A report whose "
+            "rows do not start at stage 1 is refused by report assembly and by "
+            "`okstra prepare` for the implementation run.",
+        ]
+        if done:
+            lines.append(
+                f"Stage(s) {', '.join(str(s) for s in done)} are already implemented: "
+                f"copy their rows from the \"{CARRIED_STAGES_LABEL}\" source unchanged "
+                "- every field, byte for byte - and do not fold their work into a new "
+                "stage."
+                + (
+                    " Stage(s) "
+                    f"{', '.join(str(s) for s in reauthorable)} are not implemented, so "
+                    "you may re-author their bodies in place, keeping their numbers."
+                    if reauthorable
+                    else ""
+                )
+            )
+        return lines
+
     def _schema_instructions(self) -> list[str]:
         """스키마가 이 task type 에 못 박은 값을 저작 계약 문장으로 옮긴다."""
         lines: list[str] = []
@@ -161,7 +229,11 @@ class ReportSynthesisPacket:
         return lines
 
     def _carry_validation_rules(self) -> list[str]:
-        return ["carried-stages-unchanged"] if self.incremental_decision else []
+        if self.incremental_decision:
+            return ["carried-stages-unchanged"]
+        if self.prior_plan_carry:
+            return ["prior-stage-numbers-declared"]
+        return []
 
     def _task_instructions(self) -> list[str]:
         if self.task_type == "technical-verification":
@@ -623,6 +695,52 @@ def carried_stage_rows(prior_data: Mapping[str, Any], carry_stages: list) -> lis
     ]
 
 
+def read_prior_plan_carry(
+    project_root: Path, manifest: Mapping[str, Any],
+) -> dict[str, Any] | None:
+    """증분이 아닌 재계획이 이어받아야 하는 이전 계획의 stage 사실. 없으면 ``None``.
+
+    증분 판정은 "무엇을 다시 검증하지 않을지" 를 말하고, 이건 "어떤 번호가 이미
+    점유됐는지" 를 말한다. 후자는 판정의 mode 와 무관하게 참이다 — 선택 방향이
+    바뀐 full 재계획도 stage 6 부터 붙여야 하고, 그러려면 1..5 를 다시 선언해야
+    한다(ADR-0015 + `stage_map._validate_stage_numbers`).
+    """
+    if _string(manifest.get("taskType")) != "implementation-planning":
+        return None
+    task_root = _string(manifest.get("taskRootPath"))
+    if not task_root:
+        return None
+    ledger = build_stage_ledger(_resolve(project_root, task_root))
+    # `None` 은 첫 계획 run, `unreadable` 은 계획을 못 읽은 것이다. 후자에서
+    # 번호를 주장하면 읽지 못한 파일을 근거로 지시하는 셈이고, 그 사실은
+    # analysis packet 이 이미 통지한다.
+    if not ledger or ledger.get("unreadable"):
+        return None
+    records = [
+        row
+        for row in ledger.get("stages") or ()
+        if isinstance(row, Mapping) and isinstance(row.get("stage"), int)
+    ]
+    if not records:
+        return None
+    return {
+        "sourcePlanPath": _string(ledger.get("latestPlan")),
+        "stages": sorted(row["stage"] for row in records),
+        "doneStages": sorted(
+            row["stage"] for row in records if row.get("status") == "done"
+        ),
+    }
+
+
+@dataclass(frozen=True)
+class CarriedStages:
+    """이월 source 파일과 그것을 만든 근거. 둘 중 하나만 채워진다."""
+
+    source_path: str
+    incremental_decision: dict[str, Any] | None = None
+    prior_plan: dict[str, Any] | None = None
+
+
 def carried_stages_path(narrative_path: Path) -> Path:
     _, markdown_path = report_synthesis_packet_paths(narrative_path)
     return markdown_path.with_name(
@@ -637,24 +755,60 @@ def materialize_carried_stages(
     project_root: Path,
     manifest: Mapping[str, Any],
     narrative_path: Path,
-) -> tuple[str, dict] | None:
-    """이월 stage 본문을 파일로 남기고 (프로젝트 상대 경로, 판정) 을 돌려준다.
+) -> CarriedStages | None:
+    """이월 stage 본문을 파일로 남기고 그 근거와 함께 돌려준다.
 
     묶음의 source 는 파일과 그 다이제스트다. 파생 내용을 특례로 인라인하지 않고
     실제 파일로 만드는 이유는 두 가지다 — 다이제스트가 다른 source 와 같은
     의미를 갖고, 어긋났을 때 사람이 열어 볼 수 있다.
+
+    이월 근거는 둘이고 증분 판정이 이긴다. 증분이면 검증을 건너뛰는 stage 의
+    본문이 필요하고, 아니면 번호를 점유한 stage 전부의 본문이 필요하다.
     """
     decision = read_incremental_decision(project_root, manifest)
-    if decision is None:
+    if decision is not None:
+        return _materialize_stage_rows(
+            project_root=project_root,
+            narrative_path=narrative_path,
+            source_plan=_string(decision.get("prevDataPath")),
+            stages=[
+                stage for stage in decision["carryStages"] if isinstance(stage, int)
+            ],
+            carried=CarriedStages("", incremental_decision=decision),
+        )
+    prior_plan = read_prior_plan_carry(project_root, manifest)
+    if prior_plan is None:
         return None
-    prior = _resolve(project_root, _string(decision.get("prevDataPath")))
+    # 본문이 동결되는 것은 완료된 stage 뿐이다. 완료가 없으면 옮길 행이 없고,
+    # 빈 source 를 실으면 작성자가 옮길 것 없는 파일을 읽는다 — 번호를 이어받는
+    # 지시만 남긴다.
+    if not prior_plan["doneStages"]:
+        return CarriedStages("", prior_plan=prior_plan)
+    return _materialize_stage_rows(
+        project_root=project_root,
+        narrative_path=narrative_path,
+        source_plan=_string(prior_plan.get("sourcePlanPath")),
+        stages=list(prior_plan["doneStages"]),
+        carried=CarriedStages("", prior_plan=prior_plan),
+    )
+
+
+def _materialize_stage_rows(
+    *,
+    project_root: Path,
+    narrative_path: Path,
+    source_plan: str,
+    stages: list[int],
+    carried: CarriedStages,
+) -> CarriedStages | None:
+    prior = _resolve(project_root, source_plan)
     if not prior.is_file():
         return None
     try:
         prior_data = load_owned_object(prior, artifact="prior planning report")
     except (OSError, UnicodeError, JsonBoundaryError):
         return None
-    rows = carried_stage_rows(prior_data, decision["carryStages"])
+    rows = carried_stage_rows(prior_data, stages)
     if not rows:
         return None
     path = carried_stages_path(narrative_path)
@@ -662,16 +816,21 @@ def materialize_carried_stages(
         path,
         {
             "schemaVersion": "1.0",
-            "sourcePlanPath": _string(decision.get("prevDataPath")),
-            "carryStages": list(decision["carryStages"]),
+            "sourcePlanPath": source_plan,
+            "carryStages": list(stages),
             "stages": rows,
         },
         artifact="carried plan stages",
     )
     try:
-        return str(path.resolve().relative_to(project_root.resolve())), decision
+        relative = str(path.resolve().relative_to(project_root.resolve()))
     except ValueError:
-        return str(path), decision
+        relative = str(path)
+    return CarriedStages(
+        relative,
+        incremental_decision=carried.incremental_decision,
+        prior_plan=carried.prior_plan,
+    )
 
 
 def _source_specs(
@@ -878,7 +1037,7 @@ def build_report_synthesis_packet(
             active_context,
             team_state,
             narrative_path,
-            carried[0] if carried else "",
+            carried.source_path if carried else "",
         ),
     )
     task_type = _string(manifest.get("taskType"))
@@ -918,7 +1077,8 @@ def build_report_synthesis_packet(
         accounting_snapshot=_accounting_snapshot(team_state),
         original_requirement_ids=original_requirement_ids,
         participating_analysers=participating_analysers,
-        incremental_decision=carried[1] if carried else None,
+        incremental_decision=carried.incremental_decision if carried else None,
+        prior_plan_carry=carried.prior_plan if carried else None,
     )
 
 

package/runtime/python/okstra_ctl/report_translation.py

@@ -182,6 +182,7 @@ STRUCTURAL_KEYS = frozenset({
     "area",               # slug-shaped ('scan-coverage')
     "artifact",
     "baseBranch",
+    "baseKind",
     "baseRefSha",
     "baseSha",
     "boundary",
@@ -194,7 +195,6 @@ STRUCTURAL_KEYS = frozenset({
     "clarificationId",
     "classification",
     "claudeCode",
-    "collectorBranch",
     "command",
     "commandOrObservation",
     "commandOrTest",
@@ -232,6 +232,7 @@ STRUCTURAL_KEYS = frozenset({
     "gitStatusShort",
     "h1c",
     "h2",
+    "headBranch",
     "id",
     "impact",             # 'high' / 'medium' alongside prose
     "impactKind",

package/runtime/python/okstra_ctl/report_translation_dispatch.py

@@ -10,9 +10,11 @@ fontsninja-v3-site dev-10628-3 implementation-option-selection, grok 리드):
 한 줄을 남겼고 HTML 은 영어로 남았다.
 
 이 모듈은 그 절차를 `report-finalize` 의 한 단계로 내린다. 예약이 없으면 지시문과
-프롬프트를 발행하고(`agent-prompt materialize` 와 같은 코드), CLI 래퍼 디스패처로
-워커를 띄운 뒤 사이드카가 생겼는지 본다. 디스패치 기록과 결과 링크는
-`dispatch_core` 가 배치 안에서 이미 하므로 여기서 다시 하지 않는다.
+프롬프트를 발행하고(`agent-prompt materialize` 와 같은 코드), 워커를 띄운 뒤
+사이드카가 생겼는지 본다. cmux run 이면 다른 워커와 같은 pane 으로 띄우고 끝날
+때까지 기다린다(`team dispatch` + `team await` 와 같은 코드). 그 밖의 run 은 CLI
+래퍼 디스패처로 띄운다. 디스패치 기록과 결과 링크는 `dispatch_core` 가 배치 안에서
+이미 하므로 여기서 다시 하지 않는다.
 """
 from __future__ import annotations
 
@@ -25,7 +27,15 @@ from typing import Any, Mapping
 
 from . import worker_dispatch
 from .agent.prompt_cli.cli import main as agent_prompt_main
-from .dispatch_core import translator_reservations
+from .application.dispatch_assignments import dispatch_assignments
+from .dispatch_core import (
+    BACKEND_CMUX_PANE,
+    await_dispatches,
+    dispatch_plan,
+    translator_reservations,
+)
+from .ports.worker_dispatch import WorkerDispatchRequest
+from .team import team_dispatch_port
 from .dispatch_state import (
     DispatchError,
     load_json_object,
@@ -111,7 +121,9 @@ def translate_report(
         metadata_path = ensure_translator_reservation(
             project_root, manifest_path, manifest, lang
         )
-        dispatch = dispatch_translator(project_root, workspace_root, manifest_path)
+        dispatch = dispatch_translator(
+            project_root, workspace_root, manifest_path, manifest
+        )
     except TranslateError as exc:
         return TranslateOutcome(1, "", str(exc))
     if sidecar.is_file():
@@ -166,13 +178,22 @@ def ensure_translator_reservation(
 
 
 def dispatch_translator(
-    project_root: Path, workspace_root: Path, manifest_path: Path,
+    project_root: Path,
+    workspace_root: Path,
+    manifest_path: Path,
+    manifest: Mapping[str, Any],
 ) -> TranslateOutcome:
-    """`okstra worker-dispatch --workers translator` 와 같은 코드를 프로세스 안에서 돈다.
+    """번역 워커를 띄우고 끝날 때까지 기다린다.
 
-    디스패처는 결과 JSON 을 stdout 에 찍는다. Phase 7 의 stdout 은 finalize 결과
-    JSON 하나여야 하므로 여기서 받아 단계 결과로 넘긴다.
+    cmux run 은 pane 으로 띄운다 — 사용자가 다른 워커처럼 진행을 화면에서 본다.
+    그 밖의 run 은 `okstra worker-dispatch --workers translator` 와 같은 코드를
+    프로세스 안에서 돈다. 디스패처는 결과 JSON 을 stdout 에 찍는다. Phase 7 의
+    stdout 은 finalize 결과 JSON 하나여야 하므로 여기서 받아 단계 결과로 넘긴다.
     """
+    if str(manifest.get("terminalBackend") or "") == BACKEND_CMUX_PANE:
+        return _dispatch_translator_pane(
+            project_root, workspace_root, manifest_path, manifest
+        )
     out, err = io.StringIO(), io.StringIO()
     with contextlib.redirect_stdout(out), contextlib.redirect_stderr(err):
         try:
@@ -187,6 +208,45 @@ def dispatch_translator(
     return TranslateOutcome(code, out.getvalue(), err.getvalue())
 
 
+def _dispatch_translator_pane(
+    project_root: Path,
+    workspace_root: Path,
+    manifest_path: Path,
+    manifest: Mapping[str, Any],
+) -> TranslateOutcome:
+    """`okstra team dispatch --workers translator` 뒤 `okstra team await` 와 같다.
+
+    pane 을 열지 못하면 디스패처가 CLI 래퍼로 강등하고 `DEGRADED` 줄과
+    `degradedReason` 을 남긴다 — 그 경우도 여기서 같은 대기로 정산된다. pane 은
+    run 끝의 `okstra team teardown` 이 기록을 보고 닫는다.
+    """
+    request = WorkerDispatchRequest(
+        project_root=project_root,
+        run_manifest=manifest_path,
+        workspace_root=workspace_root,
+        okstra_bin=None,
+        requested_workers=(TRANSLATOR_WORKER_ID,),
+        idle_timeout_seconds=None,
+        dispatch_kind="initial",
+        jobs_file=None,
+    )
+    out, err = io.StringIO(), io.StringIO()
+    with contextlib.redirect_stdout(out), contextlib.redirect_stderr(err):
+        try:
+            plan = dispatch_assignments(request, team_dispatch_port(manifest))
+            backend_plan = plan.backend_plan
+            if backend_plan is None:
+                raise TranslateError(
+                    "translator pane dispatch did not produce a backend plan"
+                )
+            code = dispatch_plan(backend_plan, wait=False)
+            if code == 0:
+                code = await_dispatches(backend_plan, heartbeat_seconds=0)
+        except (DispatchError, OSError) as exc:
+            raise TranslateError(f"translator dispatch failed: {exc}") from exc
+    return TranslateOutcome(code, out.getvalue(), err.getvalue())
+
+
 def _materialize_translator(
     project_root: Path,
     manifest_path: Path,