Add forest system foundation and CLI infrastructure

Establishes the foundation for forest-based stack management with core types, operations interfaces, and CLI integration. Forests are named collections of worktrees that enable unified operations like split, merge, and conflict-preserving reroot across entire stacks.

## Files Changed

### Added (6 files)

- `src/erk/cli/commands/forest/README.md` - Comprehensive documentation for forest operations (split, merge, reroot)
- `src/erk/cli/commands/forest/__init__.py` - Forest command group (infrastructure ready for subcommands)
- `src/erk/core/forest_ops.py` - ForestOps interface with real/fake implementations for metadata persistence
- `src/erk/core/forest_types.py` - Core data structures (Forest, ForestMetadata, RerootState)
- `src/erk/core/forest_utils.py` - Pure utility functions for forest operations
- `tests/fakes/forest_ops.py` - Test fake for forest operations

### Modified (4 files)

- `docs/agent/glossary.md` - Added comprehensive forest terminology (Forest, Forest Membership, Empty Forest, Reroot)
- `src/erk/cli/cli.py` - Integrated forest command group, reordered split_cmd placement for logical grouping
- `src/erk/core/consolidation_utils.py` - Simplified docstrings and refactored function organization
- `src/erk/core/context.py` - Added forest_ops dependency injection to ErkContext

### Deleted (1 file)

- `tests/core/utils/test_consolidation_utils.py` - Removed in favor of updated testing structure

## Key Changes

- **Forest metadata system**: Implements TOML-based storage for forest definitions with automatic membership tracking
- **Reroot state management**: JSON state file for tracking conflict-preserving rebase progress across branches
- **Dependency injection**: Forest operations properly integrated into context creation with real/fake implementations
- **CLI group structure**: Forest commands ready for implementation with consistent interface pattern
- **Documentation**: Complete glossary and user-facing command documentation for all planned forest operations

## Critical Notes

- Forest subcommands (list, show, split, merge, reroot) are defined but not yet implemented (TODO markers in place)
- Reroot functionality requires Graphite to be enabled

Author: schrockn

docs/agent/glossary.md

@@ -38,6 +38,66 @@ A **managed worktree** created and maintained by the erk tool.
 
 **Example**: `erk create my-feature` creates both a git worktree and an erk.
 
+### Forest
+
+A **named collection of worktrees** belonging to the same Graphite stack.
+
+**Purpose**: Enables unified stack management operations like split, merge, and reroot.
+
+**Key characteristics**:
+
+- Forest names are pure labels stored in `forests.toml` metadata
+- Renaming a forest NEVER moves worktrees or changes filesystem paths
+- Worktree paths remain stable: `~/.erk/repos/<repo>/worktrees/<original-name>/`
+- Membership determined automatically by Graphite stack structure
+
+**Lifecycle**:
+
+- Created automatically when `erk create <name>` called from trunk
+- Joined automatically when `erk create -s <name>` called from forest member
+- Deleted automatically during `erk sync` when empty (zero worktrees)
+
+**Example**: A forest named "auth" might contain worktrees `auth-redesign`, `add-oauth`, and `add-2fa`.
+
+### Forest Membership
+
+Automatic assignment of a worktree to a forest based on Graphite parent/child relationships.
+
+**Rules**:
+
+- A worktree can only belong to one forest at a time
+- If branch's parent is trunk → new forest OR join existing if siblings present
+- If branch's parent is in forest → join that forest
+
+**Example**: Creating branch `add-oauth` from `auth-redesign` automatically adds it to the `auth` forest.
+
+### Empty Forest
+
+A forest with zero existing worktrees, automatically deleted during `erk sync`.
+
+**Detection**: Checked by comparing forest metadata against actual worktree directories.
+
+**Cleanup**: Automatic and silent during sync operations.
+
+### Reroot
+
+Conflict-preserving rebase operation for an entire forest.
+
+**Purpose**: Rebase all branches in a stack while preserving conflict states in git history.
+
+**Benefits**:
+
+- Permanent audit trail of conflicts and resolutions
+- Better PR reviewability
+- Easier debugging of complex merges
+
+**Commit format**:
+
+- `[CONFLICT] Rebase conflicts from <parent> (<sha>)`
+- `[RESOLVED] Fix rebase conflicts from <parent> (<sha>)`
+
+**Example**: `erk forest reroot auth` rebases all branches in the auth forest.
+
 ### Repo Root
 
 The main git repository directory containing `.git/` directory.

