truthmark 1.4.0 → 1.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/README.de.md +623 -193
  2. package/README.es.md +624 -194
  3. package/README.md +614 -191
  4. package/README.ru.md +631 -201
  5. package/README.zh.md +630 -198
  6. package/dist/main.js +846 -39
  7. package/dist/main.js.map +1 -1
  8. package/package.json +1 -1
package/README.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 Preview previsualiza el enrutamiento de flujo probable antes de editar, sin autorizar escrituras.
100
- - Truth Realize ofrece a los cambios que empiezan en documentación una ruta acotada para actualizar código.
101
- - `truthmark check` valida los artefactos de verdad resultantes.
102
- - Todo el modelo se mantiene local-first y nativo de Git.
63
+ Tiene dos superficies distintas, y la distinción importa.
103
64
 
104
- 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
105
66
 
106
- ## Primeros pasos
67
+ La CLI es para mantenedores, revisores y automatización.
107
68
 
108
- 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.
109
70
 
110
71
  ```bash
111
- cd /path/to/your-repo
112
- npm install -g truthmark
113
72
  truthmark config
114
73
  truthmark init
115
74
  truthmark check
116
75
  ```
117
76
 
118
- 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:
119
125
 
120
126
  ```bash
121
- cd /path/to/truthmark
122
- npm install
123
- npm run build
124
127
  cd /path/to/your-repo
125
- node /path/to/truthmark/dist/main.js config
126
- node /path/to/truthmark/dist/main.js init
127
- node /path/to/truthmark/dist/main.js check
128
+ npm install -g truthmark
128
129
  ```
129
130
 
130
- 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:
131
138
 
132
139
  ```text
133
140
  .truthmark/config.yml
134
- docs/truthmark/areas.md
135
- docs/truthmark/areas/repository.md
136
- docs/templates/behavior-doc.md
137
- docs/truth/README.md
138
- docs/truth/repository/README.md
139
- docs/truth/repository/overview.md
140
- AGENTS.md
141
- CLAUDE.md
142
- GEMINI.md
143
141
  ```
144
142
 
145
- 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`.
146
- 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.
147
165
 
148
- 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.
149
167
 
150
- ## Cómo se ejecuta
168
+ ## Primer uso real
151
169
 
152
- 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.
153
171
 
154
- ### Comportamiento existente sin docs
172
+ El scaffold predeterminado empieza con un área amplia `repository`. Los repositorios reales suelen necesitar rutas más precisas.
155
173
 
156
- 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:
157
175
 
158
176
  ```text
159
- el usuario identifica un comportamiento implementado o un endpoint de api
160
- el usuario invoca explícitamente truth document
161
- el agente lee implementación, pruebas, rutas y docs existentes
162
- el agente solo escribe truth docs y rutas
163
- revisar el diff de truth docs
177
+ /truthmark-structure divide el área amplia repository en auth, billing y notifications
164
178
  ```
165
179
 
166
- 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:
167
251
 
168
252
  ```text
169
- /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
170
301
  ```
171
302
 
172
- ### 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:*` |
173
310
 
174
- 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:
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
331
+
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.
175
346
 
176
347
  ```text
177
348
  el agente cambia código funcional
178
- se ejecutan las pruebas relevantes
179
- el flujo instalado truth sync se ejecuta antes de que el agente termine
180
- revisar el diff de truth docs si se produjo uno
181
- 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
182
354
  ```
183
355
 
184
- 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.
185
-
186
- 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:
187
357
 
188
358
  ```text
189
- /truthmark-sync sincroniza ahora la verdad del repositorio antes de la entrega
359
+ /truthmark-sync sincroniza ahora la verdad del repositorio antes del traspaso
190
360
  ```
191
361
 
192
- ### Cambios doc-first
362
+ ## Comportamiento existente sin docs
193
363
 
194
- 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.
195
365
 
196
366
  ```text
197
- el usuario edita truth docs
198
- el usuario invoca explícitamente truth realize
199
- el agente lee truth docs y el código relevante
200
- el agente actualiza solo el código
201
- se ejecutan las pruebas relevantes
202
- confirmar o entregar el trabajo
367
+ /truthmark-document documenta el comportamiento implementado de timeout de sesión bajo docs/truth/authentication
203
368
  ```
