cctally 1.8.2 → 1.9.0

package/bin/cctally

@@ -43,19 +43,6 @@ if sys.version_info < __min_python_version__:
 if __name__ == "__main__":
     sys.modules.setdefault("cctally", sys.modules["__main__"])
 
-# Bind `cctally` as a local alias for sibling-back-reference patterns within
-# this module. STAYING release helpers (e.g. `_release_run_phase_stamp`) call
-# MOVED helpers (e.g. `_release_stamp_changelog` in `_cctally_release.py`)
-# via `cctally.<name>(...)`. Attribute access on the module object triggers
-# PEP 562 `__getattr__`, which lazy-loads `_cctally_release` and splices the
-# whole symbol set into this module's globals on first hit. Subsequent
-# accesses bypass `__getattr__` (normal dict lookup wins). Spec §5.5.
-#
-# Falls back to the current module if `cctally` isn't yet registered (e.g.
-# under unusual loaders); the binding is then a self-reference, which is
-# harmless because the same lookup-then-PEP562 chain applies.
-cctally = sys.modules.get("cctally") or sys.modules[__name__]
-
 import argparse
 import bisect
 import contextlib
@@ -170,7 +157,6 @@ SETUP_SYMLINK_NAMES = (
     "cctally-forecast",
     "cctally-project",
     "cctally-refresh-usage",
-    "cctally-release",
     "cctally-sync-week",
     "cctally-tui",
     "cctally-update",
@@ -202,12 +188,10 @@ PUBLIC_REPO = "omrikais/cctally"
 
 # === Eager-loaded library siblings ===
 #
-# Re-export pure-fn primitives from _lib_*.py so test/harness code that
-# reaches into cctally._release_parse_semver, cctally._SEMVER_RE, etc.
-# continues to work via the same attribute path. The actual definitions
-# live in the sibling modules; bin/cctally's namespace simply re-aliases
-# them. Eager because these are touched by code defined later in this
-# file (e.g. RELEASE_HEADER_RE uses _SEMVER_NUM).
+# Re-export pure-fn primitives from _lib_*.py so code defined later in
+# this file (e.g. RELEASE_HEADER_RE uses _SEMVER_NUM) can reach them via
+# the cctally module namespace. The actual definitions live in the
+# sibling modules; bin/cctally's namespace simply re-aliases them.
 #
 # Spec: docs/superpowers/specs/2026-05-13-bin-cctally-split-design.md §6.3-6.4
 
@@ -220,8 +204,6 @@ _cctally_core = _load_sibling("_cctally_core")
 # Eager re-exports for the 24 kernel symbols. Preserves
 # `cctally.<name>` attribute access AND `ns["<name>"]` dict-subscript
 # paths used heavily by tests (e.g. ns["open_db"]() in 125+ sites).
-# Don't add to PEP 562 __getattr__ registry — eager binding is the
-# whole point.
 eprint = _cctally_core.eprint
 now_utc_iso = _cctally_core.now_utc_iso
 parse_iso_datetime = _cctally_core.parse_iso_datetime
@@ -251,10 +233,6 @@ get_latest_usage_for_week = _cctally_core.get_latest_usage_for_week
 _lib_semver = _load_sibling("_lib_semver")
 _SEMVER_NUM = _lib_semver._SEMVER_NUM
 _SEMVER_RE = _lib_semver._SEMVER_RE
-_release_parse_semver = _lib_semver._release_parse_semver
-_release_format_semver = _lib_semver._release_format_semver
-_release_compute_next_version = _lib_semver._release_compute_next_version
-_release_semver_sort_key = _lib_semver._release_semver_sort_key
 
 _lib_pricing = _load_sibling("_lib_pricing")
 TIERED_THRESHOLD = _lib_pricing.TIERED_THRESHOLD
@@ -329,6 +307,17 @@ _aggregate_block = _lib_blocks._aggregate_block
 _build_activity_block = _lib_blocks._build_activity_block
 _blocks_to_json = _lib_blocks._blocks_to_json
 
+_lib_changelog = _load_sibling("_lib_changelog")
+# Backward-compat re-export: callers and tests reach the helper through
+# ``cctally._release_read_latest_release_version`` (incl. monkeypatch
+# sites in tests/test_release_internals.py + tests/test_update.py and
+# the ``_cctally()._release_read_latest_release_version()`` call in
+# bin/_cctally_release.py). The canonical name is
+# ``_read_latest_changelog_version`` on _lib_changelog; the alias keeps
+# the historical cctally-namespace name reachable for the monkeypatch
+# surface those tests depend on.
+_release_read_latest_release_version = _lib_changelog._read_latest_changelog_version
+
 _lib_aggregators = _load_sibling("_lib_aggregators")
 BucketUsage = _lib_aggregators.BucketUsage
 CodexBucketUsage = _lib_aggregators.CodexBucketUsage
@@ -400,13 +389,11 @@ _render_five_hour_blocks_table = _lib_render._render_five_hour_blocks_table
 
 # Eager re-export of bin/_cctally_setup.py (lazy I/O sibling that loads
 # at startup to keep `ns["cmd_setup"](...)` / `ns["_setup_X"](...)`
-# direct-dict test patterns working — PEP 562 `__getattr__` only fires
-# on module-attribute access, not dict-key access on `mod.__dict__`,
-# which is how `tests/test_setup_legacy_migrate.py` reaches in via the
-# `ns = load_script()` fixture. Spec §4.8 explicitly contemplates this
-# "partially-pre-imported lazy module" form for the rare case where
-# tests bypass PEP 562. Same pattern as Phase A `_lib_*` modules; no
-# entry in `_LAZY_MODULES` below.
+# direct-dict test patterns working — dict-key access on `mod.__dict__`
+# (the form tests/test_setup_legacy_migrate.py uses via the
+# `ns = load_script()` fixture) bypasses any module-level `__getattr__`.
+# Eager binding here makes the symbols visible on the dict regardless
+# of how callers reach them. Same pattern as the `_lib_*` modules above.
 _cctally_setup = _load_sibling("_cctally_setup")
 _settings_merge_install = _cctally_setup._settings_merge_install
 _settings_merge_uninstall = _cctally_setup._settings_merge_uninstall
@@ -803,73 +790,6 @@ DashboardHTTPHandler = _cctally_dashboard.DashboardHTTPHandler
 cmd_dashboard = _cctally_dashboard.cmd_dashboard
 
 
-# === Lazy-loaded library siblings (PEP 562 registry) ===
-#
-# Tests reach into cctally's namespace for private symbols via
-# SourceFileLoader (e.g. cctally._release_phase_stamp_done). When those
-# symbols live in lazy I/O modules (_cctally_*.py), Python's
-# module-level __getattr__ resolves them on first access by importing
-# the owning module and splicing its whole symbol surface into
-# bin/cctally's globals. Subsequent accesses skip __getattr__ entirely.
-#
-# Spec: docs/superpowers/specs/2026-05-13-bin-cctally-split-design.md §4
-
-_LAZY_MODULES: dict[str, list[str]] = {
-    "_cctally_release": [
-        "_FORMULA_VERSION_RE",
-        "_RELEASE_NPM_POLL_INTERVAL_S_DEFAULT",
-        "_RELEASE_NPM_POLL_TIMEOUT_S_DEFAULT",
-        "_homebrew_template_path",
-        "_package_json_path",
-        "_release_brew_archive_url",
-        "_release_canonical_body",
-        "_release_compute_brew_sha256",
-        "_release_dry_run",
-        "_release_extract_formula_version",
-        "_release_npm_poll_timing",
-        "_release_parse_changelog",
-        "_release_preflight_tag_clobber",
-        "_release_print_gh_fallback",
-        "_release_stamp_changelog",
-        "_release_stamp_package_json",
-        "cmd_release",
-    ],
-}
-
-# Inverted lookup: symbol -> module name. Built at module load with a
-# collision assertion so two modules can't accidentally claim the same name.
-_LAZY_NAME_TO_MODULE: dict[str, str] = {}
-for _mod_name, _names in _LAZY_MODULES.items():
-    for _n in _names:
-        assert _n not in _LAZY_NAME_TO_MODULE, (
-            f"PEP 562 registry collision: {_n!r} claimed by both "
-            f"{_LAZY_NAME_TO_MODULE.get(_n)!r} and {_mod_name!r}"
-        )
-        _LAZY_NAME_TO_MODULE[_n] = _mod_name
-
-
-def __getattr__(name: str):  # PEP 562
-    """Lazy-load a registered sibling module on first attribute access.
-
-    Tests do `cctally._release_phase_stamp_done(...)` and similar; this
-    function fires, imports the owning module via _load_sibling, splices
-    every symbol the registry claims for that module into globals(), and
-    returns the requested attribute. Subsequent attribute accesses on
-    cctally.X find the symbol directly in globals — no __getattr__ trip.
-
-    Spec: docs/superpowers/specs/2026-05-13-bin-cctally-split-design.md §4.2
-    """
-    mod_name = _LAZY_NAME_TO_MODULE.get(name)
-    if mod_name is None:
-        raise AttributeError(
-            f"module {__name__!r} has no attribute {name!r}"
-        )
-    mod = _load_sibling(mod_name)
-    for n in _LAZY_MODULES[mod_name]:
-        globals()[n] = getattr(mod, n)
-    return globals()[name]
-
-
 RELEASE_HEADER_RE = re.compile(
     rf'^## \[({_SEMVER_NUM}\.{_SEMVER_NUM}\.{_SEMVER_NUM}'
     rf'(?:-[a-zA-Z][a-zA-Z0-9-]*\.{_SEMVER_NUM})?)\] - (\d{{4}}-\d{{2}}-\d{{2}})\s*$',
@@ -879,1284 +799,11 @@ RELEASE_HEADER_RE = re.compile(
 RELEASE_SUBSECTION_ORDER = ("Added", "Changed", "Deprecated", "Removed", "Fixed", "Security")
 
 
-def _release_read_latest_release_version() -> tuple[str, str] | None:
-    """Read latest `## [X.Y.Z] - YYYY-MM-DD` header. Returns (version, date) or None."""
-    try:
-        text = CHANGELOG_PATH.read_text(encoding="utf-8")
-    except FileNotFoundError:
-        return None
-    m = RELEASE_HEADER_RE.search(text)
-    if not m:
-        return None
-    return (m.group(1), m.group(2))
-
-
-def _release_preflight_branch(allow_branch: str | None) -> None:
-    """Refuse unless on main or --allow-branch matches.
-
-    Spec §10.1 step 2: branch check fires for both real runs and --dry-run
-    (a dry-run on the wrong branch would mislead).
-    """
-    branch = subprocess.check_output(
-        ["git", "rev-parse", "--abbrev-ref", "HEAD"],
-        text=True,
-        cwd=str(CHANGELOG_PATH.parent),
-    ).strip()
-    expected = allow_branch if allow_branch else "main"
-    if branch != expected:
-        if allow_branch:
-            print(
-                f"release: refusing to cut from {branch}; allow-branch was {allow_branch}",
-                file=sys.stderr,
-            )
-        else:
-            print(
-                f"release: refusing to cut from {branch}; "
-                f"use --allow-branch {branch} if intentional",
-                file=sys.stderr,
-            )
-        sys.exit(2)
-
-
-def _release_preflight_clean_tree() -> None:
-    """Refuse if working tree is dirty (spec §10.1 step 3)."""
-    out = subprocess.check_output(
-        ["git", "status", "--porcelain"],
-        text=True,
-        cwd=str(CHANGELOG_PATH.parent),
-    )
-    if out.strip():
-        print("release: working tree dirty; commit or stash first", file=sys.stderr)
-        sys.exit(2)
-
-
-def _release_preflight_up_to_date(remote: str) -> None:
-    """Refuse if local branch is behind <remote>/<branch>; local-ahead OK.
-
-    Spec §10.1 step 4. Network failure is non-fatal — operator can re-run
-    with --resume after fixing connectivity.
-    """
-    branch = subprocess.check_output(
-        ["git", "rev-parse", "--abbrev-ref", "HEAD"],
-        text=True,
-        cwd=str(CHANGELOG_PATH.parent),
-    ).strip()
-    try:
-        subprocess.check_call(
-            ["git", "fetch", "--quiet", remote, branch],
-            stdout=subprocess.DEVNULL,
-            stderr=subprocess.DEVNULL,
-            cwd=str(CHANGELOG_PATH.parent),
-        )
-    except subprocess.CalledProcessError:
-        # Network failure — proceed; operator can re-run with --resume.
-        return
-    local = subprocess.check_output(
-        ["git", "rev-parse", branch],
-        text=True,
-        cwd=str(CHANGELOG_PATH.parent),
-    ).strip()
-    remote_sha = subprocess.check_output(
-        ["git", "rev-parse", f"{remote}/{branch}"],
-        text=True,
-        cwd=str(CHANGELOG_PATH.parent),
-    ).strip()
-    if local == remote_sha:
-        return
-    base = subprocess.check_output(
-        ["git", "merge-base", local, remote_sha],
-        text=True,
-        cwd=str(CHANGELOG_PATH.parent),
-    ).strip()
-    if base == remote_sha:
-        return  # local is strictly ahead — fine.
-    print(
-        f"release: local {branch} is behind {remote}/{branch}; pull first",
-        file=sys.stderr,
-    )
-    sys.exit(2)
-
-
-def _release_phase_stamp_done(version: str) -> tuple[bool, str | None]:
-    """Phase-1 read-only signal: returns (True, head_sha) when CHANGELOG.md
-    on disk AND HEAD's tree both contain a `## [version] - YYYY-MM-DD` header
-    line AND HEAD's commit subject is exactly `chore(release): vX.Y.Z`.
-
-    Date is read from the existing CHANGELOG, NOT recomputed from "today" —
-    `--resume` after UTC midnight rollover must still detect a stamp written
-    yesterday. Returns (False, None) on any miss (file gone, header absent,
-    HEAD blob lacks the header). When the header IS present on HEAD but
-    HEAD's subject is not the stamp subject — meaning an unrelated commit
-    landed on top of the stamp — exits 2 with a diagnostic rather than
-    tagging the wrong SHA. Read-only — never mutates.
-    """
-    expected_prefix = f"## [{version}] - "
-    try:
-        text = CHANGELOG_PATH.read_text(encoding="utf-8")
-    except FileNotFoundError:
-        return (False, None)
-    if not any(line.startswith(expected_prefix) for line in text.splitlines()):
-        return (False, None)
-    head_sha = subprocess.check_output(
-        ["git", "rev-parse", "HEAD"],
-        text=True,
-        cwd=str(CHANGELOG_PATH.parent),
-    ).strip()
-    try:
-        blob = subprocess.check_output(
-            ["git", "show", "HEAD:CHANGELOG.md"],
-            text=True,
-            stderr=subprocess.DEVNULL,
-            cwd=str(CHANGELOG_PATH.parent),
-        )
-    except subprocess.CalledProcessError:
-        return (False, None)
-    if not any(line.startswith(expected_prefix) for line in blob.splitlines()):
-        return (False, None)
-    # HEAD's blob carries the stamp; verify HEAD itself IS the stamp commit.
-    # An unrelated commit landed on top of the stamp would still satisfy the
-    # blob check (CHANGELOG.md unchanged on top), but tagging that SHA would
-    # mis-tag the release. Refuse with a clear diagnostic instead.
-    head_subject = subprocess.check_output(
-        ["git", "log", "-1", "--format=%s", "HEAD"],
-        text=True,
-        cwd=str(CHANGELOG_PATH.parent),
-    ).strip()
-    expected_subject = f"chore(release): v{version}"
-    if head_subject != expected_subject:
-        print(
-            f"release: HEAD is not the stamp commit (subject: {head_subject!r}); "
-            f"--resume cannot continue. Either checkout the stamp commit or "
-            f"revert the on-top commits.",
-            file=sys.stderr,
-        )
-        sys.exit(2)
-    # Belt-and-suspenders: package.json's version must also be stamped
-    # (Phase 1 co-stamp invariant). When package.json doesn't exist
-    # (legacy fixtures, source clones pre-Task-1), skip silently —
-    # the CHANGELOG header check above is still authoritative.
-    pj_path = cctally._package_json_path()
-    if pj_path.exists():
-        try:
-            pj = json.loads(pj_path.read_text(encoding="utf-8"))
-        except json.JSONDecodeError:
-            return (False, None)
-        if pj.get("version") != version:
-            return (False, None)
-    return (True, head_sha)
-
-
-def _release_build_stamp_message(
-    version: str,
-    body: str,
-    invocation: str,
-    prior_head: str,
-    bump_kind: str,
-    subsection_counts: dict[str, int],
-) -> str:
-    """Build the full stamp commit message: private body + `--- public ---`
-    block + canonical body (spec §7.1).
-
-    Subject is identical on both surfaces (`chore(release): vX.Y.Z`); the
-    public body is the canonical CHANGELOG section body byte-for-byte.
-    """
-    counts_str = ", ".join(
-        f"{name} ({n})" for name, n in subsection_counts.items() if n > 0
-    ) or "(none)"
-    total = sum(subsection_counts.values())
-    private_body = (
-        f"chore(release): v{version}\n"
-        f"\n"
-        f"Stamp release v{version} over {total} [Unreleased] entries.\n"
-        f"\n"
-        f"Run by `{invocation}` from main at {prior_head[:7]}.\n"
-        f"Bump kind: {bump_kind}.\n"
-        f"Subsections stamped: {counts_str}.\n"
-    )
-    public_block = f"--- public ---\nchore(release): v{version}\n\n{body}\n"
-    return private_body + "\n" + public_block
-
-
-def _release_run_phase_stamp(
-    version: str,
-    remote: str,
-    invocation: str,
-    bump_kind: str = "(unspecified)",
-) -> str:
-    """Phase 1 — stamp `[Unreleased]` into a `[X.Y.Z]` section and commit.
-
-    Idempotent: if `_release_phase_stamp_done(version)` reports done,
-    short-circuits with the existing HEAD SHA. Otherwise rewrites
-    CHANGELOG.md atomically (`os.replace`), stages it, verifies the
-    staging cache contains exactly `CHANGELOG.md` (defends against
-    operator-prestaged content slipping into the release commit), then
-    invokes `git commit -F <msgfile> --cleanup=verbatim` so the
-    `### Added` / `### Fixed` headings survive (default cleanup strips
-    `#`-prefixed lines as comments). Returns the new commit SHA.
-    """
-    done, head_sha = _release_phase_stamp_done(version)
-    if done:
-        print(
-            f"release: stamp ✓ (already done — commit {head_sha[:7]})"
-        )
-        return head_sha
-
-    print(f"release: stamp v{version}")
-    today = (
-        os.environ.get("CCTALLY_RELEASE_DATE_UTC")
-        or dt.datetime.now(dt.timezone.utc).date().isoformat()
-    )
-    old_text = CHANGELOG_PATH.read_text(encoding="utf-8")
-    try:
-        new_text, body = cctally._release_stamp_changelog(old_text, version, today)
-    except ValueError as e:
-        # Mirror the dry-run path's contract: refuse with exit 2 when
-        # `[Unreleased]` is empty (spec §3 step 4 / §11.4 row 9).
-        print(f"release: {e}", file=sys.stderr)
-        sys.exit(2)
-
-    # Subsection counts — read from the OLD parse (before the stamp moved
-    # bullets out of [Unreleased]); private-body diagnostics only.
-    parsed = cctally._release_parse_changelog(old_text)
-    counts: dict[str, int] = {}
-    if parsed["sections"]:
-        for sub in parsed["sections"][0]["subsections"]:
-            if sub["bullets"]:
-                heading = sub["heading"].replace("###", "").strip()
-                counts[heading] = len(sub["bullets"])
-
-    prior_head = subprocess.check_output(
-        ["git", "rev-parse", "HEAD"],
-        text=True,
-        cwd=str(CHANGELOG_PATH.parent),
-    ).strip()
-
-    # Atomic write: write to .tmp.<pid> sibling, then os.replace(). Wrapped
-    # in try/finally so a failure between write_text and os.replace doesn't
-    # leak a stray .tmp.<pid> file next to CHANGELOG.md.
-    tmp = CHANGELOG_PATH.with_suffix(f".md.tmp.{os.getpid()}")
-    try:
-        tmp.write_text(new_text, encoding="utf-8")
-        os.replace(tmp, CHANGELOG_PATH)
-    finally:
-        try:
-            tmp.unlink()
-        except FileNotFoundError:
-            pass
-
-    # Stage CHANGELOG.md only (`cwd` so the relative path resolves).
-    subprocess.check_call(
-        ["git", "add", CHANGELOG_PATH.name],
-        cwd=str(CHANGELOG_PATH.parent),
-    )
-
-    # Co-stamp package.json (npm channel; Phase 5 reads this version field).
-    # Path resolved via _package_json_path() (which derives from
-    # CHANGELOG_PATH) so tests monkeypatching CHANGELOG_PATH to a temp
-    # repo automatically see the correct (absent) package.json there.
-    # Guarded by `.exists()` so fixture replays for old scenarios
-    # pre-dating the npm channel still pass — they have no package.json
-    # to stamp.
-    pj_path = cctally._package_json_path()
-    if pj_path.exists():
-        pj_old = pj_path.read_text(encoding="utf-8")
-        pj_new = cctally._release_stamp_package_json(pj_old, version)
-        pj_path.write_text(pj_new, encoding="utf-8")
-        subprocess.check_call(
-            ["git", "add", pj_path.name],
-            cwd=str(CHANGELOG_PATH.parent),
-        )
-
-    # Trailer staging guard: refuse if anything else is staged. Defensive
-    # — preflight should have caught a dirty index, but operators can race
-    # `git add` between preflight and stamp.
-    staged = (
-        subprocess.check_output(
-            ["git", "diff", "--cached", "--name-only"],
-            text=True,
-            cwd=str(CHANGELOG_PATH.parent),
-        )
-        .strip()
-        .splitlines()
-    )
-    expected_staged = (
-        ["CHANGELOG.md", "package.json"]
-        if pj_path.exists()
-        else ["CHANGELOG.md"]
-    )
-    if staged != expected_staged:
-        print(
-            f"release: stamp aborted; expected only {expected_staged} staged, "
-            f"got {staged}",
-            file=sys.stderr,
-        )
-        recover_paths = " ".join(expected_staged)
-        print(
-            "release: to recover, run `git reset HEAD` and "
-            f"`git checkout -- {recover_paths}`",
-            file=sys.stderr,
-        )
-        sys.exit(3)
-
-    msg = _release_build_stamp_message(
-        version, body, invocation, prior_head, bump_kind, counts
-    )
-    msg_file = CHANGELOG_PATH.parent / f".release-msg.{os.getpid()}.txt"
-    msg_file.write_text(msg, encoding="utf-8")
-    try:
-        subprocess.check_call(
-            [
-                "git",
-                "commit",
-                "-F",
-                str(msg_file),
-                "--cleanup=verbatim",
-            ],
-            cwd=str(CHANGELOG_PATH.parent),
-        )
-    finally:
-        try:
-            msg_file.unlink()
-        except FileNotFoundError:
-            pass
-
-    new_sha = subprocess.check_output(
-        ["git", "rev-parse", "HEAD"],
-        text=True,
-        cwd=str(CHANGELOG_PATH.parent),
-    ).strip()
-    print(f"release: stamp ✓ (commit {new_sha[:7]})")
-    return new_sha
-
-
-def _release_phase_tag_done(version: str, remote: str) -> bool:
-    """Phase-2 read-only signal: tag exists locally AND on `<remote>`.
-
-    Both are required (spec §5.1): a local-only tag means the push step
-    still has work; a remote-only tag (rare — implies a manual push)
-    is treated as not-done so the local annotation is recreated.
-    Read-only — never mutates.
-    """
-    tag = f"v{version}"
-    local = (
-        subprocess.check_output(
-            ["git", "tag", "-l", tag],
-            text=True,
-            cwd=str(CHANGELOG_PATH.parent),
-        )
-        .strip()
-        .splitlines()
-    )
-    if tag not in local:
-        return False
-    try:
-        out = subprocess.check_output(
-            ["git", "ls-remote", "--tags", remote, f"refs/tags/{tag}"],
-            text=True,
-            stderr=subprocess.DEVNULL,
-            cwd=str(CHANGELOG_PATH.parent),
-        ).strip()
-        return bool(out)
-    except subprocess.CalledProcessError:
-        return False
-
-
-def _release_run_phase_tag(version: str, remote: str, stamp_sha: str) -> None:
-    """Phase 2 — write annotated tag `vX.Y.Z` and push commit + tag.
-
-    `stamp_sha` is the SHA returned by Phase 1; tagging is pinned to that
-    SHA rather than re-reading HEAD, so an unrelated commit landing on top
-    between phases never causes a mis-tag (defense in depth — the done-
-    signal in `_release_phase_stamp_done` already refuses that scenario).
-
-    Idempotent: short-circuits when `_release_phase_tag_done`. The
-    body is re-parsed from CHANGELOG.md and run through
-    `_release_canonical_body` so the annotation is byte-identical to
-    Phase 1's commit-message public block (body-canonical-three-sources
-    invariant, spec §7.4 — same string flows into Phase 4's GH Release
-    notes).
-
-    Resume scenarios:
-    - Local tag missing, remote tag missing: create + push as normal.
-    - Local tag exists, remote tag missing (push failed last run, or
-      operator pushed `main` manually): skip `git tag` (would conflict
-      with the existing local tag) and push only the tag explicitly.
-    - Both present: short-circuited by `_release_phase_tag_done` above.
-
-    Signing: use `-s` only when both `user.signingkey` is set AND
-    `tag.gpgsign` is `true`; otherwise `-a` (annotated, unsigned).
-    Operators that have signing keys configured but not enabled for
-    tags get the unsigned path. Signed tags will have a PGP signature
-    block appended to the tag object — the eventual harness scenario
-    must strip lines from `-----BEGIN PGP SIGNATURE-----` onward
-    before comparing the annotation against the canonical body.
-
-    `--cleanup=verbatim` is required: default cleanup strips
-    `#`-prefixed lines, eating every `### Added` / `### Fixed`
-    heading. Push uses `--follow-tags` to ship commit + tag in one
-    operation, plus an explicit `refs/tags/...:refs/tags/...` push as
-    belt-and-suspenders: `--follow-tags` skips tags whose target commit
-    is already on the remote (the resume-after-manual-push case), so
-    the explicit push is what guarantees the tag actually lands.
-    """
-    if _release_phase_tag_done(version, remote):
-        print(
-            f"release: tag ✓ (already done — v{version} on {remote})"
-        )
-        return
-
-    print(f"release: tag v{version}")
-    tag = f"v{version}"
-
-    # Resume-aware: if the local tag already exists from a prior run, skip
-    # `git tag` (would fail with "tag already exists") and push only.
-    local_tags = (
-        subprocess.check_output(
-            ["git", "tag", "-l", tag],
-            text=True,
-            cwd=str(CHANGELOG_PATH.parent),
-        )
-        .strip()
-        .splitlines()
-    )
-    if tag in local_tags:
-        print(f"release: tag {tag} exists locally; pushing tag only")
-    else:
-        # Body — re-parse CHANGELOG so the annotation reuses the canonical
-        # body string (matches the public block of Phase 1's commit byte
-        # for byte; same string flows into Phase 4's GH Release notes).
-        text = CHANGELOG_PATH.read_text(encoding="utf-8")
-        parsed = cctally._release_parse_changelog(text)
-        target_section = next(
-            (
-                s
-                for s in parsed["sections"]
-                if s["heading"].lstrip().startswith(f"## [{version}]")
-            ),
-            None,
-        )
-        if target_section is None:
-            print(
-                f"release: cannot find [{version}] section in CHANGELOG.md",
-                file=sys.stderr,
-            )
-            sys.exit(3)
-        body = cctally._release_canonical_body(target_section)
-
-        annotation = f"{tag}\n\n{body}\n"
-        msg_file = CHANGELOG_PATH.parent / f".release-tag-msg.{os.getpid()}.txt"
-        try:
-            msg_file.write_text(annotation, encoding="utf-8")
-            signing_key = subprocess.run(
-                ["git", "config", "--get", "user.signingkey"],
-                capture_output=True,
-                text=True,
-                cwd=str(CHANGELOG_PATH.parent),
-            ).stdout.strip()
-            tag_gpgsign = (
-                subprocess.run(
-                    ["git", "config", "--get", "tag.gpgsign"],
-                    capture_output=True,
-                    text=True,
-                    cwd=str(CHANGELOG_PATH.parent),
-                )
-                .stdout.strip()
-                .lower()
-                == "true"
-            )
-            sign_flag = "-s" if (signing_key and tag_gpgsign) else "-a"
-            subprocess.check_call(
-                [
-                    "git",
-                    "tag",
-                    sign_flag,
-                    "-F",
-                    str(msg_file),
-                    "--cleanup=verbatim",
-                    tag,
-                    stamp_sha,
-                ],
-                cwd=str(CHANGELOG_PATH.parent),
-            )
-        finally:
-            try:
-                msg_file.unlink()
-            except FileNotFoundError:
-                pass
-
-    branch = subprocess.check_output(
-        ["git", "rev-parse", "--abbrev-ref", "HEAD"],
-        text=True,
-        cwd=str(CHANGELOG_PATH.parent),
-    ).strip()
-    subprocess.check_call(
-        ["git", "push", remote, branch, "--follow-tags"],
-        cwd=str(CHANGELOG_PATH.parent),
-    )
-    # Belt-and-suspenders: --follow-tags skips tags whose target is already
-    # on the remote (e.g., resume after operator pushed `main` manually).
-    # Explicit refs-spec always pushes the tag; no-op when both are already
-    # on remote (true resume-after-success).
-    subprocess.check_call(
-        ["git", "push", remote, f"refs/tags/{tag}:refs/tags/{tag}"],
-        cwd=str(CHANGELOG_PATH.parent),
-    )
-    print(f"release: tag ✓ (annotated, pushed to {remote})")
-
-
-def _release_discover_public_clone(args: argparse.Namespace) -> pathlib.Path:
-    """Resolve the public-clone path (spec §9.1).
-
-    Priority chain (highest first):
-      1. ``--public-clone <path>`` flag.
-      2. ``git config --get release.publicClone``.
-      3. ``$APP_DIR/release-public-clone-path`` plain-text marker file.
-
-    Each source is silently skipped when missing (unset config key, no
-    marker file, no flag). Refuses with exit 2 only when ALL three
-    sources are absent — operator setup is one-time and explicit, no
-    silent fallback to a hard-coded path.
-    """
-    candidates: list[tuple[str, pathlib.Path]] = []
-
-    if getattr(args, "public_clone", None):
-        candidates.append(("--public-clone", pathlib.Path(args.public_clone)))
-
-    # Source 2 — git config. `git config --get` exits 1 when the key is
-    # unset; that's the silent-skip path. Other failures (e.g., not in a
-    # git repo) also fall through silently — preflight has already
-    # established we're inside a repo.
-    #
-    # Key is `release.publicClone` (camelCase) per git config naming
-    # conventions; git 2.46+ rejects underscore-bearing keys at write
-    # time, so the spec's informal `release.public_clone` wording maps
-    # to this canonical form. Git config lookup is case-insensitive on
-    # the trailing variable, so `release.publicclone` works too.
-    try:
-        out = subprocess.run(
-            ["git", "config", "--get", "release.publicClone"],
-            capture_output=True,
-            text=True,
-            check=True,
-        ).stdout.strip()
-        if out:
-            candidates.append(
-                ("git config release.publicClone", pathlib.Path(out))
-            )
-    except subprocess.CalledProcessError:
-        pass
-
-    # Source 3 — marker file under APP_DIR.
-    marker = APP_DIR / "release-public-clone-path"
-    if marker.exists():
-        text = marker.read_text(encoding="utf-8").strip()
-        if text:
-            candidates.append((str(marker), pathlib.Path(text)))
-
-    for _source, path in candidates:
-        if (path / ".git").exists():
-            return path.resolve()
-        # Bare repo — `<path>/HEAD` exists alongside `objects/`, `refs/`.
-        if path.is_dir() and (path / "HEAD").exists():
-            return path.resolve()
-        # Lenient fallthrough — if the path simply exists but doesn't
-        # match either layout, return it anyway. The next subprocess
-        # (`git -C <path> ...`) will fail loudly with a clear error;
-        # pre-validating here would only duplicate that diagnostic.
-        if path.exists():
-            return path.resolve()
-
-    marker_path = APP_DIR / "release-public-clone-path"
-    print(
-        "release: cannot discover public clone path; pass --public-clone "
-        "<path>, set 'release.publicClone' in git config, or write the "
-        f"path to {marker_path}",
-        file=sys.stderr,
-    )
-    sys.exit(2)
-
-
-def _release_discover_brew_clone(
-    args: argparse.Namespace,
-) -> pathlib.Path | None:
-    """Resolve the brew tap clone path. Returns ``None`` if unconfigured.
-
-    Priority chain (mirrors :func:`_release_discover_public_clone`):
-      1. ``--brew-clone <path>`` flag.
-      2. ``git config --get release.brewClone``.
-      3. ``$APP_DIR/release-brew-clone-path`` plain-text marker file.
-
-    Unlike :func:`_release_discover_public_clone` (which exits 2 when
-    none of the sources resolve), this returns ``None`` — Phase 6 is a
-    graceful skip, not a hard refusal, since release channels are
-    added incrementally and not every operator has a brew tap clone
-    on hand.
-    """
-    if getattr(args, "brew_clone", None):
-        return pathlib.Path(args.brew_clone).expanduser()
-
-    cfg = subprocess.run(
-        ["git", "config", "--get", "release.brewClone"],
-        capture_output=True,
-        text=True,
-        check=False,
-    )
-    if cfg.returncode == 0 and cfg.stdout.strip():
-        return pathlib.Path(cfg.stdout.strip()).expanduser()
-
-    marker = APP_DIR / "release-brew-clone-path"
-    if marker.exists():
-        path_str = marker.read_text(encoding="utf-8").strip()
-        if path_str:
-            return pathlib.Path(path_str).expanduser()
-
-    return None
-
-
-def _release_phase_brew_done(
-    version: str, brew_clone: pathlib.Path
-) -> bool:
-    """Phase 6 done iff the brew tap **remote** serves the ``vX.Y.Z``
-    formula on its default branch AND carries the ``v<version>`` tag.
-
-    Tag presence alone is not enough — ``brew install`` reads the
-    formula from the tap's default branch, NOT from the tag, so a
-    half-failed push (tag landed, branch did not) would still serve
-    the prior formula to users. Mirrors the
-    :func:`_release_phase_mirror_done` pattern (Phase 3) and adds a
-    branch-tip check on top.
-
-    Three-step check (each gates the next):
-
-      1. Local-file sniff — cheap pre-check; skip the network when
-         the formula isn't even staged locally.
-      2. ``git ls-remote --tags origin refs/tags/v<version>`` — tag
-         must be on the remote.
-      3. ``git ls-remote origin refs/heads/<branch>`` SHA == local
-         clone's ``HEAD`` SHA — the local formula commit must be the
-         remote default-branch tip. After a successful Phase 6 push,
-         these match; after a half-failed push (branch fail, tag
-         succeed), they diverge.
-
-    Returns ``False`` on any subprocess failure (no origin configured,
-    network glitch); the caller proceeds to run the phase, whose own
-    push step is independently idempotent.
-    """
-    formula = brew_clone / "Formula" / "cctally.rb"
-    if not formula.exists():
-        return False
-    if f"/v{version}.tar.gz" not in formula.read_text(encoding="utf-8"):
-        return False
-    try:
-        origin = subprocess.check_output(
-            ["git", "-C", str(brew_clone), "remote", "get-url", "origin"],
-            text=True,
-        ).strip()
-        tag_out = subprocess.check_output(
-            ["git", "ls-remote", "--tags", origin, f"refs/tags/v{version}"],
-            text=True,
-        ).strip()
-        if not tag_out:
-            return False
-        local_head = subprocess.check_output(
-            ["git", "-C", str(brew_clone), "rev-parse", "HEAD"],
-            text=True,
-        ).strip()
-        branch = subprocess.check_output(
-            ["git", "-C", str(brew_clone), "rev-parse", "--abbrev-ref", "HEAD"],
-            text=True,
-        ).strip()
-        head_out = subprocess.check_output(
-            ["git", "ls-remote", origin, f"refs/heads/{branch}"],
-            text=True,
-        ).strip()
-        # ls-remote line format: "<sha>\trefs/heads/<branch>"; empty
-        # output means the remote has no such branch (fresh tap).
-        remote_head = head_out.split("\t", 1)[0] if head_out else ""
-        return remote_head == local_head
-    except subprocess.CalledProcessError:
-        return False
-
-
-def _release_phase_mirror_done(
-    version: str, public_clone: pathlib.Path
-) -> bool:
-    """Phase 3 done iff the public clone's ``origin`` carries ``vX.Y.Z``.
-
-    Read-only signal — runs ``git ls-remote`` against the public clone's
-    own ``origin`` (the public mirror's URL is the single source of
-    truth here, per spec §9.1). Returns ``False`` on any subprocess
-    failure (no origin remote configured, network glitch, etc.); the
-    caller proceeds to run all three sub-steps, each idempotent on
-    its own.
-    """
-    tag = f"v{version}"
-    try:
-        public_origin = subprocess.check_output(
-            ["git", "-C", str(public_clone), "remote", "get-url", "origin"],
-            text=True,
-        ).strip()
-        out = subprocess.check_output(
-            ["git", "ls-remote", "--tags", public_origin, f"refs/tags/{tag}"],
-            text=True,
-        ).strip()
-        return bool(out)
-    except subprocess.CalledProcessError:
-        return False
-
-
-def _release_run_phase_mirror(
-    version: str, public_clone: pathlib.Path, remote: str
-) -> None:
-    """Phase 3 — replay private commits onto the public clone, then push
-    the branch + tag (spec §9.1).
-
-    Three sub-steps, each its own subprocess; any failure halts with
-    exit 3 so ``--resume`` can re-run from the failed step (each
-    sub-step is independently idempotent).
-
-      3a. ``bin/cctally-mirror-public --yes <public-clone>`` — replay
-          private commits onto the local public clone. ``--yes`` is
-          mandatory in non-interactive context (the mirror tool prompts
-          ``apply? [y/N]`` otherwise).
-      3b. ``git -C <public-clone> push origin <branch>`` — push the
-          public-clone branch to public origin. The branch is read
-          dynamically via ``git -C <public-clone> rev-parse --abbrev-ref
-          HEAD`` rather than hardcoded ``main``, since some operators
-          may run their public clone on a non-default branch.
-      3c. ``git -C <public-clone> push origin refs/tags/v<version>``
-          — push the new tag.
-
-    The ``remote`` arg is currently unused (the public-clone push always
-    targets the clone's own ``origin``); kept in the signature for
-    parity with ``_release_run_phase_tag`` and possible future
-    multi-remote scenarios.
-    """
-    del remote  # spec §9.1 — public-clone push always targets `origin`.
-    if _release_phase_mirror_done(version, public_clone):
-        print(
-            f"release: mirror ✓ (already done — v{version} on public origin)"
-        )
-        return
-
-    print("release: mirror push")
-
-    # Locate `bin/cctally-mirror-public` alongside this script. Resolve
-    # via __file__ so symlinked invocations (~/.local/bin/cctally) still
-    # find the in-repo sibling.
-    mirror_tool = (
-        pathlib.Path(__file__).resolve().parent / "cctally-mirror-public"
-    )
-    if not mirror_tool.exists():
-        print(
-            f"release: cannot find {mirror_tool}",
-            file=sys.stderr,
-        )
-        sys.exit(3)
-
-    # Step 3a — replay private commits onto the public clone.
-    rc = subprocess.call(
-        [str(mirror_tool), "--yes", "--public-clone", str(public_clone)]
-    )
-    if rc != 0:
-        print(
-            f"release: mirror replay (3a) failed (exit {rc}); "
-            "see output above",
-            file=sys.stderr,
-        )
-        sys.exit(3)
-
-    # Step 3b — push the public-clone branch to public origin. The branch
-    # is read dynamically (don't hardcode `main`).
-    try:
-        branch = subprocess.check_output(
-            ["git", "-C", str(public_clone), "rev-parse", "--abbrev-ref", "HEAD"],
-            text=True,
-        ).strip()
-    except subprocess.CalledProcessError as e:
-        print(
-            f"release: mirror branch lookup failed (exit {e.returncode})",
-            file=sys.stderr,
-        )
-        sys.exit(3)
-    rc = subprocess.call(
-        ["git", "-C", str(public_clone), "push", "origin", branch]
-    )
-    if rc != 0:
-        print(
-            f"release: mirror push branch (3b) failed (exit {rc})",
-            file=sys.stderr,
-        )
-        sys.exit(3)
-
-    # Step 3c — push the new tag.
-    tag = f"v{version}"
-    rc = subprocess.call(
-        [
-            "git", "-C", str(public_clone),
-            "push", "origin", f"refs/tags/{tag}",
-        ]
-    )
-    if rc != 0:
-        print(
-            f"release: mirror push tag (3c) failed (exit {rc})",
-            file=sys.stderr,
-        )
-        sys.exit(3)
-
-    print(f"release: mirror ✓ (v{version} propagated)")
-
-
-def _release_phase_gh_done(version: str) -> bool:
-    """Phase-4 read-only signal: ``gh release view vX.Y.Z`` returns 0.
-
-    Read-only — issues a `gh release view` against the public repo and
-    treats exit 0 as "release exists." Suppresses stderr/stdout because
-    the call is purely a probe; the operator-visible state is recorded
-    in ``_release_run_phase_gh``'s own logging. A never-authed operator
-    sees this return False (gh exits non-zero on auth error), the helper
-    falls through to its own auth probe, and the fallback path prints a
-    copy-pasteable command — same UX whether the release simply doesn't
-    exist yet or whether gh can't see it.
-    """
-    rc = subprocess.call(
-        ["gh", "release", "view", f"v{version}", "--repo", PUBLIC_REPO],
-        stdout=subprocess.DEVNULL,
-        stderr=subprocess.DEVNULL,
-    )
-    return rc == 0
-
-
-def _release_phase_npm_done(version: str) -> bool:
-    """True iff ``cctally@<version>`` is already published on npm.
-
-    Probes via ``npm view cctally@<v> dist.tarball --json``. Returns
-    True when the command succeeds AND stdout is a JSON-quoted
-    registry.npmjs.org URL. False on any other condition (timeout,
-    npm not on PATH, version absent, etc.). Used as the idempotency
-    short-circuit for Phase 5 (parity with ``_release_phase_gh_done``).
-    """
-    try:
-        result = subprocess.run(
-            ["npm", "view", f"cctally@{version}", "dist.tarball", "--json"],
-            capture_output=True,
-            text=True,
-            check=False,
-            timeout=15,
-        )
-    except (subprocess.TimeoutExpired, FileNotFoundError):
-        return False
-    if result.returncode != 0:
-        return False
-    out = result.stdout.strip()
-    return (
-        out.startswith('"')
-        and out.endswith('"')
-        and "registry.npmjs.org" in out
-    )
-
-
-def _release_run_phase_gh(version: str, body: str) -> int:
-    """Phase 4 — ``gh release create`` with auth fallback (spec §9.2).
-
-    Returns:
-      - ``0`` on successful publish OR auth-fallback (don't fail the
-        whole release on missing gh auth — phases 1-3 already succeeded;
-        Phase 4 is polish).
-      - ``3`` on hard failure of ``gh release create`` after auth was
-        confirmed OK (network glitch, server-side rejection, etc.); the
-        operator can address it then re-run ``cctally release --resume``.
-
-    Idempotent: ``_release_phase_gh_done`` short-circuits when the
-    release already exists. The body is passed in (not re-fetched here);
-    the caller is responsible for extracting it from CHANGELOG so the
-    body-canonical-three-sources invariant (spec §7.4) is preserved
-    across phases 1, 2, and 4.
-
-    Auth-mismatch semantics (spec §9.3): if ``gh release view`` finds
-    an existing release whose body differs from the current CHANGELOG
-    section, treat the existing as authoritative — no ``gh release
-    edit`` rewrite. Body divergence after the fact is a separate
-    concern that warrants explicit operator action.
-    """
-    if _release_phase_gh_done(version):
-        url = f"https://github.com/{PUBLIC_REPO}/releases/tag/v{version}"
-        print(f"release: gh release ✓ (already published — {url})")
-        return 0
-
-    print("release: gh release")
-
-    # Auth probe — both must succeed for the operator to be able to
-    # write to the public repo.
-    auth_status_ok = (
-        subprocess.call(
-            ["gh", "auth", "status", "--hostname", "github.com"],
-            stdout=subprocess.DEVNULL,
-            stderr=subprocess.DEVNULL,
-        )
-        == 0
-    )
-    repo_access_ok = (
-        subprocess.call(
-            ["gh", "api", f"repos/{PUBLIC_REPO}"],
-            stdout=subprocess.DEVNULL,
-            stderr=subprocess.DEVNULL,
-        )
-        == 0
-    )
-    if not (auth_status_ok and repo_access_ok):
-        cctally._release_print_gh_fallback(version, body)
-        return 0
-
-    # Happy path. Notes go through a tmpfile to dodge shell escaping.
-    notes_file = pathlib.Path(tempfile.gettempdir()) / (
-        f"release-notes-v{version}-{os.getpid()}.md"
-    )
-    notes_file.write_text(body, encoding="utf-8")
-    try:
-        cmd = [
-            "gh", "release", "create", f"v{version}",
-            "--repo", PUBLIC_REPO,
-            "--title", f"v{version}",
-            "--notes-file", str(notes_file),
-        ]
-        if "-" in version:
-            cmd.append("--prerelease")
-        rc = subprocess.call(cmd)
-        if rc != 0:
-            print(
-                f"release: gh release create failed (exit {rc}); "
-                "--resume to retry",
-                file=sys.stderr,
-            )
-            return 3
-    finally:
-        notes_file.unlink(missing_ok=True)
-
-    url = f"https://github.com/{PUBLIC_REPO}/releases/tag/v{version}"
-    print(f"release: gh release ✓ ({url})")
-    return 0
-
-
-def _release_run_phase_npm(
-    version: str,
-    public_clone: pathlib.Path,
-    *,
-    dist_tag: str,
-) -> int:
-    """Phase 5 — wait for the public-repo GHA workflow to publish ``cctally@<v>``.
-
-    Phase 3 pushes ``v<version>`` to ``omrikais/cctally``; the workflow at
-    ``.github/workflows/release-npm.yml`` fires on tag-push and runs
-    ``npm publish --provenance`` via OIDC trusted publisher (no NPM_TOKEN,
-    no operator 2FA round-trip — fixes the passkey-in-subprocess failure
-    mode where npm 2FA blocks ``npm publish`` from a non-interactive
-    subprocess).
-
-    Phase 5 here is observation-only: poll ``npm view cctally@<v>`` until
-    it appears, with timeout. ``cctally`` never invokes ``npm publish``
-    locally anymore — Trusted Publisher binds the right to publish to the
-    public-repo workflow, not to the operator's `npm login` token.
-
-    Returns ``0`` on observed success OR poll-timeout (soft-success: phases
-    1-4 landed; the workflow is either succeeding or visibly failing on
-    github.com; ``--resume`` re-checks the registry).
-
-    Timing overridable via ``CCTALLY_RELEASE_NPM_POLL_TIMEOUT_S`` and
-    ``CCTALLY_RELEASE_NPM_POLL_INTERVAL_S`` env vars.
-    """
-    print(f"phase 5: await npm publish via GHA (tag={dist_tag})")
-    if _release_phase_npm_done(version):
-        print(f"  cctally@{version} already on npm — skipping.")
-        return 0
-
-    timeout_s, interval_s = cctally._release_npm_poll_timing()
-    deadline = time.monotonic() + timeout_s
-    while True:
-        if _release_phase_npm_done(version):
-            print(f"  cctally@{version} on npm registry ✓")
-            return 0
-        if time.monotonic() >= deadline:
-            print(
-                f"\n  timed out after {timeout_s:.0f}s waiting for "
-                f"cctally@{version} on npm. The GHA workflow may still be "
-                f"running or have failed — check:\n"
-                f"    https://github.com/{PUBLIC_REPO}/actions\n"
-                f"  Re-run `cctally release --resume` once the workflow "
-                f"completes, or for emergency manual publish:\n"
-                f"    cd {public_clone} && npm publish --access public "
-                f"--tag {dist_tag}\n",
-                file=sys.stderr,
-            )
-            return 0
-        time.sleep(interval_s)
-
-
-def _release_run_phase_brew(
-    version: str,
-    brew_clone: pathlib.Path | None,
-    allow_downgrade: bool = False,
-) -> int:
-    """Phase 6 — render ``Formula/cctally.rb`` and push to the brew tap.
-
-    Idempotent. Pre-releases are skipped at the cmd_release call site —
-    this function never runs for them.
-
-    Phase semantics:
-      - ``brew_clone is None`` — graceful skip (no error). Operator can
-        opt in later by setting ``release.brewClone`` in git config.
-      - Done-signal short-circuit — prints "already at vX.Y.Z" and
-        returns 0 when ``Formula/cctally.rb`` already references this
-        version (idempotency under ``--resume``).
-      - Dirty working tree — refuses with exit 2 and points the operator
-        at ``--resume``.
-      - **Monotonic-version gate (issue #30).** Refuses with exit 2 when
-        the existing on-disk formula's URL pins a *higher* SemVer than
-        ``version``. Catches the f02b2f1 regression class — operator
-        runs Phase 6 from a stale CHANGELOG / fixture leak / accidental
-        old branch and would otherwise silently write a lower version
-        over a higher one. Override via ``allow_downgrade=True``
-        (operator-driven, for genuine yank/revert cases).
-      - Push failure — auth-fallback parity with Phase 4: prints the
-        exact recovery command and returns 0. Phases 1-5 already
-        succeeded, the release IS published from the user's
-        perspective; the brew tap is the third channel and treated as
-        polish.
-
-    Returns:
-      - ``0`` on success, graceful skip, idempotent short-circuit, OR
-        push fallback.
-      - ``2`` on dirty-working-tree refusal OR downgrade-gate refusal.
-    """
-    print("phase 6: brew formula bump")
-    if brew_clone is None:
-        print(
-            "  brew tap clone not configured. Set with:\n"
-            "    git config release.brewClone /path/to/homebrew-cctally\n"
-            "  Skipping phase 6 (no error).",
-            file=sys.stderr,
-        )
-        return 0
-    if _release_phase_brew_done(version, brew_clone):
-        print(f"  Formula/cctally.rb already at v{version} on tap — skipping.")
-        return 0
-
-    # Refuse on dirty working tree — we're about to write the formula
-    # and commit; mixing operator-staged work into our commit is a
-    # footgun. Resume after the operator resolves.
-    status = subprocess.run(
-        ["git", "-C", str(brew_clone), "status", "--porcelain"],
-        capture_output=True,
-        text=True,
-        check=True,
-    )
-    if status.stdout.strip():
-        print(
-            f"  brew clone has uncommitted changes:\n{status.stdout}\n"
-            "  Resolve and re-run `cctally release --resume`.",
-            file=sys.stderr,
-        )
-        return 2
-
-    formula_path = brew_clone / "Formula" / "cctally.rb"
-    local_at_version = (
-        formula_path.exists()
-        and f"/v{version}.tar.gz"
-        in formula_path.read_text(encoding="utf-8")
-    )
-
-    if local_at_version:
-        # Resume after a push failure (the done-check verifies remote
-        # tag, so we only reach here when the local commit is in place
-        # but the tap origin hasn't seen it). Skip render + commit; go
-        # straight to (re)tag + push. Re-rendering would no-op the
-        # commit (`git commit` exits 1 with nothing to commit), so
-        # short-circuiting is also what keeps the function tidy.
-        print(
-            f"  local formula already at v{version}; re-pushing to tap…"
-        )
-    else:
-        # Monotonic-version gate (issue #30). The brew tap regressed
-        # from v1.3.0 → v1.0.0 twice in one day via this code path; the
-        # equality fingerprint above (`local_at_version`) is False on a
-        # downgrade, so without this gate we'd silently overwrite a
-        # higher version. Compare the existing formula's URL-pinned
-        # SemVer against `version` (SemVer-aware so prereleases sort
-        # below their stable counterpart per §11.4); refuse with exit 2
-        # when the on-disk version is strictly higher. Unparseable
-        # formulas are treated as unversioned and allowed through.
-        if formula_path.exists():
-            existing_text = formula_path.read_text(encoding="utf-8")
-            existing_v = cctally._release_extract_formula_version(existing_text)
-            if existing_v is not None:
-                try:
-                    existing_key = _release_semver_sort_key(
-                        _release_parse_semver(existing_v)
-                    )
-                    target_key = _release_semver_sort_key(
-                        _release_parse_semver(version)
-                    )
-                except ValueError:
-                    existing_key = target_key = None
-                if (
-                    existing_key is not None
-                    and target_key is not None
-                    and existing_key > target_key
-                    and not allow_downgrade
-                ):
-                    print(
-                        f"  refuse: existing formula pins v{existing_v}, "
-                        f"target is v{version} (downgrade).\n"
-                        "  Common causes: stale CHANGELOG.md in this clone, "
-                        "fixture leak into a real `release.brewClone`, or an "
-                        "accidental old branch.\n"
-                        "  Verify intent, then re-run with "
-                        "`--allow-formula-downgrade` to override "
-                        "(yank / revert cases). See issue #30.",
-                        file=sys.stderr,
-                    )
-                    return 2
-                if (
-                    existing_key is not None
-                    and target_key is not None
-                    and existing_key > target_key
-                    and allow_downgrade
-                ):
-                    print(
-                        f"  WARNING: writing v{version} over existing v{existing_v} "
-                        "(--allow-formula-downgrade); intentional yank?",
-                        file=sys.stderr,
-                    )
-        print(f"  computing sha256 of v{version} archive…")
-        sha = cctally._release_compute_brew_sha256(version)
-
-        template = cctally._homebrew_template_path().read_text(encoding="utf-8")
-        rendered = (
-            template
-            .replace("<<VERSION>>", version)
-            .replace("<<SHA256>>", sha)
-        )
-        formula_path.parent.mkdir(parents=True, exist_ok=True)
-        formula_path.write_text(rendered, encoding="utf-8")
-
-        subprocess.run(
-            ["git", "-C", str(brew_clone), "add", "Formula/cctally.rb"],
-            check=True,
-        )
-        subprocess.run(
-            ["git", "-C", str(brew_clone), "commit", "-m",
-             f"chore(formula): cctally {version}"],
-            check=True,
-        )
-    # Tag is best-effort — re-running after a partial publish should
-    # not fail just because the tag already exists locally.
-    #
-    # Annotated form with `-m` (issue #25): plain `git tag <name>` is
-    # silently upgraded to `git tag -s <name>` under operator-global
-    # `tag.gpgsign=true` and demands a message via editor. The release
-    # script has no editor stdin, so git aborts with `fatal: no tag
-    # message?` — the atomic push refspec then fails with "src refspec
-    # does not match any" because the local tag was never created, and
-    # the auth-fallback branch below silently swallows the failure as
-    # exit 0. Mirrors Phase 2's signing detection (signing_key +
-    # tag.gpgsign → -s, else fall back), with one defensive divergence:
-    # the fallback uses --no-sign (not bare -a) so the tag still lands
-    # under tag.gpgsign=true without a usable signing key configured.
-    # Brew install reads the formula off the tap's default branch, not
-    # the tag, so signing the tap tag is operationally moot — it exists
-    # for history bookkeeping and atomic-push transport.
-    signing_key = subprocess.run(
-        ["git", "-C", str(brew_clone), "config", "--get", "user.signingkey"],
-        capture_output=True,
-        text=True,
-    ).stdout.strip()
-    tag_gpgsign = (
-        subprocess.run(
-            ["git", "-C", str(brew_clone), "config", "--get", "tag.gpgsign"],
-            capture_output=True,
-            text=True,
-        )
-        .stdout.strip()
-        .lower()
-        == "true"
-    )
-    sign_flag = "-s" if (signing_key and tag_gpgsign) else "--no-sign"
-    subprocess.run(
-        ["git", "-C", str(brew_clone), "tag", sign_flag, "-a", "-m",
-         f"cctally v{version}", f"v{version}"],
-        check=False,
-    )
-    # Single ATOMIC push of branch + tag in one transaction — the
-    # remote either accepts both refs or neither (server-side atomic
-    # push, `--atomic`). Avoids the half-failed-push asymmetry that a
-    # split branch-push + tag-push pair admits: a tag landing without
-    # the branch landing would leave `brew install` serving the OLD
-    # formula off the tap's default branch even though the remote
-    # carries the new tag. Tag refspec is explicit (`src:dst`) for
-    # atomic-push semantics — `--atomic` requires named refs, not the
-    # implicit `--follow-tags` path.
-    push = subprocess.run(
-        ["git", "-C", str(brew_clone), "push", "--atomic", "origin",
-         "HEAD", f"refs/tags/v{version}:refs/tags/v{version}"],
-        check=False,
-    )
-    if push.returncode != 0:
-        # If the local tag isn't there (e.g., the operator hit the
-        # tag.gpgsign edge case from issue #25 even with the fix), the
-        # plain push refspec fails. Surface a tag-create fallback in
-        # the hint so copy-paste recovery is self-contained.
-        print(
-            f"\n  push failed. Manual recovery:\n"
-            f"    # If local tag v{version} is missing (e.g., gpgsign issue):\n"
-            f"    git -C {brew_clone} tag --no-sign -a -m \"cctally v{version}\" v{version}\n"
-            f"    # Then push:\n"
-            f"    git -C {brew_clone} push --atomic origin HEAD "
-            f"refs/tags/v{version}:refs/tags/v{version}\n",
-            file=sys.stderr,
-        )
-        return 0  # auth-fallback semantics; parity with Phase 4.
-
-    return 0
-
-
-def _release_extract_body_from_changelog(version: str) -> str:
-    """Re-read the canonical body for ``version`` from CHANGELOG.md.
-
-    Same parse + canonicalize path as Phases 1 and 2 (spec §7.4 — the
-    body-canonical-three-sources invariant). Refuses with exit 3 if
-    the section isn't found; ``--resume`` is the recovery once the
-    operator re-stamps.
-    """
-    text = CHANGELOG_PATH.read_text(encoding="utf-8")
-    parsed = cctally._release_parse_changelog(text)
-    section = next(
-        (
-            s for s in parsed["sections"]
-            if s["heading"].startswith(f"## [{version}]")
-        ),
-        None,
-    )
-    if section is None:
-        print(
-            f"release: cannot find [{version}] section in CHANGELOG.md",
-            file=sys.stderr,
-        )
-        sys.exit(3)
-    return cctally._release_canonical_body(section)
-
-
-def cmd_release(args: argparse.Namespace) -> int:
-    """Dispatch thunk — actual implementation in bin/_cctally_release.py.
-
-    Lazy-load + invoke. Test/harness code that calls cctally.cmd_release
-    directly hits this thunk; the underlying _cctally_release.cmd_release
-    handles the work. The thunk fires only when cmd_release is invoked,
-    so the lazy module's parse cost is paid only on `cctally release ...`
-    or test access — not on every `cctally <other-subcmd>` invocation.
-
-    Spec: docs/superpowers/specs/2026-05-13-bin-cctally-split-design.md §4.1
-    """
-    return _load_sibling("_cctally_release").cmd_release(args)
+# `cmd_release` is NOT defined here: the release subcommand was extracted
+# from the main `cctally` CLI and lives as a standalone entry point
+# (bin/cctally-release). The implementation is in bin/_cctally_release.py.
+# Tests that exercise `cmd_release` import it directly from
+# `_cctally_release`.
 
 
 # Files to scan when detecting the legacy status-line snippet (Section 5).
@@ -2331,7 +978,6 @@ def _decode_escaped_cwd(dir_name: str) -> str:
     return "/" + stripped.replace("-", "/")
 
 
-
 def _sum_cost_for_range(
     start: dt.datetime,
     end: dt.datetime,
@@ -2414,7 +1060,6 @@ def _resolve_primary_model_for_block(
     return row["model"]
 
 
-
 def _read_keychain_oauth_blob() -> str | None:
     """Read the Claude Code keychain entry on macOS via `security`.
 
@@ -5276,7 +3921,6 @@ def _parse_cli_date_range(
     return range_start, range_end
 
 
-
 def cmd_daily(args: argparse.Namespace) -> int:
     """Show usage report grouped by display-timezone date."""
     _share_validate_args(args)
@@ -6475,7 +5119,6 @@ _diff_render_json = _lib_diff_kernel._diff_render_json
 _diff_resolve_anchor = _lib_diff_kernel._diff_resolve_anchor
 
 
-
 def cmd_diff(args: argparse.Namespace) -> int:
     """Compare Claude usage between two windows."""
     now_utc = _command_as_of()
@@ -10209,7 +8852,7 @@ def doctor_gather_state(
     )
 
     # ── Meta ─────────────────────────────────────────────────────────
-    cctally_version_tuple = _release_read_latest_release_version()
+    cctally_version_tuple = _lib_changelog._read_latest_changelog_version()
     cctally_version = (
         cctally_version_tuple[0] if cctally_version_tuple else "unknown"
     )
@@ -11929,90 +10572,9 @@ def build_parser() -> argparse.ArgumentParser:
     )
     doctor_p.set_defaults(func=cmd_doctor)
 
-    # ---- release (issue #24 release automation) ----
-    p_release = sub.add_parser(
-        "release",
-        help="Stamp CHANGELOG, cut SemVer tag, mirror, and create GitHub Release",
-        formatter_class=CLIHelpFormatter,
-        description=textwrap.dedent(
-            """\
-            Issue #24 release automation. Four idempotent phases:
-              1. Stamp CHANGELOG.md (move [Unreleased] entries under [X.Y.Z]).
-              2. Annotated tag vX.Y.Z + push --follow-tags.
-              3. Mirror push (replay private → push public branch + tag).
-              4. GitHub Release create on the public mirror.
-
-            See docs/commands/release.md for full reference.
-            """
-        ),
-    )
-    p_release.add_argument(
-        "kind",
-        nargs="?",
-        choices=["patch", "minor", "major", "prerelease", "finalize"],
-        help="Bump kind (omit only with --resume)",
-    )
-    p_release.add_argument(
-        "--resume",
-        action="store_true",
-        help="Continue an in-progress release (infers vX.Y.Z from latest CHANGELOG header)",
-    )
-    p_release.add_argument(
-        "--dry-run",
-        action="store_true",
-        help="Print phase plan with diff/tag/release; mutate nothing; exit 0",
-    )
-    p_release.add_argument(
-        "--no-publish",
-        action="store_true",
-        help="Stop after Phase 2 (tag); skip Phases 3-6 (mirror, gh release, npm, brew)",
-    )
-    p_release.add_argument(
-        "--prerelease-id",
-        default="rc",
-        help="Override 'rc' for prerelease bumps (default 'rc')",
-    )
-    p_release.add_argument(
-        "--bump",
-        choices=["patch", "minor", "major"],
-        help="REQUIRED with `prerelease` when current is stable; REFUSED when current is prerelease",
-    )
-    p_release.add_argument(
-        "--remote",
-        default="origin",
-        help="Default 'origin' (private remote)",
-    )
-    p_release.add_argument(
-        "--allow-branch",
-        default=None,
-        help="Override the on-main refusal (escape hatch)",
-    )
-    p_release.add_argument(
-        "--public-clone",
-        default=None,
-        help="Override public-clone discovery (default: git config 'release.publicClone' or marker file)",
-    )
-    p_release.add_argument(
-        "--skip-npm",
-        action="store_true",
-        help="Skip Phase 5 (npm publish). Idempotent: re-running --resume without it picks the channel back up.",
-    )
-    p_release.add_argument(
-        "--brew-clone",
-        default=None,
-        help="Override brew tap discovery (default: git config 'release.brewClone' or marker file)",
-    )
-    p_release.add_argument(
-        "--skip-brew",
-        action="store_true",
-        help="Skip Phase 6 (brew formula bump). Idempotent: re-running --resume without it picks the channel back up.",
-    )
-    p_release.add_argument(
-        "--allow-formula-downgrade",
-        action="store_true",
-        help="Override Phase 6's monotonic-version gate (issue #30). Use only for intentional yank/revert cases — Phase 6 normally refuses to write a formula whose URL pins a lower SemVer than the on-disk formula.",
-    )
-    p_release.set_defaults(func=cmd_release)
+    # `release` is its own standalone entry-point (bin/cctally-release);
+    # no `release` subparser is registered on the main `cctally` CLI.
+    # See docs/RELEASE.md.
 
     # ---- hook-tick (internal — hidden from --help, see onboarding spec §3) ----
     ht = sub.add_parser(
@@ -12359,12 +10921,13 @@ def _share_history_recipe_id() -> str:
 
 
 def _share_resolve_version() -> str:
-    """Source from CHANGELOG via the existing release helper. Empty string if unset.
+    """Source from CHANGELOG via the public helper. Empty string if unset.
 
-    `_release_read_latest_release_version` returns `(version, date) | None`;
-    the snapshot's `version` field carries the version string only.
+    `_lib_changelog._read_latest_changelog_version` returns
+    `(version, date) | None`; the snapshot's `version` field carries
+    the version string only.
     """
-    info = _release_read_latest_release_version()
+    info = _lib_changelog._read_latest_changelog_version()
     return info[0] if info else ""
 
 
@@ -13928,8 +12491,6 @@ cmd_tui = _cctally_tui.cmd_tui
 _tui_render_once = _cctally_tui._tui_render_once
 
 
-
-
 def main(argv: list[str] | None = None) -> int:
     _migrate_legacy_data_dir()
     parser = build_parser()
@@ -13938,7 +12499,7 @@ def main(argv: list[str] | None = None) -> int:
     # release header (issue #24); handle BEFORE subcommand dispatch so it
     # works without a subcommand (`cctally --version`).
     if getattr(args, "version", False):
-        v = _release_read_latest_release_version()
+        v = _lib_changelog._read_latest_changelog_version()
         if v is None:
             print("cctally unknown")
         else: