okstra 0.221.0 → 0.223.0

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

@@ -12,7 +12,10 @@ from okstra_ctl.pr_template import PrTemplateError, resolve_pr_template_path
 from okstra_ctl.stage_map import parse_stage_map_for_prepare
 from okstra_ctl.phases.catalog import migrated_report_template
 from okstra_ctl.handoff_error import HandoffError
-from .operations import _require_eligible, compute_eligibility, _parse_stages_csv
+from .operations import (
+    DEFAULT_RELEASE_BASES, _parse_stages_csv, _require_eligible,
+    anchor_base_branches, compute_eligibility,
+)
 
 
 def _collect_handoff_source_report_rows(
@@ -74,6 +77,43 @@ def _select_handoff_stages(stage_map: list, rows: list, selection: str) -> list[
     return nums
 
 
+def _render_anchor_base_candidates(project_root: Path, inp) -> str:
+    """구현 기준 커밋을 담은 기본 후보가 없으면, 그 커밋에 있는 origin 브랜치를
+    Q2 의 첫 후보로 올린다. 다른 task 의 미병합 stage 위에 쌓인 task 는 기본
+    후보 어느 것을 base 로 잡아도 그 task 의 커밋까지 PR 에 실린다."""
+    from okstra_ctl import worktree_registry
+    from okstra_ctl.work_categories import resolve_work_category
+    from okstra_ctl.worktree import is_ancestor
+
+    anchor = worktree_registry.get_implementation_base(
+        inp.project_id, inp.task_group, inp.task_id) or ""
+    if not anchor:
+        return ""
+    if any(is_ancestor(project_root, anchor, f"refs/remotes/origin/{name}")
+           for name in DEFAULT_RELEASE_BASES):
+        return ""
+    work_category = resolve_work_category(
+        inp.work_category, project_root=project_root,
+        task_group=inp.task_group, task_id=inp.task_id)
+    branches = anchor_base_branches(project_root, anchor,
+                                    work_category=work_category, task_id=inp.task_id)
+    held = branches["at"] + branches["containing"]
+    defaults = ", ".join(f"`{name}`" for name in DEFAULT_RELEASE_BASES)
+    lines = [f"- Implementation anchor base: `{anchor}` — no default candidate "
+             f"({defaults}) contains it, so a PR on any of them would also carry "
+             "the commits of the work this task was built on."]
+    if held:
+        lines.append(f"- Recommended release base (offer first in Q2): `{held[0]}`")
+    else:
+        lines.append("- Recommended release base: none — no origin branch holds the "
+                     "anchor; push the branch it came from before release-handoff.")
+    lines.append("- origin branches at the anchor: "
+                 + (", ".join(f"`{n}`" for n in branches["at"]) or "none"))
+    lines.append("- origin branches containing the anchor: "
+                 + (", ".join(f"`{n}`" for n in branches["containing"]) or "none"))
+    return "\n".join(lines)
+
+
 def materialize_handoff_input(
     workspace_root: Path, project_root: Path, inp, *, install_hint: str,
 ) -> dict:
@@ -133,6 +173,7 @@ def materialize_handoff_input(
         "HANDOFF_STAGES": stages_csv,
         "HANDOFF_SOURCE_REPORTS": source_rows,
         "HANDOFF_CONDITIONS": source_conditions,
+        "HANDOFF_ANCHOR_BASE_CANDIDATES": _render_anchor_base_candidates(project_root, inp),
     })
     inp.brief_path = out
     return {"HANDOFF_STAGES": stages_csv}

package/runtime/python/okstra_ctl/phases/release_handoff/operations.py

@@ -123,6 +123,51 @@ def _merge_base_for(*, project_root, project_id, task_group, task_id,
         raise HandoffError(str(exc)) from exc
 
 
+# 입력 문서 `Candidate Release Base Branches` 의 기본 후보와 같은 목록이다.
+DEFAULT_RELEASE_BASES = ("staging", "preprod", "prod", "main", "dev")
+
+
+def _origin_branches(project_root, flag: str, commit: str, own_prefix: str) -> List[str]:
+    """`git branch -r <flag> <commit>` 중 origin 브랜치 이름. 이 task 자신의 stage
+    브랜치는 릴리스 base 가 될 수 없으므로 뺀다."""
+    res = _git(Path(project_root), "branch", "-r", "--format=%(refname)", flag, commit)
+    if res.returncode != 0:
+        return []
+    prefix = "refs/remotes/origin/"
+    names = [line.strip()[len(prefix):] for line in res.stdout.splitlines()
+             if line.strip().startswith(prefix)]
+    return [n for n in names if n != "HEAD"
+            and n != own_prefix and not n.startswith(own_prefix + "-")]
+
+
+def anchor_base_branches(project_root, anchor: str, *, work_category: str,
+                         task_id: str) -> Dict[str, List[str]]:
+    """구현 기준 커밋을 tip 으로 가진 origin 브랜치와 그 커밋을 담은 브랜치."""
+    own = compute_branch_name(work_category=work_category, task_id_segment=task_id)
+    at = _origin_branches(project_root, "--points-at", anchor, own)
+    containing = [n for n in _origin_branches(project_root, "--contains", anchor, own)
+                  if n not in at]
+    return {"at": at, "containing": containing}
+
+
+def _foreign_anchor_error(*, stage: int, base_branch: str, anchor: str,
+                          branches: Dict[str, List[str]]) -> HandoffError:
+    held = branches["at"] + branches["containing"]
+    if held:
+        fix = f"re-run pr-plan with --base {held[0]}"
+    else:
+        fix = ("no origin branch holds that commit — push the branch it came "
+               f"from, or wait until it is merged into origin/{base_branch}")
+    return HandoffError(
+        f"stage {stage} would target origin/{base_branch}, but this task was "
+        f"implemented on {anchor}, which origin/{base_branch} does not contain "
+        "— the PR would also carry every commit between them, which belong to "
+        "other work. pr-plan derives stacking within this task only; a task "
+        "built on another task's unmerged branch needs that branch as its "
+        f"release base. origin branches at {anchor}: {branches['at'] or 'none'}; "
+        f"containing it: {branches['containing'] or 'none'}. {fix}")
+
+
 def _resolve_stage_base(
     *, stage: int, deps: List[int], selected: List[int], pr_covered: set,
     done: Dict[int, Dict[str, Any]], project_root, base_branch: str,
@@ -135,6 +180,13 @@ def _resolve_stage_base(
             if not is_ancestor(project_root, _done_head(done, d),
                                f"origin/{base_branch}")]
     if not live:
+        if anchor_base and not is_ancestor(project_root, anchor_base,
+                                           f"origin/{base_branch}"):
+            raise _foreign_anchor_error(
+                stage=stage, base_branch=base_branch, anchor=anchor_base,
+                branches=anchor_base_branches(
+                    project_root, anchor_base, work_category=work_category,
+                    task_id=task_id))
         commit = _run_git(["rev-parse", f"origin/{base_branch}"],
                           project_root).stdout.strip()
         return {"base_kind": "release-base", "base_branch": base_branch,

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

@@ -31,13 +31,14 @@
       `okstra handoff local-checkout --project-root <project root> --project-id <id> --task-group <g> --task-id <t> --stage <N>`
       Exit 1 means a precondition failed (MAIN worktree dirty, registry entry missing, a run still holds the stage, the target branch already deleted, or checkout failed): show the error verbatim and re-ask the action selection. On success the okstra worktree for that stage no longer exists — if the lead's cwd was inside it, EVERY subsequent step (final-report authoring included) MUST use absolute paths or run from the MAIN worktree. Then route to the final-report self-review pass.
   2. **Release base branch** (only when the user picked `push + PR`) — present these options and capture exactly one:
+     - the `Recommended release base` from the input document's `## Candidate Release Base Branches`, when that section names one — first, marked recommended
      - `preprod`
      - `main`
      - `direct input` (free-form branch name; lead validates the name exists on origin via `git ls-remote --heads origin <name>` and re-asks on failure)
-     This is the release base for the run, not necessarily each PR's base: a stage that sits on another stage targets that stage's branch. The chosen base MUST NOT be one of the stage branches. If it is, re-ask.
+     This is the release base for the run, not necessarily each PR's base: a stage that sits on another stage of this task targets that stage's branch. The release base MUST contain the task's implementation anchor base. `pr-plan` derives stacking inside this task only; when the task was built on another task's unmerged stage branch, the release base is that predecessor task's stage branch, which prepare names as the recommended base. The chosen base MUST NOT be one of this task's stage branches. If it is, re-ask.
   2p. **PR plan** (only when the user picked `push + PR`) — run
       `okstra handoff pr-plan --plan-run-root <...> --approved-plan <...> --project-root <project root> --project-id <id> --task-group <g> --task-id <t> --work-category <c> --stages <HANDOFF_STAGES> --base <chosen-base>`.
-      It returns one row per stage with `head_branch`, `head_commit`, `base_kind` (`release-base` | `stage` | `merge-base`), `base_branch` and `base_commit`. Exit 2 means the predecessors of a multi-dependency stage conflict with each other: show the `conflicts` paths and stop (route: resolve manually, then retry). Exit 1 means an eligibility or dependency violation — most often a stage whose predecessor is neither in this run nor already PR'd nor merged into the release base: show the error verbatim and re-ask the action selection. On success these rows are authoritative for every subsequent step; the lead does not recompute a base by hand.
+      It returns one row per stage with `head_branch`, `head_commit`, `base_kind` (`release-base` | `stage` | `merge-base`), `base_branch` and `base_commit`. Exit 2 means the predecessors of a multi-dependency stage conflict with each other: show the `conflicts` paths and stop (route: resolve manually, then retry). Exit 1 means an eligibility or dependency violation — most often a stage whose predecessor is neither in this run nor already PR'd nor merged into the release base: show the error verbatim and re-ask the action selection. When the error says the release base does not contain the implementation anchor, the error names the `--base` that does: show it verbatim and re-ask Q2 with that branch first. **Enforced:** `okstra_ctl.phases.release_handoff.operations._resolve_stage_base` refuses the plan. On success these rows are authoritative for every subsequent step; the lead does not recompute a base by hand.
       A `merge-base` row means `pr-plan` created a branch merging that stage's predecessors. That branch is a PR base only — it is never a PR head — and it MUST be pushed before the PR that targets it.
       The output also carries `push_plan` and `warnings`. `push_plan` is every branch the PRs sit on, already in push order (each `merge-base` first, then the stage heads in dependency order), with the `commit` it must reach and an `action` of `create` (origin does not have it), `fast-forward` (origin is behind) or `up-to-date` (origin already has that commit — do not push it). GitHub resolves a PR's head and base by name on origin, so this list, not the local branch set, is what makes the stack real. A `warnings` row means `pr-plan` fast-forwarded a local branch to origin because origin was ahead: the commits origin adds are outside what this run verified. Quote every `warnings` row verbatim in Executed Commands and say so in the branch/PR explanation — the user is deciding whether to release commits this run did not verify. `pr-plan` refuses outright when a branch moved outside okstra or diverged from origin, since only a force push could deliver it.
   2b. **Pre-merge conflict probe** (only when the user picked `push + PR`) — before pushing, for each planned stage in dependency order:

package/runtime/python/okstra_ctl/phases/release_handoff/report_assets/release-handoff-input.template.md

@@ -48,7 +48,9 @@ taskType: "{{FM_TASK_TYPE}}"
 
 ## Candidate Release Base Branches
 
-The user picks ONE release base for the whole run. Each stage's own PR base is then derived from its `depends-on` by `okstra handoff pr-plan`: a stage with no live dependency targets the release base, a stage with one targets that stage's branch (a stacked PR), and a stage with several targets a branch merging them.
+The user picks ONE release base for the whole run. Each stage's own PR base is then derived from its `depends-on` by `okstra handoff pr-plan`: a stage with no live dependency targets the release base, a stage with one targets that stage's branch (a stacked PR), and a stage with several targets a branch merging them. That derivation covers stacking inside this task only. The release base must contain the task's implementation anchor base; when this task was built on another task's unmerged stage branch, the release base is that branch, and `pr-plan` refuses a base that lacks the anchor.
+
+{{HANDOFF_ANCHOR_BASE_CANDIDATES}}
 
 - Default options offered to the user: `staging` | `preprod` | `prod` | `main` | `dev` | custom input
 - Repo-specific preference, if known (e.g. `main` is the integration branch):

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

@@ -141,7 +141,7 @@ stateDiagram-v2
 User interaction is exactly three steps.
 
 1. Q1 action: `local checkout`, `push + PR`, `skip`
-2. Q2 release base: a branch from the profile menu such as `staging`, `preprod`, `main`, or Enter directly
+2. Q2 release base: a branch from the profile menu such as `staging`, `preprod`, `main`, or Enter directly. When no default candidate contains the task's implementation anchor base (the task was built on another task's unmerged stage branch), prepare names the origin branch at the anchor as the recommended first option, and `pr-plan` refuses a release base that lacks the anchor
 3. Q3 PR title/body: every stage's draft in one question — `use as-is`, `edit then proceed`, `cancel`
 
 The merge-conflict probe happens only for `push + PR`, once per stage against that stage's own base.

package/runtime/python/okstra_ctl/process_group.py

@@ -84,6 +84,10 @@ def kill_group(pgid: int) -> bool:
         os.killpg(pgid, signal.SIGKILL)
     except ProcessLookupError:
         return False
+    except PermissionError:
+        # expected-miss: macOS 는 남은 구성원이 아직 거둬지지 않은 좀비뿐인 그룹에 EPERM 을
+        # 준다. 죽일 살아 있는 프로세스가 없다는 뜻이라, 끝난 워커의 결과를 버릴 이유가 아니다.
+        return False
     return True
 
 

package/runtime/python/okstra_ctl/report_assembly.py

@@ -18,6 +18,7 @@ from .clarification_items import (
 )
 from .final_report_schema import load_schema_version, validate
 from .report_inputs import ReportInputPath, report_input_paths, uses_report_contract_v3
+from .correction_round import correction_convergence_states, correction_round
 from .json_boundary import JsonBoundaryError, load_owned_object, serialize_owned_object
 from .report_narrative import parse_narrative, task_narrative_errors
 from .report_synthesis_packet import (
@@ -98,6 +99,32 @@ def _read_json(row: ReportInputPath) -> dict[str, Any]:
     return value
 
 
+def _correction_round_convergence(
+    initial: ReportInputPath, cross: Mapping[str, Any],
+) -> tuple[list[dict[str, Any]], list[tuple[str, Mapping[str, Any]]]]:
+    """Each correction round's re-convergence, projected like the initial one, and the
+    evidence it promotes labelled `convergence <scope>`."""
+    rows: list[dict[str, Any]] = []
+    promoted: list[tuple[str, Mapping[str, Any]]] = []
+    consensus = len(cross["consensus"])
+    differences = len(cross["differences"])
+    for scope, path in correction_convergence_states(initial.path):
+        row = ReportInputPath(initial.key, initial.owner, path)
+        try:
+            result = project_convergence(
+                _read_json(row),
+                first_consensus=consensus + 1, first_difference=differences + 1,
+            )
+        except ReportProjectionError as exc:
+            _fail(row.owner, path, "$", exc)
+        projected = result["crossVerification"]
+        consensus += len(projected["consensus"])
+        differences += len(projected["differences"])
+        rows.append({"round": correction_round(scope), **projected})
+        promoted.extend((f"convergence {scope}", item) for item in result["promotedEvidence"])
+    return rows, promoted
+
+
 def _input_map(project_root: Path, manifest: Mapping[str, Any]) -> dict[str, ReportInputPath]:
     try:
         return {row.key: row for row in report_input_paths(project_root, manifest)}
@@ -488,6 +515,11 @@ def _compose(
     data = {"schemaVersion": "3.0", **narrative, **execution}
     data["tokenUsage"] = usage
     data["crossVerification"] = convergence_data["crossVerification"]
+    rounds, round_evidence = _correction_round_convergence(
+        inputs["convergence"], data["crossVerification"]
+    )
+    if rounds:
+        data["crossVerification"]["correctionRounds"] = rounds
     data["clarificationItems"] = _clarifications(ledger, activities, inputs["approval-decisions"].path)
     # 작성자의 사실 분류와 리드 원장의 질문 연결은 양쪽 입력을 합친 뒤 검사한다.
     for reason in validate_blocked_answer_channel(data):
@@ -504,8 +536,13 @@ def _compose(
     if scope:
         data["verificationScope"] = scope
     data["agentActivity"] = activities
-    data["evidence"] = {"primary": _promoted_evidence(convergence_data)}
-    data["missingInformation"] = _census_missing_information(project_root, manifest)
+    data["evidence"] = {"primary": _promoted_evidence([
+        *(("convergence", item) for item in convergence_data["promotedEvidence"]),
+        *round_evidence,
+    ])}
+    data["missingInformation"] = _missing_information(
+        project_root, manifest, convergence_data["criticUnverified"],
+    )
     # 스냅샷 복사가 _attach_metadata 보다 먼저다 — frontmatter 가
     # selectedDirectionRef.snapshotPath 를 읽는다.
     _apply_selected_direction_snapshot(data, project_root, manifest)
@@ -529,16 +566,16 @@ def _attach_discussion(data: dict[str, Any], project_root: Path, manifest: Mappi
         _fail("discussion-record", store.records_path, "discussion", exc)
 
 
-def _census_missing_information(
-    project_root: Path, manifest: Mapping[str, Any],
+def _missing_information(
+    project_root: Path, manifest: Mapping[str, Any], critic_unverified: list[dict[str, Any]],
 ) -> list[dict[str, Any]]:
-    """Coverage-census warnings are the only rows this field carries under the
-    v3 contract, so they number from `R-001`."""
-    state = read_census_state(project_root, manifest)
-    if state is None:
-        return []
+    """Coverage-census warnings and unjudged critic gaps are the only rows this
+    field carries under the v3 contract, so they number from `R-001`."""
     _project_id, _task_group, task_id = _identity(manifest)
-    rows = census_warning_rows(state, ticket_id=task_id or "unknown")
+    ticket_id = task_id or "unknown"
+    state = read_census_state(project_root, manifest)
+    rows = [] if state is None else census_warning_rows(state, ticket_id=ticket_id)
+    rows += [{**row, "ticketId": row["ticketId"] or ticket_id} for row in critic_unverified]
     return [{"id": f"R-{index:03d}", **row} for index, row in enumerate(rows, start=1)]
 
 
@@ -717,16 +754,16 @@ def _attach_metadata(data: dict[str, Any], manifest: Mapping[str, Any]) -> None:
     }
 
 
-def _promoted_evidence(convergence: Mapping[str, Any]) -> list[dict[str, Any]]:
+def _promoted_evidence(rows: list[tuple[str, Mapping[str, Any]]]) -> list[dict[str, Any]]:
     return [
         {
             "id": f"E-{index:03d}",
             "ticketId": row["ticketId"],
             "evidence": row["evidence"],
             "sourceItems": row["sourceItems"],
-            "source": "convergence",
+            "source": source,
         }
-        for index, row in enumerate(convergence.get("promotedEvidence") or [], start=1)
+        for index, (source, row) in enumerate(rows, start=1)
     ]
 
 

package/runtime/python/okstra_ctl/report_html/common.py

@@ -403,8 +403,10 @@ def anchor_index(
         for row_id in sorted(found)
         if isinstance(row_id, str) and _anchorable(row_id)
     }
+    cross = data.get("crossVerification") if isinstance(data.get("crossVerification"), dict) else {}
+    rounds = [cross, *(r for r in cross.get("correctionRounds") or [] if isinstance(r, dict))]
     for block in ("consensus", "differences"):
-        for row in _dig(data, ("crossVerification", block)):
+        for row in (row for scope in rounds for row in scope.get(block) or []):
             row_id = row.get("id") if isinstance(row, dict) else None
             if isinstance(row_id, str) and _anchorable(row_id) and row_id not in index:
                 index[row_id] = f"id-xv-{row_id}"

package/runtime/python/okstra_ctl/report_projections.py

@@ -261,8 +261,14 @@ def _source_items(finding: Mapping[str, Any]) -> list[str]:
     return [f"{_text(worker, 'worker').removesuffix('-worker')}:{finding_id}" for worker in workers]
 
 
-def project_convergence(state: Mapping[str, Any]) -> dict[str, Any]:
-    """수렴 상태에서 독자용 합의·이견과 공개 근거만 승격한다."""
+def project_convergence(
+    state: Mapping[str, Any], *, first_consensus: int = 1, first_difference: int = 1,
+) -> dict[str, Any]:
+    """수렴 상태에서 독자용 합의·이견과 공개 근거만 승격한다.
+
+    정정 라운드 재수렴은 초기 행 다음 번호부터 매긴다 — 행 id 가 리포트 앵커라 한 리포트
+    안에서 겹치면 안 된다.
+    """
     consensus = []
     differences = []
     promoted = []
@@ -274,7 +280,7 @@ def project_convergence(state: Mapping[str, Any]) -> dict[str, Any]:
         ticket_id = _text(ticket_ids[0] if ticket_ids else "unknown", "unknown")
         if finding.get("classification") in {"full-consensus", "partial-consensus"}:
             row = {
-                "id": f"CV-{len(consensus) + 1:03d}",
+                "id": f"CV-{len(consensus) + first_consensus:03d}",
                 "ticketId": ticket_id,
                 "statement": _text(finding.get("summary"), "Converged finding"),
                 "sourceItems": _source_items(finding),
@@ -298,7 +304,7 @@ def project_convergence(state: Mapping[str, Any]) -> dict[str, Any]:
                         "position": "origin" if worker == finding.get("originWorker") else "dissent",
                     })
             differences.append({
-                "id": f"D-{len(differences) + 1:03d}",
+                "id": f"D-{len(differences) + first_difference:03d}",
                 "ticketId": ticket_id,
                 "disagreement": _text(finding.get("summary"), "Unresolved difference"),
                 "workersPosition": positions or [{"worker": "unknown", "itemId": "", "position": "unresolved"}],
@@ -311,5 +317,41 @@ def project_convergence(state: Mapping[str, Any]) -> dict[str, Any]:
             "differences": differences,
         },
         "promotedEvidence": promoted,
+        "criticUnverified": _critic_unverified(state),
     }
+    critic = (state.get("config") or {}).get("critic")
+    if isinstance(critic, Mapping):
+        result["crossVerification"]["criticGaps"] = {
+            "proposed": critic.get("gapsProposed", 0),
+            "merged": critic.get("gapsMerged", 0),
+            "unverified": critic.get("gapsUnverified", 0),
+            "duplicate": critic.get("gapsDuplicate", 0),
+        }
     return result
+
+
+def _critic_unverified(state: Mapping[str, Any]) -> list[dict[str, Any]]:
+    """미판정 gap 하나당 Missing Information 행 하나 — id 와 기본 ticket 은 조립이 채운다."""
+    ledger = (state.get("criticVerification") or {}).get("gaps") or []
+    tickets = {
+        gap.get("gapId"): (gap.get("ticketIds") or [None])[0]
+        for gap in ledger
+        if isinstance(gap, Mapping)
+    }
+    rows = []
+    for gap in state.get("unverifiedGaps") or []:
+        if not isinstance(gap, Mapping):
+            continue
+        gap_id = _text(gap.get("gapId"), "unknown")
+        rows.append({
+            "ticketId": tickets.get(gap_id),
+            "item": f"Coverage critic gap `{gap_id}` was never verified: "
+                    f"{_text(gap.get('summary'), 'no summary')}",
+            "risk": (
+                f"Verification did not complete ({_text(gap.get('reason'), 'unknown reason')}), "
+                "so no analyser has judged this gap; it is neither a finding nor a rejection."
+            ),
+            "owner": "Okstra lead",
+            "source": "critic-unverified",
+        })
+    return rows

package/runtime/python/okstra_ctl/report_synthesis_packet.py

@@ -14,6 +14,7 @@ from typing import Any, Mapping
 from okstra_token_usage.blocks import accounting_workers
 
 from .analysis_packet import reference_source_extracts
+from .correction_round import correction_convergence_states
 from .json_boundary import JsonBoundaryError, load_owned_object, write_owned_object_atomic
 from .phases.implementation_option_selection.authoring import (
     requirement_instructions as selection_requirement_instructions,
@@ -251,6 +252,17 @@ class ReportSynthesisPacket:
             ]
         if self.task_type == "implementation-planning":
             return self._planning_requirement_instructions()
+        if self.task_type == "implementation" and any(
+            source.label.startswith(f"{CONVERGENCE_STATE_LABEL} (correction-r")
+            for source in self.sources
+        ):
+            return [
+                "Each `Convergence state (correction-r<N>)` source is correction round N's "
+                "re-convergence of the verifiers' re-verification; the plain `Convergence "
+                "state` is the initial round's. Describe the stage's open findings from the "
+                "last round's re-convergence, not the initial one; report what each round "
+                "fixed through `implementation.correctionRounds`.",
+            ]
         if self.task_type != "implementation-option-selection":
             return []
         return selection_requirement_instructions(
@@ -371,6 +383,7 @@ _SOURCE_FIELDS = (
     ("Final report schema", "orchestrator", "instructionSet", "finalReportSchemaPath", True),
     ("Convergence state", "convergence", "run", "convergenceStatePath", True),
 )
+CONVERGENCE_STATE_LABEL = "Convergence state"
 
 
 _READ_CHUNK_BYTES = 16_000
@@ -514,7 +527,7 @@ def _source_markdown(
         brief = next((item.content.strip() for item in sources if item.label == "Task brief"), "")
         if len(brief.encode("utf-8")) >= _SHARED_TEXT_MIN_BYTES:
             content = content.replace(brief, 'Read the complete "Source: Task brief" above.')
-    if source.label == "Convergence state":
+    if source.label.startswith(CONVERGENCE_STATE_LABEL):
         content = _convergence_view(content)
         if content != source.content.rstrip("\n"):
             view = [
@@ -815,6 +828,14 @@ def _source_specs(
                 path = str(Path(instruction_set) / "final-report-schema.json")
         if path or required:
             specs.append((label, owner, path, required))
+        if label == CONVERGENCE_STATE_LABEL and path:
+            specs.extend(
+                (f"{CONVERGENCE_STATE_LABEL} ({scope})", owner,
+                 _relative(project_root, round_final), True)
+                for scope, round_final in correction_convergence_states(
+                    _resolve(project_root, path)
+                )
+            )
     if carried_source:
         specs.append((CARRIED_STAGES_LABEL, "orchestrator", carried_source, True))
     specs.extend(_user_response_specs(project_root, narrative_path))

package/runtime/python/okstra_ctl/run.py

@@ -3063,6 +3063,7 @@ def _write_instruction_set_sources(
             )
             if inp.clarification_response_path else ""
         ),
+        verification_target_path=ctx.get("VERIFICATION_TARGET_RELATIVE_PATH", ""),
     )
     if inp.task_type == "technical-verification":
         packet += materialize_technical_input_packet(
@@ -3370,10 +3371,11 @@ def _maybe_open_fix_cycle(inp: PrepareInputs, task_root: Path, existing: dict,
             f"{', '.join(fix_cycles.FIX_CYCLE_ENTRY_PHASES)})에서만 허용됩니다: "
             f"{inp.task_type}")
     workflow = existing.get("workflow") or {}
-    if workflow.get("lastCompletedPhase") != "release-handoff":
+    if not fix_cycles.delivery_completed(workflow):
         raise PrepareError(
-            "--fix-cycle yes 는 release-handoff 까지 완료된 task 에만 허용됩니다 "
-            "(workflow.lastCompletedPhase 확인)")
+            "--fix-cycle yes 는 release-handoff 로 전달까지 끝난 task 에만 허용됩니다 "
+            "(workflow.lastCompletedPhase 가 release-handoff 이고, skip·미전달 stage 로 "
+            "다음 phase 가 release-handoff 로 남아 있지 않아야 함)")
     brief_text = Path(inp.brief_path).read_text(encoding="utf-8")
     fix_cycles.append_opened(
         task_root, target_report=str(existing.get("latestReportRecordPath", "")),
@@ -3385,7 +3387,8 @@ def _record_fix_cycle_events(inp: PrepareInputs, ctx: dict) -> str:
     """fix-cycles.jsonl 의 lazy-close → opened → run 기록. cycle id 반환.
 
     - lazy-close: open cycle 에 release-handoff run 이 부착됐고 디스크 manifest 의
-      lastCompletedPhase 가 release-handoff 면 닫는다. manifest 는 prepare 가
+      lastCompletedPhase 가 release-handoff 면 닫는다. 다음 phase 포인터가 다시
+      release-handoff 를 가리키면(skip·미전달 stage) 닫지 않는다. manifest 는 prepare 가
       이번 run 으로 재작성하기 *전* 값이어야 하므로 finalize 직전에 호출한다.
     - opened: --fix-cycle yes 일 때만. 완료 task + entry phase 미충족이면
       PrepareError.
@@ -3398,7 +3401,7 @@ def _record_fix_cycle_events(inp: PrepareInputs, ctx: dict) -> str:
 
     open_c = fix_cycles.open_cycle(fix_cycles.read_rows(task_root))
 
-    if open_c and workflow.get("lastCompletedPhase") == "release-handoff":
+    if open_c and fix_cycles.delivery_completed(workflow):
         rows = fix_cycles.read_rows(task_root)
         handoff_attached = any(
             r.get("event") == "run" and r.get("cycle") == open_c["cycle"]

package/runtime/python/okstra_ctl/stage_reconcile.py

@@ -1,4 +1,4 @@
-"""Best-effort git reconciliation shared by stage prepare flows."""
+"""Git reconciliation shared by stage prepare flows."""
 from __future__ import annotations
 
 import sys
@@ -31,3 +31,51 @@ def auto_reconcile_best_effort(inp: Any, plan_run_root: Path) -> None:
             )
     except Exception as exc:
         print(f"git-reconcile skipped: {exc}", file=sys.stderr)
+
+
+class StaleStageRecordsError(RuntimeError):
+    """A recorded stage SHA no longer matches git and only the user can say which commit counts."""
+
+
+def require_reconciled_stages(
+    inp: Any, plan_run_root: Path, *, stage: int | None = None,
+) -> None:
+    """Apply auto items, then refuse while a confirm item remains.
+
+    A prepare that restores, rebases or merges stage branches calls this first:
+    building on a recorded commit the branch no longer carries integrates work
+    nobody verified. ``stage`` narrows the check to that stage's done row.
+    """
+    from .git_reconcile import _git, classify_task, guidance
+
+    auto_reconcile_best_effort(inp, plan_run_root)
+    # A project prepared without git (worktree status skipped-not-git) has no
+    # history the recorded SHAs could disagree with.
+    if _git(Path(inp.project_root), "rev-parse", "--git-dir").returncode != 0:
+        return
+    coordinates = dict(
+        project_id=inp.project_id,
+        task_group=inp.task_group,
+        task_id=inp.task_id,
+        work_category=inp.work_category,
+    )
+    pending = [
+        item
+        for item in classify_task(
+            project_root=Path(inp.project_root),
+            plan_run_root=plan_run_root,
+            **coordinates,
+        )
+        if item.classification == "confirm"
+        and (stage is None or item.stage == stage)
+    ]
+    if not pending:
+        return
+    lines = "\n".join(
+        f"  {f'stage {item.stage}' if item.kind == 'done' else 'anchor'}: "
+        f"{item.reason} (recorded {item.recorded})"
+        for item in pending
+    )
+    raise StaleStageRecordsError(
+        f"{lines}\n{guidance(plan_run_root=plan_run_root, **coordinates)}"
+    )

package/runtime/python/okstra_ctl/wizard/steps_plan.py

@@ -215,14 +215,14 @@ def _stage_plan_for_confirmation(
 
 
 def _fix_cycle_confirm_required(state: WizardState) -> bool:
-    """완료(release-handoff) task 에 entry phase 로 재진입하고, 아직 열린 fix
-    cycle 이 없을 때만 묻는다."""
+    """전달까지 끝난(release-handoff) task 에 entry phase 로 재진입하고, 아직
+    열린 fix cycle 이 없을 때만 묻는다."""
     if state.task_type not in fix_cycles.FIX_CYCLE_ENTRY_PHASES:
         return False
     task_root = task_dir(Path(state.project_root),
                          state.task_group, state.task_id)
     workflow = (read_task_manifest(task_root) or {}).get("workflow") or {}
-    if workflow.get("lastCompletedPhase") != "release-handoff":
+    if not fix_cycles.delivery_completed(workflow):
         return False
     return fix_cycles.open_cycle(fix_cycles.read_rows(task_root)) is None