@michaelxwb/code-flow 0.6.4 → 0.8.1

package/src/core/code-flow/scripts/codeflow/cli/cf_validation.py

@@ -0,0 +1,31 @@
+"""Programmatic validation entry with complete Git scope and argv execution."""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from typing import IO, Optional, Sequence
+import sys
+
+from codeflow.task.cf_validation_service import validate_files, validation_scope
+
+
+def main(argv: Optional[Sequence[str]] = None, stdout: IO[str] = sys.stdout) -> int:
+    parser = argparse.ArgumentParser(prog=os.environ.get("CF_RUNTIME_COMMAND") or None)
+    parser.add_argument("--root", default=os.getcwd())
+    parser.add_argument("--files", nargs="*", default=[])
+    parser.add_argument("--budget", type=float)
+    parser.add_argument("--no-heavy", action="store_true", help="Skip heavy validators (task-level finish scope)")
+    parser.add_argument("--no-cache", action="store_true", help="Force validators to run; skip content-fingerprint reuse")
+    parser.add_argument("--scope-only", action="store_true")
+    parser.add_argument("--json", action="store_true")
+    args = parser.parse_args(argv)
+    try:
+        result = ({"files": validation_scope(args.root, args.files or None)} if args.scope_only
+                  else validate_files(args.root, args.files or None, args.budget, include_heavy=not args.no_heavy,
+                                      use_cache=not args.no_cache))
+        stdout.write(json.dumps(result, ensure_ascii=False))
+        return 3 if result.get("decision") == "block" else 0
+    except (OSError, ValueError) as exc:
+        stdout.write(json.dumps({"decision": "block", "error": str(exc)}, ensure_ascii=False))
+        return 2

package/src/core/code-flow/scripts/codeflow/core/cf_context_cache.py

