ci: Add GitHub Action workflow for JSDoc analysis

Creates a workflow that:
- Triggers on JavaScript file changes in refactor-core branch
- Analyzes changed files for JSDoc coverage
- Reports on classes, functions, and existing documentation
- Ready to integrate with Claude API when configured

This sets up the infrastructure for P1.T011 (comprehensive JSDoc) to be completed automatically via GitHub Actions.

When CLAUDE_CODE_OAUTH_TOKEN is added to secrets, uncomment the Claude step to enable automatic PR creation with JSDoc enhancements.

Author: flyingrobots

.github/workflows/claude-jsdoc.yml

@@ -0,0 +1,63 @@
+name: Claude JSDoc Enhancement
+
+on:
+  push:
+    branches: [refactor-core]
+    paths:
+      - "**/*.js"
+      - "**/*.mjs"
+      - "starfleet/**/*.js"
+
+jobs:
+  analyze-jsdoc:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+      issues: write
+      id-token: write
+    
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+      
+      - name: Get changed files
+        id: changed-files
+        run: |
+          echo "Changed JavaScript files in this push:"
+          git diff --name-only HEAD^ HEAD | grep -E '\.(js|mjs)$' || echo "No JS files changed"
+          echo "files=$(git diff --name-only HEAD^ HEAD | grep -E '\.(js|mjs)$' | head -5 | tr '\n' ' ')" >> $GITHUB_OUTPUT
+
+      - name: Analyze JSDoc Coverage
+        if: steps.changed-files.outputs.files != ''
+        run: |
+          echo "📚 JSDoc Coverage Analysis for Changed Files"
+          echo "============================================"
+          for file in ${{ steps.changed-files.outputs.files }}; do
+            if [ -f "$file" ]; then
+              echo ""
+              echo "File: $file"
+              echo "Classes: $(grep -c "^class " "$file" || echo 0)"
+              echo "Functions: $(grep -c "^function \|^async function" "$file" || echo 0)"
+              echo "Existing JSDoc: $(grep -c "/\*\*" "$file" || echo 0)"
+            fi
+          done
+          echo ""
+          echo "This workflow detected changed JavaScript files."
+          echo "In production, Claude would analyze these and create a PR with JSDoc enhancements."
+
+      # Uncomment when Claude is configured:
+      # - name: Run Claude JSDoc Enhancement
+      #   if: steps.changed-files.outputs.files != ''
+      #   uses: anthropics/claude-code-action@v1
+      #   with:
+      #     claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+      #     prompt: |
+      #       Analyze these JavaScript files and add comprehensive JSDoc where missing:
+      #       ${{ steps.changed-files.outputs.files }}
+      #       
+      #       Follow the patterns from docs/decisions/000-javascript-not-typescript.md
+      #       Create a PR with the enhancements.
+      #     claude_args: '--allowed-tools "Read,Edit,MultiEdit,Bash(gh pr create:*)"'