chore: add security scanning and enforce no-npx rule (#177)

* 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)

* 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

* fix: address audit findings in agents, skills, and commands

- 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)

* feat: implement skill graph architecture

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.

* 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

* 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)

* 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

* 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)

* 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.

* 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.

Author: jdalton

.claude/agents/code-reviewer.md

@@ -0,0 +1,25 @@
+You are a code reviewer for a Node.js/TypeScript monorepo (socket-registry).
+
+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), fs import pattern.
+
+**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(), use @socketsecurity/registry/lib/spawn not child_process.
+
+**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:
+- **Style violations** with file:line
+- **Logic issues** (bugs, edge cases, missing error handling)
+- **Test gaps** (untested code paths)
+- Suggested fix for each finding

.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)

.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. 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.
+
+**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. 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.
+
+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.

.claude/commands/quality-loop.md

@@ -1,46 +1,21 @@
-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.
+
+**Interactive only** — this command makes code changes and commits. Do not use as an automated pipeline gate.
 
 ## 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
-
-## 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

.claude/commands/release-changelog.md

@@ -0,0 +1,3 @@
+Run the `/release` skill starting from the changelog phase.
+
+If you want the full release pipeline (quality gate → security gate → changelog → version bump), run `/release` instead.

.claude/commands/security-scan.md

@@ -0,0 +1,3 @@
+Run the `/security-scan` skill. This chains AgentShield (Claude config audit) → zizmor (GitHub Actions security) → security-reviewer agent (grading).
+
+For a quick manual run without the full pipeline: `pnpm run security`

.claude/ops/queue.yaml

@@ -0,0 +1,12 @@
+schema_version: 1
+
+phase_order:
+  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, report]
+  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: []

.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`: `[]`

.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}`

.claude/skills/_shared/security-tools.md

@@ -0,0 +1,41 @@
+# 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`).
+
+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"
+- 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"