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

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

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 0a8b17c..b00f868 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -17,7 +17,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:
       fail-fast: false
       lint-script: 'pnpm run lint --all'
diff --git a/.github/workflows/provenance.yml b/.github/workflows/provenance.yml
index 7a6731c..b53e57f 100644
--- a/.github/workflows/provenance.yml
+++ b/.github/workflows/provenance.yml
@@ -27,7 +27,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 }}
       dist-tag: ${{ inputs.dist-tag }}
diff --git a/.github/workflows/weekly-update.yml b/.github/workflows/weekly-update.yml
index bbc76c9..f78dece 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 }}
 
@@ -290,7 +290,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 c098c583755005d33ca990c0b73b381e57051a96 Mon Sep 17 00:00:00 2001
From: jdalton <john.david.dalton@gmail.com>
Date: Thu, 9 Apr 2026 13:50:19 -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 b53e57f..245773f 100644
--- a/.github/workflows/provenance.yml
+++ b/.github/workflows/provenance.yml
@@ -19,6 +19,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
@@ -33,5 +38,8 @@ jobs:
       dist-tag: ${{ inputs.dist-tag }}
       package-name: '@socketregistry/packageurl-js'
       publish-script: 'publish:ci'
+      publish-without-sfw: ${{ inputs.publish-without-sfw }}
       setup-script: 'ci:validate'
       use-trusted-publishing: true
+    secrets:
+      SOCKET_API_KEY: ${{ secrets.SOCKET_API_KEY }}

From e5581e0b27eadd30a1f1d5030b63861e144da35a Mon Sep 17 00:00:00 2001
From: jdalton <john.david.dalton@gmail.com>
Date: Thu, 9 Apr 2026 16:47:56 -0400
Subject: [PATCH 3/5] chore: trim CLAUDE.md and audit skills

Reduce CLAUDE.md from ~16KB to ~6KB by removing:
- Verbose emoji/output tutorial with code examples
- Redundant sections (FILE SYSTEM AS STATE, SELF-IMPROVEMENT, ROLE, EVOLUTION)
- Tutorial-like TypeScript patterns Claude already knows
- Detailed test helper docs and directory trees
- "Why this matters" explanations and repeated bullets
- Debugging section with generic advice

Fix security-scan SKILL.md description to use third-person convention
("Runs" instead of "Run").
---
 .claude/skills/security-scan/SKILL.md |   2 +-
 CLAUDE.md                             | 376 +++++---------------------
 2 files changed, 67 insertions(+), 311 deletions(-)

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 4053023..a0306ec 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -2,167 +2,87 @@
 
 **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
-- **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
+- Identify users by git credentials; use their actual name, never "the user"
+- Use "you/your" when speaking directly; use names when referencing contributions
 
 ## PRE-ACTION PROTOCOL
 
 **MANDATORY**: Review CLAUDE.md before any action. No exceptions.
 
-- 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 before the next
-- When pointed to existing code as a reference: study it before building — working code is a better spec than any description
-- Work from raw error data, not theories — if a bug report has no error output, ask for it
+- Before ANY structural refactor on a file >300 LOC: remove dead code first, commit separately
+- Multi-file changes: phases of ≤5 files, verify each before the next
+- Study existing code before building — working code is a better spec than any description
+- Work from raw error data, not theories
 - On "yes", "do it", or "go": execute immediately, no plan recap
 
 ## VERIFICATION PROTOCOL
 
-**MANDATORY**: Before claiming any task is complete:
-
-1. Run the actual command — execute the script, run the test, check the output
+1. Run the actual command — execute, don't assume
 2. State what you verified, not just "looks good"
-3. **FORBIDDEN**: Claiming "Done" when any test output shows failures, or characterizing incomplete/broken work as complete
-4. If type-check or lint is configured, run it and fix ALL errors before reporting done
-5. Re-read every file modified; confirm nothing references something that no longer exists
+3. **FORBIDDEN**: Claiming "Done" when tests show failures
+4. Run type-check/lint if configured; fix ALL errors before reporting done
+5. Re-read every modified file; confirm nothing references removed items
 
 ## CONTEXT & EDIT SAFETY
 
