phase-loop-runtime 0.2.0__py3-none-any.whl

phase_loop_runtime/pipeline_adapter/branch_ops.py

@@ -0,0 +1,274 @@
+from __future__ import annotations
+
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+from .flag import branchgov_enabled, branchgov_override_explicit
+from .markers import detect_pipeline_mode
+
+
+@dataclass(frozen=True)
+class BranchDecision:
+    """Outcome of a pipeline-branch governance decision (issue #44, IF-0-BRANCH-1).
+
+    ``diverged`` is True when the runner switched away from the operator's
+    current branch to the ``consiliency/pipeline/<version>`` convention branch —
+    the silent-divergence condition #44 makes visible.
+    """
+
+    original_branch: str
+    target_branch: str
+    action: str  # "stay" | "checkout" | "create"
+    diverged: bool
+
+
+# Stable prefix of the BranchGov default-branch refusal message. Shared so
+# reconcile._blocker_precondition_cleared can identify this blocker variant
+# without copying the literal string (the suffix interpolates the branch name).
+REFUSE_DEFAULT_BRANCH_COMMIT_PREFIX = "Refusing git commit on default branch"
+
+# Stable prefix of the BranchGov roadmap-orphan refusal (issue #83). The runner
+# consults `roadmap_orphaned_by_branchgov` BEFORE switching and builds the
+# `branch_sync_conflict` blocker from this summary; shared so downstream
+# precondition-cleared logic can recognise the variant without copying the
+# interpolated suffix (which names the branch and roadmap path).
+REFUSE_ROADMAP_ORPHAN_PREFIX = "Refusing branch-governance switch that would orphan roadmap"
+
+
+class PipelineBranchInvariantError(RuntimeError):
+    def __init__(self, message: str, *, blocker_class: str = "contract_bug") -> None:
+        super().__init__(message)
+        self.blocker_class = blocker_class
+        self.blocker_summary = message
+
+
+class PipelineDefaultBranchRefusalError(PipelineBranchInvariantError):
+    def __init__(self, message: str) -> None:
+        super().__init__(message, blocker_class="branch_sync_conflict")
+
+
+def ensure_pipeline_branch(
+    repo_root: Path,
+    roadmap_version: str,
+    default_branch: str,
+    *,
+    base_ref: str | None = None,
+    base_already_fetched: bool = False,
+) -> BranchDecision:
+    repo = Path(repo_root)
+    pipeline_branch = f"consiliency/pipeline/{roadmap_version}"
+    if not _branchgov_active(repo):
+        current = _current_branch(repo)
+        return BranchDecision(current, current, "stay", False)
+
+    current = _current_branch(repo)
+    if current == default_branch and _dirty_status(repo):
+        raise PipelineDefaultBranchRefusalError(
+            f"Refusing pipeline branch operation from dirty default branch {default_branch}."
+        )
+
+    base_ref = base_ref or f"origin/{default_branch}"
+    # #83: the runner may have already fetched the base once and shared it with
+    # the orphan preflight (so both evaluate the SAME fetched base). Skip the
+    # redundant fetch in that case; default preserves the standalone behaviour.
+    if not base_already_fetched:
+        _fetch_base_ref(repo, base_ref, default_branch)
+    if not _ref_exists(repo, base_ref):
+        raise PipelineBranchInvariantError(
+            f"Pipeline branch base ref {base_ref} is unavailable.",
+            blocker_class="branch_sync_conflict",
+        )
+
+    # Already on the convention branch: no divergence; just stay current.
+    if current == pipeline_branch:
+        rebase = _git(repo, "rebase", base_ref)
+        if rebase.returncode != 0:
+            raise PipelineBranchInvariantError(
+                f"Pipeline branch {pipeline_branch} could not rebase onto {base_ref}.",
+                blocker_class="merge_conflict",
+            )
+        return BranchDecision(current, pipeline_branch, "stay", False)
+
+    # #44: the runner is about to switch the operator's working tree from
+    # `current` to the convention branch. Surface it loudly instead of silently.
+    _warn_branch_divergence(current, pipeline_branch, roadmap_version)
+
+    if _local_branch_exists(repo, pipeline_branch):
+        checkout = _git(repo, "checkout", pipeline_branch)
+        if checkout.returncode != 0:
+            raise PipelineBranchInvariantError(
+                f"Unable to check out pipeline branch {pipeline_branch}: {_stderr_excerpt(checkout)}",
+                blocker_class="branch_sync_conflict",
+            )
+        rebase = _git(repo, "rebase", base_ref)
+        if rebase.returncode != 0:
+            raise PipelineBranchInvariantError(
+                f"Pipeline branch {pipeline_branch} could not rebase onto {base_ref}.",
+                blocker_class="merge_conflict",
+            )
+        return BranchDecision(current, pipeline_branch, "checkout", True)
+
+    created = _git(repo, "checkout", "-b", pipeline_branch, base_ref)
+    if created.returncode != 0:
+        raise PipelineBranchInvariantError(
+            f"Unable to create pipeline branch {pipeline_branch} from {base_ref}: {_stderr_excerpt(created)}",
+            blocker_class="branch_sync_conflict",
+        )
+    return BranchDecision(current, pipeline_branch, "create", True)
+
+
+def roadmap_orphaned_by_branchgov(
+    repo_root: Path,
+    roadmap: Path,
+    roadmap_version: str,
+    default_branch: str,
+    *,
+    base_ref: str | None = None,
+    base_already_fetched: bool = False,
+) -> str | None:
+    """Issue #83 preflight: would a branch-governance switch orphan the roadmap?
+
+    Returns a human-actionable summary string when ALL of the following hold,
+    and ``None`` otherwise (the switch is safe / governed):
+
+      * the switch would DIVERGE — the operator is on a non-convention branch so
+        `ensure_pipeline_branch` would `checkout`/`create` the convention branch
+        (mirrors the #44 divergence condition), AND
+      * the roadmap artifact is committed on the current branch (tracked at HEAD)
+        but is NOT reachable from the pipeline-branch base (absent at
+        ``base_ref``) — i.e. the very file the switch would make vanish, which is
+        what crashes the executor with ``FileNotFoundError`` mid-run.
+
+    The base is evaluated AFTER fetching it, matching `ensure_pipeline_branch`:
+    otherwise a stale local ``refs/remotes/origin/<default>`` would
+    FALSE-POSITIVE-refuse a roadmap that is in fact pushed and on-base. When the
+    runner has already fetched the shared base, pass ``base_already_fetched=True``
+    to avoid a redundant fetch (the caller gates branchgov-active, so this
+    predicate does not re-check it).
+
+    Behaviour-preserving for genuinely governed runs: if the roadmap is present
+    at the FETCHED base (pushed / on-base) the predicate returns ``None`` and the
+    caller proceeds with the existing switch + ``coordinator.branch_switched``.
+    """
+    repo = Path(repo_root)
+
+    pipeline_branch = f"consiliency/pipeline/{roadmap_version}"
+    current = _current_branch(repo)
+    # No divergence when already on the convention branch (the switch is a no-op
+    # "stay"), or on the default branch (handled by the dirty-default refusal).
+    if current == pipeline_branch:
+        return None
+
+    base_ref = base_ref or f"origin/{default_branch}"
+    # Evaluate the FETCHED base (the false-positive fix). Skip the fetch when the
+    # runner already did it and shared the base with us.
+    if not base_already_fetched:
+        _fetch_base_ref(repo, base_ref, default_branch)
+    if not _ref_exists(repo, base_ref):
+        # Base unavailability is surfaced by ensure_pipeline_branch itself; don't
+        # second-guess it here.
+        return None
+
+    rel = _roadmap_relpath(repo, roadmap)
+    if rel is None:
+        return None
+    # Roadmap must be committed on the current branch (tracked at HEAD) — an
+    # uncommitted/untracked roadmap is a different failure mode, not an orphan.
+    if not _path_tracked_at(repo, "HEAD", rel):
+        return None
+    # Safe (governed) when the same roadmap is reachable from the (fetched) base:
+    # the switch keeps the file visible.
+    if _path_tracked_at(repo, base_ref, rel):
+        return None
+
+    return (
+        f"{REFUSE_ROADMAP_ORPHAN_PREFIX} '{rel}'. Branch governance would switch from "
+        f"'{current}' to convention branch '{pipeline_branch}' cut from '{base_ref}', but "
+        f"the roadmap is committed only on '{current}' and is not reachable from "
+        f"'{base_ref}' — the switch would make it vanish and crash the run. Push the "
+        f"roadmap to '{base_ref}' (or land it on the base) to fix this; or, to switch "
+        f"anyway, pass --allow-branchgov (PHASE_LOOP_BRANCHGOV_ENABLE=true) — the run "
+        f"then fails cleanly (branch_sync_conflict) if the roadmap still isn't on the base."
+    )
+
+
+def _roadmap_relpath(repo: Path, roadmap: Path) -> str | None:
+    """POSIX repo-relative pathspec for the roadmap, or None if outside the repo."""
+    try:
+        rel = Path(roadmap).resolve().relative_to(Path(repo).resolve())
+    except (ValueError, OSError):
+        return None
+    return rel.as_posix()
+
+
+def _path_tracked_at(repo: Path, ref: str, relpath: str) -> bool:
+    """True when ``relpath`` is a tracked object at ``ref`` (predicts the FileNotFound)."""
+    return _git(repo, "cat-file", "-e", f"{ref}:{relpath}").returncode == 0
+
+
+def _warn_branch_divergence(current: str, target: str, roadmap_version: str) -> None:
+    sys.stderr.write(
+        f"phase-loop: switching from '{current}' to convention branch '{target}' "
+        f"(roadmap {roadmap_version}) per branch governance; files present only on "
+        f"'{current}' (e.g. a roadmap/plan not yet on '{target}') will not be "
+        f"visible after the switch.\n"
+    )
+
+
+def _fetch_base_ref(repo: Path, base_ref: str, default_branch: str) -> None:
+    if base_ref.startswith("origin/"):
+        _git(repo, "fetch", "origin", base_ref.removeprefix("origin/"))
+    elif base_ref == f"origin/{default_branch}":
+        _git(repo, "fetch", "origin", default_branch)
+
+
+def refuse_default_branch_commit(repo_root: Path, default_branch: str) -> None:
+    repo = Path(repo_root)
+    if not _branchgov_active(repo):
+        return
+    if _current_branch(repo) == default_branch:
+        raise PipelineDefaultBranchRefusalError(
+            f"{REFUSE_DEFAULT_BRANCH_COMMIT_PREFIX} {default_branch} while pipeline branch governance is enabled."
+        )
+
+
+def _branchgov_active(repo: Path) -> bool:
+    return detect_pipeline_mode(repo) and branchgov_enabled()
+
+
+def _current_branch(repo: Path) -> str:
+    result = _git(repo, "branch", "--show-current")
+    if result.returncode == 0 and result.stdout.strip():
+        return result.stdout.strip()
+    head = _git(repo, "rev-parse", "--short", "HEAD")
+    return f"detached@{head.stdout.strip()}" if head.returncode == 0 and head.stdout.strip() else "unknown"
+
+
+def _dirty_status(repo: Path) -> str:
+    result = _git(repo, "status", "--porcelain", "--untracked-files=all")
+    return result.stdout.strip() if result.returncode == 0 else ""
+
+
+def _ref_exists(repo: Path, ref: str) -> bool:
+    return _git(repo, "rev-parse", "--verify", "--quiet", ref).returncode == 0
+
+
+def _local_branch_exists(repo: Path, branch: str) -> bool:
+    return _ref_exists(repo, f"refs/heads/{branch}")
+
+
+def _git(repo: Path, *args: str) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        ["git", "-C", str(repo), *args],
+        check=False,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+    )
+
+
+def _stderr_excerpt(result: subprocess.CompletedProcess[str]) -> str:
+    text = (result.stderr or result.stdout or "").strip()
+    return " ".join(text.split())[:300] or "git command failed"

