storybook/design/behavior-tree-implementation-status.md

# Behavior Tree Keyword Implementation Status

**Task:** #7 - Implement behavior tree keyword transformation system
**Status:** In Progress (60% complete)
**Date:** February 12, 2026

---

## ✅ Completed Work

### 1. Tree-sitter Grammar (`tree-sitter-storybook/grammar.js`)
- ✅ Updated `selector_node` to use `choose` keyword with optional label
- ✅ Updated `sequence_node` to use `then` keyword with optional label
- ✅ Added `condition_node` for `if(expr)` and `when(expr)`
- ✅ Added `decorator_node` with full parameter support
- ✅ Added `decorator_keyword` enumeration
- ✅ Added `decorator_params` for all parameter types
- ✅ Updated `subtree_node` to use `include` keyword
- ✅ Extended `duration` pattern to support days (`d`)

### 2. AST Structures (`src/syntax/ast.rs` + `storybook/src/syntax/ast.rs`)
- ✅ Restructured `BehaviorNode::Selector` with label support
- ✅ Restructured `BehaviorNode::Sequence` with label support
- ✅ Added `BehaviorNode::Decorator` with typed decorators
- ✅ Created `DecoratorType` enum with 10 variants
- ✅ Created `Duration` struct with `DurationUnit` enum
- ✅ Implemented `Duration::to_milliseconds()` conversion

### 3. LALRPOP Parser (`src/syntax/parser.lalrpop`)
- ✅ Updated `BehaviorNode` choice to include new node types
- ✅ Implemented `SelectorNode` with `choose` keyword and optional label
- ✅ Implemented `SequenceNode` with `then` keyword and optional label
- ✅ Implemented `ConditionNode` for `if`/`when` expressions
- ✅ Implemented all 10 decorator parsers:
  - `DecoratorRepeat` (infinite)
  - `DecoratorRepeatN(n)`
  - `DecoratorRepeatRange(min..max)`
  - `DecoratorInvert`
  - `DecoratorRetry(n)`
  - `DecoratorTimeout(duration)`
  - `DecoratorCooldown(duration)`
  - `DecoratorGuard(expr)`
  - `DecoratorSucceedAlways`
  - `DecoratorFailAlways`
- ✅ Updated `SubTreeNode` to use `include` keyword

### 4. Lexer Tokens (`src/syntax/lexer.rs` + `storybook/src/syntax/lexer.rs`)
- ✅ Added `Choose` token
- ✅ Added `Then` token
- ✅ Added `If` token
- ✅ Added `When` token
- ✅ Added `Repeat` token
- ✅ Added `Invert` token
- ✅ Added `Retry` token
- ✅ Added `Timeout` token
- ✅ Added `Cooldown` token
- ✅ Added `Guard` token
- ✅ Added `SucceedAlways` token
- ✅ Added `FailAlways` token

### 5. Example Files
- ✅ Created `examples/new-syntax-demo.sb` with comprehensive demonstrations

---

## 🚧 In Progress / Pending

### 6. Fix Compilation Errors
The AST changes will break existing code that pattern-matches on `BehaviorNode`:
- [ ] Update all `match BehaviorNode::Selector(nodes)` to `BehaviorNode::Selector { label, children }`
- [ ] Update all `match BehaviorNode::Sequence(nodes)` to `BehaviorNode::Sequence { label, children }`
- [ ] Update all `match BehaviorNode::Decorator(name, child)` to `BehaviorNode::Decorator { decorator_type, child }`
- [ ] Check files:
  - `src/resolve/validate.rs`
  - `src/resolve/types.rs`
  - `src/types.rs`
  - LSP code in `storybook/src/lsp/`
  - Test files

### 7. Compiler / SBIR Generation
- [ ] Update SBIR node type encoding for decorators
- [ ] Implement serialization for `DecoratorType` variants
- [ ] Implement `Duration` serialization
- [ ] Update compiler to handle new AST structures
- [ ] Test SBIR output for correctness

### 8. Testing
- [ ] Rebuild Tree-sitter grammar (`npm run build` or similar)
- [ ] Test parsing `examples/new-syntax-demo.sb`
- [ ] Add unit tests for each decorator type
- [ ] Add integration tests for nested decorators
- [ ] Test round-trip: parse → compile → decompile

