truthmark 1.4.0 → 1.5.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 +623 -193
  2. package/README.es.md +624 -194
  3. package/README.md +614 -191
  4. package/README.ru.md +631 -201
  5. package/README.zh.md +630 -198
  6. package/dist/main.js +846 -39
  7. package/dist/main.js.map +1 -1
  8. package/package.json +1 -1
package/README.de.md CHANGED
@@ -1,294 +1,640 @@
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
128
129
  ```
129
130
 
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:
131
+ ### Den Repository-Wahrheitsvertrag erstellen
132
+
133
+ ```bash
134
+ truthmark config
135
+ ```
136
+
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.
144
+
145
+ ### Die Workflow-Oberflächen installieren
146
+
147
+ ```bash
148
+ truthmark init
149
+ ```
150
+
151
+ Das installiert oder aktualisiert:
147
152
 
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.
153
+ - Routendateien
154
+ - Truth-Doc-Scaffolding
155
+ - verwaltete Instruktionsblöcke
156
+ - KI-orientierte Workflow-Oberflächen für konfigurierte Plattformen
149
157
 
150
- ## Wie es läuft
158
+ ### Das Setup validieren
151
159
 
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.
160
+ ```bash
161
+ truthmark check
162
+ ```
163
+
164
+ Prüfe danach die generierten Dateien, bevor du committest.
153
165
 
154
- ### Vorhandenes Verhalten ohne Doku
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.
155
167
 
156
- Nutze das, wenn die Implementierung bereits existiert, aber die kanonischen Wahrheitsdokumente fehlen oder schwach sind:
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
+
198
+ ## Visueller Überblick
199
+
200
+ ![Truthmark-Funktionen](docs/assets/truthmark-features.png)
201
+
202
+ **Funktionen:** was Truthmark installiert und wie die Workflow-Oberfläche aufgeteilt ist.
203
+
204
+ ![Truthmark-Positionierung](docs/assets/truthmark-position.png)
205
+
206
+ **Positionierung:** wo Truthmark im Verhältnis zu Prompts, Memory und Spec-Workflows steht.
207
+
208
+ ![Truthmark-Sync-Ablauf](docs/assets/truthmark-syncflow.png)
209
+
210
+ **Sync-Ablauf:** wie Truth Sync normale Codeänderungen vor der Übergabe abschließt.
211
+
212
+ ## Warum Teams es nutzen
213
+
214
+ Truthmark ist für Teams, die bereits wissen, dass KI-Agenten Code erzeugen können.
215
+
216
+ Das nächste Problem ist Governance.
217
+
218
+ Nicht Governance als Zeremonie. Governance als einfache Frage:
219
+
220
+ > Erzählt das Repository nach dieser KI-gestützten Änderung noch die Wahrheit?
221
+
222
+ Truthmark hilft Teams, diese Frage mit festgeschriebenen Dateien, explizitem Routing und prüffähigen Diffs zu beantworten.
223
+
224
+ Es ist nützlich, wenn du Folgendes brauchst:
225
+
226
+ - weniger Dokumentationsdrift
227
+ - bessere Übergaben
228
+ - branch-spezifische Produktwahrheit
229
+ - dauerhaften Architektur- und API-Kontext
230
+ - explizite Ownership zwischen Dokumentation und Code
231
+ - sicherere Schreibgrenzen für Agenten
232
+ - prüffähigen Kontext statt verborgener Memory
233
+ - KI-Workflows, die weiterhin aus festgeschriebenen Repo-Dateien funktionieren
234
+
235
+ ## Wo Truthmark hineinpasst
236
+
237
+ Truthmark ersetzt keine Prompts, Memory, Specs, Tests oder Code Review.
238
+
239
+ Es gibt diesen Workflows einen dauerhaften Ort in Git.
240
+
241
+ | Bedarf | Besser passend |
242
+ | --- | --- |
243
+ | Bessere Ausgabe aus einer Agentensitzung | Besserer Prompt |
244
+ | Persönliche oder sitzungsbezogene Kontinuität | Memory-Tool |
245
+ | Plan-first Feature-Arbeit | Spec-Workflow |
246
+ | Branch-gebundene Wahrheit, die mit dem Code mitwandert | Truthmark |
247
+ | Korrektheit von Verhalten validieren | Tests und Review |
248
+ | KI-gestützte Kontextänderungen prüfen | Truthmark plus Git-Review |
249
+
250
+ Truthmarks Spur ist absichtlich eng:
167
251
 
168
252
  ```text
