# Frontmatter Minimal — 4-Field Standard

Protocollo frontmatter validato su 45 file riscritti. **Solo 4 campi obbligatori**; tutto il resto è derivabile da git / tooling.

## Standard template

```yaml
---
doc_type: reference
domain: booking
canonicality: canonical-source
last_updated: 2026-04-05
---
```

## Campi obbligatori (4)

| Campo | Valori ammessi | Esempi |
|-------|----------------|--------|
| `doc_type` | `reference`, `adr`, `prd`, `guide`, `spec`, `runbook`, `index` | `reference` |
| `domain` | dominio funzionale (snake-case) | `booking`, `menu`, `dio`, `customer`, `admin` |
| `canonicality` | `canonical-source`, `derived`, `index`, `deprecated` | `canonical-source` |
| `last_updated` | ISO date YYYY-MM-DD | `2026-04-05` |

## Campi OPZIONALI (solo se servono)

| Campo | Quando usare |
|-------|--------------|
| `status` | Solo per PRD: `draft`, `in_progress`, `approved`, `done` |
| `related_code_paths` | Solo se drift-detection hook lo richiede |
| `last_verified_from_code` | Solo se c'è automated verification |

## Campi DA RIMUOVERE (dal legacy frontmatter)

Questi erano presenti nei file pre-compressione ma **NON servono**:

| Campo | Perché rimuovere |
|-------|------------------|
| `owner` | Derivabile da git blame |
| `audit_notes` | Drift tracking dinamico → git commits |
| `freshness_status` | Calcolabile da last_updated vs oggi |
| `stale_since` | Legacy drift marker, dinamico |
| `stale_triggered_by` | Legacy drift marker, dinamico |
| `stale_reason` | Legacy drift marker, dinamico |
| `diataxis_type` | Derivabile da doc_type |
| `hub_role` | Legacy, non usato da tooling attivo |
| `verification_scope` | Legacy |

## Esempi per doc_type

### Reference doc (API, UI, data-model)
```yaml
---
doc_type: reference
domain: booking
canonicality: canonical-source
last_updated: 2026-04-05
---
```

### PRD
```yaml
---
doc_type: prd
domain: booking
canonicality: canonical-source
status: in_progress
last_updated: 2026-04-05
---
```

### ADR
```yaml
---
doc_type: adr
domain: booking
canonicality: canonical-source
last_updated: 2026-04-05
---
```

### Index/registry
```yaml
---
doc_type: index
domain: platform
canonicality: index
last_updated: 2026-04-05
---
```

## Perché 4 campi e basta

**Signal/noise**: ogni campo frontmatter costa token al reindex LLM. Un frontmatter da 17 linee su 200 linee di doc = **8.5% overhead**. Con 4 linee → **2%**.

**Derivabilità**: `owner`, `last_verified_*`, `stale_*` sono **dinamici**. Salvati nel file diventano immediatamente stale. Meglio calcolarli on-demand da git.

**Chiarezza**: un frontmatter breve è facilmente leggibile. Quello lungo nasconde le info importanti.

## Se devo aggiungere nuovi campi

**STOP** e chiediti:
1. È davvero canonico o è derivabile?
2. Verrà mai aggiornato manualmente?
3. Serve a un tool esistente (quale?)?

Se le risposte sono "derivabile" o "no" → **non aggiungerlo**.

Se serve davvero a un tool:
- Documenta il tool nel frontmatter-guide
- Aggiungi il campo solo ai file che quel tool scansiona
- Non propagarlo a tutti i file
