@tacuchi/agent-workflow-cli 12.4.0 → 12.6.0

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

@@ -1,43 +1,43 @@
 ---
 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.
+  Ejecuta un plan de implementación (docs/plans/PPP-plan-<slug>.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 inline con
+  regla BD read-only, structured-choice con ≤3 preguntas de contenido + 1 control flow
+  (Compactar/Cerrar) siempre, y artefactos como log vivo (CHECKPOINT siempre,
+  BACKLOG solo si difiere). Sus deltas: una sola session por run (resume vía
+  checkbox del plan-doc + CHECKPOINT); 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.
+> **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 inline, structured-choice + control `flow`, compact/resume, artefactos como log vivo) vive en el chasis.
 
 ## Flow
-PLANIFICATION
+PLAN
 
 ## 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).
+`/w:plan-exec` — **reanudable** (mismo mecanismo del chasis; aquí el resume keya off el checkbox del plan-doc + CHECKPOINT, ver Delta 1).
 
 ## Reads
-`docs/plans/PPP-plan.md`
+`docs/plans/PPP-plan-<slug>.md` (localizar vía glob `docs/plans/PPP-plan-*.md` o la ruta exacta del argumento del comando).
 
 ## Writes
-- `docs/plans/PPP-plan.md` (**read/update**, living doc: estado de fases/tareas, `Open questions`).
+- `docs/plans/PPP-plan-<slug>.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`, …).
+- Artefactos de la plan-exec session en `.workflow/sessions/` (`SCRIPTS.sql`, `DECISION`, `ANALYSIS-FILE`/`CONCLUSIONS`, …).
 - **NO** escribe en otras carpetas `docs/` ni **gradúa/exporta** otros artefactos automáticamente (ver *Boundary*).
 
 ## Boundary — sin auto-export (hard rule)
@@ -48,10 +48,10 @@ Este loop **nunca gradúa/promueve artefactos** a `docs/`. Las únicas carpetas
 
 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`.
+- Motor **gap-driven** (aplica *dentro de una tarea* ante una decisión/duda no obvia: research inline ó structured-choice).
+- **Structured-choice**: ≤3 preguntas de contenido + 1 control `flow` (`Compactar`/`Cerrar`) siempre (capacidad del arnés — ver [`../../harness/SKILL.md`](../../harness/SKILL.md); en Claude Code es `AskUserQuestion`).
+- **Research INLINE** + **regla BD** read-only (pregunta MCP si >1 sin default → `SCRIPTS.sql` → ejecuta read-only) + research **inconclusa** (degrada/difiere, límite `MAX`).
+- **Compact/resume**; **artefactos como log vivo** (`CHECKPOINT` siempre; `BACKLOG` solo si difiere).
 
 ## Composes
 
@@ -59,25 +59,26 @@ Del chasis [`spec-refine-loop`](../spec-refine-loop/SKILL.md), sin cambios:
 
 ## Internal sessions (managed)
 
-- **control session** descriptor `plan-exec` → `NNN-plan-exec`: dueña del run (`SESSION` + `CHECKPOINT` + `BACKLOG` al cerrar; Type = `control`).
-- **exec session por fase** descriptor `plan-exec-phase-<N>` → `NNN-plan-exec-phase-<N>`: `SESSION` · `DECISION` · `SCRIPTS.sql` · `CHECKPOINT` (Type = `exec`).
-- **research session** descriptor `plan-exec-research-*` → `NNN-plan-exec-research-*`: on-demand (run-and-close), igual que el chasis.
+- **plan-exec session** descriptor `plan-exec` → `NNN-plan-exec`: **una sola session por run** (Type = `exec`). Dueña del run; posee `SESSION` + `CHECKPOINT` + `DECISION` + `SCRIPTS.sql` (+ `BACKLOG` solo si difiere). La investigación es **inline** dentro de esta session: produce `ANALYSIS-FILE`/`CONCLUSIONS` (+ `SCRIPTS.sql` read-only si consulta BD) en su propia carpeta.
 
-> **Numeración**: el caller pasa solo el descriptor; el CLI antepone el `NNN` global y secuencial sobre `.workflow/sessions/` (ver chasis). No reinicia por tipo ni por fase.
+> **Numeración**: el caller pasa solo el descriptor; el CLI antepone el `NNN` global y secuencial sobre `.workflow/sessions/` (ver chasis). No reinicia por tipo.
 
-## Delta 1 — **One exec session per phase** (+ resume intra-fase)
+> **Compat (legacy):** workspaces viejos pueden tener sessions `plan-exec-phase-*` (una por fase) y `*-research-*` — son históricas y se dejan tal cual; los runs nuevos usan una sola session.
 
-- 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; el CLI antepone el `NNN` global).
+## Delta 1 — One session per run; per-phase progress in the plan-doc
+
+- Recorre las `Phases` del plan en orden (respeta deps) **dentro de la única session del run** (no hay session-por-fase).
+- El **avance por fase vive en el plan-doc** (`- [x]`) y en el `CHECKPOINT` único (Completed/Pending/Next): **artifact-first** — `CHECKPOINT.Next` se fija a la fase inminente **antes** de iniciarla; el checkbox `- [x]` del plan-doc se voltea **después** de completar la tarea.
 - 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**.
+- En **cada límite de fase**: actualiza el `CHECKPOINT` (Completed += Phase N, Next = Phase N+1) y propone commits.
+- Registra `DECISION` solo lo **no obvio**, **a medida que se toma** (los `DECISION` por fase se acumulan en el ÚNICO `DECISION`, etiquetados por fase/tarea — ej. `Origin: T2 (F1)`).
 
 ## 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.
+- **Precondición entre fases**: `branch-check` valida *identidad* de rama, **no** *limpieza* del working tree. Antes de iniciar 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**
 
@@ -94,23 +95,25 @@ Distinción por **ejecución**, no por archivo (ver el esquema `SCRIPTS.sql`):
 - 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".)
 
+> La **validación final** es el **convergence gate** de PLAN-exec (análogo al *analyze gate* de SPEC y al *coherence gate* de `plan-new`): el plan no se marca *done* hasta que pasa o queda explícitamente diferida (handoff de SQL).
+
 ## 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-*`.
