devcouncil 0.1.0

package/src/devcouncil/executors/native/agent.py

@@ -0,0 +1,107 @@
+from typing import List, Dict, Any
+from rich.console import Console
+from pydantic import BaseModel
+from devcouncil.domain.task import Task
+from devcouncil.domain.requirement import Requirement
+from devcouncil.execution.executor import Executor, ExecutionResult
+from devcouncil.llm.router import ModelRouter
+from devcouncil.execution.task_runner import TaskRunner
+from devcouncil.execution.context_builder import ContextBuilder
+from devcouncil.execution.paths import resolve_project_path
+
+console = Console()
+
+class ToolCall(BaseModel):
+    tool: str
+    args: Dict[str, Any]
+
+class AgentAction(BaseModel):
+    thought: str
+    tool_calls: List[ToolCall] = []
+    finish: bool = False
+
+class NativeAgent(Executor):
+    def __init__(self, router: ModelRouter, task_runner: TaskRunner):
+        self.router = router
+        self.task_runner = task_runner
+        self.context_builder = ContextBuilder(task_runner.project_root)
+
+    async def run_task(self, task: Task, requirements: List[Requirement]) -> ExecutionResult:
+        console.print(f"Starting [bold]Native Executor[/bold] for task {task.id}...")
+        
+        # 1. Gather rich context
+        context_json = self.context_builder.build_task_context(task, requirements)
+        
+        system_prompt = f"""
+You are the DevCouncil Native Agent. Your goal is to implement the provided task.
+Current Project Context:
+{context_json}
+
+You have access to the following tools:
+- read_file(path: str)
+- list_files()
+- apply_patch(patch: str)
+- run_command(command: str)
+
+Rules:
+1. You can only write to files or apply patches to files listed in the task's 'planned_files'.
+2. You can only run commands listed in the task's 'allowed_commands'.
+3. Use 'thought' to explain your reasoning.
+4. Set 'finish' to true when you believe the task is complete and verified.
+"""
+        messages = [{"role": "system", "content": system_prompt}]
+        
+        # Initial task prompt
+        messages.append({"role": "user", "content": f"Begin implementing task {task.id} based on the context provided."})
+
+        # Basic tool loop (Max 10 steps for safety in MVP)
+        for step in range(10):
+            action = await self.router.complete_structured(
+                role="native_agent", 
+                messages=messages,
+                schema=AgentAction
+            )
+            
+            console.print(f"\n[bold]Step {step+1}:[/bold] {action.thought}")
+            
+            if action.finish:
+                console.print("[green]Native agent signaled completion.[/green]")
+                return ExecutionResult(success=True, message="Agent signaled completion")
+
+            for tool_call in action.tool_calls:
+                result_summary = ""
+                try:
+                    if tool_call.tool == "read_file":
+                        path = tool_call.args["path"]
+                        resolved = resolve_project_path(self.task_runner.project_root, path)
+                        # Security: block reading sensitive files
+                        sensitive_patterns = {".env", ".pem", ".key", "credentials", "secrets"}
+                        path_lower = path.lower()
+                        if any(s in path_lower for s in sensitive_patterns):
+                            raise PermissionError(f"Reading sensitive file blocked: {path}")
+                        content = resolved.read_text(encoding="utf-8")
+                        if len(content) > 8000:
+                            content = content[:8000] + "\n[truncated]"
+                        result_summary = f"File content of {path}:\n{content}"
+                    elif tool_call.tool == "list_files":
+                        # We use the internal helper but return limited list
+                        files = self.context_builder.get_structure_summary()
+                        result_summary = f"Found {len(files)} files in repository."
+                    elif tool_call.tool == "write_file":
+                        raise PermissionError("write_file is disabled for the native executor; use apply_patch.")
+                    elif tool_call.tool == "apply_patch":
+                        self.task_runner.apply_patch(tool_call.args["patch"], task)
+                        result_summary = "Successfully applied patch."
+                    elif tool_call.tool == "run_command":
+                        cmd_result = self.task_runner.run_command(tool_call.args["command"], task)
+                        result_summary = f"Command finished with exit code {cmd_result.exit_code}."
+                    else:
+                        raise ValueError(f"Unknown tool: {tool_call.tool}")
+                    
+                    messages.append({"role": "user", "content": f"[Tool Result] '{tool_call.tool}': {result_summary}"})
+                except Exception as e:
+                    console.print(f"[red]Error executing tool {tool_call.tool}: {e}[/red]")
+                    messages.append({"role": "user", "content": f"[Tool Error] '{tool_call.tool}' failed: {e}"})
+
+        console.print("[red]Native agent reached maximum step limit.[/red]")
+        return ExecutionResult(success=False, message="Reached maximum step limit")

