devcouncil 0.1.1 → 0.3.0

package/src/devcouncil/planning/prompt_enhancer_service.py

@@ -1,7 +1,17 @@
+import logging
+from pathlib import Path
+
 from pydantic import BaseModel, Field
 
 from devcouncil.llm.router import ModelRouter
 
+logger = logging.getLogger(__name__)
+
+# 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
@@ -9,6 +19,17 @@ class PromptEnhancement(BaseModel):
     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 = ""
+    # Curated project knowledge (Open Knowledge Format bundles) and the project design
+    # system (design.md), selected from ``.devcouncil/knowledge`` for this goal. Like the
+    # skills fields, set deterministically after the model call.
+    applied_knowledge: list[str] = Field(default_factory=list)
+    knowledge_brief: str = ""
 
     def normalized(self, original_goal: str) -> "PromptEnhancement":
         enhanced_goal = self.enhanced_goal.strip() or original_goal
@@ -41,9 +62,74 @@ class PromptEnhancement(BaseModel):
         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,
+            ])
+        if self.knowledge_brief:
+            sections.extend([
+                "",
+                "## Project knowledge & design system (ground the plan in these)",
+                "Curated org/domain knowledge (Open Knowledge Format) and the project's "
+                "design.md. Honor design tokens/components and reuse known facts rather than "
+                "re-deriving or contradicting them.",
+                self.knowledge_brief,
+            ])
         return "\n".join(sections)
 
 
+# Stable copy of the enhancement that produced the CURRENTLY ACTIVE plan. Written when a
+# plan is persisted, so the executor reads the guidance tied to the plan it is running —
+# not whichever run happens to have the newest mtime (a later dry-run/replan would otherwise
+# win). Lives next to the plan state under .devcouncil/.
+_ACTIVE_ENHANCEMENT_FILE = "active_prompt_enhancement.json"
+
+
+def load_latest_prompt_enhancement(project_root: Path) -> "PromptEnhancement | None":
+    """Load the prompt-enhancement for the active plan, or None.
+
+    Prefers the stable ``.devcouncil/active_prompt_enhancement.json`` written when the plan
+    was persisted (so the executor gets the guidance tied to the plan it is running). Falls
+    back to the most recent per-run artifact for plans persisted before that file existed.
+    Best-effort: any read/parse failure returns None so prompt building never breaks."""
+    import json
+
+    def _load(path: Path) -> "PromptEnhancement | None":
+        try:
+            return PromptEnhancement.model_validate(json.loads(path.read_text(encoding="utf-8")))
+        except Exception:
+            return None
+
+    active = project_root / ".devcouncil" / _ACTIVE_ENHANCEMENT_FILE
+    if active.is_file():
+        loaded = _load(active)
+        if loaded is not None:
+            return loaded
+
+    runs = project_root / ".devcouncil" / "runs"
+    if not runs.exists():
+        return None
+    artifacts = [d / "prompt_enhancement.json" for d in runs.iterdir() if (d / "prompt_enhancement.json").is_file()]
+    if not artifacts:
+        return None
+    return _load(max(artifacts, key=lambda p: p.stat().st_mtime))
+
+
+def save_active_prompt_enhancement(project_root: Path, enhancement: "PromptEnhancement") -> None:
+    """Persist the enhancement for the active plan to the stable path. Best-effort."""
+    try:
+        path = project_root / ".devcouncil" / _ACTIVE_ENHANCEMENT_FILE
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(enhancement.model_dump_json(indent=2), encoding="utf-8")
+    except Exception:
+        pass
+
+
 class PromptEnhancerService:
     def __init__(self, router: ModelRouter):
         self.router = router
@@ -53,7 +139,18 @@ class PromptEnhancerService:
         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)
