@tacuchi/agent-workflow-cli 11.0.1 → 12.2.0

package/skills/w/exports/export-scripts/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: export-scripts
+description: "Consolida los SQL pendientes del workspace en un único bundle `docs/scripts/NNN-export-scripts-YYYY-MM-DD/` con numeración continua tras `00-ROLLBACK.sql`. Lee migraciones tipo-B (DDL/DML) desde dos fuentes: `.workflow/sessions/<folder>/SCRIPTS.sql` de N sesiones Y `docs/scripts/*.sql` standalone (excluyendo bundles previos). Ignora el tipo-A read-only (consultas de diagnóstico, no entregables). Headers SQL mínimos + README simple (3 secciones: Archivos / Aplicar / Revertir). El rollback se deriva de los forwards. Read-only/reporte: NUNCA ejecuta SQL ni commitea — el bundle es para que un humano/DBA lo aplique. Compone la capacidad `sql`. Úsalo para 'bundle SQL del release', 'preparar paso a prod', 'consolidar SQLs pendientes'. Invocado por el usuario vía `/w:export-scripts`."
+---
+
+# export-scripts — Bundle SQL consolidado, simple y directo
+
+Consolida las migraciones SQL pendientes de N sesiones + archivos standalone en un único bundle bajo `docs/scripts/NNN-export-scripts-YYYY-MM-DD/`, con numeración continua tras `00-ROLLBACK.sql`. **Read-only / reporte** — la IA **nunca ejecuta** el SQL; el usuario/DBA aplica el bundle manualmente.
+
+> Familia `export-*` (la única vía artefacto→`docs/`). Recicla el espíritu del viejo `export-scripts` v5.0.0 (numeración continua, headers SQL minimal, README de 3 secciones, rollback derivado de forwards), modernizado al modelo nuevo (sin modos project/hub; `docs/scripts` en inglés). Diseño: `docs/referencias/workflow-exports/export-scripts.md`.
+
+## Category
+
+`docs/scripts` — **única** carpeta `docs/` que este export escribe.
+
+## Composes
+
+Capacidad **`sql`** (built-in default `sql`), resuelta vía `.workflow/skills.toml`. Aporta el vocabulario de categorías DDL/DML, el orden de aplicación y la derivación de rollback. Este export **no** posee esa lógica: la compone. Rebindeable u `off` por config.
+
+## When to use
+
+- "Bundle SQL del release", "preparar paso a prod", "consolidar SQLs pendientes".
+- Antes de promover una rama a certificación / `main`.
+- Tras varias sesiones `exec`/`quick` que dejaron `SCRIPTS.sql` con migraciones.
+
+## What it does
+
+1. Recolecta SQL del workspace desde **dos fuentes**: `SCRIPTS.sql` tipo-B de cada sesión del corpus + `docs/scripts/*.sql` standalone (excluyendo bundles previos).
+2. Clasifica las sentencias por categoría canónica (DDL-TABLES / DDL-FUNCTIONS / DML / INSERTS).
+3. Consolida cross-source por categoría con **numeración continua** tras `00-ROLLBACK.sql`.
+4. Escribe los forwards consolidados (cada sentencia con su origen, 1 línea).
+5. Deriva `00-ROLLBACK.sql` **al final**, leyendo los forwards ya escritos.
+6. Escribe un `README.md` minimal (Archivos / Aplicar / Revertir).
+
+## What it does NOT do
+
+- **Ejecutar SQL** (invariante BD scripts-only). El bundle es entregable; lo aplica un humano/DBA.
+- Commitear, mergear, push.
+- Tocar `.workflow/sessions/` ni los `docs/scripts/*.sql` standalone (solo lectura).
+- Escribir cualquier carpeta `docs/` que no sea `docs/scripts/` (invariante: una categoría).
+- Migrar bundles previos (`docs/scripts/NNN-export-scripts-*/` quedan como histórico).
+- Incluir el tipo-A read-only (consultas de diagnóstico) ni inventar SQL.
+- Generar plantillas de correo, checklists de producción, listados de commits/sesiones, ni resúmenes ejecutivos en el README.
+
+## Read-only sandbox
+
+En plan mode **describe**, no escribe: el `NNN` resuelto, las fuentes detectadas (sesiones + standalone), las categorías con contenido, los archivos que aparecerían al root del bundle y el contenido aproximado del README. **No** ejecuta `Write`, ni `aw next-number` con efecto, ni mutaciones.
+
+## Inputs
+
+**CLI `agent-workflow` (alias `aw`)** — no leer paths hardcodeados:
+
+- `aw sessions` / `aw release-data [--since sessionNNN] [--source <alias>]` — enumera el corpus de sesiones.
+- `aw session-artifacts --code <NNN>` — lee `SCRIPTS.sql` de cada sesión (lazy). Si no existe → skip silencioso.
+- `aw next-number docs/scripts` — numeración determinística del directorio del bundle (la resolución de la carpeta destino la maneja el CLI).
+
+**Filesystem**:
+
+- `docs/scripts/*.sql` standalone (solo top-level), **excluyendo** cualquier `docs/scripts/NNN-export-scripts-*/` (outputs previos de este export).
+
+**Args** (sin lifecycle `AskUserQuestion`):
+
+```
+/w:export-scripts [--sessions NNN[,NNN]] [--since sessionNNN] [--source <alias>]
+                  [--skip-standalone] [--dry-run]
+```
+
+| Flag | Comportamiento |
+|---|---|
+| `--sessions NNN[,NNN]` | Filtro discreto por código (precede a `--since`) |
+| `--since sessionNNN` | Solo sesiones posteriores a NNN (inclusive) |
+| `--source <alias>` | Limita a una fuente (workspace multi-fuente) |
+| `--skip-standalone` | Omite la lectura de `docs/scripts/*.sql` standalone |
+| `--dry-run` | Reporte propositivo sin escribir archivos |
+
+Sin args: todas las sesiones del corpus + todos los `.sql` standalone (excluyendo bundles previos). *(Si algún flag exacto difiere en el CLI runtime, ajustar al contrato real de `aw`.)*
+
+## Flow
+
+### Paso 1 — Recolección de fuentes SQL
+
+**Fuente A — sesiones**: por cada sesión del corpus (`aw sessions` / `release-data` + `session-artifacts --code <NNN>`), leer `.workflow/sessions/<folder>/SCRIPTS.sql` si existe. Tomar **solo** las sentencias tipo-B (migraciones DDL/DML entregables); ignorar el tipo-A read-only (consultas de diagnóstico). Markers esperados por sentencia: `-- @category: <01-04>` + `-- @stmt: NNN-verbo-objetivo` (formato definido por la capacidad `sql`).
+
+**Fuente B — standalone** (salvo `--skip-standalone`): listar `docs/scripts/*.sql` top-level, **excluyendo** `docs/scripts/NNN-export-scripts-*/`. Por archivo: respetar markers `@category` si los hay; si no, inferir categoría del contenido (`CREATE/ALTER TABLE`, `CREATE INDEX` → `01`; `CREATE OR REPLACE FUNCTION`/`PROCEDURE` → `02`; `UPDATE`/`DELETE` → `03`; `INSERT INTO … VALUES` → `04`). Si el filename contiene `rollback` → skip (no entra en forward).
+
+Si la unión A + B está vacía → **abortar**: "No hay SQL pendientes en el workspace".
+
+### Paso 2 — Numeración del bundle
+
+`aw next-number docs/scripts` → `docs/scripts/NNN-export-scripts-YYYY-MM-DD/`.
+
+### Paso 3 — Clasificación y orden interno
+
+Agrupar por categoría canónica: `01 DDL-TABLES` · `02 DDL-FUNCTIONS` · `03 DML` · `04 INSERTS`. Orden interno cronológico por origen (sesión ascendente → stmt ascendente; standalone intercalado por orden léxico del filename).
+
+### Paso 4 — Numeración continua (sin gaps)
+
+Asignar números secuenciales **solo a las categorías con contenido**, en el orden canónico. El primer forward siempre es `01-…`. Ej.: solo DML → `00-ROLLBACK.sql`, `01-DML.sql`; las 4 categorías → `00-ROLLBACK.sql`, `01-DDL-TABLES.sql`, `02-DDL-FUNCTIONS.sql`, `03-DML.sql`, `04-INSERTS.sql`.
+
+### Paso 5 — Escribir forwards
+
+Por categoría con contenido, un archivo con header de 1-2 líneas (`-- 0N-<CATEGORIA>.sql — bundle NNN-export-scripts-YYYY-MM-DD`) y, por sentencia, **un comentario de una línea** con el origen (`-- sessionXXX / stmt-id` o `-- docs/scripts/001-filename.sql`) seguido del SQL tal cual lo escribió el developer (envuelto en `BEGIN; … COMMIT;` si aplica). No replicar motivación/impacto/idempotencia ya presentes en el origen; no agregar índice de sentencias ni SELECTs de verificación inventados.
+
+### Paso 6 — Derivar `00-ROLLBACK.sql` (al final)
+
+Vía la capacidad `sql`, **leyendo los forwards ya escritos** (no el `SCRIPTS.sql` original): sentencias inversas en orden inverso (último→primero), bloque transaccional único, y un bloque "Cleanup irreversible" al final fuera de transacción solo si hay operaciones sin reversa automática.
+
+### Paso 7 — Escribir `README.md` (3 secciones)
+
+`## Archivos` (tabla: 1 fila por archivo presente) · `## Aplicar` (un `psql -f` por archivo en orden ascendente; el export no ejecuta nada) · `## Revertir` (`psql -f 00-ROLLBACK.sql` + nota si hay bloque irreversible). **Vetado**: resumen ejecutivo, tabla de sesiones, plantillas de correo, listado de commits, checklist de producción.
+
+### Paso 8 — Escribir o reportar
+
+Si `--dry-run`: imprimir el reporte; no escribir. Si no: `Write` del bundle. **NUNCA commitear**. Resumen al usuario: una línea por archivo escrito + ruta del bundle (sin replicar el README).
+
+## Output location
+
+```
+docs/scripts/NNN-export-scripts-YYYY-MM-DD/
+├── 00-ROLLBACK.sql       # reversa derivada de los forwards
+├── 01-<CATEGORIA>.sql    # primer forward (numeración continua)
+├── 02-<CATEGORIA>.sql    # …según categorías con contenido
+└── README.md             # Archivos · Aplicar · Revertir
+```
+
+## Re-run
+
+Idempotente funcional: cada invocación toma el siguiente `NNN` y **no sobrescribe** bundles previos. Para regenerar: borrar el directorio manualmente y re-invocar.
+
+## Resources
+
+- Design: `docs/referencias/workflow-exports/export-scripts.md` · familia: [`../README.md`](../README.md).
+- Capacidad compuesta: `sql` (built-in default; ver `docs/referencias/workflow-skills/`).
+- Artefacto fuente: `SCRIPTS.sql` (ver `docs/referencias/workflow-artifacts/artifacts-core/`).
+- Siblings: [`../export-manuals/SKILL.md`](../export-manuals/SKILL.md) · [`../export-diagrams/SKILL.md`](../export-diagrams/SKILL.md) · [`../export-reports/SKILL.md`](../export-reports/SKILL.md).

