devcouncil 0.3.1 → 0.4.1

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

@@ -0,0 +1,120 @@
+"""`dev checkout`, `dev release`, and `dev lease` — task lease CLI service layer."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+import typer
+
+from devcouncil.execution.lease_ops import (
+    checkout_task_payload,
+    list_leases_payload,
+    release_task_payload,
+    renew_lease_payload,
+)
+from devcouncil.telemetry.logging_setup import set_log_dir
+from devcouncil.telemetry.stages import log_stage, log_step
+from devcouncil.utils.json_persist import dump_json
+
+lease_app = typer.Typer(help="List and renew task leases.")
+logger = logging.getLogger(__name__)
+
+
+def checkout(
+    task_id: str = typer.Argument(..., help="Task ID to acquire."),
+    client_id: str = typer.Option(..., "--client-id", help="Stable client id for the lease owner."),
+    agent: str | None = typer.Option(None, "--agent", help="Optional agent profile name."),
+    force: bool = typer.Option(False, "--force", help="Reclaim a stale lease."),
+    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/."),
+) -> None:
+    """Acquire a task lease and return scope for gated write tools."""
+    root = project_root.expanduser().resolve()
+    set_log_dir(root)
+    logger.info("dev checkout: task=%s client=%s", task_id, client_id)
+
+    with log_stage("checkout", project_root=root, task_id=task_id):
+        payload = checkout_task_payload(root, task_id=task_id, client_id=client_id, agent=agent, force=force)
+        if json_format:
+            typer.echo(dump_json(payload, indent=2))
+            log_step("checkout/complete", project_root=root, task_id=task_id, trace=True)
+            if not payload.get("ok"):
+                raise typer.Exit(code=1)
+            return
+        if not payload.get("ok"):
+            typer.echo(payload.get("error", "checkout failed"))
+            raise typer.Exit(code=1)
+        typer.echo(f"Checked out {task_id} (expires {payload.get('expires_at')})")
+        log_step("checkout/complete", project_root=root, task_id=task_id, trace=True)
+
+
+def release(
+    task_id: str = typer.Argument(..., help="Task ID to release."),
+    lease_token: str = typer.Option(..., "--lease-token", help="Lease token from checkout."),
+    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/."),
+) -> None:
+    """Release a held task lease."""
+    root = project_root.expanduser().resolve()
+    set_log_dir(root)
+    logger.info("dev release: task=%s", task_id)
+
+    with log_stage("release", project_root=root, task_id=task_id):
+        payload = release_task_payload(root, task_id=task_id, lease_token=lease_token)
+        if json_format:
+            typer.echo(dump_json(payload, indent=2))
+            log_step("release/complete", project_root=root, task_id=task_id, trace=True)
+            if not payload.get("ok"):
+                raise typer.Exit(code=1)
+            return
+        if not payload.get("ok"):
+            typer.echo(payload.get("error", "release failed"))
+            raise typer.Exit(code=1)
+        typer.echo(f"Released {task_id}")
+        log_step("release/complete", project_root=root, task_id=task_id, trace=True)
+
+
+@lease_app.command("list")
+def lease_list(
+    active_only: bool = typer.Option(True, "--active-only/--all", help="Only active leases."),
+    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/."),
+) -> None:
+    """List task leases for fleet supervision."""
+    root = project_root.expanduser().resolve()
+    set_log_dir(root)
+    payload = list_leases_payload(root, active_only=active_only)
+    if json_format:
+        typer.echo(dump_json(payload, indent=2))
+        if not payload.get("ok"):
+            raise typer.Exit(code=1)
+        return
+    if not payload.get("ok"):
+        typer.echo(payload.get("error", "lease list failed"))
+        raise typer.Exit(code=1)
+    for item in payload.get("leases") or []:
+        typer.echo(f"{item['task_id']}  {item['owner']}  expires={item['expires_at']}")
+
+
+@lease_app.command("renew")
+def lease_renew(
+    task_id: str = typer.Argument(..., help="Task ID."),
+    lease_token: str = typer.Option(..., "--lease-token", help="Lease token to renew."),
+    ttl_seconds: int | None = typer.Option(None, "--ttl-seconds", help="New TTL in seconds."),
+    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/."),
+) -> None:
+    """Extend a held task lease's TTL."""
+    root = project_root.expanduser().resolve()
+    set_log_dir(root)
+    payload = renew_lease_payload(root, task_id=task_id, lease_token=lease_token, ttl_seconds=ttl_seconds)
+    if json_format:
+        typer.echo(dump_json(payload, indent=2))
+        if not payload.get("ok"):
+            raise typer.Exit(code=1)
+        return
+    if not payload.get("ok"):
+        typer.echo(payload.get("error", "renew failed"))
+        raise typer.Exit(code=1)
+    typer.echo(f"Renewed {task_id} until {payload.get('expires_at')}")

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

