From cb2d28507e885a3b1fa5eb1692531cc965722e2e Mon Sep 17 00:00:00 2001
From: jdalton <john.david.dalton@gmail.com>
Date: Sun, 5 Apr 2026 15:43:34 -0400
Subject: [PATCH 01/10] chore: add security scanning and enforce no-npx rule

- Add ecc-agentshield as pinned devDep for Claude Code config scanning
- Add `pnpm run security` script (agentshield + zizmor)
- Add /security-scan command for Claude
- Add npx/dlx/yarn-dlx check to pre-commit hook
- Add NEVER npx/dlx rule to CLAUDE.md ABSOLUTE RULES
- Remove dead .husky/security-checks.sh (duplicate of .git-hooks/pre-commit)
---
 .claude/commands/security-scan.md |  22 +++
 .git-hooks/pre-commit             |  18 ++
 .husky/security-checks.sh         | 125 --------------
 CLAUDE.md                         |   1 +
 external-tools.json               |  31 ++++
 package.json                      |   3 +
 pnpm-lock.yaml                    | 208 +++++++++++++++++++++++
 pnpm-workspace.yaml               |   1 +
 scripts/setup.mjs                 | 271 ++++++++++++++++++++++++++++++
 9 files changed, 555 insertions(+), 125 deletions(-)
 create mode 100644 .claude/commands/security-scan.md
 delete mode 100755 .husky/security-checks.sh
 create mode 100644 external-tools.json
 create mode 100644 scripts/setup.mjs

diff --git a/.claude/commands/security-scan.md b/.claude/commands/security-scan.md
new file mode 100644
index 00000000..42e36005
--- /dev/null
+++ b/.claude/commands/security-scan.md
@@ -0,0 +1,22 @@
+Run a security scan of the project via `pnpm run security`, or manually:
+
+## 1. Claude Code configuration security
+
+Run `pnpm exec agentshield scan` to check `.claude/` for:
+- Hardcoded secrets in CLAUDE.md and settings
+- Overly permissive tool allow lists (e.g. `Bash(*)`)
+- Prompt injection patterns in agent definitions
+- Command injection risks in hooks
+- Risky MCP server configurations
+
+## 2. GitHub Actions workflow security
+
+Run `zizmor .github/` to scan all workflows for:
+- Unpinned actions (should use full SHA, not tags)
+- Secrets used outside `env:` blocks
+- Injection risks from untrusted inputs
+- Overly permissive permissions
+
+If zizmor is not installed, skip with a message. Install via `brew install zizmor` or see https://docs.zizmor.sh/installation/.
+
+Report all findings with severity levels. Fix CRITICAL and HIGH findings immediately.
diff --git a/.git-hooks/pre-commit b/.git-hooks/pre-commit
index 28c0da69..7ae6f541 100755
--- a/.git-hooks/pre-commit
+++ b/.git-hooks/pre-commit
@@ -112,6 +112,24 @@ for file in $STAGED_FILES; do
   fi
 done
 
+# Check for npx/dlx usage (use pnpm exec or pnpm run instead).
+printf "Checking for npx/dlx usage...\n"
+for file in $STAGED_FILES; do
+  if [ -f "$file" ]; then
+    # Skip node_modules, lockfiles, and this hook itself.
+    if echo "$file" | grep -qE 'node_modules/|pnpm-lock\.yaml|\.git-hooks/'; then
+      continue
+    fi
+
+    if grep -nE '\bnpx\b|\bpnpm dlx\b|\byarn dlx\b' "$file" 2>/dev/null | grep -v '# zizmor:' | grep -q .; then
+      printf "${RED}✗ ERROR: npx/dlx usage found in: $file${NC}\n"
+      grep -nE '\bnpx\b|\bpnpm dlx\b|\byarn dlx\b' "$file" | grep -v '# zizmor:' | head -3
+      printf "Use 'pnpm exec <package>' or 'pnpm run <script>' instead.\n"
+      ERRORS=$((ERRORS + 1))
+    fi
+  fi
+done
+
 if [ $ERRORS -gt 0 ]; then
   printf "\n"
   printf "${RED}✗ Security check failed with $ERRORS error(s).${NC}\n"
diff --git a/.husky/security-checks.sh b/.husky/security-checks.sh
deleted file mode 100755
index 3b040f83..00000000
--- a/.husky/security-checks.sh
+++ /dev/null
@@ -1,125 +0,0 @@
-#!/bin/bash
-# Socket Security Checks
-# Prevents committing sensitive data and common mistakes.
-
-set -e
-
-# Colors for output.
-RED='\033[0;31m'
-YELLOW='\033[1;33m'
-GREEN='\033[0;32m'
-NC='\033[0m'
-
-# Allowed public API key (used in socket-lib and across all Socket repos).
-# This is Socket's official public test API key - safe to commit.
-# NOTE: This value is intentionally identical across all Socket repos.
-ALLOWED_PUBLIC_KEY="sktsec_t_--RAN5U4ivauy4w37-6aoKyYPDt5ZbaT5JBVMqiwKo_api"
-
-printf "${GREEN}Running Socket Security checks...${NC}\n"
-
-# Get list of staged files.
-STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM)
-
-if [ -z "$STAGED_FILES" ]; then
-  printf "${GREEN}✓ No files to check${NC}\n"
-  exit 0
-fi
-
-ERRORS=0
-
-# Check for .DS_Store files.
-printf "Checking for .DS_Store files...\n"
-if echo "$STAGED_FILES" | grep -q '\.DS_Store'; then
-  printf "${RED}✗ ERROR: .DS_Store file detected!${NC}\n"
-  echo "$STAGED_FILES" | grep '\.DS_Store'
-  ERRORS=$((ERRORS + 1))
-fi
-
-# Check for log files.
-printf "Checking for log files...\n"
-if echo "$STAGED_FILES" | grep -E '\.log$' | grep -v 'test.*\.log'; then
-  printf "${RED}✗ ERROR: Log file detected!${NC}\n"
-  echo "$STAGED_FILES" | grep -E '\.log$' | grep -v 'test.*\.log'
-  ERRORS=$((ERRORS + 1))
-fi
-
-# Check for .env files.
-printf "Checking for .env files...\n"
-if echo "$STAGED_FILES" | grep -E '^\.env(\.local)?$'; then
-  printf "${RED}✗ ERROR: .env or .env.local file detected!${NC}\n"
-  echo "$STAGED_FILES" | grep -E '^\.env(\.local)?$'
-  printf "These files should never be committed. Use .env.example instead.\n"
-  ERRORS=$((ERRORS + 1))
-fi
-
-# Check for hardcoded user paths (generic detection).
-printf "Checking for hardcoded personal paths...\n"
-for file in $STAGED_FILES; do
-  if [ -f "$file" ]; then
-    # Skip test files and hook scripts.
-    if echo "$file" | grep -qE '\.(test|spec)\.|/test/|/tests/|fixtures/|\.git-hooks/|\.husky/'; then
-      continue
-    fi
-
-    # Check for common user path patterns.
-    if grep -E '(/Users/[^/\s]+/|/home/[^/\s]+/|C:\\Users\\[^\\]+\\)' "$file" 2>/dev/null | grep -q .; then
-      printf "${RED}✗ ERROR: Hardcoded personal path found in: $file${NC}\n"
-      grep -n -E '(/Users/[^/\s]+/|/home/[^/\s]+/|C:\\Users\\[^\\]+\\)' "$file" | head -3
-      printf "Replace with relative paths or environment variables.\n"
-      ERRORS=$((ERRORS + 1))
-    fi
-  fi
-done
-
-# Check for Socket API keys.
-printf "Checking for API keys...\n"
-for file in $STAGED_FILES; do
-  if [ -f "$file" ]; then
-    if grep -E 'sktsec_[a-zA-Z0-9_-]+' "$file" 2>/dev/null | grep -v "$ALLOWED_PUBLIC_KEY" | grep -v 'your_api_key_here' | grep -v 'SOCKET_SECURITY_API_KEY=' | grep -v 'fake-token' | grep -v 'test-token' | grep -q .; then
-      printf "${YELLOW}⚠ WARNING: Potential API key found in: $file${NC}\n"
-      grep -n 'sktsec_' "$file" | grep -v "$ALLOWED_PUBLIC_KEY" | grep -v 'your_api_key_here' | grep -v 'fake-token' | grep -v 'test-token' | head -3
-      printf "If this is a real API key, DO NOT COMMIT IT.\n"
-    fi
-  fi
-done
-
-# Check for common secret patterns.
-printf "Checking for potential secrets...\n"
-for file in $STAGED_FILES; do
-  if [ -f "$file" ]; then
-    # Skip test files, example files, and hook scripts.
-    if echo "$file" | grep -qE '\.(test|spec)\.(m?[jt]s|tsx?)$|\.example$|/test/|/tests/|fixtures/|\.git-hooks/|\.husky/'; then
-      continue
-    fi
-
-    # Check for AWS keys.
-    if grep -iE '(aws_access_key|aws_secret|AKIA[0-9A-Z]{16})' "$file" 2>/dev/null | grep -q .; then
-      printf "${RED}✗ ERROR: Potential AWS credentials found in: $file${NC}\n"
-      grep -n -iE '(aws_access_key|aws_secret|AKIA[0-9A-Z]{16})' "$file" | head -3
-      ERRORS=$((ERRORS + 1))
-    fi
-
-    # Check for GitHub tokens.
-    if grep -E 'gh[ps]_[a-zA-Z0-9]{36}' "$file" 2>/dev/null | grep -q .; then
-      printf "${RED}✗ ERROR: Potential GitHub token found in: $file${NC}\n"
-      grep -n -E 'gh[ps]_[a-zA-Z0-9]{36}' "$file" | head -3
-      ERRORS=$((ERRORS + 1))
-    fi
-
-    # Check for private keys.
-    if grep -E '-----BEGIN (RSA |EC |DSA )?PRIVATE KEY-----' "$file" 2>/dev/null | grep -q .; then
-      printf "${RED}✗ ERROR: Private key found in: $file${NC}\n"
-      ERRORS=$((ERRORS + 1))
-    fi
-  fi
-done
-
-if [ $ERRORS -gt 0 ]; then
-  printf "\n"
-  printf "${RED}✗ Security check failed with $ERRORS error(s).${NC}\n"
-  printf "Fix the issues above and try again.\n"
-  exit 1
-fi
-
-printf "${GREEN}✓ All security checks passed!${NC}\n"
-exit 0
diff --git a/CLAUDE.md b/CLAUDE.md
index 7fe869f2..d923b1eb 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -69,6 +69,7 @@
 - Always prefer editing existing files
 - Forbidden to create docs unless requested
 - Required to do exactly what was asked
+- 🚨 **NEVER use `npx`, `pnpm dlx`, or `yarn dlx`** — use `pnpm exec <package>` for devDep binaries, or `pnpm run <script>` for package.json scripts. If a tool is needed, add it as a pinned devDependency first.
 
 ## ROLE
 
diff --git a/external-tools.json b/external-tools.json
new file mode 100644
index 00000000..ca8710dc
--- /dev/null
+++ b/external-tools.json
@@ -0,0 +1,31 @@
+{
+  "zizmor": {
+    "description": "GitHub Actions security linter",
+    "type": "github-release",
+    "repository": "zizmorcore/zizmor",
+    "version": "1.23.1",
+    "binary": "zizmor",
+    "assets": {
+      "darwin-arm64": {
+        "asset": "zizmor-aarch64-apple-darwin.tar.gz",
+        "sha256": "2632561b974c69f952258c1ab4b7432d5c7f92e555704155c3ac28a2910bd717"
+      },
+      "darwin-x64": {
+        "asset": "zizmor-x86_64-apple-darwin.tar.gz",
+        "sha256": "89d5ed42081dd9d0433a10b7545fac42b35f1f030885c278b9712b32c66f2597"
+      },
+      "linux-arm64": {
+        "asset": "zizmor-aarch64-unknown-linux-gnu.tar.gz",
+        "sha256": "3725d7cd7102e4d70827186389f7d5930b6878232930d0a3eb058d7e5b47e658"
+      },
+      "linux-x64": {
+        "asset": "zizmor-x86_64-unknown-linux-gnu.tar.gz",
+        "sha256": "67a8df0a14352dd81882e14876653d097b99b0f4f6b6fe798edc0320cff27aff"
+      },
+      "win32-x64": {
+        "asset": "zizmor-x86_64-pc-windows-msvc.zip",
+        "sha256": "33c2293ff02834720dd7cd8b47348aafb2e95a19bdc993c0ecaca9c804ade92a"
+      }
+    }
+  }
+}
diff --git a/package.json b/package.json
index d4eb23ef..7ddc5818 100644
--- a/package.json
+++ b/package.json
@@ -40,6 +40,8 @@
     "package-npm-publish": "node scripts/npm/publish-npm-packages.mjs",
     "perf": "node scripts/perf.mjs",
     "precommit": "pnpm run check --staged",
+    "security": "agentshield scan && { command -v zizmor >/dev/null && zizmor .github/ || echo 'zizmor not installed — run pnpm run setup to install'; }",
+    "setup": "node scripts/setup.mjs",
     "prepare": "husky && pnpm run build",
     "prepublishOnly": "echo 'ERROR: Use GitHub Actions workflow for publishing' && exit 1",
     "publish": "node scripts/publish.mjs",
@@ -91,6 +93,7 @@
     "del-cli": "catalog:",
     "dev-null-cli": "catalog:",
     "didyoumean2": "catalog:",
+    "ecc-agentshield": "catalog:",
     "esbuild": "catalog:",
     "eta": "catalog:",
     "fast-glob": "catalog:",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 7bec6575..0a55d7e5 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -117,6 +117,9 @@ catalogs:
     didyoumean2:
       specifier: 7.0.4
       version: 7.0.4
+    ecc-agentshield:
+      specifier: 1.4.0
+      version: 1.4.0
     esbuild:
       specifier: 0.25.11
       version: 0.25.11
@@ -393,6 +396,9 @@ importers:
       didyoumean2:
         specifier: 'catalog:'
         version: 7.0.4
+      ecc-agentshield:
+        specifier: 'catalog:'
+        version: 1.4.0(encoding@0.1.13)
       esbuild:
         specifier: 'catalog:'
         version: 0.25.11
@@ -893,6 +899,9 @@ packages:
     engines: {node: '>=18.0.0'}
     hasBin: true
 
+  '@anthropic-ai/sdk@0.39.0':
+    resolution: {integrity: sha512-eMyDIPRZbt1CCLErRCi3exlAvNkBtRe+kW5vvJyef93PmNr/clstYgHhtvmkxN82nlKgzyGPCyGxrm0JQ1ZIdg==}
+
   '@babel/code-frame@7.27.1':
     resolution: {integrity: sha512-cjQ7ZlQ0Mv3b47hABuTevyTuYN4i+loJKGeV9flcCgIK37cCXRh+L1bd3iBHlynerhQ7BhCkn2BPbQUL+rGqFg==}
     engines: {node: '>=6.9.0'}
@@ -1898,6 +1907,14 @@ packages:
     resolution: {integrity: sha512-nDx2F54qKrO5MOm97qEtRwWTjpVejNfUTZBzvwxvdp6RL3HgxSFpuxRO2idExtANItrE3FuQjBItfY3yqunTGQ==}
     engines: {node: '>=18'}
 
+  '@socketregistry/es-set-tostringtag@1.0.10':
+    resolution: {integrity: sha512-btXmvw1JpA8WtSoXx9mTapo9NAyIDKRRzK84i48d8zc0X09M6ORfobVnHbgwhXf7CFhkRzhYrHG9dqbI9vpELQ==}
+    engines: {node: '>=18'}
+
+  '@socketregistry/hasown@1.0.7':
+    resolution: {integrity: sha512-MZ5dyXOtiEc7q3801T+2EmKkxrd55BOSQnG8z/8/IkIJzDxqBxGGBKVyixqFm3W657TyUEBfIT9iWgSB6ipFsA==}
+    engines: {node: '>=18'}
+
   '@socketregistry/indent-string@1.0.14':
     resolution: {integrity: sha512-SCb2h+KkZppDEDyzZheazziUpJQVeCpEMQxSiTn4VMbVkGgvpNVAWQyx3IniSzwiSJpASmwTRTlhiYk6AR19bw==}
     engines: {node: '>=18'}
@@ -2034,6 +2051,9 @@ packages:
   '@types/ms@2.1.0':
     resolution: {integrity: sha512-GsCCIZDE/p3i96vtEqx+7dBUGXrc7zeSK3wwPHIaRThS+9OhWIXRqzs4d6k1SVU8g91DrNRWxWUGhp5KXQb2VA==}
 
+  '@types/node-fetch@2.6.13':
+    resolution: {integrity: sha512-QGpRVpzSaUs30JBSGPjOg4Uveu384erbHBoT1zeONvyCfwQxIkUshLAOqN/k9EjGviPRmWTTe6aH2qySWKTVSw==}
+
   '@types/node@24.9.2':
     resolution: {integrity: sha512-uWN8YqxXxqFMX2RqGOrumsKeti4LlmIMIyV0lgut4jx7KQBcBiW6vkDtIBvHnHIquwNfJhk8v2OtmO8zXWHfPA==}
 
@@ -2157,10 +2177,18 @@ packages:
     resolution: {integrity: sha512-AO2ac6pjRB3SJmGJo+v5/aK6Omggp6fsLrs6wN9bd35ulu4cCwaAU9+7ZhXjeqHVkaHThLuzH0nZr0YpCDhygg==}
     engines: {node: ^18.17.0 || >=20.5.0}
 
+  abort-controller@3.0.0:
+    resolution: {integrity: sha512-h8lQ8tacZYnR3vNQTgibj+tODHI5/+l06Au2Pcriv/Gmet0eaj4TwWH41sO9wnHDiQsEj19q0drzdWdeAHtweg==}
+    engines: {node: '>=6.5'}
+
   agent-base@7.1.4:
     resolution: {integrity: sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ==}
     engines: {node: '>= 14'}
 
+  agentkeepalive@4.6.0:
+    resolution: {integrity: sha512-kja8j7PjmncONqaTsB8fQ+wE2mSU2DJ9D4XKoJ5PFWIdRMa6SLSN1ff4mOr4jCbfRSsxR4keIiySJU0N9T5hIQ==}
+    engines: {node: '>= 8.0.0'}
+
   ansi-regex@5.0.1:
     resolution: {integrity: sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==}
     engines: {node: '>=8'}
@@ -2191,6 +2219,9 @@ packages:
   ast-v8-to-istanbul@0.3.6:
     resolution: {integrity: sha512-9tx1z/7OF/a8EdYL3FKoBhxLf3h3D8fXvuSj0HknsVeli2HE40qbNZxyFhMtnydaRiamwFu9zhb+BsJ5tVPehQ==}
 
+  asynckit@0.4.0:
+    resolution: {integrity: sha512-Oei9OH4tRh0YqU3GxhX79dM/mwVgvbZJaSNaRk+bshkj0S5cfHcgYakreBjrHwatXKbz+IoIdYLxrKim2MjW0Q==}
+
   balanced-match@1.0.2:
     resolution: {integrity: sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==}
 
@@ -2248,6 +2279,10 @@ packages:
     resolution: {integrity: sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==}
     engines: {node: '>=10'}
 
+  chalk@5.6.2:
+    resolution: {integrity: sha512-7NzBL0rN6fMUW+f7A6Io4h40qQlG+xGmtMxfbnH/K7TAtt8JQWVQK+6g0UXKMeVJoyV5EkkNsErQ8pVD3bLHbA==}
+    engines: {node: ^12.17.0 || ^14.13 || >=16.0.0}
+
   chardet@2.1.0:
     resolution: {integrity: sha512-bNFETTG/pM5ryzQ9Ad0lJOTa6HWD/YsScAR3EnCPZRPlQh77JocYktSHOUHelyhm8IARL+o4c4F1bP5KVOjiRA==}
 
@@ -2274,6 +2309,14 @@ packages:
   color-name@1.1.4:
     resolution: {integrity: sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==}
 
+  combined-stream@1.0.8:
+    resolution: {integrity: sha512-FQN4MRfuJeHf7cBbBMJFXhKSDq+2kAArBlmRBvcvFE5BB1HZKXtSFASDhdlz9zOYwxh8lDdnvmMOe/+5cdoEdg==}
+    engines: {node: '>= 0.8'}
+
+  commander@13.1.0:
+    resolution: {integrity: sha512-/rFeCpNJQbhSZjGVwO9RFV3xPqbnERS8MmIQzCtD/zl6gpJuV/bMLuN92oG3F7d8oDEHHRrujSXNUr8fpjntKw==}
+    engines: {node: '>=18'}
+
   common-ancestor-path@1.0.1:
     resolution: {integrity: sha512-L3sHRo1pXXEqX8VU28kfgUY+YGsk09hPqZiZmLacNib6XNTCM8ubYeT7ryXQw8asB1sKgcU5lkB7ONug08aB8w==}
 
@@ -2322,6 +2365,10 @@ packages:
     resolution: {integrity: sha512-gPqh0mKTPvaUZGAuHbrBUYKZWBNAeHG7TU3QH5EhVwPMyKvmfJaNXhcD2jTcXsJRRcffuho4vaYweu80dRrMGA==}
     engines: {node: '>=18'}
 
+  delayed-stream@1.0.0:
+    resolution: {integrity: sha512-ZySD7Nf91aLB0RxL4KGrKHBXl7Eds1DAmEdcoVawXnLD7SDhpNgtuII2aAkg7a7QS41jxPSZ17p4VdGnMHk3MQ==}
+    engines: {node: '>=0.4.0'}
+
   destr@2.0.5:
     resolution: {integrity: sha512-ugFTXCtDZunbzasqBxrK93Ik/DRYsO6S/fedkWEMKqt04xZ4csmnmwGDBAb07QWNaGMAmnTIemsYZCksjATwsA==}
 
@@ -2337,6 +2384,11 @@ packages:
   eastasianwidth@0.2.0:
     resolution: {integrity: sha512-I88TYZWc9XiYHRQ4/3c5rjjfgkjhLyW2luGIheGERbNQ6OY7yTybanSpDXZa8y7VUP9YmDcYa+eyq4ca7iLqWA==}
 
+  ecc-agentshield@1.4.0:
+    resolution: {integrity: sha512-R98OO1Ujyk2lezDLb+iQmMhF6FwTJCHajy3G4FCB6x7wkSTqR9f8+eAelC5KDzYDsGSbc0sOZvjXOOPRBtMpDg==}
+    engines: {node: '>=18'}
+    hasBin: true
+
   electron-to-chromium@1.5.236:
     resolution: {integrity: sha512-Yi43booTJp2VteesVja4xdcDrAcVFItkD6RrxhMSuGx1kShh+raMwnKyIGNOTl68reqSxPPls6bB8LgIcrK9Gg==}
 
@@ -2381,6 +2433,10 @@ packages:
     resolution: {integrity: sha512-e3x3FBvGzeCIHhF+zhK8FZA2vC5uFn6b4HJjegUbIWrDb4mJ7JjTGMJY9VGIbRVpmSwHopNiaJibhjIr+HfLug==}
     engines: {node: '>=6.0.0'}
 
+  event-target-shim@5.0.1:
+    resolution: {integrity: sha512-i/2XbnSz/uxRCU6+NdVJgKWDTM427+MqYbkQzD321DuCQJUqOuJKIA0IM2+W2xtYHdKOmZ4dR6fExsd4SXL+WQ==}
+    engines: {node: '>=6'}
+
   execa@2.1.0:
     resolution: {integrity: sha512-Y/URAVapfbYy2Xp/gb6A0E7iR8xeqOCXsuuaoMn7A5PzrXUK84E1gyiEfq0wQd/GHA6GsoHWwhNq8anb0mleIw==}
     engines: {node: ^8.12.0 || >=9.7.0}
@@ -2444,6 +2500,17 @@ packages:
     resolution: {integrity: sha512-gIXjKqtFuWEgzFRJA9WCQeSJLZDjgJUOMCMzxtvFq/37KojM1BFGufqsCy0r4qSQmYLsZYMeyRqzIWOMup03sw==}
     engines: {node: '>=14'}
 
+  form-data-encoder@1.7.2:
+    resolution: {integrity: sha512-qfqtYan3rxrnCk1VYaA4H+Ms9xdpPqvLZa6xmMgFvhO32x7/3J/ExcTd6qpxM0vH2GdMI+poehyBZvqfMTto8A==}
+
+  form-data@4.0.5:
+    resolution: {integrity: sha512-8RipRLol37bNs2bhoV67fiTEvdTrbMUYcFTiy3+wuuOnUog2QBHCZWXDRijWQfAkhBj2Uf5UnVaiWwA5vdd82w==}
+    engines: {node: '>= 6'}
+
+  formdata-node@4.4.1:
+    resolution: {integrity: sha512-0iirZp3uVDjVGt9p49aTaqjk84TrglENEDuqfdlZQ1roC9CWlPk6Avf8EEnZNcAqPonwkG35x4n3ww/1THYAeQ==}
+    engines: {node: '>= 12.20'}
+
   fs-extra@11.3.1:
     resolution: {integrity: sha512-eXvGGwZ5CL17ZSwHWd3bbgk7UUpF6IFHtP57NYYakPvHOs8GDgDe5KJI36jIJzDkJ6eJjuzRA8eBQb6SkKue0g==}
     engines: {node: '>=14.14'}
@@ -2537,6 +2604,9 @@ packages:
     resolution: {integrity: sha512-AXcZb6vzzrFAUE61HnN4mpLqd/cSIwNQjtNWR0euPm6y0iqx3G4gOXaIDdtdDwZmhwe82LA6+zinmW4UBWVePQ==}
     engines: {node: '>=16.17.0'}
 
+  humanize-ms@1.2.1:
+    resolution: {integrity: sha512-Fl70vYtsAFb/C06PTS9dZBo7ihau+Tu/DNCk/OyHhea07S+aeMWpFFkUaXRa8fI+ScZbEI8dfSxwY7gxZ9SAVQ==}
+
   husky@9.1.7:
     resolution: {integrity: sha512-5gs5ytaNjBrh5Ow3zrvdUUY+0VxIuWVL4i9irt6friV+BqdCfmV11CQTWMiBYWHbXhco+J1kHfTOUkePhCDvMA==}
     engines: {node: '>=18'}
@@ -2783,6 +2853,14 @@ packages:
     resolution: {integrity: sha512-PXwfBhYu0hBCPw8Dn0E+WDYb7af3dSLVWKi3HGv84IdF4TyFoC0ysxFd0Goxw7nSv4T/PzEJQxsYsEiFCKo2BA==}
     engines: {node: '>=8.6'}
 
+  mime-db@1.52.0:
+    resolution: {integrity: sha512-sPU4uV7dYlvtWJxwwxHD0PuihVNiE7TyAbQ5SWxDCB9mUYvOgroQOwYQQOKPJ8CIbE+1ETVlOoK1UC2nU3gYvg==}
+    engines: {node: '>= 0.6'}
+
+  mime-types@2.1.35:
+    resolution: {integrity: sha512-ZDY+bPm5zTTF+YpCrAU9nK0UgICYPT0QtT1NZWFv4s++TNkcgVaT0g6+4R2uI4MjQjzysHB1zxuWL50hzaeXiw==}
+    engines: {node: '>= 0.6'}
+
   mimic-fn@2.1.0:
     resolution: {integrity: sha512-OqbOk5oEQeAZ8WXWydlu9HJjz9WVdEIvamMCcXmuqUYjTknH/sqsWvhQ3vgwKFRR1HpjvNBKQ37nbJgYzGqGcg==}
     engines: {node: '>=6'}
@@ -2866,9 +2944,23 @@ packages:
     resolution: {integrity: sha512-8Ofs/AUQh8MaEcrlq5xOX0CQ9ypTF5dl78mjlMNfOK08fzpgTHQRQPBxcPlEtIw0yRpws+Zo/3r+5WRby7u3Gg==}
     engines: {node: '>= 0.6'}
 
+  node-domexception@1.0.0:
+    resolution: {integrity: sha512-/jKZoMpw0F8GRwl4/eLROPA3cfcXtLApP0QzLmUT/HuPCZWyB7IY9ZrMeKw2O/nFIqPQB3PVM9aYm0F312AXDQ==}
+    engines: {node: '>=10.5.0'}
+    deprecated: Use your platform's native DOMException instead
+
   node-fetch-native@1.6.7:
     resolution: {integrity: sha512-g9yhqoedzIUm0nTnTqAQvueMPVOuIY16bqgAJJC8XOOubYFNwz6IER9qs0Gq2Xd0+CecCKFjtdDTMA4u4xG06Q==}
 
+  node-fetch@2.7.0:
+    resolution: {integrity: sha512-c4FRfUm/dbcWZ7U+1Wq0AwCyFL+3nt2bEw05wfxSz+DWpWsitgmSgYmy2dQdWyKC1694ELPqMs/YzUSNozLt8A==}
+    engines: {node: 4.x || >=6.0.0}
+    peerDependencies:
+      encoding: ^0.1.0
+    peerDependenciesMeta:
+      encoding:
+        optional: true
+
   node-gyp@11.4.2:
     resolution: {integrity: sha512-3gD+6zsrLQH7DyYOUIutaauuXrcyxeTPyQuZQCQoNPZMHMMS5m4y0xclNpvYzoK3VNzuyxT6eF4mkIL4WSZ1eQ==}
     engines: {node: ^18.17.0 || >=20.5.0}
@@ -3341,6 +3433,9 @@ packages:
     resolution: {integrity: sha512-sf4i37nQ2LBx4m3wB74y+ubopq6W/dIzXg0FDGjsYnZHVa1Da8FH853wlL2gtUhg+xJXjfk3kUZS3BRoQeoQBQ==}
     engines: {node: '>=6'}
 
+  tr46@0.0.3:
+    resolution: {integrity: sha512-N3WMsuqV66lT30CrXNbEjx4GEwlow3v6rr4mCcv6prnfwhS01rkgyFdjPNBYd9br7LpXV1+Emh01fHnq2Gdgrw==}
+
   trash@10.0.0:
     resolution: {integrity: sha512-nyHQPJ7F4dYCfj1xN95DAkLkf9qlyRLDpT9yYwcR5SH16q+f7VA1L5VwsdEqWFUuGNpKwgLnbOS1QBvXMYnLfA==}
     engines: {node: '>=20'}
@@ -3521,6 +3616,16 @@ packages:
     resolution: {integrity: sha512-3hu+tD8YzSLGuFYtPRb48vdhKMi0KQV5sn+uWr8+7dMEq/2G/dtLrdDinkLjqq5TIbIBjYJ4Ax/n3YiaW7QM8A==}
     engines: {node: 20 || >=22}
 
+  web-streams-polyfill@4.0.0-beta.3:
+    resolution: {integrity: sha512-QW95TCTaHmsYfHDybGMwO5IJIM93I/6vTRk+daHTWFPhwh+C8Cg7j7XyKrwrj8Ib6vYXe0ocYNrmzY4xAAN6ug==}
+    engines: {node: '>= 14'}
+
+  webidl-conversions@3.0.1:
+    resolution: {integrity: sha512-2JAn3z8AR6rjK8Sm8orRC0h/bcl/DqL7tRPdGZ4I1CjdF+EaMLmYxBHyXuKL849eucPFhvBoxMsflfOb8kxaeQ==}
+
+  whatwg-url@5.0.0:
+    resolution: {integrity: sha512-saE57nupxk6v3HY35+jzBwYa0rKSy0XR8JSxZPwgLr7ys0IBzhGviA1/TUGJLmSVqs8pb9AnvICXEuOHLprYTw==}
+
   which@2.0.2:
     resolution: {integrity: sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==}
     engines: {node: '>= 8'}
@@ -3599,6 +3704,9 @@ packages:
     resolution: {integrity: sha512-U/PBtDf35ff0D8X8D0jfdzHYEPFxAI7jJlxZXwCSez5M3190m+QobIfh+sWDWSHMCWWJN2AWamkegn6vr6YBTw==}
     engines: {node: '>=18'}
 
+  zod@3.25.76:
+    resolution: {integrity: sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==}
+
   zod@4.1.12:
     resolution: {integrity: sha512-JInaHOamG8pt5+Ey8kGmdcAcg3OL9reK8ltczgHTAwNhMys/6ThXHityHxVV2p3fkw/c+MAvBHFVYHFZDmjMCQ==}
 
@@ -3624,6 +3732,18 @@ snapshots:
       '@img/sharp-win32-arm64': 0.34.5
       '@img/sharp-win32-x64': 0.34.5
 
+  '@anthropic-ai/sdk@0.39.0(encoding@0.1.13)':
+    dependencies:
+      '@types/node': 24.9.2
+      '@types/node-fetch': 2.6.13
+      abort-controller: 3.0.0
+      agentkeepalive: 4.6.0
+      form-data-encoder: 1.7.2
+      formdata-node: 4.4.1
+      node-fetch: 2.7.0(encoding@0.1.13)
+    transitivePeerDependencies:
+      - encoding
+
   '@babel/code-frame@7.27.1':
     dependencies:
       '@babel/helper-validator-identifier': 7.27.1
@@ -4430,6 +4550,10 @@ snapshots:
 
   '@socketregistry/es-get-iterator@1.0.8': {}
 
+  '@socketregistry/es-set-tostringtag@1.0.10': {}
+
+  '@socketregistry/hasown@1.0.7': {}
+
   '@socketregistry/indent-string@1.0.14': {}
 
   '@socketregistry/is-arguments@1.0.10': {}
@@ -4518,6 +4642,11 @@ snapshots:
   '@types/ms@2.1.0':
     optional: true
 
+  '@types/node-fetch@2.6.13':
+    dependencies:
+      '@types/node': 24.9.2
+      form-data: 4.0.5
+
   '@types/node@24.9.2':
     dependencies:
       undici-types: 7.16.0
@@ -4648,8 +4777,16 @@ snapshots:
 
   abbrev@3.0.1: {}
 
+  abort-controller@3.0.0:
+    dependencies:
+      event-target-shim: 5.0.1
+
   agent-base@7.1.4: {}
 
+  agentkeepalive@4.6.0:
+    dependencies:
+      humanize-ms: 1.2.1
+
   ansi-regex@5.0.1: {}
 
   ansi-regex@6.2.2: {}
@@ -4672,6 +4809,8 @@ snapshots:
       estree-walker: 3.0.3
       js-tokens: 9.0.1
 
+  asynckit@0.4.0: {}
+
   balanced-match@1.0.2: {}
 
   baseline-browser-mapping@2.8.16: {}
@@ -4751,6 +4890,8 @@ snapshots:
       ansi-styles: 4.3.0
       supports-color: 7.2.0
 
+  chalk@5.6.2: {}
+
   chardet@2.1.0: {}
 
   chownr@3.0.0: {}
@@ -4771,6 +4912,12 @@ snapshots:
 
   color-name@1.1.4: {}
 
+  combined-stream@1.0.8:
+    dependencies:
+      delayed-stream: 1.0.0
+
+  commander@13.1.0: {}
+
   common-ancestor-path@1.0.1: {}
 
   convert-source-map@2.0.0: {}
@@ -4813,6 +4960,8 @@ snapshots:
       presentable-error: 0.0.1
       slash: 5.1.0
 
+  delayed-stream@1.0.0: {}
+
   destr@2.0.5: {}
 
   dev-null-cli@2.0.0:
@@ -4828,6 +4977,17 @@ snapshots:
 
   eastasianwidth@0.2.0: {}
 
+  ecc-agentshield@1.4.0(encoding@0.1.13):
+    dependencies:
+      '@anthropic-ai/sdk': 0.39.0(encoding@0.1.13)
+      chalk: 5.6.2
+      commander: 13.1.0
+      glob: 11.0.3
+      yaml: 2.8.2
+      zod: 3.25.76
+    transitivePeerDependencies:
+      - encoding
+
   electron-to-chromium@1.5.236: {}
 
   emoji-regex@8.0.0: {}
@@ -4890,6 +5050,8 @@ snapshots:
 
   eta@3.5.0: {}
 
+  event-target-shim@5.0.1: {}
+
   execa@2.1.0:
     dependencies:
       cross-spawn: 7.0.6
@@ -4960,6 +5122,21 @@ snapshots:
       cross-spawn: 7.0.6
       signal-exit: 4.1.0
 
+  form-data-encoder@1.7.2: {}
+
+  form-data@4.0.5:
+    dependencies:
+      asynckit: 0.4.0
+      combined-stream: 1.0.8
+      es-set-tostringtag: '@socketregistry/es-set-tostringtag@1.0.10'
+      hasown: '@socketregistry/hasown@1.0.7'
+      mime-types: 2.1.35
+
+  formdata-node@4.4.1:
+    dependencies:
+      node-domexception: 1.0.0
+      web-streams-polyfill: 4.0.0-beta.3
+
   fs-extra@11.3.1:
     dependencies:
       graceful-fs: 4.2.11
@@ -5058,6 +5235,10 @@ snapshots:
 
   human-signals@5.0.0: {}
 
+  humanize-ms@1.2.1:
+    dependencies:
+      ms: 2.1.3
+
   husky@9.1.7: {}
 
   iconv-lite@0.6.3:
@@ -5292,6 +5473,12 @@ snapshots:
       braces: 3.0.3
       picomatch: 2.3.1
 
+  mime-db@1.52.0: {}
+
+  mime-types@2.1.35:
+    dependencies:
+      mime-db: 1.52.0
+
   mimic-fn@2.1.0: {}
 
   mimic-fn@4.0.0: {}
@@ -5364,8 +5551,16 @@ snapshots:
 
   negotiator@1.0.0: {}
 
+  node-domexception@1.0.0: {}
+
   node-fetch-native@1.6.7: {}
 
+  node-fetch@2.7.0(encoding@0.1.13):
+    dependencies:
+      whatwg-url: 5.0.0
+    optionalDependencies:
+      encoding: 0.1.13
+
   node-gyp@11.4.2:
     dependencies:
       env-paths: 2.2.1
@@ -5928,6 +6123,8 @@ snapshots:
 
   totalist@3.0.1: {}
 
+  tr46@0.0.3: {}
+
   trash@10.0.0:
     dependencies:
       '@sindresorhus/chunkify': 2.0.0
@@ -6100,6 +6297,15 @@ snapshots:
 
   walk-up-path@4.0.0: {}
 
+  web-streams-polyfill@4.0.0-beta.3: {}
+
+  webidl-conversions@3.0.1: {}
+
+  whatwg-url@5.0.0:
+    dependencies:
+      tr46: 0.0.3
+      webidl-conversions: 3.0.1
+
   which@2.0.2:
     dependencies:
       isexe: 2.0.0
@@ -6165,4 +6371,6 @@ snapshots:
 
   yoctocolors-cjs@2.1.3: {}
 
+  zod@3.25.76: {}
+
   zod@4.1.12: {}
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index 85350a4b..2d27fc67 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -56,6 +56,7 @@ catalog:
   clipboardy: 4.0.0
   debug: ^4.4.3
   del: 8.0.1
+  ecc-agentshield: 1.4.0
   del-cli: 6.0.0
   dev-null-cli: 2.0.0
   didyoumean2: 7.0.4
