@ogygie/cli 0.1.0 → 0.3.0

package/README.md

@@ -1,7 +1,7 @@
 # @ogygie/cli
 
-CLI du framework Ogygie (spec `ogygie-standalone-repo`). Trois commandes,
-toutes déterministes :
+CLI du framework Ogygie (specs `ogygie-standalone-repo` et
+`product-vocabulary-gate`). Quatre commandes, toutes déterministes :
 
 - `ogygie init <nom-produit>` — scaffolde un projet Ogygie dans le répertoire
   courant (vide) depuis `templates/project/`, injecte le nom du produit et
@@ -12,6 +12,10 @@ toutes déterministes :
   ou si le CLI est plus ancien que le projet.
 - `ogygie check` — gate CI : versions en lockstep (manifeste = @ogygie/cli =
   @ogygie/core, D2) et checksums des fichiers gouvernés.
+- `ogygie verify-vocabulary` — gate CI du vocabulaire déclaré au manifeste
+  (bloc `vocabulary`) : aucun alias interdit dans les identifiants du code
+  produit, aucun mot du produit dans un fichier gouverné (D6). Silencieux tant
+  qu'aucun vocabulaire n'est déclaré.
 
 `--json` sur toute commande sort les erreurs au format OgygieError brut.
 

package/dist/cli.js

@@ -14644,6 +14644,16 @@ var FrameworkManifestSchema = external_exports.object({
   }),
   governedFiles: external_exports.string().describe("Module declaring the exhaustive list of files `upgrade` may overwrite (D3)")
 });
