devcouncil 0.1.0

package/src/devcouncil/cli/commands/run.py

@@ -0,0 +1,224 @@
+import typer
+import json
+from rich.console import Console
+from pathlib import Path
+from devcouncil.storage.db import get_db
+from devcouncil.storage.repositories import TaskRepository, RequirementRepository
+from devcouncil.executors.mini_swe import MiniSWEExecutor
+from devcouncil.executors.openhands import OpenHandsExecutor
+from devcouncil.executors.native.agent import NativeAgent
+from devcouncil.llm.provider import OpenRouterProvider
+from devcouncil.llm.router import ModelRouter
+from devcouncil.app.config import load_config, get_api_key
+from devcouncil.domain.evidence import CommandResult, DiffEvidence, TestEvidence
+from devcouncil.storage.repositories import GapRepository, EvidenceRepository, StateRepository
+from devcouncil.verification.verifier import Verifier
+from devcouncil.app.state_machine import ProjectPhase
+
+console = Console()
+
+def _current_changed_files() -> list[str]:
+    from devcouncil.verification.verifier import Verifier
+
+    return Verifier(Path(".")).get_changed_files()
+
+def _capture_after_patch(task_id: str):
+    """Capture the diff after task execution for use by rollback."""
+    try:
+        from devcouncil.verification.verifier import Verifier
+
+        checkpoint_dir = Path(".devcouncil/checkpoints")
+        checkpoint_dir.mkdir(exist_ok=True)
+        diff = Verifier(Path(".")).get_diff()
+        if diff:
+            with open(checkpoint_dir / f"{task_id}-after.patch", "w", encoding="utf-8") as f:
+                f.write(diff)
+    except Exception:
+        pass  # Non-critical — don't block execution
+
+def _capture_before_snapshot(task_id: str):
+    checkpoint_dir = Path(".devcouncil/checkpoints")
+    checkpoint_dir.mkdir(exist_ok=True)
+    snapshot = {
+        "task_id": task_id,
+        "changed_files": _current_changed_files(),
+    }
+    (checkpoint_dir / f"{task_id}-before.json").write_text(
+        json.dumps(snapshot, indent=2),
+        encoding="utf-8",
+    )
+
+def _record_project_phase(session, phase: ProjectPhase):
+    StateRepository(session).record_phase(phase.value)
+
+def _verify_after_execution(session, task, reqs, router=None) -> bool:
+    """Run deterministic verification after an automated executor finishes."""
+    import asyncio
+
+    verifier = Verifier(Path("."), router=router)
+    gaps, evidence = asyncio.run(verifier.verify_task(task, reqs))
+
+    gap_repo = GapRepository(session)
+    evidence_repo = EvidenceRepository(session)
+    gap_repo.delete_for_task(task.id)
+    evidence_repo.delete_for_task(task.id)
+
+    for gap in gaps:
+        gap_repo.save(gap)
+
+    for ev in evidence:
+        if isinstance(ev, CommandResult):
+            evidence_repo.save_command_result(task.id, ev)
+        elif isinstance(ev, DiffEvidence):
+            evidence_repo.save_diff_evidence(ev)
+        elif isinstance(ev, TestEvidence):
+            evidence_repo.save_test_evidence(ev, task.id)
+
+    task.status = "blocked" if any(g.blocking for g in gaps) else "verified"
+    return task.status == "verified"
+
+def run(
+    task_id: str = typer.Argument(..., help="ID of the task to run"),
+    executor: str = typer.Option("manual", "--executor", "-e", help="Executor to use (manual, shell)"),
+):
+    """
+    Execute a specific task.
+    """
+    db = get_db()
+    if not db:
+        console.print("[red]DevCouncil not initialized. Run 'dev init' first.[/red]")
+        return
+
+    with db.get_session() as session:
+        task_repo = TaskRepository(session)
+        task = task_repo.get_by_id(task_id)
+        if not task:
+            console.print(f"[red]Task {task_id} not found.[/red]")
+            return
+
+        from devcouncil.gating.policy import GatePolicy
+        policy = GatePolicy()
+        gate_result = policy.check_task_ready(task, Path("."))
+        if not gate_result.passed:
+            console.print(f"[red]Task {task_id} is not ready for execution.[/red]")
+            for gap in gate_result.gaps:
+                if gap.blocking:
+                    console.print(f" - [red][BLOCKING][/red] {gap.description} (Fix: {gap.recommended_fix})")
+            return
+
+        console.print(f"Running task [bold]{task_id}[/bold] using [bold]{executor}[/bold] executor...")
+
+        # 1. Create Git checkpoint
+        try:
+            from devcouncil.verification.verifier import Verifier
+
+            checkpoint_dir = Path(".devcouncil/checkpoints")
+            checkpoint_dir.mkdir(exist_ok=True)
+            _capture_before_snapshot(task_id)
+            diff = Verifier(Path(".")).get_diff()
+            if diff:
+                with open(checkpoint_dir / f"{task_id}-before.patch", "w", encoding="utf-8") as f:
+                    f.write(diff)
+                console.print(f"Created git checkpoint at {checkpoint_dir}/{task_id}-before.patch")
+        except Exception as e:
+            console.print(f"[yellow]Warning: Failed to create git checkpoint: {e}[/yellow]")
+
+        if executor == "manual":
+            _record_project_phase(session, ProjectPhase.TASK_EXECUTING)
+            task.status = "running"
+            task_repo.save(task)
+            console.print(f"\n[green]Task {task_id} is now marked as RUNNING.[/green]")
+            console.print("Use 'dev prompt TASK-ID' to get the prompt for this task.")
+            console.print("When finished, use 'dev verify TASK-ID' to check the results.")
+        elif executor == "mini":
+            _record_project_phase(session, ProjectPhase.TASK_EXECUTING)
+            req_repo = RequirementRepository(session)
+            reqs = req_repo.get_all()
+            mini_executor = MiniSWEExecutor(Path("."))
+            exec_result = mini_executor.run_task(task, reqs)
+            _capture_after_patch(task_id)
+            if exec_result.success:
+                _record_project_phase(session, ProjectPhase.TASK_VERIFYING)
+                verified = _verify_after_execution(session, task, reqs)
+                _record_project_phase(
+                    session,
+                    ProjectPhase.TASK_VERIFIED if verified else ProjectPhase.TASK_BLOCKED,
+                )
+                task_repo.save(task)
+                if verified:
+                    console.print(f"\n[green]mini-SWE-agent finished and task {task_id} verified.[/green]")
+                else:
+                    console.print(f"\n[yellow]mini-SWE-agent finished, but task {task_id} is blocked by verification gaps.[/yellow]")
+            else:
+                console.print("\n[red]mini-SWE-agent failed to start or execute.[/red]")
+        elif executor == "openhands":
+            _record_project_phase(session, ProjectPhase.TASK_EXECUTING)
+            req_repo = RequirementRepository(session)
+            reqs = req_repo.get_all()
+            oh_executor = OpenHandsExecutor(Path("."))
+            exec_result = oh_executor.run_task(task, reqs)
+            _capture_after_patch(task_id)
+            if exec_result.success:
+                _record_project_phase(session, ProjectPhase.TASK_VERIFYING)
+                verified = _verify_after_execution(session, task, reqs)
+                _record_project_phase(
+                    session,
+                    ProjectPhase.TASK_VERIFIED if verified else ProjectPhase.TASK_BLOCKED,
+                )
+                task_repo.save(task)
+                if verified:
+                    console.print(f"\n[green]OpenHands finished and task {task_id} verified.[/green]")
+                else:
+                    console.print(f"\n[yellow]OpenHands finished, but task {task_id} is blocked by verification gaps.[/yellow]")
+            else:
+                console.print("\n[red]OpenHands failed to start or execute.[/red]")
+        elif executor == "native":
+            # Load config for model routing and permissions
+            try:
+                config = load_config(Path("."))
+                api_key = get_api_key(config.models.provider)
+            except (FileNotFoundError, ValueError) as e:
+                console.print(f"[red]{e}[/red]")
+                return
+            
+            provider = OpenRouterProvider(api_key)
+            role_config = {name: role.model_dump() for name, role in config.models.roles.items()}
+            router = ModelRouter(provider, role_config)
+            
+            # Setup Permission System
+            from devcouncil.execution.permissions import PermissionPolicy, PermissionManager
+            from devcouncil.execution.task_runner import TaskRunner
+            
+            # Populate policy from config commands
+            allowed_cmds = config.commands.test + config.commands.lint + config.commands.typecheck
+            policy = PermissionPolicy(
+                allowed_shell_commands=allowed_cmds,
+            )
+            perm_manager = PermissionManager(policy, Path("."))
+            task_runner = TaskRunner(Path("."), perm_manager)
+            
+            req_repo = RequirementRepository(session)
+            reqs = req_repo.get_all()
+            
+            import asyncio
+            _record_project_phase(session, ProjectPhase.TASK_EXECUTING)
+            agent = NativeAgent(router, task_runner)
+            exec_result = asyncio.run(agent.run_task(task, reqs))
+            _capture_after_patch(task_id)
+            
+            if exec_result.success:
+                _record_project_phase(session, ProjectPhase.TASK_VERIFYING)
+                verified = _verify_after_execution(session, task, reqs, router=router)
+                _record_project_phase(
+                    session,
+                    ProjectPhase.TASK_VERIFIED if verified else ProjectPhase.TASK_BLOCKED,
+                )
+                task_repo.save(task)
+                if verified:
+                    console.print(f"\n[green]Native agent finished and task {task_id} verified.[/green]")
+                else:
+                    console.print(f"\n[yellow]Native agent finished, but task {task_id} is blocked by verification gaps.[/yellow]")
+            else:
+                console.print("\n[red]Native agent failed during execution.[/red]")
+        else:
+            console.print(f"[red]Executor {executor} not yet implemented.[/red]")

