Codebase Trellis

Was macht Codebase Trellis?

Strukturieren, unterstützen und sicher integrieren Sie KI-gestützte Codeänderungen.

Ökosystem:

• codebase-orient versteht die Codebasis.
• codebase-visualize kartiert die Codebasis.
• codebase-trellis unterstützt sicheres Änderungswachstum und Integration.

---

Wann diese Fähigkeit verwenden

Verwenden Sie diese Fähigkeit, wenn

• Dateien geändert wurden und sicheres Staging, Commit-Planung oder Commit-Ausführung benötigt werden.
• Ein Branch oder Worktree eingerichtet, beendet oder bereinigt werden muss.
• Ein Push, PR oder CI-Status geprüft oder vorbereitet werden muss.
• Die Git/GitHub-Repository-Position überprüft werden muss.
• Eine länger laufende Agentensitzung eine strukturierte Statusüberprüfung vor der Fortsetzung benötigt.
• Der Arbeitsbaum verschmutzt ist und der richtige nächste Schritt unklar ist.

Überspringen Sie diese Fähigkeit, wenn

• Die Aufgabe eine winzige, einzelne Datei, bekannter Fix ohne Git-Status-Unsicherheit ist.
• Es findet eine schreibgeschützte Erkundung statt und keine Commit/Push/Cleanup-Arbeit ist geplant.
• Eine andere Fähigkeit (codebase-orient, codebase-visualize) wurde gerade aufgerufen und keine Git-Arbeit folgt.

---

Einfache vs. strukturierte Klassifikation

Klassifizieren Sie jeden Aufruf, bevor Sie einen Workflow ausführen.

Einfacher Durchlauf:

• lokalisierter Bugfix
• Nur-Dokumentation oder Nur-Kopie Änderung
• Abhängigkeitsupdate
• kleine Refaktorisierung
• Nur-Tests Änderung
• bereits abgegrenzte Commit-Vorbereitung

Strukturierter Durchlauf:

• breite, mehrere Dateien umfassende Änderung
• mehrere Pakete
• UI plus API plus Tests
• Migration oder generierte Dateien
• länger laufende Agentenarbeit
• mehrere Commits erwartet
• Wiederaufnahme oder Übergabe wahrscheinlich erforderlich

Standardmäßig einfach, wenn unsicher. Auf strukturiert hochstufen, wenn die Inspektion ergibt, dass die Arbeit größer ist als angenommen. Nie von strukturiert herunterstufen, nachdem der Sicherheitszustand hergestellt wurde.

---

Durchsetzungsebenen

Trellis arbeitet innerhalb eines 4-stufigen Sicherheitsmodells. Diese Ebenen sind nicht gleichwertig und keine Ebene ersetzt eine andere.

Ebene 1: Skill-Disziplin (Kern v1-Ebene)

Der Skill inspiziert, meldet und sperrt riskante Operationen. Funktioniert in jedem normalen Git-Repo ohne zusätzliche Hooks oder GitHub-Zugriff. Dies ist verhaltensbasiert – es hängt davon ab, dass der Agent dem Skill folgt.

Ebene 2: Lokale Git-Hooks

Repository-lokale Hooks können während des Commits oder Pushes ausgeführt werden. Trellis kann Hooks empfehlen, installiert sie aber in v1 nicht und erfordert sie nicht. Hooks können fehlen, mit --no-verify umgangen werden oder nicht über Klone hinweg geteilt werden.

Ebene 3: Claude Code Hooks

Host-Level-Hooks können in Bezug auf Tool-Nutzung, Dateiänderungen und Berechtigungen wirken. Optionale Härtung nur – nicht für den eigenständigen Kern erforderlich. Nicht annehmen, dass sie installiert sind.

Ebene 4: GitHub-Schutzmaßnahmen

