agentic-api 2.0.684 → 2.0.885

package/dist/src/rules/git/repo.js

@@ -41,6 +41,8 @@ exports.gitAllocateNextPRNumber = gitAllocateNextPRNumber;
 exports.gitReloadIDRegistry = gitReloadIDRegistry;
 exports.gitRegisterExistingID = gitRegisterExistingID;
 exports.gitIDRegistryRename = gitIDRegistryRename;
+exports.gitGetMatterCache = gitGetMatterCache;
+exports.gitSetMatterCache = gitSetMatterCache;
 exports.gitEnsureMatterID = gitEnsureMatterID;
 exports.gitFileStrictMatter = gitFileStrictMatter;
 exports.gitEnsureRepositoryConfiguration = gitEnsureRepositoryConfiguration;
@@ -51,8 +53,7 @@ exports.gitShowConfiguration = gitShowConfiguration;
 exports.gitCheckConfiguration = gitCheckConfiguration;
 exports.gitCreateOrEditFile = gitCreateOrEditFile;
 exports.gitEditFile = gitEditFile;
-exports.gitRenameFile_git = gitRenameFile_git;
-exports.gitRenameFile_fs = gitRenameFile_fs;
+exports.gitUpdateMatter = gitUpdateMatter;
 exports.gitRenameFile = gitRenameFile;
 exports.gitDeleteFile = gitDeleteFile;
 exports.gitGetBranchHealth = gitGetBranchHealth;
@@ -63,6 +64,8 @@ const path_1 = require("path");
 const fs = __importStar(require("fs/promises"));
 const repo_tools_1 = require("./repo.tools");
 const utils_matter_1 = require("../utils.matter");
+const utils_slug_1 = require("../utils.slug");
+const utils_1 = require("../../utils");
 /**
  * Service singleton pour gérer le registre d'IDs en mémoire
  */
@@ -83,6 +86,110 @@ class IDRegistryService {
         this.repoPath = '';
         this.isDirty = false;
     }
+    createEmptyRegistry() {
+        return {
+            schemaVersion: 2,
+            last: 980,
+            lastPR: 60,
+            used: [],
+            updated: new Date().toISOString(),
+            matters: {}
+        };
+    }
+    parseMatterKey(key) {
+        const separatorIndex = key.indexOf(':');
+        if (separatorIndex < 0) {
+            return null;
+        }
+        return {
+            branch: key.slice(0, separatorIndex),
+            suffix: key.slice(separatorIndex + 1)
+        };
+    }
+    createMatterKey(branch, id) {
+        return `${branch}:${id}`;
+    }
+    normalizeMatterCache(branch, keySuffix, rawMatter) {
+        if (!rawMatter || typeof rawMatter !== 'object') {
+            return null;
+        }
+        const id = typeof rawMatter.id === 'number' ? rawMatter.id : undefined;
+        if (!id || !Number.isFinite(id)) {
+            return null;
+        }
+        const file = typeof rawMatter.file === 'string' && rawMatter.file.trim() !== ''
+            ? rawMatter.file
+            : keySuffix;
+        const normalized = {
+            id,
+            file,
+            title: rawMatter.title,
+            service: rawMatter.service,
+            updated: typeof rawMatter.updated === 'string' ? rawMatter.updated : new Date().toISOString()
+        };
+        return {
+            cacheKey: this.createMatterKey(branch, id),
+            cacheValue: normalized
+        };
+    }
+    mergeMatterCache(existing, incoming) {
+        if (!existing) {
+            return incoming;
+        }
+        const existingUpdated = Date.parse(existing.updated || '');
+        const incomingUpdated = Date.parse(incoming.updated || '');
+        const preferIncoming = !Number.isNaN(incomingUpdated) && (Number.isNaN(existingUpdated) || incomingUpdated >= existingUpdated);
+        const primary = preferIncoming ? incoming : existing;
+        const secondary = preferIncoming ? existing : incoming;
+        return {
+            id: primary.id ?? secondary.id,
+            file: primary.file || secondary.file,
+            title: primary.title ?? secondary.title,
+            service: primary.service ?? secondary.service,
+            updated: primary.updated || secondary.updated
+        };
+    }
+    migrateRegistry(data) {
+        const fallback = this.createEmptyRegistry();
+        const migrated = {
+            schemaVersion: 2,
+            last: Number.isInteger(data?.last) ? data.last : fallback.last,
+            lastPR: Number.isInteger(data?.lastPR) ? data.lastPR : fallback.lastPR,
+            used: Array.isArray(data?.used) ? data.used.filter((value) => typeof value === 'number') : [],
+            updated: typeof data?.updated === 'string' ? data.updated : fallback.updated,
+            matters: {}
+        };
+        let migrationApplied = data?.schemaVersion !== 2;
+        const rawMatters = data?.matters && typeof data.matters === 'object' ? data.matters : {};
+        for (const [rawKey, rawMatter] of Object.entries(rawMatters)) {
+            const parsed = this.parseMatterKey(rawKey);
+            if (!parsed) {
+                migrationApplied = true;
+                continue;
+            }
+            const normalized = this.normalizeMatterCache(parsed.branch, parsed.suffix, rawMatter);
+            if (!normalized) {
+                migrationApplied = true;
+                continue;
+            }
+            if (normalized.cacheKey !== rawKey) {
+                migrationApplied = true;
+            }
+            migrated.matters[normalized.cacheKey] = this.mergeMatterCache(migrated.matters[normalized.cacheKey], normalized.cacheValue);
+        }
+        const used = new Set(migrated.used);
+        for (const matter of Object.values(migrated.matters)) {
+            if (typeof matter.id === 'number') {
+                used.add(matter.id);
+            }
+        }
+        migrated.used = Array.from(used).sort((left, right) => left - right);
+        migrated.last = Math.max(migrated.last, migrated.used.length ? migrated.used[migrated.used.length - 1] : fallback.last);
+        if (migrationApplied) {
+            this.isDirty = true;
+        }
+        return migrated;
+    }
     /**
      * Initialise le service avec le chemin du repository
      */
