From 04f48045a26ebf0bd5470956208a33f22597f006 Mon Sep 17 00:00:00 2001
From: Test User <john.david.dalton@gmail.com>
Date: Thu, 9 Apr 2026 13:46:39 -0400
Subject: [PATCH 1/5] chore(ci): bump socket-registry SHA to ed311907

---
 .github/workflows/ci.yml            | 4 ++--
 .github/workflows/provenance.yml    | 2 +-
 .github/workflows/weekly-update.yml | 8 ++++----
 3 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 50afffe..e8f83f1 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -27,7 +27,7 @@ permissions:
 jobs:
   ci:
     name: Run CI Pipeline
-    uses: SocketDev/socket-registry/.github/workflows/ci.yml@4edf2e3c3beff7d536e79ce43dfb61abba7cb537 # main
+    uses: SocketDev/socket-registry/.github/workflows/ci.yml@ed3119078118d558f095e9adf8800263166d65f9 # main
     with:
       test-setup-script: 'pnpm run build'
       lint-script: 'pnpm run lint --all'
@@ -46,7 +46,7 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 10
     steps:
-      - uses: SocketDev/socket-registry/.github/actions/setup-and-install@4edf2e3c3beff7d536e79ce43dfb61abba7cb537 # main
+      - uses: SocketDev/socket-registry/.github/actions/setup-and-install@ed3119078118d558f095e9adf8800263166d65f9 # main
 
       - name: Build project
         run: pnpm run build
diff --git a/.github/workflows/provenance.yml b/.github/workflows/provenance.yml
index 31e3015..5e64030 100644
--- a/.github/workflows/provenance.yml
+++ b/.github/workflows/provenance.yml
@@ -21,7 +21,7 @@ permissions:
 
 jobs:
   publish:
-    uses: SocketDev/socket-registry/.github/workflows/provenance.yml@4edf2e3c3beff7d536e79ce43dfb61abba7cb537 # main
+    uses: SocketDev/socket-registry/.github/workflows/provenance.yml@ed3119078118d558f095e9adf8800263166d65f9 # main
     with:
       debug: ${{ inputs.debug }}
       package-name: '@socketsecurity/lib'
diff --git a/.github/workflows/weekly-update.yml b/.github/workflows/weekly-update.yml
index cb563ba..ef8027b 100644
--- a/.github/workflows/weekly-update.yml
+++ b/.github/workflows/weekly-update.yml
@@ -24,7 +24,7 @@ jobs:
     outputs:
       has-updates: ${{ steps.check.outputs.has-updates }}
     steps:
-      - uses: SocketDev/socket-registry/.github/actions/setup-and-install@4edf2e3c3beff7d536e79ce43dfb61abba7cb537 # main
+      - uses: SocketDev/socket-registry/.github/actions/setup-and-install@ed3119078118d558f095e9adf8800263166d65f9 # main
 
       - name: Check for npm updates
         id: check
@@ -48,7 +48,7 @@ jobs:
       contents: write
       pull-requests: write
     steps:
-      - uses: SocketDev/socket-registry/.github/actions/setup-and-install@4edf2e3c3beff7d536e79ce43dfb61abba7cb537 # main
+      - uses: SocketDev/socket-registry/.github/actions/setup-and-install@ed3119078118d558f095e9adf8800263166d65f9 # main
 
       - name: Create update branch
         id: branch
@@ -60,7 +60,7 @@ jobs:
           git checkout -b "$BRANCH_NAME"
           echo "branch=$BRANCH_NAME" >> $GITHUB_OUTPUT
 
-      - uses: SocketDev/socket-registry/.github/actions/setup-git-signing@4edf2e3c3beff7d536e79ce43dfb61abba7cb537 # main
+      - uses: SocketDev/socket-registry/.github/actions/setup-git-signing@ed3119078118d558f095e9adf8800263166d65f9 # main
         with:
           gpg-private-key: ${{ secrets.BOT_GPG_PRIVATE_KEY }}
 
@@ -295,7 +295,7 @@ jobs:
             test-output.log
           retention-days: 7
 
-      - uses: SocketDev/socket-registry/.github/actions/cleanup-git-signing@4edf2e3c3beff7d536e79ce43dfb61abba7cb537 # main
+      - uses: SocketDev/socket-registry/.github/actions/cleanup-git-signing@ed3119078118d558f095e9adf8800263166d65f9 # main
         if: always()
 
   notify:

From f43c7a493dd0f493ac07a306c7fa7a733002b6e1 Mon Sep 17 00:00:00 2001
From: Test User <john.david.dalton@gmail.com>
Date: Thu, 9 Apr 2026 13:50:20 -0400
Subject: [PATCH 2/5] feat(ci): pipe publish-without-sfw and SOCKET_API_KEY to
 provenance workflow

---
 .github/workflows/provenance.yml | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/.github/workflows/provenance.yml b/.github/workflows/provenance.yml
index 5e64030..fc63d42 100644
--- a/.github/workflows/provenance.yml
+++ b/.github/workflows/provenance.yml
@@ -14,6 +14,11 @@ on:
         options:
           - '0'
           - '1'
+      publish-without-sfw:
+        description: 'Publish directly to npm, bypassing Socket firewall shims'
+        required: false
+        default: false
+        type: boolean
 
 permissions:
   contents: write   # Push git tags and create GitHub releases
@@ -25,5 +30,8 @@ jobs:
     with:
       debug: ${{ inputs.debug }}
       package-name: '@socketsecurity/lib'
+      publish-without-sfw: ${{ inputs.publish-without-sfw }}
       setup-script: 'pnpm run build'
       use-trusted-publishing: true
+    secrets:
+      SOCKET_API_KEY: ${{ secrets.SOCKET_API_KEY }}

From 0b89fe1a231800769e680bc1d72a213805983782 Mon Sep 17 00:00:00 2001
From: Test User <john.david.dalton@gmail.com>
Date: Thu, 9 Apr 2026 16:48:39 -0400
Subject: [PATCH 3/5] chore: trim CLAUDE.md and audit skills

---
 .claude/commands/quality-loop.md      |   2 +-
 .claude/commands/security-scan.md     |   2 +-
 .claude/skills/security-scan/SKILL.md |   2 +-
 CLAUDE.md                             | 523 +++-----------------------
 4 files changed, 65 insertions(+), 464 deletions(-)

diff --git a/.claude/commands/quality-loop.md b/.claude/commands/quality-loop.md
index ddd5937..93eb888 100644
--- a/.claude/commands/quality-loop.md
+++ b/.claude/commands/quality-loop.md
@@ -1,4 +1,4 @@
-Run the `/quality-scan` skill and fix all issues found. Repeat until zero issues remain or 5 iterations complete.
+Runs the `/quality-scan` skill and fixes all issues found. Repeats 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.
 
