devcouncil 0.1.1 → 0.3.0

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

@@ -0,0 +1,292 @@
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from devcouncil.cli.commands import run as run_command
+from devcouncil.cli.commands.integrate import _load_raw_config, _project_root, _save_raw_config
+from devcouncil.executors.agent_registry import (
+    VALID_INPUT_MODES,
+    agent_config_entry,
+    detect_available_coding_cli,
+    is_reserved_agent_name,
+    load_agent_profiles,
+    load_cli_agent_specs,
+    normalize_agent_name,
+    resolve_automated_executor,
+    resolve_cursor_agent_executable,
+)
+from devcouncil.optimization.gepa_agent import GepaUnavailableError, optimize_agent_profile
+
+app = typer.Typer(help="Manage DevCouncil CLI agents.")
+console = Console()
+
+
+@app.callback(invoke_without_command=True)
+def list_agents(
+    ctx: typer.Context,
+    project_root: Path | None = typer.Option(None, "--project-root", help="Repository root containing .devcouncil/."),
+):
+    """List built-in and configured CLI agents."""
+    if ctx.invoked_subcommand is not None:
+        return
+
+    root = _project_root(project_root)
+    table = Table(title="DevCouncil Agents")
+    table.add_column("Agent", style="cyan")
+    table.add_column("Type")
+    table.add_column("Command")
+    table.add_column("Profile")
+    table.add_column("MCP")
+    table.add_column("Diff Review")
+
+    for name, spec in sorted(load_cli_agent_specs(root).items()):
+        table.add_row(
+            name,
+            "built-in" if spec.built_in else spec.kind,
+            " ".join(spec.base_command()),
+            spec.default_profile,
+            "yes" if spec.supports_mcp else "no",
+            "yes" if spec.supports_diff_review else "no",
+        )
+    console.print(table)
+
+
+@app.command("add")
+def add_agent(
+    name: str = typer.Argument(..., help="Agent name, for example opencode or aider."),
+    command: str = typer.Option(..., "--command", help="Executable to launch."),
+    arg: list[str] | None = typer.Option(None, "--arg", help="Argument to pass to the CLI. Repeat for multiple args."),
+    input_mode: str = typer.Option("stdin", "--input-mode", help="Prompt input mode: stdin, argument, or prompt-file."),
+    prompt_arg: str | None = typer.Option(None, "--prompt-arg", help="Flag used before the prompt or prompt file."),
+    timeout_seconds: int | None = typer.Option(None, "--timeout-seconds", help="Agent-specific timeout override."),
+    display_name: str | None = typer.Option(None, "--display-name", help="Human-readable agent name."),
+    kind: str = typer.Option("custom", "--kind", help="Agent kind, for example coding-cli or review-cli."),
+    supports_mcp: bool = typer.Option(False, "--supports-mcp", help="Mark this agent as MCP-capable."),
+    supports_diff_review: bool = typer.Option(False, "--supports-diff-review", help="Mark this agent as able to review diffs."),
+    default_profile: str = typer.Option("default", "--default-profile", help="Default execution profile for this agent."),
+    help_arg: list[str] | None = typer.Option(None, "--help-arg", help="Argument for the agent help command. Repeat for multiple args."),
+    project_root: Path | None = typer.Option(None, "--project-root", help="Repository root containing .devcouncil/."),
+):
+    """Register an arbitrary prompt-taking CLI as a DevCouncil agent."""
+    if input_mode not in VALID_INPUT_MODES:
+        console.print("[red]--input-mode must be one of: stdin, argument, prompt-file.[/red]")
+        raise typer.Exit(code=2)
+    if not name.strip():
+        console.print("[red]Agent name cannot be empty.[/red]")
+        raise typer.Exit(code=2)
+    if not command.strip():
+        console.print("[red]--command cannot be empty.[/red]")
+        raise typer.Exit(code=2)
+
+    root = _project_root(project_root)
+    if is_reserved_agent_name(name):
+        console.print(f"[red]'{name}' is reserved for a built-in DevCouncil agent.[/red]")
+        raise typer.Exit(code=2)
+    if default_profile not in load_agent_profiles(root):
+        console.print(f"[red]Unknown --default-profile '{default_profile}'.[/red]")
+        raise typer.Exit(code=2)
+
+    normalized = normalize_agent_name(name)
+    entry = agent_config_entry(
+        command=command,
+        args=arg or [],
+        input_mode=input_mode,
+        prompt_arg=prompt_arg,
+        timeout_seconds=timeout_seconds,
+        display_name=display_name,
+        kind=kind,
+        supports_mcp=supports_mcp,
+        supports_diff_review=supports_diff_review,
+        default_profile=default_profile,
+        help_command=[command, *(help_arg or [])] if help_arg else [],
+    )
+    config = _load_raw_config(root)
+    agents = config.setdefault("integrations", {}).setdefault("cli_agents", {}).setdefault("agents", {})
+    agents[normalized] = entry
+    _save_raw_config(root, config)
+    console.print(f"[green]Registered CLI agent '{normalized}' in .devcouncil/config.yaml.[/green]")
+
+
+@app.command("doctor")
+def doctor(
+    project_root: Path | None = typer.Option(None, "--project-root", help="Repository root containing .devcouncil/."),
+):
+    """Check configured CLI agents and execution profiles."""
+    root = _project_root(project_root)
+    profiles = load_agent_profiles(root)
+    table = Table(title="DevCouncil Agent Doctor")
+    table.add_column("Agent", style="cyan")
+    table.add_column("Status")
+    table.add_column("Details", no_wrap=True)
+
+    for name, spec in sorted(load_cli_agent_specs(root).items()):
+        if spec.name == "cursor":
+            executable = resolve_cursor_agent_executable()
+        else:
+            executable = _which(spec.executable)
+        mode_ok = spec.input_mode in VALID_INPUT_MODES
+        profile_ok = spec.default_profile in profiles
+        help_ok, help_detail = _check_help(spec.help_command or [spec.executable, "--help"])
+
+        if executable and mode_ok and profile_ok:
+            status = "[green]OK[/green]"
+        elif executable:
+            status = "[red]Invalid[/red]"
+        else:
+            status = "[yellow]Missing[/yellow]"
+
+        details = []
+        details.append(executable or f"{spec.executable} not found on PATH")
+        if not mode_ok:
+            details.append(f"invalid input_mode={spec.input_mode}")
+        if not profile_ok:
+            details.append(f"missing profile={spec.default_profile}")
+        if help_ok:
+            details.append("help command OK")
+        elif not spec.built_in:
+            details.append(help_detail)
+        table.add_row(name, status, "; ".join(details))
+
+    console.print(table)
+    detected = detect_available_coding_cli(root)
+    if detected:
+        resolved = resolve_automated_executor(root, None)
+        console.print(
+            f"\n[dim]Auto-pick for dev go / dev run:[/dim] [cyan]{resolved}[/cyan] "
+            f"(first built-in CLI on PATH in probe order)"
+        )
+    else:
+        console.print("\n[dim]No built-in coding CLI on PATH for auto-pick.[/dim]")
+
+
+@app.command("run")
+def run_agent(
+    task_id: str = typer.Argument(..., help="ID of the task to run."),
+    agent: str = typer.Option(..., "--agent", "-a", help="Agent name to execute."),
+    profile: str | None = typer.Option(None, "--profile", help="Execution profile: default, yolo, prod, or configured."),
+    stream: bool = typer.Option(
+        False,
+        "--stream",
+        help="Stream coding CLI stdout/stderr live (also enabled by execution.stream_cli_output).",
+    ),
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root containing .devcouncil/."),
+):
+    """Run a DevCouncil task with a named CLI agent and profile."""
+    run_command.run(task_id, executor=agent, profile=profile, stream=stream, project_root=project_root)
+
+
+def _which(command: str) -> str | None:
+    from shutil import which
+
+    return which(command)
+
+
+@app.command("help")
+def agent_help(
+    name: str = typer.Argument(..., help="Agent name, for example codex or opencode."),
+    project_root: Path | None = typer.Option(None, "--project-root", help="Repository root containing .devcouncil/."),
+):
+    """Show the underlying CLI agent's own help output."""
+    root = _project_root(project_root)
+    spec = load_cli_agent_specs(root).get(normalize_agent_name(name))
+    if spec is None:
+        console.print(f"[red]Unknown agent '{name}'. Use 'dev agents' to list available agents.[/red]")
+        raise typer.Exit(code=1)
+    command = list(spec.help_command) or [spec.executable, "--help"]
+    executable = _which(command[0])
+    if not executable:
+        console.print(f"[red]{command[0]} is not installed or not on PATH.[/red]")
+        raise typer.Exit(code=1)
+    resolved = [executable, *command[1:]]
+    use_shell = sys.platform == "win32" and Path(executable).suffix.lower() in {".bat", ".cmd", ".ps1"}
+    try:
+        result = subprocess.run(
+            subprocess.list2cmdline(resolved) if use_shell else resolved,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=15,
+            shell=use_shell,
+        )
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError) as exc:
+        console.print(f"[red]Failed to run {' '.join(command)}: {exc}[/red]")
+        raise typer.Exit(code=1)
+    output = (result.stdout or "") + (result.stderr or "")
+    typer.echo(output.strip())
+    raise typer.Exit(code=result.returncode)
+
+
+def _check_help(command: list[str]) -> tuple[bool, str]:
+    executable = _which(command[0]) if command else None
+    if not command or not executable:
+        return False, "help command unavailable"
+    resolved = [executable, *command[1:]]
+    use_shell = sys.platform == "win32" and Path(executable).suffix.lower() in {".bat", ".cmd", ".ps1"}
+    try:
+        result = subprocess.run(
+            subprocess.list2cmdline(resolved) if use_shell else resolved,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=5,
+            shell=use_shell,
+        )
+    except subprocess.TimeoutExpired:
+        return False, "help command timed out"
+    return result.returncode == 0, f"help command exited {result.returncode}"
+
+
+@app.command("optimize")
+def optimize_agent(
+    agent: str = typer.Option(..., "--agent", "-a", help="Agent name to optimize, for example codex or opencode."),
+    profile_name: str = typer.Option("default", "--profile", help="Profile name to optimize: default, yolo, prod, or configured."),
+    evals_path: Path = typer.Option(..., "--evals", help="JSON or JSONL GEPA evaluation dataset."),
+    max_metric_calls: int = typer.Option(40, "--max-metric-calls", min=1, help="Maximum GEPA metric calls."),
+    objective: str | None = typer.Option(None, "--objective", help="Override the default optimization objective."),
+    apply: bool = typer.Option(
+        False,
+        "--apply/--dry-run",
+        help="Write the optimized preamble into .devcouncil/config.yaml. Defaults to dry-run.",
+    ),
+    output_path: Path | None = typer.Option(None, "--output", help="Write the optimization artifact to this path."),
+    project_root: Path | None = typer.Option(None, "--project-root", help="Repository root containing .devcouncil/."),
+):
+    """
+    Optimize a CLI-agent profile prompt preamble with GEPA.
+    """
+    root = _project_root(project_root)
+    try:
+        result = optimize_agent_profile(
+            project_root=root,
+            agent=agent,
+            profile_name=profile_name,
+            evals_path=evals_path,
+            max_metric_calls=max_metric_calls,
+            objective=objective,
+            apply=apply,
+            output_path=output_path,
+        )
+    except GepaUnavailableError as exc:
+        console.print(f"[red]{exc}[/red]")
+        raise typer.Exit(code=1) from exc
+    except ValueError as exc:
+        console.print(f"[red]{exc}[/red]")
+        raise typer.Exit(code=2) from exc
+
+    mode = "applied" if result.applied else "dry-run"
+    score = "unknown" if result.best_score is None else f"{result.best_score:.3f}"
+    console.print(
+        f"[green]GEPA optimization complete ({mode}) for {result.agent}:{result.profile_name}.[/green]"
+    )
+    console.print(f"Score: [bold]{score}[/bold]")
+    console.print(f"Artifact: [dim]{result.artifact_path}[/dim]")
+    console.print("\n[bold]Optimized preamble[/bold]")
+    console.print(result.best_preamble or "[dim](empty)[/dim]")

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