package/skills/w/hooks/README.md

@@ -0,0 +1,15 @@
+# hooks — host hook template
+
+`hooks.template.json` wires the host (Claude Code) to the `agent-workflow` runtime hooks. Merge it into your host's user-level hook config (e.g. `~/.claude/settings.json`); the installer does this automatically for Claude.
+
+| Event | Hook | Purpose |
+|---|---|---|
+| `SessionStart` | namespace pin | Pins the workspace namespace to `workflow` (so `.workflow/` resolves). |
+| `PreToolUse` (Edit/Write) | `hook branch-check` | Verifies the expected work branch before any file edit (git-safe invariant). |
+| `PreToolUse` (`execute_sql`) | `hook sql-mutation-guard` | Blocks DML/DDL over MCP — reads only (DB scripts-only invariant). |
+| `PreToolUse` (Bash) | `hook git-commit-advisor` | Advises on commit policy (propose-then-execute, no `push`/`--amend`/`--no-verify`). |
+| `SessionEnd` | `auto-compact-on-close` | Persists pending state on close. |
+| `PreCompact` | `checkpoint-write` | Writes `CHECKPOINT.md` before the host compacts. |
+| `PostCompact` | `resume-summary` | Recovers the active loop state after a compact. |
+
+> These hooks enforce invariants 4 (DB scripts-only) and 5 (git-safe) at the host level, independent of the loop logic. The hook commands are runtime CLI subcommands (`agent-workflow hook …`), unchanged across the bundle namespace.

