install-maintenance-graft-rtk-ponytail-lite

Prompt

# Installation et Maintenance Vérifiées — Graft + RTK + Ponytail lite

Vous travaillez dans le dépôt actuel pour installer, mettre à jour, réparer,
ou vérifier cette stack :

- Graft : compréhension du code, graphe local, et enrichissement LSP.
- RTK : réduction du bruit dans le terminal.
- Ponytail : politique lite, avec intégration native quand compatible.

Commencez par un inventaire en lecture seule. Puis posez les questions manquantes ci-dessous.
Après les réponses, effectuez les opérations autorisées jusqu'aux vérifications finales.

Ne commencez pas l'installation avant d'avoir déterminé les clients et le périmètre.
Ne redemandez pas une décision déjà prise dans cette conversation.

## 1. Inventaire, puis choix utilisateur

### Inventaire sans modification

Identifiez :

- OS, architecture, shell, environnement : machine locale, WSL, SSH, conteneur ;
- racine du dépôt, worktree, statut Git et opérations Git en cours ;
- chemins réels, versions, et méthode d'installation de Git, Node, npm,
  RTK, Graft, et clients disponibles ;
- Claude Code, Codex, Kimi, Cursor Agent CLI, et Cursor IDE séparément ;
- Gemini, Copilot CLI, ou autres clients déjà présents comme cibles optionnelles ;
- répertoires de configuration effectivement utilisés, variables de redirection,
  et tout orchestrateur tel que AgentsRoom ;
- configurations existantes utilisateur, projet, plugin, et hooks hérités.

Vérifiez l'identité de `agent` avant de le considérer comme Cursor.
Un binaire présent ne prouve pas l'authentification, le fonctionnement des hooks,
ou le chargement MCP.

Ne lancez pas de mises à jour automatiques, connexions, ou installations durant cet inventaire.
Ne publiez aucune valeur secrète.

Présentez un tableau court :
Client | Binaire/version | Configuration effective | Statut connu.

### Questions à poser en une seule fois

Posez uniquement les questions dont la réponse manque :

1. Opération :
   - Installer les composants manquants et garder des versions compatibles.
   - Mettre à jour la stack vers des versions stables vérifiées.
   - Réparer l'installation existante en conservant ses versions.
   - Vérifier seulement, sans modification.

2. Clients :
   - Tous les clients détectés.
   - Une sélection parmi la liste effectivement détectée.
   - Préparer aussi la configuration pour certains clients absents.

3. Périmètre d'intégration :
   - Projet partagé : configurations portables destinées au dépôt.
   - Projet personnel : activation pour ce dépôt, fichiers locaux non versionnés.
   - Utilisateur global : activation pour les projets de cet utilisateur.
   - Mixte : choix distinct par client ou composant.

Si le périmètre est mixte, demandez uniquement les clarifications nécessaires.

Pour une mise à jour, demandez aussi toute contrainte de version si non déjà connue.
Sinon, proposez des versions stables explicites.

N'installez ni ne mettez à jour les applications clientes elles-mêmes :
l'opération concerne Graft, RTK, Ponytail, et leurs dépendances nécessaires.
Un client obsolète est signalé avec la version requise et l'action restante.

### Rendre les choix concrets

Avant d'écrire, affichez le résultat prévu :

Composant/client | Version cible | Périmètre | Fichiers ciblés | Effet partagé | Repli

Expliquez notamment :

- Un exécutable installé au niveau utilisateur peut servir plusieurs dépôts.
- Mettre à jour cet exécutable affecte tous ses utilisateurs locaux.
- Un plugin peut avoir un cache global mais une activation par projet.
- Un hook par projet peut néanmoins utiliser un état partagé.
- L'index Graft reste spécifique au dépôt/worktree.
- Une configuration globale fournie par un orchestrateur peut être isolée
  à un projet : vérifiez son périmètre réel, pas seulement son nom.

Une fois les choix obtenus, procédez sans confirmations répétées.
Demandez une nouvelle décision seulement si une limitation nécessite
une extension de périmètre ou un changement matériel de solution.

## 2. Règles d'exécution

Ordre :
inventaire → choix → sauvegardes → RTK → Graft/LSP → Ponytail →
instructions → vérifications → rapport.

Respectez les instructions du dépôt et les politiques administrées.
Si un fichier est géré par AgentsRoom ou un autre orchestrateur,
utilisez son mécanisme officiel ; ne modifiez pas directement ses fichiers générés.

Avant chaque modification :

