truthmark 1.3.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 +619 -189
  2. package/README.es.md +620 -190
  3. package/README.md +611 -188
  4. package/README.ru.md +628 -198
  5. package/README.zh.md +626 -194
  6. package/dist/main.js +2130 -178
  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 Realize gibt doc-first Änderungen einen begrenzten Pfad für Code-Updates.
100
- - `truthmark check` validiert die daraus entstehenden Wahrheitsartefakte.
101
- - Das gesamte Modell bleibt local-first und Git-nativ.
63
+ Es hat zwei unterschiedliche Oberflächen, und diese Unterscheidung ist wichtig.
102
64
 
103
- Das ist das Kernversprechen: Agentenkontext wird zu festgeschriebenem Repository-Zustand statt zu einem privaten Sitzungsartefakt.
65
+ ### 1. Menschenorientierte CLI
104
66
 
105
- ## Erste Schritte
67
+ Die CLI ist für Maintainer, Reviewer und Automatisierung.
106
68
 
107
- 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.
108
70
 
109
71
  ```bash
110
- cd /path/to/your-repo
111
- npm install -g truthmark
112
72
  truthmark config
113
73
  truthmark init
114
74
  truthmark check
115
75
  ```
116
76
 
117
- 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:
118
125
 
119
126
  ```bash
120
- cd /path/to/truthmark
121
- npm install
122
- npm run build
123
127
  cd /path/to/your-repo
124
- node /path/to/truthmark/dist/main.js config
125
- node /path/to/truthmark/dist/main.js init
126
- 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
127
135
  ```
128
136
 
129
- 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:
130
138
 
131
139
  ```text
132
140
  .truthmark/config.yml
133
- docs/truthmark/areas.md
134
- docs/truthmark/areas/repository.md
135
- docs/templates/behavior-doc.md
136
- docs/truth/README.md
137
- docs/truth/repository/README.md
138
- docs/truth/repository/overview.md
139
- AGENTS.md
140
- CLAUDE.md
141
- GEMINI.md
142
141
  ```
143
142
 
144
- 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.
145
- 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:
152
+
153
+ - Routendateien
154
+ - Truth-Doc-Scaffolding
155
+ - verwaltete Instruktionsblöcke
156
+ - KI-orientierte Workflow-Oberflächen für konfigurierte Plattformen
157
+
158
+ ### Das Setup validieren
159
+
160
+ ```bash
161
+ truthmark check
162
+ ```
163
+
164
+ Prüfe danach die generierten Dateien, bevor du committest.
165
+
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:
175
+
176
+ ```text
177
+ /truthmark-structure die breite repository-area in auth, billing und notifications aufteilen
178
+ ```
179
+
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:
251
+
252
+ ```text
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
301
+ ```
302
+
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:*` |
310
+
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:
146
357
 
147
- 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.
358
+ ```text
359
+ /truthmark-sync die Repository-Wahrheit jetzt vor der Übergabe synchronisieren
360
+ ```
361
+
362
+ ## Bestehendes Verhalten ohne Doku
363
+
364
+ Nutze Truth Document, wenn die Implementierung bereits existiert, aber die Repository-Wahrheit unvollständig ist.
365
+
366
+ ```text
367
+ /truthmark-document das implementierte Session-Timeout-Verhalten unter docs/truth/authentication dokumentieren
368
+ ```
369
+
370
+ Truth Document prüft Implementierung, Tests, Routendateien und vorhandene Dokumente als Evidenz.
148
371
 
149
- ## Wie es läuft
372
+ Es schreibt nur Truth-Dokumente und Routing.
150
373
 
151
- 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.
374
+ Es darf keinen funktionalen Code ändern.
152
375
 
153
- ### Vorhandenes Verhalten ohne Doku
376
+ ## Doc-first-Änderungen
154
377
 
155
- Nutze das, wenn die Implementierung bereits existiert, aber die kanonischen Wahrheitsdokumente fehlen oder schwach sind:
378
+ Nutze Truth Realize, wenn eine Produkt- oder Architekturentscheidung in Dokumenten beginnt und Code daran angepasst werden soll.
156
379
 
157
380
  ```text
158
- benutzer identifiziert ein implementiertes verhalten oder einen api-endpunkt
159
- benutzer ruft truth document ausdrücklich auf
160
- agent liest implementierung, tests, routing und vorhandene docs
161
- agent schreibt nur truth docs und routing
162
- truth-doc-diff prüfen
381
+ /truthmark-realize docs/truth/authentication/session-timeout.md in Code realisieren
163
382
  ```
164
383
 
165
- 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.
384
+ Truth Realize ist doc-first.
385
+
386
+ Die Truth-Dokumente führen. Der Code folgt.
387
+
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.
166
393
 
167
394
  ```text
