feat: enhance agent settlement features and improve data access controls

- Added new section in AGENTS.md detailing learned workspace facts for better understanding of settlement processes.
- Updated AgentNodeDestroyController to remove unnecessary checks for admin users.
- Enhanced AgentSettlement controllers to assert permissions for finance adjustments and bill operations.
- Improved query scopes in AgentSettlement services to ensure proper data access based on admin roles.
- Refactored methods in SettlementPartyEnrichment for better bill row enrichment and data handling.
- Introduced new methods in AdminAgentSettlementScope for managing agent node visibility and finance adjustments.

tests/Feature/AgentSettlementPeriodOpenTest.php

@@ -40,6 +40,40 @@ test('cannot open duplicate settlement period for same range', function (): void
         );
 });
 
+test('cannot open settlement period overlapping a closed period', function (): void {
+    $siteId = (int) DB::table('admin_sites')->where('is_default', true)->value('id');
+    $super = \App\Models\AdminUser::query()->create([
+        'username' => 'period_overlap_super',
+        'name' => 'Super',
+        'email' => null,
+        'password' => \Illuminate\Support\Facades\Hash::make('secret-strong'),
+        'status' => 0,
+    ]);
+    grantSuperAdminRole($super);
+    $token = $super->createToken('test', ['*'], now()->addDay())->plainTextToken;
+
+    DB::table('settlement_periods')->insert([
+        'admin_site_id' => $siteId,
+        'period_start' => '2026-05-01 00:00:00',
+        'period_end' => '2026-05-31 23:59:59',
+        'status' => 'closed',
+        'created_at' => now(),
+        'updated_at' => now(),
+    ]);
+
+    $this->withHeader('Authorization', 'Bearer '.$token)
+        ->postJson('/api/v1/admin/settlement-periods', [
+            'admin_site_id' => $siteId,
+            'period_start' => '2026-05-15 00:00:00',
+            'period_end' => '2026-06-15 23:59:59',
+        ])
+        ->assertStatus(422)
+        ->assertJsonPath(
+            'data.errors.period_start.0',
+            trans('validation.business.period_overlaps_existing'),
+        );
+});
+
 test('cannot open second settlement period while another is open on same site', function (): void {
     $siteId = (int) DB::table('admin_sites')->where('is_default', true)->value('id');
     $super = \App\Models\AdminUser::query()->create([