1 files changed, 121 insertions, 0 deletions
diff --git a/js/scripting-lang/design/HISTORY/PRECEDENCE_RESOLUTION.md b/js/scripting-lang/design/HISTORY/PRECEDENCE_RESOLUTION.md
new file mode 100644
index 0000000..6c3ea95
--- /dev/null
+++ b/js/scripting-lang/design/HISTORY/PRECEDENCE_RESOLUTION.md
@@ -0,0 +1,121 @@
+# Precedence Resolution: Historical Documentation
+
+**Status**: ✅ RESOLVED - All precedence issues have been successfully fixed  
+**Impact**: All arithmetic operations now work correctly
+
+## Overview
+
+This document archives the precedence issues that were identified and resolved during the function composition implementation. All precedence-related problems have been successfully fixed and are no longer active issues.
+
+## The Problem (Resolved)
+
+### Original Issue
+The parser was incorrectly translating `x - y` as `apply(x, negate(y))` instead of `subtract(x, y)`. This caused binary minus operations to fail.
+
+### Root Cause
+`TokenType.MINUS` was included in the `isValidArgumentStart` function, causing the parser to treat minus as a valid argument start for function application rather than a binary operator.
+
+### The Fix
+Removed `TokenType.MINUS` from `isValidArgumentStart`:
+
+```javascript
+function isValidArgumentStart(token) {
+    return token.type === TokenType.IDENTIFIER ||
+           token.type === TokenType.NUMBER ||
+           token.type === TokenType.STRING ||
+           token.type === TokenType.LEFT_PAREN ||
+           token.type === TokenType.LEFT_BRACE ||
+           token.type === TokenType.TRUE ||
+           token.type === TokenType.FALSE ||
+           token.type === TokenType.FUNCTION_REF ||
+           token.type === TokenType.FUNCTION_ARG ||
+           // Removed: token.type === TokenType.MINUS ||  ← FIXED
+           token.type === TokenType.NOT;
+}
+```
+
+## Resolution Results
+
+### ✅ All Operations Working
+- **Binary minus**: `x - y` → `subtract(x, y)` ✅
+- **Unary minus**: `-x` → `negate(x)` ✅
+- **Mixed operations**: `x * -y` → `multiply(x, negate(y))` ✅
+- **Complex expressions**: `x + y * z` → `add(x, multiply(y, z))` ✅
+
+### ✅ Test Results
+All precedence test cases now pass:
+- Basic arithmetic operations
+- Unary operations
+- Mixed unary and binary operations
+- Function application
+- Function composition
+- Comparison operations
+- Logical operations
+- Complex expressions
+- Edge cases
+
+## Technical Details
+
+### Precedence Chain (Working)
+```
+parseLogicalExpression() → parseExpression() → parseTerm() → parseApplication() → parseComposition() → parseFactor() → parsePrimary()
+```
+
+### Operator Handling (Working)
+- **Unary minus**: Handled in `parsePrimary()` (highest precedence) ✅
+- **Binary minus**: Handled in `parseExpression()` (correct precedence) ✅
+- **Function application**: Handled in `parseApplication()` (via juxtaposition) ✅
+- **Function references**: Handled in `parsePrimary()` ✅
+
+### Combinator Architecture (Working)
+All operators correctly translate to function calls:
+- `x + y` → `add(x, y)`
+- `x - y` → `subtract(x, y)`
+- `x * y` → `multiply(x, y)`
+- `f x` → `apply(f, x)`
+- `@f` → function reference
+
+## Impact on Development
+
+### Before Fix
+- Binary minus operations failed
+- Mixed operations with unary minus failed
+- Test suite had precedence-related failures
+
+### After Fix
+- All arithmetic operations work correctly
+- Function composition works perfectly
+- Standard library functions work with @ syntax
+- Test suite shows 8/18 tests passing (remaining failures are case expression issues, not precedence)
+
+## Lessons Learned
+
+### Key Insights
+1. **Combinator Architecture**: The combinator-based approach works well when precedence is handled correctly
+2. **Function Application**: Juxtaposition-based function application can coexist with operators when precedence is properly defined
+3. **Incremental Fixes**: Small changes to `isValidArgumentStart` can have significant impact on parsing behavior
+
+### Best Practices
+1. **Test-Driven Development**: Comprehensive test cases helped identify and verify the fix
+2. **Debug Mode**: `DEBUG=1` was essential for understanding parsing behavior
+3. **Incremental Testing**: Testing each operation individually helped isolate issues
+
+## Related Documents
+
+### Implementation
+- **IMPLEMENTATION_GUIDE.md**: Contains the actual implementation details
+- **PROJECT_ROADMAP.md**: Updated to reflect precedence resolution
+
+### Architecture
+- **COMBINATORS.md**: Explains the combinator foundation that made this fix possible
+- **ARCHITECTURE.md**: Complete system architecture overview
+
+## Conclusion
+
+The precedence issues have been **completely resolved**. The combinator-based architecture is working correctly, and all arithmetic operations are functioning as expected. The fix was simple but effective, demonstrating the robustness of the combinator approach.
+
+**Current Focus**: The project has moved on to case expression parsing issues, which are separate from precedence and have a clear path to resolution.
+
+---
+
+**Archive Note**: This document is kept for historical reference and to document the resolution approach for future similar issues. 
\ No newline at end of file