@tacuchi/agent-workflow-cli 6.1.0 → 7.0.0

package/skills/agent-workflow/exports/export-arq/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: export-arq
+description: "Genera documentación técnica de arquitectura (`.md` con diagramas C4 embebidos) consolidando sesiones del workspace + `docs/` (especificaciones, decisiones, arq existente). Output: contexto, contenedores, componentes, integraciones externas, modelo de datos (si MCP disponible), decisiones arquitectónicas y riesgos/deuda. Structurizr DSL por default (notación C4 formal); Mermaid y PlantUML opt-in vía `--diagrams`. Output en `docs/arquitectura/NNN-export-arq-YYYY-MM-DD/`. Read-only sobre corpus + MCP read-only para schemas. Audiencia: devs/arquitectos. Invocado sólo vía `/agent-workflow:export-arq`. v1.1 (session077): el default pasa de Mermaid a Structurizr para alinear con la regla canónica «el tipo de documento manda» (manuales técnicos / dossiers C4 → Structurizr). Mermaid auxiliar permanece embebido en arquitectura.md para lectura offline. v1.2 (session078): cada bloque Mermaid embebido lleva debajo un blockquote con link `https://mermaid.ink/img/<base64>` (PNG renderizada). v1.3 (session081): corpus extendido a `docs/` además de sesiones (DEC-002) — ver `docs/shared-contract/export-corpus-sources.md`."
+version: 1.3.0
+---
+
+> **Profile parametrization**: lee `mcp_databases[]` de `profile.json` (resuelto vía cascade 5 capas). Ver [`references/profile-parametrization.md`](../../references/profile-parametrization.md) para el contrato completo y comportamiento por defecto cuando el profile está vacío.
+
+# Export Arq — Documentación de arquitectura desde fuentes + corpus
+
+Genera un dossier técnico de arquitectura del workspace, agregando fuentes declaradas, integraciones externas y decisiones tomadas. **Read-only / reporte** — no commitea, no muta nada.
+
+> Segundo comando de la familia `/agent-workflow:export-*`. Hermano de `export-func` (informe ejecutivo). Propuesta del modelo: `docs/conclusiones/007-export-commands-family.md`.
+
+## Excepción session-aware
+
+Este skill requiere conocimiento del lifecycle. **No crea ni modifica sesiones**. Si el workspace no tiene AW-PROJECT con fuentes declaradas → abortar con `ok: false`.
+
+**Solo formato actual (v0.9+)**: sesiones legacy abortan; migrar con `/agent-workflow:migrate --upgrade-topology`.
+
+**Consumo de CLI `agent-workflow`** (no leer paths hardcodeados):
+- `agent-workflow project-md-upsert --read` — `workspace_mode`, fuentes, integraciones declaradas, working branches.
+- `agent-workflow history-data` — sesiones cerradas (insumo de decisiones + riesgos).
+- `agent-workflow session-artifacts --code <NNN>` — lectura lazy de OBJECTIVE/DECISIONS/CONCLUSIONS por sesión.
+- `agent-workflow decisiones-list --code <NNN>` — DEC-NNN cronológicas.
+- `agent-workflow next-number docs/arquitectura` — numeración determinística.
+
+**MCP read-only** (opcional, sólo si `--scope` incluye `datos` y MCP está configurado):
+- `<mcp-cert>` / `<mcp-prod>` — `SELECT count(*)`, `EXPLAIN`, `\d <tabla>` para esquemas BD.
+
+## When to use
+
+- "Documento de arquitectura", "diagrama del sistema", "C4 del workspace".
+- Onboarding técnico de nuevos miembros del equipo.
+- Antes de cambios estructurales (validar arquitectura vigente).
+- Auditoría técnica.
+- Acompañamiento a propuestas de cambio mayor.
+
+## Qué hace este skill
+
+1. Lee AW-PROJECT (fuentes + mode + integraciones declaradas).
+2. Lee corpus de sesiones cerradas (decisiones arquitectónicas + riesgos abiertos).
+3. Inspecciona filesystem por fuente: hooks instalados, MCP configurado, plugins/commands.
+4. Si `--scope` incluye `datos` y MCP disponible: consulta esquemas BD (read-only).
+5. Selecciona variante de diagrama (`--diagrams`) y plantilla.
+6. Renderiza secciones según `--scope`.
+7. Aplica validations V1-V6 (`references/validations.md`).
+8. Si pasa: escribe `docs/arquitectura/NNN-export-arq-YYYY-MM-DD/`.
+9. Si `--dry-run`: imprime reporte (secciones que aparecerían, counts, variante).
+
+## Qué NO hace
+
+- Ejecutar commits, merges, push, SQL ni envío de correos.
+- Mutar corpus de sesiones ni AW-PROJECT.
+- Validar que las integraciones declaradas funcionen (eso es `/agent-workflow:doctor`).
+- Renderizar visualmente el diagrama (sólo source Mermaid/DSL/PUML; el render visual lo hace el lector con sus herramientas).
+- Filtrar el "estado actual" del sistema por `--since` o `--period` (el snapshot es siempre el último); esos flags sólo afectan la sección "Decisiones arquitectónicas".
+
+## Sandbox read-only
+
+`../session/references/sandbox-readonly-rules.md`. En plan mode esta skill describe:
+- Variante de diagrama resuelta + plantilla a cargar.
+- Secciones que aparecerían (resolvidas por `--scope`).
+- Fuentes a inspeccionar + integraciones declaradas.
+- Si `--scope datos`: queries MCP propuestas con costo estimado (cost guard).
+- Hallazgos de V4 (Modelo de datos presente/omitido, Decisiones presentes/omitidas).
+
+NO ejecuta: `Write` del `.md` output, mutaciones MCP, `next-number` con efecto.
+
+## Estilo de comunicación
+
+`../session/references/communication-style.md`. La audiencia es técnica — sin léxico ejecutivo. `agent-workflow:redaccion-simple` aplica con preset default (frases cortas, listas sobre prosa, sin relleno). No hay traducción técnica→ejecutiva.
+
+## Entrada
+
+```
+/agent-workflow:export-arq [--since sessionNNN] [--source <alias>]
+                [--diagrams mermaid|structurizr|plantuml]
+                [--scope c4|integraciones|datos|decisiones|riesgos|todo]
+                [--dry-run]
+```
+
+### Matriz `--diagrams` × `--scope`
+
+`--diagrams` selecciona el motor del render de C4; `--scope` selecciona qué secciones aparecen.
+
+| `--scope` | Secciones presentes |
+|---|---|
+| `c4` | Sistema (C4 Context) + Contenedores (C4 Container) + Componentes (C4 Component) |
+| `integraciones` | Integraciones externas |
+| `datos` | Modelo de datos (sólo si MCP disponible) |
+| `decisiones` | Decisiones arquitectónicas |
+| `riesgos` | Riesgos y deuda |
+| `todo` (default) | Todas las secciones aplicables |
+
+| `--diagrams` | Motor de C4 |
+|---|---|
+| `structurizr` (default) | `workspace.dsl` aparte + Mermaid auxiliar embebido en MD (lectura offline) |
+| `mermaid` | Mermaid C4Context / C4Container / C4Component nativo embebido en MD (sin DSL aparte) |
+| `plantuml` | `arquitectura.puml` aparte (C4-stdlib) + nota en MD |
+
+**Regla canónica del default (DEC-004 session077)**: `export-arq` cubre documentación técnica / manuales / dossiers de arquitectura. Structurizr DSL es el estándar C4 formal (separa modelo de vistas, soporta tooling externo). Mermaid permanece como opt-in cuando se prefiere render embebido sin DSL separado.
+
+### Resolución de `--since` y `--source`
+
+- `--since sessionNNN`: filtra **sólo** la sección "Decisiones arquitectónicas" (cronológicas). El snapshot del sistema vigente NO se filtra por `--since`.
+- `--source <alias>`: limita el output a esa fuente y sus integraciones internas; con default agrega todas las fuentes del hub.
+
+### `--sessions` excluido
+
+`export-arq` produce un **snapshot del sistema vigente** (estado actual de C4, integraciones, datos, riesgos). La selección discreta de sesiones por código (`--sessions NNN[,NNN]`) **no aplica** a este export: el snapshot siempre refleja el último estado conocido. Sólo `--since sessionNNN` afecta cronológicamente la sub-sección "Decisiones arquitectónicas". Decisión canónica G4 de `docs/conclusiones/008-roadmap-export-plan-lifecycle.md` (session062).
+
+## Flujo
+
+### Paso 1 — Resolver contexto
+
+```
+agent-workflow project-md-upsert --read
+```
+
+Extrae `workspace_mode`, `fuentes[]`, integraciones declaradas, `mode` (hub/project). Determina root del workspace + path destino:
+- `hub` → `<hub>/docs/arquitectura/NNN-export-arq-YYYY-MM-DD/`.
+- `project` → `<cwd>/docs/arquitectura/NNN-export-arq-YYYY-MM-DD/`.
+
+### Paso 2 — Inspeccionar fuentes y sus internas
+
+Por cada fuente declarada:
+- Resolver `<source.path>` → leer estructura básica.
+- Detectar componentes internos: `commands/`, `skills/`, `hooks/`, `.claude-plugin/`, MCP configurado.
+- Detectar tecnologías (lenguaje, framework) por archivos de manifest (`package.json`, `pom.xml`, etc.).
+
+### Paso 3 — Filtrar corpus para decisiones
+
+```
+agent-workflow history-data
+```
+
+Aplicar filtro `--since sessionNNN` sólo si está presente.
+
+Para cada sesión cerrada del corpus filtrado:
+```
+agent-workflow decisiones-list --code <CODE>
+```
+
+Acumular DEC-NNN cronológicas. Si 0 DEC → V4 omite sección "Decisiones".
+
+### Paso 4 — Inspeccionar MCP (opcional)
+
+Si `--scope` incluye `datos` y MCP `<mcp-cert>` o `<mcp-prod>` está configurado:
+- `\d <tabla_principal>` por cada esquema relevante.
+- `SELECT count(*) FROM <tabla>` para magnitud (cost guard: ver `agent-workflow:analyze-investigate/references/cost-guard.md`).
+- Recolectar relaciones FK para erDiagram.
+
+Si MCP no disponible o `--scope` excluye `datos` → V4 omite sección "Modelo de datos" con nota inline.
+
+### Paso 5 — Identificar riesgos y deuda
+
+Escanear corpus filtrado por keywords:
+- `## Open (gaps)` en CONCLUSIONS.md.
+- "deuda técnica" / "deuda funcional" / "riesgo" en CHECKPOINT.md o CONCLUSIONS.md.
+- Sesiones con estado `requirement` o `planning` no cerradas > 30 días → deuda de "trabajo en curso estancado".
+
+### Paso 6 — Resolver variante y cargar plantilla
+
+```
+references/template-c4.md
+```
+
+Reglas por flag:
+- **`--diagrams structurizr` (default)** → cargar `references/template-structurizr.dsl` y rellenarlo con el modelo + vistas. El `arquitectura.md` incluye además un Mermaid auxiliar embebido derivado del DSL (fallback offline).
+- **`--diagrams mermaid`** → omitir `workspace.dsl`; el `arquitectura.md` lleva Mermaid C4 nativo (`C4Context`/`C4Container`/`C4Component`).
+- **`--diagrams plantuml`** → cargar `references/template-plantuml.puml` (opt-in C4-stdlib); `arquitectura.md` deja nota inline apuntando al `.puml`.
+
+### Paso 7 — Renderizar secciones
+
+Aplicar:
+1. **Plantilla** con placeholders reemplazados por datos del corpus.
+2. **Léxico técnico mínimo** (`references/lexico-tecnico.md`): cero placeholders sin reemplazar, cero fragments de plantilla, cero paths absolutos del developer, sin jerga inventada sin glosa.
+3. **`agent-workflow:redaccion-simple` preset default**: frases cortas, listas sobre prosa, sin relleno.
+4. **Link de visualización por bloque Mermaid (v1.2 — session078)**: por cada bloque ```` ```mermaid ```` en arquitectura.md (Mermaid auxiliar bajo Structurizr default, o Mermaid C4 nativo bajo `--diagrams mermaid`), agregar inmediatamente después del fence de cierre: línea en blanco + blockquote `> Ver diagrama renderizado: <https://mermaid.ink/img/BASE64>`. El `BASE64` es el código Mermaid plano codificado en base64 URL-safe (RFC 4648 §5; alfabeto `A-Z a-z 0-9 - _`). Texto fijo "Ver diagrama renderizado" en español técnico. NO aplica a `workspace.dsl` ni `arquitectura.puml` (mermaid.ink solo renderiza Mermaid).
+
+### Paso 8 — Validar (V1-V6)
+
+Aplicar checks de `references/validations.md`:
+- V1 estructura (secciones requeridas por `--scope` presentes).
+- V2 noise vetado (grep determinístico).
+- V3 secciones en orden.
+- V4 condicionales (Datos omitido si no MCP; Decisiones omitido si 0 DEC).
+- V5 header bien formado.
+- V6 referencias resolubles (paths a `docs/<categoria>/`).
+
+Si V1, V3 o V4 fallan → abortar con error report. V2, V5, V6 → warning.
+
+### Paso 9 — Escribir output
+
+Si `--dry-run`: imprimir reporte (count secciones, variante, V4 outcome). No escribir.
+
+Si pasa: `agent-workflow next-number docs/arquitectura` → escribir directorio:
+
+```
+docs/arquitectura/NNN-export-arq-YYYY-MM-DD/
+├── README.md            # índice + counts + how-to-read
+├── arquitectura.md      # documento principal con Mermaid auxiliar embebido (lectura offline)
+├── workspace.dsl        # default (--diagrams structurizr); ausente sólo con --diagrams mermaid
+└── arquitectura.puml    # opcional (--diagrams plantuml)
+```
+
+## Composición con otras skills
+
+- **`agent-workflow:redaccion-simple`** — preset default aplicado durante el render (paso 7).
+- **`agent-workflow:rules`** — anchors transversales (sandbox-readonly, commits-policy) consultables.
+- **`agent-workflow:analyze-investigate`** — referenciable para reglas de cost guard MCP cuando `--scope datos`.
+- **`session`** — este skill NO invoca graduación ni cierre. La sesión activa puede consumirlo durante validation o closure para producir un snapshot de arquitectura.
+
+## Re-ejecución
+
+Idempotente funcional: cada invocación toma siguiente NNN. No sobrescribe outputs previos.
+
+Para regenerar el último: borrar el directorio manualmente y re-invocar.
+
+## Recursos adicionales
+
+- **`references/template-c4.md`** — plantilla canónica con C4 Levels 1-3 + integraciones + datos + decisiones + riesgos.
+- **`references/template-structurizr.dsl`** — Phase 4 opt-in (`workspace.dsl` con `model` + `views`).
+- **`references/template-plantuml.puml`** — Phase 4 opt-in (C4-stdlib).
+- **`references/lexico-tecnico.md`** — lista mínima de "noise" vetado para V2.
+- **`references/validations.md`** — V1-V6 detalladas con condiciones de hard-fail.
+- **`docs/conclusiones/007-export-commands-family.md`** — Propuesta original de la familia `/agent-workflow:export-*` (session055).
+- **`agent-workflow/skills/export-func/SKILL.md`** — hermano (informe ejecutivo) que comparte patrón estructural.

