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.es.md CHANGED
@@ -1,294 +1,640 @@
1
1
  # Truthmark
2
2
 
3
- **Truthmark instala flujos de verdad del repositorio para el desarrollo de software con IA.**
3
+ **Tus agentes escriben código. Truthmark hace que su contexto sea revisable en Git.**
4
4
 
5
5
  [English](README.md) | [Deutsch](README.de.md) | [中文](README.zh.md) | Español | [Русский](README.ru.md)
6
6
 
7
- <img src="docs/assets/truthmark-banner.png" alt="Banner de Truthmark" width="100%" />
7
+ ![Banner de Truthmark](docs/assets/truthmark-banner.png)
8
8
 
9
- Los agentes de programación con IA ya escriben código rápido. La parte costosa es mantener alineada la verdad del repositorio con lo que realmente cambió.
9
+ Los agentes de programación con IA pueden cambiar un repositorio más rápido de lo que las personas pueden mantener alineado su contexto.
10
10
 
11
- Truthmark añade una guarda de cierre basada en flujo de trabajo. El camino normal es simple:
11
+ Truthmark arregla la parte que normalmente se rompe después de escribir el código: la verdad del repositorio.
12
12
 
13
- - el agente cambia código funcional
14
- - se ejecutan las pruebas relevantes
15
- - el flujo instalado Truth Sync actualiza los documentos de verdad asignados antes de que el agente termine
16
- - se revisa el diff de documentos de verdad si se produjo uno
13
+ Instala una capa de flujo de trabajo nativa de Git y acotada a la rama que ayuda a los agentes de programación con IA a actualizar los documentos correctos, respetar los límites de propiedad y dejar a las personas diffs normales que puedan revisar.
17
14
 
18
- La mayoría de las herramientas pide al equipo adoptar un hábito. Truthmark convierte ese hábito en infraestructura de flujo del repositorio.
15
+ Sin servicio alojado.
19
16
 
20
- Truthmark convierte un flujo de trabajo con IA en infraestructura del repositorio, no en tooling personal. Instala una capa de verdad nativa de Git y acotada a la rama dentro del propio repositorio, da a los agentes rutas explícitas y superficies de trabajo acotadas, y mantiene esa verdad revisable en Git en lugar de dispersarla por el historial de prompts, documentación obsoleta o estado privado de herramientas.
17
+ Sin base de datos.
21
18
 
22
- Eso importa porque el flujo vive con la rama. Una vez inicializado un repositorio, las reglas, el enrutamiento y las superficies instaladas viajan dentro del repo, así que la colaboración y los traspasos dependen menos de la configuración local de una sola persona.
19
+ Sin capa oculta de memoria.
23
20
 
24
- Para equipos que ya saben que los agentes pueden generar código, Truthmark responde al siguiente problema: cómo hacer que el repositorio siga siendo legible, revisable y gobernable a medida que crece el trabajo asistido por IA.
21
+ Sin servidor adicional que operar.
25
22
 
26
- ## Resumen visual
23
+ Solo verdad del repositorio que se mueve con la rama.
27
24
 
28
- <table>
29
- <tr>
30
- <td align="center" width="50%">
31
- <img src="docs/assets/truthmark-features.png" alt="Características de Truthmark" width="100%" />
32
- <br><strong>Características</strong><br>
33
- Lo que instala Truthmark y cómo se divide la superficie de trabajo.
34
- </td>
35
- <td align="center" width="50%">
36
- <img src="docs/assets/truthmark-position.png" alt="Posicionamiento de Truthmark" width="100%" />
37
- <br><strong>Posicionamiento</strong><br>
38
- Dónde encaja Truthmark frente a prompts, memoria y flujos spec-first.
39
- </td>
40
- </tr>
41
- <tr>
42
- <td align="center" colspan="2">
43
- <img src="docs/assets/truthmark-syncflow.png" alt="Flujo de sync de Truthmark" width="100%" />
44
- <br><strong>Flujo de sync</strong><br>
45
- Cómo Truth Sync cierra cambios normales de código antes del traspaso.
46
- </td>
47
- </tr>
48
- </table>
25
+ ## El problema
49
26
 
50
- ## Por qué los equipos lo adoptan
27
+ Los agentes de programación con IA son buenos produciendo código. Eso crea un nuevo modo de fallo.
51
28
 
52
- Truthmark no intenta hacer que los agentes suenen más inteligentes. Intenta que los cambios de repositorio asistidos por IA sean más confiables.
29
+ La implementación cambia, pero la historia del repositorio se desvía:
53
30
 
54
- - El flujo instalado Truth Sync tras cambios de código convierte el mantenimiento de documentación en una salvaguarda del flujo, no en un hábito del equipo.
55
- - La verdad acotada a la rama viaja con el código, de modo que quienes revisan pueden inspeccionar la verdad actual en diffs normales de Git.
56
- - Las superficies de flujo nativas del repositorio hacen el despliegue más ligero y los traspasos más resistentes que una simple configuración por usuario.
57
- - El enrutamiento explícito en `docs/truthmark/areas.md` y en archivos de rutas secundarias delegadas da a los agentes límites de responsabilidad y rutas de escritura más seguras.
58
- - La operación local-first evita depender de un demonio, una base de datos, un servicio remoto o MCP.
59
- - El modelo de enrutamiento es independiente del lenguaje, con diagnósticos de cobertura para superficies comunes de código JavaScript, TypeScript, Go, Python, C# y Java.
31
+ - el comportamiento vive en el historial de chat
32
+ - los documentos de arquitectura quedan atrás
33
+ - las decisiones de producto desaparecen después del traspaso
34
+ - quienes revisan ven diffs de código sin los diffs de verdad relacionados
35
+ - las ramas desarrollan silenciosamente distintas versiones de “lo que es verdad”
36
+ - cada sesión de agente tiene que redescubrir el contexto desde cero
60
37
 
61
- Para responsables técnicos, el valor es gobernanza sin infraestructura extra: las pruebas, la revisión de código y la propiedad siguen haciendo el trabajo real; Truthmark vuelve el contexto del agente duradero, inspeccionable y acotado a la rama.
38
+ Truthmark convierte ese contexto frágil en infraestructura del repositorio confirmada en Git.
62
39
 
63
- ## Dónde encaja Truthmark
40
+ En lugar de depender de que cada persona y cada agente recuerden el hábito correcto de documentación, Truthmark instala ese hábito en el repositorio.
64
41
 