169
- /truthmark-document dokumentiere das implementierte session-timeout-verhalten unter docs/truth/authentication
253
+ Repository-Wahrheit explizit machen
254
+ sie zu Code routen
255
+ Agenten-Workflows darum installieren
256
+ das Ergebnis in Git prüffähig halten
257
+ ```
258
+
259
+ ## Wie Truthmark läuft
260
+
261
+ Truthmark läuft lokal gegen den aktiven Git-Worktree.
262
+
263
+ Die menschenorientierte CLI liest und schreibt Repository-Dateien und beendet sich danach.
264
+
265
+ 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.
266
+
267
+ Die Schichten greifen so ineinander:
268
+
269
+ ```mermaid
270
+ flowchart LR
271
+ Human["Human / CI"] --> CLI["Truthmark CLI"]
272
+ CLI --> Config["Config und Routing"]
273
+ CLI --> Truth["Kanonische Truth-Dokumente"]
274
+ CLI --> Surfaces["Generierte host-native Workflows"]
275
+ Surfaces --> Hosts["Codex / Claude Code / Copilot / OpenCode / Gemini"]
276
+ Hosts --> Worktree["Aktiver Git-Worktree"]
277
+ Hosts -->|"helper checks / validate / index"| CLI
278
+ Worktree --> Truth
279
+ ```
280
+
281
+ 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.
282
+
283
+ 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.
284
+
285
+ Generierte Workflow-Oberflächen enthalten Truthmark-Versionsmarker. Nach einem Upgrade von Truthmark erneut ausführen:
286
+
287
+ ```bash
288
+ truthmark init
289
+ ```
290
+
291
+ Prüfe danach die generierten Diffs.
292
+
293
+ ## Unterstützte Agentenplattformen
294
+
295
+ Die Standardkonfiguration enthält jede unterstützte Plattform.
296
+
297
+ Entferne Plattformen, die du nicht nutzt, aus `.truthmark/config.yml`, und führe danach erneut aus:
298
+
299
+ ```bash
300
+ truthmark init
170
301
  ```
171
302
 
172
- ### Normale Codeänderungen
303
+ | Plattform-Configname | Generierte Oberfläche | Aufrufform |
304
+ | --- | --- | --- |
305
+ | `codex` | `.codex/skills/truthmark-*/`, `.codex/agents/` | `/truthmark-*` oder `$truthmark-*` |
306
+ | `claude-code` | `.claude/skills/truthmark-*/`, `.claude/agents/`, `CLAUDE.md` | `/truthmark-*` |
307
+ | `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 |
308
+ | `opencode` | `.opencode/skills/truthmark-*/`, `.opencode/agents/` | `/skill truthmark-*` |
309
+ | `gemini-cli` | `.gemini/skills/truthmark-*/`, `.gemini/commands/truthmark/`, `.gemini/agents/`, `GEMINI.md` | `/truthmark:*` |
173
310
 
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:
311
+ Unbekannte Plattformnamen sind Config-Fehler.
312
+
313
+ Das Entfernen einer Plattform stoppt künftige Aktualisierungen für diese Plattform. Es löscht zuvor generierte Dateien nicht.
314
+
315
+ ## KI-orientierte Workflows
316
+
317
+ Diese Workflows werden in unterstützte KI-Coding-Hosts installiert.
318
+
319
+ Sie werden von Agenten oder Agenten-Hosts während der Repository-Arbeit genutzt. Sie sind keine Top-Level-Shell-Befehle.
320
+
321
+ | Workflow | Richtung | Nutze ihn, wenn | Schreibgrenze |
322
+ | --- | --- | --- | --- |
323
+ | 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. |
324
+ | 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. |
325
+ | 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. |
326
+ | Truth Preview | read-only | Der Agent vor Änderungen wahrscheinliches Routing einschätzen muss. | Liest nur. Autorisiert keine Schreibzugriffe. |
327
+ | 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. |
328
+ | Truth Check | audit-first | Ein Reviewer oder Agent die Gesundheit der Repository-Wahrheit auditieren muss. | Auditiert und berichtet. |
329
+
330
+ ### Wichtige Unterscheidung
331
+
332
+ Verwechsle diese zwei Oberflächen nicht:
333
+
334
+ | Oberfläche | Genutzt von | Beispiel | Bedeutung |
335
+ | --- | --- | --- | --- |
336
+ | Menschen-CLI | Menschen, Skripte, CI-ähnliche Checks | `truthmark check` | Truth-Artefakte des Repositorys im Terminal validieren. |
337
+ | KI-orientierter Workflow | Coding-Agenten und Agenten-Hosts | `/truthmark-check` | Einen Agenten bitten, den installierten Audit-Workflow auszuführen. |
338
+
339
+ Die Namen sind absichtlich verwandt, aber die Oberflächen sind unterschiedlich.
340
+
341
+ ## Normale KI-gestützte Codeänderung
342
+
343
+ Die meisten Nutzer sollten Truth Sync nicht jedes Mal manuell aufrufen müssen.
344
+
345
+ Truth Sync ist die installierte Abschlusskontrolle für funktionale Codeänderungen.
346
+
347
+ ```text
348
+ agent ändert funktionalen Code
349
+ agent führt relevante Tests aus oder fordert sie an
350
+ installierter Workflow erkennt, dass funktionaler Code geändert wurde
351
+ Truth Sync prüft zugeordnete Truth-Dokumente
352
+ agent aktualisiert Truth-Dokumente bei Bedarf
353
+ Mensch prüft Code-Diff + Truth-Diff
354
+ ```
355
+
356
+ Der direkte Aufruf ist trotzdem nützlich für Fehlersuche, frühes Synchronisieren oder eine explizite Übergabe:
175
357
 
