@michaelxwb/code-flow 0.5.2 → 0.6.1

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

@@ -1,157 +1,108 @@
 #!/usr/bin/env python3
-"""Unified UserPromptSubmit Hook: inject matching specs into context.
+"""UserPromptSubmit hook for the Context-first three-branch router."""
 
-This hook works for both Claude Code and Codex adapters. It extracts:
-1. File paths from the prompt (for context_tags)
-2. Keywords from the prompt (for prompt_tags via extract_prompt_tags)
-
-Both tag sets are used to match specs for injection.
-
-Input (stdin): {"prompt": "...", "session_id": "..."}
-Output (stdout): {"hookSpecificOutput": {"hookEventName": "UserPromptSubmit", "additionalContext": "..."}}
-or empty on no-op
-"""
 import json
 import os
 import re
 import sys
+
 import cf_log
+from cf_checks import detect_correction
 from cf_core import (
     _log,
-    assemble_context,
-    build_effective_mapping,
-    build_spec_catalog,
-    resolve_quality_loop,
-    debug_log,
     ensure_utf8_io,
-    estimate_tokens,
-    extract_context_tags,
-    extract_prompt_tags,
-    fallback_domains_for_context,
     load_config,
-    load_inject_state,
-    match_domains,
-    match_specs_by_tags,
     normalize_path,
-    read_matched_specs,
-    resolve_compress,
-    resolve_inject_mode,
+    resolve_enforcement,
+    resolve_quality_loop,
     resolve_session_id,
-    save_inject_state,
-    select_specs_tiered,
 )
+from cf_session_state import load_session_state, save_session_state
+from cf_spec_router import RouterError, route_prompt
 
-# Pseudo spec-path key used in prompt_inject_window to dedup catalog emission.
-_CATALOG_KEY = "__catalog__"
 
-# Match bare paths, @-prefixed paths, and backtick-quoted paths.
-# Right boundary uses an ASCII-only negative lookahead instead of \b. Python's
-# \b is Unicode-aware on every platform, so "src/cli.js中" never terminated
-# the match — common Chinese phrasing dropped real paths. The explicit ASCII
-# class is locale- and OS-independent, so Windows/macOS/Linux behave the same.
-# Character class includes `\` so Windows-style paths (`src\cli.js`) pasted
-# from Explorer also match; `normalize_path()` downstream converts to `/`.
 _PATH_RE = re.compile(r'[@`]?([a-zA-Z0-9_.][a-zA-Z0-9_./\\\-]*\.[a-zA-Z]{1,6})(?![a-zA-Z0-9_])')
 _EXT_RE = re.compile(r'\.(py|js|ts|go|rs|java|rb|cs|cpp|c|h)$')
 
+_COMPRESS_INTERVAL = 25
+_REINJECT_INTERVAL = 25
+_REMINDER_TEXT = (
+    "⚠ 本会话已处理较多轮次，上下文较长；批量任务建议在任务间压缩上下文，或拆到新会话继续。"
+)
+_WARN_TEXT = "⚠ Spec Workflow 校验未通过（warn 模式）：{message} — 建议运行 cf-spec doctor 检查。"
+
 
-def extract_paths_from_prompt(prompt: str) -> list:
-    """Extract candidate file paths referenced in prompt text."""
+def extract_paths_from_prompt(prompt: str) -> list[str]:
+    """Extract explicit file paths without semantic keyword inference."""
     paths = []
     seen = set()
-    for m in _PATH_RE.finditer(prompt):
-        candidate = normalize_path(m.group(1).lstrip('@`'))
-        # Require at least one slash or a meaningful extension to reduce noise
-        if candidate in seen:
-            continue
-        if '/' in candidate or _EXT_RE.search(candidate):
+    for match in _PATH_RE.finditer(prompt):
+        candidate = normalize_path(match.group(1).lstrip('@`'))
+        if candidate not in seen and ('/' in candidate or _EXT_RE.search(candidate)):
             paths.append(candidate)
             seen.add(candidate)
     return paths
 
 