+- Todas las fases done → *structured-choice* final (contenido: `Marcar plan done` / `Preguntar algo más`; flow: `Compactar`/`Cerrar`).
+- **Sin export automático**: los artefactos (`SCRIPTS.sql`, `DECISION`, …) quedan en la session. Promoverlos a `docs/` (scripts, manuals, …) es un paso aparte vía `export-*`.
 
 ## Sequence
 
 ```
-plan-exec-loop(PPP-plan.md):
-  control = create_or_resume("plan-exec")                  # CLI antepone NNN global; CHECKPOINT, resume
-  plan = read(PPP-plan.md)
+plan-exec-loop(PPP-plan-<slug>.md):
+  session = create_or_resume("plan-exec")                  # UNA sola session por run; CLI antepone NNN global; CHECKPOINT, resume
+  plan = read(PPP-plan-<slug>.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
+    si Phase done (todas sus Tasks - [x] en el plan): skip # resume vía checkbox del plan-doc
+    seed CHECKPOINT.Next = Phase N (Pending = sus Tasks)   # ANTES de iniciar la fase: sembrar intención (artifact-first)
     para cada Task de la Phase:
-      si Task - [x] en el plan: skip                       # resume intra-fase
+      si Task - [x] en el plan: skip                       # resume intra-fase por checkbox
       verificar rama esperada por fuente (branch-check)
         si no coincide → pausar + resolver con humano
       ejecutar Task:
@@ -118,29 +121,28 @@ plan-exec-loop(PPP-plan.md):
         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
+        si decisión no obvia → DECISION (etiquetado por fase/tarea, en el ÚNICO DECISION)
+        si duda/gap → research inline ó structured-choice    # chasis
+      marcar Task - [x] + estado EN EL PLAN                # DESPUÉS de completar la Task (el plan-doc es la fuente de verdad por tarea)
     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)
+    update CHECKPOINT (Completed += Phase N, Next = Phase N+1) # DESPUÉS: Pending→Completed + Next = fase siguiente (ver ciclo artifact-first)
     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])
+  structured_choice(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
+  # NO export: los artefactos quedan en la session; un export-* los promueve aparte
+finalize: CHECKPOINT (+ BACKLOG si difiere) + cerrar session + reportar
 ```
 
 ```mermaid
 flowchart TD
-    S["create_or_resume control session<br/>read PPP-plan.md"] --> P{"¿más Phases<br/>(no done)?"}
+    S["create_or_resume plan-exec session (única)<br/>read PPP-plan-&lt;slug&gt;.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])?"}
+    P -->|sí| 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"]
@@ -148,16 +150,16 @@ flowchart TD
     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"]
+    VP --> CK["update CHECKPOINT (Completed/Next)"]
+    CK --> CM["proponer commits por fuente"]
+    CM -->|aprobado| P
     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)"]
+    RJ --> P
+    V2 --> FIN["structured-choice[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.
+- `Cerrar` (control `flow`, en cualquier momento) → `finalize` persiste `CHECKPOINT` (y `BACKLOG` solo si quedó algo sin ejecutar / sin commitear / sin aplicar), cierra la session, 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

@@ -1,77 +1,83 @@
 ---
 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
+  Genera un plan de implementación rico (docs/plans/PPP-plan-<slug>.md) a partir
+  de un spec (docs/specs/NNN-spec-<slug>.md). Heir del chasis spec-refine-loop:
+  reusa íntegro su motor gap-driven convergente, su única session por run,
+  research INLINE, structured-choice con ≤3 preguntas de contenido + 1 control flow
+  (Compactar/Cerrar) siempre presente, research autónomo con regla BD read-only,
+  y artefactos como log vivo (CHECKPOINT siempre, BACKLOG solo si difiere). 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.
+  dependencias); y una gap taxonomy propia de planificación. Distingue spec
+  refinado de borrador por la presencia de Refinement decisions/Q&A traceability
+  (si faltan → soft-suggest correr spec-refine antes). Lo arranca el comando
+  /w:plan-new y es reanudable. Invocar cuando un spec 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.
+> **Heir** del chasis [`spec-refine-loop`](../spec-refine-loop/SKILL.md). Aquí **solo** los deltas. El motor (gap-driven, sesión única, structured-choice + control `flow`, research inline + regla BD, compact/resume, artefactos como log vivo) vive en el chasis — no se repite.
 
 ## Flow
-PLANIFICATION
+PLAN
 
 ## Layer
 2 — la IA lo corre entero.
 
 ## Started by
-`/w:plan-new` — **reanudable** (mismo mecanismo de 4 casos que el chasis).
+`/w:plan-new` — **reanudable** (mismo mecanismo del chasis, keyado off CHECKPOINT).
 
 ## Reads
-`docs/specs/NNN-spec-refined.md`
+`docs/specs/NNN-spec-*.md` (glob — localiza el spec por número; o la ruta exacta del argumento del comando). **Refinado vs borrador** se distingue por la **presencia** de `## Refinement decisions` / `## Q&A traceability` en el spec: si faltan → **soft-suggest** correr `/w:spec-refine` primero (planificar sobre un spec sólido produce mejores planes), pero el usuario puede proceder.
 
 ## Writes
