@ogygie/core 0.1.0

package/src/contract-purity.ts

@@ -0,0 +1,213 @@
+/**
+ * @intent TRANSITIVE purity of the contract entry points (DECISIONS.md D29):
+ * from a feature's `schemas.ts`, no module with a runtime effect may be
+ * REACHABLE — neither directly nor through any chain of intermediaries.
+ *
+ * `@ogygie/core/module-purity` answers "is THIS file pure?". This module
+ * answers "is everything reachable from this contract pure?", which is the
+ * question that matters: the server never came back into the browser bundle
+ * through a direct import, it came back through an intermediary
+ * (a `schemas.ts` → a sibling feature's `index.ts` → its data loader →
+ * `node:fs`, FAILURES.md). A contract is imported by apps/web (the zero-drift of D4), so
+ * its whole reachable graph is part of the browser bundle.
+ *
+ * Two rules, both structural:
+ * - every external specifier reachable from a contract must be in the
+ *   allowlist (`zod` and nothing else by default);
+ * - no `index.ts` may be reached: it is the SERVER entry point of a feature
+ *   (AGENTS.md §Structure), the exact edge of the incident above.
+ * Plus one honesty rule: a module the walk cannot READ is reported, never
+ * skipped — a gate that silently swallows what it does not understand is
+ * worse than no gate (D22).
+ *
+ * Generic tooling, hence the core (D10 amended): it knows the framework's
+ * vocabulary (apps, features, schemas.ts, index.ts) and not one word of the
+ * product's domain. The filesystem is INJECTED (`readModule`), so the walk is
+ * a pure function, tested in memory with its mutations (D22).
+ */
+import { parseModuleImports } from "./module-purity.js";
+
+/** External packages a contract graph may import at runtime. */
+export const CONTRACT_ALLOWED_RUNTIME_SPECIFIERS = ["zod"] as const;
+
+/**
+ * The shape of the manifest this audit needs — structurally satisfied by
+ * `OgygieManifest`, and small enough to be written by hand in a test.
+ */
+export interface ContractPurityManifest {
+  apps: readonly { name: string; path: string; type: string }[];
+  features: readonly {
+    name: string;
+    app?: string | undefined;
+    folder: string;
+    status: string;
+  }[];
+}
+
+export type ContractImpurityKind =
+  /** An external package that is not in the runtime allowlist. */
+  | "RUNTIME_PACKAGE"
+  /** An `index.ts`: the server surface of a feature, never a contract. */
+  | "SERVER_SURFACE"
+  /** A relative import resolving to nothing readable — reported, not ignored. */
+  | "MODULE_NOT_FOUND";
+
+export interface ContractImpurity {
+  kind: ContractImpurityKind;
+  /** The contract whose graph is broken, e.g. apps/api/src/features/orders/schemas.ts. */
+  entryPath: string;
+  /** Entry → … → the module holding the faulty import. Shortest known path. */
+  chain: readonly string[];
+  /** Specifier as written (or the resolved path when nothing could be read). */
+  specifier: string;
+  /** Raw import statement, quoted back so the fix needs no guessing. */
+  statement: string;
+  /** The rule broken, in English, ready to be shown to an agent. */
+  rule: string;
+}
+
+export interface ContractPurityReport {
+  /** The contracts audited, one per non-skeleton feature of the api app. */
+  entryPaths: readonly string[];
+  /** Every module reached across all graphs — the audited surface. */
+  reachedPaths: readonly string[];
+  impurities: readonly ContractImpurity[];
+}
+
+export interface ContractPurityOptions {
+  manifest: ContractPurityManifest;
+  /** Reads a repo-relative path; `null` when the module does not exist. */
+  readModule: (path: string) => string | null;
+  /** Defaults to CONTRACT_ALLOWED_RUNTIME_SPECIFIERS. */
+  allowedRuntimeSpecifiers?: readonly string[];
+}
+
+/**
+ * The `schemas.ts` of every non-skeleton feature owned by the api app —
+ * derived from the manifest, never a hand-kept list (a feature added without
+ * its gate would be a hole).
+ */
+export function contractEntryPaths(manifest: ContractPurityManifest): string[] {
+  const apiApp = manifest.apps.find((app) => app.type === "api");
+  if (apiApp === undefined) return [];
+  const apiAppNames = new Set(
+    manifest.apps.filter((app) => app.type === "api").map((app) => app.name),
+  );
+  return manifest.features
+    .filter((feature) => feature.status !== "skeleton")
+    .filter((feature) => feature.app === undefined || apiAppNames.has(feature.app))
+    .map((feature) => `${apiApp.path}/${feature.folder}/schemas.ts`);
+}
+
+/** Walks every contract graph and reports what breaks its purity. */
+export function auditContractPurity(options: ContractPurityOptions): ContractPurityReport {
+  const allowed = new Set(
+    options.allowedRuntimeSpecifiers ?? CONTRACT_ALLOWED_RUNTIME_SPECIFIERS,
+  );
+  const entryPaths = contractEntryPaths(options.manifest);
+  const impurities: ContractImpurity[] = [];
+  const reachedPaths = new Set<string>();
+
+  for (const entryPath of entryPaths) {
+    // Breadth-first, so the chain reported for a module is the SHORTEST way
+    // the server comes back — the one a human has to cut.
+    const queue: { path: string; chain: readonly string[] }[] = [
+      { path: entryPath, chain: [entryPath] },
+    ];
+    const visited = new Set<string>([entryPath]);
+
+    while (queue.length > 0) {
+      const current = queue.shift();
+      if (current === undefined) break;
+      reachedPaths.add(current.path);
+
+      const source = options.readModule(current.path);
+      if (source === null) {
+        impurities.push({
+          kind: "MODULE_NOT_FOUND",
+          entryPath,
+          chain: current.chain,
+          specifier: current.path,
+          statement:
+            current.path === entryPath ? "contract entry point" : "import of the module above",
+          rule: `Module ${current.path} cannot be read: a contract graph is audited whole or not at all.`,
+        });
+        continue;
+      }
+
+      for (const moduleImport of parseModuleImports(source)) {
+        // Erased at compile time: no runtime edge, nothing enters the bundle.
+        if (moduleImport.typeOnly) continue;
+        const resolution = resolveContractImport(moduleImport.specifier, current.path);
+
+        if (resolution.kind === "external") {
+          if (allowed.has(resolution.specifier)) continue;
+          impurities.push({
+            kind: "RUNTIME_PACKAGE",
+            entryPath,
+            chain: current.chain,
+            specifier: resolution.specifier,
+            statement: moduleImport.statement,
+            rule: `Package "${resolution.specifier}" is not importable from a contract (allowed: ${[...allowed].join(", ")}).`,
+          });
+          continue;
+        }
+        if (resolution.kind === "server-surface") {
+          impurities.push({
+            kind: "SERVER_SURFACE",
+            entryPath,
+            chain: current.chain,
+            specifier: moduleImport.specifier,
+            statement: moduleImport.statement,
+            rule: `${resolution.path} is a feature's index.ts: the SERVER entry point, never a contract (AGENTS.md §Structure).`,
+          });
+          continue;
+        }
+        if (visited.has(resolution.path)) continue;
+        visited.add(resolution.path);
+        queue.push({ path: resolution.path, chain: [...current.chain, resolution.path] });
+      }
+    }
+  }
+
+  return { entryPaths, reachedPaths: [...reachedPaths], impurities };
+}
+
+export type ContractImportResolution =
+  | { kind: "internal"; path: string }
+  | { kind: "server-surface"; path: string }
+  | { kind: "external"; specifier: string };
+
+/**
+ * Where a specifier leads, LEXICALLY (no filesystem): a relative specifier is
+ * a repo path with its TypeScript extension restored (`./x.js` → `./x.ts`,
+ * NodeNext style), anything else is an external package or a node builtin.
+ */
+export function resolveContractImport(
+  specifier: string,
+  fromPath: string,
+): ContractImportResolution {
+  if (!specifier.startsWith("./") && !specifier.startsWith("../")) {
+    return { kind: "external", specifier };
+  }
+  const segments = fromPath.split("/").slice(0, -1);
+  for (const segment of specifier.split("/")) {
+    if (segment === "." || segment === "") continue;
+    if (segment === "..") {
+      segments.pop();
+      continue;
+    }
+    segments.push(segment);
+  }
+  const path = withSourceExtension(segments.join("/"));
+  return path.endsWith("/index.ts") || path === "index.ts"
+    ? { kind: "server-surface", path }
+    : { kind: "internal", path };
+}
+
+function withSourceExtension(path: string): string {
+  if (path.endsWith(".js")) return `${path.slice(0, -".js".length)}.ts`;
+  if (path.endsWith(".jsx")) return `${path.slice(0, -".jsx".length)}.tsx`;
+  if (path.endsWith(".ts") || path.endsWith(".tsx")) return path;
+  return `${path}.ts`;
+}

