ref-agents 1.0.0__py3-none-any.whl

ref_agents/tools/hierarchy_manager.py

@@ -0,0 +1,289 @@
+"""Hierarchy manager for Epic → Feature → Story structure."""
+
+from pathlib import Path
+from typing import Optional
+
+import structlog
+
+from ref_agents.models.hierarchy import Epic, Feature, Story
+from ref_agents.tools.requirements_serializer import (
+    epic_to_json,
+    feature_to_json,
+    story_to_json,
+)
+from ref_agents.tools.json_output import generate_json_output
+
+logger = structlog.get_logger(__name__)
+
+
+def create_epic(
+    epic_id: str,
+    title: str,
+    description: str = "",
+    requirements_dir: Path | None = None,
+) -> Epic:
+    """Create a new epic.
+
+    Args:
+        epic_id: Epic identifier (e.g., EPIC-001)
+        title: Epic title
+        description: Epic description
+        requirements_dir: Directory for requirements. Defaults to docs/requirements.
+
+    Returns:
+        Created Epic model
+    """
+    if requirements_dir is None:
+        requirements_dir = Path("docs/requirements")
+
+    epic = Epic(epic_id=epic_id, title=title, description=description)
+
+    # Write markdown file
+    epic_path = requirements_dir / f"{epic_id}.md"
+    epic_path.parent.mkdir(parents=True, exist_ok=True)
+    epic_path.write_text(_epic_to_markdown(epic), encoding="utf-8")
+
+    # Auto-generate JSON
+    epic_data = epic.to_dict()
+    generate_json_output("epic", epic_data, epic_path)
+
+    logger.info("Epic created", epic_id=epic_id, path=str(epic_path))
+
+    return epic
+
+
+def create_feature(  # noqa: PLR0913  # TECH_DEBT: refactor to TypedDict — STORY-046
+    feature_id: str,
+    epic_id: str,
+    title: str,
+    description: str = "",
+    requirements_dir: Path | None = None,
+) -> Feature:
+    """Create a new feature under an epic.
+
+    Args:
+        feature_id: Feature identifier (e.g., FEAT-001)
+        epic_id: Parent epic identifier
+        title: Feature title
+        description: Feature description
+        requirements_dir: Directory for requirements. Defaults to docs/requirements.
+
+    Returns:
+        Created Feature model
+    """
+    if requirements_dir is None:
+        requirements_dir = Path("docs/requirements")
+
+    feature = Feature(
+        feature_id=feature_id,
+        epic_id=epic_id,
+        title=title,
+        description=description,
+    )
+
+    # Write markdown file
+    feature_path = requirements_dir / f"{feature_id}.md"
+    feature_path.parent.mkdir(parents=True, exist_ok=True)
+    feature_path.write_text(_feature_to_markdown(feature), encoding="utf-8")
+
+    # Auto-generate JSON
+    feature_data = feature.to_dict()
+    generate_json_output("feature", feature_data, feature_path)
+
+    logger.info(
+        "Feature created",
+        feature_id=feature_id,
+        epic_id=epic_id,
+        path=str(feature_path),
+    )
+
+    return feature
+
+
+def create_story(  # noqa: PLR0913  # TECH_DEBT: refactor to TypedDict — STORY-046
+    story_id: str,
+    title: str,
+    user_story: str,
+    epic_id: Optional[str] = None,
+    feature_id: Optional[str] = None,
+    description: str = "",
+    requirements_dir: Path | None = None,
+    requirements_text: str = "",
+) -> Story:
+    """Create a new story (can be flat or hierarchical).
+
+    Args:
+        story_id: Story identifier (e.g., STORY-001)
+        title: Story title
+        user_story: User story text (As a... I want... So that...)
+        epic_id: Optional parent epic identifier
+        feature_id: Optional parent feature identifier
+        description: Story description
+        requirements_dir: Directory for requirements. Defaults to docs/requirements.
+        requirements_text: Raw requirements text from terminal/chat. Appended under
+            "## Raw Requirements" when provided — normalises inline input to disk.
+
+    Returns:
+        Created Story model
+    """
+    if requirements_dir is None:
+        requirements_dir = Path("docs/requirements")
+
+    story = Story(
+        story_id=story_id,
+        title=title,
+        user_story=user_story,
+        epic_id=epic_id,
+        feature_id=feature_id,
+        description=description,
+    )
+
+    # Write markdown file
+    story_path = requirements_dir / f"{story_id}.md"
+    story_path.parent.mkdir(parents=True, exist_ok=True)
+    markdown = _story_to_markdown(story)
+    if requirements_text:
+        markdown += "\n\n## Raw Requirements\n\n" + requirements_text
+    story_path.write_text(markdown, encoding="utf-8")
+
+    # Auto-generate JSON
+    story_data = story.to_dict()
+    generate_json_output("story", story_data, story_path)
+
+    logger.info(
+        "Story created",
+        story_id=story_id,
+        epic_id=epic_id,
+        feature_id=feature_id,
+        path=str(story_path),
+    )
+
+    return story
+
+
+def get_epic(epic_id: str, requirements_dir: Path | None = None) -> Optional[Epic]:
+    """Get an epic by ID.
+
+    Args:
+        epic_id: Epic identifier
+        requirements_dir: Directory for requirements
+
+    Returns:
+        Epic model if found, None otherwise
+    """
+    if requirements_dir is None:
+        requirements_dir = Path("docs/requirements")
+
+    epic_path = requirements_dir / f"{epic_id}.md"
+    if not epic_path.exists():
+        return None
+
+    epic_data = epic_to_json(epic_path)
+    return Epic(**epic_data)
+
+
+def get_feature(
+    feature_id: str, requirements_dir: Path | None = None
+) -> Optional[Feature]:
+    """Get a feature by ID.
+
+    Args:
+        feature_id: Feature identifier
+        requirements_dir: Directory for requirements
+
+    Returns:
+        Feature model if found, None otherwise
+    """
+    if requirements_dir is None:
+        requirements_dir = Path("docs/requirements")
+
+    feature_path = requirements_dir / f"{feature_id}.md"
+    if not feature_path.exists():
+        return None
+
+    feature_data = feature_to_json(feature_path)
+    return Feature(**feature_data)
+
+
+def get_story(story_id: str, requirements_dir: Path | None = None) -> Optional[Story]:
+    """Get a story by ID.
+
+    Args:
+        story_id: Story identifier
+        requirements_dir: Directory for requirements
+
+    Returns:
+        Story model if found, None otherwise
+    """
+    if requirements_dir is None:
+        requirements_dir = Path("docs/requirements")
+
+    story_path = requirements_dir / f"{story_id}.md"
+    if not story_path.exists():
+        return None
+
+    story_data = story_to_json(story_path)
+    return Story(**story_data)
+
+
+def _epic_to_markdown(epic: Epic) -> str:
+    """Convert epic to markdown format."""
+    lines = [
+        f"# Epic: [{epic.epic_id}] {epic.title}",
+        "",
+        f"**Status:** {epic.status}",
+        "",
+        "## Description",
+        "",
+        epic.description or "",
+    ]
+    return "\n".join(lines)
+
+
+def _feature_to_markdown(feature: Feature) -> str:
+    """Convert feature to markdown format."""
+    lines = [
+        f"# Feature: [{feature.feature_id}] {feature.title}",
+        "",
+        f"**Epic:** {feature.epic_id}",
+        f"**Status:** {feature.status}",
+        "",
+        "## Description",
+        "",
+        feature.description or "",
+    ]
+    return "\n".join(lines)
+
+
+def _story_to_markdown(story: Story) -> str:
+    """Convert story to markdown format."""
+    lines = [
+        f"# Requirement: [{story.story_id}] {story.title}",
+        "",
+        f"**Status:** {story.status}",
+        f"**Priority:** {story.priority}",
+    ]
+
+    if story.epic_id:
+        lines.append(f"**Epic:** {story.epic_id}")
+    if story.feature_id:
+        lines.append(f"**Feature:** {story.feature_id}")
+
+    lines.extend(
+        [
+            "",
+            "## User Story",
+            "",
+            story.user_story or "",
+            "",
+            "## Description",
+            "",
+            story.description or "",
+            "",
+            "## Acceptance Criteria",
+            "",
+            "*Acceptance criteria will be added here*",
+        ]
+    )
+
+    return "\n".join(lines)

