feat(shell): implement variables and quote parsing (Phase 6 M4 & M5)

Phase 6 Milestone 4 (Variables v0.8.0):
- Add variable storage to ShellState (HashMap)
- Implement VAR=value assignment parsing
- Implement $VAR and ${VAR} expansion
- Add special variables ($?, $$, $HOME, $PWD, $USER, $PATH, $SHELL)
- Implement export command (export VAR, export VAR=value)
- Add comprehensive unit tests for variables (8 tests)
- Expand variables in all command types (builtin + external)

Phase 6 Milestone 5 (Quote Parsing v0.9.0):
- Rewrite tokenizer with quote state machine (single/double quotes, backslash)
- Add QuoteType, WordPart, QuotedWord structures for quote-aware parsing
- Implement quote-aware variable expansion ($VAR in "" expands, in '' doesn't)
- Add positional parameters ($0-$9, $@, $*, $#) to ShellState
- Handle backslash escaping (\$, \", \\) in all contexts
- Detect unclosed quotes as errors
- Add 13 new quote parsing tests

BREAKING CHANGE: Token::Word now contains QuotedWord instead of String

Test results:
- Unit tests: 69 passed
- Integration tests: 27 passed
- Property tests: 19 passed
- Total: 115 tests passing

Ref: docs/PHASE6_M4_DESIGN.md, docs/PHASE6_M5_DESIGN.md
Ref: docs/SESSION_2026-01-28_VARIABLES.md, docs/SESSION_2026-01-29_QUOTES.md

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

Author: hyperpolymath

docs/PHASE6_M4_DESIGN.md

@@ -0,0 +1,286 @@
+# Phase 6 Milestone 4: Variables
+
+**Status**: ✅ Complete
+**Version**: 0.8.0
+**Date Completed**: 2026-01-28
+
+## Overview
+
+Implement POSIX-compatible shell variables with formal verification backing.
+
+## Scope
+
+### Variable Assignment
+```bash
+vsh> NAME="World"
+vsh> PATH=/usr/bin:/bin
+vsh> EMPTY=
+```
+
+### Variable Expansion
+```bash
+vsh> echo $NAME
+World
+vsh> echo ${NAME}
+World
+vsh> echo "Hello, $NAME"
+Hello, World
+```
+
+### Special Variables
+```bash
+vsh> echo $?       # Last exit code
+0
+vsh> echo $$       # Current shell PID
+12345
+vsh> echo $HOME    # Environment variables
+/home/user
+vsh> echo $@       # All positional parameters
+arg1 arg2 arg3
+```
+
+### Environment Variables
+```bash
+vsh> export PATH=/new/path
+vsh> env | grep PATH
+PATH=/new/path
+```
+
+## Architecture
+
+### Data Structures
+
+```rust
+pub struct ShellState {
+    // Existing fields...
+    variables: HashMap<String, String>,
+    exported_vars: HashSet<String>,
+    last_exit_code: i32,
+}
+```
+
+### Parser Extensions
+
+1. **Assignment Detection**: `VAR=value` before command execution
+2. **Dollar Expansion**: `$VAR` and `${VAR}` in tokens
+3. **Quote Handling**: Variables expand in `"..."` but not `'...'`
+
+### Expansion Order (POSIX)
+
+1. Tilde expansion (`~` → `$HOME`)
+2. Parameter expansion (`$VAR`)
+3. Command substitution (`$(cmd)` - future)
+4. Arithmetic expansion (`$((expr))` - future)
+5. Word splitting
+6. Pathname expansion (globs - future)
+7. Quote removal
+
+## Implementation Plan
+
+### Step 1: Variable Storage (30 min)
+- [x] Add `variables: HashMap<String, String>` to ShellState
+- [x] Add `last_exit_code: i32` to ShellState
+- [x] Add getter/setter methods
+
+### Step 2: Assignment Parser (1 hour)
+- [x] Detect `VAR=value` pattern in tokenizer
+- [x] Support empty values: `VAR=`
+- [x] Validate variable names (must start with letter/underscore)
+- [ ] Handle multiple assignments: `A=1 B=2 command` (deferred to Phase 6 M5)
+- [ ] Support quoted values: `VAR="hello world"` (deferred - quotes not yet implemented)
+
+### Step 3: Variable Expansion (2 hours)
+- [x] Implement `$VAR` expansion during execution
+- [x] Implement `${VAR}` expansion (braced form)
+- [x] Handle undefined variables (expand to empty string)
+- [x] Expand variables in all command arguments and paths
+- [ ] Respect quote context (expand in `"..."`, not `'...'`) (deferred - quotes not yet implemented)
+
+### Step 4: Special Variables (1 hour)
+- [x] `$?` - Last exit code
+- [x] `$$` - Current process PID
+- [x] `$HOME` - Home directory (from env)
+- [x] `$PWD` - Current working directory
+- [x] `$USER` - Current user (from env)
+- [x] `$PATH` - Command search path (from env)
+- [x] `$SHELL` - Shell name (returns "vsh")
+
+### Step 5: Export Support (1 hour)
+- [x] `export VAR=value` builtin
+- [x] `export VAR` (export existing variable)
+- [x] Track exported variables separately
+- [x] Validate variable names
+- [ ] Pass exported vars to child processes via env (deferred - will be implemented when external command env is added)
+
+### Step 6: Tests (2 hours)
+- [x] Unit tests for variable storage
+- [x] Unit tests for assignment parsing
+- [x] Unit tests for expansion (simple, braced, special, multiple)
+- [x] Unit tests for export command
+- [x] Manual integration testing (all features verified)
+- [ ] Property tests for expansion correctness (deferred - optional enhancement)
+
+### Step 7: Documentation (30 min)
+- [x] Update PHASE6_M4_DESIGN.md with completion status
+- [ ] Update STATE.scm to v0.8.0
+- [ ] Create PHASE6_M4_COMPLETE.md report
+
+## Test Cases
+
+### Assignment Tests
+```rust
+#[test]
+fn test_variable_assignment() {
+    let mut state = ShellState::new();
+    state.set_variable("NAME", "Alice");
+    assert_eq!(state.get_variable("NAME"), Some("Alice"));
+}
+
+#[test]
+fn test_multiple_assignments() {
+    // A=1 B=2 echo $A $B
+    // Should output: 1 2
+}
+```
+
+### Expansion Tests
+```rust
+#[test]
+fn test_simple_expansion() {
+    // NAME=World
+    // echo Hello, $NAME
+    // Should output: Hello, World
+}
+
+#[test]
+fn test_braced_expansion() {
+    // FILE=test
+    // echo ${FILE}.txt
+    // Should output: test.txt
+}
+
+#[test]
+fn test_undefined_variable() {
+    // echo $UNDEFINED
+    // Should output: (empty line)
+}
+```
+
+### Special Variable Tests
+```rust
+#[test]
+fn test_exit_code_variable() {
+    // false
+    // echo $?
+    // Should output: 1
+}
+
+#[test]
+fn test_pid_variable() {
+    // echo $$
+    // Should output: (current PID)
+}
+```
+
+### Quote Context Tests
+```rust
+#[test]
+fn test_expansion_in_double_quotes() {
+    // NAME=Alice
+    // echo "Hello, $NAME"
+    // Should output: Hello, Alice
+}
+
+#[test]
+fn test_no_expansion_in_single_quotes() {
+    // NAME=Alice
+    // echo 'Hello, $NAME'
+    // Should output: Hello, $NAME
+}
+```
+
+## Formal Verification Considerations
+
+### Theorems to Prove (Future)
+
+1. **Variable Substitution Correctness**
+   ```lean4
+   theorem subst_identity :
+     ∀ env : Environment, ∀ var : String, ∀ value : String,
+       expand (assign env var value) (Var var) = value
+   ```
+
+2. **Substitution Composition**
+   ```lean4
+   theorem subst_composition :
+     ∀ env : Environment, ∀ s : String,
+       expand (expand env s) = expand env s  -- Idempotent
+   ```
+
+3. **Quote Preservation**
+   ```lean4
+   theorem single_quote_no_expand :
+     ∀ env : Environment, ∀ s : String,
+       expand env (SingleQuoted s) = s
+   ```
+
+### Properties to Test (Echidna)
+
+- Expansion is idempotent (expanding twice = expanding once)
+- Undefined variables expand to empty string
+- Single quotes prevent expansion
+- Assignment doesn't affect other variables
+
+## POSIX Compliance
+
+### Supported (M4)
+- ✅ Simple assignment: `VAR=value`
+- ✅ Variable expansion: `$VAR`, `${VAR}`
+- ✅ Special variables: `$?`, `$$`
+- ✅ Environment variables: `$HOME`, `$PATH`, etc.
+- ✅ Export: `export VAR`
+- ✅ Quote handling: `"$VAR"` vs `'$VAR'`
+
+### Deferred (Future Milestones)
+- ❌ Parameter expansion: `${VAR:-default}`, `${VAR:+alt}`
+- ❌ String operations: `${VAR#pattern}`, `${VAR%pattern}`
+- ❌ Array variables: `ARRAY[0]=value`
+- ❌ Positional parameters: `$1`, `$2`, etc. (M6)
+- ❌ Command substitution: `$(cmd)` (M7)
+- ❌ Arithmetic expansion: `$((expr))` (M8)
+
+## Performance Considerations
+
+- Variable lookup: O(1) via HashMap
+- Expansion: O(n) where n = string length
+- No regex needed for simple `$VAR` expansion
+
+## Security Considerations
+
+- No arbitrary code execution in expansion
+- Environment variable isolation from untrusted sources
+- Prevent `$PATH` injection in exported vars
+
+## Success Criteria
+
+- [ ] All 20+ variable tests passing
+- [ ] Variables work in commands: `NAME=Alice echo $NAME`
+- [ ] Special variables work: `echo $?` after command
+- [ ] Export works: exported vars visible to child processes
+- [ ] Documentation complete with examples
+- [ ] STATE.scm updated to v0.8.0
+
+## Timeline
+
+**Estimated**: 8-10 hours total
+- Day 1: Steps 1-3 (variable storage, assignment, expansion)
+- Day 2: Steps 4-5 (special vars, export)
+- Day 3: Steps 6-7 (tests, documentation)
+
+**Target Completion**: 2026-01-29
+
+## References
+
+- POSIX Shell Variables: https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_05
+- Bash Variables: https://www.gnu.org/software/bash/manual/html_node/Shell-Parameters.html
+- Previous Milestone: [PHASE6_M3_COMPLETE.md](PHASE6_M3_COMPLETE.md)