agentic-api 2.0.646 → 2.0.885

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

@@ -27,6 +27,7 @@ class GitHealthManager {
     async repairRepository(branch) {
         // CRITICAL FIX: Checkout sur la branche cible avant forceRepair()
         // Sinon ensureSafeBranch() vérifie la branche courante (qui peut être 'main')
+        const failedBranches = [];
         try {
             await this.git.checkout(branch);
         }
@@ -197,6 +198,7 @@ class GitHealthManager {
      */
     async syncValidationBranches() {
         const { validationPrefix } = this.config;
+        const failedBranches = [];
         if (!validationPrefix) {
             console.error("Erreur: Le préfixe de validation n'est pas configuré.");
             return;
@@ -218,6 +220,9 @@ class GitHealthManager {
             for (const branch of validationBranches) {
                 try {
                     await this.repairRepository(branch);
+                    // Synchroniser explicitement la branche de validation avec son mergeBase.
+                    // gitSyncPR préserve metadata.files et ne doit pas regonfler le scope PR.
+                    await (0, git_1.gitSyncPR)(this.git, branch, user);
                 }
                 catch (error) {
                     console.warn(`⚠️  Échec de la synchronisation de ${branch}: ${error.message}`);
@@ -257,7 +262,8 @@ class GitHealthManager {
                     catch (repairError) {
                         console.error(`❌ Impossible de réparer ${branch}: ${repairError.message}`);
                         console.error(`📝 Cette branche nécessite une intervention manuelle`);
-                        throw repairError;
+                        failedBranches.push(branch);
+                        continue;
                     }
                 }
             }
@@ -285,6 +291,9 @@ class GitHealthManager {
                 console.warn(`⚠️  Erreur lors du retour à la branche originale: ${error}`);
             }
         }
+        if (failedBranches.length > 0) {
+            console.warn(`⚠️  Synchronisation incomplète (${failedBranches.length} branche(s) ignorée(s)): ${failedBranches.join(', ')}`);
+        }
     }
     /**
      * Migrates Git notes from the first commit of validation branches to the last one.
@@ -299,7 +308,7 @@ class GitHealthManager {
      * @returns GitPrNoteMigrationReport avec le nombre de notes migrées, déjà OK, et perdues
      */
     async migrateNotes() {
-        const { mainBranch, validationPrefix, gitNotes } = this.config;
+        const { draftBranch, validationPrefix, gitNotes } = this.config;
         if (!validationPrefix || !gitNotes.namespace) {
             console.error("Erreur: Le préfixe de validation ou le namespace des notes n'est pas configuré.");
             return { migrated: 0, alreadyOk: 0, lost: [] };
@@ -315,22 +324,30 @@ class GitHealthManager {
         for (const branch of validationBranches) {
             try {
                 const lastCommit = (await this.git.revparse(branch)).trim();
+                const prNumber = parseInt(branch.split('-').pop() || '0', 10);
                 // 1. Check if note is already on the last commit
                 const noteOnHead = await (0, git_1.gitReadNote)(this.git, lastCommit, gitNotes.namespace, 1);
                 if (noteOnHead) {
-                    alreadyOkCount++;
-                    continue;
+                    // Valider que la note HEAD correspond bien à la PR de la branche.
+                    // Sinon, continuer la recherche dans l'historique pour éviter les faux "already OK".
+                    if (noteOnHead.id === prNumber) {
+                        alreadyOkCount++;
+                        continue;
+                    }
+                    console.log(`   ⚠️  ${branch}: Note HEAD id=${noteOnHead.id}, attendu id=${prNumber} - recherche historique`);
                 }
                 // 2. Scan the branch history for a note
-                const mergeBase = (await this.git.raw('merge-base', mainBranch, branch)).trim();
+                // IMPORTANT:
+                // Les branches de validation sont créées depuis rule-editor (draftBranch),
+                // pas depuis main. Utiliser main élargit artificiellement l'historique scanné
+                // et peut faire remonter des notes d'autres PR (faux positifs).
+                const mergeBase = (await this.git.raw('merge-base', draftBranch, branch)).trim();
                 if (!mergeBase) {
-                    console.log(`⚠️  ${branch}: Impossible de trouver un point de merge avec '${mainBranch}'. Ignoré.`);
+                    console.log(`⚠️  ${branch}: Impossible de trouver un point de merge avec '${draftBranch}'. Ignoré.`);
                     continue;
                 }
                 const revListOutput = await this.git.raw('rev-list', `${mergeBase}..${branch}`);
                 const branchCommits = revListOutput.split('\n').filter(Boolean);
-                // Extract PR number from branch name (e.g., rule-validation-31 -> 31)
-                const prNumber = parseInt(branch.split('-').pop() || '0', 10);
                 let oldNoteCommit = null;
                 for (const commitHash of branchCommits) {
                     const note = await (0, git_1.gitReadNote)(this.git, commitHash, gitNotes.namespace, 1);
@@ -424,15 +441,20 @@ class GitHealthManager {
                     // Lister tous les fichiers .md dans la branche
                     const allFiles = await (0, git_1.gitListFilesInBranch)(this.git, branchName);
                     const mdFiles = allFiles.filter(f => f.endsWith('.md'));
+                    const seenIDs = new Map();
                     // Variables pour suivre les problèmes dans cette branche
                     let branchHasIssues = false;
                     const branchIssues = [];
                     for (const file of mdFiles) {
                         report.scanned++;
                         try {
-                            // ✅ OPTIMISATION: Lecture rapide du matter (id + title uniquement)
-                            // Utilise le cache, évite de parser tout le fichier
-                            const matter = await (0, git_1.gitFileStrictMatter)(this.git, file, branchName, this.config);
+                            // Lecture fraîche depuis Git: évite les faux positifs liés à un cache matter obsolète.
+                            const fileData = await (0, git_1.gitGetFileContent)(this.git, file, branchName);
+                            const parsed = (0, utils_matter_1.matterParse)(fileData?.content || '');
+                            const matter = {
+                                id: parsed.matter?.id,
+                                title: parsed.matter?.title
+                            };
                             // Vérification de l'ID et du titre
                             let hasValidID = false;
                             let hasValidTitle = false;
@@ -449,19 +471,15 @@ class GitHealthManager {
                             }
                             else {
                                 hasValidID = true;
-                                // Enregistrer l'ID existant dans le registry
-                                // ✅ gitRegisterExistingID() appelle maintenant setMatterCache() automatiquement si matter est fourni
-                                try {
-                                    (0, git_1.gitRegisterExistingID)(matter, branchName, file, this.config);
+                                const firstFile = seenIDs.get(matter.id);
+                                if (firstFile && firstFile !== file) {
+                                    report.duplicateID.push(`${fileRef} (id=${matter.id})`);
+                                    hasValidID = false;
+                                    branchHasIssues = true;
+                                    branchIssues.push(`   ⚠️  ${file}: ID ${matter.id} déjà utilisé`);
                                 }
-                                catch (error) {
-                                    if (error.code === 'id_already_used') {
-                                        // Compter les doublons mais ne pas les ajouter aux erreurs (seront réparés)
-                                        report.duplicateID.push(`${fileRef} (id=${matter.id})`);
-                                        hasValidID = false;
-                                        branchHasIssues = true;
-                                        branchIssues.push(`   ⚠️  ${file}: ID ${matter.id} déjà utilisé`);
-                                    }
+                                else {
+                                    seenIDs.set(matter.id, file);
                                 }
                             }
                             // Vérification du titre
@@ -551,42 +569,38 @@ class GitHealthManager {
         ];
         let fixed = 0;
         const fixedFiles = new Set();
-        // ✅ ÉTAPE CRITIQUE: Charger le cache pour toutes les branches avant la réparation
-        // Cela permet à getFileID() de trouver l'ID existant du fichier
+        const usedIdsByBranch = new Map();
         if (!dryRun && filesToFix.length > 0) {
-            console.log(`   🔍 Chargement du cache pour toutes les branches...`);
-            const allBranches = await (0, git_1.gitGetAllBranches)(this.git);
-            const uniqueFiles = new Set();
+            const uniqueBranches = new Set();
             for (const fileRef of filesToFix) {
-                const [, ...fileParts] = fileRef.split(':');
-                const file = fileParts.join(':');
-                uniqueFiles.add(file);
-            }
-            // Mettre en cache la liste des fichiers par branche pour éviter les appels répétés
-            const branchFilesCache = new Map();
-            for (const branch of allBranches) {
-                try {
-                    const filesInBranch = await (0, git_1.gitListFilesInBranch)(this.git, branch);
-                    branchFilesCache.set(branch, filesInBranch);
-                }
-                catch (e) {
-                    // Ignorer silencieusement les erreurs (branche peut être inaccessible)
-                    branchFilesCache.set(branch, []);
+                const [branchName] = fileRef.split(':');
+                if (branchName) {
+                    uniqueBranches.add(branchName);
                 }
             }
-            // Charger le cache pour chaque fichier dans les branches où il existe
-            for (const file of uniqueFiles) {
-                for (const branch of allBranches) {
-                    try {
-                        const filesInBranch = branchFilesCache.get(branch) || [];
-                        if (filesInBranch.includes(file)) {
-                            await (0, git_1.gitFileStrictMatter)(this.git, file, branch, this.config);
+            for (const branchName of uniqueBranches) {
+                const usedIds = new Set();
+                try {
+                    const filesInBranch = await (0, git_1.gitListFilesInBranch)(this.git, branchName);
+                    const mdFiles = filesInBranch.filter((f) => f.endsWith('.md'));
+                    for (const file of mdFiles) {
+                        try {
+                            const data = await (0, git_1.gitGetFileContent)(this.git, file, branchName);
+                            const parsed = (0, utils_matter_1.matterParse)(data?.content || '');
+                            const id = parsed.matter?.id;
+                            if (typeof id === 'number' && id > 999) {
+                                usedIds.add(id);
+                            }
+                        }
+                        catch {
+                            // Ignorer les fichiers inaccessibles ponctuellement
                         }
-                    }
-                    catch (e) {
-                        // Ignorer silencieusement les erreurs (fichier peut ne pas exister)
                     }
                 }
+                catch {
+                    // Ignorer les branches inaccessibles ponctuellement
+                }
+                usedIdsByBranch.set(branchName, usedIds);
             }
         }
         for (const fileRef of filesToFix) {
@@ -608,10 +622,29 @@ class GitHealthManager {
                     // Parser le matter complet
                     const parsed = (0, utils_matter_1.matterParse)(fileData.content);
                     const { matter: fullMatter, content } = parsed;
-                    // ✅ CORRECTION: Utiliser gitEnsureMatterID() pour réutiliser l'ID existant du fichier
-                    // Si le fichier existe déjà dans une autre branche, son ID sera réutilisé
-                    // Sinon, un nouvel ID sera généré automatiquement
-                    const matterWithID = (0, git_1.gitEnsureMatterID)(fullMatter, this.config, branchName, file);
+                    const isDuplicateIssue = report.duplicateID.some((entry) => entry.startsWith(fileRef));
+                    // Convergence stable:
+                    // - Cas normal: arbitrage par fichier (branch+file) pour réutiliser l'ID stable.
+                    // - Cas doublon réel: allouer un nouvel ID libre dans la branche et l'enregistrer explicitement.
+                    let matterWithID;
+                    if (isDuplicateIssue) {
+                        const usedIds = usedIdsByBranch.get(branchName) || new Set();
+                        let nextId = Math.max(1000, ...Array.from(usedIds)) + 20;
+                        while (usedIds.has(nextId)) {
+                            nextId += 20;
+                        }
+                        fullMatter.id = nextId;
+                        if (!fullMatter.title || fullMatter.title.trim() === '') {
+                            fullMatter.title = file.replace(/\.md$/, '');
+                        }
+                        (0, git_1.gitRegisterExistingID)(fullMatter, branchName, file, this.config);
+                        usedIds.add(nextId);
+                        usedIdsByBranch.set(branchName, usedIds);
+                        matterWithID = fullMatter;
+                    }
+                    else {
+                        matterWithID = (0, git_1.gitEnsureMatterID)(fullMatter, this.config, branchName, file);
+                    }
                     if (matterWithID.id !== fullMatter.id) {
                         if (fullMatter.id && fullMatter.id > 999) {
                             console.log(`   🔧 ${file}: ID ${fullMatter.id} remplacé par ID existant ${matterWithID.id}`);

package/dist/src/rules/git/index.d.ts

@@ -1,6 +1,6 @@
 export { lock, unlock, gitLoad, isValidInt, gitIsFileMerged, gitLastCommit, gitListFilesInBranch, gitListFilesOutsideRepo, gitFileExistsInBranch, gitGetFilesSummary, gitGetFileContent, gitGetFilePreview, gitGetFileHistory, gitReadFileOutsideRepo, gitGetUnmergedBranchesForFile, gitGetAllBranches, gitGetDiffFiles, gitReadNote, gitWriteNote, gitDeleteNote, } from './repo.tools';
-export { gitInit, gitEnsureRepositoryConfiguration, gitEnsureRemoteConfiguration, gitSetupRepository, gitShowConfiguration, gitCheckConfiguration, gitGetBranchHealth, gitGetValidationBranchHealth, gitCreateOrEditFile, gitEditFile, gitRenameFile, gitDeleteFile, gitGenerateNextID, gitReloadIDRegistry, gitRegisterExistingID, gitEnsureMatterID, gitFileStrictMatter, gitIDRegistryExists, gitIDRegistryRename, } from './repo';
-export { gitSyncPR, gitIsPRClosed, gitIsPRClosedRobust, gitGetPRMetadata, gitGetAllPR, gitGetClosedPRs, gitLoadPR, gitPRUpdateComments, gitClosePR, gitClosePRRobust, gitGetNextPRNumber, gitNewValidationRequest, gitNewPR, } from './repo.pr';
+export { gitInit, gitEnsureRepositoryConfiguration, gitEnsureRemoteConfiguration, gitSetupRepository, gitShowConfiguration, gitCheckConfiguration, gitGetBranchHealth, gitGetValidationBranchHealth, gitCreateOrEditFile, gitUpdateMatter, gitRenameFile, gitDeleteFile, gitEditFile, gitGenerateNextID, gitAllocateNextPRNumber, gitFileStrictMatter, gitGetMatterCache, gitSetMatterCache, GitDocumentMutationOptions, gitReloadIDRegistry, gitRegisterExistingID, gitEnsureMatterID, gitIDRegistryExists, gitIDRegistryRename, } from './repo';
+export { gitSyncPR, gitIsPRClosed, gitIsPRClosedRobust, gitGetPRMetadata, gitGetAllPR, gitGetClosedPRs, gitLoadPR, gitPRUpdateComments, gitClosePR, gitClosePRRobust, gitNewValidationRequest, gitNewPR, } from './repo.pr';
 export * from './git.e2e.helper';
 export * from './git.health';
 export * from './git.helper';

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

@@ -14,8 +14,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.gitGetNextPRNumber = exports.gitClosePRRobust = exports.gitClosePR = exports.gitPRUpdateComments = exports.gitLoadPR = exports.gitGetClosedPRs = exports.gitGetAllPR = exports.gitGetPRMetadata = exports.gitIsPRClosedRobust = exports.gitIsPRClosed = exports.gitSyncPR = exports.gitIDRegistryRename = exports.gitIDRegistryExists = exports.gitFileStrictMatter = exports.gitEnsureMatterID = exports.gitRegisterExistingID = exports.gitReloadIDRegistry = exports.gitGenerateNextID = exports.gitDeleteFile = exports.gitRenameFile = exports.gitEditFile = exports.gitCreateOrEditFile = exports.gitGetValidationBranchHealth = exports.gitGetBranchHealth = exports.gitCheckConfiguration = exports.gitShowConfiguration = exports.gitSetupRepository = exports.gitEnsureRemoteConfiguration = exports.gitEnsureRepositoryConfiguration = exports.gitInit = exports.gitDeleteNote = exports.gitWriteNote = exports.gitReadNote = exports.gitGetDiffFiles = exports.gitGetAllBranches = exports.gitGetUnmergedBranchesForFile = exports.gitReadFileOutsideRepo = exports.gitGetFileHistory = exports.gitGetFilePreview = exports.gitGetFileContent = exports.gitGetFilesSummary = exports.gitFileExistsInBranch = exports.gitListFilesOutsideRepo = exports.gitListFilesInBranch = exports.gitLastCommit = exports.gitIsFileMerged = exports.isValidInt = exports.gitLoad = exports.unlock = exports.lock = void 0;
-exports.gitNewPR = exports.gitNewValidationRequest = void 0;
+exports.gitLoadPR = exports.gitGetClosedPRs = exports.gitGetAllPR = exports.gitGetPRMetadata = exports.gitIsPRClosedRobust = exports.gitIsPRClosed = exports.gitSyncPR = exports.gitIDRegistryRename = exports.gitIDRegistryExists = exports.gitEnsureMatterID = exports.gitRegisterExistingID = exports.gitReloadIDRegistry = exports.gitSetMatterCache = exports.gitGetMatterCache = exports.gitFileStrictMatter = exports.gitAllocateNextPRNumber = exports.gitGenerateNextID = exports.gitEditFile = exports.gitDeleteFile = exports.gitRenameFile = exports.gitUpdateMatter = exports.gitCreateOrEditFile = exports.gitGetValidationBranchHealth = exports.gitGetBranchHealth = exports.gitCheckConfiguration = exports.gitShowConfiguration = exports.gitSetupRepository = exports.gitEnsureRemoteConfiguration = exports.gitEnsureRepositoryConfiguration = exports.gitInit = exports.gitDeleteNote = exports.gitWriteNote = exports.gitReadNote = exports.gitGetDiffFiles = exports.gitGetAllBranches = exports.gitGetUnmergedBranchesForFile = exports.gitReadFileOutsideRepo = exports.gitGetFileHistory = exports.gitGetFilePreview = exports.gitGetFileContent = exports.gitGetFilesSummary = exports.gitFileExistsInBranch = exports.gitListFilesOutsideRepo = exports.gitListFilesInBranch = exports.gitLastCommit = exports.gitIsFileMerged = exports.isValidInt = exports.gitLoad = exports.unlock = exports.lock = void 0;
+exports.gitNewPR = exports.gitNewValidationRequest = exports.gitClosePRRobust = exports.gitClosePR = exports.gitPRUpdateComments = void 0;
 // === OPÉRATIONS GIT BAS NIVEAU ===
 // Fonctions atomiques pour manipuler Git directement
 var repo_tools_1 = require("./repo.tools");
@@ -54,34 +54,51 @@ Object.defineProperty(exports, "gitShowConfiguration", { enumerable: true, get:
 Object.defineProperty(exports, "gitCheckConfiguration", { enumerable: true, get: function () { return repo_1.gitCheckConfiguration; } });
 Object.defineProperty(exports, "gitGetBranchHealth", { enumerable: true, get: function () { return repo_1.gitGetBranchHealth; } });
 Object.defineProperty(exports, "gitGetValidationBranchHealth", { enumerable: true, get: function () { return repo_1.gitGetValidationBranchHealth; } });
+// Document mutations
 Object.defineProperty(exports, "gitCreateOrEditFile", { enumerable: true, get: function () { return repo_1.gitCreateOrEditFile; } });
-Object.defineProperty(exports, "gitEditFile", { enumerable: true, get: function () { return repo_1.gitEditFile; } });
+Object.defineProperty(exports, "gitUpdateMatter", { enumerable: true, get: function () { return repo_1.gitUpdateMatter; } });
 Object.defineProperty(exports, "gitRenameFile", { enumerable: true, get: function () { return repo_1.gitRenameFile; } });
 Object.defineProperty(exports, "gitDeleteFile", { enumerable: true, get: function () { return repo_1.gitDeleteFile; } });
+// deprecated: use gitCreateOrEditFile
+Object.defineProperty(exports, "gitEditFile", { enumerable: true, get: function () { return repo_1.gitEditFile; } });
 // ID Management & Matter Cache
 Object.defineProperty(exports, "gitGenerateNextID", { enumerable: true, get: function () { return repo_1.gitGenerateNextID; } });
+Object.defineProperty(exports, "gitAllocateNextPRNumber", { enumerable: true, get: function () { return repo_1.gitAllocateNextPRNumber; } });
+Object.defineProperty(exports, "gitFileStrictMatter", { enumerable: true, get: function () { return repo_1.gitFileStrictMatter; } });
+Object.defineProperty(exports, "gitGetMatterCache", { enumerable: true, get: function () { return repo_1.gitGetMatterCache; } });
+Object.defineProperty(exports, "gitSetMatterCache", { enumerable: true, get: function () { return repo_1.gitSetMatterCache; } });
+// deprecated / legacy registry helpers
+// deprecated: low-level test helper only
 Object.defineProperty(exports, "gitReloadIDRegistry", { enumerable: true, get: function () { return repo_1.gitReloadIDRegistry; } });
+// deprecated: prefer gitCreateOrEditFile / gitUpdateMatter / gitRenameFile
 Object.defineProperty(exports, "gitRegisterExistingID", { enumerable: true, get: function () { return repo_1.gitRegisterExistingID; } });
+// deprecated: prefer document mutation APIs instead of pre-mutating matter
 Object.defineProperty(exports, "gitEnsureMatterID", { enumerable: true, get: function () { return repo_1.gitEnsureMatterID; } });
-Object.defineProperty(exports, "gitFileStrictMatter", { enumerable: true, get: function () { return repo_1.gitFileStrictMatter; } });
+// deprecated: avoid pre-checks, rely on gitEnsureMatterID / gitFileStrictMatter
 Object.defineProperty(exports, "gitIDRegistryExists", { enumerable: true, get: function () { return repo_1.gitIDRegistryExists; } });
+// deprecated: cache rename is handled by gitRenameFile
 Object.defineProperty(exports, "gitIDRegistryRename", { enumerable: true, get: function () { return repo_1.gitIDRegistryRename; } });
 // === GESTION DES PULL REQUESTS (repo.pr.ts) ===
 var repo_pr_1 = require("./repo.pr");
 // Synchronisation et statut
+// deprecated: prefer workflow-level sync orchestration
 Object.defineProperty(exports, "gitSyncPR", { enumerable: true, get: function () { return repo_pr_1.gitSyncPR; } });
+// deprecated: use gitIsPRClosedRobust
 Object.defineProperty(exports, "gitIsPRClosed", { enumerable: true, get: function () { return repo_pr_1.gitIsPRClosed; } });
 Object.defineProperty(exports, "gitIsPRClosedRobust", { enumerable: true, get: function () { return repo_pr_1.gitIsPRClosedRobust; } });
+// deprecated: use gitLoadPR for full metadata
 Object.defineProperty(exports, "gitGetPRMetadata", { enumerable: true, get: function () { return repo_pr_1.gitGetPRMetadata; } });
 Object.defineProperty(exports, "gitGetAllPR", { enumerable: true, get: function () { return repo_pr_1.gitGetAllPR; } });
+// deprecated: use gitGetAllPR(..., { closed: true })
 Object.defineProperty(exports, "gitGetClosedPRs", { enumerable: true, get: function () { return repo_pr_1.gitGetClosedPRs; } });
 Object.defineProperty(exports, "gitLoadPR", { enumerable: true, get: function () { return repo_pr_1.gitLoadPR; } });
 // Opérations sur les PRs
 Object.defineProperty(exports, "gitPRUpdateComments", { enumerable: true, get: function () { return repo_pr_1.gitPRUpdateComments; } });
+// deprecated: use gitClosePRRobust
 Object.defineProperty(exports, "gitClosePR", { enumerable: true, get: function () { return repo_pr_1.gitClosePR; } });
 Object.defineProperty(exports, "gitClosePRRobust", { enumerable: true, get: function () { return repo_pr_1.gitClosePRRobust; } });
-Object.defineProperty(exports, "gitGetNextPRNumber", { enumerable: true, get: function () { return repo_pr_1.gitGetNextPRNumber; } });
 Object.defineProperty(exports, "gitNewValidationRequest", { enumerable: true, get: function () { return repo_pr_1.gitNewValidationRequest; } });
+// deprecated: alias of gitNewValidationRequest
 Object.defineProperty(exports, "gitNewPR", { enumerable: true, get: function () { return repo_pr_1.gitNewPR; } });
 __exportStar(require("./git.e2e.helper"), exports);
 __exportStar(require("./git.health"), exports);

package/dist/src/rules/git/repo.d.ts

@@ -1,5 +1,5 @@
 import { SimpleGit } from 'simple-git';
-import { RulesGitConfig, GitCommitHistory, RuleUser, GitHealthStatus } from '../types';
+import { FrontMatter, RulesGitConfig, GitCommitHistory, RuleUser, GitHealthStatus } from '../types';
 /**
  * Structure du cache matter pour un fichier
  */
@@ -7,7 +7,10 @@ interface MatterStrict {
     id?: number;
     title?: string;
     service?: string;
-    oldfile?: string;
+}
+export interface GitDocumentMutationOptions {
+    config?: RulesGitConfig;
+    matter?: Partial<FrontMatter>;
 }
 /**
  * Vérifie si le fichier de registre d'IDs existe dans le repository Git
@@ -16,6 +19,9 @@ interface MatterStrict {
  * dans le repository. Le fichier `with-ids.json` est créé automatiquement lors du
  * premier appel à `gitGenerateNextID()` ou `gitEnsureMatterID()`.
  *
+ * @deprecated API utilitaire de compatibilité. Préférer la résolution via
+ * gitEnsureMatterID() / gitFileStrictMatter() sans dépendre d'un check préalable.
+ *
  * @param config Configuration Git optionnelle (utilise la config par défaut si non fournie)
  * @returns `true` si le fichier `.git/with-ids.json` existe, `false` sinon
  *
@@ -40,6 +46,33 @@ export declare function gitIDRegistryExists(config?: RulesGitConfig): boolean;
  * @returns Un nouvel ID unique
  */
 export declare function gitGenerateNextID(config?: RulesGitConfig): number;
+/**
+ * Génère le prochain numéro de PR via le registre `.git/with-ids.json`.
+ * Cette séquence est indépendante des IDs documentaires.
+ *
+ * @param config Configuration Git optionnelle
+ * @param minValue Valeur plancher du compteur PR (60 par défaut)
+ * @returns Prochain numéro de PR
+ */
+export declare function gitGenerateNextPRNumber(config?: RulesGitConfig, minValue?: number): number;
+/**
+ * Réaligne le compteur PR du registre sur une borne minimale sans allouer de numéro.
+ *
+ * @param minCounter Valeur minimale à garantir pour `lastPR`
+ * @param config Configuration Git optionnelle
+ */
+export declare function gitEnsureMinimumPRCounter(minCounter: number, config?: RulesGitConfig): void;
+/**
+ * Alloue le prochain numéro de PR en réalignant d'abord le compteur registre
+ * sur les branches de validation existantes.
+ *
+ * @param git Instance Git
+ * @param validationPrefix Préfixe des branches de validation
+ * @param config Configuration Git optionnelle
+ * @param minValue Valeur plancher du compteur PR (60 par défaut)
+ * @returns Prochain numéro de PR
+ */
+export declare function gitAllocateNextPRNumber(git: SimpleGit, validationPrefix: string, config?: RulesGitConfig, minValue?: number): Promise<number>;
 /**
  * Force le rechargement du registre d'IDs depuis le disque
  *
@@ -56,11 +89,16 @@ export declare function gitGenerateNextID(config?: RulesGitConfig): number;
  * await gitCreateOrEditFile(...); // Modifie le registre
  * gitReloadIDRegistry(); // Force le rechargement depuis le disque
  * ```
+ *
+ * @deprecated Réservé aux tests de bas niveau. Ne pas utiliser dans le workflow applicatif.
  */
 export declare function gitReloadIDRegistry(config?: RulesGitConfig): void;
 /**
  * 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é)
@@ -77,6 +115,8 @@ export declare function gitRegisterExistingID(matter: MatterStrict, branch?: str
 /**
  * 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
@@ -94,6 +134,13 @@ export declare function gitRegisterExistingID(matter: MatterStrict, branch?: str
  * ```
  */
 export declare function gitIDRegistryRename(oldFile: string, newFile: string, branch: string, config?: RulesGitConfig): void;
+export declare function gitGetMatterCache(branch: string, id: number, config?: RulesGitConfig): {
+    id?: number;
+    file?: string;
+    title?: string;
+    service?: string;
+} | undefined;
+export declare function gitSetMatterCache(branch: string, file: string, matter: MatterStrict, config?: RulesGitConfig): void;
 /**
  * Valide et assure qu'un matter a un ID valide
  *
@@ -134,7 +181,6 @@ export declare function gitEnsureMatterID(matter: MatterStrict, config?: RulesGi
 export declare function gitFileStrictMatter(git: SimpleGit, filePath: string, branch: string, config?: RulesGitConfig): Promise<{
     id?: number;
     title?: string;
-    oldfile?: string;
 }>;
 /**
  * Vérifie et configure un repository Git existant pour s'assurer qu'il a la configuration requise
@@ -214,6 +260,9 @@ export declare function gitCheckConfiguration(git?: SimpleGit): Promise<any>;
 export declare function gitCreateOrEditFile(git: SimpleGit, filePath: string, PR: string, content: string, user: RuleUser, config?: RulesGitConfig): Promise<GitCommitHistory>;
 /**
  * Modifie un fichier dans la branche draft (opération bas niveau)
+ *
+ * @deprecated Utiliser gitCreateOrEditFile() qui couvre création + édition.
+ *
  * @param git Instance Git
  * @param filePath Chemin du fichier
  * @param PR Nom de la branche de Pull Request
@@ -223,8 +272,13 @@ export declare function gitCreateOrEditFile(git: SimpleGit, filePath: string, PR
  * @throws GitOperationError si la modification échoue
  */
 export declare function gitEditFile(git: SimpleGit, filePath: string, PR: string, content: string, user: RuleUser, config?: RulesGitConfig): Promise<GitCommitHistory>;
-export declare function gitRenameFile_git(git: SimpleGit, oldFileName: string, newFileName: string, branch: string, user: RuleUser, config?: RulesGitConfig): Promise<GitCommitHistory>;
-export declare function gitRenameFile_fs(git: SimpleGit, oldFileName: string, newFileName: string, branch: string, user: RuleUser, config?: RulesGitConfig): Promise<GitCommitHistory>;
+/**
+ * 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(...)`.
+ */
+export declare function gitUpdateMatter(git: SimpleGit, filePath: string, branch: string, user: RuleUser, options?: GitDocumentMutationOptions | RulesGitConfig): Promise<GitCommitHistory>;
 /**
  * Renomme un fichier de manière atomique (Git ou filesystem selon le contexte)
  * @param git Instance SimpleGit
@@ -235,7 +289,7 @@ export declare function gitRenameFile_fs(git: SimpleGit, oldFileName: string, ne
  * @param config Configuration Git optionnelle
  * @returns Historique du commit de renommage
  */
-export declare function gitRenameFile(git: SimpleGit, oldFileName: string, newFileName: string, branch: string, user: RuleUser, config?: RulesGitConfig): Promise<GitCommitHistory>;
+export declare function gitRenameFile(git: SimpleGit, oldFileName: string, newFileName: string, branch: string, user: RuleUser, options?: GitDocumentMutationOptions | RulesGitConfig, nextContent?: string): Promise<GitCommitHistory>;
 /**
  * Supprime un fichier d'une branche Git (opération bas niveau)
  * @param git Instance Git
@@ -249,6 +303,8 @@ export declare function gitDeleteFile(git: SimpleGit, filePath: string, branch:
 /**
  * Diagnostique l'état de santé d'une branche Git et détecte les problèmes bloquants.
  *
+ * @deprecated Utiliser GitHealthManager pour les diagnostics et réparations.
+ *
  * **Problèmes bloquants détectés :**
  * - ❌ **Branche inexistante** : La branche spécifiée n'existe pas dans le dépôt
  * - ❌ **Branche inaccessible** : Impossible de faire un checkout vers la branche
@@ -272,6 +328,8 @@ export declare function gitGetBranchHealth(git: SimpleGit, branch?: string): Pro
 /**
  * Version optimisée de gitGetBranchHealth pour les branches de validation
  *
+ * @deprecated Utiliser GitHealthManager.diagnoseValidationBranches() / repairValidationBranches().
+ *
  * Cette fonction utilise une approche en cascade pour diagnostiquer rapidement
  * l'état d'une branche de validation sans effectuer de checkout coûteux.
  *