@michaelxwb/code-flow 0.5.1

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

@@ -0,0 +1,56 @@
+#!/usr/bin/env python3
+"""cf_feedback: mark a check as false positive (FEAT-02 对话即反馈).
+
+The violation feedback text tells the user "误报可直接告诉我"; the agent then
+runs this CLI on the user's behalf — no new slash command, no config editing.
+
+Usage: python3 cf_feedback.py ignore <check-id>
+Exit codes: 0 = recorded / 1 = usage error / 2 = unknown check id.
+stdout: one JSON line {"check_id", "fp_count", "hit_count", "disabled"}.
+"""
+import json
+import os
+import sys
+
+from cf_checks import load_check_state, load_spec_checks, record_false_positive
+from cf_core import build_effective_mapping, load_config, normalize_spec_entry
+from cf_log import append_event
+
+
+def known_check_ids(project_root: str) -> set:
+    """All check ids: declared in any configured spec, or already in state."""
+    ids = set(load_check_state(project_root).keys())
+    config = load_config(project_root)
+    mapping = build_effective_mapping(
+        project_root, (config or {}).get("path_mapping") or {}
+    )
+    specs_root = os.path.join(project_root, ".code-flow", "specs")
+    for domain_cfg in mapping.values():
+        for entry in (domain_cfg or {}).get("specs") or []:
+            rel = normalize_spec_entry(entry).get("path")
+            if not rel:
+                continue
+            checks, _ = load_spec_checks(os.path.join(specs_root, rel))
+            ids.update(check["id"] for check in checks)
+    return ids
+
+
+def main(argv: list) -> int:
+    if len(argv) != 2 or argv[0] != "ignore":
+        sys.stderr.write("usage: cf_feedback.py ignore <check-id>\n")
+        return 1
+    check_id = argv[1]
+    project_root = os.getcwd()
+    if check_id not in known_check_ids(project_root):
+        sys.stderr.write(f"unknown check id: {check_id}\n")
+        return 2
+    append_event(
+        project_root, "false_positive", {"check_id": check_id}, "cf-feedback"
+    )
+    result = record_false_positive(project_root, check_id)
+    sys.stdout.write(json.dumps(result, ensure_ascii=False) + "\n")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

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

