Dépôt canonique Forge et récupération de commits¶

Document opérationnel. Verrouille la procédure de contrôle du dépôt
de travail avant tout ticket Forge, et la procédure officielle de
récupération si des commits ont été faits hors du dépôt canonique
(projet généré, clone temporaire, environnement WSL secondaire…).

Audience : contributeurs (humains et agents IA) qui s'apprêtent à
ouvrir un ticket Forge ou à porter des commits faits par erreur dans un
autre dépôt.

Origine : ticket GIT-RECOVERY-WORKFLOW-GUARD-001, après la release
1.0.0-beta.11, plusieurs tickets ont été commités par erreur dans un
projet généré WSL (~/Projets/forge-test-b11) avant d'être portés par
patchs dans le dépôt canonique. Cette page rend la procédure officielle
et reproductible.

1. Dépôt canonique Forge¶

Le seul dépôt de référence pour le framework Forge est :

Champ	Valeur attendue
Chemin local	`/home/roger/Projets/Forge`
Branche par défaut	`main` (ou une branche ticket issue de `main`)
Remote `origin` (fetch et push)	`git@github.com:caucrogeGit/Forge.git`
Working tree	propre avant démarrage d'un ticket

Tout commit Forge doit être créé dans ce dépôt. Aucun travail sur le
framework ne doit être effectué dans :

un projet généré par forge new (présence d'un dossier mvc/ à plat
sans la structure complète du dépôt framework) ;
un dossier nommé forge-test-*, forge-beta*, forge-sandbox-* ;
un clone temporaire posé dans /tmp/, un WSL secondaire, une VM
d'essai ;
toute branche master (Forge utilise main exclusivement).

2. Checklist pré-ticket¶

À exécuter avant d'écrire la moindre ligne d'un nouveau ticket :

pwd
git status --short
git branch --show-current
git remote -v
git log -3 --oneline

Critères pour valider le dépôt courant comme Forge canonique :

pwd contient /home/roger/Projets/Forge ;
la branche courante est main ou une branche ticket (port/...,
ticket/...) explicitement créée à partir de main ;
origin pointe sur git@github.com:caucrogeGit/Forge.git (fetch
et push) ;
le working tree est propre (git status --short ne retourne rien).

Si l'un des critères n'est pas rempli, arrêter immédiatement.
Ne pas continuer le ticket. Soit corriger le contexte (changer de
dossier, basculer de branche, nettoyer le working tree), soit suivre la
procédure de récupération de la section 4 si des commits ont déjà été
créés hors du dépôt canonique.

3. Signes d'un mauvais dépôt¶

Indicateurs qui doivent déclencher un arrêt immédiat :

branche courante = master (Forge n'utilise pas master) ;
commit initial du type « based on Forge … » ou « generated by
forge new » (c'est un projet généré, pas le framework) ;
chemin courant sous forge-test-*, forge-sandbox-*, /tmp/ ;
git remote -v ne fait pas apparaître caucrogeGit/Forge.git (ou
pointe vers un fork, un mirror ou un dépôt local) ;
présence d'un dossier mvc/ sans les dossiers core/,
cli/, packages/, tests/, docs/ côte à côte (signe
caractéristique d'un projet généré : seul mvc/ est extrait).

Dans tous ces cas, on n'est pas dans Forge canonique. Les
modifications faites ici ne seront pas reflétées dans la release
publique du framework tant qu'elles n'auront pas été portées
explicitement.

4. Procédure officielle de récupération¶

À appliquer si des commits ont été faits par erreur dans un dépôt
secondaire (projet généré, WSL local, clone temporaire) et doivent être
portés dans Forge canonique.

4.1 Ne pas continuer dans le mauvais dépôt¶

Premier réflexe : arrêter d'ajouter des commits dans le dépôt
fautif. Continuer ne ferait qu'augmenter la dette à porter et le risque
de divergence.

4.2 Exporter les commits avec `git format-patch`¶

Dans le dépôt source (le mauvais) :

git format-patch <base>..<head> -o /tmp/forge-recovery-patches

<base> est le dernier commit présent aussi dans Forge canonique
(souvent origin/main au moment où le dépôt secondaire a été créé).
<head> est HEAD ou la branche locale fautive.

Les éventuels changements non commités (WIP) doivent être exportés
séparément (par exemple via git diff > /tmp/forge-recovery-patches/wip.patch)
et ne pas être appliqués automatiquement à l'étape 4.6, ils sont
revus manuellement.

4.3 Copier les patchs vers la machine canonique¶

Adapter l'hôte / l'utilisateur selon l'environnement :

scp /tmp/forge-recovery-patches/*.patch \
    roger@192.168.1.222:/tmp/forge-recovery-patches/

4.4 Créer une branche de portage dans Forge canonique¶

cd /home/roger/Projets/Forge
git switch main
git status --short                # doit être vide
git switch -c port/recovery-$(date +%Y%m%d)

Le préfixe port/recovery-YYYYMMDD rend la branche identifiable comme
branche de portage temporaire.

4.5 Vérifier chaque patch avec `git apply --check`¶

Patch par patch, dans l'ordre d'export :

git apply --check /tmp/forge-recovery-patches/0001-xxx.patch

Si git apply --check échoue (conflits, contexte introuvable, fichiers
absents), ne pas forcer. Relire le patch, comprendre la divergence,
adapter manuellement.

4.6 Appliquer avec `git am` les patchs validés¶

git am /tmp/forge-recovery-patches/0001-xxx.patch

git am préserve auteur, date et message original. Les patchs WIP
ne sont pas appliqués automatiquement : ils sont relus à la main,
recoupés en commits propres, puis intégrés via des commits explicites.

4.7 Valider avec les contrôles canoniques¶

Avant la fusion dans main, lancer les cinq validations Forge :

.venv/bin/python -m pytest -x -q
.venv/bin/python -m compileall -q .
.venv/bin/python -m ruff check .
.venv/bin/python -m mkdocs build --strict
git diff --check

Pour un portage purement documentaire, restreindre la suite pytest à
tests/meta (plus rapide) est acceptable, à condition que les commits
portés ne touchent que de la documentation et des tests méta.

4.8 Fusionner en fast-forward dans `main`¶

git switch main
git merge --ff-only port/recovery-$(date +%Y%m%d)

Le --ff-only garantit qu'il n'y a pas de commit de merge implicite
qui obscurcirait l'historique. Si le fast-forward échoue, c'est que
main a divergé pendant le portage, rebaser la branche de portage sur
main à jour, refaire les validations, puis retenter.

4.9 Pousser¶

git push origin main

Vérifier ensuite que les commits attendus apparaissent bien dans le log
distant.

5. Interdits explicites¶

Pendant une récupération, jamais :

merger directement un projet généré dans Forge canonique
(git merge <chemin-vers-projet-généré>), la structure ne
correspond pas ;
copier-coller un gros diff manuel sans audit patch par patch ;
appliquer un patch WIP automatiquement (git am wip.patch), le WIP
est revu à la main et recoupé en commits explicites ;
continuer un ticket si le dépôt courant est ambigu (échec d'un seul
critère de la section 2) ;
travailler depuis un dossier forge-test-*, forge-sandbox-*,
/tmp/ ou un projet généré pour modifier le core Forge ;
supprimer les patchs /tmp/forge-recovery-patches/ avant que les
commits portés soient poussés et confirmés sur origin/main.

6. Pour aller plus loin¶

Conventions internes de Forge, patterns
opérationnels (audit avant action, tests, code, doc).
Vue d'ensemble du contributeur, préparation
de l'environnement, sélection du ticket, validations canoniques.
Procédure de release, pour les tags officiels,
qui ne sont jamais créés depuis un dépôt secondaire.
CLAUDE.md (racine du dépôt), briefing IA, mentionne cette page
comme étape 0 obligatoire avant tout ticket.