docs: cerrar issue 0114

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-18 18:13:14 +02:00
parent 581d0f0a0e
commit df1eb701d3
1 changed files with 106 additions and 0 deletions
@@ -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/<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.