@michaelxwb/code-flow 0.5.2 → 0.6.1

package/src/core/code-flow/scripts/cf_core.py

@@ -1,6 +1,5 @@
 #!/usr/bin/env python3
 import fnmatch
-import json
 import os
 import re
 import sys
@@ -142,31 +141,15 @@ def build_effective_mapping(project_root: str, mapping: dict) -> dict:
     return effective
 
 
-def fallback_domains_for_context(mapping: dict, context_tags: set) -> set:
-    """Search space for per-spec tag matching when no path pattern fires.
-
-    Returns domains whose name matches context_tags when possible; otherwise
-    returns every configured domain so that per-spec tag matching downstream
-    can still cherry-pick. The per-spec tags in config.yml remain the real
-    filter — this function only widens the search space, never injects.
-    """
-    if not mapping:
-        return set()
-    by_name = {domain for domain in mapping.keys() if domain.lower() in context_tags}
-    if by_name:
-        return by_name
-    return set(mapping.keys())
-
-
-def is_code_file(rel_path: str, inject_config: dict) -> bool:
+def is_code_file(rel_path: str, runtime_config: dict) -> bool:
     rel_path = normalize_path(rel_path)
-    for pattern in inject_config.get("skip_paths") or []:
+    for pattern in runtime_config.get("skip_paths") or []:
         if fnmatch.fnmatch(rel_path, pattern):
             return False
     _, ext = os.path.splitext(rel_path)
-    if ext in (inject_config.get("skip_extensions") or []):
+    if ext in (runtime_config.get("skip_extensions") or []):
         return False
-    code_exts = inject_config.get("code_extensions") or []
+    code_exts = runtime_config.get("code_extensions") or []
     ext_set = _ext_set_cache.get(id(code_exts))
     if ext_set is None:
         ext_set = frozenset(code_exts)
@@ -299,112 +282,6 @@ def extract_context_tags(rel_path: str) -> set:
     return tags
 
 
-# --- Fix #5: prompt-text → tag mapping (bilingual aliases) ---
-#
-# Maps each canonical English tag (as used in .code-flow/config.yml spec tags)
-# to a list of substrings we look for in user prompt text. When a user writes
-# "写一个用户登录服务，注意性能和异常处理", "性能" → performance and "异常" →
-# exception, so the corresponding specs get injected at prompt submission time
-# instead of waiting for the Edit/Write tool call.
-#
-# Kept in Python (not config.yml) because .code-flow/config.yml is category
-# 'merge' in cli.js — existing installs wouldn't pick up new aliases on
-# upgrade. cf_core.py is category 'tool' so it's overwritten on upgrade.
-_TAG_ALIASES = {
-    "quality": ["质量", "代码质量", "规范"],
-    "performance": ["性能", "优化", "效率", "perf"],
-    "error": ["错误", "报错"],
-    "exception": ["异常", "异常处理"],
-    "test": ["测试", "单元测试", "unit test"],
-    "timeout": ["超时"],
-    "retry": ["重试"],
-    "cache": ["缓存"],
-    "log": ["日志", "日志记录", "打印日志"],
-    "logging": ["日志", "日志记录"],
-    "database": ["数据库", "db"],
-    "query": ["查询", "sql"],
-    "migration": ["迁移"],
-    "schema": ["数据模型", "模式"],
-    "api": ["接口", "api"],
-    "deploy": ["部署", "发布"],
-    "config": ["配置"],
-    "component": ["组件"],
-    "render": ["渲染"],
-    "ui": ["界面", "ui", "样式"],
-    "route": ["路由"],
-    "page": ["页面"],
-    "state": ["状态"],
-    "hook": ["hook", "钩子"],
-    "inject": ["inject", "注入", "注入规范"],
-    "spec": ["spec", "规范", "约束"],
-    "scan": ["scan", "扫描", "审计"],
-    "stats": ["stats", "统计"],
-    "session": ["session", "会话"],
-    "init": ["init", "初始化"],
-    "upgrade": ["upgrade", "升级"],
-    "merge": ["merge", "合并"],
-    "platform": ["platform", "平台", "适配器"],
-    "adapter": ["adapter", "适配器"],
-}
-
-_SHORT_ASCII_ALIAS_THRESHOLD = 3
-
-def _is_short_ascii(token: str) -> bool:
-    if len(token) > _SHORT_ASCII_ALIAS_THRESHOLD:
-        return False
-    try:
-        token.encode("ascii")
-        return True
-    except UnicodeEncodeError:
-        return False
-
-
-# Precompute (needle, is_short_ascii, compiled_pattern_or_None) at import time
-# so extract_prompt_tags() is a pure lookup loop with zero per-call overhead.
-_PREPARED_ALIASES: list = []
-
-
-def _init_prepared_aliases() -> None:
-    for canonical, aliases in _TAG_ALIASES.items():
-        entries = []
-        for alias in [canonical, *aliases]:
-            needle = alias.lower()
-            if _is_short_ascii(needle):
-                pattern = re.compile(r"\b" + re.escape(needle) + r"\b", re.IGNORECASE)
-                entries.append((needle, True, pattern))
-            else:
-                entries.append((needle, False, None))
-        _PREPARED_ALIASES.append((canonical, entries))
-
-
-_init_prepared_aliases()
-
-
-def extract_prompt_tags(prompt_text) -> set:
-    """Scan prompt text for alias hits and return canonical tags.
-
-    - Lowercases ASCII (Chinese is unaffected by .lower()).
-    - Short ASCII aliases matched with word-boundary regex (precompiled at import).
-    - Chinese aliases and long English aliases use plain substring match.
-    - Silent on empty/non-string input.
-    """
-    if not isinstance(prompt_text, str) or not prompt_text.strip():
-        return set()
-    lower = prompt_text.lower()
-    hits: set = set()
-    for canonical, entries in _PREPARED_ALIASES:
-        for needle, is_short, pattern in entries:
-            if is_short:
-                if pattern.search(lower):  # type: ignore[union-attr]
-                    hits.add(canonical)
-                    break
-            else:
-                if needle in lower:
-                    hits.add(canonical)
-                    break
-    return hits
-
-
 def normalize_spec_entry(entry) -> dict:
     """Normalize spec config entry. Supports both old (string) and new (dict) format."""
     if isinstance(entry, str):
