okstra 0.220.1 → 0.222.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

@@ -2,23 +2,48 @@
 from __future__ import annotations
 
 import argparse
+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
 
 
 _CLI_EPILOG = r"""Usage:
   okstra correction prompt --run-manifest <path> --round <N> --role <executor|verifier> \
-    --base <sha> --finding <F-id> [--finding <F-id> ...]
+    --base <sha> [--finding <F-id> ...] [--stage-base <sha>]
+  okstra correction file-size --base <stage base sha> [--head <rev>] [--repo <path>]
 
-Prints the instruction body for one correction-round prompt; pass it to
+`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. Exit 1 on a refusal.
+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
+the 400-line limit (blocking) and one `FILE-SIZE-ADVISORY:<path>:301` line per file it
+leaves over only the 300-line target, then `QA-RESULT: PASS|FAIL`; only a limit line
+fails. Exit 1 on FAIL, 2 when git cannot read the range.
 """
 
 
+def _file_size(args: argparse.Namespace) -> int:
+    try:
+        violations = file_size_violations(Path(args.repo), args.base, args.head)
+    except subprocess.CalledProcessError as exc:
+        print(f"error: git: {exc.stderr.decode(errors='replace').strip()}", file=sys.stderr)
+        return 2
+    for violation in violations:
+        print(violation.line())
+    failed = any(v.blocking for v in violations)
+    print(f"QA-RESULT: {'FAIL' if failed else 'PASS'} "
+          f"(file-size limit {FILE_LINE_LIMIT}, target {FILE_LINE_TARGET})")
+    return 1 if failed else 0
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(
         prog="okstra correction",
@@ -33,22 +58,36 @@ def main(argv: list[str] | None = None) -> int:
     prompt.add_argument("--role", choices=("executor", "verifier"), required=True)
     prompt.add_argument("--base", required=True,
                         help="the stage HEAD before this round")
-    prompt.add_argument("--finding", action="append", default=[], required=True,
+    prompt.add_argument("--finding", action="append", default=[],
                         help="a convergence finding id to fix; repeat for several")
+    prompt.add_argument("--stage-base", default="",
+                        help="the stage base commit; adds the stage diff's file-size limit findings")
+    size = commands.add_parser("file-size", help="check the stage diff against the file-size limit and target")
+    size.add_argument("--base", required=True, help="the stage base commit")
+    size.add_argument("--head", default="HEAD")
+    size.add_argument("--repo", default=".", help="the stage worktree (default: cwd)")
     args = parser.parse_args(argv)
+    if args.command == "file-size":
+        return _file_size(args)
 
     try:
         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
+        ] if args.stage_base else []
         print(correction_instruction(
             convergence_path=convergence_path, round_number=args.round, role=args.role,
-            base=args.base, finding_ids=args.finding,
+            base=args.base, finding_ids=args.finding, stage_base=args.stage_base,
+            size_violations=size_violations,
         ))
+    except subprocess.CalledProcessError as exc:
+        print(f"error: git: {exc.stderr.decode(errors='replace').strip()}", file=sys.stderr)
+        return 1
     except (CorrectionRoundError, OSError, ValueError) as exc:
         print(f"error: {exc}", file=sys.stderr)
         return 1

package/runtime/python/okstra_ctl/correction_round.py

@@ -14,6 +14,7 @@ from pathlib import Path
 from typing import Mapping, Sequence
 
 from .execution_identity import ExecutionManifest
+from .file_size_cap import FILE_LINE_LIMIT, FileSizeViolation
 from .json_boundary import load_owned_object
 
 MAX_CORRECTION_ROUNDS = 2
@@ -31,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:
@@ -101,17 +142,11 @@ def _finding_lines(findings: Sequence[Mapping[str, object]]) -> list[str]:
     return lines
 
 
-def correction_instruction(
-    *, convergence_path: Path, round_number: int, role: str, base: str,
-    finding_ids: Sequence[str],
-) -> str:
-    """The instruction body one correction-round prompt carries, read from the convergence record."""
-    if not 1 <= round_number <= MAX_CORRECTION_ROUNDS:
-        raise CorrectionRoundError(f"--round must be 1..{MAX_CORRECTION_ROUNDS}")
+def _convergence_findings(
+    convergence_path: Path, finding_ids: Sequence[str],
+) -> list[Mapping[str, object]]:
     if not finding_ids:
-        raise CorrectionRoundError("name at least one --finding")
-    if not base.strip():
-        raise CorrectionRoundError("--base is required: the stage HEAD before this round")
+        return []
     record = load_owned_object(convergence_path, artifact="convergence record")
     by_id = {
         str(row.get("findingId")): row for row in record.get("findings") or []
@@ -123,14 +158,40 @@ def correction_instruction(
             f"findings not in {convergence_path.name}: {', '.join(missing)}; "
             f"it holds {', '.join(sorted(by_id)) or 'none'}"
         )
-    findings = [by_id[fid] for fid in finding_ids]
+    return [by_id[fid] for fid in finding_ids]
+
+
+def correction_instruction(
+    *, convergence_path: Path, round_number: int, role: str, base: str,
+    finding_ids: Sequence[str], stage_base: str = "",
+    size_violations: Sequence[FileSizeViolation] = (),
+) -> str:
+    """The instruction body one correction-round prompt carries.
+
+    Verifier findings are read from the convergence record. File-size findings come from
+    `file_size_cap.file_size_violations` over `stage_base..base`, so they need no verifier
+    to have reported them.
+    """
+    if not 1 <= round_number <= MAX_CORRECTION_ROUNDS:
+        raise CorrectionRoundError(f"--round must be 1..{MAX_CORRECTION_ROUNDS}")
+    if not finding_ids and not size_violations:
+        raise CorrectionRoundError(
+            "name at least one --finding, or pass --stage-base for a stage whose diff "
+            "breaks the 400-line file-size limit"
+        )
+    if not base.strip():
+        raise CorrectionRoundError("--base is required: the stage HEAD before this round")
+    findings = _convergence_findings(convergence_path, finding_ids)
     results_dir = convergence_path.parent.parent / "worker-results"
+    stage_base_ref = stage_base.strip() or "<the stage base>"
     header = [
         f"- Convergence record: `{convergence_path}`",
         f"- Verifier results (each finding's suggested fix): `{results_dir}`",
         f"- Stage HEAD before this round: `{base.strip()}`",
+        *([f"- Stage base (file-size limit): `{stage_base.strip()}`"] if stage_base.strip() else []),
         "- Findings:",
         *("  " + line for line in _finding_lines(findings)),
+        *(f"  - `{v.finding_id}` (file-size limit; okstra): {v.line()}" for v in size_violations),
         "",
     ]
     if role == "executor":
@@ -144,6 +205,11 @@ def correction_instruction(
             "dependency, or a schema or migration change is not fixed here: stop and say so.",
             "- Update a test's expected value only where the finding shows the oracle itself is "
             "wrong; never weaken or delete an assertion to make a test pass.",
+            f"- A `FILE-SIZE:` finding is fixed by moving whole responsibilities (a group of "
+            f"functions, a class, a `describe` block) into new files beside the oversized one; "
+            f"those files count as inside this stage. Never compress code or drop comments to "
+            f"meet the number. Done when `okstra correction file-size --base {stage_base_ref}` "
+            f"prints `QA-RESULT: PASS` (limit {FILE_LINE_LIMIT} lines; aim for 300).",
             "- Follow the executor sidecar's TDD, pre-commit diff review and self-check, and "
             "commit with a Conventional Commit whose body names the finding ids.",
             "- Re-run the plan validation commands that cover the fix, and end with a "
@@ -161,6 +227,9 @@ def correction_instruction(
             "the stage was reviewed in the initial round.",
             "- Re-run every plan validation command, as the verifier sidecar's Fix-run "
             "incremental scope requires.",
+            f"- Run `okstra correction file-size --base {stage_base_ref}` against the stage base, "
+            "not this round's base: each `FILE-SIZE:` line it prints is a blocking finding, and each "
+            "`FILE-SIZE-ADVISORY:` line a recommendation.",
             "- Verdict `PASS` when every finding is fixed and no blocking check hits the "
             "correction diff; otherwise `FAIL`, with each remaining or new finding in the "
             "usual format.",

package/runtime/python/okstra_ctl/domain/mcp.py

@@ -0,0 +1,43 @@
+"""provider 어댑터와 핵심 판정이 함께 쓰는 벤더 중립 MCP 목록 값."""
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Literal
+
+McpServerState = Literal["enabled", "disabled", "needs-auth"]
+
+
+@dataclass(frozen=True)
+class VisibleMcpServer:
+    name: str
+    state: McpServerState
+
+
+@dataclass(frozen=True)
+class McpInventory:
+    """``listed`` 가 False 면 목록 자체를 못 얻은 것이라 선언 서버를 ``missing``
+    이 아니라 ``unknown`` 으로 판정한다."""
+
+    listed: bool
+    servers: tuple[VisibleMcpServer, ...] = ()
+    note: str = ""
+
+    @classmethod
+    def unavailable(cls, note: str) -> McpInventory:
+        return cls(listed=False, note=note)
+
+
+McpInventoryParser = Callable[[str], McpInventory]
+
+
+@dataclass(frozen=True)
+class McpInventoryProbe:
+    """추론 호출 없이 MCP 서버를 나열하는 명령과 그 출력 파서.
+
+    실행은 어댑터가 아니라 핵심 코드가 맡아 모든 provider 에 같은 타임아웃과
+    cwd(프로젝트 루트)를 적용한다.
+    """
+
+    argv: tuple[str, ...]
+    parse: McpInventoryParser

package/runtime/python/okstra_ctl/domain/provider.py

@@ -5,6 +5,7 @@ from collections.abc import Callable
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Literal, Mapping, Optional, Protocol
 
+from .mcp import McpInventoryProbe
 from .role import RoleCatalogError, normalize_role, ROLE_CATALOG
 from .worker_exec import WorkerWriteCapability
 
@@ -195,6 +196,7 @@ class ProviderSpec:
     exec_strategy: Optional["ExecutionStrategy"] = None
     execution_normalizer: Optional[ExecutionNormalizer] = None
     served_model_normalizer: ServedModelNormalizer = unavailable_served_model
+    mcp_inventory: Optional[McpInventoryProbe] = None
     _legacy_role_restriction: frozenset[str] = field(
         init=False,
         repr=False,