devcouncil 0.1.0 → 0.1.1

package/src/devcouncil/integrations/pr_comments.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+import httpx
+from urllib.parse import quote
+
+from devcouncil.artifacts.graph import ArtifactGraph
+from devcouncil.reporting.report_builder import ReportBuilder
+
+
+class PullRequestCommentError(RuntimeError):
+    pass
+
+
+def build_pr_comment_body(graph: ArtifactGraph, live_review: dict | None = None) -> str:
+    report = ReportBuilder.build_markdown(graph, live_review=live_review)
+    return "\n".join([
+        "## DevCouncil Verification",
+        "",
+        report,
+    ])
+
+
+class GitHubPRCommenter:
+    def __init__(self, token: str, repository: str, pull_number: int, *, base_url: str = "https://api.github.com"):
+        self.token = token
+        self.repository = repository
+        self.pull_number = pull_number
+        self.base_url = base_url.rstrip("/")
+
+    async def post_comment(self, body: str) -> dict:
+        url = f"{self.base_url}/repos/{self.repository}/issues/{self.pull_number}/comments"
+        headers = {
+            "Authorization": f"Bearer {self.token}",
+            "Accept": "application/vnd.github+json",
+            "Content-Type": "application/json",
+        }
+        async with httpx.AsyncClient() as client:
+            response = await client.post(url, headers=headers, json={"body": body})
+        if response.status_code >= 400:
+            raise PullRequestCommentError(f"GitHub comment failed with HTTP {response.status_code}: {response.text}")
+        return response.json() if response.content else {}
+
+
+class GitLabMRCommenter:
+    def __init__(self, token: str, project_id: str, merge_request_iid: int, *, base_url: str = "https://gitlab.com/api/v4"):
+        self.token = token
+        self.project_id = project_id
+        self.merge_request_iid = merge_request_iid
+        self.base_url = base_url.rstrip("/")
+
+    async def post_comment(self, body: str) -> dict:
+        project = quote(self.project_id, safe="")
+        url = f"{self.base_url}/projects/{project}/merge_requests/{self.merge_request_iid}/notes"
+        headers = {
+            "PRIVATE-TOKEN": self.token,
+            "Content-Type": "application/json",
+        }
+        async with httpx.AsyncClient() as client:
+            response = await client.post(url, headers=headers, json={"body": body})
+        if response.status_code >= 400:
+            raise PullRequestCommentError(f"GitLab comment failed with HTTP {response.status_code}: {response.text}")
+        return response.json() if response.content else {}

package/src/devcouncil/live/__init__.py

@@ -0,0 +1,2 @@
+"""Live coding-agent review primitives."""
+

package/src/devcouncil/live/cards.py