@@ -0,0 +1,67 @@
+"""Rebuildable Context parse cache bound to source bytes and parser version."""
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+from typing import Protocol
+
+from codeflow.core import cf_fs
+from codeflow.core.cf_log import warn
+import codeflow.spec.cf_spec_context_model as cf_spec_context_model
+from codeflow.spec.cf_spec_context_model import (ContextError, SpecContext, context_from_data,
+                             context_sha256, context_to_data)
+
+
+class ContextLoader(Protocol):
+    def __call__(self, path: str, *, source: bytes | None = None) -> SpecContext: ...
+
+
+def _digest(value: dict[str, object]) -> str:
+    encoded = json.dumps(value, sort_keys=True, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
+    return hashlib.sha256(encoded).hexdigest()
+
+
+def _read(path: Path, key: str) -> dict[str, object]:
+    try:
+        text = cf_fs.read_text(path)
+        if text is None:
+            return {}
+        payload = json.loads(text)
+        if not isinstance(payload, dict):
+            return {}
+        checksum = payload.pop("checksum", None)
+        if payload.get("version") == 1 and payload.get("key") == key and checksum == _digest(payload):
+            return payload
+    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
+        warn(f"Context parse cache unavailable; reloading source: {exc}")
+    return {}
+
+
+def _write(path: Path, payload: dict[str, object]) -> None:
+    try:
+        payload = dict(payload, checksum=_digest(payload))
+        cf_fs.atomic_write_text(path, json.dumps(payload, ensure_ascii=False))
+    except (OSError, UnicodeError, TypeError) as exc:
+        warn(f"Context parse cache cannot be saved: {exc}")
+
+
+def load_snapshot(root: str, path: str, loader: ContextLoader) -> tuple[SpecContext, str]:
+    source = Path(path).read_bytes()
+    parser = Path(cf_spec_context_model.__file__).read_bytes()
+    key = hashlib.sha256(str(Path(path).resolve()).encode("utf-8") + b"\0"
+                         + hashlib.sha256(source).digest() + hashlib.sha256(parser).digest()).hexdigest()
+    cache = Path(root) / ".code-flow/.context-state.json"
+    payload = _read(cache, key)
+    if payload:
+        try:
+            context = context_from_data(payload.get("context"), path)
+            identity = payload.get("identity")
+            if isinstance(identity, str) and len(identity) == 64:
+                return context, identity
+        except ContextError as exc:
+            warn(f"Context parse cache invalid; reloading source: {exc}")
+    context = loader(path, source=source)
+    identity = context_sha256(context)
+    _write(cache, {"version": 1, "key": key, "context": context_to_data(context), "identity": identity})
+    return context, identity

package/src/core/code-flow/scripts/{cf_core.py → codeflow/core/cf_core.py}

@@ -1,10 +1,14 @@
 #!/usr/bin/env python3
 import fnmatch
+import json
 import os
 import re
 import sys
 import time
 
+from codeflow.core import cf_log
+from codeflow.core.cf_markdown import parse_frontmatter
+
 # --- Config cache (fix #3: avoid re-parsing YAML on every hook call) ---
 
 _config_cache: dict = {}
@@ -13,6 +17,12 @@ _effective_mapping_cache: dict = {}
 _ext_set_cache: dict = {}
 
 
+class ConfigError(ValueError):
+    """An existing project configuration cannot be read or validated."""
+
+    code = "invalid_config"
+
+
 def project_instruction_file(project_root: str, platform: str = "") -> str:
     """Select the installed platform's instruction file, with legacy fallback."""
     names = ("CLAUDE.md", "AGENTS.md") if platform in ("claude", "costrict") else ("AGENTS.md", "CLAUDE.md")
@@ -24,24 +34,27 @@ def load_config(project_root: str) -> dict:
     if not os.path.exists(config_path):
         return {}
     try:
-        mtime = os.path.getmtime(config_path)
-    except OSError:
-        return {}
+        info = os.stat(config_path)
+        signature = (info.st_mtime_ns, info.st_ctime_ns, info.st_size)
+    except OSError as exc:
+        raise ConfigError(f"{config_path}: {exc}") from exc
     cached = _config_cache.get(config_path)
-    if cached and cached["mtime"] == mtime:
+    if cached and cached["mtime"] == signature:
         return cached["data"]
     try:
         import yaml
-    except Exception:
-        return {}
+    except ImportError as exc:
+        raise ConfigError("PyYAML is required to read code-flow configuration") from exc
     try:
         with open(config_path, "r", encoding="utf-8") as file:
             data = yaml.safe_load(file)
-        result = data or {}
-        _config_cache[config_path] = {"mtime": mtime, "data": result}
+        if not isinstance(data, dict):
+            raise ConfigError(f"{config_path}: configuration must be a YAML mapping")
+        result = data
+        _config_cache[config_path] = {"mtime": signature, "data": result}
         return result
-    except Exception:
-        return {}
+    except (OSError, UnicodeError, yaml.YAMLError) as exc:
+        raise ConfigError(f"{config_path}: {exc}") from exc
 
 
 def estimate_tokens(text: str) -> int:
@@ -86,9 +99,6 @@ def _spec_path_from_entry(entry) -> str:
 
 
 def discover_spec_domains(project_root: str) -> dict:
-    cached = _spec_domains_cache.get(project_root)
-    if cached is not None:
-        return cached
     specs_root = os.path.join(project_root, ".code-flow", "specs")
     discovered = {}
     if not os.path.isdir(specs_root):
@@ -122,12 +132,24 @@ def _default_spec_entry(rel: str) -> dict:
     return {"path": rel, "tags": ["*"], "tier": tier}
 
 
+def _mapping_signature(mapping: dict) -> str:
+    """Content signature for the mapping cache.
+
+    `id(mapping)` keys were reused after GC, potentially serving a mapping
+    built from stale config contents. Hash the JSON projection instead.
+    """
+    try:
+        return json.dumps(mapping or {}, ensure_ascii=False, sort_keys=True, default=str)
+    except (TypeError, ValueError):
+        return ""
+
+
 def build_effective_mapping(project_root: str, mapping: dict) -> dict:
-    cache_key = (project_root, id(mapping))
+    discovered = discover_spec_domains(project_root)
+    cache_key = (project_root, _mapping_signature(mapping), _mapping_signature(discovered))
     cached = _effective_mapping_cache.get(cache_key)
     if cached is not None:
         return cached
-    discovered = discover_spec_domains(project_root)
     effective = {}
 
     for domain, rel_paths in discovered.items():
@@ -182,10 +204,12 @@ def is_code_file(rel_path: str, runtime_config: dict) -> bool:
     if ext in (runtime_config.get("skip_extensions") or []):
         return False
     code_exts = runtime_config.get("code_extensions") or []
-    ext_set = _ext_set_cache.get(id(code_exts))
+    # Content key: id() reuse after GC could serve a stale extension set.
+    ext_key = tuple(code_exts)
+    ext_set = _ext_set_cache.get(ext_key)
     if ext_set is None:
         ext_set = frozenset(code_exts)
-        _ext_set_cache[id(code_exts)] = ext_set
+        _ext_set_cache[ext_key] = ext_set
     return ext in ext_set
 
 
@@ -201,119 +225,6 @@ def match_domains(rel_path: str, mapping: dict) -> list:
     return domains
 
 
-# --- Fix #2: safe depluralization with allowlist ---
-
-_SAFE_DEPLURALS = {
-    "models": "model",
-    "services": "service",
-    "components": "component",
-    "handlers": "handler",
-    "controllers": "controller",
-    "middlewares": "middleware",
-    "validators": "validator",
-    "schemas": "schema",
-    "repositories": "repository",
-    "migrations": "migration",
-    "fixtures": "fixture",
-    "plugins": "plugin",
-    "routes": "route",
-    "routers": "router",
-    "hooks": "hook",
-    "pages": "page",
-    "stores": "store",
-    "styles": "style",
-    "types": "type",
-    "configs": "config",
-    "scripts": "script",
-    "tasks": "task",
-    "specs": "spec",
-    "tests": "test",
-    "utils": "util",
-    "helpers": "helper",
-    "views": "view",
-    "templates": "template",
-    "errors": "error",
-    "exceptions": "exception",
-    "docs": "doc",
-}
-
-# --- Fix #1: semantic directory → concept tag mapping ---
-
-_DIR_SEMANTIC_TAGS = {
-    "handlers": ["api", "error"],
-    "controllers": ["api"],
-    "middleware": ["api", "config"],
-    "middlewares": ["api", "config"],
-    "routers": ["api", "route"],
-    "routes": ["api", "route"],
-    "views": ["ui", "render"],
-    "templates": ["ui", "render"],
-    "models": ["model", "database", "orm", "schema"],
-    "model": ["model", "database", "orm", "schema"],
-    "schemas": ["model", "schema", "database"],
-    "migrations": ["database", "migration"],
-    "repositories": ["database", "query"],
-    "dao": ["database", "query"],
-    "validators": ["quality", "error"],
-    "exceptions": ["error", "exception"],
-    "errors": ["error", "exception"],
-    "auth": ["api", "config"],
-    "config": ["config", "deploy"],
-    "configs": ["config", "deploy"],
-    "settings": ["config"],
-    "tests": ["test", "quality"],
-    "test": ["test", "quality"],
-    "utils": ["quality"],
-    "helpers": ["quality"],
-    "lib": ["quality"],
-    "common": ["quality"],
-    "shared": ["quality"],
-    "core": ["quality"],
-    "logging": ["log", "logging"],
-    "logger": ["log", "logging"],
-    "logs": ["log", "logging"],
-    "cache": ["cache", "performance"],
-    "queue": ["performance"],
-    "jobs": ["performance"],
-    "workers": ["performance"],
-}
-
-
-def extract_context_tags(rel_path: str) -> set:
-    """Extract context tags from a file path for spec matching.
-
-    Uses three strategies:
-    1. Directory names as tags (with safe depluralization)
-    2. Semantic mapping: common directory names → concept tags
-    3. Filename stem word splitting
-    """
-    rel_path = normalize_path(rel_path)
-    tags = set()
-    parts = rel_path.split("/")
-
-    for part in parts[:-1]:
-        lower = part.lower()
-        tags.add(lower)
-        deplural = _SAFE_DEPLURALS.get(lower)
-        if deplural:
-            tags.add(deplural)
-        semantic = _DIR_SEMANTIC_TAGS.get(lower)
-        if semantic:
-            tags.update(semantic)
-
-    filename = parts[-1] if parts else ""
-    stem = os.path.splitext(filename)[0].lower()
-    if stem:
-        words = _FILENAME_WORDS_RE.findall(stem.replace("_", " ").replace("-", " "))
-        tags.update(words)
-        for word in words:
-            semantic = _DIR_SEMANTIC_TAGS.get(word)
-            if semantic:
-                tags.update(semantic)
-
-    return tags
-
-
 def normalize_spec_entry(entry) -> dict:
     """Normalize spec config entry. Supports both old (string) and new (dict) format."""
     if isinstance(entry, str):
@@ -327,7 +238,6 @@ def normalize_spec_entry(entry) -> dict:
     return {}
 
 
-_FILENAME_WORDS_RE = re.compile(r"[a-z]+")
 _BULLET_PREFIXES = ("- ", "* ", "+ ")
 _COMPRESS_HTML_RE = re.compile(r"<!--.*?-->", re.DOTALL)
 _COMPRESS_TRAILING_WS_RE = re.compile(r"[ \t]+$", re.MULTILINE)
@@ -376,107 +286,6 @@ def compress_content(text: str) -> str:
         return text
 
 
-def read_matched_specs(
-    project_root: str,
-    domain: str,
-    matched: list,
-    compress: bool = True,
-) -> list:
-    """Read matched spec files; optionally apply lossless compression.
-
-    When ``compress`` is True (default), each spec's content is passed through
-    :func:`compress_content` before token estimation so callers can make
-    explicit budget decisions from the returned token counts.
-
-    Returned items carry:
-        - ``content``: final content (compressed when ``compress=True``)
-        - ``tokens``: token count of final content (drives budget decisions)
-        - ``tokens_raw``: token count of uncompressed content (for cf-stats)
-
-    ``CF_DEBUG=1`` emits a per-file ``compress path=... raw=... compressed=...
-    saved=...%`` record via :func:`debug_log`.
-    """
-    specs_root = os.path.join(project_root, ".code-flow", "specs")
-    specs: list = []
-    for cfg in matched:
-        rel = cfg["path"]
-        spec_path = os.path.join(specs_root, rel)
-        try:
-            with open(spec_path, "r", encoding="utf-8") as f:
-                raw_content = f.read().strip()
-            # Frontmatter feeds the spec catalog only — never spend injection
-            # budget on it. Specs without frontmatter pass through unchanged.
-            _, raw_content = parse_spec_frontmatter(raw_content)
-            raw_content = raw_content.strip()
-            if not raw_content:
-                continue
-            raw_tokens = estimate_tokens(raw_content)
-            if compress:
-                try:
-                    content = compress_content(raw_content)
-                except Exception as exc:
-                    _log(f"read_matched_specs compress failed path={rel}: {exc}")
-                    content = raw_content
-            else:
-                content = raw_content
-            tokens = estimate_tokens(content)
-            if compress and raw_tokens != tokens:
-                saved_pct = (
-                    round((raw_tokens - tokens) * 100 / raw_tokens, 1)
-                    if raw_tokens
-                    else 0.0
-                )
-                debug_log(
-                    f"compress path={rel} raw={raw_tokens} "
-                    f"compressed={tokens} saved={saved_pct}%",
-                    project_root,
-                )
-            specs.append(
-                {
-                    "path": rel,
-                    "content": content,
-                    "tokens": tokens,
-                    "tokens_raw": raw_tokens,
-                    "domain": domain,
-                    "tier": cfg.get("tier", 1),
-                }
-            )
-        except Exception:
-            continue
-    return specs
-
-
-# --- Kept for backward compatibility with old config format ---
-
-
-def read_specs(project_root: str, domain: str, domain_cfg: dict) -> list:
-    specs_root = os.path.join(project_root, ".code-flow", "specs")
-    specs = []
-    for entry in domain_cfg.get("specs") or []:
-        cfg = normalize_spec_entry(entry)
-        rel = cfg.get("path", "")
-        if not rel:
-            continue
-        spec_path = os.path.join(specs_root, rel)
-        try:
-            with open(spec_path, "r", encoding="utf-8") as file:
-                content = file.read().strip()
-            if not content:
-                continue
-            specs.append(
-                {
-                    "path": rel,
-                    "content": content,
-                    "tokens": estimate_tokens(content),
-                    "domain": domain,
-                    "tier": cfg.get("tier", 1),
-                }
-            )
-        except Exception:
-            continue
-    return specs
-
-
 def non_injectable_specs(effective_mapping: dict) -> set:
     """tags: [] 的命令专用模板（如 shared 的 PRD/设计模板）——永不自动注入，
     预算统计（cf-stats/cf-scan）必须排除，避免利用率虚高。"""
@@ -501,7 +310,9 @@ def resolve_quality_loop(config: dict) -> dict:
         return {"enabled": False, "post_check": False,
                 "stop_check": False, "finish_check": False,
                 "correction_capture": False,
-                "compress_reminder": False}
+                "compress_reminder": False,
+                "heavy_at_finish": False,
+                "finish_verifier_budget": 300.0}
     cfg = config.get("quality_loop")
     cfg = cfg if isinstance(cfg, dict) else {}
     enabled = cfg.get("enabled") is True
