devcouncil 0.1.1 → 0.2.1

package/src/devcouncil/app/__init__.py

@@ -1,28 +0,0 @@
-from devcouncil.app.state_machine import StateMachine, ProjectPhase
-from devcouncil.app.run_context import RunContext
-from devcouncil.app.orchestrator import Orchestrator
-from devcouncil.app.events import EventBus, bus, EventTypes
-from devcouncil.app.errors import (
-    DevCouncilError,
-    GatingError,
-    ConfigurationError,
-    OrchestrationError,
-    ExecutionError,
-    VerificationError,
-)
-
-__all__ = [
-    "StateMachine",
-    "ProjectPhase",
-    "RunContext",
-    "Orchestrator",
-    "EventBus",
-    "bus",
-    "EventTypes",
-    "DevCouncilError",
-    "GatingError",
-    "ConfigurationError",
-    "OrchestrationError",
-    "ExecutionError",
-    "VerificationError",
-]

package/src/devcouncil/app/config.py

@@ -1,158 +0,0 @@
-"""Typed configuration loader with Pydantic validation.
-
-Replaces scattered yaml.safe_load() calls with a single validated config service.
-"""
-
-from __future__ import annotations
-
-import os
-from pathlib import Path
-from typing import Dict, List
-
-from pydantic import BaseModel, Field
-
-
-class ModelRoleConfig(BaseModel):
-    model: str
-    temperature: float = 0.0
-
-
-class ModelsConfig(BaseModel):
-    provider: str = "openrouter"
-    roles: Dict[str, ModelRoleConfig] = Field(default_factory=dict)
-
-
-class ProjectConfig(BaseModel):
-    name: str = "devcouncil-project"
-    root: str = "."
-    default_branch: str = "main"
-
-
-class CommandsConfig(BaseModel):
-    test: List[str] = Field(default_factory=list)
-    lint: List[str] = Field(default_factory=list)
-    typecheck: List[str] = Field(default_factory=list)
-
-
-class GatesConfig(BaseModel):
-    require_clean_git_before_task: bool = True
-    block_orphan_diffs: bool = True
-    block_missing_tests_for_high_requirements: bool = True
-    block_dependency_changes_without_approval: bool = True
-    block_schema_change_without_migration: bool = True
-    block_failed_commands: bool = True
-
-
-class ExecutionConfig(BaseModel):
-    default_executor: str = "manual"
-    max_repair_attempts: int = 3
-    checkpoint_before_each_task: bool = True
-    command_timeout: int = 300
-
-
-class PrivacyConfig(BaseModel):
-    redact_env_vars: bool = True
-    redact_secrets_in_logs: bool = True
-    store_prompts_locally: bool = True
-
-
-class AgentFlowIntegrationConfig(BaseModel):
-    enabled: bool = False
-    trace_path: str = ".devcouncil/logs/traces.jsonl"
-    mode: str = "jsonl"
-
-
-class CodeReviewGraphIntegrationConfig(BaseModel):
-    enabled: bool = False
-    command: str = "code-review-graph"
-    optional: bool = True
-
-
-class LiveReviewIntegrationConfig(BaseModel):
-    enabled: bool = True
-    cards_path: str = ".devcouncil/live/cards"
-    signals_path: str = ".devcouncil/live/signals"
-    default_client: str = "claude"
-
-
-class IntegrationsConfig(BaseModel):
-    agent_flow: AgentFlowIntegrationConfig = Field(default_factory=AgentFlowIntegrationConfig)
-    code_review_graph: CodeReviewGraphIntegrationConfig = Field(default_factory=CodeReviewGraphIntegrationConfig)
-    live_review: LiveReviewIntegrationConfig = Field(default_factory=LiveReviewIntegrationConfig)
-
-
-class ProviderConfig(BaseModel):
-    sort: str = "price"
-    allow_fallbacks: bool = True
-    require_parameters: bool = True
-    data_collection: str = "deny"
-
-
-class DevCouncilConfig(BaseModel):
-    """Top-level validated configuration."""
-
-    project: ProjectConfig = Field(default_factory=ProjectConfig)
-    models: ModelsConfig = Field(default_factory=ModelsConfig)
-    provider: ProviderConfig = Field(default_factory=ProviderConfig)
-    commands: CommandsConfig = Field(default_factory=CommandsConfig)
-    gates: GatesConfig = Field(default_factory=GatesConfig)
-    execution: ExecutionConfig = Field(default_factory=ExecutionConfig)
-    privacy: PrivacyConfig = Field(default_factory=PrivacyConfig)
-    integrations: IntegrationsConfig = Field(default_factory=IntegrationsConfig)
-
-
-def load_config(project_root: Path = Path(".")) -> DevCouncilConfig:
-    """Load and validate .devcouncil/config.yaml.
-    
-    Returns DevCouncilConfig with defaults for any missing fields.
-    Raises FileNotFoundError if config doesn't exist.
-    """
-    import yaml
-
-    config_path = project_root / ".devcouncil" / "config.yaml"
-    if not config_path.exists():
-        raise FileNotFoundError(f"Config not found at {config_path}. Run 'dev init' first.")
-
-    with open(config_path) as f:
-        raw = yaml.safe_load(f) or {}
-
-    return DevCouncilConfig.model_validate(raw)
-
-
-def provider_api_key_env_var(provider: str = "openrouter") -> str:
-    env_map = {
-        "openrouter": "OPENROUTER_API_KEY",
-        "openai": "OPENAI_API_KEY",
-        "anthropic": "ANTHROPIC_API_KEY",
-    }
-    return env_map.get(provider, f"{provider.upper()}_API_KEY")
-
-
-def load_local_secrets(project_root: Path = Path(".")) -> Dict[str, str]:
-    secrets_path = project_root / ".devcouncil" / "secrets.env"
-    if not secrets_path.exists():
-        return {}
-
-    secrets: Dict[str, str] = {}
-    for line in secrets_path.read_text(encoding="utf-8").splitlines():
-        stripped = line.strip()
-        if not stripped or stripped.startswith("#") or "=" not in stripped:
-            continue
-        key, value = stripped.split("=", 1)
-        secrets[key.strip()] = value.strip().strip('"').strip("'")
-    return secrets
-
-
-def get_api_key(provider: str = "openrouter", project_root: Path = Path(".")) -> str:
-    """Retrieve the API key for the configured provider from environment.
-    
-    Raises ValueError if not found.
-    """
-    env_var = provider_api_key_env_var(provider)
-    key = os.environ.get(env_var) or load_local_secrets(project_root).get(env_var)
-    if not key:
-        raise ValueError(
-            f"API key not found. Set {env_var} in your environment or run 'dev setup'. "
-            f"Provider: {provider}"
-        )
-    return key

