META-01: Especificación de metadata documental

Contrato del nodo atómico y del parser de frontmatter YAML para Gate 0. Implementación objetivo: :docugraph-core (portable; sin UI). No duplica glosario narrativo: términos en GLOSSARY-01.

1. Alcance Gate 0

In scope

Bloque YAML entre --- al inicio del archivo Markdown.
Campos obligatorios/opcionales listados abajo.
Construcción de grafo dirigido por links.depends_on.
Errores de parseo y de integridad referencial reportables por validate_traceability.
Determinismo del modelo en memoria (mismo workspace → mismo grafo).

Out of scope

Persistencia PostgreSQL (SCHEMA-01).
Entitlements / maxDepth freemium (catálogo producto).
Edición UI de metadata.
Inferencia automática de enlaces no declarados.

2. Ubicación y descubrimiento

Regla	Detalle
Extensiones	`.md` (UTF-8)
Raíz	`workspacePath` configurado al arrancar el servidor MCP
Inclusión	Archivos bajo la raíz, excluyendo directorios configurables (default sugerido: `.git`, `build`, `node_modules`, `.gradle`)
Un ID por workspace	El campo `id` debe ser único; colisión = error de validación

3. Schema de frontmatter

3.1 Campos

Campo	Tipo	Obligatorio	Descripción
`id`	string	sí	Identificador atómico estable (p. ej. `BE-02`, `US-01`, `MASTER-00`)
`title`	string	sí	Título legible
`type`	string	sí	Tipo documental libre controlado por convención del repo
`status`	string	recomendado	Estado del artefacto (p. ej. `APROBADA`, `EN_PRUEBA`)
`phase`	string	opcional	`GATE_0` \| `POC` \| `MVP` \| `POST_MVP` \| … (gobernanza producto)
`version`	string/number	opcional	Versión del documento
`tags`	string[]	opcional	Etiquetas
`links`	object	recomendado	Relaciones (ver §3.2)

Campos adicionales se conservan en un mapa extensions o se ignoran sin fallar el parseo (política Gate 0: no fallar por claves desconocidas; sí fallar por YAML inválido o falta de id/title/type).

3.2 `links`

links:
  depends_on: [ID-A, ID-B]    # upstream: este nodo depende de…
  depended_by: [ID-C]         # downstream declarativo (informativo)
  related: [ID-D]             # no implica orden de bundle obligatorio
  tables: [users]             # opcional; citas de schema (catálogo)

Relación	Dirige el Graph Resolver (Gate 0)	Incluir en bundle por defecto
`depends_on`	sí (aristas u→upstream)	sí, vía recorrido desde `taskId`
`depended_by`	no para recorrido upstream; usable en auditoría de simetría	no automáticamente
`related`	no	no (salvo política futura)
`tables`	no como nodos MD	fuera de Gate 0 bundle mínimo

3.3 Ejemplo mínimo válido

---
id: BE-02
title: "Demo task: create resource"
type: backend_task
status: DRAFT
tags: [demo, gate-0]
links:
  depends_on: [US-DEMO-01]
  depended_by: []
  related: []
---

4. Modelo de nodo en runtime

DocNode
  id: String
  title: String
  type: String
  status: String?
  phase: String?
  tags: List<String>
  links: LinkBlock
  path: String          # relativo al workspace
  bodyMarkdown: String  # contenido tras el frontmatter

LinkBlock
  dependsOn: List<String>
  dependedBy: List<String>
  related: List<String>

5. Reglas del grafo (DAG)

Arista de dependencia para resolución de contexto: from = node.id → to ∈ node.links.depends_on.
El grafo usado por get_task_context es el de depends_on.
Ciclos: cualquier SCC de tamaño > 1 o self-loop es error de validate_traceability (Tarjan o equivalente).
Link roto: ID en depends_on / depended_by / related sin nodo con ese id → error (o warning configurable; Gate 0: error para depends_on, warning para related).
Simetría depended_by: si A lista B en depended_by pero B no lista A en depends_on, warning (no bloquea bundle).
Agentes que editen docs del monorepo deben mantener bidireccionalidad (AGENTS Rule 3); el validador lo audita.

6. Errores de metadata (catálogo Gate 0)

Código	Severidad	Condición
`FM_MISSING`	error	Archivo `.md` sin frontmatter
`FM_YAML_INVALID`	error	YAML no parseable
`FM_FIELD_MISSING`	error	Falta `id`, `title` o `type`
`FM_ID_DUPLICATE`	error	Dos archivos con el mismo `id`
`LINK_BROKEN_DEPENDS`	error	`depends_on` apunta a ID inexistente
`LINK_BROKEN_RELATED`	warning	`related` / `depended_by` roto
`LINK_CYCLE`	error	Ciclo en grafo `depends_on`
`LINK_ASYMMETRY`	warning	`depended_by` sin espejo en `depends_on`

El informe JSON de validación agrupa errors[] y warnings[] con code, message, path?, nodeId?, detail?.

7. Bundle y justificación (contrato de datos)

Salida lógica de resolución (consumida por MCP-G0):

ContextBundle
  taskId: String
  maxDepth: Int
  nodes: List<BundleNode>   # orden estable
  truncated: Boolean        # si se cortó por maxDepth

BundleNode
  id: String
  path: String
  title: String
  depth: Int                # distancia desde taskId (0 = tarea)
  inclusionReason: String   # p. ej. "root" | "depends_on from BE-02 via US-DEMO-01"
  markdown: String          # frontmatter + body o body según política; Gate 0: archivo completo

Determinismo

Mismo snapshot de archivos → mismo conjunto de IDs.
Orden de nodes: orden topológico reverse-postorder; empates por id lexicográfico ascendente.
Recorrido: BFS o DFS documentado en código; debe respetar maxDepth (default 5).
No incluir nodos solo por related.

8. Parser YAML (DEC-003)

Implementar parser de frontmatter nativo/liviano en :docugraph-core.
No adoptar kaml (archivada; Rule 5 / DEC-003).
Subconjunto YAML suficiente: mappings, scalars, listas de scalars. No se exige YAML 1.2 completo en Gate 0.

9. Trazabilidad

Gobierna implementación del loader/parser/grafo.
Consumido por MCP-G0 y GATE-0 (research/GATE_0_SPEC.md).
Alineado con Rule 2–3 de AGENTS.md.