---
id: "0114"
title: "DoD evidence schema canonico: frontmatter + BD + validator"
status: pendiente
type: feature
domain:
  - taxonomy
  - dev-loop
  - registry-quality
scope: registry
priority: alta
depends: []
blocks:
  - "0115"
  - "0117"
related:
  - "0008"
  - "0100"
  - "0102"
created: 2026-05-18
updated: 2026-05-18
tags: [dod, evidence, frontmatter, taxonomy, validator]
flow: "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:

```yaml
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.