### 9. Example Migration
- [ ] Migrate `examples/alice-in-wonderland/world/characters/white_rabbit.sb`
- [ ] Migrate `examples/alice-in-wonderland/world/characters/mad_tea_party.sb` (add `repeat` decorator)
- [ ] Migrate `examples/alice-in-wonderland/world/characters/cheshire_cat.sb` (add decorators)
- [ ] Migrate `examples/alice-in-wonderland/world/characters/royal_court.sb` (add `repeat` decorators)
- [ ] Migrate `examples/alice-in-wonderland/world/characters/caterpillar.sb`
- [ ] Migrate `tests/examples/behavior_and_lifearc.sb`
- [ ] Update test corpus in `tree-sitter-storybook/test/corpus/behaviors.txt`

### 10. Documentation
- [ ] Update `design.md` Section 6 with new syntax
- [ ] Create migration guide
- [ ] Add tutorial examples highlighting named nodes
- [ ] Update CHANGELOG with breaking changes
- [ ] Prepare handoff notes for language documentation agent

---

## 📊 Progress Metrics

**Overall Completion:** 60%

**By Phase:**
- Phase 1 (Grammar & Parser): 100% ✅
- Phase 2 (AST & Compiler): 70% (AST done, compiler pending)
- Phase 3 (Examples & Tests): 10% (example created, migration pending)
- Phase 4 (Documentation): 0%

**By Component:**
- Grammar: 100% ✅
- AST: 100% ✅
- Lexer: 100% ✅
- Parser: 100% ✅
- Compilation fixes: 0%
- Compiler/SBIR: 0%
- Testing: 10%
- Migration: 0%
- Documentation: 0%

---

## 🎯 Next Immediate Actions

1. **Find and fix compilation errors** from AST changes
2. **Update compiler** to handle new `DecoratorType` enum
3. **Test parsing** the new syntax example
4. **Migrate one example** (White Rabbit) to validate end-to-end
5. **Add unit tests** for decorator parsing

---

## 📝 Design Decisions Implemented

Following Sienna's feedback from design review:

✅ **Use `choose` only** (not `selector`)
✅ **Use `then` only** (not `sequence`)
✅ **Remove @ prefix for actions**
✅ **Use `include` for subtrees**
✅ **Named nodes are prominent** (optional label on choose/then)
✅ **Decorators approved** (all 10 types implemented)
✅ **No backward compatibility** (clean break from symbolic syntax)

---

## 🔄 Files Modified

**Grammar:**
- `tree-sitter-storybook/grammar.js`

**AST:**
- `src/syntax/ast.rs`
- `storybook/src/syntax/ast.rs`

**Parser:**
- `src/syntax/parser.lalrpop`

**Lexer:**
- `src/syntax/lexer.rs`
- `storybook/src/syntax/lexer.rs`

**Examples:**
- `examples/new-syntax-demo.sb` (new)

---

## 🐛 Known Issues / Blockers

**Compilation Errors Expected:**
The AST structure changes will cause compilation errors in any code that pattern-matches on `BehaviorNode`. These need to be fixed before the code will compile.

**Files Likely Affected:**
- `src/resolve/validate.rs` - behavior tree validation
- `src/resolve/types.rs` - type resolution
- `src/types.rs` - type definitions
- `storybook/src/lsp/semantic_tokens.rs` - LSP highlighting
- `storybook/src/lsp/navigation_tests.rs` - LSP tests
- Test files with behavior tree examples

**Resolution Strategy:**
1. Attempt to compile
2. Fix each compilation error by updating pattern matches
3. Test that fixes maintain correct behavior
4. Coordinate with LSP agent if LSP changes are extensive

---

## 📚 Resources

**Design Document:** `/Users/sienna/Development/storybook/design/behavior-tree-keywords-design.md`
**Example File:** `/Users/sienna/Development/storybook/examples/new-syntax-demo.sb`
**TEAM PLAN:** `/Users/sienna/Development/storybook/TEAM_PLAN.md` (Task #7)

---

**Last Updated:** 2026-02-12
**Next Update:** After fixing compilation errors