devcouncil 0.3.0 → 0.4.0

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

@@ -11,6 +11,7 @@ process likely crashed) as ``orphaned``.
 from __future__ import annotations
 
 import json
+import logging
 import time
 from pathlib import Path
 
@@ -19,9 +20,12 @@ from rich.console import Console
 from rich.table import Table
 
 from devcouncil.utils.redaction import redact_text
+from devcouncil.utils.json_persist import read_json
+from devcouncil.telemetry.stages import log_stage, log_step
 
 app = typer.Typer(help="List and inspect coding-agent run manifests.")
 console = Console()
+logger = logging.getLogger(__name__)
 
 # A run still marked ``running`` whose manifest has not been touched for longer
 # than this is treated as orphaned (the executor process likely died). Used as a
@@ -49,14 +53,14 @@ def _orphan_after_seconds(project_root: Path) -> int:
         ttl = int(load_config(project_root).execution.lease_ttl_seconds)
         if ttl > 0:
             return ttl
-    except Exception:
-        pass
+    except Exception as e:
+        logger.debug("Failed to load lease TTL from config, using default orphan threshold: %s", e)
     return _DEFAULT_ORPHAN_AFTER_SECONDS
 
 
 def _load_manifest(manifest_path: Path) -> dict | None:
     try:
-        data = json.loads(manifest_path.read_text(encoding="utf-8"))
+        data = read_json(manifest_path)
     except (OSError, json.JSONDecodeError):
         return None
     return data if isinstance(data, dict) else None
@@ -142,41 +146,50 @@ def list_runs(
 ) -> None:
     """List recorded coding-agent runs, newest first."""
     root = project_root.expanduser().resolve()
-    orphan_after = _orphan_after_seconds(root)
-    runs = _collect_runs(root, orphan_after=orphan_after)
-    if status:
-        runs = [run for run in runs if run.get("status") == status]
-    if limit > 0:
-        runs = runs[:limit]
-
-    if json_output:
-        console.print_json(data={"runs": runs, "count": len(runs)})
-        return
-
-    if not runs:
-        console.print("[dim]No agent runs found under .devcouncil/runs/.[/dim]")
-        return
-
-    table = Table(title="Agent runs")
-    table.add_column("Run ID", overflow="fold")
-    table.add_column("Task")
-    table.add_column("Agent")
-    table.add_column("Profile")
-    table.add_column("Status")
-    table.add_column("Started")
-    for run in runs:
-        status_text = str(run.get("status") or "?")
-        if run.get("orphaned"):
-            status_text = f"[red]{status_text} (orphaned)[/red]"
-        table.add_row(
-            str(run.get("run_id") or ""),
-            str(run.get("task_id") or ""),
-            str(run.get("agent") or ""),
-            str(run.get("profile") or ""),
-            status_text,
-            str(run.get("started_at") or ""),
-        )
-    console.print(table)
+    from devcouncil.telemetry.logging_setup import set_log_dir
+    set_log_dir(root)
+    logger.info("dev runs list: status=%s limit=%d", status, limit)
+    with log_stage("runs", project_root=root, subcommand="list"):
+        log_step("runs/1: collecting run manifests", project_root=root, trace=True)
+        orphan_after = _orphan_after_seconds(root)
+        runs = _collect_runs(root, orphan_after=orphan_after)
+        if status:
+            runs = [run for run in runs if run.get("status") == status]
+        total = len(runs)
+        if limit > 0:
+            runs = runs[:limit]
+
+        if json_output:
+            console.print_json(data={"runs": runs, "count": len(runs), "total": total})
+            log_step("runs/complete", project_root=root, count=len(runs), trace=True)
+            return
+
+        if not runs:
+            console.print("[dim]No agent runs found under .devcouncil/runs/.[/dim]")
+            log_step("runs/complete", project_root=root, count=0, trace=True)
+            return
+
+        table = Table(title="Agent runs")
+        table.add_column("Run ID", overflow="fold")
+        table.add_column("Task")
+        table.add_column("Agent")
+        table.add_column("Profile")
+        table.add_column("Status")
+        table.add_column("Started")
+        for run in runs:
+            status_text = str(run.get("status") or "?")
+            if run.get("orphaned"):
+                status_text = f"[red]{status_text} (orphaned)[/red]"
+            table.add_row(
+                str(run.get("run_id") or ""),
+                str(run.get("task_id") or ""),
+                str(run.get("agent") or ""),
+                str(run.get("profile") or ""),
+                status_text,
+                str(run.get("started_at") or ""),
+            )
+        console.print(table)
+        log_step("runs/complete", project_root=root, count=len(runs), trace=True)
 
 
 @app.command("show")