204
369
 
205
- 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.
375
+
376
+ ## Cambios doc-first
206
377
 
207
- Codex, Claude Code y los IDEs de Copilot compatibles pueden invocarlo con `/truthmark-realize`. Los hosts de estilo OpenCode pueden usar `/skill truthmark-realize`.
378
+ Usa Truth Realize cuando una decisión de producto o arquitectura empieza en documentos y el código debe actualizarse para coincidir.
208
379
 
209
380
  ```text
210
381
  /truthmark-realize realiza docs/truth/authentication/session-timeout.md como código
211
382
  ```
212
383
 
213
- ## Qué instala
384
+ Truth Realize es doc-first.
214
385
 
215
- 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.
386
+ Los documentos de verdad lideran. El código sigue.
216
387
 
217
- Truthmark instala dos superficies distintas:
388
+ El agente no debe editar los documentos de verdad que está realizando.
218
389
 
219
- - comandos CLI orientados a personas, ejecutados por personas o CI para configurar el repositorio, refrescar archivos instalados, validar artefactos de verdad y generar opcionalmente contexto derivado para revisión
220
- - superficies de flujo de trabajo para agentes, invocadas por agentes de código u hosts de agentes durante flujos de implementación; no son comandos de terminal diarios adicionales para personas
390
+ ## Preview de rutas de solo lectura
221
391
 
222
- - `.truthmark/config.yml` para el contrato de jerarquía confirmado y legible por máquina
223
- - `docs/truthmark/areas.md` para el índice raíz de rutas
224
- - `docs/truthmark/areas/**/*.md` para archivos de rutas secundarias delegadas
225
- - `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
226
- - bloques de instrucciones administrados para plataformas configuradas como `AGENTS.md`, `CLAUDE.md`, instrucciones de Copilot y `GEMINI.md`
227
- - skills, prompts o comandos nativos del host para Truth Structure, Truth Document, Truth Sync, Truth Preview, Truth Realize y Truth Check
228
- - verificadores de solo lectura de Codex, Claude Code, GitHub Copilot y OpenCode con alcance de proyecto, más agentes `truth-doc-writer` con lease donde el host admite agentes, bajo `.codex/agents/`, `.claude/agents/`, `.github/agents/` y `.opencode/agents/` para auditorías propias del flujo y shards de documentación concedidos por el padre
392
+ Usa Truth Preview antes de un cambio cuando el agente necesita entender la ruta probable.
229
393
 
230
- Las superficies de flujo de trabajo instaladas son el entorno de ejecución:
394
+ ```text
395
+ /truthmark-preview previsualiza la ruta de verdad probable para cambios en la API de billing
396
+ ```
397
+
398
+ Truth Preview es read-only.
399
+
400
+ Es una ayuda de selección y planificación, no una autorización de escritura ni un reemplazo de Truth Check.
401
+
402
+ ## Auditoría de verdad del repositorio
403
+
404
+ Usa Truth Check cuando quieres un flujo de auditoría orientado a agentes.
405
+
406
+ ```text
407
+ /truthmark-check audita rutas y cobertura de verdad antes de la revisión
408
+ ```
409
+
410
+ Usa la CLI orientada a personas cuando quieres validación en terminal:
231
411
 
232
- - Truth Structure crea o repara el enrutamiento de áreas y documentos de verdad iniciales.
233
- - Truth Document crea o repara documentos de verdad para comportamiento ya implementado.
234
- - Truth Sync mantiene alineados los documentos de verdad asignados con los cambios funcionales.
235
- - Truth Preview previsualiza el enrutamiento de flujo probable antes de editar sin escribir archivos.
236
- - Truth Realize actualiza el código para que coincida con los documentos de verdad.
237
- - Truth Check audita la salud de la verdad del repositorio.
412
+ ```bash
413
+ truthmark check
414
+ ```
238
415
 
239
- 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.
416
+ Ambas son útiles. No son la misma superficie.
240
417
 
241
- Las superficies generadas son administradas por Truthmark, incluyen un marcador de versión y pueden refrescarse con `truthmark init`.
418
+ ## Comandos CLI orientados a personas
242
419
 
243
- ## Comandos
420
+ La mayoría de los mantenedores empieza con tres comandos.
244
421
 
245
- Truthmark V1 mantiene enfocada la CLI de terminal. La mayoría de los usuarios humanos solo necesita configuración, actualización y validación:
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. |
246
427
 
247
- | CLI orientada a personas | Uso |
248
- | ------------------------ | --- |
249
- | `truthmark config` | Crea `.truthmark/config.yml`; solo escribe ese archivo, salvo que se use `--stdout`. |
250
- | `truthmark init` | Instala o refresca los archivos locales de flujo de trabajo desde la configuración revisada. |
251
- | `truthmark check` | Valida configuración, autoridad, enrutamiento, documentos que contienen decisiones, frontmatter, enlaces internos, alcance de rama y diagnósticos de cobertura. |
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.
252
429
 
253
- Los demás comandos CLI son ayudantes opcionales de inteligencia del repositorio. Generan contexto derivado para revisión sobre el checkout activo; no son fuentes de verdad:
430
+ No son fuentes de verdad.
254
431
 
255
- | CLI opcional | Uso |
256
- | ------------ | --- |
432
+ | Comando | Propósito |
433
+ | --- | --- |
257
434
  | `truthmark index` | Construye JSON de RepoIndex y RouteMap para el checkout activo. |
258
- | `truthmark impact --base <ref>` | Mapea los archivos cambiados a truth docs enrutados, rutas propietarias, pruebas cercanas y símbolos públicos. |
259
- | `truthmark 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. |
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.
260
443
 
