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

specfact_cli/importers/speckit_converter.py

@@ -7,12 +7,15 @@ to SpecFact format (plans, protocols).
 
 from __future__ import annotations
 
+import re
+from collections.abc import Callable
 from pathlib import Path
 from typing import Any
 
 from beartype import beartype
 from icontract import ensure, require
 
+from specfact_cli.analyzers.constitution_evidence_extractor import ConstitutionEvidenceExtractor
 from specfact_cli.generators.plan_generator import PlanGenerator
 from specfact_cli.generators.protocol_generator import ProtocolGenerator
 from specfact_cli.generators.workflow_generator import WorkflowGenerator
@@ -43,6 +46,7 @@ class SpecKitConverter:
         self.protocol_generator = ProtocolGenerator()
         self.plan_generator = PlanGenerator()
         self.workflow_generator = WorkflowGenerator()
+        self.constitution_extractor = ConstitutionEvidenceExtractor(repo_path)
         self.mapping_file = mapping_file
 
     @beartype
@@ -111,10 +115,10 @@ class SpecKitConverter:
         # Discover features from markdown artifacts
         discovered_features = self.scanner.discover_features()
 
-        # Extract features from markdown data
-        features = self._extract_features_from_markdown(discovered_features)
+        # Extract features from markdown data (empty list if no features found)
+        features = self._extract_features_from_markdown(discovered_features) if discovered_features else []
 
-        # Parse constitution for constraints
+        # Parse constitution for constraints (only if needed for idea creation)
         structure = self.scanner.scan_structure()
         memory_dir = Path(structure.get("specify_memory_dir", "")) if structure.get("specify_memory_dir") else None
         constraints: list[str] = []
@@ -155,6 +159,7 @@ class SpecKitConverter:
             product=product,
             features=features,
             metadata=None,
+            clarifications=None,
         )
 
         # Write to file if output path provided
@@ -259,6 +264,16 @@ class SpecKitConverter:
                         if (story_ref and story_ref in story_key) or not story_ref:
                             tasks.append(task.get("description", ""))
 
+            # Extract scenarios from Spec-Kit format (Primary, Alternate, Exception, Recovery)
+            scenarios = story_data.get("scenarios")
+            # Ensure scenarios dict has correct format (filter out empty lists)
+            if scenarios and isinstance(scenarios, dict):
+                # Filter out empty scenario lists
+                filtered_scenarios = {k: v for k, v in scenarios.items() if v and isinstance(v, list) and len(v) > 0}
+                scenarios = filtered_scenarios if filtered_scenarios else None
+            else:
+                scenarios = None
+
             story = Story(
                 key=story_key,
                 title=story_title,
@@ -269,6 +284,8 @@ class SpecKitConverter:
                 tasks=tasks,
                 confidence=0.8,  # High confidence from spec
                 draft=False,
+                scenarios=scenarios,
+                contracts=None,
             )
             stories.append(story)
 
@@ -357,7 +374,9 @@ class SpecKitConverter:
     @require(lambda plan_bundle: isinstance(plan_bundle, PlanBundle), "Must be PlanBundle instance")
     @ensure(lambda result: isinstance(result, int), "Must return int (number of features converted)")
     @ensure(lambda result: result >= 0, "Result must be non-negative")
-    def convert_to_speckit(self, plan_bundle: PlanBundle) -> int:
+    def convert_to_speckit(
+        self, plan_bundle: PlanBundle, progress_callback: Callable[[int, int], None] | None = None
+    ) -> int:
         """
         Convert SpecFact plan bundle to Spec-Kit markdown artifacts.
 
@@ -365,27 +384,44 @@ class SpecKitConverter:
 
         Args:
             plan_bundle: SpecFact plan bundle to convert
+            progress_callback: Optional callback function(current, total) to report progress
 
         Returns:
             Number of features converted
         """
         features_converted = 0
