@tacuchi/agent-workflow-cli 14.10.0 → 14.11.0

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

@@ -3,9 +3,10 @@ name: quick-loop
 description: >-
   El atajo liviano de agent-workflow: resuelve una tarea acotada (fix, ajuste
   chico) directamente desde el prompt, editando código con ceremonia mínima.
-  Heir del chasis spec-refine-loop y de plan-exec-loop (git seguro, BD solo-
-  scripts, gate de revisión de cierre proporcional, sin auto-export); sus
-  deltas viven en el cuerpo: sin fases ni plan-doc (el prompt ES la tarea),
+  Heir del chasis común de los loops (loops/CHASSIS.md — motor gap-driven con
+  las políticas de loops que editan código: git seguro, BD solo-scripts, gate
+  de revisión de cierre proporcional, sin auto-export); sus deltas viven en
+  el cuerpo: sin fases ni plan-doc (el prompt ES la tarea),
   session ligera única (<slug>-quick), un solo commit, y escalación con
   handoff a SPEC/PLAN si la tarea crece. NO toca docs/. Lo arranca /w:quick y
   es reanudable. Invocar para cambios pequeños y directos que no ameritan spec
@@ -14,7 +15,7 @@ description: >-
 
 # 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.
+> **Heir** del chasis común — aquí **solo** los deltas de QUICK. El motor vive en el chasis y las *Políticas de loops que editan código* (git · BD · gate proporcional) en `CODE-POLICIES.md` — no se repiten.
 
 ## Flow
 QUICK
@@ -39,8 +40,7 @@ QUICK
 
 ## Inherits
 
-- del **chasis** [`spec-refine-loop`](../spec-refine-loop/SKILL.md): **objetivo persistente** (acá el más directo: el prompt *es* el objetivo) + **verification-first** (`SESSION.Success criteria` proporcional), 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/`), y el **gate de revisión de cierre** (§ *Delta 5* de plan-exec) en versión **proporcional**: antes de proponer el único commit, re-lectura del diff aplicando las convenciones ambientes instaladas → corregir o diferir justificado.
+Leé **[`../CHASSIS.md`](../CHASSIS.md)** (instalación normal) **o** `CHASSIS.md` junto a este archivo (instalación aplanada) — el motor completo del loop (objetivo persistente + verification-first, gap-driven, session única + research inline, structured-choice + control `flow`, compact/resume, artefactos como log vivo, numeración, convergence gate, docs/ boundary) — **y** **[`../CODE-POLICIES.md`](../CODE-POLICIES.md)** (o `CODE-POLICIES.md` junto a este archivo) — las *Políticas de loops que editan código* (git seguro · BD solo-scripts · gate de revisión de cierre **proporcional**) — **siempre antes** de estos deltas.
 
 ## Composes
 
@@ -51,10 +51,11 @@ QUICK
 ## Delta QUICK — minimal ceremony
 
 - **Sin fases, sin plan-doc**: el prompt **es** la tarea (una sola unidad). No hay roadmap.
-- **Verification-first proporcional** (ceremonia mínima): aun acá se **siembra el check antes**, del tamaño de la tarea. Código: un test (repro del bug → fix) o "build/lint/tests existentes siguen verdes" (chore). **Análisis/diseño**: una **rúbrica falsable corta**, *ratificada por el usuario* antes de perseguirla. Es el `SESSION.Success criteria` del run (ver [chasis § Verification-first](../spec-refine-loop/SKILL.md)).
-- **Una sola session**. **Un solo commit** propuesto al final (solo si hubo cambios de código), **tras el gate de revisión de cierre proporcional** (heredado de plan-exec § *Delta 5*): re-lectura del diff + convenciones ambientes; corregir o diferir; nada llega al commit sin revisar.
+- **Verification-first proporcional** (ceremonia mínima): aun acá se **siembra el check antes**, del tamaño de la tarea. Código: un test (repro del bug → fix) o "build/lint/tests existentes siguen verdes" (chore). **Análisis/diseño**: una **rúbrica falsable corta**, *ratificada por el usuario* antes de perseguirla. Es el `SESSION.Success criteria` del run (ver [chasis § *Verification-first*](../CHASSIS.md)).
+- **Git y BD inline** (políticas completas en [`../CODE-POLICIES.md`](../CODE-POLICIES.md)): antes de editar, verificar rama esperada por fuente (`aw check-branch`); commit **propuesto** (aprobar antes) — nunca `push`/`--amend`/`--no-verify`. La IA **nunca ejecuta DML/DDL**: las migraciones se redactan en el `SCRIPTS.sql` de la session (consultas read-only sí, vía MCP).
+- **Una sola session**. **Un solo commit** propuesto al final (solo si hubo cambios de código), **tras el gate de revisión de cierre proporcional** ([`../CODE-POLICIES.md`](../CODE-POLICIES.md) § *Gate de revisión de cierre*): re-lectura del diff + convenciones ambientes; corregir o diferir; nada llega al commit sin revisar.
 - **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;
+  - 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" ([`../CODE-POLICIES.md`](../CODE-POLICIES.md) § *Git seguro*: 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.
@@ -95,22 +96,6 @@ quick-loop(prompt):
 finalize: CHECKPOINT (DESPUÉS: Pending→Completed) + BACKLOG (solo si queda algo diferido) + cerrar session + reportar
 ```
 
