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
-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.
-
-**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 , , , and tags following Claude best practices.
-
-
**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 ,
-Verify the environment before starting scans:
-
-
-```bash
-git status
-```
-
-
-**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)
-
-
+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
-
-Update dependencies in the current repository only:
-
-
-**Update Process:**
-
-```bash
-pnpm run update
-```
-
-
-**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.
+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
-
-Clean up junk files and organize the repository before scanning:
-
-
-**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:
-
-**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
-
-
+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
-
-Run automated consistency checker to validate architectural patterns:
-
-
-**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
-
-
-**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
-
-
+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
-
-Ask user which scans to run:
-
-
-**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.
-
-
-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.
-
+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
-
-For each enabled scan type, spawn a specialized agent using Task tool:
-
-
-```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
-
-
-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)
-
+Each finding must include: file path with line number, issue description, severity, code pattern, trigger, suggested fix, and impact.
---
### Phase 7: Aggregate Findings
-
-Collect all findings from agents and aggregate:
-
-
-```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
-
-
-**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)
-
+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
-
-Create structured quality report with all findings:
-
-
-```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`
-
-
-**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
-
+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:
```
-
-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.
-
+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.
## Success Criteria
-- ✅ `QUALITY_SCAN_COMPLETE` 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
+- `QUALITY_SCAN_COMPLETE` 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 , , , , and 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/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/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
-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.
diff --git a/CLAUDE.md b/CLAUDE.md
index 4053023..a1c6b90 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 ", 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 ` for devDep binaries, or `pnpm run