okstra 0.207.1 → 0.209.0

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

@@ -118,6 +118,7 @@ def _add_materialize_parser(commands: argparse._SubParsersAction) -> None:
              "result is not their own worker result",
     )
     materialize.add_argument("--host-runtime", help=standalone_only)
+    materialize.add_argument("--execution-runner", choices=("cli-wrapper",), help=standalone_only)
     materialize.add_argument(
         "--terminal-backend",
         choices=(BACKEND_CLI_WRAPPER, BACKEND_CMUX_PANE),

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

@@ -13,7 +13,6 @@ import os
 from pathlib import Path
 import shlex
 import shutil
-import tempfile
 from typing import Any, Mapping, get_args
 
 from ..invocation import (
@@ -31,7 +30,7 @@ from ..invocation import (
     compose_unbound_run_prompt,
 )
 from ...assignment_environment import load_assignment_context
-from ...assignment_resolver import AssignmentContext, resolve_dispatch_assignment
+from ..standalone import StandaloneInvocationRequest, prepare_standalone_invocation
 from ...path_hints import hydrate_active_run_context
 from ...worker_prompt_headers import worker_prompt_headers
 from ...worker_prompt_contract import (
@@ -127,6 +126,7 @@ def _materialize_run(
         )
     forbidden = {
         "host-runtime": args.host_runtime,
+        "execution-runner": args.execution_runner,
         "provider": args.provider,
         "model-role": args.model_role,
         "model": args.model,
@@ -142,9 +142,11 @@ def _materialize_run(
     contract = _mapping(manifest.get("agentContract"), "run agent contract")
     authorized = _mapping(contract.get("authorizedPaths"), "authorized paths")
 
+    # 교정 전용 디스패치는 본문을 원장에서 렌더한다(`_with_report_writer_sections`).
+    # 그때 지시문 출처는 원장 자신이다.
     instruction_path = _authorized_path(
         project_root,
-        args.instruction,
+        args.instruction or getattr(args, "corrections", None),
         authorized.get("instructionRoots"),
         "instruction",
         must_exist=True,
@@ -343,7 +345,7 @@ def _materialize_run(
         manifest=manifest,
         active_context=active_context,
     ))
-    body = instruction_path.read_text(encoding="utf-8")
+    body = instruction_path.read_text(encoding="utf-8") if args.instruction else ""
     identity_errors = validate_plan_verify_dispatch_identity(
         body, dispatch_kind=args.dispatch_kind, result_name=result_path.name,
     )
@@ -963,125 +965,9 @@ def _materialize_standalone(
         execution_provider_ids=(args.provider,),
         include_native_provider=False,
     )
-    assignment = _standalone_assignment(
-        context=assignment_context,
-        provider=args.provider,
-        model_role=args.model_role,
-        model=args.model,
-    )
-    duty_root = root / f"{args.invocation_id}.duty-contracts"
-    _snapshot_standalone_duties(duty_root)
-    return prepare_agent_invocation(AgentInvocationRequest(
-        invocation_id=args.invocation_id,
-        worker_id=None,
-        audience=args.audience,
-        assignment_ref=None,
-        purpose=args.purpose,
-        assignment=assignment,
-        instruction=AgentInstruction(
-            anchor_lines=(),
-            body=instruction_path.read_text(encoding="utf-8"),
-            source_paths=(AgentInstructionSource(
-                kind="project",
-                path=_relative(project_root, instruction_path),
-            ),),
-        ),
-        project_root=project_root,
-        run_manifest_path=None,
-        duty_root=duty_root,
-        prompt_path=prompt_path,
-        metadata_path=prompt_path.with_name(prompt_path.name + ".meta.json"),
-        dispatch_kind="standalone",
-        participant_ref=None,
-        role_execution_ref=None,
-        duty_id=None,
-        invocation_ref=None,
-        attempt=1,
+    return prepare_standalone_invocation(StandaloneInvocationRequest(
+        project_root=project_root, invocation_id=args.invocation_id, audience=args.audience,
+        purpose=args.purpose, context=assignment_context, provider=args.provider,
+        model_role=args.model_role, model=args.model, instruction_path=instruction_path,
+        prompt_path=prompt_path, requested_runner=args.execution_runner,
     ))
-
-
-def _standalone_assignment(
-    *,
-    context: AssignmentContext,
-    provider: str,
-    model_role: str,
-    model: str,
-) -> AgentModelAssignment:
-    host_runtime = context.environment.host_descriptor.id
-    resolved = resolve_dispatch_assignment(
-        context=context,
-        host_runtime=host_runtime,
-        role=model_role,
-        duty_id=model_role,
-        provider=provider,
-        model=model,
-    )
-    binding = resolved.binding
-    if binding is None:
-        raise AgentPromptCliError("standalone assignment requires a model binding")
-    return AgentModelAssignment(
-        provider=resolved.provider_id,
-        model=resolved.display_name,
-        model_execution_value=binding.resolved_execution_value,
-        runner=binding.runner,
-        host_runtime=host_runtime,
-        host_model_value=binding.host_model_value,
-    )
-
-
-def _snapshot_standalone_duties(destination: Path) -> None:
-    # 부모 개수를 세면 체크아웃(`<root>/scripts/okstra_ctl/agent/prompt_cli/`)
-    # 에서만 맞는다 — 설치본은 패키지가 `~/.okstra/lib/python/` 이라 prompts 가
-    # 한 단계 위(`~/.okstra/prompts/`)에 있다. duties 를 실제로 가진 루트를
-    # 탐색해서 해소한다.
-    from ...paths import find_asset_root
-
-    duties_relative = ("prompts", "duties")
-    root = find_asset_root(duties_relative, is_present=Path.is_dir)
-    if root is None:
-        raise AgentPromptCliError(
-            "duty contract source not found: no prompts/duties under "
-            "OKSTRA_HOME or this checkout"
-        )
-    source = root.joinpath(*duties_relative)
-    # 공통 계약은 직무가 아니라 `agents/` 가 소유한다(ADR-0017). 동결본은 한
-    # 뿌리여야 하므로 여기서 함께 싣는다.
-    common_root = find_asset_root(("agents", "common.json"), is_present=Path.is_file)
-    if common_root is None:
-        raise AgentPromptCliError(
-            "agent common contract not found: no agents/common.json under "
-            "OKSTRA_HOME or this checkout"
-        )
-    common_source = common_root / "agents" / "common.json"
-
-    def _staged_digest() -> str:
-        staged = Path(tempfile.mkdtemp(prefix=".okstra-standalone-duties."))
-        try:
-            shutil.copytree(source, staged, dirs_exist_ok=True)
-            shutil.copyfile(common_source, staged / "common.json")
-            shutil.copytree(
-                common_source.parent / "roles", staged / "roles", dirs_exist_ok=True
-            )
-            return digest_duty_catalog(staged)
-        finally:
-            shutil.rmtree(staged, ignore_errors=True)
-
-    if destination.exists():
-        if not destination.is_dir() or digest_duty_catalog(destination) != _staged_digest():
-            raise AgentPromptCliError("standalone duty snapshot conflicts with existing files")
-        return
-    temporary = Path(tempfile.mkdtemp(prefix=f".{destination.name}.", dir=destination.parent))
-    try:
-        shutil.copytree(source, temporary, dirs_exist_ok=True)
-        shutil.copyfile(common_source, temporary / "common.json")
-        shutil.copytree(
-            common_source.parent / "roles", temporary / "roles", dirs_exist_ok=True
-        )
-        try:
-            os.rename(temporary, destination)
-        except FileExistsError:
-            if digest_duty_catalog(destination) != _staged_digest():
-                raise AgentPromptCliError("standalone duty snapshot publication conflict")
-    finally:
-        if temporary.exists():
-            shutil.rmtree(temporary)

package/runtime/python/okstra_ctl/agent/standalone.py

@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+import os
+import shutil
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+
+from ..assignment_resolver import AssignmentContext, resolve_dispatch_assignment
+from .invocation import (
+    AgentAudience,
+    AgentInstruction,
+    AgentInstructionSource,
+    AgentInvocationError,
+    AgentInvocationRequest,
+    AgentModelAssignment,
+    PreparedAgentInvocation,
+    digest_duty_catalog,
+    prepare_agent_invocation,
+)
+
+
+@dataclass(frozen=True)
+class StandaloneInvocationRequest:
+    project_root: Path
+    invocation_id: str
+    audience: AgentAudience
+    purpose: str
+    context: AssignmentContext
+    provider: str
+    model_role: str
+    model: str
+    instruction_path: Path
+    prompt_path: Path
+    requested_runner: str | None = None
+
+
+def prepare_standalone_invocation(
+    request: StandaloneInvocationRequest,
+) -> PreparedAgentInvocation:
+    root = request.project_root / ".okstra" / "agent-invocations" / request.purpose
+    if not root.resolve().is_relative_to(request.project_root.resolve()):
+        raise AgentInvocationError("standalone invocation root escapes project")
+    duty_root = root / f"{request.invocation_id}.duty-contracts"
+    snapshot_standalone_duties(duty_root)
+    assignment = standalone_assignment(
+        context=request.context,
+        provider=request.provider,
+        model_role=request.model_role,
+        model=request.model,
+        requested_runner=request.requested_runner,
+    )
+    return prepare_agent_invocation(
+        AgentInvocationRequest(
+            invocation_id=request.invocation_id,
+            worker_id=None,
+            audience=request.audience,
+            assignment_ref=None,
+            purpose=request.purpose,
+            assignment=assignment,
+            instruction=AgentInstruction(
+                anchor_lines=(),
+                body=request.instruction_path.read_text(encoding="utf-8"),
+                source_paths=(
+                    AgentInstructionSource(
+                        kind="project",
+                        path=request.instruction_path.relative_to(
+                            request.project_root
+                        ).as_posix(),
+                    ),
+                ),
+            ),
+            project_root=request.project_root,
+            run_manifest_path=None,
+            duty_root=duty_root,
+            prompt_path=request.prompt_path,
+            metadata_path=request.prompt_path.with_name(
+                request.prompt_path.name + ".meta.json"
+            ),
+            dispatch_kind="standalone",
+            participant_ref=None,
+            role_execution_ref=None,
+            duty_id=None,
+            invocation_ref=None,
+            attempt=1,
+        )
+    )
+
+
+def standalone_assignment(
+    *,
+    context: AssignmentContext,
+    provider: str,
+    model_role: str,
+    model: str,
+    requested_runner: str | None = None,
+) -> AgentModelAssignment:
+    host_runtime = context.environment.host_descriptor.id
+    resolved = resolve_dispatch_assignment(
+        context=context,
+        host_runtime=host_runtime,
+        role=model_role,
+        duty_id=model_role,
+        provider=provider,
+        model=model,
+        requested_runner=requested_runner,
+    )
+    binding = resolved.binding
+    if binding is None:
+        raise AgentInvocationError("standalone assignment requires a model binding")
+    return AgentModelAssignment(
+        provider=resolved.provider_id,
+        model=resolved.display_name,
+        model_execution_value=binding.resolved_execution_value,
+        runner=binding.runner,
+        host_runtime=host_runtime,
+        host_model_value=binding.host_model_value,
+    )
+
+
+def snapshot_standalone_duties(destination: Path) -> None:
+    # 부모 개수를 세면 체크아웃(`<root>/scripts/okstra_ctl/agent/prompt_cli/`)
+    # 에서만 맞는다 — 설치본은 패키지가 `~/.okstra/lib/python/` 이라 prompts 가
+    # 한 단계 위(`~/.okstra/prompts/`)에 있다. duties 를 실제로 가진 루트를
+    # 탐색해서 해소한다.
+    from ..paths import find_asset_root
+
+    duties_relative = ("prompts", "duties")
+    root = find_asset_root(duties_relative, is_present=Path.is_dir)
+    if root is None:
+        raise AgentInvocationError(
+            "duty contract source not found: no prompts/duties under "
+            "OKSTRA_HOME or this checkout"
+        )
+    source = root.joinpath(*duties_relative)
+    # 공통 계약은 직무가 아니라 `agents/` 가 소유한다(ADR-0017). 동결본은 한
+    # 뿌리여야 하므로 여기서 함께 싣는다.
+    common_root = find_asset_root(("agents", "common.json"), is_present=Path.is_file)
+    if common_root is None:
+        raise AgentInvocationError(
+            "agent common contract not found: no agents/common.json under "
+            "OKSTRA_HOME or this checkout"
+        )
+    common_source = common_root / "agents" / "common.json"
+
+    def _staged_digest() -> str:
+        staged = Path(tempfile.mkdtemp(prefix=".okstra-standalone-duties."))
+        try:
+            _copy_standalone_contracts(source, common_source, staged)
+            return digest_duty_catalog(staged)
+        finally:
+            shutil.rmtree(staged, ignore_errors=True)
+
+    if destination.exists():
+        if (
+            not destination.is_dir()
+            or digest_duty_catalog(destination) != _staged_digest()
+        ):
+            raise AgentInvocationError(
+                "standalone duty snapshot conflicts with existing files"
+            )
+        return
+    temporary = Path(
+        tempfile.mkdtemp(prefix=f".{destination.name}.", dir=destination.parent)
+    )
+    try:
+        _copy_standalone_contracts(source, common_source, temporary)
+        try:
+            os.rename(temporary, destination)
+        except FileExistsError:
+            if digest_duty_catalog(destination) != _staged_digest():
+                raise AgentInvocationError(
+                    "standalone duty snapshot publication conflict"
+                )
+    finally:
+        if temporary.exists():
+            shutil.rmtree(temporary)
+
+
+def _copy_standalone_contracts(source: Path, common: Path, target: Path) -> None:
+    shutil.copytree(source, target, dirs_exist_ok=True)
+    shutil.copyfile(common, target / "common.json")
+    shutil.copytree(common.parent / "roles", target / "roles", dirs_exist_ok=True)

package/runtime/python/okstra_ctl/analysis_packet.py

@@ -25,6 +25,7 @@ BRIEF_SECTIONS = (
 CANONICAL_BRIEF_SECTIONS = (
     "Source Material",
     "Context",
+    "Project Scope",
     "Problem / Symptom",
     "Desired Outcome",
     "Expected Behavior",
@@ -107,6 +108,8 @@ def build_analysis_packet(
     stage_ledger_notice: str = "",
     prior_planning_summary: str = "",
     direct_work_text: str = "",
+    business_knowledge_text: str = "",
+    coverage_census_text: str = "",
 ) -> str:
     """Return the primary compact input for Claude/Codex/Antigravity analysers.
 
@@ -120,6 +123,9 @@ def build_analysis_packet(
     `group_context_path` is the task-group context prepare copied into the
     instruction set (`task-group-context.md`); `None` means the group has no
     such document and the packet carries no `## Task-Group Context` section.
+
+    `coverage_census_text` is the `## Coverage Census` block
+    `coverage_census.render_census_section` rendered; empty means no census.
     """
     brief_text = task_brief_path.read_text(encoding="utf-8")
     group_context_text = _read_optional(group_context_path) if group_context_path else ""
@@ -155,6 +161,10 @@ def build_analysis_packet(
                    fix_history_text, prior_planning_summary, stage_ledger_json)),
     ))
     parts.extend(_profile_block(task_type, profile_text))
+    if business_knowledge_text:
+        parts.extend(["", business_knowledge_text, ""])
+    if coverage_census_text:
+        parts.extend(["", coverage_census_text])
     parts.extend(_reference_block(reference_text))
     parts.extend(_fix_history_block(fix_history_text))
     parts.extend(_stage_ledger_block(stage_ledger_json))
@@ -167,7 +177,7 @@ def build_analysis_packet(
 
 
 _HEADING_RE = re.compile(r"\A#{1,2} \S")
-_FENCE_RE = re.compile(r"\A\s*(```|~~~)")
+_FENCE_RE = re.compile(r"\A\s*(?P<marker>`{3,}|~{3,})(?P<info>.*)\Z")
 # 목차 자신이 차지하는 줄 수 중 표제 행을 뺀 나머지. 행 수는 표제 개수로
 # 정해지므로 삽입 전에 전체 이동량을 계산할 수 있다.
 _INDEX_PREAMBLE_LINES = 5
@@ -273,11 +283,7 @@ def _heading_lines(lines: list[str]) -> list[tuple[int, str]]:
     not a section.
     """
     out: list[tuple[int, str]] = []
-    fenced = False
-    for number, line in enumerate(lines, start=1):
-        if _FENCE_RE.match(line):
-            fenced = not fenced
-            continue
+    for number, (line, fenced) in enumerate(zip(lines, _fence_mask(lines)), start=1):
         if fenced or not _HEADING_RE.match(line):
             continue
         if line.startswith("# OKSTRA Analysis Packet"):
@@ -286,6 +292,30 @@ def _heading_lines(lines: list[str]) -> list[tuple[int, str]]:
     return out
 
 
+def _fence_mask(lines: list[str]) -> list[bool]:
+    """Per line, whether it belongs to a fenced block (fence lines included).
+
+    A fence closes only on the same character at least as long, with no info
+    string (CommonMark). Briefs quote whole documents in ````` ```` ````` fences
+    that themselves contain ``` blocks and `## ` headings.
+    """
+    mask: list[bool] = []
+    opener: str | None = None
+    for line in lines:
+        match = _FENCE_RE.match(line)
+        if opener is None:
+            if match:
+                opener = match.group("marker")
+            mask.append(opener is not None)
+            continue
+        mask.append(True)
+        if (match and not match.group("info").strip()
+                and match.group("marker")[0] == opener[0]
+                and len(match.group("marker")) >= len(opener)):
+            opener = None
+    return mask
+
+
 def _packet_frontmatter(brief_text: str, task_key: str) -> str:
     frontmatter = _extract_frontmatter(brief_text)
     if frontmatter:
@@ -697,8 +727,9 @@ def _section_map(text: str) -> dict[str, str]:
     result: dict[str, list[str]] = {}
     aliases: dict[str, str] = {}
     current = ""
-    for line in _strip_frontmatter(text).splitlines():
-        if line.startswith("## "):
+    lines = _strip_frontmatter(text).splitlines()
+    for line, fenced in zip(lines, _fence_mask(lines)):
+        if line.startswith("## ") and not fenced:
             current = line[3:].strip()
             result.setdefault(current, [])
             alias = _heading_alias(current)

package/runtime/python/okstra_ctl/assignment_resolver.py

@@ -240,6 +240,7 @@ def resolve_model_assignment(
     environment: AssignmentEnvironment,
     entry_mode: Literal["current-session", "new-session"] = "new-session",
     require_selectable: bool = True,
+    requested_runner: str | None = None,
 ) -> ResolvedAssignment:
     """Resolve one canonical model through the selected host execution path.
 
@@ -269,6 +270,7 @@ def resolve_model_assignment(
         model,
         pool,
         environment,
+        requested_runner,
     )
     return _resolved_assignment(instance, model, host, entry_mode, binding)
 
@@ -281,6 +283,7 @@ def resolve_dispatch_assignment(
     duty_id: str,
     provider: str,
     model: str = "",
+    requested_runner: str | None = None,
 ) -> ResolvedAssignment:
     """Resolve one legacy provider/model input through the shared core."""
     canonical_role = normalize_role(role)
@@ -298,6 +301,7 @@ def resolve_dispatch_assignment(
         pool=pool,
         host=host,
         environment=context.environment,
+        requested_runner=requested_runner,
     )
 
 
@@ -604,10 +608,12 @@ def _first_supported_binding(
     model: ResolvedModel,
     pool: ModelPool,
     environment: AssignmentEnvironment,
+    requested_runner: str | None = None,
 ) -> HostModelBinding:
     provider = pool.resolve_provider(model.provider_id)
     errors: list[str] = []
-    for runner in _runner_candidates(instance, environment, provider):
+    runners = (requested_runner,) if requested_runner else _runner_candidates(instance, environment, provider)
+    for runner in runners:
         try:
             resolve_assignment_runner(
                 host=environment.host_descriptor,

package/runtime/python/okstra_ctl/brief_frontmatter.py

@@ -45,5 +45,15 @@ def read_brief_frontmatter(path: Path) -> dict[str, str]:
     return out
 
 
+def brief_task_id(frontmatter: Mapping[str, str]) -> str:
+    """The task-id a brief belongs to, unslugified; ``''`` when it names none.
+
+    okstra-manager splits one ticket into per-project child tasks keyed by the
+    ticket alone, so its briefs record that key in ``task-id`` while ``brief-id``
+    stays the long file stem. Other briefs carry only ``brief-id``.
+    """
+    return frontmatter.get("task-id") or frontmatter.get("brief-id", "")
+
+
 def has_reporter_confirmation_contract(frontmatter: Mapping[str, str]) -> bool:
     return "reporter-confirmations" in frontmatter

package/runtime/python/okstra_ctl/business_flow/__init__.py

@@ -0,0 +1,4 @@
+from .engine import explain_flow
+from .store import query_knowledge
+
+__all__ = ["explain_flow", "query_knowledge"]

package/runtime/python/okstra_ctl/business_flow/cli.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from ..json_boundary import JsonBoundaryError
+from ..report_language import resolve_report_language
+from .contracts import BusinessFlowError, FlowRequest
+from .engine import explain_flow, load_execution, rerun_explanation
+from .store import query_knowledge
+
+
+def build_parser() -> argparse.ArgumentParser:
+    explain = argparse.ArgumentParser(add_help=False)
+    explain.add_argument("--question", dest="question_flag", default="")
+    explain.add_argument(
+        "--mode", choices=("current", "pre", "post"), default="current"
+    )
+    explain.add_argument("--task-key", default="")
+    explain.add_argument("--baseline", default="")
+    explain.add_argument("--source-root", type=Path)
+    explain.add_argument("--report-language", default="")
+    explain.add_argument(
+        "--source-artifact",
+        action="append",
+        default=[],
+        help="existing read-only verification record",
+    )
+    explain.add_argument("--host-runtime", default="claude-code")
+    explain.add_argument("--project-root", type=Path, default=Path.cwd())
+    explain.add_argument("--json", action="store_true")
+    parser = argparse.ArgumentParser(prog="okstra explain-flow", parents=[explain])
+    parser.set_defaults(command="explain", question="")
+    commands = parser.add_subparsers(dest="command")
+    explicit = commands.add_parser(
+        "explain", help="investigate a business question", parents=[explain]
+    )
+    explicit.add_argument("question", nargs="?", default="")
+    knowledge = commands.add_parser(
+        "knowledge", help="query relevant shared business knowledge"
+    )
+    knowledge.add_argument("--query", required=True)
+    rerun = commands.add_parser(
+        "rerun", help="retry only an explanation and retain its history"
+    )
+    rerun.add_argument("--execution", required=True)
+    rerun.add_argument("--source-root", type=Path)
+    status = commands.add_parser("status", help="inspect an explanation execution")
+    status.add_argument("--execution", required=True)
+    for child in (knowledge, rerun, status):
+        child.add_argument("--project-root", type=Path, default=Path.cwd())
+        child.add_argument("--json", action="store_true")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    arguments = list(sys.argv[1:] if argv is None else argv)
+    if (
+        arguments
+        and not arguments[0].startswith("-")
+        and arguments[0]
+        not in {
+            "explain",
+            "knowledge",
+            "rerun",
+            "status",
+            "-h",
+            "--help",
+        }
+    ):
+        arguments.insert(0, "explain")
+    args = build_parser().parse_args(arguments)
+    args.command = args.command or "explain"
+    try:
+        if args.command == "explain":
+            result = explain_flow(
+                FlowRequest(
+                    args.project_root,
+                    args.question_flag or args.question,
+                    args.mode,
+                    args.task_key,
+                    args.baseline,
+                    args.source_root,
+                    args.report_language
+                    or resolve_report_language(args.project_root, {}, {}),
+                    tuple(args.source_artifact),
+                    args.host_runtime,
+                )
+            )
+        elif args.command == "knowledge":
+            result = query_knowledge(args.project_root, args.query)
+        elif args.command == "rerun":
+            result = rerun_explanation(
+                args.project_root, args.execution, source_root=args.source_root
+            )
+        else:
+            result = load_execution(args.project_root, args.execution)
+        print(
+            json.dumps(result, ensure_ascii=False, indent=2)
+            if args.json
+            else render_result(result)
+        )
+        return 1 if result.get("status") == "failed" else 0
+    except (OSError, BusinessFlowError, JsonBoundaryError) as exc:
+        print(f"explain-flow: {exc}", file=sys.stderr)
+        return 1
+
+
+def render_result(result: dict) -> str:
+    if "claims" in result:
+        lines = ["Shared Business Knowledge", ""]
+        for row in result["claims"]:
+            lines.append(
+                f"- {row['value']} ({row['level']}; {row['freshness']}; {row['status']})"
+            )
+            lines.append(f"  - Claim: {row['id']}; owner: {row['ownerRoot']}")
+        lines.extend(f"- Read error: {error}" for error in result["errors"])
+        return "\n".join(lines)
+    lines = [
+        "Business Flow Explanation",
+        f"Status: {result['status']}",
+        f"Execution: {result['id']}",
+    ]
+    lines.extend(f"{kind}: {path}" for kind, path in result.get("reports", {}).items())
+    if result.get("error"):
+        lines.append(f"Error: {result['error']}")
+    lines.append(f"Retry: okstra explain-flow rerun --execution {result['id']}")
+    return "\n".join(lines)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())