@@ -5,6 +5,13 @@ breaks. This command surfaces the always-on shared log
 (``.devcouncil/logs/devcouncil.log``) and the per-run logs
 (``.devcouncil/runs/<run_id>/run.log``) without the user needing to remember
 paths or hand-roll ``tail``/``grep``.
+
+DELIBERATELY UNINSTRUMENTED: this command's subject *is* the log. Emitting log
+records (``logger.info`` / ``log_stage`` / ``log_step``) from here mutates what
+the user asked to inspect — ``tail`` displaces the trailing lines it was asked
+to show with its own records, and ``path`` creates the very file it is supposed
+to report as "not created yet". An introspection command must not modify what
+it introspects, so no stage instrumentation belongs in this file.
 """
 
 import time
@@ -14,14 +21,16 @@ from typing import Optional
 import typer
 from rich.console import Console
 
-from devcouncil.telemetry.logging_setup import LOG_RELATIVE_PATH
+from devcouncil.telemetry.logging_setup import _resolve_log_path
 
 app = typer.Typer(help="View DevCouncil runtime logs (shared and per-run).")
 console = Console()
 
 
 def _shared_log(root: Path) -> Path:
-    return root / LOG_RELATIVE_PATH
+    # Honors DEVCOUNCIL_LOG_DIR so `dev logs` inspects the same file the
+    # handlers actually write to.
+    return _resolve_log_path(root)
 
 
 def _runs_dir(root: Path) -> Path:
@@ -32,7 +41,6 @@ def _print_tail(path: Path, limit: int, grep: Optional[str]) -> None:
     if not path.exists():
         console.print(f"[yellow]No log at {path}. Run a command first (or pass --project-root).[/yellow]")
         raise typer.Exit(code=0)
-    # Read only the tail rather than the whole (potentially large, rotated) file.
     lines = path.read_text(encoding="utf-8", errors="replace").splitlines()
     if grep:
         lines = [line for line in lines if grep.lower() in line.lower()]
@@ -56,11 +64,10 @@ def tail(
     if not follow:
         return
 
-    # Follow mode: poll for appended bytes (the file is append-only between rotations).
     console.print(f"[dim]— following {path} (Ctrl-C to stop) —[/dim]")
     try:
         with open(path, "r", encoding="utf-8", errors="replace") as handle:
-            handle.seek(0, 2)  # jump to EOF; we already printed the tail
+            handle.seek(0, 2)
             while True:
                 line = handle.readline()
                 if line:

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

@@ -1,20 +1,55 @@
-import json
+from devcouncil.utils.json_persist import dump_json
+import logging
 from pathlib import Path
 
 import typer
 
 from devcouncil.indexing.lsp import LspInspector
+from devcouncil.telemetry.stages import log_stage, log_step
 
-app = typer.Typer(help="Inspect optional LSP integration readiness.")
+app = typer.Typer(
+    help=(
+        "Inspect optional LSP integration readiness. "
+        "Default is detection-only (PATH check). When indexing.lsp_refs is enabled, "
+        "reports mode: client for the live references/definition client."
+    ),
+)
+logger = logging.getLogger(__name__)
 
 
 @app.command("inspect")
 def inspect(
     project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root."),
+    json_format: bool = typer.Option(False, "--json", help="Emit {mode, servers_detected, note} JSON."),
 ):
-    """Print detected language servers and initialize payloads."""
+    """Print detected language servers; mode is detection-only or client."""
     root = project_root.expanduser().resolve()
+    # Existence check FIRST: set_log_dir/log_stage create .devcouncil/ under the
+    # root, which would materialize a missing/typo'd path and turn the "does not
+    # exist" report into a false success.
     if not root.exists():
-        typer.echo(json.dumps({"languages": [], "servers": [], "initialize_requests": {}, "error": f"{root} does not exist"}, indent=2))
+        typer.echo(dump_json({"languages": [], "servers": [], "initialize_requests": {}, "error": f"{root} does not exist"}, indent=2))
         raise typer.Exit(code=1)
-    typer.echo(LspInspector(root).summary_json())
+    from devcouncil.telemetry.logging_setup import set_log_dir
+    set_log_dir(root)
+    logger.info("dev lsp inspect")
+    with log_stage("lsp", project_root=root):
+        log_step("lsp/1: inspecting language servers", project_root=root, trace=True)
+        client_enabled = False
+        try:
+            from devcouncil.indexing.lsp_client import lsp_refs_enabled
+
+            client_enabled = lsp_refs_enabled(root)
+        except Exception:
+            client_enabled = False
+        summary = LspInspector(root).summary(client_enabled=client_enabled)
+        if json_format:
+            compact = {
+                "mode": summary.get("mode", "detection-only"),
+                "servers_detected": summary.get("servers_detected", summary.get("detected_servers", [])),
+                "note": summary.get("note", LspInspector._DETECTION_ONLY_NOTE),
+            }
+            typer.echo(dump_json(compact, indent=2))
+        else:
+            typer.echo(dump_json(summary, indent=2))
+        log_step("lsp/complete", project_root=root, trace=True)

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

@@ -1,88 +1,63 @@
-import json
+import logging
 from pathlib import Path
 
 import typer
 from rich.console import Console
 
-from devcouncil.cli.commands.init import initialize_project
+from devcouncil.indexing.map_artifacts import (
+    _important_surfaces as _important_surfaces,
+    _wiki_index_rel as _wiki_index_rel,
+    generate_map_artifacts as generate_map_artifacts,
+    write_agent_guides,
+)
 from devcouncil.indexing.repo_mapper import RepoMap, RepoMapper
 from devcouncil.integrations.code_review_graph import CodeReviewGraphAdapter
 from devcouncil.storage.db import get_db
+from devcouncil.telemetry.stages import log_stage, log_step
+from devcouncil.utils.json_persist import dump_json
+
+# Back-compat aliases for tests / external importers.
+_write_agent_guides = write_agent_guides
 
 console = Console()
 status_console = Console(stderr=True)
-
-AGENT_GUIDE_MARKER = "<!-- Managed by dev map: keep this file in sync with .devcouncil/repo_map.json. -->"
-
-
-def _important_surfaces(repo_map: RepoMap) -> list[str]:
-    """Derive the 'important surfaces' list from the computed map, so the guide points
-    at THIS repo's real subsystems instead of hardcoded DevCouncil paths."""
-    lines: list[str] = []
-    for index, subsystem in enumerate(repo_map.subsystems[:6], start=1):
-        lines.append(f"{index}. `{subsystem.area}/` — {subsystem.summary}")
-    if not lines:
-        for index, path in enumerate(repo_map.important_files[:6], start=1):
-            lines.append(f"{index}. `{path}`")
-    return lines or ["1. See `.devcouncil/repo_map.json` for the file index."]
-
-
-def _agent_guide_text(repo_map_path: Path, repo_root: Path, repo_map: RepoMap) -> str:
-    return "\n".join(
-        [
-            AGENT_GUIDE_MARKER,
-            "",
-            "# Agent Workspace Guide",
-            "",
-            "Use `.devcouncil/repo_map.json` as the primary file index for this workspace.",
-            f"Repo map: `{repo_map_path.relative_to(repo_root).as_posix() if repo_map_path.is_relative_to(repo_root) else repo_map_path}`",
-            "",
-            "Workflow for agents:",
-            "1. Open `.devcouncil/repo_map.json` before guessing at file locations.",
-            "2. Use the `files` list to resolve module ownership and nearby siblings.",
-            "3. Use `subsystems` for subsystem-level navigation.",
-            "4. In `subsystems`, use `entry_points` + `critical_files` for entry points and starting context.",
-            "5. Use `role_files` in `subsystems` for subsystem role buckets (entry, runtime, policy, adapters, etc.).",
-            "6. Use `neighbors` and `handoff_paths` in `subsystems` to follow cross-subsystem flow.",
-            "7. Run `dev map` again after large refactors to refresh the map.",
-            "",
-            "Important surfaces:",
-            *_important_surfaces(repo_map),
-            "",
-            "If the map and source disagree, trust the source and regenerate the map.",
-        ]
-    )
+logger = logging.getLogger(__name__)
 
 
-def _write_agent_guides(repo_root: Path, repo_map_path: Path, repo_map: RepoMap) -> None:
-    for filename in ("AGENTS.md", "CLAUDE.md"):
-        path = repo_root / filename
-        if path.exists():
-            existing = path.read_text(encoding="utf-8")
-            if AGENT_GUIDE_MARKER not in existing:
-                continue
-        path.write_text(_agent_guide_text(repo_map_path, repo_root, repo_map) + "\n", encoding="utf-8")
+def _liveness_summary(repo_map: RepoMap) -> str | None:
+    unreliable = bool(getattr(repo_map, "liveness_unreachable_unreliable", False))
+    if not (
+        repo_map.entry_roots
+        or repo_map.unwired_candidates
+        or repo_map.unreachable_files
+        or repo_map.dead_symbol_candidates
+        or unreliable
+    ):
+        return None
+    if not repo_map.entry_roots or unreliable:
+        import sys
 