+        if skills:
+            logger.info("Prompt enhancer matched %d skill(s): %s", len(skills), ", ".join(s.name for s in skills))
+
+        knowledge = _select_knowledge(goal, project_root)
+        knowledge_intake = _knowledge_intake(knowledge)
+        knowledge_brief = _knowledge_brief(knowledge)
+
         prompt = f"""
 Original user goal:
 {goal}
@@ -64,12 +161,22 @@ Repository map:
 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)"}
+
+Project knowledge & design system (curated facts and design tokens for this codebase):
+{knowledge_intake or "(no project knowledge ingested)"}
+
 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.
@@ -78,8 +185,106 @@ Requirements:
             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),
         )
-        return enhancement.normalized(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,
+                "applied_knowledge": [source.name for source in knowledge],
+                "knowledge_brief": knowledge_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 _select_knowledge(goal: str, project_root: Path | None):
+    """OKF/design knowledge selection for planning; never raises (best-effort)."""
+    if project_root is None:
+        return []
+    try:
+        from devcouncil.app.config import load_config
+        from devcouncil.knowledge.sources import select_knowledge_sources
+
+        cfg = load_config(project_root).knowledge
+        if not cfg.enabled:
+            return []
+        return select_knowledge_sources(
+            goal=goal, project_root=project_root,
+            directory=cfg.directory, design_always=cfg.design_always,
+        )
+    except Exception:
+        return []
+
+
+def _knowledge_intake(sources: list) -> str:
+    """Full knowledge bodies (capped) for the one-shot enhancer call."""
+    if not sources:
+        return ""
+    blocks: list[str] = []
+    total = 0
+    for source in sources[:_MAX_SKILLS_FOR_INTAKE]:
+        body = (getattr(source, "body", "") or "").strip()
+        if not body:
+            continue
+        kind = getattr(source, "kind", "knowledge")
+        block = f"### {kind}: {getattr(source, 'name', '')}\n{body}"
+        total += len(block)
+        if total > _MAX_INTAKE_CHARS:
+            break
+        blocks.append(block)
+    return "\n\n".join(blocks).strip()
+
+
+def _knowledge_brief(sources: list) -> str:
+    """One line per knowledge source (kind + name + description) for the debate prompt."""
+    lines = []
+    for source in sources:
+        description = (getattr(source, "description", "") or "").strip()
+        kind = getattr(source, "kind", "knowledge")
+        head = f"- **{getattr(source, 'name', '')}** ({kind})"
+        lines.append(f"{head} — {description}" if description else head)
+    return "\n".join(lines).strip()
 
 
 def _clean_items(items: list[str]) -> list[str]:

package/src/devcouncil/planning/repair_service.py

@@ -1,10 +1,13 @@
 from typing import List
 import json
+import logging
 from pydantic import BaseModel
 from devcouncil.domain.gap import Gap
 from devcouncil.domain.task import Task
 from devcouncil.llm.router import ModelRouter
 
+logger = logging.getLogger(__name__)
+
 class RepairOutput(BaseModel):
     suggested_tasks: List[Task]
 
@@ -31,9 +34,12 @@ Your task is to generate focused implementation tasks to fix these gaps.
 Return a JSON object with 'suggested_tasks'.
 """
         messages = [{"role": "user", "content": prompt}]
-        
-        return await self.router.complete_structured(
+
+        logger.info("Generating repair plan from %d gap(s)", len(gaps))
+        result = await self.router.complete_structured(
             role="planner_a",  # Pragmatic tech lead is best suited for repair task generation
             messages=messages,
             schema=RepairOutput
         )
+        logger.info("Repair plan: %d suggested task(s)", len(result.suggested_tasks))
+        return result

package/src/devcouncil/planning/spec_service.py

@@ -1,9 +1,12 @@
+import logging
 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
 
+logger = logging.getLogger(__name__)
+
 class BlockingQuestion(BaseModel):
     id: str
     question: str
@@ -30,15 +33,46 @@ Your task is to draft the initial software specification for this goal.
 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 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(
+
+        result = await self.router.complete_structured(
             role="spec_writer",
             messages=messages,
             schema=SpecOutput
         )
+        logger.info(
+            "Spec generated: %d requirement(s), %d assumption(s), %d blocking question(s)",
+            len(result.requirements), len(result.assumptions), len(result.blocking_questions),
+        )
+        return result

package/src/devcouncil/repo/ci_scaffold.py

@@ -0,0 +1,165 @@
+"""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 DevCouncilConfig, 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",
+    config: DevCouncilConfig | None = None,
+) -> str:
+    """Render the workflow YAML text deterministically from config + detected stacks."""
+    if config is None:
+        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
+    config = load_config(project_root)
+    default_branch = config.project.default_branch or "main"
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(
+        render_workflow(project_root, default_branch, config), 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