@@ -187,37 +200,254 @@ def show_run(
 ) -> None:
     """Show the full manifest for a run plus a redacted transcript tail."""
     root = project_root.expanduser().resolve()
-    run_dir = _runs_dir(root) / run_id
-    manifest_path = run_dir / "agent-run.json"
-    manifest = _load_manifest(manifest_path)
-    if manifest is None:
+    from devcouncil.telemetry.logging_setup import set_log_dir
+    set_log_dir(root)
+    logger.info("dev runs show: run_id=%s", run_id)
+    with log_stage("runs", project_root=root, subcommand="show", run_id=run_id):
+        log_step("runs/1: loading run manifest", project_root=root, run_id=run_id, trace=True)
+        run_dir = _runs_dir(root) / run_id
+        manifest_path = run_dir / "agent-run.json"
+        manifest = _load_manifest(manifest_path)
+        if manifest is None:
+            if json_output:
+                console.print_json(data={"ok": False, "error": f"Run {run_id} not found.", "run_id": run_id})
+            else:
+                console.print(f"[red]Run {run_id} not found under .devcouncil/runs/.[/red]")
+            raise typer.Exit(code=1)
+
+        orphan_after = _orphan_after_seconds(root)
+        orphaned = _is_orphaned(manifest, manifest_path, orphan_after=orphan_after, now=time.time())
+        transcript_path = _find_transcript(run_dir, manifest)
+        transcript_tail = _transcript_tail(transcript_path) if transcript_path else ""
+
         if json_output:
-            console.print_json(data={"ok": False, "error": f"Run {run_id} not found.", "run_id": run_id})
+            console.print_json(data={
+                "ok": True,
+                "run_id": run_id,
+                "manifest": manifest,
+                "orphaned": orphaned,
+                "transcript_path": str(transcript_path) if transcript_path else None,
+                "transcript_tail": transcript_tail,
+            })
+            log_step("runs/complete", project_root=root, run_id=run_id, trace=True)
+            return
+
+        console.print_json(data=manifest)
+        if orphaned:
+            console.print("[red]This run is orphaned: still marked running but its manifest is stale.[/red]")
+        if transcript_path:
+            console.print(f"\n[bold]Transcript tail[/bold] [dim]({transcript_path})[/dim]:")
+            console.print(transcript_tail or "[dim](empty)[/dim]")
         else:
-            console.print(f"[red]Run {run_id} not found under .devcouncil/runs/.[/red]")
+            console.print("\n[dim]No transcript file found for this run.[/dim]")
+        log_step("runs/complete", project_root=root, run_id=run_id, trace=True)
+
+
+# --- Shepherd-style reversible-trace commands -------------------------------------
+# A run is an object a supervisor (human or meta-agent) can operate on: inspect the
+# full timeline (`timeline`), see exactly what it changed (`diff`), reverse its
+# workspace effects (`revert`), or ask for a keep/revert/repair verdict (`supervise`).
+
+
+def _resolve_root(project_root: Path) -> Path:
+    root = project_root.expanduser().resolve()
+    from devcouncil.telemetry.logging_setup import set_log_dir
+
+    set_log_dir(root)
+    return root
+
+
+def _load_timeline_or_exit(root: Path, reference: str):
+    from devcouncil.execution.run_trace import load_timeline
+
+    try:
+        return load_timeline(root, reference)
+    except ValueError as exc:
+        console.print(f"[red]{exc}[/red]")
         raise typer.Exit(code=1)
 
