@michaelxwb/code-flow 0.8.1 → 1.0.0

package/src/core/code-flow/scripts/codeflow/core/cf_markdown.py

@@ -1,77 +0,0 @@
-"""Shared Markdown primitives: frontmatter splitting and pipe-table headers.
-
-Pure parsing only — no I/O, no schema knowledge. Feature modules keep their own
-field aliases and value semantics.
-"""
-
-from __future__ import annotations
-
-import re
-from typing import Mapping, Optional, Sequence
-
-
-_FRONTMATTER_RE = re.compile(r"\A---[ \t]*\n(.*?)\n---[ \t]*\n?", re.DOTALL)
-_SEPARATOR_CELL_RE = re.compile(r"^:?-{2,}:?$")
-
-
-def parse_frontmatter(text: str) -> tuple[Mapping[str, object], str]:
-    """Split optional frontmatter into flat metadata + body.
-
-    Parses only flat `key: value` string pairs — enough for `description:` —
-    so the hook hot path never needs pyyaml for this. Content without
-    frontmatter returns ({}, text) unchanged.
-    """
-    if not isinstance(text, str):
-        return {}, text
-    match = _FRONTMATTER_RE.match(text)
-    if match is None:
-        return {}, text
-    meta: dict[str, object] = {}
-    for line in match.group(1).splitlines():
-        key, sep, value = line.partition(":")
-        if not sep:
-            continue
-        key = key.strip()
-        if key:
-            meta[key] = value.strip().strip('"').strip("'")
-    return meta, text[match.end():]
-
-
-def frontmatter_block(text: str) -> Optional[str]:
-    """Return the raw frontmatter text (no delimiters), or None when absent."""
-    if not isinstance(text, str):
-        return None
-    match = _FRONTMATTER_RE.match(text)
-    return match.group(1) if match else None
-
-
-def table_cells(line: str) -> tuple[str, ...]:
-    """Split one pipe-table line into trimmed cells; () for non-table lines."""
-    stripped = line.strip()
-    if not stripped.startswith("|"):
-        return ()
-    return tuple(cell.strip() for cell in stripped.strip("|").split("|"))
-
-
-def is_separator_row(cells: Sequence[str]) -> bool:
-    """True for the `|---|:--:|` alignment row."""
-    return bool(cells) and all(_SEPARATOR_CELL_RE.match(cell.replace(" ", "")) for cell in cells)
-
-
-def table_columns(lines: Sequence[str]) -> Mapping[str, int]:
-    """Map header names to column offsets; {} when no header row exists."""
-    for line in lines:
-        cells = table_cells(line)
-        if not cells or is_separator_row(cells):
-            continue
-        return {cell: index for index, cell in enumerate(cells)}
-    return {}
-
-
-def column_index(header: Sequence[str], *names: str) -> int:
-    """Lowest header index containing any alias (case-insensitive), else -1."""
-    for index, cell in enumerate(header):
-        lowered = cell.lower()
-        if any(name.lower() in lowered for name in names):
-            return index
-    return -1

package/src/core/code-flow/scripts/codeflow/core/cf_native_paths.py

@@ -1,26 +0,0 @@
-"""Native runtime project discovery and all-or-nothing path validation."""
-import os
-from pathlib import Path
-from codeflow.core.cf_patch import FileOperation
-
-
-def project_root(cwd: str) -> str:
-    directory = Path(cwd).absolute()
-    for candidate in (directory, *directory.parents):
-        if (candidate / ".code-flow/config.yml").is_file():
-            return str(candidate)
-    return ""
-
-
-def validated_paths(root: str, cwd: str, operations: tuple[FileOperation, ...]) -> tuple[tuple[str, bool], ...]:
-    paths: dict[str, bool] = {}
-    for operation in operations:
-        for path, deleted in ((operation.path, operation.kind in {"delete", "move"}),
-                              (operation.destination, False)):
-            if not path:
-                continue
-            absolute = Path(os.path.abspath(os.path.join(cwd, path)))
-            if not absolute.is_relative_to(Path(root)) or not absolute.resolve().is_relative_to(Path(root).resolve()):
-                raise ValueError(f"patch path is outside project: {path}")
-            paths[str(absolute)] = deleted
-    return tuple(paths.items())