package/src/devcouncil/cli/commands/setup.py

@@ -0,0 +1,82 @@
+from pathlib import Path
+import shutil
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+
+from devcouncil.cli.commands.doctor import render_doctor_check
+from devcouncil.cli.commands.init import initialize_project
+from devcouncil.cli.commands.integrate import _codex_command, _configure, _gemini_command
+
+app = typer.Typer()
+console = Console()
+
+
+@app.callback(invoke_without_command=True)
+def setup(
+    ctx: typer.Context,
+    project_root: Path = typer.Option(
+        Path("."),
+        "--project-root",
+        help="Target project repository root. Defaults to the terminal's current directory.",
+    ),
+    name: str | None = typer.Option(None, "--name", "-n", help="Project name for .devcouncil/config.yaml."),
+    integrate: bool = typer.Option(False, "--integrate", help="Configure supported coding CLI MCP integrations."),
+    apply: bool = typer.Option(False, "--apply", help="Apply integration config instead of previewing commands."),
+    gemini_scope: str = typer.Option("project", "--gemini-scope", help="Gemini MCP config scope: project or user."),
+):
+    """
+    Initialize DevCouncil from a normal terminal in the target repository root.
+
+    Use the coding CLI later only for the generated dev prompt output.
+    """
+    if ctx.invoked_subcommand is not None:
+        return
+
+    if gemini_scope not in {"project", "user"}:
+        console.print("[red]--gemini-scope must be 'project' or 'user'.[/red]")
+        raise typer.Exit(code=2)
+
+    root = project_root.expanduser().resolve()
+    created = initialize_project(root, project_name=name)
+    if not created:
+        console.print(f"[yellow]DevCouncil is already initialized at {root / '.devcouncil'}.[/yellow]")
+
+    console.print()
+    render_doctor_check()
+
+    if integrate:
+        console.print()
+        console.print("[bold]Coding CLI integration[/bold]")
+        commands = [
+            ("Codex CLI", _codex_command(root)),
+            ("Gemini CLI", _gemini_command(root, gemini_scope)),
+        ]
+        results = []
+        for tool, command in commands:
+            if apply and not shutil.which(command[0]):
+                console.print(f"[yellow]{tool} CLI not found on PATH. Skipping optional integration.[/yellow]")
+                continue
+            results.append(_configure(tool, command, apply))
+        if apply and any(not ok for ok in results):
+            raise typer.Exit(code=1)
+
+    console.print()
+    console.print(Panel.fit(
+        "\n".join([
+            "[bold]Next commands[/bold]",
+            f"Keep running DevCouncil commands in this terminal at: {root}",
+            "dev plan \"Describe the implementation goal\"",
+            "dev tasks",
+            "dev run TASK-001 --executor manual",
+            "dev prompt TASK-001",
+            "Paste only the dev prompt output into your coding CLI.",
+            "dev verify TASK-001",
+            "",
+            "Use [bold]dev setup --integrate[/bold] to preview coding CLI MCP setup.",
+            "Use [bold]dev setup --integrate --apply[/bold] to configure detected clients.",
+        ]),
+        title="DevCouncil is ready",
+        border_style="green",
+    ))

