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

package/bin/goblin-install

@@ -0,0 +1,720 @@
+#!/usr/bin/env bash
+# goblin-install — drop the harness into a target repo, idempotently.
+#
+# Usage: goblin-install --target <dir> [options]
+#   --target <dir>        required; the repo root to install into
+#   --class A|B|C|D|E|F    required unless --uninstall or --re-pin; anything else needs an explicit class
+#   --models <path>       model mapping file   (default: $GOBLIN_MODELS -> ~/projects/fleet-model.yaml)
+#   --practice <path>     the referenced standard (default: $GOBLIN_PRACTICE -> ~/projects/PROJECT-PRACTICE.md); a named path that is absent is reported, never silently dropped
+#   --parts <list>        comma list to install; default = every part the class requires
+#   --archive             mark the project archive: verify requires no HANDOFF and no gates
+#   --skills yes|no       install .hermes/skills (default yes; needs the one-time skills trust step)
+#   --dry-run             print the plan; write nothing
+#   --upgrade             re-install at the current version; report created/updated/unchanged/skipped
+#   --opt-out <part>      record the part in disabled: so its required checks are skipped
+#   --uninstall           remove exactly the files in installed.json
+#   --re-pin              re-record practice_sha256: for an edited standard; nothing else changes
+#   --force               allow overwriting a file goblin-stack did not create
+#   --yes                 non-interactive; take the defaults above
+#
+# Exit codes: 0 success / no-op | 1 a refusal (with the path and the fix) | 2 bad input or a
+# missing dependency.
+
+set -uo pipefail
+
+GOBLIN_INSTALL_VERSION="0.4.4"
+SELF_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+SRC=$(cd "$SELF_DIR/.." && pwd)
+# shellcheck source=goblin-lib.sh
+. "$SELF_DIR/goblin-lib.sh"
+
+TARGET=""
+CLASS=""
+MODELS="${GOBLIN_MODELS:-$HOME/projects/fleet-model.yaml}"
+PRACTICE="${GOBLIN_PRACTICE:-$HOME/projects/PROJECT-PRACTICE.md}"
+# W5-3: `--practice <path>` naming a file that is not there used to be IGNORED IN SILENCE -
+# exit 0, `practice: ~`, `practice_sha256: ~`, and not one line about it in the install log.
+# The empty pin is a legitimate state (a repo may reference no standard, and the default path is
+# allowed to be absent), so this is a refusal to be silent, not a refusal to install: the value
+# stays empty and the log names the path that was not found.
+PRACTICE_ARG=""
+PARTS=""
+ARCHIVE="false"
+SKILLS="yes"
+DRY_RUN=0
+UPGRADE=0
+UNINSTALL=0
+RE_PIN=0
+FORCE=0
+OPT_OUT=""
+
+usage() {
+  # The header comment runs from line 2 to the first blank line, so adding an option cannot
+  # truncate the help or leak code into it. The old fixed range ('2,22p') ended on the
+  # `set -uo pipefail` line and printed it as if it were an option.
+  sed -n '2,/^$/p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
+}
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --target)    TARGET="${2:-}"; shift 2 ;;
+    --class)     CLASS="${2:-}"; shift 2 ;;
+    --models)    MODELS="${2:-}"; shift 2 ;;
+    --practice)  PRACTICE="${2:-}"; PRACTICE_ARG="$PRACTICE"; shift 2 ;;
+    --parts)     PARTS="${2:-}"; shift 2 ;;
+    --archive)   ARCHIVE="true"; shift ;;
+    --skills)    SKILLS="${2:-}"; shift 2 ;;
+    --dry-run)   DRY_RUN=1; shift ;;
+    --upgrade)   UPGRADE=1; shift ;;
+    --uninstall) UNINSTALL=1; shift ;;
+    --re-pin)    RE_PIN=1; shift ;;
+    --opt-out)   OPT_OUT="${2:-}"; shift 2 ;;
+    --force)     FORCE=1; shift ;;
+    --yes)       shift ;;
+    -h|--help)   usage; exit 0 ;;
+    *) g_err "unknown option: $1"; usage >&2; exit 2 ;;
+  esac
+done
+
+for dep in git awk sed grep; do
+  command -v "$dep" >/dev/null 2>&1 || { g_err "missing dependency: $dep"; exit 2; }
+done
+[ -n "$TARGET" ] || { g_err "--target is required"; exit 2; }
+TARGET=$(g_expand_tilde "$TARGET")
+[ -d "$TARGET" ] || { g_err "--target is not a directory: $TARGET"; exit 2; }
+TARGET=$(cd "$TARGET" && pwd)
+[ -f "$SRC/VERSION" ] || { g_err "no VERSION at $SRC — is this a goblin-stack checkout?"; exit 2; }
+
+VERSION=$(head -n 1 "$SRC/VERSION")
+CLASSES_TSV="$SRC/manifest/classes.tsv"
+INSTALLED="$TARGET/.goblin/installed.json"
+CONFIG="$TARGET/.goblin/goblin.yaml"
+STAMP=$(date +%F)
+
+# --uninstall and --re-pin are different jobs, and this guard has to sit ABOVE the uninstall
+# branch: that branch ends `exit 0`, so the same check placed below it was unreachable and
+# `--uninstall --re-pin` ran the uninstall without ever seeing the refusal (measured at bf7e9c9:
+# exit 0, target uninstalled, "different jobs" never printed).
+if [ "$UNINSTALL" -eq 1 ] && [ "$RE_PIN" -eq 1 ]; then
+  g_err "--uninstall and --re-pin are different jobs; run them one at a time"
+  exit 2
+fi
+
+# ------------------------------------------------------------- uninstall ------
+if [ "$UNINSTALL" -eq 1 ]; then
+  [ -f "$INSTALLED" ] || { g_err "nothing to uninstall: $INSTALLED is absent"; exit 2; }
+  n=0
+  PARENTS=""
+  while IFS=$'\t' read -r p h; do
+    [ -n "$p" ] || continue
+    [ -e "$TARGET/$p" ] || continue
+    if [ "$DRY_RUN" -eq 1 ]; then g_info "would remove $p"; else rm -f "$TARGET/$p"; fi
+    n=$((n + 1))
+    # EVERY ancestor directory, not just the immediate parent: a file at
+    # .github/workflows/goblin-gate.yml empties two levels, and collecting only `${p%/*}` left
+    # .github/ behind with nothing named (the shape t-uninstall.sh asserts against).
+    d="$p"; while [ "${d%/*}" != "$d" ]; do d="${d%/*}"; PARENTS="$PARENTS$d"$'\n'; done
+  done < <(g_installed_files "$INSTALLED")
+  # The config is goblin-stack's own file, so it goes too. HANDOFF/AGENTS/SPEC/reviews do not:
+  # they are the project's record, not the harness's.
+  if [ -f "$CONFIG" ]; then
+    [ "$DRY_RUN" -eq 1 ] || rm -f "$CONFIG"
+    g_info "removed .goblin/goblin.yaml (goblin-stack's own config)"
+  fi
+  # Runtime state goblin-stack's own checks wrote.
+  for f in .goblin/last-gate-line .goblin/ratchet-last .goblin/.ds-report; do
+    [ -f "$TARGET/$f" ] || continue
+    [ "$DRY_RUN" -eq 1 ] || rm -f "$TARGET/$f"
+    g_info "removed $f (runtime state)"
+  done
+  # The three decision records (audit waivers, boundary waivers, the install-hook allowlist) are
+  # put_once files. An UNEDITED one is still goblin-stack's template and goes; an EDITED one is
+  # the project's decision and stays, named in the summary. Deleting a decision silently would be
+  # data loss; leaving an untouched template behind would be residue (both were measured).
+  KEPT=""
+  while IFS=$'\t' read -r p h; do
+    [ -n "$p" ] || continue
+    case "$p" in
+      .goblin/audit-waiver.tsv|.goblin/boundary-waivers|.goblin/install-hooks.allowlist) ;;
+      *) continue ;;
+    esac
+    [ -e "$TARGET/$p" ] || continue
+    if [ "$(g_sha256_file "$TARGET/$p")" = "$h" ]; then
+      [ "$DRY_RUN" -eq 1 ] || rm -f "$TARGET/$p"
+      g_info "removed $p (unedited template)"
+      n=$((n + 1))
+      case "$p" in */*) PARENTS="$PARENTS${p%/*}"$'\n' ;; esac
+    else
+      KEPT="$KEPT $p"
+      g_info "kept $p (you edited it: a decision record is the project's, not the harness's)"
+    fi
+  done < <(g_json_object "$INSTALLED" owned)
+  # installed.json goes BEFORE the directory pass. While it was still on disk, .goblin/ was
+  # never empty when it was tested, so the directory survived unnamed (D17 / F2-7).
+  if [ "$DRY_RUN" -eq 0 ]; then
+    rm -f "$INSTALLED"
+    if [ -f "$TARGET/.gitignore" ]; then
+      printf '# goblin-stack uninstalled %s\n' "$STAMP" >> "$TARGET/.gitignore"
+    fi
+  fi
+  # Empty directories goblin-stack created: the parents of the files just removed, plus the
+  # harness roots. Deepest first, so a parent is only tested once its child has gone. The
+  # old fixed list never tried .hermes/skills/goblin-* and tested .goblin/ too early.
+  nd=0
+  while read -r d; do
+    [ -n "$d" ] || continue
+    [ -d "$TARGET/$d" ] || continue
+    if [ "$DRY_RUN" -eq 1 ]; then
+      g_info "would remove $d/ (if the files above leave it empty)"
+      nd=$((nd + 1))
+      continue
+    fi
+    if [ -z "$(ls -A "$TARGET/$d" 2>/dev/null)" ]; then
+      rmdir "$TARGET/$d" 2>/dev/null && { g_info "removed $d/ (empty)"; nd=$((nd + 1)); }
+    fi
+  done < <({
+      printf '%s' "$PARENTS"
+      printf '.goblin\n.goblin/bin\n.goblin/manifest\n.goblin/bans\n.hermes\n.hermes/skills\n'
+    } | awk 'NF' | awk -F/ '{print NF " " $0}' | sort -rn | cut -d' ' -f2- | awk '!seen[$0]++')
+  g_info "removed $n file(s) and $nd empty director(y|ies). Left in place: HANDOFF.md, AGENTS.md, ROUND-000-SPEC.md, reviews/, the .gitignore block${KEPT:+, and the decision record(s) you edited:$KEPT}."
+  exit 0
+fi
+
+# ---------------------------------------------------------------- re-pin ------
+# The practice pin (practice_sha256: in .goblin/goblin.yaml, re-checked by IN-02) exists to catch
+# a SILENTLY edited standard. The standard itself is a living document edited in place, and
+# goblin.yaml is an `owned` file the installer never rewrites - so the remedy for an edit that IS
+# intended has to be explicit, printed and deliberate. This mode rewrites exactly one line and
+# reports the old and new hash. It is unreachable from --upgrade and from goblin-verify, by
+# design: an automatic re-pin would be the silent edit the pin exists to catch.
+# See docs/CONTRACTS.md, "An edited standard is not a dead end".
+if [ "$RE_PIN" -eq 1 ]; then
+  [ -f "$CONFIG" ] || { g_err "nothing to re-pin: $CONFIG is absent (install first)"; exit 2; }
+  PIN_PATH=$(g_expand_tilde "$(g_yaml_scalar "$CONFIG" practice)")
+  [ -n "$PIN_PATH" ] || { g_err "no practice: recorded in $CONFIG — nothing to re-pin"; exit 2; }
+  [ -f "$PIN_PATH" ] || { g_err "the recorded standard is absent: $PIN_PATH"; exit 2; }
+  grep -q '^practice_sha256:' "$CONFIG" || { g_err "no practice_sha256: line in $CONFIG to rewrite"; exit 2; }
+  # g_unquote, exactly as goblin-verify reads it: a hand-quoted value is accepted by the verifier,
+  # so it must not read as "different" here and trigger a rewrite of a line that already matches.
+  OLD_SHA=$(g_unquote "$(g_yaml_scalar "$CONFIG" practice_sha256)")
+  NEW_SHA=$(g_sha256_file "$PIN_PATH")
+  if [ "$OLD_SHA" = "$NEW_SHA" ]; then
+    g_info "practice pin already current: $PIN_PATH"
+    g_info "  recorded $OLD_SHA"
+    exit 0
+  fi
+  if [ "$DRY_RUN" -eq 1 ]; then
+    g_info "would re-pin $PIN_PATH"
+    g_info "  recorded $OLD_SHA"
+    g_info "  now      $NEW_SHA"
+    exit 0
+  fi
+  # One line, in place. Every other line of the config - comments included - is untouched, so
+  # the `owned` contract holds for everything except the single value just asked for.
+  sed -i "s|^practice_sha256:.*|practice_sha256: $NEW_SHA|" "$CONFIG" \
+    || { g_err "could not rewrite the pin in $CONFIG"; exit 1; }
+  # Fail closed: never report a re-pin that did not land. The failure this command exists to
+  # remove is a hash nobody verified (measured at bf7e9c9: sed -i could not write to a read-only
+  # .goblin/, yet the branch printed "practice re-pinned" with both hashes and exited 0, leaving
+  # IN-02 RED and the config byte-identical).
+  grep -qxF "practice_sha256: $NEW_SHA" "$CONFIG" \
+    || { g_err "the new pin did not land in $CONFIG"; exit 1; }
+  g_info "practice re-pinned: $PIN_PATH"
+  g_info "  recorded $OLD_SHA"
+  g_info "  now      $NEW_SHA"
+  g_info ""
+  g_info "next:"
+  g_info "  1. cd $TARGET && git add .goblin/goblin.yaml && git commit   # the re-pin is a change like any other"
+  g_info "  2. .goblin/bin/goblin-verify --only IN-02   # practice pin ok"
+  exit 0
+fi
+
+[ -n "$CLASS" ] || { g_err "--class is required (A|B|C|D|E|F)"; exit 2; }
+case "$CLASS" in A|B|C|D|E|F) ;; *) g_err "--class must be one of A B C D E F, got '$CLASS'"; exit 2 ;; esac
+case "$SKILLS" in yes|no) ;; *) g_err "--skills must be yes or no"; exit 2 ;; esac
+
+PRESET=$(ls "$SRC"/presets/"$CLASS"-*.yaml 2>/dev/null | head -n 1)
+[ -n "$PRESET" ] || { g_err "no preset for class $CLASS"; exit 2; }
+
+preset() { local v; v=$(g_yaml_scalar "$PRESET" "$1"); printf '%s' "${v%\"}" | sed 's/^"//'; }
+
+HARNESS_DIR=$(preset harness_dir); [ -n "$HARNESS_DIR" ] || HARNESS_DIR=checks
+SCAFFOLD=$(preset scaffold_checks); [ -n "$SCAFFOLD" ] || SCAFFOLD=no
+GATE_NAME=$(preset gate_name)
+GATE_CMD=$(preset gate_cmd)
+RAT_NAME=$(preset ratchet_name)
+RAT_CMD=$(preset ratchet_cmd)
+RAT_CEIL=$(preset ratchet_ceiling)
+REPLAY_ENV=$(preset replay_env)
+REPLAY_CMD=$(preset replay_cmd)
+RUNTIME_DATA=$(preset runtime_data)
+ADV_CEILING=$(preset advisory_ceiling); [ -n "$ADV_CEILING" ] || ADV_CEILING=10
+# The loop ceiling (G2, LP-03) is a CEILING, not a per-class policy: every class gets the same
+# one, defaulted to the engine's own DEFAULT_MAX_TURNS when a preset predates the key.
+LOOP_MAX_TURNS=$(preset loop_max_turns_ceiling); [ -n "$LOOP_MAX_TURNS" ] || LOOP_MAX_TURNS=20
+# The optional second gate (class A: the TODO ceiling). Empty for every other class.
+GATE2_NAME=$(preset gate2_name)
+GATE2_CMD=$(preset gate2_cmd)
+# The security surface (SC-01..SC-09) and the perf baseline (PF-01).
+SEC_GITIGNORE_FAMILY=$(preset sec_gitignore_family); [ -n "$SEC_GITIGNORE_FAMILY" ] || SEC_GITIGNORE_FAMILY=no
+SEC_BUILD_OUTPUT=$(preset sec_build_output)
+SEC_AUDIT_CMD=$(preset sec_audit_cmd)
+SEC_AUDIT_MAX_AGE=$(preset sec_audit_max_age_days); [ -n "$SEC_AUDIT_MAX_AGE" ] || SEC_AUDIT_MAX_AGE=90
+SEC_WAIVER_MAX_AGE=$(preset sec_waiver_max_age_days); [ -n "$SEC_WAIVER_MAX_AGE" ] || SEC_WAIVER_MAX_AGE=180
+SEC_WRITE_ROUTES=$(preset sec_write_routes)
+PERF_METRIC=$(preset perf_metric)
+PERF_CMD=$(preset perf_cmd)
+PERF_BASELINE_COMMIT=$(preset perf_baseline_commit)
+PERF_BASELINE_VALUE=$(preset perf_baseline_value); [ -n "$PERF_BASELINE_VALUE" ] || PERF_BASELINE_VALUE=0
+PERF_MEASURED=$(preset perf_measured)
+PERF_HOST_GATE=$(preset perf_host_gate)
+# The ban list (G5): which bans this class turns on. An unlisted ban SKIPs with a reason.
+BANS=$(preset bans)
+# `layers:` is a block list the project declares; no preset ships one, so it renders empty and
+# BN-05 SKIPs with that reason until the project declares a from/to pair.
+LAYERS_BLOCK=""
+
+need() { g_class_need "$CLASSES_TSV" "$CLASS" "$1"; }
+
+# parts that are OFF for this class become real opt-outs, not silent absences
+DISABLED=""
+for p in handoff spec gate replay ratchet pr-gate review-panel playbooks tokens ci-gate; do
+  [ "$(need "$p")" = "-" ] && DISABLED="$DISABLED$p,"
+done
+[ "$SKILLS" = "no" ] && DISABLED="$DISABLED""playbooks,"
+if [ -n "$OPT_OUT" ]; then DISABLED="$DISABLED$OPT_OUT,"; fi
+DISABLED=$(printf '%s' "$DISABLED" | tr ',' '\n' | grep -v '^$' | sort -u | paste -sd, -)
+# The automation producers ride the `playbooks` part (they are the shipped automation files, and
+# --skills no disables that part), so they are written under exactly the condition that makes
+# AU-01..AU-04 and SK-04 honour an opt-out.
+PLAYBOOKS_ON=1
+case ",$DISABLED," in *,playbooks,*) PLAYBOOKS_ON=0 ;; esac
+# parts the class forbids are never installed
+for p in spec replay ratchet pr-gate; do
+  [ "$(need "$p")" = "-" ] && SCAFFOLD=no
+done
+
+WANT_SPEC=1; [ "$(need spec)" = "-" ] && WANT_SPEC=0
+WANT_REVIEWS=0
+case "$(need pr-gate)$(need review-panel)" in *R*|*O*) WANT_REVIEWS=1 ;; esac
+WANT_RATCHET=1; [ "$(need ratchet)" = "-" ] && WANT_RATCHET=0
+# The CI lane (G6 A.6). Installed for a class that requires or permits it (A, C, E, F) and never
+# for one that forbids it (B, D) - where CL-01 then requires the file to be ABSENT, which is why
+# class_part_artifact keys off this exact path rather than off .github/workflows/.
+WANT_CI_GATE=1; [ "$(need ci-gate)" = "-" ] && WANT_CI_GATE=0
+[ "$ARCHIVE" = "true" ] && { WANT_SPEC=0; WANT_REVIEWS=0; SCAFFOLD=no; }
+
+OWNER_EMAIL=$( cd "$TARGET" && git config user.email 2>/dev/null )
+[ -n "$OWNER_EMAIL" ] || OWNER_EMAIL="you@example.com"
+BRANCH=$( cd "$TARGET" && git rev-parse --abbrev-ref HEAD 2>/dev/null )
+case "$BRANCH" in ""|HEAD) BRANCH=main ;; esac
+HEAD_SHORT=$( cd "$TARGET" && git rev-parse --short HEAD 2>/dev/null )
+[ -n "$HEAD_SHORT" ] || HEAD_SHORT="0000000"
+
+# practice pin
+if [ -f "$(g_expand_tilde "$PRACTICE")" ]; then
+  PRACTICE_SHA=$(g_sha256_file "$(g_expand_tilde "$PRACTICE")")
+else
+  # W5-3: an explicitly named --practice that does not resolve is REPORTED, not swallowed. The
+  # pin stays empty (a repo with no referenced standard is legitimate), but a flag nobody honours
+  # has to say so - `practice: ~` with no line in the log is the "silent no-op" species.
+  if [ -n "$PRACTICE_ARG" ]; then
+    g_info "warning: --practice $PRACTICE_ARG does not exist - no standard is referenced"
+    g_info "         (practice: and practice_sha256: stay empty in .goblin/goblin.yaml)"
+  fi
+  PRACTICE=""
+  PRACTICE_SHA=""
+fi
+
+# ratchet ceiling: measured at install time, so the ratchet starts anchored to reality
+if [ "$RAT_CEIL" = "measure" ]; then
+  RAT_CEIL=$( cd "$TARGET" && bash -c "$RAT_CMD" 2>/dev/null | tr -d '[:space:]' )
+  case "$RAT_CEIL" in ''|*[!0-9]*) RAT_CEIL=0 ;; esac
+fi
+[ "$WANT_RATCHET" -eq 0 ] && { RAT_NAME=""; RAT_CMD=""; RAT_CEIL=0; }
+# A part the class turns off must not be declared either: leaving replay.env/replay.cmd in the
+# config made CL-01's "class forbids this part" branch fire on the installer's own output (D10).
+[ "$(need replay)" = "-" ] && { REPLAY_ENV=""; REPLAY_CMD=""; }
+
+# parts selected with --parts
+part_wanted() {
+  [ -z "$PARTS" ] && return 0
+  case ",$PARTS," in *",$1,"*) return 0 ;; esac
+  return 1
+}
+
+# ------------------------------------------------------------------ plan -----
+TMP=$(mktemp -d)
+trap 'rm -rf "$TMP"' EXIT
+: > "$TMP/files.tsv"
+: > "$TMP/owned.tsv"
+: > "$TMP/refused.tsv"
+CREATED=0; UPDATED=0; UNCHANGED=0; SKIPPED=0
+REFUSED_PATHS=""
+# Files a PREVIOUS run created and left to the user (never overwritten, never hash-checked).
+PREV_OWNED=""
+# Files a PREVIOUS run installed (the hash-checked 'files' map). A path that exists on disk
+# but is NOT in this map was not created by goblin-stack, so it is refused rather than
+# clobbered - the contract in docs/CONTRACTS.md. --force is the only way past it.
+PREV_FILES=""
+if [ -f "$INSTALLED" ]; then
+  PREV_OWNED=$(g_json_object "$INSTALLED" owned | cut -f1)
+  PREV_FILES=$(g_installed_files "$INSTALLED" | cut -f1)
+fi
+
+# prev_installed <relpath> - did a previous run install this exact path?
+prev_installed() {
+  [ -n "$PREV_FILES" ] || return 1
+  printf '%s\n' "$PREV_FILES" | grep -qxF "$1"
+}
+
+render() { # render <template> key value [key value ...]
+  local tpl="$1"; shift
+  local out; out=$(cat "$tpl")
+  while [ $# -ge 2 ]; do out=${out//"{{$1}}"/$2}; shift 2; done
+  printf '%s\n' "$out"
+}
+
+# put <relpath> <source-file> [refuse-overwrite]
+# Refuses when the destination exists with different content and goblin-stack did not install
+# it: either the caller asked for it explicitly ('refuse') or the path is not in the previous
+# run's 'files' map. --force is the documented override.
+put() {
+  local rel="$1" srcf="$2" refuse="${3:-}"
+  local dst="$TARGET/$rel" srch cur
+  srch=$(g_sha256_file "$srcf")
+  if [ -f "$dst" ]; then
+    cur=$(g_sha256_file "$dst")
+    if [ "$cur" = "$srch" ]; then
+      UNCHANGED=$((UNCHANGED + 1))
+      printf '%s\t%s\n' "$rel" "$srch" >> "$TMP/files.tsv"
+      return 0
+    fi
+    if [ "$FORCE" -eq 0 ] && { [ "$refuse" = "refuse" ] || ! prev_installed "$rel"; }; then
+      SKIPPED=$((SKIPPED + 1))
+      printf '%s\t%s\n' "$rel" "$cur" >> "$TMP/refused.tsv"
+      REFUSED_PATHS="$REFUSED_PATHS $rel"
+      g_info "kept (exists, not installed by goblin-stack): $rel"
+      return 0
+    fi
+    UPDATED=$((UPDATED + 1))
+  else
+    CREATED=$((CREATED + 1))
+  fi
+  if [ "$DRY_RUN" -eq 1 ]; then g_info "plan: $rel"; else
+    mkdir -p "$(dirname "$dst")"
+    cp "$srcf" "$dst"
+    [ -x "$srcf" ] && chmod +x "$dst"
+  fi
+  printf '%s\t%s\n' "$rel" "$srch" >> "$TMP/files.tsv"
+}
+
+# put_once <relpath> <source-file> — created once, then YOURS. Never overwritten, never
+# hash-checked (you are meant to edit it), and left in place by --uninstall.
+put_once() {
+  local rel="$1" srcf="$2"
+  local dst="$TARGET/$rel" srch cur
+  srch=$(g_sha256_file "$srcf")
+  if [ -f "$dst" ] && [ "$FORCE" -eq 1 ] && ! printf '%s\n' "$PREV_OWNED" | grep -qxF "$rel"; then
+    # --force is the documented override for "a file goblin-stack did not create" (D11). A file
+    # a previous install created is 'yours' by contract, and --force does not take it back.
+    UPDATED=$((UPDATED + 1))
+    g_info "taken over (--force): $rel"
+    if [ "$DRY_RUN" -eq 0 ]; then cp "$srcf" "$dst"; fi
+    printf '%s\t%s\n' "$rel" "$srch" >> "$TMP/owned.tsv"
+    return 0
+  fi
+  if [ -f "$dst" ]; then
+    SKIPPED=$((SKIPPED + 1))
+    if printf '%s\n' "$PREV_OWNED" | grep -qxF "$rel"; then
+      g_info "kept (yours, never overwritten): $rel"
+      # Still recorded as yours, so the next install keeps treating it that way.
+      printf '%s\t%s\n' "$rel" "$srch" >> "$TMP/owned.tsv"
+    else
+      cur=$(g_sha256_file "$dst")
+      printf '%s\t%s\n' "$rel" "$cur" >> "$TMP/refused.tsv"
+      REFUSED_PATHS="$REFUSED_PATHS $rel"
+      g_info "kept (existed before the install, never overwritten): $rel"
+    fi
+    # A refused file is NOT recorded as owned: it was never goblin-stack's, so a later run
+    # must refuse it again rather than inherit ownership of it (D11).
+    return 0
+  fi
+  CREATED=$((CREATED + 1))
+  if [ "$DRY_RUN" -eq 1 ]; then
+    g_info "plan: $rel"
+  else
+    mkdir -p "$(dirname "$dst")"
+    cp "$srcf" "$dst"
+  fi
+  printf '%s\t%s\n' "$rel" "$srch" >> "$TMP/owned.tsv"
+}
+
+# ------------------------------------------------------- generated content ---
+render_config() {
+  local gates runtime
+  gates="  - name: $GATE_NAME
+    cmd: $GATE_CMD"
+  # A class may declare a second gate (A: the TODO ceiling that used to be the ratchet, G4 D2).
+  if [ -n "$GATE2_NAME" ] && [ -n "$GATE2_CMD" ]; then
+    gates="$gates
+  - name: $GATE2_NAME
+    cmd: $GATE2_CMD"
+  fi
+  runtime="  - $RUNTIME_DATA"
+  render "$SRC/templates/goblin.yaml.tmpl" \
+    CLASS "$CLASS" \
+    BRANCH "$BRANCH" \
+    MODELS_FILE "$MODELS" \
+    PRACTICE "$PRACTICE" \
+    PRACTICE_SHA "$PRACTICE_SHA" \
+    OWNER_EMAIL "$OWNER_EMAIL" \
+    ARCHIVE "$ARCHIVE" \
+    MAX_DIRTY "0" \
+    ADVISORY_CEILING "$ADV_CEILING" \
+    SEC_GITIGNORE_FAMILY "$SEC_GITIGNORE_FAMILY" \
+    SEC_BUILD_OUTPUT "$SEC_BUILD_OUTPUT" \
+    SEC_AUDIT_CMD "$SEC_AUDIT_CMD" \
+    SEC_AUDIT_MAX_AGE "$SEC_AUDIT_MAX_AGE" \
+    SEC_WAIVER_MAX_AGE "$SEC_WAIVER_MAX_AGE" \
+    SEC_WRITE_ROUTES "$SEC_WRITE_ROUTES" \
+    PERF_METRIC "$PERF_METRIC" \
+    PERF_CMD "$PERF_CMD" \
+    PERF_BASELINE_COMMIT "$PERF_BASELINE_COMMIT" \
+    PERF_BASELINE_VALUE "$PERF_BASELINE_VALUE" \
+    PERF_MEASURED "$PERF_MEASURED" \
+    PERF_HOST_GATE "$PERF_HOST_GATE" \
+    HARNESS_DIR "$HARNESS_DIR" \
+    SCAFFOLD_CHECKS "$SCAFFOLD" \
+    FEATURE_MAP "" \
+    SOURCE_ROOT "." \
+    VERIFY_DOCTOR "" \
+    REFERENCE_MANIFEST "" \
+    QUARANTINE_ROOT "" \
+    LOOP_MAX_TURNS "$LOOP_MAX_TURNS" \
+    GATES "$gates" \
+    RATCHET_NAME "$RAT_NAME" \
+    RATCHET_CMD "$RAT_CMD" \
+    RATCHET_CEILING "$RAT_CEIL" \
+    RUNTIME_DATA "$runtime" \
+    BANS "$BANS" \
+    BANS_EXEMPT "" \
+    LAYERS "$LAYERS_BLOCK" \
+    REPLAY_ENV "$REPLAY_ENV" \
+    REPLAY_CMD "$REPLAY_CMD" \
+    DISABLED "$DISABLED" > "$TMP/goblin.yaml"
+}
+
+render_config
+# The re-shadow refusal (W3 §5.3): a record with engine.mode=global is a MIGRATED repo.
+# Re-installing would recreate the 18-file payload (the vendored step of the resolution
+# chain then beats the declared engine_dir — the shadowing hazard, W3-SPEC §3.1) AND
+# rewrite the record from scratch, silently de-migrating it. The writer below has no
+# engine:-block support, so the rewrite is not a migration-aware update — it is a
+# regression. The exits out of a migrated repo are `git revert` of the migration's two
+# commits, or a hand edit of the engine_dir line (docs/GUIDE.md "Rolling back a
+# migration"). DRY_RUN reports the refusal too: the plan it prints is not shippable.
+# The guard sits BEFORE the put-loop: a refusal that fires after the payload phase has
+# already re-created the 18 files is a refusal that itself shadows (measured: U11's
+# 'the refused install wrote nothing' failed on exactly that).
+g_install_engine_mode() {
+  awk -v q='"' -v k="mode" '
+    index($0, q "engine" q) && /:[[:space:]]*\{/ { inf = 1; next }
+    inf && /^[[:space:]]*\}/ { inf = 0 }
+    inf && index($0, q k q) {
+      v = $0; sub(/^[^:]*:[[:space:]]*/, "", v); sub(/,?[[:space:]]*$/, "", v)
+      gsub(q, "", v); print v; exit
+    }
+  ' "$1" 2>/dev/null
+}
+if [ -f "$INSTALLED" ] && [ "$(g_install_engine_mode "$INSTALLED")" = "global" ]; then
+  g_rec_engine_dir=$(awk -v q='"' '
+    index($0, q "engine" q) && /:[[:space:]]*\{/ { inf = 1; next }
+    inf && /^[[:space:]]*\}/ { inf = 0 }
+    inf && index($0, q "engine_dir" q) {
+      v = $0; sub(/^[^:]*:[[:space:]]*/, "", v); sub(/,?[[:space:]]*$/, "", v)
+      gsub(q, "", v); print v; exit
+    }
+  ' "$INSTALLED")
+  g_err "goblin-install: $TARGET is migrated to the global engine at ${g_rec_engine_dir:-<unknown>}. Re-installing would re-shadow it and rewrite its migration record. To return to a vendored engine: git revert the two W3 commits (see docs/GUIDE.md \"Rolling back a migration\"). To re-point at a different engine: edit .goblin/goblin.yaml's engine_dir line."
+  exit 1
+fi
+
+put ".goblin/bin/goblin-verify" "$SRC/bin/goblin-verify"
+put ".goblin/bin/goblin-lib.sh" "$SRC/bin/goblin-lib.sh"
+# The audit record is produced by a DELIBERATE, separate command - SC-07 reads the record and
+# never the network (RISKS.md K4: no network at verify time).
+put ".goblin/bin/goblin-audit" "$SRC/bin/goblin-audit"
+put ".goblin/roles.yaml" "$SRC/roles.yaml"
+put ".goblin/manifest/enforcement.tsv" "$SRC/manifest/enforcement.tsv"
+put ".goblin/manifest/playbooks.tsv" "$SRC/manifest/playbooks.tsv"
+put ".goblin/manifest/classes.tsv" "$SRC/manifest/classes.tsv"
+put ".goblin/manifest/glossary.tsv" "$SRC/manifest/glossary.tsv"
+# The ban list (G5): the table, the engine, and the two probes. A ban with no mechanism is a
+# wish, so the table and the engine install together or not at all.
+put ".goblin/manifest/bans.tsv" "$SRC/manifest/bans.tsv"
+put ".goblin/bin/goblin-bans" "$SRC/bin/goblin-bans"
+put ".goblin/bans/README.md" "$SRC/bans/README.md"
+put ".goblin/bans/grep-ban.sh" "$SRC/bans/grep-ban.sh"
+put ".goblin/bans/layer-check.sh" "$SRC/bans/layer-check.sh"
+put_once ".goblin/goblin.yaml" "$TMP/goblin.yaml"
+# The security lane's two decision records and the audit allowlist are created once, then YOURS:
+# they are answers to questions only the project can answer (G4 B3).
+[ -f "$SRC/templates/audit-waiver.tsv.tmpl" ] && put_once ".goblin/audit-waiver.tsv" "$SRC/templates/audit-waiver.tsv.tmpl"
+[ -f "$SRC/templates/boundary-waivers.tmpl" ] && put_once ".goblin/boundary-waivers" "$SRC/templates/boundary-waivers.tmpl"
+[ -f "$SRC/templates/install-hooks.allowlist.tmpl" ] && put_once ".goblin/install-hooks.allowlist" "$SRC/templates/install-hooks.allowlist.tmpl"
+
+if [ "$SKILLS" = "yes" ] && part_wanted playbooks; then
+  for d in "$SRC"/skills/*/; do
+    [ -d "$d" ] || continue
+    name=$(basename "$d")
+    put ".hermes/skills/$name/SKILL.md" "$d/SKILL.md"
+  done
+fi
+
+# The automation producers. They land in the target so the target is self-contained and
+# IN-02/SK-02 hash them like every other installed file; the cron copy step then reads from
+# here (see the "next:" block and automations/README.md).
+if [ "$PLAYBOOKS_ON" -eq 1 ] && part_wanted playbooks; then
+  for f in "$SRC"/automations/drift-audit.sh "$SRC"/automations/bugreporter-intake.sh \
+           "$SRC"/automations/README.md "$SRC"/automations/report.schema.tsv; do
+    [ -f "$f" ] || continue
+    put ".goblin/automations/$(basename "$f")" "$f"
+  done
+  if [ -f "$SRC/templates/report.yaml.tmpl" ]; then
+    put ".goblin/automations/report.yaml.tmpl" "$SRC/templates/report.yaml.tmpl"
+  fi
+fi
+
+if [ "$WANT_SPEC" -eq 1 ] && part_wanted spec; then
+  render "$SRC/templates/SPEC.md.tmpl" CLASS "$CLASS" DATE "$STAMP" > "$TMP/spec"
+  put_once "ROUND-000-SPEC.md" "$TMP/spec"
+fi
+if [ "$ARCHIVE" != "true" ] && part_wanted handoff; then
+  render "$SRC/templates/HANDOFF.md.tmpl" CLASS "$CLASS" DATE "$STAMP" HEAD "$HEAD_SHORT" BRANCH "$BRANCH" GATE_NAME "$GATE_NAME" GATE_CMD "$GATE_CMD" > "$TMP/handoff"
+  put_once "HANDOFF.md" "$TMP/handoff"
+fi
+render "$SRC/templates/AGENTS.md.tmpl" CLASS "$CLASS" DATE "$STAMP" > "$TMP/agents"
+put_once "AGENTS.md" "$TMP/agents"
+
+if [ "$WANT_REVIEWS" -eq 1 ]; then
+  printf '# Review verdicts live here: reviews/<slug>-<head7>.md, each naming the SHA it reviewed.\n' > "$TMP/gitkeep"
+  put_once "reviews/.gitkeep" "$TMP/gitkeep"
+fi
+
+# The CI lane (G6): one workflow, rendered and placed. The header of the template states what
+# makes a workflow a GATE (a required check, no admin bypass, a push identity that is not the
+# repo's sole admin) - because a workflow file nobody is bound by is decoration. The job carries
+# no `if:` at any level, so PG-05 passes on goblin-stack's own output.
+if [ "$WANT_CI_GATE" -eq 1 ] && part_wanted ci-gate && [ -f "$SRC/templates/ci/goblin-gate.yml.tmpl" ]; then
+  render "$SRC/templates/ci/goblin-gate.yml.tmpl" CLASS "$CLASS" BRANCH "$BRANCH" DATE "$STAMP" > "$TMP/gate.yml"
+  put ".github/workflows/goblin-gate.yml" "$TMP/gate.yml"
+fi
+
+if [ "$SCAFFOLD" = "yes" ]; then
+  put "$HARNESS_DIR/gate.sh" "$SRC/templates/checks/gate.sh.tmpl"
+  put "$HARNESS_DIR/assert.mjs" "$SRC/templates/checks/assert.mjs.tmpl"
+fi
+
+# .gitignore: one appended block, delimited by markers; never rewritten. The declared
+# runtime_data paths are listed too, because DS-01 asserts each of them is git-ignored.
+GI_MARK="# >>> goblin-stack >>>"
+if [ -f "$TARGET/.gitignore" ] && grep -qF "$GI_MARK" "$TARGET/.gitignore"; then
+  SKIPPED=$((SKIPPED + 1))
+  g_info "kept (.gitignore block already present)"
+else
+  {
+    [ -f "$TARGET/.gitignore" ] && cat "$TARGET/.gitignore"
+    printf '\n%s\n' "$GI_MARK"
+    printf '# goblin-stack runtime state (gates write these; they are not fixture)\n'
+    printf '.goblin/last-gate-line\n.goblin/.ds-report\n.goblin/ratchet-last\n'
+    if [ "$SEC_GITIGNORE_FAMILY" = "yes" ]; then
+      # SC-02: the whole secret family, not one member of it. The row is behavioural - it asks
+      # git's own matcher (`git check-ignore`) rather than reading this file - so a rule that
+      # looks right but does not match still fails.
+      printf '# the secret family (SC-02): each is one `git add` away from a live credential\n'
+      printf '.env\n.env.*\n*.pem\n*.key\n'
+    fi
+    if [ -n "$RUNTIME_DATA" ]; then
+      printf '# declared runtime_data (DS-01 hashes them around every gate run)\n'
+      printf '%s\n' "$RUNTIME_DATA"
+    fi
+    printf '# <<< goblin-stack <<<\n'
+  } > "$TMP/gitignore.new"
+  if [ -f "$TARGET/.gitignore" ]; then UPDATED=$((UPDATED + 1)); else CREATED=$((CREATED + 1)); fi
+  # Counted in --dry-run too: the plan must name every write it would make (D14).
+  if [ "$DRY_RUN" -eq 0 ]; then cp "$TMP/gitignore.new" "$TARGET/.gitignore"; fi
+fi
+
+# installed.json is the record; it is written LAST and never lists itself
+{
+  printf '{\n'
+  printf '  "version": "%s",\n' "$VERSION"
+  printf '  "source_sha": "%s",\n' "$( cd "$SRC" && git rev-parse HEAD 2>/dev/null || echo unknown )"
+  printf '  "class": "%s",\n' "$CLASS"
+  printf '  "installed_at": "%s",\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+  printf '  "options": {"skills": "%s", "archive": %s, "parts": "%s"},\n' "$SKILLS" "$ARCHIVE" "${PARTS:-all}"
+  printf '  "files": {\n'
+  awk -F'\t' 'NF==2 {printf "    \"%s\": \"%s\",\n", $1, $2}' "$TMP/files.tsv" | sed '$ s/,$//'
+  printf '  },\n'
+  printf '  "owned": {\n'
+  awk -F'\t' 'NF==2 {printf "    \"%s\": \"%s\",\n", $1, $2}' "$TMP/owned.tsv" | sed '$ s/,$//'
+  printf '  },\n'
+  printf '  "refused": {\n'
+  awk -F'\t' 'NF==2 {printf "    \"%s\": \"%s\",\n", $1, $2}' "$TMP/refused.tsv" | sed '$ s/,$//'
+  printf '  }\n'
+  printf '}\n'
+} > "$TMP/installed.json"
+
+PREV_VERSION=""
+if [ -f "$INSTALLED" ]; then PREV_VERSION=$(g_installed_scalar "$INSTALLED" version); fi
+
+
+if [ "$DRY_RUN" -eq 0 ]; then
+  mkdir -p "$TARGET/.goblin"
+  if [ "$CREATED" -eq 0 ] && [ "$UPDATED" -eq 0 ] && [ "$PREV_VERSION" = "$VERSION" ]; then
+    g_info "no-op: $UNCHANGED files unchanged (v$VERSION already installed)"
+  else
+    cp "$TMP/installed.json" "$INSTALLED"
+    if [ -n "$PREV_VERSION" ] && [ "$PREV_VERSION" != "$VERSION" ]; then
+      g_info "upgraded $PREV_VERSION -> $VERSION"
+    fi
+    g_info "created $CREATED · updated $UPDATED · unchanged $UNCHANGED · skipped $SKIPPED"
+  fi
+  if [ -n "$OPT_OUT" ]; then
+    for p in $(printf '%s' "$OPT_OUT" | tr ',' ' '); do
+      if grep -q "^disabled:" "$CONFIG"; then
+        cur=$(g_yaml_scalar "$CONFIG" disabled)
+        cur=${cur#[}; cur=${cur%]}
+        new=$(printf '%s,%s' "$cur" "$p" | tr ',' '\n' | grep -v '^$' | sort -u | paste -sd, -)
+        sed -i "s|^disabled:.*|disabled: [$new]|" "$CONFIG"
+      fi
+    done
+    g_info "recorded opt-out: $OPT_OUT"
+  fi
+  g_info ""
+  g_info "next:"
+  g_info "  1. cd $TARGET && git add -A && git commit   # the install is a change like any other"
+  g_info "  2. .goblin/bin/goblin-verify   # or add .goblin/bin to PATH"
+  g_info "  3. edit .goblin/goblin.yaml: replace the default gate with your real commands (P8 step 3)"
+  if [ "$SKILLS" = "yes" ]; then
+    g_info "  4. hermes skills trust $TARGET   # one-time, so the project-tier skills load"
+  fi
+  g_info ""
+  g_info "automations (optional; neither writes outside this repo, and A-02 has no agent in it):"
+  g_info "  bash $TARGET/.goblin/automations/drift-audit.sh --dry-run        # read the record first"
+  g_info "  cp $TARGET/.goblin/automations/drift-audit.sh ~/.hermes/scripts/"
+  g_info "  hermes cron create \"0 9 * * 1\" --name \"Drift audit - weekly\" --no-agent \\"
+  g_info "      --script drift-audit.sh --deliver <channel>"
+  g_info "  P13/P14 in docs/FLOWS.md; the whole model in automations/README.md"
+else
+  g_info "dry-run: created $CREATED · updated $UPDATED · unchanged $UNCHANGED · skipped $SKIPPED"
+fi
+
+if [ -n "$REFUSED_PATHS" ]; then
+  g_info "refused to overwrite:$REFUSED_PATHS (kept - reconcile it: docs/ADOPTION.md; --force would destroy it)"
+  # Documented contract (docs/CONTRACTS.md, this file's header): exit 1 is "a refusal, with
+  # the path and the fix". A wrapper has to be able to detect it (D2).
+  exit 1
+fi
+exit 0