devcouncil 0.1.1 → 0.2.0

package/src/devcouncil/planning/correction_manifest.py

@@ -0,0 +1,303 @@
+"""Correction manifest generation for repair loops."""
+
+from __future__ import annotations
+
+import json
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+from devcouncil.app.config import load_config
+from devcouncil.domain.gap import Gap
+from devcouncil.domain.task import Task
+from devcouncil.storage.db import get_db
+from devcouncil.storage.native import CorrectionManifestRepository
+from devcouncil.storage.repositories import EvidenceRepository, GapRepository, TaskRepository
+from devcouncil.utils.redaction import redact_text
+
+# Bounds for the prior-attempt context folded into the manifest. These reach the
+# next executor's prompt verbatim, so they must stay small enough not to crowd out
+# the task spec / blow the context window while still carrying the signal the agent
+# needs (what it changed last time, and why verification rejected it).
+_MAX_PRIOR_DIFF_CHARS = 8000
+_MAX_FAILING_OUTPUT_CHARS = 4000
+# Per failed command, how much of the captured stdout/stderr tail to keep. Test
+# runners put the actual assertion/traceback at the end, so we keep the tail.
+_MAX_PER_COMMAND_OUTPUT_CHARS = 1500
+
+
+class CorrectionManifest(BaseModel):
+    task_id: str
+    root_cause: str
+    failed_evidence: list[str] = Field(default_factory=list)
+    allowed_repair_files: list[str] = Field(default_factory=list)
+    forbidden_changes: list[str] = Field(default_factory=list)
+    commands_to_rerun: list[str] = Field(default_factory=list)
+    prior_failed_attempts: int = 0
+    retry_budget: int = 3
+    executor_recommendation: str = "manual"
+    created_at: str
+    # Blocking gaps ordered most-actionable-first (severity, then gap-type priority),
+    # so the repair loop is steered at the real defect (a failing test) rather than an
+    # arbitrary first gap (e.g. an orphan_diff). The first entry is the root_cause.
+    ordered_blocking_gaps: list[str] = Field(default_factory=list)
+    # Prior-attempt context (optional, backward-compatible). Without these the repair
+    # executor only sees the root_cause text and re-derives the same wrong approach
+    # blind. ``prior_diff`` is what the previous attempt actually changed; it lets the
+    # agent see (and stop re-applying) its rejected edit. ``failing_output`` is the
+    # captured failing test / verification output that explains *why* it was rejected.
+    # Both are redacted and size-bounded before being written.
+    prior_diff: str = ""
+    failing_output: str = ""
+
+
+# Severity ordering: most severe first.
+_SEVERITY_RANK = {"critical": 0, "high": 1, "medium": 2, "low": 3}
+
+# Gap-type priority within a severity band. Lower sorts first. Executable-evidence
+# failures (a failing test / unproven acceptance criterion) are the real defect signal
+# and must outrank scope (orphan/dependency) and advisory (review/secret) gaps so the
+# repair loop targets the failing test, not an orphan_diff.
+_GAP_TYPE_PRIORITY = {
+    "test_failed": 0,
+    "acceptance_criteria_unproven": 1,
+    "diff_not_exercised": 1,
+    "task_not_implemented": 2,
+    "migration_gap": 2,
+    "orphan_diff": 3,
+    "planned_file_not_changed": 3,
+    "dependency_risk": 3,
+    "architecture_drift": 4,
+    "assumption_violated": 4,
+    "security_risk": 5,
+}
+
+
+def _ordered_blocking_gaps(blocking_gaps: list[Gap]) -> list[Gap]:
+    """Stable-sort blocking gaps by (severity, gap-type priority).
+
+    ``test_failed`` / ``acceptance_*`` gaps come before orphan/dependency before
+    review/secret, so the picked root_cause is the failing behavior rather than an
+    incidental scope finding. Unknown severities/types sort last (defensive)."""
+    return sorted(
+        blocking_gaps,
+        key=lambda g: (
+            _SEVERITY_RANK.get(g.severity, 9),
+            _GAP_TYPE_PRIORITY.get(g.gap_type, 9),
+        ),
+    )
+
+
+def _latest_agent_run(project_root: Path, task_id: str) -> dict | None:
+    runs_dir = project_root / ".devcouncil" / "runs"
+    if not runs_dir.exists():
+        return None
+    candidates = sorted(runs_dir.glob("*/agent-run.json"), reverse=True)
+    for path in candidates:
+        try:
+            payload = json.loads(path.read_text(encoding="utf-8"))
+        except Exception:
+            continue
+        if payload.get("task_id") == task_id:
+            return payload
+    return None
+
+
+def _truncate_tail(text: str, limit: int) -> str:
+    """Keep the last ``limit`` chars of ``text`` (the actionable tail of test output),
+    prefixing a marker when truncated. Empty/whitespace input returns ""."""
+    text = (text or "").strip()
+    if len(text) <= limit:
+        return text
+    return "[devcouncil: output truncated, showing last "f"{limit} chars]\n" + text[-limit:]
+
+
+def _truncate_head(text: str, limit: int) -> str:
+    """Keep the first ``limit`` chars of ``text`` (diffs read top-down), with a marker
+    when truncated. Empty/whitespace input returns ""."""
+    text = (text or "").strip()
+    if len(text) <= limit:
+        return text
+    return text[:limit] + "\n[devcouncil: diff truncated, "f"{len(text) - limit} chars omitted]"
+
+
+def _read_text_tail(path: Path, limit: int) -> str:
+    """Best-effort read of a captured stdout/stderr file, keeping its tail. Never raises."""
+    try:
+        if not path.is_file():
+            return ""
+        return _truncate_tail(path.read_text(encoding="utf-8", errors="replace"), limit)
+    except Exception:
+        return ""
+
+
+def _collect_prior_diff(project_root: Path, task_id: str) -> str:
+    """The prior attempt's working-tree diff, from the task's ``after`` checkpoint patch.
+
+    The checkpoint service writes ``<task_id>-after.patch`` after each executor run, so
+    this is exactly what the previous attempt changed. Redacted and head-bounded so the
+    repair executor can see (and avoid re-applying) its rejected edit without the diff
+    swamping the prompt. Returns "" when no patch exists (e.g. first attempt)."""
+    patch_path = project_root / ".devcouncil" / "checkpoints" / f"{task_id}-after.patch"
+    try:
+        if not patch_path.is_file():
+            return ""
+        raw = patch_path.read_text(encoding="utf-8", errors="replace")
+    except Exception:
+        return ""
+    return _truncate_head(redact_text(raw), _MAX_PRIOR_DIFF_CHARS)
+
+
+def _collect_failing_output(project_root: Path, failed_results) -> str:
+    """The captured stdout/stderr of the failing verification commands.
+
+    Folds each failed command's summary plus the tail of its captured stdout/stderr so
+    the repair executor sees *why* it was rejected (the actual assertion / traceback),
+    not just that a command exited non-zero. Redacted and size-bounded. Returns ""
+    when there is nothing useful to show."""
+    blocks: list[str] = []
+    for result in failed_results:
+        parts = [f"$ {result.command} (exit {result.exit_code})"]
+        if result.summary and result.summary.strip():
+            parts.append(result.summary.strip())
+        for label, rel in (("stdout", result.stdout_path), ("stderr", result.stderr_path)):
+            if not rel:
+                continue
+            path = Path(rel)
+            if not path.is_absolute():
+                path = project_root / rel
+            tail = _read_text_tail(path, _MAX_PER_COMMAND_OUTPUT_CHARS)
+            if tail:
+                parts.append(f"--- {label} ---\n{tail}")
+        blocks.append("\n".join(parts))
+    if not blocks:
+        return ""
+    return _truncate_tail(redact_text("\n\n".join(blocks)), _MAX_FAILING_OUTPUT_CHARS)
+
+
+def build_correction_manifest(
+    project_root: Path,
+    task: Task,
+    blocking_gaps: list[Gap],
+    *,
+    repair_service=None,
+    prior_attempts: int = 0,
+) -> CorrectionManifest:
+    config = load_config(project_root)
+    failed: list[str] = []
+    failed_results: list = []
+    db = get_db(project_root)
+    if db:
+        with db.get_session() as session:
+            # Scope failed evidence to THIS task. Scanning every evidence row made a
+            # repair for one task chase unrelated failures from another, so the loop
+            # never converged on the real defect.
+            for result in EvidenceRepository(session).get_command_results_for_task(task.id):
+                if result.exit_code != 0:
+                    failed.append(f"{result.command} (exit {result.exit_code})")
+                    failed_results.append(result)
+
+    # Steer the repair at the most actionable failure (a failing test / unproven AC),
+    # not an arbitrary first gap such as an orphan_diff.
+    ordered_gaps = _ordered_blocking_gaps(blocking_gaps)
+    root_cause = ordered_gaps[0].description if ordered_gaps else "Unknown failure"
+    manifest = CorrectionManifest(
+        task_id=task.id,
+        root_cause=root_cause,
+        ordered_blocking_gaps=[g.description for g in ordered_gaps],
+        failed_evidence=failed,
+        allowed_repair_files=[pf.path for pf in task.planned_files],
+        forbidden_changes=list(task.forbidden_changes),
+        commands_to_rerun=task.expected_tests or task.allowed_commands,
+        # The number of repair attempts already made on this task — real, not a
+        # hardcoded 0. The agent sees how much of its budget is spent so it knows
+        # when to change approach rather than retry the same fix.
+        prior_failed_attempts=prior_attempts,
+        retry_budget=config.execution.max_repair_attempts,
+        executor_recommendation=config.execution.default_executor,
+        created_at=datetime.now(timezone.utc).isoformat(),
+        # Prior-attempt context so the next executor repairs against what actually
+        # happened (its rejected diff + the failing output) instead of re-deriving
+        # the same wrong approach blind. Both are redacted and size-bounded.
+        prior_diff=_collect_prior_diff(project_root, task.id),
+        failing_output=_collect_failing_output(project_root, failed_results),
+    )
+
+    if repair_service is not None:
+        try:
+            import asyncio
+
+            plan = asyncio.run(repair_service.generate_repair_plan(blocking_gaps, task.description))
+            if plan.suggested_tasks:
+                suggested = plan.suggested_tasks[0]
+                manifest.root_cause = suggested.description or manifest.root_cause
+                # Use the repair plan's concrete scope instead of throwing it away:
+                # union its targeted files/tests with the task's so the re-implement
+                # step focuses on what actually needs fixing without losing task scope.
+                manifest.allowed_repair_files = _union(
+                    manifest.allowed_repair_files, [pf.path for pf in suggested.planned_files]
+                )
+                manifest.commands_to_rerun = _union(manifest.commands_to_rerun, suggested.expected_tests)
+        except Exception:
+            pass
+    return manifest
+
+
+def _union(base: list[str], extra: list[str]) -> list[str]:
+    """Append items from ``extra`` not already in ``base`` (order-preserving dedupe)."""
+    merged = list(base)
+    for item in extra:
+        if item and item not in merged:
+            merged.append(item)
+    return merged
+
+
+def write_correction_manifest(project_root: Path, task_id: str, *, repair_service=None) -> Path | None:
+    db = get_db(project_root)
+    if not db:
+        return None
+    with db.get_session() as session:
+        task = TaskRepository(session).get_by_id(task_id)
+        if not task:
+            return None
+        gaps = [g for g in GapRepository(session).get_all() if g.task_id == task_id and g.blocking]
+        if not gaps:
+            return None
+        prior_record = CorrectionManifestRepository(session).latest_for_task(task_id)
+        prior_attempts = (prior_record.attempt + 1) if prior_record else 1
+
+    manifest = build_correction_manifest(
+        project_root, task, gaps, repair_service=repair_service, prior_attempts=prior_attempts
+    )
+    run_id = str(uuid.uuid4())
+    run_dir = project_root / ".devcouncil" / "runs" / run_id
+    run_dir.mkdir(parents=True, exist_ok=True)
+    path = run_dir / "correction-manifest.json"
+    path.write_text(manifest.model_dump_json(indent=2), encoding="utf-8")
+
+    with db.get_session() as session:
+        CorrectionManifestRepository(session).save(
+            task_id,
+            str(path),
+            "open",
+            run_id=run_id,
+            retry_budget=manifest.retry_budget,
+            attempt=manifest.prior_failed_attempts,
+        )
+    return path
+
+
+def load_latest_correction_manifest(project_root: Path, task_id: str) -> CorrectionManifest | None:
+    db = get_db(project_root)
+    if not db:
+        return None
+    with db.get_session() as session:
+        record = CorrectionManifestRepository(session).latest_for_task(task_id)
+        if not record:
+            return None
+        path = Path(record.manifest_path)
+        if not path.exists():
+            return None
+        return CorrectionManifest.model_validate(json.loads(path.read_text(encoding="utf-8")))

