devcouncil 0.1.0 → 0.2.0

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

@@ -0,0 +1,73 @@
+import typer
+from pathlib import Path
+from rich.console import Console
+
+from devcouncil.cli.commands.init import initialize_project
+from devcouncil.execution.shell_session import GuardedShellSession
+from devcouncil.storage.db import get_db
+from devcouncil.storage.repositories import TaskRepository
+
+console = Console()
+
+
+def shell(
+    task_id: str = typer.Argument(..., help="Task ID"),
+    command: str | None = typer.Option(None, "--command", help="Run one guarded command and exit."),
+    shell_name: str = typer.Option("auto", "--shell", help="Shell backend: auto, pwsh, bash, zsh."),
+    force: bool = typer.Option(False, "--force", help="Reclaim a stale lease from a previous (possibly crashed) session."),
+    project_root: Path = typer.Option(Path("."), "--project-root"),
+):
+    """
+    Run guarded shell commands for a task.
+    """
+    root = project_root.expanduser().resolve()
+    initialize_project(root, quiet=True)
+    db = get_db(root)
+    if not db:
+        console.print("[red]DevCouncil not initialized.[/red]")
+        raise typer.Exit(code=1)
+
+    with db.get_session() as session:
+        task = TaskRepository(session).get_by_id(task_id)
+        if not task:
+            console.print(f"[red]Task {task_id} not found.[/red]")
+            raise typer.Exit(code=1)
+
+    try:
+        session_runner = GuardedShellSession(root, task, shell=shell_name)
+    except ValueError as exc:
+        console.print(f"[red]{exc}[/red]")
+        raise typer.Exit(code=2)
+    try:
+        session_runner.start(force=force)
+    except ValueError as exc:
+        # A live or stale lease from a prior session blocks a new one. Don't dump
+        # a traceback — tell the user how to recover.
+        console.print(f"[red]{exc}[/red]")
+        console.print(
+            "[yellow]Another shell session may be active for this task. If it is "
+            "stale (a previous session crashed), re-run with [bold]--force[/bold] to "
+            "reclaim it.[/yellow]"
+        )
+        raise typer.Exit(code=2)
+    try:
+        if command:
+            code = session_runner.run_one(command)
+            raise typer.Exit(code=code)
+
+        console.print(f"[cyan]Guarded shell for {task_id}. Type exit or quit to end.[/cyan]")
+        while True:
+            try:
+                line = input(f"devcouncil:{task_id}> ")
+            except (EOFError, KeyboardInterrupt):
+                break
+            normalized = line.strip()
+            if normalized.lower() in {"exit", "quit"}:
+                break
+            if not normalized:
+                continue
+            code = session_runner.run_one(normalized)
+            if code != 0:
+                console.print(f"[yellow]Command exited with {code}[/yellow]")
+    finally:
+        session_runner.finish()

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

