okstra 0.199.1 → 0.199.3

package/runtime/python/okstra_ctl/implementation_direction.py

@@ -31,6 +31,7 @@ from .json_boundary import (
     write_owned_object_atomic,
 )
 from .report_views import normalize_direction_selection_identity
+from .qa_commands import find_denied_tokens
 from .scope_provenance import brief_end_state_id_sequence
 from .user_response import UserResponseError, parse_direction_selection
 
@@ -814,14 +815,31 @@ _MANUAL_VALIDATION_MARKERS = (
 )
 
 
-def _stage_validation_executability_errors(
+def stage_validation_executability_errors(
     planning: Mapping[str, Any],
 ) -> list[str]:
     failures: list[str] = []
     for row in planning.get("validationChecklist") or ():
-        if not isinstance(row, Mapping) or not row.get("stageRefs"):
+        if not isinstance(row, Mapping):
             continue
-        lowered = str(row.get("commandOrObservation") or "").lower()
+        command = str(row.get("commandOrObservation") or "")
+        denied = find_denied_tokens(command)
+        if re.search(r"(?<![\w/])\.?/?\.okstra/tasks/", command):
+            denied.append(
+                "project-relative QA path (use the absolute task artifact path; keep worktree cwd)"
+            )
+        if re.search(r">\s*/(?:tmp|private/tmp|var/tmp)/", command):
+            denied.append(
+                "output outside the worktree (use a worktree-local output path)"
+            )
+        if denied:
+            failures.append(
+                f"validationChecklist {row.get('id')} conflicts with verifier command rules: "
+                f"{'; '.join(denied)}; correct and approve the plan before implementation"
+            )
+        if not row.get("stageRefs"):
+            continue
+        lowered = command.lower()
         matched = [
             marker for marker in _MANUAL_VALIDATION_MARKERS if marker in lowered
         ]
@@ -947,6 +965,6 @@ def validate_selected_direction_plan(
             planning, brief_end_state_id_sequence(Path(brief_path))
         )
     )
-    failures.extend(_stage_validation_executability_errors(planning))
+    failures.extend(stage_validation_executability_errors(planning))
     failures.extend(_micro_stage_fold_errors(planning))
     return failures

package/runtime/python/okstra_ctl/plan_items.py

@@ -643,7 +643,7 @@ CRITIC_WORKER_ID = "critic-worker"
 
 
 def is_critic_worker(worker: str) -> bool:
-    """본문 동수를 가르는 critic 표인지."""
+    """본문 판정을 교정하는 비판 검토자 표인지."""
     name = str(worker or "").strip().lower()
     return name == CRITIC_WORKER_ID or name.endswith("-critic-worker")
 
@@ -738,7 +738,10 @@ CRITIC_TIE_PREAMBLE = (
     "You are the critic tie-break. Only the items below are in dispute. "
     "Each item already has one AGREE and one DISAGREE from the two plan-body "
     "verifiers. Decide the item: AGREE or DISAGREE(<kind>). Your verdict "
-    "settles the split. Do not re-open items that are not listed.\n"
+    "settles the split, including a prior DISAGREE(a) or DISAGREE(f). "
+    "Explain whether the earlier dissent is supported or mistaken; a corrected "
+    "dissent remains in the audit history without overriding your decision. "
+    "Do not re-open items that are not listed.\n"
 )
 
 # 라운드 2+ 는 직전 라운드의 반대 의견을 해결하려고 존재한다. 그 의견을 프롬프트가

package/runtime/python/okstra_ctl/plan_items_cli.py

