devcouncil 0.1.0 → 0.2.0

package/src/devcouncil/planning/prompt_enhancer_service.py

@@ -0,0 +1,167 @@
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+from devcouncil.llm.router import ModelRouter
+
+# Cap how much skill text we feed the enhancer so a repo matching many skills
+# can't blow up the planning prompt. Domain skills are ~50 lines each.
+_MAX_SKILLS_FOR_INTAKE = 4
+_MAX_INTAKE_CHARS = 8000
+
+
+class PromptEnhancement(BaseModel):
+    original_goal: str
+    enhanced_goal: str
+    codebase_context: list[str] = Field(default_factory=list)
+    debate_focus: list[str] = Field(default_factory=list)
+    constraints: list[str] = Field(default_factory=list)
+    # Senior-level domain intake folded in from the skills library (android, ios,
+    # web, ...). ``applied_skills`` are the matched skill names; ``skills_brief`` is
+    # the compact title+description block the council debates with. Both are set
+    # deterministically after the model call — the LLM does not populate them.
+    applied_skills: list[str] = Field(default_factory=list)
+    skills_brief: str = ""
+
+    def normalized(self, original_goal: str) -> "PromptEnhancement":
+        enhanced_goal = self.enhanced_goal.strip() or original_goal
+        return self.model_copy(
+            update={
+                "original_goal": original_goal,
+                "enhanced_goal": enhanced_goal,
+                "codebase_context": _clean_items(self.codebase_context),
+                "debate_focus": _clean_items(self.debate_focus),
+                "constraints": _clean_items(self.constraints),
+            }
+        )
+
+    def debate_prompt(self) -> str:
+        sections = [
+            "# Enhanced Planning Prompt",
+            "",
+            "## Original user goal",
+            self.original_goal,
+            "",
+            "## Codebase-specific goal",
+            self.enhanced_goal,
+        ]
+        if self.codebase_context:
+            sections.extend(["", "## Relevant codebase context"])
+            sections.extend(f"- {item}" for item in self.codebase_context)
+        if self.constraints:
+            sections.extend(["", "## Constraints to preserve"])
+            sections.extend(f"- {item}" for item in self.constraints)
+        if self.debate_focus:
+            sections.extend(["", "## Debate focus"])
+            sections.extend(f"- {item}" for item in self.debate_focus)
+        if self.skills_brief:
+            sections.extend([
+                "",
+                "## Domain engineering intake (apply current senior-level practices)",
+                "Plan to the *current* state of these domains — recommended libraries, "
+                "deprecations to avoid, and the right build/test CLI commands. The coding "
+                "agent receives the full skill text; the plan must already assume it.",
+                self.skills_brief,
+            ])
+        return "\n".join(sections)
+
+
+class PromptEnhancerService:
+    def __init__(self, router: ModelRouter):
+        self.router = router
+
+    async def enhance_prompt(
+        self,
+        goal: str,
+        repo_map_json: str,
+        graph_context_json: str | None = None,
+        project_root: Path | None = None,
+    ) -> PromptEnhancement:
+        skills = _select_skills(goal, project_root)
+        skills_intake = _full_intake(skills)
+        skills_brief = _compact_brief(skills)
+
+        prompt = f"""
+Original user goal:
+{goal}
+
+Repository map:
+{repo_map_json}
+
+Code review graph context:
+{graph_context_json or "{}"}
+
+Applicable engineering skills (senior-level domain intake for this codebase/goal):
+{skills_intake or "(no domain skills matched; rely on general engineering judgment)"}
+
+You are DevCouncil's codebase-specific prompt enhancer.
+Rewrite the user goal into a better planning prompt before it is sent to the council debate.
+
+Requirements:
+- Preserve the user's intent exactly; do not add unrelated features.
+- Make the goal specific to the mapped repository architecture, languages, tests, and likely ownership boundaries.
+- Fold the relevant skill intake into the goal and constraints like a senior engineer who
+  just briefed themselves: name the *current* recommended libraries/APIs, the deprecated
+  ones to avoid, the platform/SDK/toolchain versions to target, and the exact build/test
+  CLI commands that will prove the change. Only include skill points relevant to THIS goal.
+- Identify constraints the planners and critics must preserve.
+- Identify debate focus areas that should force useful disagreement between pragmatic and production-readiness plans.
+- Keep the enhanced_goal concise enough to be used as the goal for spec, planning, critique, and arbitration.
+"""
+        enhancement = await self.router.complete_structured(
+            role="prompt_enhancer",
+            messages=[{"role": "user", "content": prompt}],
+            schema=PromptEnhancement,
+            # If enhancement fails on a weak model, fall back to the raw goal —
+            # planning proceeds with the user's original intent unchanged.
+            fallback=PromptEnhancement(original_goal=goal, enhanced_goal=goal),
+        )
+        # Skill provenance is deterministic, not model-decided: stamp it after the call
+        # so the artifact/report shows exactly which skills shaped this plan.
+        return enhancement.normalized(goal).model_copy(
+            update={
+                "applied_skills": [skill.name for skill in skills],
+                "skills_brief": skills_brief,
+            }
+        )
+
+
+def _select_skills(goal: str, project_root: Path | None):
+    """Codebase-aware skill selection; never raises (skills are best-effort)."""
+    try:
+        from devcouncil.skills.registry import select_skills
+
+        return select_skills(goal=goal, project_root=project_root)
+    except Exception:
+        return []
+
+
+def _full_intake(skills: list) -> str:
+    """Full skill bodies (capped) for the one-shot enhancer call."""
+    if not skills:
+        return ""
+    blocks: list[str] = []
+    total = 0
+    for skill in skills[:_MAX_SKILLS_FOR_INTAKE]:
+        body = (getattr(skill, "body", "") or "").strip()
+        if not body:
+            continue
+        block = f"### Skill: {skill.name}\n{body}"
+        total += len(block)
+        if total > _MAX_INTAKE_CHARS:
+            break
+        blocks.append(block)
+    return "\n\n".join(blocks).strip()
+
+
+def _compact_brief(skills: list) -> str:
+    """One line per skill (name + description) for the council debate prompt."""
+    lines = []
+    for skill in skills:
+        description = (getattr(skill, "description", "") or "").strip()
+        lines.append(f"- **{skill.name}** — {description}" if description else f"- **{skill.name}**")
+    return "\n".join(lines).strip()
+
+
+def _clean_items(items: list[str]) -> list[str]:
+    return [item.strip() for item in items if item.strip()]