-
-        for feature in plan_bundle.features:
+        total_features = len(plan_bundle.features)
+        # Track used feature numbers to avoid duplicates
+        used_feature_nums: set[int] = set()
+
+        for idx, feature in enumerate(plan_bundle.features, start=1):
+            # Report progress if callback provided
+            if progress_callback:
+                progress_callback(idx, total_features)
             # Generate feature directory name from key (FEATURE-001 -> 001-feature-name)
-            feature_num = self._extract_feature_number(feature.key)
+            # Use number from key if available and not already used, otherwise use sequential index
+            extracted_num = self._extract_feature_number(feature.key)
+            if extracted_num == 0 or extracted_num in used_feature_nums:
+                # No number found in key, or number already used - use sequential numbering
+                # Find next available sequential number starting from idx
+                feature_num = idx
+                while feature_num in used_feature_nums:
+                    feature_num += 1
+            else:
+                feature_num = extracted_num
+            used_feature_nums.add(feature_num)
             feature_name = self._to_feature_dir_name(feature.title)
 
             # Create feature directory
             feature_dir = self.repo_path / "specs" / f"{feature_num:03d}-{feature_name}"
             feature_dir.mkdir(parents=True, exist_ok=True)
 
-            # Generate spec.md
-            spec_content = self._generate_spec_markdown(feature)
+            # Generate spec.md (pass calculated feature_num to avoid recalculation)
+            spec_content = self._generate_spec_markdown(feature, feature_num=feature_num)
             (feature_dir / "spec.md").write_text(spec_content, encoding="utf-8")
 
             # Generate plan.md
-            plan_content = self._generate_plan_markdown(feature)
+            plan_content = self._generate_plan_markdown(feature, plan_bundle)
             (feature_dir / "plan.md").write_text(plan_content, encoding="utf-8")
 
             # Generate tasks.md
@@ -398,14 +434,29 @@ class SpecKitConverter:
 
     @beartype
     @require(lambda feature: isinstance(feature, Feature), "Must be Feature instance")
+    @require(
+        lambda feature_num: feature_num is None or feature_num > 0,
+        "Feature number must be None or positive",
+    )
     @ensure(lambda result: isinstance(result, str), "Must return string")
     @ensure(lambda result: len(result) > 0, "Result must be non-empty")
-    def _generate_spec_markdown(self, feature: Feature) -> str:
-        """Generate Spec-Kit spec.md content from SpecFact feature."""
+    def _generate_spec_markdown(self, feature: Feature, feature_num: int | None = None) -> str:
+        """
+        Generate Spec-Kit spec.md content from SpecFact feature.
+
+        Args:
+            feature: Feature to generate spec for
+            feature_num: Optional pre-calculated feature number (avoids recalculation with fallback)
+        """
         from datetime import datetime
 
         # Extract feature branch from feature key (FEATURE-001 -> 001-feature-name)
-        feature_num = self._extract_feature_number(feature.key)
+        # Use provided feature_num if available, otherwise extract from key (with fallback to 1)
+        if feature_num is None:
+            feature_num = self._extract_feature_number(feature.key)
+            if feature_num == 0:
+                # Fallback: use 1 if no number found (shouldn't happen if called from convert_to_speckit)
+                feature_num = 1
         feature_name = self._to_feature_dir_name(feature.title)
         feature_branch = f"{feature_num:03d}-{feature_name}"
 
@@ -438,7 +489,17 @@ class SpecKitConverter:
                 lines.append(f"### User Story {idx} - {story.title} (Priority: {priority})")
                 lines.append(f"Users can {story.title}")
                 lines.append("")