phase_loop_runtime/pipeline_adapter/flag.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+import os
+
+
+def branchgov_enabled() -> bool:
+    return os.environ.get("PHASE_LOOP_BRANCHGOV_ENABLE") != "false"
+
+
+def branchgov_override_explicit() -> bool:
+    """True only when branch governance is EXPLICITLY opted into (issue #83).
+
+    Distinct from ``branchgov_enabled()`` (which is True for both the unset
+    default and ``"true"``). The default-on case is exactly the bug surface: a
+    locally-committed roadmap on the operator's branch would be orphaned by the
+    convention-branch switch. The orphan-refusal preflight must therefore key on
+    this *explicit* signal — set by ``--allow-branchgov`` (which exports
+    ``PHASE_LOOP_BRANCHGOV_ENABLE=true``) — so the unset default still refuses
+    and only a deliberate ``"true"`` (or ``--allow-branchgov``) switches anyway.
+    """
+    return os.environ.get("PHASE_LOOP_BRANCHGOV_ENABLE") == "true"
+
+
+def trust_executor_evidence_enabled() -> bool:
+    return os.environ.get("PHASE_LOOP_TRUST_EXECUTOR_EVIDENCE") != "false"
+
+
+def allow_lane_ir_override_enabled() -> bool:
+    return os.environ.get("PHASE_LOOP_ALLOW_LANE_IR_OVERRIDE") != "false"
+
+
+def dispatch_lock_enabled() -> bool:
+    return os.environ.get("PHASE_LOOP_DISPATCH_LOCK") != "false"
+
+
+def parallel_dispatch_enabled() -> bool:
+    return os.environ.get("PHASE_LOOP_PARALLEL_DISPATCH") != "false"
+
+
+def reconcile_git_reality_enabled() -> bool:
+    # SAFE CUTOVER: defaults OFF (opt-in), unlike the flags above. The active body
+    # wires into classify_phase — the universal classifier — so on our own runtime
+    # the feature lands inert and is flipped on deliberately after validation.
+    return os.environ.get("PHASE_LOOP_RECONCILE_GIT_REALITY") == "true"
+
+
+def concurrent_real_exec_integration_enabled() -> bool:
+    # SAFE CUTOVER: defaults OFF (opt-in). Switches the concurrent scheduler's
+    # worktree integration from the committed-only merge (integrate_phase_worktree)
+    # to dirty-work transport (transfer_phase_worktree_dirty), which lands a real
+    # executor's uncommitted phase-owned work onto the pipeline branch so the
+    # parent closeout commits it. Only active under `--phase-scheduler concurrent`
+    # (itself opt-in); flipped on deliberately after a real concurrent run
+    # validates the transport on this runtime's own repo.
+    return os.environ.get("PHASE_LOOP_CONCURRENT_REAL_EXEC") == "true"