package/skills/{agent-workflow → w}/hooks/hooks.template.json

@@ -63,7 +63,7 @@
           {
             "type": "command",
             "command": "agent-workflow checkpoint-write",
-            "statusMessage": "Escribiendo CHECKPOINT.md antes de compactar... (tip: `/agent-workflow:compact` sintetiza el resumen con contexto vivo)",
+            "statusMessage": "Escribiendo CHECKPOINT.md antes de compactar...",
             "timeout": 10
           }
         ]
@@ -81,7 +81,7 @@
           },
           {
             "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á."
+            "prompt": "Contexto compactado. El JSON anterior es output de `agent-workflow resume-summary`. Si hay `active_sessions`, reanudá el loop activo desde su CHECKPOINT.md y presentá un resumen. Si está vacío, terminá."
           }
         ]
       }

package/skills/w/loops/README.md

@@ -0,0 +1,118 @@
+# w/loops — Loop map (Layer 2)
+
+> Los **loops** son las piezas que la **IA corre enteras** para producir entregables y orquestar el trabajo. Los arranca un comando `/w:…` (Capa 1) y, a partir de ahí, **los conduce la IA**, no el usuario.
+>
+> Hermanos: `../commands/` (Capa 1, comandos `/w:…`) · `.workflow/sessions/` (Capa 3, sessions + artefactos internos) · la familia `export-*` (única vía artefacto→`docs/`) · las **capacidades** componibles (roles bindeados en `.workflow/skills.toml`).
+
+---
+
+## What a loop is
+
+Un loop es una **skill** que le enseña a la IA *cómo iterar* hasta producir un entregable. Se invoca por su `name:` con el tool `Skill`. La IA lo ejecuta de punta a punta: detecta huecos, los resuelve (preguntando al humano o investigando), integra y repite hasta converger.
+
+Propiedades comunes a **los 4 loops**:
+
+1. **Gap-driven convergente** — cada ciclo: `detect_gaps` → resolver (humano o research) → integrar → repetir hasta que no queden gaps materiales. Los gaps "agotados" (límite `MAX` de intentos) no se re-disparan → garantiza convergencia.
+2. **Puede crear sessions internas** — si refinar/planificar/ejecutar requiere trabajo profundo (ej. investigar el código), el loop crea una session en `.workflow/sessions/` que maneja **sus** artefactos, la cierra y reporta de vuelta. **El usuario nunca crea esas sessions.**
+3. **AskUserQuestion con dos tipos de tab** (límite host: 4 preguntas/llamada):
+   - **tab(s) de contenido** (≤3) — la(s) pregunta(s) real(es) del momento (resolver una duda, elegir MCP, o en convergencia: `Guardar` / `Preguntar algo más`).
+   - **tab `flow`** (1, SIEMPRE presente) — control de ciclo de vida por un canal lateral. Así el contenido lo maneja la IA y el ciclo de vida lo dirige el humano.
+4. **Escribe solo en su propia carpeta `docs/`** — y **nunca** gradúa/exporta otros artefactos a `docs/`. Esa promoción la hacen las skills `export-*`, aparte y explícita.
+
+## flow tab — options
+
+El tab `flow` es **fijo**: `Compactar` / `Cerrar`, presente en los 4 loops. Responder el tab de contenido **sin tocar `flow`** = seguir iterando ("continuar" es el comportamiento por defecto del loop, no una opción del canal de control).
+
+| Option | What it does |
+|---|---|
+| `Compactar` | Escribe `CHECKPOINT` (session dueña del run) + dispara `/compact` del host y reanuda sin perder el hilo. |
+| `Cerrar` | `finalize`: persiste lo pendiente (`CHECKPOINT` + `BACKLOG`), cierra sessions internas y termina el loop. |
+
+## Loops and their flow
+
+| Loop (`name:`) | Flow | Started by | Reads | Writes |
+|---|---|---|---|---|
+| [`spec-refine-loop`](spec-refine-loop/SKILL.md) | SPEC | `/w:spec-refine` | `docs/specs/NNN-spec.md` (o `…-spec-refined.md` si ya existe) | `docs/specs/NNN-spec-refined.md` |
+| [`plan-new-loop`](plan-new-loop/SKILL.md) | PLANIFICATION | `/w:plan-new` | `docs/specs/NNN-spec-refined.md` | `docs/plans/PPP-plan.md` |
+| [`plan-exec-loop`](plan-exec-loop/SKILL.md) | PLANIFICATION | `/w:plan-exec` | `docs/plans/PPP-plan.md` | `docs/plans/PPP-plan.md` (update) + `docs/tools`; resto vía `export-*` |
+| [`quick-loop`](quick-loop/SKILL.md) | QUICK | `/w:quick` | — (prompt) | edita código + session ligera; **no** `docs/` |
+
+> `/w:spec-new` no tiene loop (es single-pass). Por eso hay **5 comandos / 4 loops**.
+
+### `docs/` boundary (regla dura)
+
+Los loops **nunca** graduan/exportan artefactos a `docs/` automáticamente. Cada loop escribe **solo** su(s) carpeta(s):
+
+| Flow | Carpetas `docs/` que escribe |
+|---|---|
+| SPEC | `docs/specs` |
+| PLANIFICATION | `docs/plans` (living) + `docs/tools` (herramientas creadas — salida directa) |
+| QUICK | ninguna |
+
+Todo lo demás (migraciones → `docs/scripts`, manuales → `docs/manuals`, diagramas → `docs/diagrams`, informes → `docs/reports`) queda como **artefacto de session** hasta que un `export-*` lo promueva, como paso aparte y explícito.
+
+## Loops × flow tab
+
+| Loop | tab(s) de contenido típicos | tab `flow` |
+|---|---|---|
+| `spec-refine-loop` | dudas-de-humano · elección de MCP · convergencia (`Guardar especificación refinada` / `Preguntar algo más`) | `Compactar` / `Cerrar` |
+| `plan-new-loop` | dudas · elección de MCP · convergencia (`Guardar plan` / `Preguntar algo más`) | `Compactar` / `Cerrar` |
+| `plan-exec-loop` | decisiones/dudas no obvias · elección de MCP · cierre (`Marcar plan done` / `Preguntar algo más`) | `Compactar` / `Cerrar` |
+| `quick-loop` | dudas no obvias · escalar a SPEC/PLAN · cierre (`Cerrar tarea` / `Preguntar algo más`) | `Compactar` / `Cerrar` |
+
+## Schema of each loop file
+
+| Field | Description |
+|---|---|
+| `## Flow` | A qué flujo pertenece (SPEC · PLANIFICATION · QUICK) |
+| `## Layer` | Siempre 2 (la IA lo corre entero) |
+| `## Started by` | Comando `/w:…` que lo arranca (reanudable) |
+| `## Reads` | Documento(s) de entrada |
+| `## Writes` | Documento(s) de salida (`generate` / `read-update`) |
+| `## Internal sessions` | Sessions que crea y sus artefactos |
+| `## Sequence` | Pseudocódigo + mermaid del loop |
+| `## Convergence / exit` | Cuándo para |
+
+El **chasis** (`spec-refine-loop`) además detalla `## Composes` (capacidades que compone), `## Deliverable schema`, `## Gap taxonomy`, `## Ask-vs-research rule`, `## Research: autonomy, scope & failure`, `## AskUserQuestion`, `## Compact / resume`, `## Integration`.
+
+Los **heirs** (`plan-new-loop`, `plan-exec-loop`, `quick-loop`) usan `## Inherits` (lo que reusan del chasis, sin repetirlo) + `## Delta N` (sus diferencias).
+
+## Chassis / heirs
+
+```
+spec-refine-loop  ── CHASIS (patrón de referencia: motor gap-driven, sessions,
+        │            AskUserQuestion + tab flow, research autónomo + regla BD,
+        │            compact/resume, Cerrar persiste CHECKPOINT+BACKLOG)
+        ├── plan-new-loop   (heir)  → deltas: plan rico, gap taxonomy de plan
+        ├── plan-exec-loop  (heir)  → deltas: ejecución real (código/BD/git),
+        │                              session por fase, sin auto-export
+        └── quick-loop      (heir)  → deltas: ceremonia mínima, 1 session,
+                                       hereda git/BD/no-export de plan-exec
+```
+
+El chasis **no es una capacidad bindeable**: *es* `spec-refine-loop` y los demás loops lo heredan. Lo enchufable son las **capacidades** que un loop compone (ej. `ui-design`, `sql`, `git`, `testing`), resueltas por `.workflow/skills.toml`.
+
+## Composed capabilities (roles)
+
+Los loops componen **capacidades por su rol**, no skills concretas; la skill que cumple el rol la resuelve `.workflow/skills.toml` (`built-in default → ~/.workflow/skills.toml → .workflow/skills.toml`).
+
+| Role | Default built-in | Composed by |
+|---|---|---|
+| `ui-design` | `ui-spec` | `spec-refine-loop` (cuando hay UI) |
+| `sql` | `sql` | research · `plan-exec-loop` · `quick-loop` |
+| `git` | `git` | `plan-exec-loop` · `quick-loop` |
+| `coding-standards` | `coding-standards` | `plan-exec-loop` · `quick-loop` |
+| `writing` | `writing` | todos los loops |
+| `research` | `research` | todos los loops (research on-demand) |
+| `testing` | `testing` | `plan-exec-loop` · `quick-loop` |
+| `tools` | `tools` | `plan-exec-loop` |
+| `overview` | `workflow` | cualquiera (orientación) |
+
+`off` en config → capacidad desactivada: el loop sigue sin ella; si era necesaria, lo dice o pregunta al humano.
+
+## Index
+
+- [`spec-refine-loop/SKILL.md`](spec-refine-loop/SKILL.md) — el chasis
+- [`plan-new-loop/SKILL.md`](plan-new-loop/SKILL.md)
+- [`plan-exec-loop/SKILL.md`](plan-exec-loop/SKILL.md)
+- [`quick-loop/SKILL.md`](quick-loop/SKILL.md)

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.