specfact-cli 0.26.0__tar.gz → 0.26.1__tar.gz

{specfact_cli-0.26.0 → specfact_cli-0.26.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specfact-cli
-Version: 0.26.0
+Version: 0.26.1
 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

{specfact_cli-0.26.0 → specfact_cli-0.26.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "specfact-cli"
-version = "0.26.0"
+version = "0.26.1"
 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.0 → specfact_cli-0.26.1}/resources/prompts/specfact.backlog-refine.md

@@ -155,20 +155,39 @@ Display refinement results:
 
 - `assignees`: Preserved
 - `tags`: Preserved
-- `state`: Preserved
+- `state`: Preserved (original state maintained)
 - `priority`: Preserved (if present in provider_fields)
 - `due_date`: Preserved (if present in provider_fields)
 - `story_points`: Preserved (if present in provider_fields)
 - `sprint`: Preserved (if present)
 - `release`: Preserved (if present)
+- `source_state`: Preserved for cross-adapter state mapping (stored in bundle entries)
 - All other metadata: Preserved in provider_fields
 
+**Cross-Adapter State Preservation**:
+
+- When items are imported into bundles, the original `source_state` (e.g., "open", "closed", "New", "Active") is stored in `source_metadata["source_state"]`
+- During cross-adapter export (e.g., GitHub → ADO), the `source_state` is used to determine the correct target state
+- Generic state mapping ensures state is correctly translated between any adapter pair using OpenSpec as intermediate format
+- This ensures closed GitHub issues sync to ADO as "Closed", and open GitHub issues sync to ADO as "New"
+
 **OpenSpec Comment Integration**:
 
 - When `--openspec-comment` is used, a structured comment is added to the backlog item
 - The comment includes: Change ID, template used, confidence score, refinement timestamp
 - Original body is preserved; comment provides OpenSpec reference for cross-sync
 
+**Cross-Adapter State Mapping**:
+
+- When refining items that will be synced across adapters (e.g., GitHub ↔ ADO), state is preserved using generic mapping
+- Generic state mapping uses OpenSpec as intermediate format:
+  - Source adapter state → OpenSpec status → Target adapter state
+  - Example: GitHub "open" → OpenSpec "proposed" → ADO "New"
+  - Example: GitHub "closed" → OpenSpec "applied" → ADO "Closed"
+- State preservation: Original `source_state` is stored in bundle entries and used during cross-adapter export
+- Bidirectional mapping: Works in both directions (GitHub → ADO and ADO → GitHub)
+- State mapping is automatic during `sync bridge` operations when `source_state` and `source_type` are present
+
 ## Architecture Note
 
 SpecFact CLI follows a CLI-first architecture:
@@ -232,6 +251,16 @@ Items updated in remote backlog:
 
 # Refine and import to OpenSpec bundle
 /specfact.backlog-refine --adapter github --repo-owner nold-ai --repo-name specfact-cli --bundle my-project --auto-bundle --state open
+
+# Cross-adapter sync workflow: Refine GitHub → Sync to ADO (with state preservation)
+/specfact.backlog-refine --adapter github --repo-owner nold-ai --repo-name specfact-cli --write --labels feature
+# Then sync to ADO (state will be automatically mapped: open → New, closed → Closed)
+# specfact sync bridge --adapter ado --ado-org my-org --ado-project my-project --mode bidirectional
+
+# Cross-adapter sync workflow: Refine ADO → Sync to GitHub (with state preservation)
+/specfact.backlog-refine --adapter ado --ado-org my-org --ado-project my-project --write --state Active
+# Then sync to GitHub (state will be automatically mapped: New → open, Closed → closed)
+# specfact sync bridge --adapter github --repo-owner my-org --repo-name my-repo --mode bidirectional
 ```
 
 ## Context

{specfact_cli-0.26.0 → specfact_cli-0.26.1}/src/__init__.py

@@ -3,4 +3,4 @@ SpecFact CLI - Spec→Contract→Sentinel tool for contract-driven development.
 """
 
 # Define the package version (kept in sync with pyproject.toml and setup.py)
-__version__ = "0.26.0"
+__version__ = "0.26.1"

{specfact_cli-0.26.0 → specfact_cli-0.26.1}/src/specfact_cli/__init__.py

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

{specfact_cli-0.26.0 → specfact_cli-0.26.1}/src/specfact_cli/adapters/ado.py

@@ -200,6 +200,12 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
 
         Note:
             This implements the tool-agnostic metadata extraction pattern for Azure DevOps.
+            Future backlog adapters should implement similar parsing for their tools.
+
+            Change ID extraction priority:
+            1. Description footer (legacy format): *OpenSpec Change Proposal: `id`*
+            2. Comments (new format): **Change ID**: `id` in OpenSpec Change Proposal Reference comment
+            3. Work item ID (fallback)
         """
         if not isinstance(item_data, dict):
             msg = "ADO work item data must be dict"
@@ -256,15 +262,40 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
             if impact_match:
                 impact = impact_match.group(1).strip()
 
-        # Extract change ID from OpenSpec metadata footer or work item ID
+        # Extract change ID from OpenSpec metadata footer, comments, or work item ID
         change_id = None
+
+        # First, check description for OpenSpec metadata footer (legacy format)
         if description_raw:
             # Look for OpenSpec metadata footer: *OpenSpec Change Proposal: `{change_id}`*
             change_id_match = re.search(r"OpenSpec Change Proposal:\s*`([^`]+)`", description_raw, re.IGNORECASE)
             if change_id_match:
                 change_id = change_id_match.group(1)
+
+        # If not found in description, check comments (new format - OpenSpec info in comments)
+        if not change_id:
+            work_item_id = item_data.get("id")
+            if work_item_id and self.org and self.project:
+                comments = self._get_work_item_comments(self.org, self.project, work_item_id)
+                # Look for OpenSpec Change Proposal Reference comment
+                openspec_patterns = [
+                    r"\*\*Change ID\*\*[:\s]+`([a-z0-9-]+)`",
+                    r"Change ID[:\s]+`([a-z0-9-]+)`",
+                    r"OpenSpec Change Proposal[:\s]+`?([a-z0-9-]+)`?",
+                    r"\*OpenSpec Change Proposal:\s*`([a-z0-9-]+)`",
+                ]
+                for comment in comments:
+                    comment_text = comment.get("text", "") or comment.get("body", "")
+                    for pattern in openspec_patterns:
+                        match = re.search(pattern, comment_text, re.IGNORECASE | re.DOTALL)
+                        if match:
+                            change_id = match.group(1)
+                            break
+                    if change_id:
+                        break
+
+        # Fallback to work item ID if still not found
         if not change_id:
-            # Use work item ID as fallback
             change_id = str(item_data.get("id", "unknown"))
 
         # Extract status from System.State
@@ -1298,7 +1329,15 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
         work_item_type = self._get_work_item_type(org, project)
 
         # Map status to ADO state
-        ado_state = self.map_openspec_status_to_backlog(status)
+        # Check if source_state and source_type are provided (from cross-adapter sync)
+        source_state = proposal_data.get("source_state")
+        source_type = proposal_data.get("source_type")
+        if source_state and source_type and source_type != "ado":
+            # Use generic cross-adapter state mapping (preserves original state from source adapter)
+            ado_state = self.map_backlog_state_between_adapters(source_state, source_type, self)
+        else:
+            # Use OpenSpec status mapping (default behavior)
+            ado_state = self.map_openspec_status_to_backlog(status)
 
         # Ensure API token is available
         if not self.api_token:
@@ -1436,7 +1475,15 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
         status = proposal_data.get("status", "proposed")
 
         # Map status to ADO state
-        ado_state = self.map_openspec_status_to_backlog(status)
+        # Check if source_state and source_type are provided (from cross-adapter sync)
+        source_state = proposal_data.get("source_state")
+        source_type = proposal_data.get("source_type")
+        if source_state and source_type and source_type != "ado":
+            # Use generic cross-adapter state mapping (preserves original state from source adapter)
+            ado_state = self.map_backlog_state_between_adapters(source_state, source_type, self)
+        else:
+            # Use OpenSpec status mapping (default behavior)
+            ado_state = self.map_openspec_status_to_backlog(status)
 
         # Ensure API token is available
         if not self.api_token:
@@ -1546,7 +1593,15 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
             body = "\n".join(body_parts)
 
         # Map status to ADO state
-        ado_state = self.map_openspec_status_to_backlog(status)
+        # Check if source_state and source_type are provided (from cross-adapter sync)
+        source_state = proposal_data.get("source_state")
+        source_type = proposal_data.get("source_type")
+        if source_state and source_type and source_type != "ado":
+            # Use generic cross-adapter state mapping (preserves original state from source adapter)
+            ado_state = self.map_backlog_state_between_adapters(source_state, source_type, self)
+        else:
+            # Use OpenSpec status mapping (default behavior)
+            ado_state = self.map_openspec_status_to_backlog(status)
 
         # Ensure API token is available
         if not self.api_token:
@@ -1980,6 +2035,37 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
             self.console.log(f"[bold yellow]Warning:[/bold yellow] Error checking branch existence: {e}")
             return False
 
+    def _get_work_item_comments(self, org: str, project: str, work_item_id: int) -> list[dict[str, Any]]:
+        """
+        Fetch comments for an Azure DevOps work item.
+
+        Args:
+            org: Azure DevOps organization
+            project: Azure DevOps project
+            work_item_id: Work item ID
+
+        Returns:
+            List of comment dicts with 'text' or 'body' field, or empty list on error
+        """
+        if not self.api_token:
+            return []
+
+        url = f"{self.base_url}/{org}/{project}/_apis/wit/workitems/{work_item_id}/comments?api-version=7.1"
+        headers = {
+            "Accept": "application/json",
+            **self._auth_headers(),
+        }
+
+        try:
+            response = requests.get(url, headers=headers, timeout=30)
+            response.raise_for_status()
+            # ADO API returns comments in a 'comments' array within the response
+            response_data = response.json()
+            return response_data.get("comments", [])
+        except requests.RequestException:
+            # Return empty list on error - comments are optional
+            return []
+
     @beartype
     @require(lambda org: isinstance(org, str) and org, "Organization must be non-empty string")
     @require(lambda project: isinstance(project, str) and project, "Project must be non-empty string")

{specfact_cli-0.26.0 → specfact_cli-0.26.1}/src/specfact_cli/adapters/backlog_base.py

@@ -74,6 +74,72 @@ class BacklogAdapterMixin(ABC):
             tool-specific status mapping logic.
         """
 
+    @beartype
+    @require(
+        lambda source_state: isinstance(source_state, str) and len(source_state) > 0,
+        "Source state must be non-empty string",
+    )
+    @require(
+        lambda source_adapter_type: isinstance(source_adapter_type, str) and len(source_adapter_type) > 0,
+        "Source adapter type must be non-empty string",
+    )
+    @require(
+        lambda target_adapter: isinstance(target_adapter, BacklogAdapterMixin),
+        "Target adapter must implement BacklogAdapterMixin",
+    )
+    @ensure(lambda result: isinstance(result, str), "Must return status string")
+    def map_backlog_state_between_adapters(
+        self, source_state: str, source_adapter_type: str, target_adapter: BacklogAdapterMixin
+    ) -> str:
+        """
+        Map backlog state from one adapter to another using OpenSpec as intermediate format.
+
+        This method provides generic cross-adapter state mapping by:
+        1. Getting the source adapter instance
+        2. Mapping source state to OpenSpec status using source adapter's mapping
+        3. Mapping OpenSpec status to target state using target adapter's mapping
+
+        Args:
+            source_state: State from source adapter (e.g., "open", "closed", "New", "Active")
+            source_adapter_type: Source adapter type (e.g., "github", "ado", "jira")
+            target_adapter: Target adapter instance (must implement BacklogAdapterMixin)
+
+        Returns:
+            Target adapter state string
+
+        Note:
+            This is a generic method that works for any adapter pair by using OpenSpec
+            as the intermediate format. It requires the source adapter to be registered
+            in AdapterRegistry to retrieve its mapping methods.
+        """
+        from specfact_cli.adapters.registry import AdapterRegistry
+
+        # Get source adapter instance to use its mapping methods
+        source_adapter = AdapterRegistry.get_adapter(source_adapter_type)
+        if not source_adapter or not isinstance(source_adapter, BacklogAdapterMixin):
+            # Fallback: if source adapter not found, try to map directly
+            # This handles cases where source adapter might not be registered
+            # In this case, we'll use the target adapter's default mapping
+            openspec_status = "proposed"  # Default fallback
+        else:
+            # Step 1: Map source state to OpenSpec status using source adapter
+            openspec_status = source_adapter.map_backlog_status_to_openspec(source_state)
+
+        # Step 2: Map OpenSpec status to target state using target adapter
+        # Special handling for GitHub adapter: use issue state method instead of labels
+        if hasattr(target_adapter, "map_openspec_status_to_issue_state"):
+            # GitHub adapter: use issue state mapping (open/closed)
+            return target_adapter.map_openspec_status_to_issue_state(openspec_status)
+
+        target_state = target_adapter.map_openspec_status_to_backlog(openspec_status)
+
+        # Handle list return type (some adapters return lists)
+        if isinstance(target_state, list):
+            # Use first element if list (typically the primary state)
+            return target_state[0] if target_state else "New"
+
+        return target_state
+
     @abstractmethod
     @beartype
     @require(lambda item_data: isinstance(item_data, dict), "Item data must be dict")

{specfact_cli-0.26.0 → specfact_cli-0.26.1}/src/specfact_cli/adapters/github.py

@@ -169,6 +169,30 @@ class GitHubAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
         # Default: treat as proposed
         return "proposed"
 
+    @beartype
+    @require(lambda status: isinstance(status, str) and len(status) > 0, "Status must be non-empty string")
+    @ensure(lambda result: isinstance(result, str), "Must return issue state string")
+    def map_openspec_status_to_issue_state(self, status: str) -> str:
+        """
+        Map OpenSpec change status to GitHub issue state (open/closed).
+
+        Args:
+            status: OpenSpec change status (proposed, in-progress, applied, deprecated, discarded)
+
+        Returns:
+            GitHub issue state: "open" or "closed"
+
+        Note:
+            This method is used for cross-adapter state mapping where we need the
+            actual issue state, not labels. For label mapping, use map_openspec_status_to_backlog().
+        """
+        # Map OpenSpec status to GitHub issue state
+        # "applied", "deprecated", "discarded" → closed
+        # "proposed", "in-progress" → open
+        if status in ("applied", "deprecated", "discarded"):
+            return "closed"
+        return "open"
+
     @beartype
     @require(lambda status: isinstance(status, str) and len(status) > 0, "Status must be non-empty string")
     @ensure(lambda result: isinstance(result, list), "Must return list of label strings")
@@ -185,6 +209,8 @@ class GitHubAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
         Note:
             This implements the tool-agnostic status mapping pattern for GitHub.
             Future backlog adapters should implement similar mappings for their tools.
+
+            For cross-adapter state mapping (issue state, not labels), use map_openspec_status_to_issue_state().
         """
         labels = ["openspec"]
 
@@ -210,6 +236,7 @@ class GitHubAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
         - Title (from issue title)
         - Description (What Changes section)
         - Rationale (Why section)
+        - Change ID (from body footer or comments)
         - Other optional fields (timeline, owner, stakeholders, dependencies)
 
         Args:
@@ -220,6 +247,7 @@ class GitHubAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
             - title: str
             - description: str (What Changes section)
             - rationale: str (Why section)
+            - change_id: str (extracted from body footer or comments)
             - status: str (mapped to OpenSpec status)
             - Other optional fields
 
@@ -229,6 +257,11 @@ class GitHubAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
         Note:
             This implements the tool-agnostic metadata extraction pattern for GitHub.
             Future backlog adapters should implement similar parsing for their tools.
+
+            Change ID extraction priority:
+            1. Body footer (legacy format): *OpenSpec Change Proposal: `id`*
+            2. Comments (new format): **Change ID**: `id` in OpenSpec Change Proposal Reference comment
+            3. Issue number (fallback)
         """
         if not isinstance(item_data, dict):
             msg = "GitHub issue data must be dict"
@@ -278,15 +311,41 @@ class GitHubAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
             if impact_match:
                 impact = impact_match.group(1).strip()
 
-        # Extract change ID from OpenSpec metadata footer or issue number
+        # Extract change ID from OpenSpec metadata footer, comments, or issue number
         change_id = None
+
+        # First, check body for OpenSpec metadata footer (legacy format)
         if body:
             # Look for OpenSpec metadata footer: *OpenSpec Change Proposal: `{change_id}`*
             change_id_match = re.search(r"OpenSpec Change Proposal:\s*`([^`]+)`", body, re.IGNORECASE)
             if change_id_match:
                 change_id = change_id_match.group(1)
+
+        # If not found in body, check comments (new format - OpenSpec info in comments)
+        if not change_id:
+            issue_number = item_data.get("number")
+            if issue_number and self.repo_owner and self.repo_name:
+                comments = self._get_issue_comments(self.repo_owner, self.repo_name, issue_number)
+                # Look for OpenSpec Change Proposal Reference comment
+                # Pattern 1: Structured comment format with "**Change ID**: `id`"
+                openspec_patterns = [
+                    r"\*\*Change ID\*\*[:\s]+`([a-z0-9-]+)`",
+                    r"Change ID[:\s]+`([a-z0-9-]+)`",
+                    r"OpenSpec Change Proposal[:\s]+`?([a-z0-9-]+)`?",
+                    r"\*OpenSpec Change Proposal:\s*`([a-z0-9-]+)`",
+                ]
+                for comment in comments:
+                    comment_body = comment.get("body", "")
+                    for pattern in openspec_patterns:
+                        match = re.search(pattern, comment_body, re.IGNORECASE | re.DOTALL)
+                        if match:
+                            change_id = match.group(1)
+                            break
+                    if change_id:
+                        break
+
+        # Fallback to issue number if still not found
         if not change_id:
-            # Use issue number as fallback
             change_id = str(item_data.get("number", "unknown"))
 
         # Extract status from labels
@@ -491,12 +550,17 @@ class GitHubAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
                 source_metadata.setdefault("source_repo", source_repo)
 
             entry_id = artifact_path.get("number") or artifact_path.get("id")
+            # Extract GitHub issue state (open/closed) for cross-adapter sync state preservation
+            github_state = artifact_path.get("state", "open").lower()
             entry = {
                 "source_id": str(entry_id) if entry_id is not None else None,
                 "source_url": artifact_path.get("html_url") or artifact_path.get("url") or "",
                 "source_type": "github",
                 "source_repo": source_repo or "",
-                "source_metadata": {"last_synced_status": proposal.status},
+                "source_metadata": {
+                    "last_synced_status": proposal.status,
+                    "source_state": github_state,  # Preserve GitHub state for cross-adapter sync
+                },
             }
             entries = source_metadata.get("backlog_entries")
             if not isinstance(entries, list):
@@ -1011,6 +1075,17 @@ class GitHubAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
 
             body = "\n".join(body_parts)
 
+        # Check for API token before making request
+        if not self.api_token:
+            msg = (
+                "GitHub API token required to create issues. Options:\n"
+                "  1. Set GITHUB_TOKEN environment variable\n"
+                "  2. Use --github-token option\n"
+                "  3. Use GitHub CLI authentication (gh auth login)\n"
+                "  4. Store token via specfact auth github"
+            )
+            raise ValueError(msg)
+
         # Create issue via GitHub API
         url = f"{self.base_url}/repos/{repo_owner}/{repo_name}/issues"
         headers = {
@@ -1018,9 +1093,24 @@ class GitHubAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
             "Accept": "application/vnd.github.v3+json",
         }
         # Determine issue state based on proposal status
-        # Completed proposals (applied, deprecated, discarded) should be closed
-        should_close = status in ("applied", "deprecated", "discarded")
-        issue_state = "closed" if should_close else "open"
+        # Check if source_state and source_type are provided (from cross-adapter sync)
+        source_state = proposal_data.get("source_state")
+        source_type = proposal_data.get("source_type")
+        if source_state and source_type and source_type != "github":
+            # Use generic cross-adapter state mapping (preserves original state from source adapter)
+            from specfact_cli.adapters.registry import AdapterRegistry
+
+            source_adapter = AdapterRegistry.get_adapter(source_type)
+            if source_adapter and hasattr(source_adapter, "map_backlog_state_between_adapters"):
+                issue_state = source_adapter.map_backlog_state_between_adapters(source_state, source_type, self)
+            else:
+                # Fallback: map via OpenSpec status
+                should_close = status in ("applied", "deprecated", "discarded")
+                issue_state = "closed" if should_close else "open"
+        else:
+            # Use OpenSpec status mapping (default behavior)
+            should_close = status in ("applied", "deprecated", "discarded")
+            issue_state = "closed" if should_close else "open"
 
         # Map status to GitHub state_reason
         state_reason = None
@@ -1120,7 +1210,23 @@ class GitHubAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
         title = proposal_data.get("title", "Untitled")
 
         # Map status to GitHub issue state and comment
-        should_close = status in ("applied", "deprecated", "discarded")
+        # Check if source_state and source_type are provided (from cross-adapter sync)
+        source_state = proposal_data.get("source_state")
+        source_type = proposal_data.get("source_type")
+        if source_state and source_type and source_type != "github":
+            # Use generic cross-adapter state mapping (preserves original state from source adapter)
+            from specfact_cli.adapters.registry import AdapterRegistry
+
+            source_adapter = AdapterRegistry.get_adapter(source_type)
+            if source_adapter and hasattr(source_adapter, "map_backlog_state_between_adapters"):
+                issue_state = source_adapter.map_backlog_state_between_adapters(source_state, source_type, self)
+                should_close = issue_state == "closed"
+            else:
+                # Fallback: map via OpenSpec status
+                should_close = status in ("applied", "deprecated", "discarded")
+        else:
+            # Use OpenSpec status mapping (default behavior)
+            should_close = status in ("applied", "deprecated", "discarded")
         source_tracking = proposal_data.get("source_tracking", {})
         # Note: code_repo_path not available in _update_issue_status context
         comment_text = self._get_status_comment(status, title, source_tracking, None)
@@ -1161,6 +1267,35 @@ class GitHubAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
             console.print(f"[bold red]✗[/bold red] {msg}")
             raise
 
+    def _get_issue_comments(self, repo_owner: str, repo_name: str, issue_number: int) -> list[dict[str, Any]]:
+        """
+        Fetch comments for a GitHub issue.
+
+        Args:
+            repo_owner: GitHub repository owner
+            repo_name: GitHub repository name
+            issue_number: Issue number
+
+        Returns:
+            List of comment dicts with 'body' field, or empty list on error
+        """
+        if not self.api_token:
+            return []
+
+        url = f"{self.base_url}/repos/{repo_owner}/{repo_name}/issues/{issue_number}/comments"
+        headers = {
+            "Authorization": f"token {self.api_token}",
+            "Accept": "application/vnd.github.v3+json",
+        }
+
+        try:
+            response = requests.get(url, headers=headers, timeout=30)
+            response.raise_for_status()
+            return response.json()
+        except requests.RequestException:
+            # Return empty list on error - comments are optional
+            return []
+
     def _add_issue_comment(self, repo_owner: str, repo_name: str, issue_number: int, comment: str) -> None:
         """
         Add comment to GitHub issue.
@@ -2419,7 +2554,7 @@ class GitHubAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
     @beartype
     @require(lambda item: isinstance(item, BacklogItem), "Item must be BacklogItem")
     @require(
-        lambda update_fields: update_fields is None or isinstance(update_fields, list),
+        lambda item, update_fields: update_fields is None or isinstance(update_fields, list),
         "Update fields must be None or list",
     )
     @ensure(lambda result: isinstance(result, BacklogItem), "Must return BacklogItem")

{specfact_cli-0.26.0 → specfact_cli-0.26.1}/src/specfact_cli/commands/backlog_commands.py

@@ -97,6 +97,35 @@ def _apply_filters(
     return filtered
 
 
+def _extract_openspec_change_id(body: str) -> str | None:
+    """
+    Extract OpenSpec change proposal ID from issue body.
+
+    Looks for patterns like:
+    - *OpenSpec Change Proposal: `id`*
+    - OpenSpec Change Proposal: `id`
+    - OpenSpec.*proposal: `id`
+
+    Args:
+        body: Issue body text
+
+    Returns:
+        Change proposal ID if found, None otherwise
+    """
+    import re
+
+    openspec_patterns = [
+        r"OpenSpec Change Proposal[:\s]+`?([a-z0-9-]+)`?",
+        r"\*OpenSpec Change Proposal:\s*`([a-z0-9-]+)`",
+        r"OpenSpec.*proposal[:\s]+`?([a-z0-9-]+)`?",
+    ]
+    for pattern in openspec_patterns:
+        match = re.search(pattern, body, re.IGNORECASE)
+        if match:
+            return match.group(1)
+    return None
+
+
 def _build_adapter_kwargs(
     adapter: str,
     repo_owner: str | None = None,
@@ -623,8 +652,12 @@ def refine(
 
                             # Add OpenSpec comment if requested
                             if openspec_comment:
+                                # Extract OpenSpec change proposal ID from original body if present
+                                original_body = item.body_markdown or ""
+                                openspec_change_id = _extract_openspec_change_id(original_body)
+
                                 # Generate OpenSpec change proposal reference
-                                change_id = f"backlog-refine-{item.id}"
+                                change_id = openspec_change_id or f"backlog-refine-{item.id}"
                                 comment_text = (
                                     f"## OpenSpec Change Proposal Reference\n\n"
                                     f"This backlog item was refined using SpecFact CLI template-driven refinement.\n\n"
@@ -671,8 +704,12 @@ def refine(
 
                                 # Add OpenSpec comment if requested
                                 if openspec_comment:
+                                    # Extract OpenSpec change proposal ID from original body if present
+                                    original_body = item.body_markdown or ""
+                                    openspec_change_id = _extract_openspec_change_id(original_body)
+
                                     # Generate OpenSpec change proposal reference
-                                    change_id = f"backlog-refine-{item.id}"
+                                    change_id = openspec_change_id or f"backlog-refine-{item.id}"
                                     comment_text = (
                                         f"## OpenSpec Change Proposal Reference\n\n"
                                         f"This backlog item was refined using SpecFact CLI template-driven refinement.\n\n"

{specfact_cli-0.26.0 → specfact_cli-0.26.1}/src/specfact_cli/sync/bridge_sync.py

@@ -1912,6 +1912,26 @@ class BridgeSync:
                 "source_tracking": entries,
             }
 
+            # Extract source state from backlog entries (for cross-adapter sync state preservation)
+            # Check for source backlog entry from a different adapter (generic approach)
+            source_state = None
+            source_type = None
+            for entry in entries:
+                if isinstance(entry, dict):
+                    entry_type = entry.get("source_type", "").lower()
+                    # Look for entry from a different adapter (not the target adapter)
+                    if entry_type and entry_type != adapter_type.lower():
+                        source_metadata = entry.get("source_metadata", {})
+                        entry_source_state = source_metadata.get("source_state")
+                        if entry_source_state:
+                            source_state = entry_source_state
+                            source_type = entry_type
+                            break
+
+            if source_state and source_type:
+                proposal_dict["source_state"] = source_state
+                proposal_dict["source_type"] = source_type
+
             if isinstance(proposal.source_tracking.source_metadata, dict):
                 raw_title = proposal.source_tracking.source_metadata.get("raw_title")
                 raw_body = proposal.source_tracking.source_metadata.get("raw_body")