-def _emit_catalog(
-    project_root: str,
-    sid: str,
-    inject_config: dict,
-    budget_cfg: dict,
-    effective_mapping: dict,
-    quality_loop: dict = None,
-) -> None:
-    """Inject the compact spec catalog (inject.mode=catalog, no path evidence).
+def _payload(text: str, mode: str) -> dict[str, object]:
+    payload: dict[str, object] = {
+        "hookSpecificOutput": {"hookEventName": "UserPromptSubmit", "additionalContext": text}
+    }
+    if os.environ.get("CF_DEBUG") == "1":
+        payload["debug"] = {"mode": mode}
+    return payload
 
-    The model does the semantic spec selection itself by reading the catalog;
-    dedup reuses prompt_inject_window under the pseudo key _CATALOG_KEY so the
-    catalog re-surfaces after dedup_window prompts (auto-compaction recovery).
-    """
-    try:
-        catalog_max = int(budget_cfg.get("catalog_max", 200))
-    except (ValueError, TypeError):
-        catalog_max = 200
-    catalog = build_spec_catalog(project_root, effective_mapping, catalog_max)
-    if not catalog:
-        debug_log(f"user_prompt_hook catalog_empty session={sid}", project_root)
+
+def _record_correction(root: str, prompt: str, paths: list[str], sid: str) -> None:
+    config = load_config(root)
+    if not config or not resolve_quality_loop(config)["correction_capture"]:
         return
+    correction = detect_correction(prompt)
+    if correction:
+        cf_log.append_event(root, "correction", {"phrase": correction["phrase"], "prompt_head": prompt[:200], "files": paths}, sid)
 
-    state = load_inject_state(project_root)
-    same_session = state.get("session_id") == sid
-    if same_session:
-        injected_specs = set(state.get("injected_specs") or [])
-        prompt_window = dict(state.get("prompt_inject_window") or {})
-        prompt_count = int(state.get("prompt_count") or 0) + 1
-    else:
-        injected_specs = set()
-        prompt_window = {}
-        prompt_count = 1
 
+def _session_reminder(root: str, sid: str) -> str:
+    """One-line context-compress nudge once per COMPRESS_INTERVAL prompts per session.
+
+    Gated by quality_loop.compress_reminder; disabled → zero IO. Never raises: a
+    corrupt state file degrades to no reminder rather than breaking the hook.
+    """
+    config = load_config(root)
+    if not config or not resolve_quality_loop(config)["compress_reminder"]:
+        return ""
+    state = load_session_state(root)
     try:
-        dedup_window = int(inject_config.get("dedup_window", 5))
+        if state.get("session_id") != sid:
+            state = {"session_id": sid, "prompt_count": 0, "next_remind_at": _COMPRESS_INTERVAL}
+        state["prompt_count"] = int(state.get("prompt_count", 0)) + 1
+        reminder = ""
+        if state["prompt_count"] >= int(state.get("next_remind_at", _COMPRESS_INTERVAL)):
+            reminder = _REMINDER_TEXT
+            state["next_remind_at"] = int(state["next_remind_at"]) + _COMPRESS_INTERVAL
     except (ValueError, TypeError):
-        dedup_window = 5
+        return ""
+    save_session_state(root, state)
+    return reminder
 
-    last = prompt_window.get(_CATALOG_KEY)
-    emit = (
-        dedup_window <= 0
-        or last is None
-        or prompt_count - int(last) >= dedup_window
-    )
-    if emit:
-        prompt_window[_CATALOG_KEY] = prompt_count
-    save_inject_state(project_root, {
-        "session_id": sid,
-        "injected_specs": sorted(injected_specs),
-        "last_file": state.get("last_file", "") if same_session else "",
-        "prompt_count": prompt_count,
-        "prompt_inject_window": prompt_window,
-    })
 