package/src/devcouncil/executors/openhands.py

@@ -0,0 +1,71 @@
+import subprocess
+from pathlib import Path
+from rich.console import Console
+from devcouncil.domain.task import Task
+from devcouncil.domain.requirement import Requirement
+from devcouncil.execution.executor import Executor, ExecutionResult
+from devcouncil.execution.prompt_builder import PromptBuilder
+
+console = Console()
+
+class OpenHandsExecutor(Executor):
+    def __init__(self, project_root: Path):
+        self.project_root = project_root
+
+    def run_task(self, task: Task, requirements: list[Requirement]) -> ExecutionResult:
+        builder = PromptBuilder(self.project_root)
+        task_prompt = builder.build_task_prompt(task, requirements)
+        
+        console.print(f"Starting [bold]OpenHands[/bold] for task {task.id}...")
+        
+        # OpenHands often expects a workspace mount and an instruction.
+        # Keep the full prompt out of argv so Windows command-line limits and
+        # terminal logs do not become part of the execution boundary.
+        # Reference: https://github.com/All-Hands-AI/OpenHands
+        instruction_file = self.project_root / ".devcouncil" / f"{task.id}-openhands-task.md"
+        instruction_file.parent.mkdir(parents=True, exist_ok=True)
+        instruction_file.write_text(task_prompt, encoding="utf-8")
+        
+        cmd = [
+            "openhands", "run",
+            "--workspace-base", str(self.project_root),
+            "--task-file", str(instruction_file),
+            "--headless"
+        ]
+        
+        console.print(f"Command: [dim]{' '.join(cmd)}[/dim]")
+        console.print("[yellow]Note: OpenHands must be installed and configured in the environment.[/yellow]")
+        
+        try:
+            result = subprocess.run(
+                cmd,
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+                cwd=self.project_root,
+                timeout=1800,
+            )
+            self._write_log(task.id, result)
+            if result.returncode != 0:
+                console.print(f"[red]OpenHands exited with {result.returncode}.[/red]")
+                return ExecutionResult(success=False, message=f"Exited with code {result.returncode}")
+            return ExecutionResult(success=True, message="Completed successfully")
+        except Exception as e:
+            console.print(f"[red]Error running OpenHands: {e}[/red]")
+            return ExecutionResult(success=False, message=str(e))
+
+    def _write_log(self, task_id: str, result: subprocess.CompletedProcess[str]) -> None:
+        log_dir = self.project_root / ".devcouncil" / "logs"
+        log_dir.mkdir(parents=True, exist_ok=True)
+        log_path = log_dir / f"{task_id}-openhands.log"
+        log_path.write_text(
+            "\n".join([
+                f"command_returncode={result.returncode}",
+                "=== stdout ===",
+                result.stdout or "",
+                "=== stderr ===",
+                result.stderr or "",
+            ]),
+            encoding="utf-8",
+        )

package/src/devcouncil/gating/__init__.py

@@ -0,0 +1 @@
+

package/src/devcouncil/gating/checks/clean_git.py

@@ -0,0 +1,45 @@
+import subprocess
+import logging
+from devcouncil.domain.gap import Gap
+
+logger = logging.getLogger(__name__)
+
+class CleanGitCheck:
+    """Ensures the working tree is clean before a task starts."""
+    
+    def check(self, project_root, task_id: str) -> list[Gap]:
+        try:
+            status = subprocess.check_output(["git", "status", "--porcelain"], cwd=project_root).decode()
+            if status.strip():
+                return [Gap(
+                    id=f"GAP-{task_id}-DIRTY-GIT",
+                    severity="high",
+                    gap_type="architecture_drift",
+                    task_id=task_id,
+                    description="Git working tree is dirty. Execution requires a clean state for checkpointing.",
+                    recommended_fix="Commit or stash your current changes before running the task.",
+                    blocking=True
+                )]
+        except FileNotFoundError:
+            logger.error("Git is not installed or not in PATH.")
+            return [Gap(
+                id=f"GAP-{task_id}-NO-GIT",
+                severity="high",
+                gap_type="architecture_drift",
+                task_id=task_id,
+                description="Git is not available. Cannot verify working tree cleanliness.",
+                recommended_fix="Install git and ensure it is in your PATH.",
+                blocking=True
+            )]
+        except subprocess.CalledProcessError as e:
+            logger.warning("Git status check failed: %s", e)
+            return [Gap(
+                id=f"GAP-{task_id}-GIT-ERROR",
+                severity="medium",
+                gap_type="architecture_drift",
+                task_id=task_id,
+                description=f"Git status check failed: {e}. Directory may not be a git repository.",
+                recommended_fix="Initialize a git repository with 'git init' before running tasks.",
+                blocking=True
+            )]
+        return []

