devcouncil 0.1.0

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

@@ -0,0 +1,163 @@
+import typer
+import asyncio
+from rich.console import Console
+from rich.table import Table
+from pathlib import Path
+from typing import Optional
+from devcouncil.storage.db import get_db
+from devcouncil.storage.repositories import TaskRepository, RequirementRepository, GapRepository, EvidenceRepository, StateRepository
+from devcouncil.verification.verifier import Verifier
+from devcouncil.llm.provider import OpenRouterProvider
+from devcouncil.llm.router import ModelRouter
+from devcouncil.domain.evidence import CommandResult, DiffEvidence, TestEvidence
+from devcouncil.app.config import load_config, get_api_key
+from devcouncil.app.state_machine import ProjectPhase
+from devcouncil.integrations.code_review_graph import CodeReviewGraphAdapter
+from devcouncil.telemetry.traces import TraceLogger
+
+console = Console()
+MAX_RENDERED_GAPS = 20
+
+def verify(
+    task_id: Optional[str] = typer.Argument(None, help="Optional ID of the task to verify"),
+):
+    """
+    Verify one task, or all tasks when TASK_ID is omitted.
+    """
+    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)
+        req_repo = RequirementRepository(session)
+        gap_repo = GapRepository(session)
+        evidence_repo = EvidenceRepository(session)
+        
+        tasks = [task_repo.get_by_id(task_id)] if task_id else task_repo.get_all()
+        tasks = [task for task in tasks if task is not None]
+        if not tasks:
+            missing = f"Task {task_id} not found." if task_id else "No tasks found to verify."
+            console.print(f"[red]{missing}[/red]")
+            return
+
+        reqs = req_repo.get_all()
+        
+        # Load router for LLM review if possible
+        router = None
+        try:
+            config = load_config(Path("."))
+            api_key = get_api_key(config.models.provider)
+            provider = OpenRouterProvider(api_key)
+            role_config = {name: role.model_dump() for name, role in config.models.roles.items()}
+            router = ModelRouter(provider, role_config)
+        except Exception:
+            pass
+
+        verifier = Verifier(Path("."), router=router)
+        total_gaps = 0
+        blocked_tasks = 0
+
+        for task in tasks:
+            TraceLogger(Path(".")).log_event(
+                "task_verification_started",
+                {"task_id": task.id},
+                task_id=task.id,
+                summary=f"Verifying {task.id}",
+            )
+            graph_context = CodeReviewGraphAdapter(Path(".")).get_context(
+                [planned.path for planned in task.planned_files]
+            )
+            if graph_context.available:
+                TraceLogger(Path(".")).log_event(
+                    "graph_context_loaded",
+                    graph_context.model_dump(),
+                    task_id=task.id,
+                    summary=f"Loaded graph context for {task.id}",
+                )
+            StateRepository(session).record_phase(ProjectPhase.TASK_VERIFYING.value)
+            gap_repo.delete_for_task(task.id)
+            evidence_repo.delete_for_task(task.id)
+
+            gaps, evidence = asyncio.run(verifier.verify_task(task, reqs))
+            total_gaps += len(gaps)
+
+            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)
+
+            _print_task_result(task.id, gaps)
+
+            if any(gap.blocking for gap in gaps):
+                task.status = "blocked"
+                blocked_tasks += 1
+                TraceLogger(Path(".")).log_event(
+                    "gate_failed",
+                    {"task_id": task.id, "gap_count": len(gaps)},
+                    task_id=task.id,
+                    summary=f"{task.id} blocked with {len(gaps)} gap(s)",
+                )
+            else:
+                task.status = "verified"
+                TraceLogger(Path(".")).log_event(
+                    "task_verified",
+                    {"task_id": task.id, "gap_count": len(gaps)},
+                    task_id=task.id,
+                    summary=f"{task.id} verified",
+                )
+            task_repo.save(task)
+
+        StateRepository(session).record_phase(
+            ProjectPhase.TASK_BLOCKED.value if blocked_tasks else ProjectPhase.TASK_VERIFIED.value
+        )
+
+        if len(tasks) > 1:
+            if blocked_tasks:
+                console.print(
+                    f"\n[yellow]Verified {len(tasks)} tasks: {blocked_tasks} blocked, "
+                    f"{total_gaps} total gap(s).[/yellow]"
+                )
+            else:
+                console.print(f"\n[green]Verified {len(tasks)} tasks successfully.[/green]")
+
+
+def _print_task_result(task_id: str, gaps):
+    if not gaps:
+        console.print(f"[green]Task {task_id} verified successfully! No gaps found.[/green]")
+        return
+
+    console.print(f"[yellow]Verification finished for task {task_id} with {len(gaps)} gaps:[/yellow]")
+
+    table = Table(title="Detected Gaps")
+    table.add_column("ID", style="cyan")
+    table.add_column("Severity", style="magenta")
+    table.add_column("Description", style="white")
+    table.add_column("Blocking", style="red")
+
+    for gap in gaps[:MAX_RENDERED_GAPS]:
+        table.add_row(
+            gap.id,
+            gap.severity,
+            gap.description,
+            "YES" if gap.blocking else "NO",
+        )
+
+    console.print(table)
+    if len(gaps) > MAX_RENDERED_GAPS:
+        console.print(
+            f"[yellow]Showing first {MAX_RENDERED_GAPS} of {len(gaps)} gaps. "
+            "Run [bold]dev report --json[/bold] for the full list.[/yellow]"
+        )
+
+    if any(gap.blocking for gap in gaps):
+        console.print(f"\n[red]Task {task_id} is BLOCKED due to critical gaps.[/red]")
+    else:
+        console.print(f"\n[green]Task {task_id} passed with non-blocking gaps.[/green]")

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