-    if not emit:
-        debug_log(
-            f"user_prompt_hook catalog_deduped session={sid} prompt_count={prompt_count}",
-            project_root,
-        )
-        return
+def _route_with_enforcement(root: str, paths: list[str], sid: str, enforcement: str) -> tuple[object, object]:
+    """Route with enforcement-aware failure handling.
 
-    debug_log(
-        f"user_prompt_hook catalog_injected tokens={estimate_tokens(catalog)} "
-        f"prompt_count={prompt_count} session={sid}",
-        project_root,
-    )
-    if quality_loop and quality_loop.get("enabled"):
-        cf_log.append_event(
-            project_root, "inject",
-            {"specs": ["__catalog__"], "mode": "catalog", "source": "catalog"},
-            sid,
-        )
-    payload = {
-        "hookSpecificOutput": {
-            "hookEventName": "UserPromptSubmit",
-            "additionalContext": catalog,
-        }
-    }
-    if os.environ.get("CF_DEBUG") == "1":
-        payload["debug"] = {"mode": "catalog", "prompt_count": prompt_count}
-    sys.stdout.write(json.dumps(payload, ensure_ascii=False))
+    required — fail closed with the SPEC_WORKFLOW_BLOCKED message;
+    warn    — degrade to a short advisory message;
+    inject  — degrade silently.
+    Returns (result, error_payload); exactly one is not None.
+    """
+    try:
+        return route_prompt(root, paths, sid), None
+    except RouterError as exc:
+        if enforcement == "required":
+            message = f"SPEC_WORKFLOW_BLOCKED [{exc.code}]: {exc}. Run cf-spec doctor before continuing."
+            return None, _payload(message, "blocked")
+        if enforcement == "warn":
+            return None, _payload(_WARN_TEXT.format(message=str(exc)), "warn")
+        return None, None
 
 
 def main() -> None:
@@ -164,238 +115,57 @@ def main() -> None:
         prompt = data.get("prompt", "")
         if not isinstance(prompt, str) or not prompt.strip():
             return
-
-        project_root = os.getcwd()
-        
-        # Resolve session_id consistently with PreToolUse hook
+        root = os.getcwd()
         sid = resolve_session_id(data)
-        debug_log(
-            f"user_prompt_hook start session={sid} "
-            f"prompt_len={len(prompt)} prompt_head={prompt[:200]!r}",
-            project_root,
-        )
-
-        config = load_config(project_root)
-        if not config:
-            debug_log(f"user_prompt_hook no_config session={sid}", project_root)
-            return
-
-        inject_config = config.get("inject") or {}
-        if inject_config.get("auto") is False:
-            return
-        compress_enabled = resolve_compress(inject_config)
-
-        mapping = config.get("path_mapping") or {}
-        effective_mapping = build_effective_mapping(project_root, mapping)
-
-        budget_cfg = config.get("budget") or {}
-        l1_budget = 1700
-        map_max = 400
-        try:
-            l1_budget = int(budget_cfg.get("l1_max", 1700))
-        except (ValueError, TypeError):
-            pass
-        try:
-            map_max = int(budget_cfg.get("map_max", 400))
-        except (ValueError, TypeError):
-            pass
-
-        # Derive context_tags from file paths mentioned in the prompt
-        candidate_paths = extract_paths_from_prompt(prompt)
-        context_tags: set = set()
-        matched_domains: set = set()
-        for cp in candidate_paths:
-            context_tags.update(extract_context_tags(cp))
-            matched_domains.update(match_domains(cp, effective_mapping))
-
-        # NEW: Extract prompt_tags from user prompt keywords
-        prompt_tags = extract_prompt_tags(prompt)
-        debug_log(f"user_prompt_hook paths={candidate_paths} context_tags={sorted(context_tags)} prompt_tags={sorted(prompt_tags)}", project_root)
-
-        # Catalog mode: prompts without explicit path evidence get the compact
-        # spec catalog and the model pulls relevant specs itself — keyword-table
-        # guessing systematically missed open vocabulary. Path-bearing prompts
-        # (matched_domains non-empty here means a prompt path hit a domain
-        # pattern) keep deterministic full injection: paths are strong evidence.
-        mode = resolve_inject_mode(inject_config)
-        quality_loop = resolve_quality_loop(config)
-
-        # FEAT-04 信号①：纠正句式 → correction 事件（仅本地，NFR-SEC-01）。
-        # 配对（信号②）由 cf-learn 离线完成，hook 热路径只记原始事件。
-        if quality_loop["correction_capture"]:
-            from cf_checks import detect_correction
-            correction = detect_correction(prompt)
-            if correction:
-                cf_log.append_event(
-                    project_root, "correction",
-                    {"phrase": correction["phrase"],
-                     "prompt_head": prompt[:200],
-                     "files": candidate_paths},
-                    sid,
-                )
-                debug_log(
-                    f"user_prompt_hook correction phrase={correction['phrase']!r}",
-                    project_root,
-                )
-
-        if mode == "catalog" and not matched_domains:
-            _emit_catalog(
-                project_root, sid, inject_config, budget_cfg,
-                effective_mapping, quality_loop,
-            )
+        config = load_config(root)
+        enforcement = resolve_enforcement(config) if config else "required"
+        paths = extract_paths_from_prompt(prompt)
+        _record_correction(root, prompt, paths, sid)
+        result, error_payload = _route_with_enforcement(root, paths, sid, enforcement)
+        if error_payload is not None:
+            sys.stdout.write(json.dumps(error_payload, ensure_ascii=False))
             return
