jearless 0.10.4__py3-none-any.whl

jearless/__init__.py

@@ -0,0 +1,12 @@
+"""jearless — Fearless. Jearless. Task tracking and a changelog on bare git."""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _package_version
+
+# The version is DERIVED from package metadata (which pyproject feeds, which the
+# hook mirrors) — a hardcoded third copy here would drift, and did (0.1.0 in the
+# wheel while the flow lived at 0.10.4). One authored source, everything else derives.
+try:
+    __version__ = _package_version("jearless")
+except PackageNotFoundError:  # running from a bare source tree, not installed
+    __version__ = "0.0.0"

jearless/add.py

@@ -0,0 +1,122 @@
+"""add: append a task to the eternal registry — the one sanctioned YAML write.
+
+The duplicate guard (task tooling/10) watches the door: on high keyword
+overlap with existing summaries it lists the look-alikes and demands
+confirmation. The most common duplicate in nature is a re-suggested DONE
+task — hence the derived state next to each match.
+"""
+
+import re
+import sys
+from pathlib import Path
+
+from ruamel.yaml import YAML
+
+from jearless import config, duplicate, gitwrap, registry, state
+from jearless.errors import JearlessError
+from jearless.registry import REGISTRY_NAME
+
+# Project names live in branch names: lowercase latin, digits, underscores.
+PROJECT_RE = re.compile(r"^[a-z0-9_]+$")
+
+# The header a newborn registry is born with — the same covenant comment as the seeded one.
+_TEMPLATE = """\
+# The eternal jearless task registry (README: frozen facts only, no live state).
+# Status is never stored: available = here without a branch; in_progress = a branch
+# on origin; done = a merge commit in main.
+tasks: {}
+"""
+
+
+def _max_from_archives(cwd: Path, project: str) -> int:
+    best = 0
+    for path in sorted(cwd.glob("archive_*.yml")):
+        best = max(best, registry.load_path(path).max_id(project))
+    return best
+
+
+def _max_from_branches(cwd: Path, cfg: config.Config, project: str, remote: str) -> int | None:
+    """None means origin is unreachable: the id is then based on the registry only."""
+    try:
+        heads = gitwrap.remote_heads(cwd, remote)
+    except gitwrap.GitError:
+        return None
+    best = 0
+    for name in heads:
+        m = cfg.match_branch(name)
+        if m and m.group("project") == project:
+            best = max(best, int(m.group("num")))
+    return best
+
+
+def _states(cwd: Path, cfg: config.Config, remote: str) -> dict[tuple[str, int], str]:
+    """Derived states for the warning; an unreachable origin simply drops the annotation."""
+    try:
+        gitwrap.run(["fetch", "--quiet", remote], cwd)
+        view = state.compute(cwd, cfg, registry.load(cwd), remote)
+    except (gitwrap.GitError, JearlessError):
+        return {}
+    return {(tv.task.project, tv.task.id): tv.state for tv in view.tasks}
+
+
+def _guard(cwd: Path, cfg: config.Config, summary: str, remote: str, yes: bool) -> None:
+    if yes:
+        return
+    matches = duplicate.find_similar(registry.load_all(cwd), summary, cfg.duplicate_threshold)
+    if not matches:
+        return
+    states = _states(cwd, cfg, remote)
+    print("warning: similar tasks exist:")
+    for m in matches:
+        derived = states.get((m.task.project, m.task.id))
+        tag = f" ({derived})" if derived else ""
+        print(f"  {m.task.project}/{m.task.id}{tag}: {m.task.summary} — {round(m.score * 100)}%")
+    if not sys.stdin.isatty():
+        raise JearlessError("declined: no terminal to confirm — re-run with --yes to force")
+    if input("Are you sure to add? [y/N] ").strip().lower() not in ("y", "yes"):
+        raise JearlessError("declined — the registry is untouched")
+
+
+def add(
+    cwd: Path,
+    project: str,
+    summary: str,
+    points: int | None = None,
+    remote: str = "origin",
+    yes: bool = False,
+) -> int:
+    if not PROJECT_RE.match(project):
+        raise JearlessError("project names are [a-z0-9_]: they live in branch names")
+    summary = summary.strip()
+    if not summary:
+        raise JearlessError("summary must not be empty")
+
+    cfg = config.load(cwd)
+    _guard(cwd, cfg, summary, remote, yes)
+    candidates = [registry.load(cwd).max_id(project), _max_from_archives(cwd, project)]
+    from_branches = _max_from_branches(cwd, cfg, project, remote)
+    if from_branches is not None:
+        candidates.append(from_branches)
+    else:
+        print(
+            f"jear: cannot reach '{remote}' — next id checked against the registry only",
+            file=sys.stderr,
+        )
+    next_id = max(candidates) + 1
+
+    path = cwd / REGISTRY_NAME
+    yaml = YAML(typ="rt")  # round-trip: comments survive the append
+    yaml.indent(mapping=2, sequence=4, offset=2)
+    yaml.width = 100000  # never wrap a long summary
+    data = yaml.load(path) if path.exists() else None
+    if data is None:
+        data = yaml.load(_TEMPLATE)
+    if not isinstance(data, dict):
+        raise JearlessError(f"{REGISTRY_NAME}: expected a mapping at the top level")
+    entry: dict = {"id": next_id, "summary": summary}
+    if points is not None:
+        entry["story_points"] = points
+    data.setdefault("tasks", {}).setdefault(project, []).append(entry)
+    yaml.dump(data, path)
+    print(f"task {project}/{next_id} added — commit tasks.yml to main")
+    return next_id

