okstra 0.221.0 → 0.223.0

package/runtime/python/okstra_ctl/convergence_provenance.py

@@ -21,7 +21,6 @@ from pathlib import Path
 from typing import Mapping
 
 from okstra_ctl.convergence_engine import grouped_input_digest
-from okstra_ctl.correction_round import correction_round
 from okstra_ctl.execution_identity import Attempt, ExecutionManifest
 from okstra_ctl.execution_manifest import read_execution_manifest_view
 from okstra_ctl.json_boundary import (
@@ -30,10 +29,16 @@ from okstra_ctl.json_boundary import (
 from okstra_ctl.worker_prompt_policy import CENSUS_GAPFILL_DISPATCH_KIND
 
 GROUPS_BASENAME_RE = re.compile(
-    r"^convergence-groups-(?P<suffix>[a-z][a-z-]*?-\d{3})\.json$"
+    r"^convergence-groups-(?:(?P<scope>correction-r[1-9][0-9]*)-)?"
+    r"(?P<suffix>[a-z][a-z-]*?-\d{3})\.json$"
 )
 
 
+def scoped_suffix(suffix: str, scope: str | None) -> str:
+    """`implementation-001` in the initial namespace, `correction-r1-implementation-001` in round 1's."""
+    return f"{scope}-{suffix}" if scope else suffix
+
+
 def _nonempty_string(value: object) -> bool:
     return isinstance(value, str) and bool(value.strip())
 
@@ -81,7 +86,9 @@ def group_claims(document: object) -> list[tuple[str, str, str]] | None:
     return claims
 
 
-def groups_digest_ok(state_dir: Path, suffix: str, document: dict) -> bool:
+def groups_digest_ok(
+    state_dir: Path, suffix: str, document: dict, scope: str | None = None,
+) -> bool:
     """False only when a recorded groupsDigest exists and no longer matches.
 
     ``okstra convergence seed`` pins ``grouped_input_digest`` of the grouping
@@ -90,7 +97,7 @@ def groups_digest_ok(state_dir: Path, suffix: str, document: dict) -> bool:
     evidence of fabrication — so the caller refuses to judge it. A missing
     working state or missing digest means judge the file as parsed.
     """
-    work_path = state_dir / f"convergence-work-{suffix}.json"
+    work_path = state_dir / f"convergence-work-{scoped_suffix(suffix, scope)}.json"
     try:
         work = load_owned_object(work_path, artifact="convergence work state")
     except (OSError, ValueError):
@@ -101,11 +108,14 @@ def groups_digest_ok(state_dir: Path, suffix: str, document: dict) -> bool:
     return grouped_input_digest(document) == recorded
 
 
-def discovery_attempts(manifest: ExecutionManifest) -> dict[str, list[Attempt]]:
-    """교정 실행과 수정 라운드 재검증은 발견 결과를 대체하지만 재검증 투표는 발견 출처가 아니다.
+def discovery_attempts(
+    manifest: ExecutionManifest, scope: str | None = None,
+) -> dict[str, list[Attempt]]:
+    """한 수렴 범위의 발견 결과. 교정 실행은 초기 결과를 대체하지만 재검증 투표는 발견 출처가 아니다.
 
-    수정 라운드(`correction-r<N>`) 뒤 수렴을 다시 시작하면 마지막 라운드의 verifier 결과가
-    출처여야 한다. 빠지면 고치기 전 FAIL 결과로 다시 수렴한다.
+    수정 라운드 N 의 재수렴(`scope` = `correction-r<N>`)은 그 라운드의 재검증 결과만 읽고, 초기
+    수렴은 초기 결과만 읽는다. 하나로 섞으면 이미 끝난 초기 grouping 의 출처가 라운드 결과로
+    바뀌어 그 grouping 이 출처 검사에서 깨진다.
     """
     latest: dict[str, Attempt] = {}
     for attempt in manifest.attempts:
@@ -114,8 +124,8 @@ def discovery_attempts(manifest: ExecutionManifest) -> dict[str, list[Attempt]]:
             latest[attempt.invocation_ref] = attempt
     by_role: dict[str, list[Attempt]] = {}
     for invocation in manifest.invocations:
-        if (invocation.dispatch_kind not in {"initial", "correction"}
-                and correction_round(invocation.dispatch_kind) is None):
+        kind = invocation.dispatch_kind
+        if (kind != scope if scope else kind not in {"initial", "correction"}):
             continue
         attempt = latest.get(invocation.invocation_ref)
         if attempt is not None:
@@ -124,13 +134,13 @@ def discovery_attempts(manifest: ExecutionManifest) -> dict[str, list[Attempt]]:
 
 
 def worker_result_paths(
-    run_dir: Path, document: Mapping, suffix: str
+    run_dir: Path, document: Mapping, suffix: str, scope: str | None = None,
 ) -> dict[str, Path]:
     """실행 원장의 채택된 발견 결과를 고른다. 구형 원장은 파일명 규칙을 쓴다."""
     results_dir = run_dir / "worker-results"
     workers = document.get("workers") or []
     paths = {
-        row["workerId"]: results_dir / f"{row['workerId']}-worker-{suffix}.md"
+        row["workerId"]: results_dir / f"{row['workerId']}-worker-{scoped_suffix(suffix, scope)}.md"
         for row in workers if isinstance(row, Mapping) and row.get("workerId")
     }
     if document.get("schemaVersion") != "2.0":
@@ -142,7 +152,7 @@ def worker_result_paths(
     manifest, authority = read_execution_manifest_view(manifest_path)
     if manifest.legacy:
         return paths
-    attempts = discovery_attempts(manifest)
+    attempts = discovery_attempts(manifest, scope)
     for row in workers:
         if not isinstance(row, Mapping) or not row.get("workerId"):
             continue
@@ -208,6 +218,7 @@ def provenance_errors(
     worker_results_dir: Path,
     suffix: str,
     groups_label: str,
+    scope: str | None = None,
 ) -> list[str]:
     """Every claim in ``document`` whose cited ID is absent from its worker's
     result file. An unjudgeable document yields no errors — a caller that
@@ -215,22 +226,23 @@ def provenance_errors(
     claims = group_claims(document)
     if claims is None:
         return []
-    paths = worker_result_paths(worker_results_dir.parent, document, suffix)
+    paths = worker_result_paths(worker_results_dir.parent, document, suffix, scope)
+    result_suffix = scoped_suffix(suffix, scope)
     contents: dict[str, str | None] = {}
     errors: list[str] = []
     for finding_id, worker, item_id in claims:
         if worker not in contents:
             candidate = paths.get(worker)
-            if candidate is not None and candidate.name != f"{worker}-worker-{suffix}.md":
+            if candidate is not None and candidate.name != f"{worker}-worker-{result_suffix}.md":
                 contents[worker] = candidate.read_text(encoding="utf-8")
             else:
                 contents[worker] = read_canonical_worker_result(
-                    worker_results_dir, worker, suffix
+                    worker_results_dir, worker, result_suffix
                 )
         text = contents[worker]
         if text is None or id_occurs_wordbounded(text, item_id):
             continue
-        gapfill = read_canonical_worker_result(
+        gapfill = None if scope else read_canonical_worker_result(
             worker_results_dir, worker, f"{CENSUS_GAPFILL_DISPATCH_KIND}-{suffix}"
         )
         # A finding the census gap-fill raised lives in that worker's gap-fill
@@ -240,7 +252,7 @@ def provenance_errors(
         errors.append(
             f"convergence groups `{groups_label}` group {finding_id} "
             f"cites source item `{worker}:{item_id}`, but that ID does not "
-            f"occur in the worker's result file `{paths.get(worker, Path(f'{worker}-worker-{suffix}.md')).name}` — a "
+            f"occur in the worker's result file `{paths.get(worker, Path(f'{worker}-worker-{result_suffix}.md')).name}` — a "
             "grouping may not invent a provenance link to an item the "
             "worker never reported."
         )
@@ -297,7 +309,7 @@ def run_dir_provenance_errors(run_dir: Path) -> list[str]:
         match = GROUPS_BASENAME_RE.match(groups_path.name)
         if match is None:
             continue
-        suffix = match.group("suffix")
+        suffix, scope = match.group("suffix"), match.group("scope")
         try:
             document = load_owned_object(
                 groups_path, artifact="convergence groups input"
@@ -306,7 +318,7 @@ def run_dir_provenance_errors(run_dir: Path) -> list[str]:
             continue
         if not isinstance(document, dict):
             continue
-        if not groups_digest_ok(state_dir, suffix, document):
+        if not groups_digest_ok(state_dir, suffix, document, scope):
             continue
         result_suffix = worker_result_suffix(Path(run_dir), document)
         if result_suffix is None:
@@ -317,6 +329,7 @@ def run_dir_provenance_errors(run_dir: Path) -> list[str]:
                 worker_results_dir=worker_results_dir,
                 suffix=result_suffix,
                 groups_label=groups_path.name,
+                scope=scope,
             )
         )
     return errors
@@ -329,7 +342,9 @@ DISCARDED_ATTEMPT_STATUSES = frozenset(
 )
 
 
-def discarded_workers(document: object, execution_manifest: object) -> dict[str, str]:
+def discarded_workers(
+    document: object, execution_manifest: object, scope: str | None = None,
+) -> dict[str, str]:
     """``{workerId: "<invocationRef>#<attempt> <status>"}`` — 발견 attempt 가 전부
     폐기돼 채택할 결과가 없는 분석 워커.
 
@@ -341,7 +356,7 @@ def discarded_workers(document: object, execution_manifest: object) -> dict[str,
         return {}
     if execution_manifest is None or getattr(execution_manifest, "legacy", False):
         return {}
-    attempts = discovery_attempts(execution_manifest)
+    attempts = discovery_attempts(execution_manifest, scope)
     result: dict[str, str] = {}
     for row in document["workers"]:
         if not isinstance(row, dict):
@@ -360,7 +375,9 @@ def discarded_workers(document: object, execution_manifest: object) -> dict[str,
     return result
 
 
-def discarded_worker_errors(document: object, execution_manifest: object) -> list[str]:
+def discarded_worker_errors(
+    document: object, execution_manifest: object, scope: str | None = None,
+) -> list[str]:
     """Groups that cite a worker whose only initial attempts were discarded.
 
     The mutation audit discards a result by setting the attempt terminal status
@@ -371,7 +388,7 @@ def discarded_worker_errors(document: object, execution_manifest: object) -> lis
     3 named it ``originWorker`` — the ledger said "discarded" while convergence
     said "adopted".
     """
-    discarded = discarded_workers(document, execution_manifest)
+    discarded = discarded_workers(document, execution_manifest, scope)
     if not discarded or not isinstance(document, dict):
         return []
     errors: list[str] = []
@@ -393,3 +410,31 @@ def discarded_worker_errors(document: object, execution_manifest: object) -> lis
                 "as a new invocation and cite that result"
             )
     return errors
+
+
+def missing_scope_results(
+    document: object, execution_manifest: object, scope: str | None,
+) -> list[str]:
+    """Analysis workers of a correction round's grouping with no accepted result from that round.
+
+    Without one the provenance check would read nothing and pass, and the round would converge
+    on items the worker never re-verified.
+    """
+    if scope is None or execution_manifest is None or getattr(execution_manifest, "legacy", False):
+        return []
+    if not isinstance(document, dict):
+        return []
+    attempts = discovery_attempts(execution_manifest, scope)
+    missing = sorted({
+        str(row.get("workerId"))
+        for row in document.get("workers") or []
+        if isinstance(row, dict) and row.get("audience") == "analysis"
+        and not any(
+            item.status == "ok" for item in attempts.get(row.get("sourceRoleExecutionRef"), [])
+        )
+    })
+    return [
+        f"`{worker}` has no accepted `{scope}` result; await that round's verifiers "
+        "before converging it"
+        for worker in missing
+    ]

package/runtime/python/okstra_ctl/convergence_reverify_prompt.py

@@ -136,6 +136,7 @@ def reverify_findings(
     *,
     project_root: Path,
     run_dir: Path,
+    scope: str | None = None,
 ) -> list[ReverifyFinding]:
     """계획 행의 finding 을 계획 순서대로, 원 워커의 실물 인용 위치와 함께."""
     row = plan_row_for_worker(plan, worker_id)
@@ -146,7 +147,9 @@ def reverify_findings(
     }
     result_paths = {
         result.worker_id: result.result_path
-        for result in analyser_results(groups, project_root=project_root, run_dir=run_dir)
+        for result in analyser_results(
+            groups, project_root=project_root, run_dir=run_dir, scope=scope,
+        )
     }
     findings: list[ReverifyFinding] = []
     for finding_id in row["findingIds"]:

package/runtime/python/okstra_ctl/correction_cli.py

@@ -6,8 +6,8 @@ import subprocess
 import sys
 from pathlib import Path
 
-from .convergence import canonical_run_state_artifact, validated_run_authority
-from .correction_round import CorrectionRoundError, correction_instruction
+from .convergence import scoped_convergence_state, validated_run_authority
+from .correction_round import CorrectionRoundError, convergence_scope, correction_instruction
 from .file_size_cap import FILE_LINE_LIMIT, FILE_LINE_TARGET, file_size_violations
 
 
@@ -18,7 +18,9 @@ _CLI_EPILOG = r"""Usage:
 
 `prompt` prints the instruction body for one correction-round prompt; pass it to
 `okstra agent-prompt materialize --instruction` with --dispatch-kind correction-r<N>.
-Findings are read from the run's convergence record; --stage-base adds the file-size
+Findings are read from the convergence record that preceded the round: the run's
+initial one for round 1, round N-1's re-convergence (`convergence-correction-r<N-1>-…`)
+for round N; --stage-base adds the file-size
 findings of `<stage-base>..<base>` (the 400-line limit only). Exit 1 on a refusal.
 
 `file-size` prints one `FILE-SIZE:<path>:401` line per file the stage diff leaves over
@@ -72,10 +74,8 @@ def main(argv: list[str] | None = None) -> int:
         authority = validated_run_authority(args.run_manifest)
         if authority.task_type != "implementation":
             raise CorrectionRoundError("correction rounds exist only in implementation runs")
-        convergence_path = canonical_run_state_artifact(
-            authority, manifest_field="convergenceStatePath", prefix="convergence",
-            label="convergence state",
-        )
+        previous = args.round - 1 if args.round > 1 else None
+        convergence_path = scoped_convergence_state(authority, convergence_scope(previous))
         size_violations = [
             v for v in file_size_violations(Path.cwd(), args.stage_base, args.base)
             if v.blocking

package/runtime/python/okstra_ctl/correction_round.py

@@ -32,6 +32,46 @@ def correction_round(dispatch_kind: str) -> int | None:
     return int(match.group(1)) if match else None
 
 
+def convergence_scope(round_number: int | None) -> str | None:
+    """The convergence namespace of correction round N (`correction-r<N>`); None is the initial one.
+
+    Re-converging a round's re-verification reuses no initial-round artifact: its groups, working
+    and final state, round plans and reverify invocations carry this token, so the initial final
+    stays as written and its provenance keeps reading the initial results.
+    """
+    if round_number is None:
+        return None
+    if not 1 <= round_number <= MAX_CORRECTION_ROUNDS:
+        raise CorrectionRoundError(f"--correction-round must be 1..{MAX_CORRECTION_ROUNDS}")
+    return f"{CORRECTION_DISPATCH_KIND_PREFIX}{round_number}"
+
+
+def correction_convergence_states(initial_final: Path) -> list[tuple[str, Path]]:
+    """Each correction round's re-convergence final written beside the run's initial one."""
+    prefix = "convergence-"
+    if not initial_final.name.startswith(prefix):
+        return []
+    rest = initial_final.name[len(prefix):]
+    rows = []
+    for round_number in range(1, MAX_CORRECTION_ROUNDS + 1):
+        scope = convergence_scope(round_number)
+        path = initial_final.with_name(f"{prefix}{scope}-{rest}")
+        if path.is_file():
+            rows.append((scope, path))
+    return rows
+
+
+def reverify_invocation_in_scope(invocation_ref: str, scope: str | None, round_number: int) -> bool:
+    """Whether a `reverify-r<N>` invocation belongs to this convergence namespace.
+
+    Both namespaces dispatch kind `reverify-r<N>`, so the invocation id tells them apart: a
+    correction re-convergence names it `…-correction-r<M>-reverify-r<N>-<worker>`.
+    """
+    if scope is None:
+        return f"-{CORRECTION_DISPATCH_KIND_PREFIX}" not in invocation_ref
+    return f"-{scope}-reverify-r{round_number}-" in invocation_ref
+
+
 def validate_correction_dispatch(
     manifest: ExecutionManifest, jobs: Sequence[object],
 ) -> None:

package/runtime/python/okstra_ctl/fix_cycles.py

@@ -17,7 +17,9 @@ from __future__ import annotations
 import json
 import re
 from pathlib import Path
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List, Mapping, Optional
+
+from okstra_project.phase_pointer import promote
 
 from .run_context import dir_flock
 from .jsonl import append_jsonl
@@ -33,6 +35,17 @@ FIX_CYCLE_ENTRY_PHASES = (
 )
 
 
+def delivery_completed(workflow: Mapping[str, Any]) -> bool:
+    """release-handoff 가 전달까지 끝냈는가. fix cycle 을 열고 닫는 조건이다.
+
+    skip·미전달 stage 가 남은 handoff 는 다음 phase 포인터를 다시
+    release-handoff 로 둔다(`next_phase.project`).
+    """
+    if workflow.get("lastCompletedPhase") != "release-handoff":
+        return False
+    return promote(workflow.get("nextRecommendedPhase"))["phase"] != "release-handoff"
+
+
 def fix_cycles_path(task_root: Path) -> Path:
     return Path(task_root) / "history" / FIX_CYCLES_FILENAME
 

package/runtime/python/okstra_ctl/git_reconcile.py

@@ -165,13 +165,20 @@ class ReconcileError(Exception):
     pass
 
 
+# 최신 done 행이 last-wins 라, 보정 행이 이 필드를 안 옮기면 stage 의 보고서·carry 가 사라진다.
+_COMPLETION_FIELDS = ("report_path", "carry_path", "completed_at")
+
+
 def _record_reconciled(plan_run_root: Path, *, impl_task_key: str, stage: int,
                        new_commit: str, replaced: str, reason: str) -> None:
-    from .consumers import append_consumer
+    from .consumers import append_consumer, latest_done_by_stage, read_consumers
+    previous = latest_done_by_stage(read_consumers(plan_run_root)).get(stage) or {}
+    completion = {k: previous[k] for k in _COMPLETION_FIELDS if previous.get(k)}
     append_consumer(
         plan_run_root, impl_task_key=impl_task_key, stage=stage,
         status="done", force_reappend=True, head_commit=new_commit,
         reconciled=True, reconcile_reason=reason, replaced_commit=replaced,
+        **completion,
     )
 
 
@@ -195,12 +202,19 @@ def auto_reconcile(*, project_root: Path, plan_run_root: Path,
     return applied
 
 
-def guidance(*, plan_run_root: Path, project_id: str, task_group: str,
+def _command(*, plan_run_root: Path, project_id: str, task_group: str,
              task_id: str, work_category: str) -> str:
-    """PrepareError 에 첨부하는 회복 안내 (명령 예시 포함)."""
-    base = (f"okstra git-reconcile --plan-run-root {plan_run_root} "
+    return (f"okstra git-reconcile --plan-run-root {plan_run_root} "
             f"--project-id {project_id} --task-group {task_group} "
             f"--task-id {task_id} --work-category {work_category}")
+
+
+def guidance(*, plan_run_root: Path, project_id: str, task_group: str,
+             task_id: str, work_category: str) -> str:
+    """PrepareError 에 첨부하는 회복 안내 (명령 예시 포함)."""
+    base = _command(plan_run_root=plan_run_root, project_id=project_id,
+                    task_group=task_group, task_id=task_id,
+                    work_category=work_category)
     return ("Recorded stage SHAs no longer match the git history "
             "(external rebase/squash/amend?). Inspect and reconcile:\n"
             f"  {base} --check --text\n"
@@ -224,6 +238,32 @@ def _apply_user_ref(project_root: Path, plan_run_root: Path,
     return {"stage": stage, "new_commit": sha}
 
 
+def _anchor_warning(*, project_root: Path, plan_run_root: Path, project_id: str,
+                    task_group: str, task_id: str, work_category: str,
+                    stage: int, new_commit: str) -> str:
+    """보정한 head 가 anchor 를 담지 않으면 whole-task diff 의 base 가 틀린다.
+    anchor 는 --reset-anchor 로만 옮기므로 경고와 명령만 낸다."""
+    from . import worktree_registry as _reg
+
+    anchor = _reg.get_implementation_base(project_id, task_group, task_id) or ""
+    if not _resolve_commit_sha(project_root, anchor):
+        return ""
+    if _git(project_root, "merge-base", "--is-ancestor",
+            anchor, new_commit).returncode == 0:
+        return ""
+    entry = _reg.lookup(project_id, task_group, task_id)
+    base_ref = entry.base_ref if entry else ""
+    new_base = (_git(project_root, "merge-base", base_ref, new_commit).stdout.strip()
+                if base_ref else "")
+    command = _command(plan_run_root=plan_run_root, project_id=project_id,
+                       task_group=task_group, task_id=task_id,
+                       work_category=work_category)
+    return (f"stage {stage} head {new_commit} does not contain the implementation "
+            f"anchor {anchor}; whole-task final-verification would diff from the "
+            f"old base. Move the anchor after confirming the new base:\n"
+            f"  {command} --apply --reset-anchor {new_base or '<new-base-commit>'}")
+
+
 def apply_reconcile(*, project_root: Path, plan_run_root: Path,
                     project_id: str, task_group: str, task_id: str,
                     work_category: str, stage: Optional[int] = None,
@@ -239,6 +279,7 @@ def apply_reconcile(*, project_root: Path, plan_run_root: Path,
     from .consumers import read_consumers, latest_done_by_stage
 
     applied: List[dict] = []
+    warnings: List[str] = []
     if reset_anchor:
         sha = _resolve_commit_sha(project_root, reset_anchor)
         if not sha:
@@ -247,8 +288,16 @@ def apply_reconcile(*, project_root: Path, plan_run_root: Path,
         applied.append({"anchor": sha})
     if use_ref:
         latest = latest_done_by_stage(read_consumers(plan_run_root))
-        applied.append(_apply_user_ref(
-            project_root, plan_run_root, latest, stage, use_ref))
+        recorded = _apply_user_ref(
+            project_root, plan_run_root, latest, stage, use_ref)
+        applied.append(recorded)
+        warning = _anchor_warning(
+            project_root=project_root, plan_run_root=plan_run_root,
+            project_id=project_id, task_group=task_group, task_id=task_id,
+            work_category=work_category, stage=stage,
+            new_commit=recorded["new_commit"])
+        if warning:
+            warnings.append(warning)
     items = classify_task(
         project_root=project_root, plan_run_root=plan_run_root,
         project_id=project_id, task_group=task_group, task_id=task_id,
@@ -264,7 +313,8 @@ def apply_reconcile(*, project_root: Path, plan_run_root: Path,
         applied.append({"stage": item.stage, "new_commit": item.suggested_commit})
     remaining = [i for i in items if i.classification == "confirm"
                  and not (use_ref and i.stage == stage)]
-    return {"applied": applied, "remaining_confirm": remaining}
+    return {"applied": applied, "remaining_confirm": remaining,
+            "warnings": warnings}
 
 
 def _items_as_json(items: List[StaleItem]) -> list:
@@ -345,6 +395,9 @@ def render_git_reconcile_text(payload: dict) -> str:
         rows.append(line(f"Item {index} kind", item.get("kind")))
         rows.append(line(f"Item {index} classification", item.get("classification")))
         rows.append(line(f"Item {index} reason", item.get("reason")))
+    warnings = payload.get("warnings") if isinstance(payload.get("warnings"), list) else []
+    for index, warning in enumerate(warnings, 1):
+        rows.append(line(f"Warning {index}", warning))
     if "error" in payload:
         rows.append(line("Failure reason", payload.get("error")))
     return "".join(rows)
@@ -362,7 +415,8 @@ def main(argv: Optional[list] = None) -> int:
             result = apply_reconcile(**kw, stage=a.stage, use_ref=a.use_ref,
                                      reset_anchor=a.reset_anchor)
             out = {"applied": result["applied"],
-                   "remaining_confirm": _items_as_json(result["remaining_confirm"])}
+                   "remaining_confirm": _items_as_json(result["remaining_confirm"]),
+                   "warnings": result["warnings"]}
             _emit_result(out, as_json=a.json, as_text=a.text)
             return 2 if result["remaining_confirm"] else 0
         items = classify_task(**kw)

package/runtime/python/okstra_ctl/next_phase.py

@@ -35,7 +35,7 @@ from okstra_project.phase_pointer import (  # noqa: F401 — 의도적 재노출
     promote,
 )
 
-# 라우팅 필드가 없어 항상 terminal 인 task-type.
+# 라우팅 필드가 자유 문자열이라 전달을 마치면 terminal 인 task-type.
 _TERMINAL_TASK_TYPES = frozenset({"release-handoff"})
 
 # 라우팅 필드가 없어 항상 pending 인 사이드트랙 task-type.
@@ -120,14 +120,13 @@ def project(report_data: Mapping[str, Any]) -> dict[str, str]:
 
     if task_type in _TERMINAL_TASK_TYPES:
         # release-handoff 의 라우팅 칸은 자유 문자열이다. phase 로 삼을 값은
-        # 없지만(생애주기가 여기서 끝난다) 그 문장은 태스크가 왜 끝났는지
-        # 말하므로 근거 자리에 싣는다.
-        return make(
-            status=STATUS_TERMINAL,
-            rationale=_text(
-                _block(report_data, "releaseHandoff").get("routingRecommendation")
-            ),
-        )
+        # 없지만 그 문장은 태스크가 왜 끝났는지(또는 무엇이 남았는지) 말하므로
+        # 근거 자리에 싣는다.
+        handoff = _block(report_data, "releaseHandoff")
+        rationale = _text(handoff.get("routingRecommendation"))
+        if _handoff_left_stages_undelivered(handoff):
+            return make(phase="release-handoff", status=STATUS_READY, rationale=rationale)
+        return make(status=STATUS_TERMINAL, rationale=rationale)
     if task_type in _SIDETRACK_TASK_TYPES:
         return make(status=STATUS_PENDING)
 
@@ -148,6 +147,20 @@ def project(report_data: Mapping[str, Any]) -> dict[str, str]:
     return make(status=STATUS_PENDING)
 
 
+def _handoff_left_stages_undelivered(handoff: Mapping[str, Any]) -> bool:
+    """skip 이거나 PR 을 건너뛴 stage 가 있으면 release-handoff 재진입이 남는다.
+
+    `prompts/lead/phase-routing.md` `## release-handoff` 의 라우팅 규칙이다.
+    """
+    selections = handoff.get("userSelections")
+    if isinstance(selections, Mapping) and selections.get("h1") == "skip":
+        return True
+    outcomes = handoff.get("pullRequestOutcomes")
+    return isinstance(outcomes, list) and any(
+        isinstance(row, Mapping) and row.get("kind") == "skipped" for row in outcomes
+    )
+
+
 def _block(report_data: Mapping[str, Any], key: str) -> Mapping[str, Any]:
     block = report_data.get(key)
     return block if isinstance(block, Mapping) else {}

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

@@ -25,7 +25,7 @@ from okstra_ctl.plan_run_root import plan_run_root_from_approved_plan
 from okstra_ctl.prepare_error import PrepareError
 from okstra_ctl.stage_integrate import IntegrateResult
 from okstra_ctl.stage_map import active_stage_records
-from okstra_ctl.stage_reconcile import auto_reconcile_best_effort
+from okstra_ctl.stage_reconcile import require_reconciled_stages
 from okstra_ctl.stage_targets import (
     FinalVerificationTarget,
     StageTargetError,
@@ -106,7 +106,8 @@ def _read_final_verification_done_rows(
     plan_run_root = plan_run_root_from_approved_plan(request.approved_plan_path)
     backfill_done_from_carry(plan_run_root)
     project_id, task_group, task_id = registry_coordinates
-    auto_reconcile_best_effort(
+    # 복원·재배치·통합보다 먼저 거부해야 거부된 prepare 가 git 을 건드리지 않는다.
+    require_reconciled_stages(
         replace(
             request,
             project_id=project_id,
@@ -114,6 +115,7 @@ def _read_final_verification_done_rows(
             task_id=task_id,
         ),
         plan_run_root,
+        stage=request.stage,
     )
     from okstra_ctl.stage_rebase import synchronize_stage_stack
     from okstra_ctl.stage_targets import StageWorktreeIdentity

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

@@ -17,7 +17,7 @@ from typing import Any
 from okstra_ctl import stage_targets
 from okstra_ctl.design_prep import DesignPrepDecision, DesignPrepError, resolve_design_prep
 from okstra_ctl.final_report_paths import final_report_data_path
-from okstra_ctl.stage_reconcile import auto_reconcile_best_effort
+from okstra_ctl.stage_reconcile import StaleStageRecordsError, require_reconciled_stages
 from okstra_ctl.worker_prompt_policy import IMPLEMENTATION_STAGE_HEADER
 
 
@@ -94,7 +94,11 @@ 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)
+    # stage 재배치·base 계산보다 먼저 거부해야 거부된 prepare 가 git 을 건드리지 않는다.
+    try:
+        require_reconciled_stages(inp, plan_run_root)
+    except StaleStageRecordsError as exc:
+        raise ImplementationStageError(str(exc)) from exc
     from okstra_ctl.stage_rebase import synchronize_stage_stack
 
     try:

package/runtime/python/okstra_ctl/phases/implementation/host-rules.md

@@ -47,6 +47,7 @@ If `render-bundle` fails with a `PrepareError` containing `Recorded stage SHAs n
    - **Enter a different ref directly** — the user names a commit/branch/tag.
    - **Abort** — stop the run without recovering.
 3. Run `okstra git-reconcile … --apply --stage <N> --use-ref <ref>` with the chosen ref, then retry the failed `render-bundle` with the same arguments.
+   If that output carries a `Warning` naming the implementation anchor, the chosen head no longer contains the anchor: show the warning to the user and run its printed `--reset-anchor` command only after they confirm the new base, before the retry.
 
 If the anchor (`implementation_base_commit`) is reported unresolvable, run the same command's `--reset-anchor <ref>` after user confirmation. Correcting a confirm item without the picker is forbidden — the runtime also rejects a confirm correction without `--use-ref`.
 

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

@@ -88,10 +88,10 @@ Changing a test's expected value is allowed here when the finding shows the orac
 2. Write the executor instruction with `okstra correction prompt --run-manifest <path> --round <N> --role executor --base <base> --stage-base <stage base> --finding <F-id> [--finding <F-id> ...]` into a file under the run's `state/`, then materialize it with `okstra agent-prompt materialize` — `--audience implementation-executor`, `--assignment-ref initial/<executor worker id>`, `--dispatch-kind correction-r<N>`, a new `--invocation-id` ending `-correction-r<N>-<executor worker id>`, and a result path `<executor worker id>-worker-correction-r<N>-implementation-<seq>.md`. Build a jobs file with `okstra agent-prompt jobs --dispatch-kind correction-r<N>`, dispatch it alone with `okstra team dispatch --jobs-file <path> --dispatch-kind correction-r<N>`, and settle it with `okstra team await`.
    `--stage-base` (the carry's `stageCommitRange.base`) adds a `FILE-SIZE:<path>` finding for each file the stage diff leaves over the 400-line limit, computed by `okstra correction file-size`; a `FILE-SIZE-ADVISORY:` line (the 300-line target) never opens or joins a round; a round may hold only those findings, and `findingIds` records them by that id. Leave out a convergence finding id that restates a `FILE-SIZE:` line, or the executor reads it twice.
 3. Do the same for every verifier with `--role verifier`, `--audience implementation-verifier`, its own `initial/<verifier worker id>` assignment, and result `<verifier worker id>-worker-correction-r<N>-implementation-<seq>.md`; dispatch the verifiers in one batch without the executor.
-4. Converge the re-verification results the way the initial round was converged, restarting Phase 5.5 with `okstra convergence seed ... --restart-from-round0`.
+4. Converge the re-verification results in round `<N>`'s own namespace, leaving the initial convergence as written. Run Phase 5.5 again with `correction-r<N>` before `<task-type>` in every state name: `okstra convergence prepare-groups --correction-round <N>` writes `convergence-groups-correction-r<N>-<task-type>-<seq>.json`; seed it with `--work-state …/convergence-work-correction-r<N>-<task-type>-<seq>.json` and `--final-state …/convergence-correction-r<N>-<task-type>-<seq>.json`; name round plans and results `convergence-round-<k>-plan-correction-r<N>-<task-type>-<seq>.json`. A reverify round in it passes `--correction-round <N>` to `reverify-prompt` and `collect-results`, materializes with `--invocation-id` ending `-correction-r<N>-reverify-r<k>-<worker id>`, and names its result `<worker id>-worker-correction-r<N>-reverify-r<k>-<task-type>-<seq>.md`. Never reseed the initial paths: a terminal final there is reused, and `--restart-from-round0` refuses it. Round `<N+1>`'s `okstra correction prompt` reads its findings from this round's final, and the report writer's synthesis packet carries it as `Convergence state (correction-r<N>)` beside the initial `Convergence state` (`report_synthesis_packet._source_specs`); report assembly projects it into `crossVerification.correctionRounds[]` and appends the evidence it promotes to `evidence.primary` with source `convergence correction-r<N>` (`report_assembly._correction_round_convergence`).
 5. No re-verification verdict is `FAIL`: the round `result` is `pass` and the run continues to persistence with the post-fix head. Otherwise `result: fail`; start round `<N+1>` if the cap allows and the entry rules still hold, or end the run `FAIL`.
 
-**Enforced:** `scripts/okstra_ctl/dispatch_core.py` `_validate_correction_rounds` (via `correction_round.validate_correction_dispatch`) refuses a round past the cap, a verifier dispatch before that round's executor returned an `ok` result, a second executor fix in the same round, and round `<N+1>` before round `<N>` was re-verified. `validators/validate-run.py` `_validate_correction_rounds` (blocking) fails a report whose `correctionRounds` differ from the correction rounds the run dispatched, whose rounds are not 1, 2 in order, whose `result` contradicts its verdicts, or whose `verifierResults` are not the last round's verdicts. The entry rules are instructions only. `okstra stage-done` (`scripts/okstra_ctl/stage_done.py` `_check_file_size`) refuses to settle a stage whose carry range breaks the 400-line file-size limit and names the `--stage-base` to pass, so a size violation no verifier reported still reaches a correction round, or ends the run `FAIL` when no round is left.
+**Enforced:** `okstra convergence seed` (`scripts/okstra_ctl/convergence.py` `_seed`) accepts state paths only in the initial or a `correction-r<N>` namespace, refuses a round grouping before every grouped verifier returned an `ok` round `<N>` result (`convergence_provenance.missing_scope_results`), and checks its cited items against that round's results (`discovery_attempts` per namespace); `convergence_migration.decide_seed_action` refuses `--restart-from-round0` without an invalid working state; `plan-round` refuses to overwrite a round plan whose namespace already dispatched that round (`_refuse_dispatched_plan_overwrite`); `collect-results` reads only the namespace's reverify invocations (`correction_round.reverify_invocation_in_scope`). `scripts/okstra_ctl/dispatch_core.py` `_validate_correction_rounds` (via `correction_round.validate_correction_dispatch`) refuses a round past the cap, a verifier dispatch before that round's executor returned an `ok` result, a second executor fix in the same round, and round `<N+1>` before round `<N>` was re-verified. `validators/validate-run.py` `_validate_correction_rounds` (blocking) fails a report whose `correctionRounds` differ from the correction rounds the run dispatched, whose rounds are not 1, 2 in order, whose `result` contradicts its verdicts, or whose `verifierResults` are not the last round's verdicts. The entry rules are instructions only. `okstra stage-done` (`scripts/okstra_ctl/stage_done.py` `_check_file_size`) refuses to settle a stage whose carry range breaks the 400-line file-size limit and names the `--stage-base` to pass, so a size violation no verifier reported still reaches a correction round, or ends the run `FAIL` when no round is left.
 
 ## Self-review pass before finalising the report (the Okstra lead runs this; do not delegate it)