@tacuchi/agent-workflow-cli 6.1.0 → 7.0.0

package/skills/agent-workflow/hooks/hooks.template.json

@@ -0,0 +1,90 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh -c 'CONFIG_SRC=\"${CLAUDE_PLUGIN_ROOT}/config/agent-workflow-runtime.json\"; CONFIG_DST=\"$HOME/.workflow/agent-workflow/runtime.json\"; if [ -f \"$CONFIG_SRC\" ]; then mkdir -p \"$(dirname \"$CONFIG_DST\")\"; cp -f \"$CONFIG_SRC\" \"$CONFIG_DST\" 2>/dev/null; fi; NS_FILE=\"$HOME/.config/agent-workflow/namespace\"; mkdir -p \"$(dirname \"$NS_FILE\")\" 2>/dev/null; printf \"workflow\\n\" > \"$NS_FILE\" 2>/dev/null; exit 0'",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "agent-workflow hook branch-check",
+            "timeout": 15
+          }
+        ]
+      },
+      {
+        "matcher": "mcp__.*__execute_sql",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "agent-workflow hook sql-mutation-guard",
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "agent-workflow hook git-commit-advisor",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "agent-workflow auto-compact-on-close",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "agent-workflow checkpoint-write",
+            "statusMessage": "Escribiendo CHECKPOINT.md antes de compactar... (tip: `/agent-workflow:compact` sintetiza el resumen con contexto vivo)",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "PostCompact": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "agent-workflow resume-summary",
+            "statusMessage": "Recuperando estado tras compact...",
+            "timeout": 10
+          },
+          {
+            "type": "prompt",
+            "prompt": "Contexto compactado. El JSON anterior es output de `agent-workflow resume-summary`. Si hay `active_sessions`, invocá `/agent-workflow:resume` para sintetizar CHECKPOINT.md y presentar resumen. Si está vacío, terminá."
+          }
+        ]
+      }
+    ]
+  }
+}

package/skills/agent-workflow/references/README.md

