truthmark 1.4.0 → 1.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/README.de.md +672 -194
  2. package/README.es.md +673 -195
  3. package/README.md +663 -192
  4. package/README.ru.md +680 -202
  5. package/README.zh.md +679 -199
  6. package/dist/main.js +1307 -145
  7. package/dist/main.js.map +1 -1
  8. package/package.json +1 -2
package/README.es.md CHANGED
@@ -1,294 +1,687 @@
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
129
+ ```
130
+
131
+ ### Crear el contrato de verdad del repositorio
132
+
133
+ ```bash
134
+ truthmark config
128
135
  ```
129
136
 
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:
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
+ | Portal opcional | Genera un sitio HTML estático confirmado desde documentos de verdad Markdown cuando se habilita y solicita explícitamente. |
198
+
199
+ ## Resumen visual
200
+
201
+ ![Características de Truthmark](docs/assets/truthmark-features.png)
202
+
203
+ **Características:** qué instala Truthmark y cómo se divide la superficie de flujo.
204
+
205
+ ![Posición de Truthmark](docs/assets/truthmark-position.png)
206
+
207
+ **Posición:** dónde encaja Truthmark frente a prompts, memoria y flujos de especificación.
208
+
209
+ ![Flujo de sync de Truthmark](docs/assets/truthmark-syncflow.png)
210
+
211
+ **Flujo de sync:** cómo Truth Sync cierra cambios normales de código antes del traspaso.
212
+
213
+ ## Por qué los equipos lo adoptan
214
+
215
+ Truthmark es para equipos que ya saben que los agentes de IA pueden generar código.
216
+
217
+ El siguiente problema es la gobernanza.
218
+
219
+ No gobernanza como ceremonia. Gobernanza como una pregunta simple:
220
+
221
+ > Después de este cambio asistido por IA, ¿el repositorio todavía dice la verdad?
222
+
223
+ Truthmark ayuda a los equipos a responder con archivos confirmados, rutas explícitas y diffs revisables.
224
+
225
+ Es útil cuando necesitas:
226
+
227
+ - menos deriva de documentación
228
+ - mejores traspasos
229
+ - verdad de producto específica de cada rama
230
+ - contexto duradero de arquitectura y API
231
+ - propiedad explícita entre documentos y código
232
+ - límites de escritura más seguros para agentes
233
+ - contexto revisable en lugar de memoria oculta
234
+ - flujos de IA que sigan funcionando desde archivos confirmados del repo
235
+
236
+ ## Dónde encaja Truthmark
237
+
238
+ Truthmark no reemplaza prompts, memoria, especificaciones, pruebas ni revisión de código.
239
+
240
+ Les da a esos flujos un lugar duradero donde aterrizar en Git.
241
+
242
+ | Necesidad | Mejor opción |
243
+ | --- | --- |
244
+ | Mejor salida de una sesión de agente | Mejor prompt |
245
+ | Continuidad personal o por sesión | Herramienta de memoria |
246
+ | Trabajo de funciones plan-first | Flujo de especificación |
247
+ | Verdad acotada a la rama que viaja con el código | Truthmark |
248
+ | Validar la corrección del comportamiento | Pruebas y revisión |
249
+ | Revisar cambios de contexto asistidos por IA | Truthmark más revisión Git |
250
+
251
+ El carril de Truthmark es estrecho por diseño:
167
252
 
168
253
  ```text