@@ -418,33 +295,6 @@ def normalize_spec_entry(entry) -> dict:
     return {}
 
 
-def match_specs_by_tags(
-    specs_config: list, context_tags: set, prompt_tags: set = None
-) -> tuple:
-    """Return (matched_specs, has_tier1_match).
-
-    Wildcard tag '*' always matches (used by tier 0 specs like _map.md).
-    prompt_tags (if provided) are unioned with context_tags so that Chinese/
-    English keywords from the user prompt can also gate tier 1 specs.
-    The caller uses has_tier1_match to decide whether to fallback to all specs.
-    """
-    effective_tags = context_tags if prompt_tags is None else (context_tags | prompt_tags)
-    matched = []
-    has_tier1_match = False
-    for entry in specs_config:
-        cfg = normalize_spec_entry(entry)
-        if not cfg.get("path"):
-            continue
-        spec_tags = set(cfg.get("tags") or [])
-        if "*" in spec_tags:
-            matched.append(cfg)
-        elif spec_tags & effective_tags:
-            matched.append(cfg)
-            if cfg.get("tier", 1) != 0:
-                has_tier1_match = True
-    return matched, has_tier1_match
-
-
 _FILENAME_WORDS_RE = re.compile(r"[a-z]+")
 _BULLET_PREFIXES = ("- ", "* ", "+ ")
 _COMPRESS_HTML_RE = re.compile(r"<!--.*?-->", re.DOTALL)