@@ -1,57 +1,76 @@
-import typer
-from rich.console import Console
-from rich.panel import Panel
-from devcouncil.storage.db import get_db
-from devcouncil.storage.repositories import TaskRepository, RequirementRepository
-
-app = typer.Typer()
-console = Console()
-
-@app.callback(invoke_without_command=True)
-def show(
-    ctx: typer.Context,
-    task_id: str = typer.Argument(..., help="ID of the task to show"),
-):
-    """
-    Show details of a specific task.
-    """
-    if ctx.invoked_subcommand is not None:
-        return
-
-    db = get_db()
-    if not db:
-        console.print("[red]DevCouncil not initialized. Run 'dev init' first.[/red]")
-        raise typer.Exit(code=1)
-
-    with db.get_session() as session:
-        task_repo = TaskRepository(session)
-        req_repo = RequirementRepository(session)
-        
-        task = task_repo.get_by_id(task_id)
-        if not task:
-            console.print(f"[red]Task {task_id} not found.[/red]")
-            raise typer.Exit(code=1)
-        
-        reqs = req_repo.get_all()
-        req_map = {r.id: r for r in reqs}
-
-        output = f"[bold]Status:[/bold] {task.status}\n\n"
-        output += f"[bold]Description:[/bold]\n{task.description}\n\n"
-        
-        output += "[bold]Linked Requirements:[/bold]\n"
-        for req_id in task.requirement_ids:
-            req = req_map.get(req_id)
-            if req:
-                output += f"  - [cyan]{req.id}[/cyan]: {req.title}\n"
-            else:
-                output += f"  - [cyan]{req_id}[/cyan]: (Requirement not found)\n"
-                
-        output += "\n[bold]Planned Files:[/bold]\n"
-        for pf in task.planned_files:
-            output += f"  - {pf.path} ({pf.allowed_change}): {pf.reason}\n"
-            
-        output += "\n[bold]Expected Tests:[/bold]\n"
-        for et in task.expected_tests:
-            output += f"  - {et}\n"
-
-        console.print(Panel(output, title=f"Task {task.id}: {task.title}", expand=False))
+import json
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from devcouncil.cli.commands.init import initialize_project
+from devcouncil.storage.db import get_db
+from devcouncil.storage.repositories import TaskRepository, RequirementRepository
+
+app = typer.Typer()
+console = Console()
+
+@app.callback(invoke_without_command=True)
+def show(
+    ctx: typer.Context,
+    task_id: str = typer.Argument(..., help="ID of the task to 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/."),
+):
+    """
+    Show details of a specific task.
+    """
+    if ctx.invoked_subcommand is not None:
+        return
+
+    root = project_root.expanduser().resolve()
+    initialize_project(root, quiet=True)
+    db = get_db(root)
+    if not db:
+        raise typer.Exit(code=1)
+
+    with db.get_session() as session:
+        task_repo = TaskRepository(session)
+        req_repo = RequirementRepository(session)
+        
+        task = task_repo.get_by_id(task_id)
+        if not task:
+            console.print(f"[red]Task {task_id} not found.[/red]")
+            raise typer.Exit(code=1)
+        
+        reqs = req_repo.get_all()
+        req_map = {r.id: r for r in reqs}
+
+        if json_format:
+            linked_requirements = [
+                req_map[req_id].model_dump()
+                for req_id in task.requirement_ids
+                if req_id in req_map
+            ]
+            typer.echo(json.dumps({
+                "task": task.model_dump(),
+                "linked_requirements": linked_requirements,
+            }, indent=2))
+            return
+
+        output = f"[bold]Status:[/bold] {task.status}\n\n"
+        output += f"[bold]Description:[/bold]\n{task.description}\n\n"
+        
+        output += "[bold]Linked Requirements:[/bold]\n"
+        for req_id in task.requirement_ids:
+            req = req_map.get(req_id)
+            if req:
+                output += f"  - [cyan]{req.id}[/cyan]: {req.title}\n"
+            else:
+                output += f"  - [cyan]{req_id}[/cyan]: (Requirement not found)\n"
+                
+        output += "\n[bold]Planned Files:[/bold]\n"
+        for pf in task.planned_files:
+            output += f"  - {pf.path} ({pf.allowed_change}): {pf.reason}\n"
+            
+        output += "\n[bold]Expected Tests:[/bold]\n"
+        for et in task.expected_tests:
+            output += f"  - {et}\n"
+
+        console.print(Panel(output, title=f"Task {task.id}: {task.title}", expand=False))

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