@@ -0,0 +1,178 @@
+#!/usr/bin/env python3
+import json
+import os
+import sys
+
+import cf_log
+from cf_core import (
+    _log,
+    assemble_context,
+    build_effective_mapping,
+    debug_log,
+    ensure_utf8_io,
+    extract_context_tags,
+    fallback_domains_for_context,
+    is_code_file,
+    load_config,
+    load_inject_state,
+    match_domains,
+    match_specs_by_tags,
+    read_matched_specs,
+    resolve_compress,
+    resolve_quality_loop,
+    resolve_session_id,
+    save_inject_state,
+    select_specs_tiered,
+)
+
+
+
+
+
+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", "")
+        tool_input = data.get("tool_input") or {}
+        file_path = tool_input.get("file_path", "")
+        if tool_name not in {"Edit", "Write", "MultiEdit"}:
+            return
+        if not isinstance(file_path, str) or not file_path:
+            return
+
+        project_root = os.getcwd()
+        abs_path = file_path
+        if not os.path.isabs(abs_path):
+            abs_path = os.path.join(project_root, file_path)
+        rel_path = os.path.relpath(abs_path, project_root)
+
+        config = load_config(project_root)
+        if not config:
+            return
+        inject_config = config.get("inject") or {}
+        if inject_config.get("auto") is False:
+            return
+        if not is_code_file(rel_path, inject_config):
+            return
+        compress_enabled = resolve_compress(inject_config)
+
+        mapping = config.get("path_mapping") or {}
+        effective_mapping = build_effective_mapping(project_root, mapping)
+        domains = match_domains(rel_path, effective_mapping)
+
+        sid = resolve_session_id(data)
+
+        # Quality-loop instrumentation (FEAT-00): every code-file edit is an
+        # event — correction pairing and stop-check need them even when no
+        # spec matches below. append_event never raises (hot path safe).
+        quality_loop = resolve_quality_loop(config)
+        if quality_loop["enabled"]:
+            cf_log.append_event(
+                project_root, "edit",
+                {"file": rel_path.replace(os.sep, "/"), "tool": tool_name},
+                sid,
+            )
+
+        # Extract context tags from file path
+        context_tags = extract_context_tags(rel_path)
+        if not domains:
+            domains = sorted(fallback_domains_for_context(effective_mapping, context_tags))
+            if not domains:
+                return
+
+        # Budget config
+        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
+
+        # Strict tag-based matching per domain. No bulk-load fallback: when a
+        # Tier 1 spec's tags don't intersect context_tags, the spec is NOT
+        # injected. Tier 0 (_map.md) uses the "*" wildcard so it still reaches
+        # the model as navigation. Re-inject every call (session dedup removed).
+        all_matched = []
+        for domain in domains:
+            domain_cfg = effective_mapping.get(domain) or {}
+            specs_config = domain_cfg.get("specs") or []
+            matched, _ = match_specs_by_tags(specs_config, context_tags)
+            if matched:
+                specs = read_matched_specs(
+                    project_root, domain, matched, compress=compress_enabled
+                )
+                all_matched.extend(specs)
+
+        if not all_matched:
+            return
+
+        selected = select_specs_tiered(all_matched, l1_budget, map_max)
+        if not selected:
+            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 [])
+        else:
+            injected_specs = set()
+
+        # Update state with newly injected spec paths. Preserve
+        # UserPromptSubmit-owned fields (prompt_count / prompt_inject_window)
+        # verbatim so cross-hook writes don't reset the dedup window.
+        new_injected = injected_specs | {s["path"] for s in selected}
+        debug_log(f"inject_hook injected={[s['path'] for s in selected]} path={rel_path}", project_root)
+        new_state = {
+            "session_id": sid,
+            "injected_specs": sorted(new_injected),
+            "last_file": abs_path,
+        }
+        if same_session:
+            if "prompt_count" in state:
+                new_state["prompt_count"] = state["prompt_count"]
+            if "prompt_inject_window" in state:
+                new_state["prompt_inject_window"] = state["prompt_inject_window"]
+        save_inject_state(project_root, new_state)
+
+        if quality_loop["enabled"]:
+            cf_log.append_event(
+                project_root, "inject",
+                {"specs": [s["path"] for s in selected],
+                 "mode": "full", "source": "pretooluse"},
+                sid,
+            )
+
+        payload = {
+            "hookSpecificOutput": {
+                "hookEventName": "PreToolUse",
+                "additionalContext": assemble_context(
+                    selected, "## Active Specs (auto-injected)"
+                ),
+            }
+        }
+        if os.environ.get("CF_DEBUG") == "1":
+            payload["debug"] = {
+                "target": abs_path,
+                "domains": sorted(domains),
+                "context_tags": sorted(context_tags),
+                "matched_specs": [s["path"] for s in selected],
+            }
+        sys.stdout.write(json.dumps(payload, ensure_ascii=False))
+    except Exception as exc:
+        # Fix #9: log errors to stderr instead of silently swallowing
+        _log(f"cf_inject_hook error: {exc}")
+        return
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,146 @@
+#!/usr/bin/env python3
+"""Session activity log: JSONL event stream for the quality-loop feature.
+
+Design contract (spec-quality-loop.design.md §3.3):
+- One event per line: {"v", "ts", "sid", "event", "data"}.
+- append is O(1) single-write; failures are swallowed (stderr only) so the
+  hook protocol is never broken by logging (RULE-01 / E-03).
+- Reads are line-tolerant: corrupt lines are skipped, never raised (RULE-05).
+- Rotation: when the live file reaches MAX_BYTES it is archived to
+  sessions/YYYY-MM/session-log-<ts>.jsonl and a fresh file starts (B-02).
+"""
+import json
+import os
+import sys
+from datetime import datetime, timedelta
+
+LOG_NAME = ".session-log.jsonl"
+SESSIONS_DIR = "sessions"
+MAX_BYTES = 5 * 1024 * 1024
+SCHEMA_VERSION = 1
+
+KNOWN_EVENTS = (
+    "inject",
+    "edit",
+    "violation",
+    "correction",
+    "false_positive",
+    "degrade",
+    "stop_check",
+)
+
+
+def _log(msg: str) -> None:
+    sys.stderr.write(f"[cf-log] {msg}\n")
+
+
+def log_path(project_root: str) -> str:
+    return os.path.join(project_root, ".code-flow", LOG_NAME)
+
+
+def _archive_dir(project_root: str, month: str) -> str:
+    return os.path.join(project_root, ".code-flow", SESSIONS_DIR, month)
+
+
+def _rotate_if_needed(project_root: str, path: str) -> None:
+    try:
+        if os.path.getsize(path) < MAX_BYTES:
+            return
+    except OSError:
+        return
+    now = datetime.now()
+    month_dir = _archive_dir(project_root, now.strftime("%Y-%m"))
+    os.makedirs(month_dir, exist_ok=True)
+    target = os.path.join(
+        month_dir, f"session-log-{now.strftime('%Y%m%dT%H%M%S')}.jsonl"
+    )
+    os.replace(path, target)
+
+
+def append_event(project_root: str, event: str, data: dict, sid: str) -> bool:
+    """Append one event line. Never raises; returns False on failure (E-03)."""
+    try:
+        path = log_path(project_root)
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        _rotate_if_needed(project_root, path)
+        line = json.dumps(
+            {
+                "v": SCHEMA_VERSION,
+                "ts": datetime.now().isoformat(timespec="seconds"),
+                "sid": sid,
+                "event": event,
+                "data": data or {},
+            },
+            ensure_ascii=False,
+        )
+        with open(path, "a", encoding="utf-8") as f:
+            f.write(line + "\n")
+        return True
+    except Exception as exc:
+        _log(f"append_event failed: {exc}")
+        return False
+
+
+def degrade(project_root: str, component: str, error: object, sid: str = "") -> None:
+    """Record a degrade event (FEAT-02). Never raises — degrading the
+    degrade-logger itself must stay invisible (RULE-01)."""
+    append_event(
+        project_root,
+        "degrade",
+        {"component": component, "error": str(error)[:200]},
+        sid,
+    )
+
+
+def _candidate_files(project_root: str, days: int) -> list:
+    """Live log + archived months overlapping the [now-days, now] window."""
+    paths = []
+    base = os.path.join(project_root, ".code-flow", SESSIONS_DIR)
+    if os.path.isdir(base):
+        cutoff = datetime.now() - timedelta(days=days)
+        for month in sorted(os.listdir(base)):
+            try:
+                month_start = datetime.strptime(month, "%Y-%m")
+            except ValueError:
+                continue
+            # keep a month if any part of it can fall inside the window
+            if month_start >= cutoff.replace(day=1):
+                month_dir = os.path.join(base, month)
+                paths.extend(
+                    os.path.join(month_dir, name)
+                    for name in sorted(os.listdir(month_dir))
+                    if name.endswith(".jsonl")
+                )
+    live = log_path(project_root)
+    if os.path.exists(live):
+        paths.append(live)
+    return paths
+
+
+def read_events(project_root: str, days: int = 30, events: tuple = ()) -> list:
+    """Read events within the window, oldest first. Corrupt lines skipped."""
+    cutoff = (datetime.now() - timedelta(days=days)).isoformat(timespec="seconds")
+    wanted = set(events) if events else None
+    out = []
+    for path in _candidate_files(project_root, days):
+        try:
+            with open(path, "r", encoding="utf-8") as f:
+                for raw in f:
+                    raw = raw.strip()
+                    if not raw:
+                        continue
+                    try:
+                        item = json.loads(raw)
+                    except Exception:
+                        continue
+                    if not isinstance(item, dict) or "event" not in item:
+                        continue
+                    if wanted is not None and item["event"] not in wanted:
+                        continue
+                    if str(item.get("ts", "")) < cutoff:
+                        continue
+                    out.append(item)
+        except Exception as exc:
+            _log(f"read_events skipped {path}: {exc}")
+            continue
+    return out

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

