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

specfact_cli/utils/acceptance_criteria.py

@@ -0,0 +1,127 @@
+"""
+Utility functions for validating and analyzing acceptance criteria.
+
+This module provides shared logic for detecting code-specific acceptance criteria
+to prevent false positives in ambiguity scanning and plan enrichment.
+"""
+
+from __future__ import annotations
+
+import re
+
+from beartype import beartype
+from icontract import ensure, require
+
+
+@beartype
+@require(lambda acceptance: isinstance(acceptance, str), "Acceptance must be string")
+@ensure(lambda result: isinstance(result, bool), "Must return bool")
+def is_code_specific_criteria(acceptance: str) -> bool:
+    """
+    Check if acceptance criteria are already code-specific (should not be replaced).
+
+    Code-specific criteria contain:
+    - Method signatures: method(), method(param: type)
+    - Class names: ClassName, ClassName.method()
+    - File paths: src/, path/to/file.py
+    - Type hints: : Path, : str, -> bool
+    - Specific return values: returns dict with 'key'
+    - Specific assertions: ==, in, >=, <=
+
+    Args:
+        acceptance: Acceptance criteria text to check
+
+    Returns:
+        True if criteria are code-specific, False if vague/generic
+    """
+    acceptance_lower = acceptance.lower()
+
+    # FIRST: Check for generic placeholders that indicate non-code-specific
+    # If found, return False immediately (don't enrich)
+    generic_placeholders = [
+        "interact with the system",
+        "perform the action",
+        "access the system",
+        "works correctly",
+        "works as expected",
+        "is functional and verified",
+    ]
+
+    if any(placeholder in acceptance_lower for placeholder in generic_placeholders):
+        return False
+
+    # SECOND: Check for vague patterns that should be enriched
+    # Use word boundaries to avoid false positives (e.g., "works" in "workspace")
+    vague_patterns = [
+        r"\bis\s+implemented\b",
+        r"\bis\s+functional\b",
+        r"\bworks\b",  # Word boundary prevents matching "workspace", "framework", etc.
+        r"\bis\s+done\b",
+        r"\bis\s+complete\b",
+        r"\bis\s+ready\b",
+    ]
+    if any(re.search(pattern, acceptance_lower) for pattern in vague_patterns):
+        return False  # Not code-specific, should be enriched
+
+    # THIRD: Check for code-specific indicators
+    code_specific_patterns = [
+        # Method signatures with parentheses
+        r"\([^)]*\)",  # method() or method(param)
+        r":\s*(path|str|int|bool|dict|list|tuple|set|float|bytes|any|none)",  # Type hints
+        r"->\s*(path|str|int|bool|dict|list|tuple|set|float|bytes|any|none)",  # Return type hints
+        # File paths
+        r"src/",
+        r"tests/",
+        r"\.py",
+        r"\.yaml",
+        r"\.json",
+        # Class names (PascalCase with method/dot, or in specific contexts)
+        r"[A-Z][a-zA-Z0-9]*\.",
+        r"[A-Z][a-zA-Z0-9]*\(",
+        r"returns\s+[A-Z][a-zA-Z0-9]{3,}\b",  # Returns ClassName (4+ chars)
+        r"instance\s+of\s+[A-Z][a-zA-Z0-9]{3,}\b",  # instance of ClassName
+        r"\b[A-Z][a-zA-Z0-9]{4,}\b",  # Standalone class names (5+ chars, PascalCase) - avoids common words
+        # Specific assertions
+        r"==\s*['\"]",
+        r"in\s*\(",
+        r">=\s*\d",
+        r"<=\s*\d",
+        r"returns\s+(dict|list|tuple|set|str|int|bool|float)\s+with",
+        r"returns\s+[A-Z][a-zA-Z0-9]*",  # Returns a class instance
+        # NetworkX, Path.resolve(), etc.
+        r"nx\.",
+        r"Path\.",
+        r"resolve\(\)",
+        # Version strings, specific values
+        r"version\s*=\s*['\"]",
+        r"version\s*==\s*['\"]",
+    ]
+
+    for pattern in code_specific_patterns:
+        if re.search(pattern, acceptance, re.IGNORECASE):
+            # Verify match is not a common word
+            matches = re.findall(pattern, acceptance, re.IGNORECASE)
+            common_words = [
+                "given",
+                "when",
+                "then",
+                "user",
+                "system",
+                "developer",
+                "they",
+                "the",
+                "with",
+                "from",
+                "that",
+            ]
+            # Filter out common words from matches
+            if isinstance(matches, list):
+                actual_matches = [m for m in matches if isinstance(m, str) and m.lower() not in common_words]
+            else:
+                actual_matches = [matches] if isinstance(matches, str) and matches.lower() not in common_words else []
+
+            if actual_matches:
+                return True
+
+    # If no code-specific patterns found, it's not code-specific
+    return False