diff --git a/.claude/commands/security-scan.md b/.claude/commands/security-scan.md
index 6c62968..a8eab92 100644
--- a/.claude/commands/security-scan.md
+++ b/.claude/commands/security-scan.md
@@ -1,3 +1,3 @@
-Run the `/security-scan` skill. This chains AgentShield (Claude config audit) → zizmor (GitHub Actions security) → security-reviewer agent (grading).
+Runs the `/security-scan` skill. 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`
diff --git a/.claude/skills/security-scan/SKILL.md b/.claude/skills/security-scan/SKILL.md
index 0ba403f..161fb5b 100644
--- a/.claude/skills/security-scan/SKILL.md
+++ b/.claude/skills/security-scan/SKILL.md
@@ -1,6 +1,6 @@
 ---
 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.
+description: Runs 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
diff --git a/CLAUDE.md b/CLAUDE.md
index 1ee8f53..efb78a8 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -2,14 +2,11 @@
 
 **MANDATORY**: Act as principal-level engineer. Follow these guidelines exactly.
 
-## 👤 USER CONTEXT
+## USER CONTEXT
 
 - **Identify users by git credentials**: Extract name from git commit author, GitHub account, or context
-- 🚨 **When identity is verified**: ALWAYS use their actual name - NEVER use "the user" or "user"
-- **Direct communication**: Use "you/your" when speaking directly to the verified user
-- **Discussing their work**: Use their actual name when referencing their commits/contributions
+- When identity is verified: ALWAYS use their actual name, NEVER "the user"
 - **Example**: If git shows "John-David Dalton <jdalton@example.com>", refer to them as "John-David"
-- **Other contributors**: Use their actual names from commit history/context
 
 ## PRE-ACTION PROTOCOL
 
@@ -71,7 +68,6 @@
 
 - After ANY correction from the user: log the pattern to memory so the same mistake is never repeated
 - Convert mistakes into strict rules — don't just note them, enforce them
-- After fixing a bug: explain why it happened and whether anything prevents that category of bug in the future
 
 ## FILE SYSTEM AS STATE
 
@@ -85,7 +81,7 @@ The file system is working memory. Use it actively:
 ## HOUSEKEEPING
 
 - Before risky changes: offer to checkpoint — "want me to commit before this?"
-- If a file is getting unwieldy (>400 LOC): flag it — "this is big enough to cause pain — want me to split it?"
+- If a file is getting unwieldy (>400 LOC): flag it
 
 ## ABSOLUTE RULES
 
@@ -93,43 +89,15 @@ The file system is working memory. Use it actively:
 - 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.
+- NEVER use `npx`, `pnpm dlx`, or `yarn dlx` — use `pnpm exec <package>` for devDep binaries, or `pnpm run <script>` for package.json scripts
 
-## 📄 DOCUMENTATION POLICY
+## DOCUMENTATION POLICY
 
-**Philosophy**: Minimize documentation clutter. Code should be self-documenting; docs should be intentional.
+**Allowed**: `README.md`, `CLAUDE.md`, `SECURITY.md`, `CHANGELOG.md`, `docs/` (max 10 files), `.claude/` (functional only), `*/README.md` (complex subsystems only)
 
-**Allowed documentation files**:
+**Forbidden**: Migration/planning docs after completion, redundant guides, docs duplicating code comments, tutorial content, ADRs unless requested
 
-- `README.md` - Project overview, installation, basic usage only
-- `CLAUDE.md` - AI assistant instructions
-- `SECURITY.md` - Security policy (GitHub standard)
-- `CHANGELOG.md` - Version history (auto-generated preferred)
-- `docs/` - Concentrated API/usage documentation (10 files max, keep concise)
-- `.claude/` - Claude Code commands/skills (functional, not documentation)
-- `*/README.md` - Only for plugins/, scripts/, or complex subsystems requiring context
-
-**Forbidden documentation**:
-
-- ❌ Migration plans after migration completes
-- ❌ Planning documents after implementation
-- ❌ Redundant "getting started" guides
-- ❌ Docs duplicating what's in code comments
-- ❌ Tutorial content better suited for external blog posts
-- ❌ Architecture decision records (ADRs) unless explicitly requested
-
-**Maintenance protocol**:
-
-1. **After completing migrations**: DELETE planning documents (e.g., `MIGRATION_PLAN_*.md`)
-2. **After major refactors**: REMOVE implementation plans
-3. **Quarterly review**: Audit and remove stale documentation
-4. **Before adding docs**: Ask "Can this be a code comment instead?"
-
-**Enforcement**:
-
-- AI assistants MUST NOT create documentation files unless explicitly requested
-- Code reviewers should challenge new documentation files
-- Prefer inline code documentation (`@fileoverview`, JSDoc) over separate markdown files
+After completing migrations or major refactors, DELETE planning documents. Prefer inline code documentation (`@fileoverview`, JSDoc) over separate markdown files.
 
 ## ROLE
 
@@ -139,7 +107,7 @@ Principal Software Engineer: production code, architecture, reliability, ownersh
 
 If user repeats instruction 2+ times, ask: "Should I add this to CLAUDE.md?"
 
-## 📚 SHARED STANDARDS
+## SHARED STANDARDS
 
 **Canonical reference**: `../socket-registry/CLAUDE.md`
 
@@ -147,107 +115,49 @@ All shared standards (git, testing, code style, cross-platform, CI) defined in s
 
 **Quick references**:
 
-- Commits: [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) `<type>(<scope>): <description>` — types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `perf` — NO AI attribution (the commit-msg hook auto-strips it)
+- Commits: [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) `<type>(<scope>): <description>` — NO AI attribution
 - Scripts: Prefer `pnpm run foo --flag` over `foo:bar` scripts
-- Docs: Use `docs/` folder, lowercase-with-hyphens.md filenames, pithy writing with visuals
 - Dependencies: After `package.json` edits, run `pnpm install` to update `pnpm-lock.yaml`
-- Backward Compatibility: 🚨 FORBIDDEN to maintain - actively remove when encountered (see canonical CLAUDE.md)
+- Backward Compatibility: FORBIDDEN to maintain — actively remove when encountered (see canonical CLAUDE.md)
 - Work Safeguards: MANDATORY commit + backup branch before bulk changes
 - Safe Deletion: Use `safeDelete()` from `@socketsecurity/lib/fs` (NEVER `fs.rm/rmSync` or `rm -rf`)
 
 ---
 
-## 📝 EMOJI & OUTPUT STYLE
-
-**Terminal Symbols** (based on `@socketsecurity/lib/logger` LOG_SYMBOLS):
-
-- ✓ Success/checkmark - MUST be green (NOT ✅)
-- ✗ Error/failure - MUST be red (NOT ❌)
-- ⚠ Warning/caution - MUST be yellow (NOT ⚠️)
-- ℹ Info - MUST be blue (NOT ℹ️)
-- → Step/progress - MUST be cyan (NOT ➜ or ▶)
-
-**Color Requirements** (apply color to icon ONLY, not entire message):
-
-```javascript
-import colors from 'yoctocolors-cjs'
-;`${colors.green('✓')} ${msg}` // Success
-`${colors.red('✗')} ${msg}` // Error
-`${colors.yellow('⚠')} ${msg}` // Warning
-`${colors.blue('ℹ')} ${msg}` // Info
-`${colors.cyan('→')} ${msg}` // Step/Progress
-```
-
-**Color Package**:
-
-- Use `yoctocolors-cjs` (NOT `yoctocolors` ESM package)
-- Pinned dev dependency in all Socket projects
-- CommonJS compatibility for scripts and tooling
-
-**Allowed Emojis** (use sparingly):
+## EMOJI & OUTPUT STYLE
 
-- 📦 Packages
-- 💡 Ideas/tips
-- 🚀 Launch/deploy/excitement
-- 🎉 Major success/celebration
+**Terminal Symbols** (from `@socketsecurity/lib/logger` LOG_SYMBOLS):
 
-**General Philosophy**:
+| Symbol | Color | Meaning |
+|--------|-------|---------|
+| ✓ | green | Success |
+| ✗ | red | Error |
+| ⚠ | yellow | Warning |
+| ℹ | blue | Info |
+| → | cyan | Step/progress |
 
-- Prefer colored text-based symbols (✓✗⚠ℹ→) for maximum terminal compatibility
-- Always color-code symbols: green=success, red=error, yellow=warning, blue=info, cyan=step
-- Use emojis sparingly for emphasis and delight
-- Avoid emoji overload - less is more
-- When in doubt, use plain text
+Color the icon only, not the message. Use `yoctocolors-cjs` (not the ESM `yoctocolors`). Use emojis sparingly; prefer colored text symbols for terminal compatibility.
 
 ---
 
-## 🏗️ LIB-SPECIFIC
+## LIB-SPECIFIC
 
 ### Architecture
 
 Core infrastructure library for Socket.dev security tools.
 
-**Directory structure**:
-
-```
-src/
-├── index.ts           # Main export barrel
-├── types.ts           # TypeScript type definitions
-├── constants/         # Node.js, npm, package manager constants
-├── env/              # Typed environment variable access
-├── packages/         # Package management utilities
-├── external/         # Vendored external dependencies
-└── utils/            # Shared utilities
-
-dist/                 # Build output (CommonJS)
-├── external/         # Bundled external dependencies
-└── ...               # Compiled source files
-
-scripts/              # Build and development scripts
-test/                 # Test files
-```
-
-**Path aliases** (defined in `.config/tsconfig.external-aliases.json`):
-
-```
-#constants/* → src/constants/*
-#env/*       → src/env/*
-#lib/*       → src/*
-#packages/*  → src/packages/*
-#types       → src/types
-#utils/*     → src/utils/*
-```
+**Path aliases** (from `.config/tsconfig.external-aliases.json`): `#constants/*`, `#env/*`, `#lib/*`, `#packages/*`, `#types`, `#utils/*` — all map to `src/` subdirectories. Always use aliases for internal imports (never relative paths).
 
 ### Commands
 