package/src/devcouncil/cli/commands/show.py

@@ -0,0 +1,57 @@
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from devcouncil.storage.db import get_db
+from devcouncil.storage.repositories import TaskRepository, RequirementRepository
+
+app = typer.Typer()
+console = Console()
+
+@app.callback(invoke_without_command=True)
+def show(
+    ctx: typer.Context,
+    task_id: str = typer.Argument(..., help="ID of the task to show"),
+):
+    """
+    Show details of a specific task.
+    """
+    if ctx.invoked_subcommand is not None:
+        return
+
+    db = get_db()
+    if not db:
+        console.print("[red]DevCouncil not initialized. Run 'dev init' first.[/red]")
+        raise typer.Exit(code=1)
+
+    with db.get_session() as session:
+        task_repo = TaskRepository(session)
+        req_repo = RequirementRepository(session)
+        
+        task = task_repo.get_by_id(task_id)
+        if not task:
+            console.print(f"[red]Task {task_id} not found.[/red]")
+            raise typer.Exit(code=1)
+        
+        reqs = req_repo.get_all()
+        req_map = {r.id: r for r in reqs}
+
+        output = f"[bold]Status:[/bold] {task.status}\n\n"
+        output += f"[bold]Description:[/bold]\n{task.description}\n\n"
+        
+        output += "[bold]Linked Requirements:[/bold]\n"
+        for req_id in task.requirement_ids:
+            req = req_map.get(req_id)
+            if req:
+                output += f"  - [cyan]{req.id}[/cyan]: {req.title}\n"
+            else:
+                output += f"  - [cyan]{req_id}[/cyan]: (Requirement not found)\n"
+                
+        output += "\n[bold]Planned Files:[/bold]\n"
+        for pf in task.planned_files:
+            output += f"  - {pf.path} ({pf.allowed_change}): {pf.reason}\n"
+            
+        output += "\n[bold]Expected Tests:[/bold]\n"
+        for et in task.expected_tests:
+            output += f"  - {et}\n"
+
+        console.print(Panel(output, title=f"Task {task.id}: {task.title}", expand=False))

