okstra 0.218.0 → 0.219.1

package/runtime/python/okstra_ctl/dispatch_core.py

@@ -674,7 +674,7 @@ def _dispatch_cli_wrapper_batch(
         # (`_persisted_write_contract`) attempt 2 의 정책 digest 는 attempt 1 과
         # 다른데, 첫 라운드의 baseline 을 그대로 쓰면 마감의
         # `_validate_snapshot_authority` 가 `policyDigests` 불일치로 죽고 attempt-N
-        # 사이드카는 끝내 안 써진다(실측 2026-09-08, translator attempt 2:
+        # 사이드카는 끝내 안 써진다(실측 2026-09-08, 워커 attempt 2:
         # 산출물 완전·exit 0 인데 dispatcher 예외). 앞 라운드에서 완주한 동료의
         # 변경은 그 attempt 의 감사가 이미 판정했으므로 새 baseline 에 흡수돼도
         # 맞다 — 재시도는 `failed-no-mutation` 뒤에만 오므로(`retry_allowed`)
@@ -920,15 +920,6 @@ def _jobs_from_roster(
         options,
         team_state=team_state,
     )
-    if selected == ["translator"]:
-        return [_translator_job_from_reservation(
-            project_root,
-            workspace_root,
-            manifest,
-            team_state,
-            active_context,
-            options,
-        )]
     _mark_roster_skips(project_root, manifest, team_state, selected, requested_workers, options)
     worker_facts, prompt_paths = _materialize_roster_prompts(
         project_root,
@@ -962,29 +953,6 @@ def _select_workers(
     *,
     team_state: Mapping[str, Any] | None = None,
 ) -> list[str]:
-    # 번역자 디스패치는 roster 를 읽지 않는다 — 근거는 prepare 가 심는 canonical
-    # translator role execution 이다. 그래서 빈 roster 검사보다 앞에 둔다.
-    # 종전에는 뒤에 있어서, roster 가 비는 phase 에서 이 분기에 닿을 수 없었다:
-    # `release-handoff` 는 의도적으로 single-lead 라 `_resolve_roster` 가 빈
-    # 목록을 강제하는데(`run.py`), `reportLanguage` 가 en 이 아니면 render-views 는
-    # 번역 사이드카를 요구한다. 두 요구가 겹치면 예약 경로는 "run manifest has no
-    # recommendedWorkers entries" 로, jobs-file 경로는 "jobs file translator must
-    # use canonical reservation dispatch" 로 막혀 번역자를 띄울 방법이 없었다
-    # (실측 2026-09-07, fontsninja-v3-site dev-10626 release-handoff 001 — 리드가
-    # `okstra report-translate write` 로 우회했고, 그 run 의 매니페스트에는
-    # translator role execution 과 invocationAssignments.translator 가 둘 다 있다).
-    if tuple(requested_workers) == ("translator",):
-        provider = _canonical_translator_provider(manifest)
-        if provider is None:
-            raise DispatchError(
-                "translator dispatch requires a canonical translator role execution"
-            )
-        if provider not in options.supported_worker_wrappers:
-            raise DispatchError(
-                f"unsupported {options.unsupported_worker_label} translator provider: "
-                f"{provider}"
-            )
-        return ["translator"]
     recommended = _string_list(manifest.get("recommendedWorkers"))
     if not recommended:
         raise DispatchError("run manifest has no recommendedWorkers entries")
@@ -1027,270 +995,6 @@ def _select_workers(
     return selected
 
 
-def _canonical_translator_provider(manifest: Mapping[str, Any]) -> str | None:
-    execution = _canonical_translator_execution(manifest)
-    return _string_value(execution.get("provider")) if execution else None
-
-
-def _canonical_translator_execution(
-    manifest: Mapping[str, Any],
-) -> Mapping[str, Any] | None:
-    assignments = manifest.get("invocationAssignments")
-    assignment = (
-        assignments.get("translator") if isinstance(assignments, Mapping) else None
-    )
-    if not isinstance(assignment, Mapping):
-        return None
-    provider = _string_value(assignment.get("provider"))
-    model_execution = _string_value(assignment.get("modelExecutionValue"))
-    runner = _string_value(assignment.get("runner"))
-    if not provider or not model_execution or runner != BACKEND_CLI_WRAPPER:
-        return None
-    role_executions = manifest.get("roleExecutions")
-    matches = [
-        row
-        for row in role_executions
-        if isinstance(row, Mapping)
-        and row.get("role") == "translator"
-        and row.get("provider") == provider
-        and isinstance(row.get("binding"), Mapping)
-        and row["binding"].get("runner") == runner
-        and row["binding"].get("resolvedExecutionValue") == model_execution
-    ] if isinstance(role_executions, list) else []
-    return matches[0] if len(matches) == 1 else None
-
-
-_TRANSLATOR_RESERVATION_KEYS = {
-    "schemaVersion", "executionIdentityVersion", "invocationId",
-    "assignmentRef", "audience", "dispatchKind", "promptPath",
-    "metadataPath", "invocationRef", "participantRef",
-    "roleExecutionRef", "dutyId", "attempt",
-}
-
-
-def _translator_job_from_reservation(
-    project_root: Path,
-    workspace_root: Path,
-    manifest: Mapping[str, Any],
-    team_state: Mapping[str, Any],
-    active_context: Mapping[str, Any],
-    options: _BuildOptions,
-) -> WorkerJob:
-    execution = _canonical_translator_execution(manifest)
-    if execution is None:
-        raise DispatchError(
-            "translator dispatch requires a canonical translator role execution"
-        )
-    candidates, seen = translator_reservations(project_root, manifest, team_state)
-    run_manifest_rel = _string_value(manifest.get("runManifestPath"))
-    if len(candidates) != 1:
-        run_label = run_manifest_rel or "run manifest path unknown"
-        raise DispatchError(
-            "translator dispatch requires exactly one canonical invocation "
-            f"reservation for this run ({run_label}); found {len(candidates)}. "
-            "Translator reservations seen: " + ("; ".join(seen) if seen else "none")
-        )
-    reservation = candidates[0]
-    prompt_path = _resolve_project_path(
-        project_root, _require_string(reservation, "promptPath")
-    )
-    metadata_path = _resolve_project_path(
-        project_root, _require_string(reservation, "metadataPath")
-    )
-    expected_metadata = prompt_path.with_name(prompt_path.name + ".meta.json")
-    if metadata_path != expected_metadata:
-        raise DispatchError("translator invocation metadata path is not prompt-adjacent")
-    metadata = _load_json_object(metadata_path, "agent invocation metadata")
-    invocation = _invocation_job_fields(metadata, prompt_path, manifest)
-    expected = {
-        "invocationId": invocation["invocation_id"],
-        "invocationRef": invocation["invocation_ref"],
-        "participantRef": invocation["participant_ref"],
-        "roleExecutionRef": invocation["role_execution_ref"],
-        "dutyId": invocation["duty_id"],
-        "attempt": invocation["attempt"],
-    }
-    if any(reservation.get(key) != value for key, value in expected.items()):
-        raise DispatchError("translator reservation and invocation metadata differ")
-    if (
-        invocation["audience"] != "translator"
-        or invocation["assignment_ref"] != "translator"
-        or metadata.get("dispatchKind") != "translator"
-    ):
-        raise DispatchError("translator invocation identity is invalid")
-    result_path, worker_result_path = _translator_prompt_outputs(
-        project_root, prompt_path
-    )
-    if result_path == worker_result_path:
-        raise DispatchError(
-            "translator result and standard worker result paths must differ"
-        )
-    provider = _require_string(execution, "provider")
-    binding = execution.get("binding")
-    if not isinstance(binding, Mapping):
-        raise DispatchError("translator role execution has no binding")
-    return WorkerJob(
-        worker_id="translator",
-        provider=provider,
-        backend=options.default_backend,
-        project_root=project_root,
-        model_execution_value=_require_string(binding, "resolvedExecutionValue"),
-        wrapper_path=_resolve_wrapper(provider, workspace_root, options),
-        prompt_path=prompt_path,
-        result_path=result_path,
-        worker_result_path=worker_result_path,
-        completion_paths=(result_path, worker_result_path),
-        worktree_path=_worktree_path(manifest, active_context),
-        role="translator",
-        idle_timeout_seconds=options.idle_timeout_seconds,
-        dispatch_kind="translator",
-        **invocation,
-    )
-
-
-def translator_reservations(
-    project_root: Path,
-    manifest: Mapping[str, Any],
-    team_state: Mapping[str, Any],
-) -> tuple[list[Mapping[str, Any]], list[str]]:
-    """이 run 이 지금 디스패치할 수 있는 translator 예약과, 본 예약 전부의 요약.
-
-    두 소비자가 같은 답을 읽는다: `_translator_job_from_reservation` 은 그 하나를
-    골라 띄우고, `report-finalize` 의 `translate` 단계
-    (`okstra_ctl.report_translation_dispatch`) 는 0건이면 예약을 만든다. 후보를
-    세는 규칙이 두 곳이면 한쪽만 고쳐져 "만들었는데 못 고른다" 가 나온다.
-    """
-    execution = _canonical_translator_execution(manifest)
-    if execution is None:
-        raise DispatchError(
-            "translator dispatch requires a canonical translator role execution"
-        )
-    contract = manifest.get("agentContract")
-    if not isinstance(contract, Mapping):
-        raise DispatchError("translator dispatch requires an agent contract")
-    reservation_root = _resolve_required_path(
-        project_root, contract, "invocationReservationRootPath"
-    )
-    dispatched_ids = {
-        str(row.get("dispatchId") or "")
-        for collection in (
-            team_state.get("workerDispatches") or [],
-            team_state.get("agentDispatches") or [],
-        )
-        for row in collection
-        if isinstance(row, Mapping)
-    }
-    return _translator_reservation_candidates(
-        project_root,
-        reservation_root,
-        execution=execution,
-        dispatched_ids=dispatched_ids,
-        run_manifest_rel=_string_value(manifest.get("runManifestPath")),
-    )
-
-
-def _translator_reservation_candidates(
-    project_root: Path,
-    reservation_root: Path,
-    *,
-    execution: Mapping[str, Any],
-    dispatched_ids: set[str],
-    run_manifest_rel: str,
-) -> tuple[list[Mapping[str, Any]], list[str]]:
-    """이 run 이 디스패치할 수 있는 translator 예약과, 본 예약 전부의 요약.
-
-    예약 디렉터리(`prompts/.agent-invocations/`)는 run 이 아니라 task type 단위라
-    같은 task 의 이전 run 이 남긴 translator 예약이 함께 놓인다. translator 는
-    `assignmentRef` 가 접미 없는 `translator` 하나이고, 이전 run 의 디스패치는
-    이번 run 의 team-state 에 없으므로 "아직 디스패치 안 됨" 으로 읽혀 후보가
-    둘이 됐다 — 두 번째 run 부터 번역이 영영 막혔다(2026-09-03 실측,
-    fontsninja-v3-site dev-10626-1 r02·r04). 예약 자체는 run 을 모르지만 그 옆의
-    `.meta.json` 은 `contractSource.runManifestPath` 로 자기 run 을 안다. 그
-    값을 이번 run 의 `runManifestPath` 와 대조한다. 매니페스트가 그 경로를 안
-    가진 레거시 run 은 종전대로 run 을 가리지 않는다.
-    """
-    candidates: list[Mapping[str, Any]] = []
-    seen: list[str] = []
-    for path in sorted(reservation_root.glob("*.json")):
-        reservation = _load_json_object(path, "agent invocation reservation")
-        if not (
-            set(reservation) == _TRANSLATOR_RESERVATION_KEYS
-            and reservation.get("schemaVersion") == "2.0"
-            and reservation.get("executionIdentityVersion") == 2
-            and reservation.get("assignmentRef") == "translator"
-            and reservation.get("audience") == "translator"
-            and reservation.get("dispatchKind") == "translator"
-            and reservation.get("dutyId") == "translator"
-        ):
-            continue
-        invocation_id = str(reservation.get("invocationId") or "")
-        reservation_run = _reservation_run_manifest_rel(project_root, reservation)
-        dispatched = _build_dispatch_id(
-            invocation_id, int(reservation.get("attempt") or 0),
-        ) in dispatched_ids
-        seen.append(
-            f"{invocation_id} (run {reservation_run or 'unknown'}"
-            + (", dispatched" if dispatched else "")
-            + ")"
-        )
-        if dispatched:
-            continue
-        if (
-            reservation.get("participantRef") != execution.get("participantRef")
-            or reservation.get("roleExecutionRef") != execution.get("roleExecutionRef")
-        ):
-            continue
-        if run_manifest_rel and (
-            reservation_run is None
-            or os.path.normpath(reservation_run) != os.path.normpath(run_manifest_rel)
-        ):
-            continue
-        candidates.append(reservation)
-    return candidates, seen
-
-
-def _reservation_run_manifest_rel(
-    project_root: Path, reservation: Mapping[str, Any],
-) -> str | None:
-    """예약 옆 `.meta.json` 의 `contractSource.runManifestPath`. 못 읽으면 None."""
-    metadata_value = _string_value(reservation.get("metadataPath"))
-    if not metadata_value:
-        return None
-    try:
-        metadata = _load_json_object(
-            _resolve_project_path(project_root, metadata_value),
-            "agent invocation metadata",
-        )
-    except DispatchError:
-        return None
-    source = metadata.get("contractSource")
-    if not isinstance(source, Mapping):
-        return None
-    return _string_value(source.get("runManifestPath")) or None
-
-
-def _translator_prompt_outputs(
-    project_root: Path, prompt_path: Path,
-) -> tuple[Path, Path]:
-    try:
-        lines = prompt_path.read_text(encoding="utf-8").splitlines()
-    except OSError as exc:
-        raise DispatchError(f"cannot read translator prompt: {exc}") from exc
-    values: list[str] = []
-    for header in ("Result Path", "Worker Result Path"):
-        prefix = f"**{header}:** "
-        matches = [line[len(prefix):].strip() for line in lines if line.startswith(prefix)]
-        if len(matches) != 1 or not matches[0]:
-            raise DispatchError(
-                f"translator prompt requires exactly one non-empty {prefix.strip()} header"
-            )
-        values.append(matches[0])
-    return (
-        _resolve_project_path(project_root, values[0]),
-        _resolve_project_path(project_root, values[1]),
-    )
-
-
 def _select_cli_wrapper_assignments(
     recommended: Sequence[str],
     requested_workers: Sequence[str],
@@ -2878,27 +2582,6 @@ def _wrapper_log_tail(job: WorkerJob) -> str | None:
     return tail.decode("utf-8", errors="replace").strip() or None
 
 
-def _projectionless_translator(plan: DispatchPlan, job: WorkerJob) -> bool:
-    if not (
-        job.has_execution_identity
-        and job.role == "translator"
-        and job.worker_id == "translator"
-        and job.audience == "translator"
-        and job.assignment_ref == "translator"
-        and job.duty_id == "translator"
-        and job.dispatch_kind == "translator"
-    ):
-        return False
-    execution = _canonical_translator_execution(plan.manifest)
-    return bool(
-        execution
-        and execution.get("roleExecutionRef") == job.role_execution_ref
-        and execution.get("participantRef") == job.participant_ref
-        and execution.get("executionLabel") == job.execution_label
-        and execution.get("provider") == job.provider
-    )
-
-
 def _transition_job_status(
     plan: DispatchPlan,
     job: WorkerJob,
@@ -2907,24 +2590,6 @@ def _transition_job_status(
     *,
     model_execution_value: str = "",
 ) -> None:
-    if not _projectionless_translator(plan, job):
-        _transition_worker_status(
-            plan.team_state_path,
-            job.worker_id,
-            status,
-            reason,
-            model_execution_value=model_execution_value,
-        )
-        return
-    team_state = _load_json_object(plan.team_state_path, "team-state")
-    workers = team_state.get("workers")
-    if not isinstance(workers, list):
-        raise DispatchError("team-state workers must be an array")
-    if not any(
-        isinstance(row, Mapping) and row.get("workerId") == job.worker_id
-        for row in workers
-    ):
-        return
     _transition_worker_status(
         plan.team_state_path,
         job.worker_id,
@@ -2945,20 +2610,9 @@ def _job_terminal_status(
         row for row in workers
         if isinstance(row, Mapping) and row.get("workerId") == job.worker_id
     ]
-    if len(matches) == 1:
-        return _string_value(matches[0].get("status"))
-    if matches or not _projectionless_translator(plan, job):
+    if len(matches) != 1:
         raise DispatchError(f"team-state has no unique workerId={job.worker_id}")
-    dispatches = team_state.get("workerDispatches")
-    records = [
-        row for row in dispatches
-        if isinstance(row, Mapping)
-        and row.get("promptPath") == str(job.prompt_path)
-        and row.get("attempt") == attempt
-    ] if isinstance(dispatches, list) else []
-    if len(records) != 1:
-        raise DispatchError("translator dispatch has no unique status record")
-    return _string_value(records[0].get("status"))
+    return _string_value(matches[0].get("status"))
 
 
 def _record_dispatch(

package/runtime/python/okstra_ctl/dispatch_state.py

@@ -2221,19 +2221,6 @@ def _validate_v2_jobs_file_authority(
         )
     if errors:
         raise DispatchError("jobs file v2 authority: " + "; ".join(errors))
-    role_executions = {
-        string_value(row.get("roleExecutionRef")): row
-        for row in manifest.get("roleExecutions") or []
-        if isinstance(row, Mapping)
-    }
-    if any(
-        isinstance(role_executions.get(job.role_execution_ref), Mapping)
-        and role_executions[job.role_execution_ref].get("role") == "translator"
-        for job in jobs
-    ):
-        raise DispatchError(
-            "jobs file translator must use canonical reservation dispatch"
-        )
 
 
 def worker_jobs_from_file(

package/runtime/python/okstra_ctl/domain/provider.py

@@ -275,6 +275,6 @@ def _legacy_execution_capabilities(roles: frozenset[str]) -> frozenset[str]:
             capabilities.add("source-readonly")
         if role == "implementer":
             capabilities.add("project-mutation")
-        if role in {"report-writer", "translator"}:
+        if role == "report-writer":
             capabilities.add("extended-artifact-authoring")
     return frozenset(capabilities)

package/runtime/python/okstra_ctl/domain/role.py

@@ -35,11 +35,6 @@ ROLE_DEFINITIONS = (
         (),
         _READONLY_CAPABILITIES | frozenset({"extended-artifact-authoring"}),
     ),
-    RoleDefinition(
-        "translator",
-        (),
-        _READONLY_CAPABILITIES | frozenset({"extended-artifact-authoring"}),
-    ),
 )
 
 DUTY_ROLE_IDS = {
@@ -61,7 +56,6 @@ DUTY_ROLE_IDS = {
     "schedule-verifier": "verifier",
     "business-flow-investigator": "analyser",
     "report-writer": "report-writer",
-    "translator": "translator",
 }
 
 

package/runtime/python/okstra_ctl/final_report_paths.py

@@ -6,7 +6,6 @@ from pathlib import Path
 
 DATA_JSON_SUFFIX = ".data.json"
 MARKDOWN_SUFFIX = ".md"
-TRANSLATION_SOURCE_SUFFIX = ".translation-source.json"
 
 
 def _stem(data_path: Path) -> str:
@@ -106,21 +105,6 @@ def timeline_report_record_rel(run: dict) -> str:
     return report_record_rel_from_legacy_pointer(str(run.get("reportPath") or ""))
 
 
-def translation_source_path(data_path: Path) -> Path:
-    """Return the translator's work list for a final-report data.json path."""
-    return data_path.with_name(_stem(data_path) + TRANSLATION_SOURCE_SUFFIX)
-
-
-def translation_sidecar_path(data_path: Path, lang: str) -> Path:
-    """Return the filled translation sidecar the HTML renderer overlays.
-
-    One file per language beside the report it translates, so the renderer
-    finds it from the data.json alone and a run for another language does not
-    overwrite it.
-    """
-    return data_path.with_name(f"{_stem(data_path)}.i18n.{lang}.json")
-
-
 def sidecar_source_rel(path: Path) -> str:
     """사이드카 프론트매터가 `source-report` / `source-data` 에 적는 경로.
 

package/runtime/python/okstra_ctl/i18n.py

@@ -47,8 +47,8 @@ def load_dictionary(lang: str, rel: tuple[str, ...] = DICTIONARY_REL) -> dict[st
     """`<lang>.json` 이 있으면 그것, 없으면 영어 사전.
 
     사전은 페이지 크롬(표 머리글·빈 상태·enum 라벨)의 고정 문자열이고 본문은
-    번역 사이드카가 덮는다. 사전이 없는 언어의 리포트는 본문은 그 언어, 크롬은
-    영어로 나온다 — 사전이 없다고 렌더를 거절하면 독자는 아무것도 못 받는다.
+    report-writer 가 리포트 언어로 쓴다. 사전이 없는 언어의 리포트는 본문은 그
+    언어, 크롬은 영어로 나온다 — 사전이 없다고 렌더를 거절하면 독자는 아무것도 못 받는다.
     """
     directory = _i18n_dir(rel)
     path = directory / f"{lang}.json"

package/runtime/python/okstra_ctl/path_hints.py

@@ -119,7 +119,6 @@ def hydrate_active_run_context(payload: Mapping[str, Any]) -> dict[str, Any]:
                     "IMPLEMENTATION_WORKER_PREAMBLE_PATH", ""
                 ),
                 "report-writer": ctx.get("REPORT_WRITER_PREAMBLE_PATH", ""),
-                "translator": ctx.get("TRANSLATOR_PREAMBLE_PATH", ""),
             },
             "workerErrorContractPath": ctx.get("WORKER_ERROR_CONTRACT_PATH", ""),
             "hostSessionContractPath": (
@@ -515,9 +514,6 @@ def _runtime_fields(paths: Mapping[str, Any]) -> dict[str, str]:
         "REPORT_WRITER_PREAMBLE_PATH": str(
             runtime_home / "templates" / "report-writer-prompt-preamble.md"
         ),
-        "TRANSLATOR_PREAMBLE_PATH": str(
-            runtime_home / "templates" / "translator-prompt-preamble.md"
-        ),
         "WORKER_ERROR_CONTRACT_PATH": str(
             runtime_home / "templates" / "worker-error-contract.md"
         ),

package/runtime/python/okstra_ctl/paths.py

@@ -663,9 +663,6 @@ def compute_run_paths(
         "REPORT_WRITER_PREAMBLE_PATH": str(
             runtime_home / "templates" / "report-writer-prompt-preamble.md"
         ),
-        "TRANSLATOR_PREAMBLE_PATH": str(
-            runtime_home / "templates" / "translator-prompt-preamble.md"
-        ),
         "WORKER_ERROR_CONTRACT_PATH": str(
             runtime_home / "templates" / "worker-error-contract.md"
         ),

package/runtime/python/okstra_ctl/phases/final_verification/profile.md

@@ -12,6 +12,7 @@
     - DB / IO / SQL real-execution evidence — trigger: the diff touches DB/IO/SQL (ORM / query-builder, `*.repository.*`, model / `migrations/**` / `*.sql`, or changed query strings). Then Validation Evidence MUST cite a real (or faithful-replica) DB execution — the `db-test` command + exit code — not a mock-only suite. Rationale: a mock-only suite cannot observe the SQL actually emitted (observed failure class: `prompts/profiles/_implementation-verifier.md` §"DB / IO / SQL change — real-execution gate"). A DB-touching change whose only evidence is mocked, or for which no `db-test` ran, is an **Acceptance Blocker** (`major`+; per the Verdict vocabulary below, any blocker moves the verdict off `accepted`). This gate stops an unverified DB change from reaching `release-handoff` and being pushed.
       - **External Tier 3 de-duplication exception.** A DB/IO/SQL surface covered by an in-scope Tier 3 entry whose `requires` include `db`, `http`, or `external` is governed by the External QA outcome policy. Its non-PASS or unavailable result MUST NOT generate a second legacy db-test-not-configured or mock-only blocker solely for that same Tier 3 non-PASS or unavailable result. Tier 1 or Tier 2 failures remain blocking, and DB surfaces without declared external Tier 3 coverage remain blocking.
     - no new defects introduced — the diff does not break previously-working behaviour and adds no new bug (logic/off-by-one, null/empty handling, resource leaks, broken error paths)
+    - no security defect on input from outside the process — for every changed file that reads a request body, query, header, upload, message or webhook, or acts on its behalf: work that grows faster than the input (pairwise uniqueness, nested scans, a backtracking regex, input-driven recursion) runs only after a size/count bound has rejected oversized input — check the validation framework's configuration, since class-validator without `stopAtFirstError` still runs `@ArrayUnique` after `@ArrayMaxSize` fails and a byte-size body limit does not bound element count; input reaches SQL, shell commands, file paths, server-side fetch targets, templates and regexes only through parameters, allowlists or escaping; a new route / handler / resolver carries the project's auth guard and compares the caller with the owner of an input-chosen id; no secret, full token, password or personal data reaches source, logs, error messages or responses; nothing evaluates or unsafely deserializes input. Each hit is an Acceptance Blocker citing the triggering input and its effect. The same rules, with examples, are `clean-code.md` "Untrusted input and security" in the installed coding-preflight pack (`~/.okstra/prompts/coding-preflight/clean-code.md`).
     - scope conformance — the delivered diff stays within the approved plan's scope; flag out-of-scope edits, unrelated file changes, leftover debug/commented-out code, and unintended deletions
     - project review-rule packs — a pack applies when either source names it: the task brief's `Source Material` / `Reporter Confirmations` cites its exact `SKILL.md` path, or `<PROJECT_ROOT>/.okstra/project.json` lists it under `reviewRulePacks` (the project's standing standard, applying whether or not the brief mentions it). The two sources are a union. Read only those files and the `references/*.md` files they directly name. Do not search parent directories or host skill catalogs. Apply the rules as an acceptance overlay (record `project-review-rules: <paths read>`, `project-review-rules: declared <path> unreadable`, or `project-review-rules: none declared or cited`). This is a static review pass, not a PR-comment workflow — do NOT dispatch reviewer subagents. Because this phase verifies the **whole-task merged diff**, it is the gate that catches **cross-stage findings a per-stage `implementation` verifier structurally cannot see** (each implementation run reviews only its own stage diff): most importantly two cross-stage conditions: (a) the same helper stack / transform / domain rule duplicated across stages or services — byte-identical duplication is always an Acceptance Blocker, and semantically-equivalent transforms across services are blockers unless the approved plan explicitly justified keeping them separate; (b) an API newly orphaned because its only caller was removed in a different stage. A confirmed cross-stage duplication of this kind is an Acceptance Blocker (`major`+) that cites every `path:line` location and names the shared-module location to converge on. (Single-stage scope sees only one stage, so it cannot raise cross-stage findings — note that limitation rather than implying coverage.)
   - Residual-tracked — note as Residual Risk unless severe enough to block:
@@ -25,6 +26,7 @@
     - **whole-task mutates only when it has to.** When one stage branch already contains every other done stage's commit — the usual shape of a linear plan, since each stage branches from its predecessor's done commit — that branch IS the whole task, and verification runs in that stage's worktree with no merge at all (`stage_targets.containing_stage`). Only when the stage graph has several tips does entry auto-merge (with `--no-ff`) the done stages into the task branch to create an integration commit; that case is the mutating one. The stage worktrees are NOT removed on entry: they are reclaimed after the verdict, by the Phase 7 `teardown-stages` step, and only when the verdict clears the work for release (`accepted`, or `conditional-accept` with no condition blocking release). A `blocked` verdict therefore leaves every stage worktree in place, so the rework it routes to can start immediately. The stage branches are kept as the reviewable stack (the target of `okstra handoff local-checkout --stage <N>`). If a merge conflict occurs it reports the conflicting files and aborts (the user resolves them manually and retries). A stage worktree with uncommitted changes remaining is preserved. Therefore the "fully-merged, clean target" the entry gate above refers to is the state after this auto-integration step completes, and whole-task final-verification must be treated as a mutating phase that creates the integration commit.
   - **single-stage scope** (`--stage N`): prep verified stage N is `status:done` and its isolated stage worktree exists and is clean. Other stages' state is irrelevant. A single-stage run is a partial verification of one stage, and that is exactly the unit release-handoff ships: an `accepted` verdict here makes the stage PR-eligible, so `release-handoff` is the routing target. It says nothing about any other stage.
   - the lead still captures `git status --short` from the injected worktree to confirm the analysis ran against the delivered work-tree state; an unexpected divergence (dirty tree outside `.okstra/`, missing worktree) is a `tool-failure`, not a silent proceed.
+- **Stage worktree lifecycle:** implementation finalization may already have removed a completed stage's directory. Preparation restores the preserved stage branch for single-stage verification, or the containing tip branch for a linear whole-task target. After successful report validation, a release-ready single-stage verdict reclaims that stage's clean worktree; a whole-task verdict reclaims completed stages without any cleanup-time merge. Blocked, active, dirty, nested, or changed stages remain available for rework. The branch and registry base survive cleanup. After finalization use the main project root or absolute artifact paths because the verification cwd may have been removed. Enforcement: `report_finalize._teardown_stage_worktrees`, `stage_targets.teardown_completed_stage_worktrees`, and `tests/worktree/test_stage_rebase.py`.
 - Worker verification procedure:
   - **Target confirmation:** analyse the injected target and nothing else. Read `verification-target.md` for the stage/report mapping and the complete diff stat. Prepare fixed that target and `phases/final_verification/validation.py` `validate_verification_target_match` (called by `validators/validate-run.py`) re-checks the report against its digest, so the procedure to follow here is simply: if the worktree you can see does not match the injected target, record a `tool-failure` — never reselect a target.
   - **Evidence:** attach file:line, exact command + exit code, log excerpt, or MCP SELECT evidence to every finding. Mark a requirement as covered only when the cited artifact demonstrates it.

package/runtime/python/okstra_ctl/phases/final_verification/spec.md

@@ -184,6 +184,8 @@ flowchart TD
 
 The stage merge of whole-task mode is a runtime-owned integration step that prepare performs; the matching teardown is a runtime-owned step too, but it runs after the verdict (Phase 7 `teardown-stages`) and only when the verdict clears the work for release. After that, lead verification is read-only. Source edit, follow-up fix, and scope expansion are all forbidden. When a defect is found, it is not fixed within the current run. The lead chooses the next phase from `prompts/lead/phase-routing.md` using the blocker facts this phase recorded.
 
+Implementation finalization may already have reclaimed completed stage worktrees. Target acquisition restores a missing single-stage worktree, or the containing tip-stage worktree for a linear whole-task target, from its preserved branch. Restoration does not merge into the task branch. After a release-ready single-stage verdict, `report-finalize` also reclaims that stage's worktree using the captured verification head; a blocked verdict keeps the restored worktree for rework. Cleanup never merges stages: `stage_targets.teardown_completed_stage_worktrees` only reclaims completed, inactive worktrees whose tips match the selected completion commits. Tests: `tests/worktree/test_stage_rebase.py`.
+
 ### 8. Verified code
 
 - `scripts/okstra_ctl/phases/final_verification/profile.md`

package/runtime/python/okstra_ctl/phases/final_verification/target.py

@@ -1,6 +1,6 @@
 """final-verification 이 검증할 대상을 고른다.
 
-단일 stage 검증은 그 stage 의 worktree 를 읽기만 한다. 전체 작업 검증은 완료된
+검증 대상 고정 전에 이동한 의존 기준을 재배치한다. 전체 작업 검증은 완료된
 stage 전부를 담은 stage 브랜치가 있으면 그것을 쓰고, 없으면 task 브랜치에 통합한
 결과를 쓴다. 원장·registry·Git·통합은 공통 모듈이 제공하고, 여기서는 어느 것을
 언제 부를지만 정한다. 전체 과정은 task 키 잠금 하나 안에서 돈다.
@@ -115,6 +115,14 @@ def _read_final_verification_done_rows(
         ),
         plan_run_root,
     )
+    from okstra_ctl.stage_rebase import synchronize_stage_stack
+    from okstra_ctl.stage_targets import StageWorktreeIdentity
+
+    synchronize_stage_stack(
+        project_root=request.project_root, plan_run_root=plan_run_root,
+        stage_map=list(request.stage_map),
+        identity=StageWorktreeIdentity(project_id, task_group, task_id, request.work_category),
+    )
     return read_stage_consumer_state(plan_run_root).done_rows
 
 
@@ -141,6 +149,10 @@ def _acquire_single_stage_target(
     assert stage is not None
     row = worktree_registry.get_stage_row(*registry_coordinates, stage)
     worktree_path = (row or {}).get("worktree_path", "")
+    if worktree_path and not Path(worktree_path).exists():
+        from okstra_ctl.worktree.provision import restore_stage_worktree
+
+        restore_stage_worktree(request.project_root, worktree_path, row["branch"])
     head = ""
     if worktree_path and Path(worktree_path).is_dir():
         head_result = _git(worktree_path, "rev-parse", "HEAD")
@@ -183,6 +195,10 @@ def _acquire_tip_stage_target(
         return None
     row = worktree_registry.get_stage_row(*registry_coordinates, tip) or {}
     worktree_path = row.get("worktree_path", "")
+    if worktree_path and not Path(worktree_path).exists():
+        from okstra_ctl.worktree.provision import restore_stage_worktree
+
+        restore_stage_worktree(request.project_root, worktree_path, row["branch"])
     if not worktree_path or not Path(worktree_path).is_dir():
         return None
     head_result = _git(worktree_path, "rev-parse", "HEAD")

package/runtime/python/okstra_ctl/phases/implementation/entry.py

@@ -95,6 +95,18 @@ def claim_implementation_stage_run(
     plan_run_root = Path(inp.approved_plan_path).resolve().parents[1]
     backfill_done_from_carry(plan_run_root)
     auto_reconcile_best_effort(inp, plan_run_root)
+    from okstra_ctl.stage_rebase import synchronize_stage_stack
+
+    try:
+        synchronize_stage_stack(
+            project_root=Path(inp.project_root), plan_run_root=plan_run_root,
+            stage_map=ctx_stage_map,
+            identity=stage_targets.StageWorktreeIdentity(
+                inp.project_id, task_group_segment, task_id_segment, inp.work_category,
+            ),
+        )
+    except RuntimeError as exc:
+        raise ImplementationStageError(str(exc)) from exc
     reserved_stages = _reg.list_active_stage_numbers(
         inp.project_id,
         inp.task_group,

package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md

@@ -94,6 +94,7 @@ A finding that needs no code change (convergence settled it as a verifier misrea
 - **A run that ends with no verifier result still closes.** When the stage ends before any verifier returned a verdict — the executor stopped without a change and the user chose not to verify, or every dispatched verifier ended without a result — append the `failed` row as above, record each roster verifier `not-run` with its reason (`okstra worker-state transition --team-state <path> --worker <worker-id> --status not-run --reason <text>`; a worker the dispatch skipped already carries one), and write the convergence state with `okstra convergence skip --run-manifest <path> --reason <text>` before dispatching the report writer. Without that state the report-writer packet refuses with `convergence … required source is missing`. The command refuses while any analyser, verifier, or critic attempt returned a result or is still running; such a run converges normally. In the report, write each verifier's `verifierResults[]` row as `verdict: not-run`, and state the reason under `Stage sidecar evidence` as `withheld`.
 - On a non-`FAIL` verdict, for this run's single stage: write its JSON verbatim to `runs/<impl-task-key>/carry/stage-<N>.json` — after a passing lead minor fix, with the head, files, and note that §"Lead minor fix" adds. Refuse to overwrite an existing file (one stage = one sidecar; a fix run re-entering after a `failed` row writes the first one, because a withheld stage never wrote it). A stage reopened after a `done` row (see "Reopening a settled stage" below) still has the sidecar of the run that first settled it, naming a head the stage has since moved past: move it unchanged to `runs/<impl-task-key>/carry/superseded/stage-<N>-from-<that run's task-type>-<seq>.json` before writing the new one, and name both paths in `Stage sidecar evidence`. Do not rename it inside `carry/`: the readers glob `carry/stage-*.json` (`okstra_ctl.stage_map`, `okstra_ctl.consumers.backfill_done_from_carry`), so a renamed file there is read again as a live sidecar. A reopened stage whose run ends `FAIL` writes nothing and leaves the old file where it is.
 - On a non-`FAIL` verdict, for this run's single stage: append a `status:"done"` row to `runs/<plan-task-key>/consumers.jsonl` with `completed_at`, `carry_path`, `report_path` (this run's final-report path relative to the run root), and the SHA of HEAD. Append it with `okstra_ctl.consumers.append_consumer` (NOT a raw filesystem write) — that call honours the consumers lock AND releases this stage's worktree-registry occupancy, so later runs stop seeing a finished stage as a concurrent run. `report_path` lets `final-verification` cite each stage's originating report when assembling its Source Implementation Report list.
+- **Automatic stage worktree cleanup:** after the report passes finalization, `report-finalize` reclaims this completed stage's clean worktree. It compares the report's final commit with the completion ledger and branch tip, preserves active or unfinished stages and dirty or nested worktrees, and keeps the branch and registry base for dependency rebases and later re-entry. Never remove the directory by hand before finalization. A later implementation or final-verification entry restores it from the preserved branch. After finalization, use the main project root or absolute artifact paths: this run's stage cwd may no longer exist. Enforcement: `report_finalize._teardown_stage_worktrees`, `stage_targets.teardown_completed_stage_worktrees`, and the cleanup/restoration tests in `tests/worktree/test_stage_rebase.py`.
 - **Reopening a settled stage.** Appending a `status:"failed"` row after a `done` one withdraws that stage: `--stage N` accepts it again, its dependents stop resolving a base from the withdrawn head, and whole-task final-verification blocks until it is settled again. Write it with `okstra stage-reopen <task-key> --stage <N> --reason "<why>" [--evidence <report>]`, which records the reason and the report that found the defect, and re-run the stage rather than repairing the tree outside okstra — a stage reverted outside the ledger leaves the recorded `head_commit` and the carry sidecar naming a tree that no longer exists, and the next stage branches from it.
 - The verifier round, Phase 5.5 convergence, and this Phase 6 report run **once per run** over this stage's diff — NOT per step.
 - Record this stage's new contents in the final report's `Stage sidecar evidence` deliverable section: the sidecar by path with its one-line summary, and the new consumers row quoted by itself.

package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-executor.md

@@ -9,6 +9,7 @@ until Phase 5 ends, then drop from active context for Phase 6/7.
 
 ## Executor role binding (carried over from the thin core)
 
+- **Moving dependency bases:** never run `git merge <predecessor>` or merge an old origin branch into this stage to update its base. Runtime preparation rebases downstream stages in dependency order through `okstra_ctl.stage_rebase`; a predecessor moving during execution requires stopping and re-entering preparation after the current stage claim is released. Do not rewrite another active stage or repair registry/ledger SHAs by hand. Enforcement of preparation ordering and conflict recovery is covered by `tests/worktree/test_stage_rebase.py`.
 - The `Executor` (bound in `implementation.md` thin core) is the **only worker permitted to mutate project files**. All other workers run read-only. A `runner=native-session` executor uses the selected host adapter's native edit and command primitives. A `runner=cli-wrapper` executor mutates files inside its provider CLI's auto-edit mode. The safety rules in this sidecar apply identically to both runners.
 - When the thin core's Task worktree block resolves status to `created` or `reused`, the Executor MUST run every Edit / Write / build / test / commit command with the worktree path as cwd. Treat it as `project_root` for the duration of this run. Do NOT mutate the caller's original checkout. Do NOT `cd` out of the worktree to reach files. If a file outside the worktree is genuinely needed, treat it as a planning gap: record it in `Out-of-plan edits` and continue.
   - **How to set the working directory**: every command and native edit MUST target `{{EXECUTOR_WORKTREE_PATH}}`, never the lead session's original project directory. The selected runtime adapter owns the exact native command syntax. Provider CLI wrappers inject the worktree at the CLI layer. For tools that accept an explicit working-directory flag (`git -C <path>`, `cargo --manifest-path`, `pytest --rootdir`), prefer that form.