fn_registry/dev/flows/template.md

---
name: <slug>
id: NNNN
status: pending
created: YYYY-MM-DD
updated: YYYY-MM-DD
priority: medium                # low | medium | high
risk: low                       # low | medium | high (sensibilidad datos)
related_issues: []
apps: []                        # apps tocadas — usadas por /flow list --app
projects: []                    # projects relacionados
vaults: []                      # vaults sink/source
capability_groups: []           # extractor, transformer, sink, navegator, ...
trigger: manual                 # manual | cron | webhook
schedule: ""                    # cron expr si trigger=cron
expected_runtime_s: 60
tags: []
---

## Goal

Una frase: que prueba este flow del sistema multi-app.

## Pre-requisitos

- Lista de cosas manuales/externas que deben estar listas antes (Chrome logueado, vault montado, service corriendo, token en `pass`, ...).

## Funciones del registry recomendadas

Tabla rol -> funcion candidata (ver `AGENT_GUIDE.md` para discovery). Si falta una pieza: marca `FALTA: crear <id>` con prompt sugerido para fn-constructor.

| Rol | Funcion candidata | Estado |
|---|---|---|
| Extractor | `<id>` | OK / FALTA |
| Validator | `<id>` | OK / FALTA |
| Transformer | `<id>` | OK / FALTA |
| Sink | `<id>` | OK / FALTA |
| Scheduler | DAG `<path>.yaml` / webhook / manual | OK / FALTA |
| Notify | `<id>` | OK / FALTA |

## Apps tocadas

- `<app>` (rol en el flow)

## Projects relacionados

- `<project>` (razon)

## Vaults / storage

- `<vault o BD>` (origin / sink)

## Capability groups consultados

- `<group>` (ver `docs/capabilities/<group>.md`)

## Flow

Pasos numerados. Cada paso puede ser:
- texto libre (manual)
- `function: <id>` (registry function)
- `cmd: <bash>`
- `js: <expression>` (en tab Chrome)
- `dag: <name>` (DAG en `apps/dag_engine/dags_migrated/`)

1. Paso 1.
2. Paso 2.

## Acceptance

Checks task-level del flow — verifican que el flow CORRE una vez. Pueden quedar `[ ]` mientras iteras. NO sustituyen a la DoD.

- [ ] Criterio 1.
- [ ] Criterio 2.

## Definition of Done

**Filosofia triada (ver `.claude/rules/dod_quality.md`):** DoD no es checkbox que se marca a mano. Cada item debe llevar **evidencia ejecutable** (comando, e2e_check, screenshot link, dashboard URL con datos frescos, log query). Si no puedes probarlo, no es DoD: es deseo. Las 3 capas son obligatorias.

### Mecanica (pre-requisito, NO sustituye al resto)

Construir verde no es estar hecho. Es la base para empezar a probar.

- [ ] **Build verde** (`cmd: <comando build>`).
- [ ] **Tests unitarios verdes** (`cmd: <comando test>`, listar IDs/paths).
- [ ] **`fn index` limpio** (sin warnings nuevos).
- [ ] **`fn doctor` verde** en artefactos tocados (`cmd: ./fn doctor --json | jq ...`).
- [ ] **`uses_functions` auditado** (sin drift en `app.md` vs imports reales).

### Cobertura de comportamiento

Cada escenario debe tener una prueba ejecutable con assert real (no smoke "no peto"). Anadir tantas filas como casos relevantes — golden path + edge cases + error paths.

| Escenario | Tipo de prueba | Comando / evidencia | Resultado esperado |
|---|---|---|---|
| Golden path: <descripcion> | unit / e2e / manual | `<cmd>` | <output concreto, no "ok"> |
| Edge case 1: <input limite> | unit / e2e | `<cmd>` | <comportamiento concreto> |
| Edge case 2: <estado raro> | unit / e2e | `<cmd>` | <comportamiento concreto> |
| Error path 1: <fallo esperado> | e2e | `<cmd que provoca fallo>` | <fallo manejado, no crash> |
| Error path 2: <recursos caidos> | e2e | `<cmd>` | <degradacion graceful + log> |

**Regla**: al menos 1 golden + 2 edge + 1 error path. Tests inscritos en `e2e_runs` de la app correspondiente cuando aplique.

### Vida util validada

El flow no esta hecho hasta que sobrevive **uso real** durante >=7 dias sin romperse silenciosamente. Cada metrica tiene umbral medible y dashboard observable.

| Metrica | Umbral | Donde se observa | Ventana |
|---|---|---|---|
| <metrica 1, ej. handshakes vivos> | `>=N` | `<dashboard URL / app panel>` | 7 dias |
| <metrica 2, ej. error_rate> | `<X%` | `<dashboard URL>` | 7 dias |
| <metrica 3, ej. duracion p95> | `<Xms` | `call_monitor.function_stats` | 30 dias |
| crashes del proceso | `0` | `journalctl -u <unit>` | 7 dias |
| huecos en audit chain | `0` | `cmd: <verify chain>` | continuo |

**Regla**: las metricas NO se autoreportan en el flow; las lee el operador del dashboard real. Si el dashboard no existe, el item se invalida.

### User-facing (reforzado)

"DoD verde" sin uso humano real = plumbing limpio sin razon de existir.

- [ ] **User-facing surface**: <accion concreta del humano + lugar exacto donde ve/usa el output (NO una BD, NO un log)>.
- [ ] **User-facing usage real**: el humano (operador) usa la cosa en **su PC, en su contexto real**, **>=N veces en >=7 dias**, con inputs reales (no demo, no sandbox).
- [ ] **User-facing variado**: cubre >=3 capabilities/casos distintos (no solo "abre dashboard y mira").
- [ ] **User-facing onboarding**: parrafo en `## Notas` que explica "para ver/usar esto: hacer X" sin leer el flow.
- [ ] **User-facing latencia**: percepcion del cambio <Xs|Xmin> tras el evento (X declarado, medido).

### Anti-criterios (invalidan la DoD aunque los checkboxes esten verdes)

Marca el flow como **NO done** si cualquiera de estas condiciones es cierta:

- [ ] **Solo-en-mi-PC**: el flow funciona en `home-wsl` pero falla en `pc-aurgi` u otro PC del operador.
- [ ] **Repetible-en-sandbox-vacio**: solo pasa con BD limpia / cuenta limpia / sin datos historicos.
- [ ] **Camino feliz unico**: los error paths fueron declarados pero NUNCA se ejercitaron (sin entry en `e2e_runs` o logs reales).
- [ ] **Dashboard fantasma**: el dashboard declarado en "Vida util" no se ha abierto en >30 dias.
- [ ] **Self-test que no apesta**: el `e2e_check` retorna `pass` sin verificar nada material (no asserts).
- [ ] **Silent-fail**: el proceso muere/degrada sin alerta visible al operador.
- [ ] **Approval saltado**: alguna capability con `requires_approval=true` fue ejecutada sin el approval flow.

### Custom (opcional, dominio-especifico)

- [ ] _(custom)_ <DoD especifica al dominio si aplica>.

## Telemetria esperada

- `call_monitor.calls`: que aparece.
- `data_factory.runs`: que aparece.
- `<app>.operations.db`: que aparece.
- Matrix / email / dashboard: que aparece visible.

## Riesgos / gotchas

- Lista de cosas que pueden romperse y como detectarlas.

## Notas

(rellenas tras correr o tras hallazgos)