package/src/db.ts

@@ -0,0 +1,9 @@
+/**
+ * @intent Generic type of the product's Drizzle connection.
+ * The core does NOT pick the driver: node-postgres in production, PGlite in
+ * tests — both satisfy this type. Every DB-effectful function receives it
+ * by injection.
+ */
+import type { PgDatabase, PgQueryResultHKT } from "drizzle-orm/pg-core";
+
+export type Database = PgDatabase<PgQueryResultHKT>;

package/src/decision-refs.test.ts

@@ -0,0 +1,114 @@
+/**
+ * @intent Mutation tests of the decision-reference gate (DECISIONS.md D22:
+ * every gate is born with its negative test). The violation to catch is the
+ * one that really happened: a spec founding its rules on a decision that
+ * exists nowhere (D26, consigned in FAILURES.md). A valid citation must stay
+ * silent, an orphan one must be detected — otherwise the gate is decoration.
+ */
+import { describe, expect, it } from "vitest";
+import {
+  findDecisionReferences,
+  findDuplicateDecisionIds,
+  findUnknownDecisionReferences,
+  parseKnownDecisionIds,
+} from "./decision-refs.js";
+
+const DECISIONS = [
+  "# DECISIONS.md",
+  "",
+  "## D11 — 2026-07-30 — Anglais maximal dans le code",
+  "- **Décision** : les identifiants sont en anglais (voir aussi D99, jamais prise).",
+  "",
+  "## D26 — 2026-08 — Nomenclature partagée : codes normalisés",
+  "- **Décision** : le catalogue global s'appuie sur des codes normalisés.",
+].join("\n");
+
+describe("décisions réellement présentes dans DECISIONS.md", () => {
+  it("ne retient que les décisions DÉCLARÉES par leur titre, pas celles citées dans un corps", () => {
+    // D99 appears inside D11's body: a cross-reference declares nothing.
+    expect(parseKnownDecisionIds(DECISIONS)).toEqual(["D11", "D26"]);
+  });
+});
+
+describe("numérotation globale sur plusieurs fichiers de décisions (scission Phase 3)", () => {
+  it("deux fichiers aux numéros disjoints ne remontent aucun doublon", () => {
+    expect(findDuplicateDecisionIds([["D11", "D26"], ["D1", "D2"]])).toEqual([]);
+  });
+
+  it("MUTATION — un même D<n> déclaré dans les DEUX fichiers est DÉTECTÉ (citation ambiguë)", () => {
+    expect(findDuplicateDecisionIds([["D11", "D26"], ["D26", "D30"]])).toEqual(["D26"]);
+  });
+
+  it("MUTATION — un titre répété DANS un même fichier est aussi un doublon", () => {
+    expect(findDuplicateDecisionIds([["D11", "D11"]])).toEqual(["D11"]);
+  });
+});
+
+describe("citations de décisions dans un texte", () => {
+  it("reconnaît une citation collée à la ponctuation, au gras ou à un tiret", () => {
+    const text = 'refs: ["DECISIONS.md D26"]\nRègle **D11** (D13/D15), lot D24-D28.';
+
+    expect(findDecisionReferences(text)).toEqual([
+      { decision: "D26", line: 1 },
+      { decision: "D11", line: 2 },
+      { decision: "D13", line: 2 },
+      { decision: "D15", line: 2 },
+      { decision: "D24", line: 2 },
+      { decision: "D28", line: 2 },
+    ]);
+  });
+
+  it("ne prend pas un fragment de mot ou de nombre pour une décision", () => {
+    expect(findDecisionReferences("3D2 UUIDv4 D26bis ADR12")).toEqual([]);
+  });
+});
+
+describe("gate SPEC_UNKNOWN_DECISION_REFERENCE", () => {
+  const known = parseKnownDecisionIds(DECISIONS);
+
+  it("laisse passer une spec dont toutes les décisions citées existent", () => {
+    const spec = [
+      "---",
+      "id: nomenclature-codes",
+      'refs: ["DECISIONS.md D26 D11"]',
+      "---",
+      "# @intent",
+      "Nomenclature normalisée (D26), identifiants en anglais (D11).",
+    ].join("\n");
+
+    expect(findUnknownDecisionReferences(spec, known)).toEqual([]);
+  });
+
+  it("MUTATION — une référence orpheline dans le CORPS d'une spec est détectée", () => {
+    const spec = "# @intent\nLe mapping suit la nomenclature actée en D42.";
+
+    expect(findUnknownDecisionReferences(spec, known)).toEqual([
+      { decision: "D42", line: 2 },
+    ]);
+  });
+
+  it("MUTATION — une référence orpheline dans le FRONTMATTER refs est détectée", () => {
+    const spec = ['---', 'refs: ["DECISIONS.md D26", "DECISIONS.md D42"]', '---'].join("\n");
+
+    expect(findUnknownDecisionReferences(spec, known)).toEqual([
+      { decision: "D42", line: 2 },
+    ]);
+  });
+
+  it("MUTATION — une décision citée par AGENTS.md mais jamais actée est détectée", () => {
+    const agents = "## Règles git\n- Une session = un worktree (D25).";
+
+    expect(findUnknownDecisionReferences(agents, known)).toEqual([
+      { decision: "D25", line: 2 },
+    ]);
+  });
+
+  it("signale chaque décision orpheline UNE fois, à sa première citation", () => {
+    const spec = "D42 ici,\npuis D42 encore,\net D43 ailleurs.";
+
+    expect(findUnknownDecisionReferences(spec, known)).toEqual([
+      { decision: "D42", line: 1 },
+      { decision: "D43", line: 3 },
+    ]);
+  });
+});

