docs: dod_evidence_schema templates + READMEs (issue 0114)

- docs/templates/issue.md and docs/templates/flow.md include the optional dod_evidence_schema: block with realistic example items. - dev/issues/README.md and dev/flows/README.md document the schema, kinds by example, validation rules and the fn doctor dod entrypoint. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-18 18:13:02 +02:00
parent c5587842b9
commit 581d0f0a0e
4 changed files with 235 additions and 0 deletions
@@ -56,6 +56,48 @@ Regla: si la respuesta a "donde lo ves" es "en una BD" o "en un log" -> NO vale.

 `/flow done` rechaza el cierre si falta alguno de los 4 user-facing checks o si `## Notas` no contiene parrafo onboarding.

+### DoD evidence schema (issue 0114, opcional)
+
+Ademas de los checkboxes humanos del bloque `## Definition of Done`, cada flow puede declarar en su frontmatter un bloque `dod_evidence_schema:` con la version maquinable de la DoD: lista de evidencias con id unico, `kind` cerrado, `expected` libre y `required` bool. Auditable con `fn doctor dod`.
+
+```yaml
+dod_evidence_schema:
+  - id: surface_dashboard
+    kind: url
+    expected: "https://metabase.organic-machine.com/dashboard/12 muestra ultimo refresh hoy"
+    required: true
+  - id: matrix_room_msg
+    kind: screenshot
+    expected: "sala matrix #flows recibe mensaje con resumen del run"
+    required: true
+  - id: data_factory_run
+    kind: cmd
+    expected: "sqlite3 data_factory.db 'SELECT count(*) FROM runs WHERE flow=NNNN' > 0"
+    required: true
+  - id: error_path_log
+    kind: log
+    expected: "fallar collector intencional deja entry status=error sin crash"
+    required: false
+```
+
+Reglas:
+- `kind` ∈ {`screenshot`, `log`, `url`, `cmd`}.
+- `id` unico por flow.
+- `expected` no vacio.
+- `required` default `true`.
+
+Ejemplos por kind:
+
+| kind | que pones en `expected` |
+|---|---|
+| `screenshot` | "frame de la app/sala mostrando estado Y" |
+| `log` | "fichero <path> contiene linea con texto Z" |
+| `url` | "GET <url> devuelve 200 con campo W" o "dashboard tal carga ultima fila < 24h" |
+| `cmd` | comando shell con exit 0 (incluido SQL via sqlite3) |
+
+Plantilla canonica: `docs/templates/flow.md`. Validador: `fn doctor dod` + `audit_dod_schema_go_infra`.
+
+
 ## Para agentes / LLMs

 Antes de crear o editar un flow, lee `AGENT_GUIDE.md`. Define:
@@ -2,6 +2,48 @@

 > **Frontmatter YAML** es la fuente de verdad desde 2026-05-17 (issue 0100).
 > Cada `.md` empieza con bloque `---` con `id`, `title`, `status`, `type`, `domain`, `scope`, `priority`, `depends`, `blocks`, `related`, `created`, `updated`, `tags`.
+
+## DoD evidence schema (issue 0114, opcional)
+
+Cualquier issue puede declarar en su frontmatter un bloque `dod_evidence_schema:` que enumera **evidencias concretas** capturables al cerrar. Es la version maquinable del bloque humano `## Definition of Done`: lista de items con id unico, `kind` cerrado, `expected` libre y `required` bool. Auditable con `fn doctor dod` (sale humana y `--json`).
+
+```yaml
+dod_evidence_schema:
+  - id: surface_1_board_drag
+    kind: screenshot
+    expected: "kanban_cpp board con card en columna Doing (agent)"
+    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
+```
+
+Reglas:
+- `kind` ∈ {`screenshot`, `log`, `url`, `cmd`}. Otro valor rechaza el item.
+- `id` unico por issue (los duplicados se reportan).
+- `expected` no vacio (descripcion observable de la evidencia).
+- `required` bool (default `true` si se omite).
+
+Ejemplos por kind:
+
+| kind | que pones en `expected` |
+|---|---|
+| `screenshot` | "frame de la UI X mostrando estado Y" — capturable manual o por test visual |
+| `log` | "fichero <path> contiene linea con texto Z" — grep-eable |
+| `url` | "GET <url> devuelve 200 y body con campo W" — curl-eable |
+| `cmd` | comando que debe terminar con exit 0 (o assert explicito) |
+
+Plantilla canonica: `docs/templates/issue.md`. Validador: `fn doctor dod` + `audit_dod_schema_go_infra`.
+
 > Para listar/filtrar: `/issue list --domain trading --status pendiente` (cuando `dev_console` exista — issue 0101).
 >
 > Dominios canonicos: `meta cpp-stack kanban trading gamedev osint data-ingest registry-quality notify imagegen apps-infra dev-ux deploy frontend mcp browser telemetry docs`.