jearless/changelog.py

@@ -0,0 +1,81 @@
+"""changelog: derived from merge commits between refs — printed, never stored (README).
+
+Dry-run is the only mode: writing files is the release step's business (task tooling/9).
+"""
+
+from pathlib import Path
+
+from jearless import config, gitwrap, registry, state
+from jearless.errors import JearlessError
+
+_UNRELEASED = "Unreleased"
+
+
+def _summary_for(reg: registry.Registry, project: str, num: int, slug: str | None) -> str:
+    """The registry (union with archives) first; the branch slug is the fallback (README)."""
+    for task in reg.tasks.get(project, []):
+        if task.id == num:
+            return task.summary
+    return (slug or "task").replace("-", " ")
+
+
+def _entries_from_history(
+    cwd: Path, cfg: config.Config, reg: registry.Registry, rev_range: str
+) -> tuple[dict[str, list[tuple[tuple[str, int], str]]], int]:
+    sections: dict[str, list[tuple[tuple[str, int], str]]] = {}
+    skipped = 0
+    subjects = gitwrap.lines(["log", rev_range, "--merges", "--format=%s"], cwd)
+    for subject in subjects:
+        branch = state.branch_from_merge_subject(subject)
+        m = cfg.match_branch(branch) if branch else None
+        if not m:
+            skipped += 1  # off-taxonomy merge: the visible hole, counted aloud
+            continue
+        project, num = m.group("project"), int(m.group("num"))
+        summary = _summary_for(reg, project, num, m.group("slug"))
+        line = cfg.line_template.format(
+            type=m.group("type"),
+            project=project,
+            num=num,
+            slug=m.group("slug") or "",
+            summary=summary,
+        )
+        sections.setdefault(m.group("type"), []).append(((project, num), line))
+    return sections, skipped
+
+
+def render(
+    cwd: Path, from_tag: str | None = None, to_tag: str | None = None, header: str | None = None
+) -> str:
+    """The changelog as text; `header` overrides the section title (used by release)."""
+    cfg = config.load(cwd)
+    reg = registry.load_all(cwd)
+    to_ref = to_tag or "HEAD"
+    rev_range = f"{from_tag}..{to_ref}" if from_tag else to_ref
+    try:
+        sections, skipped = _entries_from_history(cwd, cfg, reg, rev_range)
+        date = gitwrap.out(["log", "-1", "--format=%cd", "--date=short", to_ref], cwd)
+    except gitwrap.GitError as exc:
+        raise JearlessError(f"cannot read history {rev_range}: {exc}") from exc
+
+    lines = ["# Changelog"]
+    title = header or to_tag or _UNRELEASED
+    lines.append(f"## {title} ({date})" if date else f"## {title}")
+    for prefix, section_title in cfg.sections.items():
+        entries = sorted(sections.pop(prefix, []))
+        if not entries:
+            continue
+        lines.append(f"### {section_title}")
+        lines.extend(f"- {line}" for _, line in entries)
+    others = sorted((key, line) for entries in sections.values() for key, line in entries)
+    if others:
+        lines.append("### Other")
+        lines.extend(f"- {line}" for _, line in others)
+    if skipped:
+        lines.append(f"# {skipped} off-taxonomy merge(s) skipped — the visible hole (README)")
+    return "\n".join(lines) + "\n"
+
+
+def run(cwd: Path, from_tag: str | None = None, to_tag: str | None = None) -> int:
+    print(render(cwd, from_tag=from_tag, to_tag=to_tag), end="")
+    return 0