package/src/devcouncil/planning/repair_service.py

@@ -1,39 +1,39 @@
-from typing import List
-import json
-from pydantic import BaseModel
-from devcouncil.domain.gap import Gap
-from devcouncil.domain.task import Task
-from devcouncil.llm.router import ModelRouter
-
-class RepairOutput(BaseModel):
-    suggested_tasks: List[Task]
-
-class RepairService:
-    """Uses LLM to infer focused repair tasks from blocking gaps."""
-    
-    def __init__(self, router: ModelRouter):
-        self.router = router
-
-    async def generate_repair_plan(self, gaps: List[Gap], project_context: str) -> RepairOutput:
-        prompt = f"""
-The following blocking gaps were detected during verification.
-Gaps:
-{json.dumps([g.model_dump() for g in gaps], indent=2)}
-
-Project Context:
-{project_context}
-
-Your task is to generate focused implementation tasks to fix these gaps.
-- Each task must have a clear description and recommended fix.
-- Specify 'planned_files' that need modification (infer from gap evidence).
-- Link each task to the relevant 'requirement_id' mentioned in the gap.
-
-Return a JSON object with 'suggested_tasks'.
-"""
-        messages = [{"role": "user", "content": prompt}]
-        
-        return await self.router.complete_structured(
-            role="planner_a",  # Pragmatic tech lead is best suited for repair task generation
-            messages=messages,
-            schema=RepairOutput
-        )
+from typing import List
+import json
+from pydantic import BaseModel
+from devcouncil.domain.gap import Gap
+from devcouncil.domain.task import Task
+from devcouncil.llm.router import ModelRouter
+
+class RepairOutput(BaseModel):
+    suggested_tasks: List[Task]
+
+class RepairService:
+    """Uses LLM to infer focused repair tasks from blocking gaps."""
+    
+    def __init__(self, router: ModelRouter):
+        self.router = router
+
+    async def generate_repair_plan(self, gaps: List[Gap], project_context: str) -> RepairOutput:
+        prompt = f"""
+The following blocking gaps were detected during verification.
+Gaps:
+{json.dumps([g.model_dump() for g in gaps], indent=2)}
+
+Project Context:
+{project_context}
+
+Your task is to generate focused implementation tasks to fix these gaps.
+- Each task must have a clear description and recommended fix.
+- Specify 'planned_files' that need modification (infer from gap evidence).
+- Link each task to the relevant 'requirement_id' mentioned in the gap.
+
+Return a JSON object with 'suggested_tasks'.
+"""
+        messages = [{"role": "user", "content": prompt}]
+        
+        return await self.router.complete_structured(
+            role="planner_a",  # Pragmatic tech lead is best suited for repair task generation
+            messages=messages,
+            schema=RepairOutput
+        )

package/src/devcouncil/planning/spec_service.py

@@ -1,44 +1,70 @@
-from typing import List
-from pydantic import BaseModel
-from devcouncil.domain.requirement import Requirement
-from devcouncil.domain.assumption import Assumption
-from devcouncil.llm.router import ModelRouter
-
-class BlockingQuestion(BaseModel):
-    id: str
-    question: str
-    reason: str
-
-class SpecOutput(BaseModel):
-    requirements: List[Requirement]
-    assumptions: List[Assumption]
-    blocking_questions: List[BlockingQuestion]
-
-class SpecService:
-    def __init__(self, router: ModelRouter):
-        self.router = router
-
-    async def generate_spec(self, goal: str, repo_map_json: str) -> SpecOutput:
-        prompt = f"""
-Goal: {goal}
-
-Repository Map:
-{repo_map_json}
-
-Your task is to draft the initial software specification for this goal.
-1. Identify functional and non-functional requirements.
-2. Extract any assumptions you are making about the codebase or architecture.
-3. List any blocking questions that the user must answer before implementation can proceed.
-
-Each requirement MUST have clear acceptance criteria with verification methods.
-Each assumption MUST have a confidence and impact level.
-"""
-        messages = [
-            {"role": "user", "content": prompt}
-        ]
-        
-        return await self.router.complete_structured(
-            role="spec_writer",
-            messages=messages,
-            schema=SpecOutput
-        )
+from typing import List
+from pydantic import BaseModel
+from devcouncil.domain.requirement import Requirement
+from devcouncil.domain.assumption import Assumption
+from devcouncil.llm.router import ModelRouter
+
+class BlockingQuestion(BaseModel):
+    id: str
+    question: str
+    reason: str
+
+class SpecOutput(BaseModel):
+    requirements: List[Requirement]
+    assumptions: List[Assumption]
+    blocking_questions: List[BlockingQuestion]
+
+class SpecService:
+    def __init__(self, router: ModelRouter):
+        self.router = router
+
+    async def generate_spec(self, goal: str, repo_map_json: str) -> SpecOutput:
+        prompt = f"""
+Goal: {goal}
+
+Repository Map:
+{repo_map_json}
+
+Your task is to draft the initial software specification for this goal.
+1. Identify functional and non-functional requirements.
+2. Extract any assumptions you are making about the codebase or architecture.
+3. List any blocking questions that the user must answer before implementation can proceed.
+
+Each requirement MUST have clear, testable acceptance criteria with verification methods.
+Be RIGOROUS about edge cases — a terse goal hides most of the real requirements.
+For every behavior, add explicit acceptance criteria covering, where applicable:
+- the normal/happy path with concrete example inputs and expected outputs;
+- boundary and degenerate inputs (empty, single element, zero, negative, very large,
+  duplicate, already-sorted vs. unsorted, min/max);
+- invalid or malformed inputs and the EXACT expected error behavior (e.g. raises
+  ValueError/TypeError) rather than silent or undefined behavior;
+- non-mutation / no-unexpected-side-effects on inputs when the behavior is a pure
+  transformation;
+- correct result TYPE (e.g. float vs int) when it matters.
+Prefer several small, individually-verifiable acceptance criteria over one vague one.
+
+Acceptance criteria MUST assert observable BEHAVIOR — return values, raised exceptions,
+output, or side effects on supplied data — not repository state or tooling. DevCouncil's
+own gates enforce file scope, clean diffs, and planned-file limits, so do NOT write
+criteria about `git status`/`--porcelain` output, the exact set of changed/created files,
+`git show HEAD` byte/append-only contents, commit shape, or whether flake8/mypy/ruff/
+eslint/tsc/npm pass. Never require a tool the repo is not already configured for. Use the
+`static_check` verification method ONLY for behavior expressible as a runnable assertion
+(an importable function's result or raised exception), never to mean "a linter runs clean"
+or "these files exist". If a criterion genuinely cannot be proven by running code
+(architecture choices, repo scope, "works without extra configuration", subjective
+quality), give it verification_method "manual" — it will be surfaced for human review
+rather than block the automated gate. Prefer rewriting such a criterion as a concrete
+behavioral one whenever possible.
+
+Each assumption MUST have a confidence and impact level.
+"""
+        messages = [
+            {"role": "user", "content": prompt}
+        ]
+        
+        return await self.router.complete_structured(
+            role="spec_writer",
+            messages=messages,
+            schema=SpecOutput
+        )

