monoco-toolkit 0.1.1__py3-none-any.whl → 0.2.8__py3-none-any.whl

monoco/features/issue/commands.py

@@ -8,38 +8,49 @@ from rich.table import Table
 import typer
 
 from monoco.core.config import get_config
-from monoco.core.output import print_output
+from monoco.core.output import print_output, OutputManager, AgentOutput
 from .models import IssueType, IssueStatus, IssueSolution, IssueStage, IsolationType, IssueMetadata
 from . import core
 
 app = typer.Typer(help="Agent-Native Issue Management.")
 backlog_app = typer.Typer(help="Manage backlog operations.")
+lsp_app = typer.Typer(help="LSP Server commands.")
 app.add_typer(backlog_app, name="backlog")
+app.add_typer(lsp_app, name="lsp")
 console = Console()
 
 @app.command("create")
 def create(
-    type: IssueType = typer.Argument(..., help="Issue type (epic, feature, chore, fix)"),
+    type: str = typer.Argument(..., help="Issue type (epic, feature, chore, fix, etc.)"),
     title: str = typer.Option(..., "--title", "-t", help="Issue title"),
     parent: Optional[str] = typer.Option(None, "--parent", "-p", help="Parent Issue ID"),
     is_backlog: bool = typer.Option(False, "--backlog", help="Create as backlog item"),
-    stage: Optional[IssueStage] = typer.Option(None, "--stage", help="Issue stage (todo, doing, review)"),
+    stage: Optional[str] = typer.Option(None, "--stage", help="Issue stage"),
     dependencies: List[str] = typer.Option([], "--dependency", "-d", help="Issue dependency ID(s)"),
     related: List[str] = typer.Option([], "--related", "-r", help="Related Issue ID(s)"),
     subdir: Optional[str] = typer.Option(None, "--subdir", "-s", help="Subdirectory for organization (e.g. 'Backend/Auth')"),
     sprint: Optional[str] = typer.Option(None, "--sprint", help="Sprint ID"),
     tags: List[str] = typer.Option([], "--tag", help="Tags"),
     root: Optional[str] = typer.Option(None, "--root", help="Override issues root directory"),
+    json: AgentOutput = False,
 ):
+    """Create a new issue."""
     """Create a new issue."""
     config = get_config()
     issues_root = _resolve_issues_root(config, root)
-    status = IssueStatus.BACKLOG if is_backlog else IssueStatus.OPEN
+    status = "backlog" if is_backlog else "open"
+    
+    # Sanitize inputs (strip #)
+    if parent and parent.startswith("#"):
+        parent = parent[1:]
     
+    dependencies = [d[1:] if d.startswith("#") else d for d in dependencies]
+    related = [r[1:] if r.startswith("#") else r for r in related]
+
     if parent:
         parent_path = core.find_issue_path(issues_root, parent)
         if not parent_path:
-            console.print(f"[red]✘ Error:[/red] Parent issue {parent} not found.")
+            OutputManager.error(f"Parent issue {parent} not found.")
             raise typer.Exit(code=1)
 
     try:
