diff --git a/dev/flows/README.md b/dev/flows/README.md index 5c6c9569..8c7dd9e9 100644 --- a/dev/flows/README.md +++ b/dev/flows/README.md @@ -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 contiene linea con texto Z" | +| `url` | "GET 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: diff --git a/dev/issues/README.md b/dev/issues/README.md index 186b4aac..cbfbb35b 100644 --- a/dev/issues/README.md +++ b/dev/issues/README.md @@ -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//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 contiene linea con texto Z" — grep-eable | +| `url` | "GET 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`. diff --git a/docs/templates/flow.md b/docs/templates/flow.md new file mode 100644 index 00000000..83678310 --- /dev/null +++ b/docs/templates/flow.md @@ -0,0 +1,73 @@ +--- +name: +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: ` (registry function) +- `cmd: ` +- `js: ` (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**: . +- [ ] **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 . + +## Telemetria esperada +Que cambia en call_monitor / data_factory.runs / dag_engine. + +## Notas +Hallazgos tras correr. Incluye el parrafo onboarding. diff --git a/docs/templates/issue.md b/docs/templates/issue.md new file mode 100644 index 00000000..902ac1f7 --- /dev/null +++ b/docs/templates/issue.md @@ -0,0 +1,78 @@ +--- +id: "NNNN" +title: "" +status: pendiente # pendiente | in-progress | bloqueado | completado | descartado +type: feature # feature | bugfix | refactor | docs | chore | research | infra +domain: + - # ver dev/TAXONOMY.md (meta, cpp-stack, kanban, trading, ...) +scope: registry-only # registry-only | app: | flow: +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//agent.log contiene 'workflow done'" + required: true +--- +# NNNN — + +**Status:** pendiente +**Created:** 2026-05-18 +**Type:** feature +**Priority:** media +**Domain:** +**Scope:** registry-only +**Depends:** — +**Blocks:** — + +## Problema + + + +## Objetivo + + + +## 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**: . +- [ ] **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 . + +## Notas + +