-- **Build**: `pnpm build` (production build)
-- **Watch**: `pnpm run dev` (development mode)
-- **Test**: `pnpm test` (run tests)
-- **Type check**: `pnpm run check` (TypeScript type checking)
-- **Lint**: `pnpm run lint` (oxlint - 50-100x faster than ESLint)
-- **Fix**: `pnpm run fix` (auto-fix formatting/lint issues with oxfmt)
-- **Coverage**: `pnpm run cover` (test coverage)
-- **Clean**: `pnpm run clean` (remove build artifacts)
+- **Build**: `pnpm build`
+- **Watch**: `pnpm run dev`
+- **Test**: `pnpm test`
+- **Type check**: `pnpm run check`
+- **Lint**: `pnpm run lint` (oxlint)
+- **Fix**: `pnpm run fix` (oxfmt)
+- **Coverage**: `pnpm run cover`
+- **Clean**: `pnpm run clean`
 
 ## Agents & Skills
 
@@ -260,89 +170,32 @@ test/                 # Test files
 
 ### Code Quality Tools
 
-#### Linting (oxlint)
-
-- **Tool**: [oxlint](https://oxc.rs) v1.52+ - Rust-based linter (50-100x faster than ESLint)
-- **Config**: `.oxlintrc.json` - 167+ rules with file-specific overrides
-- **Features**:
-  - TypeScript type-aware rules with `--type-aware` flag
-  - ESLint plugin compatibility via `jsPlugins` (e.g., `eslint-plugin-sort-destructure-keys`)
-  - Inline comments: `// oxlint-disable-next-line rule-name`
-  - Categories: correctness, suspicious, pedantic, style, restriction
-- **Performance**: ~100ms for full codebase lint
-
-#### Formatting (oxfmt)
-
-- **Tool**: [oxfmt](https://oxc.rs) v0.37+ - Rust-based formatter (3x faster than Biome, 30x faster than Prettier)
-- **Config**: `.oxfmtrc.json` - Prettier v3.8 compatible
-- **Settings**:
-  - Semi: true
-  - Single quotes: true
-  - Tab width: 2
-  - Print width: 80
-  - Trailing commas: all
-- **Performance**: ~20ms for full codebase format
-
-#### Usage
-
-- `pnpm run lint` - Run oxlint with type-aware rules
-- `pnpm run fix` - Run oxfmt to auto-fix formatting
-- `scripts/lint.mjs` - Orchestrates both tools with proper error handling
+- **Linting**: oxlint v1.52+ with `.oxlintrc.json`, TypeScript type-aware rules. Inline disable: `// oxlint-disable-next-line rule-name`
+- **Formatting**: oxfmt v0.37+ with `.oxfmtrc.json` (Prettier v3.8 compatible, semi, single quotes, 2-space, 80 width, trailing commas)
 
 ### Build System
 
-#### Compilation
-
-- **Target**: TypeScript → CommonJS (ES2022)
-- **Builder**: esbuild via `scripts/build/js.mjs`
-- **Type generation**: tsgo (TypeScript Native Preview)
+- **Target**: TypeScript → CommonJS (ES2022) via esbuild
+- **Types**: tsgo (TypeScript Native Preview)
 - **Output**: `dist/` directory
+- **Build scripts**: All in `scripts/` as `.mjs` files. Shell scripts (`.sh`) FORBIDDEN.
+- **Main build** (`pnpm build`): Clean → build source + types + externals in parallel → fix exports
 
-#### Build Scripts
-
-All build scripts are Node.js modules (`.mjs`) in `scripts/`:
-
-- `build/js.mjs` - Main JavaScript compilation
-- `build/externals.mjs` - External dependency bundling
-- `fix/commonjs-exports.mjs` - Post-build CommonJS export fixes
-- `fix/external-imports.mjs` - Fix external import patterns
-- `fix/generate-package-exports.mjs` - Auto-generate package.json exports
-
-🚨 **FORBIDDEN**: Shell scripts (`.sh`) - Always use Node.js scripts
-
-#### Build Process
-
-The main build command (`pnpm build`) orchestrates via `scripts/build/main.mjs`:
-
-1. Clean previous build
-2. Build in parallel: source code, types, and externals
-3. Fix exports via `scripts/fix/main.mjs`
-
-Individual commands:
-
-- `pnpm run clean` - Clean build artifacts only
-- `pnpm build` - Full build (default)
-
-### Code Style - Lib-Specific
-
-#### Comments
-
-Default to NO comments. Only add one when the WHY is non-obvious to a senior engineer reading the code cold.
+### Code Style
 
 #### File Organization
 
-- **Extensions**: `.ts` for TypeScript, `.d.ts` for type definitions
-- **Naming**: kebab-case filenames (e.g., `cache-with-ttl.ts`)
-- **Module headers**: 🚨 MANDATORY `@fileoverview` headers
-- **Node.js imports**: 🚨 MANDATORY `node:` prefix
-- **Semicolons**: ❌ OMIT (consistent with socket-registry)
+- **Extensions**: `.ts` for source, `.d.ts` for type definitions
+- **Naming**: kebab-case filenames
+- **Module headers**: MANDATORY `@fileoverview` headers
+- **Node.js imports**: MANDATORY `node:` prefix
+- **Semicolons**: OMIT
 
 #### Type Patterns
 
-- **Type safety**: ❌ FORBIDDEN `any`; use `unknown` or specific types
-- **Type imports**: Always separate `import type` from runtime imports
-- **Null-prototype objects**: Use `{ __proto__: null, ...props }` pattern
-- **Options pattern**: `const opts = { __proto__: null, ...options } as SomeOptions`
+- FORBIDDEN: `any` — use `unknown` or specific types
+- Always separate `import type` from runtime imports
+- Null-prototype objects: `{ __proto__: null, ...props }`
 
 #### Import Organization
 
@@ -354,293 +207,41 @@ Default to NO comments. Only add one when the WHY is non-obvious to a senior eng
 
 Blank lines between groups, alphabetical within groups.
 
-#### Path Aliases Usage
-
-- **Internal imports**: Always use path aliases for internal modules
-  - ✅ `import { getCI } from '#env/ci'`
-  - ❌ `import { getCI } from '../env/ci'`
-- **External modules**: Regular imports
-  - ✅ `import path from 'node:path'`
-
 #### Export Patterns
 
-- **Named exports ONLY**: 🚨 MANDATORY for all library modules
-  - ✅ `export { value }` - Direct named export
-  - ✅ `export { foo, bar, baz }` - Multiple named exports
-  - ❌ `export default value` - FORBIDDEN (breaks dual CJS/ESM compatibility)
-  - ❌ `export default X; export { X as 'module.exports' }` - FORBIDDEN (dual export pattern)
-- **Rationale**: Dual-format (CJS/ESM) compatibility requires consistent named exports
-  - Named exports work identically in both module systems
-  - Default exports require `.default` access, breaking consistency
-  - Build validation enforces this pattern (enabled in CI)
-- **Enforcement**:
-  - Oxlint linting rule: `"no-default-export": "error"`
-  - Build-time validation: `scripts/validate/esm-named-exports.mjs`
-  - CI validation: `scripts/validate/dist-exports.mjs`
+- Named exports ONLY — `export default` FORBIDDEN (breaks dual CJS/ESM compatibility)
+- Enforced by: oxlint `no-default-export`, build-time validation, CI validation
 
 #### Function Organization
 
-- **Alphabetical ordering**: 🚨 MANDATORY for all files with 3+ exported functions
-  - **Private functions first**: Non-exported helpers, getters, utilities (alphabetically sorted)
-  - **Exported functions second**: All public API functions (alphabetically sorted)
-  - **Constants/types before functions**: Interfaces, types, constants at top of file
-- **Benefits**:
-  - Predictable function location for navigation
-  - Reduced merge conflicts when adding new functions
-  - Easier code review (spot missing/duplicate exports)
-  - Consistent structure across entire codebase
-- **Example**:
-
-  ```typescript
-  // 1. Imports
-  import { foo } from 'bar'
-
-  // 2. Types/Constants
-  export interface Options { ... }
-
-  // 3. Private functions (alphabetical)
-  function helperA() { ... }
-  function helperB() { ... }
-
-  // 4. Exported functions (alphabetical)
-  export function publicA() { ... }
-  export function publicB() { ... }
-  export function publicC() { ... }
-  ```
+- MANDATORY alphabetical ordering for files with 3+ exported functions
+- Private functions first (alphabetical), then exported functions (alphabetical)
+- Constants/types before functions
 
 ### Package Exports
 
-#### Export Structure
-
-All modules are exported via `package.json` exports field:
-
-- **Constants**: `./constants/<name>` → `dist/constants/<name>.js`
-- **Environment**: `./env/<name>` → `dist/env/<name>.js`
-- **Libraries**: `./<name>` → `dist/<name>.js`
-- **Packages**: `./packages/<name>` → `dist/packages/<name>.js`
-- **Types**: `./types` → `dist/types.js`
-
-#### Adding New Exports
-
-When adding new modules, update `package.json` exports:
-
-```json
-"./module-name": {
-  "types": "./dist/path/to/module.d.ts",
-  "default": "./dist/path/to/module.js"
-}
-```
-
-Or use `scripts/generate-package-exports.mjs` to auto-generate exports.
+All modules exported via `package.json` exports field. When adding new modules, update exports or use `scripts/generate-package-exports.mjs`.
 
 ### Testing
 
-**Vitest Configuration**: This repo uses the shared vitest configuration pattern documented in `../socket-registry/CLAUDE.md` (see "Vitest Configuration Variants" section). Main config: `.config/vitest.config.mts`
-
-#### Test Structure
-
-- **Directories**: `test/` - All test files
-- **Naming**: Match source structure (e.g., `test/spinner.test.ts` for `src/spinner.ts`)
-- **Framework**: Vitest
-- **Coverage**: c8/v8 coverage via Vitest
-
-#### Test Patterns
-
-- Use descriptive test names
-- Test both success and error paths
-- Mock external dependencies appropriately
-- Use path helpers for cross-platform tests
+**Framework**: Vitest (shared config from socket-registry, main config: `.config/vitest.config.mts`)
 
-### Test Style — Functional Over Source Scanning
-
-**NEVER write source-code-scanning tests**
-
-Do not read source files and assert on their contents (`.toContain('pattern')`). These tests are brittle and break on any refactor.
-
-- Write functional tests that verify **behavior**, not string patterns
-- For modules requiring a built binary: use integration tests
-- For pure logic: use unit tests with real function calls
-
-#### Running Tests
-
-- **All tests**: `pnpm test`
-- **Specific file**: `pnpm test path/to/file.test.ts`
-- **Coverage**: `pnpm run cover`
-- **🚨 NEVER USE `--` before test paths** - runs all tests
+- Test files in `test/`, naming matches source structure
+- NEVER use `--` before test paths (runs all tests)
+- NEVER write source-code-scanning tests — verify behavior with real function calls
 
 ### External Dependencies
 
-#### Vendored Dependencies
-
-Some dependencies are vendored in `src/external/`:
-
-- Type definitions for external packages
-- Optimized versions of dependencies
-
-#### Path Mappings
-
-`tsconfig.json` includes path mappings for vendored deps:
-
-```json
-"paths": {
-  "cacache": ["./src/external/cacache"],
-  "make-fetch-happen": ["./src/external/make-fetch-happen"],
-  "fast-sort": ["./src/external/fast-sort"],
-  "pacote": ["./src/external/pacote"]
-}
-```
+Some dependencies are vendored in `src/external/` with `tsconfig.json` path mappings (cacache, make-fetch-happen, fast-sort, pacote).
 
 ### CI Integration
 
-#### Optimized CI Pipeline
-
-**Workflow**: `.github/workflows/ci.yml` - Custom optimized pipeline
-
-**Key Optimizations**:
-
-- **Separate lint job**: Runs once (not 6x in matrix) - saves ~10s
-- **Build caching**: Build runs once, artifacts cached for all jobs - eliminates 5 rebuilds (~8s saved)
-- **Parallel execution**: Lint, build, test, type-check run in parallel where possible
-- **Smart dependencies**: Type-check runs after build completes, tests wait for lint + build
-- **Matrix strategy**: Tests run on Node 20/22/24 × Ubuntu/Windows (6 combinations)
-
-**Performance**:
-
-- Build time: ~1.6s (esbuild, parallelized)
-- Test execution: ~5s (4582 tests, multi-threaded)
-- Total CI time: ~40-60% faster than previous setup
-- Status check job: Single required check for branch protection
-
-**Job Structure**:
-
-1. **lint** - Runs Biome linting (once, Node 22/Ubuntu)
-2. **build** - Compiles source, caches dist + node_modules
-3. **test** - Runs test suite on all matrix combinations (uses cached build)
-4. **type-check** - TypeScript type checking (uses cached build)
-5. **ci-success** - Aggregates all job results for branch protection
-
-**Cache Strategy**:
-
-```yaml
-key: build-${{ github.sha }}-${{ runner.os }}
-path: |
-  dist
-  node_modules
-```
-
-**Previous Setup** (for reference):
-
-- Used reusable workflow: `SocketDev/socket-registry/.github/workflows/ci.yml@<SHA>`
-- 🚨 MANDATORY: Use full commit SHA, not tags
-- Format: `@662bbcab1b7533e24ba8e3446cffd8a7e5f7617e # main`
-
-### Development Workflow
-
-#### Before Committing
-
-1. `pnpm run fix` - Auto-fix formatting/lint issues
-2. `pnpm run check` - Type check
-3. `pnpm test` - Run tests (or `pnpm run cover` for coverage)
-
-#### Watch Mode
-
-Use `pnpm run dev` for development with automatic rebuilds.
-
-#### Adding New Utilities
-
-1. Create utility in appropriate `src/` subdirectory
-2. Use path aliases for internal imports
-3. Add type definitions
-4. Update `package.json` exports if direct export needed
-5. Add tests in `test/` matching structure
-6. Update types and build
-
-### Common Patterns
-
-#### Environment Variables
-
-Access via typed getter functions in `src/env/`:
-
-```typescript
-import { getCI } from '#env/ci'
-import { getNodeEnv } from '#env/node-env'
-import { isTest } from '#env/test'
-```
-
-Each env module exports a pure getter function that accesses only its own environment variable. For fallback logic, compose multiple getters:
-
-```typescript
-import { getHome } from '#env/home'
-import { getUserprofile } from '#env/windows'
-
-const homeDir = getHome() || getUserprofile() // Cross-platform fallback
-```
-
-**Testing with rewiring:**
-Environment getters support test rewiring without modifying `process.env`:
-
-```typescript
-import { setEnv, clearEnv, resetEnv } from '#env/rewire'
-import { getCI } from '#env/ci'
-
-// In test
-setEnv('CI', '1')
-expect(getCI()).toBe(true)
-
-clearEnv('CI') // Clear single override
-resetEnv() // Clear all overrides (use in afterEach)
-```
-
-This allows isolated tests without polluting the global process.env state.
-
-#### File System Operations
-
-Use utilities from `#lib/fs`:
-
-```typescript
-import { readJsonFile, writeJsonFile } from '#lib/fs'
-```
-
-#### Spawning Processes
-
-Use spawn utility from `#lib/spawn`:
-
-```typescript
-import { spawn } from '#lib/spawn'
-```
-
-#### Path Operations
-
-Use path utilities from `#lib/paths`:
-
-```typescript
-import { normalizePath } from '#lib/paths'
-```
-
-#### Working Directory
-
-- **🚨 NEVER use `process.chdir()`** - use `{ cwd }` options and absolute paths instead
-  - Breaks tests, worker threads, and causes race conditions
-  - Always pass `{ cwd: absolutePath }` to spawn/exec/fs operations
-
-### Debugging
-
-#### Common Issues
-
-- **Path alias resolution**: Ensure `tsconfig.json` paths match actual file structure
-- **Module resolution**: Use `node:` prefix for Node.js built-ins
-- **Build errors**: Check for missing exports in `package.json`
-- **Test failures**: Verify path alias resolution in test environment
+Custom optimized pipeline in `.github/workflows/ci.yml`: separate lint job (runs once), build caching (build once, artifacts shared), parallel execution, matrix tests on Node 20/22/24 x Ubuntu/Windows. Single `ci-success` job for branch protection.
 
-#### Build Debugging
+### Environment Variables
 
-- Check `dist/` output structure
-- Verify CommonJS exports are correctly transformed
-- Ensure type definitions are generated
+Access via typed getter functions in `src/env/`. Each module exports a pure getter. Test rewiring via `#env/rewire` (`setEnv`, `clearEnv`, `resetEnv`) without modifying `process.env`.
 
-### Notes
+### Working Directory
 
-- This is a core utilities library - maintain high quality and test coverage
-- Breaking changes impact all Socket.dev tools - coordinate carefully
-- Cross-platform compatibility is critical
-- Performance matters - this code runs frequently in security tools
+NEVER use `process.chdir()` — use `{ cwd }` options and absolute paths instead.

From fe38194bb1abd32e2351c43ead314586f4910b76 Mon Sep 17 00:00:00 2001
From: Test User <john.david.dalton@gmail.com>
Date: Thu, 9 Apr 2026 17:11:28 -0400
Subject: [PATCH 4/5] chore: trim quality-scan skill to 63 lines (was 625)

---
 .claude/skills/quality-scan/SKILL.md | 644 ++-------------------------
 1 file changed, 39 insertions(+), 605 deletions(-)

diff --git a/.claude/skills/quality-scan/SKILL.md b/.claude/skills/quality-scan/SKILL.md
index 7b895a5..d204ca2 100644
--- a/.claude/skills/quality-scan/SKILL.md
+++ b/.claude/skills/quality-scan/SKILL.md
@@ -1,625 +1,59 @@
 ---
 name: quality-scan
-description: Validates structural consistency, cleans up junk files (SCREAMING_TEXT.md, temp files), and performs comprehensive quality scans across codebase to identify critical bugs, logic errors, caching issues, and workflow problems. Spawns specialized agents for targeted analysis and generates prioritized improvement tasks. Use when improving code quality, before releases, or investigating issues.
+description: Runs comprehensive quality scans across the codebase using specialized agents to identify critical bugs, logic errors, caching issues, and workflow problems. Use when improving code quality, before releases, or investigating issues.
 ---
 
 # quality-scan
 
 <task>
-Your task is to perform comprehensive quality scans across the codebase using specialized agents to identify critical bugs, logic errors, caching issues, and workflow problems. Before scanning, clean up junk files (SCREAMING_TEXT.md files, temporary test files, etc.) to ensure a clean and organized repository. Generate a prioritized report with actionable improvement tasks.
+Performs comprehensive quality scans across the codebase, cleaning up junk files
+and spawning specialized agents for targeted analysis. Generates a prioritized
+report with actionable improvement tasks.
 </task>
 
-<context>
-**What is Quality Scanning?**
-Quality scanning uses specialized AI agents to systematically analyze code for different categories of issues. Each agent type focuses on specific problem domains and reports findings with severity levels and actionable fixes.
-
-**Scan Types Available:**
-1. **critical** - Crashes, security vulnerabilities, resource leaks, data corruption
-2. **logic** - Algorithm errors, edge cases, type guards, off-by-one errors
-3. **cache** - Cache staleness, race conditions, invalidation bugs
-4. **workflow** - Build scripts, CI issues, cross-platform compatibility
-5. **workflow-optimization** - CI optimization checks (build-required conditions on cached builds)
-6. **security** - GitHub Actions workflow security (zizmor scanner)
-7. **documentation** - README accuracy, outdated docs, missing documentation, junior developer friendliness
-
-**Why Quality Scanning Matters:**
-- Catches bugs before they reach production
-- Identifies security vulnerabilities early
-- Improves code quality systematically
-- Provides actionable fixes with file:line references
-- Prioritizes issues by severity for efficient remediation
-- Cleans up junk files for a well-organized repository
-
-**Agent Prompts:**
-All agent prompts are embedded in `reference.md` with structured <context>, <instructions>, <pattern>, and <output_format> tags following Claude best practices.
-</context>
-
 <constraints>
-**CRITICAL Requirements:**
-- Read-only analysis (no code changes during scan)
-- 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
-- All findings must include suggested fixes
-
-**Do NOT:**
-- Fix issues during scan (analysis only - report findings)
-- Skip critical scan types without user permission
-- Report findings without file/line references
-- Proceed if codebase has uncommitted changes (warn but continue)
-
-**Do ONLY:**
-- Run enabled scan types in priority order (critical → logic → cache → workflow)
-- Generate structured findings with severity levels
-- Provide actionable improvement tasks with specific code changes
-- Report statistics and coverage metrics
-- Deduplicate findings across scans
+- Analysis phase is read-only; do not fix issues during scan.
+- Must complete all enabled scans before reporting.
+- Findings prioritized by severity (Critical > High > Medium > Low).
+- All findings must include file:line references and suggested fixes.
+- Run `pnpm test` after each fix iteration.
+- Cap at 5 iterations; stop and report if issues persist.
 </constraints>
 
-<instructions>
-
-## Process
-
-Execute the following phases sequentially to perform comprehensive quality analysis.
-
-### Phase 1: Validate Environment
-
-<prerequisites>
-Verify the environment before starting scans:
-</prerequisites>
-
-```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>
-
----
-
-### Phase 2: Update Dependencies
-
-<action>
-Update dependencies in the current repository only:
-</action>
-
-**Update Process:**
-
-```bash
-pnpm run update
-```
-
-<validation>
-**Expected Results:**
-- Dependencies updated in current repository
-- Report number of packages updated
-- Continue with scan even if update fails
-
-**Track for reporting:**
-- Packages updated: N
-- Update status: Success/Failed (with warning)
-
-**Important:** Only update dependencies in the current repository. Do NOT attempt to update sibling repositories as this is out of scope and could have unintended side effects.</validation>
-
----
-
-### Phase 2b: Install External Tools (zizmor)
-
-<action>
-Install zizmor for GitHub Actions security scanning using version that meets repository's minimumReleaseAge policy.
-</action>
-
-<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>
-
----
-
-### Phase 3: Repository Cleanup
-
-<action>
-Clean up junk files and organize the repository before scanning:
-</action>
-
-**Cleanup Tasks:**
-
-1. **Remove SCREAMING_TEXT.md files** (all-caps .md files) that are NOT:
-   - Inside `.claude/` directory
-   - Inside `docs/` directory
-   - Named `README.md`, `LICENSE`, or `SECURITY.md`
-
-2. **Remove temporary test files** in wrong locations:
-   - `.test.mjs` or `.test.mts` files outside `test/` or `__tests__/` directories
-   - Temp files: `*.tmp`, `*.temp`, `.DS_Store`, `Thumbs.db`
-   - Editor backups: `*~`, `*.swp`, `*.swo`, `*.bak`
-   - Test artifacts: `*.log` files in root or package directories (not logs/)
-
-```bash
-# Find SCREAMING_TEXT.md files (all caps with .md extension)
-find . -type f -name '*.md' \
-  ! -path './.claude/*' \
-  ! -path './docs/*' \
-  ! -name 'README.md' \
-  ! -name 'LICENSE' \
-  ! -name 'SECURITY.md' \
-  | grep -E '/[A-Z_]+\.md$'
-
-# Find test files in wrong locations
-find . -type f \( -name '*.test.mjs' -o -name '*.test.mts' \) \
-  ! -path '*/test/*' \
-  ! -path '*/__tests__/*' \
-  ! -path '*/node_modules/*'
-
-# Find temp files
-find . -type f \( \
-  -name '*.tmp' -o \
-  -name '*.temp' -o \
-  -name '.DS_Store' -o \
-  -name 'Thumbs.db' -o \
-  -name '*~' -o \
-  -name '*.swp' -o \
-  -name '*.swo' -o \
-  -name '*.bak' \
-\) ! -path '*/node_modules/*'
-
-# Find log files in wrong places (not in logs/ or build/ directories)
-find . -type f -name '*.log' \
-  ! -path '*/logs/*' \
-  ! -path '*/build/*' \
-  ! -path '*/node_modules/*' \
-  ! -path '*/.git/*'
-```
-
-<validation>
-**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
-
-**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>
-
----
-
-### Phase 4: Structural Validation
-
-<action>
-Run automated consistency checker to validate architectural patterns:
-</action>
-
-**Validation Tasks:**
-
-Run the consistency checker to validate monorepo structure:
-
-```bash
-node scripts/check-consistency.mjs
-```
-
-**The consistency checker validates:**
-1. **Required files** - README.md, package.json existence
-2. **Vitest configurations** - Proper mergeConfig usage
-3. **Test scripts** - Correct test patterns per package type
-4. **Coverage scripts** - Coverage setup where appropriate
-5. **External tools** - external-tools.json format validation
-6. **Build output structure** - Standard build/{mode}/out/Final/ layout
-7. **Package.json structure** - Standard fields and structure
-8. **Workspace dependencies** - Proper workspace:* and catalog: usage
-
-<validation>
-**Expected Results:**
-- Errors: 0 (any errors should be reported as Critical findings)
-- Warnings: 2 or fewer (expected deviations documented in checker)
-- Info: Multiple info messages are normal (observations only)
-
-**If errors found:**
-1. Report as Critical findings in the final report
-2. Include file:line references from checker output
-3. Suggest fixes based on checker recommendations
-4. Continue with remaining scans
-
-**If warnings found:**
-- Report as Low findings (these are expected deviations)
-- Document in final report under "Structural Validation"
-
-**Track for reporting:**
-- Number of packages validated
-- Number of errors/warnings/info messages
-- Any architectural pattern violations
-
-</validation>
-
----
-
-### Phase 5: Determine Scan Scope
-
-<action>
-Ask user which scans to run:
-</action>
-
-**Default Scan Types** (run all unless user specifies):
-1. **critical** - Critical bugs (crashes, security, resource leaks)
-2. **logic** - Logic errors (algorithms, edge cases, type guards)
-3. **cache** - Caching issues (staleness, races, invalidation)
-4. **workflow** - Workflow problems (scripts, CI, git hooks)
-5. **workflow-optimization** - CI optimization (build-required checks for cached builds)
-6. **security** - GitHub Actions security (template injection, cache poisoning, etc.)
-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 4 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.
-
-<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
-
-If user requests non-existent scan type, report error and suggest valid types.
-</validation>
-
----
-
-### Phase 6: Execute Scans
-
-<action>
-For each enabled scan type, spawn a specialized agent using Task tool:
-</action>
-
-```typescript
-// Example: Critical scan
-Task({
-  subagent_type: "general-purpose",
-  description: "Critical bugs scan",
-  prompt: `${CRITICAL_SCAN_PROMPT_FROM_REFERENCE_MD}
-
-[IF monorepo] Focus on packages/ directories and root-level scripts/.
-[IF single package] Focus on src/, lib/, and scripts/ directories.
-
-Report findings in this format:
-- File: path/to/file.mts:lineNumber
-- Issue: Brief description
-- Severity: Critical/High/Medium/Low
-- Pattern: Code snippet
-- Trigger: What input triggers this
-- Fix: Suggested fix
-- Impact: What happens if triggered
-
-Scan systematically and report all findings. If no issues found, state that explicitly.`
-})
-```
-
-**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
-4. Capture findings from agent response
-5. Parse and categorize results
-
-**Execution Order:** Run scans sequentially in priority order:
-- critical (highest priority)
-- logic
-- cache
-- workflow (lowest priority)
-
-**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
-
-<validation>
-For each scan completion:
-- Verify agent completed without errors
-- Extract findings from agent output
-- Parse into structured format (file, issue, severity, fix)
-- Track scan coverage (files analyzed)
-</validation>
-
----
-
-### Phase 7: Aggregate Findings
-
-<action>
-Collect all findings from agents and aggregate:
-</action>
-
-```typescript
-interface Finding {
-  file: string           // "src/path/to/file.mts:89" or "packages/pkg/src/file.mts:89"
-  issue: string          // "Potential null pointer access"
-  severity: "Critical" | "High" | "Medium" | "Low"
-  scanType: string       // "critical"
-  pattern: string        // Code snippet showing the issue
-  trigger: string        // What causes this issue
-  fix: string            // Suggested code change
-  impact: string         // What happens if triggered
-}
-```
-
-**Deduplication:**
-- Remove duplicate findings across scans (same file:line, same issue)
-- Keep the finding from the highest priority scan
-- Track which scans found the same issue
-
-**Prioritization:**
-- Sort by severity: Critical → High → Medium → Low
-- Within same severity, sort by scanType priority
-- Within same severity+scanType, sort alphabetically by file path
-
-<validation>
-**Checkpoint:** Verify aggregation:
-- Total findings count
-- Breakdown by severity (N critical, N high, N medium, N low)
-- Breakdown by scan type
-- Duplicate removal count (if any)
-</validation>
-
----
-
-### Phase 8: Generate Report
-
-<action>
-Create structured quality report with all findings:
-</action>
-
-```markdown
-# Quality Scan Report
-
-**Date:** YYYY-MM-DD
-**Repository:** [repository name]
-**Scans:** [list of scan types run]
-**Files Scanned:** N
-**Findings:** N critical, N high, N medium, N low
-
-## Dependency Updates
-
-**Status:** N packages updated
-**Result:** Success/Failed
-
-## Structural Validation
-
-**Consistency Checker Results:**
-- Packages validated: 12
-- Errors: N (reported as Critical below)
-- Warnings: N (reported as Low below)
-- Info: N observations
-
-**Validation Categories:**
-✓ Required files
-✓ Vitest configurations
-✓ Test scripts
-✓ Coverage scripts
-✓ External tools
-✓ Build output structure
-✓ Package.json structure
-✓ Workspace dependencies
-
-## Critical Issues (Priority 1) - N found
-
-### src/path/to/file.mts:89
-- **Issue**: [Description of critical issue]
-- **Pattern**: [Problematic code snippet]
-- **Trigger**: [What triggers this issue]
-- **Fix**: [Suggested fix]
-- **Impact**: [Impact description]
-- **Scan**: critical
-
-## High Issues (Priority 2) - N found
-
-[Similar format for high severity issues]
-
-## Medium Issues (Priority 3) - N found
-
-[Similar format for medium severity issues]
-
-## Low Issues (Priority 4) - N found
-
-[Similar format for low severity issues]
-
-## Scan Coverage
-
-- **Dependency updates**: N packages updated
-- **Structural validation**: [IF consistency checker exists] N packages validated, N architectural patterns checked
-- **Critical scan**: N files analyzed in [src/ or packages/]
-- **Logic scan**: N files analyzed
-- **Cache scan**: N files analyzed (if applicable)
-- **Workflow scan**: N files analyzed (package.json, scripts/, .github/)
-
-## Recommendations
-
-1. Address N critical issues immediately before next release
-2. Review N high-severity logic errors in patch application
-3. Schedule N medium issues for next sprint
-4. Low-priority items can be addressed during refactoring
-
-## No Findings
-
-[If a scan found no issues, list it here:]
-- Critical scan: ✓ Clean
-- Logic scan: ✓ Clean
-```
-
-**Output Report:**
-1. Display report to console (user sees it)
-2. Offer to save to file (optional): `reports/quality-scan-YYYY-MM-DD.md`
-
-<validation>
-**Report Quality Checks:**
-- All findings include file:line references
-- All findings include suggested fixes
-- Findings are grouped by severity
-- Scan coverage statistics included
-- Recommendations are actionable
-</validation>
-
----
-
-### Phase 9: Complete
-
-<completion_signal>
-```xml
-<promise>QUALITY_SCAN_COMPLETE</promise>
-```
-</completion_signal>
-
-<summary>
-Report these final metrics to the user:
-
-**Quality Scan Complete**
-========================
-✓ Dependency updates: N packages updated
-✓ Structural validation: [IF applicable] N packages validated (N errors, N warnings)
-✓ Repository cleanup: N junk files removed
-✓ Scans completed: [list of scan types]
-✓ Total findings: N (N critical, N high, N medium, N low)
-✓ Files scanned: N
-✓ Report generated: Yes
-✓ Scan duration: [calculated from start to end]
-
-**Dependency Update Summary:**
-- Packages updated: N
-- Update status: Success/Failed
-
-**Structural Validation Summary:**
-[IF consistency checker exists]
-- Packages validated: N
-- Consistency errors: N (included in critical findings)
-- Consistency warnings: N (included in low findings)
-- Architectural patterns checked: N
-
-**Repository Cleanup Summary:**
-- SCREAMING_TEXT.md files removed: N
-- Temporary test files removed: N
-- Temp/backup files removed: N
-- Log files cleaned up: N
-
-**Critical Issues Requiring Immediate Attention:**
-- N critical issues found
-- Review report above for details and fixes
-
-**Next Steps:**
-1. Address critical issues immediately
-2. Review high-severity findings
-3. Schedule medium/low issues appropriately
-4. Re-run scans after fixes to verify
-
-All findings include file:line references and suggested fixes.
-</summary>
-
-</instructions>
-
-## Success Criteria
-
-- ✅ `<promise>QUALITY_SCAN_COMPLETE</promise>` output
-- ✅ All enabled scans completed without errors
-- ✅ Findings prioritized by severity (Critical → Low)
-- ✅ All findings include file:line references
-- ✅ Actionable suggestions provided for all findings
-- ✅ Report generated with statistics and coverage metrics
-- ✅ Duplicate findings removed
-
-## Scan Types
+## Phases
 
-See `reference.md` for detailed agent prompts with structured tags:
+1. **Validate Environment** — `git status`; follow `_shared/env-check.md`.
+2. **Update Dependencies** — `pnpm run update`; continue even if it fails.
+3. **Install External Tools** — See `_shared/security-tools.md` for zizmor; use `pnpm run setup`.
+4. **Repository Cleanup** — Glob for junk files (SCREAMING_TEXT.md, temp files, editor backups); confirm before deletion.
+5. **Structural Validation** — `pnpm run check`; report errors as Critical findings.
+6. **Determine Scan Scope** — Ask user: all scans, critical only, or custom selection. CI mode runs all automatically.
+7. **Execute Scans** — Spawn agents sequentially via Agent tool using prompts from [reference.md](reference.md). Apply `agents/code-reviewer.md` rules for code scans, `agents/security-reviewer.md` for security scans.
+8. **Aggregate Findings** — Deduplicate across scans, sort by severity then scan type.
+9. **Generate Report** — Summary table by severity + scan type, display to user.
+10. **Fix All Issues** — Apply fixes from Critical to Low; read each file before editing.
+11. **Run Tests** — `pnpm test`; revert and exit iteration on failure.
+12. **Commit Fixes** — Stage and commit with summary of fixed issue counts.
+13. **Iteration Decision** — Zero issues = done; otherwise loop back to Phase 7.
 
-- **critical-scan** - Null access, promise rejections, race conditions, resource leaks
-- **logic-scan** - Off-by-one errors, type guards, edge cases, algorithm correctness
-- **cache-scan** - Invalidation, key generation, memory management, concurrency
-- **workflow-scan** - Scripts, package.json, git hooks, CI configuration
-- **workflow-optimization-scan** - CI optimization checks (build-required on installation steps with checkpoint caching)
-- **security-scan** - GitHub Actions workflow security (runs zizmor scanner)
-- **documentation-scan** - README accuracy, outdated examples, incorrect package names, missing documentation, junior developer friendliness (beginner-friendly explanations, troubleshooting, getting started guides)
+## Available Scans
 
-All agent prompts follow Claude best practices with <context>, <instructions>, <pattern>, <output_format>, and <quality_guidelines> tags.
+See [reference.md](reference.md) for detailed agent prompts. Scan types:
 
-## Commands
+- **critical** — Crashes, security vulnerabilities, resource leaks, data corruption
+- **logic** — Algorithm errors, edge cases, type guards, off-by-one errors
+- **cache** — Cache staleness, race conditions, invalidation bugs
+- **workflow** — Build scripts, CI issues, cross-platform compatibility
+- **security** — GitHub Actions workflow security via zizmor + credential exposure
+- **documentation** — README accuracy, outdated docs, missing documentation
 
-This skill is self-contained. No external commands needed.
+## Scan Scope
 
-## Context
+Primary: `src/`, `scripts/`, `test/`, `.github/workflows/`
+Excluded: `node_modules/`, `dist/`, `.pnpm-store/`
 
-This skill provides systematic code quality analysis by:
-- Spawning specialized agents for targeted analysis
-- Using Task 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)
+## Error Recovery
 
-For detailed agent prompts with best practices structure, see `reference.md`.
+- **Scan agent failure**: Log warning, continue remaining scans.
+- **Test failure after fixes**: `git restore .`, report failures, exit iteration.
+- **Git commit failure**: Display error, ask user to resolve.

From 670f2f0cc99814327d14a1c8a87f150891a1e9ad Mon Sep 17 00:00:00 2001
From: Test User <john.david.dalton@gmail.com>
Date: Thu, 9 Apr 2026 17:16:32 -0400
Subject: [PATCH 5/5] fix: format CLAUDE.md with oxfmt

---
 CLAUDE.md | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index efb78a8..3bfccb6 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -128,13 +128,13 @@ All shared standards (git, testing, code style, cross-platform, CI) defined in s
 
 **Terminal Symbols** (from `@socketsecurity/lib/logger` LOG_SYMBOLS):
 
-| Symbol | Color | Meaning |
-|--------|-------|---------|
-| ✓ | green | Success |
-| ✗ | red | Error |
-| ⚠ | yellow | Warning |
-| ℹ | blue | Info |
-| → | cyan | Step/progress |
+| Symbol | Color  | Meaning       |
+| ------ | ------ | ------------- |
+| ✓      | green  | Success       |
+| ✗      | red    | Error         |
+| ⚠      | yellow | Warning       |
+| ℹ      | blue   | Info          |
+| →      | cyan   | Step/progress |
 
 Color the icon only, not the message. Use `yoctocolors-cjs` (not the ESM `yoctocolors`). Use emojis sparingly; prefer colored text symbols for terminal compatibility.