devcouncil 0.4.0 → 0.4.1

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

@@ -17,13 +17,42 @@ from devcouncil.integrations.mcp.util import (
     truncate_text,
     within_root,
 )
+from devcouncil.storage.db import Database
+from devcouncil.storage.repositories import TaskRepository
 
 
-async def handle_read_file(root: Path, arguments: dict) -> list[TextContent]:
+async def handle_read_file(
+    root: Path,
+    arguments: dict,
+    db: Database | None = None,
+) -> list[TextContent]:
     rel_path, arg_error = required_string_argument(arguments, "path")
     if arg_error:
         return arg_error
     assert rel_path is not None
+    task_id = optional_string_argument(arguments, "task_id")
+    if task_id == "":
+        return error_text("task_id must be a string", code="invalid_arguments", argument="task_id")
+    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)
+        planned = {pf.path.replace("\\", "/") for pf in task.planned_files}
+        normalized = rel_path.replace("\\", "/")
+        if normalized not in planned:
+            # Fail closed: never broaden task scope to arbitrary repo paths.
+            return error_text(
+                f"Path {normalized} is outside task {task_id} planned-file scope.",
+                code="out_of_scope",
+                path=normalized,
+                task_id=task_id,
+            )
     if is_secret_path(root, rel_path):
         return error_text(
             "Refusing to read a secret/credential path.",

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

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-import json
 from pathlib import Path
 
 from mcp.types import TextContent
@@ -13,25 +12,11 @@ from devcouncil.integrations.mcp.util import (
     json_text,
     optional_string_argument,
     required_string_argument,
-    run_cli_command,
+    run_cli_json,
     truncate_text,
 )
 
 
-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")
-        return None, error_text(stderr, code="cli_failed")
-    return None, error_text("CLI command returned invalid JSON", code="cli_parse_error")
-
-
 async def handle_list_agent_runs(root: Path, arguments: dict) -> list[TextContent]:
     status_filter = optional_string_argument(arguments, "status")
     if status_filter == "":
@@ -40,7 +25,7 @@ async def handle_list_agent_runs(root: Path, arguments: dict) -> list[TextConten
     cli_args = ["runs", "list", "--json", "--limit", str(limit)]
     if status_filter:
         cli_args.extend(["--status", status_filter])
-    payload, cli_error = _cli_json(root, cli_args)
+    payload, cli_error = run_cli_json(cli_args, root)
     if cli_error:
         return cli_error
     assert payload is not None
@@ -61,7 +46,7 @@ async def handle_get_run(root: Path, arguments: dict) -> list[TextContent]:
     if arg_error:
         return arg_error
     assert run_id is not None
-    payload, cli_error = _cli_json(root, ["runs", "show", run_id, "--json"])
+    payload, cli_error = run_cli_json(["runs", "show", run_id, "--json"], root)
     if cli_error:
         return cli_error
     assert payload is not None

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

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import json
 from pathlib import Path
+from typing import Any
 
 from mcp.types import TextContent
 
@@ -12,48 +13,108 @@ from devcouncil.integrations.mcp.util import (
     int_argument,
     json_text,
     optional_string_argument,
+    parse_cli_json,
     required_string_argument,
     run_cli_command,
+    run_cli_json,
 )
 
+# Default MCP list/status projections target a ~32 KB agent context budget.
+MCP_CONTEXT_BUDGET_CHARS = 32_000
+
+_LIST_TASK_FIELDS = ("id", "title", "status", "priority", "requirement_ids", "lease")
+_GAP_FIELDS = (
+    "id",
+    "severity",
+    "gap_type",
+    "blocking",
+    "task_id",
+    "requirement_id",
+    "file",
+    "line",
+    "acceptance_criterion_id",
+)
+_ACTION_FIELDS = (
+    "gap_id",
+    "gap_type",
+    "category",
+    "severity",
+    "blocking",
+    "action",
+    "file",
+    "line",
+    "suggested_command",
+    "acceptance_criterion_id",
+)
 
-def _cli_json(root: Path, args: list[str]) -> tuple[dict | None, list[TextContent] | None]:
-    result = run_cli_command(args, root)
-    if not result.get("ok"):
-        stderr = str(result.get("stderr") or "CLI command failed")
-        return None, error_text(stderr, code="cli_failed")
-    try:
-        return json.loads(str(result.get("stdout") or "{}")), None
-    except json.JSONDecodeError:
-        return None, error_text("CLI command returned invalid JSON", code="cli_parse_error")
 
+def _compact_task_row(task: object) -> dict[str, Any]:
+    if not isinstance(task, dict):
+        return {}
+    row: dict[str, Any] = {key: task.get(key) for key in _LIST_TASK_FIELDS}
+    row["requirements"] = task.get("requirement_ids") or []
+    row.pop("requirement_ids", None)
+    return row
 
-async def handle_status(root: Path, db: object, arguments: dict) -> list[TextContent]:
-    del db  # routed through CLI service layer
-    result = run_cli_command(["status", "--json"], root)
-    if not result.get("ok"):
-        stderr = str(result.get("stderr") or "status command failed")
-        return error_text(stderr, code="cli_failed")
+
+def _compact_gap_row(gap: object) -> dict[str, Any]:
+    if not isinstance(gap, dict):
+        return {}
+    return {key: gap.get(key) for key in _GAP_FIELDS}
+
+
+def _compact_action_row(action: object) -> dict[str, Any]:
+    if not isinstance(action, dict):
+        return {}
+    return {key: action.get(key) for key in _ACTION_FIELDS}
+
+
+def _status_cli_error(cli_error: list[TextContent]) -> list[TextContent]:
     try:
-        payload = json.loads(str(result.get("stdout") or "{}"))
-    except json.JSONDecodeError:
+        err = json.loads(cli_error[0].text)
+    except (IndexError, json.JSONDecodeError, TypeError):
+        return cli_error
+    code = err.get("code")
+    if code == "cli_parse_error":
         return error_text("status command returned invalid JSON", code="cli_parse_error")
+    if code == "cli_failed":
+        return error_text(str(err.get("error") or "status command failed"), code="cli_failed")
+    return cli_error
+
+
+async def handle_status(root: Path, db: object, arguments: dict) -> list[TextContent]:
+    del db, arguments
+    payload, cli_error = parse_cli_json(run_cli_command(["status", "--json"], root, truncate=False))
+    if cli_error:
+        return _status_cli_error(cli_error)
+    assert payload is not None
     if not payload.get("initialized"):
         return error_text("DevCouncil not initialized in this directory.", code="not_initialized")
     summary = payload.get("coverage_summary") or {}
+    live = payload.get("live_review") or {}
     phase = payload.get("phase", "UNKNOWN")
-    status_str = (
-        f"Phase: {phase}\n"
-        f"Requirements: {summary.get('total_requirements', 0)} ({summary.get('requirements_without_tasks', 0)} unmapped)\n"
-        f"Tasks: {summary.get('total_tasks', 0)} ({summary.get('tasks_without_requirements', 0)} orphaned)\n"
-        f"Gaps: {summary.get('total_gaps', 0)} ({summary.get('blocking_gaps', 0)} blocking)\n"
-    )
-    return [TextContent(type="text", text=status_str)]
+    lines = [
+        f"Phase: {phase}",
+        (
+            f"Requirements: {summary.get('total_requirements', 0)} "
+            f"({summary.get('requirements_without_tasks', 0)} unmapped)"
+        ),
+        (
+            f"Tasks: {summary.get('total_tasks', 0)} "
+            f"({summary.get('tasks_without_requirements', 0)} orphaned)"
+        ),
+        (
+            f"Gaps: {summary.get('total_gaps', 0)} "
+            f"({summary.get('blocking_gaps', 0)} blocking)"
+        ),
+        f"Live signals: {live.get('pending_signals', 0)}",
+    ]
+    return [TextContent(type="text", text="\n".join(lines) + "\n")]
 
 
 async def handle_report(root: Path, db: object, arguments: dict) -> list[TextContent]:
-    del db  # routed through CLI service layer
-    result = run_cli_command(["report"], root)
+    del db, arguments
+    result = run_cli_command(["report"], root, truncate=True)
     if not result.get("ok"):
         stderr = str(result.get("stderr") or "report command failed")
         return error_text(stderr, code="cli_failed")
@@ -61,7 +122,7 @@ async def handle_report(root: Path, db: object, arguments: dict) -> list[TextCon
 
 
 async def handle_get_gaps(root: Path, db: object, arguments: dict) -> list[TextContent]:
-    del db  # routed through CLI service layer
+    del db
     task_id, arg_error = required_string_argument(arguments, "task_id")
     if arg_error:
         return arg_error
@@ -70,22 +131,29 @@ async def handle_get_gaps(root: Path, db: object, arguments: dict) -> list[TextC
     cli_args = ["gaps", "--json", "--task-id", task_id]
     if blocking_only:
         cli_args.append("--blocking-only")
-    payload, cli_error = _cli_json(root, cli_args)
+    payload, cli_error = run_cli_json(cli_args, root)
     if cli_error:
         return cli_error
     assert payload is not None
     if not payload.get("initialized", True):
         return error_text("DevCouncil not initialized in this directory.", code="not_initialized")
+    gaps = payload.get("gaps")
+    if isinstance(gaps, list):
+        payload = {
+            **payload,
+            "gaps": [_compact_gap_row(gap) for gap in gaps],
+            "gap_count": len(gaps),
+        }
     return json_text(payload)
 
 
 async def handle_get_next_actions(root: Path, db: object, arguments: dict) -> list[TextContent]:
-    del db  # routed through CLI service layer
+    del db
     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, ["gaps", "--json", "--task-id", task_id, "--next-actions"])
+    payload, cli_error = run_cli_json(["gaps", "--json", "--task-id", task_id, "--next-actions"], root)
     if cli_error:
         return cli_error
     assert payload is not None
@@ -94,11 +162,22 @@ async def handle_get_next_actions(root: Path, db: object, arguments: dict) -> li
             str(payload.get("error") or "next-actions command failed"),
             code="cli_failed",
         )
+    next_actions = payload.get("next_actions")
+    advisory = payload.get("advisory_actions")
+    updates: dict[str, Any] = {}
+    if isinstance(next_actions, list):
+        updates["next_actions"] = [_compact_action_row(a) for a in next_actions]
+        updates["next_action_count"] = len(next_actions)
+    if isinstance(advisory, list):
+        updates["advisory_actions"] = [_compact_action_row(a) for a in advisory]
+        updates["advisory_action_count"] = len(advisory)
+    if updates:
+        payload = {**payload, **updates}
     return json_text(payload)
 
 
 async def handle_list_tasks(root: Path, db: object, arguments: dict) -> list[TextContent]:
-    del db  # routed through CLI service layer
+    del db
     status_filter = optional_string_argument(arguments, "status")
     if status_filter == "":
         return error_text("status must be a string", code="invalid_arguments", argument="status")
@@ -107,8 +186,14 @@ async def handle_list_tasks(root: Path, db: object, arguments: dict) -> list[Tex
     cli_args = ["tasks", "--json", "--limit", str(limit), "--offset", str(offset)]
     if status_filter:
         cli_args.extend(["--status", status_filter])
-    payload, cli_error = _cli_json(root, cli_args)
+    payload, cli_error = run_cli_json(cli_args, root)
     if cli_error:
         return cli_error
     assert payload is not None
+    tasks = payload.get("tasks")
+    if isinstance(tasks, list):
+        payload = {
+            **payload,
+            "tasks": [_compact_task_row(task) for task in tasks],
+        }
     return json_text(payload)

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

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-import json
 from pathlib import Path
 
 from mcp.types import TextContent
@@ -11,29 +10,18 @@ from devcouncil.integrations.mcp.util import (
     error_text,
     json_text,
     required_string_argument,
-    run_cli_command,
+    run_cli_json,
 )
 from devcouncil.utils.json_persist import dump_json
 
 
-def _cli_json(root: Path, args: list[str]) -> tuple[dict | None, list[TextContent] | None]:
-    result = run_cli_command(args, root)
-    if not result.get("ok"):
-        stderr = str(result.get("stderr") or "CLI command failed")
-        return None, error_text(stderr, code="cli_failed")
-    try:
-        return json.loads(str(result.get("stdout") or "{}")), None
-    except json.JSONDecodeError:
-        return None, error_text("CLI command returned invalid JSON", code="cli_parse_error")
-
-
 async def handle_get_task(root: Path, db: object, arguments: dict) -> list[TextContent]:
     del db  # routed through CLI service layer
     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, ["show", task_id, "--json"])
+    payload, cli_error = run_cli_json(["show", task_id, "--json"], root)
     if cli_error:
         return cli_error
     assert payload is not None
@@ -49,7 +37,7 @@ async def handle_get_prompt(root: Path, db: object, arguments: dict) -> list[Tex
     if arg_error:
         return arg_error
     assert task_id is not None
-    payload, cli_error = _cli_json(root, ["prompt", task_id, "--json"])
+    payload, cli_error = run_cli_json(["prompt", task_id, "--json"], root)
     if cli_error:
         return cli_error
     assert payload is not None
@@ -71,14 +59,14 @@ async def handle_prepare_execution(root: Path, db: object, arguments: dict) -> l
     if arg_error:
         return arg_error
     assert task_id is not None
-    show_payload, show_error = _cli_json(root, ["show", task_id, "--json"])
+    show_payload, show_error = run_cli_json(["show", task_id, "--json"], root)
     if show_error:
         return show_error
     assert show_payload is not None
     task = show_payload.get("task")
     if not isinstance(task, dict):
         return error_text(f"Task {task_id} not found.", code="not_found", task_id=str(task_id))
-    prompt_payload, prompt_error = _cli_json(root, ["prompt", task_id, "--json"])
+    prompt_payload, prompt_error = run_cli_json(["prompt", task_id, "--json"], root)
     if prompt_error:
         return prompt_error
     assert prompt_payload is not None

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

@@ -14,7 +14,11 @@ def all_tools() -> list[Tool]:
         *debug_tools(),
         Tool(
             name="devcouncil_status",
-            description="Get the current status of the DevCouncil project, including phase, tasks, and gaps.",
+            description=(
+                "Get a compact project status summary (phase, requirement/task/gap counts). "
+                "Default responses stay within a ~32 KB agent context budget; use "
+                "devcouncil_get_task / get_gaps / get_next_actions for detail by ID."
+            ),
             inputSchema={
                 "type": "object",
                 "properties": {}
@@ -50,9 +54,10 @@ def all_tools() -> list[Tool]:
         Tool(
             name="devcouncil_get_gaps",
             description=(
-                "Read the persisted verification gaps for a task WITHOUT re-running "
-                "verification. Cheap and idempotent — use it to resume after a "
-                "reconnect or to inspect outstanding work before deciding to repair."
+                "Read persisted verification gaps for a task WITHOUT re-running "
+                "verification. Returns a compact projection (IDs, severity, type, "
+                "file/line) within a ~32 KB context budget; use get_task for full "
+                "detail. Cheap and idempotent for resume/repair decisions."
             ),
             inputSchema={
                 "type": "object",
@@ -66,9 +71,10 @@ def all_tools() -> list[Tool]:
         Tool(
             name="devcouncil_get_next_actions",
             description=(
-                "Get the typed, machine-routable next-actions contract for a task from "
-                "its persisted gaps, WITHOUT re-verifying. Returns blocking next_actions "
-                "plus advisory_actions and the tools allowed next."
+                "Get the typed next-actions contract for a task from persisted gaps, "
+                "WITHOUT re-verifying. Compact by default (gap_id/category/action/file; "
+                "~32 KB context budget). Returns blocking next_actions, advisory_actions, "
+                "and allowed_next_tools."
             ),
             inputSchema={
                 "type": "object",
@@ -166,7 +172,11 @@ def all_tools() -> list[Tool]:
         ),
         Tool(
             name="devcouncil_list_tasks",
-            description="List DevCouncil tasks with status and requirement mappings. Supports a status filter and limit/offset paging so large projects don't blow the agent's context.",
+            description=(
+                "List DevCouncil tasks as compact rows (id/title/status/priority/"
+                "requirements/lease) within a ~32 KB context budget. Supports status "
+                "filter and limit/offset paging; use get_task for full detail."
+            ),
             inputSchema={
                 "type": "object",
                 "properties": {
@@ -710,13 +720,21 @@ def all_tools() -> list[Tool]:
                 "Read a repository file (read-only, no lease required) so an MCP-only "
                 "agent can inspect content before constructing a diff or overwriting it. "
                 "Containment-checked against the project root and refuses secret/credential "
-                "paths. Supports offset/limit or line_range windowing. Returns content "
-                "(truncated), sha256, and line_count."
+                "paths. When task_id is set, the path must intersect that task's planned "
+                "files (fail-closed; never broadens scope). Supports offset/limit or "
+                "line_range windowing. Returns content (truncated), sha256, and line_count."
             ),
             inputSchema={
                 "type": "object",
                 "properties": {
                     "path": {"type": "string", "description": "Repository-relative or absolute path inside the project."},
+                    "task_id": {
+                        "type": "string",
+                        "description": (
+                            "Optional task scope. When set, only planned-file paths for "
+                            "that task may be read."
+                        ),
+                    },
                     "offset": {"type": "integer", "minimum": 0, "description": "0-based line offset to start from."},
                     "limit": {"type": "integer", "minimum": 1, "description": "Max number of lines to return."},
                     "line_range": {

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

@@ -10,6 +10,7 @@ from devcouncil.integrations.mcp.util import (
     error_text,
     json_text,
     optional_string_argument,
+    parse_cli_json,
     run_cli_command,
     truncate_text,
 )
@@ -29,18 +30,10 @@ def _apply_body_truncation(payload: dict) -> dict:
 async def handle_wiki_page(root: Path, arguments: dict) -> list[TextContent]:
     page = optional_string_argument(arguments, "page")
     query = optional_string_argument(arguments, "query")
-    result = run_cli_command(
-        _wiki_cli_args(page=page, query=query),
-        root,
+    payload, _cli_error = parse_cli_json(
+        run_cli_command(_wiki_cli_args(page=page, query=query), root, truncate=False),
     )
-    if result.get("ok"):
-        import json
-
-        try:
-            payload = json.loads(str(result.get("stdout") or "{}"))
-        except json.JSONDecodeError:
-            payload = read_wiki_page(root, page=page, query=query)
-    else:
+    if payload is None:
         payload = read_wiki_page(root, page=page, query=query)
     if not payload.get("ok", True):
         return error_text(

package/src/devcouncil/integrations/mcp/server.py

@@ -329,7 +329,7 @@ async def call_tool(name: str, arguments: dict) -> list[TextContent]:
         return await handoff_handlers.handle_handoff_agent(root, db, arguments)
 
     if name == "devcouncil_read_file":
-        return await read_handlers.handle_read_file(root, arguments)
+        return await read_handlers.handle_read_file(root, arguments, db=db)
 
     if name == "devcouncil_get_diff":
         return await git_handlers.handle_get_diff(root, db, arguments)

package/src/devcouncil/integrations/mcp/util.py

@@ -243,7 +243,24 @@ def parse_cli_json(result: dict[str, object]) -> tuple[dict | None, list[TextCon
     return None, error_text("CLI command returned invalid JSON", code="cli_parse_error")
 
 
-def run_cli_command(args: list[str], root: Path) -> dict[str, object]:
+def _cli_stream_text(value: str | bytes | None, *, truncate: bool) -> tuple[str, bool]:
+    """Optionally truncate a CLI stream for external raw-text boundaries."""
+    if truncate:
+        return truncate_text(value)
+    if value is None:
+        return "", False
+    if isinstance(value, bytes):
+        return value.decode("utf-8", errors="replace"), False
+    return value, False
+
+
+def run_cli_command(args: list[str], root: Path, *, truncate: bool = False) -> dict[str, object]:
+    """Run ``devcouncil`` CLI and return a structured subprocess payload.
+
+    By default stdout/stderr are kept intact so structured JSON handlers can
+    parse large payloads. Pass ``truncate=True`` only for external raw-text
+    surfaces such as ``devcouncil_cli`` and report previews.
+    """
     command = [sys.executable, "-m", "devcouncil", *args, "--project-root", str(root)]
     try:
         result = subprocess.run(
@@ -255,8 +272,8 @@ def run_cli_command(args: list[str], root: Path) -> dict[str, object]:
             errors="replace",
             timeout=_CLI_TIMEOUT_SECONDS,
         )
-        stdout, stdout_truncated = truncate_text(result.stdout)
-        stderr, stderr_truncated = truncate_text(result.stderr)
+        stdout, stdout_truncated = _cli_stream_text(result.stdout, truncate=truncate)
+        stderr, stderr_truncated = _cli_stream_text(result.stderr, truncate=truncate)
         return {
             "ok": result.returncode == 0,
             "returncode": result.returncode,
@@ -267,8 +284,8 @@ def run_cli_command(args: list[str], root: Path) -> dict[str, object]:
             "timed_out": False,
         }
     except subprocess.TimeoutExpired as exc:
-        stdout, stdout_truncated = truncate_text(exc.output)
-        stderr, stderr_truncated = truncate_text(exc.stderr)
+        stdout, stdout_truncated = _cli_stream_text(exc.output, truncate=truncate)
+        stderr, stderr_truncated = _cli_stream_text(exc.stderr, truncate=truncate)
         return {
             "ok": False,
             "returncode": None,
@@ -281,6 +298,11 @@ def run_cli_command(args: list[str], root: Path) -> dict[str, object]:
         }
 
 
+def run_cli_json(args: list[str], root: Path) -> tuple[dict | None, list[TextContent] | None]:
+    """Run CLI without truncating stdout, then parse structured JSON."""
+    return parse_cli_json(run_cli_command(args, root, truncate=False))
+
+
 GIT_APPLY_TIMEOUT_SECONDS = _GIT_APPLY_TIMEOUT_SECONDS
 
 

package/src/devcouncil/live/summary.py

@@ -3,17 +3,35 @@ from __future__ import annotations
 from pathlib import Path
 
 from devcouncil.live.cards import load_cards, unresolved_blocking_cards
-from devcouncil.live.signals import load_signals
+from devcouncil.live.signals import ReviewSignal, load_signals
 from devcouncil.live.tasks import active_task_id
 
 
-def live_review_summary(project_root: Path, task_id: str | None = None) -> dict:
+def _compact_signal_item(signal: ReviewSignal) -> dict:
+    """IDs/counts-safe projection for general status (no PII / absolute paths)."""
+    signal_id = Path(signal.path).name if signal.path else None
+    return {
+        "id": signal_id,
+        "client": signal.client,
+        "task_id": signal.task_id,
+    }
+
+
+def live_review_summary(
+    project_root: Path,
+    task_id: str | None = None,
+    *,
+    include_signal_details: bool = False,
+) -> dict:
     cards = load_cards(project_root)
     signals = load_signals(project_root)
     active_id = active_task_id(project_root)
     scoped_task_id = task_id or active_id
     blockers = unresolved_blocking_cards(project_root, task_id=scoped_task_id, cards=cards)
-    pending_signal_items = [signal.model_dump() for signal in signals]
+    if include_signal_details:
+        pending_signal_items = [signal.model_dump() for signal in signals]
+    else:
+        pending_signal_items = [_compact_signal_item(signal) for signal in signals]
     open_count = 0
     resolved_count = 0
     ignored_count = 0