@@ -0,0 +1,20 @@
+import typer
+from rich.console import Console
+import importlib.metadata
+
+app = typer.Typer()
+console = Console()
+
+@app.callback(invoke_without_command=True)
+def version(ctx: typer.Context):
+    """
+    Display the current version of DevCouncil.
+    """
+    if ctx.invoked_subcommand is not None:
+        return
+        
+    try:
+        ver = importlib.metadata.version("devcouncil")
+        console.print(f"DevCouncil version: [bold cyan]{ver}[/bold cyan]")
+    except importlib.metadata.PackageNotFoundError:
+        console.print("DevCouncil version: [yellow]unknown (editable/uninstalled)[/yellow]")

package/src/devcouncil/cli/main.py

@@ -0,0 +1,70 @@
+import typer
+from devcouncil.cli.commands import (
+    artifacts,
+    baseline,
+    config,
+    doctor,
+    hook,
+    init,
+    integrate,
+    map,
+    mcp_server,
+    plan,
+    prompt,
+    repair,
+    report,
+    reset_demo_state,
+    rollback,
+    run,
+    setup,
+    show,
+    status,
+    tasks,
+    trace,
+    verify,
+    version,
+)
+
+app = typer.Typer(
+    name="dev",
+    help="DevCouncil: Gated orchestrator for AI-assisted software development.",
+    add_completion=False,
+)
+
+# Typer subcommands (those using app = Typer())
+app.add_typer(init.app, name="init")
+app.add_typer(doctor.app, name="doctor")
+app.add_typer(prompt.app, name="prompt")
+app.add_typer(tasks.app, name="tasks")
+app.add_typer(show.app, name="show")
+app.add_typer(report.app, name="report")
+app.add_typer(rollback.app, name="rollback")
+app.add_typer(config.app, name="config")
+app.add_typer(artifacts.app, name="artifacts")
+app.add_typer(hook.app, name="hook")
+app.add_typer(version.app, name="version")
+app.add_typer(mcp_server.app, name="mcp-server")
+app.add_typer(integrate.app, name="integrate")
+app.add_typer(integrate.app, name="integrations")
+app.add_typer(trace.app, name="trace")
+app.add_typer(setup.app, name="setup")
+
+# Direct command registrations (those defined as def cmd())
+app.command(name="baseline")(baseline.baseline)
+app.command(name="map")(map.map_repo)
+app.command(name="plan")(plan.plan)
+app.command(name="reset-demo-state")(reset_demo_state.reset_demo_state)
+app.command(name="run")(run.run)
+app.command(name="verify")(verify.verify)
+app.command(name="repair")(repair.repair)
+app.command(name="status")(status.status)
+
+@app.callback()
+def main():
+    """
+    DevCouncil: Gated orchestrator for AI-assisted software development.
+    """
+    pass
+
+if __name__ == "__main__":
+    app()

