devcouncil 0.1.1 → 0.2.0

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

@@ -1,8 +1,9 @@
 import typer
-import subprocess
 from pathlib import Path
 from rich.console import Console
 
+from devcouncil.execution.checkpoints import CheckpointService
+
 app = typer.Typer()
 console = Console()
 
@@ -19,42 +20,40 @@ def rollback(
         return
 
     root = project_root.expanduser().resolve()
-    checkpoint_file = root / ".devcouncil" / "checkpoints" / f"{task_id}-before.patch"
-    after_patch = root / ".devcouncil" / "checkpoints" / f"{task_id}-after.patch"
+    checkpoint_dir = root / ".devcouncil" / "checkpoints"
+    checkpoint_file = checkpoint_dir / f"{task_id}-before.patch"
+    after_patch = checkpoint_dir / f"{task_id}-after.patch"
+    service = CheckpointService(root)
 
     if not checkpoint_file.exists() and not after_patch.exists():
-        console.print(
-            f"[red]No checkpoint found for task {task_id}. Expected {after_patch} "
-            f"or {checkpoint_file}.[/red]"
-        )
-        raise typer.Exit(code=1)
+        before_ref = CheckpointService.REF_BEFORE.format(task_id=task_id)
+        after_ref = CheckpointService.REF_AFTER.format(task_id=task_id)
+        if not service._ref_exists(before_ref) and not service._ref_exists(after_ref):
+            console.print(
+                f"[red]No checkpoint found for task {task_id}. Expected {after_patch} "
+                f"or {checkpoint_file}.[/red]"
+            )
+            raise typer.Exit(code=1)
 
     console.print(f"Rolling back task [bold]{task_id}[/bold]...")
-    
-    try:
-        if after_patch.exists():
-            # Reverse-apply the task's changes only
-            console.print(f"Applying reverse patch from [bold]{after_patch}[/bold]...")
-            subprocess.check_call(
-                ["git", "apply", "-R", str(after_patch)],
-                cwd=root,
-            )
-            console.print(f"[green]Successfully rolled back task {task_id} changes.[/green]")
-        else:
-            # No after-patch, but we have the before-patch — warn and offer manual reset
+    result = service.rollback(task_id)
+    if "failed" in result.message.lower() or result.message.startswith("No checkpoint"):
+        console.print(f"[yellow]{result.message}[/yellow]")
+        if checkpoint_file.exists():
             console.print(
-                f"[yellow]No after-patch found at {after_patch}.[/yellow]\n"
                 f"The before-patch at {checkpoint_file} captured the state before the task ran.\n"
                 f"To manually reset:\n"
                 f"  1. [bold]git stash[/bold] (if you want to keep current changes)\n"
                 f"  2. [bold]git checkout -- .[/bold] (discard working tree changes)\n"
                 f"  3. [bold]git apply {checkpoint_file}[/bold] (restore pre-task state)"
             )
-    except subprocess.CalledProcessError as e:
-        console.print(f"[red]Failed to apply reverse patch: {e}[/red]")
-        console.print("[yellow]The patch may conflict with current changes. Try resolving manually:[/yellow]")
-        console.print(f"  git apply -R --3way {after_patch}")
-        raise typer.Exit(code=1)
-    except Exception as e:
-        console.print(f"[red]Failed to rollback: {e}[/red]")
+        elif after_patch.exists():
+            console.print(
+                f"Only the after-patch at {after_patch} exists (it captured the task's changes).\n"
+                f"To manually revert those changes from the working tree:\n"
+                f"  1. [bold]git apply --stat {after_patch}[/bold] (inspect what the task changed)\n"
+                f"  2. [bold]git apply -R {after_patch}[/bold] (reverse-apply the task's changes)"
+            )
         raise typer.Exit(code=1)
+
+    console.print(f"[green]Successfully rolled back task {task_id}.[/green] {result.message}")

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

@@ -1,5 +1,4 @@
 import typer
-import json
 from rich.console import Console
 from pathlib import Path
 from devcouncil.storage.db import get_db
@@ -7,6 +6,11 @@ from devcouncil.storage.repositories import TaskRepository, RequirementRepositor
 from devcouncil.executors.mini_swe import MiniSWEExecutor
 from devcouncil.executors.openhands import OpenHandsExecutor
 from devcouncil.executors.coding_cli import CodingCliExecutor
+from devcouncil.executors.agent_registry import (
+    AGENT_ALIASES,
+    BUILTIN_CODING_EXECUTOR_NAMES,
+    load_cli_agent_specs,
+)
 from devcouncil.executors.native.agent import NativeAgent
 from devcouncil.llm.provider import create_provider, validate_model_provider
 from devcouncil.llm.router import ModelRouter
@@ -16,20 +20,18 @@ from devcouncil.storage.repositories import GapRepository, EvidenceRepository, S
 from devcouncil.verification.verifier import Verifier
 from devcouncil.app.state_machine import ProjectPhase
 from devcouncil.cli.commands.init import initialize_project
+from devcouncil.telemetry.traces import TraceLogger
 
 console = Console()
-CODING_EXECUTOR_ALIASES = {
-    "codex": "codex",
-    "codex-cli": "codex",
-    "gemini": "gemini",
-    "gemini-cli": "gemini",
-    "claude": "claude",
-    "claude-code": "claude",
-    "claude-cli": "claude",
-}
+CODING_EXECUTOR_ALIASES = {name: name for name in BUILTIN_CODING_EXECUTOR_NAMES} | AGENT_ALIASES
 
 CODING_EXECUTORS = set(CODING_EXECUTOR_ALIASES.keys())
 
+
+def _custom_cli_agents(project_root: Path) -> set[str]:
+    specs = load_cli_agent_specs(project_root)
+    return {name for name, spec in specs.items() if not spec.built_in}
+
 def _current_changed_files(project_root: Path = Path(".")) -> list[str]:
     from devcouncil.verification.verifier import Verifier
 
@@ -38,28 +40,16 @@ def _current_changed_files(project_root: Path = Path(".")) -> list[str]:
 def _capture_after_patch(task_id: str, project_root: Path = Path(".")):
     """Capture the diff after task execution for use by rollback."""
     try:
-        from devcouncil.verification.verifier import Verifier
+        from devcouncil.execution.checkpoints import CheckpointService
 
-        checkpoint_dir = project_root / ".devcouncil" / "checkpoints"
-        checkpoint_dir.mkdir(exist_ok=True)
-        diff = Verifier(project_root).get_diff()
-        if diff:
-            with open(checkpoint_dir / f"{task_id}-after.patch", "w", encoding="utf-8") as f:
-                f.write(diff)
+        CheckpointService(project_root).create_after(task_id)
     except Exception:
         pass  # Non-critical — don't block execution
 
 def _capture_before_snapshot(task_id: str, project_root: Path = Path(".")):
-    checkpoint_dir = project_root / ".devcouncil" / "checkpoints"
-    checkpoint_dir.mkdir(exist_ok=True)
-    snapshot = {
-        "task_id": task_id,
-        "changed_files": _current_changed_files(project_root),
-    }
-    (checkpoint_dir / f"{task_id}-before.json").write_text(
-        json.dumps(snapshot, indent=2),
-        encoding="utf-8",
-    )
+    from devcouncil.execution.checkpoints import CheckpointService
+
+    CheckpointService(project_root).create_before(task_id)
 
 def _record_project_phase(session, phase: ProjectPhase):
     StateRepository(session).record_phase(phase.value)
@@ -90,13 +80,33 @@ def _verify_after_execution(session, task, reqs, router=None, project_root: Path
     task.status = "blocked" if any(g.blocking for g in gaps) else "verified"
     return task.status == "verified"
 
+
+def _record_agent_verification(project_root: Path, task_id: str, executor: str, run_id: str | None, verified: bool) -> None:
+    TraceLogger(project_root).log_event(
+        "agent_run_verified",
+        {"agent": executor, "verified": verified},
+        run_id=run_id,
+        task_id=task_id,
+        summary=f"{executor} verification {'passed' if verified else 'blocked'} for {task_id}",
+    )
+
 def run(
     task_id: str = typer.Argument(..., help="ID of the task to run"),
     executor: str = typer.Option(
         "manual",
         "--executor",
         "-e",
-        help="Executor to use (manual, mini, openhands, native, codex, codex-cli, gemini, gemini-cli, claude, claude-code, claude-cli)",
+        help=(
+            "Executor to use (manual, mini, openhands, native-preview, "
+            "codex, gemini, claude, opencode, antigravity, warp, cursor, aider, "
+            "copilot, goose, amp, qwen, crush, or a configured agent)"
+        ),
+    ),
+    profile: str | None = typer.Option(None, "--profile", help="CLI-agent execution profile: default, yolo, prod, or a configured profile."),
+    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/."),
 ):
@@ -118,8 +128,8 @@ def run(
             return
 
         from devcouncil.gating.policy import GatePolicy
-        policy = GatePolicy()
-        gate_result = policy.check_task_ready(task, root)
+        gate_policy = GatePolicy()
+        gate_result = gate_policy.check_task_ready(task, root)
         if not gate_result.passed:
             console.print(f"[red]Task {task_id} is not ready for execution.[/red]")
             for gap in gate_result.gaps:
@@ -131,20 +141,23 @@ def run(
 
         # 1. Create Git checkpoint
         try:
-            from devcouncil.verification.verifier import Verifier
+            from devcouncil.execution.checkpoints import CheckpointService
 
-            checkpoint_dir = root / ".devcouncil" / "checkpoints"
-            checkpoint_dir.mkdir(exist_ok=True)
-            _capture_before_snapshot(task_id, root)
-            diff = Verifier(root).get_diff()
-            if diff:
-                with open(checkpoint_dir / f"{task_id}-before.patch", "w", encoding="utf-8") as f:
-                    f.write(diff)
-                console.print(f"Created git checkpoint at {checkpoint_dir}/{task_id}-before.patch")
+            result = CheckpointService(root).create_before(task_id)
+            if result.patch_path:
+                console.print(f"Created git checkpoint at {result.patch_path}")
+            elif result.git_ref_created:
+                console.print(f"Created git checkpoint ref {result.ref}")
         except Exception as e:
             console.print(f"[yellow]Warning: Failed to create git checkpoint: {e}[/yellow]")
 
         executor = executor.strip().lower().replace("_", "-")
+        if executor not in CODING_EXECUTORS and executor not in _custom_cli_agents(root):
+            ignored = [flag for flag, value in (("--profile", profile), ("--stream", stream)) if value]
+            if ignored:
+                console.print(
+                    f"[yellow]{' and '.join(ignored)} only apply to coding CLI executors and are ignored for '{executor}'.[/yellow]"
+                )
         if executor == "manual":
             _record_project_phase(session, ProjectPhase.TASK_EXECUTING)
             task.status = "running"
@@ -152,22 +165,30 @@ def run(
             console.print(f"\n[green]Task {task_id} is now marked as RUNNING.[/green]")
             console.print("Use 'dev prompt TASK-ID' to get the prompt for this task.")
             console.print("When finished, use 'dev verify TASK-ID' to check the results.")
-        elif executor in CODING_EXECUTORS:
+        elif executor in CODING_EXECUTORS or executor in _custom_cli_agents(root):
             _record_project_phase(session, ProjectPhase.TASK_EXECUTING)
             req_repo = RequirementRepository(session)
             reqs = req_repo.get_all()
-            cli_client = CODING_EXECUTOR_ALIASES[executor]
-            cli_executor = CodingCliExecutor(root, cli_client)
+            cli_client = CODING_EXECUTOR_ALIASES.get(executor, executor)
+            cli_executor = CodingCliExecutor(root, cli_client, profile=profile, stream_output=stream or None)
             exec_result = cli_executor.run_task(task, reqs)
             _capture_after_patch(task_id, root)
             if exec_result.success:
                 _record_project_phase(session, ProjectPhase.TASK_VERIFYING)
                 verified = _verify_after_execution(session, task, reqs, project_root=root)
+                _record_agent_verification(root, task.id, cli_client, getattr(cli_executor, "last_run_id", None), verified)
                 _record_project_phase(
                     session,
                     ProjectPhase.TASK_VERIFIED if verified else ProjectPhase.TASK_BLOCKED,
                 )
                 task_repo.save(task)
+                run_id = getattr(cli_executor, "last_run_id", None)
+                if run_id:
+                    run_dir = root / ".devcouncil" / "runs" / run_id
+                    console.print(f"Run artifacts: [dim]{run_dir}[/dim]")
+                    transcript_path = getattr(cli_executor, "last_transcript_path", None)
+                    if transcript_path:
+                        console.print(f"Transcript: [dim]{transcript_path}[/dim]")
                 if verified:
                     console.print(f"\n[green]{executor.upper()} finished and task {task_id} verified.[/green]")
                 else:
@@ -216,7 +237,7 @@ def run(
                     console.print(f"\n[yellow]OpenHands finished, but task {task_id} is blocked by verification gaps.[/yellow]")
             else:
                 console.print("\n[red]OpenHands failed to start or execute.[/red]")
-        elif executor == "native":
+        elif executor in {"native", "native-preview"}:
             # Load config for model routing and permissions
             try:
                 config = load_config(root)
@@ -226,9 +247,9 @@ def run(
                 console.print(f"[red]{e}[/red]")
                 return
             
-            provider = create_provider(config.models.provider, api_key)
+            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)
+            router = ModelRouter(provider, role_config, project_root=root)
             
             # Setup Permission System
             from devcouncil.execution.permissions import PermissionPolicy, PermissionManager
@@ -236,19 +257,18 @@ def run(
             
             # Populate policy from config commands
             allowed_cmds = config.commands.test + config.commands.lint + config.commands.typecheck
-            policy = PermissionPolicy(
+            permission_policy = PermissionPolicy(
                 allowed_shell_commands=allowed_cmds,
             )
-            perm_manager = PermissionManager(policy, root)
+            perm_manager = PermissionManager(permission_policy, root)
             task_runner = TaskRunner(root, perm_manager)
             
             req_repo = RequirementRepository(session)
             reqs = req_repo.get_all()
             
-            import asyncio
             _record_project_phase(session, ProjectPhase.TASK_EXECUTING)
             agent = NativeAgent(router, task_runner)
-            exec_result = asyncio.run(agent.run_task(task, reqs))
+            exec_result = agent.run_task(task, reqs)
             _capture_after_patch(task_id, root)
             
             if exec_result.success:

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

@@ -0,0 +1,223 @@
+"""`dev runs` — list and inspect per-run agent manifests.
+
+Coding-CLI executors write a manifest at
+``.devcouncil/runs/<run-id>/agent-run.json`` (prompt file, executor, profile,
+resolved command, exit status, run metadata). These commands let a developer or a
+supervisor list and inspect those runs without reading raw JSON, and flag a run
+whose status is still ``running`` but whose manifest has gone stale (the executor
+process likely crashed) as ``orphaned``.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from devcouncil.utils.redaction import redact_text
+
+app = typer.Typer(help="List and inspect coding-agent run manifests.")
+console = Console()
+
+# 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
+# sane default; can be overridden per-call with --orphan-after.
+_DEFAULT_ORPHAN_AFTER_SECONDS = 600
+
+# Transcript/log files (in priority order) whose tail `dev runs show` surfaces.
+_TRANSCRIPT_CANDIDATES = ("transcript.txt", "transcript.log", "output.log", "run.log")
+_TRANSCRIPT_TAIL_LINES = 40
+
+
+def _runs_dir(project_root: Path) -> Path:
+    return project_root / ".devcouncil" / "runs"
+
+
+def _orphan_after_seconds(project_root: Path) -> int:
+    """Threshold (seconds) after which a stale ``running`` manifest is orphaned.
+
+    Config-driven when available (execution.lease_ttl_seconds is a reasonable
+    proxy for "how long a live run can plausibly stay quiet"); falls back to a
+    sane default so the command works before `dev init`."""
+    try:
+        from devcouncil.app.config import load_config
+
+        ttl = int(load_config(project_root).execution.lease_ttl_seconds)
+        if ttl > 0:
+            return ttl
+    except Exception:
+        pass
+    return _DEFAULT_ORPHAN_AFTER_SECONDS
+
+
+def _load_manifest(manifest_path: Path) -> dict | None:
+    try:
+        data = json.loads(manifest_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def _is_orphaned(manifest: dict, manifest_path: Path, *, orphan_after: int, now: float) -> bool:
+    """A run is orphaned when it is still ``running`` but its manifest file has
+    not been updated within the threshold — i.e. no heartbeat, executor gone."""
+    if manifest.get("status") != "running":
+        return False
+    try:
+        mtime = manifest_path.stat().st_mtime
+    except OSError:
+        return False
+    return (now - mtime) > max(0, orphan_after)
+
+
+def _run_summary(manifest: dict, manifest_path: Path, *, orphan_after: int, now: float) -> dict:
+    return {
+        "run_id": manifest.get("run_id") or manifest_path.parent.name,
+        "task_id": manifest.get("task_id"),
+        "agent": manifest.get("agent"),
+        "profile": manifest.get("profile"),
+        "status": manifest.get("status"),
+        "started_at": manifest.get("started_at") or manifest.get("timestamp"),
+        "finished_at": manifest.get("finished_at"),
+        "returncode": manifest.get("returncode"),
+        "orphaned": _is_orphaned(manifest, manifest_path, orphan_after=orphan_after, now=now),
+    }
+
+
+def _collect_runs(project_root: Path, *, orphan_after: int) -> list[dict]:
+    runs_dir = _runs_dir(project_root)
+    if not runs_dir.is_dir():
+        return []
+    now = time.time()
+    summaries: list[tuple[float, dict]] = []
+    for manifest_path in runs_dir.glob("*/agent-run.json"):
+        manifest = _load_manifest(manifest_path)
+        if manifest is None:
+            continue
+        try:
+            sort_key = manifest_path.stat().st_mtime
+        except OSError:
+            sort_key = 0.0
+        summaries.append((sort_key, _run_summary(manifest, manifest_path, orphan_after=orphan_after, now=now)))
+    # Newest first.
+    summaries.sort(key=lambda item: item[0], reverse=True)
+    return [summary for _, summary in summaries]
+
+
+def _find_transcript(run_dir: Path, manifest: dict) -> Path | None:
+    recorded = manifest.get("transcript")
+    if isinstance(recorded, str) and recorded:
+        candidate = Path(recorded)
+        if not candidate.is_absolute():
+            candidate = run_dir / recorded
+        if candidate.is_file():
+            return candidate
+    for name in _TRANSCRIPT_CANDIDATES:
+        candidate = run_dir / name
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def _transcript_tail(path: Path, *, lines: int = _TRANSCRIPT_TAIL_LINES) -> str:
+    """Return the redacted tail of a transcript file (best-effort)."""
+    try:
+        content = path.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return ""
+    tail = content.splitlines()[-lines:]
+    return redact_text("\n".join(tail))
+
+
+@app.command("list")
+def list_runs(
+    json_output: bool = typer.Option(False, "--json", help="Emit machine-readable JSON."),
+    limit: int = typer.Option(20, "--limit", help="Maximum number of runs to show."),
+    status: str | None = typer.Option(None, "--status", help="Filter by run status (e.g. running, finished, failed, timeout)."),
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root containing .devcouncil/."),
+) -> 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)
+
+
+@app.command("show")
+def show_run(
+    run_id: str = typer.Argument(..., help="The run id to inspect."),
+    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:
+    """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:
+        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": 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]")

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

@@ -0,0 +1,32 @@
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from devcouncil.repo.ci_scaffold import WORKFLOW_RELPATH, detect_stacks, scaffold_ci
+
+console = Console()
+
+
+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."),
+):
+    """Write a starter GitHub Actions workflow derived from the configured commands."""
+    root = project_root.expanduser().resolve()
+    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
+
+    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]")

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

@@ -0,0 +1,47 @@
+import json
+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
+
+app = typer.Typer(help="Semantic snapshots and diffs.")
+console = Console()
+
+
+@app.command("snapshot")
+def snapshot(
+    task_id: str = typer.Argument(...),
+    stage: str = typer.Option("before", "--stage", help="before or after"),
+    project_root: Path = typer.Option(Path("."), "--project-root"),
+    json_format: bool = typer.Option(False, "--json"),
+):
+    root = project_root.expanduser().resolve()
+    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}")
+
+
+@app.command("diff")
+def semantic_diff(
+    task_id: str = typer.Argument(...),
+    project_root: Path = typer.Option(Path("."), "--project-root"),
+    json_format: bool = typer.Option(False, "--json"),
+):
+    root = project_root.expanduser().resolve()
+    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', '')}")