-                lines.append("**Why this priority**: Core functionality")
+                # Extract priority rationale from story tags, feature outcomes, or use default
+                priority_rationale = "Core functionality"
+                if story.tags:
+                    for tag in story.tags:
+                        if tag.startswith(("priority:", "rationale:")):
+                            priority_rationale = tag.split(":", 1)[1].strip()
+                            break
+                if (not priority_rationale or priority_rationale == "Core functionality") and feature.outcomes:
+                    # Try to extract from feature outcomes
+                    priority_rationale = feature.outcomes[0] if len(feature.outcomes[0]) < 100 else "Core functionality"
+                lines.append(f"**Why this priority**: {priority_rationale}")
                 lines.append("")
 
                 # INVSEST criteria (CRITICAL for /speckit.analyze and /speckit.checklist)
@@ -461,26 +522,100 @@ class SpecKitConverter:
                 for acc_idx, acc in enumerate(story.acceptance, start=1):
                     # Parse Given/When/Then if available
                     if "Given" in acc and "When" in acc and "Then" in acc:
-                        parts = acc.split(", ")
-                        given = parts[0].replace("Given ", "").strip()
-                        when = parts[1].replace("When ", "").strip()
-                        then = parts[2].replace("Then ", "").strip()
+                        # Use regex to properly extract Given/When/Then parts
+                        # This handles commas inside type hints (e.g., "dict[str, Any]")
+                        gwt_pattern = r"Given\s+(.+?),\s*When\s+(.+?),\s*Then\s+(.+?)(?:$|,)"
+                        match = re.search(gwt_pattern, acc, re.IGNORECASE | re.DOTALL)
+                        if match:
+                            given = match.group(1).strip()
+                            when = match.group(2).strip()
+                            then = match.group(3).strip()
+                        else:
+                            # Fallback to simple split if regex fails
+                            parts = acc.split(", ")
+                            given = parts[0].replace("Given ", "").strip() if len(parts) > 0 else ""
+                            when = parts[1].replace("When ", "").strip() if len(parts) > 1 else ""
+                            then = parts[2].replace("Then ", "").strip() if len(parts) > 2 else ""
                         lines.append(f"{acc_idx}. **Given** {given}, **When** {when}, **Then** {then}")
 
                         # Categorize scenarios based on keywords
                         scenario_text = f"{given}, {when}, {then}"
                         acc_lower = acc.lower()
-                        if any(keyword in acc_lower for keyword in ["error", "exception", "fail", "invalid"]):
+                        if any(keyword in acc_lower for keyword in ["error", "exception", "fail", "invalid", "reject"]):
                             scenarios_exception.append(scenario_text)
-                        elif any(keyword in acc_lower for keyword in ["recover", "retry", "fallback"]):
+                        elif any(keyword in acc_lower for keyword in ["recover", "retry", "fallback", "retry"]):
                             scenarios_recovery.append(scenario_text)
-                        elif any(keyword in acc_lower for keyword in ["alternate", "alternative", "different"]):
+                        elif any(
+                            keyword in acc_lower for keyword in ["alternate", "alternative", "different", "optional"]
+                        ):
                             scenarios_alternate.append(scenario_text)
                         else:
                             scenarios_primary.append(scenario_text)
                     else:
