diff --git a/dev/issues/completed/0114-dod-evidence-schema.md b/dev/issues/completed/0114-dod-evidence-schema.md new file mode 100644 index 00000000..2b588cd8 --- /dev/null +++ b/dev/issues/completed/0114-dod-evidence-schema.md @@ -0,0 +1,106 @@ +--- +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//agent.log contiene 'workflow done'" + required: true +``` + +### Kinds + +| `kind` | Que adjunta el agente | Como valida | +|---|---|---| +| `screenshot` | path PNG en `agent_runs//evidence/.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.