# Objective Guard — canonical documentation

Objective Guard is a continuous-verification runtime for coding agents. Its job is to detect incorrect changes, objective drift and scope expansion that does not yet have proportional evidence, as early as possible.

New here? Start with [getting-started.md](getting-started.md). Running it inside an agent harness? See [guides/README.md](guides/README.md).

## Layers

This directory deliberately separates six classes of document, each with its own authority:

| Layer | Purpose | Authority |
| --- | --- | --- |
| [Getting started](getting-started.md) | Takes a newcomer from an unmodified repository to a first closed round. | Operational; must match the CLI. |
| [Guides](guides/README.md) | Per-harness integration (Claude Code, Codex, and future harnesses). | Operational; must match the installed hooks. |
| [Product](product/01-vision-and-thesis.md) | Defines what will be built, why, how it decides, and in what order. | Canonical for implementation. |
| [Functionality](functionality/INDEX.md) | Translates the product into actors, capabilities, rules and verifiable cases. | Canonical for functional acceptance. |
| [Episodes and findings](episodes/README.md) | Preserves organic signals, reasoning failures and corrections of direction. | Append-only narrative evidence; informs product and research. |
| [Initial research](initial-research/README.md) | Preserves hypotheses, earlier PRDs and adversarial reviews. | Historical; explains decisions, does not govern the current product. |

## Recommended reading order

1. [Getting started](getting-started.md)
2. [Vision and thesis](product/01-vision-and-thesis.md)
3. [Product contract](product/02-product-contract.md)
4. [Signal and decision model](product/03-signal-and-decision-model.md)
5. [Technical architecture](product/04-technical-architecture.md)
6. [Scientific validation](product/05-scientific-validation.md)
7. [Roadmap and criteria](product/06-roadmap-and-criteria.md)
8. [Phase 1 calibration protocol](product/07-phase-1-calibration-protocol.md)
9. [Round lifecycle and active work PRD](product/08-round-lifecycle-and-active-work-prd.md)
10. [Episodes and findings](episodes/README.md)
11. [Functional map](functionality/INDEX.md)
12. [Installed AWC coordination](product/10-awc-installed-coordination.md)

## Language policy

English is the canonical documentation language. Every canonical document has a Spanish counterpart beside it, sharing the same slug with an `.es.md` extension:

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

Rules:

1. The English file is the source of truth. When content changes, update the English file and its Spanish counterpart **in the same changeset** — a stale counterpart is a bug, not a translation delay.
2. Both files keep the same numeric prefix, slug and directory. New documents add both files at once.
3. English files link to English files; Spanish files link to Spanish files. Citations to code paths (`src/…`, `test/…`) are identical in both.
4. Confidence markers are localized: `[Fact]` / `[Inference]` / `[Ambiguity]` in English, `[Hecho]` / `[Inferencia]` / `[Ambigüedad]` in Spanish.
5. Product-surface text — CLI output, code comments, agent-facing diagnostics — is English only and has no counterpart.

The documentation guard enforces pairing and structure mechanically, so a missing counterpart, an orphan Spanish document or a link that crosses language fails the build rather than drifting silently.

It does **not** enforce freshness: two paired documents can still diverge in content, and no check currently catches that. Rule 1 is therefore still a discipline, not a control. The reasoning behind this design — and the drift that motivated it — is recorded in [E-032](episodes/E-032-generated-mirrors-drifted-without-a-guard.md).

## Precedence rule

If a historical document contradicts the documentation under `docs/product/`, the product documentation prevails. If a statistical claim contradicts a deterministic fact observed by a reproducible tool, both are reported separately: the statistic does not invalidate the fact, and an isolated fact does not validate a general theory.

## Documentation dogfooding

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

The guard checks required layers, structural contracts, functional capabilities, the test matrix, English/Spanish pairing, guide structure and relative links. It does not prove the thesis is true or that the future product is correct; it proves the documentation deliverable satisfies an explicit, reproducible contract.