@@ -95,14 +202,12 @@ class IDRegistryService {
             // Si le registre existe déjà, le recharger depuis le nouveau chemin
             if (this.registry) {
                 this.registry = this.loadFromDisk();
-                this.isDirty = false;
                 return;
             }
         }
         // Si le registre n'existe pas encore, le créer
         if (!this.registry) {
             this.registry = this.loadFromDisk();
-            this.isDirty = false;
         }
     }
     /**
@@ -114,43 +219,24 @@ class IDRegistryService {
             throw new Error('IDRegistryService not initialized. Call init() first.');
         }
         this.registry = this.loadFromDisk();
-        this.isDirty = false;
     }
     /**
      * Charge le registre depuis le disque
      */
     loadFromDisk() {
         const registryPath = (0, path_1.join)(this.repoPath, '.git', 'with-ids.json');
+        this.isDirty = false;
         if (!(0, fs_1.existsSync)(registryPath)) {
-            return {
-                last: 980,
-                lastPR: 60,
-                used: [],
-                updated: new Date().toISOString(),
-                matters: {}
-            };
+            return this.createEmptyRegistry();
         }
         try {
             const data = JSON.parse((0, fs_1.readFileSync)(registryPath, 'utf8'));
-            // Migration : ajouter matters si absent (compatibilité anciens registres)
-            if (!data.matters) {
-                data.matters = {};
-            }
-            // Migration : compteur PR indépendant (valeur initiale explicite)
-            if (!Number.isInteger(data.lastPR)) {
-                data.lastPR = 60;
-            }
-            return data;
+            return this.migrateRegistry(data);
         }
         catch (error) {
             console.warn('⚠️ Registre d\'IDs corrompu, création d\'un nouveau');
-            return {
-                last: 980,
-                lastPR: 60,
-                used: [],
-                updated: new Date().toISOString(),
-                matters: {}
-            };
+            this.isDirty = false;
+            return this.createEmptyRegistry();
         }
     }
     /**
@@ -241,14 +327,23 @@ class IDRegistryService {
         if (!this.registry) {
             return undefined;
         }
-        // Chercher le fichier dans toutes les branches
-        for (const [cacheKey, matter] of Object.entries(this.registry.matters)) {
-            const [, cachedFile] = cacheKey.split(':');
-            if (cachedFile === file) {
-                return matter.id;
+        // Chercher le fichier dans toutes les branches.
+        // Si plusieurs IDs existent (état incohérent), retourner un ID canonique déterministe
+        // pour éviter les oscillations entre redémarrages.
+        const ids = new Set();
+        for (const matter of Object.values(this.registry.matters)) {
+            if (matter.file === file && typeof matter.id === 'number') {
+                ids.add(matter.id);
             }
         }
-        return undefined;
+        if (ids.size === 0) {
+            return undefined;
+        }
+        if (ids.size === 1) {
+            return [...ids][0];
+        }
+        // Politique d'arbitrage: conserver le plus petit ID observé pour ce fichier.
+        return Math.min(...ids);
     }
     /**
      * Vérifie si un ID appartient déjà à un fichier spécifique
@@ -274,18 +369,14 @@ class IDRegistryService {
      * @param id L'ID à chercher
      * @returns Le nom du fichier qui possède cet ID, ou undefined
      */