@@ -0,0 +1,12 @@
+# references/
+
+Documentación de referencia consumida por skills universal y por la AI. Ya existente desde v6.x; se mantiene como anclaje canónico para `[[name]]` linking.
+
+Contenido (existing + esperado T2):
+
+- `*-cheatsheet.md` — atajos por familia de comandos.
+- `flow-*.md` — guías por flow (dev/design/analyze).
+- `phase-*.md` — guías por fase (planning/execution/validation/closure).
+- `lifecycle-state-machine.md` — diagrama oficial de transiciones.
+
+A diferencia de `doctrine/` (reglas activas), `references/` es documentación leída a demanda. Linkear desde doctrine/* con `[[name]]`.

package/skills/agent-workflow/references/legacy-anchors.md

@@ -0,0 +1,50 @@
+# Legacy anchors — alias permanentes `qtc:<topic>` → `agent-workflow:<topic>`
+
+Política definida en `docs/especificaciones/003-migracion-lifecycle-a-aw/MAPPING.md` §"Política de anchors": el SKILL universal expone anchors `agent-workflow:<topic>` como nombre canónico. Los anchors `qtc:<topic>` se mantienen como **aliases permanentes** dentro del SKILL universal para que CLAUDE.md / AGENTS.md / READMEs / docs históricos que referencien `qtc:*` no rompan.
+
+## Tabla de aliases
+
+| Legacy anchor | Anchor canónico | Razón |
+|---|---|---|
+| `qtc:commits-policy` | `agent-workflow:commits-policy` | doctrina universal de commit messages |
+| `qtc:sandbox-readonly` | `agent-workflow:sandbox-readonly` | plan mode read-only |
+| `qtc:mcp-readonly` | `agent-workflow:mcp-readonly` | MCP SELECT/EXPLAIN/\d only |
+| `qtc:redaccion-simple` | `agent-workflow:redaccion-simple` | estilo de prosa |
+| `qtc:coding-standards` | `agent-workflow:coding-standards` | estándares por stack |
+| `qtc:graduacion-routing` | `agent-workflow:graduacion-routing` | routing kind por hub/fuente |
+| `qtc:branch-verification` | `agent-workflow:branch-verification` | gate de rama por fuente |
+
+## Anchors de skills (agent-workflow:*)
+
+Los nombres de skill también funcionan como anchors:
+
+| Legacy | Canónico |
+|---|---|
+| `qtc:session` | `agent-workflow:session` |
+| `qtc:resume` | `agent-workflow:resume` |
+| `qtc:compact` | `agent-workflow:compact` |
+| `qtc:rules` | `agent-workflow:rules` |
+| `qtc:doctor` | `agent-workflow:doctor` |
+| `qtc:migrate` | `agent-workflow:migrate` |
+| `qtc:project-init` | `agent-workflow:project-init` |
+| `qtc:hub-init` | `agent-workflow:hub-init` |
+| `qtc:export-*` (9 commands) | `agent-workflow:export-*` |
+| `qtc:dev-workflow` / `qtc:design-workflow` / `qtc:analyze-workflow` | `agent-workflow:dev-workflow` / etc. |
+
+## Empresas que quieran shadow propios
+
+Cualquier empresa puede inyectar sus propios anchors `<empresa>:<topic>` via `profile.custom_anchors[]`:
+
+```json
+{
+  "custom_anchors": [
+    { "anchor": "acme:special-rule", "target": "profiles/anchors/acme-special-rule.md" }
+  ]
+}
+```
+
+El skill `agent-workflow:rules` los renderiza al final del bundle bajo "## Anchors específicos del profile".
+
+## Política de retiro
+
+Los aliases `qtc:*` documentados aquí son **permanentes**. No hay ventana de retiro planeada. El skill `agent-workflow:rules` los expone automáticamente cuando el profile QTC está activo (detectado via `profile.namespace === "qtc"` o cuando `profile.mcp_databases[]` contiene los nombres legacy).

package/skills/agent-workflow/references/profile-parametrization.md

@@ -0,0 +1,88 @@
+# Profile parametrization — guía para los 10 skills sensibles a empresa
+
+Este documento centraliza qué campos de `profile.json` (resuelto por `src/application/profile/profile-service.ts`) drivean el comportamiento de cada skill parametrizado.
+
+Profile cascade (de mayor a menor precedencia):
+1. Flag `--profile <path>`
+2. Env `AW_PROFILE`
+3. `~/.config/agent-workflow/profile.json` (XDG-ish, user-level)
+4. `<cwd>/.<namespace>/profile.json` (workspace-level)
+5. `DEFAULT_PROFILE` embebido (todos los campos en valores agnósticos)
+
+Schema completo en `src/application/profile/profile-service.ts:Profile`.
+
+## Skills parametrizados (10)
+
+### 5 antes-QTC (D4 ampliado — session082)
+
+#### 1. `doctrine/project-init/`
+- **Campo**: `profile.claude_md_block` (default `AW-PROJECT`; QTC profile: `QTC-PROJECT`).
+- **Behavior**: el bloque insertado en `CLAUDE.md`/`AGENTS.md` lleva el marker `<!-- <claude_md_block>-START -->` / `<!-- <claude_md_block>-END -->`.
+- **Detección legacy**: `<!-- QTC-WORKFLOW-START -->` (pre-v0.8) se detecta sin importar el profile; si presente, recomendar `/agent-workflow:migrate`.
+
+#### 2. `doctrine/hub-init/`
+- Idem `project-init` para el marker del bloque hub.
+- Adicional: detección de "modo hub vs project" sigue siendo agnóstica.
+
+#### 3. `doctrine/doctor/`
+- **Campo**: `profile.mcp_databases[]`.
+- **Behavior**: la sección "MCP connectivity check" itera sobre `profile.mcp_databases[]`. Si el array está vacío, la sección se omite ("no MCP configured, skip BD section").
+
+#### 4. `doctrine/migrate/`
+- **Campo**: `profile.migrate_legacy_rules[]`.
+- **Behavior**: la lista de reglas legacy → moderno se carga del profile. Profile QTC trae ~10 reglas (`.claude/sessions/` → `.workflow/sessions/`, ES headers → EN, `QTC-WORKFLOW` → `claude_md_block`, etc.). Profile vacío → migrate es no-op.
+- **Reglas hard-coded en el skill**: cero. Lo que migre depende 100% del profile.
+
+#### 5. `doctrine/rules/`
+- **Campo**: `profile.custom_anchors[]`.
+- **Behavior**: el bundle de anchors universales (`agent-workflow:commits-policy`, `agent-workflow:sandbox-readonly`, etc.) se renderiza siempre. Los anchors del profile se agregan al final del bundle bajo "## Anchors específicos del profile". Profile QTC inyecta `qtc:mcp-readonly` (legacy alias) automáticamente si `profile.mcp_databases[]` no está vacío.
+
+### 5 ambiguos (parametrizados por contexto)
+
+#### 6. `specialties/analyze-investigate/`
+- **Campo**: `profile.mcp_databases[]`.
+- **Behavior**: la fase "BD investigation" enumera las MCPs disponibles desde el profile. Si vacío, advierte "no MCP configured, skip BD section" y prosigue con read-only de código.
+
+#### 7. `standards/coding-standards/`
+- **Campo**: `profile.mcp_databases[]` (sección BD) + `profile.examples_path` (ejemplos override).
+- **Behavior**: sección "BD vía MCP" se renderiza dinámicamente desde el profile. Las secciones Angular/Spring/Node + FE-BE R1-R6 son agnósticas; profile.examples_path permite override de ejemplos para empresas que no usan Angular/Spring.
+
+#### 8. `exports/export-arq/`
+- **Campo**: `profile.mcp_databases[]` (paso 4 BD esquemas).
+- **Behavior**: el paso "Resolución BD" extrae esquemas iterando sobre `profile.mcp_databases[]`. C4 model conceptual es agnóstico.
+
+#### 9. `exports/export-report/`
+- **Campo**: `profile.lexicon_path` (default `null` = sin lexicon).
+- **Behavior**: si `profile.lexicon_path` apunta a un archivo, se carga como léxico empresa-específico y se aplica a la prosa del export. Profile QTC apunta a su archivo de léxico; profile vacío → no se aplica léxico.
+
+#### 10. `specialties/refactor/`
+- **Campo**: `profile.examples_path` (override de ejemplos Strangler Fig).
+- **Behavior**: la doctrina (Strangler Fig + 4 fases) es agnóstica. Los ejemplos en cada fase se cargan desde `profile.examples_path` si está definido. Profile QTC carga ejemplos QTC; profile vacío → ejemplos genéricos.
+
+## Hook adicional
+
+#### `hooks/hooks.template.json` — `sql-mutation-guard` matcher
+- **Campo**: `profile.mcp_databases[]`.
+- **Behavior**: el matcher `mcp__<db>__execute_sql` se compila dinámicamente desde el profile. Sin profile → matcher disabled, hook no se registra (skip silencioso).
+
+## Cómo cargar el profile en un skill (para devs)
+
+Patrón canónico en TypeScript:
+
+```typescript
+import { resolveProfile } from "../../application/profile/profile-service.js";
+
+const resolved = await resolveProfile(fs, env, { flagPath: args.values.get("profile") });
+if ("code" in resolved) {
+  // PROFILE_NOT_FOUND / PROFILE_INVALID_JSON / PROFILE_INVALID_SCHEMA
+  return errorResult(resolved);
+}
+const { profile, source, path } = resolved;
+// Use profile.mcp_databases, profile.claude_md_block, etc.
+```
+
+Para skills en markdown (sin código), referenciar este documento en el frontmatter o en una sección "## Profile parametrization" del SKILL.md específico.
+
+## Anchors legacy
+
+Los anchors `qtc:<topic>` se mantienen como alias permanentes en `references/legacy-anchors.md` para que CLAUDE.md históricos no rompan. Anchor canónico nuevo: `agent-workflow:<topic>`.

package/skills/agent-workflow/specialties/README.md

@@ -0,0 +1,14 @@
+# specialties/
+
+Kinds graduables al cerrar sesión. Cada specialty declara cómo se materializa el artefacto final y su routing (hub vs fuente).
+
+Contenido esperado (T2 PR2):
+
+- `decision.md` — decisión arquitectónica (hub).
+- `manual.md` — manual técnico (fuente).
+- `script.md` — script SQL/bash (fuente).
+- `especificacion.md` — spec de feature/system (hub).
+- `conclusion.md` — conclusión de analyze (hub).
+- `release.md` — release notes (fuente).
+
+Routing automático lo provee `agent-workflow graduation-routing` según `workspace_mode` y kind. Sólo estos 6 graduan al cerrar — el resto queda en sesión.

package/skills/agent-workflow/specialties/analyze-conclude/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: analyze-conclude
+description: "Produce CONCLUSIONS.md como cierre del análisis para las 3 modalidades (technical/incident/data). Una sola estructura: summary + conclusions con evidencia + recommendations con responsable + traceability. Vive en la sesión, no se gradúa por defecto. Invocado al final de execution en sesiones analyze cuando ya existe FINDINGS.md. Reemplaza a analyze-rfc, analyze-data y analyze-postmortem."
+version: 2.1.0
+---
+
+# analyze-conclude — qtc v2.1+
+
+Specialty skill **analyze**: produce el cierre del análisis para cualquier modalidad (technical / incident / data). Última fase de execution para sesiones analyze.
+
+> **v2.0+ unifica el output**: reemplaza a `analyze-rfc`, `analyze-data` y `analyze-postmortem`. Las 3 modalidades comparten una sola estructura (`CONCLUSIONS.md`) con la sección `## Modality` embebida. La diferencia entre modalidades queda en el contenido de Conclusions / Recommendations, no en archivos separados.
+
+## Cuándo se invoca
+
+- Composición desde `agent-workflow:session` al final de execution si OBJECTIVE declara `## Modality: technical|incident|data` (legacy: `## Modalidad: tecnica|incidente|datos`) y existe `FINDINGS.md` (legacy: `HALLAZGOS.md`).
+- NL del usuario: "armá las conclusiones", "cerrá el análisis", "documentá las recomendaciones", "armá la propuesta", "spec final del análisis", "armá el post-mortem", "armá el informe".
+
+## Acción
+
+Producir `.workflow/sessions/<folder>/CONCLUSIONS.md` con la estructura canónica única.
+
+### Estructura canónica de CONCLUSIONS.md
+
+```markdown
+# Conclusions — sessionNNN-analyze-<slug>
+
+## Modality
+
+<technical | incident | data>
+
+## Summary
+
+[1-3 oraciones: qué se investigó, qué se concluyó, qué hacer al respecto.]
+
+## Conclusions
+
+- **C1**: <conclusión + link a evidencia (`EVIDENCE.md#section` o `FINDINGS.md#patron`)>
+- **C2**: <conclusión + evidencia>
+- **C3**: ...
+
+## Recommendations
+
+- **R1**: <acción concreta + responsable + cuándo (fecha objetivo o ventana)>
+- **R2**: <acción + responsable + cuándo>
+- **R3**: ...
+
+## Traceability
+
+- EVIDENCE: `.workflow/sessions/<folder>/EVIDENCE.md`
+- FINDINGS: `.workflow/sessions/<folder>/FINDINGS.md`
+- queries/: lista de archivos si aplica
+- Decisiones derivadas: <DEC-NNN si aplica> (en DECISIONS.md de la sesión)
+
+## Open (gaps)  [opcional]
+
+- <pregunta sin respuesta que requiere más investigación>
+- <hipótesis sin probar>
+```
+
+### Reglas comunes a las 3 modalidades
+
+- **Conclusions con evidencia**: cada `**CN**` enlaza al artefacto que lo sustenta (EVIDENCE o FINDINGS). Sin evidencia no se afirma.
+- **Recommendations accionables**: cada `**RN**` declara responsable (persona/equipo, no "alguien") y cuándo (fecha objetivo o ventana, no "pronto").
+- **Sin código de implementación**: el documento describe QUÉ hacer, no CÓMO. La implementación es de flow=dev (otra sesión, vía handoff `--from analyze:NNN`).
+- **Honest gaps**: si quedan preguntas sin responder, va `## Open (gaps)`. No esconder debilidades del análisis.
+- **Modality embebida**: la sección `## Modality` declara el sabor (technical / incident / data). El contenido del cuerpo se modula por modalidad pero la estructura no cambia.
+
+## Modulación por modalidad
+
+La estructura es única. Lo que cambia es el peso y el contenido de cada sección.
+
+### Modality: technical (propuesta tradicional)
+
+- **Summary**: qué decisión técnica se recomienda y por qué.
+- **Conclusions**: opciones evaluadas con tradeoffs (pros/cons/costo S/M/L). Cada CN puede ser una opción descartada con su razón o la opción recomendada con su justificación.
+- **Recommendations**: típicamente una `**R1**` que describe la decisión final + acciones de seguimiento (handoff a dev, ajustes de doctrina).
+- **Open**: dependencias externas, decisiones que dependen de otra sesión.
+
+Reglas específicas:
+- **3 opciones es óptimo**: si el espacio es claro, 2 alcanza. Si hay ambigüedad alta, hasta 4. Más es ruido.
+- **Tradeoffs explícitos**: nunca "ventaja: bueno". Cada Pro/Con específico.
+- **Costo estimado obligatorio**: S/M/L de implementación.
+- **Decisión recomendada con justificación**: no presentar opciones sin elegir. Si genuinamente no hay una mejor, declararlo y describir cómo decidir (ej. "depende de tolerancia a downtime: A si 0, B si <1h").
+
+### Modality: incident (post-mortem tradicional)
+
+- **Summary**: qué pasó, cuándo, impacto, causa raíz, qué se hizo. Incluir severidad declarada (SEV1/2/3/4) con justificación de 1 línea.
+- **Conclusions**: timeline (`**C1**`: timeline), causa raíz (`**C2**`: causa raíz), impacto cuantificado (`**C3**`: impacto), lo que funcionó / no funcionó (`**C4**`/`**C5**`).
+- **Recommendations**: acciones inmediatas hechas (`**R1**`), acciones preventivas con owner + fecha (`**R2**`/`**R3**`/...). Priorizar P1 = bloqueo de SEV similar futuro; P2 = reduce probabilidad; P3 = mejora detección/respuesta.
+- **Open**: lecciones aprendidas pendientes de socializar.
+
+Reglas específicas:
+- **Sin culpas**: foco en sistemas y procesos, no personas. "El deploy no tenía smoke test" > "Juan deployó sin testear".
+- **Timeline en hora local + UTC si cross-timezone**.
+- **Acciones preventivas con owner + fecha**: vagueness mata follow-up.
+- **Honest about gaps**: si no se sabe la causa raíz exacta, decirlo.
+
+Para detalles de severidad, impacto cuantitativo y timeline de comunicación, ver `references/incident-classification.md`.
+
+### Modality: data (informe de análisis)
+
+- **Summary**: qué se midió, qué se encontró, qué hacer al respecto.
+- **Conclusions**: hallazgos numéricos con valor + comparación + tendencia (`**C1**`: métrica X = ..., +33% vs período anterior, link a query). Interpretación en contexto del negocio.
+- **Recommendations**: acciones SUGERIDAS basadas en los datos (técnicas, de producto/proceso, investigación adicional).
+- **Traceability**: agregar `queries/*.sql` con cada métrica enlazada a la query que la produjo.
+- **Open**: limitaciones del análisis (sample size, sesgos conocidos, datos faltantes).
+
+Reglas específicas:
+- **Números siempre con unidad y contexto**: "2.4M" sin más es ruido; "2.4M solicitudes en Q1 2026 (vs 1.8M Q4 2025, +33%)" tiene contenido.
+- **Citar queries**: cada métrica enlaza a la query que la produjo. Reproducibilidad.
+- **Metodología documentada**: tamaño de muestra, ventana, manejo de nulos, outliers, tests de hipótesis si aplican. Sin metodología los números son indefendibles.
+- **Limitaciones honestas**: si hay sample bias, datos faltantes, ventana corta, decirlo en `## Open`.
+- **Acciones SUGERIDAS, no ordenadas**: el informe propone; el usuario/equipo decide qué accionar.
+
+#### Metodología estadística (modality=data)
+
+Decisiones metodológicas que el documento debe declarar al elegir modality=data:
+
+- **Tamaño de muestra**: `n = X (universo|sample, ventana <fecha>–<fecha>)`. Para sampling: `n ≥ 384` para 95% confianza, ±5% margen sobre proporción 0.5 (peor caso).
+- **Intervalos de confianza**: default 95%. Reportar como `valor ± margen` o `[lower, upper]`. Wilson/Clopper-Pearson para proporciones; t-Student si n<30; Poisson exact CI para conteos.
+- **Manejo de nulos**: excluir (<5% sin bias), imputar (<15% con justificación), reportar separado (≥15% o estado-nulo informativo), o bloquear análisis si invalida conclusiones.
+- **Outliers**: IQR (default), z-score (normal), percentil 1/99 (robustez), o domain rule. Reportar cuántos hay y su impacto.
+- **Tests de hipótesis** (opcional): H0/H1 explícitas, p-value + tamaño de efecto, α=0.05 default, Bonferroni si múltiples comparaciones.
+
+## Loop de iteración
+
+1. Primer draft de CONCLUSIONS.md.
+2. Mostrar al usuario.
+3. Iterar (Edit, no recreación) hasta que el usuario confirme: "OK, lo dejo así".
+
+## Cierre y graduación
+
+**Default: no graduar.** CONCLUSIONS.md vive en la sesión (`.workflow/sessions/<folder>/CONCLUSIONS.md`). La sesión cierra y el artefacto queda como referencia consultable; las recommendations accionables se ejecutan vía sesiones de handoff (`--from analyze:NNN`) o quedan en backlog informal.
+
+**Si el usuario pide graduarlo explícitamente**: usar `kind = conclusion` (uno de los 6 kinds del modelo nuevo):
+
+```
+agent-workflow graduate --kind conclusion --session <CODE> --slug <kebab>
+```
+
+Destino:
+- **workspace_mode=hub** → `<hub>/docs/conclusiones/NNN-<slug>.md`.
+- **workspace_mode=project** → `<project>/docs/conclusiones/NNN-<slug>.md`.
+
+La regla canónica DEC-002 manda destino sin prompt por sesión: hub mode → hub root; project mode → cwd. Sin override.
+
+Sugerir handoff post-cierre: `/agent-workflow:session --from analyze:NNN "<acción de implementación>"`.
+
+> Regla canónica de routing: `agent-workflow/skills/session/references/graduacion-routing.md`.
+
+## Composición con otras skills
+
+| Skill | Cuándo |
+|---|---|
+| `analyze-synthesize` | pre-requisito (FINDINGS.md debe existir) |
+| `analyze-investigate` | si surge nueva pregunta durante el cierre, retroceder con queries adicionales |
+| `agent-workflow:session --from analyze:NNN` | post-cierre, para implementar acciones |
+
+## Sandbox read-only
+
+Reglas universales en `../session/references/sandbox-readonly-rules.md`. En plan mode esta skill describe en el plan file:
+
+- **Path destino**: `.workflow/sessions/<folder>/CONCLUSIONS.md`.
+- **Modality declarada** en OBJECTIVE (`technical`/`incident`/`data` requerido; legacy ES `tecnica`/`incidente`/`datos` se normaliza). Si falta o es otra, plan dice "preguntar al usuario".
+- **Esqueleto de CONCLUSIONS.md**: secciones canónicas (Modality, Summary, Conclusions, Recommendations, Traceability, Open opcional). Modulación según modalidad.
+- **Investigación previa requerida**: si hay sub-preguntas pendientes en FINDINGS, listar para que el usuario decida si invoca `analyze-investigate` antes.
+
+NO ejecuta: `Write` sobre CONCLUSIONS.md, queries MCP costosas (>10k filas estimadas), `agent-workflow graduate`.
+
+## Recursos
+
+- **`references/incident-classification.md`** — severidad SEV1/2/3/4, impacto cuantitativo, timeline de comunicación, trazabilidad de acciones (aplica a modality=incident).
+- shared-contract §10 — handoff `--from analyze:NNN`.
+- shared-contract §11 — convención `## Modality`.
+- shared-contract §14 — fase execution del lifecycle universal.

package/skills/agent-workflow/specialties/analyze-conclude/references/incident-classification.md

@@ -0,0 +1,61 @@
+# Clasificación del incidente — severidad, impacto, comunicación
+
+Aplica a `analyze-conclude` con `## Modality: incident` (legacy: `## Modalidad: incidente`). Toda CONCLUSIONS.md de incidente debe declarar severidad, impacto cliente cuantificado y timeline de comunicación. Sin estos campos, las conclusiones son incompletas.
+
+## Severidad
+
+| Nivel | Criterio | Ejemplos | Comunicación esperada |
+|---|---|---|---|
+| **SEV1** | Crítico — sistema o flujo principal caído >1h, datos comprometidos, multas regulatorias | Login down >1h, BD principal corrupta, leak de PII | Status page + email a clientes + regulador (si aplica) en <30 min de detección |
+| **SEV2** | Degradado — feature secundaria caída, flujo principal degradado >15min y <1h | Latencia 5x normal en endpoint clave, una región caída | Status page + Slack interno; email cliente si dura >30 min |
+| **SEV3** | Limitado — afecta <10% usuarios o feature no-crítica | Bug en pantalla específica, error intermitente bajo volumen | Slack interno; sin comunicación externa salvo cliente afectado pregunte |
+| **SEV4** | Cosmético / interno — sin impacto en producción visible | Job batch atrasado pero recuperable, alerta interna falsa | Solo Slack del equipo; no requiere post-mortem formal salvo aprendizaje notable |
+
+Declarar la severidad en el **Resumen** y justificar en una línea: "SEV2 — flujo de pago degradado 35 min para 8% de usuarios".
+
+## Impacto cliente — cuantitativo
+
+Cada CONCLUSIONS.md de incidente documenta dentro de **Conclusiones** una `**CN**: Impacto` con las siguientes magnitudes (si no aplica una, decir "no aplica"; nunca dejar vacío):
+
+| Métrica | Cómo cuantificar |
+|---|---|
+| **Duración total** | Desde primer evento hasta servicio restaurado (no desde detección — el cliente sintió desde el primer evento) |
+| **Usuarios afectados** | Número absoluto (preferido) o estimación con metodología clara (ej. "5% de usuarios activos del día = ~12k") |
+| **Transacciones impactadas** | Perdidas, duplicadas, en estado inconsistente — separadas. Cantidad + valor monetario si aplica |
+| **Datos comprometidos** | Sí/no/qué tipo. Si sí, declarar acción de notificación regulatoria |
+| **Costo financiero** | Refunds, créditos, penalidades, costo de remediación. Estimación con rango si no es preciso |
+| **Reputación / soporte** | Tickets abiertos relacionados, menciones en redes, NPS si se mide |
+
+Si los datos no están disponibles inmediatamente, CONCLUSIONS.md **declara** que se actualizará con números finales en una fecha objetivo.
+
+## Timeline de comunicación
+
+Bloque obligatorio dentro de la conclusión `**CN**: Timeline` — registra **cuándo y a quién** se comunicó:
+
+| Evento | Canal | Audiencia | Hora (UTC) | Quién |
+|---|---|---|---|---|
+| Detección interna | Slack #incidents | Equipo on-call | HH:MM | sistema/persona |
+| Activación incident commander | Llamada/Slack | Equipo extendido | HH:MM | IC asignado |
+| Primer aviso interno | Slack #general | Toda la org | HH:MM | IC |
+| Primer aviso externo | Status page | Clientes | HH:MM | Comms / IC |
+| Aviso regulador (SEV1 con datos) | Email/portal regulatorio | <ente> | HH:MM | Compliance |
+| Resolución comunicada externamente | Status page + email | Clientes | HH:MM | Comms |
+| Post-mortem público (si compromete confianza) | Blog/email | Clientes | YYYY-MM-DD | Comms |
+
+### Reglas de comunicación
+
+- **SEV1**: status page actualizada cada 30 min hasta resolución. Cliente dueño de los datos comprometidos contactado directamente <2h.
+- **SEV2**: status page actualizada al menos 2 veces (inicio + resolución). Email a clientes si dura >30 min.
+- **SEV3**: Slack interno + ticket si cliente lo reporta. Sin proactivo externo.
+- **Honestidad**: no minimizar en comunicación pública. "Estamos investigando un incidente que afecta a algunos usuarios" es preferible a silencio o promesas vacías.
+
+## Trazabilidad de acciones
+
+Cada `**RN**` (Recomendación) preventiva cumple:
+
+- **Owner nombrado** (persona o equipo, no "alguien").
+- **Fecha objetivo** en formato YYYY-MM-DD.
+- **Criterio de "hecho"** medible (ej. "alerta dispara con dataset de prueba" no "mejorar alerting").
+- **Priorizada**: P1 = bloqueo de SEV similar futuro; P2 = reduce probabilidad; P3 = mejora detección/respuesta.
+
+CONCLUSIONS.md de incidente se considera **cerrable** sólo cuando todas las recomendaciones P1 tienen owner y fecha.

package/skills/agent-workflow/specialties/analyze-investigate/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: analyze-investigate
+description: Recolección de evidencia divergente sin juicio. Lee código, corre queries read-only contra <mcp-cert>/<mcp-prod> (MCPs), tracea logs, cava git history. Produce EVIDENCE.md + queries/. Invocado en execution de sesiones analyze (cualquier modalidad). Pre-requisito de analyze-synthesize en analyze sessions.
+version: 1.2.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.
+
+# analyze-investigate — qtc v1.1+
+
+Specialty skill **analyze**: investigación divergente. Primer paso de `execution` para sesiones analyze (cualquier modalidad). **Read-only**.
+
+## Rama base — verificar antes de leer/queries
+
+Antes de lecturas extensivas o queries (`Grep`, `Read`, MCP `<mcp-cert>`/`<mcp-prod>`), confirmar que cada fuente está en su `main_branch` (default `certificacion`). El análisis sobre otra rama puede divergir de producción y producir conclusiones erradas.
+
+- El lifecycle ya valida esto al entrar a execution (skill `session`, bloque "Verificación interactiva de ramas"). Si no se ejecutó, correr `agent-workflow sources` antes de la primera evidencia.
+- Si una fuente está en otra rama, **avisar** explícitamente en `EVIDENCE.md` que el análisis se hizo sobre `<current_branch>` y aclarar el riesgo de divergencia.
+- Para decidir editar código durante la investigación, ver Caso C en `../session/references/branch-verification.md` (no aplica a este skill — es read-only).
+
+## Cuándo se invoca
+
+- Composición desde `agent-workflow:session` en `execution` cuando es sesión `analyze` y todavía no existe `EVIDENCE.md` (legacy: `EVIDENCIA.md`).
+- NL: "investigá", "buscar evidencia", "qué dice el código sobre X", "corré la query".
+- Devuelta por `specialty-choose --phase execution` cuando OBJECTIVE menciona análisis/investigación/propuesta/post-mortem.
+
+## Acción
+
+Producir `.workflow/sessions/<folder>/EVIDENCE.md` + opcionalmente `queries/*.sql`.
+
+### Estructura de EVIDENCE.md
+
+```markdown
+# Evidence — sessionNNN-analyze-<slug>
+
+## Original question
+
+[Copiar `## Question` del OBJECTIVE.md.]
+
+## Sources consulted
+
+- Código: <repo+path/file.java líneas X-Y>
+- Logs: <archivo o sistema>
+- BD (<mcp-cert> / <mcp-prod>): <queries en queries/>
+- Git history: <commits relevantes con SHA y fecha>
+- Refs externas: <links si aplica>
+
+## Raw finding 1: <título>
+
+- **Qué se observó**: ...
+- **Dónde**: <link/path>
+- **Cuándo**: <fecha si aplica>
+
+## Raw finding 2: ...
+
+## Notes / tentative hypotheses
+
+- [hipótesis sin compromiso, para revisar en analyze-synthesize]
+```
+
+### Lectura estructurada del OBJECTIVE
+
+Para extraer la pregunta original sin leer todo el archivo:
+
+```
+agent-workflow objetivo-data --code <CODE>
+```
+
+Devuelve `{titulo, tipo, modalidad, brief, criterios_aceptacion, fuentes_mencionadas, origen}`. El `brief` aplica como "Original question" para sesiones analyze. El comando lee tanto `OBJECTIVE.md` (canónico EN) como `OBJETIVO.md` (legacy ES) vía bilingual readers de R1.
+
+### Reglas para queries (modalidad=datos o tecnica con datos)
+
+- **Read-only siempre**: SELECT, no DML. Los MCP servers `<mcp-cert>` y `<mcp-prod>` lo enforcan a nivel server.
+- **Guardar en `.workflow/sessions/<folder>/queries/NNN-<slug>.sql`** con header:
+  ```sql
+  -- Query: <propósito>
+  -- Server: <mcp-cert> | <mcp-prod>
+  -- Fecha: 2026-04-26
+  -- Sesión: sessionNNN-analyze-<slug>
+  -- Costo estimado: <filas|N/A>; índices usados: <lista|none>
+  ```
+- **Numerar secuencialmente** por orden de ejecución.
+- **Resultado resumido en EVIDENCE.md**, no el dump completo (puede ser MB).
+
+### Cost guard — antes de ejecutar (v1.1+)
+
+Las queries contra `<mcp-cert>` / `<mcp-prod>` tienen costo real (latencia, I/O, hold de conexión). Aplicar el cost guard antes de cualquier query no-trivial.
+
+**Resumen de categorías**:
+- **Barata**: COUNT(*) ≤ 1.000 filas o PK lookup → ejecutar directo.
+- **Moderada**: 1.000-10.000 filas o seq scan sobre tabla pequeña → avisar al usuario tamaño + duración estimada antes.
+- **Costosa**: > 10.000 filas o seq scan sobre >100k → **confirmación explícita** del usuario antes.
+- **Bloqueada**: UPDATE/INSERT/DELETE → refusarse.
+
+Procedimiento completo (4 pasos: estimar tamaño con COUNT(*) + EXPLAIN; clasificar; aviso al usuario con formatos exactos; registrar costo real en header) + excepciones permitidas + anti-patrones en **`references/cost-guard.md`**.
+
+### Reglas para lectura de código
+
+- Usar `Grep` y `Read` extensivamente. NUNCA `Edit/Write` durante investigate (read-only).
+- Citar paths con líneas: `mscore-solicitud-spring/src/main/java/.../Foo.java:142`.
+- Si el código está disperso, usar `Glob` + `Grep` para zoom.
+
+### Reglas para logs y git history
+
+- Logs: si hay acceso (SSH o herramienta del proyecto), describir la query/comando. Capturar timestamps relevantes.
+- Git: `git log --oneline --since="<fecha>" -- <path>` para acotar. Capturar SHA + fecha + autor + mensaje. Si modalidad=incidente, capturar commit "culpable" destacado.
+- **Solo git read-only**: `log`, `show`, `diff`, `blame`, `branch --show-current`. NUNCA ejecutar `git commit`/`push`/`merge`/`rebase`/`tag`/`reset --hard`/`checkout` durante investigate. Ver `agent-workflow:commits-policy`.
+
+## Loop de investigación
+
+```
+[hipótesis] → [buscar evidencia] → [actualizar EVIDENCE.md] → [nueva hipótesis o convergencia]
+                                           ↓
+                                  [→ analyze-synthesize cuando hay suficiente]
+```
+
+Iterar hasta material suficiente para sintetizar.
+
+## Reglas
+
+- **NO juzgar durante investigate**: capturar lo que es, no lo que "debería ser". El juicio viene en `analyze-synthesize`.
+- **Sin escribir código**: read-only. NUNCA Edit/Write durante investigate.
+- **Honest about gaps**: si una fuente no está disponible, declararlo en EVIDENCE.
+- **Sospechar de la pregunta original**: si surge evidencia que sugiere que la pregunta del OBJECTIVE está mal formulada, marcarlo en "Notes / tentative hypotheses".
+
+## Composición con otras skills
+
+| Skill | Cuándo |
+|---|---|
+| `analyze-synthesize` | siguiente paso una vez EVIDENCE tiene material suficiente |
+| `analyze-conclude` | después de synthesize, produce CONCLUSIONS.md modulado por modalidad (technical/incident/data) |
+
+## Sandbox read-only
+
+`../session/references/sandbox-readonly-rules.md` (canon). En plan mode describe en el plan file:
+
+- **Paths destino**: `.workflow/sessions/<folder>/EVIDENCE.md` + `queries/*.sql`.
+- **Fuentes a consultar**: archivos de código (paths), tablas BD (schema + nombre), logs/dashboards (con ventanas), git history.
+- **Queries propuestas**: lista con SELECT + tabla + ventana + costo estimado. Marcar costosas para que decida el usuario.
+- **Estructura de EVIDENCE.md**: hallazgos crudos sin sintetizar.
+
+NO ejecuta: queries MCP (aunque sean read-only — respetar plan mode), `Read` está permitido pero limitado a navegación, `Write` sobre EVIDENCE.md o queries/.
+
+## Recursos
+
+- **`references/cost-guard.md`** — protocolo completo de cost guard (4 pasos + excepciones + anti-patrones).
+- MCP servers `<mcp-cert>` y `<mcp-prod>` — read-only por server config.
+- shared-contract §14 — fase execution del lifecycle universal.