package/src/decision-refs.ts

@@ -0,0 +1,103 @@
+/**
+ * @intent Testable heart of the gate that guards DECISION REFERENCES
+ * (DECISIONS.md).
+ * A spec, or AGENTS.md, may found a rule on a decision `D<n>`; that decision
+ * must REALLY exist in a decisions file. A product spec once grounded six
+ * passages on D26 while D26 lived in no committed file: the agent followed the
+ * prose correctly, and the repo documented a decision nobody had taken. A
+ * phantom reference is silent documentary drift — exactly what Ogygie claims to
+ * eliminate — so it breaks the build instead.
+ *
+ * These functions are pure (source text in, findings out) so the negative tests
+ * required by DECISIONS.md D22 can feed them known violations directly;
+ * scripts/verify-specs.ts only reports what they return.
+ */
+
+/**
+ * Reference boundary: a decision id is never a fragment of a word or of a
+ * number (`3D2`, `UUIDv4`), but IS a citation when glued to punctuation,
+ * markdown emphasis or a hyphen — `(D24)`, `**D11**`, `D13/D15`, `D24-D28`.
+ */
+const DECISION_REFERENCE = /(?<![A-Za-z0-9])D(\d+)(?![A-Za-z0-9])/g;
+
+/** A decision is DECLARED by its own heading in DECISIONS.md: `## D<n> — ...`. */
+const DECISION_HEADING = /^##\s+D(\d+)\b/;
+
+/** One citation of a decision, located for the human who has to fix it. */
+export interface DecisionReference {
+  /** Cited decision, e.g. "D26". */
+  decision: string;
+  /** 1-based line of the citation in the scanned file. */
+  line: number;
+}
+
+/**
+ * Ids of the decisions REALLY present in DECISIONS.md, in file order.
+ * Only headings count: a decision mentioned in the body of another one is a
+ * cross-reference, not a declaration.
+ */
+export function parseKnownDecisionIds(decisionsMarkdown: string): string[] {
+  const ids: string[] = [];
+  for (const line of decisionsMarkdown.split("\n")) {
+    const heading = DECISION_HEADING.exec(line);
+    if (heading !== null) ids.push(`D${heading[1]}`);
+  }
+  return ids;
+}
+
+/**
+ * Decision ids declared in MORE than one decisions file (Phase 3 split:
+ * framework + product files share ONE global numbering). A duplicate id makes
+ * every citation ambiguous, so the gate refuses it instead of picking a side.
+ * Returns each duplicated id once, in first-encounter order.
+ */
+export function findDuplicateDecisionIds(
+  perFileIds: readonly (readonly string[])[],
+): string[] {
+  const seen = new Set<string>();
+  const duplicated: string[] = [];
+  for (const fileIds of perFileIds) {
+    // Within one file, a repeated heading is also a duplicate declaration.
+    for (const id of fileIds) {
+      if (seen.has(id)) {
+        if (!duplicated.includes(id)) duplicated.push(id);
+      } else {
+        seen.add(id);
+      }
+    }
+  }
+  return duplicated;
+}
+
+/** Every decision citation found in a text (frontmatter included), in order. */
+export function findDecisionReferences(text: string): DecisionReference[] {
+  const references: DecisionReference[] = [];
+  const lines = text.split("\n");
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index] ?? "";
+    for (const match of line.matchAll(DECISION_REFERENCE)) {
+      references.push({ decision: `D${match[1]}`, line: index + 1 });
+    }
+  }
+  return references;
+}
+
+/**
+ * Citations pointing at a decision absent from DECISIONS.md — one entry per
+ * distinct decision (the first citation locates it; listing the same orphan
+ * twenty times would bury the twenty-first file).
+ */
+export function findUnknownDecisionReferences(
+  text: string,
+  knownDecisionIds: readonly string[],
+): DecisionReference[] {
+  const known = new Set(knownDecisionIds);
+  const unknown: DecisionReference[] = [];
+  const alreadyReported = new Set<string>();
+  for (const reference of findDecisionReferences(text)) {
+    if (known.has(reference.decision) || alreadyReported.has(reference.decision)) continue;
+    alreadyReported.add(reference.decision);
+    unknown.push(reference);
+  }
+  return unknown;
+}

