devcouncil 0.1.0

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

@@ -0,0 +1,276 @@
+import typer
+import asyncio
+import json
+import datetime
+from typing import Any
+from rich.console import Console
+from rich.panel import Panel
+from rich.progress import Progress, SpinnerColumn, TextColumn
+from pathlib import Path
+
+from devcouncil.storage.db import get_db
+from devcouncil.storage.repositories import (
+    RequirementRepository,
+    AssumptionRepository,
+    TaskRepository,
+    CritiqueFindingRepository,
+    GapRepository,
+)
+from devcouncil.indexing.repo_mapper import RepoMapper
+from devcouncil.integrations.code_review_graph import CodeReviewGraphAdapter
+from devcouncil.llm.provider import OpenRouterProvider, MockProvider
+from devcouncil.llm.router import ModelRouter
+from devcouncil.planning.spec_service import SpecService
+from devcouncil.planning.plan_service import PlanService
+from devcouncil.planning.critique_service import CritiqueService
+from devcouncil.planning.arbiter_service import ArbiterService
+from devcouncil.gating.policy import GatePolicy
+from devcouncil.app.orchestrator import Orchestrator
+from devcouncil.app.state_machine import ProjectPhase
+from devcouncil.app.config import load_config, get_api_key
+
+app = typer.Typer()
+console = Console()
+
+
+def _decision_ids(items: list[Any]) -> set[str]:
+    ids: set[str] = set()
+    for item in items:
+        if isinstance(item, str):
+            ids.add(item)
+        elif isinstance(item, dict):
+            value = item.get("id") or item.get("finding_id")
+            if value:
+                ids.add(str(value))
+    return ids
+
+
+def _reconcile_findings(findings, decision):
+    accepted_ids = set(decision.accepted_finding_ids)
+    rejected_ids = _decision_ids(decision.rejected_finding_ids)
+    reconciled = []
+    for finding in findings:
+        if finding.id in accepted_ids:
+            reconciled.append(finding.model_copy(update={"status": "converted"}))
+        elif finding.id in rejected_ids:
+            reconciled.append(finding.model_copy(update={"status": "rejected"}))
+        else:
+            reconciled.append(finding)
+    return reconciled
+
+async def run_plan_flow(
+    goal: str,
+    requirements_only: bool = False,
+    dry_run: bool = False,
+    persist: bool = True,
+):
+    db = get_db()
+    if not db:
+        console.print("[red]DevCouncil not initialized. Run 'dev init' first.[/red]")
+        return
+
+    # Load validated config
+    config = load_config(Path("."))
+
+    api_key = None
+    if not dry_run:
+        try:
+            api_key = get_api_key(config.models.provider)
+        except ValueError as e:
+            console.print(f"[red]{e}[/red]")
+            return
+
+    orchestrator = Orchestrator(Path("."), persist_state=persist)
+    orchestrator.reset_state_machine(ProjectPhase.NEW)
+    run_id = datetime.datetime.now(datetime.timezone.utc).strftime("%Y%m%dT%H%M%SZ") + "-plan"
+    await orchestrator.start_run(run_id, goal)
+
+    if dry_run:
+        # Override config models to be unique roles for mock mapping
+        config.models.roles["spec_writer"].model = "mock/spec_writer"
+        config.models.roles["planner_a"].model = "mock/planner_a"
+        config.models.roles["planner_b"].model = "mock/planner_b"
+        config.models.roles["critic_a"].model = "mock/critic_a"
+        config.models.roles["critic_b"].model = "mock/critic_b"
+        config.models.roles["arbiter"].model = "mock/arbiter"
+
+        provider = MockProvider()
+        provider.responses = {
+            "mock/spec_writer": json.dumps({
+                "requirements": [{"id": "REQ-001", "title": "Mock Req", "description": "Desc", "priority": "high", "source": "user", "acceptance_criteria": []}],
+                "assumptions": [],
+                "blocking_questions": []
+            }),
+            "mock/planner_a": [
+                json.dumps({
+                    "id": "PLAN-A", "rationale": "Simple", "tasks": [{"id": "TASK-001", "title": "Mock Task", "description": "Desc", "requirement_ids": ["REQ-001"], "acceptance_criterion_ids": [], "planned_files": [], "expected_tests": [], "allowed_commands": [], "status": "planned"}]
+                }),
+                json.dumps({"rebuttals": []})
+            ],
+            "mock/planner_b": [
+                json.dumps({
+                    "id": "PLAN-B", "rationale": "Robust", "tasks": [{"id": "TASK-001", "title": "Mock Task", "description": "Desc", "requirement_ids": ["REQ-001"], "acceptance_criterion_ids": [], "planned_files": [], "expected_tests": [], "allowed_commands": [], "status": "planned"}]
+                }),
+                json.dumps({"rebuttals": []})
+            ],
+            "mock/critic_a": '{"findings": []}',
+            "mock/critic_b": '{"findings": []}',
+            "mock/arbiter": json.dumps({
+                "accepted_finding_ids": [], "rejected_finding_ids": [], 
+                "final_requirements": [{"id": "REQ-001", "title": "Mock Req", "description": "Desc", "priority": "high", "source": "user", "acceptance_criteria": [{"id": "AC-1", "description": "Test it", "verification_method": "unit_test"}]}],
+                "final_tasks": [{"id": "TASK-001", "title": "Mock Task", "description": "Desc", "requirement_ids": ["REQ-001"], "acceptance_criterion_ids": ["AC-1"], "planned_files": [{"path": "test.py", "reason": "logic", "allowed_change": "modify"}], "expected_tests": [], "allowed_commands": [], "status": "planned"}]
+            }),
+        }
+        # Special case: PlanService calls use the same model names. 
+        # I'll modify PlanService to use a slightly different role string if needed, 
+        # but for Dry Run, let's just make the MockProvider return based on the schema requested.
+    else:
+        provider = OpenRouterProvider(api_key)
+
+    # Build role config after dry-run overrides so mocks are routed correctly.
+    role_config = {name: role.model_dump() for name, role in config.models.roles.items()}
+    router = ModelRouter(provider, role_config)
+    
+    spec_service = SpecService(router)
+    plan_service = PlanService(router)
+    critique_service = CritiqueService(router)
+    arbiter_service = ArbiterService(router)
+    mapper = RepoMapper(Path("."))
+
+    with Progress(
+        SpinnerColumn(),
+        TextColumn("[progress.description]{task.description}"),
+        transient=True,
+    ) as progress:
+        # 1. Repo Map
+        progress.add_task(description="Mapping repository...", total=None)
+        repo_map = mapper.map_repo(goal)
+        repo_map_json = repo_map.model_dump_json(indent=2)
+        orchestrator.save_run_artifact("repo_map.json", json.loads(repo_map_json))
+        graph_context = CodeReviewGraphAdapter(Path(".")).get_context()
+        if graph_context.available:
+            orchestrator.save_run_artifact("code_review_graph_context.json", graph_context.model_dump())
+        await orchestrator.transition_to(ProjectPhase.REPO_MAPPED)
+
+        # 2. Spec / Requirements
+        progress.add_task(description="Generating requirements...", total=None)
+        spec_output = await spec_service.generate_spec(goal, repo_map_json)
+        orchestrator.save_run_artifact("requirements.json", spec_output.model_dump())
+        await orchestrator.transition_to(ProjectPhase.REQUIREMENTS_DRAFTED)
+        
+        if requirements_only:
+            console.print(Panel(f"Found {len(spec_output.requirements)} requirements.", title="Requirements Generated"))
+            return
+
+        # 3. Independent Plans
+        progress.add_task(description="Generating Plan A (Pragmatic)...", total=None)
+        plan_a = await plan_service.generate_plan("planner_a", goal, json.dumps([r.model_dump() for r in spec_output.requirements]), repo_map_json)
+        orchestrator.save_run_artifact("plan_a.json", plan_a.model_dump())
+        
+        progress.add_task(description="Generating Plan B (Robust)...", total=None)
+        plan_b = await plan_service.generate_plan("planner_b", goal, json.dumps([r.model_dump() for r in spec_output.requirements]), repo_map_json)
+        orchestrator.save_run_artifact("plan_b.json", plan_b.model_dump())
+        await orchestrator.transition_to(ProjectPhase.PLANS_GENERATED)
+
+        # 4. Cross-Critique
+        progress.add_task(description="Critiquing Plan B...", total=None)
+        critique_a = await critique_service.generate_critique("critic_a", plan_b.model_dump_json(), json.dumps([r.model_dump() for r in spec_output.requirements]))
+        orchestrator.save_run_artifact("critique_a.json", critique_a.model_dump())
+        
+        progress.add_task(description="Critiquing Plan A...", total=None)
+        critique_b = await critique_service.generate_critique("critic_b", plan_a.model_dump_json(), json.dumps([r.model_dump() for r in spec_output.requirements]))
+        orchestrator.save_run_artifact("critique_b.json", critique_b.model_dump())
+        await orchestrator.transition_to(ProjectPhase.CRITIQUES_GENERATED)
+
+        # 5. Rebuttals
+        progress.add_task(description="Generating rebuttals...", total=None)
+        rebuttal_a = await critique_service.generate_rebuttal("planner_a", plan_a.model_dump_json(), critique_b.model_dump_json())
+        orchestrator.save_run_artifact("rebuttal_a.json", rebuttal_a.model_dump())
+        rebuttal_b = await critique_service.generate_rebuttal("planner_b", plan_b.model_dump_json(), critique_a.model_dump_json())
+        orchestrator.save_run_artifact("rebuttal_b.json", rebuttal_b.model_dump())
+
+        # 6. Arbitration
+        progress.add_task(description="Arbitrating final plan...", total=None)
+        decision = await arbiter_service.arbitrate(
+            goal,
+            json.dumps([r.model_dump() for r in spec_output.requirements]),
+            plan_a.model_dump_json(),
+            plan_b.model_dump_json(),
+            critique_a.model_dump_json(),
+            critique_b.model_dump_json(),
+            rebuttal_a.model_dump_json(),
+            rebuttal_b.model_dump_json()
+        )
+        orchestrator.save_run_artifact("decision.json", decision.model_dump())
+        await orchestrator.transition_to(ProjectPhase.ARBITRATED)
+        reconciled_findings = _reconcile_findings([*critique_a.findings, *critique_b.findings], decision)
+
+        # 7. Save to DB unless this is a non-persistent dry run.
+        if persist:
+            with db.get_session() as session:
+                req_repo = RequirementRepository(session)
+                assumption_repo = AssumptionRepository(session)
+                task_repo = TaskRepository(session)
+                finding_repo = CritiqueFindingRepository(session)
+                
+                for req in decision.final_requirements:
+                    req_repo.save(req)
+
+                for assumption in spec_output.assumptions:
+                    assumption_repo.save(assumption)
+                
+                for task in decision.final_tasks:
+                    task_repo.save(task)
+
+                for finding in reconciled_findings:
+                    finding_repo.save(finding)
+
+    console.print("[green]Planning complete![/green]")
+    if dry_run:
+        console.print("[blue](DRY RUN: No actual LLM calls were made)[/blue]")
+        if not persist:
+            console.print("[blue](DRY RUN: Final requirements/tasks were not persisted)[/blue]")
+    console.print(f"Final Requirements: [bold]{len(decision.final_requirements)}[/bold]")
+    console.print(f"Final Tasks: [bold]{len(decision.final_tasks)}[/bold]")
+    
+    # 8. Check Gates
+    policy = GatePolicy()
+    result = policy.check_plan_approval(
+        decision.final_requirements,
+        decision.final_tasks,
+        assumptions=spec_output.assumptions,
+        findings=reconciled_findings,
+        blocking_questions=spec_output.blocking_questions,
+    )
+    if persist:
+        with db.get_session() as session:
+            GapRepository(session).delete_plan_gaps()
+
+    if result.passed:
+        console.print("[green]Plan approved by gates.[/green]")
+        await orchestrator.transition_to(ProjectPhase.PLAN_APPROVED)
+    else:
+        if persist:
+            with db.get_session() as session:
+                gap_repo = GapRepository(session)
+                for gap in result.gaps:
+                    gap_repo.save(gap)
+        console.print("[yellow]Plan generated but failed gates. See status for gaps.[/yellow]")
+        await orchestrator.transition_to(ProjectPhase.AWAITING_USER_DECISIONS)
+
+@app.command()
+def plan(
+    goal: str = typer.Argument(..., help="The goal of the implementation"),
+    requirements_only: bool = typer.Option(False, "--requirements-only", help="Only generate requirements"),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Simulate planning without LLM calls"),
+    persist: bool = typer.Option(
+        False,
+        "--persist/--no-persist",
+        help="Persist dry-run planning artifacts into the main state database.",
+    ),
+):
+    """
+    Run the full planning cycle (Repo map -> Spec -> Plan A/B -> Critique -> Arbiter).
+    """
+    should_persist = persist or not dry_run
+    asyncio.run(run_plan_flow(goal, requirements_only, dry_run, should_persist))

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