package/src/devcouncil/council/prompts/arbiter.md

@@ -0,0 +1,19 @@
+Goal: {goal}
+
+Initial Requirements:
+{requirements_json}
+
+Plan A: {plan_a_json}
+Plan B: {plan_b_json}
+
+Critique of Plan B by Critic A: {critique_a_json}
+Critique of Plan A by Critic B: {critique_b_json}
+
+Rebuttal of Critic B by Planner A: {rebuttal_a_json}
+Rebuttal of Critic A by Planner B: {rebuttal_b_json}
+
+You are the arbiter engineering manager. Your goal is to produce the final, definitive set of requirements and tasks.
+- You do not decide by vibes.
+- High-severity unrefuted findings from critics must be incorporated into the final requirements or tasks.
+- If a planner successfully rebutted a finding, you may skip it.
+- Produce a single, coherent task graph.

package/src/devcouncil/council/prompts/critic_a.md

@@ -0,0 +1,10 @@
+Requirements:
+{requirements_json}
+
+Target Plan:
+{target_plan_json}
+
+You are a hostile staff engineer reviewing another team's implementation plan.
+Find missing requirements, bad assumptions, missing tests, security risks, migration risks, and unverifiable claims.
+Do not praise. Do not rewrite the plan.
+Every finding must include a falsifiable_check.

package/src/devcouncil/council/prompts/critic_b.md

@@ -0,0 +1,10 @@
+Requirements:
+{requirements_json}
+
+Target Plan:
+{target_plan_json}
+
+You are a hostile staff engineer reviewing another team's implementation plan.
+Find missing requirements, bad assumptions, missing tests, security risks, migration risks, and unverifiable claims.
+Do not praise. Do not rewrite the plan.
+Every finding must include a falsifiable_check.

package/src/devcouncil/council/prompts/implementation_reviewer.md

@@ -0,0 +1,16 @@
+You are an expert software reviewer. Review the following code changes against the task requirements.
+Task: {task.title}
+Description: {task.description}
+
+Requirements:
+{requirements_json}
+
+Code Diff:
+{diff}
+
+Your task is to identify if the implementation is complete, correct, and follows best practices.
+- Identify missing edge cases.
+- Identify architectural drift.
+- Identify security risks not caught by static scans.
+
+Return a JSON object with 'is_satisfactory' and a list of 'findings' (as Gap objects).

package/src/devcouncil/council/prompts/planner_a.md

@@ -0,0 +1,16 @@
+Goal: {goal}
+
+Requirements:
+{requirements_json}
+
+Repository Map:
+{repo_map_json}
+
+Your task is to create a detailed implementation plan.
+- Break down the requirements into atomic implementation tasks.
+- For each task, specify which files will be created or modified.
+- Specify which tests are expected to verify the task.
+- Ensure each task maps back to at least one requirement.
+
+Role-specific instructions:
+You are the pragmatic tech lead. Optimize for simplicity and minimal dependencies.

package/src/devcouncil/council/prompts/planner_b.md

@@ -0,0 +1,16 @@
+Goal: {goal}
+
+Requirements:
+{requirements_json}
+
+Repository Map:
+{repo_map_json}
+
+Your task is to create a detailed implementation plan.
+- Break down the requirements into atomic implementation tasks.
+- For each task, specify which files will be created or modified.
+- Specify which tests are expected to verify the task.
+- Ensure each task maps back to at least one requirement.
+
+Role-specific instructions:
+You are the production-readiness architect. Optimize for security, performance, edge cases, failure modes, and maintainability. Assume the first plan will miss subtle requirements.

package/src/devcouncil/council/prompts/rebuttal.md

@@ -0,0 +1,10 @@
+Original Plan:
+{original_plan_json}
+
+Critique Findings:
+{findings_json}
+
+You are the planner who created the original plan. Review the critique findings.
+- A finding can be rejected only with artifact evidence or strong justification.
+- A finding can be accepted and converted into a requirement/task/test.
+- No hand-wavy rebuttals.