package/src/devcouncil/app/errors.py

@@ -1,23 +0,0 @@
-class DevCouncilError(Exception):
-    """Base exception for all DevCouncil errors."""
-    pass
-
-class GatingError(DevCouncilError):
-    """Raised when a task or plan fails a mandatory gate."""
-    pass
-
-class ConfigurationError(DevCouncilError):
-    """Raised when the project configuration is invalid or missing."""
-    pass
-
-class OrchestrationError(DevCouncilError):
-    """Raised when the orchestrator encounters an unexpected state."""
-    pass
-
-class ExecutionError(DevCouncilError):
-    """Raised when an external or internal executor fails to run a task."""
-    pass
-
-class VerificationError(DevCouncilError):
-    """Raised when the verifier fails to run its checks properly."""
-    pass

package/src/devcouncil/app/events.py

@@ -1,44 +0,0 @@
-from typing import Any, Callable, Dict, List
-import inspect
-import logging
-
-logger = logging.getLogger(__name__)
-
-class EventBus:
-    """Simple asynchronous event bus for DevCouncil orchestration."""
-    def __init__(self):
-        self._listeners: Dict[str, List[Callable]] = {}
-
-    def subscribe(self, event_type: str, callback: Callable):
-        if event_type not in self._listeners:
-            self._listeners[event_type] = []
-        self._listeners[event_type].append(callback)
-
-    async def emit(self, event_type: str, payload: Any = None):
-        """Emit an event asynchronously to all registered listeners.
-        
-        Supports both sync and async callbacks.
-        """
-        logger.debug(f"Event emitted: {event_type}")
-        if event_type in self._listeners:
-            for callback in self._listeners[event_type]:
-                try:
-                    if inspect.iscoroutinefunction(callback):
-                        await callback(payload)
-                    else:
-                        callback(payload)
-                except Exception as e:
-                    logger.error(f"Error in event listener for {event_type}: {e}")
-
-# Global event bus instance
-bus = EventBus()
-
-# Standard Event Types
-class EventTypes:
-    PLANNING_STARTED = "planning_started"
-    PLANNING_COMPLETED = "planning_completed"
-    TASK_EXECUTING = "task_executing"
-    TASK_VERIFIED = "task_verified"
-    TASK_BLOCKED = "task_blocked"
-    GATE_FAILED = "gate_failed"
-    MODEL_CALLED = "model_called"

