okstra 0.52.0 → 0.53.0

package/runtime/python/okstra_ctl/run.py

@@ -88,6 +88,12 @@ APPROVED_FRONTMATTER_PATTERN = re.compile(
     re.IGNORECASE | re.MULTILINE,
 )
 
+PLAN_BODY_GATE_PATTERN = re.compile(
+    r"Gate result[^A-Za-z\n]+(?P<value>[a-z][a-z\-]+)",
+    re.IGNORECASE,
+)
+BLOCKING_PLAN_BODY_GATES = {"blocked-by-disagreement", "aborted-non-result"}
+
 # Frontmatter implementation-option matcher.
 #
 # `approved:` 바로 아래 줄의 `implementation-option:` 한 줄을 식별한다.
@@ -112,6 +118,138 @@ def _extract_frontmatter_block(body: str) -> str | None:
     return m.group(1) if m else None
 
 
+def _final_report_data_path(report_path: Path) -> Path:
+    name = report_path.name
+    if name.endswith(".md"):
+        return report_path.with_name(name[:-3] + ".data.json")
+    return report_path.with_suffix(".data.json")
+
+
+def _load_final_report_data_if_present(report_path: Path) -> tuple[Path, dict] | None:
+    data_path = _final_report_data_path(report_path)
+    if not data_path.is_file():
+        return None
+    try:
+        data = json.loads(data_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise PrepareError(
+            f"approved plan data.json is invalid JSON: {data_path}: {exc}"
+        ) from exc
+    if not isinstance(data, dict):
+        raise PrepareError(f"approved plan data.json must be a JSON object: {data_path}")
+    return data_path, data
+
+
+def _data_json_gate_result(data: dict) -> str:
+    planning = data.get("implementationPlanning")
+    if not isinstance(planning, dict):
+        return ""
+    verification = planning.get("planBodyVerification")
+    if not isinstance(verification, dict):
+        return ""
+    return str(verification.get("gateResult") or "").strip().lower()
+
+
+def _reject_blocking_plan_body_gate(path: Path, body: str, *, action: str) -> None:
+    gate_match = PLAN_BODY_GATE_PATTERN.search(body)
+    if gate_match:
+        gate_value = gate_match.group("value").strip().lower()
+        if gate_value in BLOCKING_PLAN_BODY_GATES:
+            raise PrepareError(
+                f"{action} rejected because approved plan Gate result is "
+                f"`{gate_value}`: {path}\n"
+                "  resolve the plan-body verification disagreement and regenerate "
+                "the implementation-planning report before approval."
+            )
+
+    loaded = _load_final_report_data_if_present(path)
+    if loaded is None:
+        return
+    data_path, data = loaded
+    data_gate = _data_json_gate_result(data)
+    if data_gate in BLOCKING_PLAN_BODY_GATES:
+        raise PrepareError(
+            f"{action} rejected because approved plan data.json Gate result is "
+            f"`{data_gate}`: {data_path}\n"
+            "  data.json is the final-report source of truth; regenerate the "
+            "report after resolving the verification disagreement."
+        )
+
+
+def _validate_data_json_approval_consistency(
+    path: Path,
+    *,
+    markdown_approved: bool,
+) -> None:
+    loaded = _load_final_report_data_if_present(path)
+    if loaded is None:
+        return
+    data_path, data = loaded
+    frontmatter = data.get("frontmatter")
+    if not isinstance(frontmatter, dict) or "approved" not in frontmatter:
+        raise PrepareError(
+            f"approved plan data.json has no frontmatter.approved field: {data_path}"
+        )
+    data_approved = frontmatter.get("approved")
+    if not isinstance(data_approved, bool):
+        raise PrepareError(
+            f"approved plan data.json frontmatter.approved is not boolean: {data_path}"
+        )
+    if data_approved != markdown_approved:
+        raise PrepareError(
+            "approved plan markdown frontmatter and data.json disagree on "
+            f"`approved`: markdown={str(markdown_approved).lower()}, "
+            f"data.json={str(data_approved).lower()}\n"
+            f"  markdown: {path}\n"
+            f"  data.json: {data_path}\n"
+            "  regenerate the report from data.json or use `okstra --approve` "
+            "so the source of truth is updated first."
+        )
+
+
+def _set_data_json_approved_true_if_present(path: Path) -> bool:
+    loaded = _load_final_report_data_if_present(path)
+    if loaded is None:
+        return False
+    data_path, data = loaded
+    data_gate = _data_json_gate_result(data)
+    if data_gate in BLOCKING_PLAN_BODY_GATES:
+        raise PrepareError(
+            f"--approve rejected because approved plan data.json Gate result is "
+            f"`{data_gate}`: {data_path}"
+        )
+    frontmatter = data.setdefault("frontmatter", {})
+    if not isinstance(frontmatter, dict):
+        raise PrepareError(
+            f"approved plan data.json frontmatter must be an object: {data_path}"
+        )
+    frontmatter["approved"] = True
+
+    try:
+        from .render_final_report import (
+            FinalReportRenderError,
+            find_default_template,
+            render,
+        )
+
+        rendered = render(data, template_path=find_default_template())
+    except FinalReportRenderError as exc:
+        raise PrepareError(
+            f"--approve could not re-render approved plan from data.json: {exc}"
+        ) from exc
+
+    data_tmp = data_path.with_suffix(data_path.suffix + f".tmp.{os.getpid()}")
+    md_tmp = path.with_suffix(path.suffix + f".tmp.{os.getpid()}")
+    data_tmp.write_text(
+        json.dumps(data, ensure_ascii=False, indent=2) + "\n",
+        encoding="utf-8",
+    )
+    md_tmp.write_text(rendered, encoding="utf-8")
+    data_tmp.replace(data_path)
+    md_tmp.replace(path)
+    return True
+
+
 class PrepareError(Exception):
     """surface to caller — task bundle prepare failed."""
 
@@ -195,6 +333,8 @@ def _validate_approved_plan(path: str) -> None:
             "or re-run okstra with `--approve` to flip it from the CLI.\n"
             "  resolve any `Blocks=approval` rows in `## 1. Clarification Items` first."
         )