-    getFileByID(id) {
+    getFileByID(branch, id) {
+        return this.getMatterCache(branch, id)?.file;
+    }
+    getMatterCachesByID(id) {
         if (!this.registry) {
-            return undefined;
-        }
-        // Chercher l'ID dans le cache
-        for (const [cacheKey, matter] of Object.entries(this.registry.matters)) {
-            if (matter.id === id) {
-                const [, file] = cacheKey.split(':');
-                return file;
-            }
+            return [];
         }
-        return undefined;
+        return Object.values(this.registry.matters).filter(matter => matter.id === id);
     }
     /**
      * Enregistre un ID existant
@@ -327,23 +418,24 @@ class IDRegistryService {
      * Récupère un matter depuis le cache
      * Note: Le champ 'updated' est filtré pour ne pas être exposé à l'extérieur
      */
-    getMatterCache(branch, file) {
+    getMatterCache(branch, id) {
         if (!this.registry) {
             throw new Error('IDRegistryService not initialized. Call init() first.');
         }
-        const cacheKey = `${branch}:${file}`;
-        const cached = this.registry.matters[cacheKey];
-        if (!cached) {
-            return undefined;
+        const cacheKey = this.createMatterKey(branch, id);
+        return this.registry.matters[cacheKey];
+    }
+    getMatterCacheByFile(branch, file) {
+        if (!this.registry) {
+            throw new Error('IDRegistryService not initialized. Call init() first.');
         }
-        // Retourner uniquement les champs publics (sans 'updated')
-        return {
-            id: cached.id,
-            title: cached.title,
-            service: cached.service,
-            // FIXME(oldfile): compat temporaire; ne pas utiliser oldfile comme identité documentaire.
-            oldfile: cached.oldfile
-        };
+        for (const [cacheKey, matter] of Object.entries(this.registry.matters)) {
+            const parsed = this.parseMatterKey(cacheKey);
+            if (parsed?.branch === branch && matter.file === file) {
+                return matter;
+            }
+        }
+        return undefined;
     }
     /**
      * Met à jour le cache d'un matter
@@ -352,13 +444,17 @@ class IDRegistryService {
         if (!this.registry) {
             throw new Error('IDRegistryService not initialized. Call init() first.');
         }
-        const cacheKey = `${branch}:${file}`;
+        if (!matter.id || !Number.isFinite(matter.id)) {
+            this.deleteMatterCacheByFile(branch, file);
+            return;
+        }
+        this.deleteMatterCacheByFile(branch, file);
+        const cacheKey = this.createMatterKey(branch, matter.id);
         this.registry.matters[cacheKey] = {
             id: matter.id,
+            file,
             title: matter.title,
             service: matter.service,
-            // FIXME(oldfile): compat temporaire; à retirer quand le client ne dépend plus de ce signal.
-            oldfile: matter.oldfile,
             updated: new Date().toISOString()
         };
         this.isDirty = true;
@@ -366,14 +462,21 @@ class IDRegistryService {
     /**
      * Supprime une entrée du cache
      */
-    deleteMatterCache(branch, file) {
+    deleteMatterCache(branch, id) {
         if (!this.registry) {
             throw new Error('IDRegistryService not initialized. Call init() first.');
         }
-        const cacheKey = `${branch}:${file}`;
+        const cacheKey = this.createMatterKey(branch, id);
         delete this.registry.matters[cacheKey];
         this.isDirty = true;
     }
+    deleteMatterCacheByFile(branch, file) {
+        const cached = this.getMatterCacheByFile(branch, file);
+        if (!cached?.id) {
+            return;
+        }
+        this.deleteMatterCache(branch, cached.id);
+    }
     /**
      * Renomme une entrée dans le cache du registre
      *
@@ -392,27 +495,18 @@ class IDRegistryService {
      * idRegistryService.rename('old-name.md', 'new-name.md', 'rule-validation-1');
      * ```
      */
-    rename(oldFile, newFile, branch) {
+    rename(id, newFile, branch) {
         if (!this.registry) {
             throw new Error('IDRegistryService not initialized. Call init() first.');
         }
-        const oldKey = `${branch}:${oldFile}`;
-        const newKey = `${branch}:${newFile}`;
-        // Récupérer le cache existant
-        const cached = this.registry.matters[oldKey];
+        const cacheKey = this.createMatterKey(branch, id);
+        const cached = this.registry.matters[cacheKey];
         if (!cached) {
-            // Pas de cache pour l'ancien fichier, rien à renommer
             return;
         }
-        // Supprimer l'ancienne clé
-        delete this.registry.matters[oldKey];
-        //
-        // Créer la nouvelle clé avec les mêmes données
-        // ⚠️ NE PAS inclure oldfile - c'est temporaire uniquement pour notification client
-        this.registry.matters[newKey] = {
-            id: cached.id,
-            title: cached.title,
-            service: cached.service,
+        this.registry.matters[cacheKey] = {
+            ...cached,
+            file: newFile,
             updated: new Date().toISOString()
         };
         this.isDirty = true;
@@ -552,6 +646,9 @@ function gitReloadIDRegistry(config) {
 /**
  * Enregistre un ID existant dans le registre
  *
+ * @deprecated Préférer `gitCreateOrEditFile(...)`, `gitUpdateMatter(...)` ou
+ * `gitRenameFile(...)` qui synchronisent le registre dans le même flux documentaire.
+ *
  * @param matter Le matter contenant l'ID à enregistrer
  * @param branch Branche du fichier (optionnel, pour vérification de propriété)
  * @param file Nom du fichier (optionnel, pour vérification de propriété)
@@ -575,8 +672,9 @@ function gitRegisterExistingID(matter, branch, file, config) {
     // Si l'ID existe déjà, vérifier qu'il appartient au MÊME fichier
     const registry = idRegistryService.getRegistry();
     if (registry.used.includes(matter.id)) {
-        const ownerFile = idRegistryService.getFileByID(matter.id);
-        if (ownerFile && ownerFile !== file) {
+        const conflictingOwner = idRegistryService.getMatterCachesByID(matter.id)
+            .find(owner => owner.file !== file);
+        if (conflictingOwner?.file) {
             // ID utilisé par un AUTRE fichier → Erreur
             const error = new Error(`ID ${matter.id} est déjà utilisé`);
             error.code = 'id_already_used';
@@ -595,6 +693,8 @@ function gitRegisterExistingID(matter, branch, file, config) {
 /**
  * Renomme un fichier dans le cache du registre d'IDs
  *
+ * @deprecated Le cache de matter/ID est maintenant mis à jour par `gitRenameFile(...)`.
+ *
  * Cette fonction met à jour le cache lorsqu'un fichier est renommé:
  * - Supprime l'entrée avec l'ancien nom
  * - Crée une nouvelle entrée avec le nouveau nom
@@ -614,7 +714,102 @@ function gitRegisterExistingID(matter, branch, file, config) {
 function gitIDRegistryRename(oldFile, newFile, branch, config) {
     const gitConf = (0, repo_tools_1.gitLoad)(config);
     idRegistryService.init(gitConf.repoPath);
-    idRegistryService.rename(oldFile, newFile, branch);
+    const cached = idRegistryService.getMatterCacheByFile(branch, oldFile);
+    if (!cached?.id) {
+        return;
+    }
+    idRegistryService.rename(cached.id, newFile, branch);
+    idRegistryService.save();
+}
+function gitGetMatterCache(branch, id, config) {
+    const gitConf = (0, repo_tools_1.gitLoad)(config);
+    idRegistryService.init(gitConf.repoPath);
+    const cached = idRegistryService.getMatterCache(branch, id);
+    if (!cached) {
+        return undefined;
+    }
+    return {
+        id: cached.id,
+        file: cached.file,
+        title: cached.title,
+        service: cached.service
+    };
+}
+function gitSetMatterCache(branch, file, matter, config) {
+    const gitConf = (0, repo_tools_1.gitLoad)(config);
+    idRegistryService.init(gitConf.repoPath);
+    idRegistryService.setMatterCache(branch, file, matter);
+    idRegistryService.save();
+}
+function isRulesGitConfig(value) {
+    return !!value
+        && typeof value === 'object'
+        && 'instance' in value
+        && 'repoPath' in value
+        && 'mainBranch' in value;
+}
+function resolveDocumentMutationOptions(options) {
+    if (isRulesGitConfig(options)) {
+        return { config: options };
+    }
+    return options ?? {};
+}
+function buildDocumentMutationContent(currentContent, nextContent, matterPatch) {
+    const currentParsed = (0, utils_matter_1.matterParse)(currentContent);
+    const hasMatterPatch = !!matterPatch && Object.keys(matterPatch).length > 0;
+    if (!nextContent && !hasMatterPatch) {
+        return {
+            content: currentContent,
+            matter: currentParsed.matter
+        };
+    }
+    const candidateParsed = nextContent ? (0, utils_matter_1.matterParse)(nextContent) : currentParsed;
+    const matter = {
+        ...currentParsed.matter,
+        ...candidateParsed.matter,
+        ...(matterPatch ?? {})
+    };
+    return {
+        content: (0, utils_matter_1.matterSerialize)(candidateParsed.content, matter),
+        matter
+    };
+}
+function assertUpdateMatterDoesNotRequireRename(filePath, matterPatch, finalMatter) {
+    if (!matterPatch || !Object.prototype.hasOwnProperty.call(matterPatch, 'title')) {
+        return;
+    }
+    const nextTitle = finalMatter.title?.trim();
+    if (!nextTitle) {
+        throw new errors_1.GitOperationError('Le matter doit contenir un champ "title" de type string', 'missing_title', { filePath, matter: finalMatter });
+    }
+    const currentSlug = (0, utils_slug_1.slugFromFile)(filePath);
+    const nextSlug = (0, utils_1.toSlug)(nextTitle);
+    if (nextSlug !== currentSlug) {
+        throw new errors_1.GitOperationError(`La mutation du matter nécessite un rename explicite: ${filePath} -> ${nextSlug}.md`, 'rename_required', { filePath, currentSlug, nextSlug, title: nextTitle });
+    }
+}
+function assertRenameMatterMatchesFile(newFileName, finalMatter) {
+    const nextTitle = finalMatter.title?.trim();
+    if (!nextTitle) {
+        return;
+    }
+    const expectedSlug = (0, utils_1.toSlug)(nextTitle);
+    const targetSlug = (0, utils_slug_1.slugFromFile)(newFileName);
+    if (expectedSlug !== targetSlug) {
+        throw new errors_1.GitOperationError(`Le titre final "${nextTitle}" ne correspond pas au fichier "${newFileName}"`, 'rename_matter_mismatch', { newFileName, expectedSlug, targetSlug, title: nextTitle });
+    }
+}
+function syncMatterCacheAfterRename(branch, oldFileName, newFileName, matter, config) {
+    const gitConf = (0, repo_tools_1.gitLoad)(config);
+    idRegistryService.init(gitConf.repoPath);
+    idRegistryService.deleteMatterCacheByFile(branch, oldFileName);
+    if (typeof matter.id === 'number' && Number.isFinite(matter.id)) {
+        idRegistryService.setMatterCache(branch, newFileName, {
+            id: matter.id,
+            title: matter.title,
+            service: matter.service
+        });
+    }
     idRegistryService.save();
 }
 /**
@@ -636,17 +831,21 @@ function gitEnsureMatterID(matter, config, branch, file) {
     // ✅ NOUVEAU: Chercher d'abord l'ID existant du fichier (peu importe la branche)
     const existingFileID = file ? idRegistryService.getFileID(file) : undefined;
     if (existingFileID) {
-        // Le fichier a déjà un ID → le réutiliser pour garantir la cohérence
-        matter.id = existingFileID;
-        // Mettre à jour le cache si branch est définie (sinon ce sera fait plus tard)
-        if (branch && file && matter.title) {
-            idRegistryService.setMatterCache(branch, file, {
-                id: matter.id,
-                title: matter.title,
-                service: matter.service
-            });
+        // Le fichier a déjà un ID candidat dans le cache.
+        // Ne le réutiliser que s'il est bien arbitré pour ce fichier.
+        const owner = branch ? idRegistryService.getMatterCache(branch, existingFileID) : undefined;
+        if (!owner?.file || owner.file === file) {
+            matter.id = existingFileID;
+            // Mettre à jour le cache si branch est définie (sinon ce sera fait plus tard)
+            if (branch && file && matter.title) {
+                idRegistryService.setMatterCache(branch, file, {
+                    id: matter.id,
+                    title: matter.title,
+                    service: matter.service
+                });
+            }
+            return matter;
         }
-        return matter;
     }
     // Si matter a un ID fourni manuellement (ex: import ou test)
     // FIXME 999 should be a constant in config
@@ -703,7 +902,7 @@ function validateMatter(matter) {
  */
 function extractMatterFromContent(content) {
     if (!content) {
-        return { id: 0, title: undefined, service: undefined, oldfile: undefined };
+        return { id: 0, title: undefined, service: undefined };
     }
     // Regex pour extraire id (format: "id: 1234" ou "id: '1234'")
     const idMatch = content.match(/^id:\s*['"]?(\d+)['"]?/m);
@@ -713,11 +912,7 @@ function extractMatterFromContent(content) {
     const title = titleMatch ? titleMatch[1].trim() : undefined;
     const serviceMatch = content.match(/^service:\s*["']?([^"'\n]+)["']?/m);
     const service = serviceMatch ? serviceMatch[1].trim() : undefined;
-    //
-    // FIXME(oldfile): extraction legacy pour compat UI rename; migration cible: ID-only.
-    const oldfileMatch = content.match(/^oldfile:\s*["']?([^"'\n]+)["']?/m);
-    const oldfile = oldfileMatch ? oldfileMatch[1].trim() : undefined;
-    return { id, title, service, oldfile };
+    return { id, title, service };
 }
 /**
  * Lecture rapide et stricte du matter d'un fichier (id + title uniquement)
@@ -747,19 +942,18 @@ async function gitFileStrictMatter(git, filePath, branch, config) {
     idRegistryService.init(gitConf.repoPath);
     try {
         // ✅ ÉTAPE 1: Vérifier le cache
-        const cached = idRegistryService.getMatterCache(branch, filePath);
+        const cached = idRegistryService.getMatterCacheByFile(branch, filePath);
         if (cached) {
             // Cache trouvé, retourner directement
             return {
                 id: cached.id,
-                title: cached.title,
-                oldfile: cached.oldfile // ✅ Inclure oldfile temporaire
+                title: cached.title
             };
         }
         // ❌ ÉTAPE 2: Cache absent, lire le fichier
         const content = await git.show([`${branch}:${filePath}`]);
         if (!content) {
-            return { id: undefined, title: undefined, oldfile: undefined };
+            return { id: undefined, title: undefined };
         }
         // ✅ ÉTAPE 3: Extraction rapide avec regex (sans matterParse complet)
         const matter = extractMatterFromContent(content);
@@ -772,7 +966,7 @@ async function gitFileStrictMatter(git, filePath, branch, config) {
         if (gitConf.verbose) {
             console.warn(`⚠️ Erreur lecture matter de ${filePath}:`, error);
         }
-        return { id: undefined, title: undefined, oldfile: undefined };
+        return { id: undefined, title: undefined };
     }
 }
 /**
@@ -1207,8 +1401,8 @@ async function gitCreateOrEditFile(git, filePath, PR, content, user, config) {
             idRegistryService.init(gitConf.repoPath);
             idRegistryService.setMatterCache(PR, filePath, {
                 id: parsed.matter.id,
-                title: parsed.matter.title
-                // ⚠️ Ne PAS persister oldfile dans le cache - temporaire uniquement pour client
+                title: parsed.matter.title,
+                service: parsed.matter.service
             });
             idRegistryService.save();
         }
@@ -1232,8 +1426,18 @@ async function gitCreateOrEditFile(git, filePath, PR, content, user, config) {
         }
         // Determine the current head after the commit attempt.
         const newHead = (await git.revparse(['HEAD'])).trim();
-        let newFiles = await (0, repo_tools_1.gitGetDiffFiles)(git, PR, oldNote.mergeBase);
-        newFiles = await sanitizePRFiles(git, newFiles, PR);
+        // IMPORTANT:
+        // Le scope d'une PR doit rester le delta métier déclaré (fichiers déjà trackés + fichier courant),
+        // pas un recalcul global de diff qui peut gonfler metadata.files si mergeBase est absent/ancien.
+        const previousFiles = Array.isArray(oldNote.files) ? oldNote.files : [];
+        const mergedFiles = [...previousFiles, filePath];
+        let newFiles = await sanitizePRFiles(git, mergedFiles, PR);
+        // Fallback de compat pour anciennes notes sans files
+        if (newFiles.length === 0) {
+            const safeBase = oldNote.mergeBase || gitConf.draftBranch;
+            newFiles = await (0, repo_tools_1.gitGetDiffFiles)(git, PR, safeBase);
+            newFiles = await sanitizePRFiles(git, newFiles, PR);
+        }
         const updatedNote = {
             ...oldNote,
             files: newFiles,
@@ -1296,7 +1500,57 @@ async function gitEditFile(git, filePath, PR, content, user, config) {
     }
     return await gitCreateOrEditFile(git, filePath, PR, content, user, config);
 }
-async function gitRenameFile_git(git, oldFileName, newFileName, branch, user, config) {
+/**
+ * Met à jour le front-matter d'un document sans changer son nom de fichier.
+ *
+ * Cette API refuse explicitement toute mutation du `title` qui nécessiterait
+ * un changement de slug / filename. Dans ce cas, utiliser `gitRenameFile(...)`.
+ */
+async function gitUpdateMatter(git, filePath, branch, user, options) {
+    const resolvedOptions = resolveDocumentMutationOptions(options);
+    const gitConf = (0, repo_tools_1.gitLoad)(resolvedOptions.config);
+    let currentContent;
+    if (branch.toLowerCase() === 'new') {
+        if (!gitConf.uploadPath) {
+            throw new errors_1.GitOperationError('uploadPath is required for NEW document mutations', 'missing_upload_path', { filePath, branch });
+        }
+        const fullPath = (0, path_1.join)(gitConf.uploadPath, filePath);
+        if (!(0, fs_1.existsSync)(fullPath)) {
+            throw new errors_1.FileNotFoundError(filePath, branch);
+        }
+        currentContent = await fs.readFile(fullPath, 'utf8');
+    }
+    else {
+        const currentDocument = await (0, repo_tools_1.gitGetFileContent)(git, filePath, branch);
+        currentContent = currentDocument?.content;
+    }
+    if (!currentContent) {
+        throw new errors_1.FileNotFoundError(filePath, branch);
+    }
+    const finalDocument = buildDocumentMutationContent(currentContent, undefined, resolvedOptions.matter);
+    assertUpdateMatterDoesNotRequireRename(filePath, resolvedOptions.matter, finalDocument.matter);
+    if (branch.toLowerCase() === 'new') {
+        const fullPath = (0, path_1.join)(gitConf.uploadPath, filePath);
+        await fs.writeFile(fullPath, finalDocument.content, { flag: 'w', encoding: 'utf8' });
+        return {
+            hash: '',
+            date: new Date(),
+            message: `update matter: ${filePath}`,
+            author: {
+                name: user.name,
+                email: user.email
+            },
+            branch,
+            content: finalDocument.content
+        };
+    }
+    const commit = await gitCreateOrEditFile(git, filePath, branch, finalDocument.content, user, gitConf);
+    return {
+        ...commit,
+        content: finalDocument.content
+    };
+}
+async function gitRenameFile_git(git, oldFileName, newFileName, branch, user, finalContent, config) {
     // Si les noms sont identiques, pas besoin de renommer
     if (oldFileName === newFileName) {
         return {
@@ -1324,6 +1578,12 @@ async function gitRenameFile_git(git, oldFileName, newFileName, branch, user, co
         await git.checkout(branch);
         // Rename file with git mv (atomique dans Git)
         await git.raw(['mv', oldFileName, newFileName]);
+        if (typeof finalContent === 'string') {
+            const fullNewPath = (0, path_1.join)(gitConf.repoPath, newFileName);
+            await fs.mkdir((0, path_1.dirname)(fullNewPath), { recursive: true });
+            await fs.writeFile(fullNewPath, finalContent, { flag: 'w', encoding: 'utf8' });
+            await git.add(newFileName);
+        }
         // Commit - git mv automatically stages changes
         const commit = await git.commit(`rename: ${oldFileName} → ${newFileName}`, {
             '--author': `${user.name} <${user.email}>`
@@ -1336,17 +1596,11 @@ async function gitRenameFile_git(git, oldFileName, newFileName, branch, user, co
                 name: user.name,
                 email: user.email
             },
-            branch: branch
+            branch: branch,
+            content: finalContent
         };
     }
     catch (error) {
-        // En cas d'erreur, essayer de restaurer l'état initial
-        try {
-            await git.reset(['--hard']);
-        }
-        catch (resetError) {
-            console.warn('Could not reset after failed rename:', resetError);
-        }
         throw error;
     }
     finally {
@@ -1356,7 +1610,7 @@ async function gitRenameFile_git(git, oldFileName, newFileName, branch, user, co
         (0, repo_tools_1.unlock)(`checkout`);
     }
 }
-async function gitRenameFile_fs(git, oldFileName, newFileName, branch, user, config) {
+async function gitRenameFile_fs(git, oldFileName, newFileName, branch, user, finalContent, config) {
     // Si les noms sont identiques, pas besoin de renommer
     if (oldFileName === newFileName) {
         return {
@@ -1370,6 +1624,9 @@ async function gitRenameFile_fs(git, oldFileName, newFileName, branch, user, con
     const gitConf = (0, repo_tools_1.gitLoad)(config);
     try {
         await (0, repo_tools_1.lock)(`checkout`);
+        if (!gitConf.uploadPath) {
+            throw new errors_1.GitOperationError('uploadPath is required for filesystem rename', 'missing_upload_path', { oldFileName, newFileName, branch });
+        }
         const fullNewPath = (0, path_1.join)(gitConf.uploadPath, newFileName);
         const fullOldPath = (0, path_1.join)(gitConf.uploadPath, oldFileName);
         // Vérifier que l'ancien fichier existe
@@ -1383,10 +1640,13 @@ async function gitRenameFile_fs(git, oldFileName, newFileName, branch, user, con
             throw new Error(`Le fichier de destination "${newFileName}" existe déjà sur le système de fichiers`);
         }
         // Renommage atomique filesystem
-        // Utiliser copyFile + unlink pour plus de sécurité que rename() sur certains systèmes
         try {
+            await fs.mkdir((0, path_1.dirname)(fullNewPath), { recursive: true });
             await fs.copyFile(fullOldPath, fullNewPath);
             await fs.unlink(fullOldPath);
+            if (typeof finalContent === 'string') {
+                await fs.writeFile(fullNewPath, finalContent, { flag: 'w', encoding: 'utf8' });
+            }
         }
         catch (copyError) {
             // En cas d'erreur, nettoyer le nouveau fichier s'il a été créé
@@ -1408,7 +1668,8 @@ async function gitRenameFile_fs(git, oldFileName, newFileName, branch, user, con
                 name: user.name,
                 email: user.email
             },
-            branch: branch
+            branch: branch,
+            content: finalContent
         };
     }
     catch (error) {
@@ -1428,7 +1689,7 @@ async function gitRenameFile_fs(git, oldFileName, newFileName, branch, user, con
  * @param config Configuration Git optionnelle
  * @returns Historique du commit de renommage
  */
-async function gitRenameFile(git, oldFileName, newFileName, branch, user, config) {
+async function gitRenameFile(git, oldFileName, newFileName, branch, user, options, nextContent) {
     // Si les noms sont identiques, pas besoin de renommer
     if (oldFileName === newFileName) {
         return {
@@ -1439,37 +1700,44 @@ async function gitRenameFile(git, oldFileName, newFileName, branch, user, config
             branch: branch
         };
     }
-    // load config
-    const gitConf = (0, repo_tools_1.gitLoad)(config);
-    // Pour les fichiers dans Git, utiliser Git uniquement (pas de fallback filesystem)
-    try {
-        //
-        //FIXME: add a check about the branch (file can be NEW and on branch)
-        const fullOldPath = (0, path_1.join)(gitConf.uploadPath, oldFileName);
-        let result;
-        if ((0, fs_1.existsSync)(fullOldPath)) {
-            result = await gitRenameFile_fs(git, oldFileName, newFileName, branch, user, config);
-        }
-        else {
-            result = await gitRenameFile_git(git, oldFileName, newFileName, branch, user, config);
-            if (branch !== 'NEW' && branch.startsWith(gitConf.validationPrefix)) {
-                try {
-                    await gitPRReplaceFile(git, branch, { remove: oldFileName, add: newFileName }, gitConf);
-                }
-                catch (metadataError) {
-                    if (gitConf.verbose) {
-                        console.warn('⚠️ Failed to update PR metadata after rename:', metadataError);
-                    }
+    const resolvedOptions = resolveDocumentMutationOptions(options);
+    const gitConf = (0, repo_tools_1.gitLoad)(resolvedOptions.config);
+    if (branch.toLowerCase() === 'new' && !gitConf.uploadPath) {
+        throw new errors_1.GitOperationError('uploadPath is required for NEW renames', 'missing_upload_path', { oldFileName, newFileName, branch });
+    }
+    const fullOldPath = gitConf.uploadPath ? (0, path_1.join)(gitConf.uploadPath, oldFileName) : '';
+    const useFilesystem = branch.toLowerCase() === 'new'
+        || (!!gitConf.uploadPath && (0, fs_1.existsSync)(fullOldPath) && !(await (0, repo_tools_1.gitFileExistsInBranch)(git, oldFileName, branch)));
+    const currentContent = useFilesystem
+        ? await fs.readFile(fullOldPath, 'utf8')
+        : (await (0, repo_tools_1.gitGetFileContent)(git, oldFileName, branch))?.content;
+    if (!currentContent) {
+        throw new errors_1.FileNotFoundError(oldFileName, branch);
+    }
+    const finalDocument = buildDocumentMutationContent(currentContent, nextContent, resolvedOptions.matter);
+    assertRenameMatterMatchesFile(newFileName, finalDocument.matter);
+    let result;
+    if (useFilesystem) {
+        result = await gitRenameFile_fs(git, oldFileName, newFileName, branch, user, finalDocument.content, gitConf);
+    }
+    else {
+        result = await gitRenameFile_git(git, oldFileName, newFileName, branch, user, finalDocument.content, gitConf);
+        if (branch.startsWith(gitConf.validationPrefix)) {
+            try {
+                await gitPRReplaceFile(git, branch, { remove: oldFileName, add: newFileName }, gitConf);
+            }
+            catch (metadataError) {
+                if (gitConf.verbose) {
+                    console.warn('⚠️ Failed to update PR metadata after rename:', metadataError);
                 }
             }
         }
-        return result;
-    }
-    catch (error) {
-        // Pour les vraies branches Git, ne pas faire de fallback filesystem
-        // Seules les branches NEW utilisent le filesystem
-        throw error;
+        syncMatterCacheAfterRename(branch, oldFileName, newFileName, finalDocument.matter, gitConf);
     }
+    return {
+        ...result,
+        content: finalDocument.content
+    };
 }
 /**
  * Met à jour la liste des fichiers d'une PR après un renommage.
@@ -1555,7 +1823,18 @@ async function gitDeleteFile(git, filePath, branch, user, config) {
         // Mettre à jour la note si elle existe (pour les branches PR)
         if (oldNote) {
             const newHead = (await git.revparse(['HEAD'])).trim();
-            const newFiles = await (0, repo_tools_1.gitGetDiffFiles)(git, branch, oldNote.mergeBase);
+            // IMPORTANT:
+            // Conserver metadata.files piloté par les opérations métier explicites.
+            // Ici: suppression => on retire seulement le fichier supprimé, puis on sanitize.
+            const previousFiles = Array.isArray(oldNote.files) ? oldNote.files : [];
+            const mergedFiles = previousFiles.filter((f) => f !== filePath);
+            let newFiles = await sanitizePRFiles(git, mergedFiles, branch);
+            // Fallback de compat pour anciennes notes sans files
+            if (newFiles.length === 0 && previousFiles.length === 0) {
+                const safeBase = oldNote.mergeBase || gitConf.draftBranch;
+                newFiles = await (0, repo_tools_1.gitGetDiffFiles)(git, branch, safeBase);
+                newFiles = await sanitizePRFiles(git, newFiles, branch);
+            }
             const updatedNote = {
                 ...oldNote,
                 files: newFiles,
@@ -1847,6 +2126,11 @@ async function checkMergeInProgress(repoPath) {
     return mergeFiles.some(file => (0, fs_1.existsSync)((0, path_1.join)(gitDir, file)));
 }
 async function sanitizePRFiles(git, files, branch) {
+    // TODO(PR scope): Clarifier le besoin métier.
+    // - Cette fonction valide seulement "existe dans la branche" + déduplication.
+    // - Sur une branche créée depuis rule-editor (checkout -b), presque tous les fichiers existent déjà.
+    // - Donc ce helper NE peut PAS, à lui seul, déterminer le vrai périmètre PR.
+    // Source de vérité attendue: metadata.files maintenu par opérations explicites (add/edit/rename/delete).
     if (!files || files.length === 0) {
         return [];
     }