deviatdd 2.5.2__tar.gz → 2.5.3__tar.gz

{deviatdd-2.5.2 → deviatdd-2.5.3}/CHANGELOG.md

@@ -28,6 +28,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   on the process command line — no exposure in `ps aux`,
   `/proc/<pid>/cmdline`, audit logs, or shell history. `uv publish` reads
   `UV_PUBLISH_TOKEN` natively.
+- README: PyPI version badge in the badge row; one-line `deviate --version`
+  verification step in Quickstart (right after `uv tool install deviatdd`);
+  new `## Troubleshooting` section covering the five most common first-run
+  failures (no `uv`, CLI binary confusion, slash commands not appearing,
+  missing PyPI token, missing agent backend), each with a one-paragraph
+  fix and a link back to the canonical docs (`CONTRIBUTING.md`,
+  `specs/constitution.md`).
+
+- README: Quickstart wording updated — "four agent directories" → "all
+  supported agent directories" to track the six backends listed in the
+  install comment.
+
 
 
 - `format_commit_message()` and `_commit_phase()` accept an optional `phase`
@@ -37,6 +49,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   test is visible at a glance; `feat:` commits continue to use ✨
   regardless of phase.
 
+### Fixed
+- `deviate --version` (and any code path importing `deviate.__version__`)
+  raised `importlib.metadata.PackageNotFoundError: No package metadata was
+  found for deviate` at import time. The two call sites in
+  `src/deviate/__init__.py` and `src/deviate/cli/__init__.py` queried
+  metadata for the import name `"deviate"` instead of the distribution
+  name `"deviatdd"` declared in `pyproject.toml`. Both now query
+  `"deviatdd"` and additionally fall back to a `"0.0.0+unknown"` sentinel
+  (so source checkouts without a dist-info still import). The
+  `test_version` test was tautological (asserted against the same broken
+  `version("deviate")` call it was meant to guard); it now asserts
+  `deviate --version` stdout equals the real
+  `importlib.metadata.version("deviatdd")`, and a new
+  `test_module_version_resolves` import-time guard fails loudly if the
+  module-level lookup regresses.
+
 ### Changed
 - **Shard prompts now own all vertical-slicing rules**; the PRD prompt's
   §Issue Sharding Strategy was removed to eliminate drift between the two.