@@ -0,0 +1,207 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+
+from devcouncil.live.models import AgentTurn, CardStatus, CritiqueCard
+
+RISK_TERMS = (
+    "skip tests",
+    "no tests",
+    "untested",
+    "ignore failing",
+    "disable",
+    "workaround",
+    "quick hack",
+    "hardcode",
+    "force push",
+    "--no-verify",
+    "reset --hard",
+)
+
+EVIDENCE_TERMS = (
+    "test",
+    "pytest",
+    "vitest",
+    "npm test",
+    "go test",
+    "cargo test",
+    "verification",
+    "verified",
+)
+
+
+def review_turn(turn: AgentTurn, project_root: Path, client: str | None = None) -> CritiqueCard:
+    """Generate a deterministic critique card for an agent response."""
+    content = turn.content.strip()
+    lower = content.lower()
+    concerns: list[str] = []
+    alternatives: list[str] = []
+    evidence_requests: list[str] = []
+
+    risky_terms = [term for term in RISK_TERMS if term in lower]
+    if risky_terms:
+        concerns.append(f"Response contains risky implementation language: {', '.join(risky_terms[:4])}.")
+        alternatives.append("Replace risky shortcuts with a scoped implementation and explicit rollback or verification path.")
+
+    if _looks_like_completion_claim(lower) and not any(term in lower for term in EVIDENCE_TERMS):
+        concerns.append("The response appears to claim completion without naming verification evidence.")
+        evidence_requests.append("State the exact commands, checks, or reviewed artifacts that prove the change.")
+
+    if _mentions_broad_change(lower):
+        concerns.append("The response suggests broad codebase changes; confirm they are authorized by the active DevCouncil task.")
+        alternatives.append("Split broad work into smaller planned files and run DevCouncil gates before marking it done.")
+
+    if "todo" in lower or "follow-up" in lower or "later" in lower:
+        evidence_requests.append("List any remaining TODOs as DevCouncil gaps or repair tasks instead of burying them in chat.")
+
+    verdict = "Approved"
+    if concerns:
+        verdict = "Concerns"
+    if any(term in lower for term in ("--no-verify", "reset --hard", "force push", "ignore failing")):
+        verdict = "Critical Issues"
+
+    if not alternatives and verdict == "Approved":
+        alternatives.append("Proceed, but keep the final answer tied to changed files and verification evidence.")
+
+    summary = "No blocking critique found." if verdict == "Approved" else concerns[0]
+    message_for_agent = _message_for_agent(verdict, concerns, evidence_requests)
+    card_id = _card_id(turn)
+    return CritiqueCard(
+        id=card_id,
+        session_id=turn.session_id,
+        turn_id=turn.turn_id,
+        client=client or turn.source,
+        verdict=verdict,
+        summary=summary,
+        concerns=concerns,
+        alternatives=alternatives,
+        evidence_requests=evidence_requests,
+        message_for_agent=message_for_agent,
+    )
+
+
+def save_card(project_root: Path, card: CritiqueCard) -> Path:
+    cards_dir = project_root / ".devcouncil" / "live" / "cards"
+    cards_dir.mkdir(parents=True, exist_ok=True)
+    path = cards_dir / f"{card.id}.json"
+    path.write_text(card.model_dump_json(indent=2) + "\n", encoding="utf-8")
+    return path
+
+
+def card_path(project_root: Path, card_id: str) -> Path:
+    return project_root / ".devcouncil" / "live" / "cards" / f"{card_id}.json"
+
+
+def load_cards(project_root: Path) -> list[CritiqueCard]:
+    cards_dir = project_root / ".devcouncil" / "live" / "cards"
+    if not cards_dir.exists():
+        return []
+    cards: list[CritiqueCard] = []
+    for path in sorted(cards_dir.glob("*.json"), key=lambda item: item.stat().st_mtime, reverse=True):
+        try:
+            cards.append(CritiqueCard.model_validate(json.loads(path.read_text(encoding="utf-8"))))
+        except Exception:
+            continue
+    return cards
+
+
+def filter_cards(
+    cards: list[CritiqueCard],
+    *,
+    task_id: str | None = None,
+    status: str | None = None,
+    verdict: str | None = None,
+    client: str | None = None,
+) -> tuple[list[CritiqueCard], str | None, str | None]:
+    normalized_status = status.lower() if status else None
+    if normalized_status and normalized_status not in {"open", "resolved", "ignored"}:
+        return [], "--status must be open, resolved, or ignored.", "status"
+
+    verdict_map = {
+        "approved": "Approved",
+        "concerns": "Concerns",
+        "critical": "Critical Issues",
+        "critical issues": "Critical Issues",
+    }
+    normalized_verdict = None
+    if verdict:
+        normalized_verdict = verdict_map.get(verdict.lower())
+        if not normalized_verdict:
+            return [], "--verdict must be approved, concerns, or critical.", "verdict"
+
+    normalized_client = client.lower() if client else None
+    filtered = []
+    for card in cards:
+        if task_id and card.task_id != task_id:
+            continue
+        if normalized_status and card.status != normalized_status:
+            continue
+        if normalized_verdict and card.verdict != normalized_verdict:
+            continue
+        if normalized_client and card.client.lower() != normalized_client:
+            continue
+        filtered.append(card)
+    return filtered, None, None
+
+
+def get_card(project_root: Path, card_id: str) -> CritiqueCard | None:
+    for card in load_cards(project_root):
+        if card.id == card_id:
+            return card
+    return None
+
+
+def update_card_status(project_root: Path, card_id: str, status: CardStatus) -> CritiqueCard | None:
+    cards_dir = project_root / ".devcouncil" / "live" / "cards"
+    path = cards_dir / f"{card_id}.json"
+    if not path.exists():
+        return None
+    card = CritiqueCard.model_validate(json.loads(path.read_text(encoding="utf-8")))
+    updated = card.model_copy(update={"status": status})
+    path.write_text(updated.model_dump_json(indent=2) + "\n", encoding="utf-8")
+    return updated
+
+
+def unresolved_blocking_cards(project_root: Path, task_id: str | None = None) -> list[CritiqueCard]:
+    return [
+        card for card in load_cards(project_root)
+        if card.status == "open" and card.verdict == "Critical Issues"
+        and (task_id is None or card.task_id in {None, task_id})
+    ]
+
+
+def _card_id(turn: AgentTurn) -> str:
+    digest = hashlib.sha1(f"{turn.session_id}:{turn.turn_id}:{turn.content}".encode("utf-8")).hexdigest()
+    return f"CARD-{digest[:12]}"
+
+
+def _looks_like_completion_claim(lower: str) -> bool:
+    return any(phrase in lower for phrase in (
+        "done",
+        "completed",
+        "implemented",
+        "fixed",
+        "ready",
+        "all set",
+    ))
+
+
+def _mentions_broad_change(lower: str) -> bool:
+    return any(phrase in lower for phrase in (
+        "refactor the entire",
+        "rewrite",
+        "all files",
+        "every file",
+        "across the codebase",
+    ))
+
+
+def _message_for_agent(verdict: str, concerns: list[str], evidence_requests: list[str]) -> str:
+    if verdict == "Approved":
+        return "Continue, but keep the next response grounded in changed files and verification evidence."
+    pieces = ["Pause and address this review before proceeding."]
+    pieces.extend(concerns)
+    pieces.extend(evidence_requests)
+    return " ".join(pieces)