package/src/devcouncil/repo/ci_scaffold.py

@@ -0,0 +1,157 @@
+"""Scaffold a starter GitHub Actions workflow for a target repository.
+
+DevCouncil already knows a project's test/lint/typecheck commands (config.yaml), so
+it can emit a sensible CI starter that runs them. The workflow is a *template* the
+user can adjust; scaffolding never overwrites an existing workflow unless forced.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from devcouncil.app.config import load_config
+
+WORKFLOW_RELPATH = Path(".github") / "workflows" / "devcouncil.yml"
+
+_PYTHON_TOOLS = {
+    "pytest", "flake8", "ruff", "mypy", "tox", "python", "python3", "uv",
+    "poetry", "black", "isort", "pyright",
+}
+_NODE_TOOLS = {
+    "npm", "npx", "pnpm", "yarn", "bun", "eslint", "tsc", "jest", "vitest", "node",
+}
+_PYTHON_MARKERS = ("pyproject.toml", "requirements.txt", "setup.py", "setup.cfg", "Pipfile")
+
+
+def detect_stacks(project_root: Path) -> set[str]:
+    """Best-effort detection of the language stacks present in the repo."""
+    stacks: set[str] = set()
+    if any((project_root / marker).exists() for marker in _PYTHON_MARKERS):
+        stacks.add("python")
+    if (project_root / "package.json").exists():
+        stacks.add("node")
+    return stacks
+
+
+def _command_stack(command: str) -> str | None:
+    tool = command.split()[0] if command.strip() else ""
+    if tool in _PYTHON_TOOLS:
+        return "python"
+    if tool in _NODE_TOOLS:
+        return "node"
+    return None
+
+
+def _applicable_commands(commands: list[str], stacks: set[str]) -> list[str]:
+    """Keep commands whose tool matches a detected stack; if none detected, keep all."""
+    if not stacks:
+        return list(commands)
+    kept = []
+    for command in commands:
+        stack = _command_stack(command)
+        if stack is None or stack in stacks:
+            kept.append(command)
+    return kept
+
+
+# Optional dependency-audit step per stack. Emitted only when the matching stack is
+# detected, so a Python-only repo never gets an npm audit (and vice versa). These are
+# non-blocking (continue-on-error) starters the user can tighten.
+_AUDIT_STEPS: dict[str, list[str]] = {
+    "python": [
+        "      - name: Dependency audit (pip-audit)",
+        "        continue-on-error: true",
+        "        run: pip-audit",
+    ],
+    "node": [
+        "      - name: Dependency audit (npm audit)",
+        "        continue-on-error: true",
+        "        run: npm audit --audit-level=high",
+    ],
+}
+
+
+def _add_audit_steps(steps: list[str], stacks: set[str]) -> None:
+    """Append an optional SCA audit step for each detected stack (only)."""
+    for stack in sorted(stacks):
+        steps.extend(_AUDIT_STEPS.get(stack, []))
+
+
+def _python_version(project_root: Path) -> str:
+    version_file = project_root / ".python-version"
+    if version_file.exists():
+        first = version_file.read_text(encoding="utf-8").strip().splitlines()
+        if first and first[0].strip():
+            return first[0].strip()
+    return "3.12"
+
+
+def render_workflow(project_root: Path, default_branch: str = "main") -> str:
+    """Render the workflow YAML text deterministically from config + detected stacks."""
+    config = load_config(project_root)
+    stacks = detect_stacks(project_root)
+    commands = config.commands
+
+    steps: list[str] = [
+        "      - name: Checkout",
+        "        uses: actions/checkout@v4",
+    ]
+    if "python" in stacks:
+        steps += [
+            "      - name: Set up Python",
+            "        uses: actions/setup-python@v5",
+            "        with:",
+            f'          python-version: "{_python_version(project_root)}"',
+        ]
+    if "node" in stacks:
+        steps += [
+            "      - name: Set up Node",
+            "        uses: actions/setup-node@v4",
+            "        with:",
+            '          node-version: "20"',
+        ]
+
+    def add_command_steps(label: str, raw_commands: list[str]) -> None:
+        for command in _applicable_commands(raw_commands, stacks):
+            steps.append(f"      - name: {label} ({command.split()[0]})")
+            steps.append(f"        run: {command}")
+
+    add_command_steps("Lint", commands.lint)
+    add_command_steps("Typecheck", commands.typecheck)
+    add_command_steps("Test", commands.test)
+    _add_audit_steps(steps, stacks)
+
+    body = "\n".join(steps)
+    return (
+        "# Starter CI workflow generated by DevCouncil from .devcouncil/config.yaml.\n"
+        "# Adjust the setup steps, dependency install, and commands for your stack.\n"
+        "name: DevCouncil CI\n"
+        "\n"
+        "on:\n"
+        "  push:\n"
+        f'    branches: ["{default_branch}"]\n'
+        "  pull_request:\n"
+        f'    branches: ["{default_branch}"]\n'
+        "\n"
+        "jobs:\n"
+        "  checks:\n"
+        "    runs-on: ubuntu-latest\n"
+        "    steps:\n"
+        f"{body}\n"
+    )
+
+
+def scaffold_ci(project_root: Path, force: bool = False) -> Path | None:
+    """Write the starter workflow. Returns the path, or None if one already exists.
+
+    Does not overwrite an existing ``.github/workflows/devcouncil.yml`` unless
+    ``force`` is set, so re-running is safe and user edits are preserved.
+    """
+    project_root = project_root.resolve()
+    target = project_root / WORKFLOW_RELPATH
+    if target.exists() and not force:
+        return None
+    default_branch = load_config(project_root).project.default_branch or "main"
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(render_workflow(project_root, default_branch), encoding="utf-8")
+    return target

package/src/devcouncil/repo/gitignore.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+
+GITIGNORE_SECTIONS: tuple[tuple[str, tuple[str, ...]], ...] = (
+    (
+        "DevCouncil local state",
+        (
+            ".devcouncil/*",
+            "!.devcouncil/",
+            "!.devcouncil/config.yaml",
+            "!.devcouncil/graphify.yaml",
+        ),
+    ),
+    (
+        "Local AI coding agents",
+        (
+            ".agents/",
+            ".codex/",
+            ".aider*",
+            ".gemini/",
+            ".claude*",
+            ".cursor/",
+            ".openhands/",
+            ".opencode/",
+            ".conductor/",
+            ".conducor/",
+            ".antigravity/",
+            ".warp/",
+            ".gitnexus",
+        ),
+    ),
+    (
+        "Generated workspace guides (regenerated by 'dev map')",
+        (
+            "AGENTS.md",
+            "CLAUDE.md",
+        ),
+    ),
+    (
+        "Secrets and local databases",
+        (
+            "*.sqlite",
+            "*.sqlite-wal",
+            "*.sqlite-shm",
+            "*.db",
+        ),
+    ),
+    (
+        "Temporary, log, and dump artifacts",
+        (
+            "logs/",
+            "log/",
+            "tmp/",
+            "temp/",
+            ".tmp/",
+            ".temp/",
+            "scratch/",
+            "dumps/",
+            "dump/",
+            "*.tmp",
+            "*.temp",
+            "*.log",
+            "*.dmp",
+            "*.dump",
+            "*.bak",
+            "*.swp",
+            "*_results.txt",
+            "*_log.txt",
+            "*_output.txt",
+        ),
+    ),
+    (
+        "Environment, dependency, and cache directories",
+        (
+            "__pycache__/",
+            "*.py[cod]",
+            ".venv/",
+            "venv/",
+            "node_modules/",
+            ".env",
+            ".env.local",
+            ".env.*",
+            "!.env.example",
+            ".pytest_cache/",
+            ".mypy_cache/",
+            ".ruff_cache/",
+            ".DS_Store",
+            "Thumbs.db",
+        ),
+    ),
+)
+
+
+def ensure_gitignore(project_root: Path) -> None:
+    gitignore_path = project_root / ".gitignore"
+    content = ""
+    if gitignore_path.exists():
+        try:
+            content = gitignore_path.read_text(encoding="utf-8")
+        except OSError:
+            return
+
+    existing_rules = {line.strip() for line in content.splitlines() if line.strip()}
+    chunks: list[str] = []
+    for heading, rules in GITIGNORE_SECTIONS:
+        missing_rules = [rule for rule in rules if rule not in existing_rules]
+        if missing_rules:
+            chunks.append("\n".join([f"# {heading}", *missing_rules]))
+
+    if not chunks:
+        return
+
+    prefix = ""
+    if content:
+        prefix = "" if content.endswith("\n") else "\n"
+        prefix += "\n"
+
+    try:
+        gitignore_path.write_text(content + prefix + "\n\n".join(chunks) + "\n", encoding="utf-8")
+    except OSError:
+        return