specfact-cli 0.26.13__tar.gz → 0.26.15__tar.gz

{specfact_cli-0.26.13 → specfact_cli-0.26.15}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specfact-cli
-Version: 0.26.13
+Version: 0.26.15
 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,7 +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`. See [Debug Logging](docs/reference/debug-logging.md).
+- 🔍 **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.13 → specfact_cli-0.26.15}/README.md

@@ -339,7 +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`. See [Debug Logging](docs/reference/debug-logging.md).
+- 🔍 **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.13 → specfact_cli-0.26.15}/pyproject.toml

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

@@ -69,6 +69,8 @@ Refine backlog items from DevOps tools (GitHub Issues, Azure DevOps, etc.) into
   - Ambiguous name-only matches will prompt for explicit iteration path
 - `--release RELEASE` - Filter by release identifier (case-insensitive)
 - `--limit N` - Maximum number of items to process in this refinement session (caps batch size)
+- `--ignore-refined` / `--no-ignore-refined` - When set (default), exclude already-refined items so `--limit` applies to items that need refinement. Use `--no-ignore-refined` to process the first N items in order.
+- `--id ISSUE_ID` - Refine only this backlog item (issue or work item ID). Other items are ignored.
 - `--persona PERSONA` - Filter templates by persona (product-owner, architect, developer)
 - `--framework FRAMEWORK` - Filter templates by framework (agile, scrum, safe, kanban)
 
@@ -162,6 +164,30 @@ specfact backlog refine $ADAPTER \
    - Use `:quit` or `:abort` to cancel the entire session gracefully
    - Session cancellation shows summary and exits without error
 
+### Interactive refinement (Copilot mode)
+
+When refining backlog items in Copilot mode (e.g. after export to tmp or during a refinement session), follow this **per-story loop** so the PO and stakeholders can review and approve before any update:
+
+1. **For each story** (one at a time):
+   - **Present** the refined story in a clear, readable format:
+     - Use headings for Title, Body, Acceptance Criteria, Metrics.
+     - Use tables or panels for structured data so it is easy to scan.
+   - **Assess specification level** so the DevOps team knows if the story is ready, under-specified, or over-specified:
+     - **Under-specified**: Missing acceptance criteria, vague scope, unclear "so that" or user value. List evidence (e.g. "No AC", "Scope could mean X or Y"). Suggest what to add.
+     - **Over-specified**: Too much implementation detail, too many sub-steps for one story, or solution prescribed instead of outcome. List evidence and suggest what to trim or split.
+     - **Fit for scope and intent**: Clear persona, capability, benefit, and testable AC; appropriate size. State briefly why it is ready (and, if DoR is in use, that DoR is satisfied).
+   - **List ambiguities** or open questions (e.g. unclear scope, missing acceptance criteria, conflicting assumptions).
+   - **Ask** the PO and other stakeholders for clarification: "Please review the refined story above. Do you want any changes? Any ambiguities to resolve? Should this story be split?"
+   - **If the user provides feedback**: Re-refine the story incorporating the feedback, then repeat from "Present" for this story.
+   - **Only when the user explicitly approves** (e.g. "looks good", "approved", "no changes"): Mark this story as done and move to the **next** story.
+   - **Do not update** the backlog item (or write to the refined file as final) until the user has approved this story.
+
+2. **Formatting**:
+   - Use clear headings, bullet lists, and optional tables/panels so refinement sessions are easy to follow and enjoyable.
+   - Keep each story’s block self-contained so stakeholders can focus on one item at a time.
+
+3. **Rule**: The backlog item (or exported block) must only be updated/finalized **after** the user has approved the refined content for that story. Then proceed to the next story with the same process.
+
 ### Step 3: Present Results
 
 Display refinement results:

{specfact_cli-0.26.13 → specfact_cli-0.26.15}/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.13"
+__version__ = "0.26.15"

{specfact_cli-0.26.13 → specfact_cli-0.26.15}/src/specfact_cli/__init__.py

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

{specfact_cli-0.26.13 → specfact_cli-0.26.15}/src/specfact_cli/adapters/ado.py

@@ -11,8 +11,7 @@ This follows the backlog adapter patterns established by the GitHub adapter.
 from __future__ import annotations
 
 import os
-
-# import re
+import re
 from datetime import UTC, datetime
 from pathlib import Path
 from typing import Any
@@ -28,6 +27,7 @@ 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
@@ -36,9 +36,68 @@ 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.
@@ -1642,10 +1701,10 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
                 "state": ado_state,
             }
         except requests.RequestException as e:
