specfact-cli 0.4.2__py3-none-any.whl → 0.6.8__py3-none-any.whl

specfact_cli/commands/sync.py

@@ -7,136 +7,66 @@ repository changes, and SpecFact plans.
 
 from __future__ import annotations
 
+import os
 import shutil
 from pathlib import Path
 from typing import Any
 
 import typer
+from beartype import beartype
+from icontract import ensure, require
 from rich.console import Console
 from rich.progress import Progress, SpinnerColumn, TextColumn
 
-from specfact_cli.models.plan import PlanBundle
+from specfact_cli.models.plan import Feature, PlanBundle
 from specfact_cli.sync.speckit_sync import SpecKitSync
+from specfact_cli.telemetry import telemetry
 
 
 app = typer.Typer(help="Synchronize Spec-Kit artifacts and repository changes")
 console = Console()
 
 
-def _sync_speckit_to_specfact(repo: Path, converter: Any, scanner: Any, progress: Any) -> tuple[PlanBundle, int, int]:
-    """
-    Sync Spec-Kit artifacts to SpecFact format.
-
-    Returns:
-        Tuple of (merged_bundle, features_updated, features_added)
-    """
-    from specfact_cli.generators.plan_generator import PlanGenerator
-    from specfact_cli.utils.structure import SpecFactStructure
-    from specfact_cli.validators.schema import validate_plan_bundle
-
-    plan_path = repo / SpecFactStructure.DEFAULT_PLAN
-    existing_bundle: PlanBundle | None = None
-
-    if plan_path.exists():
-        validation_result = validate_plan_bundle(plan_path)
-        if isinstance(validation_result, tuple):
-            is_valid, _error, bundle = validation_result
-            if is_valid and bundle:
-                existing_bundle = bundle
-
-    # Convert Spec-Kit to SpecFact
-    converted_bundle = converter.convert_plan(None if not existing_bundle else plan_path)
-
-    # Merge with existing plan if it exists
-    features_updated = 0
-    features_added = 0
-
-    if existing_bundle:
-        feature_keys_existing = {f.key for f in existing_bundle.features}
-
-        for feature in converted_bundle.features:
-            if feature.key in feature_keys_existing:
-                existing_idx = next(i for i, f in enumerate(existing_bundle.features) if f.key == feature.key)
-                existing_bundle.features[existing_idx] = feature
-                features_updated += 1
-            else:
-                existing_bundle.features.append(feature)
-                features_added += 1
-
-        # Update product themes
-        themes_existing = set(existing_bundle.product.themes)
-        themes_new = set(converted_bundle.product.themes)
-        existing_bundle.product.themes = list(themes_existing | themes_new)
-
-        # Write merged bundle
-        generator = PlanGenerator()
-        generator.generate(existing_bundle, plan_path)
-        return existing_bundle, features_updated, features_added
-    # Write new bundle
-    generator = PlanGenerator()
-    generator.generate(converted_bundle, plan_path)
-    return converted_bundle, 0, len(converted_bundle.features)
-
-
-@app.command("spec-kit")
-def sync_spec_kit(
-    repo: Path = typer.Option(
-        Path("."),
-        "--repo",
-        help="Path to repository",
-        exists=True,
-        file_okay=False,
-        dir_okay=True,
-    ),
-    bidirectional: bool = typer.Option(
-        False,
-        "--bidirectional",
-        help="Enable bidirectional sync (Spec-Kit ↔ SpecFact)",
-    ),
-    plan: Path | None = typer.Option(
-        None,
-        "--plan",
-        help="Path to SpecFact plan bundle for SpecFact → Spec-Kit conversion (default: .specfact/plans/main.bundle.yaml)",
-    ),
-    overwrite: bool = typer.Option(
-        False,
-        "--overwrite",
-        help="Overwrite existing Spec-Kit artifacts (delete all existing before sync)",
-    ),
-    watch: bool = typer.Option(
-        False,
-        "--watch",
-        help="Watch mode for continuous sync",
-    ),
-    interval: int = typer.Option(
-        5,
-        "--interval",
-        help="Watch interval in seconds (default: 5)",
-        min=1,
-    ),
+def _is_test_mode() -> bool:
+    """Check if running in test mode."""
+    # Check for TEST_MODE environment variable
+    if os.environ.get("TEST_MODE") == "true":
+        return True
+    # Check if running under pytest (common patterns)
+    import sys
+
+    return any("pytest" in arg or "test" in arg.lower() for arg in sys.argv) or "pytest" in sys.modules
+
+
+@beartype
+@require(lambda repo: repo.exists(), "Repository path must exist")
+@require(lambda repo: repo.is_dir(), "Repository path must be a directory")
+@require(lambda bidirectional: isinstance(bidirectional, bool), "Bidirectional must be bool")
+@require(lambda plan: plan is None or isinstance(plan, Path), "Plan must be None or Path")
+@require(lambda overwrite: isinstance(overwrite, bool), "Overwrite must be bool")
+@ensure(lambda result: result is None, "Must return None")
+def _perform_sync_operation(
+    repo: Path,
+    bidirectional: bool,
+    plan: Path | None,
+    overwrite: bool,
 ) -> None:
     """
-    Sync changes between Spec-Kit artifacts and SpecFact.
+    Perform sync operation without watch mode.
 
-    Synchronizes markdown artifacts generated by Spec-Kit slash commands
-    with SpecFact plan bundles and protocols.
+    This is extracted to avoid recursion when called from watch mode callback.
 
-    Example:
-        specfact sync spec-kit --repo . --bidirectional
+    Args:
+        repo: Path to repository
+        bidirectional: Enable bidirectional sync
+        plan: Path to SpecFact plan bundle
+        overwrite: Overwrite existing Spec-Kit artifacts
     """
     from specfact_cli.importers.speckit_converter import SpecKitConverter
     from specfact_cli.importers.speckit_scanner import SpecKitScanner
     from specfact_cli.utils.structure import SpecFactStructure
     from specfact_cli.validators.schema import validate_plan_bundle
 
-    console.print(f"[bold cyan]Syncing Spec-Kit artifacts from:[/bold cyan] {repo}")
-
-    # Watch mode (not implemented yet)
-    if watch:
-        console.print("[yellow]→ Watch mode enabled (not implemented yet)[/yellow]")
-        console.print(f"[dim]Would watch for changes every {interval} seconds[/dim]")
-        raise typer.Exit(0)
-
     # Step 1: Detect Spec-Kit repository
     scanner = SpecKitScanner(repo)
     if not scanner.is_speckit_repo():
@@ -146,6 +76,64 @@ def sync_spec_kit(
 
     console.print("[bold green]✓[/bold green] Detected Spec-Kit repository")
 
+    # Step 1.5: Validate constitution exists and is not empty
+    has_constitution, constitution_error = scanner.has_constitution()
+    if not has_constitution:
+        console.print("[bold red]✗[/bold red] Constitution required")
+        console.print(f"[red]{constitution_error}[/red]")
+        console.print("\n[bold yellow]Next Steps:[/bold yellow]")
+        console.print("1. Run 'specfact constitution bootstrap --repo .' to auto-generate constitution")
+        console.print("2. Or run '/speckit.constitution' command in your AI assistant")
+        console.print("3. Then run 'specfact sync spec-kit' again")
+        raise typer.Exit(1)
+
+    # Check if constitution is minimal and suggest bootstrap
+    constitution_path = repo / ".specify" / "memory" / "constitution.md"
+    if constitution_path.exists():
+        from specfact_cli.commands.constitution import is_constitution_minimal
+
+        if is_constitution_minimal(constitution_path):
+            # Auto-generate in test mode, prompt in interactive mode
+            # Check for test environment (TEST_MODE or PYTEST_CURRENT_TEST)
+            is_test_env = os.environ.get("TEST_MODE") == "true" or os.environ.get("PYTEST_CURRENT_TEST") is not None
+            if is_test_env:
+                # Auto-generate bootstrap constitution in test mode
+                from specfact_cli.enrichers.constitution_enricher import ConstitutionEnricher
+
+                enricher = ConstitutionEnricher()
+                enriched_content = enricher.bootstrap(repo, constitution_path)
+                constitution_path.write_text(enriched_content, encoding="utf-8")
+            else:
+                # Check if we're in an interactive environment
+                import sys
+
+                is_interactive = (hasattr(sys.stdin, "isatty") and sys.stdin.isatty()) and sys.stdin.isatty()
+                if is_interactive:
+                    console.print("[yellow]⚠[/yellow] Constitution is minimal (essentially empty)")
+                    suggest_bootstrap = typer.confirm(
+                        "Generate bootstrap constitution from repository analysis?",
+                        default=True,
+                    )
+                    if suggest_bootstrap:
+                        from specfact_cli.enrichers.constitution_enricher import ConstitutionEnricher
+
+                        console.print("[dim]Generating bootstrap constitution...[/dim]")
+                        enricher = ConstitutionEnricher()
+                        enriched_content = enricher.bootstrap(repo, constitution_path)
+                        constitution_path.write_text(enriched_content, encoding="utf-8")
+                        console.print("[bold green]✓[/bold green] Bootstrap constitution generated")
+                        console.print("[dim]Review and adjust as needed before syncing[/dim]")
+                    else:
+                        console.print(
+                            "[dim]Skipping bootstrap. Run 'specfact constitution bootstrap' manually if needed[/dim]"
+                        )
+                else:
+                    # Non-interactive mode: skip prompt
+                    console.print("[yellow]⚠[/yellow] Constitution is minimal (essentially empty)")
+                    console.print("[dim]Run 'specfact constitution bootstrap --repo .' to generate constitution[/dim]")
+
+    console.print("[bold green]✓[/bold green] Constitution found and validated")
+
     # Step 2: Detect SpecFact structure
     specfact_exists = (repo / SpecFactStructure.ROOT).exists()
 
@@ -168,10 +156,28 @@ def sync_spec_kit(
         console=console,
     ) as progress:
         # Step 3: Scan Spec-Kit artifacts
-        task = progress.add_task("[cyan]📦[/cyan] Scanning Spec-Kit artifacts...", total=None)
+        task = progress.add_task("[cyan]Scanning Spec-Kit artifacts...[/cyan]", total=None)
+        # Keep description showing current activity (spinner will show automatically)
+        progress.update(task, description="[cyan]Scanning Spec-Kit artifacts...[/cyan]")
         features = scanner.discover_features()
+        # Update with final status after completion
         progress.update(task, description=f"[green]✓[/green] Found {len(features)} features in specs/")
 
+        # Step 3.5: Validate Spec-Kit artifacts for unidirectional sync
+        if not bidirectional and len(features) == 0:
+            console.print("[bold red]✗[/bold red] No Spec-Kit features found")
+            console.print(
+                "[red]Unidirectional sync (Spec-Kit → SpecFact) requires at least one feature specification.[/red]"
+            )
+            console.print("\n[bold yellow]Next Steps:[/bold yellow]")
+            console.print("1. Run '/speckit.specify' command in your AI assistant to create feature specifications")
+            console.print("2. Optionally run '/speckit.plan' and '/speckit.tasks' to create complete artifacts")
+            console.print("3. Then run 'specfact sync spec-kit' again")
+            console.print(
+                "\n[dim]Note: For bidirectional sync, Spec-Kit artifacts are optional if syncing from SpecFact → Spec-Kit[/dim]"
+            )
+            raise typer.Exit(1)
+
         # Step 4: Sync based on mode
         specfact_changes: dict[str, Any] = {}
         conflicts: list[dict[str, Any]] = []
@@ -180,10 +186,55 @@ def sync_spec_kit(
         if bidirectional:
             # Bidirectional sync: Spec-Kit → SpecFact and SpecFact → Spec-Kit
             # Step 5.1: Spec-Kit → SpecFact (unidirectional sync)
-            task = progress.add_task("[cyan]📝[/cyan] Converting Spec-Kit → SpecFact...", total=None)
-            merged_bundle, features_updated, features_added = _sync_speckit_to_specfact(
-                repo, converter, scanner, progress
-            )
+            # Skip expensive conversion if no Spec-Kit features found (optimization)
+            if len(features) == 0:
+                task = progress.add_task("[cyan]📝[/cyan] Converting Spec-Kit → SpecFact...", total=None)
+                progress.update(
+                    task,
+                    description="[green]✓[/green] Skipped (no Spec-Kit features found)",
+                )
+                console.print("[dim]  - Skipped Spec-Kit → SpecFact (no features in specs/)[/dim]")
+                # Use existing plan bundle if available, otherwise create minimal empty one
+                from specfact_cli.utils.structure import SpecFactStructure
+                from specfact_cli.validators.schema import validate_plan_bundle
+
+                # Use get_default_plan_path() to find the active plan (checks config or falls back to main.bundle.yaml)
+                plan_path = SpecFactStructure.get_default_plan_path(repo)
+                if plan_path.exists():
+                    # Show progress while loading plan bundle
+                    progress.update(task, description="[cyan]Parsing plan bundle YAML...[/cyan]")
+                    validation_result = validate_plan_bundle(plan_path)
+                    if isinstance(validation_result, tuple):
+                        is_valid, _error, bundle = validation_result
+                        if is_valid and bundle:
+                            # Show progress during validation (Pydantic validation can be slow for large bundles)
+                            progress.update(
+                                task, description=f"[cyan]Validating {len(bundle.features)} features...[/cyan]"
+                            )
+                            merged_bundle = bundle
+                            progress.update(
+                                task,
+                                description=f"[green]✓[/green] Loaded plan bundle ({len(bundle.features)} features)",
+                            )
+                        else:
+                            # Fallback: create minimal bundle via converter (but skip expensive parsing)
+                            progress.update(task, description="[cyan]Creating plan bundle from Spec-Kit...[/cyan]")
+                            merged_bundle = _sync_speckit_to_specfact(repo, converter, scanner, progress, task)[0]
+                    else:
+                        progress.update(task, description="[cyan]Creating plan bundle from Spec-Kit...[/cyan]")
+                        merged_bundle = _sync_speckit_to_specfact(repo, converter, scanner, progress, task)[0]
+                else:
+                    progress.update(task, description="[cyan]Creating plan bundle from Spec-Kit...[/cyan]")
+                    merged_bundle = _sync_speckit_to_specfact(repo, converter, scanner, progress, task)[0]
+                features_updated = 0
+                features_added = 0
+            else:
+                task = progress.add_task("[cyan]Converting Spec-Kit → SpecFact...[/cyan]", total=None)
+                # Show current activity (spinner will show automatically)
+                progress.update(task, description="[cyan]Converting Spec-Kit → SpecFact...[/cyan]")
+                merged_bundle, features_updated, features_added = _sync_speckit_to_specfact(
+                    repo, converter, scanner, progress
+                )
 
             if features_updated > 0 or features_added > 0:
                 progress.update(
@@ -199,55 +250,79 @@ def sync_spec_kit(
                 )
 
             # Step 5.2: SpecFact → Spec-Kit (reverse conversion)
-            task = progress.add_task("[cyan]🔄[/cyan] Converting SpecFact → Spec-Kit...", total=None)
+            task = progress.add_task("[cyan]Converting SpecFact → Spec-Kit...[/cyan]", total=None)
+            # Show current activity (spinner will show automatically)
+            progress.update(task, description="[cyan]Detecting SpecFact changes...[/cyan]")
 
-            # Detect SpecFact changes
+            # Detect SpecFact changes (for tracking/incremental sync, but don't block conversion)
             specfact_changes = sync.detect_specfact_changes(repo)
 
-            if specfact_changes:
-                # Load plan bundle and convert to Spec-Kit
-                # Use provided plan path, or default to main plan
+            # Use the merged_bundle we already loaded, or load it if not available
+            # We convert even if no "changes" detected, as long as plan bundle exists and has features
+            plan_bundle_to_convert: PlanBundle | None = None
+
+            # Prefer using merged_bundle if it has features (already loaded above)
+            if merged_bundle and len(merged_bundle.features) > 0:
+                plan_bundle_to_convert = merged_bundle
+            else:
+                # Fallback: load plan bundle from file if merged_bundle is empty or None
                 if plan:
                     plan_path = plan if plan.is_absolute() else repo / plan
                 else:
-                    plan_path = repo / SpecFactStructure.DEFAULT_PLAN
+                    # Use get_default_plan_path() to find the active plan (checks config or falls back to main.bundle.yaml)
+                    plan_path = SpecFactStructure.get_default_plan_path(repo)
 
                 if plan_path.exists():
+                    progress.update(task, description="[cyan]Loading plan bundle...[/cyan]")
                     validation_result = validate_plan_bundle(plan_path)
                     if isinstance(validation_result, tuple):
                         is_valid, _error, plan_bundle = validation_result
-                        if is_valid and plan_bundle:
-                            # Handle overwrite mode
-                            if overwrite:
-                                # Delete existing Spec-Kit artifacts before conversion
-                                specs_dir = repo / "specs"
-                                if specs_dir.exists():
-                                    console.print(
-                                        "[yellow]⚠[/yellow] Overwrite mode: Removing existing Spec-Kit artifacts..."
-                                    )
-                                    shutil.rmtree(specs_dir)
-                                    specs_dir.mkdir(parents=True, exist_ok=True)
-                                    console.print("[green]✓[/green] Existing artifacts removed")
+                        if is_valid and plan_bundle and len(plan_bundle.features) > 0:
+                            plan_bundle_to_convert = plan_bundle
+
+            # Convert if we have a plan bundle with features
+            if plan_bundle_to_convert and len(plan_bundle_to_convert.features) > 0:
+                # Handle overwrite mode
+                if overwrite:
+                    progress.update(task, description="[cyan]Removing existing artifacts...[/cyan]")
+                    # Delete existing Spec-Kit artifacts before conversion
+                    specs_dir = repo / "specs"
+                    if specs_dir.exists():
+                        console.print("[yellow]⚠[/yellow] Overwrite mode: Removing existing Spec-Kit artifacts...")
+                        shutil.rmtree(specs_dir)
+                        specs_dir.mkdir(parents=True, exist_ok=True)
+                        console.print("[green]✓[/green] Existing artifacts removed")
+
+                # Convert SpecFact plan bundle to Spec-Kit markdown
+                total_features = len(plan_bundle_to_convert.features)
+                progress.update(
+                    task,
+                    description=f"[cyan]Converting plan bundle to Spec-Kit format (0 of {total_features})...[/cyan]",
+                )
 
-                            # Convert SpecFact plan bundle to Spec-Kit markdown
-                            features_converted_speckit = converter.convert_to_speckit(plan_bundle)
-                            progress.update(
-                                task,
-                                description=f"[green]✓[/green] Converted {features_converted_speckit} features to Spec-Kit",
-                            )
-                            mode_text = "overwritten" if overwrite else "generated"
-                            console.print(
-                                f"[dim]  - {mode_text.capitalize()} spec.md, plan.md, tasks.md for {features_converted_speckit} features[/dim]"
-                            )
-                        else:
-                            progress.update(task, description="[yellow]⚠[/yellow] Plan bundle validation failed")
-                            console.print("[yellow]⚠[/yellow] Could not load plan bundle for conversion")
-                    else:
-                        progress.update(task, description="[yellow]⚠[/yellow] Plan bundle not found")
-                else:
-                    progress.update(task, description="[green]✓[/green] No SpecFact plan to sync")
+                # Progress callback to update during conversion
+                def update_progress(current: int, total: int) -> None:
+                    progress.update(
+                        task,
+                        description=f"[cyan]Converting plan bundle to Spec-Kit format ({current} of {total})...[/cyan]",
+                    )
+
+                features_converted_speckit = converter.convert_to_speckit(plan_bundle_to_convert, update_progress)
+                progress.update(
+                    task,
+                    description=f"[green]✓[/green] Converted {features_converted_speckit} features to Spec-Kit",
+                )
+                mode_text = "overwritten" if overwrite else "generated"
+                console.print(
+                    f"[dim]  - {mode_text.capitalize()} spec.md, plan.md, tasks.md for {features_converted_speckit} features[/dim]"
+                )
+                # Warning about Constitution Check gates
+                console.print(
+                    "[yellow]⚠[/yellow] [dim]Note: Constitution Check gates in plan.md are set to PENDING - review and check gates based on your project's actual state[/dim]"
+                )
             else:
-                progress.update(task, description="[green]✓[/green] No SpecFact changes to sync")
+                progress.update(task, description="[green]✓[/green] No features to convert to Spec-Kit")
+                features_converted_speckit = 0
 
             # Detect conflicts between both directions
             speckit_changes = sync.detect_speckit_changes(repo)
@@ -260,7 +335,9 @@ def sync_spec_kit(
                 console.print("[bold green]✓[/bold green] No conflicts detected")
         else:
             # Unidirectional sync: Spec-Kit → SpecFact
-            task = progress.add_task("[cyan]📝[/cyan] Converting to SpecFact format...", total=None)
+            task = progress.add_task("[cyan]Converting to SpecFact format...[/cyan]", total=None)
+            # Show current activity (spinner will show automatically)
+            progress.update(task, description="[cyan]Converting to SpecFact format...[/cyan]")
 
             merged_bundle, features_updated, features_added = _sync_speckit_to_specfact(
                 repo, converter, scanner, progress
@@ -294,16 +371,24 @@ def sync_spec_kit(
         if bidirectional:
             console.print("[bold cyan]Sync Summary (Bidirectional):[/bold cyan]")
             console.print(f"  - Spec-Kit → SpecFact: Updated {features_updated}, Added {features_added} features")
-            if specfact_changes:
+            # Always show conversion result (we convert if plan bundle exists, not just when changes detected)
+            if features_converted_speckit > 0:
                 console.print(
                     f"  - SpecFact → Spec-Kit: {features_converted_speckit} features converted to Spec-Kit markdown"
                 )
             else:
-                console.print("  - SpecFact → Spec-Kit: No changes detected")
+                console.print("  - SpecFact → Spec-Kit: No features to convert")
             if conflicts:
                 console.print(f"  - Conflicts: {len(conflicts)} detected and resolved")
             else:
                 console.print("  - Conflicts: None detected")
+
+            # Post-sync validation suggestion
+            if features_converted_speckit > 0:
+                console.print()
+                console.print("[bold cyan]Next Steps:[/bold cyan]")
+                console.print("  Run '/speckit.analyze' to validate artifact consistency and quality")
+                console.print("  This will check for ambiguities, duplications, and constitution alignment")
         else:
             console.print("[bold cyan]Sync Summary (Unidirectional):[/bold cyan]")
             if features:
@@ -313,10 +398,368 @@ def sync_spec_kit(
                 console.print(f"  - Added: {features_added} new features")
             console.print("  - Direction: Spec-Kit → SpecFact")
 
+            # Post-sync validation suggestion
+            console.print()
+            console.print("[bold cyan]Next Steps:[/bold cyan]")
+            console.print("  Run '/speckit.analyze' to validate artifact consistency and quality")
+            console.print("  This will check for ambiguities, duplications, and constitution alignment")
+
     console.print()
     console.print("[bold green]✓[/bold green] Sync complete!")
 
 
+def _sync_speckit_to_specfact(
+    repo: Path, converter: Any, scanner: Any, progress: Any, task: int | None = None
+) -> tuple[PlanBundle, int, int]:
+    """
+    Sync Spec-Kit artifacts to SpecFact format.
+
+    Args:
+        repo: Repository path
+        converter: SpecKitConverter instance
+        scanner: SpecKitScanner instance
+        progress: Rich Progress instance
+        task: Optional progress task ID to update
+
+    Returns:
+        Tuple of (merged_bundle, features_updated, features_added)
+    """
+    from specfact_cli.generators.plan_generator import PlanGenerator
+    from specfact_cli.utils.structure import SpecFactStructure
+    from specfact_cli.validators.schema import validate_plan_bundle
+
+    plan_path = SpecFactStructure.get_default_plan_path(repo)
+    existing_bundle: PlanBundle | None = None
+
+    if plan_path.exists():
+        if task is not None:
+            progress.update(task, description="[cyan]Validating existing plan bundle...[/cyan]")
+        validation_result = validate_plan_bundle(plan_path)
+        if isinstance(validation_result, tuple):
+            is_valid, _error, bundle = validation_result
+            if is_valid and bundle:
+                existing_bundle = bundle
+                # Deduplicate existing features by normalized key (clean up duplicates from previous syncs)
+                from specfact_cli.utils.feature_keys import normalize_feature_key
+
+                seen_normalized_keys: set[str] = set()
+                deduplicated_features: list[Feature] = []
+                for existing_feature in existing_bundle.features:
+                    normalized_key = normalize_feature_key(existing_feature.key)
+                    if normalized_key not in seen_normalized_keys:
+                        seen_normalized_keys.add(normalized_key)
+                        deduplicated_features.append(existing_feature)
+
+                duplicates_removed = len(existing_bundle.features) - len(deduplicated_features)
+                if duplicates_removed > 0:
+                    existing_bundle.features = deduplicated_features
+                    # Write back deduplicated bundle immediately to clean up the plan file
+                    from specfact_cli.generators.plan_generator import PlanGenerator
+
+                    if task is not None:
+                        progress.update(
+                            task,
+                            description=f"[cyan]Deduplicating {duplicates_removed} duplicate features and writing cleaned plan...[/cyan]",
+                        )
+                    generator = PlanGenerator()
+                    generator.generate(existing_bundle, plan_path)
+                    if task is not None:
+                        progress.update(
+                            task,
+                            description=f"[green]✓[/green] Removed {duplicates_removed} duplicates, cleaned plan saved",
+                        )
+
+    # Convert Spec-Kit to SpecFact
+    if task is not None:
+        progress.update(task, description="[cyan]Converting Spec-Kit artifacts to SpecFact format...[/cyan]")
+    converted_bundle = converter.convert_plan(None if not existing_bundle else plan_path)
+
+    # Merge with existing plan if it exists
+    features_updated = 0
+    features_added = 0
+
+    if existing_bundle:
+        if task is not None:
+            progress.update(task, description="[cyan]Merging with existing plan bundle...[/cyan]")
+        # Use normalized keys for matching to handle different key formats (e.g., FEATURE-001 vs 001_FEATURE_NAME)
+        from specfact_cli.utils.feature_keys import normalize_feature_key
+
+        # Build a map of normalized_key -> (index, original_key) for existing features
+        normalized_key_map: dict[str, tuple[int, str]] = {}
+        for idx, existing_feature in enumerate(existing_bundle.features):
+            normalized_key = normalize_feature_key(existing_feature.key)
+            # If multiple features have the same normalized key, keep the first one
+            if normalized_key not in normalized_key_map:
+                normalized_key_map[normalized_key] = (idx, existing_feature.key)
+
+        for feature in converted_bundle.features:
+            normalized_key = normalize_feature_key(feature.key)
+            matched = False
+
+            # Try exact match first
+            if normalized_key in normalized_key_map:
+                existing_idx, original_key = normalized_key_map[normalized_key]
+                # Preserve the original key format from existing bundle
+                feature.key = original_key
+                existing_bundle.features[existing_idx] = feature
+                features_updated += 1
+                matched = True
+            else:
+                # Try prefix match for abbreviated vs full names
+                # (e.g., IDEINTEGRATION vs IDEINTEGRATIONSYSTEM)
+                # Only match if shorter is a PREFIX of longer with significant length difference
+                # AND at least one key has a numbered prefix (041_, 042-, etc.) indicating Spec-Kit origin
+                # This avoids false positives like SMARTCOVERAGE vs SMARTCOVERAGEMANAGER (both from code analysis)
+                for existing_norm_key, (existing_idx, original_key) in normalized_key_map.items():
+                    shorter = min(normalized_key, existing_norm_key, key=len)
+                    longer = max(normalized_key, existing_norm_key, key=len)
+
+                    # Check if at least one key has a numbered prefix (Spec-Kit format)
+                    import re
+
+                    has_speckit_key = bool(
+                        re.match(r"^\d{3}[_-]", feature.key) or re.match(r"^\d{3}[_-]", original_key)
+                    )
+
+                    # More conservative matching:
+                    # 1. At least one key must have numbered prefix (Spec-Kit origin)
+                    # 2. Shorter must be at least 10 chars
+                    # 3. Longer must start with shorter (prefix match)
+                    # 4. Length difference must be at least 6 chars
+                    # 5. Shorter must be < 75% of longer (to ensure significant difference)
+                    length_diff = len(longer) - len(shorter)
+                    length_ratio = len(shorter) / len(longer) if len(longer) > 0 else 1.0
+
+                    if (
+                        has_speckit_key
+                        and len(shorter) >= 10
+                        and longer.startswith(shorter)
+                        and length_diff >= 6
+                        and length_ratio < 0.75
+                    ):
+                        # Match found - use the existing key format (prefer full name if available)
+                        if len(existing_norm_key) >= len(normalized_key):
+                            # Existing key is longer (full name) - keep it
+                            feature.key = original_key
+                        else:
+                            # New key is longer (full name) - use it but update existing
+                            existing_bundle.features[existing_idx].key = feature.key
+                        existing_bundle.features[existing_idx] = feature
+                        features_updated += 1
+                        matched = True
+                        break
+
+            if not matched:
+                # New feature - add it
+                existing_bundle.features.append(feature)
+                features_added += 1
+
+        # Update product themes
+        themes_existing = set(existing_bundle.product.themes)
+        themes_new = set(converted_bundle.product.themes)
+        existing_bundle.product.themes = list(themes_existing | themes_new)
+
+        # Write merged bundle
+        if task is not None:
+            progress.update(task, description="[cyan]Writing plan bundle to disk...[/cyan]")
+        generator = PlanGenerator()
+        generator.generate(existing_bundle, plan_path)
+        return existing_bundle, features_updated, features_added
+    # Write new bundle
+    generator = PlanGenerator()
+    generator.generate(converted_bundle, plan_path)
+    return converted_bundle, 0, len(converted_bundle.features)
+
+
+@app.command("spec-kit")
+def sync_spec_kit(
+    repo: Path = typer.Option(
+        Path("."),
+        "--repo",
+        help="Path to repository",
+        exists=True,
+        file_okay=False,
+        dir_okay=True,
+    ),
+    bidirectional: bool = typer.Option(
+        False,
+        "--bidirectional",
+        help="Enable bidirectional sync (Spec-Kit ↔ SpecFact)",
+    ),
+    plan: Path | None = typer.Option(
+        None,
+        "--plan",
+        help="Path to SpecFact plan bundle for SpecFact → Spec-Kit conversion (default: .specfact/plans/main.bundle.yaml)",
+    ),
+    overwrite: bool = typer.Option(
+        False,
+        "--overwrite",
+        help="Overwrite existing Spec-Kit artifacts (delete all existing before sync)",
+    ),
+    watch: bool = typer.Option(
+        False,
+        "--watch",
+        help="Watch mode for continuous sync",
+    ),
+    interval: int = typer.Option(
+        5,
+        "--interval",
+        help="Watch interval in seconds (default: 5)",
+        min=1,
+    ),
+    ensure_speckit_compliance: bool = typer.Option(
+        False,
+        "--ensure-speckit-compliance",
+        help="Validate and auto-enrich plan bundle for Spec-Kit compliance before sync (ensures technology stack, testable acceptance criteria, comprehensive scenarios)",
+    ),
+) -> None:
+    """
+    Sync changes between Spec-Kit artifacts and SpecFact.
+
+    Synchronizes markdown artifacts generated by Spec-Kit slash commands
+    with SpecFact plan bundles and protocols.
+
+    Example:
+        specfact sync spec-kit --repo . --bidirectional
+    """
+    telemetry_metadata = {
+        "bidirectional": bidirectional,
+        "watch": watch,
+        "overwrite": overwrite,
+        "interval": interval,
+    }
+
+    with telemetry.track_command("sync.spec_kit", telemetry_metadata) as record:
+        console.print(f"[bold cyan]Syncing Spec-Kit artifacts from:[/bold cyan] {repo}")
+
+        # Ensure Spec-Kit compliance if requested
+        if ensure_speckit_compliance:
+            console.print("\n[cyan]🔍 Validating plan bundle for Spec-Kit compliance...[/cyan]")
+            from specfact_cli.utils.structure import SpecFactStructure
+            from specfact_cli.validators.schema import validate_plan_bundle
+
+            # Use provided plan path or default
+            plan_path = plan if plan else SpecFactStructure.get_default_plan_path(repo)
+            if not plan_path.is_absolute():
+                plan_path = repo / plan_path
+
+            if plan_path.exists():
+                validation_result = validate_plan_bundle(plan_path)
+                if isinstance(validation_result, tuple):
+                    is_valid, _error, plan_bundle = validation_result
+                    if is_valid and plan_bundle:
+                        # Check for technology stack in constraints
+                        has_tech_stack = bool(
+                            plan_bundle.idea
+                            and plan_bundle.idea.constraints
+                            and any(
+                                "Python" in c or "framework" in c.lower() or "database" in c.lower()
+                                for c in plan_bundle.idea.constraints
+                            )
+                        )
+
+                        if not has_tech_stack:
+                            console.print("[yellow]⚠ Technology stack not found in constraints[/yellow]")
+                            console.print("[dim]Technology stack will be extracted from constraints during sync[/dim]")
+
+                        # Check for testable acceptance criteria
+                        features_with_non_testable = []
+                        for feature in plan_bundle.features:
+                            for story in feature.stories:
+                                testable_count = sum(
+                                    1
+                                    for acc in story.acceptance
+                                    if any(
+                                        keyword in acc.lower()
+                                        for keyword in ["must", "should", "verify", "validate", "ensure"]
+                                    )
+                                )
+                                if testable_count < len(story.acceptance) and len(story.acceptance) > 0:
+                                    features_with_non_testable.append((feature.key, story.key))
+
+                        if features_with_non_testable:
+                            console.print(
+                                f"[yellow]⚠ Found {len(features_with_non_testable)} stories with non-testable acceptance criteria[/yellow]"
+                            )
+                            console.print("[dim]Acceptance criteria will be enhanced during sync[/dim]")
+
+                        console.print("[green]✓ Plan bundle validation complete[/green]")
+                    else:
+                        console.print("[yellow]⚠ Plan bundle validation failed, but continuing with sync[/yellow]")
+                else:
+                    console.print("[yellow]⚠ Could not validate plan bundle, but continuing with sync[/yellow]")
+            else:
+                console.print("[yellow]⚠ Plan bundle not found, skipping compliance check[/yellow]")
+
+        # Resolve repo path to ensure it's absolute and valid (do this once at the start)
+        resolved_repo = repo.resolve()
+        if not resolved_repo.exists():
+            console.print(f"[red]Error:[/red] Repository path does not exist: {resolved_repo}")
+            raise typer.Exit(1)
+        if not resolved_repo.is_dir():
+            console.print(f"[red]Error:[/red] Repository path is not a directory: {resolved_repo}")
+            raise typer.Exit(1)
+
+        # Watch mode implementation
+        if watch:
+            from specfact_cli.sync.watcher import FileChange, SyncWatcher
+
+            console.print("[bold cyan]Watch mode enabled[/bold cyan]")
+            console.print(f"[dim]Watching for changes every {interval} seconds[/dim]\n")
+
+            @beartype
+            @require(lambda changes: isinstance(changes, list), "Changes must be a list")
+            @require(
+                lambda changes: all(hasattr(c, "change_type") for c in changes),
+                "All changes must have change_type attribute",
+            )
+            @ensure(lambda result: result is None, "Must return None")
+            def sync_callback(changes: list[FileChange]) -> None:
+                """Handle file changes and trigger sync."""
+                spec_kit_changes = [c for c in changes if c.change_type == "spec_kit"]
+                specfact_changes = [c for c in changes if c.change_type == "specfact"]
+
+                if spec_kit_changes or specfact_changes:
+                    console.print(f"[cyan]Detected {len(changes)} change(s), syncing...[/cyan]")
+                    # Perform one-time sync (bidirectional if enabled)
+                    try:
+                        # Re-validate resolved_repo before use (may have been cleaned up)
+                        if not resolved_repo.exists():
+                            console.print(f"[yellow]⚠[/yellow] Repository path no longer exists: {resolved_repo}\n")
+                            return
+                        if not resolved_repo.is_dir():
+                            console.print(
+                                f"[yellow]⚠[/yellow] Repository path is no longer a directory: {resolved_repo}\n"
+                            )
+                            return
+                        # Use resolved_repo from outer scope (already resolved and validated)
+                        _perform_sync_operation(
+                            repo=resolved_repo,
+                            bidirectional=bidirectional,
+                            plan=plan,
+                            overwrite=overwrite,
+                        )
+                        console.print("[green]✓[/green] Sync complete\n")
+                    except Exception as e:
+                        console.print(f"[red]✗[/red] Sync failed: {e}\n")
+
+            # Use resolved_repo for watcher (already resolved and validated)
+            watcher = SyncWatcher(resolved_repo, sync_callback, interval=interval)
+            watcher.watch()
+            record({"watch_mode": True})
+            return
+
+        # Perform sync operation (extracted to avoid recursion in watch mode)
+        # Use resolved_repo (already resolved and validated above)
+        _perform_sync_operation(
+            repo=resolved_repo,
+            bidirectional=bidirectional,
+            plan=plan,
+            overwrite=overwrite,
+        )
+        record({"sync_completed": True})
+
+
 @app.command("repository")
 def sync_repository(
     repo: Path = typer.Option(
@@ -362,47 +805,119 @@ def sync_repository(
     """
     from specfact_cli.sync.repository_sync import RepositorySync
 
-    console.print(f"[bold cyan]Syncing repository changes from:[/bold cyan] {repo}")
+    telemetry_metadata = {
+        "watch": watch,
+        "interval": interval,
+        "confidence": confidence,
+    }
 
-    if target is None:
-        target = repo / ".specfact"
+    with telemetry.track_command("sync.repository", telemetry_metadata) as record:
+        console.print(f"[bold cyan]Syncing repository changes from:[/bold cyan] {repo}")
 
-    sync = RepositorySync(repo, target, confidence_threshold=confidence)
+        # Resolve repo path to ensure it's absolute and valid (do this once at the start)
+        resolved_repo = repo.resolve()
+        if not resolved_repo.exists():
+            console.print(f"[red]Error:[/red] Repository path does not exist: {resolved_repo}")
+            raise typer.Exit(1)
+        if not resolved_repo.is_dir():
+            console.print(f"[red]Error:[/red] Repository path is not a directory: {resolved_repo}")
+            raise typer.Exit(1)
 
-    if watch:
-        console.print("[yellow]→ Watch mode enabled (not implemented yet)[/yellow]")
-        console.print(f"[dim]Would watch for changes every {interval} seconds[/dim]")
-        raise typer.Exit(0)
+        if target is None:
+            target = resolved_repo / ".specfact"
 
-    with Progress(
-        SpinnerColumn(),
-        TextColumn("[progress.description]{task.description}"),
-        console=console,
-    ) as progress:
-        # Step 1: Detect code changes
-        task = progress.add_task("Detecting code changes...", total=None)
-        result = sync.sync_repository_changes(repo)
-        progress.update(task, description=f"✓ Detected {len(result.code_changes)} code changes")
+        sync = RepositorySync(resolved_repo, target, confidence_threshold=confidence)
 
-        # Step 2: Show plan updates
-        if result.plan_updates:
-            task = progress.add_task("Updating plan artifacts...", total=None)
-            total_features = sum(update.get("features", 0) for update in result.plan_updates)
-            progress.update(task, description=f"✓ Updated plan artifacts ({total_features} features)")
+        if watch:
+            from specfact_cli.sync.watcher import FileChange, SyncWatcher
 
-        # Step 3: Show deviations
+            console.print("[bold cyan]Watch mode enabled[/bold cyan]")
+            console.print(f"[dim]Watching for changes every {interval} seconds[/dim]\n")
+
+            @beartype
+            @require(lambda changes: isinstance(changes, list), "Changes must be a list")
+            @require(
+                lambda changes: all(hasattr(c, "change_type") for c in changes),
+                "All changes must have change_type attribute",
+            )
+            @ensure(lambda result: result is None, "Must return None")
+            def sync_callback(changes: list[FileChange]) -> None:
+                """Handle file changes and trigger sync."""
+                code_changes = [c for c in changes if c.change_type == "code"]
+
+                if code_changes:
+                    console.print(f"[cyan]Detected {len(code_changes)} code change(s), syncing...[/cyan]")
+                    # Perform repository sync
+                    try:
+                        # Re-validate resolved_repo before use (may have been cleaned up)
+                        if not resolved_repo.exists():
+                            console.print(f"[yellow]⚠[/yellow] Repository path no longer exists: {resolved_repo}\n")
+                            return
+                        if not resolved_repo.is_dir():
+                            console.print(
+                                f"[yellow]⚠[/yellow] Repository path is no longer a directory: {resolved_repo}\n"
+                            )
+                            return
+                        # Use resolved_repo from outer scope (already resolved and validated)
+                        result = sync.sync_repository_changes(resolved_repo)
+                        if result.status == "success":
+                            console.print("[green]✓[/green] Repository sync complete\n")
+                        elif result.status == "deviation_detected":
+                            console.print(f"[yellow]⚠[/yellow] Deviations detected: {len(result.deviations)}\n")
+                        else:
+                            console.print(f"[red]✗[/red] Sync failed: {result.status}\n")
+                    except Exception as e:
+                        console.print(f"[red]✗[/red] Sync failed: {e}\n")
+
+            # Use resolved_repo for watcher (already resolved and validated)
+            watcher = SyncWatcher(resolved_repo, sync_callback, interval=interval)
+            watcher.watch()
+            record({"watch_mode": True})
+            return
+
+        # Use resolved_repo (already resolved and validated above)
+        # Disable Progress in test mode to avoid LiveError conflicts
+        if _is_test_mode():
+            # In test mode, just run the sync without Progress
+            result = sync.sync_repository_changes(resolved_repo)
+        else:
+            with Progress(
+                SpinnerColumn(),
+                TextColumn("[progress.description]{task.description}"),
+                console=console,
+            ) as progress:
+                # Step 1: Detect code changes
+                task = progress.add_task("Detecting code changes...", total=None)
+                result = sync.sync_repository_changes(resolved_repo)
+                progress.update(task, description=f"✓ Detected {len(result.code_changes)} code changes")
+
+                # Step 2: Show plan updates
+                if result.plan_updates:
+                    task = progress.add_task("Updating plan artifacts...", total=None)
+                    total_features = sum(update.get("features", 0) for update in result.plan_updates)
+                    progress.update(task, description=f"✓ Updated plan artifacts ({total_features} features)")
+
+                # Step 3: Show deviations
+                if result.deviations:
+                    task = progress.add_task("Tracking deviations...", total=None)
+                    progress.update(task, description=f"✓ Found {len(result.deviations)} deviations")
+
+        # Record sync results
+        record(
+            {
+                "code_changes": len(result.code_changes),
+                "plan_updates": len(result.plan_updates) if result.plan_updates else 0,
+                "deviations": len(result.deviations) if result.deviations else 0,
+            }
+        )
+
+        # Report results
+        console.print(f"[bold cyan]Code Changes:[/bold cyan] {len(result.code_changes)}")
+        if result.plan_updates:
+            console.print(f"[bold cyan]Plan Updates:[/bold cyan] {len(result.plan_updates)}")
         if result.deviations:
-            task = progress.add_task("Tracking deviations...", total=None)
-            progress.update(task, description=f"✓ Found {len(result.deviations)} deviations")
-
-    # Report results
-    console.print(f"[bold cyan]Code Changes:[/bold cyan] {len(result.code_changes)}")
-    if result.plan_updates:
-        console.print(f"[bold cyan]Plan Updates:[/bold cyan] {len(result.plan_updates)}")
-    if result.deviations:
-        console.print(f"[yellow]⚠[/yellow] Found {len(result.deviations)} deviations from manual plan")
-        console.print("[dim]Run 'specfact plan compare' for detailed deviation report[/dim]")
-    else:
-        console.print("[bold green]✓[/bold green] No deviations detected")
-
-    console.print("[bold green]✓[/bold green] Repository sync complete!")
+            console.print(f"[yellow]⚠[/yellow] Found {len(result.deviations)} deviations from manual plan")
+            console.print("[dim]Run 'specfact plan compare' for detailed deviation report[/dim]")
+        else:
+            console.print("[bold green]✓[/bold green] No deviations detected")
+        console.print("[bold green]✓[/bold green] Repository sync complete!")