GitHub-seitige Durchsetzung: Branch-Schutz, Regelsets, erforderliche Checks, erforderliche Überprüfungen, signierte Commits, Force-Push-Einschränkungen, Merge-Queue, Secret Scanning, Code Scanning, Dependabot. Inspizieren und melden, wenn der API-Zugriff dies zulässt; niemals Schutzmaßnahmen annehmen.

Nichtgleichwertigkeitsregel:

• Skill-Disziplin ist kein Hook.
• Ein lokaler Hook ist kein GitHub-Branch-Schutz.
• Ein lokaler grep ist kein Secret Scanning.
• PR-Head-Checks sind keine Merge-Queue-Checks.
• Ein sichtbarer grüner Haken ist kein Beweis dafür, dass alle erforderlichen Checks für den relevanten SHA bestanden haben.

Wenn eine Ebene nicht verfügbar oder nicht verifiziert ist, sagen Sie dies deutlich.

---

Interoperabilitätsgrenze

Eigenständiger Kern

Codebase Trellis muss in jedem normalen Git-Repo funktionieren, ohne Artefakte von Schwester-Skills zu benötigen. Es besitzt:

• Git-Status und Dirty-State-Inspektion
• gestagte, ungestagte, unverfolgte, ignorierte, generierte, sensible und bereits vorhandene Änderungserkennung
• Commit-Gruppierung und Commit-Plan-Übergabe
• Branch/Worktree-Sicherheit
• Push/PR/CI-Gates
• Bereinigungsregeln
• Trellis-Berichtausgabe

Optionale beratende Lektüre

Wenn Artefakte von Schwester-Skills vorhanden sind, darf Trellis sie als beratenden Kontext lesen.

Von codebase-orient (Beispiele: docs/ai/CODEBASE_MAP.md, docs/ai/CHANGE_SURFACES.md, docs/ai/OPEN_QUESTIONS.md):

• Repo-Layout und Paket-/Workspace-Struktur
• bekannte Checks und generierte Dokumentationsrichtlinie
• wichtige Konventionen und Gefahrenzonen

Von codebase-visualize (Beispiele: docs/ai/visualize/codebase-graph.json):

• Auswirkungsradius und betroffene Module
• Docs-to-Code-Kanten und Dateien mit hoher Zentralität

Regeln:

• Diese Dateien nicht benötigen.
• Sie nicht neu generieren.
• Sie nicht stillschweigend ändern.
• Die routinemäßige Commit-Planung nicht blockieren, weil die Visualisierung fehlt.
• Sie nicht als autoritativer als Quellen-/Konfigurations-/kanonische Dokumente behandeln.

Übergabeauslöser

• /codebase-orient vorschlagen, wenn die Repo-Struktur unklar ist, bekannte Checks unbekannt sind oder dem Agenten der Kontext fehlt, um Risiken zu klassifizieren.
• /codebase-visualize vorschlagen, wenn die Änderungsauswirkung breit oder architektonisch ist, Abhängigkeitsbeziehungen wichtig sind oder der Auswirkungsradius die Entscheidung verbessern würde.

---

Universelle Regeln

Immer:

1. Identifizieren Sie zuerst das Repo-Root, den Branch und den Dirty-State.
2. Zeigen Sie den Zustand, bevor Sie Befehle vorschlagen.
3. Trennen Sie gestagte, ungestagte, unverfolgte, gelöschte und ignorierte Dateien.
4. Behandeln Sie teilweise gestagte Dateien als mehrdeutig und riskant.
5. Schließen Sie sensible Dateien aus allen Commit-Plänen aus.
6. Bevorzugen Sie genaue Dateilisten gegenüber breiten Pfadbefehlen.
7. Stoppen Sie bei Befehlsfehlern.
8. Sagen Sie, wenn gh nicht verfügbar ist oder keine Berechtigung hat.
9. Halten Sie Berichte kurz und handlungsorientiert.
10. Melden Sie, was bekannt und was unbekannt ist; kollabieren Sie Unbekanntes nicht in angenommene Sicherheit.