package/src/devcouncil/council/prompts/spec_writer.md

@@ -0,0 +1,12 @@
+Goal: {goal}
+
+Repository Map:
+{repo_map_json}
+
+Your task is to draft the initial software specification for this goal.
+1. Identify functional and non-functional requirements.
+2. Extract any assumptions you are making about the codebase or architecture.
+3. List any blocking questions that the user must answer before implementation can proceed.
+
+Each requirement MUST have clear acceptance criteria with verification methods.
+Each assumption MUST have a confidence and impact level.

package/src/devcouncil/domain/assumption.py

@@ -0,0 +1,17 @@
+from pydantic import BaseModel, Field
+from typing import Literal, List
+
+class Assumption(BaseModel):
+    id: str
+    statement: str
+    confidence: Literal["low", "medium", "high"]
+    impact: Literal["low", "medium", "high"]
+    reversible: bool
+    requires_user_confirmation: bool
+    linked_requirement_ids: List[str] = Field(default_factory=list)
+    status: Literal[
+        "open",
+        "confirmed",
+        "rejected",
+        "converted_to_requirement"
+    ] = "open"

package/src/devcouncil/domain/critique.py

@@ -0,0 +1,32 @@
+from pydantic import BaseModel
+from typing import Literal, Optional
+
+class CritiqueFinding(BaseModel):
+    id: str
+    source_agent: str
+    target_plan_id: str
+    severity: Literal["low", "medium", "high", "critical"]
+    finding_type: Literal[
+        "missing_requirement",
+        "missing_task",
+        "missing_test",
+        "bad_assumption",
+        "architecture_risk",
+        "security_risk",
+        "performance_risk",
+        "dependency_risk",
+        "migration_risk",
+        "unverifiable_acceptance_criteria"
+    ]
+    claim: str
+    linked_requirement_id: Optional[str] = None
+    suggested_requirement: Optional[str] = None
+    suggested_task: Optional[str] = None
+    falsifiable_check: str
+    status: Literal[
+        "open",
+        "accepted",
+        "rejected",
+        "converted",
+        "needs_user"
+    ] = "open"

package/src/devcouncil/domain/evidence.py

@@ -0,0 +1,27 @@
+from pydantic import BaseModel
+from typing import Literal, List
+
+class CommandResult(BaseModel):
+    command: str
+    exit_code: int
+    stdout_path: str
+    stderr_path: str
+    summary: str
+
+class DiffEvidence(BaseModel):
+    task_id: str
+    changed_files: List[str]
+    added_files: List[str]
+    deleted_files: List[str]
+    diff_summary: str
+
+class VerificationEvidence(BaseModel):
+    __test__ = False  # Prevent pytest from collecting this as a test class
+    requirement_id: str
+    acceptance_criterion_id: str
+    command: str
+    status: Literal["passed", "failed", "not_run"]
+    evidence_summary: str
+
+# Backward-compatible alias
+TestEvidence = VerificationEvidence

package/src/devcouncil/domain/gap.py

@@ -0,0 +1,26 @@
+from pydantic import BaseModel, Field
+from typing import Literal, List, Optional
+
+class Gap(BaseModel):
+    id: str
+    severity: Literal["low", "medium", "high", "critical"]
+    gap_type: Literal[
+        "requirement_not_planned",
+        "task_not_implemented",
+        "planned_file_not_changed",
+        "orphan_diff",
+        "missing_test",
+        "test_failed",
+        "acceptance_criteria_unproven",
+        "assumption_violated",
+        "architecture_drift",
+        "security_risk",
+        "dependency_risk",
+        "migration_gap"
+    ]
+    requirement_id: Optional[str] = None
+    task_id: Optional[str] = None
+    description: str
+    evidence: List[str] = Field(default_factory=list)
+    recommended_fix: str
+    blocking: bool

package/src/devcouncil/domain/requirement.py

