1st commit

assets/hooks/pre-commit

@@ -1,14 +1,18 @@
 #!/usr/bin/env bash
+# Safety settings: exit on errors, treat unset variables as errors, and catch pipeline failures
 set -euo pipefail
 
+# Find and navigate to the git repo root (or current dir if not in a repo) so file paths work correctly regardless of where the commit command is run
 ROOT="$(git rev-parse --show-toplevel 2>/dev/null || echo ".")"
 cd "$ROOT"
 
 # -------- collect staged files ----------
+# Get list of staged added/modified files into STAGED array, exit early if none found
 mapfile -t STAGED < <(git diff --cached --name-only --diff-filter=AM || true)
 [ "${#STAGED[@]}" -eq 0 ] && exit 0
 
 # -------- tiny secret scan (fast, regex only) ----------
+# Abort commit if staged changes contain potential secrets (api keys, tokens, etc.) matching common patterns
 DIFF="$(git diff --cached)"
 if echo "$DIFF" | grep -Eqi '(api[_-]?key|secret|access[_-]?token|private[_-]?key)[:=]\s*[A-Za-z0-9_\-]{12,}'; then
   echo >&2 "[pre-commit] Possible secret detected in staged changes."
@@ -17,6 +21,7 @@ if echo "$DIFF" | grep -Eqi '(api[_-]?key|secret|access[_-]?token|private[_-]?ke
 fi
 
 # -------- ensure discussion summaries exist (companion files) ----------
+# Create and auto-stage a summary template file for any discussion file that doesn't already have one
 ensure_summary() {
   local disc="$1"
   local dir; dir="$(dirname "$disc")"
@@ -67,6 +72,7 @@ EOF
   fi
 }
 
+# Process each staged discussion file and ensure it has a summary
 for f in "${STAGED[@]}"; do
   case "$f" in
     Docs/features/*/discussions/*.discussion.md) ensure_summary "$f";;
@@ -74,6 +80,7 @@ for f in "${STAGED[@]}"; do
 done
 
 # -------- future orchestration (non-blocking status) ----------
+# Run workflow status check if available, but don't block commit if it fails
 if [ -x "automation/workflow.py" ]; then
   python3 automation/workflow.py --status || true
 fi