168
- /truthmark-document dokumentiere das implementierte session-timeout-verhalten unter docs/truth/authentication
395
+ /truthmark-preview das wahrscheinliche Truth-Routing für Änderungen an der Billing-API prüfen
169
396
  ```
170
397
 
171
- ### Normale Codeänderungen
398
+ Truth Preview ist read-only.
172
399
 
173
- 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:
400
+ Es ist Auswahl- und Planungshilfe, keine Schreibautorisierung und kein Ersatz für Truth Check.
401
+
402
+ ## Repository-Truth-Audit
403
+
404
+ Nutze Truth Check, wenn du einen agentenorientierten Audit-Workflow möchtest.
174
405
 
175
406
  ```text
176
- agent ändert funktionalen code
177
- relevante tests laufen
178
- der installierte truth-sync-workflow läuft, bevor der agent fertig ist
179
- truth-doc-diff prüfen, falls einer erzeugt wurde
180
- arbeit committen oder übergeben
407
+ /truthmark-check Routing und Truth-Coverage vor dem Review auditieren
408
+ ```
409
+
410
+ Nutze die menschenorientierte CLI, wenn du Terminalvalidierung möchtest:
411
+
412
+ ```bash
413
+ truthmark check
181
414
  ```
182
415
 
183
- 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.
416
+ Beides ist nützlich. Es ist nicht dieselbe Oberfläche.
417
+
418
+ ## Menschenorientierte CLI-Befehle
419
+
420
+ Die meisten Maintainer beginnen mit drei Befehlen.
421
+
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. |
427
+
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.
429
+
430
+ Sie sind keine Quellen der Wahrheit.
184
431
 
185
- 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.
432
+ | Befehl | Zweck |
433
+ | --- | --- |
434
+ | `truthmark index` | Baut RepoIndex- und RouteMap-JSON für den aktiven Checkout. |
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. |
437
+
438
+ Strukturierte Ausgabe ist mit `--json` verfügbar, wo sie unterstützt wird.
439
+
440
+ ## Konfiguration
441
+
442
+ Truthmark ist config-first.
443
+
444
+ Die wichtigste Config-Datei ist:
186
445
 
187
446
  ```text
188
- /truthmark-sync die repository-wahrheit jetzt vor der übergabe synchronisieren
447
+ .truthmark/config.yml
448
+ ```
449
+
450
+ Neue Repositories sollten ausführen:
451
+
452
+ ```bash
453
+ truthmark config
454
+ ```
455
+
456
+ Prüfe danach die generierte Config, bevor du ausführst:
457
+
458
+ ```bash
459
+ truthmark init
189
460
  ```
190
461
 
191
- ### Doc-first-Änderungen
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. |
192
479
 
193
- Nutze das, wenn eine Produkt- oder Architekturentscheidung in der Doku beginnt:
480
+ ## Repository-Truth-Routing
481
+
482
+ Truthmark ordnet Codeoberflächen Truth-Dokumenten zu.
483
+
484
+ Die wichtigsten Routendateien sind:
194
485
 
195
486
  ```text
196
- benutzer bearbeitet wahrheitsdokumente
197
- benutzer ruft truth realize ausdrücklich auf
198
- agent liest wahrheitsdokumente und relevanten code
199
- agent aktualisiert nur code
200
- relevante tests laufen
201
- arbeit committen oder übergeben
487
+ docs/truthmark/areas.md
488
+ docs/truthmark/areas/**/*.md
202
489
  ```
203
490
 
204
- Truth Realize ist manuell und doc-first: Wahrheitsdokumente führen, Code folgt, und der Agent darf die Wahrheitsdokumente, die er realisiert, nicht bearbeiten.
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
205
497
 
206
- 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.
498
+ Das Standard-Scaffold beginnt breit. Bestehende Repositories sollten die Standardroute meist in echte Ownership-Bereiche aufteilen.
499
+
500
+ Beispiel:
207
501
 
208
502
  ```text
209
- /truthmark-realize docs/truth/authentication/session-timeout.md in code umsetzen
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
210
527
  ```
211
528
 
212
- ## Was es installiert
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
213
539
 
214
- 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.
540
+ Der Parent-Workflow besitzt weiterhin finale Interpretation, Schreibgrenzen, Diff-Validierung und Abnahme.
215
541
 
216
- - `.truthmark/config.yml` für den maschinenlesbaren, festgeschriebenen Hierarchievertrag
217
- - `docs/truthmark/areas.md` für den Root-Routenindex
218
- - `docs/truthmark/areas/**/*.md` für delegierte untergeordnete Routendateien
219
- - `docs/templates/behavior-doc.md` sowie die weiteren typspezifischen Vorlagen unter `docs/templates/` für die editierbaren Truth-Doc-Standards der generierten Workflows
220
- - verwaltete Instruktionsblöcke für konfigurierte Plattformen wie `AGENTS.md`, `CLAUDE.md`, Copilot-Anweisungen und `GEMINI.md`
221
- - host-native Skills, Prompts oder Commands für Truth Structure, Truth Document, Truth Sync, Truth Realize und Truth Check
542
+ Das ist wichtig: Subagents helfen bei begrenzter Evidenzarbeit. Sie ersetzen den Haupt-Workflow-Vertrag nicht.
222
543
 
223
- Die installierten Workflow-Flächen sind die Runtime:
544
+ ## Review-Schleife
224
545
 
225
- - Truth Structure erstellt oder repariert Area-Routing und erste Wahrheitsdokumente.
226
- - Truth Document erstellt oder repariert Wahrheitsdokumente für bereits implementiertes Verhalten.
227
- - Truth Sync hält zugeordnete Wahrheitsdokumente bei funktionalen Änderungen synchron.
228
- - Truth Realize aktualisiert Code so, dass er zu den Wahrheitsdokumenten passt.
229
- - Truth Check auditiert die Gesundheit der Repository-Wahrheit.
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
+ ```
230
557
 