@@ -503,8 +353,8 @@ def read_matched_specs(
     """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 ``select_specs_tiered``
-    budget decisions benefit from compression savings.
+    :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``)
@@ -595,74 +445,6 @@ def read_specs(project_root: str, domain: str, domain_cfg: dict) -> list:
     return specs
 
 
-def select_specs(specs: list, budget: int, priorities: dict) -> list:
-    """Legacy select by priority. Used by cf-inject manual command."""
-    if budget <= 0:
-        return []
-
-    def priority(spec: dict) -> int:
-        value = priorities.get(spec.get("path"))
-        if isinstance(value, int):
-            return value
-        try:
-            return int(value)
-        except Exception:
-            return 1000
-
-    ordered = sorted(specs, key=lambda spec: (priority(spec), spec.get("path", "")))
-    selected = []
-    total = 0
-    for spec in ordered:
-        if total + spec.get("tokens", 0) <= budget:
-            selected.append(spec)
-            total += spec.get("tokens", 0)
-    return selected
-
-
-def select_specs_tiered(specs: list, budget: int, map_max: int = 400) -> list:
-    """Tier-aware spec selection.
-
-    Tier 0: included if within map_max budget (fix #4).
-    Tier 1: budget-controlled, ordered by list position (preserved).
-    """
-    tier0 = [s for s in specs if s.get("tier", 1) == 0]
-    tier1 = [s for s in specs if s.get("tier", 1) != 0]
-
-    selected = []
-    for spec in tier0:
-        if spec.get("tokens", 0) <= map_max:
-            selected.append(spec)
-        else:
-            _log(
-                f"WARNING: {spec['path']} exceeds map_max budget "
-                f"({spec['tokens']} > {map_max} tokens), skipped"
-            )
-
-    total = 0
-    for spec in tier1:
-        tokens = spec.get("tokens", 0)
-        if total + tokens <= budget:
-            selected.append(spec)
-            total += tokens
-    return selected
-
-
-def resolve_inject_mode(inject_config: dict) -> str:
-    """Resolve inject.mode: only the literal string "catalog" enables catalog mode.
-
-    Missing / None / any other value → "full" (pre-0.5 behavior), so existing
-    user configs keep byte-identical injection after upgrade; new `code-flow
-    init` deployments opt in via the config template. Mirrors the
-    resolve_compress philosophy: only an explicit literal flips behavior.
-    """
-    if not isinstance(inject_config, dict):
-        return "full"
-    mode = inject_config.get("mode")
-    if isinstance(mode, str) and mode.strip().lower() == "catalog":
-        return "catalog"
-    return "full"
-
-
 def non_injectable_specs(effective_mapping: dict) -> set:
     """tags: [] 的命令专用模板（如 shared 的 PRD/设计模板）——永不自动注入，
     预算统计（cf-stats/cf-scan）必须排除，避免利用率虚高。"""
@@ -685,7 +467,8 @@ def resolve_quality_loop(config: dict) -> dict:
     """
     if not isinstance(config, dict):
         return {"enabled": False, "post_check": False,
-                "stop_check": False, "correction_capture": False}
+                "stop_check": False, "correction_capture": False,
+                "compress_reminder": False}
     cfg = config.get("quality_loop")
     cfg = cfg if isinstance(cfg, dict) else {}
     enabled = cfg.get("enabled") is True
@@ -698,9 +481,31 @@ def resolve_quality_loop(config: dict) -> dict:
         "post_check": _sub("post_check"),
         "stop_check": _sub("stop_check"),
         "correction_capture": _sub("correction_capture"),
+        "compress_reminder": _sub("compress_reminder"),
     }
 
 
+ENFORCEMENT_MODES = frozenset(("required", "warn", "inject"))
+
+
+def resolve_enforcement(config: dict) -> str:
+    """Project-wide Spec Workflow enforcement tier (light-mode ladder).
+
+    required — full fail-closed gates (default; upgraded projects keep it);
+    warn    — gates run but only log/report, never block the session;
+    inject  — routing/injection only; gates and blocks are disabled.
+    Missing or invalid values fail closed to "required".
+    """
+    if not isinstance(config, dict):
+        return "required"
+    workflow = config.get("spec_workflow")
+    workflow = workflow if isinstance(workflow, dict) else {}
+    value = workflow.get("enforcement")
+    if isinstance(value, str) and value in ENFORCEMENT_MODES:
+        return value
+    return "required"
+
+
 _FRONTMATTER_RE = re.compile(r"\A---[ \t]*\n(.*?)\n---[ \t]*\n?", re.DOTALL)
 
 
@@ -776,7 +581,7 @@ def _catalog_entries(project_root: str, effective_mapping: dict) -> list:
 def build_spec_catalog(
     project_root: str, effective_mapping: dict, catalog_max: int = 200
 ) -> str:
-    """Build the compact one-line-per-spec catalog for inject.mode=catalog.
+    """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
@@ -855,27 +660,6 @@ def assemble_context(specs: list, heading: str) -> str:
     return "\n\n".join(parts)
 
 
-def load_inject_state(project_root: str) -> dict:
-    state_path = os.path.join(project_root, ".code-flow", ".inject-state")
-    try:
-        with open(state_path, "r", encoding="utf-8") as file:
-            data = json.load(file)
-        if isinstance(data, dict):
-            return data
-    except Exception:
-        return {}
-    return {}
-
-
-def save_inject_state(project_root: str, payload: dict) -> None:
-    state_path = os.path.join(project_root, ".code-flow", ".inject-state")
-    try:
-        with open(state_path, "w", encoding="utf-8") as file:
-            json.dump(payload, file)
-    except Exception:
-        return
-
-
 def _log(msg: str) -> None:
     """Log to stderr (fix #9: don't pollute stdout which is hook output)."""
     print(msg, file=sys.stderr)
