specfact-cli 0.26.11__tar.gz → 0.26.14__tar.gz

{specfact_cli-0.26.11 → specfact_cli-0.26.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specfact-cli
-Version: 0.26.11
+Version: 0.26.14
 Summary: Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts. Automate legacy code documentation and prevent modernization regressions.
 Project-URL: Homepage, https://github.com/nold-ai/specfact-cli
 Project-URL: Repository, https://github.com/nold-ai/specfact-cli.git
@@ -617,6 +617,7 @@ hatch run contract-test-full
 
 - 💬 **Questions?** [GitHub Discussions](https://github.com/nold-ai/specfact-cli/discussions)
 - 🐛 **Found a bug?** [GitHub Issues](https://github.com/nold-ai/specfact-cli/issues)
+- 🔍 **Debugging I/O or API issues?** Run with `--debug`; logs are written to `~/.specfact/logs/specfact-debug.log`. With `--debug`, ADO API errors include response snippet and patch paths in the log. See [Debug Logging](docs/reference/debug-logging.md).
 - 📧 **Need help?** [hello@noldai.com](mailto:hello@noldai.com)
 - 🌐 **Learn more:** [specfact.com](https://specfact.com) • [specfact.io](https://specfact.io) • [specfact.dev](https://specfact.dev)
 

{specfact_cli-0.26.11 → specfact_cli-0.26.14}/README.md

@@ -339,6 +339,7 @@ hatch run contract-test-full
 
 - 💬 **Questions?** [GitHub Discussions](https://github.com/nold-ai/specfact-cli/discussions)
 - 🐛 **Found a bug?** [GitHub Issues](https://github.com/nold-ai/specfact-cli/issues)
+- 🔍 **Debugging I/O or API issues?** Run with `--debug`; logs are written to `~/.specfact/logs/specfact-debug.log`. With `--debug`, ADO API errors include response snippet and patch paths in the log. See [Debug Logging](docs/reference/debug-logging.md).
 - 📧 **Need help?** [hello@noldai.com](mailto:hello@noldai.com)
 - 🌐 **Learn more:** [specfact.com](https://specfact.com) • [specfact.io](https://specfact.io) • [specfact.dev](https://specfact.dev)
 

{specfact_cli-0.26.11 → specfact_cli-0.26.14}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "specfact-cli"
-version = "0.26.11"
+version = "0.26.14"
 description = "Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts. Automate legacy code documentation and prevent modernization regressions."
 readme = "README.md"
 requires-python = ">=3.11"

{specfact_cli-0.26.11 → specfact_cli-0.26.14}/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.26.11"
+__version__ = "0.26.14"

{specfact_cli-0.26.11 → specfact_cli-0.26.14}/src/specfact_cli/__init__.py

@@ -9,6 +9,6 @@ This package provides command-line tools for:
 - Validating reproducibility
 """
 
-__version__ = "0.26.11"
+__version__ = "0.26.14"
 
 __all__ = ["__version__"]

specfact_cli-0.26.14/src/specfact_cli/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running the CLI as python -m specfact_cli."""
+
+if __name__ == "__main__":
+    from specfact_cli.cli import cli_main
+
+    cli_main()

{specfact_cli-0.26.11 → specfact_cli-0.26.14}/src/specfact_cli/adapters/ado.py

@@ -27,17 +27,77 @@ from specfact_cli.adapters.base import BridgeAdapter
 from specfact_cli.backlog.adapters.base import BacklogAdapter
 from specfact_cli.backlog.filters import BacklogFilters
 from specfact_cli.backlog.mappers.ado_mapper import AdoFieldMapper
+from specfact_cli.common.logger_setup import LoggerSetup
 from specfact_cli.models.backlog_item import BacklogItem
 from specfact_cli.models.bridge import BridgeConfig
 from specfact_cli.models.capabilities import ToolCapabilities
 from specfact_cli.models.change import ChangeProposal, ChangeTracking
-from specfact_cli.runtime import debug_print
+from specfact_cli.runtime import debug_log_operation, debug_print, is_debug_mode
 from specfact_cli.utils.auth_tokens import get_token, set_token
 
 
+_MAX_RESPONSE_BODY_LOG = 2048
+
 console = Console()
 
 
+def _log_ado_patch_failure(
+    response: requests.Response | None,
+    operations: list[dict[str, Any]],
+    url: str,
+    context: str = "",
+) -> str:
+    """
+    Log ADO PATCH failure to debug log (when debug on) and return user-facing message.
+
+    Parses response body (JSON message or truncated text), extracts patch paths,
+    redacts/truncates for debug log, and builds a user message with ADO text and hint.
+    """
+    paths = [op.get("path", "") for op in operations if isinstance(op, dict)]
+    snippet = ""
+    if response is not None:
+        try:
+            body = response.json()
+            snippet = str(body.get("message", response.text[:500]))
+        except Exception:
+            snippet = (response.text or "")[:_MAX_RESPONSE_BODY_LOG]
+        snippet = snippet[:_MAX_RESPONSE_BODY_LOG]
+        snippet = str(LoggerSetup.redact_secrets(snippet))
+
+    if is_debug_mode():
+        debug_log_operation(
+            "ado_patch",
+            url,
+            "failed",
+            error=context or snippet[:500],
+            extra={"response_body": snippet, "patch_paths": paths},
+        )
+
+    return _build_ado_user_message(response)
+
+
+def _build_ado_user_message(response: requests.Response | None) -> str:
+    """Build user-facing error message from ADO response and append mapping hint."""
+    hint = " Check custom field mapping; see ado_custom.yaml or documentation."
+    if response is None:
+        return f"Azure DevOps request failed.{hint}"
+    try:
+        body = response.json()
+        msg = body.get("message", "") or (response.text or "")[:500]
+    except Exception:
+        msg = (response.text or "")[:500]
+    if not msg:
+        return f"Azure DevOps request failed (HTTP {getattr(response, 'status_code', '')}).{hint}"
+
+    m = re.search(r"Cannot find field\s+([^\s]+)", msg, re.IGNORECASE)
+    if m:
+        field = m.group(1).strip().rstrip(".")
+        user_msg = f"Field '{field}' not found.{hint}"
+    else:
+        user_msg = f"{msg}{hint}"
+    return user_msg
+
+
 class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
     """
     Azure DevOps bridge adapter implementing BridgeAdapter interface.
@@ -372,6 +432,8 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
         rationale = ""
         impact = ""
 
+        import re
+
         # Parse markdown sections (Why, What Changes)
         if description_raw:
             # Extract "Why" section (stop at What Changes or OpenSpec footer)
@@ -696,6 +758,8 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
             ValueError: If required configuration is missing
             requests.RequestException: If Azure DevOps API call fails
         """
+        import re as _re
+
         if not self.api_token:
             msg = (
                 "Azure DevOps API token required. Options:\n"
@@ -751,7 +815,7 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
                                 parsed = urlparse(source_url)
                                 if parsed.hostname and parsed.hostname.lower() == "dev.azure.com":
                                     target_org = target_repo.split("/")[0]
-                                    ado_org_match = re.search(r"dev\.azure\.com/([^/]+)/", source_url)
+                                    ado_org_match = _re.search(r"dev\.azure\.com/([^/]+)/", source_url)
                                     if ado_org_match and ado_org_match.group(1) == target_org:
                                         # Org matches - this is likely the same ADO organization
                                         work_item_id = entry.get("source_id")
@@ -773,8 +837,8 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
                         # 3. AND (project is unknown in entry OR project is unknown in target OR both contain GUIDs)
                         # This prevents matching org/project-a with org/project-b when both have known project names
                         source_url = entry.get("source_url", "")
-                        entry_has_guid = source_url and re.search(
-                            r"dev\.azure\.com/[^/]+/[0-9a-f-]{36}", source_url, re.IGNORECASE
+                        entry_has_guid = source_url and _re.search(
+                            r"dev\.azure\.com/[^/]+/[0-9a-f-]{36}", source_url, _re.IGNORECASE
                         )
                         project_unknown = (
                             not entry_project  # Entry has no project part
@@ -967,8 +1031,10 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
         Returns:
             Tuple of (org, project, work_item_id)
         """
+        import re as _re
+
         cleaned = item_ref.strip().lstrip("#")
-        url_match = re.search(r"dev\.azure\.com/([^/]+)/([^/]+)/.*?/(\d+)", cleaned, re.IGNORECASE)
+        url_match = _re.search(r"dev\.azure\.com/([^/]+)/([^/]+)/.*?/(\d+)", cleaned, _re.IGNORECASE)
         if url_match:
             return url_match.group(1), url_match.group(2), int(url_match.group(3))
 
@@ -1439,6 +1505,13 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
 
         try:
             response = requests.post(url, json=wiql, headers=headers, timeout=10)
+            if is_debug_mode():
+                debug_log_operation(
+                    "ado_wiql",
+                    url,
+                    str(response.status_code),
+                    error=None if response.ok else (response.text[:200] if response.text else None),
+                )
             if response.status_code != 200:
                 return None
             work_items = response.json().get("workItems", [])
@@ -1453,7 +1526,9 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
                 "source_type": "ado",
                 "source_repo": f"{org}/{project}",
             }
-        except requests.RequestException:
+        except requests.RequestException as e:
+            if is_debug_mode():
+                debug_log_operation("ado_wiql", url, "error", error=str(e))
             return None
 
     def _create_work_item_from_proposal(
@@ -1473,6 +1548,8 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
         Returns:
             Dict with work item data: {"work_item_id": int, "work_item_url": str, "state": str}
         """
+        import re as _re
+
         title = proposal_data.get("title", "Untitled Change Proposal")
         description = proposal_data.get("description", "")
         rationale = proposal_data.get("rationale", "")
@@ -1489,7 +1566,7 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
         else:
             body_parts = []
 
-            display_title = re.sub(r"^\[change\]\s*", "", title, flags=re.IGNORECASE).strip()
+            display_title = _re.sub(r"^\[change\]\s*", "", title, flags=_re.IGNORECASE).strip()
             if display_title:
                 body_parts.append(f"# {display_title}")
                 body_parts.append("")
@@ -1572,6 +1649,13 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
 
         try:
             response = requests.patch(url, json=patch_document, headers=headers, timeout=30)
+            if is_debug_mode():
+                debug_log_operation(
+                    "ado_patch",
+                    url,
+                    str(response.status_code),
+                    error=None if response.ok else (response.text[:200] if response.text else None),
+                )
             response.raise_for_status()
             work_item_data = response.json()
 
@@ -1617,8 +1701,10 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
                 "state": ado_state,
             }
         except requests.RequestException as e:
-            msg = f"Failed to create Azure DevOps work item: {e}"
-            console.print(f"[bold red]✗[/bold red] {msg}")
+            resp = getattr(e, "response", None)
+            user_msg = _log_ado_patch_failure(resp, patch_document, url)
+            e.ado_user_message = user_msg
+            console.print(f"[bold red]✗[/bold red] {user_msg}")
             raise
 
     def _update_work_item_status(
@@ -1717,8 +1803,9 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
                 "state": ado_state,
             }
         except requests.RequestException as e:
-            msg = f"Failed to update Azure DevOps work item #{work_item_id}: {e}"
-            console.print(f"[bold red]✗[/bold red] {msg}")
+            resp = getattr(e, "response", None)
+            user_msg = _log_ado_patch_failure(resp, patch_document, url)
+            console.print(f"[bold red]✗[/bold red] {user_msg}")
             raise
 
     def _update_work_item_body(
@@ -1740,6 +1827,8 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
         Returns:
             Dict with updated work item data: {"work_item_id": int, "work_item_url": str, "state": str}
         """
+        import re as _re
+
         title = proposal_data.get("title", "Untitled Change Proposal")
         description = proposal_data.get("description", "")
         rationale = proposal_data.get("rationale", "")
@@ -1756,7 +1845,7 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
         else:
             body_parts = []
 
-            display_title = re.sub(r"^\[change\]\s*", "", title, flags=re.IGNORECASE).strip()
+            display_title = _re.sub(r"^\[change\]\s*", "", title, flags=_re.IGNORECASE).strip()
             if display_title:
                 body_parts.append(f"# {display_title}")
                 body_parts.append("")
@@ -1847,8 +1936,9 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
                 "state": ado_state,
             }
         except requests.RequestException as e:
-            msg = f"Failed to update Azure DevOps work item #{work_item_id}: {e}"
-            console.print(f"[bold red]✗[/bold red] {msg}")
+            resp = getattr(e, "response", None)
+            user_msg = _log_ado_patch_failure(resp, patch_document, url)
+            console.print(f"[bold red]✗[/bold red] {user_msg}")
             raise
 
     @beartype
@@ -1954,8 +2044,10 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
                 "new_state": ado_state,
             }
         except requests.RequestException as e:
-            msg = f"Failed to sync status to Azure DevOps work item #{work_item_id}: {e}"
-            console.print(f"[bold red]✗[/bold red] {msg}")
+            resp = getattr(e, "response", None)
+            user_msg = _log_ado_patch_failure(resp, patch_document, url)
+            e.ado_user_message = user_msg
+            console.print(f"[bold red]✗[/bold red] {user_msg}")
             raise
 
     @beartype
@@ -2332,8 +2424,10 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
                 "comment_added": True,
             }
         except requests.RequestException as e:
-            msg = f"Failed to add comment to Azure DevOps work item #{work_item_id}: {e}"
-            console.print(f"[bold red]✗[/bold red] {msg}")
+            resp = getattr(e, "response", None)
+            user_msg = _log_ado_patch_failure(resp, [], url)
+            e.ado_user_message = user_msg
+            console.print(f"[bold red]✗[/bold red] {user_msg}")
             raise
 
     @beartype
@@ -2908,8 +3002,22 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
 
             try:
                 response = requests.get(url, headers=workitems_headers, params=params, timeout=30)
+                if is_debug_mode():
+                    debug_log_operation(
+                        "ado_workitems_get",
+                        url,
+                        str(response.status_code),
+                        error=None if response.ok else (response.text[:200] if response.text else None),
+                    )
                 response.raise_for_status()
             except requests.HTTPError as e:
+                if is_debug_mode():
+                    debug_log_operation(
+                        "ado_workitems_get",
+                        url,
+                        "error",
+                        error=str(e.response.status_code) if e.response is not None else str(e),
+                    )
                 # Provide better error message with URL details
                 error_detail = ""
                 if e.response is not None:
@@ -3095,11 +3203,12 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
 
         # Update description (body_markdown) - always use System.Description
         if update_fields is None or "body" in update_fields or "body_markdown" in update_fields:
-            # Convert TODO markers to proper Markdown checkboxes for ADO rendering
             import re
 
-            markdown_content = item.body_markdown
-            # Pattern matches: * [TODO: ...] or - [TODO: ...] or *[TODO: ...] or -[TODO: ...]
+            # Never send null: ADO rejects null for /fields/System.Description (HTTP 400)
+            raw_body = item.body_markdown
+            markdown_content = raw_body if raw_body is not None else ""
+            # Convert TODO markers to proper Markdown checkboxes for ADO rendering
             todo_pattern = r"^(\s*)[-*]\s*\[TODO[:\s]+([^\]]+)\](.*)$"
             markdown_content = re.sub(
                 todo_pattern,
@@ -3108,11 +3217,9 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
                 flags=re.MULTILINE | re.IGNORECASE,
             )
 
-            # Get mapped description field name (honors custom mappings)
             description_field = reverse_mappings.get("description", "System.Description")
-            # Set multiline field format to Markdown FIRST (before setting content)
+            # Set multiline field format to Markdown first (optional; many ADO instances return 400 for this path)
             operations.append({"op": "add", "path": f"/multilineFieldsFormat/{description_field}", "value": "Markdown"})
-            # Then set description content with Markdown format
             operations.append({"op": "replace", "path": f"/fields/{description_field}", "value": markdown_content})
 
         # Update acceptance criteria using mapped field name (honors custom mappings)
@@ -3158,7 +3265,9 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
             response = requests.patch(url, headers=headers, json=operations, timeout=30)
             response.raise_for_status()
         except requests.HTTPError as e:
-            # Handle various error cases
+            user_msg = _log_ado_patch_failure(e.response, operations, url)
+            e.ado_user_message = user_msg
+            response = None
             if e.response and e.response.status_code in (400, 422):
                 error_message = ""
                 try:
@@ -3167,91 +3276,79 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
                 except Exception:
                     pass
 
-                # Check if error is about multilineFieldsFormat already existing (use "replace" instead)
-                if "already exists" in error_message.lower() or "cannot add" in error_message.lower():
-                    # Try with "replace" operation for multilineFieldsFormat
+                # First retry: omit multilineFieldsFormat entirely (only /fields/ updates).
+                # Many ADO instances reject /multilineFieldsFormat/ path with 400 Bad Request.
+                operations_no_format = [
+                    op for op in operations if not (op.get("path") or "").startswith("/multilineFieldsFormat/")
+                ]
+                if operations_no_format != operations:
+                    try:
+                        resp = requests.patch(url, headers=headers, json=operations_no_format, timeout=30)
+                        resp.raise_for_status()
+                        response = resp
+                    except requests.HTTPError as retry_error:
+                        _log_ado_patch_failure(
+                            retry_error.response,
+                            operations_no_format,
+                            url,
+                            context=str(retry_error),
+                        )
+
+                if response is None and (
+                    "already exists" in error_message.lower() or "cannot add" in error_message.lower()
+                ):
+                    # Second: try "replace" instead of "add" for multilineFieldsFormat
                     operations_replace = []
                     for op in operations:
-                        if op.get("path") == "/multilineFieldsFormat/System.Description":
-                            # Change to replace operation
-                            operations_replace.append({"op": "replace", "path": op["path"], "value": op["value"]})
+                        path = op.get("path") or ""
+                        if path.startswith("/multilineFieldsFormat/"):
+                            operations_replace.append({"op": "replace", "path": path, "value": op["value"]})
                         else:
                             operations_replace.append(op)
-
                     try:
-                        response = requests.patch(url, headers=headers, json=operations_replace, timeout=30)
-                        response.raise_for_status()
+                        resp = requests.patch(url, headers=headers, json=operations_replace, timeout=30)
+                        resp.raise_for_status()
+                        response = resp
                     except requests.HTTPError:
-                        # If replace also fails, fallback to HTML conversion
-                        console.print("[yellow]⚠ Markdown format not supported, converting to HTML[/yellow]")
-                        operations_html = [
-                            op for op in operations if "/multilineFieldsFormat/" not in op.get("path", "")
-                        ]
-                        # Find description operation and convert markdown to HTML
-                        for op in operations_html:
-                            if op.get("path") == "/fields/System.Description":
-                                # Convert TODO markers to HTML checkboxes before converting to HTML
-                                import re
-
-                                markdown_for_html = op["value"]
-                                # Convert TODO markers to checkboxes first
-                                todo_pattern = r"^(\s*)[-*]\s*\[TODO[:\s]+([^\]]+)\](.*)$"
-                                markdown_for_html = re.sub(
-                                    todo_pattern,
-                                    r"\1- [ ] \2",
-                                    markdown_for_html,
-                                    flags=re.MULTILINE | re.IGNORECASE,
-                                )
-                                # Simple markdown to HTML conversion (basic)
-                                try:
-                                    import markdown
-
-                                    html_body = markdown.markdown(
-                                        markdown_for_html, extensions=["fenced_code", "tables"]
-                                    )
-                                    op["value"] = html_body
-                                except ImportError:
-                                    # markdown library not available - use raw text
-                                    console.print("[yellow]⚠ markdown library not available, using raw text[/yellow]")
-                                    # Keep original markdown as-is (ADO may still render it)
-                                break
-
-                        response = requests.patch(url, headers=headers, json=operations_html, timeout=30)
-                        response.raise_for_status()
-                else:
-                    # Other 400/422 errors - try HTML fallback
-                    console.print("[yellow]⚠ Markdown format not supported, converting to HTML[/yellow]")
-                    operations_html = [op for op in operations if "/multilineFieldsFormat/" not in op.get("path", "")]
-                    # Find description operation and convert markdown to HTML
+                        pass
+
+                if response is None:
+                    # Third: HTML fallback (no multilineFieldsFormat, description as HTML)
+                    import re as _re
+
+                    console.print("[yellow]⚠ Markdown format not supported, converting description to HTML[/yellow]")
+                    operations_html = [
+                        op for op in operations if not (op.get("path") or "").startswith("/multilineFieldsFormat/")
+                    ]
+                    description_field = reverse_mappings.get("description", "System.Description")
+                    desc_path = f"/fields/{description_field}"
                     for op in operations_html:
-                        if op.get("path") == "/fields/System.Description":
-                            # Convert TODO markers to HTML checkboxes before converting to HTML
-                            import re
-
-                            markdown_for_html = op["value"]
-                            # Convert TODO markers to checkboxes first
+                        if op.get("path") == desc_path:
+                            markdown_for_html = op.get("value") or ""
                             todo_pattern = r"^(\s*)[-*]\s*\[TODO[:\s]+([^\]]+)\](.*)$"
-                            markdown_for_html = re.sub(
+                            markdown_for_html = _re.sub(
                                 todo_pattern,
                                 r"\1- [ ] \2",
                                 markdown_for_html,
-                                flags=re.MULTILINE | re.IGNORECASE,
+                                flags=_re.MULTILINE | _re.IGNORECASE,
                             )
-                            # Simple markdown to HTML conversion (basic)
                             try:
                                 import markdown
 
-                                html_body = markdown.markdown(markdown_for_html, extensions=["fenced_code", "tables"])
-                                op["value"] = html_body
+                                op["value"] = markdown.markdown(markdown_for_html, extensions=["fenced_code", "tables"])
                             except ImportError:
-                                # markdown library not available - use raw text
-                                console.print("[yellow]⚠ markdown library not available, using raw text[/yellow]")
-                                # Keep original markdown as-is (ADO may still render it)
+                                pass
                             break
+                    try:
+                        resp = requests.patch(url, headers=headers, json=operations_html, timeout=30)
+                        resp.raise_for_status()
+                        response = resp
+                    except requests.HTTPError:
+                        console.print(f"[bold red]✗[/bold red] {user_msg}")
+                        raise
 
-                    response = requests.patch(url, headers=headers, json=operations_html, timeout=30)
-                    response.raise_for_status()
-            else:
+            if response is None:
+                console.print(f"[bold red]✗[/bold red] {user_msg}")
                 raise
 
         updated_work_item = response.json()

{specfact_cli-0.26.11 → specfact_cli-0.26.14}/src/specfact_cli/adapters/github.py

@@ -35,6 +35,7 @@ from specfact_cli.models.backlog_item import BacklogItem
 from specfact_cli.models.bridge import BridgeConfig
 from specfact_cli.models.capabilities import ToolCapabilities
 from specfact_cli.models.change import ChangeProposal, ChangeTracking
+from specfact_cli.runtime import debug_log_operation, is_debug_mode
 from specfact_cli.utils.auth_tokens import get_token
 
 
@@ -817,6 +818,13 @@ class GitHubAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
             "Accept": "application/vnd.github.v3+json",
         }
         response = requests.get(url, headers=headers, timeout=30)
+        if is_debug_mode():
+            debug_log_operation(
+                "github_api_get",
+                url,
+                str(response.status_code),
+                error=None if response.ok else (response.text[:200] if response.text else None),
+            )
         response.raise_for_status()
         return response.json()
 

{specfact_cli-0.26.11 → specfact_cli-0.26.14}/src/specfact_cli/cli.py

@@ -75,7 +75,7 @@ from specfact_cli.commands import (
     validate,
 )
 from specfact_cli.modes import OperationalMode, detect_mode
-from specfact_cli.runtime import get_configured_console, set_debug_mode
+from specfact_cli.runtime import get_configured_console, init_debug_log_file, set_debug_mode
 from specfact_cli.utils.progressive_disclosure import ProgressiveDisclosureGroup
 from specfact_cli.utils.structured_io import StructuredFormat
 
@@ -246,7 +246,7 @@ def main(
     debug: bool = typer.Option(
         False,
         "--debug",
-        help="Enable debug output (shows detailed logging and diagnostic information)",
+        help="Enable debug output: console diagnostics and log file at ~/.specfact/logs/specfact-debug.log (operation metadata for file I/O and API calls)",
     ),
     skip_checks: bool = typer.Option(
         False,
@@ -297,6 +297,8 @@ def main(
 
     # Set debug mode
     set_debug_mode(debug)
+    if debug:
+        init_debug_log_file()
 
     runtime.configure_io_formats(input_format=input_format, output_format=output_format)
     # Invert logic: --interactive means not non-interactive, --no-interactive means non-interactive

{specfact_cli-0.26.11 → specfact_cli-0.26.14}/src/specfact_cli/commands/analyze.py

@@ -17,6 +17,7 @@ from rich.console import Console
 from rich.table import Table
 
 from specfact_cli.models.quality import CodeQuality, QualityTracking
+from specfact_cli.runtime import debug_log_operation, debug_print, is_debug_mode
 from specfact_cli.telemetry import telemetry
 from specfact_cli.utils import print_error, print_success
 from specfact_cli.utils.progress import load_bundle_with_progress
@@ -63,12 +64,23 @@ def analyze_contracts(
     **Examples:**
         specfact analyze contracts --repo . --bundle legacy-api
     """
+    if is_debug_mode():
+        debug_log_operation("command", "analyze contracts", "started", extra={"repo": str(repo), "bundle": bundle})
+        debug_print("[dim]analyze contracts: started[/dim]")
     console = Console()
 
     # Use active plan as default if bundle not provided
     if bundle is None:
         bundle = SpecFactStructure.get_active_bundle_name(repo)
         if bundle is None:
+            if is_debug_mode():
+                debug_log_operation(
+                    "command",
+                    "analyze contracts",
+                    "failed",
+                    error="Bundle name required",
+                    extra={"reason": "no_bundle"},
+                )
             console.print("[bold red]✗[/bold red] Bundle name required")
             console.print("[yellow]→[/yellow] Use --bundle option or run 'specfact plan select' to set active plan")
             raise typer.Exit(1)
@@ -78,6 +90,14 @@ def analyze_contracts(
     bundle_dir = SpecFactStructure.project_dir(base_path=repo_path, bundle_name=bundle)
 
     if not bundle_dir.exists():
+        if is_debug_mode():
+            debug_log_operation(
+                "command",
+                "analyze contracts",
+                "failed",
+                error=f"Bundle not found: {bundle_dir}",
+                extra={"reason": "bundle_missing"},
+            )
         print_error(f"Project bundle not found: {bundle_dir}")
         raise typer.Exit(1)
 
@@ -200,6 +220,14 @@ def analyze_contracts(
                 "files_with_crosshair": files_with_crosshair,
             }
         )
+        if is_debug_mode():
+            debug_log_operation(
+                "command",
+                "analyze contracts",
+                "success",
+                extra={"files_analyzed": files_analyzed, "bundle": bundle},
+            )
+            debug_print("[dim]analyze contracts: success[/dim]")
 
 
 def _analyze_file_quality(file_path: Path) -> CodeQuality: