feat: add extract clean mode with checksum validation and bulk operations

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

@@ -1,7 +1,7 @@
 # Phase 3 — Advanced Operations & Safety
 
 **Status:** ACTIVE  
-**Last Updated:** 2025-11-27
+**Last Updated:** 2025-11-29
 
 ## Goal
 
@@ -31,7 +31,7 @@ Enable portable configuration validation, selective file extraction with compreh
 - **Notes**: Supports ad-hoc (`--from/--to`) and bulk (`--all`) modes, `--persist` for saving mappings, `--force` for overrides, directory structure preserved
 - **Delivered**: All 5 user stories (ad-hoc extraction, persistent mappings, bulk execution, overwrite protection, validation & errors), 411 tests passing
 
-### 3. Multi-Pattern Extraction ⏳ NEXT
+### 3. Multi-Pattern Extraction ✅ COMPLETE
 
 - **Purpose & user value**: Allows specifying multiple glob patterns in a single extraction, enabling users to gather files from multiple source directories (e.g., both `include/` and `src/`) into one destination without running multiple commands
 - **Success metrics**:
@@ -44,8 +44,11 @@ Enable portable configuration validation, selective file extraction with compreh
   - CLI: Repeated `--from` flags (native swift-argument-parser support)
   - YAML: Both `from: "pattern"` and `from: ["pattern1", "pattern2"]` supported
   - Excludes are global (apply to all patterns)
+  - Zero-match warnings for patterns that don't match any files
+  - Full relative path preservation (industry standard)
+- **Delivered**: All 5 user stories (multiple CLI patterns, backward-compatible YAML, persist arrays, global excludes, zero-match warnings), 439 tests passing
 
-### 4. Extract Clean Mode ⏳ PLANNED
+### 4. Extract Clean Mode ✅ COMPLETE
 
 - **Purpose & user value**: Removes previously extracted files from destination based on source glob patterns, enabling users to clean up extracted files when no longer needed or before re-extraction with different patterns
 - **Success metrics**:
@@ -58,8 +61,10 @@ Enable portable configuration validation, selective file extraction with compreh
   - `--clean` flag triggers removal mode (opposite of extraction)
   - Pattern matches files in source (subtree) directory
   - Corresponding files removed from destination directory
-  - Checksum validation prevents accidental deletion of modified files
-  - Bulk mode: `extract --clean --name foo` cleans all persisted mappings
+  - Checksum validation via `git hash-object` prevents accidental deletion of modified files
+  - Bulk mode: `extract --clean --name foo` or `--clean --all` for all subtrees
+  - Continue-on-error for bulk operations with failure summary
+- **Delivered**: All 5 user stories (ad-hoc clean, force override, bulk clean, multi-pattern, error handling), 477 tests passing
 
 ### 5. Lint Command ⏳ PLANNED
 
@@ -77,10 +82,10 @@ Enable portable configuration validation, selective file extraction with compreh
 - **Local ordering**: 
   1. Case-Insensitive Names ✅
   2. Extract Command ✅
-  3. Multi-Pattern Extraction ⏳ (next)
-  4. Extract Clean Mode ⏳ (after multi-pattern, leverages array patterns)
+  3. Multi-Pattern Extraction ✅
+  4. Extract Clean Mode ✅
   5. Lint Command ⏳ (final Phase 3 feature)
-- **Rationale**: Multi-pattern extraction is simpler and immediately useful; Clean mode benefits from multi-pattern support; Lint validates all previous operations
+- **Rationale**: Lint command validates all previous operations and completes Phase 3
 - **Cross-phase dependencies**: Requires Phase 2 Add Command for subtrees to exist
 
 ## Phase-Specific Metrics & Success Criteria
@@ -89,7 +94,7 @@ This phase is successful when:
 - All five features complete and tested
 - Extract supports multiple patterns and cleanup operations
 - Lint provides comprehensive integrity validation
-- 450+ tests pass on macOS and Ubuntu
+- 475+ tests pass on macOS and Ubuntu
 
 ## Risks & Assumptions
 
@@ -100,6 +105,7 @@ This phase is successful when:
 
 ## Phase Notes
 
+- 2025-11-29: Extract Clean Mode complete (010-extract-clean) with 477 tests; dry-run/preview mode deferred to Phase 5 backlog
 - 2025-11-27: Added Multi-Pattern Extraction and Extract Clean Mode features before Lint Command
 - 2025-10-29: Case-Insensitive Names added to Phase 3
 - 2025-10-28: Extract Command completed with 411 tests

.specify/memory/roadmap/phase-5-backlog.md

@@ -60,11 +60,12 @@ Post-1.0 enhancements for advanced workflows, improved onboarding, and enterpris
 
 ### 7. Extract Dry-Run Mode (`--dry-run` flag)
 
-- **Purpose & user value**: Preview extraction results without actually copying files
+- **Purpose & user value**: Preview extraction or clean results without modifying filesystem
 - **Success metrics**:
-  - Users can verify extraction plan (files matched, conflicts detected) without modifying filesystem
-- **Dependencies**: Extract Command
-- **Notes**: Shows file list with status indicators, conflict warnings, summary statistics
+  - Users can verify extraction plan (files matched, conflicts detected) without copying files
+  - Users can preview clean operation (files to delete, checksum status) without removing files
+- **Dependencies**: Extract Command, Extract Clean Mode
+- **Notes**: Shows file list with status indicators, conflict warnings, summary statistics. For clean mode, shows checksum validation results and would-be-deleted files
 
 ### 8. Extract Auto-Stage Mode (`--stage` flag)
 

README.md

@@ -176,6 +176,24 @@ subtree extract --name example-lib
 subtree extract --all
 ```
 
+### 🧹 Clean Extracted Files
+
+Remove previously extracted files with checksum validation:
+
+```bash
+# Clean specific files (validates checksums before deletion)
+subtree extract --clean --name mylib --from "src/**/*.c" --to Sources/
+
+# Clean all saved mappings for a subtree
+subtree extract --clean --name mylib
+
+# Clean all mappings for all subtrees
+subtree extract --clean --all
+
+# Force clean modified files (skips checksum validation)
+subtree extract --clean --force --name mylib --from "*.c" --to Sources/
+```
+
 ### ✅ Validate Subtree State
 
 Verify subtree integrity and synchronization:
@@ -222,14 +240,15 @@ subtree validate --with-remote
 - **`remove`** - Remove configured subtrees
   - `--name <name>` - Remove specific subtree
 
-- **`extract`** - Copy files from subtrees
+- **`extract`** - Copy or clean files from subtrees
   - `--name <name>` - Extract from specific subtree
   - `--from <pattern>` - Source glob pattern (repeatable for multi-pattern)
   - `--to <path>` - Destination path
   - `--exclude <pattern>` - Exclude pattern (repeatable)
   - `--all` - Execute all saved mappings
   - `--persist` - Save mapping to subtree.yaml
-  - `--force` - Overwrite git-tracked files
+  - `--force` - Overwrite git-tracked files / force delete modified files
+  - `--clean` - Remove extracted files (validates checksums first)
 
 - **`validate`** - Verify subtree integrity
   - `--name <name>` - Validate specific subtree