ref_agents/tools/invest_scorer.py

@@ -0,0 +1,249 @@
+"""INVEST scoring tool for user story quality assessment."""
+
+from typing import Optional
+
+import structlog
+
+from ref_agents.models.invest import INVESTScores
+
+logger = structlog.get_logger(__name__)
+
+
+def score_invest_principles(
+    user_story: str,
+    acceptance_criteria: list[str],
+    description: Optional[str] = None,
+) -> INVESTScores:
+    """Score a user story against INVEST principles.
+
+    Args:
+        user_story: User story text (As a... I want... So that...)
+        acceptance_criteria: List of acceptance criteria (Gherkin format preferred)
+        description: Optional story description
+
+    Returns:
+        INVESTScores with 0-5 scores for each principle
+    """
+    story_text = f"{user_story} {description or ''} {' '.join(acceptance_criteria)}"
+
+    # Independent: Check for dependencies, blockers, prerequisites
+    independent_score = _score_independent(story_text, acceptance_criteria)
+
+    # Negotiable: Check for specific implementation details (should be absent)
+    negotiable_score = _score_negotiable(story_text)
+
+    # Valuable: Check for value statement ("So that...")
+    valuable_score = _score_valuable(user_story, description)
+
+    # Estimable: Check for clear AC, testable criteria
+    estimable_score = _score_estimable(acceptance_criteria)
+
+    # Small: Check story size (AC count, complexity indicators)
+    small_score = _score_small(acceptance_criteria, story_text)
+
+    # Testable: Check for Gherkin format, binary pass/fail criteria
+    testable_score = _score_testable(acceptance_criteria)
+
+    return INVESTScores(
+        independent=independent_score,
+        negotiable=negotiable_score,
+        valuable=valuable_score,
+        estimable=estimable_score,
+        small=small_score,
+        testable=testable_score,
+    )
+
+
+def _score_by_keyword_count(
+    text: str, keywords: list[str], reverse: bool = False
+) -> int:
+    """Score based on keyword count in text.
+
+    Args:
+        text: Text to analyze
+        keywords: Keywords to search for
+        reverse: If True, higher count = higher score (default: False, higher count = lower score)
+
+    Returns:
+        Score 0-5 based on keyword count
+    """
+    text_lower = text.lower()
+    count = sum(1 for kw in keywords if kw in text_lower)
+
+    if reverse:
+        # Higher count = higher score
+        if count == 0:
+            return 1
+        elif count == 1:
+            return 2
+        elif count == 2:  # noqa: PLR2004  # TECH_DEBT: extract to named constant — G25
+            return 3
+        elif count <= 3:  # noqa: PLR2004  # TECH_DEBT: extract to named constant — G25
+            return 4
+        else:
+            return 5
+    else:
+        # Higher count = lower score
+        if count == 0:
+            return 5
+        elif count == 1:
+            return 4
+        elif count == 2:  # noqa: PLR2004  # TECH_DEBT: extract to named constant — G25
+            return 3
+        elif count <= 3:  # noqa: PLR2004  # TECH_DEBT: extract to named constant — G25
+            return 2
+        else:
+            return 1
+
+
+def _score_independent(story_text: str, acceptance_criteria: list[str]) -> int:
+    """Score Independent principle (0-5).
+
+    Lower score if story mentions dependencies, blockers, or prerequisites.
+
+    Args:
+        story_text: Story text to analyze
+        acceptance_criteria: Acceptance criteria (unused, kept for API consistency)
+    """
+    dependency_keywords = [
+        "depends on",
+        "requires",
+        "blocked by",
+        "must complete first",
+        "prerequisite",
+        "after",
+        "before",
+    ]
+    _ = acceptance_criteria  # Unused but kept for API consistency
+    return _score_by_keyword_count(story_text, dependency_keywords, reverse=False)
+
+
+def _score_negotiable(story_text: str) -> int:
+    """Score Negotiable principle (0-5).
+
+    Lower score if story contains specific implementation details.
+    """
+    implementation_keywords = [
+        "must use",
+        "must implement",
+        "exactly",
+        "specifically",
+        "only",
+        "cannot use",
+        "forbidden",
+    ]
+    return _score_by_keyword_count(story_text, implementation_keywords, reverse=False)
+
+
+def _score_valuable(user_story: str, description: Optional[str] = None) -> int:
+    """Score Valuable principle (0-5).
+
+    Higher score if "So that..." clause is present and clear.
+    """
+    text = f"{user_story} {description or ''}"
+    text_lower = text.lower()
+
+    # Check for value statement
+    if "so that" in text_lower:
+        # Check if value is specific (not generic)
+        generic_values = ["better", "good", "nice", "improve"]
+        has_generic = any(gv in text_lower for gv in generic_values)
+
+        if not has_generic:
+            return 5
+        else:
+            return 3
+    else:
+        return 2
+
+
+def _count_matches_in_list(items: list[str], keywords: list[str]) -> int:
+    """Count items that contain any of the keywords.
+
+    Args:
+        items: List of strings to search
+        keywords: Keywords to search for
+
+    Returns:
+        Count of items containing at least one keyword
+    """
+    return sum(
+        1 for item in items if any(keyword in item.lower() for keyword in keywords)
+    )
+
+
+def _score_estimable(acceptance_criteria: list[str]) -> int:
+    """Score Estimable principle (0-5).
+
+    Higher score if AC are clear, specific, and measurable.
+    """
+    if not acceptance_criteria:
+        return 1
+
+    # Check for specific, measurable criteria
+    specific_indicators = ["status:", "status code", "error", "timeout", "count"]
+    ambiguous_terms = ["fast", "quickly", "user-friendly", "easy", "intuitive"]
+
+    specific_count = _count_matches_in_list(acceptance_criteria, specific_indicators)
+    ambiguous_count = _count_matches_in_list(acceptance_criteria, ambiguous_terms)
+
+    if ambiguous_count > 0:
+        return max(1, 3 - ambiguous_count)
+    elif specific_count >= len(acceptance_criteria) * 0.5:
+        return 5
+    elif specific_count > 0:
+        return 4
+    else:
+        return 3
+
+
+def _score_small(acceptance_criteria: list[str], story_text: str) -> int:
+    """Score Small principle (0-5).
+
+    Higher score if story is appropriately sized (3-8 AC ideal).
+
+    Args:
+        acceptance_criteria: List of acceptance criteria
+        story_text: Story text (unused, kept for API consistency)
+    """
+    ac_count = len(acceptance_criteria)
+    _ = story_text  # Unused but kept for API consistency
+
+    # Ideal: 3-8 AC
+    if 3 <= ac_count <= 8:  # noqa: PLR2004  # TECH_DEBT: extract to named constant — G25
+        return 5
+    elif ac_count == 2 or ac_count == 9:  # noqa: PLR2004  # TECH_DEBT: extract to named constant — G25
+        return 4
+    elif ac_count == 1 or ac_count == 10:  # noqa: PLR2004  # TECH_DEBT: extract to named constant — G25
+        return 3
+    elif ac_count == 0:
+        return 1
+    elif ac_count > 10:  # noqa: PLR2004  # TECH_DEBT: extract to named constant — G25
+        return 2
+    else:
+        return 4
+
+
+def _score_testable(acceptance_criteria: list[str]) -> int:
+    """Score Testable principle (0-5).
+
+    Higher score if AC use Gherkin format and are binary (pass/fail).
+    """
+    if not acceptance_criteria:
+        return 1
+
+    gherkin_keywords = ["given", "when", "then", "and", "but"]
+    gherkin_count = _count_matches_in_list(acceptance_criteria, gherkin_keywords)
+
+    gherkin_ratio = gherkin_count / len(acceptance_criteria)
+
+    if gherkin_ratio >= 0.8:  # noqa: PLR2004  # TECH_DEBT: extract to named constant — G25
+        return 5
+    elif gherkin_ratio >= 0.6:  # noqa: PLR2004  # TECH_DEBT: extract to named constant — G25
+        return 4
+    elif gherkin_ratio >= 0.4:  # noqa: PLR2004  # TECH_DEBT: extract to named constant — G25
+        return 3
+    elif gherkin_ratio > 0:
+        return 2
+    else:
+        return 1