---
name: migrate_issues_frontmatter
kind: pipeline
lang: py
domain: pipelines
version: "1.0.0"
purity: impure
signature: "def migrate_issues_frontmatter(issues_dir: str, backup_dir: str = '', dry_run: bool = False) -> dict"
description: "Migra dev/issues/*.md de metadata inline (**Key:** value) a frontmatter YAML canonico (issue 0100). Idempotente: archivos ya migrados (id + domain + scope presentes) se saltan. Archivos con frontmatter parcial reciben merge de claves faltantes. Infiere domain, scope, type y priority por heuristicas de nombre de archivo."
tags: [registry-quality, frontmatter, chore, dev-issues, migration, registry]
uses_functions:
  - extract_frontmatter_py_core
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports:
  - json
  - os
  - re
  - shutil
  - sys
  - datetime
  - pathlib
  - typing
tested: false
params:
  - name: issues_dir
    desc: "Ruta al directorio de issues (ej. 'dev/issues'). Se escanean *.md directos y completed/*.md."
  - name: backup_dir
    desc: "Directorio donde copiar los originales antes de escribir. Default: <issues_dir>/.backup_pre_0100/. Pasar '' para usar el default."
  - name: dry_run
    desc: "Si True, calcula cambios pero no escribe archivos ni crea backups."
output: "dict con claves: migrated (N archivos migrados desde cero), merged (N archivos con frontmatter parcial completado), skipped (N ya completos), warnings (lista de strings), files (lista de resultados por archivo con action/domain_inferred/scope_inferred/warnings)."
file_path: "python/functions/pipelines/migrate_issues_frontmatter.py"
notes: |
  Pipeline impuro: muta archivos .md en disco y crea backups.

  Heuristicas de domain (primer match gana, multi-tag posible):
    cpp-stack     — filename contiene cpp-, imgui, glfw, glsl, altsnap
    kanban        — filename contiene kanban
    trading       — filename contiene trading
    gamedev       — filename contiene gamedev
    osint         — filename contiene osint, odr-
    data-ingest   — filename contiene metabase, bigquery, datafactory, navegator, cdp-
    notify        — filename contiene notify, telegram, matrix
    imagegen      — filename contiene imagegen, sd-cpp, stable-diffusion
    registry-quality — filename contiene audit-, registry-first, uses_functions, nested-app-md
    meta          — filename contiene autonomous, e2e-validation, registry-call, delegation, capability, call-monitor, mcp-
    deploy        — filename contiene deploy, vps
    dev-ux        — filename contiene fn-run, gradle_run, dev-
    browser       — filename contiene browser, chrome, cdp-
    apps-infra    — filename contiene datahub, app-hub, launcher, app-locations
    frontend      — filename contiene frontend, react
    default       — lista vacia + warning

  Heuristicas de scope:
    roadmap       -> cross-stack
    extract-|migrate-|audit- -> registry-only
    type=app o -app- en filename -> app-scoped
    default       -> multi-app

  Heuristicas de type (si no viene del inline):
    roadmap       -> epic
    audit-|cleanup- -> chore
    fix-|bugfix-  -> bugfix
    default       -> feature

  Heuristicas de priority (si no viene del inline):
    mtime < 14 dias -> alta
    else            -> media

  Formatos inline reconocidos:
    **Status:** value   (y variantes: Estado, Tipo, Prioridad, Created, Depends, Blocks, Related)
    | **Campo** | valor |   (tabla markdown)

  El backup se crea solo UNA vez por archivo (si ya existe el backup, no sobreescribe).
  Segunda ejecucion = 0 cambios si los archivos ya tienen id + domain + scope.
---

## Ejemplo

```bash
# Siempre hacer dry-run primero para revisar
cd /home/lucas/fn_registry
python/.venv/bin/python3 python/functions/pipelines/migrate_issues_frontmatter.py dev/issues --dry-run

# Aplicar migracion real
python/.venv/bin/python3 python/functions/pipelines/migrate_issues_frontmatter.py dev/issues

# O via fn run
./fn run migrate_issues_frontmatter_py_pipelines
```

```python
import sys
sys.path.insert(0, "python/functions")
from pipelines.migrate_issues_frontmatter import migrate_issues_frontmatter

# Dry run
result = migrate_issues_frontmatter("dev/issues", dry_run=True)
print(result["migrated"], "to migrate,", result["skipped"], "already done")

# Apply
result = migrate_issues_frontmatter("dev/issues")
print(result["warnings"])
```

## Cuando usarla

Cuando necesites migrar `dev/issues/*.md` de inline `**Key:** value` a frontmatter YAML canonico. Ejecucion one-shot por proyecto; despues de la primera pasada, correr periodicamente para validar issues nuevos (idempotente).

Tambien util al crear un proyecto nuevo que adopte el formato issues/ de fn_registry: copia los .md y lanza el pipeline para homogeneizar.

## Gotchas

- **Muta archivos en disco**. Siempre correr con `--dry-run` primero para revisar la salida.
- **Backup dir no es gitignored por defecto**. Anadir `.backup_pre_0100/` al `.gitignore` del repo si no se quiere versionar.
- **Heuristicas de domain son best-effort**. Revisar warnings al final de la ejecucion; los archivos sin domain inferido quedan con `domain: []` y aparecen en warnings.
- **Frontmatter parcial se completa sin sobreescribir**. Si ya tienes `status: done` en el YAML, no se toca. Solo se anaden las claves ausentes.
- **El backup se escribe antes que el nuevo contenido**. Si el proceso se interrumpe a mitad, los backups son los originales correctos.
- **No valida el schema canonico de los tipos**. Si una issue tiene `type: weird-value`, se guarda tal cual y no hay warning. La validacion es responsabilidad de `fn doctor issues` (issue 0102, pendiente).