176
358
  ```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
359
+ /truthmark-sync die Repository-Wahrheit jetzt vor der Übergabe synchronisieren
182
360
  ```
183
361
 
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.
362
+ ## Bestehendes Verhalten ohne Doku
185
363
 
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.
364
+ Nutze Truth Document, wenn die Implementierung bereits existiert, aber die Repository-Wahrheit unvollständig ist.
187
365
 
188
366
  ```text
189
- /truthmark-sync die repository-wahrheit jetzt vor der übergabe synchronisieren
367
+ /truthmark-document das implementierte Session-Timeout-Verhalten unter docs/truth/authentication dokumentieren
190
368
  ```
191
369
 
192
- ### Doc-first-Änderungen
370
+ Truth Document prüft Implementierung, Tests, Routendateien und vorhandene Dokumente als Evidenz.
193
371
 
194
- Nutze das, wenn eine Produkt- oder Architekturentscheidung in der Doku beginnt:
372
+ Es schreibt nur Truth-Dokumente und Routing.
373
+
374
+ Es darf keinen funktionalen Code ändern.
375
+
376
+ ## Doc-first-Änderungen
377
+
378
+ Nutze Truth Realize, wenn eine Produkt- oder Architekturentscheidung in Dokumenten beginnt und Code daran angepasst werden soll.
195
379
 
196
380
  ```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
381
+ /truthmark-realize docs/truth/authentication/session-timeout.md in Code realisieren
203
382
  ```
204
383
 
205
- Truth Realize ist manuell und doc-first: Wahrheitsdokumente führen, Code folgt, und der Agent darf die Wahrheitsdokumente, die er realisiert, nicht bearbeiten.
384
+ Truth Realize ist doc-first.
385
+
386
+ Die Truth-Dokumente führen. Der Code folgt.
206
387
 
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.
388
+ Der Agent darf die Truth-Dokumente, die er realisiert, nicht bearbeiten.
389
+
390
+ ## Read-only-Routing-Preview
391
+
392
+ Nutze Truth Preview vor einer Änderung, wenn der Agent wahrscheinliches Routing verstehen muss.
208
393
 
209
394
  ```text
210
- /truthmark-realize docs/truth/authentication/session-timeout.md in code umsetzen
395
+ /truthmark-preview das wahrscheinliche Truth-Routing für Änderungen an der Billing-API prüfen
211
396
  ```
212
397
 
213
- ## Was es installiert
398
+ Truth Preview ist read-only.
214
399
 
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.
400
+ Es ist Auswahl- und Planungshilfe, keine Schreibautorisierung und kein Ersatz für Truth Check.
216
401
 
217
- Truthmark installiert zwei getrennte Oberflächen:
402
+ ## Repository-Truth-Audit
218
403
 
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
404
+ Nutze Truth Check, wenn du einen agentenorientierten Audit-Workflow möchtest.
221
405
 
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
406
+ ```text
407
+ /truthmark-check Routing und Truth-Coverage vor dem Review auditieren
408
+ ```
229
409
 