-- After 10+ messages: re-read any file before editing it — do not trust remembered contents
-- Read files >500 LOC in chunks using offset/limit; never assume one read captured the whole file
-- Before every edit: re-read the file. After every edit: re-read to confirm the change applied correctly
-- When renaming anything, search separately for: direct calls, type references, string literals, dynamic imports, re-exports, test files — one grep is not enough
-- Tool results over 50K characters are silently truncated — if search returns suspiciously few results, narrow scope and re-run
-- For tasks touching >5 files: use sub-agents with worktree isolation to prevent context decay
+- After 10+ messages: re-read files before editing
+- Read files >500 LOC in chunks
+- Before every edit: re-read. After every edit: re-read to confirm
+- When renaming: search direct calls, type refs, string literals, dynamic imports, re-exports, tests
+- Tool results over 50K chars are silently truncated — narrow scope and re-run if results seem incomplete
+- For tasks touching >5 files: use sub-agents with worktree isolation
 
 ## JUDGMENT PROTOCOL
 
-- If the user's request is based on a misconception, say so before executing
-- If you spot a bug adjacent to what was asked, flag it: "I also noticed X — want me to fix it?"
-- You are a collaborator, not just an executor
+- Flag misconceptions before executing
+- Flag adjacent bugs: "I also noticed X — want me to fix it?"
 
 ## SCOPE PROTOCOL
 
-- Do not add features, refactor, or make improvements beyond what was asked
-- Try the simplest approach first; if architecture is actually flawed, flag it and wait for approval before restructuring
-- When asked to "make a plan," output only the plan — no code until given the go-ahead
+- Do not add features or improvements beyond what was asked
+- Simplest approach first; flag architectural flaws and wait for approval
 
 ## COMPLETION PROTOCOL
 
-- **NEVER claim done with something 80% complete** — finish 100% before reporting
-- When a multi-step change doesn't immediately show gains, commit and keep iterating — don't revert
-- If one approach fails, fix forward: analyze why, adjust, rebuild, re-measure — not `git checkout`
-- After EVERY code change: build, test, verify, commit. This is a single atomic unit
-- Reverting is a last resort after exhausting forward fixes — and requires explicit user approval
-
-## FILE SYSTEM AS STATE
-
-The file system is working memory. Use it actively:
-
-- Write intermediate results and analysis to files in `.claude/`
-- Use `.claude/` for plans, status tracking, and cross-session context
-- When debugging, save logs and outputs to files for reproducible verification
-- Don't hold large analysis in context — write it down, reference it later
-
-## SELF-IMPROVEMENT
-
-- 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
+- Finish 100% before reporting — never claim done at 80%
+- Fix forward, don't revert (reverting requires explicit user approval)
+- After EVERY code change: build, test, verify, commit as one atomic unit
 
 ## SELF-EVALUATION
 
-- Before calling anything done: present two views — what a perfectionist would reject vs. what a pragmatist would ship
-- After fixing a bug: explain why it happened
-- If a fix doesn't work after two attempts: stop, re-read the relevant section top-down, state where the mental model was wrong, propose something fundamentally different
-- If asked to "step back" or "going in circles": drop everything, rethink from scratch
+- Present two views before calling done: what a perfectionist would reject vs. what a pragmatist would ship
+- If a fix fails twice: stop, re-read top-down, state where the mental model was wrong
 
 ## 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?"
+- Offer to checkpoint before risky changes
+- Flag files >400 LOC for potential splitting
 
 ## ABSOLUTE RULES
 
-- Never create files unless necessary
-- Always prefer editing existing files
+- Never create files unless necessary; 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
-
-Principal Software Engineer: production code, architecture, reliability, ownership.
-
-## EVOLUTION
-
-If user repeats instruction 2+ times, ask: "Should I add this to CLAUDE.md?"
+- 🚨 **NEVER use `npx`, `pnpm dlx`, or `yarn dlx`** — use `pnpm exec` or `pnpm run`
 
 ## 📚 SHARED STANDARDS
 
 **Canonical reference**: `../socket-registry/CLAUDE.md`
 