@@ -0,0 +1,88 @@
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from devcouncil.skills.registry import get_skill, load_skills, scaffold_skills, select_skills
+
+app = typer.Typer(help="Inspect and scaffold DevCouncil engineering skills for coding agents.")
+console = Console()
+
+
+def _is_repo_skill(skill, project_root: Path) -> bool:
+    if skill.source_path is None:
+        return False
+    try:
+        skill.source_path.resolve().relative_to(project_root.resolve())
+        return True
+    except ValueError:
+        return False
+
+
+@app.callback(invoke_without_command=True)
+def skills(
+    ctx: typer.Context,
+    goal: str = typer.Option("", "--goal", help="Optional goal text; highlights the skills that would apply."),
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root used for file-based skill triggers."),
+):
+    """List available skills and show which apply to this repository/goal."""
+    if ctx.invoked_subcommand is not None:
+        return
+
+    root = project_root.expanduser().resolve()
+    all_skills = load_skills(project_root=root)
+    if not all_skills:
+        console.print("[yellow]No skills found in the DevCouncil skills library.[/yellow]")
+        raise typer.Exit()
+
+    selected = {skill.name for skill in select_skills(goal, root)}
+    table = Table(title="DevCouncil Skills")
+    table.add_column("Skill", style="cyan")
+    table.add_column("Source", justify="center")
+    table.add_column("Applies", justify="center")
+    table.add_column("Description")
+    for skill in all_skills:
+        applies = "always" if skill.always else ("yes" if skill.name in selected else "-")
+        style = "green" if skill.name in selected else "dim"
+        source = "repo" if _is_repo_skill(skill, root) else "library"
+        table.add_row(skill.name, source, f"[{style}]{applies}[/{style}]", skill.description)
+    console.print(table)
+    console.print(
+        "\nScaffold the applicable skills into this repo with: "
+        "[bold]dev skills scaffold[/bold] (add a goal to widen selection, or --all)."
+    )
+
+
+@app.command("show")
+def show(
+    name: str = typer.Argument(..., help="Skill name, e.g. core-engineering or android."),
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root, so repo-local skills are found too."),
+):
+    """Print the full body of a single skill."""
+    skill = get_skill(name, project_root=project_root.expanduser().resolve())
+    if skill is None:
+        console.print(f"[red]No skill named '{name}'. Run 'dev skills' to list available skills.[/red]")
+        raise typer.Exit(code=1)
+    console.print(skill.to_skill_md())
+
+
+@app.command("scaffold")
+def scaffold(
+    goal: str = typer.Argument("", help="Optional goal text used to widen domain-skill selection."),
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root to scaffold skills into."),
+    all_skills: bool = typer.Option(False, "--all", help="Scaffold every skill, not just the ones that apply."),
+):
+    """Write the applicable skills into <repo>/.claude/skills/<name>/SKILL.md."""
+    root = project_root.expanduser().resolve()
+    chosen = load_skills(project_root=root) if all_skills else select_skills(goal, root)
+    written = scaffold_skills(root, chosen)
+    if not written:
+        console.print(
+            f"[green]Skills already up to date in {root / '.claude' / 'skills'} "
+            f"({len(chosen)} applicable).[/green]"
+        )
+        return
+    console.print(f"[green]Wrote {len(written)} skill file(s):[/green]")
+    for path in written:
+        console.print(f"  {path.relative_to(root).as_posix()}")

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