specfact_cli/utils/enrichment_parser.py

@@ -0,0 +1,445 @@
+"""
+Enrichment parser for LLM-generated enrichment reports.
+
+This module parses Markdown enrichment reports generated by LLMs during
+the dual-stack enrichment workflow and applies them to plan bundles.
+"""
+
+from __future__ import annotations
+
+import re
+from contextlib import suppress
+from pathlib import Path
+from typing import Any
+
+from beartype import beartype
+from icontract import ensure, require
+
+from specfact_cli.models.plan import Feature, PlanBundle, Story
+
+
+class EnrichmentReport:
+    """Parsed enrichment report from LLM."""
+
+    def __init__(self) -> None:
+        """Initialize empty enrichment report."""
+        self.missing_features: list[dict[str, Any]] = []
+        self.confidence_adjustments: dict[str, float] = {}
+        self.business_context: dict[str, list[str]] = {
+            "priorities": [],
+            "constraints": [],
+            "unknowns": [],
+        }
+
+    @beartype
+    @require(lambda feature: isinstance(feature, dict), "Feature must be dictionary")
+    def add_missing_feature(self, feature: dict[str, Any]) -> None:
+        """Add a missing feature discovered by LLM."""
+        self.missing_features.append(feature)
+
+    @beartype
+    @require(lambda feature_key: isinstance(feature_key, str), "Feature key must be string")
+    @require(lambda confidence: 0.0 <= confidence <= 1.0, "Confidence must be 0.0-1.0")
+    def adjust_confidence(self, feature_key: str, confidence: float) -> None:
+        """Adjust confidence score for a feature."""
+        self.confidence_adjustments[feature_key] = confidence
+
+    @beartype
+    @require(lambda category: isinstance(category, str), "Category must be string")
+    @require(lambda items: isinstance(items, list), "Items must be list")
+    def add_business_context(self, category: str, items: list[str]) -> None:
+        """Add business context items."""
+        if category in self.business_context:
+            self.business_context[category].extend(items)
+
+
+class EnrichmentParser:
+    """Parser for Markdown enrichment reports."""
+
+    @beartype
+    @require(
+        lambda report_path: isinstance(report_path, (Path, str)) and bool(str(report_path).strip()),
+        "Report path must be non-empty Path or str",
+    )
+    @ensure(lambda result: isinstance(result, EnrichmentReport), "Must return EnrichmentReport")
+    def parse(self, report_path: Path | str) -> EnrichmentReport:
+        """
+        Parse Markdown enrichment report.
+
+        Args:
+            report_path: Path to Markdown enrichment report (must be non-empty)
+
+        Returns:
+            Parsed EnrichmentReport
+
+        Raises:
+            FileNotFoundError: If report file doesn't exist
+            ValueError: If report_path is empty or invalid
+        """
+        report_path = Path(report_path)
+        if not str(report_path).strip():
+            raise ValueError("Report path cannot be empty")
+        if not report_path.exists():
+            raise FileNotFoundError(f"Enrichment report not found: {report_path}")
+        if report_path.is_dir():
+            raise ValueError(f"Report path must be a file, not a directory: {report_path}")
+
+        content = report_path.read_text(encoding="utf-8")
+        report = EnrichmentReport()
+
+        # Parse missing features section
+        self._parse_missing_features(content, report)
+
+        # Parse confidence adjustments section
+        self._parse_confidence_adjustments(content, report)
+
+        # Parse business context section
+        self._parse_business_context(content, report)
+
+        return report
+
+    @beartype
+    @require(lambda content: isinstance(content, str), "Content must be string")
+    @require(lambda report: isinstance(report, EnrichmentReport), "Report must be EnrichmentReport")
+    def _parse_missing_features(self, content: str, report: EnrichmentReport) -> None:
+        """Parse missing features section from enrichment report."""
+        # Look for "Missing Features" or "Missing features" section
+        pattern = r"##\s*(?:Missing\s+)?Features?\s*(?:\(.*?\))?\s*\n(.*?)(?=##|\Z)"
+        match = re.search(pattern, content, re.IGNORECASE | re.DOTALL)
+        if not match:
+            return
+
+        section = match.group(1)
+
+        # Extract individual features (numbered or bulleted)
+        feature_pattern = r"(?:^|\n)(?:\d+\.|\*|\-)\s*(.+?)(?=\n(?:^\d+\.|\*|\-|\Z))"
+        features = re.findall(feature_pattern, section, re.MULTILINE | re.DOTALL)
+
+        for feature_text in features:
+            feature = self._parse_feature_block(feature_text)
+            if feature:
+                report.add_missing_feature(feature)
+
+    @beartype
+    @require(lambda feature_text: isinstance(feature_text, str), "Feature text must be string")
+    @ensure(lambda result: result is None or isinstance(result, dict), "Must return None or dict")
+    def _parse_feature_block(self, feature_text: str) -> dict[str, Any] | None:
+        """Parse a single feature block from enrichment report."""
+        feature: dict[str, Any] = {
+            "key": "",
+            "title": "",
+            "confidence": 0.5,
+            "outcomes": [],
+            "stories": [],
+        }
+
+        # Extract key (e.g., "FEATURE-IDEINTEGRATION" or "Suggested key: FEATURE-IDEINTEGRATION")
+        key_match = re.search(r"(?:key|Key):\s*([A-Z0-9_-]+)", feature_text, re.IGNORECASE)
+        if key_match:
+            feature["key"] = key_match.group(1)
+        else:
+            # Try to extract from title
+            title_match = re.search(r"^\*\*([^*]+)\*\*", feature_text, re.MULTILINE)
+            if title_match:
+                # Generate key from title
+                title = title_match.group(1).strip()
+                feature["title"] = title
+                feature["key"] = f"FEATURE-{title.upper().replace(' ', '').replace('-', '')[:20]}"
+
+        # Extract title
+        if not feature["title"]:
+            title_match = re.search(r"(?:title|Title):\s*(.+?)(?:\n|$)", feature_text, re.IGNORECASE)
+            if title_match:
+                feature["title"] = title_match.group(1).strip()
+
+        # Extract confidence
+        confidence_match = re.search(r"(?:confidence|Confidence):\s*([0-9.]+)", feature_text, re.IGNORECASE)
+        if confidence_match:
+            with suppress(ValueError):
+                feature["confidence"] = float(confidence_match.group(1))
+
+        # Extract outcomes
+        outcomes_match = re.search(
+            r"(?:outcomes?|Outcomes?):\s*(.+?)(?:\n(?:stories?|Stories?)|$)", feature_text, re.IGNORECASE | re.DOTALL
+        )
+        if outcomes_match:
+            outcomes_text = outcomes_match.group(1)
+            # Split by lines or bullets
+            outcomes = [o.strip() for o in re.split(r"\n|,", outcomes_text) if o.strip()]
+            feature["outcomes"] = outcomes
+
+        # Extract business value or reason
+        reason_match = re.search(
+            r"(?:reason|Reason|Business value):\s*(.+?)(?:\n(?:stories?|Stories?)|$)",
+            feature_text,
+            re.IGNORECASE | re.DOTALL,
+        )
+        if reason_match:
+            reason = reason_match.group(1).strip()
+            if reason and reason not in feature["outcomes"]:
+                feature["outcomes"].append(reason)
+
+        # Extract stories (REQUIRED for features to pass promotion validation)
+        stories_match = re.search(
+            r"(?:stories?|Stories?):\s*(.+?)(?:\n(?:##|$))", feature_text, re.IGNORECASE | re.DOTALL
+        )
+        if stories_match:
+            stories_text = stories_match.group(1)
+            stories = self._parse_stories_from_text(stories_text, feature.get("key", ""))
+            feature["stories"] = stories
+
+        # Only return if we have at least a key or title
+        if feature["key"] or feature["title"]:
+            return feature
+
+        return None
+
+    @beartype
+    @require(lambda stories_text: isinstance(stories_text, str), "Stories text must be string")
+    @require(lambda feature_key: isinstance(feature_key, str), "Feature key must be string")
+    @ensure(lambda result: isinstance(result, list), "Must return list of story dicts")
+    def _parse_stories_from_text(self, stories_text: str, feature_key: str) -> list[dict[str, Any]]:
+        """Parse stories from enrichment report text."""
+        stories: list[dict[str, Any]] = []
+
+        # Extract individual stories (numbered, bulleted, or sub-headers)
+        # Pattern matches: "1. Story title", "- Story title", "### Story title", etc.
+        story_pattern = r"(?:^|\n)(?:(?:\d+\.|\*|\-|\#\#\#)\s*)?(.+?)(?=\n(?:^\d+\.|\*|\-|\#\#\#|\Z))"
+        story_matches = re.findall(story_pattern, stories_text, re.MULTILINE | re.DOTALL)
+
+        for idx, story_text in enumerate(story_matches, start=1):
+            story = self._parse_story_block(story_text, feature_key, idx)
+            if story:
+                stories.append(story)
+
+        return stories
+
+    @beartype
+    @require(lambda story_text: isinstance(story_text, str), "Story text must be string")
+    @require(lambda feature_key: isinstance(feature_key, str), "Feature key must be string")
+    @require(
+        lambda story_number: isinstance(story_number, int) and story_number > 0, "Story number must be positive int"
+    )
+    @ensure(lambda result: result is None or isinstance(result, dict), "Must return None or story dict")
+    def _parse_story_block(self, story_text: str, feature_key: str, story_number: int) -> dict[str, Any] | None:
+        """Parse a single story block from enrichment report."""
+        story: dict[str, Any] = {
+            "key": "",
+            "title": "",
+            "acceptance": [],
+            "story_points": None,
+            "value_points": None,
+            "tasks": [],
+            "confidence": 0.8,
+        }
+
+        # Generate story key from feature key and number
+        if feature_key:
+            # Extract base from feature key (e.g., "FEATURE-DUALSTACK" -> "DUALSTACK")
+            base = feature_key.replace("FEATURE-", "").upper()
+            story["key"] = f"STORY-{base}-{story_number:03d}"
+        else:
+            story["key"] = f"STORY-{story_number:03d}"
+
+        # Extract title (first line or after "Title:")
+        title_match = re.search(r"(?:title|Title):\s*(.+?)(?:\n|$)", story_text, re.IGNORECASE)
+        if title_match:
+            story["title"] = title_match.group(1).strip()
+        else:
+            # Use first line as title
+            first_line = story_text.split("\n")[0].strip()
+            if first_line and not first_line.startswith("#"):
+                story["title"] = first_line
+
+        # Extract acceptance criteria
+        acceptance_match = re.search(
+            r"(?:acceptance|Acceptance|criteria|Criteria):\s*(.+?)(?:\n(?:tasks?|Tasks?|points?|Points?)|$)",
+            story_text,
+            re.IGNORECASE | re.DOTALL,
+        )
+        if acceptance_match:
+            acceptance_text = acceptance_match.group(1)
+            acceptance = [a.strip() for a in re.split(r"\n|,", acceptance_text) if a.strip()]
+            story["acceptance"] = acceptance
+        else:
+            # Default acceptance if none found
+            story["acceptance"] = [f"{story.get('title', 'Story')} works as expected"]
+
+        # Extract tasks
+        tasks_match = re.search(
+            r"(?:tasks?|Tasks?):\s*(.+?)(?:\n(?:points?|Points?|$))", story_text, re.IGNORECASE | re.DOTALL
+        )
+        if tasks_match:
+            tasks_text = tasks_match.group(1)
+            tasks = [t.strip() for t in re.split(r"\n|,", tasks_text) if t.strip()]
+            story["tasks"] = tasks
+
+        # Extract story points
+        story_points_match = re.search(r"(?:story\s+points?|Story\s+Points?):\s*(\d+)", story_text, re.IGNORECASE)
+        if story_points_match:
+            with suppress(ValueError):
+                story["story_points"] = int(story_points_match.group(1))
+
+        # Extract value points
+        value_points_match = re.search(r"(?:value\s+points?|Value\s+Points?):\s*(\d+)", story_text, re.IGNORECASE)
+        if value_points_match:
+            with suppress(ValueError):
+                story["value_points"] = int(value_points_match.group(1))
+
+        # Only return if we have at least a title
+        if story["title"]:
+            return story
+
+        return None
+
+    @beartype
+    @require(lambda content: isinstance(content, str), "Content must be string")
+    @require(lambda report: isinstance(report, EnrichmentReport), "Report must be EnrichmentReport")
+    def _parse_confidence_adjustments(self, content: str, report: EnrichmentReport) -> None:
+        """Parse confidence adjustments section from enrichment report."""
+        # Look for "Confidence Adjustments" or "Confidence adjustments" section
+        pattern = r"##\s*Confidence\s+Adjustments?\s*\n(.*?)(?=##|\Z)"
+        match = re.search(pattern, content, re.IGNORECASE | re.DOTALL)
+        if not match:
+            return
+
+        section = match.group(1)
+
+        # Extract adjustments (format: "FEATURE-KEY → 0.95" or "FEATURE-KEY: 0.95")
+        adjustment_pattern = r"([A-Z0-9_-]+)\s*(?:→|:)\s*([0-9.]+)"
+        adjustments = re.findall(adjustment_pattern, section, re.IGNORECASE)
+
+        for feature_key, confidence_str in adjustments:
+            try:
+                confidence = float(confidence_str)
+                if 0.0 <= confidence <= 1.0:
+                    report.adjust_confidence(feature_key.upper(), confidence)
+            except ValueError:
+                pass
+
+    @beartype
+    @require(lambda content: isinstance(content, str), "Content must be string")
+    @require(lambda report: isinstance(report, EnrichmentReport), "Report must be EnrichmentReport")
+    def _parse_business_context(self, content: str, report: EnrichmentReport) -> None:
+        """Parse business context section from enrichment report."""
+        # Look for "Business Context" section
+        pattern = r"##\s*Business\s+Context\s*\n(.*?)(?=##|\Z)"
+        match = re.search(pattern, content, re.IGNORECASE | re.DOTALL)
+        if not match:
+            return
+
+        section = match.group(1)
+
+        # Extract priorities
+        priorities_match = re.search(
+            r"(?:Priorities?|Priority):\s*(.+?)(?:\n(?:Constraints?|Unknowns?)|$)", section, re.IGNORECASE | re.DOTALL
+        )
+        if priorities_match:
+            priorities_text = priorities_match.group(1)
+            priorities = [
+                p.strip() for p in re.split(r"\n|,", priorities_text) if p.strip() and not p.strip().startswith("-")
+            ]
+            report.add_business_context("priorities", priorities)
+
+        # Extract constraints
+        constraints_match = re.search(
+            r"(?:Constraints?|Constraint):\s*(.+?)(?:\n(?:Unknowns?|Priorities?)|$)", section, re.IGNORECASE | re.DOTALL
+        )
+        if constraints_match:
+            constraints_text = constraints_match.group(1)
+            constraints = [
+                c.strip() for c in re.split(r"\n|,", constraints_text) if c.strip() and not c.strip().startswith("-")
+            ]
+            report.add_business_context("constraints", constraints)
+
+        # Extract unknowns
+        unknowns_match = re.search(
+            r"(?:Unknowns?|Unknown):\s*(.+?)(?:\n(?:Priorities?|Constraints?)|$)", section, re.IGNORECASE | re.DOTALL
+        )
+        if unknowns_match:
+            unknowns_text = unknowns_match.group(1)
+            unknowns = [
+                u.strip() for u in re.split(r"\n|,", unknowns_text) if u.strip() and not u.strip().startswith("-")
+            ]
+            report.add_business_context("unknowns", unknowns)
+
+
+@beartype
+@require(lambda plan_bundle: isinstance(plan_bundle, PlanBundle), "Plan bundle must be PlanBundle")
+@require(lambda enrichment: isinstance(enrichment, EnrichmentReport), "Enrichment must be EnrichmentReport")
+@ensure(lambda result: isinstance(result, PlanBundle), "Must return PlanBundle")
+def apply_enrichment(plan_bundle: PlanBundle, enrichment: EnrichmentReport) -> PlanBundle:
+    """
+    Apply enrichment report to plan bundle.
+
+    Args:
+        plan_bundle: Original plan bundle from CLI
+        enrichment: Parsed enrichment report
+
+    Returns:
+        Enriched plan bundle
+    """
+    # Create a copy to avoid mutating the original
+    enriched = plan_bundle.model_copy(deep=True)
+
+    # Apply confidence adjustments
+    feature_keys = {f.key: i for i, f in enumerate(enriched.features)}
+    for feature_key, new_confidence in enrichment.confidence_adjustments.items():
+        if feature_key in feature_keys:
+            enriched.features[feature_keys[feature_key]].confidence = new_confidence
+
+    # Add missing features
+    for missing_feature_data in enrichment.missing_features:
+        # Check if feature already exists
+        feature_key = missing_feature_data.get("key", "")
+        if feature_key and feature_key in feature_keys:
+            # Update existing feature instead of adding duplicate
+            existing_idx = feature_keys[feature_key]
+            existing_feature = enriched.features[existing_idx]
+            # Update confidence if provided
+            if "confidence" in missing_feature_data:
+                existing_feature.confidence = missing_feature_data["confidence"]
+            # Merge outcomes
+            if "outcomes" in missing_feature_data:
+                for outcome in missing_feature_data["outcomes"]:
+                    if outcome not in existing_feature.outcomes:
+                        existing_feature.outcomes.append(outcome)
+        else:
+            # Create new feature with stories (if provided)
+            stories_data = missing_feature_data.get("stories", [])
+            stories: list[Story] = []
+            for story_data in stories_data:
+                if isinstance(story_data, dict):
+                    story = Story(
+                        key=story_data.get("key", f"STORY-{len(stories) + 1:03d}"),
+                        title=story_data.get("title", "Untitled Story"),
+                        acceptance=story_data.get("acceptance", []),
+                        story_points=story_data.get("story_points"),
+                        value_points=story_data.get("value_points"),
+                        tasks=story_data.get("tasks", []),
+                        confidence=story_data.get("confidence", 0.8),
+                        draft=False,
+                        scenarios=None,
+                        contracts=None,
+                    )
+                    stories.append(story)
+
+            feature = Feature(
+                key=missing_feature_data.get("key", f"FEATURE-{len(enriched.features) + 1:03d}"),
+                title=missing_feature_data.get("title", "Untitled Feature"),
+                outcomes=missing_feature_data.get("outcomes", []),
+                acceptance=[],
+                constraints=[],
+                stories=stories,  # Include parsed stories
+                confidence=missing_feature_data.get("confidence", 0.5),
+                draft=False,
+            )
+            enriched.features.append(feature)
+
+    # Apply business context to idea if present
+    if enriched.idea and enrichment.business_context and enrichment.business_context.get("constraints"):
+        if enriched.idea.constraints is None:
+            enriched.idea.constraints = []
+        enriched.idea.constraints.extend(enrichment.business_context["constraints"])
+
+    return enriched