-
-def generate_map_artifacts(root: Path, output: Path, goal: str = "", *, scan_dependencies: bool = False) -> RepoMap:
-    """Build the repo map and write repo_map.json + agent guides (no LLM, no re-init).
-
-    Assumes ``.devcouncil/`` already exists. Shared by the ``dev map`` command and
-    by project initialization so a freshly set-up repo is immediately navigable.
-    ``scan_dependencies`` is opt-in (off for init and default mapping) because it can
-    shell out to dependency auditors.
-    """
-    repo_map = RepoMapper(root).map_repo(goal, scan_dependencies=scan_dependencies)
-    graph_context = CodeReviewGraphAdapter(root).get_context()
-    output = output if output.is_absolute() else root / output
-    output.parent.mkdir(parents=True, exist_ok=True)
-    output.write_text(repo_map.model_dump_json(indent=2), encoding="utf-8")
-    _write_agent_guides(root, output, repo_map)
-    if graph_context.available:
-        graph_output = output.with_name("code_review_graph_context.json")
-        graph_output.write_text(graph_context.model_dump_json(indent=2), encoding="utf-8")
-        status_console.print(f"[green]Wrote code-review-graph context to {graph_output}[/green]")
-    return repo_map
+        print(
+            "warning: unreachable_files low-confidence "
+            "(liveness_unreachable_unreliable); prefer unwired_candidates / "
+            "dead_symbol_candidates and `dev graph dead --confidence extracted`",
+            file=sys.stderr,
+        )
+    samples = repo_map.unwired_candidates[:3] + repo_map.dead_symbol_candidates[:2]
+    sample_txt = (", " + ", ".join(samples)) if samples else ""
+    unreachable_txt = (
+        "omitted (unreliable)"
+        if unreliable
+        else str(len(repo_map.unreachable_files))
+    )
+    return (
+        f"liveness: {len(repo_map.entry_roots)} entry roots, "
+        f"{len(repo_map.unwired_candidates)} unwired, "
+        f"{unreachable_txt} unreachable, "
+        f"{len(repo_map.dead_symbol_candidates)} dead symbols"
+        f"{sample_txt}"
+        " (prefer unwired + extracted dead; map clears on any non-test importer)"
+    )
 
 
 def map_repo(
@@ -99,14 +74,282 @@ def map_repo(
         "--scan-deps",
         help="Run available dependency auditors (pip-audit/npm audit/osv-scanner) and record dependency_risks in the map. Off by default.",
     ),
+    liveness: bool = typer.Option(
+        True,
+        "--liveness/--no-liveness",
+        help="Compute entry_roots / unwired / unreachable / dead_symbol candidate lists (on by default).",
+    ),
+    lsp_refs: bool = typer.Option(
+        False,
+        "--lsp-refs/--no-lsp-refs",
+        help=(
+            "Confirm dead-symbol candidates via live LSP references when a language "
+            "server is on PATH. Also set indexing.lsp_refs in config.yaml. Off by default."
+        ),
+    ),
+    refresh_wiki: bool = typer.Option(
+        True,
+        "--wiki/--no-wiki",
+        help="After mapping, refresh stale codebase-wiki page skeletons when a wiki exists (no LLM calls).",
+    ),
+    watch: bool = typer.Option(
+        False,
+        "--watch",
+        help="After the initial map, watch the tree and incrementally refresh on code edits (Ctrl-C to stop).",
+    ),
+    if_stale: bool = typer.Option(
+        False,
+        "--if-stale",
+        help="Fingerprint-check first and exit 0 without rebuilding when the on-disk map is still fresh.",
+    ),
+    pdg: bool = typer.Option(
+        False,
+        "--pdg/--no-pdg",
+        help="Build opt-in PDG/CFG/taint layer after map (Python-only, intra-procedural).",
+    ),
 ):
     """Build the deterministic repository map without calling an LLM."""
     root = project_root.expanduser().resolve()