-
-        # Fallback: unresolved domains → prefer domain-name hint in tags, then all domains
-        if not matched_domains:
-            matched_domains = fallback_domains_for_context(effective_mapping, context_tags)
-            debug_log(f"user_prompt_hook fallback_domains={sorted(matched_domains)}", project_root)
-
-        # Strict tag-based matching per domain. No bulk-load fallback: when a
-        # Tier 1 spec's tags don't intersect (context_tags ∪ prompt_tags), the
-        # spec is NOT injected. Tier 0 (_map.md) uses "*" so navigation still
-        # reaches the model. Re-inject every call (session dedup removed).
-        all_matched = []
-        for domain in matched_domains:
-            domain_cfg = effective_mapping.get(domain) or {}
-            specs_config = domain_cfg.get("specs") or []
-            matched, _ = match_specs_by_tags(specs_config, context_tags, prompt_tags)
-            if matched:
-                specs = read_matched_specs(
-                    project_root, domain, matched, compress=compress_enabled
-                )
-                all_matched.extend(specs)
-
-        if not all_matched:
-            debug_log(f"user_prompt_hook no_specs_matched session={sid}", project_root)
+        if result is None:
             return
-
-        selected = select_specs_tiered(all_matched, l1_budget, map_max)
-        if not selected:
+        reminder = ""
+        if config and resolve_quality_loop(config)["compress_reminder"]:
+            reminder = _session_reminder(root, sid)
+        text = result.text
+        if result.mode == "task" and result.context_sha256:
+            # Dedup: inject the projection once per session/context, refreshing
+            # at the compress cadence so long sessions do not re-pay 12k chars
+            # on every prompt.
+            state = load_session_state(root)
+            count = int(state.get("prompt_count", 0))
+            dirty = False
+            if not (config and resolve_quality_loop(config)["compress_reminder"]):
+                # compress_reminder off → _session_reminder never bumps the
+                # counter; maintain the cadence here so the periodic refresh
+                # still fires after compaction.
+                count += 1
+                state["prompt_count"] = count
+                dirty = True
+            injected = state.get("injected_sha256")
+            last_inject = int(state.get("last_inject_prompt", 0))
+            if injected == result.context_sha256 and count - last_inject < _REINJECT_INTERVAL:
+                text = ""
+            else:
+                state["injected_sha256"] = result.context_sha256
+                state["last_inject_prompt"] = count
+                dirty = True
+            if dirty:
+                save_session_state(root, state)
+        if not text and not reminder:
             return
