simplicio-cli 0.7.1__tar.gz → 0.9.0__tar.gz

{simplicio_cli-0.7.1/simplicio_cli.egg-info → simplicio_cli-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simplicio-cli
-Version: 0.7.1
+Version: 0.9.0
 Summary: Portable task-to-code pipeline that works with any LLM. Turn a one-line task into a verified code change — diff + test + verify loop. +55 pts on a 156-check benchmark, 21% faster, ~same tokens.
 Author-email: Wesley Simplicio <wesleybob4@gmail.com>
 License: MIT
@@ -106,14 +106,18 @@ simplicio-py task "hide the Delete button for non-admins"
 ```mermaid
 flowchart LR
   mapper["simplicio-mapper
-repo context"] --> current["simplicio-cli
-this project"]
-  prompt["simplicio-prompt
-reasoning runtime"] --> current
+repo context"] --> runtime["simplicio-runtime
+task and MCP surface"]
+  loop["simplicio-loop
+proven task flow"] --> runtime
+  runtime --> current["simplicio-cli
+focused implementation"]
+  current --> edit["simplicio edit
+mechanical writes"]
   current --> evidence["validated evidence
 tests, docs, screenshots"]
-  current --> sprint["simplicio-sprint
-delivery loop"]
+  runtime --> sprint["simplicio-sprint
+delivery status"]
 ```
 
 ## Proof and validation
@@ -125,8 +129,9 @@ delivery loop"]
 ## Simplicio ecosystem
 
 - [simplicio-mapper](https://github.com/wesleysimplicio/simplicio-mapper) supplies repo context before interpretation.
+- [simplicio-runtime](https://github.com/wesleysimplicio/simplicio-runtime) is the canonical task, MCP, and assistant entrypoint.
+- [simplicio-loop](https://github.com/wesleysimplicio/simplicio-loop) is the proven task-flow reference the runtime reuses for evidence-gated execution.
 - [simplicio-cli](https://github.com/wesleysimplicio/simplicio-dev-cli) executes focused code tasks with verification.
-- [simplicio-prompt](https://github.com/wesleysimplicio/simplicio-prompt) provides fan-out and consensus runtime patterns.
 - [simplicio-sprint](https://github.com/wesleysimplicio/simplicio-sprint) turns cards into draft PR delivery loops.
 
 ## Documentation standard
@@ -159,15 +164,16 @@ pip install simplicio-cli
 ---
 ### Recommended Default Stack (Official)
 
-The recommended and supported way to use `simplicio-dev-cli` is as part of the full Simplicio execution stack:
+The recommended and supported way to use `simplicio-dev-cli` is inside the runtime-first Simplicio execution stack:
 
-**simplicio-dev-cli + simplicio-prompt + agents/skills**
+**simplicio-runtime + simplicio-loop + simplicio-dev-cli + agents/skills**
 
-- `simplicio-dev-cli`: 6-layer contract, verification loop, and core task execution.
-- `simplicio-prompt`: Subagent runtime, fan-out, behavior consensus aggregator, and advanced orchestration.
-- **Agents & Skills**: Reusable capabilities from `.skills/`, `.agents/`, and the Simplicio starter (AGENTS.md, specs-as-code, etc.).
+- `simplicio-runtime`: canonical task, MCP, and assistant entrypoint.
+- `simplicio-loop`: the proven converge/drain task flow used today; runtime reuses it as the reference discipline for evidence-gated completion, durable execution journals, and worker coordination.
+- `simplicio-dev-cli`: focused implementation/test executor that can call `simplicio edit` for deterministic writes once a change is decided.
+- **Agents & Skills**: reusable capabilities from `.skills/`, `.agents/`, and the Simplicio starter (AGENTS.md, specs-as-code, etc.).
 
-This combination is the **official default** across the Simplicio ecosystem. All benchmarks, examples, and documentation assume this full stack.
+This combination is the **official default** across the Simplicio ecosystem. `simplicio-runtime` is the unified future-facing surface, while `simplicio-loop` remains the current production task flow used in company repos.
 
 See the canonical policy:
 - [docs/LLM_USAGE_POLICY.md](docs/LLM_USAGE_POLICY.md)

{simplicio_cli-0.7.1 → simplicio_cli-0.9.0}/README.md

@@ -61,14 +61,18 @@ simplicio-py task "hide the Delete button for non-admins"
 ```mermaid
 flowchart LR
   mapper["simplicio-mapper
-repo context"] --> current["simplicio-cli
-this project"]
-  prompt["simplicio-prompt
-reasoning runtime"] --> current
+repo context"] --> runtime["simplicio-runtime
+task and MCP surface"]
+  loop["simplicio-loop
+proven task flow"] --> runtime
+  runtime --> current["simplicio-cli
+focused implementation"]
+  current --> edit["simplicio edit
+mechanical writes"]
   current --> evidence["validated evidence
 tests, docs, screenshots"]
-  current --> sprint["simplicio-sprint
-delivery loop"]
+  runtime --> sprint["simplicio-sprint
+delivery status"]
 ```
 
 ## Proof and validation
@@ -80,8 +84,9 @@ delivery loop"]
 ## Simplicio ecosystem
 
 - [simplicio-mapper](https://github.com/wesleysimplicio/simplicio-mapper) supplies repo context before interpretation.
+- [simplicio-runtime](https://github.com/wesleysimplicio/simplicio-runtime) is the canonical task, MCP, and assistant entrypoint.
+- [simplicio-loop](https://github.com/wesleysimplicio/simplicio-loop) is the proven task-flow reference the runtime reuses for evidence-gated execution.
 - [simplicio-cli](https://github.com/wesleysimplicio/simplicio-dev-cli) executes focused code tasks with verification.
-- [simplicio-prompt](https://github.com/wesleysimplicio/simplicio-prompt) provides fan-out and consensus runtime patterns.
 - [simplicio-sprint](https://github.com/wesleysimplicio/simplicio-sprint) turns cards into draft PR delivery loops.
 
 ## Documentation standard
@@ -114,15 +119,16 @@ pip install simplicio-cli
 ---
 ### Recommended Default Stack (Official)
 
-The recommended and supported way to use `simplicio-dev-cli` is as part of the full Simplicio execution stack:
+The recommended and supported way to use `simplicio-dev-cli` is inside the runtime-first Simplicio execution stack:
 
-**simplicio-dev-cli + simplicio-prompt + agents/skills**
+**simplicio-runtime + simplicio-loop + simplicio-dev-cli + agents/skills**
 
-- `simplicio-dev-cli`: 6-layer contract, verification loop, and core task execution.
-- `simplicio-prompt`: Subagent runtime, fan-out, behavior consensus aggregator, and advanced orchestration.
-- **Agents & Skills**: Reusable capabilities from `.skills/`, `.agents/`, and the Simplicio starter (AGENTS.md, specs-as-code, etc.).
+- `simplicio-runtime`: canonical task, MCP, and assistant entrypoint.
+- `simplicio-loop`: the proven converge/drain task flow used today; runtime reuses it as the reference discipline for evidence-gated completion, durable execution journals, and worker coordination.
+- `simplicio-dev-cli`: focused implementation/test executor that can call `simplicio edit` for deterministic writes once a change is decided.
+- **Agents & Skills**: reusable capabilities from `.skills/`, `.agents/`, and the Simplicio starter (AGENTS.md, specs-as-code, etc.).
 
-This combination is the **official default** across the Simplicio ecosystem. All benchmarks, examples, and documentation assume this full stack.
+This combination is the **official default** across the Simplicio ecosystem. `simplicio-runtime` is the unified future-facing surface, while `simplicio-loop` remains the current production task flow used in company repos.
 
 See the canonical policy:
 - [docs/LLM_USAGE_POLICY.md](docs/LLM_USAGE_POLICY.md)

{simplicio_cli-0.7.1 → simplicio_cli-0.9.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "simplicio-cli"
-version = "0.7.1"
+version = "0.9.0"
 description = "Portable task-to-code pipeline that works with any LLM. Turn a one-line task into a verified code change — diff + test + verify loop. +55 pts on a 156-check benchmark, 21% faster, ~same tokens."
 readme = "README.md"
 license = { text = "MIT" }

simplicio_cli-0.9.0/simplicio/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.9.0"

{simplicio_cli-0.7.1 → simplicio_cli-0.9.0}/simplicio/cli.py

@@ -6,6 +6,8 @@ import argparse
 import json
 import os
 import re
+import shutil
+import subprocess
 import sys
 import time
 from pathlib import Path
@@ -48,7 +50,73 @@ def maybe_autoinstall(cmd: str | None) -> bool:
     return False
 
 
+def _parse_rust_flags(
+    args: list[str],
+) -> tuple[list[str], bool, bool]:
+    """Strip ``--native`` and ``--python`` flags from *args*.
+
+    Returns ``(cleaned_args, native_flag, python_flag)`` where the flags
+    have been removed from the argument list.
+    """
+    cleaned: list[str] = []
+    native = False
+    python = False
+    for a in args:
+        if a == "--native":
+            native = True
+        elif a == "--python":
+            python = True
+        else:
+            cleaned.append(a)
+    return cleaned, native, python
+
+
+def _try_route_via_simplicio(
+    cmd_name: str,
+    args: list[str],
+    *,
+    prefer_native: bool = True,
+    prefer_python: bool = False,
+) -> int | None:
+    """Attempt to route *cmd_name* via the Rust ``simplicio`` binary.
+
+    Returns the exit code if the binary handled the command, or ``None``
+    if the caller should fall back to the Python implementation.
+    """
+    try:
+        from .commands import route_command
+
+        return route_command(
+            cmd_name,
+            args,
+            prefer_native=prefer_native,
+            prefer_python=prefer_python,
+        )
+    except ImportError:
+        return None
+
+
 def _dispatch_nested(argv: list[str]) -> int | None:
+    if argv and argv[0] == "gate":
+        clean_args, native, python = _parse_rust_flags(argv[1:])
+        result = _try_route_via_simplicio(
+            "gate", clean_args, prefer_native=native or not python, prefer_python=python
+        )
+        if result is not None:
+            return result
+        from .commands.gate import main as gate_main
+
+        return gate_main(clean_args)
+    if argv and argv[0] == "nest":
+        clean_args, native, python = _parse_rust_flags(argv[1:])
+        result = _try_route_via_simplicio(
+            "nest", clean_args, prefer_native=native or not python, prefer_python=python
+        )
+        if result is not None:
+            return result
+        from .commands.nest import main as nest_main
+
+        return nest_main(clean_args)
     if argv and argv[0] == "scratch":
         maybe_autoinstall("scratch")
         from .scratch.cli import main as scratch_main
@@ -479,10 +547,56 @@ def _write_sprint_state(
     path.write_text(json.dumps(payload, indent=2, sort_keys=True), encoding="utf-8")
 
 
+def _status_claims_gate(payload: dict[str, object]) -> dict[str, object]:
+    """Return a low-risk claim contract for ``status --json`` consumers.
+
+    A persisted sprint state can prove that this adapter recorded a fresh,
+    passing local execution for the tracked sprint flow. It still cannot prove
+    repo-wide green on its own, so downstream consumers must not escalate that
+    broader claim from a single status payload.
+    """
+
+    failed_features = payload.get("failed_features")
+    failed_dod_gates = payload.get("failed_dod_gates")
+    state = payload.get("state") or ("complete" if payload.get("complete") else "in-progress")
+    has_fresh_passing_state = (
+        bool(payload.get("complete"))
+        and state == "complete"
+        and not failed_features
+        and not failed_dod_gates
+    )
+    if not has_fresh_passing_state:
+        return {
+            "allow_fresh_verification_claim": False,
+            "allow_repo_green_claim": False,
+            "proof_scope": "none",
+            "reason": "fresh passing verification evidence is not available",
+        }
+    return {
+        "allow_fresh_verification_claim": True,
+        "allow_repo_green_claim": False,
+        "proof_scope": "sprint_state",
+        "reason": (
+            "last passing evidence came from the stored sprint state; "
+            "it does not prove repo-wide green"
+        ),
+    }
+
+
 def _run_status_command(a: argparse.Namespace) -> int:
-    state_path = Path(a.root) / ".simplicio" / "sprint_state.json"
+    from .mapper import artifact_status
+
+    root = Path(a.root).resolve()
+    state_path = root / ".simplicio" / "sprint_state.json"
     if not state_path.is_file():
-        payload = {"state": "none", "path": str(state_path)}
+        payload = {
+            "schema": "simplicio.dev-cli.status/v1",
+            "root": str(root),
+            "state": "none",
+            "path": str(state_path),
+            "artifacts": artifact_status(root),
+        }
+        payload["claims_gate"] = _status_claims_gate(payload)
         if a.json:
             print(json.dumps(payload, sort_keys=True))
         else:
@@ -493,8 +607,15 @@ def _run_status_command(a: argparse.Namespace) -> int:
     except json.JSONDecodeError as exc:
         print(f"{CLI_PROG} status: invalid state file: {exc}", file=sys.stderr)
         return 2
+    json_payload = {
+        "schema": "simplicio.dev-cli.status/v1",
+        "root": str(root),
+        **payload,
+        "artifacts": artifact_status(root),
+    }
+    json_payload["claims_gate"] = _status_claims_gate(json_payload)
     if a.json:
-        print(json.dumps(payload, sort_keys=True))
+        print(json.dumps(json_payload, sort_keys=True))
         return 0
     completed = payload.get("completed_features", 0)
     total = payload.get("total_features", 0)
@@ -546,6 +667,30 @@ def _run_mechanical_edit_command(a: argparse.Namespace) -> int:
     return 0 if result["status"] == "ok" else 1
 
 
+def _runtime_edit_binary() -> str | None:
+    if os.environ.get("SIMPLICIO_DEV_CLI_NO_RUNTIME_EDIT"):
+        return None
+    return shutil.which("simplicio")
+
+
+def _run_edit_command(a: argparse.Namespace) -> int:
+    runtime = None if a.no_runtime else _runtime_edit_binary()
+    if runtime:
+        cmd = [runtime, "edit", "--plan", a.plan, "--repo", a.root]
+        if a.json:
+            cmd.append("--json")
+        if not a.apply:
+            cmd.append("--dry-run")
+        try:
+            plan_stdin = _read_text_source("-") if a.plan == "-" else None
+            completed = subprocess.run(cmd, input=plan_stdin, text=True)
+        except OSError as exc:
+            print(f"{CLI_PROG} edit: runtime delegation failed ({exc}); using local fallback", file=sys.stderr)
+        else:
+            return completed.returncode
+    return _run_mechanical_edit_command(a)
+
+
 def _run_token_command(a: argparse.Namespace) -> int:
     from .token_primitives import (
         ContextCache,
@@ -612,6 +757,60 @@ def _run_runtime_command(a: argparse.Namespace) -> int:
     return 2
 
 
+def _run_claims_command(a: argparse.Namespace) -> int:
+    from .commands.claims import main as claims_main
+
+    claims_argv = [a.claims_cmd]
+    if a.claims_cmd in {"check", "tag"}:
+        claims_argv.extend(a.statement)
+    elif a.claims_cmd == "report":
+        if a.path:
+            claims_argv += ["--path", a.path]
+        if a.json_file:
+            claims_argv += ["--json", a.json_file]
+        claims_argv.extend(a.claims)
+    return claims_main(claims_argv)
+
+
+def _run_file_command(a: argparse.Namespace) -> int:
+    from .commands.file_read import run as file_read_run
+
+    if a.file_cmd == "read":
+        return file_read_run(a)
+    print(f"{CLI_PROG} file: unsupported command", file=sys.stderr)
+    return 2
+
+
+def _run_test_command(a: argparse.Namespace) -> int:
+    from .commands.test_run import run as test_run_run
+
+    if a.test_cmd == "run":
+        extra_args = a.extra_args
+        if extra_args and extra_args[0] == "--":
+            extra_args = extra_args[1:]
+        # `--cmd` is parsed into `test_program` to avoid colliding with the
+        # top-level subparser's `dest="cmd"`; translate to the attribute
+        # name `commands/test_run.py` expects.
+        a.cmd = a.test_program
+        return test_run_run(a, extra_args)
+    print(f"{CLI_PROG} test: unsupported command", file=sys.stderr)
+    return 2
+
+
+def _run_inspect_command(a: argparse.Namespace) -> int:
+    from .mapper import inspect_target
+
+    payload = {
+        "schema": "simplicio.dev-cli.inspect/v1",
+        **inspect_target(a.root, a.target, goal=a.goal),
+    }
+    if a.json:
+        print(json.dumps(payload, sort_keys=True))
+    else:
+        print(payload["context"])
+    return 0
+
+
 def _run_run_command(a: argparse.Namespace) -> int:
     from .intent import AUTO_CONFIDENCE_THRESHOLD, classify_goal
 
@@ -707,6 +906,23 @@ def main(argv=None):
     p_status.add_argument("--root", default=".")
     p_status.add_argument("--json", action="store_true")
 
+    p_claims = sub.add_parser("claims", help="claims-gate checks and report generation")
+    claims_sub = p_claims.add_subparsers(dest="claims_cmd", required=True)
+    p_claims_check = claims_sub.add_parser("check", help="verify a claim against the 8 rules")
+    p_claims_check.add_argument("statement", nargs="+")
+    p_claims_tag = claims_sub.add_parser("tag", help="suggest MEASURED|CANON|UNVERIFIED")
+    p_claims_tag.add_argument("statement", nargs="+")
+    p_claims_report = claims_sub.add_parser("report", help="generate/load a claims report")
+    p_claims_report.add_argument("claims", nargs="*")
+    p_claims_report.add_argument("--path")
+    p_claims_report.add_argument("--json", dest="json_file")
+
+    p_inspect = sub.add_parser("inspect", help="inspect a target with mapper-backed context")
+    p_inspect.add_argument("target")
+    p_inspect.add_argument("--root", default=".")
+    p_inspect.add_argument("--goal", default="")
+    p_inspect.add_argument("--json", action="store_true")
+
     p_doctor = sub.add_parser(
         "doctor",
         help="check local llama.cpp readiness and dependency freshness",
@@ -735,6 +951,51 @@ def main(argv=None):
     p_mechanical.add_argument("--dry-run", action="store_true")
     p_mechanical.add_argument("--json", action="store_true")
 
+    p_edit = sub.add_parser(
+        "edit",
+        help="apply a mechanical edit plan via simplicio-runtime when available",
+    )
+    p_edit.add_argument("--root", "--repo", dest="root", default=".")
+    p_edit.add_argument("--plan", default="-", help="plan JSON path, or - for stdin")
+    p_edit.add_argument("--apply", action="store_true")
+    p_edit.add_argument("--dry-run", action="store_true")
+    p_edit.add_argument("--json", action="store_true")
+    p_edit.add_argument(
+        "--no-runtime",
+        action="store_true",
+        help="use the Python mechanical-edit fallback instead of delegating to simplicio edit",
+    )
+
+    p_file = sub.add_parser("file", help="read raw file contents")
+    file_sub = p_file.add_subparsers(dest="file_cmd", required=True)
+    p_file_read = file_sub.add_parser(
+        "read", help="print a file's contents, optionally sliced by line range"
+    )
+    p_file_read.add_argument("path")
+    p_file_read.add_argument("--json", action="store_true")
+    p_file_read.add_argument("--start", type=int, default=None, help="1-indexed inclusive start line")
+    p_file_read.add_argument("--end", type=int, default=None, help="1-indexed inclusive end line")
+    p_file_read.add_argument("--max-bytes", type=int, default=None, dest="max_bytes")
+    p_file_read.add_argument("--repo", default=".")
+
+    p_test = sub.add_parser("test", help="run a test command and report results")
+    test_sub = p_test.add_subparsers(dest="test_cmd", required=True)
+    p_test_run = test_sub.add_parser("run", help="run a test command (default: pytest)")
+    p_test_run.add_argument("--cmd", dest="test_program", default="pytest")
+    p_test_run.add_argument("--json", action="store_true")
+    p_test_run.add_argument("--repo", default=".")
+    p_test_run.add_argument(
+        "--timeout",
+        type=float,
+        default=120.0,
+        help="seconds to wait for the test command before giving up (default: 120)",
+    )
+    p_test_run.add_argument(
+        "extra_args",
+        nargs=argparse.REMAINDER,
+        help="extra args passed through to --cmd after a literal --",
+    )
+
     p_token = sub.add_parser("token", help="token-efficient execution primitives")
     token_sub = p_token.add_subparsers(dest="token_cmd", required=True)
     p_log = token_sub.add_parser("log-summary")
@@ -765,6 +1026,45 @@ def main(argv=None):
         p_cache_action.add_argument("--content-file")
     cache_sub.choices["put"].add_argument("--summary-file", required=True)
 
+    p_score_skill = sub.add_parser(
+        "score-skill",
+        help="deterministic SkillOpt-style scorer for skill/law text",
+    )
+    p_score_skill.add_argument(
+        "skill",
+        nargs="?",
+        default="-",
+        help="skill/law text file path, or - for stdin (default: -)",
+    )
+    p_score_skill.add_argument(
+        "--scenario", "-s",
+        dest="scenario_sources",
+        action="append",
+        default=[],
+        help="JSON scenario file path (repeatable); falls back to builtin scenarios",
+    )
+    p_score_skill.add_argument(
+        "--extra-scenario",
+        action="append",
+        default=[],
+        help="inline JSON scenario string (repeatable)",
+    )
+    p_score_skill.add_argument("--json", action="store_true")
+    p_score_skill.add_argument(
+        "--verbose", "-v", action="store_true",
+        help="print per-scenario detail even on success",
+    )
+    p_score_skill.add_argument(
+        "--native",
+        action="store_true",
+        help="force the Rust simplicio binary for this command",
+    )
+    p_score_skill.add_argument(
+        "--python",
+        action="store_true",
+        help="force the Python implementation for this command",
+    )
+
     p_runtime = sub.add_parser("runtime", help="runtime-facing dev-cli contracts")
     runtime_sub = p_runtime.add_subparsers(dest="runtime_cmd", required=True)
     p_runtime_doctor = runtime_sub.add_parser("doctor")
@@ -838,6 +1138,10 @@ def main(argv=None):
         return detect_main(detect_argv)
     elif a.cmd == "status":
         return _run_status_command(a)
+    elif a.cmd == "claims":
+        return _run_claims_command(a)
+    elif a.cmd == "inspect":
+        return _run_inspect_command(a)
     elif a.cmd == "doctor":
         from .doctor import main as doctor_main
 
@@ -873,8 +1177,36 @@ def main(argv=None):
         return 0
     elif a.cmd == "mechanical-edit":
         return _run_mechanical_edit_command(a)
+    elif a.cmd == "edit":
+        return _run_edit_command(a)
+    elif a.cmd == "file":
+        return _run_file_command(a)
+    elif a.cmd == "test":
+        return _run_test_command(a)
     elif a.cmd == "token":
         return _run_token_command(a)
+    elif a.cmd == "score-skill":
+        score_argv = [a.skill]
+        for s in a.scenario_sources:
+            score_argv += ["--scenario", s]
+        for e in a.extra_scenario:
+            score_argv += ["--extra-scenario", e]
+        if a.json:
+            score_argv.append("--json")
+        if a.verbose:
+            score_argv.append("--verbose")
+        # Try Rust binary first, then fall back to Python
+        result = _try_route_via_simplicio(
+            "score-skill",
+            score_argv,
+            prefer_native=a.native or not a.python,
+            prefer_python=a.python,
+        )
+        if result is not None:
+            return result
+        from .commands.score_skill import main as score_skill_main
+
+        return score_skill_main(score_argv)
     elif a.cmd == "runtime":
         return _run_runtime_command(a)
     elif a.cmd == "task":

simplicio_cli-0.9.0/simplicio/commands/__init__.py

@@ -0,0 +1,63 @@
+"""simplicio-dev-cli command modules.
+
+Command routing — dispatches ``gate``, ``nest``, and ``score-skill``
+commands to the native Rust ``simplicio`` binary when available, with
+automatic fallback to the Python implementation.
+"""
+
+from __future__ import annotations
+
+from ..runtime_bridge import call_simplicio, simplicio_available, use_native_implementation
+
+
+def route_command(
+    cmd_name: str,
+    args: list[str],
+    *,
+    prefer_native: bool = True,
+    prefer_python: bool = False,
+) -> int | None:
+    """Route a command to the Rust binary or return ``None`` for Python fallback.
+
+    When the Rust binary is available and *prefer_native* is ``True``, the
+    command is executed via ``subprocess`` against the native ``simplicio``
+    binary and its exit code is returned immediately.
+
+    When Rust is unavailable or *prefer_python* is ``True``, the function
+    returns ``None`` so the caller can invoke the Python implementation.
+
+    Parameters
+    ----------
+    cmd_name:
+        Subcommand name (e.g. ``"gate"``, ``"nest"``, ``"score-skill"``).
+    args:
+        Remaining command-line arguments for the subcommand.
+    prefer_native:
+        Whether to prefer the Rust binary when available (default ``True``).
+    prefer_python:
+        Force the Python fallback even when Rust is available (default ``False``).
+
+    Returns
+    -------
+    Exit code (``int``) when the Rust binary handled the command, or
+    ``None`` if the caller should fall back to the Python implementation.
+    """
+    if not use_native_implementation(
+        prefer_native=prefer_native, prefer_python=prefer_python
+    ):
+        return None
+
+    try:
+        result = call_simplicio([cmd_name, *args])
+    except RuntimeError:
+        return None
+    except FileNotFoundError:
+        return None
+
+    # Forward the Rust binary's output to the user
+    if result.stdout:
+        print(result.stdout, end="")
+    if result.stderr:
+        print(result.stderr, end="", file=__import__("sys").stderr)
+
+    return result.returncode