refactor: add Builder return types to all Eloquent query scopes

Add `Builder $query` parameter type and `: Builder` return type to
18 query scopes across 8 model files. Import `Illuminate\Database\Eloquent\Builder`
in each affected model.

Affected models: Task, AgentSession, AgentApiKey, AgentPhase, AgentPlan,
Prompt, AgentWorkspaceState, WorkspaceState.

Closes #16

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Models/AgentApiKey.php

@@ -5,6 +5,7 @@ declare(strict_types=1);
 namespace Core\Mod\Agentic\Models;
 
 use Core\Tenant\Models\Workspace;
+use Illuminate\Database\Eloquent\Builder;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations\BelongsTo;
 use Illuminate\Support\Str;
@@ -120,7 +121,7 @@ class AgentApiKey extends Model
     }
 
     // Scopes
-    public function scopeActive($query)
+    public function scopeActive(Builder $query): Builder
     {
         return $query->whereNull('revoked_at')
             ->where(function ($q) {
@@ -136,12 +137,12 @@ class AgentApiKey extends Model
         return $query->where('workspace_id', $workspaceId);
     }
 
-    public function scopeRevoked($query)
+    public function scopeRevoked(Builder $query): Builder
     {
         return $query->whereNotNull('revoked_at');
     }
 
-    public function scopeExpired($query)
+    public function scopeExpired(Builder $query): Builder
     {
         return $query->whereNotNull('expires_at')
             ->where('expires_at', '<=', now());

Models/AgentPhase.php

@@ -5,6 +5,7 @@ declare(strict_types=1);
 namespace Core\Mod\Agentic\Models;
 
 use Core\Mod\Agentic\Database\Factories\AgentPhaseFactory;
+use Illuminate\Database\Eloquent\Builder;
 use Illuminate\Database\Eloquent\Factories\HasFactory;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations\BelongsTo;
@@ -82,22 +83,22 @@ class AgentPhase extends Model
     }
 
     // Scopes
-    public function scopePending($query)
+    public function scopePending(Builder $query): Builder
     {
         return $query->where('status', self::STATUS_PENDING);
     }
 
-    public function scopeInProgress($query)
+    public function scopeInProgress(Builder $query): Builder
     {
         return $query->where('status', self::STATUS_IN_PROGRESS);
     }
 
-    public function scopeCompleted($query)
+    public function scopeCompleted(Builder $query): Builder
     {
         return $query->where('status', self::STATUS_COMPLETED);
     }
 
-    public function scopeBlocked($query)
+    public function scopeBlocked(Builder $query): Builder
     {
         return $query->where('status', self::STATUS_BLOCKED);
     }

Models/AgentPlan.php

@@ -7,6 +7,7 @@ namespace Core\Mod\Agentic\Models;
 use Core\Mod\Agentic\Database\Factories\AgentPlanFactory;
 use Core\Tenant\Concerns\BelongsToWorkspace;
 use Core\Tenant\Models\Workspace;
+use Illuminate\Database\Eloquent\Builder;
 use Illuminate\Database\Eloquent\Factories\HasFactory;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations\BelongsTo;
@@ -99,17 +100,17 @@ class AgentPlan extends Model
     }
 
     // Scopes
-    public function scopeActive($query)
+    public function scopeActive(Builder $query): Builder
     {
         return $query->where('status', self::STATUS_ACTIVE);
     }
 
-    public function scopeDraft($query)
+    public function scopeDraft(Builder $query): Builder
     {
         return $query->where('status', self::STATUS_DRAFT);
     }
 
-    public function scopeNotArchived($query)
+    public function scopeNotArchived(Builder $query): Builder
     {
         return $query->where('status', '!=', self::STATUS_ARCHIVED);
     }
@@ -120,7 +121,7 @@ class AgentPlan extends Model
      * This is a safe replacement for orderByRaw("FIELD(status, ...)") which
      * could be vulnerable to SQL injection if extended with user input.
      */
-    public function scopeOrderByStatus($query, string $direction = 'asc')
+    public function scopeOrderByStatus(Builder $query, string $direction = 'asc'): Builder
     {
         return $query->orderByRaw('CASE status
             WHEN ? THEN 1

Models/AgentSession.php

@@ -7,6 +7,7 @@ namespace Core\Mod\Agentic\Models;
 use Core\Mod\Agentic\Database\Factories\AgentSessionFactory;
 use Core\Tenant\Concerns\BelongsToWorkspace;
 use Core\Tenant\Models\Workspace;
+use Illuminate\Database\Eloquent\Builder;
 use Illuminate\Database\Eloquent\Factories\HasFactory;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations\BelongsTo;
@@ -107,12 +108,12 @@ class AgentSession extends Model
     }
 
     // Scopes
-    public function scopeActive($query)
+    public function scopeActive(Builder $query): Builder
     {
         return $query->where('status', self::STATUS_ACTIVE);
     }
 
-    public function scopeForPlan($query, AgentPlan|int $plan)
+    public function scopeForPlan(Builder $query, AgentPlan|int $plan): Builder
     {
         $planId = $plan instanceof AgentPlan ? $plan->id : $plan;
 

Models/AgentWorkspaceState.php

@@ -4,6 +4,7 @@ declare(strict_types=1);
 
 namespace Core\Mod\Agentic\Models;
 
+use Illuminate\Database\Eloquent\Builder;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations\BelongsTo;
 
@@ -54,14 +55,14 @@ class AgentWorkspaceState extends Model
     }
 
     // Scopes
-    public function scopeForPlan($query, AgentPlan|int $plan)
+    public function scopeForPlan(Builder $query, AgentPlan|int $plan): Builder
     {
         $planId = $plan instanceof AgentPlan ? $plan->id : $plan;
 
         return $query->where('agent_plan_id', $planId);
     }
 
-    public function scopeOfType($query, string $type)
+    public function scopeOfType(Builder $query, string $type): Builder
     {
         return $query->where('type', $type);
     }

Models/Prompt.php

@@ -4,6 +4,7 @@ declare(strict_types=1);
 
 namespace Core\Mod\Agentic\Models;
 
+use Illuminate\Database\Eloquent\Builder;
 use Illuminate\Database\Eloquent\Factories\HasFactory;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations\HasMany;
@@ -82,7 +83,7 @@ class Prompt extends Model
     /**
      * Scope to only active prompts.
      */
-    public function scopeActive($query)
+    public function scopeActive(Builder $query): Builder
     {
         return $query->where('is_active', true);
     }
@@ -90,7 +91,7 @@ class Prompt extends Model
     /**
      * Scope by category.
      */
-    public function scopeCategory($query, string $category)
+    public function scopeCategory(Builder $query, string $category): Builder
     {
         return $query->where('category', $category);
     }
@@ -98,7 +99,7 @@ class Prompt extends Model
     /**
      * Scope by model provider.
      */
-    public function scopeForModel($query, string $model)
+    public function scopeForModel(Builder $query, string $model): Builder
     {
         return $query->where('model', $model);
     }

Models/Task.php

@@ -5,6 +5,7 @@ declare(strict_types=1);
 namespace Core\Mod\Agentic\Models;
 
 use Core\Tenant\Concerns\BelongsToWorkspace;
+use Illuminate\Database\Eloquent\Builder;
 use Illuminate\Database\Eloquent\Model;
 
 class Task extends Model
@@ -26,22 +27,22 @@ class Task extends Model
         'line_ref' => 'integer',
     ];
 
-    public function scopePending($query)
+    public function scopePending(Builder $query): Builder
     {
         return $query->where('status', 'pending');
     }
 
-    public function scopeInProgress($query)
+    public function scopeInProgress(Builder $query): Builder
     {
         return $query->where('status', 'in_progress');
     }
 
-    public function scopeDone($query)
+    public function scopeDone(Builder $query): Builder
     {
         return $query->where('status', 'done');
     }
 
-    public function scopeActive($query)
+    public function scopeActive(Builder $query): Builder
     {
         return $query->whereIn('status', ['pending', 'in_progress']);
     }

Models/WorkspaceState.php

@@ -4,6 +4,7 @@ declare(strict_types=1);
 
 namespace Core\Mod\Agentic\Models;
 
+use Illuminate\Database\Eloquent\Builder;
 use Illuminate\Database\Eloquent\Factories\HasFactory;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations\BelongsTo;
@@ -132,7 +133,7 @@ class WorkspaceState extends Model
     /**
      * Scope: for plan.
      */
-    public function scopeForPlan($query, int $planId)
+    public function scopeForPlan(Builder $query, int $planId): Builder
     {
         return $query->where('agent_plan_id', $planId);
     }
@@ -140,7 +141,7 @@ class WorkspaceState extends Model
     /**
      * Scope: by type.
      */
-    public function scopeByType($query, string $type)
+    public function scopeByType(Builder $query, string $type): Builder
     {
         return $query->where('type', $type);
     }