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

phase_loop_runtime/redaction.py

@@ -0,0 +1,184 @@
+from __future__ import annotations
+
+import json
+import re
+from pathlib import PurePosixPath
+from typing import Any, Mapping
+
+from .models import CHANGED_PATH_CATEGORIES, SourceTruthImpact
+
+
+_SOURCE_TRUTH_REASON_BY_CATEGORY = {
+    "docs": "docs_source_truth_touched",
+    "specs": "specs_source_truth_touched",
+    "active_canonical_spec": "active_specs_touched",
+    "managed_root_mirror_spec": "managed_mirror_specs_touched",
+    "mirror_manifest": "mirror_manifests_touched",
+    "archive_manifest": "archive_manifests_touched",
+    "archived_spec": "archived_specs_touched",
+    "unmanaged_spec": "unmanaged_specs_touched",
+    "pipeline_sources": "pipeline_sources_touched",
+    "portal_contract_refs": "portal_contract_refs_touched",
+    "greenfield_authority_refs": "greenfield_authority_refs_touched",
+}
+
+_CATEGORY_BY_PROTECTED_SOURCE_ROLE = {
+    "active_canonical_spec": "active_canonical_spec",
+    "managed_mirror_file": "managed_root_mirror_spec",
+    "mirror_manifest": "mirror_manifest",
+    "archive_manifest": "archive_manifest",
+    "archived_spec": "archived_spec",
+    "unmanaged_spec_input": "unmanaged_spec",
+    "root_specs_intake": "unmanaged_spec",
+}
+
+_FORBIDDEN_METADATA_PATTERNS: tuple[tuple[str, re.Pattern[str]], ...] = (
+    ("raw_diff", re.compile(r"diff --git|@@\s+-\d+,\d+\s+\+\d+,\d+\s+@@")),
+    ("raw_spec_body", re.compile(r"raw spec bod(?:y|ies)|spec body bytes|verbatim spec", re.I)),
+    ("raw_transcript", re.compile(r"raw transcript|transcript bytes|verbatim transcript", re.I)),
+    ("secret_like_value", re.compile(r"(?:api[_-]?key|secret|token|password)\s*[:=]\s*['\"]?[A-Za-z0-9_\-]{12,}", re.I)),
+    ("absolute_private_path", re.compile(r"/(?:home|users|mnt/(?:private|evidence|secure|raw|HC_Volume_[^/\s]+))/(?:[^\"'\s]+)", re.I)),
+    ("provider_payload", re.compile(r"raw provider payload|provider payload|anthropic[_-]?payload|openai[_-]?payload", re.I)),
+    ("credential_payload", re.compile(r"credential payload|private key|-----begin [a-z ]*private key-----", re.I)),
+    ("local_env_value", re.compile(r"local env value|\.env(?:\.local)? value|process\.env\[[^\]]+\]\s*=", re.I)),
+    ("private_evidence", re.compile(r"private evidence|evidence bytes|raw evidence", re.I)),
+)
+
+
+def classify_changed_path(path: str, protected_source_roles: Mapping[str, str] | None = None) -> str:
+    normalized = _normalize_path(path)
+    parts = PurePosixPath(normalized).parts
+    lower = normalized.lower()
+    role_category = _category_from_protected_source_role(normalized, protected_source_roles)
+    if role_category is not None:
+        return role_category
+
+    if normalized.startswith("tests/") or "/tests/" in normalized or "/fixtures/" in normalized:
+        return "tests"
+    if lower == "readme.md" or normalized.startswith("docs/") or normalized.endswith(".md") and "/docs/" in normalized:
+        return "docs"
+    if _looks_like_mirror_manifest(normalized, lower):
+        return "mirror_manifest"
+    if _looks_like_archive_manifest(normalized, lower):
+        return "archive_manifest"
+    if _looks_like_active_canonical_spec(normalized, lower):
+        return "active_canonical_spec"
+    if _looks_like_archived_spec(normalized, lower):
+        return "archived_spec"
+    if normalized.startswith("specs/") or normalized.startswith("spec/"):
+        return "unmanaged_spec"
+    if (
+        normalized.startswith(".pipeline/")
+        or "pipeline.definition.json" in lower
+        or normalized.startswith("packages/pipeline-schema/")
+        or normalized.startswith("pipeline-sources/")
+    ):
+        return "pipeline_sources"
+    if (
+        "portal-contract" in lower
+        or normalized.startswith("portal/contracts/")
+        or normalized.startswith("contracts/portal/")
+        or normalized.startswith("consiliency-portal/contracts/")
+    ):
+        return "portal_contract_refs"
+    if (
+        "greenfield-authority" in lower
+        or normalized.startswith("greenfield/authority/")
+        or normalized.startswith("greenfield/contracts/")
+        or normalized.startswith("authority/greenfield/")
+    ):
+        return "greenfield_authority_refs"
+    if _looks_like_code_path(normalized, parts):
+        return "code"
+    return "unknown"
+
+
+def build_source_truth_impact(
+    changed_paths: tuple[str, ...] | list[str] | Any,
+    protected_source_roles: Mapping[str, str] | None = None,
+) -> SourceTruthImpact:
+    paths = _stable_paths(changed_paths)
+    boundaries = tuple(
+        {"path": path, "category": classify_changed_path(path, protected_source_roles)}
+        for path in paths
+    )
+    reasons: list[str] = []
+    for boundary in boundaries:
+        category = boundary["category"]
+        reason = _SOURCE_TRUTH_REASON_BY_CATEGORY.get(category)
+        if reason is not None:
+            reasons.append(reason)
+        if "adoption" in boundary["path"].lower() and "contract" in boundary["path"].lower():
+            reasons.append("adoption_contracts_touched")
+        if "contract" in boundary["path"].lower() and category in CHANGED_PATH_CATEGORIES:
+            reasons.append("contract_refs_touched")
+    return SourceTruthImpact(
+        changed_path_boundaries=boundaries,
+        canonical_refresh_recommended=bool(reasons),
+        canonical_refresh_reason_codes=tuple(sorted(dict.fromkeys(reasons))),
+        redaction_posture="metadata_only",
+    )
+
+
+def metadata_redaction_diagnostic(payload: Mapping[str, Any] | None) -> dict[str, str] | None:
+    if payload is None:
+        return None
+    serialized = json.dumps(payload, sort_keys=True)
+    for kind, pattern in _FORBIDDEN_METADATA_PATTERNS:
+        if pattern.search(serialized):
+            return {"kind": "malformed_closeout", "message": f"closeout contains forbidden metadata token: {kind}"}
+    return None
+
+
+def _normalize_path(path: str) -> str:
+    normalized = str(path).replace("\\", "/").strip()
+    return normalized[2:] if normalized.startswith("./") else normalized
+
+
+def _stable_paths(paths: tuple[str, ...] | list[str] | Any) -> list[str]:
+    if not isinstance(paths, (tuple, list)):
+        return []
+    return sorted(dict.fromkeys(_normalize_path(str(path)) for path in paths if str(path).strip()))
+
+
+def _looks_like_code_path(path: str, parts: tuple[str, ...]) -> bool:
+    if path.startswith(("codex-config/", "shared/skills/", "scripts/")):
+        return True
+    if parts and parts[0] in {"bin", "lib", "src"}:
+        return True
+    return PurePosixPath(path).suffix in {".py", ".sh", ".bash", ".zsh", ".toml", ".yaml", ".yml", ".json"}
+
+
+def _category_from_protected_source_role(
+    path: str,
+    protected_source_roles: Mapping[str, str] | None,
+) -> str | None:
+    if not protected_source_roles:
+        return None
+    role = protected_source_roles.get(path) or protected_source_roles.get(path.lower())
+    if role is None:
+        return None
+    return _CATEGORY_BY_PROTECTED_SOURCE_ROLE.get(role)
+
+
+def _looks_like_mirror_manifest(path: str, lower: str) -> bool:
+    name = PurePosixPath(path).name.lower()
+    return name == "mirror-manifest.json" or "mirror_manifest" in lower or "/mirror-manifest" in lower
+
+
+def _looks_like_archive_manifest(path: str, lower: str) -> bool:
+    name = PurePosixPath(path).name.lower()
+    return name == "archive-manifest.json" or "archive_manifest" in lower or "/archive-manifest" in lower
+
+
+def _looks_like_active_canonical_spec(path: str, lower: str) -> bool:
+    return (
+        path.startswith(".pipeline/specs/active/")
+        or path.startswith(".pipeline/specs/canonical/")
+        or "/active-canonical/" in lower
+        or "/canonical-specs/" in lower
+    )
+
+
+def _looks_like_archived_spec(path: str, lower: str) -> bool:
+    return path.startswith(".pipeline/specs/archive/") or "/archived-specs/" in lower

phase_loop_runtime/reflection_sync.py

@@ -0,0 +1,293 @@
+"""Multi-machine reflection collection (Slice 1).
+
+Reflections are written locally by skills at close-out (see
+``claude-config/shared/runtime-state.md``) and never leave the machine — they
+are gitignored and live in ``~/.<harness>/skills/<skill>/reflections/``. This
+module provides the *collection half*: redact each reflection (so it is safe to
+pool across machines, including off-tailnet collaborators) and copy it under a
+machine-namespaced path into a shared store directory.
+
+Two pure, testable building blocks:
+
+* :func:`machine_id` — a stable, non-secret per-machine identifier.
+* :func:`redact_reflection_text` — deterministically strips repo/branch/commit/
+  path identity from a reflection so the pooled copy is repo-agnostic.
+
+and the orchestrator :func:`export_reflections`, invoked by
+``scripts/reflections-sync``. The git transport and run-id dedup ledger are
+intentionally deferred to Slice 2 (a ``phase-loop reflections sync`` subcommand).
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import os
+import re
+import socket
+import sys
+import uuid
+from pathlib import Path
+
+from .skill_paths import resolve_skill_bundle_root
+
+DEFAULT_HARNESSES: tuple[str, ...] = ("claude", "codex", "gemini", "opencode")
+
+# Repo-local (source-controlled) reflection roots per harness, relative to repo.
+_REPO_LOCAL_ROOTS: dict[str, tuple[str, ...]] = {
+    "claude": ("claude-config/claude-skills", "claude-config/skills"),
+    "codex": ("codex-config/skills",),
+    "gemini": ("gemini-config/skills",),
+    "opencode": ("opencode-config/skills",),
+}
+
+
+# ---------------------------------------------------------------------------
+# Machine identity
+# ---------------------------------------------------------------------------
+
+def _slug(value: str) -> str:
+    out = re.sub(r"[^A-Za-z0-9._-]+", "-", value.strip())
+    out = re.sub(r"-{2,}", "-", out).strip("-")
+    return out or "unknown"
+
+
+def _machine_id_file() -> Path:
+    base = os.environ.get("XDG_CONFIG_HOME") or os.path.expanduser("~/.config")
+    return Path(base) / "dotfiles" / "machine-id"
+
+
+def machine_id() -> str:
+    """Return a stable, non-secret identifier for this machine.
+
+    Persisted at ``$XDG_CONFIG_HOME/dotfiles/machine-id`` (default
+    ``~/.config/dotfiles/machine-id``) so it survives across runs and is
+    independent of tailnet membership — off-tailnet collaborators have no
+    tailscale hostname. ``DOTFILES_MACHINE_ID`` overrides. Falls back to a
+    hostname-derived hash if the id file cannot be written.
+    """
+    override = os.environ.get("DOTFILES_MACHINE_ID")
+    if override and override.strip():
+        return _slug(override)
+
+    path = _machine_id_file()
+    try:
+        existing = path.read_text(encoding="utf-8").strip()
+        if existing:
+            return _slug(existing)
+    except OSError:
+        pass
+
+    new_id = uuid.uuid4().hex[:12]
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(new_id + "\n", encoding="utf-8")
+        return new_id
+    except OSError:
+        host = socket.gethostname() or "unknown-host"
+        return "host-" + hashlib.sha256(host.encode("utf-8")).hexdigest()[:10]
+
+
+# ---------------------------------------------------------------------------
+# Redaction
+# ---------------------------------------------------------------------------
+
+# Structured Run-context / frontmatter fields whose values reveal identity.
+# Maps a lowercased field name to the placeholder prefix used for its hash.
+_SENSITIVE_FIELDS: dict[str, str] = {
+    "repo": "repo",
+    "repo root": "repo-root",
+    "repo_root": "repo-root",
+    "repo path": "repo-root",
+    "branch": "branch",
+    "branch slug": "branch",
+    "branch_slug": "branch",
+    "commit": "commit",
+    "artifact": "artifact",
+    "artifact path": "artifact",
+}
+
+# Matches "- Field: value", "Field: value", "field = value" (markdown or yaml).
+_FIELD_RE = re.compile(
+    r"^(?P<prefix>\s*(?:[-*]\s+)?(?P<name>[A-Za-z][A-Za-z _]*?)\s*[:=]\s*)(?P<value>.*?)\s*$"
+)
+
+# Already-redacted token (e.g. "<repo:ab12cd34ef>") or an explicit empty marker.
+_REDACTED_RE = re.compile(r"^(<[^>]*>|none|n/?a|-)?$", re.IGNORECASE)
+
+# Absolute project/worktree roots: collapse the private prefix *and* the project
+# segment to "<repo>", keeping any instructive repo-relative tail.
+_PROJECT_PATH_RE = re.compile(
+    r"/(?:mnt/[^/\s]+/(?:code|worktrees)"
+    r"|home/[^/\s]+/(?:projects|code|src|repos|dev|work)"
+    r"|Users/[^/\s]+/(?:projects|code|src|repos|dev|work))"
+    r"/[^/\s:'\"]+"
+)
+
+# Remaining home prefixes: drop the username, keep the generic tail (e.g.
+# "/home/jenner/.claude/skills" -> "~/.claude/skills").
+_HOME_PATH_RE = re.compile(r"/home/[^/\s]+|/Users/[^/\s]+|/root(?=/|\b)")
+
+
+def _hash_token(value: str, prefix: str) -> str:
+    digest = hashlib.sha256(value.strip().encode("utf-8")).hexdigest()[:10]
+    return f"<{prefix}:{digest}>"
+
+
+def _redact_paths(text: str) -> str:
+    text = _PROJECT_PATH_RE.sub("<repo>", text)
+    text = _HOME_PATH_RE.sub("~", text)
+    return text
+
+
+def redact_reflection_text(text: str, machine: str | None = None) -> str:
+    """Return a repo-agnostic copy of a reflection, safe to pool across machines.
+
+    Deterministic and idempotent. Two passes:
+
+    1. **Structured fields** (Repo/Branch/Commit/Artifact/repo_root/...): replace
+       the value with a stable hash token, so the same repo/branch still
+       *correlates* across reflections without revealing its name. Values that
+       are already redacted, empty, or "none" are left untouched (idempotency).
+    2. **Free-text paths**: collapse absolute project/worktree paths to
+       ``<repo>/...`` and strip usernames from home paths.
+
+    Known limitation: free-text references to a repo/branch *by bare name*
+    (not as a path) can't be detected and are not redacted — the v36 schema's
+    "repo-agnostic" intent still applies to authored content. The structured
+    fields above are the guaranteed-clean part.
+    """
+    lines = text.splitlines(keepends=False)
+    out: list[str] = []
+    already_marked = bool(lines) and lines[0].startswith("<!-- reflection-sync: redacted;")
+    if machine and not already_marked:
+        out.append(f"<!-- reflection-sync: redacted; machine={_slug(machine)} -->")
+
+    for line in lines:
+        m = _FIELD_RE.match(line)
+        if m:
+            name = m.group("name").strip().lower()
+            prefix = _SENSITIVE_FIELDS.get(name)
+            if prefix is not None:
+                value = m.group("value")
+                if _REDACTED_RE.match(value.strip()):
+                    out.append(line)
+                else:
+                    out.append(m.group("prefix") + _hash_token(value, prefix))
+                continue
+        out.append(_redact_paths(line))
+
+    result = "\n".join(out)
+    if text.endswith("\n"):
+        result += "\n"
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Export
+# ---------------------------------------------------------------------------
+
+def _candidate_roots(repo: Path, harness: str) -> list[Path]:
+    roots = [resolve_skill_bundle_root(harness)]
+    for rel in _REPO_LOCAL_ROOTS.get(harness, ()):
+        roots.append(repo / rel)
+    return roots
+
+
+def iter_reflection_files(repo: Path, harnesses: tuple[str, ...] = DEFAULT_HARNESSES):
+    """Yield ``(skill_name, rel_path, source_path)`` for every live reflection.
+
+    ``rel_path`` is relative to the skill's ``reflections/`` dir (e.g.
+    ``<repo_hash>/<branch_slug>/<run_id>.md``, or a flat ``<file>.md`` for legacy
+    layouts). Archived reflections are skipped. Duplicate (skill, rel) pairs
+    seen across roots are de-duplicated.
+    """
+    repo = Path(repo).expanduser()
+    seen: set[tuple[str, str]] = set()
+    for harness in harnesses:
+        for root in _candidate_roots(repo, harness):
+            if not root.exists():
+                continue
+            for refl_dir in sorted(root.glob("*/reflections")):
+                skill = refl_dir.parent.name
+                for path in sorted(refl_dir.rglob("*.md")):
+                    if "archive" in path.parts or not path.is_file():
+                        continue
+                    rel = path.relative_to(refl_dir)
+                    key = (skill, rel.as_posix())
+                    if key in seen:
+                        continue
+                    seen.add(key)
+                    yield skill, rel, path
+
+
+def export_reflections(
+    repo: Path,
+    dest_root: Path,
+    machine: str | None = None,
+    harnesses: tuple[str, ...] = DEFAULT_HARNESSES,
+) -> list[Path]:
+    """Redact and copy every live reflection into a machine-namespaced store.
+
+    Destination layout (the ``<machine>`` segment sits directly above the file,
+    so machines never collide even on an identical repo_hash/branch):
+
+        ``<dest_root>/<skill>/<rel.parent>/<machine>/<rel.name>``
+
+    Returns the list of written destination paths.
+    """
+    machine = machine or machine_id()
+    dest_root = Path(dest_root).expanduser()
+    written: list[Path] = []
+    for skill, rel, src in iter_reflection_files(repo, harnesses):
+        try:
+            text = src.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        # Skip reflections that were imported from the pool (already redacted on
+        # another machine) so an aggregator never re-pools them under its own id.
+        if text.lstrip().startswith("<!-- reflection-sync: redacted;"):
+            continue
+        redacted = redact_reflection_text(text, machine=machine)
+        dest = dest_root / skill / rel.parent / machine / rel.name
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_text(redacted, encoding="utf-8")
+        written.append(dest)
+    return written
+
+
+# ---------------------------------------------------------------------------
+# Minimal CLI seam (the full `phase-loop reflections sync` subcommand is Slice 2)
+# ---------------------------------------------------------------------------
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="phase_loop_runtime.reflection_sync")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    exp = sub.add_parser("export", help="redact + copy local reflections to a store dir")
+    exp.add_argument("--repo", required=True, help="repo root to scan")
+    exp.add_argument("--dest", required=True, help="destination store root")
+    exp.add_argument("--machine", default=None, help="machine id override")
+
+    mid = sub.add_parser("machine-id", help="print this machine's stable id")
+    mid.set_defaults(_is_machine_id=True)
+
+    args = parser.parse_args(argv)
+
+    if args.command == "machine-id":
+        print(machine_id())
+        return 0
+
+    if args.command == "export":
+        written = export_reflections(
+            Path(args.repo), Path(args.dest), machine=args.machine
+        )
+        print(f"exported {len(written)} reflection(s) to {args.dest}")
+        return 0
+
+    parser.error("unknown command")
+    return 2
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

phase_loop_runtime/release_guard.py

@@ -0,0 +1,186 @@
+from __future__ import annotations
+
+import fnmatch
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .discovery import plan_metadata
+
+
+RELEASE_DISPATCH_MUTATION = "release_dispatch"
+RELEASE_AFFECTING_PATTERNS = (
+    ".github/workflows/**",
+    "CHANGELOG*",
+    "RELEASE*",
+    "VERSION",
+    "pyproject.toml",
+    "setup.cfg",
+    "setup.py",
+    "uv.lock",
+    "poetry.lock",
+    "requirements*.txt",
+    "docs/release/**",
+    "docs/releases/**",
+    "docs/release*.md",
+    "scripts/*release*",
+    "scripts/download-release.py",
+)
+
+
+@dataclass(frozen=True)
+class ReleaseDispatchBlocker:
+    blocker_class: str
+    blocker_summary: str
+    required_human_inputs: tuple[str, ...]
+    metadata: dict[str, Any]
+
+    def to_blocker(self) -> dict[str, Any]:
+        return {
+            "human_required": True,
+            "blocker_class": self.blocker_class,
+            "blocker_summary": self.blocker_summary,
+            "required_human_inputs": self.required_human_inputs,
+        }
+
+
+def is_release_dispatch_plan(plan: Path | None) -> bool:
+    if plan is None:
+        return False
+    metadata = plan_metadata(plan)
+    if metadata.get("phase_loop_mutation") == RELEASE_DISPATCH_MUTATION:
+        return True
+    try:
+        text = plan.read_text(encoding="utf-8").lower()
+    except OSError:
+        return False
+    return "gh workflow run" in text and "release" in text
+
+
+def release_dispatch_blocker(repo: Path, plan: Path | None) -> ReleaseDispatchBlocker | None:
+    if plan is None or not is_release_dispatch_plan(plan):
+        return None
+
+    metadata = plan_metadata(plan)
+    dirty_paths = _dirty_release_affecting_paths(repo)
+    if dirty_paths:
+        return ReleaseDispatchBlocker(
+            blocker_class="dirty_worktree_conflict",
+            blocker_summary=(
+                "Release dispatch requires clean release-affecting files before the "
+                "external workflow is started."
+            ),
+            required_human_inputs=(
+                "Commit, merge, or isolate the release-affecting changes.",
+                "Sync the release branch with the configured base ref, then rerun the dispatch phase.",
+            ),
+            metadata={
+                "guard": "release_dispatch",
+                "reason": "dirty_release_affecting_paths",
+                "plan": str(plan),
+                "dirty_paths": dirty_paths,
+                "phase_loop_mutation": metadata.get("phase_loop_mutation"),
+            },
+        )
+
+    base_ref, base_ref_explicit = _release_base_ref(metadata)
+    sync = _branch_sync(repo, base_ref)
+    if not sync["base_available"]:
+        if not base_ref_explicit and not sync["base_remote_available"]:
+            return None
+        return ReleaseDispatchBlocker(
+            blocker_class="branch_sync_conflict",
+            blocker_summary=f"Release dispatch base ref `{base_ref}` is unavailable locally.",
+            required_human_inputs=(
+                f"Fetch or configure `{base_ref}` before rerunning release dispatch.",
+                "Rerun the dispatch phase from a branch that can be compared to the release base.",
+            ),
+            metadata={
+                "guard": "release_dispatch",
+                "reason": "base_ref_unavailable",
+                "plan": str(plan),
+                **sync,
+            },
+        )
+    if sync["head"] != sync["base_commit"]:
+        return ReleaseDispatchBlocker(
+            blocker_class="branch_sync_conflict",
+            blocker_summary=(
+                f"Release dispatch requires `HEAD` to match `{base_ref}` before the "
+                "external workflow is started."
+            ),
+            required_human_inputs=(
+                f"Merge or sync the release branch so `HEAD` matches `{base_ref}`.",
+                "Rerun the dispatch phase from the clean synced branch.",
+            ),
+            metadata={
+                "guard": "release_dispatch",
+                "reason": "head_not_at_base_ref",
+                "plan": str(plan),
+                **sync,
+            },
+        )
+    return None
+
+
+def _release_base_ref(metadata: dict[str, str]) -> tuple[str, bool]:
+    for key in ("release_base_ref", "phase_loop_release_base_ref"):
+        value = metadata.get(key)
+        if value:
+            return value, True
+    return "origin/main", False
+
+
+def _dirty_release_affecting_paths(repo: Path) -> list[str]:
+    try:
+        status = subprocess.check_output(
+            ["git", "-C", str(repo), "status", "--porcelain", "--untracked-files=all"],
+            text=True,
+        )
+    except Exception:
+        return []
+    paths: list[str] = []
+    for line in status.splitlines():
+        if not line:
+            continue
+        path = _status_path(line)
+        if path and _is_release_affecting_path(path):
+            paths.append(path)
+    return sorted(dict.fromkeys(paths))
+
+
+def _status_path(line: str) -> str:
+    path = line[3:] if len(line) > 3 else ""
+    if " -> " in path:
+        path = path.split(" -> ", 1)[1]
+    return path.strip().strip('"')
+
+
+def _is_release_affecting_path(path: str) -> bool:
+    normalized = path.replace("\\", "/")
+    return any(fnmatch.fnmatchcase(normalized, pattern) for pattern in RELEASE_AFFECTING_PATTERNS)
+
+
+def _branch_sync(repo: Path, base_ref: str) -> dict[str, Any]:
+    head = _git(repo, "rev-parse", "HEAD")
+    base_commit = _git(repo, "rev-parse", "--verify", f"{base_ref}^{{commit}}")
+    remote = base_ref.split("/", 1)[0] if "/" in base_ref else ""
+    return {
+        "base_ref": base_ref,
+        "base_available": bool(base_commit),
+        "base_remote_available": bool(remote and _git(repo, "remote", "get-url", remote)),
+        "head": _short_sha(head),
+        "base_commit": _short_sha(base_commit),
+    }
+
+
+def _git(repo: Path, *args: str) -> str:
+    try:
+        return subprocess.check_output(["git", "-C", str(repo), *args], text=True, stderr=subprocess.DEVNULL).strip()
+    except Exception:
+        return ""
+
+
+def _short_sha(value: str) -> str:
+    return value[:12] if value else ""