@ogygie/cli 0.1.0

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@ogygie/cli",
+  "version": "0.1.0",
+  "description": "Ogygie framework CLI: deterministic scaffolding (init), governed-file upgrades (upgrade) and lockstep verification (check) for Ogygie products.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "ogygie": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json",
+    "build": "tsx scripts/build.ts",
+    "record-checksums": "tsx scripts/record-governed-checksums.ts"
+  },
+  "devDependencies": {
+    "@ogygie/core": "workspace:*",
+    "@types/node": "^24.0.0",
+    "esbuild": "^0.28.0",
+    "tsx": "^4.20.0",
+    "typescript": "^5.8.0",
+    "zod": "^4.0.0"
+  }
+}

package/templates/feature/README.md

@@ -0,0 +1,9 @@
+# templates/feature — réservé (non câblé)
+
+Ce dossier est POSÉ par la spec `ogygie-standalone-repo` mais volontairement
+vide : le scaffolding de feature (`ogygie generate feature`) fera l'objet d'une
+spec ultérieure. En attendant, la forme canonique d'une feature est décrite
+dans `AGENTS.md` §Structure d'une feature, et l'exemple vivant est la feature
+`notes` du repo framework.
+
+Rien ici n'est lu par `ogygie init`, `upgrade` ni `check`.

package/templates/project/AGENTS.md

