efarmz-slackbot-data 1.0.0

package/.tasks/F4-infrastructure-layer.md

@@ -0,0 +1,229 @@
+---
+title: "F4 — Infrastructure Layer"
+type: feature
+status: todo
+prd: .tasks/PRD.md
+depends_on: F3
+github_issue: 29
+---
+
+# F4 — Infrastructure Layer
+
+## Objectif
+
+Implémenter tous les adapters concrets qui réalisent les ports définis dans `src/domain/ports/`. Cette couche peut importer les SDKs tiers (`pg`, `@anthropic-ai/sdk`, `@slack/bolt`, `pino`) mais ne doit jamais importer `src/application/`.
+
+## Fichiers à créer
+
+### SQL (`src/infrastructure/sql/`)
+
+**`RegexSqlValidator.ts`** — implémente `SqlValidator`
+
+Règles de validation (dans l'ordre) :
+1. Trim + normalisation whitespace
+2. Doit commencer par `SELECT` ou `WITH` (insensitive) → sinon `InvalidSqlError`
+3. Refus des keywords mutables : `\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE|GRANT|REVOKE|COPY|CALL|VACUUM|MERGE)\b` (insensitive) → `InvalidSqlError`
+4. Refus de `;` sauf en toute fin de requête (optionnel) → `InvalidSqlError`
+5. Si absent : append `LIMIT {SQL_MAX_ROWS}` avant le `;` final ou en fin de chaîne
+
+Retourne le SQL nettoyé (string), ou throw `InvalidSqlError`.
+
+Tests exhaustifs requis (voir ci-dessous).
+
+### Persistence (`src/infrastructure/persistence/`)
+
+**`PostgresPoolFactory.ts`**
+- Crée un `Pool` pg depuis `DATABASE_URL`
+- `idleTimeoutMillis: 30000`, `connectionTimeoutMillis: 5000`
+- Export : factory function `createPool(databaseUrl: string): Pool`
+
+**`PostgresSqlExecutor.ts`** — implémente `SqlExecutor`
+```typescript
+class PostgresSqlExecutor implements SqlExecutor {
+  constructor(private readonly pool: Pool, private readonly timeoutMs: number) {}
+
+  async execute(query: SqlQuery): Promise<QueryResult> {
+    const client = await this.pool.connect();
+    try {
+      await client.query(`SET statement_timeout = ${this.timeoutMs}`);
+      const result = await client.query(query.raw);
+      return QueryResult.create(
+        result.fields.map(f => f.name),
+        result.rows,
+      );
+    } finally {
+      client.release();
+    }
+  }
+}
+```
+- Wrap les erreurs PG en `SqlExecutionError`
+
+**`InMemoryConversationRepository.ts`** — implémente `ConversationRepository`
+- Stockage : `Map<ThreadId, { conversation: Conversation; lastAccess: number }>`
+- LRU : si `Map.size >= CONVERSATION_MAX_THREADS`, supprimer l'entrée avec le `lastAccess` le plus ancien
+- TTL : au `get`, vérifier si `Date.now() - lastAccess > CONVERSATION_TTL_MS` → retourner `null` et purger
+- `save` met à jour `lastAccess`
+
+### Schemas (`src/infrastructure/schemas/`)
+
+**`FileSystemSchemaCatalog.ts`** — implémente `SchemaCatalog`
+- Au constructeur : lire tous les `*.md` dans `SCHEMAS_DIR` (sync, fail-fast si erreur → `SchemaLoadError`)
+- Concatène le contenu de tous les fichiers avec séparateurs
+- `getDocumentation()` retourne la chaîne concaténée (mémoïsée)
+
+### LLM (`src/infrastructure/llm/`)
+
+**`prompts/SystemPromptBuilder.ts`**
+```typescript
+class SystemPromptBuilder {
+  static build(schemaDoc: string): AnthropicSystemContent {
+    return [
+      {
+        type: 'text',
+        text: SYSTEM_PROMPT_HEADER,
+      },
+      {
+        type: 'text',
+        text: schemaDoc,
+        cache_control: { type: 'ephemeral' },
+      },
+    ];
+  }
+}
+```
+Le `SYSTEM_PROMPT_HEADER` décrit le rôle du bot, les règles (SELECT uniquement, toujours utiliser `run_sql`), et le format de réponse attendu.
+
+**`prompts/ToolDefinitions.ts`**
+- Export de la définition JSON du tool `run_sql` (réexporte depuis `application/agent/tools/RunSqlTool.ts`)
+
+**`mappers/AnthropicMessageMapper.ts`**
+- Convertit `LLMMessage[]` (domain) → `Anthropic.MessageParam[]` (SDK)
+- Convertit `Anthropic.Message` (SDK) → `LLMResponse` (domain)
+
+**`AnthropicLLMProvider.ts`** — implémente `LLMProvider`
+```typescript
+class AnthropicLLMProvider implements LLMProvider {
+  constructor(
+    private readonly client: Anthropic,
+    private readonly model: string,
+    private readonly schemaCatalog: SchemaCatalog,
+  ) {}
+
+  async generate(request: LLMRequest): Promise<LLMResponse> {
+    const response = await this.client.messages.create({
+      model: this.model,
+      max_tokens: 4096,
+      system: SystemPromptBuilder.build(this.schemaCatalog.getDocumentation()),
+      messages: AnthropicMessageMapper.toSDK(request.messages),
+      tools: request.tools,
+    });
+    return AnthropicMessageMapper.fromSDK(response);
+  }
+}
+```
+- Wrap les erreurs Anthropic en `LLMError`
+
+### Slack (`src/infrastructure/slack/`)
+
+**`SlackApp.ts`** — Setup Bolt
+- `App` avec `token` + `signingSecret` + `receiver: ExpressReceiver`
+- Export : `{ app, receiver }`
+
+**`BoltSlackMessenger.ts`** — implémente `SlackMessenger`
+```typescript
+class BoltSlackMessenger implements SlackMessenger {
+  async post(threadId: ThreadId, text: string): Promise<void> {
+    await this.client.chat.postMessage({
+      channel: threadId.channelId,
+      thread_ts: threadId.threadTs,
+      text,
+    });
+  }
+
+  async postCsv(threadId, text, csvBuffer, filename): Promise<void> {
+    await this.client.chat.postMessage({ ... text ... });
+    await this.client.files.uploadV2({
+      channel_id: threadId.channelId,
+      thread_ts: threadId.threadTs,
+      filename,
+      file: csvBuffer,
+    });
+  }
+}
+```
+
+> Note : `ThreadId` doit encoder `channelId` + `threadTs` pour permettre le posting. Adapter la définition du VO si nécessaire.
+
+**`SlackAdminLogger.ts`** — implémente `AdminLogger`
+- Si `SLACK_ADMIN_CHANNEL_ID` absent → no-op (log warning au boot)
+- Post un message formaté dans le channel admin avec : user, question, sqls[], rowCount, durationMs, tokens
+
+**`handlers/AppMentionHandler.ts`**
+```typescript
+// app.event('app_mention', async ({ event, ack, say }) => {
+//   ack(); // 200 OK immédiat
+//   const dedupKey = event.event_id;
+//   if (eventCache.has(dedupKey)) return;
+//   eventCache.set(dedupKey, true, TTL_5MIN);
+//   setImmediate(async () => { await answerQuestion.execute(...) });
+// });
+```
+- Ack immédiat
+- Déduplication par `event_id` (cache Map avec TTL 5 min)
+- Traitement en `setImmediate` / promise détachée
+- Catch-all : log + message Slack générique d'erreur
+
+**`handlers/DirectMessageHandler.ts`**
+- Même logique que `AppMentionHandler` pour `message.im`
+- Filtrer les bots (`event.bot_id` présent → ignorer)
+
+### Logging (`src/infrastructure/logging/`)
+
+**`PinoLogger.ts`** — implémente `Logger`
+```typescript
+class PinoLogger implements Logger {
+  private readonly pino: pino.Logger;
+  constructor(level: string) {
+    this.pino = pino({ level });
+  }
+  debug(msg, meta?) { this.pino.debug(meta ?? {}, msg); }
+  info(msg, meta?) { this.pino.info(meta ?? {}, msg); }
+  warn(msg, meta?) { this.pino.warn(meta ?? {}, msg); }
+  error(msg, meta?) { this.pino.error(meta ?? {}, msg); }
+}
+```
+
+## Tests unitaires (`src/infrastructure/__tests__/`)
+
+**`RegexSqlValidator.test.ts`** — tests exhaustifs
+- `SELECT * FROM orders` → valide
+- `WITH cte AS (...) SELECT ...` → valide
+- `SELECT ...; DROP TABLE orders` → `InvalidSqlError`
+- `INSERT INTO orders ...` → `InvalidSqlError`
+- `UPDATE orders SET ...` → `InvalidSqlError`
+- `DELETE FROM orders ...` → `InvalidSqlError`
+- `DROP TABLE orders` → `InvalidSqlError`
+- `CREATE TABLE ...` → `InvalidSqlError`
+- `ALTER TABLE ...` → `InvalidSqlError`
+- `TRUNCATE orders` → `InvalidSqlError`
+- `GRANT SELECT ...` → `InvalidSqlError`
+- `select * from orders where name like 'drop%'` → valide (keyword dans string)
+- SQL sans LIMIT → LIMIT ajouté
+- SQL avec LIMIT existant → LIMIT non-dupliqué
+- SQL avec `;` au milieu → `InvalidSqlError`
+
+**`InMemoryConversationRepository.test.ts`**
+- `get` après TTL → retourne `null`
+- `save` → LRU éviction si `MAX_THREADS` atteint
+- `purge` → supprime l'entrée
+
+## Acceptance Criteria
+
+- [ ] `yarn typecheck` passe
+- [ ] `yarn test` : tests `RegexSqlValidator` et `InMemoryConversationRepository` passent
+- [ ] `RegexSqlValidator` couvre tous les keywords interdits
+- [ ] `PostgresSqlExecutor` set `statement_timeout` avant chaque requête
+- [ ] `AnthropicLLMProvider` utilise `cache_control: { type: 'ephemeral' }` sur le bloc system
+- [ ] Handlers Slack ack < 3s (traitement en `setImmediate`)
+- [ ] Déduplication par `event_id` dans les deux handlers

package/.tasks/F5-config-main.md

@@ -0,0 +1,160 @@
+---
+title: "F5 — Config & Composition Root"
+type: feature
+status: todo
+prd: .tasks/PRD.md
+depends_on: F4
+---
+
+# F5 — Config & Composition Root
+
+## Objectif
+
+Assembler toutes les couches via la DI manuelle (`Container`), valider les variables d'environnement au boot, et créer l'entry point `main.ts`. C'est le seul endroit où les implémentations concrètes sont instanciées et câblées ensemble.
+
+## Fichiers à créer
+
+### `src/config/env.ts`
+
+Validation via zod au boot — fail-fast si variable manquante ou invalide.
+
+```typescript
+import { z } from 'zod';
+
+const envSchema = z.object({
+  PORT: z.coerce.number().default(3000),
+  NODE_ENV: z.enum([`development`, `production`, `test`]).default(`development`),
+  LOG_LEVEL: z.enum([`debug`, `info`, `warn`, `error`]).default(`info`),
+
+  SLACK_BOT_TOKEN: z.string().min(1),
+  SLACK_SIGNING_SECRET: z.string().min(1),
+  SLACK_ADMIN_CHANNEL_ID: z.string().optional(),
+
+  LLM_PROVIDER: z.enum([`anthropic`]).default(`anthropic`),
+  LLM_MODEL: z.string().default(`claude-haiku-4-5-20251001`),
+  ANTHROPIC_API_KEY: z.string().min(1),
+  AGENT_MAX_TURNS: z.coerce.number().default(5),
+
+  DATABASE_URL: z.string().url(),
+  SQL_TIMEOUT_MS: z.coerce.number().default(30000),
+  SQL_MAX_ROWS: z.coerce.number().default(100),
+  SQL_CSV_THRESHOLD: z.coerce.number().default(15),
+
+  CONVERSATION_MAX_MESSAGES: z.coerce.number().default(8),
+  CONVERSATION_TTL_MS: z.coerce.number().default(3600000),
+  CONVERSATION_MAX_THREADS: z.coerce.number().default(200),
+
+  SCHEMAS_DIR: z.string().default(`./docs/schemas`),
+});
+
+const parsed = envSchema.safeParse(process.env);
+if (!parsed.success) {
+  console.error(`Invalid environment variables:`, parsed.error.format());
+  process.exit(1);
+}
+
+export const env = parsed.data;
+```
+
+### `src/config/constants.ts`
+
+Constantes dérivées de `env` ou fixes :
+
+```typescript
+export const SYSTEM_PROMPT_HEADER = `...`; // prompt system du bot
+```
+
+### `src/config/Container.ts`
+
+Composition root — instancie et câble toutes les dépendances.
+
+```typescript
+import { env } from './env.js';
+import { PinoLogger } from '@/infrastructure/logging/PinoLogger.js';
+import { FileSystemSchemaCatalog } from '@/infrastructure/schemas/FileSystemSchemaCatalog.js';
+import { RegexSqlValidator } from '@/infrastructure/sql/RegexSqlValidator.js';
+import { createPool } from '@/infrastructure/persistence/PostgresPoolFactory.js';
+import { PostgresSqlExecutor } from '@/infrastructure/persistence/PostgresSqlExecutor.js';
+import { InMemoryConversationRepository } from '@/infrastructure/persistence/InMemoryConversationRepository.js';
+import { AnthropicLLMProvider } from '@/infrastructure/llm/AnthropicLLMProvider.js';
+import { BoltSlackMessenger } from '@/infrastructure/slack/BoltSlackMessenger.js';
+import { SlackAdminLogger } from '@/infrastructure/slack/SlackAdminLogger.js';
+import { AgentLoop } from '@/application/agent/AgentLoop.js';
+import { ResponseRenderer } from '@/application/formatting/ResponseRenderer.js';
+import { AnswerQuestion } from '@/application/usecases/AnswerQuestion.js';
+import { ParseQuestion } from '@/application/usecases/ParseQuestion.js';
+import Anthropic from '@anthropic-ai/sdk';
+
+export function createContainer() {
+  const logger = new PinoLogger(env.LOG_LEVEL);
+
+  const schemaCatalog = new FileSystemSchemaCatalog(env.SCHEMAS_DIR, logger);
+
+  const sqlValidator = new RegexSqlValidator(env.SQL_MAX_ROWS);
+  const pool = createPool(env.DATABASE_URL);
+  const sqlExecutor = new PostgresSqlExecutor(pool, env.SQL_TIMEOUT_MS);
+  const conversationRepository = new InMemoryConversationRepository(
+    env.CONVERSATION_TTL_MS,
+    env.CONVERSATION_MAX_THREADS,
+    env.CONVERSATION_MAX_MESSAGES,
+  );
+
+  const anthropicClient = new Anthropic({ apiKey: env.ANTHROPIC_API_KEY });
+  const llmProvider = new AnthropicLLMProvider(anthropicClient, env.LLM_MODEL, schemaCatalog);
+
+  // Slack (app + client instanciés avant pour les messengers)
+  const { app } = createSlackApp(env); // setup Bolt
+  const slackMessenger = new BoltSlackMessenger(app.client);
+  const adminLogger = new SlackAdminLogger(app.client, env.SLACK_ADMIN_CHANNEL_ID, logger);
+
+  const agentLoop = new AgentLoop(llmProvider, sqlValidator, sqlExecutor, schemaCatalog, env.AGENT_MAX_TURNS);
+  const responseRenderer = new ResponseRenderer(env.SQL_CSV_THRESHOLD);
+
+  const answerQuestion = new AnswerQuestion(
+    conversationRepository,
+    agentLoop,
+    responseRenderer,
+    slackMessenger,
+    adminLogger,
+    logger,
+  );
+  const parseQuestion = new ParseQuestion();
+
+  return { app, answerQuestion, parseQuestion, logger };
+}
+```
+
+### `src/main.ts`
+
+Entry point minimal — boot, setup handlers, start server.
+
+```typescript
+import { createContainer } from '@/config/Container.js';
+import { AppMentionHandler } from '@/infrastructure/slack/handlers/AppMentionHandler.js';
+import { DirectMessageHandler } from '@/infrastructure/slack/handlers/DirectMessageHandler.js';
+import { env } from '@/config/env.js';
+
+async function main() {
+  const { app, answerQuestion, parseQuestion, logger } = createContainer();
+
+  AppMentionHandler.register(app, answerQuestion, parseQuestion, logger);
+  DirectMessageHandler.register(app, answerQuestion, parseQuestion, logger);
+
+  await app.start(env.PORT);
+  logger.info(`Bot started on port ${env.PORT}`);
+}
+
+main().catch((err) => {
+  console.error(`Fatal error at startup:`, err);
+  process.exit(1);
+});
+```
+
+## Acceptance Criteria
+
+- [ ] `yarn typecheck` passe
+- [ ] `yarn build` produit `dist/main.js` sans erreur
+- [ ] `yarn start` démarre sur le port configuré (avec env valide)
+- [ ] Boot échoue immédiatement si une variable requise est manquante (exit code 1)
+- [ ] `FileSystemSchemaCatalog` lève `SchemaLoadError` au boot si `SCHEMAS_DIR` invalide
+- [ ] Aucune instanciation de classe concrète en dehors de `Container.ts` et `main.ts`

package/.tasks/F6-schemas-deployment.md

@@ -0,0 +1,129 @@
+---
+title: "F6 — Documentation des schémas & Déploiement"
+type: feature
+status: todo
+prd: .tasks/PRD.md
+depends_on: F5
+---
+
+# F6 — Documentation des schémas & Déploiement
+
+## Objectif
+
+Rédiger la documentation des schémas PostgreSQL efarmz (chargée dans le system prompt du LLM), finaliser le Dockerfile pour Clever Cloud, et rédiger le README de setup. Aucun code de production à écrire dans cette feature.
+
+## Livrables
+
+### 1. Documentation des schémas (`docs/schemas/`)
+
+Un fichier `.md` par schéma PostgreSQL. Format attendu par `FileSystemSchemaCatalog` :
+
+```
+docs/schemas/
+├── efarmz_db.md          # schéma principal (commandes, clients, produits, …)
+├── efarmz_intercom.md    # schéma Intercom (conversations, contacts)
+└── ...                   # autres schémas si nécessaire
+```
+
+**Format de chaque fichier** (exemple `efarmz_db.md`) :
+
+```markdown
+# Schéma efarmz_db
+
+## Table: orders
+Description courte du contenu de la table.
+
+| Colonne        | Type        | Description                          |
+|----------------|-------------|--------------------------------------|
+| id             | uuid        | Identifiant unique de la commande    |
+| customer_id    | uuid        | Référence vers customers.id          |
+| status         | varchar     | Statut : pending, confirmed, shipped |
+| total_amount   | numeric     | Montant total TTC en euros           |
+| created_at     | timestamptz | Date de création                     |
+
+## Table: customers
+...
+```
+
+**Contenu fourni par l'utilisateur** — ce fichier est un placeholder vide à compléter.
+
+> Important : plus la doc est précise (descriptions des colonnes, valeurs d'enum, relations FK, exemples de valeurs), meilleure sera la qualité du SQL généré.
+
+### 2. `Dockerfile` finalisé
+
+Multi-stage, Node 22 slim, copie `docs/` dans l'image runtime :
+
+```dockerfile
+FROM node:22-slim AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --omit=dev
+COPY tsconfig.json ./
+COPY src ./src
+RUN npm run build
+
+FROM node:22-slim AS runtime
+WORKDIR /app
+ENV NODE_ENV=production
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/node_modules ./node_modules
+COPY docs ./docs
+EXPOSE 3000
+CMD ["node", "dist/main.js"]
+```
+
+### 3. Clever Cloud — configuration
+
+Fichier `clevercloud/` ou variables dans l'interface Clever Cloud :
+
+- **Type** : Node.js ou Docker (préférer Docker pour le contrôle de la version Node)
+- **Build** : `docker build`
+- **Port** : 3000 (variable `PORT`)
+- **Toutes les variables d'env** depuis `.env.example` à configurer dans l'interface CC
+
+### 4. Rôle PostgreSQL read-only
+
+Script SQL à exécuter manuellement sur la base de prod :
+
+```sql
+-- À adapter pour chaque schéma accessible
+CREATE USER slackbot_readonly WITH PASSWORD 'mot_de_passe_fort';
+GRANT CONNECT ON DATABASE efarmz TO slackbot_readonly;
+GRANT USAGE ON SCHEMA efarmz_db TO slackbot_readonly;
+GRANT SELECT ON ALL TABLES IN SCHEMA efarmz_db TO slackbot_readonly;
+ALTER DEFAULT PRIVILEGES IN SCHEMA efarmz_db GRANT SELECT ON TABLES TO slackbot_readonly;
+-- Répéter pour efarmz_intercom, etc.
+```
+
+### 5. `README.md`
+
+Sections :
+
+1. **Pré-requis** : Node 22, Docker, ngrok (dev local), compte Clever Cloud
+2. **Setup Slack App** :
+   - Créer une app sur api.slack.com
+   - Activer les scopes : `app_mentions:read`, `chat:write`, `chat:write.public`, `files:write`, `im:history`, `im:read`, `im:write`, `users:read`
+   - Activer les event subscriptions : `app_mention`, `message.im`
+   - URL webhook : `https://<clever-domain>/slack/events`
+   - Activer l'App Home → DM tab
+3. **Variables d'environnement** : référence à `.env.example`, description de chaque variable
+4. **Setup local (ngrok)** :
+   ```bash
+   cp .env.example .env
+   # Remplir .env
+   yarn dev
+   ngrok http 3000
+   # Configurer l'URL ngrok dans la Slack App
+   ```
+5. **Init PostgreSQL read-only** : script SQL ci-dessus
+6. **Déploiement Clever Cloud** : push Docker, config env vars
+7. **Ajout d'un nouveau schéma** : déposer un `.md` dans `docs/schemas/`, redéployer
+8. **Flags utilisateur** : `--sql`, `--debug`, `--no-context`
+
+## Acceptance Criteria
+
+- [ ] Au moins un fichier `docs/schemas/*.md` présent (même placeholder)
+- [ ] `docker build .` réussit depuis zéro
+- [ ] `README.md` couvre setup local (ngrok) et déploiement Clever Cloud
+- [ ] Script SQL init du rôle read-only documenté dans le README
+- [ ] `.env.example` contient toutes les variables avec commentaires explicatifs

package/CLAUDE.md

@@ -0,0 +1,163 @@
+# CLAUDE.md — efarmz-slackbot-data
+
+Bot Slack qui traduit des questions en langage naturel vers des requêtes SQL via LLM (boucle agentique), exécute en read-only sur les bases analytiques efarmz, et renvoie le résultat formaté dans Slack.
+
+> Plan détaillé : `.plans/efarmz-slackbot-data-712fe7.md`
+
+## Stack (différente du starter Next.js)
+
+- **Runtime** : Node.js 22 + TypeScript strict (ESM, `noUncheckedIndexedAccess`)
+- **Slack** : `@slack/bolt` (HTTP receiver Express, pas Socket Mode)
+- **DB** : `pg` (PAS de Drizzle — service standalone, pas de migrations)
+- **LLM** : `@anthropic-ai/sdk` par défaut (Haiku 4.5), derrière une interface `LLMProvider`
+- **Validation** : `zod`
+- **Logs** : `pino`
+- **Tests** : `vitest`
+- **Hosting** : Clever Cloud (Docker)
+
+Pas de Next.js, pas de React, pas de Tailwind, pas de Drizzle, pas de Trigger.dev, pas d'auth utilisateur (le workspace Slack est la frontière de sécurité).
+
+## Architecture DDD / Hexagonal
+
+Trois couches, **dépendances unidirectionnelles** : `domain` ← `application` ← `infrastructure` ← `main`.
+
+```
+src/
+├── domain/            # PURE — aucun import externe (sauf zod pour validation)
+│   ├── entities/      # Conversation, ConversationMessage, QueryResult
+│   ├── value-objects/ # ThreadId, Question, QuestionFlags, SqlQuery, ...
+│   ├── errors/        # DomainError + sous-classes
+│   └── ports/         # Interfaces : LLMProvider, SqlExecutor, SqlValidator, ...
+├── application/       # Use cases (orchestration) — dépend de domain seulement
+│   ├── usecases/      # AnswerQuestion, ParseQuestion
+│   ├── agent/         # AgentLoop, RunSqlTool
+│   └── formatting/    # ResponseRenderer + Scalar/Monospace/Csv renderers
+├── infrastructure/    # Adapters — implémente les ports de domain
+│   ├── llm/           # AnthropicLLMProvider
+│   ├── persistence/   # PostgresSqlExecutor, InMemoryConversationRepository
+│   ├── sql/           # RegexSqlValidator
+│   ├── schemas/       # FileSystemSchemaCatalog
+│   ├── slack/         # BoltSlackMessenger, handlers
+│   └── logging/       # PinoLogger
+├── config/            # env.ts (zod), Container (DI manuel), constants
+└── main.ts            # Entry point
+```
+
+### Dependency Rule (non-négociable)
+
+- `domain/` n'importe **JAMAIS** de `application/`, `infrastructure/`, `config/` ni de SDK tiers (`@slack/bolt`, `pg`, `@anthropic-ai/sdk`).
+- `application/` importe **uniquement** de `domain/`.
+- `infrastructure/` peut importer `domain/` (pour implémenter ses ports) — jamais `application/`.
+- `main.ts` + `config/Container.ts` sont les seuls endroits où on assemble (compose) les implémentations.
+
+Si tu te retrouves à importer `pg` ou `@slack/bolt` dans `domain/`, c'est une erreur d'architecture — il faut un nouveau port.
+
+## Conventions DDD
+
+**Value Objects** : immuables, validés à la construction via factory statique. Constructeur privé.
+```typescript
+// src/domain/value-objects/SqlQuery.ts
+class SqlQuery {
+  private constructor(public readonly raw: string) {}
+  static create(raw: string, validator: SqlValidator): SqlQuery {
+    return new SqlQuery(validator.validate(raw));
+  }
+}
+```
+
+**Entities** : ont une identité, encapsulent leurs invariants. Pas de DTO anémique.
+```typescript
+// src/domain/entities/Conversation.ts — append plafonne à N messages
+class Conversation {
+  append(message: ConversationMessage): Conversation { /* invariants ici */ }
+}
+```
+
+**Ports** : interfaces dans `domain/ports/`, granularité fine (ISP). Pas de port fourre-tout.
+- ✅ `SlackMessenger` (post) + `AdminLogger` (logQuery) séparés
+- ❌ `SlackService` qui mélange tout
+
+**Erreurs** : sous-classes de `DomainError`, jamais `throw new Error("string")` brut.
+
+**DI** : manuelle via `config/Container.ts`. Pas d'inversify/tsyringe.
+
+## Boucle agentique
+
+`AgentLoop.run()` itère sur `tool_use` jusqu'à `end_turn` ou `AGENT_MAX_TURNS`. À chaque tour avec `run_sql` :
+1. `SqlValidator.validate(input.sql)` → si KO, renvoie `tool_result.is_error = true` au LLM
+2. `SqlExecutor.execute(query)` → succès ou erreur PG renvoyée comme `tool_result.is_error`
+3. Le LLM corrige automatiquement au tour suivant — pas de logique de retry manuelle à écrire
+
+Si tu modifies la boucle, garde la règle : **toute erreur SQL doit être renvoyée comme `tool_result`, pas thrown**. Sinon le LLM ne peut pas corriger.
+
+## Sécurité SQL (4 couches, toutes obligatoires)
+
+1. **Utilisateur PG read-only** dédié (rôle `slackbot_readonly`) — impossible de muter même si tout le reste est bypassé
+2. **`RegexSqlValidator`** : doit commencer par `SELECT`/`WITH`, refuse les keywords mutables (INSERT/UPDATE/DELETE/DROP/CREATE/ALTER/TRUNCATE/GRANT/REVOKE/COPY/CALL/VACUUM/MERGE), refuse `;` en milieu de requête, force `LIMIT SQL_MAX_ROWS`
+3. **`SET statement_timeout = SQL_TIMEOUT_MS`** par session
+4. **`SqlQuery` VO** : constructeur privé — impossible d'exécuter un SQL non validé (vérifié au compile-time)
+
+**Ne jamais** ajouter un chemin qui contourne le validator — tout `SqlExecutor.execute` doit recevoir un `SqlQuery`, pas une `string`.
+
+## Doc des schémas
+
+`docs/schemas/*.md` — un fichier par schéma PostgreSQL (efarmz_db, efarmz_intercom, …). Chargés au boot par `FileSystemSchemaCatalog`, concaténés dans le system prompt avec `cache_control: { type: "ephemeral" }` (TTL 5 min Anthropic) pour économiser les tokens en rafale.
+
+Quand on ajoute un schéma : déposer le `.md` dans `docs/schemas/`, redéployer. Pas de code à changer.
+
+## Format de réponse
+
+`ResponseRenderer` décide :
+- 0 ligne → "Aucun résultat."
+- 1×1 → `ScalarRenderer` (valeur en gras)
+- ≤ `SQL_CSV_THRESHOLD` lignes → `MonospaceTableRenderer` (bloc code aligné inline)
+- \> `SQL_CSV_THRESHOLD` → monospace tronqué **+** CSV uploadé via `files.uploadV2`
+
+Flags utilisateur dans le message Slack :
+- `--sql` : ajoute le SQL en bloc code
+- `--debug` : `--sql` + `EXPLAIN`
+- `--no-context` : ignore l'historique du thread
+
+## Conventions de code
+
+- **Strings** : backticks (cohérent avec règles globales)
+- **Imports** : paths absolus `@/` (alias TS configuré sur `src/`), jamais `../`
+- **ESM** : tout est ESM, imports avec `.js` extension dans les paths relatifs si nécessaire
+- **Naming** : `PascalCase.ts` pour classes/types, `camelCase.ts` pour fonctions/helpers
+- **1 fichier = 1 export default** (cohérent avec convention globale)
+- **Pas de comments** sauf si le *why* est non-évident (cf. règles globales)
+
+## Commandes
+
+```bash
+yarn dev          # tsx watch src/main.ts
+yarn build        # tsc
+yarn start        # node dist/main.js
+yarn test         # vitest run
+yarn test:watch   # vitest
+yarn lint         # eslint
+yarn typecheck    # tsc --noEmit
+```
+
+## Variables d'environnement
+
+Voir `.env.example`. Toutes validées via `config/env.ts` (zod). Le boot échoue si une variable est manquante ou invalide (fail-fast).
+
+## Hors-scope V1
+
+À refuser si demandé sans discussion préalable :
+- UI admin web
+- Persistance DB du bot lui-même (LRU mémoire suffit pour les conversations)
+- Implémentation OpenAI concrète (l'interface est prête, l'impl viendra plus tard)
+- Graphiques, exports custom
+- Slash commands (`/efarmz-stats ...`)
+- i18n des réponses du bot
+- Auth utilisateur niveau bot (workspace = frontière)
+
+## Points d'attention récurrents
+
+- **Ack Slack < 3s** : les handlers doivent répondre `200 OK` immédiatement, traitement en arrière-plan
+- **Idempotence** : Slack retry — dédupliquer par `event_id` (cache 5 min)
+- **Prompt caching** : toujours marquer le bloc system (doc schémas) avec `cache_control: { type: "ephemeral" }`
+- **PII** : les résultats peuvent contenir emails/noms — workspace privé only, accepté
+- **Coûts** : surveiller via `SlackAdminLogger` (channel admin)