@@ -14,10 +14,13 @@ console = Console()
 
 
 @app.command(name="validate")
-def validate():
+def validate(
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root containing .devcouncil/."),
+):
     """Validate requirements and tasks stored in the artifact graph."""
-    initialize_project(Path("."), quiet=True)
-    db = get_db()
+    root = project_root.expanduser().resolve()
+    initialize_project(root, quiet=True)
+    db = get_db(root)
     if not db:
         console.print("[red]DevCouncil state is unavailable in this directory.[/red]")
         raise typer.Exit(code=1)

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

@@ -0,0 +1,220 @@
+"""`dev check` — a one-shot audit of the current uncommitted changes.
+
+The lowest-friction entry point: no planning, no task graph. You let a coding
+agent change your repo, then `dev check` tells you what is out of scope, what
+edge cases look unhandled, what's risky, and whether any secrets leaked —
+grounded in the real diff. With ``--goal`` it also compiles acceptance checks
+from the stated intent and runs them as evidence.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import subprocess
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from devcouncil.app.config import get_api_key, load_config
+from devcouncil.cli.commands.init import initialize_project
+from devcouncil.domain.task import Task
+from devcouncil.integrations.code_review_graph import CodeReviewGraphAdapter
+from devcouncil.integrations.github_intent import resolve_goal_intent
+from devcouncil.llm.provider import ProviderRequestError, create_provider, validate_model_provider
+from devcouncil.llm.router import ModelRouter, StructuredOutputError
+from devcouncil.verification.ad_hoc_check import AdHocCheckResult, run_working_tree_check
+from devcouncil.verification.implementation_reviewer import ImplementationReviewer
+from devcouncil.verification.verifier import Verifier
+
+console = Console()
+logger = logging.getLogger(__name__)
+
+
+def _diff(root: Path, base: str | None) -> str:
+    if not base:
+        return Verifier(root).get_diff()
+    try:
+        return subprocess.check_output(
+            ["git", "diff", base, "--"], cwd=root, text=True, encoding="utf-8", errors="replace"
+        )
+    except Exception:
+        return ""
+
+
+def check(
+    goal: str | None = typer.Option(None, "--goal", "-g", help="What the change was meant to do — sharpens the review and enables acceptance checks. Also accepts a GitHub issue/PR reference (#142, owner/repo#142, or a github.com URL)."),
+    base: str | None = typer.Option(None, "--base", help="Diff against this git ref instead of the uncommitted working tree."),
+    test_commands: list[str] | None = typer.Option(None, "--test", "-t", help="A verification command proving the change works (repeatable). Switches to the deterministic evidence gate."),
+    verify: bool = typer.Option(False, "--verify", help="Run the deterministic evidence gate (orphan-diff, acceptance evidence, diff↔coverage, next actions) instead of the LLM audit. No provider keys needed."),
+    enforce_coverage: bool = typer.Option(False, "--enforce-coverage", help="Evidence gate: block when the tests do not exercise the changed lines."),
+    min_coverage: float = typer.Option(0.0, "--min-coverage", help="Evidence gate: minimum fraction of changed lines that must be exercised (implies --enforce-coverage)."),
+    json_format: bool = typer.Option(False, "--json", help="Machine-readable output."),
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root."),
+):
+    """Audit the current changes — scope, risks, missing edge cases, secrets — no planning required."""
+    root = project_root.expanduser().resolve()
+    from devcouncil.telemetry.logging_setup import set_log_dir
+    set_log_dir(root)
+    initialize_project(root, quiet=True)
+
+    # A --goal of "#142" or a GitHub issue/PR URL is a reference, not a spec —
+    # expand it into the issue/PR title + body so acceptance checks and the review
+    # are grounded in the real intent (same behavior as `dev go`).
+    if goal:
+        expanded_goal, intent_note = resolve_goal_intent(goal, root)
+        if intent_note and not json_format:
+            console.print(f"[dim]{intent_note}[/dim]")
+        goal = expanded_goal
+
+    # Evidence-gate mode: deterministic verification of the working-tree diff against an
+    # inline requirement (--goal), with the diff↔coverage gate and the typed next-actions
+    # contract. Provider-key-free — this is the lite path that lets you taste the gate.
+    if verify or test_commands:
+        result = run_working_tree_check(
+            root,
+            goal,
+            test_commands=list(test_commands or []),
+            enforce_coverage=enforce_coverage,
+            min_ratio=min_coverage,
+        )
+        if json_format:
+            typer.echo(json.dumps(result.to_dict(), indent=2))
+        else:
+            _render_gate(result)
+        raise typer.Exit(code=0 if result.passed else 1)
+
+    verifier = Verifier(root)
+
+    logger.info("dev check (LLM audit): base=%s goal=%s", base or "working-tree", "set" if goal else "none")
+    diff = _diff(root, base)
+    if not diff.strip():
+        logger.info("dev check: clean working tree; nothing to audit")
+        msg = "No changes to check (clean working tree)."
+        typer.echo(json.dumps({"ok": True, "message": msg}) if json_format else msg)
+        return
+
+    changed_files = verifier.get_changed_files()
+    secret_gaps = verifier.secret_scanner.scan_diff(diff, "check")
+    if secret_gaps:
+        logger.warning("dev check: %d possible secret(s) in diff across %d changed file(s)", len(secret_gaps), len(changed_files))
+
+    # Blast radius: what do the changed files ripple into? Surfaced from the
+    # structural graph when the code-review-graph integration is enabled, so a
+    # reviewer sees the impact (and which tests to run) before approving.
+    graph_context = CodeReviewGraphAdapter(root).get_context(changed_files)
+
+    findings = []
+    review_note = 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, provider_prefs=config.provider)
+        role_config = {name: role.model_dump() for name, role in config.models.roles.items()}
+        router = ModelRouter(provider, role_config, project_root=root)
+        synthetic = Task(
+            id="CHECK",
+            title="Ad-hoc change review",
+            description=(
+                goal
+                or "Review these changes for correctness, missing edge cases, error handling, "
+                "risky shortcuts, and scope creep."
+            ),
+        )
+        review = asyncio.run(ImplementationReviewer(router).review_changes(synthetic, [], diff))
+        findings = review.findings
+    except (ProviderRequestError, StructuredOutputError) as exc:
+        logger.warning("dev check: LLM review unavailable: %s", exc)
+        review_note = f"LLM review unavailable: {exc}"
+    except Exception as exc:  # pragma: no cover - best effort
+        logger.warning("dev check: LLM review unavailable: %s", exc)
+        review_note = f"LLM review unavailable: {exc}"
+    logger.info("dev check audit complete: %d secret finding(s), %d review finding(s)", len(secret_gaps), len(findings))
+
+    if json_format:
+        typer.echo(json.dumps({
+            "ok": not secret_gaps,
+            "changed_files": changed_files,
+            "secret_findings": [g.model_dump() for g in secret_gaps],
+            "review_findings": [g.model_dump() for g in findings],
+            "review_note": review_note,
+            "blast_radius": {
+                "available": graph_context.available,
+                "impacted_files": graph_context.impacted_files,
+                "related_tests": graph_context.related_tests,
+            },
+        }, indent=2))
+        return
+
+    console.print(f"[bold]Changed files ({len(changed_files)}):[/bold] " + ", ".join(changed_files[:20]) or "(none)")
+    if secret_gaps:
+        console.print(f"\n[red bold]⚠ Possible secrets in the diff ({len(secret_gaps)}):[/red bold]")
+        for g in secret_gaps[:10]:
+            console.print(f"  - {g.description[:100]}")
+    if findings:
+        console.print(f"\n[bold]Review findings ({len(findings)}):[/bold]")
+        for f in findings[:15]:
+            sev = getattr(f, "severity", "info")
+            colour = {"critical": "red", "high": "red", "medium": "yellow"}.get(sev, "white")
+            console.print(f"  - [{colour}]{sev}[/{colour}]: {f.description[:140]}")
+    if graph_context.available and (graph_context.impacted_files or graph_context.related_tests):
+        console.print("\n[bold]Blast radius[/bold] [dim](from the structural graph)[/dim]:")
+        if graph_context.impacted_files:
+            console.print(f"  [cyan]Impacted files ({len(graph_context.impacted_files)}):[/cyan] "
+                          + ", ".join(graph_context.impacted_files[:15]))
+        if graph_context.related_tests:
+            console.print(f"  [cyan]Related tests ({len(graph_context.related_tests)}):[/cyan] "
+                          + ", ".join(graph_context.related_tests[:15]))
+    if not secret_gaps and not findings:
+        console.print("\n[green]No secrets or review concerns found in the diff.[/green]")
+    if review_note:
+        console.print(f"\n[dim]{review_note}[/dim]")
+    console.print(
+        "\n[dim]Tip: `dev check --goal \"what this change should do\"` sharpens the review.[/dim]"
+    )
+    console.print(
+        "[dim]Tip: `dev check --verify --test \"<cmd>\"` runs the deterministic evidence gate "
+        "(no provider keys).[/dim]"
+    )
+
+
+def _render_gate(result: AdHocCheckResult) -> None:
+    """Render the deterministic evidence-gate result for humans."""
+    if result.reason == "no_changes":
+        console.print("[yellow]No working-tree changes to verify. Make a change first, then re-run.[/yellow]")
+        return
+
+    console.print(f"[bold]Checking:[/bold] {result.requirement}")
+    console.print(f"[dim]{len(result.changed_files)} changed file(s) in scope.[/dim]")
+    if result.diff_coverage and result.diff_coverage.measured:
+        console.print(f"[dim]Diff coverage: {result.diff_coverage.summary}[/dim]")
+
+    if not result.gaps:
+        console.print("\n[green]Verified: the change is backed by passing evidence.[/green]")
+        return
+
+    table = Table(title="Findings")
+    table.add_column("Type", style="cyan")
+    table.add_column("Severity", style="magenta")
+    table.add_column("Finding", style="white")
+    table.add_column("Blocking", style="red")
+    for gap in result.gaps[:20]:
+        table.add_row(gap.gap_type, gap.severity, gap.description, "YES" if gap.blocking else "no")
+    console.print(table)
+
+    if result.next_actions:
+        console.print("\n[bold]Next actions:[/bold]")
+        for action in result.next_actions:
+            location = ""
+            if action.file:
+                location = f" [dim]({action.file}{':' + str(action.line) if action.line else ''})[/dim]"
+            console.print(f"  • [[cyan]{action.category}[/cyan]] {action.action}{location}")
+
+    if result.passed:
+        console.print("\n[green]Verified with non-blocking signals only.[/green]")
+    else:
+        console.print("\n[red]Not verified: blocking gaps must be resolved.[/red]")

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

@@ -2,8 +2,14 @@ import typer
 import yaml
 from pathlib import Path
 from rich.console import Console
+from devcouncil.cli.commands.init import parse_role_model_overrides
 from devcouncil.app.config import load_config
-from devcouncil.llm.provider import SUPPORTED_MODEL_PROVIDERS, validate_model_provider
+from devcouncil.llm.provider import (
+    SUPPORTED_MODEL_PROVIDERS,
+    apply_provider_default_role_models,
+    build_role_model_config,
+    validate_model_provider,
+)
 
 app = typer.Typer(help="Manage DevCouncil configuration")
 console = Console()
@@ -11,21 +17,34 @@ console = Console()
 @app.command("models")
 def models(
     role: str = typer.Option(None, "--role", "-r", help="Specific role to show/edit"),
-    model: str = typer.Option(None, "--model", "-m", help="New model string to set for the role"),
+    model: str = typer.Option(None, "--model", "-m", help="New model string to set for the role, or every role when --role is omitted."),
     provider: str = typer.Option(None, "--provider", help="Set the model provider."),
+    role_model: list[str] | None = typer.Option(
+        None,
+        "--role-model",
+        help="Per-role model override in ROLE=MODEL form. Can be repeated.",
+    ),
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root containing .devcouncil/."),
 ):
     """View or edit model role configuration."""
+    root = project_root.expanduser().resolve()
     try:
-        load_config(Path("."))
+        load_config(root)
     except FileNotFoundError as e:
         console.print(f"[red]{e}[/red]")
         return
 
-    config_path = Path(".devcouncil/config.yaml")
+    config_path = root / ".devcouncil" / "config.yaml"
     
     with open(config_path) as f:
         raw_config = yaml.safe_load(f) or {}
 
+    try:
+        role_models = parse_role_model_overrides(role_model)
+    except ValueError as e:
+        console.print(f"[red]{e}[/red]")
+        raise typer.Exit(code=2) from e
+
     if provider:
         try:
             normalized_provider = validate_model_provider(provider)
@@ -35,12 +54,32 @@ def models(
         raw_config.setdefault("models", {})
         previous = raw_config["models"].get("provider", "openrouter")
         raw_config["models"]["provider"] = normalized_provider
+        updated_role_defaults = apply_provider_default_role_models(raw_config, previous, normalized_provider)
         with open(config_path, "w") as f:
             yaml.dump(raw_config, f, default_flow_style=False)
         if previous == normalized_provider:
             console.print(f"[green]Model provider remains '{normalized_provider}'.[/green]")
         else:
             console.print(f"[green]Updated model provider from '{previous}' to '{normalized_provider}'.[/green]")
+        if updated_role_defaults:
+            console.print(f"[green]Updated default role models for '{normalized_provider}'.[/green]")
+        if not model and not role_models:
+            return
+
+    if not role and (model or role_models):
+        raw_config.setdefault("models", {})
+        configured_provider = validate_model_provider(raw_config["models"].get("provider", "openrouter"))
+        raw_config["models"]["roles"] = build_role_model_config(
+            configured_provider,
+            model=model,
+            role_models=role_models,
+        )
+        with open(config_path, "w") as f:
+            yaml.dump(raw_config, f, default_flow_style=False)
+        if model:
+            console.print(f"[green]Updated all model roles to use '{model}'.[/green]")
+        for selected_role, selected_model in role_models.items():
+            console.print(f"[green]Updated '{selected_role}' to use model '{selected_model}'.[/green]")
         return
 
     if not role:

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

@@ -0,0 +1,57 @@
+import json
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from devcouncil.telemetry.cost import group_cost
+
+app = typer.Typer(help="Inspect DevCouncil model-call cost, grouped by task and run.")
+console = Console()
+
+
+@app.command("show")
+def show(
+    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/."),
+):
+    """Report estimated model-call cost grouped by task_id and run_id.
+
+    Reads the local ``model_calls.jsonl`` ledger only — fully offline. Records
+    written before per-task attribution (or made without a task/run context) are
+    grouped under ``(unattributed)``.
+    """
+    root = project_root.expanduser().resolve()
+    summary = group_cost(root)
+
+    if json_format:
+        typer.echo(json.dumps(summary, indent=2))
+        return
+
+    console.print(
+        f"[bold]Total Cost:[/bold] ${summary['total_cost']:.4f} "
+        f"across {summary['total_calls']} model call(s)"
+    )
+
+    def _render(title: str, groups: dict) -> None:
+        if not groups:
+            return
+        table = Table(title=title)
+        table.add_column("Group", style="cyan")
+        table.add_column("Cost ($)", justify="right")
+        table.add_column("Calls", justify="right")
+        table.add_column("Prompt", justify="right")
+        table.add_column("Completion", justify="right")
+        for name, stats in sorted(groups.items(), key=lambda kv: kv[1]["cost"], reverse=True):
+            table.add_row(
+                name,
+                f"{stats['cost']:.4f}",
+                str(stats["calls"]),
+                str(stats["prompt_tokens"]),
+                str(stats["completion_tokens"]),
+            )
+        console.print(table)
+
+    _render("Cost by Task", summary["by_task"])
+    _render("Cost by Run", summary["by_run"])