@tacuchi/agent-workflow-cli 11.0.1 → 12.0.0

package/skills/agent-workflow/doctrine/refactor/references/refactor-md-template.md

@@ -1,108 +0,0 @@
-# Template REFACTOR.md — agent-workflow:refactor
-
-Artefacto canónico del skill `refactor`. Vive en `.workflow/sessions/sessionNNN-dev-refactor-<slug>/REFACTOR.md` durante la sesión.
-
-> **Modelo de artefactos (DEC-003)**: REFACTOR.md **no se gradúa con kind dedicado**. Vive en la sesión y se consulta desde ahí. Si el documento amerita preservarse, el usuario lo cura manualmente como `manual` (cómo se reorganiza el módulo) o `especificacion` (contrato del módulo nuevo). El destino al graduar respeta `workspace_mode` (DEC-002): hub mode → `<hub>/docs/<categoria>/`; project mode → `<cwd>/docs/<categoria>/`.
-
-## Estructura mínima
-
-```markdown
-# Refactor — <feature-name>
-
-## Análisis legacy
-
-### Paths involucrados
-- FE: `<repo>/src/<path>`
-- BE: `<repo>/<package-path>`
-- DB: `<schema>.<tabla>`, funciones `fn_*`, SP `sp_*`
-
-### Endpoints actuales
-| Verbo | Path | Acción | DTO request | DTO response |
-|---|---|---|---|---|
-| GET | `/api/<feature>` | listar | — | `<Feature>Response[]` |
-| POST | `/api/<feature>` | crear | `<Feature>CreateRequest` | `<Feature>Response` |
-| PUT | `/api/<feature>/{id}` | editar (full) | `<Feature>UpdateRequest` | `<Feature>Response` |
-| DELETE | `/api/<feature>/{id}` | eliminar | — | 204 |
-
-### DTOs actuales
-- `<Feature>CreateRequest`: <count> campos, todos required
-- `<Feature>UpdateRequest`: <count> campos, casi idénticos a Create
-- `<Feature>Response`: mapeo entidad
-
-### Validaciones / reglas de negocio
-- Regla 1: …
-- Regla 2: …
-
-### Accesos / roles
-- Permite roles: `admin.x`, `comercial.y`
-- Bypass super-admin: sí/no
-
-### Smells detectados (motivación del refactor)
-- DTOs Create/Update duplicados (fix: Sparse DTO unificado)
-- PUT envía toda la entidad (fix: PATCH sparse)
-- `try/catch` que silencia errores (fix: fail-fast)
-- Otros: …
-
-## Diseño nuevo
-
-### Paths nuevos
-- FE: `<repo>/src/<path>` (mismo nombre, después de rename del legacy)
-- BE: `<repo>/<package-path>` (mismo nombre, después de rename del legacy)
-
-### Endpoints nuevos
-| Verbo | Path | Acción | DTO | Cambio vs legacy |
-|---|---|---|---|---|
-| GET | `/api/<feature>` | listar | — / `<Feature>Response[]` | igual |
-| POST | `/api/<feature>` | crear | `<Feature>SaveRequest` | DTO unificado |
-| PATCH | `/api/<feature>/{id}` | editar sparse | `<Feature>SaveRequest` | PUT → PATCH; sparse |
-| DELETE | `/api/<feature>/{id}` | eliminar | — | igual |
-
-### DTOs nuevos (Sparse DTO unificado)
-- `<Feature>SaveRequest`: campos nullable, sirve para create + edit. En edit, null = no tocar.
-- `<Feature>Response`: ajustado si aplica.
-
-### Reglas FE-BE aplicadas (checklist)
-- [ ] Mismo DTO Create/Edit (Sparse).
-- [ ] PATCH para edit, sparse object.
-- [ ] BE no usa fallbacks que oculten errores; valida con Bean Validation y devuelve 400 estructurado.
-- [ ] FE propaga errores HTTP via toast/mensaje (sin `catchError(() => of([]))`).
-- [ ] DB: funciones nuevas arrancan en Phase 0 como stub (devuelven mock); implementación real en Phase 1/2.
-
-## Plan de migración (12 pasos Strangler)
-
-1. [ ] Análisis completo (esta sección + sigs.).
-2. [ ] M7 confirma estrategia de rename (auto/manual/solo-análisis).
-3. [ ] `git mv` FE: `src/.../<feature>/` → `src/.../<feature>-legacy/`.
-4. [ ] `git mv` BE: paquete `<feature>` → `<feature>_legacy` (si aplica al stack).
-5. [ ] Crear nuevo `<feature>/` en FE + BE desde cero (vacío para Phase 0).
-6. [ ] Phase 0 — Contrato: interfaces FE + DTOs BE + endpoints stub + funciones BD mock.
-7. [ ] M6 — phase-gate (Phase 0 → 1). [Nota: S7 design-review ya fue disparado antes de Phase 0 desde planning closure, v2.8+ — reemplazó a M9.]
-8. [ ] Phase 1 — Lecturas: GET, listados, filtros, combos.
-9. [ ] M6 — phase-gate (Phase 1 → 2).
-10. [ ] Phase 2 — Mutaciones: POST + PATCH (sparse) + DELETE + scripts BD reales.
-11. [ ] Validación e2e por usuario.
-12. [ ] M8 — refactor-cleanup: `git rm -r <feature>-legacy/` + REFACTOR.md `legacy_purged: true`.
-
-## Estado
-
-```yaml
-status: discovery | legacy-marked | implementing | validating | completed
-phase: 0 | 1 | 2 | done
-legacy_purged: false | true
-created: 2026-MM-DD
-last_update: 2026-MM-DD
-```
-
-## Refs
-
-- Sesión origen: `.workflow/sessions/sessionNNN-dev-refactor-<slug>/`
-- DECISIONS.md de la sesión: decisiones load-bearing del refactor.
-- `agent-workflow:prompts-catalog` M7/M8.
-- `agent-workflow:coding-standards/references/fe-be-integration.md`.
-```
-
-## Notas de uso
-
-- **Tamaño esperado**: 200-400 líneas para un mantenimiento CRUD típico. Si crece más, dividir en sub-features (cada uno con su propia sesión `## Type: refactor`).
-- **No prescribir lenguaje natural redundante**: las tablas son densas a propósito. REFACTOR.md vive en la sesión y, si amerita preservarse, se cura manualmente como `manual` o `especificacion` (DEC-003).
-- **Cuando standalone (sin sesión)**: el archivo se nombra `REFACTOR-<slug>.md` en el CWD; status queda en `discovery` y no avanza.