- validez le format ET la structure des configurations JSON/JSONC/TOML ;
- sauvegardez les fichiers affectés hors du dépôt, avec accès restreint ;
- enregistrez versions et éléments nécessaires au retour arrière ;
- relisez le dry-run de l'installateur quand il existe.

Un fichier invalide ne doit jamais être remplacé par une configuration vide.

Fusionnez les configurations en préservant les autres MCP, hooks, permissions,
instructions, commentaires quand possible, et lignes de statut.
Ne changez pas les règles d'approbation ni les empreintes de confiance.

Préservez les modifications Git préexistantes. Pas de commit, push, reset,
clean, stash, ni modification du code applicatif.
En cas de conflit non résolu ou d'opération Git en cours, suspendez
les écritures dans le dépôt ; continuez les diagnostics indépendants.

N'installez pas Graphify, CodeGraph, Caveman, ou Headroom.
Une ancienne intégration conflictuelle est supprimée seulement après identification précise,
sauvegarde, et dans le périmètre autorisé.
Ne désinstallez pas globalement un outil utilisé ailleurs.

Une erreur bloque ses étapes dépendantes, pas d'autres clients indépendants.
Ne déclarez pas une étape réussie pour contourner une limitation.

## 3. Capacités et périmètre : vérifier avant de configurer

Consultez l'aide des versions installées et les documents correspondant
aux versions publiées que vous utiliserez :

- https://github.com/rtk-ai/rtk
- https://github.com/trailhq/Graft
- https://github.com/DietrichGebert/ponytail
- documentation officielle de chaque client sélectionné.

La branche main/develop peut décrire des fonctionnalités absentes d'une release.
Pour une option douteuse, vérifiez la release, l'aide, ou le code livré.

Établissez pour chaque intégration :

Client | Hooks projet disponibles | Installateur compatible |
Périmètre d'activation | Périmètre d'état | Preuve

Ne confondez pas :
"le client accepte les hooks projet"
et "l'installateur de cet outil sait les installer au niveau projet."

Points de contrôle à reverifier dans les versions présentes :

- Claude : paramètres utilisateur, projet partagé et projet local.
- Cursor : hooks utilisateur et projet ; tester IDE et CLI séparément.
- Codex : configurations utilisateur/projet et activation des plugins ;
  vérifier les mécanismes de hook réellement disponibles.
- Kimi : ne pas supposer une configuration de hook par projet ;
  distinguer configuration utilisateur, instructions projet et options de lancement.
- Gemini/Copilot : vérifier leurs propres mécanismes si sélectionnés.

Si l’installateur ne respecte pas la portée demandée :

1. Chercher une option officielle appropriée.
2. Sinon, utiliser une configuration manuelle documentée du même adaptateur,
   uniquement si son protocole et ses chemins restent compatibles.
3. Sinon, utiliser un repli par instructions/prefixe explicite.
4. Ne jamais basculer silencieusement vers global.

Inspecter les hooks globaux hérités avant d’ajouter leurs équivalents locaux :
ils peuvent s’accumuler au lieu de se remplacer.
Préserver les hooks de sécurité. Signaler les effets globaux qui restent actifs.

## 4. RTK

Vérifier l’origine `rtk-ai/rtk`, la version, l’aide, la configuration
et `rtk gain`. Un échec de `gain` peut venir de la base ou des permissions :
cela n’est pas une preuve suffisante d’un mauvais package.

Installer ou mettre à jour avec le gestionnaire déjà utilisé, si approprié.
Vérifier l’origine de la formule ou du package et la version obtenue.
Éviter les installations concurrentes et les modifications PATH inutiles.
Ne pas lancer aveuglément `cargo install rtk`.

Consulter `rtk init --help` pour la version choisie.
Sélectionner les options par client et portée ; ne pas copier systématiquement
`-g` d’un exemple de documentation.

Ne pas supposer que l’intégration Codex est toujours une instruction simple,
ni qu’elle a toujours un hook : cela dépend de la version RTK.
Vérifier aussi les incompatibilités entre options d’initialisation.

Dans la configuration effectivement lue, fusionner les exclusions :

    [hooks]
    exclude_commands = ["graft", "curl", "playwright"]

Préserver les exclusions existantes et vérifier leur prise en compte.
Si ce paramètre est global, indiquer cet effet avant de le modifier.
Désactiver la télémétrie optionnelle par le mécanisme documenté,
dans la portée autorisée.

RTK est le seul composant autorisé à réécrire les commandes shell.
Les hooks de sécurité, audit et approbation restent applicables.

