scripts/check-executables-allow-sync.sh

@@ -2,17 +2,11 @@
 set -euo pipefail
 
 # Fails the push when root apm.yml's executables.allow key stops naming
-# kyberforge's actual version.
-#
-# apm gates a package's hooks/ and bin/ on an EXACT dict lookup of
-# "<package>#<version>" in executables.allow (apm_cli/security/executables.py,
-# `allow_executables.get(package_key)`) — there is no wildcard and no
-# version-less form. So bumping plugins/kyberforge/apm.yml's `version:` without
-# bumping the key in root apm.yml does not error anywhere: the entry simply
-# stops matching, kyberforge's SessionStart hook stops deploying, and the apm
-# install goes quietly stale — the exact failure ADR-0019 records as live and
-# mitigates only with a comment. Nothing else in the pre-push gate compares the
-# two files, which is why this exists.
+# kyberforge's actual version. apm matches that key by exact dict lookup
+# (apm_cli/security/executables.py) — a version bump that misses the key
+# update deploys nothing, with no error anywhere. See ADR-0019, "The allow
+# key is version-pinned, and that is a live failure mode", for the full
+# argument; nothing else in the pre-push gate compares these two files.
 #
 # Run from repo root or pass REPO_ROOT as arg.
 
@@ -64,12 +58,9 @@ fi
 #   a<TAB>present|absent              exactly once — is executables.allow a mapping?
 #   k<TAB><allow key>                 zero or more
 #
-# python3 + PyYAML is preferred where importable, because it is a real parser.
-# It is deliberately NOT a hard requirement: no other hook in this repo's
-# pre-push gate needs PyYAML, and making a version-pin check the one thing that
-# can block every push on a missing pip package is a worse failure than reading
-# two known shapes by hand. The fallback below is not a YAML parser — it
-# recognises exactly the two shapes these manifests use and nothing else.
+# python3 + PyYAML is preferred where importable; the fallback below is not a
+# YAML parser, it recognises only the two shapes these manifests use. PyYAML
+# stays optional so a missing pip package can't block every push (ADR-0019).
 
 read_facts_python() {
   python3 - "$ROOT_MANIFEST" "$PLUGIN_MANIFEST" << 'PY'