feat: Add lockfile guard workflow to prevent unintended lockfile changes

Author: SyedFahad7

.github/PULL_REQUEST_TEMPLATE.md

@@ -24,6 +24,7 @@ _Add screenshots of relevant screens_
 
 - [ ] My PR follows the style guidelines of this project
 - [ ] I have performed a self-check on my work
+- [ ] If `package.json` is unchanged, `package-lock.json` is also unchanged in this PR
 
 **If changes are made in the code:**
 

.github/workflows/lockfile-guard.yml

@@ -0,0 +1,51 @@
+name: Lockfile Guard
+
+on:
+  pull_request:
+    branches:
+      - develop
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  lockfile-guard:
+    name: Prevent unintended lockfile churn
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Validate package and lockfile changes
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          BASE_SHA="${{ github.event.pull_request.base.sha }}"
+          HEAD_SHA="${{ github.event.pull_request.head.sha }}"
+
+          CHANGED_FILES="$(git diff --name-only "$BASE_SHA" "$HEAD_SHA")"
+
+          PACKAGE_CHANGED="false"
+          LOCK_CHANGED="false"
+
+          if echo "$CHANGED_FILES" | grep -qx "package.json"; then
+            PACKAGE_CHANGED="true"
+          fi
+
+          if echo "$CHANGED_FILES" | grep -qx "package-lock.json"; then
+            LOCK_CHANGED="true"
+          fi
+
+          if [ "$LOCK_CHANGED" = "true" ] && [ "$PACKAGE_CHANGED" = "false" ]; then
+            echo "❌ package-lock.json changed without package.json changes."
+            echo "If your PR does not intentionally change dependencies, discard lockfile changes:"
+            echo "git checkout -- package-lock.json"
+            exit 1
+          fi
+
+          echo "✅ Lockfile check passed."

CONTRIBUTING.md

@@ -47,6 +47,37 @@ If your work depends on unreleased features or changes, base your work directly
 
 ## Code Contributions
 
+### 🚨 Dependency & Lockfile Policy (Read Before PR!)
+
+**When to Commit `package-lock.json`**
+
+- **You MUST commit `package-lock.json` if:**
+	- You add, remove, or upgrade a dependency in `package.json` (for example, when your new tool needs a new npm package).
+	- You intentionally update any package version in `package.json`.
+	- After such changes, always run `npm install` and commit both `package.json` and `package-lock.json` together.
+
+- **You MUST NOT commit `package-lock.json` if:**
+	- You are only editing, adding, or refactoring tool components, UI, or logic, and did not touch `package.json`.
+	- You ran `npm install` after pulling latest develop, but did not change dependencies. If the lockfile changes, discard it (`git checkout -- package-lock.json`).
+
+- **Dependency/toolchain upgrades (Next.js, ESLint, etc.) must be in a separate PR, never mixed with feature/tool PRs.**
+
+**For Adding a New Tool:**
+
+- If your tool needs a new npm package:
+	1. Add the dependency to `package.json`.
+	2. Run `npm install` (this updates `package-lock.json`).
+	3. Commit both files in your PR.
+- If your tool does NOT need a new dependency, do NOT touch or commit `package-lock.json`.
+
+**Why?**
+
+- Our CI uses `npm ci`, which requires the lockfile to match `package.json` exactly.
+- Random lockfile churn (from different npm versions or accidental upgrades) causes huge, noisy diffs and can break builds.
+- Only the canonical lockfile in `develop` is valid.
+
+---
+
 Please ensure your pull request adheres to the following guidelines:
 
 - Search [open pull requests](https://github.com/betterbugs/dev-tools/pulls) to ensure your change hasn't already been submitted