docs: cerrar issue 0114
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -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.
|
||||||
Reference in New Issue
Block a user