@@ -509,6 +320,12 @@ def resolve_quality_loop(config: dict) -> dict:
     def _sub(key: str) -> bool:
         return enabled and cfg.get(key) is not False
 
+    # 任务级 verifier 执行预算（秒）：超预算的 command/test verifier 延后到
+    # 需求级 verify-e2e；0 = 不限制（恢复旧行为）。非法值回落默认 300。
+    budget = cfg.get("finish_verifier_budget", 300)
+    if isinstance(budget, bool) or not isinstance(budget, (int, float)) or budget < 0 or budget != budget:
+        budget = 300.0
+
     return {
         "enabled": enabled,
         "post_check": _sub("post_check"),
@@ -516,6 +333,9 @@ def resolve_quality_loop(config: dict) -> dict:
         "finish_check": _sub("finish_check"),
         "correction_capture": _sub("correction_capture"),
         "compress_reminder": _sub("compress_reminder"),
+        # heavy validator 默认只在归档 cf_validation / /cf-validate 全量执行
+        "heavy_at_finish": enabled and cfg.get("heavy_at_finish") is True,
+        "finish_verifier_budget": float(budget),
     }
 
 
@@ -540,30 +360,13 @@ def resolve_enforcement(config: dict) -> str:
     return "required"
 
 
-_FRONTMATTER_RE = re.compile(r"\A---[ \t]*\n(.*?)\n---[ \t]*\n?", re.DOTALL)
-
-
 def parse_spec_frontmatter(content: str) -> tuple:
     """Split optional YAML frontmatter from spec content → (meta, body).
 
-    Parses only flat `key: value` string pairs — enough for `description:` —
-    so the hook hot path never needs pyyaml for this. Content without
-    frontmatter returns ({}, content) unchanged.
+    Flat `key: value` parsing keeps the hook hot path free of pyyaml; content
+    without frontmatter returns ({}, content) unchanged.
     """