@@ -0,0 +1,483 @@
+# AGENTS.md — Ogygie v1 (conventions GÉNÉRIQUES du framework)
+
+> **Tu es un agent qui travaille sur ce repo. Lis ce fichier EN ENTIER, puis
+> `AGENTS.product.md` (les liaisons produit : noms réels, alias, listes fermées),
+> puis `ogygie.manifest.json`. Ne lis rien d'autre avant d'avoir une tâche précise.**
+>
+> Ce fichier est GÉNÉRIQUE — aucune règle ici ne nomme le produit ni son
+> domaine ; ses exemples utilisent un domaine neutre (`orders`). Tout ce qui
+> lie ces règles au produit réel vit dans `AGENTS.product.md`. Les décisions
+> structurantes du repo se consignent dans `DECISIONS.md` (framework) et
+> `DECISIONS.product.md` (produit) — numérotation `D<n>` globale unique aux
+> deux fichiers, vérifiée par verify-specs. Ils naissent vierges : ce produit
+> écrira ses propres décisions, en commençant au premier numéro.
+
+## Ordre de lecture obligatoire pour toute tâche
+
+1. `AGENTS.md` (ce fichier) — les règles.
+2. `AGENTS.product.md` — l'extension produit (alias, colonnes tenant, listes fermées).
+3. `ogygie.manifest.json` — la carte du repo (features, routes, dépendances).
+4. `specs/<feature>.spec.md` — la spec de la feature concernée (si elle existe).
+5. Le dossier `features/<feature>/` concerné — et LUI SEUL.
+
+Interdiction d'explorer le repo au-delà. Si le manifeste ne suffit pas à localiser ce dont tu as besoin, c'est un bug du manifeste : le signaler dans `FAILURES.md`.
+
+## Les 8 principes (version opérationnelle)
+
+1. **Localité radicale** — une feature = un dossier `features/<nom>/` autonome (route + schémas + logique + tests). Aucun fichier magique, aucun comportement par convention de nommage. Tout module chargé l'est par un import explicite.
+2. **Contrats aux frontières** — toute entrée/sortie (HTTP, DB, job, événement) passe par un schéma Zod. Le schéma est LA source de vérité : validation runtime + type TS inféré (`z.infer`) + doc.
+3. **Manifeste machine-lisible** — `ogygie.manifest.json` indexe tout. Toute PR qui ajoute/modifie une feature met à jour le manifeste dans le même commit. La CI casse si le manifeste ment.
+4. **Une seule façon idiomatique** — pour chaque besoin, copie le template canonique ci-dessous. N'invente pas de variante. Si le template est inadapté, ne contourne pas : propose un amendement de ce fichier.
+5. **Effets déclarés** — toute fonction qui touche DB/réseau/fs/horloge reçoit ses dépendances en paramètre (injection). Jamais d'import global de client au fond d'un helper.
+6. **Erreurs pour agents** — toute erreur suit le format `OgygieError` (voir `packages/ogygie-core/src/error.schema.ts`) : code stable, `file`, `cause`, `suggestedFix`.
+7. **Testabilité en secondes** — `pnpm test -- features/<nom>` doit passer en < 10 s, sans réseau ni DB réelle (voir template test).
+8. **Verbeux plutôt qu'ambigu** — noms longs et descriptifs, bloc `@intent` en tête de chaque fichier, imports complets. On écrit pour un lecteur sans contexte. **Le code est en ANGLAIS MAXIMAL** : identifiants, tables/colonnes BDD, routes HTTP, codes d'erreur, valeurs d'enum, noms de schémas et de patterns, et TOUS les commentaires (dont `@intent`) — sans exception. Le français reste réservé aux documents (specs, décisions, PR) et aux textes UI via clés ICU.
+
+## Structure d'une feature
+
+```
+features/orders/
+├── index.ts          # SEUL point d'export public de la feature
+├── routes.ts         # Enregistrement Fastify des endpoints
+├── schemas.ts        # Contrats Zod (input/output/erreurs métier)
+├── service.ts        # Logique métier PURE (dépendances injectées)
+├── repository.ts     # Accès DB (seul fichier autorisé à parler à Drizzle)
+├── service.test.ts   # Tests de la logique (rapides, sans I/O)
+└── routes.test.ts    # Tests des endpoints (fastify.inject, DB mémoire)
+```
+
+Règle de dépendance : `routes → service → repository`. Jamais l'inverse, jamais de saut (une route n'appelle pas le repository directement). Une feature importe une autre feature UNIQUEMENT via son `index.ts`, et cette dépendance est déclarée dans le manifeste.
+
+**Exception unique et bornée — les CONTRATS (amendement 2026-08).**
+`schemas.ts` est le seul fichier d'une feature qui n'importe QUE des contrats :
+zod, un contrat produit partagé (la liste fermée est dans `AGENTS.product.md`),
+et — quand une dépendance déclarée au manifeste l'exige — le `schemas.ts` d'une
+autre feature. JAMAIS son `index.ts`. Motif : un `index.ts` porte la surface
+SERVEUR (routes, service, chargeurs de données) ; or `schemas.ts` est importé
+par le FRONT (`@<produit>/api/features/<nom>/schemas` — c'est le zéro-drift de
+la stack front). Un contrat qui traîne du code serveur casse le build du front (constaté :
+un `schemas.ts` → l'`index.ts` d'une feature voisine → son loader → `node:fs`
+dans le bundle navigateur, FAILURES.md) ou y embarque Drizzle. Un `schemas.ts`
+reste donc importable par un navigateur, et ce n'est pas une promesse : le gate
+`pnpm ogygie:verify-contracts` parcourt tout le graphe d'imports depuis
+chaque `schemas.ts` — la TRANSITIVITÉ est le cœur du contrôle, c'est par un
+intermédiaire que le serveur revient — et casse la CI sur tout paquet hors
+liste (`zod` seul), tout `index.ts` atteint, et tout module illisible.
+
+## Templates canoniques
+
+### 1. Endpoint HTTP
+
+```ts
+// features/<nom>/routes.ts
+/**
+ * @intent HTTP endpoints of the <nom> feature.
+ * No business logic here: schema validation + delegation to the service.
+ */
+import type { FastifyInstance } from "fastify";
+import {
+  CreateOrderInputSchema,
+  CreateOrderOutputSchema,
+} from "./schemas.js";
+import { createOrder } from "./service.js";
+
+export async function registerOrderRoutes(app: FastifyInstance): Promise<void> {
+  app.post("/api/orders", {
+    schema: {
+      body: CreateOrderInputSchema,
+      response: { 201: CreateOrderOutputSchema },
+    },
+    handler: async (request, reply) => {
+      const result = await createOrder(
+        { db: app.db, clock: app.clock },
+        request.body,
+      );
+      return reply.code(201).send(result);
+    },
+  });
+}
+```
+
+### 2. Contrat Zod
+
+```ts
+// features/<nom>/schemas.ts
+/**
+ * @intent Data contracts of the <nom> feature.
+ * Single source of truth: runtime validation + TS types + documentation.
+ */
+import { z } from "zod";
+
+export const CreateOrderInputSchema = z.object({
+  customerId: z.uuid(),
+  reference: z.string().min(1).max(120),
+  quantity: z.number().int().positive().max(1_000_000),
+});
+export type CreateOrderInput = z.infer<typeof CreateOrderInputSchema>;
+```
+
+Règles : suffixe `Schema` obligatoire, type inféré exporté juste en dessous, jamais de type TS écrit à la main pour une donnée qui traverse une frontière. Union discriminée persistée = colonnes nullables par branche + contrainte CHECK miroir de la forme de l'union dans la migration.
+
+### 3. Service (logique pure, effets déclarés)
+
+```ts
+// features/<nom>/service.ts
+/**
+ * @intent Business logic of the <nom> feature. Pure functions:
+ * every effectful dependency (db, clock, network) is injected.
+ */
+import type { Database } from "@ogygie/core/db";
+import type { Clock } from "@ogygie/core/clock";
+import type { CreateOrderInput, CreateOrderOutput } from "./schemas.js";
+import { insertOrder } from "./repository.js";
+
+export interface CreateOrderDeps {
+  db: Database;
+  clock: Clock;
+}
+
+export async function createOrder(
+  deps: CreateOrderDeps,
+  input: CreateOrderInput,
+): Promise<CreateOrderOutput> {
+  // ... business logic ...
+  return insertOrder(deps.db, /* ... */);
+}
+```
+
+### 4. Accès DB
+
+Voir le template repository du §Multi-tenant (il REMPLACE tout accès direct) :
+tout repository reçoit le contexte tenant en premier paramètre et passe par
+`tenantDb`.
+
+### 5. Test
+
+```ts
+// features/<nom>/service.test.ts
+/**
+ * @intent Proves the behaviors described in specs/<nom>.spec.md.
+ * Each Given/When/Then block of the spec = one identically named test.
+ */
+import { describe, expect, it } from "vitest";
+import { createOrder } from "./service.js";
+import { createInMemoryDb, fixedClock } from "@ogygie/core/test-kit";
+
+describe("orders", () => {
+  it("ÉTANT DONNÉ un client connu QUAND on crée une commande ALORS elle est numérotée séquentiellement", async () => {
+    const deps = { db: await createInMemoryDb(migrations), clock: fixedClock("2026-07-01") };
+    const result = await createOrder(deps, /* fixture */); // fixture from the spec
+    expect(result.sequenceNumber).toBe(1);
+  });
+});
+```
+
+### 6. Erreur métier
+
+```ts
+import { ogygieError } from "@ogygie/core/errors";
+
+throw ogygieError({
+  code: "ORDER_CUSTOMER_NOT_FOUND",
+  message: "The targeted customer does not exist for this tenant.",
+  file: "src/features/orders/service.ts",
+  cause: `customerId=${input.customerId} absent from the customers table`,
+  suggestedFix: "Create the customer via POST /api/customers before creating an order.",
+});
+```
+
+## Workflow de livraison d'une feature
+
+1. Lire la spec (`specs/<nom>.spec.md`, status `validated`). Pas de spec validée = pas de code.
+   Amender une spec en cours de session = commit séparé dédié, signalé dans la PR et validé en revue.
+2. Écrire `schemas.ts` d'abord (les contrats), puis les tests (depuis les Given/When/Then), puis l'implémentation.
+3. Mettre à jour `ogygie.manifest.json` (feature, routes, dépendances).
+4. `pnpm test -- features/<nom>` vert en < 10 s.
+5. Si un pattern se répète pour la 3e fois → le signaler comme candidat à l'extraction `@ogygie/core`.
+   Exception : l'outillage et l'infrastructure GÉNÉRIQUES peuvent naître ou
+   monter dans le core sans attendre 3 répétitions ; le code métier, jamais. Critère : le
+   module contient-il une seule décision propre au produit ? Si oui, il reste dans `apps/`.
+6. Si tu as halluciné une API, cassé une feature ou tourné en rond → consigner dans `FAILURES.md` (date, symptôme, cause racine, convention qui l'aurait empêché).
+7. Tout gate CI (verify-*, lint) naît et se durcit avec son test négatif : un test de mutation prouve qu'une violation connue est détectée.
+8. Git : force-push, réécriture d'historique et isolation des sessions
+   (un worktree par session) → voir §Évolution d'une feature livrée,
+   « Règles git ». Une seule formulation dans ce fichier, pas deux.
+
+## Interdits absolus
+
+- `any`, `as unknown as`, `@ts-ignore` (utiliser `@ts-expect-error` avec justification si inévitable).
+- Import d'un fichier interne d'une autre feature (passer par son `index.ts`).
+- Client DB/HTTP importé globalement dans un helper.
+- Type écrit à la main pour une donnée qui a un schéma Zod.
+- Commit qui modifie une feature sans mettre à jour manifeste + tests.
+- **Garde de nullité écrite `=== null` / `!== null` sur un champ OPTIONNEL ou
+  ÉLARGI.** Elle s'écrit `== null` / `!= null` — qui attrape `null` ET
+  `undefined` — ou la donnée passe par son schéma Zod (dont le `.default(null)`
+  normalise). Motif, constaté (FAILURES.md 2026-07-31) : une donnée AU REPOS
+  écrite avant l'ajout du champ ne porte pas la clé, donc vaut `undefined` et
+  non `null` ; la garde stricte y lit « présent » et le code croit à une valeur
+  saisie qui n'existe pas. Le contrat porte bien le défaut, mais rien n'oblige
+  un appelant à parser : fixtures, tests et scripts lisent le JSON brut.
+
+## Internationalisation (règles worldwide — non négociables)
+
+1. **Domaine en unités SI canoniques.** La base et les services stockent et calculent
+   TOUJOURS dans les unités SI du domaine (mètres, m², kg, litres…). Jamais une unité
+   locale (impériale…) dans un calcul. La conversion est un problème de PRÉSENTATION,
+   résolu une fois dans le front via `preferences.unitSystem` du tenant.
+2. **Argent = jamais un float.** Tout montant est `{ amountCents: int, currency: ISO4217 }`.
+   Les calculs monétaires passent par les helpers de `@ogygie/core/money` (à créer).
+   Un tenant a UNE devise de travail ; pas de conversion de change en v1.
+3. **Aucune chaîne UI en dur.** Tout texte visible passe par une clé de traduction ICU
+   (`t("orders.create.title")` — clés de traduction en anglais). Les libellés saisis
+   par l'utilisateur sont des DONNÉES, jamais traduits.
+4. **Les messages d'OgygieError ont deux canaux** : `message` (anglais technique, pour
+   les logs et les agents) + `userMessageKey` (clé ICU pour l'affichage).
+   `suggestedFix` reste en anglais technique.
+5. **Temps** : dates stockées en UTC ISO 8601 ; chaque tenant a un fuseau IANA.
+   Les semaines sont des semaines ISO 8601 (lundi = premier jour) partout — l'affichage
+   local peut différer, pas le calcul.
+6. **Identifiants code en anglais, contenu en langue de l'utilisateur.** Les enums du
+   domaine sont en anglais ; leur affichage est traduit.
+
+## Front (apps/web) — règles et templates canoniques
+
+### Stack imposée (toute autre lib = amendement DECISIONS.md d'abord)
+Vite + React 19 + TanStack Router (routing EN CODE) + TanStack Query (état serveur) ;
+PAS de lib d'état client (useState suffit) ; Tailwind v4 thémé depuis `design/tokens.json`
+(valeurs arbitraires `p-[13px]` interdites par lint) ; primitives UI copiées dans
+`apps/web/src/patterns/` (jamais consommées directement depuis node_modules par une
+feature) ; react-hook-form UNIQUEMENT via le pattern `ContractForm` ; TanStack
+Table UNIQUEMENT via `DataTable` ; Recharts UNIQUEMENT via `VarianceChart` ;
+date-fns via les helpers `@ogygie/core` (jamais de `new Date()` nu) ; i18n Lingui
+(ICU, extraction vérifiée en CI). Noms de patterns en anglais.
+
+### Structure d'une feature front (miroir de l'API)
+```
+apps/web/features/orders/
+├── index.ts            # seul export public
+├── routes.tsx          # définition TanStack Router de la feature
+├── queries.ts          # hooks TanStack Query (fetch + invalidations)
+├── OrdersList.tsx      # écrans = composition de patterns, rien d'autre
+├── OrderForm.tsx
+└── OrdersList.test.tsx # un test par état UI de la spec
+```
+
+### Template canonique — hook de requête
+```ts
+// apps/web/features/orders/queries.ts
+/** @intent Data access of the orders feature. Re-validates contracts in dev. */
+import { useQuery } from "@tanstack/react-query";
+import { ListOrdersOutputSchema } from "@product/api/features/orders/schemas";
+import { fetchContract } from "../../lib/fetchContract"; // Zod parse in dev, OgygieError on broken contract
+
+export function useOrders() {
+  return useQuery({
+    queryKey: ["orders"],
+    queryFn: () => fetchContract("/api/orders", ListOrdersOutputSchema),
+  });
+}
+```
+
+### Template canonique — écran
+```tsx
+// apps/web/features/orders/OrdersList.tsx
+/** @intent Orders list screen: composition of patterns, zero business logic. */
+import { Trans } from "@lingui/react/macro";
+import { DataTable } from "../../patterns/DataTable";
+import { EmptyState } from "../../patterns/EmptyState";
+import { ErrorBanner } from "../../patterns/ErrorBanner";
+import { useOrders } from "./queries";
+
+export function OrdersList() {
+  const { data, isPending, error } = useOrders();
+  if (error) return <ErrorBanner error={error} />;
+  if (isPending) return <DataTable.Skeleton />;
+  if (data.orders.length === 0)
+    return <EmptyState title={<Trans>Ajoutez votre première commande</Trans>} />;
+  return <DataTable rows={data.orders} columns={orderColumns} />;
+}
+```
+
+### Règles front absolues
+- Un écran est une COMPOSITION de patterns : jamais de `<table>`, `<form>` ou fetch nus
+  dans une feature. Si un pattern manque, on le crée dans `patterns/` (et on met à jour
+  `design/patterns.md`), on ne bricole pas dans la feature.
+- Chaque état UI listé dans la spec (vide/chargement/nominal/erreur) a son test.
+- Toute chaîne visible passe par Lingui (`<Trans>`/`t`) — la CI casse sinon.
+- Chiffres financiers : `tabular-nums`, alignés à droite, unité explicite.
+
+### La boucle design (specs/ogygie-design-brief.spec.md)
+Avant de maquetter un écran, générer le brief DÉRIVÉ de la feature :
+```
+pnpm ogygie:design-brief <feature>   → design/briefs/<feature>.md
+```
+Le brief tire tout des sources de vérité : tokens (`design/tokens.json`),
+patterns (`design/patterns.md` + les modules des apps front), champs des
+contrats Zod des routes, actions par méthode, états UI de la spec, codes
+d'erreur réels, volumétries des fixtures. L'outil de design (humain ou IA)
+produit une mise en page — jamais du code ; la décision humaine revient dans
+la spec de la feature (section « # Design »), puis l'implémentation suit la
+spec. Règle non négociable : le design ne crée jamais de token ni de
+composant one-off — une couleur ou un espacement absent est un amendement de
+`design/tokens.json`, un pattern manquant naît dans le catalogue.
+
+## Multi-tenant (SaaS) — sécurité structurelle, non optionnelle
+
+Le produit est un SaaS multi-tenant. La fuite inter-tenants est le risque n°1
+d'un code écrit par agents : elle doit être IMPOSSIBLE par construction, pas évitée
+par vigilance.
+
+1. **Toute fonction de repository reçoit un contexte tenant en premier paramètre**,
+   fourni par le middleware d'auth — jamais par le body ou la query string du client.
+   Le core expose le type GÉNÉRIQUE `TenantContext` (`{ tenantId: uuid, userId: uuid }`) ;
+   le produit l'aliase sous son propre nom (déclaré dans `AGENTS.product.md`) — le core
+   ne connaît AUCUN mot du domaine du produit (règle de séparation, le journal des décisions).
+2. **Tout accès Drizzle passe par `tenantDb(ctx)`** (`@ogygie/core/tenant`) qui
+   applique systématiquement le filtre de la colonne tenant (nom déclaré dans
+   `AGENTS.product.md`). Accès Drizzle direct hors de ce helper = interdit
+   (règle lint `ogygie/no-raw-db`).
+3. **Row-Level Security PostgreSQL activée sur toute table portant la colonne
+   tenant** (second rempart : même une requête buggée ne peut pas lire un
+   autre tenant). Toute migration créant une table tenant inclut sa policy RLS —
+   le template de migration l'impose.
+4. Les tables de référentiel PARTAGÉ — connaissance universelle qu'aucun tenant
+   ne possède, chargée par un script d'extraction depuis une source externe
+   versionnée — sont déclarées explicitement au manifeste sous la forme objet
+   `{ "name": "<table>", "shared": true }` (clé anglaise : le manifeste est
+   machine-lisible). Elles échappent alors à la règle 3 (pas de colonne
+   tenant, pas de policy RLS tenant) ET à la règle 2 : n'ayant aucune colonne
+   sur laquelle filtrer, elles se lisent hors de `tenantDb`. Ce droit se paie
+   comptant, et les gates le vérifient au lieu de faire confiance :
+   - une feature ne gagne l'accès brut à la base que si TOUTES ses tables sont
+     partagées (lint-interdits, dérivé du manifeste) — une seule table tenant
+     dans la même feature le lui retire ;
+   - une table déclarée partagée qui porte encore la colonne tenant casse
+     verify-manifest (`SHARED_TABLE_WITH_TENANT_COLUMN`) ;
+   - côté API ces tables sont en LECTURE SEULE : seul le script d'extraction
+     les alimente.
+   La liste des tables partagées du produit est dans `AGENTS.product.md`.
+
+### Template repository (le SEUL accès DB autorisé)
+```ts
+// features/<nom>/repository.ts
+/** @intent Only file of the feature allowed to touch the DB, always through tenantDb. */
+import type { ProductContext } from "../../context.js"; // the product's alias of TenantContext (real name: AGENTS.product.md)
+import { tenantDb } from "@ogygie/core/tenant";
+import { orders } from "./db.schema.js";
+
+export async function insertOrder(ctx: ProductContext, values: NewOrder) {
+  const [row] = await tenantDb(ctx).insert(orders).values(values).returning();
+  return row; // tenant column injected and filtered by tenantDb, never by hand
+}
+```
+Les services propagent `ctx` tel quel (routes → service → repository) sans jamais le
+reconstruire ni le modifier.
+
+### Piège connu de la façade tenantDb (TS2353)
+L'excess-property-check TypeScript bute sur les littéraux inline passés au
+`set()` générique de `TenantDb` (TS2353 alors que la propriété existe).
+Convention : passer des VARIABLES TYPÉES sur les types concrets
+(`Partial<Omit<NewX, ...>>`), jamais des littéraux inline. Plus lisible, et
+le compilateur est d'accord.
+
+## Sécurité — interdits vérifiables
+
+La sécurité est structurelle : un agent suit des rails, il ne « fait pas attention ».
+S'ajoutent au multi-tenant (§ précédent) et aux contrats Zod :
+
+1. **Secrets** : uniquement via variables d'environnement, validées au démarrage par
+   le schéma de `apps/api/src/env.ts` (boot refusé si un secret manque). Aucun secret
+   en dur nulle part — gitleaks casse la CI sinon.
+2. **Tout identifiant venant du client est hostile.** L'appartenance fait foi via
+   le contexte tenant ; jamais d'identifiant tenant lu depuis body/query/params
+   (seule exception : la route de bascule du tenant actif, qui vérifie l'appartenance).
+3. **Front** : `dangerouslySetInnerHTML` interdit (lint). On ne débranche jamais
+   l'échappement React.
+4. **Bootstrap Fastify** : `@fastify/helmet` + `@fastify/rate-limit` posés une fois
+   dans `apps/api/src/server.ts` — jamais feature par feature.
+5. **Sessions** : cookies `httpOnly + secure + sameSite=lax` (vérifier la config
+   Better Auth, ne pas présumer).
+6. **Dépendances** : ajouter un paquet npm est un événement RARE. Justification
+   obligatoire dans la PR, nom du paquet vérifié sur le registre (anti-slopsquatting),
+   `--frozen-lockfile` en CI. En cas de doute sur un nom de paquet : STOP et demander.
+7. **Erreurs en production** : seuls les champs d'OgygieError sortent vers le client ;
+   jamais de stack trace ni de détail interne.
+8. **URL d'API en dur côté front : interdit.** Le front appelle `/api/...`
+   en relatif — il ne connaît ni l'hôte ni le port de l'API. Toute
+   URL absolue vers l'API dans apps/web est une violation (lint).
+9. **La passerelle n'autorise jamais.** Aucune règle d'accès, aucun filtre
+   métier dans apps/gateway : l'autorisation vit dans l'API (session →
+   contexte tenant → tenantDb). Un relais qui autorise devient un confused
+   deputy.
+10. **Toute route publique passe par le manifeste.** Une route API absente
+    du manifeste est inatteignable depuis l'extérieur (la passerelle ne la
+    monte pas) — le manifeste est aussi une surface de sécurité.
+
+## Évolution d'une feature livrée
+
+Modifier une feature existante suit un protocole aussi canonique que sa création.
+Le contexte complet d'une feature vit dans TROIS artefacts : son entrée au
+manifeste, sa spec, son dossier — jamais dans d'anciennes PR ni de mémoire de
+session. Si ces trois-là ne suffisent pas à comprendre la feature : STOP,
+FAILURES.md.
+
+### Cycle de vie de la spec
+- Une évolution ROUVRE la spec : commit « spec amendment » qui modifie les
+  comportements ET repasse `status: implemented → validated`.
+- La spec décrit toujours L'ÉTAT COURANT VOULU (jamais un empilement de deltas) ;
+  l'historique vit dans une section `# Changelog` en fin de spec :
+  `## v2 — AAAA-MM — <ajouts / retraits / motif>` + le git log.
+- Retour à `implemented` : chaque nouveau comportement a son test, les anciens
+  tests restent verts, SAUF ceux d'un comportement explicitement retiré au
+  Changelog (le retrait d'un test sans ligne de Changelog = violation).
+- Gate verify-specs : feature `delivered` + spec `validated` = « évolution en
+  cours », état légitime et visible ; jamais un état permanent (> 1 PR = signal).
+
+### Première commande obligatoire : le rayon d'impact
+Avant toute modification d'une feature livrée, lancer :
+```
+pnpm ogygie:impact <feature>
+```
+Tout dépendant listé doit rester vert à la fin de la session. Un dépendant
+cassé sciemment (contrat qui change) est migré DANS LA MÊME PR.
+
+### Contrats exportés : élargir libre, restreindre = événement
+- ÉLARGIR un schéma exporté (champ optionnel en plus, nouvelle valeur d'enum
+  en sortie) : libre.
+- RESTREINDRE ou RENOMMER (champ retiré/renommé, contrainte durcie, valeur
+  d'enum supprimée, route déplacée) : exige `ogygie:impact`, migration de tous
+  les consommateurs dans la même PR, et mention explicite dans la description
+  de PR. C'est notre semver à l'échelle du monorepo : tout bouge ensemble ou
+  rien ne bouge.
+
+### Migrations en évolution : additives d'abord (expand → migrate → contract)
+À la création d'une feature, une migration est libre. En évolution, il y a des
+données réelles :
+1. EXPAND : ajouter (colonne nullable, nouvelle table, nouvel index) — jamais
+   casser l'existant dans ce pas.
+2. MIGRATE : remplir/backfiller, basculer le code sur le nouveau chemin.
+3. CONTRACT : supprimer l'ancien (colonne, contrainte) — dans une release
+   ULTÉRIEURE, jamais le même lot que le code qui l'exploite.
+- Interdits en un seul lot : RENAME de colonne/table exploitée, DROP d'une
+  colonne encore lue, changement de type en place. Toute migration destructive
+  = section dédiée dans la description de PR.
+- Rappel : toute nouvelle table tenant garde sa policy RLS.
+
+### Règles git
+- **Force-push : sur une branche de feature avant revue, OUI ; sur `main`,
+  JAMAIS** (la protection de branche doit l'interdire côté GitHub).
+- Toute réécriture d'historique (rebase, cherry-pick, reconstruction depuis
+  le reflog) se conclut par DEUX preuves avant push : `git diff` vide contre
+  l'état validé, et boucle complète re-passée verte. Sans ces deux preuves,
+  ne pas pousser.
+- **`git checkout/restore -- <chemin>` ne vise JAMAIS un répertoire** tant que
+  le travail n'est pas committé : il écrase l'arbre sans confirmation et sans
+  rien laisser au reflog (constaté, FAILURES.md 2026-07-31 — dix fichiers de
+  session effacés par une commande de commodité). Pour comparer avec HEAD,
+  extraire une COPIE (`git show HEAD:<fichier>`), ne pas remettre l'arbre à
+  HEAD.
+- **Une session = un worktree** : ne bascule JAMAIS la branche d'un
+  répertoire que tu ne sais pas exclusivement tien. Si `git status` montre
+  des modifications qui ne sont pas les tiennes : STOP, signale-le, ne
+  stash pas.

package/templates/project/AGENTS.product.md

@@ -0,0 +1,48 @@
+# AGENTS.product.md — Extension produit : __PRODUCT_NAME__
+
+> Lu APRÈS `AGENTS.md` (les règles génériques du framework Ogygie), qu'il ne
+> répète jamais : ce fichier ne contient que les LIAISONS — les noms réels que
+> les règles génériques laissent en placeholder, et les règles qui n'existent
+> que pour ce produit. C'est LE premier fichier à remplir après `ogygie init` :
+> tant qu'une section dit « à définir », la règle générique correspondante n'a
+> pas de prise sur ce produit.
+
+## Identité
+
+- Produit : **__PRODUCT_NAME__** — à décrire : le job-to-be-done du produit en
+  une phrase (reporter aussi la description dans `ogygie.manifest.json`).
+- Les ids de features/specs sont en FRANÇAIS : ils nomment des documents, pas
+  du code.
+
+## Liaisons multi-tenant
+
+- Tenant du produit : **à définir** (le mot du domaine qui possède les
+  données). L'alias produit de `TenantContext` est **`<Tenant>Context`**
+  (`apps/api/src/context.ts`) : clé TS de colonne `<tenant>Id`, colonne SQL
+  **`<tenant>_id`** — à déclarer aussi dans `scripts/verify-manifest.ts`
+  (`TENANT_COLUMN_NAMES`).
+- Liste fermée du socle autorisé à toucher la base brute : **à définir** (la
+  feature qui CONSTRUIT les contextes tenant) — déclarée dans
+  `scripts/lint-interdits.ts` (`RAW_DB_SOCLE_ALLOWLIST`). Toute autre feature
+  passe par `tenantDb`, sauf les features à tables 100 % partagées (dérivé du
+  manifeste).
+- Seule route autorisée à recevoir un identifiant de tenant côté client : la
+  route de bascule du tenant actif (appartenance vérifiée, 403 opaque sinon) —
+  l'exception prévue par AGENTS.md §Sécurité 2. À nommer ici quand elle existe.
+
+## Contrats produit partagés (exception §Structure)
+
+- Aucun pour l'instant : la liste fermée est VIDE. Le jour où deux features
+  partagent un contrat transverse, il naît sous `apps/api/src/` et s'ajoute
+  ici.
+
+## Tables partagées du produit (§Multi-tenant règle 4)
+
+- Aucune pour l'instant. Une table de référentiel partagé se déclare au
+  manifeste (`{ "name": "...", "shared": true }`) et s'ajoute ici avec sa
+  source et son script d'extraction.
+
+## Règles produit
+
+- (aucune pour l'instant — toute règle qui ne vaut que pour ce produit se
+  consigne ici, jamais dans AGENTS.md, qui est gouverné par Ogygie)

package/templates/project/CLAUDE.md

@@ -0,0 +1,29 @@
+# Instructions pour Claude Code
+
+Avant TOUTE tâche, lis dans cet ordre :
+1. `AGENTS.md` — les règles et templates canoniques GÉNÉRIQUES (obligatoire, en entier)
+2. `AGENTS.product.md` — l'extension produit : alias, colonnes tenant, listes fermées (obligatoire, en entier)
+3. `ogygie.manifest.json` — la carte du repo
+4. `DECISIONS.md` (framework) et `DECISIONS.product.md` (produit) — les décisions actées (ne jamais les rouvrir ; numérotation D<n> globale sur les deux fichiers)
+5. La spec de la feature concernée dans `specs/` (une spec `status: validated` = droit d'implémenter)
+
+N'explore pas le repo au-delà du dossier de la feature concernée.
+Si les fichiers ci-dessus ne suffisent pas pour accomplir la tâche : STOP,
+consigne le manque dans `FAILURES.md` et demande, plutôt que de deviner.
+
+Communication en français. Frontière linguistique : tout ce qui est
+MACHINE-LISIBLE est en ANGLAIS — identifiants, fonctions, tables et colonnes
+BDD, routes HTTP, codes d'erreur, valeurs d'enum, noms de schémas/contrats et
+de patterns, clés du manifeste, champs OgygieError, et TOUS les commentaires
+(y compris `@intent`) — aucune exception. Tout ce qui est destiné aux HUMAINS
+du projet reste en FRANÇAIS : specs (prose et titres de sections),
+DECISIONS.md, DECISIONS.product.md, FAILURES.md, PR, textes UI via clés ICU,
+ids de features/specs.
+
+La boucle verte du repo est `pnpm verify` (gates → typecheck → lint → tests).
+Elle doit être verte avant tout commit.
+
+N'utilise AUCUN skill ou workflow de processus externe (superpowers, brainstorming,
+plans multi-étapes génériques) : le processus de ce repo est défini par AGENTS.md
+et les specs, rien d'autre. Si ce processus te semble insuffisant pour une tâche,
+consigne le manque dans FAILURES.md au lieu de compenser par un skill.

package/templates/project/DECISIONS.md

@@ -0,0 +1,18 @@
+# DECISIONS.md — Décisions structurantes du FRAMEWORK
+
+> Chaque décision est datée, motivée, et cite ce qu'elle exclut. Un agent ne
+> rouvre pas une décision actée : il la lit ici et s'y conforme (ou propose un
+> amendement). Ce fichier porte les décisions FRAMEWORK (conventions,
+> outillage, gates) ; les décisions propres au produit vivent dans
+> `DECISIONS.product.md`. La numérotation `D<n>` est GLOBALE aux deux fichiers
+> — un même numéro ne peut exister qu'à un seul endroit (gate
+> DECISION_DECLARED_TWICE).
+>
+> Format d'une décision :
+>
+> ## D<n> — AAAA-MM-JJ — <titre>
+> - **Décision** : …
+> - **Motivation** : …
+> - **Exclut** : …
+
+(aucune décision pour l'instant — la première sera D1)

package/templates/project/DECISIONS.product.md

@@ -0,0 +1,11 @@
+# DECISIONS.product.md — Décisions structurantes du PRODUIT
+
+> Chaque décision est datée, motivée, et cite ce qu'elle exclut. Un agent ne
+> rouvre pas une décision actée : il la lit ici et s'y conforme (ou propose un
+> amendement). Ce fichier porte les décisions propres au PRODUIT (périmètre,
+> domaine, arbitrages métier) ; les décisions du framework vivent dans
+> `DECISIONS.md`. La numérotation `D<n>` est GLOBALE aux deux fichiers — un
+> même numéro ne peut exister qu'à un seul endroit (gate
+> DECISION_DECLARED_TWICE).
+
+(aucune décision pour l'instant)

package/templates/project/FAILURES.md

@@ -0,0 +1,16 @@
+# FAILURES.md — Journal des échecs
+
+> Spec vivante du framework : chaque fois qu'un agent hallucine une API, casse
+> une feature ou tourne en rond, l'échec se consigne ICI — date, symptôme,
+> cause racine, et la convention qui l'aurait empêché. Un échec non consigné
+> se reproduira.
+>
+> Format d'une entrée :
+>
+> ## AAAA-MM-JJ — <symptôme en une ligne>
+> - **Symptôme** : …
+> - **Cause racine** : …
+> - **Convention qui l'aurait empêché** : … (et si elle n'existe pas : la
+>   proposer en amendement d'AGENTS.md ou en décision)
+
+(aucun échec consigné pour l'instant)