# Objective Guard — documentación canónica

Objective Guard es un runtime de verificación continua para agentes de programación. Su función es detectar lo antes posible cambios incorrectos, desviaciones del objetivo y expansión de scope que todavía no tiene evidencia proporcional.

¿Recién llegás? Empezá con [getting-started.es.md](getting-started.es.md). ¿Lo estás corriendo dentro de un harness de agentes? Mirá [guides/README.es.md](guides/README.es.md).

## Capas

Este directorio separa deliberadamente seis clases de documentos, cada una con su propia autoridad:

| Capa | Propósito | Autoridad |
| --- | --- | --- |
| [Primeros pasos](getting-started.es.md) | Lleva a quien recién llega desde un repositorio sin modificar hasta una primera ronda cerrada. | Operacional; debe coincidir con la CLI. |
| [Guías](guides/README.es.md) | Integración por harness (Claude Code, Codex, y futuros harnesses). | Operacional; debe coincidir con los hooks instalados. |
| [Producto](product/01-vision-and-thesis.es.md) | Define qué se construirá, por qué, cómo decide y en qué orden. | Canónica para implementación. |
| [Funcionalidad](functionality/INDEX.es.md) | Traduce el producto a actores, capacidades, reglas y casos verificables. | Canónica para aceptación funcional. |
| [Episodios y hallazgos](episodes/README.es.md) | Conserva señales orgánicas, fallos de razonamiento y correcciones de dirección. | Evidencia narrativa append-only; informa producto e investigación. |
| [Investigación inicial](initial-research/README.es.md) | Conserva hipótesis, PRDs anteriores y revisiones adversarias. | Histórica; explica decisiones, no gobierna el producto actual. |

## Orden de lectura recomendado

1. [Primeros pasos](getting-started.es.md)
2. [Visión y tesis](product/01-vision-and-thesis.es.md)
3. [Contrato de producto](product/02-product-contract.es.md)
4. [Modelo de señales y decisión](product/03-signal-and-decision-model.es.md)
5. [Arquitectura técnica](product/04-technical-architecture.es.md)
6. [Validación científica](product/05-scientific-validation.es.md)
7. [Roadmap y criterios](product/06-roadmap-and-criteria.es.md)
8. [Protocolo de calibración de Fase 1](product/07-phase-1-calibration-protocol.es.md)
9. [PRD de ciclo de vida de rondas y trabajo activo](product/08-round-lifecycle-and-active-work-prd.es.md)
10. [Episodios y hallazgos](episodes/README.es.md)
11. [Mapa funcional](functionality/INDEX.es.md)
12. [Coordinación de AWC instalado](product/10-awc-installed-coordination.es.md)

## Política de idioma

El inglés es el idioma canónico de la documentación. Todo documento canónico tiene, al lado, una contraparte en español que comparte el mismo slug con extensión `.es.md`:

```
docs/product/02-product-contract.md      <- canonical (English)
docs/product/02-product-contract.es.md   <- alternative (Spanish)
```

Reglas:

1. El archivo en inglés es la fuente de verdad. Cuando el contenido cambia, actualizá el archivo en inglés y su contraparte en español **en el mismo changeset** — una contraparte desactualizada es un bug, no una demora de traducción.
2. Ambos archivos mantienen el mismo prefijo numérico, slug y directorio. Los documentos nuevos agregan ambos archivos a la vez.
3. Los archivos en inglés enlazan a archivos en inglés; los archivos en español enlazan a archivos en español. Las citas a paths de código (`src/…`, `test/…`) son idénticas en ambos.
4. Los marcadores de confianza se localizan: `[Fact]` / `[Inference]` / `[Ambiguity]` en inglés, `[Hecho]` / `[Inferencia]` / `[Ambigüedad]` en español.
5. El texto de superficie de producto — salida de CLI, comentarios de código, diagnósticos orientados al agente — es sólo en inglés y no tiene contraparte.

El guard de documentación exige el pairing y la estructura de forma mecánica: una contraparte faltante, un documento en español huérfano o un enlace que cruza idiomas hacen fallar el build en lugar de desviarse en silencio.

**No** exige frescura: dos documentos emparejados pueden seguir divergiendo en contenido y hoy ningún check lo detecta. Por eso la regla 1 sigue siendo una disciplina, no un control. El razonamiento de este diseño —y la deriva que lo motivó— quedan registrados en [E-032](episodes/E-032-generated-mirrors-drifted-without-a-guard.es.md).

## Regla de precedencia

Si un documento histórico contradice la documentación de `docs/product/`, prevalece la documentación de producto. Si una afirmación estadística contradice un hecho determinista observado por una herramienta reproducible, ambos se reportan por separado: la estadística no invalida el hecho y el hecho aislado no valida una teoría general.

## Dogfooding documental

```bash
node scripts/validate-docs.mjs
```

El guard verifica las capas requeridas, los contratos estructurales, las capacidades funcionales, la matriz de tests, el pairing inglés/español, la estructura de las guías y los enlaces relativos. No demuestra que la tesis sea verdadera ni que el producto futuro sea correcto; demuestra que el entregable documental satisface un contrato explícito y reproducible.