package/src/devcouncil/gating/checks/planned_files_check.py

@@ -0,0 +1,32 @@
+from devcouncil.domain.task import Task
+from devcouncil.domain.gap import Gap
+
+class PlannedFilesCheck:
+    """Ensures a task has legitimate files planned for modification."""
+    
+    def check(self, task: Task) -> list[Gap]:
+        gaps = []
+        if not task.planned_files:
+            gaps.append(Gap(
+                id=f"GAP-{task.id}-NO-FILES",
+                severity="high",
+                gap_type="task_not_implemented",
+                task_id=task.id,
+                description=f"Task {task.id} has no planned files. Agents won't know where to write code.",
+                recommended_fix="Update the task to include at least one planned file path.",
+                blocking=True
+            ))
+        
+        has_modify = any(pf.allowed_change in ["create", "modify", "delete"] for pf in task.planned_files)
+        if task.planned_files and not has_modify:
+            gaps.append(Gap(
+                id=f"GAP-{task.id}-READ-ONLY",
+                severity="medium",
+                gap_type="task_not_implemented",
+                task_id=task.id,
+                description=f"Task {task.id} only has read-only files. No changes can be made.",
+                recommended_fix="Grant 'modify' or 'create' permissions to at least one file.",
+                blocking=True
+            ))
+            
+        return gaps

package/src/devcouncil/gating/checks/requirement_coverage.py

@@ -0,0 +1,26 @@
+from devcouncil.domain.requirement import Requirement
+from devcouncil.domain.task import Task
+from devcouncil.domain.gap import Gap
+from typing import List
+
+class RequirementCoverageCheck:
+    """Detects requirements that are not mapped to any tasks."""
+    
+    def check(self, requirements: List[Requirement], tasks: List[Task]) -> List[Gap]:
+        task_req_ids = set()
+        for t in tasks:
+            task_req_ids.update(t.requirement_ids)
+            
+        gaps = []
+        for req in requirements:
+            if req.id not in task_req_ids:
+                gaps.append(Gap(
+                    id=f"GAP-PLAN-{req.id}-UNMAPPED",
+                    severity="high",
+                    gap_type="requirement_not_planned",
+                    requirement_id=req.id,
+                    description=f"Requirement '{req.title}' is not covered by any task.",
+                    recommended_fix="Decompose this requirement into one or more implementation tasks.",
+                    blocking=True
+                ))
+        return gaps

package/src/devcouncil/gating/checks/secret_scan_check.py

@@ -0,0 +1,34 @@
+from typing import List
+from devcouncil.domain.gap import Gap
+from devcouncil.utils.redaction import SECRET_PATTERNS, redact_string
+
+class SecretScanner:
+    """Scans code diffs for potential secrets (API keys, tokens, etc.)."""
+    
+    def scan_diff(self, diff_content: str, task_id: str) -> List[Gap]:
+        gaps = []
+        lines = diff_content.splitlines()
+        current_file = "unknown_file"
+        
+        for i, line in enumerate(lines):
+            if line.startswith("+++ b/"):
+                current_file = line[6:]
+                continue
+                
+            # Only scan added lines in diff
+            if not line.startswith("+") or line.startswith("+++"):
+                continue
+                
+            for key_type, pattern in SECRET_PATTERNS.items():
+                if pattern.search(line):
+                    gaps.append(Gap(
+                        id=f"GAP-{task_id}-SECRET-{key_type.upper()}-{i}",
+                        severity="critical",
+                        gap_type="security_risk",
+                        task_id=task_id,
+                        description=f"Potential {key_type} found in {current_file} (diff line {i+1}).",
+                        evidence=[redact_string(line.strip())],
+                        recommended_fix="Remove the secret and use environment variables or a secret manager.",
+                        blocking=True
+                    ))
+        return gaps

package/src/devcouncil/gating/policy.py