169
- /truthmark-document documenta el comportamiento implementado del timeout de sesión en docs/truth/authentication
254
+ hacer explícita la verdad del repositorio
255
+ mapearla al código
256
+ instalar flujos de agentes alrededor de ella
257
+ mantener el resultado revisable en Git
258
+ ```
259
+
260
+ ## Cómo se ejecuta Truthmark
261
+
262
+ Truthmark se ejecuta localmente contra el worktree Git activo.
263
+
264
+ La CLI orientada a personas lee y escribe archivos del repositorio, y luego termina.
265
+
266
+ 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.
267
+
268
+ Las capas encajan así:
269
+
270
+ ```mermaid
271
+ flowchart LR
272
+ Human["Human / CI"] --> CLI["Truthmark CLI"]
273
+ CLI --> Config["Config y routing"]
274
+ CLI --> Truth["Documentos truth canónicos"]
275
+ CLI --> Surfaces["Workflows host-native generados"]
276
+ Surfaces --> Hosts["Codex / Claude Code / Copilot / OpenCode / Gemini"]
277
+ Hosts --> Worktree["Git worktree activo"]
278
+ Hosts -->|"helper checks / validate / index"| CLI
279
+ Worktree --> Truth
170
280
  ```
171
281
 
172
- ### Cambios de código normales
282
+ 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.
283
+
284
+ 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.
285
+
286
+ Las superficies de flujo generadas incluyen marcadores de versión de Truthmark. Después de actualizar Truthmark, vuelve a ejecutar:
287
+
288
+ ```bash
289
+ truthmark init
290
+ ```
291
+
292
+ Luego revisa los diffs generados.
293
+
294
+ ## Plataformas de agentes compatibles
295
+
296
+ La configuración predeterminada incluye todas las plataformas compatibles.
297
+
298
+ Elimina de `.truthmark/config.yml` las plataformas que no uses, y luego vuelve a ejecutar:
299
+
300
+ ```bash
301
+ truthmark init
302
+ ```
303
+
304
+ | Nombre de plataforma en config | Superficie generada | Forma de invocación |
305
+ | --- | --- | --- |
306
+ | `codex` | `.codex/skills/truthmark-*/`, `.codex/agents/` | `/truthmark-*` o `$truthmark-*` |
307
+ | `claude-code` | `.claude/skills/truthmark-*/`, `.claude/agents/`, `CLAUDE.md` | `/truthmark-*` |
308
+ | `github-copilot` | `.github/skills/truthmark-*/`, `.github/prompts/`, `.github/agents/`, `.github/copilot-instructions.md` | `/truthmark-*` en IDEs de Copilot compatibles; agentes personalizados `@truth-*` en Copilot CLI |
309
+ | `opencode` | `.opencode/skills/truthmark-*/`, `.opencode/agents/` | `/skill truthmark-*` |
310
+ | `gemini-cli` | `.gemini/skills/truthmark-*/`, `.gemini/commands/truthmark/`, `.gemini/agents/`, `GEMINI.md` | `/truthmark:*` |
311
+
312
+ Los nombres de plataforma desconocidos son errores de configuración.
313
+
314
+ Eliminar una plataforma detiene futuros refrescos para esa plataforma. No elimina archivos generados previamente.
315
+
316
+ ## Flujos orientados a IA
317
+
318
+ Estos flujos se instalan en hosts de programación con IA compatibles.
319
+
320
+ Los usan agentes o hosts de agentes durante el trabajo en el repositorio. No son comandos de shell de nivel superior.
321
+
322
+ | Flujo | Dirección | Úsalo cuando | Límite de escritura |
323
+ | --- | --- | --- | --- |
324
+ | 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. |
325
+ | 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. |
326
+ | 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. |
327
+ | Truth Preview | read-only | El agente necesita previsualizar rutas probables antes de editar. | Solo lee. No autoriza escrituras. |
328
+ | 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. |
329
+ | Truth Check | audit-first | Un revisor o agente necesita auditar la salud de la verdad del repositorio. | Audita e informa. |
330
+ | Truthmark Portal | presentation-only | Una persona pide explícitamente un Portal HTML estático navegable sobre los documentos de verdad del repositorio. | Escribe solo archivos estáticos generados no canónicos bajo el directorio de salida Portal configurado. |
331
+
332
+ ### Distinción importante
173
333
 
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:
334
+ No confundas estas dos superficies:
335
+
336
+ | Superficie | Usada por | Ejemplo | Significado |
337
+ | --- | --- | --- | --- |
338
+ | CLI humana | personas, scripts, checks tipo CI | `truthmark check` | Validar artefactos de verdad del repositorio desde la terminal. |
339
+ | 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. |
340
+
341
+ Los nombres están relacionados a propósito, pero las superficies son distintas.
342
+
343
+ ## Cambio normal de código asistido por IA
344
+
345
+ La mayoría de los usuarios no debería invocar Truth Sync manualmente cada vez.
346
+
347
+ Truth Sync es la guarda de cierre instalada para cambios de código funcional.
175
348
 
176
349
  ```text