-All shared standards (git, testing, code style, cross-platform, CI) defined in socket-registry/CLAUDE.md.
-
-**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
+- 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)
+- Dependencies: After `package.json` edits, run `pnpm install`
+- Backward Compatibility: 🚨 FORBIDDEN to maintain — actively remove when encountered
 - Work Safeguards: MANDATORY commit + backup branch before bulk changes
 - Safe Deletion: Use `safeDelete()` from `@socketsecurity/lib/fs` (NEVER `fs.rm/rmSync` or `rm -rf`)
 - HTTP Requests: NEVER use `fetch()` — use `httpJson`/`httpText`/`httpRequest` from `@socketsecurity/lib/http-request`
 
 ---
 
-## 📝 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):
-
-- 📦 Packages
-- 💡 Ideas/tips
-- 🚀 Launch/deploy/excitement
-- 🎉 Major success/celebration
+## EMOJI & OUTPUT STYLE
 
-**General Philosophy**:
-
-- 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
+**Terminal symbols** (from `@socketsecurity/lib/logger` LOG_SYMBOLS): ✓ (green), ✗ (red), ⚠ (yellow), ℹ (blue), → (cyan). Color the icon only, not the message. Use `yoctocolors-cjs` (not ESM `yoctocolors`). Avoid emoji overload.
 
 ---
 
@@ -170,228 +90,64 @@ import colors from 'yoctocolors-cjs'
 
 ### Architecture
 
