titan-cli 0.2.0__tar.gz → 0.3.2__tar.gz

{titan_cli-0.2.0 → titan_cli-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: titan-cli
-Version: 0.2.0
+Version: 0.3.2
 Summary: Modular development tools orchestrator - Streamline your workflows with AI integration and intuitive terminal UI
 License: MIT
 License-File: LICENSE

{titan_cli-0.2.0 → titan_cli-0.3.2}/plugins/titan-plugin-git/titan_plugin_git/clients/git_client.py

@@ -243,6 +243,12 @@ class GitClient:
         """Create a commit."""
         return self.commit_service.commit(message, all, no_verify)
 
+    def commit_files(
+        self, files: list, message: str, no_verify: bool = True
+    ) -> ClientResult[str]:
+        """Create a commit with specific files only."""
+        return self.commit_service.commit_files(files, message, no_verify)
+
     def get_current_commit(self) -> ClientResult[str]:
         """Get current commit SHA (HEAD)."""
         return self.commit_service.get_current_commit()
@@ -303,9 +309,20 @@ class GitClient:
         """Get diff for a specific file."""
         return self.diff_service.get_file_diff(file_path)
 
-    def get_branch_diff(self, base_branch: str, head_branch: str) -> ClientResult[str]:
-        """Get diff between two branches."""
-        return self.diff_service.get_branch_diff(base_branch, head_branch)
+    def get_branch_diff(self, base_branch: str, head_branch: str, context_lines: int = 3, use_remote: bool = False) -> ClientResult[str]:
+        """
+        Get diff between two branches.
+
+        Args:
+            base_branch: Base branch name
+            head_branch: Head branch name
+            context_lines: Number of context lines (default: 3)
+            use_remote: If True, both branches are treated as remote refs (default: False)
+
+        Returns:
+            ClientResult[str] with diff output
+        """
+        return self.diff_service.get_branch_diff(base_branch, head_branch, context_lines, use_remote)
 
     def get_diff_stat(self, base_ref: str, head_ref: str = "HEAD") -> ClientResult[str]:
         """Get diff stat summary."""

{titan_cli-0.2.0 → titan_cli-0.3.2}/plugins/titan-plugin-git/titan_plugin_git/clients/services/commit_service.py

@@ -5,7 +5,8 @@ Commit Service
 Business logic for Git commit operations.
 Uses network layer to execute commands, parses to network models, maps to view models.
 """
-from typing import List, Optional
+import os
+from typing import List, Optional, Sequence
 
 from titan_cli.core.result import ClientResult, ClientSuccess, ClientError
 from titan_cli.core.logging import log_client_operation
@@ -70,6 +71,63 @@ class CommitService:
         except GitCommandError as e:
             return ClientError(error_message=str(e), error_code="COMMIT_ERROR")
 
+    @log_client_operation()
+    def commit_files(
+        self, files: Sequence[str], message: str, no_verify: bool = True
+    ) -> ClientResult[str]:
+        """
+        Create a commit with specific files only.
+
+        Args:
+            files: File paths to stage and commit
+            message: Commit message
+            no_verify: Skip pre-commit and commit-msg hooks
+
+        Returns:
+            ClientResult[str] with commit hash
+        """
+        try:
+            # Separate existing files from deleted ones
+            # Only include files that exist in the filesystem OR are tracked in git
+            existing_files = []
+            deleted_files = []
+
+            for f in files:
+                if os.path.exists(f):
+                    # File exists in filesystem
+                    existing_files.append(f)
+                else:
+                    # File doesn't exist - check if it's tracked in git
+                    # If it's tracked, we can use git rm; if not, skip it
+                    try:
+                        self.git.run_command(["git", "ls-files", "--error-unmatch", f])
+                        # File is tracked, mark for deletion
+                        deleted_files.append(f)
+                    except GitCommandError:
+                        # File not tracked in git, skip it
+                        pass
+
+            # Stage existing files with git add
+            if existing_files:
+                self.git.run_command(["git", "add", "--"] + existing_files)
+
+            # Stage deleted files with git rm
+            if deleted_files:
+                self.git.run_command(["git", "rm", "--"] + deleted_files)
+
+            args = ["git", "commit", "-m", message]
+            if no_verify:
+                args.append("--no-verify")
+            self.git.run_command(args)
+
+            commit_hash = self.git.run_command(["git", "rev-parse", "HEAD"])
+            return ClientSuccess(
+                data=commit_hash,
+                message=f"Commit created: {commit_hash[:7]}"
+            )
+        except GitCommandError as e:
+            return ClientError(error_message=str(e), error_code="COMMIT_ERROR")
+
     @log_client_operation()
     def get_current_commit(self) -> ClientResult[str]:
         """

{titan_cli-0.2.0 → titan_cli-0.3.2}/plugins/titan-plugin-git/titan_plugin_git/clients/services/diff_service.py

@@ -141,20 +141,34 @@ class DiffService:
             return ClientError(error_message=str(e), error_code="DIFF_ERROR")
 
     @log_client_operation()
-    def get_branch_diff(self, base_branch: str, head_branch: str) -> ClientResult[str]:
+    def get_branch_diff(self, base_branch: str, head_branch: str, context_lines: int = 3, use_remote: bool = False) -> ClientResult[str]:
         """
         Get diff between two branches.
 
         Args:
             base_branch: Base branch name
             head_branch: Head branch name
+            context_lines: Number of unchanged context lines around each change (default: 3).
+                When called from code review with context_lines=20, provides extended context
+                for AI analysis. The higher value gives better code understanding for review
+                quality, while still keeping token usage reasonable compared to reading entire files.
+            use_remote: If True, both branches are prefixed with the configured default_remote.
+                Used for PR reviews where branches are remote refs only (not checked out locally).
 
         Returns:
             ClientResult[str] with diff output
         """
         try:
+            # Build branch references using configured default_remote if use_remote=True
+            if use_remote:
+                base_ref = f"{self.default_remote}/{base_branch}"
+                head_ref = f"{self.default_remote}/{head_branch}"
+            else:
+                base_ref = f"{self.default_remote}/{base_branch}"
+                head_ref = head_branch
+
             diff = self.git.run_command(
-                ["git", "diff", f"{self.default_remote}/{base_branch}...{head_branch}"],
+                ["git", "diff", f"-U{context_lines}", f"{base_ref}...{head_ref}"],
                 check=False
             )
             return ClientSuccess(

{titan_cli-0.2.0 → titan_cli-0.3.2}/plugins/titan-plugin-git/titan_plugin_git/operations/__init__.py

@@ -20,6 +20,7 @@ from .commit_operations import (
 
 from .diff_operations import (
     parse_diff_stat_output,
+    expand_rename_path,
     get_max_filename_length,
     colorize_diff_stats,
     colorize_diff_summary,
@@ -42,6 +43,7 @@ __all__ = [
 
     # Diff operations
     "parse_diff_stat_output",
+    "expand_rename_path",
     "get_max_filename_length",
     "colorize_diff_stats",
     "colorize_diff_summary",

{titan_cli-0.2.0 → titan_cli-0.3.2}/plugins/titan-plugin-git/titan_plugin_git/operations/diff_operations.py

@@ -5,8 +5,36 @@ Pure business logic for Git diff parsing and formatting.
 These functions can be used by any step and are easily testable.
 """
 
+import re
 from typing import List, Tuple
 
+# Matches git rename notation: prefix{old => new}suffix
+# Examples:
+#   titan_cli/core/{models.py => models/__init__.py}  →  titan_cli/core/models/__init__.py
+#   {old_dir => new_dir}/file.py                      →  new_dir/file.py
+_RENAME_PATTERN = re.compile(r'^(.*?)\{[^}]*\s*=>\s*([^}]*)\}(.*)$')
+
+
+def expand_rename_path(path: str) -> str:
+    """
+    Expand a git rename notation path to the actual new file path.
+
+    Git diff --stat uses {old => new} notation for renames.
+    This function converts it to a real file path usable by git add.
+
+    Args:
+        path: A file path, possibly containing git rename notation.
+
+    Returns:
+        Expanded path with the rename resolved to the new name.
+        If no rename notation is present, returns the path unchanged.
+    """
+    match = _RENAME_PATTERN.match(path)
+    if not match:
+        return path
+    prefix, new_part, suffix = match.groups()
+    return prefix + new_part.strip() + suffix
+
 
 def parse_diff_stat_output(stat_output: str) -> Tuple[List[Tuple[str, str]], List[str]]:
     """
@@ -155,6 +183,7 @@ def format_diff_stat_display(stat_output: str) -> Tuple[List[str], List[str]]:
 
 __all__ = [
     "parse_diff_stat_output",
+    "expand_rename_path",
     "get_max_filename_length",
     "colorize_diff_stats",
     "colorize_diff_summary",

{titan_cli-0.2.0 → titan_cli-0.3.2}/plugins/titan-plugin-git/titan_plugin_git/steps/commit_step.py

@@ -53,9 +53,14 @@ def create_git_commit_step(ctx: WorkflowContext) -> WorkflowResult:
 
     all_files = ctx.get('all_files', True)
     no_verify = ctx.get('no_verify', False)
+    selected_files = ctx.data.get("selected_files")
 
     # Create commit using ClientResult pattern
-    result = ctx.git.commit(message=commit_message, all=all_files, no_verify=no_verify)
+    # If the user picked a specific subset of files, stage only those
+    if selected_files is not None:
+        result = ctx.git.commit_files(files=selected_files, message=commit_message, no_verify=no_verify)
+    else:
+        result = ctx.git.commit(message=commit_message, all=all_files, no_verify=no_verify)
 
     match result:
         case ClientSuccess(data=commit_hash):

titan_cli-0.3.2/plugins/titan-plugin-git/titan_plugin_git/steps/create_branch_step.py

@@ -0,0 +1,166 @@
+"""
+Create a new Git branch.
+"""
+
+import traceback
+
+from titan_cli.engine import WorkflowContext, WorkflowResult, Success, Error
+from titan_cli.core.result import ClientSuccess, ClientError
+from ..operations import (
+    check_branch_exists,
+    determine_safe_checkout_target,
+    should_delete_before_create,
+)
+
+
+def create_branch_step(ctx: WorkflowContext) -> WorkflowResult:
+    """
+    Create a new Git branch.
+
+    Inputs (from ctx.data):
+        new_branch (str): Name of the branch to create
+        start_point (str, optional): Starting point for the branch (defaults to HEAD)
+        delete_if_exists (bool, optional): Delete the branch if it already exists (default: False)
+        checkout (bool, optional): Checkout the new branch after creation (default: True)
+
+    Returns:
+        Success: Branch created successfully
+        Error: Git operation failed
+    """
+    if ctx.textual:
+        ctx.textual.begin_step("Create Branch")
+
+    if not ctx.textual:
+        return Error("Textual UI context is not available for this step.")
+
+    if not ctx.git:
+        ctx.textual.error_text("Git client not available in context")
+        ctx.textual.end_step("error")
+        return Error("Git client not available in context")
+
+    try:
+        # Get params from context
+        new_branch = ctx.get("new_branch")
+        if not new_branch:
+            ctx.textual.error_text("No branch name specified")
+            ctx.textual.dim_text("Set 'new_branch' in workflow params or previous step")
+            ctx.textual.end_step("error")
+            return Error("No branch name specified")
+
+        start_point = ctx.get("start_point", "HEAD")
+        delete_if_exists = ctx.get("delete_if_exists", False)
+        checkout = ctx.get("checkout", True)
+
+        ctx.textual.text("")
+        ctx.textual.dim_text(f"Creating branch: {new_branch}")
+        ctx.textual.dim_text(f"From: {start_point}")
+
+        # Check if branch exists using operations
+        branches_result = ctx.git.get_branches()
+
+        match branches_result:
+            case ClientSuccess(data=all_branches):
+                branch_names = [b.name for b in all_branches]
+                branch_exists = check_branch_exists(new_branch, branch_names)
+            case ClientError(error_message=err):
+                ctx.textual.error_text(f"Failed to get branches: {err}")
+                ctx.textual.end_step("error")
+                return Error(f"Failed to get branches: {err}")
+
+        # Delete if exists and requested using operations
+        if should_delete_before_create(branch_exists, delete_if_exists):
+            ctx.textual.text("")
+            ctx.textual.warning_text(f"Branch {new_branch} exists, deleting...")
+
+            # If we're on the branch, checkout another one first using operations
+            current_branch_result = ctx.git.get_current_branch()
+
+            match current_branch_result:
+                case ClientSuccess(data=current_branch):
+                    safe_target = determine_safe_checkout_target(
+                        current_branch=current_branch,
+                        branch_to_delete=new_branch,
+                        main_branch=ctx.git.main_branch,
+                        all_branches=branch_names
+                    )
+
+                    if safe_target:
+                        checkout_result = ctx.git.checkout(safe_target)
+                        match checkout_result:
+                            case ClientSuccess():
+                                ctx.textual.dim_text(f"Switched to {safe_target}")
+                            case ClientError(error_message=err):
+                                ctx.textual.error_text(f"Failed to checkout {safe_target}: {err}")
+                                ctx.textual.end_step("error")
+                                return Error(f"Cannot checkout {safe_target}: {err}")
+                    elif current_branch == new_branch:
+                        # Cannot delete current branch and no safe target available
+                        ctx.textual.error_text(f"Cannot delete current branch {new_branch}")
+                        ctx.textual.end_step("error")
+                        return Error("Cannot delete current branch")
+
+                    # Delete the branch
+                    delete_result = ctx.git.safe_delete_branch(new_branch, force=True)
+                    match delete_result:
+                        case ClientSuccess():
+                            ctx.textual.success_text(f"✓ Deleted existing branch {new_branch}")
+                        case ClientError(error_message=err):
+                            ctx.textual.error_text(f"Failed to delete {new_branch}: {err}")
+                            ctx.textual.end_step("error")
+                            return Error(f"Failed to delete branch: {err}")
+
+                case ClientError(error_message=err):
+                    ctx.textual.error_text(f"Failed to get current branch: {err}")
+                    ctx.textual.end_step("error")
+                    return Error(f"Failed to get current branch: {err}")
+
+        elif branch_exists:
+            ctx.textual.error_text(f"Branch {new_branch} already exists")
+            ctx.textual.dim_text("Set 'delete_if_exists: true' to recreate it")
+            ctx.textual.end_step("error")
+            return Error(f"Branch {new_branch} already exists")
+
+        # Create the branch
+        ctx.textual.text("")
+        create_result = ctx.git.create_branch(new_branch, start_point=start_point)
+        match create_result:
+            case ClientSuccess():
+                ctx.textual.success_text(f"✓ Created branch {new_branch}")
+            case ClientError(error_message=err):
+                ctx.textual.error_text(f"Failed to create {new_branch}: {err}")
+                ctx.textual.end_step("error")
+                return Error(f"Failed to create branch: {err}")
+
+        # Checkout if requested
+        if checkout:
+            checkout_result = ctx.git.checkout(new_branch)
+            match checkout_result:
+                case ClientSuccess():
+                    ctx.textual.success_text(f"✓ Checked out {new_branch}")
+                case ClientError(error_message=err):
+                    ctx.textual.warning_text(f"Branch created but failed to checkout: {err}")
+
+        ctx.textual.text("")
+        ctx.textual.end_step("success")
+        return Success(
+            f"Created branch {new_branch}",
+            metadata={
+                "new_branch": new_branch,
+                "start_point": start_point,
+                "checked_out": checkout
+            }
+        )
+
+    except Exception as e:
+        tb = traceback.format_exc()
+        ctx.textual.text("")
+        ctx.textual.error_text(f"Failed to create branch: {str(e)}")
+        ctx.textual.text("")
+        ctx.textual.dim_text("Full traceback:")
+        for line in tb.split('\n'):
+            ctx.textual.dim_text(line)
+        ctx.textual.end_step("error")
+        return Error(f"Failed to create branch: {str(e)}")
+
+
+__all__ = ["create_branch_step"]

{titan_cli-0.2.0 → titan_cli-0.3.2}/plugins/titan-plugin-git/titan_plugin_git/steps/diff_summary_step.py

@@ -1,19 +1,22 @@
 # plugins/titan-plugin-git/titan_plugin_git/steps/diff_summary_step.py
-from titan_cli.engine import WorkflowContext, WorkflowResult, Success, Error, Skip
+from titan_cli.engine import WorkflowContext, WorkflowResult, Success, Error, Skip, Exit
 from titan_cli.core.result import ClientSuccess, ClientError
+from titan_cli.ui.tui.widgets import SelectionOption
 from titan_plugin_git.messages import msg
-from ..operations import format_diff_stat_display
+from ..operations import parse_diff_stat_output, expand_rename_path, colorize_diff_stats, colorize_diff_summary, format_diff_stat_display
 
 
 def show_uncommitted_diff_summary(ctx: WorkflowContext) -> WorkflowResult:
     """
-    Show summary of uncommitted changes (git diff --stat).
+    Show uncommitted changes and let the user select which files to include
+    in the commit. Each checkbox shows the filename and its diff stats inline.
 
-    Provides a visual overview of files changed and lines modified
-    before generating commit messages.
+    Saves selected file paths to ctx.data["selected_files"].
 
     Returns:
-        Success: Always (even if no changes, for workflow continuity)
+        Success: Files selected and saved to context
+        Exit: No files selected by the user
+        Skip: Could not retrieve diff stat
     """
     if not ctx.textual:
         return Error("Textual UI context is not available for this step.")
@@ -24,7 +27,6 @@ def show_uncommitted_diff_summary(ctx: WorkflowContext) -> WorkflowResult:
     # Begin step container
     ctx.textual.begin_step("Show Changes Summary")
 
-    # Get diff stat for uncommitted changes using ClientResult pattern
     result = ctx.git.get_uncommitted_diff_stat()
 
     match result:
@@ -34,17 +36,45 @@ def show_uncommitted_diff_summary(ctx: WorkflowContext) -> WorkflowResult:
                 ctx.textual.end_step("success")
                 return Success("No changes")
 
-            # Format and render diff stat
-            formatted_files, formatted_summary = format_diff_stat_display(stat_output)
-            ctx.textual.show_diff_stat(formatted_files, formatted_summary, "Changes summary:")
+            file_lines, summary_lines = parse_diff_stat_output(stat_output)
+
+            if file_lines:
+                max_len = max(len(filename) for filename, _ in file_lines)
+                options = [
+                    SelectionOption(
+                        value=expand_rename_path(filename),
+                        label=f"{filename.ljust(max_len)} |{colorize_diff_stats(stats)}",
+                        selected=True,
+                    )
+                    for filename, stats in file_lines
+                ]
+
+                summary_text = colorize_diff_summary(summary_lines[0].strip()) if summary_lines else ""
+                question = f"Select files to include in the commit:  {summary_text}"
+
+                selected = ctx.textual.ask_multiselect(question, options)
+
+                if not selected:
+                    ctx.textual.warning_text("No files selected. Select at least one file to commit.")
+                    ctx.textual.end_step("skip")
+                    return Exit("No files selected for commit")
+
+                ctx.data["selected_files"] = selected
+
+                # Show what was selected
+                selected_set = set(selected)
+                selected_lines = [(f, s) for f, s in file_lines if f in selected_set]
+                formatted_selected = [
+                    f"{f.ljust(max_len)} |{colorize_diff_stats(s)}"
+                    for f, s in selected_lines
+                ]
+                formatted_summary = [colorize_diff_summary(summary_lines[0].strip())] if summary_lines else []
+                ctx.textual.show_diff_stat(formatted_selected, formatted_summary, "Files to commit:")
 
-            # End step container with success
             ctx.textual.end_step("success")
-
             return Success("Diff summary displayed")
 
         case ClientError(error_message=err):
-            # Don't fail the workflow, just skip
             ctx.textual.end_step("skip")
             return Skip(f"Could not show diff summary: {err}")
 

{titan_cli-0.2.0 → titan_cli-0.3.2}/plugins/titan-plugin-github/titan_plugin_github/agents/__init__.py

@@ -2,5 +2,6 @@
 """AI agents for GitHub plugin."""
 
 from .pr_agent import PRAgent, PRAnalysis
+from .code_review_agent import CodeReviewAgent
 
-__all__ = ["PRAgent", "PRAnalysis"]
+__all__ = ["PRAgent", "PRAnalysis", "CodeReviewAgent"]

titan_cli-0.3.2/plugins/titan-plugin-github/titan_plugin_github/agents/code_review_agent.py

@@ -0,0 +1,168 @@
+# plugins/titan-plugin-github/titan_plugin_github/agents/code_review_agent.py
+"""
+CodeReviewAgent - AI agent for reviewing pull requests.
+
+Analyzes PR diffs and project skills to generate structured review comments.
+"""
+
+import json
+from typing import List
+
+from titan_cli.core.logging import get_logger
+from titan_cli.ai.agents.base import BaseAIAgent, AgentRequest
+from ..models.review_enums import FindingSeverity
+from ..models.view import UIReviewSuggestion
+
+logger = get_logger(__name__)
+
+
+def _normalize_suggestion_severity(raw_severity: str) -> FindingSeverity:
+    """Normalize legacy and current AI severity labels into FindingSeverity."""
+    mapping = {
+        "blocking": FindingSeverity.BLOCKING,
+        "critical": FindingSeverity.BLOCKING,
+        "important": FindingSeverity.IMPORTANT,
+        "improvement": FindingSeverity.IMPORTANT,
+        "nit": FindingSeverity.NIT,
+        "suggestion": FindingSeverity.NIT,
+    }
+    return mapping.get(raw_severity.lower(), FindingSeverity.NIT)
+
+_SYSTEM_PROMPT = """You are an expert code reviewer. Your task is to review pull request diffs
+and identify problems, bugs, and improvements.
+
+When reviewing code, focus ONLY on:
+- Correctness: bugs, logic errors, edge cases
+- Security: vulnerabilities, unsafe patterns
+- Performance: inefficiencies, unnecessary complexity
+- Maintainability: readability, naming, structure
+- Project conventions: follow any project-specific skills/guidelines provided
+
+IMPORTANT rules:
+- ONLY comment when you have something to improve or fix. Never praise, compliment, or validate changes.
+- Do NOT say things like "Good cleanup", "Excellent improvement", "Nice refactor", etc.
+- If a change looks correct and has no issues, skip it entirely — return nothing for that file/line.
+- Every comment must propose a concrete change or flag a real problem.
+- If the code looks good overall, return an empty array [].
+
+If "Existing Open Review Comments" are provided:
+- Check each thread before suggesting changes — do NOT duplicate an issue already in the conversation.
+- If the author/reviewer has already responded (even with a short note), and the issue seems addressed, do NOT suggest it again.
+  - Example: If someone says "This variable exists as an org secret", don't suggest validating it.
+  - Example: If someone says "Already fixed in commit X", don't repeat the same issue.
+- Only reply to a thread (using `reply_to_comment_id`) if needed to continue the conversation:
+  - If author says it's fixed and they're RIGHT → skip, don't reply
+  - If author disagrees and they're RIGHT → skip, don't reply
+  - If author is WRONG or hasn't addressed it yet → reply with clarification, evidence, or escalation
+- Never suggest a reply just to repeat the original comment. Replies must add new context or refute the author's reasoning.
+
+Output your review as a JSON array of comment objects. Each comment must have:
+- "file": the file path (string). Use empty string "" when replying to a thread.
+- "snippet": the exact line of code where the problem is (copy-paste the line verbatim from the diff, without the leading + or - character). Use null for general file-level comments or replies.
+- "body": the review comment text (string, be concise and actionable)
+- "severity": one of "blocking", "important", or "nit"
+- "reply_to_comment_id": (optional) the integer comment ID from `[comment_id:N]` if this is a follow-up reply to an existing thread. Omit or use null for new comments.
+
+Severity guide:
+- "blocking": bugs, security issues, broken logic that must be fixed
+- "important": code quality issues that should be addressed
+- "nit": minor style, naming, or optional improvements
+
+Respond with ONLY the JSON array, no other text.
+"""
+
+
+class CodeReviewAgent(BaseAIAgent):
+    """
+    AI agent for reviewing pull requests using project skills as context.
+
+    Generates structured UIReviewSuggestion objects from PR diffs.
+    """
+
+    def get_system_prompt(self) -> str:
+        """System prompt for code review expertise."""
+        return _SYSTEM_PROMPT
+
+    def review(self, context: str) -> List[UIReviewSuggestion]:
+        """
+        Generate review comments for a PR.
+
+        Args:
+            context: Formatted string with PR info, diff, and project skills
+
+        Returns:
+            List of UIReviewSuggestion objects
+        """
+        request = AgentRequest(
+            context=context,
+            max_tokens=4000,
+            temperature=0.3,
+            operation="code_review",
+        )
+
+        try:
+            response = self.generate(request)
+        except Exception as e:
+            logger.error(f"AI code review failed: {e}")
+            return []
+
+        return self._parse_suggestions(response.content)
+
+    def _parse_suggestions(self, content: str) -> List[UIReviewSuggestion]:
+        """
+        Parse AI JSON response into UIReviewSuggestion objects.
+
+        Args:
+            content: Raw AI response string
+
+        Returns:
+            List of UIReviewSuggestion objects (empty list on parse failure)
+        """
+        # Strip markdown code fences if present
+        text = content.strip()
+        if text.startswith("```"):
+            lines = text.split("\n")
+            text = "\n".join(lines[1:-1]) if len(lines) > 2 else text
+
+        try:
+            data = json.loads(text)
+        except json.JSONDecodeError:
+            logger.warning(f"Failed to parse AI review response as JSON: {content[:200]}")
+            return []
+
+        if not isinstance(data, list):
+            logger.warning(f"AI review response is not a list: {type(data)}")
+            return []
+
+        suggestions = []
+
+        for item in data:
+            if not isinstance(item, dict):
+                continue
+
+            file_path = item.get("file", "")
+            if not file_path:
+                continue
+
+            severity = _normalize_suggestion_severity(str(item.get("severity", "nit")))
+
+            snippet_raw = item.get("snippet")
+            snippet = snippet_raw.strip() if isinstance(snippet_raw, str) and snippet_raw else None
+
+            body = item.get("body", "").strip()
+            if not body:
+                continue
+
+            reply_to_raw = item.get("reply_to_comment_id")
+            reply_to_comment_id = int(reply_to_raw) if isinstance(reply_to_raw, (int, float)) and reply_to_raw else None
+
+            suggestions.append(UIReviewSuggestion(
+                file_path=file_path,
+                line=None,   # Will be resolved deterministically from snippet
+                body=body,
+                severity=severity,
+                snippet=snippet,
+                reply_to_comment_id=reply_to_comment_id,
+            ))
+
+        return suggestions