devcouncil 0.4.0 → 0.4.1

package/README.md

@@ -1,26 +1,65 @@
 # DevCouncil: The Gated AI Orchestrator
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/bharathvbcr/DevCouncil/main/src/devcouncil/assets/devcouncil_logo_premium.png" alt="DevCouncil Logo" width="300">
+  <img src="https://raw.githubusercontent.com/bharathvbcr/DevCouncil/main/src/devcouncil/assets/devcouncil_social_preview.jpg" alt="DevCouncil gated AI orchestration" width="720">
 </p>
 
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
 [![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
 [![uv](https://img.shields.io/badge/managed%20by-uv-purple.svg)](https://github.com/astral-sh/uv)
 
-**"DevCouncil should not merely generate code. It should make AI-generated work prove that it satisfied the original intent."**
+## OpenAI Build Week 2026
 
-DevCouncil is a high-integrity command-line orchestration platform for AI-assisted software development. It turns AI implementation from a black-box generation task into a gated engineering workflow where every change is authorized, verified, and traceable back to a requirement.
+Coding agents -- including Codex and other prompt-taking CLIs -- often claim success without proving that the change satisfied the original requirements. DevCouncil turns that claim into a gated engineering workflow: every change is scoped, verified, and traceable back to a requirement. Model confidence is not the final authority; evidence is.
 
-DevCouncil does not replace coding agents. Its primary native path is Claude Code, followed by Codex CLI; it also works beside OpenCode, Google Antigravity CLI, Warp/Oz, Cursor, Aider, and bring-your-own prompt-taking CLIs. It owns the plan, task scope, verification loop, repair prompts, and evidence trail.
+### What judges should see
+
+1. **Provider-free red-to-green evidence gate** -- install once, then watch a controlled sample fail verification and pass after a real fix, with no API keys.
+2. **Self-contained interactive code graph** -- open the packed `demo.html` artifact and navigate filters, path highlighting, and neighborhoods (no blank canvas).
+3. **Codex / MCP agent-control path** -- status, diffs, and task tools stay correct under real project-sized JSON so an agent can resume from evidence instead of chat memory.
+
+### Judge path (intended package: `devcouncil@0.4.1`)
+
+DevCouncil supports macOS, Linux, and Windows. Requires Node.js 18+, Python 3.12+, and Git. No model provider key is needed for the deterministic demos below.
+
+```bash
+# Prefer the Build Week release once published:
+npm install -g devcouncil@0.4.1
+devcouncil --help
+
+# Core demo: red verdict -> apply fix -> green verdict (no API keys)
+git clone https://github.com/bharathvbcr/DevCouncil.git
+cd DevCouncil
+bash scripts/build-week-demo.sh
+
+# Interactive graph artifact (self-contained HTML)
+mkdir -p /tmp/devcouncil-judge-demo
+dev graph demo --project-root /tmp/devcouncil-judge-demo --json
+# Open /tmp/devcouncil-judge-demo/.devcouncil/graph/demo.html
+```
+
+Until `0.4.1` is on the registry, clone this repository and run the same commands from a checkout that includes the Build Week fixes (`uv sync --group dev` if you need local `dev`).
+
+### Eligible Build Week work
+
+DevCouncil existed before OpenAI Build Week. This submission covers only meaningful extensions on or after **July 13, 2026**. Eligible history begins at commit `6f5bd73` (baseline before eligible work: `3cfd5d1`). Major themes:
+
+- canonical SQLite code-intelligence index, multi-language grammars, incremental watching, graph queries/community detection, and a self-contained interactive code-graph artifact (including a ForceGraph compatibility fix for the packed demo);
+- stronger deterministic verification: stop gates, claim checking, diff-to-evidence coverage, task leases, PDG/corpus checks, bounded repair, machine-readable next actions;
+- deeper CLI, MCP, dashboard, coding-agent, and CI integration, plus the installable npm release path aimed at `0.4.1` for judges.
+
+During Build Week, Codex and GPT-5.6 were used as an engineering partner to map paths, challenge claims, run install/browser checks, implement focused repairs, and verify behavior. The maintainer set requirements, scope, and acceptance evidence. The primary Codex `/feedback` session ID is on the Devpost submission. This does **not** claim that all eligible code was authored exclusively by Codex/GPT-5.6.
+
+See [docs/build-week-demo.md](docs/build-week-demo.md) for the provider-free demo walkthrough.
 
 ## Documentation
 
+- [Build Week demo](docs/build-week-demo.md): provider-free red-to-green judge script.
 - [Quickstart](docs/quickstart.md): shortest install-to-first-task path.
 - [Daily workflow](docs/workflow.md): manual sidecar loop, verification, repair, rollback, and `dev watch`.
 - [Coding CLI integration](docs/coding-cli-integration.md): tiers, Claude Code, Codex, OpenCode, Antigravity, Cursor, Grok Build, Aider, MCP, hooks, stop gate / claim checks, and automated executors (Gemini deprecated).
 - [CLI command reference](docs/cli-reference.md): available `dev` commands.
-- [Repo map & code graph](docs/code-graph.md): `dev map` / `dev graph` — navigation, dead code, blast radius, PDG (opt-in), HTML visualizer.
+- [Repo map & code graph](docs/code-graph.md): `dev map` / `dev graph` -- navigation, dead code, blast radius, PDG (opt-in), HTML visualizer.
 - [Corpus side index](docs/corpus.md): `dev corpus` for docs/PDFs/images and optional verify gates.
 - [Hero loop](docs/hero-loop.md): certified Claude Code + MCP closed loop, leases, rigor, and `dev check --verify` on-ramp.
 - [Architecture](docs/architecture.md): components, artifact graph, state machine, gating policy, and gated execution.
@@ -152,7 +191,11 @@ DevCouncil is an application layer around coding agents. It does not just emit p
 ### Workflow Features
 
 - **Repository onboarding:** `dev setup` initializes `.devcouncil/`, generates the repo map + `AGENTS.md`/`CLAUDE.md` guides, scaffolds applicable engineering skills, runs environment checks, offers integration setup, and prints the next useful commands. Use `--skip-map` / `--skip-skills` to opt out, or `--scaffold-ci` to also write a starter GitHub Actions workflow. **`dev boot "goal"`** chains setup, `dev integrate --apply`, optional CI scaffold flags, and `dev go` in one command (see [quickstart](docs/quickstart.md)).
-- **Repository mapping:** `dev map` writes `.devcouncil/repo_map.json` and a symbol-level `.devcouncil/graph/code_graph.json`, identifies important files and subsystems, filters generated/temp files, and keeps managed `AGENTS.md` / `CLAUDE.md` workspace guides synchronized. Subsystems, entry points, neighbors, and important surfaces are inferred generically for **any** repository — grouped from the directory tree and ranked by an import-graph in-degree. Freshness uses git HEAD, tracked-file hash, and a content fingerprint so plain edits mark the map stale; a **missing map is stale** (fail-closed on hard rigor). Post-tool-use hooks and `dev map --watch` refresh incrementally. Unified analyze entry: `dev graph ingest`. Query with `dev graph query|trace|dead|search|cypher|html`. Liveness lists are capped at 5000 per list and 256 dependents per file (truncation metadata when hit). The map is also generated automatically on first init.
+- **Repository mapping:** `dev map` writes `.devcouncil/repo_map.json` and a symbol-level `.devcouncil/graph/code_graph.json`, identifies important files and subsystems, filters generated/temp files, and keeps managed `AGENTS.md` / `CLAUDE.md` workspace guides synchronized. Subsystems, entry points, neighbors, and important surfaces are inferred generically for **any** repository — grouped from the directory tree and ranked by an import-graph in-degree. Freshness uses git HEAD, tracked-file hash, and a content fingerprint so plain edits mark the map stale; a **missing map is stale** (fail-closed on hard rigor). Post-tool-use hooks and `dev map --watch` refresh incrementally. Unified analyze entry: `dev graph ingest`. Query with `dev graph query|trace|dead|search|cypher|html`. Liveness lists are capped at 5000 per list and 256 dependents per file (truncation metadata when hit). The map is also generated automatically on first init. (See [docs/code-graph.md](docs/code-graph.md) for details).
+  
+  <p align="center">
+    <img src="docs/graph_preview.png" alt="Repository Code Graph Preview" width="600">
+  </p>
 - **Engineering skills:** `dev skills` lists the bundled skills and shows which apply to the repository; `dev skills scaffold` writes them into `.claude/skills/<name>/SKILL.md`. A merged always-on `core-engineering` skill (think-before-coding, simplicity, surgical changes, goal-driven execution, evidence-grounded communication) plus domain skills (Android, iOS, Windows, web, AI training) that brief the agent on current SDKs, deprecations, and tooling before coding. Applicable skills are also embedded into `dev prompt` output.
 - **CI scaffolding:** `dev scaffold-ci` writes a starter `.github/workflows/devcouncil.yml` derived from the configured test/lint/typecheck commands, filtered to the detected language stack; it never overwrites existing CI unless `--force`. Run `dev scaffold-ci --evidence` to generate `.github/workflows/devcouncil-evidence.yml` which automates verifying PRs and uploading evidence JSON and HTML reports.
 - **Planning council:** `dev plan` turns a goal into requirements, acceptance criteria, assumptions, critique findings, and executable tasks. When advisory gaps remain, the project stays in `AWAITING_USER_DECISIONS` until you run `dev approve` (or `dev e2e`/`dev go --force`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devcouncil",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Gated orchestrator for AI-assisted software development",
   "license": "Apache-2.0",
   "homepage": "https://github.com/bharathvbcr/DevCouncil#readme",

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "devcouncil"
-version = "0.4.0"
+version = "0.4.1"
 description = "Gated orchestrator for AI-assisted software development"
 readme = "README.md"
 requires-python = ">=3.12"

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

@@ -210,23 +210,20 @@ def status(
 
     if payload["pending_signal_items"]:
         table = Table(title="Pending Agent Responses")
-        table.add_column("Client", style="cyan")
+        table.add_column("ID", style="cyan")
+        table.add_column("Client")
         table.add_column("Task")
-        table.add_column("Transcript", overflow="fold")
-        table.add_column("Review Command", overflow="fold")
         for signal in payload["pending_signal_items"]:
             table.add_row(
+                signal.get("id") or "",
                 signal.get("client") or "",
                 signal.get("task_id") or "(unscoped)",
-                signal.get("transcript_path") or "",
-                signal.get("review_command") or "",
             )
         console.print(table)
-        commands = [signal.get("review_command") for signal in payload["pending_signal_items"] if signal.get("review_command")]
-        if commands:
-            console.print("[cyan]Pending review commands:[/cyan]")
-            for command in commands:
-                console.print(command)
+        console.print(
+            "[dim]Sensitive transcript paths and review commands: "
+            "`dev watch signals` / `dev watch review`.[/dim]"
+        )
 
 
 @app.command("resolve")

package/src/devcouncil/indexing/viz.py

@@ -47,7 +47,7 @@ def _vendor_js() -> str:
         "nodeVal:function(){return this},linkColor:function(){return this},"
         "linkDirectionalParticles:function(){return this},"
         "linkDirectionalParticleWidth:function(){return this},"
-        "onNodeClick:function(){return this},onNodeDblClick:function(){return this},"
+        "onNodeClick:function(){return this},"
         "width:function(){return this},height:function(){return this},_missing:true};};"
     )
 
@@ -565,7 +565,16 @@ const g = Graph(elem)
     if (pathHighlight.size && pathHighlight.has(s) && pathHighlight.has(t)) return 3;
     return 1.5;
   }})
-  .onNodeClick(n => {{
+  .onNodeClick((n, event) => {{
+    // ForceGraph exposes click events but no double-click chain method.
+    // The native event detail increments for a double click, so use it to
+    // preserve neighbor expansion without depending on a nonexistent API.
+    if (event && event.detail >= 2) {{
+      const links = activePayload().links;
+      expandIds = neighborExpand(n.id, links, 1);
+      redraw();
+      return;
+    }}
     showDetail(n);
     if (selected.length === 1 && selected[0] === n.id) {{ selected = []; pathHighlight = new Set(); redraw(); return; }}
     if (selected.length >= 2) selected = [];
@@ -577,11 +586,6 @@ const g = Graph(elem)
       showDetail(n);
     }}
     redraw();
-  }})
-  .onNodeDblClick(n => {{
-    const links = activePayload().links;
-    expandIds = neighborExpand(n.id, links, 1);
-    redraw();
   }});
 
 function redraw() {{

package/src/devcouncil/integrations/mcp/handlers/cli_gate.py

@@ -38,6 +38,6 @@ async def handle_cli(root: Path, arguments: dict) -> list[TextContent]:
     if forbidden:
         return error_text("forbidden flag(s) through MCP: " + ", ".join(forbidden), code="forbidden_flags", flags=forbidden)
     try:
-        return json_text(run_cli_command(args, root))
+        return json_text(run_cli_command(args, root, truncate=True))
     except Exception as exc:
         return error_text(str(exc), code="cli_execution_error")

package/src/devcouncil/integrations/mcp/handlers/git.py

@@ -20,12 +20,139 @@ from devcouncil.integrations.mcp.util import (
 from devcouncil.storage.db import Database
 from devcouncil.storage.repositories import TaskRepository
 
+_BINARY_PROBE_BYTES = 8192
+
+
+def _run_git(root: Path, args: list[str]) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        args,
+        cwd=root,
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        timeout=CLI_TIMEOUT_SECONDS,
+    )
+
+
+def _parse_name_status_z(data: str) -> dict[str, str]:
+    """Parse ``git diff --name-status -z`` into ``{path: status}``.
+
+    Rename/copy records are ``STATUS\\0OLD\\0NEW\\0``; other records are
+    ``STATUS\\0PATH\\0``. The new path is the authoritative key for renames.
+    """
+    status_by_path: dict[str, str] = {}
+    parts = data.split("\0")
+    i = 0
+    while i < len(parts):
+        status = parts[i]
+        if not status:
+            i += 1
+            continue
+        kind = status[0]
+        if kind in "RC" and i + 2 < len(parts):
+            new_path = parts[i + 2].replace("\\", "/")
+            if new_path:
+                status_by_path[new_path] = status
+            i += 3
+            continue
+        if i + 1 < len(parts):
+            path = parts[i + 1].replace("\\", "/")
+            if path:
+                status_by_path[path] = status
+            i += 2
+            continue
+        break
+    return status_by_path
+
+
+def _format_untracked_file_diff(rel_path: str, full_path: Path) -> tuple[str, int]:
+    """Return ``(unified_diff_fragment, addition_count)`` for a new untracked file."""
+    try:
+        raw = full_path.read_bytes()
+    except OSError:
+        return "", 0
+
+    header = [
+        f"diff --git a/{rel_path} b/{rel_path}",
+        "new file mode 100644",
+        "--- /dev/null",
+        f"+++ b/{rel_path}",
+    ]
+    if b"\0" in raw[:_BINARY_PROBE_BYTES]:
+        return "\n".join([*header, f"Binary files /dev/null and b/{rel_path} differ"]), 0
+
+    text = raw.decode("utf-8", errors="replace")
+    if not text:
+        return "\n".join(header) + "\n", 0
+
+    lines = text.splitlines()
+    if text.endswith(("\n", "\r")):
+        line_count = len(lines)
+    else:
+        line_count = max(len(lines), 1)
+
+    diff_lines = [*header, f"@@ -0,0 +1,{line_count} @@"]
+    diff_lines.extend(f"+{line}" for line in lines)
+    return "\n".join(diff_lines), line_count
+
+
+def _list_untracked(root: Path, paths: list[str]) -> tuple[list[str], str | None]:
+    """List untracked paths; return ``(paths, error)`` when the Git call fails."""
+    args = ["git", "ls-files", "--others", "--exclude-standard", "-z"]
+    if paths:
+        args.append("--")
+        args.extend(paths)
+    try:
+        proc = _run_git(root, args)
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        return [], str(exc)
+    if proc.returncode != 0:
+        detail = (proc.stderr or proc.stdout or f"git ls-files exited {proc.returncode}").strip()
+        return [], detail or f"git ls-files exited {proc.returncode}"
+    return [p.replace("\\", "/") for p in proc.stdout.split("\0") if p.strip()], None
+
+
+def _collect_untracked(
+    root: Path,
+    paths: list[str],
+    *,
+    known_paths: set[str],
+) -> tuple[list[dict[str, object]], str, str | None]:
+    """Build file entries and unified diff for untracked files in scope."""
+    untracked, err = _list_untracked(root, paths)
+    if err is not None:
+        return [], "", err
+
+    files: list[dict[str, object]] = []
+    fragments: list[str] = []
+    for rel in untracked:
+        if rel in known_paths:
+            continue
+        full = root / rel
+        if not full.is_file():
+            continue
+        fragment, additions = _format_untracked_file_diff(rel, full)
+        if not fragment:
+            continue
+        files.append({
+            "path": rel,
+            "status": "A",
+            "additions": additions,
+            "deletions": 0,
+        })
+        fragments.append(fragment.rstrip("\n"))
+    unified = "\n".join(fragments)
+    if unified:
+        unified += "\n"
+    return files, unified, None
+
 
 async def git_diff(root: Path, paths: list[str], staged: bool) -> dict[str, object]:
     """Compute a (optionally path-scoped, optionally staged) git diff."""
     diff_args = ["git", "diff"]
     numstat_args = ["git", "diff", "--numstat"]
-    namestatus_args = ["git", "diff", "--name-status"]
+    namestatus_args = ["git", "diff", "--name-status", "-z"]
     if staged:
         for args in (diff_args, numstat_args, namestatus_args):
             args.append("--cached")
@@ -35,10 +162,7 @@ async def git_diff(root: Path, paths: list[str], staged: bool) -> dict[str, obje
             args.extend(paths)
 
     def _run(args: list[str]) -> subprocess.CompletedProcess[str]:
-        return subprocess.run(
-            args, cwd=root, capture_output=True, text=True,
-            encoding="utf-8", errors="replace", timeout=CLI_TIMEOUT_SECONDS,
-        )
+        return _run_git(root, args)
 
     try:
         loop = asyncio.get_event_loop()
@@ -50,11 +174,23 @@ async def git_diff(root: Path, paths: list[str], staged: bool) -> dict[str, obje
     except (OSError, subprocess.TimeoutExpired) as exc:
         return {"ok": False, "files": [], "unified_diff": "", "truncated": False, "error": str(exc)}
 
-    status_by_path: dict[str, str] = {}
-    for line in namestatus_proc.stdout.splitlines():
-        parts = line.split("\t")
-        if len(parts) >= 2:
-            status_by_path[parts[-1].replace("\\", "/")] = parts[0]
+    for proc, label in (
+        (diff_proc, "git diff"),
+        (numstat_proc, "git diff --numstat"),
+        (namestatus_proc, "git diff --name-status"),
+    ):
+        if proc.returncode != 0:
+            detail = (proc.stderr or proc.stdout or f"{label} exited {proc.returncode}").strip()
+            return {
+                "ok": False,
+                "files": [],
+                "unified_diff": "",
+                "truncated": False,
+                "error": detail or f"{label} exited {proc.returncode}",
+                "staged": staged,
+            }
+
+    status_by_path = _parse_name_status_z(namestatus_proc.stdout)
 
     files: list[dict[str, object]] = []
     for line in numstat_proc.stdout.splitlines():
@@ -62,6 +198,9 @@ async def git_diff(root: Path, paths: list[str], staged: bool) -> dict[str, obje
         if len(parts) < 3:
             continue
         added_str, deleted_str, file_path = parts[0], parts[1], parts[-1]
+        # Rename numstat without -z may use "old => new"; prefer the new side.
+        if " => " in file_path:
+            file_path = file_path.split(" => ", 1)[-1]
         file_path = file_path.replace("\\", "/")
         files.append({
             "path": file_path,
@@ -70,10 +209,37 @@ async def git_diff(root: Path, paths: list[str], staged: bool) -> dict[str, obje
             "deletions": int(deleted_str) if deleted_str.isdigit() else 0,
         })
 
-    unified_diff, truncated = truncate_text(diff_proc.stdout)
+    unified_parts = [diff_proc.stdout.rstrip("\n")] if diff_proc.stdout else []
+    if not staged:
+        known = {str(entry["path"]) for entry in files}
+        untracked_files, untracked_diff, untracked_err = await asyncio.get_event_loop().run_in_executor(
+            None,
+            lambda: _collect_untracked(root, paths, known_paths=known),
+        )
+        if untracked_err is not None:
+            return {
+                "ok": False,
+                "files": [],
+                "unified_diff": "",
+                "truncated": False,
+                "error": untracked_err,
+                "staged": staged,
+            }
+        files.extend(untracked_files)
+        if untracked_diff:
+            unified_parts.append(untracked_diff.rstrip("\n"))
+
+    combined = "\n".join(part for part in unified_parts if part)
+    if combined:
+        combined += "\n"
+    unified_diff, truncated = truncate_text(combined)
     return {"ok": True, "files": files, "unified_diff": unified_diff, "truncated": truncated, "staged": staged}
 
 
+def _empty_diff_payload(staged: bool) -> dict[str, object]:
+    return {"ok": True, "files": [], "unified_diff": "", "truncated": False, "staged": staged}
+
+
 async def handle_get_diff(root: Path, db: Database | None, arguments: dict) -> list[TextContent]:
     if not is_git_repo(root):
         return error_text("get_diff requires a git repository.", code="not_a_git_repo")
@@ -86,14 +252,30 @@ async def handle_get_diff(root: Path, db: Database | None, arguments: dict) -> l
     staged_value = arguments.get("staged", False)
     if not isinstance(staged_value, bool):
         return error_text("staged must be a boolean", code="invalid_arguments", argument="staged")
-    scope_paths: list[str] = list(explicit_paths)
-    if task_id and db:
+
+    scope_paths: list[str] = [p.replace("\\", "/") for p in explicit_paths]
+    task_scoped = False
+    if task_id:
+        if db is None:
+            return error_text(
+                "DevCouncil not initialized in this directory.",
+                code="not_initialized",
+            )
         with db.get_session() as session:
             task = TaskRepository(session).get_by_id(task_id)
         if task is None:
             return error_text(f"Task {task_id} not found.", code="not_found", task_id=task_id)
-        for planned in task.planned_files:
-            p = planned.path.replace("\\", "/")
-            if p not in scope_paths:
-                scope_paths.append(p)
+        planned = [pf.path.replace("\\", "/") for pf in task.planned_files]
+        planned_set = set(planned)
+        task_scoped = True
+        if explicit_paths:
+            # Intersect only — explicit paths must never broaden task scope.
+            scope_paths = [p for p in scope_paths if p in planned_set]
+        else:
+            scope_paths = planned
+
+    if task_scoped and not scope_paths:
+        # Empty planned scope or empty intersection: fail closed to empty, never full repo.
+        return json_text(_empty_diff_payload(staged_value))
+
     return json_text(await git_diff(root, scope_paths, staged_value))

package/src/devcouncil/integrations/mcp/handlers/graph.py

@@ -2,13 +2,13 @@
 
 from __future__ import annotations
 
-import json
 from pathlib import Path
 
 from mcp.types import TextContent
 
 from devcouncil.integrations.mcp.util import (
     json_text,
+    parse_cli_json,
     run_cli_command,
 )
 
@@ -21,13 +21,11 @@ async def handle_graph_context(root: Path, arguments: dict) -> list[TextContent]
     for item in files:
         if isinstance(item, str) and item:
             file_args.extend(["--file", item])
-    result = run_cli_command(["graph-context", "--json", *file_args], root)
-    if result.get("ok"):
-        try:
-            payload = json.loads(str(result.get("stdout") or "{}"))
-            return json_text(payload)
-        except json.JSONDecodeError:
-            pass
+    payload, _cli_error = parse_cli_json(
+        run_cli_command(["graph-context", "--json", *file_args], root, truncate=False),
+    )
+    if payload is not None:
+        return json_text(payload)
     from devcouncil.integrations.code_review_graph import CodeReviewGraphAdapter
 
     context = CodeReviewGraphAdapter(root).get_context(

package/src/devcouncil/integrations/mcp/handlers/knowledge.py

@@ -2,13 +2,13 @@
 
 from __future__ import annotations
 
-import json
 from pathlib import Path
 
 from mcp.types import TextContent
 
 from devcouncil.integrations.mcp.util import (
     json_text,
+    parse_cli_json,
     required_string_argument,
     run_cli_command,
 )
@@ -20,11 +20,9 @@ async def handle_select_knowledge(root: Path, arguments: dict) -> list[TextConte
     if arg_error:
         return arg_error
     assert goal is not None
-    result = run_cli_command(["okf", "select", "--json", "--goal", goal], root)
-    if result.get("ok"):
-        try:
-            payload = json.loads(str(result.get("stdout") or "{}"))
-            return json_text(payload)
-        except json.JSONDecodeError:
-            pass
+    payload, _cli_error = parse_cli_json(
+        run_cli_command(["okf", "select", "--json", "--goal", goal], root, truncate=False),
+    )
+    if payload is not None:
+        return json_text(payload)
     return json_text(select_knowledge_payload(root, goal))

package/src/devcouncil/integrations/mcp/handlers/provenance.py

@@ -2,13 +2,18 @@
 
 from __future__ import annotations
 
-import json
 from pathlib import Path
 
 from mcp.types import Resource, TextContent
 from pydantic import AnyUrl
 
-from devcouncil.integrations.mcp.util import json_text, required_string_argument, run_cli_command
+from devcouncil.integrations.mcp.util import (
+    json_text,
+    parse_cli_json,
+    required_string_argument,
+    run_cli_command,
+    run_cli_json,
+)
 from devcouncil.knowledge.resource_discovery import (
     discover_knowledge_sources,
     knowledge_source_uri,
@@ -27,28 +32,12 @@ __all__ = [
 from devcouncil.knowledge.resource_discovery import knowledge_settings  # noqa: E402
 
 
-def _cli_json(root: Path, args: list[str]) -> tuple[dict | None, list[TextContent] | None]:
-    result = run_cli_command(args, root)
-    stdout = str(result.get("stdout") or "").strip()
-    if stdout:
-        try:
-            return json.loads(stdout), None
-        except json.JSONDecodeError:
-            pass
-    if not result.get("ok"):
-        stderr = str(result.get("stderr") or "CLI command failed")
-        from devcouncil.integrations.mcp.util import error_text
-        return None, error_text(stderr, code="cli_failed")
-    from devcouncil.integrations.mcp.util import error_text
-    return None, error_text("CLI command returned invalid JSON", code="cli_parse_error")
-
-
 async def handle_get_task_provenance(root: Path, db: object, arguments: dict) -> list[TextContent]:
     task_id, arg_error = required_string_argument(arguments, "task_id")
     if arg_error:
         return arg_error
     assert task_id is not None
-    payload, cli_error = _cli_json(root, ["provenance", task_id, "--json"])
+    payload, cli_error = run_cli_json(["provenance", task_id, "--json"], root)
     if cli_error:
         return cli_error
     assert payload is not None
@@ -57,25 +46,22 @@ async def handle_get_task_provenance(root: Path, db: object, arguments: dict) ->
 
 async def list_resources(root: Path) -> list[Resource]:
     """Expose the DevCouncil corpus as browsable MCP resources."""
-    result = run_cli_command(["resource", "list", "--json"], root)
-    stdout = str(result.get("stdout") or "").strip()
-    if stdout:
-        try:
-            payload = json.loads(stdout)
-            descriptors = payload.get("resources") or []
-            if isinstance(descriptors, list):
-                return [
-                    Resource(
-                        uri=AnyUrl(item["uri"]),
-                        name=item["name"],
-                        description=item["description"],
-                        mimeType=item["mimeType"],
-                    )
-                    for item in descriptors
-                    if isinstance(item, dict) and item.get("uri")
-                ]
-        except json.JSONDecodeError:
-            pass
+    payload, _cli_error = parse_cli_json(
+        run_cli_command(["resource", "list", "--json"], root, truncate=False),
+    )
+    if payload is not None:
+        descriptors = payload.get("resources") or []
+        if isinstance(descriptors, list):
+            return [
+                Resource(
+                    uri=AnyUrl(item["uri"]),
+                    name=item["name"],
+                    description=item["description"],
+                    mimeType=item["mimeType"],
+                )
+                for item in descriptors
+                if isinstance(item, dict) and item.get("uri")
+            ]
     # Fallback when CLI is unavailable (e.g. during early init).
     from devcouncil.reporting.mcp_resources import list_mcp_resource_uris
 
@@ -92,7 +78,7 @@ async def list_resources(root: Path) -> list[Resource]:
 
 async def read_resource(root: Path, uri: AnyUrl) -> str:
     key = str(uri).rstrip("/")
-    result = run_cli_command(["resource", "read", key], root)
+    result = run_cli_command(["resource", "read", key], root, truncate=False)
     stdout = result.get("stdout")
     if result.get("ok") and stdout is not None:
         return str(stdout)