-TypeScript implementation of [Package URL specification](https://github.com/package-url/purl-spec) - Compiled to CommonJS for deployment
-
-**Core Structure**:
-
-- **Main**: `src/package-url.ts` - Main exports and API
-- **Parser**: Core parsing logic for purl strings
-- **Normalizer**: Type-specific normalization
-- **Validator**: Input validation and sanitization
-- **Types**: Type-specific handling (npm, pypi, maven, etc.)
-- **Build**: `dist/` - CommonJS output
+TypeScript implementation of [Package URL spec](https://github.com/package-url/purl-spec) (ECMA-427), compiled to CommonJS.
 
-**Features**: Full purl spec compliance, high-performance parsing, TypeScript type safety, type-specific normalization, CommonJS-only deployment
+- `src/package-url.ts` — main exports and API
+- `src/purl-types/` — type-specific handlers (npm, pypi, maven, etc.)
+- `src/error.js` — PurlError
+- `dist/` — CommonJS build output
 
 ### Commands
 
-- **Build**: `pnpm build` (production build)
-- **Watch**: `pnpm build --watch` (dev mode with 68% faster incremental builds)
+- **Build**: `pnpm build` (`pnpm build --watch` for dev)
 - **Test**: `pnpm test`
 - **Type check**: `pnpm type`
 - **Lint**: `pnpm lint`
 - **Check all**: `pnpm check`
 - **Fix**: `pnpm fix`
-- **Coverage**: `pnpm cover`
-
-**Development tip:** Use `pnpm build --watch` for 68% faster rebuilds (9ms vs 27ms). Incremental builds use esbuild's context API for in-memory caching.
+- **Coverage**: `pnpm cover` (must maintain 100%)
 
 ## Agents & Skills
 
-- `/security-scan` — runs AgentShield + zizmor security audit
-- `/quality-scan` — comprehensive code quality analysis
+- `/security-scan` — AgentShield + zizmor security audit
+- `/quality-scan` — code quality analysis with specialized agents
 - `/quality-loop` — scan and fix iteratively
 - Agents: `code-reviewer`, `security-reviewer`, `refactor-cleaner` (in `.claude/agents/`)
 - Shared subskills in `.claude/skills/_shared/`
-- Pipeline state tracked in `.claude/ops/queue.yaml`
-
-### PURL Standards
-
-#### Specification Compliance
-
-- Maintain strict compliance with purl spec
-- Test against reference implementations
-- Document any deviations/extensions
-- Never throw on valid purls per spec
-
-#### Performance Critical
-
-- High-performance parser for security scanning
-- Optimize for speed without sacrificing correctness
-- Benchmark changes against existing performance
-- Avoid unnecessary allocations
-
-### Error Handling - PurlError Patterns
-
-#### Error Types
-
-- **PurlError**: Parser-specific errors from `src/error.js`
-- **Error**: Generic argument validation only
-- **Catch parameters**: 🚨 MANDATORY `catch (e)` not `catch (error)`
-
-#### Error Message Format
-
-**Parser errors (PurlError)**: No period, lowercase (unless proper noun)
-
-- ✅ `throw new PurlError('missing required "pkg" scheme component')`
-- ✅ `throw new PurlError('npm "name" component cannot contain whitespace')`
-- ❌ `throw new PurlError('Missing required component.')`
-
-**Argument validation (Error)**: Period, sentence case
-
-- ✅ `throw new Error('JSON string argument is required.')`
-- ✅ `throw new Error('Invalid JSON string.', { cause: e })`
-- ❌ `throw new Error('json string required')`
-
-#### Error Message Patterns
 
-- **Component validation**: `{type} "{component}" component {violation}`
-  - Example: `cocoapods "name" component cannot contain whitespace`
-- **Required**: `"{component}" is a required component`
-- **Type requirements**: `{type} requires a "{component}" component`
-- **Qualifier**: `qualifier "{key}" {violation}`
-  - Example: `qualifier "tag_id" must not be empty`
-- **Parse failures**: `failed to parse as {format}` or `unable to decode "{component}" component`
-- **Character restrictions**: `cannot start with`, `cannot contain`
+### Error Handling — PurlError Patterns
 
-#### Error Requirements
+**PurlError** (parser errors): no period, lowercase start (unless proper noun)
+- Pattern: `{type} "{component}" component {violation}`
+- Required: `"{component}" is a required component`
+- Qualifier: `qualifier "{key}" {violation}`
 
-- Never throw on valid purls per spec
-- Include `{ cause: e }` when wrapping errors
-- No `process.exit()` in library code - throw errors instead
-  - **Exception**: CLI scripts in `scripts/` may use `process.exit()` for proper exit codes
-- No silent failures - throw proper errors
+**Error** (argument validation): period, sentence case
+- Example: `throw new Error('JSON string argument is required.')`
 
-### Comments
-
-Default to NO comments. Only add one when the WHY is non-obvious to a senior engineer reading the code cold.
+**Rules**: Never throw on valid purls. Include `{ cause: e }` when wrapping. No `process.exit()` in library code (OK in `scripts/`). Use `catch (e)` not `catch (error)`.
 
 ### TypeScript Patterns
 
-#### Import Style
-
-🚨 MANDATORY - Type imports must be on separate lines:
-
-- ✅ `import { parseScriptArgs, isQuiet } from './argv.mjs'`
-  `import type { ArgParserConfig } from './argv.mjs'`
-- ❌ `import { parseScriptArgs, isQuiet, type ArgParserConfig } from './argv.mjs'`
-
-#### 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
-
-#### Optional Properties
-
-With `exactOptionalPropertyTypes`, assign conditionally:
-
-- ✅ `if (value !== undefined) { this.prop = value }`
-- ❌ `this.prop = value ?? undefined`
-
-#### Index Signatures & Bracket Notation
-
-🚨 MANDATORY - Use bracket notation with index signatures:
-
-- ✅ `obj['prop']?.['method']`
-- ❌ `obj.prop.method`
-
-**Type assertions**: Use with bracket notation
-
-- ✅ `(obj['method'] as MethodType)?.(arg)`
-
-**Reusable types**: Define common patterns once
-
-- `ComponentEncoder = (_value: unknown) => string`
-- `ComponentNormalizer = (_value: string) => string | undefined`
-- `QualifiersValue = string | number | boolean | null | undefined`
+- 🚨 Type imports MUST be separate `import type` statements, never inline `type` in value imports
+- With `exactOptionalPropertyTypes`: assign conditionally, never `prop = value ?? undefined`
+- 🚨 Use bracket notation with index signatures: `obj['prop']?.['method']`
+- **NEVER** use `process.chdir()` — pass `{ cwd }` options instead
 
 ### Testing
 
-**Vitest Configuration**: This repo uses the shared vitest configuration patterns documented in `../socket-registry/CLAUDE.md` (see "Vitest Configuration Variants" section). Two configs available:
-
-- `.config/vitest.config.mts` - Main config (threads, isolate: false, concurrent: true)
-- `.config/vitest.config.isolated.mts` - Full process isolation (forks, isolate: true)
-
-#### Test File Naming Conventions
-
-🚨 **MANDATORY** - Use correct suffix based on isolation requirements:
-
-**Standard tests** (`*.test.mts`):
-
-- Run with thread pool, shared worker context
-- Fast execution, parallel within suites
-- Most tests should use this pattern
-- Example: `test/package-url.test.mts`
-
-**Isolated tests** (`*.isolated.test.mts`):
-
-- Run with fork pool, full process isolation
-- Required for tests that:
-  - Mock global objects (global.URL, global.process, etc.)
-  - Use vi.doMock() for dynamic module mocking
-  - Would cause race conditions in concurrent execution
-- Automatically detected and run separately by `scripts/test.mjs`
-- Example: `test/purl-global-mocking.isolated.test.mts`
-
-**When to use isolated tests**:
-
-- ✅ Modifying global.URL, global.process, or other globals
-- ✅ Tests that fail intermittently in concurrent mode
-- ❌ Standard property testing - use regular tests
-- ❌ HTTP mocking with nock - works fine in thread pool
-
-#### Test Structure
-
-- **Test files**: `test/` - All test files
-- **Spec compliance**: `test/purl-spec.test.mts` - Package URL spec tests
-- **Edge cases**: `test/purl-edge-cases.test.mts` - Edge cases and coverage
-- **Test helpers**: `test/utils/test-helpers.mts` - Reusable test utilities
-- **Assertion helpers**: `test/utils/assertions.mts` - Property validation helpers
-
-#### Test Helpers
-
-Test helpers in `test/utils/test-helpers.mts`:
-
-- `createTestPurl(type, name, opts?)` - Factory for PackageURL instances
-- `createTestFunction(returnValue?)` - Creates test functions with optional return values
-
-See file for usage examples.
-
-#### Running Tests
-
-- **All tests**: `pnpm test` or `pnpm test:unit`
-- **Specific file**: `pnpm test:unit path/to/file.test.js`
-- **🚨 NEVER USE `--` before test paths** - runs ALL tests
-- **Update snapshots**: `pnpm test:unit -u` or `pnpm testu`
-- **Coverage**: `pnpm cover` (must maintain 100%)
-
-#### Best Practices
-
-- **Use createTestPurl()**: Cleaner than `new PackageURL()` with many undefined params
-- **Maintain 100% coverage**: All code paths must be tested
-- **Spec compliance**: Strict compliance with purl spec required
-- **Test edge cases**: Include edge cases in `purl-edge-cases.test.mts`
-- **Performance**: Benchmark performance-sensitive changes
-
-### 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.
+**Vitest configs**: `.config/vitest.config.mts` (threads, shared) and `.config/vitest.config.isolated.mts` (forks, full isolation).
 
-- 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
+**File naming**: `*.test.mts` for standard tests; `*.isolated.test.mts` for tests that mock globals or use `vi.doMock()`.
 
-### CI Testing
+- `pnpm test` — all tests
+- `pnpm test:unit path/to/file.test.mts` — specific file
+- 🚨 **NEVER use `--` before test paths** — runs ALL tests
+- `pnpm testu` — update snapshots
+- `pnpm cover` — must maintain 100%
 
-- **🚨 MANDATORY**: `SocketDev/socket-registry/.github/workflows/ci.yml@<SHA>` with full SHA
-- **Format**: `@662bbcab1b7533e24ba8e3446cffd8a7e5f7617e # main`
-- **Docs**: `socket-registry/CLAUDE.md`, `socket-registry/docs/CI_TESTING_TOOLS.md`
+**Test style**: Functional tests over source scanning. Never read source files and assert on contents.
 
-### Debugging
+### CI
 
-- Use benchmarks to verify parsing speed
-- Test against purl-spec test suite
-- Test unusual but valid package URLs
+🚨 **MANDATORY**: Pin CI workflow refs to full SHA — `@<full-sha> # main`

From 06bc851c318c44336c93218bf340b1c67093f292 Mon Sep 17 00:00:00 2001
From: jdalton <john.david.dalton@gmail.com>
Date: Thu, 9 Apr 2026 17:08:29 -0400
Subject: [PATCH 4/5] chore: trim quality-scan skill and fix voice

---
 .claude/skills/quality-scan/SKILL.md     | 512 ++---------------------
 .claude/skills/quality-scan/reference.md | 101 +++++
 .claude/skills/updating/SKILL.md         |   2 +-
 3 files changed, 142 insertions(+), 473 deletions(-)

diff --git a/.claude/skills/quality-scan/SKILL.md b/.claude/skills/quality-scan/SKILL.md
index 2e393f6..a436fa8 100644
--- a/.claude/skills/quality-scan/SKILL.md
+++ b/.claude/skills/quality-scan/SKILL.md
@@ -6,50 +6,24 @@ description: Validates structural consistency, cleans up junk files (SCREAMING_T
 # 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.
+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 repository. Generate 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)
+- 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)
+- 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)
+- 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
@@ -60,419 +34,73 @@ All agent prompts are embedded in `reference.md` with structured <context>, <ins
 
 ## 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>
