okstra 0.206.0 → 0.207.0

package/runtime/python/okstra_ctl/agent/prompt_cli/batch.py

@@ -0,0 +1,183 @@
+"""dispatch 배치 하나를 한 번의 호출로 materialize 하고, 원하면 jobs 파일까지 쓴다.
+
+항목마다 단일 `materialize` 호출과 같은 파서와 `_materialize` 를 거치므로, 항목은
+그 호출이 낼 오류와 똑같이 실패한다. 여기에는 반복과 jobs 넘기기만 있다.
+"""
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+from typing import Callable
+
+from ..invocation import AgentInvocationError
+from ...dispatch_state import DispatchError
+from ...json_boundary import JsonBoundaryError, load_owned_object
+from ...worker_prompt_headers import WorkerPromptHeaderError
+from .emit import _prepared_payload
+from .inputs import AgentPromptCliError, _project_input, _project_root
+from .jobs import check_jobs_target, generate_jobs
+from .materialize import _materialize
+
+
+_ENTRY_FAILURES = (
+    AgentPromptCliError, AgentInvocationError, DispatchError,
+    WorkerPromptHeaderError, OSError, ValueError,
+)
+_REQUIRED_FLAGS = ("invocation-id", "audience", "instruction", "prompt")
+_STANDALONE_FLAGS = frozenset({
+    "host-runtime", "terminal-backend", "provider", "model-role", "model", "purpose",
+})
+_ENTRY_FLAGS = frozenset({
+    "invocation-id", "audience", "instruction", "prompt", "worker-id",
+    "dispatch-kind", "assignment-ref", "source-role-execution-ref", "result",
+    "corrections", "audit-source", "replace-undispatched",
+})
+
+
+def materialize_batch(
+    args: argparse.Namespace,
+    parser_factory: Callable[[], argparse.ArgumentParser],
+) -> dict[str, object]:
+    entries, dispatch_kind = _validated_batch(args, parser_factory)
+    prepared = _publish(entries)
+    jobs_path = write_jobs(args, prepared, dispatch_kind) if args.jobs_out else None
+    return {"ok": True, "invocations": prepared, "jobsPath": jobs_path}
+
+
+def _validated_batch(
+    args: argparse.Namespace,
+    parser_factory: Callable[[], argparse.ArgumentParser],
+) -> tuple[list[argparse.Namespace], str]:
+    """배치 전체를 발행 전에 검사한다 — 어느 항목도 쓰기 전에 거부할 수 있는 것은 전부 여기서."""
+    if not args.run_manifest:
+        raise AgentPromptCliError("materialize --batch requires --run-manifest")
+    stray = sorted(
+        "--" + flag for flag in _ENTRY_FLAGS | _STANDALONE_FLAGS
+        if getattr(args, flag.replace("-", "_"))
+    )
+    if stray:
+        raise AgentPromptCliError(
+            "with --batch pass only --project-root, --run-manifest, --jobs-out "
+            "and --json; per-invocation flags belong in the batch entries: "
+            + ", ".join(stray)
+        )
+    project = _project_root(args.project_root)
+    entries = [
+        _entry_args(args, index, entry, parser_factory)
+        for index, entry in enumerate(_load_entries(project, args.batch), start=1)
+    ]
+    ids = [entry.invocation_id for entry in entries]
+    if len(set(ids)) != len(ids):
+        raise AgentPromptCliError("batch repeats an invocation id")
+    kinds = {entry.dispatch_kind for entry in entries}
+    if args.jobs_out and len(kinds) != 1:
+        raise AgentPromptCliError(
+            "--jobs-out needs one dispatch kind; this batch has "
+            + ", ".join(sorted(str(kind) for kind in kinds))
+        )
+    if args.jobs_out:
+        check_jobs_target(args.project_root, args.run_manifest, args.jobs_out)
+    return entries, next(iter(kinds))
+
+
+def _publish(entries: list[argparse.Namespace]) -> list[dict[str, object]]:
+    prepared: list[dict[str, object]] = []
+    for index, entry in enumerate(entries, start=1):
+        try:
+            prepared.append(_prepared_payload(_materialize(entry), entry.audience))
+        except _ENTRY_FAILURES as exc:
+            raise AgentPromptCliError(
+                f"batch entry {index} ({entry.invocation_id}): {exc}; "
+                + _published_note(prepared)
+            ) from exc
+    return prepared
+
+
+def write_jobs(
+    args: argparse.Namespace,
+    prepared: list[dict[str, object]],
+    dispatch_kind: str,
+) -> str:
+    """materialize 된 호출들을 그대로 `agent-prompt jobs` 에 넘긴다."""
+    try:
+        return str(generate_jobs(argparse.Namespace(
+            project_root=args.project_root,
+            run_manifest=args.run_manifest,
+            dispatch_kind=dispatch_kind,
+            metadata=[str(row["metadataPath"]) for row in prepared],
+            out=args.jobs_out,
+        ))["jobsPath"])
+    except _ENTRY_FAILURES as exc:
+        raise AgentPromptCliError(
+            f"jobs file not written: {exc}; " + _published_note(prepared)
+        ) from exc
+
+
+def _published_note(prepared: list[dict[str, object]]) -> str:
+    if not prepared:
+        return "no entry was materialized"
+    # 발행된 항목은 발행된 채 남는다. 같은 배치를 다시 돌리면 새로 쓰지 않고
+    # 동일한 프롬프트·메타데이터·예약을 재사용한다.
+    return (
+        "already materialized and reused unchanged by an identical rerun: "
+        + ", ".join(str(row["invocationId"]) for row in prepared)
+    )
+
+
+def _load_entries(project: Path, raw: str) -> list[object]:
+    path = _project_input(project, raw, "batch")
+    try:
+        payload = load_owned_object(path, artifact="agent prompt batch")
+    except JsonBoundaryError as exc:
+        raise AgentPromptCliError(f"batch file is invalid: {exc}") from exc
+    entries = payload.get("invocations")
+    if set(payload) != {"invocations"} or not isinstance(entries, list) or not entries:
+        raise AgentPromptCliError(
+            'batch file must be {"invocations": [...]} with at least one entry'
+        )
+    return entries
+
+
+def _entry_args(
+    args: argparse.Namespace,
+    index: int,
+    entry: object,
+    parser_factory: Callable[[], argparse.ArgumentParser],
+) -> argparse.Namespace:
+    if not isinstance(entry, dict):
+        raise AgentPromptCliError(f"batch entry {index} must be an object")
+    unknown = sorted(set(entry) - _ENTRY_FLAGS)
+    if unknown:
+        raise AgentPromptCliError(
+            f"batch entry {index} has keys outside the materialize flags: "
+            + ", ".join(unknown)
+        )
+    argv = [
+        "materialize",
+        "--project-root", str(args.project_root),
+        "--run-manifest", str(args.run_manifest),
+    ]
+    for key, value in entry.items():
+        if value is True and key == "replace-undispatched":
+            argv.append(f"--{key}")
+        elif isinstance(value, str) and key != "replace-undispatched":
+            argv.extend([f"--{key}", value])
+        else:
+            raise AgentPromptCliError(f"batch entry {index}: invalid value for {key}")
+    try:
+        parsed = parser_factory().parse_args(argv)
+    except SystemExit as exc:
+        raise AgentPromptCliError(
+            f"batch entry {index}: invalid materialize arguments"
+        ) from exc
+    require_invocation_flags(parsed, f"batch entry {index}")
+    return parsed
+
+
+def require_invocation_flags(args: argparse.Namespace, label: str) -> None:
+    missing = [
+        "--" + flag for flag in _REQUIRED_FLAGS
+        if not getattr(args, flag.replace("-", "_"))
+    ]
+    if missing:
+        raise AgentPromptCliError(f"{label} requires: " + ", ".join(missing))