177
350
  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
351
+ el agente ejecuta o pide pruebas relevantes
352
+ el flujo instalado detecta que cambió código funcional
353
+ Truth Sync revisa los documentos de verdad asignados
354
+ el agente actualiza documentos de verdad si hace falta
355
+ una persona revisa el diff de código + el diff de verdad
182
356
  ```
183
357
 
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`.
358
+ La invocación directa sigue siendo útil para depurar, forzar una sincronización temprana o hacer explícito el traspaso:
187
359
 
188
360
  ```text
189
- /truthmark-sync sincroniza ahora la verdad del repositorio antes de la entrega
361
+ /truthmark-sync sincroniza ahora la verdad del repositorio antes del traspaso
190
362
  ```
191
363
 
192
- ### Cambios doc-first
364
+ ## Comportamiento existente sin docs
193
365
 
194
- Usa este flujo cuando una decisión de producto o arquitectura empieza en la documentación:
366
+ Usa Truth Document cuando la implementación ya existe pero la verdad del repositorio está incompleta.
195
367
 
196
368
  ```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
369
+ /truthmark-document documenta el comportamiento implementado de timeout de sesión bajo docs/truth/authentication
203
370
  ```
204
371
 
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.
372
+ Truth Document inspecciona implementación, pruebas, archivos de rutas y documentación existente como evidencia.
373
+
374
+ Escribe solo documentos de verdad y rutas.
375
+
376
+ No debe cambiar código funcional.
377
+
378
+ ## Cambios doc-first
206
379
 
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`.
380
+ Usa Truth Realize cuando una decisión de producto o arquitectura empieza en documentos y el código debe actualizarse para coincidir.
208
381
 
209
382
  ```text
210
383
  /truthmark-realize realiza docs/truth/authentication/session-timeout.md como código
211
384
  ```
212
385
 
213
- ## Qué instala
386
+ Truth Realize es doc-first.
214
387
 
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.
388
+ Los documentos de verdad lideran. El código sigue.
216
389
 
217
- Truthmark instala dos superficies distintas:
390
+ El agente no debe editar los documentos de verdad que está realizando.
218
391
 
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
392
+ ## Preview de rutas de solo lectura
221
393
 
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
394
+ Usa Truth Preview antes de un cambio cuando el agente necesita entender la ruta probable.
229
395
 
230
- Las superficies de flujo de trabajo instaladas son el entorno de ejecución:
396
+ ```text
397
+ /truthmark-preview previsualiza la ruta de verdad probable para cambios en la API de billing
398
+ ```
399
+
400
+ Truth Preview es read-only.
231
401
 
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.
402
+ Es una ayuda de selección y planificación, no una autorización de escritura ni un reemplazo de Truth Check.
238
403
 
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.
404
+ ## Auditoría de verdad del repositorio
240
405
 
241
- Las superficies generadas son administradas por Truthmark, incluyen un marcador de versión y pueden refrescarse con `truthmark init`.
406
+ Usa Truth Check cuando quieres un flujo de auditoría orientado a agentes.
242
407
 
243
- ## Comandos
408
+ ```text
409
+ /truthmark-check audita rutas y cobertura de verdad antes de la revisión
410
+ ```
244
411
 
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:
412
+ Usa la CLI orientada a personas cuando quieres validación en terminal:
413
+
414
+ ```bash
415
+ truthmark check
416
+ ```
246
417
 
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. |
418
+ Ambas son útiles. No son la misma superficie.
252
419
 
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:
420
+ ## Comandos CLI orientados a personas
254
421
 
255
- | CLI opcional | Uso |
256
- | ------------ | --- |
422
+ La mayoría de los mantenedores empieza con tres comandos.
423
+
424
+ | Comando | Propósito |
425
+ | --- | --- |
426
+ | `truthmark config` | Crea `.truthmark/config.yml`. Solo escribe ese archivo, salvo que se use `--stdout`. |
427
+ | `truthmark init` | Instala o refresca superficies de flujo configuradas desde la config revisada. |
428
+ | `truthmark check` | Valida configuración, autoridad, rutas, documentos con decisiones, frontmatter, enlaces internos, alcance de rama, superficies generadas, frescura y diagnósticos de cobertura. |
429
+
430
+ 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.
431
+
432
+ No son fuentes de verdad.
433
+
434
+ | Comando | Propósito |
435
+ | --- | --- |
257
436
  | `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. |