-    if not isinstance(content, str):
-        return {}, content
-    match = _FRONTMATTER_RE.match(content)
-    if not match:
-        return {}, content
-    meta: dict = {}
-    for line in match.group(1).splitlines():
-        key, sep, value = line.partition(":")
-        if not sep:
-            continue
-        key = key.strip()
-        if key:
-            meta[key] = value.strip().strip('"').strip("'")
-    return meta, content[match.end():]
+    return parse_frontmatter(content)
 
 
 def spec_description(content: str) -> str:
@@ -595,6 +398,14 @@ CATALOG_HEADER = (
 )
 
 
+class CatalogBudgetError(ConfigError):
+    """Catalog cannot fit its mandatory header and complete-list notice."""
+
+    def __init__(self, minimum: int) -> None:
+        self.minimum = minimum
+        super().__init__(f"catalog_max is too small; minimum is {minimum} estimated tokens")
+
+
 def _catalog_entries(project_root: str, effective_mapping: dict) -> list:
     """Collect injectable specs as (tier, rel_path, abs_path) sorted tier1-first."""
     specs_root = os.path.join(project_root, ".code-flow", "specs")
@@ -604,7 +415,7 @@ def _catalog_entries(project_root: str, effective_mapping: dict) -> list:
             cfg = normalize_spec_entry(entry)
             rel = cfg.get("path", "")
             # tags: [] marks command-only templates — never advertised either
