vault-provenance-rules

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)