src/erk/cli/cli.py

@@ -8,6 +8,7 @@
 from erk.cli.commands.current import current_cmd
 from erk.cli.commands.delete import del_cmd, delete_cmd
 from erk.cli.commands.down import down_cmd
+from erk.cli.commands.forest import forest_group
 from erk.cli.commands.goto import goto_cmd
 from erk.cli.commands.init import init_cmd
 from erk.cli.commands.land_stack import land_stack
@@ -43,19 +44,20 @@ def cli(ctx: click.Context) -> None:
 cli.add_command(down_cmd)
 cli.add_command(checkout_cmd)
 cli.add_command(checkout_cmd, name="co")  # Alias
+cli.add_command(forest_group)
 cli.add_command(goto_cmd)
 cli.add_command(land_stack)
 cli.add_command(up_cmd)
 cli.add_command(list_cmd)
 cli.add_command(ls_cmd)
+cli.add_command(split_cmd)
 cli.add_command(status_cmd)
 cli.add_command(init_cmd)
 cli.add_command(move_cmd)
 cli.add_command(delete_cmd)
 cli.add_command(del_cmd)
 cli.add_command(rename_cmd)
 cli.add_command(config_group)
-cli.add_command(split_cmd)
 cli.add_command(sync_cmd)
 cli.add_command(hidden_shell_cmd)
 cli.add_command(prepare_cwd_recovery_cmd)

src/erk/cli/commands/forest/README.md