diff --git a/scripts/setup.mjs b/scripts/setup.mjs
new file mode 100644
index 00000000..8a0c8c0e
--- /dev/null
+++ b/scripts/setup.mjs
@@ -0,0 +1,271 @@
+/**
+ * @fileoverview Developer setup script.
+ *
+ * Checks prerequisites and installs pinned external tools
+ * (currently: zizmor for GitHub Actions security scanning).
+ *
+ * Usage:
+ *   pnpm run setup                # Check prerequisites, install tools
+ *   pnpm run setup --quiet        # Minimal output (for postinstall)
+ */
+
+import { createHash } from 'node:crypto'
+import { createReadStream, existsSync, readFileSync } from 'node:fs'
+import { mkdir, open, readFile, rm, unlink, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+import process from 'node:process'
+
+import { WIN32 } from '@socketsecurity/lib/constants/platform'
+import { getDefaultLogger } from '@socketsecurity/lib/logger'
+import { spawn } from '@socketsecurity/lib/spawn'
+
+const logger = getDefaultLogger()
+const quiet = process.argv.includes('--quiet')
+
+const log = {
+  error: msg => logger.error(msg),
+  info: msg => !quiet && logger.info(msg),
+  step: msg => !quiet && logger.substep(msg),
+  success: msg => !quiet && logger.success(msg),
+  warn: msg => logger.warn(msg),
+}
+
+// Tools cached in repo root (.cache/external-tools/), gitignored via **/.cache.
+function getCacheDir() {
+  if (process.env.EXTERNAL_TOOLS_CACHE) {
+    return process.env.EXTERNAL_TOOLS_CACHE
+  }
+  return path.join(process.cwd(), '.cache', 'external-tools')
+}
+
+function getToolCachePath(tool, version) {
+  const archMap = { arm64: 'aarch64', x64: 'x86_64' }
+  const osMap = { darwin: 'darwin', linux: 'linux', win32: 'win32' }
+  const target = `${osMap[process.platform] || process.platform}-${archMap[process.arch] || process.arch}`
+  return path.join(getCacheDir(), tool, `${version}-${target}`)
+}
+
+function computeSha256(filePath) {
+  return new Promise((resolve, reject) => {
+    const hash = createHash('sha256')
+    const stream = createReadStream(filePath)
+    stream.on('data', data => hash.update(data))
+    stream.on('end', () => resolve(hash.digest('hex')))
+    stream.on('error', reject)
+  })
+}
+
+function verifyCacheIntegrity(cachePath, expectedSha256) {
+  const checksumFile = path.join(cachePath, '.checksum')
+  if (!existsSync(checksumFile)) return false
+  try {
+    return readFileSync(checksumFile, 'utf8').trim() === expectedSha256
+  } catch {
+    return false
+  }
+}
+
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function acquireLock(lockPath, timeoutMs = 120_000) {
+  await mkdir(path.dirname(lockPath), { recursive: true })
+  const start = Date.now()
+  while (Date.now() - start < timeoutMs) {
+    try {
+      const fd = await open(lockPath, 'wx')
+      await fd.writeFile(String(process.pid))
+      await fd.close()
+      return async () => {
+        await unlink(lockPath).catch(() => {})
+      }
+    } catch (err) {
+      if (err.code === 'EEXIST') {
+        try {
+          const pid = parseInt(readFileSync(lockPath, 'utf8').trim(), 10)
+          if (pid && !isProcessAlive(pid)) {
+            await unlink(lockPath).catch(() => {})
+            continue
+          }
+        } catch {}
+        await new Promise(r => setTimeout(r, 500))
+        continue
+      }
+      throw err
+    }
+  }
+  throw new Error(`Timed out waiting for lock: ${lockPath}`)
+}
+
+async function downloadAndVerify(tool, config) {
+  const platformKey = `${process.platform}-${process.arch}`
+  const assetInfo = config.assets[platformKey]
+  if (!assetInfo) {
+    log.warn(`No ${tool} binary available for ${platformKey}`)
+    return undefined
+  }
+
+  const { version, binary } = config
+  const cachePath = getToolCachePath(tool, version)
+  const binaryName = WIN32 ? `${binary}.exe` : binary
+  const binaryPath = path.join(cachePath, binaryName)
+
+  // Check cache with integrity verification.
+  if (
+    existsSync(binaryPath) &&
+    verifyCacheIntegrity(cachePath, assetInfo.sha256)
+  ) {
+    log.step(`Using cached ${tool} ${version}`)
+    return binaryPath
+  }
+
+  const lockPath = path.join(getCacheDir(), `.lock-${tool}-${version}`)
+  const releaseLock = await acquireLock(lockPath)
+
+  try {
+    // Re-check after lock (another process may have completed).
+    if (
+      existsSync(binaryPath) &&
+      verifyCacheIntegrity(cachePath, assetInfo.sha256)
+    ) {
+      log.step(`Using cached ${tool} ${version}`)
+      return binaryPath
+    }
+
+    // Clean corrupted cache.
+    if (existsSync(cachePath)) {
+      await rm(cachePath, { recursive: true, force: true })
+    }
+
+    const tmpDir = path.join(
+      getCacheDir(),
+      `.tmp-${tool}-${version}-${process.pid}`,
+    )
+    await mkdir(tmpDir, { recursive: true })
+    const url = `https://github.com/${config.repository}/releases/download/v${version}/${assetInfo.asset}`
+    const archivePath = path.join(tmpDir, assetInfo.asset)
+
+    try {
+      log.step(`Downloading ${tool} ${version}...`)
+      const result = await spawn(
+        'curl',
+        ['-fSL', '--retry', '3', '-o', archivePath, url],
+        { stdio: quiet ? 'pipe' : 'inherit', shell: WIN32 },
+      )
+      if ((result.code ?? 0) !== 0) {
+        throw new Error(`Download failed: ${url}`)
+      }
+
+      // Verify checksum.
+      log.step('Verifying checksum...')
+      const actual = await computeSha256(archivePath)
+      if (actual !== assetInfo.sha256) {
+        throw new Error(
+          `Checksum mismatch for ${tool} ${version}:\n` +
+            `  Expected: ${assetInfo.sha256}\n` +
+            `  Actual:   ${actual}`,
+        )
+      }
+
+      // Extract.
+      log.step('Extracting...')
+      if (assetInfo.asset.endsWith('.zip')) {
+        const unzipResult = await spawn(
+          WIN32 ? 'powershell' : 'unzip',
+          WIN32
+            ? [
+                '-Command',
+                `Expand-Archive -Path '${archivePath}' -DestinationPath '${tmpDir}' -Force`,
+              ]
+            : ['-q', '-o', archivePath, '-d', tmpDir],
+          { stdio: 'pipe', shell: WIN32 },
+        )
+        if ((unzipResult.code ?? 0) !== 0) {
+          throw new Error(`Extraction failed for ${archivePath}`)
+        }
+      } else {
+        const tarResult = await spawn(
+          'tar',
+          ['xf', archivePath, '-C', tmpDir],
+          { stdio: 'pipe', shell: WIN32 },
+        )
+        if ((tarResult.code ?? 0) !== 0) {
+          throw new Error(`Extraction failed for ${archivePath}`)
+        }
+      }
+
+      // Write checksum marker, then move to cache.
+      await mkdir(cachePath, { recursive: true })
+      const extractedBinary = path.join(tmpDir, binaryName)
+      if (!existsSync(extractedBinary)) {
+        throw new Error(`Binary not found after extraction: ${extractedBinary}`)
+      }
+
+      const { copyFile, chmod } = await import('node:fs/promises')
+      await copyFile(extractedBinary, path.join(cachePath, binaryName))
+      if (!WIN32) {
+        await chmod(path.join(cachePath, binaryName), 0o755)
+      }
+      await writeFile(path.join(cachePath, '.checksum'), assetInfo.sha256)
+
+      await rm(tmpDir, { recursive: true, force: true }).catch(() => {})
+      log.success(`${tool} ${version} installed`)
+      return path.join(cachePath, binaryName)
+    } catch (err) {
+      await rm(tmpDir, { recursive: true, force: true }).catch(() => {})
+      throw err
+    }
+  } finally {
+    await releaseLock()
+  }
+}
+
+async function main() {
+  if (!quiet) {
+    logger.log('\n🔧 Developer Setup\n')
+  }
+
+  // Load external tools config.
+  const configPath = path.join(process.cwd(), 'external-tools.json')
+  if (!existsSync(configPath)) {
+    log.warn('No external-tools.json found')
+    return
+  }
+  const config = JSON.parse(await readFile(configPath, 'utf8'))
+
+  let allOk = true
+  for (const [tool, toolConfig] of Object.entries(config)) {
+    if (toolConfig.type !== 'github-release') continue
+    try {
+      const binaryPath = await downloadAndVerify(tool, toolConfig)
+      if (binaryPath) {
+        log.info(`${tool} ${toolConfig.version}: ${binaryPath}`)
+      } else {
+        log.warn(`${tool}: skipped (unsupported platform)`)
+      }
+    } catch (err) {
+      log.error(`Failed to install ${tool}: ${err.message}`)
+      allOk = false
+    }
+  }
+
+  if (!quiet) {
+    if (allOk) {
+      logger.success('Setup complete')
+    } else {
+      logger.warn('Setup completed with warnings')
+    }
+    logger.log('')
+  }
+}
+
+main().catch(e => {
+  logger.error(e)
+  process.exitCode = 1
+})

From bb9f58255bed1c056bfb501ba1d4af71f8cc795a Mon Sep 17 00:00:00 2001
From: jdalton <john.david.dalton@gmail.com>
Date: Sun, 5 Apr 2026 17:36:47 -0400
Subject: [PATCH 02/10] chore: add agents, ci-cascade skill, and
 release-changelog command

Agents (reference CLAUDE.md rules, don't duplicate them):
- code-reviewer: applies code style, test style, sorting rules
- security-reviewer: applies safe file ops, secret detection, dependency rules
- refactor-cleaner: applies pre-action protocol, dead code removal, scope rules

Skills:
- ci-cascade: extracts SHA pin cascade procedure from CLAUDE.md into executable workflow

Commands:
- release-changelog: generates changelog entries following Keep a Changelog format
---
 .claude/agents/code-reviewer.md       | 21 ++++++++++
 .claude/agents/refactor-cleaner.md    | 25 +++++++++++
 .claude/agents/security-reviewer.md   | 26 ++++++++++++
 .claude/commands/release-changelog.md | 17 ++++++++
 .claude/skills/ci-cascade/SKILL.md    | 60 +++++++++++++++++++++++++++
 .gitignore                            |  3 +-
 6 files changed, 151 insertions(+), 1 deletion(-)
 create mode 100644 .claude/agents/code-reviewer.md
 create mode 100644 .claude/agents/refactor-cleaner.md
 create mode 100644 .claude/agents/security-reviewer.md
 create mode 100644 .claude/commands/release-changelog.md
 create mode 100644 .claude/skills/ci-cascade/SKILL.md

diff --git a/.claude/agents/code-reviewer.md b/.claude/agents/code-reviewer.md
new file mode 100644
index 00000000..70860976
--- /dev/null
+++ b/.claude/agents/code-reviewer.md
@@ -0,0 +1,21 @@
+You are a code reviewer for a Node.js/TypeScript monorepo (socket-registry).
+
+Apply these rules from CLAUDE.md exactly:
+
+**Code Style - File Organization**: kebab-case filenames, @fileoverview headers, node: prefix imports, import sorting order (node → external → @socketsecurity → local → types).
+
+**Code Style - Patterns**: UPPER_SNAKE_CASE constants, undefined over null, __proto__: null first in literals, { 0: key, 1: val } for entries loops, !array.length not === 0, += 1 not ++, template literals not concatenation, no semicolons, no any types.
+
+**Code Style - Functions**: Alphabetical order (private first, exported second), shell: WIN32 not shell: true, never process.chdir().
+
+**Code Style - Comments**: Default NO comments. Only when WHY is non-obvious. End with periods. Single-line only. JSDoc: description + @throws only.
+
+**Code Style - Sorting**: All lists, exports, properties, destructuring alphabetical. Type properties: required first, optional second.
+
+**Test Style**: Functional tests over source scanning. Never read source files and assert on contents. Verify behavior with real function calls.
+
+For each file reviewed, report:
+- **Style violations** with file:line
+- **Logic issues** (bugs, edge cases, missing error handling)
+- **Test gaps** (untested code paths)
+- Suggested fix for each finding
diff --git a/.claude/agents/refactor-cleaner.md b/.claude/agents/refactor-cleaner.md
new file mode 100644
index 00000000..4f3230fc
--- /dev/null
+++ b/.claude/agents/refactor-cleaner.md
@@ -0,0 +1,25 @@
+You are a refactoring specialist for a Node.js/TypeScript monorepo (socket-registry).
+
+Apply these rules from CLAUDE.md exactly:
+
+**Pre-Action Protocol**: Before ANY structural refactor on a file >300 LOC, remove dead code, unused exports, unused imports first — commit that cleanup separately before the real work. Multi-file changes: break into phases (≤5 files each), verify each phase.
+
+**Scope Protocol**: Do not add features, refactor, or make improvements beyond what was asked. Try simplest approach first.
+
+**Verification Protocol**: Run the actual command after changes. State what you verified. Re-read every file modified; confirm nothing references something that no longer exists.
+
+**Procedure:**
+
+1. **Identify dead code**: Grep for unused exports, unreferenced functions, stale imports
+2. **Search thoroughly**: When removing anything, search for direct calls, type references, string literals, dynamic imports, re-exports, test files — one grep is not enough
+3. **Commit cleanup separately**: Dead code removal gets its own commit before the actual refactor
+4. **Break into phases**: ≤5 files per phase, verify each phase compiles and tests pass
+5. **Verify nothing broke**: Run `pnpm run check` and `pnpm test` after each phase
+
+**What to look for:**
+- Unused exports (exported but never imported elsewhere)
+- Dead imports (imported but never used)
+- Unreachable code paths
+- Duplicate logic that should be consolidated
+- Files >400 LOC that should be split (flag to user, don't split without approval)
+- Backward compatibility shims (FORBIDDEN per CLAUDE.md — actively remove)
diff --git a/.claude/agents/security-reviewer.md b/.claude/agents/security-reviewer.md
new file mode 100644
index 00000000..236330f1
--- /dev/null
+++ b/.claude/agents/security-reviewer.md
@@ -0,0 +1,26 @@
+You are a security reviewer for Socket Security Node.js repositories.
+
+Apply these rules from CLAUDE.md exactly:
+
+**Safe File Operations**: Use safeDelete()/safeDeleteSync() from @socketsecurity/lib/fs. NEVER fs.rm(), fs.rmSync(), or rm -rf. NEVER use os.tmpdir() — use tempDir from @socketsecurity/lib/env/temp-dir.
+
+**Absolute Rules**: NEVER use npx, pnpm dlx, or yarn dlx. Use pnpm exec or pnpm run with pinned devDeps.
+
+**Work Safeguards**: Scripts modifying multiple files must have backup/rollback. Git operations that rewrite history require explicit confirmation.
+
+**Review checklist:**
+
+1. **Secrets**: Hardcoded API keys, passwords, tokens, private keys in code or config
+2. **Injection**: Command injection via shell: true or string interpolation in spawn/exec. Path traversal in file operations.
+3. **Dependencies**: npx/dlx usage. Unpinned versions (^ or ~). Missing minimumReleaseAge bypass justification.
+4. **File operations**: fs.rm without safeDelete. os.tmpdir usage. process.chdir usage.
+5. **GitHub Actions**: Unpinned action versions (must use full SHA). Secrets outside env blocks. Template injection from untrusted inputs.
+6. **Error handling**: Sensitive data in error messages. Stack traces exposed to users.
+
+For each finding, report:
+- **Severity**: CRITICAL / HIGH / MEDIUM / LOW
+- **Location**: file:line
+- **Issue**: what's wrong
+- **Fix**: how to fix it
+
+Run `pnpm audit` for dependency vulnerabilities. Run `pnpm run security` for config/workflow scanning.
diff --git a/.claude/commands/release-changelog.md b/.claude/commands/release-changelog.md
new file mode 100644
index 00000000..880a1407
--- /dev/null
+++ b/.claude/commands/release-changelog.md
@@ -0,0 +1,17 @@
+Generate a changelog entry for the next release.
+
+Follow the format from CLAUDE.md § "Changelog Management":
+- Format: `## [version](https://github.com/SocketDev/socket-registry/releases/tag/vversion) - YYYY-MM-DD`
+- Follow [Keep a Changelog](https://keepachangelog.com/)
+- Sections: Added, Changed, Fixed, Removed
+- User-facing changes only (no internal refactoring, deps, or CI)
+
+Steps:
+1. Read current CHANGELOG.md to get the last released version
+2. Run `git log --oneline <last-tag>..HEAD` to see all commits since last release
+3. Categorize each commit into Added/Changed/Fixed/Removed
+4. Skip chore/ci/deps commits unless they affect user-facing behavior
+5. Determine version bump: feat → minor, fix → patch, breaking → major
+6. Write the new entry at the top of CHANGELOG.md
+7. Update version in package.json
+8. Present the changelog for review before committing
diff --git a/.claude/skills/ci-cascade/SKILL.md b/.claude/skills/ci-cascade/SKILL.md
new file mode 100644
index 00000000..65434fcc
--- /dev/null
+++ b/.claude/skills/ci-cascade/SKILL.md
@@ -0,0 +1,60 @@
+---
+name: ci-cascade
+description: Execute the GitHub Actions SHA pin cascade when a socket-registry action changes. Creates PRs in dependency order, waits for merges, and propagates the final SHA to all consuming repos.
+---
+
+# CI SHA Pin Cascade
+
+Implements the cascade procedure defined in CLAUDE.md § "GitHub Actions SHA Pin Cascade (CRITICAL)".
+
+## When to Use
+
+- After modifying any GitHub Action in `.github/actions/`
+- After modifying a reusable workflow in `.github/workflows/ci.yml` or `provenance.yml`
+- When a dependency (Node.js version, pnpm version, sfw-free) changes in an action
+
+## Procedure
+
+Follow the layer order exactly. Each layer gets its own PR. Never combine layers.
+
+### Phase 1: Identify what changed
+
+Determine which layer was modified:
+- Layer 1 (leaf actions): checkout, install, debug, setup-git-signing, cleanup-git-signing, run-script, artifacts, cache-npm-packages
+- Layer 2a (setup): references debug
+- Layer 2b (setup-and-install): references checkout, setup, install
+- Layer 3 (reusable workflows): ci.yml, provenance.yml
+- Layer 4 (local wrappers): _local-not-for-reuse-*
+
+### Phase 2: Create PRs in order
+
+Starting from the layer above the change, create a PR for each layer:
+
+1. **Get current SHA**: `git fetch origin main && git rev-parse origin/main`
+2. **Create branch**: `git checkout -b chore/ci-cascade-layer-N`
+3. **Update refs**: Replace old SHA with new SHA in all files at this layer
+4. **Verify**: `grep -rn "SocketDev/socket-registry" .github/ | grep "@" | grep -v "<new-sha>"`
+5. **Don't clobber**: Never replace third-party SHAs (actions/checkout, actions/upload-artifact, etc.)
+6. **Commit**: `chore(ci): bump socket-registry action refs to main (<short-sha>)`
+7. **Push and create PR**
+8. **Wait for merge** before proceeding to next layer
+
+### Phase 3: Propagate to external repos
+
+The **propagation SHA** is the Layer 3 merge SHA (where ci.yml and provenance.yml were updated). All external repos pin to this same SHA.
+
+External repos (update all):
+- socket-btm, socket-cli, socket-sdk-js, socket-packageurl-js
+- socket-sbom-generator, socket-lib, ultrathink
+
+For each repo:
+1. Update all `SocketDev/socket-registry/.github/` refs to the propagation SHA
+2. Push directly to main where allowed
+3. Create PRs where branch protection requires it
+
+### Phase 4: Verify
+
+For each updated repo, confirm no old SHAs remain:
+```bash
+grep -rn "SocketDev/socket-registry" .github/ | grep "@" | grep -v "<propagation-sha>"
+```
diff --git a/.gitignore b/.gitignore
index ce9658ca..055220d5 100644
--- a/.gitignore
+++ b/.gitignore
@@ -19,8 +19,9 @@ WIP
 
 # Claude Code scratch files
 /.claude/*
-!/.claude/skills/
+!/.claude/agents/
 !/.claude/commands/
+!/.claude/skills/
 
 # Environment files
 /.env

From 111c85586cc8af71608def68d9579f52c5ebb4bb Mon Sep 17 00:00:00 2001
From: jdalton <john.david.dalton@gmail.com>
Date: Sun, 5 Apr 2026 18:09:11 -0400
Subject: [PATCH 03/10] fix: address audit findings in agents, skills, and
 commands
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- security-reviewer: remove fabricated os.tmpdir() prohibition (CLAUDE.md
  recommends it), add fetch() prohibition from CLAUDE.md
- code-reviewer: add missing rules (undefined over null, __proto__: null,
  error handling, backward compat, spawn, loop annotations)
- ci-cascade: add missing Layer 4 (local wrappers) before external propagation
- quality-scan: fix "4 scan types" → "all scan types", fix "Task tool" → "Agent tool"
- quality-loop: remove stale architectural issue from wrong repo (socket-btm)
- Delete stale scratch scripts from .claude/ (migration scripts, update-workflow-shas)
---
 .claude/agents/code-reviewer.md      | 14 +++++++++-----
 .claude/agents/security-reviewer.md  |  4 ++--
 .claude/commands/quality-loop.md     | 28 ----------------------------
 .claude/skills/ci-cascade/SKILL.md   | 18 ++++++++++--------
 .claude/skills/quality-scan/SKILL.md |  8 ++++----
 5 files changed, 25 insertions(+), 47 deletions(-)

diff --git a/.claude/agents/code-reviewer.md b/.claude/agents/code-reviewer.md
index 70860976..2f5f2039 100644
--- a/.claude/agents/code-reviewer.md
+++ b/.claude/agents/code-reviewer.md
@@ -1,17 +1,21 @@
 You are a code reviewer for a Node.js/TypeScript monorepo (socket-registry).
 
-Apply these rules from CLAUDE.md exactly:
+Apply the rules from CLAUDE.md sections listed below. Reference the full section in CLAUDE.md for details — these are summaries, not the complete rules.
 
-**Code Style - File Organization**: kebab-case filenames, @fileoverview headers, node: prefix imports, import sorting order (node → external → @socketsecurity → local → types).
+**Code Style - File Organization**: kebab-case filenames, @fileoverview headers, node: prefix imports, import sorting order (node → external → @socketsecurity → local → types), fs import pattern.
 
-**Code Style - Patterns**: UPPER_SNAKE_CASE constants, undefined over null, __proto__: null first in literals, { 0: key, 1: val } for entries loops, !array.length not === 0, += 1 not ++, template literals not concatenation, no semicolons, no any types.
+**Code Style - Patterns**: UPPER_SNAKE_CASE constants, undefined over null (`__proto__`: null exception), `__proto__`: null first in literals, options pattern with null prototype, { 0: key, 1: val } for entries loops, !array.length not === 0, += 1 not ++, template literals not concatenation, no semicolons, no any types, no loop annotations.
 
-**Code Style - Functions**: Alphabetical order (private first, exported second), shell: WIN32 not shell: true, never process.chdir().
+**Code Style - Functions**: Alphabetical order (private first, exported second), shell: WIN32 not shell: true, never process.chdir(), use @socketsecurity/registry/lib/spawn not child_process.
 
-**Code Style - Comments**: Default NO comments. Only when WHY is non-obvious. End with periods. Single-line only. JSDoc: description + @throws only.
+**Code Style - Comments**: Default NO comments. Only when WHY is non-obvious. Multi-sentence comments end with periods; single phrases may not. Single-line only. JSDoc: description + @throws only.
 
 **Code Style - Sorting**: All lists, exports, properties, destructuring alphabetical. Type properties: required first, optional second.
 
+**Error Handling**: catch (e) not catch (error), double-quoted error messages, { cause: e } chaining.
+
+**Backward Compatibility**: FORBIDDEN — actively remove compat shims, don't maintain them.
+
 **Test Style**: Functional tests over source scanning. Never read source files and assert on contents. Verify behavior with real function calls.
 
 For each file reviewed, report:
diff --git a/.claude/agents/security-reviewer.md b/.claude/agents/security-reviewer.md
index 236330f1..a5625045 100644
--- a/.claude/agents/security-reviewer.md
+++ b/.claude/agents/security-reviewer.md
@@ -2,7 +2,7 @@ You are a security reviewer for Socket Security Node.js repositories.
 
 Apply these rules from CLAUDE.md exactly:
 
-**Safe File Operations**: Use safeDelete()/safeDeleteSync() from @socketsecurity/lib/fs. NEVER fs.rm(), fs.rmSync(), or rm -rf. NEVER use os.tmpdir() — use tempDir from @socketsecurity/lib/env/temp-dir.
+**Safe File Operations**: Use safeDelete()/safeDeleteSync() from @socketsecurity/lib/fs. NEVER fs.rm(), fs.rmSync(), or rm -rf. Use os.tmpdir() + fs.mkdtemp() for temp dirs. NEVER use fetch() — use httpJson/httpText/httpRequest from @socketsecurity/lib/http-request.
 
 **Absolute Rules**: NEVER use npx, pnpm dlx, or yarn dlx. Use pnpm exec or pnpm run with pinned devDeps.
 
@@ -13,7 +13,7 @@ Apply these rules from CLAUDE.md exactly:
 1. **Secrets**: Hardcoded API keys, passwords, tokens, private keys in code or config
 2. **Injection**: Command injection via shell: true or string interpolation in spawn/exec. Path traversal in file operations.
 3. **Dependencies**: npx/dlx usage. Unpinned versions (^ or ~). Missing minimumReleaseAge bypass justification.
-4. **File operations**: fs.rm without safeDelete. os.tmpdir usage. process.chdir usage.
+4. **File operations**: fs.rm without safeDelete. process.chdir usage. fetch() usage (must use lib's httpRequest).
 5. **GitHub Actions**: Unpinned action versions (must use full SHA). Secrets outside env blocks. Template injection from untrusted inputs.
 6. **Error handling**: Sensitive data in error messages. Stack traces exposed to users.
 
diff --git a/.claude/commands/quality-loop.md b/.claude/commands/quality-loop.md
index a818f350..9840165d 100644
--- a/.claude/commands/quality-loop.md
+++ b/.claude/commands/quality-loop.md
@@ -16,31 +16,3 @@ Run the quality-scan skill and fix all issues found. Repeat until zero issues re
 - Do not skip architectural fixes
 - Run tests after fixes to verify nothing broke
 - Track iteration count and report progress
-
-## Outstanding Architectural Issue (Requires Design Review)
-
-### Checkpoint Cache Invalidation (High Severity)
-
-**Issue**: Source package changes don't invalidate checkpoints properly.
-
-**Root Cause**: Cache keys are computed AFTER `prepareExternalSources()` syncs source packages to additions/. Since cache keys hash files in additions/ (which are now synced), they match the checkpoint even though source packages changed.
-
-**Scenario**:
-1. Developer modifies `packages/binject/src/socketsecurity/binject/file.c`
-2. Runs `pnpm --filter node-smol-builder clean && pnpm build`
-3. `prepareExternalSources()` syncs binject → additions/source-patched/src/socketsecurity/binject/
-4. Cache key computed from additions/ files matches old checkpoint
-5. Build restores stale checkpoint, skips recompilation
-6. **Result**: Binary contains old binject code
-
-**Impact**: Silent build incorrectness when modifying source packages
-
-**Proposed Solutions** (require architectural review):
-- Option 1: Include source package mtimes in cache key metadata
-- Option 2: Make `prepareExternalSources()` idempotent, always re-sync
-
-**Files Affected**:
-- packages/node-smol-builder/scripts/common/shared/build.mjs (collectBuildSourceFiles)
-- packages/node-smol-builder/scripts/common/shared/checkpoints.mjs (cache key generation)
-
-**Status**: Documented for architectural review and future implementation
diff --git a/.claude/skills/ci-cascade/SKILL.md b/.claude/skills/ci-cascade/SKILL.md
index 65434fcc..efea0724 100644
--- a/.claude/skills/ci-cascade/SKILL.md
+++ b/.claude/skills/ci-cascade/SKILL.md
@@ -39,20 +39,22 @@ Starting from the layer above the change, create a PR for each layer:
 7. **Push and create PR**
 8. **Wait for merge** before proceeding to next layer
 
-### Phase 3: Propagate to external repos
+### Phase 3: Update Layer 4 (local wrappers)
 
-The **propagation SHA** is the Layer 3 merge SHA (where ci.yml and provenance.yml were updated). All external repos pin to this same SHA.
+After Layer 3 merges, get the **propagation SHA** (Layer 3 merge SHA). Update the `_local-not-for-reuse-*` workflows to pin to this SHA. Create a PR, merge it.
 
-External repos (update all):
-- socket-btm, socket-cli, socket-sdk-js, socket-packageurl-js
-- socket-sbom-generator, socket-lib, ultrathink
+The Layer 4 merge SHA is NOT used for external pinning — external repos pin to the Layer 3 SHA because that's where the reusable workflows (ci.yml, provenance.yml) were updated.
+
+### Phase 4: Propagate to external repos
+
+All external repos pin to the **propagation SHA** (Layer 3 merge SHA).
 
 For each repo:
 1. Update all `SocketDev/socket-registry/.github/` refs to the propagation SHA
-2. Push directly to main where allowed
-3. Create PRs where branch protection requires it
+2. Push directly to main where allowed (socket-btm, socket-sbom-generator, ultrathink)
+3. Create PRs where branch protection requires it (socket-cli, socket-lib, socket-sdk-js, socket-packageurl-js)
 
-### Phase 4: Verify
+### Phase 5: Verify
 
 For each updated repo, confirm no old SHAs remain:
 ```bash
diff --git a/.claude/skills/quality-scan/SKILL.md b/.claude/skills/quality-scan/SKILL.md
index 7b895a54..6e8866fc 100644
--- a/.claude/skills/quality-scan/SKILL.md
+++ b/.claude/skills/quality-scan/SKILL.md
@@ -312,7 +312,7 @@ Use AskUserQuestion tool:
 - Header: "Scan Types"
 - multiSelect: true
 - Options:
-  - "All scans (recommended)" → Run all 4 scan types
+  - "All scans (recommended)" → Run all scan types
   - "Critical only" → Run critical scan only
   - "Critical + Logic" → Run critical and logic scans
   - "Custom selection" → Ask user to specify which scans
@@ -336,7 +336,7 @@ If user requests non-existent scan type, report error and suggest valid types.
 ### Phase 6: Execute Scans
 
 <action>
-For each enabled scan type, spawn a specialized agent using Task tool:
+For each enabled scan type, spawn a specialized agent using Agent tool:
 </action>
 
 ```typescript
@@ -365,7 +365,7 @@ Scan systematically and report all findings. If no issues found, state that expl
 **For each scan:**
 1. Load agent prompt template from `reference.md`
 2. Customize for repository context (determine monorepo vs single package structure)
-3. Spawn agent with Task tool using "general-purpose" subagent_type
+3. Spawn agent with Agent tool using "general-purpose" subagent_type
 4. Capture findings from agent response
 5. Parse and categorize results
 
@@ -617,7 +617,7 @@ This skill is self-contained. No external commands needed.
 
 This skill provides systematic code quality analysis by:
 - Spawning specialized agents for targeted analysis
-- Using Task tool to run agents autonomously
+- Using Agent tool to run agents autonomously
 - Embedding agent prompts in reference.md following best practices
 - Generating prioritized, actionable reports
 - Supporting partial scans (user can select specific scan types)

From 7e2a9587832df39e488b8fe084955c2720a38475 Mon Sep 17 00:00:00 2001
From: jdalton <john.david.dalton@gmail.com>
Date: Sun, 5 Apr 2026 23:28:28 -0400
Subject: [PATCH 04/10] feat: implement skill graph architecture
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Shared subskills (_shared/):
- env-check: environment validation for all pipelines
- verify-build: pnpm fix/check/test pattern
- security-tools: zizmor + agentshield + socket CLI detection
- report-format: severity levels, A-F grading, HANDOFF protocol

New skills:
- security-scan: promoted from command to full pipeline
  (agentshield → zizmor → security-reviewer agent grading)
- release: orchestrator pipeline
  (quality gate → security gate → changelog → version bump)

Pipeline state tracking:
- .claude/ops/queue.yaml: tracks pipeline runs with phase progression

Updated commands:
- security-scan: delegates to security-scan skill
- release-changelog: delegates to release skill
- quality-loop: references refactor-cleaner agent for fixes

Architecture: 5 pipelines, 4 shared subskills, 3 agents wired in.
Follows arscontexta queue pattern and Socket Skills orchestrator pattern.
---
 .claude/commands/quality-loop.md         | 17 ++---
 .claude/commands/release-changelog.md    | 18 +----
 .claude/commands/security-scan.md        | 23 +------
 .claude/ops/queue.yaml                   | 10 +++
 .claude/skills/_shared/env-check.md      | 27 ++++++++
 .claude/skills/_shared/report-format.md  | 47 +++++++++++++
 .claude/skills/_shared/security-tools.md | 30 ++++++++
 .claude/skills/_shared/verify-build.md   | 22 ++++++
 .claude/skills/release/SKILL.md          | 88 ++++++++++++++++++++++++
 .claude/skills/security-scan/SKILL.md    | 82 ++++++++++++++++++++++
 .gitignore                               |  1 +
 11 files changed, 320 insertions(+), 45 deletions(-)
 create mode 100644 .claude/ops/queue.yaml
 create mode 100644 .claude/skills/_shared/env-check.md
 create mode 100644 .claude/skills/_shared/report-format.md
 create mode 100644 .claude/skills/_shared/security-tools.md
 create mode 100644 .claude/skills/_shared/verify-build.md
 create mode 100644 .claude/skills/release/SKILL.md
 create mode 100644 .claude/skills/security-scan/SKILL.md

diff --git a/.claude/commands/quality-loop.md b/.claude/commands/quality-loop.md
index 9840165d..3d0da6b4 100644
--- a/.claude/commands/quality-loop.md
+++ b/.claude/commands/quality-loop.md
@@ -1,18 +1,19 @@
-Run the quality-scan skill and fix all issues found. Repeat until zero issues remain or 5 iterations complete.
+Run the `/quality-scan` skill and fix all issues found. Repeat until zero issues remain or 5 iterations complete.
 
 ## Process
 
-1. Run quality-scan skill
-2. If issues found: fix ALL of them
-3. Run quality-scan again
-4. Repeat until:
+1. Run `/quality-scan` skill (all scan types)
+2. If issues found: spawn the `refactor-cleaner` agent (see `agents/refactor-cleaner.md`) to fix them, grouped by category
+3. Run verify-build (see `_shared/verify-build.md`) after fixes
+4. Run `/quality-scan` again
+5. Repeat until:
    - Zero issues found (success), OR
    - 5 iterations completed (stop)
-5. Commit all fixes with message: "fix: resolve quality scan issues (iteration N)"
+6. Commit all fixes: `fix: resolve quality scan issues (iteration N)`
 
 ## Rules
 
-- Fix every issue, not just "easy" ones
-- Do not skip architectural fixes
+- Fix every issue, not just easy ones
+- Spawn refactor-cleaner with CLAUDE.md's pre-action protocol: dead code first, then structural changes, ≤5 files per phase
 - Run tests after fixes to verify nothing broke
 - Track iteration count and report progress
diff --git a/.claude/commands/release-changelog.md b/.claude/commands/release-changelog.md
index 880a1407..c119573b 100644
--- a/.claude/commands/release-changelog.md
+++ b/.claude/commands/release-changelog.md
@@ -1,17 +1,3 @@
-Generate a changelog entry for the next release.
+Run the `/release` skill starting from the changelog phase.
 
-Follow the format from CLAUDE.md § "Changelog Management":
-- Format: `## [version](https://github.com/SocketDev/socket-registry/releases/tag/vversion) - YYYY-MM-DD`
-- Follow [Keep a Changelog](https://keepachangelog.com/)
-- Sections: Added, Changed, Fixed, Removed
-- User-facing changes only (no internal refactoring, deps, or CI)
-
-Steps:
-1. Read current CHANGELOG.md to get the last released version
-2. Run `git log --oneline <last-tag>..HEAD` to see all commits since last release
-3. Categorize each commit into Added/Changed/Fixed/Removed
-4. Skip chore/ci/deps commits unless they affect user-facing behavior
-5. Determine version bump: feat → minor, fix → patch, breaking → major
-6. Write the new entry at the top of CHANGELOG.md
-7. Update version in package.json
-8. Present the changelog for review before committing
+If you want the full release pipeline (quality gate → security gate → changelog → version bump), run `/release` instead.
diff --git a/.claude/commands/security-scan.md b/.claude/commands/security-scan.md
index 42e36005..6c629680 100644
--- a/.claude/commands/security-scan.md
+++ b/.claude/commands/security-scan.md
@@ -1,22 +1,3 @@
-Run a security scan of the project via `pnpm run security`, or manually:
+Run the `/security-scan` skill. This chains AgentShield (Claude config audit) → zizmor (GitHub Actions security) → security-reviewer agent (grading).
 
-## 1. Claude Code configuration security
-
-Run `pnpm exec agentshield scan` to check `.claude/` for:
-- Hardcoded secrets in CLAUDE.md and settings
-- Overly permissive tool allow lists (e.g. `Bash(*)`)
-- Prompt injection patterns in agent definitions
-- Command injection risks in hooks
-- Risky MCP server configurations
-
-## 2. GitHub Actions workflow security
-
-Run `zizmor .github/` to scan all workflows for:
-- Unpinned actions (should use full SHA, not tags)
-- Secrets used outside `env:` blocks
-- Injection risks from untrusted inputs
-- Overly permissive permissions
-
-If zizmor is not installed, skip with a message. Install via `brew install zizmor` or see https://docs.zizmor.sh/installation/.
-
-Report all findings with severity levels. Fix CRITICAL and HIGH findings immediately.
+For a quick manual run without the full pipeline: `pnpm run security`
diff --git a/.claude/ops/queue.yaml b/.claude/ops/queue.yaml
new file mode 100644
index 00000000..7264d957
--- /dev/null
+++ b/.claude/ops/queue.yaml
@@ -0,0 +1,10 @@
+schema_version: 1
+
+phase_order:
+  quality-scan: [env-check, dep-update, cleanup, structural, scans, report]
+  security-scan: [env-check, agentshield, zizmor, grade-report]
+  updating: [env-check, npm-update, validate]
+  ci-cascade: [identify, layer-prs, propagate, verify]
+  release: [quality-gate, security-gate, changelog, version-bump]
+
+runs: []
diff --git a/.claude/skills/_shared/env-check.md b/.claude/skills/_shared/env-check.md
new file mode 100644
index 00000000..ee2c203d
--- /dev/null
+++ b/.claude/skills/_shared/env-check.md
@@ -0,0 +1,27 @@
+# Environment Check
+
+Shared prerequisite validation for all pipelines. Run at the start of every skill.
+
+## Steps
+
+1. Run `git status` to check working directory state
+2. Detect CI mode: check for `GITHUB_ACTIONS` or `CI` environment variables
+3. Verify `node_modules/` exists (run `pnpm install` if missing)
+4. Verify on a valid branch (`git branch --show-current`)
+
+## Behavior
+
+- **Clean working directory**: proceed normally
+- **Dirty working directory**: warn and continue (most skills are read-only or create their own commits)
+- **CI mode**: set `CI_MODE=true` — skills should skip interactive prompts and local-only validation
+- **Missing node_modules**: run `pnpm install` before proceeding
+
+## Queue Tracking
+
+Write a run entry to `.claude/ops/queue.yaml` with:
+- `id`: `{pipeline}-{YYYY-MM-DD}-{NNN}`
+- `pipeline`: the invoking skill name
+- `status`: `in-progress`
+- `started`: current UTC timestamp
+- `current_phase`: `env-check`
+- `completed_phases`: `[]`
diff --git a/.claude/skills/_shared/report-format.md b/.claude/skills/_shared/report-format.md
new file mode 100644
index 00000000..3e8cdce7
--- /dev/null
+++ b/.claude/skills/_shared/report-format.md
@@ -0,0 +1,47 @@
+# Report Format
+
+Shared output format for all scan and review pipelines.
+
+## Finding Format
+
+Each finding:
+```
+- **[SEVERITY]** file:line — description
+  Fix: how to fix it
+```
+
+Severity levels: CRITICAL, HIGH, MEDIUM, LOW
+
+## Grade Calculation
+
+Based on finding severity distribution:
+- **A** (90-100): 0 critical, 0 high
+- **B** (80-89): 0 critical, 1-3 high
+- **C** (70-79): 0 critical, 4+ high OR 1 critical
+- **D** (60-69): 2-3 critical
+- **F** (< 60): 4+ critical
+
+## Pipeline HANDOFF
+
+When a skill completes as part of a larger pipeline (e.g., quality-scan within release),
+output a structured handoff block:
+
+```
+=== HANDOFF: {skill-name} ===
+Status: {pass|fail}
+Grade: {A-F}
+Findings: {critical: N, high: N, medium: N, low: N}
+Summary: {one-line description}
+=== END HANDOFF ===
+```
+
+The parent pipeline reads this to decide whether to proceed (gate check) or abort.
+
+## Queue Completion
+
+When the final phase completes, update `.claude/ops/queue.yaml`:
+- `status`: `done` (or `failed`)
+- `completed`: current UTC timestamp
+- `current_phase`: `~` (null)
+- `completed_phases`: full list
+- `findings_count`: `{critical: N, high: N, medium: N, low: N}`
diff --git a/.claude/skills/_shared/security-tools.md b/.claude/skills/_shared/security-tools.md
new file mode 100644
index 00000000..8ab87d0c
--- /dev/null
+++ b/.claude/skills/_shared/security-tools.md
@@ -0,0 +1,30 @@
+# Security Tools
+
+Shared tool detection for security scanning pipelines.
+
+## AgentShield
+
+Installed as a pinned devDependency (`ecc-agentshield` in pnpm-workspace.yaml catalog).
+Run via: `pnpm exec agentshield scan`
+No install step needed — available after `pnpm install`.
+
+## Zizmor
+
+Not an npm package. Installed via `pnpm run setup` which downloads the pinned version
+from GitHub releases with SHA256 checksum verification (see `external-tools.json`).
+
+Detection: `command -v zizmor` or check `.cache/external-tools/zizmor/*/zizmor`
+
+If not available:
+- Warn: "zizmor not installed — run `pnpm run setup` to install"
+- Skip the zizmor phase (don't fail the pipeline)
+
+## Socket CLI
+
+Optional. Used for dependency scanning in the updating and security-scan pipelines.
+
+Detection: `command -v socket`
+
+If not available:
+- Skip socket-scan phases gracefully
+- Note in report: "Socket CLI not available — dependency scan skipped"
diff --git a/.claude/skills/_shared/verify-build.md b/.claude/skills/_shared/verify-build.md
new file mode 100644
index 00000000..5dc82c03
--- /dev/null
+++ b/.claude/skills/_shared/verify-build.md
@@ -0,0 +1,22 @@
+# Verify Build
+
+Shared build/test/lint validation. Referenced by skills that modify code or dependencies.
+
+## Steps
+
+Run in order, stop on first failure:
+
+1. `pnpm run fix --all` — auto-fix lint and formatting issues
+2. `pnpm run check --all` — lint + typecheck + validation (read-only, fails on violations)
+3. `pnpm test` — full test suite
+
+## CI Mode
+
+When `CI_MODE=true` (detected by env-check), skip this validation entirely.
+CI runs these checks in its own matrix (Node 20/22/24 × ubuntu/windows).
+
+## On Failure
+
+- Report which step failed with the error output
+- Do NOT proceed to the next pipeline phase
+- Mark the pipeline run as `status: failed` in `.claude/ops/queue.yaml`
diff --git a/.claude/skills/release/SKILL.md b/.claude/skills/release/SKILL.md
new file mode 100644
index 00000000..83ccf1c2
--- /dev/null
+++ b/.claude/skills/release/SKILL.md
@@ -0,0 +1,88 @@
+---
+name: release
+description: Release pipeline orchestrator. Runs quality and security gates, generates changelog, bumps version, and offers to publish.
+---
+
+# Release
+
+Orchestrates a release by chaining quality-scan and security-scan as gates, then generating a changelog and version bump.
+
+## When to Use
+
+- Preparing a new release
+- When `/release-changelog` command is invoked (delegates here)
+
+## Process
+
+### Phase 1: Quality Gate
+
+Run the `/quality-scan` skill with all scan types enabled.
+
+**Gate condition**: zero CRITICAL findings. If any CRITICAL findings exist, abort the release and report them.
+
+Read the HANDOFF block from quality-scan to check:
+```
+Findings: {critical: N, ...}
+```
+
+If `critical > 0`: stop, report findings, do not proceed.
+
+Update queue: `current_phase: quality-gate`
+
+---
+
+### Phase 2: Security Gate
+
+Run the `/security-scan` skill.
+
+**Gate condition**: grade B or above. If grade is C, D, or F, abort the release and report findings.
+
+Read the HANDOFF block from security-scan to check:
+```
+Grade: {A-F}
+```
+
+If grade is C or worse: stop, report findings, do not proceed.
+
+Update queue: `current_phase: security-gate`
+
+---
+
+### Phase 3: Changelog
+
+Generate changelog entry following CLAUDE.md § "Changelog Management":
+
+1. Read current `CHANGELOG.md` to get the last released version
+2. Run `git log --oneline <last-tag>..HEAD` to see commits since last release
+3. Categorize: Added / Changed / Fixed / Removed
+4. Skip chore/ci/deps commits unless they affect user-facing behavior
+5. Write new entry at top of CHANGELOG.md
+6. Present for review before committing
+
+Update queue: `current_phase: changelog`
+
+---
+
+### Phase 4: Version Bump
+
+Determine version bump from commit types:
+- `feat` commits → minor bump
+- `fix` commits only → patch bump
+- Breaking changes (noted in commits) → major bump
+
+Update `version` in `package.json`.
+
+Present the version change for approval. Commit changelog + version bump together:
+```
+chore(release): X.Y.Z
+```
+
+Update queue: `status: done`
+
+---
+
+### Post-Release (Manual)
+
+After the release commit is merged:
+1. Tag: `git tag vX.Y.Z && git push origin vX.Y.Z`
+2. The provenance workflow handles npm publishing
diff --git a/.claude/skills/security-scan/SKILL.md b/.claude/skills/security-scan/SKILL.md
new file mode 100644
index 00000000..0ba403fe
--- /dev/null
+++ b/.claude/skills/security-scan/SKILL.md
@@ -0,0 +1,82 @@
+---
+name: security-scan
+description: Run a multi-tool security scan — AgentShield for Claude config, zizmor for GitHub Actions, and optionally Socket CLI for dependency scanning. Produces an A-F graded security report.
+---
+
+# Security Scan
+
+Multi-tool security scanning pipeline for the repository.
+
+## When to Use
+
+- After modifying `.claude/` config, settings, hooks, or agent definitions
+- After modifying GitHub Actions workflows
+- Before releases (called as a gate by the release pipeline)
+- Periodic security hygiene checks
+
+## Prerequisites
+
+See `_shared/security-tools.md` for tool detection and installation.
+
+## Process
+
+### Phase 1: Environment Check
+
+Follow `_shared/env-check.md`. Initialize a queue run entry for `security-scan`.
+
+---
+
+### Phase 2: AgentShield Scan
+
+Scan Claude Code configuration for security issues:
+
+```bash
+pnpm exec agentshield scan
+```
+
+Checks `.claude/` for:
+- Hardcoded secrets in CLAUDE.md and settings
+- Overly permissive tool allow lists (e.g. `Bash(*)`)
+- Prompt injection patterns in agent definitions
+- Command injection risks in hooks
+- Risky MCP server configurations
+
+Capture the grade and findings count.
+
+Update queue: `current_phase: agentshield` → `completed_phases: [env-check, agentshield]`
+
+---
+
+### Phase 3: Zizmor Scan
+
+Scan GitHub Actions workflows for security issues.
+
+See `_shared/security-tools.md` for zizmor detection. If not installed, skip with a warning.
+
+```bash
+zizmor .github/
+```
+
+Checks for:
+- Unpinned actions (must use full SHA, not tags)
+- Secrets used outside `env:` blocks
+- Injection risks from untrusted inputs (template injection)
+- Overly permissive permissions
+
+Capture findings. Update queue phase.
+
+---
+
+### Phase 4: Grade + Report
+
+Spawn the `security-reviewer` agent (see `agents/security-reviewer.md`) with the combined output from AgentShield and zizmor.
+
+The agent:
+1. Applies CLAUDE.md security rules to evaluate the findings
+2. Calculates an A-F grade per `_shared/report-format.md`
+3. Generates a prioritized report (CRITICAL first)
+4. Suggests fixes for HIGH and CRITICAL findings
+
+Output a HANDOFF block per `_shared/report-format.md` for pipeline chaining.
+
+Update queue: `status: done`, write `findings_count` and final grade.
diff --git a/.gitignore b/.gitignore
index 055220d5..3f298222 100644
--- a/.gitignore
+++ b/.gitignore
@@ -21,6 +21,7 @@ WIP
 /.claude/*
 !/.claude/agents/
 !/.claude/commands/
+!/.claude/ops/
 !/.claude/skills/
 
 # Environment files

From 466c1de5b0d6ebeaf7b5a16fd5937bda6541f24c Mon Sep 17 00:00:00 2001
From: jdalton <john.david.dalton@gmail.com>
Date: Mon, 6 Apr 2026 02:07:05 -0400
Subject: [PATCH 05/10] refactor: integrate existing skills with skill graph

- quality-scan: reference _shared/env-check, _shared/security-tools,
  wire code-reviewer + security-reviewer agents into scan phase,
  replace <promise> with HANDOFF block, add queue tracking, fix
  constraints (not read-only), fix tool references
- updating: reference _shared/env-check + _shared/verify-build,
  add HANDOFF output, add queue tracking
- ci-cascade: reference _shared/env-check, add queue tracking,
  add HANDOFF output
- queue.yaml: fix phase_order to match actual skill phases
---
 .claude/ops/queue.yaml               |   6 +-
 .claude/skills/ci-cascade/SKILL.md   |  25 +++++
 .claude/skills/quality-scan/SKILL.md | 135 +++++++++------------------
 .claude/skills/updating/SKILL.md     |  57 +++++------
 4 files changed, 96 insertions(+), 127 deletions(-)

diff --git a/.claude/ops/queue.yaml b/.claude/ops/queue.yaml
index 7264d957..0f3b9eb5 100644
--- a/.claude/ops/queue.yaml
+++ b/.claude/ops/queue.yaml
@@ -1,10 +1,10 @@
 schema_version: 1
 
 phase_order:
-  quality-scan: [env-check, dep-update, cleanup, structural, scans, report]
+  quality-scan: [env-check, dep-update, tools-install, cleanup, structural, scan-scope, scans, aggregate, report, complete]
   security-scan: [env-check, agentshield, zizmor, grade-report]
-  updating: [env-check, npm-update, validate]
-  ci-cascade: [identify, layer-prs, propagate, verify]
+  updating: [env-check, npm-update, validate, report]
+  ci-cascade: [identify, layer-prs, layer-4-update, propagate, verify]
   release: [quality-gate, security-gate, changelog, version-bump]
 
 runs: []
diff --git a/.claude/skills/ci-cascade/SKILL.md b/.claude/skills/ci-cascade/SKILL.md
index efea0724..b2cecb25 100644
--- a/.claude/skills/ci-cascade/SKILL.md
+++ b/.claude/skills/ci-cascade/SKILL.md
@@ -15,10 +15,14 @@ Implements the cascade procedure defined in CLAUDE.md § "GitHub Actions SHA Pin
 
 ## Procedure
 
+Follow `_shared/env-check.md` to initialize a queue run entry for `ci-cascade`.
+
 Follow the layer order exactly. Each layer gets its own PR. Never combine layers.
 
 ### Phase 1: Identify what changed
 
+Update queue: advance `current_phase` in `.claude/ops/queue.yaml`
+
 Determine which layer was modified:
 - Layer 1 (leaf actions): checkout, install, debug, setup-git-signing, cleanup-git-signing, run-script, artifacts, cache-npm-packages
 - Layer 2a (setup): references debug
@@ -28,6 +32,8 @@ Determine which layer was modified:
 
 ### Phase 2: Create PRs in order
 
+Update queue: advance `current_phase` in `.claude/ops/queue.yaml`
+
 Starting from the layer above the change, create a PR for each layer:
 
 1. **Get current SHA**: `git fetch origin main && git rev-parse origin/main`
@@ -41,12 +47,16 @@ Starting from the layer above the change, create a PR for each layer:
 
 ### Phase 3: Update Layer 4 (local wrappers)
 
+Update queue: advance `current_phase` in `.claude/ops/queue.yaml`
+
 After Layer 3 merges, get the **propagation SHA** (Layer 3 merge SHA). Update the `_local-not-for-reuse-*` workflows to pin to this SHA. Create a PR, merge it.
 
 The Layer 4 merge SHA is NOT used for external pinning — external repos pin to the Layer 3 SHA because that's where the reusable workflows (ci.yml, provenance.yml) were updated.
 
 ### Phase 4: Propagate to external repos
 
+Update queue: advance `current_phase` in `.claude/ops/queue.yaml`
+
 All external repos pin to the **propagation SHA** (Layer 3 merge SHA).
 
 For each repo:
@@ -56,7 +66,22 @@ For each repo:
 
 ### Phase 5: Verify
 
+Update queue: advance `current_phase` in `.claude/ops/queue.yaml`
+
 For each updated repo, confirm no old SHAs remain:
 ```bash
 grep -rn "SocketDev/socket-registry" .github/ | grep "@" | grep -v "<propagation-sha>"
 ```
+
+### Completion
+
+Output a HANDOFF block per `_shared/report-format.md`:
+
+```
+=== HANDOFF: ci-cascade ===
+Status: {pass|fail}
+Summary: {one-line: "Propagated SHA XXXXX to N repos"}
+=== END HANDOFF ===
+```
+
+Update queue: `status: done`, write completion timestamp.
diff --git a/.claude/skills/quality-scan/SKILL.md b/.claude/skills/quality-scan/SKILL.md
index 6e8866fc..4340122b 100644
--- a/.claude/skills/quality-scan/SKILL.md
+++ b/.claude/skills/quality-scan/SKILL.md
@@ -36,7 +36,7 @@ All agent prompts are embedded in `reference.md` with structured <context>, <ins
 
 <constraints>
 **CRITICAL Requirements:**
-- Read-only analysis (no code changes during scan)
+- Analysis phase (dependency updates and cleanup happen in early phases, code scanning is read-only)
 - Must complete all enabled scans before reporting
 - Findings must be prioritized by severity (Critical → High → Medium → Low)
 - Must generate actionable tasks with file:line references
@@ -64,30 +64,16 @@ Execute the following phases sequentially to perform comprehensive quality analy
 
 ### Phase 1: Validate Environment
 
-<prerequisites>
-Verify the environment before starting scans:
-</prerequisites>
+Update queue: advance `current_phase` in `.claude/ops/queue.yaml`
 
-```bash
-git status
-```
-
-<validation>
-**Expected State:**
-- Working directory should be clean (warn if dirty but continue)
-- On a valid branch
-- Node modules installed
-
-**If working directory dirty:**
-- Warn user: "Working directory has uncommitted changes - continuing with scan"
-- Continue with scans (quality scanning is read-only)
-
-</validation>
+Follow `_shared/env-check.md` to validate the environment and initialize a queue run entry for `quality-scan`.
 
 ---
 
 ### Phase 2: Update Dependencies
 
+Update queue: advance `current_phase` in `.claude/ops/queue.yaml`
+
 <action>
 Update dependencies in the current repository only:
 </action>
@@ -114,61 +100,16 @@ pnpm run update
 
 ### Phase 2b: Install External Tools (zizmor)
 
-<action>
-Install zizmor for GitHub Actions security scanning using version that meets repository's minimumReleaseAge policy.
-</action>
+Update queue: advance `current_phase` in `.claude/ops/queue.yaml`
 
-<version_selection>
-Determine the appropriate zizmor version dynamically:
-
-1. **Read minimumReleaseAge from `.pnpmrc`**:
-   ```bash
-   grep 'minimumReleaseAge' .pnpmrc | cut -d'=' -f2
-   ```
-   This returns minutes (e.g., `10080` = 7 days). Default to 10080 if not found.
-
-2. **Query zizmor releases** (using curl or gh):
-   ```bash
-   # Option A: curl (universally available)
-   curl -s "https://api.github.com/repos/zizmorcore/zizmor/releases" | \
-     jq '[.[] | select(.prerelease == false) | {tag: .tag_name, date: .published_at}] | .[0:10]'
-
-   # Option B: gh (if available)
-   gh api repos/zizmorcore/zizmor/releases --jq \
-     '[.[] | select(.prerelease == false) | {tag: .tag_name, date: .published_at}] | .[0:10]'
-   ```
-
-3. **Calculate age and select version**:
-   - Convert minimumReleaseAge from minutes to days: `minutes / 1440`
-   - Find latest stable release older than that threshold
-   - Example: If minimumReleaseAge=10080 (7 days) and today is March 24, select releases from March 17 or earlier
-
-4. **Install selected version** (choose based on available tools):
-   ```bash
-   # macOS with Homebrew (latest only, version pinning limited)
-   brew install zizmor
-
-   # Python environments (version pinning supported)
-   pipx install zizmor==VERSION
-   uv tool install zizmor==VERSION
-   uvx zizmor@VERSION --help
-   ```
-
-   **Recommended priority**: pipx/uvx > brew
-</version_selection>
-
-<rationale>
-Using minimumReleaseAge prevents supply chain attacks from compromised new releases. The 7-day window allows community detection of malicious packages before adoption.
-</rationale>
-
-<fallback>
-If no release meets the age requirement, warn the user and skip zizmor scan. Never install a release younger than minimumReleaseAge.
-</fallback>
+See `_shared/security-tools.md` for zizmor detection. Use `pnpm run setup` to install pinned tools.
 
 ---
 
 ### Phase 3: Repository Cleanup
 
+Update queue: advance `current_phase` in `.claude/ops/queue.yaml`
+
 <action>
 Clean up junk files and organize the repository before scanning:
 </action>
@@ -244,6 +185,8 @@ find . -type f -name '*.log' \
 
 ### Phase 4: Structural Validation
 
+Update queue: advance `current_phase` in `.claude/ops/queue.yaml`
+
 <action>
 Run automated consistency checker to validate architectural patterns:
 </action>
@@ -293,6 +236,8 @@ node scripts/check-consistency.mjs
 
 ### Phase 5: Determine Scan Scope
 
+Update queue: advance `current_phase` in `.claude/ops/queue.yaml`
+
 <action>
 Ask user which scans to run:
 </action>
@@ -307,15 +252,11 @@ Ask user which scans to run:
 7. **documentation** - Documentation accuracy (README errors, outdated docs)
 
 **User Interaction:**
-Use AskUserQuestion tool:
-- Question: "Which quality scans would you like to run?"
-- Header: "Scan Types"
-- multiSelect: true
-- Options:
-  - "All scans (recommended)" → Run all scan types
-  - "Critical only" → Run critical scan only
-  - "Critical + Logic" → Run critical and logic scans
-  - "Custom selection" → Ask user to specify which scans
+Ask the user which scans to run:
+- "All scans (recommended)" - Run all scan types
+- "Critical only" - Run critical scan only
+- "Critical + Logic" - Run critical and logic scans
+- "Custom selection" - Ask user to specify which scans
 
 **Default:** If user doesn't specify, run all scans.
 
@@ -335,16 +276,16 @@ If user requests non-existent scan type, report error and suggest valid types.
 
 ### Phase 6: Execute Scans
 
+Update queue: advance `current_phase` in `.claude/ops/queue.yaml`
+
 <action>
 For each enabled scan type, spawn a specialized agent using Agent tool:
 </action>
 
-```typescript
-// Example: Critical scan
-Task({
-  subagent_type: "general-purpose",
-  description: "Critical bugs scan",
-  prompt: `${CRITICAL_SCAN_PROMPT_FROM_REFERENCE_MD}
+```
+Example: Critical scan via Agent tool
+
+Prompt the agent with the CRITICAL_SCAN_PROMPT from reference.md, adding:
 
 [IF monorepo] Focus on packages/ directories and root-level scripts/.
 [IF single package] Focus on src/, lib/, and scripts/ directories.
@@ -358,8 +299,7 @@ Report findings in this format:
 - Fix: Suggested fix
 - Impact: What happens if triggered
 
-Scan systematically and report all findings. If no issues found, state that explicitly.`
-})
+Scan systematically and report all findings. If no issues found, state that explicitly.
 ```
 
 **For each scan:**
@@ -375,6 +315,10 @@ Scan systematically and report all findings. If no issues found, state that expl
 - cache
 - workflow (lowest priority)
 
+**Agent Rules:**
+- For critical, logic, and cache scans: the agent should apply the rules from `agents/code-reviewer.md` (code style, patterns, error handling) in addition to the scan-type-specific prompt from reference.md.
+- For the security scan type: the agent should apply the rules from `agents/security-reviewer.md` (safe file ops, secret detection, dependency rules).
+
 **Agent Prompt Sources:**
 - Critical scan: reference.md starting at line ~12
 - Logic scan: reference.md starting at line ~100
@@ -396,6 +340,8 @@ For each scan completion:
 
 ### Phase 7: Aggregate Findings
 
+Update queue: advance `current_phase` in `.claude/ops/queue.yaml`
+
 <action>
 Collect all findings from agents and aggregate:
 </action>
@@ -435,6 +381,8 @@ interface Finding {
 
 ### Phase 8: Generate Report
 
+Update queue: advance `current_phase` in `.claude/ops/queue.yaml`
+
 <action>
 Create structured quality report with all findings:
 </action>
@@ -533,9 +481,18 @@ Create structured quality report with all findings:
 
 ### Phase 9: Complete
 
+Update queue: advance `current_phase` in `.claude/ops/queue.yaml`
+
 <completion_signal>
-```xml
-<promise>QUALITY_SCAN_COMPLETE</promise>
+Output a HANDOFF block per `_shared/report-format.md`:
+
+```
+=== HANDOFF: quality-scan ===
+Status: {pass|fail}
+Grade: {A-F}
+Findings: {critical: N, high: N, medium: N, low: N}
+Summary: {one-line description}
+=== END HANDOFF ===
 ```
 </completion_signal>
 
@@ -587,7 +544,7 @@ All findings include file:line references and suggested fixes.
 
 ## Success Criteria
 
-- ✅ `<promise>QUALITY_SCAN_COMPLETE</promise>` output
+- ✅ HANDOFF block output per `_shared/report-format.md`
 - ✅ All enabled scans completed without errors
 - ✅ Findings prioritized by severity (Critical → Low)
 - ✅ All findings include file:line references
@@ -611,7 +568,7 @@ All agent prompts follow Claude best practices with <context>, <instructions>, <
 
 ## Commands
 
-This skill is self-contained. No external commands needed.
+Requires: `git`, `pnpm`, `node`, and optionally `zizmor` (see `_shared/security-tools.md`).
 
 ## Context
 
diff --git a/.claude/skills/updating/SKILL.md b/.claude/skills/updating/SKILL.md
index f97d5548..aed6bba4 100644
--- a/.claude/skills/updating/SKILL.md
+++ b/.claude/skills/updating/SKILL.md
@@ -43,33 +43,16 @@ This skill updates npm packages for security patches, bug fixes, and new feature
 
 ### Phase 1: Validate Environment
 
-<action>
-Check working directory is clean and detect CI mode:
-</action>
+Update queue: advance `current_phase` in `.claude/ops/queue.yaml`
 
-```bash
-# Detect CI mode
-if [ "$CI" = "true" ] || [ -n "$GITHUB_ACTIONS" ]; then
-  CI_MODE=true
-  echo "Running in CI mode - will skip build validation"
-else
-  CI_MODE=false
-  echo "Running in interactive mode - will validate builds"
-fi
-
-# Check working directory is clean
-git status --porcelain
-```
-
-<validation>
-- Working directory must be clean
-- CI_MODE detected for subsequent phases
-</validation>
+Follow `_shared/env-check.md` to validate the environment and initialize a queue run entry for `updating`.
 
 ---
 
 ### Phase 2: Update npm Packages
 
+Update queue: advance `current_phase` in `.claude/ops/queue.yaml`
+
 <action>
 Run pnpm run update to update npm dependencies:
 </action>
@@ -94,26 +77,16 @@ fi
 
 ### Phase 3: Final Validation
 
-<action>
-Run build and test suite (skip in CI mode):
-</action>
+Update queue: advance `current_phase` in `.claude/ops/queue.yaml`
 
-```bash
-if [ "$CI_MODE" = "true" ]; then
-  echo "CI mode: Skipping final validation (CI will run builds/tests separately)"
-  echo "Commits created - ready for push by CI workflow"
-else
-  echo "Interactive mode: Running full validation..."
-  pnpm run fix --all
-  pnpm run check --all
-  pnpm test
-fi
-```
+Follow `_shared/verify-build.md` for build validation.
 
 ---
 
 ### Phase 4: Report Summary
 
+Update queue: advance `current_phase` in `.claude/ops/queue.yaml`
+
 <action>
 Generate update report:
 </action>
@@ -145,6 +118,20 @@ Generate update report:
 3. Review PR when CI passes
 ```
 
+### Completion
+
+Output a HANDOFF block per `_shared/report-format.md`:
+
+```
+=== HANDOFF: updating ===
+Status: {pass|fail}
+Findings: {packages_updated: N}
+Summary: {one-line description of what was updated}
+=== END HANDOFF ===
+```
+
+Update queue: `status: done`, write completion timestamp.
+
 </instructions>
 
 ## Success Criteria

From 6a8a1ce94f78f1594827d6b315930ca066299d76 Mon Sep 17 00:00:00 2001
From: jdalton <john.david.dalton@gmail.com>
Date: Mon, 6 Apr 2026 11:24:32 -0400
Subject: [PATCH 06/10] fix: address remaining audit findings

- quality-scan: add CI/gate mode to skip interactive prompts in
  Phases 3 (cleanup), 5 (scan scope), and 8 (save report)
- quality-scan: remove hardcoded AskUserQuestion tool name
- quality-loop: document as interactive-only (not for pipeline gates)
---
 .claude/commands/quality-loop.md     |  2 ++
 .claude/skills/quality-scan/SKILL.md | 31 ++++++++++++++--------------
 2 files changed, 17 insertions(+), 16 deletions(-)

diff --git a/.claude/commands/quality-loop.md b/.claude/commands/quality-loop.md
index 3d0da6b4..ddd59375 100644
--- a/.claude/commands/quality-loop.md
+++ b/.claude/commands/quality-loop.md
@@ -1,5 +1,7 @@
 Run the `/quality-scan` skill and fix all issues found. Repeat until zero issues remain or 5 iterations complete.
 
+**Interactive only** — this command makes code changes and commits. Do not use as an automated pipeline gate.
+
 ## Process
 
 1. Run `/quality-scan` skill (all scan types)
diff --git a/.claude/skills/quality-scan/SKILL.md b/.claude/skills/quality-scan/SKILL.md
index 4340122b..f0538cc1 100644
--- a/.claude/skills/quality-scan/SKILL.md
+++ b/.claude/skills/quality-scan/SKILL.md
@@ -167,16 +167,13 @@ find . -type f -name '*.log' \
 **For each file found:**
 1. Show the file path to user
 2. Explain why it's considered junk
-3. Ask user for confirmation before deleting (use AskUserQuestion)
-4. Delete confirmed files: `git rm` if tracked, `rm` if untracked
-5. Report files removed
+3. In interactive mode: ask user for confirmation before deleting
+4. In CI mode or when called as a pipeline gate: auto-delete without prompting
+5. Delete confirmed files: `git rm` if tracked, `rm` if untracked
+6. Report files removed
 
 **If no junk files found:**
 - Report: "✓ Repository is clean - no junk files found"
-
-**Important:**
-- Always get user confirmation before deleting
-- Show file contents if user is unsure
 - Track deleted files for reporting
 
 </validation>
@@ -251,14 +248,15 @@ Ask user which scans to run:
 6. **security** - GitHub Actions security (template injection, cache poisoning, etc.)
 7. **documentation** - Documentation accuracy (README errors, outdated docs)
 
-**User Interaction:**
-Ask the user which scans to run:
-- "All scans (recommended)" - Run all scan types
-- "Critical only" - Run critical scan only
-- "Critical + Logic" - Run critical and logic scans
-- "Custom selection" - Ask user to specify which scans
+**Scan Selection:**
+- In CI mode or when called as a pipeline gate (e.g. by `/release`): run all scans automatically, no prompting
+- In interactive mode: ask the user which scans to run:
+  - "All scans (recommended)" — run all scan types
+  - "Critical only" — run critical scan only
+  - "Critical + Logic" — run critical and logic scans
+  - "Custom selection" — ask user to specify
 
-**Default:** If user doesn't specify, run all scans.
+**Default:** If not specified, run all scans.
 
 <validation>
 Validate selected scan types exist in reference.md:
@@ -465,8 +463,9 @@ Create structured quality report with all findings:
 ```
 
 **Output Report:**
-1. Display report to console (user sees it)
-2. Offer to save to file (optional): `reports/quality-scan-YYYY-MM-DD.md`
+1. Display report to console
+2. In interactive mode: offer to save to file (`reports/quality-scan-YYYY-MM-DD.md`)
+3. In CI mode or pipeline gate mode: skip save prompt
 
 <validation>
 **Report Quality Checks:**

From 75cf70c1fb8beee447037b6c913e17ed54be6b0a Mon Sep 17 00:00:00 2001
From: jdalton <john.david.dalton@gmail.com>
Date: Mon, 6 Apr 2026 11:51:47 -0400
Subject: [PATCH 07/10] fix: address final review operability issues

- quality-scan: replace missing check-consistency.mjs with pnpm run check
- quality-scan: replace fragile line-number refs with section name refs
- quality-scan/reference.md: replace stale zizmor v1.22.0 install block
  with reference to _shared/security-tools.md + external-tools.json
- security-tools.md: add zizmor PATH detection via .cache/ fallback
- release: handle missing CHANGELOG.md and missing tags gracefully
---
 .claude/skills/_shared/security-tools.md | 13 +++++++++-
 .claude/skills/quality-scan/SKILL.md     | 31 ++++++++++++------------
 .claude/skills/quality-scan/reference.md | 23 +-----------------
 .claude/skills/release/SKILL.md          |  4 +--
 4 files changed, 31 insertions(+), 40 deletions(-)

diff --git a/.claude/skills/_shared/security-tools.md b/.claude/skills/_shared/security-tools.md
index 8ab87d0c..9a1f0271 100644
--- a/.claude/skills/_shared/security-tools.md
+++ b/.claude/skills/_shared/security-tools.md
@@ -13,7 +13,18 @@ No install step needed — available after `pnpm install`.
 Not an npm package. Installed via `pnpm run setup` which downloads the pinned version
 from GitHub releases with SHA256 checksum verification (see `external-tools.json`).
 
-Detection: `command -v zizmor` or check `.cache/external-tools/zizmor/*/zizmor`
+The binary is cached at `.cache/external-tools/zizmor/{version}-{platform}/zizmor`.
+
+Detection order:
+1. `command -v zizmor` (if already on PATH, e.g. via brew)
+2. `.cache/external-tools/zizmor/*/zizmor` (from `pnpm run setup`)
+
+Run via the full path if not on PATH:
+```bash
+ZIZMOR="$(find .cache/external-tools/zizmor -name zizmor -type f 2>/dev/null | head -1)"
+if [ -z "$ZIZMOR" ]; then ZIZMOR="$(command -v zizmor 2>/dev/null)"; fi
+if [ -n "$ZIZMOR" ]; then "$ZIZMOR" .github/; else echo "zizmor not installed — run pnpm run setup"; fi
+```
 
 If not available:
 - Warn: "zizmor not installed — run `pnpm run setup` to install"
diff --git a/.claude/skills/quality-scan/SKILL.md b/.claude/skills/quality-scan/SKILL.md
index f0538cc1..6381af40 100644
--- a/.claude/skills/quality-scan/SKILL.md
+++ b/.claude/skills/quality-scan/SKILL.md
@@ -190,10 +190,10 @@ Run automated consistency checker to validate architectural patterns:
 
 **Validation Tasks:**
 
-Run the consistency checker to validate monorepo structure:
+Run the check script to validate monorepo structure:
 
 ```bash
-node scripts/check-consistency.mjs
+pnpm run check --all
 ```
 
 **The consistency checker validates:**
@@ -260,12 +260,13 @@ Ask user which scans to run:
 
 <validation>
 Validate selected scan types exist in reference.md:
-- critical-scan → reference.md line ~5
-- logic-scan → reference.md line ~100
-- cache-scan → reference.md line ~200
-- workflow-scan → reference.md line ~300
-- security-scan → reference.md line ~400
-- documentation-scan → reference.md line ~810
+- critical-scan → reference.md § "Critical Scan Agent"
+- logic-scan → reference.md § "Logic Scan Agent"
+- cache-scan → reference.md § "Cache Scan Agent"
+- workflow-scan → reference.md § "Workflow Scan Agent"
+- security-scan → reference.md § "Security Scan Agent"
+- workflow-optimization-scan → reference.md § "Workflow Optimization Scan Agent"
+- documentation-scan → reference.md § "Documentation Scan Agent"
 
 If user requests non-existent scan type, report error and suggest valid types.
 </validation>
@@ -318,13 +319,13 @@ Scan systematically and report all findings. If no issues found, state that expl
 - For the security scan type: the agent should apply the rules from `agents/security-reviewer.md` (safe file ops, secret detection, dependency rules).
 
 **Agent Prompt Sources:**
-- Critical scan: reference.md starting at line ~12
-- Logic scan: reference.md starting at line ~100
-- Cache scan: reference.md starting at line ~200
-- Workflow scan: reference.md starting at line ~300
-- Security scan: reference.md starting at line ~400
-- Workflow-optimization scan: reference.md starting at line ~860
-- Documentation scan: reference.md starting at line ~1040
+- Critical scan: reference.md § "Critical Scan Agent"
+- Logic scan: reference.md § "Logic Scan Agent"
+- Cache scan: reference.md § "Cache Scan Agent"
+- Workflow scan: reference.md § "Workflow Scan Agent"
+- Security scan: reference.md § "Security Scan Agent"
+- Workflow-optimization scan: reference.md § "Workflow Optimization Scan Agent"
+- Documentation scan: reference.md § "Documentation Scan Agent"
 
 <validation>
 For each scan completion:
diff --git a/.claude/skills/quality-scan/reference.md b/.claude/skills/quality-scan/reference.md
index 8f91a0a2..9a228514 100644
--- a/.claude/skills/quality-scan/reference.md
+++ b/.claude/skills/quality-scan/reference.md
@@ -924,28 +924,7 @@ Zizmor is a GitHub Actions workflow security scanner that detects:
 This repository uses GitHub Actions for CI/CD with workflows in `.github/workflows/`.
 
 **Installation:**
-Zizmor is not available via npm. Install zizmor v1.22.0 using one of these methods:
-
-**GitHub Releases (Recommended):**
-```bash
-# Download from https://github.com/zizmorcore/zizmor/releases/tag/v1.22.0
-# macOS ARM64:
-curl -L https://github.com/zizmorcore/zizmor/releases/download/v1.22.0/zizmor-aarch64-apple-darwin -o /usr/local/bin/zizmor
-chmod +x /usr/local/bin/zizmor
-
-# macOS x64:
-curl -L https://github.com/zizmorcore/zizmor/releases/download/v1.22.0/zizmor-x86_64-apple-darwin -o /usr/local/bin/zizmor
-chmod +x /usr/local/bin/zizmor
-
-# Linux x64:
-curl -L https://github.com/zizmorcore/zizmor/releases/download/v1.22.0/zizmor-x86_64-unknown-linux-musl -o /usr/local/bin/zizmor
-chmod +x /usr/local/bin/zizmor
-```
-
-**Alternative Methods:**
-- Homebrew: `brew install zizmor@1.22.0`
-- Cargo: `cargo install zizmor --version 1.22.0`
-- See https://docs.zizmor.sh/installation/ for all options
+Zizmor is not an npm package. See `_shared/security-tools.md` for detection and `external-tools.json` for the pinned version. Install via `pnpm run setup`.
 </context>
 
 <instructions>
diff --git a/.claude/skills/release/SKILL.md b/.claude/skills/release/SKILL.md
index 83ccf1c2..119b2042 100644
--- a/.claude/skills/release/SKILL.md
+++ b/.claude/skills/release/SKILL.md
@@ -52,8 +52,8 @@ Update queue: `current_phase: security-gate`
 
 Generate changelog entry following CLAUDE.md § "Changelog Management":
 
-1. Read current `CHANGELOG.md` to get the last released version
-2. Run `git log --oneline <last-tag>..HEAD` to see commits since last release
+1. Read current `CHANGELOG.md` to get the last released version (if it doesn't exist, create it with the Keep a Changelog header)
+2. If no tags exist, use all commits on main; otherwise run `git log --oneline <last-tag>..HEAD`
 3. Categorize: Added / Changed / Fixed / Removed
 4. Skip chore/ci/deps commits unless they affect user-facing behavior
 5. Write new entry at top of CHANGELOG.md

From ddc29952012c160ef5266ab0e0ae4ee3e288325d Mon Sep 17 00:00:00 2001
From: jdalton <john.david.dalton@gmail.com>
Date: Mon, 6 Apr 2026 14:36:53 -0400
Subject: [PATCH 08/10] fix: remove socket-btm content, fix staging, add queue
 cleanup

- reference.md: remove all socket-btm-specific patterns (binject, binpress,
  binsuite, PE resources, LIEF, C/C++ examples, primordials). Rewrite
  Workflow and Workflow-Optimization scan agents for socket-registry.
  File reduced from 1597 to 1300 lines.
- updating: stage all files that pnpm run update changes (pnpm-workspace.yaml,
  packages/npm/*/package.json) not just package.json + lockfile
- queue.yaml: add retention guidance (keep last 10 runs)
---
 .claude/ops/queue.yaml                   |   2 +
 .claude/skills/quality-scan/reference.md | 513 +++++------------------
 .claude/skills/updating/SKILL.md         |   4 +-
 3 files changed, 112 insertions(+), 407 deletions(-)

diff --git a/.claude/ops/queue.yaml b/.claude/ops/queue.yaml
index 0f3b9eb5..df32751e 100644
--- a/.claude/ops/queue.yaml
+++ b/.claude/ops/queue.yaml
@@ -7,4 +7,6 @@ phase_order:
   ci-cascade: [identify, layer-prs, layer-4-update, propagate, verify]
   release: [quality-gate, security-gate, changelog, version-bump]
 
+# Completed runs are appended here by skills. Prune periodically —
+# keep the last 10 entries and delete older ones to avoid unbounded growth.
 runs: []
diff --git a/.claude/skills/quality-scan/reference.md b/.claude/skills/quality-scan/reference.md
index 9a228514..d80de687 100644
--- a/.claude/skills/quality-scan/reference.md
+++ b/.claude/skills/quality-scan/reference.md
@@ -17,13 +17,13 @@ Examples:
 
 **BAD - Ignoring return values and reconstructing paths:**
 ```javascript
-await downloadSocketBtmRelease({ asset, downloadDir, tool: 'lief' })
-const downloadedPath = path.join(downloadDir, 'lief', 'assets', asset)  // ❌ Assumes path structure
+await downloadAsset({ asset, downloadDir, tool: 'package' })
+const downloadedPath = path.join(downloadDir, 'package', 'assets', asset)  // ❌ Assumes path structure
 ```
 
 **GOOD - Use the return value:**
 ```javascript
-const downloadedPath = await downloadSocketBtmRelease({ asset, downloadDir })  // ✅ Simple, trust the function
+const downloadedPath = await downloadAsset({ asset, downloadDir })  // ✅ Simple, trust the function
 ```
 
 **Principle**: If a function returns what you need, use it. Don't reconstruct or assume.
@@ -57,7 +57,6 @@ Common characteristics to look for:
 Scan all code files for these critical bug patterns:
 - [IF monorepo] TypeScript/JavaScript: packages/npm/*/scripts/**/*.{mjs,mts}, registry/lib/**/*.js, scripts/**/*.{mjs,mts}
 - [IF single package] TypeScript/JavaScript: src/**/*.{ts,mts,mjs,js}, lib/**/*.{ts,mts,mjs,js}
-- [IF C/C++ code exists] C/C++: src/**/*.{c,cc,cpp,h}
 - Focus on:
 
 <pattern name="null_undefined_access">
@@ -101,92 +100,6 @@ Scan all code files for these critical bug patterns:
 - Buffer operations without size checks
 </pattern>
 
-<pattern name="primordials_protection">
-**CRITICAL for Node.js internal code (IF repository has Node.js internals):**
-- Direct Promise method calls (Promise.all, Promise.allSettled, Promise.race, Promise.any) instead of primordials
-- Missing primordials import in internal/ modules
-- Using Promise.all where Promise.allSettled would be safer for error collection
-- [SOCKET-BTM SPECIFIC] Check additions/source-patched/lib/internal/socketsecurity/smol/*.js for SafePromiseAllSettled usage
-- [SOCKET-BTM SPECIFIC] Check additions/source-patched/deps/fast-webstreams/*.js for SafePromiseAllReturnVoid usage
-- [SOCKET-BTM SPECIFIC] Verify sync scripts (vendor-fast-webstreams/sync.mjs) inject primordials when syncing from upstream
-</pattern>
-
-<pattern name="cross_platform_binary_bugs">
-**[SOCKET-BTM SPECIFIC] CRITICAL for binary tooling (binject, binpress, stubs-builder):**
-Cross-platform binary processing that uses compile-time platform detection:
-- `#ifdef __APPLE__` / `#ifdef _WIN32` selecting sizes, offsets, or behaviors for binary operations
-- Host platform detection instead of target binary format detection
-- Example buggy pattern (causes "Cannot inject into uncompressed stub" errors):
-  ```c
-  #ifdef __APPLE__
-  size_t search_size = SEARCH_SIZE_MACHO;  // Uses macOS size even for Linux ELF binaries!
-  #else
-  size_t search_size = SEARCH_SIZE_ELF;
-  #endif
-  ```
-- Fix: Use runtime binary format detection based on the executable being processed:
-  ```c
-  binject_format_t format = binject_detect_format(executable);
-  size_t search_size = get_search_size_for_format(format);
-  ```
-- Impact: Cross-platform CI (e.g., macOS building Linux binaries) silently produces broken binaries
-</pattern>
-
-<pattern name="pe_resource_requirements">
-**[SOCKET-BTM SPECIFIC] CRITICAL for Windows binary tooling:**
-Windows PE binaries missing required .rsrc sections for LIEF injection:
-- LIEF cannot create resource sections from scratch - must exist in the binary
-- Symptoms: "Binary has no resources section" error during SEA injection
-- Check Windows Makefiles (Makefile.windows) for:
-  1. Missing .rc resource file compilation with windres
-  2. Missing RESOURCE_OBJ in the final link step
-- Required for any PE binary that will receive NODE_SEA_BLOB or other injected resources
-</pattern>
-
-<pattern name="binsuite_self_compression_in_tests">
-**[SOCKET-BTM SPECIFIC] CRITICAL for test reliability and CI stability:**
-Tests compressing binsuite binaries (binpress, binflate, binject) as test input cause:
-- Flaky/slow tests: These binaries vary between builds, causing inconsistent test behavior
-- CI timeouts: Large binary compression takes excessive time
-- Parallel test interference: Tests using static paths collide in parallel runs
-
-**Bad patterns to flag:**
-```typescript
-// BAD - compressing binsuite tools themselves
-const originalBinary = BINPRESS  // or BINFLATE, BINJECT
-await execCommand(BINPRESS, [BINFLATE, '-o', output])
-
-// BAD - static testDir paths (parallel collision risk)
-const testDir = path.join(PACKAGE_DIR, 'test-tmp')
-```
-
-**Correct patterns:**
-```typescript
-// GOOD - use Node.js binary (consistent across builds)
-const NODE_BINARY = process.execPath
-let testDir: string
-let testBinary: string
-
-beforeAll(async () => {
-  // Unique testDir isolates parallel test runs
-  const uniqueId = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
-  testDir = path.join(os.tmpdir(), `package-test-${uniqueId}`)
-  await safeMkdir(testDir)
-  // Copy Node.js as consistent test input
-  testBinary = path.join(testDir, 'test-node')
-  await fs.copyFile(NODE_BINARY, testBinary)
-})
-```
-
-**Where to check:**
-- packages/npm/*/test/*.test.mts
-- test/**/*.test.js
-- test/**/*.test.mts
-- Any test that uses external package managers or performs heavy I/O operations
-
-**Impact:** Tests performing intensive npm operations can cause CI timeouts
-</pattern>
-
 For each bug found, think through:
 1. Can this actually crash in production?
 2. What input would trigger it?
@@ -213,21 +126,12 @@ Trigger: When operation fails without error handling
 Fix: `await asyncOperation().catch(err => { logger.error(err); throw new Error(\`Operation failed: \${err.message}\`) })`
 Impact: Uncaught exception crashes process
 
-Example (C/C++):
-File: src/path/to/file.c:234
-Issue: Potential null pointer dereference after malloc
-Severity: Critical
-Pattern: `uint8_t* buffer = malloc(size); memcpy(buffer, data, size);`
-Trigger: When malloc fails due to insufficient memory
-Fix: `uint8_t* buffer = malloc(size); if (!buffer) return ERROR_MEMORY; memcpy(buffer, data, size);`
-Impact: Segmentation fault crashes process
 </output_format>
 
 <quality_guidelines>
 - Only report actual bugs, not style issues or minor improvements
 - Verify bugs are not already handled by surrounding code
 - Prioritize bugs affecting reliability and correctness
-- For C/C++: Focus on memory safety, null checks, buffer overflows
 - For TypeScript: Focus on promise handling, type guards, external input validation
 - Skip false positives (TypeScript type guards are sufficient in many cases)
 - [IF monorepo] Scan across all packages systematically
@@ -298,73 +202,6 @@ Algorithm implementation issues:
 - Deduplication: Missing deduplication of duplicate items
 </pattern>
 
-<pattern name="patch_handling">
-**[SOCKET-BTM SPECIFIC] Patch application logic errors:**
-- Unified diff parsing: Line offset calculation errors, context matching failures
-- Hunk application: Off-by-one in line number calculations
-- Patch validation: Missing validation of patch format (malformed hunks)
-- Backup/restore: Not properly handling patch failures mid-application
-- Independent patches: Assumptions about patch ordering or dependencies
-</pattern>
-
-<pattern name="binary_format">
-**[SOCKET-BTM SPECIFIC] Binary format handling errors:**
-- Format detection: Misidentifying ELF/Mach-O/PE headers
-- Section/segment: Off-by-one in offset calculations, size validation missing
-- Endianness: Not handling big-endian vs little-endian correctly
-- Alignment: Missing alignment requirements for injected data
-- Cross-platform: Windows vs Unix path separators, line endings
-</pattern>
-
-<pattern name="compile_time_vs_runtime_platform">
-**[SOCKET-BTM SPECIFIC] Cross-platform binary processing bugs (CRITICAL - causes silent failures):**
-- Using `#ifdef __APPLE__` / `#ifdef _WIN32` to select binary format-specific behavior
-- Code uses host platform instead of target binary format for size/offset calculations
-- Magic marker search using compile-time constants instead of runtime binary format detection
-- Example bug pattern:
-  ```c
-  // BAD - uses compile-time platform, breaks cross-platform builds
-  #ifdef __APPLE__
-  size_t search_size = 64 * 1024;   // Mach-O size
-  #elif defined(_WIN32)
-  size_t search_size = 128 * 1024;  // PE size
-  #else
-  size_t search_size = 1408 * 1024; // ELF size
-  #endif
-
-  // GOOD - runtime detection based on binary being processed
-  binject_format_t format = binject_detect_format(executable);
-  size_t search_size = get_search_size_for_format(format);
-  ```
-- Symptoms: "Cannot inject into uncompressed stub binary" when building Linux binaries on macOS
-- Critical for: binject, binpress, stubs-builder, any code manipulating binaries cross-platform
-- Real-world impact: macOS CI processing Linux ELF binaries uses wrong search size, fails to find markers
-</pattern>
-
-<pattern name="missing_pe_resources">
-**[SOCKET-BTM SPECIFIC] Windows PE binaries missing required resource sections:**
-- PE stub binaries without .rsrc section cannot receive LIEF-injected resources
-- LIEF cannot create resource sections from scratch - binary must have existing resources
-- Symptoms: "Binary has no resources section" error during Windows SEA injection
-- Check Windows Makefiles for:
-  1. Missing .rc resource file (stub.rc or similar)
-  2. Missing windres compilation step: `$(WINDRES) -i $(RESOURCE_RC) -o $@`
-  3. Missing resource object in link step: `$(CC) ... $(RESOURCE_OBJ) ...`
-- Required for binaries that need NODE_SEA_BLOB or other injected resources
-- Example fix for Makefile.windows:
-  ```makefile
-  RESOURCE_RC = src/socketsecurity/stubs-builder/stub.rc
-  RESOURCE_OBJ = $(OUT_DIR)/stub.res.o
-  WINDRES ?= windres
-
-  $(RESOURCE_OBJ): $(RESOURCE_RC) | $(OUT_DIR)
-      $(WINDRES) -i $(RESOURCE_RC) -o $@
-
-  $(OUT_DIR)/$(TARGET): $(SOURCE) $(RESOURCE_OBJ) ...
-      $(CC) ... $(SOURCE) $(RESOURCE_OBJ) ...
-  ```
-</pattern>
-
 Before reporting, think through:
 1. Does this logic error produce incorrect output?
 2. What specific input would trigger it?
@@ -391,14 +228,6 @@ Pattern: `for (let i = 0; i < items.length - 1; i++)`
 Fix: `for (let i = 0; i < items.length; i++)`
 Impact: Last item is silently omitted, causing incorrect processing
 
-Example (C code):
-File: src/path/to/file.c:234
-Issue: Incorrect size calculation with alignment
-Severity: High
-Edge Case: When data requires alignment
-Pattern: `new_size = existing_size + data_size;`
-Fix: `new_size = ALIGN_UP(existing_size + data_size, alignment);`
-Impact: Misaligned data causes segfault
 </output_format>
 
 <quality_guidelines>
@@ -406,7 +235,6 @@ Impact: Misaligned data causes segfault
 - Focus on errors affecting correctness and data integrity
 - Verify logic errors aren't false alarms due to type narrowing
 - Consider real-world edge cases: malformed input, unusual formats, cross-platform paths
-- [IF C/C++ exists] Pay special attention to pointer arithmetic and buffer calculations
 </quality_guidelines>
 
 Analyze systematically and report all logic errors found. If no errors are found, state that explicitly.
@@ -425,7 +253,7 @@ Analyze systematically and report all logic errors found. If no errors are found
 Your task is to analyze caching implementation for correctness, staleness bugs, and performance issues. Focus on cache corruption, invalidation failures, and race conditions.
 
 <context>
-**[SOCKET-BTM SPECIFIC - Adapt for your repository's caching strategy]**
+[CONDITIONAL: Adapt for your repository's caching strategy]
 
 This project uses caching for npm package overrides and registry data:
 - **Storage**: Package override caching in packages/npm/*
@@ -458,7 +286,7 @@ Checkpoint key generation correctness:
 - Patch ordering: Does key depend on patch application order?
 - Platform isolation: Are Windows/macOS/Linux checkpoints properly separated?
 - Arch isolation: Are ARM64/x64 checkpoints kept separate?
-- Additions: Are build-infra/binject changes invalidating checkpoints?
+- Dependencies: Are dependency changes invalidating caches?
 - Environment: Are env vars (NODE_OPTIONS, etc.) affecting builds included?
 
 **NOTE**: Platform-agnostic operations (npm package parsing) may share cache keys across platforms,
@@ -489,7 +317,7 @@ Scenarios producing stale/incorrect checkpoints:
 - Platform mismatch: Restoring darwin checkpoint on linux
 - Arch mismatch: Restoring arm64 checkpoint for x64 build
 - Version mismatch: Node.js version changed but checkpoint reused
-- Additions changed: build-infra/binject updated but checkpoint not invalidated
+- Dependencies changed: Updated dependencies but checkpoint not invalidated
 - Environment drift: Build flags changed but cache key unchanged
 </pattern>
 
@@ -544,28 +372,29 @@ Analyze the checkpoint implementation thoroughly across all checkpoint stages an
 
 ### Workflow Scan Agent
 
-**Mission**: Detect problems in build scripts, CI configuration, git hooks, and developer workflows across the socket-btm monorepo.
+**Mission**: Detect problems in build scripts, CI configuration, git hooks, and developer workflows across the socket-registry monorepo.
 
-**Scan Targets**: All `scripts/`, `package.json`, `.git-hooks/*`, `.github/workflows/*` across packages
+**Scan Targets**: All `scripts/`, `package.json`, `.git-hooks/*`, `.husky/*`, `.github/workflows/*` across packages
 
 **Prompt Template:**
 ```
-Your task is to identify issues in socket-btm's development workflows, build scripts, and CI configuration that could cause build failures, test flakiness, or poor developer experience.
+Your task is to identify issues in socket-registry's development workflows, build scripts, and CI configuration that could cause build failures, test flakiness, or poor developer experience.
 
 <context>
-socket-btm is a pnpm monorepo with:
+socket-registry is a pnpm monorepo with:
+- **npm packages**: packages/npm/* (override packages published to npm)
 - **Build scripts**: scripts/**/*.{mjs,mts} (ESM, cross-platform Node.js)
 - **Package manager**: pnpm workspaces with scripts in each package.json
-- **Git hooks**: .git-hooks/* for pre-commit, pre-push validation
-- **CI**: GitHub Actions (.github/workflows/)
-- **Platforms**: Must work on Windows, macOS, Linux (ARM64, x64)
+- **Git hooks**: .git-hooks/* and .husky/* for pre-commit, pre-push validation
+- **CI**: GitHub Actions (.github/workflows/) - reusable workflows consumed by other repos
+- **Platforms**: Must work on Windows, macOS, Linux
 - **CLAUDE.md**: Defines conventions (no process.exit(), no backward compat, etc.)
-- **Critical**: Build scripts compile C/C++ code and apply patches - must handle errors gracefully
+- **Critical**: Build scripts generate npm override packages - must handle errors gracefully
 
-Packages:
-- node-smol-builder: Main build orchestration
-- binject: C/C++ binary injection library
-- bin-infra, build-infra: Utilities used by node-smol-builder
+Key directories:
+- packages/npm/ - Override npm packages
+- registry/lib/ - Registry library code
+- scripts/ - Build and maintenance scripts
 </context>
 
 <instructions>
@@ -594,7 +423,7 @@ Error handling in scripts:
 <pattern name="import_conventions">
 Import style conventions (Socket Security standards):
 - Use `@socketsecurity/lib/logger` instead of custom log functions or cherry-picked console methods
-- Use `@socketsecurity/lib/spawn` instead of `node:child_process` (except in `additions/` directory)
+- Use `@socketsecurity/lib/spawn` instead of `node:child_process`
 - For Node.js built-in modules: **Cherry-pick fs, default import path/os/url/crypto**
   - For `fs`: cherry-pick sync methods, use promises namespace for async
   - For `child_process`: **avoid direct usage** - prefer `@socketsecurity/lib/spawn`
@@ -609,7 +438,7 @@ Import style conventions (Socket Security standards):
 
 Examples of what to flag:
 - Custom log functions: `function log(msg) { console.log(msg) }` → use `@socketsecurity/lib/logger`
-- Direct child_process usage (except in additions/):
+- Direct child_process usage:
   - `import { execSync } from 'node:child_process'` → use `import { spawn } from '@socketsecurity/lib/spawn'`
   - `execSync('cmd arg1')` → use `await spawn('cmd', ['arg1'])`
 - Default imports for fs:
@@ -650,12 +479,11 @@ Git hooks configuration:
 CI pipeline issues:
 - Build order: Are steps in correct sequence (install → build → test)?
 - Cross-platform: Are Windows/macOS/Linux builds all tested?
-- C/C++ compilation: Are compiler toolchains (clang, gcc, MSVC) properly configured?
-- Build artifacts: Are Node.js binaries uploaded for each platform?
-- Checkpoint caching: Are build checkpoints cached across CI runs?
+- Build artifacts: Are npm packages built and published correctly?
+- Caching: Are node_modules and build outputs cached across CI runs?
 - Failure notifications: Are build failures clearly visible?
-- Node.js versions: Are upstream Node.js version updates tested?
-- Patch validation: Are patch files validated before application?
+- Node.js versions: Are multiple Node.js versions tested?
+- Reusable workflows: Are workflow inputs and outputs documented?
 </pattern>
 
 <pattern name="developer_experience">
@@ -665,56 +493,24 @@ Documentation and setup:
 </pattern>
 
 <pattern name="build_infrastructure">
-Build script architecture and helper methods (CRITICAL for consistent builds):
+Build script architecture (CRITICAL for consistent package builds):
 
 **Package Build Entry Points:**
-- Packages MUST use `scripts/build.mjs` as the build entry point, never direct Makefile invocation
-- build.mjs handles: dependency downloads, environment setup, then Make invocation
-- Direct `make -f Makefile.<platform>` bypasses critical setup (curl/LIEF downloads)
-
-**Required build.mjs patterns:**
-```javascript
-// CORRECT - uses buildBinSuitePackage from bin-infra
-import { buildBinSuitePackage } from 'bin-infra/lib/builder'
-
-buildBinSuitePackage({
-  packageName: 'tool-name',
-  packageDir: packageRoot,
-  beforeBuild: async () => {
-    // Download dependencies BEFORE Make runs
-    await ensureCurl()  // stubs-builder
-    await ensureLief()          // binject, binpress
-  },
-  smokeTest: async (binaryPath) => { ... }
-})
-```
-
-**Dependency download helpers:**
-- `ensureCurl()` - Downloads curl+mbedTLS from releases (stubs-builder)
-- `ensureLief()` - Downloads LIEF library from releases (binject, binpress)
-- `downloadSocketBtmRelease()` - Generic helper from `@socketsecurity/lib/releases/socket-btm`
+- Use `pnpm run build` as the build entry point
+- Build scripts in `scripts/` handle package generation and validation
 
 **Common mistakes to flag:**
-1. Makefile invoked directly without pnpm wrapper:
-   - Bug: `make -f Makefile.macos` in documentation or scripts
+1. Missing pnpm wrapper:
+   - Bug: Running scripts directly instead of through pnpm
    - Fix: Use `pnpm run build` or `pnpm --filter <package> build`
 
-2. Missing beforeBuild hook:
-   - Bug: build.mjs doesn't download dependencies before Make
-   - Fix: Add beforeBuild with appropriate ensure* calls
-
-3. Wrong dependency helper:
-   - Bug: Manually downloading curl/LIEF with curl/wget
-   - Fix: Use downloadSocketBtmRelease() or package-specific helpers
-
-4. Not using buildBinSuitePackage:
-   - Bug: Custom build script without standard patterns
-   - Fix: Use bin-infra/lib/builder for consistent behavior
+2. Missing error handling in build scripts:
+   - Bug: Build script doesn't validate outputs
+   - Fix: Add validation after each build step
 
 **Check these files:**
-- scripts/build.mjs - Build orchestration for overrides
+- scripts/ - Build and maintenance scripts
 - packages/npm/*/package.json - Override package definitions
-- README.md files - Should document `pnpm run build`, not direct make
 </pattern>
 
 For each issue, consider:
@@ -1034,163 +830,79 @@ Group findings by severity (Error → High → Medium → Low → Info)
 
 ## Workflow Optimization Scan Agent
 
-**Mission**: Verify GitHub Actions workflows optimize CI time by checking `build-required` conditions on expensive installation/setup steps when checkpoint caching is used.
+**Mission**: Verify GitHub Actions workflows optimize CI time by using proper caching, conditional steps, and avoiding redundant work.
 
-**Scan Targets**: All `.github/workflows/*.yml` files that use checkpoint caching
+**Scan Targets**: All `.github/workflows/*.yml` files
 
 **Prompt Template:**
 ```
-Your task is to verify GitHub Actions workflows properly skip expensive tool installation steps when builds are restored from cache by checking for `build-required` conditions.
+Your task is to verify GitHub Actions workflows properly optimize CI time by using caching, conditional steps, and avoiding redundant installations.
 
 <context>
 **Why Workflow Optimization Matters:**
-CI workflows waste significant time installing build tools (compilers, CMake, toolchains) even when builds are restored from cache. For socket-btm with 9 workflows building Node.js binaries across multiple platforms, these optimizations save:
-- **Windows**: 1-3 minutes per run (MinGW/LLVM/CMake installation)
-- **macOS**: 30-60 seconds per run (brew installs, Xcode setup)
-- **Linux**: 30-60 seconds per run (apt-get installs, toolchain setup)
-
-**socket-btm Checkpoint Caching System:**
-socket-btm uses a sophisticated checkpoint caching system to speed up builds:
-- `restore-checkpoint` action: Restores build artifacts from cache (yoga-layout, models, lief, onnxruntime, node-smol)
-- `setup-checkpoints` action: Manages checkpoints for binsuite tools (binpress, binflate, binject)
-- `build-required` output: Indicates if actual build is needed (false when cache restored)
-
-**Workflows Using Checkpoints:**
-1. binsuite.yml - Uses `setup-checkpoints` (binpress, binflate, binject jobs)
-2. node-smol.yml - Uses `restore-checkpoint`
-3. lief.yml - Uses `restore-checkpoint`
-4. onnxruntime.yml - Uses `restore-checkpoint`
-5. yoga-layout.yml - Uses `restore-checkpoint` (Docker-only, no native steps)
-6. models.yml - Uses `restore-checkpoint` (Docker-only, no native steps)
-7. curl.yml - No checkpoint caching
-8. stubs.yml - No checkpoint caching for native builds
-
-**Expected Pattern:**
-Installation steps should check `build-required` before running:
-```yaml
-- name: Install CMake (Windows)
-  if: steps.setup-checkpoints.outputs.build-required == 'true' && matrix.os == 'windows'
-  run: choco install cmake -y
-```
-
-Or the full cache validation pattern:
-```yaml
-- name: Setup build toolchain (macOS)
-  if: |
-    matrix.os == 'macos' &&
-    ((steps.lief-checkpoint-cache.outputs.cache-hit != 'true' || steps.validate-cache.outputs.valid == 'false') ||
-    steps.restore-checkpoint.outputs.build-required == 'true')
-  run: brew install cmake ccache
-```
+CI workflows waste significant time when they don't leverage caching or skip unnecessary steps.
+
+**socket-registry CI Structure:**
+socket-registry provides reusable GitHub Actions workflows consumed by other Socket repos:
+- Reusable workflows in `.github/workflows/` with `workflow_call` triggers
+- Package build and test workflows
+- Publishing workflows for npm packages
+
+**Expected Patterns:**
+- Cache node_modules and pnpm store across runs
+- Skip build steps when outputs are cached
+- Use `if` conditions to skip unnecessary platform-specific steps
 </context>
 
 <instructions>
-Systematically verify all workflows that use checkpoint caching properly optimize installation steps:
+Systematically verify all workflows optimize CI time:
 
-**Step 1: Identify workflows with checkpoint caching**
+**Step 1: Identify workflows with caching**
 ```bash
-grep -l "restore-checkpoint\|setup-checkpoints" .github/workflows/*.yml
+ls .github/workflows/*.yml
 ```
 
 **Step 2: For each workflow, check:**
-1. Which checkpoint action is used (`restore-checkpoint` or `setup-checkpoints`)
-2. Identify ALL installation/setup steps:
-   - Steps with names: "Install", "Setup", "Select Xcode"
-   - Steps running: `choco install`, `apt-get install`, `brew install`, `xcode-select`
-   - Steps downloading tools: llvm-mingw downloads, toolchain downloads
-
-**Step 3: Verify each installation step has correct condition:**
-- For `setup-checkpoints`: `steps.setup-checkpoints.outputs.build-required == 'true'`
-- For `restore-checkpoint`: `steps.restore-checkpoint.outputs.build-required == 'true'`
-- OR full cache check: `(cache-hit != 'true' || valid == 'false') || build-required == 'true'`
-
-**Step 4: Exceptions (steps that should NOT check build-required):**
-- pnpm/Node.js setup (needed to run build scripts)
-- QEMU/Docker setup for testing (not build dependencies)
-- Depot CLI setup (needed for Docker builds)
-- Steps in workflows without checkpoint caching
-
-<pattern name="missing_build_required_check">
-Installation step runs unconditionally even when cache is restored:
-```yaml
-# BAD - no build-required check
-- name: Install CMake (Windows)
-  if: matrix.os == 'windows'
-  run: choco install cmake -y
-
-# GOOD - checks build-required
-- name: Install CMake (Windows)
-  if: steps.setup-checkpoints.outputs.build-required == 'true' && matrix.os == 'windows'
-  run: choco install cmake -y
-```
+1. Is pnpm store cached? (`actions/cache` or `pnpm/action-setup` with cache)
+2. Are build outputs cached when possible?
+3. Are installation steps conditional on cache misses?
 
-Look for steps that:
-- Install compilers (gcc, clang, MinGW, llvm-mingw)
-- Install build tools (cmake, ninja, make, ccache)
-- Setup toolchains (musl-tools, cross-compilers)
-- Select Xcode versions
-- Download toolchain archives
-</pattern>
+**Step 3: Verify optimization patterns:**
 
-<pattern name="wrong_checkpoint_reference">
-Step references wrong checkpoint action output:
+<pattern name="missing_cache">
+Workflows that install dependencies without caching:
 ```yaml
-# BAD - binsuite.yml uses setup-checkpoints, not restore-checkpoint
-- name: Install tools
-  if: steps.restore-checkpoint.outputs.build-required == 'true'
-
-# GOOD - correct reference
-- name: Install tools
-  if: steps.setup-checkpoints.outputs.build-required == 'true'
+# BAD - no caching
+- run: pnpm install
+
+# GOOD - with pnpm store cache
+- uses: pnpm/action-setup@v4
+- uses: actions/setup-node@v4
+  with:
+    cache: 'pnpm'
+- run: pnpm install
 ```
-
-socket-btm conventions:
-- binsuite.yml (binpress/binflate/binject): Use `steps.setup-checkpoints.outputs.build-required`
-- node-smol.yml, lief.yml, onnxruntime.yml: Use `steps.restore-checkpoint.outputs.build-required`
 </pattern>
 
-<pattern name="incomplete_condition">
-Step checks some conditions but misses build-required:
-```yaml
-# BAD - checks platform but not build-required
-- name: Setup toolchain (Windows ARM64)
-  if: matrix.os == 'windows' && matrix.cross_compile
-  run: |
-    curl -o llvm-mingw.zip https://...
-    7z x llvm-mingw.zip
-
-# GOOD - includes build-required check
-- name: Setup toolchain (Windows ARM64)
-  if: |
-    matrix.os == 'windows' && matrix.cross_compile &&
-    ((steps.cache.outputs.cache-hit != 'true' || steps.validate.outputs.valid == 'false') ||
-    steps.restore-checkpoint.outputs.build-required == 'true')
-```
+<pattern name="redundant_steps">
+Steps that run unconditionally but could be skipped:
+- Installation steps that re-run even when cached
+- Build steps that re-run even when outputs exist
+- Test setup that duplicates other workflow steps
 </pattern>
 
-**socket-btm-Specific Workflow Patterns:**
-
-1. **binsuite.yml** (binpress, binflate, binject jobs):
-   - Uses: `setup-checkpoints` action
-   - Steps to check: Compiler setup, dependency installation, toolchain setup, Xcode selection, CMake installation
-
-2. **node-smol.yml**:
-   - Uses: `restore-checkpoint` action
-   - Steps to check: musl toolchain, Xcode selection, Windows tools, compression dependencies
-
-3. **lief.yml**:
-   - Uses: `restore-checkpoint` action with full cache validation
-   - Steps to check: macOS toolchain (brew install cmake ccache), Windows toolchains
-
-4. **onnxruntime.yml**:
-   - Uses: `restore-checkpoint` action
-   - Steps to check: Build tools installation (ninja-build)
+<pattern name="reusable_workflow_issues">
+Reusable workflow problems:
+- Missing required inputs documentation
+- Outputs not properly propagated to callers
+- Secrets not passed through correctly
+</pattern>
 
 For each issue found:
 1. Identify the workflow file and line number
-2. Show the current condition
-3. Explain why build-required check is missing or incorrect
-4. Provide the corrected condition
+2. Show the current configuration
+3. Explain the optimization opportunity
+4. Provide the corrected configuration
 5. Estimate time savings from the fix
 </instructions>
 
@@ -1198,33 +910,31 @@ For each issue found:
 For each finding, report:
 
 File: .github/workflows/workflow-name.yml:line
-Issue: Installation step missing build-required check
+Issue: [One-line description]
 Severity: Medium
-Impact: Wastes N seconds/minutes installing tools when cache is restored
-Pattern: [current condition]
-Fix: [corrected condition with build-required check]
-Savings: Estimated ~N seconds per cached CI run
+Impact: Wastes N seconds/minutes per CI run
+Pattern: [current configuration]
+Fix: [corrected configuration]
+Savings: Estimated ~N seconds per CI run
 
 Example:
-File: .github/workflows/lief.yml:310
-Issue: macOS toolchain setup missing build-required check
+File: .github/workflows/ci.yml:45
+Issue: pnpm store not cached across runs
 Severity: Medium
-Impact: Wastes 30-60 seconds installing cmake/ccache when LIEF is restored from cache
-Pattern: `if: matrix.os == 'macos'`
-Fix: `if: matrix.os == 'macos' && ((steps.lief-checkpoint-cache.outputs.cache-hit != 'true' || steps.validate-cache.outputs.valid == 'false') || steps.restore-checkpoint.outputs.build-required == 'true')`
-Savings: ~45 seconds per cached macOS CI run
+Impact: Wastes 30-60 seconds reinstalling dependencies on each run
+Pattern: Missing `cache: 'pnpm'` in setup-node step
+Fix: Add `cache: 'pnpm'` to actions/setup-node configuration
+Savings: ~45 seconds per CI run
 </output_format>
 
 <quality_guidelines>
-- Only report installation/setup steps that install tools needed for building
-- Don't report steps needed for running build scripts (pnpm, Node.js)
-- Verify the checkpoint action type before suggesting fix
-- Calculate realistic time savings based on actual tool installation times
+- Only report steps where caching or conditions would provide real savings
+- Don't report steps that genuinely need to run every time
 - If all workflows are optimized, state that explicitly
 - Group findings by workflow file
 </quality_guidelines>
 
-Systematically analyze all workflows with checkpoints and report all missing optimizations. If workflows are fully optimized, state: "✓ All workflows properly optimize installation steps with build-required checks."
+Systematically analyze all workflows and report all missing optimizations. If workflows are fully optimized, state: "All workflows properly optimize CI time."
 ```
 
 ---
@@ -1329,10 +1039,8 @@ Look for:
 <pattern name="build_outputs">
 Look for:
 - Build output paths that don't match actual outputs
-- File sizes that are significantly outdated
-- Checkpoint names that don't match actual implementation
-- Binary names that are incorrect
-- Missing intermediate build stages
+- Package names that are incorrect
+- Missing build steps in documentation
 </pattern>
 
 <pattern name="version_information">
@@ -1342,14 +1050,10 @@ Look for:
 - Tool version requirements that are incorrect
 - Patch counts that don't match actual patches
 
-**CRITICAL: For third-party library versions (LIEF, Node.js, ONNX Runtime, etc.):**
+**CRITICAL: For dependency versions:**
 - DO NOT blindly "correct" documented versions without verification
-- For socket-btm specifically, versions must align with what Node.js upstream uses
-- LIEF version: Documented version (v0.17.0) is correct - aligned with Node.js needs
-- Node.js version: Check .node-version file (source of truth)
-- ONNX Runtime, Yoga: Verify against package configurations
+- Check package.json files as the source of truth for dependency versions
 - If unsure about a version, SKIP reporting it as incorrect - ask user to verify
-- NEVER change version numbers based on git describe output from dependencies
 - When in doubt, assume documentation is correct unless you can definitively verify otherwise
 </pattern>
 
@@ -1365,8 +1069,8 @@ Look for:
 **CRITICAL: Evaluate documentation from a junior developer perspective**
 
 Check for junior-developer unfriendly patterns:
-- Missing "Why" explanations (e.g., "Use binject to inject SEA" without explaining what SEA is)
-- Assumed knowledge not documented (Node.js SEA, LIEF, VFS concepts)
+- Missing "Why" explanations (e.g., "Use overrides to replace packages" without explaining what overrides are)
+- Assumed knowledge not documented (npm overrides, pnpm workspaces)
 - No examples for common workflows (first-time setup, typical usage)
 - Missing troubleshooting sections
 - No explanation of error messages
@@ -1384,11 +1088,10 @@ Check for junior-developer unfriendly patterns:
 5. **Error message handling** - Should help debug, not confuse
 
 **Areas requiring extra scrutiny:**
-- Binary manipulation concepts (SEA, VFS, section injection)
-- Build system complexity (checkpoints, caching, cross-compilation)
-- Patch management (upstream sync, patch regeneration)
-- C/C++ integration points (LIEF, native code)
-- Cross-platform differences (Linux musl/glibc, macOS universal binaries, Windows)
+- npm override concepts (how overrides work, why they exist)
+- Package registry architecture (packages/npm/ structure, registry/lib/)
+- Build scripts and automation (scripts/ directory)
+- CI/CD workflows (reusable workflows, publishing)
 
 For each junior-dev issue:
 - Identify the knowledge gap or assumption
@@ -1397,9 +1100,9 @@ For each junior-dev issue:
 - Provide example of clear explanation
 
 Example findings:
-- "README assumes knowledge of Node.js SEA without explaining it"
-- "No explanation of what 'upstream sync' means or why it matters"
-- "Technical term 'checkpoint caching' used without definition"
+- "README assumes knowledge of npm overrides without explaining them"
+- "No explanation of what 'override packages' means or why they exist"
+- "Technical term 'pnpm workspaces' used without definition"
 - "Build errors not documented in troubleshooting section"
 </pattern>
 
diff --git a/.claude/skills/updating/SKILL.md b/.claude/skills/updating/SKILL.md
index aed6bba4..adc8b446 100644
--- a/.claude/skills/updating/SKILL.md
+++ b/.claude/skills/updating/SKILL.md
@@ -62,8 +62,8 @@ Run pnpm run update to update npm dependencies:
 pnpm run update
 
 # Check if there are changes
-if [ -n "$(git status --porcelain pnpm-lock.yaml package.json)" ]; then
-  git add pnpm-lock.yaml package.json
+if [ -n "$(git status --porcelain)" ]; then
+  git add pnpm-lock.yaml pnpm-workspace.yaml package.json packages/npm/*/package.json
   git commit -m "chore: update npm dependencies
 
 Updated npm packages via pnpm run update."

From c94fc9b0b7a1fc872434024c91dca6f348fbf637 Mon Sep 17 00:00:00 2001
From: jdalton <john.david.dalton@gmail.com>
Date: Mon, 6 Apr 2026 14:45:51 -0400
Subject: [PATCH 09/10] chore(deps): bump @anthropic-ai/claude-code to 2.1.92
 (security)

v2.1.90 fixes deny-rule bypass (parse-fail fallback degradation).
v2.1.91 adds disableSkillShellExecution setting.
v2.1.92 fixes hook semantics and sandbox hardening.

Also add @anthropic-ai/* to minimumReleaseAgeExclude for consistency
with other trusted first-party packages.
---
 pnpm-lock.yaml      | 12 ++++++------
 pnpm-workspace.yaml |  3 ++-
 2 files changed, 8 insertions(+), 7 deletions(-)

diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 0a55d7e5..fa240205 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -7,8 +7,8 @@ settings:
 catalogs:
   default:
     '@anthropic-ai/claude-code':
-      specifier: 2.1.89
-      version: 2.1.89
+      specifier: 2.1.92
+      version: 2.1.92
     '@babel/core':
       specifier: 7.28.4
       version: 7.28.4
@@ -278,7 +278,7 @@ importers:
     devDependencies:
       '@anthropic-ai/claude-code':
         specifier: 'catalog:'
-        version: 2.1.89
+        version: 2.1.92
       '@babel/core':
         specifier: 'catalog:'
         version: 7.28.4
@@ -894,8 +894,8 @@ packages:
     engines: {node: '>=20'}
     hasBin: true
 
-  '@anthropic-ai/claude-code@2.1.89':
-    resolution: {integrity: sha512-etjihHqVxj1RjS5Zu/o+rv3ojn1N7AWzfgIOCSSSncfyb4qJn9J677scj0LHIxtwzjgU7j1qAedXlXKxgkFG2w==}
+  '@anthropic-ai/claude-code@2.1.92':
+    resolution: {integrity: sha512-mNGw/IK3+1yHsQBeKaNtdTPCrQDkUEuNTJtm3OBTXs4bBkUVdIgRme/34ZnbZkl2VMMYPoNaTvqX2qJZ9EdSxQ==}
     engines: {node: '>=18.0.0'}
     hasBin: true
 
@@ -3720,7 +3720,7 @@ snapshots:
       tinyexec: 1.0.2
       tinyglobby: 0.2.15
 
-  '@anthropic-ai/claude-code@2.1.89':
+  '@anthropic-ai/claude-code@2.1.92':
     optionalDependencies:
       '@img/sharp-darwin-arm64': 0.34.5
       '@img/sharp-darwin-x64': 0.34.5
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index 2d27fc67..d1894ccf 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -1,6 +1,7 @@
 # Wait 7 days (10080 minutes) before installing newly published packages.
 minimumReleaseAge: 10080
 minimumReleaseAgeExclude:
+  - '@anthropic-ai/*'
   - '@socketaddon/*'
   - '@socketbin/*'
   - '@socketregistry/*'
@@ -13,7 +14,7 @@ packages:
   - scripts
 
 catalog:
-  '@anthropic-ai/claude-code': 2.1.89
+  '@anthropic-ai/claude-code': 2.1.92
   '@babel/core': 7.28.4
   '@babel/generator': 7.28.3
   '@babel/parser': 7.28.4

From 78d511a4c82c8344fb6a1c4f97e1cbe76c3e677e Mon Sep 17 00:00:00 2001
From: jdalton <john.david.dalton@gmail.com>
Date: Mon, 6 Apr 2026 15:02:03 -0400
Subject: [PATCH 10/10] fix: commit-msg hook false positive on package scope
 names

The AI attribution filter matched package names like
@anthropic-ai/claude-code. Now uses .com suffix matching
and excludes the -ai/ npm scope.
---
 .git-hooks/commit-msg | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.git-hooks/commit-msg b/.git-hooks/commit-msg
index b85d1f50..1210859a 100755
--- a/.git-hooks/commit-msg
+++ b/.git-hooks/commit-msg
@@ -47,7 +47,7 @@ if [ -f "$COMMIT_MSG_FILE" ]; then
   # Read the commit message line by line and filter out AI attribution.
   while IFS= read -r line || [ -n "$line" ]; do
     # Check if this line contains AI attribution patterns.
-    if echo "$line" | grep -qiE "(Generated with|Co-Authored-By: Claude|Co-Authored-By: AI|🤖 Generated|AI generated|Claude Code|@anthropic|Assistant:|Generated by Claude|Machine generated)"; then
+    if echo "$line" | grep -qiE "(Generated with|Co-Authored-By: Claude|Co-Authored-By: AI|🤖 Generated|AI generated|Claude Code|@anthropic\.com|Assistant:|Generated by Claude|Machine generated)" && ! echo "$line" | grep -qE "@anthropic-ai/"; then
       REMOVED_LINES=$((REMOVED_LINES + 1))
     else
       # Line doesn't contain AI attribution, keep it.