specfact_cli/utils/feature_keys.py

@@ -21,12 +21,14 @@ def normalize_feature_key(key: str) -> str:
     - `FEATURE-CONTRACTFIRSTTESTMANAGER` -> `CONTRACTFIRSTTESTMANAGER`
     - `FEATURE-001` -> `001`
     - `CONTRACT_FIRST_TEST_MANAGER` -> `CONTRACTFIRSTTESTMANAGER`
+    - `041-ide-integration-system` -> `IDEINTEGRATIONSYSTEM`
+    - `047-ide-integration-system` -> `IDEINTEGRATIONSYSTEM` (same as above)
 
     Args:
         key: Feature key in any format
 
     Returns:
-        Normalized key (uppercase, no prefixes, no underscores)
+        Normalized key (uppercase, no prefixes, no underscores, no hyphens)
 
     Examples:
         >>> normalize_feature_key("000_CONTRACT_FIRST_TEST_MANAGER")
@@ -35,9 +37,16 @@ def normalize_feature_key(key: str) -> str:
         'CONTRACTFIRSTTESTMANAGER'
         >>> normalize_feature_key("FEATURE-001")
         '001'
+        >>> normalize_feature_key("041-ide-integration-system")
+        'IDEINTEGRATIONSYSTEM'
     """
-    # Remove common prefixes
-    key = key.replace("FEATURE-", "").replace("000_", "").replace("001_", "")
+    # Remove common prefixes (FEATURE-, and numbered prefixes like 000_, 001_, 002_, etc.)
+    key = key.replace("FEATURE-", "")
+    # Remove numbered prefixes with underscores (000_, 001_, 002_, ..., 999_)
+    key = re.sub(r"^\d{3}_", "", key)
+    # Remove numbered prefixes with hyphens (000-, 001-, 002-, ..., 999-)
+    # This handles Spec-Kit directory format like "041-ide-integration-system"
+    key = re.sub(r"^\d{3}-", "", key)
 
     # Remove underscores and spaces, convert to uppercase
     return re.sub(r"[_\s-]", "", key).upper()