230
- Die installierten Workflow-Flächen sind die Runtime:
410
+ Nutze die menschenorientierte CLI, wenn du Terminalvalidierung möchtest:
231
411
 
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.
412
+ ```bash
413
+ truthmark check
414
+ ```
238
415
 
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.
416
+ Beides ist nützlich. Es ist nicht dieselbe Oberfläche.
240
417
 
241
- Generierte Flächen werden von Truthmark verwaltet, enthalten einen Versionsmarker und können mit `truthmark init` aktualisiert werden.
418
+ ## Menschenorientierte CLI-Befehle
242
419
 
243
- ## Befehle
420
+ Die meisten Maintainer beginnen mit drei Befehlen.
244
421
 
245
- Truthmark V1 hält die Terminal-CLI fokussiert. Die meisten menschlichen Nutzer brauchen nur Einrichtung, Aktualisierung und Validierung:
422
+ | Befehl | Zweck |
423
+ | --- | --- |
424
+ | `truthmark config` | Erstellt `.truthmark/config.yml`. Schreibt nur diese Datei, außer `--stdout` wird verwendet. |
425
+ | `truthmark init` | Installiert oder aktualisiert konfigurierte Workflow-Oberflächen aus der geprüften Config. |
426
+ | `truthmark check` | Validiert Config, Autorität, Routing, entscheidungstragende Dokumente, Frontmatter, interne Links, Branch-Scope, generierte Oberflächen, Freshness und Coverage-Diagnostik. |
246
427
 
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. |
428
+ 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
429
 
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:
430
+ Sie sind keine Quellen der Wahrheit.
254
431
 
255
- | Optionaler CLI-Befehl | Zweck |
256
- | --------------------- | ----- |
432
+ | Befehl | Zweck |
433
+ | --- | --- |
257
434
  | `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. |
435
+ | `truthmark impact --base <ref>` | Ordnet geänderte Dateien gerouteten Truth-Dokumenten, besitzenden Routen, nahen Tests und öffentlichen Symbolen zu. |
436
+ | `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. |
260
437
 
261
- Alle oben genannten CLI-Befehle unterstützen `--json`, wenn strukturierte Ausgabe für Automatisierung nützlich ist.
438
+ Strukturierte Ausgabe ist mit `--json` verfügbar, wo sie unterstützt wird.
262
439
 
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.
440
+ ## Konfiguration
264
441
 
265
- Sie laufen über die konfigurierten Agenten-Host-Flächen, zum Beispiel Codex/Claude/Copilot `/truthmark-*`, OpenCode `/skill truthmark-*` oder Gemini `/truthmark:*`.
442
+ Truthmark ist config-first.
266
443
 
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.
444
+ Die wichtigste Config-Datei ist:
268
445
 
269
446
  ```text
270
- /truthmark-check routing und truth-abdeckung vor der review prüfen
447
+ .truthmark/config.yml
271
448
  ```
272
449
 
273
- ## Warum es existiert
450
+ Neue Repositories sollten ausführen:
274
451
 
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:
452
+ ```bash
453
+ truthmark config
454
+ ```
277
455
 
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
456
+ Prüfe danach die generierte Config, bevor du ausführst:
286
457
 