@@ -0,0 +1,190 @@
+from pydantic import BaseModel
+from typing import Any, List, Optional
+from pathlib import Path
+
+from devcouncil.domain.requirement import Requirement
+from devcouncil.domain.task import Task
+from devcouncil.domain.gap import Gap
+from devcouncil.domain.assumption import Assumption
+from devcouncil.domain.critique import CritiqueFinding
+from devcouncil.gating.checks.requirement_coverage import RequirementCoverageCheck
+from devcouncil.gating.checks.planned_files_check import PlannedFilesCheck
+from devcouncil.gating.checks.clean_git import CleanGitCheck
+
+class GateResult(BaseModel):
+    passed: bool
+    gaps: List[Gap]
+
+class GatePolicy:
+    """Central engine for executing project and task level quality gates."""
+    
+    def __init__(self):
+        self.req_coverage = RequirementCoverageCheck()
+        self.planned_files = PlannedFilesCheck()
+        self.clean_git = CleanGitCheck()
+
+    def check_plan_approval(
+        self,
+        requirements: List[Requirement],
+        tasks: List[Task],
+        assumptions: Optional[List[Assumption]] = None,
+        findings: Optional[List[CritiqueFinding]] = None,
+        blocking_questions: Optional[List[Any]] = None,
+    ) -> GateResult:
+        """Determines if the overall project plan is ready for execution."""
+        gaps = []
+        known_req_ids = {req.id for req in requirements}
+        known_ac_ids = {
+            ac.id
+            for req in requirements
+            for ac in req.acceptance_criteria
+        }
+        
+        # 1. Check requirement coverage
+        gaps.extend(self.req_coverage.check(requirements, tasks))
+        
+        # 2. Check for acceptance criteria presence
+        for req in requirements:
+            if not req.acceptance_criteria:
+                gaps.append(Gap(
+                    id=f"GAP-PLAN-{req.id}-NO-AC",
+                    severity="high",
+                    gap_type="requirement_not_planned",
+                    requirement_id=req.id,
+                    description=f"Requirement {req.id} has no acceptance criteria.",
+                    recommended_fix="Define at least one measurable AC.",
+                    blocking=True
+                ))
+
+            for ac in req.acceptance_criteria:
+                if not ac.verification_method:
+                    gaps.append(Gap(
+                        id=f"GAP-PLAN-{ac.id}-NO-VERIFY",
+                        severity="high",
+                        gap_type="acceptance_criteria_unproven",
+                        requirement_id=req.id,
+                        description=f"Acceptance criterion {ac.id} has no verification method.",
+                        recommended_fix="Define a deterministic verification method for this AC.",
+                        blocking=True,
+                    ))
+
+        for task in tasks:
+            if not task.requirement_ids:
+                gaps.append(Gap(
+                    id=f"GAP-PLAN-{task.id}-NO-REQ",
+                    severity="high",
+                    gap_type="requirement_not_planned",
+                    task_id=task.id,
+                    description=f"Task {task.id} is not mapped to any requirement.",
+                    recommended_fix="Map each task to at least one requirement.",
+                    blocking=True,
+                ))
+
+            unknown_req_ids = [req_id for req_id in task.requirement_ids if req_id not in known_req_ids]
+            if unknown_req_ids:
+                gaps.append(Gap(
+                    id=f"GAP-PLAN-{task.id}-UNKNOWN-REQ",
+                    severity="high",
+                    gap_type="requirement_not_planned",
+                    task_id=task.id,
+                    description=f"Task {task.id} references unknown requirement(s): {', '.join(unknown_req_ids)}.",
+                    recommended_fix="Remove invalid requirement links or add the missing requirements.",
+                    blocking=True,
+                ))
+
+            unknown_ac_ids = [ac_id for ac_id in task.acceptance_criterion_ids if ac_id not in known_ac_ids]
+            if unknown_ac_ids:
+                gaps.append(Gap(
+                    id=f"GAP-PLAN-{task.id}-UNKNOWN-AC",
+                    severity="high",
+                    gap_type="acceptance_criteria_unproven",
+                    task_id=task.id,
+                    description=f"Task {task.id} references unknown acceptance criteria: {', '.join(unknown_ac_ids)}.",
+                    recommended_fix="Link tasks only to acceptance criteria declared by requirements.",
+                    blocking=True,
+                ))
+
+        for assumption in assumptions or []:
+            if (
+                assumption.impact == "high"
+                and assumption.status == "open"
+                and assumption.requires_user_confirmation
+            ):
+                gaps.append(Gap(
+                    id=f"GAP-PLAN-{assumption.id}-OPEN",
+                    severity="high",
+                    gap_type="assumption_violated",
+                    requirement_id=assumption.linked_requirement_ids[0] if assumption.linked_requirement_ids else None,
+                    description=f"High-impact assumption {assumption.id} is still open: {assumption.statement}",
+                    recommended_fix="Confirm, reject, or convert this assumption before approving the plan.",
+                    blocking=True,
+                ))
+
+        for finding in findings or []:
+            if finding.severity in {"high", "critical"} and finding.status == "open":
+                gaps.append(Gap(
+                    id=f"GAP-PLAN-{finding.id}-OPEN",
+                    severity=finding.severity,
+                    gap_type="architecture_drift",
+                    requirement_id=finding.linked_requirement_id,
+                    description=f"Open {finding.severity} critique finding remains: {finding.claim}",
+                    recommended_fix="Convert, rebut with evidence, or mark this finding resolved before approval.",
+                    blocking=True,
+                ))
+
+        for question in blocking_questions or []:
+            question_id = getattr(question, "id", "QUESTION")
+            question_text = getattr(question, "question", str(question))
+            gaps.append(Gap(
+                id=f"GAP-PLAN-{question_id}-BLOCKING",
+                severity="high",
+                gap_type="requirement_not_planned",
+                description=f"Blocking question remains unanswered: {question_text}",
+                recommended_fix="Answer or convert the blocking question before approving the plan.",
+                blocking=True,
+            ))
+
+        return GateResult(
+            passed=len([g for g in gaps if g.blocking]) == 0, 
+            gaps=gaps
+        )
+
+    def check_task_ready(self, task: Task, project_root: Path) -> GateResult:
+        """Determines if a specific task can begin execution."""
+        gaps = []
+        
+        # 1. Check Git state
+        gaps.extend(self.clean_git.check(project_root, task.id))
+        
+        # 2. Check planned files
+        gaps.extend(self.planned_files.check(task))
+
+        # 3. Check execution/verification evidence contract
+        if not task.allowed_commands:
+            gaps.append(Gap(
+                id=f"GAP-{task.id}-NO-COMMANDS",
+                severity="high",
+                gap_type="missing_test",
+                task_id=task.id,
+                description=f"Task {task.id} has no allowed commands for execution or verification.",
+                recommended_fix="Add explicit allowed_commands for the task before execution.",
+                blocking=True,
+            ))
+
+        if not task.expected_tests:
+            gaps.append(Gap(
+                id=f"GAP-{task.id}-NO-EXPECTED-EVIDENCE",
+                severity="high",
+                gap_type="missing_test",
+                task_id=task.id,
+                description=f"Task {task.id} has no expected verification evidence.",
+                recommended_fix="Add expected_tests or targeted static/manual review commands that prove the acceptance criteria.",
+                blocking=True,
+            ))
+
+        # 4. Check for task dependencies (if implemented)
+        
+        return GateResult(
+            passed=len([g for g in gaps if g.blocking]) == 0, 
+            gaps=gaps
+        )