@@ -34,6 +34,7 @@ from .plan_items import (
     content_hash,
     correction_prompt_text,
     critic_is_rostered,
+    is_critic_worker,
     critic_tie_prompt_text,
     dispatch_item_ids,
     extract_plan_items,
@@ -53,6 +54,8 @@ from .stage_ledger import build_stage_ledger
 from .claim_reproduction import NOT_RUNNABLE, reproduce
 from .final_report_schema import load_schema_version
 from .report_narrative import parse_narrative
+from .report_assembly import validate_plan_draft
+from .error_log_write import record_runtime_failure
 from .user_response import parse_user_response_entries
 from .verdict_blocks import (
     PLAN_ITEM_VERDICTS,
@@ -266,7 +269,8 @@ def _parser() -> argparse.ArgumentParser:
     )
     apply_verdicts.add_argument(
         "--append", action="store_true",
-        help="add these votes to the existing rows (the critic's tie vote); "
+        help="add critic corrections while preserving analyser votes; a later "
+             "critic verdict updates that critic's current row after its earlier round is complete; "
              "without it every recorded verdict row is replaced, so a round "
              "that was never closed with complete-round is refused first",
     )
@@ -285,6 +289,11 @@ def _parser() -> argparse.ArgumentParser:
     complete.add_argument("--state", type=Path, required=True)
     complete.add_argument("--run-manifest", type=Path, required=True)
     complete.add_argument("--round", type=int, required=True, dest="round_number")
+    complete.add_argument(
+        "--items", type=Path,
+        help="restore this round's dispatched queue from its prepared items artifact; "
+             "earlier verdicts outside that queue remain unchanged",
+    )
     complete.add_argument("--self-fix-note", action="append", default=[], metavar="<item-id>=<markdown-file>")
     complete.add_argument(
         "--self-fix-group", action="append", default=[],
@@ -405,6 +414,15 @@ def _sync_task_manifest_gating(run_manifest: Path, gating: bool) -> None:
 def _prepare(args: argparse.Namespace) -> dict[str, Any]:
     output = _prepared_items_path(args.run_manifest)
     source = _plan_source(args)
+    authority = validated_run_authority(args.run_manifest)
+    if authority.payload.get("reportContractVersion") == "3.0":
+        failures = validate_plan_draft(source, authority.project_root, authority.payload)
+        if failures:
+            raise PlanItemContractError(
+                "owner=report-writer fieldPath=implementationPlanning: "
+                + "; ".join(failures)
+                + "; correct the narrative in this run, then retry plan-items prepare"
+            )
     envelope = _envelope(source)
     envelope["dispatchQueue"] = _queue_for(
         envelope["items"],
@@ -469,6 +487,18 @@ def _label(key: str) -> str:
     return " ".join(part.capitalize() for part in key.replace("Id", " ID").split())
 
 
+def _render_literal(label: str, value: str, indent: str = "") -> list[str]:
+    """명령·코드의 줄바꿈을 보존하고 본문보다 긴 울타리로 감싼다."""
+    fence = "`" * max(
+        3, 1 + max((len(part) for part in re.findall(r"`+", value)), default=0)
+    )
+    body = "".join(indent + "  " + row for row in value.splitlines(keepends=True))
+    ending = "" if value.endswith("\n") else "\n"
+    return [
+        f"{indent}- {label}:\n\n{indent}  {fence}text\n{body}{ending}{indent}  {fence}\n"
+    ]
+
+
 def _render_object_list(key: str, value: object) -> list[str]:
     if not isinstance(value, list):
         raise PlanItemContractError(f"plan item {key} must be an array")
@@ -491,6 +521,8 @@ def _render_object_list(key: str, value: object) -> list[str]:
                     raise PlanItemContractError(
                         f"plan item {field_path} must be scalar"
                     )
+                elif field == "details" and isinstance(field_value, str):
+                    rows.extend(_render_literal(f"`{field_path}`", field_value, "    "))
                 else:
                     rows.append(
                         f"    - `{field_path}`: `{scalar(field_value)}`\n"
@@ -542,6 +574,8 @@ def _render_scalar_or_list(key: str, value: object, indent: str = "") -> list[st
         return rows
     if isinstance(value, Mapping):
         raise PlanItemContractError(f"plan item {key} must be scalar")
+    if key in {"command", "commandOrObservation"} and isinstance(value, str):
+        return _render_literal(_label(key), value, indent)
     return [indent + line(_label(key), value)]
 
 
@@ -1389,12 +1423,7 @@ def _apply_verdicts(args: argparse.Namespace) -> dict[str, Any]:
     discard_open_rounds = bool(getattr(args, "discard_open_rounds", False))
     if discard_open_rounds and args.state is not None and args.result:
         _restore_queue_from_results(verification, args.result, recorded)
-    queue = verification.get("dispatchQueue") if isinstance(verification, Mapping) else None
-    assigned = (
-        {item_id for item_id in queue if isinstance(item_id, str)}
-        if isinstance(queue, list) else known
-    )
-    assigned = _narrow_assignment(args, assigned)
+    assigned = _narrow_dispatch_queue(args, verification, known)
     rows = _incoming_verdict_rows(args, assigned)
     missing = sorted(item_id for item_id in rows if item_id not in known)
     if missing:
@@ -1405,21 +1434,14 @@ def _apply_verdicts(args: argparse.Namespace) -> dict[str, Any]:
         )
     if args.round_number < 1:
         raise PlanItemContractError("--round must be 1 or greater")
-    if (
-        isinstance(verification, Mapping)
-        and verification.get("gating") is False
-        and args.round_number > 1
-    ):
-        # `complete-round` 가 같은 조건으로 거절하지만 그때는 이미 라운드 2 판정이
-        # 상태에 쓰인 뒤다 — 판정은 있는데 `roundHistory` 에 그 라운드가 없는
-        # 불일치가 남고, 상태 파일은 수렴 엔진 소유라 복구 경로가 없었다
-        # (2026-09-05 실측, dev-10626 planning). 쓰기 전에 같은 문장으로 거절한다.
-        raise PlanItemContractError(
-            "advisory plan-body gating allows one verification round"
-        )
     project_root = _probe_project_root(getattr(args, "run_manifest", None))
     append = bool(getattr(args, "append", False))
-    if not append:
+    replaces_critic = append and any(
+        is_critic_worker(row.get("worker", ""))
+        and any(v.get("worker") == row.get("worker") for v in rows.get(item.get("id"), []))
+        for item in recorded for row in item.get("verdicts", [])
+    )
+    if not append or replaces_critic:
         _reject_uncompleted_round_loss(
             recorded, rows, data.get("roundHistory"), args.round_number, target,
             discard_open_rounds=discard_open_rounds,
@@ -1428,6 +1450,7 @@ def _apply_verdicts(args: argparse.Namespace) -> dict[str, Any]:
     for item in recorded:
         if isinstance(item, Mapping) and item.get("id") in rows:
             writer(item, rows[item["id"]], args.round_number, project_root)
+    _validate_advisory_round(verification, args.round_number)
     write_json_atomic(target, data)
     return {"ok": True, "operation": "apply-verdicts", "path": str(target)}
 
@@ -1462,23 +1485,26 @@ def _append_item_verdicts(
     round_number: int,
     project_root: Path | None,
 ) -> None:
-    """동수 항목의 critic 표. 이미 투표한 워커는 거부한다."""
+    """분석자 표를 보존하고, 비판 검토자의 후속 판정을 현재 표로 갱신한다."""
     stamped = _stamped_verdicts(incoming, round_number, project_root)
     existing = item.get("verdicts")
     current = existing if isinstance(existing, list) else []
-    seen = {
-        row.get("worker") for row in current if isinstance(row, Mapping)
+    seen = {row.get("worker"): row.get("round", 1) for row in current if isinstance(row, Mapping)}
+    refreshed = {
+        row.get("worker") for row in stamped
+        if is_critic_worker(row.get("worker", ""))
+        and row.get("worker") in seen and round_number > seen[row["worker"]]
     }
-    clash = [row.get("worker") for row in stamped if row.get("worker") in seen]
+    clash = [row.get("worker") for row in stamped if row.get("worker") in seen and row.get("worker") not in refreshed]
     if clash:
         raise PlanItemContractError(
             f"plan item {item.get('id')} already has a vote from {clash} — "
             "the extra vote must come from a worker who has not voted on it. "
-            "--append is the critic's tie vote; a worker re-voting in a later "
+            "--append accepts critic corrections; an analyser re-voting in a later "
             "round is recorded without --append, after the earlier round is "
             "closed with complete-round"
         )
-    item["verdicts"] = [*current, *stamped]
+    item["verdicts"] = [row for row in current if row.get("worker") not in refreshed] + stamped
     _remember_verified_hash(item)
 
 
@@ -1586,7 +1612,7 @@ def _reject_uncompleted_round_loss(
     )
     raise PlanItemContractError(
         f"round {round_number} would replace verdicts of a round that was never "
-        f"completed ({detail}) — apply-verdicts replaces every recorded row, and "
+        f"completed ({detail}) — replacing these verdicts would lose their history; "
         "only complete-round keeps a round's votes in planItems[].rounds. Close "
         f"the earlier round first: run {commands}, then re-run this command. "
         "If those rows are themselves being re-applied from their result files "
@@ -1699,7 +1725,11 @@ def _round_inputs(args: argparse.Namespace) -> tuple[dict[str, Any], list[dict[s
     audit, history = data.get("planItems"), data.get("roundHistory")
     if not isinstance(audit, list) or not isinstance(history, list):
         raise PlanItemContractError("state planItems and roundHistory must be arrays")
-    return data, _state_plan_body_items(data, args.state), audit, history
+    current = _state_plan_body_items(data, args.state)
+    _narrow_dispatch_queue(
+        args, data["planBodyVerification"], {item.get("id") for item in current},
+    )
+    return data, current, audit, history
 
 
 def _round_snapshots(current: list[dict[str, Any]], verification: Mapping[str, Any], round_number: int) -> tuple[dict[str, dict[str, Any]], dict[str, Any]]:
@@ -1782,16 +1812,27 @@ def _reject_round_gap(history: list[Any], round_number: int) -> None:
         )
 
 
+def _validate_advisory_round(verification: Mapping[str, Any], round_number: int) -> None:
+    """분석자 검증 횟수 제한은 비판 검토자의 교정에 적용하지 않는다."""
+    if verification.get("gating") is not False or round_number <= 1:
+        return
+    if any(
+        row.get("round") == round_number and not is_critic_worker(row.get("worker", ""))
+        for item in verification.get("planItems", []) for row in item.get("verdicts", [])
+    ):
+        raise PlanItemContractError(
+            "advisory plan-body gating allows one verification round for analysers; "
+            "critic corrections do not consume that limit"
+        )
+
+
 def _complete_round(args: argparse.Namespace) -> dict[str, Any]:
     if args.round_number < 1:
         raise PlanItemContractError("--round must be 1 or greater")
     data, current, audit, history = _round_inputs(args)
     verification = data["planBodyVerification"]
+    _validate_advisory_round(verification, args.round_number)
     if verification.get("gating") is False:
-        if args.round_number > 1:
-            raise PlanItemContractError(
-                "advisory plan-body gating allows one verification round"
-            )
         if args.self_fix_group or args.self_fix_note or args.self_fix_stop_reason:
             raise PlanItemContractError(
                 "advisory plan-body gating forbids the self-fix loop"
@@ -1936,8 +1977,8 @@ def _correction_prompt(args: argparse.Namespace) -> str:
     return correction_prompt_text(_prompt(args))
 
 
-def _narrow_assignment(
-    args: argparse.Namespace, assigned: set[object],
+def _narrow_dispatch_queue(
+    args: argparse.Namespace, verification: dict[str, Any], known: set[object],
 ) -> set[object]:
     """이 라운드가 실제로 배정한 항목들.
 
@@ -1946,10 +1987,15 @@ def _narrow_assignment(
     37항목을 미응답으로 거절했다 — 문서가 "model-facing" 이라고 적은 형식이
     tie 라운드에서는 쓸 수 없고, 우회로가 헬프 스스로 historical 이라 적은
     `--verdicts` 뿐이었다(실측 2026-09-10, fontsninja-v3-site dev-10628-3).
-    `--items` 로 그 라운드의 artifact 를 주면 그 `dispatchQueue` 가 배정이
-    된다. 미응답 검사 자체는 그대로다 — 좁힌 배정 안에서 여전히 전건을
-    요구하므로, 워커가 자기 몫을 조용히 빠뜨리는 것은 계속 잡힌다.
+    배정 범위는 판정 저장과 완료 기록이 함께 써야 한다. 지역 변수만 좁히면
+    저장은 성공해도 완료가 과거 큐 전체에서 새 라운드의 표를 요구한다.
+    상태의 큐만 좁히고 기존 표와 라운드 이력은 보존한다.
     """
+    queue = verification.get("dispatchQueue")
+    assigned = (
+        {item_id for item_id in queue if isinstance(item_id, str)}
+        if isinstance(queue, list) else known
+    )
     items_path = getattr(args, "items", None)
     if items_path is None:
         return assigned
@@ -1965,6 +2011,10 @@ def _narrow_assignment(
             f"queue does not contain — pass the artifact this round dispatched, "
             f"not another round's"
         )
+    verification["dispatchQueue"] = [
+        item_id for item_id in (queue if isinstance(queue, list) else sorted(assigned))
+        if item_id in narrowed
+    ]
     return narrowed
 
 
@@ -2011,6 +2061,13 @@ def main(argv: list[str] | None = None) -> int:
         result = _HANDLERS[args.command](args)
     except (PlanItemContractError, VerdictBlockError, OSError, ValueError) as exc:
         print(f"plan-items: {exc}", file=sys.stderr)
+        manifest = getattr(args, "run_manifest", None)
+        if manifest:
+            logged = record_runtime_failure(
+                Path(manifest), command=f"plan-items {args.command}", exit_code=2, detail=str(exc)
+            )
+            if not logged["ok"]:
+                print(f"error-log: {logged['reason']}", file=sys.stderr)
         return 2
     if isinstance(result, str):
         print(result, end="")

package/runtime/python/okstra_ctl/qa_commands.py

@@ -72,6 +72,31 @@ def _has_insta_update_set(cmd: str) -> bool:
     return match.group(1).lower() != "no"
 
 
+def find_unfrozen_installs(cmd: str) -> list[str]:
+    """계획과 실행 기록에서 같은 잠금파일 고정 조건을 판정한다."""
+    found: list[str] = []
+    if _has_npm_install_without_ci(cmd):
+        found.append("npm install (use 'npm ci' instead)")
+    for match in re.finditer(r"\b(pnpm|yarn|bun)\s+(?:install|i)\b([^;&|\n]*)", cmd):
+        flags = match.group(2).split()
+        frozen = "--frozen-lockfile" in flags or (
+            match.group(1) == "yarn" and "--immutable" in flags
+        )
+        disabled = any(
+            flag
+            in {
+                "--no-frozen-lockfile",
+                "--frozen-lockfile=false",
+                "--no-immutable",
+                "--immutable=false",
+            }
+            for flag in flags
+        )
+        if not frozen or disabled:
+            found.append(f"{match.group(1)} install (requires a frozen lockfile)")
+    return found
+
+
 def find_denied_tokens(cmd: str) -> list[str]:
     """`cmd` 안에 포함된 모든 denied 토큰 목록을 반환. 비어 있으면 안전."""
     if not isinstance(cmd, str):
@@ -84,8 +109,7 @@ def find_denied_tokens(cmd: str) -> list[str]:
     for sub in _DENIED_SUBSTRINGS:
         if sub in cmd:
             found.append(sub)
-    if _has_npm_install_without_ci(cmd):
-        found.append("npm install (use 'npm ci' instead)")
+    found.extend(find_unfrozen_installs(cmd))
     if _has_insta_update_set(cmd):
         found.append("INSTA_UPDATE=<not-no>")
     return found

package/runtime/python/okstra_ctl/report_assembly.py

@@ -1,6 +1,7 @@
 """역할별 리포트 입력을 검증해 계약 3.0 정본을 한 번 게시한다."""
 from __future__ import annotations
 
+import copy
 import json
 import os
 import tempfile
@@ -573,7 +574,7 @@ def _apply_selected_direction_snapshot(
             )
 
 
-def _selected_direction_publication_errors(
+def selected_direction_plan_errors(
     data: Mapping[str, Any], project_root: Path, manifest: Mapping[str, Any]
 ) -> list[str]:
     """게시 직전에 구현 진입 검증을 그대로 돌린다.
@@ -593,6 +594,16 @@ def _selected_direction_publication_errors(
     return validate_selected_direction_plan(data, brief_path, snapshot_path)
 
 
+def validate_plan_draft(
+    data: Mapping[str, Any], project_root: Path, manifest: Mapping[str, Any]
+) -> list[str]:
+    """작성자 입력을 게시하지 않고 같은 기계 투영과 의미 검사로 검증한다."""
+    draft = copy.deepcopy(dict(data))
+    _apply_selected_direction_snapshot(draft, project_root, manifest)
+    _attach_metadata(draft, manifest)
+    return selected_direction_plan_errors(draft, project_root, manifest)
+
+
 def _identity(manifest: Mapping[str, Any]) -> tuple[str, str, str]:
     task_key = str(manifest.get("taskKey") or "")
     parts = task_key.split(":")
@@ -872,7 +883,7 @@ def assemble_report(
         raise ReportAssemblyError(tuple(input_issues))
     data = _compose(project_root, manifest_path, manifest, inputs, schema)
     errors = validate(data, schema)
-    direction_errors = _selected_direction_publication_errors(
+    direction_errors = selected_direction_plan_errors(
         data, project_root, manifest
     )
     value = manifest.get("expectedReportRecordPath")

package/runtime/python/okstra_ctl/report_finalize.py

@@ -44,7 +44,7 @@ import json
 from datetime import date, datetime, timezone
 import subprocess
 import sys
-from dataclasses import dataclass
+from dataclasses import asdict, dataclass
 from pathlib import Path
 from typing import Any, Callable, Mapping, Sequence
 
@@ -73,6 +73,7 @@ from .stage_targets import (
     integrate_and_teardown_whole_task,
 )
 from .session import observe_lead_session
+from .error_log_write import record_runtime_failure
 
 # 포인터 값 타입만 쓴다. `okstra_project.phase_pointer` 는 okstra 안의
 # 어떤 것도 import 하지 않는 leaf 라 순환이 없다 — 그 모듈 도크스트링.
@@ -93,6 +94,7 @@ STEP_SPAWN_FOLLOWUPS = "spawn-followups"
 STEP_VALIDATE_RUN = "validate-run"
 STEP_RECORD_GROUP_MEMORY = "record-group-memory"
 STEP_TEARDOWN_STAGES = "teardown-stages"
+STEP_PREFLIGHT = "preflight"
 
 STEP_ORDER = (
     STEP_PROJECT_ACTIVITY,
@@ -112,6 +114,7 @@ STEP_ORDER = (
 V3_STEP_ORDER = (
     STEP_TOKEN_USAGE,
     STEP_PROJECT_ACTIVITY,
+    STEP_PREFLIGHT,
     # Before the render that overlays its sidecar.
     STEP_TRANSLATE,
     STEP_RENDER_VIEWS,
@@ -401,6 +404,11 @@ def build_commands(ctx: FinalizeContext) -> list[tuple[str, list[str]]]:
     if ctx.report_contract_version != "3.0":
         return commands
     by_name = dict(commands)
+    by_name[STEP_PREFLIGHT] = [
+        *_validate_run_command(ctx, ctx.data_path),
+        "--section",
+        "preflight",
+    ]
     usage = by_name[STEP_TOKEN_USAGE]
     marker = usage.index("--substitute-data")
     by_name[STEP_TOKEN_USAGE] = usage[:marker]
@@ -553,13 +561,17 @@ def step_payload(
     command: Sequence[str],
     result: subprocess.CompletedProcess[str],
 ) -> dict[str, Any]:
-    return {
+    payload = {
         "name": name,
         "command": list(command),
         "exitCode": result.returncode,
         "stdoutTail": tail(result.stdout),
         "stderrTail": tail(result.stderr),
     }
+    if name == STEP_PROJECT_ACTIVITY and result.returncode != 0 and result.stdout:
+        # 소유자 오류는 요약 문자열 길이에 잘리지 않은 전체 목록으로 전달한다.
+        payload["issues"] = json.loads(result.stdout).get("issues", [])
+    return payload
 
 
 def run_finalize(
@@ -585,6 +597,8 @@ def run_finalize(
 
     if only:
         selected = set(only)
+        if ctx.report_contract_version == "3.0" and STEP_TRANSLATE in selected:
+            selected.add(STEP_PREFLIGHT)
         contract_order = (
             V3_STEP_ORDER if ctx.report_contract_version == "3.0" else STEP_ORDER
         )
@@ -601,23 +615,7 @@ def run_finalize(
             ctx, commands, selected, all_commands
         )
 
-    first_failure = ""
-    validated = False
-    for name, command in commands:
-        # 실패한 시퀀스가 worktree 를 거두면 재작업 대상이 사라지고, 검증 안 된
-        # 레코드를 기억하면 형제 task 가 그것을 결론으로 읽는다.
-        if name in _SKIPPED_AFTER_FAILURE and first_failure:
-            continue
-        if before_step is not None:
-            before_step(name)
-        result = _run_finalize_step(ctx, name, command)
-        steps.append(step_payload(name, command, result))
-        if result.returncode != 0 and not first_failure:
-            first_failure = f"{name} failed with exit code {result.returncode}"
-        if name == STEP_VALIDATE_RUN and result.returncode == 0:
-            validated = True
-    if validated:
-        _record_run_end(ctx.team_state_path)
+    steps, first_failure = _execute_finalize_steps(ctx, commands, before_step)
     pointer, pointer_error = _recorded_next_phase(ctx)
     payload: dict[str, Any] = {
         "ok": not first_failure,
@@ -630,12 +628,89 @@ def run_finalize(
     following = _next_in_group(steps)
     if following:
         payload["nextInGroup"] = following
+    if first_failure:
+        payload["recovery"] = _finalize_recovery(ctx, payload)
     # closeout 이 실제로 건넬 명령. 표를 리드의 기억에 맡기지 않는다.
     payload["nextCommand"] = closeout_command(payload)
     payload["reportPaths"] = _closeout_report_paths(ctx)
     return payload
 
 
+def _execute_finalize_steps(
+    ctx: FinalizeContext, commands: Sequence[tuple[str, list[str]]],
+    before_step: Callable[[str], None] | None,
+) -> tuple[list[dict[str, Any]], str]:
+    """처리 순서를 지키며 각 실패를 기록하고, 전체 성공일 때 실행을 닫는다."""
+    steps: list[dict[str, Any]] = []
+    first_failure = ""
+    validated = False
+    preflight_failed = False
+    for name, command in commands:
+        # 실패한 시퀀스가 worktree 를 거두면 재작업 대상이 사라지고, 검증 안 된
+        # 레코드를 기억하면 형제 task 가 그것을 결론으로 읽는다.
+        if name in _SKIPPED_AFTER_FAILURE and first_failure:
+            continue
+        if name == STEP_TRANSLATE and preflight_failed:
+            continue
+        if before_step is not None:
+            before_step(name)
+        result = _run_finalize_step(ctx, name, command)
+        step = step_payload(name, command, result)
+        if result.returncode != 0:
+            step["errorLogAppend"] = record_runtime_failure(
+                ctx.manifest_path, project_root=ctx.project_root,
+                command=f"report-finalize {name}", exit_code=result.returncode,
+                detail="\n".join(filter(None, [result.stderr, result.stdout])) or f"{name} exited {result.returncode}",
+            )
+        steps.append(step)
+        if name == STEP_PREFLIGHT:
+            preflight_failed = result.returncode != 0
+        if result.returncode != 0 and not first_failure:
+            first_failure = f"{name} failed with exit code {result.returncode}"
+        if name == STEP_VALIDATE_RUN and result.returncode == 0:
+            validated = True
+    if validated and not first_failure:
+        _record_run_end(ctx.team_state_path)
+    return steps, first_failure
+
+
+def _finalize_recovery(ctx: FinalizeContext, result: Mapping[str, Any]) -> dict[str, Any]:
+    """새 실행 대신 실패한 처리부터 재개할 명령과 원본 소유자 오류를 전달한다."""
+    order = V3_STEP_ORDER if ctx.report_contract_version == "3.0" else STEP_ORDER
+    failed = {step["name"] for step in result.get("steps") or [] if step.get("exitCode")}
+    pointer = promote_next_phase(result.get("nextRecommendedPhase"))
+    if (failed == {STEP_VALIDATE_RUN} and pointer["status"] == STATUS_BLOCKED
+            and pointer["phase"] and pointer["phase"] != ctx.task_type):
+        return {"mode": "phase-reentry", "phase": pointer["phase"], "instruction": pointer["rationale"]}
+    command = [
+        "okstra", "report-finalize", "--project-root", str(ctx.project_root),
+        "--run-manifest", str(ctx.manifest_path), "--report", str(ctx.data_path),
+        "--team-state", str(ctx.team_state_path),
+    ]
+    resume_steps = _recovery_step_names(result, order)
+    if ctx.report_contract_version == "3.0" and STEP_PROJECT_ACTIVITY not in resume_steps:
+        # 수정한 서사·판정 상태를 정본에 다시 조립해야 후속 검사가 새 입력을 읽는다.
+        resume_steps = list(order[order.index(STEP_PROJECT_ACTIVITY):])
+    for name in resume_steps:
+        command.extend(["--only", name])
+    issues = []
+    for step in result.get("steps") or []:
+        if step.get("name") != STEP_PROJECT_ACTIVITY or not step.get("exitCode"):
+            continue
+        issues.extend(step.get("issues") or [])
+    return {
+        "mode": "same-run", "resumeCommand": command, "issues": issues,
+        "instruction": (
+            "Repair the reported causes in this run using the owning input's correction command, "
+            "then execute resumeCommand. Preserve approvals, model choices and completed evidence. "
+            "If plan content changes, re-verify the affected items before finalizing. "
+            "After a narrative correction, check existing translations with report-translate check-data "
+            "and regenerate them if their source no longer matches. "
+            "Ask only for an unresolved user decision or an actual external prerequisite."
+        ),
+    }
+
+
 def _closeout_report_paths(ctx: FinalizeContext) -> dict[str, Any]:
     """closeout 이 인용할 task 한정 경로와, 그대로 답장에 붙일 링크.
 
@@ -838,7 +913,11 @@ def _run_project_activity(
                 ctx.data_path,
             )
             count = len(rows)
-    except (ActivityProjectionError, ReportAssemblyError) as exc:
+    except ReportAssemblyError as exc:
+        return subprocess.CompletedProcess(
+            command, 1, json.dumps({"issues": [asdict(issue) for issue in exc.issues]}), str(exc)
+        )
+    except ActivityProjectionError as exc:
         return subprocess.CompletedProcess(command, 1, "", str(exc))
     return subprocess.CompletedProcess(
         command, 0, json.dumps({"count": count}), ""
@@ -1076,12 +1155,21 @@ def closeout_command(result: Mapping[str, Any]) -> dict[str, str]:
     돌려주는 것은 `command` 와 `note` 두 칸이다. `command` 가 비면 근거
     문장이 그 자리를 대신한다.
     """
+    recovery = result.get("recovery")
+    if isinstance(recovery, Mapping) and recovery.get("mode") == "same-run":
+        return {"command": "", "note": str(recovery["instruction"])}
     failed_validate = any(
         step.get("name") == STEP_VALIDATE_RUN and step.get("exitCode") != 0
         for step in (result.get("steps") or [])
         if isinstance(step, Mapping)
     )
     if failed_validate:
+        recovery = promote_next_phase(result.get("nextRecommendedPhase"))
+        if recovery["status"] == STATUS_BLOCKED and recovery["phase"]:
+            return {
+                "command": f"/okstra-run → {recovery['phase']}",
+                "note": recovery["rationale"],
+            }
         return {
             "command": "/okstra-run",
             "note": "validate-run failed — name the blocking cause in one line, "