@@ -1,105 +1,141 @@
-from rich.console import Console
-from rich.table import Table
-from rich.panel import Panel
-from pathlib import Path
-import json
-from devcouncil.storage.db import get_db
-from devcouncil.storage.repositories import ArtifactGraphRepository
-from devcouncil.telemetry.cost import CostEstimator
-
-console = Console()
-
-def status():
-    """
-    Show the current status of the DevCouncil project.
-    """
-    db = get_db()
-    if not db:
-        console.print("[yellow]DevCouncil not initialized in this directory.[/yellow]")
-        console.print("Run [bold]dev init[/bold] to get started.")
-        return
-
-    with db.get_session() as session:
-        graph_repo = ArtifactGraphRepository(session)
-        graph = graph_repo.load_graph()
-        summary = graph.coverage_summary()
-
-        reqs = list(graph.requirements.values())
-        tasks = list(graph.tasks.values())
-        blocking_gaps = graph.blocking_gaps()
-
-        # Determine phase
-        if not reqs and not tasks:
-            phase = "NEW"
-        elif reqs and not tasks:
-            phase = "REQUIREMENTS_DRAFTED"
-        elif blocking_gaps:
-            phase = "TASK_BLOCKED"
-        elif tasks:
-            statuses = {t.status for t in tasks}
-            if "running" in statuses:
-                phase = "TASK_EXECUTING"
-            elif "blocked" in statuses:
-                phase = "TASK_BLOCKED"
-            elif all(s in ("verified", "done") for s in statuses):
-                phase = "PROJECT_DONE"
-            else:
-                phase = "PLAN_APPROVED"
-        else:
-            phase = "NEW"
-
-        # Phase color
-        phase_colors = {
-            "NEW": "yellow",
-            "REQUIREMENTS_DRAFTED": "cyan",
-            "PLAN_APPROVED": "green",
-            "TASK_EXECUTING": "blue",
-            "TASK_BLOCKED": "red",
-            "PROJECT_DONE": "green bold",
-        }
-        phase_color = phase_colors.get(phase, "white")
-
-        # Calculate cost
-        total_cost = 0.0
-        log_file = Path(".devcouncil/logs/model_calls.jsonl")
-        if log_file.exists():
-            with open(log_file, "r", encoding="utf-8") as f:
-                for line in f:
-                    try:
-                        entry = json.loads(line)
-                        total_cost += CostEstimator.estimate_cost(
-                            entry.get("response", {}).get("model", ""),
-                            entry.get("usage", {})
-                        )
-                    except Exception:
-                        continue
-
-        console.print(Panel(
-            f"[bold]Phase:[/bold] [{phase_color}]{phase}[/{phase_color}]\n"
-            f"[bold]Requirements:[/bold] {summary['total_requirements']} ({summary['requirements_without_tasks']} unmapped)\n"
-            f"[bold]Tasks:[/bold] {summary['total_tasks']} ({summary['tasks_without_requirements']} orphaned)\n"
-            f"[bold]Acceptance Criteria:[/bold] {summary['total_ac']} ({summary['ac_without_evidence']} unverified)\n"
-            f"[bold]Gaps:[/bold] {summary['total_gaps']} ({summary['blocking_gaps']} blocking)\n"
-            f"[bold]Total Cost:[/bold] ${total_cost:.4f}",
-            title="DevCouncil Status",
-            expand=False,
-        ))
-
-        if tasks:
-            table = Table(title="Task Summary")
-            table.add_column("Status", style="magenta")
-            table.add_column("Count", justify="right")
-
-            status_counts: dict[str, int] = {}
-            for t in tasks:
-                status_counts[t.status] = status_counts.get(t.status, 0) + 1
-            for s, count in sorted(status_counts.items()):
-                table.add_row(s, str(count))
-            console.print(table)
-
-        if blocking_gaps:
-            console.print(f"\n[red bold]WARNING: {len(blocking_gaps)} blocking gap(s) must be resolved:[/red bold]")
-            for g in blocking_gaps[:5]:
-                console.print(f"  - [red]{g.id}[/red]: {g.description[:80]}")
-            if len(blocking_gaps) > 5:
-                console.print(f"  ... and {len(blocking_gaps) - 5} more. Run [bold]dev report[/bold] for details.")
+from rich.console import Console
+from rich.table import Table
+from rich.panel import Panel
+from pathlib import Path
+import json
+import typer
+from devcouncil.cli.commands.init import initialize_project
+from devcouncil.app.project_status import compute_phase
+from devcouncil.storage.db import get_db
+from devcouncil.storage.repositories import ArtifactGraphRepository, StateRepository
+from devcouncil.telemetry.cost import CostEstimator, cost_by_task
+from devcouncil.live.summary import live_review_summary
+
+console = Console()
+
+def _status_payload(project_root: Path) -> dict:
+    initialize_project(project_root, quiet=True)
+    db = get_db(project_root)
+    if not db:
+        return {"initialized": False, "phase": "UNINITIALIZED"}
+
+    with db.get_session() as session:
+        graph_repo = ArtifactGraphRepository(session)
+        graph = graph_repo.load_graph()
+        summary = graph.coverage_summary()
+
+        blocking_gaps = graph.blocking_gaps()
+        state = StateRepository(session).get_state()
+        phase = compute_phase(graph, state.current_phase if state else None)
+
+        total_cost = 0.0
+        log_file = project_root / ".devcouncil" / "logs" / "model_calls.jsonl"
+        if log_file.exists():
+            with open(log_file, "r", encoding="utf-8") as f:
+                for line in f:
+                    try:
+                        entry = json.loads(line)
+                        total_cost += CostEstimator.estimate_cost(
+                            entry.get("response", {}).get("model", ""),
+                            entry.get("usage", {}),
+                        )
+                    except Exception:
+                        continue
+
+        status_counts: dict[str, int] = {}
+        for task in graph.tasks.values():
+            status_counts[task.status] = status_counts.get(task.status, 0) + 1
+
+        return {
+            "initialized": True,
+            "phase": phase,
+            "coverage_summary": summary,
+            "total_cost": total_cost,
+            "cost_by_task": cost_by_task(project_root),
+            "task_status_counts": status_counts,
+            "blocking_gaps": [gap.model_dump() for gap in blocking_gaps],
+            "live_review": live_review_summary(project_root),
+        }
+
+
+def status(
+    json_format: bool = typer.Option(False, "--json", help="Output machine-readable JSON."),
+    fail_on_blocking: bool = typer.Option(
+        False,
+        "--fail-on-blocking",
+        help="Exit non-zero when blocking gaps remain, so shell-driven agents can gate on $?.",
+    ),
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root containing .devcouncil/."),
+):
+    """
+    Show the current status of the DevCouncil project.
+    """
+    root = project_root.expanduser().resolve()
+    payload = _status_payload(root)
+
+    def _maybe_fail() -> None:
+        if fail_on_blocking and payload.get("blocking_gaps"):
+            raise typer.Exit(code=1)
+
+    if json_format:
+        typer.echo(json.dumps(payload, indent=2))
+        _maybe_fail()
+        return
+
+    if not payload["initialized"]:
+        console.print("[yellow]DevCouncil state is not available in this directory.[/yellow]")
+        return
+
+    summary = payload["coverage_summary"]
+    phase = payload["phase"]
+    phase_colors = {
+        "NEW": "yellow",
+        "REQUIREMENTS_DRAFTED": "cyan",
+        "PLAN_APPROVED": "green",
+        "TASK_EXECUTING": "blue",
+        "TASK_BLOCKED": "red",
+        "PROJECT_DONE": "green bold",
+    }
+    phase_color = phase_colors.get(phase, "white")
+
+    console.print(Panel(
+        f"[bold]Phase:[/bold] [{phase_color}]{phase}[/{phase_color}]\n"
+        f"[bold]Requirements:[/bold] {summary['total_requirements']} ({summary['requirements_without_tasks']} unmapped)\n"
+        f"[bold]Tasks:[/bold] {summary['total_tasks']} ({summary['tasks_without_requirements']} orphaned)\n"
+        f"[bold]Acceptance Criteria:[/bold] {summary['total_ac']} ({summary['ac_without_evidence']} unverified)\n"
+        f"[bold]Gaps:[/bold] {summary['total_gaps']} ({summary['blocking_gaps']} blocking)\n"
+        f"[bold]Live Review:[/bold] {payload['live_review']['cards']['critical_open']} open critical, "
+        f"{len(payload['live_review']['blocking_cards'])} blocking in scope, "
+        f"{payload['live_review']['pending_signals']} pending signal(s)\n"
+        f"[bold]Total Cost:[/bold] ${payload['total_cost']:.4f}",
+        title="DevCouncil Status",
+        expand=False,
+    ))
+
+    if payload["task_status_counts"]:
+        table = Table(title="Task Summary")
+        table.add_column("Status", style="magenta")
+        table.add_column("Count", justify="right")
+        for state, count in sorted(payload["task_status_counts"].items()):
+            table.add_row(state, str(count))
+        console.print(table)
+
+    cost_groups = payload.get("cost_by_task") or {}
+    if cost_groups:
+        cost_table = Table(title="Cost by Task")
+        cost_table.add_column("Task", style="cyan")
+        cost_table.add_column("Cost ($)", justify="right")
+        cost_table.add_column("Calls", justify="right")
+        for name, stats in sorted(cost_groups.items(), key=lambda kv: kv[1]["cost"], reverse=True):
+            cost_table.add_row(name, f"{stats['cost']:.4f}", str(stats["calls"]))
+        console.print(cost_table)
+
+    blocking_gaps = payload["blocking_gaps"]
+    if blocking_gaps:
+        console.print(f"\n[red bold]WARNING: {len(blocking_gaps)} blocking gap(s) must be resolved:[/red bold]")
+        for gap in blocking_gaps[:5]:
+            console.print(f"  - [red]{gap['id']}[/red]: {gap['description'][:80]}")
+        if len(blocking_gaps) > 5:
+            console.print(f"  ... and {len(blocking_gaps) - 5} more. Run [bold]dev report[/bold] for details.")
+
+    _maybe_fail()

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