@@ -0,0 +1,196 @@
+#!/usr/bin/env python3
+"""PostToolUse Hook: compliance feedback after Edit/Write (FEAT-01).
+
+Flow (spec-quality-loop.design.md §3.4):
+  edited file → matched domains → aggregate frontmatter checks of their
+  constraint specs → run against on-disk content → feedback via
+  additionalContext (advice only, never blocking) → violation events.
+
+Protocol invariants (RULE-01/02):
+  - always exit 0, stdout is JSON-only or empty (no-op);
+  - violations only warn — there is no error severity;
+  - same check+file reported once per session (RISK-05);
+  - any internal failure degrades silently (stderr + degrade event).
+
+Input (stdin): {"tool_name", "tool_input": {"file_path"}, "session_id"}
+Output: {"hookSpecificOutput": {"hookEventName": "PostToolUse",
+         "additionalContext": "..."}} or empty.
+"""
+import json
+import os
+import sys
+
+import cf_log
+from cf_checks import (
+    load_check_state,
+    load_spec_checks,
+    record_hits,
+    run_checks,
+    save_check_state,
+)
+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_quality_loop,
+    resolve_session_id,
+)
+
+FEEDBACK_HINT = '如认为误报，直接告诉我"这是误报"，我会标记忽略。'
+_REPORTED_KEY = "_reported"
+
+
+def _collect_checks(project_root: str, domains: list, mapping: dict) -> list:
+    """Aggregate checks of all constraint specs in matched domains.
+
+    Each check is annotated with its source spec path. Checks apply whenever
+    their own `files` glob matches — independent of injection tag gating.
+    """
+    specs_root = os.path.join(project_root, ".code-flow", "specs")
+    collected = []
+    seen_specs = set()
+    for domain in domains:
+        for entry in (mapping.get(domain) or {}).get("specs") or []:
+            cfg = normalize_spec_entry(entry)
+            rel = cfg.get("path")
+            if not rel or rel in seen_specs or not cfg.get("tags"):
+                continue
+            seen_specs.add(rel)
+            checks, _ = load_spec_checks(os.path.join(specs_root, rel))
+            for check in checks:
+                item = dict(check)
+                item["spec"] = rel
+                collected.append(item)
+    return collected
+
+
+def _session_reported(state: dict, sid: str) -> set:
+    session = state.get(_REPORTED_KEY) or {}
+    if session.get("sid") != sid:
+        return set()
+    return set(session.get("keys") or [])
+
+
+def _save_reported(project_root: str, state: dict, sid: str, keys: set) -> None:
+    state[_REPORTED_KEY] = {"sid": sid, "keys": sorted(keys)}
+    save_check_state(project_root, state)
+
+
+def _feedback_text(violations: list) -> str:
+    lines = ["## Spec 合规反馈 (auto-check)", ""]
+    for v in violations:
+        lines.append(f"⚠ {v['message']}（规则: {v['spec']}#{v['check_id']}）")
+        lines.append(f"  违规行 {v['line_no']}: {v['line']}")
+    lines.append("")
+    lines.append("请修正以上违规后再继续。" + FEEDBACK_HINT)
+    return "\n".join(lines)
+
+
+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"}:
+            return
+        if not isinstance(file_path, str) or not file_path:
+            return
+
+        project_root = os.getcwd()
+        config = load_config(project_root)
+        if not config:
+            return
+        quality_loop = resolve_quality_loop(config)
+        if not quality_loop["post_check"]:
+            return
+
+        abs_path = file_path
+        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)
+        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
+
+        checks = _collect_checks(project_root, domains, mapping)
+        if not checks:
+            return
+
+        try:
+            with open(abs_path, "r", encoding="utf-8") as f:
+                content = f.read()
+        except Exception:
+            return
+
+        state = load_check_state(project_root)
+        violations, skipped = run_checks(checks, rel_path, content, state)
+        for item in skipped:
+            cf_log.degrade(
+                project_root, "post_check",
+                f"{item['check_id']}:{item['reason']}", sid,
+            )
+        if not violations:
+            return
+
+        spec_by_check = {c["id"]: c["spec"] for c in checks}
+        reported = _session_reported(state, sid)
+        fresh = []
+        for v in violations:
+            key = f"{v['check_id']}|{v['file']}"
+            if key in reported:
+                continue
+            v["spec"] = spec_by_check.get(v["check_id"], "")
+            fresh.append(v)
+            reported.add(key)
+        if not fresh:
+            return
+
+        # hit_count feeds the false-positive rate denominator (RULE-04)
+        record_hits(project_root, sorted({v["check_id"] for v in fresh}))
+        state = load_check_state(project_root)
+        _save_reported(project_root, state, sid, reported)
+
+        for v in fresh:
+            cf_log.append_event(
+                project_root, "violation",
+                {"check_id": v["check_id"], "spec": v["spec"],
+                 "file": v["file"], "severity": v["severity"]},
+                sid,
+            )
+
+        payload = {
+            "hookSpecificOutput": {
+                "hookEventName": "PostToolUse",
+                "additionalContext": _feedback_text(fresh),
+            }
+        }
+        sys.stdout.write(json.dumps(payload, ensure_ascii=False))
+    except Exception as exc:
+        _log(f"cf_post_hook error: {exc}")
+        return
+
+
+if __name__ == "__main__":
+    main()