phase_loop_runtime/pipeline_adapter/markers.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+def detect_pipeline_mode(repo_root: Path) -> bool:
+    root = Path(repo_root)
+    return (
+        (root / ".pipeline").exists()
+        or (root / ".github" / "workflows" / "pipeline-bootstrap.yml").exists()
+        or os.environ.get("PHASE_LOOP_PIPELINE_MODE") == "true"
+    )

phase_loop_runtime/pipeline_adapter/merge_policy.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any
+
+
+MERGE_POLICY_ON_PASS = ("required", "auto", "never")
+
+
+class MergePolicyParseError(ValueError):
+    pass
+
+
+@dataclass(frozen=True)
+class MergePolicy:
+    on_pass: str = "required"
+    approvers: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        if self.on_pass not in MERGE_POLICY_ON_PASS:
+            raise MergePolicyParseError(f"invalid merge_policy.on_pass: {self.on_pass}")
+        normalized = tuple(str(approver).strip() for approver in self.approvers if str(approver).strip())
+        object.__setattr__(self, "approvers", normalized)
+
+    def to_json(self) -> dict[str, object]:
+        return {"on_pass": self.on_pass, "approvers": list(self.approvers)}
+
+
+def parse(phase_block: dict) -> MergePolicy:
+    if "merge_policy" not in phase_block or phase_block.get("merge_policy") in (None, ""):
+        return MergePolicy(on_pass="required", approvers=())
+
+    raw = _coerce_policy_block(phase_block["merge_policy"])
+    on_pass = str(raw.get("on_pass") or "required").strip()
+    if on_pass not in MERGE_POLICY_ON_PASS:
+        raise MergePolicyParseError(f"invalid merge_policy.on_pass: {on_pass}")
+
+    approvers = _approver_tuple(raw.get("approvers"))
+    if on_pass == "required" and not approvers:
+        raise MergePolicyParseError("explicit merge_policy.on_pass=required requires at least one approver")
+    return MergePolicy(on_pass=on_pass, approvers=approvers)
+
+
+def _coerce_policy_block(value: Any) -> dict[str, Any]:
+    if isinstance(value, dict):
+        return value
+    if isinstance(value, str):
+        stripped = value.strip()
+        if not stripped:
+            return {}
+        if stripped in MERGE_POLICY_ON_PASS:
+            return {"on_pass": stripped}
+        try:
+            decoded = json.loads(stripped)
+        except json.JSONDecodeError as exc:
+            raise MergePolicyParseError(f"invalid merge_policy JSON: {exc.msg}") from exc
+        if isinstance(decoded, dict):
+            return decoded
+    raise MergePolicyParseError("merge_policy must be an object or JSON object string")
+
+
+def _approver_tuple(value: Any) -> tuple[str, ...]:
+    if value is None:
+        return ()
+    if isinstance(value, str):
+        items = value.split(",")
+    elif isinstance(value, (list, tuple)):
+        items = value
+    else:
+        raise MergePolicyParseError("merge_policy.approvers must be a list, tuple, or comma-separated string")
+    return tuple(str(item).strip() for item in items if str(item).strip())

phase_loop_runtime/pipeline_adapter/ratification.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+import json
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from ..git_topology import collect_git_topology
+from ..runtime_paths import ensure_phase_loop_excluded, phase_loop_event_file
+from ..models import utc_now
+from .merge_policy import MergePolicy
+
+
+TRIGGER_PATH = Path(".pipeline") / "ratification-trigger.json"
+
+
+def emit_ratification_passed(
+    repo_root: Path,
+    roadmap_version: str,
+    phase_alias: str,
+    ratification_gate: str,
+    merge_policy: MergePolicy,
+    audit: dict[str, Any],
+) -> None:
+    repo = Path(repo_root)
+    payload = _payload(repo, roadmap_version, phase_alias, ratification_gate, merge_policy, audit)
+    ensure_phase_loop_excluded(repo)
+    event_path = phase_loop_event_file(repo)
+    event_path.parent.mkdir(parents=True, exist_ok=True)
+    event = {
+        "timestamp": utc_now(),
+        "repo": str(repo),
+        "roadmap": roadmap_version,
+        "phase": phase_alias,
+        "event_type": "ratification.passed",
+        "action": "ratification",
+        "status": "passed",
+        "source": "pipeline_adapter",
+        "schema_version": 2,
+        "payload": payload,
+        "git_topology": collect_git_topology(repo),
+    }
+    with event_path.open("a", encoding="utf-8") as handle:
+        handle.write(json.dumps(event, sort_keys=True) + "\n")
+
+    trigger = repo / TRIGGER_PATH
+    trigger.parent.mkdir(parents=True, exist_ok=True)
+    trigger.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+
+
+def _payload(
+    repo: Path,
+    roadmap_version: str,
+    phase_alias: str,
+    ratification_gate: str,
+    merge_policy: MergePolicy,
+    audit: dict[str, Any],
+) -> dict[str, Any]:
+    return {
+        "roadmap_version": roadmap_version,
+        "phase_alias": phase_alias,
+        "ratification_gate": ratification_gate,
+        "merge_policy": merge_policy.to_json(),
+        "audit": dict(audit),
+        "pipeline_branch": _current_branch(repo),
+        "default_branch": _default_branch(repo),
+        "head_sha": _git_output_or_empty(repo, "rev-parse", "HEAD") or None,
+        "merge_pr_title": f"{roadmap_version} phase {phase_alias} ratification: {ratification_gate}",
+    }
+
+
+def _current_branch(repo: Path) -> str:
+    return _git_output_or_empty(repo, "branch", "--show-current") or "detached"
+
+
+def _default_branch(repo: Path) -> str:
+    remote_head = _git_output_or_empty(repo, "symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD")
+    if remote_head.startswith("origin/"):
+        return remote_head.removeprefix("origin/")
+    # Authoritative fallback: ask the remote for its HEAD when origin/HEAD is unset.
+    # The previous fallback used @{upstream} which returns the current branch's
+    # tracking ref and could mis-identify the pipeline branch as the default.
+    ls_remote = _git_output_or_empty(repo, "ls-remote", "--symref", "origin", "HEAD")
+    for line in ls_remote.splitlines():
+        if line.startswith("ref: refs/heads/"):
+            ref = line.split("\t", 1)[0].removeprefix("ref: refs/heads/").strip()
+            if ref:
+                return ref
+    return "main"
+
+
+def _git_output_or_empty(repo: Path, *args: str) -> str:
+    try:
+        return subprocess.check_output(
+            ["git", "-C", str(repo), *args],
+            text=True,
+            stderr=subprocess.DEVNULL,
+        ).strip()
+    except Exception:
+        return ""