+    _reject_blocking_plan_body_gate(p, body, action="approved plan validation")
+    _validate_data_json_approval_consistency(p, markdown_approved=True)
     # frontmatter approved == true 상태. §1 Clarification Items 의
     # Blocks=approval 행이 아직 open/answered 면 승인을 무효화한다.
     blockers = unresolved_approval_blockers(body)
@@ -235,13 +375,21 @@ def _resolve_effective_stages(
     done_stages: set,
     requested: str,
     budget: int = RUN_STEP_BUDGET,
+    started_stages: set = None,
+    reserved_stages: set = None,
 ) -> list:
     """Return the ordered list of stage numbers this run executes.
 
     `requested` is "auto" or a decimal string. For "auto" the run batches all
-    ready stages (depends-on all done, itself not done) in stage-number order up
-    to `budget` effective steps — but always at least one. A numeric request is a
-    single forced stage. Raises PrepareError on rejection cases."""
+    ready stages (depends-on all done, itself neither done nor occupied) in
+    stage-number order up to `budget` effective steps. A numeric request is a
+    single forced stage. `started_stages`/`reserved_stages` are stages a
+    concurrent run already holds (consumers.jsonl `started` and the registry
+    stage reservations); they are excluded so two simultaneous runs never pick
+    the same stage. Raises PrepareError on rejection cases."""
+    started_stages = started_stages or set()
+    reserved_stages = reserved_stages or set()
+    occupied = done_stages | started_stages | reserved_stages
     if requested != "auto":
         try:
             n = int(requested)
@@ -259,11 +407,15 @@ def _resolve_effective_stages(
             raise PrepareError(
                 f"--stage {n} already completed (consumers.jsonl status:done exists)"
             )
+        if n in started_stages or n in reserved_stages:
+            raise PrepareError(
+                f"--stage {n} already in progress or reserved by another run"
+            )
         return [n]
 
     ready = [
         s for s in stages
-        if s["stage_number"] not in done_stages
+        if s["stage_number"] not in occupied
         and all(d in done_stages for d in s["depends_on"])
     ]
     if not ready:
@@ -281,6 +433,166 @@ def _resolve_effective_stages(
     return batch
 
 
+def _commit_is_ancestor(project_root, ancestor: str, descendant: str) -> bool:
+    """True iff `ancestor` is an ancestor of `descendant` in project_root's git
+    history (`git merge-base --is-ancestor`, exit 0). Used to detect whether a
+    predecessor stage's done commit has been merged into the task worktree HEAD."""
+    r = _subprocess.run(
+        ["git", "merge-base", "--is-ancestor", ancestor, descendant],
+        cwd=str(project_root), capture_output=True, text=True,
+    )
+    return r.returncode == 0
+
+
+def _resolve_stage_base_commit(
+    stage: dict,
+    consumer_done_rows: list,
+    anchor_base_commit: str,
+    candidate_base: str = "",
+    project_root=None,
+) -> str:
+    """Pick the git base commit a stage's isolated worktree branches from.
+
+    - 독립 (`depends-on (none)`): anchor (= implementation_base_commit fixed
+      at first stage entry).
+    - 단일 의존 (`depends-on X`): predecessor X 의 `done.head_commit`.
+    - 다중 의존 (`depends-on X,Y…`): spec §9 옵션 A 자동 감지. candidate_base
+      (= task-key worktree HEAD) 에 모든 선행 done commit 이 ancestor 면
+      candidate 를 반환(사용자가 선행을 머지함). 아니면 PrepareError.
+
+    Raises PrepareError on missing predecessor / anchor / unmerged predecessor."""
+    deps = stage.get("depends_on") or []
+    if len(deps) >= 2:
+        n = stage["stage_number"]
+        # 1) 모든 선행의 done head_commit 수집
+        pred_commits = {}
+        for d in deps:
+            head = next(
+                (r.get("head_commit") for r in consumer_done_rows
+                 if r.get("stage") == d and r.get("status") == "done"
+                 and r.get("head_commit")),
+                None,
+            )
+            if not head:
+                raise PrepareError(
+                    f"predecessor stage {d} has no done row with head_commit "
+                    f"in consumers.jsonl; multi-dependency stage {n} cannot start"
+                )
+            pred_commits[d] = head
+        # 2) candidate (task-key worktree HEAD) 필요
+        if not candidate_base or project_root is None:
+            raise PrepareError(
+                f"candidate base missing for multi-dependency stage {n}; "
+                "task-key worktree HEAD could not be resolved"
+            )
+        # 3) 모든 선행 done 이 candidate 의 ancestor 인지 (=사용자가 머지함)
+        for d, head in pred_commits.items():
+            if not _commit_is_ancestor(project_root, head, candidate_base):
+                raise PrepareError(
+                    f"multi-dependency stage {n}: predecessor stage {d} "
+                    f"({head[:8]}) is not merged into the task worktree "
+                    f"({candidate_base[:8]}). Merge stage branches "
+                    f"(e.g. the `-s{d}` branches) into the task worktree "
+                    "(or into main, then refresh the worktree) and retry."
+                )
+        return candidate_base
+    if not deps:
+        if not anchor_base_commit:
+            raise PrepareError(
+                f"anchor base commit missing for independent stage "
+                f"{stage['stage_number']}; first-stage prepare should have "
+                "fixed it via worktree_registry.set_implementation_base"
+            )
+        return anchor_base_commit
+    # 단일 의존
+    pred = deps[0]
+    for row in consumer_done_rows:
+        if row.get("stage") == pred and row.get("status") == "done":
+            head = row.get("head_commit") or ""
+            if head:
+                return head
+    raise PrepareError(
+        f"predecessor stage {pred} has no done row with head_commit in "
+        "consumers.jsonl; cannot derive base for stage "
+        f"{stage['stage_number']}"
+    )
+
+
+@dataclass
+class _FVTarget:
+    scope: str            # "whole-task" | "single-stage"
+    base: str
+    head: str
+    worktree_path: str
+    stages: list          # list[int]
+    reports: list         # list[str], report_path 값(없으면 "")
+
+
+def _resolve_whole_task_target(
+    *, stage_map: list, done_rows: list, anchor_base: str,
+    task_worktree_path: str, task_head: str, task_dirty: bool,
+    merged: dict,
+) -> "_FVTarget":
+    """전체-task 검증 target. 모든 Stage Map stage 가 done + HEAD 에 머지 +
+    worktree clean 이어야 한다. 위반 시 PrepareError."""
+    done_by_stage = {r["stage"]: r for r in done_rows}
+    for s in stage_map:
+        n = s["stage_number"]
+        if n not in done_by_stage:
+            raise PrepareError(
+                f"final-verification(whole-task): stage {n} not done — "
+                f"run implementation --stage {n} first"
+            )
+        if not merged.get(n, False):
+            sha = done_by_stage[n].get("head_commit", "")
+            raise PrepareError(
+                f"final-verification(whole-task): stage {n} done commit "
+                f"{sha} not merged into task worktree HEAD — merge stage "
+                "branches then retry"
+            )
+    if task_dirty:
+        raise PrepareError(
+            "final-verification: worktree has uncommitted source changes "
+            "(outside .okstra/) — commit or stash before verifying"
+        )
+    stages = [s["stage_number"] for s in stage_map]
+    reports = [done_by_stage[n].get("report_path", "") for n in stages]
+    return _FVTarget(
+        scope="whole-task", base=anchor_base, head=task_head,
+        worktree_path=task_worktree_path, stages=stages, reports=reports,
+    )
+
+
+def _resolve_single_stage_target(
+    *, requested_stage: str, done_rows: list, stage_base: str,
+    stage_worktree_path: str, stage_head: str, stage_dirty: bool,
+) -> "_FVTarget":
+    """단독-stage 검증 target. stage N 만 done + stage worktree 존재 + clean.
+    다른 stage 의 done/머지 여부와 무관. 위반 시 PrepareError."""
+    n = int(requested_stage)
+    done_by_stage = {r["stage"]: r for r in done_rows}
+    if n not in done_by_stage:
+        raise PrepareError(
+            f"final-verification(single-stage): stage {n} not done — "
+            f"run implementation --stage {n} first"
+        )
+    if not stage_worktree_path:
+        raise PrepareError(
+            f"final-verification(single-stage): stage worktree not found for "
+            f"stage {n} (torn down?) — use whole-task mode (--stage auto)"
+        )
+    if stage_dirty:
+        raise PrepareError(
+            "final-verification: worktree has uncommitted source changes "
+            "(outside .okstra/) — commit or stash before verifying"
+        )
+    return _FVTarget(
+        scope="single-stage", base=stage_base, head=stage_head,
+        worktree_path=stage_worktree_path, stages=[n],
+        reports=[done_by_stage[n].get("report_path", "")],
+    )
+
+
 def _parse_stage_map_into_ctx(plan_path: str) -> list:
     """Reuse the validator's parser to extract StageMeta dicts for the ctx."""
     text = Path(plan_path).read_text(encoding="utf-8")
