feat: implement multi-destination extraction with fan-out support

.specify/memory/roadmap.md

@@ -1,6 +1,6 @@
 # Product Roadmap: Subtree CLI
 
-**Version:** v1.7.0  
+**Version:** v1.8.0  
 **Last Updated:** 2025-11-30
 
 ## Vision & Goals
@@ -34,7 +34,7 @@ Simplify git subtree management through declarative YAML configuration with safe
 - ✅ Multi-Pattern Extraction (5 user stories, 439 tests)
 - ✅ Extract Clean Mode (5 user stories, 477 tests)
 - ✅ **Brace Expansion: Embedded Path Separators** (4 user stories, 526 tests)
-- ⏳ **Multi-Destination Extraction** — Fan-out to multiple `--to` paths
+- ✅ **Multi-Destination Extraction** (5 user stories, 571 tests) — Fan-out to multiple `--to` paths
 - ⏳ Lint Command — Configuration integrity validation
 
 ## Product-Level Metrics & Success Criteria
@@ -80,6 +80,7 @@ Simplify git subtree management through declarative YAML configuration with safe
 
 ## Change Log
 
+- **v1.8.0** (2025-11-30): Multi-Destination Extraction complete (012-multi-destination-extraction) with 571 tests; fan-out to multiple `--to` paths, fail-fast validation, clean mode parity, bulk support (MINOR — feature complete)
 - **v1.7.0** (2025-11-30): Brace Expansion complete (011-brace-expansion) with 526 tests; embedded path separators, cartesian product, bash pass-through semantics (MINOR — feature complete)
 - **v1.6.0** (2025-11-29): Added Brace Expansion and Multi-Destination Extraction to Phase 3; marked Multi-Pattern Extraction and Extract Clean Mode complete (MINOR — new features)
 - **v1.5.0** (2025-11-27): Roadmap refactored to multi-file structure; added Multi-Pattern Extraction and Extract Clean Mode to Phase 3 (MINOR — new features, structural improvement)

.specify/memory/roadmap/phase-3-advanced-operations.md

@@ -82,7 +82,7 @@ Enable portable configuration validation, selective file extraction with compreh
   - Nested braces, escaping, numeric ranges deferred to backlog
 - **Delivered**: All 4 user stories (basic expansion, multiple groups, pass-through, empty alternative errors), 526 tests passing
 
-### 6. Multi-Destination Extraction (Fan-Out) ⏳ PLANNED
+### 6. Multi-Destination Extraction (Fan-Out) ✅ COMPLETE
 
 - **Purpose & user value**: Allows extracting matched files to multiple destinations simultaneously (e.g., `--to Lib/ --to Vendor/`), enabling distribution of extracted files to multiple locations without repeated commands
 - **Success metrics**:
@@ -95,7 +95,10 @@ Enable portable configuration validation, selective file extraction with compreh
   - Fan-out semantics: N files × M destinations = N×M copy operations
   - Directory structure preserved at each destination
   - YAML schema: `to: ["path1/", "path2/"]` for persisted mappings
-  - Atomic per-destination: all files to one destination succeed or fail together
+  - Fail-fast validation: all destinations checked upfront before any writes
+  - PathNormalizer deduplicates equivalent paths (`Lib/`, `./Lib`, `Lib` → single destination)
+  - Backward compatible: single `--to` and existing YAML configs unchanged
+- **Delivered**: All 5 user stories (CLI multi-dest, persist arrays, clean mode, fail-fast, bulk support), 571 tests passing
 
 ### 7. Lint Command ⏳ PLANNED
 
@@ -116,7 +119,7 @@ Enable portable configuration validation, selective file extraction with compreh
   3. Multi-Pattern Extraction ✅
   4. Extract Clean Mode ✅
   5. Brace Expansion in Patterns ✅
-  6. Multi-Destination Extraction ⏳
+  6. Multi-Destination Extraction ✅
   7. Lint Command ⏳ (final Phase 3 feature)
 - **Rationale**: Brace Expansion and Multi-Destination extend pattern capabilities before Lint validates all operations
 - **Cross-phase dependencies**: Requires Phase 2 Add Command for subtrees to exist
@@ -127,7 +130,7 @@ This phase is successful when:
 - All seven features complete and tested
 - Extract supports multiple patterns and cleanup operations
 - Lint provides comprehensive integrity validation
-- 600+ tests pass on macOS and Ubuntu (currently 526, growing)
+- 600+ tests pass on macOS and Ubuntu (currently 571, growing)
 
 ## Risks & Assumptions
 
@@ -138,6 +141,7 @@ This phase is successful when:
 
 ## Phase Notes
 
+- 2025-11-30: Multi-Destination Extraction complete (012-multi-destination-extraction) with 571 tests; 5 user stories delivered
 - 2025-11-30: Brace Expansion complete (011-brace-expansion) with 526 tests; 4 user stories delivered
 - 2025-11-29: Added Brace Expansion and Multi-Destination Extraction features
 - 2025-11-29: Extract Clean Mode complete (010-extract-clean) with 477 tests; dry-run/preview mode deferred to Phase 5 backlog

