chore: rewrite constitution with CLI-focused principles and enforcement model

.specify/memory/roadmap/phase-1-foundation.md

@@ -0,0 +1,61 @@
+# Phase 1 — Foundation
+
+**Status:** COMPLETE  
+**Last Updated:** 2025-11-27
+
+## Goal
+
+Establish project infrastructure and configuration management. Delivers CLI skeleton, config schema, and init command as the foundation for all subsequent features.
+
+## Key Features
+
+### 1. CLI Bootstrap
+
+- **Purpose & user value**: Provides command-line interface skeleton with discoverable help system, enabling users to explore available commands and understand tool capabilities without external documentation
+- **Success metrics**:
+  - Command help accessible in <5 seconds via `subtree --help`
+  - All stub commands execute without crashing (exit code 0)
+  - CI pipeline runs tests on macOS + Ubuntu completing in <10 minutes
+- **Dependencies**: None
+- **Notes**: Includes test infrastructure (unit + integration test harness) and GitHub Actions CI
+
+### 2. Configuration Schema & Validation
+
+- **Purpose & user value**: Defines `subtree.yaml` structure and validation rules, enabling users to manage subtree dependencies declaratively with clear error messages when configuration is invalid
+- **Success metrics**:
+  - Valid configs parse successfully on first attempt when following docs
+  - Invalid configs produce clear, actionable error messages within 1 second
+  - 100% of format/constraint violations caught before git operations
+- **Dependencies**: CLI Bootstrap
+- **Notes**: Format-only validation (no network/git checks), supports glob patterns for extract mappings
+
+### 3. Init Command
+
+- **Purpose & user value**: Creates initial `subtree.yaml` configuration file at git repository root, providing starting point for declarative subtree management with overwrite protection
+- **Success metrics**:
+  - Initialization completes in <1 second
+  - Users successfully initialize on first attempt without documentation
+  - 100% of initialization attempts either succeed or fail with clear error
+- **Dependencies**: Configuration Schema & Validation
+- **Notes**: Works from any subdirectory, follows symlinks to find git root, atomic file operations for concurrent safety
+
+## Dependencies & Sequencing
+
+- **Local ordering**: CLI Bootstrap → Configuration Schema → Init Command
+- **Rationale**: Each feature builds on the previous; CLI provides entry point, schema defines config format, init creates the config file
+
+## Phase-Specific Metrics & Success Criteria
+
+This phase is successful when:
+- All three features are complete and tested on macOS 13+ and Ubuntu 20.04 LTS
+- Test infrastructure supports both unit tests and integration tests
+- CI pipeline validates all changes automatically
+
+## Risks & Assumptions
+
+- **Assumptions**: Swift 6.1 toolchain available on target platforms
+- **Risks & mitigations**: None significant for foundation phase
+
+## Phase Notes
+
+- 2025-10-27: Phase 1 complete with all features delivered

.specify/memory/roadmap/phase-2-core-operations.md