@@ -340,6 +652,7 @@ def _apply_cli_approval(path: str) -> str:
             "  expected a single line of the form `approved: false` "
             "(report-writer worker emits this by default)."
         )
+    _reject_blocking_plan_body_gate(p, body, action="--approve")
 
     audit_iso = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
     audit_line = (
@@ -347,11 +660,26 @@ def _apply_cli_approval(path: str) -> str:
         "(user CLI invocation treated as approval signal)"
     )
 
+    rendered_from_data = False
+    if m.group(1).lower() != "true":
+        rendered_from_data = _set_data_json_approved_true_if_present(p)
+        if rendered_from_data:
+            body = p.read_text(encoding="utf-8", errors="replace")
+            frontmatter = _extract_frontmatter_block(body) or ""
+            m = APPROVED_FRONTMATTER_PATTERN.search(frontmatter)
+            if not m:
+                raise PrepareError(
+                    f"--approve re-rendered the approved-plan but the markdown "
+                    f"frontmatter has no `approved:` field: {path}"
+                )
+
     if m.group(1).lower() == "true":
         if audit_line.split(" — ")[1] in body:
             return "already-approved"
         new_body = body.rstrip("\n") + "\n" + audit_line + "\n"
         p.write_text(new_body, encoding="utf-8")
+        if rendered_from_data:
+            return "frontmatter-flipped"
         return "already-approved-audit-appended"
 
     flipped_frontmatter = APPROVED_FRONTMATTER_PATTERN.sub(
@@ -698,25 +1026,44 @@ def _validate_prepare_inputs(project_root: Path, inp: PrepareInputs) -> list:
     if not inp.brief_path.is_file():
         raise PrepareError(f"task brief not found: {inp.brief_path}")
     ctx_stage_map: list = []
-    if inp.task_type == "implementation":
+    # implementation 과 final-verification 은 둘 다 승인된 plan 의 Stage Map 을
+    # 입력으로 받는다(전자는 실행 scope, 후자는 검증 scope). plan-presence +
+    # stage-map 파싱은 공유하고, frontmatter 승인/option 주입/구조 검증 같은
+    # implementation 전용 단계만 따로 게이트한다.
+    if inp.task_type in ("implementation", "final-verification"):
         if not inp.approved_plan_path:
             raise PrepareError(
-                "task-type implementation requires --approved-plan <path-to-final-report.md>"
+                f"task-type {inp.task_type} requires "
+                "--approved-plan <path-to-final-report.md>"
             )
-        if inp.approve_plan_ack:
-            # 사용자가 직접 `--approve` 를 입력한 행위 자체를 승인 의사로 모델링한다.
-            # 파일의 frontmatter approved 를 true 로 toggle 한 뒤 동일한 검증
-            # 경로(`_validate_approved_plan`) 를 그대로 통과시킨다.
-            _apply_cli_approval(inp.approved_plan_path)
-        if inp.implementation_option:
-            # 유저가 고른 Option Candidate 이름을 approved-plan frontmatter 의
-            # `implementation-option:` 라인에 기록한다. 빈 값이면 implementation 이
-            # plan 의 `Recommended Option` 으로 폴백하므로 호출하지 않는다.
-            _apply_cli_implementation_option(
-                inp.approved_plan_path, inp.implementation_option
-            )
-        _validate_approved_plan(inp.approved_plan_path)
-        _validate_stage_structure(inp.approved_plan_path)
+        if inp.task_type == "implementation":
+            if inp.approve_plan_ack:
+                # 사용자가 직접 `--approve` 를 입력한 행위 자체를 승인 의사로 모델링한다.
+                # 파일의 frontmatter approved 를 true 로 toggle 한 뒤 동일한 검증
+                # 경로(`_validate_approved_plan`) 를 그대로 통과시킨다.
+                _apply_cli_approval(inp.approved_plan_path)
+            if inp.implementation_option:
+                # 유저가 고른 Option Candidate 이름을 approved-plan frontmatter 의
+                # `implementation-option:` 라인에 기록한다. 빈 값이면 implementation 이
+                # plan 의 `Recommended Option` 으로 폴백하므로 호출하지 않는다.
+                _apply_cli_implementation_option(
+                    inp.approved_plan_path, inp.implementation_option
+                )
+            _validate_approved_plan(inp.approved_plan_path)
+            _validate_stage_structure(inp.approved_plan_path)
+        else:
+            # final-verification 에서 --approve / --implementation-option 은
+            # 의미가 없다 (승인은 implementation 진입 시 이미 끝났다).
+            if inp.approve_plan_ack:
+                raise PrepareError(
+                    "--approve is only meaningful with --task-type implementation "
+                    "and --approved-plan <path>"
+                )
+            if inp.implementation_option:
+                raise PrepareError(
+                    "--implementation-option is only meaningful with --task-type "
+                    "implementation and --approved-plan <path>"
+                )
         ctx_stage_map = _parse_stage_map_into_ctx(inp.approved_plan_path)
     else:
         if inp.approve_plan_ack:
@@ -735,8 +1082,8 @@ def _validate_prepare_inputs(project_root: Path, inp: PrepareInputs) -> list:
             )
         if inp.stage != "auto":
             raise PrepareError(
-                f"--stage is only meaningful with --task-type implementation; "
-                f"got {inp.task_type}"
+                "--stage is only meaningful with --task-type implementation or "
+                f"final-verification; got {inp.task_type}"
             )
     if inp.clarification_response_path and not Path(inp.clarification_response_path).is_file():
         raise PrepareError(
@@ -888,44 +1235,195 @@ def _resolve_model_bindings(inp: PrepareInputs, workers: list[str]) -> _ModelBin
 
 
 def _reserve_implementation_stages(inp: PrepareInputs, ctx: dict, ctx_stage_map: list) -> None:
-    """implementation run 의 ready-set 배치를 선택하고 consumers.jsonl 에 stage 별
-    `started` 행을 예약한다. ctx 에 effective_stages / STAGE_BATCH_DIRECTIVE 를 채우고
-    inp.stage 를 확정된 배치 CSV 로 덮어쓴다."""
+    """implementation run 의 첫 ready stage 를 결정하고 stage 격리 worktree 를
+    발급해 ctx 의 EXECUTOR_WORKTREE_* 를 덮어쓴다. anchor base commit 을 1회
+    고정하고 그 stage 를 consumers.jsonl 에 started 로 append.
+
+    spec §2.3: 한 run = 한 stage. `_resolve_effective_stages` 는 backward
+    compat 로 batch 리스트를 반환하지만 첫 번째만 실행한다 — stage 마다 격리
+    worktree·branch 가 필요해 batch 가 의미를 잃기 때문(cost-aware-design 의
+    run-batch 와의 의도된 트레이드오프)."""
     from .consumers import read_consumers, append_consumer
+    from . import worktree as _worktree
+    from . import worktree_registry as _reg
     import datetime as _dt
 
     ctx["parsed_stage_map"] = ctx_stage_map
     plan_run_root = Path(inp.approved_plan_path).resolve().parents[1]
     consumed = read_consumers(plan_run_root)
     done_stages = {r["stage"] for r in consumed if r.get("status") == "done"}
-    effective = _resolve_effective_stages(ctx["parsed_stage_map"], done_stages, inp.stage)
-    ctx["effective_stages"] = effective
-    csv = ",".join(str(n) for n in effective)
+    started_stages = {r["stage"] for r in consumed if r.get("status") == "started"}
+    reserved_stages = _reg.list_active_stage_numbers(
+        inp.project_id, inp.task_group, inp.task_id,
+    )
+
+    batch = _resolve_effective_stages(
+        ctx_stage_map, done_stages, inp.stage,
+        started_stages=started_stages, reserved_stages=reserved_stages,
+    )
+    # stage 격리: 한 run = 한 stage. 첫 ready stage 만 실행.
+    selected = batch[0]
+    ctx["effective_stages"] = [selected]
+    csv = str(selected)
     ctx["EFFECTIVE_STAGES"] = csv
     ctx["STAGE_BATCH_DIRECTIVE"] = (
-        f"- **Stage batch for this implementation run:** `{csv}` "
-        "(comma-separated stage numbers, ascending). Execute exactly these "
-        "Stage Map stages in this order — this is the authoritative scope. "
-        "Do NOT recompute the start stage from `consumers.jsonl`; the runtime "
-        "already selected and reserved this batch."
+        f"- **Stage for this implementation run:** `{csv}`. "
+        "Execute exactly this Stage Map stage — this is the authoritative scope. "
+        "Do NOT recompute from `consumers.jsonl`; the runtime already selected "
+        "and reserved this stage."
     )
     inp.stage = csv
     print(f"selected stages: {csv}", file=sys.stdout)
-    head_proc = _subprocess.run(
-        ["git", "rev-parse", "HEAD"],
-        cwd=inp.project_root, capture_output=True, text=True,
-    )
-    head_sha = head_proc.stdout.strip() if head_proc.returncode == 0 else ""
-    now = _dt.datetime.now(_dt.timezone.utc).isoformat()
-    for stage_n in effective:
+
+    # spec §2.1 degradation: 주변 흐름이 non-git / nested-worktree 로 skipped 면
+    # stage 격리도 동일하게 degrade — consumers 만 기록 (기존 평면 동작 보존).
+    wt_status = ctx.get("EXECUTOR_WORKTREE_STATUS", "")
+    if wt_status.startswith("skipped"):
+        head_proc = _subprocess.run(
+            ["git", "rev-parse", "HEAD"],
+            cwd=inp.project_root, capture_output=True, text=True,
+        )
+        head_sha = head_proc.stdout.strip() if head_proc.returncode == 0 else ""
+        now = _dt.datetime.now(_dt.timezone.utc).isoformat()
         append_consumer(
             plan_run_root,
             impl_task_key=ctx["TASK_KEY"],
-            stage=stage_n,
+            stage=selected,
             status="started",
             started_at=now,
             head_commit=head_sha,
         )
+        return
+
+    # anchor base commit 1회 고정 (task-key worktree HEAD 기준)
+    head_proc = _subprocess.run(
+        ["git", "rev-parse", "HEAD"],
+        cwd=inp.project_root, capture_output=True, text=True,
+    )
+    head_sha = head_proc.stdout.strip() if head_proc.returncode == 0 else ""
+    if head_sha:
+        _reg.set_implementation_base(
+            inp.project_id, inp.task_group, inp.task_id, head_sha,
+        )
+    anchor = _reg.get_implementation_base(
+        inp.project_id, inp.task_group, inp.task_id,
+    ) or ""
+
+    # stage 격리 worktree 발급 — 의존 종류별 base 결정
+    selected_stage = next(
+        s for s in ctx_stage_map if s["stage_number"] == selected
+    )
+    consumer_done_rows = [r for r in consumed if r.get("status") == "done"]
+    stage_base = _resolve_stage_base_commit(
+        selected_stage, consumer_done_rows, anchor_base_commit=anchor,
+        candidate_base=head_sha, project_root=Path(inp.project_root),
+    )
+    try:
+        provision = _worktree.provision_stage_worktree(
+            project_root=Path(inp.project_root),
+            project_id=inp.project_id,
+            task_group_segment=ctx["TASK_GROUP_SEGMENT"],
+            task_id_segment=ctx["TASK_ID_SEGMENT"],
+            work_category=inp.work_category,
+            stage_number=selected,
+            base_commit=stage_base,
+        )
+    except RuntimeError as exc:
+        raise PrepareError(f"stage worktree provisioning failed: {exc}") from exc
+
+    ctx["EXECUTOR_WORKTREE_PATH"] = provision.path
+    ctx["EXECUTOR_WORKTREE_BRANCH"] = provision.branch
+    ctx["EXECUTOR_WORKTREE_BASE_REF"] = provision.base_ref
+    ctx["EXECUTOR_WORKTREE_STATUS"] = provision.status
+    ctx["EXECUTOR_WORKTREE_NOTE"] = provision.note
+
+    # consumers append — stage worktree base 를 head_commit 으로
+    now = _dt.datetime.now(_dt.timezone.utc).isoformat()
+    append_consumer(
+        plan_run_root,
+        impl_task_key=ctx["TASK_KEY"],
+        stage=selected,
+        status="started",
+        started_at=now,
+        head_commit=provision.base_ref,
+    )
+
+
+def _git_out(cwd, *args) -> str:
+    r = _subprocess.run(["git", "-C", str(cwd), *args],
+                        capture_output=True, text=True)
+    return r.stdout.strip() if r.returncode == 0 else ""
+
+
+def _is_ancestor(cwd, commit, head) -> bool:
+    if not commit or not head:
+        return False
+    r = _subprocess.run(
+        ["git", "-C", str(cwd), "merge-base", "--is-ancestor", commit, head],
+        capture_output=True, text=True,
+    )
+    return r.returncode == 0
+
+
+def _is_dirty_excluding_okstra(cwd) -> bool:
+    out = _git_out(cwd, "status", "--short", "--", ".", ":(exclude).okstra")
+    return bool(out.strip())
+
+
+def _reserve_final_verification_target(
+    inp: "PrepareInputs", ctx: dict, ctx_stage_map: list,
+) -> None:
+    """final-verification 의 검증 target 을 registry/consumers/git 에서
+    해소하고 gate 를 강제한다. 위반 시 PrepareError. 결과를 ctx 의
+    VERIFICATION_* 키로 주입한다."""
+    from .consumers import read_consumers
+    from . import worktree_registry as _reg
+
+    plan_run_root = Path(inp.approved_plan_path).resolve().parents[1]
+    done_rows = [r for r in read_consumers(plan_run_root)
+                 if r.get("status") == "done"]
+
+    if inp.stage and inp.stage != "auto":
+        n = int(inp.stage)
+        row = _reg.get_stage_row(inp.project_id, inp.task_group, inp.task_id, n)
+        wt_path = (row or {}).get("worktree_path", "")
+        stage_base = (row or {}).get("base_ref", "")
+        head = _git_out(wt_path, "rev-parse", "HEAD") if wt_path else ""
+        target = _resolve_single_stage_target(
+            requested_stage=inp.stage, done_rows=done_rows,
+            stage_base=stage_base, stage_worktree_path=wt_path,
+            stage_head=head,
+            stage_dirty=_is_dirty_excluding_okstra(wt_path) if wt_path else False,
+        )
+        ctx["EXECUTOR_WORKTREE_PATH"] = wt_path
+    else:
+        wt_path = ctx["EXECUTOR_WORKTREE_PATH"]
+        anchor = _reg.get_implementation_base(
+            inp.project_id, inp.task_group, inp.task_id) or ""
+        head = _git_out(wt_path, "rev-parse", "HEAD")
+        merged = {r["stage"]: _is_ancestor(wt_path, r.get("head_commit", ""), head)
+                  for r in done_rows}
+        target = _resolve_whole_task_target(
+            stage_map=ctx_stage_map, done_rows=done_rows, anchor_base=anchor,
+            task_worktree_path=wt_path, task_head=head,
+            task_dirty=_is_dirty_excluding_okstra(wt_path), merged=merged,
+        )
+
+    diff_stat = _git_out(target.worktree_path, "diff", "--stat",
+                         f"{target.base}..{target.head}")
+    reports = "\n".join(
+        f"  - stage {s}: `{rp or '(report_path unrecorded)'}`"
+        for s, rp in zip(target.stages, target.reports)
+    )
+    ctx["VERIFICATION_TARGET"] = (
+        f"- **Verification scope:** `{target.scope}`\n"
+        f"- **Worktree:** `{target.worktree_path}`\n"
+        f"- **Verification base ref:** `{target.base}`\n"
+        f"- **Verification head SHA:** `{target.head}`\n"
+        f"- **Stages under verification:** {target.stages}\n"
+        f"- **Source implementation reports:**\n{reports}\n"
+        f"- **Verification diff stat:**\n```\n{diff_stat}\n```"
+    )
 
 
 def _write_instruction_set_sources(
@@ -1270,6 +1768,8 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     })
     if inp.task_type == "implementation":
         _reserve_implementation_stages(inp, ctx, ctx_stage_map)
+    elif inp.task_type == "final-verification":
+        _reserve_final_verification_target(inp, ctx, ctx_stage_map)
 
     # ---- prepare directories + cleanup ----
     _ensure_task_directories(ctx)