287
- ## Projektstatus
458
+ ```bash
459
+ truthmark init
460
+ ```
461
+
462
+ Wichtige Config-Bereiche sind:
463
+
464
+ | Config-Bereich | Zweck |
465
+ | --- | --- |
466
+ | `version` | Version des Config-Vertrags. |
467
+ | `platforms` | Agenten-Hosts, die plattformspezifische generierte Oberflächen erhalten sollen. |
468
+ | `docs.layout` | Aktueller Docs-Layoutmodus. |
469
+ | `docs.roots` | Benannte kanonische Dokumentationswurzeln. |
470
+ | `docs.routing.root_index` | Pfad zum Root-Routenindex. |
471
+ | `docs.routing.area_files_root` | Verzeichnis für delegierte untergeordnete Routendateien. |
472
+ | `docs.routing.default_area` | Dateiname des initial erzeugten untergeordneten Routings ohne Erweiterung. |
473
+ | `docs.routing.max_delegation_depth` | Aktuelle maximale Routing-Delegationstiefe. |
474
+ | `authority` | Geordnete kanonische Dokumente und Globs, die als Repository-Truth-Autorität dienen. |
475
+ | `instruction_targets` | Dateien, die gemeinsam verwaltete Instruktionsblöcke erhalten, etwa `AGENTS.md`. |
476
+ | `frontmatter.required` | Metadatenfelder, die bei Fehlen Error-Diagnostik erzeugen. |
477
+ | `frontmatter.recommended` | Metadatenfelder, die bei Fehlen Review-Diagnostik erzeugen. |
478
+ | `ignore` | Glob-Muster, die von relevanten Checks und Routing-Logik ausgeschlossen sind. |
479
+
480
+ ## Repository-Truth-Routing
481
+
482
+ Truthmark ordnet Codeoberflächen Truth-Dokumenten zu.
483
+
484
+ Die wichtigsten Routendateien sind:
485
+
486
+ ```text
487
+ docs/truthmark/areas.md
488
+ docs/truthmark/areas/**/*.md
489
+ ```
490
+
491
+ Eine Route sagt dem Agenten:
492
+
493
+ - welche Codeoberfläche zu einem Bereich gehört
494
+ - welche Truth-Dokumente diesen Bereich besitzen
495
+ - wann Truth aktualisiert werden sollte
496
+ - welche Art von Truth-Dokument beteiligt ist
497
+
498
+ Das Standard-Scaffold beginnt breit. Bestehende Repositories sollten die Standardroute meist in echte Ownership-Bereiche aufteilen.
499
+
500
+ Beispiel:
501
+
502
+ ```text
503
+ /truthmark-structure die breite repository-area in frontend, backend, billing und deployment aufteilen
504
+ ```
505
+
506
+ Gutes Routing gibt Truth Sync präzise Ziele.
507
+
508
+ Schlechtes Routing zwingt Agenten zum Raten.
509
+
510
+ ## Was Truthmark installiert
511
+
512
+ Truthmark installiert eine kompakte, repository-native Truth-Schicht.
513
+
514
+ Das geschieht in vier Schichten:
515
+
516
+ - Config und Routing für Ownership-Grenzen
517
+ - kanonische Truth-Dokumente und Starter-Templates
518
+ - kompakte verwaltete Instruction-Blöcke für repositoryweiten Agent-Kontext
519
+ - host-native Workflow-Pakete, Commands, Prompts und Verifier-Agents für die in der Config aktivierten Plattformen
520
+
521
+ Truthmark bewahrt manuellen Inhalt außerhalb verwalteter Instruktionsblöcke.
522
+
523
+ Generierte Workflow-Oberflächen werden von Truthmark verwaltet und können durch erneutes Ausführen aktualisiert werden:
524
+
525
+ ```bash
526
+ truthmark init
527
+ ```
528
+
529
+ ## Subagents und begrenzte Evidenzprüfungen
530
+
531
+ Wo der Host es unterstützt, kann Truthmark projektbezogene Prüfer-Agenten und einen geleasten `truth-doc-writer` installieren.
532
+
533
+ Diese helfen, große Truth-Aufgaben begrenzt zu halten:
534
+
535
+ - Route Auditors prüfen Route-Ownership
536
+ - Claim Verifiers prüfen, ob Dokumentclaims durch Evidenz gestützt sind
537
+ - Doc Reviewers prüfen Truth-Doc-Qualität
538
+ - geleaste Doc Writers bearbeiten begrenzte Truth-Doc-Schreib-Shards
539
+
540
+ Der Parent-Workflow besitzt weiterhin finale Interpretation, Schreibgrenzen, Diff-Validierung und Abnahme.
541
+
542
+ Das ist wichtig: Subagents helfen bei begrenzter Evidenzarbeit. Sie ersetzen den Haupt-Workflow-Vertrag nicht.
543
+
544
+ ## Review-Schleife
545
+
546
+ Truthmark ist für normalen Git-Review entworfen.
547
+
548
+ Eine gute KI-gestützte Übergabe sollte Folgendes zeigen:
549
+
550
+ ```text
551
+ Code-Diff
552
+ Test-Evidenz
553
+ Truth-Doc-Diff, falls nötig
554
+ Routing-Änderungen, falls nötig
555
+ Agentenbericht
556
+ ```
557
+
558
+ Der Reviewer sollte beantworten können:
559
+
560
+ - Welcher Code hat sich geändert?
561
+ - Welche Truth-Dokumente besitzen diesen Code?
562
+ - Mussten diese Dokumente aktualisiert werden?
563
+ - Falls nicht, warum nicht?
564
+ - Ist der Agent innerhalb der Workflow-Schreibgrenze geblieben?
565
+ - Sind Test- oder Verifikationsevidenz enthalten?
566
+
567
+ ## Beispiele
568
+
569
+ ### Ein Repository initialisieren
570
+
571
+ ```bash
572
+ npm install -g truthmark
573
+ truthmark config
574
+ truthmark init
575
+ truthmark check
576
+ ```
577
+
578
+ ### Unbenutzte Agentenplattformen entfernen
579
+
580
+ Bearbeiten:
581
+
582
+ ```text
583
+ .truthmark/config.yml
584
+ ```
585
+
586
+ Danach erneut ausführen:
587
+
588
+ ```bash
589
+ truthmark init
590
+ truthmark check
591
+ ```
592
+
593
+ ### Breites Routing aufteilen
594
+
595
+ ```text
596
+ /truthmark-structure die breite repository-area in auth, billing, notifications und deployment aufteilen
597
+ ```
598
+
599
+ ### Implementiertes Verhalten dokumentieren
600
+
601
+ ```text
602
+ /truthmark-document den implementierten Password-Reset-Flow unter docs/truth/authentication dokumentieren
603
+ ```
604
+
605
+ ### Nach Codeänderungen synchronisieren
606
+
607
+ ```text
608
+ /truthmark-sync die Repository-Wahrheit jetzt vor der Übergabe synchronisieren
609
+ ```
610
+
611
+ ### Eine doc-first Entscheidung realisieren
612
+
613
+ ```text
614
+ /truthmark-realize docs/truth/billing/invoice-retry-policy.md in Code realisieren
615
+ ```
616
+
617
+ ### Truth-Gesundheit im Terminal auditieren
618
+
619
+ ```bash
620
+ truthmark check
621
+ ```
622
+
623
+ ### Branch-Impact-Kontext erzeugen
624
+
625
+ ```bash
626
+ truthmark impact --base main
627
+ ```
628
+
629
+ ### Workflow-Kontext erzeugen
630
+
631
+ ```bash
632
+ truthmark context --workflow truth-sync --base main --format markdown
633
+ ```
288
634
 
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.
635
+ ## Projektstatus
290
636
 
