devcouncil 0.3.0 → 0.4.0

package/src/devcouncil/campaign/bloom.py

@@ -0,0 +1,137 @@
+"""Bloom's-taxonomy routing — decide whether a task needs a worker or a thinker.
+
+The Coordinator tags every subtask with a Bloom level and routes it: the lower three
+levels (Remember / Understand / Apply) are execution and go to an **Worker**;
+the upper three (Analyze / Evaluate / Create) are cognition and go to the
+**Reviewer**. The classifier is a deterministic keyword heuristic — intentionally
+simple, cheap and testable — with an explicit override honoured first so a
+planner or human can pin a level via ``Task.difficulty`` or a tag.
+"""
+
+from __future__ import annotations
+
+import re
+from enum import IntEnum
+from typing import Dict, Iterable, List, Optional
+
+from devcouncil.campaign.roles import Rank
+
+
+class BloomLevel(IntEnum):
+    REMEMBER = 1
+    UNDERSTAND = 2
+    APPLY = 3
+    ANALYZE = 4
+    EVALUATE = 5
+    CREATE = 6
+
+    @property
+    def label(self) -> str:
+        return self.name.capitalize()
+
+
+# Ordered high→low so a strong verb ("architect", L6) wins over an incidental
+# weak one ("list", L1) appearing in the same sentence.
+_KEYWORDS: Dict[BloomLevel, List[str]] = {
+    BloomLevel.CREATE: [
+        "design", "architect", "architecture", "invent", "compose", "author",
+        "scaffold new", "green-field", "greenfield", "propose", "strategy",
+        "strategize", "plan the", "new subsystem", "from scratch",
+    ],
+    BloomLevel.EVALUATE: [
+        "evaluate", "assess", "review", "audit", "critique", "judge", "compare",
+        "trade-off", "tradeoff", "recommend", "decide", "prioritize", "quality",
+        "verify design", "root cause", "root-cause",
+    ],
+    BloomLevel.ANALYZE: [
+        "analyze", "analyse", "investigate", "diagnose", "debug", "profile",
+        "why", "reverse-engineer", "break down", "correlate", "trace",
+        "distinguish", "differentiate",
+    ],
+    BloomLevel.APPLY: [
+        "implement", "build", "write", "add", "create ", "fix", "refactor",
+        "wire", "integrate", "migrate", "port", "configure", "hook up",
+        "apply", "use", "run", "execute",
+    ],
+    BloomLevel.UNDERSTAND: [
+        "summarize", "summarise", "explain", "describe", "document", "clarify",
+        "interpret", "outline", "paraphrase", "restate",
+    ],
+    BloomLevel.REMEMBER: [
+        "list", "find", "locate", "look up", "fetch", "collect", "gather",
+        "identify", "name", "retrieve", "read",
+    ],
+}
+
+# Strong execution verbs — when present, cap classification at APPLY even if
+# evaluate/analyze keywords ("review", "quality", …) also appear in the title.
+_IMPLEMENTATION_OVERRIDES: List[str] = [
+    "implement", "fix", "add", "write", "build", "refactor", "wire", "integrate",
+    "migrate", "port", "configure", "hook up",
+]
+
+
+_DIFFICULTY_HINT: Dict[str, BloomLevel] = {
+    "easy": BloomLevel.APPLY,
+    "normal": BloomLevel.APPLY,
+    "hard": BloomLevel.ANALYZE,
+}
+
+
+def _match(text: str, phrase: str) -> bool:
+    if phrase.endswith(" ") or " " in phrase:
+        return phrase.strip() in text
+    return re.search(rf"\b{re.escape(phrase)}\b", text) is not None
+
+
+def classify_bloom(
+    text: str,
+    *,
+    override: Optional[BloomLevel] = None,
+    difficulty: Optional[str] = None,
+) -> BloomLevel:
+    """Classify free text into a :class:`BloomLevel`.
+
+    Precedence: explicit ``override`` > keyword match > ``difficulty`` hint >
+    default (:attr:`BloomLevel.APPLY`, the most common execution level).
+    """
+    if override is not None:
+        return override
+    haystack = (text or "").lower()
+    for level in sorted(_KEYWORDS, reverse=True):  # CREATE(6) → REMEMBER(1)
+        if level is BloomLevel.APPLY:
+            continue
+        if any(_match(haystack, kw) for kw in _KEYWORDS[level]):
+            if level >= BloomLevel.EVALUATE and any(
+                _match(haystack, kw) for kw in _IMPLEMENTATION_OVERRIDES
+            ):
+                return BloomLevel.APPLY
+            return level
+    if any(_match(haystack, kw) for kw in _KEYWORDS[BloomLevel.APPLY]):
+        return BloomLevel.APPLY
+    if difficulty and difficulty.lower() in _DIFFICULTY_HINT:
+        return _DIFFICULTY_HINT[difficulty.lower()]
+    return BloomLevel.APPLY
+
+
+def route_rank(level: BloomLevel) -> Rank:
+    """Map a Bloom level to the rank that should own it."""
+    return Rank.REVIEWER if level >= BloomLevel.ANALYZE else Rank.WORKER
+
+
+def route_text(
+    text: str,
+    *,
+    override: Optional[BloomLevel] = None,
+    difficulty: Optional[str] = None,
+) -> Rank:
+    """Convenience: classify ``text`` and return the owning rank."""
+    return route_rank(classify_bloom(text, override=override, difficulty=difficulty))
+
+
+def summarize_routing(items: Iterable[str]) -> Dict[str, int]:
+    """Count how a batch of task descriptions would route (for the dashboard)."""
+    counts = {Rank.WORKER.value: 0, Rank.REVIEWER.value: 0}
+    for item in items:
+        counts[route_text(item).value] += 1
+    return counts