package/src/devcouncil/app/orchestrator.py

@@ -1,92 +0,0 @@
-import logging
-import json
-from pathlib import Path
-from typing import Optional, Any
-
-from devcouncil.app.state_machine import StateMachine, ProjectPhase
-from devcouncil.app.run_context import RunContext
-from devcouncil.app.events import bus, EventTypes
-from devcouncil.storage.db import get_db
-from devcouncil.storage.repositories import StateRepository
-from devcouncil.telemetry.traces import TraceLogger
-
-logger = logging.getLogger(__name__)
-
-class Orchestrator:
-    """Central orchestrator managing the workflow lifecycle and state transitions."""
-    def __init__(self, project_root: Path, persist_state: bool = True):
-        self.project_root = project_root
-        self.persist_state = persist_state
-        
-        db = get_db(self.project_root)
-        if db:
-            with db.get_session() as session:
-                repo = StateRepository(session)
-                state = repo.get_state()
-                if state:
-                    self.state_machine = StateMachine(ProjectPhase(state.current_phase))
-                    self.state_machine._history = [ProjectPhase(p) for p in json.loads(state.history_json)]
-                else:
-                    self.state_machine = StateMachine(ProjectPhase.NEW)
-        else:
-            self.state_machine = StateMachine(ProjectPhase.NEW)
-            
-        self.current_run: Optional[RunContext] = None
-
-    def reset_state_machine(self, initial: ProjectPhase = ProjectPhase.NEW):
-        """Start a new lifecycle sequence without depending on prior persisted phase."""
-        self.state_machine = StateMachine(initial)
-
-    async def start_run(self, run_id: str, goal: str) -> RunContext:
-        """Start a new orchestration run."""
-        self.current_run = RunContext(
-            run_id=run_id,
-            project_root=str(self.project_root),
-            goal=goal
-        )
-        self.current_run.initialize()
-        TraceLogger(self.project_root).log_event(
-            "planning_started",
-            {"goal": goal},
-            run_id=run_id,
-            summary=f"Planning started: {goal}",
-        )
-        
-        await bus.emit(EventTypes.PLANNING_STARTED, {"run_id": run_id, "goal": goal})
-        return self.current_run
-
-    async def transition_to(self, target_phase: ProjectPhase):
-        """Transition the project phase and emit events."""
-        old_phase = self.state_machine.phase
-        self.state_machine.transition(target_phase)
-        
-        db = get_db(self.project_root)
-        if db and self.persist_state:
-            with db.get_session() as session:
-                repo = StateRepository(session)
-                repo.save_state(
-                    self.state_machine.phase.value,
-                    [p.value for p in self.state_machine.history]
-                )
-                
-        logger.info(f"Transitioned from {old_phase.value} to {target_phase.value}")
-        TraceLogger(self.project_root).log_event(
-            "phase_transition",
-            {"from": old_phase.value, "to": target_phase.value},
-            run_id=self.current_run.run_id if self.current_run else None,
-            summary=f"{old_phase.value} -> {target_phase.value}",
-        )
-        
-        if target_phase == ProjectPhase.PLAN_APPROVED:
-            await bus.emit(EventTypes.PLANNING_COMPLETED, {"run_id": self.current_run.run_id if self.current_run else None})
-
-    def save_run_artifact(self, name: str, data: Any, is_json: bool = True):
-        """Save a local artifact specific to this run (in .devcouncil/runs/)."""
-        if not self.current_run:
-            logger.warning("Attempted to save artifact without an active run context.")
-            return
-            
-        if is_json:
-            self.current_run.save_json_artifact(name, data)
-        else:
-            self.current_run.save_artifact(name, data)