+    # Reject missing roots before set_log_dir / initialize_project mkdir(parents=True)
+    # silently creates an empty project and maps zero files with exit 0.
+    if not root.is_dir():
+        status_console.print(f"[red]Project root does not exist: {root}[/red]")
+        raise typer.Exit(code=1)
+    # `dev map /some/repo` parses the path as the GOAL and maps the CWD repo with
+    # exit 0 — surface the likely intent instead of silently mapping the wrong repo.
+    if goal and project_root == Path("."):
+        goal_path = Path(goal).expanduser()
+        if goal_path.is_absolute() and goal_path.is_dir() and goal_path.resolve() != root:
+            status_console.print(
+                f"[yellow]Goal argument is a directory ({goal}). Did you mean "
+                f"`dev map --project-root {goal}`? Mapping {root} with it as goal text.[/yellow]"
+            )
+    from devcouncil.telemetry.logging_setup import set_log_dir
+    set_log_dir(root)
+    # CLI flag OR config; flag alone is enough without rewriting config.
+    use_lsp = lsp_refs
+    if not use_lsp:
+        try:
+            from devcouncil.app.config import load_config
+
+            use_lsp = bool(load_config(root).indexing.lsp_refs)
+        except Exception:
+            use_lsp = False
+    logger.info(
+        "dev map: goal=%r scan_deps=%s liveness=%s lsp_refs=%s if_stale=%s",
+        goal, scan_deps, liveness, use_lsp, if_stale,
+    )
+    from devcouncil.cli.commands.init import initialize_project
+
     initialize_project(root, quiet=True, with_map=False)
     if not get_db(root):
         raise typer.Exit(code=1)
 
     output = output if output.is_absolute() else root / output