@@ -1,41 +1,55 @@
-import typer
-from rich.console import Console
-from rich.table import Table
-from devcouncil.storage.db import get_db
-from devcouncil.storage.repositories import TaskRepository
-
-app = typer.Typer()
-console = Console()
-
-@app.callback(invoke_without_command=True)
-def tasks(ctx: typer.Context):
-    """
-    List task graph and task gate status.
-    """
-    if ctx.invoked_subcommand is not None:
-        return
-
-    db = get_db()
-    if not db:
-        console.print("[red]DevCouncil not initialized. Run 'dev init' first.[/red]")
-        raise typer.Exit(code=1)
-
-    with db.get_session() as session:
-        task_repo = TaskRepository(session)
-        tasks_list = task_repo.get_all()
-        
-        if not tasks_list:
-            console.print("No tasks found. Run 'dev plan' to generate tasks.")
-            return
-
-        table = Table(title="DevCouncil Tasks")
-        table.add_column("Task ID", style="cyan", no_wrap=True)
-        table.add_column("Title", style="white")
-        table.add_column("Status", style="magenta")
-        table.add_column("Linked Reqs", style="green")
-
-        for t in tasks_list:
-            reqs = ", ".join(t.requirement_ids)
-            table.add_row(t.id, t.title, t.status, reqs)
-
-        console.print(table)
+import json
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.table import Table
+from devcouncil.cli.commands.init import initialize_project
+from devcouncil.storage.db import get_db
+from devcouncil.storage.repositories import TaskRepository
+
+app = typer.Typer()
+console = Console()
+
+@app.callback(invoke_without_command=True)
+def tasks(
+    ctx: typer.Context,
+    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/."),
+):
+    """
+    List task graph and task gate status.
+    """
+    if ctx.invoked_subcommand is not None:
+        return
+
+    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)
+
+    with db.get_session() as session:
+        task_repo = TaskRepository(session)
+        tasks_list = task_repo.get_all()
+
+        if json_format:
+            typer.echo(json.dumps({"tasks": [task.model_dump() for task in tasks_list]}, indent=2))
+            return
+        
+        if not tasks_list:
+            console.print("No tasks found. Run 'dev plan' to generate tasks.")
+            return
+
+        table = Table(title="DevCouncil Tasks")
+        table.add_column("Task ID", style="cyan", no_wrap=True)
+        table.add_column("Title", style="white")
+        table.add_column("Status", style="magenta")
+        table.add_column("Linked Reqs", style="green")
+
+        for t in tasks_list:
+            reqs = ", ".join(t.requirement_ids)
+            table.add_row(t.id, t.title, t.status, reqs)
+
+        console.print(table)