package/src/devcouncil/app/project_status.py

@@ -1,29 +0,0 @@
-from __future__ import annotations
-
-from devcouncil.artifacts.graph import ArtifactGraph
-
-
-def compute_phase(graph: ArtifactGraph, persisted_phase: str | None = None) -> str:
-    """Compute the current project phase, honoring explicit persisted state first."""
-    if persisted_phase:
-        return persisted_phase
-
-    reqs = list(graph.requirements.values())
-    tasks = list(graph.tasks.values())
-    blocking_gaps = graph.blocking_gaps()
-    if not reqs and not tasks:
-        return "NEW"
-    if reqs and not tasks:
-        return "REQUIREMENTS_DRAFTED"
-    if blocking_gaps:
-        return "TASK_BLOCKED"
-    if tasks:
-        statuses = {task.status for task in tasks}
-        if "running" in statuses:
-            return "TASK_EXECUTING"
-        if "blocked" in statuses:
-            return "TASK_BLOCKED"
-        if all(status in {"verified", "done"} for status in statuses):
-            return "PROJECT_DONE"
-        return "PLAN_APPROVED"
-    return "NEW"

package/src/devcouncil/app/run_context.py

@@ -1,39 +0,0 @@
-from pathlib import Path
-from datetime import datetime, timezone
-from pydantic import BaseModel, Field
-from typing import Optional, List, Dict, Any
-import json
-import logging
-
-logger = logging.getLogger(__name__)
-
-class RunContext(BaseModel):
-    """Context object encapsulating the current execution run."""
-    run_id: str
-    project_root: str
-    goal: Optional[str] = None
-    start_time: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
-    active_tasks: List[str] = Field(default_factory=list)
-    metadata: Dict[str, Any] = Field(default_factory=dict)
-    
-    @property
-    def run_dir(self) -> Path:
-        return Path(self.project_root) / ".devcouncil" / "runs" / self.run_id
-
-    def initialize(self):
-        """Create the necessary run directory and sub-folders."""
-        self.run_dir.mkdir(parents=True, exist_ok=True)
-        logger.info(f"Initialized run context at {self.run_dir}")
-
-    def save_artifact(self, filename: str, content: str):
-        """Save a text artifact associated with this run."""
-        path = self.run_dir / filename
-        path.write_text(content, encoding="utf-8")
-        logger.debug(f"Saved artifact to {path}")
-
-    def save_json_artifact(self, filename: str, data: Any):
-        """Save a JSON artifact associated with this run."""
-        path = self.run_dir / filename
-        with open(path, "w", encoding="utf-8") as f:
-            json.dump(data, f, indent=2)
-        logger.debug(f"Saved JSON artifact to {path}")

package/src/devcouncil/app/state_machine.py