@@ -0,0 +1,22 @@
+from pydantic import BaseModel, Field
+from typing import Literal, List
+
+class AcceptanceCriterion(BaseModel):
+    id: str
+    description: str
+    verification_method: Literal[
+        "unit_test",
+        "integration_test",
+        "manual",
+        "static_check",
+        "llm_review"
+    ]
+    required: bool = True
+
+class Requirement(BaseModel):
+    id: str
+    title: str
+    description: str
+    priority: Literal["low", "medium", "high", "critical"]
+    source: Literal["user", "planner", "critic", "arbiter"]
+    acceptance_criteria: List[AcceptanceCriterion] = Field(default_factory=list)

package/src/devcouncil/domain/task.py

@@ -0,0 +1,26 @@
+from pydantic import BaseModel, Field
+from typing import Literal, List
+
+class PlannedFile(BaseModel):
+    path: str
+    reason: str
+    allowed_change: Literal["create", "modify", "delete", "read_only"]
+
+class Task(BaseModel):
+    id: str
+    title: str
+    description: str
+    requirement_ids: List[str] = Field(default_factory=list)
+    acceptance_criterion_ids: List[str] = Field(default_factory=list)
+    planned_files: List[PlannedFile] = Field(default_factory=list)
+    expected_tests: List[str] = Field(default_factory=list)
+    allowed_commands: List[str] = Field(default_factory=list)
+    forbidden_changes: List[str] = Field(default_factory=list)
+    status: Literal[
+        "planned",
+        "ready",
+        "running",
+        "blocked",
+        "verified",
+        "done"
+    ] = "planned"

package/src/devcouncil/execution/__init__.py

@@ -0,0 +1 @@
+

package/src/devcouncil/execution/context_builder.py

@@ -0,0 +1,60 @@
+from pathlib import Path
+from typing import List
+from devcouncil.domain.task import Task
+from devcouncil.domain.requirement import Requirement
+from devcouncil.utils.redaction import redact_string
+import json
+
+class ContextBuilder:
+    """Gathers repo-level and task-level context for agent prompts."""
+    
+    def __init__(self, project_root: Path):
+        self.project_root = project_root
+
+    def build_task_context(self, task: Task, requirements: List[Requirement]) -> str:
+        """Collects all relevant information for implementing a task."""
+        
+        # 1. Map requirements relevant to this task
+        req_map = {r.id: r for r in requirements}
+        task_reqs = [req_map[rid] for rid in task.requirement_ids if rid in req_map]
+        
+        # 2. Gather content of planned files (if they exist)
+        file_contents = {}
+        for pf in task.planned_files:
+            file_path = self.project_root / pf.path
+            if file_path.exists() and file_path.is_file():
+                try:
+                    raw = file_path.read_text(encoding="utf-8")
+                    file_contents[pf.path] = redact_string(raw)
+                except Exception:
+                    file_contents[pf.path] = "[Error reading file]"
+            else:
+                file_contents[pf.path] = "[New file - does not exist yet]"
+
+        # 3. Assemble the context string
+        context = {
+            "task": task.model_dump(),
+            "relevant_requirements": [r.model_dump() for r in task_reqs],
+            "file_contents": file_contents,
+            "project_structure": self.get_structure_summary(task)
+        }
+        
+        return json.dumps(context, indent=2)
+
+    def get_structure_summary(self, task: Task = None) -> List[str]:
+        """Simple list of files in the project for context."""
+        try:
+            import subprocess
+            output = subprocess.check_output(
+                ["git", "ls-files", "--cached", "--others", "--exclude-standard"],
+                cwd=self.project_root,
+                stderr=subprocess.DEVNULL
+            ).decode().splitlines()
+            
+            if task and task.planned_files:
+                planned_paths = {pf.path for pf in task.planned_files}
+                output = [p for p in output if p in planned_paths] + [p for p in output if p not in planned_paths]
+                
+            return output[:100] # Limit to avoid context overflow
+        except Exception:
+            return []

package/src/devcouncil/execution/executor.py

@@ -0,0 +1,15 @@
+from abc import ABC, abstractmethod
+from typing import List
+from pydantic import BaseModel
+from devcouncil.domain.task import Task
+from devcouncil.domain.requirement import Requirement
+
+class ExecutionResult(BaseModel):
+    success: bool
+    message: str
+
+class Executor(ABC):
+    @abstractmethod
+    def run_task(self, task: Task, requirements: List[Requirement]) -> ExecutionResult:
+        """Execute the task and return the result."""
+        pass