-                        lines.append(f"{acc_idx}. {acc}")
-                        scenarios_primary.append(acc)
+                        # Convert simple acceptance to Given/When/Then format for better scenario extraction
+                        acc_lower = acc.lower()
+
+                        # Generate Given/When/Then from simple acceptance
+                        if "must" in acc_lower or "should" in acc_lower or "will" in acc_lower:
+                            # Extract action and outcome
+                            if "verify" in acc_lower or "validate" in acc_lower:
+                                action = (
+                                    acc.replace("Must verify", "")
+                                    .replace("Must validate", "")
+                                    .replace("Should verify", "")
+                                    .replace("Should validate", "")
+                                    .strip()
+                                )
+                                given = "user performs action"
+                                when = f"system {action}"
+                                then = f"{action} succeeds"
+                            elif "handle" in acc_lower or "display" in acc_lower:
+                                action = (
+                                    acc.replace("Must handle", "")
+                                    .replace("Must display", "")
+                                    .replace("Should handle", "")
+                                    .replace("Should display", "")
+                                    .strip()
+                                )
+                                given = "error condition occurs"
+                                when = "system processes error"
+                                then = f"system {action}"
+                            else:
+                                # Generic conversion
+                                given = "user interacts with system"
+                                when = "action is performed"
+                                then = acc.replace("Must", "").replace("Should", "").replace("Will", "").strip()
+
+                            lines.append(f"{acc_idx}. **Given** {given}, **When** {when}, **Then** {then}")
+
+                            # Categorize based on keywords
+                            scenario_text = f"{given}, {when}, {then}"
+                            if any(
+                                keyword in acc_lower
+                                for keyword in ["error", "exception", "fail", "invalid", "reject", "handle error"]
+                            ):
+                                scenarios_exception.append(scenario_text)
+                            elif any(keyword in acc_lower for keyword in ["recover", "retry", "fallback"]):
+                                scenarios_recovery.append(scenario_text)
+                            elif any(
+                                keyword in acc_lower
+                                for keyword in ["alternate", "alternative", "different", "optional"]
+                            ):
+                                scenarios_alternate.append(scenario_text)
+                            else:
+                                scenarios_primary.append(scenario_text)
+                        else:
+                            # Keep original format but still categorize
+                            lines.append(f"{acc_idx}. {acc}")
+                            acc_lower = acc.lower()
+                            if any(keyword in acc_lower for keyword in ["error", "exception", "fail", "invalid"]):
+                                scenarios_exception.append(acc)
+                            elif any(keyword in acc_lower for keyword in ["recover", "retry", "fallback"]):
+                                scenarios_recovery.append(acc)
+                            elif any(keyword in acc_lower for keyword in ["alternate", "alternative", "different"]):
+                                scenarios_alternate.append(acc)
+                            else:
+                                scenarios_primary.append(acc)
 
                 lines.append("")
 
@@ -546,9 +681,12 @@ class SpecKitConverter:
         return "\n".join(lines)
 
     @beartype
-    @require(lambda feature: isinstance(feature, Feature), "Must be Feature instance")
+    @require(
+        lambda feature, plan_bundle: isinstance(feature, Feature) and isinstance(plan_bundle, PlanBundle),
+        "Must be Feature and PlanBundle instances",
+    )
     @ensure(lambda result: isinstance(result, str), "Must return string")
-    def _generate_plan_markdown(self, feature: Feature) -> str:
+    def _generate_plan_markdown(self, feature: Feature, plan_bundle: PlanBundle) -> str:
         """Generate Spec-Kit plan.md content from SpecFact feature."""
         lines = [f"# Implementation Plan: {feature.title}", ""]
         lines.append("## Summary")
@@ -557,21 +695,49 @@ class SpecKitConverter:
 
         lines.append("## Technical Context")
         lines.append("")
-        lines.append("**Language/Version**: Python 3.11+")
+
+        # Extract technology stack from constraints
+        technology_stack = self._extract_technology_stack(feature, plan_bundle)
+        language_version = next((s for s in technology_stack if "Python" in s), "Python 3.11+")
+
+        lines.append(f"**Language/Version**: {language_version}")
         lines.append("")
 
         lines.append("**Primary Dependencies:**")
         lines.append("")
