felhom-controller/controller/scripts/golden_notice.py

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""golden_notice.py — tell the repo that CREATES the golden debt, at the moment it creates it.

Usage:  python3 scripts/golden_notice.py <repo-root>
Exit ALWAYS 0 when it can answer, 2 when it cannot. **NEVER 1. It cannot refuse a push.**

WHY THIS EXISTS (R-404, 2026-09-01).

The golden-currency check was pointed at the wrong repository. `felhom.eu` — which holds the bake
evidence, the register and the architecture — ran it on every push, including pushes that touch only
documents and therefore can neither create the debt nor clear it. `felhom-controller` — where a
release actually happens — **never checked at all.** So the person who could act heard nothing and
the person who could not act was blocked, and `--no-verify` was reached for thirteen times.

This is the other half of that correction: the notice belongs where the debt is born.

⚠ IT IS ADVISORY IN EVERY CASE, AND THAT IS NOT TIMIDITY — IT IS THE ONLY CORRECT BEHAVIOUR.
At the moment a release is committed the golden legitimately does NOT exist yet: you cannot bake a
golden for a version you have not pushed. Blocking here would refuse the very commit that starts the
process. And blocking LATER is the mistake this whole change is undoing. So it prints, and the
runner's exit code is untouched. `controller_gates.py` gained a `blocking` field to express that;
before this, that runner could not describe a gate that reports without refusing.

⚠ IT NEVER GUESSES. With no `felhom.eu` sibling clone it says INCONCLUSIVE and stays silent about
currency — an absent input is "I do not know", never "fine".

NO SECOND IMPLEMENTATION. It IMPORTS `felhom.eu/scripts/golden_currency_gate.py` and calls that
gate's own `released_versions()` and `newest_baked()`, so the comparison here is the SAME
comparison, read in the other direction. A private copy of "which version owes a golden" is a second
thing that can be wrong, and the two would drift. This follows `instructions_gate.py`'s cross-repo
pattern: the shared script lives in ONE repo and is invoked across the workspace, never copied.
"""
import importlib.util
import os
import sys

HERE = os.path.dirname(os.path.abspath(__file__))
CTRL = os.path.dirname(HERE)
REPO_DEFAULT = os.path.dirname(CTRL)


def load_gate(repo_root):
    """Import the sibling felhom.eu gate. Returns (module, tried_path) or (None, tried_path)."""
    path = os.path.join(os.path.dirname(repo_root), "felhom.eu", "scripts",
                        "golden_currency_gate.py")
    if not os.path.isfile(path):
        return None, path
    try:
        spec = importlib.util.spec_from_file_location("golden_currency_gate", path)
        mod = importlib.util.module_from_spec(spec)
        spec.loader.exec_module(mod)
        return mod, path
    except Exception as e:
        sys.stdout.write("golden-notice: the sibling gate could not be imported: %s\n" % e)
        return None, path


def main(argv):
    repo_root = os.path.abspath(argv[1]) if len(argv) > 1 else REPO_DEFAULT
    gate, tried = load_gate(repo_root)
    if gate is None:
        print("golden-notice: INCONCLUSIVE — no felhom.eu sibling clone.")
        print("  tried: %s" % tried)
        print("  Nothing is claimed about golden currency. An absent input is 'I do not know',")
        print("  never 'fine'. This is still NOT a refusal — it never blocks a push.")
        return 2

    try:
        released = gate.released_versions()
        baked = gate.newest_baked()
    except Exception as e:
        print("golden-notice: INCONCLUSIVE — the sibling gate raised %s" % e)
        return 2

    # `released_versions()` returns newest-first; `newest_baked()` returns the newest bake.
    newest_rel = released[0] if released else None
    newest_bake = baked[0] if isinstance(baked, tuple) else baked
    if newest_rel is None:
        print("golden-notice: INCONCLUSIVE — could not read a released version from CHANGELOG.md.")
        return 2

    rel_s = gate.vstr(newest_rel)
    bake_s = gate.vstr(newest_bake) if newest_bake else "none"

    if newest_bake and tuple(newest_bake) >= tuple(newest_rel):
        print("golden-notice: OK — v%s is released and a golden carries it (newest bake %s)."
              % (rel_s, bake_s))
        return 0

    # The debt exists. Say so plainly, and say what clears it.
    print("=" * 78)
    print("NOTICE — v%s OWES A GOLDEN.  (this NEVER blocks; see the docstring)" % rel_s)
    print("=" * 78)
    print("  newest released controller : %s   (this repo's CHANGELOG.md)" % rel_s)
    print("  newest golden baked        : %s   (felhom.eu documentation/tests/)" % bake_s)
    print("")
    print("  A machine installed right now would receive %s, not %s." % (bake_s, rel_s))
    print("")
    print("  This is a REMINDER AT THE ONE MOMENT IT IS USEFUL — you are in the repo where the")
    print("  release happens. It does not block, and must not: at the moment a release is")
    print("  committed the golden cannot exist yet.")
    print("")
    print("  WHAT CLEARS IT: bake a golden (felhom.eu documentation/runbooks/RUNBOOK-manual-build.md")
    print("  section 4.1), then vouch it — a THREE-field change: golden_version + agent_version +")
    print("  min_agent. The bake record lands in felhom.eu documentation/tests/golden-<ver>-<date>/.")
    print("")
    print("  If this release deliberately needs no golden, record a waiver row in")
    print("  felhom.eu documentation/backlog/OPEN-ITEMS.md — never a habit of bypassing.")
    print("=" * 78)
    return 0


if __name__ == "__main__":
    sys.exit(main(sys.argv))