# Rebase Playbook

Checklist operativa per rebase tracciabili tra `git-node` e Mantis.

## 1) Rebase Preflight

Prima di avviare un rebase:

1. Verifica stato working tree con `git_query` `action: "status"`.
2. Verifica il branch di partenza **senza** usare `current_branch`: usa la sequenza supportata `git_query` `action: "status"` (campo branch) + conferma con `git_query` `action: "history"` oppure `git_query` `action: "repo_info"`.
3. Acquisisci baseline commit (HEAD corrente + target base) con `git_query` `action: "history"`.
4. Conferma relazione di ancestry dove rilevante (`git_query` `action: "check_ancestor"`).
5. Se il branch e condiviso o ad alto rischio, annota nel ticket Mantis la finestra operativa prevista.

Output minimo consigliato nel log/nota:

* branch corrente
* commit HEAD pre-rebase
* branch/commit di destinazione
* eventuali file locali non tracciati o modificati

## 2) Semantic Conflicts (oltre al conflitto testuale)

Anche quando Git non segnala conflitti, verifica possibili conflitti semantici:

* **Contract/API drift**: firme o payload cambiati in modo compatibile sintatticamente ma incompatibile a runtime.
* **Behavior drift**: logica equivalente nel diff ma ordine di esecuzione o side effect diversi.
* **Data/SQL drift**: query ancora valide ma semanticamente errate rispetto a schema/migrazioni correnti.
* **Config/feature flag drift**: default o toggle cambiati che alterano comportamento.
* **Doc/Test drift**: test o documentazione non piu allineati alla serie rebased.

Per ridurre rischio:

1. usa `git_diff` `action: "range_diff"` su serie originale vs rebased;
2. isola commit con delta sospetto (`only_left`/`only_right` o patch molto diversa);
3. fai handoff alla skill di dominio (SQL/CFML/UI) quando il conflitto e logico e non solo sintattico;
4. registra nel ticket decisioni e tradeoff non ovvi.

## 3) Post-Rebase Verification

Dopo il rebase, completa verifiche minime prima di dichiarare equivalenza:

1. `git_query` `action: "status"` deve risultare pulito (salvo modifiche intenzionali).
2. `git_query` `action: "history"` per confermare nuova linearizzazione.
3. `git_diff` `action: "range_diff"` tra serie pre e post rebase.
4. Smoke test locali o check rapidi applicabili al dominio toccato.
5. Aggiornamento nota Mantis con:
   * nuovo HEAD
   * esito range-diff
   * test/check eseguiti
   * eventuali rischi residui.

### 3.1 Rebase parziale da "prima commit utile"

Quando l'utente indica una commit soglia e chiede di considerare prod/base per tutto cio' che precede:

1. verifica che la commit soglia sia risolvibile e appartenga alla serie originale (`check_ancestor` o `merge-base --is-ancestor`);
2. conserva come `original_range` la serie da `<commit_soglia>^..branch_origine`;
3. durante il rebase, salta le commit precedenti alla soglia e non risolvere semanticamente conflitti di quella parte, salvo file manifest/label che il progetto considera cumulativi;
4. se devi modificare `git-rebase-todo`, evita editor/manual copy: usa l'helper solo su todo lineari, in `dry_run` prima della scrittura; l'helper deve rifiutare todo strutturali da `--rebase-merges` (`label`, `reset`, `merge`) e riscrivere UTF-8 senza BOM riportando quante righe sono state eliminate;
5. dopo il rebase confronta `original_range` con `target_base..HEAD`, ma interpreta merge commit e commit generate come eccezioni motivate, non come regressioni automatiche.

### 3.2 File `.properties`: manifest generati vs risorse cumulative

Non trattare tutti i `.properties` allo stesso modo:

* `update/updates.properties` e manifest checksum simili sono generati: se l'utente dice "prendi prod", ripristina il lato base/prod e salta la commit di rebuild se resta vuota.
* `labels.*.properties`, `messages.*.properties`, `pagetitle.*.properties` e risorse i18n sono cumulative: in caso di conflitto unisci le chiavi dei due rami, preservando le modifiche non equivalenti di entrambi.
* prima di chiudere, verifica che le risorse cumulative non abbiano perso chiavi rispetto alla serie originale utile.

### 3.3 Regressioni senza conflitto testuale

Il rebase puo' perdere modifiche anche senza conflitti. Esegui almeno questi controlli quando `range-diff` mostra coppie `!` o path rinominati:

1. confronta i file toccati dalla serie originale utile, escludendo solo i manifest generati concordati;
2. usa rename detection e controlla i rename solo di case (`scm_createOrder.cfc` -> `scm_createorder.cfc`), frequenti su Windows;
3. se un file ha path diverso ma contenuto atteso, confronta gli hash/blob tra `origin:path` e working tree;
4. per valori puntuali sospetti usa pickaxe (`git log -S "valore" -- <path>`) per identificare la commit che li ha introdotti;
5. se trovi una regressione nel working tree, dichiarala esplicitamente e lascia la correzione non committata o committata solo su richiesta.

## 4) Stop Condition per Review Umana

Interrompi automazione e richiedi review umana quando si verifica almeno una condizione:

* `range_diff` mostra divergenze sostanziali non spiegabili rapidamente.
* conflitti su aree critiche (migrazioni DB, sicurezza, billing, autorizzazioni, data-loss risk).
* non e possibile provare equivalenza comportamentale con test/smoke disponibili.
* rebase coinvolge commit di piu autori con intenzioni in conflitto.
* il ticket Mantis contiene requisiti ambigui o contraddittori rispetto al codice reale.

Formato consigliato per escalation nel ticket:

* **Motivo stop**: perche il flusso automatico non e affidabile.
* **Evidenza**: commit/range/file coinvolti.
* **Decisione richiesta**: cosa deve confermare il reviewer umano.
* **Impatto temporale**: blocco totale o parziale del delivery.