231
- `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.
558
+ Der Reviewer sollte beantworten können:
232
559
 
233
- Generierte Flächen werden von Truthmark verwaltet, enthalten einen Versionsmarker und können mit `truthmark init` aktualisiert werden.
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?
234
566
 
235
- ## Befehle
567
+ ## Beispiele
236
568
 
237
- Truthmark V1 hält die CLI fokussiert, weil der laufende Workflow in den installierten Agenten-Flächen leben soll und nicht in einer langen Liste täglicher manueller Befehle. In nachgelagerten Repositories erzeugt `truthmark config` den in Git festgeschriebenen Hierarchievertrag, `truthmark init` installiert und aktualisiert Workflow-Flächen aus dieser geprüften Konfiguration, `truthmark check` validiert Wahrheitsartefakte für manuelle Audits, CI oder Fehlersuche, und die Repository-Intelligence-Befehle erzeugen abgeleitete Prüfarbeitsstände, wenn lokale Werkzeuge verfügbar sind.
569
+ ### Ein Repository initialisieren
238
570
 
239
571
  ```bash
572
+ npm install -g truthmark
240
573
  truthmark config
241
574
  truthmark init
242
575
  truthmark check
243
- truthmark index
244
- truthmark impact --base main
245
- truthmark context --workflow truth-sync --base main
246
- truthmark config --json
247
- truthmark check --json
248
- truthmark index --json
249
- truthmark impact --base main --json
250
- truthmark context --workflow truth-sync --base main --json
251
576
  ```
252
577
 
253
- `config` schreibt nur `.truthmark/config.yml`, außer `--stdout` wird verwendet.
578
+ ### Unbenutzte Agentenplattformen entfernen
254
579
 
255
- `init` benötigt `.truthmark/config.yml` und installiert oder aktualisiert anschließend die lokalen Workflow-Dateien.
580
+ Bearbeiten:
256
581
 
257
- `check` validiert Konfiguration, Autorität, Routing, entscheidungstragende Dokumente, Frontmatter, interne Links, Branch-Scope und Coverage-Diagnostik.
582
+ ```text
583
+ .truthmark/config.yml
584
+ ```
258
585
 
259
- `index` baut RepoIndex- und RouteMap-JSON für den aktiven Checkout.
586
+ Danach erneut ausführen:
260
587
 
261
- `impact --base <ref>` ordnet geänderte Dateien den gerouteten Truth-Dokumenten, Routen, nahen Tests und öffentlichen Symbolen zu.
588
+ ```bash
589
+ truthmark init
590
+ truthmark check
591
+ ```
262
592
 
263
- `context --workflow <workflow> [--base <ref>]` erzeugt ein begrenztes ContextPack für Truth Sync, Truth Document oder Truth Realize. `--format markdown` rendert eine menschenlesbare Fassung.
593
+ ### Breites Routing aufteilen
264
594
 
265
- Truth Structure, Truth Document, Truth Sync, Truth Realize und Truth Check sind installierte Agenten-Workflows, keine täglichen Top-Level-CLI-Befehle.
595
+ ```text
596
+ /truthmark-structure die breite repository-area in auth, billing, notifications und deployment aufteilen
597
+ ```
266
598
 
267
- Sie laufen über die konfigurierten Agenten-Host-Flächen, zum Beispiel Codex/Claude/Copilot `/truthmark-*`, OpenCode `/skill truthmark-*` oder Gemini `/truthmark:*`.
599
+ ### Implementiertes Verhalten dokumentieren
268
600
 
269
601
  ```text
270
- /truthmark-check routing und truth-abdeckung vor der review prüfen
602
+ /truthmark-document den implementierten Password-Reset-Flow unter docs/truth/authentication dokumentieren
271
603
  ```
272
604
 
273
- ## Warum es existiert
605
+ ### Nach Codeänderungen synchronisieren
274
606
 
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:
607
+ ```text
608
+ /truthmark-sync die Repository-Wahrheit jetzt vor der Übergabe synchronisieren
609
+ ```
277
610
 
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
611
+ ### Eine doc-first Entscheidung realisieren
286
612
 
287
- ## Projektstatus
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
288
630
 
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.
631
+ ```bash
632
+ truthmark context --workflow truth-sync --base main --format markdown
633
+ ```
634
+
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 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:
731
+
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
330
739
 
331
- Es ist ein leichtgewichtiger Weg, lokale KI-Coding-Agenten dazu zu bringen, die Wahrheit zu respektieren, die dein Team in Git pflegt.
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