-
-        # Load state with session isolation (deferred until after match success)
-        state = load_inject_state(project_root)
-        same_session = state.get("session_id") == sid
-        if same_session:
-            injected_specs = set(state.get("injected_specs") or [])
-            prompt_window = dict(state.get("prompt_inject_window") or {})
-            prompt_count = int(state.get("prompt_count") or 0) + 1
-        else:
-            injected_specs = set()
-            prompt_window = {}
-            prompt_count = 1
-
-        # TTL-window dedup: skip specs re-injected within the last N prompts in
-        # this session. dedup_window <= 0 disables dedup (every call re-injects).
-        # The window bounds — not removes — re-injection, so an auto-compaction
-        # that drops earlier context can still recover specs after N prompts.
-        try:
-            dedup_window = int(inject_config.get("dedup_window", 5))
-        except (ValueError, TypeError):
-            dedup_window = 5
-
-        if dedup_window > 0:
-            emitted = [
-                s for s in selected
-                if (s["path"] not in prompt_window)
-                or (prompt_count - int(prompt_window[s["path"]]) >= dedup_window)
-            ]
-        else:
-            emitted = list(selected)
-
-        # Compare by path so this stays correct if `emitted` is ever rebuilt
-        # from copies instead of filtered references to the same dicts.
-        emitted_paths = {s["path"] for s in emitted}
-        skipped = [s["path"] for s in selected if s["path"] not in emitted_paths]
-
-        # Catalog-mode path turns also carry the catalog (same dedup window):
-        # the path pins one domain's full specs, the catalog keeps every other
-        # spec reachable for cross-domain asks ("改 cli.js 部署 hook 脚本"
-        # would otherwise lose the scripts constraints entirely).
-        catalog_text = ""
-        if mode == "catalog":
-            last = prompt_window.get(_CATALOG_KEY)
-            catalog_due = (
-                dedup_window <= 0
-                or last is None
-                or prompt_count - int(last) >= dedup_window
-            )
-            if catalog_due:
-                try:
-                    catalog_max = int(budget_cfg.get("catalog_max", 200))
-                except (ValueError, TypeError):
-                    catalog_max = 200
-                catalog_text = build_spec_catalog(
-                    project_root, effective_mapping, catalog_max
-                )
-                if catalog_text:
-                    prompt_window[_CATALOG_KEY] = prompt_count
-
-        # Always persist prompt_count so the dedup window keeps advancing even
-        # on fully-deduped turns. Preserve PreToolUse-owned fields verbatim.
-        for s in emitted:
-            prompt_window[s["path"]] = prompt_count
-        save_inject_state(project_root, {
-            "session_id": sid,
-            "injected_specs": sorted(injected_specs | {s["path"] for s in emitted}),
-            "last_file": state.get("last_file", "") if same_session else "",
-            "prompt_count": prompt_count,
-            "prompt_inject_window": prompt_window,
-        })
-
-        if not emitted and not catalog_text:
-            debug_log(
-                f"user_prompt_hook dedup_all_skipped session={sid} "
-                f"prompt_count={prompt_count} skipped={skipped}",
-                project_root,
-            )
-            return
-
-        debug_log(
-            f"user_prompt_hook injected={[s['path'] for s in emitted]} "
-            f"skipped={skipped} catalog_appended={bool(catalog_text)} "
-            f"prompt_count={prompt_count} session={sid}",
-            project_root,
-        )
-
-        if quality_loop["enabled"]:
-            cf_log.append_event(
-                project_root, "inject",
-                {"specs": [s["path"] for s in emitted],
-                 "mode": mode, "source": "prompt",
-                 "catalog_appended": bool(catalog_text)},
-                sid,
-            )
-
-        parts = []
-        if emitted:
-            parts.append(assemble_context(emitted, "## Active Specs (auto-injected)"))
-        if catalog_text:
-            parts.append(catalog_text)
-        payload = {
-            "hookSpecificOutput": {
-                "hookEventName": "UserPromptSubmit",
-                "additionalContext": "\n\n".join(parts),
-            }
-        }
-        if os.environ.get("CF_DEBUG") == "1":
-            payload["debug"] = {
-                "mode": mode,
-                "candidate_paths": candidate_paths,
-                "domains": sorted(matched_domains),
-                "context_tags": sorted(context_tags),
-                "prompt_tags": sorted(prompt_tags),
-                "matched_specs": [s["path"] for s in emitted],
-                "deduped_specs": skipped,
-                "prompt_count": prompt_count,
-                "dedup_window": dedup_window,
-            }
-
-        sys.stdout.write(json.dumps(payload, ensure_ascii=False))
-
-    except Exception as exc:
+        if text:
+            cf_log.append_event(root, "inject", {"specs": list(result.specs), "mode": result.mode, "source": result.mode}, sid)
+        if text and reminder:
+            text = text.rstrip() + "\n\n" + reminder
+        elif reminder:
+            text = reminder
+        sys.stdout.write(json.dumps(_payload(text, result.mode if text else "reminder"), ensure_ascii=False))
+    except (json.JSONDecodeError, UnicodeError, OSError, ValueError) as exc:
         _log(f"cf_user_prompt_hook error: {exc}")