package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py

@@ -16,6 +16,8 @@ from ...error_log_write import record_runtime_failure
 from ...dispatch_state import BACKEND_CLI_WRAPPER, BACKEND_CMUX_PANE, DispatchError
 from .emit import _emit, _prepared_payload
 from .inputs import AgentPromptCliError
+from .batch import materialize_batch, require_invocation_flags, write_jobs
+from .jobs import check_jobs_target
 from .materialize import _apply_corrections, _check_corrections, _materialize
 from .jobs import generate_jobs
 from .results import (
@@ -31,7 +33,8 @@ from .results import (
 
 
 _CLI_EPILOG = r"""Usage:
-  okstra agent-prompt materialize [options]
+  okstra agent-prompt materialize [options] [--jobs-out <path>]
+  okstra agent-prompt materialize --project-root <dir> --run-manifest <path> --batch <file> [--jobs-out <path>]
   okstra agent-prompt jobs --project-root <dir> --run-manifest <path> --dispatch-kind <kind> --metadata <path> [--metadata <path>] --out <path>
   okstra agent-prompt check-corrections --project-root <dir> --run-manifest <path> --corrections <file>
   okstra agent-prompt apply-corrections --project-root <dir> --run-manifest <path> --corrections <file>
@@ -63,6 +66,10 @@ def _parser() -> argparse.ArgumentParser:
         help="resolve the role, worker count and models an operation requires",
     )
     operation.add_argument("--operation", required=True)
+    operation.add_argument(
+        "--count", type=int, default=None,
+        help="slots to open, from 1 to the operation contract's count (default: the contract's count)",
+    )
     operation.add_argument("--json", action="store_true")
     jobs = commands.add_parser("jobs", help="generate a verified jobs file without dispatching")
     _common_paths(jobs)
@@ -77,10 +84,11 @@ def _parser() -> argparse.ArgumentParser:
 def _add_materialize_parser(commands: argparse._SubParsersAction) -> None:
     materialize = commands.add_parser("materialize")
     _common_paths(materialize)
-    materialize.add_argument("--invocation-id", required=True)
-    materialize.add_argument("--audience", required=True)
-    materialize.add_argument("--instruction", required=True)
-    materialize.add_argument("--prompt", required=True)
+    single_only = "required unless --batch is given"
+    materialize.add_argument("--invocation-id", help=single_only)
+    materialize.add_argument("--audience", help=single_only)
+    materialize.add_argument("--instruction", help=single_only)
+    materialize.add_argument("--prompt", help=single_only)
     # 두 갈래의 인자를 한 파서가 받는다. 어느 갈래의 것인지 help 에 적지 않으면
     # `--help` 가 조건 없이 나열한 인자를 run 갈래가 거절해 놀라게 된다.
     run_only = "run mode only (with --run-manifest)"
@@ -130,6 +138,20 @@ def _add_materialize_parser(commands: argparse._SubParsersAction) -> None:
              "reservations are append-only, so a rewrite needs a fresh "
              "invocation id and prompt path",
     )
+    materialize.add_argument(
+        "--batch",
+        help="run mode only: a JSON file {\"invocations\": [...]} whose "
+             "entries map the per-invocation flags above (without the leading "
+             "--) to values, one entry per worker of the batch; each entry is "
+             "materialized exactly as a single call would be",
+    )
+    materialize.add_argument(
+        "--jobs-out",
+        help="run mode only: also write the verified jobs file for "
+             "`okstra team dispatch --jobs-file` from the materialized "
+             "invocations, as `okstra agent-prompt jobs` would; every batch "
+             "entry must share one --dispatch-kind",
+    )
     materialize.add_argument("--json", action="store_true")
 
     check = commands.add_parser(
@@ -277,7 +299,7 @@ def _refreeze_contracts(args: argparse.Namespace) -> dict[str, object]:
     }
 
 
-def _resolve_operation(operation_id: str) -> dict[str, object]:
+def _resolve_operation(operation_id: str, count: int | None) -> dict[str, object]:
     """이 작업이 열 칸과 각 칸의 모델. 기술은 작업 이름만 알면 된다."""
     from ...model_pool import ModelPool
     from ...operation_invocation import (
@@ -298,6 +320,7 @@ def _resolve_operation(operation_id: str) -> dict[str, object]:
             operation_id,
             contract_root=root,
             pool=ModelPool.from_registry(default_provider_registry()),
+            count=count,
         )
     except OperationPreparationError as exc:
         raise AgentPromptCliError(str(exc)) from exc
@@ -318,11 +341,38 @@ def _resolve_operation(operation_id: str) -> dict[str, object]:
     }
 
 
+def _materialize_batch_command(args: argparse.Namespace) -> int:
+    payload = materialize_batch(args, _parser)
+    if args.json:
+        _emit(payload, True)
+        return 0
+    for row in payload["invocations"]:
+        print(row["promptPath"])
+    if payload["jobsPath"]:
+        print(payload["jobsPath"])
+    return 0
+
+
+def _materialize_single_command(args: argparse.Namespace) -> int:
+    require_invocation_flags(args, "materialize")
+    if args.jobs_out:
+        if not args.run_manifest:
+            raise AgentPromptCliError("--jobs-out requires --run-manifest")
+        check_jobs_target(args.project_root, args.run_manifest, args.jobs_out)
+    payload = _prepared_payload(_materialize(args), args.audience)
+    if args.jobs_out:
+        payload["jobsPath"] = write_jobs(args, [payload], args.dispatch_kind)
+    _emit(payload, args.json)
+    if args.jobs_out and not args.json:
+        print(payload["jobsPath"])
+    return 0
+
+
 def main(argv: list[str] | None = None) -> int:
     try:
         args = _parser().parse_args(argv)
         if args.command == "resolve-operation":
-            payload = _resolve_operation(args.operation)
+            payload = _resolve_operation(args.operation, args.count)
             if args.json:
                 _emit(payload, True)
             else:
@@ -346,9 +396,9 @@ def main(argv: list[str] | None = None) -> int:
                 print(payload["jobsPath"])
             return 0
         if args.command == "materialize":
-            prepared = _materialize(args)
-            _emit(_prepared_payload(prepared, args.audience), args.json)
-            return 0
+            if args.batch:
+                return _materialize_batch_command(args)
+            return _materialize_single_command(args)
         if args.command == "check-corrections":
             payload = _check_corrections(args)
             if args.json:

package/runtime/python/okstra_ctl/agent/prompt_cli/corrections.py

@@ -25,7 +25,7 @@ from ..activity import (
 )
 from ...final_report_schema import load_schema_version
 from ...json_boundary import load_owned_object
-from ...implementation_options import validate_implementation_option_selection
+from ...phases.implementation_option_selection.validation import validate_implementation_option_selection
 from ...report_contract import TASK_TYPE_DATA_PROPERTY
 from ...report_assembly import validate_plan_draft
 from ...report_corrections import (

package/runtime/python/okstra_ctl/agent/prompt_cli/jobs.py

@@ -19,13 +19,30 @@ from .inputs import (
 )
 
 
-def generate_jobs(args: argparse.Namespace) -> dict[str, object]:
-    project = _project_root(args.project_root)
-    manifest_path = _project_input(project, args.run_manifest, "run manifest")
+def check_jobs_target(project_root: str, run_manifest: str, out: str) -> None:
+    """jobs 파일을 쓸 수 있는 run 인지 — `materialize --jobs-out` 이 발행 전에 부른다.
+
+    발행 뒤에 이 검사에서 거부되면 프롬프트만 발행된 채 남는다.
+    """
+    _jobs_target(project_root, run_manifest, out)
+
+
+def _jobs_target(
+    project_root: str, run_manifest: str, out: str,
+) -> tuple[Path, Path, dict, Path]:
+    project = _project_root(project_root)
+    manifest_path = _project_input(project, run_manifest, "run manifest")
     manifest = _read_json_object(manifest_path, "run manifest")
     if manifest.get("executionIdentityVersion") != 2:
         raise AgentPromptCliError("agent-prompt jobs requires a v2 run manifest")
-    output = _authorized_path(project, args.out, [manifest["runDirectoryPath"]], "jobs", must_exist=False)
+    output = _authorized_path(project, out, [manifest["runDirectoryPath"]], "jobs", must_exist=False)
+    return project, manifest_path, manifest, output
+
+
+def generate_jobs(args: argparse.Namespace) -> dict[str, object]:
+    project, manifest_path, manifest, output = _jobs_target(
+        args.project_root, args.run_manifest, args.out,
+    )
     paths = [_project_input(project, value, "metadata") for value in args.metadata]
     rows = [_metadata_job(project, manifest_path, manifest, path, args.dispatch_kind) for path in paths]
     refs = [(row["invocationRef"], row["attempt"]) for row in rows]

package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py

@@ -34,7 +34,11 @@ from ...assignment_environment import load_assignment_context
 from ...assignment_resolver import AssignmentContext, resolve_dispatch_assignment
 from ...path_hints import hydrate_active_run_context
 from ...worker_prompt_headers import worker_prompt_headers
-from ...worker_prompt_contract import complete_reverify_instruction, validate_reverify_prompt
+from ...worker_prompt_contract import (
+    complete_reverify_instruction,
+    validate_plan_verify_dispatch_identity,
+    validate_reverify_prompt,
+)
 from ...worker_prompt_policy import (
     critic_assignment_ref,
     is_plan_critic_verification,
@@ -340,6 +344,11 @@ def _materialize_run(
         active_context=active_context,
     ))
     body = instruction_path.read_text(encoding="utf-8")
+    identity_errors = validate_plan_verify_dispatch_identity(
+        body, dispatch_kind=args.dispatch_kind, result_name=result_path.name,
+    )
+    if identity_errors:
+        raise AgentPromptCliError("; ".join(identity_errors))
     is_reverify = is_verification_dispatch_kind(args.dispatch_kind)
     if is_reverify:
         body = _complete_run_reverify_body(args, manifest, active_context, assignment, body, instruction_path)

package/runtime/python/okstra_ctl/analysis_inputs.py

@@ -73,7 +73,6 @@ _EVIDENCE_RELATION_BY_TYPES = {
 _REPORT_NAME_RE = re.compile(
     r"^final-report-.+-(?P<run_seq>[^-]+)\.data\.json$"
 )
-_FEATURE_ID_RE = re.compile(r"PF-\d{3}")
 _FULL_COMMIT_RE = re.compile(r"[0-9a-f]{40}")
 _RUN_SEQ_RE = re.compile(r"[0-9]{3}")
 
@@ -347,41 +346,3 @@ def resolve_evidence_inputs(
             freshness="exact" if candidate.source_commit == current_commit else "stale",
         ))
     return tuple(resolved)
-
-
-def resolve_analysis_target(
-    raw_target: str,
-    evidence_inputs: Sequence[ResolvedEvidenceInput],
-    candidates: Mapping[Path, AnalysisReportCandidate],
-) -> dict[str, object]:
-    """Normalize a feature-index identifier or a non-empty free-text target."""
-    target = raw_target.strip()
-    if not target:
-        raise AnalysisInputError("analysis target must not be empty")
-    if not _FEATURE_ID_RE.fullmatch(target):
-        return {"inputMode": "free-text", "requestedValue": target}
-    matches: list[dict[object, object]] = []
-    for evidence in evidence_inputs:
-        if evidence.relation != "project-context":
-            continue
-        candidate = candidates.get(evidence.report_path)
-        if candidate is None:
-            candidate = next(
-                (value for path, value in candidates.items() if path.resolve() == evidence.report_path),
-                None,
-            )
-        if candidate is None:
-            continue
-        matches.extend(
-            feature for feature in candidate.feature_index
-            if isinstance(feature, dict) and feature.get("id") == target
-        )
-    if len(matches) != 1:
-        raise AnalysisInputError(
-            f"exactly one project-context feature must match {target}"
-        )
-    return {
-        "inputMode": "feature-index",
-        "requestedValue": target,
-        "feature": dict(matches[0]),
-    }

package/runtime/python/okstra_ctl/analysis_scope.py

@@ -0,0 +1,31 @@
+"""분석 증거와 단계 내용 검증이 공유하는 프로젝트 상대 경로 판독."""
+from __future__ import annotations
+
+from pathlib import PurePosixPath
+
+
+def _normalized_project_path(path: object) -> PurePosixPath | None:
+    if not isinstance(path, str):
+        return None
+    raw = path.strip().rstrip("/")
+    if not raw or raw == "." or raw.startswith("/"):
+        return None
+    if any(part in {"", ".", ".."} for part in raw.split("/")):
+        return None
+    normalized = PurePosixPath(raw)
+    if normalized.is_absolute():
+        return None
+    return normalized
+
+
+def _path_is_included(path: object, included_paths: list[object]) -> bool:
+    candidate = _normalized_project_path(path)
+    if candidate is None:
+        return False
+    for raw in included_paths:
+        included = _normalized_project_path(raw)
+        if included is not None and (
+            candidate == included or included in candidate.parents
+        ):
+            return True
+    return False

package/runtime/python/okstra_ctl/approval_decisions.py

@@ -222,7 +222,7 @@ def open_decision(
     clarification_id: str, ticket_id: str, statement: str, expected_form: str,
     classification: str, origin: str, user_confirmation: str,
     unblock_condition: str, recommended_disposition: str,
-    options: Sequence[DecisionOption],
+    options: Sequence[DecisionOption], supersedes: Sequence[str] = (),
 ) -> None:
     row = _decision_row(
         clarification_id=clarification_id, ticket_id=ticket_id,
@@ -237,10 +237,30 @@ def open_decision(
         raise ApprovalDecisionError("activeClarifications must be an array")
     if any(item.get("id") == clarification_id for item in active if isinstance(item, Mapping)):
         raise ApprovalDecisionError(f"duplicate active clarification: {clarification_id}")
+    if supersedes:
+        row["supersedes"] = _superseded_carried_ids(ledger, supersedes)
     active.append(row)
     write_json_atomic(ledger_path, ledger)
 
 
+def _superseded_carried_ids(
+    ledger: Mapping[str, Any], supersedes: Sequence[str],
+) -> list[str]:
+    carried = ledger.get("carriedDecisions")
+    carried_ids = {
+        entry["decision"].get("id")
+        for entry in (carried if isinstance(carried, list) else [])
+        if isinstance(entry, Mapping) and isinstance(entry.get("decision"), Mapping)
+    }
+    ids = list(dict.fromkeys(_required(value, "supersedes") for value in supersedes))
+    unknown = [value for value in ids if value not in carried_ids]
+    if unknown:
+        raise ApprovalDecisionError(
+            f"supersedes must name carried decisions of this ledger: {unknown}"
+        )
+    return ids
+
+
 def resolve_decision(
     ledger_path: Path, clarification_id: str, *, disposition: str,
     user_text: str, user_response_ref: str, check_refs: Sequence[str],
@@ -412,10 +432,20 @@ def _add_open_arguments(parser: argparse.ArgumentParser) -> None:
     )
     for flag in repeated:
         parser.add_argument(f"--option-{flag}", action="append", default=[])
+    parser.add_argument(
+        "--supersedes",
+        action="append",
+        default=[],
+        help=(
+            "a carried decision this question replaces; once this row is "
+            "resolved, report assembly publishes that carried row as obsolete. "
+            "Repeat for several ids."
+        ),
+    )
 
 
 _CLI_EPILOG = r"""Usage:
-  okstra approval-decision open --ledger <path> [decision fields]
+  okstra approval-decision open --ledger <path> [decision fields] [--supersedes <C-NNN> ...]
   okstra approval-decision resolve --ledger <path> --clarification-id <C-NNN> [resolution fields]
   okstra approval-decision carry --ledger <path> --from-responses <clarification-response.md> --clarification-id <C-NNN> [--clarification-id <C-NNN> ...]
   okstra approval-decision carry --ledger <path> --source-ledger <path> --source-run-ref <ref> --clarification-id <C-NNN>

package/runtime/python/okstra_ctl/asset_roots.py

@@ -0,0 +1,19 @@
+"""Ancestor-based runtime asset lookup independent of run and phase state."""
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from pathlib import Path
+
+
+def walk_to_asset_root(
+    relative: Sequence[str],
+    *,
+    start: Path,
+    is_present: Callable[[Path], bool] = Path.is_file,
+) -> Path | None:
+    """Return the nearest ancestor carrying the asset without home overrides."""
+    here = Path(start).resolve()
+    for parent in [here, *here.parents]:
+        if is_present(parent.joinpath(*relative)):
+            return parent
+    return None

package/runtime/python/okstra_ctl/assignment_resolver.py

@@ -327,6 +327,14 @@ def resolve_model_selection(
     raw_model: str,
 ) -> ResolvedModel:
     """Resolve one explicit or provider-default catalog model without binding."""
+    if raw_model and "/" in raw_model:
+        # `agent-prompt resolve-operation` prints slots as model refs.
+        selected = pool.resolve(raw_model)
+        if selected.provider_id != provider.strip().lower():
+            raise AssignmentResolutionError(
+                f"model {raw_model!r} does not belong to provider {provider!r}"
+            )
+        return selected
     if raw_model:
         return pool.resolve_alias(provider, raw_model)
     selected = pool.default_candidate(provider, role)

package/runtime/python/okstra_ctl/blocking_checks.py

@@ -239,6 +239,13 @@ _BLOCKING: tuple[tuple[str, str], ...] = (
         "같은 이유 — 검증 범위가 열거값 밖이거나 단일 stage 검증이 전체 "
         "release-handoff 를 요구한다.",
     ),
+    (
+        "for release but `runs/implementation-planning/consumers.jsonl` carries no",
+        "통과 판정이 stage 에 `verified` 행을 남기지 않았다 — handoff.py 의 "
+        "compute_eligibility 가 그 행으로만 PR 대상을 고르므로 통과한 stage 가 "
+        "release-handoff 에서 영영 제외된다. report-finalize 의 record-verified "
+        "단계가 이 검증 직전에 행을 쓰므로 정상 run 은 항상 만족한다.",
+    ),
 )
 
 # 2026-08-28 에 제거한 조각과 근거 (감사 보고서 §2):