feat: implement multi-destination extraction with fan-out support (#8)

Adds ability to extract files to multiple destinations simultaneously using repeated --to flags:
- Made --to option repeatable to accept multiple destination paths
- Added PathNormalizer.deduplicate() for destination deduplication
- Implemented fail-fast validation across all destinations before copying
- Added per-destination success output showing files extracted to each location
- Extended clean mode to support multi-destinations

* chore: mark multi-destination extraction complete with 571 tests passing

Updated roadmap and Phase 3 documentation to mark 012-multi-destination-extraction as complete with 571 tests passing. Added changelog entry for v1.8.0 release. Updated spec status from Draft to Complete. Added Type Change Checklist to tasks template and optional Validation Steps section to spec template.

Author: csjones

.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