claude-code-generator 0.5.6__tar.gz → 0.5.8__tar.gz

{claude_code_generator-0.5.6/src/claude_code_generator.egg-info → claude_code_generator-0.5.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-code-generator
-Version: 0.5.6
+Version: 0.5.8
 Summary: Orchestrator CLI that drives Claude Code end-to-end to generate whole projects from a requirements.md file.
 Author: Silvio Baratto
 License: MIT

{claude_code_generator-0.5.6 → claude_code_generator-0.5.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "claude-code-generator"
-version = "0.5.6"
+version = "0.5.8"
 description = "Orchestrator CLI that drives Claude Code end-to-end to generate whole projects from a requirements.md file."
 readme = "README.md"
 license = { text = "MIT" }
@@ -96,4 +96,4 @@ asyncio_mode = "auto"
 
 [tool.pyright]
 # Test mocks intentionally use unused parameters to match the production interface signature.
-reportUnusedParameter = "none"
+reportUnusedParameter = false

{claude_code_generator-0.5.6 → claude_code_generator-0.5.8/src/claude_code_generator.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-code-generator
-Version: 0.5.6
+Version: 0.5.8
 Summary: Orchestrator CLI that drives Claude Code end-to-end to generate whole projects from a requirements.md file.
 Author: Silvio Baratto
 License: MIT

{claude_code_generator-0.5.6 → claude_code_generator-0.5.8}/src/claude_code_generator.egg-info/SOURCES.txt

@@ -13,6 +13,7 @@ src/code_generator/checklist.py
 src/code_generator/cli.py
 src/code_generator/effort.py
 src/code_generator/env.py
+src/code_generator/exceptions.py
 src/code_generator/git_ops.py
 src/code_generator/logging_setup.py
 src/code_generator/memory.py
@@ -151,6 +152,7 @@ tests/test_no_max_turns_in_call_sites.py
 tests/test_no_max_turns_literal.py
 tests/test_non_goals_grep_guard.py
 tests/test_ollama_budget.py
+tests/test_ollama_hardening.py
 tests/test_ollama_rate_limit.py
 tests/test_optimize.py
 tests/test_options.py

{claude_code_generator-0.5.6 → claude_code_generator-0.5.8}/src/code_generator/__init__.py

@@ -1,3 +1,3 @@
 """code-generator: orchestrator CLI for end-to-end project generation."""
 
-__version__ = "0.5.6"
+__version__ = "0.5.8"

{claude_code_generator-0.5.6 → claude_code_generator-0.5.8}/src/code_generator/agents.py

@@ -74,6 +74,38 @@ _PYTHON_CLI = AgentSelection(
 )
 
 
+# ---------------------------------------------------------------------------
+# Extra-skill detection
+# ---------------------------------------------------------------------------
+
+_EXTRA_SKILL_KEYWORDS: tuple[tuple[tuple[str, ...], tuple[str, ...]], ...] = (
+    (("supabase",), ("supabase", "supabase-postgres-best-practices")),
+    (
+        ("skfolio", "portfolio optim", "efficient frontier", "mean-variance", "risk parity"),
+        ("skfolio",),
+    ),
+    (("yfinance", "yahoo finance", "ohlcv", "stock data", "ticker data"), ("yfinance",)),
+    (("xlsx", ".xlsx", " excel", "spreadsheet"), ("xlsx",)),
+    (("docx", ".docx", "word document"), ("docx",)),
+)
+
+
+def _detect_extra_skills(block: str) -> tuple[str, ...]:
+    extras: list[str] = []
+    for keywords, skills in _EXTRA_SKILL_KEYWORDS:
+        if any(kw in block for kw in keywords):
+            extras.extend(skills)
+    return tuple(extras)
+
+
+def _merge(base: AgentSelection, extras: tuple[str, ...]) -> AgentSelection:
+    if not extras:
+        return base
+    existing = set(base.skills)
+    new_skills = base.skills + tuple(s for s in extras if s not in existing)
+    return AgentSelection(primary=base.primary, support=base.support, skills=new_skills)
+
+
 # ---------------------------------------------------------------------------
 # Public API
 # ---------------------------------------------------------------------------
@@ -131,18 +163,16 @@ def detect(requirements_path: Path) -> AgentSelection:
     has_fastapi = "fastapi" in block or "python api" in block
 
     if has_angular and has_fastapi:
-        return _ANGULAR_FASTAPI
-
-    if has_angular:
-        return _ANGULAR_ONLY
-
-    if has_fastapi:
-        return _FASTAPI
-
-    if "baml" in block or "llm function" in block:
-        return _BAML
-
-    if "typer" in block or "click" in block or "python cli" in block:
-        return _PYTHON_CLI
-
-    return _GENERIC_FALLBACK
+        base = _ANGULAR_FASTAPI
+    elif has_angular:
+        base = _ANGULAR_ONLY
+    elif has_fastapi:
+        base = _FASTAPI
+    elif "baml" in block or "llm function" in block:
+        base = _BAML
+    elif "typer" in block or "click" in block or "python cli" in block:
+        base = _PYTHON_CLI
+    else:
+        base = _GENERIC_FALLBACK
+
+    return _merge(base, _detect_extra_skills(block))

{claude_code_generator-0.5.6 → claude_code_generator-0.5.8}/src/code_generator/commands/_dispatch.py

@@ -37,14 +37,51 @@ __all__ = ["dispatch_async", "dispatch_orchestrator"]
 
 _GRAPHIFY_TIMEOUT = int(os.environ.get("CODE_GENERATOR_GRAPHIFY_TIMEOUT", "600"))
 
+_GRAPHIFY_EXTRACT_CMD = ["graphify", "extract", "."]
+_GRAPHIFY_UPDATE_CMD = ["graphify", "update", "."]
 
 _SETUP_HINT = (
-    "graph-report: graphify-out/graph.json not found — run `/graphify .` once "
-    "inside Claude Code (or another graphify-compatible assistant) to seed the "
-    "knowledge graph. After that, code-generator will keep it fresh "
-    "automatically with `graphify update .`. Using fallback for now."
+    "graph-report: headless extraction via `graphify extract .` was attempted "
+    "automatically but failed — ensure graphify >= 0.7.3 is installed "
+    "(`pipx install graphifyy`) or run `/graphify .` once inside Claude Code "
+    "to seed the knowledge graph manually. Using fallback for now."
 )
 
+_GRAPHIFY_MIN_VERSION = (0, 7, 3)
+_GRAPHIFY_UPGRADE_HINT = (
+    "upgrade for headless seeding and v0.5.5 workaround removal: pip install -U graphifyy"
+)
+
+
+def _parse_version_line(stdout: str) -> str | None:
+    """Return 'X.Y.Z' from pip-show stdout, or None when the line is absent."""
+    for line in stdout.splitlines():
+        if line.startswith("Version:"):
+            return line.split(":", 1)[1].strip()
+    return None
+
+
+def _get_graphify_version_str() -> str | None:
+    """Probe installed graphifyy version via pip show; None on any failure."""
+    try:
+        result = subprocess.run(
+            ["pip", "show", "graphifyy"], capture_output=True, text=True, check=False
+        )
+        return _parse_version_line(result.stdout or "")
+    except (OSError, subprocess.SubprocessError):
+        return None
+
+
+def _probe_graphify_version(log: logging.Logger) -> None:
+    """Warn when graphify is below _GRAPHIFY_MIN_VERSION or undetectable."""
+    version_str = _get_graphify_version_str()
+    if version_str is None:
+        log.warning("graph-report: graphify version unknown — %s", _GRAPHIFY_UPGRADE_HINT)
+        return
+    version = tuple(int(p) for p in version_str.split(".") if p.isdigit())
+    if version < _GRAPHIFY_MIN_VERSION:
+        log.warning("graph-report: graphify %s detected — %s", version_str, _GRAPHIFY_UPGRADE_HINT)
+
 
 def _decode_stderr(stderr: bytes | str | None) -> str:
     """Decode subprocess stderr to a short single-line string for logging."""
@@ -55,42 +92,65 @@ def _decode_stderr(stderr: bytes | str | None) -> str:
     return text[:500]
 
 
-def _compute_and_persist_graph_report(project_dir: Path, log: logging.Logger) -> None:
-    """Refresh the codebase graph via graphify and persist the report.
+def _extract_argv(ollama_model: str | None) -> list[str]:
+    """Build graphify extract argv, appending --backend ollama on the Ollama path."""
+    if ollama_model is not None:
+        return [*_GRAPHIFY_EXTRACT_CMD, "--backend", "ollama"]
+    return list(_GRAPHIFY_EXTRACT_CMD)
+
+
+def _run_graphify(
+    cmd: list[str],
+    project_dir: Path,
+    log: logging.Logger,
+    memories_dir: Path,
+) -> bool:
+    """Run a graphify subprocess. Write fallback and return False on any error."""
+    try:
+        log.info("graph-report: running %s", " ".join(cmd))
+        subprocess.run(  # noqa: S603
+            cmd,
+            cwd=project_dir,
+            timeout=_GRAPHIFY_TIMEOUT,
+            capture_output=True,
+            check=True,
+        )
+        return True
+    except subprocess.CalledProcessError as exc:
+        stderr = _decode_stderr(exc.stderr)
+        log.warning(
+            "graph-report: graphify exited %d; using fallback. stderr: %s",
+            exc.returncode,
+            stderr or "<empty>",
+        )
+    except subprocess.TimeoutExpired as exc:
+        log.warning("graph-report: graphify timed out after %ss; using fallback", exc.timeout)
+    except (FileNotFoundError, OSError) as exc:
+        log.warning("graph-report: could not invoke graphify (%s); using fallback", exc)
+    _memory.write_memory_file(memories_dir, "cycle-repo-map.md", _memory.REPOMAP_FALLBACK)
+    return False
 
-    Graphify's shell CLI does **not** support a "build" subcommand — the full
-    LLM-driven build only happens through the ``/graphify`` slash-command
-    inside an AI assistant (Claude Code, Codex, Cursor, etc.).  The shell
-    binary only supports maintenance subcommands like ``update``, ``watch``,
-    ``query``.
+
+def _compute_and_persist_graph_report(
+    project_dir: Path, log: logging.Logger, *, ollama_model: str | None = None
+) -> None:
+    """Refresh the codebase graph via graphify and persist the report.
 
     Strategy:
 
-    1. If ``graphify-out/graph.json`` does **not** exist, the user has never
-       seeded the graph.  Log a one-time setup hint, write the fallback
-       sentinel, and return — do not call subprocess.  The user must run
-       ``/graphify .`` in their assistant once to seed it.
+    1. If ``graphify-out/graph.json`` does **not** exist, run
+       ``graphify extract .`` (headless LLM-driven seeding, requires >= 0.7.3).
+       On success, read ``GRAPH_REPORT.md`` and persist.  On failure, write the
+       fallback sentinel and emit :data:`_SETUP_HINT`.
 
-    2. If it exists, run ``graphify update .`` (cwd=project_dir).  This is
-       AST-only re-extraction, no LLM cost, fast on cached files.  It
-       refreshes ``graph.json`` and ``GRAPH_REPORT.md``.  Doc / paper /
-       image changes are *not* picked up — for those the user must run
-       ``/graphify .`` again in their assistant.
+    2. If it exists, run ``graphify update .`` (AST-only refresh, no LLM cost).
+       Refreshes ``graph.json`` and ``GRAPH_REPORT.md``.
 
     Falls back to :data:`code_generator.memory.REPOMAP_FALLBACK` on any
     failure (binary missing, timeout, non-zero exit, missing report file).
-    Stderr from graphify is captured and logged at WARN level on failure so
-    the user can diagnose without re-running by hand.
-
-    Auth: graphify inherits the parent process env. ``graphify update`` is
-    AST-only and makes no LLM calls, so OAuth context is irrelevant on this
-    codepath — but we still don't strip ``ANTHROPIC_*`` because the startup
-    ``env.assert_safe_environment()`` check (CLAUDE.md non-negotiable #1)
-    already guarantees those vars are absent on the Anthropic Max path.
 
     Args:
-        project_dir: Project root directory (graphify writes ``graphify-out/``
-            into this directory).
+        project_dir: Project root directory.
         log: Phase logger.
     """
     memories_dir = project_dir / ".code-generator" / "memories"
@@ -106,53 +166,14 @@ def _compute_and_persist_graph_report(project_dir: Path, log: logging.Logger) ->
         return
 
     if not graph_json.exists():
-        log.info(_SETUP_HINT)
-        _memory.write_memory_file(memories_dir, "cycle-repo-map.md", _memory.REPOMAP_FALLBACK)
-        return
-
-    cmd = ["graphify", "update", "."]
-    # GRAPHIFY_NO_TIPS=1 suppresses the tip-printer that has a NameError in
-    # graphify v0.5.5 (_os not in scope outside the install block).
-    os.environ.setdefault("GRAPHIFY_NO_TIPS", "1")
-    try:
-        log.info("graph-report: refreshing (cmd=%s)", " ".join(cmd))
-        subprocess.run(  # noqa: S603
-            cmd,
-            cwd=project_dir,
-            timeout=_GRAPHIFY_TIMEOUT,
-            capture_output=True,
-            check=True,
-        )
-    except subprocess.CalledProcessError as exc:
-        stderr = _decode_stderr(exc.stderr)
-        # graphify v0.5.5 has a NameError in its tip-printer (_os not in scope)
-        # that fires after a successful update — treat it as success so the
-        # real GRAPH_REPORT.md is used instead of the fallback sentinel.
-        if "NameError: name '_os' is not defined" in (stderr or ""):
-            log.info(
-                "graph-report: graphify tip-printer bug (v0.5.5) — graph updated; ignoring exit 1"
-            )
-        else:
-            log.warning(
-                "graph-report: graphify exited %d; using fallback. stderr: %s",
-                exc.returncode,
-                stderr or "<empty>",
-            )
-            _memory.write_memory_file(memories_dir, "cycle-repo-map.md", _memory.REPOMAP_FALLBACK)
+        log.info("graph-report: graph.json absent — attempting headless extraction")
+        if not _run_graphify(_extract_argv(ollama_model), project_dir, log, memories_dir):
+            log.info(_SETUP_HINT)
+            return
+    else:
+        _probe_graphify_version(log)
+        if not _run_graphify(_GRAPHIFY_UPDATE_CMD, project_dir, log, memories_dir):
             return
-    except subprocess.TimeoutExpired as exc:
-        log.warning(
-            "graph-report: graphify timed out after %ss; using fallback",
-            exc.timeout,
-        )
-        _memory.write_memory_file(memories_dir, "cycle-repo-map.md", _memory.REPOMAP_FALLBACK)
-        return
-    except (FileNotFoundError, OSError) as exc:
-        # `FileNotFoundError` here means the `graphify` binary disappeared
-        # between `shutil.which` and `subprocess.run`. Extremely unlikely.
-        log.warning("graph-report: could not invoke graphify (%s); using fallback", exc)
-        _memory.write_memory_file(memories_dir, "cycle-repo-map.md", _memory.REPOMAP_FALLBACK)
-        return
 
     try:
         content = report_path.read_text(encoding="utf-8")
@@ -289,7 +310,7 @@ async def _apply_delta_plan(
             "Phase 0 failed during delta planning; aborting to preserve cycle history."
         )
 
-    new_cycles = state_module.append_new_cycles(st, raw_cycles)
+    new_cycles = state_module.append_new_cycles(st, raw_cycles, ollama_model=effective_model)
 
     if not new_cycles:
         logger.info("Delta planning: no new cycles detected.")
@@ -344,7 +365,7 @@ async def dispatch_async(
     # Build the codebase graph once at the top of dispatch so Phase 0
     # (complexity analysis) sees a fresh report alongside Phases 1 and 2.
     graph_logger = setup_phase_logger("graph-report", project_dir)
-    _compute_and_persist_graph_report(project_dir, graph_logger)
+    _compute_and_persist_graph_report(project_dir, graph_logger, ollama_model=ollama_model)
 
     # Phase 0: determine mode when not already known.
     if mode == "auto":

{claude_code_generator-0.5.6 → claude_code_generator-0.5.8}/src/code_generator/commands/generate.py

@@ -147,6 +147,20 @@ def _persist_repo_info(
 @generate_app.callback(invoke_without_command=True)
 def generate_command(
     ctx: typer.Context,
+    model: Annotated[
+        str | None,
+        typer.Option(
+            "--model",
+            help=(
+                "Model tag to use for ALL phases (single-model routing). "
+                "When set, overrides the per-phase Opus/Sonnet/Haiku defaults "
+                "and routes every phase through the operator's configured endpoint. "
+                "Preserves existing ANTHROPIC_AUTH_TOKEN + ANTHROPIC_BASE_URL from "
+                "the parent environment."
+            ),
+            show_default=False,
+        ),
+    ] = None,
     dry_run: Annotated[
         bool,
         typer.Option("--dry-run/--no-dry-run", help="Print what would happen without doing it."),
@@ -192,12 +206,21 @@ def generate_command(
         ),
     ] = None,
 ) -> None:
-    """Run the full code-generation pipeline (default: Anthropic Max)."""
+    """Run the full code-generation pipeline (default: Anthropic Max).
+
+    Pass --model to route all phases through a custom endpoint (e.g. a local
+    Ollama daemon or a cloud proxy) instead of Anthropic Max. When --model is
+    set, the existing ANTHROPIC_AUTH_TOKEN and ANTHROPIC_BASE_URL from the
+    parent environment are preserved.
+    """
     # A subcommand like `generate ollama` has its own body; skip the default flow.
     if ctx.invoked_subcommand is not None:
         return
 
-    env.assert_safe_environment()
+    if model is not None:
+        env.assert_safe_environment_custom_model()
+    else:
+        env.assert_safe_environment()
     env.assert_single_workspace()
 
     if phase is not None and continue_:
@@ -235,6 +258,11 @@ def generate_command(
     # Persist the fresh RepoInfo atomically; warns when it differs from stored value.
     _persist_repo_info(st, repo_info, state_path)
 
+    # When --model is set, stamp the tag on existing cycles so --continue
+    # resolves the correct model without the operator re-typing --model.
+    if model is not None:
+        _stamp_model_on_existing_cycles(st, model, state_path)
+
     # Rate-limit pause guard: inform user and exit cleanly.
     if _check_paused(st):
         raise typer.Exit(code=0)
@@ -262,6 +290,7 @@ def generate_command(
             session_mode=effective_session_mode,
             session_mode_explicit=session_mode_explicit,
             max_turns=max_turns,
+            ollama_model=model,
         )
     except typer.Exit:
         raise
@@ -431,6 +460,9 @@ def generate_ollama_command(
         )
         raise typer.Exit(code=2)
 
+    # #268: advisory warning when the Ollama path carries a claude-* model tag.
+    env.warn_on_claude_model_for_ollama(effective_model)
+
     # (6) Persist the resolved model on existing cycles before dispatch so
     #     --continue resume stays consistent across sessions. New cycles
     #     created by phase 0/1 inherit the tag via the orchestrator thread

{claude_code_generator-0.5.6 → claude_code_generator-0.5.8}/src/code_generator/env.py

@@ -286,6 +286,61 @@ def assert_safe_environment() -> None:
     strip_dangerous_env()
 
 
+def warn_on_claude_model_for_ollama(model: str | None) -> None:
+    """Emit a WARNING when an Ollama-localhost env carries a ``claude-*`` model tag.
+
+    The Ollama codepath (#218) routes through a local daemon, so a
+    ``claude-opus-4-7`` / ``claude-sonnet-4-6`` / ``claude-haiku-*`` tag
+    almost always indicates a misconfiguration — the operator intended a
+    local model but typed an Anthropic model name.  The warning is purely
+    advisory; the upstream guarantee lives in the orchestrator's
+    ``_run_phases`` guard, which raises
+    :class:`~code_generator.exceptions.OllamaModelRequiredError` for the
+    same condition.
+
+    Args:
+        model: The resolved effective model tag, or ``None`` (no-op).
+    """
+    if model is not None and model.startswith("claude-"):
+        _logger.warning(
+            "Ollama daemon routing is active (ANTHROPIC_BASE_URL=%s) "
+            "but the model tag %r starts with 'claude-'. "
+            "This likely indicates a misconfiguration — did you mean "
+            "to use an Ollama model tag (e.g. 'qwen3-coder:480b:cloud')? "
+            "Use `code-generator generate ollama --model <tag>` for "
+            "single-model Ollama runs.",
+            OLLAMA_BASE_URL,
+            model,
+        )
+
+
+def assert_safe_environment_custom_model() -> None:
+    """Strip Anthropic API creds but preserve routing for custom model endpoints.
+
+    When ``--model`` is passed to the default ``generate`` command (not the
+    ``ollama`` subcommand), the operator's existing ``ANTHROPIC_AUTH_TOKEN``
+    and ``ANTHROPIC_BASE_URL`` are preserved so the custom endpoint routing
+    survives. Only real Anthropic credit keys are stripped.
+    """
+    offenders = [var for var in DANGEROUS_VARS if var in os.environ]
+    if offenders:
+        listed = ", ".join(offenders)
+        print(
+            f"Using custom model (preserving routing, ignoring {listed} for this process).",
+            file=sys.stderr,
+        )
+    _strip_dangerous_env_custom()
+
+
+def _strip_dangerous_env_custom() -> None:
+    """Strip DANGEROUS_VARS except ANTHROPIC_AUTH_TOKEN (preserve custom routing)."""
+    protected = {"ANTHROPIC_AUTH_TOKEN"}
+    for var in DANGEROUS_VARS:
+        if var in protected:
+            continue
+        os.environ.pop(var, None)
+
+
 def assert_safe_environment_ollama() -> None:
     """Strip Anthropic env vars and install the scoped Ollama routing in place.
 

claude_code_generator-0.5.8/src/code_generator/exceptions.py

@@ -0,0 +1,26 @@
+"""Shared exception classes for the code-generator pipeline.
+
+Single-responsibility: domain exception types only — no runner errors
+(those live in runner/types.py), no preflight errors (preflight.py).
+"""
+
+from __future__ import annotations
+
+
+class OllamaModelRequiredError(RuntimeError):
+    """Raised when the Ollama codepath has no resolvable model tag.
+
+    On the Ollama single-model path (#218), every phase requires a concrete
+    model tag (e.g. ``qwen3-coder:480b:cloud``).  This error fires when the
+    orchestrator detects that no model is available — either because
+    ``--model`` wasn't passed on a fresh run, or because the stored
+    ``CycleState.ollama_model`` is ``None`` on ``--continue``.
+
+    The ``fix_action`` string is a ready-to-paste remediation for the
+    operator; it is included in the error message automatically.
+    """
+
+    def __init__(self, reason: str, fix_action: str) -> None:
+        self.reason = reason
+        self.fix_action = fix_action
+        super().__init__(f"{reason} {fix_action}")

{claude_code_generator-0.5.6 → claude_code_generator-0.5.8}/src/code_generator/orchestrator/cycle_loop.py

@@ -14,11 +14,14 @@ Topological iteration:
 from __future__ import annotations
 
 import logging
+import os
 import shutil
 from typing import TYPE_CHECKING, Any, Literal
 
+from code_generator import env as _env
 from code_generator import gh, git_ops
 from code_generator import state as _state
+from code_generator.exceptions import OllamaModelRequiredError
 from code_generator.logging_setup import setup_phase_logger
 from code_generator.orchestrator import (
     phase1_plan,
@@ -171,6 +174,12 @@ def _resolve_effective_model(state: State, cycle: CycleState | None) -> str | No
     Priority: cycle.ollama_model (multi-cycle) > state.cycles[-1].ollama_model
     (single-mode fallback when ``cycle`` is not yet bound). The function never
     reads ``state.ollama_model`` because the field is cycle-level per #217.
+
+    Raises:
+        OllamaModelRequiredError: When the Ollama codepath is detected
+            (``ANTHROPIC_BASE_URL`` is localhost) and no model tag can be
+            resolved from state/cycle — this prevents a silent fallback
+            to an Anthropic model name.
     """
     if cycle is not None and cycle.ollama_model:
         return cycle.ollama_model
@@ -178,6 +187,21 @@ def _resolve_effective_model(state: State, cycle: CycleState | None) -> str | No
         last = state.cycles[-1]
         if isinstance(last, CycleState) and last.ollama_model:
             return last.ollama_model
+
+    if _env._is_localhost_base_url(os.environ.get("ANTHROPIC_BASE_URL")):  # noqa: SLF001
+        raise OllamaModelRequiredError(
+            reason=(
+                "Ollama daemon routing is active but no model tag is resolvable "
+                "from state.json. This happens when --continue is used on a "
+                "legacy state file that predates the ollama_model field, or "
+                "when --model was omitted on a fresh run."
+            ),
+            fix_action=(
+                "Re-run with --model <tag> to supply the model explicitly, e.g.: "
+                "code-generator generate ollama --model qwen3-coder:480b:cloud"
+            ),
+        )
+
     return None
 
 
@@ -231,6 +255,25 @@ async def _run_phases(
     if effective_model is None:
         effective_model = _resolve_effective_model(state, cycle)
 
+    # #268: belt-and-suspenders — when the Ollama codepath is active
+    # (effective_model is set) but the tag starts with "claude-", the operator
+    # almost certainly intended a local model.  Refuse before any phase runs
+    # so a mistyped tag never reaches the daemon (which would emit a cryptic
+    # "model may not exist").
+    if effective_model is not None and effective_model.startswith("claude-"):
+        raise OllamaModelRequiredError(
+            reason=(
+                f"Ollama single-model routing is active but the model tag "
+                f"{effective_model!r} starts with 'claude-'. "
+                "This likely indicates a misconfiguration — did you mean "
+                "to use an Ollama model tag?"
+            ),
+            fix_action=(
+                "Pass a valid Ollama model tag instead, e.g.: "
+                "code-generator generate ollama --model qwen3-coder:480b:cloud"
+            ),
+        )
+
     # #220: Ollama per-cycle budget tracker. ``effective_model is not None``
     # uniquely identifies the Ollama codepath inside the orchestrator, so we
     # key activation off it rather than threading an extra ``provider`` flag.