package/src/devcouncil/live/models.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+Verdict = Literal["Approved", "Concerns", "Critical Issues"]
+CardStatus = Literal["open", "resolved", "ignored"]
+
+
+class AgentTurn(BaseModel):
+    """A normalized coding-agent conversation turn."""
+
+    session_id: str
+    turn_id: str
+    source: str = "generic"
+    role: Literal["user", "assistant", "system", "tool", "unknown"] = "unknown"
+    content: str = ""
+    timestamp: str | None = None
+    raw: dict[str, Any] = Field(default_factory=dict)
+
+
+class AgentSession(BaseModel):
+    """A discovered coding-agent transcript."""
+
+    id: str
+    client: str
+    transcript_path: str
+    updated_at: str | None = None
+    turns: int = 0
+
+
+class CritiqueCard(BaseModel):
+    """Sage-style response review, shaped for DevCouncil gates."""
+
+    model_config = ConfigDict(populate_by_name=True, serialize_by_alias=True)
+
+    schema_version: str = Field("devcouncil.critique_card.v1", alias="schema")
+    id: str
+    session_id: str
+    turn_id: str
+    task_id: str | None = None
+    client: str
+    verdict: Verdict
+    summary: str
+    concerns: list[str] = Field(default_factory=list)
+    alternatives: list[str] = Field(default_factory=list)
+    message_for_agent: str = ""
+    evidence_requests: list[str] = Field(default_factory=list)
+    status: CardStatus = "open"
+    created_at: str = Field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+    source_path: str | None = None
+
+    @property
+    def blocks_completion(self) -> bool:
+        return self.verdict == "Critical Issues"
+
+
+def session_id_from_path(path: Path) -> str:
+    return path.stem.replace(".", "-")