@@ -900,16 +684,16 @@ def ensure_utf8_io() -> None:
                 pass
 
 
-def resolve_compress(inject_config: dict) -> bool:
+def resolve_compress(quality_config: dict) -> bool:
     """Return whether Hook-time spec compression is enabled.
 
     Only a literal ``False`` turns it off; missing, ``None``, or any
     non-bool value falls back to ``True`` so upgrades pick up compression
     without requiring a config edit.
     """
-    if not isinstance(inject_config, dict):
+    if not isinstance(quality_config, dict):
         return True
-    value = inject_config.get("compress")
+    value = quality_config.get("compress")
     if value is False:
         return False
     return True
@@ -918,12 +702,8 @@ def resolve_compress(inject_config: dict) -> bool:
 def resolve_session_id(hook_data: dict) -> str:
     """Derive a session id consistent across PreToolUse / UserPromptSubmit hooks.
 
-    Prefer the session_id Claude Code / Codex pass in the hook payload so all
-    hooks within one session share the same id (fix #10 — previously
-    cf_inject_hook used PID while cf_codex_user_prompt_hook used the hook-
-    provided id, causing .inject-state dedup to break and specs to be
-    re-injected). Falls back to the current PID when the hook runtime omits
-    the field (older Codex versions, unit tests).
+    Prefer the platform-provided id so prompt, edit, feedback, and stop events
+    share one trace. Fall back to the PID for older runtimes and unit tests.
     """
     if isinstance(hook_data, dict):
         sid = hook_data.get("session_id")

package/src/core/code-flow/scripts/cf_log.py

@@ -27,6 +27,14 @@ KNOWN_EVENTS = (
     "false_positive",
     "degrade",
     "stop_check",
+    "spec_candidate",
+    "spec_bound",
+    "spec_applied",
+    "spec_read",
+    "spec_drift",
+    "spec_gate",
+    "late_violation",
+    "metrics_degraded",
 )
 
 

package/src/core/code-flow/scripts/cf_post_hook.py

@@ -32,13 +32,12 @@ from cf_core import (
     _log,
     build_effective_mapping,
     ensure_utf8_io,
-    extract_context_tags,
-    fallback_domains_for_context,
     is_code_file,
     load_config,
     match_domains,
     normalize_path,
     normalize_spec_entry,
+    resolve_enforcement,
     resolve_quality_loop,
     resolve_session_id,
 )
@@ -111,6 +110,8 @@ def main() -> None:
         config = load_config(project_root)
         if not config:
             return
+        if resolve_enforcement(config) == "inject":
+            return
         quality_loop = resolve_quality_loop(config)
         if not quality_loop["post_check"]:
             return
@@ -119,18 +120,14 @@ def main() -> None:
         if not os.path.isabs(abs_path):
             abs_path = os.path.join(project_root, file_path)
         rel_path = normalize_path(os.path.relpath(abs_path, project_root))
-        if not is_code_file(rel_path, config.get("inject") or {}):
-            return
-
         sid = resolve_session_id(data)
+        cf_log.append_event(project_root, "edit", {"file": rel_path, "tool": tool_name}, sid)
+        if not is_code_file(rel_path, config.get("quality_loop") or {}):
+            return
         mapping = build_effective_mapping(
             project_root, config.get("path_mapping") or {}
         )
         domains = match_domains(rel_path, mapping)
-        if not domains:
-            domains = sorted(fallback_domains_for_context(
-                mapping, extract_context_tags(rel_path)
-            ))
         if not domains:
             return
 

package/src/core/code-flow/scripts/cf_pre_tool_hook.py

