truthmark 1.4.0 → 1.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/README.de.md +672 -194
  2. package/README.es.md +673 -195
  3. package/README.md +663 -192
  4. package/README.ru.md +680 -202
  5. package/README.zh.md +679 -199
  6. package/dist/main.js +1307 -145
  7. package/dist/main.js.map +1 -1
  8. package/package.json +1 -2
package/README.de.md CHANGED
@@ -1,294 +1,687 @@
1
1
  # Truthmark
2
2
 
3
- **Truthmark installiert Repository-Wahrheits-Workflows für KI-Softwareentwicklung.**
3
+ **Deine Agenten schreiben Code. Truthmark macht ihren Kontext in Git prüfbar.**
4
4
 
5
5
  [English](README.md) | Deutsch | [中文](README.zh.md) | [Español](README.es.md) | [Русский](README.ru.md)
6
6
 
7
- <img src="docs/assets/truthmark-banner.png" alt="Truthmark-Banner" width="100%" />
7
+ ![Truthmark-Banner](docs/assets/truthmark-banner.png)
8
8
 
9
- KI-Coding-Agenten schreiben bereits schnell Code. Der teure Teil ist, die Repository-Wahrheit mit den tatsächlichen Änderungen im Gleichschritt zu halten.
9
+ KI-Coding-Agenten können ein Repository schneller verändern, als Menschen den Kontext ausrichten können.
10
10
 
11
- Truthmark fügt diesem Ablauf eine Abschlusskontrolle als Workflow hinzu. Der normale Pfad ist einfach:
11
+ Truthmark repariert den Teil, der normalerweise nach dem Code-Schreiben bricht: die Repository-Wahrheit.
12
12
 
13
- - Agent ändert funktionalen Code
14
- - relevante Tests laufen
15
- - der installierte Truth-Sync-Workflow aktualisiert zugeordnete Wahrheitsdokumente, bevor der Agent fertig ist
16
- - Truth-Doc-Diff prüfen, wenn einer erzeugt wurde
13
+ Es installiert eine Git-native, branch-gebundene Workflow-Schicht, die KI-Coding-Agenten hilft, die richtigen Dokumente zu aktualisieren, Ownership-Grenzen zu respektieren und Menschen normale Diffs zur Prüfung zu hinterlassen.
17
14
 
18
- Die meisten Tools bitten Teams darum, sich eine Gewohnheit anzueignen. Truthmark macht daraus Repository-Workflow-Infrastruktur.
15
+ Kein gehosteter Dienst.
19
16
 
20
- Truthmark macht aus einem KI-Workflow Repository-Infrastruktur statt persönlichem Tooling. Es installiert eine Git-native, branch-gebundene Wahrheitsschicht im Repository, gibt Agenten explizites Routing und begrenzte Workflow-Flächen und hält diese Wahrheit in Git prüfbar, statt sie über Prompt-Verlauf, veraltete Dokumentation oder privaten Tool-Zustand zu verstreuen.
17
+ Keine Datenbank.
21
18
 
22
- Das ist wichtig, weil der Workflow mit dem Branch lebt. Sobald ein Repository initialisiert ist, reisen Regeln, Routing und installierte Workflow-Flächen im Repository mit, sodass Zusammenarbeit und Übergaben weniger von der Rechnerkonfiguration einer einzelnen Person abhängen.
19
+ Keine verborgene Memory-Schicht.
23
20
 
24
- Für Teams, die bereits wissen, dass Agenten Code erzeugen können, beantwortet Truthmark das nächste Problem: wie das Repository selbst lesbar, prüfbar und steuerbar bleibt, wenn KI-gestützte Arbeit skaliert.
21
+ Kein zusätzlicher Server im Betrieb.
25
22
 
26
- ## Visueller Überblick
23
+ Nur Repository-Wahrheit, die mit dem Branch mitwandert.
27
24
 
28
- <table>
29
- <tr>
30
- <td align="center" width="50%">
31
- <img src="docs/assets/truthmark-features.png" alt="Truthmark-Funktionen" width="100%" />
32
- <br><strong>Funktionen</strong><br>
33
- Was Truthmark installiert und wie sich die Workflow-Fläche aufteilt.
34
- </td>
35
- <td align="center" width="50%">
36
- <img src="docs/assets/truthmark-position.png" alt="Truthmark-Positionierung" width="100%" />
37
- <br><strong>Positionierung</strong><br>
38
- Wo Truthmark im Verhältnis zu Prompts, Memory und Spec-Workflows steht.
39
- </td>
40
- </tr>
41
- <tr>
42
- <td align="center" colspan="2">
43
- <img src="docs/assets/truthmark-syncflow.png" alt="Truthmark-Sync-Ablauf" width="100%" />
44
- <br><strong>Sync-Ablauf</strong><br>
45
- Wie Truth Sync normale Codeänderungen vor einer Übergabe abschließt.
46
- </td>
47
- </tr>
48
- </table>
25
+ ## Das Problem
49
26
 
50
- ## Warum Teams es nutzen
27
+ KI-Coding-Agenten sind gut darin, Code zu erzeugen. Dadurch entsteht eine neue Fehlerart.
51
28
 
52
- Truthmark versucht nicht, Agenten klüger wirken zu lassen. Es soll KI-gestützte Repository-Änderungen vertrauenswürdiger machen.
29
+ Die Implementierung ändert sich, aber die Repository-Erzählung driftet ab:
53
30
 
54
- - Installierte Truth-Sync-Läufe nach Codeänderungen machen Dokumentationspflege zu einer Workflow-Schutzschicht statt zu einer Teamgewohnheit.
55
- - Branch-gebundene Wahrheit bewegt sich mit dem Code, sodass Reviewer aktuelle Wahrheit in normalen Git-Diffs prüfen können.
56
- - Repository-native Workflow-Flächen machen Rollout leichter und Übergaben robuster als reine Pro-User-Konfiguration.
57
- - Explizites Routing in `docs/truthmark/areas.md` und delegierten untergeordneten Routendateien gibt Agenten Zuständigkeitsgrenzen und sicherere Schreibpfade.
58
- - Local-first-Betrieb vermeidet einen Daemon, eine Datenbank, einen Remote-Dienst oder eine MCP-Abhängigkeit.
59
- - Das Routing-Modell ist sprachunabhängig, mit Coverage-Diagnostik für gängige JavaScript-, TypeScript-, Go-, Python-, C#- und Java-Codeflächen.
31
+ - Verhalten lebt im Chatverlauf
32
+ - Architekturdokumente fallen zurück
33
+ - Produktentscheidungen verschwinden nach der Übergabe
34
+ - Reviewer sehen Code-Diffs ohne die zugehörigen Truth-Diffs
35
+ - Branches entwickeln unbemerkt unterschiedliche Versionen davon, „was wahr ist“
36
+ - jede Agentensitzung muss Kontext neu entdecken
60
37
 
61
- Für Tech Leads liegt der Wert in Governance ohne Zusatzinfrastruktur: Tests, Code Review und Ownership leisten weiterhin die eigentliche Arbeit; Truthmark macht den Kontext des Agenten dauerhaft, prüfbar und branch-gebunden.
38
+ Truthmark verwandelt diesen fragilen Kontext in festgeschriebene Repository-Infrastruktur.
62
39
 
63
- ## Wo Truthmark hineinpasst
40
+ Statt darauf zu vertrauen, dass jeder Mensch und jeder Agent die richtige Dokumentationsgewohnheit beibehält, installiert Truthmark diese Gewohnheit im Repository.
64
41
 
65
- Truthmark ist keine allgemeine KI-Produktivitätssuite. Es besetzt eine bestimmte Schicht im Stack: branch-gebundene, prüfbare Repository-Wahrheit, die mit der Implementierung synchron bleibt.
42
+ ## Das Versprechen
66
43
 
