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
@@ -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>