@tacuchi/agent-workflow-cli 11.0.1 → 12.0.0

package/skills/w/loops/plan-exec-loop/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: plan-exec-loop
+description: >-
+  Ejecuta un plan de implementación (docs/plans/PPP-plan.md) como living doc: lo
+  lee y actualiza fase a fase mientras edita el código real, gestiona BD y git.
+  Heir del chasis spec-refine-loop: reusa su motor gap-driven (aplicado dentro
+  de una tarea ante decisiones/dudas no obvias), research on-demand con regla BD
+  read-only, AskUserQuestion con ≤3 tabs de contenido + 1 tab flow
+  (Compactar/Cerrar) siempre, y compact/resume con Cerrar que persiste CHECKPOINT
+  + BACKLOG. Sus deltas: una exec session por fase (resume intra-fase); git
+  seguro (verifica rama esperada antes de editar, propone commits por fuente,
+  nunca push/--amend/--no-verify); la IA NUNCA ejecuta DML/DDL (migraciones se
+  redactan en SCRIPTS.sql, solo read-only se ejecuta); validación por fase y
+  final (lo dependiente de migración no aplicada se difiere como handoff a DBA);
+  y SIN auto-export (escribe solo docs/plans + docs/tools; el resto queda como
+  artefacto de session para export-*). Compone git, coding-standards, testing,
+  tools y sql. Lo arranca /w:plan-exec y es reanudable. Invocar para implementar
+  un plan ya generado.
+---
+
+# plan-exec-loop
+
+> **Heir** del chasis [`spec-refine-loop`](../spec-refine-loop/SKILL.md). Aquí los **deltas de ejecución** — el trabajo real: código, BD, git. El motor (gap-driven, research on-demand, AskUserQuestion + tab `flow`, compact/resume, `Cerrar` persiste) vive en el chasis.
+
+## Flow
+PLANIFICATION
+
+## Layer
+2 — la IA lo corre entero.
+
+## Started by
+`/w:plan-exec` — **reanudable** (mismo mecanismo de 4 casos del chasis; aquí con resume intra-fase, ver Delta 1).
+
+## Reads
+`docs/plans/PPP-plan.md`
+
+## Writes
+- `docs/plans/PPP-plan.md` (**read/update**, living doc: estado de fases/tareas, `Open questions`).
+- `docs/tools/`: herramientas/utilidades reusables que la IA **crea** durante la ejecución (salida directa, no export).
+- Artefactos de exec session en `.workflow/sessions/` (`SCRIPTS.sql`, `DECISION`, …).
+- **NO** escribe en otras carpetas `docs/` ni **gradúa/exporta** otros artefactos automáticamente (ver *Boundary*).
+
+## Boundary — sin auto-export (hard rule)
+
+Este loop **nunca gradúa/promueve artefactos** a `docs/`. Las únicas carpetas `docs/` que escribe son **`docs/plans`** (el plan, living) y **`docs/tools`** (las herramientas que crea — salida directa, no un export). Todo lo demás (migraciones → `docs/scripts`, manuales → `docs/manuals`, diagramas → `docs/diagrams`, etc.) lo hacen skills **`export-*`** aparte, como paso explícito posterior. Los artefactos quedan en sus sessions hasta entonces.
+
+## Inherits
+
+Del chasis [`spec-refine-loop`](../spec-refine-loop/SKILL.md), sin cambios:
+
+- Motor **gap-driven** (aplica *dentro de una tarea* ante una decisión/duda no obvia: research session ó AskUserQuestion).
+- **AskUserQuestion**: ≤3 contenido + 1 `flow` (`Compactar`/`Cerrar`) siempre.
+- **research session** on-demand + **regla BD** read-only (pregunta MCP si >1 sin default → `SCRIPTS.sql` → ejecuta read-only) + research **inconclusa** (degrada/difiere, límite `MAX`).
+- **Compact/resume**; **`Cerrar` persiste** `CHECKPOINT` + `BACKLOG`.
+
+## Composes
+
+`git` (rama segura + commits propuestos) · `coding-standards` (cambio mínimo, estilo de la fuente) · `testing` (validación) · `tools` (herramientas reusables → `docs/tools`) · `sql` (regla BD) · `writing`. Todas resueltas por `.workflow/skills.toml`; `off` → el loop sigue sin la capacidad y, si era necesaria, lo dice o pregunta.
+
+## Internal sessions (managed)
+
+- **control session** `<plan>-plan-exec`: dueña del run (`SESSION` + `CHECKPOINT` + `BACKLOG` al cerrar; Type = `control`).
+- **exec session por fase** `<plan>-exec-phase-<N>`: `SESSION` · `DECISION` · `SCRIPTS.sql` · `CHECKPOINT` (Type = `exec`).
+- **research session** `<plan>-research-*`: on-demand (run-and-close), igual que el chasis.
+
+## Delta 1 — **One exec session per phase** (+ resume intra-fase)
+
+- Recorre las `Phases` del plan en orden (respeta deps).
+- Por cada Phase no completada → `create_or_resume(<plan>-exec-phase-<N>)` (**reusa** la session si la fase quedó a medias; no crea una segunda).
+- Ejecuta las `Tasks` de la fase; **salta** las ya marcadas `- [x]` en el plan (el plan-doc es la fuente de verdad por tarea). Marca `- [x]` + estado **en el plan** (living doc; no en un `TASKS` aparte).
+- Registra `DECISION` solo lo **no obvio**.
+
+## Delta 2 — Git policy: **rama segura + commits propuestos**
+
+- **Antes de editar** archivos de una fuente: verifica rama actual = rama esperada de esa fuente (estilo `branch-check`). Si no coincide → **pausa y resuelve con el humano**; nunca `stash`/`reset --hard`/`checkout -- .`/`clean` sin confirmación por fuente.
+- **Al cerrar una fase** (o al `Cerrar`): **propone commits por fuente** (propose-then-execute, aprobar antes); nunca `push`/`--amend`/`--no-verify`.
+- **Commit rechazado**: los cambios **quedan en el working tree** (no se revierten). Se permite reproponer / editar mensaje. Se registra en `CHECKPOINT` + `BACKLOG` que la fase quedó **sin commitear** (reanudable).
+- **Precondición entre fases**: `branch-check` valida *identidad* de rama, **no** *limpieza* del working tree. Antes de iniciar la exec session de la siguiente fase, el working tree de cada fuente debe estar **limpio** (committeado) o explícitamente **reconocido** como "cambios sin commitear de la fase N" — para no co-mezclar dos fases en un mismo commit.
+
+## Delta 3 — DB policy: **la IA nunca ejecuta DML**
+
+Distinción por **ejecución**, no por archivo (ver el esquema `SCRIPTS.sql`):
+
+- **Consultas read-only** (diagnóstico/validación) → `SCRIPTS.sql` (artefacto de la session); la IA **sí** las ejecuta read-only vía MCP (`sql-mutation-guard`).
+- **Migraciones DDL/DML** (cambios de esquema/datos) → la IA las **redacta en `SCRIPTS.sql`** (artefacto de la session) pero **NUNCA las ejecuta**.
+
+> El SQL mutante **queda en la session**, no se mueve a `docs/`. Su promoción a `docs/scripts/` (forward + rollback) la hace un `export-*` **aparte**, no este loop.
+
+## Delta 4 — Validation
+
+- Tras ejecutar (por fase y al final): corre tests/checks contra `Validations` + `Final behavior` + acceptance/success criteria del spec.
+- Validación que **corre y falla** → vuelve a la tarea (gap); no avanza.
+- **Validación dependiente de una migración no aplicada**: como la IA no ejecuta el DML, **no puede correr read-only** → se **difiere** (handoff a DBA), **no bloquea el avance**. Se registra en `Open questions` del plan + `BACKLOG`, marcando "verificación pendiente tras aplicar SQL". (Reusa el patrón degradar/diferir + límite `MAX` del chasis → evita el bucle "vuelve a la tarea".)
+
+## Delta 5 — Completitud / cierre
+
+- Una fase cierra **done** cuando sus tareas están `- [x]` y su validación pasó **o** quedó diferida (handoff de SQL). Estado posible: **"done — SQL pendiente de aplicar"**.
+- Todas las fases done → `AskUserQuestion` final (contenido: `Marcar plan done` / `Preguntar algo más`; flow: `Compactar`/`Cerrar`).
+- **Sin export automático**: los artefactos (`SCRIPTS.sql`, `DECISION`, …) quedan en sus sessions. Promoverlos a `docs/` (scripts, manuals, …) es un paso aparte vía `export-*`.
+
+## Sequence
+
+```
+plan-exec-loop(PPP-plan.md):
+  control = create_or_resume(<plan>-plan-exec)             # CHECKPOINT, resume
+  plan = read(PPP-plan.md)
+  para cada Phase en plan (en orden, respeta deps):
+    si Phase done: skip
+    es = create_or_resume(<plan>-exec-phase-<N>)           # reusa si quedó a medias
+    para cada Task de la Phase:
+      si Task - [x] en el plan: skip                       # resume intra-fase
+      verificar rama esperada por fuente (branch-check)
+        si no coincide → pausar + resolver con humano
+      ejecutar Task:
+        editar código en las fuentes (cambio mínimo)
+        si crea herramienta/utilidad reusable → docs/tools (salida directa)
+        si consulta BD read-only → SCRIPTS.sql + ejecutar read-only
+        si cambio BD (DDL/DML) → redactar en SCRIPTS.sql (artefacto session, NO ejecutar)
+        si decisión no obvia → DECISION
+        si duda/gap → research session ó AskUserQuestion   # chasis
+      marcar Task - [x] + estado EN EL PLAN
+    validación de la fase:
+        la que corre y falla → volver a la tarea
+        la dependiente de migración no aplicada → diferir (Open questions + BACKLOG)
+    proponer commit(s) por fuente (aprobar antes)          # nunca push/amend/--no-verify
+        si rechazado → cambios quedan; registrar "fase sin commitear"
+    precondición siguiente fase: working tree limpio o reconocido
+    es.close_and_report()
+  validación final (lo que se pueda; lo dependiente de SQL queda como handoff)
+  AskUserQuestion(contenido: [Marcar plan done, Preguntar algo más], flow: [Compactar, Cerrar])
+  marcar plan done (o "done — SQL pendiente de aplicar")
+  # NO export: los artefactos quedan en sessions; un export-* los promueve aparte
+finalize: CHECKPOINT + BACKLOG + cerrar sessions + reportar
+```
+
+```mermaid
+flowchart TD
+    S["create_or_resume control session<br/>read PPP-plan.md"] --> P{"¿más Phases<br/>(no done)?"}
+    P -->|no| V2["validación final<br/>(dep. de SQL → handoff)"]
+    P -->|sí| ES["create_or_resume exec session (Phase N)"]
+    ES --> T{"¿Task pendiente<br/>(no - [x])?"}
+    T -->|sí| G["branch-check por fuente"]
+    G -->|rama ok| DO["editar código · read-only→SCRIPTS.sql<br/>migración DDL/DML→SCRIPTS.sql (no ejecuta) · DECISION"]
+    G -->|rama ≠| PA["pausar + resolver con humano"]
+    PA --> G
+    DO --> MK["marcar Task - [x] en el PLAN"]
+    MK --> T
+    T -->|no| VP["validación de fase<br/>(falla→tarea · dep. SQL→diferir)"]
+    VP --> CM["proponer commits por fuente"]
+    CM -->|aprobado| CL["cerrar exec session + reportar"]
+    CM -->|rechazado| RJ["cambios quedan · registrar 'sin commitear'"]
+    RJ --> CL
+    CL --> P
+    V2 --> FIN["AskUserQuestion[Marcar plan done · Preguntar más]<br/>plan done (sin auto-export)"]
+```
+
+## Convergence / exit
+
+- Plan completo + validación OK (o diferida con handoff) → `Marcar plan done`.
+- `Cerrar` (tab flow, en cualquier momento) → `finalize` persiste `CHECKPOINT` + `BACKLOG` (qué quedó sin ejecutar / sin commitear / sin aplicar), cierra sessions, reporta.
+- La promoción de artefactos a `docs/` (vía `export-*`) es **siempre** un paso posterior y explícito, fuera de este loop.

