@techgoblin/gobstack 0.0.0-stage → 0.4.4-beta.1

package/bin/goblin-upgrade

@@ -0,0 +1,572 @@
+#!/usr/bin/env bash
+# goblin-upgrade — the 0.4.4 per-repo → global migration (W3, W3-SPEC §2).
+#
+#   goblin upgrade [--target <dir>] [--dry-run] [--yes] [--engine-dir <path>]
+#
+# What it does (the corrected 7-step sequence, W3-SPEC §2 — the record is rewritten
+# BEFORE the deletion, and every verify runs against a committed tree, CM-03):
+#   0. preflight: resolve the input state (I1/I2/I3/I4), refuse R1–R10
+#   1. hash-verify every recorded file (IN-02 clause-1 logic) — drift exits 1
+#   2. verify #1 — the untouched repo must already be green
+#   3. land the global engine at --engine-dir (default ~/.goblin/engine), 0700,
+#      by copying this repo's own 18 verified bytes (same-hash reuse; different
+#      hash → R6 refusal — never overwrite a global engine other repos declare)
+#   4. commit A: engine_dir: active in goblin.yaml + engine: block in
+#      installed.json (18 engine entries dropped, skills retained) + gate.sh and
+#      the CI run line re-pointed
+#   5. verify #2 — green with BOTH engines present (the vendored one judges; the
+#      point is that the rewritten record and gate.sh parse mid-sequence)
+#   6. commit B: git rm exactly the 18 engine paths (the only irreversible step)
+#   7. verify #3 — expected, measured: 39 passed, 0 failed, 11 advisory,
+#      32 skipped, rc 0 (W3-SPEC MA5)
+#   8. report: counts, engine identity, both commit SHAs, the rollback command
+#
+# Exit contract (PLAN-V1 §2.3): 0 ok or no-op · 1 refusal, with the path and the
+# fix · 2 bad input. Refusals R1–R10 are W3-SPEC §4 verbatim in intent.
+#
+# Non-negotiables inherited from the rest of bin/: no npm, no jq, no yq, no
+# network (bash/awk/sed/git only); the engine stays bash; nothing outside the
+# repo is written except the engine lift, which is additive; rollback is pure
+# `git revert` of this command's own two commits (W3-SPEC §5).
+set -uo pipefail
+
+GOBLIN_UPGRADE_VERSION="0.4.4"
+
+usage() { sed -n '2,/^$/p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; }
+
+g_err() { printf 'error: %s\n' "$*" >&2; }
+
+# g_expand_tilde <path> — ~ and ~/... to $HOME (the goblin-install:81 idiom).
+g_expand_tilde() {
+  case "$1" in
+    "~") printf '%s\n' "$HOME" ;;
+    "~"/*) printf '%s\n' "$HOME/${1#\~/}" ;;
+    *) printf '%s\n' "$1" ;;
+  esac
+}
+
+# sha256 <file> — the one hash spelling, used everywhere.
+sha256() { sha256sum "$1" 2>/dev/null | awk '{print $1}'; }
+
+# ---- options ------------------------------------------------------------------
+TARGET="."
+DRY_RUN=0          # --dry-run is the DEFAULT: the CLI never changes a repo
+                   # without an explicit --yes (PLAN-V1 §8.1 item 8).
+YES=0
+ENGINE_DIR_OPT=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --target)     TARGET="${2:-}"; shift 2 ;;
+    --dry-run)    DRY_RUN=1; shift ;;
+    --yes)        YES=1; shift ;;
+    --engine-dir) ENGINE_DIR_OPT="${2:-}"; shift 2 ;;
+    --help|-h)    usage; exit 0 ;;
+    *) g_err "unknown option: $1"; usage >&2; exit 2 ;;
+  esac
+done
+if [ "$DRY_RUN" -eq 1 ] && [ "$YES" -eq 1 ]; then
+  g_err "--dry-run and --yes are mutually exclusive"
+  exit 2
+fi
+[ -n "$TARGET" ] || { g_err "--target needs a directory"; exit 2; }
+[ -z "$ENGINE_DIR_OPT" ] || [ -n "${ENGINE_DIR_OPT#-}" ] || { g_err "--engine-dir needs a path"; exit 2; }
+
+for dep in git awk sed grep sha256sum; do
+  command -v "$dep" >/dev/null 2>&1 || { g_err "missing dependency: $dep"; exit 2; }
+done
+
+[ -d "$TARGET" ] || { g_err "--target is not a directory: $TARGET"; exit 2; }
+REPO=$(cd "$TARGET" && pwd)
+[ -n "$ENGINE_DIR_OPT" ] && ENGINE_DIR_OPT=$(g_expand_tilde "$ENGINE_DIR_OPT")
+ED="${ENGINE_DIR_OPT:-$HOME/.goblin/engine}"
+
+CONFIG="$REPO/.goblin/goblin.yaml"
+INSTALLED="$REPO/.goblin/installed.json"
+
+# The 18 engine paths (W3-SPEC MA1): .goblin/bin/* (the 4 installable) +
+# .goblin/manifest/* (5) + .goblin/bans/* (3) + .goblin/automations/* (5) +
+# .goblin/roles.yaml. The checkout's bin/ holds 8 files; only 4 are installable
+# (goblin-install:509-522), so the vendored payload is exactly these four.
+ENGINE_BIN_FILES="goblin-verify goblin-lib.sh goblin-audit goblin-bans"
+
+# vendored_list — the repo's engine payload, one path per line, .goblin-prefixed.
+# Empty when there is no payload (the engine is already gone).
+vendored_list() {
+  local f
+  [ -d "$REPO/.goblin/bin" ] && for f in $ENGINE_BIN_FILES; do
+    [ -f "$REPO/.goblin/bin/$f" ] && printf '%s\n' ".goblin/bin/$f"
+  done
+  for d in manifest bans automations; do
+    [ -d "$REPO/.goblin/$d" ] || continue
+    for f in "$REPO/.goblin/$d/"*; do
+      [ -f "$f" ] && printf '%s\n' ".goblin/$d/$(basename "$f")"
+    done
+  done
+  [ -f "$REPO/.goblin/roles.yaml" ] && printf '%s\n' ".goblin/roles.yaml"
+  return 0
+}
+
+# g_installed_files_strict <record> — only the `files:` map's entries (the same
+# reader goblin-verify's IN-04 uses: the `engine:` block's key/value pairs must
+# never read as files).
+g_installed_files_strict() {
+  awk '
+    /^  "files": \{[[:space:]]*\},?$/ { next }
+    /^  "files": \{/ { f = 1; next }
+    f && /^  \},$/ { f = 0 }
+    f && /^    "/ {
+      line = $0
+      sub(/^    "/, "", line)
+      p = line; sub(/".*/, "", p)
+      h = line; sub(/[^"]*"[[:space:]]*:[[:space:]]*"/, "", h); sub(/".*/, "", h)
+      if (p != "") print p "\t" h
+    }
+  ' "$1"
+}
+
+# engine_block_field <key> — one field of the record's engine: block (empty if absent).
+engine_block_field() {
+  [ -f "$INSTALLED" ] || return 0
+  awk -v k="$1" '
+    index($0, "\"engine\"") && /:[[:space:]]*\{/ { inf = 1; next }
+    inf && /^[[:space:]]*\}/ { inf = 0 }
+    inf && $0 ~ ("\"" k "\"") {
+      v = $0; sub(/^[^:]*:[[:space:]]*/, "", v); sub(/,?[[:space:]]*$/, "", v)
+      gsub(/"/, "", v); print v; exit
+    }
+  ' "$INSTALLED"
+}
+
+record_scalar() { # <key>
+  sed -n "s/^[[:space:]]*\"$1\"[[:space:]]*:[[:space:]]*\"\{0,1\}\([^\",]*\)\"\{0,1\},\{0,1\}$/\1/p" "$INSTALLED" | head -n 1
+}
+
+# record_files_count — entries in the record's files map.
+record_files_count() { g_installed_files_strict "$INSTALLED" | grep -c .; }
+
+record_engine_entries_count() { # engine-path entries still in the record
+  g_installed_files_strict "$INSTALLED" | cut -f1 | grep -cE '^\.goblin/(bin/|manifest/|bans/|automations/|roles\.yaml$)' || true
+}
+
+# ---- verify #N runner ----------------------------------------------------------
+# The verify INSIDE the sequence must see the target repo's own state: HOME and
+# GOBLIN_ENGINE_DIR are re-pointed for the child only, so the operator's shell
+# environment can never override the migration's own declaration (the engine-dir
+# escape hatch, --engine-dir, must win over an inherited GOBLIN_ENGINE_DIR).
+VERIFY_SCRIPT=""   # resolved per step: vendored while it exists, else the engine's
+run_verify() {
+  local ed="$ED"
+  ( cd "$REPO" && env -u GOBLIN_ENGINE_DIR \
+      ${ed:+GOBLIN_ENGINE_DIR="$ed"} HOME="${GOBLIN_UPGRADE_HOME:-$HOME}" \
+      bash "$VERIFY_SCRIPT" "$@" )
+}
+
+step_line() { printf 'step %s: %s\n' "$1" "$2"; }
+
+# ---- preflight: resolve the input state (W3-SPEC §1.2) -------------------------
+#   I1 fresh 0.4.x per-repo install  → migrate
+#   I2 already migrated              → idempotent no-op, exit 0
+#   I3 absent/foreign/unparseable    → refusal (2 / 1)
+#   I4 partial crash shapes          → refusal naming resume/rollback (R8/R9)
+
+MODE=""
+
+# ---- R3: not a git repo --------------------------------------------------------
+if ! git -C "$REPO" rev-parse --git-dir >/dev/null 2>&1; then
+  MODE="refuse-R3"
+  R3_MSG="upgrade: $REPO is not a git repository - upgrade's safety (three verifies, two commits, revert) requires git. fix: git init && git add -A && git commit"
+else
+  # ---- R2: detached HEAD -------------------------------------------------------
+  if [ -z "$(git -C "$REPO" symbolic-ref -q HEAD)" ]; then
+    MODE="refuse-R2"
+    R2_SHA=$(git -C "$REPO" rev-parse --short HEAD)
+    R2_MSG="upgrade: $REPO is in detached-HEAD state at $R2_SHA - upgrade's rollback is \`git revert\` of its commits, which needs a branch. fix: git switch -c <name>"
+  else
+    # ---- R1: dirty tree --------------------------------------------------------
+    R1_COUNT=$(git -C "$REPO" status --porcelain | grep -c . || true)
+    if [ "${R1_COUNT:-0}" -gt 0 ]; then
+      MODE="refuse-R1"
+      R1_MSG="upgrade: $R1_COUNT uncommitted entries in $REPO - commit or stash first (upgrade writes its own two commits and cannot mix them with yours)"
+    fi
+  fi
+fi
+
+# ---- the record (I3) -----------------------------------------------------------
+RECORD_PRESENT=0
+[ -f "$INSTALLED" ] && RECORD_PRESENT=1
+RECORD_OK=0
+if [ "$RECORD_PRESENT" -eq 1 ]; then
+  # It must parse, carry a version, and carry a files map (the strict reader must
+  # see at least the shape a 0.4.x install writes).
+  REC_VERSION=$(record_scalar version)
+  REC_FILES_N=$(record_files_count)
+  if grep -q '"version"' "$INSTALLED" 2>/dev/null && [ -n "$REC_VERSION" ] && grep -q '"files"' "$INSTALLED" 2>/dev/null; then
+    RECORD_OK=1
+  fi
+fi
+
+case "$RECORD_PRESENT:$RECORD_OK" in
+  0:*) MODE="${MODE:-refuse-I3-absent}" ;;
+  *:0) MODE="${MODE:-refuse-I3-parse}" ;;
+esac
+
+if [ "$RECORD_OK" -eq 1 ]; then
+  case "$REC_VERSION" in
+    0.4.*) : ;;
+    *) MODE="${MODE:-refuse-I3-version}" ;;
+  esac
+fi
+
+# ---- the state discriminator (I1/I2/I4), only on a well-formed 0.4.x record ----
+if [ "${RECORD_OK:-0}" -eq 1 ] && [ -z "${MODE:-}" ]; then
+  BLOCK_MODE=$(engine_block_field mode)
+  BLOCK_DIR=$(engine_block_field engine_dir)
+  PAYLOAD_N=$(vendored_list | grep -c . || true)
+  RECORD_ENGINE_N=$(record_engine_entries_count)
+  if [ "$BLOCK_MODE" = "global" ] && [ "$PAYLOAD_N" -eq 0 ]; then
+    MODE="noop-R4"                      # I2: already migrated → idempotent no-op
+  elif [ "$BLOCK_MODE" = "global" ] && [ "$PAYLOAD_N" -gt 0 ]; then
+    MODE="refuse-R8"                    # crash between commits A and B
+    R8_MSG="upgrade: partial migration detected - the record says global but $PAYLOAD_N engine files are still here. fix: resume by removing them (the engine lives at ${BLOCK_DIR:-$ED}), or roll back: git revert <commit A>"
+  elif [ "$BLOCK_MODE" != "global" ] && [ "$RECORD_ENGINE_N" -lt 18 ]; then
+    MODE="refuse-R9"                    # hand-migration: entries PARTIALLY or fully dropped, no block
+    R9_MSG="upgrade: $REPO's record is missing its engine: block and carries only $RECORD_ENGINE_N of the 18 engine entries - dropped $((18 - RECORD_ENGINE_N)) by hand, a state goblin upgrade did not produce. fix: restore the record (git checkout .goblin/installed.json) and re-run"
+  elif [ "$PAYLOAD_N" -eq 0 ]; then
+    MODE="refuse-R5"                    # fresh-shape record but no payload to lift
+    R5_MSG="upgrade: no engine at $ED and no vendored payload to lift it from - install the engine first (goblin-install a fresh repo, or set --engine-dir)"
+  elif [ "$RECORD_ENGINE_N" -eq 18 ]; then
+    MODE="migrate"                      # I1: the migration runs (record intact, payload intact)
+  else
+    MODE="refuse-R9"                    # record count off in any unnamed combination: refuse, do not guess
+    R9_MSG="upgrade: $REPO's record carries $RECORD_ENGINE_N engine entries where a 0.4.4 install records 18 - an unnamed state. fix: restore the record (git checkout .goblin/installed.json) and re-run"
+  fi
+fi
+
+# ---- dry-run report -------------------------------------------------------------
+if [ "$DRY_RUN" -eq 1 ]; then
+  printf 'goblin upgrade --dry-run — target %s\n' "$REPO"
+  printf '  engine-dir: %s\n' "$ED"
+  case "$MODE" in
+    migrate)
+      printf '  state: fresh 0.4.x per-repo install (record %s entries, %s engine payload files on disk)\n' \
+        "$(record_files_count)" "$PAYLOAD_N"
+      step_line 1 "hash-verify every recorded file (IN-02 clause-1 logic)"
+      step_line 2 "verify #1 — the untouched repo must be green"
+      step_line 3 "land the global engine at $ED (copy this repo's own $PAYLOAD_N verified bytes; reuse if the hash pair matches)"
+      step_line 4 "commit A — engine_dir: active in goblin.yaml + engine: block in installed.json (record $(record_files_count) → $(( $(record_files_count) - RECORD_ENGINE_N )) entries) + gate.sh and the CI run line re-pointed"
+      step_line 5 "verify #2 — green with both engines present (vendored judges; proves the rewritten record parses)"
+      step_line 6 "commit B — git rm exactly the $PAYLOAD_N engine paths (the only irreversible step)"
+      step_line 7 "verify #3 — expected: 39 passed, 0 failed, 11 advisory, 32 skipped, rc 0"
+      step_line 8 "report — counts, engine identity, both commit SHAs, the rollback command"
+      ;;
+    noop-R4)
+      printf '  state: already migrated — the real run would print no-op and exit 0\n'
+      ;;
+    refuse-R1) printf '  would refuse (exit 1): %s\n' "$R1_MSG" ;;
+    refuse-R2) printf '  would refuse (exit 1): %s\n' "$R2_MSG" ;;
+    refuse-R3) printf '  would refuse (exit 1): %s\n' "$R3_MSG" ;;
+    refuse-I3-absent) printf '  would refuse: nothing to upgrade: %s/.goblin/installed.json — this is not a per-repo goblin-stack install\n' "$REPO" ;;
+    refuse-I3-parse)  printf '  would refuse: %s does not parse — this is not a per-repo goblin-stack install (exit 2)\n' "$INSTALLED" ;;
+    refuse-I3-version) printf '  would refuse: record says %s; this upgrade migrates 0.4.x installs — do not hand-edit the record\n' "$REC_VERSION" ;;
+    refuse-R8) printf '  would refuse (exit 1): %s\n' "$R8_MSG" ;;
+    refuse-R9) printf '  would refuse (exit 1): %s\n' "$R9_MSG" ;;
+    refuse-R5) printf '  would refuse (exit 1): %s\n' "$R5_MSG" ;;
+    *) printf '  state: unknown\n' ;;
+  esac
+  printf '  dry-run wrote nothing.\n'
+  exit 0
+fi
+
+# ---- the refusals, for a real run ----------------------------------------------
+case "$MODE" in
+  refuse-R1) g_err "$R1_MSG"; exit 1 ;;
+  refuse-R2) g_err "$R2_MSG"; exit 1 ;;
+  refuse-R3) g_err "$R3_MSG"; exit 1 ;;
+  refuse-I3-absent)
+    g_err "nothing to upgrade: $INSTALLED — this is not a per-repo goblin-stack install"
+    exit 2 ;;
+  refuse-I3-parse)
+    g_err "$INSTALLED does not parse — this is not a per-repo goblin-stack install"
+    exit 2 ;;
+  refuse-I3-version)
+    g_err "record says $REC_VERSION; this upgrade migrates 0.4.x installs — do not hand-edit the record"
+    exit 1 ;;
+  refuse-R8) g_err "$R8_MSG"; exit 1 ;;
+  refuse-R9) g_err "$R9_MSG"; exit 1 ;;
+  refuse-R5) g_err "$R5_MSG"; exit 1 ;;
+  noop-R4)
+    printf 'no-op: already migrated to %s (cli %s)\n' \
+      "${BLOCK_DIR:-$ED}" "$(engine_block_field cli_version)"
+    exit 0 ;;
+esac
+
+# ================================================================================ step 1
+# Hash-verify EVERY recorded file before writing anything. A hand-edited harness
+# is not migrated silently: any drift exits 1 naming the file.
+step_line 1 "hash-verify the record ($(record_files_count) files)"
+VERIFY_SCRIPT="$REPO/.goblin/bin/goblin-verify"
+while IFS=$'\t' read -r p h; do
+  [ -n "$p" ] || continue
+  if [ ! -e "$REPO/$p" ]; then
+    g_err "upgrade: recorded file is missing: $REPO/$p - restore it (git checkout -- $p) before upgrading"
+    exit 1
+  fi
+  cur=$(sha256 "$REPO/$p")
+  if [ "$cur" != "$h" ]; then
+    g_err "upgrade: hash drift: $p (recorded $h, now $cur) - restore it (git checkout -- $p) before upgrading; a hand-edited harness is not migrated silently"
+    exit 1
+  fi
+done < <(g_installed_files_strict "$INSTALLED")
+
+# ================================================================================ step 2
+# Verify #1 — the untouched repo must already be green. Do not migrate a repo
+# that is already red: the migration would be blamed for it.
+step_line 2 "verify #1 — the untouched repo must be green"
+VERIFY_SCRIPT="$REPO/.goblin/bin/goblin-verify"
+V1=$(run_verify 2>&1); V1_RC=$?
+if [ "$V1_RC" -ne 0 ]; then
+  printf '%s\n' "$V1"
+  g_err "upgrade: verify #1 is red (exit $V1_RC) - the repo is not green before the migration; fix it first (the migration would be blamed for a red it did not cause)"
+  exit 1
+fi
+printf 'verify #1: %s\n' "$(printf '%s' "$V1" | grep -E 'passed,' | head -n 1 | sed 's/^[[:space:]]*//')"
+
+# ================================================================================ step 3
+# Land the global engine. Copy THIS repo's own just-verified bytes — no trust
+# question arises. Same hash pair → reuse; different → R6 refusal.
+step_line 3 "land the global engine at $ED"
+RH=$(sha256 "$REPO/.goblin/bin/goblin-verify")
+RT=$(sha256 "$REPO/.goblin/manifest/enforcement.tsv")
+CLI_VERSION=$(record_scalar version)
+if [ -d "$ED" ]; then
+  if [ ! -f "$ED/manifest/enforcement.tsv" ]; then
+    g_err "upgrade: $ED exists but holds no manifest/enforcement.tsv - this is not an engine directory (a partial copy is a crashed step 3). fix: pass --engine-dir <path>, or remove $ED and re-run"
+    exit 1
+  fi
+  EH=$(sha256 "$ED/bin/goblin-verify")
+  if [ -z "$EH" ]; then
+    g_err "upgrade: $ED holds a manifest but no bin/goblin-verify - a partial engine copy. fix: pass --engine-dir <path>, or remove $ED and re-run"
+    exit 1
+  fi
+  ET=$(sha256 "$ED/manifest/enforcement.tsv")
+  if [ "$EH" = "$RH" ] && [ "$ET" = "$RT" ]; then
+    printf '  reusing existing engine (identical hash pair)\n'
+  else
+    g_err "upgrade: $ED holds a different engine (cli_sha256 ${EH:-absent}, enforcement ${ET:-absent}) than this repo's ($RH, $RT). I will not overwrite a global engine other repos may declare. fix: pass --engine-dir <path> for a second engine, or upgrade $ED first"
+    exit 1
+  fi
+else
+  lift_rc=0
+  while IFS= read -r rel; do
+    [ -n "$rel" ] || continue
+    dst="$ED/${rel#.goblin/}"
+    mkdir -p "$(dirname "$dst")" || { lift_rc=1; break; }
+    cp -p "$REPO/$rel" "$dst" || { lift_rc=1; break; }
+  done < <(vendored_list)
+  if [ "$lift_rc" -ne 0 ]; then
+    g_err "upgrade: copying the engine payload to $ED failed - aborting before anything in the repo changed"
+    exit 1
+  fi
+  chmod 700 "$ED"
+  # Validate AFTER the copy: the landed engine must carry this repo's exact bytes.
+  EH=$(sha256 "$ED/bin/goblin-verify"); ET=$(sha256 "$ED/manifest/enforcement.tsv")
+  if [ "$EH" != "$RH" ] || [ "$ET" != "$RT" ]; then
+    g_err "upgrade: the engine landed at $ED does not match this repo's bytes (cli $EH/$RH, enforcement $ET/$RT) - a partial copy; remove $ED and re-run"
+    exit 1
+  fi
+  printf '  landed %s engine files at %s (mode 0700)\n' "$(vendored_list | grep -c .)" "$ED"
+fi
+
+# ================================================================================ step 4
+# Commit A — the declaration-and-record commit. Written in ONE commit:
+#   goblin.yaml    the commented `# engine_dir:` placeholder becomes the active line
+#   installed.json gains the engine: block; exactly the 18 engine entries drop
+#                  (skills stay — MA5 shows SK-01/02/04/AU-04 SKIP by mode)
+#   checks/gate.sh the source line re-pointed to the engine-resolution idiom
+#   .github/workflows/goblin-gate.yml  run line re-pointed to npx @techgoblin/gobstack@<v>
+# The record rewrite happens BEFORE any deletion (the plan's order is measured
+# wrong: deleting with the record untouched is IN-02 FAIL, W3-SPEC MA3).
+step_line 4 "commit A — the declaration-and-record commit"
+
+engine_dir_line="$ED"
+active_engine_line() { printf 'engine_dir: %s\n' "$engine_dir_line"; }
+
+# ---- goblin.yaml: the commented placeholder becomes the active line ----
+if grep -q '^engine_dir:' "$CONFIG"; then
+  cur_line=$(sed -n 's/^engine_dir:[[:space:]]*//p' "$CONFIG" | head -n 1)
+  if [ "$cur_line" != "$engine_dir_line" ]; then
+    g_err "upgrade: $CONFIG already declares engine_dir: $cur_line (wanted $engine_dir_line) - unparseable or hand-edited config; aborting"
+    exit 2
+  fi
+else
+  if ! grep -q '^# engine_dir:' "$CONFIG"; then
+    g_err "upgrade: $CONFIG has neither an active nor a commented engine_dir: line - not a 0.4.4 template; aborting"
+    exit 2
+  fi
+  sed -i "s|^# engine_dir:.*|$(active_engine_line | sed 's/[&|]/\\&/g')|" "$CONFIG"
+fi
+
+# ---- installed.json: engine block + drop exactly the 18 engine entries ----
+REC_BEFORE=$(record_files_count)
+PYJ=$(mktemp -d)
+cat > "$PYJ/rewrite_record.py" <<'PYEOF'
+import json, sys
+path, ed, ver, cli_sha, tsv_sha = sys.argv[1], sys.argv[2], sys.argv[3], sys.argv[4], sys.argv[5]
+rec = json.load(open(path))
+rec["engine"] = {"mode": "global", "engine_dir": ed, "cli_version": ver,
+                 "cli_sha256": cli_sha, "enforcement_tsv_sha256": tsv_sha}
+def is_engine(p):
+    return p.startswith(".goblin/bin/") or p.startswith(".goblin/manifest/") \
+        or p.startswith(".goblin/bans/") or p.startswith(".goblin/automations/") \
+        or p == ".goblin/roles.yaml"
+rec["files"] = {p: h for p, h in rec["files"].items() if not is_engine(p)}
+json.dump(rec, open(path, "w"), indent=2)
+PYEOF
+cat > "$PYJ/rehash_record.py" <<'PYEOF'
+import json, sys
+path, key, new_sha = sys.argv[1], sys.argv[2], sys.argv[3]
+rec = json.load(open(path))
+if key in rec.get("files", {}):
+    rec["files"][key] = new_sha
+    json.dump(rec, open(path, "w"), indent=2)
+PYEOF
+if ! python3 "$PYJ/rewrite_record.py" "$INSTALLED" "$ED" "$CLI_VERSION" "$RH" "$RT"; then
+  g_err "upgrade: rewriting $INSTALLED failed (python3 unavailable or the record unparseable) - the tree is uncommitted; fix: git checkout .goblin/goblin.yaml .goblin/installed.json checks/gate.sh"
+  exit 2
+fi
+REC_AFTER=$(record_files_count)
+
+# ---- checks/gate.sh: source line re-pointed to the engine-resolution idiom ----
+GATE="$REPO/checks/gate.sh"
+if [ -f "$GATE" ] && grep -q '\.goblin/bin/goblin-lib.sh' "$GATE"; then
+  # No machine path is committed: the idiom resolves engine_dir: → the env
+  # default → ~/.goblin/engine, then sources <engine>/bin/goblin-lib.sh.
+  # The CONFIG line moves UP beside ROOT so the resolver can read it.
+  # gate.sh is a files-RECORDED artifact: its record entry is re-hashed below,
+  # in the same commit (IN-02 would otherwise read the rewrite as drift).
+  awk '
+    /^# shellcheck source=\/dev\/null$/ && !done {
+      print "# shellcheck source=/dev/null"
+      print "# The engine went global (goblin upgrade): resolve it exactly as"
+      print "# goblin-verify does - engine_dir:, then the machine default."
+      print "CONFIG=\"$ROOT/.goblin/goblin.yaml\""
+      print "ENGINE_DIR=$(sed -n \"s/^engine_dir:[[:space:]]*//p\" \"$CONFIG\" | head -n 1)"
+      print "case \"$ENGINE_DIR\" in \"~\") ENGINE_DIR=\"$HOME\" ;; \"~\"/*) ENGINE_DIR=\"$HOME/${ENGINE_DIR#\\~/}\" ;; esac"
+      print "if [ -z \"$ENGINE_DIR\" ] && [ -n \"${GOBLIN_ENGINE_DIR:-}\" ]; then ENGINE_DIR=$GOBLIN_ENGINE_DIR; fi"
+      print "if [ -z \"$ENGINE_DIR\" ] && [ -d \"$HOME/.goblin/engine\" ]; then ENGINE_DIR=$HOME/.goblin/engine; fi"
+      print ". \"$ENGINE_DIR/bin/goblin-lib.sh\""
+      done=1; next
+    }
+    /^CONFIG="/ { next }
+    /^\. \"\$ROOT\/\.goblin\/bin\/goblin-lib\.sh\"$/ { next }
+    { print }
+  ' "$GATE" > "$GATE.new" && mv "$GATE.new" "$GATE"
+  GATE_NEW=$(sha256 "$GATE")
+  python3 "$PYJ/rehash_record.py" "$INSTALLED" "checks/gate.sh" "$GATE_NEW" || {
+    g_err "upgrade: re-hashing the rewritten gate.sh in $INSTALLED failed - the tree is uncommitted; fix: git checkout ."
+    exit 2
+  }
+fi
+
+# ---- the CI workflow: run line re-pointed to the pinned global form ----
+WF="$REPO/.github/workflows/goblin-gate.yml"
+if [ -f "$WF" ] && grep -q 'run: bash .goblin/bin/goblin-verify' "$WF"; then
+  # Names a package W5 publishes; until then CI on a migrated repo is expected
+  # red-by-absence — recorded in the commit message, not hidden. The workflow is
+  # a files-RECORDED artifact, so this rewrite re-hashes its record entry here,
+  # in the same commit (IN-02 hashes every recorded file; a rewritten artifact
+  # with a stale recorded hash would fail verify #2 — measured this session).
+  sed -i "s|run: bash .goblin/bin/goblin-verify|run: npx @techgoblin/gobstack@$CLI_VERSION run goblin-verify|" "$WF"
+  WF_NEW=$(sha256 "$WF")
+  python3 "$PYJ/rehash_record.py" "$INSTALLED" ".github/workflows/goblin-gate.yml" "$WF_NEW" || {
+    g_err "upgrade: re-hashing the rewritten workflow in $INSTALLED failed - the tree is uncommitted; fix: git checkout ."
+    exit 2
+  }
+  rm -rf "$PYJ"
+fi
+
+git -C "$REPO" add -A
+git -C "$REPO" -c commit.gpgsign=false commit -q -m "feat: migrate goblin-stack engine to global $ED (W3 step A)
+
+The record is rewritten BEFORE the deletion (the plan's order is measured
+wrong: deleting with the record untouched is IN-02 FAIL, W3-SPEC MA3).
+goblin.yaml gains the active engine_dir line; installed.json gains the
+engine block and drops exactly the engine entries (skills stay); gate.sh
+and the CI run line are re-pointed. The CI run line names
+npx @techgoblin/gobstack@$CLI_VERSION verify — a package W5 publishes; until then
+CI on a migrated repo is expected red-by-absence."
+COMMIT_A=$(git -C "$REPO" rev-parse --short HEAD)
+printf '  commit A: %s (record %s → %s entries)\n' "$COMMIT_A" "$REC_BEFORE" "$REC_AFTER"
+
+# ================================================================================ step 5
+# Verify #2 — green with both engines present. The vendored engine judges this
+# run (W1's A7 ordering); the point is that the rewritten record, declaration
+# and gate.sh parse and the tree is green MID-sequence. Red → no deletion; the
+# user reverts commit A.
+step_line 5 "verify #2 — green with both engines present"
+VERIFY_SCRIPT="$REPO/.goblin/bin/goblin-verify"
+V2=$(run_verify 2>&1); V2_RC=$?
+if [ "$V2_RC" -ne 0 ]; then
+  printf '%s\n' "$V2"
+  g_err "upgrade: verify #2 is red (exit $V2_RC) - nothing was deleted. fix: git revert $COMMIT_A"
+  exit 1
+fi
+printf 'verify #2: %s\n' "$(printf '%s' "$V2" | grep -E 'passed,' | head -n 1 | sed 's/^[[:space:]]*//')"
+
+# ================================================================================ step 6
+# Commit B — the deletion (the only irreversible step). Exactly the payload list
+# the record just dropped; never skills/, installed.json, or any owned file.
+step_line 6 "commit B — git rm the engine payload (the only irreversible step)"
+EXPECT_N=$(vendored_list | grep -c .)
+DELETE_N=0
+while IFS= read -r rel; do
+  [ -n "$rel" ] || continue
+  case "$rel" in
+    .goblin/bin/goblin-verify|.goblin/bin/goblin-lib.sh|.goblin/bin/goblin-audit|.goblin/bin/goblin-bans|\
+    .goblin/manifest/*|.goblin/bans/*|.goblin/automations/*|.goblin/roles.yaml) : ;;
+    *) g_err "upgrade: refusing to delete anything outside the engine-path list: $rel - aborting, nothing deleted"
+       exit 1 ;;
+  esac
+  DELETE_N=$((DELETE_N + 1))
+done < <(vendored_list)
+if [ "$DELETE_N" -ne "$EXPECT_N" ]; then
+  g_err "upgrade: payload list changed mid-run ($EXPECT_N → $DELETE_N) - aborting, nothing deleted"
+  exit 1
+fi
+while IFS= read -r rel; do
+  [ -n "$rel" ] || continue
+  git -C "$REPO" rm -q "$rel"
+done < <(vendored_list)
+git -C "$REPO" -c commit.gpgsign=false commit -q -m "feat: remove the vendored engine payload (W3 step B; engine lives at $ED)
+
+The one-way door, split from commit A so the rollback for a red verify #3
+never has to resurrect a deleted file: \`git revert <A> <B>\` restores the
+pre-upgrade tree byte-for-byte (W3-SPEC §5.2)."
+COMMIT_B=$(git -C "$REPO" rev-parse --short HEAD)
+printf '  commit B: %s (%s files deleted)\n' "$COMMIT_B" "$DELETE_N"
+
+# ================================================================================ step 7
+# Verify #3 — the post-deletion gate, run against a committed tree (CM-03).
+# Expected, measured: 39 passed, 0 failed, 11 advisory, 32 skipped, rc 0 (MA5).
+step_line 7 "verify #3 — the post-deletion gate"
+if [ -f "$REPO/.goblin/bin/goblin-verify" ]; then
+  VERIFY_SCRIPT="$REPO/.goblin/bin/goblin-verify"
+else
+  VERIFY_SCRIPT="$ED/bin/goblin-verify"
+fi
+V3=$(run_verify 2>&1); V3_RC=$?
+if [ "$V3_RC" -ne 0 ]; then
+  printf '%s\n' "$V3"
+  g_err "upgrade: verify #3 is red (exit $V3_RC) - rollback: git revert $COMMIT_A $COMMIT_B"
+  exit 1
+fi
+printf 'verify #3: %s\n' "$(printf '%s' "$V3" | grep -E 'passed,' | head -n 1 | sed 's/^[[:space:]]*//')"
+
+# ================================================================================ step 8
+step_line 8 "report"
+printf '  files moved: %s (now at %s)\n' "$DELETE_N" "$ED"
+printf '  record entries: %s -> %s\n' "$REC_BEFORE" "$REC_AFTER"
+printf '  engine identity: cli_sha256=%s enforcement_tsv_sha256=%s\n' "$RH" "$RT"
+printf '  commits: %s (A, declaration+record), %s (B, deletion)\n' "$COMMIT_A" "$COMMIT_B"
+printf '  rollback: git revert %s %s\n' "$COMMIT_A" "$COMMIT_B"
+exit 0