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

specfact_cli/utils/ide_setup.py

@@ -9,6 +9,8 @@ from __future__ import annotations
 
 import os
 import re
+import site
+import sys
 from pathlib import Path
 from typing import Literal
 
@@ -112,10 +114,17 @@ IDE_CONFIG: dict[str, dict[str, str | bool | None]] = {
 SPECFACT_COMMANDS = [
     "specfact-import-from-code",
     "specfact-plan-init",
+    "specfact-plan-add-feature",
+    "specfact-plan-add-story",
+    "specfact-plan-update-idea",
+    "specfact-plan-update-feature",
     "specfact-plan-select",
     "specfact-plan-promote",
     "specfact-plan-compare",
+    "specfact-plan-review",
     "specfact-sync",
+    "specfact-enforce",
+    "specfact-repro",
 ]
 
 
@@ -380,3 +389,164 @@ def create_vscode_settings(repo_path: Path, settings_file: str) -> Path | None:
 
     console.print(f"[green]Updated:[/green] {settings_path}")
     return settings_path
+
+
+@beartype
+@ensure(
+    lambda result: isinstance(result, list) and all(isinstance(p, Path) for p in result), "Must return list of Paths"
+)
+def get_package_installation_locations(package_name: str) -> list[Path]:
+    """
+    Get all possible installation locations for a Python package across different OS and installation types.
+
+    This function searches for package locations in:
+    - User site-packages (per-user installations: ~/.local/lib/python3.X/site-packages)
+    - System site-packages (global installations: /usr/lib/python3.X/site-packages, C:\\Python3X\\Lib\\site-packages)
+    - Virtual environments (venv, conda, etc.)
+    - uvx cache locations (~/.cache/uv/archive-v0/...)
+
+    Args:
+        package_name: Name of the package to locate (e.g., "specfact_cli")
+
+    Returns:
+        List of Path objects representing possible package installation locations
+
+    Examples:
+        >>> locations = get_package_installation_locations("specfact_cli")
+        >>> len(locations) > 0
+        True
+    """
+    locations: list[Path] = []
+
+    # Method 1: Use importlib.util.find_spec() to find the actual installed location
+    try:
+        import importlib.util
+
+        spec = importlib.util.find_spec(package_name)
+        if spec and spec.origin:
+            package_path = Path(spec.origin).parent.resolve()
+            locations.append(package_path)
+    except Exception:
+        pass
+
+    # Method 2: Check all site-packages directories (user + system)
+    try:
+        # User site-packages (per-user installation)
+        # Linux/macOS: ~/.local/lib/python3.X/site-packages
+        # Windows: %APPDATA%\\Python\\Python3X\\site-packages
+        user_site = site.getusersitepackages()
+        if user_site:
+            user_package_path = Path(user_site) / package_name
+            if user_package_path.exists():
+                locations.append(user_package_path.resolve())
+    except Exception:
+        pass
+
+    try:
+        # System site-packages (global installation)
+        # Linux: /usr/lib/python3.X/dist-packages, /usr/local/lib/python3.X/dist-packages
+        # macOS: /Library/Frameworks/Python.framework/Versions/X/lib/pythonX.X/site-packages
+        # Windows: C:\\Python3X\\Lib\\site-packages
+        system_sites = site.getsitepackages()
+        for site_path in system_sites:
+            system_package_path = Path(site_path) / package_name
+            if system_package_path.exists():
+                locations.append(system_package_path.resolve())
+    except Exception:
+        pass
+
+    # Method 3: Check sys.path for additional locations (virtual environments, etc.)
+    for path_str in sys.path:
+        if not path_str or path_str == "":
+            continue
+        try:
+            path = Path(path_str).resolve()
+            if path.exists() and path.is_dir():
+                # Check if package is directly in this path
+                package_path = path / package_name
+                if package_path.exists():
+                    locations.append(package_path.resolve())
+                # Check if this is a site-packages directory
+                if path.name == "site-packages" or "site-packages" in path.parts:
+                    package_path = path / package_name
+                    if package_path.exists():
+                        locations.append(package_path.resolve())
+        except Exception:
+            continue
+
+    # Method 4: Check uvx cache locations (common on Linux/macOS/Windows)
+    # uvx stores packages in cache directories with varying structures
+    if sys.platform != "win32":
+        # Linux/macOS: ~/.cache/uv/archive-v0/.../lib/python3.X/site-packages/
+        uvx_cache_base = Path.home() / ".cache" / "uv" / "archive-v0"
+        if uvx_cache_base.exists():
+            for archive_dir in uvx_cache_base.iterdir():
+                if archive_dir.is_dir():
+                    # Look for site-packages directories (rglob finds all matches)
+                    for site_packages_dir in archive_dir.rglob("site-packages"):
+                        if site_packages_dir.is_dir():
+                            package_path = site_packages_dir / package_name
+                            if package_path.exists():
+                                locations.append(package_path.resolve())
+    else:
+        # Windows: Check %LOCALAPPDATA%\\uv\\cache\\archive-v0\\
+        localappdata = os.environ.get("LOCALAPPDATA")
+        if localappdata:
+            uvx_cache_base = Path(localappdata) / "uv" / "cache" / "archive-v0"
+            if uvx_cache_base.exists():
+                for archive_dir in uvx_cache_base.iterdir():
+                    if archive_dir.is_dir():
+                        # Look for site-packages directories
+                        for site_packages_dir in archive_dir.rglob("site-packages"):
+                            if site_packages_dir.is_dir():
+                                package_path = site_packages_dir / package_name
+                                if package_path.exists():
+                                    locations.append(package_path.resolve())
+
+    # Remove duplicates while preserving order
+    seen = set()
+    unique_locations: list[Path] = []
+    for loc in locations:
+        loc_str = str(loc)
+        if loc_str not in seen:
+            seen.add(loc_str)
+            unique_locations.append(loc)
+
+    return unique_locations
+
+
+@beartype
+@require(lambda package_name: isinstance(package_name, str) and len(package_name) > 0, "Package name must be non-empty")
+@ensure(
+    lambda result: result is None or (isinstance(result, Path) and result.exists()),
+    "Result must be None or existing Path",
+)
+def find_package_resources_path(package_name: str, resource_subpath: str) -> Path | None:
+    """
+    Find the path to a resource within an installed package.
+
+    Searches across all possible installation locations (user, system, venv, uvx cache)
+    to find the package and then locates the resource subpath.
+
+    Args:
+        package_name: Name of the package (e.g., "specfact_cli")
+        resource_subpath: Subpath within the package (e.g., "resources/prompts")
+
+    Returns:
+        Path to the resource directory if found, None otherwise
+
+    Examples:
+        >>> path = find_package_resources_path("specfact_cli", "resources/prompts")
+        >>> path is None or path.exists()
+        True
+    """
+    # Get all possible package installation locations
+    package_locations = get_package_installation_locations(package_name)
+
+    # Try each location
+    for package_path in package_locations:
+        resource_path = (package_path / resource_subpath).resolve()
+        if resource_path.exists():
+            return resource_path
+
+    return None

specfact_cli/utils/structure.py

@@ -30,6 +30,7 @@ class SpecFactStructure:
     REPORTS_BROWNFIELD = f"{ROOT}/reports/brownfield"
     REPORTS_COMPARISON = f"{ROOT}/reports/comparison"
     REPORTS_ENFORCEMENT = f"{ROOT}/reports/enforcement"
+    REPORTS_ENRICHMENT = f"{ROOT}/reports/enrichment"
     GATES_RESULTS = f"{ROOT}/gates/results"
     CACHE = f"{ROOT}/cache"
 
@@ -76,6 +77,7 @@ class SpecFactStructure:
         (base_path / cls.REPORTS_BROWNFIELD).mkdir(parents=True, exist_ok=True)
         (base_path / cls.REPORTS_COMPARISON).mkdir(parents=True, exist_ok=True)
         (base_path / cls.REPORTS_ENFORCEMENT).mkdir(parents=True, exist_ok=True)
+        (base_path / cls.REPORTS_ENRICHMENT).mkdir(parents=True, exist_ok=True)
         (base_path / cls.GATES_RESULTS).mkdir(parents=True, exist_ok=True)
         (base_path / cls.CACHE).mkdir(parents=True, exist_ok=True)
 
@@ -264,8 +266,10 @@ class SpecFactStructure:
             except Exception:
                 pass
 
-        # Find all plan bundles
-        for plan_file in sorted(plans_dir.glob("*.bundle.yaml"), reverse=True):
+        # Find all plan bundles, sorted by modification date (oldest first, newest last)
+        plan_files = list(plans_dir.glob("*.bundle.yaml"))
+        plan_files_sorted = sorted(plan_files, key=lambda p: p.stat().st_mtime, reverse=False)
+        for plan_file in plan_files_sorted:
             if plan_file.name == "config.yaml":
                 continue
 
@@ -391,6 +395,175 @@ class SpecFactStructure:
         directory.mkdir(parents=True, exist_ok=True)
         return directory / f"{sanitized_name}.{timestamp}.bundle.yaml"
 
+    @classmethod
+    @beartype
+    @require(lambda plan_bundle_path: isinstance(plan_bundle_path, Path), "Plan bundle path must be Path")
+    @ensure(lambda result: isinstance(result, Path), "Must return Path")
+    def get_enrichment_report_path(cls, plan_bundle_path: Path, base_path: Path | None = None) -> Path:
+        """
+        Get enrichment report path based on plan bundle path.
+
+        The enrichment report is named to match the plan bundle, replacing
+        `.bundle.yaml` with `.enrichment.md` and placing it in the enrichment reports directory.
+
+        Args:
+            plan_bundle_path: Path to plan bundle file (e.g., `.specfact/plans/specfact-cli.2025-11-17T09-26-47.bundle.yaml`)
+            base_path: Base directory (default: current directory)
+
+        Returns:
+            Path to enrichment report (e.g., `.specfact/reports/enrichment/specfact-cli.2025-11-17T09-26-47.enrichment.md`)
+
+        Examples:
+            >>> plan = Path('.specfact/plans/specfact-cli.2025-11-17T09-26-47.bundle.yaml')
+            >>> SpecFactStructure.get_enrichment_report_path(plan)
+            Path('.specfact/reports/enrichment/specfact-cli.2025-11-17T09-26-47.enrichment.md')
+        """
+        if base_path is None:
+            base_path = Path(".")
+        else:
+            # Normalize base_path to repository root (avoid recursive .specfact creation)
+            base_path = Path(base_path).resolve()
+            # If base_path contains .specfact, find the repository root
+            parts = base_path.parts
+            if ".specfact" in parts:
+                # Find the index of .specfact and go up to repository root
+                specfact_idx = parts.index(".specfact")
+                base_path = Path(*parts[:specfact_idx])
+
+        # Extract filename from plan bundle path
+        plan_filename = plan_bundle_path.name
+
+        # Replace .bundle.yaml with .enrichment.md
+        if plan_filename.endswith(".bundle.yaml"):
+            enrichment_filename = plan_filename.replace(".bundle.yaml", ".enrichment.md")
+        else:
+            # Fallback: append .enrichment.md if pattern doesn't match
+            enrichment_filename = f"{plan_bundle_path.stem}.enrichment.md"
+
+        directory = base_path / cls.REPORTS_ENRICHMENT
+        directory.mkdir(parents=True, exist_ok=True)
+        return directory / enrichment_filename
+
+    @classmethod
+    @beartype
+    @require(
+        lambda enrichment_report_path: isinstance(enrichment_report_path, Path), "Enrichment report path must be Path"
+    )
+    @ensure(lambda result: result is None or isinstance(result, Path), "Must return None or Path")
+    def get_plan_bundle_from_enrichment(
+        cls, enrichment_report_path: Path, base_path: Path | None = None
+    ) -> Path | None:
+        """
+        Get original plan bundle path from enrichment report path.
+
+        Derives the original plan bundle path by reversing the enrichment report naming convention.
+        The enrichment report is named to match the plan bundle, so we can reverse this.
+
+        Args:
+            enrichment_report_path: Path to enrichment report (e.g., `.specfact/reports/enrichment/specfact-cli.2025-11-17T09-26-47.enrichment.md`)
+            base_path: Base directory (default: current directory)
+
+        Returns:
+            Path to original plan bundle, or None if not found
+
+        Examples:
+            >>> enrichment = Path('.specfact/reports/enrichment/specfact-cli.2025-11-17T09-26-47.enrichment.md')
+            >>> SpecFactStructure.get_plan_bundle_from_enrichment(enrichment)
+            Path('.specfact/plans/specfact-cli.2025-11-17T09-26-47.bundle.yaml')
+        """
+        if base_path is None:
+            base_path = Path(".")
+        else:
+            # Normalize base_path to repository root
+            base_path = Path(base_path).resolve()
+            parts = base_path.parts
+            if ".specfact" in parts:
+                specfact_idx = parts.index(".specfact")
+                base_path = Path(*parts[:specfact_idx])
+
+        # Extract filename from enrichment report path
+        enrichment_filename = enrichment_report_path.name
+
+        # Replace .enrichment.md with .bundle.yaml
+        if enrichment_filename.endswith(".enrichment.md"):
+            plan_filename = enrichment_filename.replace(".enrichment.md", ".bundle.yaml")
+        else:
+            # Fallback: try to construct from stem
+            plan_filename = f"{enrichment_report_path.stem}.bundle.yaml"
+
+        plan_path = base_path / cls.PLANS / plan_filename
+        return plan_path if plan_path.exists() else None
+
+    @classmethod
+    @beartype
+    @require(lambda original_plan_path: isinstance(original_plan_path, Path), "Original plan path must be Path")
+    @require(lambda base_path: base_path is None or isinstance(base_path, Path), "Base path must be None or Path")
+    @ensure(lambda result: isinstance(result, Path), "Must return Path")
+    def get_enriched_plan_path(cls, original_plan_path: Path, base_path: Path | None = None) -> Path:
+        """
+        Get enriched plan bundle path based on original plan bundle path.
+
+        Creates a path for an enriched plan bundle with a clear "enriched" label and timestamp.
+        Format: `<name>.<original-timestamp>.enriched.<enrichment-timestamp>.bundle.yaml`
+
+        Args:
+            original_plan_path: Path to original plan bundle (e.g., `.specfact/plans/specfact-cli.2025-11-17T09-26-47.bundle.yaml`)
+            base_path: Base directory (default: current directory)
+
+        Returns:
+            Path to enriched plan bundle (e.g., `.specfact/plans/specfact-cli.2025-11-17T09-26-47.enriched.2025-11-17T11-15-29.bundle.yaml`)
+
+        Examples:
+            >>> plan = Path('.specfact/plans/specfact-cli.2025-11-17T09-26-47.bundle.yaml')
+            >>> SpecFactStructure.get_enriched_plan_path(plan)
+            Path('.specfact/plans/specfact-cli.2025-11-17T09-26-47.enriched.2025-11-17T11-15-29.bundle.yaml')
+        """
+        if base_path is None:
+            base_path = Path(".")
+        else:
+            # Normalize base_path to repository root
+            base_path = Path(base_path).resolve()
+            parts = base_path.parts
+            if ".specfact" in parts:
+                specfact_idx = parts.index(".specfact")
+                base_path = Path(*parts[:specfact_idx])
+
+        # Extract original plan filename
+        original_filename = original_plan_path.name
+
+        # Extract name and original timestamp from filename
+        # Format: <name>.<timestamp>.bundle.yaml
+        if original_filename.endswith(".bundle.yaml"):
+            name_with_timestamp = original_filename.replace(".bundle.yaml", "")
+            # Split name and timestamp (timestamp is after last dot before .bundle.yaml)
+            # Pattern: <name>.<timestamp> -> we want to insert .enriched.<new-timestamp>
+            parts_name = name_with_timestamp.rsplit(".", 1)
+            if len(parts_name) == 2:
+                # Has timestamp: <name>.<timestamp>
+                name_part = parts_name[0]
+                original_timestamp = parts_name[1]
+            else:
+                # No timestamp found, use whole name
+                name_part = name_with_timestamp
+                original_timestamp = None
+        else:
+            # Fallback: use stem
+            name_part = original_plan_path.stem
+            original_timestamp = None
+
+        # Generate new timestamp for enrichment
+        enrichment_timestamp = datetime.now().strftime("%Y-%m-%dT%H-%M-%S")
+
+        # Build enriched filename
+        if original_timestamp:
+            enriched_filename = f"{name_part}.{original_timestamp}.enriched.{enrichment_timestamp}.bundle.yaml"
+        else:
+            enriched_filename = f"{name_part}.enriched.{enrichment_timestamp}.bundle.yaml"
+
+        directory = base_path / cls.PLANS
+        directory.mkdir(parents=True, exist_ok=True)
+        return directory / enriched_filename
+
     @classmethod
     @beartype
     @require(lambda base_path: base_path is None or isinstance(base_path, Path), "Base path must be None or Path")
@@ -462,6 +635,10 @@ This directory contains SpecFact CLI artifacts for contract-driven development.
 - `plans/` - Plan bundles (versioned in git)
 - `protocols/` - FSM protocol definitions (versioned)
 - `reports/` - Analysis reports (gitignored)
+  - `brownfield/` - Brownfield import analysis reports
+  - `comparison/` - Plan comparison reports
+  - `enforcement/` - Enforcement validation reports
+  - `enrichment/` - LLM enrichment reports (matched to plan bundles by name/timestamp)
 - `gates/` - Enforcement configuration and results
 - `cache/` - Tool caches (gitignored)
 

specfact_cli/utils/yaml_utils.py

@@ -12,6 +12,7 @@ from typing import Any
 from beartype import beartype
 from icontract import ensure, require
 from ruamel.yaml import YAML
+from ruamel.yaml.scalarstring import DoubleQuotedScalarString
 
 
 class YAMLUtils:
@@ -33,6 +34,9 @@ class YAMLUtils:
         self.yaml.preserve_quotes = preserve_quotes
         self.yaml.indent(mapping=indent_mapping, sequence=indent_sequence)
         self.yaml.default_flow_style = False
+        # Configure to quote boolean-like strings to prevent YAML parsing issues
+        # YAML parsers interpret "Yes", "No", "True", "False", "On", "Off" as booleans
+        self.yaml.default_style = None  # Let ruamel.yaml decide, but we'll quote manually
 
     @beartype
     @require(lambda file_path: isinstance(file_path, (Path, str)), "File path must be Path or str")
@@ -86,9 +90,38 @@ class YAMLUtils:
         file_path = Path(file_path)
         file_path.parent.mkdir(parents=True, exist_ok=True)
 
+        # Quote boolean-like strings to prevent YAML parsing issues
+        data = self._quote_boolean_like_strings(data)
+
         with open(file_path, "w", encoding="utf-8") as f:
             self.yaml.dump(data, f)
 
+    @beartype
+    def _quote_boolean_like_strings(self, data: Any) -> Any:
+        """
+        Recursively quote boolean-like strings to prevent YAML parsing issues.
+
+        YAML parsers interpret "Yes", "No", "True", "False", "On", "Off" as booleans
+        unless they're quoted. This function ensures these values are quoted.
+
+        Args:
+            data: Data structure to process
+
+        Returns:
+            Data structure with boolean-like strings quoted
+        """
+        # Boolean-like strings that YAML parsers interpret as booleans
+        boolean_like_strings = {"yes", "no", "true", "false", "on", "off", "Yes", "No", "True", "False", "On", "Off"}
+
+        if isinstance(data, dict):
+            return {k: self._quote_boolean_like_strings(v) for k, v in data.items()}
+        if isinstance(data, list):
+            return [self._quote_boolean_like_strings(item) for item in data]
+        if isinstance(data, str) and data in boolean_like_strings:
+            # Use DoubleQuotedScalarString to force quoting in YAML output
+            return DoubleQuotedScalarString(data)
+        return data
+
     @beartype
     @ensure(lambda result: isinstance(result, str), "Must return string")
     def dump_string(self, data: Any) -> str:

specfact_cli/validators/repro_checker.py

@@ -605,8 +605,23 @@ class ReproChecker:
             result.output = proc.stdout
             result.error = proc.stderr
 
+            # Check if this is a CrossHair signature analysis limitation (not a real failure)
+            is_signature_issue = False
+            if tool.lower() == "crosshair" and proc.returncode != 0:
+                combined_output = f"{proc.stderr} {proc.stdout}".lower()
+                is_signature_issue = (
+                    "wrong parameter order" in combined_output
+                    or "keyword-only parameter" in combined_output
+                    or "valueerror: wrong parameter" in combined_output
+                    or ("signature" in combined_output and ("error" in combined_output or "failure" in combined_output))
+                )
+
             if proc.returncode == 0:
                 result.status = CheckStatus.PASSED
+            elif is_signature_issue:
+                # CrossHair signature analysis limitation - treat as skipped, not failed
+                result.status = CheckStatus.SKIPPED
+                result.error = f"CrossHair signature analysis limitation (non-blocking, runtime contracts valid): {proc.stderr[:200] if proc.stderr else 'signature analysis limitation'}"
             else:
                 result.status = CheckStatus.FAILED
 
@@ -648,7 +663,13 @@ class ReproChecker:
         src_dir = self.repo_path / "src"
 
         checks: list[tuple[str, str, list[str], int | None, bool]] = [
-            ("Linting (ruff)", "ruff", ["ruff", "check", "src/", "tests/", "tools/"], None, True),
+            (
+                "Linting (ruff)",
+                "ruff",
+                ["ruff", "check", "--output-format=full", "src/", "tests/", "tools/"],
+                None,
+                True,
+            ),
         ]
 
         # Add semgrep only if config exists

specfact_cli/validators/schema.py

@@ -20,6 +20,13 @@ from specfact_cli.models.plan import PlanBundle
 from specfact_cli.models.protocol import Protocol
 
 
+# Try to use faster CLoader if available (C extension), fallback to SafeLoader
+try:
+    from yaml import CLoader as YamlLoader  # type: ignore[attr-defined]
+except ImportError:
+    from yaml import SafeLoader as YamlLoader  # type: ignore[assignment]
+
+
 class SchemaValidator:
     """Schema validator for plan bundles and protocols."""
 
@@ -141,8 +148,10 @@ def validate_plan_bundle(
     # Otherwise treat as path
     path = plan_or_path
     try:
-        with path.open("r") as f:
-            data = yaml.safe_load(f)
+        with path.open("r", encoding="utf-8") as f:
+            # Use CLoader for faster parsing (10-100x faster than SafeLoader)
+            # Falls back to SafeLoader if C extension not available
+            data = yaml.load(f, Loader=YamlLoader)  # type: ignore[arg-type]
 
         bundle = PlanBundle(**data)
         return True, None, bundle
@@ -180,8 +189,10 @@ def validate_protocol(protocol_or_path: Protocol | Path) -> ValidationReport | t
     # Otherwise treat as path
     path = protocol_or_path
     try:
-        with path.open("r") as f:
-            data = yaml.safe_load(f)
+        with path.open("r", encoding="utf-8") as f:
+            # Use CLoader for faster parsing (10-100x faster than SafeLoader)
+            # Falls back to SafeLoader if C extension not available
+            data = yaml.load(f, Loader=YamlLoader)  # type: ignore[arg-type]
 
         protocol = Protocol(**data)
         return True, None, protocol