@guanlin4924/devflow-pi 0.1.0

package/plugins/devflow-core/runtime/hooks/hook_common.py

@@ -0,0 +1,696 @@
+#!/usr/bin/env python3
+"""Shared, dependency-free helpers for skill-kit lifecycle hooks."""
+
+from __future__ import annotations
+
+import fnmatch
+import hashlib
+import json
+import os
+import re
+import subprocess
+import tempfile
+import time
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any, Iterator
+
+try:
+    import fcntl
+except ImportError:  # pragma: no cover - Windows fallback
+    fcntl = None
+
+
+DEFAULT_POLICY: dict[str, Any] = {
+    "version": 1,
+    "mode": "strict",
+    "protected_roots": [],
+    "required_evidence": [
+        ".planning/rules/INDEX.md",
+        ".context/spec/index.md",
+        ".planning/navigation/INDEX.md",
+    ],
+    "optional_evidence": [".planning/code-index/INDEX.md"],
+    "allowed_before_gate": [
+        "AGENTS.md",
+        "README.md",
+        ".planning/**",
+        ".context/**",
+        ".agent-gates/**",
+        ".omp/**",
+        ".skills/**",
+    ],
+    "context_sync": {
+        "enabled": True,
+        "auto_light": True,
+        "light_timeout_seconds": 120,
+        "full_file_threshold": 30,
+        "ignore": [
+            ".planning/**",
+            ".context/**",
+            ".agent-gates/**",
+            ".omp/**",
+            ".skills/**",
+        ],
+        "medium_patterns": [
+            "**/routes.*",
+            "**/router.*",
+            "**/routes/**",
+            "**/api/**",
+            "**/*handler.*",
+            "**/controllers/**",
+            "**/migrations/**",
+            "package.json",
+            "**/package.json",
+            "go.mod",
+            "**/go.mod",
+            "Cargo.toml",
+            "**/Cargo.toml",
+            "pyproject.toml",
+            "**/pyproject.toml",
+            "Makefile",
+            "**/Makefile",
+            "**/vite.config.*",
+            "**/next.config.*",
+        ],
+        "full_patterns": [],
+    },
+}
+
+COMMON_SOURCE_ROOTS = (
+    "src",
+    "app",
+    "apps",
+    "backend",
+    "frontend",
+    "server",
+    "client",
+    "packages",
+    "cmd",
+    "internal",
+    "pkg",
+    "lib",
+)
+
+DIRECT_PATH_KEYS = {
+    "file_path",
+    "filepath",
+    "path",
+    "paths",
+    "target",
+    "targets",
+    "directory",
+    "folder",
+    "workdir",
+    "cwd",
+}
+
+MUTATION_TOOL_MARKERS = ("edit", "write", "notebookedit", "apply_patch", "applypatch")
+COMMAND_TOOL_MARKERS = ("bash", "shell", "exec_command", "execcommand", "terminal")
+READ_TOOL_MARKERS = ("read", "grep", "glob", "search", "find")
+
+
+def read_event() -> dict[str, Any]:
+    try:
+        payload = json.load(__import__("sys").stdin)
+    except (json.JSONDecodeError, OSError, TypeError):
+        return {}
+    return payload if isinstance(payload, dict) else {}
+
+
+def cli_dir_name() -> str:
+    return ".omp"
+
+
+def project_root(event: dict[str, Any] | None = None) -> Path:
+    event = event or {}
+    explicit = os.environ.get("OMP_PROJECT_DIR")
+    candidate = Path(explicit or event.get("cwd") or os.getcwd()).expanduser().resolve()
+    if candidate.is_file():
+        candidate = candidate.parent
+    for current in (candidate, *candidate.parents):
+        if any(
+            (current / marker).exists()
+            for marker in (".omp", ".agent-gates", ".planning", ".skills")
+        ):
+            return current
+    return candidate
+
+
+def skill_kit_root(root: Path) -> Path:
+    """Resolve the version-pinned skill source for submodule and marketplace installs."""
+    configured = os.environ.get("DEVFLOW_KIT_ROOT")
+    intel = os.environ.get("DEVFLOW_INTEL_SKILL_ROOT")
+    candidates = [
+        Path(intel).expanduser() if intel else None,
+        Path(configured).expanduser() if configured else None,
+        root / ".skills",
+        Path(__file__).resolve().parents[2],
+    ]
+    for candidate in candidates:
+        if candidate and (
+            (candidate / "workflow-orchestrator/scripts/inspect_state.rb").is_file()
+            or (candidate / "workflow-code-index/scripts/code_index.py").is_file()
+        ):
+            return candidate.resolve()
+    return (root / ".skills").resolve()
+
+
+def _deep_merge(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
+    result = dict(base)
+    for key, value in override.items():
+        if isinstance(value, dict) and isinstance(result.get(key), dict):
+            result[key] = _deep_merge(result[key], value)
+        else:
+            result[key] = value
+    return result
+
+
+def load_hook_config(root: Path, cli_dir: str | None = None) -> dict[str, Any]:
+    cli_dir = cli_dir or cli_dir_name()
+    path = root / cli_dir / "hook-config.json"
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (FileNotFoundError, PermissionError, json.JSONDecodeError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def load_policy(root: Path, cli_dir: str | None = None) -> dict[str, Any]:
+    config = load_hook_config(root, cli_dir)
+    policy_rel = config.get("gates", {}).get("index_first", {}).get(
+        "policy", ".agent-gates/index-first.json"
+    )
+    policy_path = root / str(policy_rel)
+    try:
+        data = json.loads(policy_path.read_text(encoding="utf-8"))
+    except (FileNotFoundError, PermissionError, json.JSONDecodeError):
+        data = {}
+    return _deep_merge(DEFAULT_POLICY, data if isinstance(data, dict) else {})
+
+
+def normalize_rel(raw: str | os.PathLike[str], root: Path) -> str | None:
+    value = str(raw).strip().strip("'\"")
+    if not value or value.startswith("-"):
+        return None
+    value = value.replace("\\", "/")
+    path = Path(value).expanduser()
+    if path.is_absolute():
+        try:
+            return path.resolve(strict=False).relative_to(root.resolve()).as_posix()
+        except ValueError:
+            return None
+    normalized = Path(os.path.normpath(value)).as_posix()
+    if normalized == ".":
+        return "."
+    if normalized == ".." or normalized.startswith("../"):
+        return None
+    return normalized.removeprefix("./")
+
+
+def _walk_path_values(value: Any, key: str = "") -> Iterator[str]:
+    if isinstance(value, dict):
+        for child_key, child_value in value.items():
+            yield from _walk_path_values(child_value, str(child_key).lower())
+    elif isinstance(value, list):
+        for item in value:
+            yield from _walk_path_values(item, key)
+    elif isinstance(value, str) and key in DIRECT_PATH_KEYS:
+        yield value
+
+
+def command_text(event: dict[str, Any]) -> str:
+    tool_input = event.get("tool_input", {})
+    if not isinstance(tool_input, dict):
+        return ""
+    for key in ("command", "cmd", "script"):
+        value = tool_input.get(key)
+        if isinstance(value, str):
+            return value
+    return ""
+
+
+def tool_name(event: dict[str, Any]) -> str:
+    return str(event.get("tool_name", "")).lower().replace("-", "_")
+
+
+def is_command_tool(event: dict[str, Any]) -> bool:
+    name = tool_name(event)
+    return any(marker in name for marker in COMMAND_TOOL_MARKERS) or bool(command_text(event))
+
+
+def is_mutation_tool(event: dict[str, Any]) -> bool:
+    name = tool_name(event)
+    return any(marker in name for marker in MUTATION_TOOL_MARKERS)
+
+
+def direct_tool_paths(event: dict[str, Any], root: Path) -> list[str]:
+    tool_input = event.get("tool_input", {})
+    values = list(_walk_path_values(tool_input))
+    name = tool_name(event)
+    if "apply_patch" in name or "applypatch" in name:
+        patch = tool_input if isinstance(tool_input, str) else ""
+        if isinstance(tool_input, dict):
+            patch = str(tool_input.get("patch") or tool_input.get("input") or "")
+        values.extend(re.findall(r"^\*\*\* (?:Add|Update|Delete) File:\s*(.+)$", patch, re.MULTILINE))
+    result = []
+    for value in values:
+        normalized = normalize_rel(value, root)
+        if normalized is not None:
+            result.append(normalized)
+    return sorted(dict.fromkeys(result))
+
+
+def path_matches(path: str, patterns: list[str]) -> bool:
+    for pattern in patterns:
+        pattern = str(pattern).removeprefix("./")
+        if fnmatch.fnmatch(path, pattern):
+            return True
+        if pattern.startswith("**/") and fnmatch.fnmatch(path, pattern[3:]):
+            return True
+        if pattern.endswith("/**") and (path == pattern[:-3] or path.startswith(pattern[:-2])):
+            return True
+    return False
+
+
+def _navigation_codebase_roots(root: Path) -> list[str]:
+    path = root / ".planning/navigation/INDEX.md"
+    try:
+        text = path.read_text(encoding="utf-8")
+    except (FileNotFoundError, PermissionError):
+        return []
+    match = re.search(r"^## Codebase Registry\s*$([\s\S]*?)(?=^## |\Z)", text, re.MULTILINE)
+    if not match:
+        return []
+    section = match.group(1)
+    roots = []
+    for line in section.splitlines():
+        if not line.startswith("|") or "`" not in line:
+            continue
+        cells = [cell.strip() for cell in line.strip().strip("|").split("|")]
+        if len(cells) < 2 or cells[0].lower() in {"name", "---"}:
+            continue
+        found = re.search(r"`([^`]+)`", cells[1])
+        if found:
+            normalized = normalize_rel(found.group(1), root)
+            if normalized not in {None, "."}:
+                roots.append(normalized)
+    return roots
+
+
+def protected_roots(root: Path, policy: dict[str, Any]) -> list[str]:
+    configured = []
+    for item in policy.get("protected_roots", []):
+        value = item.get("path") if isinstance(item, dict) else item
+        normalized = normalize_rel(str(value), root) if value else None
+        if normalized not in {None, "."}:
+            configured.append(normalized.rstrip("/"))
+    if configured:
+        return sorted(dict.fromkeys(configured))
+    discovered = _navigation_codebase_roots(root)
+    if discovered:
+        return sorted(dict.fromkeys(discovered))
+    return [name for name in COMMON_SOURCE_ROOTS if (root / name).is_dir()]
+
+
+def required_evidence(root: Path, policy: dict[str, Any]) -> list[str]:
+    result = []
+    for item in policy.get("required_evidence", []):
+        value = item.get("path") if isinstance(item, dict) else item
+        optional = bool(item.get("optional")) if isinstance(item, dict) else False
+        normalized = normalize_rel(str(value), root) if value else None
+        if normalized and ((root / normalized).is_file() or not optional):
+            if (root / normalized).is_file():
+                result.append(normalized)
+    return list(dict.fromkeys(result))
+
+
+def path_is_protected(path: str, roots: list[str], allowed: list[str]) -> bool:
+    if path_matches(path, allowed):
+        return False
+    return any(path == source_root or path.startswith(f"{source_root}/") for source_root in roots)
+
+
+def _command_mentions_allowed_scope(command: str, allowed: list[str]) -> bool:
+    simple_prefixes = [pattern[:-3] for pattern in allowed if pattern.endswith("/**")]
+    exact_paths = [pattern for pattern in allowed if not any(char in pattern for char in "*?[")]
+    candidates = simple_prefixes + exact_paths
+    return any(
+        re.search(rf"(?:^|[\s'\"]){re.escape(prefix)}(?:/|[\s'\";|&]|$)", command)
+        for prefix in candidates
+    )
+
+
+def command_touches_protected_source(
+    event: dict[str, Any], root: Path, roots: list[str], allowed: list[str]
+) -> bool:
+    command = command_text(event)
+    if not command:
+        return False
+    normalized_command = command.replace("\\", "/")
+    for source_root in roots:
+        if re.search(rf"(?:^|[\s'\"=:/]){re.escape(source_root)}(?:/|[\s'\";|&]|$)", normalized_command):
+            return True
+
+    event_cwd = normalize_rel(str(event.get("cwd") or root), root)
+    if event_cwd and any(event_cwd == item or event_cwd.startswith(f"{item}/") for item in roots):
+        return True
+
+    reader = re.search(
+        r"(?:^|[;&|]\s*|\s)(?:cat|sed|rg|grep|find|fd|awk|less|head|tail|nl|bat)\b",
+        normalized_command,
+    )
+    git_reader = re.search(r"\bgit\s+(?:diff|show|grep|blame)\b", normalized_command)
+    if not (reader or git_reader):
+        return False
+    if _command_mentions_allowed_scope(normalized_command, allowed) and not re.search(r"(?:^|\s)\.(?:\s|$)", normalized_command):
+        return False
+    return bool(roots)
+
+
+def tool_requests_protected_source(
+    event: dict[str, Any], root: Path, policy: dict[str, Any]
+) -> tuple[bool, list[str]]:
+    roots = protected_roots(root, policy)
+    allowed = [str(item) for item in policy.get("allowed_before_gate", [])]
+    blocked_paths = [
+        path for path in direct_tool_paths(event, root) if path_is_protected(path, roots, allowed)
+    ]
+    if blocked_paths:
+        return True, blocked_paths
+    if is_command_tool(event) and command_touches_protected_source(event, root, roots, allowed):
+        return True, ["<shell command>"]
+    name = tool_name(event)
+    if "agent" in name or "task" in name:
+        prompt = str(event.get("tool_input", {})).lower()
+        if re.search(r"\b(source|code|implementation|debug|review|grep|search|route|api|architecture)\b", prompt):
+            return True, ["<subagent source request>"]
+    return False, []
+
+
+def evidence_observed(event: dict[str, Any], root: Path, artifacts: list[str]) -> list[str]:
+    name = tool_name(event)
+    if not (any(marker in name for marker in READ_TOOL_MARKERS) or is_command_tool(event)):
+        return []
+    paths = set(direct_tool_paths(event, root))
+    command = command_text(event).replace("\\", "/")
+    shell_reader = bool(
+        re.search(
+            r"(?:^|[;&|]\s*|\s)(?:cat|sed|rg|grep|awk|less|head|tail|nl|bat)\b",
+            command,
+        )
+        or re.search(r"\bgit\s+(?:show|grep|blame)\b", command)
+    )
+    observed = []
+    for artifact in artifacts:
+        absolute = (root / artifact).as_posix()
+        if artifact in paths or absolute in paths:
+            observed.append(artifact)
+        elif shell_reader and command and (artifact in command or absolute in command):
+            observed.append(artifact)
+    return sorted(dict.fromkeys(observed))
+
+
+def file_fingerprint(path: Path) -> str:
+    if not path.exists() and not path.is_symlink():
+        return "<missing>"
+    if path.is_dir():
+        return "<directory>"
+    try:
+        digest = hashlib.sha256()
+        with path.open("rb") as handle:
+            for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+                digest.update(chunk)
+        return digest.hexdigest()
+    except (OSError, PermissionError):
+        return "<unreadable>"
+
+
+def _run_git(root: Path, args: list[str]) -> subprocess.CompletedProcess[bytes]:
+    return subprocess.run(
+        ["git", "-C", str(root), *args],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        check=False,
+    )
+
+
+def git_head(root: Path) -> str:
+    result = _run_git(root, ["rev-parse", "HEAD"])
+    return result.stdout.decode("utf-8", errors="replace").strip() if result.returncode == 0 else ""
+
+
+def git_status_paths(root: Path) -> dict[str, str]:
+    result = _run_git(root, ["status", "--porcelain=v1", "-z", "--untracked-files=all"])
+    if result.returncode != 0:
+        return {}
+    records = result.stdout.split(b"\0")
+    status_by_path: dict[str, str] = {}
+    index = 0
+    while index < len(records):
+        record = records[index]
+        index += 1
+        if not record or len(record) < 4:
+            continue
+        status = record[:2].decode("ascii", errors="replace")
+        raw_path = record[3:].decode("utf-8", errors="surrogateescape")
+        normalized = normalize_rel(raw_path, root)
+        if normalized:
+            status_by_path[normalized] = status
+        if "R" in status or "C" in status:
+            index += 1
+    return status_by_path
+
+
+def worktree_snapshot(root: Path) -> dict[str, str]:
+    return {path: file_fingerprint(root / path) for path in git_status_paths(root)}
+
+
+def _committed_changes(root: Path, baseline_head: str) -> set[str]:
+    current_head = git_head(root)
+    if not baseline_head or not current_head or baseline_head == current_head:
+        return set()
+    result = _run_git(root, ["diff", "--name-only", "-z", f"{baseline_head}..{current_head}"])
+    if result.returncode != 0:
+        return set()
+    paths = set()
+    for raw in result.stdout.split(b"\0"):
+        if not raw:
+            continue
+        normalized = normalize_rel(raw.decode("utf-8", errors="surrogateescape"), root)
+        if normalized:
+            paths.add(normalized)
+    return paths
+
+
+def discover_git_repos(root: Path, policy: dict[str, Any] | None = None) -> list[Path]:
+    policy = policy or DEFAULT_POLICY
+    candidates = [root]
+    candidates.extend(root / path for path in _navigation_codebase_roots(root))
+    candidates.extend(root / path for path in COMMON_SOURCE_ROOTS if (root / path).is_dir())
+    for item in policy.get("context_sync", {}).get("repositories", []):
+        normalized = normalize_rel(str(item), root)
+        if normalized:
+            candidates.append(root / normalized)
+
+    repositories: dict[str, Path] = {}
+    for candidate in candidates:
+        if not candidate.exists():
+            continue
+        result = _run_git(candidate, ["rev-parse", "--show-toplevel"])
+        if result.returncode != 0:
+            continue
+        repo = Path(result.stdout.decode("utf-8", errors="replace").strip()).resolve()
+        try:
+            repo.relative_to(root.resolve())
+        except ValueError:
+            continue
+        repositories[str(repo)] = repo
+    return sorted(repositories.values(), key=lambda path: path.as_posix())
+
+
+def _project_rel_from_repo(root: Path, repo: Path, path: str) -> str | None:
+    return normalize_rel(repo / path, root)
+
+
+def repository_snapshot(root: Path, policy: dict[str, Any]) -> dict[str, dict[str, Any]]:
+    snapshot: dict[str, dict[str, Any]] = {}
+    for repo in discover_git_repos(root, policy):
+        repo_key = normalize_rel(repo, root) or "."
+        worktree = {}
+        for path in git_status_paths(repo):
+            project_path = _project_rel_from_repo(root, repo, path)
+            if project_path:
+                worktree[project_path] = file_fingerprint(root / project_path)
+        snapshot[repo_key] = {"head": git_head(repo), "worktree": worktree}
+    return snapshot
+
+
+def _repository_changes(
+    root: Path, baseline_repos: dict[str, Any], policy: dict[str, Any]
+) -> set[str]:
+    changed: set[str] = set()
+    current_repos = {normalize_rel(repo, root) or ".": repo for repo in discover_git_repos(root, policy)}
+    for repo_key in set(baseline_repos) | set(current_repos):
+        baseline = baseline_repos.get(repo_key, {})
+        baseline = baseline if isinstance(baseline, dict) else {}
+        current_repo = current_repos.get(repo_key)
+        if current_repo is None:
+            if repo_key != ".":
+                changed.add(repo_key)
+            continue
+        current_worktree = {}
+        for path in git_status_paths(current_repo):
+            project_path = _project_rel_from_repo(root, current_repo, path)
+            if project_path:
+                current_worktree[project_path] = file_fingerprint(root / project_path)
+        baseline_worktree = baseline.get("worktree", {})
+        baseline_worktree = baseline_worktree if isinstance(baseline_worktree, dict) else {}
+        changed.update(
+            path
+            for path in set(baseline_worktree) | set(current_worktree)
+            if baseline_worktree.get(path, "<clean>") != current_worktree.get(path, "<clean>")
+        )
+        for repo_path in _committed_changes(current_repo, str(baseline.get("head") or "")):
+            project_path = _project_rel_from_repo(root, current_repo, repo_path)
+            if project_path:
+                changed.add(project_path)
+    return changed
+
+
+def _state_root(root: Path) -> Path:
+    project_id = hashlib.sha256(str(root.resolve()).encode("utf-8")).hexdigest()[:16]
+    return Path(tempfile.gettempdir()) / "skill-kit-hooks" / project_id
+
+
+def _safe_session_id(session_id: str) -> str:
+    clean = re.sub(r"[^A-Za-z0-9_.-]+", "_", session_id or "default")
+    return clean[:160] or "default"
+
+
+def state_path(root: Path, session_id: str) -> Path:
+    return _state_root(root) / f"{_safe_session_id(session_id)}.json"
+
+
+@contextmanager
+def locked_state(root: Path, session_id: str) -> Iterator[dict[str, Any]]:
+    directory = _state_root(root)
+    directory.mkdir(parents=True, exist_ok=True)
+    path = state_path(root, session_id)
+    lock_path = path.with_suffix(path.suffix + ".lock")
+    with lock_path.open("a+", encoding="utf-8") as lock:
+        if fcntl is not None:
+            fcntl.flock(lock.fileno(), fcntl.LOCK_EX)
+        try:
+            try:
+                state = json.loads(path.read_text(encoding="utf-8"))
+            except (FileNotFoundError, json.JSONDecodeError, PermissionError):
+                state = {}
+            if not isinstance(state, dict):
+                state = {}
+            yield state
+            temp_path = path.with_name(f"{path.name}.{os.getpid()}.tmp")
+            temp_path.write_text(
+                json.dumps(state, ensure_ascii=False, indent=2, sort_keys=True) + "\n",
+                encoding="utf-8",
+            )
+            os.replace(temp_path, path)
+        finally:
+            if fcntl is not None:
+                fcntl.flock(lock.fileno(), fcntl.LOCK_UN)
+
+
+def initialize_session(root: Path, event: dict[str, Any], force: bool = False) -> dict[str, Any]:
+    session_id = str(event.get("session_id") or "default")
+    source = str(event.get("source") or "startup")
+    policy = load_policy(root)
+    with locked_state(root, session_id) as state:
+        should_reset = force or not state or source in {"startup", "clear"}
+        if should_reset:
+            state.clear()
+            state.update(
+                {
+                    "version": 1,
+                    "project_root": str(root),
+                    "session_id": session_id,
+                    "started_at": int(time.time()),
+                    "baseline_head": git_head(root),
+                    "baseline_worktree": worktree_snapshot(root),
+                    "baseline_repositories": repository_snapshot(root, policy),
+                    "evidence": [],
+                    "touched_files": [],
+                    "prechange_fingerprints": {},
+                    "rescan_required": False,
+                    "stop_block_count": 0,
+                }
+            )
+        return dict(state)
+
+
+def ensure_session(root: Path, event: dict[str, Any]) -> str:
+    session_id = str(event.get("session_id") or "default")
+    path = state_path(root, session_id)
+    if not path.exists():
+        initialize_session(root, event)
+    return session_id
+
+
+def changed_files_for_state(root: Path, state: dict[str, Any], policy: dict[str, Any]) -> list[str]:
+    baseline_repos = state.get("baseline_repositories")
+    if isinstance(baseline_repos, dict):
+        changed = _repository_changes(root, baseline_repos, policy)
+    else:
+        baseline = state.get("baseline_worktree", {})
+        baseline = baseline if isinstance(baseline, dict) else {}
+        current = worktree_snapshot(root)
+        changed = {
+            path
+            for path in set(baseline) | set(current)
+            if baseline.get(path, "<clean>") != current.get(path, "<clean>")
+        }
+        changed.update(_committed_changes(root, str(state.get("baseline_head") or "")))
+
+    prechange = state.get("prechange_fingerprints", {})
+    if isinstance(prechange, dict):
+        for path, before in prechange.items():
+            if file_fingerprint(root / path) != before:
+                changed.add(path)
+
+    ignore = [str(item) for item in policy.get("context_sync", {}).get("ignore", [])]
+    return sorted(path for path in changed if not path_matches(path, ignore))
+
+
+def changes_signature(root: Path, paths: list[str]) -> str:
+    digest = hashlib.sha256()
+    for path in sorted(dict.fromkeys(paths)):
+        digest.update(path.encode("utf-8", errors="surrogateescape"))
+        digest.update(b"\0")
+        digest.update(file_fingerprint(root / path).encode("ascii", errors="replace"))
+        digest.update(b"\0")
+    digest.update(git_head(root).encode("ascii", errors="replace"))
+    return digest.hexdigest()
+
+
+def classify_changes(paths: list[str], policy: dict[str, Any]) -> tuple[str, list[str]]:
+    sync = policy.get("context_sync", {})
+    full_patterns = [str(item) for item in sync.get("full_patterns", [])]
+    medium_patterns = [str(item) for item in sync.get("medium_patterns", [])]
+    full_matches = [path for path in paths if path_matches(path, full_patterns)]
+    medium_matches = [path for path in paths if path_matches(path, medium_patterns)]
+    threshold = int(sync.get("full_file_threshold", 30))
+    manifest_names = {"package.json", "go.mod", "Cargo.toml", "pyproject.toml", "Makefile"}
+    structural = any(Path(path).name in manifest_names for path in paths)
+    if full_matches or (len(paths) > threshold and structural):
+        return "Full", sorted(dict.fromkeys(full_matches or medium_matches))
+    if medium_matches:
+        return "Medium", sorted(dict.fromkeys(medium_matches))
+    return "Light", []
+
+
+def record_prechange_fingerprints(root: Path, session_id: str, paths: list[str]) -> None:
+    if not paths:
+        return
+    with locked_state(root, session_id) as state:
+        fingerprints = state.setdefault("prechange_fingerprints", {})
+        for path in paths:
+            fingerprints.setdefault(path, file_fingerprint(root / path))