+Run `git status`. Working directory should be clean (warn if dirty but continue). Confirm on a valid branch with node modules installed.
 
 ---
 
 ### 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>
+Run `pnpm run update` for the current repository only. Report number of packages updated. Continue with scan even if update fails.
 
 ---
 
 ### 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/*'
-```
+Clean up junk files before scanning:
 
-<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
+1. **SCREAMING_TEXT.md files** (all-caps .md files) NOT inside `.claude/` or `docs/`, and NOT named `README.md`, `LICENSE`, or `SECURITY.md`
+2. **Misplaced test files** (`.test.mjs`/`.test.mts` outside `test/` or `__tests__/`)
+3. **Temp files** (`*.tmp`, `*.temp`, `.DS_Store`, `Thumbs.db`, `*~`, `*.swp`, `*.swo`, `*.bak`)
+4. **Stray log files** (`*.log` in root or source directories, not in `logs/` or `build/`)
 
-**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>
+For each file found: show the path, explain why it is junk, get user confirmation before deleting. Use `git rm` if tracked, `rm` if untracked.
 
 ---
 
 ### 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>
+Run `node scripts/check-consistency.mjs` if it exists. Report errors as Critical findings. Warnings are Low findings. Continue with remaining scans regardless.
 
 ---
 
 ### 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>
+Ask the user which scans to run. Default is all scan types.
+
+**Scan types:**
+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
 
 ---
 
 ### 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 enabled scan type, spawn a specialized agent via Task tool (subagent_type: "general-purpose"). Load the agent prompt template from `reference.md`, customize for repository context, and capture findings.
+
+Run scans sequentially in priority order: critical > logic > cache > workflow > workflow-optimization > security > documentation.
 
-**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>
+Each finding must include: file path with line number, issue description, severity, code pattern, trigger, suggested fix, and impact.
 
 ---
 
 ### 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>
+Collect all findings. Deduplicate (same file:line and issue across scans, keeping the highest-priority scan's version). Sort by severity descending, then by scan type priority, then alphabetically by file path.
 
 ---
 
 ### 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]
+Generate a structured report using the "Report Template" section in `reference.md`. The report must include: scan metadata, dependency update status, structural validation results, findings grouped by severity, scan coverage statistics, and prioritized recommendations.
 
-## 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>
+Display report to console and offer to save to `reports/quality-scan-YYYY-MM-DD.md`.
 
 ---
 
@@ -484,87 +112,27 @@ Create structured quality report with all findings:
 ```
 </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>
