feat(workflows): add duplicate detection and update documentation

## Duplicate Detection (Medium Priority Fix)

Added automatic duplicate detection in spec-create.yml:
- Validates that specification directory was actually created
- Checks Claude's comment for duplicate indicators
- Auto-closes issue with 'duplicate' label if duplicate detected
- Removes 'spec-request' label to prevent confusion
- Provides clear error message if creation failed for other reasons

This prevents duplicate issues from staying open with stale labels.

## Documentation Updates (CLAUDE.md)

Updated workflow documentation to reflect recent improvements:

1. **Supporting Workflows** - Added sync-labels.yml to the list
   - Documents automatic label synchronization after manual merges

2. **Workflow Data Flow** - Enhanced Flow A (spec creation)
   - Added duplicate detection validation step
   - Shows when issues are auto-closed for duplicates

3. **Workflow Data Flow** - Enhanced Flow B (implementation)
   - Documents atomic commits (implementation + metadata together)
   - Shows PR completeness validation in impl-merge.yml
   - Prevents partial merges with missing implementation files

4. **Decoupled Architecture** - Added benefits
   - Labels auto-synced after manual PR merges
   - Spec merge operations serialized to prevent race conditions

All workflow improvements from #3228 are now fully documented.

Related: #3228

Author: claude

.github/workflows/spec-create.yml

@@ -275,6 +275,41 @@ jobs:
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
+      - name: Validate specification was created (not duplicate)
+        if: steps.check.outputs.should_run == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          SPEC_ID: ${{ steps.extract.outputs.specification_id }}
+          ISSUE_NUM: ${{ github.event.issue.number }}
+        run: |
+          # Check if specification directory was actually created
+          if [ ! -d "plots/${SPEC_ID}" ]; then
+            echo "::warning::Specification directory not created - likely a duplicate"
+
+            # Get Claude's comment to find duplicate info
+            COMMENT=$(gh issue view "$ISSUE_NUM" --json comments -q '.comments[-1].body' 2>/dev/null || echo "")
+
+            if echo "$COMMENT" | grep -qi "duplicate\|exists\|already"; then
+              echo "::notice::Claude detected duplicate - closing issue"
+
+              gh label create "duplicate" --color "cfd3d7" \
+                --description "Duplicate specification" 2>/dev/null || true
+
+              gh issue edit "$ISSUE_NUM" --remove-label "spec-request" 2>/dev/null || true
+              gh issue edit "$ISSUE_NUM" --add-label "duplicate" 2>/dev/null || true
+              gh issue close "$ISSUE_NUM" --comment "**Duplicate detected:** Claude's analysis indicates this specification already exists. See previous comment for details."
+
+              exit 0  # Not an error, just a duplicate
+            fi
+
+            # If not a duplicate, something else failed
+            echo "::error::Specification creation failed for unknown reason"
+            gh issue comment "$ISSUE_NUM" --body "**Error:** Specification creation failed. Please check the [workflow logs](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}) for details."
+            exit 1
+          fi
+
+          echo "::notice::Specification directory created successfully"
+
       - name: Create Pull Request
         if: steps.check.outputs.should_run == 'true'
         id: pr

CLAUDE.md

@@ -637,6 +637,7 @@ spec-create.yml
     ├── Creates branch: specification/{specification-id}
     ├── Creates: plots/{specification-id}/specification.md
     ├── Creates: plots/{specification-id}/specification.yaml
+    ├── Validates: checks for duplicates (closes issue if duplicate detected)
     ├── Creates PR: specification/{specification-id} → main
     └── Posts: spec analysis comment (waits for approval)
     │
@@ -658,6 +659,7 @@ impl-generate.yml
     ├── Creates branch: implementation/{specification-id}/{library}
     ├── Generates implementation code
     ├── Tests with MPLBACKEND=Agg
+    ├── Commits implementation + metadata atomically (prevents partial PRs)
     ├── Uploads preview to GCS staging
     ├── Creates PR: implementation/{specification-id}/{library} → main
     └── Triggers impl-review.yml
@@ -669,6 +671,7 @@ impl-review.yml
     ├── Adds labels: quality:XX, ai-approved OR ai-rejected
     │
     ├── If APPROVED → triggers impl-merge.yml
+    │       ├── Validates PR completeness (blocks merge if implementation file missing)
     │       ├── Squash-merges PR to main
     │       ├── Creates metadata/{library}.yaml
     │       ├── Promotes GCS: staging → production
@@ -711,6 +714,7 @@ Issue ready for maintainer review
 | **ci-lint.yml** | Ruff linting on PR |
 | **ci-unittest.yml** | Unit tests on PR |
 | **sync-postgres.yml** | Syncs plots/ to database on push to main |
+| **sync-labels.yml** | Auto-syncs labels after manual PR merges (spec-ready, impl:*:done) |
 
 ### Decoupled Architecture
 
@@ -723,6 +727,7 @@ The new architecture separates specification and implementation processes:
 - **No merge conflicts** - Per-library metadata files
 - **Flexible triggers** - Labels for single, dispatch for bulk
 - **PostgreSQL synced on every merge to main**
+- **Labels auto-synced** - Manual PR merges automatically update issue labels
 
 **Branch naming:**
 - `specification/{specification-id}` - New specification PRs
@@ -731,6 +736,7 @@ The new architecture separates specification and implementation processes:
 **Concurrency:**
 - Global limit: max 3 implementation workflows simultaneously
 - `bulk-generate.yml` uses `max-parallel: 3` in matrix strategy
+- Spec merge operations are serialized (one at a time) to prevent race conditions
 
 ## GitHub Issue Labels