package/src/devcouncil/live/repair_prompt.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from devcouncil.execution.prompt_builder import PromptBuilder
+from devcouncil.live.models import CritiqueCard
+from devcouncil.storage.db import get_db
+from devcouncil.storage.repositories import RequirementRepository, TaskRepository
+
+
+def build_live_repair_prompt(project_root: Path, card: CritiqueCard) -> str:
+    """Build a ready-to-paste repair prompt for a live-review critique card."""
+    prompt = [
+        f"# Repair Live Review Card {card.id}",
+        "",
+        "A DevCouncil live-review card is blocking or warning on the current coding-agent session.",
+        "Address the critique directly, then provide exact verification evidence.",
+        "",
+        "## Card",
+        f"- Verdict: {card.verdict}",
+        f"- Status: {card.status}",
+        f"- Task: {card.task_id or '(unscoped)'}",
+        f"- Summary: {card.summary}",
+    ]
+    if card.concerns:
+        prompt.extend(["", "## Concerns"])
+        prompt.extend(f"- {item}" for item in card.concerns)
+    if card.alternatives:
+        prompt.extend(["", "## Safer Alternatives"])
+        prompt.extend(f"- {item}" for item in card.alternatives)
+    if card.evidence_requests:
+        prompt.extend(["", "## Required Evidence"])
+        prompt.extend(f"- {item}" for item in card.evidence_requests)
+    if card.message_for_agent:
+        prompt.extend(["", "## Message For Agent", card.message_for_agent])
+
+    task_prompt = _task_prompt(project_root, card.task_id)
+    if task_prompt:
+        prompt.extend(["", "## Original DevCouncil Task Contract", task_prompt])
+
+    prompt.extend([
+        "",
+        "## Repair Instructions",
+        "1. Do not bypass tests, hooks, or verification gates.",
+        "2. Keep changes within the DevCouncil task contract when one is present.",
+        "3. Address each concern above explicitly.",
+        "4. Run the expected verification commands and report exact results.",
+        f"5. After the repair is complete, ask the developer to run `dev watch resolve {card.id} --status resolved`.",
+    ])
+    return "\n".join(prompt).rstrip() + "\n"
+
+
+def build_bulk_live_repair_prompt(project_root: Path, cards: list[CritiqueCard]) -> str:
+    """Build a combined repair prompt for multiple live-review critique cards."""
+    if not cards:
+        return "# Live Review Repair\n\nNo blocking live-review cards found for this scope.\n"
+    sections = [
+        "# Repair Blocking Live Review Cards",
+        "",
+        f"DevCouncil found {len(cards)} blocking live-review card(s). Address each card below.",
+    ]
+    for index, card in enumerate(cards, start=1):
+        sections.extend([
+            "",
+            f"---\n\n## Card {index}: {card.id}",
+            "",
+            build_live_repair_prompt(project_root, card).strip(),
+        ])
+    return "\n".join(sections).rstrip() + "\n"
+
+
+def _task_prompt(project_root: Path, task_id: str | None) -> str | None:
+    if not task_id:
+        return None
+    db = get_db(project_root)
+    if not db:
+        return None
+    with db.get_session() as session:
+        task = TaskRepository(session).get_by_id(task_id)
+        if not task:
+            return None
+        requirements = RequirementRepository(session).get_all()
+    return PromptBuilder(project_root).build_task_prompt(task, requirements)

