devcouncil 0.2.0 → 0.3.1

package/src/devcouncil/execution/shell_session.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import logging
 import os
 import shlex
 import shutil
@@ -20,6 +21,8 @@ from devcouncil.storage.native import ShellCommandRepository, ShellSessionReposi
 from devcouncil.storage.repositories import EvidenceRepository, TaskRepository
 from devcouncil.telemetry.traces import TraceLogger
 
+logger = logging.getLogger(__name__)
+
 
 class ShellBackend:
     def run_command(self, command: str, cwd: Path, env: dict[str, str] | None = None) -> subprocess.CompletedProcess[str]:
@@ -137,6 +140,7 @@ class GuardedShellSession:
         stderr_path = self.log_dir / f"{self.task.id}-{log_id}.stderr.log"
 
         if decision.action == "deny":
+            logger.warning("Shell command DENIED for %s: %s (%s)", self.task.id, normalized, decision.reason)
             self._record_command(normalized, "denied", reason=decision.reason)
             TraceLogger(self.project_root).log_event(
                 "shell_command_denied",
@@ -152,9 +156,11 @@ class GuardedShellSession:
             )
             return 1
 
+        logger.info("Shell command for %s: %s", self.task.id, normalized)
         try:
             result = self.backend.run_command(normalized, self.project_root)
         except (NotImplementedError, FileNotFoundError, OSError) as exc:
+            logger.warning("Shell command could not run for %s: %s (%s)", self.task.id, normalized, exc)
             self._record_command(normalized, "denied", reason=str(exc))
             console.print(f"[red]Could not run '{normalized}':[/red] {exc}")
             return 1

package/src/devcouncil/execution/task_runner.py

@@ -5,8 +5,11 @@ import logging
 import re
 import shlex
 from pathlib import Path
-from typing import Literal, Optional
+from typing import Literal, Optional, TYPE_CHECKING
 from devcouncil.domain.task import Task
+
+if TYPE_CHECKING:
+    from devcouncil.app.config import DevCouncilConfig
 from devcouncil.execution.permissions import PermissionManager
 from devcouncil.domain.evidence import CommandResult
 from devcouncil.app.errors import ExecutionError
@@ -25,6 +28,16 @@ class TaskRunner:
         self.project_root = project_root
         self.permissions = permission_manager
         self.patch_engine = PatchEngine(project_root)
+        # Load config and build the trace logger once: run_command previously
+        # re-parsed config.yaml on every command, and each operation rebuilt a
+        # TraceLogger. Both are reusable for the lifetime of the runner.
+        self.config: "Optional[DevCouncilConfig]"
+        try:
+            from devcouncil.app.config import load_config
+            self.config = load_config(project_root)
+        except Exception:
+            self.config = None
+        self.tracer = TraceLogger(project_root)
 
     def _validate_path_within_root(self, path: str) -> None:
         """Ensure a path resolves to a location within the project root."""
@@ -37,7 +50,7 @@ class TaskRunner:
             self._validate_path_within_root(path)
             self.permissions.validate_action("file_write", path, task, operation=operation)
         applied = self.patch_engine.apply_patch(patch)
