fn_registry/dev/issues/0114-dod-evidence-schema.md

id, title, status, type, domain, scope, priority, depends, blocks, related, created, updated, tags, flow

id	title	status	type	domain	scope	priority	depends	blocks	related	created	updated	tags	flow
0114	DoD evidence schema canonico: frontmatter + BD + validator	pendiente	feature	taxonomy dev-loop registry-quality	registry	alta		0115 0117	0008 0100 0102	2026-05-18	2026-05-18	dod evidence frontmatter taxonomy validator	0008

0114 — DoD evidence schema canonico

Problema

Hoy ## Definition of Done es una lista markdown libre. dod_user: existe en frontmatter (issue 0102) como ratio. Falta una forma estructurada de declarar QUE evidencia tiene que aportar el agente por cada item DoD (screenshot, log, url, output cmd).

Sin schema, el agente no sabe que adjuntar y el validador no puede checkear automaticamente.

Decision

Anadir bloque dod_evidence_schema: al frontmatter de issues y flows. Lista de items con shape canonico:

dod_evidence_schema:
  - id: surface_1_board_drag
    kind: screenshot
    expected: "kanban_cpp.exe board con card en columna Doing (agent), barra progreso visible"
    required: true
  - id: backend_health
    kind: cmd
    expected: "curl -fsS http://localhost:8403/api/health == 200"
    required: true
  - id: timeline_entry
    kind: url
    expected: "http://localhost:8486/api/runs?app=kanban_cpp devuelve >=1 run"
    required: false
  - id: agent_log
    kind: log
    expected: "agent_runs/<run_id>/agent.log contiene 'workflow done'"
    required: true

Kinds

kind	Que adjunta el agente	Como valida
screenshot	path PNG en agent_runs/<run_id>/evidence/<item_id>.png	check existe + tamaño > 0 + dimensions sensatas
log	path file (txt/log)	check existe + grep pattern de expected (opcional)
url	URL string	HEAD request (2xx/3xx) o GET + match pattern
cmd	comando + stdout esperado	exec + compare exit code + grep stdout

Persistencia

Frontmatter declara el SCHEMA (lo que se espera). agent_runner_api (0113) crea un row en dod_items por cada entrada al iniciar run. Agente luego adjunta dod_evidence rows.

Validator: audit_dod_schema_go_infra

Funcion Go nueva en functions/infra/. Lee .md de dev/issues/ + dev/flows/, parsea frontmatter, valida:

• id unico por archivo.
• kind in [screenshot, log, url, cmd].
• expected no vacio.
• required bool (default true).

Output: tabla caveman con drift / errores.

Wrapper CLI: fn doctor dod.

Criterios de aceptacion

• Plantilla docs/templates/issue.md + docs/templates/flow.md actualizadas con bloque opcional dod_evidence_schema: y ejemplo.
• audit_dod_schema_go_infra registrado (functions/infra/audit_dod_schema.{go,md}).
• fn doctor dod muestra: items por archivo + drift + errores.
• Indexer (registry/parser.go) lee dod_evidence_schema: y lo persiste si afecta a la tabla issues/flows (en apps/issues_api/).
• Migracion apps/agent_runner_api/migrations/004_dod_items.sql referencia este schema (issue 0113).
• Doc en dev/issues/README.md + dev/flows/README.md: cuando declarar evidence schema, ejemplos por kind.
• Al menos 2 issues piloto con bloque rellenado (recomendado: 0112 + 0116).
• Tests Go: audit_dod_schema_test.go cubre kinds validos/invalidos + frontmatter malformed.

Gotchas

• dod_user: (0102) es METRICA (ratio). dod_evidence_schema: es DECLARACION. NO renombrar ni fusionar — son cosas distintas.
• Frontmatter YAML con array de objects: parser actual debe soportarlo. Verificar con registry/parser.go antes.
• Schema retroactivo: issues viejos sin bloque siguen validos (dod_evidence_schema: [] o ausente -> sin validacion automatica).
• cmd con secretos/credenciales: NUNCA en el expected. Si el comando los necesita, env var.

Out of scope

• UI para editar schema (eso vive en kanban_cpp/skill_tree v2).
• Validacion en CI / pre-commit (futuro: hook que rechaza issue sin schema si type=feature).
• Schema versioning — por ahora v1 implicito.