package/skills/agent-workflow/exports/export-arq/references/lexico-tecnico.md

@@ -0,0 +1,94 @@
+# Léxico técnico — limpieza mínima de noise para export-arq
+
+A diferencia de `export-func/references/lexico.md` (que traduce técnico→ejecutivo para audiencia gerencial), este léxico es **mínimo**: la audiencia de `export-arq` es técnica (devs/arquitectos) y los términos técnicos son bienvenidos. Sólo se veta el "noise" interno no profesional.
+
+## Lista vetada (V2 — para grep determinista)
+
+Términos / patrones que **no deben aparecer** en el cuerpo del output (excepto en `## Referencias`):
+
+```
+{{
+}}
+<-- TODO
+<-- FIXME
+<-- WIP
+<-- XXX
+{{PRODUCTO}}
+{{FECHA
+{{C4_CONTEXT
+{{C4_CONTAINER
+{{C4_COMPONENT
+{{INTEGRACIONES
+{{MODELO_DATOS
+{{DECISIONES
+{{RIESGOS
+{{REFERENCIAS
+{{RESUMEN
+{{LISTA_FUENTES
+{{DIAGRAMS_ENGINE
+sessionXXX
+sessionYYY
+sessionNNN
+DEC-NNN
+NNN-export
+YYYY-MM-DD
+/Users/
+~/Git/
+TODO:
+FIXME:
+WIP:
+XXX:
+HACK:
+```
+
+**Qué busca esta lista**:
+- **Placeholders no reemplazados** (`{{...}}`, `sessionXXX`, `DEC-NNN`, `NNN-export`, `YYYY-MM-DD`): indica fallo del render.
+- **Fragmentos de plantilla** (`<-- TODO`, `<-- FIXME`, comentarios HTML que debían stripearse): noise residual.
+- **Paths absolutos del developer** (`/Users/`, `~/Git/`): no son útiles para el lector y filtran info local.
+- **Markers de "WIP"** (TODO/FIXME/HACK con dos puntos): si quedaron en el doc final, V2 los marca como noise.
+
+**Excepciones autorizadas** (V2 las exime):
+- La sección `## Referencias` puede contener placeholders esperados (ej. `docs/arquitectura/NNN-...` como path tipo).
+- El header puede contener identificadores del producto que sean canónicos (ej. "qtc-*").
+
+## Cómo validar
+
+```bash
+# Strippear header (antes del primer #) y sección Referencias
+awk '
+  BEGIN { body=0 }
+  /^# Referencias/ { body=0 }
+  body { print }
+  /^# / && !/Referencias/ { body=1 }
+' output.md > /tmp/body.md
+
+# grep contra la lista vetada (fixed strings, case-sensitive para placeholders).
+grep -n -F -f lexico-noise-vetado.txt /tmp/body.md
+```
+
+Salida vacía → V2 pasa. Salida con matches → V2 falla.
+
+## Reglas adicionales de redacción
+
+Aplicables al render del documento. Heredan de `agent-workflow:redaccion-simple` con preset default:
+
+- **Frases cortas**: ≤20 palabras (más permisivo que en export-func ejecutivo).
+- **Listas sobre prosa**: 3+ items paralelos → bullets.
+- **Una idea por línea en bullets**.
+- **Sin relleno**: cero "es importante notar que", "cabe destacar", etc.
+- **Verbos directos**: "valida" mejor que "realiza la validación de".
+- **Términos técnicos OK**: jerga del dominio (propuesta, MCP, C4, hook, skill) está autorizada — la audiencia la maneja.
+- **Acrónimos**: glosarlos la primera vez sólo si no son del dominio cotidiano del lector técnico. Ej: "C4 (Context-Container-Component-Code)" la primera vez OK; "MCP" se asume conocido.
+- **Sin nombres del developer** (ni paths absolutos, ni emails, ni handles).
+- **Diagramas integrados con texto**: cada diagrama Mermaid va acompañado de 1-2 líneas que lo introducen o resumen. Diagrama suelto sin texto es noise estructural.
+
+## Diferencias con `export-func/references/lexico.md`
+
+| Aspecto | `export-arq/lexico-tecnico.md` | `export-func/lexico.md` |
+|---|---|---|
+| Foco | Limpieza de noise interno | Traducción técnica → ejecutiva |
+| Tamaño de tabla | ~25 términos vetados | ~75 términos vetados |
+| Tabla de traducción | ninguna | ~45 pares |
+| Términos técnicos | autorizados | vetados (deben traducirse) |
+| Audiencia | devs/arquitectos | gerencia/jefatura/comité |
+| Grep modo | `-F -f` (case-sensitive ok) | `-i -F -f` (case-insensitive) |