-        TraceLogger(self.project_root).log_event(
+        self.tracer.log_event(
             "tool_patch_applied",
             {"paths": sorted(changes), "success": applied},
             task_id=task.id,
@@ -107,9 +120,7 @@ class TaskRunner:
         logger.info(f"Executing authorized command: {command}")
         
         try:
-            from devcouncil.app.config import load_config
-            config = load_config(self.project_root)
-            timeout = config.execution.command_timeout
+            timeout = self.config.execution.command_timeout if self.config is not None else 300
         except Exception:
             timeout = 300
 
@@ -133,7 +144,7 @@ class TaskRunner:
             stderr_path = self._save_command_log(task.id, command, "stderr", stderr)
             stdout_summary = redact_string(stdout[-500:])
             stderr_summary = redact_string(stderr[-500:])
-            TraceLogger(self.project_root).log_event(
+            self.tracer.log_event(
                 "command_executed",
                 {"command": command, "exit_code": result.returncode},
                 task_id=task.id,
@@ -160,7 +171,7 @@ class TaskRunner:
         try:
             full_path.parent.mkdir(parents=True, exist_ok=True)
             full_path.write_text(content, encoding="utf-8")
-            TraceLogger(self.project_root).log_event(
+            self.tracer.log_event(
                 "file_written",
                 {"path": path},
                 task_id=task.id,

package/src/devcouncil/executors/agent_registry.py

@@ -95,6 +95,11 @@ def normalize_agent_name(name: str) -> str:
 
 
 def resolve_cursor_agent_executable() -> str | None:
+    # NOTE: intentionally NOT lru_cached. It takes no project_root key, so a
+    # process-wide cache would leak one test's PATH probe (which the suite
+    # monkeypatches shutil.which to control) into the next, breaking isolation.
+    # The PATH search is two cheap shutil.which() calls; the dominant repeated
+    # cost (load_cli_agent_specs / config parsing) is cached instead.
     for candidate in ("cursor-agent", "agent"):
         if shutil.which(candidate):
             return candidate
@@ -246,8 +251,19 @@ def detect_available_coding_cli(
     project_root: Path,
     probe_order: tuple[str, ...] | None = None,
 ) -> str | None:
+    # Load specs once for the whole probe rather than per client (each
+    # resolve_coding_cli_executable() call would otherwise rebuild the spec
+    # table and re-parse config.yaml). Resolution below mirrors
+    # resolve_coding_cli_executable() exactly, just against the prebuilt table.
+    specs = load_cli_agent_specs(project_root)
     for client in probe_order or resolve_coding_cli_probe_order(project_root):
-        if resolve_coding_cli_executable(project_root, client):
+        normalized = normalize_agent_name(client)
+        if normalized == "cursor":
+            if resolve_cursor_agent_executable():
+                return client
+            continue
+        spec = specs.get(normalized)
+        if spec and shutil.which(spec.executable):
             return client
     return None
 
@@ -453,6 +469,11 @@ def builtin_agent_specs(project_root: Path) -> dict[str, CliAgentSpec]:
 
 
 def load_cli_agent_specs(project_root: Path) -> dict[str, CliAgentSpec]:
+    # NOTE: intentionally NOT cached. Callers (e.g. `setup` then `integrate
+    # doctor`) rewrite config.yaml for the same project_root within a single
+    # process and expect the next load to reflect it, so this must stay a live
+    # read. The repeated-reload hot path (the CLI probe loop) instead hoists a
+    # single load — see detect_available_coding_cli.
     specs = builtin_agent_specs(project_root)
     try:
         configured = load_config(project_root).integrations.cli_agents.agents

package/src/devcouncil/executors/coding_cli.py

@@ -1,4 +1,5 @@
 import json
+import logging
 import os
 import queue
 import shutil
@@ -9,12 +10,13 @@ import time
 import uuid
 from datetime import datetime, timezone
 from pathlib import Path
+from typing import Optional
 
 from rich.console import Console
 
 from devcouncil.domain.requirement import Requirement
 from devcouncil.domain.task import Task
-from devcouncil.app.config import load_config
+from devcouncil.app.config import DevCouncilConfig, load_config
 from devcouncil.execution.executor import Executor, ExecutionResult
 from devcouncil.execution.prompt_builder import PromptBuilder
 from devcouncil.executors.agent_registry import (
@@ -27,9 +29,17 @@ from devcouncil.executors.agent_registry import (
 )
 from devcouncil.repo.gitignore import ensure_gitignore
 from devcouncil.telemetry.traces import TraceLogger
+from devcouncil.telemetry.logging_setup import run_log
 from devcouncil.utils.redaction import redact_text
 
 console = Console()
+logger = logging.getLogger(__name__)
+
+# DevCouncil-managed scaffolding `dev` writes into a workspace itself (agent guides, the
+# managed .gitignore). The pre-verify scope gate must never revert these — they are not
+# task work, and reverting them would undo `dev`'s own setup. .devcouncil/* is handled
+# by a prefix check at the call site.
+_SCAFFOLDING_PATHS = frozenset({"AGENTS.md", "AGENTS.json", "CLAUDE.md", ".gitignore"})
 
 
 class CodingCliExecutor(Executor):
@@ -44,6 +54,14 @@ class CodingCliExecutor(Executor):
         stream_output: bool | None = None,
     ):
         self.project_root = project_root
+        # Load the project config once per executor instance. The same handle is
+        # reused by _resolve_stream_output, _cursor_resume_mode and the Warp
+        # command builder, which would otherwise each re-parse config.yaml.
+        self._config: Optional[DevCouncilConfig]
+        try:
+            self._config = load_config(project_root)
+        except Exception:
+            self._config = None
         self.client = self._normalize_client(client)
         self.timeout_seconds = timeout_seconds
         self.spec = self._resolve_spec()
@@ -66,7 +84,9 @@ class CodingCliExecutor(Executor):
         if stream_output is not None:
             return stream_output
         try:
-            return bool(load_config(self.project_root).execution.stream_cli_output)
+            if self._config is None:
+                return False
+            return bool(self._config.execution.stream_cli_output)
         except Exception:
             return False
 
@@ -193,8 +213,10 @@ class CodingCliExecutor(Executor):
 
     def _load_warp_config(self) -> dict:
         try:
-            warp = load_config(self.project_root).integrations.warp
-            data = warp.model_dump()
+            if self._config is None:
+                data = {}
+            else:
+                data = self._config.integrations.warp.model_dump()
         except Exception:
             data = {}
         if command := os.environ.get("DEVCOUNCIL_WARP_COMMAND"):
@@ -210,12 +232,15 @@ class CodingCliExecutor(Executor):
         return data
 
     def run_task(self, task: Task, requirements: list[Requirement]) -> ExecutionResult:
+        logger.info("coding_cli.run_task: client=%s profile=%s task=%s", self.client, self.profile_name, task.id)
         if self.profile is None:
+            logger.error("Unknown agent profile %r for %s; cannot start.", self.profile_name, self.client)
             return ExecutionResult(
                 success=False,
                 message=f"Unknown agent profile '{self.profile_name}' for {self.client}.",
             )
         if self.spec.input_mode not in VALID_INPUT_MODES:
+            logger.error("Invalid input_mode %r for %s; cannot start.", self.spec.input_mode, self.client)
             return ExecutionResult(
                 success=False,
                 message=(
@@ -229,10 +254,12 @@ class CodingCliExecutor(Executor):
         try:
             command = self._command(task.id)
         except ValueError as exc:
+            logger.error("Failed to build %s command for %s: %s", self.client, task.id, exc)
             return ExecutionResult(success=False, message=str(exc))
 
         executable = command[0]
         if not shutil.which(executable):
+            logger.error("%s CLI executable %r not found on PATH.", self.client, executable)
             return ExecutionResult(
                 success=False,
                 message=f"{self.client} CLI is not installed or not on PATH.",
@@ -263,6 +290,12 @@ class CodingCliExecutor(Executor):
         console.print(f"Starting [bold]{self.client.upper()}[/bold] for task [bold]{task.id}[/bold]...")
         console.print(f"Task prompt: [dim]{instruction_file}[/dim]")
 
+        # Isolate this run's full DEBUG trail in its own run-dir log, on top of the
+        # always-on shared devcouncil.log, so an agent run can be inspected end-to-end
+        # without grepping across unrelated activity / log rotations.
+        run_log_cm = run_log(self.project_root / ".devcouncil" / "runs" / run_id / "run.log")
+        run_log_cm.__enter__()
+
         started = time.monotonic()
         try:
             invocation, input_text = self._invocation(command, prompt, instruction_file)
@@ -296,8 +329,10 @@ class CodingCliExecutor(Executor):
                 else None
             )
             started = time.monotonic()
+            logger.info("Launching %s subprocess for %s (timeout=%ss)", self.client, task.id, self._effective_timeout())
             result = self._run_subprocess(invocation, input_text, env, transcript_path=transcript_path)
             duration = round(time.monotonic() - started, 3)
+            logger.info("%s subprocess for %s exited %s in %.2fs", self.client, task.id, result.returncode, duration)
             finished_at = datetime.now(timezone.utc).isoformat()
             self._write_log(log_prefix, result)
             if transcript_path and transcript_path.exists():
@@ -316,6 +351,7 @@ class CodingCliExecutor(Executor):
                 )
                 stderr_preview = (result.stderr or result.stdout or "").strip().splitlines()[:5]
                 detail = redact_text(stderr_preview[0]) if stderr_preview else "No diagnostics were produced."
+                logger.error("%s exited %s for %s: %s", self.client, result.returncode, task.id, detail)
                 TraceLogger(self.project_root).log_event(
                     "agent_run_failed",
                     {"agent": self.client, "profile": self.profile_name, "returncode": result.returncode, "detail": detail},
@@ -343,8 +379,31 @@ class CodingCliExecutor(Executor):
                 task_id=task.id,
                 summary=f"{self.client} finished for {task.id}",
             )
+            # Opt-in pre-verify scope gate: this CLI subprocess wrote directly to disk with
+            # no per-write hook, so revert any out-of-scope change now (before it reaches the
+            # verify gate or a commit) rather than only flagging it as orphan_diff post-verify.
+            if self._scope_enforcement_enabled():
+                reverted = self._enforce_file_scope(task)
+                if reverted:
+                    files = ", ".join(path for path, _ in reverted)
+                    TraceLogger(self.project_root).log_event(
+                        "agent_scope_violation_reverted",
+                        {"agent": self.client, "task_id": task.id,
+                         "reverted": [{"path": p, "reason": r} for p, r in reverted]},
+                        run_id=run_id,
+                        task_id=task.id,
+                        summary=f"Reverted {len(reverted)} out-of-scope change(s) by {self.client}",
+                    )
+                    return ExecutionResult(
+                        success=False,
+                        message=(
+                            f"Reverted {len(reverted)} out-of-scope file change(s) the task did not "
+                            f"authorize: {files}. Re-run keeping edits within the task's allowed files."
+                        ),
+                    )
             return ExecutionResult(success=True, message=f"{self.client} execution finished.")
         except subprocess.TimeoutExpired:
+            logger.error("%s timed out after %ss for %s", self.client, self._effective_timeout(), task.id)
             self._update_run_manifest(
                 run_id,
                 status="timeout",
@@ -363,6 +422,7 @@ class CodingCliExecutor(Executor):
                 message=f"{self.client} execution timed out after {self._effective_timeout()}s.",
             )
         except Exception as exc:
+            logger.exception("%s execution raised for %s: %s", self.client, task.id, exc)
             self._update_run_manifest(
                 run_id,
                 status="failed",
@@ -372,6 +432,71 @@ class CodingCliExecutor(Executor):
                 duration_seconds=round(time.monotonic() - started, 3),
             )
             return ExecutionResult(success=False, message=str(exc))
+        finally:
+            run_log_cm.__exit__(None, None, None)
+
+    def _scope_enforcement_enabled(self) -> bool:
+        try:
+            from devcouncil.app.config import load_config
+            return bool(load_config(self.project_root).execution.enforce_file_scope_pre_verify)
+        except Exception:
+            return False
+
+    def _enforce_file_scope(self, task: Task) -> list[tuple[str, str]]:
+        """Revert any file this task's subprocess changed that the task does not authorize.
+
+        Uses the task's net changed files (baseline/snapshot subtracted, DevCouncil-managed
+        paths already filtered) and the same policy the hook path enforces. Returns the list
+        of ``(path, reason)`` reverted; empty when every change was in scope."""
+        try:
+            from devcouncil.execution.policy_engine import TaskPolicyEngine
+            from devcouncil.verification.verifier import Verifier
+
+            changed = Verifier(self.project_root).get_task_changed_files(task.id)
+        except Exception:
+            return []
+        engine = TaskPolicyEngine(self.project_root)
+        reverted: list[tuple[str, str]] = []
+        for path in changed:
+            # Never touch DevCouncil-managed scaffolding even if it surfaces in the diff
+            # (e.g. baseline snapshots failed to load): `dev` owns these files, not the task.
+            if path in _SCAFFOLDING_PATHS or path.startswith(".devcouncil/"):
+                continue
+            try:
+                decision = engine.evaluate_file_change(path, task, "write")
+            except Exception:
+                continue
+            if decision.action == "deny" and self._revert_path(path):
+                reverted.append((path, decision.reason))
+        return reverted
+
+    def _revert_path(self, rel_path: str) -> bool:
+        """Undo an out-of-scope change. A file that exists in HEAD is restored to HEAD; a
+        file the task newly added (absent from HEAD, or no HEAD at all) is unstaged and
+        deleted. Best-effort — a failed revert returns False so the path is not reported as
+        cleanly gated (and the caller does not claim it was reverted)."""
+        try:
+            in_head = subprocess.run(
+                ["git", "cat-file", "-e", f"HEAD:{rel_path}"],
+                cwd=self.project_root, capture_output=True, text=True,
+            ).returncode == 0
+            if in_head:
+                return subprocess.run(
+                    ["git", "checkout", "HEAD", "--", rel_path],
+                    cwd=self.project_root, capture_output=True, text=True,
+                ).returncode == 0
+            # New file (incl. the no-HEAD case): unstage if staged, then remove the working
+            # copy so it cannot be committed by the next repair attempt.
+            subprocess.run(
+                ["git", "rm", "-f", "--cached", "--ignore-unmatch", rel_path],
+                cwd=self.project_root, capture_output=True, text=True,
+            )
+            full = self.project_root / rel_path
+            if full.is_file():
+                full.unlink()
+            return True
+        except Exception:
+            return False
 
     def _resolve_invocation(self, invocation: list[str], env: dict[str, str]) -> list[str]:
         """Route Windows batch shims through the command interpreter.
@@ -520,7 +645,10 @@ class CodingCliExecutor(Executor):
 
     def _cursor_resume_mode(self) -> str:
         try:
-            mode = (load_config(self.project_root).execution.cursor_resume_mode or "off").strip().lower()
+            if self._config is None:
+                mode = "off"
+            else:
+                mode = (self._config.execution.cursor_resume_mode or "off").strip().lower()
         except Exception:
             mode = "off"
         if mode not in {"off", "project", "task"}:

package/src/devcouncil/executors/mini_swe.py

@@ -1,3 +1,4 @@
+import logging
 import subprocess
 import sys
 from pathlib import Path
@@ -8,6 +9,7 @@ from devcouncil.execution.executor import Executor, ExecutionResult
 from devcouncil.execution.prompt_builder import PromptBuilder
 
 console = Console()
+logger = logging.getLogger(__name__)
 
 class MiniSWEExecutor(Executor):
     def __init__(self, project_root: Path):
@@ -22,6 +24,7 @@ class MiniSWEExecutor(Executor):
         instruction_file.parent.mkdir(parents=True, exist_ok=True)
         instruction_file.write_text(task_prompt, encoding="utf-8")
         
+        logger.info("mini-SWE-agent starting for %s", task.id)
         console.print(f"Starting [bold]mini-SWE-agent[/bold] for task {task.id}...")
         
         # In a real implementation, we'd invoke the agent CLI
@@ -50,10 +53,13 @@ class MiniSWEExecutor(Executor):
             )
             self._write_log(task.id, result)
             if result.returncode != 0:
+                logger.error("mini-SWE-agent exited %s for %s", result.returncode, task.id)
                 console.print(f"[red]mini-SWE-agent exited with {result.returncode}.[/red]")
                 return ExecutionResult(success=False, message='Execution failed')
+            logger.info("mini-SWE-agent finished for %s", task.id)
             return ExecutionResult(success=True, message='Execution successful')
         except Exception as e:
+            logger.exception("mini-SWE-agent error for %s: %s", task.id, e)
             console.print(f"[red]Error running mini-SWE-agent: {e}[/red]")
             return ExecutionResult(success=False, message='Execution failed')
 

package/src/devcouncil/executors/native/agent.py

@@ -1,5 +1,6 @@
 from typing import List, Dict, Any
 import asyncio
+import logging
 from rich.console import Console
 from pydantic import BaseModel
 from devcouncil.domain.task import Task
@@ -13,6 +14,7 @@ from devcouncil.execution.paths import resolve_project_path
 from devcouncil.app.errors import ExecutionError
 
 console = Console()
+logger = logging.getLogger(__name__)
 
 # Resilience bounds for the preview native loop.
 MAX_AGENT_STEPS = 10
@@ -44,6 +46,7 @@ class NativeAgent(Executor):
         return asyncio.run(self._run_task_async(task, requirements))
 
     async def _run_task_async(self, task: Task, requirements: List[Requirement]) -> ExecutionResult:
+        logger.info("Native agent starting for %s (max_steps=%d)", task.id, MAX_AGENT_STEPS)
         console.print(f"Starting [bold]Native Executor[/bold] for task {task.id}...")
         console.print("[yellow]Native executor is preview quality; DevCouncil verification remains the completion gate.[/yellow]")
         
@@ -96,8 +99,10 @@ Rules:
                 # native_agent has no fallback by design, so handle it here rather than
                 # letting it propagate and abort the entire `dev go` run.
                 structured_failures += 1
+                logger.warning("Native agent step %d: unparseable action (%d/%d): %s", step + 1, structured_failures, MAX_STRUCTURED_FAILURES, exc)
                 console.print(f"[red]Native agent could not parse a valid action: {exc}[/red]")
                 if structured_failures >= MAX_STRUCTURED_FAILURES:
+                    logger.error("Native agent giving up on %s after %d unparseable responses", task.id, structured_failures)
                     return ExecutionResult(
                         success=False,
                         message=f"Native agent gave up after {structured_failures} unparseable responses.",
@@ -113,6 +118,11 @@ Rules:
                 continue
             structured_failures = 0
 
+            logger.info(
+                "Native agent %s step %d/%d: %d tool call(s)%s",
+                task.id, step + 1, MAX_AGENT_STEPS, len(action.tool_calls),
+                " finish=True" if action.finish else "",
+            )
             console.print(f"\n[bold]Step {step+1}:[/bold] {action.thought}")
 
             # Record the agent's own turn so subsequent steps see what it already did.
@@ -121,6 +131,7 @@ Rules:
             messages.append({"role": "assistant", "content": action.model_dump_json()})
 
             if action.finish:
+                logger.info("Native agent signaled completion for %s at step %d", task.id, step + 1)
                 console.print("[green]Native agent signaled completion.[/green]")
                 return ExecutionResult(success=True, message="Agent signaled completion; pending DevCouncil verification")
 
@@ -135,6 +146,7 @@ Rules:
 
             for tool_call in action.tool_calls:
                 result_summary = ""
+                logger.debug("Native agent tool call: %s args=%s", tool_call.tool, list(tool_call.args))
                 try:
                     if tool_call.tool == "read_file":
                         path = tool_call.args["path"]
@@ -183,10 +195,12 @@ Rules:
                     
                     messages.append({"role": "user", "content": f"[Tool Result] '{tool_call.tool}': {result_summary}"})
                 except Exception as e:
+                    logger.warning("Native agent tool %s failed for %s: %s", tool_call.tool, task.id, e)
                     console.print(f"[red]Error executing tool {tool_call.tool}: {e}[/red]")
                     if tool_call.tool == "apply_patch":
                         consecutive_patch_failures += 1
                         if consecutive_patch_failures >= MAX_CONSECUTIVE_PATCH_FAILURES:
+                            logger.error("Native agent giving up on %s after %d consecutive patch failures", task.id, consecutive_patch_failures)
                             return ExecutionResult(
                                 success=False,
                                 message=(
@@ -204,5 +218,6 @@ Rules:
                     else:
                         messages.append({"role": "user", "content": f"[Tool Error] '{tool_call.tool}' failed: {e}"})
 
+        logger.warning("Native agent reached max step limit (%d) for %s", MAX_AGENT_STEPS, task.id)
         console.print("[red]Native agent reached maximum step limit.[/red]")
         return ExecutionResult(success=False, message="Reached maximum step limit")

package/src/devcouncil/executors/openhands.py

@@ -1,3 +1,4 @@
+import logging
 import subprocess
 from pathlib import Path
 from rich.console import Console
@@ -7,6 +8,7 @@ from devcouncil.execution.executor import Executor, ExecutionResult
 from devcouncil.execution.prompt_builder import PromptBuilder
 
 console = Console()
+logger = logging.getLogger(__name__)
 
 class OpenHandsExecutor(Executor):
     def __init__(self, project_root: Path):
@@ -16,6 +18,7 @@ class OpenHandsExecutor(Executor):
         builder = PromptBuilder(self.project_root)
         task_prompt = builder.build_task_prompt(task, requirements)
         
+        logger.info("OpenHands starting for %s", task.id)
         console.print(f"Starting [bold]OpenHands[/bold] for task {task.id}...")
         
         # OpenHands often expects a workspace mount and an instruction.
@@ -48,10 +51,13 @@ class OpenHandsExecutor(Executor):
             )
             self._write_log(task.id, result)
             if result.returncode != 0:
+                logger.error("OpenHands exited %s for %s", result.returncode, task.id)
                 console.print(f"[red]OpenHands exited with {result.returncode}.[/red]")
                 return ExecutionResult(success=False, message=f"Exited with code {result.returncode}")
+            logger.info("OpenHands finished for %s", task.id)
             return ExecutionResult(success=True, message="Completed successfully")
         except Exception as e:
+            logger.exception("OpenHands error for %s: %s", task.id, e)
             console.print(f"[red]Error running OpenHands: {e}[/red]")
             return ExecutionResult(success=False, message=str(e))
 

package/src/devcouncil/gating/checks/secret_scan_check.py

@@ -1,8 +1,11 @@
+import logging
 import re
 from typing import List
 from devcouncil.domain.gap import Gap
 from devcouncil.utils.redaction import SECRET_PATTERNS, redact_string
 
+logger = logging.getLogger(__name__)
+
 # Captures the new-file starting line from a unified-diff hunk header (@@ -a,b +c,d @@).
 _HUNK_RE = re.compile(r"^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@")
 
@@ -32,6 +35,10 @@ class SecretScanner:
                 for key_type, pattern in SECRET_PATTERNS.items():
                     if pattern.search(line):
                         counter += 1
+                        logger.warning(
+                            "Potential %s secret detected in %s:%d (task %s)",
+                            key_type, current_file, new_line_no, task_id,
+                        )
                         gaps.append(Gap(
                             id=f"GAP-{task_id}-SECRET-{key_type.upper()}-{new_line_no}-{counter}",
                             severity="critical",

package/src/devcouncil/gating/policy.py

@@ -1,3 +1,5 @@
+import logging
+from collections import deque
 from pydantic import BaseModel
 from typing import Any, List, Optional
 from pathlib import Path
@@ -11,6 +13,32 @@ from devcouncil.gating.checks.requirement_coverage import RequirementCoverageChe
 from devcouncil.gating.checks.planned_files_check import PlannedFilesCheck
 from devcouncil.gating.checks.clean_git import CleanGitCheck
 
+logger = logging.getLogger(__name__)
+
+
+def _log_gate(name: str, gaps: List[Gap], *, routine: bool = False, **context: Any) -> bool:
+    """Log a gate decision and return whether it passed (no blocking gaps).
+
+    A passing gate is logged at INFO for once-per-plan checks (a real milestone) but at
+    DEBUG for ``routine`` per-task checks (e.g. task_ready, which fires for every task and
+    every repair attempt) so the ``-v`` stream stays milestone-level. A FAILED gate is
+    always WARNING — that's the signal you actually chase.
+    """
+    blocking = [g for g in gaps if g.blocking]
+    passed = not blocking
+    suffix = "".join(f" {k}={v}" for k, v in context.items())
+    if passed:
+        log = logger.debug if routine else logger.info
+        log("Gate %s PASSED (%d advisory gap(s))%s", name, len(gaps), suffix)
+    else:
+        logger.warning(
+            "Gate %s FAILED%s: %s",
+            name, suffix,
+            "; ".join(f"{g.gap_type}: {g.description}" for g in blocking),
+        )
+    return passed
+
+
 class GateResult(BaseModel):
     passed: bool
     gaps: List[Gap]
@@ -60,10 +88,10 @@ def topological_order(tasks: List[Task]) -> List[Task]:
                 indegree[task.id] += 1
                 dependents[dep].append(task.id)
     # Kahn's algorithm, seeded in original order for stability.
-    ready = [t.id for t in tasks if indegree[t.id] == 0]
+    ready = deque(t.id for t in tasks if indegree[t.id] == 0)
     ordered: List[str] = []
     while ready:
-        current = ready.pop(0)
+        current = ready.popleft()
         ordered.append(current)
         for child in dependents[current]:
             indegree[child] -= 1
@@ -192,13 +220,16 @@ class GatePolicy:
         # earlier one (e.g. both add the same function), which then fails per-task
         # verification. Consolidating a file's work into one task avoids this.
         writers_by_file: dict[str, list[str]] = {}
+        writer_sets: dict[str, set[str]] = {}
         for task in tasks:
             for pf in task.planned_files:
                 if pf.allowed_change in ("create", "modify", "delete"):
                     path = pf.path.replace("\\", "/")
-                    writers_by_file.setdefault(path, [])
-                    if task.id not in writers_by_file[path]:
-                        writers_by_file[path].append(task.id)
+                    owners = writers_by_file.setdefault(path, [])
+                    seen = writer_sets.setdefault(path, set())
+                    if task.id not in seen:
+                        seen.add(task.id)
+                        owners.append(task.id)
         for path, owners in writers_by_file.items():
             if len(owners) > 1:
                 gaps.append(Gap(
@@ -262,7 +293,7 @@ class GatePolicy:
             ))
 
         return GateResult(
-            passed=len([g for g in gaps if g.blocking]) == 0, 
+            passed=_log_gate("plan_approval", gaps),
             gaps=gaps
         )
 
@@ -305,7 +336,7 @@ class GatePolicy:
             ))
 
         return GateResult(
-            passed=len([g for g in gaps if g.blocking]) == 0,
+            passed=_log_gate("task_ready", gaps, routine=True, task_id=task.id),
             gaps=gaps
         )