-        return
 
 
 if __name__ == "__main__":

package/src/core/code-flow/specs/backend/code-quality-performance.md

@@ -1,5 +1,14 @@
 ---
+id: backend-code-quality-performance
 description: 写后端代码时适用：错误处理、测试、超时重试、缓存等质量与性能约束
+stages: [design, plan, code, review]
+enforcement: required
+verifiers:
+  - rule: RULE-backend-quality-001
+    type: manual
+    config:
+      checklist: Confirm all Guidance and Avoid items for this Spec.
+      owner: project-owner
 ---
 
 # Backend Code Quality & Performance
@@ -29,6 +38,9 @@ except Exception:
 
 
 ## Rules
+- [RULE-backend-quality-001] The implementation must satisfy every applicable item in Guidance and avoid every item in Avoid.
+
+## Guidance
 - 所有公开函数 / 方法必须有类型注解（type hints / 类型签名）
 - 异常必须显式处理或显式上抛，禁止 `except Exception: pass` / `catch (e) {}` 静默吞掉
 - 外部依赖调用（HTTP / RPC / DB）必须设置超时，关键调用补重试 + 指数退避
@@ -40,7 +52,7 @@ except Exception:
 - 资源（连接、文件、锁）使用 `with` / `using` / `defer` 确保释放
 - 性能敏感路径加监控指标（QPS / P95 延迟 / 错误率）
 
-## Anti-Patterns
+## Avoid
 - 禁止在请求链路中吞掉异常导致客户端拿到错误结果却无日志
 - 禁止无超时的外部调用（容易导致线程 / 协程泄漏）
 - 禁止用循环模拟批量操作（DB 批量 / 网络批量必须用原生批量 API）

package/src/core/code-flow/specs/backend/database.md

@@ -1,5 +1,14 @@
 ---
+id: backend-database
 description: 涉及数据库/ORM/迁移/查询时适用：schema 与数据访问约束
+stages: [design, plan, code, review]
+enforcement: required
+verifiers:
+  - rule: RULE-backend-database-001
+    type: manual
+    config:
+      checklist: Confirm all Guidance and Avoid items for this Spec.
+      owner: project-owner
 ---
 
 # Backend Database