phase_loop_runtime/pipeline_adapter/sibling_matcher.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+from pathlib import PurePosixPath
+
+
+LOCKFILE_NAMES = {"package-lock.json", "pnpm-lock.yaml", "yarn.lock", "bun.lockb"}
+ENV_SOURCE_NAMES = {"env.ts", "env.js", "env.mjs", "env.cjs", "environment.ts", "environment.js"}
+
+
+def validate_phase_owned_evidence(
+    declared_paths: tuple[str, ...] | list[str],
+    actual_paths: tuple[str, ...] | list[str],
+    evidence: object,
+) -> tuple[dict[str, str], ...]:
+    declared = tuple(filter(None, (_clean_path(path) for path in declared_paths)))
+    actual = set(filter(None, (_clean_path(path) for path in actual_paths)))
+    accepted: list[dict[str, str]] = []
+    seen: set[str] = set()
+
+    for item in _evidence_items(evidence):
+        evidence_path = _clean_path(str(item.get("path") or item.get("actual_path") or item.get("sibling") or ""))
+        if not evidence_path or evidence_path not in actual or evidence_path in seen:
+            continue
+        match = _matching_declared_path(evidence_path, declared)
+        if match is None:
+            continue
+        accepted.append(
+            {
+                "path": evidence_path,
+                "declared_path": match[0],
+                "kind": match[1],
+            }
+        )
+        seen.add(evidence_path)
+
+    return tuple(accepted)
+
+
+def _evidence_items(evidence: object) -> tuple[dict[str, object], ...]:
+    if not isinstance(evidence, list):
+        return ()
+    items: list[dict[str, object]] = []
+    for item in evidence:
+        if isinstance(item, str):
+            items.append({"path": item})
+        elif isinstance(item, dict):
+            items.append(item)
+    return tuple(items)
+
+
+def _clean_path(path: str) -> str:
+    path = path.replace("\\", "/").strip().strip("/")
+    if not path or path.startswith("/") or path.startswith("../") or "/../" in path or path == "..":
+        return ""
+    return path
+
+
+def _matching_declared_path(path: str, declared_paths: tuple[str, ...]) -> tuple[str, str] | None:
+    for declared in declared_paths:
+        if _is_test_for(path, declared):
+            return declared, "test"
+        if _is_snapshot_for(path, declared):
+            return declared, "snapshot"
+        if _is_migration_peer(path, declared):
+            return declared, "migration_timestamp"
+        if _is_lockfile_for_manifest(path, declared):
+            return declared, "package_lock"
+        if _is_env_example_for(path, declared):
+            return declared, "env_example"
+    return None
+
+
+def _stem_without_test_suffix(name: str) -> str:
+    for suffix in (".test", ".spec"):
+        if name.endswith(suffix):
+            return name[: -len(suffix)]
+    return name
+
+
+def _is_test_for(path: str, declared: str) -> bool:
+    candidate = PurePosixPath(path)
+    source = PurePosixPath(declared)
+    if "__tests__" not in candidate.parts and not candidate.name.startswith("test_"):
+        return False
+    candidate_stem = _stem_without_test_suffix(candidate.stem)
+    source_stem = source.stem
+    if candidate.name.startswith("test_"):
+        candidate_stem = candidate_stem.removeprefix("test_")
+    return candidate_stem == source_stem
+
+
+def _is_snapshot_for(path: str, declared: str) -> bool:
+    candidate = PurePosixPath(path)
+    source = PurePosixPath(declared)
+    return "__snapshots__" in candidate.parts and candidate.stem.startswith(source.stem)
+
+
+def _migration_timestamp(path: str) -> str | None:
+    candidate = PurePosixPath(path)
+    if "migrations" not in candidate.parts:
+        return None
+    prefix = candidate.name.split("_", 1)[0]
+    return prefix if prefix.isdigit() and len(prefix) >= 8 else None
+
+
+def _is_migration_peer(path: str, declared: str) -> bool:
+    path_ts = _migration_timestamp(path)
+    declared_ts = _migration_timestamp(declared)
+    return bool(path_ts and declared_ts and path_ts == declared_ts and path != declared)
+
+
+def _is_lockfile_for_manifest(path: str, declared: str) -> bool:
+    candidate = PurePosixPath(path)
+    source = PurePosixPath(declared)
+    return candidate.parent == source.parent and candidate.name in LOCKFILE_NAMES and source.name == "package.json"
+
+
+def _is_env_example_for(path: str, declared: str) -> bool:
+    candidate = PurePosixPath(path)
+    source = PurePosixPath(declared)
+    if candidate.name != ".env.example":
+        return False
+    return candidate.parent == source.parent and (source.name in ENV_SOURCE_NAMES or "env" in source.stem.lower())