devcouncil 0.3.1 → 0.4.0

package/src/devcouncil/campaign/prompts/reviewer.md

@@ -0,0 +1,24 @@
+# Reviewer — Reviewer (quality control)
+
+You are a thinker, not a doer. You judge the work and you shape the strategy.
+
+## Duties
+
+- **Quality-control** every task the Worker finish, through the DevCouncil
+  **Verifier** (`verify_task`). Report each as *verified* or *blocked* with the
+  blocking gaps named.
+- Own the hard cognition — Bloom **Analyze / Evaluate / Create**: architecture,
+  root-cause analysis, evaluation, and strategy planning.
+- **Aggregate** the verdicts and report up to the **Coordinator**.
+
+## Forbidden
+
+- **Never manage the Worker** — you review their output, you do not command them.
+- **Never report directly to the Director** — everything goes through the Coordinator.
+- **Never implement** the fix yourself — name the gap; the Coordinator re-dispatches.
+- **Never contact the operator.**
+
+## Style
+
+Measured and analytical. "The gate holds on three counts; two gaps remain. Coordinator,
+re-dispatch task T-004."

package/src/devcouncil/campaign/prompts/worker.md

@@ -0,0 +1,24 @@
+# Worker — Worker (worker)
+
+You are the front line. You take one task and you finish it.
+
+## Duties
+
+- Execute the **single** task the Coordinator assigned to you, through your coding
+  executor (`CodingCliExecutor` or the native agent). Stay strictly inside the
+  task's `planned_files`, `allowed_commands` and `forbidden_changes`.
+- When done, **self-review** against the parent command's intent.
+- Write a completion report (`queue`/mailbox `report_received`) and notify the
+  **Reviewer** — not the Coordinator — for quality control.
+- Then check your own mailbox for the next order.
+
+## Forbidden
+
+- **Never QC your own work** — that is the Reviewer's job.
+- **Never touch another Worker's task or files.**
+- **Never contact the operator.**
+- **Never poll** — act only when nudged.
+
+## Style
+
+Eager and brief. "Hah! The task is complete — Reviewer, I await your judgement."

package/src/devcouncil/campaign/roles.py