{deviatdd-2.5.2 → deviatdd-2.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deviatdd
-Version: 2.5.2
+Version: 2.5.3
 Summary: DeviaTDD CLI — agent orchestration framework
 Project-URL: Homepage, https://github.com/wernerbisschoff/deviatdd
 Project-URL: Repository, https://github.com/wernerbisschoff/deviatdd
@@ -60,6 +60,7 @@ Description-Content-Type: text/markdown
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
 [![uv](https://img.shields.io/badge/managed%20with-uv-purple.svg)](https://docs.astral.sh/uv/)
+[![PyPI](https://img.shields.io/pypi/v/deviatdd)](https://pypi.org/project/deviatdd/)
 
 # DeviaTDD
 
@@ -87,17 +88,18 @@ Most AI coding agents stop at "write code that passes." DeviaTDD goes further
 ## Quickstart
 
 ```bash
-# Install (requires Python 3.13+ and uv)
+# Install (requires Python 3.13+ and uv).
 # The PyPI package is `deviatdd`; the CLI binary it installs is `deviate`.
 
 uv tool install deviatdd
+deviate --version                # confirm install
 
 # Bootstrap a new project + install slash commands into your agent of
 # choice. Does it all in one shot: scaffolds .deviate/, specs/constitution.md,
 # governance blocks, and installs /deviate-* slash commands for every
 # supported agent. The --agent flag picks the default backend persisted
 # to .deviate/config.toml (slash commands themselves are installed to all
-# four agent directories regardless).
+# supported agent directories regardless).
 deviate setup --agent claude     # or: opencode | pi | droid | factory | omp
 ```
 
@@ -381,6 +383,39 @@ Claims in this README flagged with an italic _design proposal_ note have **no di
 
 ---
 
+## Troubleshooting
+
+**`uv: command not found`** — Install [uv](https://docs.astral.sh/uv/) first
+(it's the project's mandated package manager per
+[`specs/constitution.md`](specs/constitution.md)). macOS / Linux:
+`curl -LsSf https://astral.sh/uv/install.sh | sh`.
+
+**`deviate: command not found` after `uv tool install deviatdd`** — Verify
+the install landed: `uv tool list | grep deviatdd`. Reinstall if missing:
+`uv tool install --reinstall deviatdd`. The PyPI package name and the CLI
+binary name differ — that's intentional (see [Quickstart](#quickstart)).
+
+**`deviate setup` runs but `/deviate-*` commands don't appear in the
+agent** — Slash commands are installed to `<workdir>/.claude/commands/`,
+`.opencode/commands/`, `.omp/commands/`, `.factory/commands/`, and
+`.pi/prompts/`. Verify the directory exists and is readable, then restart
+the agent so it picks up the new commands.
+
+**`mise run publish` fails with `PYPI_API_TOKEN is not set`** — The task
+loads `.env` from the project root. `.env` must contain
+`PYPI_API_TOKEN=pypi-...`. `.env.example` documents the variable name;
+`.env` itself is gitignored.
+
+**Agent backend not installed** — `deviate setup --agent <name>` scaffolds
+the project without the agent present, but invoking `/deviate-*` slash
+commands requires the agent to be installed. Install Claude Code / OpenCode
+/ Pi / Droid / Factory / OMP first per their respective install
+instructions.
+
+For development-setup details, see
+[`CONTRIBUTING.md`](CONTRIBUTING.md#development-setup) and
+[`specs/constitution.md`](specs/constitution.md).
+
 ## License
 
 [MIT](LICENSE) © 2026 Werner Bisschoff

{deviatdd-2.5.2 → deviatdd-2.5.3}/README.md

@@ -6,6 +6,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
 [![uv](https://img.shields.io/badge/managed%20with-uv-purple.svg)](https://docs.astral.sh/uv/)
+[![PyPI](https://img.shields.io/pypi/v/deviatdd)](https://pypi.org/project/deviatdd/)
 
 # DeviaTDD
 
@@ -33,17 +34,18 @@ Most AI coding agents stop at "write code that passes." DeviaTDD goes further
 ## Quickstart
 
 ```bash
-# Install (requires Python 3.13+ and uv)
+# Install (requires Python 3.13+ and uv).
 # The PyPI package is `deviatdd`; the CLI binary it installs is `deviate`.
 
 uv tool install deviatdd
+deviate --version                # confirm install
 
 # Bootstrap a new project + install slash commands into your agent of
 # choice. Does it all in one shot: scaffolds .deviate/, specs/constitution.md,
 # governance blocks, and installs /deviate-* slash commands for every
 # supported agent. The --agent flag picks the default backend persisted
 # to .deviate/config.toml (slash commands themselves are installed to all
-# four agent directories regardless).
+# supported agent directories regardless).
 deviate setup --agent claude     # or: opencode | pi | droid | factory | omp
 ```
 
@@ -327,6 +329,39 @@ Claims in this README flagged with an italic _design proposal_ note have **no di
 
 ---
 
+## Troubleshooting
+
+**`uv: command not found`** — Install [uv](https://docs.astral.sh/uv/) first
+(it's the project's mandated package manager per
+[`specs/constitution.md`](specs/constitution.md)). macOS / Linux:
+`curl -LsSf https://astral.sh/uv/install.sh | sh`.
+
+**`deviate: command not found` after `uv tool install deviatdd`** — Verify
+the install landed: `uv tool list | grep deviatdd`. Reinstall if missing:
+`uv tool install --reinstall deviatdd`. The PyPI package name and the CLI
+binary name differ — that's intentional (see [Quickstart](#quickstart)).
+
+**`deviate setup` runs but `/deviate-*` commands don't appear in the
+agent** — Slash commands are installed to `<workdir>/.claude/commands/`,
+`.opencode/commands/`, `.omp/commands/`, `.factory/commands/`, and
+`.pi/prompts/`. Verify the directory exists and is readable, then restart
+the agent so it picks up the new commands.
+
+**`mise run publish` fails with `PYPI_API_TOKEN is not set`** — The task
+loads `.env` from the project root. `.env` must contain
+`PYPI_API_TOKEN=pypi-...`. `.env.example` documents the variable name;
+`.env` itself is gitignored.
+
+**Agent backend not installed** — `deviate setup --agent <name>` scaffolds
+the project without the agent present, but invoking `/deviate-*` slash
+commands requires the agent to be installed. Install Claude Code / OpenCode
+/ Pi / Droid / Factory / OMP first per their respective install
+instructions.
+
+For development-setup details, see
+[`CONTRIBUTING.md`](CONTRIBUTING.md#development-setup) and
+[`specs/constitution.md`](specs/constitution.md).
+
 ## License
 
 [MIT](LICENSE) © 2026 Werner Bisschoff

{deviatdd-2.5.2 → deviatdd-2.5.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "deviatdd"
-version = "2.5.2"
+version = "2.5.3"
 description = "DeviaTDD CLI — agent orchestration framework"
 readme = "README.md"
 license = "MIT"

deviatdd-2.5.3/src/deviate/__init__.py

@@ -0,0 +1,10 @@
+from importlib.metadata import PackageNotFoundError, version as _version
+
+try:
+    __version__ = _version("deviatdd")
+except PackageNotFoundError:
+    # Source checkouts without an editable install (e.g. running the module
+    # directly from a git clone) have no dist-info. Fall back to a sentinel
+    # so the CLI still imports; downstream code can detect it via the
+    # "+unknown" suffix.
+    __version__ = "0.0.0+unknown"

{deviatdd-2.5.2 → deviatdd-2.5.3}/src/deviate/cli/__init__.py

@@ -59,9 +59,13 @@ AGENT_CHOICES: tuple[str, ...] = ("factory", "droid", "claude", "opencode", "pi"
 
 def _version_callback(value: bool) -> None:
     if value:
-        from importlib.metadata import version
+        from importlib.metadata import PackageNotFoundError, version
 
-        typer.echo(f"deviate {version('deviate')}")
+        try:
+            ver = version("deviatdd")
+        except PackageNotFoundError:
+            ver = "0.0.0+unknown"
+        typer.echo(f"deviate {ver}")
         raise typer.Exit()
 
 

{deviatdd-2.5.2 → deviatdd-2.5.3}/tests/test_cli/test_init.py

@@ -1217,9 +1217,36 @@ class TestInitPiBackend:
                 )
 
 
+def test_module_version_resolves():
+    """Import-time guard: deviate.__version__ must not raise PackageNotFoundError.
+
+    Regression: src/deviate/__init__.py previously called
+    version("deviate") (the import name) instead of "deviatdd" (the
+    distribution name in pyproject.toml), so importing the package failed
+    with PackageNotFoundError and the entire CLI was unreachable.
+    """
+    import importlib
+
+    import deviate
+
+    importlib.reload(deviate)  # force re-evaluation of the module-level call
+    assert deviate.__version__, "deviate.__version__ must be a non-empty string"
+    assert "+unknown" not in deviate.__version__, (
+        f"deviate.__version__ is the missing-metadata fallback: {deviate.__version__!r}. "
+        "Check that the deviatdd distribution is installed (e.g. "
+        "`uv tool install --force .`)."
+    )
+
+
 def test_version():
+    """`deviate --version` prints the installed distribution version.
+
+    Asserts the CLI output matches `importlib.metadata.version("deviatdd")`
+    directly — re-deriving the expected string via the same broken lookup
+    would let a regression slip through.
+    """
     from importlib.metadata import version
 
     result = runner.invoke(cli, ["--version"])
-    assert result.exit_code == 0
-    assert result.stdout.strip() == f"deviate {version('deviate')}"
+    assert result.exit_code == 0, result.output
+    assert result.stdout.strip() == f"deviate {version('deviatdd')}"

{deviatdd-2.5.2 → deviatdd-2.5.3}/uv.lock

@@ -85,7 +85,7 @@ wheels = [
 
 [[package]]
 name = "deviatdd"
-version = "2.5.2"
+version = "2.5.3"
 source = { editable = "." }
 dependencies = [
     { name = "pydantic" },

deviatdd-2.5.2/src/deviate/__init__.py

@@ -1,3 +0,0 @@
-from importlib.metadata import version as _version
-
-__version__ = _version("deviate")