docs: streamline CLAUDE.md to reference canonical source

- Reduce from ~213 to ~119 lines (44% reduction)
- Reference socket-registry/CLAUDE.md for shared standards
- Keep only purl-specific error patterns and TypeScript patterns
- Maintain spec compliance and performance guidance

Author: jdalton

CLAUDE.md

@@ -1,212 +1,118 @@
 # CLAUDE.md
 
-🚨 **CRITICAL**: This file contains MANDATORY guidelines for Claude Code (claude.ai/code). You MUST follow these guidelines EXACTLY as specified. Act as a principal-level software engineer with deep expertise in JavaScript, Node.js, and package URL parsing.
+🚨 **MANDATORY**: Act as principal-level engineer with deep expertise in JavaScript, Node.js, and package URL parsing.
 
 ## 📚 SHARED STANDARDS
 
-**This project follows Socket's unified development standards.** For comprehensive guidelines on:
-- Code style (imports, sorting, __proto__ patterns, comments)
-- Git workflow (GitHub Actions, CI, commit messages)
-- Error handling standards and message patterns
-- Cross-platform compatibility
-- Testing best practices (Vitest memory optimization)
-- Dependency alignment
-- Changelog management
+**See canonical reference:** `../socket-registry/CLAUDE.md`
 
-**See the canonical reference:** `socket-registry/CLAUDE.md` (in sibling repository)
+For all shared Socket standards (git workflow, testing, code style, imports, sorting, error handling, cross-platform, CI, etc.), refer to socket-registry/CLAUDE.md.
 
-This file contains **Package URL (purl) specific** rules and patterns. When in doubt, consult socket-registry/CLAUDE.md first.
-
-## 🎯 YOUR ROLE
-
-You are a **Principal Software Engineer** responsible for production-quality code, architectural decisions, and system reliability.
-
-## 🔍 PRE-ACTION PROTOCOL
-
-- **🚨 MANDATORY**: Before ANY action, review both this file AND socket-registry/CLAUDE.md
-- Check before you act - ensure approach follows established patterns
-- No exceptions for code changes, commits, documentation, testing, file operations
-
-## 🛡️ ABSOLUTE RULES
-
-- 🚨 **NEVER** create files unless absolutely necessary
-- 🚨 **ALWAYS** prefer editing existing files
-- 🚨 **FORBIDDEN** to proactively create documentation files unless explicitly requested
-- 🚨 **REQUIRED** to do exactly what was asked - nothing more, nothing less
+---
 
-## 🏗️ ARCHITECTURE
+## 🏗️ PURL-SPECIFIC
 