package/src/devcouncil/indexing/__init__.py

@@ -0,0 +1 @@
+

package/src/devcouncil/indexing/graph_index.py

@@ -0,0 +1,48 @@
+from typing import List, Dict, Any, Set
+from pydantic import BaseModel, Field
+from pathlib import Path
+
+class GraphNode(BaseModel):
+    id: str
+    type: str # "file", "symbol", "requirement", "task"
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+
+class GraphEdge(BaseModel):
+    source: str
+    target: str
+    relation: str # "imports", "implements", "validates", "contains"
+
+class KnowledgeGraph(BaseModel):
+    nodes: List[GraphNode] = []
+    edges: List[GraphEdge] = []
+
+class GraphIndex:
+    def __init__(self, project_root: Path):
+        self.project_root = project_root
+        self.graph = KnowledgeGraph()
+
+    def build_initial_graph(self, files: List[str]):
+        """
+        Bootstrap the graph from file list.
+        """
+        for f in files:
+            self.graph.nodes.append(GraphNode(
+                id=f,
+                type="file",
+                metadata={"extension": Path(f).suffix}
+            ))
+
+    def add_relation(self, source: str, target: str, relation: str):
+        self.graph.edges.append(GraphEdge(source=source, target=target, relation=relation))
+
+    def get_context_for_file(self, file_path: str) -> Set[str]:
+        """
+        Retrieve related paths for a given file.
+        """
+        related = {file_path}
+        for edge in self.graph.edges:
+            if edge.source == file_path:
+                related.add(edge.target)
+            if edge.target == file_path:
+                related.add(edge.source)
+        return related