@@ -0,0 +1,67 @@
+# Phase 2 — Core Subtree Operations
+
+**Status:** COMPLETE  
+**Last Updated:** 2025-11-27
+
+## Goal
+
+Enable complete subtree lifecycle management with atomic commits. Delivers add, update, and remove commands that maintain synchronization between git repository state and configuration file.
+
+## Key Features
+
+### 1. Add Command (CLI-First)
+
+- **Purpose & user value**: Adds subtrees to repository via CLI flags in single atomic commits, creating config entries automatically and ensuring configuration always reflects repository state
+- **Success metrics**:
+  - Subtree addition completes in <10 seconds for typical repositories
+  - 100% of add operations produce single commit (subtree + config update)
+  - Users can add subtrees with minimal flags (only --remote required)
+  - Smart defaults reduce typing: name from URL, prefix from name, ref defaults to 'main'
+- **Dependencies**: Init Command
+- **Notes**: CLI-First workflow (flags create config entry), atomic commit-amend pattern, duplicate detection via config check (name OR prefix), squash enabled by default (--no-squash to disable)
+- **Delivered**: All 5 user stories implemented (MVP with smart defaults, override defaults, no-squash mode, duplicate prevention, error handling), 150 tests passing
+
+### 2. Update Command
+
+- **Purpose & user value**: Updates subtrees to latest versions with flexible commit strategies, enabling users to keep dependencies current with report-only mode for CI/CD safety checks
+- **Success metrics**:
+  - Update check (report mode) completes in <5 seconds
+  - Users understand update status without applying changes (exit code 5 if updates available)
+  - 100% of applied updates tracked in config with correct commit hash
+- **Dependencies**: Add Command
+- **Notes**: Report mode (no changes), current branch commits only, single-commit squashing option (--squash/--no-squash)
+- **Delivered**: All 5 user stories implemented (selective update with squash, bulk update --all, report mode for CI/CD, no-squash mode, error handling), tag-aware commit messages, atomic commit pattern
+
+### 3. Remove Command
+
+- **Purpose & user value**: Safely removes subtrees and updates configuration atomically, ensuring clean repository state and preventing orphaned configuration entries with idempotent behavior
+- **Success metrics**:
+  - Removal completes in <5 seconds
+  - 100% of remove operations produce single commit (removal + config update)
+  - Config entries removed atomically with subtree directory
+  - Idempotent: succeeds when directory already deleted (exit code 0)
+- **Dependencies**: Add Command
+- **Notes**: Single atomic commit for removal + config update, validates subtree exists before removal, smart detection for directory state with context-aware success messages
+- **Delivered**: All 2 user stories implemented (clean removal, idempotent removal), 191 tests passing, comprehensive error handling with exit codes 0/1/2/3
+
+## Dependencies & Sequencing
+
+- **Local ordering**: Add Command → Update Command / Remove Command (parallel development possible)
+- **Rationale**: Add establishes the atomic commit pattern used by Update and Remove
+- **Cross-phase dependencies**: Requires Phase 1 Init Command for config access
+
+## Phase-Specific Metrics & Success Criteria
+
+This phase is successful when:
+- All three commands complete with atomic commits (git + config in one commit)
+- Case-insensitive name lookup works across all commands
+- 191+ tests pass on macOS and Ubuntu
+
+## Risks & Assumptions
+
+- **Assumptions**: Git subtree command available in standard git distribution
+- **Risks & mitigations**: Git behavior varies across versions → target git 2.x+, integration tests catch issues
+
+## Phase Notes
+
+- 2025-10-29: Phase 2 complete with all features delivered (191 tests passing)

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

