@michaelxwb/code-flow 0.8.1 → 1.0.0

package/src/core/code-flow/scripts/codeflow/spec/cf_spec_resolver.py

@@ -1,369 +0,0 @@
-#!/usr/bin/env python3
-"""Deterministic stage/path candidate resolution for schema-v1 Specs."""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-import fnmatch
-from pathlib import Path
-from typing import Mapping, Optional, Sequence
-
-from codeflow.spec.cf_spec_metadata import (
-    ALLOWED_STAGES,
-    SpecHeader,
-    SpecMetadata,
-    SpecRule,
-    load_spec_header,
-    load_spec_metadata,
-)
-
-
-SCOPE_PRIORITY = {"unmatched": 0, "global": 1, "path": 2, "task": 3}
-_config_cache: dict[str, tuple[int, int, int, Mapping[str, object]]] = {}
-_metadata_cache: dict[str, tuple[int, int, int, SpecMetadata]] = {}
-
-
-class SpecResolutionError(ValueError):
-    """An explicit resolver/configuration failure."""
-
-    def __init__(self, path: str, field: str, message: str) -> None:
-        self.path = path
-        self.field = field
-        self.message = message
-        super().__init__(f"{path}: resolution_error {field}: {message}")
-
-
-@dataclass(frozen=True)
-class SpecCandidate:
-    spec_id: str
-    path: str
-    scope: str
-    priority: int
-    matched_paths: tuple[str, ...]
-    metadata: SpecMetadata
-
-    @property
-    def required_rule_count(self) -> int:
-        if self.metadata.enforcement == "advisory":
-            return 0
-        return sum(rule.enforcement == "required" for rule in self.metadata.rules)
-
-
-@dataclass(frozen=True)
-class SpecCandidateHeader:
-    spec_id: str
-    path: str
-    scope: str
-    priority: int
-    matched_paths: tuple[str, ...]
-    enforcement: str
-
-
-@dataclass(frozen=True)
-class ResolvedRule:
-    ref: str
-    spec_id: str
-    text: str
-    enforcement: str
-    scope: str
-    priority: int
-    overridden_spec_ids: tuple[str, ...]
-
-
-@dataclass(frozen=True)
-class RuleConflict:
-    ref: str
-    priority: int
-    spec_ids: tuple[str, ...]
-    text_sha256: tuple[str, ...]
-
-
-@dataclass(frozen=True)
-class PrecedenceResolution:
-    candidates: tuple[SpecCandidate, ...]
-    effective_rules: tuple[ResolvedRule, ...]
-    conflicts: tuple[RuleConflict, ...]
-
-
-@dataclass(frozen=True)
-class CandidatePage:
-    items: tuple[SpecCandidate, ...]
-    total: int
-    has_more: bool
-
-
-@dataclass(frozen=True)
-class _RuleSource:
-    candidate: SpecCandidate
-    rule: SpecRule
-    enforcement: str
-
-
-def _fingerprint(path: Path, field: str) -> tuple[int, int, int]:
-    try:
-        stat = path.stat()
-    except OSError as exc:
-        raise SpecResolutionError(str(path), field, f"读取状态失败: {exc}") from exc
-    return stat.st_mtime_ns, stat.st_ctime_ns, stat.st_size
-
-
-def _load_config(root: str) -> Mapping[str, object]:
-    import yaml
-    path = Path(root) / ".code-flow" / "config.yml"
-    if not path.is_file():
-        raise SpecResolutionError(str(path), "config", "缺失 config.yml")
-    signature = _fingerprint(path, "config")
-    cached = _config_cache.get(str(path))
-    if cached and cached[:3] == signature:
-        return cached[3]
-    try:
-        loaded = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
-    except (OSError, UnicodeError, yaml.YAMLError) as exc:
-        raise SpecResolutionError(str(path), "config", f"解析失败: {exc}") from exc
-    if not isinstance(loaded, dict) or not all(isinstance(key, str) for key in loaded):
-        raise SpecResolutionError(str(path), "config", "顶层必须是字符串 key mapping")
-    _config_cache[str(path)] = (*signature, loaded)
-    return loaded
-
-
-def _path_mapping(config: Mapping[str, object], path: str) -> Mapping[str, object]:
-    value = config.get("path_mapping")
-    if not isinstance(value, dict) or not all(isinstance(key, str) for key in value):
-        raise SpecResolutionError(path, "path_mapping", "必须是字符串 key mapping")
-    return value
-
-
-def _domain_config(mapping: Mapping[str, object], domain: str, config_path: str) -> Mapping[str, object]:
-    value = mapping.get(domain, {})
-    if not isinstance(value, dict):
-        raise SpecResolutionError(config_path, f"path_mapping.{domain}", "必须是 mapping")
-    return value
-
-
-def _patterns(config: Mapping[str, object], field: str, config_path: str) -> tuple[str, ...]:
-    value = config.get("patterns", [])
-    if not isinstance(value, list) or not all(isinstance(item, str) for item in value):
-        raise SpecResolutionError(config_path, field, "patterns 必须是字符串列表")
-    return tuple(item.replace("\\", "/") for item in value)
-
-
-def _non_injectable(mapping: Mapping[str, object], config_path: str) -> set[str]:
-    excluded: set[str] = set()
-    for domain in mapping:
-        config = _domain_config(mapping, domain, config_path)
-        entries = config.get("specs", [])
-        if not isinstance(entries, list):
-            raise SpecResolutionError(config_path, f"path_mapping.{domain}.specs", "必须是列表")
-        for entry in entries:
-            if isinstance(entry, dict) and entry.get("tags") == [] and isinstance(entry.get("path"), str):
-                excluded.add(str(entry["path"]).replace("\\", "/"))
-    return excluded
-
-
-def _load_metadata(path: Path) -> SpecMetadata:
-    signature = _fingerprint(path, "spec")
-    cached = _metadata_cache.get(str(path))
-    if cached and cached[:3] == signature:
-        return cached[3]
-    metadata = load_spec_metadata(str(path))
-    _metadata_cache[str(path)] = (*signature, metadata)
-    return metadata
-
-
-def _candidate_scope(relative: str, patterns: Sequence[str], paths: Sequence[str]) -> tuple[str, tuple[str, ...]]:
-    if relative.startswith("_session/"):
-        return "task", ()
-    matched = tuple(path for path in paths if any(fnmatch.fnmatch(path, pattern) for pattern in patterns))
-    if matched:
-        return "path", matched
-    # A domain without patterns is truly global. A domain WITH patterns that
-    # match nothing is irrelevant to these paths ("unmatched") — discovery
-    # keeps it, but injection and scope expansion must not consume it.
-    return ("global", ()) if not patterns else ("unmatched", ())
-
-
-def _candidate_for(
-    path: Path,
-    spec_root: Path,
-    mapping: Mapping[str, object],
-    config_path: str,
-    stage: str,
-    paths: Sequence[str],
-) -> Optional[SpecCandidate]:
-    relative = path.relative_to(spec_root).as_posix()
-    metadata = _load_metadata(path)
-    if stage not in metadata.stages:
-        return None
-    domain = relative.split("/", 1)[0]
-    config = _domain_config(mapping, domain, config_path)
-    patterns = _patterns(config, f"path_mapping.{domain}.patterns", config_path)
-    scope, matched = _candidate_scope(relative, patterns, paths)
-    return SpecCandidate(metadata.id, relative, scope, SCOPE_PRIORITY[scope], matched, metadata)
-
-
-def _candidate_header_for(
-    path: Path,
-    spec_root: Path,
-    mapping: Mapping[str, object],
-    config_path: str,
-    stage: str,
-    paths: Sequence[str],
-) -> Optional[SpecCandidateHeader]:
-    relative = path.relative_to(spec_root).as_posix()
-    header: SpecHeader = load_spec_header(str(path))
-    if stage not in header.stages:
-        return None
-    domain = relative.split("/", 1)[0]
-    config = _domain_config(mapping, domain, config_path)
-    patterns = _patterns(config, f"path_mapping.{domain}.patterns", config_path)
-    scope, matched = _candidate_scope(relative, patterns, paths)
-    return SpecCandidateHeader(
-        header.id, relative, scope, SCOPE_PRIORITY[scope], matched, header.enforcement
-    )
-
-
-def _spec_paths(spec_root: Path, excluded: set[str]) -> tuple[Path, ...]:
-    result: list[Path] = []
-    for path in sorted(spec_root.rglob("*.md")):
-        relative = path.relative_to(spec_root).as_posix()
-        if path.name != "_map.md" and not relative.startswith("_session/") and relative not in excluded:
-            result.append(path)
-    return tuple(result)
-
-
-def _routing_paths(
-    spec_root: Path, excluded: set[str], mapping: Mapping[str, object],
-    config_path: str, paths: Sequence[str], matched_only: bool,
-) -> tuple[Path, ...]:
-    discovered = _spec_paths(spec_root, excluded)
-    if not matched_only:
-        return discovered
-    relevant = []
-    for path in discovered:
-        relative = path.relative_to(spec_root).as_posix()
-        domain = relative.split("/", 1)[0]
-        patterns = _patterns(_domain_config(mapping, domain, config_path),
-                             f"path_mapping.{domain}.patterns", config_path)
-        if _candidate_scope(relative, patterns, paths)[0] != "unmatched":
-            relevant.append(path)
-    return tuple(relevant)
-
-
-def resolve_candidates(
-    root: str, stage: str, paths: Sequence[str], *, matched_only: bool = False,
-) -> tuple[SpecCandidate, ...]:
-    if stage not in ALLOWED_STAGES:
-        raise SpecResolutionError(root, "stage", f"不支持 stage: {stage!r}")
-    normalized_paths = tuple(path.replace("\\", "/") for path in paths)
-    config = _load_config(root)
-    config_path = str(Path(root) / ".code-flow" / "config.yml")
-    mapping = _path_mapping(config, config_path)
-    excluded = _non_injectable(mapping, config_path)
-    spec_root = Path(root) / ".code-flow" / "specs"
-    if not spec_root.is_dir():
-        raise SpecResolutionError(str(spec_root), "specs", "缺失 specs 目录")
-    candidates: list[SpecCandidate] = []
-    ids: dict[str, str] = {}
-    for path in _routing_paths(spec_root, excluded, mapping, config_path, normalized_paths, matched_only):
-        candidate = _candidate_for(path, spec_root, mapping, config_path, stage, normalized_paths)
-        if candidate is None:
-            continue
-        if candidate.spec_id in ids:
-            detail = f"重复 id {candidate.spec_id}: {ids[candidate.spec_id]}, {candidate.path}"
-            raise SpecResolutionError(str(spec_root), "spec_id", detail)
-        ids[candidate.spec_id] = candidate.path
-        candidates.append(candidate)
-    return tuple(sorted(candidates, key=lambda item: (-item.priority, item.path)))
-
-
-def resolve_candidate_headers(
-    root: str, stage: str, paths: Sequence[str], *, matched_only: bool = False,
-    excluded_paths: Sequence[str] = (),
-) -> tuple[SpecCandidateHeader, ...]:
-    """Resolve candidates from routing frontmatter without parsing bodies or hashes."""
-    if stage not in ALLOWED_STAGES:
-        raise SpecResolutionError(root, "stage", f"不支持 stage: {stage!r}")
-    normalized_paths = tuple(path.replace("\\", "/") for path in paths)
-    config = _load_config(root)
-    config_path = str(Path(root) / ".code-flow" / "config.yml")
-    mapping = _path_mapping(config, config_path)
-    excluded = _non_injectable(mapping, config_path)
-    excluded.update(excluded_paths)
-    spec_root = Path(root) / ".code-flow" / "specs"
-    if not spec_root.is_dir():
-        raise SpecResolutionError(str(spec_root), "specs", "缺失 specs 目录")
-    candidates: list[SpecCandidateHeader] = []
-    ids: dict[str, str] = {}
-    for path in _routing_paths(spec_root, excluded, mapping, config_path, normalized_paths, matched_only):
-        candidate = _candidate_header_for(path, spec_root, mapping, config_path, stage, normalized_paths)
-        if candidate is None:
-            continue
-        if candidate.spec_id in ids:
-            detail = f"重复 id {candidate.spec_id}: {ids[candidate.spec_id]}, {candidate.path}"
-            raise SpecResolutionError(str(spec_root), "spec_id", detail)
-        ids[candidate.spec_id] = candidate.path
-        candidates.append(candidate)
-    return tuple(sorted(candidates, key=lambda item: (-item.priority, item.path)))
-
-
-def _effective_enforcement(candidate: SpecCandidate, rule: SpecRule) -> str:
-    if candidate.metadata.enforcement == "advisory" and rule.enforcement == "required":
-        return "advisory"
-    return rule.enforcement
-
-
-def _rule_sources(candidates: Sequence[SpecCandidate]) -> dict[str, list[_RuleSource]]:
-    grouped: dict[str, list[_RuleSource]] = {}
-    for candidate in candidates:
-        for rule in candidate.metadata.rules:
-            source = _RuleSource(candidate, rule, _effective_enforcement(candidate, rule))
-            grouped.setdefault(rule.ref, []).append(source)
-    for sources in grouped.values():
-        sources.sort(key=lambda item: (-item.candidate.priority, item.candidate.path))
-    return grouped
-
-
-def _resolve_rule(ref: str, sources: Sequence[_RuleSource]) -> tuple[Optional[ResolvedRule], Optional[RuleConflict]]:
-    priority = sources[0].candidate.priority
-    top = tuple(source for source in sources if source.candidate.priority == priority)
-    required = tuple(source for source in top if source.enforcement == "required")
-    hashes = {source.rule.text_sha256 for source in required}
-    if len(required) > 1 and len(hashes) > 1:
-        conflict = RuleConflict(
-            ref,
-            priority,
-            tuple(source.candidate.spec_id for source in required),
-            tuple(source.rule.text_sha256 for source in required),
-        )
-        return None, conflict
-    winner = required[0] if required else top[0]
-    overridden = tuple(source.candidate.spec_id for source in sources if source is not winner)
-    resolved = ResolvedRule(
-        ref,
-        winner.candidate.spec_id,
-        winner.rule.text,
-        winner.enforcement,
-        winner.candidate.scope,
-        priority,
-        overridden,
-    )
-    return resolved, None
-
-
-def resolve_precedence(candidates: Sequence[SpecCandidate]) -> PrecedenceResolution:
-    effective: list[ResolvedRule] = []
-    conflicts: list[RuleConflict] = []
-    for ref, sources in sorted(_rule_sources(candidates).items()):
-        resolved, conflict = _resolve_rule(ref, sources)
-        if resolved is not None:
-            effective.append(resolved)
-        if conflict is not None:
-            conflicts.append(conflict)
-    return PrecedenceResolution(tuple(candidates), tuple(effective), tuple(conflicts))
-
-
-def build_candidate_page(candidates: Sequence[SpecCandidate], limit: int) -> CandidatePage:
-    if limit <= 0:
-        raise SpecResolutionError("<memory>", "limit", "必须大于 0")
-    items = tuple(candidates[:limit])
-    return CandidatePage(items=items, total=len(candidates), has_more=len(candidates) > limit)