-            if not rel or not cfg.get("tags"):
+            if not rel or rel.startswith("_session/") or not cfg.get("tags"):
                 continue
             entries.append((cfg.get("tier", 1), rel, os.path.join(specs_root, rel)))
     # Tier 1 constraints first so budget truncation drops navigation maps first
@@ -612,66 +423,77 @@ def _catalog_entries(project_root: str, effective_mapping: dict) -> list:
     return entries
 
 
-def build_spec_catalog(
-    project_root: str, effective_mapping: dict, catalog_max: int = 200
-) -> str:
-    """Build the compact Catalog used only when no task or path is active.
-
-    The model performs the semantic matching itself by reading the catalog and
-    pulling relevant specs — replacing keyword-table guessing on prompts with
-    no explicit path evidence. Cached per project_root keyed by the mtimes of
-    config.yml and every listed spec file.
-    """
-    entries = _catalog_entries(project_root, effective_mapping)
-    if not entries:
-        return ""
-    config_path = os.path.join(project_root, ".code-flow", "config.yml")
-    signature = []
-    for path in [config_path] + [abs_path for _, _, abs_path in entries]:
-        try:
-            signature.append((path, os.path.getmtime(path)))
-        except OSError:
-            signature.append((path, 0.0))
-    signature = tuple(signature)
-    cached = _catalog_cache.get(project_root)
-    if cached and cached["signature"] == signature and cached["catalog_max"] == catalog_max:
-        return cached["catalog"]
-
+def _catalog_lines(entries: list[tuple[int, str, str]]) -> list[str]:
     lines = []
     for tier, rel, abs_path in entries:
         try:
             with open(abs_path, "r", encoding="utf-8") as f:
                 desc = spec_description(f.read())
