devcouncil 0.3.0 → 0.4.0

package/src/devcouncil/planning/arbiter_service.py

@@ -1,6 +1,6 @@
 import logging
 from typing import List, Dict
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 from devcouncil.domain.requirement import Requirement
 from devcouncil.domain.task import Task
 from devcouncil.llm.router import ModelRouter
@@ -8,8 +8,13 @@ from devcouncil.llm.router import ModelRouter
 logger = logging.getLogger(__name__)
 
 class ArbiterDecision(BaseModel):
-    accepted_finding_ids: List[str]
-    rejected_finding_ids: List[Dict[str, str]] # id, reason
+    # Empty finding lists are routinely OMITTED (not sent as "[]") by models on
+    # providers without grammar-constrained decoding; an absent empty list is
+    # not an arbitration failure, so default instead of crashing the run.
+    # final_requirements/final_tasks stay required — a decision without them is
+    # a real failure the healing/retry path must surface.
+    accepted_finding_ids: List[str] = Field(default_factory=list)
+    rejected_finding_ids: List[Dict[str, str]] = Field(default_factory=list)  # id, reason
     final_requirements: List[Requirement]
     final_tasks: List[Task]
 
@@ -48,6 +53,10 @@ You are the arbiter engineering manager. Your goal is to produce the final, defi
 - High-severity unrefuted findings from critics must be incorporated into the final requirements or tasks.
 - If a planner successfully rebutted a finding, you may skip it.
 - Produce a single, coherent task graph.