package/src/devcouncil/campaign/dashboard.py

@@ -0,0 +1,123 @@
+"""The campaign dashboard — the Coordinator's single source of truth for the operator.
+
+Only the Coordinator writes ``.devcouncil/campaign/dashboard.md``. It renders the roster,
+the order in play, work in progress, achievements (verified tasks) and anything
+blocked, so the operator (or the Director answering for the operator) can read the state of
+the campaign at a glance.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Dict, List, Optional
+
+
+@dataclass
+class RosterEntry:
+    agent: str
+    rank: str
+    status: str = "idle"       # idle | working | reviewing
+    current_task: str = "-"
+
+
+@dataclass
+class DashboardState:
+    """Everything the dashboard renders — mutated by the campaign as it runs."""
+
+    goal: str = ""
+    roster: List[RosterEntry] = field(default_factory=list)
+    in_progress: List[str] = field(default_factory=list)   # "T-001 · worker1 · Apply"
+    achievements: List[str] = field(default_factory=list)   # verified task lines
+    blocked: List[str] = field(default_factory=list)        # "T-002 — <gap>"
+    skipped: List[str] = field(default_factory=list)        # unmet dependency
+    routing: Dict[str, int] = field(default_factory=dict)
+    total_tasks: int = 0
+    completed_tasks: int = 0
+    cost_usd: float = 0.0
+    cost_budget_usd: float | None = None
+
+    def roster_for(self, agent: str) -> Optional[RosterEntry]:
+        for entry in self.roster:
+            if entry.agent == agent:
+                return entry
+        return None
+
+
+class DashboardWriter:
+    """Renders :class:`DashboardState` to markdown and writes it atomically-ish."""
+
+    def __init__(self, root: Path | str = Path(".")):
+        self.root = Path(root)
+        self.path = self.root / ".devcouncil" / "campaign" / "dashboard.md"
+
+    def render(self, state: DashboardState) -> str:
+        now = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%SZ")
+        lines: List[str] = []
+        lines.append("# Director Campaign Dashboard")
+        lines.append("")
+        lines.append(f"_Updated {now} — written by the Coordinator._")
+        lines.append("")
+        lines.append("## Order")
+        lines.append("")
+        lines.append(f"> {state.goal or '(none)'}")
+        lines.append("")
+        if state.routing:
+            routed = ", ".join(f"{k}: {v}" for k, v in state.routing.items())
+            lines.append(f"Routing — {routed}")
+            lines.append("")
+
+        if state.total_tasks:
+            pct = int(100 * state.completed_tasks / state.total_tasks) if state.total_tasks else 0
+            lines.append("## Progress")
+            lines.append("")
+            lines.append(f"- Tasks: **{state.completed_tasks}/{state.total_tasks}** verified ({pct}%)")
+            if state.cost_budget_usd is not None:
+                lines.append(
+                    f"- Spend: **${state.cost_usd:.4f}** / ${state.cost_budget_usd:.2f} budget"
+                )
+            elif state.cost_usd:
+                lines.append(f"- Spend: **${state.cost_usd:.4f}**")
+            lines.append("")
+
+        lines.append("## Roster")
+        lines.append("")
+        lines.append("| Agent | Rank | Status | Current |")
+        lines.append("| --- | --- | --- | --- |")
+        for e in state.roster:
+            lines.append(f"| {e.agent} | {e.rank} | {e.status} | {e.current_task} |")
+        lines.append("")
+
+        lines.append(f"## In Progress ({len(state.in_progress)})")
+        lines.append("")
+        lines.extend(f"- {row}" for row in state.in_progress)
+        if not state.in_progress:
+            lines.append("- (quiet)")
+        lines.append("")
+
+        lines.append(f"## Achievements ({len(state.achievements)})")
+        lines.append("")
+        lines.extend(f"- ✅ {row}" for row in state.achievements)
+        if not state.achievements:
+            lines.append("- (none yet)")
+        lines.append("")
+
+        if state.blocked:
+            lines.append(f"## Blocked ({len(state.blocked)})")
+            lines.append("")
+            lines.extend(f"- ⛔ {row}" for row in state.blocked)
+            lines.append("")
+
+        if state.skipped:
+            lines.append(f"## Skipped — unmet dependencies ({len(state.skipped)})")
+            lines.append("")
+            lines.extend(f"- ⏭️ {row}" for row in state.skipped)
+            lines.append("")
+
+        return "\n".join(lines).rstrip() + "\n"
+
+    def write(self, state: DashboardState) -> Path:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.path.write_text(self.render(state), encoding="utf-8")
+        return self.path

package/src/devcouncil/campaign/mailbox.py

@@ -0,0 +1,305 @@
+"""File-based agent mailbox — the Director message bus.
+
+Faithful port of the original ``scripts/inbox_write.sh`` semantics:
+
+* one YAML file per agent at ``.devcouncil/campaign/inbox/<agent>.yaml`` holding a
+  ``messages:`` list of ``{id, from, timestamp, type, content, read}`` entries;
+* every append happens under a cross-process lock (an ``mkdir`` spin-mutex, plus
+  ``fcntl.flock`` where available) so concurrent Worker never corrupt a file;
+* writes are atomic (temp file + :func:`os.replace`) so a reader never observes a
+  half-written file;
+* the file is capped (all unread + newest ``MAX_READ_RETAINED`` read) so a busy
+  campaign cannot grow a mailbox without bound;
+* self-sends are rejected (an agent may not mail itself).
+
+Delivery is considered guaranteed the instant the write succeeds — there are no
+ACKs or retries. Waking the recipient is a separate concern handled by
+:mod:`devcouncil.campaign.watcher`.
+"""
+
+from __future__ import annotations
+
+import os
+import tempfile
+import time
+import uuid
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Dict, List, Optional
+
+import yaml
+
+try:  # POSIX advisory lock; optional, we still hold the mkdir spin-mutex without it.
+    import fcntl
+except ImportError:  # pragma: no cover - Windows
+    fcntl = None  # type: ignore[assignment]
+
+MAX_MESSAGES = 50
+"""Hard cap on messages retained per mailbox file."""
+
+MAX_READ_RETAINED = 30
+"""When capping, keep every unread message plus this many newest read ones."""
+
+LOCK_TIMEOUT_S = 5.0
+"""How long :meth:`Mailbox._lock` spins before giving up on the mutex."""
+
+# Message types the watcher consumes directly (context resets, model swaps, …).
+# They are delivered but excluded from the "N unread" nudge count so they never
+# masquerade as work waiting for the agent.
+SPECIAL_TYPES = frozenset({"clear_command", "model_switch", "cli_restart"})
+
+
+def _utcnow() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+@dataclass
+class Message:
+    """One entry in an agent's mailbox."""
+
+    id: str
+    from_agent: str
+    timestamp: str
+    type: str
+    content: str
+    read: bool = False
+
+    def to_dict(self) -> Dict[str, object]:
+        # Persist with the original schema's ``from`` key (a Python keyword, hence
+        # the ``from_agent`` attribute name).
+        return {
+            "id": self.id,
+            "from": self.from_agent,
+            "timestamp": self.timestamp,
+            "type": self.type,
+            "content": self.content,
+            "read": self.read,
+        }
+
+    @classmethod
+    def from_dict(cls, raw: Dict[str, object]) -> "Message":
+        return cls(
+            id=str(raw.get("id", "")),
+            from_agent=str(raw.get("from", raw.get("from_agent", ""))),
+            timestamp=str(raw.get("timestamp", "")),
+            type=str(raw.get("type", "info")),
+            content=str(raw.get("content", "")),
+            read=bool(raw.get("read", False)),
+        )
+
+    @property
+    def is_special(self) -> bool:
+        return self.type in SPECIAL_TYPES
+
+
+class MailboxError(RuntimeError):
+    """Raised when a mailbox invariant is violated (e.g. a self-send)."""
+
+
+class MailboxLockTimeout(MailboxError):
+    """Raised when the mailbox mutex cannot be acquired within :data:`LOCK_TIMEOUT_S`."""
+
+
+class Mailbox:
+    """Read/write access to every agent's on-disk inbox.
+
+    A single :class:`Mailbox` instance is safe to share across threads; all
+    mutation goes through the per-agent file lock.
+    """
+
+    def __init__(self, root: Path | str = Path(".")):
+        self.root = Path(root)
+        self.inbox_dir = self.root / ".devcouncil" / "campaign" / "inbox"
+
+    # -- paths -----------------------------------------------------------------
+
+    def path_for(self, agent: str) -> Path:
+        return self.inbox_dir / f"{agent}.yaml"
+
+    def _ensure_dir(self) -> None:
+        self.inbox_dir.mkdir(parents=True, exist_ok=True)
+
+    # -- locking ---------------------------------------------------------------
+
+    class _Lock:
+        """``with mailbox._lock(agent):`` — mkdir spin-mutex + optional flock."""
+
+        def __init__(self, path: Path):
+            self._mutex_dir = path.with_suffix(path.suffix + ".lock.d")
+            self._flock_path = path.with_suffix(path.suffix + ".flock")
+            self._flock_fd: Optional[int] = None
+            self._acquired = False
+
+        def __enter__(self) -> "Mailbox._Lock":
+            deadline = time.monotonic() + LOCK_TIMEOUT_S
+            self._mutex_dir.parent.mkdir(parents=True, exist_ok=True)
+            while True:
+                try:
+                    self._mutex_dir.mkdir()  # atomic on POSIX + Windows
+                    self._acquired = True
+                    break
+                except FileExistsError:
+                    if time.monotonic() > deadline:
+                        # Best-effort stale-lock recovery: if the mutex dir is very old,
+                        # assume a crashed writer left it behind and try once more.
+                        try:
+                            age = time.time() - self._mutex_dir.stat().st_mtime
+                            if age > LOCK_TIMEOUT_S * 2:
+                                self._mutex_dir.rmdir()
+                                continue
+                        except OSError:
+                            pass
+                        raise MailboxLockTimeout(
+                            f"could not acquire mailbox lock within {LOCK_TIMEOUT_S}s: {self._mutex_dir}"
+                        )
+                    time.sleep(0.02)
+            if fcntl is not None:
+                try:
+                    self._flock_fd = os.open(self._flock_path, os.O_CREAT | os.O_RDWR, 0o644)
+                    fcntl.flock(self._flock_fd, fcntl.LOCK_EX)
+                except OSError:
+                    self._flock_fd = None
+            return self
+
+        def __exit__(self, *exc: object) -> None:
+            if self._flock_fd is not None:
+                try:
+                    if fcntl is not None:
+                        fcntl.flock(self._flock_fd, fcntl.LOCK_UN)
+                    os.close(self._flock_fd)
+                except OSError:
+                    pass
+                self._flock_fd = None
+            if self._acquired:
+                try:
+                    self._mutex_dir.rmdir()
+                except OSError:
+                    pass
+
+    def _lock(self, agent: str) -> "Mailbox._Lock":
+        self._ensure_dir()
+        return Mailbox._Lock(self.path_for(agent))
+
+    # -- io --------------------------------------------------------------------
+
+    def _read_raw(self, agent: str) -> List[Message]:
+        path = self.path_for(agent)
+        if not path.exists():
+            return []
+        try:
+            data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+        except (yaml.YAMLError, OSError):
+            return []
+        raw = data.get("messages", []) if isinstance(data, dict) else []
+        return [Message.from_dict(m) for m in raw if isinstance(m, dict)]
+
+    def _write_atomic(self, agent: str, messages: List[Message]) -> None:
+        self._ensure_dir()
+        path = self.path_for(agent)
+        payload = {"agent": agent, "messages": [m.to_dict() for m in messages]}
+        text = yaml.safe_dump(payload, allow_unicode=True, sort_keys=False)
+        fd, tmp = tempfile.mkstemp(dir=str(self.inbox_dir), prefix=f".{agent}.", suffix=".tmp")
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as fh:
+                fh.write(text)
+                fh.flush()
+                os.fsync(fh.fileno())
+            os.replace(tmp, path)  # atomic swap
+        finally:
+            if os.path.exists(tmp):
+                os.unlink(tmp)
+
+    @staticmethod
+    def _cap(messages: List[Message]) -> List[Message]:
+        if len(messages) <= MAX_MESSAGES:
+            return messages
+        unread = [m for m in messages if not m.read]
+        read = [m for m in messages if m.read]
+        kept_read = read[-MAX_READ_RETAINED:]
+        # Preserve original ordering (oldest→newest) while dropping the oldest read.
+        keep = set(id(m) for m in unread) | set(id(m) for m in kept_read)
+        result = [m for m in messages if id(m) in keep]
+        if len(result) > MAX_MESSAGES:
+            # Unread dominated the cap — drop oldest messages to honor MAX_MESSAGES.
+            result = result[-MAX_MESSAGES:]
+        return result
+
+    # -- public api ------------------------------------------------------------
+
+    def send(
+        self,
+        target: str,
+        content: str,
+        type: str = "info",
+        from_agent: str = "director",
+    ) -> Message:
+        """Append a message to ``target``'s mailbox and return it.
+
+        Raises :class:`MailboxError` on a self-send.
+        """
+        if target == from_agent:
+            raise MailboxError(f"{from_agent} may not send mail to itself")
+        message = Message(
+            id=uuid.uuid4().hex[:12],
+            from_agent=from_agent,
+            timestamp=_utcnow(),
+            type=type,
+            content=content,
+            read=False,
+        )
+        with self._lock(target):
+            messages = self._read_raw(target)
+            messages.append(message)
+            self._write_atomic(target, self._cap(messages))
+        return message
+
+    def all(self, agent: str) -> List[Message]:
+        """Every message currently in ``agent``'s mailbox (oldest→newest)."""
+        return self._read_raw(agent)
+
+    def unread(self, agent: str) -> List[Message]:
+        """Unread messages in delivery order."""
+        return [m for m in self._read_raw(agent) if not m.read]
+
+    def count_unread(self, agent: str, exclude_special: bool = True) -> int:
+        """Number of unread messages — the ``N`` in an ``inboxN`` nudge."""
+        msgs = self.unread(agent)
+        if exclude_special:
+            msgs = [m for m in msgs if not m.is_special]
+        return len(msgs)
+
+    def mark_read(self, agent: str, ids: Optional[List[str]] = None) -> int:
+        """Mark messages read. ``ids=None`` marks all. Returns count changed."""
+        target_ids = set(ids) if ids is not None else None
+        changed = 0
+        with self._lock(agent):
+            messages = self._read_raw(agent)
+            for m in messages:
+                if not m.read and (target_ids is None or m.id in target_ids):
+                    m.read = True
+                    changed += 1
+            if changed:
+                self._write_atomic(agent, messages)
+        return changed
+
+    def drain(self, agent: str, exclude_special: bool = False) -> List[Message]:
+        """Return unread messages and mark them read in one locked pass."""
+        with self._lock(agent):
+            messages = self._read_raw(agent)
+            picked: List[Message] = []
+            for m in messages:
+                if m.read:
+                    continue
+                if exclude_special and m.is_special:
+                    continue
+                m.read = True
+                picked.append(m)
+            if picked:
+                self._write_atomic(agent, messages)
+        return picked
+
+    def clear(self, agent: str) -> None:
+        """Reset an agent's mailbox (used by campaign ``--clean``)."""
+        with self._lock(agent):
+            self._write_atomic(agent, [])