291
- V1 bietet derzeit:
637
+ Truthmark V1 bietet derzeit:
292
638
 
293
639
  - `truthmark config`
294
640
  - `truthmark init`
@@ -296,15 +642,58 @@ V1 bietet derzeit:
296
642
  - `truthmark index`
297
643
  - `truthmark impact`
298
644
  - `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
645
  - 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
646
+ - verwaltete Instruktionsblöcke
647
+ - generierte Truth-Structure-Workflow-Oberflächen
648
+ - generierte Truth-Document-Workflow-Oberflächen
649
+ - generierte Truth-Sync-Workflow-Oberflächen
650
+ - generierte Truth-Preview-Workflow-Oberflächen
651
+ - generierte Truth-Realize-Workflow-Oberflächen
652
+ - generierte Truth-Check-Workflow-Oberflächen
653
+ - Diagnostik für Route, Autorität, Entscheidungsstruktur, Frontmatter, Links, Freshness, generierte Oberflächen und Coverage
654
+ - abgeleitete RepoIndex-, RouteMap-, ImpactSet- und ContextPack-Artefakte
655
+ - host-spezifische Oberflächen für Codex, Claude Code, GitHub Copilot, OpenCode und Gemini CLI
656
+
657
+ ## Entwicklung
658
+
659
+ Abhängigkeiten installieren:
660
+
661
+ ```bash
662
+ npm install
663
+ ```
664
+
665
+ Die lokale Entwicklungs-CLI ausführen:
666
+
667
+ ```bash
668
+ npm run dev -- init
669
+ npm run dev -- check
670
+ ```
671
+
672
+ Den vollständigen Projektcheck ausführen:
673
+
674
+ ```bash
675
+ npm run check
676
+ ```
677
+
678
+ Nützliche Skripte:
679
+
680
+ | Skript | Zweck |
681
+ | --- | --- |
682
+ | `npm run dev` | Führt den TypeScript-CLI-Einstiegspunkt mit `tsx` aus. |
683
+ | `npm run build` | Baut das Paket. |
684
+ | `npm run lint` | Führt ESLint aus. |
685
+ | `npm run typecheck` | Führt TypeScript-Checks aus. |
686
+ | `npm run test` | Führt Tests aus. |
687
+ | `npm run check` | Führt Lint, Typecheck, Tests und Build aus. |
688
+ | `npm run release:check` | Führt release-orientierte Validierung aus. |
689
+
690
+ Wenn du Truthmark selbst änderst, siehe [CONTRIBUTORS.md](CONTRIBUTORS.md).
304
691
 
305
692
  ## Dokumentation
306
693
 
307
- Die Root-README ist für Menschen gedacht, die das Paket evaluieren und ausprobieren. Detaillierte funktionale und geschäftliche Spezifikationen liegen unter `docs/`:
694
+ Die README ist der schnelle Pfad für Evaluation und Setup.
695
+
696
+ Aktuelles Verhalten im Detail lebt unter `docs/`:
308
697
 
309
698
  - [Dokumentationsindex](docs/README.md)
310
699
  - [Architekturüberblick](docs/architecture/overview.md)
@@ -314,11 +703,11 @@ Die Root-README ist für Menschen gedacht, die das Paket evaluieren und ausprobi
314
703
  - [Installierte Workflows](docs/truth/workflows/overview.md)
315
704
  - [Leitfaden zur Pflege von Repository-Wahrheit](docs/standards/maintaining-repository-truth.md)
316
705
 
317
- Aktuelles Verhalten gehört in den oben genannten kanonischen Dokumentationsbaum.
706
+ ## Designgrenzen
318
707
 
319
- ## Nicht-Ziele
708
+ Truthmark ist absichtlich klein.
320
709
 
321
- Truthmark V1 ist nicht:
710
+ Es ist nicht:
322
711
 
323
712
  - ein gehosteter Dienst
324
713
  - ein MCP-Server
@@ -327,8 +716,49 @@ Truthmark V1 ist nicht:
327
716
  - ein CI- oder PR-Enforcement-Produkt
328
717
  - ein Ersatz für Tests, Code Review oder technische Führung
329
718
  - eine autonome Code-Rewrite-Engine
719
+ - ein Framework für Modelltraining oder Fine-Tuning
720
+ - eine verborgene Memory-Schicht
721
+
722
+ Diese Grenzen sind Teil des Produkts.
723
+
724
+ Truthmark hält den Workflow lokal, festgeschrieben, branch-gebunden und prüffähig.
725
+
726
+ ## Sicherheit und Review-Disziplin
727
+
728
+ Truthmark hilft dem Repository, ehrlich zu bleiben. Es beweist nicht, dass der Code korrekt ist.
729
+
730
+ Teams sollten weiterhin:
330
731
 
331
- Es ist ein leichtgewichtiger Weg, lokale KI-Coding-Agenten dazu zu bringen, die Wahrheit zu respektieren, die dein Team in Git pflegt.
732
+ - relevante Tests ausführen
733
+ - funktionale Codeänderungen prüfen
734
+ - Truth-Doc-Änderungen prüfen
735
+ - Secrets aus der Dokumentation heraushalten
736
+ - repository-spezifische Instruktionen außerhalb verwalteter Blöcke halten
737
+ - Diffs generierter Workflow-Oberflächen nach Upgrades prüfen
738
+ - menschliche Ownership über Produkt- und Architekturentscheidungen behalten
739
+
740
+ Truthmark macht Agentenkontext sichtbar. Es ersetzt menschliches Urteil nicht.
741
+
742
+ ## Roadmap-Richtung
743
+
744
+ Die aktuelle Zukunftsrichtung betont:
745
+
746
+ - stärkere Evidenzberichte in `truthmark check`
747
+ - klarere Adoptionsbeispiele
748
+ - Beispiel-Repositories mit echten Truth-Sync-Zyklen
749
+ - Migrationsleitfäden für Teams, die bereits Agenten-Instruktionsdateien nutzen
750
+ - Konformitätstests für generierte Host-Oberflächen
751
+ - route-aware Hinweise auf stale truth
752
+ - begrenzte Implementierungschecklisten für doc-first Arbeit
753
+
754
+ Der Schwerpunkt bleibt gleich:
755
+
756
+ ```text
757
+ Repository-Wahrheit
758
+ agent-native Workflows
759
+ Git-Review
760
+ branch-gebundener Kontext
761
+ ```
332
762
 
333
763
  ## Lizenz
334
764