+- Set each task's ``difficulty`` field to ``easy``, ``normal``, or ``hard`` based on scope
+  (files touched, acceptance criteria count, cross-cutting concerns). Hard tasks get
+  stricter verification — prefer splitting work that would score hard into smaller tasks.
+- Mention ``scaffolding`` in a task description only when intentional placeholders are expected.
 """
         messages = [
             {"role": "user", "content": prompt}

package/src/devcouncil/planning/correction_manifest.py

@@ -2,11 +2,11 @@
 
 from __future__ import annotations
 
-import json
 import logging
 import uuid
 from datetime import datetime, timezone
 from pathlib import Path
+from typing import Any, cast
 
 from pydantic import BaseModel, Field
 
@@ -17,6 +17,7 @@ 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
+from devcouncil.utils.json_persist import read_json, read_model_json, write_model_json
 
 logger = logging.getLogger(__name__)
 
@@ -54,6 +55,17 @@ class CorrectionManifest(BaseModel):
     # Both are redacted and size-bounded before being written.
     prior_diff: str = ""
     failing_output: str = ""
+    # One line per prior repair attempt (root cause it targeted + whether the
+    # blocking gaps changed afterwards), carried forward from the previous manifest
+    # so the agent sees its own trajectory instead of rediscovering it.
+    attempt_history: list[str] = Field(default_factory=list)
+    # Deterministic strategy guidance derived from the attempt state: "change
+    # approach" when the same gaps reproduced, "final attempt — analyze, don't
+    # stub" when the budget is nearly spent. Empty on a first attempt.
+    approach_guidance: str = ""
+    # ``file:line reason`` for every stub/placeholder the verifier detected, so the
+    # repair prompt names the exact placeholders to replace.
+    stub_findings: list[str] = Field(default_factory=list)
 
 
 # Severity ordering: most severe first.
@@ -89,7 +101,13 @@ def remediable_incomplete_gaps(all_gaps: list[Gap]) -> list[Gap]:
 _GAP_TYPE_PRIORITY = {
     "test_failed": 0,
     "acceptance_criteria_unproven": 1,
+    "coarse_acceptance_proof": 1,
     "diff_not_exercised": 1,
+    "stub_detected": 1,
+    "unwired_file": 1,
+    "dead_symbol": 1,
+    "stranded_code": 1,
+    "stub_declared": 4,
     "task_not_implemented": 2,
     "migration_gap": 2,
     "orphan_diff": 3,
@@ -97,6 +115,7 @@ _GAP_TYPE_PRIORITY = {
     "dependency_risk": 3,
     "architecture_drift": 4,
     "assumption_violated": 4,
+    "suspicious_effort": 4,
     "security_risk": 5,
 }
 
@@ -123,11 +142,11 @@ def _latest_agent_run(project_root: Path, task_id: str) -> dict | 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"))
+            payload = read_json(path)
         except Exception:
             continue
         if payload.get("task_id") == task_id:
-            return payload
+            return cast(dict[Any, Any], payload)
     return None
 
 
@@ -203,6 +222,51 @@ def _collect_failing_output(project_root: Path, failed_results) -> str:
     return _truncate_tail(redact_text("\n\n".join(blocks)), _MAX_FAILING_OUTPUT_CHARS)
 
 
+REPAIR_RULES = (
+    "## Repair rules (non-negotiable)\n"
+    "1. Only claim completion after every command in `commands_to_rerun` passes locally; "
+    "a claim without fresh passing evidence will be rejected by verification.\n"
+    "2. Never delete, skip, or weaken a test (or an assertion) to make verification pass.\n"
+    "3. Never satisfy a gap with a stub, placeholder, TODO, or hardcoded special-case.\n"
+    "4. If `prior_diff` is present, your previous edit was REJECTED — read `failing_output` "
+    "and fix the root cause; do not re-apply the same change.\n"
+    "5. If the criterion genuinely cannot be met, say so explicitly and explain what is "
+    "missing instead of faking progress.\n"
+)
+
+
+def _build_attempt_history(prior: "CorrectionManifest | None", *, gaps_identical: bool) -> list[str]:
+    """Carry the prior manifest's history forward and append one line for the attempt
+    that just failed. Empty on a first repair."""
+    if prior is None:
+        return []
+    history = list(prior.attempt_history)
+    outcome = "identical blocking gaps reproduced" if gaps_identical else "blocking gaps changed"
+    history.append(
+        f"attempt {max(1, prior.prior_failed_attempts)}: targeted '{prior.root_cause[:160]}'; {outcome}"
+    )
+    # Bounded so a long-running loop cannot swell the manifest.
+    return history[-10:]
+
+
+def _build_approach_guidance(
+    prior: "CorrectionManifest | None", prior_attempts: int, retry_budget: int, *, gaps_identical: bool
+) -> str:
+    parts: list[str] = []
+    if prior is not None and gaps_identical:
+        parts.append(
+            "Your previous approach failed the same way (identical blocking gaps). Do NOT "
+            "retry the same edit; re-read the failing output and change strategy."
+        )
+    if retry_budget and prior_attempts >= retry_budget:
+        parts.append(
+            "This is the FINAL budgeted attempt. If an acceptance criterion cannot be met, "
+            "leave a clear written analysis of why (and what is missing) instead of "
+            "stubbing code or weakening tests."
+        )
+    return " ".join(parts)
+
+
 def build_correction_manifest(
     project_root: Path,
     task: Task,
@@ -211,6 +275,7 @@ def build_correction_manifest(
     repair_service=None,
     prior_attempts: int = 0,
     config=None,
+    prior_manifest: "CorrectionManifest | None" = None,
 ) -> CorrectionManifest:
     # ``config`` may be threaded in by a caller that already loaded it (e.g. the repair
     # loop, which would otherwise reload config from disk on every attempt). Fall back
@@ -234,10 +299,16 @@ def build_correction_manifest(
     # 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"
+    ordered_descriptions = [g.description for g in ordered_gaps]
+    gaps_identical = bool(
+        prior_manifest is not None
+        and prior_manifest.ordered_blocking_gaps == ordered_descriptions
+    )
+    retry_budget = config.execution.max_repair_attempts
     manifest = CorrectionManifest(
         task_id=task.id,
         root_cause=root_cause,
-        ordered_blocking_gaps=[g.description for g in ordered_gaps],
+        ordered_blocking_gaps=ordered_descriptions,
         failed_evidence=failed,
         allowed_repair_files=[pf.path for pf in task.planned_files],
         forbidden_changes=list(task.forbidden_changes),
@@ -246,7 +317,7 @@ def build_correction_manifest(
         # 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,
+        retry_budget=retry_budget,
         executor_recommendation=config.execution.default_executor,
         created_at=datetime.now(timezone.utc).isoformat(),
         # Prior-attempt context so the next executor repairs against what actually
@@ -254,6 +325,15 @@ def build_correction_manifest(
         # 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),
+        attempt_history=_build_attempt_history(prior_manifest, gaps_identical=gaps_identical),
+        approach_guidance=_build_approach_guidance(
+            prior_manifest, prior_attempts, retry_budget, gaps_identical=gaps_identical
+        ),
+        stub_findings=[
+            f"{g.file}:{g.line} {g.description}" if g.file else g.description
+            for g in blocking_gaps
+            if g.gap_type == "stub_detected"
+        ],
     )
 
     if repair_service is not None:
@@ -271,8 +351,9 @@ def build_correction_manifest(
                     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
+        except Exception as e:
+            # The manifest still ships, but without the repair plan's focused scope.
+            logger.warning("Repair plan generation failed, keeping heuristic manifest scope: %s", e)
     return manifest
 
 
@@ -311,14 +392,18 @@ def write_correction_manifest(
         "Writing correction manifest for %s: %d gap(s), prior_attempts=%d",
         task_id, len(gaps), prior_attempts,
     )
+    # The previous manifest (if any) feeds attempt_history and the identical-gaps
+    # comparison behind approach_guidance. Loaded BEFORE the new one is written.
+    prior_manifest = load_latest_correction_manifest(project_root, task_id)
     manifest = build_correction_manifest(
-        project_root, task, gaps, repair_service=repair_service, prior_attempts=prior_attempts, config=config
+        project_root, task, gaps, repair_service=repair_service, prior_attempts=prior_attempts,
+        config=config, prior_manifest=prior_manifest,
     )
     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")
+    write_model_json(path, manifest)
 
     with db.get_session() as session:
         CorrectionManifestRepository(session).save(
@@ -343,4 +428,16 @@ def load_latest_correction_manifest(project_root: Path, task_id: str) -> Correct
         path = Path(record.manifest_path)
         if not path.exists():
             return None
-        return CorrectionManifest.model_validate(json.loads(path.read_text(encoding="utf-8")))
+        return read_model_json(path, CorrectionManifest)
+
+
+def repair_prompt_prefix(project_root: Path, task_id: str) -> str:
+    """Correction manifest + repair rules for a repair run, or ``\"\"`` on first attempt."""
+    correction = load_latest_correction_manifest(project_root, task_id)
+    if correction is None:
+        return ""
+    return (
+        f"# DevCouncil Correction Manifest\n\n"
+        f"{correction.model_dump_json(indent=2)}\n\n"
+        f"{REPAIR_RULES}\n"
+    )

