devcouncil 0.1.0 → 0.1.1

package/src/devcouncil/app/orchestrator.py

@@ -1,44 +1,44 @@
-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
+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."""
+
+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),
@@ -51,24 +51,24 @@ class Orchestrator:
             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]
-                )
-                
+        
+        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",
@@ -79,14 +79,14 @@ class Orchestrator:
         
         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)
+
+    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

@@ -0,0 +1,29 @@
+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 +1,39 @@
-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}")
+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 +1,108 @@
-"""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())
+"""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 +1 @@
-"""Artifact package: graph, coverage, and validation for the persistent artifact DAG."""
+"""Artifact package: graph, coverage, and validation for the persistent artifact DAG."""