docs(flows): DoD obligatorio con user-facing surface + abrir issues 0100-0103 (taxonomia, frontmatter migration, dev_console, work dashboard)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-17 00:07:03 +02:00
parent a03675113a
commit 6ad82167bb
72 changed files with 3920 additions and 303 deletions
@@ -0,0 +1,105 @@
+# 0100 — Migrar frontmatter inline a YAML canonico en dev/issues/
+
+**Status:** pendiente
+**Created:** 2026-05-16
+**Type:** chore
+**Priority:** alta
+**Domain:** registry-quality
+**Scope:** registry-only
+**Depends:** —
+**Blocks:** 0102 (work dashboard tab necesita filtros frontmatter)
+**Related:** 0103 (taxonomia + slash commands)
+
+## Problema
+
+Hoy los 71 archivos `dev/issues/*.md` declaran metadata como markdown inline:
+
+```
+# 0099 — datahub app (launcher central)
+
+**Status:** pendiente
+**Created:** 2026-05-16
+**Type:** app
+**Priority:** alta
+**Depends:** 0096 — DONE
+**Blocks:** —
+```
+
+Imposible filtrar/agrupar sin parsers ad-hoc por linea. Issues antiguos (0027-0070) ni siquiera tienen `Type` ni `Priority`. Resultado: `/issue list` no existe; humano lee `README.md` (tabla manual) que se queda obsoleta.
+
+## Objetivo
+
+Frontmatter YAML canonico al inicio de cada issue, igual modelo que `dev/flows/`. Mantener el contenido humano intacto debajo.
+
+```yaml
+---
+id: 0099
+title: datahub app launcher central
+status: pendiente              # pendiente | in-progress | bloqueado | completado | deferred
+type: app                       # app | feature | bugfix | refactor | chore | docs | spike | epic | infra
+domain: [apps-infra, cpp-stack]
+scope: app-scoped               # registry-only | app-scoped | multi-app | cross-stack
+priority: alta                  # alta | media | baja
+depends: [0096]
+blocks: []
+related: [0095, 0097]
+created: 2026-05-16
+updated: 2026-05-16
+tags: []
+---
+
+# 0099 — datahub app launcher central
+
+(cuerpo original sin tocar)
+```
+
+## Pipeline propuesto
+
+`migrate_issues_frontmatter_bash_pipelines` (o python, lo que encaje mejor). Idempotente.
+
+1. Para cada `dev/issues/*.md`:
+   - Si ya tiene frontmatter YAML (`---` en linea 1): merge campos faltantes solo, no sobreescribe.
+   - Si no: parsea las lineas `**Key:** value` debajo del H1, extrae a YAML.
+   - Si `Type` / `Priority` ausentes: deja vacios + log warning para revision manual.
+   - `domain` y `scope` se infieren con heuristica por nombre/contenido (ej. `cpp-*` -> `cpp-stack`, `kanban-*` -> `kanban`, `trading-*` -> `trading`).
+2. Backup en `dev/issues/.backup_pre_0100/` antes de cualquier escritura.
+3. Output final: tabla de issues sin clasificar para review humano.
+
+## Dominios canonicos (allowlist)
+
+```
+meta, cpp-stack, kanban, trading, gamedev, osint, data-ingest,
+registry-quality, notify, imagegen, apps-infra, dev-ux, deploy,
+frontend, mcp, browser, telemetry, docs
+```
+
+Cualquier issue con `domain:` fuera de esta lista hace fallar el indexer.
+
+## Acceptance
+
+- [ ] Pipeline existe en `bash/functions/pipelines/` o `python/functions/pipelines/`.
+- [ ] 71 issues migrados sin perder contenido (diff vs backup solo en cabecera).
+- [ ] `dev/issues/README.md` ya no es fuente de verdad — se genera desde frontmatter via subcomando `/issue list` o cron diario.
+- [ ] Issues completados en `dev/issues/completed/` tambien migrados.
+- [ ] `fn doctor issues` (subcomando nuevo) reporta issues sin Type/Priority/Domain/Scope.
+- [ ] Pipeline idempotente (segunda corrida = 0 cambios).
+
+## Definition of Done
+
+### Generico
+
+- [ ] **Repetibilidad**: pipeline corre N veces sin diff.
+- [ ] **Observabilidad**: log de campos inferidos vs por defecto.
+- [ ] **Error-path**: archivo malformado -> skip + log + exit code != 0.
+- [ ] **Idempotencia**: archivo ya migrado -> 0 cambios.
+- [ ] **Secrets**: N/A.
+- [ ] **Docs**: README de `dev/issues/` actualizado para apuntar al frontmatter.
+- [ ] **Registry-first**: pipeline reusa `parse_yaml_frontmatter_*` (crear si no existe).
+- [ ] **INDEX + status**: issue cerrado + movido a `completed/`.
+
+### User-facing
+
+- [ ] **User-facing**: tras correr el pipeline, `head -20 dev/issues/0099-datahub-app-launcher.md` muestra YAML legible + `/issue show 0099` (cuando exista) imprime tabla limpia.
+- [ ] **User-facing repeat**: cada issue nuevo creado con `/issue create` (issue 0101) hereda el formato.
+- [ ] **User-facing onboarding**: parrafo en `dev/issues/README.md`: "Cada issue empieza con frontmatter YAML. Para ver/filtrar: `/issue list --domain trading --status pendiente`."
+- [ ] **User-facing latencia**: migracion completa en <60s sobre 71 archivos.
@@ -0,0 +1,100 @@
+# 0101 — dev_console Go binario: /issue /flow /work unificados
+
+**Status:** pendiente
+**Created:** 2026-05-16
+**Type:** app
+**Priority:** alta
+**Domain:** meta
+**Scope:** registry-only
+**Depends:** 0100 (frontmatter migration)
+**Blocks:** 0102 (work dashboard tab consume `dev_console --json`)
+**Related:** 0103 (slash commands llaman al binario)
+
+## Problema
+
+Issues y flows hoy se gestionan a ojo: `ls dev/issues/`, `grep`, edit manual de tablas en `README.md` / `INDEX.md`. Sin un comando unificado:
+
+- No hay `/issue list --domain trading --status pendiente`.
+- No hay `/flow status 0001` que cuente checkboxes + DoD %.
+- No hay vista cross-cutting "que hacer hoy" mezclando issues + flows.
+
+Necesitamos un binario unico (`dev_console`) con la misma forma que `fn`: subcomandos consistentes, output texto + `--json`, latencia <200ms.
+
+## Objetivo v1
+
+App Go en `apps/dev_console/` con subcomandos:
+
+### issue
+
+| Subcomando | Que hace |
+|---|---|
+| `dev_console issue list [--domain X] [--type Y] [--status Z] [--prio P] [--epic NNNN]` | tabla filtrable + DoD % |
+| `dev_console issue show NNNN` | imprime archivo |
+| `dev_console issue status NNNN` | % acceptance + estado deps (resuelto si todos los `depends` estan `completado`) |
+| `dev_console issue board` | output TUI o tabla columnas pendiente/in-progress/bloqueado/done |
+| `dev_console issue dep NNNN` | arbol bloquea/depende navegable |
+| `dev_console issue roadmap NNNN` | epic + sub-IDs (auto-detecta `NNNNa`, `NNNNb`, ...) |
+| `dev_console issue tag NNNN +X -Y` | mantenimiento tags |
+| `dev_console issue done NNNN` | mueve a `completed/`, valida deps, actualiza README |
+| `dev_console issue stale [--days 30]` | sin update >N dias |
+| `dev_console issue create <slug> --type T --domain D` | scaffold con frontmatter canonico |
+
+### flow
+
+| Subcomando | Que hace |
+|---|---|
+| `dev_console flow list [--app X] [--pattern P] [--risk R]` | tabla filtrable + DoD % |
+| `dev_console flow create <slug>` | scaffold (rechaza si falta DoD user-facing) |
+| `dev_console flow show NNNN` | imprime archivo |
+| `dev_console flow status NNNN` | Acceptance % + DoD % separados + checks user-facing destacados |
+| `dev_console flow dod NNNN` | solo bloque DoD + checklist live |
+| `dev_console flow trace NNNN` | join `call_monitor.calls` + `data_factory.runs` filtrados por funciones/apps del flow |
+| `dev_console flow user-test NNNN` | abre superficie usuario declarada en DoD (URL, lanza .exe, abre tab) |
+| `dev_console flow run NNNN` | fase 2 — ejecuta steps con `function:` |
+| `dev_console flow chain N M` | declara composicion N -> M |
+| `dev_console flow done NNNN` | exige DoD 100% (incluyendo user-facing) antes de mover |
+
+### work (cross-cutting)
+
+| Subcomando | Que hace |
+|---|---|
+| `dev_console work today` | top items prio alta + deps satisfechas (issues + flows) |
+| `dev_console work weekly` | review semanal: closed vs planeados (lookup en git log + completed/) |
+| `dev_console work search "texto"` | FTS sobre issues + flows + completed |
+| `dev_console work dashboard` | imprime JSON consumible por tab Work (issue 0102) |
+
+## Reglas tecnicas
+
+- Go + parser YAML (gopkg.in/yaml.v3) + tabwriter. Sin DB propia — fuente de verdad = archivos `.md`.
+- Cache opcional en `~/.cache/dev_console/index.json` invalidada por mtime.
+- `--json` en TODOS los subcomandos para consumo por dashboards/agentes.
+- Latencia objetivo <200ms en lookup, <500ms en list (71 issues + 7 flows).
+- Build canonico: `CGO_ENABLED=0 go build -tags fts5 -o dev_console .`
+
+## Acceptance
+
+- [ ] `dev_console issue list --status pendiente` lista los issues abiertos.
+- [ ] `dev_console flow status 0001` muestra Acceptance + DoD + user-facing %.
+- [ ] `dev_console work today` produce lista util (no vacia, no flood).
+- [ ] `dev_console flow done 0001` rechaza si DoD <100%.
+- [ ] Tests con fixtures en `apps/dev_console/testdata/`.
+
+## Definition of Done
+
+### Generico
+
+- [ ] **Repetibilidad**: tests verdes 3x; latencia consistente.
+- [ ] **Observabilidad**: cada invocacion registrada en `call_monitor.calls` (hook PostToolUse Bash detecta `dev_console *`).
+- [ ] **Error-path**: archivo malformado -> mensaje claro + exit code != 0.
+- [ ] **Idempotencia**: `done` 2x sobre mismo issue = 0 cambios la segunda.
+- [ ] **Secrets**: N/A.
+- [ ] **Docs**: `apps/dev_console/app.md` + `README.md` con ejemplos.
+- [ ] **Registry-first**: reusa `parse_yaml_frontmatter_*`, `checklist_count_*`, etc.
+- [ ] **INDEX + status**: issue cerrado.
+
+### User-facing
+
+- [ ] **User-facing**: usuario teclea `/issue list` en Claude Code o `dev_console issue list` en terminal y ve tabla limpia con prio/domain/status.
+- [ ] **User-facing repeat**: comando responde igual cada vez, sub-segundo, sin reset de estado.
+- [ ] **User-facing onboarding**: `apps/dev_console/app.md` lista comandos canonicos + casos comunes.
+- [ ] **User-facing latencia**: <500ms p95 para list, <200ms para show.
@@ -0,0 +1,77 @@
+# 0102 — Tab Work en registry_dashboard (issues + flows + telemetria)
+
+**Status:** pendiente
+**Created:** 2026-05-16
+**Type:** feature
+**Priority:** media
+**Domain:** meta
+**Scope:** app-scoped
+**Depends:** 0100 (frontmatter migration), 0101 (dev_console --json)
+**Blocks:** —
+**Related:** 0103 (slash commands)
+
+## Problema
+
+Hoy para ver "estado global del trabajo" hay que:
+
+1. `ls dev/issues/*.md` + leer cabeceras.
+2. `cat dev/flows/INDEX.md` + abrir flow por flow.
+3. `sqlite3 call_monitor.db` para metricas.
+4. Cruzar a mano que issues bloquean que flow.
+
+Cero visibilidad cross-cutting. Y nada me dice "abre el flow 0001 ya, todos sus checks user-facing estan listos" o "issue 0099 esta verde pero su dependencia 0096 esta marcada como DONE incorrectamente".
+
+## Objetivo
+
+Tab nueva `Work` en `projects/fn_monitoring/apps/registry_dashboard` (C++ ImGui). Tres paneles:
+
+### Panel 1 — Kanban issues
+
+Columnas: `pendiente | in-progress | bloqueado | completado-hoy`. Filtros (combo): domain, type, priority. Card por issue muestra: id, title, prio, deps no resueltas (en rojo si las hay).
+
+Drag entre columnas -> llama `dev_console issue tag NNNN --status X` por debajo.
+
+### Panel 2 — Flows table
+
+Tabla con columnas: id, slug, pattern, status, Acceptance %, DoD %, **DoD user-facing %**, ultima run en `data_factory.runs`. Click en fila -> abre archivo .md (o panel detalle al lado).
+
+Boton `User-test` por fila -> lanza `dev_console flow user-test NNNN` (abre URL/app/sala Matrix declarada).
+
+### Panel 3 — Telemetria (resumen call_monitor)
+
+KPIs ultimas 24h: `calls_24h`, `violations_24h`, `pending_proposals`, `Reg %`. Sparkline 7d por KPI. Misma fuente que el hook UserPromptSubmit.
+
+## Reglas
+
+- ImGui + `data_table_cpp_viz` para tablas (registry-first).
+- Datos vienen de `dev_console work dashboard --json` (call cada 5s en debug, cada 30s en prod).
+- Si `dev_console` no esta instalado: panel muestra placeholder + comando para instalar (sin crash).
+- Tab carga en <300ms (issue 0101 garantiza el binario).
+
+## Acceptance
+
+- [ ] Tab Work aparece en `registry_dashboard` con los 3 paneles.
+- [ ] Filtros funcionan (domain, type, priority, pattern).
+- [ ] Drag de issue actualiza disco.
+- [ ] User-test boton abre superficie usuario.
+- [ ] Refresh manual + auto cada 30s.
+
+## Definition of Done
+
+### Generico
+
+- [ ] **Repetibilidad**: tab abre 10x sin leak handles ni memoria.
+- [ ] **Observabilidad**: cada accion (drag, click User-test) loguea via `fn_log`.
+- [ ] **Error-path**: `dev_console` falla -> tab muestra error formateado, no crash.
+- [ ] **Idempotencia**: refresh 100x = misma tabla.
+- [ ] **Secrets**: N/A.
+- [ ] **Docs**: `registry_dashboard.app.md` lista la tab + casos de uso.
+- [ ] **Registry-first**: reusa `data_table_cpp_viz`, `selectable_text`, `fn_log`.
+- [ ] **INDEX + status**: issue cerrado.
+
+### User-facing
+
+- [ ] **User-facing**: usuario abre `registry_dashboard.exe` -> tab Work -> ve issues kanban + flows table + KPIs todo en una pantalla.
+- [ ] **User-facing repeat**: mismo dashboard manana muestra estado actualizado sin reset (deps resueltas se reflejan).
+- [ ] **User-facing onboarding**: parrafo en `app.md`: "Para el estado del trabajo: lanzar `registry_dashboard.exe` -> tab Work. Boton User-test abre la superficie usuario del flow."
+- [ ] **User-facing latencia**: refresh <300ms; cambio en disco visible en <30s (auto-refresh).
@@ -0,0 +1,123 @@
+# 0103 — Taxonomia + slash commands /issue /flow /work
+
+**Status:** pendiente
+**Created:** 2026-05-16
+**Type:** feature
+**Priority:** alta
+**Domain:** meta
+**Scope:** registry-only
+**Depends:** 0100 (frontmatter ya canonico), 0101 (dev_console binary)
+**Blocks:** 0102 (work dashboard usa los slash desde la tab)
+**Related:** todos los issues + flows
+
+## Problema
+
+Sin taxonomia formal, todo issue/flow se mezcla en un saco. `dev_console` (issue 0101) necesita un schema concreto para filtros: que dominios existen, que tipos son validos, que estados, que scopes. Y los slash commands `/issue *` / `/flow *` / `/work *` necesitan existir como archivos en `.claude/commands/` para que Claude Code los reconozca.
+
+## Objetivo
+
+### A) Taxonomia documentada
+
+Crear `dev/TAXONOMY.md` con la lista canonica:
+
+**Dominios** (allowlist):
+```
+meta, cpp-stack, kanban, trading, gamedev, osint, data-ingest,
+registry-quality, notify, imagegen, apps-infra, dev-ux, deploy,
+frontend, mcp, browser, telemetry, docs
+```
+
+**Tipos**:
+```
+app | feature | bugfix | refactor | chore | docs | spike | epic | infra | planning
+```
+
+**Estados**:
+```
+pendiente | in-progress | bloqueado | completado | deferred
+```
+
+**Scopes**:
+```
+registry-only | app-scoped | multi-app | cross-stack
+```
+
+**Prioridades**:
+```
+alta | media | baja
+```
+
+**Flow patterns**:
+```
+smoke-cron | prod-data | event-driven | manual-deep | gitops | realtime-loop
+```
+
+### B) Slash commands
+
+Crear `.claude/commands/issue.md`, `flow.md`, `work.md`. Cada uno con frontmatter que define `tool: Bash` + un `command:` que llama a `dev_console <subcomando> "$ARGS"`. Mientras 0101 no este listo: stub que avisa.
+
+```yaml
+# .claude/commands/issue.md
+---
+description: Gestiona issues del registry (list, show, status, board, done, ...)
+allowed-tools: [Bash]
+---
+
+Usage: /issue <subcomando> [args]
+
+Subcomandos:
+- list [--domain X] [--status Y] [--prio P]
+- show NNNN
+- status NNNN
+- board
+- dep NNNN
+- roadmap NNNN
+- tag NNNN +X -Y
+- done NNNN
+- stale [--days N]
+- create <slug> --type T --domain D
+
+Run:
+!`./apps/dev_console/dev_console issue $ARGUMENTS`
+```
+
+### C) Aplicar tags retroactivos
+
+Pipeline `tag_existing_issues_bash_pipelines` que, basado en heuristicas (nombre del archivo, contenido), propone `domain` y `scope` para los 71 issues. Output: lista para review humano (no escribe sin confirmacion).
+
+Heuristicas iniciales:
+- `cpp-*` -> domain `cpp-stack`
+- `kanban-*` -> domain `kanban`
+- `trading-*` -> domain `trading`
+- `gamedev-*` -> domain `gamedev`
+- `osint-*`, `odr-*` -> domain `osint`
+- `cpp-app-*`, `apps-*`, `init-*-app` -> scope `app-scoped`
+- `roadmap` en el title -> type `epic`
+
+## Acceptance
+
+- [ ] `dev/TAXONOMY.md` creado con todas las listas + descripcion 1-frase por valor.
+- [ ] `.claude/commands/{issue,flow,work}.md` existen y son visibles a Claude Code.
+- [ ] `fn doctor issues` (subcomando de 0100) valida `domain` y `scope` contra la allowlist.
+- [ ] Pipeline de tags retroactivos corre + produce reporte.
+- [ ] >=80% de los 71 issues quedan clasificados sin intervencion humana.
+
+## Definition of Done
+
+### Generico
+
+- [ ] **Repetibilidad**: pipeline + slash commands estables; no varian salida.
+- [ ] **Observabilidad**: cada slash command pasa por hook PostToolUse -> `call_monitor.calls`.
+- [ ] **Error-path**: dominio invalido -> error claro + sugerencia ("did you mean ...?").
+- [ ] **Idempotencia**: pipeline 2x = 0 cambios despues de primera pasada.
+- [ ] **Secrets**: N/A.
+- [ ] **Docs**: TAXONOMY referenciado desde `.claude/rules/INDEX.md`.
+- [ ] **Registry-first**: pipeline reusa parsers existentes.
+- [ ] **INDEX + status**: issue cerrado.
+
+### User-facing
+
+- [ ] **User-facing**: usuario teclea `/issue list --domain trading` en Claude Code y ve los 10 sub-issues del roadmap trading.
+- [ ] **User-facing repeat**: comandos disponibles desde cualquier sesion, no estado por sesion.
+- [ ] **User-facing onboarding**: `.claude/commands/issue.md` autodescribe los subcomandos (Claude Code los muestra al tipear `/issue` + tab).
+- [ ] **User-facing latencia**: <500ms por slash command.