package/skills/agent-workflow/exports/export-arq/references/template-c4.md

@@ -0,0 +1,293 @@
+# Plantilla canónica — arquitectura.md (export-arq)
+
+Plantilla con placeholders identificables. Las llaves dobles `{{PLACEHOLDER}}` se reemplazan por el render del skill. Los comentarios `<!-- ... -->` orientan al AI sobre contenido por sección; no aparecen en el output final.
+
+**Secciones condicionales**: aparecen o se omiten según `--scope` y disponibilidad de MCP. Ver `validations.md` V3/V4.
+
+---
+
+```markdown
+# Arquitectura — {{PRODUCTO}}
+
+Snapshot del sistema al {{FECHA_SNAPSHOT}}.
+Fuentes incluidas: {{LISTA_FUENTES}}.
+Variante de diagrama: {{DIAGRAMS_ENGINE}}.
+
+## Resumen
+
+<!-- 2-4 frases. Qué es el sistema, qué hace, en qué consta a alto nivel.
+     Audiencia: devs/arquitectos. Sin jerga inventada sin glosa.
+     Sin commits, sin nombres de archivos internos. -->
+
+{{RESUMEN}}
+
+## Sistema (C4 Context)
+
+<!-- C4 Level 1: el sistema como caja única + usuarios + sistemas vecinos.
+     Default Structurizr DSL (ver workspace.dsl); Mermaid auxiliar embebido para lectura offline.
+     Con --diagrams mermaid el bloque queda como Mermaid C4Context nativo.
+     Con --diagrams plantuml se reemplaza por nota inline a arquitectura.puml.
+     v1.2 (session078): cada bloque Mermaid lleva debajo blockquote con link mermaid.ink/img/<base64>. -->
+
+```mermaid
+{{C4_CONTEXT_MERMAID}}
+```
+
+> Ver diagrama renderizado: <{{C4_CONTEXT_MERMAID_RENDER_LINK}}>
+
+{{C4_CONTEXT_TEXTO}}
+
+## Contenedores (C4 Container)
+
+<!-- C4 Level 2: aplicaciones / servicios / data stores que componen el sistema.
+     Cada fuente declarada en AW-PROJECT aparece como un contenedor.
+     Tecnologías por contenedor identificables por manifests (package.json, etc.).
+     Default Structurizr DSL (vista `container` en workspace.dsl); Mermaid auxiliar embebido.
+     v1.2 (session078): cada bloque Mermaid lleva debajo blockquote con link mermaid.ink/img/<base64>. -->
+
+```mermaid
+{{C4_CONTAINER_MERMAID}}
+```
+
+> Ver diagrama renderizado: <{{C4_CONTAINER_MERMAID_RENDER_LINK}}>
+
+{{C4_CONTAINER_TEXTO}}
+
+## Componentes (C4 Component)
+
+<!-- C4 Level 3: módulos internos relevantes por contenedor.
+     Sólo para los contenedores con suficiente complejidad interna.
+     1 diagrama por contenedor relevante; el resto se omite.
+     Default Structurizr DSL (vistas `component` por contenedor en workspace.dsl); Mermaid auxiliar embebido.
+     Condicional por scope: aparece si --scope ∈ {c4, todo}. -->
+
+{{C4_COMPONENT_BLOQUES}}
+
+## Integraciones externas
+
+<!-- Sistemas externos con los que el workspace interactúa.
+     Para qtc-* runtime hub: MCP servers, hooks PreToolUse, marketplace, npm registry.
+     Tabla + opcional sequenceDiagram para flows críticos.
+     Condicional por scope: aparece si --scope ∈ {integraciones, todo}. -->
+
+| Integración | Dirección | Tecnología | Uso |
+|---|---|---|---|
+{{INTEGRACIONES_TABLA}}
+
+{{INTEGRACIONES_DIAGRAMA_OPCIONAL}}
+
+## Modelo de datos
+
+<!-- Esquemas BD relevantes, vía MCP read-only (`\d`, `SELECT count`).
+     erDiagram con tablas + FK relevantes.
+     Condicional por scope+MCP: aparece si --scope ∈ {datos, todo} Y MCP disponible.
+     Si MCP no disponible: nota inline _(MCP no configurado — modelo de datos no disponible)_. -->
+
+{{MODELO_DATOS_OR_OMIT}}
+
+## Decisiones arquitectónicas
+
+<!-- Tabla cronológica de DEC-NNN del corpus + propuestas graduadas.
+     Cada decisión linkea a su sesión origen.
+     Condicional por scope: aparece si --scope ∈ {decisiones, todo}.
+     Si 0 DEC → sección omitida con nota o nada (decisión del render). -->
+
+| Fecha | DEC | Decisión | Origen |
+|---|---|---|---|
+{{DECISIONES_TABLA}}
+
+## Riesgos y deuda
+
+<!-- Bullets categorizados (negocio / operativo / técnico).
+     Extraídos de `## Open (gaps)`, `## Recommendations`, menciones a "deuda" / "riesgo" en el corpus.
+     Cada item ≤30 palabras.
+     Condicional por scope: aparece si --scope ∈ {riesgos, todo}. -->
+
+{{RIESGOS_BULLETS}}
+
+## Referencias
+
+<!-- Links a artefactos del workspace.
+     Hasta 8 referencias. Omitir categorías sin material. -->
+
+{{REFERENCIAS}}
+```
+
+---
+
+## Placeholders detallados
+
+### `{{PRODUCTO}}`
+
+Nombre del sistema/producto desde `AW-PROJECT.proyecto`. Si la descripción es larga, usar la primera frase (≤10 palabras). Capitalización natural (no mayúsculas a la fuerza).
+
+Ejemplo: `Runtime qtc-*` o `Sistema de mantenimiento de parámetros`.
+
+### `{{FECHA_SNAPSHOT}}`
+
+Fecha del sistema al momento de generar el doc. Formato natural ES: `18 de mayo de 2026`.
+
+### `{{LISTA_FUENTES}}`
+
+Lista coma-separada de los alias de fuentes declaradas en AW-PROJECT. Si `--source <alias>`, sólo esa fuente.
+
+Ejemplo: `agent-workflow, agent-workflow, qtc-plugins-marketplace`.
+
+### `{{DIAGRAMS_ENGINE}}`
+
+Valor del flag `--diagrams` resuelto: `Structurizr DSL (default)` / `Mermaid C4 nativo` / `PlantUML (C4-stdlib)`. v1.1 (session077) invirtió el default: la elección refleja la regla "tipo de documento manda" — `export-arq` genera dossiers técnicos, Structurizr es el estándar C4 formal.
+
+### `{{RESUMEN}}` (2-4 frases)
+
+Descripción del sistema en términos técnicos. Sin marketing, sin tono ejecutivo. Audiencia: devs.
+
+### `{{C4_CONTEXT_MERMAID}}`
+
+Bloque Mermaid `C4Context`. Ejemplo de estructura:
+
+```
+C4Context
+  title Diagrama de Contexto: Runtime qtc-*
+  Person(dev, "Developer", "Miembro del equipo")
+  System(sistema, "Runtime qtc-*", "Coordinación de sesiones")
+  System_Ext(claude, "Claude Code", "Host AI")
+  System_Ext(codex, "Codex", "Host AI alternativo")
+  System_Ext(npm, "npm registry", "Distribución CLI")
+  Rel(dev, sistema, "Usa")
+  Rel(sistema, claude, "Se integra con")
+  Rel(sistema, codex, "Se integra con")
+  Rel(sistema, npm, "Publica a")
+```
+
+**Default `--diagrams structurizr`**: este bloque contiene el export Mermaid del DSL (auxiliar embebido para lectura offline); el archivo canónico es `workspace.dsl`. Con `--diagrams mermaid`: el bloque es Mermaid C4 nativo y `workspace.dsl` no se genera. Con `--diagrams plantuml`: se reemplaza por nota inline `> Ver arquitectura.puml para el diagrama C4 Context en PlantUML.`
+
+### `{{C4_CONTEXT_TEXTO}}`
+
+1-2 párrafos describiendo el contexto. Quiénes son los actores, qué interacciones existen, qué quedó fuera de scope.
+
+### `{{C4_CONTAINER_MERMAID}}`
+
+Bloque Mermaid `C4Container` con un contenedor por fuente. Ejemplo:
+
+```
+C4Container
+  title Diagrama de Contenedores: Runtime qtc-*
+  Person(dev, "Developer")
+  System_Boundary(sistema, "Runtime qtc-*") {
+    Container(cli, "agent-workflow CLI", "Node.js / TypeScript", "Línea de comandos del runtime")
+    Container(plugin, "agent-workflow", "Markdown skills + hooks", "Skills y comandos invocables")
+    Container(marketplace, "qtc-plugins-marketplace", "JSON manifest", "Distribución del plugin")
+  }
+  Rel(dev, cli, "Ejecuta")
+  Rel(cli, plugin, "Lee skills")
+  Rel(plugin, marketplace, "Distribuido via")
+```
+
+### `{{C4_CONTAINER_TEXTO}}`
+
+1 párrafo por contenedor: responsabilidad + tecnología + dependencias externas relevantes.
+
+### `{{C4_COMPONENT_BLOQUES}}`
+
+Para cada contenedor con complejidad interna suficiente: header `### <Contenedor>` + Mermaid C4Component + texto descriptivo.
+
+Si ningún contenedor justifica C4 Component → omitir esta sub-sección completa con nota inline `_(No se identificaron contenedores con complejidad interna que justifiquen C4 Component nivel.)_`.
+
+### `{{INTEGRACIONES_TABLA}}`
+
+Filas por integración:
+
+| Integración | Dirección | Tecnología | Uso |
+|---|---|---|---|
+| Claude Code | bidireccional | CLI + hooks JSON | Host AI principal |
+| Codex | bidireccional | CLI + hooks JSON | Host AI alternativo |
+| MCP <mcp-cert> | salida read-only | PostgreSQL via MCP | Consulta de esquemas BD |
+| npm registry | salida write | HTTPS | Distribución CLI |
+
+### `{{INTEGRACIONES_DIAGRAMA_OPCIONAL}}`
+
+Sequence Mermaid opcional para flows críticos (ej. session-create cross-runtime). Sólo si aporta claridad real.
+
+### `{{MODELO_DATOS_OR_OMIT}}`
+
+**A. Si MCP disponible Y `--scope` ∈ {datos, todo}**:
+
+```mermaid
+erDiagram
+  TABLA_A ||--o{ TABLA_B : "tiene"
+  TABLA_A {
+    int id PK
+    string nombre
+  }
+  TABLA_B {
+    int id PK
+    int a_id FK
+    string detalle
+  }
+```
+
++ tabla con tamaños (cantidad de filas por tabla relevante).
+
+**B. Si MCP NO disponible o `--scope` excluye datos**:
+
+```
+_(MCP no configurado en este workspace — modelo de datos no disponible.
+Esta sección aparece en workspaces de producto con MCP <mcp-cert> / <mcp-prod> habilitado.)_
+```
+
+Encabezado de sección sigue presente; el body es la nota.
+
+### `{{DECISIONES_TABLA}}`
+
+Filas cronológicas (más reciente primero):
+
+| Fecha | DEC | Decisión | Origen |
+|---|---|---|---|
+| 2026-05-18 | DEC-001 | Skill standalone sin foundation export-shared | session057-dev-export-func |
+| 2026-05-18 | DEC-002 | Skill orquesta, sin sub-comando CLI dedicado | session057-dev-export-func |
+| ... | ... | ... | ... |
+
+Si 0 DEC en el corpus filtrado por `--since` → omitir la sección completa o reemplazar por nota `_(Sin decisiones formales DEC-NNN registradas en el período filtrado.)_` (decisión del render según contexto).
+
+### `{{RIESGOS_BULLETS}}`
+
+Bullets categorizados:
+
+```
+**De negocio**:
+- ...
+
+**Operativos**:
+- ...
+
+**Técnicos**:
+- ...
+```
+
+Omitir sub-categorías vacías. Cada item ≤30 palabras.
+
+### `{{REFERENCIAS}}`
+
+Bullets agrupados:
+
+```
+- Decisiones documentadas: docs/decisiones/
+- Propuestas técnicas: docs/conclusiones/
+- Especificaciones: docs/especificaciones/
+- Manuales operativos: docs/manuales/
+- Informes ejecutivos: docs/funcional/
+- Scripts SQL: docs/scripts/
+- README del workspace: ./README.md (si existe)
+```
+
+V6 valida que cada path resoluble exista en filesystem; los que no existen → omitidos.
+
+## Reglas de render
+
+1. **Sin cota dura de palabras**: este doc es técnico; completitud > concisión.
+2. **Léxico**: aplica `lexico-tecnico.md` (mínimo — sólo vetar noise/jerga inventada/placeholders sin reemplazar). NO traducción ejecutiva.
+3. **Diagrama central**: el documento sin diagramas C4 (al menos Context+Container) no es válido — V1 hard-fail.
+4. **Modelo de datos**: condicional V4. Si MCP no configurado → nota inline, no placeholder vacío.
+5. **Decisiones**: condicional. Si 0 DEC → nota o sección omitida (consistente con el patrón).
+6. **Link mermaid.ink por bloque Mermaid (v1.2 — session078)**: cada bloque ```` ```mermaid ```` lleva blockquote inline debajo: `> Ver diagrama renderizado: <https://mermaid.ink/img/BASE64>`. Encoding plain base64 URL-safe del código Mermaid plano. NO aplica a workspace.dsl ni arquitectura.puml.
+7. **Idempotencia conceptual**: dos generaciones consecutivas sobre el mismo workspace producen documentos equivalentes en estructura y datos (diagramas pueden tener layout distintos por nature del render; el BASE64 del link cambia solo si cambia el código Mermaid).