Update AGENTS.md with common issues and implementation notes

Author: avoidwork

AGENTS.md

@@ -55,7 +55,23 @@ Source code is in `src/`.
 
 ## Testing
 
-- Framework: Mocha
+- Framework: Node.js built-in test runner (`node --test`)
 - Coverage: 100% (c8)
 - Test pattern: `tests/**/*.js`
 - All tests must pass with 100% coverage before merging
+- Run: `npm test` (lint + tests)
+
+## Common Issues to Avoid
+
+- **Memory leaks**: When removing items from the linked list, always clear `prev`/`next` pointers to allow garbage collection
+- **LRU order pollution**: Methods like `entries()` and `values()` should access items directly rather than calling `get()`, which moves items and can delete expired items mid-iteration
+- **TTL edge cases**: Direct property access (`this.items[key]`) should be used instead of `has()` when you need to inspect expired-but-not-yet-deleted items
+- **Dead code**: Always verify edge case code is actually reachable before adding special handling
+- **Constructor assignment**: Use `let` not `const` for variables that may be reassigned (e.g., in `setWithEvicted`)
+
+## Implementation Notes
+
+- The LRU uses a doubly-linked list with `first` and `last` pointers for O(1) operations
+- TTL is stored per-item as an `expiry` timestamp; `0` means no expiration
+- `moveToEnd()` is the core method for maintaining LRU order - item is always moved to the `last` position
+- `setWithEvicted()` optimizes updates by avoiding the full `set()` path for existing keys