egutierrez
b9716a7cd6
Snapshot de WIP acumulado de sesiones previas antes de merge wave 1 del flow 0008 (kanban_cpp + agent_runner_api + DoD schema). Incluye: - dev/flows/0008-kanban-cpp-and-agent-workflows.md - dev/issues/0112-0119*.md (7 sub-issues) - WIP previo en cmd/fn/doctor.go, registry/*, modules/, cpp/, etc. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
107 lines
4.0 KiB
Markdown
107 lines
4.0 KiB
Markdown
---
|
|
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.
|