agents-gitflow-guard 0.0.26 → 0.0.27

package/README.de.md

@@ -0,0 +1,211 @@
+# agents-gitflow-guard
+
+> **Sind Sie es leid, dass KI-Agenten Ihren GitFlow umgehen?**
+
+Ein konfigurierbarer Branch-Rollen-Guard für KI-Coding-Agenten — [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH), Claude Code, Codex, OpenCode, Antigravity und Pi.  
+Sie definieren Ihre eigenen Branches — **integration** (Features werden über PR/MR zusammengeführt), **preview** (Umgebungs-Endpunkte), **production** (Produktion), **archive** (Archiv) — jeweils mit eigenen Aktualisierungsregeln. Agenten können den Flow nicht überspringen, und sensible Merges bleiben in Ihrer Hand.
+
+[English](README.md) · [简体中文](README.zh.md) · [繁體中文](README.zh-tw.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [Deutsch](README.de.md) · [Français](README.fr.md) · [Italiano](README.it.md) · [Português](README.pt.md) · [Español](README.es.md) · [Русский](README.ru.md) · [Lizenz](LICENSE)
+
+[![ko-fi](https://img.shields.io/badge/ko--fi-FF5E5B?style=flat-square&logo=ko-fi&logoColor=white)](https://ko-fi.com/keanz21)
+
+---
+
+## Inhaltsverzeichnis
+
+- [Schnellstart — In 30 Sekunden zu einem geschützten Repository](#schnellstart--in-30-sekunden-zu-einem-geschützten-repository)
+- [Warum — Das Problem, das dieses Plugin löst](#warum--das-problem-das-dieses-plugin-löst)
+- [Zielgruppe — Szenarien & Teams](#zielgruppe--szenarien--teams)
+- [Funktionen — Was es tut](#funktionen--was-es-tut)
+- [Einschränkungen — Was es NICHT tut](#einschränkungen--was-es-nicht-tut)
+- [Server-seitiger Schutz vs. dieses Plugin](#server-seitiger-schutz-vs-dieses-plugin)
+- [Funktionsweise — Der Mechanismus in drei Zeilen](#funktionsweise--der-mechanismus-in-drei-zeilen)
+- [Konfigurationsreferenz](#konfigurationsreferenz)
+- [Gate-Matrix — Was blockiert wird, was durchgelassen wird](#gate-matrix--was-blockiert-wird-was-durchgelassen-wird)
+- [Menschliche Kontrolle — Wo der Entwickler die Kontrolle behält](#menschliche-kontrolle--wo-der-entwickler-die-kontrolle-behält)
+- [Installation im Detail](#installation-im-detail)
+- [FAQ](#faq)
+- [Glossar](#glossar)
+- [Roadmap](#roadmap)
+- [Unterstützung](#unterstützung)
+- [Entwicklung](#entwicklung)
+- [Lizenz](#lizenz)
+
+---
+
+## Schnellstart — In 30 Sekunden zu einem geschützten Repository
+
+**Schritt 1 — Installieren.** Alle sechs Clients verwenden dasselbe npm-Paket `agents-gitflow-guard` — wählen Sie Ihren Client:
+
+```bash
+# DSH — In-Process-Plugin (DSH danach neu starten; Plugins werden beim Start geladen)
+dsh plugin --profile web add agents-gitflow-guard
+```
+
+```bash
+# Claude Code · Codex · OpenCode · Antigravity — Eigenständige Hooks (kein DSH erforderlich)
+npm i -g agents-gitflow-guard
+```
+
+```bash
+# Pi — In-Process-Erweiterung
+npm i -D agents-gitflow-guard
+```
+
+> **Hinweis**: Ein einfaches `add` oder `npm i` installiert die neueste Version aus der npm-Registry. Falls Ihr Registry-Spiegel Cache-Verzögerungen aufweist oder Sie eine feste Version benötigen, hängen Sie `@<version>` an (z. B. `npm i -g agents-gitflow-guard@<version>`). (DSH-Benutzer: Die pnpm Peer-Dependency-*Warnung* ist normal — DSH stellt `@deepseek-ai/cordis` / `@deepseek-ai/dsh-tools` beim Start bereit; das Plugin funktioniert regulär.)
+>
+> Die Hook-basierten Clients (Claude Code · Codex · OpenCode · Antigravity) erfordern nach der Installation einen einzigen Verdrahtungs-Befehl (**ein Befehl pro Client**, siehe unten). Pi benötigt das Kopieren einer Datei. DSH wird bei der Installation automatisch eingebunden.
+
+**Schritt 2 — Client verdrahten (keine Konfigurationsdatei erforderlich).** Der Guard bringt **integrierte Standardeinstellungen mit, die `develop` (Integration) + `main` (Archiv) schützen** — null Konfigurationsaufwand, standardmäßig aktiv. Sie müssen Ihrem KI-Client lediglich mitteilen, den Guard aufzurufen:
+
+```bash
+# Claude Code → .claude/settings.json dieses Repositories
+gitflow-guard wire --client claude --project --yes
+```
+
+```bash
+# Codex / OpenCode / Antigravity (jeweils eigene Konfigurationsdatei; --yes überspringt die Bestätigung)
+gitflow-guard wire --client codex --project --yes
+gitflow-guard wire --client opencode --project --yes
+gitflow-guard wire --client antigravity --project --yes
+```
+
+```bash
+# Vorschau (ohne Schreiben) / Entfernen / Interaktiver Assistent:
+gitflow-guard wire --client claude --dry-run
+gitflow-guard wire --client claude --unwire
+gitflow-guard setup
+```
+
+`wire` fügt den Hook **zerstörungsfrei** in Ihre bestehende Konfiguration ein (vorhandene Hooks bleiben unberührt) und schreibt standardmäßig in das **Projektverzeichnis**. `--global` (für alle Repositories auf diesem Rechner) erfordert immer eine Bestätigung oder `--yes`. Die genauen Pfade und Formate finden Sie unter [Installation im Detail](#installation-im-detail).
+
+> ⚠️ **main ist standardmäßig geschützt.** Entwickler, die Trunk-basiert arbeiten (direkter Push auf einen einzigen Branch), werden bei direkten Pushes auf `main` blockiert, bis sie den Guard deaktivieren — erstellen Sie dazu eine `gitflow-guard.config.json` mit `{ "enabled": false }` oder definieren Sie eigene Branch-Zuordnungen (siehe [Konfigurationsreferenz](#konfigurationsreferenz)). `gitflow-guard status` weist darauf hin, wenn die Standardeinstellungen aktiv sind.
+
+**Schritt 3 — Überprüfen.** Weisen Sie den Agenten an, `git push origin develop` auszuführen. Der Aufruf wird blockiert:
+
+```text
+Error: [gitflow-guard] blocked: Protected branch "develop" forbids direct push
+Next: Integration branch (develop) is updated via PR/MR from a feature branch: push the feature first, then `gh pr create --base develop` / `glab mr create --target-branch develop`.
+```
+
+Nachrichten werden standardmäßig auf Englisch ausgegeben; über `"locale": "zh"` kann auf Chinesisch gewechselt werden (siehe [Konfigurationsreferenz](#konfigurationsreferenz)).
+
+**Fertig.** Der Guard ist mit den Standardeinstellungen aktiv. Für weitere Stages (`preview` / `production`) oder andere Branch-Namen erstellen Sie einfach eine `gitflow-guard.config.json` mit den gewünschten Feldern. Die vollständige Entscheidungstabelle finden Sie in der [Gate-Matrix](#gate-matrix--was-blockiert-wird-was-durchgelassen-wird).
+
+---
+
+## Warum — Das Problem, das dieses Plugin löst
+
+KI-Coding-Agenten arbeiten direkt in Ihrem Repository. Ihnen wird über System-Prompts und Projektdateien (`AGENTS.md`, `CLAUDE.md` etc.) mitgeteilt, wie der Branching-Flow aussieht.
+
+**Dies sind jedoch weiche Regeln.** Agenten überspringen oder „vergessen“ diese Regeln gelegentlich — nicht aus böser Absicht, sondern weil Textanweisungen für ein Sprachmodell unverbindlich sind.
+
+Dieses Plugin verwandelt weiche Anweisungen in **harte Mechanismen**. Jede Git-Operation wird vor der Ausführung gegen den tatsächlichen lokalen Repository-Zustand geprüft. Verstöße werden blockiert, bevor der Befehl ausgeführt wird.
+
+Niemand muss sich Regeln merken — die Regeln werden technisch durchgesetzt.
+
+---
+
+## Zielgruppe — Szenarien & Teams
+
+- Sie haben einen definierten Branch-Flow (von einem einfachen `develop`-Zweig bis zu mehrstufigen Preview/Production-Pipelines).
+- Ein Agent hat bereits einmal direkt auf einen geschützten Branch gepusht oder unerlaubt gemergt.
+- Sie möchten Branch-Schutz nicht rein menschlicher Aufmerksamkeit überlassen.
+- Mehrere Features werden parallel entwickelt und in geteilten Umgebungen zusammengeführt.
+
+---
+
+## Funktionen — Was es tut
+
+- **Blockiert vor der Ausführung**: Direkte Pushes, Force-Pushes und Löschungen geschützter Branches (integration / preview / production / archive) sowie Agenten-Merges in production/archive.
+- **Rollenbasiert & flexibel konfigurierbar**: `integration` (Standard: `develop`) als Kernrolle; `preview`, `production`, `archive` optional konfigurierbar.
+- **Menschliche Freigabe (Merge-by-user)**: Merges in Produktions- und Archiv-Branches sind Agenten verwehrt — nur der Klick des Entwicklers im PR führt den Merge durch.
+- **Vollständiges Audit-Log**: Jeder abgewiesene Befehl wird in `~/.local/state/gitflow-guard/` protokolliert — außerhalb des Repositories und manipulationssicher.
+- **Plattformunabhängig**: Arbeitet rein mit lokalem Git; unterstützt optional `gh` (GitHub) oder `glab` (GitLab).
+
+---
+
+## Einschränkungen — Was es NICHT tut
+
+- **Keine absolute Sicherheitsgrenze**: Die Befehlsanalyse basiert auf Heuristiken. Absichtlich stark verschleierte Befehle können die Textanalyse umgehen.
+- **Kein Ersatz für Server-Branch-Protection**: Echter Schutz im Team gehört zusätzlich in die GitHub/GitLab-Einstellungen.
+- **Kein Ersatz für den Workflow selbst**: Das Repository muss mindestens einen `integration`-Branch aufweisen.
+
+---
+
+## Konfigurationsreferenz
+
+### Standardeinstellungen & Deep-Merge
+
+Der Guard ist **ohne Konfigurationsdatei standardmäßig aktiv**:
+
+| Standard | Rolle | Regel |
+|---|---|---|
+| `develop` | **integration** | Kein direkter Push; Aktualisierung über PR/MR (`update: "pr"`) |
+| `main` | **archive** | Kein direkter Push / kein Agenten-Merge (`mergeBy: "user"`) |
+
+Benutzerdefinierte Felder in `gitflow-guard.config.json` überschreiben die Standardwerte per **Deep-Merge**:
+
+```jsonc
+{
+  "enabled": true,
+  "featurePattern": "feature/[\\w-]+",
+  "branches": {
+    "integration": ["develop"],
+    "preview": ["staging", "preview-[\\w-]+"],
+    "production": { "branches": ["prod"], "update": "pr", "mergeBy": "user" },
+    "archive": ["main"]
+  }
+}
+```
+
+---
+
+## Gate-Matrix — Was blockiert wird, was durchgelassen wird
+
+| Agenten-Aktion | Entscheidung |
+|---|---|
+| commit / push auf Feature-Branch / sync / rebase | ✅ allow (erlaubt) |
+| Direkter push / force-push / Löschen von integration / preview / production / archive | 🚫 block (blockiert) |
+| PR/MR: Feature → integration / preview | ✅ allow (erlaubt) |
+| PR/MR: Feature → production | ✅ Erstellung erlaubt; **Merge blockiert** (Entwickler führt Merge aus) |
+| PR/MR → archive | ✅ Erstellung erlaubt; 🚫 **Merge blockiert** (Entwickler führt Merge aus) |
+| Lokales `git merge feature/x` auf integration / preview | 🚫 block (PR/MR erforderlich; `update: flexible` erlaubt es) |
+| Verkettete Befehle (`checkout develop && merge feature/x`) | 🚫 block (Branch-Wechsel wird pro Segment simuliert) |
+| Erzwingen des Zurücksetzens geschützter Branches (`git checkout -B/-C`) | 🚫 block (ref-update Gate) |
+| `git symbolic-ref` Änderungen auf geschützten Branches | 🚫 block (ref-update Gate) |
+| `git cherry-pick` / `git revert` auf geschützten Branches | 🚫 block (Verlaufsänderung auf geschütztem Branch verhindert) |
+| Mit `sudo` gewrappte Git-Befehle | 🚫 Wrapper wird entfernt (`sudo -u …` inkl.) und Git-Befehl geprüft |
+
+---
+
+## Installation im Detail
+
+**Voraussetzung**: **Node.js ≥ 22** auf Ihrem `PATH`.
+
+```bash
+# Global installieren
+npm i -g agents-gitflow-guard
+
+# Client konfigurieren (Wire)
+gitflow-guard wire --client claude --project --yes
+gitflow-guard wire --client codex --project --yes
+gitflow-guard wire --client opencode --project --yes
+gitflow-guard wire --client antigravity --project --yes
+```
+
+---
+
+## FAQ
+
+### Kann ich abweichende Branch-Namen verwenden?
+Ja. Branch-Namen sind vollständig frei wählbar und werden über `gitflow-guard.config.json` definiert.
+
+### Blockiert das Plugin meine normale Entwicklungsarbeit?
+Nein. Sämtliche reguläre Feature-Branch-Arbeiten (Commits, Pushes, Rebase, Tests) laufen ohne jede Einschränkung.
+
+---
+
+## Lizenz
+
+[MIT](LICENSE) © FeatureAgents

package/README.es.md

@@ -0,0 +1,137 @@
+# agents-gitflow-guard
+
+> **¿Cansado de que los agentes de IA ignoren tu GitFlow?**
+
+Un guardián configurable para roles de ramas Git, diseñado para agentes de programación de IA — [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH), Claude Code, Codex, OpenCode, Antigravity y Pi.  
+Define tus propias ramas — **integration** (las funcionalidades se integran mediante PR/MR), **preview** (entornos de prueba), **production** (producción), **archive** (archivo) — cada una con sus propias reglas de actualización. Los agentes no pueden eludir el flujo y los merges críticos permanecen bajo tu control humano.
+
+[English](README.md) · [简体中文](README.zh.md) · [繁體中文](README.zh-tw.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [Deutsch](README.de.md) · [Français](README.fr.md) · [Italiano](README.it.md) · [Português](README.pt.md) · [Español](README.es.md) · [Русский](README.ru.md) · [Licencia](LICENSE)
+
+[![ko-fi](https://img.shields.io/badge/ko--fi-FF5E5B?style=flat-square&logo=ko-fi&logoColor=white)](https://ko-fi.com/keanz21)
+
+---
+
+## Índice
+
+- [Inicio Rápido — 30 segundos para proteger tu repositorio](#inicio-rápido--30-segundos-para-proteger-tu-repositorio)
+- [Por qué — El problema que resuelve este plugin](#por-qué--el-problema-que-resuelve-este-plugin)
+- [Para quién es — Escenarios y equipos](#para-quién-es--escenarios-y-equipos)
+- [Qué hace — Capacidades](#qué-hace--capacidades)
+- [Qué NO hace — Límites](#qué-no-hace--límites)
+- [Protección del lado del servidor vs este plugin](#protección-del-lado-del-servidor-vs-este-plugin)
+- [Cómo funciona — El mecanismo en tres líneas](#cómo-funciona--el-mecanismo-en-tres-líneas)
+- [Referencia de Configuración](#referencia-de-configuración)
+- [Matriz de Decisión — Qué se bloquea y qué se permite](#matriz-de-decisión--qué-se-bloquea-y-qué-se-permite)
+- [Dónde el humano mantiene el control](#dónde-el-humano-mantiene-el-control)
+- [Instalación Detallada](#instalación-detallada)
+- [Preguntas Frecuentes (FAQ)](#preguntas-frecuentes-faq)
+- [Glosario](#glosario)
+- [Hoja de Ruta (Roadmap)](#hoja-de-ruta-roadmap)
+- [Soporte](#soporte)
+- [Desarrollo](#desarrollo)
+- [Licencia](#licencia)
+
+---
+
+## Inicio Rápido — 30 segundos para proteger tu repositorio
+
+**Paso 1 — Instalación.** Los seis clientes utilizan el mismo paquete npm `agents-gitflow-guard`:
+
+```bash
+# DSH — Plugin en proceso (reiniciar DSH después de la instalación)
+dsh plugin --profile web add agents-gitflow-guard
+```
+
+```bash
+# Claude Code · Codex · OpenCode · Antigravity — Hooks autónomos (sin necesidad de DSH)
+npm i -g agents-gitflow-guard
+```
+
+```bash
+# Pi — Extensión en proceso
+npm i -D agents-gitflow-guard
+```
+
+**Paso 2 — Conectar el cliente (sin necesidad de archivo de configuración).** El plugin viene con **valores predeterminados integrados que protegen `develop` (integración) + `main` (archivo)** — activado por defecto con cero configuración:
+
+```bash
+# Claude Code → .claude/settings.json de este repositorio
+gitflow-guard wire --client claude --project --yes
+```
+
+```bash
+# Codex / OpenCode / Antigravity (archivos dedicados por cliente)
+gitflow-guard wire --client codex --project --yes
+gitflow-guard wire --client opencode --project --yes
+gitflow-guard wire --client antigravity --project --yes
+```
+
+```bash
+# Vista previa sin escribir / Desinstalación / Asistente interactivo:
+gitflow-guard wire --client claude --dry-run
+gitflow-guard wire --client claude --unwire
+gitflow-guard setup
+```
+
+`wire` inserta la configuración de forma **no destructiva** en tus archivos existentes.
+
+> ⚠️ **main está protegido por defecto.** Para flujos de tipo Trunk-based, desactiva el guard estableciendo `{ "enabled": false }` en `gitflow-guard.config.json`.
+
+**Paso 3 — Verificación.** Pide al agente que ejecute `git push origin develop`. La operación será bloqueada:
+
+```text
+Error: [gitflow-guard] blocked: Protected branch "develop" forbids direct push
+Next: Integration branch (develop) is updated via PR/MR from a feature branch: push the feature first, then `gh pr create --base develop` / `glab mr create --target-branch develop`.
+```
+
+---
+
+## Por qué — El problema que resuelve este plugin
+
+Los agentes de programación de IA trabajan directamente en tu repositorio. Las instrucciones en prompts y archivos de documentación (`AGENTS.md`, `CLAUDE.md`, etc.) son **reglas flexibles**: los modelos pueden ignorarlas u olvidarlas.
+
+Este plugin transforma reglas de texto en **mecanismos rígidos de sistema**. Cada comando Git intentado por el agente es interceptado y validado contra el estado real del repositorio local antes de su ejecución.
+
+---
+
+## Qué hace — Capacidades
+
+- **Bloqueo previo a la ejecución**: Push directo, force push y eliminación de ramas protegidas (integration, preview, production, archive) se bloquean antes de ejecutarse.
+- **Merge exclusivo por humanos (Merge-by-user)**: Los agentes pueden crear PR/MR hacia producción o archivo, pero el merge efectivo está reservado al usuario.
+- **Registro de auditoría seguro**: Cada denegación se registra en `~/.local/state/gitflow-guard/` fuera del repositorio.
+
+---
+
+## Matriz de Decisión — Qué se bloquea y qué se permite
+
+| Acción del Agente | Decisión |
+|---|---|
+| commit / push en rama feature / sync / rebase | ✅ allow (permitido) |
+| Push directo / force push / eliminación en integration / preview / production / archive | 🚫 block (bloqueado) |
+| Creación de PR/MR: feature → integration / preview | ✅ allow (permitido) |
+| Creación de PR/MR: feature → production | ✅ Creación permitida; **Merge bloqueado** (el usuario realiza el merge) |
+| Creación de PR/MR → archive | ✅ Creación permitida; 🚫 **Merge bloqueado** (el usuario realiza el merge) |
+| `git merge feature/x` local en integration / preview | 🚫 block (PR/MR obligatorio) |
+| Comandos encadenados (`checkout develop && merge feature/x`) | 🚫 block (simulación por segmento) |
+| `git checkout -B` / `git switch -C` hacia ramas protegidas | 🚫 block |
+| Comandos Git ejecutados con `sudo` | 🚫 Envoltura eliminada y comando subyacente validado |
+
+---
+
+## Instalación Detallada
+
+**Requisito previo**: **Node.js ≥ 22** en tu `PATH`.
+
+```bash
+npm i -g agents-gitflow-guard
+gitflow-guard wire --client claude --project --yes
+gitflow-guard wire --client codex --project --yes
+gitflow-guard wire --client opencode --project --yes
+gitflow-guard wire --client antigravity --project --yes
+```
+
+---
+
+## Licencia
+
+[MIT](LICENSE) © FeatureAgents

package/README.fr.md

@@ -0,0 +1,138 @@
+# agents-gitflow-guard
+
+> **Vous en avez assez que les agents IA contournent votre GitFlow ?**
+
+Un garde-fou configurable pour les rôles de branches Git, conçu pour les agents de codage IA — [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH), Claude Code, Codex, OpenCode, Antigravity et Pi.  
+Définissez vos propres branches — **integration** (les fonctionnalités sont intégrées via PR/MR), **preview** (environnements de test), **production**, **archive** — chacune avec ses propres règles. Les agents ne peuvent pas contourner le processus et les fusions sensibles restent sous contrôle humain.
+
+[English](README.md) · [简体中文](README.zh.md) · [繁體中文](README.zh-tw.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [Deutsch](README.de.md) · [Français](README.fr.md) · [Italiano](README.it.md) · [Português](README.pt.md) · [Español](README.es.md) · [Русский](README.ru.md) · [Licence](LICENSE)
+
+[![ko-fi](https://img.shields.io/badge/ko--fi-FF5E5B?style=flat-square&logo=ko-fi&logoColor=white)](https://ko-fi.com/keanz21)
+
+---
+
+## Table des matières
+
+- [Démarrage rapide — 30 secondes pour protéger un dépôt](#démarrage-rapide--30-secondes-pour-protéger-un-dépôt)
+- [Pourquoi — Le problème résolu par ce plugin](#pourquoi--le-problème-résolu-par-ce-plugin)
+- [Pour qui — Cas d'usage et équipes](#pour-qui--cas-dusage-et-équipes)
+- [Fonctionnalités — Ce que fait le plugin](#fonctionnalités--ce-que-fait-le-plugin)
+- [Ce que le plugin ne fait PAS — Limites](#ce-que-le-plugin-ne-fait-pas--limites)
+- [Protection côté serveur vs ce plugin](#protection-côté-serveur-vs-ce-plugin)
+- [Fonctionnement — Le mécanisme en trois lignes](#fonctionnement--le-mécanisme-en-trois-lignes)
+- [Référence de configuration](#référence-de-configuration)
+- [Matrice de décision — Ce qui est bloqué ou autorisé](#matrice-de-décision--ce-qui-est-bloqué-ou-autorisé)
+- [Le contrôle reste humain](#le-contrôle-reste-humain)
+- [Installation détaillée](#installation-détaillée)
+- [Foire aux questions (FAQ)](#foire-aux-questions-faq)
+- [Glossaire](#glossaire)
+- [Feuille de route](#feuille-de-route)
+- [Support](#support)
+- [Développement](#développement)
+- [Licence](#licence)
+
+---
+
+## Démarrage rapide — 30 secondes pour protéger un dépôt
+
+**Étape 1 — Installation.** Les six clients utilisent le même paquet npm `agents-gitflow-guard` :
+
+```bash
+# DSH — Plugin interne au processus (redémarrer DSH après installation)
+dsh plugin --profile web add agents-gitflow-guard
+```
+
+```bash
+# Claude Code · Codex · OpenCode · Antigravity — Hooks autonomes (sans DSH)
+npm i -g agents-gitflow-guard
+```
+
+```bash
+# Pi — Extension interne
+npm i -D agents-gitflow-guard
+```
+
+> **Remarque** : Une commande standard installe la dernière version. Pour figer une version spécifique, ajoutez `@<version>` (ex: `npm i -g agents-gitflow-guard@<version>`).
+
+**Étape 2 — Connexion du client (aucun fichier de configuration requis).** Le plugin intègre des **valeurs par défaut qui protègent `develop` (intégration) + `main` (archive)** — activé d'office avec zéro configuration :
+
+```bash
+# Claude Code → .claude/settings.json de ce dépôt
+gitflow-guard wire --client claude --project --yes
+```
+
+```bash
+# Codex / OpenCode / Antigravity (fichiers de configuration dédiés)
+gitflow-guard wire --client codex --project --yes
+gitflow-guard wire --client opencode --project --yes
+gitflow-guard wire --client antigravity --project --yes
+```
+
+```bash
+# Aperçu sans écriture / Désinstallation / Assistant interactif :
+gitflow-guard wire --client claude --dry-run
+gitflow-guard wire --client claude --unwire
+gitflow-guard setup
+```
+
+`wire` insère la configuration de façon **non destructive** dans vos fichiers existants.
+
+> ⚠️ **main est protégé par défaut.** Pour les flux de type Trunk-based (où tout le monde pousse sur une branche unique), désactivez le garde avec `{ "enabled": false }` dans `gitflow-guard.config.json`.
+
+**Étape 3 — Vérification.** Demandez à l'agent d'exécuter `git push origin develop`. L'opération sera bloquée :
+
+```text
+Error: [gitflow-guard] blocked: Protected branch "develop" forbids direct push
+Next: Integration branch (develop) is updated via PR/MR from a feature branch: push the feature first, then `gh pr create --base develop` / `glab mr create --target-branch develop`.
+```
+
+---
+
+## Pourquoi — Le problème résolu par ce plugin
+
+Les agents IA de codage travaillent directement dans votre dépôt. Les instructions dans les fichiers Markdown (`AGENTS.md`, `CLAUDE.md`, etc.) sont des **règles souples** : les modèles peuvent les ignorer ou les oublier.
+
+Ce plugin transforme les consignes textuelles en **mécanismes rigides**. Toute commande Git exécutée par l'agent est interceptée et validée par rapport à l'état réel du dépôt local avant exécution.
+
+---
+
+## Fonctionnalités — Ce que fait le plugin
+
+- **Blocage pré-exécution** : Pousser directement, forcer le push ou supprimer des branches protégées (integration, preview, production, archive) est bloqué.
+- **Fusion par l'humain uniquement (Merge-by-user)** : Les agents peuvent créer des PR/MR vers la production et l'archive, mais la fusion effective est réservée à l'humain.
+- **Journal d'audit inviolable** : Chaque refus est consigné dans `~/.local/state/gitflow-guard/` en dehors du dépôt.
+
+---
+
+## Matrice de décision — Ce qui est bloqué ou autorisé
+
+| Action de l'agent | Décision |
+|---|---|
+| commit / push sur branche feature / rebase / sync | ✅ allow (autorisé) |
+| Push direct / force push / suppression sur integration / preview / production / archive | 🚫 block (bloqué) |
+| Création de PR/MR : feature → integration / preview | ✅ allow (autorisé) |
+| Création de PR/MR : feature → production | ✅ Création autorisée ; **Fusion bloquée** (réservée à l'humain) |
+| Création de PR/MR → archive | ✅ Création autorisée ; 🚫 **Fusion bloquée** (réservée à l'humain) |
+| `git merge feature/x` localement sur integration / preview | 🚫 block (PR/MR requis) |
+| `git checkout -B` / `git switch -C` ciblant une branche protégée | 🚫 block |
+| Commandes Git encapsulées dans `sudo` | 🚫 Enveloppe retirée et commande sous-jacente vérifiée |
+
+---
+
+## Installation détaillée
+
+**Prérequis** : **Node.js ≥ 22** dans votre `PATH`.
+
+```bash
+npm i -g agents-gitflow-guard
+gitflow-guard wire --client claude --project --yes
+gitflow-guard wire --client codex --project --yes
+gitflow-guard wire --client opencode --project --yes
+gitflow-guard wire --client antigravity --project --yes
+```
+
+---
+
+## Licence
+
+[MIT](LICENSE) © FeatureAgents

package/README.it.md

@@ -0,0 +1,137 @@
+# agents-gitflow-guard
+
+> **Sei stanco che gli agenti IA ignorino il tuo GitFlow?**
+
+Un guardiano configurabile per i ruoli dei branch Git, progettato per gli agenti di sviluppo IA — [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH), Claude Code, Codex, OpenCode, Antigravity e Pi.  
+Definisci i tuoi branch — **integration** (le funzionalità vengono integrate tramite PR/MR), **preview** (ambienti di test), **production** (produzione), **archive** (archivio) — ciascuno con le proprie regole di aggiornamento. Gli agenti non possono saltare il flusso e i merge critici rimangono sotto il tuo controllo.
+
+[English](README.md) · [简体中文](README.zh.md) · [繁體中文](README.zh-tw.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [Deutsch](README.de.md) · [Français](README.fr.md) · [Italiano](README.it.md) · [Português](README.pt.md) · [Español](README.es.md) · [Русский](README.ru.md) · [Licenza](LICENSE)
+
+[![ko-fi](https://img.shields.io/badge/ko--fi-FF5E5B?style=flat-square&logo=ko-fi&logoColor=white)](https://ko-fi.com/keanz21)
+
+---
+
+## Indice
+
+- [Guida rapida — 30 secondi per proteggere il repository](#guida-rapida--30-secondi-per-proteggere-il-repository)
+- [Perché — Il problema risolto da questo plugin](#perché--il-problema-risolto-da-questo-plugin)
+- [Per chi è pensato — Scenari e team](#per-chi-è-pensato--scenari-e-team)
+- [Funzionalità — Cosa fa il plugin](#funzionalità--cosa-fa-il-plugin)
+- [Cosa NON fa — Limiti](#cosa-non-fa--limiti)
+- [Protezione lato server vs questo plugin](#protezione-lato-server-vs-questo-plugin)
+- [Come funziona — Il meccanismo in tre righe](#come-funziona--il-meccanismo-in-tre-righe)
+- [Riferimento configurazione](#riferimento-configurazione)
+- [Matrice decisionale — Cosa viene bloccato e cosa consentito](#matrice-decisionale--cosa-viene-bloccato-e-cosa-consentito)
+- [Il controllo umano](#il-controllo-umano)
+- [Installazione dettagliata](#installazione-dettagliata)
+- [Domande frequenti (FAQ)](#domande-frequenti-faq)
+- [Glossario](#glossario)
+- [Tabella di marcia](#tabella-di-marcia)
+- [Supporto](#supporto)
+- [Sviluppo](#sviluppo)
+- [Licenza](#licenza)
+
+---
+
+## Guida rapida — 30 secondi per proteggere il repository
+
+**Passo 1 — Installazione.** Tutti e sei i client utilizzano lo stesso pacchetto npm `agents-gitflow-guard`:
+
+```bash
+# DSH — Plugin in-process (riavviare DSH dopo l'installazione)
+dsh plugin --profile web add agents-gitflow-guard
+```
+
+```bash
+# Claude Code · Codex · OpenCode · Antigravity — Hook autonomi (senza DSH)
+npm i -g agents-gitflow-guard
+```
+
+```bash
+# Pi — Estensione in-process
+npm i -D agents-gitflow-guard
+```
+
+**Passo 2 — Configurazione del client (nessun file di configurazione richiesto).** Il plugin include **valori predefiniti integrati per proteggere `develop` (integrazione) + `main` (archivio)** — attivo per impostazione predefinita senza alcuna configurazione iniziale:
+
+```bash
+# Claude Code → .claude/settings.json di questo repository
+gitflow-guard wire --client claude --project --yes
+```
+
+```bash
+# Codex / OpenCode / Antigravity (file dedicati per ciascun client)
+gitflow-guard wire --client codex --project --yes
+gitflow-guard wire --client opencode --project --yes
+gitflow-guard wire --client antigravity --project --yes
+```
+
+```bash
+# Anteprima senza scrittura / Rimozione / Configurazione guidata:
+gitflow-guard wire --client claude --dry-run
+gitflow-guard wire --client claude --unwire
+gitflow-guard setup
+```
+
+`wire` applica le modifiche in modo **non distruttivo** ai file di configurazione esistenti.
+
+> ⚠️ **main è protetto per impostazione predefinita.** Per i flussi di tipo Trunk-based, disattiva il plugin impostando `{ "enabled": false }` in `gitflow-guard.config.json`.
+
+**Passo 3 — Verifica.** Chiedi all'agente di eseguire `git push origin develop`. L'operazione verrà bloccata:
+
+```text
+Error: [gitflow-guard] blocked: Protected branch "develop" forbids direct push
+Next: Integration branch (develop) is updated via PR/MR from a feature branch: push the feature first, then `gh pr create --base develop` / `glab mr create --target-branch develop`.
+```
+
+---
+
+## Perché — Il problema risolto da questo plugin
+
+Gli agenti IA lavorano direttamente nel repository. Le istruzioni nei prompt di sistema e nei file di progetto (`AGENTS.md`, `CLAUDE.md`, ecc.) sono **regole flessibili**: i modelli possono dimenticarle o ignorarle.
+
+Questo plugin trasforma le regole testuali in **vincoli rigidi di sistema**. Ogni comando Git tentato dall'agente viene intercettato e verificato rispetto allo stato reale del repository locale prima dell'esecuzione.
+
+---
+
+## Funzionalità — Cosa fa il plugin
+
+- **Blocco pre-esecuzione**: Push diretti, force push e cancellazioni su branch protetti (integration, preview, production, archive) vengono bloccati prima dell'esecuzione.
+- **Merge riservato all'umano (Merge-by-user)**: Gli agenti possono creare PR/MR verso la produzione o l'archivio, ma il merge effettivo è riservato all'utente.
+- **Audit log protetto**: Tutte le operazioni respinte vengono registrate in `~/.local/state/gitflow-guard/` al di fuori del repository.
+
+---
+
+## Matrice decisionale — Cosa viene bloccato e cosa consentito
+
+| Azione dell'agente | Decisione |
+|---|---|
+| commit / push su branch feature / sync / rebase | ✅ allow (consentito) |
+| Push diretto / force push / cancellazione su integration / preview / production / archive | 🚫 block (bloccato) |
+| Creazione PR/MR: feature → integration / preview | ✅ allow (consentito) |
+| Creazione PR/MR: feature → production | ✅ Creazione consentita; **Merge bloccato** (eseguito dall'utente) |
+| Creazione PR/MR → archive | ✅ Creazione consentita; 🚫 **Merge bloccato** (eseguito dall'utente) |
+| `git merge feature/x` locale su integration / preview | 🚫 block (PR/MR richiesto) |
+| Comandi concatenati (`checkout develop && merge feature/x`) | 🚫 block (simulazione per segmento) |
+| `git checkout -B` / `git switch -C` verso branch protetti | 🚫 block |
+| Comandi Git eseguiti con `sudo` | 🚫 Wrapper rimosso e comando sottostante verificato |
+
+---
+
+## Installazione dettagliata
+
+**Prerequisiti**: **Node.js ≥ 22** nel tuo `PATH`.
+
+```bash
+npm i -g agents-gitflow-guard
+gitflow-guard wire --client claude --project --yes
+gitflow-guard wire --client codex --project --yes
+gitflow-guard wire --client opencode --project --yes
+gitflow-guard wire --client antigravity --project --yes
+```
+
+---
+
+## Licenza
+
+[MIT](LICENSE) © FeatureAgents