package/src/devcouncil/planning/critique_service.py

@@ -39,7 +39,10 @@ Every finding must include a falsifiable_check.
         return await self.router.complete_structured(
             role=role,
             messages=messages,
-            schema=CritiqueOutput
+            schema=CritiqueOutput,
+            # Degrade gracefully on weaker models: an un-critiqued plan is still a
+            # usable plan, far better than crashing the whole planning run.
+            fallback=CritiqueOutput(findings=[]),
         )
 
     async def generate_rebuttal(self, role: str, original_plan_json: str, findings_json: str) -> RebuttalOutput:
@@ -62,5 +65,7 @@ You are the planner who created the original plan. Review the critique findings.
         return await self.router.complete_structured(
             role=role,
             messages=messages,
-            schema=RebuttalOutput
+            schema=RebuttalOutput,
+            # No rebuttals means findings stand as-is — a safe, conservative default.
+            fallback=RebuttalOutput(rebuttals=[]),
         )

package/src/devcouncil/planning/plan_service.py

@@ -23,9 +23,23 @@ Repository Map:
 {repo_map_json}
 
 Your task is to create a detailed implementation plan.
-- Break down the requirements into atomic implementation tasks.
-- For each task, specify which files will be created or modified.
-- Specify which tests are expected to verify the task.
+- Break down the requirements into atomic implementation tasks, but use the FEWEST
+  tasks that cover them — do NOT over-decompose. A small goal (e.g. add one function
+  plus its test) is typically one or two tasks, not four.
+- Each file's changes must be OWNED BY A SINGLE TASK. Never create two tasks that both
+  create/modify the same file — that causes duplicate or conflicting edits. If work on
+  a file spans concerns, keep it in one task or split by FILE, not by sub-edit.
+- For each task, specify which files will be created or modified. Every implementation
+  task must declare at least one writable (create/modify) planned file — a task that
+  only reads files cannot implement anything.
+- Fill expected_tests with RUNNABLE shell commands (not prose) that exit 0 iff the
+  task's acceptance criteria hold and can run immediately after THIS task with no
+  missing tools or files. Prove BEHAVIOR with self-contained inline assertions, e.g.
+  python -c "import calc; assert calc.add(2,3)==5". Use pytest only on a whole test
+  file this or an earlier task creates (python -m pytest tests/test_x.py -q), never a
+  ::node id. Do NOT assert repository/git state (git status, changed-file sets,
+  append-only contents) and do NOT invoke flake8/mypy/ruff/eslint/tsc/npm unless the
+  repo is already configured for them.
 - Ensure each task maps back to at least one requirement.
 
 Role-specific instructions:

package/src/devcouncil/planning/prompt_enhancer_service.py

@@ -1,7 +1,14 @@
+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
@@ -9,6 +16,12 @@ 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 = ""
 
     def normalized(self, original_goal: str) -> "PromptEnhancement":
         enhanced_goal = self.enhanced_goal.strip() or original_goal
@@ -41,6 +54,15 @@ 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,
+            ])
         return "\n".join(sections)
 
 
@@ -53,7 +75,12 @@ 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)
+
         prompt = f"""
 Original user goal:
 {goal}
@@ -64,12 +91,19 @@ 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)"}
+
 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 +112,55 @@ 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),
+        )
+        # 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,
+            }
         )
-        return enhancement.normalized(goal)
+
+
+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]:

package/src/devcouncil/planning/spec_service.py

@@ -30,7 +30,33 @@ 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 = [

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