Codebase Trellis
Structure, soutien et intégration sécurisée des modifications de code assistées par IA.
Écosystème :
codebase-orientcomprend la base de code.codebase-visualizecartographie la base de code.codebase-trellissoutient la croissance et l'intégration sécurisées des modifications.
Quand utiliser cette compétence
Utilisez cette compétence quand
- Des fichiers ont changé et nécessitent un staging sécurisé, une planification de commit, ou une exécution de commit.
- Une branche ou un worktree doit être créé, terminé ou nettoyé.
- Un push, une PR ou un état CI nécessite une inspection ou une préparation.
- La posture du dépôt Git/GitHub nécessite un audit.
- Une session d'agent de longue durée a besoin d'une revue d'état structurée avant de continuer.
- L'arbre de travail est sale et la prochaine étape appropriée n'est pas claire.
Ignorez cette compétence quand
- La tâche est une petite correction connue d'un seul fichier, sans incertitude sur l'état Git.
- Une exploration en lecture seule est en cours et aucun travail de commit/push/nettoyage n'est prévu.
- Une autre compétence (
codebase-orient,codebase-visualize) vient d'être invoquée et aucun travail Git ne suit.
Classification simple vs structurée
Classez chaque invocation avant d'exécuter tout workflow.
Passe simple :
- correction de bogue localisée
- modification de documentation ou de copie uniquement
- mise à jour de dépendance
- petit refactoring
- modification de test uniquement
- préparation de commit déjà cadré
Passe structurée :
- modification large de plusieurs fichiers
- multiples paquets
- UI plus API plus tests
- migration ou fichiers générés
- travail d'agent de longue durée
- plusieurs commits attendus
- reprise ou transfert probable
Par défaut, choisissez simple en cas de doute. Passez à structuré si l'inspection révèle que le travail est plus important qu'il n'y paraît. Ne rétrogradez jamais de structuré une fois que l'état de sécurité a été établi.
Couches d'application
Trellis fonctionne dans un modèle de sécurité à 4 couches. Ces couches ne sont pas équivalentes et aucune couche ne se substitue à une autre.
Couche 1 : Discipline de la compétence (couche de base v1)
La compétence inspecte, signale et verrouille les opérations risquées. Fonctionne dans tout dépôt Git normal sans hooks supplémentaires ni accès GitHub. Il s'agit d'un comportement — cela dépend du respect de la compétence par l'agent.
Couche 2 : Hooks Git locaux
Les hooks locaux au dépôt peuvent s'exécuter lors du commit ou du push. Treillis peut recommander des hooks mais ne les exige ni ne les installe dans v1. Les hooks peuvent être manquants, contournés avec --no-verify, ou non partagés entre clones.
Couche 3 : Hooks Claude Code
Les hooks au niveau de l'hôte peuvent agir autour de l'utilisation des outils, des modifications de fichiers et des permissions. Renforcement optionnel uniquement — pas requis pour le cœur autonome. Ne supposez pas qu'ils sont installés.
Couche 4 : Protections GitHub
Application côté GitHub : protection de branche, ensembles de règles, vérifications requises, revues requises, commits signés, restrictions de force-push, file d'attente de merge, scan de secrets, scan de code, Dependabot. Inspectez et signalez lorsque l'accès API le permet ; ne supposez jamais que les protections existent.
Règle de non-équivalence :
- La discipline de la compétence n'est pas un hook.
- Un hook local n'est pas une protection de branche GitHub.
- Un grep local réussi n'est pas un scan de secrets.
- Les vérifications de tête de PR ne sont pas des vérifications de file d'attente de merge.
- Une coche verte visible n'est pas une preuve que toutes les vérifications requises ont réussi pour le SHA concerné.
Si une couche est indisponible ou non vérifiée, dites-le clairement.
Limite d'interopérabilité
Cœur autonome
Codebase Trellis doit fonctionner dans tout dépôt Git normal sans nécessiter d'artefacts de compétences sœurs. Il possède :
- Inspection de l'état Git et de l'état sale
- Détection des modifications staged, unstaged, untracked, ignorées, générées, sensibles et préexistantes
- Regroupement de commits et transfert de plan de commit
- Sécurité des branches/worktrees
- Verrous push/PR/CI
- Règles de nettoyage
- Sortie du rapport Trellis
Lectures consultatives optionnelles
Si des artefacts de compétences sœurs existent, Trellis peut les lire à titre de contexte consultatif uniquement.
De codebase-orient (exemples : docs/ai/CODEBASE_MAP.md, docs/ai/CHANGE_SURFACES.md, docs/ai/OPEN_QUESTIONS.md) :
- disposition du dépôt et structure des paquets/espaces de travail
- vérifications connues et politique relative aux documents générés
- conventions importantes et zones dangereuses
De codebase-visualize (exemples : docs/ai/visualize/codebase-graph.json) :
- rayon d'explosion et modules affectés
- arêtes doc-à-code et fichiers à haute centralité
Règles :
- N'exigez pas ces fichiers.
- Ne les régénérez pas.
- Ne les modifiez pas silencieusement.
- Ne bloquez pas la planification de routine des commits en raison de l'absence de visualisation.
- Ne les traitez pas comme plus autoritaires que les documents source/config/canoniques.
Déclencheurs de transfert
- Suggérez
/codebase-orientlorsque la structure du dépôt n'est pas claire, que les vérifications connues sont inconnues, ou que l'agent manque de contexte suffisant pour classer le risque. - Suggérez
/codebase-visualizelorsque l'impact des modifications est large ou architectural, que les relations de dépendance sont importantes, ou que le rayon d'explosion améliorerait la décision.
Règles universelles
Toujours :
- Commencez par identifier la racine du dépôt, la branche et l'état sale.
- Montrez l'état avant de proposer des commandes.
- Séparez les fichiers staged, unstaged, untracked, supprimés et ignorés.
- Traitez les fichiers partiellement staged comme ambigus et risqués.
- Excluez les fichiers sensibles de tous les plans de commit.
- Préférez des listes de fichiers exactes aux commandes de chemin larges.
- Arrêtez-vous en cas d'échec de commande.
- Dites quand
ghest indisponible ou manque d'autorisation. - Gardez les rapports courts et exploitables.
- Rapportez ce qui est connu et ce qui est inconnu ; ne transformez pas les inconnues en sécurité supposée.
Jamais :
- Exécutez
git add .sans approbation explicite de la liste exacte des fichiers. - Commitez sans montrer les fichiers planifiés et le message de commit.
- Pushez dans le cadre du commit.
- Mergez dans le cadre du push.
- Utilisez
git push --force. - Inférez
--force-with-lease; il doit être explicitement demandé. - Supprimez des branches sans confirmation écrite du nom de la branche.
- Supprimez des worktrees non créés par cette session ou qui ne sont pas clairement des worktrees jetables locaux au projet.
- Incluez
.env, des clés, des jetons, des identifiants ou des fichiers ignorés dans un plan de commit. - Affirmez que les tests, CI ou paramètres GitHub ont réussi sans vérification.
- Affirmez "aucun secret" ou "aucune vulnérabilité" à partir d'un simple grep local ou de vérifications visibles seules.
- Signalez CI comme vert à moins que le SHA concerné et les vérifications requises soient tous deux connus.
- Incluez silencieusement des fichiers sales préexistants.
- Incluez silencieusement des fichiers untracked.
Verrous de risque
Lecture seule — aucune approbation nécessaire :
git status,git diff --stat,git log,git remote -vgh pr view,gh run list,gh repo view- Toute commande d'inspection ou de diagnostic qui ne modifie pas l'état
Modification d'état faible — plan visible et approbation requise en mode exécution :
- Créer une branche locale
- Créer un worktree local
- Stager des fichiers explicitement listés
- Créer un commit à partir d'un plan approuvé
Modification d'état élevée — approbation explicite requise :
- Push (toute branche)
- Créer une PR
- Merge une branche
- Rebaser une branche
- Modifier la protection de branche ou les ensembles de règles
- Supprimer une branche
- Supprimer un worktree
Dangereux — confirmation écrite et préférence pour afficher les commandes plutôt que les exécuter :
- Push vers une branche protégée (nécessite le nom de la branche écrit)
- Push
--force-with-lease(doit être explicitement demandé) git reset --hardgit clean -fdou toute suppression de fichier untracked- Supprimer une branche avec des commits non fusionnés
- Réécrire l'historique public
- Correction d'historique secret
git push --force est toujours interdit.
Modèles de fichiers sensibles
N'incluez jamais ces éléments dans un plan de commit. Si l'utilisateur passe outre après un avertissement, avertissez à nouveau et recommandez de ne pas le faire.
.env
.env.*
*.pem
*.key
*.p12
*.pfx
id_rsa*
*.cert
.aws/credentials
credentials.json
*.secret
token.txt
.npmrc
auth.json
service-account*.json
Excluez également : les fichiers ignorés, les sorties de build, les caches et les dossiers de dépendances, sauf si le dépôt les suit intentionnellement.
Exclusions courantes :
node_modules/
dist/
build/
.cache/
.svelte-kit/
.next/
coverage/
__pycache__/
*.pyc
Limite de visibilité de la sécurité
Trellis peut signaler les signaux de sécurité visibles. Trellis n'est pas un scanner de sécurité complet.
Signalez quand ils sont visibles :
- fichiers à forme de secret dans le diff local (noms de fichiers ou motifs correspondant à
.env,*.key, etc.) - si le scan de secrets GitHub et la protection push semblent activés
- si CodeQL ou le scan de code est configuré
- si les alertes Dependabot ou les mises à jour de sécurité sont visibles
- si les fichiers de dépendance ont changé dans ce diff
N'affirmez jamais :
- "aucun secret trouvé" uniquement parce que le grep local n'a rien trouvé
- "aucune vulnérabilité" uniquement parce que les vérifications GitHub visibles sont vertes
- que la posture de sécurité est propre, sauf vérification via un outil de sécurité dédié
Limite de visibilité GitHub/CI
Signalez ce qui peut et ne peut pas être vérifié. Ne transformez pas un état de protection inconnu en sécurité supposée.
Les modes CI sont des questions différentes — ne les confondez pas :
Préparation au niveau PR :
- Cette PR est-elle prête à être fusionnée ?
- Les vérifications requises passent-elles pour ce SHA ?
- Les vérifications en attente, ignorées ou annulées sont-elles pertinentes ?
Inspection de l'exécution du workflow :
- Pourquoi cette exécution a-t-elle échoué ?
- Quel job ou étape a échoué ?
- Des logs ou artefacts sont-ils disponibles ?
État de protection GitHub — signalez l'un des éléments suivants :
État de protection : vérifié -- <résumé de ce qui a été trouvé>État de protection : non vérifié. Ne supposez pas que main est protégé.
File d'attente de merge — si une file d'attente de merge est requise, les vérifications de tête de PR ne sont pas le signal final. Signalez séparément :
- vérifications de tête de PR
- vérifications requises
- vérifications de file d'attente de merge ou de groupe de merge si présentes
- si le SHA vérifié correspond au commit en cours de discussion
N'ajoutez jamais à la file d'attente de merge, n'activez pas l'auto-merge, et ne mergez pas sans approbation explicite de l'utilisateur.
Rapport Trellis
Le rapport Trellis est la sortie signature de chaque passage d'inspection ou de planification.
Formulaire complet
Rapport Trellis
Vérification racine
- Racine du dépôt : <répertoire de travail actuel ; si worktree lié, il s'agit du chemin du worktree>
- Dépôt principal : <racine du dépôt parent, dérivée de GIT_COMMON si worktree lié ; omettre si ce n'est pas un worktree lié>
- Branche :
- Distant/amont :
- État du worktree : <worktree lié à <chemin> / checkout du dépôt principal / HEAD détaché>
- État d'identité/signature :
- Fichiers sales de base (préexistants) :
Vérification d'enchevêtrement
- Modifications staged :
- Modifications unstaged :
- Fichiers untracked :
- Fichiers ignorés/générés notables :
- Fichiers à apparence sensible :
- Fichiers partiellement staged :
- Préoccupations mixtes :
Plan de croissance
- Groupes de modifications suggérés :
- Limites de commit suggérées :
- Forme de PR suggérée :
- Fichiers exclus du périmètre :
- Fichiers nécessitant une décision de l'utilisateur :
Vérification de verrou
- Sécurisé pour inspecter/lire : oui
- Nécessite une approbation avant staging :
- Nécessite une approbation avant commit :
- Nécessite une approbation avant push :
- Nécessite une approbation avant merge/auto-merge :
- Nécessite une approbation avant nettoyage/suppression :
Vérification de canopée
- Visibilité du dépôt/PR GitHub :
- Vérifications requises :
- État CI et SHA vérifié :
- État de la protection de branche/ensemble de règles :
- État de la file d'attente de merge :
- Signaux de sécurité visibles :
- Inconnues/protections non vérifiées :
Prochaine action sécurisée
- Recommandation :
- Commandes exactes (lecture seule uniquement, ou avec annotation de verrou) :
- Décision requise de l'utilisateur :
Formulaire court
Utilisez pour les passes simples ou les petits arbres de travail.
Rapport Trellis
- Racine : <résumé du dépôt / branche / worktree>
- Enchevêtrement : <résumé staged / unstaged / untracked / sensible / préoccupation mixte>
- Croissance : <recommandation de regroupement commit/PR>
- Verrous : <opérations nécessitant une approbation>
- Canopée : <état GitHub/CI/protection si connu, ou "non vérifié">
- Prochaine : <une prochaine action sécurisée>
Formulaire d'arrêt
Utilisez lorsque Trellis ne peut pas ou ne doit pas continuer.
Arrêt Trellis
- Raison de l'arrêt :
- Preuve :
- Risque si ignoré :
- Options de récupération sécurisées :
- Option recommandée :
Les raisons d'arrêt incluent :
- Un fichier à apparence sensible serait stagé.
- Un fichier sale préexistant serait inclus silencieusement.
- Un fichier partiellement staged rend l'intention ambiguë.
- La branche cible est protégée ou inconnue et un push/merge a été demandé.
- Une opération de type force a été demandée sans acceptation explicite du risque.
- L'état push ou CI revendiqué fait référence à un SHA différent.
- Une autre branche, worktree ou PR semble posséder la même tâche.
Aiguillage de mode
Lisez $ARGUMENTS.
Si aucun mode n'est fourni, exécutez audit.
Modes pris en charge :
audit: revue de posture Git locale et GitHub en lecture seulestart: préparer un travail isolé en utilisant une branche ou un worktreecommit: planifier ou exécuter des commits cohérentspush: préparer ou exécuter un push et une surveillance CIfinish: terminer la branche via PR, merge local, conserver ou supprimerrecover: récupérer d'erreurs Git
Mode audit
Exécutez des diagnostics en lecture seule. Produisez un rapport Trellis. Ne modifiez jamais l'état local ou distant.
Pré-vol audit — Git local
Toujours exécuter en premier, quelle que soit la disponibilité de gh :
git rev-parse --show-toplevel 2>/dev/null || echo "ERREUR : pas un dépôt git"
git branch --show-current
git status --short
git diff --stat
git diff --cached --stat
git log --oneline -10
git remote -v
git config --show-origin --show-scope --get user.name 2>/dev/null || echo "non défini"
git config --show-origin --show-scope --get user.email 2>/dev/null || echo "non défini"
git config commit.gpgsign 2>/dev/null || echo "non défini"
Pré-vol audit — Vérifications des fichiers communautaires
Vérifiez la présence/absence de chaque fichier localement. La présence/absence est un fait vérifié ; la qualité du contenu ne l'est pas :
test -f README.md && echo "présent" || echo "absent"
test -f LICENSE && echo "présent" || echo "absent"
test -f SECURITY.md && echo "présent" || echo "absent"
test -f CODE_OF_CONDUCT.md && echo "présent" || echo "absent"
test -f CONTRIBUTING.md || test -f .github/CONTRIBUTING.md && echo "présent" || echo "absent"
test -f .github/PULL_REQUEST_TEMPLATE.md && echo "présent" || echo "absent"
test -d .github/ISSUE_TEMPLATE && echo "présent" || echo "absent"
test -f CODEOWNERS || test -f .github/CODEOWNERS || test -f docs/CODEOWNERS && echo "présent" || echo "absent"
test -f .github/dependabot.yml || test -f .github/dependabot.yaml && echo "présent" || echo "absent"
test -d .github/workflows && echo "présent" || echo "absent"
Posture GitHub — verrou de disponibilité
Avant d'exécuter toute commande gh :
- Vérifiez si un distant GitHub est présent :
git remote -v | grep github.com - Vérifiez si
ghest disponible :gh auth status 2>/dev/null
Si aucun distant GitHub n'est détecté : signalez tous les champs de posture GitHub comme indisponible -- distant non-GitHub.
Si gh est indisponible
...
[tronqué pour la traduction]