chore(githooks): lint changed nomarchy-* scripts on commit

Adds two-tier linting before the existing docs/SCRIPTS.md regenerate
step:

- bash -n on every changed nomarchy-* script. Catches syntax errors
  that would otherwise be discovered at runtime by an unlucky user.
  Always fatal.
- shellcheck --severity=error when shellcheck is on PATH. Catches
  unquoted-var, use-before-define, missing-shebang, and other
  bug-shaped patterns. Only error-level issues block - the long
  tail of pre-existing warnings stays as a known cleanup task,
  not a commit blocker. Hook silently skips this step when
  shellcheck isn't installed (so contributors without it can still
  commit).

Catches the class of bug that's bit us repeatedly: a script ships,
the runtime path that exercises the broken line is rare, and the bug
sits latent until a user trips it. Cheaper to catch at commit time.

Caveat: 156 nomarchy-* scripts already have shellcheck warnings
(severity warning/info/style); we deliberately ship around them via
the --severity=error gate. A future per-script audit can dial the
severity up as scripts get cleaned up.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

.githooks/pre-commit

@@ -4,9 +4,12 @@
 # Enable per-clone with:
 #   git config core.hooksPath .githooks
 #
-# Re-runs the script audit generator when any nomarchy-* script in the three
+# Two responsibilities:
-# script directories is added, modified, or deleted in this commit, then
+#  1. Lint changed nomarchy-* scripts (bash -n + shellcheck if available)
-# stages the refreshed docs/SCRIPTS.md so it lands together with the change.
+#     so syntax errors and unquoted-var bugs don't ship.
+#  2. Regenerate docs/SCRIPTS.md when any nomarchy-* script under the three
+#     script directories is added, modified, or deleted in this commit, and
+#     stage the refreshed file so it lands with the change.
 
 set -e
 
@@ -15,6 +18,31 @@ cd "$repo_root"
 
 script_dirs_re='^(features/scripts/utils|core/system/scripts|themes/engine/scripts)/nomarchy-'
 
+# 1. Lint changed scripts. bash -n catches syntax errors (always fatal).
+# shellcheck catches unquoted-var, use-before-define, missing-shebang, etc.
+# We only fail on severity=error so the long tail of pre-existing warnings
+# (info / style / warning) doesn't block commits — those can be cleaned up
+# incrementally without a flag day.
+changed_scripts=$(git diff --cached --name-only --diff-filter=ACMR \
+                  | grep -E "$script_dirs_re" || true)
+if [[ -n "$changed_scripts" ]]; then
+  while IFS= read -r script; do
+    [[ -f "$script" ]] || continue
+    if ! bash -n "$script"; then
+      echo "pre-commit: bash syntax error in $script — aborting commit." >&2
+      exit 1
+    fi
+    if command -v shellcheck >/dev/null 2>&1; then
+      if ! shellcheck --severity=error --shell=bash "$script"; then
+        echo "pre-commit: shellcheck found error-level issues in $script — aborting commit." >&2
+        echo "pre-commit: fix the reported issues, or rerun with --no-verify after a deliberate decision to ship." >&2
+        exit 1
+      fi
+    fi
+  done <<< "$changed_scripts"
+fi
+
+# 2. Regenerate the script audit doc.
 if git diff --cached --name-only --diff-filter=ACMRD | grep -qE "$script_dirs_re"; then
   echo "pre-commit: regenerating docs/SCRIPTS.md (script change detected)…"
   ./bin/utils/nomarchy-docs-scripts --out docs/SCRIPTS.md