jearless/cli.py

@@ -0,0 +1,107 @@
+"""The CLI frame: subcommands per PLAN.md, phases 1-4.
+
+In Phase 0 the subcommands are stubs, but empty states are handled by the
+live modules, without crashing (Phase 0 DoD).
+"""
+
+import argparse
+import sys
+from pathlib import Path
+
+from jearless import __version__
+from jearless import add as add_mod
+from jearless import changelog as changelog_mod
+from jearless import doctor as doctor_mod
+from jearless import release as release_mod
+from jearless import retro as retro_mod
+from jearless import sprint as sprint_mod
+from jearless import take as take_mod
+from jearless import timeline as timeline_mod
+from jearless.errors import JearlessError
+
+PHASES = {
+    "add": 1,
+    "take": 1,
+    "sprint": 1,
+    "changelog": 2,
+    "doctor": 2,
+    "timeline": 3,
+    "retro": 3,
+    "archive": 4,
+}
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="jear",
+        description="Fearless. Jira-less. Task tracking and changelog on bare git.",
+    )
+    parser.add_argument("--version", action="version", version=f"jearless {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True, metavar="COMMAND")
+
+    p = sub.add_parser("add", help="add a task to the registry (Phase 1)")
+    p.add_argument("project")
+    p.add_argument("summary")
+    p.add_argument("--points", type=int, default=None)
+    p.add_argument("--yes", action="store_true", help="skip the duplicate guard")
+
+    p = sub.add_parser("take", help="take a task: branch + push (Phase 1)")
+    p.add_argument("project")
+    p.add_argument("id", type=int)
+
+    sub.add_parser("sprint", help="sprint: registry × branches × merge log join (Phase 1)")
+
+    p = sub.add_parser(
+        "changelog", help="changelog from merge commits (Phase 2); dry-run is the only mode"
+    )
+    p.add_argument("--from", dest="from_tag", default=None, metavar="TAG")
+    p.add_argument("--to", dest="to_tag", default=None, metavar="TAG")
+    p.add_argument("--dry-run", action="store_true", help="accepted for symmetry; always dry")
+
+    sub.add_parser("doctor", help="diagnostics: unattributed commits etc. (Phase 2)")
+
+    p = sub.add_parser("timeline", help="actual timeline, mermaid (Phase 3)")
+    group = p.add_mutually_exclusive_group()
+    group.add_argument("--live", action="store_true")
+    group.add_argument("--snapshot", metavar="TAG")
+
+    p = sub.add_parser("retro", help="plan versus actual (Phase 3)")
+    p.add_argument("plan")
+
+    p = sub.add_parser(
+        "release", help="tag + changelog + timeline snapshot in one move (task tooling/9)"
+    )
+    p.add_argument("--tag", default=None, metavar="TAG")
+
+    sub.add_parser("archive", help="move done tasks out (Phase 4, on trigger)")
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    cwd = Path.cwd()
+    try:
+        if args.command == "add":
+            add_mod.add(cwd, args.project, args.summary, args.points, yes=args.yes)
+            return 0
+        if args.command == "take":
+            print(take_mod.take(cwd, args.project, args.id))
+            return 0
+        if args.command == "sprint":
+            return sprint_mod.run(cwd)
+        if args.command == "changelog":
+            return changelog_mod.run(cwd, from_tag=args.from_tag, to_tag=args.to_tag)
+        if args.command == "doctor":
+            return doctor_mod.run(cwd)
+        if args.command == "timeline":
+            return timeline_mod.run(cwd, snapshot=args.snapshot)
+        if args.command == "retro":
+            return retro_mod.run(cwd, Path(args.plan))
+        if args.command == "release":
+            return release_mod.run(cwd, tag=args.tag)
+        print(f"not implemented (Phase {PHASES[args.command]}) — see PLAN.md")
+        return 0
+    except JearlessError as exc:
+        print(f"jear: {exc}", file=sys.stderr)
+        return 1

jearless/config.py

@@ -0,0 +1,69 @@
+"""The .jearless.toml config: the branch regex, the changelog line template, sections."""
+
+import re
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+
+from jearless.errors import JearlessError
+
+CONFIG_NAME = ".jearless.toml"
+
+# Slashes are the structural separators: type/project/number-slug (README).
+DEFAULT_BRANCH_PATTERN = (
+    r"^(?P<type>[a-z]+)/(?P<project>[a-z0-9_]+)/(?P<num>\d+)(?:-(?P<slug>[a-z0-9-]+))?$"
+)
+REQUIRED_GROUPS = ("type", "project", "num")
+DEFAULT_SECTIONS = {"feature": "Added", "fix": "Fixed"}
+DEFAULT_LINE_TEMPLATE = "{project}-{num}: {summary}"
+DEFAULT_DUPLICATE_THRESHOLD = 0.6
+
+
+class ConfigError(JearlessError):
+    """The config exists but is invalid."""
+
+
+@dataclass(frozen=True)
+class Config:
+    branch_pattern: re.Pattern
+    sections: dict[str, str]
+    line_template: str
+    duplicate_threshold: float = DEFAULT_DUPLICATE_THRESHOLD
+
+    def match_branch(self, name: str) -> re.Match | None:
+        return self.branch_pattern.match(name)
+
+
+def _compile_branch_pattern(pattern: str) -> re.Pattern:
+    try:
+        compiled = re.compile(pattern)
+    except re.error as exc:
+        raise ConfigError(f"branch regex does not compile: {exc}") from exc
+    missing = [g for g in REQUIRED_GROUPS if g not in compiled.groupindex]
+    if missing:
+        raise ConfigError(f"branch regex misses named groups: {', '.join(missing)}")
+    return compiled
+
+
+def load(cwd: Path) -> Config:
+    """A missing .jearless.toml is not an error: defaults apply."""
+    path = cwd / CONFIG_NAME
+    data: dict = {}
+    if path.exists():
+        try:
+            data = tomllib.loads(path.read_text(encoding="utf-8"))
+        except tomllib.TOMLDecodeError as exc:
+            raise ConfigError(f"{CONFIG_NAME}: {exc}") from exc
+    branch = data.get("branch", {})
+    changelog = data.get("changelog", {})
+    duplicate = data.get("duplicate", {})
+    threshold = duplicate.get("threshold", DEFAULT_DUPLICATE_THRESHOLD)
+    if not isinstance(threshold, (int, float)) or not 0 < threshold <= 1:
+        raise ConfigError("[duplicate] threshold must be a number in (0, 1]")
+    sections = {**DEFAULT_SECTIONS, **changelog.get("sections", {})}
+    return Config(
+        branch_pattern=_compile_branch_pattern(branch.get("pattern", DEFAULT_BRANCH_PATTERN)),
+        sections=sections,
+        line_template=changelog.get("line_template", DEFAULT_LINE_TEMPLATE),
+        duplicate_threshold=float(threshold),
+    )

jearless/doctor.py

@@ -0,0 +1,83 @@
+"""doctor: the visible hole — unattributed commits, naming violations, a sick registry.
+
+The audit walks the first-parent chain of main: a commit there is attributed
+when it is a merge (the branch name is the key) or touches nothing but
+sanctioned artifacts — the registry, the changelog, timeline snapshots (README).
+Commits that arrived inside a --no-ff merge hang off second parents and are
+attributed by that merge. Everything else on the chain is a hole: a squash,
+a fast-forward or plain drift.
+"""
+
+from pathlib import Path
+
+from jearless import config, gitwrap, registry
+from jearless.gitwrap import GitError
+from jearless.registry import REGISTRY_NAME, RegistryError
+
+
+def _check_registry(cwd: Path, findings: list[str]) -> None:
+    try:
+        registry.load(cwd)
+    except RegistryError as exc:
+        findings.append(f"registry: {exc}")
+
+
+def _check_branches(cwd: Path, cfg: config.Config, findings: list[str], remote: str) -> None:
+    try:
+        heads = gitwrap.remote_heads(cwd, remote)
+    except GitError:
+        findings.append(f"{remote}: unreachable — branch checks skipped")
+        return
+    known = set(cfg.sections) | {"chore"}
+    for name in heads:
+        prefix = name.split("/", 1)[0]
+        if prefix in known and not cfg.match_branch(name):
+            findings.append(f"branch: '{name}' starts like a task branch but misses the pattern")
+
+
+# Sanctioned artifacts: bookkeeping, not task work. env.yml version bumps
+# normally ride branches via the hook; a direct one is human bookkeeping.
+_SANCTIONED_EXACT = frozenset({REGISTRY_NAME, "CHANGELOG.md", "env.yml"})
+_SANCTIONED_PREFIXES = ("archive_", "snapshots/")
+
+
+def _is_sanctioned_edit(cwd: Path, sha: str) -> bool:
+    files = gitwrap.lines(["diff-tree", "--no-commit-id", "--name-only", "-r", "--root", sha], cwd)
+    return all(
+        f in _SANCTIONED_EXACT or f.startswith(_SANCTIONED_PREFIXES) for f in files
+    )
+
+
+def _check_unattributed(cwd: Path, findings: list[str], remote: str) -> None:
+    ref = f"{remote}/main"
+    try:
+        # first-parent only: WIP that arrived inside a --no-ff merge is attributed
+        # by that merge, not audited on its own
+        log = gitwrap.out(["log", "--first-parent", ref, "--format=%H%x1f%P%x1f%s"], cwd)
+    except GitError:
+        findings.append(f"main: no {ref} — nothing to audit yet")
+        return
+    for line in log.splitlines():
+        if not line.strip():
+            continue
+        sha, parents, subject = line.split("\x1f", 2)
+        if len(parents.split()) > 1:
+            continue  # a merge: attributed by its branch name
+        if _is_sanctioned_edit(cwd, sha):
+            continue  # a sanctioned human edit: a task, the changelog, a snapshot
+        findings.append(
+            f"main: unattributed commit {sha[:7]} \"{subject}\" "
+            f"(not a merge, not a registry edit) — squash or fast-forward suspected"
+        )
+
+
+def run(cwd: Path, remote: str = "origin") -> int:
+    findings: list[str] = []
+    _check_registry(cwd, findings)
+    cfg = config.load(cwd)
+    _check_branches(cwd, cfg, findings, remote)
+    _check_unattributed(cwd, findings, remote)
+    for line in findings:
+        print(line)
+    print(f"doctor: {len(findings)} finding(s)")
+    return 1 if findings else 0

jearless/duplicate.py

@@ -0,0 +1,86 @@
+"""The duplicate guard (task tooling/10): cheap keyword overlap with mini-IDF.
+
+Simple means by charter: tokenize, weight each word by its scarcity across the
+registry's own summaries, score with weighted Jaccard corrected by containment.
+No stemming frameworks, no edit distance — a duplicate is the same words in a
+different order, and reordering is not the enemy.
+"""
+
+import re
+from dataclasses import dataclass
+
+from jearless import registry
+
+_STOPWORDS = frozenset(
+    [
+        "a", "an", "and", "are", "as", "at", "be", "but", "by", "for", "from",
+        "has", "have", "in", "into", "is", "it", "its", "of", "on", "or",
+        "the", "this", "to", "with", "you", "your",
+    ]
+)
+_WORD_RE = re.compile(r"[a-z0-9]+")
+
+
+def tokenize(summary: str) -> list[str]:
+    """Lowercase alphanumeric runs minus stopwords; a naive plural strip.
+
+    The strip misses branch/branches-class pairs — acceptable for a guard:
+    it is a net, not a wall, and misses cost nothing while false alarms cost
+    a confirmation each.
+    """
+    words: list[str] = []
+    for raw in _WORD_RE.findall(summary.lower()):
+        if raw in _STOPWORDS:
+            continue
+        if len(raw) > 3 and raw.endswith("s") and not raw.endswith("ss"):
+            raw = raw[:-1]  # tasks → task; class stays class
+        words.append(raw)
+    return words
+
+
+def _weights(summaries: list[str]) -> dict[str, float]:
+    """Mini-IDF: a word occurring in many summaries weighs almost nothing.
+
+    This is the whole defense against domain noise: "task" and "registry" are
+    in half of our summaries and must not trigger matches on their own.
+    """
+    df: dict[str, int] = {}
+    for summary in summaries:
+        for word in set(tokenize(summary)):
+            df[word] = df.get(word, 0) + 1
+    return {word: 1.0 / n for word, n in df.items()}
+
+
+@dataclass(frozen=True)
+class Match:
+    task: registry.Task
+    score: float  # 0..1
+
+
+def _score(new: set[str], old: set[str], weights: dict[str, float]) -> float:
+    def weight(word: str) -> float:
+        return weights.get(word, 1.0)  # an unseen word is maximally informative
+
+    union = new | old
+    if not union:
+        return 0.0
+    shared = new & old
+    jaccard = sum(weight(w) for w in shared) / sum(weight(w) for w in union)
+    denom = min(sum(weight(w) for w in new), sum(weight(w) for w in old))
+    containment = sum(weight(w) for w in shared) / denom if denom else 0.0
+    # containment guards the common duplicate: a short summary inside a long one
+    return max(jaccard, containment)
+
+
+def find_similar(
+    reg: registry.Registry, summary: str, threshold: float, limit: int = 3
+) -> list[Match]:
+    """Existing tasks whose summaries overlap above the threshold, best first."""
+    new = set(tokenize(summary))
+    weights = _weights([t.summary for t in reg.all()])
+    matches: list[Match] = []
+    for task in reg.all():
+        score = _score(new, set(tokenize(task.summary)), weights)
+        if score >= threshold:
+            matches.append(Match(task, score))
+    return sorted(matches, key=lambda m: m.score, reverse=True)[:limit]

jearless/errors.py

@@ -0,0 +1,5 @@
+"""The base error: reaches the user as a single line, without a traceback."""
+
+
+class JearlessError(RuntimeError):
+    """Parent of all jearless errors — the CLI catches it and prints it briefly."""

jearless/gitwrap.py

@@ -0,0 +1,69 @@
+"""Git via subprocess: no intermediary libraries, all flags in plain sight.
+
+Rationale in PLAN.md: jearless is about the precise semantics of git,
+so git calls must not be hidden behind wrappers like GitPython.
+"""
+
+import os
+import subprocess
+from pathlib import Path
+
+from jearless.errors import JearlessError
+
+
+class GitError(JearlessError):
+    """git exited with a non-zero code."""
+
+
+def _git(args: list[str], cwd: Path, env: dict[str, str] | None = None) -> subprocess.CompletedProcess:
+    return subprocess.run(
+        ["git", *args],
+        cwd=cwd,
+        capture_output=True,
+        encoding="utf-8",
+        errors="replace",
+        check=False,
+        env={**os.environ, **env} if env else None,
+    )
+
+
+def run(
+    args: list[str], cwd: Path, env: dict[str, str] | None = None
+) -> subprocess.CompletedProcess:
+    """Run git; on failure raise GitError with stderr as a single line."""
+    proc = _git(args, cwd, env)
+    if proc.returncode != 0:
+        detail = proc.stderr.strip() or proc.stdout.strip()
+        raise GitError(f"git {' '.join(args)}: {detail}")
+    return proc
+
+
+def out(args: list[str], cwd: Path) -> str:
+    return run(args, cwd).stdout.strip()
+
+
+def lines(args: list[str], cwd: Path) -> list[str]:
+    return [ln for ln in run(args, cwd).stdout.splitlines() if ln.strip()]
+
+
+def is_repo(cwd: Path) -> bool:
+    proc = _git(["rev-parse", "--is-inside-work-tree"], cwd)
+    return proc.returncode == 0 and proc.stdout.strip() == "true"
+
+
+def has_commits(cwd: Path) -> bool:
+    """A fresh `git init` is a repository without commits: a Phase 0 empty state."""
+    proc = _git(["rev-parse", "--verify", "--quiet", "HEAD"], cwd)
+    return proc.returncode == 0
+
+
+def remote_heads(cwd: Path, remote: str = "origin", pattern: str | None = None) -> dict[str, str]:
+    """Branches on the remote — the source of truth about occupancy (README), not a cache."""
+    args = ["ls-remote", "--heads", remote]
+    if pattern:
+        args.append(pattern)
+    heads: dict[str, str] = {}
+    for ln in lines(args, cwd):
+        sha, _, ref = ln.partition("\t")
+        heads[ref.removeprefix("refs/heads/")] = sha
+    return heads