package/skills/agent-workflow/doctrine/refactor/references/strangler-checklist.md

@@ -1,116 +0,0 @@
-# Strangler Fig — checklist de 12 pasos para refactor
-
-Pasos canónicos del skill `agent-workflow:refactor`. Reflejan Strangler Fig (Fowler) adaptado al stack agent-workflow con flujo phased y prompts M7/M8/M6 + S7 (pre-Phase 0). M9 retirado en v2.8+ por DEC-002 de session049 — reemplazado por S7 desde planning closure.
-
-## Discovery (paso 1-2)
-
-### 1. Análisis legacy
-
-Compone con `agent-workflow:analyze-investigate`. Outputs en REFACTOR.md sección "Análisis legacy":
-
-- Paths FE / BE / DB.
-- Endpoints actuales (verbo, path, DTOs).
-- DTOs (counts, redundancias).
-- Validaciones y reglas de negocio detectadas en el código.
-- Accesos / roles.
-- Smells (DTOs duplicados, fallbacks que ocultan errores, PUT en lugar de PATCH, etc.).
-
-### 2. REFACTOR.md draft
-
-AI redacta sección "Análisis legacy" + "Diseño nuevo" + "Plan de migración" (1-12) + "Estado" inicial (`status: discovery`).
-
-Usuario revisa el draft. Si aprueba → paso 3. Si pide cambios, AI itera.
-
-## Marcar legacy (paso 3-5)
-
-### 3. M7 — refactor-legacy-detected
-
-Prompt al usuario con 3 opciones (rename + AI imports / rename + IDE imports / solo análisis). Spec literal en `agent-workflow:prompts-catalog#M7`.
-
-### 4. Rename Strangler
-
-- FE: `git mv <repo>/src/.../<feature>/ <repo>/src/.../<feature>-legacy/`.
-- BE (Spring/Java): renombrar paquete `<feature>` → `<feature>_legacy`, actualizar imports si la opción A fue elegida.
-- BD: **NO** se renombran funciones/SP — la BD es estado, no código. Las funciones nuevas se crean en paralelo durante Phase 0/1/2 con nombres canónicos.
-
-### 5. Crear `<feature>/` vacía
-
-- FE: crear `src/.../<feature>/` con módulo skeleton (NgModule vacío + service stub).
-- BE: crear paquete `<feature>` con controller stub + DTOs vacíos (Sparse DTO).
-
-REFACTOR.md → `status: legacy-marked`.
-
-## Generar TASKS.md phased (paso 6)
-
-### 6. Hand off a `implement`
-
-`refactor` genera TASKS.md con secciones canónicas:
-
-```markdown
-## Phase 0 — Contrato
-- [ ] Interfaces FE: `<Feature>Service` con métodos `list/save/delete` que arrojan "not impl"
-- [ ] DTOs BE: record `<Feature>SaveRequest` (Sparse, campos nullable)
-- [ ] Endpoints BE: `@PatchMapping` que devuelven 501
-- [ ] Funciones BD: `fn_<feature>_listar` que devuelve mock `[]::jsonb`
-- [ ] Cableado: FE llama BE → 501 capturado por handler → toast informativo
-
-## Phase 1 — Lecturas
-- [ ] GET /api/<feature> con paginación + filtros
-- [ ] FE listado con grilla, combos, search
-- [ ] Funciones BD reales para SELECT
-- [ ] Tests unitarios de queries (si aplica)
-
-## Phase 2 — Mutaciones
-- [ ] POST /api/<feature> (create con Sparse DTO)
-- [ ] PATCH /api/<feature>/{id} (edit sparse, null = no tocar)
-- [ ] DELETE /api/<feature>/{id}
-- [ ] FE formularios con validación
-- [ ] Scripts SQL: DDL/DML reales bajo `docs/scripts/`
-- [ ] Tests e2e si aplica
-```
-
-`implement` toma TASKS.md y ejecuta el loop con M6 (phase-gate Phase 1→2). S7 (design-review) fue disparado antes de Phase 0 desde planning closure de `skills/session/SKILL.md` (v2.8+ — reemplazó a M9 que disparaba post-stub).
-
-REFACTOR.md → `status: implementing`, `phase: 0`.
-
-## Validación (paso 7-8)
-
-### 7. Validación e2e
-
-Cuando `implement` cierra Phase 2, REFACTOR.md → `status: validating`.
-
-El usuario:
-- Levanta FE + BE en local.
-- Ejecuta scripts SQL contra cert.
-- Prueba flujos: create, list, filter, edit (sparse), delete.
-- Compara contra el comportamiento legacy si está disponible.
-
-Confirma con la AI: "validado, todo funciona".
-
-REFACTOR.md → `status: completed` (pero `legacy_purged: false` aún).
-
-### 8. M8 — refactor-cleanup
-
-Prompt al usuario con 3 opciones (eliminar / mantener / cancelar). Spec literal en `agent-workflow:prompts-catalog#M8`.
-
-Si elige eliminar:
-- `git rm -r <repo>/src/.../<feature>-legacy/` (FE).
-- `git rm -r <package>_legacy/` (BE) si aplica.
-- BD: si hay funciones legacy paralelas que deben removerse, generar script SQL bajo `.workflow/sessions/<sessionNNN>/scripts/cleanup-<feature>.sql` con `DROP FUNCTION IF EXISTS ...`. El bundle final se arma vía `/agent-workflow:release` (kind=`script`). **El AI NO ejecuta el script** — el usuario lo aplica.
-
-REFACTOR.md → `legacy_purged: true`.
-
-## Closure
-
-REFACTOR.md vive en la sesión (`.workflow/sessions/<folder>/REFACTOR.md`) y **no se gradúa con kind dedicado** (DEC-003). Si el documento amerita preservarse fuera de la sesión, el usuario lo cura como `manual` o `especificacion`. La sesión cierra siguiendo el flujo estándar (commits via M1, compact, session-close).
-
-## Errores y rollback
-
-| Situación | Acción |
-|---|---|
-| Phase 1 falla, lecturas no funcionan | Re-iterar Phase 1 (M6 opción 3) sin tocar legacy. Legacy sigue funcionando como referencia. |
-| Phase 2 falla, mutaciones rompen | Re-iterar Phase 2 con DECISION nueva en DECISIONS.md. Legacy sigue intacto. |
-| Validación e2e descubre regresión grave | Pausar refactor, abrir DECISIÓN documentando, decidir si seguir o rollback. NO disparar M8 cleanup. |
-| Usuario abandona el refactor a mitad de camino | REFACTOR.md mantiene `status: implementing` o `validating`; legacy sigue intacto. La sesión se puede retomar más tarde. |
-
-**Nunca** se borra el legacy hasta que M8 se confirme con `## Estado: completed` + validación e2e explícita del usuario. Esto garantiza que el rollback siempre es posible (Strangler Fig: "transform → coexist → eliminate").

