Document computer science significance of separator-merge

Capture the profound implications of multi-separator merge capability
for solving cross-domain entity tracking and parallel task coordination.

## Key Insights

Multi-separator merge solves fundamental CS problems:

1. **Cross-domain entity tracking** - Same logical entity across
   multiple physical representations (docs, tests, code)

2. **Parallel task coordination** - Multiple people working on
   different aspects of the same feature

3. **Completeness verification** - Automatic gap analysis via
   separator markers

4. **Namespace unification** - Virtual unified namespace across
   different naming conventions

## Theoretical Foundation

Analogous to:
- Virtual File Systems (VFS) - unify different storage types
- Database Views - logical view over physical tables
- Graph Homomorphism - map different graphs to canonical form

## Practical Impact

- Living completeness map of codebase
- Instant visibility into what exists where
- Automation-friendly (CI/CD checks for completeness)
- Reduces cognitive load
- Makes gaps visible through absence

## Files

- docs/main.trait.separator-merge.cs-significance.md
- docs/main.trait.separator-merge.todo.md (updated status)

This documents WHY the feature is powerful, not just what it does.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: marcnulu

docs/main.trait.separator-merge.cs-significance.md

@@ -0,0 +1,313 @@
+# Computer Science Significance: Multi-Separator Merge
+
+## The Core Problem
+
+Software projects have **logical entities** that exist across **multiple physical representations**:
+
+```
+Logical Entity: "UserService.Authentication"
+
+Physical Representations:
+- docs/UserService.Authentication.md         (documentation)
+- tests/UserService.Authentication.test.js   (test suite)
+- src/UserService_Authentication.cpp         (implementation)
+- docs/UserService.Authentication.api.yaml   (API spec)
+```
+
+**Problem:** These are the SAME entity conceptually, but different naming conventions (dots, underscores, paths) make them appear unrelated.
+
+## The Solution: Separator Merge
+
+Multi-separator merge creates a **virtual unified namespace** across the codebase:
+
+```bash
+recur tree UserService.Authentication --sep "." --sep "_" --sep "/"
+```
+
+**Result:** All representations appear under one logical node.
+
+## Computer Science Problems Solved
+
+### 1. **Cross-Domain Entity Tracking**
+
+**Problem:** Tracking the same logical entity across documentation, tests, and code.
+
+**Before:** Manual correlation
+```bash
+# Find docs
+find docs/ -name "*Authentication*"
+
+# Find code
+find src/ -name "*Authentication*"
+
+# Mentally correlate: "Are these the same thing?"
+```
+
+**After:** Automatic unification
+```bash
+recur tree UserService.Authentication --sep "." --sep "_" --show-sep
+
+# Shows:
+#   readme.md [.]        # docs
+#   test.js [.]          # tests
+#   impl.cpp [_]         # code
+#   api.yaml [.]         # spec
+```
+
+### 2. **Parallel Task Coordination**
+
+**Scenario:** Multiple people working on the same feature:
+- **Alice:** Writing documentation (`UserService.Authentication.md`)
+- **Bob:** Implementing code (`UserService_Authentication.cpp`)
+- **Charlie:** Writing tests (`UserService.Authentication.test.js`)
+
+**Problem:** How to track completeness across parallel work?
+
+**Solution:** Gap analysis in real-time
+```bash
+recur files "UserService.Authentication.**" --sep "." --sep "_" --show-sep
+
+# Instantly see:
+#   ✅ Documentation [.]  - Alice done
+#   ❌ Tests [.]         - Charlie in progress (no file yet)
+#   ✅ Implementation [_] - Bob done
+```
+
+### 3. **Completeness Verification**
+
+**Problem:** "Is this feature fully implemented?"
+
+Requires checking:
+- ✅ Documented?
+- ✅ Tested?
+- ✅ Implemented?
+- ✅ API spec exists?
+
+**Before:** Manual checklist
+
+**After:** Query completeness
+```bash
+recur tree Feature.X --sep "." --sep "_" --show-sep
+
+# Missing markers = incomplete aspects
+# If only [.] markers → documented but not coded
+# If only [_] markers → coded but not documented
+```
+
+### 4. **Namespace Unification**
+
+**Problem:** Different languages/conventions use different separators:
+- JavaScript: `UserService.Authentication`  (dots)
+- Python: `user_service_authentication`     (underscores)
+- C++: `UserService::Authentication`        (colons)
+- Paths: `UserService/Authentication`       (slashes)
+
+**Solution:** Virtual unified namespace
+```bash
+recur tree UserService --sep "." --sep "_" --sep "::" --sep "/"
+
+# All naming conventions appear under one hierarchy
+```
+
+## Theoretical Foundation
+
+This is analogous to:
+
+### 1. **Virtual File Systems (VFS)**
+Like how Linux VFS unifies different filesystem types under one interface, separator-merge unifies different naming conventions under one hierarchy.
+
+### 2. **Database Views**
+Creates a "view" across multiple physical storage representations (files) into one logical schema (hierarchy).
+
+### 3. **Graph Homomorphism**
+Maps different graph structures (dot-separated, underscore-separated) into one canonical graph structure.
+
+## Practical Applications
+
+### Use Case 1: Feature Development Workflow
+
+**Team working on new feature: "PaymentGateway.Stripe"**
+
+```bash
+# Day 1: Start feature
+recur tree PaymentGateway.Stripe --sep "." --sep "_" --show-sep
+# Empty or partial
+
+# Day 5: Check progress
+recur tree PaymentGateway.Stripe --sep "." --sep "_" --show-sep
+
+# Shows:
+#   spec.md [.]          ✅ Spec written
+#   readme.md [.]        ✅ Docs written
+#   test.py [_]          ✅ Tests exist
+#   impl.py [_]          ✅ Code exists
+#   integration.test [.] ❌ Missing!
+
+# Action: "We need integration tests"
+```
+
+### Use Case 2: Code Review Completeness
+
+**Before merging PR:**
+```bash
+recur files "NewFeature.**" --sep "." --sep "_" --show-sep
+
+# Check:
+# - Does every [_] (code file) have a corresponding [.] (doc)?
+# - Does every public API have a test?
+# - Gap analysis automatic
+```
+
+### Use Case 3: Refactoring Safety
+
+**Renaming feature: "OldName" → "NewName"**
+
+```bash
+# Find ALL representations
+recur files "OldName.**" --sep "." --sep "_" --sep "::"
+
+# Shows every file across all domains
+# Ensures you don't miss docs when renaming code
+```
+
+### Use Case 4: Cross-Language Projects
+
+**Project with multiple languages:**
+- Frontend: `user.service.ts` (TypeScript, dots)
+- Backend: `user_service.py` (Python, underscores)
+- Docs: `user.service.md` (Markdown, dots)
+
+```bash
+recur tree user.service --sep "." --sep "_"
+
+# Unified view of the entire feature across languages
+```
+
+## The "Named Entity" Problem
+
+**Named entities** in software:
+- Class names
+- Module names
+- Feature names
+- API endpoints
+
+**Problem:** Same entity, multiple representations
+
+**Example:**
+```
+Entity: "EmailValidator"
+
+Representations:
+- EmailValidator.cs          (C# class)
+- email_validator.py         (Python module)
+- email-validator.md         (Documentation)
+- emailValidator.test.js     (Test file)
+- email_validator_spec.yaml  (Spec)
+```
+
+**Question:** "How complete is EmailValidator?"
+
+**Answer (before):** Search 5 different ways, manually correlate
+
+**Answer (now):** One query
+```bash
+recur tree EmailValidator --sep "." --sep "_" --sep "-" --show-sep
+```
+
+## Parallel Task Coordination
+
+**Scenario:** Distributed team, async work
+
+**Monday:**
+```bash
+recur tree Feature.X --sep "." --sep "_" --show-sep
+# Shows: readme.md [.]
+# Status: Only docs exist
+```
+
+**Tuesday:**
+```bash
+recur tree Feature.X --sep "." --sep "_" --show-sep
+# Shows:
+#   readme.md [.]
+#   impl.rs [_]
+# Status: Code added
+```
+
+**Wednesday:**
+```bash
+recur tree Feature.X --sep "." --sep "_" --show-sep
+# Shows:
+#   readme.md [.]
+#   impl.rs [_]
+#   test.jl [.]
+# Status: Tests added
+```
+
+**Complete when all domains present!**
+
+## Why This Matters
+
+### 1. **Reduces Cognitive Load**
+Don't need to remember:
+- "Where did I document this?"
+- "What's the source code filename?"
+- "Did someone write tests?"
+
+One query answers all.
+
+### 2. **Enables Automation**
+CI/CD can check:
+```bash
+# Fail PR if no tests for new code
+recur files "NewFeature.**" --sep "." --sep "_" --show-sep | \
+  grep "\[_\]" | \
+  while read file; do
+    # Check if corresponding [.] test exists
+  done
+```
+
+### 3. **Makes Gaps Visible**
+Missing files = missing work
+Instantly visible through absence
+
+### 4. **Supports Polyglot Codebases**
+Different languages, one view
+
+## Computer Science Concepts Applied
+
+1. **Abstraction:** Separators are implementation details
+2. **Virtualization:** Create unified view over heterogeneous storage
+3. **Graph Theory:** Merge multiple graphs into canonical form
+4. **Set Theory:** Union of separator-specific file sets
+5. **Relational Algebra:** JOIN operation across domains
+
+## The Power: Emergent Properties
+
+**Individual features:**
+- Multi-separator query: Useful
+- Normalization: Useful
+- Show-sep markers: Useful
+
+**Combined:** Transforms codebase navigation
+
+**Emergent capability:** **Living completeness map**
+
+You can see, at any moment:
+- What exists where
+- What's missing
+- Who's working on what (by domain)
+- Is this feature "done"?
+
+## Conclusion
+
+Multi-separator merge solves the **cross-domain entity tracking problem** - a fundamental challenge in modern software development where logical entities span multiple physical representations with incompatible naming conventions.
+
+**Impact:**
+- ✅ Better coordination across parallel tasks
+- ✅ Automatic completeness verification
+- ✅ Reduced cognitive load
+- ✅ Enables new automation patterns
+- ✅ Makes gaps visible instantly
+
+**This is why it's powerful.**

docs/main.trait.separator-merge.todo.md

@@ -33,12 +33,12 @@ recur files "main.command.**" --sep "." --sep "_" --sep-replace-default "."
 ## Implementation Phases
 - [x] Phase 1: Documentation + failing tests + placeholder code
 - [x] Phase 2: Implement trait and basic multi-separator support ✅ COMPLETE!
-- [ ] Phase 3: Implement --sep-replace-default normalization logic
-- [ ] Phase 4: Implement --show-sep display logic
+- [x] Phase 3: Implement --sep-replace-default normalization logic ✅ COMPLETE!
+- [x] Phase 4: Implement --show-sep display logic ✅ COMPLETE!
 - [ ] Phase 5: Enhanced help examples showing multi-separator usage patterns
 
 ## Current Status
-**Phase 2 COMPLETE** - Multi-separator merging is WORKING!
+**Phase 4 COMPLETE** - Show-sep markers working! Gap analysis enabled!
 
 Core functionality delivered:
 - Multiple `--sep` flags accepted