@michaelxwb/code-flow 0.6.5 → 1.0.0

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

@@ -1,112 +0,0 @@
-#!/usr/bin/env python3
-"""Shared execution substrate: deadline-aware argv subprocess runner.
-
-All check executors (acceptance scenarios, Spec verifiers, session
-validators) funnel through here so one entry deadline constrains the whole
-chain, commands never pass through a shell, and unrun work is reported as
-`incomplete` instead of silently skipped or falsely passed.
-"""
-
-from __future__ import annotations
-
-import shlex
-import json
-import subprocess
-import time
-from contextlib import contextmanager
-from contextvars import ContextVar
-from pathlib import Path
-from typing import Iterator, Mapping, Optional, Sequence
-
-_EXECUTIONS: ContextVar[Optional[dict[str, dict[str, object]]]] = ContextVar("cf_executions", default=None)
-
-
-@contextmanager
-def execution_session() -> Iterator[None]:
-    """Share results only inside one validation operation, never across turns."""
-    if _EXECUTIONS.get() is not None:
-        yield
-        return
-    token = _EXECUTIONS.set({})
-    try:
-        yield
-    finally:
-        _EXECUTIONS.reset(token)
-
-
-def invalidate_executions() -> None:
-    cache = _EXECUTIONS.get()
-    if cache is not None:
-        cache.clear()
-
-
-def execution_key(argv: Sequence[str], cwd: str, timeout: float) -> str:
-    """Identity of a command under the current process environment."""
-    return json.dumps([list(argv), str(Path(cwd).resolve()), float(timeout)], ensure_ascii=False)
-
-
-def remaining_seconds(deadline: Optional[float]) -> Optional[float]:
-    """Seconds left until the absolute monotonic deadline (None = unbounded)."""
-    if deadline is None:
-        return None
-    return deadline - time.monotonic()
-
-
-def build_argv(template: str, files: Sequence[str]) -> list[str]:
-    """Expand a validator command template into argv without a shell.
-
-    `{files}` must be a standalone token and expands to one argv entry per
-    file (spaces/metachars safe). Embedded usage is a config error — refusing
-    is safer than reintroducing shell splitting.
-    """
-    tokens = shlex.split(template or "")
-    if not tokens:
-        return []
-    argv: list[str] = []
-    for token in tokens:
-        if token == "{files}":
-            argv.extend(files)
-        elif "{files}" in token:
-            raise ValueError(f"validator command must keep {{files}} as a standalone token: {template!r}")
-        else:
-            argv.append(token)
-    return argv
-
-
-def run_command(
-    argv: Sequence[str],
-    cwd: str,
-    timeout: float,
-    deadline: Optional[float] = None,
-) -> dict[str, object]:
-    """Run argv synchronously under timeout+deadline. Never uses a shell."""
-    key = execution_key(argv, cwd, timeout)
-    cache = _EXECUTIONS.get()
-    if cache is not None and key in cache:
-        return dict(cache[key])
-    result = _execute(argv, cwd, timeout, deadline)
-    if cache is not None and result["status"] == "ok":
-        cache[key] = result
-    return result
-
-
-def _execute(argv: Sequence[str], cwd: str, timeout: float, deadline: Optional[float]) -> dict[str, object]:
-    remaining = remaining_seconds(deadline)
-    if remaining is not None and remaining <= 0:
-        return {"status": "deadline_exceeded", "returncode": None, "stdout": "", "stderr": ""}
-    effective = min(timeout, remaining) if remaining is not None else timeout
-    try:
-        proc = subprocess.run(
-            list(argv), cwd=cwd, capture_output=True, text=True, timeout=max(effective, 0.01)
-        )
-    except subprocess.TimeoutExpired as exc:
-        out = exc.stdout
-        return {
-            "status": "timeout",
-            "returncode": None,
-            "stdout": (out.decode() if isinstance(out, bytes) else (out or ""))[-4000:],
-            "stderr": "",
-        }
-    except OSError as exc:
-        return {"status": "spawn_error", "returncode": None, "stdout": "", "stderr": str(exc)}
-    return {"status": "ok", "returncode": proc.returncode, "stdout": proc.stdout or "", "stderr": proc.stderr or ""}

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

@@ -1,56 +0,0 @@
-#!/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_log.py

@@ -1,154 +0,0 @@
-#!/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",
-    "spec_candidate",
-    "spec_bound",
-    "spec_applied",
-    "spec_read",
-    "spec_drift",
-    "spec_gate",
-    "late_violation",
-    "metrics_degraded",
-)
-
-
-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

@@ -1,196 +0,0 @@
-#!/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,
-    effective_project_root,
-    ensure_utf8_io,
-    is_code_file,
-    load_config,
-    match_domains,
-    normalize_path,
-    normalize_spec_entry,
-    resolve_enforcement,
-    resolve_quality_loop,
-    resolve_session_id,
-    timing_log,
-)
-
-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
-
-        session_root = os.getcwd()
-        abs_path = file_path if os.path.isabs(file_path) else os.path.join(session_root, file_path)
-        # 并行子 agent 在 .code-flow/worktrees/... 内编辑时路由到该 worktree 的规格与状态
-        project_root = effective_project_root(session_root, abs_path)
-        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
-
-        rel_path = normalize_path(os.path.relpath(abs_path, project_root))
-        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:
-            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()
-    timing_log("cf_post_hook")

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

@@ -1,104 +0,0 @@
-#!/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,
-    effective_project_root,
-    ensure_utf8_io,
-    load_config,
-    normalize_path,
-    resolve_enforcement,
-    resolve_session_id,
-    timing_log,
-)
-from cf_session_state import load_session_state, save_session_state
-from cf_spec_context import injection_version, load_active_task, load_context
-from cf_spec_resolver import resolve_candidate_headers
-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_candidate_headers(root, "code", (relative,))
-        if item.spec_id not in bound and item.enforcement == "required"
-        and getattr(item, "scope", "path") != "unmatched"
-    )
-
-
-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
-        session_root = os.getcwd()
-        absolute = file_path if os.path.isabs(file_path) else os.path.join(session_root, file_path)
-        # 并行子 agent 在 .code-flow/worktrees/... 内编辑时路由到该 worktree 的上下文
-        root = effective_project_root(session_root, absolute)
-        sid = resolve_session_id(data)
-        config = load_config(root)
-        enforcement = resolve_enforcement(config) if config else "required"
-        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 session/task/contract version changed; skip per-edit
-            # re-injection. Same version key as the prompt hook so a TASK
-            # switch re-injects here too.
-            state = load_session_state(root)
-            version = injection_version(root, sid, result.context_sha256)
-            if state.get("injected_version") == version:
-                text = ""
-            else:
-                state["injected_version"] = version
-                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()
-    timing_log("cf_pre_tool_hook")