Ne pas copier un hook Claude dans un autre client sans compatibilité documentée.
Sans réécriture effective, configurer le préfixe explicite `rtk`.
Éviter les hooks doubles et les préfixes doubles.

## 5. Graft avec LSP

### Installation et confidentialité

Vérifier l’identité du package `@nanonets/graft`, sa version publiée
et ses exigences Node.

Installer en dehors des dépendances de l’application, dans un emplacement adapté.
Ne pas modifier package.json ni le fichier de verrouillage du projet pour installer Graft.

Appliquer `DO_NOT_TRACK=1` dès le premier lancement et dans le MCP.
Utiliser la commande officielle de désactivation de la télémétrie si disponible.

Ne pas activer Brain, compte, enrichissement LLM, ni `--deep`.
Ne pas promettre zéro réseau sans vérification.

Ne pas lancer automatiquement `graft init`.
Favoriser un câblage explicite ; son installateur peut écrire hors du dépôt.

### LSP vraiment opérationnel

Avant d’explorer le code de l’application, respecter les règles Graft du dépôt.
Puis identifier les langages utiles et consulter les intégrations LSP
de la version Graft choisie.

Réutiliser les serveurs compatibles déjà présents.
Installer uniquement les serveurs nécessaires, avec versions enregistrées,
hors dépendances d’application quand possible.

Vérifier :

- l’exécutable et sa version ;
- sa disponibilité dans le PATH du processus Graft/MCP ;
- les prérequis langage et espace de travail ;
- son support par cette version Graft.

Après lecture de l’aide, utiliser notamment, si ces options sont disponibles :

    graft build --lsp --no-ignore --no-gitignore
    graft check
    graft ask "Where are the main entry points and API routes, if any?" --source

Appliquer DO_NOT_TRACK à ces commandes avec la syntaxe shell actuelle.

Vérifier la signification des options : dans certaines versions,
`--no-ignore` et `--no-gitignore` empêchent l’écriture de fichiers d’exclusion ;
ils ne signifient pas « indexer les fichiers ignorés ».

Gérer explicitement l’exclusion Git de `/graft/` selon la portée choisie.
Vérifier avec Git. Ne pas supprimer automatiquement des fichiers déjà suivis.
Préserver annotations et contenu humain.

Une construction avec `--lsp` et un code de sortie 0 ne prouve pas l’usage de LSP.
Chercher une preuve ciblée : serveur effectivement lancé, résultat de résolution,
arêtes enrichies ou diagnostics documentés.

Rapporter par langage :
LSP vérifié / disponible sans enrichissement observé / indisponible / non supporté.

Ne jamais charger tout le graphe ou wiring.json dans le contexte.
Vérifier aussi si l’enrichissement LSP persiste après un rafraîchissement automatique ;
sinon, documenter la reconstruction explicite nécessaire.

### MCP et fraîcheur

Configurer une seule entrée Graft effective par client.
Découvrir le fichier, le schéma et la portée effectivement supportés.

Pour chaque serveur, vérifier :
commande installée, arguments MCP, DO_NOT_TRACK, PATH et répertoire de travail.

Ne pas supposer qu’un fichier `.kimi-code/mcp.json`, `.mcp.json` ou autre est chargé automatiquement : confirmer le mécanisme client ou l’option de lancement nécessaire.

Une configuration MCP globale est acceptable uniquement si le processus cible adresse correctement chaque dépôt. Sinon, garder le MCP au niveau projet.

Ne pas utiliser `npx -y ...@latest` à chaque démarrage.
Ne pas versionner des chemins personnels absolus ou secrets.
Ne pas inventer une variable universelle `${workspaceFolder}`.

Dans ce profil, ne pas ajouter de hooks Graft.
Pas de smart-grep, grep-redirect ou interception shell Graft.

Vérifier le rafraîchissement et l’absence de désactivation involontaire.
Un rafraîchissement raté interdit de présenter le graphe comme frais.

Inspecter les anciennes intégrations et métadonnées d’auto-câblage avant migration.
Ne supprimer que les éléments identifiés et sauvegardés.
Vérifier qu’ils ne réapparaissent pas après démarrage et requête MCP.

### Statistiques Graft

Opération, usage observé et collecte de statistiques séparés.

Selon la version, `graft stats` dépend des hooks de session.
Sans ces hooks, le message « aucune session enregistrée pour l'instant » peut apparaître malgré des requêtes Graft réussies.

Ne fabriquez pas de statistiques ni ne lancez `graft init` pour faire disparaître ce message.

Si l'utilisateur a besoin de statistiques natives, exposez la compatibilité des hooks de mesure disponibles et demandez explicitement l'évolution du profil sans hooks avant toute activation.

