vault-components-strategy

name	vault-components-strategy
description	Estrategia para promover componentes compartidos en vault/components/ — cuándo emitir un fichero vs. anotar en pending-components.md
metadata	{"tipo":"decision"}

Regla

Solo se promueve un componente bajo vault/components/<name>.md cuando existen ≥2 consumidores evidenciados (distintos del owner) mediante código observable (import directo, uso en test, invocación de API). Si solo se evidencia 1 consumidor, o la dependencia se sospecha pero no se constata en código, se anota en vault/meta/pending-components.md y no se crea fichero de componente.

Por qué

gv.py validate verifica que los wikilinks de consumidores resuelvan a módulos registrados en vault/.graphvault/config.json. Un componente con un solo consumidor o con consumidores inventados produce wikilinks rotos o falla la validación. La regla ≥2 garantiza que el grafo refleje reutilización real y mantiene validate en exit 0.

Cómo aplicar

• Evidencia suficiente: from server.game_data import, import game_data en tests y en scripts → 2 consumidores → promover.
• Evidencia insuficiente: "server.common.py probablemente usada por tests dado su nombre" → 1 consumidor confirmado → pending.
• Frontmatter obligatorio: type: component, owner_repo no vacío, consumidores como wikilinks [[nombre-modulo]] en sección Consumers.
• Ruta de pending: vault/meta/pending-components.md (requiere frontmatter type: meta).
• No copiar código fuente: documentar solo la superficie pública y la intención.

Evidencia de origen

Tarea 07 (plan/task/07.md): server.common, server.config y server.main descartados con 1 único consumidor evidenciado; game_data, logic y map_utils promovidos con ≥2 wikilinks distintos del owner. Validado con gv.py validate exit 0.