specfact-cli 0.35.0__tar.gz → 0.36.0__tar.gz

{specfact_cli-0.35.0 → specfact_cli-0.36.0}/.gitignore

@@ -111,6 +111,12 @@ docs/internal/
 .claude/skills/openspec-*/
 !.claude/skills/openspec-workflows/
 
+.codex/skills/openspec-*/
+!.codex/skills/openspec-workflows/
+
+.vibe/skills/openspec-*/
+!.vibe/skills/openspec-workflows/
+
 # Semgrep rules (generated from tools/semgrep/ - source rules are versioned)
 .semgrep/
 

{specfact_cli-0.35.0 → specfact_cli-0.36.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specfact-cli
-Version: 0.35.0
+Version: 0.36.0
 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
@@ -431,51 +431,11 @@ Start with:
 - **Backlogs**: GitHub Issues, Azure DevOps, Jira, Linear
 - **Contracts**: Specmatic, OpenAPI
 
-### Module Lifecycle Baseline
+For technical architecture details (module lifecycle, registry internals, adapters, and implementation status), use:
 
-SpecFact now has a lifecycle-managed module system:
-
-- `specfact init` is bootstrap-first: initializes local CLI state and reports prompt status.
-- `specfact init ide` handles IDE prompt/template sync and IDE settings updates.
-- `specfact module` is the canonical lifecycle surface:
-  - `specfact module install <namespace/name>` installs marketplace modules into `~/.specfact/marketplace-modules/`.
-  - `specfact module list [--source builtin|marketplace|custom]` shows multi-source discovery state.
-  - `specfact module enable <id>` / `specfact module disable <id> [--force]` manage enabled state.
-  - `specfact module uninstall <name>` and `specfact module upgrade <name>` manage marketplace lifecycle.
-- `specfact init --list-modules`, `--enable-module`, and `--disable-module` remain supported as compatibility aliases during migration.
-- Module lifecycle operations keep dependency-aware safety checks with `--force` cascading behavior.
-- Module manifests support dependency and core-version compatibility enforcement at registration time.
-
-This lifecycle model is the baseline for future granular module updates and enhancements. Module installation from third-party or open-source community providers is planned, but not implemented yet.
-
-Contract-first module architecture highlights:
-
-- `ModuleIOContract` formalizes module IO operations (`import`, `export`, `sync`, `validate`) on `ProjectBundle`.
-- Core-module isolation is enforced by static analysis (`core` never imports `specfact_cli.modules.*` directly).
-- Registration tracks protocol operation coverage and schema compatibility metadata.
-- Bridge registry support allows module manifests to declare `service_bridges` converters (for example ADO/Jira/Linear/GitHub) loaded at lifecycle startup without direct core-to-module imports.
-- Protocol reporting classifies modules from effective runtime interfaces with a single aggregate summary (`Full/Partial/Legacy`).
-- Module manifests support publisher and integrity metadata (arch-06) with optional checksum and signature verification at registration time.
-
-Why this matters:
-
-- Feature areas can evolve independently without repeatedly modifying core CLI wiring.
-- Module teams can ship at different speeds while preserving stable core behavior.
-- Clear IO contracts reduce coupling and make future migrations (e.g., new adapters/modules) lower risk.
-- Core remains focused on lifecycle, registry, and validation orchestration rather than tool-specific command logic.
-
----
-
-## Developer Note: Command Layout
-
-- Primary command implementations live in `src/specfact_cli/modules/<module>/src/commands.py`.
-- Legacy imports from `src/specfact_cli/commands/*.py` are compatibility shims and only guarantee `app` re-exports.
-- Preferred imports for module code:
-  - `from specfact_cli.modules.<module>.src.commands import app`
-  - `from specfact_cli.modules.<module>.src.commands import <symbol>`
-- Shim deprecation timeline:
-  - Legacy shim usage is deprecated for non-`app` symbols now.
-  - Shim removal is planned no earlier than `v0.30` (or the next major migration window).
+- [Architecture Reference](docs/reference/architecture.md)
+- [Architecture Docs Index](docs/architecture/README.md)
+- [Architecture Implementation Status](docs/architecture/implementation-status.md)
 
 ---
 

{specfact_cli-0.35.0 → specfact_cli-0.36.0}/README.md

@@ -154,51 +154,11 @@ Start with:
 - **Backlogs**: GitHub Issues, Azure DevOps, Jira, Linear
 - **Contracts**: Specmatic, OpenAPI
 
-### Module Lifecycle Baseline
+For technical architecture details (module lifecycle, registry internals, adapters, and implementation status), use:
 
-SpecFact now has a lifecycle-managed module system:
-
-- `specfact init` is bootstrap-first: initializes local CLI state and reports prompt status.
-- `specfact init ide` handles IDE prompt/template sync and IDE settings updates.
-- `specfact module` is the canonical lifecycle surface:
-  - `specfact module install <namespace/name>` installs marketplace modules into `~/.specfact/marketplace-modules/`.
-  - `specfact module list [--source builtin|marketplace|custom]` shows multi-source discovery state.
-  - `specfact module enable <id>` / `specfact module disable <id> [--force]` manage enabled state.
-  - `specfact module uninstall <name>` and `specfact module upgrade <name>` manage marketplace lifecycle.
-- `specfact init --list-modules`, `--enable-module`, and `--disable-module` remain supported as compatibility aliases during migration.
-- Module lifecycle operations keep dependency-aware safety checks with `--force` cascading behavior.
-- Module manifests support dependency and core-version compatibility enforcement at registration time.
-
-This lifecycle model is the baseline for future granular module updates and enhancements. Module installation from third-party or open-source community providers is planned, but not implemented yet.
-
-Contract-first module architecture highlights:
-
-- `ModuleIOContract` formalizes module IO operations (`import`, `export`, `sync`, `validate`) on `ProjectBundle`.
-- Core-module isolation is enforced by static analysis (`core` never imports `specfact_cli.modules.*` directly).
-- Registration tracks protocol operation coverage and schema compatibility metadata.
-- Bridge registry support allows module manifests to declare `service_bridges` converters (for example ADO/Jira/Linear/GitHub) loaded at lifecycle startup without direct core-to-module imports.
-- Protocol reporting classifies modules from effective runtime interfaces with a single aggregate summary (`Full/Partial/Legacy`).
-- Module manifests support publisher and integrity metadata (arch-06) with optional checksum and signature verification at registration time.
-
-Why this matters:
-
-- Feature areas can evolve independently without repeatedly modifying core CLI wiring.
-- Module teams can ship at different speeds while preserving stable core behavior.
-- Clear IO contracts reduce coupling and make future migrations (e.g., new adapters/modules) lower risk.
-- Core remains focused on lifecycle, registry, and validation orchestration rather than tool-specific command logic.
-
----
-
-## Developer Note: Command Layout
-
-- Primary command implementations live in `src/specfact_cli/modules/<module>/src/commands.py`.
-- Legacy imports from `src/specfact_cli/commands/*.py` are compatibility shims and only guarantee `app` re-exports.
-- Preferred imports for module code:
-  - `from specfact_cli.modules.<module>.src.commands import app`
-  - `from specfact_cli.modules.<module>.src.commands import <symbol>`
-- Shim deprecation timeline:
-  - Legacy shim usage is deprecated for non-`app` symbols now.
-  - Shim removal is planned no earlier than `v0.30` (or the next major migration window).
+- [Architecture Reference](docs/reference/architecture.md)
+- [Architecture Docs Index](docs/architecture/README.md)
+- [Architecture Implementation Status](docs/architecture/implementation-status.md)
 
 ---
 

{specfact_cli-0.35.0 → specfact_cli-0.36.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "specfact-cli"
-version = "0.35.0"
+version = "0.36.0"
 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"

{specfact_cli-0.35.0 → specfact_cli-0.36.0}/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.35.0"
+__version__ = "0.36.0"

{specfact_cli-0.35.0 → specfact_cli-0.36.0}/src/specfact_cli/__init__.py

@@ -8,6 +8,6 @@ This package provides command-line tools for:
 - Supporting agile ceremonies and team workflows
 """
 
-__version__ = "0.35.0"
+__version__ = "0.36.0"
 
 __all__ = ["__version__"]

{specfact_cli-0.35.0 → specfact_cli-0.36.0}/src/specfact_cli/adapters/ado.py

@@ -1657,7 +1657,10 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
         ]
 
         try:
-            response = requests.patch(url, json=patch_document, headers=headers, timeout=30)
+            response = self._request_with_retry(
+                lambda: requests.patch(url, json=patch_document, headers=headers, timeout=30),
+                retry_on_ambiguous_transport=False,
+            )
             if is_debug_mode():
                 debug_log_operation(
                     "ado_patch",
@@ -1800,8 +1803,9 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
         patch_document = [{"op": "replace", "path": "/fields/System.State", "value": ado_state}]
 
         try:
-            response = requests.patch(url, json=patch_document, headers=headers, timeout=30)
-            response.raise_for_status()
+            response = self._request_with_retry(
+                lambda: requests.patch(url, json=patch_document, headers=headers, timeout=30)
+            )
             work_item_data = response.json()
 
             work_item_url = work_item_data.get("_links", {}).get("html", {}).get("href", "")
@@ -1933,8 +1937,9 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
         ]
 
         try:
-            response = requests.patch(url, json=patch_document, headers=headers, timeout=30)
-            response.raise_for_status()
+            response = self._request_with_retry(
+                lambda: requests.patch(url, json=patch_document, headers=headers, timeout=30)
+            )
             work_item_data = response.json()
 
             work_item_url = work_item_data.get("_links", {}).get("html", {}).get("href", "")
@@ -2040,8 +2045,9 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
         patch_document = [{"op": "replace", "path": "/fields/System.State", "value": ado_state}]
 
         try:
-            response = requests.patch(url, json=patch_document, headers=headers, timeout=30)
-            response.raise_for_status()
+            response = self._request_with_retry(
+                lambda: requests.patch(url, json=patch_document, headers=headers, timeout=30)
+            )
             work_item_data = response.json()
 
             work_item_url = work_item_data.get("_links", {}).get("html", {}).get("href", "")
@@ -2442,8 +2448,10 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
         comment_body = {"text": comment_text}
 
         try:
-            response = requests.post(url, json=comment_body, headers=headers, timeout=30)
-            response.raise_for_status()
+            response = self._request_with_retry(
+                lambda: requests.post(url, json=comment_body, headers=headers, timeout=30),
+                retry_on_ambiguous_transport=False,
+            )
             comment_data = response.json()
 
             comment_id = comment_data.get("id")
@@ -2690,6 +2698,7 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
         self,
         sprint_filter: str | None,
         items: list[BacklogItem],
+        apply_current_when_missing: bool = True,
     ) -> tuple[str | None, list[BacklogItem]]:
         """
         Resolve sprint filter with path matching and ambiguity detection.
@@ -2705,6 +2714,8 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
             ValueError: If ambiguous sprint name match is detected
         """
         if not sprint_filter:
+            if not apply_current_when_missing:
+                return None, items
             # No sprint filter - try to get current iteration
             current_iteration = self._get_current_iteration()
             if current_iteration:
@@ -2859,13 +2870,16 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
             # Sprint will be resolved post-fetch to handle ambiguity
             pass
         else:
-            # No sprint/iteration - try current iteration
-            current_iteration = self._get_current_iteration()
-            if current_iteration:
-                resolved_iteration = current_iteration
-                conditions.append(f"[System.IterationPath] = '{resolved_iteration}'")
-            else:
-                console.print("[yellow]⚠ No current iteration found and no sprint/iteration filter provided[/yellow]")
+            # No sprint/iteration - optionally use current iteration default
+            if getattr(filters, "use_current_iteration_default", True):
+                current_iteration = self._get_current_iteration()
+                if current_iteration:
+                    resolved_iteration = current_iteration
+                    conditions.append(f"[System.IterationPath] = '{resolved_iteration}'")
+                else:
+                    console.print(
+                        "[yellow]⚠ No current iteration found and no sprint/iteration filter provided[/yellow]"
+                    )
 
         if conditions:
             wiql_parts.append("AND " + " AND ".join(conditions))
@@ -3113,7 +3127,11 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
         # Sprint filtering with path matching and ambiguity detection
         if filters.sprint:
             try:
-                _, filtered_items = self._resolve_sprint_filter(filters.sprint, filtered_items)
+                _, filtered_items = self._resolve_sprint_filter(
+                    filters.sprint,
+                    filtered_items,
+                    apply_current_when_missing=getattr(filters, "use_current_iteration_default", True),
+                )
             except ValueError as e:
                 # Ambiguous sprint match - raise with clear error message
                 console.print(f"[red]Error:[/red] {e}")
@@ -3137,6 +3155,115 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
 
         return filtered_items
 
+    @beartype
+    @require(
+        lambda project_id: isinstance(project_id, str) and len(project_id.strip()) > 0, "project_id must be non-empty"
+    )
+    @require(lambda payload: isinstance(payload, dict), "payload must be dict")
+    @ensure(lambda result: isinstance(result, dict), "Must return dict")
+    def create_issue(self, project_id: str, payload: dict[str, Any]) -> dict[str, Any]:
+        """Create an Azure DevOps work item from provider-agnostic backlog payload."""
+        org, project = self._resolve_graph_project_context(project_id)
+        if not self.api_token:
+            raise ValueError("Azure DevOps API token is required")
+
+        title = str(payload.get("title") or "").strip()
+        if not title:
+            raise ValueError("payload.title is required")
+
+        raw_type = str(payload.get("type") or "task").strip().lower()
+        type_mapping = {
+            "epic": "Epic",
+            "feature": "Feature",
+            "story": "User Story",
+            "user story": "User Story",
+            "task": "Task",
+            "bug": "Bug",
+            "spike": "Task",
+        }
+        work_item_type = type_mapping.get(raw_type, "Task")
+
+        description = str(payload.get("description") or payload.get("body") or "").strip()
+        description_format = str(payload.get("description_format") or "markdown").strip().lower()
+        field_rendering_format = "Markdown" if description_format != "classic" else "Html"
+        patch_document: list[dict[str, Any]] = [
+            {"op": "add", "path": "/fields/System.Title", "value": title},
+            {"op": "add", "path": "/fields/System.Description", "value": description},
+            {"op": "add", "path": "/multilineFieldsFormat/System.Description", "value": field_rendering_format},
+        ]
+
+        acceptance_criteria = str(payload.get("acceptance_criteria") or "").strip()
+        if acceptance_criteria:
+            patch_document.append(
+                {
+                    "op": "add",
+                    "path": "/fields/Microsoft.VSTS.Common.AcceptanceCriteria",
+                    "value": acceptance_criteria,
+                }
+            )
+
+        priority = payload.get("priority")
+        if priority not in (None, ""):
+            patch_document.append(
+                {
+                    "op": "add",
+                    "path": "/fields/Microsoft.VSTS.Common.Priority",
+                    "value": priority,
+                }
+            )
+
+        story_points = payload.get("story_points")
+        if story_points is not None:
+            patch_document.append(
+                {
+                    "op": "add",
+                    "path": "/fields/Microsoft.VSTS.Scheduling.StoryPoints",
+                    "value": story_points,
+                }
+            )
+
+        sprint = str(payload.get("sprint") or "").strip()
+        if sprint:
+            patch_document.append(
+                {
+                    "op": "add",
+                    "path": "/fields/System.IterationPath",
+                    "value": sprint,
+                }
+            )
+
+        parent_id = str(payload.get("parent_id") or "").strip()
+        if parent_id:
+            parent_url = f"{self.base_url}/{org}/{project}/_apis/wit/workItems/{parent_id}"
+            patch_document.append(
+                {
+                    "op": "add",
+                    "path": "/relations/-",
+                    "value": {"rel": "System.LinkTypes.Hierarchy-Reverse", "url": parent_url},
+                }
+            )
+
+        url = f"{self.base_url}/{org}/{project}/_apis/wit/workitems/${work_item_type}?api-version=7.1"
+        headers = {
+            "Content-Type": "application/json-patch+json",
+            **self._auth_headers(),
+        }
+        response = self._request_with_retry(
+            lambda: requests.patch(url, json=patch_document, headers=headers, timeout=30),
+            retry_on_ambiguous_transport=False,
+        )
+        created = response.json()
+
+        created_id = str(created.get("id") or "")
+        html_url = str(created.get("_links", {}).get("html", {}).get("href") or "")
+        fallback_url = str(created.get("url") or "")
+
+        return {
+            "id": created_id,
+            "key": created_id,
+            "url": html_url or fallback_url,
+        }
+
     @beartype
     @require(lambda project_id: isinstance(project_id, str) and len(project_id) > 0, "project_id must be non-empty")
     @ensure(lambda result: isinstance(result, list), "Must return list")
@@ -3429,8 +3556,9 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
 
         # Update work item
         try:
-            response = requests.patch(url, headers=headers, json=operations, timeout=30)
-            response.raise_for_status()
+            response = self._request_with_retry(
+                lambda: requests.patch(url, headers=headers, json=operations, timeout=30)
+            )
         except requests.HTTPError as e:
             user_msg = _log_ado_patch_failure(e.response, operations, url)
             e.ado_user_message = user_msg

{specfact_cli-0.35.0 → specfact_cli-0.36.0}/src/specfact_cli/adapters/backlog_base.py

@@ -11,10 +11,12 @@ functionality for status mapping, metadata extraction, and conflict resolution.
 
 from __future__ import annotations
 
+import time
 from abc import ABC, abstractmethod
 from datetime import UTC, datetime
 from typing import Any
 
+import requests
 from beartype import beartype
 from icontract import ensure, require
 
@@ -35,6 +37,10 @@ class BacklogAdapterMixin(ABC):
     and implement the abstract methods to provide tool-specific implementations.
     """
 
+    RETRYABLE_HTTP_STATUSES: tuple[int, ...] = (429, 500, 502, 503, 504)
+    RETRY_DEFAULT_ATTEMPTS: int = 3
+    RETRY_BACKOFF_SECONDS: float = 0.5
+
     @abstractmethod
     @beartype
     @require(lambda status: isinstance(status, str) and len(status) > 0, "Status must be non-empty string")
@@ -140,6 +146,71 @@ class BacklogAdapterMixin(ABC):
 
         return target_state
 
+    @beartype
+    @require(lambda attempts: attempts is None or attempts > 0, "attempts must be > 0 when provided")
+    @require(
+        lambda backoff_seconds: backoff_seconds is None or backoff_seconds >= 0,
+        "backoff_seconds must be >= 0 when provided",
+    )
+    @require(
+        lambda retry_on_ambiguous_transport: isinstance(retry_on_ambiguous_transport, bool), "retry flag must be bool"
+    )
+    @ensure(lambda result: hasattr(result, "raise_for_status"), "Result must support raise_for_status")
+    def _request_with_retry(
+        self,
+        request_callable: Any,
+        *,
+        attempts: int | None = None,
+        backoff_seconds: float | None = None,
+        retry_on_ambiguous_transport: bool = True,
+    ) -> Any:
+        """Execute HTTP request with central retry policy for transient failures.
+
+        For non-idempotent writes, callers can disable transport-error replay by passing
+        retry_on_ambiguous_transport=False to avoid accidental duplicate side effects.
+        """
+        max_attempts = attempts or self.RETRY_DEFAULT_ATTEMPTS
+        delay = backoff_seconds if backoff_seconds is not None else self.RETRY_BACKOFF_SECONDS
+
+        last_error: Exception | None = None
+        for attempt in range(1, max_attempts + 1):
+            try:
+                response = request_callable()
+                status_code = int(getattr(response, "status_code", 0) or 0)
+                if status_code in self.RETRYABLE_HTTP_STATUSES and attempt < max_attempts:
+                    time.sleep(delay * (2 ** (attempt - 1)))
+                    continue
+                response.raise_for_status()
+                return response
+            except requests.HTTPError as error:
+                status_code = int(getattr(error.response, "status_code", 0) or 0)
+                is_transient = status_code in self.RETRYABLE_HTTP_STATUSES
+                last_error = error
+                if is_transient and attempt < max_attempts:
+                    time.sleep(delay * (2 ** (attempt - 1)))
+                    continue
+                raise
+            except (requests.Timeout, requests.ConnectionError) as error:
+                last_error = error
+                if retry_on_ambiguous_transport and attempt < max_attempts:
+                    time.sleep(delay * (2 ** (attempt - 1)))
+                    continue
+                raise
+
+        if last_error is not None:
+            raise last_error
+        raise RuntimeError("Retry logic failed without response or error")
+
+    @abstractmethod
+    @beartype
+    @require(
+        lambda project_id: isinstance(project_id, str) and len(project_id.strip()) > 0, "Project ID must be non-empty"
+    )
+    @require(lambda payload: isinstance(payload, dict), "Payload must be dict")
+    @ensure(lambda result: isinstance(result, dict), "Must return created issue metadata dict")
+    def create_issue(self, project_id: str, payload: dict[str, Any]) -> dict[str, Any]:
+        """Create backlog issue/work item from provider-agnostic payload."""
+
     @abstractmethod
     @beartype
     @require(lambda item_data: isinstance(item_data, dict), "Item data must be dict")