-`docs/plans/PPP-plan.md` (`generate`; **sobrescribe con confirmación** si existe). Solo escribe `docs/plans` — nunca otras carpetas `docs/` ni auto-export.
+`docs/plans/PPP-plan-<slug>.md` (`generate`; **sobrescribe con confirmación** si existe). Solo escribe `docs/plans` — nunca otras carpetas `docs/` ni auto-export.
+
+> **slug**: kebab-case corto derivado del Requirement del spec — solo `[a-z0-9-]`, ≤ ~5 palabras / ≤ 40 chars. El CLI solo devuelve el número `PPP`; el loop arma el nombre completo. Para localizar planes, glob `docs/plans/PPP-plan-*.md`.
 
 ## 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` (descriptor `plan-new` → `NNN-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 + numeración global** del chasis: `<run>` = descriptor `plan-new`; hijas `--name plan-new-research-<gap>`. El CLI antepone el `NNN` global y secuencial (sin reiniciar por tipo); el caller pasa solo el descriptor.
+- Motor **gap-driven convergente** + **ciclo artifact-first** del chasis (sembrar `CHECKPOINT.Pending/Next` ANTES → `detect_gaps` → resolver → integrar → actualizar `Pending→Completed` DESPUÉS; gaps agotados con límite `MAX` no se re-disparan).
+- **Una sola session por run**: descriptor `plan-new` → `NNN-plan-new` (Type = `refine`): `SESSION` + `CHECKPOINT` (+ `BACKLOG` solo si difiere). La **investigación es inline** dentro de esta session (produce `ANALYSIS-FILE`/`CONCLUSIONS` + `SCRIPTS.sql` read-only en su propia carpeta), no una session aparte.
+- **Structured-choice**: ≤3 preguntas de contenido + 1 control `flow` (`Compactar`/`Cerrar`) siempre (capacidad del arnés — ver [`../../harness/SKILL.md`](../../harness/SKILL.md); en Claude Code es `AskUserQuestion`).
+- **Ask-vs-research rule** + **research autónomo inline** + **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** y **artefactos como log vivo (ciclo artifact-first)** (`CHECKPOINT` siempre; `BACKLOG` solo si difiere).
+- **Naming + numeración global** del chasis: `<run>` = descriptor `plan-new`. El CLI antepone el `NNN` global y secuencial (sin reiniciar por tipo); el caller pasa solo el descriptor.
 