package/skills/w/loops/plan-new-loop/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: plan-new-loop
+description: >-
+  Genera un plan de implementación rico (docs/plans/PPP-plan.md) a partir de un
+  spec refinado (docs/specs/NNN-spec-refined.md). Heir del chasis
+  spec-refine-loop: reusa íntegro su motor gap-driven convergente, sus sessions
+  internas (control + research on-demand), AskUserQuestion con ≤3 tabs de
+  contenido + 1 tab flow (Compactar/Cerrar) siempre presente, research autónomo
+  con regla BD read-only, y compact/resume con Cerrar que persiste CHECKPOINT +
+  BACKLOG. Sus deltas: el plan absorbe inline el nivel TECHNICAL-NOTE
+  (Solution/Impacted/AS-IS/TO-BE/Validations…) + Phases/Tasks con estado vivo;
+  el research aquí mapea código/impacto (componentes FE/BE/BD, wiring AS-IS,
+  dependencias); y una gap taxonomy propia de planificación. Lo arranca el
+  comando /w:plan-new y es reanudable. Invocar cuando un spec ya refinado deba
+  convertirse en un plan ejecutable antes de implementar.
+---
+
+# plan-new-loop
+
+> **Heir** del chasis [`spec-refine-loop`](../spec-refine-loop/SKILL.md). Aquí **solo** los deltas. El motor (gap-driven, sessions, AskUserQuestion + tab `flow`, research autónomo + regla BD, compact/resume, `Cerrar` persiste) vive en el chasis — no se repite.
+
+## Flow
+PLANIFICATION
+
+## Layer
+2 — la IA lo corre entero.
+
+## Started by
+`/w:plan-new` — **reanudable** (mismo mecanismo de 4 casos que el chasis).
+
+## Reads
+`docs/specs/NNN-spec-refined.md`
+
+## Writes
+`docs/plans/PPP-plan.md` (`generate`; **sobrescribe con confirmación** si existe). Solo escribe `docs/plans` — nunca otras carpetas `docs/` ni auto-export.
+
+## Inherits
+
+Del chasis [`spec-refine-loop`](../spec-refine-loop/SKILL.md), sin cambios:
+
+- Motor **gap-driven convergente** (`detect_gaps` → resolver → integrar → repetir; gaps agotados con límite `MAX` no se re-disparan).
+- **Sessions internas**: `control` (`<plan>-plan-new`: `SESSION` + `CHECKPOINT`, + `BACKLOG` al cerrar; Type = `refine`/`control`) + `research` on-demand (run-and-close, puede cerrar inconclusa).
+- **AskUserQuestion**: ≤3 tabs de contenido + 1 tab `flow` (`Compactar`/`Cerrar`) siempre.
+- **Ask-vs-research rule** + **research autónomo** + **regla BD** (pregunta MCP si >1 sin default → queries a `SCRIPTS.sql` → ejecuta read-only, `sql-mutation-guard`) + manejo de research **inconclusa** (degrada a humano / difiere a `Open questions` + límite `MAX`).
+- **Compact / resume** (4 casos) y **`Cerrar` persiste** `CHECKPOINT` + `BACKLOG`.
+- **Naming** `<run>` para sessions hijas: `<plan>-plan-new` → `<plan>-research-*`.
+
+## Delta 1 — Deliverable: PLAN RICO (`PPP-plan.md`)
+
+El plan absorbe el nivel `TECHNICAL-NOTE` **inline** (decisión del usuario) + roadmap:
+
+```markdown
+# Plan PPP — <slug>
+
+> Derivado de docs/specs/NNN-spec-refined.md · generado por plan-new-loop
+
+## Origin              spec fuente (o prompt, si se bootstrapeó vía spec-new)
+## Summary             el cómo, en 1–2 frases
+## Solution            explicación técnica/funcional de cómo se implementará
+## Impacted            FE · BE · BD (esquemas/tablas/funciones) · APIs · integraciones
+## Dependencies        docs / fuentes / bases / sesiones
+## Current state (AS-IS)   wiring actual (interfaces y métodos), resumido
+## Target state (TO-BE)    wiring objetivo
+## Final behavior      cómo se comporta el flujo al final (alineado con criterios del spec)
+## Phases              fases agrupadoras (complejidad XS–S)
+## Tasks               tareas por fase (≤XS), con deps y estado vivo (- [ ])
+## Validations         validaciones / restricciones / lógica de negocio
+## Risks / impact      riesgos e impactos técnicos
+## Assumptions         supuestos
+## Estimated time      sizing XS–XL (desarrollo + pruebas internas)
+## Open questions      pendientes
+```
+
+> **Implicación de catálogo:** `TECHNICAL-NOTE` deja de ser artefacto de exec session y se vuelve **secciones del plan-doc**. Reconciliado en [`plan-exec-loop`](../plan-exec-loop/SKILL.md): la exec session por fase **no** lleva `TECHNICAL-NOTE` ni `TASKS` propios; el detalle técnico y el progreso viven inline en el plan-doc (living).
+
+## Delta 2 — Gap taxonomy (de "plan")
+
+Reemplaza la gap taxonomy de spec por una orientada a planificación:
+
+| Gap | Signal | Resolved by |
+|---|---|---|
+| Approach/Solution sin definir | el cómo es vago | research / humano |
+| Componentes sin identificar | impacto FE/BE/BD desconocido | **research** (mapea el código) |
+| Wiring AS-IS desconocido | no se sabe el estado actual | **research** |
+| Fase muy grande | complejidad > S | humano (re-partir) |
+| Tarea no atómica | complejidad > XS | la IA re-parte |
+| Deps faltantes | orden no claro | research / humano |
+| Criterios del spec sin cubrir | tareas no trazan a acceptance criteria | la IA deriva + humano confirma |
+| Riesgos sin atender | — | humano |
+
+## Delta 3 — What research investigates here
+
+El research del chasis se especializa: mapear **código/impacto** — componentes FE/BE/BD afectados, wiring AS-IS, dependencias. Alimenta las secciones `Solution`, `Impacted`, `Current state (AS-IS)`. La regla BD del chasis aplica igual (queries read-only a `SCRIPTS.sql`, MCP elegido vía tab de contenido si >1 sin default).
+
+## Convergence / exit
+
+Sin gaps materiales → `AskUserQuestion` (contenido: `Guardar plan` / `Preguntar algo más`; flow: `Compactar`/`Cerrar`) → al `Guardar`, escribe `docs/plans/PPP-plan.md` (con confirmación si existe) → `finalize` (persiste `CHECKPOINT` + `BACKLOG`, cierra sessions, reporta). `Cerrar` en cualquier momento → `finalize` igual.

