roadmap-cli 0.2.0__tar.gz → 0.3.1__tar.gz

{roadmap_cli-0.2.0 → roadmap_cli-0.3.1}/.gitignore

@@ -254,6 +254,7 @@ test_sync_init/*.lock
 /tmp/test_check_sync/*.tmp
 /tmp/test_check_sync/*.lock
 sync_git_state.txt
+/output.txt
 
 # design notes, AI prompts, etc.
 

roadmap_cli-0.3.1/CHANGELOG.md

@@ -0,0 +1,224 @@
+# Changelog
+
+All notable changes to Roadmap CLI are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and releases follow
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.3.1] - 2026-10-08
+
+### Added
+
+- Add CI gates for high-confidence dead code and active documentation links,
+  with negative fixtures proving rejected inputs.
+
+- Add branch-outcome regressions for migration refusals, canonical transaction
+  failure/retry, planning idempotency, aggregate invariants and scoped issue-list
+  workload output.
+
+- Add scoped requirement verification records, fail-closed evidence policy and
+  an executable maintainer handover runbook with a current release checklist.
+
+- Add explicit workspace selection, JSON entity inspection with issue history,
+  project/milestone ID-only creation, nullable-field clearing, issue due dates and
+  label edits, project owner/priority controls, and stderr-only operational verbosity.
+- Add a reviewed command/option evidence matrix and a guard against CLI drift.
+
+- Add global `--debug` tracebacks for unexpected CLI failures. Configuration
+  access errors no longer silently use defaults; command import failures remain
+  errors. Log projection refresh exceptions with Python logging and send repair
+  warnings to stderr.
+- Show candidate IDs and labels for ambiguous issue/project/milestone lookups.
+- Explain effective configuration values, owning scope, and default/configured
+  source with `config explain KEY [--format json]`.
+- Print only the created issue ID with `issue create --print-id`, keeping
+  warnings and branch notifications on stderr.
+- Show repair-preview commands in plain health output and document built-in
+  shell completion.
+
+### Changed
+
+- Replace deprecated Click filesystem isolation in tests with pytest-managed
+  temporary workspaces, remove retired coverage exclusions, and enable Bandit's
+  try/except/pass rule instead of suppressing it globally.
+
+- Raise the statement-coverage floor to 90% after real-storage CLI safety journeys.
+
+- Replace the hand-written import graph checker with Import Linter contracts
+  and narrow namespace/core dependency guards; raise the coverage floor to 87%.
+
+- Standardize type checking on ty and remove Pyright and unused pytest plugins;
+  consolidate development dependencies into the dev extra.
+- Run architecture checks in pre-commit, retain CI coverage evidence, and
+  require the full CI workflow before a release can publish.
+
+### Fixed
+
+- Correct the empty issue-list creation hint to include the required `--title`
+  option, with a CLI regression proving the suggested command works.
+
+- Refuse migration when canonical directories cannot be enumerated or a personal
+  configuration schema version is boolean; protect changed migration previews
+  and prove projection failure rollback/retry with regression tests.
+- Distinguish unpublished master behavior from PyPI 0.3.0 and correct the package
+  documentation URL to the actual default branch.
+
+- Refuse dry-run recovery writes and parent-close guard bypasses; reject explicit
+  branch options without branch action before canonical writes.
+- Preserve literal machine output, independent sort directions and empty CSV
+  headers; validate output options and export enums even when results are empty.
+- Honor empty-analysis destinations and health summary-only across formats.
+- Require explicit bounded health repair targets. Prefer `--format`, `--yes` and
+  `milestone progress`; warn on deprecated spellings through 0.3, retire in 0.4.
+  Archive keeps a lifecycle override; its legacy force-as-consent shortcut is
+  explicitly deprecated, as is project close's shortcut. Init force is deprecated
+  because initialization is idempotent and never overwrites canonical data.
+
+- Keep broken-reference health findings visible when filtering by entity, with
+  workspace-relative scopes and an accurate unhealthy exit code.
+- Validate manually edited configuration values using the same type rules as
+  scoped writes; reject boolean schema versions without rewriting input.
+- Treat duplicate project/milestone names as ambiguous and list candidates.
+
+- Preserve successful canonical mutation results when post-commit cleanup or
+  projection stale-marker persistence fails; retry journals on reopen.
+- Reject symlinked backup directories/files and anchor cleanup deletion to a
+  directory descriptor, including revalidation after confirmation.
+- Fail canonical scans on unreadable directories instead of treating them as
+  empty, and block projection repair when enumeration fails.
+
+- Refuse recovery preview and projection repair when transaction journals
+  cannot be inspected, instead of silently treating them as absent.
+- Validate complete recovery journals and snapshot integrity before replay;
+  preserve post-interruption manual edits and reject unsafe snapshot paths.
+- Release workspace locks when recovery or lock-metadata persistence fails.
+- Persist transaction snapshots and preparation/cleanup boundaries; preserve
+  rollback intent when an ordinary write failure cannot finish restoration.
+- Rebuild missing projections when retrying a migration interrupted after
+  canonical commit.
+- Explicitly select locked development dependencies for CI and pre-commit
+  checks and the documented contributor commands.
+
+### Added
+
+- Reliability coverage for deletion guards, reciprocal dependency edits,
+  populated backup cleanup, malformed canonical input, and repair refusal.
+- A maintainer continuity/inactivity policy and a review closeout record that
+  distinguishes local verification from remote CI and independent review.
+- A required CI audit of locked runtime/development dependencies using pinned
+  pip-audit, in addition to GitHub's Dependabot monitoring.
+- Reliability tests covering actual process termination, separate writers,
+  filesystem replacement failures, recovery conflicts, and installed CLI
+  repair, plus a recovery guide and guarantee-to-test evidence map.
+
+## [0.3.0] - 2026-09-02
+
+### Changed
+
+- Migrated static type checking from Pyright-only to `ty` running alongside
+  Pyright, both enforced in CI and pre-commit; aligned their configured
+  Python-version floor with the declared `>=3.12` support range.
+- Reduced cyclomatic complexity across the codebase and enforced a
+  xenon B-or-better gate (absolute, per-module, and average) in CI and
+  pre-commit.
+- Raised the enforced test coverage floor from 78% to 85%, backed by a
+  targeted test-coverage sweep (CLI output formatting and issue query
+  presentation) that reached 85.70%.
+- Reduced DRY violations identified during the complexity-reduction pass.
+- Enabled GitHub's native Dependabot vulnerability alerts for the repository.
+
+### Fixed
+
+- Removed the stale, inaccurate `.env.production` file (unverifiable "0 known
+  CVEs" claim, an obsolete `poetry install` reference, and unused
+  environment variables that nothing in the codebase reads).
+- Removed the stale, tracked `output.txt` pytest-output artifact from version
+  control.
+- Fixed a broken `SECURITY.md` reference to a nonexistent developer-notes
+  file; it now points to the ADR that documents credential handling.
+
+### Removed
+
+- Removed `.env.production` and `output.txt` from version control (see
+  Fixed, above).
+
+## [0.2.0] - 2026-08-27
+
+
+### Added
+
+- Added explicit `roadmap migrate` preflight, dry-run, confirmed execution,
+  structured output, recovery, and idempotent rerun for supported 0.1.1
+  workspaces.
+- Added versioned workspace/document schemas, stable entity IDs, scoped
+  configuration, deterministic JSON/CSV output, read-only health diagnosis,
+  previewable repair, and explicit local Git status/branch/reference commands.
+- Added architecture, test-quality, package-installation, compatibility,
+  failure-injection, concurrency, corruption, migration, offline, and measured
+  performance gates.
+
+### Changed
+
+- Canonical Markdown/YAML documents are now the sole data authority. SQLite is
+  a disposable query projection refreshed or rebuilt only from those files.
+- Projects, milestones, and issues use flat stable-ID paths. Lifecycle state is
+  metadata rather than a physical archive-directory contract.
+- New IDs use complete UUID4 values; migration preserves existing IDs and
+  user-authored content.
+- The package now has one Domain/Application/Adapters/Bootstrap architecture,
+  one configuration path, one persistence path, and one implementation for
+  each retained CLI journey.
+- Supported runtimes now include Python 3.12 through 3.14 on macOS and Linux;
+  CI verifies the full Python range and installed artifacts on Ubuntu x64 and
+  macOS ARM64.
+- Machine-readable stdout is isolated from diagnostics and confirmations on
+  stderr.
+
+### Removed
+
+- Removed provider-backed synchronization, GitHub entity replication,
+  Roadmap-owned credentials, connectivity/setup handlers, provider baselines,
+  reconciliation databases, and sync metrics. Ordinary Git transport remains
+  outside Roadmap and local file-to-SQLite projection maintenance remains.
+- Removed the legacy `core`, `common`, `infrastructure`, `presentation`, and
+  superseded adapter ownership zones, along with duplicate configuration,
+  health, export, persistence, and compatibility implementations.
+- Removed claimed features that did not belong to the retained product,
+  including hosted dashboards, predictive analytics, OAuth, and generated API
+  documentation stacks.
+
+### Migration
+
+- Existing 0.1.1 workspaces must run `roadmap migrate --dry-run` and review the
+  report before `roadmap migrate --yes`.
+- Migration rewrites canonical entities to stable paths, externalizes user
+  preferences, removes legacy credential fields, and rebuilds SQLite without
+  treating it as authority. See `docs/user_guide/MIGRATING_TO_0_2.md`.
+
+## [0.1.1] - 2026-08-09
+
+### Fixed
+
+- Removed the unrelated `roadmap` PyPI distribution from runtime dependencies;
+  it shadowed this project's package and broke the console command.
+- Moved development and documentation tooling out of runtime dependencies.
+- Read the installed version from distribution metadata and added clean wheel
+  and source-distribution smoke tests.
+- Corrected supported Python/platform declarations, repository URLs, and
+  installation guidance.
+
+## [0.1.0] - 2026-05-18
+
+### Changed
+
+- Reset the public version from premature 1.x tags to 0.1.0 so package versions
+  accurately communicate pre-1.0 compatibility and maturity.
+
+## Pre-reset 1.x tags
+
+Tags numbered 1.0.0 through 1.0.2 predated the maturity reset. Their release
+notes contained aspirational and unverified feature, compatibility, coverage,
+security, and performance claims, so they are not a description of the current
+product contract. Git history remains available for provenance; supported
+behavior begins with the honest 0.1.x line above.

{roadmap_cli-0.2.0 → roadmap_cli-0.3.1}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.5
 Name: roadmap-cli
-Version: 0.2.0
+Version: 0.3.1
 Summary: Git-native command line tool for local project roadmap management
 Project-URL: Homepage, https://github.com/shanewilkins/roadmap
 Project-URL: Repository, https://github.com/shanewilkins/roadmap
 Project-URL: Issues, https://github.com/shanewilkins/roadmap/issues
-Project-URL: Documentation, https://github.com/shanewilkins/roadmap/tree/main/docs
+Project-URL: Documentation, https://github.com/shanewilkins/roadmap/tree/master/docs
 Author: Shane Wilkins
 License: MIT
 License-File: LICENSE.md
@@ -33,17 +33,16 @@ Requires-Dist: pyyaml<7.0.0,>=6.0.3
 Requires-Dist: rich<16.0.0,>=15.0.0
 Provides-Extra: dev
 Requires-Dist: bandit[toml]>=1.9.4; extra == 'dev'
+Requires-Dist: import-linter<3,>=2.11; extra == 'dev'
+Requires-Dist: markdown-it-py<5,>=4.2; extra == 'dev'
 Requires-Dist: pre-commit>=4.6.0; extra == 'dev'
-Requires-Dist: pyright>=1.1.411; extra == 'dev'
-Requires-Dist: pytest-aiohttp>=1.1.0; extra == 'dev'
-Requires-Dist: pytest-asyncio>=1.3.0; extra == 'dev'
-Requires-Dist: pytest-benchmark>=5.2.3; extra == 'dev'
 Requires-Dist: pytest-cov>=7.1.0; extra == 'dev'
-Requires-Dist: pytest-mock>=3.15.1; extra == 'dev'
 Requires-Dist: pytest-xdist>=3.8.0; extra == 'dev'
 Requires-Dist: pytest>=9.0.3; extra == 'dev'
 Requires-Dist: radon<7.0.0,>=6.0.1; extra == 'dev'
-Requires-Dist: ruff==0.16.4; extra == 'dev'
+Requires-Dist: ruff>=0.16.10; extra == 'dev'
+Requires-Dist: ty>=0.0.84; extra == 'dev'
+Requires-Dist: vulture<3,>=2.14; extra == 'dev'
 Requires-Dist: xenon<1.0.0,>=0.9.3; extra == 'dev'
 Description-Content-Type: text/markdown
 
@@ -54,9 +53,17 @@ their planning data in reviewable Markdown and YAML files rather than a hosted
 service. It supports issues, dependencies, comments, projects, milestones,
 daily views, health checks, and machine-readable exports.
 
-The current release is 0.2.0. Its deliberately contracted behavior is defined
+Version **0.3.1** adds CLI workflow improvements and reliability fixes. Use the
+[versioned documentation](https://github.com/shanewilkins/roadmap/tree/v0.3.1/docs)
+and [0.3.1 changelog](CHANGELOG.md#031---2026-10-08) for this version.
+Source checkouts can precede package publication; check
+[PyPI](https://pypi.org/project/roadmap-cli/) for available package versions.
+
+The retained CLI and data behavior is defined
 by an explicit
 [public compatibility contract](docs/architecture/public-contract-0.2.md).
+0.3 is an internal quality-hardening release; the 0.2 CLI and data contract is
+unchanged.
 
 ## What it does
 
@@ -139,7 +146,7 @@ Organize delivery:
 
 ```bash
 roadmap project create --title "Web application"
-roadmap milestone create --title "0.2" --due-date 2026-09-30
+roadmap milestone create --title "0.2" --due-date 2026-09-30 --project "Web application"
 roadmap milestone assign <issue-id> "0.2"
 roadmap milestone view "0.2"
 ```
@@ -211,6 +218,7 @@ migration. Do not treat the internal SQLite schema as a public API.
 - [Workflows](docs/user_guide/WORKFLOWS.md)
 - [FAQ](docs/user_guide/FAQ.md)
 - [0.2 migration guide](docs/user_guide/MIGRATING_TO_0_2.md)
+- [Recovery guide](docs/user_guide/RECOVERY.md)
 - [Architecture decisions](docs/architecture/README.md)
 - [Refactor case study](docs/architecture/portfolio-case-study.md)
 - [0.2 release checklist](docs/releases/0.2.0-checklist.md)
@@ -225,7 +233,9 @@ product direction.
 
 ## Project status
 
-Roadmap 0.2.0 is the result of thirteen independently verified refactor phases.
+This checkout targets 0.3.1; the workflow shortcuts below describe that version. See the [next-release checklist](docs/releases/NEXT_RELEASE.md)
+for the remaining publication checks. The architecture was established through
+thirteen independently verified refactor phases for 0.2.0.
 See the
 [execution plan](docs/architecture/refactor-execution-plan.md) and published
 [checkpoint reports](docs/architecture/README.md#execution-checkpoints).
@@ -233,3 +243,27 @@ See the
 ## License
 
 [MIT](LICENSE.md)
+
+
+### Small workflow shortcuts
+
+- Ambiguous issue, project, and milestone lookups list matching IDs and labels.
+- Plain health output offers repair-preview commands; previews never apply repairs.
+- `roadmap config explain output.format` shows the effective value and its source;
+  add `--format json` for structured output.
+- Capture a created issue ID without parsing prose:
+
+```sh
+issue_id=$(roadmap issue create --title "Improve recovery guidance" --print-id)
+roadmap issue view "$issue_id"
+```
+
+`--print-id` keeps warnings and branch notifications on stderr. A subsequent
+Git-branch failure still returns nonzero; the printed ID identifies the already
+created issue, so inspect it before retrying creation.
+
+Enable [shell completion](docs/user_guide/SHELL_COMPLETION.md) for commands,
+options, and choice values.
+
+The reviewed command and option contracts, compatibility guidance, and examples
+are in the [CLI correctness guide](docs/architecture/cli-correctness-closeout.md).

{roadmap_cli-0.2.0 → roadmap_cli-0.3.1}/README.md

@@ -5,9 +5,17 @@ their planning data in reviewable Markdown and YAML files rather than a hosted
 service. It supports issues, dependencies, comments, projects, milestones,
 daily views, health checks, and machine-readable exports.
 
-The current release is 0.2.0. Its deliberately contracted behavior is defined
+Version **0.3.1** adds CLI workflow improvements and reliability fixes. Use the
+[versioned documentation](https://github.com/shanewilkins/roadmap/tree/v0.3.1/docs)
+and [0.3.1 changelog](CHANGELOG.md#031---2026-10-08) for this version.
+Source checkouts can precede package publication; check
+[PyPI](https://pypi.org/project/roadmap-cli/) for available package versions.
+
+The retained CLI and data behavior is defined
 by an explicit
 [public compatibility contract](docs/architecture/public-contract-0.2.md).
+0.3 is an internal quality-hardening release; the 0.2 CLI and data contract is
+unchanged.
 
 ## What it does
 
@@ -90,7 +98,7 @@ Organize delivery:
 
 ```bash
 roadmap project create --title "Web application"
-roadmap milestone create --title "0.2" --due-date 2026-09-30
+roadmap milestone create --title "0.2" --due-date 2026-09-30 --project "Web application"
 roadmap milestone assign <issue-id> "0.2"
 roadmap milestone view "0.2"
 ```
@@ -162,6 +170,7 @@ migration. Do not treat the internal SQLite schema as a public API.
 - [Workflows](docs/user_guide/WORKFLOWS.md)
 - [FAQ](docs/user_guide/FAQ.md)
 - [0.2 migration guide](docs/user_guide/MIGRATING_TO_0_2.md)
+- [Recovery guide](docs/user_guide/RECOVERY.md)
 - [Architecture decisions](docs/architecture/README.md)
 - [Refactor case study](docs/architecture/portfolio-case-study.md)
 - [0.2 release checklist](docs/releases/0.2.0-checklist.md)
@@ -176,7 +185,9 @@ product direction.
 
 ## Project status
 
-Roadmap 0.2.0 is the result of thirteen independently verified refactor phases.
+This checkout targets 0.3.1; the workflow shortcuts below describe that version. See the [next-release checklist](docs/releases/NEXT_RELEASE.md)
+for the remaining publication checks. The architecture was established through
+thirteen independently verified refactor phases for 0.2.0.
 See the
 [execution plan](docs/architecture/refactor-execution-plan.md) and published
 [checkpoint reports](docs/architecture/README.md#execution-checkpoints).
@@ -184,3 +195,27 @@ See the
 ## License
 
 [MIT](LICENSE.md)
+
+
+### Small workflow shortcuts
+
+- Ambiguous issue, project, and milestone lookups list matching IDs and labels.
+- Plain health output offers repair-preview commands; previews never apply repairs.
+- `roadmap config explain output.format` shows the effective value and its source;
+  add `--format json` for structured output.
+- Capture a created issue ID without parsing prose:
+
+```sh
+issue_id=$(roadmap issue create --title "Improve recovery guidance" --print-id)
+roadmap issue view "$issue_id"
+```
+
+`--print-id` keeps warnings and branch notifications on stderr. A subsequent
+Git-branch failure still returns nonzero; the printed ID identifies the already
+created issue, so inspect it before retrying creation.
+
+Enable [shell completion](docs/user_guide/SHELL_COMPLETION.md) for commands,
+options, and choice values.
+
+The reviewed command and option contracts, compatibility guidance, and examples
+are in the [CLI correctness guide](docs/architecture/cli-correctness-closeout.md).

{roadmap_cli-0.2.0 → roadmap_cli-0.3.1}/pyproject.toml

@@ -13,7 +13,7 @@ build-backend = "hatchling.build"
 #   Installs the locked runtime and development dependency sets.
 # ============================================================================
 name = "roadmap-cli"
-version = "0.2.0"
+version = "0.3.1"
 description = "Git-native command line tool for local project roadmap management"
 readme = "README.md"
 requires-python = ">=3.12,<4.0"
@@ -59,24 +59,23 @@ dependencies = [
 dev = [
     "pytest>=9.0.3",
     "pytest-cov>=7.1.0",
-    "pytest-asyncio>=1.3.0",
-    "pytest-aiohttp>=1.1.0",
-    "ruff==0.16.4",
+    "ruff>=0.16.10",
     "pre-commit>=4.6.0",
     "bandit[toml]>=1.9.4",
     "radon>=6.0.1,<7.0.0",
     "xenon>=0.9.3,<1.0.0",
     "pytest-xdist>=3.8.0",
-    "pytest-benchmark>=5.2.3",
-    "pyright>=1.1.411",
-    "pytest-mock>=3.15.1",
+    "ty>=0.0.84",
+    "import-linter>=2.11,<3",
+    "markdown-it-py>=4.2,<5",
+    "vulture>=2.14,<3",
 ]
 
 [project.urls]
 Homepage = "https://github.com/shanewilkins/roadmap"
 Repository = "https://github.com/shanewilkins/roadmap"
 Issues = "https://github.com/shanewilkins/roadmap/issues"
-Documentation = "https://github.com/shanewilkins/roadmap/tree/main/docs"
+Documentation = "https://github.com/shanewilkins/roadmap/tree/master/docs"
 
 [project.scripts]
 roadmap = "roadmap.bootstrap:main"
@@ -112,10 +111,27 @@ include = [
 # - ruff.toml: Linting and formatting rules
 # - bandit.toml: Security scanning configuration
 # - .coveragerc: Test coverage thresholds and exclusions
-# - pyrightconfig.json: Type checking configuration
+# - tool.ty below: Type checking configuration
 
-# Type checking is now handled by Pyright
-# Configuration is in pyrightconfig.json
+# ty is the sole type checker, enforced in CI and pre-commit.
+[tool.ty.src]
+include = ["roadmap", "tests"]
+# These fixture trees are synthetic "roadmap" packages used only for the
+# architecture checker's AST scan; they are never actually imported, so
+# ty's import resolution has nothing real to check them against.
+exclude = ["tests/policy/fixtures/architecture"]
+
+[tool.ty.environment]
+python-version = "3.12"
+
+[tool.ty.rules]
+unresolved-import = "error"
+unresolved-reference = "error"
+invalid-argument-type = "error"
+invalid-assignment = "error"
+invalid-return-type = "error"
+possibly-missing-attribute = "error"
+unresolved-attribute = "error"
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
@@ -131,17 +147,5 @@ markers = [
     "mock_scanning: Tests with mocked repository scanning operations",
     "no_xdist: Tests that should not run in parallel (disables xdist parallelization)"
 ]
-filterwarnings = [
-    "ignore::pytest_benchmark.logger.PytestBenchmarkWarning"
-]
-
-[dependency-groups]
-dev = [
-    "pytest-asyncio>=1.4.0",
-    "pytest-benchmark>=5.2.3",
-    "pytest-cov>=7.1.0",
-    "pytest-mock>=3.15.1",
-    "pytest-xdist>=3.8.0",
-]
 
 # Coverage configuration moved to config/.coveragerc

{roadmap_cli-0.2.0 → roadmap_cli-0.3.1}/roadmap/__init__.py

@@ -4,10 +4,10 @@ from importlib.metadata import PackageNotFoundError, version
 
 # Installed artifacts read their distribution metadata; source checkouts use the
 # matching fallback without importing the executable adapter as a side effect.
-__version__ = "0.2.0"
+__version__ = "0.3.1"
 try:
     __version__ = version("roadmap-cli")
 except PackageNotFoundError:
-    __version__ = "0.2.0"
+    __version__ = "0.3.1"
 
 __all__ = ["__version__"]

{roadmap_cli-0.2.0 → roadmap_cli-0.3.1}/roadmap/adapters/inbound/cli/__init__.py

@@ -1,6 +1,7 @@
 """Lazy Click adapter assembled by :mod:`roadmap.bootstrap`."""
 
 import importlib
+import stat
 from collections.abc import Callable, Mapping
 from dataclasses import dataclass
 from pathlib import Path
@@ -12,7 +13,9 @@ import click
 def _handle_cli_exception(ctx: click.Context, error: Exception) -> Any:
     from roadmap.adapters.inbound.cli.exception_handler import handle_cli_exception
 
-    return handle_cli_exception(ctx, error, show_traceback=False)
+    return handle_cli_exception(
+        ctx, error, show_traceback=bool(ctx.find_root().params.get("debug", False))
+    )
 
 
 CommandLocation = tuple[str, str, str]
@@ -67,6 +70,7 @@ class CliRuntime:
     migration_factory: Callable[[], Any]
     initialization_factory: Callable[[str], Any]
     version: str
+    workspace_factories: Callable[[Path], dict[str, Any]] | None = None
 
 
 class RoadmapClickGroup(click.Group):
@@ -92,27 +96,21 @@ class RoadmapClickGroup(click.Group):
         """Render root help from static metadata without importing features."""
         names = sorted(self._command_registry)
         limit = formatter.width - 6 - max(map(len, names), default=0)
-        rows = [(name, click.utils.make_default_short_help(self._command_registry[name][2], limit)) for name in names]  # fmt: skip
+        rows = [(name, click.Command(name, help=self._command_registry[name][2]).get_short_help_str(limit)) for name in names]  # fmt: skip
         with formatter.section("Commands"):
             formatter.write_dl(rows)
 
-    def get_command(self, ctx: click.Context, name: str) -> click.Command | None:
+    def get_command(self, ctx: click.Context, cmd_name: str) -> click.Command | None:
         """Load one registered command only when Click requests it."""
-        if (attached := super().get_command(ctx, name)) is not None:
+        if (attached := super().get_command(ctx, cmd_name)) is not None:
             return attached
-        if name in self._command_cache:
-            return self._command_cache[name]
-        location = self._command_registry.get(name)
+        if cmd_name in self._command_cache:
+            return self._command_cache[cmd_name]
+        location = self._command_registry.get(cmd_name)
         if location is None:
             return None
         module_path, attribute, _help = location
-        try:
-            self._command_cache[name] = command = getattr(importlib.import_module(module_path), attribute)  # fmt: skip
-        except Exception as error:
-            self._console_factory().print(
-                f"⚠️  Failed to load command '{name}': {error}", style="yellow"
-            )
-            return None
+        self._command_cache[cmd_name] = command = getattr(importlib.import_module(module_path), attribute)  # fmt: skip
         return command
 
     def invoke(self, ctx: click.Context) -> Any:
@@ -138,8 +136,16 @@ def create_cli(
         console_factory=runtime.console_factory,
     )
     @click.version_option(version=runtime.version)
+    @click.option(
+        "--debug", is_flag=True, help="Show tracebacks for unexpected errors."
+    )
+    @click.option(
+        "--workspace",
+        type=click.Path(path_type=Path),
+        help="Canonical workspace directory; overrides the current-directory default.",
+    )
     @click.pass_context
-    def cli(ctx: click.Context) -> None:
+    def cli(ctx: click.Context, debug: bool, workspace: Path | None) -> None:  # noqa: ARG001
         """Roadmap CLI - A command line tool for creating and managing roadmaps."""
         ctx.ensure_object(dict)
         ctx.obj.setdefault("core_factory", runtime.core_factory)
@@ -147,12 +153,34 @@ def create_cli(
         ctx.obj.setdefault("console_factory", runtime.console_factory)
         ctx.obj.setdefault("migration_factory", runtime.migration_factory)
         ctx.obj.setdefault("initialization_factory", runtime.initialization_factory)
+        if workspace is not None:
+            if runtime.workspace_factories is None:
+                raise click.ClickException(
+                    "Explicit workspace selection requires Bootstrap"
+                )
+            selected = workspace.expanduser().absolute()
+            ctx.obj.update(runtime.workspace_factories(selected))
+            ctx.obj["workspace"] = selected
+            ctx.obj.pop("core", None)
+            if ctx.invoked_subcommand not in {None, "init", "migrate"}:
+                try:
+                    valid = stat.S_ISDIR(selected.stat().st_mode) and stat.S_ISREG(
+                        (selected / "config.yaml").stat().st_mode
+                    )
+                except OSError as error:
+                    raise click.ClickException(
+                        f"Cannot open explicit workspace {selected}: {error}"
+                    ) from error
+                if not valid:
+                    raise click.ClickException(
+                        f"Explicit workspace is not initialized: {selected}"
+                    )
         if (
             ctx.invoked_subcommand not in {None, "init", "migrate"}
             and "core" not in ctx.obj
         ):
             try:
-                ctx.obj["core"] = runtime.core_factory(".roadmap")
+                ctx.obj["core"] = ctx.obj["core_factory"](".roadmap")
             except Exception as error:
                 _handle_cli_exception(ctx, error)