-## Delta 1 — Deliverable: PLAN RICO (`PPP-plan.md`)
+## Delta 1 — Deliverable: PLAN RICO (`PPP-plan-<slug>.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
+> Derivado de docs/specs/NNN-spec-<slug>.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
+## Summary             el cómo, en 1–2 frases                                   (core)
+## Solution            explicación técnica/funcional de cómo se implementará    (core)
+## Impacted            FE · BE · BD (esquemas/tablas/funciones) · APIs · integr. (core)
+## Dependencies        docs / fuentes / bases / sesiones                        (opt.)
+## Current state (AS-IS)   wiring actual (interfaces y métodos), resumido        (opt.)
+## Target state (TO-BE)    wiring objetivo                                       (opt.)
+## Final behavior      cómo se comporta el flujo al final (alineado con criterios del spec) (core)
+## Phases              fases agrupadoras (complejidad XS–S)                      (core)
+## Tasks               tareas por fase (≤XS), con deps y estado vivo (- [ ])     (core)
+## Validations         validaciones / restricciones / lógica de negocio         (core)
+## Risks / impact      riesgos e impactos técnicos                              (opt.)
+## Assumptions         supuestos                                                (opt.)
+## Estimated time      sizing XS–XL (desarrollo + pruebas internas)             (opt.)
+## Open questions      pendientes                                               (core)
 ```
 
-> **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).
+> **Escala con complejidad:** las `(core)` van **siempre**; las `(opt.)` solo si el plan lo amerita — un plan chico puede omitir `Dependencies`, AS-IS/TO-BE, `Risks`, `Assumptions`, `Estimated time`. Conciso > exhaustivo.
+
+> **Implicación de catálogo:** `TECHNICAL-NOTE` deja de ser artefacto de session y se vuelve **secciones del plan-doc**. Reconciliado en [`plan-exec-loop`](../plan-exec-loop/SKILL.md): la única plan-exec session **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")
 
@@ -86,12 +92,12 @@ Reemplaza la gap taxonomy de spec por una orientada a planificación:
 | 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 |
+| Riesgos sin atender | riesgos técnicos sin mitigar/declarar | 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).
+El research **inline** 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 pregunta 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.
+Sin gaps materiales → **coherence gate** (read-only; es el "convergence gate" del chasis para PLAN-new): cada `acceptance criterion` del spec **traza** a una fase/tarea, `Final behavior` los cubre, fases XS–S / tareas XS, `deps` sin ciclos, `Impacted` consistente con `Solution`. Lo que falle **vuelve como gap** — la trazabilidad criterio→tarea es una **invariante chequeada**, no una sección aparte. Si pasa → *structured-choice* (contenido: `Guardar plan` / `Preguntar algo más`; flow: `Compactar`/`Cerrar`) → al `Guardar`, escribe `docs/plans/PPP-plan-<slug>.md` (con confirmación si existe) → `finalize` (persiste `CHECKPOINT`, y `BACKLOG` solo si difiere; cierra la session, reporta). `Cerrar` en cualquier momento → `finalize` igual.

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

@@ -4,16 +4,16 @@ 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.
+  research INLINE con regla BD read-only, structured-choice con ≤3 preguntas de
+  contenido + 1 control flow Compactar/Cerrar siempre, compact/resume con artefactos
+  como log vivo: CHECKPOINT siempre, BACKLOG solo si difiere) 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
@@ -39,21 +39,21 @@ QUICK
 
 ## Internal session
 
-- **SIEMPRE** crea una session ligera con descriptor `<slug>-quick` → `NNN-<slug>-quick` (Type = `quick`, ≈ `exec`): `SESSION` · `DECISION` · `SCRIPTS.sql` · `CHECKPOINT` (+ `BACKLOG` al cerrar). Una sola session (no exec-por-fase). El caller pasa solo el descriptor; el CLI antepone el `NNN` global y secuencial (ver chasis).
+- **SIEMPRE** crea una session ligera con descriptor `<slug>-quick` → `NNN-<slug>-quick` (Type = `quick`, ≈ `exec`): `SESSION` · `DECISION` · `SCRIPTS.sql` · `CHECKPOINT` (+ `BACKLOG` solo si difiere). Una sola session. La investigación es **inline** dentro de ella (`ANALYSIS-FILE`/`CONCLUSIONS` + `SCRIPTS.sql` read-only en su carpeta). El caller pasa solo el descriptor; el CLI antepone el `NNN` global y secuencial (ver chasis).
 
 ## 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`.