Nie:

1. git add . ohne explizite Zustimmung zur genauen Dateiliste ausführen.
2. Commit ohne Anzeige der geplanten Dateien und der Commit-Nachricht.
3. Push als Teil des Commits.
4. Merge als Teil des Pushes.
5. git push --force verwenden.
6. --force-with-lease ableiten; es muss explizit angefordert werden.
7. Branches ohne getippte Bestätigung des Branch-Namens löschen.
8. Worktrees entfernen, die nicht von dieser Sitzung erstellt wurden oder nicht klar projektlokale, wegwerfbare Worktrees sind.
9. .env, Schlüssel, Token, Anmeldeinformationen oder ignorierte Dateien in einen Commit-Plan aufnehmen.
10. Tests, CI oder GitHub-Einstellungen als bestanden behaupten, sofern nicht verifiziert.
11. "Keine Geheimnisse" oder "Keine Schwachstellen" allein aus einem lokalen grep oder sichtbaren Checks behaupten.
12. CI als grün melden, es sei denn, der relevante SHA und die erforderlichen Checks sind beide bekannt.
13. Vorhandene verschmutzte Dateien stillschweigend einbeziehen.
14. Unverfolgte Dateien stillschweigend einbeziehen.

---

Risikogates

Schreibgeschützt – keine Genehmigung erforderlich:

• git status, git diff --stat, git log, git remote -v
• gh pr view, gh run list, gh repo view
• Jeder Inspektions- oder Diagnosebefehl, der den Zustand nicht ändert

Niedrige Zustandsänderung – sichtbarer Plan und Genehmigung im Ausführungsmodus erforderlich:

• Lokalen Branch erstellen
• Lokalen Worktree erstellen
• Explizit aufgeführte Dateien stagen
• Commit aus genehmigtem Plan erstellen

Hohe Zustandsänderung – explizite Genehmigung erforderlich:

• Push (jeder Branch)
• PR erstellen
• Branch mergen
• Branch rebasen
• Branch-Schutz oder Regelsets bearbeiten
• Branch löschen
• Worktree entfernen

Gefährlich – getippte Bestätigung und bevorzugen Sie die Ausgabe von Befehlen gegenüber der Ausführung:

• Push zu geschütztem Branch (erfordert getippten Branch-Namen)
• --force-with-lease Push (muss explizit angefordert werden)
• git reset --hard
• git clean -fd oder jegliches Entfernen unverfolgter Dateien
• Branch mit nicht gemergten Commits löschen
• Öffentliche Geschichte umschreiben
• Behebung von Geheimnisgeschichte

git push --force ist immer verboten.

---

Sensitive Dateimuster

Diese niemals in einen Commit-Plan aufnehmen. Wenn der Benutzer nach einer Warnung überschreibt, warnen Sie erneut und empfehlen Sie davon ab.

.env
.env.*
*.pem
*.key
*.p12
*.pfx
id_rsa*
*.cert
.aws/credentials
credentials.json
*.secret
token.txt
.npmrc
auth.json
service-account*.json

Auch ausschließen: ignorierte Dateien, Build-Ausgabe, Caches und Abhängigkeitsordner, es sei denn, das Repo verfolgt sie absichtlich.

Häufige Ausschlüsse:

node_modules/
dist/
build/
.cache/
.svelte-kit/
.next/
coverage/
__pycache__/
*.pyc

---

Sichtbarkeitsgrenze für Sicherheit

Trellis kann sichtbare Sicherheitssignale melden. Trellis ist kein vollständiger Sicherheitsscanner.

Melden, wenn sichtbar:

• geheimnisartige Dateien im lokalen Diff (Dateinamen oder Muster, die mit .env, *.key usw. übereinstimmen)
• ob GitHub Secret Scanning und Push Protection aktiviert erscheinen
• ob CodeQL oder Code Scanning konfiguriert ist
• ob Dependabot-Benachrichtigungen oder Sicherheitsupdates sichtbar sind
• ob sich Abhängigkeitsdateien in diesem Diff geändert haben