437
+ | `truthmark impact --base <ref>` | Mapea archivos cambiados a documentos de verdad enrutados, rutas propietarias, pruebas cercanas y símbolos públicos. |
438
+ | `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. |
439
+
440
+ La salida estructurada está disponible con `--json` donde se admite.
441
+
442
+ ## Truthmark Portal
443
+
444
+ Truthmark Portal es un flujo opcional de presentación para equipos que quieren un sitio legible por personas sobre sus documentos de verdad confirmados.
445
+
446
+ Está separado deliberadamente del flujo central de verdad:
447
+
448
+ - Los documentos de verdad Markdown siguen siendo canónicos.
449
+ - El HTML Portal generado es solo presentación.
450
+ - Portal se ejecuta solo manualmente; no se ejecuta como puerta de finalización, paso de Truth Sync, paso de `truthmark check` ni hook automático post-change.
451
+ - Las escrituras de Portal permanecen dentro del directorio de salida configurado salvo que la persona cambie el alcance explícitamente.
452
+ - Las páginas generadas deben usar assets locales, procedencia de fuentes y un aviso visible de que Markdown es canónico.
453
+
454
+ Habilítalo con el bloque de configuración con espacio de nombres:
455
+
456
+ ```yaml
457
+ truthmark-portal:
458
+ enabled: true
459
+ output: docs/truthmark-portal
460
+ template: default
461
+ ```
462
+
463
+ Luego vuelve a ejecutar:
464
+
465
+ ```bash
466
+ truthmark init
467
+ ```
260
468
 
261
- Todos los comandos CLI anteriores admiten `--json` cuando la salida estructurada es útil para automatización.
469
+ Cuando está habilitado, Truthmark instala superficies Portal host-native para las plataformas configuradas, como `/truthmark-portal` o `/truthmark:portal` según el host de agente.
262
470
 
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.
471
+ ## Configuración
264
472
 
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:*`.
473
+ Truthmark es config-first.
266
474
 
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.
475
+ El archivo principal de configuración es:
268
476
 
269
477
  ```text
270
- /truthmark-check audita el enrutamiento y la cobertura de verdad antes de la revisión
478
+ .truthmark/config.yml
271
479
  ```
272
480
 
273
- ## Por qué existe
481
+ Los repositorios nuevos deberían ejecutar:
274
482
 
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:
483
+ ```bash
484
+ truthmark config
485
+ ```
277
486
 
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
487
+ Luego revisar la config generada antes de ejecutar:
286
488
 