## 6. Ponytail lite

Privilégiez une intégration officielle compatible avec le client et le scope.
Vérifiez son manifeste, ses événements et ses dépendances.

Distinguez :
installation du plugin, activation, mode par défaut et état du mode actuel.

Inspectez les sources réellement lues :
configuration, `PONYTAIL_DEFAULT_MODE`, état persistant et données du plugin.
`defaultMode: lite` ne prouve pas qu'un ancien état complet a été remplacé.

Si le mode est partagé entre plusieurs conversations, indiquez-le.
Dans le scope projet, ne changez pas silencieusement le mode global par défaut.
Utilisez un mécanisme local documenté ou la politique lite par instructions.

Par client :

- Claude/Codex : installation et activation officielles au scope disponible.
  Vérifiez les sous-commandes avant de les utiliser.
  Les approbations de hooks restent à la charge de l'utilisateur.
- Cursor : adaptateur officiel, ou règle d'instruction ; évitez leur accumulation.
  Si `scripts/cursor-hooks.js install --project` existe, lancez le script
  depuis la racine du dépôt cible en utilisant le chemin officiel de checkout.
  Sans `--project`, vérifiez la destination utilisateur.
  Inspectez les chemins générés : un hook projet contenant un chemin absolu
  vers un checkout personnel n'est pas portable et ne doit pas être commis.
- Kimi : cherchez un adaptateur officiel compatible. Sinon, politique lite
  dans AGENTS.md ; ajoutez une compétence locale minimale seulement si utile
  et si son format et son chargement sont confirmés.
  Identifiez-le comme une adaptation, sans promettre de commandes ou stats natives.
- Autres clients sélectionnés : appliquez la même vérification, sans transposer automatiquement
  les événements Claude/Codex.

Gardez le checkout de l'adaptateur à une version ou un commit identifié.
Ne faites pas de git pull sur un checkout modifié.
N'ajoutez pas de barre de statut ou d'indicateur visuel.

Testez le mode effectif dans une nouvelle session.

## 7. Instructions communes compactes

Fusionnez un bloc délimité par :

    <!-- agent-stack:start -->
    ...
    <!-- agent-stack:end -->

dans AGENTS.md. Préservez tout contenu externe et les ajouts humains.
Ne copiez pas cette invite d'installation dans les instructions de l'agent.

Le bloc doit exprimer :

### Graft

Pour comprendre ou modifier le code, commencez par une exploration de l'application :
`graft ask "<question précise>" --source`, ou l'outil MCP Graft effectivement exposé.

Instructions, compétences, Git, configurations et découverte MCP peuvent précéder.
Après orientation, lisez directement les portions utiles.
Pour les appelants, utilisez les commandes/outils de trace disponibles.

En cas de graphe obsolète : vérifiez, reconstruction adaptée avec LSP, puis nouvelle requête.
Après une recherche infructueuse : grep ciblé graft, puis lecture directe
ou rg borné avec explication de la limite.

Un fichier fourni, une trace de pile, une configuration ou un langage non indexé
permettent une lecture ciblée directe.
L'absence dans le graphe ne prouve pas l'absence de code ou d'appelants.

Après modifications : graft blast, base Git vérifiée, et tests pertinents.
Pas de --name, pas de chargement complet du graphe.
Signalez le nombre réel d'appels et toute erreur.

### RTK

Hook vérifié : laissez la réécriture agir sans double préfixe.
Sinon : préfixez explicitement les commandes compatibles.
Ne passez jamais Graft via RTK.

Pour sortie complète : rappelez --full si disponible, ou proxy.
Ne relancez pas automatiquement une commande avec effets de bord.
Préservez pipelines et redirections.

Avant validation : diffs réels non compressés, diff --cached,
diff --check et inspection séparée des nouveaux fichiers.
Pas de staging automatique.

### Ponytail lite

Implémentez correctement la demande et réutilisez l'existant.
Rapportez brièvement une solution significativement plus simple.
Préservez validation, sécurité, permissions, accessibilité, transactions
et tests nécessaires. Vérifiez les usages avant suppression ou intégration.

Complet uniquement sur demande explicite, jamais ultra par défaut.
Un audit ne déclenche pas une refonte.
La correction prime pour sécurité, parseurs, concurrence et migrations.

Ne prétendez pas qu'un mode partagé est local à une conversation.
Après un full autorisé, vérifiez le retour au mode lite.
Off ne supprime pas les instructions déjà injectées.

### Chargement

