devcouncil 0.3.1 → 0.4.0

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

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-import json
+from devcouncil.utils.json_persist import dump_json
 import asyncio
 import logging
 import time
@@ -30,6 +30,7 @@ from devcouncil.app.config import get_api_key, load_config
 from devcouncil.llm.provider import create_provider, validate_model_provider
 from devcouncil.llm.router import ModelRouter
 from devcouncil.telemetry.traces import TraceLogger
+from devcouncil.telemetry.stages import log_stage, log_step
 
 app = typer.Typer(help="Review active coding-agent sessions and emit critique cards.")
 console = Console()
@@ -44,19 +45,26 @@ def sessions(
 ):
     """List coding-agent transcripts DevCouncil can review."""
     root = project_root.expanduser().resolve()
-    found = discover_sessions(root, client=client)
-    if json_format:
-        typer.echo(json.dumps({"sessions": [item.model_dump() for item in found]}, indent=2))
-        return
+    from devcouncil.telemetry.logging_setup import set_log_dir
+    set_log_dir(root)
+    logger.info("dev watch sessions: client=%s", client)
+    with log_stage("watch", project_root=root, subcommand="sessions", client=client):
+        log_step("watch/1: discovering sessions", project_root=root, trace=True)
+        found = discover_sessions(root, client=client)
+        if json_format:
+            typer.echo(dump_json({"sessions": [item.model_dump() for item in found]}, indent=2))
+            log_step("watch/complete", project_root=root, count=len(found), trace=True)
+            return
 
-    table = Table(title="DevCouncil Watch Sessions")
-    table.add_column("Client", style="cyan")
-    table.add_column("Session")
-    table.add_column("Turns", justify="right")
-    table.add_column("Transcript")
-    for item in found:
-        table.add_row(item.client, item.id, str(item.turns), item.transcript_path)
-    console.print(table)
+        table = Table(title="DevCouncil Watch Sessions")
+        table.add_column("Client", style="cyan")
+        table.add_column("Session")
+        table.add_column("Turns", justify="right")
+        table.add_column("Transcript")
+        for item in found:
+            table.add_row(item.client, item.id, str(item.turns), item.transcript_path)
+        console.print(table)
+        log_step("watch/complete", project_root=root, count=len(found), trace=True)
 
 
 @app.command("review")
@@ -81,7 +89,7 @@ def review(
     if transcript_path is None:
         message = "No transcript selected. Use --transcript, --session, or --latest."
         if json_format:
-            typer.echo(json.dumps({"ok": False, "error": message}, indent=2))
+            typer.echo(dump_json({"ok": False, "error": message}, indent=2))
         else:
             console.print(f"[red]{message}[/red]")
         raise typer.Exit(code=2)
@@ -89,7 +97,7 @@ def review(
     if turn is None:
         message = f"No assistant turn found in {transcript_path}."
         if json_format:
-            typer.echo(json.dumps({"ok": False, "error": message}, indent=2))
+            typer.echo(dump_json({"ok": False, "error": message}, indent=2))
         else:
             console.print(f"[yellow]{message}[/yellow]")
         raise typer.Exit(code=1)
@@ -106,7 +114,7 @@ def review(
     payload["duplicate"] = duplicate
 
     if json_format:
-        typer.echo(json.dumps(payload, indent=2))
+        typer.echo(dump_json(payload, indent=2))
         return
 
     _print_card(card)
@@ -129,7 +137,7 @@ def cards(
     if limit < 1:
         message = "--limit must be greater than 0."
         if json_format:
-            typer.echo(json.dumps({"ok": False, "error": message}, indent=2))
+            typer.echo(dump_json({"ok": False, "error": message}, indent=2))
         else:
             console.print(f"[red]{message}[/red]")
         raise typer.Exit(code=2)
@@ -142,14 +150,14 @@ def cards(
     )
     if error:
         if json_format:
-            typer.echo(json.dumps({"ok": False, "error": error}, indent=2))
+            typer.echo(dump_json({"ok": False, "error": error}, indent=2))
         else:
             console.print(f"[red]{error}[/red]")
         raise typer.Exit(code=2)
     total = len(found)
     found = found[:limit]
     if json_format:
-        typer.echo(json.dumps({
+        typer.echo(dump_json({
             "cards": [item.model_dump() for item in found],
             "filters": {
                 "task_id": task_id,
@@ -175,7 +183,7 @@ def status(
     root = project_root.expanduser().resolve()
     payload = live_review_summary(root, task_id=task_id)
     if json_format:
-        typer.echo(json.dumps(payload, indent=2))
+        typer.echo(dump_json(payload, indent=2))
         return
     blockers = payload["blocking_cards"]
 
@@ -232,7 +240,7 @@ def resolve(
     if status not in {"resolved", "ignored"}:
         message = "--status must be resolved or ignored."
         if json_format:
-            typer.echo(json.dumps({"ok": False, "error": message}, indent=2))
+            typer.echo(dump_json({"ok": False, "error": message}, indent=2))
         else:
             console.print(f"[red]{message}[/red]")
         raise typer.Exit(code=2)
@@ -241,12 +249,12 @@ def resolve(
     if card is None:
         message = f"Critique card {card_id} not found."
         if json_format:
-            typer.echo(json.dumps({"ok": False, "error": message}, indent=2))
+            typer.echo(dump_json({"ok": False, "error": message}, indent=2))
         else:
             console.print(f"[red]{message}[/red]")
         raise typer.Exit(code=1)
     if json_format:
-        typer.echo(json.dumps({"ok": True, "card": card.model_dump()}, indent=2))
+        typer.echo(dump_json({"ok": True, "card": card.model_dump()}, indent=2))
         _log_card_resolved(root, card)
         return
     _log_card_resolved(root, card)
@@ -265,13 +273,13 @@ def repair(
     if card is None:
         message = f"Critique card {card_id} not found."
         if json_format:
-            typer.echo(json.dumps({"ok": False, "error": message}, indent=2))
+            typer.echo(dump_json({"ok": False, "error": message}, indent=2))
         else:
             console.print(f"[red]{message}[/red]")
         raise typer.Exit(code=1)
     prompt = build_live_repair_prompt(root, card)
     if json_format:
-        typer.echo(json.dumps({"ok": True, "card": card.model_dump(), "prompt": prompt}, indent=2))
+        typer.echo(dump_json({"ok": True, "card": card.model_dump(), "prompt": prompt}, indent=2))
         return
     typer.echo(prompt)
 
@@ -296,7 +304,7 @@ def repair_all(
     resolved_cards = [card for card in cards if card is not None]
     prompt = build_bulk_live_repair_prompt(root, resolved_cards)
     if json_format:
-        typer.echo(json.dumps({
+        typer.echo(dump_json({
             "ok": True,
             "scope_task_id": summary["scope_task_id"],
             "cards": [card.model_dump() for card in resolved_cards],
@@ -316,7 +324,7 @@ def signals(
     root = project_root.expanduser().resolve()
     found = _filtered_signals(root, client)
     if json_format:
-        typer.echo(json.dumps({"signals": [item.model_dump() for item in found]}, indent=2))
+        typer.echo(dump_json({"signals": [item.model_dump() for item in found]}, indent=2))
         return
     table = Table(title="DevCouncil Watch Signals")
     table.add_column("Client", style="cyan")
@@ -378,7 +386,7 @@ def pending(
 
     logger.info("dev watch pending complete: %d reviewed, %d skipped", len(reviewed), len(skipped))
     if json_format:
-        typer.echo(json.dumps({"reviewed": reviewed, "skipped": skipped}, indent=2))
+        typer.echo(dump_json({"reviewed": reviewed, "skipped": skipped}, indent=2))
         return
     for item in skipped:
         console.print(f"[yellow]Skipped signal:[/yellow] {item['reason']}")
@@ -441,7 +449,7 @@ def import_transcript(
     """Normalize a transcript into DevCouncil turn records without reviewing it."""
     turns = load_turns(transcript.expanduser().resolve(), client=client)
     if json_format:
-        typer.echo(json.dumps({"turns": [turn.model_dump() for turn in turns]}, indent=2))
+        typer.echo(dump_json({"turns": [turn.model_dump() for turn in turns]}, indent=2))
         return
     console.print(f"Loaded {len(turns)} turns from {transcript}")
 
@@ -492,6 +500,7 @@ def _resolve_transcript(
     transcript: Path | None = None,
     session: str | None = None,
     latest: bool = False,
+    task_id: str | None = None,
 ) -> Path | None:
     if transcript is not None:
         path = transcript.expanduser()
@@ -499,6 +508,13 @@ def _resolve_transcript(
             path = root / path
         return path.resolve()
 
+    if client.lower() == "claude" and task_id:
+        from devcouncil.live.transcripts import claude_transcript_for_task
+
+        pinned = claude_transcript_for_task(root, task_id)
+        if pinned is not None:
+            return pinned
+
     selector = "latest" if latest else session
     if selector is None:
         return None
@@ -590,5 +606,8 @@ async def _review_turn(turn, root: Path, client: str, use_llm: bool, task_id: st
         logger.warning("Model-backed live review unavailable; using deterministic card: %s", exc)
         console.print(f"[yellow]Model-backed review unavailable; using deterministic card: {exc}[/yellow]")
         return review_turn(turn, root, client=client, task_id=task_id)
-    card = await LiveReviewService(router).review(turn, root, client=client, use_llm=True)
+    # task_id flows through so the LLM review is grounded in the task's recorded
+    # verification state (like the deterministic path), instead of judging the
+    # agent's prose in a vacuum.
+    card = await LiveReviewService(router).review(turn, root, client=client, use_llm=True, task_id=task_id)
     return card.model_copy(update={"task_id": task_id}) if task_id else card

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

@@ -1,12 +1,15 @@
-import json
+from devcouncil.utils.json_persist import dump_json
+import logging
 import typer
 from pathlib import Path
 from rich.console import Console
 
 from devcouncil.cli.commands.init import initialize_project
 from devcouncil.execution.fs_watcher import FilesystemWatcher
+from devcouncil.telemetry.stages import log_stage, log_step
 
 console = Console()
+logger = logging.getLogger(__name__)
 
 
 def watch_fs(
@@ -17,24 +20,32 @@ def watch_fs(
     json_format: bool = typer.Option(False, "--json"),
 ):
     root = project_root.expanduser().resolve()
+    from devcouncil.telemetry.logging_setup import set_log_dir
+    set_log_dir(root)
+    logger.info("dev watch-fs: task=%s once=%s", task_id, once)
     initialize_project(root, quiet=True)
 
-    def _print_event(event: dict) -> None:
-        status = "allowed" if event["allowed"] else "denied"
-        console.print(f"[cyan]{event['path']}[/cyan] {status}: {event['reason']}")
+    with log_stage("watch_fs", project_root=root, task_id=task_id, once=once):
+        log_step("watch_fs/1: starting filesystem watcher", project_root=root, task_id=task_id, trace=True)
 
-    watcher = FilesystemWatcher(root, task_id, poll_interval=poll_interval, on_event=_print_event)
-    if once:
-        events = watcher.scan_once()
-        if json_format:
-            typer.echo(json.dumps({"events": events}, indent=2))
-        else:
-            for event in events:
-                status = "allowed" if event["allowed"] else "denied"
-                console.print(f"[cyan]{event['path']}[/cyan] {status}: {event['reason']}")
-        return
-    console.print(f"[cyan]Watching filesystem for task {task_id}. Ctrl+C to stop.[/cyan]")
-    try:
-        watcher.watch()
-    except KeyboardInterrupt:
-        console.print("[yellow]Stopped filesystem watcher.[/yellow]")
+        def _print_event(event: dict) -> None:
+            status = "allowed" if event["allowed"] else "denied"
+            console.print(f"[cyan]{event['path']}[/cyan] {status}: {event['reason']}")
+
+        watcher = FilesystemWatcher(root, task_id, poll_interval=poll_interval, on_event=_print_event)
+        if once:
+            events = watcher.scan_once()
+            if json_format:
+                typer.echo(dump_json({"events": events}, indent=2))
+            else:
+                for event in events:
+                    status = "allowed" if event["allowed"] else "denied"
+                    console.print(f"[cyan]{event['path']}[/cyan] {status}: {event['reason']}")
+            log_step("watch_fs/complete", project_root=root, task_id=task_id, count=len(events), trace=True)
+            return
+        console.print(f"[cyan]Watching filesystem for task {task_id}. Ctrl+C to stop.[/cyan]")
+        try:
+            watcher.watch()
+        except KeyboardInterrupt:
+            console.print("[yellow]Stopped filesystem watcher.[/yellow]")
+        log_step("watch_fs/complete", project_root=root, task_id=task_id, trace=True)

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

@@ -0,0 +1,278 @@
+"""`dev wiki` — generate and maintain the agent-facing codebase wiki.
+
+An OpenWiki-style, self-maintaining wiki of this repository, emitted as an OKF bundle
+under ``.devcouncil/knowledge/okf/wiki/`` so pages are automatically injected into
+planning/council/task prompts as knowledge sources (and are exportable/renderable with
+the existing ``dev okf`` tooling).
+
+* ``dev wiki update`` (alias ``generate``) — build the wiki, or refresh only the pages
+  whose repo-map slice changed. With a configured model, new/stale pages are enriched
+  with LLM-written prose by the ``wiki_writer`` role; without one, the deterministic
+  skeleton is used.
+* ``dev wiki status`` — show which pages are fresh vs stale against the current map.
+* ``dev wiki install-action`` — write a GitHub Action that keeps the wiki updated by
+  opening a PR when the map drifts (the OpenWiki maintenance pattern).
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from devcouncil.indexing.repo_mapper import RepoMap
+
+app = typer.Typer(help="Generate and maintain the agent-facing codebase wiki (OKF bundle).")
+console = Console()
+logger = logging.getLogger(__name__)
+
+_WORKFLOW_PATH = Path(".github") / "workflows" / "devcouncil-wiki-update.yml"
+
+_WIKI_WORKFLOW = """\
+# DevCouncil codebase wiki — automatic maintenance.
+#
+# Generated by `dev wiki install-action`. Nightly (and on demand) this rebuilds the
+# repository map, refreshes the stale wiki pages, and opens a PR when anything changed —
+# so the agent-facing documentation tracks the code without anyone remembering to run it.
+#
+# The refresh runs with --no-llm by default (deterministic, no secrets needed). To get
+# LLM-enriched prose in CI, add your provider API key as a repository secret and export
+# it in the "Update wiki" step (e.g. OPENROUTER_API_KEY).
+name: DevCouncil Wiki Update
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 5 * * *"  # nightly (UTC); adjust or remove as needed
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  update-wiki:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v7
+      - name: Install DevCouncil
+        run: |
+          uv tool install devcouncil
+          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+      - name: Update wiki
+        run: |
+          dev map --no-wiki > /dev/null
+          dev wiki update --no-llm
+      - name: Open PR if the wiki changed
+        uses: peter-evans/create-pull-request@v7
+        with:
+          commit-message: "docs: refresh DevCouncil codebase wiki"
+          title: "Refresh DevCouncil codebase wiki"
+          body: >
+            Automated wiki refresh: the repository map drifted from the last generated
+            wiki. Review the page diffs and merge to keep agent-facing docs current.
+          branch: devcouncil/wiki-update
+          add-paths: |
+            .devcouncil/knowledge/okf/wiki/**
+"""
+
+# .gitignore rules that make the wiki committable in repos that ignore .devcouncil/*
+# (the default DevCouncil layout). Appended by `dev wiki install-action` when needed.
+_GITIGNORE_UNIGNORE = """\
+
+# DevCouncil codebase wiki: shared knowledge-as-code, maintained by `dev wiki update`.
+!.devcouncil/knowledge/
+.devcouncil/knowledge/*
+!.devcouncil/knowledge/okf/
+.devcouncil/knowledge/okf/*
+!.devcouncil/knowledge/okf/wiki/
+"""
+
+
+def wiki_dir_for(root: Path) -> Path:
+    from devcouncil.knowledge.wiki import wiki_dir_for as _wiki_dir_for
+
+    return _wiki_dir_for(root)
+
+
+def _load_repo_map(root: Path, *, remap: bool) -> RepoMap:
+    """Load .devcouncil/repo_map.json, (re)generating it when missing or on --remap."""
+    map_path = root / ".devcouncil" / "repo_map.json"
+    if remap or not map_path.is_file():
+        from devcouncil.indexing.map_artifacts import generate_map_artifacts
+
+        console.print("[dim]Building repository map...[/dim]")
+        return generate_map_artifacts(root, map_path)
+    return RepoMap.model_validate_json(map_path.read_text(encoding="utf-8"))
+
+
+def _print_result(result) -> None:
+    if result.changed:
+        console.print(
+            f"[green]Wiki updated:[/green] {len(result.created)} created, "
+            f"{len(result.updated)} updated, {len(result.skipped)} unchanged "
+            f"([cyan]{result.wiki_dir}[/cyan])."
+        )
+    else:
+        console.print(
+            f"[green]Wiki is up to date[/green] ({len(result.skipped)} pages, "
+            f"[cyan]{result.wiki_dir}[/cyan])."
+        )
+    if result.enriched:
+        console.print(f"[green]LLM-enriched {len(result.enriched)} page(s).[/green]")
+    if result.problems:
+        console.print(f"[yellow]{len(result.problems)} OKF validation issue(s):[/yellow]")
+        for p in result.problems[:10]:
+            console.print(f"  - {p}")
+
+
+def _update(
+    project_root: Path,
+    *,
+    llm: bool,
+    force: bool,
+    remap: bool,
+) -> None:
+    root = project_root.expanduser().resolve()
+    from devcouncil.telemetry.logging_setup import set_log_dir
+
+    set_log_dir(root)
+    logger.info("dev wiki update: llm=%s force=%s remap=%s", llm, force, remap)
+    from devcouncil.cli.commands.init import initialize_project
+
+    initialize_project(root, quiet=True)
+
+    from devcouncil.knowledge.wiki import refresh_wiki
+
+    result = refresh_wiki(root, llm=llm, force=force, remap=remap)
+    _print_result(result)
+
+
+@app.command("update")
+def update(
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root containing .devcouncil/."),
+    llm: bool = typer.Option(True, "--llm/--no-llm", help="Enrich new/stale pages with LLM-written prose (degrades to the skeleton without a configured model)."),
+    force: bool = typer.Option(False, "--force", help="Rewrite (and re-enrich) every page, ignoring fingerprints."),
+    remap: bool = typer.Option(False, "--remap", help="Rebuild .devcouncil/repo_map.json first."),
+) -> None:
+    """Create the wiki, or refresh only the pages whose repo-map slice changed."""
+    _update(project_root, llm=llm, force=force, remap=remap)
+
+
+@app.command("generate")
+def generate(
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root containing .devcouncil/."),
+    llm: bool = typer.Option(True, "--llm/--no-llm", help="Enrich pages with LLM-written prose."),
+    force: bool = typer.Option(False, "--force", help="Rewrite (and re-enrich) every page."),
+    remap: bool = typer.Option(False, "--remap", help="Rebuild .devcouncil/repo_map.json first."),
+) -> None:
+    """Alias of `dev wiki update`."""
+    _update(project_root, llm=llm, force=force, remap=remap)
+
+
+@app.command("read")
+def read(
+    page: str | None = typer.Option(None, "--page", help="Fetch one wiki page by relative path."),
+    query: str | None = typer.Option(None, "--query", help="Search wiki pages by keyword."),
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root containing .devcouncil/."),
+    json_output: bool = typer.Option(False, "--json", help="Emit machine-readable JSON."),
+) -> None:
+    """Read the generated codebase wiki (list, fetch, or search)."""
+    from devcouncil.knowledge.wiki_read import read_wiki_page
+
+    root = project_root.expanduser().resolve()
+    payload = read_wiki_page(root, page=page, query=query)
+    if json_output:
+        console.print_json(data=payload)
+        if not payload.get("ok", True):
+            raise typer.Exit(code=1)
+        return
+    if not payload.get("ok", True):
+        console.print(f"[red]{payload.get('error')}[/red]")
+        raise typer.Exit(code=1)
+    if "pages" in payload:
+        pages = payload["pages"]
+        if isinstance(pages, list):
+            for item in pages:
+                if isinstance(item, dict):
+                    console.print(f"- {item.get('page')}: {item.get('title')}")
+        return
+    console.print(payload.get("body") or "")
+
+
+@app.command("status")
+def status(
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root containing .devcouncil/."),
+    json_output: bool = typer.Option(False, "--json", help="Emit machine-readable JSON."),
+) -> None:
+    """Show which wiki pages are fresh vs stale against the current repository map."""
+    root = project_root.expanduser().resolve()
+    from devcouncil.telemetry.logging_setup import set_log_dir
+
+    set_log_dir(root)
+
+    wiki_dir = wiki_dir_for(root)
+    if not (wiki_dir / "index.md").is_file():
+        if json_output:
+            console.print_json(data={"exists": False, "wiki_dir": str(wiki_dir)})
+        else:
+            console.print(
+                f"[yellow]No wiki found at[/yellow] {wiki_dir}. Run [bold]dev wiki update[/bold] to create it."
+            )
+        raise typer.Exit(code=1)
+
+    repo_map = _load_repo_map(root, remap=False)
+    from devcouncil.knowledge.wiki import _page_fingerprints, wiki_stale_pages
+
+    stale = wiki_stale_pages(root, repo_map, wiki_dir)
+    total = len(_page_fingerprints(repo_map))
+
+    if json_output:
+        console.print_json(data={
+            "exists": True,
+            "wiki_dir": str(wiki_dir),
+            "pages": total,
+            "stale": stale,
+            "fresh": total - len(stale),
+        })
+        return
+
+    if not stale:
+        console.print(f"[green]✓ Wiki is fresh[/green] — {total} page(s) match the current repo map.")
+        return
+
+    table = Table(title=f"Stale wiki pages ({len(stale)}/{total})")
+    table.add_column("Page", overflow="fold")
+    table.add_column("Reason")
+    for rel_path, reason in sorted(stale.items()):
+        table.add_row(rel_path, reason)
+    console.print(table)
+    console.print("Run [bold]dev wiki update[/bold] to refresh them.")
+
+
+@app.command("install-action")
+def install_action(
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root containing .devcouncil/."),
+    force: bool = typer.Option(False, "--force", help="Overwrite an existing workflow file."),
+) -> None:
+    """Install a GitHub Action that keeps the wiki updated via automated PRs."""
+    root = project_root.expanduser().resolve()
+    target = root / _WORKFLOW_PATH
+    if target.exists() and not force:
+        console.print(f"[yellow]{target} already exists; use --force to overwrite.[/yellow]")
+        raise typer.Exit(code=1)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(_WIKI_WORKFLOW, encoding="utf-8")
+    console.print(f"[green]Wrote[/green] {target}. The wiki will refresh nightly via PR.")
+
+    # The default DevCouncil .gitignore ignores .devcouncil/* — un-ignore the wiki so
+    # the workflow's PRs can actually commit it.
+    gitignore = root / ".gitignore"
+    if gitignore.is_file():
+        content = gitignore.read_text(encoding="utf-8")
+        if ".devcouncil" in content and "!.devcouncil/knowledge/okf/wiki/" not in content:
+            gitignore.write_text(content.rstrip("\n") + "\n" + _GITIGNORE_UNIGNORE, encoding="utf-8")
+            console.print("[green]Updated .gitignore[/green] so the wiki is committable.")