package/skills/w/loops/quick-loop/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: quick-loop
+description: >-
+  El atajo liviano de agent-workflow: resuelve una tarea acotada (un fix, un
+  ajuste pequeño) directamente desde el prompt del usuario, editando código con
+  ceremonia mínima. Heir del chasis spec-refine-loop (motor gap-driven mínimo,
+  research on-demand con regla BD read-only, AskUserQuestion con ≤3 tabs de
+  contenido + 1 tab flow Compactar/Cerrar siempre, compact/resume con Cerrar que
+  persiste CHECKPOINT + BACKLOG) y de plan-exec-loop (git seguro: rama esperada
+  antes de editar + commit propuesto, nunca push/--amend/--no-verify; la IA
+  nunca ejecuta DML, migraciones a SCRIPTS.sql; sin auto-export). Sus deltas: sin
+  fases ni plan-doc (el prompt ES la tarea), una sola session ligera
+  (<slug>-quick), un solo commit; y escalación con handoff si la tarea crece
+  (propone subir a SPEC/PLAN dejando el código a medias como contexto). NO toca
+  docs/. Lo arranca /w:quick y es reanudable. Invocar para cambios pequeños y
+  directos que no ameritan spec ni plan formal.
+---
+
+# quick-loop
+
+> **Heir** del chasis [`spec-refine-loop`](../spec-refine-loop/SKILL.md) + las políticas de ejecución de [`plan-exec-loop`](../plan-exec-loop/SKILL.md). Aquí **solo** los deltas de QUICK.
+
+## Flow
+QUICK
+
+## Layer
+2 — la IA lo corre entero (loop mínimo).
+
+## Started by
+`/w:quick` — **reanudable** (mismo mecanismo de resume del chasis).
+
+## Reads
+— (el prompt del usuario; no hay documento de entrada).
+
+## Writes
+- Edita código en las fuentes (cambio mínimo).
+- Artefactos de la session en `.workflow/sessions/`.
+- **NO toca `docs/`** (sin doc, sin auto-export).
+
+## Internal session
+
+- **SIEMPRE** crea una session ligera `<slug>-quick` (Type = `quick`, ≈ `exec`): `SESSION` · `DECISION` · `SCRIPTS.sql` · `CHECKPOINT` (+ `BACKLOG` al cerrar). Una sola session (no exec-por-fase).
+
+## Inherits
+
+- del **chasis** [`spec-refine-loop`](../spec-refine-loop/SKILL.md): gap-driven (mínimo), `AskUserQuestion` ≤3 + `flow` (`Compactar`/`Cerrar`), `research` on-demand + regla BD read-only (pregunta MCP si >1 sin default → `SCRIPTS.sql` → ejecuta read-only), compact/resume, `Cerrar` persiste `CHECKPOINT`+`BACKLOG`.
+- de [`plan-exec-loop`](../plan-exec-loop/SKILL.md): **git** (rama segura antes de editar + commit propuesto; nunca `push`/`--amend`/`--no-verify`), **BD** (la IA nunca ejecuta DML; migraciones → `SCRIPTS.sql` de la session), **sin auto-export** (no toca otras carpetas `docs/`).
+
+## Composes
+
+`git` · `coding-standards` · `testing` (validación puntual) · `sql` (regla BD) · `writing` · `research`. Resueltas por `.workflow/skills.toml`.
+
+## Delta QUICK — minimal ceremony
+
+- **Sin fases, sin plan-doc**: el prompt **es** la tarea (una sola unidad). No hay roadmap.
+- **Una sola session** (no exec-por-fase). **Un solo commit** propuesto al final.
+- **Escalación + handoff**: si la tarea crece (muchos archivos / ≥2 fuentes / necesita arquitectura) → propone subir a **SPEC/PLAN**. Si el usuario acepta:
+  - el **código ya editado queda** en el working tree (no se revierte) **y se registra** en `CHECKPOINT` + `BACKLOG` ("cambios sin commitear en `<fuente>` — código a medias; decidir commit/descartar al retomar") — reusando **ambas** mitades del patrón "commit rechazado" de plan-exec (no revertir **y** registrar lo sin commitear). Crítico en la rama **SPEC**, que no retoma el working tree;
+  - la session quick va a `finalize`, persistiendo `CHECKPOINT` + `BACKLOG` con un **puntero** al spec/plan sembrado (Followups: "escalado a `docs/specs/NNN` o `docs/plans/PPP` — retomar ahí");
+  - los artefactos (`DECISION`, `SCRIPTS.sql`) **quedan en la session quick** como contexto referenciable por la nueva session (no se migran);
+  - **asimetría**: escalar a **PLAN** puede **absorber** el avance (plan-exec retoma el working tree existente); escalar a **SPEC** **reinicia** el ciclo de diseño y trata el código a medias como **contexto/referencia**, no como trabajo ya ingerido.
+
+## Sequence
+
+```
+quick-loop(prompt):
+  s = create_or_resume(<slug>-quick)        # siempre session ligera
+  trabajar la tarea (loop mínimo):
+    verificar rama esperada por fuente (branch-check); si no → pausar + resolver
+    editar código (cambio mínimo)
+    si consulta BD read-only → SCRIPTS.sql + ejecutar read-only
+    si cambio BD (DDL/DML) → SCRIPTS.sql (artefacto session, NO ejecutar)
+    si decisión no obvia → DECISION
+    si duda/gap → research session ó AskUserQuestion        # chasis
+    si la tarea CRECE → proponer escalar a SPEC/PLAN
+        si acepta → handoff (código queda; BACKLOG→spec/plan sembrado) → goto finalize
+  validación puntual (test si aplica)
+  proponer commit (aprobar antes)                            # nunca push/amend/--no-verify
+  AskUserQuestion(contenido: [Cerrar tarea, Preguntar algo más], flow: [Compactar, Cerrar])
+finalize: CHECKPOINT + BACKLOG (si queda algo) + cerrar session + reportar
+```
+
+```mermaid
+flowchart TD
+    S["create_or_resume session <slug>-quick"] --> G["branch-check por fuente"]
+    G -->|ok| DO["editar código · BD→SCRIPTS.sql · DECISION<br/>(duda→research/AskUserQuestion)"]
+    G -->|rama ≠| PA["pausar + resolver"]
+    PA --> G
+    DO --> GROW{"¿la tarea creció?"}
+    GROW -->|sí| ESC["escalar a SPEC/PLAN<br/>código queda · BACKLOG→spec/plan sembrado"]
+    ESC --> FIN
+    GROW -->|no| V["validación puntual"]
+    V --> CM["proponer commit (aprobar)"]
+    CM --> Q["AskUserQuestion[Cerrar · Preguntar más]<br/>flow[Compactar · Cerrar]"]
+    Q --> FIN["finalize: CHECKPOINT + BACKLOG + cerrar"]
+```
+
+## Convergence / exit
+
+- Tarea hecha + commit (o aprobado saltarlo) → `Cerrar`.
+- `Cerrar`/`Compactar` (tab flow) → persiste `CHECKPOINT` + `BACKLOG` (reanudable).
+- **Sin export**: nada va a `docs/`. Si algo amerita preservarse → se promueve aparte vía `export-*`, o se escala a SPEC/PLAN.