67
- | Wenn du brauchst | Beste Wahl |
68
- | --------------------------------------------------------------------------- | ------------------------------------------- |
69
- | Bessere Ergebnisse aus einer einzelnen Coding-Sitzung | Bessere Prompts und enger gefasste Aufgaben |
70
- | Bequemlichkeit über Sitzungen hinweg für einen Agenten oder eine Person | Speicherwerkzeuge |
71
- | Spec-first-Planung für neue Features | Spezifikations-Tools wie Spec Kit |
72
- | Branch-gebundene, prüfbare Repository-Wahrheit, die mit dem Code mitwandert | Truthmark |
44
+ Wenn ein Agent funktionalen Code ändert, sollte die Arbeit nicht mit einem reinen Code-Diff enden.
73
45
 
74
- Der Punkt ist nicht, dass Prompts, Memory oder Specs nutzlos wären. Der Punkt ist, dass keines davon allein Repository-Wahrheit in ein in Git festgeschriebenes, prüfbares Asset verwandelt, das Übergaben, Reviews und auseinanderlaufende Branches übersteht.
46
+ Der normale Truthmark-Pfad ist:
75
47
 
76
- ## Inhalt
48
+ ```text
49
+ agent ändert funktionalen Code
50
+ relevante Tests laufen
51
+ Truth Sync prüft zugeordnete Truth-Dokumente
52
+ Truth-Dokumente werden bei Bedarf aktualisiert
53
+ Mensch prüft Code-Diff + Truth-Diff
54
+ committen oder übergeben
55
+ ```
77
56
 