-    repo_map = generate_map_artifacts(root, output, goal, scan_dependencies=scan_deps)
-    typer.echo(json.dumps(repo_map.model_dump(), indent=2))
-    status_console.print(f"[green]Wrote repository map to {output}[/green]")
+    if if_stale and output.is_file():
+        try:
+            from devcouncil.utils.json_persist import read_json
+
+            data = read_json(output) or {}
+            if isinstance(data, dict) and not RepoMapper(root).map_is_stale(data):
+                status_console.print(f"[dim]Map is fresh; skipping rebuild ({output})[/dim]")
+                raise typer.Exit(code=0)
+        except typer.Exit:
+            raise
+        except Exception:
+            logger.debug("if-stale freshness check failed; rebuilding", exc_info=True)
+
+    with log_stage("map", project_root=root, scan_deps=scan_deps):
+        log_step("map/1: generating repository map", project_root=root, trace=True)
+        from devcouncil.codeintel.build_control import GraphBuildBusy
+
+        try:
+            from devcouncil.indexing.map_artifacts import refresh_map_artifacts
+
+            refresh = refresh_map_artifacts(
+                root,
+                output,
+                goal,
+                scan_dependencies=scan_deps,
+                liveness=liveness,
+                lsp_refs=use_lsp,
+            )
+            repo_map = refresh.repo_map
+        except GraphBuildBusy as exc:
+            status_console.print(f"[red]{exc}[/red]")
+            raise typer.Exit(code=1) from exc
+        if refresh.degraded:
+            status_console.print(
+                f"[red]Map wrote lean/degraded artifacts: {refresh.reason or refresh.mode}[/red]"
+            )
+            raise typer.Exit(code=1)
+        if refresh.compatibility_export_degraded:
+            status_console.print(
+                f"[yellow]Compatibility export degraded (canonical SQLite ok): "
+                f"{refresh.reason}[/yellow]"
+            )
+        try:
+            typer.echo(dump_json(repo_map.model_dump(), indent=2))
+        except BrokenPipeError:
+            # Consumer closed stdout early (`dev map | head`). The artifacts are
+            # already written — a closed pipe must not turn the stage red.
+            import os
+            import sys
+
+            logger.debug("stdout pipe closed while streaming repo map JSON")
+            try:
+                os.dup2(os.open(os.devnull, os.O_WRONLY), sys.stdout.fileno())
+            except OSError:
+                pass
+        status_console.print(f"[green]Wrote repository map to {output}[/green]")
+        graph_out = root / ".devcouncil" / "graph" / "code_graph.json"
+        if not graph_out.is_file():
+            # The export write failed or an external cleanup removed the JSON
+            # while SQLite (canonical) still holds the graph — re-export instead
+            # of exiting green without the documented artifact.
+            from devcouncil.indexing.graph.build import export_code_graph_json
+
+            if export_code_graph_json(root) is not None:
+                status_console.print(
+                    f"[yellow]Code graph JSON was missing; re-exported from store to {graph_out}[/yellow]"
+                )
+            else:
+                status_console.print(
+                    f"[yellow]Code graph JSON missing and store re-export failed ({graph_out}); "
+                    "run `dev graph doctor`[/yellow]"
+                )
+        if graph_out.is_file():
+            status_console.print(f"[green]Wrote code graph to {graph_out}[/green]")
+            if pdg:
+                try:
+                    from devcouncil.indexing.graph.build import (
+                        build_pdg_for_paths,
+                        load_code_graph,
+                        merge_pdg_into_graph,
+                        write_code_graph,
+                    )
+
+                    graph = load_code_graph(root)
+                    if graph is not None:
+                        layer = build_pdg_for_paths(root, graph)
+                        shards = merge_pdg_into_graph(graph, layer)
+                        merged: dict = {}
+                        try:
+                            from devcouncil.codeintel import get_codeintel_service
+
+                            merged = dict(get_codeintel_service(root).store.analysis_shards())
+                        except Exception:
+                            pass
+                        for path, payload in shards.items():
+                            merged.setdefault(path, {}).update(payload)
+                        write_code_graph(root, graph, analysis_shards=merged)
+                        stats = (graph.meta.get("pdg") or {}).get("stats") or {}
+                        status_console.print(
+                            f"[green]Wrote PDG layer[/green] "
+                            f"({stats.get('function_count', 0)} functions, "
+                            f"{stats.get('taint_count', 0)} taint findings)"
+                        )
+                except Exception as exc:
+                    logger.warning("PDG build after map failed: %s", exc)
+            try:
+                from devcouncil.app.config import load_config
+
+                if bool(load_config(root).indexing.write_graph_html):
+                    from devcouncil.indexing.viz import write_graph_html
+
+                    html_out = write_graph_html(root, open_browser=False)
+                    status_console.print(f"[green]Wrote graph HTML to {html_out}[/green]")
+            except Exception as exc:
+                logger.warning("Failed to write graph.html after map: %s", exc)
+        summary = _liveness_summary(repo_map)
+        if summary:
+            status_console.print(f"[cyan]{summary}[/cyan]")
+        if refresh_wiki:
+            _refresh_wiki_skeletons(root, repo_map)
+        log_step("map/complete", project_root=root, trace=True)
+        if watch:
+            _watch_map(root, liveness=liveness)
+
+
+def graph_context_cmd(
+    files: list[str] = typer.Option([], "--file", help="Changed files to scope blast-radius (repeatable)."),
+    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:
+    """Return code-review-graph context for the given files."""
+    root = project_root.expanduser().resolve()
+    context = CodeReviewGraphAdapter(root).get_context(files)
+    if json_output:
+        typer.echo(context.model_dump_json(indent=2))
+        return
+    if not context.available:
+        console.print("[dim]Code-review graph integration is not available.[/dim]")
+        return
+    if context.impacted_files:
+        console.print("[cyan]Impacted files:[/cyan] " + ", ".join(context.impacted_files[:20]))
+    if context.related_tests:
+        console.print("[cyan]Related tests:[/cyan] " + ", ".join(context.related_tests[:20]))
+
+
+def _refresh_wiki_skeletons(root: Path, repo_map: RepoMap) -> None:
+    """Keep the codebase wiki in step with the map — seamlessly, but deterministically.
+
+    Only runs when a wiki was already generated (`dev wiki update` opted the repo in),
+    and only rewrites pages whose repo-map slice changed. No model calls here: `dev map`
+    must stay fast and offline; run `dev wiki update` for LLM-enriched prose on the
+    refreshed pages.
+    """
+    try:
+        from devcouncil.knowledge.wiki import (
+            _project_name,
+            generate_wiki,
+            wiki_dir_for,
+            wiki_stale_pages,
+        )
+
+        wiki_dir = wiki_dir_for(root)
+        if not (wiki_dir / "index.md").is_file():
+            return
+        stale = wiki_stale_pages(root, repo_map, wiki_dir)
+        if not stale:
+            return
+        result = generate_wiki(root, repo_map, wiki_dir, project_name=_project_name(root))
+        status_console.print(
+            f"[green]Refreshed {len(result.changed)} stale wiki page(s)[/green] "
+            "(skeleton only — run `dev wiki update` for LLM-enriched prose)."
+        )
+    except Exception as exc:
+        # The wiki is a convenience layer; never let it fail `dev map`.
+        logger.warning("Wiki refresh after map failed: %s", exc)
+
+
+def _watch_map(root: Path, *, liveness: bool = True) -> None:
+    """Run the shared code-intelligence coordinator for map compatibility."""
+    import time
+
+    from devcouncil.codeintel.sync import get_sync_coordinator
+    from devcouncil.indexing.graph.build import refresh_map_for_paths
+
+    coordinator = get_sync_coordinator(
+        root,
+        debounce_seconds=0.8,
+        sync_callback=lambda paths: refresh_map_for_paths(root, paths, liveness=liveness),
+    )
+    state = coordinator.start()
+    status_console.print(
+        f"[cyan]Watching {root} with {state.backend or 'reconciliation'} "
+        f"(state={state.state}, debounce 0.8s). Ctrl-C to stop.[/cyan]"
+    )
+    try:
+        while True:
+            time.sleep(0.8)
+            before = coordinator.status().pending
+            if before and not coordinator.sync_now():
+                failure = coordinator.status().last_error or coordinator.status().degraded_reason
+                status_console.print(f"[yellow]Watch refresh failed (ignored): {failure}[/yellow]")
+            elif before:
+                status_console.print(f"[green]Refreshed map for {len(before)} path(s)[/green]")
+    except KeyboardInterrupt:
+        status_console.print("Stopped watching.")
+    finally:
+        coordinator.stop(timeout=2)