-```mermaid
-flowchart TD
-    S["create_or_resume NNN-&lt;slug&gt;-quick<br/>seed Objective + Success criteria (verification-first)"] --> G["branch-check (si edita código)"]
-    G -->|ok| DO["producir deliverable: código Ó análisis/diseño<br/>BD→SCRIPTS.sql · DECISION · (duda→research/structured-choice)"]
-    G -->|rama ≠| PA["pausar + resolver"]
-    PA --> G
-    DO --> GROW{"¿la tarea creció?"}
-    GROW -->|sí| ESC["escalar a SPEC/PLAN<br/>avance queda · BACKLOG→spec/plan sembrado"]
-    ESC --> FIN
-    GROW -->|no| V["convergence gate:<br/>Success criteria en verde"]
-    V --> RV["si hubo código → gate de revisión de cierre<br/>(diff + convenciones ambientes → corregir/diferir)"]
-    RV --> CM["proponer commit (aprobar)"]
-    CM --> Q["structured-choice[Cerrar · Preguntar más]<br/>flow[Compactar · Cerrar]"]
-    Q --> FIN["finalize: CHECKPOINT + BACKLOG + cerrar"]
-```
-
 ## Convergence / exit
 
 - **Success criteria en verde** (proporcional) + gate de revisión de cierre pasado y commit propuesto si hubo código (o aprobado saltarlo) → `Cerrar`.

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

@@ -1,24 +1,26 @@
 ---
 name: spec-refine-loop
 description: >-
