fix: resolve merge commit detection and add production safety features

🔧 Fixed Git Show Bug:
- Removed --format=%n from all git show calls (was producing ['', ''] empty arrays)
- Added merge-aware fallback: git diff --name-only <parent^1> <commit> for merge commits

🚀 Customer Guidance:
- Buildkite users: Keep CI_PIPELINE_SOURCE=merge_request_event override for GitLab-triggered pipelines
- Squash merge opt-out: SOCKET_GIT_DISABLE_SQUASH_HEURISTIC=1 available if heuristic detection causes false positives (default: heuristic enabled)

⚠️ Enhanced Warnings:
- Octopus merges log a first-parent warning when 3+ parents detected
- Clear messaging about limitations: 'Using first-parent diff only - may not show all changes from all branches'

📊 Detection Transparency:
- Frozen DETECTION SUMMARY log schema for monitoring integration
- Method tracking: mr-diff | merge-diff | single-commit-show
- Git command logging for debugging support escalations

🛡️ Production Safety:
- Parent commit validation prevents accidental huge diffs
- Graceful error handling with clear failure messages
- Lazy loading for improved performance

✅ What This Fixes:
- Empty file detection on merge commits (['', ''] → actual changed files)
- Incorrect API mode fallbacks on merge commits
- Missing transparency in file detection logic
- No guardrails against dangerous Git operations

Real Detection Examples:
- Single Commit: DETECTION SUMMARY: method=single-commit-show files=11 sha=095b0ccc cmd="git show --name-only 095b0cc..."
- Merge Commit: DETECTION SUMMARY: method=merge-diff files=1 sha=b459b2e3 cmd="git diff --name-only 89ca8e3a..b459b2e3"

Author: dachi-dev

README.md

@@ -285,6 +285,84 @@ The CLI determines which files to scan based on the following logic:
 - **Using `--enable-diff`**: Forces diff mode without SCM integration - useful when you want differential scanning but are using `--integration api`. For example: `socketcli --integration api --enable-diff --target-path /path/to/repo`
 - **Auto-detection**: Most CI/CD scenarios now work with just `socketcli --target-path /path/to/repo --scm github --pr-number $PR_NUM`
 
+## CI/CD Platform Notes
+
+### Buildkite Integration
+
+Buildkite triggers may require special environment variable setup when integrated with GitLab or other source control systems.
+
+#### Event Type Override
+
+If you encounter "Unknown event type trigger" in Buildkite-triggered jobs, you can override the event type:
+
+```bash
+# Override Buildkite pipeline event type to merge_request_event
+export CI_PIPELINE_SOURCE=merge_request_event
+socketcli --target-path $BUILDKITE_BUILD_CHECKOUT_PATH --scm gitlab
+```
+
+#### Troubleshooting Missing MR Variables
+
+To verify if GitLab MR environment variables are available in your Buildkite pipeline:
+
+```bash
+# Add this debugging snippet to your Buildkite pipeline
+echo "=== GitLab MR Environment Variables ==="
+echo "CI_MERGE_REQUEST_SOURCE_BRANCH_NAME: ${CI_MERGE_REQUEST_SOURCE_BRANCH_NAME:-'NOT SET'}"
+echo "CI_MERGE_REQUEST_TARGET_BRANCH_NAME: ${CI_MERGE_REQUEST_TARGET_BRANCH_NAME:-'NOT SET'}"
+echo "CI_MERGE_REQUEST_IID: ${CI_MERGE_REQUEST_IID:-'NOT SET'}"
+echo "CI_PIPELINE_SOURCE: ${CI_PIPELINE_SOURCE:-'NOT SET'}"
+echo "========================================"
+```
+
+If these variables are missing, the CLI will fall back to merge-aware Git diff detection, which may produce partial results for complex merge scenarios.
+
+#### Buildkite-Specific Configuration
+
+For optimal detection in Buildkite environments triggered by GitLab:
+
+```bash
+# Example Buildkite pipeline step
+steps:
+  - label: "Socket Security Scan"
+    command: |
+      # Override event type if needed
+      export CI_PIPELINE_SOURCE=merge_request_event
+      
+      # Run Socket scan with GitLab SCM detection
+      socketcli \
+        --target-path $BUILDKITE_BUILD_CHECKOUT_PATH \
+        --scm gitlab \
+        --pr-number ${CI_MERGE_REQUEST_IID:-0} \
+        --enable-debug
+```
+
+### Advanced Configuration Options
+
+#### Squash Merge Detection Control
+
+The CLI uses heuristic-based detection for squash merges. To disable this behavior:
+
+```bash
+export SOCKET_GIT_DISABLE_SQUASH_HEURISTIC=1
+socketcli --target-path ./my-project
+```
+
+**When to use this:**
+- False positives: Regular commits with merge-like messages are misclassified
+- Consistent behavior: You want deterministic single-commit detection only
+- Performance: Avoiding heuristic analysis for large repositories
+
+#### Default Branch Detection Matrix
+
+| Scenario | `--default-branch` | `--ignore-commit-files` | Behavior |
+|----------|-------------------|------------------------|----------|
+| **PR/MR Context** | Not set | Not set | Auto-detects as `false` (PR scans) |
+| **Main Branch Push** | Not set | Not set | Auto-detects as `true` (main branch) |
+| **Force Default** | `--default-branch` | Not set | Forces `true` regardless of context |
+| **Force API Mode** | Not set | `--ignore-commit-files` | Full scan, default branch auto-detected |
+| **Override Both** | `--default-branch` | `--ignore-commit-files` | Forces default branch + full scan |
+
 ## Debugging and Troubleshooting
 
 ### Saving Submitted Files List