@@ -0,0 +1,105 @@
+# Phase 3 — Advanced Operations & Safety
+
+**Status:** ACTIVE  
+**Last Updated:** 2025-11-27
+
+## Goal
+
+Enable portable configuration validation, selective file extraction with comprehensive safety features, and configuration integrity checking.
+
+## Key Features
+
+### 1. Case-Insensitive Names & Validation ✅ COMPLETE
+
+- **Purpose & user value**: Enables flexible name matching for all commands (add, remove, update) while preventing duplicate names/prefixes across case variations, ensuring configs work portably across macOS (case-insensitive) and Linux (case-sensitive) filesystems
+- **Success metrics**:
+  - Users can remove/update subtrees without remembering exact case (e.g., `remove hello-world` matches `Hello-World`)
+  - 100% of case-variant duplicate names detected during add
+  - 100% of case-variant duplicate prefixes detected during add
+  - Configs portable across all platforms
+- **Dependencies**: Add Command, Remove Command, Update Command
+- **Notes**: Case-insensitive lookup for name matching, case-insensitive duplicate validation, stores original case in config
+
+### 2. Extract Command ✅ COMPLETE
+
+- **Purpose & user value**: Copies files from subtrees to project structure using glob patterns with smart overwrite protection, enabling selective integration of upstream files without manual copying
+- **Success metrics**:
+  - Ad-hoc extraction completes in <3 seconds for typical file sets
+  - Glob patterns match expected files with 100% accuracy
+  - Git-tracked files protected unless `--force` explicitly used
+- **Dependencies**: Add Command
+- **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
+
+- **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**:
+  - Users can specify multiple `--from` patterns in single command
+  - YAML config supports both string (legacy) and array (new) formats for backward compatibility
+  - Global `--exclude` patterns apply to all source patterns
+  - 100% backward compatible with existing single-pattern extractions
+- **Dependencies**: Extract Command
+- **Notes**: 
+  - 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)
+
+### 4. Extract Clean Mode ⏳ PLANNED
+
+- **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**:
+  - Files removed only when checksum matches source (safety by default)
+  - `--force` flag overrides checksum validation
+  - Empty directories pruned after file removal
+  - Works with both ad-hoc patterns and persisted mappings (bulk mode parity)
+- **Dependencies**: Extract Command, Multi-Pattern Extraction
+- **Notes**:
+  - `--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
+
+### 5. Lint Command ⏳ PLANNED
+
+- **Purpose & user value**: Validates subtree integrity and synchronization state offline and with remote checks, enabling users to detect configuration drift, missing subtrees, or desync between config and repository state
+- **Success metrics**:
+  - Offline validation completes in <2 seconds
+  - 100% of config/repository mismatches detected and reported clearly
+  - Repair mode fixes discrepancies without manual intervention
+  - Remote validation detects divergence from upstream within 10 seconds
+- **Dependencies**: Add Command
+- **Notes**: Renamed from "validate" for clarity, offline mode (commit hash checks), `--with-remote` for upstream comparison, `--repair` mode
+
+## Dependencies & Sequencing
+
+- **Local ordering**: 
+  1. Case-Insensitive Names ✅
+  2. Extract Command ✅
+  3. Multi-Pattern Extraction ⏳ (next)
+  4. Extract Clean Mode ⏳ (after multi-pattern, leverages array patterns)
+  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
+- **Cross-phase dependencies**: Requires Phase 2 Add Command for subtrees to exist
+
+## Phase-Specific Metrics & Success Criteria
+
+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
+
+## Risks & Assumptions
+
+- **Assumptions**: Users understand glob pattern syntax
+- **Risks & mitigations**: 
+  - Glob complexity → clear pattern validation errors, consider dry-run mode
+  - Accidental file deletion → checksum validation + `--force` gate
+
+## Phase Notes
+
+- 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-4-production-readiness.md

@@ -0,0 +1,56 @@
+# Phase 4 — Production Readiness
+
+**Status:** PLANNED  
+**Last Updated:** 2025-11-27
+
+## Goal
+
+Deliver production-grade packaging and polished user experience. Enables distribution via pre-built binaries and comprehensive documentation.
+
+## Key Features
+
+### 1. CI Packaging & Binary Releases
+
+- **Purpose & user value**: Automated release packaging with platform-specific binaries distributed via GitHub Releases, enabling users to install pre-built binaries without Swift toolchain
+- **Success metrics**:
+  - Release artifacts generated automatically on version tags
+  - Binaries available for macOS (arm64/x86_64) and Linux (x86_64/arm64)
+  - Users can install via single download + chmod command
+  - Swift artifact bundles include checksums for SPM integration
+- **Dependencies**: Lint Command (all commands complete)
+- **Notes**: GitHub Actions release workflow, artifact bundles for SPM, SHA256 checksums, installation instructions in releases
+
+### 2. Polish & UX Refinements
+
+- **Purpose & user value**: Comprehensive UX improvements including progress indicators, enhanced error messages, and documentation site, reducing friction for new users and improving troubleshooting experience
+- **Success metrics**:
+  - Long-running operations show progress indicators (no silent hangs)
+  - Error messages include suggested fixes 100% of the time
+  - New users complete first subtree add within 5 minutes using only docs
+  - Documentation site covers all commands with runnable examples
+- **Dependencies**: CI Packaging
+- **Notes**: Progress bars for git operations, emoji-prefixed messages throughout, comprehensive CHANGELOG, documentation site (GitHub Pages or similar), example repositories
+
+## Dependencies & Sequencing
+
+- **Local ordering**: CI Packaging → Polish & UX Refinements
+- **Rationale**: Distribution infrastructure before final polish
+- **Cross-phase dependencies**: Requires Phase 3 complete (all commands feature-complete)
+
+## Phase-Specific Metrics & Success Criteria
+
+This phase is successful when:
+- Pre-built binaries available for all target platforms
+- Documentation site live with comprehensive command reference
+- New users can install and use tool without source compilation
+
+## Risks & Assumptions
+
+- **Assumptions**: GitHub Actions sufficient for release automation
+- **Risks & mitigations**: 
+  - Cross-compilation complexity → use native runners per platform
+  - Documentation maintenance → generate from source where possible
+
+## Phase Notes
+
+- 2025-11-27: Initial phase file created from roadmap refactor