@@ -9,21 +9,24 @@ This document tracks active and planned work for PSCue. For architectural detail
99## Current Status
1010
1111** Latest Release** : v0.3.0 (2025-11-09)
12- - ✅ Multi-word prediction suggestions (Phase 17.4)
13- - ✅ Dynamic workflow learning (Phase 18.1)
14- - ✅ Smart directory navigation with ` pcd ` command (Phases 17.5-17.7)
15- - ✅ Enhanced path handling and fuzzy matching
12+ - ✅ Multi-word prediction suggestions (Phase 17.4) - archived to docs/COMPLETED.md
13+ - ✅ Dynamic workflow learning (Phase 18.1) - archived to docs/COMPLETED.md
14+ - ✅ Smart directory navigation with ` pcd ` command (Phases 17.5-17.8) - archived to docs/COMPLETED.md
15+ - Phase 17.5: Basic ` pcd ` command with tab completion
16+ - Phase 17.6: Enhanced algorithm (fuzzy matching, frecency, distance scoring)
17+ - Phase 17.7: Inline predictions and relative paths
18+ - Phase 17.8: Partial command predictions (typing "g" suggests "git")
1619- ✅ Comprehensive test coverage (300+ tests)
1720- 🎉 Available for installation via one-line command
1821
1922** Previous Release** : v0.2.0 (2025-11-05)
20- - ML-based N-gram sequence prediction (Phase 17.1)
21- - Privacy & security - sensitive data protection (Phase 17.2)
22- - Partial word completion filtering (Phase 17.3)
23+ - ML-based N-gram sequence prediction (Phase 17.1) - archived
24+ - Privacy & security - sensitive data protection (Phase 17.2) - archived
25+ - Partial word completion filtering (Phase 17.3) - archived
2326- Automated CI/CD with GitHub Actions
2427
2528** Recent Improvements** (not yet released):
26- - None currently - all features shipped in v0.3.0
29+ - None currently - all v0.3.0 features archived to docs/COMPLETED.md
2730
2831** Installation** :
2932``` powershell
@@ -34,329 +37,6 @@ irm https://raw.githubusercontent.com/lucaspimentel/PSCue/main/scripts/install-r
3437
3538## Planned Work
3639
37- ### Phase 17.5: Smart Directory Navigation (` pcd ` command)
38- ** Status** : ✅ ** COMPLETE** (2025-11-08)
39-
40- Add a PowerShell function with smart tab completion for directory navigation, leveraging PSCue's learned directory data without interfering with native ` cd ` completion.
41-
42- ** Completed** :
43- - ✅ Created ` module/Functions/PCD.ps1 ` with ` Invoke-PCD ` function
44- - ✅ Function logic: calls ` Set-Location ` with argument
45- - ✅ Fallback to native behavior if no learned data available
46- - ✅ Handles empty argument (cd to home directory)
47- - ✅ Tab completion: ` Register-ArgumentCompleter -CommandName ` (in-process)
48- - ✅ Queries ` PSCueModule.KnowledgeGraph.GetSuggestions("cd", @()) `
49- - ✅ Filters by ` $wordToComplete ` (StartsWith matching)
50- - ✅ Returns ` CompletionResult ` objects with usage count and last used date tooltip
51- - ✅ Created alias: ` pcd ` (PowerShell Change Directory)
52- - ✅ Updated ` module/PSCue.psd1 ` :
53- - ✅ Added to ` FunctionsToExport ` : ` 'Invoke-PCD' `
54- - ✅ Added to ` AliasesToExport ` : ` 'pcd' `
55- - ✅ Also added missing workflow management functions to exports
56- - ✅ Created comprehensive tests in ` test/PSCue.Module.Tests/PCDTests.cs ` :
57- - ✅ 19 tests covering all functionality
58- - ✅ ArgumentGraph integration tests
59- - ✅ Tab completion simulation tests
60- - ✅ Scoring and ranking tests
61- - ✅ Edge cases and performance tests
62- - ✅ Documentation:
63- - ✅ Updated README.md with ` pcd ` command usage and examples
64- - ✅ Updated CLAUDE.md quick reference
65-
66- ** Files Modified** :
67- - ` module/Functions/PCD.ps1 ` (new file)
68- - ` module/PSCue.psd1 ` (added function/alias exports)
69- - ` test/PSCue.Module.Tests/PCDTests.cs ` (new file)
70- - ` README.md ` (added pcd usage section)
71- - ` CLAUDE.md ` (added pcd to function reference)
72-
73- ** Design Decisions** :
74- - ** In-process completion** : Direct call to ` PSCueModule.KnowledgeGraph ` (<1ms, no IPC overhead)
75- - ** Non-invasive** : Separate command (` pcd ` ), doesn't interfere with native ` cd ` tab completion
76- - ** Reuses existing data** : ArgumentGraph already tracks ` cd ` command with directory normalization
77- - ** Name choice** : ` pcd ` = PowerShell/PSCue Change Directory (alternatives: ` scd ` , ` lcd ` , ` qcd ` , ` cue ` )
78- - ** Display** : PSReadLine handles menu display (` MenuComplete ` , ` ListView ` ) - we just return ordered results
79-
80- ** Note** : See Phase 17.6 below for enhanced algorithm improvements (fuzzy matching, frecency scoring, distance awareness).
81-
82- ### Phase 17.6: Enhanced PCD Algorithm
83- ** Status** : ✅ ** COMPLETE** (2025-11-08)
84-
85- Enhance the ` pcd ` command with advanced matching, scoring, and navigation features.
86-
87- ** Goals** :
88- 1 . ** Well-known shortcuts** : Fast handling of ` ~ ` , ` .. ` , ` . ` with highest priority
89- 2 . ** Fuzzy matching** : Levenshtein distance + substring matching for flexible directory finding
90- 3 . ** Frecency scoring** : Configurable blend of frequency + recency + distance
91- 4 . ** Distance scoring** : Boost directories closer to current location (parent/child/sibling)
92- 5 . ** Recursive search** : Optional deep filesystem search for matching directories
93- 6 . ** Best-match navigation** : ` pcd <name> ` finds best match if no exact path exists
94-
95- ** Implementation Plan** :
96-
97- ** Core Engine** (✅ COMPLETE):
98- - [x] Create ` src/PSCue.Module/PCDCompletionEngine.cs ` with multi-stage algorithm
99- - [x] Stage 1: Well-known shortcuts (~ , .., .) with priority 1000/999/998
100- - [x] Stage 2: Learned directories with enhanced scoring
101- - [x] Match scoring: Exact (1.0) > Prefix (0.9) > Fuzzy (0.0-0.8)
102- - [x] Fuzzy matching: Substring + Levenshtein distance
103- - [x] Frecency: Configurable weights (default: 50% frequency, 30% recency, 20% distance)
104- - [x] Distance scoring: Same dir (1.0), Parent (0.9), Child (0.85-0.5), Sibling (0.7), Ancestor (0.6-0.1)
105- - [x] Stage 3: Recursive filesystem search (optional, configurable depth)
106-
107- ** PowerShell Integration** (✅ COMPLETE):
108- - [x] Update ` module/Functions/PCD.ps1 ` (205 lines total)
109- - [x] Tab completion: Use ` PcdCompletionEngine.GetSuggestions() `
110- - [x] Create engine instance with config from env vars
111- - [x] Call ` GetSuggestions($wordToComplete, $currentDirectory, 20) `
112- - [x] Convert ` PcdSuggestion ` objects to ` CompletionResult `
113- - [x] Show match type indicators in tooltips
114- - [x] ` Invoke-PCD ` function: Smart path resolution with best-match fallback
115- - [x] If path doesn't exist, use engine to find best match
116- - [x] Show message: "No exact match, navigating to: <best-match >"
117- - [x] Fall back to Set-Location error if no good matches
118- - [x] Read configuration from environment variables
119-
120- ** Testing** (✅ COMPLETE):
121- - [x] Create ` test/PSCue.Module.Tests/PcdEnhancedTests.cs `
122- - [x] Well-known shortcuts tests
123- - [x] Fuzzy matching tests
124- - [x] Frecency scoring tests
125- - [x] Distance scoring tests
126- - [x] Recursive search tests
127- - [x] Best-match navigation tests
128- - [x] Performance tests
129- - [x] Edge cases and error handling
130- - [x] Tooltip and display tests
131- - [x] All tests passing ✅
132-
133- ** Documentation** (✅ COMPLETE):
134- - [x] Update ` README.md ` : Enhanced features section with full algorithm details
135- - [x] Update ` CLAUDE.md ` : Algorithm details and file references
136- - [x] Update ` TODO.md ` : Mark Phase 17.6 complete
137-
138- ** Environment Variables** :
139- ``` powershell
140- # Scoring weights (must sum to ~1.0 with match weight)
141- $env:PSCUE_PCD_FREQUENCY_WEIGHT = "0.5" # Default: 0.5 (50%)
142- $env:PSCUE_PCD_RECENCY_WEIGHT = "0.3" # Default: 0.3 (30%)
143- $env:PSCUE_PCD_DISTANCE_WEIGHT = "0.2" # Default: 0.2 (20%)
144-
145- # Recursive search (disabled by default for performance)
146- $env:PSCUE_PCD_RECURSIVE_SEARCH = "true" # Default: false
147- $env:PSCUE_PCD_MAX_DEPTH = "3" # Default: 3 levels deep
148- ```
149-
150- ** Files Modified** :
151- - ` src/PSCue.Module/PcdCompletionEngine.cs ` (new file) ✅
152- - ` module/Functions/PCD.ps1 ` (enhanced) ✅
153- - ` test/PSCue.Module.Tests/PcdEnhancedTests.cs ` (new file) ✅
154- - ` README.md ` (enhanced pcd section) ✅
155- - ` CLAUDE.md ` (algorithm details + file references) ✅
156- - ` TODO.md ` (Phase 17.6 marked complete) ✅
157-
158- ** Key Achievements** :
159- - Multi-stage completion algorithm: Shortcuts → Learned → Recursive
160- - Fuzzy matching with Levenshtein distance + substring matching
161- - Configurable frecency scoring (frequency + recency + distance)
162- - Distance-aware scoring for nearby directories
163- - Best-match navigation without Tab completion
164- - Comprehensive test coverage for all features
165- - Full documentation in README and CLAUDE.md
166- - Performance targets met: <10ms tab completion, <50ms best-match
167-
168- ### Phase 17.7: PCD Inline Predictions & Relative Paths
169- ** Status** : ✅ ** COMPLETE** (2025-11-09)
170-
171- Enhance ` pcd ` with inline predictions and relative path display.
172-
173- ** Completed** :
174- - [x] Inline predictor integration
175- - [x] Add pcd command detection to CommandPredictor
176- - [x] Create GetPcdSuggestions() method
177- - [x] Support both "pcd" and "Invoke-PCD" commands
178- - [x] Show suggestions even for "pcd<space >" (always show predictions)
179- - [x] Return multiple suggestions (up to 5 for predictor)
180- - [x] Add environment variable helper methods
181- - [x] Relative path conversion
182- - [x] Add ToRelativePath() method to PcdCompletionEngine
183- - [x] Convert parent directory to ".."
184- - [x] Convert child directories to "./subdir" when shorter
185- - [x] Convert sibling directories to "../sibling" when shorter
186- - [x] Fall back to absolute path if relative isn't shorter
187- - [x] Apply to both tab completion and inline predictor
188- - [x] Keep full paths in DisplayPath and tooltips
189- - [x] Filter unhelpful suggestions
190- - [x] Don't suggest current directory (".")
191- - [x] Don't suggest previous directory ("-")
192- - [x] Don't suggest path that matches current directory
193-
194- ** Files Modified** :
195- - ` src/PSCue.Module/CommandPredictor.cs ` (added GetPcdSuggestions, env helpers)
196- - ` src/PSCue.Module/PcdCompletionEngine.cs ` (added ToRelativePath, updated suggestions)
197- - ` test/PSCue.Module.Tests/PcdEnhancedTests.cs ` (updated for filtering behavior)
198-
199- ** Key Achievements** :
200- - Inline predictions work like other commands (git, gh, etc.)
201- - Relative paths reduce visual noise significantly
202- - Full context still available in tooltips
203- - Performance maintained: <10ms for predictor responses
204-
205- ### Phase 17.8: Partial Command Predictions
206- ** Status** : ✅ ** COMPLETE** (2025-11-09)
207- ** Priority** : Medium
208- ** Estimated Effort** : 8-12 hours (Actual: ~ 2 hours)
209-
210- ** Goal** : Show inline predictions for partial commands (e.g., typing "g" suggests "git", "gh", "gt").
211-
212- ** Why This Matters** :
213- - Saves keystrokes for frequently-used commands
214- - Improves discoverability of available commands
215- - Complements existing argument/workflow predictions
216-
217- ** Current Behavior** : Inline predictions only show after command + space (e.g., "git "). Partial commands like "g" get no inline suggestions.
218-
219- ** Architecture** :
220- ``` csharp
221- // Extend src/PSCue.Module/CommandPredictor.cs (~100 lines)
222- public override SuggestionPackage GetSuggestion (
223- PredictionClient client ,
224- PredictionContext context ,
225- CancellationToken cancellationToken )
226- {
227- var commandLine = context .InputAst .Extent .Text ;
228-
229- // NEW: If line contains no space, suggest full commands
230- if (! commandLine .Contains (' ' ))
231- {
232- var partial = commandLine .Trim ();
233- if (string .IsNullOrEmpty (partial ))
234- return null ; // Empty prompt = workflow predictions only
235-
236- return GetPartialCommandSuggestions (partial );
237- }
238-
239- // Existing: Suggest arguments/next commands
240- // ...
241- }
242-
243- private SuggestionPackage GetPartialCommandSuggestions (string partial )
244- {
245- // 1. Query ArgumentGraph for commands starting with partial
246- // 2. Query WorkflowLearner for recently used commands
247- // 3. Filter by StartsWith(partial, StringComparison.OrdinalIgnoreCase)
248- // 4. Score by frequency + recency
249- // 5. Return top 5 suggestions
250- }
251- ```
252-
253- ** Data Sources** :
254- 1 . ** Learned Commands** : Query ` ArgumentGraph ` for commands matching partial
255- - Use existing frequency + recency scoring
256- 2 . ** Workflow History** : Query ` WorkflowLearner ` for recently executed commands
257- - Boost commands used in last 10 minutes (1.5× multiplier)
258- 3 . ** Known Commands** : Fallback to PSCue's hardcoded command list (git, gh, az, etc.)
259- - Lower priority (0.5× multiplier) - prefer learned commands
260-
261- ** Tasks** :
262- 1 . [ ] Add partial command detection to ` CommandPredictor.GetSuggestion() ` (~ 30 lines)
263- 2 . [ ] Implement ` GetPartialCommandSuggestions() ` method (~ 70 lines)
264- - [ ] Query ArgumentGraph for matching commands
265- - [ ] Query WorkflowLearner for recent commands
266- - [ ] Apply filtering and scoring
267- - [ ] Return top 5 suggestions
268- 3 . [ ] Add configuration environment variable
269- - [ ] ` PSCUE_PARTIAL_COMMAND_PREDICTIONS ` (default: true)
270- 4 . [ ] Write tests (~ 10 test cases)
271- - [ ] Single-character partial ("g" → "git", "gh")
272- - [ ] Multi-character partial ("do" → "docker", "dotnet")
273- - [ ] Case-insensitive matching ("GI" → "git")
274- - [ ] Scoring accuracy (frequency + recency)
275- - [ ] Empty prompt (no suggestions)
276- - [ ] Workflow boost for recent commands
277- 5 . [ ] Documentation updates
278- - [ ] README: Add partial command section
279- - [ ] CLAUDE.md: Update feature list
280-
281- ** Example Behavior** :
282- ``` powershell
283- # User types "g" (no space, no Tab)
284- PS> g█
285- # Inline predictions:
286- # → git (most frequent)
287- # → gh (second most frequent)
288- # → gt (least frequent)
289-
290- # User types "doc" (no space, no Tab)
291- PS> doc█
292- # → docker (exact prefix match)
293-
294- # User types "GI" (case-insensitive)
295- PS> GI█
296- # → git (case-insensitive match)
297-
298- # Empty prompt - no command suggestions (only workflow predictions)
299- PS> █
300- # → git status (workflow prediction, not command prediction)
301- ```
302-
303- ** Performance Targets** :
304- - Query time: <5ms (same as existing inline predictions)
305- - No noticeable typing lag
306- - Efficient filtering with StartsWith() + case-insensitive comparison
307-
308- ** Edge Cases** :
309- - Empty prompt: No command suggestions (reserve for workflow predictions only)
310- - Single space: No command suggestions (move to argument suggestions)
311- - Very long partial (10+ chars): Likely not a command, no suggestions
312- - No matching commands: Return empty (no fallback noise)
313-
314- ** Configuration** :
315- ``` powershell
316- # Enable/disable partial command predictions (default: true)
317- $env:PSCUE_PARTIAL_COMMAND_PREDICTIONS = "true"
318- ```
319-
320- ** Dependencies** : None (uses existing ArgumentGraph + WorkflowLearner)
321-
322- ** Success Criteria** :
323- - ✅ Partial commands show relevant suggestions
324- - ✅ Scoring prioritizes frequent/recent commands
325- - ✅ Performance meets <5ms target
326- - ✅ No interference with existing workflow predictions
327- - ✅ All tests passing
328- - ✅ User can disable feature via environment variable
329-
330- ** Follow-up Questions** (to test after implementation):
331- - Is this helpful or noisy? (May need user feedback to decide)
332- - Should we show command suggestions at empty prompt? (Currently reserved for workflows)
333- - Should we limit to commands with high confidence? (Avoid suggesting rarely-used commands)
334-
335- ** Completed** :
336- - [x] Added ` GetPartialCommandSuggestions() ` method to CommandPredictor
337- - [x] Integrated with existing suggestion pipeline (merges with genericSuggestions)
338- - [x] Environment variable configuration: ` PSCUE_PARTIAL_COMMAND_PREDICTIONS ` (default: true)
339- - [x] Scoring algorithm: 60% frequency + 40% recency, with 1.5× boost for recently used commands
340- - [x] Filters: Very long partials (>10 chars) ignored, case-insensitive matching
341- - [x] Comprehensive unit tests (7 test cases covering core functionality)
342- - [x] Performance: <5ms target met (reuses existing ArgumentGraph queries)
343-
344- ** Files Modified** :
345- - ` src/PSCue.Module/CommandPredictor.cs ` (~ 100 lines added)
346- - ` GetPartialCommandSuggestions() ` method
347- - ` FormatLastUsed() ` helper method
348- - Integration into GetSuggestion() workflow
349- - ` test/PSCue.Module.Tests/CommandPredictorTests.cs ` (7 new tests)
350-
351- ** Key Achievements** :
352- - Frequency-based command suggestions from learned data
353- - Works without workflow context (fresh sessions, unrelated commands)
354- - Complements existing workflow predictions
355- - User-friendly tooltips show usage stats ("Used X times, last: Xm ago")
356- - Can be disabled via environment variable
357-
358- ---
359-
36040### Phase 17.9: Tab Completion on Empty Input
36141** Status** : Planned
36242** Priority** : Medium-Low
@@ -445,27 +125,9 @@ PS> █ # Press Tab
445125- [ ] Background pre-computation for heavy ML
446126- [ ] Research ONNX Runtime + NativeAOT compatibility
447127
448- ### Phase 18.1: Dynamic Workflow Learning
449- ** Status** : ✅ ** COMPLETE** (2025-11-07)
450-
451- ** Completed** :
452- - ✅ WorkflowLearner.cs core infrastructure (~ 500 lines)
453- - ✅ SQLite schema extension (workflow_transitions table - 8 tables total)
454- - ✅ Module initialization and lifecycle integration
455- - ✅ FeedbackProvider integration (automatic learning)
456- - ✅ CommandPredictor integration (inline predictions at empty prompt)
457- - ✅ Configuration via environment variables (4 new vars)
458- - ✅ PersistenceManager save/load methods
459- - ✅ Comprehensive testing (35+ unit tests)
460- - ✅ PowerShell module functions (5 functions: Get/Stats/Clear/Export/Import)
461- - ✅ Documentation updates (CLAUDE.md, README.md, TODO.md)
462-
463- ** Phase 18.2 (Time-Based Detection)** also completed as part of 18.1:
464- - ✅ Time-sensitive scoring with timing pattern awareness
465- - ✅ Time delta tracking in database
466- - ✅ Confidence adjustments based on timing (1.5× to 0.8× boost)
467-
468- ** See** : [ COMPLETED.md] ( docs/COMPLETED.md ) for detailed implementation notes
128+ ---
129+
130+ ## Phase 18: Workflow Improvements
469131
470132### Phase 18.3: Workflow Chains (3+ Commands)
471133** Status** : Planned
0 commit comments