okstra 0.220.1 → 0.222.0

package/runtime/python/okstra_ctl/mcp_cli.py

@@ -0,0 +1,179 @@
+"""`okstra mcp` — declare project MCP servers and check provider reachability."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from okstra_project import resolve_project_root
+from okstra_project.resolver import ResolverError
+
+from .json_boundary import JsonBoundaryError
+from .mcp_servers import (
+    McpDeclarationError,
+    assess,
+    brief_source_warnings,
+    load_declarations,
+    parse_declaration,
+    probe_inventories,
+    provider_probes,
+    reachability_sentence,
+    remove_declaration,
+    upsert_declaration,
+)
+
+_CLI_EPILOG = r"""Usage:
+  okstra mcp list [--json] [--cwd <dir>]
+  okstra mcp add --name <name> --description <text> --tool <tool>... [--alias <name>...] [--notes <text>] [--cwd <dir>]
+  okstra mcp remove --name <name> [--cwd <dir>]
+  okstra mcp check [--provider <id>...] [--brief <path>] [--json] [--cwd <dir>]
+
+Declarations live in .okstra/project.json `mcpServers`. `--alias` names the
+server as a provider CLI lists it (for example `figma-desktop`). `check` runs
+each provider adapter's MCP listing command; it never sends an inference call.
+Add a missing server through that provider CLI's own MCP configuration.
+"""
+
+
+def _project_root(cwd: str) -> Path:
+    return resolve_project_root(cwd=str(Path(cwd).resolve()))
+
+
+def _list(root: Path, as_json: bool) -> int:
+    declarations, problems = load_declarations(root)
+    if as_json:
+        print(json.dumps({
+            "servers": [d.to_json() for d in declarations],
+            "problems": list(problems),
+        }, ensure_ascii=False, indent=2))
+        return 1 if problems else 0
+    if not declarations:
+        print("No MCP servers declared.")
+    for declaration in declarations:
+        aliases = f" (aliases: {', '.join(declaration.aliases)})" if declaration.aliases else ""
+        print(f"{declaration.name}{aliases}: {declaration.description}")
+        print(f"  tools: {', '.join(declaration.tools)}")
+        if declaration.notes:
+            print(f"  notes: {declaration.notes}")
+    for problem in problems:
+        print(f"invalid: {problem}")
+    return 1 if problems else 0
+
+
+def _add(root: Path, args: argparse.Namespace) -> int:
+    raw = {
+        "name": args.name,
+        "description": args.description,
+        "tools": args.tool or [],
+    }
+    if args.alias:
+        raw["aliases"] = args.alias
+    if args.notes:
+        raw["notes"] = args.notes
+    declaration, errors = parse_declaration(raw)
+    if declaration is None:
+        print("error: " + "; ".join(errors))
+        return 1
+    replaced = upsert_declaration(root, declaration)
+    print(f"{'Replaced' if replaced else 'Added'} MCP server `{declaration.name}`.")
+    print("Run `okstra mcp check` to see which providers can reach it.")
+    return 0
+
+
+def _remove(root: Path, name: str) -> int:
+    if not remove_declaration(root, name):
+        print(f"error: no MCP server named `{name}` is declared")
+        return 1
+    print(f"Removed MCP server `{name}`.")
+    return 0
+
+
+def _check(root: Path, providers: list[str], brief: str, as_json: bool) -> int:
+    from .registry.provider_registry import default_provider_registry
+
+    declarations, problems = load_declarations(root)
+    provider_ids = providers or list(default_provider_registry().ids())
+    rows = assess(declarations, probe_inventories(provider_probes(provider_ids), root))
+    brief_warnings = (
+        brief_source_warnings(Path(brief).read_text(encoding="utf-8"), declarations, rows)
+        if brief else ()
+    )
+    if as_json:
+        print(json.dumps({
+            "servers": [
+                {
+                    "name": row.server.name,
+                    "providers": [
+                        {
+                            "provider": cell.provider_id,
+                            "status": cell.status,
+                            "visibleName": cell.visible_name,
+                            "note": cell.note,
+                        }
+                        for cell in row.cells
+                    ],
+                }
+                for row in rows
+            ],
+            "problems": list(problems),
+            "briefWarnings": list(brief_warnings),
+        }, ensure_ascii=False, indent=2))
+        return 0
+    if not declarations:
+        print("No MCP servers declared. Register one with `okstra mcp add`.")
+    for row in rows:
+        print(f"{row.server.name}: {reachability_sentence(row)}")
+        for cell in row.cells:
+            if cell.note and cell.status != "missing":
+                print(f"  {cell.provider_id}: {cell.note}")
+    for problem in problems:
+        print(f"invalid: {problem}")
+    for warning in brief_warnings:
+        print(warning)
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Declare project MCP servers and check provider reachability.",
+        epilog=_CLI_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        prog="okstra mcp",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+    listed = sub.add_parser("list")
+    listed.add_argument("--json", action="store_true")
+    listed.add_argument("--cwd", default=".")
+    add = sub.add_parser("add")
+    add.add_argument("--name", required=True)
+    add.add_argument("--description", required=True)
+    add.add_argument("--tool", action="append")
+    add.add_argument("--alias", action="append")
+    add.add_argument("--notes", default="")
+    add.add_argument("--cwd", default=".")
+    remove = sub.add_parser("remove")
+    remove.add_argument("--name", required=True)
+    remove.add_argument("--cwd", default=".")
+    check = sub.add_parser("check")
+    check.add_argument("--provider", action="append", default=[])
+    check.add_argument("--brief", default="")
+    check.add_argument("--json", action="store_true")
+    check.add_argument("--cwd", default=".")
+    args = parser.parse_args(argv)
+    try:
+        root = _project_root(args.cwd)
+        if args.command == "list":
+            return _list(root, args.json)
+        if args.command == "add":
+            return _add(root, args)
+        if args.command == "remove":
+            return _remove(root, args.name)
+        return _check(root, args.provider, args.brief, args.json)
+    except (McpDeclarationError, JsonBoundaryError, ResolverError, OSError, ValueError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/runtime/python/okstra_ctl/mcp_servers.py

@@ -0,0 +1,421 @@
+"""프로젝트 MCP 서버 선언과 provider 별 도달성 판정.
+
+선언은 논리 서버 이름과, provider CLI 가 그 서버를 나열하는 이름(`aliases`)만
+갖는다. 어느 provider 가 볼 수 있는지는 각 어댑터의 `mcp_inventory` 가 답하며,
+이 모듈은 provider 이름을 하나도 모른다.
+"""
+from __future__ import annotations
+
+import re
+import subprocess
+from collections.abc import Callable, Iterable, Mapping, Sequence
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Literal
+
+from okstra_project.dirs import OKSTRA_DIR_NAME, project_json_path
+
+from .domain.mcp import McpInventory, McpInventoryProbe
+from .json_boundary import JsonBoundaryError, load_owned_object, write_owned_object_atomic
+
+PROBE_TIMEOUT_SECONDS = 20.0
+
+Reachability = Literal["reachable", "disabled", "missing", "unknown"]
+
+
+class McpDeclarationError(ValueError):
+    pass
+
+
+@dataclass(frozen=True)
+class McpServerDeclaration:
+    name: str
+    description: str
+    tools: tuple[str, ...]
+    aliases: tuple[str, ...] = ()
+    notes: str = ""
+
+    def to_json(self) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "name": self.name,
+            "description": self.description,
+            "tools": list(self.tools),
+        }
+        if self.aliases:
+            payload["aliases"] = list(self.aliases)
+        if self.notes:
+            payload["notes"] = self.notes
+        return payload
+
+
+@dataclass(frozen=True)
+class ProviderCell:
+    provider_id: str
+    status: Reachability
+    visible_name: str = ""
+    note: str = ""
+
+
+@dataclass(frozen=True)
+class ServerReachability:
+    server: McpServerDeclaration
+    cells: tuple[ProviderCell, ...]
+
+    def reachable_from(self) -> tuple[str, ...]:
+        return tuple(c.provider_id for c in self.cells if c.status == "reachable")
+
+
+def _string_list(value: object, field: str, errors: list[str]) -> tuple[str, ...]:
+    if not isinstance(value, list) or not all(
+        isinstance(item, str) and item.strip() for item in value
+    ):
+        errors.append(f"`{field}` must be a list of non-empty strings")
+        return ()
+    return tuple(item.strip() for item in value)
+
+
+def parse_declaration(raw: object) -> tuple[McpServerDeclaration | None, list[str]]:
+    if not isinstance(raw, dict):
+        return None, ["entry must be an object"]
+    errors: list[str] = []
+    name = raw.get("name")
+    if not isinstance(name, str) or not name.strip():
+        errors.append("`name` must be a non-empty string")
+    description = raw.get("description")
+    if not isinstance(description, str) or not description.strip():
+        errors.append("`description` must be a non-empty string")
+    tools = _string_list(raw.get("tools"), "tools", errors)
+    if raw.get("tools") == []:
+        errors.append("`tools` must not be empty")
+    aliases = _string_list(raw["aliases"], "aliases", errors) if "aliases" in raw else ()
+    notes = raw.get("notes", "")
+    if not isinstance(notes, str):
+        errors.append("`notes` must be a string")
+    if errors:
+        return None, errors
+    return (
+        McpServerDeclaration(
+            name=name.strip(),
+            description=description.strip(),
+            tools=tools,
+            aliases=aliases,
+            notes=notes.strip(),
+        ),
+        [],
+    )
+
+
+def load_declarations(
+    project_root: Path,
+) -> tuple[tuple[McpServerDeclaration, ...], tuple[str, ...]]:
+    path = project_json_path(project_root)
+    if not path.is_file():
+        return (), ()
+    try:
+        raw = load_owned_object(path, artifact="project config")
+    except JsonBoundaryError as exc:
+        return (), (str(exc),)
+    servers = raw.get("mcpServers")
+    if servers is None:
+        return (), ()
+    if not isinstance(servers, list):
+        return (), (f"`mcpServers` in {path} must be a list",)
+    declarations: list[McpServerDeclaration] = []
+    problems: list[str] = []
+    seen: set[str] = set()
+    for index, entry in enumerate(servers):
+        declaration, errors = parse_declaration(entry)
+        if declaration is None:
+            problems.append(f"mcpServers[{index}]: " + "; ".join(errors))
+            continue
+        if declaration.name in seen:
+            problems.append(f"mcpServers[{index}]: duplicate name `{declaration.name}`")
+            continue
+        seen.add(declaration.name)
+        declarations.append(declaration)
+    return tuple(declarations), tuple(problems)
+
+
+def _read_project_config(project_root: Path) -> tuple[Path, dict[str, Any]]:
+    path = project_json_path(project_root)
+    if not path.is_file():
+        raise McpDeclarationError(
+            f"{path} not found; register the project with `okstra setup` first"
+        )
+    return path, load_owned_object(path, artifact="project config")
+
+
+def upsert_declaration(project_root: Path, declaration: McpServerDeclaration) -> bool:
+    path, data = _read_project_config(project_root)
+    servers = data.get("mcpServers") or []
+    if not isinstance(servers, list):
+        raise McpDeclarationError(f"`mcpServers` in {path} must be a list")
+    kept = [
+        entry for entry in servers
+        if not (isinstance(entry, dict) and entry.get("name") == declaration.name)
+    ]
+    replaced = len(kept) != len(servers)
+    data["mcpServers"] = [*kept, declaration.to_json()]
+    write_owned_object_atomic(path, data, artifact="project config")
+    return replaced
+
+
+def remove_declaration(project_root: Path, name: str) -> bool:
+    path, data = _read_project_config(project_root)
+    servers = data.get("mcpServers") or []
+    if not isinstance(servers, list):
+        raise McpDeclarationError(f"`mcpServers` in {path} must be a list")
+    kept = [
+        entry for entry in servers
+        if not (isinstance(entry, dict) and entry.get("name") == name)
+    ]
+    if len(kept) == len(servers):
+        return False
+    data["mcpServers"] = kept
+    write_owned_object_atomic(path, data, artifact="project config")
+    return True
+
+
+def normalize_server_name(name: str) -> str:
+    return re.sub(r"[\s._-]+", "", name).lower()
+
+
+def _match(
+    declaration: McpServerDeclaration, inventory: McpInventory,
+) -> tuple[Reachability, str]:
+    if not inventory.listed:
+        return "unknown", ""
+    wanted = {normalize_server_name(n) for n in (declaration.name, *declaration.aliases)}
+    found = [s for s in inventory.servers if normalize_server_name(s.name) in wanted]
+    for server in found:
+        if server.state == "enabled":
+            return "reachable", server.name
+    if found:
+        return "disabled", found[0].name
+    return "missing", ""
+
+
+@dataclass(frozen=True)
+class CommandOutcome:
+    stdout: str | None
+    failure: str = ""
+
+
+CommandRunner = Callable[[tuple[str, ...], Path], CommandOutcome]
+
+
+def run_command(argv: tuple[str, ...], project_root: Path) -> CommandOutcome:
+    command = " ".join(argv)
+    try:
+        completed = subprocess.run(
+            list(argv),
+            cwd=project_root,
+            capture_output=True,
+            text=True,
+            timeout=PROBE_TIMEOUT_SECONDS,
+            check=False,
+        )
+    except FileNotFoundError:
+        return CommandOutcome(None, f"`{argv[0]}` is not installed")
+    except subprocess.TimeoutExpired:
+        return CommandOutcome(None, f"`{command}` timed out after {PROBE_TIMEOUT_SECONDS:.0f}s")
+    except OSError as exc:
+        return CommandOutcome(None, f"`{command}` failed to start ({exc})")
+    if completed.returncode != 0:
+        return CommandOutcome(None, f"`{command}` exited {completed.returncode}")
+    return CommandOutcome(completed.stdout)
+
+
+def probe_inventories(
+    probes: Mapping[str, McpInventoryProbe | None],
+    project_root: Path,
+    runner: CommandRunner | None = None,
+) -> dict[str, McpInventory]:
+    """같은 명령은 한 번만 실행한다. claude 와 zai 처럼 CLI 를 공유하는 어댑터가
+    목록 비용(실측 7.5초)을 두 번 치르지 않게 하려는 것이다."""
+    commands = {probe.argv for probe in probes.values() if probe is not None}
+    outcomes: dict[tuple[str, ...], CommandOutcome] = {}
+    if commands:
+        with ThreadPoolExecutor(max_workers=len(commands)) as pool:
+            futures = {
+                argv: pool.submit(runner or run_command, argv, project_root)
+                for argv in commands
+            }
+            outcomes = {argv: future.result() for argv, future in futures.items()}
+    inventories: dict[str, McpInventory] = {}
+    for provider_id, probe in probes.items():
+        if probe is None:
+            inventories[provider_id] = McpInventory.unavailable(
+                "adapter declares no MCP inventory probe"
+            )
+            continue
+        outcome = outcomes[probe.argv]
+        inventories[provider_id] = (
+            probe.parse(outcome.stdout)
+            if outcome.stdout is not None
+            else McpInventory.unavailable(outcome.failure)
+        )
+    return inventories
+
+
+def assess(
+    declarations: Sequence[McpServerDeclaration],
+    inventories: Mapping[str, McpInventory],
+) -> tuple[ServerReachability, ...]:
+    rows: list[ServerReachability] = []
+    for declaration in declarations:
+        cells = []
+        for provider_id, inventory in inventories.items():
+            status, visible = _match(declaration, inventory)
+            cells.append(ProviderCell(provider_id, status, visible, inventory.note))
+        rows.append(ServerReachability(declaration, tuple(cells)))
+    return tuple(rows)
+
+
+def provider_probes(provider_ids: Iterable[str]) -> dict[str, McpInventoryProbe | None]:
+    from .registry.provider_registry import default_provider_registry
+
+    registry = default_provider_registry()
+    return {
+        provider_id: registry.resolve(provider_id).mcp_inventory
+        for provider_id in dict.fromkeys(provider_ids)
+    }
+
+
+def _cell_text(cell: ProviderCell) -> str:
+    if cell.status == "reachable":
+        return f"{cell.provider_id} (as `{cell.visible_name}`)"
+    if cell.status == "disabled":
+        return f"{cell.provider_id} (disabled as `{cell.visible_name}`)"
+    return f"{cell.provider_id} ({cell.status})"
+
+
+def reachability_sentence(row: ServerReachability) -> str:
+    reachable = [c for c in row.cells if c.status == "reachable"]
+    other = [c for c in row.cells if c.status != "reachable"]
+    parts = []
+    if reachable:
+        parts.append("Reachable from: " + ", ".join(_cell_text(c) for c in reachable))
+    if other:
+        parts.append("Not reachable: " + ", ".join(_cell_text(c) for c in other))
+    return ". ".join(parts)
+
+
+def reachability_warnings(rows: Sequence[ServerReachability]) -> tuple[str, ...]:
+    warnings = []
+    for row in rows:
+        for cell in row.cells:
+            if cell.status == "reachable":
+                continue
+            detail = _cell_text(cell)
+            if cell.note:
+                detail += f": {cell.note}"
+            warnings.append(
+                f"mcp: server `{row.server.name}` is not reachable from provider {detail}"
+            )
+    return tuple(warnings)
+
+
+NO_MCP_SERVERS_LINE = (
+    f"- No MCP servers are declared in `{OKSTRA_DIR_NAME}/project.json`'s "
+    "`mcpServers` array. Treat MCP tools as unavailable for this run. To enable "
+    "them, register each server with `okstra mcp add` and re-render the bundle."
+)
+
+
+def render_block(
+    declarations: Sequence[McpServerDeclaration],
+    rows: Sequence[ServerReachability] = (),
+) -> str:
+    """툴 이름은 논리 이름으로만 싣는다. 실제 호출 이름은 CLI 마다 규칙이 달라
+    워커가 자기 CLI 의 툴 목록에서 찾는다."""
+    if not declarations:
+        return NO_MCP_SERVERS_LINE
+    by_name = {row.server.name: row for row in rows}
+    lines = []
+    for declaration in declarations:
+        parts = [f"`{declaration.name}`"]
+        if declaration.aliases:
+            parts[0] += " (also listed as " + ", ".join(
+                f"`{alias}`" for alias in declaration.aliases
+            ) + ")"
+        parts.append(declaration.description)
+        parts.append("Tools: " + ", ".join(f"`{tool}`" for tool in declaration.tools))
+        if declaration.notes:
+            parts.append(declaration.notes)
+        row = by_name.get(declaration.name)
+        if row is not None and row.cells:
+            parts.append(reachability_sentence(row))
+        lines.append("- " + ". ".join(p.rstrip(".") for p in parts) + ".")
+    return "\n".join(lines)
+
+
+@dataclass(frozen=True)
+class BriefSource:
+    label: str
+    pattern: re.Pattern[str]
+    keyword: str
+
+
+BRIEF_SOURCES = (
+    BriefSource(
+        "Figma",
+        re.compile(r"figma\.com/(?:file|design|proto|board)/", re.IGNORECASE),
+        "figma",
+    ),
+)
+
+
+def brief_source_warnings(
+    brief_text: str,
+    declarations: Sequence[McpServerDeclaration],
+    rows: Sequence[ServerReachability] = (),
+) -> tuple[str, ...]:
+    warnings = []
+    for source in BRIEF_SOURCES:
+        if not source.pattern.search(brief_text):
+            continue
+        matching = [
+            d for d in declarations
+            if any(source.keyword in normalize_server_name(n) for n in (d.name, *d.aliases))
+        ]
+        if not matching:
+            warnings.append(
+                f"mcp: brief cites a {source.label} URL but no mcpServers entry matches "
+                f"'{source.keyword}'; register it with `okstra mcp add`"
+            )
+            continue
+        names = {d.name for d in matching}
+        checked = [row for row in rows if row.server.name in names]
+        if checked and not any(row.reachable_from() for row in checked):
+            warnings.append(
+                f"mcp: brief cites a {source.label} URL but no selected provider can "
+                f"reach {', '.join(sorted(names))}; add it to a provider CLI's MCP "
+                "configuration or select a provider that lists it"
+            )
+    return tuple(warnings)
+
+
+@dataclass(frozen=True)
+class PreparedMcp:
+    block: str
+    warnings: tuple[str, ...]
+
+
+def prepare_mcp(
+    project_root: Path,
+    provider_ids: Iterable[str],
+    brief_text: str,
+    runner: CommandRunner | None = None,
+) -> PreparedMcp:
+    """판정 결과는 경고와 렌더에만 쓰고 run 을 거절하지 않는다."""
+    declarations, problems = load_declarations(project_root)
+    warnings = [f"mcp: {problem}" for problem in problems]
+    rows: tuple[ServerReachability, ...] = ()
+    if declarations:
+        inventories = probe_inventories(provider_probes(provider_ids), project_root, runner)
+        rows = assess(declarations, inventories)
+        warnings.extend(reachability_warnings(rows))
+    warnings.extend(brief_source_warnings(brief_text, declarations, rows))
+    return PreparedMcp(render_block(declarations, rows), tuple(warnings))

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