@@ -0,0 +1,47 @@
+import typer
+from rich.console import Console
+from rich.markdown import Markdown
+from devcouncil.storage.db import get_db
+from devcouncil.storage.repositories import TaskRepository, RequirementRepository
+from pathlib import Path
+
+from devcouncil.execution.prompt_builder import PromptBuilder
+
+app = typer.Typer()
+console = Console()
+
+@app.callback(invoke_without_command=True)
+def prompt(
+    ctx: typer.Context,
+    task_id: str = typer.Argument(..., help="ID of the task to generate a prompt for"),
+    pretty: bool = typer.Option(False, "--pretty", help="Render the prompt for terminal reading."),
+):
+    """
+    Generate a constrained prompt for 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()
+        
+        builder = PromptBuilder(Path("."))
+        task_prompt = builder.build_task_prompt(task, reqs)
+
+        if pretty:
+            console.print(Markdown(task_prompt))
+        else:
+            typer.echo(task_prompt, nl=not task_prompt.endswith("\n"))

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

@@ -0,0 +1,69 @@
+import typer
+from rich.console import Console
+from devcouncil.storage.db import get_db
+from devcouncil.storage.repositories import TaskRepository, GapRepository
+from devcouncil.planning.repair_service import RepairService
+from devcouncil.execution.context_builder import ContextBuilder
+from devcouncil.llm.provider import OpenRouterProvider
+from devcouncil.llm.router import ModelRouter
+from devcouncil.app.config import load_config, get_api_key
+import asyncio
+from pathlib import Path
+
+app = typer.Typer()
+console = Console()
+
+async def run_repair_flow():
+    db = get_db()
+    if not db:
+        console.print("[red]DevCouncil not initialized. Run 'dev init' first.[/red]")
+        return
+
+    with db.get_session() as session:
+        gap_repo = GapRepository(session)
+        task_repo = TaskRepository(session)
+
+        all_gaps = gap_repo.get_all()
+        blocking_gaps = [g for g in all_gaps if g.blocking]
+        
+        if not blocking_gaps:
+            console.print("[green]No blocking gaps found. Nothing to repair![/green]")
+            return
+
+        console.print(f"Found [bold]{len(blocking_gaps)}[/bold] blocking gaps. Orchestrating repair plan...")
+
+        # Load router
+        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)
+        repair_service = RepairService(router)
+        context_builder = ContextBuilder(Path("."))
+        
+        # Build minimal context for repair.
+        project_context = context_builder.get_structure_summary()
+
+        repair_output = await repair_service.generate_repair_plan(blocking_gaps, str(project_context))
+        
+        for task in repair_output.suggested_tasks:
+            task.id = f"REPAIR-{task.id}"
+            task_repo.save(task)
+            console.print(f"  - Created intelligent repair task [bold]{task.id}[/bold]: {task.title}")
+
+        console.print(f"\n[green]Successfully generated {len(repair_output.suggested_tasks)} repair tasks.[/green]")
+
+@app.callback(invoke_without_command=True)
+def repair(ctx: typer.Context):
+    """
+    Convert blocking gaps into intelligent repair tasks using LLM inference.
+    """
+    if ctx.invoked_subcommand is not None:
+        return
+
+    asyncio.run(run_repair_flow())

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

@@ -0,0 +1,71 @@
+import typer
+from rich.console import Console
+from rich.markdown import Markdown
+from devcouncil.storage.db import get_db
+from devcouncil.storage.repositories import ArtifactGraphRepository
+from devcouncil.reporting.report_builder import ReportBuilder
+from devcouncil.integrations.github import GitHubIntegration
+from devcouncil.artifacts.graph import ArtifactGraph
+from devcouncil.telemetry.traces import TraceLogger
+import asyncio
+import os
+import subprocess
+from pathlib import Path
+
+app = typer.Typer()
+console = Console()
+
+async def run_github_report(graph: ArtifactGraph):
+    token = os.environ.get("GITHUB_TOKEN")
+    repo = os.environ.get("GITHUB_REPOSITORY") # e.g. owner/repo
+    
+    if not token or not repo:
+        console.print("[red]GITHUB_TOKEN and GITHUB_REPOSITORY must be set for GitHub reporting.[/red]")
+        return
+
+    try:
+        # Detect current SHA
+        sha = subprocess.check_output(["git", "rev-parse", "HEAD"]).decode().strip()
+        integration = GitHubIntegration(token, repo, sha)
+        await integration.report_verification(graph)
+        console.print(f"[green]Successfully reported to GitHub PR Checks for {repo} at {sha[:7]}[/green]")
+    except Exception as e:
+        console.print(f"[red]Failed to report to GitHub: {e}[/red]")
+
+@app.callback(invoke_without_command=True)
+def report(
+    ctx: typer.Context,
+    planning_only: bool = typer.Option(False, "--planning-only", help="Report only the planning phase status"),
+    json_format: bool = typer.Option(False, "--json", help="Output report in JSON format"),
+    github: bool = typer.Option(False, "--github", help="Post report to GitHub PR Checks"),
+):
+    """
+    Produce final evidence report.
+    """
+    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:
+        graph_repo = ArtifactGraphRepository(session)
+        graph = graph_repo.load_graph()
+        TraceLogger(Path(".")).log_event(
+            "report_generated",
+            {"json": json_format, "github": github, "planning_only": planning_only},
+            summary="Generated DevCouncil report",
+        )
+        
+        if github:
+            asyncio.run(run_github_report(graph))
+            return
+
+        if json_format:
+            output = ReportBuilder.build_json(graph)
+            typer.echo(output)
+        else:
+            output = ReportBuilder.build_markdown(graph)
+            console.print(Markdown(output))

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

@@ -0,0 +1,28 @@
+import typer
+from rich.console import Console
+from sqlmodel import delete
+
+from devcouncil.storage.db import get_db
+from devcouncil.storage.models import EvidenceModel, GapModel, RequirementModel, TaskModel
+
+console = Console()
+
+
+def reset_demo_state(
+    yes: bool = typer.Option(False, "--yes", help="Confirm clearing planning/demo artifacts."),
+):
+    """Clear demo planning artifacts from the local DevCouncil state database."""
+    if not yes:
+        console.print("[red]Refusing to clear state without --yes.[/red]")
+        raise typer.Exit(code=1)
+
+    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:
+        for model in (EvidenceModel, GapModel, TaskModel, RequirementModel):
+            session.exec(delete(model))
+
+    console.print("[green]Cleared requirements, tasks, gaps, and evidence from local state.[/green]")

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

@@ -0,0 +1,58 @@
+import typer
+import subprocess
+from pathlib import Path
+from rich.console import Console
+
+app = typer.Typer()
+console = Console()
+
+@app.callback(invoke_without_command=True)
+def rollback(
+    ctx: typer.Context,
+    task_id: str = typer.Argument(..., help="ID of the task to rollback"),
+):
+    """
+    Revert changes using a task's git checkpoint.
+    """
+    if ctx.invoked_subcommand is not None:
+        return
+
+    checkpoint_file = Path(".devcouncil/checkpoints") / f"{task_id}-before.patch"
+    after_patch = Path(".devcouncil/checkpoints") / f"{task_id}-after.patch"
+
+    if not checkpoint_file.exists() and not after_patch.exists():
+        console.print(
+            f"[red]No checkpoint found for task {task_id}. Expected {after_patch} "
+            f"or {checkpoint_file}.[/red]"
+        )
+        raise typer.Exit(code=1)
+
+    console.print(f"Rolling back task [bold]{task_id}[/bold]...")
+    
+    try:
+        if after_patch.exists():
+            # Reverse-apply the task's changes only
+            console.print(f"Applying reverse patch from [bold]{after_patch}[/bold]...")
+            subprocess.check_call(
+                ["git", "apply", "-R", str(after_patch)],
+                cwd=".",
+            )
+            console.print(f"[green]Successfully rolled back task {task_id} changes.[/green]")
+        else:
+            # No after-patch, but we have the before-patch — warn and offer manual reset
+            console.print(
+                f"[yellow]No after-patch found at {after_patch}.[/yellow]\n"
+                f"The before-patch at {checkpoint_file} captured the state before the task ran.\n"
+                f"To manually reset:\n"
+                f"  1. [bold]git stash[/bold] (if you want to keep current changes)\n"
+                f"  2. [bold]git checkout -- .[/bold] (discard working tree changes)\n"
+                f"  3. [bold]git apply {checkpoint_file}[/bold] (restore pre-task state)"
+            )
+    except subprocess.CalledProcessError as e:
+        console.print(f"[red]Failed to apply reverse patch: {e}[/red]")
+        console.print("[yellow]The patch may conflict with current changes. Try resolving manually:[/yellow]")
+        console.print(f"  git apply -R --3way {after_patch}")
+        raise typer.Exit(code=1)
+    except Exception as e:
+        console.print(f"[red]Failed to rollback: {e}[/red]")
+        raise typer.Exit(code=1)