AI Hallucinations Are Not Harmless - When AI Gaslights You: A Case Study

[nader443 (Nader Abdulaal)]

@vibe-qa

ask the Agent to create the rules in a way that they will listen to them?

I asked the Agent to create the rules in a way that they will listen to them? Yes.
I audted the rules made sure no conflicts between them too.

This is an Example of one of the rules:

---

** IMPORT STANDARDIZATION RULE - NADER APP **

---

description: “Enforces alias-based imports (@src/*) instead of relative paths for consistent monorepo architecture”
impact: ‘High’
methodology: ‘Systematic Import Standardization’
lastValidated: 2025-08-08
successMetrics: “100% alias-based imports, 0 relative path violations, consistent monorepo architecture”

MANDATORY IMPORT STANDARDIZATION

ENFORCE: Workspace-Specific Alias Patterns

Backend Workspace (apps/backend/)

// ✅ CORRECT: Use @src aliases for backend imports
import { DrizzleService } from '@src/drizzle/services/drizzle.service';
import { users } from '@src/drizzle/schema/tables/users';
import { FirebaseAuthGuard } from '@src/firebase-auth/firebase-auth.guard';
import { CustomLoggerService } from '@src/common/logging/logger.service';
import { UserRole } from '@src/common/enums/user-role.enum';
import { AnalyticsService } from '@src/analytics/services/analytics.service';
import { AuthService } from '@src/auth/services/auth.service';
import { PaymentService } from '@src/payments/services/payment.service';

Frontend Workspace (apps/frontend/)

// ✅ CORRECT: Use @/ aliases for frontend imports
import { UserCard } from '@/components/cards/UserCard';
import { ApiResponse } from '@nader-app/shared-types';
import { StatCard } from '@nader-app/ui-template';
import { useUserStore } from '@/stores/useUserStore';

Portal Workspace (apps/portal/web/)

// ✅ CORRECT: Use @/ aliases for portal imports
import { PortalLayout } from '@/components/layout/PortalLayout';
import { ApiResponse } from '@nader-app/shared-types';
import { usePortalStore } from '@/stores/usePortalStore';

Shared Packages

// ✅ CORRECT: Use @nader-app/* aliases for shared packages
import type { ApiResponse, UserData } from '@nader-app/shared-types';
import { StatCard, MainCard } from '@nader-app/ui-template';
import { DataTable } from '@nader-app/shared-components';

FORBIDDEN: Relative Path Imports

// ❌ WRONG: Relative paths are forbidden in all workspaces
import { DrizzleService } from '../../drizzle/services/drizzle.service';
import { users } from '../../../drizzle/schema/tables/users';
import { FirebaseAuthGuard } from '../../firebase-auth/firebase-auth.guard';
import { CustomLoggerService } from '../../common/logging/logger.service';
import { UserRole } from '../../../common/enums/user-role.enum';

// ❌ WRONG: Frontend relative paths
import { UserCard } from '../../components/cards/UserCard';
import { useUserStore } from '../../../stores/useUserStore';

---

ARCHITECTURAL JUSTIFICATION

Monorepo Compatibility

• Workspace Isolation: Alias-based imports respect monorepo workspace boundaries
• File Move Safety: Imports don’t break when files are moved within the workspace
• Team Consistency: Single import pattern across entire codebase
• IDE Support: Better autocomplete and refactoring support

Enterprise Scalability

• Headless Architecture Support: Consistent imports across decoupled services
• TypeScript Excellence: Better type resolution and error detection
• Developer Experience: Clearer, more maintainable import statements
• Build Performance: Optimized module resolution in monorepo context

---

COMPREHENSIVE PATH ALIAS MAPPINGS

Core Module Aliases

// Authentication & Security
import { ... } from '@src/firebase-auth/...';
import { ... } from '@src/auth/...';

// Business Modules
import { ... } from '@src/analytics/...';
import { ... } from '@src/payments/...';
import { ... } from '@src/rfqs/...';
import { ... } from '@src/smm/...';
import { ... } from '@src/social/...';
import { ... } from '@src/users/...';
import { ... } from '@src/fsm/...';
import { ... } from '@src/csm/...';
import { ... } from '@src/chat/...';

// Infrastructure
import { ... } from '@src/drizzle/...';
import { ... } from '@src/config/...';
import { ... } from '@src/repositories/...';

// Shared Components
import { ... } from '@src/common/...';
import { ... } from '@src/super-admin/...';
import { ... } from '@src/company-management/...';
import { ... } from '@src/jobs/...';

Drizzle Schema Specific Aliases

// Schema imports
import { ... } from '@src/drizzle/schema/tables/...';
import { ... } from '@src/drizzle/schema/customTypes';
import { ... } from '@src/drizzle/services/drizzle.service';

// Table-specific imports
import { users } from '@src/drizzle/schema/tables/users';
import { posts } from '@src/drizzle/schema/tables/social/posts.table';
import { campaigns } from '@src/drizzle/schema/tables/smm/campaigns';

---

IMPLEMENTATION ENFORCEMENT

ESLint Rules

// Enforced in .eslintrc.js
'no-restricted-imports': [
  'error',
  {
    patterns: [
      {
        group: ['../../*', '../../../*', '../../../../*'],
        message: 'Use @src/* alias imports instead of relative paths'
      }
    ]
  }
]

TypeScript Configuration

// Enforced in tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@src/*": ["src/*"],
      "@firebase-auth/*": ["src/firebase-auth/*"],
      "@analytics/*": ["src/analytics/*"],
      "@auth/*": ["src/auth/*"],
      "@payments/*": ["src/payments/*"],
      "@rfqs/*": ["src/rfqs/*"],
      "@smm/*": ["src/smm/*"],
      "@social/*": ["src/social/*"],
      "@users/*": ["src/users/*"],
      "@fsm/*": ["src/fsm/*"],
      "@csm/*": ["src/csm/*"],
      "@chat/*": ["src/chat/*"],
      "@company-management/*": ["src/company-management/*"],
      "@super-admin/*": ["src/super-admin/*"],
      "@repositories/*": ["src/repositories/*"],
      "@config/*": ["src/config/*"],
      "@jobs/*": ["src/jobs/*"],
      "@drizzle/*": ["src/drizzle/*"],
      "@common/*": ["src/common/*"]
    }
  }
}

---

MIGRATION PROTOCOL

Automated Migration Script

# Run migration script
node scripts/migrate-imports.js

# Verify TypeScript compilation
cd apps/backend && npx tsc --noEmit

# Test application
pnpm run dev --filter=@nader-app/backend

Manual Verification Commands

# Find remaining relative imports
find apps/backend/src -name "*.ts" -exec grep -l "from.*\.\./" {} \;

# Count alias-based imports
find apps/backend/src -name "*.ts" -exec grep -c "from.*@src/" {} \;

# ESLint validation
cd apps/backend && npx eslint src/ --ext .ts

---

SUCCESS METRICS

Compliance Targets

• 100% Alias Usage: Zero relative path imports in production code
• 0 ESLint Violations: No restricted import warnings
• TypeScript Clean: Zero compilation errors related to import resolution
• Build Success: Successful compilation with alias-based imports

Quality Gates

# Pre-commit validation
npm run lint:backend
npm run type-check:backend

# CI/CD validation
pnpm run validate:imports
pnpm run test:backend

---

MAINTENANCE PROTOCOLS

New Module Integration

When adding new modules:

1. Add Path Alias: Update tsconfig.json with new @src/module/* mapping
2. Update ESLint: Add module to restricted import patterns if needed
3. Update Migration Script: Add module to IMPORT_MAPPINGS in migration script
4. Document: Update this rule with new module alias

Code Review Checklist

• All imports use @src/* aliases
• No relative path imports (../../*)
• Import ordering follows ESLint rules
• TypeScript compilation successful
• ESLint validation passes

---

RELATED DOCUMENTATION

• Architecture: README.md - Monorepo architecture overview
• Frontend Rules: frontend_rules.mdc - Frontend debugging patterns
• Cursor Rules: cursor_rules.mdc - Core development framework
• Migration Script: scripts/migrate-imports.js - Automated import conversion

---

ENFORCEMENT: This rule is mandatory for maintaining consistent monorepo architecture. Any deviation requires explicit approval with detailed justification.

Last Updated: 2025-08-08 | Validation Status: Active | Compliance Rate: Target 100%
description:
globs:
alwaysApply: false