287
- ## Estado del proyecto
489
+ ```bash
490
+ truthmark init
491
+ ```
492
+
493
+ Las áreas importantes de configuración incluyen:
494
+
495
+ | Área de config | Propósito |
496
+ | --- | --- |
497
+ | `version` | Versión del contrato de configuración. |
498
+ | `platforms` | Hosts de agentes que deben recibir superficies generadas específicas de plataforma. |
499
+ | `docs.layout` | Modo actual de layout de documentación. |
500
+ | `docs.roots` | Raíces nombradas de documentación canónica. |
501
+ | `docs.routing.root_index` | Ruta del índice raíz de rutas. |
502
+ | `docs.routing.area_files_root` | Directorio para archivos de rutas secundarias delegadas. |
503
+ | `docs.routing.default_area` | Nombre base de la ruta secundaria inicial generada. |
504
+ | `docs.routing.max_delegation_depth` | Profundidad máxima actual de delegación de rutas. |
505
+ | `truthmark-portal` | Ajustes opcionales del flujo manual de presentación: `enabled`, `output` y `template`. |
506
+ | `authority` | Documentos canónicos y globs ordenados usados como autoridad de verdad del repositorio. |
507
+ | `instruction_targets` | Archivos que reciben bloques de instrucciones administrados compartidos, como `AGENTS.md`. |
508
+ | `frontmatter.required` | Campos de metadatos que producen diagnósticos de error cuando faltan. |
509
+ | `frontmatter.recommended` | Campos de metadatos que producen diagnósticos de revisión cuando faltan. |
510
+ | `ignore` | Patrones glob excluidos de checks relevantes y lógica de rutas. |
511
+
512
+ ## Rutas de verdad del repositorio
513
+
514
+ Truthmark mapea superficies de código a documentos de verdad.
515
+
516
+ Los archivos principales de rutas son:
517
+
518
+ ```text
519
+ docs/truthmark/areas.md
520
+ docs/truthmark/areas/**/*.md
521
+ ```
522
+
523
+ Una ruta le dice al agente:
524
+
525
+ - qué superficie de código pertenece a un área
526
+ - qué documentos de verdad poseen esa área
527
+ - cuándo debe actualizarse la verdad
528
+ - qué tipo de documento de verdad participa
529
+
530
+ El scaffold predeterminado empieza amplio. Los repositorios existentes suelen tener que dividir la ruta predeterminada en áreas reales de propiedad.
531
+
532
+ Ejemplo:
533
+
534
+ ```text
535
+ /truthmark-structure divide el área amplia repository en frontend, backend, billing y deployment
536
+ ```
537
+
538
+ Un buen routing da a Truth Sync destinos precisos.
539
+
540
+ Un mal routing hace que los agentes adivinen.
541
+
542
+ ## Qué instala Truthmark
543
+
544
+ Truthmark instala una capa compacta de verdad nativa del repositorio.
545
+
546
+ Lo instala en cuatro capas:
547
+
548
+ - config y routing para límites de ownership
549
+ - documentos truth canónicos y plantillas iniciales
550
+ - bloques de instrucciones administrados y compactos para contexto de agente en todo el repo
551
+ - paquetes de workflow, comandos, prompts y agentes verificadores host-native para las plataformas habilitadas en la config
552
+
553
+ Truthmark conserva el contenido manual fuera de los bloques de instrucciones administrados.
554
+
555
+ Las superficies de flujo generadas son administradas por Truthmark y pueden refrescarse volviendo a ejecutar:
556
+
557
+ ```bash
558
+ truthmark init
559
+ ```
560
+
561
+ ## Subagentes y checks acotados de evidencia
562
+
563
+ Donde el host lo admite, Truthmark puede instalar agentes verificadores con alcance de proyecto y un `truth-doc-writer` con lease.
564
+
565
+ Ayudan a mantener acotadas las tareas grandes de verdad:
566
+
567
+ - route auditors inspeccionan la propiedad de rutas
568
+ - claim verifiers revisan si las afirmaciones de docs están respaldadas por evidencia
569
+ - doc reviewers inspeccionan la calidad de los documentos de verdad
570
+ - leased doc writers manejan shards acotados de escritura de documentos de verdad
571
+
572
+ 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.
573
+
574
+ Esto es importante: los subagentes ayudan con trabajo acotado de evidencia. No reemplazan el contrato principal del flujo.
575
+
576
+ ## Bucle de revisión
288
577
 
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.
578
+ Truthmark está diseñado para revisión normal en Git.
290
579
 