@@ -62,26 +73,79 @@ def create(
         except ValueError:
             rel_path = path
 
-        console.print(f"[green]✔[/green] Created [bold]{issue.id}[/bold] in status [cyan]{issue.status.value}[/cyan].")
-        console.print(f"[dim]Path: {rel_path}[/dim]")
+        if OutputManager.is_agent_mode():
+            OutputManager.print({
+                "issue": issue,
+                "path": str(rel_path),
+                "status": "created"
+            })
+        else:
+            console.print(f"[green]✔ Created {issue.id} in status {issue.status}.[/green]")
+            console.print(f"Path: {rel_path}")
+
     except ValueError as e:
-        console.print(f"[red]✘ Error:[/red] {str(e)}")
+        OutputManager.error(str(e))
         raise typer.Exit(code=1)
 
+@app.command("update")
+def update(
+    issue_id: str = typer.Argument(..., help="Issue ID to update"),
+    title: Optional[str] = typer.Option(None, "--title", "-t", help="New title"),
+    status: Optional[str] = typer.Option(None, "--status", help="New status"),
+    stage: Optional[str] = typer.Option(None, "--stage", help="New stage"),
+    parent: Optional[str] = typer.Option(None, "--parent", "-p", help="Parent Issue ID"),
+    sprint: Optional[str] = typer.Option(None, "--sprint", help="Sprint ID"),
+    dependencies: Optional[List[str]] = typer.Option(None, "--dependency", "-d", help="Issue dependency ID(s)"),
+    related: Optional[List[str]] = typer.Option(None, "--related", "-r", help="Related Issue ID(s)"),
+    tags: Optional[List[str]] = typer.Option(None, "--tag", help="Tags"),
+    root: Optional[str] = typer.Option(None, "--root", help="Override issues root directory"),
+    json: AgentOutput = False,
+):
+    """Update an existing issue."""
+    config = get_config()
+    issues_root = _resolve_issues_root(config, root)
+    
+    try:
+        issue = core.update_issue(
+            issues_root, 
+            issue_id, 
+            status=status, 
+            stage=stage,
+            title=title,
+            parent=parent,
+            sprint=sprint,
+            dependencies=dependencies, 
+            related=related, 
+            tags=tags
+        )
+        
+        OutputManager.print({
+            "issue": issue,
+            "status": "updated"
+        })
+    except Exception as e:
+        OutputManager.error(str(e))
+        raise typer.Exit(code=1)
+
+
 @app.command("open")
 def move_open(
     issue_id: str = typer.Argument(..., help="Issue ID to open"),
     root: Optional[str] = typer.Option(None, "--root", help="Override issues root directory"),
+    json: AgentOutput = False,
 ):
-    """Move issue to open status and set stage to Todo."""
+    """Move issue to open status and set stage to Draft."""
     config = get_config()
     issues_root = _resolve_issues_root(config, root)
     try:
         # Pull operation: Force stage to TODO
-        core.update_issue(issues_root, issue_id, status=IssueStatus.OPEN, stage=IssueStage.TODO)
-        console.print(f"[green]▶[/green] Issue [bold]{issue_id}[/bold] moved to open/todo.")
+        issue = core.update_issue(issues_root, issue_id, status="open", stage="draft")
+        OutputManager.print({
+            "issue": issue,
+            "status": "opened"
+        })
     except Exception as e:
-        console.print(f"[red]✘ Error:[/red] {str(e)}")
+        OutputManager.error(str(e))
         raise typer.Exit(code=1)
 
 @app.command("start")
@@ -90,6 +154,7 @@ def start(
     branch: bool = typer.Option(False, "--branch", "-b", help="Start in a new git branch"),
     worktree: bool = typer.Option(False, "--worktree", "-w", help="Start in a new git worktree"),
     root: Optional[str] = typer.Option(None, "--root", help="Override issues root directory"),
+    json: AgentOutput = False,
 ):
     """Start working on an issue (Stage -> Doing)."""
     config = get_config()
@@ -97,32 +162,38 @@ def start(
     project_root = _resolve_project_root(config)
 
     if branch and worktree:
-         console.print("[red]Error:[/red] Cannot specify both --branch and --worktree.")
+         OutputManager.error("Cannot specify both --branch and --worktree.")
          raise typer.Exit(code=1)
 
     try:
         # Implicitly ensure status is Open
-        core.update_issue(issues_root, issue_id, status=IssueStatus.OPEN, stage=IssueStage.DOING)
+        issue = core.update_issue(issues_root, issue_id, status="open", stage="doing")
         
+        isolation_info = None
+
         if branch:
             try:
-                meta = core.start_issue_isolation(issues_root, issue_id, IsolationType.BRANCH, project_root)
-                console.print(f"[green]✔[/green] Switched to branch [bold]{meta.isolation.ref}[/bold]")
+                issue = core.start_issue_isolation(issues_root, issue_id, "branch", project_root)
+                isolation_info = {"type": "branch", "ref": issue.isolation.ref}
             except Exception as e:
-                console.print(f"[red]Error:[/red] Failed to create branch: {e}")
+                OutputManager.error(f"Failed to create branch: {e}")
                 raise typer.Exit(code=1)
                 
         if worktree:
             try:
-                meta = core.start_issue_isolation(issues_root, issue_id, IsolationType.WORKTREE, project_root)
-                console.print(f"[green]✔[/green] Created worktree at [bold]{meta.isolation.path}[/bold]")
+                issue = core.start_issue_isolation(issues_root, issue_id, "worktree", project_root)
+                isolation_info = {"type": "worktree", "path": issue.isolation.path, "ref": issue.isolation.ref}
             except Exception as e:
-                console.print(f"[red]Error:[/red] Failed to create worktree: {e}")
+                OutputManager.error(f"Failed to create worktree: {e}")
                 raise typer.Exit(code=1)
 
-        console.print(f"[green]🚀[/green] Issue [bold]{issue_id}[/bold] started.")
+        OutputManager.print({
+            "issue": issue,
+            "status": "started",
+            "isolation": isolation_info
+        })
     except Exception as e:
-        console.print(f"[red]✘ Error:[/red] {str(e)}")
+        OutputManager.error(str(e))
         raise typer.Exit(code=1)
 
 @app.command("submit")
@@ -131,6 +202,7 @@ def submit(
     prune: bool = typer.Option(False, "--prune", help="Delete branch/worktree after submit"),
     force: bool = typer.Option(False, "--force", help="Force delete branch/worktree"),
     root: Optional[str] = typer.Option(None, "--root", help="Override issues root directory"),
+    json: AgentOutput = False,
 ):
     """Submit issue for review (Stage -> Review) and generate delivery report."""
     config = get_config()
@@ -138,116 +210,153 @@ def submit(
     project_root = _resolve_project_root(config)
     try:
         # Implicitly ensure status is Open
-        core.update_issue(issues_root, issue_id, status=IssueStatus.OPEN, stage=IssueStage.REVIEW)
-        console.print(f"[green]🚀[/green] Issue [bold]{issue_id}[/bold] submitted for review.")
+        issue = core.update_issue(issues_root, issue_id, status="open", stage="review")
         
         # Delivery Report Generation
+        report_status = "skipped"
         try:
              core.generate_delivery_report(issues_root, issue_id, project_root)
-             console.print(f"[dim]✔ Delivery report appended to issue file.[/dim]")
+             report_status = "generated"
         except Exception as e:
-             console.print(f"[yellow]⚠ Failed to generate delivery report: {e}[/yellow]")
+             report_status = f"failed: {e}"
         
+        pruned_resources = []
         if prune:
             try:
-                deleted = core.prune_issue_resources(issues_root, issue_id, force, project_root)
-                if deleted:
-                    console.print(f"[dim]✔ Pruned resources: {', '.join(deleted)}[/dim]")
+                pruned_resources = core.prune_issue_resources(issues_root, issue_id, force, project_root)
             except Exception as e:
-                console.print(f"[red]Prune Error:[/red] {e}")
+                OutputManager.error(f"Prune Error: {e}")
                 raise typer.Exit(code=1)
              
+        OutputManager.print({
+            "issue": issue,
+            "status": "submitted",
+            "report": report_status,
+            "pruned": pruned_resources
+        })
+             
     except Exception as e:
-        console.print(f"[red]✘ Error:[/red] {str(e)}")
+        OutputManager.error(str(e))
         raise typer.Exit(code=1)
 
 @app.command("close")
 def move_close(
     issue_id: str = typer.Argument(..., help="Issue ID to close"),
-    solution: Optional[IssueSolution] = typer.Option(None, "--solution", "-s", help="Solution type"),
+    solution: Optional[str] = typer.Option(None, "--solution", "-s", help="Solution type"),
     prune: bool = typer.Option(False, "--prune", help="Delete branch/worktree after close"),
     force: bool = typer.Option(False, "--force", help="Force delete branch/worktree"),
     root: Optional[str] = typer.Option(None, "--root", help="Override issues root directory"),
+    json: AgentOutput = False,
 ):
     """Close issue."""
     config = get_config()
     issues_root = _resolve_issues_root(config, root)
     project_root = _resolve_project_root(config)
+    
+    # Pre-flight check for interactive guidance (Requirement FEAT-0082 #6)
+    if solution is None:
+        # Resolve options from engine
+        from .engine import get_engine
+        engine = get_engine(str(issues_root.parent))
+        valid_solutions = engine.issue_config.solutions or []
+        OutputManager.error(f"Closing an issue requires a solution. Options: {', '.join(valid_solutions)}")
+        raise typer.Exit(code=1)
+
     try:
-        core.update_issue(issues_root, issue_id, status=IssueStatus.CLOSED, solution=solution)
-        console.print(f"[dim]✔[/dim] Issue [bold]{issue_id}[/bold] closed.")
+        issue = core.update_issue(issues_root, issue_id, status="closed", solution=solution)
         
+        pruned_resources = []
         if prune:
             try:
-                deleted = core.prune_issue_resources(issues_root, issue_id, force, project_root)
-                if deleted:
-                    console.print(f"[dim]✔ Pruned resources: {', '.join(deleted)}[/dim]")
+                pruned_resources = core.prune_issue_resources(issues_root, issue_id, force, project_root)
             except Exception as e:
-                console.print(f"[red]Prune Error:[/red] {e}")
+                OutputManager.error(f"Prune Error: {e}")
                 raise typer.Exit(code=1)
 
+        OutputManager.print({
+            "issue": issue,
+            "status": "closed",
+            "pruned": pruned_resources
+        })
+
     except Exception as e:
-        console.print(f"[red]✘ Error:[/red] {str(e)}")
+        OutputManager.error(str(e))
         raise typer.Exit(code=1)
 
 @backlog_app.command("push")
 def push(
     issue_id: str = typer.Argument(..., help="Issue ID to push to backlog"),
     root: Optional[str] = typer.Option(None, "--root", help="Override issues root directory"),
+    json: AgentOutput = False,
 ):
     """Push issue to backlog."""
     config = get_config()
     issues_root = _resolve_issues_root(config, root)
     try:
-        core.update_issue(issues_root, issue_id, status=IssueStatus.BACKLOG)
-        console.print(f"[blue]💤[/blue] Issue [bold]{issue_id}[/bold] pushed to backlog.")
+        issue = core.update_issue(issues_root, issue_id, status="backlog")
+        OutputManager.print({
+            "issue": issue,
+            "status": "pushed_to_backlog"
+        })
     except Exception as e:
-        console.print(f"[red]✘ Error:[/red] {str(e)}")
+        OutputManager.error(str(e))
         raise typer.Exit(code=1)
 
 @backlog_app.command("pull")
 def pull(
     issue_id: str = typer.Argument(..., help="Issue ID to pull from backlog"),
     root: Optional[str] = typer.Option(None, "--root", help="Override issues root directory"),
+    json: AgentOutput = False,
 ):
-    """Pull issue from backlog (Open & Todo)."""
+    """Pull issue from backlog (Open & Draft)."""
     config = get_config()
     issues_root = _resolve_issues_root(config, root)
     try:
-        core.update_issue(issues_root, issue_id, status=IssueStatus.OPEN, stage=IssueStage.TODO)
-        console.print(f"[green]🔥[/green] Issue [bold]{issue_id}[/bold] pulled from backlog.")
+        issue = core.update_issue(issues_root, issue_id, status="open", stage="draft")
+        OutputManager.print({
+            "issue": issue,
+            "status": "pulled_from_backlog"
+        })
     except Exception as e:
-        console.print(f"[red]✘ Error:[/red] {str(e)}")
+        OutputManager.error(str(e))
         raise typer.Exit(code=1)
 
 @app.command("cancel")
 def cancel(
     issue_id: str = typer.Argument(..., help="Issue ID to cancel"),
     root: Optional[str] = typer.Option(None, "--root", help="Override issues root directory"),
+    json: AgentOutput = False,
 ):
     """Cancel issue."""
     config = get_config()
     issues_root = _resolve_issues_root(config, root)
     try:
-        core.update_issue(issues_root, issue_id, status=IssueStatus.CLOSED, solution=IssueSolution.CANCELLED)
-        console.print(f"[red]✘[/red] Issue [bold]{issue_id}[/bold] cancelled.")
+        issue = core.update_issue(issues_root, issue_id, status="closed", solution="cancelled")
+        OutputManager.print({
+            "issue": issue,
+            "status": "cancelled"
+        })
     except Exception as e:
-        console.print(f"[red]✘ Error:[/red] {str(e)}")
+        OutputManager.error(str(e))
         raise typer.Exit(code=1)
 
 @app.command("delete")
 def delete(
     issue_id: str = typer.Argument(..., help="Issue ID to delete"),
     root: Optional[str] = typer.Option(None, "--root", help="Override issues root directory"),
+    json: AgentOutput = False,
 ):
     """Physically remove an issue file."""
     config = get_config()
     issues_root = _resolve_issues_root(config, root)
     try:
         core.delete_issue_file(issues_root, issue_id)
-        console.print(f"[red]✔[/red] Issue [bold]{issue_id}[/bold] physically deleted.")
+        OutputManager.print({
+            "id": issue_id,
+            "status": "deleted"
+        })
     except Exception as e:
-        console.print(f"[red]✘ Error:[/red] {str(e)}")
+        OutputManager.error(str(e))
         raise typer.Exit(code=1)
 
 @app.command("move")
@@ -256,6 +365,7 @@ def move(
     target: str = typer.Option(..., "--to", help="Target project directory (e.g., ../OtherProject)"),
     renumber: bool = typer.Option(False, "--renumber", help="Automatically renumber on ID conflict"),
     root: Optional[str] = typer.Option(None, "--root", help="Override source issues root directory"),
+    json: AgentOutput = False,
 ):
     """Move an issue to another project."""
     config = get_config()
@@ -270,7 +380,7 @@ def move(
     elif target_path.name == "Issues" and target_path.exists():
         target_issues_root = target_path
     else:
-        console.print(f"[red]✘ Error:[/red] Target path must be a project root with 'Issues' directory or an 'Issues' directory itself.")
+        OutputManager.error("Target path must be a project root with 'Issues' directory or an 'Issues' directory itself.")
         raise typer.Exit(code=1)
     
     try:
@@ -286,32 +396,37 @@ def move(
         except ValueError:
             rel_path = new_path
         
-        if updated_meta.id != issue_id:
-            console.print(f"[green]✔[/green] Moved and renumbered: [bold]{issue_id}[/bold] → [bold]{updated_meta.id}[/bold]")
-        else:
-            console.print(f"[green]✔[/green] Moved [bold]{issue_id}[/bold] to target project.")
-        
-        console.print(f"[dim]New path: {rel_path}[/dim]")
+        OutputManager.print({
+            "issue": updated_meta,
+            "new_path": str(rel_path),
+            "status": "moved",
+            "renumbered": updated_meta.id != issue_id
+        })
         
     except FileNotFoundError as e:
-        console.print(f"[red]✘ Error:[/red] {str(e)}")
+        OutputManager.error(str(e))
         raise typer.Exit(code=1)
     except ValueError as e:
-        console.print(f"[red]✘ Conflict:[/red] {str(e)}")
+        OutputManager.error(str(e))
         raise typer.Exit(code=1)
     except Exception as e:
-        console.print(f"[red]✘ Error:[/red] {str(e)}")
+        OutputManager.error(str(e))
         raise typer.Exit(code=1)
 
 @app.command("board")
 def board(
     root: Optional[str] = typer.Option(None, "--root", help="Override issues root directory"),
+    json: AgentOutput = False,
 ):
     """Visualize issues in a Kanban board."""
     config = get_config()
     issues_root = _resolve_issues_root(config, root)
     
     board_data = core.get_board_data(issues_root)
+
+    if OutputManager.is_agent_mode():
+        OutputManager.print(board_data)
+        return
     
     from rich.columns import Columns
     from rich.console import RenderableType
@@ -319,7 +434,7 @@ def board(
     columns: List[RenderableType] = []
     
     stage_titles = {
-        "todo": "[bold white]TODO[/bold white]",
+        "draft": "[bold white]DRAFT[/bold white]",
         "doing": "[bold yellow]DOING[/bold yellow]",
         "review": "[bold cyan]REVIEW[/bold cyan]",
         "done": "[bold green]DONE[/bold green]"
@@ -329,10 +444,10 @@ def board(
         issue_list = []
         for issue in sorted(issues, key=lambda x: x.updated_at, reverse=True):
             type_color = {
-                IssueType.FEATURE: "green",
-                IssueType.CHORE: "blue",
-                IssueType.FIX: "red",
-                IssueType.EPIC: "magenta"
+                "feature": "green",
+                "chore": "blue",
+                "fix": "red",
+                "epic": "magenta"
             }.get(issue.type, "white")
             
             issue_list.append(
@@ -360,10 +475,11 @@ def board(
 @app.command("list")
 def list_cmd(
     status: Optional[str] = typer.Option(None, "--status", "-s", help="Filter by status (open, closed, backlog, all)"),
-    type: Optional[IssueType] = typer.Option(None, "--type", "-t", help="Filter by type"),
-    stage: Optional[IssueStage] = typer.Option(None, "--stage", help="Filter by stage"),
+    type: Optional[str] = typer.Option(None, "--type", "-t", help="Filter by type"),
+    stage: Optional[str] = typer.Option(None, "--stage", help="Filter by stage"),
     root: Optional[str] = typer.Option(None, "--root", help="Override issues root directory"),
     workspace: bool = typer.Option(False, "--workspace", "-w", help="Include issues from workspace members"),
+    json: AgentOutput = False,
 ):
     """List issues in a table format with filtering."""
     config = get_config()
@@ -371,7 +487,7 @@ def list_cmd(
     
     # Validation
     if status and status.lower() not in ["open", "closed", "backlog", "all"]:
-         console.print(f"[red]Invalid status:[/red] {status}. Use open, closed, backlog or all.")
+         OutputManager.error(f"Invalid status: {status}. Use open, closed, backlog or all.")
          raise typer.Exit(code=1)
          
     target_status = status.lower() if status else "open"
@@ -382,7 +498,7 @@ def list_cmd(
     for i in issues:
         # Status Filter
         if target_status != "all":
-            if i.status.value != target_status:
+            if i.status != target_status:
                 continue
                 
         # Type Filter
@@ -395,12 +511,13 @@ def list_cmd(
             
         filtered.append(i)
         
-    # Sort: Updated Descending
-        filtered.append(i)
-        
     # Sort: Updated Descending
     filtered.sort(key=lambda x: x.updated_at, reverse=True)
     
+    if OutputManager.is_agent_mode():
+        OutputManager.print(filtered)
+        return
+
     # Render
     _render_issues_table(filtered, title=f"Issues ({len(filtered)})")
 
@@ -430,13 +547,13 @@ def _render_issues_table(issues: List[IssueMetadata], title: str = "Issues"):
         t_color = type_colors.get(i.type, "white")
         s_color = status_colors.get(i.status, "white")
         
-        stage_str = i.stage.value if i.stage else "-"
+        stage_str = i.stage if i.stage else "-"
         updated_str = i.updated_at.strftime("%Y-%m-%d %H:%M")
         
         table.add_row(
             i.id,
-            f"[{t_color}]{i.type.value}[/{t_color}]",
-            f"[{s_color}]{i.status.value}[/{s_color}]",
+            f"[{t_color}]{i.type}[/{t_color}]",
+            f"[{s_color}]{i.status}[/{s_color}]",
             stage_str,
             i.title,
             updated_str
@@ -448,6 +565,7 @@ def _render_issues_table(issues: List[IssueMetadata], title: str = "Issues"):
 def query_cmd(
     query: str = typer.Argument(..., help="Search query (e.g. '+bug -ui' or 'login')"),
     root: Optional[str] = typer.Option(None, "--root", help="Override issues root directory"),
+    json: AgentOutput = False,
 ):
     """
     Search issues using advanced syntax.
@@ -468,6 +586,10 @@ def query_cmd(
     # For now, updated at descending is useful.
     results.sort(key=lambda x: x.updated_at, reverse=True)
     
+    if OutputManager.is_agent_mode():
+        OutputManager.print(results)
+        return
+
     _render_issues_table(results, title=f"Search Results for '{query}' ({len(results)})")
 
 @app.command("scope")
@@ -477,6 +599,7 @@ def scope(
     recursive: bool = typer.Option(False, "--recursive", "-r", help="Recursively scan subdirectories"),
     root: Optional[str] = typer.Option(None, "--root", help="Override issues root directory"),
     workspace: bool = typer.Option(False, "--workspace", "-w", help="Include issues from workspace members"),
+    json: AgentOutput = False,
 ):
     """Show progress tree."""
     config = get_config()
@@ -494,12 +617,16 @@ def scope(
             
     issues = filtered_issues
 
+    if OutputManager.is_agent_mode():
+        OutputManager.print(issues)
+        return
+
     tree = Tree(f"[bold blue]Monoco Issue Scope[/bold blue]")
-    epics = sorted([i for i in issues if i.type == IssueType.EPIC], key=lambda x: x.id)
-    stories = [i for i in issues if i.type == IssueType.FEATURE]
-    tasks = [i for i in issues if i.type in [IssueType.CHORE, IssueType.FIX]]
+    epics = sorted([i for i in issues if i.type == "epic"], key=lambda x: x.id)
+    stories = [i for i in issues if i.type == "feature"]
+    tasks = [i for i in issues if i.type in ["chore", "fix"]]
 
-    status_map = {IssueStatus.OPEN: "[blue]●[/blue]", IssueStatus.CLOSED: "[green]✔[/green]", IssueStatus.BACKLOG: "[dim]💤[/dim]"}
+    status_map = {"open": "[blue]●[/blue]", "closed": "[green]✔[/green]", "backlog": "[dim]💤[/dim]"}
 
     for epic in epics:
         epic_node = tree.add(f"{status_map[epic.status]} [bold]{epic.id}[/bold]: {epic.title}")
@@ -512,16 +639,112 @@ def scope(
 
     console.print(Panel(tree, expand=False))
 
+@app.command("sync-files")
+def sync_files(
+    issue_id: Optional[str] = typer.Argument(None, help="Issue ID to sync (default: current context)"),
+    root: Optional[str] = typer.Option(None, "--root", help="Override issues root directory"),
+    json: AgentOutput = False,
+):
+    """
+    Sync issue 'files' field with git changed files.
+    """
+    config = get_config()
+    issues_root = _resolve_issues_root(config, root)
+    project_root = _resolve_project_root(config)
+    
+    if not issue_id:
+        # Infer from branch
+        from monoco.core import git
+        current = git.get_current_branch(project_root)
+        # Try to parse ID from branch "feat/issue-123-slug"
+        import re
+        match = re.search(r"(?:feat|fix|chore|epic)/([a-zA-Z]+-\d+)", current)
+        if match:
+             issue_id = match.group(1).upper()
+        else:
+             OutputManager.error("Cannot infer Issue ID from current branch. Please specify Issue ID.")
+             raise typer.Exit(code=1)
+
+    try:
+        changed = core.sync_issue_files(issues_root, issue_id, project_root)
+        OutputManager.print({
+            "id": issue_id,
+            "status": "synced",
+            "files": changed
+        })
+    except Exception as e:
+        OutputManager.error(str(e))
+        raise typer.Exit(code=1)
+
+@app.command("inspect")
+def inspect(
+    target: str = typer.Argument(..., help="Issue ID or File Path"),
+    root: Optional[str] = typer.Option(None, "--root", help="Override issues root directory"),
+    ast: bool = typer.Option(False, "--ast", help="Output JSON AST structure for debugging"),
+    json: AgentOutput = False,
+):
+    """
+    Inspect a specific issue and return its metadata (including actions).
+    """
+    config = get_config()
+    issues_root = _resolve_issues_root(config, root)
+    
+    # Try as Path
+    target_path = Path(target)
+    if target_path.exists() and target_path.is_file():
+        path = target_path
+    else:
+        # Try as ID
+        # Search path logic is needed? Or core.find_issue_path
+        path = core.find_issue_path(issues_root, target)
+        if not path:
+             OutputManager.error(f"Issue or file {target} not found.")
+             raise typer.Exit(code=1)
+    
+    # AST Debug Mode
+    if ast:
+        from .domain.parser import MarkdownParser
+        content = path.read_text()
+        try:
+            domain_issue = MarkdownParser.parse(content, path=str(path))
+            print(domain_issue.model_dump_json(indent=2))
+        except Exception as e:
+            OutputManager.error(f"Failed to parse AST: {e}")
+            raise typer.Exit(code=1)
+        return
+
+    # Normal Mode
+    meta = core.parse_issue(path)
+        
+    if not meta:
+         OutputManager.error(f"Could not parse issue {target}.")
+         raise typer.Exit(code=1)
+
+    # In JSON mode (AgentOutput), we might want to return rich data
+    if OutputManager.is_agent_mode():
+        OutputManager.print(meta)
+    else:
+        # For human, print yaml-like or table
+        console.print(meta)
+
 @app.command("lint")
 def lint(
     recursive: bool = typer.Option(False, "--recursive", "-r", help="Recursively scan subdirectories"),
+    fix: bool = typer.Option(False, "--fix", help="Attempt to automatically fix issues (e.g. missing headings)"),
+    format: str = typer.Option("table", "--format", "-f", help="Output format (table, json)"),
+    file: Optional[str] = typer.Option(None, "--file", help="Validate a single file instead of scanning the entire workspace"),
     root: Optional[str] = typer.Option(None, "--root", help="Override issues root directory"),
+    json: AgentOutput = False,
 ):
     """Verify the integrity of the Issues directory (declarative check)."""
     from . import linter
     config = get_config()
     issues_root = _resolve_issues_root(config, root)
-    linter.run_lint(issues_root, recursive=recursive)
+    
+    if OutputManager.is_agent_mode():
+        format = "json"
+
+    linter.run_lint(issues_root, recursive=recursive, fix=fix, format=format, file_path=file)
 
 def _resolve_issues_root(config, cli_root: Optional[str]) -> Path:
     """
@@ -544,27 +767,9 @@ def _resolve_issues_root(config, cli_root: Optional[str]) -> Path:
         return path
     
     # 2. Handle Default / Contextual Execution (No --root)
-    # We need to detect if we are in a Workspace Root with multiple projects
+    # Strict Workspace Check: If not in a project root, we rely on the config root.
+    # (The global app callback already enforces presence of .monoco for most commands)
     cwd = Path.cwd()
-    
-    # If CWD is NOT a project root (no monoco.yaml/Issues), scan for subprojects
-    if not is_project_root(cwd):
-        subprojects = find_projects(cwd)
-        if len(subprojects) > 1:
-            console.print(f"[yellow]Workspace detected with {len(subprojects)} projects:[/yellow]")
-            for p in subprojects:
-                console.print(f" - [bold]{p.name}[/bold]")
-            console.print("\n[yellow]Please specify a project using --root <PATH>.[/yellow]")
-            # We don't exit here strictly, but usually this means we can't find 'Issues' in CWD anyway
-            # so the config fallbacks below will likely fail or point to non-existent CWD/Issues.
-            # But let's fail fast to be helpful.
-            raise typer.Exit(code=1)
-        elif len(subprojects) == 1:
-            # Auto-select the only child project?
-            # It's safer to require explicit intent, but let's try to be helpful if it's obvious.
-            # However, standard behavior is usually "operate on current dir". 
-            # Let's stick to standard config resolution, but maybe warn.
-            pass
 
     # 3. Config Fallback
     config_issues_path = Path(config.paths.issues)
@@ -708,3 +913,40 @@ def commit(
     except Exception as e:
          console.print(f"[red]Git Error:[/red] {e}")
          raise typer.Exit(code=1)
+
+@lsp_app.command("definition")
+def lsp_definition(
+    file: str = typer.Option(..., "--file", "-f", help="Abs path to file"),
+    line: int = typer.Option(..., "--line", "-l", help="0-indexed line number"),
+    character: int = typer.Option(..., "--char", "-c", help="0-indexed character number"),
+):
+    """
+    Handle textDocument/definition request.
+    Output: JSON Location | null
+    """
+    import json
+    from monoco.core.lsp import Position
+    from monoco.features.issue.lsp import DefinitionProvider
+
+    config = get_config()
+    # Workspace Root resolution is key here. 
+    # If we are in a workspace, we want the workspace root, not just issue root.
+    # _resolve_project_root returns the closest project root or monoco root.
+    workspace_root = _resolve_project_root(config)
+    # Search for topmost workspace root to enable cross-project navigation
+    current_best = workspace_root
+    for parent in [workspace_root] + list(workspace_root.parents):
+        if (parent / ".monoco" / "workspace.yaml").exists() or (parent / ".monoco" / "project.yaml").exists():
+            current_best = parent
+    workspace_root = current_best
+    
+    provider = DefinitionProvider(workspace_root)
+    file_path = Path(file)
+    
+    locations = provider.provide_definition(
+        file_path, 
+        Position(line=line, character=character)
+    )
+    
+    # helper to serialize
+    print(json.dumps([l.model_dump(mode='json') for l in locations]))