package/skills/agent-workflow/doctrine/resume/SKILL.md

@@ -1,199 +0,0 @@
----
-name: resume
-description: Lee CHECKPOINT.md de la sesión activa, sintetiza placeholders si hace falta y presenta resumen de dónde quedó el trabajo. Invocado vía /agent-workflow:resume, NL como retomar/donde quedamos/continuar, o automáticamente desde el PostCompact hook tras /compact. Fallback a session-resume base si no hay checkpoint.
-version: 2.4.0
----
-
-# Resume — qtc v2.1
-
-Recupera el estado de la sesión activa después de un compact (o al volver al proyecto). Lee `.workflow/sessions/<folder>/CHECKPOINT.md` y lo presenta al usuario.
-
-## Triggers
-
-- **Slash explícito**: `/agent-workflow:resume`.
-- **NL del usuario**: "retomar", "retomemos", "donde quedamos", "continuar", "seguir con la sesión".
-- **Automático en PostCompact hook**: tras un `/compact` el hook lee el resumen y se lo pasa al AI para presentarlo.
-
-## Acción
-
-### 1. Detectar sesión(es) activa(s)
-
-```
-agent-workflow resume-summary
-```
-
-Output:
-```json
-{
-  "active_sessions": ["session046-dev-jobs-async"],
-  "primary_session": "session046-dev-jobs-async",
-  "phase_from_aw_project": "execution",
-  "branches_from_aw_project": ["mscore-solicitud-spring=feature/session046"],
-  "checkpoint_present": true,
-  "checkpoint": {
-    "actualizado": "2026-04-25 20:14",
-    "fase": "execution (2/4)",
-    "avance": "60% (3 de 5 tareas en TASKS.md completas)",
-    "proximo": ["Implementar el consumer de la cola DLQ"]
-  }
-}
-```
-
-Si `active_sessions` está vacío → "No hay sesiones activas para retomar." y stop.
-
-### 2. Síntesis post-compact (fill placeholders)
-
-Si la sesión activa tiene `checkpoint_status` en `missing`, `draft` o `stale`, ejecutar antes de presentar:
-
-1. Si `checkpoint_status: missing`: ejecutar `agent-workflow checkpoint-write --code <primary_session_code>` para regenerar el draft. Continuar con el draft recién generado.
-2. Si `checkpoint_status: draft` o `stale` (o el draft recién se regeneró): leer `checkpoint_path` y rellenar cada placeholder `_[AI: ...]_` con la mejor información disponible. Mapeo de campos:
-   - `ultimo` → 1-3 oraciones del último avance, basado en `decisiones recientes` y archivos tocados.
-   - `proximo` → 1-2 oraciones leyendo el primer ítem abierto de TASKS.md de la sesión.
-   - `archivos_proposito` → 1 línea por archivo en la lista.
-   - `contexto` → 2-3 párrafos con info mínima para retomar.
-   - `skills` → lista de skills invocadas (en post-compact suele ser solo `compact`/`resume`).
-3. Si para algún campo no hay información suficiente: escribir `_(sin info — completar al retomar)_` en lugar de inventar. Editar el archivo con la herramienta Edit.
-
-Si `checkpoint_status: complete` (o `needs_ai_action: false`): saltar este paso. Pasar directo a la presentación.
-
-Esta lógica vivía antes en el hook PostCompact (entry prompt). Quedó acá porque (a) es lógica de skill no de hook (boundary clean), y (b) Codex no soporta prompt-type en hooks → en CC se auto-dispara via /agent-workflow:resume; en Codex el usuario lo invoca manualmente.
-
-### 3. Si hay CHECKPOINT.md
-
-Leer el archivo completo:
-
-```
-agent-workflow checkpoint-read --code <CODE>
-```
-
-Presentar al usuario un resumen estructurado:
-
-```markdown
-**Sesión activa**: session046-dev-jobs-async
-**Fase**: execution (2/4) · 60% completa (3/5 tareas)
-**Última actualización**: 2026-04-25 20:14
-
-**Lo último que hicimos**: <campo del checkpoint>
-
-**Próximo paso**: <campo del checkpoint>
-
-**Decisiones recientes**:
-<lista>
-
-**Archivos tocados sin commit**:
-<lista corta>
-
-**Contexto crítico**:
-<párrafos del checkpoint>
-```
-
-Y disparar `AskUserQuestion` con spec de S5 (`../session/references/prompts-catalog.md#S5`). Header `post-compact`, 3 opciones (Retomar misma sesión / Abrir nueva sesión / Solo recapitular, después decido). **Recomendación dinámica**: el AI marca `(Recomendado)` en opción 1 si CHECKPOINT.md indica `tasks_open ≥ 1`; caso contrario marca opción 2. NO narrar la pregunta en texto plano.
-
-Resolución por opción:
-
-- **Retomar misma sesión** → cargar OBJECTIVE.md, TASKS.md, DECISIONS.md como contexto activo; verificar ramas (`agent-workflow sources`); reanudar en la fase indicada.
-- **Abrir nueva sesión** → cerrar la actual como `paused` (graduación postergada) y delegar al skill `session` con prompt de OBJECTIVE.
-- **Solo recapitular** → mantener el resumen presentado; pausar el loop y dejar que el usuario decida en próximo turno.
-- **Other auto** → instrucción custom (ej. "retomá pero salteá a la T5") — interpretar y aplicar; si ambiguo, fallback a "Solo recapitular".
-
-**Si CHECKPOINT.md ausente o ilegible**: skip S5 y fallback a `session-resume` base con soft prompt "¿Continuamos desde acá?".
-
-### 4. Si NO hay CHECKPOINT.md
-
-Fallback a:
-
-```
-agent-workflow session-resume --code <CODE>
-```
-
-Devuelve campos base (objetivo, fase, ramas, tasks counts). Presentar como resumen y preguntar si continúa.
-
-### 5. Si hay múltiples sesiones activas
-
-Listar todas con resumen 1-línea cada una y pedir al usuario seleccionar cuál retomar.
-
-### 6. Si NO hay sesiones activas — detectar cerradas con artefactos (F-E.2)
-
-Cuando `resume-summary` retorna `active_sessions: []`, re-invocar con `--include-recent-closed` para detectar sesiones cerradas en los últimos 7 días que tengan artefactos "completos":
-
-```
-agent-workflow resume-summary --include-recent-closed
-```
-
-Heurística "completos" por flow (definida en G5 de session062):
-
-| Flow | Criterio |
-|---|---|
-| `analyze` | `EVIDENCE.md` + `FINDINGS.md` + `CONCLUSIONS.md` presentes |
-| `dev` | `TASKS.md` con ≥50% closed Y `DECISIONS.md` presente |
-| `design` | `DELIVERY.md` presente |
-
-Si `recent_closed_with_artifacts.length > 0`, disparar `AskUserQuestion` con spec del S-prompt `closed-with-artifacts` (`../session/references/prompts-catalog.md#closed-with-artifacts`):
-
-- Header: `closed-with-artifacts`.
-- 4 opciones:
-  1. **Export plan** — invocar `/agent-workflow:export-plan --sessions <NNN>` con la sesión elegida.
-  2. **Export conclusions** — invocar `/agent-workflow:export-conclusions --sessions <NNN>` (solo si la sesión es analyze con CONCLUSIONS).
-  3. **Abrir nueva sesión** — delegar a `/agent-workflow:session` con prompt OBJECTIVE.
-  4. **Solo recapitular** — leer artefactos y presentar resumen, sin acción derivada.
-
-**Recomendación dinámica**: si hay 1 sola sesión analyze cerrada → opción 2 marcada `(Recomendado)`. Si hay ≥2 sesiones del mismo dominio → opción 1 marcada `(Recomendado)`. Sin ambigüedad: el AI explica brevemente la heurística antes del prompt.
-
-**Other auto** = "Otra acción" → registrar como nota informal y consultar.
-
-Si `recent_closed_with_artifacts.length == 0`: "No hay sesiones activas para retomar." y stop (comportamiento previo).
-
-## Ejemplo
-
-Usuario abre Claude Code después de un compact previo.
-
-PostCompact hook dispara → AI ejecuta `agent-workflow resume-summary` → recibe el JSON.
-
-AI presenta:
-```
-Sesión activa: session046-dev-jobs-async (execution 2/4, 60%).
-
-Última actualización: 2026-04-25 20:14.
-
-**Lo último**: Implementé el publisher de jobs con RabbitMQ — flujo end-to-end de
-encolado funciona, mensajes llegan a `qtc.jobs.priority`.
-
-**Próximo paso**: Implementar el consumer de la cola DLQ con retry exponencial.
-
-**Decisiones recientes**: DEC-003 — Usar RabbitMQ exchange `topic` (no `direct`)
-para soportar wildcards en routing keys.
-
-**Contexto crítico**: La cola principal usa publisher confirms; el consumer DLQ
-debe replicar el patrón. El test de integración corre en `mscore-jobs-test`.
-
-¿Continuamos desde el consumer DLQ?
-```
-
-Usuario: "sí" → AI carga TASKS.md, busca el item del consumer, arranca implementación.
-
-## Sandbox read-only
-
-Reglas universales en `../session/references/sandbox-readonly-rules.md` (canon agent-workflow).
-
-`resume` es read-only por diseño — los sub-comandos que invoca (`resume-summary`, `checkpoint-read`, `session-resume`) están todos en la lista plan-mode-safe. Igual, en plan mode esta skill describe en el plan file:
-
-- Qué sesión activa se detectó (output de `resume-summary`) — lectura ya ejecutada o a ejecutar.
-- Qué presentaría al usuario (resumen estructurado: fase, avance, lo último, próximo paso, decisiones, archivos sin commit, contexto crítico).
-- Qué **NO** hace: cargar OBJECTIVE.md (legacy: OBJETIVO.md) / TASKS.md / DECISIONS.md (legacy: DECISIONES.md) como contexto activo (eso es para post-aprobación del plan), ni invocar `agent-workflow sources` que también es read-only pero forma parte del "flujo activo" post-plan.
-
-## Reglas
-
-- **Una sola sesión por turno**: si hay varias activas, presentar todas pero retomar una a la vez.
-- **No asumir continuación**: siempre preguntar antes de cargar contexto profundo.
-- **CHECKPOINT.md > session-resume base**: si existe checkpoint, es la fuente de verdad. Si no, base.
-- **Branches verification**: antes de editar, correr `agent-workflow sources`.
-
-## Política — sin fallback al CLI
-
-Si `agent-workflow resume-summary`, `checkpoint-read` o `sources` falla (no está en PATH, comando no reconocido, exit code != 0), **cortá la acción y reportá al usuario**: pedile que verifique `npm install -g @tacuchi/agent-workflow-cli`. No hay flujo alternativo Python.
-
-## Recursos
-
-- `agent-workflow checkpoint-read` — lectura programática del último CHECKPOINT.md.
-- shared-contract.md §17 — formato CHECKPOINT.md.
-- **`agent-workflow:redaccion-simple`** — guía de redacción para el resumen que se presenta al retomar. Frases cortas, una idea por línea.