261
- Todos los comandos CLI anteriores admiten `--json` cuando la salida estructurada es útil para automatización.
444
+ El archivo principal de configuración es:
262
445
 
263
- Truth Structure, Truth Document, Truth Sync, Truth Preview, Truth Realize y Truth Check son flujos de trabajo instalados para agentes, no comandos CLI principales de uso diario.
446
+ ```text
447
+ .truthmark/config.yml
448
+ ```
264
449
 
265
- Se ejecutan a través de las superficies configuradas del host agente, por ejemplo Codex/Claude/Copilot `/truthmark-*`, OpenCode `/skill truthmark-*` o Gemini `/truthmark:*`.
450
+ Los repositorios nuevos deberían ejecutar:
266
451
 
267
- Estas invocaciones parecen comandos porque los hosts de agentes exponen skills mediante slash commands. Trátalas como instrucciones para un agente, no como comandos de terminal que una persona deba ejecutar.
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:
268
485
 
269
486
  ```text
270
- /truthmark-check audita el enrutamiento y la cobertura de verdad antes de la revisión
487
+ docs/truthmark/areas.md
488
+ docs/truthmark/areas/**/*.md
271
489
  ```
272
490
 
273
- ## Por qué existe
491
+ Una ruta le dice al agente:
274
492
 
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:
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
277
497
 
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
498
+ El scaffold predeterminado empieza amplio. Los repositorios existentes suelen tener que dividir la ruta predeterminada en áreas reales de propiedad.
286
499
 
287
- ## Estado del proyecto
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
573
+ truthmark config
574
+ truthmark init
575
+ truthmark check
576
+ ```
577
+
578
+ ### Quitar plataformas de agentes no usadas
579
+
580
+ Edita:
581
+
582
+ ```text
583
+ .truthmark/config.yml
584
+ ```
585
+
586
+ Luego vuelve a ejecutar:
587
+
588
+ ```bash
589
+ truthmark init
590
+ truthmark check
591
+ ```
288
592
 
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.
593
+ ### Dividir una ruta amplia
290
594
 
291
- V1 actualmente ofrece:
595
+ ```text
596
+ /truthmark-structure divide el área amplia repository en auth, billing, notifications y deployment
597
+ ```
598
+
599
+ ### Documentar comportamiento implementado
600
+
601
+ ```text
602
+ /truthmark-document documenta el flujo implementado de restablecimiento de contraseña bajo docs/truth/authentication
603
+ ```
604
+
605
+ ### Sincronizar después de cambios de código
606
+
607
+ ```text
608
+ /truthmark-sync sincroniza ahora la verdad del repositorio antes del traspaso
609
+ ```
610
+
611
+ ### Realizar una decisión doc-first
612
+
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
+ ```
634
+
635
+ ## Estado del proyecto
636
+
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 Preview, 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