specfact-cli 0.40.1__tar.gz → 0.40.3__tar.gz

{specfact_cli-0.40.1 → specfact_cli-0.40.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specfact-cli
-Version: 0.40.1
+Version: 0.40.3
 Summary: The swiss knife CLI for agile DevOps teams. Keep backlog, specs, tests, and code in sync with validation and contract enforcement for new projects and long-lived codebases.
 Project-URL: Homepage, https://github.com/nold-ai/specfact-cli
 Project-URL: Repository, https://github.com/nold-ai/specfact-cli.git
@@ -353,6 +353,8 @@ As of `0.40.0`, flat root commands are removed. Use grouped commands:
 ### Backlog Bridge (60 seconds)
 
 SpecFact's USP is closing the drift gap between **backlog -> specs -> code**.
+These commands require the backlog bundle to be installed first, for example via
+`specfact init --profile backlog-team` or `specfact init --install backlog`.
 
 ```bash
 # 1) Initialize backlog config + field mapping

{specfact_cli-0.40.1 → specfact_cli-0.40.3}/README.md

@@ -74,6 +74,8 @@ As of `0.40.0`, flat root commands are removed. Use grouped commands:
 ### Backlog Bridge (60 seconds)
 
 SpecFact's USP is closing the drift gap between **backlog -> specs -> code**.
+These commands require the backlog bundle to be installed first, for example via
+`specfact init --profile backlog-team` or `specfact init --install backlog`.
 
 ```bash
 # 1) Initialize backlog config + field mapping

{specfact_cli-0.40.1 → specfact_cli-0.40.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "specfact-cli"
-version = "0.40.1"
+version = "0.40.3"
 description = "The swiss knife CLI for agile DevOps teams. Keep backlog, specs, tests, and code in sync with validation and contract enforcement for new projects and long-lived codebases."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -388,7 +388,6 @@ sources = ["src"]
 "resources/schemas" = "specfact_cli/resources/schemas"
 "resources/mappings" = "specfact_cli/resources/mappings"
 "resources/keys" = "specfact_cli/resources/keys"
-"modules/backlog-core" = "specfact_cli/modules/backlog-core"
 "modules/bundle-mapper" = "specfact_cli/modules/bundle-mapper"
 # Note: resources/semgrep files are in src/specfact_cli/resources/semgrep/ and are automatically included
 

{specfact_cli-0.40.1 → specfact_cli-0.40.3}/src/__init__.py

@@ -3,4 +3,4 @@ SpecFact CLI - Spec→Contract→Sentinel tool for contract-driven development.
 """
 
 # Package version: keep in sync with pyproject.toml, setup.py, src/specfact_cli/__init__.py
-__version__ = "0.40.1"
+__version__ = "0.40.3"

{specfact_cli-0.40.1 → specfact_cli-0.40.3}/src/specfact_cli/__init__.py

@@ -42,6 +42,6 @@ def _bootstrap_bundle_paths() -> None:
 
 _bootstrap_bundle_paths()
 
-__version__ = "0.40.1"
+__version__ = "0.40.3"
 
 __all__ = ["__version__"]

{specfact_cli-0.40.1 → specfact_cli-0.40.3}/src/specfact_cli/adapters/ado.py

@@ -3414,6 +3414,21 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
                 }
             )
 
+        provider_fields = payload.get("provider_fields")
+        provider_field_values = provider_fields.get("fields") if isinstance(provider_fields, dict) else None
+        if isinstance(provider_field_values, dict):
+            for field_name, field_value in provider_field_values.items():
+                normalized_field = str(field_name).strip()
+                if not normalized_field:
+                    continue
+                patch_document.append(
+                    {
+                        "op": "add",
+                        "path": f"/fields/{normalized_field}",
+                        "value": field_value,
+                    }
+                )
+
         sprint = str(payload.get("sprint") or "").strip()
         if sprint:
             patch_document.append(

specfact_cli-0.40.3/src/specfact_cli/backlog/__init__.py

@@ -0,0 +1,14 @@
+"""Shared backlog conversion helpers retained by core adapters."""
+
+from __future__ import annotations
+
+from specfact_cli.backlog.converter import (
+    convert_ado_work_item_to_backlog_item,
+    convert_github_issue_to_backlog_item,
+)
+
+
+__all__ = [
+    "convert_ado_work_item_to_backlog_item",
+    "convert_github_issue_to_backlog_item",
+]

specfact_cli-0.40.3/src/specfact_cli/backlog/adapters/__init__.py

@@ -0,0 +1,8 @@
+"""Backlog adapter contracts retained by core provider integrations."""
+
+from __future__ import annotations
+
+from specfact_cli.backlog.adapters.base import BacklogAdapter
+
+
+__all__ = ["BacklogAdapter"]

{specfact_cli-0.40.1 → specfact_cli-0.40.3}/src/specfact_cli/common/logger_setup.py

@@ -396,6 +396,7 @@ class LoggerSetup:
         use_rotating_file: bool = True,
         append_mode: bool = True,
         preserve_test_format: bool = False,
+        emit_to_console: bool = True,
     ) -> logging.Logger:
         """
         Creates a new logger or returns an existing one with the specified configuration.
@@ -513,15 +514,20 @@ class LoggerSetup:
             with contextlib.suppress(Exception):
                 logger.info("[LoggerSetup] File logger initialized: %s", log_file_path)
         else:
-            # If no log file is specified, set up a listener with a console handler
+            # If no log file is specified, stream to console only when explicitly requested.
             log_queue = Queue(-1)
             cls._log_queues[logger_name] = log_queue
 
-            console_handler = logging.StreamHandler(_safe_console_stream())
-            console_handler.setFormatter(log_format)
-            console_handler.setLevel(level)
+            sink_handler: logging.Handler
+            if emit_to_console:
+                sink_handler = logging.StreamHandler(_safe_console_stream())
+                sink_handler.setFormatter(log_format)
+                sink_handler.setLevel(level)
+            else:
+                sink_handler = logging.NullHandler()
+                sink_handler.setLevel(level)
 
-            listener = QueueListener(log_queue, console_handler, respect_handler_level=True)
+            listener = QueueListener(log_queue, sink_handler, respect_handler_level=True)
             listener.start()
             cls._log_listeners[logger_name] = listener
 

{specfact_cli-0.40.1 → specfact_cli-0.40.3}/src/specfact_cli/common/logging_utils.py

@@ -38,4 +38,10 @@ def _try_common_logger(name: str, level: str) -> logging.Logger | None:
         from specfact_cli.common.logger_setup import LoggerSetup  # type: ignore[import]
     except ImportError:
         return None
-    return LoggerSetup.create_logger(name, log_level=level)
+    try:
+        from specfact_cli.runtime import is_debug_mode  # type: ignore[import]
+
+        emit_to_console = is_debug_mode()
+    except ImportError:
+        emit_to_console = False
+    return LoggerSetup.create_logger(name, log_level=level, emit_to_console=emit_to_console)

{specfact_cli-0.40.1 → specfact_cli-0.40.3}/src/specfact_cli/groups/__init__.py

@@ -1,8 +1,7 @@
-"""Category group commands: project, backlog, code, spec, govern."""
+"""Category group commands: project, code, spec, govern."""
 
 from __future__ import annotations
 
-from specfact_cli.groups.backlog_group import app as backlog_app
 from specfact_cli.groups.codebase_group import app as codebase_app
 from specfact_cli.groups.govern_group import app as govern_app
 from specfact_cli.groups.project_group import app as project_app
@@ -10,7 +9,6 @@ from specfact_cli.groups.spec_group import app as spec_app
 
 
 __all__ = [
-    "backlog_app",
     "codebase_app",
     "govern_app",
     "project_app",

specfact_cli-0.40.3/src/specfact_cli/groups/member_group.py

@@ -0,0 +1,60 @@
+"""Generic category group builder for bundle-owned command surfaces."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import typer
+from beartype import beartype
+from icontract import ensure, require
+
+from specfact_cli.registry.registry import CommandRegistry
+
+
+@require(lambda app: app is not None)
+@beartype
+def _register_members(app: typer.Typer, members: Sequence[tuple[str, str]]) -> int:
+    """Register member module sub-apps and return how many were added."""
+    added = 0
+    for display_name, cmd_name in members:
+        try:
+            member_app = CommandRegistry.get_module_typer(cmd_name)
+            if member_app is not None:
+                app.add_typer(member_app, name=display_name)
+                added += 1
+        except ValueError:
+            continue
+    return added
+
+
+@require(lambda name: isinstance(name, str) and len(name) > 0)
+@require(lambda help_text: isinstance(help_text, str) and len(help_text) > 0)
+@ensure(lambda result: isinstance(result, typer.Typer))
+@beartype
+def build_member_group(
+    *,
+    name: str,
+    help_text: str,
+    members: Sequence[tuple[str, str]],
+    flatten_same_name: str | None = None,
+    install_hint_module: str | None = None,
+) -> typer.Typer:
+    """Build a lazy category group from registered member modules."""
+    app = typer.Typer(name=name, help=help_text, no_args_is_help=True)
+    added = _register_members(app, members)
+
+    if added == 0 and install_hint_module:
+        placeholder = typer.Typer(help=f"{help_text} (module not loaded).")
+
+        @placeholder.command("install")
+        def _install_hint() -> None:
+            from specfact_cli.utils.prompts import print_warning
+
+            print_warning(f"No {name} module loaded. Install with: specfact module install {install_hint_module}")
+
+        app.add_typer(placeholder, name=name)
+
+    if flatten_same_name:
+        app._specfact_flatten_same_name = flatten_same_name
+
+    return app

{specfact_cli-0.40.1 → specfact_cli-0.40.3}/src/specfact_cli/modules/module_registry/module-package.yaml

@@ -1,5 +1,5 @@
 name: module-registry
-version: 0.1.9
+version: 0.1.10
 commands:
   - module
 category: core
@@ -17,5 +17,5 @@ publisher:
 description: 'Manage modules: search, list, show, install, and upgrade.'
 license: Apache-2.0
 integrity:
-  checksum: sha256:d8d4103bfe44bc638fd5affa2734bbb063f9c86f2873055f745beca9ee0a9db3
-  signature: OJtCXdfZfnLZhB543+ODtFRXgyYamZk6xrvLfHubE+kwU+jCPWaZDJ83YqheuR7kQlqMlRue5UZb3DbOu4pwBQ==
+  checksum: sha256:85e40c4c083982f0bab2bde2a27a08a4e6832fe6d93ae3d62c4659c138fd6295
+  signature: INFP+nx7iPCqZPnGIwB39L6GpckB16+EqPwaPW/kwwBtlLBX9RaZ1DcMbhu5f6tPqjA9sETRMBtrQ5GiBbVfCQ==

{specfact_cli-0.40.1 → specfact_cli-0.40.3}/src/specfact_cli/modules/module_registry/src/commands.py

@@ -7,6 +7,7 @@ import shutil
 from pathlib import Path
 
 import typer
+import yaml
 from beartype import beartype
 from rich.console import Console
 from rich.table import Table
@@ -39,6 +40,20 @@ app = typer.Typer(help="Manage marketplace modules")
 console = Console()
 
 
+def _read_installed_module_version(module_dir: Path) -> str:
+    """Read installed module version from its manifest, if available."""
+    manifest_path = module_dir / "module-package.yaml"
+    if not manifest_path.exists():
+        return "unknown"
+    try:
+        loaded = yaml.safe_load(manifest_path.read_text(encoding="utf-8"))
+    except Exception:
+        return "unknown"
+    if not isinstance(loaded, dict):
+        return "unknown"
+    return str(loaded.get("version", "unknown"))
+
+
 def _publisher_from_module_id(module_id: str) -> str:
     """Extract normalized publisher namespace from module id."""
     return module_id.split("/", 1)[0].strip().lower() if "/" in module_id else ""
@@ -803,19 +818,22 @@ def upgrade(
             # If module isn't discovered locally, still attempt marketplace install/upgrade by ID.
             target_ids = [prefixed]
 
-    upgraded: list[str] = []
+    upgraded: list[tuple[str, str, str]] = []
     failed: list[str] = []
     for target in target_ids:
         try:
             module_id = target if "/" in target else f"specfact/{target}"
-            install_module(module_id, reinstall=True)
-            upgraded.append(module_id)
+            previous_version = str(by_id.get(target, {}).get("version", "unknown"))
+            installed_path = install_module(module_id, reinstall=True)
+            upgraded.append((module_id, previous_version, _read_installed_module_version(installed_path)))
         except Exception as exc:
             console.print(f"[red]Failed upgrading {target}: {exc}[/red]")
             failed.append(target)
 
     if upgraded:
-        console.print(f"[green]Upgraded[/green] {', '.join(upgraded)}")
+        console.print("[green]Upgraded:[/green]")
+        for module_id, previous_version, new_version in upgraded:
+            console.print(f"  {module_id}: {previous_version} -> {new_version}")
     if failed:
         raise typer.Exit(1)
 

{specfact_cli-0.40.1 → specfact_cli-0.40.3}/src/specfact_cli/registry/module_discovery.py

@@ -56,7 +56,14 @@ def discover_all_modules(
     effective_custom_root = custom_root or CUSTOM_MODULES_ROOT
 
     roots: list[tuple[str, Path]] = [("builtin", effective_builtin_root)]
+    project_matches_user_root = False
     if effective_project_root is not None:
+        try:
+            project_matches_user_root = effective_project_root.resolve() == effective_user_root.resolve()
+        except OSError:
+            project_matches_user_root = effective_project_root == effective_user_root
+
+    if effective_project_root is not None and not project_matches_user_root:
         roots.append(("project", effective_project_root))
     roots.extend(
         [

{specfact_cli-0.40.1 → specfact_cli-0.40.3}/src/specfact_cli/registry/module_installer.py

@@ -730,7 +730,7 @@ def install_module(
                 dependency_manifest = target_root / dependency_name / "module-package.yaml"
                 if dependency_manifest.exists():
                     dependency_version = _installed_dependency_version(dependency_manifest)
-                    logger.warning(
+                    logger.info(
                         "Dependency %s already satisfied (version %s)", dependency_module_id, dependency_version
                     )
                     continue

{specfact_cli-0.40.1 → specfact_cli-0.40.3}/src/specfact_cli/registry/module_packages.py

@@ -879,14 +879,24 @@ def get_installed_bundles(
 
 # Bundle name -> (group_name, help_str, build_app_fn) for conditional category mounting.
 def _build_bundle_to_group() -> dict[str, tuple[str, str, Any]]:
-    from specfact_cli.groups.backlog_group import build_app as build_backlog_app
     from specfact_cli.groups.codebase_group import build_app as build_codebase_app
     from specfact_cli.groups.govern_group import build_app as build_govern_app
+    from specfact_cli.groups.member_group import build_member_group
     from specfact_cli.groups.project_group import build_app as build_project_app
     from specfact_cli.groups.spec_group import build_app as build_spec_app
 
     return {
-        "specfact-backlog": ("backlog", "Backlog and policy commands.", build_backlog_app),
+        "specfact-backlog": (
+            "backlog",
+            "Backlog and policy commands.",
+            lambda: build_member_group(
+                name="backlog",
+                help_text="Backlog and policy commands.",
+                members=(("backlog", "backlog"), ("policy", "policy")),
+                flatten_same_name="backlog",
+                install_hint_module="nold-ai/specfact-backlog",
+            ),
+        ),
         "specfact-codebase": (
             "code",
             "Codebase quality commands: analyze, drift, validate, repro.",
@@ -1171,26 +1181,20 @@ def register_module_package_commands(
     if category_grouping_enabled:
         _mount_installed_category_groups(packages, enabled_map)
     discovered_count = protocol_full + protocol_partial + protocol_legacy
-    if discovered_count and (protocol_partial > 0 or protocol_legacy > 0):
-        print_warning(
-            "Module compatibility check: "
-            f"{protocol_full + protocol_partial}/{discovered_count} compliant "
-            f"(full={protocol_full}, partial={protocol_partial}, legacy={protocol_legacy})."
+    if discovered_count and (protocol_partial > 0 or protocol_legacy > 0) and is_debug_mode():
+        logger.info(
+            "Module compatibility check: %s/%s compliant (full=%s, partial=%s, legacy=%s)",
+            protocol_full + protocol_partial,
+            discovered_count,
+            protocol_full,
+            protocol_partial,
+            protocol_legacy,
         )
         if partial_modules:
             partial_desc = ", ".join(f"{name} ({'/'.join(ops)})" for name, ops in sorted(partial_modules))
-            print_warning(f"Partially compliant modules: {partial_desc}")
+            logger.info("Partially compliant modules: %s", partial_desc)
         if legacy_modules:
-            print_warning(f"Legacy modules: {', '.join(sorted(set(legacy_modules)))}")
-        if is_debug_mode():
-            logger.info(
-                "Protocol-compliant: %s/%s modules (Full=%s, Partial=%s, Legacy=%s)",
-                protocol_full + protocol_partial,
-                discovered_count,
-                protocol_full,
-                protocol_partial,
-                protocol_legacy,
-            )
+            logger.info("Legacy modules: %s", ", ".join(sorted(set(legacy_modules))))
     for module_id, reason in skipped:
         logger.debug("Skipped module '%s': %s", module_id, reason)
 

{specfact_cli-0.40.1 → specfact_cli-0.40.3}/src/specfact_cli/utils/ide_setup.py

@@ -121,10 +121,6 @@ SPECFACT_COMMANDS = [
     "specfact.06-sync",
     "specfact.07-contracts",
     "specfact.compare",
-    "specfact.sync-backlog",
-    "specfact.backlog-daily",
-    "specfact.backlog-refine",
-    "specfact.backlog-add",
     "specfact.validate",
 ]
 

specfact_cli-0.40.3/src/specfact_cli/validation/__init__.py

@@ -0,0 +1,14 @@
+"""Validation helpers for release and command-surface audits."""
+
+from specfact_cli.validation.command_audit import (
+    CommandAuditCase,
+    build_command_audit_cases,
+    official_marketplace_module_ids,
+)
+
+
+__all__ = [
+    "CommandAuditCase",
+    "build_command_audit_cases",
+    "official_marketplace_module_ids",
+]

specfact_cli-0.40.3/src/specfact_cli/validation/command_audit.py

@@ -0,0 +1,165 @@
+"""Helpers for command-package runtime validation."""
+
+from __future__ import annotations
+
+import importlib
+import os
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+
+AuditMode = Literal["help-only", "fixture-backed", "dry-run"]
+
+
+@dataclass(frozen=True)
+class CommandAuditCase:
+    """One command-path audit case."""
+
+    command_path: str
+    argv: tuple[str, ...]
+    phase: str
+    mode: AuditMode
+    owner: str
+
+
+def _resolve_modules_repo_root() -> Path | None:
+    configured = os.environ.get("SPECFACT_MODULES_REPO", "").strip()
+    if configured:
+        candidate = Path(configured).expanduser().resolve()
+        if candidate.exists():
+            return candidate
+
+    current = Path(__file__).resolve()
+    for parent in current.parents:
+        sibling = parent.parent / "specfact-cli-modules"
+        if sibling.exists():
+            return sibling.resolve()
+        direct = parent / "specfact-cli-modules"
+        if direct.exists():
+            return direct.resolve()
+    return None
+
+
+def _ensure_bundle_sources_on_sys_path() -> None:
+    modules_repo = _resolve_modules_repo_root()
+    if modules_repo is None:
+        return
+    packages_root = modules_repo / "packages"
+    if not packages_root.exists():
+        return
+    for bundle_src in packages_root.glob("*/src"):
+        bundle_src_str = str(bundle_src.resolve())
+        if bundle_src_str not in sys.path:
+            sys.path.insert(0, bundle_src_str)
+
+
+def _command_info_name(command_info: object) -> str:
+    explicit_name = getattr(command_info, "name", None)
+    if isinstance(explicit_name, str) and explicit_name:
+        return explicit_name
+    callback = getattr(command_info, "callback", None)
+    callback_name = getattr(callback, "__name__", "")
+    return callback_name.replace("_", "-") if callback_name else ""
+
+
+def _collect_typer_paths(app: object, prefix: str) -> set[str]:
+    paths: set[str] = set()
+
+    for command_info in list(getattr(app, "registered_commands", [])):
+        command_name = _command_info_name(command_info)
+        if command_name:
+            paths.add(f"{prefix} {command_name}")
+
+    for group_info in list(getattr(app, "registered_groups", [])):
+        group_name = getattr(group_info, "name", "") or ""
+        if not group_name:
+            nested_app = getattr(group_info, "typer_instance", None)
+            nested_info = getattr(nested_app, "info", None) if nested_app is not None else None
+            group_name = getattr(nested_info, "name", "") or ""
+        if not group_name:
+            continue
+        group_prefix = f"{prefix} {group_name}"
+        paths.add(group_prefix)
+        nested_app = getattr(group_info, "typer_instance", None)
+        if nested_app is not None:
+            paths.update(_collect_typer_paths(nested_app, group_prefix))
+
+    return paths
+
+
+def _import_typer(module_path: str, attr_name: str = "app") -> object:
+    module = importlib.import_module(module_path)
+    return getattr(module, attr_name)
+
+
+def official_marketplace_module_ids() -> tuple[str, ...]:
+    """Return the official marketplace module ids that make up the full CLI surface."""
+    return (
+        "nold-ai/specfact-project",
+        "nold-ai/specfact-spec",
+        "nold-ai/specfact-codebase",
+        "nold-ai/specfact-backlog",
+        "nold-ai/specfact-govern",
+    )
+
+
+def _explicit_cases() -> list[CommandAuditCase]:
+    return [
+        CommandAuditCase("specfact", ("--help",), "root", "help-only", "specfact-core"),
+        CommandAuditCase("project", ("project", "--help"), "project", "help-only", "nold-ai/specfact-project"),
+        CommandAuditCase("spec", ("spec", "--help"), "spec", "help-only", "nold-ai/specfact-spec"),
+        CommandAuditCase("code", ("code", "--help"), "code", "help-only", "nold-ai/specfact-codebase"),
+        CommandAuditCase("backlog", ("backlog", "--help"), "backlog", "help-only", "nold-ai/specfact-backlog"),
+        CommandAuditCase("govern", ("govern", "--help"), "govern", "help-only", "nold-ai/specfact-govern"),
+        CommandAuditCase(
+            "module init", ("module", "init", "--scope", "user"), "core", "fixture-backed", "specfact-core"
+        ),
+        CommandAuditCase("module search", ("module", "search", "specfact"), "core", "fixture-backed", "specfact-core"),
+        CommandAuditCase("module list", ("module", "list", "--show-origin"), "core", "fixture-backed", "specfact-core"),
+        CommandAuditCase(
+            "module show",
+            ("module", "show", "nold-ai/specfact-backlog"),
+            "core",
+            "fixture-backed",
+            "specfact-core",
+        ),
+    ]
+
+
+def build_command_audit_cases() -> list[CommandAuditCase]:
+    """Build the full command audit matrix for core and official bundle command paths."""
+    _ensure_bundle_sources_on_sys_path()
+    app_specs = [
+        ("specfact_cli.modules.init.src.commands", "init", "core", "specfact-core", "import"),
+        ("specfact_cli.modules.module_registry.src.commands", "module", "core", "specfact-core", "import"),
+        ("specfact_cli.modules.upgrade.src.commands", "upgrade", "core", "specfact-core", "import"),
+        ("specfact_project.project.commands", "project", "project", "nold-ai/specfact-project", "import"),
+        ("specfact_spec.spec.commands", "spec", "spec", "nold-ai/specfact-spec", "import"),
+        ("specfact_codebase.code.commands", "code", "code", "nold-ai/specfact-codebase", "import"),
+        ("specfact_backlog.backlog.commands", "backlog", "backlog", "nold-ai/specfact-backlog", "import"),
+        ("specfact_govern.govern.commands", "govern", "govern", "nold-ai/specfact-govern", "import"),
+    ]
+
+    cases: dict[str, CommandAuditCase] = {case.command_path: case for case in _explicit_cases()}
+    for module_path, prefix, phase, owner, _load_mode in app_specs:
+        app = _import_typer(module_path)
+        cases.setdefault(
+            prefix,
+            CommandAuditCase(prefix, (*tuple(prefix.split()), "--help"), phase, "help-only", owner),
+        )
+        for command_path in sorted(_collect_typer_paths(app, prefix)):
+            cases.setdefault(
+                command_path,
+                CommandAuditCase(
+                    command_path,
+                    (*tuple(command_path.split()), "--help"),
+                    phase,
+                    "help-only",
+                    owner,
+                ),
+            )
+
+    phase_order = {"root": 0, "core": 1, "project": 2, "spec": 3, "code": 4, "backlog": 5, "govern": 6}
+    return sorted(cases.values(), key=lambda case: (phase_order.get(case.phase, 99), case.command_path))