@@ -0,0 +1,88 @@
+#!/usr/bin/env python3
+"""PreToolUse hook: advisory Context/scope guidance on Edit/Write/MultiEdit.
+
+Hot-path policy: never deny the tool; inject context or guidance instead.
+Hard enforcement lives at the checkpoints (start / done / stop), not here.
+"""
+
+import json
+import os
+from pathlib import Path
+import sys
+
+import cf_log
+from cf_core import _log, ensure_utf8_io, load_config, normalize_path, resolve_enforcement, resolve_session_id
+from cf_session_state import load_session_state, save_session_state
+from cf_spec_context import load_active_task, load_context
+from cf_spec_resolver import resolve_candidates
+from cf_spec_router import RouterError, route_prompt
+
+_WARN_TEXT = "⚠ Spec Workflow 校验未通过（warn 模式）：{message} — 建议运行 cf-spec doctor 检查。"
+
+
+def _active_expansion(root: str, relative: str) -> tuple[str, ...]:
+    marker = Path(root) / ".code-flow/.active-task.json"
+    if not marker.exists():
+        return ()
+    active = load_active_task(root)
+    context = load_context(str(Path(root) / active.task_dir / "spec-context.yml"))
+    bound = {item.spec_id for item in context.bindings}
+    return tuple(
+        item.spec_id for item in resolve_candidates(root, "code", (relative,))
+        if item.spec_id not in bound and item.metadata.enforcement == "required"
+    )
+
+
+def _inject(text: str) -> dict[str, object]:
+    return {"hookSpecificOutput": {"hookEventName": "PreToolUse", "additionalContext": text}}
+
+
+def main() -> None:
+    try:
+        ensure_utf8_io()
+        raw = sys.stdin.read()
+        if not raw.strip():
+            return
+        data = json.loads(raw)
+        tool_name = data.get("tool_name", "")
+        file_path = (data.get("tool_input") or {}).get("file_path", "")
+        if tool_name not in {"Edit", "Write", "MultiEdit"} or not isinstance(file_path, str) or not file_path:
+            return
+        root = os.getcwd()
+        sid = resolve_session_id(data)
+        config = load_config(root)
+        enforcement = resolve_enforcement(config) if config else "required"
+        absolute = file_path if os.path.isabs(file_path) else os.path.join(root, file_path)
+        relative = normalize_path(os.path.relpath(absolute, root))
+        try:
+            expanded = _active_expansion(root, relative)
+            result = route_prompt(root, (relative,), sid)
+        except RouterError as exc:
+            if enforcement == "required":
+                sys.stdout.write(json.dumps(_inject(f"SPEC_WORKFLOW_BLOCKED [{exc.code}]: {exc}. Run cf-spec doctor before continuing."), ensure_ascii=False))
+            elif enforcement == "warn":
+                sys.stdout.write(json.dumps(_inject(_WARN_TEXT.format(message=str(exc))), ensure_ascii=False))
+            return
+        if expanded:
+            message = f"⚠ 该路径引入未绑定 required Spec：{', '.join(expanded)} — 建议先 refresh Context / Plan 再继续编辑。"
+            sys.stdout.write(json.dumps(_inject(message), ensure_ascii=False))
+            return
+        text = result.text
+        if result.mode == "task" and result.context_sha256:
+            # The projection is already in context from the prompt route unless
+            # the bound rules changed; skip per-edit re-injection.
+            state = load_session_state(root)
+            if state.get("injected_sha256") == result.context_sha256:
+                text = ""
+            else:
+                state["injected_sha256"] = result.context_sha256
+                save_session_state(root, state)
+        if text:
+            sys.stdout.write(json.dumps(_inject(text), ensure_ascii=False))
+        cf_log.append_event(root, "edit_intent", {"file": relative, "tool": tool_name, "specs": list(result.specs)}, sid)
+    except (json.JSONDecodeError, OSError, ValueError) as exc:
+        _log(f"cf_pre_tool_hook error: {exc}")
+
+
+if __name__ == "__main__":
+    main()

package/src/core/code-flow/scripts/cf_session_state.py

@@ -0,0 +1,37 @@
+#!/usr/bin/env python3
+"""Shared per-session state for injection/reminder cadence.
+
+Stores one JSON file per project root (`.code-flow/.session-state.json`),
+keyed by session id. Both read and write are best-effort: a corrupt or
+unwritable state degrades to no-op rather than breaking hook protocols.
+"""
+
+import json
+import os
+from pathlib import Path
+from typing import Mapping
+
+
+_STATE_PATH = ".code-flow/.session-state.json"
+
+
+def load_session_state(root: str) -> dict:
+    """Return the persisted state dict; {} on any failure (never raises)."""
+    try:
+        value = json.loads((Path(root) / _STATE_PATH).read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError, UnicodeError):
+        return {}
+    return value if isinstance(value, dict) else {}
+
+
+def save_session_state(root: str, state: Mapping) -> bool:
+    """Atomically persist state; False on failure (never raises)."""
+    path = Path(root) / _STATE_PATH
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        temporary = path.with_name(f".{path.name}.{os.getpid()}.tmp")
+        temporary.write_text(json.dumps(dict(state), ensure_ascii=False), encoding="utf-8")
+        os.replace(temporary, path)
+        return True
+    except (OSError, UnicodeError, TypeError):
+        return False