package/src/devcouncil/live/reviewer.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from devcouncil.live.cards import review_turn
+from devcouncil.live.models import AgentTurn, CritiqueCard
+from devcouncil.llm.router import ModelRouter
+
+
+class LiveReviewService:
+    """Reviews coding-agent responses with deterministic or model-backed critique cards."""
+
+    def __init__(self, router: ModelRouter | None = None, role: str = "live_reviewer"):
+        self.router = router
+        self.role = role
+
+    async def review(
+        self,
+        turn: AgentTurn,
+        project_root: Path,
+        client: str = "generic",
+        use_llm: bool = False,
+    ) -> CritiqueCard:
+        fallback = review_turn(turn, project_root, client=client)
+        if not use_llm or self.router is None:
+            return fallback
+
+        prompt = f"""
+You are DevCouncil's live coding-agent reviewer.
+Review the latest assistant response before the developer follows it.
+
+Return a critique card with:
+- verdict: Approved, Concerns, or Critical Issues.
+- concerns: concrete risks in the response, reasoning, plan, or proof.
+- alternatives: safer approaches or architectures.
+- evidence_requests: exact proof the agent should provide before claiming done.
+- message_for_agent: a concise ready-to-paste instruction for the coding agent.
+
+Do not praise. Do not review formatting. Focus on correctness, missing requirements, architectural drift,
+unsafe commands, weak evidence, and premature completion claims.
+
+Client: {client}
+Session: {turn.session_id}
+Turn: {turn.turn_id}
+
+Assistant response:
+{turn.content}
+"""
+        try:
+            reviewed = await self.router.complete_structured(
+                role=self.role,
+                messages=[{"role": "user", "content": prompt}],
+                schema=CritiqueCard,
+            )
+        except ValueError:
+            reviewed = await self.router.complete_structured(
+                role="implementation_reviewer",
+                messages=[{"role": "user", "content": prompt}],
+                schema=CritiqueCard,
+            )
+        except Exception:
+            return fallback
+
+        return reviewed.model_copy(update={
+            "id": fallback.id,
+            "session_id": turn.session_id,
+            "turn_id": turn.turn_id,
+            "client": client,
+            "source_path": fallback.source_path,
+        })

package/src/devcouncil/live/signals.py