-        except Exception:
+        except (OSError, UnicodeError) as exc:
+            _log(f"Spec Catalog read failed: {rel}: {exc}")
             continue
         suffix = "（导航地图）" if tier == 0 else ""
         lines.append(f"- `{rel}` — {desc or '(no description)'}{suffix}")
-    if not lines:
-        return ""
+    return lines
 
+
+def _bounded_catalog(lines: list[str], maximum: int) -> str:
     catalog = CATALOG_HEADER
     included = 0
+    def footer(count: int) -> str:
+        if count == len(lines):
+            return ""
+        return (f"\n已展示 {count}/{len(lines)} 项；其余规范请运行 "
+                "`code-flow spec catalog --root . --stage code --json` 获取。")
     for line in lines:
         candidate = catalog + "\n" + line
-        if estimate_tokens(candidate) > catalog_max:
-            break
+        if estimate_tokens(candidate + footer(included + 1)) > maximum:
+            continue
         catalog = candidate
         included += 1
-    if included < len(lines):
-        _log(
-            f"WARNING: spec catalog truncated to {included}/{len(lines)} "
-            f"entries (catalog_max={catalog_max} tokens)"
-        )
-    if included == 0:
+    text = catalog + footer(included)
+    if estimate_tokens(text) > maximum:
+        raise CatalogBudgetError(estimate_tokens(text))
+    return text
+
+
+def build_spec_catalog(project_root: str, effective_mapping: dict, catalog_max: int = 200) -> str:
+    """Publish bounded navigation with an explicit complete-catalog entry point."""
+    entries = _catalog_entries(project_root, effective_mapping)
+    if not entries:
         return ""
-    _catalog_cache[project_root] = {
-        "signature": signature,
-        "catalog_max": catalog_max,
-        "catalog": catalog,
-    }
+    signature = []
+    for _, _, path in entries:
+        try:
+            info = os.stat(path)
+            signature.append((path, info.st_mtime_ns, info.st_ctime_ns, info.st_size))
+        except OSError:
+            signature.append((path, 0, 0, 0))
+    cached = _catalog_cache.get(project_root)
+    if cached and cached["signature"] == signature and cached["catalog_max"] == catalog_max:
+        return cached["catalog"]
+    lines = _catalog_lines(entries)
+    catalog = _bounded_catalog(lines, catalog_max) if lines else ""
+    _catalog_cache[project_root] = {"signature": signature, "catalog_max": catalog_max, "catalog": catalog}
     return catalog
 
 
+def catalog_omissions(project_root: str, effective_mapping: dict, catalog_max: int) -> dict[str, object]:
+    """Compute omissions from the actual bounded catalog without changing its ordering."""
+    from collections import Counter
+    lines = _catalog_lines(_catalog_entries(project_root, effective_mapping))
+    text = build_spec_catalog(project_root, effective_mapping, catalog_max)
+    remaining = Counter(line for line in text.splitlines() if line.startswith('- `'))
+    dropped: list[str] = []
+    for line in lines:
+        if remaining[line]:
+            remaining[line] -= 1
+        else:
+            dropped.append(line.split('`', 2)[1])
+    return {"dropped_count": len(dropped),
+            "dropped_domains": sorted({path.split('/', 1)[0] for path in dropped})}
+
+
 def assemble_context(specs: list, heading: str) -> str:
     parts = [heading]
     parts.append("以上规范是本次开发的约束条件，生成代码必须遵循。")
@@ -695,8 +517,8 @@ def assemble_context(specs: list, heading: str) -> str:
 
 
 def _log(msg: str) -> None:
-    """Log to stderr (fix #9: don't pollute stdout which is hook output)."""
-    print(msg, file=sys.stderr)
+    """Diagnostics go to stderr through the shared L0 writer (fix #9)."""
+    cf_log.warn(msg)
 
 
 _PROCESS_START = time.monotonic()