PR-02: Engine Core (Ring Buffer, Matcher, Policy)

[Coldaine]

Summary

Implements the core suggestion engine for Shortcut Sage:

• RingBuffer: Time-windowed event storage (~3s)
• FeatureExtractor: Context analysis from event sequences
• RuleMatcher: Pattern matching for context-based rules
• PolicyEngine: Cooldown management, top-N ranking, acceptance tracking

Depends On

• PR-01: Config & Schemas ✅ Merged to master (commit 23ba57a)

Test Plan

• Unit tests for all engine components
• Integration tests with golden scenarios
• Coverage ≥80% (actual: 92% for engine modules)
• All tests pass locally

Artifacts

• sage/buffer.py, sage/events.py, sage/features.py, sage/matcher.py, sage/policy.py
• Comprehensive unit and integration tests
• docs/plans/StagedImplementation.md - Implementation strategy

Known Issues

None

Security/Privacy

• No PII in events (symbolic actions only)
• Local processing only

---

Labels: stacked, do-not-merge, engine

@copilot @codex Ready for autonomous review. Continue to PR-03 (DBus IPC) if approved.

🤖 Generated with Claude Code

[Copilot]

Pull Request Overview

Implements the core suggestion engine for Shortcut Sage, providing the foundation for context-aware keyboard shortcut recommendations. This PR adds time-windowed event storage, feature extraction from event sequences, rule pattern matching, and policy management with cooldowns and priority-based ranking.

Key Changes:

• Ring buffer implementation with automatic pruning for 3-second event windows
• Feature extraction engine that analyzes event sequences to build context
• Rule matching system supporting string and list patterns for contextual suggestions
• Policy engine with cooldown management, top-N filtering, and acceptance tracking

Reviewed Changes

Copilot reviewed 28 out of 30 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
sage/buffer.py	Ring buffer for time-windowed event storage with automatic pruning
sage/events.py	Event model with timestamp handling and dictionary conversion
sage/features.py	Feature extraction from event sequences for context analysis
sage/matcher.py	Rule matching engine supporting various pattern types
sage/policy.py	Policy engine with cooldowns, priority sorting, and acceptance tracking
sage/models.py	Pydantic models for configuration validation and data structures
sage/config.py	Configuration loader with YAML parsing and validation
sage/watcher.py	File system watcher for hot-reload configuration changes
tests/	Comprehensive unit and integration tests with >90% coverage
config/	Sample configuration files for shortcuts and rules
pyproject.toml	Project configuration with dependencies and tool settings

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}