@@ -0,0 +1,135 @@
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class ReviewSignal(BaseModel):
+    client: str = "generic"
+    payload: dict[str, Any] = Field(default_factory=dict)
+    transcript_path: str | None = None
+    session_id: str | None = None
+    task_id: str | None = None
+    created_at: str = Field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+    review_command: str | None = None
+    path: str | None = None
+
+
+def signal_dir(project_root: Path) -> Path:
+    return project_root / ".devcouncil" / "live" / "signals"
+
+
+def processed_signal_dir(project_root: Path) -> Path:
+    return signal_dir(project_root) / "processed"
+
+
+def write_signal(project_root: Path, client: str, payload: dict[str, Any]) -> Path:
+    directory = signal_dir(project_root)
+    directory.mkdir(parents=True, exist_ok=True)
+    transcript_path = extract_transcript_path(payload)
+    session_id = _string_value(payload, "session_id", "sessionId", "session", "cwd")
+    task_id = extract_task_id(payload)
+    signal = ReviewSignal(
+        client=client.lower(),
+        payload=payload,
+        transcript_path=transcript_path,
+        session_id=session_id,
+        task_id=task_id,
+        review_command=_review_command(client.lower(), transcript_path, task_id),
+    )
+    key = transcript_path or session_id or json.dumps(payload, sort_keys=True, default=str)
+    import hashlib
+
+    digest = hashlib.sha1(key.encode("utf-8", errors="replace")).hexdigest()[:12]
+    path = directory / f"{client.lower()}-{digest}.json"
+    signal.path = str(path)
+    path.write_text(signal.model_dump_json(indent=2) + "\n", encoding="utf-8")
+    return path
+
+
+def load_signals(project_root: Path) -> list[ReviewSignal]:
+    directory = signal_dir(project_root)
+    if not directory.exists():
+        return []
+    signals: list[ReviewSignal] = []
+    for path in sorted(directory.glob("*.json"), key=lambda item: item.stat().st_mtime, reverse=True):
+        try:
+            raw = json.loads(path.read_text(encoding="utf-8"))
+            signal = ReviewSignal.model_validate(raw)
+            signal.path = str(path)
+            signals.append(signal)
+        except Exception:
+            continue
+    return signals
+
+
+def mark_processed(signal: ReviewSignal, project_root: Path) -> Path | None:
+    if not signal.path:
+        return None
+    source = Path(signal.path)
+    if not source.exists():
+        return None
+    target_dir = processed_signal_dir(project_root)
+    target_dir.mkdir(parents=True, exist_ok=True)
+    target = target_dir / source.name
+    if target.exists():
+        target.unlink()
+    source.replace(target)
+    return target
+
+
+def extract_transcript_path(payload: dict[str, Any]) -> str | None:
+    direct = _string_value(
+        payload,
+        "transcript_path",
+        "transcriptPath",
+        "transcript",
+        "conversation_path",
+        "conversationPath",
+        "file",
+        "path",
+    )
+    if direct:
+        return direct
+    for key in ("session", "message", "hook_event", "event"):
+        nested = payload.get(key)
+        if isinstance(nested, dict):
+            value = extract_transcript_path(nested)
+            if value:
+                return value
+    return None
+
+
+def extract_task_id(payload: dict[str, Any]) -> str | None:
+    direct = _string_value(payload, "task_id", "taskId", "task", "active_task", "activeTask")
+    if direct:
+        return direct
+    for key in ("session", "message", "hook_event", "event", "metadata"):
+        nested = payload.get(key)
+        if isinstance(nested, dict):
+            value = extract_task_id(nested)
+            if value:
+                return value
+    return None
+
+
+def _string_value(payload: dict[str, Any], *keys: str) -> str | None:
+    for key in keys:
+        value = payload.get(key)
+        if isinstance(value, str) and value.strip():
+            return value
+    return None
+
+
+def _review_command(client: str, transcript_path: str | None, task_id: str | None = None) -> str:
+    if transcript_path:
+        command = f"dev watch review --client {client} --transcript {transcript_path}"
+    else:
+        command = f"dev watch pending --client {client}"
+    if task_id:
+        command += f" --task-id {task_id}"
+    return command

package/src/devcouncil/live/summary.py

@@ -0,0 +1,34 @@
+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.tasks import active_task_id
+
+
+def live_review_summary(project_root: Path, task_id: str | None = None) -> 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)
+    pending_signal_items = [signal.model_dump() for signal in signals]
+    return {
+        "active_task_id": active_id,
+        "scope_task_id": scoped_task_id,
+        "pending_signals": len(signals),
+        "pending_signal_items": pending_signal_items[:10],
+        "cards": {
+            "total": len(cards),
+            "open": len([card for card in cards if card.status == "open"]),
+            "resolved": len([card for card in cards if card.status == "resolved"]),
+            "ignored": len([card for card in cards if card.status == "ignored"]),
+            "critical_open": len([
+                card for card in cards
+                if card.status == "open" and card.verdict == "Critical Issues"
+            ]),
+        },
+        "blocking_cards": [card.model_dump() for card in blockers],
+        "recent_cards": [card.model_dump() for card in cards[:5]],
+    }

package/src/devcouncil/live/tasks.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from devcouncil.storage.db import get_db
+from devcouncil.storage.repositories import TaskRepository
+
+
+def active_task_id(project_root: Path) -> str | None:
+    """Return the single running DevCouncil task ID, if one is unambiguous."""
+    db = get_db(project_root)
+    if not db:
+        return None
+    with db.get_session() as session:
+        running = [task for task in TaskRepository(session).get_all() if task.status == "running"]
+    if len(running) != 1:
+        return None
+    return running[0].id