.specify/templates/spec-template.md

@@ -113,3 +113,17 @@
 - **SC-002**: [Measurable metric, e.g., "System handles 1000 concurrent users without degradation"]
 - **SC-003**: [User satisfaction metric, e.g., "90% of users successfully complete primary task on first attempt"]
 - **SC-004**: [Business metric, e.g., "Reduce support tickets related to [X] by 50%"]
+
+## Validation Steps *(optional)*
+
+<!--
+  If this feature requires manual validation beyond automated tests, document the steps here.
+  Otherwise, explicitly state: "All validation covered by automated tests."
+
+  This section helps ensure quickstart.md or manual QA steps are planned upfront.
+-->
+
+- [ ] Step 1: [Manual validation step, e.g., "Run `command --flag` and verify output shows X"]
+- [ ] Step 2: [Manual validation step, e.g., "Create config with Y and verify behavior Z"]
+
+*Or state:* All validation covered by automated tests.

.specify/templates/tasks-template.md

@@ -249,3 +249,18 @@ With multiple developers:
 - Commit after each task or logical group
 - Stop at any checkpoint to validate story independently
 - Avoid: vague tasks, same file conflicts, cross-story dependencies that break independence
+
+---
+
+## Type Change Checklist
+
+When changing a field's type (e.g., `String?` → `[String]}`, `Int` → `Int?`), verify:
+
+- [ ] All `!= nil` checks updated to appropriate emptiness checks (e.g., `.isEmpty`)
+- [ ] All `guard let` bindings updated to new type
+- [ ] All comparisons updated (e.g., `== nil` → `.isEmpty`)
+- [ ] All initializers updated to match new type
+- [ ] Run `swift build` (or equivalent) to catch remaining issues
+- [ ] Update tests to use new type format
+
+**Rationale**: Type changes propagate through the codebase. Missing updates cause lint errors mid-implementation.

README.md

@@ -165,6 +165,17 @@ subtree extract --name mylib \
   --from "src/**/*.c" \
   --to vendor/
 
+# Multi-destination extraction (012) - fan-out to multiple locations
+subtree extract --name mylib \
+  --from "**/*.h" \
+  --to Lib/include/ \
+  --to Vendor/headers/
+
+# Combined: multi-pattern + multi-destination (cartesian product)
+subtree extract --name mylib \
+  --from "*.h" --from "*.c" \
+  --to Lib/ --to Vendor/
+
 # Brace expansion (011) - compact patterns with {alternatives}
 subtree extract --name mylib --from "*.{h,c,cpp}" --to Sources/
 subtree extract --name mylib --from "{src,test}/*.swift" --to Sources/
@@ -177,8 +188,8 @@ subtree extract --name crypto-lib \
 # With exclusions (applies to all patterns)
 subtree extract --name mylib --from "src/**/*.c" --to Sources/ --exclude "**/test/**"
 
-# Save multi-pattern mapping for future use
-subtree extract --name mylib --from "include/**/*.h" --from "src/**/*.c" --to vendor/ --persist
+# Save multi-destination mapping for future use
+subtree extract --name mylib --from "**/*.h" --to Lib/ --to Vendor/ --persist
 
 # Execute saved mappings from subtree.yaml
 subtree extract --name example-lib
@@ -193,6 +204,9 @@ Remove previously extracted files with checksum validation:
 # Clean specific files (validates checksums before deletion)
 subtree extract --clean --name mylib --from "src/**/*.c" --to Sources/
 
+# Clean from multiple destinations (012)
+subtree extract --clean --name mylib --from "**/*.h" --to Lib/ --to Vendor/
+
 # Clean all saved mappings for a subtree
 subtree extract --clean --name mylib
 
@@ -258,6 +272,7 @@ subtree validate --with-remote
   - `--persist` - Save mapping to subtree.yaml
   - `--force` - Overwrite git-tracked files / force delete modified files
   - `--clean` - Remove extracted files (validates checksums first)
+  - Multi-destination: Use `--to` multiple times for fan-out extraction
 
 - **`validate`** - Verify subtree integrity
   - `--name <name>` - Validate specific subtree
@@ -287,16 +302,28 @@ subtrees:
     squash: true                         # Default: true
     commit: 0123456789abcdef...          # Latest known commit
     extractions:                         # File extraction mappings
-      # Single pattern (legacy format)
+      # Single pattern, single destination (legacy format)
       - from: "docs/**/*.md"
         to: Docs/
-      # Multi-pattern (009) - array format
+      # Multi-pattern (009) - union extraction
       - from:
           - "include/**/*.h"
           - "src/**/*.c"
         to: vendor/
         exclude:
           - "**/test/**"
+      # Multi-destination (012) - fan-out to multiple locations
+      - from: "**/*.h"
+        to:
+          - Lib/include/
+          - Vendor/headers/
+      # Combined: multi-pattern + multi-destination
+      - from:
+          - "*.h"
+          - "*.c"
+        to:
+          - Lib/
+          - Vendor/
 ```
 
 ## Platform Compatibility