-        # Could extract from feature context if available
-        lines.append("- `typer` - CLI framework")
-        lines.append("- `pydantic` - Data validation")
+        # Extract dependencies from technology stack
+        dependencies = [
+            s
+            for s in technology_stack
+            if any(fw in s.lower() for fw in ["typer", "fastapi", "django", "flask", "pydantic", "sqlalchemy"])
+        ]
+        if dependencies:
+            for dep in dependencies[:5]:  # Limit to top 5
+                # Format: "FastAPI framework" -> "fastapi - Web framework"
+                dep_lower = dep.lower()
+                if "fastapi" in dep_lower:
+                    lines.append("- `fastapi` - Web framework")
+                elif "django" in dep_lower:
+                    lines.append("- `django` - Web framework")
+                elif "flask" in dep_lower:
+                    lines.append("- `flask` - Web framework")
+                elif "typer" in dep_lower:
+                    lines.append("- `typer` - CLI framework")
+                elif "pydantic" in dep_lower:
+                    lines.append("- `pydantic` - Data validation")
+                elif "sqlalchemy" in dep_lower:
+                    lines.append("- `sqlalchemy` - ORM")
+                else:
+                    lines.append(f"- {dep}")
+        else:
+            lines.append("- `typer` - CLI framework")
+            lines.append("- `pydantic` - Data validation")
         lines.append("")
 
         lines.append("**Technology Stack:**")
         lines.append("")
-        lines.append("- Python 3.11+")
-        lines.append("- Typer for CLI")
-        lines.append("- Pydantic for data validation")
+        for stack_item in technology_stack:
+            lines.append(f"- {stack_item}")
         lines.append("")
 
         lines.append("**Constraints:**")
@@ -588,23 +754,87 @@ class SpecKitConverter:
         lines.append("- None at this time")
         lines.append("")
 
+        # Check if contracts are defined in stories (for Article IX and contract definitions section)
+        contracts_defined = any(story.contracts for story in feature.stories if story.contracts)
+
         # Constitution Check section (CRITICAL for /speckit.analyze)
-        lines.append("## Constitution Check")
-        lines.append("")
-        lines.append("**Article VII (Simplicity)**:")
-        lines.append("- [ ] Using ≤3 projects?")
-        lines.append("- [ ] No future-proofing?")
-        lines.append("")
-        lines.append("**Article VIII (Anti-Abstraction)**:")
-        lines.append("- [ ] Using framework directly?")
-        lines.append("- [ ] Single model representation?")
-        lines.append("")
-        lines.append("**Article IX (Integration-First)**:")
-        lines.append("- [ ] Contracts defined?")
-        lines.append("- [ ] Contract tests written?")
-        lines.append("")
-        lines.append("**Status**: PASS")
-        lines.append("")
+        # Extract evidence-based constitution status (Step 2.2)
+        try:
+            constitution_evidence = self.constitution_extractor.extract_all_evidence(self.repo_path)
+            constitution_section = self.constitution_extractor.generate_constitution_check_section(
+                constitution_evidence
+            )
+            lines.append(constitution_section)
+        except Exception:
+            # Fallback to basic constitution check if extraction fails
+            lines.append("## Constitution Check")
+            lines.append("")
+            lines.append("**Article VII (Simplicity)**:")
+            lines.append("- [ ] Evidence extraction pending")
+            lines.append("")
+            lines.append("**Article VIII (Anti-Abstraction)**:")
+            lines.append("- [ ] Evidence extraction pending")
+            lines.append("")
+            lines.append("**Article IX (Integration-First)**:")
+            if contracts_defined:
+                lines.append("- [x] Contracts defined?")
+                lines.append("- [ ] Contract tests written?")
+            else:
+                lines.append("- [ ] Contracts defined?")
+                lines.append("- [ ] Contract tests written?")
+            lines.append("")
+            lines.append("**Status**: PENDING")
+            lines.append("")
+
+        # Add contract definitions section if contracts exist (Step 2.1)
+        if contracts_defined:
+            lines.append("### Contract Definitions")
+            lines.append("")
+            for story in feature.stories:
+                if story.contracts:
+                    lines.append(f"#### {story.title}")
+                    lines.append("")
+                    contracts = story.contracts
+
+                    # Parameters
+                    if contracts.get("parameters"):
+                        lines.append("**Parameters:**")
+                        for param in contracts["parameters"]:
+                            param_type = param.get("type", "Any")
+                            required = "required" if param.get("required", True) else "optional"
+                            default = f" (default: {param.get('default')})" if param.get("default") is not None else ""
+                            lines.append(f"- `{param['name']}`: {param_type} ({required}){default}")
+                        lines.append("")
+
+                    # Return type
+                    if contracts.get("return_type"):
+                        return_type = contracts["return_type"].get("type", "Any")
+                        lines.append(f"**Return Type**: `{return_type}`")
+                        lines.append("")
+
+                    # Preconditions
+                    if contracts.get("preconditions"):
+                        lines.append("**Preconditions:**")
+                        for precondition in contracts["preconditions"]:
+                            lines.append(f"- {precondition}")
+                        lines.append("")
+
+                    # Postconditions
+                    if contracts.get("postconditions"):
+                        lines.append("**Postconditions:**")
+                        for postcondition in contracts["postconditions"]:
+                            lines.append(f"- {postcondition}")
+                        lines.append("")
+
+                    # Error contracts
+                    if contracts.get("error_contracts"):
+                        lines.append("**Error Contracts:**")
+                        for error_contract in contracts["error_contracts"]:
+                            exc_type = error_contract.get("exception_type", "Exception")
+                            condition = error_contract.get("condition", "Error condition")
+                            lines.append(f"- `{exc_type}`: {condition}")
+                        lines.append("")
+            lines.append("")
 
         # Phases section
         lines.append("## Phase 0: Research")
@@ -724,6 +954,92 @@ class SpecKitConverter:
 
         return "\n".join(lines)
 
+    @beartype
+    @require(lambda feature: isinstance(feature, Feature), "Must be Feature instance")
+    @require(lambda plan_bundle: isinstance(plan_bundle, PlanBundle), "Must be PlanBundle instance")
+    @ensure(lambda result: isinstance(result, list), "Must return list")
+    @ensure(lambda result: len(result) > 0, "Must have at least one stack item")
+    def _extract_technology_stack(self, feature: Feature, plan_bundle: PlanBundle) -> list[str]:
+        """
+        Extract technology stack from feature and plan bundle constraints.
+
+        Args:
+            feature: Feature to extract stack from
+            plan_bundle: Plan bundle containing idea-level constraints
+
+        Returns:
+            List of technology stack items
+        """
+        stack: list[str] = []
+        seen: set[str] = set()
+
+        # Extract from idea-level constraints (project-wide)
+        if plan_bundle.idea and plan_bundle.idea.constraints:
+            for constraint in plan_bundle.idea.constraints:
+                constraint_lower = constraint.lower()
+
+                # Extract Python version
+                if "python" in constraint_lower and constraint not in seen:
+                    stack.append(constraint)
+                    seen.add(constraint)
+
+                # Extract frameworks
+                for fw in ["fastapi", "django", "flask", "typer", "tornado", "bottle"]:
+                    if fw in constraint_lower and constraint not in seen:
+                        stack.append(constraint)
+                        seen.add(constraint)
+                        break
+
+                # Extract databases
+                for db in ["postgres", "postgresql", "mysql", "sqlite", "redis", "mongodb", "cassandra"]:
+                    if db in constraint_lower and constraint not in seen:
+                        stack.append(constraint)
+                        seen.add(constraint)
+                        break
+
+        # Extract from feature-level constraints (feature-specific)
+        if feature.constraints:
+            for constraint in feature.constraints:
+                constraint_lower = constraint.lower()
+
+                # Skip if already added from idea constraints
+                if constraint in seen:
+                    continue
+
+                # Extract frameworks
+                for fw in ["fastapi", "django", "flask", "typer", "tornado", "bottle"]:
+                    if fw in constraint_lower:
+                        stack.append(constraint)
+                        seen.add(constraint)
+                        break
+
+                # Extract databases
+                for db in ["postgres", "postgresql", "mysql", "sqlite", "redis", "mongodb", "cassandra"]:
+                    if db in constraint_lower:
+                        stack.append(constraint)
+                        seen.add(constraint)
+                        break
+
+                # Extract testing tools
+                for test in ["pytest", "unittest", "nose", "tox"]:
+                    if test in constraint_lower:
+                        stack.append(constraint)
+                        seen.add(constraint)
+                        break
+
+                # Extract deployment tools
+                for deploy in ["docker", "kubernetes", "aws", "gcp", "azure"]:
+                    if deploy in constraint_lower:
+                        stack.append(constraint)
+                        seen.add(constraint)
+                        break
+
+        # Default fallback if nothing extracted
+        if not stack:
+            stack = ["Python 3.11+", "Typer for CLI", "Pydantic for data validation"]
+
+        return stack
+
     @beartype
     @require(lambda feature_key: isinstance(feature_key, str), "Must be string")
     @ensure(lambda result: isinstance(result, int), "Must return int")

