Skip to content

Commit 715a95c

Browse files
lucaspimentelclaude
andcommitted
docs: archive completed phases to COMPLETED.md
Move Phases 17.5-17.8 and 18.1-18.2 from TODO.md to docs/COMPLETED.md: - Phase 17.5: Smart Directory Navigation (pcd command) - Phase 17.6: Enhanced PCD Algorithm - Phase 17.7: PCD Inline Predictions & Relative Paths - Phase 17.8: Partial Command Predictions - Phase 18.1: Dynamic Workflow Learning (already archived) Updated TODO.md Current Status to show v0.3.0 features as archived. Removed ~320 lines of completed implementation details. TODO.md now focuses only on planned work (17.9, 17.10, 18.3+). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
1 parent 1e71ffa commit 715a95c

File tree

2 files changed

+207
-352
lines changed

2 files changed

+207
-352
lines changed

TODO.md

Lines changed: 14 additions & 352 deletions
Original file line numberDiff line numberDiff line change
@@ -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

Comments
 (0)