@@ -1,108 +0,0 @@
-"""Gating state machine for DevCouncil project lifecycle.
-
-States (from §12):
-  NEW -> REPO_MAPPED -> REQUIREMENTS_DRAFTED -> PLANS_GENERATED
-  -> CRITIQUES_GENERATED -> ARBITRATED -> AWAITING_USER_DECISIONS
-  -> PLAN_APPROVED -> TASK_READY -> TASK_EXECUTING -> TASK_VERIFYING
-  -> TASK_BLOCKED | TASK_VERIFIED -> PROJECT_DONE
-"""
-
-from __future__ import annotations
-
-from enum import Enum
-from typing import Dict, List, Set
-
-
-
-class ProjectPhase(str, Enum):
-    NEW = "NEW"
-    REPO_MAPPED = "REPO_MAPPED"
-    REQUIREMENTS_DRAFTED = "REQUIREMENTS_DRAFTED"
-    PLANS_GENERATED = "PLANS_GENERATED"
-    CRITIQUES_GENERATED = "CRITIQUES_GENERATED"
-    ARBITRATED = "ARBITRATED"
-    AWAITING_USER_DECISIONS = "AWAITING_USER_DECISIONS"
-    PLAN_APPROVED = "PLAN_APPROVED"
-    TASK_READY = "TASK_READY"
-    TASK_EXECUTING = "TASK_EXECUTING"
-    TASK_VERIFYING = "TASK_VERIFYING"
-    TASK_BLOCKED = "TASK_BLOCKED"
-    TASK_VERIFIED = "TASK_VERIFIED"
-    PROJECT_DONE = "PROJECT_DONE"
-
-
-# Valid transitions: from_phase -> set of valid next phases
-TRANSITIONS: Dict[ProjectPhase, Set[ProjectPhase]] = {
-    ProjectPhase.NEW: {ProjectPhase.REPO_MAPPED},
-    ProjectPhase.REPO_MAPPED: {ProjectPhase.REQUIREMENTS_DRAFTED},
-    ProjectPhase.REQUIREMENTS_DRAFTED: {ProjectPhase.PLANS_GENERATED},
-    ProjectPhase.PLANS_GENERATED: {ProjectPhase.CRITIQUES_GENERATED},
-    ProjectPhase.CRITIQUES_GENERATED: {ProjectPhase.ARBITRATED},
-    ProjectPhase.ARBITRATED: {
-        ProjectPhase.AWAITING_USER_DECISIONS,
-        ProjectPhase.PLAN_APPROVED,
-    },
-    ProjectPhase.AWAITING_USER_DECISIONS: {ProjectPhase.PLAN_APPROVED},
-    ProjectPhase.PLAN_APPROVED: {ProjectPhase.TASK_READY},
-    ProjectPhase.TASK_READY: {ProjectPhase.TASK_EXECUTING},
-    ProjectPhase.TASK_EXECUTING: {ProjectPhase.TASK_VERIFYING},
-    ProjectPhase.TASK_VERIFYING: {
-        ProjectPhase.TASK_VERIFIED,
-        ProjectPhase.TASK_BLOCKED,
-    },
-    ProjectPhase.TASK_BLOCKED: {
-        ProjectPhase.TASK_READY,  # after repair
-    },
-    ProjectPhase.TASK_VERIFIED: {
-        ProjectPhase.TASK_READY,  # next task
-        ProjectPhase.PROJECT_DONE,
-    },
-    ProjectPhase.PROJECT_DONE: set(),
-}
-
-
-class InvalidTransitionError(Exception):
-    """Raised when a state transition is not allowed."""
-
-    def __init__(self, current: ProjectPhase, target: ProjectPhase):
-        self.current = current
-        self.target = target
-        super().__init__(
-            f"Invalid transition: {current.value} -> {target.value}. "
-            f"Valid targets: {', '.join(t.value for t in TRANSITIONS.get(current, set()))}"
-        )
-
-
-class StateMachine:
-    """Manages project phase transitions with validation."""
-
-    def __init__(self, initial: ProjectPhase = ProjectPhase.NEW):
-        self._phase = initial
-        self._history: List[ProjectPhase] = [initial]
-
-    @property
-    def phase(self) -> ProjectPhase:
-        return self._phase
-
-    @property
-    def history(self) -> List[ProjectPhase]:
-        return list(self._history)
-
-    def can_transition(self, target: ProjectPhase) -> bool:
-        """Check if a transition to the target phase is valid."""
-        valid = TRANSITIONS.get(self._phase, set())
-        return target in valid
-
-    def transition(self, target: ProjectPhase) -> None:
-        """Transition to a new phase.
-        
-        Raises InvalidTransitionError if the transition is not allowed.
-        """
-        if not self.can_transition(target):
-            raise InvalidTransitionError(self._phase, target)
-        self._phase = target
-        self._history.append(target)
-
-    def valid_transitions(self) -> Set[ProjectPhase]:
-        """Return the set of valid next phases from the current state."""
-        return TRANSITIONS.get(self._phase, set())