+- del **chasis** [`spec-refine-loop`](../spec-refine-loop/SKILL.md): gap-driven (mínimo), *structured-choice* ≤3 preguntas de contenido + 1 control `flow` (`Compactar`/`Cerrar`) (capacidad del arnés — ver [`../../harness/SKILL.md`](../../harness/SKILL.md); en Claude Code es `AskUserQuestion`), `research` **inline** + regla BD read-only (pregunta MCP si >1 sin default → `SCRIPTS.sql` → ejecuta read-only), compact/resume, **artefactos como log vivo (ciclo artifact-first)** (`CHECKPOINT` siempre; `BACKLOG` solo si difiere).
 - 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`.
+`git` · `coding-standards` · `testing` (validación puntual) · `sql` (regla BD) · `writing` · `research` (inline). 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.
+- **Una sola session**. **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í");
@@ -65,25 +65,26 @@ QUICK
 ```
 quick-loop(prompt):
   s = create_or_resume("<slug>-quick")      # CLI antepone NNN global; siempre session ligera
+  seed CHECKPOINT.Pending/Next = la tarea (s)   # ANTES: sembrar intención (artifact-first); SESSION.Objective = el prompt
   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 duda/gap → research inline ó structured-choice         # 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
+  structured_choice(contenido: [Cerrar tarea, Preguntar algo más], flow: [Compactar, Cerrar])
+finalize: CHECKPOINT (DESPUÉS: Pending→Completed) + BACKLOG (solo si queda algo diferido) + cerrar session + reportar
 ```
 
 ```mermaid
 flowchart TD
     S["create_or_resume session NNN-&lt;slug&gt;-quick"] --> G["branch-check por fuente"]
-    G -->|ok| DO["editar código · BD→SCRIPTS.sql · DECISION<br/>(duda→research/AskUserQuestion)"]
+    G -->|ok| DO["editar código · BD→SCRIPTS.sql · DECISION<br/>(duda→research inline/structured-choice)"]
     G -->|rama ≠| PA["pausar + resolver"]
     PA --> G
     DO --> GROW{"¿la tarea creció?"}
@@ -91,12 +92,14 @@ flowchart TD
     ESC --> FIN
     GROW -->|no| V["validación puntual"]
     V --> CM["proponer commit (aprobar)"]
-    CM --> Q["AskUserQuestion[Cerrar · Preguntar más]<br/>flow[Compactar · Cerrar]"]
+    CM --> Q["structured-choice[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).
+- `Cerrar`/`Compactar` (control `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.
+
+> La **validación puntual** es el *convergence gate* de QUICK: la **excepción deliberada lightweight** del chasis (sin checklist formal) — se reduce a "¿el cambio hace lo que pedía el prompt? (test si aplica)". Mínima ceremonia por diseño.