-    orphan_after = _orphan_after_seconds(root)
-    orphaned = _is_orphaned(manifest, manifest_path, orphan_after=orphan_after, now=time.time())
-    transcript_path = _find_transcript(run_dir, manifest)
-    transcript_tail = _transcript_tail(transcript_path) if transcript_path else ""
-
-    if json_output:
-        console.print_json(data={
-            "ok": True,
-            "run_id": run_id,
-            "manifest": manifest,
-            "orphaned": orphaned,
-            "transcript_path": str(transcript_path) if transcript_path else None,
-            "transcript_tail": transcript_tail,
-        })
-        return
-
-    console.print_json(data=manifest)
-    if orphaned:
-        console.print("[red]This run is orphaned: still marked running but its manifest is stale.[/red]")
-    if transcript_path:
-        console.print(f"\n[bold]Transcript tail[/bold] [dim]({transcript_path})[/dim]:")
-        console.print(transcript_tail or "[dim](empty)[/dim]")
-    else:
-        console.print("\n[dim]No transcript file found for this run.[/dim]")
+
+def _supervisor_router(root: Path):
+    """Best-effort ModelRouter for `dev runs supervise`; None degrades to heuristics.
+
+    The ``run_supervisor`` role falls back to a capable existing role when the project
+    config doesn't define a dedicated one (same pattern as `dev skills` / `dev wiki`).
+    """
+    try:
+        from devcouncil.app.config import get_api_key, load_config
+        from devcouncil.llm.provider import create_provider, validate_model_provider
+        from devcouncil.llm.router import ModelRouter
+
+        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, provider_prefs=config.provider
+        )
+        role_config = {name: role.model_dump() for name, role in config.models.roles.items()}
+        if not role_config:
+            return None
+        capable = (
+            role_config.get("arbiter")
+            or role_config.get("planner_a")
+            or next(iter(role_config.values()))
+        )
+        role_config.setdefault("run_supervisor", dict(capable))
+        return ModelRouter(provider, role_config, project_root=root)
+    except Exception as exc:
+        logger.warning("Model-backed supervision unavailable; using heuristics: %s", exc)
+        return None
+
+
+@app.command("timeline")
+def timeline(
+    reference: str = typer.Argument(..., help="A run id or task id to inspect."),
+    json_output: bool = typer.Option(False, "--json", help="Emit machine-readable JSON."),
+    limit: int = typer.Option(40, "--limit", help="Maximum number of trace events to show."),
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root containing .devcouncil/."),
+) -> None:
+    """Show a run's full reversible trace: events, checkpoints, and diff stat."""
+    root = _resolve_root(project_root)
+    logger.info("dev runs timeline: ref=%s", reference)
+    with log_stage("runs", project_root=root, subcommand="timeline"):
+        tl = _load_timeline_or_exit(root, reference)
+
+        if json_output:
+            data = tl.model_dump(mode="json")
+            if limit > 0:
+                data["events"] = data["events"][-limit:]
+            console.print_json(data=data)
+            return
+
+        title = tl.run_id or tl.task_id
+        console.print(f"[bold]Run[/bold] {title}  [dim]task={tl.task_id or '?'} status={tl.status or '?'}[/dim]")
+        if tl.checkpoints:
+            table = Table(title="Checkpoints")
+            table.add_column("Stage")
+            table.add_column("Ref", overflow="fold")
+            table.add_column("Snapshot")
+            table.add_column("Patch", overflow="fold")
+            for cp in tl.checkpoints:
+                table.add_row(cp.stage, cp.ref, cp.sha[:12], cp.patch_path or "-")
+            console.print(table)
+        else:
+            console.print("[dim]No git checkpoints recorded for this run.[/dim]")
+
+        events = tl.events[-limit:] if limit > 0 else tl.events
+        if events:
+            table = Table(title=f"Trace events (last {len(events)})")
+            table.add_column("Time", overflow="fold")
+            table.add_column("Type")
+            table.add_column("Summary", overflow="fold")
+            for event in events:
+                table.add_row(event.timestamp, event.type, redact_text(event.summary or ""))
+            console.print(table)
+        else:
+            console.print("[dim]No trace events recorded for this run.[/dim]")
+
+        if tl.diff_stat:
+            console.print("\n[bold]Workspace changes[/bold]:")
+            console.print(tl.diff_stat)
+        console.print(
+            f"\nReversible: {'[green]yes[/green]' if tl.reversible else '[yellow]no[/yellow]'}"
+            + (f" — `dev runs revert {reference}` restores the pre-run state." if tl.reversible else "")
+        )
+        log_step("runs/complete", project_root=root, trace=True)
+
+
+@app.command("diff")
+def diff(
+    reference: str = typer.Argument(..., help="A run id or task id."),
+    stat: bool = typer.Option(False, "--stat", help="Show only the diff stat."),
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root containing .devcouncil/."),
+) -> None:
+    """Show the workspace changes a run produced (from its git checkpoints)."""
+    root = _resolve_root(project_root)
+    logger.info("dev runs diff: ref=%s stat=%s", reference, stat)
+    tl = _load_timeline_or_exit(root, reference)
+    from devcouncil.execution.run_trace import diff_run
+
+    output = diff_run(root, tl.task_id, stat_only=stat)
+    if not output:
+        console.print("[dim]No recorded diff for this run (no before/after checkpoints or patch).[/dim]")
+        raise typer.Exit(code=1)
+    console.print(output)
+
+
+@app.command("revert")
+def revert(
+    reference: str = typer.Argument(..., help="A run id or task id to revert."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip the confirmation prompt."),
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root containing .devcouncil/."),
+) -> None:
+    """Reverse a run's workspace effects using its git checkpoints (recorded in the trace)."""
+    root = _resolve_root(project_root)
+    logger.info("dev runs revert: ref=%s", reference)
+    with log_stage("runs", project_root=root, subcommand="revert"):
+        tl = _load_timeline_or_exit(root, reference)
+        if not tl.reversible:
+            console.print(
+                f"[red]Run {reference} has no before/after checkpoints; nothing to revert.[/red]"
+            )
+            raise typer.Exit(code=1)
+        if tl.diff_stat:
+            console.print("[bold]This will reverse:[/bold]")
+            console.print(tl.diff_stat)
+        if not yes and not typer.confirm(f"Revert run {reference} (task {tl.task_id})?"):
+            raise typer.Exit(code=1)
+
+        from devcouncil.execution.run_trace import revert_run
+
+        result = revert_run(root, reference)
+        if "failed" in result.message.lower() or result.message.startswith("No checkpoint"):
+            console.print(f"[red]{result.message}[/red] Try `dev rollback {tl.task_id}` for manual guidance.")
+            raise typer.Exit(code=1)
+        console.print(f"[green]Reverted run {reference}.[/green] {result.message}")
+        log_step("runs/complete", project_root=root, trace=True)
+
+
+@app.command("supervise")
+def supervise(
+    reference: str = typer.Argument(..., help="A run id or task id to review."),
+    llm: bool = typer.Option(True, "--llm/--no-llm", help="Use the run_supervisor model role (falls back to deterministic heuristics)."),
+    apply: bool = typer.Option(False, "--apply", help="If the verdict is 'revert', revert the run immediately."),
+    json_output: bool = typer.Option(False, "--json", help="Emit machine-readable JSON."),
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root containing .devcouncil/."),
+) -> None:
+    """Ask the supervisor meta-agent for a keep/revert/repair verdict on a run."""
+    import asyncio
+
+    root = _resolve_root(project_root)
+    logger.info("dev runs supervise: ref=%s llm=%s apply=%s", reference, llm, apply)
+    with log_stage("runs", project_root=root, subcommand="supervise"):
+        tl = _load_timeline_or_exit(root, reference)
+        router = _supervisor_router(root) if llm else None
+
+        from devcouncil.execution.run_trace import supervise_run
+
+        verdict = asyncio.run(supervise_run(root, tl, router))
+
+        if json_output:
+            console.print_json(data=verdict.model_dump(mode="json"))
+        else:
+            color = {"keep": "green", "repair": "yellow", "revert": "red"}[verdict.verdict]
+            console.print(
+                f"Verdict: [{color}]{verdict.verdict}[/{color}] "
+                f"[dim](confidence {verdict.confidence:.2f}, {verdict.source})[/dim]"
+            )
+            if verdict.rationale:
+                console.print(verdict.rationale)
+            for finding in verdict.findings:
+                console.print(f"  - {redact_text(finding)}")
+
+        if verdict.verdict == "revert":
+            if not tl.reversible:
+                console.print("[yellow]Verdict is 'revert' but the run has no checkpoints to revert with.[/yellow]")
+            elif apply:
+                from devcouncil.execution.run_trace import revert_run
+
+                result = revert_run(root, reference)
+                console.print(f"[green]Applied revert.[/green] {result.message}")
+            else:
+                console.print(f"Run [bold]dev runs revert {reference}[/bold] to apply it.")
+        log_step("runs/complete", project_root=root, verdict=verdict.verdict, trace=True)

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

@@ -1,32 +1,53 @@
+import logging
 from pathlib import Path
 
 import typer
 from rich.console import Console
 
-from devcouncil.repo.ci_scaffold import WORKFLOW_RELPATH, detect_stacks, scaffold_ci
+from devcouncil.repo.ci_scaffold import WORKFLOW_RELPATH, EVIDENCE_WORKFLOW_RELPATH, detect_stacks, scaffold_ci, scaffold_evidence_ci
+from devcouncil.telemetry.stages import log_stage, log_step
 
 console = Console()
+logger = logging.getLogger(__name__)
 
 
 def scaffold_ci_command(
     project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root to scaffold CI into."),
     force: bool = typer.Option(False, "--force", help="Overwrite an existing devcouncil.yml workflow."),
+    evidence: bool = typer.Option(False, "--evidence", help="Also write .github/workflows/devcouncil-evidence.yml."),
 ):
     """Write a starter GitHub Actions workflow derived from the configured commands."""
     root = project_root.expanduser().resolve()
+    from devcouncil.telemetry.logging_setup import set_log_dir
+    set_log_dir(root)
+    logger.info("dev scaffold-ci: force=%s evidence=%s", force, evidence)
     if not (root / ".devcouncil").exists():
         console.print("[red]DevCouncil is not initialized here. Run 'dev setup' first.[/red]")
         raise typer.Exit(code=1)
 
-    target = scaffold_ci(root, force=force)
-    if target is None:
-        console.print(
-            f"[yellow]{WORKFLOW_RELPATH.as_posix()} already exists. "
-            f"Re-run with --force to overwrite.[/yellow]"
-        )
-        return
+    with log_stage("scaffold", project_root=root, force=force):
+        log_step("scaffold/1: writing CI workflow", project_root=root, trace=True)
+        target = scaffold_ci(root, force=force)
+        if target is None:
+            console.print(
+                f"[yellow]{WORKFLOW_RELPATH.as_posix()} already exists. "
+                f"Re-run with --force to overwrite.[/yellow]"
+            )
+            log_step("scaffold/complete", project_root=root, skipped=True, trace=True)
+        else:
+            stacks = detect_stacks(root)
+            detected = ", ".join(sorted(stacks)) if stacks else "none auto-detected"
+            console.print(f"[green]Wrote {target.relative_to(root).as_posix()} (stacks: {detected}).[/green]")
+            console.print("[dim]Review the setup/install steps and commands before relying on it.[/dim]")
+            log_step("scaffold/complete", project_root=root, trace=True)
 
-    stacks = detect_stacks(root)
-    detected = ", ".join(sorted(stacks)) if stacks else "none auto-detected"
-    console.print(f"[green]Wrote {target.relative_to(root).as_posix()} (stacks: {detected}).[/green]")
-    console.print("[dim]Review the setup/install steps and commands before relying on it.[/dim]")
+        if evidence:
+            log_step("scaffold/2: writing evidence workflow", project_root=root, trace=True)
+            evidence_target = scaffold_evidence_ci(root, force=force)
+            if evidence_target is None:
+                console.print(
+                    f"[yellow]{EVIDENCE_WORKFLOW_RELPATH.as_posix()} already exists. "
+                    f"Re-run with --force to overwrite.[/yellow]"
+                )
+            else:
+                console.print(f"[green]Wrote {evidence_target.relative_to(root).as_posix()} (verify → evidence artifacts → optional GitHub Check/comment).[/green]")

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

@@ -1,13 +1,16 @@
-import json
+from devcouncil.utils.json_persist import dump_json
+import logging
 import typer
 from pathlib import Path
 from rich.console import Console
 
 from devcouncil.cli.commands.init import initialize_project
 from devcouncil.indexing.semantic_index import SemanticIndex
+from devcouncil.telemetry.stages import log_stage, log_step
 
 app = typer.Typer(help="Semantic snapshots and diffs.")
 console = Console()
+logger = logging.getLogger(__name__)
 
 
 @app.command("snapshot")
@@ -18,16 +21,22 @@ def snapshot(
     json_format: bool = typer.Option(False, "--json"),
 ):
     root = project_root.expanduser().resolve()
+    from devcouncil.telemetry.logging_setup import set_log_dir
+    set_log_dir(root)
+    logger.info("dev semantic snapshot: task=%s stage=%s", task_id, stage)
     initialize_project(root, quiet=True)
     if stage not in {"before", "after"}:
         console.print("[red]--stage must be before or after[/red]")
         raise typer.Exit(code=2)
-    path = SemanticIndex(root).create_snapshot(task_id, stage)
-    payload = {"task_id": task_id, "stage": stage, "path": str(path)}
-    if json_format:
-        typer.echo(json.dumps(payload, indent=2))
-    else:
-        console.print(f"[green]Wrote semantic snapshot:[/green] {path}")
+    with log_stage("semantic", project_root=root, subcommand="snapshot", task_id=task_id):
+        log_step("semantic/1: creating snapshot", project_root=root, task_id=task_id, trace=True)
+        path = SemanticIndex(root).create_snapshot(task_id, stage)
+        payload = {"task_id": task_id, "stage": stage, "path": str(path)}
+        if json_format:
+            typer.echo(dump_json(payload, indent=2))
+        else:
+            console.print(f"[green]Wrote semantic snapshot:[/green] {path}")
+        log_step("semantic/complete", project_root=root, task_id=task_id, trace=True)
 
 
 @app.command("diff")
@@ -37,11 +46,17 @@ def semantic_diff(
     json_format: bool = typer.Option(False, "--json"),
 ):
     root = project_root.expanduser().resolve()
+    from devcouncil.telemetry.logging_setup import set_log_dir
+    set_log_dir(root)
+    logger.info("dev semantic diff: task=%s", task_id)
     initialize_project(root, quiet=True)
-    result = SemanticIndex(root).diff(task_id)
-    if json_format:
-        typer.echo(json.dumps(result, indent=2))
-    else:
-        console.print(f"[cyan]Summary:[/cyan] {result['summary']}")
-        for item in result["classifications"]:
-            console.print(f" - {item['type']}: {item.get('path', '')}")
+    with log_stage("semantic", project_root=root, subcommand="diff", task_id=task_id):
+        log_step("semantic/1: computing semantic diff", project_root=root, task_id=task_id, trace=True)
+        result = SemanticIndex(root).diff(task_id)
+        if json_format:
+            typer.echo(dump_json(result, indent=2))
+        else:
+            console.print(f"[cyan]Summary:[/cyan] {result['summary']}")
+            for item in result["classifications"]:
+                console.print(f" - {item['type']}: {item.get('path', '')}")
+        log_step("semantic/complete", project_root=root, task_id=task_id, trace=True)