@@ -19,6 +28,9 @@ cur.execute(f"SELECT * FROM users WHERE email = '{email}'")
 ```
 
 ## Rules
+- [RULE-backend-database-001] The implementation must satisfy every applicable item in Guidance and avoid every item in Avoid.
+
+## Guidance
 - 所有 SQL 必须参数化，禁止字符串拼接 / 模板插值用户输入
 - 迁移脚本必须可回滚，或写成幂等脚本（`IF NOT EXISTS` / `ON CONFLICT`）
 - 事务边界明确：跨表写入必须在同一事务内，禁止"半提交"状态
@@ -32,7 +44,7 @@ cur.execute(f"SELECT * FROM users WHERE email = '{email}'")
 - 缓存与数据库一致性：先写库再失效缓存（`cache-aside`）
 - CRUD 基类统一实现 `get / list / create / update / delete / bulk_*`，子类只扩展模型特有查询
 
-## Anti-Patterns
+## Avoid
 - 禁止在事务内发起外部 HTTP / RPC 调用，超时会导致连接池耗尽
 - 禁止在循环中执行单条 `INSERT` / `UPDATE`，必须批量化
 - 禁止在 ORM 之外手写 SQL 时绕过参数绑定

package/src/core/code-flow/specs/backend/directory-structure.md

@@ -1,5 +1,14 @@
 ---
+id: backend-directory-structure
 description: 新建/移动后端文件时适用：目录结构与模块组织约束
+stages: [design, plan, code, review]
+enforcement: required
+verifiers:
+  - rule: RULE-backend-directory-001
+    type: manual
+    config:
+      checklist: Confirm all Guidance and Avoid items for this Spec.
+      owner: project-owner
 ---
 
 # Backend Directory Structure
@@ -22,6 +31,9 @@ if order.status == 1 and role == "admin":   # 魔法数字 / 魔法字符串
 ```
 
 ## Rules
+- [RULE-backend-directory-001] The implementation must satisfy every applicable item in Guidance and avoid every item in Avoid.
+
+## Guidance
 - 接口层放 `api/`，业务逻辑放 `services/`，数据模型放 `models/`，禁止跨层倒置依赖
 - 入口文件（`main.*`）只做框架装配，不写业务代码
 - 配置统一放 `config/`，禁止在业务代码中直接读 `os.environ` / `process.env`
@@ -35,7 +47,7 @@ if order.status == 1 and role == "admin":   # 魔法数字 / 魔法字符串
 - 常量命名用 UPPER_SNAKE_CASE，枚举优先使用语言原生 `Enum`
 - 测试目录与源码同构（`tests/services/order/test_*`）
 
-## Anti-Patterns
+## Avoid
 - 禁止在根目录堆放脚本与临时代码，临时脚本放 `scripts/` 并命名清晰
 - 禁止在 `models/` 里写业务逻辑，模型仅定义结构与简单关联
 - 禁止把常量直接写在业务代码里（如 `if status == 1` / `role == "admin"`），必须引用 `constants/` 中的命名常量

package/src/core/code-flow/specs/backend/logging.md

@@ -1,5 +1,14 @@
 ---
+id: backend-logging
 description: 涉及日志/调试/监控时适用：日志级别、格式、追踪约束
+stages: [design, plan, code, review]
+enforcement: required
+verifiers:
+  - rule: RULE-backend-logging-001
+    type: manual
+    config:
+      checklist: Confirm all Guidance and Avoid items for this Spec.
+      owner: project-owner
 ---
 
 # Backend Logging
@@ -21,6 +30,9 @@ logger.error("failed")                 # 丢失原始错误与上下文
 ```
 
 ## Rules
+- [RULE-backend-logging-001] The implementation must satisfy every applicable item in Guidance and avoid every item in Avoid.
+
+## Guidance
 - 关键路径（请求入口、外部调用、DB 写入、异常分支）必须输出结构化日志
 - 日志中禁止出现明文密码、token、身份证号等敏感字段，需在记录前脱敏
 - 每条请求日志必须包含 `request_id`，串联整个调用链
@@ -32,7 +44,7 @@ logger.error("failed")                 # 丢失原始错误与上下文
 - 高频路径用采样日志，避免 IO 阻塞主流程
 - 日志输出到 stdout/stderr，由部署环境采集，禁止业务代码写文件
 
-## Anti-Patterns
+## Avoid
 - 禁止在循环或热路径中无脱敏地打印请求体
 - 禁止用 `print` / `console.log` 替代日志框架
 - 禁止吞掉异常仅打 `logger.error("failed")`，必须保留原始错误与上下文