78
- - [Warum Teams es nutzen](#warum-teams-es-nutzen)
79
- - [Was Truthmark löst](#was-truthmark-löst)
80
- - [Wo Truthmark hineinpasst](#wo-truthmark-hineinpasst)
81
- - [Erste Schritte](#erste-schritte)
82
- - [Wie es läuft](#wie-es-läuft)
83
- - [Was es installiert](#was-es-installiert)
84
- - [Befehle](#befehle)
85
- - [Warum es existiert](#warum-es-existiert)
86
- - [Projektstatus](#projektstatus)
87
- - [Dokumentation](#dokumentation)
88
- - [Nicht-Ziele](#nicht-ziele)
89
- - [Lizenz](#lizenz)
57
+ Das ist der Kernwert: **KI-Arbeit wird leichter vertrauenswürdig, weil das Repository lesbar bleibt.**
90
58
 
91
- ## Was Truthmark löst
59
+ ## Zwei Oberflächen, ein Wahrheitssystem
92
60
 
93
- Truthmark macht Repository-Wahrheit zu einer expliziten Workflow-Fläche für Agenten:
61
+ Truthmark ist nicht nur eine CLI.
94
62
 
95
- - `.truthmark/config.yml` definiert den festgeschriebenen Hierarchievertrag.
96
- - `docs/truthmark/areas.md` und delegierte untergeordnete Routendateien ordnen Codebereiche den Dokumenten zu, die sie verantworten.
97
- - Truth Document erstellt oder repariert kanonische Wahrheitsdokumente für bereits implementiertes Verhalten, wenn keine Codeänderung nötig ist.
98
- - Truth Sync hält zugeordnete Wahrheitsdokumente bei funktionalen Änderungen synchron.
99
- - Truth Preview zeigt wahrscheinliches Workflow-Routing vor Änderungen an, ohne Schreibzugriffe zu autorisieren.
100
- - Truth Realize gibt doc-first Änderungen einen begrenzten Pfad für Code-Updates.
101
- - `truthmark check` validiert die daraus entstehenden Wahrheitsartefakte.
102
- - Das gesamte Modell bleibt local-first und Git-nativ.
63
+ Es hat zwei unterschiedliche Oberflächen, und diese Unterscheidung ist wichtig.
103
64
 
104
- Das ist das Kernversprechen: Agentenkontext wird zu festgeschriebenem Repository-Zustand statt zu einem privaten Sitzungsartefakt.
65
+ ### 1. Menschenorientierte CLI
105
66
 
106
- ## Erste Schritte
67
+ Die CLI ist für Maintainer, Reviewer und Automatisierung.
107
68
 
108
- Installiere Truthmark in dem Repository, das du initialisieren möchtest:
69
+ Nutze sie, um ein Repository zu konfigurieren, Workflow-Dateien zu installieren oder zu aktualisieren, Truth-Artefakte zu validieren und optionalen Review-Kontext zu erzeugen.
109
70
 
110
71
  ```bash
111
- cd /path/to/your-repo
112
- npm install -g truthmark
113
72
  truthmark config
114
73
  truthmark init
115
74
  truthmark check
116
75
  ```
117
76
 
118
- Wenn du stattdessen unveröffentlichte Änderungen aus einem Source-Checkout ausprobieren möchtest:
77
+ Die CLI bereitet die Repository-Umgebung vor und validiert sie.
78
+
79
+ Sie ist nicht die Runtime für den KI-Workflow.
80
+
81
+ ### 2. KI-orientierte Workflow-Oberflächen
82
+
83
+ Die KI-orientierten Oberflächen sind für Coding-Agenten.
84
+
85
+ Truthmark installiert host-native Skills, Prompts, Commands, verwaltete Instruktionsblöcke und unterstützte Subagent-Oberflächen, damit KI-Agenten repository-spezifische Truth-Workflows in ihren normalen Coding-Tools befolgen können.
86
+
87
+ Beispiele:
88
+
89
+ ```text
90
+ /truthmark-sync
91
+ /truthmark-document
92
+ /truthmark-structure
93
+ /truthmark-realize
94
+ /truthmark-preview
95
+ /truthmark-check
96
+ ```
97
+
98
+ Sie sehen wie Befehle aus, weil Agenten-Hosts Workflows über Slash-Commands, Prompts, Skills oder Projektbefehle bereitstellen.
99
+
100
+ Es sind keine Shell-Befehle.
101
+
102
+ Es sind KI-orientierte Workflow-Einstiegspunkte.
103
+
104
+ Die Trennung ist das Produkt:
105
+
106
+ ```text
107
+ Menschen besitzen den Repository-Vertrag
108
+ Truthmark installiert den Vertrag ins Repo
109
+ Agenten arbeiten innerhalb dieses Vertrags
110
+ Truth-Updates erscheinen als Git-Diffs
111
+ Menschen prüfen das Ergebnis
112
+ ```
113
+
114
+ ## Quick Start
115
+
116
+ ### Voraussetzungen
117
+
118
+ - Node.js `>=20`
119
+ - npm
120
+ - ein Git-Repository
121
+
122
+ ### Truthmark installieren
123
+
124
+ Führe dies in dem Repository aus, das du initialisieren möchtest:
119
125
 
120
126
  ```bash
121
- cd /path/to/truthmark
122
- npm install
123
- npm run build
124
127
  cd /path/to/your-repo
125
- node /path/to/truthmark/dist/main.js config
126
- node /path/to/truthmark/dist/main.js init
127
- node /path/to/truthmark/dist/main.js check
128
+ npm install -g truthmark
129
+ ```
130
+
131
+ ### Den Repository-Wahrheitsvertrag erstellen
132
+
133
+ ```bash
134
+ truthmark config
128
135
  ```
129
136
 
130
- Prüfe `.truthmark/config.yml` vor `init`; es ist der in Git festgeschriebene Hierarchievertrag. Nach `init` solltest du die generierte Workflow-Fläche und die Routendateien prüfen, damit die gerouteten Dokumente zu den Dokumenten passen, die deinen Code tatsächlich verantworten:
137
+ Das erzeugt:
131
138
 
132
139
  ```text
133
140
  .truthmark/config.yml
134
- docs/truthmark/areas.md
135
- docs/truthmark/areas/repository.md
136
- docs/templates/behavior-doc.md
137
- docs/truth/README.md
138
- docs/truth/repository/README.md
139
- docs/truth/repository/overview.md
140
- AGENTS.md
141
- CLAUDE.md
142
- GEMINI.md
143
141
  ```
144
142
 
145
- Unterstützte Plattformen sind `codex`, `opencode`, `claude-code`, `github-copilot` und `gemini-cli`. Die Standardkonfiguration enthält alle davon; entferne Plattformen, die du nicht nutzt, aus `.truthmark/config.yml`, bevor du `truthmark init` erneut ausführst.
146
- Die standardmäßig erzeugte Struktur verwendet Truth-`README.md`-Dateien als Indizes und beginnt die Wahrheit über aktuelles Verhalten in begrenzten Blattdokumenten wie `docs/truth/repository/overview.md`.
143
+ Prüfe diese Datei, bevor du fortfährst. Sie definiert den festgeschriebenen Hierarchievertrag für das Repository.
147
144
 
148
- Bestehende Repositories brauchen nach `init` meist einen Aufräumschritt: Führe den installierten Truth-Structure-Workflow aus, wenn die erzeugte `repository`-Route zu breit ist, Ownership mehrere Produkte oder Services umfasst oder Routendateien noch auf Platzhalterdokumente zeigen. Truth Structure teilt breite Routings auf, erstellt oder repariert erste kanonische Wahrheitsdokumente und gibt Truth Sync präzise Ziele, bevor funktionale Codearbeit beginnt. Codex, Claude Code und unterstützte Copilot-IDEs können ihn mit `/truthmark-structure` aufrufen; Hosts im OpenCode-Stil können `/skill truthmark-structure` verwenden.
145
+ ### Die Workflow-Oberflächen installieren
149
146
 
150
- ## Wie es läuft
147
+ ```bash
148
+ truthmark init
149
+ ```
150
+
151
+ Das installiert oder aktualisiert:
152
+
153
+ - Routendateien
154
+ - Truth-Doc-Scaffolding
155
+ - verwaltete Instruktionsblöcke
156
+ - KI-orientierte Workflow-Oberflächen für konfigurierte Plattformen
151
157
 
152
- Truthmark ist am stärksten auf dem Standardpfad, nicht als Sammlung manueller Befehle. Der handelnde Agent und die Host-Umgebung entscheiden, ob delegiert oder der installierte Workflow inline ausgeführt wird.
158
+ ### Das Setup validieren
159
+
160
+ ```bash
161
+ truthmark check
162
+ ```
153
163
 
154
- ### Vorhandenes Verhalten ohne Doku
164
+ Prüfe danach die generierten Dateien, bevor du committest.
155
165
 
156
- Nutze das, wenn die Implementierung bereits existiert, aber die kanonischen Wahrheitsdokumente fehlen oder schwach sind:
166
+ Die konkreten Dateien hängen von `.truthmark/config.yml` ab, aber die Installation hat immer dieselbe Form: Routing, Truth-Scaffolding, kompakte verwaltete Instructions und host-native Workflow-Oberflächen für die aktivierten Plattformen.
167
+
168
+ ## Erste echte Nutzung
169
+
170
+ Die meisten Repositories brauchen nach der Initialisierung einen Aufräumschritt.
171
+
172
+ Das Standard-Scaffold beginnt mit einem breiten Bereich `repository`. Echte Repositories brauchen meist präziseres Routing.
173
+
174
+ Bitte deinen Agenten, die breite Route in tatsächliche Produkt-, Service-, Domänen- oder Ownership-Bereiche aufzuteilen:
157
175
 
158
176
  ```text
159
- benutzer identifiziert ein implementiertes verhalten oder einen api-endpunkt
160
- benutzer ruft truth document ausdrücklich auf
161
- agent liest implementierung, tests, routing und vorhandene docs
162
- agent schreibt nur truth docs und routing
163
- truth-doc-diff prüfen
177
+ /truthmark-structure die breite repository-area in auth, billing und notifications aufteilen
164
178
  ```
165
179
 
166
- Truth Document ist manuell und implementation-first: Code dient als Beleg, Wahrheitsdokumente werden erstellt oder repariert, und funktionaler Code darf nicht geändert werden. Codex, Claude Code und unterstützte Copilot-IDEs können es mit `/truthmark-document` aufrufen. Hosts im OpenCode-Stil können `/skill truthmark-document` verwenden.
180
+ Danach nutzt du deinen KI-Coding-Agenten normal.
181
+
182
+ Wenn der Agent funktionalen Code ändert, wirkt Truth Sync als Abschlusskontrolle und prüft vor der Übergabe, ob zugeordnete Truth-Dokumente geändert werden müssen.
183
+
184
+ ## Was du bekommst
185
+
186
+ | Fähigkeit | Was sie tut |
187
+ | --- | --- |
188
+ | Git-native Wahrheit | Hält Repository-Wahrheit in festgeschriebenem Markdown und Config. |
189
+ | Branch-gebundener Kontext | Wahrheit wandert mit dem Branch statt in einer privaten Sitzung zu leben. |
190
+ | Menschen-CLI | Gibt Maintainern Befehle für Setup, Aktualisierung, Validierung und Inspektion. |
191
+ | KI-orientierte Workflows | Gibt Agenten host-native Workflows für Sync, Dokumentation, Struktur, Preview, Realisierung und Audit. |
192
+ | Explizites Routing | Ordnet Codebereiche kanonischen Truth-Dokumenten zu. |
193
+ | Prüffähige Übergaben | Erzeugt normale Git-Diffs für Code und Truth-Dokumente. |
194
+ | Local-first-Betrieb | Benötigt keinen gehosteten Dienst, Daemon, keine Datenbank und keinen MCP-Server. |
195
+ | Sicherere Schreibgrenzen | Trennt code-first, doc-first, read-only und doc-only Workflows. |
196
+ | Validierung | Meldet Probleme bei Routing, Autorität, Frontmatter, Links, generierten Oberflächen, Branch-Scope, Freshness und Coverage. |
197
+ | Optionales Portal | Erzeugt eine festgeschriebene statische HTML-Präsentationssite aus Markdown-Truth-Dokumenten, wenn es ausdrücklich aktiviert und angefragt wird. |
198
+
199
+ ## Visueller Überblick
200
+
201
+ ![Truthmark-Funktionen](docs/assets/truthmark-features.png)
202
+
203
+ **Funktionen:** was Truthmark installiert und wie die Workflow-Oberfläche aufgeteilt ist.
204
+
205
+ ![Truthmark-Positionierung](docs/assets/truthmark-position.png)
206
+
207
+ **Positionierung:** wo Truthmark im Verhältnis zu Prompts, Memory und Spec-Workflows steht.
208
+
209
+ ![Truthmark-Sync-Ablauf](docs/assets/truthmark-syncflow.png)
210
+
211
+ **Sync-Ablauf:** wie Truth Sync normale Codeänderungen vor der Übergabe abschließt.
212
+
213
+ ## Warum Teams es nutzen
214
+
215
+ Truthmark ist für Teams, die bereits wissen, dass KI-Agenten Code erzeugen können.
216
+
217
+ Das nächste Problem ist Governance.
218
+
219
+ Nicht Governance als Zeremonie. Governance als einfache Frage:
220
+
221
+ > Erzählt das Repository nach dieser KI-gestützten Änderung noch die Wahrheit?
222
+
223
+ Truthmark hilft Teams, diese Frage mit festgeschriebenen Dateien, explizitem Routing und prüffähigen Diffs zu beantworten.
224
+
225
+ Es ist nützlich, wenn du Folgendes brauchst:
226
+
227
+ - weniger Dokumentationsdrift
228
+ - bessere Übergaben
229
+ - branch-spezifische Produktwahrheit
230
+ - dauerhaften Architektur- und API-Kontext
231
+ - explizite Ownership zwischen Dokumentation und Code
232
+ - sicherere Schreibgrenzen für Agenten
233
+ - prüffähigen Kontext statt verborgener Memory
234
+ - KI-Workflows, die weiterhin aus festgeschriebenen Repo-Dateien funktionieren
235
+
236
+ ## Wo Truthmark hineinpasst
237
+
238
+ Truthmark ersetzt keine Prompts, Memory, Specs, Tests oder Code Review.
239
+
240
+ Es gibt diesen Workflows einen dauerhaften Ort in Git.
241
+
242
+ | Bedarf | Besser passend |
243
+ | --- | --- |
244
+ | Bessere Ausgabe aus einer Agentensitzung | Besserer Prompt |
245
+ | Persönliche oder sitzungsbezogene Kontinuität | Memory-Tool |
246
+ | Plan-first Feature-Arbeit | Spec-Workflow |
247
+ | Branch-gebundene Wahrheit, die mit dem Code mitwandert | Truthmark |
248
+ | Korrektheit von Verhalten validieren | Tests und Review |
249
+ | KI-gestützte Kontextänderungen prüfen | Truthmark plus Git-Review |
250
+
251
+ Truthmarks Spur ist absichtlich eng:
167
252
 
168
253
  ```text
169
- /truthmark-document dokumentiere das implementierte session-timeout-verhalten unter docs/truth/authentication
254
+ Repository-Wahrheit explizit machen
255
+ sie zu Code routen
256
+ Agenten-Workflows darum installieren
257
+ das Ergebnis in Git prüffähig halten
258
+ ```
259
+
260
+ ## Wie Truthmark läuft
261
+
262
+ Truthmark läuft lokal gegen den aktiven Git-Worktree.
263
+
264
+ Die menschenorientierte CLI liest und schreibt Repository-Dateien und beendet sich danach.
265
+
266
+ Die KI-orientierten Workflow-Oberflächen sind festgeschriebene Dateien, die Agenten-Hosts später laden können. Dadurch können Agenten dem installierten Workflow aus dem Repository-Zustand folgen, statt von einem Hintergrundprozess von Truthmark abzuhängen.
267
+
268
+ Die Schichten greifen so ineinander:
269
+
270
+ ```mermaid
271
+ flowchart LR
272
+ Human["Human / CI"] --> CLI["Truthmark CLI"]
273
+ CLI --> Config["Config und Routing"]
274
+ CLI --> Truth["Kanonische Truth-Dokumente"]
275
+ CLI --> Surfaces["Generierte host-native Workflows"]
276
+ Surfaces --> Hosts["Codex / Claude Code / Copilot / OpenCode / Gemini"]
277
+ Hosts --> Worktree["Aktiver Git-Worktree"]
278
+ Hosts -->|"helper checks / validate / index"| CLI
279
+ Worktree --> Truth
170
280
  ```
171
281
 
172
- ### Normale Codeänderungen
282
+ Agents sprechen nicht mit einem Truthmark-Daemon, können aber die installierte Truthmark CLI ausführen, wenn ein Workflow Validierung, Indexing oder Helper-Checks verlangt.
283
+
284
+ Truthmark besitzt die generierten Workflow-Oberflächen, aber der wichtige Vertrag ist architektonisch: repo-lokale Config und Routing zeigen Agents auf kanonische Truth-Dokumente, während host-native Workflows jedem unterstützten Agent einen eigenen Weg geben, dieselben Truthmark-Prozeduren auszuführen.
285
+
286
+ Generierte Workflow-Oberflächen enthalten Truthmark-Versionsmarker. Nach einem Upgrade von Truthmark erneut ausführen:
287
+
288
+ ```bash
289
+ truthmark init
290
+ ```
291
+
292
+ Prüfe danach die generierten Diffs.
293
+
294
+ ## Unterstützte Agentenplattformen
295
+
296
+ Die Standardkonfiguration enthält jede unterstützte Plattform.
297
+
298
+ Entferne Plattformen, die du nicht nutzt, aus `.truthmark/config.yml`, und führe danach erneut aus:
299
+
300
+ ```bash
301
+ truthmark init
302
+ ```
303
+
304
+ | Plattform-Configname | Generierte Oberfläche | Aufrufform |
305
+ | --- | --- | --- |
306
+ | `codex` | `.codex/skills/truthmark-*/`, `.codex/agents/` | `/truthmark-*` oder `$truthmark-*` |
307
+ | `claude-code` | `.claude/skills/truthmark-*/`, `.claude/agents/`, `CLAUDE.md` | `/truthmark-*` |
308
+ | `github-copilot` | `.github/skills/truthmark-*/`, `.github/prompts/`, `.github/agents/`, `.github/copilot-instructions.md` | `/truthmark-*` in unterstützten Copilot-IDEs; `@truth-*` Custom Agents in Copilot CLI |
309
+ | `opencode` | `.opencode/skills/truthmark-*/`, `.opencode/agents/` | `/skill truthmark-*` |
310
+ | `gemini-cli` | `.gemini/skills/truthmark-*/`, `.gemini/commands/truthmark/`, `.gemini/agents/`, `GEMINI.md` | `/truthmark:*` |
311
+
312
+ Unbekannte Plattformnamen sind Config-Fehler.
313
+
314
+ Das Entfernen einer Plattform stoppt künftige Aktualisierungen für diese Plattform. Es löscht zuvor generierte Dateien nicht.
315
+
316
+ ## KI-orientierte Workflows
317
+
318
+ Diese Workflows werden in unterstützte KI-Coding-Hosts installiert.
319
+
320
+ Sie werden von Agenten oder Agenten-Hosts während der Repository-Arbeit genutzt. Sie sind keine Top-Level-Shell-Befehle.
321
+
322
+ | Workflow | Richtung | Nutze ihn, wenn | Schreibgrenze |
323
+ | --- | --- | --- | --- |
324
+ | Truth Structure | topology-first | Die Standardroute zu breit ist, Ownership mehrere Bereiche umfasst oder Routendateien noch auf Platzhalter zeigen. | Erstellt oder repariert Routing und Starter-Truth-Dokumente. |
325
+ | Truth Document | implementation-first | Verhalten bereits im Code existiert, aber kanonische Truth-Dokumente fehlen oder schwach sind. | Schreibt nur Truth-Dokumente und Routing. Funktionaler Code darf nicht geändert werden. |
326
+ | Truth Sync | code-first | Funktionaler Code geändert wurde und zugeordnete Truth-Dokumente vor der Übergabe aktualisiert werden müssen könnten. | Aktualisiert Truth-Dokumente. Funktionaler Code darf von Truth Sync nicht umgeschrieben werden. |
327
+ | Truth Preview | read-only | Der Agent vor Änderungen wahrscheinliches Routing einschätzen muss. | Liest nur. Autorisiert keine Schreibzugriffe. |
328
+ | Truth Realize | doc-first | Produkt- oder Architektur-Truth-Dokumente führen und Code daran angepasst werden soll. | Aktualisiert nur Code. Der Agent darf die Truth-Dokumente, die er realisiert, nicht bearbeiten. |
329
+ | Truth Check | audit-first | Ein Reviewer oder Agent die Gesundheit der Repository-Wahrheit auditieren muss. | Auditiert und berichtet. |
330
+ | Truthmark Portal | presentation-only | Ein Mensch ausdrücklich eine durchsuchbare statische HTML-Portalansicht über Repository-Truth-Dokumente anfordert. | Schreibt generierte nicht-kanonische statische Dateien nur unter dem konfigurierten Portal-Ausgabeverzeichnis. |
331
+
332
+ ### Wichtige Unterscheidung
173
333
 
174
- Die meisten Nutzer sollten Truth Sync nicht direkt aufrufen müssen. Entscheidend ist, dass der installierte Agenten-Workflow Truth Sync als Abschlusskontrolle behandelt, wenn funktionaler Code geändert wurde. Der normale Ablauf ist:
334
+ Verwechsle diese zwei Oberflächen nicht:
335
+
336
+ | Oberfläche | Genutzt von | Beispiel | Bedeutung |
337
+ | --- | --- | --- | --- |
338
+ | Menschen-CLI | Menschen, Skripte, CI-ähnliche Checks | `truthmark check` | Truth-Artefakte des Repositorys im Terminal validieren. |
339
+ | KI-orientierter Workflow | Coding-Agenten und Agenten-Hosts | `/truthmark-check` | Einen Agenten bitten, den installierten Audit-Workflow auszuführen. |
340
+
341
+ Die Namen sind absichtlich verwandt, aber die Oberflächen sind unterschiedlich.
342
+
343
+ ## Normale KI-gestützte Codeänderung
344
+
345
+ Die meisten Nutzer sollten Truth Sync nicht jedes Mal manuell aufrufen müssen.
346
+
347
+ Truth Sync ist die installierte Abschlusskontrolle für funktionale Codeänderungen.
348
+
349
+ ```text
350
+ agent ändert funktionalen Code
351
+ agent führt relevante Tests aus oder fordert sie an
352
+ installierter Workflow erkennt, dass funktionaler Code geändert wurde
353
+ Truth Sync prüft zugeordnete Truth-Dokumente
354
+ agent aktualisiert Truth-Dokumente bei Bedarf
355
+ Mensch prüft Code-Diff + Truth-Diff
356
+ ```
357
+
358
+ Der direkte Aufruf ist trotzdem nützlich für Fehlersuche, frühes Synchronisieren oder eine explizite Übergabe:
175
359
 
176
360
  ```text
177
- agent ändert funktionalen code
178
- relevante tests laufen
179
- der installierte truth-sync-workflow läuft, bevor der agent fertig ist
180
- truth-doc-diff prüfen, falls einer erzeugt wurde
181
- arbeit committen oder übergeben
361
+ /truthmark-sync die Repository-Wahrheit jetzt vor der Übergabe synchronisieren
182
362
  ```
183
363
 
184
- Truth Sync ist code-first: Code führt, Wahrheitsdokumente folgen, und Truth Sync darf funktionalen Code nicht umschreiben. Seine Hauptaufgabe ist, über den installierten Agenten-Workflow als Abschlusskontrolle zu laufen, wenn funktionaler Code geändert wurde. Direkte Aufrufe sind vor allem für Fehlersuche, frühe Synchronisierung vor einer Übergabe oder bewusstes Ausführen des Workflows gedacht.
364
+ ## Bestehendes Verhalten ohne Doku
185
365
 
186
- Codex, Claude Code und unterstützte Copilot-IDEs können es mit `/truthmark-sync` aufrufen. Hosts im OpenCode-Stil können `/skill truthmark-sync` verwenden.
366
+ Nutze Truth Document, wenn die Implementierung bereits existiert, aber die Repository-Wahrheit unvollständig ist.
187
367
 
188
368
  ```text
189
- /truthmark-sync die repository-wahrheit jetzt vor der übergabe synchronisieren
369
+ /truthmark-document das implementierte Session-Timeout-Verhalten unter docs/truth/authentication dokumentieren
190
370
  ```
191
371
 
192
- ### Doc-first-Änderungen
372
+ Truth Document prüft Implementierung, Tests, Routendateien und vorhandene Dokumente als Evidenz.
193
373
 
194
- Nutze das, wenn eine Produkt- oder Architekturentscheidung in der Doku beginnt:
374
+ Es schreibt nur Truth-Dokumente und Routing.
375
+
376
+ Es darf keinen funktionalen Code ändern.
377
+
378
+ ## Doc-first-Änderungen
379
+
380
+ Nutze Truth Realize, wenn eine Produkt- oder Architekturentscheidung in Dokumenten beginnt und Code daran angepasst werden soll.
195
381
 
196
382
  ```text
197
- benutzer bearbeitet wahrheitsdokumente
198
- benutzer ruft truth realize ausdrücklich auf
199
- agent liest wahrheitsdokumente und relevanten code
200
- agent aktualisiert nur code
201
- relevante tests laufen
202
- arbeit committen oder übergeben
383
+ /truthmark-realize docs/truth/authentication/session-timeout.md in Code realisieren
203
384
  ```
204
385
 
205
- Truth Realize ist manuell und doc-first: Wahrheitsdokumente führen, Code folgt, und der Agent darf die Wahrheitsdokumente, die er realisiert, nicht bearbeiten.
386
+ Truth Realize ist doc-first.
387
+
388
+ Die Truth-Dokumente führen. Der Code folgt.
206
389
 
207
- Codex, Claude Code und unterstützte Copilot-IDEs können es mit `/truthmark-realize` aufrufen. Hosts im OpenCode-Stil können `/skill truthmark-realize` verwenden.
390
+ Der Agent darf die Truth-Dokumente, die er realisiert, nicht bearbeiten.
391
+
392
+ ## Read-only-Routing-Preview
393
+
394
+ Nutze Truth Preview vor einer Änderung, wenn der Agent wahrscheinliches Routing verstehen muss.
208
395
 
209
396
  ```text
210
- /truthmark-realize docs/truth/authentication/session-timeout.md in code umsetzen
397
+ /truthmark-preview das wahrscheinliche Truth-Routing für Änderungen an der Billing-API prüfen
211
398
  ```
212
399
 
213
- ## Was es installiert
400
+ Truth Preview ist read-only.
214
401
 
215
- Truthmark hält die dauerhafte Workflow-Fläche klein und repository-nativ. Nach `truthmark init` trägt das Repository selbst Routing, Regeln und installierte Workflow-Flächen, sodass Teams nicht nur auf die lokale Konfiguration einer einzelnen Person angewiesen sind.
402
+ Es ist Auswahl- und Planungshilfe, keine Schreibautorisierung und kein Ersatz für Truth Check.
216
403
 
217
- Truthmark installiert zwei getrennte Oberflächen:
404
+ ## Repository-Truth-Audit
218
405
 
219
- - menschenorientierte CLI-Befehle, die Menschen oder CI ausführen, um das Repository zu konfigurieren, installierte Dateien zu aktualisieren, Truth-Artefakte zu validieren und optional abgeleiteten Review-Kontext zu erzeugen
220
- - Agenten-Workflow-Flächen, die Coding-Agenten oder Agenten-Hosts während Implementierungsworkflows aufrufen; sie sind keine zusätzlichen täglichen Terminalbefehle für Menschen
406
+ Nutze Truth Check, wenn du einen agentenorientierten Audit-Workflow möchtest.
221
407
 
222
- - `.truthmark/config.yml` für den maschinenlesbaren, festgeschriebenen Hierarchievertrag
223
- - `docs/truthmark/areas.md` für den Root-Routenindex
224
- - `docs/truthmark/areas/**/*.md` für delegierte untergeordnete Routendateien
225
- - `docs/templates/behavior-doc.md` sowie die weiteren typspezifischen Vorlagen unter `docs/templates/` für die editierbaren Truth-Doc-Standards der generierten Workflows
226
- - verwaltete Instruktionsblöcke für konfigurierte Plattformen wie `AGENTS.md`, `CLAUDE.md`, Copilot-Anweisungen und `GEMINI.md`
227
- - host-native Skills, Prompts oder Commands für Truth Structure, Truth Document, Truth Sync, Truth Preview, Truth Realize und Truth Check
228
- - projektbezogene schreibgeschützte Codex-, Claude-Code-, GitHub-Copilot- und OpenCode-Prüfer plus geleaste `truth-doc-writer`-Agenten, wo Hosts Agenten unterstützen, unter `.codex/agents/`, `.claude/agents/`, `.github/agents/` und `.opencode/agents/` für workflow-eigene Audits und vom Parent geleaste Dokument-Shards
408
+ ```text
409
+ /truthmark-check Routing und Truth-Coverage vor dem Review auditieren
410
+ ```
229
411
 
230
- Die installierten Workflow-Flächen sind die Runtime:
412
+ Nutze die menschenorientierte CLI, wenn du Terminalvalidierung möchtest:
231
413
 
232
- - Truth Structure erstellt oder repariert Area-Routing und erste Wahrheitsdokumente.
233
- - Truth Document erstellt oder repariert Wahrheitsdokumente für bereits implementiertes Verhalten.
234
- - Truth Sync hält zugeordnete Wahrheitsdokumente bei funktionalen Änderungen synchron.
235
- - Truth Preview zeigt wahrscheinliches Workflow-Routing vor Änderungen an, ohne Dateien zu schreiben.
236
- - Truth Realize aktualisiert Code so, dass er zu den Wahrheitsdokumenten passt.
237
- - Truth Check auditiert die Gesundheit der Repository-Wahrheit.
414
+ ```bash
415
+ truthmark check
416
+ ```
238
417
 
239
- `README.md`-Dateien von Features sind Indizes. Truth Sync soll begrenzte Blattdokumente für aktuelles Verhalten lesen und aktualisieren. Generierte Workflow-Flächen bewahren die Autorität der Repository-Regeln, während sie Implementierungscode und kanonische Wahrheitsdokumente als Belege für aktuelles Verhalten behandeln.
418
+ Beides ist nützlich. Es ist nicht dieselbe Oberfläche.
240
419
 
241
- Generierte Flächen werden von Truthmark verwaltet, enthalten einen Versionsmarker und können mit `truthmark init` aktualisiert werden.
420
+ ## Menschenorientierte CLI-Befehle
242
421
 
243
- ## Befehle
422
+ Die meisten Maintainer beginnen mit drei Befehlen.
244
423
 
245
- Truthmark V1 hält die Terminal-CLI fokussiert. Die meisten menschlichen Nutzer brauchen nur Einrichtung, Aktualisierung und Validierung:
424
+ | Befehl | Zweck |
425
+ | --- | --- |
426
+ | `truthmark config` | Erstellt `.truthmark/config.yml`. Schreibt nur diese Datei, außer `--stdout` wird verwendet. |
427
+ | `truthmark init` | Installiert oder aktualisiert konfigurierte Workflow-Oberflächen aus der geprüften Config. |
428
+ | `truthmark check` | Validiert Config, Autorität, Routing, entscheidungstragende Dokumente, Frontmatter, interne Links, Branch-Scope, generierte Oberflächen, Freshness und Coverage-Diagnostik. |
246
429
 
247
- | Menschenorientierter CLI-Befehl | Zweck |
248
- | -------------------------------- | ----- |
249
- | `truthmark config` | Erstellt `.truthmark/config.yml`; schreibt nur diese Datei, außer `--stdout` wird verwendet. |
250
- | `truthmark init` | Installiert oder aktualisiert lokale Workflow-Dateien aus der geprüften Konfiguration. |
251
- | `truthmark check` | Validiert Konfiguration, Autorität, Routing, entscheidungstragende Dokumente, Frontmatter, interne Links, Branch-Scope und Coverage-Diagnostik. |
430
+ Optionale Repository-Intelligence-Helfer erzeugen abgeleiteten Review-Kontext für den aktiven Checkout. Generierte Workflow-Skill-Pakete können außerdem Helper-Manifeste und Helper-Policies bereitstellen, die installierte `truthmark validate ... --json` CLI-Validatoren aufrufen; diese Helpers sind Beschleuniger, keine im Repository gebündelten lokalen Skripte und keine Quellen der Wahrheit. Eigenständige Copilot-Prompts und Gemini-Commands verwenden denselben CLI-Validator-Vertrag, wenn der installierte Runner verfügbar ist; andernfalls melden sie einen sichtbaren übersprungenen Helper-Status und führen eine manuelle Validierung durch.
252
431
 
253
- Die übrigen CLI-Befehle sind optionale Repository-Intelligence-Helfer. Sie erzeugen abgeleiteten Review-Kontext für den aktiven Checkout; sie sind keine Quellen der Wahrheit:
432
+ Sie sind keine Quellen der Wahrheit.
254
433
 
255
- | Optionaler CLI-Befehl | Zweck |
256
- | --------------------- | ----- |
434
+ | Befehl | Zweck |
435
+ | --- | --- |
257
436
  | `truthmark index` | Baut RepoIndex- und RouteMap-JSON für den aktiven Checkout. |
258
- | `truthmark impact --base <ref>` | Ordnet geänderte Dateien den gerouteten Truth-Dokumenten, zuständigen Routen, nahen Tests und öffentlichen Symbolen zu. |
259
- | `truthmark context --workflow <workflow> [--base <ref>]` | Erzeugt ein begrenztes ContextPack für Truth Sync, Truth Document oder Truth Realize. `--format markdown` rendert eine menschenlesbare Fassung. |
437
+ | `truthmark impact --base <ref>` | Ordnet geänderte Dateien gerouteten Truth-Dokumenten, besitzenden Routen, nahen Tests und öffentlichen Symbolen zu. |
438
+ | `truthmark context --workflow <workflow> [--base <ref>]` | Erzeugt ein begrenztes ContextPack für Truth Sync, Truth Document oder Truth Realize. Nutze `--format markdown` für eine menschenlesbare Fassung. |
439
+
440
+ Strukturierte Ausgabe ist mit `--json` verfügbar, wo sie unterstützt wird.
441
+
442
+ ## Truthmark Portal
443
+
444
+ Truthmark Portal ist ein optionaler Präsentations-Workflow für Teams, die eine menschenlesbare Site über ihren festgeschriebenen Truth-Dokumenten möchten.
445
+
446
+ Er ist bewusst vom Kern-Truth-Workflow getrennt:
447
+
448
+ - Markdown-Truth-Dokumente bleiben kanonisch.
449
+ - Generiertes Portal-HTML dient nur der Präsentation.
450
+ - Portal wird nur manuell ausgeführt; es läuft nicht als Completion-Gate, Truth-Sync-Schritt, `truthmark check`-Schritt oder automatischer Post-Change-Hook.
451
+ - Portal-Schreibzugriffe bleiben im konfigurierten Ausgabeverzeichnis, sofern der Nutzer den Scope nicht ausdrücklich ändert.
452
+ - Generierte Seiten sollten lokale Assets, Quellen-Provenance und einen sichtbaren Markdown-ist-kanonisch-Hinweis verwenden.
453
+
454
+ Aktiviere es mit dem namespaced Config-Block:
455
+
456
+ ```yaml
457
+ truthmark-portal:
458
+ enabled: true
459
+ output: docs/truthmark-portal
460
+ template: default
461
+ ```
462
+
463
+ Dann erneut ausführen:
464
+
465
+ ```bash
466
+ truthmark init
467
+ ```
468
+
469
+ Wenn aktiviert, installiert Truthmark host-native Portal-Workflow-Oberflächen für die konfigurierten Plattformen, etwa `/truthmark-portal` oder `/truthmark:portal` je nach Agenten-Host.
260
470
 
261
- Alle oben genannten CLI-Befehle unterstützen `--json`, wenn strukturierte Ausgabe für Automatisierung nützlich ist.
471
+ ## Konfiguration
262
472
 
263
- Truth Structure, Truth Document, Truth Sync, Truth Preview, Truth Realize und Truth Check sind installierte Agenten-Workflows, keine täglichen Top-Level-CLI-Befehle.
473
+ Truthmark ist config-first.
264
474
 
265
- Sie laufen über die konfigurierten Agenten-Host-Flächen, zum Beispiel Codex/Claude/Copilot `/truthmark-*`, OpenCode `/skill truthmark-*` oder Gemini `/truthmark:*`.
475
+ Die wichtigste Config-Datei ist:
266
476
 
267
- Diese Aufrufe wirken befehlsartig, weil Agenten-Hosts Skills über Slash-Commands bereitstellen. Behandle sie als Anweisungen an einen Agenten, nicht als Terminalbefehle, die Menschen ausführen sollen.
477
+ ```text
478
+ .truthmark/config.yml
479
+ ```
480
+
481
+ Neue Repositories sollten ausführen:
482
+
483
+ ```bash
484
+ truthmark config
485
+ ```
486
+
487
+ Prüfe danach die generierte Config, bevor du ausführst:
488
+
489
+ ```bash
490
+ truthmark init
491
+ ```
492
+
493
+ Wichtige Config-Bereiche sind:
494
+
495
+ | Config-Bereich | Zweck |
496
+ | --- | --- |
497
+ | `version` | Version des Config-Vertrags. |
498
+ | `platforms` | Agenten-Hosts, die plattformspezifische generierte Oberflächen erhalten sollen. |
499
+ | `docs.layout` | Aktueller Docs-Layoutmodus. |
500
+ | `docs.roots` | Benannte kanonische Dokumentationswurzeln. |
501
+ | `docs.routing.root_index` | Pfad zum Root-Routenindex. |
502
+ | `docs.routing.area_files_root` | Verzeichnis für delegierte untergeordnete Routendateien. |
503
+ | `docs.routing.default_area` | Dateiname des initial erzeugten untergeordneten Routings ohne Erweiterung. |
504
+ | `docs.routing.max_delegation_depth` | Aktuelle maximale Routing-Delegationstiefe. |
505
+ | `truthmark-portal` | Optionale manuelle Präsentations-Workflow-Einstellungen: `enabled`, `output` und `template`. |
506
+ | `authority` | Geordnete kanonische Dokumente und Globs, die als Repository-Truth-Autorität dienen. |
507
+ | `instruction_targets` | Dateien, die gemeinsam verwaltete Instruktionsblöcke erhalten, etwa `AGENTS.md`. |
508
+ | `frontmatter.required` | Metadatenfelder, die bei Fehlen Error-Diagnostik erzeugen. |
509
+ | `frontmatter.recommended` | Metadatenfelder, die bei Fehlen Review-Diagnostik erzeugen. |
510
+ | `ignore` | Glob-Muster, die von relevanten Checks und Routing-Logik ausgeschlossen sind. |
511
+
512
+ ## Repository-Truth-Routing
513
+
514
+ Truthmark ordnet Codeoberflächen Truth-Dokumenten zu.
515
+
516
+ Die wichtigsten Routendateien sind:
268
517
 
269
518
  ```text
270
- /truthmark-check routing und truth-abdeckung vor der review prüfen
519
+ docs/truthmark/areas.md
520
+ docs/truthmark/areas/**/*.md
271
521
  ```
272
522
 
273
- ## Warum es existiert
523
+ Eine Route sagt dem Agenten:
274
524
 
275
- Die meisten KI-Coding-Workflows optimieren für die nächste Antwort. Truthmark optimiert für die nächste Übergabe.
276
- Es geht davon aus, dass ernsthafte Teams Folgendes brauchen:
525
+ - welche Codeoberfläche zu einem Bereich gehört
526
+ - welche Truth-Dokumente diesen Bereich besitzen
527
+ - wann Truth aktualisiert werden sollte
528
+ - welche Art von Truth-Dokument beteiligt ist
277
529
 
278
- - branch-spezifische Produktwahrheit
279
- - dauerhafte Architektur- und API-Entscheidungen
280
- - explizite Zuständigkeit zwischen Dokumentation und Code
281
- - sichere Schreibgrenzen für Agenten
282
- - normale Git-Diffs, die Menschen prüfen können
283
- - lesbares Markdown, das Teammitglieder ohne Spezialwerkzeuge inspizieren können
284
- - Wahrheit, die mit dem Branch mitwandert, statt in verborgenem Sitzungszustand zu leben
285
- - Workflows, die auch funktionieren, wenn das Paket nicht global installiert ist
530
+ Das Standard-Scaffold beginnt breit. Bestehende Repositories sollten die Standardroute meist in echte Ownership-Bereiche aufteilen.
286
531
 
287
- ## Projektstatus
532
+ Beispiel:
533
+
534
+ ```text
535
+ /truthmark-structure die breite repository-area in frontend, backend, billing und deployment aufteilen
536
+ ```
537
+
538
+ Gutes Routing gibt Truth Sync präzise Ziele.
539
+
540
+ Schlechtes Routing zwingt Agenten zum Raten.
541
+
542
+ ## Was Truthmark installiert
543
+
544
+ Truthmark installiert eine kompakte, repository-native Truth-Schicht.
545
+
546
+ Das geschieht in vier Schichten:
547
+
548
+ - Config und Routing für Ownership-Grenzen
549
+ - kanonische Truth-Dokumente und Starter-Templates
550
+ - kompakte verwaltete Instruction-Blöcke für repositoryweiten Agent-Kontext
551
+ - host-native Workflow-Pakete, Commands, Prompts und Verifier-Agents für die in der Config aktivierten Plattformen
552
+
553
+ Truthmark bewahrt manuellen Inhalt außerhalb verwalteter Instruktionsblöcke.
554
+
555
+ Generierte Workflow-Oberflächen werden von Truthmark verwaltet und können durch erneutes Ausführen aktualisiert werden:
556
+
557
+ ```bash
558
+ truthmark init
559
+ ```
560
+
561
+ ## Subagents und begrenzte Evidenzprüfungen
562
+
563
+ Wo der Host es unterstützt, kann Truthmark projektbezogene Prüfer-Agenten und einen geleasten `truth-doc-writer` installieren.
564
+
565
+ Diese helfen, große Truth-Aufgaben begrenzt zu halten:
566
+
567
+ - Route Auditors prüfen Route-Ownership
568
+ - Claim Verifiers prüfen, ob Dokumentclaims durch Evidenz gestützt sind
569
+ - Doc Reviewers prüfen Truth-Doc-Qualität
570
+ - geleaste Doc Writers bearbeiten begrenzte Truth-Doc-Schreib-Shards
571
+
572
+ Der Parent-Workflow besitzt weiterhin finale Interpretation, Schreibgrenzen, Diff-Validierung und Abnahme.
573
+
574
+ Das ist wichtig: Subagents helfen bei begrenzter Evidenzarbeit. Sie ersetzen den Haupt-Workflow-Vertrag nicht.
575
+
576
+ ## Review-Schleife
577
+
578
+ Truthmark ist für normalen Git-Review entworfen.
579
+
580
+ Eine gute KI-gestützte Übergabe sollte Folgendes zeigen:
581
+
582
+ ```text
583
+ Code-Diff
584
+ Test-Evidenz
585
+ Truth-Doc-Diff, falls nötig
586
+ Routing-Änderungen, falls nötig
587
+ Agentenbericht
588
+ ```
589
+
590
+ Der Reviewer sollte beantworten können:
591
+
592
+ - Welcher Code hat sich geändert?
593
+ - Welche Truth-Dokumente besitzen diesen Code?
594
+ - Mussten diese Dokumente aktualisiert werden?
595
+ - Falls nicht, warum nicht?
596
+ - Ist der Agent innerhalb der Workflow-Schreibgrenze geblieben?
597
+ - Sind Test- oder Verifikationsevidenz enthalten?
598
+
599
+ ## Beispiele
600
+
601
+ ### Ein Repository initialisieren
602
+
603
+ ```bash
604
+ npm install -g truthmark
605
+ truthmark config
606
+ truthmark init
607
+ truthmark check
608
+ ```
609
+
610
+ ### Unbenutzte Agentenplattformen entfernen
611
+
612
+ Bearbeiten:
613
+
614
+ ```text
615
+ .truthmark/config.yml
616
+ ```
617
+
618
+ Danach erneut ausführen:
619
+
620
+ ```bash
621
+ truthmark init
622
+ truthmark check
623
+ ```
624
+
625
+ ### Breites Routing aufteilen
626
+
627
+ ```text
628
+ /truthmark-structure die breite repository-area in auth, billing, notifications und deployment aufteilen
629
+ ```
630
+
631
+ ### Implementiertes Verhalten dokumentieren
632
+
633
+ ```text
634
+ /truthmark-document den implementierten Password-Reset-Flow unter docs/truth/authentication dokumentieren
635
+ ```
288
636
 
289
- Truthmark ist kein Memory-Server und kein MCP-Server. Es ist eine Repository-Praxis, verpackt als kleiner CLI-Installer plus agent-native Workflow-Flächen, die KI-Workflow-Regeln in Repository-Infrastruktur verwandeln.
637
+ ### Nach Codeänderungen synchronisieren
290
638
 
291
- V1 bietet derzeit:
639
+ ```text
640
+ /truthmark-sync die Repository-Wahrheit jetzt vor der Übergabe synchronisieren
641
+ ```
642
+
643
+ ### Eine doc-first Entscheidung realisieren
644
+
645
+ ```text
646
+ /truthmark-realize docs/truth/billing/invoice-retry-policy.md in Code realisieren
647
+ ```
648
+
649
+ ### Truth-Gesundheit im Terminal auditieren
650
+
651
+ ```bash
652
+ truthmark check
653
+ ```
654
+
655
+ ### Branch-Impact-Kontext erzeugen
656
+
657
+ ```bash
658
+ truthmark impact --base main
659
+ ```
660
+
661
+ ### Workflow-Kontext erzeugen
662
+
663
+ ```bash
664
+ truthmark context --workflow truth-sync --base main --format markdown
665
+ ```
666
+
667
+ ### Optionalen Portal-Workflow aktivieren
668
+
669
+ ```yaml
670
+ truthmark-portal:
671
+ enabled: true
672
+ output: docs/truthmark-portal
673
+ template: default
674
+ ```
675
+
676
+ ```bash
677
+ truthmark init
678
+ ```
679
+
680
+ Bitte den Agenten-Host anschließend ausdrücklich, den installierten Portal-Workflow auszuführen, wenn die statische Präsentationssite erzeugt oder aktualisiert werden soll.
681
+
682
+ ## Projektstatus
683
+
684
+ Truthmark V1 bietet derzeit:
292
685
 
293
686
  - `truthmark config`
294
687
  - `truthmark init`
@@ -296,15 +689,59 @@ V1 bietet derzeit:
296
689
  - `truthmark index`
297
690
  - `truthmark impact`
298
691
  - `truthmark context`
299
- - verwaltete `AGENTS.md`-Workflow-Anweisungen
300
- - generierte Truth Structure-, Truth Document-, Truth Sync-, Truth Preview-, Truth Realize- und Truth Check-Skill-Flächen für konfigurierte Agenten-Hosts
301
692
  - Branch-Scope-Metadaten
302
- - Diagnostik für Konfiguration, Autorität, Routing, Entscheidungsstruktur, Frontmatter, Links, Freshness und polyglotte Abdeckung
303
- - abgeleitete RepoIndex-, RouteMap-, ImpactSet- und ContextPack-Artefakte für schnellere lokale Prüfung, wenn die CLI verfügbar ist
693
+ - verwaltete Instruktionsblöcke
694
+ - generierte Truth-Structure-Workflow-Oberflächen
695
+ - generierte Truth-Document-Workflow-Oberflächen
696
+ - generierte Truth-Sync-Workflow-Oberflächen
697
+ - generierte Truth-Preview-Workflow-Oberflächen
698
+ - generierte Truth-Realize-Workflow-Oberflächen
699
+ - generierte Truth-Check-Workflow-Oberflächen
700
+ - optionale generierte Truthmark-Portal-Workflow-Oberflächen
701
+ - Diagnostik für Route, Autorität, Entscheidungsstruktur, Frontmatter, Links, Freshness, generierte Oberflächen und Coverage
702
+ - abgeleitete RepoIndex-, RouteMap-, ImpactSet- und ContextPack-Artefakte
703
+ - host-spezifische Oberflächen für Codex, Claude Code, GitHub Copilot, OpenCode und Gemini CLI
704
+
705
+ ## Entwicklung
706
+
707
+ Abhängigkeiten installieren:
708
+
709
+ ```bash
710
+ npm install
711
+ ```
712
+
713
+ Die lokale Entwicklungs-CLI ausführen:
714
+
715
+ ```bash
716
+ npm run dev -- init
717
+ npm run dev -- check
718
+ ```
719
+
720
+ Den vollständigen Projektcheck ausführen:
721
+
722
+ ```bash
723
+ npm run check
724
+ ```
725
+
726
+ Nützliche Skripte:
727
+
728
+ | Skript | Zweck |
729
+ | --- | --- |
730
+ | `npm run dev` | Führt den TypeScript-CLI-Einstiegspunkt mit `tsx` aus. |
731
+ | `npm run build` | Baut das Paket. |
732
+ | `npm run lint` | Führt ESLint aus. |
733
+ | `npm run typecheck` | Führt TypeScript-Checks aus. |
734
+ | `npm run test` | Führt Tests aus. |
735
+ | `npm run check` | Führt Lint, Typecheck, Tests und Build aus. |
736
+ | `npm run release:check` | Führt release-orientierte Validierung aus. |
737
+
738
+ Wenn du Truthmark selbst änderst, siehe [CONTRIBUTORS.md](CONTRIBUTORS.md).
304
739
 
305
740
  ## Dokumentation
306
741
 
307
- Die Root-README ist für Menschen gedacht, die das Paket evaluieren und ausprobieren. Detaillierte funktionale und geschäftliche Spezifikationen liegen unter `docs/`:
742
+ Die README ist der schnelle Pfad für Evaluation und Setup.
743
+
744
+ Aktuelles Verhalten im Detail lebt unter `docs/`:
308
745
 
309
746
  - [Dokumentationsindex](docs/README.md)
310
747
  - [Architekturüberblick](docs/architecture/overview.md)
@@ -314,21 +751,62 @@ Die Root-README ist für Menschen gedacht, die das Paket evaluieren und ausprobi
314
751
  - [Installierte Workflows](docs/truth/workflows/overview.md)
315
752
  - [Leitfaden zur Pflege von Repository-Wahrheit](docs/standards/maintaining-repository-truth.md)
316
753
 
317
- Aktuelles Verhalten gehört in den oben genannten kanonischen Dokumentationsbaum.
754
+ ## Designgrenzen
318
755
 
319
- ## Nicht-Ziele
756
+ Truthmark ist absichtlich klein.
320
757
 
321
- Truthmark V1 ist nicht:
758
+ Es ist nicht:
322
759
 
323
760
  - ein gehosteter Dienst
324
761
  - ein MCP-Server
325
762
  - eine Vektordatenbank
326
- - ein Generator für Dokumentations-Websites
763
+ - ein kanonischer Dokumentations-Website-Generator oder eine gehostete Docs-Plattform
327
764
  - ein CI- oder PR-Enforcement-Produkt
328
765
  - ein Ersatz für Tests, Code Review oder technische Führung
329
766
  - eine autonome Code-Rewrite-Engine
767
+ - ein Framework für Modelltraining oder Fine-Tuning
768
+ - eine verborgene Memory-Schicht
769
+
770
+ Diese Grenzen sind Teil des Produkts.
771
+
772
+ Truthmark hält den Workflow lokal, festgeschrieben, branch-gebunden und prüffähig.
773
+
774
+ ## Sicherheit und Review-Disziplin
775
+
776
+ Truthmark hilft dem Repository, ehrlich zu bleiben. Es beweist nicht, dass der Code korrekt ist.
777
+
778
+ Teams sollten weiterhin:
330
779
 
331
- Es ist ein leichtgewichtiger Weg, lokale KI-Coding-Agenten dazu zu bringen, die Wahrheit zu respektieren, die dein Team in Git pflegt.
780
+ - relevante Tests ausführen
781
+ - funktionale Codeänderungen prüfen
782
+ - Truth-Doc-Änderungen prüfen
783
+ - Secrets aus der Dokumentation heraushalten
784
+ - repository-spezifische Instruktionen außerhalb verwalteter Blöcke halten
785
+ - Diffs generierter Workflow-Oberflächen nach Upgrades prüfen
786
+ - menschliche Ownership über Produkt- und Architekturentscheidungen behalten
787
+
788
+ Truthmark macht Agentenkontext sichtbar. Es ersetzt menschliches Urteil nicht.
789
+
790
+ ## Roadmap-Richtung
791
+
792
+ Die aktuelle Zukunftsrichtung betont:
793
+
794
+ - stärkere Evidenzberichte in `truthmark check`
795
+ - klarere Adoptionsbeispiele
796
+ - Beispiel-Repositories mit echten Truth-Sync-Zyklen
797
+ - Migrationsleitfäden für Teams, die bereits Agenten-Instruktionsdateien nutzen
798
+ - Konformitätstests für generierte Host-Oberflächen
799
+ - route-aware Hinweise auf stale truth
800
+ - begrenzte Implementierungschecklisten für doc-first Arbeit
801
+
802
+ Der Schwerpunkt bleibt gleich:
803
+
804
+ ```text
805
+ Repository-Wahrheit
806
+ agent-native Workflows
807
+ Git-Review
808
+ branch-gebundener Kontext
809
+ ```
332
810
 
333
811
  ## Lizenz
334
812