-### TypeScript Implementation of Package URL Specification
-Parsing and constructing package URLs, compiled to CommonJS for deployment.
+### Architecture
+TypeScript implementation of [Package URL specification](https://github.com/package-url/purl-spec) - Compiled to CommonJS for deployment
 
-### Core Structure
-- **Main entry**: `src/package-url.ts` - Main exports and API
+**Core Structure**:
+- **Main**: `src/package-url.ts` - Main exports and API
 - **Parser**: Core parsing logic for purl strings
-- **Normalizer**: Normalization logic for different package types
+- **Normalizer**: Type-specific normalization
 - **Validator**: Input validation and sanitization
-- **Types**: Type-specific handling for npm, pypi, maven, etc.
-- **Build output**: `dist/` - CommonJS compilation output
-
-### Key Features
-- Full purl specification compliance
-- High-performance parsing with TypeScript type safety
-- Type-specific normalization
-- Comprehensive validation
-- Extensive test coverage
-- CommonJS-only deployment for maximum compatibility
+- **Types**: Type-specific handling (npm, pypi, maven, etc.)
+- **Build**: `dist/` - CommonJS output
 
-## ⚡ COMMANDS
+**Features**: Full purl spec compliance, high-performance parsing, TypeScript type safety, type-specific normalization, CommonJS-only deployment
 
-### Development Commands
+### Commands
 - **Build**: `pnpm build`
-- **Test**: `pnpm test`
-- **Test unit**: `pnpm test:unit`
+- **Test**: `pnpm test`, `pnpm test:unit`
 - **Type check**: `pnpm check:tsc`
 - **Lint**: `pnpm check:lint`
 - **Check all**: `pnpm check`
-- **Fix linting**: `pnpm check:lint:fix` or `pnpm fix`
+- **Fix**: `pnpm check:lint:fix` or `pnpm fix`
 - **Coverage**: `pnpm coverage`
 
-### Testing Best Practices
-- **🚨 NEVER USE `--` BEFORE TEST FILE PATHS** - Runs ALL tests!
-- **Test single file**: ✅ CORRECT: `pnpm test:unit path/to/file.test.js`
-  - ❌ WRONG: `pnpm test:unit -- path/to/file.test.js`
-- **Update snapshots**: `pnpm test:unit -u` or `pnpm testu`
-- **🚨 MANDATORY Coverage Requirements**: Before pushing commits, ensure test coverage is maintained or improved
-  - **Never decrease coverage**: All changes MUST maintain or increase existing coverage percentages
-  - **Check before push**: Run `pnpm run test` to verify coverage thresholds are met
-  - **Fix coverage drops**: If coverage decreases, add tests to restore or improve coverage before pushing
-  - **Rationale**: Declining coverage indicates untested code paths, which increases risk of bugs and regressions
-
-### CI Testing Infrastructure
-- **🚨 MANDATORY**: Use `SocketDev/socket-registry/.github/workflows/ci.yml@<SHA>` with full commit SHA (not @main)
-- **🚨 CRITICAL**: GitHub Actions require full-length commit SHAs. Format: `@662bbcab1b7533e24ba8e3446cffd8a7e5f7617e # main`
-- **Reusable workflows**: Socket-registry provides centralized, reusable workflows for lint/type-check/test/coverage
-- **Benefits**: Parallel execution, consistent configuration, cross-platform testing
-- **Documentation**: See `docs/CI_TESTING.md` and `socket-registry/docs/CI_TESTING_TOOLS.md`
-
-## 📋 PURL-SPECIFIC RULES
-
-### 1. Package URL Standards
-- Implements [Package URL specification](https://github.com/package-url/purl-spec)
+### PURL Standards
+
+#### Specification Compliance
 - Maintain strict compliance with purl spec
 - Test against reference implementations
-- Document any deviations or extensions
+- Document any deviations/extensions
+- Never throw on valid purls per spec
 
-### 2. Performance Critical
-- High-performance parser used in security scanning
+#### Performance Critical
+- High-performance parser for security scanning
 - Optimize for speed without sacrificing correctness
 - Benchmark changes against existing performance
 - Avoid unnecessary allocations
 
-### 3. Error Handling - PurlError Patterns
+### Error Handling - PurlError Patterns
 
 #### Error Types
-- **Custom error type**: Use `PurlError` from `src/error.js` for parser-specific errors
-- **Standard errors**: Use `Error` only for generic argument validation
-- **Catch parameters**: 🚨 MANDATORY - Use `catch (e)` not `catch (error)`
+- **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 ending period, lowercase start (unless proper noun)
-  - ✅ CORRECT: `throw new PurlError('missing required "pkg" scheme component')`
-  - ✅ CORRECT: `throw new PurlError('npm "name" component cannot contain whitespace')`
-  - ❌ WRONG: `throw new PurlError('Missing required component.')`
-- **Argument validation (Error)**: Ending period, sentence case
-  - ✅ CORRECT: `throw new Error('JSON string argument is required.')`
-  - ✅ CORRECT: `throw new Error('Invalid JSON string.', { cause: e })`
-  - ❌ WRONG: `throw new Error('json string required')`
+**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 components**: `"{component}" is a required component`
-- **Type-specific requirements**: `{type} requires a "{component}" component`
-- **Qualifier validation**: `qualifier "{key}" {violation}`
+- **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**: Use specific descriptions like `cannot start with`, `cannot contain`
+- **Character restrictions**: `cannot start with`, `cannot contain`
 
-#### Error Handling Requirements
-- **Spec compliance**: Never throw on valid purls per spec
-- **Error context**: Include `{ cause: e }` when wrapping underlying errors
-- **No process.exit()**: Never use `process.exit(1)` - throw errors instead
-- **No silent failures**: Never use `logger.error()` followed by `return` - throw proper errors
+#### Error Requirements
+- Never throw on valid purls per spec
+- Include `{ cause: e }` when wrapping errors
+- No `process.exit()` - throw errors
+- No silent failures - throw proper errors
 
-## 🎨 PURL-SPECIFIC CODE PATTERNS
+### TypeScript Patterns
 
-### File Structure
-- **File extensions**: `.ts` for TypeScript, `.js` for JavaScript, `.mjs` for ES modules
-- **Naming**: kebab-case (e.g., `package-url.ts`, `purl-type.ts`)
-- **Module headers**: 🚨 MANDATORY - All modules MUST have `@fileoverview` headers
+#### Optional Properties
+With `exactOptionalPropertyTypes`, assign conditionally:
+- ✅ `if (value !== undefined) { this.prop = value }`
+- ❌ `this.prop = value ?? undefined`
 
-### TypeScript Patterns
-- **Optional properties**: With `exactOptionalPropertyTypes`, assign conditionally
-  - ✅ CORRECT: `if (value !== undefined) { this.prop = value }`
-  - ❌ WRONG: `this.prop = value ?? undefined`
-
-### Index Signatures & Bracket Notation
-- **Access pattern**: 🚨 MANDATORY - Use bracket notation with index signatures
-  - ✅ CORRECT: `obj['prop']?.['method']`
-  - ❌ WRONG: `obj.prop.method`
-- **Type assertions**: Use with bracket notation
-  - ✅ CORRECT: `(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`
-
-## 🔧 GIT WORKFLOW
-
-### Commit Messages
-- **🚨 ABSOLUTELY FORBIDDEN**: NEVER add Claude Code attribution to commit messages
-  - ❌ WRONG: Adding "🤖 Generated with [Claude Code]..." or "Co-Authored-By: Claude"
-  - ✅ CORRECT: Write commit messages without any AI attribution or signatures
-  - **Rationale**: This is a professional project and commit messages should not contain AI tool attributions
-
-### Pre-Commit Quality Checks
-- **🚨 MANDATORY**: Always run these commands before committing:
-  - `pnpm fix` - Fix linting and formatting issues
-  - `pnpm check` - Run all checks (lint, type-check, tests)
-  - **Rationale**: Ensures code quality regardless of whether hooks run
-
-### Commit Strategy with --no-verify
-- **--no-verify usage**: Use `--no-verify` flag for commits that don't require pre-commit hooks
-  - ✅ **Safe to skip hooks**: GitHub Actions workflows (.github/workflows/), tests (test/), documentation (*.md), configuration files
-  - ❌ **Always run hooks**: Package source code (src/), published library code, parser implementations
-  - **Important**: Even when using `--no-verify`, you MUST still run `pnpm fix` and `pnpm check` manually first
-  - **Rationale**: Pre-commit hooks run linting and type-checking which are critical for library code but less critical for non-published files
-
-### Batch Commits Strategy
-- **When making many changes**: Break large changesets into small, logical commits
-- **First commit with tests**: Run full test suite (hooks) for the first commit only
-- **Subsequent commits with --no-verify**: Use `--no-verify` for follow-up commits
-- **Example workflow**:
-  1. Make all changes and ensure `pnpm fix && pnpm check` passes
-  2. Stage and commit core changes with hooks: `git commit -m "message"`
-  3. Stage and commit related changes: `git commit --no-verify -m "message"`
-  4. Stage and commit cleanup: `git commit --no-verify -m "message"`
-  5. Stage and commit docs: `git commit --no-verify -m "message"`
-- **Rationale**: Reduces commit time while maintaining code quality through initial validation
-
-## 🔍 DEBUGGING
-
-### Performance Testing
-- Use benchmarks to verify parsing speed
-- Test against purl-spec test suite
-- Test with unusual but valid package URLs
+#### Index Signatures & Bracket Notation
+🚨 MANDATORY - Use bracket notation with index signatures:
+- ✅ `obj['prop']?.['method']`
+- ❌ `obj.prop.method`
 
-## 📝 SCRATCH DOCUMENTS
+**Type assertions**: Use with bracket notation
+- ✅ `(obj['method'] as MethodType)?.(arg)`
 
-### Working Documents Directory
-- **Location**: `.claude/` directory (gitignored)
-- **Purpose**: Store scratch documents, planning notes, analysis reports, and temporary documentation
-- **🚨 CRITICAL**: NEVER commit files in `.claude/` to version control
-- **Examples of scratch documents**:
-  - Working notes and implementation plans
-  - Analysis reports from codebase investigations
-  - Temporary documentation and TODO lists
-  - Any files not intended for production use
+**Reusable types**: Define common patterns once
+- `ComponentEncoder = (_value: unknown) => string`
+- `ComponentNormalizer = (_value: string) => string | undefined`
+- `QualifiersValue = string | number | boolean | null | undefined`
 
----
+### Testing
+- **🚨 NEVER USE `--` before test paths** - runs ALL tests
+- **Test single file**: ✅ `pnpm test:unit path/to/file.test.js`
+- **Update snapshots**: `pnpm test:unit -u` or `pnpm testu`
+
+### CI Testing
+- **🚨 MANDATORY**: `SocketDev/socket-registry/.github/workflows/ci.yml@<SHA>` with full SHA
+- **Format**: `@662bbcab1b7533e24ba8e3446cffd8a7e5f7617e # main`
+- **Docs**: `docs/CI_TESTING.md`, `socket-registry/docs/CI_TESTING_TOOLS.md`
 
-**For all other standards not covered here, refer to `socket-registry/CLAUDE.md` (in sibling repository)**
+### Debugging
+- Use benchmarks to verify parsing speed
+- Test against purl-spec test suite
+- Test unusual but valid package URLs