package/src/core/code-flow/scripts/codeflow/core/cf_patch.py

@@ -1,33 +0,0 @@
-"""Shared structured patch parser for native platform entries."""
-from dataclasses import dataclass, replace
-
-
-@dataclass(frozen=True)
-class FileOperation:
-    kind: str
-    path: str
-    destination: str = ""
-
-
-def parse_patch(command: str) -> tuple[FileOperation, ...]:
-    lines = command.splitlines()
-    if len(lines) < 3 or lines[0] != "*** Begin Patch" or lines[-1] != "*** End Patch":
-        raise ValueError("patch must contain a complete Begin/End envelope")
-    operations: list[FileOperation] = []
-    headers = {"*** Add File: ": "add", "*** Update File: ": "update", "*** Delete File: ": "delete"}
-    for line in lines[1:-1]:
-        header = next((prefix for prefix in headers if line.startswith(prefix)), "")
-        if header:
-            path = line[len(header):]
-            if not path or "\x00" in path:
-                raise ValueError("patch file path is empty or invalid")
-            operations.append(FileOperation(headers[header], path))
-        elif line.startswith("*** Move to: "):
-            if not operations or operations[-1].kind != "update" or not line[13:]:
-                raise ValueError("Move to must follow an Update File")
-            operations[-1] = replace(operations[-1], kind="move", destination=line[13:])
-        elif not operations or (line and not line.startswith(("+", "-", " ", "@@", "*** End of File"))):
-            raise ValueError("unrecognized patch syntax")
-    if not operations:
-        raise ValueError("patch contains no file operations")
-    return tuple(operations)

package/src/core/code-flow/scripts/codeflow/core/cf_runtime_install.py

@@ -1,32 +0,0 @@
-"""Integrity check for the installed runtime contract and managed artifacts."""
-import hashlib
-import json
-from pathlib import Path
-
-
-def verify_install(root: str) -> None:
-    directory = Path(root)
-    if (directory / ".code-flow/.runtime-migration.lock").exists():
-        raise ValueError("runtime migration is in progress or needs recovery")
-    manifest = json.loads((directory / ".code-flow/.runtime-install.json").read_text(encoding="utf-8"))
-    version = (directory / ".code-flow/.version").read_text(encoding="utf-8").strip()
-    if manifest.get("schema_version") != 1 or manifest.get("version") != version:
-        raise ValueError("runtime installation version is inconsistent")
-    files = manifest.get("files")
-    if not isinstance(files, dict) or not files:
-        raise ValueError("runtime installation manifest has no artifacts")
-    for relative, expected in files.items():
-        path = directory / relative
-        if not path.resolve().is_relative_to(directory.resolve()):
-            raise ValueError(f"installation artifact escapes project: {relative}")
-        if hashlib.sha256(path.read_bytes()).hexdigest() != expected:
-            raise ValueError(f"managed runtime artifact has drifted: {relative}")
-    for relative, expected in manifest.get("hook_contracts", {}).items():
-        actual = json.loads((directory / relative).read_text(encoding="utf-8")).get("hooks", {})
-        for event, groups in expected.items():
-            for group in groups:
-                candidates = [item for item in actual.get(event, [])
-                              if item.get("matcher", "") == group.get("matcher", "")]
-                for hook in group["hooks"]:
-                    if not any(hook in item.get("hooks", []) for item in candidates):
-                        raise ValueError(f"managed hook has drifted: {relative}:{event}")

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

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

package/src/core/code-flow/scripts/codeflow/core/cf_stop_guard.py