-  El CHASIS de los loops de agent-workflow. Refina un spec borrador
-  (docs/specs/NNN-spec-<slug>.md) editándolo IN PLACE hasta dejarlo sin
-  ambigüedad, 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 INLINE en la propia session
-  (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 vía
-  CHECKPOINT. Usa structured-choice con ≤3 preguntas de contenido + 1 control flow
-  (Compactar/Cerrar) siempre presente; mantiene sus artefactos como log vivo
-  (CHECKPOINT siempre, BACKLOG solo si difiere). 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.
+  Refina un spec borrador (docs/specs/NNN-spec-<slug>.md) editándolo IN PLACE
+  hasta dejarlo sin ambigüedad. Heir del chasis común de los loops
+  (loops/CHASSIS.md — motor gap-driven convergente: session única con research
+  inline, structured-choice ≤3 preguntas + control flow, artefactos como log
+  vivo, compact/resume, convergence gate); aquí viven solo sus deltas SPEC:
+  gap taxonomy de spec, analyze gate, sección ## UI spec vía la capacidad
+  ui-design cuando el requerimiento involucra UI, y agrega Refinement
+  decisions + Q&A traceability al spec — la marca de refinado que plan-new
+  detecta. Lo arranca /w:spec-refine; reanudable vía CHECKPOINT y re-corrible
+  a demanda. 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í.
+> **Heir** del chasis común — aquí **solo** los deltas de SPEC. El motor no se repite.
+
+## Inherits
+
+Leé **[`../CHASSIS.md`](../CHASSIS.md)** (instalación normal) **o** `CHASSIS.md` junto a este archivo (instalación aplanada) — el motor completo del loop (objetivo persistente + verification-first, gap-driven, session única + research inline, structured-choice + control `flow`, compact/resume, artefactos como log vivo, numeración, convergence gate), **siempre antes** de estos deltas.
 
 ## Flow
 SPEC
@@ -27,7 +29,7 @@ SPEC
 2 — la IA lo corre entero (gap-driven). El usuario no conduce el ciclo; solo responde preguntas de contenido y dirige el ciclo de vida por el control `flow`.
 
 ## Started by
-`/w:spec-refine` — **reanudable**. Detecta el estado previo (vía CHECKPOINT) y arranca según corresponda (ver *Compact / resume*).
+`/w:spec-refine` — **reanudable**. Detecta el estado previo (vía CHECKPOINT) y arranca según corresponda (ver *Compact / resume — claves SPEC*).
 
 ## Reads
 - `docs/specs/NNN-spec*.md` (glob — localiza el spec por número, también captura el legacy `NNN-spec.md`), **o** la ruta exacta pasada en el argumento del comando. **Siempre el spec mismo**: este loop lo edita in place, no hay un archivo "refined" aparte.
@@ -35,97 +37,25 @@ SPEC
 ## Writes
 Actualiza `docs/specs/NNN-spec-<slug>.md` **in place** (cuando el usuario elige `Guardar especificación refinada`): completa secciones y **agrega** `## Refinement decisions` + `## Q&A traceability`, cerrando `Open questions` a medida que se resuelven. Como sobrescribe un doc existente, **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.
-
-## Objetivo persistente (chasis — heredado por todos los loops)
-
-Un loop **es un objetivo persistente**: existe para cumplir el `SESSION.Objective` declarado al arrancar, y **no se considera terminado hasta que el convergence gate confirma que el objetivo se cumplió**. La iteración gap-driven es el *método*; los artefactos son el *registro*; el objetivo persistente es el *frame* que los gobierna.
-
-Está **modelado en cómo se comporta el `/goal` de Claude Code** (declarás un objetivo, el agente no para hasta cumplirlo, auto-completa al cumplirse, con corte explícito para abortar antes) pero como **doctrina agnóstica, no una dependencia del host**: el "no parar hasta converger" lo sostiene el propio loop (su `repeat:` + el convergence gate), no un Stop hook del arnés — ningún host necesita `/goal`. Y, a diferencia del `/goal` pelado, **deja registro durable** (artifact-first) que sobrevive compactación y resume.
-
-| Comportamiento de `/goal` (ejemplo) | Análogo agnóstico en el loop |
-|---|---|
-| declarar el objetivo | `SESSION.Objective` |
-| no parar hasta cumplirlo | `repeat:` gap-driven hasta `gaps == ∅` |
-| objetivo cumplido → auto-clear | **convergence gate** pasa → `finalize` |
-| `/goal clear` (abortar antes) | control `flow` `Cerrar` |
-| la directiva sobrevive el contexto | `CHECKPOINT` + resume (compactación **y próximo prompt**) |
-
-> Los heirs heredan el frame: `plan-new`/`plan-exec` persiguen el plan hasta su gate; `quick-loop` es la encarnación más directa (el prompt *es* el objetivo) — el "símil a `/goal`" del modelo.
-
-> **Continuidad inter-turno (contexto operativo).** El mismo `CHECKPOINT`+resume que sobrevive la compactación gobierna también el **próximo prompt**: dentro de un workspace, un prompt **sin comando** **continúa/reabre la sesión más reciente** (la *última iniciada*) en vez de arrancar trabajo suelto — el objetivo persiste **entre turnos**, no solo dentro del run. Un **comando de flujo** señala "nueva línea de trabajo" (sesión nueva) — **salvo re-correr el mismo flujo sobre la misma entrada** (mismo spec), que hace `create_or_resume`: reanuda/reabre la refine session existente en vez de duplicarla (ver *Compact / resume*, caso 3); la convergencia cierra la sesión y un prompt relacionado posterior la **reabre** (resume quita `.closed`). Es la fila 2 de la matriz de contexto operativo (ver [`../../SKILL.md`](../../SKILL.md) § *Contexto operativo*) — doctrina agnóstica que la IA evalúa en cada turno, no un Stop hook del host.
-
-## Verification-first (chasis — heredado por todos los loops)
-
-El objetivo persistente necesita una **condición de término checkable** — si no, el loop no sabe cuándo cumplió (o persigue un blanco que inventó). Esa condición se **siembra ANTES de ejecutar**, no se improvisa al final: es **TDD generalizado**. Junto con artifact-first (sección siguiente) son los **dos sembrados** de cada gap/fase: *cómo sabré que funcionó* + *qué voy a hacer*.
-
-**Dónde vive:** en `SESSION.Success criteria` (ver [`../../artifacts/artifacts-core/SESSION.md`](../../artifacts/artifacts-core/SESSION.md)) — checklist `[ ]` de criterios **falsables** (que *pueden* fallar). `CHECKPOINT.Pending/Completed` trackea el avance **red→green**. Dos formas según el deliverable:
-
-| Deliverable | Criterio = | Ciclo |
-|---|---|---|
-| código / script / fix / feature | **tests ejecutables** (unit, build, lint, repro del bug) | TDD literal: red → green → refactor |
-| migración BD (no ejecutable; invariante 4) | **rúbrica**: `SCRIPTS.sql` válido + revisado (no se ejecuta) | rúbrica |
-| spec / plan | **rúbrica** = los acceptance criteria del documento (referenciados, no duplicados) | rúbrica |
-| análisis / diseño | **rúbrica falsable por inspección** (ej. "todos los afectados con `file:line`"; "cada decisión: rationale + ≥1 alternativa") | rúbrica |
-
-**Forma y peso escalan** (preserva la *ceremonia mínima* de quick): un chore es "tests/build existentes siguen verdes" (una línea); un feature, acceptance tests reales. No es "siempre escribir tests nuevos" — es "**siempre declarar el check antes**". Para deliverables **subjetivos** (análisis/diseño) la IA **propone** la rúbrica y el **humano la ratifica** (structured-choice) antes de perseguirla. **Criterio irresoluble** (sin evidencia, BD no disponible) → cierra `inconcluso` + el loop **degrada** (humano, o difiere a `Open questions`/`BACKLOG`); nunca itera en falso.
-
-> El **convergence gate** (sección *Convergence / exit*) es, operacionalmente, **"todos los `Success criteria` en verde"**. Los gates por-heir (analyze gate, coherencia del plan, validación final, validación puntual proporcional) son **instancias** de esto, con los criterios sembrados al inicio.
-
-**Integridad del gate (anti-gaming + verificación independiente).** El gate solo vale si no se hace trampa para pasarlo. El loop **no**:
-
-- modifica el check ni afloja un `Success criterion` para forzar verde;
-- debilita, borra ni saltea tests/validaciones;
-- usa asserts triviales o tautológicos que siempre pasan (el valor esperado sale de una fuente independiente, no del propio output);
-- parchea el test en lugar de arreglar la causa (preferir arreglar producción).
-
-Ante un blocker real **para y lo reporta** (→ `Open questions`/`BACKLOG`) en vez de gamear la métrica. El veredicto cuenta **solo el output del check, no la auto-declaración** del implementador: cuando el deliverable lo justifica, la verificación final la hace una pasada **independiente** (subagente o re-lectura limpia) que no asume correcta la implementación — *only command output counts*.
-
-## Artifacts as a live log — ciclo artifact-first (chasis — heredado por todos los loops)
-
-El loop trabaja **artifact-first**: el artefacto se **siembra antes** de ejecutar y se **actualiza después**, no solo al cerrar. Cada gap/fase/tarea corre el ciclo de **3 tiempos**:
-
-1. **ANTES — sembrar la intención.** Antes de ejecutar, deja en el artefacto lo que se **va a** hacer: `CHECKPOINT.Pending`/`Next` = el trabajo inminente (`SESSION.Objective` ya fijó el qué del run).
-2. **EJECUTAR.** Resolver el gap / correr la fase / editar el código.
-3. **DESPUÉS — llevar al estado real.** `CHECKPOINT.Pending → Completed`; `DECISION` lo no obvio **a medida que se toma**; `BACKLOG` **solo si** algo queda diferido/followup (`session-close` ya no fabrica un BACKLOG vacío).
+> **Invariante de boundary:** este loop escribe **solo** en `docs/specs`. Nunca gradúa/exporta otros artefactos a `docs/` — eso es trabajo de `export-*`, aparte (chasis § *docs/ boundary*).
 
-> El artefacto expresa la **intención** (Pending/Next, antes) y luego el **resultado** (Completed/DECISION, después), en **cada** límite de gap/fase — no solo al `Compactar`/`Cerrar`. Los artefactos de session son el registro vivo del run; el spec/plan es la **base guía**.
+## Internal sessions — instancia SPEC
 
-## Internal sessions (managed)
-
-El loop crea y maneja su session en `.workflow/sessions/`. El usuario nunca la crea.
+Doctrina completa en el chasis (§ *Internal sessions* + *Numeración*). La instancia de este loop:
 
 | Session | When | Artifacts | Role |
 |---|---|---|---|
-| **refine session** `NNN-<slug>-spec-refine/` | al arrancar el loop (o se reanuda) | `SESSION.md` · `CHECKPOINT.md` (· `BACKLOG.md` solo si difiere) | Dueña del run. Mantiene el avance vivo (CHECKPOINT) y habilita el resume. Type = `refine`. |
-
-> **Research INLINE** — la investigación ya **no** es una session aparte: es una actividad **dentro de la session actual** que escribe sus artefactos (`ANALYSIS-FILE`/`CONCLUSIONS`, + `SCRIPTS.sql` read-only si consulta BD) **en la carpeta de la propia session del run**. Ver *Research: autonomy, scope & failure*.
-
-> El spec **nunca** entra en una session; vive en `docs/specs/`.
+| **refine session** `NNN-<slug>-spec-refine/` | al arrancar el loop (o se reanuda) | `SESSION.md` · `CHECKPOINT.md` (· `BACKLOG.md` solo si difiere) | Dueña del run. Type = `refine`; descriptor `<slug>-spec-refine` (el `<slug>` sale del spec de entrada). |
 
 > **Compat (legacy):** workspaces viejos pueden tener `NNN-spec.md` / `NNN-spec-refined.md` y sessions `*-research-*` aparte — son históricos y se dejan tal cual. El glob `NNN-spec*.md` igual encuentra el spec base, y re-correr spec-refine lo edita in place de ahí en adelante.
 
-### Numeración de sessions (regla dura, heredada por todos los loops)
-
-El **CLI es dueño del número**: `aw session-create` antepone un `NNN` **global y secuencial** escaneando **todas** las sessions de `.workflow/sessions/` (cualquier tipo). El caller pasa **solo el descriptor** vía `--name` — **nunca** un número. Así la numeración no se reinicia por tipo ni colisiona, y cada folder queda **autodescriptivo** con la forma `NNN-<slug>-<flow>` (ej.: `002-correo-otp-spec-refine`, `003-correo-otp-plan-new`, `004-correo-otp-plan-exec`, `005-validacion-correo-quick`).
-
-> `<run>` = el **descriptor** (sin número) de la session del run, siempre con forma **`<slug>-<flow>`**: `<slug>-spec-refine`, `<slug>-plan-new`, `<slug>-plan-exec`, `<slug>-quick`. El `<slug>` es **descriptivo** y sale del doc de entrada del flujo — `docs/specs/NNN-spec-<slug>.md` para spec-refine/plan-new; `docs/plans/PPP-plan-<slug>.md` para plan-exec; el prompt para quick — para que el folder diga de un vistazo de qué trata, no solo qué flujo lo creó. Como la investigación es **inline** en esta misma session, ya no hay sessions hijas `*-research-*` que numerar (compat: las viejas son históricas).
->
-> **Resume**: localiza la session existente **escaneando** `.workflow/sessions/` por descriptor + `## Origin` (qué spec/plan), **no** reconstruyendo el número (que es global, no derivable del artefacto). `aw session-resume --code <NNN | folder>` resuelve ambas formas.
-
-**CLI**:
-- `aw session-create --type refine --name <slug>-spec-refine` → crea `NNN-<slug>-spec-refine` / `aw session-resume --code <…>` (detecta `CHECKPOINT`).
-- `aw checkpoint-write` / `aw checkpoint-read` para el resume.
-- `aw session-close` al cerrar (con razón); `aw session-artifacts` para inspeccionar.
-- **Reabrir para continuar** (contexto operativo, fila 2): `aw session-resume --code <NNN> --reopen` reactiva una sesión **cerrada** (quita `.closed` → activa) para seguir trabajando en ella; sin `--reopen`, el resume es read-only. Para detectar cuál es la más reciente cerrada: `aw resume-summary --include-recent-closed` (o `aw sessions --state all`).
-
 ## Composes
 
 El gap **UI sin especificar** (cuando el requerimiento involucra UI; ver *Gap taxonomy*) se resuelve **componiendo** la capacidad **`ui-design`** (default built-in `ui-spec`; rebindeable vía `.workflow/skills.toml`): autora el UI spec nativamente (estructura, vocabulario, formato Markdown). Es un tercer modo de resolución de gap (junto a *research* y *humano*): el loop aporta la iteración/Q&A que el viejo servicio no tenía (design-system, tema, variantes, desambiguación) **vía la misma structured-choice**, y lo integra como sección `## UI spec` del spec.
 
 > **Dos niveles de la misma capacidad:** aquí (SPEC) produce la sección `## UI spec` del spec — el *qué* de la UI, grano grueso. En PLAN, `plan-new-loop`/`plan-refine-loop` componen la **misma** capacidad para producir **design SPECs por pantalla** (`NNN-SPEC-<SLUG>.md`, artefactos de su sesión — ver [`SPEC.md`](../../artifacts/artifacts-design/SPEC.md)), derivados de esta sección si existe.
 
-Otras capacidades transversales que el chasis usa siempre: `research` (research **inline**, ver abajo), `sql` (regla BD en research). Todas se resuelven por config; `off` → el loop sigue sin la capacidad y, si era necesaria, lo dice o pregunta. La **prosa del spec** sigue las convenciones de redacción **ambientes** (el host auto-aplica una skill de writing instalada si está presente), no un rol compuesto.
+Otras capacidades transversales que el motor usa siempre: `research` (research **inline** — chasis § *Research*), `sql` (regla BD en research — chasis). Todas se resuelven por config; `off` → el loop sigue sin la capacidad y, si era necesaria, lo dice o pregunta. La **prosa del spec** sigue las convenciones de redacción **ambientes** (el host auto-aplica una skill de writing instalada si está presente), no un rol compuesto.
 
 > **Convenciones ambientes (no roles):** estándares de código/testing/redacción y `creating-tools` son skills standalone que el host auto-descubre por su `description` — el workflow no las bindea ni depende de ellas. Doctrina completa: [../../roles/README.md](../../roles/README.md).
 
@@ -177,41 +107,6 @@ Cada duda preguntada al humano + la respuesta elegida.
 | Contradicción interna | secciones que se contradicen | **humano** |
 | UI sin especificar *(si aplica)* | el requerimiento involucra UI pero falta `## UI spec` | **capacidad `ui-design`** |
 
-## 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** (structured-choice).
-
-## Research: autonomy, scope & failure
-
-La investigación es **inline**: una actividad **dentro de la session actual del run**, no una session aparte. Escribe sus artefactos (`ANALYSIS-FILE` → `CONCLUSIONS`, + `SCRIPTS.sql` read-only si consulta BD) en la **carpeta de la propia session**.
-
-- **Autónomo**: la IA investiga inline y reporta **sin pedir permiso**. El humano se entera al integrarse (en `Refinement decisions`) y mantiene control vía el control `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 la **misma structured-choice** como una **pregunta 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 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 investigación concluye con estado **`inconcluso`** en `CONCLUSIONS` y reporta el motivo.
-  - 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 spec.
-  - 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.
-
-## Structured-choice (design & batching)
-
-*structured-choice* (capacidad del arnés — ver `../../harness/SKILL.md`). En **Claude Code** es `AskUserQuestion` (máx 4 preguntas/llamada → **≤3 preguntas de contenido + 1 control `flow`**); en un arnés sin elección estructurada, degrada a **markdown numerado**.
-
-- Como el control `flow` va **siempre** → **≤3 preguntas de contenido + 1 control `flow`**.
-- **control `flow`** (ciclo de vida, siempre presente): `Compactar` | `Cerrar`. Responder solo las preguntas de contenido (sin tocar `flow`) = seguir iterando.
-- **Preguntas 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.
-- **Respuesta recomendada por pregunta**: cada pregunta de contenido lleva **siempre** la respuesta que la IA recomienda — como primera opción (marcada *recomendada*) en `AskUserQuestion`, o señalada en el markdown numerado al degradar. Nunca se pregunta "a secas": el humano ratifica o corrige una propuesta, no parte de cero. La IA recomienda en base a lo investigado (regla ask-vs-research), no por defecto vacío.
-
 ## Sequence
 
 ```
@@ -237,7 +132,7 @@ spec-refine-loop(spec):
         si no: attempts[gap]++ ; si attempts[gap] >= MAX → pending_human.push(gap)
       si no:
         pending_human.push(gap)
-    update CHECKPOINT (refine_session)        # DESPUÉS: Pending→Completed, en cada límite de gap (ver ciclo artifact-first)
+    update CHECKPOINT (refine_session)        # DESPUÉS: Pending→Completed, en cada límite de gap (chasis § ciclo artifact-first)
     si pending_human no vacío:
       ans = structured_choice(contenido: pending_human (≤3), flow: [Compactar, Cerrar])
       switch(flow):
@@ -258,46 +153,18 @@ finalize:
   cerrar refine_session ; reportar
 ```
 
-```mermaid
-flowchart TD
-    S["input = glob NNN-spec*.md (el spec mismo)<br/>create_or_resume refine session"] --> D{"¿gaps<br/>(no agotados)?"}
-    D -->|no| AN{"analyze gate<br/>criterios↔Requirement · sin contradicciones<br/>Scope · Open questions cerradas/diferidas"}
-    AN -->|falla| D
-    AN -->|ok| C["structured-choice<br/>contenido[Guardar refinada · Preguntar más]<br/>flow[Compactar · Cerrar]"]
-    D -->|sí| B["tomar ≤3 gaps"]
-    B --> K{"tipo de gap"}
-    K -->|UI| UI["componer ui-design<br/>→ ## UI spec (design-system/tema vía structured-choice)"]
-    K -->|factual y attempts&lt;MAX| RS["research INLINE en la session<br/>ANALYSIS-FILE → CONCLUSIONS (+SCRIPTS.sql)"]
-    K -->|humano| Q["structured-choice<br/>contenido[dudas + elección MCP ≤3]<br/>flow[Compactar · Cerrar]"]
-    RS --> CC{"¿concluyente?"}
-    CC -->|sí| I1["integrar → Refinement decisions"]
-    CC -->|no| DEG["attempts++ ; degradar a humano / Open questions"]
-    Q --> I2["integrar → Q&A traceability"]
-    UI --> CK["update CHECKPOINT (Pending→Completed)"]
-    I1 --> CK
-    DEG --> CK
-    I2 --> CK
-    CK --> D
-    C -->|Guardar| W["edit IN PLACE con confirmación<br/>completa + inserta UI spec/Refinement decisions/Q&A"]
-    C -->|Preguntar más| D
-    W --> FIN["finalize: CHECKPOINT (+ BACKLOG si difiere)<br/>+ cerrar session + reportar"]
-```
-
-## Compact / resume
-
-El resume **keya off el `CHECKPOINT`** de la refine session, no de la existencia de un archivo "refined". Tres casos al ejecutar `/w:spec-refine` sobre un spec:
+## Compact / resume — claves SPEC
 
-1. **En curso** (existe `CHECKPOINT.md` en la refine session) → reanuda desde el avance (gaps resueltos, Q&A, `attempts`, research inline en curso).
-2. **Sin avance** (no hay CHECKPOINT y el spec **no** tiene `Refinement decisions`/`Q&A traceability`) → arranca desde cero leyendo el spec (`NNN-spec*.md`).
-3. **Ya refinado / re-refine on demand** (no hay CHECKPOINT abierto pero el spec **ya tiene** `Refinement decisions`/`Q&A traceability`) → **operación de primera clase**: mientras el flujo siga en SPEC, re-correr `/w:spec-refine` sobre el mismo spec **cuantas veces haga falta** (nuevos requerimientos, cambios de scope, tras re-leerlo) está soportado. `create_or_resume` detecta la refine session existente —típicamente **cerrada** tras converger— por descriptor + `## Origin` y la **reabre** (ver *Internal sessions*: detección con `aw sessions --state all` / `aw resume-summary --include-recent-closed`, reapertura con `aw session-resume --code <NNN> --reopen`); re-refinamiento incremental leyendo el **spec mismo**; al `Guardar`, edita in place con confirmación.
+Mecanismo completo (3 casos, `Compactar`, re-run on demand con `--reopen`) en el chasis (§ *Compact / resume*). Claves SPEC:
 
-> **`Compactar`** (control `flow`, transversal a los 3 casos) → escribe `CHECKPOINT.md` en la refine session (spec en progreso, gaps restantes, Q&A, `attempts`) → dispara la **compactación** del arnés (en Claude Code: `/compact`; ver `../../harness/SKILL.md`) → reanuda leyendo el checkpoint.
+- La **marca de trabajo previo** es la presencia de `## Refinement decisions` + `## Q&A traceability` en el spec (la *marca de refinado*, ver *Deliverable schema*).
+- El re-refine on demand es **operación de primera clase** mientras el flujo siga en SPEC (nuevos requerimientos, cambios de scope, tras re-leer el spec): lee siempre el **spec mismo**, re-refinamiento incremental; al `Guardar`, edita in place con confirmación.
 
 ## Convergence / exit
 
-- **Sin gaps materiales** → **analyze gate** (read-only) = **`Success criteria` en verde** (*verification-first*): cada acceptance criterion traza al `Requirement`, sin contradicciones internas, `Scope` In/Out coherente, `Open questions` cerradas o explícitamente diferidas. Lo que falle **vuelve como gap**; si pasa → ofrece `Guardar especificación refinada`. *(Es el "convergence gate" del chasis; los heirs son instancias: plan-new = coherencia del plan, plan-exec = validación final, quick = validación puntual proporcional.)*
+- **Sin gaps materiales** → **analyze gate** (read-only) = **`Success criteria` en verde** (*verification-first*; la instancia SPEC del convergence gate del chasis): cada acceptance criterion traza al `Requirement`, sin contradicciones internas, `Scope` In/Out coherente, `Open questions` cerradas o explícitamente diferidas. Lo que falle **vuelve como gap**; si pasa → ofrece `Guardar especificación refinada`.
 - `Guardar` → `edit_in_place_with_confirm(spec)` y `finalize`.
-- `Cerrar` (control `flow`, en cualquier momento) → `finalize`. **`finalize` persiste siempre el `CHECKPOINT.md`** (reanudable) y, **solo si hay algo diferido/followup**, escribe `BACKLOG.md` (motivo de cierre + `Open questions` diferidas); cierra la session y reporta. Así sobrevive el avance aunque no se haya `Compactar` antes.
+- `Cerrar` → `finalize` del chasis (persiste siempre `CHECKPOINT`; `BACKLOG` **solo si** hay diferidos — acá: motivo de cierre + `Open questions` diferidas).
 
 ## Integration (dónde aterriza cada resolución)
 
@@ -305,10 +172,3 @@ El resume **keya off el `CHECKPOINT`** de la refine session, no de la existencia
 - Resuelto vía **humano** → `## Q&A traceability` del spec.
 - Resuelto vía **capacidad `ui-design`** (gap UI) → sección `## UI spec` del spec.
 - **Research inconclusa o sin resolver** → `## Open questions` del spec (diferido) + `BACKLOG.md` de la refine session (solo si queda algo diferido).
-
-## Heredan este chasis
-
-- `plan-new-loop` — mismo motor; deltas: plan rico + gap taxonomy de plan.
-- `plan-refine-loop` — mismo motor; deltas: refina el **plan** in place (auxiliar, no obligatorio), reusando la gap taxonomy + coherence gate de `plan-new-loop`. Es a `plan-new` lo que este chasis (`spec-refine`) es a `spec-new`.
-- `plan-exec-loop` — mismo motor; deltas: ejecución real (código/BD/git), **una sola session por run** (progreso por fase en el plan-doc), sin auto-export.
-- `quick-loop` — mismo motor (mínimo); hereda además git/BD/no-export de `plan-exec-loop`.