Nie behaupten:

• "Keine Geheimnisse gefunden", nur weil der lokale grep nichts gefunden hat
• "Keine Schwachstellen", nur weil sichtbare GitHub-Checks grün sind
• Die Sicherheitslage ist sauber, es sei denn, ein dediziertes Sicherheitstool hat sie verifiziert

---

GitHub/CI-Sichtbarkeitsgrenze

Melden Sie, was verifiziert werden kann und was nicht. Kollabieren Sie unbekannte Schutzstatus nicht in angenommene Sicherheit.

CI-Modi sind unterschiedliche Fragen – vermischen Sie sie nicht:

PR-Level-Bereitschaft:

• Ist dieser PR merge-bereit?
• Bestehen erforderliche Checks für diesen SHA?
• Sind ausstehende, übersprungene oder abgebrochene Checks relevant?

Workflow-Run-Inspektion:

• Warum ist dieser Run fehlgeschlagen?
• Welcher Job oder Schritt ist fehlgeschlagen?
• Sind Logs oder Artefakte verfügbar?

GitHub-Schutzstatus – melden Sie einen von:

• Schutzstatus: verifiziert -- <Zusammenfassung des Gefundenen>
• Schutzstatus: nicht verifiziert. Nehmen Sie nicht an, dass main geschützt ist.

Merge-Queue – wenn eine Merge-Queue erforderlich ist, sind PR-Head-Checks nicht das endgültige Signal. Separat melden:

• PR-Head-Checks
• erforderliche Checks
• Merge-Queue- oder Merge-Group-Checks, falls vorhanden
• ob der geprüfte SHA mit dem Commit übereinstimmt, der besprochen wird

Nie zur Merge-Queue hinzufügen, Auto-Merge aktivieren oder ohne explizite Benutzerzustimmung mergen.

---

Trellis-Bericht

Der Trellis-Bericht ist die Signaturausgabe jedes Inspektions- oder Planungsdurchlaufs.

Vollständige Form

Trellis report

Root check
- Repo root:     <aktuelles Arbeitsverzeichnis; bei verknüpftem Worktree ist dies der Worktree-Pfad>
- Main repo:     <übergeordnetes Repo-Root, abgeleitet von GIT_COMMON, wenn verknüpfter Worktree; weglassen, wenn nicht verknüpfter Worktree>
- Branch:
- Remote/upstream:
- Worktree state: <verknüpfter Worktree unter <Pfad> / Main-Repo-Checkout / detachierter HEAD>
- Identity/signing state:
- Baseline dirty files (pre-existing):

Tangle check
- Staged changes:
- Unstaged changes:
- Untracked files:
- Ignored/generated files of note:
- Sensitive-looking files:
- Partially staged files:
- Mixed concerns:

Growth plan
- Suggested change groups:
- Suggested commit boundaries:
- Suggested PR shape:
- Files excluded from scope:
- Files requiring user decision:

Gate check
- Safe to inspect/read: yes
- Requires approval before staging:
- Requires approval before commit:
- Requires approval before push:
- Requires approval before merge/auto-merge:
- Requires approval before cleanup/delete:

Canopy check
- GitHub repository/PR visibility:
- Required checks:
- CI state and SHA checked:
- Branch protection/ruleset state:
- Merge queue state:
- Security signals visible:
- Unknowns/unverified protections:

Next safe action
- Recommendation:
- Exact commands (read-only only, or with gate annotation):
- Decision required from user:

Kurzform

Verwenden Sie für einfache Durchläufe oder kleine Arbeitsbäume.

Trellis report
- Root: <Repo / Branch / Worktree Zusammenfassung>
- Tangle: <gestaged / ungestaged / unverfolgt / sensibel / gemischte Bedenken Zusammenfassung>
- Growth: <Commit/PR-Gruppierungsempfehlung>
- Gates: <Operationen, die Genehmigung erfordern>
- Canopy: <GitHub/CI/Schutzstatus, falls bekannt, oder "nicht verifiziert">
- Next: <eine sichere nächste Aktion>