291
- V1 actualmente ofrece:
580
+ Un buen traspaso asistido por IA debería mostrar:
581
+
582
+ ```text
583
+ diff de código
584
+ evidencia de pruebas
585
+ diff de documentos de verdad, si hace falta
586
+ cambios de rutas, si hacen falta
587
+ informe del agente
588
+ ```
589
+
590
+ Quien revisa debería poder responder:
591
+
592
+ - ¿Qué código cambió?
593
+ - ¿Qué documentos de verdad poseen ese código?
594
+ - ¿Esos documentos necesitaron actualizaciones?
595
+ - Si no, ¿por qué no?
596
+ - ¿El agente permaneció dentro del límite de escritura del flujo?
597
+ - ¿Se incluye evidencia de pruebas o verificación?
598
+
599
+ ## Ejemplos
600
+
601
+ ### Inicializar un repositorio
602
+
603
+ ```bash
604
+ npm install -g truthmark
605
+ truthmark config
606
+ truthmark init
607
+ truthmark check
608
+ ```
609
+
610
+ ### Quitar plataformas de agentes no usadas
611
+
612
+ Edita:
613
+
614
+ ```text
615
+ .truthmark/config.yml
616
+ ```
617
+
618
+ Luego vuelve a ejecutar:
619
+
620
+ ```bash
621
+ truthmark init
622
+ truthmark check
623
+ ```
624
+
625
+ ### Dividir una ruta amplia
626
+
627
+ ```text
628
+ /truthmark-structure divide el área amplia repository en auth, billing, notifications y deployment
629
+ ```
630
+
631
+ ### Documentar comportamiento implementado
632
+
633
+ ```text
634
+ /truthmark-document documenta el flujo implementado de restablecimiento de contraseña bajo docs/truth/authentication
635
+ ```
636
+
637
+ ### Sincronizar después de cambios de código
638
+
639
+ ```text
640
+ /truthmark-sync sincroniza ahora la verdad del repositorio antes del traspaso
641
+ ```
642
+
643
+ ### Realizar una decisión doc-first
644
+
645
+ ```text
646
+ /truthmark-realize realiza docs/truth/billing/invoice-retry-policy.md como código
647
+ ```
648
+
649
+ ### Auditar la salud de verdad desde la terminal
650
+
651
+ ```bash
652
+ truthmark check
653
+ ```
654
+
655
+ ### Generar contexto de impacto de rama
656
+
657
+ ```bash
658
+ truthmark impact --base main
659
+ ```
660
+
661
+ ### Generar contexto de workflow
662
+
663
+ ```bash
664
+ truthmark context --workflow truth-sync --base main --format markdown
665
+ ```
666
+
667
+ ### Habilitar el flujo Portal opcional
668
+
669
+ ```yaml
670
+ truthmark-portal:
671
+ enabled: true
672
+ output: docs/truthmark-portal
673
+ template: default
674
+ ```
675
+
676
+ ```bash
677
+ truthmark init
678
+ ```
679
+
680
+ Luego pide explícitamente al host de agente que ejecute el flujo Portal instalado cuando quieras generar o refrescar el sitio estático de presentación.
681
+
682
+ ## Estado del proyecto
683
+
684
+ Truthmark V1 actualmente proporciona:
292
685
 
293
686
  - `truthmark config`
294
687
  - `truthmark init`
@@ -296,39 +689,124 @@ V1 actualmente ofrece:
296
689
  - `truthmark index`
297
690
  - `truthmark impact`
298
691
  - `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
692
  - 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
693
+ - bloques de instrucciones administrados
694
+ - superficies generadas de flujo Truth Structure
695
+ - superficies generadas de flujo Truth Document
696
+ - superficies generadas de flujo Truth Sync
697
+ - superficies generadas de flujo Truth Preview
698
+ - superficies generadas de flujo Truth Realize
699
+ - superficies generadas de flujo Truth Check
700
+ - superficies generadas opcionales de flujo Truthmark Portal
701
+ - diagnósticos de rutas, autoridad, estructura de decisiones, frontmatter, enlaces, frescura, superficies generadas y cobertura
702
+ - artefactos derivados RepoIndex, RouteMap, ImpactSet y ContextPack
703
+ - superficies específicas de host para Codex, Claude Code, GitHub Copilot, OpenCode y Gemini CLI
704
+
705
+ ## Desarrollo
706
+
707
+ Instalar dependencias:
708
+
709
+ ```bash
710
+ npm install
711
+ ```
712
+
713
+ Ejecutar la CLI local de desarrollo:
714
+
715
+ ```bash
716
+ npm run dev -- init
717
+ npm run dev -- check
718
+ ```
719
+
720
+ Ejecutar el check completo del proyecto:
721
+
722
+ ```bash
723
+ npm run check
724
+ ```
725
+
726
+ Scripts útiles:
727
+
728
+ | Script | Propósito |
729
+ | --- | --- |
730
+ | `npm run dev` | Ejecuta el punto de entrada CLI en TypeScript con `tsx`. |
731
+ | `npm run build` | Construye el paquete. |
732
+ | `npm run lint` | Ejecuta ESLint. |
733
+ | `npm run typecheck` | Ejecuta checks de TypeScript. |
734
+ | `npm run test` | Ejecuta las pruebas. |
735
+ | `npm run check` | Ejecuta lint, typecheck, pruebas y build. |
736
+ | `npm run release:check` | Ejecuta validación orientada a release. |
737
+
738
+ Cuando cambies Truthmark en sí, consulta [CONTRIBUTORS.md](CONTRIBUTORS.md).
304
739
 
305
740
  ## Documentación
306
741
 
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/`:
742
+ El README es el camino rápido para evaluación y configuración.
743
+
744
+ El comportamiento actual detallado vive bajo `docs/`:
308
745
 