Confirmez comment chaque client charge effectivement ces instructions.
Utilisez des imports/adaptateurs minimaux documentés.
Évitez duplications et imports circulaires.

RTK reste le seul réécrivain de shell.
Pas de hook Graft dans ce profil.

## 8. Mise à jour et réparation

La même invite doit pouvoir être relancée sans doublons.

En mode mise à jour :

1. Relisez les choix de scope et l'état précédemment vérifié.
2. Comparez versions installées, versions cibles et changements incompatibles.
3. Sauvegardez avant toute migration.
4. Mettez à jour uniquement les composants sélectionnés.
5. Rafraîchissez plugins/adaptateurs avec leur mécanisme officiel.
6. Réévaluez les capacités : un ancien fallback peut être remplacé
   par une intégration native désormais disponible, dans le même scope.
7. Migrez uniquement les clés et blocs appartenant à cette stack.
8. Reconstruisez le graphe si nécessaire et revérifiez le LSP.
9. Redémarrez les processus MCP/client nécessaires :
   un processus existant peut encore exécuter l'ancienne version.
10. Rejouez contrôles et tests des intégrations modifiées.

Ne réinstallez pas inutilement un composant déjà conforme.
Ne lancez pas une mise à jour générale des paquets de la machine.

En mode réparation, conservez les versions sauf incompatibilité démontrée
et décision explicite de mise à jour.

Préparez un rollback ciblé : versions précédentes, sauvegardes,
et commandes exactes. Ne restaurez pas aveuglément un fichier entier
si d'autres modifications ont eu lieu depuis sa sauvegarde.

Une seconde exécution sans changements demandés ne doit créer
aucun hook, serveur MCP, ni section d'instructions dupliquée.

## 9. Contrôles et preuves

Testez séparément :

- Exécution RTK et compression explicite ;
- déclenchement automatique des hooks, exclusions et passage brut ;
- Graft : fraîcheur, résultat correspondant au dépôt, et enrichissement LSP ;
- MCP : serveur fonctionnel ET chargement effectif dans chaque client ;
- Ponytail : activation et mode effectif ;
- absence de doublons et auto-câblage réapparu ;
- validité finale des configurations et portée effective.

Un fichier présent n’est pas une preuve de chargement.
Une sonde MCP externe n’est pas une preuve de chargement dans le client.
Un préfixe RTK explicite n’est pas une preuve de hook automatique.

Pour chaque client disponible et authentifié, ouvrir une nouvelle session
dans le dépôt, avec ses protections habituelles, et fournir ce ticket neutre :

"Sans modifier le code, localisez les points d’entrée principaux.
S’il y a une API, indiquez où ses routes sont montées et tracez
un chemin vers la logique métier. Citez fichiers et lignes."

Ne pas ajouter « use Graft ».
Inspecter les appels d’outils visibles, pas le raisonnement interne.
Conserver des preuves minimales et censurer les données sensibles.

Si approbation, connexion ou action UI manquante :
NON TESTÉ / ACTION UTILISATEUR, jamais succès supposé.

## 10. Livrable

Dans le périmètre autorisé, conserver une courte documentation de maintenance :

- choix d’opération, clients et périmètre ;
- versions exactes, origine et date de vérification ;
- mécanismes de configuration et limites ;
- reconstruction Graft/LSP ;
- procédure de mise à jour, vérification et retour arrière.

Pour une installation partagée, utiliser `docs/agent-stack.md`.
Pour une installation personnelle/globale, garder les informations spécifiques à la machine
hors des fichiers versionnés.
En mode vérification seule, livrer le rapport sans créer ces fichiers.

Rapporter les commandes décisives, leurs résultats, fichiers modifiés,
sauvegardes et actions utilisateur exactes.

Inventorier les hooks finaux :
client, origine, périmètre, événement, matcher, rôle et commande censurée.

Terminer par :

Client/version | Périmètre effectif | Configuration présente |
MCP chargé | Graft observé à la première exploration |
LSP | RTK | Ponytail | Preuve/action restante

Utiliser des états explicites :
CONFIGURÉ / CHARGÉ / USAGE OBSERVÉ / NON TESTÉ / BLOQUÉ / NON APPLICABLE.

Classer les fichiers :
À COMMITTER APRÈS REVUE / À IGNORER / CONFIGURATION MACHINE.

Les chemins personnels, secrets, caches, graphes, sauvegardes et transcriptions
ne doivent pas être inclus dans les fichiers à committer.

Afficher le statut Git final et les changements introduits par cette intervention,
distinguant ceux-ci des modifications préexistantes. Ne rien committer.

Tags