@@ -0,0 +1,73 @@
+---
+name: <slug-del-flow>
+id: NNNN
+status: pending                # pending | running | done | failed | deferred
+created: 2026-05-18
+updated: 2026-05-18
+priority: high                 # low | medium | high
+risk: low                      # low | medium | high (sensibilidad de datos)
+related_issues: []
+apps: []
+trigger: manual                # manual | cron | webhook
+schedule: ""
+expected_runtime_s: 60
+tags: []
+
+# OPCIONAL (issue 0114): contrato de evidencia DoD canonico.
+# Cada item es una superficie/check observable que prueba que el flow funciono.
+dod_evidence_schema:
+  - id: surface_dashboard
+    kind: url
+    expected: "https://metabase.organic-machine.com/dashboard/12 muestra ultimo refresh hoy"
+    required: true
+  - id: matrix_room_msg
+    kind: screenshot
+    expected: "sala matrix #flows recibe mensaje con resumen del run"
+    required: true
+  - id: data_factory_run
+    kind: cmd
+    expected: "sqlite3 data_factory.db 'SELECT count(*) FROM runs WHERE flow=NNNN AND created_at > date(now,-1 day)' > 0"
+    required: true
+  - id: error_path_log
+    kind: log
+    expected: "fallar collector intencional deja entry status=error en operations.db sin crash"
+    required: false
+---
+
+## Goal
+Una frase: que estamos probando.
+
+## Pre-requisitos
+- Lista de requisitos manuales (ej. Chrome con remote-debugging).
+
+## Flow
+Pasos numerados. Cada paso puede ser:
+- texto libre (manual)
+- `function: <id>` (registry function)
+- `cmd: <bash>`
+- `js: <expression>` (en tab Chrome)
+
+## Acceptance
+- [ ] Checklist
+- [ ] ...
+
+## Definition of Done
+
+- [ ] **Repetibilidad**: corre N veces consecutivas sin intervencion manual.
+- [ ] **Observabilidad**: call_monitor.calls + data_factory.runs + dashboard.
+- [ ] **Error-path**: 1 modo de fallo probado y manejado (no crash silencioso).
+- [ ] **Idempotencia**: re-ejecutar no duplica datos.
+- [ ] **Secrets**: cero credenciales fuera de pass/vaults.
+- [ ] **Docs**: `## Notas` rellenado con hallazgos reales.
+- [ ] **Registry-first**: todas las piezas existen como funciones del registry.
+- [ ] **INDEX + status**: status=done + fila INDEX.md + movido a completed/.
+- [ ] **User-facing**: <accion + lugar exacto>.
+- [ ] **User-facing repeat**: humano vuelve manana y ve datos frescos.
+- [ ] **User-facing onboarding**: parrafo en `## Notas` explica "para ver/usar esto: hacer X".
+- [ ] **User-facing latencia**: humano percibe cambio en <X segundos|minutos>.
+
+## Telemetria esperada
+Que cambia en call_monitor / data_factory.runs / dag_engine.
+
+## Notas
+Hallazgos tras correr. Incluye el parrafo onboarding.
@@ -0,0 +1,78 @@
+---
+id: "NNNN"
+title: "<titulo corto del issue>"
+status: pendiente              # pendiente | in-progress | bloqueado | completado | descartado
+type: feature                  # feature | bugfix | refactor | docs | chore | research | infra
+domain:
+  - <dominio>                  # ver dev/TAXONOMY.md (meta, cpp-stack, kanban, trading, ...)
+scope: registry-only           # registry-only | app:<id> | flow:<NNNN>
+priority: media                # critica | alta | media | baja
+depends: []                    # ["0099", ...] (IDs de issues bloqueantes)
+blocks: []                     # ["0120", ...] (IDs que este issue desbloquea)
+related: []
+created: 2026-05-18
+updated: 2026-05-18
+tags: []
+
+# OPCIONAL (issue 0114): contrato de evidencia DoD canonico.
+# Cada item es una prueba concreta que debe quedar capturada al cerrar el issue.
+# kind in {screenshot, log, url, cmd}. expected NO vacio. id unico.
+dod_evidence_schema:
+  - id: surface_1_board_drag
+    kind: screenshot
+    expected: "kanban_cpp board con card en columna Doing (agent)"
+    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
+---
+# NNNN — <titulo corto del issue>
+
+**Status:** pendiente
+**Created:** 2026-05-18
+**Type:** feature
+**Priority:** media
+**Domain:** <dominio>
+**Scope:** registry-only
+**Depends:** —
+**Blocks:** —
+
+## Problema
+
+<que esta fallando o que falta y por que importa>
+
+## Objetivo
+
+<criterio observable de cuando el issue esta hecho>
+
+## Plan
+
+1. ...
+2. ...
+
+## Acceptance
+
+- [ ] check 1
+- [ ] check 2
+
+## Definition of Done
+
+- [ ] **Repetibilidad**: pasa N veces consecutivas sin intervencion manual.
+- [ ] **Observabilidad**: queda trazado en call_monitor + dashboard correspondiente.
+- [ ] **User-facing**: <accion concreta del humano + lugar exacto donde ve el output>.
+- [ ] **User-facing repeat**: el humano vuelve manana y ve datos frescos sin conocer el issue.
+- [ ] **User-facing onboarding**: parrafo en `## Notas` que explica "para ver/usar esto: hacer X".
+- [ ] **User-facing latencia**: el humano percibe el cambio en <X segundos|minutos>.
+
+## Notas
+
+<hallazgos, comandos para reproducir, parrafo onboarding>