@@ -1,53 +0,0 @@
-"""Nonblocking process lock for Stop gates; the OS releases abandoned locks."""
-from __future__ import annotations
-
-from contextlib import contextmanager
-import json
-import os
-from pathlib import Path
-from typing import IO, Iterator
-
-
-class StopAlreadyRunning(ValueError):
-    pass
-
-
-def _lock(handle: IO[str]) -> None:
-    if os.name == "nt":
-        import msvcrt
-        handle.seek(0)
-        msvcrt.locking(handle.fileno(), msvcrt.LK_NBLCK, 1)
-    else:
-        import fcntl
-        fcntl.flock(handle.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
-
-
-def _unlock(handle: IO[str]) -> None:
-    if os.name == "nt":
-        import msvcrt
-        handle.seek(0)
-        msvcrt.locking(handle.fileno(), msvcrt.LK_UNLCK, 1)
-    else:
-        import fcntl
-        fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
-
-
-@contextmanager
-def stop_guard(root: str, sid: str) -> Iterator[None]:
-    path = Path(root) / ".code-flow/.stop.lock"
-    path.parent.mkdir(parents=True, exist_ok=True)
-    with path.open("a+", encoding="utf-8") as handle:
-        try:
-            _lock(handle)
-        except OSError as exc:
-            handle.seek(0)
-            owner = handle.read(512).strip() or "owner unavailable"
-            raise StopAlreadyRunning(f"stop_already_running: {owner}; 等待该进程结束后重试 Stop") from exc
-        try:
-            handle.seek(0)
-            handle.truncate()
-            json.dump({"pid": os.getpid(), "session_id": sid}, handle)
-            handle.flush()
-            yield
-        finally:
-            _unlock(handle)

package/src/core/code-flow/scripts/codeflow/core/cf_task_state.py

@@ -1,9 +0,0 @@
-"""Shared lifecycle predicate without loading the workflow runtime.
-
-0.8 adds an explicit provisional state: a TASK whose required code checks were
-not actually executed must never look finished. Keep the finished set narrow so
-dependency resolution, parallel collect and archive cannot treat provisional
-work as complete.
-"""
-
-FINISHED_STATUSES = ("done", "verified")

package/src/core/code-flow/scripts/codeflow/core/cf_validators.py

@@ -1,408 +0,0 @@
-#!/usr/bin/env python3
-"""Validator engine: parse validation.yml, match triggers, execute commands.
-
-L1 domain module. It owns the single interpretation of `.code-flow/validation.yml`
-(four states: missing / empty / valid / parse_error), trigger matching,
-deadline-bound execution, and the content-fingerprint result cache. Consumers:
-`cf_validation` (validate), `cf_task_runtime` (finish), `cf_stop_hook` (Stop),
-and `cf_task_workflow` (layer counts). Dependencies stay in L0/L1: `cf_core`,
-`cf_exec_base`, and `cf_log`.
-"""
-
-from __future__ import annotations
-
-from dataclasses import dataclass, replace
-from datetime import datetime, timezone
-import fnmatch
-import hashlib
-import json
-import math
-import os
-from pathlib import Path
-import re
-import time
-from typing import Mapping, NamedTuple, Optional, Sequence
-
-from codeflow.core import cf_log
-from codeflow.core.cf_core import normalize_path
-from codeflow.core.cf_exec_base import (build_argv, record_report, redact_sensitive_text, report_requested,
-                                        remaining_seconds, run_command, worktree_fingerprint)
-
-MISSING = "missing"
-EMPTY = "empty"
-VALID = "valid"
-PARSE_ERROR = "parse_error"
-
-VALIDATION_CACHE_FILE = ".validation-cache.json"
-MAX_VALIDATION_CACHE_ENTRIES = 256
-_BRACE_RE = re.compile(r"\{([^{}]+)\}")
-
-
-@dataclass(frozen=True)
-class ValidatorConfig:
-    """Single interpretation of .code-flow/validation.yml."""
-
-    state: str
-    validators: tuple[Mapping[str, object], ...] = ()
-    error: str = ""
-    path: str = ""
-
-    def without_heavy(self) -> "ValidatorConfig":
-        """Return a config with only lightweight validators (Stop policy)."""
-        return replace(self, validators=tuple(item for item in self.validators if not is_heavy(item)))
-
-
-class ValidatorRun(NamedTuple):
-    failures: list[dict[str, object]]
-    truncated: bool
-    reused: int
-
-
-def expand_braces(pattern: str) -> list:
-    """Expand one level of `{a,b}` alternation → list of fnmatch patterns."""
-    match = _BRACE_RE.search(pattern)
-    if not match:
-        return [pattern]
-    head, tail = pattern[: match.start()], pattern[match.end():]
-    out = []
-    for option in match.group(1).split(","):
-        out.extend(expand_braces(head + option + tail))
-    return out
-
-
-def trigger_matches(trigger: str, rel_path: str) -> bool:
-    """fnmatch with brace expansion; `**/` prefix also matches root files."""
-    rel_path = normalize_path(rel_path)
-    for pattern in expand_braces(trigger or ""):
-        candidates = [pattern]
-        if pattern.startswith("**/"):
-            candidates.append(pattern[3:])
-        if any(fnmatch.fnmatch(rel_path, candidate) for candidate in candidates):
-            return True
-    return False
-
-
-def _parse_error(path: str, message: str) -> ValidatorConfig:
-    cf_log.warn(f"{path}: {message}")
-    return ValidatorConfig(PARSE_ERROR, error=message, path=path)
-
-
-def _classify(path: str, data: object) -> ValidatorConfig:
-    if data is None or data == {}:
-        return ValidatorConfig(EMPTY, path=path)
-    if not isinstance(data, dict):
-        return _parse_error(path, "validation.yml must be a YAML mapping")
-    validators = data.get("validators")
-    if validators is None or validators == []:
-        return ValidatorConfig(EMPTY, path=path)
-    if not isinstance(validators, list):
-        return _parse_error(path, "validators must be a list")
-    for index, item in enumerate(validators, 1):
-        if not isinstance(item, Mapping):
-            return _parse_error(path, f"validator #{index} must be a mapping")
-    return ValidatorConfig(VALID, tuple(validators), path=path)
-
-
-def load_validators(project_root: str) -> ValidatorConfig:
-    """Read validation.yml into one of four explicit states (API-01)."""
-    path = os.path.join(project_root, ".code-flow", "validation.yml")
-    if not os.path.exists(path):
-        return ValidatorConfig(MISSING, path=path)
-    try:
-        import yaml
-    except ImportError as exc:
-        return _parse_error(path, f"PyYAML unavailable: {exc}")
-    try:
-        with open(path, "r", encoding="utf-8") as file:
-            data = yaml.safe_load(file)
-    except (OSError, UnicodeError, yaml.YAMLError) as exc:
-        return _parse_error(path, str(exc))
-    return _classify(path, data)
-
-
-def package_script_validators(project_root: str) -> tuple[Mapping[str, object], ...]:
-    """Existing product policy for a missing/empty validation.yml."""
-    package = Path(project_root) / "package.json"
-    if not package.is_file():
-        return ()
-    data = json.loads(package.read_text(encoding="utf-8"))
-    scripts = data.get("scripts", {}) if isinstance(data, dict) else {}
-    if not isinstance(scripts, dict):
-        raise ValueError("invalid package scripts")
-    return tuple(
-        {"name": name, "trigger": "*", "command": f"npm run {name}", "timeout": 60000}
-        for name in ("test", "lint") if isinstance(scripts.get(name), str)
-    )
-
-
-def resolve_validators(
-    project_root: str,
-) -> tuple[ValidatorConfig, tuple[Mapping[str, object], ...]]:
-    """Config state plus the effective validators for this project.
-
-    missing/empty keep the product policy (package.json test/lint fallback);
-    parse_error returns no validators so callers must fail closed on state.
-    """
-    config = load_validators(project_root)
-    if config.state == VALID:
-        return config, config.validators
-    if config.state == PARSE_ERROR:
-        return config, ()
-    return config, package_script_validators(project_root)
-
-
-def is_heavy(validator: object) -> bool:
-    return isinstance(validator, Mapping) and validator.get("heavy") is True
-
-
-def _validator_failure(validator: Mapping[str, object], detail: str,
-                       incomplete: bool = False) -> dict[str, object]:
-    result: dict[str, object] = {
-        "name": validator.get("name", "validator"),
-        "on_fail": validator.get("on_fail", ""),
-        "detail": detail,
-    }
-    if incomplete:
-        result["incomplete"] = True
-    return result
-
-
-def _validator_argv(root: str, validator: Mapping[str, object], matched: list,
-                    strict: bool) -> list:
-    existing = [name for name in matched if os.path.isfile(os.path.join(root, name))]
-    template = str(validator.get("command", ""))
-    if "{files}" in template and not existing:
-        return []
-    argv = build_argv(template, existing)
-    if not argv and strict:
-        raise ValueError("validator command missing")
-    return argv
-
-
-def _tool_missing(detail: str) -> bool:
-    """Recognize 'tool not installed' output so template validators (mypy, npx …)
-    do not block projects that have not installed the optional tool yet."""
-    lowered = detail.lower()
-    markers = (
-        "no module named",
-        "modulenotfounderror",
-        "command not found",
-        "is not recognized as an internal or external command",
-        "could not determine executable to run",
-        "not found in $path",
-    )
-    return any(marker in lowered for marker in markers)
-
-
-def _validator_result(root: str, validator: Mapping[str, object], argv: list, sid: str,
-                      deadline: Optional[float], strict: bool,
-                      timings: Optional[dict[str, float]] = None) -> tuple[list, bool, bool]:
-    try:
-        timeout = float(validator.get("timeout", 30000)) / 1000.0
-    except (ValueError, TypeError):
-        if strict:
-            return [_validator_failure(validator, "invalid validator timeout")], False, False
-        timeout = 30.0
-    if not math.isfinite(timeout) or timeout <= 0:
-        return [_validator_failure(validator, "invalid validator timeout")], False, False
-    outcome = run_command(argv, root, timeout, deadline)
-    if timings is not None:
-        timings["execution_ms"] += float(outcome.get("execution_ms", 0))
-    reused = bool(outcome.get("execution_reused"))
-    passed = outcome["status"] == "ok" and outcome["returncode"] == 0
-    if outcome["status"] == "deadline_exceeded":
-        return [_validator_failure(validator, "预算耗尽未执行", True)], True, reused
-    timed_out = outcome["status"] == "timeout"
-    detail = (f"超时（>{timeout:.0f}s），未完成" if timed_out else
-              (str(outcome.get("stdout", "")) + str(outcome.get("stderr", ""))).strip()[-400:])
-    if outcome["status"] == "spawn_error":
-        if validator.get("skip_if_missing") is True:
-            cf_log.degrade(root, "stop_check", f"{validator.get('name')}:tool_missing", sid)
-            return [], False, reused
-        cf_log.degrade(root, "stop_check", f"{validator.get('name')}:{outcome['stderr']}", sid)
-        if not strict:
-            return [], False, reused
-    elif not passed and not timed_out and validator.get("skip_if_missing") is True and _tool_missing(detail):
-        cf_log.degrade(root, "stop_check", f"{validator.get('name')}:tool_missing", sid)
-        return [], False, reused
-    cf_log.append_event(root, "stop_check",
-                        {"trigger": validator.get("trigger", ""),
-                         "cmd": Path(argv[0]).name, "passed": passed}, sid)
-    return ([] if passed else [_validator_failure(validator, redact_sensitive_text(detail))]), timed_out, reused
-
-
-def _tree_fingerprint(project_root: str, validators: Sequence[object]) -> str:
-    """工作树内容指纹（内容寻址，忽略 .code-flow），与提交状态无关。
-
-    已提交内容取 blob SHA，未提交/未跟踪内容用工作区文件哈希补齐；未跟踪文件
-    只纳入命中任一 validator trigger 的路径（构建/测试产物不使缓存失效）。
-    同一内容在提交前后得到相同指纹；返回 "" 表示无法判定（禁用缓存）。
-    """
-    triggers = [str(item.get("trigger", "")) for item in validators if isinstance(item, Mapping)]
-    if triggers:
-        untracked_filter = lambda path: any(trigger_matches(trigger, path) for trigger in triggers)
-    else:
-        untracked_filter = None
-    return worktree_fingerprint(project_root, untracked_filter)
-
-
-def _validation_cache_path(project_root: str) -> Path:
-    return Path(project_root) / ".code-flow" / VALIDATION_CACHE_FILE
-
-
-def _load_validation_cache(project_root: str) -> dict:
-    try:
-        data = json.loads(_validation_cache_path(project_root).read_text(encoding="utf-8"))
-    except (OSError, ValueError):
-        return {}
-    return data if isinstance(data, dict) else {}
-
-
-def _save_validation_cache(project_root: str, cache: dict) -> None:
-    if len(cache) > MAX_VALIDATION_CACHE_ENTRIES:
-        ordered = sorted(
-            cache.items(),
-            key=lambda item: str(item[1].get("at", "")) if isinstance(item[1], dict) else "",
-        )
-        cache = dict(ordered[-MAX_VALIDATION_CACHE_ENTRIES:])
-    try:
-        path = _validation_cache_path(project_root)
-        path.parent.mkdir(parents=True, exist_ok=True)
-        path.write_text(json.dumps(cache, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
-    except OSError:
-        return  # 缓存写入失败不影响验证结论
-
-
-def _cache_key(argv: Sequence[str]) -> str:
-    return hashlib.sha256(json.dumps({"argv": list(argv)}, ensure_ascii=False).encode()).hexdigest()
-
-
-_CACHE_ENV_KEYS = frozenset({
-    "DATABASE_URL", "REDIS_URL", "INTERNAL_SERVICE_TOKEN", "ENV", "LOG_DIR", "LOG_LEVEL",
-    "ARTIFACT_ROOT", "SKILL_CACHE_ROOT", "MIGRATIONS_DIR", "DEFAULT_TENANT_ID", "HOME",
-    "TMPDIR", "PYTHONPATH", "PYTHONHASHSEED", "LANG", "LC_ALL", "LC_CTYPE", "TZ", "CI",
-})
-
-_CACHE_ENV_PREFIXES = (
-    "MUAD_", "DATABASE_", "REDIS_", "POSTGRES", "INTERNAL_", "ARTIFACT_", "SKILL_",
-    "MODEL_", "CAPACITY_", "WECOM_", "CHANNEL_", "GATEWAY_", "RUNTIME_", "WORKER_",
-)
-
-
-def _execution_environment() -> dict[str, str]:
-    """Stable, test-relevant environment fingerprint.
-
-    Shell/terminal bookkeeping (SHLVL, PATH, UV_*, PWD, ...) differs between a
-    direct invocation and the `bash -lc` wrapper used by spec verifiers without
-    changing test inputs, so only known test-relevant keys/prefixes participate.
-    """
-    return {
-        key: value for key, value in os.environ.items()
-        if key in _CACHE_ENV_KEYS or key.startswith(_CACHE_ENV_PREFIXES)
-    }
-
-
-def _execution_observation(root: str, validator: Mapping[str, object], argv: Sequence[str],
-                           fingerprint: str, entry: object) -> dict[str, str]:
-    """Describe this execution without exposing commands or environment values."""
-    payload = {"argv": list(argv), "cwd": str(Path(root).resolve()), "validator": dict(validator),
-               "environment": _execution_environment(), "input_fingerprint": fingerprint}
-    identity = hashlib.sha256(json.dumps(payload, sort_keys=True, ensure_ascii=False,
-                                        default=str).encode()).hexdigest()
-    prior = entry.get("fingerprint") if isinstance(entry, dict) else None
-    previous_identity = entry.get("execution_identity") if isinstance(entry, dict) else None
-    category = ("unproven" if not fingerprint else "no_baseline" if prior is None else
-                "worktree_changed" if prior != fingerprint else
-                "execution_context_changed" if previous_identity != identity else "unchanged")
-    return {"identity": identity, "input_change_category": category}
-
-
-def _run_one(project_root: str, validator: object, files: Sequence[str], sid: str,
-             deadline: Optional[float], strict: bool, fingerprint: str,
-             cache_data: dict, dirty: list[bool], timings: Optional[dict[str, float]] = None,
-             observations: Optional[list[dict[str, str]]] = None) -> ValidatorRun:
-    if not isinstance(validator, Mapping):
-        failures = [_validator_failure({}, "invalid validator record")] if strict else []
-        return ValidatorRun(failures, False, 0)
-    matched = [path for path in files if trigger_matches(validator.get("trigger", ""), path)]
-    if not matched:
-        return ValidatorRun([], False, 0)
-    remaining = remaining_seconds(deadline)
-    if remaining is not None and remaining <= 0:
-        return ValidatorRun([_validator_failure(validator, "预算耗尽未执行", True)], True, 0)
-    try:
-        argv = _validator_argv(project_root, validator, matched, strict)
-    except ValueError as exc:
-        return ValidatorRun([_validator_failure(validator, f"validator 配置错误: {exc}")], False, 0)
-    if not argv:
-        return ValidatorRun([], False, 0)
-    key = _cache_key(argv)
-    entry = cache_data.get(key)
-    observation = _execution_observation(project_root, validator, argv, fingerprint, entry)
-    if observations is not None:
-        observations.append(observation)
-    if fingerprint:
-        if (isinstance(entry, dict) and entry.get("fingerprint") == fingerprint
-                and entry.get("execution_identity") == observation["identity"]):
-            return ValidatorRun([], False, 1)
-    errors, incomplete, reused = _validator_result(project_root, validator, argv, sid, deadline, strict, timings)
-    if fingerprint and not errors and not incomplete:
-        cache_data[key] = {
-            "fingerprint": fingerprint,
-            "at": datetime.now(timezone.utc).isoformat(),
-        }
-        cache_data[key]["execution_identity"] = observation["identity"]
-        dirty[0] = True
-    return ValidatorRun(errors, incomplete, int(reused))
-
-
-def run_validators(
-    project_root: str,
-    config: ValidatorConfig,
-    files: Sequence[str],
-    sid: str,
-    deadline: Optional[float] = None,
-    *,
-    strict: bool = False,
-    cache: bool = True,
-    timings: Optional[dict[str, float]] = None,
-    observations: Optional[list[dict[str, str]]] = None,
-) -> ValidatorRun:
-    """Match validators, execute argv under one deadline, report unrun work.
-
-    `cache` reuses passing results when the worktree content fingerprint and
-    argv are unchanged (failures are never cached). Returns (failures,
-    truncated, reused).
-    """
-    validators = list(config.validators)
-    if report_requested():
-        if timings is None:
-            timings = {"planning_ms": 0.0, "preflight_ms": 0.0, "execution_ms": 0.0, "evidence_ms": 0.0}
-        if observations is None:
-            observations = []
-    started = time.monotonic()
-    fingerprint = _tree_fingerprint(project_root, validators) if cache and validators else ""
-    cache_data = _load_validation_cache(project_root) if fingerprint else {}
-    if timings is not None:
-        timings["preflight_ms"] += (time.monotonic() - started) * 1000
-    dirty = [False]
-    failures: list[dict[str, object]] = []
-    truncated = False
-    reused = 0
-    for validator in validators:
-        outcome = _run_one(project_root, validator, files, sid, deadline, strict,
-                           fingerprint, cache_data, dirty, timings, observations)
-        failures.extend(outcome.failures)
-        truncated = truncated or outcome.truncated
-        reused += outcome.reused
-    if dirty[0]:
-        started = time.monotonic()
-        _save_validation_cache(project_root, cache_data)
-        if timings is not None:
-            timings["evidence_ms"] += (time.monotonic() - started) * 1000
-    if report_requested():
-        record_report({"kind": "validators", "scope": {"files": list(files)}, "timings": dict(timings or {}),
-                       "execution_identities": [item["identity"] for item in observations or []],
-                       "input_change_category": [item["input_change_category"] for item in observations or []],
-                       "reused": reused, "selected": len(observations or [])})
-    return ValidatorRun(failures, truncated, reused)