devcouncil 0.1.0 → 0.2.0

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

@@ -1,11 +1,12 @@
 import json
 import time
 from pathlib import Path
+from typing import Optional
 
 import typer
 from rich.console import Console
 
-from devcouncil.telemetry.traces import read_trace_events
+from devcouncil.telemetry.traces import read_trace_events, read_trace_events_since
 
 app = typer.Typer(help="Inspect DevCouncil trace events.")
 console = Console()
@@ -13,12 +14,56 @@ console = Console()
 
 @app.command("tail")
 def tail(
-    follow: bool = typer.Option(False, "--follow", "-f", help="Continue polling for new events."),
+    follow: bool = typer.Option(
+        False, "--follow/--no-follow", "-f", help="Continue polling for new events (default is a single shot)."
+    ),
     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."),
+    since: Optional[int] = typer.Option(
+        None,
+        "--since",
+        help="Byte-offset cursor from a previous run; emit only events after it (stateless incremental polling).",
+    ),
+    json_summary: bool = typer.Option(
+        False,
+        "--json",
+        help="Emit a single {events, next_cursor} JSON object (incremental mode). Implies --no-follow.",
+    ),
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root containing .devcouncil/."),
 ):
-    """Print the DevCouncil trace JSONL stream for replay or debugging."""
-    project_root = Path(".")
+    """Print the DevCouncil trace JSONL stream for replay or debugging.
+
+    With ``--since <cursor> --no-follow`` (or ``--json``) a single-shot supervising
+    agent gets only the events appended after the cursor plus a ``next_cursor`` to
+    pass back on the next poll, so each poll is O(new) rather than O(all).
+    """
+    project_root = project_root.expanduser().resolve()
+
+    # Incremental cursor mode: any of --since / --json / explicit --no-follow.
+    incremental = since is not None or json_summary
+    if incremental:
+        events, next_cursor = read_trace_events_since(project_root, since)
+        if json_summary:
+            typer.echo(
+                json.dumps(
+                    {
+                        "events": [event.model_dump(by_alias=True) for event in events],
+                        "next_cursor": next_cursor,
+                    }
+                )
+            )
+            return
+        for event in events:
+            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)}"
+                )
+        console.print(f"[dim]next_cursor: {next_cursor}[/dim]")
+        return
+
     printed = 0
 
     def emit_new(start_index: int) -> int:

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

@@ -1,105 +1,203 @@
-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
+import typer
+import asyncio
+import json
+from rich.console import Console
+from rich.table import Table
+from pathlib import Path
+from typing import Optional
+from devcouncil.cli.commands.init import initialize_project
+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 create_provider, validate_model_provider
+from devcouncil.llm.router import ModelRouter
+from devcouncil.domain.evidence import CommandResult, DiffEvidence, DiffCoverageEvidence, TestEvidence
+from devcouncil.domain.gap import Gap
+from devcouncil.verification.next_actions import split_next_actions
 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
