From 2b5fe0f712b77e81dde7e2b8a756efe3f8084472 Mon Sep 17 00:00:00 2001
From: Adam Moussa <166072409+amoussa1229@users.noreply.github.com>
Date: Thu, 14 May 2026 18:25:10 -0400
Subject: [PATCH] Add pre-push hook for npm ci validation

Catches lock file drift locally before it breaks CI. Includes
install instructions in git-workflow.md.
---
 README.md       |  1 +
 git-workflow.md | 15 +++++++++++++++
 hooks/pre-push  | 19 +++++++++++++++++++
 3 files changed, 35 insertions(+)
 create mode 100755 hooks/pre-push

diff --git a/README.md b/README.md
index 1a48ee4..71bbd16 100644
--- a/README.md
+++ b/README.md
@@ -14,6 +14,7 @@ Engineering conventions and best practices for Sea Haven Industries.
 - [SAM Project Layout](sam-project-layout.md) -- standard directory structure for serverless projects
 - [Secrets and Configuration](secrets-and-config.md) -- Secrets Manager vs SSM Parameter Store
 - [CI/CD Pipelines](cicd.md) -- every deployable repo gets a pipeline, no manual deploys
+- [Git Hooks](hooks/) -- recommended pre-push and pre-commit hooks
 
 ## Contributing
 
diff --git a/git-workflow.md b/git-workflow.md
index e717cfb..236c62d 100644
--- a/git-workflow.md
+++ b/git-workflow.md
@@ -73,6 +73,21 @@ git push origin v1.2.0
 
 Start at `v0.1.0` for new projects. Move to `v1.0.0` when the interface is stable and has external consumers.
 
+## Git Hooks
+
+Recommended hooks live in [`hooks/`](hooks/) — copy them into `.git/hooks/` when setting up a project.
+
+| Hook | Purpose |
+|---|---|
+| `pre-push` | Runs `npm ci` to catch lock file drift before it breaks CI |
+
+Install for a Node.js project:
+
+```bash
+cp ~/Documents/repositories/engineering-handbook/hooks/pre-push .git/hooks/pre-push
+chmod +x .git/hooks/pre-push
+```
+
 ## Cleaning Up
 
 After a PR is merged:
diff --git a/hooks/pre-push b/hooks/pre-push
new file mode 100755
index 0000000..01021c6
--- /dev/null
+++ b/hooks/pre-push
@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# Pre-push hook: verify npm ci passes before pushing Node.js projects.
+# Catches lock file drift that would break CI.
+#
+# Install: cp hooks/pre-push .git/hooks/pre-push && chmod +x .git/hooks/pre-push
+
+set -euo pipefail
+
+if [[ ! -f package-lock.json ]]; then
+  exit 0
+fi
+
+echo "pre-push: running npm ci..."
+if ! npm ci --ignore-scripts --no-audit --no-fund 2>/dev/null; then
+  echo "pre-push: npm ci failed — lock file may be out of sync."
+  echo "Run: rm -rf node_modules package-lock.json && npm install"
+  exit 1
+fi
+echo "pre-push: npm ci passed."