65
- Truthmark no es una suite general de productividad para IA. Ocupa una capa concreta de la pila: verdad de repositorio revisable, acotada a la rama y alineada con la implementación.
42
+ ## La promesa
66
43
 
67
- | Si necesitas | Mejor opción |
68
- | ------------------------------------------------------------------------------ | -------------------------------------------- |
69
- | Mejores resultados en una sola sesión de programación | Mejores prompts y una tarea mejor delimitada |
70
- | Continuidad cómoda entre sesiones para un agente o una persona | Herramientas de memoria |
71
- | Planificación spec-first para nuevas funciones | Herramientas de especificación como Spec Kit |
72
- | Verdad del repositorio, revisable y acotada a la rama, que viaja con el código | Truthmark |
44
+ Cuando un agente cambia código funcional, el trabajo no debería terminar con solo un diff de código.
73
45
 
74
- La idea no es que los prompts, la memoria o las especificaciones no sirvan. La idea es que ninguno de ellos, por sí solo, convierte la verdad del repositorio en un activo confirmado en Git, inspeccionable y capaz de sobrevivir a traspasos, revisiones y divergencias entre ramas.
46
+ El camino normal de Truthmark es:
75
47
 
76
- ## Contenido
48
+ ```text
49
+ el agente cambia código funcional
50
+ se ejecutan pruebas relevantes
51
+ Truth Sync revisa los documentos de verdad asignados
52
+ los documentos de verdad se actualizan cuando hace falta
53
+ una persona revisa el diff de código + el diff de verdad
54
+ confirmar o traspasar
55
+ ```
77
56
 