package/src/devcouncil/artifacts/__init__.py

@@ -1 +0,0 @@
-"""Artifact package: graph, coverage, and validation for the persistent artifact DAG."""

package/src/devcouncil/artifacts/coverage.py

@@ -1,96 +0,0 @@
-"""Coverage analysis utilities for the artifact graph."""
-
-from __future__ import annotations
-
-from typing import Dict, List, Tuple
-
-from devcouncil.artifacts.graph import ArtifactGraph
-
-
-def requirement_task_matrix(graph: ArtifactGraph) -> List[Dict[str, str]]:
-    """Build a requirement → task → status coverage matrix for reporting.
-    
-    Returns a list of dicts suitable for rendering as a table:
-      [{"requirement": "REQ-001", "title": "...", "task": "TASK-001", "task_status": "verified"}, ...]
-    """
-    rows: List[Dict[str, str]] = []
-    for req in graph.requirements.values():
-        linked_tasks = [
-            t for t in graph.tasks.values() if req.id in t.requirement_ids
-        ]
-        if not linked_tasks:
-            rows.append({
-                "requirement": req.id,
-                "title": req.title,
-                "task": "(none)",
-                "task_status": "NOT PLANNED",
-            })
-        else:
-            for task in linked_tasks:
-                rows.append({
-                    "requirement": req.id,
-                    "title": req.title,
-                    "task": task.id,
-                    "task_status": task.status,
-                })
-    return rows
-
-
-def acceptance_criteria_evidence_matrix(
-    graph: ArtifactGraph,
-) -> List[Dict[str, str]]:
-    """Build an AC → evidence mapping for the final report.
-    
-    Returns rows with requirement_id, ac_id, ac_description, evidence_status.
-    """
-    evidenced: Dict[str, str] = {}
-    for ev in graph.test_evidence:
-        key = ev.acceptance_criterion_id
-        evidenced[key] = ev.status  # "passed", "failed", "not_run"
-
-    rows: List[Dict[str, str]] = []
-    for req in graph.requirements.values():
-        for ac in req.acceptance_criteria:
-            status = evidenced.get(ac.id, "no_evidence")
-            rows.append({
-                "requirement_id": req.id,
-                "ac_id": ac.id,
-                "description": ac.description,
-                "verification_method": ac.verification_method,
-                "status": status,
-            })
-    return rows
-
-
-def can_approve_plan(graph: ArtifactGraph) -> Tuple[bool, List[str]]:
-    """Check if the plan meets the PLAN_APPROVED gate criteria.
-    
-    Returns (passed, list_of_reasons_if_failed).
-    
-    Criteria (from §12):
-      - Every requirement has acceptance criteria.
-      - Every acceptance criterion has a verification method.
-      - Every requirement maps to at least one task.
-      - Every task maps to at least one requirement.
-      - Every high-impact assumption is confirmed or converted.
-      - No critical critique finding remains open.
-      - No blocking question remains unanswered.
-    """
-    reasons: List[str] = []
-
-    for req in graph.requirements_without_acceptance_criteria():
-        reasons.append(f"{req.id} has no acceptance criteria.")
-
-    for req in graph.requirements_without_tasks():
-        reasons.append(f"{req.id} is not mapped to any task.")
-
-    for task in graph.tasks_without_requirements():
-        reasons.append(f"{task.id} is not mapped to any requirement.")
-
-    for asm in graph.unconfirmed_high_impact_assumptions():
-        reasons.append(f"Assumption {asm.id} (high impact) is still open: {asm.statement}")
-
-    for finding in graph.open_findings("critical"):
-        reasons.append(f"Critical finding {finding.id} is still open: {finding.claim}")
-
-    return len(reasons) == 0, reasons