fix(shim): harden CafeScripto shim discovery + pin canonical (#32)

Hardens the `bin/cafe` shim (discovery: $AFFINESCRIPT → PATH → sibling
checkout, actionable not-found message) and adds `.affinescript-pin`
(canonical commit lock).

Part of Milestone A of the face-sealing plan. Binding contract:
`docs/specs/FACE-CONTRACT.adoc` in hyperpolymath/affinescript (PR #685).
Draft — lands after the contract PR is reviewed.

---------

Co-authored-by: gitbot-fleet <gitbot@hyperpolymath.example.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: 3 people

.affinescript-pin

@@ -0,0 +1,6 @@
+# AffineScript canonical pin — the compiler commit this face is validated against.
+# Version-lock per docs/specs/FACE-CONTRACT.adoc (hyperpolymath/affinescript).
+# Update deliberately (after re-running the face conformance gate), not casually.
+repo = https://github.com/hyperpolymath/affinescript.git
+commit = 4b36de2fad7bc18408aec9b71c6c3acf1afe8d09
+face = cafe

.github/workflows/governance.yml

@@ -32,4 +32,3 @@ permissions:
 jobs:
   governance:
     uses: hyperpolymath/standards/.github/workflows/governance-reusable.yml@d7c22711e830e1f383846472f6e9b99debdb201e
-    timeout-minutes: 10

bin/cafe

@@ -2,14 +2,60 @@
 # SPDX-License-Identifier: MPL-2.0
 # SPDX-FileCopyrightText: 2024-2026 Jonathan D.A. Jewell (hyperpolymath)
 #
-# cafe — CafeScripto shim. Forwards arguments to the affinescript CLI
-# with --face cafe injected right after the subcommand. Source files
-# should still use the canonical .affine extension and a face: cafescripto
-# pragma; this shim only saves typing the --face flag for routine use.
+# cafe — CafeScripto shim (brand surface only; carries no compiler).
+#
+# Locates the canonical `affinescript` compiler and injects `--face cafe`.
+# Source files use the canonical `.affine` extension plus a `face: cafescripto`
+# pragma; this shim only saves typing the flag. Discovery order and the binding
+# contract are normative in docs/specs/FACE-CONTRACT.adoc (hyperpolymath/affinescript).
+set -euo pipefail
+FACE="cafe"
+BRAND="CafeScripto"
+
+# Resolve this script's own directory (follow symlinks) for sibling discovery.
+SOURCE="${BASH_SOURCE[0]}"
+while [ -h "$SOURCE" ]; do
+  DIR="$(cd -P "$(dirname "$SOURCE")" >/dev/null 2>&1 && pwd)"
+  SOURCE="$(readlink "$SOURCE")"
+  [ "${SOURCE#/}" = "$SOURCE" ] && SOURCE="$DIR/$SOURCE"
+done
+SCRIPT_DIR="$(cd -P "$(dirname "$SOURCE")" >/dev/null 2>&1 && pwd)"
+
+find_affinescript() {
+  # 1. explicit override
+  if [ -n "${AFFINESCRIPT:-}" ] && [ -x "${AFFINESCRIPT:-}" ]; then
+    printf '%s' "$AFFINESCRIPT"; return 0
+  fi
+  # 2. on PATH (e.g. `opam install affinescript`)
+  if command -v affinescript >/dev/null 2>&1; then
+    printf '%s' affinescript; return 0
+  fi
+  # 3. a sibling canonical checkout, built (`dune build`)
+  local c
+  for c in \
+    "$SCRIPT_DIR/../../γ-affinescript/affinescript/_build/default/bin/main.exe" \
+    "$SCRIPT_DIR/../../../γ-affinescript/affinescript/_build/default/bin/main.exe" \
+    "$SCRIPT_DIR/../affinescript/_build/default/bin/main.exe" \
+    "$HOME/developer/repos/γ-affinescript/affinescript/_build/default/bin/main.exe"; do
+    if [ -x "$c" ]; then printf '%s' "$c"; return 0; fi
+  done
+  return 1
+}
+
+if ! AS="$(find_affinescript)"; then
+  cat >&2 <<MSG
+error: the canonical \`affinescript\` compiler was not found.
+$BRAND is a brand surface only — it needs the compiler installed. Try one of:
+  • opam install affinescript          (then re-run)
+  • export AFFINESCRIPT=/path/to/affinescript
+  • build a sibling checkout: (in γ-affinescript/affinescript) dune build
+See docs/specs/FACE-CONTRACT.adoc in hyperpolymath/affinescript.
+MSG
+  exit 127
+fi
 
 if [ $# -eq 0 ]; then
-  exec affinescript
+  exec "$AS"
 fi
-subcmd="$1"
-shift
-exec affinescript "$subcmd" --face cafe "$@"
+subcmd="$1"; shift
+exec "$AS" "$subcmd" --face "$FACE" "$@"