@@ -0,0 +1,202 @@
+"""The Director command hierarchy — ranks, duties, and enforceable boundaries.
+
+Each :class:`Role` couples a rank to the *actions it is permitted to take*. The
+original encodes "who may do what / who may never do what" as prose in role
+markdown; here that contract is also machine-checkable via
+:func:`assert_allowed`, so the orchestrator can hard-enforce the chain of
+command (only the Coordinator writes the dashboard, only the Reviewer performs QC, an
+Worker never reviews its own work, and so on) rather than trusting a prompt.
+
+The human-readable persona/duty text still lives in ``prompts/<rank>.md`` and is
+surfaced by :func:`load_role_instructions` for injection into an agent's
+context.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import Dict, FrozenSet, List
+
+_PROMPTS_DIR = Path(__file__).parent / "prompts"
+
+
+class Rank(str, Enum):
+    """A position in the command hierarchy."""
+
+    DIRECTOR = "director"
+    COORDINATOR = "coordinator"
+    WORKER = "worker"
+    REVIEWER = "reviewer"
+
+    def __str__(self) -> str:  # nicer CLI/log output
+        return self.value
+
+
+class Action(str, Enum):
+    """A discrete capability that a rank may or may not exercise."""
+
+    RELAY_ORDER = "relay_order"          # accept the operator's order, hand to Coordinator
+    READ_DASHBOARD = "read_dashboard"
+    APPROVE_SKILL = "approve_skill"
+    DECOMPOSE = "decompose"              # split an order into subtasks
+    ASSIGN = "assign"                    # dispatch a task to a worker
+    WRITE_DASHBOARD = "write_dashboard"  # sole right of the Coordinator
+    ROUTE_QC = "route_qc"                # send finished work to the Reviewer
+    ROLLUP = "rollup"                    # aggregate reports, decide done/blocked
+    NOTIFY = "notify"                    # push to the operator (ntfy / dashboard)
+    EXECUTE_TASK = "execute_task"        # actually do the work
+    SELF_REVIEW = "self_review"          # a worker's own sanity check
+    WRITE_REPORT = "write_report"        # a worker reporting completion
+    QC_REVIEW = "qc_review"              # quality control of another's work
+    DEEP_ANALYSIS = "deep_analysis"      # architecture / root-cause (Bloom L4-6)
+    AGGREGATE_REPORTS = "aggregate_reports"
+    CONTACT_HUMAN = "contact_human"      # only the Director/Coordinator may reach the operator
+
+
+class ForbiddenActionError(RuntimeError):
+    """Raised when a rank attempts an action outside its remit."""
+
+    def __init__(self, rank: "Rank", action: "Action"):
+        self.rank = rank
+        self.action = action
+        super().__init__(
+            f"{rank} is forbidden from '{action.value}' — it violates the role hierarchy"
+        )
+
+
+@dataclass(frozen=True)
+class Role:
+    """A rank plus its persona and the actions it is permitted to take."""
+
+    rank: Rank
+    title: str
+    summary: str
+    allowed: FrozenSet[Action]
+    reports_to: Rank | None
+    # Human-facing bullet duties, mirrored in prompts/<rank>.md for quick display.
+    duties: List[str] = field(default_factory=list)
+
+    def may(self, action: Action) -> bool:
+        return action in self.allowed
+
+    @property
+    def forbidden(self) -> FrozenSet[Action]:
+        return frozenset(Action) - self.allowed
+
+
+ROLES: Dict[Rank, Role] = {
+    Rank.DIRECTOR: Role(
+        rank=Rank.DIRECTOR,
+        title="Director ",
+        summary="Relays the operator's order to the Coordinator and steps back. Never works.",
+        allowed=frozenset(
+            {
+                Action.RELAY_ORDER,
+                Action.READ_DASHBOARD,
+                Action.APPROVE_SKILL,
+                Action.NOTIFY,
+                Action.CONTACT_HUMAN,
+            }
+        ),
+        reports_to=None,
+        duties=[
+            "Receive the operator's order and record it as a campaign command.",
+            "Hand the command to the Coordinator, then yield so the operator may issue more.",
+            "Read the dashboard; never write it, never execute a task, never bypass the Coordinator.",
+        ],
+    ),
+    Rank.COORDINATOR: Role(
+        rank=Rank.COORDINATOR,
+        title="Coordinator ",
+        summary="Decomposes the order, dispatches Worker in parallel, owns the dashboard.",
+        allowed=frozenset(
+            {
+                Action.DECOMPOSE,
+                Action.ASSIGN,
+                Action.WRITE_DASHBOARD,
+                Action.ROUTE_QC,
+                Action.ROLLUP,
+                Action.NOTIFY,
+                Action.READ_DASHBOARD,
+                Action.CONTACT_HUMAN,
+            }
+        ),
+        reports_to=Rank.DIRECTOR,
+        duties=[
+            "Decompose the command into subtasks and classify each by Bloom level.",
+            "Dispatch execution tasks to Worker in parallel; route analysis/QC to the Reviewer.",
+            "Own the dashboard and roll finished, verified work up to the Director.",
+            "Never do the work yourself — 'one Worker can do it all' is Coordinator laziness.",
+        ],
+    ),
+    Rank.WORKER: Role(
+        rank=Rank.WORKER,
+        title="Worker ",
+        summary="Runs exactly one task through a coding executor, then reports to the Reviewer.",
+        allowed=frozenset(
+            {
+                Action.EXECUTE_TASK,
+                Action.SELF_REVIEW,
+                Action.WRITE_REPORT,
+            }
+        ),
+        reports_to=Rank.REVIEWER,
+        duties=[
+            "Execute the single task assigned to you and nothing beyond its scope.",
+            "Self-review against the parent command, then write a completion report.",
+            "Notify the Reviewer for QC. Never QC your own work, never touch another's task, never poll.",
+        ],
+    ),
+    Rank.REVIEWER: Role(
+        rank=Rank.REVIEWER,
+        title="Reviewer ",
+        summary="A thinker, not a doer. Verifies finished work and handles Bloom L4-L6.",
+        allowed=frozenset(
+            {
+                Action.QC_REVIEW,
+                Action.DEEP_ANALYSIS,
+                Action.AGGREGATE_REPORTS,
+                Action.WRITE_REPORT,
+            }
+        ),
+        reports_to=Rank.COORDINATOR,
+        duties=[
+            "Quality-control Worker output through the DevCouncil Verifier.",
+            "Own architecture, root-cause and strategy work (Bloom Analyze/Evaluate/Create).",
+            "Aggregate verdicts and report up to the Coordinator. Never manage Worker, never implement.",
+        ],
+    ),
+}
+
+
+def get_role(rank: Rank | str) -> Role:
+    """Look up a :class:`Role` by rank (enum or string)."""
+    if isinstance(rank, str):
+        rank = Rank(rank)
+    return ROLES[rank]
+
+
+def assert_allowed(rank: Rank | str, action: Action) -> None:
+    """Raise :class:`ForbiddenActionError` if ``rank`` may not perform ``action``."""
+    role = get_role(rank)
+    if not role.may(action):
+        raise ForbiddenActionError(role.rank, action)
+
+
+def load_role_instructions(rank: Rank | str) -> str:
+    """Return the persona/duty markdown for ``rank`` (``prompts/<rank>.md``).
+
+    Falls back to a synthesised summary when the file is missing so the system is
+    resilient to a trimmed install.
+    """
+    if isinstance(rank, str):
+        rank = Rank(rank)
+    path = _PROMPTS_DIR / f"{rank.value}.md"
+    if path.exists():
+        return path.read_text(encoding="utf-8")
+    role = ROLES[rank]
+    lines = [f"# {role.title}", "", role.summary, ""]
+    lines += [f"- {duty}" for duty in role.duties]
+    return "\n".join(lines)

package/src/devcouncil/campaign/watcher.py

@@ -0,0 +1,153 @@
+"""Mailbox watcher — the "you have mail" nudge layer.
+
+In the original, one ``inotifywait``/``fswatch`` daemon per agent blocks on a
+kernel file-change event and, when the inbox changes, fires a content-free
+``inboxN`` keystroke into that agent's tmux pane. Message *content* never travels
+over the wire — only the wake-up.
+
+DevCouncil runs its agents in-process, so the "keystroke" becomes a Python
+callback: ``nudge(agent, unread_count)``. We still key off real filesystem
+events (via :mod:`watchdog`, already a DevCouncil dependency) so cross-process
+writers — e.g. a leased MCP agent appending to a mailbox — also wake the
+campaign. When watchdog is unavailable we fall back to a polling thread, and
+:meth:`MailboxWatcher.poll_once` lets a single-threaded orchestrator drive the
+same logic deterministically (and keeps unit tests free of timing races).
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import Any, Callable, Dict, Iterable, List, Optional
+
+from devcouncil.campaign.mailbox import Mailbox
+
+NudgeCallback = Callable[[str, int], None]
+
+try:  # watchdog is a declared dependency; degrade gracefully if it is missing.
+    from watchdog.events import FileSystemEventHandler
+    from watchdog.observers import Observer
+
+    _HAS_WATCHDOG = True
+except Exception:  # pragma: no cover - exercised only without watchdog
+    FileSystemEventHandler = object  # type: ignore[assignment,misc]
+    Observer = None  # type: ignore[assignment]
+    _HAS_WATCHDOG = False
+
+
+class MailboxWatcher:
+    """Watch a set of agent mailboxes and nudge on new unread mail.
+
+    Parameters
+    ----------
+    mailbox:
+        The shared :class:`~devcouncil.campaign.mailbox.Mailbox`.
+    agents:
+        Agent ids to watch.
+    nudge:
+        Called ``nudge(agent, unread_count)`` whenever an agent's unread count
+        rises. Never called with a count of zero.
+    poll_interval:
+        Seconds between scans on the polling fallback.
+    """
+
+    def __init__(
+        self,
+        mailbox: Mailbox,
+        agents: Iterable[str],
+        nudge: NudgeCallback,
+        poll_interval: float = 1.0,
+    ):
+        self.mailbox = mailbox
+        self.agents: List[str] = list(agents)
+        self.nudge = nudge
+        self.poll_interval = poll_interval
+        # Last unread count we nudged for, per agent — so a nudge fires on the
+        # *rising edge* only (0->N or N->N+1), never repeatedly for the same mail.
+        self._last: Dict[str, int] = {a: 0 for a in self.agents}
+        self._lock = threading.Lock()
+        self._observer: Any = None
+        self._stop = threading.Event()
+        self._poll_thread: Optional[threading.Thread] = None
+
+    # -- core logic ------------------------------------------------------------
+
+    def poll_once(self) -> List[str]:
+        """Scan all mailboxes once; nudge agents whose unread count rose.
+
+        Returns the list of agents nudged. Safe to call from any thread and from
+        tests; this is the single choke-point through which every nudge flows.
+        """
+        nudged: List[str] = []
+        with self._lock:
+            for agent in self.agents:
+                count = self.mailbox.count_unread(agent)
+                previous = self._last.get(agent, 0)
+                if count > previous and count > 0:
+                    self._last[agent] = count
+                    nudged.append(agent)
+                elif count < previous:
+                    # Agent drained its inbox; re-arm so the next arrival nudges.
+                    self._last[agent] = count
+        for agent in nudged:
+            self.nudge(agent, self.mailbox.count_unread(agent))
+        return nudged
+
+    def reset(self, agent: Optional[str] = None) -> None:
+        """Forget prior nudge state so the next scan re-nudges pending mail."""
+        with self._lock:
+            if agent is None:
+                self._last = {a: 0 for a in self.agents}
+            else:
+                self._last[agent] = 0
+
+    # -- background operation --------------------------------------------------
+
+    def start(self) -> None:
+        """Begin watching in the background (watchdog, or a polling thread)."""
+        self.mailbox.inbox_dir.mkdir(parents=True, exist_ok=True)
+        if _HAS_WATCHDOG and Observer is not None:
+            handler = _InboxEventHandler(self)
+            self._observer = Observer()
+            self._observer.schedule(handler, str(self.mailbox.inbox_dir), recursive=False)
+            self._observer.start()
+        else:  # pragma: no cover - fallback path
+            self._poll_thread = threading.Thread(target=self._poll_loop, daemon=True)
+            self._poll_thread.start()
+        # Deliver anything already waiting at startup.
+        self.poll_once()
+
+    def _poll_loop(self) -> None:  # pragma: no cover - timing loop
+        while not self._stop.wait(self.poll_interval):
+            self.poll_once()
+
+    def stop(self) -> None:
+        self._stop.set()
+        if self._observer is not None:
+            try:
+                self._observer.stop()
+                self._observer.join(timeout=2.0)
+            except Exception:
+                pass
+            self._observer = None
+        if self._poll_thread is not None:  # pragma: no cover
+            self._poll_thread.join(timeout=2.0)
+            self._poll_thread = None
+
+    def __enter__(self) -> "MailboxWatcher":
+        self.start()
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.stop()
+
+
+class _InboxEventHandler(FileSystemEventHandler):
+    """Translates filesystem change events into a debounced ``poll_once``."""
+
+    def __init__(self, watcher: MailboxWatcher):
+        self._watcher = watcher
+
+    def on_any_event(self, event: object) -> None:  # pragma: no cover - needs fs events
+        # A YAML write shows up as create/modify/moved on the atomic replace; we
+        # do not care which — a single re-scan reconciles all mailboxes.
+        self._watcher.poll_once()

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

