---
name: vault-provenance-rules
description: Reglas universales al escribir ficheros en vault/ — frontmatter de provenance, bloques Evidence y prohibición de código fuente
metadata:
  tipo: decision
---

Cada fichero `.md` generado en `vault/` debe cumplir tres invariantes:

1. **Frontmatter de provenance**: campos `commit` (SHA corto de git al leer las fuentes, obtenido con `git rev-parse --short HEAD`) y `last_sync` (timestamp ISO 8601 UTC real, no placeholder — obtener con `date -u +%Y-%m-%dT%H:%M:%SZ`). Usar un placeholder cuesta una iteración correctiva completa (evidencia: iter-5 de task/00).

2. **Bloque `## Evidence`** al final de cada sección, citando rutas de fichero fuente sin números de línea. Criterio de aceptación universal en todos los checkpoints juez del plan.

3. **Sin código fuente**: solo intención, interfaces, estructura y entidades nombradas. Para el módulo agent, tampoco el contenido literal de los prompts. Bloques triple-backtick procedentes de `server/` o `agent/` están prohibidos.

**Pitfall conocido — cierre de config**: después de que `gv.py validate` pase, hay que actualizar explícitamente la entrada del repo en `vault/.graphvault/config.json` con `phase: "done"` y `last_sync_commit`. Omitirlo causa rechazo de juez aunque validate haya salido con exit 0 (evidencia: iter-8 de task/00).

## Cierre y validación

Toda tarea de vault debe terminar con una secuencia disciplinada de tres pasos para evitar cierre incompleto y permitir detección temprana de fricciones. Primero, ejecutar `python3 /Users/juantomas/.claude/skills/graph-vault/scripts/gv.py --vault vault validate` con verificación explícita de exit code 0; este paso confirma que todos los ficheros generados cumplen el esquema y frontmatter obligatorio, sin dejar errores silenciosos. Segundo, una vez `validate` pase, actualizar de forma **inmediata** la entrada correspondiente en `vault/.graphvault/config.json` con dos campos: `phase: "done"` y `last_sync_commit` con el SHA corto del commit actual (`git rev-parse --short HEAD`). Este cierre de config es un **invariante crítico** que marcan los jueces de todas las subtareas de cierre ([juez] en líneas 63-70 de task/01.md): sin él, el juez rechazará aunque validate haya salido con exit 0, forzando una iteración correctiva completa.

Tercero, invocar `/maestro review` para que revise el trabajo completado de la tarea y almacene decisiones y fricciones observadas como skills locales. Esto permite que futuras iteraciones de vault aprendan del trabajo anterior sin repetir errores; es especialmente crítico en tareas de vault donde la fricciones acumuladas (orden de secciones, frontmatter incompleto, cierre de config olvidado) tienden a repetirse. El patrón está anclado en plan.md línea 18 (parar tras completar una acción única) y en task/01.md líneas 71 donde la subtarea final es explícitamente `[ ] Invocar la acción review de maestro`: su presencia como subtarea hojas (sin [x] hasta el final) hace que cierre incompleto sea detectable incluso sin leer todos los ficheros de validación.

## Evidence

- `plan/plan.md` (línea 18: "Parar. No busques la siguiente subtarea")
- `plan/task/01.md` (líneas 61–71: secuencia de tres pasos — validate, config.json, maestro review)