Stopp-Form

Verwenden Sie, wenn Trellis nicht fortfahren kann oder darf.

Trellis stop
- Stop reason:
- Evidence:
- Risk if ignored:
- Safe recovery options:
- Recommended option:

Stopp-Gründe umfassen:

• Eine sensibel aussehende Datei würde gestaged werden.
• Eine bereits vorhandene verschmutzte Datei würde stillschweigend einbezogen.
• Eine teilweise gestagte Datei macht die Absicht mehrdeutig.
• Der Ziel-Branch ist geschützt oder unbekannt und ein Push/Merge wurde angefordert.
• Eine force-ähnliche Operation wurde ohne explizite Risikoakzeptanz angefordert.
• Der behauptete Push- oder CI-Status bezieht sich auf einen anderen SHA.
• Ein anderer Branch, Worktree oder PR scheint dieselbe Aufgabe zu besitzen.

---

Modus-Routing

Lesen Sie $ARGUMENTS.

Wenn kein Modus angegeben ist, führen Sie audit aus.

Unterstützte Modi:

• audit: schreibgeschützte lokale Git- und GitHub-Positionsüberprüfung
• start: isolierte Arbeit mit einem Branch oder Worktree vorbereiten
• commit: kohärente Commits planen oder ausführen
• push: Push und CI-Überwachung vorbereiten oder ausführen
• finish: Branch durch PR, lokales Mergen, Behalten oder Verwerfen abschließen
• recover: von Git-Fehlern erholen

---

audit-Modus

Führen Sie schreibgeschützte Diagnosen aus. Erstellen Sie einen Trellis-Bericht. Ändern Sie niemals einen lokalen oder entfernten Zustand.

Audit-Vorflug – lokales Git

Immer zuerst ausführen, unabhängig von der gh-Verfügbarkeit:

git rev-parse --show-toplevel 2>/dev/null || echo "ERROR: not a git repo"
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 "unset"
git config --show-origin --show-scope --get user.email 2>/dev/null || echo "unset"
git config commit.gpgsign 2>/dev/null || echo "unset"

Audit-Vorflug – Community-Dateiprüfungen

Prüfen Sie das Vorhandensein/Nichtvorhandensein jeder Datei lokal. Vorhandensein/Nichtvorhandensein ist eine verifizierte Tatsache; Inhaltsqualität ist es nicht:

test -f README.md && echo "present" || echo "absent"
test -f LICENSE && echo "present" || echo "absent"
test -f SECURITY.md && echo "present" || echo "absent"
test -f CODE_OF_CONDUCT.md && echo "present" || echo "absent"
test -f CONTRIBUTING.md || test -f .github/CONTRIBUTING.md && echo "present" || echo "absent"
test -f .github/PULL_REQUEST_TEMPLATE.md && echo "present" || echo "absent"
test -d .github/ISSUE_TEMPLATE && echo "present" || echo "absent"
test -f CODEOWNERS || test -f .github/CODEOWNERS || test -f docs/CODEOWNERS && echo "present" || echo "absent"
test -f .github/dependabot.yml || test -f .github/dependabot.yaml && echo "present" || echo "absent"
test -d .github/workflows && echo "present" || echo "absent"

GitHub-Position – Verfügbarkeits-Gate

Vor der Ausführung eines gh-Befehls:

1. Prüfen, ob ein GitHub-Remote vorhanden ist: git remote -v | grep github.com
2. Prüfen, ob gh verfügbar ist: gh auth status 2>/dev/null

Wenn kein GitHub-Remote erkannt wird: alle GitHub-Positionsfelder als nicht verfügbar -- kein GitHub-Remote melden.

Wenn gh nicht verfügbar ist