@@ -0,0 +1,284 @@
+# Forest Commands
+
+Unified stack management for erk worktrees.
+
+## Overview
+
+Forests are named collections of worktrees belonging to the same Graphite stack. They enable:
+
+- **Split**: Convert single worktree into forest of individual worktrees
+- **Merge**: Consolidate forest into single worktree
+- **Reroot**: Conflict-preserving rebase for entire stack
+- **Automatic lifecycle**: Creation, cleanup, and membership management
+
+## Requirements
+
+- Graphite must be enabled: `erk config set use-graphite true`
+- All branches must have worktrees (for reroot operations)
+- Clean working directory (no uncommitted changes for reroot)
+
+## Commands
+
+### Query Commands
+
+#### `erk forest`
+
+Show forest for current worktree with tree structure.
+
+```bash
+$ erk forest
+Forest: auth (3 worktrees)
+├── auth-redesign [auth-redesign] ← you are here
+├── add-oauth [add-oauth]
+└── add-2fa [add-2fa]
+```
+
+#### `erk forest list`
+
+List all forests in repository with creation dates.
+
+```bash
+$ erk forest list
+Forests in my-project:
+• auth-redesign (3 worktrees) - created 2024-01-15
+• perf-work (2 worktrees) - created 2024-01-16
+```
+
+#### `erk forest show [NAME]`
+
+Show specific forest (defaults to current worktree's forest).
+
+#### `erk forest rename OLD NEW`
+
+Rename forest (label only, paths unchanged).
+
+**Important**: Renaming changes only the metadata label. Worktree paths remain stable.
+
+### Split Operation
+
+Convert single worktree containing multiple branches into forest with individual worktrees.
+
+```bash
+$ erk forest split [FOREST_NAME]
+```
+
+**Options**:
+
+- `--up`: Only split upstack branches (toward leaves)
+- `--down`: Only split downstack branches (toward trunk)
+- `--force`: Skip confirmation
+- `--dry-run`: Preview without executing
+
+**Example**:
+
+```bash
+$ erk forest split
+Current worktree 'auth' contains 3 branches.
+Forest 'auth' will contain 3 worktrees:
+  • auth-redesign [auth-redesign] (current)
+  • add-oauth [add-oauth] (new)
+  • add-2fa [add-2fa] (new)
+
+Continue? [y/N]: y
+```
+
+### Merge Operation
+
+Consolidate forest into single worktree by removing all worktrees except target.
+
+```bash
+$ erk forest merge [FOREST_NAME]
+```
+
+**Options**:
+
+- `--into WORKTREE`: Specify target worktree to keep
+- `--force`: Skip confirmation
+- `--dry-run`: Preview without executing
+
+**Default target**: Current worktree (if in forest) or first worktree.
+
+**Example**:
+
+```bash
+$ erk forest merge auth
+This will merge forest 'auth' (3 worktrees) into worktree 'auth-redesign'.
+Worktrees to be removed:
+  • add-oauth
+  • add-2fa
+
+Continue? [y/N]: y
+```
+
+### Reroot Operation
+
+Conflict-preserving rebase for entire stack.
+
+#### Starting a Rebase
+
+```bash
+$ erk forest reroot [FOREST_NAME]
+```
+
+Pre-flight checks:
+
+1. Graphite enabled
+2. Clean working directory
+3. All branches have worktrees
+
+The command displays stack preview and runs pre-flight checks before confirmation.
+
+#### When Conflicts Occur
+
+Reroot pauses on conflicts and prompts whether to commit conflict state:
+
+```
+⚠️  Conflicts detected in branch: feature-1
+
+Conflicted files (3):
+  - src/main.py (UU - both modified)
+  - src/utils.py (UU - both modified)
+  - tests/test_main.py (AU - added by us, modified by them)
+
+Commit conflict state to preserve in history? [Y/n]: y
+Creating conflict commit: [CONFLICT] Rebase conflicts from main (abc1234)
+  ✅ Conflict commit created
+  ✅ Progress saved
+
+Next steps:
+1. Resolve conflicts in the files listed above
+2. Run: erk forest reroot --continue
+
+ℹ️  Current worktree: /Users/you/.erk/repos/myproject/worktrees/feature-1
+```
+
+#### Resolving Conflicts
+
+After manually resolving conflicts:
+
+```bash
+$ erk forest reroot --continue
+```
+
+This creates a `[RESOLVED]` commit and continues with remaining branches.
+
+#### Abort Workflow
+
+To abort an in-progress reroot:
+
+```bash
+$ erk forest reroot --abort
+```
+
+Runs `git rebase --abort` and cleans up state files.
+
+## Automatic Lifecycle
+
+### Auto-Creation
+
+Forests are created silently when:
+
+1. Creating branch from trunk: `erk create <name>` → new forest
+2. Creating branch from forest member: `erk create -s <name>` → joins forest
+
+No explicit forest creation needed.
+
+### Auto-Cleanup
+
+Empty forests (zero worktrees) are automatically deleted during `erk sync`.
+
+## Git History After Rebase
+
+Conflict commits preserve exact conflict state:
+
+```bash
+$ git log --oneline
+abc1234 [RESOLVED] Fix rebase conflicts from main (abc1234)
+def5678 [CONFLICT] Rebase conflicts from main (abc1234)
+```
+
+View conflict state:
+
+```bash
+$ git show def5678
+```
+
+View resolution:
+
+```bash
+$ git show abc1234
+```
+
+Compare before/after:
+
+```bash
+$ git diff def5678 abc1234
+```
+
+## Common Errors
+
+### "This command requires Graphite"
+
+**Solution**: `erk config set use-graphite true`
+
+### "Uncommitted changes detected"
+
+**Solution**: Commit or stash changes before reroot
+
+```bash
+$ git add . && git commit -m "WIP"
+# or
+$ git stash
+```
+
+### "The following branches do not have worktrees"
+
+**Solution**: Create worktrees for missing branches
+
+```bash
+$ erk create feature-1
+$ erk create feature-2
+```
+
+### "No rebase state found" (on --continue)
+
+**Solution**: Start new rebase instead
+
+```bash
+$ erk forest reroot
+```
+
+## Design Rationale
+
+### Why forests are labels not filesystem structures
+
+Forest names are pure metadata labels. Renaming never moves worktrees because:
+
+- Prevents breaking tools/scripts that depend on stable paths
+- Separation of logical grouping from physical storage
+- Simpler consistency model
+
+### Why auto-creation is silent
+
+Forest concept should be invisible until explicitly needed:
+
+- Users just create branches normally
+- Forests emerge naturally from stack structure
+- Reduces cognitive overhead
+
+### Why conflict commits are optional
+
+User confirmation prompt (not automatic) because:
+
+- Some users may prefer clean history
+- Allows case-by-case decisions
+- Explicit consent for history modification
+
+## Migration from Split/Consolidate
+
+Old commands have been replaced:
+
+- `erk split` → `erk forest split`
+- `erk consolidate` → `erk forest merge`
+
+**Key difference**: The `--name` flag is gone. Forest names are managed automatically.