Update documentation to require full commit SHAs

GitHub Actions require full-length commit SHAs. Updated all CI workflow references and standardized documentation messaging across Socket projects

Author: jdalton

CLAUDE.md

@@ -74,10 +74,11 @@ Parsing and constructing package URLs, compiled to CommonJS for deployment.
 - **Update snapshots**: `pnpm test:unit -u` or `pnpm testu`
 
 ### CI Testing Infrastructure
-- **🚨 MANDATORY**: Use `SocketDev/socket-registry/.github/workflows/ci.yml@main` for consistent CI across Socket projects
+- **🚨 MANDATORY**: Use `SocketDev/socket-registry/.github/workflows/ci.yml@<SHA>` with full commit SHA (not @main)
+- **🚨 CRITICAL**: GitHub Actions require full-length commit SHAs. Format: `@662bbcab1b7533e24ba8e3446cffd8a7e5f7617e # main`
 - **Reusable workflows**: Socket-registry provides centralized, reusable workflows for lint/type-check/test/coverage
 - **Benefits**: Parallel execution, consistent configuration, cross-platform testing
-- **Documentation**: See `socket-registry/docs/CI_TESTING_TOOLS.md` for reference
+- **Documentation**: See `docs/CI_TESTING.md` and `socket-registry/docs/CI_TESTING_TOOLS.md`
 
 ## 📋 PURL-SPECIFIC RULES
 

docs/CI_TESTING.md

@@ -4,20 +4,21 @@
 
 This project uses socket-registry's centralized CI testing infrastructure. The solution provides:
 
-- **🚨 MANDATORY**: Use `SocketDev/socket-registry/.github/workflows/ci.yml@main` for consistent CI
+- **🚨 MANDATORY**: Use `SocketDev/socket-registry/.github/workflows/ci.yml@<SHA>` with full commit SHA
+- **🚨 CRITICAL**: GitHub Actions require full-length commit SHAs, NOT `@main`. Format: `@662bbcab1b7533e24ba8e3446cffd8a7e5f7617e # main`
 - **Multi-platform testing**: Linux, Windows, and macOS support
 - **Multi-version Node.js matrix**: Test across Node.js 20, 22, and 24
 - **Flexible configuration**: Customizable test scripts, timeouts, and artifact uploads
 - **Memory optimization**: Configured heap sizes for CI and local environments
 - **Cross-platform compatibility**: Handles Windows and POSIX path differences
 
-**For socket-registry-specific package testing tools**, see `socket-registry/docs/CI_TESTING_TOOLS.md` and `socket-registry/docs/PACKAGE_TESTING_GUIDE.md`. These tools (`validate:packages`, `validate:ci`) are specific to socket-registry's package override structure.
+**🚨 Socket-registry-specific tools**: The `validate:packages` and `validate:ci` scripts are specific to socket-registry's package override structure and not applicable to other Socket projects. See `socket-registry/docs/CI_TESTING_TOOLS.md` for details.
 
 ## Workflow Structure
 
 ### Centralized CI Workflow
 
-**🚨 MANDATORY**: Use `SocketDev/socket-registry/.github/workflows/ci.yml@main` for consistent CI across all Socket projects.
+**🚨 MANDATORY**: Use `SocketDev/socket-registry/.github/workflows/ci.yml@<SHA>` with full commit SHA for consistent CI across all Socket projects.
 
 **Key Features:**
 - Matrix testing across Node.js versions and operating systems
@@ -34,7 +35,7 @@ Located at `.github/workflows/test.yml`, this workflow calls socket-registry's r
 ```yaml
 jobs:
   test:
-    uses: SocketDev/socket-registry/.github/workflows/ci.yml@main
+    uses: SocketDev/socket-registry/.github/workflows/ci.yml@662bbcab1b7533e24ba8e3446cffd8a7e5f7617e # main
     with:
       node-versions: '[20, 22, 24]'
       os-versions: '["ubuntu-latest", "windows-latest"]'
@@ -44,7 +45,7 @@ jobs:
       timeout-minutes: 10
 ```
 
-**Note**: For projects still using local reusable workflows (`.github/workflows/_reusable-test.yml`), migrate to socket-registry's centralized workflow.
+**🚨 CRITICAL**: Never use `@main` - always use the full 40-character commit SHA. Get the SHA with: `cd /path/to/socket-registry && git rev-parse main`
 
 ## Configuration Options
 
@@ -73,11 +74,11 @@ jobs:
 
 ## Best Practices
 
-### 1. Use Centralized Workflow
+### 1. Use Centralized CI Workflow
 
-Always use socket-registry's centralized CI workflow for consistency:
+Always use socket-registry's centralized CI workflow with full commit SHA:
 ```yaml
-uses: SocketDev/socket-registry/.github/workflows/ci.yml@main
+uses: SocketDev/socket-registry/.github/workflows/ci.yml@662bbcab1b7533e24ba8e3446cffd8a7e5f7617e # main
 ```
 
 ### 2. Configure Timeouts
@@ -87,11 +88,7 @@ Set appropriate timeouts for your test suite:
 timeout-minutes: 10  # Adjust based on suite size
 ```
 
-### 3. Platform-Specific Tests
-
-Use matrix exclude for platform-specific issues if needed.
-
-### 4. Debug Mode
+### 3. Debug Mode
 
 Enable debug mode for troubleshooting:
 ```yaml
@@ -142,10 +139,10 @@ pnpm check
 ## Integration with socket-registry
 
 This project uses socket-registry's centralized CI infrastructure:
-- **CI Workflow**: `SocketDev/socket-registry/.github/workflows/ci.yml@main`
+- **CI Workflow**: `SocketDev/socket-registry/.github/workflows/ci.yml@<SHA>` (must use full commit SHA)
 - **Cross-platform compatibility**: Follows socket-registry guidelines
 - **Memory optimization**: Aligned with socket-registry patterns
 
-**Socket-registry-specific tools**: The `validate:packages` and `validate:ci` scripts in socket-registry are specific to its package override structure and not applicable to purl projects. See `socket-registry/docs/CI_TESTING_TOOLS.md` and `socket-registry/docs/PACKAGE_TESTING_GUIDE.md` for details.
+**🚨 Socket-registry-specific tools**: The `validate:packages` and `validate:ci` scripts are specific to socket-registry's package override structure and not applicable to other Socket projects. See `socket-registry/docs/CI_TESTING_TOOLS.md` for details.
 
-For consistency across Socket projects, follow the patterns established in socket-registry/CLAUDE.md and documented here.
+For consistency across Socket projects, follow the patterns established in `socket-registry/CLAUDE.md`.