@michaelxwb/code-flow 0.5.2 → 0.6.0

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

@@ -1,157 +1,49 @@
 #!/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_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_session_id,
-    save_inject_state,
-    select_specs_tiered,
-)
+from cf_checks import detect_correction
+from cf_core import _log, ensure_utf8_io, normalize_path, resolve_quality_loop, resolve_session_id, load_config
+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)$')
 
 
-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).
-
-    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)
-        return
-
-    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
-
-    try:
-        dedup_window = int(inject_config.get("dedup_window", 5))
-    except (ValueError, TypeError):
-        dedup_window = 5
+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
 
-    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,
-        )
+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
-
-    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))
+    correction = detect_correction(prompt)
+    if correction:
+        cf_log.append_event(root, "correction", {"phrase": correction["phrase"], "prompt_head": prompt[:200], "files": paths}, sid)
 
 
 def main() -> None:
@@ -164,238 +56,20 @@ 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,
-            )
-            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)
-            return
-
-        selected = select_specs_tiered(all_matched, l1_budget, map_max)
-        if not selected:
+        paths = extract_paths_from_prompt(prompt)
+        _record_correction(root, prompt, paths, sid)
+        result = route_prompt(root, paths, sid)
+        if not result.text:
             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:
+        cf_log.append_event(root, "inject", {"specs": list(result.specs), "mode": result.mode, "source": result.mode}, sid)
+        sys.stdout.write(json.dumps(_payload(result.text, result.mode), ensure_ascii=False))
+    except RouterError as exc:
+        message = f"SPEC_WORKFLOW_BLOCKED [{exc.code}]: {exc}. Run cf-spec doctor before continuing."
+        sys.stdout.write(json.dumps(_payload(message, "blocked"), 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")`，必须保留原始错误与上下文

package/src/core/code-flow/specs/backend/platform-rules.md

@@ -1,5 +1,14 @@
 ---
+id: backend-platform-rules
 description: 涉及 API 设计/部署/配置/版本兼容时适用：平台规则
+stages: [design, plan, code, review]
+enforcement: required
+verifiers:
+  - rule: RULE-backend-platform-001
+    type: manual
+    config:
+      checklist: Confirm all Guidance and Avoid items for this Spec.
+      owner: project-owner
 ---
 
 # Backend Platform Rules
@@ -20,6 +29,9 @@ return {"code": 1, "message": "order not found", "data": None}
 ```
 
 ## Rules
+- [RULE-backend-platform-001] The implementation must satisfy every applicable item in Guidance and avoid every item in Avoid.
+
+## Guidance
 - API 变更必须保持向后兼容；破坏性变更走新版本路径（`/v2/...`）并保留旧版本至少一个发布周期
 - 配置项分环境管理（dev / staging / prod），敏感值走密钥管理服务，禁止入库
 - 新增外部依赖必须更新部署文档与 `requirements` / `package.json` 锁文件
@@ -35,7 +47,7 @@ return {"code": 1, "message": "order not found", "data": None}
 - 健康检查端点（`/healthz`、`/readyz`）必须独立于业务认证
 - 部署前跑 smoke test，覆盖核心路径
 
-## Anti-Patterns
+## Avoid
 - 禁止在生产环境开启 `DEBUG` / 详细堆栈输出
 - 禁止把 secret 写进代码库或 dev 配置文件
 - 禁止破坏性 API 变更不通知调用方直接发布

package/src/core/code-flow/specs/frontend/component-specs.md

@@ -1,5 +1,14 @@
 ---
+id: frontend-component-specs
 description: 写/改组件时适用：props、hooks、渲染、UI 样式约束
+stages: [design, plan, code, review]
+enforcement: required
+verifiers:
+  - rule: RULE-frontend-component-001
+    type: manual
+    config:
+      checklist: Confirm all Guidance and Avoid items for this Spec.
+      owner: project-owner
 ---
 
 # Component Specs
@@ -36,6 +45,9 @@ const OrderRow = ({ id }) => {
 ```
 
 ## Rules
+- [RULE-frontend-component-001] The implementation must satisfy every applicable item in Guidance and avoid every item in Avoid.
+
+## Guidance
 - Props 必须类型化（TS interface / PropTypes / defineProps），可选项给默认值
 - 组件文件名与导出组件名一致，使用 PascalCase
 - 单组件文件 ≤ 300 行，超出拆成子组件或提取 hook
@@ -49,7 +61,7 @@ const OrderRow = ({ id }) => {
 - 受控表单优先；非受控仅用于不需要回读值的场景
 - 样式遵循设计系统：间距用 4 的倍数，强调色 ≤ 2 种
 
-## Anti-Patterns
+## Avoid
 - 禁止在组件内直接修改 props 或 store 内部状态
 - 禁止把大量逻辑塞进 JSX 表达式，复杂条件提取变量或子组件
 - 禁止用 `index` 作为列表 `key`（顺序变更会触发错误复用）

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

@@ -1,5 +1,14 @@
 ---
+id: frontend-directory-structure
 description: 新建/移动前端文件时适用：目录结构、路由/页面/组件存放约束
+stages: [design, plan, code, review]
+enforcement: required
+verifiers:
+  - rule: RULE-frontend-directory-001
+    type: manual
+    config:
+      checklist: Confirm all Guidance and Avoid items for this Spec.
+      owner: project-owner
 ---
 
 # Frontend Directory Structure
@@ -24,6 +33,9 @@ const order = await fetch(`/orders/${id}`).then((r) => r.json());
 ```
 
 ## Rules
+- [RULE-frontend-directory-001] The implementation must satisfy every applicable item in Guidance and avoid every item in Avoid.
+
+## Guidance
 - 通用组件放 `src/components/`，页面级组件放 `src/pages/`，业务复用逻辑放 `src/hooks/`（或 `composables/`）
 - **接口调用独立成层**：API 调用必须在 `src/services/` 封装；组件 / hook / composable 经 service 消费，**禁止组件或视图层内裸 `fetch` / `axios`**
 - 类型定义放 `src/types/`（共享）或与组件同目录（局部），禁止散落
@@ -35,7 +47,7 @@ const order = await fetch(`/orders/${id}`).then((r) => r.json());
 - 资源文件（图片 / 字体）放 `src/assets/`，构建工具处理 hash 与压缩
 - 测试文件与源码同目录（`Foo.test.tsx`）或镜像放 `tests/`
 
-## Anti-Patterns
+## Avoid
 - 禁止在 `src/` 下随意新增未登记的一级目录
 - 禁止页面与组件互相循环引用
 - 禁止把仅本组件用的 hook / 类型上提到全局目录