package/src/devcouncil/cli/commands/status.py

@@ -0,0 +1,105 @@
+from rich.console import Console
+from rich.table import Table
+from rich.panel import Panel
+from pathlib import Path
+import json
+from devcouncil.storage.db import get_db
+from devcouncil.storage.repositories import ArtifactGraphRepository
+from devcouncil.telemetry.cost import CostEstimator
+
+console = Console()
+
+def status():
+    """
+    Show the current status of the DevCouncil project.
+    """
+    db = get_db()
+    if not db:
+        console.print("[yellow]DevCouncil not initialized in this directory.[/yellow]")
+        console.print("Run [bold]dev init[/bold] to get started.")
+        return
+
+    with db.get_session() as session:
+        graph_repo = ArtifactGraphRepository(session)
+        graph = graph_repo.load_graph()
+        summary = graph.coverage_summary()
+
+        reqs = list(graph.requirements.values())
+        tasks = list(graph.tasks.values())
+        blocking_gaps = graph.blocking_gaps()
+
+        # Determine phase
+        if not reqs and not tasks:
+            phase = "NEW"
+        elif reqs and not tasks:
+            phase = "REQUIREMENTS_DRAFTED"
+        elif blocking_gaps:
+            phase = "TASK_BLOCKED"
+        elif tasks:
+            statuses = {t.status for t in tasks}
+            if "running" in statuses:
+                phase = "TASK_EXECUTING"
+            elif "blocked" in statuses:
+                phase = "TASK_BLOCKED"
+            elif all(s in ("verified", "done") for s in statuses):
+                phase = "PROJECT_DONE"
+            else:
+                phase = "PLAN_APPROVED"
+        else:
+            phase = "NEW"
+
+        # Phase color
+        phase_colors = {
+            "NEW": "yellow",
+            "REQUIREMENTS_DRAFTED": "cyan",
+            "PLAN_APPROVED": "green",
+            "TASK_EXECUTING": "blue",
+            "TASK_BLOCKED": "red",
+            "PROJECT_DONE": "green bold",
+        }
+        phase_color = phase_colors.get(phase, "white")
+
+        # Calculate cost
+        total_cost = 0.0
+        log_file = Path(".devcouncil/logs/model_calls.jsonl")
+        if log_file.exists():
+            with open(log_file, "r", encoding="utf-8") as f:
+                for line in f:
+                    try:
+                        entry = json.loads(line)
+                        total_cost += CostEstimator.estimate_cost(
+                            entry.get("response", {}).get("model", ""),
+                            entry.get("usage", {})
+                        )
+                    except Exception:
+                        continue
+
+        console.print(Panel(
+            f"[bold]Phase:[/bold] [{phase_color}]{phase}[/{phase_color}]\n"
+            f"[bold]Requirements:[/bold] {summary['total_requirements']} ({summary['requirements_without_tasks']} unmapped)\n"
+            f"[bold]Tasks:[/bold] {summary['total_tasks']} ({summary['tasks_without_requirements']} orphaned)\n"
+            f"[bold]Acceptance Criteria:[/bold] {summary['total_ac']} ({summary['ac_without_evidence']} unverified)\n"
+            f"[bold]Gaps:[/bold] {summary['total_gaps']} ({summary['blocking_gaps']} blocking)\n"
+            f"[bold]Total Cost:[/bold] ${total_cost:.4f}",
+            title="DevCouncil Status",
+            expand=False,
+        ))
+
+        if tasks:
+            table = Table(title="Task Summary")
+            table.add_column("Status", style="magenta")
+            table.add_column("Count", justify="right")
+
+            status_counts: dict[str, int] = {}
+            for t in tasks:
+                status_counts[t.status] = status_counts.get(t.status, 0) + 1
+            for s, count in sorted(status_counts.items()):
+                table.add_row(s, str(count))
+            console.print(table)
+
+        if blocking_gaps:
+            console.print(f"\n[red bold]WARNING: {len(blocking_gaps)} blocking gap(s) must be resolved:[/red bold]")
+            for g in blocking_gaps[:5]:
+                console.print(f"  - [red]{g.id}[/red]: {g.description[:80]}")
+            if len(blocking_gaps) > 5:
+                console.print(f"  ... and {len(blocking_gaps) - 5} more. Run [bold]dev report[/bold] for details.")