+Report final metrics: dependency update count, structural validation results, cleanup count, scans completed, total findings by severity, files scanned, and scan duration. See `reference.md` section "Completion Summary" for the full template.
 
 </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
+- `<promise>QUALITY_SCAN_COMPLETE</promise>` output
+- All enabled scans completed without errors
+- Findings prioritized by severity (Critical > Low)
+- All findings include file:line references and suggested fixes
+- Report generated with statistics and coverage metrics
+- Duplicate findings removed
 
 ## Scan Types
 
-See `reference.md` for detailed agent prompts with structured tags:
+See `reference.md` for detailed agent prompts:
 
 - **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)
+- **workflow-optimization-scan** - CI optimization checks (build-required on cached builds)
 - **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)
-
-All agent prompts follow Claude best practices with <context>, <instructions>, <pattern>, <output_format>, and <quality_guidelines> tags.
-
-## Commands
-
-This skill is self-contained. No external commands needed.
-
-## Context
-
-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)
-
-For detailed agent prompts with best practices structure, see `reference.md`.
+- **documentation-scan** - README accuracy, outdated examples, missing documentation
diff --git a/.claude/skills/quality-scan/reference.md b/.claude/skills/quality-scan/reference.md
index d6899aa..7ea3b58 100644
--- a/.claude/skills/quality-scan/reference.md
+++ b/.claude/skills/quality-scan/reference.md
@@ -1615,3 +1615,104 @@ Scan all README.md files in the repository and report all documentation inaccura
 - **Impact**: Users expect automatic behavior that doesn't exist
 ```
 
+
+---
+
+## Report Template
+
+Use this format when generating the Phase 8 quality scan report:
+
+```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:**
+- Errors: N (reported as Critical below)
+- Warnings: N (reported as Low below)
+- Info: N observations
+
+## 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
+
+[Same format as Critical]
+
+## Medium Issues (Priority 3) - N found
+
+[Same format as Critical]
+
+## Low Issues (Priority 4) - N found
+
+[Same format as Critical]
+
+## Scan Coverage
+
+- **Dependency updates**: N packages updated
+- **Structural validation**: N architectural patterns checked
+- **Critical scan**: N files analyzed
+- **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
+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
+```
+
+---
+
+## Completion Summary
+
+Report these final metrics when Phase 9 completes:
+
+```
+Quality Scan Complete
+========================
+- Dependency updates: N packages updated
+- Structural validation: 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]
+
+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
+```
diff --git a/.claude/skills/updating/SKILL.md b/.claude/skills/updating/SKILL.md
index 09ac330..64ca4f5 100644
--- a/.claude/skills/updating/SKILL.md
+++ b/.claude/skills/updating/SKILL.md
@@ -8,7 +8,7 @@ allowed-tools: Task, Skill, Bash, Read, Grep, Glob, Edit
 # updating
 
 <task>
-Your task is to update all dependencies in socket-packageurl-js: npm packages via `pnpm run update`, then sync upstream specs and check feature parity with the purl npm package, ensuring all builds and tests pass.
+Update all dependencies in socket-packageurl-js: npm packages via `pnpm run update`, then sync upstream specs and check feature parity with the purl npm package, ensuring all builds and tests pass.
 </task>
 
 <context>

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

---
 CLAUDE.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index a0306ec..a1c6b90 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -118,11 +118,13 @@ TypeScript implementation of [Package URL spec](https://github.com/package-url/p
 ### Error Handling — PurlError Patterns
 
 **PurlError** (parser errors): no period, lowercase start (unless proper noun)
+
 - Pattern: `{type} "{component}" component {violation}`
 - Required: `"{component}" is a required component`
 - Qualifier: `qualifier "{key}" {violation}`
 
 **Error** (argument validation): period, sentence case
+
 - Example: `throw new Error('JSON string argument is required.')`
 
 **Rules**: Never throw on valid purls. Include `{ cause: e }` when wrapping. No `process.exit()` in library code (OK in `scripts/`). Use `catch (e)` not `catch (error)`.