-
+
+console = Console()
+MAX_RENDERED_GAPS = 20
+
+
+def reconcile_cross_task_acceptance(
+    gaps: list[Gap], proven_acs: set[str]
+) -> list[Gap]:
+    """Drop a task's blocking ``acceptance_criteria_unproven`` gaps whose criterion is
+    already proven by passing evidence in another task.
+
+    Acceptance criteria are requirement-level, not task-private: when the planner splits
+    "implement X" and "add tests for X" into separate tasks that share criteria, the
+    implement task would otherwise stay blocked for criteria the test task proved. The
+    caller passes ``proven_acs`` gathered from passing evidence re-run against the current
+    tree, so a regression would have failed the test and excluded the criterion — only
+    genuinely-satisfied criteria are cleared. Returns the gaps to keep."""
+    return [
+        gap
+        for gap in gaps
+        if not (
+            gap.blocking
+            and gap.gap_type == "acceptance_criteria_unproven"
+            and gap.acceptance_criterion_id in proven_acs
+        )
+    ]
+
+def verify(
+    task_id: Optional[str] = typer.Argument(None, help="Optional ID of the task to verify"),
+    sandbox: str = typer.Option("local", "--sandbox", help="Verification sandbox: local, docker, or nix."),
+    json_format: bool = typer.Option(False, "--json", help="Output machine-readable JSON."),
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root containing .devcouncil/."),
+):
+    """
+    Verify one task, or all tasks when TASK_ID is omitted.
+    """
+    root = project_root.expanduser().resolve()
+    initialize_project(root, quiet=True)
+    db = get_db(root)
+    if not db:
+        if json_format:
+            typer.echo(json.dumps({"ok": False, "error": "DevCouncil state is unavailable in this directory."}, indent=2))
+        else:
+            console.print("[red]DevCouncil state is unavailable in this directory.[/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."
+            if json_format:
+                typer.echo(json.dumps({"ok": False, "error": missing}, indent=2))
+            else:
+                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(root)
+            validate_model_provider(config.models.provider)
+            api_key = get_api_key(config.models.provider, root)
+            provider = create_provider(config.models.provider, api_key, project_root=root)
+            role_config = {name: role.model_dump() for name, role in config.models.roles.items()}
+            router = ModelRouter(provider, role_config, project_root=root)
+        except Exception:
+            pass
+
+        from devcouncil.verification.sandbox import get_sandbox
+
+        verifier = Verifier(root, router=router)
+        total_gaps = 0
+        blocked_tasks = 0
+        task_results = []
+        # Cross-task acceptance reconciliation state: a criterion proven by passing
+        # evidence in ANY task is proven for every task that shares it.
+        proven_acs: set[str] = set()
+        per_task_gaps: dict[str, list] = {}
+
         for task in tasks:
-            TraceLogger(Path(".")).log_event(
+            if sandbox != "local":
+                commands = task.expected_tests or task.allowed_commands
+                sandbox_result = get_sandbox(sandbox, root).run(task, commands, reqs)
+                if sandbox_result.status == "unsupported":
+                    message = f"Sandbox {sandbox} is unavailable."
+                    if json_format:
+                        typer.echo(json.dumps({"ok": False, "error": message, "sandbox": sandbox}, indent=2))
+                    else:
+                        console.print(f"[red]{message}[/red]")
+                    return
+                if sandbox_result.status == "failed":
+                    task.status = "blocked"
+                    blocked_tasks += 1
+                    task_repo.save(task)
+                    task_results.append({
+                        "task_id": task.id,
+                        "status": task.status,
+                        "sandbox": sandbox,
+                        "gap_count": 1,
+                        "blocking_gap_count": 1,
+                        "gaps": [],
+                    })
+                    if json_format:
+                        typer.echo(json.dumps({
+                            "ok": False,
+                            "task_id": task.id,
+                            "sandbox": sandbox,
+                            "commands": sandbox_result.commands,
+                        }, indent=2))
+                    else:
+                        console.print(f"[red]{task.id} failed in {sandbox} sandbox.[/red]")
+                    continue
+                task.status = "verified"
+                task_repo.save(task)
+                task_results.append({
+                    "task_id": task.id,
+                    "status": task.status,
+                    "sandbox": sandbox,
+                    "gap_count": 0,
+                    "blocking_gap_count": 0,
+                    "gaps": [],
+                })
+                if not json_format:
+                    console.print(f"[green]{task.id} passed in {sandbox} sandbox.[/green]")
+                continue
+            TraceLogger(root).log_event(
                 "task_verification_started",
                 {"task_id": task.id},
                 task_id=task.id,
                 summary=f"Verifying {task.id}",
             )
-            graph_context = CodeReviewGraphAdapter(Path(".")).get_context(
+            graph_context = CodeReviewGraphAdapter(root).get_context(
                 [planned.path for planned in task.planned_files]
             )
             if graph_context.available:
-                TraceLogger(Path(".")).log_event(
+                TraceLogger(root).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)
-
+            gap_repo.delete_for_task(task.id)
+            evidence_repo.delete_for_task(task.id)
+
+            gaps, evidence = asyncio.run(verifier.verify_task(task, reqs))
+            outcome = verifier.last_outcome
+            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, DiffCoverageEvidence):
+                    evidence_repo.save_diff_coverage_evidence(ev)
+                elif isinstance(ev, DiffEvidence):
+                    evidence_repo.save_diff_evidence(ev)
+                elif isinstance(ev, TestEvidence):
+                    evidence_repo.save_test_evidence(ev, task.id)
+                    if ev.status == "passed" and ev.acceptance_criterion_id:
+                        proven_acs.add(ev.acceptance_criterion_id)
+
+            per_task_gaps[task.id] = gaps
+            if not json_format:
+                _print_task_result(task.id, gaps)
+
             if any(gap.blocking for gap in gaps):
                 task.status = "blocked"
                 blocked_tasks += 1
-                TraceLogger(Path(".")).log_event(
+                TraceLogger(root).log_event(
                     "gate_failed",
                     {"task_id": task.id, "gap_count": len(gaps)},
                     task_id=task.id,
@@ -107,57 +205,124 @@ def verify(
                 )
             else:
                 task.status = "verified"
-                TraceLogger(Path(".")).log_event(
+                TraceLogger(root).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]")
+            blocking_actions, advisory_actions = split_next_actions(gaps)
+            task_results.append({
+                "task_id": task.id,
+                "status": task.status,
+                "gap_count": len(gaps),
+                "blocking_gap_count": len([gap for gap in gaps if gap.blocking]),
+                "gaps": [gap.model_dump() for gap in gaps],
+                "next_actions": [action.model_dump() for action in blocking_actions],
+                "advisory_actions": [action.model_dump() for action in advisory_actions],
+                "verification_mode": outcome.mode if outcome else "unknown",
+                "compiler_active": outcome.compiler_active if outcome else False,
+                "diff_empty": outcome.diff_empty if outcome else False,
+                "coverage_measured": outcome.coverage_measured if outcome else False,
+                "coverage_skipped_reason": outcome.coverage_skipped_reason if outcome else None,
+            })
+
+        # Cross-task acceptance reconciliation (only meaningful across the full set).
+        # The planner sometimes splits "implement X" and "add tests for X" into separate
+        # tasks that share acceptance criteria; the implement task would otherwise stay
+        # blocked for criteria the test task already proved. A criterion proven by passing
+        # evidence in ANY task is proven for every task that shares it. Evidence was re-run
+        # against the current tree, so a regression would have failed the test and the AC
+        # would not be in proven_acs — this clears only genuinely-satisfied criteria.
+        if task_id is None and proven_acs:
+            for task in tasks:
+                gaps = per_task_gaps.get(task.id, [])
+                kept = reconcile_cross_task_acceptance(gaps, proven_acs)
+                if len(kept) == len(gaps):
+                    continue
+                gap_repo.delete_for_task(task.id)
+                for gap in kept:
+                    gap_repo.save(gap)
+                per_task_gaps[task.id] = kept
+                if task.status == "blocked" and not any(gap.blocking for gap in kept):
+                    task.status = "verified"
+                    blocked_tasks = max(0, blocked_tasks - 1)
+                    TraceLogger(root).log_event(
+                        "task_reconciled",
+                        {"task_id": task.id, "cross_task_proven": True},
+                        task_id=task.id,
+                        summary=f"{task.id} verified via cross-task acceptance reconciliation",
+                    )
+                task_repo.save(task)
+                for result in task_results:
+                    if result["task_id"] == task.id:
+                        blocking_actions, advisory_actions = split_next_actions(kept)
+                        result["status"] = task.status
+                        result["gap_count"] = len(kept)
+                        result["blocking_gap_count"] = len([gap for gap in kept if gap.blocking])
+                        result["gaps"] = [gap.model_dump() for gap in kept]
+                        result["next_actions"] = [action.model_dump() for action in blocking_actions]
+                        result["advisory_actions"] = [action.model_dump() for action in advisory_actions]
+
+        StateRepository(session).record_phase(
+            ProjectPhase.TASK_BLOCKED.value if blocked_tasks else ProjectPhase.TASK_VERIFIED.value
+        )
+
+        if json_format:
+            typer.echo(json.dumps({
+                "ok": blocked_tasks == 0,
+                "verified_tasks": len(tasks),
+                "blocked_tasks": blocked_tasks,
+                "total_gaps": total_gaps,
+                "tasks": task_results,
+            }, indent=2))
+        elif 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]")
+
+    # Exit-code contract (so shell-driven agents can gate on $?):
+    #   0 = all verified, no blocking gaps
+    #   1 = at least one task is blocked by a verification gap
+    # Argument/state errors above return early with their own message and exit 0.
+    if blocked_tasks:
+        raise typer.Exit(code=1)
+
+
+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

@@ -1,20 +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]")
+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]")