specfact_cli/importers/speckit_scanner.py

@@ -55,6 +55,71 @@ class SpecKitScanner:
         specify_dir = self.repo_path / self.SPECIFY_DIR
         return specify_dir.exists() and specify_dir.is_dir()
 
+    @beartype
+    @ensure(lambda result: isinstance(result, tuple), "Must return tuple")
+    @ensure(lambda result: len(result) == 2, "Must return (bool, str) tuple")
+    def has_constitution(self) -> tuple[bool, str]:
+        """
+        Check if constitution.md exists and is not empty.
+
+        Returns:
+            Tuple of (exists_and_valid, error_message)
+            - exists_and_valid: True if constitution exists and has content
+            - error_message: Empty string if valid, otherwise error description
+        """
+        memory_dir = self.repo_path / self.SPECIFY_MEMORY_DIR
+        constitution_file = memory_dir / "constitution.md"
+
+        if not memory_dir.exists():
+            return (
+                False,
+                f"Spec-Kit memory directory not found: {memory_dir}\n"
+                "The constitution must be created before syncing.\n"
+                "Run '/speckit.constitution' command first to create the project constitution.",
+            )
+
+        if not constitution_file.exists():
+            return (
+                False,
+                f"Constitution file not found: {constitution_file}\n"
+                "The constitution is required before syncing Spec-Kit artifacts.\n"
+                "Run '/speckit.constitution' command first to create the project constitution.",
+            )
+
+        # Check if file is empty or only contains whitespace/placeholders
+        try:
+            content = constitution_file.read_text(encoding="utf-8").strip()
+            if not content:
+                return (
+                    False,
+                    f"Constitution file is empty: {constitution_file}\n"
+                    "The constitution must be populated before syncing.\n"
+                    "Run '/speckit.constitution' command to fill in the constitution template.",
+                )
+
+            # Check if file only contains template placeholders (no actual content)
+            # Look for patterns like [PROJECT_NAME], [PRINCIPLE_1_NAME], etc.
+            placeholder_pattern = r"\[[A-Z_0-9]+\]"
+            placeholder_count = len(re.findall(placeholder_pattern, content))
+            # If more than 50% of lines contain placeholders, consider it a template
+            lines = [line.strip() for line in content.split("\n") if line.strip()]
+            if lines and placeholder_count > len(lines) * 0.5:
+                return (
+                    False,
+                    f"Constitution file contains only template placeholders: {constitution_file}\n"
+                    "The constitution must be filled in before syncing.\n"
+                    "Run '/speckit.constitution' command to replace placeholders with actual project principles.",
+                )
+
+            return (True, "")
+        except Exception as e:
+            return (
+                False,
+                f"Error reading constitution file: {constitution_file}\n"
+                f"Error: {e!s}\n"
+                "Please ensure the constitution file is readable and try again.",
+            )
+
     @beartype
     @ensure(lambda result: isinstance(result, dict), "Must return dictionary")
     @ensure(lambda result: "is_speckit" in result, "Must include is_speckit key")