package/src/devcouncil/campaign/notify.py

@@ -0,0 +1,91 @@
+"""Notifications to the operator — a port of the original ``ntfy.sh`` push.
+
+The Coordinator (and only the Coordinator/Director) may reach the operator. When a campaign finishes
+— or a task is blocked — a one-line push goes to an `ntfy <https://ntfy.sh>`_
+topic so the operator can watch progress from a phone. A missing topic degrades to
+a silent no-op; a failed push never crashes a campaign.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import List, Optional
+
+
+class Notifier:
+    """Best-effort push notifier backed by ntfy.
+
+    Parameters
+    ----------
+    topic:
+        ntfy topic. Falls back to ``$DIRECTOR_NTFY_TOPIC``. Empty → disabled.
+    server:
+        ntfy server base URL (default the public ``https://ntfy.sh``). Falls back
+        to ``$DIRECTOR_NTFY_SERVER``.
+    enabled:
+        Force-enable/disable; ``None`` means "enabled iff a topic is set".
+    """
+
+    def __init__(
+        self,
+        topic: Optional[str] = None,
+        server: Optional[str] = None,
+        enabled: Optional[bool] = None,
+    ):
+        self.topic = topic or os.environ.get("DIRECTOR_NTFY_TOPIC", "")
+        self.server = (server or os.environ.get("DIRECTOR_NTFY_SERVER") or "https://ntfy.sh").rstrip("/")
+        self.enabled = bool(self.topic) if enabled is None else enabled
+        # Records every push (delivered or not) for the dashboard / tests.
+        self.sent: List[str] = []
+
+    def notify(
+        self,
+        message: str,
+        title: Optional[str] = None,
+        priority: Optional[str] = None,
+        tags: Optional[List[str]] = None,
+    ) -> bool:
+        """Send a push. Returns ``True`` if it left the machine, else ``False``."""
+        self.sent.append(message)
+        if not self.enabled or not self.topic:
+            return False
+        try:  # httpx is a DevCouncil dependency; import lazily to keep startup cheap.
+            import httpx
+
+            headers = {}
+            if title:
+                headers["Title"] = title
+            if priority:
+                headers["Priority"] = priority
+            if tags:
+                headers["Tags"] = ",".join(tags)
+            token = os.environ.get("DIRECTOR_NTFY_TOKEN")
+            if token:
+                headers["Authorization"] = f"Bearer {token}"
+            resp = httpx.post(
+                f"{self.server}/{self.topic}",
+                content=message.encode("utf-8"),
+                headers=headers,
+                timeout=5.0,
+            )
+            return resp.status_code < 400
+        except Exception:
+            # Never let a notification failure abort the campaign.
+            return False
+
+
+class NullNotifier(Notifier):
+    """A notifier that records messages but never sends — the default."""
+
+    def __init__(self) -> None:
+        super().__init__(topic="", enabled=False)
+
+    def notify(
+        self,
+        message: str,
+        title: Optional[str] = None,
+        priority: Optional[str] = None,
+        tags: Optional[List[str]] = None,
+    ) -> bool:
+        self.sent.append(message)
+        return False