309
746
  - [Índice de documentación](docs/README.md)
310
747
  - [Resumen de arquitectura](docs/architecture/overview.md)
311
748
  - [Contratos de API y CLI](docs/truth/contracts.md)
312
749
  - [Comportamiento de init y scaffold](docs/truth/init-and-scaffold.md)
313
750
  - [Diagnósticos de check](docs/truth/check-diagnostics.md)
314
- - [Flujos de trabajo instalados](docs/truth/workflows/overview.md)
751
+ - [Flujos instalados](docs/truth/workflows/overview.md)
315
752
  - [Guía para mantener la verdad del repositorio](docs/standards/maintaining-repository-truth.md)
316
753
 
317
- El comportamiento actual pertenece al árbol canónico de documentación anterior.
754
+ ## Límites de diseño
318
755
 
319
- ## No objetivos
756
+ Truthmark es intencionalmente pequeño.
320
757
 
321
- Truthmark V1 no es:
758
+ No es:
322
759
 
323
760
  - un servicio alojado
324
761
  - un servidor MCP
325
762
  - una base de datos vectorial
326
- - un generador de sitios de documentación
763
+ - un generador canónico de sitios de documentación o plataforma de docs alojada
327
764
  - un producto de enforcement para CI o PR
328
- - un sustituto de pruebas, revisión de código o liderazgo técnico
765
+ - un reemplazo de pruebas, revisión de código o liderazgo técnico
329
766
  - un motor autónomo de reescritura de código
767
+ - un framework de entrenamiento o fine-tuning de modelos
768
+ - una capa oculta de memoria
769
+
770
+ Esos límites son parte del producto.
771
+
772
+ Truthmark mantiene el flujo local, confirmado, acotado a la rama y revisable.
773
+
774
+ ## Seguridad y disciplina de revisión
775
+
776
+ Truthmark ayuda a que el repositorio se mantenga honesto. No prueba que el código sea correcto.
777
+
778
+ Los equipos deberían seguir:
330
779
 
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.
780
+ - ejecutando pruebas relevantes
781
+ - revisando cambios de código funcional
782
+ - revisando cambios de documentos de verdad
783
+ - manteniendo secretos fuera de la documentación
784
+ - manteniendo instrucciones específicas del repositorio fuera de bloques administrados
785
+ - revisando diffs de superficies de flujo generadas después de upgrades
786
+ - conservando propiedad humana sobre decisiones de producto y arquitectura
787
+
788
+ Truthmark hace visible el contexto del agente. No reemplaza el juicio humano.
789
+
790
+ ## Dirección de la hoja de ruta
791
+
792
+ La dirección futura actual enfatiza:
793
+
794
+ - reportes de evidencia más fuertes en `truthmark check`
795
+ - ejemplos de adopción más claros
796
+ - repositorios de ejemplo que muestren ciclos reales de Truth Sync
797
+ - guías de migración para equipos que ya usan archivos de instrucciones para agentes
798
+ - pruebas de conformidad para superficies generadas de host
799
+ - pistas de verdad obsoleta conscientes de rutas
800
+ - checklists acotadas de implementación para trabajo doc-first
801
+
802
+ El centro de gravedad se mantiene igual:
803
+
804
+ ```text
805
+ verdad del repositorio
806
+ flujos nativos para agentes
807
+ revisión en Git
808
+ contexto acotado a la rama
809
+ ```
332
810
 
333
811
  ## Licencia
334
812