package/skills/w/loops/spec-refine-loop/SKILL.md

@@ -0,0 +1,222 @@
+---
+name: spec-refine-loop
+description: >-
+  El CHASIS de los loops de agent-workflow. Refina un spec borrador
+  (docs/specs/NNN-spec.md) hasta un spec refinado sin ambigüedad
+  (docs/specs/NNN-spec-refined.md) mediante un motor gap-driven convergente:
+  detecta huecos/ambigüedades, los resuelve preguntando al humano (lo que
+  depende de su intención) o investigando de forma autónoma vía sessions de
+  research (lo que se responde leyendo el repo/datos), integra y repite hasta
+  converger. Compone la capacidad ui-design (built-in ui-spec) cuando el
+  requerimiento involucra UI. Lo arranca el comando /w:spec-refine y es
+  reanudable (4 casos de resume). Usa AskUserQuestion con ≤3 tabs de contenido
+  + 1 tab flow (Compactar/Cerrar) siempre presente; Cerrar persiste CHECKPOINT
+  + BACKLOG. Es el patrón de referencia que heredan plan-new-loop,
+  plan-exec-loop y quick-loop. Invocar cuando haya que refinar/desambiguar una
+  especificación antes de planificar.
+---
+
+# spec-refine-loop
+
+> **El CHASIS.** Primer loop diseñado en detalle; patrón de referencia que heredan los demás loops (`plan-new-loop`, `plan-exec-loop`, `quick-loop`). Si editas el motor, edítalo aquí.
+
+## Flow
+SPEC
+
+## Layer
+2 — la IA lo corre entero (gap-driven). El usuario no conduce el ciclo; solo responde tabs de contenido y dirige el ciclo de vida por el tab `flow`.
+
+## Started by
+`/w:spec-refine` — **reanudable**. Detecta el estado previo y arranca según corresponda (ver *Compact / resume*, 4 casos).
+
+## Reads
+- `docs/specs/NNN-spec.md` (borrador), **o**
+- `docs/specs/NNN-spec-refined.md` si **ya existe** un refinado previo → se re-refina incremental sobre el refined (NO sobre el borrador stale).
+
+## Writes
+`docs/specs/NNN-spec-refined.md` (cuando el usuario elige `Guardar especificación refinada`). Si el archivo **ya existe**, **sobrescribe con confirmación** del usuario.
+
+> **Invariante de boundary:** este loop escribe **solo** en `docs/specs`. Nunca gradúa/exporta otros artefactos a `docs/` — eso es trabajo de `export-*`, aparte.
+
+## Internal sessions (managed)
+
+El loop crea y maneja sus sessions en `.workflow/sessions/`. El usuario nunca las crea.
+
+| Session | When | Artifacts | Role |
+|---|---|---|---|
+| **refine session** `<spec>-spec-refine/` | al arrancar el loop (o se reanuda) | `SESSION.md` · `CHECKPOINT.md` (· `BACKLOG.md` al cerrar) | Dueña del run. Guarda el avance al `Compactar` y al `Cerrar`; habilita el resume. Type = `refine`. |
+| **research session** `<run>-research-*/` | on-demand, por cada gap factual | `SESSION.md` · `ANALYSIS-FILE.md` → `CONCLUSIONS.md` (+ `SCRIPTS.sql` si consulta BD) | Investiga, concluye, **cierra y reporta**. Puede cerrar **inconclusa**. Type = `research`; on-demand, **no reanudable** (run-and-close, sin `CHECKPOINT`/`BACKLOG` propios). |
+
+> El spec **nunca** entra en una session; vive en `docs/specs/`.
+>
+> `<run>` = id de la session dueña del loop padre, que prefija sus sessions hijas: `<spec>-spec-refine`, `<plan>-plan-new`, `<plan>-plan-exec`, `<slug>-quick`. Así el patrón de naming es exacto en cualquier flujo que herede este chasis.
+
+**CLI** (asunción de naming; los subcomandos se implementan en paralelo — no bloquear):
+- `aw session-create --type refine --name <spec>-spec-refine` / `aw session-resume --code <…>` (detecta `CHECKPOINT`).
+- `aw session-create --type research --name <run>-research-<gap>` para cada gap factual.
+- `aw checkpoint-write` / `aw checkpoint-read` para el resume.
+- `aw session-close` al cerrar (con razón); `aw session-artifacts` para inspeccionar.
+
+## Composes
+
+Cuando el requerimiento involucra **UI**, compone la capacidad **`ui-design`** (default built-in `ui-spec`; rebindeable vía `.workflow/skills.toml`): autora el UI spec nativamente (esquema `Screen`, vocabulario, formato). El loop aporta la iteración/Q&A que el viejo servicio no tenía (design-system, tema, variantes, desambiguación) y lo integra como sección `## UI spec` del spec.
+
+Otras capacidades transversales que el chasis usa siempre: `research` (research on-demand), `sql` (regla BD en research), `writing` (redacción del refined). Todas se resuelven por config; `off` → el loop sigue sin la capacidad y, si era necesaria, lo dice o pregunta.
+
+## Deliverable schema (`NNN-spec-refined.md`)
+
+Más rico que el borrador: mismas secciones **completadas** + dos nuevas (`Refinement decisions`, `Q&A traceability`).
+
+```markdown
+# Spec NNN (refined) — <slug>
+
+> Derivado de `NNN-spec.md` · refinado por spec-refine-loop
+
+## Requirement            (afinado, sin ambigüedad)
+## Context                (completo)
+## Scope                  (In / Out claros)
+## Acceptance criteria    (testables, - [ ])
+## Assumptions            (declarados)
+
+## UI spec                (opt. — si involucra UI; vía capacidad ui-design / skill ui-spec)
+Screen (JSON) + render Markdown.
+
+## Refinement decisions   ← NEW
+Qué se definió al refinar y por qué. Incluye lo resuelto vía research
+(con referencia a la research session / CONCLUSIONS).
+
+## Q&A traceability       ← NEW
+Cada duda preguntada al humano + la respuesta elegida.
+
+## Open questions         (idealmente "None"; lo que quede se difiere)
+```
+
+## Gap taxonomy (= weak sections of the schema)
+
+`detect_gaps(work)` busca estas señales; cada una tiene un resolutor:
+
+| Gap | Signal | Resolved by |
+|---|---|---|
+| Requirement vago | el qué/por qué ambiguo | **humano** |
+| Context incompleto | sistemas/componentes sin identificar | **research** |
+| Scope borroso | falta `Out`, o In/Out se solapan | **humano** |
+| Criterios no testables | acceptance no verificable | **humano** (derivar + confirmar) |
+| Open questions abiertas | dudas explícitas | según naturaleza |
+| Supuestos ocultos | el spec asume cosas no dichas | **research** valida / **humano** confirma |
+| Contradicción interna | secciones que se contradicen | **humano** |
+
+## Ask-vs-research rule (el discriminador)
+
+Para cada gap, una sola pregunta decide el resolutor:
+
+> *"¿Puedo responder esto leyendo el repo/datos?"* → **research** (autónomo).
+> *"¿Depende de lo que el usuario quiere?"* → **preguntar al humano** (AskUserQuestion).
+
+## Research: autonomy, scope & failure
+
+- **Autónomo**: la IA crea la research session, investiga y reporta **sin pedir permiso**. El humano se entera al integrarse (en `Refinement decisions`) y mantiene control vía el tab `flow`.
+- **Alcance**: workspace + repos asociados (fuentes) + MCPs de BD.
+- **Regla BD** (única excepción a la autonomía):
+  1. **Elección de MCP**: si el gap requiere BD y hay **>1 MCP candidato sin default configurado**, la IA pregunta cuál usar. Esa pregunta va por el **mismo `AskUserQuestion`** como un **tab de contenido** (cuenta dentro del límite ≤3 + `flow`), **antes** de ejecutar queries. Si hay un único MCP o un default, no pregunta.
+  2. Escribe **primero** las queries en `SCRIPTS.sql` de la research session.
+  3. Las ejecuta **read-only** vía MCP (respeta `sql-mutation-guard`: nunca DML/DDL).
+- **Research inconclusa** (BD no disponible, evidencia insuficiente, gap factual irresoluble):
+  - La research session cierra con estado **`inconcluso`** y reporta el motivo (vía su `Success criteria` no cumplido).
+  - El loop **degrada** el gap: lo pasa a **pregunta-al-humano** (próximo batch → `Q&A traceability`) o, si tampoco aplica, lo **difiere** a `## Open questions` del refined.
+  - El gap se marca **"ya intentado vía research"** (`attempts[gap]++`, límite `MAX`) para que `detect_gaps` **no lo re-dispare en bucle** → garantiza convergencia.
+
+## AskUserQuestion (design & batching)
+
+- Límite del host: **máx 4 preguntas/llamada**. Como el tab `flow` va **siempre** → **≤3 tabs de contenido + 1 tab `flow`**.
+- **tab `flow`** (ciclo de vida, siempre presente): `Compactar` | `Cerrar`. Responder solo los tabs de contenido (sin tocar `flow`) = seguir iterando.
+- **Tabs de contenido** posibles:
+  - dudas-de-humano (gaps no factuales);
+  - elección de MCP (regla BD) — antes de ejecutar queries;
+  - en **convergencia**, acción: `Guardar especificación refinada` | `Preguntar algo más`.
+- **Batching**: agrupar hasta 3 gaps de humano en una sola llamada. Si hay más de 3 pendientes, priorizar (los que desbloquean otros gaps primero) y diferir el resto a la próxima vuelta.
+
+## Sequence
+
+```
+spec-refine-loop(spec):
+  input = exists(NNN-spec-refined.md) ? NNN-spec-refined.md : NNN-spec.md   # (#2 resume)
+  refine_session = create_or_resume(<spec>-spec-refine)    # detecta CHECKPOINT
+  work = read(input)  (+ aplicar avance del checkpoint si reanuda)
+  attempts = {}                                            # anti-relanzamiento por gap
+  repeat:
+    gaps = detect_gaps(work)  menos los gaps "agotados"
+    if gaps == ∅: break
+    batch = top ≤3 gaps ; pending_human = []
+    para cada gap en batch:
+      si factual(gap) y attempts[gap] < MAX:
+        si requiere BD y >1 MCP sin default → encolar "elección MCP" en pending_human
+        rs  = create_research_session(gap)
+        res = rs.run_and_close()             # ANALYSIS-FILE → CONCLUSIONS (+SCRIPTS.sql)
+        si res.concluyente: work = integrate(work, res)    # → Refinement decisions
+        si no: attempts[gap]++ ; si attempts[gap] >= MAX → pending_human.push(gap)
+      si no:
+        pending_human.push(gap)
+    si pending_human no vacío:
+      ans = AskUserQuestion(contenido: pending_human (≤3), flow: [Compactar, Cerrar])
+      switch(flow):
+        Compactar → write CHECKPOINT (refine_session) ; /compact ; continue
+        Cerrar    → goto finalize
+      work = integrate(work, ans)            # → Q&A traceability / Open questions
+  # convergió:
+  ans = AskUserQuestion(contenido: [Guardar refinada, Preguntar algo más],
+                        flow: [Compactar, Cerrar])
+  Guardar          → write_with_confirm(NNN-spec-refined.md) ; goto finalize   # (#2)
+  Preguntar algo más → continue
+  flow Compactar/Cerrar → manejar igual
+finalize:
+  write CHECKPOINT (refine_session)                        # (#5) persiste siempre
+  write/update BACKLOG (motivo de cierre + Open questions diferidas)   # (#5)
+  cerrar research sessions abiertas ; cerrar refine_session ; reportar
+```
+
+```mermaid
+flowchart TD
+    S["input = refined si existe, si no borrador<br/>create_or_resume refine session"] --> D{"¿gaps<br/>(no agotados)?"}
+    D -->|no| C["AskUserQuestion<br/>contenido[Guardar refinada · Preguntar más]<br/>flow[Compactar · Cerrar]"]
+    D -->|sí| B["tomar ≤3 gaps"]
+    B --> F{"¿factual y<br/>attempts<MAX?"}
+    F -->|sí| RS["research session<br/>ANALYSIS-FILE → CONCLUSIONS (+SCRIPTS.sql)"]
+    RS --> CC{"¿concluyente?"}
+    CC -->|sí| I1["integrar → Refinement decisions"]
+    CC -->|no| DEG["attempts++ ; degradar a humano / Open questions"]
+    F -->|no| Q["AskUserQuestion<br/>contenido[dudas + elección MCP ≤3]<br/>flow[Compactar · Cerrar]"]
+    Q --> I2["integrar → Q&A traceability"]
+    I1 --> D
+    DEG --> D
+    I2 --> D
+    C -->|Guardar| W["write_with_confirm<br/>NNN-spec-refined.md"]
+    C -->|Preguntar más| D
+    W --> FIN["finalize: CHECKPOINT + BACKLOG<br/>+ cerrar sessions + reportar"]
+```
+
+## Compact / resume
+
+Cuatro casos al ejecutar `/w:spec-refine` sobre un spec:
+
+1. **En curso** (existe `CHECKPOINT.md` en la refine session) → reanuda desde el avance (gaps resueltos, Q&A, `attempts`, research sessions abiertas).
+2. **Sin avance** (no hay CHECKPOINT ni refined) → arranca desde cero leyendo `NNN-spec.md`.
+3. **Ya completado** (existe `NNN-spec-refined.md`, sin CHECKPOINT) → re-refinamiento incremental: input = el **refined** (no el borrador); al `Guardar`, sobrescribe con confirmación.
+4. **`Compactar`** (tab flow) → escribe `CHECKPOINT.md` en la refine session (spec en progreso, gaps restantes, Q&A, `attempts`, research sessions abiertas) → dispara `/compact` del host → reanuda leyendo el checkpoint.
+
+## Convergence / exit
+
+- **Sin gaps materiales** → ofrece `Guardar especificación refinada`.
+- `Guardar` → `write_with_confirm(NNN-spec-refined.md)` y `finalize`.
+- `Cerrar` (tab flow, en cualquier momento) → `finalize`. **`finalize` persiste siempre**: escribe `CHECKPOINT.md` (reanudable) **y** `BACKLOG.md` (motivo de cierre + `Open questions` diferidas), cierra sessions y reporta. Así sobrevive el avance aunque no se haya `Compactar` antes.
+
+## Integration (dónde aterriza cada resolución)
+
+- Resuelto vía **research** → `## Refinement decisions` del refined (+ ref a la research session / `CONCLUSIONS`).
+- Resuelto vía **humano** → `## Q&A traceability` del refined.
+- **Research inconclusa o sin resolver** → `## Open questions` del refined (diferido) + `BACKLOG.md` de la refine session al cerrar.
+
+## Heredan este chasis
+
+- `plan-new-loop` — mismo motor; deltas: plan rico + gap taxonomy de plan.
+- `plan-exec-loop` — mismo motor; deltas: ejecución real (código/BD/git), session por fase, sin auto-export.
+- `quick-loop` — mismo motor (mínimo); hereda además git/BD/no-export de `plan-exec-loop`.