package/src/design-brief.test.ts

@@ -0,0 +1,221 @@
+/**
+ * @intent Proves the behaviors described in specs/ogygie-design-brief.spec.md.
+ * Each Given/When/Then block of the spec = one identically named test.
+ * Fixtures use the neutral "orders" domain of AGENTS.md — the core knows no
+ * product vocabulary, and neither do its tests.
+ */
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+import {
+  buildDesignBrief,
+  fieldDescriptorsOfJsonSchema,
+  renderDesignBriefMarkdown,
+  type DesignBriefSources,
+  type JsonSchemaNode,
+} from "./design-brief.js";
+
+const OrderSchema = z.object({
+  id: z.uuid(),
+  reference: z.string().min(1).max(120),
+  totalCents: z.number().int(),
+  widthMeters: z.number().optional(),
+  shippedAt: z.iso.datetime().nullable(),
+  status: z.enum(["draft", "sent"]),
+  mysteryBlob: z.string(),
+});
+
+const listOutputJsonSchema = z.toJSONSchema(
+  z.object({ orders: z.array(OrderSchema) }),
+) as JsonSchemaNode;
+const createInputJsonSchema = z.toJSONSchema(
+  z.object({
+    reference: z.string().min(1).max(120),
+    quantity: z.number().int().positive().max(1_000_000),
+  }),
+) as JsonSchemaNode;
+
+const SPEC_WITH_UI_STATES = `---
+id: orders
+status: validated
+depends_on: []
+priority: P1
+refs: []
+deferred: ["ORDER_EXPORT (export document) blockedBy:documents"]
+---
+
+# @intent
+Commandes d'exemple.
+
+# Comportements
+- ÉTANT DONNÉ un contexte
+  ALORS un résultat
+- Le tri par défaut reste non tranché (par date ou par référence ?).
+
+# Contrats de données
+- ListOrdersOutputSchema: { orders: [...] }
+
+# États UI
+- vide (aucune ligne)
+- chargement
+- nominal (liste)
+- erreur (bandeau OgygieError)
+
+# Non-objectifs
+Rien.
+
+# Budget
+- P95 API < 100 ms
+`;
+
+function sourcesFixture(overrides: Partial<DesignBriefSources> = {}): DesignBriefSources {
+  return {
+    featureName: "orders",
+    validFeatureNames: ["orders", "documents"],
+    visualTokensJson: '{\n  "color": { "surface": "#ffffff" }\n}\n',
+    patternsCatalogDoc: "# Catalogue\n\n## DataTable\n\nTableau avec tri.\n\n## EmptyState\n\nÉtat vide.\n",
+    patternModules: [{ name: "DataTable", intent: "Sortable data table." }],
+    routes: [
+      {
+        method: "GET",
+        path: "/api/orders",
+        description: "Liste les commandes.",
+        inputSchemaName: "ListOrdersInputSchema",
+        outputSchemaName: "ListOrdersOutputSchema",
+        inputJsonSchema: z.toJSONSchema(z.object({})) as JsonSchemaNode,
+        outputJsonSchema: listOutputJsonSchema,
+      },
+      {
+        method: "POST",
+        path: "/api/orders",
+        description: "Crée une commande.",
+        inputSchemaName: "CreateOrderInputSchema",
+        outputSchemaName: "CreateOrderOutputSchema",
+        inputJsonSchema: createInputJsonSchema,
+        outputJsonSchema: z.toJSONSchema(z.object({ order: OrderSchema })) as JsonSchemaNode,
+      },
+    ],
+    specContent: SPEC_WITH_UI_STATES,
+    featureSources: [
+      {
+        file: "src/features/orders/service.ts",
+        content: 'throwOgygieError({ code: "ORDER_REFERENCE_ALREADY_USED", message: "…" }, 409);',
+      },
+    ],
+    fixtureCounts: [{ table: "orders", count: 42 }],
+    ...overrides,
+  };
+}
+
+const ALL_SECTIONS_IN_ORDER = [
+  "## Langage visuel",
+  "## Vocabulaire de composition",
+  "## Données à afficher",
+  "## Données à saisir",
+  "## Actions",
+  "## États obligatoires",
+  "## Volumétries réelles",
+  "## Contraintes non négociables",
+  "## Questions ouvertes",
+];
+
+describe("ogygie-design-brief", () => {
+  it("ÉTANT DONNÉ une feature connue ALORS un document Markdown autoporteur contient toutes les sections, sans aucune section vide non signalée", () => {
+    const result = buildDesignBrief(sourcesFixture());
+    expect(result.failure).toBeNull();
+    if (result.brief === null) throw new Error("brief attendu");
+    const markdown = renderDesignBriefMarkdown(result.brief);
+
+    let cursor = -1;
+    for (const section of ALL_SECTIONS_IN_ORDER) {
+      const position = markdown.indexOf(section);
+      expect(position, `section absente : ${section}`).toBeGreaterThan(cursor);
+      cursor = position;
+    }
+    // Every derived datum is there — the exact value, not a sentence around it.
+    expect(markdown).toContain('"surface": "#ffffff"');
+    expect(markdown).toContain("**DataTable** — Sortable data table.");
+    expect(markdown).toContain("**EmptyState** — État vide.");
+    expect(markdown).toContain("`ListOrdersOutputSchema` — GET /api/orders");
+    expect(markdown).toContain("| `orders[].reference` | string | oui | longueur 1..120 | unknown |");
+    expect(markdown).toContain("mutation : un bouton ou une commande à placer");
+    expect(markdown).toContain("- `ORDER_REFERENCE_ALREADY_USED`");
+    expect(markdown).toContain("- `orders` : 42 ligne(s) de fixtures");
+    expect(markdown).toContain("- vide (aucune ligne)");
+    expect(markdown).toContain("Le tri par défaut reste non tranché (par date ou par référence ?).");
+    expect(markdown).toContain("deferred — ORDER_EXPORT (export document) blockedBy:documents");
+    // Nothing was silently emptied: the full fixture triggers no signal marker.
+    expect(markdown).not.toContain("Section vide");
+    expect(result.brief.warnings).toEqual([]);
+
+    // An emptied source is SIGNALED in its section, never silent.
+    const bare = buildDesignBrief(
+      sourcesFixture({ visualTokensJson: null, patternsCatalogDoc: null, patternModules: [] }),
+    );
+    if (bare.brief === null) throw new Error("brief attendu");
+    const bareMarkdown = renderDesignBriefMarkdown(bare.brief);
+    expect(bareMarkdown).toContain(
+      "_Section vide — signalée, jamais devinée : design/tokens.json introuvable._",
+    );
+    expect(bareMarkdown).toContain(
+      "_Section vide — signalée, jamais devinée : ni design/patterns.md, ni dossier patterns/ d'une app front._",
+    );
+  });
+
+  it("ÉTANT DONNÉ une feature dont la spec n'a pas de section « États UI » ALORS le brief est produit MAIS porte DESIGN_BRIEF_MISSING_UI_STATES en tête", () => {
+    const result = buildDesignBrief(
+      sourcesFixture({ specContent: SPEC_WITH_UI_STATES.replace(/# États UI[\s\S]*?# Non-objectifs/, "# Non-objectifs") }),
+    );
+    expect(result.failure).toBeNull();
+    if (result.brief === null) throw new Error("brief attendu");
+    expect(result.brief.warnings[0]).toMatch(/^DESIGN_BRIEF_MISSING_UI_STATES/);
+
+    const markdown = renderDesignBriefMarkdown(result.brief);
+    const warningPosition = markdown.indexOf("DESIGN_BRIEF_MISSING_UI_STATES");
+    expect(warningPosition).toBeGreaterThan(-1);
+    // "en tête" : before the first content section of the document.
+    expect(warningPosition).toBeLessThan(markdown.indexOf("## Langage visuel"));
+  });
+
+  it("ÉTANT DONNÉ une feature inconnue du manifeste ALORS OgygieError DESIGN_BRIEF_UNKNOWN_FEATURE avec la liste des features", () => {
+    const result = buildDesignBrief(sourcesFixture({ featureName: "inconnue" }));
+    expect(result.brief).toBeNull();
+    if (result.failure === null) throw new Error("failure attendue");
+    expect(result.failure.code).toBe("DESIGN_BRIEF_UNKNOWN_FEATURE");
+    expect(result.failure.message).toContain("orders, documents");
+  });
+
+  it("ÉTANT DONNÉ un champ dont le nom ne suit aucune convention ALORS il est listé avec format: unknown — et les conventions connues sont appliquées", () => {
+    const fields = fieldDescriptorsOfJsonSchema(listOutputJsonSchema);
+    const byName = new Map(fields.map((field) => [field.name, field]));
+
+    expect(byName.get("orders[].mysteryBlob")?.format).toBe("unknown");
+    expect(byName.get("orders[].totalCents")?.format).toBe("currency-amount");
+    expect(byName.get("orders[].widthMeters")?.format).toBe("measure");
+    expect(byName.get("orders[].widthMeters")?.required).toBe(false);
+    expect(byName.get("orders[].shippedAt")?.format).toBe("local-date");
+    expect(byName.get("orders[].shippedAt")?.type).toBe("string(date-time) | null");
+    expect(byName.get("orders[].status")?.format).toBe("translated-enum-label");
+    expect(byName.get("orders[].status")?.type).toBe("enum(draft ; sent)");
+    expect(byName.get("orders[].id")?.type).toBe("string(uuid)");
+  });
+
+  it("ÉTANT DONNÉ des fixtures absentes ALORS les volumétries sont marquées « non mesurées » plutôt qu'omises", () => {
+    const result = buildDesignBrief(
+      sourcesFixture({ fixtureCounts: [{ table: "orders", count: null }] }),
+    );
+    if (result.brief === null) throw new Error("brief attendu");
+    const markdown = renderDesignBriefMarkdown(result.brief);
+    expect(markdown).toContain(
+      "- `orders` : non mesurée (aucune fixture trouvée dans test-fixtures/)",
+    );
+  });
+
+  it("ÉTANT DONNÉ deux exécutions successives sur une source inchangée ALORS le document produit est identique octet pour octet", () => {
+    const first = buildDesignBrief(sourcesFixture());
+    const second = buildDesignBrief(sourcesFixture());
+    if (first.brief === null || second.brief === null) throw new Error("briefs attendus");
+    expect(renderDesignBriefMarkdown(first.brief)).toBe(
+      renderDesignBriefMarkdown(second.brief),
+    );
+  });
+});