+var VocabularyEntrySchema = external_exports.object({
+  canonical: external_exports.string().regex(/^[a-z][a-zA-Z0-9]*$/, "camelCase English term required").describe("The one machine term for this concept, e.g. gadget"),
+  forbiddenAliases: external_exports.array(
+    external_exports.string().min(2).regex(/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/, "lowercase root (kebab-case allowed) required")
+  ).min(1).describe("Roots the code may never carry for this concept, e.g. widget"),
+  reference: external_exports.string().optional().describe("Anchor into AGENTS.product.md where the concept is explained")
+});
+var ProductVocabularySchema = external_exports.object({
+  entries: external_exports.array(VocabularyEntrySchema)
+});
 var OgygieManifestSchema = external_exports.object({
   version: external_exports.literal(1),
   product: external_exports.object({
@@ -14661,12 +14671,54 @@ var OgygieManifestSchema = external_exports.object({
     })
   ),
   features: external_exports.array(FeatureManifestSchema),
+  vocabulary: ProductVocabularySchema.optional().describe(
+    "The product's closed vocabulary \u2014 declared here, enforced by `ogygie verify-vocabulary`. Absent = gate silent"
+  ),
   conventions: external_exports.object({
     agentsMd: external_exports.literal("AGENTS.md"),
     failuresMd: external_exports.literal("FAILURES.md"),
     specsFolder: external_exports.literal("specs/")
   })
 }).superRefine((manifest, context) => {
+  const canonicalOwners = /* @__PURE__ */ new Map();
+  const aliasOwners = /* @__PURE__ */ new Map();
+  (manifest.vocabulary?.entries ?? []).forEach((entry, index) => {
+    const canonicalRoot = entry.canonical.toLowerCase();
+    const firstOwner = canonicalOwners.get(canonicalRoot);
+    if (firstOwner !== void 0) {
+      context.addIssue({
+        code: "custom",
+        path: ["vocabulary", "entries", index, "canonical"],
+        message: `canonical "${entry.canonical}" is already declared by entry ${firstOwner}`
+      });
+    } else {
+      canonicalOwners.set(canonicalRoot, index);
+    }
+  });
+  (manifest.vocabulary?.entries ?? []).forEach((entry, index) => {
+    entry.forbiddenAliases.forEach((alias, aliasIndex) => {
+      const path = ["vocabulary", "entries", index, "forbiddenAliases", aliasIndex];
+      const canonicalOwner = canonicalOwners.get(alias);
+      if (canonicalOwner !== void 0) {
+        context.addIssue({
+          code: "custom",
+          path,
+          message: `alias "${alias}" is the canonical term of entry ${canonicalOwner} \u2014 a term cannot be both`
+        });
+        return;
+      }
+      const firstOwner = aliasOwners.get(alias);
+      if (firstOwner !== void 0) {
+        context.addIssue({
+          code: "custom",
+          path,
+          message: `alias "${alias}" is already forbidden by entry ${firstOwner} \u2014 one alias belongs to one concept`
+        });
+        return;
+      }
+      aliasOwners.set(alias, index);
+    });
+  });
   const appsByName = new Map(manifest.apps.map((app) => [app.name, app]));
   const knownInvalidationTargets = new Set(
     manifest.features.map((feature) => feature.name)
@@ -14939,6 +14991,19 @@ function diffLines(oldText, newText) {
   return output.join("\n");
 }
 
+// src/framework-gates.ts
+var frameworkGates = [
+  {
+    scriptName: "ogygie:verify-vocabulary",
+    command: "ogygie verify-vocabulary",
+    intent: "Le vocabulaire d\xE9clar\xE9 au manifeste : alias interdits dans les identifiants, puret\xE9 des fichiers gouvern\xE9s."
+  }
+];
+function missingFrameworkGates(scripts) {
+  const commands = Object.values(scripts ?? {}).join(" ; ");
+  return frameworkGates.filter((gate) => !commands.includes(gate.command));
+}
+
 // src/version.ts
 function compareVersions(a, b) {
   const partsA = a.split(".").map(Number);
@@ -14953,6 +15018,30 @@ function compareVersions(a, b) {
 }
 
 // src/commands/upgrade.ts
+function reportMissingGates(deps) {
+  const packageJsonPath = join4(deps.projectRoot, "package.json");
+  if (!existsSync4(packageJsonPath)) return;
+  let scripts;
+  try {
+    const parsed = JSON.parse(readFileSync4(packageJsonPath, "utf8"));
+    const scriptsValue = typeof parsed === "object" && parsed !== null ? parsed.scripts : void 0;
+    if (typeof scriptsValue === "object" && scriptsValue !== null) {
+      scripts = scriptsValue;
+    }
+  } catch {
+    return;
+  }
+  const missing = missingFrameworkGates(scripts);
+  if (missing.length === 0) return;
+  deps.log("");
+  deps.log(
+    `\u26A0 ${missing.length} gate(s) du framework ne tournent pas dans ta boucle locale (package.json n'est pas gouvern\xE9 \u2014 \xE0 toi de l'ajouter, la CI gouvern\xE9e les appelle d\xE9j\xE0) :`
+  );
+  for (const gate of missing) {
+    deps.log(`    "${gate.scriptName}": "${gate.command}"   # ${gate.intent}`);
+  }
+  deps.log("  puis appelle ces scripts depuis ton script `verify`.");
+}
 async function upgradeProject(deps) {
   const installedVersion = readPinnedOgygieVersion(deps.projectRoot);
   if (compareVersions(deps.cliVersion, installedVersion) < 0) {
@@ -14961,7 +15050,7 @@ async function upgradeProject(deps) {
       message: `The running CLI (${deps.cliVersion}) is older than the project's ogygieVersion (${installedVersion}) \u2014 a downgrade does not exist.`,
       file: "ogygie.manifest.json",
       cause: `cli ${deps.cliVersion} < ogygieVersion ${installedVersion}`,
-      suggestedFix: "Run `pnpm update @ogygie/cli` first, then retry the upgrade."
+      suggestedFix: `Install a CLI at least as recent as the project, WITH an explicit version (init pins exact ranges, so a bare \`pnpm update\` moves nothing): pnpm update @ogygie/core@${installedVersion} @ogygie/cli@${installedVersion} \u2014 then retry the upgrade.`
     });
   }
   if (compareVersions(deps.cliVersion, installedVersion) === 0) {
@@ -15037,6 +15126,7 @@ ${diff}`);
   deps.log(
     `Rappel lockstep (D2) : mettre @ogygie/core ET @ogygie/cli \xE0 ${deps.cliVersion} (\`pnpm update @ogygie/core@${deps.cliVersion} @ogygie/cli@${deps.cliVersion}\`), puis committer l'upgrade SEUL \u2014 jamais m\xEAl\xE9 \xE0 une feature.`
   );
+  reportMissingGates(deps);
   return {
     fromVersion: installedVersion,
     toVersion: deps.cliVersion,
@@ -15044,6 +15134,186 @@ ${diff}`);
   };
 }
 
+// src/commands/verify-vocabulary.ts
+import { existsSync as existsSync5, readFileSync as readFileSync5, readdirSync as readdirSync2, statSync as statSync2 } from "node:fs";
+import { join as join5, relative, sep } from "node:path";
+
+// ../ogygie-core/src/vocabulary.ts
+var TOKEN_PATTERN = new RegExp("\\p{L}[\\p{L}\\p{N}]*(?:[-_$][\\p{L}\\p{N}]+)*", "gu");
+function segmentsOfIdentifier(token) {
+  return token.split(/[-_$]+/).flatMap(
+    (part) => part.replace(new RegExp("(?<=\\p{Ll}|\\p{N})(?=\\p{Lu})", "gu"), " ").replace(new RegExp("(?<=\\p{Lu})(?=\\p{Lu}\\p{Ll})", "gu"), " ").split(" ")
+  ).filter((segment) => segment.length > 0).map((segment) => segment.toLowerCase());
+}
+function tokenCarriesRoot(tokenSegments, rootSegments) {
+  const lastIndex = rootSegments.length - 1;
+  for (let start = 0; start + rootSegments.length <= tokenSegments.length; start += 1) {
+    let leadingSegmentsMatch = true;
+    for (let offset = 0; offset < lastIndex; offset += 1) {
+      if (tokenSegments[start + offset] !== rootSegments[offset]) {
+        leadingSegmentsMatch = false;
+        break;
+      }
+    }
+    const lastTokenSegment = tokenSegments[start + lastIndex];
+    if (leadingSegmentsMatch && lastTokenSegment !== void 0 && lastTokenSegment.startsWith(rootSegments[lastIndex] ?? "")) {
+      return true;
+    }
+  }
+  return false;
+}
+function findProductVocabulary(sourceText, vocabularyRoots) {
+  const roots = vocabularyRoots.map((root) => ({
+    root,
+    segments: segmentsOfIdentifier(root)
+  }));
+  const matches = [];
+  const alreadyReported = /* @__PURE__ */ new Set();
+  sourceText.split("\n").forEach((lineText, lineIndex) => {
+    for (const token of lineText.match(TOKEN_PATTERN) ?? []) {
+      const tokenSegments = segmentsOfIdentifier(token);
+      for (const { root, segments } of roots) {
+        if (segments.length === 0) continue;
+        if (!tokenCarriesRoot(tokenSegments, segments)) continue;
+        const reportKey = `${root} ${token}`;
+        if (alreadyReported.has(reportKey)) continue;
+        alreadyReported.add(reportKey);
+        matches.push({ root, identifier: token, line: lineIndex + 1 });
+      }
+    }
+  });
+  return matches;
+}
+function stripComments(sourceText) {
+  const blankKeepingNewlines = (text) => text.replace(/[^\n]/g, " ");
+  return sourceText.replace(/\/\*[\s\S]*?\*\//g, blankKeepingNewlines).replace(/\/\/[^\n]*/g, blankKeepingNewlines);
+}
+
+// ../ogygie-core/src/vocabulary-audit.ts
+function canonicalByAlias(vocabulary) {
+  const byAlias = /* @__PURE__ */ new Map();
+  for (const entry of vocabulary.entries) {
+    for (const alias of entry.forbiddenAliases) byAlias.set(alias, entry.canonical);
+  }
+  return byAlias;
+}
+function auditProductVocabulary(input) {
+  const { vocabulary } = input;
+  if (vocabulary === void 0 || vocabulary.entries.length === 0) return [];
+  const canonicalOfAlias = canonicalByAlias(vocabulary);
+  const forbiddenAliases = [...canonicalOfAlias.keys()];
+  const canonicalTerms = vocabulary.entries.map((entry) => entry.canonical);
+  const violations = [];
+  for (const file2 of input.sourceFiles) {
+    for (const match of findProductVocabulary(stripComments(file2.content), forbiddenAliases)) {
+      violations.push({
+        kind: "FORBIDDEN_ALIAS",
+        filePath: file2.path,
+        match,
+        canonical: canonicalOfAlias.get(match.root) ?? null
+      });
+    }
+  }
+  for (const file2 of input.governedFiles) {
+    for (const match of findProductVocabulary(file2.content, canonicalTerms)) {
+      violations.push({
+        kind: "GOVERNED_FILE",
+        filePath: file2.path,
+        match,
+        canonical: null
+      });
+    }
+  }
+  return violations;
+}
+
+// src/commands/verify-vocabulary.ts
+var CODE_EXTENSIONS = [".ts", ".tsx", ".mts", ".mjs", ".js", ".jsx"];
+var IGNORED_DIRS = /* @__PURE__ */ new Set(["node_modules", "dist", "build", ".git", "coverage"]);
+function readManifest(projectRoot) {
+  const manifestPath = join5(projectRoot, MANIFEST_FILE_NAME);
+  if (!existsSync5(manifestPath)) {
+    throwOgygieError({
+      code: "OGYGIE_CLI_USAGE",
+      message: `No ${MANIFEST_FILE_NAME} here \u2014 this is not an Ogygie project root.`,
+      file: MANIFEST_FILE_NAME,
+      cause: `${manifestPath} does not exist`,
+      suggestedFix: "Run the command from the project root."
+    });
+  }
+  const parsed = OgygieManifestSchema.safeParse(
+    JSON.parse(readFileSync5(manifestPath, "utf8"))
+  );
+  if (!parsed.success) {
+    throwOgygieError({
+      code: "MANIFEST_INVALID",
+      message: `${MANIFEST_FILE_NAME} does not satisfy OgygieManifestSchema \u2014 the vocabulary cannot be read from it.`,
+      file: MANIFEST_FILE_NAME,
+      cause: parsed.error.issues.map((issue2) => `${issue2.path.join(".")}: ${issue2.message}`).join(" ; "),
+      suggestedFix: "Fix the listed fields, then run the gate again."
+    });
+  }
+  return parsed.data;
+}
+function collectCodeFiles(projectRoot, folder) {
+  const absoluteFolder = join5(projectRoot, folder);
+  if (!existsSync5(absoluteFolder)) return [];
+  const files = [];
+  const walk = (directory) => {
+    for (const entry of readdirSync2(directory)) {
+      if (IGNORED_DIRS.has(entry)) continue;
+      const entryPath = join5(directory, entry);
+      if (statSync2(entryPath).isDirectory()) {
+        walk(entryPath);
+        continue;
+      }
+      if (!CODE_EXTENSIONS.some((extension) => entry.endsWith(extension))) continue;
+      files.push({
+        path: relative(projectRoot, entryPath).split(sep).join("/"),
+        content: readFileSync5(entryPath, "utf8")
+      });
+    }
+  };
+  walk(absoluteFolder);
+  return files;
+}
+function productCodeFoldersOf(manifest) {
+  return [
+    ...manifest.apps.map((app) => app.path),
+    ...(manifest.framework?.packages ?? []).map((packageEntry) => packageEntry.path)
+  ];
+}
+function verifyVocabulary(deps) {
+  const manifest = readManifest(deps.projectRoot);
+  if (manifest.vocabulary === void 0) return [];
+  const sourceFiles = productCodeFoldersOf(manifest).flatMap(
+    (folder) => collectCodeFiles(deps.projectRoot, folder)
+  );
+  const governed = governedFiles.filter((file2) => existsSync5(join5(deps.projectRoot, file2.targetPath))).map((file2) => ({
+    path: file2.targetPath,
+    content: readFileSync5(join5(deps.projectRoot, file2.targetPath), "utf8")
+  }));
+  return auditProductVocabulary({
+    vocabulary: manifest.vocabulary,
+    sourceFiles,
+    governedFiles: governed
+  }).map(
+    (violation) => violation.kind === "FORBIDDEN_ALIAS" ? ogygieError({
+      code: "OGYGIE_VOCABULARY_FORBIDDEN_ALIAS",
+      message: `${violation.filePath}:${violation.match.line} uses "${violation.match.identifier}", built on the forbidden alias "${violation.match.root}".`,
+      file: violation.filePath,
+      cause: `identifier ${violation.match.identifier} carries the root "${violation.match.root}" declared forbidden in ${MANIFEST_FILE_NAME}`,
+      suggestedFix: `Rename it around the canonical term: use "${violation.canonical ?? ""}" instead of "${violation.match.root}".`
+    }) : ogygieError({
+      code: "OGYGIE_VOCABULARY_IN_GOVERNED_FILE",
+      message: `Governed file ${violation.filePath}:${violation.match.line} names the product term "${violation.match.identifier}".`,
+      file: violation.filePath,
+      cause: `a governed file is identical in every Ogygie project, so it may name no product domain \u2014 found the declared root "${violation.match.root}"`,
+      suggestedFix: "Move the product-specific part to AGENTS.product.md (or to the product's own files), and restore the governed file to its pristine content."
+    })
+  );
+}
+
 // src/governed-checksums.ts
 var governedChecksumsByVersion = {
   "0.1.0": {
@@ -15051,24 +15321,39 @@ var governedChecksumsByVersion = {
     "AGENTS.md": "de700f99aaf949b1d85c6ae6d199897736084f4c19adf132cdf5a3568af59f69",
     "CLAUDE.md": "785ee8d90e368806d8cf0b4d84a15f29d1dc961168bda86cf1a6c60a923c8c9b",
     "tsconfig.base.json": "0f8919e9ed8bbc88e0308fa2fa91471dabb18d1df721bd78c04076597eba89a2"
+  },
+  "0.2.0": {
+    ".github/workflows/ogygie-gates.yml": "48c40efe9fe66dd0f9c3b94287026d80eae9afd6782b5833fdf8846d8662babf",
+    "AGENTS.md": "ca73ab619d8c55fac11858d815bf5fbab6537ecebe7ae4123cbdeb3e3e36bf1a",
+    "CLAUDE.md": "785ee8d90e368806d8cf0b4d84a15f29d1dc961168bda86cf1a6c60a923c8c9b",
+    "tsconfig.base.json": "0f8919e9ed8bbc88e0308fa2fa91471dabb18d1df721bd78c04076597eba89a2"
+  },
+  "0.3.0": {
+    ".github/workflows/ogygie-gates.yml": "48c40efe9fe66dd0f9c3b94287026d80eae9afd6782b5833fdf8846d8662babf",
+    "AGENTS.md": "ca73ab619d8c55fac11858d815bf5fbab6537ecebe7ae4123cbdeb3e3e36bf1a",
+    "CLAUDE.md": "785ee8d90e368806d8cf0b4d84a15f29d1dc961168bda86cf1a6c60a923c8c9b",
+    "tsconfig.base.json": "0f8919e9ed8bbc88e0308fa2fa91471dabb18d1df721bd78c04076597eba89a2"
   }
 };
 
 // src/paths.ts
-import { existsSync as existsSync5, readFileSync as readFileSync5 } from "node:fs";
-import { dirname as dirname3, join as join5 } from "node:path";
+import { existsSync as existsSync6, readFileSync as readFileSync6 } from "node:fs";
+import { dirname as dirname3, join as join6 } from "node:path";
 import { fileURLToPath } from "node:url";
-var PACKAGE_ROOT = join5(dirname3(fileURLToPath(import.meta.url)), "..");
+var PACKAGE_ROOT = join6(dirname3(fileURLToPath(import.meta.url)), "..");
 var PackageVersionSchema2 = external_exports.object({ version: external_exports.string() });
 function cliVersion() {
   return PackageVersionSchema2.parse(
-    JSON.parse(readFileSync5(join5(PACKAGE_ROOT, "package.json"), "utf8"))
+    JSON.parse(readFileSync6(join6(PACKAGE_ROOT, "package.json"), "utf8"))
   ).version;
 }
 function templatesDir() {
-  const embedded = join5(PACKAGE_ROOT, "templates");
-  if (existsSync5(embedded)) return embedded;
-  return join5(PACKAGE_ROOT, "..", "..", "templates");
+  const embedded = join6(PACKAGE_ROOT, "templates");
+  if (existsSync6(embedded)) return embedded;
+  return repoTemplatesDir();
+}
+function repoTemplatesDir() {
+  return join6(PACKAGE_ROOT, "..", "..", "templates");
 }
 
 // src/cli.ts
@@ -15133,14 +15418,23 @@ ogygie check \u2014 ${problems.length} probl\xE8me(s).`);
     console.log(
       `ogygie check \u2014 OK, lockstep ${cliVersion()} et fichiers gouvern\xE9s intacts.`
     );
+  } else if (command === "verify-vocabulary") {
+    const problems = verifyVocabulary({ projectRoot: process.cwd() });
+    if (problems.length > 0) {
+      for (const problem of problems) printError(problem);
+      console.error(`
+ogygie verify-vocabulary \u2014 ${problems.length} probl\xE8me(s).`);
+      process.exit(1);
+    }
+    console.log("ogygie verify-vocabulary \u2014 OK, le vocabulaire d\xE9clar\xE9 est respect\xE9.");
   } else {
     printError(
       ogygieError({
         code: "OGYGIE_CLI_USAGE",
         message: `Unknown command ${JSON.stringify(command ?? "")}.`,
         file: null,
-        cause: `expected one of: init <product-name>, upgrade, check (flags: --json, --yes)`,
-        suggestedFix: "Run `ogygie init <product-name>`, `ogygie upgrade` or `ogygie check`."
+        cause: `expected one of: init <product-name>, upgrade, check, verify-vocabulary (flags: --json, --yes)`,
+        suggestedFix: "Run `ogygie init <product-name>`, `ogygie upgrade`, `ogygie check` or `ogygie verify-vocabulary`."
       })
     );
     process.exit(1);

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@ogygie/cli",
-  "version": "0.1.0",
+  "version": "0.3.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"
+    "ogygie": "dist/cli.js"
   },
   "files": [
     "dist",
@@ -16,17 +16,17 @@
   "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"
+    "zod": "^4.0.0",
+    "@ogygie/core": "0.3.0"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json",
+    "build": "tsx scripts/build.ts",
+    "record-checksums": "tsx scripts/record-governed-checksums.ts"
   }
-}
+}

package/templates/project/AGENTS.md

@@ -240,6 +240,38 @@ throw ogygieError({
 6. **Identifiants code en anglais, contenu en langue de l'utilisateur.** Les enums du
    domaine sont en anglais ; leur affichage est traduit.
 
+## Vocabulaire du produit — un concept, un terme
+
+Le produit déclare son vocabulaire fermé dans le bloc `vocabulary` d'`ogygie.manifest.json` :
+pour chaque concept, LE terme canonique (identifiant machine, anglais) et les
+alias que le code n'a pas le droit de porter. La prose qui explique le métier
+reste dans `AGENTS.product.md` et cite les termes canoniques : le manifeste
+déclare, la prose explique, la partie machine n'existe qu'à un seul endroit.
+
+Le gate `pnpm exec ogygie verify-vocabulary` (posé dans la CI gouvernée)
+applique deux règles :
+
+- **Le code du produit ne porte aucun alias interdit** — l'appariement se fait
+  sur les identifiants machine (découpage camelCase / snake_case / kebab-case,
+  par racine), commentaires exclus. La prose du métier garde ses mots ; le code
+  n'a qu'un terme par concept. Erreur `OGYGIE_VOCABULARY_FORBIDDEN_ALIAS`, dont
+  la correction suggérée est le terme canonique.
+- **Aucun fichier gouverné ne nomme un terme du produit**, canonique compris :
+  un fichier gouverné est identique dans tous les projets Ogygie, il ne peut
+  donc connaître le domaine d'aucun. Erreur
+  `OGYGIE_VOCABULARY_IN_GOVERNED_FILE` — la spécificité locale se déplace vers
+  `AGENTS.product.md`, elle ne se négocie pas dans un fichier gouverné.
+
+Tant qu'aucun bloc `vocabulary` n'est déclaré, le gate passe sans rien dire :
+il devient actif le jour où le produit déclare, jamais avant. Renommer un
+concept est donc une opération à un seul endroit — on change le canonique, le
+gate liste tous les identifiants à corriger.
+
+Choisir les racines est un acte de conception, pas une formalité : l'appariement
+se fait PAR RACINE, donc une racine trop courte attrape des mots génériques
+(déclarer `memo` interdit fait tomber `memory`, `createInMemoryDb`…). Une racine
+se déclare assez longue pour ne nommer que le concept.
+
 ## Front (apps/web) — règles et templates canoniques
 
 ### Stack imposée (toute autre lib = amendement DECISIONS.md d'abord)

package/templates/project/AGENTS.product.md

@@ -42,6 +42,14 @@
   manifeste (`{ "name": "...", "shared": true }`) et s'ajoute ici avec sa
   source et son script d'extraction.
 
+## Vocabulaire du produit (§Vocabulaire)
+
+- À définir, concept par concept : chaque terme canonique et ses alias
+  interdits se déclarent dans le bloc `vocabulary` d'`ogygie.manifest.json`
+  (la partie machine), et sa définition métier se rédige ICI, sous une ancre
+  que l'entrée du manifeste référence. Tant que le bloc est absent, le gate
+  `ogygie verify-vocabulary` passe sans rien dire.
+
 ## Règles produit
 
 - (aucune pour l'instant — toute règle qui ne vaut que pour ce produit se

package/templates/project/ci/ogygie-gates.yml

@@ -29,6 +29,7 @@ jobs:
       - run: pnpm ogygie:verify-manifest   # manifest ↔ actual code (routes, folders, tables)
       - run: pnpm ogygie:verify-specs      # frontmatter + sections + spec lifecycle + decision refs
       - run: pnpm ogygie:verify-contracts  # transitive purity of every schemas.ts
+      - run: pnpm exec ogygie verify-vocabulary # declared vocabulary: forbidden aliases + governed-file purity
       - run: pnpm typecheck
       - run: pnpm lint                     # any, ts-ignore, raw-db, dangerouslySetInnerHTML
       - run: pnpm test

package/templates/project/package.json

@@ -13,9 +13,10 @@
     "ogygie:verify-manifest": "tsx scripts/verify-manifest.ts",
     "ogygie:verify-specs": "tsx scripts/verify-specs.ts",
     "ogygie:verify-contracts": "tsx scripts/verify-contracts.ts",
+    "ogygie:verify-vocabulary": "ogygie verify-vocabulary",
     "ogygie:impact": "tsx scripts/ogygie-impact.ts",
     "ogygie:design-brief": "tsx scripts/ogygie-design-brief.ts",
-    "verify": "pnpm ogygie:verify-manifest && pnpm ogygie:verify-specs && pnpm ogygie:verify-contracts && pnpm typecheck && pnpm lint && pnpm test"
+    "verify": "pnpm ogygie:verify-manifest && pnpm ogygie:verify-specs && pnpm ogygie:verify-contracts && pnpm ogygie:verify-vocabulary && pnpm typecheck && pnpm lint && pnpm test"
   },
   "dependencies": {
     "@ogygie/core": "__OGYGIE_VERSION__"

package/templates/project/scripts/ogygie-impact.ts

@@ -12,7 +12,7 @@
  *
  * Deliberate scope choices:
  * - Depth 1 only (direct dependents) — spec §Non-objectifs.
- * - The owned-tables scan ignores *.test.ts files: seeding ANOTHER feature's
+ * - The owned-tables scan ignores *.test.ts files: populating ANOTHER feature's
  *   table as a fixture is the canonical bench pattern ("the socle feature owns
  *   that model" — see any service.test.ts); flagging it would make every run
  *   red and the tool useless. Production code referencing a foreign table
@@ -289,7 +289,7 @@ if (featureArgument === undefined) {
     message: "No feature name given. Usage: pnpm ogygie:impact <feature> [--json].",
     file: null,
     cause: "process.argv carries no non-flag argument",
-    suggestedFix: "Pass a feature name from ogygie.manifest.json, e.g. `pnpm ogygie:impact cultures`.",
+    suggestedFix: "Pass a feature name from ogygie.manifest.json, e.g. `pnpm ogygie:impact orders`.",
   });
   console.error(JSON.stringify(failure, null, 2));
   process.exit(1);

package/templates/project/scripts/verify-contracts.ts

@@ -3,8 +3,8 @@
  * feature's `schemas.ts`, walk the WHOLE import graph and prove that nothing
  * with a runtime effect is reachable — the transitivity is the point, since
  * that is how the server came back into the browser bundle
- * (`cultures/schemas.ts` → `especes-eppo/index.ts` → `seed.ts` → `node:fs`,
- * FAILURES.md).
+ * (`orders/schemas.ts` → a sibling feature's `index.ts` → its data loader →
+ * `node:fs`, FAILURES.md).
  *
  * The decision logic lives in @ogygie/core/contract-purity, born with its
  * mutation tests (D22) — this script only reads the manifest, the disk, and

package/templates/project/specs/_TEMPLATE.spec.md

@@ -15,7 +15,7 @@ existe, pas comment elle est construite.
 
 # Comportements
 (prose en français ; codes d'erreur, noms de schémas et valeurs d'enum
-directement en anglais — D11/D14, ex. « ALORS OgygieError PLOT_CODE_ALREADY_USED »)
+directement en anglais — D11/D14, ex. « ALORS OgygieError ORDER_REFERENCE_ALREADY_USED »)
 - ÉTANT DONNÉ <contexte>
   QUAND <action>
   ALORS <résultat observable et vérifiable>