package/src/devcouncil/planning/plan_difficulty.py

@@ -0,0 +1,69 @@
+"""Plan-time difficulty tagging so the council sees rigor before execution.
+
+The verifier's deterministic estimator runs here on every task the arbiter emits
+without an explicit ``Task.difficulty``. Overscoped tasks that score ``hard`` get
+a human-visible warning so planners can split them before agents start work.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import List, Tuple
+
+from devcouncil.domain.requirement import Requirement
+from devcouncil.domain.task import Task
+from devcouncil.verification.difficulty import (
+    _HARD_THRESHOLD,
+    difficulty_score,
+    estimate_difficulty,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def annotate_tasks_with_difficulty(
+    tasks: List[Task],
+    requirements: List[Requirement] | None = None,
+) -> List[Task]:
+    """Set ``Task.difficulty`` from the estimator when the arbiter left it unset."""
+    annotated: List[Task] = []
+    for task in tasks:
+        if task.difficulty in ("easy", "normal", "hard"):
+            annotated.append(task)
+            continue
+        difficulty = estimate_difficulty(task, requirements)
+        annotated.append(task.model_copy(update={"difficulty": difficulty}))
+    return annotated
+
+
+def overscoped_hard_warnings(
+    tasks: List[Task],
+    requirements: List[Requirement] | None = None,
+) -> List[str]:
+    """Advisory messages for tasks that score hard and may need splitting."""
+    warnings: List[str] = []
+    for task in tasks:
+        score = difficulty_score(task, requirements)
+        if score < _HARD_THRESHOLD:
+            continue
+        writable = [pf for pf in task.planned_files if pf.allowed_change != "read_only"]
+        if len(writable) >= 4 or len(task.acceptance_criterion_ids) >= 5:
+            warnings.append(
+                f"{task.id} ({task.title!r}) scores hard ({score}): "
+                f"{len(writable)} writable file(s), "
+                f"{len(task.acceptance_criterion_ids)} acceptance criterion(s). "
+                "Consider splitting into smaller tasks before execution."
+            )
+    return warnings
+
+
+def apply_plan_difficulty(
+    tasks: List[Task],
+    requirements: List[Requirement] | None = None,
+) -> Tuple[List[Task], List[str]]:
+    """Annotate difficulty and return any overscoped-hard warnings."""
+    annotated = annotate_tasks_with_difficulty(tasks, requirements)
+    warnings = overscoped_hard_warnings(annotated, requirements)
+    for msg in warnings:
+        logger.info("Plan difficulty: %s", msg)
+    return annotated, warnings

package/src/devcouncil/planning/plan_service.py

@@ -8,8 +8,11 @@ from devcouncil.llm.router import ModelRouter
 logger = logging.getLogger(__name__)
 
 class PlanOutput(BaseModel):
-    id: str
-    rationale: str
+    # id/rationale are descriptive metadata some models omit; don't fail an
+    # otherwise-valid plan over them. tasks stays required — a plan without
+    # tasks is a real failure the healing/retry path must surface.
+    id: str = "PLAN"
+    rationale: str = ""
     tasks: List[Task]
 
 

package/src/devcouncil/planning/planned_files_reconcile.py

@@ -0,0 +1,191 @@
+"""Reconcile planner-emitted ``planned_files`` against the real repository.
+
+The planner names ``planned_files`` as free-form LLM output. A
+``modify``/``delete``/``read_only`` entry that points at a path the repo does not
+actually contain is not a harmless typo: it becomes the file whitelist that
+downstream scope enforcement trusts. A plausible-but-wrong path (a typo, or a file
+that was renamed) then silently reverts the legitimate write the agent makes to the
+*real* path, because the real path was never whitelisted.
+
+This pass grounds those paths in the repo map's actual file set before the plan is
+persisted. Its guiding invariant is **it only ever relaxes or corrects scope, never
+tightens it** — so it can remove false reverts but never introduce a new one:
+
+  - ``create`` entries are left as-is (a new file legitimately isn't in the map yet).
+  - a path that exists in the map is kept (normalized).
+  - a non-existent ``modify``/``delete``/``read_only`` path is *repaired* to a real
+    path when exactly one file in the repo shares its basename (the typo/rename case).
+  - anything else (no basename match, or an ambiguous multi-match) is kept as-is and
+    reported as an advisory warning, never dropped.
+
+Import-light (domain + stdlib only) so it stays unit-testable without booting the
+planner's LLM/router stack.
+"""
+
+from __future__ import annotations
+
+from typing import Iterable
+
+from devcouncil.domain.task import PlannedFile, Task
+
+
+def _normalize(path: str) -> str:
+    """Strip ``./`` prefixes, normalize separators, and drop trailing slashes."""
+    return path.strip().replace("\\", "/").removeprefix("./").rstrip("/")
+
+
+def _basename(path: str) -> str:
+    return path.rsplit("/", 1)[-1]
+
+
+def repo_files_from_map(repo_map: object) -> list[str]:
+    """Extract tracked file paths from a ``RepoMap`` (or its ``dict`` form)."""
+    files = getattr(repo_map, "files", None)
+    if files is None and isinstance(repo_map, dict):
+        files = repo_map.get("files", [])
+    result: list[str] = []
+    for entry in files or []:
+        path = getattr(entry, "path", None)
+        if path is None and isinstance(entry, dict):
+            path = entry.get("path")
+        if path:
+            result.append(path)
+    return result
+
+
+def reconcile_planned_files(
+    tasks: list[Task],
+    repo_files: Iterable[str],
+) -> tuple[list[Task], list[str]]:
+    """Ground each task's ``planned_files`` against the real repo file set.
+
+    Returns the (possibly rewritten) tasks and a list of human-readable warnings
+    describing every repair or unresolved mismatch. When ``repo_files`` is empty
+    (no map available), tasks are returned untouched — we can't distinguish a
+    hallucinated path from a real one, so we degrade gracefully rather than guess.
+    """
+    known = {_normalize(f) for f in repo_files if f and f.strip()}
+
+    if not known:
+        return list(tasks), []
+
+    by_basename: dict[str, set[str]] = {}
+    for f in known:
+        by_basename.setdefault(_basename(f), set()).add(f)
+
+    warnings: list[str] = []
+    new_tasks: list[Task] = []
+
+    for task in tasks:
+        if not task.planned_files:
+            new_tasks.append(task)
+            continue
+
+        changed = False
+        kept: list[PlannedFile] = []
+        for pf in task.planned_files:
+            norm = _normalize(pf.path)
+
+            # A file this task creates legitimately isn't in the map yet.
+            if pf.allowed_change == "create" or norm in known:
+                if norm != pf.path:
+                    kept.append(pf.model_copy(update={"path": norm}))
+                    changed = True
+                else:
+                    kept.append(pf)
+                continue
+
+            # Non-existent modify/delete/read_only target: repair on a unique
+            # basename match (the typo / rename case), otherwise keep + warn.
+            candidates = by_basename.get(_basename(norm), set())
+            if len(candidates) == 1:
+                repaired = next(iter(candidates))
+                kept.append(pf.model_copy(update={"path": repaired}))
+                changed = True
+                warnings.append(
+                    f"{task.id}: planned file '{pf.path}' not found in repo; "
+                    f"repaired to '{repaired}' (unique basename match)."
+                )
+            else:
+                kept.append(pf.model_copy(update={"path": norm}) if norm != pf.path else pf)
+                if norm != pf.path:
+                    changed = True
+                detail = (
+                    f"{len(candidates)} basename matches — ambiguous"
+                    if candidates
+                    else "no matching file"
+                )
+                warnings.append(
+                    f"{task.id}: planned file '{pf.path}' ({pf.allowed_change}) "
+                    f"not found in repo ({detail}); left as-is for review."
+                )
+
+        new_tasks.append(task.model_copy(update={"planned_files": kept}) if changed else task)
+
+    return new_tasks, warnings
+
+
+def expand_scope_with_dependents(
+    tasks: list[Task],
+    dependents: dict[str, list[str]],
+    repo_files: Iterable[str],
+    max_per_file: int = 8,
+) -> tuple[list[Task], list[str]]:
+    """Widen each task's ``planned_files`` with the real callers of its writable files.
+
+    The other half of the scope bug ``reconcile_planned_files`` doesn't cover: the
+    planner names ``foo.py`` to modify but not the files that *import* ``foo.py`` and
+    must change with it. Those omitted callers are outside the whitelist, so the
+    agent's necessary edit to them is reverted. Using the repo map's ``dependents``
+    (reverse import edges), add each writable file's callers as ``modify``-scoped
+    entries — capped per file and drawn only from files that actually exist, so this
+    only ever *relaxes* scope from a grounded signal, never invents paths.
+    """
+    if not dependents:
+        return list(tasks), []
+
+    known = {_normalize(f) for f in repo_files if f and f.strip()}
+    norm_dependents = {
+        _normalize(k): [_normalize(v) for v in (vs or [])] for k, vs in dependents.items()
+    }
+
+    warnings: list[str] = []
+    new_tasks: list[Task] = []
+
+    for task in tasks:
+        existing = {_normalize(pf.path) for pf in task.planned_files}
+        additions: list[PlannedFile] = []
+        for pf in task.planned_files:
+            if pf.allowed_change not in ("modify", "delete"):
+                continue
+            norm = _normalize(pf.path)
+            added = 0
+            for dep in norm_dependents.get(norm, []):
+                if added >= max_per_file:
+                    break
+                if dep in existing:
+                    continue
+                if known and dep not in known:
+                    continue
+                existing.add(dep)
+                additions.append(
+                    PlannedFile(
+                        path=dep,
+                        reason=f"imports {norm}; may need updating when it changes (repo map dependents)",
+                        allowed_change="modify",
+                    )
+                )
+                added += 1
+
+        if additions:
+            new_tasks.append(
+                task.model_copy(update={"planned_files": [*task.planned_files, *additions]})
+            )
+            warnings.append(
+                f"{task.id}: widened scope with {len(additions)} dependent file(s) so a "
+                "required caller edit isn't reverted."
+            )
+        else:
+            new_tasks.append(task)
+
+    return new_tasks, warnings

package/src/devcouncil/planning/prompt_enhancer_service.py

@@ -4,6 +4,7 @@ from pathlib import Path
 from pydantic import BaseModel, Field
 
 from devcouncil.llm.router import ModelRouter
+from devcouncil.utils.json_persist import read_model_json, write_model_json
 
 logger = logging.getLogger(__name__)
 
@@ -97,11 +98,10 @@ def load_latest_prompt_enhancement(project_root: Path) -> "PromptEnhancement | N
     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")))
+            return read_model_json(path, PromptEnhancement)
         except Exception:
             return None
 
@@ -125,9 +125,10 @@ def save_active_prompt_enhancement(project_root: Path, enhancement: "PromptEnhan
     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
+        write_model_json(path, enhancement)
+    except Exception as e:
+        # If this persistence fails, executors silently run without (or with stale) guidance.
+        logger.warning("Failed to persist active prompt enhancement: %s", e)
 
 
 class PromptEnhancerService:

package/src/devcouncil/planning/question_conversion.py

@@ -0,0 +1,56 @@
+"""Convert blocking spec questions into non-blocking assumptions."""
+
+from __future__ import annotations
+
+from devcouncil.domain.assumption import Assumption
+from devcouncil.planning.spec_service import BlockingQuestion
+
+
+def assumption_id_from_question(question_id: str) -> str:
+    """Derive a stable assumption id from a blocking-question id."""
+    if question_id.startswith("ASM-"):
+        return question_id
+    if question_id.startswith("Q-"):
+        return f"ASM-from-{question_id}"
+    return f"ASM-from-Q-{question_id}"
+
+
+def blocking_question_to_assumption(question: BlockingQuestion) -> Assumption:
+    """Map one blocking question to a low-confidence assumption that does not block approval."""
+    statement = question.question
+    if question.reason:
+        statement = f"{question.question} (Context: {question.reason})"
+    return Assumption(
+        id=assumption_id_from_question(question.id),
+        statement=statement,
+        confidence="low",
+        impact="medium",
+        reversible=True,
+        requires_user_confirmation=False,
+        status="open",
+    )
+
+
+def convert_blocking_questions_to_assumptions(
+    assumptions: list[Assumption],
+    blocking_questions: list[BlockingQuestion],
+) -> tuple[list[Assumption], list[BlockingQuestion]]:
+    """Append converted questions as assumptions and return an empty blocking list."""
+    if not blocking_questions:
+        return assumptions, blocking_questions
+
+    existing_ids = {assumption.id for assumption in assumptions}
+    converted: list[Assumption] = []
+    for question in blocking_questions:
+        assumption = blocking_question_to_assumption(question)
+        candidate_id = assumption.id
+        suffix = 1
+        while candidate_id in existing_ids:
+            candidate_id = f"{assumption.id}-{suffix}"
+            suffix += 1
+        if candidate_id != assumption.id:
+            assumption = assumption.model_copy(update={"id": candidate_id})
+        existing_ids.add(assumption.id)
+        converted.append(assumption)
+
+    return [*assumptions, *converted], []

package/src/devcouncil/planning/spec_service.py

@@ -1,6 +1,6 @@
 import logging
 from typing import List
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 from devcouncil.domain.requirement import Requirement
 from devcouncil.domain.assumption import Assumption
 from devcouncil.llm.router import ModelRouter
@@ -14,8 +14,14 @@ class BlockingQuestion(BaseModel):
 
 class SpecOutput(BaseModel):
     requirements: List[Requirement]
-    assumptions: List[Assumption]
-    blocking_questions: List[BlockingQuestion]
+    # Models on providers without grammar-constrained decoding (e.g.
+    # gemini-2.5-flash via OpenRouter) routinely OMIT list fields that would be
+    # empty instead of emitting "[]". An absent empty list is semantically
+    # identical to an empty one, so default rather than crash the planning run
+    # with a "Field required" validation error. requirements stays required:
+    # a spec without requirements IS a failure worth surfacing.
+    assumptions: List[Assumption] = Field(default_factory=list)
+    blocking_questions: List[BlockingQuestion] = Field(default_factory=list)
 
 class SpecService:
     def __init__(self, router: ModelRouter):