@@ -22,9 +22,12 @@ from devcouncil.executors.agent_registry import (
     resolve_cursor_agent_executable,
 )
 from devcouncil.optimization.gepa_agent import GepaUnavailableError, optimize_agent_profile
+from devcouncil.telemetry.stages import log_stage, log_step
+import logging
 
 app = typer.Typer(help="Manage DevCouncil CLI agents.")
 console = Console()
+logger = logging.getLogger(__name__)
 
 
 @app.callback(invoke_without_command=True)
@@ -37,24 +40,28 @@ def list_agents(
         return
 
     root = _project_root(project_root)
-    table = Table(title="DevCouncil Agents")
-    table.add_column("Agent", style="cyan")
-    table.add_column("Type")
-    table.add_column("Command")
-    table.add_column("Profile")
-    table.add_column("MCP")
-    table.add_column("Diff Review")
+    logger.info("dev agents list")
+    with log_stage("agents", project_root=root, subcommand="list"):
+        log_step("agents/1: loading agent registry", project_root=root, trace=True)
+        table = Table(title="DevCouncil Agents")
+        table.add_column("Agent", style="cyan")
+        table.add_column("Type")
+        table.add_column("Command")
+        table.add_column("Profile")
+        table.add_column("MCP")
+        table.add_column("Diff Review")
 
-    for name, spec in sorted(load_cli_agent_specs(root).items()):
-        table.add_row(
-            name,
-            "built-in" if spec.built_in else spec.kind,
-            " ".join(spec.base_command()),
-            spec.default_profile,
-            "yes" if spec.supports_mcp else "no",
-            "yes" if spec.supports_diff_review else "no",
-        )
-    console.print(table)
+        for name, spec in sorted(load_cli_agent_specs(root).items()):
+            table.add_row(
+                name,
+                "built-in" if spec.built_in else spec.kind,
+                " ".join(spec.base_command()),
+                spec.default_profile,
+                "yes" if spec.supports_mcp else "no",
+                "yes" if spec.supports_diff_review else "no",
+            )
+        console.print(table)
+        log_step("agents/complete", project_root=root, trace=True)
 
 
 @app.command("add")

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

@@ -1,3 +1,4 @@
+import logging
 import typer
 from rich.console import Console
 from rich.table import Table
@@ -8,9 +9,11 @@ from devcouncil.artifacts.validators import ArtifactValidator
 from devcouncil.storage.db import get_db
 from devcouncil.storage.repositories import RequirementRepository, TaskRepository
 from devcouncil.cli.commands.init import initialize_project
+from devcouncil.telemetry.stages import log_stage, log_step
 
 app = typer.Typer()
 console = Console()
+logger = logging.getLogger(__name__)
 
 
 @app.command(name="validate")
@@ -19,36 +22,42 @@ def validate(
 ):
     """Validate requirements and tasks stored in the artifact graph."""
     root = project_root.expanduser().resolve()
+    from devcouncil.telemetry.logging_setup import set_log_dir
+    set_log_dir(root)
+    logger.info("dev artifacts validate")
     initialize_project(root, quiet=True)
     db = get_db(root)
     if not db:
         console.print("[red]DevCouncil state is unavailable in this directory.[/red]")
         raise typer.Exit(code=1)
 
-    errors: list[str] = []
-    with db.get_session() as session:
-        req_repo = RequirementRepository(session)
-        task_repo = TaskRepository(session)
-
-        for req in req_repo.get_all():
-            try:
-                ArtifactValidator.validate_requirement(req)
-            except GatingError as exc:
-                errors.append(str(exc))
-
-        for task in task_repo.get_all():
-            try:
-                ArtifactValidator.validate_task(task)
-            except GatingError as exc:
-                errors.append(str(exc))
-
-    if not errors:
-        console.print("[green]Artifacts are valid.[/green]")
-        return
-
-    table = Table(title="Artifact Validation Errors")
-    table.add_column("Error", style="red")
-    for error in errors:
-        table.add_row(error)
-    console.print(table)
-    raise typer.Exit(code=1)
+    with log_stage("artifacts", project_root=root):
+        log_step("artifacts/1: validating requirements and tasks", project_root=root, trace=True)
+        errors: list[str] = []
+        with db.get_session() as session:
+            req_repo = RequirementRepository(session)
+            task_repo = TaskRepository(session)
+
+            for req in req_repo.get_all():
+                try:
+                    ArtifactValidator.validate_requirement(req)
+                except GatingError as exc:
+                    errors.append(str(exc))
+
+            for task in task_repo.get_all():
+                try:
+                    ArtifactValidator.validate_task(task)
+                except GatingError as exc:
+                    errors.append(str(exc))
+
+        if not errors:
+            console.print("[green]Artifacts are valid.[/green]")
+            log_step("artifacts/complete", project_root=root, trace=True)
+            return
+
+        table = Table(title="Artifact Validation Errors")
+        table.add_column("Error", style="red")
+        for error in errors:
+            table.add_row(error)
+        console.print(table)
+        raise typer.Exit(code=1)

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

@@ -1,11 +1,14 @@
-import json
+from devcouncil.utils.json_persist import dump_json
+import logging
 from pathlib import Path
 
 import typer
 
 from devcouncil.indexing.ast_matcher import AstMatcher
+from devcouncil.telemetry.stages import log_stage, log_step
 
 app = typer.Typer(help="Run structural AST searches.")
+logger = logging.getLogger(__name__)
 
 
 @app.command("match")
@@ -18,5 +21,11 @@ def match(
 ):
     """Find function/class/type symbols using tree-sitter when available and fallbacks otherwise."""
     root = project_root.expanduser().resolve()
-    matches = AstMatcher(root).match(query=query, language=language, kind=kind, limit=max(1, limit))
-    typer.echo(json.dumps({"matches": [item.model_dump() for item in matches]}, indent=2))
+    from devcouncil.telemetry.logging_setup import set_log_dir
+    set_log_dir(root)
+    logger.info("dev ast match: query=%r language=%s kind=%s", query, language, kind)
+    with log_stage("ast", project_root=root):
+        log_step("ast/1: running structural match", project_root=root, trace=True)
+        matches = AstMatcher(root).match(query=query, language=language, kind=kind, limit=max(1, limit))
+        typer.echo(dump_json({"matches": [item.model_dump() for item in matches]}, indent=2))
+        log_step("ast/complete", project_root=root, count=len(matches), trace=True)

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

@@ -1,4 +1,4 @@
-import json
+import logging
 from pathlib import Path
 
 import typer
@@ -6,9 +6,12 @@ from rich.console import Console
 
 from devcouncil.cli.commands.init import initialize_project
 from devcouncil.storage.db import get_db
+from devcouncil.telemetry.stages import log_stage, log_step
+from devcouncil.utils.json_persist import write_json
 from devcouncil.verification.verifier import Verifier
 
 console = Console()
+logger = logging.getLogger(__name__)
 
 
 def baseline(
@@ -17,19 +20,25 @@ def baseline(
 ):
     """Capture the current repo state as DevCouncil's verification baseline."""
     root = project_root.expanduser().resolve()
+    from devcouncil.telemetry.logging_setup import set_log_dir
+    set_log_dir(root)
+    logger.info("dev baseline: force=%s", force)
     initialize_project(root, quiet=True)
     if not get_db(root):
         raise typer.Exit(code=1)
 
-    baseline_path = root / ".devcouncil" / "baseline.json"
-    if baseline_path.exists() and not force:
-        console.print("[yellow]Baseline already exists. Use --force to replace it.[/yellow]")
-        raise typer.Exit(code=1)
+    with log_stage("baseline", project_root=root, force=force):
+        log_step("baseline/1: capturing verification snapshot", project_root=root, trace=True)
+        baseline_path = root / ".devcouncil" / "baseline.json"
+        if baseline_path.exists() and not force:
+            console.print("[yellow]Baseline already exists. Use --force to replace it.[/yellow]")
+            raise typer.Exit(code=1)
 
-    changed_files = Verifier(root).get_changed_files()
-    payload = {
-        "changed_files": changed_files,
-        "note": "Files present in this snapshot are excluded from future task-scoped verification diffs.",
-    }
-    baseline_path.write_text(json.dumps(payload, indent=2), encoding="utf-8")
-    console.print(f"[green]Captured baseline with {len(changed_files)} changed file(s).[/green]")
+        changed_files = Verifier(root).get_changed_files()
+        payload = {
+            "changed_files": changed_files,
+            "note": "Files present in this snapshot are excluded from future task-scoped verification diffs.",
+        }
+        write_json(baseline_path, payload)
+        console.print(f"[green]Captured baseline with {len(changed_files)} changed file(s).[/green]")
+        log_step("baseline/complete", project_root=root, file_count=len(changed_files), trace=True)