package/src/devcouncil/cli/commands/tasks.py

@@ -0,0 +1,41 @@
+import typer
+from rich.console import Console
+from rich.table import Table
+from devcouncil.storage.db import get_db
+from devcouncil.storage.repositories import TaskRepository
+
+app = typer.Typer()
+console = Console()
+
+@app.callback(invoke_without_command=True)
+def tasks(ctx: typer.Context):
+    """
+    List task graph and task gate status.
+    """
+    if ctx.invoked_subcommand is not None:
+        return
+
+    db = get_db()
+    if not db:
+        console.print("[red]DevCouncil not initialized. Run 'dev init' first.[/red]")
+        raise typer.Exit(code=1)
+
+    with db.get_session() as session:
+        task_repo = TaskRepository(session)
+        tasks_list = task_repo.get_all()
+        
+        if not tasks_list:
+            console.print("No tasks found. Run 'dev plan' to generate tasks.")
+            return
+
+        table = Table(title="DevCouncil Tasks")
+        table.add_column("Task ID", style="cyan", no_wrap=True)
+        table.add_column("Title", style="white")
+        table.add_column("Status", style="magenta")
+        table.add_column("Linked Reqs", style="green")
+
+        for t in tasks_list:
+            reqs = ", ".join(t.requirement_ids)
+            table.add_row(t.id, t.title, t.status, reqs)
+
+        console.print(table)

package/src/devcouncil/cli/commands/trace.py

@@ -0,0 +1,43 @@
+import json
+import time
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from devcouncil.telemetry.traces import read_trace_events
+
+app = typer.Typer(help="Inspect DevCouncil trace events.")
+console = Console()
+
+
+@app.command("tail")
+def tail(
+    follow: bool = typer.Option(False, "--follow", "-f", help="Continue polling for new events."),
+    limit: int = typer.Option(50, "--limit", "-n", help="Maximum events to print before following."),
+    jsonl: bool = typer.Option(True, "--jsonl/--pretty", help="Print JSONL or compact text rows."),
+):
+    """Print the DevCouncil trace JSONL stream for replay or debugging."""
+    project_root = Path(".")
+    printed = 0
+
+    def emit_new(start_index: int) -> int:
+        events = list(read_trace_events(project_root))
+        selected = events[start_index:]
+        for event in selected:
+            if jsonl:
+                typer.echo(event.model_dump_json())
+            else:
+                console.print(
+                    f"{event.timestamp} {event.type} "
+                    f"{event.task_id or '-'} {event.summary or json.dumps(event.details)}"
+                )
+        return len(events)
+
+    events = list(read_trace_events(project_root))
+    start = max(0, len(events) - limit)
+    printed = emit_new(start)
+
+    while follow:
+        time.sleep(1)
+        printed = emit_new(printed)