PHASE_CTS_MCP_3_PLANNING.md•54.1 kB
# PHASE CTS_MCP_3: Cross-Project Signal Intelligence & Refactoring Automation
## Advanced signal analysis with project-wide tracking, unused signal detection, and AI-powered refactoring recommendations
**Status**: 🟡 PLANNING
**Priority**: HIGH
**Phase Duration**: 5-6 weeks (AI-assisted) | 12-14 weeks (traditional)
**Dependencies**: Phase CTS_MCP_2 Complete
**Phase Owner**: CTS MCP Development Team
**Created**: 2025-10-30
**Updated**: 2025-10-30
**Target Start**: 2025-11-04
**Target Completion**: 2025-12-13
**Actual Start**: N/A
**Actual Completion**: N/A
**Related Documentation**:
- **Project Vision**: CTS MCP Server for Godot Signal Architecture Analysis
- **Previous Phase**: [PHASE_CTS_MCP_2_COMPLETION_REPORT.md](./PHASE_CTS_MCP_2_COMPLETION_REPORT.md)
- **Next Phase**: PHASE_CTS_MCP_4_PLANNING.md (AI-Powered Code Generation)
- **Master Roadmap**: CTS_MCP_ROADMAP.md
- **Phase Index**: PHASE_CTS_MCP_3_INDEX.md
---
## 📋 Executive Summary
### Phase Vision
Phase 3 transforms the CTS MCP server from a **file-level signal parser** into a **project-wide signal intelligence system**. Building on Phase 2's AST-level parsing and clustering, Phase 3 extends analysis to entire Godot projects, tracking signal definitions, emissions, and connections across all `.gd` files. This enables detection of unused signals, orphaned connections, and refactoring opportunities—empowering developers to maintain clean, efficient signal architectures as projects grow.
**Strategic Importance**: Signal systems are the backbone of Godot architecture. As projects scale to 100+ scripts with 300+ signals, manual tracking becomes error-prone. Phase 3 automates signal architecture validation, enabling safe refactoring and preventing signal bloat.
**End State Vision**: Developers can:
1. **Visualize** the entire project's signal graph (all files, all connections)
2. **Detect** unused signals automatically (never emitted or connected)
3. **Refactor** safely with AI-powered rename/merge/delete suggestions
4. **Monitor** signal health with trend analysis and alerts
5. **Clean up** legacy code with confidence (no downstream breakage)
**User-Facing Impact**:
- **Before Phase 3**: "I have 200 signals across 80 files. Are any unused? Which can I safely delete?"
- **After Phase 3**: One-click unused signal report, safe deletion suggestions, automated refactoring
### Problem Context
**Current State Before Phase 3** (Phase 2 capabilities):
- ✅ Single-file signal extraction with 100% accuracy
- ✅ Clustered visualization for <300 signals
- ✅ Dependency graph for file-level connections
- ❌ **No cross-file signal tracking** (can't find all `.emit()` calls project-wide)
- ❌ **No unused signal detection** (manual inspection required)
- ❌ **No refactoring automation** (risky manual renames/deletions)
**Pain Points Addressed**:
1. **Signal Bloat**: Projects accumulate 50-100 unused signals over time (10-20% of total)
- Manual cleanup takes 4-8 hours per cleanup session
- Risk of breaking working code (missed connections)
- Phase 3 automates detection and safe deletion (30min cleanup)
2. **Refactoring Fear**: Developers avoid signal renames due to breakage risk
- "I want to rename `player_health_changed` to `player_damaged` but it's used in 15 files"
- Manual search-replace error rate: 15-20% (missed connections, typos)
- Phase 3 provides AI-powered refactoring with 100% accuracy
3. **Signal Sprawl**: Similar signals with different names (`player_died` vs `player_death` vs `on_player_death`)
- 20-30% of signals are near-duplicates
- Consolidation requires manual analysis (2-3 hours per review)
- Phase 3 detects duplicates and suggests merges (10min review)
**Opportunity Unlocked**:
- Safe, automated signal architecture maintenance
- Confidence to refactor legacy code
- Prevention of signal bloat (continuous monitoring)
- 10x faster signal cleanup workflows
### Phase Scope Overview
**Total HOPs in Phase**: 7 HOPs (3 foundation + 3 features + 1 polish)
**Total Sub-HOPs**: 4 sub-HOPs (2 complex HOPs split)
**Estimated Total Lines**: 4,200 implementation + 2,800 tests + 900 documentation
**Critical Path HOPs**: 3.1, 3.2a, 3.2b, 3.3, 3.7 (5 HOPs gate phase completion)
**Scope Breakdown**:
```
Foundation HOPs (3.1 - 3.2b): 3 HOPs (2 sub-HOPs), 2 weeks
├─ Cross-file signal tracking infrastructure
├─ Global signal graph construction
└─ Project-wide AST parsing optimization
Feature HOPs (3.3 - 3.5): 3 HOPs, 2.5 weeks
├─ Unused signal detection and reporting
├─ Refactoring suggestion engine
└─ Hierarchical clustering with labeling
Polish HOPs (3.6 - 3.7): 2 HOPs (2 sub-HOPs), 0.5 weeks
├─ Performance alerts and monitoring
├─ Documentation and completion report
└─ Production readiness validation
```
### Success Criteria (Phase-Level)
**Must-Have** (Phase Blockers - Cannot Complete Phase Without These):
- [ ] All 7 critical path HOPs completed (3.1, 3.2a, 3.2b, 3.3, 3.7)
- [ ] Project-wide signal tracking validates 500+ signal project (<5s scan time)
- [ ] Unused signal detection achieves ≥95% precision (low false positives)
- [ ] Refactoring suggestions achieve ≥98% accuracy (validated with test suite)
- [ ] Phase-level performance targets met (<5s project scan, <1s graph render)
- [ ] 0 compilation errors across all phase code (TypeScript strict mode)
- [ ] All 85+ phase tests passing (≥90% coverage minimum)
- [ ] Phase documentation complete (ADRs, signal contracts, completion report)
**Nice-to-Have** (Phase Enhancements - Defer to Phase 4 if Time-Constrained):
- [ ] Real-time signal monitoring (watch mode for project changes)
- [ ] GitHub integration (signal health checks in PRs)
- [ ] Signal naming convention linter
- [ ] Cross-project signal comparison (compare two Godot projects)
**Quality Gates**:
- [ ] Code review completion rate: 100%
- [ ] Test coverage: ≥90% (phase average, up from 93.6% in Phase 2)
- [ ] Signal contract compliance: 100% (all new signals documented)
- [ ] CTS compliance: 100% (all HOPs <750 lines, files <500 lines)
- [ ] Performance regression: 0% (no slowdowns vs Phase 2)
- [ ] False positive rate: <5% (unused signal detection)
**Documentation Gates**:
- [ ] 3 ADRs created (graph construction, refactoring engine, clustering v2)
- [ ] API documentation complete (all public methods typed and documented)
- [ ] Integration guides for cross-file tracking and refactoring
- [ ] Completion report with metrics, lessons learned, Phase 4 recommendations
- [ ] Migration guide from Phase 2 to Phase 3
---
## 🎯 Phase Goals & Objectives
### Strategic Goals (Why This Phase Exists)
1. **Enable Safe Signal Architecture Evolution**
- **Strategic Value**: Godot projects evolve over 6-24 months. Signal architectures need continuous refactoring to prevent technical debt.
- **Current Blocker**: Fear of breaking working code prevents refactoring (15-20% error rate with manual changes).
- **Phase 3 Solution**: AI-powered refactoring with 98%+ accuracy enables confident evolution.
- **Business Impact**: 10x faster refactoring workflows (30min vs 4-8 hours per cleanup session).
2. **Prevent Signal Bloat Through Automated Detection**
- **Strategic Value**: Unused signals accumulate at 5-10 signals per month (10-20% of total over 12 months).
- **Current Blocker**: Manual detection requires reviewing 500+ signals across 80+ files (4-8 hours per review).
- **Phase 3 Solution**: Automated unused signal detection with ≥95% precision (<5% false positives).
- **Business Impact**: Continuous monitoring prevents bloat (proactive vs reactive cleanup).
3. **Build Foundation for AI-Powered Code Generation (Phase 4)**
- **Strategic Value**: Phase 4 will generate Godot code from natural language. Requires understanding of signal architecture.
- **Current Blocker**: Phase 2 only understands single-file signals (can't generate cross-file signal connections).
- **Phase 3 Solution**: Global signal graph enables validation of generated code (prevents invalid emissions/connections).
- **Business Impact**: Phase 3 is prerequisite for Phase 4's AI code generation.
### Tactical Objectives (What This Phase Delivers)
**Foundation Objectives** (HOPs 3.1 - 3.2b):
- [ ] **HOP 3.1**: Project-wide AST parsing infrastructure
- Scan all `.gd` files in project (<5s for 500-file project)
- Incremental parsing (only changed files)
- Cache invalidation on file changes
- **Target**: <5s initial scan, <500ms incremental updates
- [ ] **HOP 3.2a**: Signal graph construction (definitions + emissions)
- Track signal definitions across all files
- Detect `.emit()` calls project-wide
- Build emission graph (which signals emit which)
- **Target**: Graph construction <1s for 300 signals
- [ ] **HOP 3.2b**: Signal graph construction (connections)
- Detect `.connect()` calls project-wide
- Track connection targets (method names, lambdas)
- Build connection graph (who listens to what)
- **Target**: Graph construction <1s for 500 connections
**Feature Objectives** (HOPs 3.3 - 3.5):
- [ ] **HOP 3.3**: Unused signal detection
- Detect signals with zero `.emit()` calls (never emitted)
- Detect signals with zero `.connect()` listeners (never connected)
- Report with file locations and suggested deletions
- **Target**: ≥95% precision, <5% false positives
- [ ] **HOP 3.4**: Refactoring suggestion engine
- Similarity detection for duplicate signals (edit distance, semantic similarity)
- Naming convention validation (snake_case, verb tense consistency)
- Safe deletion suggestions (no downstream impact)
- **Target**: ≥98% suggestion accuracy
- [ ] **HOP 3.5**: Hierarchical clustering with auto-labeling
- 2-level clustering (clusters within clusters)
- Theme detection (file prefix, signal prefix analysis)
- Interactive drill-down UI
- **Target**: <500ms clustering for 300 signals
**Quality Objectives** (Throughout Phase):
- [ ] Test coverage ≥90% across all phase code
- [ ] Performance budget: <5s project scan, <1s graph render
- [ ] Memory budget: <100MB total (including graph storage)
- [ ] Signal contract documentation: 100% compliance (6 new signals)
- [ ] CTS compliance: 100% (all HOPs/sub-HOPs validated)
### Non-Goals (Explicitly Out of Phase Scope)
> **Critical**: These are explicitly deferred to maintain phase focus and prevent scope creep.
**Deferred to Phase 4 (AI Code Generation)**:
- ❌ Natural language to GDScript code generation
- ❌ AI-powered signal architecture recommendations
- ❌ Automated test generation for signals
- ❌ Code completion based on signal context
**Deferred to Future Phases (Phase 5+)**:
- ❌ Real-time signal monitoring (watch mode for file changes)
- ❌ GitHub integration (signal health checks in PRs)
- ❌ Cross-project signal comparison
- ❌ Signal performance profiling (runtime overhead analysis)
**Permanently Out of Scope**:
- ❌ Godot Engine modification (we work with existing engine, not fork)
- ❌ Custom signal syntax (use standard GDScript signals)
- ❌ Automatic code refactoring (suggestions only, user approves)
**Rationale for Deferrals**:
- **Phase 4 Deferrals**: Require Phase 3's global signal graph as foundation. Cannot generate code without understanding project-wide signal architecture.
- **Phase 5+ Deferrals**: Nice-to-have features that don't block core value. Real-time monitoring requires filesystem watchers (complex). GitHub integration requires API authentication (scope creep).
- **Permanent Scope**: Engine modification violates "work with existing tools" principle. Auto-refactoring without approval is risky (user must review changes).
---
## 🗺️ Phase Architecture Overview
### High-Level System Diagram
```
┌─────────────────────────────────────────────────────────────────────────┐
│ PHASE 3: CROSS-PROJECT SIGNAL INTELLIGENCE - SYSTEM ARCHITECTURE │
│ │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ Foundation Layer (HOPs 3.1 - 3.2b) │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ Project │───▶│ Signal Graph │───▶│ Graph │ │ │
│ │ │ Scanner │ │ Builder │ │ Cache │ │ │
│ │ │ (3.1) │ │ (3.2a, 3.2b) │ │ │ │ │
│ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │
│ │ │ │ │ │ │
│ │ │ Tree-sitter AST │ Graph Data │ Serialization │ │
│ │ ▼ ▼ ▼ │ │
│ │ All .gd files ────▶ Definitions ◀──┐ JSON Cache │ │
│ │ in project Emissions │ (versioned) │ │
│ │ Connections ───┘ │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ Feature Layer (HOPs 3.3 - 3.5) │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ Unused │◀───│ Refactoring │◀───│ Hierarchical │ │ │
│ │ │ Detector │ │ Engine │ │ Clustering │ │ │
│ │ │ (3.3) │ │ (3.4) │ │ (3.5) │ │ │
│ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │
│ │ │ │ │ │ │
│ │ │ Graph Analysis │ Suggestions │ 2-Level Clusters │ │
│ │ ▼ ▼ ▼ │ │
│ │ Zero emissions Rename/Merge Cluster Themes │ │
│ │ Zero connections Safe deletions Drill-down UI │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ Integration Layer (HOPs 3.6 - 3.7) │ │
│ │ ┌──────────────────────────────────────────────────────────────┐ │ │
│ │ │ EventBus / SignalBus (Phase 3 Signal Contracts) │ │ │
│ │ │ • project:scan_started(project_path, file_count) │ │ │
│ │ │ • project:scan_completed(graph, scan_time) │ │ │
│ │ │ • analyzer:unused_detected(unused_signals, confidence) │ │ │
│ │ │ • refactor:suggestion_generated(suggestion, accuracy) │ │ │
│ │ │ • cluster:hierarchy_computed(root_cluster, depth) │ │ │
│ │ │ • perf:degradation_alert(metric, old, new, threshold) │ │ │
│ │ └──────────────────────────────────────────────────────────────┘ │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ External Integrations │ │
│ │ • Phase 2: Tree-sitter Bridge, Signal Extractor │ │
│ │ • Phase 2: Clustered Signal Map Renderer (enhanced in 3.5) │ │
│ │ • MCP Protocol: New tools (analyze_project, suggest_refactoring) │ │
│ │ • VS Code: Webview for hierarchical cluster visualization │ │
│ └────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
```
### Phase-Level Signal Architecture
**CRITICAL**: Phase 3 signals enable project-wide analysis coordination.
```typescript
// EventBus signals (MCP server internal events)
// Location: src/signals/phase3_signals.ts
// Phase 3 Signal Contracts
/** Foundation Signals (HOPs 3.1 - 3.2b) **/
// Emitted when project scan begins
// @param project_path: Absolute path to Godot project root
// @param file_count: Number of .gd files to scan
// @param scan_mode: 'full' | 'incremental'
interface ProjectScanStartedPayload {
project_path: string;
file_count: number;
scan_mode: 'full' | 'incremental';
timestamp: number;
}
signal project:scan_started(payload: ProjectScanStartedPayload)
// Emitted when project scan completes successfully
// @param graph: Global signal graph (definitions, emissions, connections)
// @param scan_time: Total scan duration in milliseconds
// @param cache_hit_rate: Percentage of files served from cache
interface ProjectScanCompletedPayload {
graph: SignalGraph;
scan_time: number;
cache_hit_rate: number;
timestamp: number;
}
signal project:scan_completed(payload: ProjectScanCompletedPayload)
// Emitted when scan fails (parse errors, permissions, etc.)
// @param error: Error details
// @param files_scanned: Number of files processed before failure
interface ProjectScanFailedPayload {
error: Error;
files_scanned: number;
failed_file: string | null;
timestamp: number;
}
signal project:scan_failed(payload: ProjectScanFailedPayload)
/** Feature Signals (HOPs 3.3 - 3.5) **/
// Emitted when unused signals detected
// @param unused_signals: Array of signal definitions with zero usage
// @param confidence: Detection confidence (0-1, based on graph completeness)
interface UnusedDetectedPayload {
unused_signals: Array<{
name: string;
file: string;
line: number;
reason: 'never_emitted' | 'never_connected' | 'both';
}>;
confidence: number;
timestamp: number;
}
signal analyzer:unused_detected(payload: UnusedDetectedPayload)
// Emitted when refactoring suggestion generated
// @param suggestion: Refactoring recommendation
// @param accuracy: Estimated accuracy (0-1, based on similarity score)
interface RefactorSuggestionPayload {
suggestion: {
type: 'rename' | 'merge' | 'delete';
target_signal: string;
replacement: string | null;
affected_files: string[];
confidence: number;
};
accuracy: number;
timestamp: number;
}
signal refactor:suggestion_generated(payload: RefactorSuggestionPayload)
// Emitted when hierarchical clustering completes
// @param root_cluster: Top-level cluster with nested children
// @param depth: Maximum cluster depth
// @param labels: Auto-generated cluster labels
interface HierarchyComputedPayload {
root_cluster: ClusterNode;
depth: number;
labels: Map<number, string>;
timestamp: number;
}
signal cluster:hierarchy_computed(payload: HierarchyComputedPayload)
/** Performance Signals (HOPs 3.6 - 3.7) **/
// Emitted when performance degradation detected
// @param metric: Performance metric name
// @param old_value: Previous measurement
// @param new_value: Current measurement
// @param threshold: Degradation threshold percentage
interface DegradationAlertPayload {
metric: string;
old_value: number;
new_value: number;
threshold: number;
degradation_pct: number;
timestamp: number;
}
signal perf:degradation_alert(payload: DegradationAlertPayload)
/** Phase Lifecycle Signals **/
// Emitted when Phase 3 systems initialized
signal phase3:ready()
// Emitted when Phase 3 shutting down
signal phase3:shutdown()
```
**Signal Contract Documentation**: All signals documented in `docs/signals/PHASE_3_SIGNAL_CONTRACTS.md`
### Major Components & Responsibilities
**Foundation Components** (HOPs 3.1 - 3.2b):
1. **Project Scanner** (`src/scanner/project_scanner.ts`) - HOP 3.1
- **Responsibility**: Scan all `.gd` files in Godot project
- **Input**: Project root path
- **Output**: Array of AST trees (one per file)
- **Performance**: <5s for 500-file project
- **Caching**: Incremental scanning (only changed files)
- **Dependencies**: Phase 2 TreeSitterBridge
- **Signals Emitted**: `project:scan_started`, `project:scan_completed`, `project:scan_failed`
2. **Signal Graph Builder** (`src/graph/signal_graph_builder.ts`) - HOP 3.2a, 3.2b
- **Responsibility**: Construct global signal graph from ASTs
- **Input**: Array of AST trees
- **Output**: `SignalGraph` (definitions, emissions, connections)
- **Performance**: <1s for 300 signals
- **Graph Structure**:
```typescript
interface SignalGraph {
definitions: Map<string, SignalDefinition[]>; // signal name → definitions (may be multiple files)
emissions: Map<string, EmissionSite[]>; // signal name → .emit() call sites
connections: Map<string, ConnectionSite[]>; // signal name → .connect() call sites
orphans: string[]; // signals defined but never used
}
```
- **Dependencies**: Phase 2 SignalExtractor
- **Signals Emitted**: `project:scan_completed`
3. **Graph Cache Manager** (`src/graph/graph_cache.ts`) - HOP 3.1
- **Responsibility**: Cache signal graphs with versioning
- **Input**: `SignalGraph` + project metadata
- **Output**: Serialized JSON cache
- **Performance**: <100ms save/load for 300-signal graph
- **Invalidation**: File mtime, parser version, graph schema version
- **Dependencies**: Phase 2 Metadata system
- **Signals Emitted**: `cache:invalidation_triggered`
**Feature Components** (HOPs 3.3 - 3.5):
4. **Unused Signal Detector** (`src/analysis/unused_detector.ts`) - HOP 3.3
- **Responsibility**: Identify signals with zero usage
- **Input**: `SignalGraph`
- **Output**: Array of unused signals with reasons
- **Algorithm**:
```
for each signal_name in graph.definitions:
if graph.emissions[signal_name].length == 0:
flag as "never_emitted"
if graph.connections[signal_name].length == 0:
flag as "never_connected"
if both flags set:
flag as "orphan" (highest confidence)
```
- **Performance**: <500ms for 300 signals
- **Confidence Scoring**: 0.95 for orphans, 0.80 for single-flag
- **Dependencies**: SignalGraph
- **Signals Emitted**: `analyzer:unused_detected`
5. **Refactoring Engine** (`src/refactor/suggestion_engine.ts`) - HOP 3.4
- **Responsibility**: Generate rename/merge/delete suggestions
- **Input**: `SignalGraph` + coding standards
- **Output**: Array of refactoring suggestions with accuracy scores
- **Algorithms**:
- **Similarity**: Levenshtein distance + semantic embedding (word2vec)
- **Naming**: Snake_case validation, verb tense consistency
- **Safety**: Impact analysis (count affected files/lines)
- **Performance**: <1s for 300 signals
- **Accuracy Target**: ≥98% (validated with test corpus)
- **Dependencies**: SignalGraph
- **Signals Emitted**: `refactor:suggestion_generated`
6. **Hierarchical Clusterer** (`src/clustering/hierarchical_clusterer.ts`) - HOP 3.5
- **Responsibility**: 2-level clustering with auto-labeling
- **Input**: `SignalGraph` nodes/edges
- **Output**: `ClusterTree` (root + children)
- **Algorithm**: Greedy modularity (Phase 2) → Recursive subdivision
- **Labeling**: File prefix analysis (`player_*` → "Player Signals"), signal prefix detection
- **Performance**: <500ms for 300 signals
- **Dependencies**: Phase 2 CommunityDetection (enhanced)
- **Signals Emitted**: `cluster:hierarchy_computed`
**Polish Components** (HOPs 3.6 - 3.7):
7. **Performance Monitor** (`src/monitoring/performance_monitor.ts`) - HOP 3.6
- **Responsibility**: Track metrics and alert on degradation
- **Input**: Performance samples from Phase 2 pipeline
- **Output**: Alerts when metrics degrade >20%
- **Metrics Monitored**: Scan time, graph build time, cluster time, memory usage
- **Alert Thresholds**: Configurable (default 20% degradation)
- **Dependencies**: Phase 2 PerformancePipeline
- **Signals Emitted**: `perf:degradation_alert`
### Data Flow Diagram
```
Godot Project (500 .gd files)
│
▼
[Project Scanner] ──signal:scan_started──▶ EventBus
│ (HOP 3.1)
│ Tree-sitter parse all files
│ Incremental: only changed files
▼
AST Trees (cached)
│
▼
[Signal Graph Builder] ──signal:scan_completed──▶ EventBus
│ (HOP 3.2a, 3.2b)
│ Extract: definitions, emissions, connections
▼
Global Signal Graph
│
├──▶ [Unused Detector] ──signal:unused_detected──▶ EventBus
│ │ (HOP 3.3)
│ │ Identify zero-usage signals
│ ▼
│ Unused Signal Report
│
├──▶ [Refactoring Engine] ──signal:suggestion_generated──▶ EventBus
│ │ (HOP 3.4)
│ │ Similarity + naming analysis
│ ▼
│ Refactoring Suggestions
│
└──▶ [Hierarchical Clusterer] ──signal:hierarchy_computed──▶ EventBus
│ (HOP 3.5)
│ 2-level clustering + labeling
▼
Cluster Tree
│
▼
[D3 Renderer (enhanced)]
│
▼
Interactive Visualization (drill-down UI)
```
### Integration Points
**With Previous Phases**:
- **Phase 2 Integration**: Extends tree-sitter parsing from single-file to project-wide
- Reuses: `TreeSitterBridge`, `SignalExtractor`, `ParserDiagnostics`
- Enhances: `CommunityDetection` (hierarchical), `D3SignalMapV2` (drill-down)
- New capability: Cross-file tracking (Phase 2 only understood single files)
**With Addons** (see `docs/Architecture/ADDON_MASTERLIST.md`):
- **Signal Lens**: Validates signal emission order in real-time
- Phase 3 provides global graph → Signal Lens highlights unused signals in editor
- Integration point: Export graph to Signal Lens format (JSON)
- **GUT Testing**: Tests refactoring suggestions with deterministic corpus
- Phase 3 suggests rename → GUT validates all tests still pass
- Integration point: Test suite validation API
**With External Systems** (MCP servers, CI/CD, etc.):
- **Shrimp MCP**: Export refactoring suggestions as Shrimp tasks
- User reviews suggestions → Approve → Shrimp creates refactoring tasks
- Integration point: `CTS_Export_to_Shrimp` tool (enhanced)
- **VS Code**: New webview for hierarchical cluster drill-down
- Interactive tree navigation (expand/collapse clusters)
- Integration point: `CTS_Render_Artifact` tool (new artifact type: `hierarchical_cluster`)
---
## 📊 Phase HOPs Breakdown
### HOP Dependency Graph
```
┌──────────────────────────────────────────────────────────────────────────┐
│ Phase 3 - HOP Dependency Graph │
│ │
│ 3.1 Project Scanner (Foundation) │
│ │ │
│ ├──▶ 3.2a Signal Graph (Definitions + Emissions) ──┐ │
│ │ │ │
│ └──▶ 3.2b Signal Graph (Connections) ───────────────┼──▶ 3.3 Unused │
│ │ Detector │
│ │ │ │
│ ├──▶ 3.4 Refactor│
│ │ Engine │
│ │ │ │
│ └──▶ 3.5 Hierarch│
│ Clustering │
│ │ │
│ 3.6a Performance Alerts ──────────────────────────────────┐ │ │
│ │ │ │
│ 3.6b Monitoring Dashboard ────────────────────────────────┼────┘ │
│ │ │
│ └──▶ 3.7 Final│
│ Polish │
│ │
│ Critical Path (RED): 3.1 → 3.2a → 3.2b → 3.3 → 3.7 │
│ Feature Track (BLUE): 3.4, 3.5 (parallel with 3.3) │
│ Polish Track (GREEN): 3.6a, 3.6b (parallel with 3.5) │
└──────────────────────────────────────────────────────────────────────────┘
```
### Critical Path HOPs (Must Complete for Phase Success)
#### HOP 3.1: Project-Wide Scanner Infrastructure
- **Purpose**: Scan all `.gd` files in Godot project and construct AST forest
- **Duration**: 12 hours
- **Dependencies**: Phase 2 complete (TreeSitterBridge)
- **Deliverables**:
- `ProjectScanner` class (250 LOC)
- Incremental scanning logic (150 LOC)
- Graph cache manager (200 LOC)
- 15 tests
- **CTS Status**: ✅ Single HOP, 600 lines estimated (implementation + tests)
- **Planning Document**: [HOP_3_1_PROJECT_SCANNER.md](./hops/HOP_3_1_PROJECT_SCANNER.md)
- **Priority**: CRITICAL (blocks all graph construction)
- **Performance Target**: <5s for 500 files (initial scan), <500ms (incremental)
#### HOP 3.2a: Signal Graph Builder - Definitions & Emissions
- **Purpose**: Extract signal definitions and `.emit()` calls from AST forest
- **Duration**: 10 hours
- **Dependencies**: HOP 3.1
- **Deliverables**:
- `SignalGraphBuilder` class (300 LOC)
- Definition extraction (100 LOC)
- Emission detection (150 LOC)
- 12 tests
- **CTS Status**: ✅ Single HOP, 550 lines estimated
- **Planning Document**: [HOP_3_2a_GRAPH_BUILDER_DEFINITIONS.md](./hops/HOP_3_2a_GRAPH_BUILDER_DEFINITIONS.md)
- **Priority**: CRITICAL (enables unused detection)
- **Performance Target**: <1s for 300 signals
#### HOP 3.2b: Signal Graph Builder - Connections
- **Purpose**: Extract `.connect()` calls and build connection graph
- **Duration**: 10 hours
- **Dependencies**: HOP 3.2a
- **Deliverables**:
- Connection detection (200 LOC)
- Lambda connection handling (150 LOC)
- Graph merging (100 LOC)
- 12 tests
- **CTS Status**: ✅ Single HOP, 450 lines estimated
- **Planning Document**: [HOP_3_2b_GRAPH_BUILDER_CONNECTIONS.md](./hops/HOP_3_2b_GRAPH_BUILDER_CONNECTIONS.md)
- **Priority**: CRITICAL (completes signal graph)
- **Performance Target**: <1s for 500 connections
#### HOP 3.3: Unused Signal Detection Engine
- **Purpose**: Identify signals with zero emissions or connections
- **Duration**: 8 hours
- **Dependencies**: HOP 3.2b
- **Deliverables**:
- `UnusedDetector` class (200 LOC)
- Confidence scoring (100 LOC)
- Report generation (150 LOC)
- 10 tests
- **CTS Status**: ✅ Single HOP, 450 lines estimated
- **Planning Document**: [HOP_3_3_UNUSED_DETECTOR.md](./hops/HOP_3_3_UNUSED_DETECTOR.md)
- **Priority**: CRITICAL (primary user value)
- **Accuracy Target**: ≥95% precision (<5% false positives)
#### HOP 3.7: Final Polish, Documentation & Completion
- **Purpose**: Integration testing, documentation, completion report
- **Duration**: 8 hours
- **Dependencies**: ALL previous HOPs complete
- **Deliverables**:
- Integration tests (200 LOC)
- Performance validation (100 LOC)
- 3 ADRs (900 LOC documentation)
- Completion report (500 LOC)
- Migration guide (200 LOC)
- **CTS Status**: ✅ Single HOP, 400 lines code + 1600 lines docs
- **Planning Document**: [HOP_3_7_FINAL_POLISH.md](./hops/HOP_3_7_FINAL_POLISH.md)
- **Priority**: CRITICAL (phase cannot complete without this)
- **Quality Target**: 0 compilation errors, all tests passing
**Critical Path Total**: 48 hours (5 HOPs)
---
### Parallel Track HOPs (Can Develop Concurrently)
#### Feature Track: Refactoring & Clustering
**HOP 3.4: Refactoring Suggestion Engine**
- **Purpose**: Generate rename/merge/delete suggestions with accuracy scores
- **Duration**: 12 hours
- **Dependencies**: HOP 3.2b (needs signal graph)
- **Deliverables**:
- `RefactoringEngine` class (350 LOC)
- Similarity detection (Levenshtein + semantic) (200 LOC)
- Naming convention validation (150 LOC)
- 15 tests (with test corpus)
- **CTS Status**: ⚠️ Split into 3.4a (similarity), 3.4b (naming/safety) if >750 lines
- **Planning Document**: [HOP_3_4_REFACTORING_ENGINE.md](./hops/HOP_3_4_REFACTORING_ENGINE.md)
- **Priority**: MEDIUM (enhances Phase 3 but not MVP)
- **Parallel With**: HOP 3.3 (can develop simultaneously after 3.2b)
- **Accuracy Target**: ≥98% suggestion accuracy
**HOP 3.5: Hierarchical Clustering with Auto-Labeling**
- **Purpose**: 2-level clustering with theme detection for signal map
- **Duration**: 10 hours
- **Dependencies**: HOP 3.2b (needs signal graph)
- **Deliverables**:
- `HierarchicalClusterer` class (250 LOC)
- Theme detection (file/signal prefix analysis) (150 LOC)
- D3 drill-down renderer enhancement (200 LOC)
- 12 tests
- **CTS Status**: ✅ Single HOP, 600 lines estimated
- **Planning Document**: [HOP_3_5_HIERARCHICAL_CLUSTERING.md](./hops/HOP_3_5_HIERARCHICAL_CLUSTERING.md)
- **Priority**: MEDIUM (improves visualization quality)
- **Parallel With**: HOP 3.3, 3.4 (can develop simultaneously)
- **Performance Target**: <500ms for 300 signals
**Feature Track Total**: 22 hours (2 HOPs)
---
#### Polish Track: Performance Monitoring
**HOP 3.6a: Performance Degradation Alerts**
- **Purpose**: Automated alerts when metrics degrade >20%
- **Duration**: 6 hours
- **Dependencies**: HOP 3.1 (needs performance samples)
- **Deliverables**:
- `PerformanceMonitor` class (150 LOC)
- Threshold configuration (50 LOC)
- Alert generation (100 LOC)
- 8 tests
- **CTS Status**: ✅ Single HOP, 300 lines estimated
- **Planning Document**: [HOP_3_6a_PERF_ALERTS.md](./hops/HOP_3_6a_PERF_ALERTS.md)
- **Priority**: LOW (nice-to-have, can defer)
- **Parallel With**: ALL other HOPs (independent)
**HOP 3.6b: Performance Monitoring Dashboard**
- **Purpose**: Real-time dashboard for Phase 3 performance metrics
- **Duration**: 6 hours
- **Dependencies**: HOP 3.6a
- **Deliverables**:
- Dashboard React component (200 LOC)
- Metric visualization (D3 charts) (150 LOC)
- 6 tests
- **CTS Status**: ✅ Single HOP, 350 lines estimated
- **Planning Document**: [HOP_3_6b_PERF_DASHBOARD.md](./hops/HOP_3_6b_PERF_DASHBOARD.md)
- **Priority**: LOW (defer to Phase 4 if time-constrained)
- **Parallel With**: ALL other HOPs (independent)
**Polish Track Total**: 12 hours (2 HOPs)
---
### Phase HOP Summary Table
| HOP ID | Name | Type | Duration | Dependencies | CTS Status | Priority | Can Parallelize |
|--------|------|------|----------|--------------|------------|----------|-----------------|
| 3.1 | Project Scanner | Foundation | 12h | Phase 2 | ✅ Single | CRITICAL | No (foundation) |
| 3.2a | Graph Builder (Defs) | Foundation | 10h | 3.1 | ✅ Single | CRITICAL | No (critical path) |
| 3.2b | Graph Builder (Conns) | Foundation | 10h | 3.2a | ✅ Single | CRITICAL | No (critical path) |
| 3.3 | Unused Detector | Feature | 8h | 3.2b | ✅ Single | CRITICAL | No (critical path) |
| 3.4 | Refactoring Engine | Feature | 12h | 3.2b | ⚠️ May split | MEDIUM | Yes (with 3.3, 3.5) |
| 3.5 | Hierarchical Clustering | Feature | 10h | 3.2b | ✅ Single | MEDIUM | Yes (with 3.3, 3.4) |
| 3.6a | Performance Alerts | Polish | 6h | 3.1 | ✅ Single | LOW | Yes (with all) |
| 3.6b | Performance Dashboard | Polish | 6h | 3.6a | ✅ Single | LOW | Yes (with all) |
| 3.7 | Final Polish | Polish | 8h | ALL | ✅ Single | CRITICAL | No (final HOP) |
| **TOTAL** | **7 HOPs (9 if splits)** | - | **82h** | - | **100% CTS** | - | **~27% Parallelizable** |
**Phase Timeline Scenarios**:
- **Sequential (1 developer)**: 82 hours (~10 days)
- **Parallel (2 developers)**: 60 hours (~7.5 days) (Critical Path + Feature Track)
- **Parallel (3 developers)**: 54 hours (~7 days) (Critical + Feature + Polish)
---
## 🎯 CTS Compliance Analysis (Phase-Level)
### Phase Scope Validation
**Total Estimated Lines** (All HOPs Combined):
- **Implementation**: 4,200 lines across 18 files
- **Tests**: 2,800 lines (100+ tests total, 15 test files)
- **Documentation**: 1,900 lines (HOPs + ADRs + API docs + completion report)
- **TOTAL**: 8,900 lines (phase deliverables)
**Per-HOP CTS Compliance**:
- ✅ **8** HOPs comply as single-HOP (<750 lines total, all files <500 lines)
- ⚠️ **1** HOP may split (3.4: Refactoring Engine, estimated 700 lines → may need 3.4a/3.4b)
- ✅ **0** Sub-HOPs currently (may become 1 if 3.4 splits)
- 🎯 **100%** CTS Compliance Rate (after potential split)
**Largest HOPs** (Risk Assessment):
| HOP ID | Estimated Lines | Status | Split Strategy (if needed) |
|--------|----------------|--------|----------------------------|
| 3.4 | 700 lines | ⚠️ MONITOR | If >750: 3.4a (similarity) + 3.4b (naming/safety) |
| 3.1 | 600 lines | ✅ SINGLE | Within budget, no split needed |
| 3.5 | 600 lines | ✅ SINGLE | Within budget, no split needed |
### Signal-First Compliance (Phase-Level)
**Phase Signal Budget**: 9 new signals total
- **Foundation Signals**: 3 signals (project:scan_started, scan_completed, scan_failed)
- **Feature Signals**: 3 signals (analyzer:unused_detected, refactor:suggestion_generated, cluster:hierarchy_computed)
- **Performance Signals**: 1 signal (perf:degradation_alert)
- **Lifecycle Signals**: 2 signals (phase3:ready, phase3:shutdown)
**Signal Allocation Per HOP**:
| HOP ID | Signals Introduced | Signal Purpose | Contract Documentation |
|--------|-------------------|----------------|------------------------|
| 3.1 | 3 | Scan lifecycle (started, completed, failed) | PHASE_3_SIGNAL_CONTRACTS.md |
| 3.3 | 1 | Unused signal detection results | PHASE_3_SIGNAL_CONTRACTS.md |
| 3.4 | 1 | Refactoring suggestions | PHASE_3_SIGNAL_CONTRACTS.md |
| 3.5 | 1 | Hierarchical clustering results | PHASE_3_SIGNAL_CONTRACTS.md |
| 3.6a | 1 | Performance degradation alerts | PHASE_3_SIGNAL_CONTRACTS.md |
| 3.7 | 2 | Phase lifecycle | PHASE_3_SIGNAL_CONTRACTS.md |
| **TOTAL** | **9 signals** | - | **100% Documented** |
**Signal-First Workflow** (Phase-Level):
1. **Step 1**: Define ALL 9 phase signals upfront (before any HOP implementation)
2. **Step 2**: Document signal contracts in `docs/signals/PHASE_3_SIGNAL_CONTRACTS.md`
3. **Step 3**: Each HOP implements a subset of phase signals
4. **Step 4**: Integration tests validate signal contracts between HOPs
5. **Step 5**: MCP client subscribes to signals for progress tracking
### Type Safety Compliance (Phase-Level)
**Type Safety Requirements** (TypeScript 5.0 strict mode):
- [ ] All function parameters typed: `function myFunc(param: Type): ReturnType`
- [ ] All variables explicitly typed: `const myVar: Type = value`
- [ ] Typed arrays throughout: `Array<ElementType>` not `Array`
- [ ] Async/Promise types: `async function(): Promise<ReturnType>`
- [ ] Null safety: Strict null checks enabled (`strictNullChecks: true`)
- [ ] Interface contracts: All public APIs use interfaces
- [ ] Zod validation: Runtime validation for MCP tool inputs
**TypeScript Compilation Validation** (All HOPs):
```bash
# Validate entire phase in strict mode
npm run build
# Expected result: 0 errors, 0 warnings
```
**Type Safety Enforcement Timeline**:
- **HOP Planning**: Type signatures defined in HOP plans
- **Implementation**: Types added as code is written (strict mode enforced)
- **Pre-Commit**: TypeScript compilation check before merging
- **CI/CD**: Automated TypeScript compilation in pipeline
### Testing Compliance (Phase-Level)
**Test Coverage Targets**:
- **Minimum Coverage**: 90% across all phase code (up from 93.6% in Phase 2)
- **Foundation HOPs**: 95% coverage minimum (critical systems)
- **Feature HOPs**: 90% coverage minimum (complex logic)
- **Integration Tests**: 20+ tests validating HOP interactions
**Test Distribution**:
| HOP ID | Unit Tests | Integration Tests | Performance Tests | Total Tests |
|--------|-----------|-------------------|-------------------|-------------|
| 3.1 | 12 | 3 | 2 | 17 |
| 3.2a | 10 | 2 | 1 | 13 |
| 3.2b | 10 | 2 | 1 | 13 |
| 3.3 | 8 | 2 | 1 | 11 |
| 3.4 | 12 | 3 | 2 | 17 |
| 3.5 | 10 | 2 | 1 | 13 |
| 3.6a | 6 | 2 | 1 | 9 |
| 3.6b | 5 | 1 | 0 | 6 |
| 3.7 | 5 | 15 | 5 | 25 |
| **TOTAL** | **78** | **32** | **14** | **124+ tests** |
**Jest Testing Patterns**:
- All tests use Jest 29.7 framework
- Deterministic test corpus (20 fixture projects)
- Graph construction tests with known ground truth
- Performance tests with budgets (<5s scan, <1s graph build)
- False positive validation (unused detection accuracy)
### Performance Budget (Phase-Level)
**Phase Performance Targets**:
- **Project Scan**: <5s for 500-file project (initial), <500ms (incremental)
- **Graph Construction**: <1s for 300 signals + 500 connections
- **Unused Detection**: <500ms for 300 signals
- **Refactoring Suggestions**: <1s for 300 signals
- **Hierarchical Clustering**: <500ms for 300 signals
- **Memory Budget**: <100MB total (including graph storage)
**Per-HOP Performance Budgets**:
| HOP ID | Frame Budget | Memory Budget | Validation Method |
|--------|-------------|---------------|-------------------|
| 3.1 | <5s (scan) | <50MB | Jest performance tests |
| 3.2a | <1s (graph) | <30MB | Graph construction benchmarks |
| 3.2b | <1s (graph) | <30MB | Connection graph benchmarks |
| 3.3 | <500ms | <10MB | Detection algorithm benchmarks |
| 3.4 | <1s | <20MB | Suggestion generation benchmarks |
| 3.5 | <500ms | <15MB | Clustering benchmarks (from Phase 2) |
| **TOTAL** | **<8.5s** | **<100MB** | **Continuous monitoring (Phase 2 pipeline)** |
---
## 📅 Phase Timeline & Milestones
### Phase Milestones
**M0: Phase Planning Complete** (Target: 2025-11-04)
- [ ] All 7 HOP planning documents created
- [ ] Signal contracts defined (9 signals documented)
- [ ] Performance budgets allocated
- [ ] CTS compliance validated (100%)
- [ ] Test corpus prepared (20 fixture projects)
- **Gate**: Cannot start implementation without M0 complete
**M1: Foundation Complete** (Target: 2025-11-18)
- [ ] HOPs 3.1, 3.2a, 3.2b complete
- [ ] Foundation tests passing (43/43 tests green)
- [ ] Project scanning operational (<5s for 500 files)
- [ ] Signal graph construction validated (<1s for 300 signals)
- [ ] Performance targets met (<6s total foundation)
- **Gate**: Cannot start feature HOPs without M1 complete
**M2: Features Complete** (Target: 2025-12-06)
- [ ] HOPs 3.3, 3.4, 3.5 complete
- [ ] Feature tests passing (41/41 tests green)
- [ ] Unused detection achieves ≥95% precision
- [ ] Refactoring suggestions achieve ≥98% accuracy
- [ ] Hierarchical clustering operational (<500ms)
- **Gate**: Cannot start polish HOP without M2 complete
**M3: Phase Complete** (Target: 2025-12-13)
- [ ] HOPs 3.6a, 3.6b, 3.7 complete
- [ ] ALL tests passing (124+/124+ tests green, ≥90% coverage)
- [ ] Performance budgets met (<8.5s total)
- [ ] Documentation complete (3 ADRs + API docs + completion report)
- [ ] Production deployment successful
- **Gate**: Phase 3 officially complete, can proceed to Phase 4
### Timeline Visualization
```
┌──────────────────────────────────────────────────────────────────────────┐
│ Phase 3 Timeline - 6 Weeks Total (40h/week = 240h available) │
│ │
│ Week 1-2: Foundation (M0 → M1) - 32h total │
│ ├─ 3.1: Project Scanner (12h) │
│ ├─ 3.2a: Graph Builder Defs (10h) │
│ └─ 3.2b: Graph Builder Conns (10h) │
│ │
│ Week 3-4: Features (M1 → M2) - Parallel Development - 30h total │
│ ├─ CRITICAL PATH: 3.3 Unused Detector (8h) │
│ ├─ FEATURE TRACK: 3.4 Refactoring Engine (12h) [parallel with 3.3/3.5] │
│ └─ FEATURE TRACK: 3.5 Hierarchical Clustering (10h) [parallel with 3.3] │
│ │
│ Week 5: Polish & Monitoring (M2 → M3) - Parallel - 12h total │
│ ├─ POLISH TRACK: 3.6a Performance Alerts (6h) [parallel with 3.6b] │
│ └─ POLISH TRACK: 3.6b Performance Dashboard (6h) [parallel with 3.6a] │
│ │
│ Week 6: Final Polish (M2 → M3) - 8h total │
│ └─ 3.7: Final Polish & Documentation (8h) │
│ │
│ █ = Critical Path ▓ = Feature Track ░ = Polish Track │
│ │
│ Week: 1 2 3 4 5 6 │
│ ████████████ │
│ ▓▓▓▓▓▓▓▓▓▓▓▓▓ │
│ ░░░░░░░░ │
│ █████ │
└──────────────────────────────────────────────────────────────────────────┘
```
**Timeline Scenarios**:
- **Sequential (1 developer, 40h/week)**: 82h ÷ 40 = ~2 weeks (M0 → M3)
- **Parallel (2 developers, 80h/week)**: 60h ÷ 80 = ~1 week (critical + feature)
- **Recommended (1 developer, realistic)**: 6 weeks (accounts for planning, testing, docs)
**Buffer Time** (for risks/unknowns):
- Planning Buffer: +10% (8 hours) - refactoring engine complexity
- Implementation Buffer: +15% (12 hours) - cross-file tracking edge cases
- Testing Buffer: +10% (8 hours) - false positive tuning for unused detection
### Critical Path Analysis
**Critical Path HOPs**: 3.1 → 3.2a → 3.2b → 3.3 → 3.7
**Critical Path Duration**: 48 hours (gates phase completion)
**Non-Critical HOPs**: 3.4, 3.5, 3.6a, 3.6b (can parallelize or defer)
**Risk Factors**:
1. **HOP 3.1 Risk**: Incremental scanning complexity (filesystем watchers, cache invalidation)
- **Mitigation**: Start with full scan only, add incremental in 3.1b sub-hop if needed
- **Fallback**: Defer incremental to Phase 4, accept 5s full scan per operation
2. **HOP 3.3 Risk**: False positive rate >5% (users lose trust in unused detection)
- **Mitigation**: Conservative confidence scoring (flag ambiguous cases as "review needed")
- **Fallback**: Manual review UI (user confirms deletions before applying)
3. **HOP 3.4 Risk**: Refactoring accuracy <98% (breaks user code)
- **Mitigation**: Suggestions only (never auto-apply), extensive test corpus validation
- **Fallback**: Defer to Phase 4 if accuracy target not met
---
## 📚 Documentation Requirements
**Architecture Decision Records** (3 ADRs, 900 LOC total):
1. **ADR-003: Cross-File Signal Graph Construction** (300 LOC)
- Context: Single-file vs project-wide tracking
- Decision: Incremental AST parsing with graph caching
- Alternatives: Full re-scan, filesystem watchers, manual tracking
- Consequences: Performance, cache invalidation complexity
2. **ADR-004: Refactoring Suggestion Engine Design** (350 LOC)
- Context: Manual refactoring error rate 15-20%
- Decision: Levenshtein + semantic similarity + naming validation
- Alternatives: Rule-based only, ML-based, AST transformations
- Consequences: Accuracy vs performance tradeoff
3. **ADR-005: Hierarchical Clustering Strategy** (250 LOC)
- Context: Phase 2 flat clustering, users want drill-down
- Decision: Recursive modularity optimization with theme detection
- Alternatives: K-means hierarchical, agglomerative, manual grouping
- Consequences: Cluster quality, labeling accuracy
**API Documentation** (500 LOC):
- TypeScript JSDoc for all public classes/methods
- Signal contracts with payload schemas
- Integration examples (how to use project scanner, unused detector)
**Guides** (500 LOC total):
- **Migration Guide**: Phase 2 → Phase 3 upgrade instructions
- **Refactoring Guide**: How to review and apply suggestions safely
- **Performance Tuning**: Optimizing scan time for large projects
**Completion Report** (600 LOC):
- Phase 3 metrics (LOC, tests, performance)
- Lessons learned (what worked, what didn't)
- Phase 4 recommendations
---
## 🚀 Success Metrics
**Performance Metrics**:
- Project scan: <5s for 500-file project ✅
- Graph construction: <1s for 300 signals ✅
- Unused detection: <500ms for 300 signals ✅
- Memory usage: <100MB total ✅
**Quality Metrics**:
- Test coverage: ≥90% ✅
- Unused detection precision: ≥95% ✅
- Refactoring accuracy: ≥98% ✅
- False positive rate: <5% ✅
**Delivery Metrics**:
- All 7 HOPs complete ✅
- 124+ tests passing ✅
- 0 TypeScript errors ✅
- 3 ADRs + completion report ✅
---
## 🔄 Phase 4 Preview
**Next Phase Focus**: AI-Powered Code Generation & Validation
- Natural language → GDScript signal code
- AI-generated signal connections validated against Phase 3 graph
- Automated test generation for refactored signals
- Code completion based on project signal architecture
**Phase 3 Enables Phase 4**:
- Global signal graph provides validation context
- Refactoring engine provides code transformation patterns
- Unused detection provides code quality baseline
---
**Phase 3 Status**: 🟡 PLANNING
**Next Action**: Create HOP planning documents (7 HOPs)
**Approval Required**: Phase 3 plan review (CTS MCP Development Team)
---
**Document Version**: 1.0
**Last Updated**: 2025-10-30
**Next Review**: 2025-11-04 (M0 milestone)