package/src/core/code-flow/scripts/codeflow/spec/cf_spec_router.py

@@ -1,304 +0,0 @@
-#!/usr/bin/env python3
-"""Context-first prompt router for task, path, and Catalog modes."""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-import hashlib
-import json
-import os
-from pathlib import Path
-import tempfile
-import codeflow.cli.cf_spec_session as cf_spec_session
-from typing import Mapping, Optional, Sequence
-
-from codeflow.core.cf_core import (
-    assemble_context,
-    ConfigError,
-    build_effective_mapping,
-    build_spec_catalog,
-    estimate_tokens,
-    load_config,
-    resolve_compress,
-)
-from codeflow.core.cf_log import warn
-from codeflow.cli.cf_spec_context import ContextError, SpecContext, load_active_task, load_context
-from codeflow.core.cf_context_cache import load_snapshot
-from codeflow.spec.cf_spec_resolver import resolve_candidate_headers
-from codeflow.spec.cf_spec_context_model import context_sha256
-from codeflow.spec.cf_task_projection import project_task_session
-
-
-_PROJECTION_CACHE_PATH = ".code-flow/.task-projection-state.json"
-
-
-@dataclass(frozen=True)
-class RouteResult:
-    mode: str
-    text: str
-    specs: tuple[str, ...]
-    context_sha256: Optional[str] = None
-    expanded_specs: tuple[str, ...] = ()
-
-
-class RouterError(ValueError):
-    """Fail-closed routing error with a stable code."""
-
-    def __init__(self, code: str, message: str) -> None:
-        self.code = code
-        super().__init__(message)
-
-
-def _task_file(task_dir: Path, task_id: str) -> Path:
-    matches = []
-    for path in sorted(task_dir.glob("*.md")):
-        if path.name.endswith((".prd.md", ".design.md")):
-            continue
-        if f"## {task_id}:" in path.read_text(encoding="utf-8"):
-            matches.append(path)
-    if len(matches) != 1:
-        raise RouterError("task_file_ambiguous", f"{task_id} matched {len(matches)} task files")
-    return matches[0]
-
-
-def _projection_cache_path(root: str) -> Path:
-    return Path(root) / _PROJECTION_CACHE_PATH
-
-
-def _context_stat(task_dir: Path) -> list[int]:
-    info = (task_dir / "spec-context.yml").stat()
-    return [info.st_mtime_ns, info.st_ctime_ns, info.st_size]
-
-
-def _load_projection_cache(root: str) -> Mapping[str, object]:
-    try:
-        value = json.loads(_projection_cache_path(root).read_text(encoding="utf-8"))
-    except (OSError, UnicodeError, json.JSONDecodeError):
-        return {}
-    if not isinstance(value, dict):
-        return {}
-    checksum = value.pop("checksum", None)
-    expected = hashlib.sha256(json.dumps(value, sort_keys=True, ensure_ascii=False).encode()).hexdigest()
-    return value if checksum == expected else {}
-
-
-def _cached_projection(
-    root: str, task_dir: Path, task_id: str, current_hash: str
-) -> Optional[tuple[str, bool]]:
-    cache = _load_projection_cache(root)
-    if (
-        cache.get("version") != 1
-        or cache.get("task_id") != task_id
-        or cache.get("context_sha256") != current_hash
-        or not isinstance(cache.get("task_file"), str)
-        or not isinstance(cache.get("text"), str)
-        or not isinstance(cache.get("truncated"), bool)
-    ):
-        return None
-    task_file = Path(str(cache["task_file"]))
-    if task_file.parent != task_dir or not task_file.is_file():
-        return None
-    try:
-        directory_mtime = task_dir.stat().st_mtime_ns
-        task_mtime = task_file.stat().st_mtime_ns
-    except OSError:
-        return None
-    if cache.get("task_dir_mtime_ns") != directory_mtime or cache.get("task_mtime_ns") != task_mtime:
-        return None
-    if cache.get("context_stat") != _context_stat(task_dir):
-        return None
-    if cache.get("projector_sha256") != hashlib.sha256(Path(cf_spec_session.__file__).read_bytes()).hexdigest():
-        return None
-    if cache.get("task_sha256") != hashlib.sha256(task_file.read_bytes()).hexdigest():
-        return None
-    return str(cache["text"]), bool(cache["truncated"])
-
-
-def _save_projection_cache(
-    root: str,
-    task_dir: Path,
-    task_file: Path,
-    task_id: str,
-    current_hash: str,
-    text: str,
-    truncated: bool,
-) -> None:
-    try:
-        payload = {
-            "version": 1,
-            "task_id": task_id,
-            "context_sha256": current_hash,
-            "context_stat": _context_stat(task_dir),
-            "projector_sha256": hashlib.sha256(Path(cf_spec_session.__file__).read_bytes()).hexdigest(),
-            "task_file": str(task_file),
-            "task_dir_mtime_ns": task_dir.stat().st_mtime_ns,
-            "task_mtime_ns": task_file.stat().st_mtime_ns,
-            "task_sha256": hashlib.sha256(task_file.read_bytes()).hexdigest(),
-            "text": text,
-            "truncated": truncated,
-        }
-        path = _projection_cache_path(root)
-        payload["checksum"] = hashlib.sha256(json.dumps(payload, sort_keys=True, ensure_ascii=False).encode()).hexdigest()
-        path.parent.mkdir(parents=True, exist_ok=True)
-        temporary = path.with_name(f".{path.name}.{os.getpid()}.tmp")
-        temporary.write_text(json.dumps(payload, ensure_ascii=False), encoding="utf-8")
-        os.replace(temporary, path)
-    except (OSError, TypeError, UnicodeError):
-        if "temporary" in locals() and temporary.exists():
-            try:
-                temporary.unlink()
-            except OSError:
-                pass
-
-
-def _verify_bound_specs(root: str, context: SpecContext) -> None:
-    spec_root = Path(root) / ".code-flow/specs"
-    for binding in context.bindings:
-        target = spec_root / binding.path
-        try:
-            current = hashlib.sha256(target.read_bytes()).hexdigest()
-        except OSError as exc:
-            raise RouterError("bound_spec_missing", f"{binding.path}: {exc}; refresh Context") from exc
-        if current != binding.hashes.file_sha256:
-            raise RouterError("bound_spec_drift", f"{binding.path} changed; refresh Context before coding")
-
-
-def _scope_expansion(root: str, context: SpecContext, paths: Sequence[str]) -> tuple[str, ...]:
-    bound = {binding.spec_id for binding in context.bindings}
-    candidates = resolve_candidate_headers(
-        root, "code", paths, matched_only=True,
-        excluded_paths=tuple(binding.path for binding in context.bindings),
-    )
-    return tuple(item.spec_id for item in candidates
-                 if item.spec_id not in bound and item.enforcement == "required")
-
-
-def _active_route(root: str, paths: Sequence[str] = (), check_scope: bool = False) -> RouteResult:
-    try:
-        active = load_active_task(root)
-        task_dir = (Path(root) / active.task_dir).resolve()
-        context, current_hash = load_snapshot(root, str(task_dir / "spec-context.yml"), load_context)
-    except (ContextError, OSError, ValueError) as exc:
-        raise RouterError("invalid_active_task", str(exc)) from exc
-    if current_hash != active.context_sha256:
-        raise RouterError(
-            "active_context_drift",
-            "active marker Context hash does not match; run `code-flow spec refresh --task-dir <dir> --root <root> --json` to re-sync it (refresh updates the marker hash), or `code-flow spec active doctor --resync` with the hash from `code-flow spec status --json`",
-        )
-    _verify_bound_specs(root, context)
-    cached = _cached_projection(root, task_dir, active.task_id, current_hash)
-    if cached is None:
-        task_file = _task_file(task_dir, active.task_id)
-        try:
-            projection = project_task_session(context, str(task_file), active.task_id, context_hash=current_hash)
-        except ValueError as exc:
-            raise RouterError("invalid_task_projection", str(exc)) from exc
-        _save_projection_cache(
-            root, task_dir, task_file, active.task_id, current_hash, projection.text, projection.truncated
-        )
-        text, truncated = projection.text, projection.truncated
-    else:
-        text, truncated = cached
-    if truncated:
-        raise RouterError("task_projection_truncated", "split the TASK before coding")
-    refs = tuple(binding.spec_id for binding in context.bindings
-                 if any(f"`{binding.spec_id}#{rule.ref}`" in text for rule in binding.rules))
-    expanded = _scope_expansion(root, context, paths) if check_scope else ()
-    return RouteResult("task", text, refs, current_hash, expanded)
-
-
-def _read_candidates(root: str, paths: Sequence[str], compress: bool = True) -> RouteResult:
-    from codeflow.spec.cf_spec_budget import SpecBudgetError, path_specs
-    try:
-        specs = path_specs(root, paths, compress)
-    except SpecBudgetError as exc:
-        raise RouterError(exc.code, str(exc)) from exc
-    text = assemble_context(specs, "## Active Specs (path-mapped)") if specs else ""
-    budget = load_config(root).get("budget", {})
-    if not isinstance(budget, dict):
-        raise RouterError("invalid_budget", "budget must be a mapping")
-    maximum = min(int(budget.get("total", 2500)), int(budget.get("l1_max", 1700)))
-    if maximum <= 0 or estimate_tokens(text) > maximum:
-        raise RouterError("spec_budget_exceeded", f"Matched Specs exceed {maximum} estimated tokens; create a focused TASK Context or split the editing scope. Required constraints were not truncated.")
-    return RouteResult("path", text, tuple(item["path"] for item in specs))
-
-
-def _catalog_path(root: str) -> Path:
-    return Path(root) / ".code-flow/.catalog-state.json"
-
-
-def _load_catalog_state(root: str) -> dict[str, object]:
-    path = _catalog_path(root)
-    if not path.exists():
-        return {"version": 1, "session_id": "", "prompt_count": 0, "last_emitted": 0}
-    try:
-        value = json.loads(path.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError) as exc:
-        raise RouterError("invalid_catalog_state", str(exc)) from exc
-    if not isinstance(value, dict) or value.get("version") != 1:
-        raise RouterError("invalid_catalog_state", "Catalog state schema must be version 1")
-    if any(type(value.get(key)) is not int or value[key] < 0 for key in ("prompt_count", "last_emitted")):
-        raise RouterError("invalid_catalog_state", "Catalog counters must be nonnegative integers")
-    return value
-
-
-def _save_catalog_state(root: str, state: Mapping[str, object]) -> None:
-    path = _catalog_path(root)
-    path.parent.mkdir(parents=True, exist_ok=True)
-    temporary = ""
-    try:
-        with tempfile.NamedTemporaryFile("w", encoding="utf-8", dir=path.parent, delete=False) as handle:
-            temporary = handle.name
-            json.dump(state, handle, ensure_ascii=False)
-            handle.flush()
-            os.fsync(handle.fileno())
-        os.replace(temporary, path)
-    except OSError as exc:
-        if temporary and Path(temporary).exists():
-            Path(temporary).unlink()
-        warn(f"Spec Catalog dedup state could not be saved: {exc}")
-
-
-def _catalog_route(root: str, session_id: str, config: Mapping[str, object]) -> RouteResult:
-    state = _load_catalog_state(root)
-    same_session = state.get("session_id") == session_id
-    count = int(state.get("prompt_count", 0)) + 1 if same_session else 1
-    last = int(state.get("last_emitted", 0)) if same_session else 0
-    workflow = config.get("spec_workflow") if isinstance(config.get("spec_workflow"), dict) else {}
-    catalog_config = workflow.get("catalog") if isinstance(workflow.get("catalog"), dict) else {}
-    window = int(catalog_config.get("dedup_window", 5))
-    due = window <= 0 or last == 0 or count - last >= window
-    next_state = {"version": 1, "session_id": session_id, "prompt_count": count, "last_emitted": count if due else last}
-    if not due:
-        _save_catalog_state(root, next_state)
-        return RouteResult("catalog", "", ())
-    budget = config.get("budget") if isinstance(config.get("budget"), dict) else {}
-    maximum = int(budget.get("catalog_max", 200))
-    mapping = build_effective_mapping(root, config.get("path_mapping") or {})
-    text = build_spec_catalog(root, mapping, maximum)
-    from codeflow.spec.cf_injection import defer_commit
-    defer_commit(lambda: _save_catalog_state(root, next_state))
-    return RouteResult("catalog", text, ())
-
-
-def route_prompt(root: str, paths: Sequence[str], session_id: str, *, check_scope: bool = False) -> RouteResult:
-    try:
-        return _route_prompt(root, paths, session_id, check_scope)
-    except RouterError:
-        raise
-    except (ConfigError, ContextError, OSError, UnicodeError, ValueError, TypeError) as exc:
-        raise RouterError(getattr(exc, "code", "invalid_routing_input"), str(exc)) from exc
-
-
-def _route_prompt(root: str, paths: Sequence[str], session_id: str, check_scope: bool) -> RouteResult:
-    """Choose exactly one route; an invalid active marker never falls back."""
-    marker = Path(root) / ".code-flow/.active-task.json"
-    if marker.exists():
-        return _active_route(root, paths, check_scope)
-    config = load_config(root)
-    if not config:
-        return RouteResult("none", "", ())
-    if paths:
-        quality = config.get("quality_loop")
-        return _read_candidates(root, paths, resolve_compress(quality if isinstance(quality, dict) else {}))
-    return _catalog_route(root, session_id, config)