-            if is_debug_mode():
-                debug_log_operation("ado_patch", url, "error", error=str(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(
@@ -1744,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(
@@ -1876,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
@@ -1983,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
@@ -2361,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
@@ -3200,7 +3265,8 @@ 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 400/422: often caused by /multilineFieldsFormat/ not being supported by ADO API
+            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 = ""
@@ -3221,14 +3287,12 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
                         resp.raise_for_status()
                         response = resp
                     except requests.HTTPError as retry_error:
-                        # Retry with operations_no_format failed; continue to next fallback strategy.
-                        if is_debug_mode():
-                            debug_log_operation(
-                                "ado_patch",
-                                url,
-                                "failed",
-                                error=str(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()
@@ -3280,9 +3344,11 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
                         resp.raise_for_status()
                         response = resp
                     except requests.HTTPError:
+                        console.print(f"[bold red]✗[/bold red] {user_msg}")
                         raise
 
             if response is None:
+                console.print(f"[bold red]✗[/bold red] {user_msg}")
                 raise
 
         updated_work_item = response.json()

{specfact_cli-0.26.13 → specfact_cli-0.26.15}/src/specfact_cli/cli.py

@@ -454,6 +454,7 @@ def cli_main() -> None:
         console.print()  # Empty line after banner
     elif not is_help_or_version and not is_test_mode:
         # Show simple version line like other CLIs (skip for help/version commands and in test mode)
+        # Printed before startup checks so users see output immediately (important with slow checks e.g. xagt)
         print_version_line()
 
     # Run startup checks (template validation and version check)

{specfact_cli-0.26.13 → specfact_cli-0.26.15}/src/specfact_cli/commands/backlog_commands.py

@@ -16,6 +16,7 @@ from __future__ import annotations
 import os
 import re
 import sys
+import tempfile
 from datetime import datetime
 from pathlib import Path
 from typing import Any
@@ -295,6 +296,44 @@ def _parse_refined_export_markdown(content: str) -> dict[str, dict[str, Any]]:
     return result
 
 
+@beartype
+def _item_needs_refinement(
+    item: BacklogItem,
+    detector: TemplateDetector,
+    registry: TemplateRegistry,
+    template_id: str | None,
+    normalized_adapter: str | None,
+    normalized_framework: str | None,
+    normalized_persona: str | None,
+) -> bool:
+    """
+    Return True if the item needs refinement (should be processed); False if already refined (skip).
+
+    Mirrors the "already refined" skip logic used in the refine loop: checkboxes + all required
+    sections, or high confidence with no missing fields.
+    """
+    detection_result = detector.detect_template(
+        item,
+        provider=normalized_adapter,
+        framework=normalized_framework,
+        persona=normalized_persona,
+    )
+    if detection_result.template_id:
+        target = registry.get_template(detection_result.template_id) if detection_result.template_id else None
+        if target and target.required_sections:
+            has_checkboxes = bool(
+                re.search(r"^[\s]*- \[[ x]\]", item.body_markdown or "", re.MULTILINE | re.IGNORECASE)
+            )
+            all_present = all(
+                bool(re.search(rf"^#+\s+{re.escape(s)}\s*$", item.body_markdown or "", re.MULTILINE | re.IGNORECASE))
+                for s in target.required_sections
+            )
+            if has_checkboxes and all_present and not detection_result.missing_fields:
+                return False
+    already_refined = template_id is None and detection_result.confidence >= 0.8 and not detection_result.missing_fields
+    return not already_refined
+
+
 def _fetch_backlog_items(
     adapter_name: str,
     search_query: str | None = None,
@@ -423,6 +462,16 @@ def refine(
         "--limit",
         help="Maximum number of items to process in this refinement session. Use to cap batch size and avoid processing too many items at once.",
     ),
+    ignore_refined: bool = typer.Option(
+        True,
+        "--ignore-refined/--no-ignore-refined",
+        help="When set (default), exclude already-refined items from the batch so --limit applies to items that need refinement. Use --no-ignore-refined to process the first N items in order (already-refined skipped in loop).",
+    ),
+    issue_id: str | None = typer.Option(
+        None,
+        "--id",
+        help="Refine only this backlog item (issue or work item ID). Other items are ignored.",
+    ),
     template_id: str | None = typer.Option(None, "--template", "-t", help="Target template ID (default: auto-detect)"),
     auto_accept_high_confidence: bool = typer.Option(
         False, "--auto-accept-high-confidence", help="Auto-accept refinements with confidence >= 0.85"
@@ -445,12 +494,12 @@ def refine(
     export_to_tmp: bool = typer.Option(
         False,
         "--export-to-tmp",
-        help="Export backlog items to temporary file for copilot processing (default: /tmp/specfact-backlog-refine-<timestamp>.md)",
+        help="Export backlog items to temporary file for copilot processing (default: <system-temp>/specfact-backlog-refine-<timestamp>.md)",
     ),
     import_from_tmp: bool = typer.Option(
         False,
         "--import-from-tmp",
-        help="Import refined content from temporary file after copilot processing (default: /tmp/specfact-backlog-refine-<timestamp>-refined.md)",
+        help="Import refined content from temporary file after copilot processing (default: <system-temp>/specfact-backlog-refine-<timestamp>-refined.md)",
     ),
     tmp_file: Path | None = typer.Option(
         None,
@@ -650,6 +699,10 @@ def refine(
                 init_progress.update(validate_task, description="[green]✓[/green] Configuration validated")
 
         # Fetch backlog items with filters
+        # When ignore_refined and limit are set, fetch more candidates so we have enough after filtering
+        fetch_limit: int | None = limit
+        if ignore_refined and limit is not None and limit > 0:
+            fetch_limit = limit * 5
         with Progress(
             SpinnerColumn(),
             TextColumn("[progress.description]{task.description}"),
@@ -667,7 +720,7 @@ def refine(
                 iteration=iteration,
                 sprint=sprint,
                 release=release,
-                limit=limit,
+                limit=fetch_limit,
                 repo_owner=repo_owner,
                 repo_name=repo_name,
                 github_token=github_token,
@@ -705,6 +758,34 @@ def refine(
                 console.print("[yellow]No backlog items found.[/yellow]")
             return
 
+        # Filter by issue ID when --id is set
+        if issue_id is not None:
+            items = [i for i in items if str(i.id) == str(issue_id)]
+            if not items:
+                console.print(
+                    f"[bold red]✗[/bold red] No backlog item with id {issue_id!r} found. "
+                    "Check filters and adapter configuration."
+                )
+                raise typer.Exit(1)
+
+        # When ignore_refined (default), keep only items that need refinement; then apply limit
+        if ignore_refined:
+            items = [
+                i
+                for i in items
+                if _item_needs_refinement(
+                    i, detector, registry, template_id, normalized_adapter, normalized_framework, normalized_persona
+                )
+            ]
+            if limit is not None and len(items) > limit:
+                items = items[:limit]
+            if ignore_refined and (limit is not None or issue_id is not None):
+                console.print(
+                    f"[dim]Filtered to {len(items)} item(s) needing refinement"
+                    + (f" (limit {limit})" if limit is not None else "")
+                    + "[/dim]"
+                )
+
         # Validate export/import flags
         if export_to_tmp and import_from_tmp:
             console.print("[bold red]✗[/bold red] --export-to-tmp and --import-from-tmp are mutually exclusive")
@@ -713,7 +794,7 @@ def refine(
         # Handle export mode
         if export_to_tmp:
             timestamp = datetime.now().strftime("%Y%m%d-%H%M%S")
-            export_file = tmp_file or Path(f"/tmp/specfact-backlog-refine-{timestamp}.md")
+            export_file = tmp_file or (Path(tempfile.gettempdir()) / f"specfact-backlog-refine-{timestamp}.md")
 
             console.print(f"[bold cyan]Exporting {len(items)} backlog item(s) to: {export_file}[/bold cyan]")
 
@@ -764,7 +845,7 @@ def refine(
         # Handle import mode
         if import_from_tmp:
             timestamp = datetime.now().strftime("%Y%m%d-%H%M%S")
-            import_file = tmp_file or Path(f"/tmp/specfact-backlog-refine-{timestamp}-refined.md")
+            import_file = tmp_file or (Path(tempfile.gettempdir()) / f"specfact-backlog-refine-{timestamp}-refined.md")
 
             if not import_file.exists():
                 console.print(f"[bold red]✗[/bold red] Import file not found: {import_file}")
@@ -842,8 +923,8 @@ def refine(
             console.print(f"[green]✓ Updated {len(updated_items)} backlog item(s)[/green]")
             return
 
-        # Apply limit if specified
-        if limit and len(items) > limit:
+        # Apply limit if specified (when not ignore_refined; when ignore_refined we already filtered and sliced)
+        if not ignore_refined and limit is not None and len(items) > limit:
             items = items[:limit]
             console.print(f"[yellow]Limited to {limit} items (found {len(items)} total)[/yellow]")
         else:

{specfact_cli-0.26.13 → specfact_cli-0.26.15}/src/specfact_cli/commands/sync.py

@@ -1099,19 +1099,19 @@ def sync_bridge(
     export_to_tmp: bool = typer.Option(
         False,
         "--export-to-tmp",
-        help="Export proposal content to temporary file for LLM review (default: /tmp/specfact-proposal-<change-id>.md).",
+        help="Export proposal content to temporary file for LLM review (default: <system-temp>/specfact-proposal-<change-id>.md).",
         hidden=True,
     ),
     import_from_tmp: bool = typer.Option(
         False,
         "--import-from-tmp",
-        help="Import sanitized content from temporary file after LLM review (default: /tmp/specfact-proposal-<change-id>-sanitized.md).",
+        help="Import sanitized content from temporary file after LLM review (default: <system-temp>/specfact-proposal-<change-id>-sanitized.md).",
         hidden=True,
     ),
     tmp_file: Path | None = typer.Option(
         None,
         "--tmp-file",
-        help="Custom temporary file path (default: /tmp/specfact-proposal-<change-id>.md).",
+        help="Custom temporary file path (default: <system-temp>/specfact-proposal-<change-id>.md).",
         hidden=True,
     ),
     update_existing: bool = typer.Option(

{specfact_cli-0.26.13 → specfact_cli-0.26.15}/src/specfact_cli/sync/bridge_sync.py

@@ -12,6 +12,7 @@ from __future__ import annotations
 import hashlib
 import re
 import subprocess
+import tempfile
 from dataclasses import dataclass
 from urllib.parse import urlparse
 
@@ -557,7 +558,7 @@ class BridgeSync:
             change_ids: Optional list of change proposal IDs to filter. If None, exports all active proposals.
             export_to_tmp: If True, export proposal content to temporary file for LLM review.
             import_from_tmp: If True, import sanitized content from temporary file after LLM review.
-            tmp_file: Optional custom temporary file path. Default: `/tmp/specfact-proposal-<change-id>.md`.
+            tmp_file: Optional custom temporary file path. Default: <system-temp>/specfact-proposal-<change-id>.md.
 
         Returns:
             SyncResult with operation details
@@ -904,7 +905,7 @@ class BridgeSync:
                     # Handle temporary file workflow if requested
                     if export_to_tmp:
                         # Export proposal content to temporary file for LLM review
-                        tmp_file_path = tmp_file or Path(f"/tmp/specfact-proposal-{change_id}.md")
+                        tmp_file_path = tmp_file or (Path(tempfile.gettempdir()) / f"specfact-proposal-{change_id}.md")
                         try:
                             # Create markdown content from proposal
                             proposal_content = self._format_proposal_for_export(proposal)
@@ -919,7 +920,9 @@ class BridgeSync:
 
                     if import_from_tmp:
                         # Import sanitized content from temporary file
-                        sanitized_file_path = tmp_file or Path(f"/tmp/specfact-proposal-{change_id}-sanitized.md")
+                        sanitized_file_path = tmp_file or (
+                            Path(tempfile.gettempdir()) / f"specfact-proposal-{change_id}-sanitized.md"
+                        )
                         try:
                             if not sanitized_file_path.exists():
                                 errors.append(
@@ -933,7 +936,7 @@ class BridgeSync:
                             proposal_to_export = self._parse_sanitized_proposal(sanitized_content, proposal)
                             # Cleanup temporary files after import
                             try:
-                                original_tmp = Path(f"/tmp/specfact-proposal-{change_id}.md")
+                                original_tmp = Path(tempfile.gettempdir()) / f"specfact-proposal-{change_id}.md"
                                 if original_tmp.exists():
                                     original_tmp.unlink()
                                 if sanitized_file_path.exists():
@@ -2504,7 +2507,7 @@ class BridgeSync:
         # Handle sanitized content updates (when import_from_tmp is used)
         if import_from_tmp:
             change_id = proposal.get("change_id", "unknown")
-            sanitized_file = tmp_file or Path(f"/tmp/specfact-proposal-{change_id}-sanitized.md")
+            sanitized_file = tmp_file or (Path(tempfile.gettempdir()) / f"specfact-proposal-{change_id}-sanitized.md")
             if sanitized_file.exists():
                 sanitized_content = sanitized_file.read_text(encoding="utf-8")
                 proposal_for_hash = {
@@ -2603,7 +2606,9 @@ class BridgeSync:
             try:
                 if import_from_tmp:
                     change_id = proposal.get("change_id", "unknown")
-                    sanitized_file = tmp_file or Path(f"/tmp/specfact-proposal-{change_id}-sanitized.md")
+                    sanitized_file = tmp_file or (
+                        Path(tempfile.gettempdir()) / f"specfact-proposal-{change_id}-sanitized.md"
+                    )
                     if sanitized_file.exists():
                         sanitized_content = sanitized_file.read_text(encoding="utf-8")
                         proposal_for_update = {