78
- - [Por qué los equipos lo adoptan](#por-qué-los-equipos-lo-adoptan)
79
- - [Qué resuelve Truthmark](#qué-resuelve-truthmark)
80
- - [Dónde encaja Truthmark](#dónde-encaja-truthmark)
81
- - [Primeros pasos](#primeros-pasos)
82
- - [Cómo se ejecuta](#cómo-se-ejecuta)
83
- - [Qué instala](#qué-instala)
84
- - [Comandos](#comandos)
85
- - [Por qué existe](#por-qué-existe)
86
- - [Estado del proyecto](#estado-del-proyecto)
87
- - [Documentación](#documentación)
88
- - [No objetivos](#no-objetivos)
89
- - [Licencia](#licencia)
57
+ Ese es el valor central: **el trabajo con IA es más fácil de confiar porque el repositorio sigue siendo legible.**
90
58
 
91
- ## Qué resuelve Truthmark
59
+ ## Dos superficies, un sistema de verdad
92
60
 
93
- Truthmark convierte la verdad del repositorio en una superficie explícita de flujo de trabajo para agentes:
61
+ Truthmark no es solo una CLI.
94
62
 
95
- - `.truthmark/config.yml` define el contrato de jerarquía confirmado en el repositorio.
96
- - `docs/truthmark/areas.md` y los archivos de rutas secundarias delegadas asignan áreas de código a los documentos que las gobiernan.
97
- - Truth Document genera o repara documentos de verdad canónica para comportamiento ya implementado cuando no hace falta cambiar código.
98
- - Truth Sync mantiene alineados los documentos de verdad asignados cuando hay cambios funcionales.
99
- - Truth Realize ofrece a los cambios que empiezan en documentación una ruta acotada para actualizar código.
100
- - `truthmark check` valida los artefactos de verdad resultantes.
101
- - Todo el modelo se mantiene local-first y nativo de Git.
63
+ Tiene dos superficies distintas, y la distinción importa.
102
64
 
103
- Esta es la promesa central: el contexto del agente pasa a ser estado confirmado del repositorio, no un artefacto privado de una sesión.
65
+ ### 1. CLI orientada a personas
104
66
 
105
- ## Primeros pasos
67
+ La CLI es para mantenedores, revisores y automatización.
106
68
 
107
- Instala Truthmark en el repositorio que quieras inicializar:
69
+ Úsala para configurar un repositorio, instalar o refrescar archivos de flujo de trabajo, validar artefactos de verdad y generar contexto opcional para revisión.
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
- Si quieres probar cambios aún no publicados desde un checkout del código fuente:
77
+ La CLI prepara y valida el entorno del repositorio.
78
+
79
+ No es el runtime del flujo de trabajo con IA.
80
+
81
+ ### 2. Superficies de flujo orientadas a IA
82
+
83
+ Las superficies orientadas a IA son para agentes de programación.
84
+
85
+ Truthmark instala skills, prompts, comandos, bloques de instrucciones administrados y superficies de subagentes nativos del host para que los agentes de IA puedan seguir flujos de verdad específicos del repositorio dentro de sus herramientas normales de programación.
86
+
87
+ Ejemplos:
88
+
89
+ ```text
90
+ /truthmark-sync
91
+ /truthmark-document
92
+ /truthmark-structure
93
+ /truthmark-realize
94
+ /truthmark-preview
95
+ /truthmark-check
96
+ ```
97
+
98
+ Parecen comandos porque los hosts de agentes exponen flujos mediante slash commands, prompts, skills o comandos de proyecto.
99
+
100
+ No son comandos de shell.
101
+
102
+ Son puntos de entrada de flujo para IA.
103
+
104
+ La división es el producto:
105
+
106
+ ```text
107
+ las personas poseen el contrato del repositorio
108
+ Truthmark instala el contrato en el repo
109
+ los agentes operan dentro de ese contrato
110
+ las actualizaciones de verdad aparecen como diffs de Git
111
+ las personas revisan el resultado
112
+ ```
113
+
114
+ ## Inicio rápido
115
+
116
+ ### Requisitos
117
+
118
+ - Node.js `>=20`
119
+ - npm
120
+ - un repositorio Git
121
+
122
+ ### Instalar Truthmark
123
+
124
+ Ejecuta esto dentro del repositorio que quieres inicializar:
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
127
129
  ```
128
130
 
129
- Revisa `.truthmark/config.yml` antes de `init`; es el contrato de jerarquía confirmado en el repositorio. Después de `init`, revisa la superficie de flujo de trabajo generada y los archivos de rutas para que los documentos enrutados coincidan con los documentos que realmente gobiernan tu código:
131
+ ### Crear el contrato de verdad del repositorio
132
+
133
+ ```bash
134
+ truthmark config
135
+ ```
136
+
137
+ Esto crea:
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
- Las plataformas compatibles son `codex`, `opencode`, `claude-code`, `github-copilot` y `gemini-cli`. La configuración predeterminada las incluye todas; elimina de `.truthmark/config.yml` las plataformas que no uses antes de volver a ejecutar `truthmark init`.
145
- La estructura generada por defecto usa los `README.md` de verdad como índices y empieza la verdad sobre el comportamiento actual en documentos hoja acotados, como `docs/truth/repository/overview.md`.
143
+ Revisa este archivo antes de continuar. Define el contrato de jerarquía confirmado en el repositorio.
144
+
145
+ ### Instalar las superficies de flujo
146
+
147
+ ```bash
148
+ truthmark init
149
+ ```
150
+
151
+ Esto instala o refresca:
152
+
153
+ - archivos de rutas
154
+ - scaffolding de documentos de verdad
155
+ - bloques de instrucciones administrados
156
+ - superficies de flujo orientadas a IA para las plataformas configuradas
157
+
158
+ ### Validar la configuración
159
+
160
+ ```bash
161
+ truthmark check
162
+ ```
163
+
164
+ Después revisa los archivos generados antes de confirmar.
146
165
 
147
- Los repositorios existentes suelen necesitar una pasada de limpieza después de `init`: ejecuta el flujo instalado Truth Structure cuando la ruta `repository` generada sea demasiado amplia, la propiedad abarque varios productos o servicios, o los archivos de rutas sigan apuntando a documentos de marcador de posición. Truth Structure divide rutas amplias, crea o repara documentos de verdad canónica iniciales y da a Truth Sync destinos precisos antes de que empiece el trabajo de código funcional. Codex, Claude Code y los IDEs de Copilot compatibles pueden invocarlo con `/truthmark-structure`; los hosts de estilo OpenCode pueden usar `/skill truthmark-structure`.
166
+ Los archivos exactos dependen de `.truthmark/config.yml`, pero la instalación siempre tiene la misma forma: routing, truth scaffolding, instrucciones administradas compactas y superficies de workflow host-native para las plataformas habilitadas.
148
167
 
149
- ## Cómo se ejecuta
168
+ ## Primer uso real
150
169
 
151
- Truthmark es más fuerte en el camino por defecto, no como un conjunto de comandos manuales. El agente que actúa y el entorno anfitrión deciden si delegan o ejecutan el flujo instalado en línea.
170
+ La mayoría de los repositorios necesita una pasada de limpieza después de la inicialización.
152
171
 
153
- ### Comportamiento existente sin docs
172
+ El scaffold predeterminado empieza con un área amplia `repository`. Los repositorios reales suelen necesitar rutas más precisas.
154
173
 
155
- Usa esto cuando la implementación ya existe pero faltan o son débiles los documentos de verdad canónica:
174
+ Pide a tu agente que divida la ruta amplia en áreas reales de producto, servicio, dominio o propiedad:
156
175
 
157
176
  ```text
158
- el usuario identifica un comportamiento implementado o un endpoint de api
159
- el usuario invoca explícitamente truth document
160
- el agente lee implementación, pruebas, rutas y docs existentes
161
- el agente solo escribe truth docs y rutas
162
- revisar el diff de truth docs
177
+ /truthmark-structure divide el área amplia repository en auth, billing y notifications
163
178
  ```
164
179
 
165
- Truth Document es manual y con prioridad de implementación: el código sirve como evidencia, los documentos de verdad se crean o reparan, y no se debe cambiar código funcional. Codex, Claude Code y los IDEs de Copilot compatibles pueden invocarlo con `/truthmark-document`; los hosts de estilo OpenCode pueden usar `/skill truthmark-document`.
180
+ Después usa tu agente de programación con IA normalmente.
181
+
182
+ Cuando el agente cambia código funcional, Truth Sync actúa como guarda de cierre que revisa si los documentos de verdad asignados deben cambiar antes del traspaso.
183
+
184
+ ## Qué obtienes
185
+
186
+ | Capacidad | Qué hace |
187
+ | --- | --- |
188
+ | Verdad nativa de Git | Mantiene la verdad del repositorio en Markdown y config confirmados. |
189
+ | Contexto acotado a la rama | La verdad se mueve con la rama en lugar de vivir en una sesión privada. |
190
+ | CLI humana | Da a mantenedores comandos de configuración, refresco, validación e inspección. |
191
+ | Flujos orientados a IA | Da a los agentes flujos nativos del host para sincronización, documentación, estructura, preview, realización y auditoría. |
192
+ | Rutas explícitas | Mapea áreas de código a documentos de verdad canónicos. |
193
+ | Traspasos revisables | Produce diffs normales de Git para código y documentos de verdad. |
194
+ | Operación local-first | No requiere servicio alojado, demonio, base de datos ni servidor MCP. |
195
+ | Límites de escritura más seguros | Separa flujos code-first, doc-first, read-only y doc-only. |
196
+ | Validación | Reporta problemas de rutas, autoridad, frontmatter, enlaces, superficies generadas, alcance de rama, frescura y cobertura. |
197
+
198
+ ## Resumen visual
199
+
200
+ ![Características de Truthmark](docs/assets/truthmark-features.png)
201
+
202
+ **Características:** qué instala Truthmark y cómo se divide la superficie de flujo.
203
+
204
+ ![Posición de Truthmark](docs/assets/truthmark-position.png)
205
+
206
+ **Posición:** dónde encaja Truthmark frente a prompts, memoria y flujos de especificación.
207
+
208
+ ![Flujo de sync de Truthmark](docs/assets/truthmark-syncflow.png)
209
+
210
+ **Flujo de sync:** cómo Truth Sync cierra cambios normales de código antes del traspaso.
211
+
212
+ ## Por qué los equipos lo adoptan
213
+
214
+ Truthmark es para equipos que ya saben que los agentes de IA pueden generar código.
215
+
216
+ El siguiente problema es la gobernanza.
217
+
218
+ No gobernanza como ceremonia. Gobernanza como una pregunta simple:
219
+
220
+ > Después de este cambio asistido por IA, ¿el repositorio todavía dice la verdad?
221
+
222
+ Truthmark ayuda a los equipos a responder con archivos confirmados, rutas explícitas y diffs revisables.
223
+
224
+ Es útil cuando necesitas:
225
+
226
+ - menos deriva de documentación
227
+ - mejores traspasos
228
+ - verdad de producto específica de cada rama
229
+ - contexto duradero de arquitectura y API
230
+ - propiedad explícita entre documentos y código
231
+ - límites de escritura más seguros para agentes
232
+ - contexto revisable en lugar de memoria oculta
233
+ - flujos de IA que sigan funcionando desde archivos confirmados del repo
234
+
235
+ ## Dónde encaja Truthmark
236
+
237
+ Truthmark no reemplaza prompts, memoria, especificaciones, pruebas ni revisión de código.
238
+
239
+ Les da a esos flujos un lugar duradero donde aterrizar en Git.
240
+
241
+ | Necesidad | Mejor opción |
242
+ | --- | --- |
243
+ | Mejor salida de una sesión de agente | Mejor prompt |
244
+ | Continuidad personal o por sesión | Herramienta de memoria |
245
+ | Trabajo de funciones plan-first | Flujo de especificación |
246
+ | Verdad acotada a la rama que viaja con el código | Truthmark |
247
+ | Validar la corrección del comportamiento | Pruebas y revisión |
248
+ | Revisar cambios de contexto asistidos por IA | Truthmark más revisión Git |
249
+
250
+ El carril de Truthmark es estrecho por diseño:
166
251
 
167
252
  ```text
168
- /truthmark-document documenta el comportamiento implementado del timeout de sesión en docs/truth/authentication
253
+ hacer explícita la verdad del repositorio
254
+ mapearla al código
255
+ instalar flujos de agentes alrededor de ella
256
+ mantener el resultado revisable en Git
257
+ ```
258
+
259
+ ## Cómo se ejecuta Truthmark
260
+
261
+ Truthmark se ejecuta localmente contra el worktree Git activo.
262
+
263
+ La CLI orientada a personas lee y escribe archivos del repositorio, y luego termina.
264
+
265
+ Las superficies de flujo orientadas a IA son archivos confirmados que los hosts de agentes pueden cargar después. Eso permite que los agentes sigan el flujo instalado desde el estado del repositorio, sin depender de un proceso de Truthmark en segundo plano.
266
+
267
+ Las capas encajan así:
268
+
269
+ ```mermaid
270
+ flowchart LR
271
+ Human["Human / CI"] --> CLI["Truthmark CLI"]
272
+ CLI --> Config["Config y routing"]
273
+ CLI --> Truth["Documentos truth canónicos"]
274
+ CLI --> Surfaces["Workflows host-native generados"]
275
+ Surfaces --> Hosts["Codex / Claude Code / Copilot / OpenCode / Gemini"]
276
+ Hosts --> Worktree["Git worktree activo"]
277
+ Hosts -->|"helper checks / validate / index"| CLI
278
+ Worktree --> Truth
279
+ ```
280
+
281
+ Los agentes no hablan con un daemon de Truthmark, pero pueden ejecutar la CLI instalada de Truthmark cuando un workflow pide validación, indexing o helper checks.
282
+
283
+ Truthmark es dueño de las superficies de workflow que genera, pero el contrato importante es arquitectónico: la config y el routing del repo apuntan a los agentes hacia los documentos truth canónicos, mientras que los workflows host-native dan a cada agente compatible una forma de ejecutar los mismos procedimientos de Truthmark.
284
+
285
+ Las superficies de flujo generadas incluyen marcadores de versión de Truthmark. Después de actualizar Truthmark, vuelve a ejecutar:
286
+
287
+ ```bash
288
+ truthmark init
289
+ ```
290
+
291
+ Luego revisa los diffs generados.
292
+
293
+ ## Plataformas de agentes compatibles
294
+
295
+ La configuración predeterminada incluye todas las plataformas compatibles.
296
+
297
+ Elimina de `.truthmark/config.yml` las plataformas que no uses, y luego vuelve a ejecutar:
298
+
299
+ ```bash
300
+ truthmark init
169
301
  ```
170
302
 
171
- ### Cambios de código normales
303
+ | Nombre de plataforma en config | Superficie generada | Forma de invocación |
304
+ | --- | --- | --- |
305
+ | `codex` | `.codex/skills/truthmark-*/`, `.codex/agents/` | `/truthmark-*` o `$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-*` en IDEs de Copilot compatibles; agentes personalizados `@truth-*` en 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
+ Los nombres de plataforma desconocidos son errores de configuración.
312
+
313
+ Eliminar una plataforma detiene futuros refrescos para esa plataforma. No elimina archivos generados previamente.
314
+
315
+ ## Flujos orientados a IA
316
+
317
+ Estos flujos se instalan en hosts de programación con IA compatibles.
318
+
319
+ Los usan agentes o hosts de agentes durante el trabajo en el repositorio. No son comandos de shell de nivel superior.
320
+
321
+ | Flujo | Dirección | Úsalo cuando | Límite de escritura |
322
+ | --- | --- | --- | --- |
323
+ | Truth Structure | topology-first | La ruta predeterminada es demasiado amplia, la propiedad abarca varias áreas o los archivos de rutas siguen apuntando a placeholders. | Crea o repara rutas y documentos de verdad iniciales. |
324
+ | Truth Document | implementation-first | El comportamiento ya existe en código, pero faltan o son débiles los documentos de verdad canónicos. | Escribe solo documentos de verdad y rutas. No debe cambiar código funcional. |
325
+ | Truth Sync | code-first | Cambió código funcional y puede que los documentos de verdad asignados deban actualizarse antes del traspaso. | Actualiza documentos de verdad. Truth Sync no debe reescribir código funcional. |
326
+ | Truth Preview | read-only | El agente necesita previsualizar rutas probables antes de editar. | Solo lee. No autoriza escrituras. |
327
+ | Truth Realize | doc-first | Documentos de verdad de producto o arquitectura lideran y el código debe actualizarse para coincidir. | Actualiza solo código. El agente no debe editar los documentos de verdad que está realizando. |
328
+ | Truth Check | audit-first | Un revisor o agente necesita auditar la salud de la verdad del repositorio. | Audita e informa. |
329
+
330
+ ### Distinción importante
172
331
 
173
- La mayoría de los usuarios no debería invocar Truth Sync directamente. Lo importante es que el flujo instalado del agente trate Truth Sync como una guarda de cierre cuando cambió código funcional. El flujo normal es:
332
+ No confundas estas dos superficies:
333
+
334
+ | Superficie | Usada por | Ejemplo | Significado |
335
+ | --- | --- | --- | --- |
336
+ | CLI humana | personas, scripts, checks tipo CI | `truthmark check` | Validar artefactos de verdad del repositorio desde la terminal. |
337
+ | Flujo orientado a IA | agentes de programación y hosts de agentes | `/truthmark-check` | Pedir a un agente que ejecute el flujo instalado de auditoría. |
338
+
339
+ Los nombres están relacionados a propósito, pero las superficies son distintas.
340
+
341
+ ## Cambio normal de código asistido por IA
342
+
343
+ La mayoría de los usuarios no debería invocar Truth Sync manualmente cada vez.
344
+
345
+ Truth Sync es la guarda de cierre instalada para cambios de código funcional.
174
346
 
175
347
  ```text
176
348
  el agente cambia código funcional
177
- se ejecutan las pruebas relevantes
178
- el flujo instalado truth sync se ejecuta antes de que el agente termine
179
- revisar el diff de truth docs si se produjo uno
180
- confirmar o entregar el trabajo
349
+ el agente ejecuta o pide pruebas relevantes
350
+ el flujo instalado detecta que cambió código funcional
351
+ Truth Sync revisa los documentos de verdad asignados
352
+ el agente actualiza documentos de verdad si hace falta
353
+ una persona revisa el diff de código + el diff de verdad
181
354
  ```
182
355
 
183
- Truth Sync es code-first: el código lidera, los documentos de verdad siguen, y Truth Sync no debe reescribir código funcional. Su tarea principal es ejecutarse mediante el flujo instalado del agente como guarda de cierre cuando cambió código funcional. La invocación directa se usa sobre todo para depurar, forzar una sincronización temprana antes de entregar el trabajo o ejecutar el flujo de forma intencional.
184
-
185
- Codex, Claude Code y los IDEs de Copilot compatibles pueden invocarlo con `/truthmark-sync`. Los hosts de estilo OpenCode pueden usar `/skill truthmark-sync`.
356
+ La invocación directa sigue siendo útil para depurar, forzar una sincronización temprana o hacer explícito el traspaso:
186
357
 
187
358
  ```text
188
- /truthmark-sync sincroniza ahora la verdad del repositorio antes de la entrega
359
+ /truthmark-sync sincroniza ahora la verdad del repositorio antes del traspaso
189
360
  ```
190
361
 
191
- ### Cambios doc-first
362
+ ## Comportamiento existente sin docs
192
363
 
193
- Usa este flujo cuando una decisión de producto o arquitectura empieza en la documentación:
364
+ Usa Truth Document cuando la implementación ya existe pero la verdad del repositorio está incompleta.
194
365
 
195
366
  ```text
196
- el usuario edita truth docs
197
- el usuario invoca explícitamente truth realize
198
- el agente lee truth docs y el código relevante
199
- el agente actualiza solo el código
200
- se ejecutan las pruebas relevantes
201
- confirmar o entregar el trabajo
367
+ /truthmark-document documenta el comportamiento implementado de timeout de sesión bajo docs/truth/authentication
202
368
  ```
203
369
 
204
- Truth Realize es manual y doc-first: los documentos de verdad lideran, el código sigue, y el agente no debe editar los documentos de verdad que está realizando.
370
+ Truth Document inspecciona implementación, pruebas, archivos de rutas y documentación existente como evidencia.
371
+
372
+ Escribe solo documentos de verdad y rutas.
373
+
374
+ No debe cambiar código funcional.
205
375
 
206
- Codex, Claude Code y los IDEs de Copilot compatibles pueden invocarlo con `/truthmark-realize`. Los hosts de estilo OpenCode pueden usar `/skill truthmark-realize`.
376
+ ## Cambios doc-first
377
+
378
+ Usa Truth Realize cuando una decisión de producto o arquitectura empieza en documentos y el código debe actualizarse para coincidir.
207
379
 
208
380
  ```text
209
381
  /truthmark-realize realiza docs/truth/authentication/session-timeout.md como código
210
382
  ```
211
383
 
212
- ## Qué instala
384
+ Truth Realize es doc-first.
385
+
386
+ Los documentos de verdad lideran. El código sigue.
387
+
388
+ El agente no debe editar los documentos de verdad que está realizando.
389
+
390
+ ## Preview de rutas de solo lectura
213
391
 
214
- Truthmark mantiene pequeña y nativa del repositorio la superficie duradera de flujo de trabajo. Después de `truthmark init`, el propio repositorio lleva el enrutamiento, las reglas y las superficies instaladas, así que el equipo no depende solo de la configuración local de una persona.
392
+ Usa Truth Preview antes de un cambio cuando el agente necesita entender la ruta probable.
215
393
 
216
- - `.truthmark/config.yml` para el contrato de jerarquía confirmado y legible por máquina
217
- - `docs/truthmark/areas.md` para el índice raíz de rutas
218
- - `docs/truthmark/areas/**/*.md` para archivos de rutas secundarias delegadas
219
- - `docs/templates/behavior-doc.md` y las demás plantillas específicas por tipo bajo `docs/templates/` para los estándares editables de truth docs usados por los flujos generados
220
- - bloques de instrucciones administrados para plataformas configuradas como `AGENTS.md`, `CLAUDE.md`, instrucciones de Copilot y `GEMINI.md`
221
- - skills, prompts o comandos nativos del host para Truth Structure, Truth Document, Truth Sync, Truth Realize y Truth Check
394
+ ```text
395
+ /truthmark-preview previsualiza la ruta de verdad probable para cambios en la API de billing
396
+ ```
222
397
 
223
- Las superficies de flujo de trabajo instaladas son el entorno de ejecución:
398
+ Truth Preview es read-only.
224
399
 
225
- - Truth Structure crea o repara el enrutamiento de áreas y documentos de verdad iniciales.
226
- - Truth Document crea o repara documentos de verdad para comportamiento ya implementado.
227
- - Truth Sync mantiene alineados los documentos de verdad asignados con los cambios funcionales.
228
- - Truth Realize actualiza el código para que coincida con los documentos de verdad.
229
- - Truth Check audita la salud de la verdad del repositorio.
400
+ Es una ayuda de selección y planificación, no una autorización de escritura ni un reemplazo de Truth Check.
230
401
 
231
- Los `README.md` de funciones son índices. Se espera que Truth Sync lea y actualice documentos hoja acotados para el comportamiento actual. Las superficies de flujo generadas preservan la autoridad de las reglas del repositorio mientras tratan el código de implementación y los documentos canónicos de verdad como evidencia del comportamiento actual.
402
+ ## Auditoría de verdad del repositorio
232
403
 
233
- Las superficies generadas son administradas por Truthmark, incluyen un marcador de versión y pueden refrescarse con `truthmark init`.
404
+ Usa Truth Check cuando quieres un flujo de auditoría orientado a agentes.
234
405
 
235
- ## Comandos
406
+ ```text
407
+ /truthmark-check audita rutas y cobertura de verdad antes de la revisión
408
+ ```
236
409
 
237
- Truthmark V1 mantiene la CLI pequeña a propósito porque el flujo continuo debe vivir en las superficies instaladas del agente, no en una lista larga de comandos manuales de uso diario. En repositorios derivados, `truthmark config` crea el contrato de jerarquía confirmado en Git, `truthmark init` instala y refresca superficies de flujo de trabajo a partir de esa configuración revisada, `truthmark check` valida los artefactos de verdad para auditorías manuales, CI o depuración, y los comandos de inteligencia del repositorio generan artefactos derivados de revisión cuando hay herramientas locales disponibles.
410
+ Usa la CLI orientada a personas cuando quieres validación en terminal:
238
411
 
239
412
  ```bash
413
+ truthmark check
414
+ ```
415
+
416
+ Ambas son útiles. No son la misma superficie.
417
+
418
+ ## Comandos CLI orientados a personas
419
+
420
+ La mayoría de los mantenedores empieza con tres comandos.
421
+
422
+ | Comando | Propósito |
423
+ | --- | --- |
424
+ | `truthmark config` | Crea `.truthmark/config.yml`. Solo escribe ese archivo, salvo que se use `--stdout`. |
425
+ | `truthmark init` | Instala o refresca superficies de flujo configuradas desde la config revisada. |
426
+ | `truthmark check` | Valida configuración, autoridad, rutas, documentos con decisiones, frontmatter, enlaces internos, alcance de rama, superficies generadas, frescura y diagnósticos de cobertura. |
427
+
428
+ Los ayudantes opcionales de inteligencia del repositorio generan contexto derivado para revisión sobre el checkout activo. Los paquetes de skill de flujo generados también pueden exponer manifests y policies de helpers que llaman a validadores CLI `truthmark validate ... --json` instalados; esos helpers son aceleradores, no scripts locales empaquetados en el repo ni fuentes de verdad. Los prompts independientes de Copilot y los comandos de Gemini usan el mismo contrato de validador CLI cuando el runner instalado está disponible; de lo contrario informan un estado de helper omitido visible y hacen validación manual.
429
+
430
+ No son fuentes de verdad.
431
+
432
+ | Comando | Propósito |
433
+ | --- | --- |
434
+ | `truthmark index` | Construye JSON de RepoIndex y RouteMap para el checkout activo. |
435
+ | `truthmark impact --base <ref>` | Mapea archivos cambiados a documentos de verdad enrutados, rutas propietarias, pruebas cercanas y símbolos públicos. |
436
+ | `truthmark context --workflow <workflow> [--base <ref>]` | Genera un ContextPack acotado para Truth Sync, Truth Document o Truth Realize. Usa `--format markdown` para una versión legible por personas. |
437
+
438
+ La salida estructurada está disponible con `--json` donde se admite.
439
+
440
+ ## Configuración
441
+
442
+ Truthmark es config-first.
443
+
444
+ El archivo principal de configuración es:
445
+
446
+ ```text
447
+ .truthmark/config.yml
448
+ ```
449
+
450
+ Los repositorios nuevos deberían ejecutar:
451
+
452
+ ```bash
453
+ truthmark config
454
+ ```
455
+
456
+ Luego revisar la config generada antes de ejecutar:
457
+
458
+ ```bash
459
+ truthmark init
460
+ ```
461
+
462
+ Las áreas importantes de configuración incluyen:
463
+
464
+ | Área de config | Propósito |
465
+ | --- | --- |
466
+ | `version` | Versión del contrato de configuración. |
467
+ | `platforms` | Hosts de agentes que deben recibir superficies generadas específicas de plataforma. |
468
+ | `docs.layout` | Modo actual de layout de documentación. |
469
+ | `docs.roots` | Raíces nombradas de documentación canónica. |
470
+ | `docs.routing.root_index` | Ruta del índice raíz de rutas. |
471
+ | `docs.routing.area_files_root` | Directorio para archivos de rutas secundarias delegadas. |
472
+ | `docs.routing.default_area` | Nombre base de la ruta secundaria inicial generada. |
473
+ | `docs.routing.max_delegation_depth` | Profundidad máxima actual de delegación de rutas. |
474
+ | `authority` | Documentos canónicos y globs ordenados usados como autoridad de verdad del repositorio. |
475
+ | `instruction_targets` | Archivos que reciben bloques de instrucciones administrados compartidos, como `AGENTS.md`. |
476
+ | `frontmatter.required` | Campos de metadatos que producen diagnósticos de error cuando faltan. |
477
+ | `frontmatter.recommended` | Campos de metadatos que producen diagnósticos de revisión cuando faltan. |
478
+ | `ignore` | Patrones glob excluidos de checks relevantes y lógica de rutas. |
479
+
480
+ ## Rutas de verdad del repositorio
481
+
482
+ Truthmark mapea superficies de código a documentos de verdad.
483
+
484
+ Los archivos principales de rutas son:
485
+
486
+ ```text
487
+ docs/truthmark/areas.md
488
+ docs/truthmark/areas/**/*.md
489
+ ```
490
+
491
+ Una ruta le dice al agente:
492
+
493
+ - qué superficie de código pertenece a un área
494
+ - qué documentos de verdad poseen esa área
495
+ - cuándo debe actualizarse la verdad
496
+ - qué tipo de documento de verdad participa
497
+
498
+ El scaffold predeterminado empieza amplio. Los repositorios existentes suelen tener que dividir la ruta predeterminada en áreas reales de propiedad.
499
+
500
+ Ejemplo:
501
+
502
+ ```text
503
+ /truthmark-structure divide el área amplia repository en frontend, backend, billing y deployment
504
+ ```
505
+
506
+ Un buen routing da a Truth Sync destinos precisos.
507
+
508
+ Un mal routing hace que los agentes adivinen.
509
+
510
+ ## Qué instala Truthmark
511
+
512
+ Truthmark instala una capa compacta de verdad nativa del repositorio.
513
+
514
+ Lo instala en cuatro capas:
515
+
516
+ - config y routing para límites de ownership
517
+ - documentos truth canónicos y plantillas iniciales
518
+ - bloques de instrucciones administrados y compactos para contexto de agente en todo el repo
519
+ - paquetes de workflow, comandos, prompts y agentes verificadores host-native para las plataformas habilitadas en la config
520
+
521
+ Truthmark conserva el contenido manual fuera de los bloques de instrucciones administrados.
522
+
523
+ Las superficies de flujo generadas son administradas por Truthmark y pueden refrescarse volviendo a ejecutar:
524
+
525
+ ```bash
526
+ truthmark init
527
+ ```
528
+
529
+ ## Subagentes y checks acotados de evidencia
530
+
531
+ Donde el host lo admite, Truthmark puede instalar agentes verificadores con alcance de proyecto y un `truth-doc-writer` con lease.
532
+
533
+ Ayudan a mantener acotadas las tareas grandes de verdad:
534
+
535
+ - route auditors inspeccionan la propiedad de rutas
536
+ - claim verifiers revisan si las afirmaciones de docs están respaldadas por evidencia
537
+ - doc reviewers inspeccionan la calidad de los documentos de verdad
538
+ - leased doc writers manejan shards acotados de escritura de documentos de verdad
539
+
540
+ El flujo padre sigue siendo dueño de la interpretación final, los límites de escritura, la validación del diff y la aceptación.
541
+
542
+ Esto es importante: los subagentes ayudan con trabajo acotado de evidencia. No reemplazan el contrato principal del flujo.
543
+
544
+ ## Bucle de revisión
545
+
546
+ Truthmark está diseñado para revisión normal en Git.
547
+
548
+ Un buen traspaso asistido por IA debería mostrar:
549
+
550
+ ```text
551
+ diff de código
552
+ evidencia de pruebas
553
+ diff de documentos de verdad, si hace falta
554
+ cambios de rutas, si hacen falta
555
+ informe del agente
556
+ ```
557
+
558
+ Quien revisa debería poder responder:
559
+
560
+ - ¿Qué código cambió?
561
+ - ¿Qué documentos de verdad poseen ese código?
562
+ - ¿Esos documentos necesitaron actualizaciones?
563
+ - Si no, ¿por qué no?
564
+ - ¿El agente permaneció dentro del límite de escritura del flujo?
565
+ - ¿Se incluye evidencia de pruebas o verificación?
566
+
567
+ ## Ejemplos
568
+
569
+ ### Inicializar un repositorio
570
+
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` solo escribe `.truthmark/config.yml`, salvo que se use `--stdout`.
578
+ ### Quitar plataformas de agentes no usadas
254
579
 
255
- `init` requiere `.truthmark/config.yml` y luego instala o refresca los archivos locales de flujo de trabajo.
580
+ Edita:
256
581
 
257
- `check` valida configuración, autoridad, enrutamiento, documentos que contienen decisiones, frontmatter, enlaces internos, alcance de rama y diagnósticos de cobertura.
582
+ ```text
583
+ .truthmark/config.yml
584
+ ```
258
585
 
259
- `index` construye JSON de RepoIndex y RouteMap para el checkout activo.
586
+ Luego vuelve a ejecutar:
260
587
 
261
- `impact --base <ref>` mapea los archivos cambiados a los truth docs enrutados, rutas propietarias, pruebas cercanas y símbolos públicos.
588
+ ```bash
589
+ truthmark init
590
+ truthmark check
591
+ ```
262
592
 
263
- `context --workflow <workflow> [--base <ref>]` genera un ContextPack acotado para Truth Sync, Truth Document o Truth Realize. `--format markdown` lo renderiza en un formato legible para personas.
593
+ ### Dividir una ruta amplia
264
594
 
265
- Truth Structure, Truth Document, Truth Sync, Truth Realize y Truth Check son flujos de trabajo instalados para agentes, no comandos CLI principales de uso diario.
595
+ ```text
596
+ /truthmark-structure divide el área amplia repository en auth, billing, notifications y deployment
597
+ ```
266
598
 
267
- Se ejecutan a través de las superficies configuradas del host agente, por ejemplo Codex/Claude/Copilot `/truthmark-*`, OpenCode `/skill truthmark-*` o Gemini `/truthmark:*`.
599
+ ### Documentar comportamiento implementado
268
600
 
269
601
  ```text
270
- /truthmark-check audita el enrutamiento y la cobertura de verdad antes de la revisión
602
+ /truthmark-document documenta el flujo implementado de restablecimiento de contraseña bajo docs/truth/authentication
271
603
  ```
272
604
 
273
- ## Por qué existe
605
+ ### Sincronizar después de cambios de código
274
606
 
275
- La mayoría de los flujos de programación con IA optimizan la siguiente respuesta. Truthmark optimiza el siguiente traspaso.
276
- Asume que los equipos serios necesitan:
607
+ ```text
608
+ /truthmark-sync sincroniza ahora la verdad del repositorio antes del traspaso
609
+ ```
277
610
 
278
- - verdad de producto específica de cada rama
279
- - decisiones duraderas de arquitectura y API
280
- - propiedad explícita entre documentación y código
281
- - límites seguros de escritura para agentes
282
- - diffs normales de Git que humanos puedan revisar
283
- - Markdown legible que el equipo pueda inspeccionar sin herramientas especiales
284
- - verdad que viaje con la rama en lugar de vivir en estado oculto de sesión
285
- - flujos que sigan funcionando aunque el paquete no esté instalado globalmente
611
+ ### Realizar una decisión doc-first
286
612
 
287
- ## Estado del proyecto
613
+ ```text
614
+ /truthmark-realize realiza docs/truth/billing/invoice-retry-policy.md como código
615
+ ```
616
+
617
+ ### Auditar la salud de verdad desde la terminal
618
+
619
+ ```bash
620
+ truthmark check
621
+ ```
622
+
623
+ ### Generar contexto de impacto de rama
624
+
625
+ ```bash
626
+ truthmark impact --base main
627
+ ```
628
+
629
+ ### Generar contexto de workflow
630
+
631
+ ```bash
632
+ truthmark context --workflow truth-sync --base main --format markdown
633
+ ```
288
634
 
289
- Truthmark no es un servidor de memoria ni un servidor MCP. Es una práctica de repositorio empaquetada como un pequeño instalador CLI más superficies de flujo de trabajo nativas para agentes que convierten las reglas del flujo de IA en infraestructura del repositorio.
635
+ ## Estado del proyecto
290
636
 
291
- V1 actualmente ofrece:
637
+ Truthmark V1 actualmente proporciona:
292
638
 
293
639
  - `truthmark config`
294
640
  - `truthmark init`
@@ -296,39 +642,123 @@ V1 actualmente ofrece:
296
642
  - `truthmark index`
297
643
  - `truthmark impact`
298
644
  - `truthmark context`
299
- - instrucciones de flujo de trabajo administradas en `AGENTS.md`
300
- - superficies de skill generadas para Truth Structure, Truth Document, Truth Sync, Truth Realize y Truth Check en los anfitriones de agentes configurados
301
645
  - metadatos de alcance de rama
302
- - diagnósticos de configuración, autoridad, enrutamiento, estructura de decisiones, frontmatter, enlaces y cobertura políglota
303
- - artefactos derivados de RepoIndex, RouteMap, ImpactSet y ContextPack para una revisión local más rápida cuando la CLI está disponible
646
+ - bloques de instrucciones administrados
647
+ - superficies generadas de flujo Truth Structure
648
+ - superficies generadas de flujo Truth Document
649
+ - superficies generadas de flujo Truth Sync
650
+ - superficies generadas de flujo Truth Preview
651
+ - superficies generadas de flujo Truth Realize
652
+ - superficies generadas de flujo Truth Check
653
+ - diagnósticos de rutas, autoridad, estructura de decisiones, frontmatter, enlaces, frescura, superficies generadas y cobertura
654
+ - artefactos derivados RepoIndex, RouteMap, ImpactSet y ContextPack
655
+ - superficies específicas de host para Codex, Claude Code, GitHub Copilot, OpenCode y Gemini CLI
656
+
657
+ ## Desarrollo
658
+
659
+ Instalar dependencias:
660
+
661
+ ```bash
662
+ npm install
663
+ ```
664
+
665
+ Ejecutar la CLI local de desarrollo:
666
+
667
+ ```bash
668
+ npm run dev -- init
669
+ npm run dev -- check
670
+ ```
671
+
672
+ Ejecutar el check completo del proyecto:
673
+
674
+ ```bash
675
+ npm run check
676
+ ```
677
+
678
+ Scripts útiles:
679
+
680
+ | Script | Propósito |
681
+ | --- | --- |
682
+ | `npm run dev` | Ejecuta el punto de entrada CLI en TypeScript con `tsx`. |
683
+ | `npm run build` | Construye el paquete. |
684
+ | `npm run lint` | Ejecuta ESLint. |
685
+ | `npm run typecheck` | Ejecuta checks de TypeScript. |
686
+ | `npm run test` | Ejecuta las pruebas. |
687
+ | `npm run check` | Ejecuta lint, typecheck, pruebas y build. |
688
+ | `npm run release:check` | Ejecuta validación orientada a release. |
689
+
690
+ Cuando cambies Truthmark en sí, consulta [CONTRIBUTORS.md](CONTRIBUTORS.md).
304
691
 
305
692
  ## Documentación
306
693
 
307
- El README raíz es para personas que evalúan y prueban el paquete. Las especificaciones funcionales y de negocio detalladas viven en `docs/`:
694
+ El README es el camino rápido para evaluación y configuración.
695
+
696
+ El comportamiento actual detallado vive bajo `docs/`:
308
697
 
309
698
  - [Índice de documentación](docs/README.md)
310
699
  - [Resumen de arquitectura](docs/architecture/overview.md)
311
700
  - [Contratos de API y CLI](docs/truth/contracts.md)
312
701
  - [Comportamiento de init y scaffold](docs/truth/init-and-scaffold.md)
313
702
  - [Diagnósticos de check](docs/truth/check-diagnostics.md)
314
- - [Flujos de trabajo instalados](docs/truth/workflows/overview.md)
703
+ - [Flujos instalados](docs/truth/workflows/overview.md)
315
704
  - [Guía para mantener la verdad del repositorio](docs/standards/maintaining-repository-truth.md)
316
705
 
317
- El comportamiento actual pertenece al árbol canónico de documentación anterior.
706
+ ## Límites de diseño
318
707
 
319
- ## No objetivos
708
+ Truthmark es intencionalmente pequeño.
320
709
 
321
- Truthmark V1 no es:
710
+ No es:
322
711
 
323
712
  - un servicio alojado
324
713
  - un servidor MCP
325
714
  - una base de datos vectorial
326
715
  - un generador de sitios de documentación
327
716
  - un producto de enforcement para CI o PR
328
- - un sustituto de pruebas, revisión de código o liderazgo técnico
717
+ - un reemplazo de pruebas, revisión de código o liderazgo técnico
329
718
  - un motor autónomo de reescritura de código
719
+ - un framework de entrenamiento o fine-tuning de modelos
720
+ - una capa oculta de memoria
721
+
722
+ Esos límites son parte del producto.
723
+
724
+ Truthmark mantiene el flujo local, confirmado, acotado a la rama y revisable.
725
+
726
+ ## Seguridad y disciplina de revisión
727
+
728
+ Truthmark ayuda a que el repositorio se mantenga honesto. No prueba que el código sea correcto.
729
+
730
+ Los equipos deberían seguir:
330
731
 
331
- Es una forma ligera de hacer que los agentes locales de programación con IA respeten la verdad que tu equipo guarda en Git.
732
+ - ejecutando pruebas relevantes
733
+ - revisando cambios de código funcional
734
+ - revisando cambios de documentos de verdad
735
+ - manteniendo secretos fuera de la documentación
736
+ - manteniendo instrucciones específicas del repositorio fuera de bloques administrados
737
+ - revisando diffs de superficies de flujo generadas después de upgrades
738
+ - conservando propiedad humana sobre decisiones de producto y arquitectura
739
+
740
+ Truthmark hace visible el contexto del agente. No reemplaza el juicio humano.
741
+
742
+ ## Dirección de la hoja de ruta
743
+
744
+ La dirección futura actual enfatiza:
745
+
746
+ - reportes de evidencia más fuertes en `truthmark check`
747
+ - ejemplos de adopción más claros
748
+ - repositorios de ejemplo que muestren ciclos reales de Truth Sync
749
+ - guías de migración para equipos que ya usan archivos de instrucciones para agentes
750
+ - pruebas de conformidad para superficies generadas de host
751
+ - pistas de verdad obsoleta conscientes de rutas
752
+ - checklists acotadas de implementación para trabajo doc-first
753
+
754
+ El centro de gravedad se mantiene igual:
755
+
756
+ ```text
757
+ verdad del repositorio
758
+ flujos nativos para agentes
759
+ revisión en Git
760
+ contexto acotado a la rama
761
+ ```
332
762
 
333
763
  ## Licencia
334
764