@tacuchi/agent-workflow-cli 12.5.0 → 12.7.0

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

@@ -4,8 +4,8 @@ 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 INLINE con regla BD read-only, AskUserQuestion con ≤3 tabs de
-  contenido + 1 tab flow Compactar/Cerrar siempre, compact/resume con artefactos
+  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;
@@ -43,7 +43,7 @@ QUICK
 
 ## Inherits
 
-- del **chasis** [`spec-refine-loop`](../spec-refine-loop/SKILL.md): gap-driven (mínimo), `AskUserQuestion` ≤3 + `flow` (`Compactar`/`Cerrar`), `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).
+- 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
@@ -72,19 +72,19 @@ quick-loop(prompt):
     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 inline ó 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])
+  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-<slug>-quick"] --> G["branch-check por fuente"]
-    G -->|ok| DO["editar código · BD→SCRIPTS.sql · DECISION<br/>(duda→research inline/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ó?"}
@@ -92,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.

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

@@ -9,7 +9,7 @@ description: >-
   (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 AskUserQuestion con ≤3 tabs de contenido + 1 tab flow
+  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
@@ -24,13 +24,13 @@ description: >-
 SPEC
 
 ## Layer
-2 — la IA lo corre entero (gap-driven). El usuario no conduce el ciclo; solo responde tabs de contenido y dirige el ciclo de vida por el tab `flow`.
+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*).
 
 ## 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 `$ARGUMENTS`. **Siempre el spec mismo**: este loop lo edita in place, no hay un archivo "refined" aparte.
+- `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.
 
 ## 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.
@@ -65,7 +65,7 @@ El loop crea y maneja su session en `.workflow/sessions/`. El usuario nunca la c
 
 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 (ej.: `001-spec-refine`, `002-plan-new`, `003-plan-exec`, …).
 
-> `<run>` = el **descriptor** (sin número) de la session del run: `spec-refine`, `plan-new`, `plan-exec`, `quick`. Como la investigación es **inline** en esta misma session, ya no hay sessions hijas `*-research-*` que numerar (compat: las viejas son históricas).
+> `<run>` = el **descriptor** (sin número) de la session del run: `spec-refine`, `plan-new`, `plan-exec`; QUICK usa `<slug>-quick` (slug del prompt). 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.
 
@@ -76,7 +76,7 @@ El **CLI es dueño del número**: `aw session-create` antepone un `NNN` **global
 
 ## Composes
 
-Cuando el requerimiento involucra **UI**, compone la capacidad **`ui-design`** (default built-in `ui-spec`; rebindeable vía `.workflow/skills.toml`): autora el UI spec nativamente (esquema `Screen`, vocabulario, formato). El loop aporta la iteración/Q&A que el viejo servicio no tenía (design-system, tema, variantes, desambiguación) y lo integra como sección `## UI spec` del spec.
+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.
 
 Otras capacidades transversales que el chasis usa siempre: `research` (research **inline**, ver abajo), `sql` (regla BD en research), `writing` (redacción del spec). Todas se resuelven por config; `off` → el loop sigue sin la capacidad y, si era necesaria, lo dice o pregunta.
 
@@ -89,14 +89,15 @@ El spec se completa **in place**: mismas secciones del borrador **completadas**
 
 > Refinado in place por spec-refine-loop
 
+## Origin                 (opt. — se conserva del borrador)
 ## Requirement            (afinado, sin ambigüedad)
 ## Context                (completo)
 ## Scope                  (In / Out claros)
-## Acceptance criteria    (testables, - [ ])
+## Acceptance criteria    (testables, - [ ]; estilo EARS / Given-When-Then recomendado)
 ## Assumptions            (declarados)
 
 ## UI spec                (opt. — si involucra UI; vía capacidad ui-design / skill ui-spec)
-Screen (JSON) + render Markdown.
+Descripción estructurada en Markdown (pantallas → regiones/componentes). Ver [`ui-spec`](../../roles/ui-spec/SKILL.md).
 
 ## Refinement decisions   ← NEW (se AGREGA)
 Qué se definió al refinar y por qué. Incluye lo resuelto vía research inline
@@ -108,6 +109,10 @@ Cada duda preguntada al humano + la respuesta elegida.
 ## Open questions         (idealmente "None"; lo que quede se difiere)
 ```
 
+> **Marca de refinado (contrato con PLAN):** la presencia de `## Refinement decisions` + `## Q&A traceability` distingue un spec refinado de un borrador — plan-new lo detecta así, NO por el nombre del archivo; sin esas 2 secciones plan-new hace soft-suggest de spec-refine.
+
+> **Acceptance criteria = criterios testables estáticos** (el "qué"): plan-exec los valida pero el avance se trackea en el PLAN (sus Tasks), no marcando estos `- [ ]` en el spec; el spec no muta por ejecución, solo por re-refine.
+
 ## Gap taxonomy (= weak sections of the schema)
 
 `detect_gaps(work)` busca estas señales; cada una tiene un resolutor:
@@ -121,22 +126,23 @@ Cada duda preguntada al humano + la respuesta elegida.
 | Open questions abiertas | dudas explícitas | según naturaleza |
 | Supuestos ocultos | el spec asume cosas no dichas | **research** valida / **humano** confirma |
 | Contradicción interna | secciones que se contradicen | **humano** |
+| 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** (AskUserQuestion).
+> *"¿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 tab `flow`.
+- **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 el **mismo `AskUserQuestion`** como un **tab de contenido** (cuenta dentro del límite ≤3 + `flow`), **antes** de ejecutar queries. Si hay un único MCP o un default, no pregunta.
+  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):
@@ -144,11 +150,13 @@ La investigación es **inline**: una actividad **dentro de la session actual del
   - 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.
 
-## AskUserQuestion (design & batching)
+## 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**.
 
-- Límite del host: **máx 4 preguntas/llamada**. Como el tab `flow` va **siempre** → **≤3 tabs de contenido + 1 tab `flow`**.
-- **tab `flow`** (ciclo de vida, siempre presente): `Compactar` | `Cerrar`. Responder solo los tabs de contenido (sin tocar `flow`) = seguir iterando.
-- **Tabs de contenido** posibles:
+- 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`.
@@ -158,7 +166,7 @@ La investigación es **inline**: una actividad **dentro de la session actual del
 
 ```
 spec-refine-loop(spec):
-  input = glob(NNN-spec*.md) | $ARGUMENTS path          # siempre el spec mismo (in place)
+  input = glob(NNN-spec*.md) | argumento (ruta)         # siempre el spec mismo (in place)
   refine_session = create_or_resume("spec-refine")      # CLI antepone NNN global; resume localiza por descriptor/origin
   work = read(input)  (+ aplicar avance del checkpoint si reanuda)
   attempts = {}                                         # anti-relanzamiento por gap
@@ -168,7 +176,10 @@ spec-refine-loop(spec):
     batch = top ≤3 gaps ; pending_human = []
     seed CHECKPOINT.Pending/Next = batch (refine_session) # ANTES: sembrar intención (artifact-first)
     para cada gap en batch:
-      si factual(gap) y attempts[gap] < MAX:
+      si gap = UI (requerimiento con UI, falta ## UI spec):
+        componer ui-design → autora ## UI spec   # design-system/tema vía structured-choice (cuenta en el batch)
+        work = integrate(work, ui)               # → ## UI spec
+      si no, si factual(gap) y attempts[gap] < MAX:
         si requiere BD y >1 MCP sin default → encolar "elección MCP" en pending_human
         res = research_inline(gap)           # en la session actual: ANALYSIS-FILE → CONCLUSIONS (+SCRIPTS.sql read-only)
         si res.concluyente: work = integrate(work, res)    # → Refinement decisions
@@ -177,15 +188,17 @@ spec-refine-loop(spec):
         pending_human.push(gap)
     update CHECKPOINT (refine_session)        # DESPUÉS: Pending→Completed, en cada límite de gap (ver ciclo artifact-first)
     si pending_human no vacío:
-      ans = AskUserQuestion(contenido: pending_human (≤3), flow: [Compactar, Cerrar])
+      ans = structured_choice(contenido: pending_human (≤3), flow: [Compactar, Cerrar])
       switch(flow):
-        Compactar → write CHECKPOINT (refine_session) ; /compact ; continue
+        Compactar → write CHECKPOINT (refine_session) ; compactar(arnés) ; continue
         Cerrar    → goto finalize
       work = integrate(work, ans)            # → Q&A traceability / Open questions
-  # convergió:
-  ans = AskUserQuestion(contenido: [Guardar refinada, Preguntar algo más],
+  # sin gaps materiales → analyze gate (read-only) antes de ofrecer Guardar:
+  issues = analyze(work)   # criterios trazan al Requirement · sin contradicciones · Scope coherente · Open questions cerradas/diferidas
+  si issues: gaps += issues ; continue            # los hallazgos vuelven al loop como gaps
+  ans = structured_choice(contenido: [Guardar refinada, Preguntar algo más],
                         flow: [Compactar, Cerrar])
-  Guardar          → edit_in_place_with_confirm(spec)  # completa secciones + agrega Refinement decisions/Q&A ; goto finalize
+  Guardar          → edit_in_place_with_confirm(spec)  # completa secciones + inserta UI spec/Refinement decisions/Q&A ; goto finalize
   Preguntar algo más → continue
   flow Compactar/Cerrar → manejar igual
 finalize:
@@ -197,20 +210,24 @@ finalize:
 ```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| C["AskUserQuestion<br/>contenido[Guardar refinada · Preguntar más]<br/>flow[Compactar · Cerrar]"]
+    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 --> F{"¿factual y<br/>attempts<MAX?"}
-    F -->|sí| RS["research INLINE en la session<br/>ANALYSIS-FILE → CONCLUSIONS (+SCRIPTS.sql)"]
+    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"]
-    F -->|no| Q["AskUserQuestion<br/>contenido[dudas + elección MCP ≤3]<br/>flow[Compactar · Cerrar]"]
     Q --> I2["integrar → Q&A traceability"]
-    I1 --> CK["update CHECKPOINT (Pending→Completed)"]
+    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 + agrega Refinement decisions/Q&A"]
+    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"]
 ```
@@ -223,18 +240,19 @@ El resume **keya off el `CHECKPOINT`** de la refine session, no de la existencia
 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** (no hay CHECKPOINT abierto pero el spec **ya tiene** `Refinement decisions`/`Q&A traceability`) → re-refinamiento incremental leyendo el **spec mismo**; al `Guardar`, edita in place con confirmación.
 
-> **`Compactar`** (tab flow, transversal a los 3 casos) → escribe `CHECKPOINT.md` en la refine session (spec en progreso, gaps restantes, Q&A, `attempts`) → dispara `/compact` del host → reanuda leyendo el checkpoint.
+> **`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.
 
 ## Convergence / exit
 
-- **Sin gaps materiales** → ofrece `Guardar especificación refinada`.
+- **Sin gaps materiales** → **analyze gate** (read-only): 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; heirs: plan-new = coherencia del plan, plan-exec = validación final, quick = validación puntual — excepción lightweight.)*
 - `Guardar` → `edit_in_place_with_confirm(spec)` y `finalize`.
-- `Cerrar` (tab 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` (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.
 
 ## Integration (dónde aterriza cada resolución)
 
 - Resuelto vía **research inline** → `## Refinement decisions` del spec (+ ref a las `CONCLUSIONS` de la session).
 - 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

package/skills/w/roles/README.md

@@ -12,7 +12,7 @@ All 10 roles, their built-in defaults, their tier, and which loops/exports compo
 
 | Role | Default built-in | Tier | Composed by |
 |---|---|---|---|
-| `ui-design` | [`ui-spec`](../ui-spec/SKILL.md) | must | `spec-refine-loop` (when requirement involves UI) |
+| `ui-design` | [`ui-spec`](ui-spec/SKILL.md) | must | `spec-refine-loop` (when requirement involves UI) |
 | `sql` | `sql` | must | inline research · `plan-exec-loop` · `quick-loop` · `export-scripts` |
 | `git` | `git` | must | `plan-exec-loop` · `quick-loop` |
 | `coding-standards` | `coding-standards` | must | `plan-exec-loop` · `quick-loop` |

package/skills/w/roles/git/SKILL.md

@@ -6,7 +6,8 @@ description: >-
   commits when the user approves, and NEVER runs push, --amend, --no-verify, force,
   merge/rebase/cherry-pick, tags, or destructive resets without explicit user request.
   Read-only git (status/log/diff/branch) is always allowed. Use when a loop is about
-  to edit code or when the user asks to commit / save / push changes.
+  to edit code, when the user asks to commit / save / push changes, or to resolve an
+  in-progress merge conflict (via /w:fix-git).
 ---
 
 # git — git-safe capability
@@ -23,6 +24,7 @@ Operar git de forma **segura y controlada**: verificar la rama esperada antes de
 
 - **`plan-exec-loop`** — verifica rama antes de cada edit; propone commits al cerrar/checkpoint.
 - **`quick-loop`** — igual, en el atajo liviano.
+- **`/w:fix-git`** (comando transversal) — compone la sección *Resolución de conflictos de merge* para resolver un merge en curso en cualquier repo.
 
 (Cualquier flujo que edite código o que el usuario quiera commitear lo usa.)
 
@@ -40,9 +42,11 @@ Lista cerrada. La IA **nunca** las ejecuta por iniciativa propia:
 
 Y **siempre** prohibido, aún cuando el usuario pida commit: `--no-verify` (respetar los hooks pre-commit), `--force`, trailers `Co-Authored-By`, firmas de modelo.
 
+> **Excepción — merge en curso:** resolver los conflictos de un merge **ya iniciado** (MERGE_HEAD), o iniciado a pedido **explícito** del usuario vía `/w:fix-git`, **sí** está permitido (es solicitud explícita, no iniciativa propia) — ver *Resolución de conflictos de merge*.
+
 ### Operaciones read-only (siempre permitidas, sin preguntar)
 
-`status` · `log` · `diff` · `branch --show-current` · `rev-parse` · `show`. `git checkout` (cambio de rama) **no** es read-only: requiere `AskUserQuestion` aunque no sea destructivo (ver verificación de rama).
+`status` · `log` · `diff` · `branch --show-current` · `rev-parse` · `show`. `git checkout` (cambio de rama) **no** es read-only: requiere *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`**; sin elección estructurada degrada a **markdown numerado**) aunque no sea destructivo (ver verificación de rama).
 
 ### Verificación de rama (antes de editar)
 
@@ -53,9 +57,9 @@ Campos por fuente: `alias`, `path`, `main_branch` (base, default `certificacion`
 Casos:
 
 - **`match=true`** → OK, editar.
-- **`match=false, dirty=false`** (Caso A — rama distinta, repo limpio) → `AskUserQuestion`: hacer `git checkout <expected>` / mantener current y actualizar la expectativa de la sesión / cancelar.
+- **`match=false, dirty=false`** (Caso A — rama distinta, repo limpio) → *structured-choice*: hacer `git checkout <expected>` / mantener current y actualizar la expectativa de la sesión / cancelar.
 - **`match=false, dirty=true`** (Caso B — rama distinta + cambios sin commit) → **pausar y esperar resolución manual**. No proponer checkout (podría perder trabajo). Pedir al usuario commit/stash/discard y avisar cuando continuar.
-- **Cross-fuente (hub)**: si las fuentes tocadas apuntan a ramas distintas sin declararlo, **hard gate** — bloquear avance con `AskUserQuestion` (alinear todas / declarar divergencia explícita / cancelar).
+- **Cross-fuente (hub)**: si las fuentes tocadas apuntan a ramas distintas sin declararlo, **hard gate** — bloquear avance con *structured-choice* (alinear todas / declarar divergencia explícita / cancelar).
 - **HEAD detached** → tratar como Caso A.
 - **Fuente fuera de git** (`is_repo=false`) → informar, no bloquear.
 
@@ -64,14 +68,14 @@ Casos:
 Ante cualquier pedido o disparo de commit (cierre de loop, "commitea esto", "guardá los cambios"):
 
 1. Resolver las fuentes y su estado dirty/rama.
-2. Si hay 1+ fuentes `dirty=true`, invocar **una sola** `AskUserQuestion` con un tab por fuente dirty (máx 4 simultáneas; si N>4, en tandas):
-   - Header del tab: el `alias` de la fuente.
+2. Si hay 1+ fuentes `dirty=true`, invocar **una sola** *structured-choice* con una pregunta de contenido por fuente dirty (máx 4 simultáneas → **≤3 preguntas de contenido + 1 control `flow`**; si N>3, en tandas):
+   - Header de la pregunta: el `alias` de la fuente.
    - Opciones: "Aprobar sugerido (Recomendado)" con el mensaje canónico / "Saltar esta fuente". `Other` = mensaje custom.
 3. Ejecutar `git -C <path> commit -m "<msg>"` solo en las fuentes aprobadas, **una a una**. Respetar hooks (sin `--no-verify`).
 4. Si una fuente tiene `match=false` (rama distinta a la esperada): **omitirla y abortar su commit**; avisar para alinear la rama primero.
 5. Si todas están `dirty=false` → skip silencioso, informar en chat que no hay nada que commitear.
 
-**Bypass** (Regla 5): si el usuario aporta el mensaje literal exacto (`-m "..."`, comillas), commitear directo sin `AskUserQuestion`, pero seguir validando rama, hooks y formato. Si el literal viola el formato, avisar antes de ejecutar.
+**Bypass** (Regla 5): si el usuario aporta el mensaje literal exacto (`-m "..."`, comillas), commitear directo sin *structured-choice*, pero seguir validando rama, hooks y formato. Si el literal viola el formato, avisar antes de ejecutar.
 
 ### Formato canónico del mensaje
 
@@ -89,6 +93,23 @@ fix(session018): corrige drift en hooks.json
 
 Fuera de sesión activa: relajar a "1 línea + sin co-author"; el tag `session<NNN>` se omite. El propose-then-execute sigue activo.
 
+### Resolución de conflictos de merge
+
+`git merge` autónomo está prohibido (arriba), **pero** resolver un merge **ya en curso** (MERGE_HEAD) o invocado por el usuario vía `/w:fix-git` **sí** es trabajo sancionado. **Agnóstico al workspace**: opera sobre cualquier repo (no requiere `.workflow/`, flows ni sesiones).
+
+1. **Detectar + identificar** con `aw merge-state [<path>|--source <alias>|--all]` (read-only): `is_merging`, `current_branch` (**destino / ours**), `merge_origin` (**origen / theirs**), `conflicted_files`. Si `merge_origin` viene vacío, mirar `.git/MERGE_MSG` o `git log --oneline -1 MERGE_HEAD`.
+2. **Analizar la intención** de cada conflicto **antes** de resolver — nunca elegir un lado a ciegas:
+   - Las tres versiones: `git show :1:<file>` (base) · `:2:<file>` (ours/destino) · `:3:<file>` (theirs/origen).
+   - El porqué de cada lado: `git log --merge -p -- <file>`; el historial del hunk en cada rama.
+   - El código alrededor del marcador (coherencia con el resto del archivo).
+3. **Resolver** editando el archivo (quitar `<<<<<<<` / `=======` / `>>>>>>>`): elegir **ours**, **theirs**, **combinar** ambas intenciones, o **reescribir** para satisfacer las dos. `git add <file>` lo resuelto.
+4. **Preguntar** (*structured-choice*) cuando la intención es **ambigua** o los dos lados son **incoherentes** entre sí (no combinables sin perder algo): una pregunta de contenido por archivo/hunk dudoso (≤3 + control `flow`), opciones "Ours (`<destino>`)" / "Theirs (`<origen>`)" / "Combinar" / "Editar manual". **No inventar** una resolución cuando hay duda real.
+5. **Commit propuesto**: completar el merge es un `git commit` (el merge commit) → **propose-then-execute** como cualquier commit (formato canónico de arriba; fuera de sesión → 1 línea sin tag `session<NNN>`; nunca `--no-verify`/`--amend`/`push`). El hook `git-commit-advisor` lo gatea.
+6. **Escape**: si el merge no debe completarse, `git merge --abort` **tras confirmación** del usuario (*structured-choice*) — deja el repo como antes del merge.
+
+> **Resume por git**: el estado del merge en `.git` (MERGE_HEAD + índice) **es** el checkpoint; re-correr `/w:fix-git` reanuda desde los conflictos que queden. No hay session ni artefacto.
+> **Rebase / cherry-pick**: fuera de v1 (misma resolución de markers; distinto `--continue` / `REBASE_HEAD`).
+
 ## Output
 
 Ninguno en `docs/`. Produce commits **solo** cuando el usuario aprueba, en los repos fuente. La verificación de rama puede actualizar la expectativa de rama de la sesión si el usuario lo elige.

package/skills/w/roles/research/SKILL.md

@@ -24,7 +24,7 @@ El discriminador clave:
 | La pregunta... | Acción |
 |---|---|
 | puede responderse leyendo repo / datos (hechos objetivos del sistema) | **investigar** |
-| depende de preferencias, prioridades o decisiones del usuario | **preguntar al humano** vía `AskUserQuestion` |
+| depende de preferencias, prioridades o decisiones del usuario | **preguntar al humano** vía *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**. |
 | está parcialmente en el repo y parcialmente en intención del usuario | investigar primero, luego preguntar solo por la parte incierta |
 
 ## Composed by

package/skills/w/roles/testing/SKILL.md

@@ -28,10 +28,10 @@ Dar a los loops la capacidad de razonar sobre tests: qué nivel aplicar, con qu
 
 ### Execution rule
 
-Por defecto, **no ejecutar pruebas automáticamente**. Antes de correr cualquier test runner:
+Por defecto, **no ejecutar pruebas automáticamente**. Antes de correr cualquier test runner, preguntar al humano vía *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**.
 
 ```
-AskUserQuestion:
+structured-choice:
   "¿Correr los tests?"
   [a] Sí, el loop los ejecuta
   [b] Los corro yo manualmente

package/skills/w/roles/ui-spec/SKILL.md

@@ -2,12 +2,12 @@
 name: ui-spec
 description: >-
   UI spec authoring — built-in default for the `ui-design` capability. Given a UI
-  requirement, author a structured, framework-agnostic screen specification (the
-  universal `Screen` model in JSON) plus its readable Markdown render. Knows the
-  `Screen` schema, the kind/region vocabulary, the authoring rules, design-system /
-  theme / variant handling, and the exact Markdown render format. Use when a loop is
-  refining a spec that involves screens, forms, dashboards, modals or any UI surface
-  — primarily `spec-refine-loop`. Recycled from the `ui-spec-generator` service.
+  requirement, author a structured, framework-agnostic screen specification as
+  **Markdown** (single output format). Knows the conceptual screen structure, the
+  kind/region vocabulary, the authoring rules, design-system / theme / variant
+  handling, and the exact Markdown render format. Use when a loop is refining a spec
+  that involves screens, forms, dashboards, modals or any UI surface — primarily
+  `spec-refine-loop`. Recycled from the `ui-spec-generator` service.
 ---
 
 # ui-spec — UI spec authoring
@@ -18,37 +18,31 @@ description: >-
 
 ## Purpose
 
-Dado un requerimiento de UI, autorar una **especificación de pantalla estructurada** — un modelo universal, agnóstico de framework — más su render Markdown legible. **Reemplaza** al servicio single-shot `ui-spec-generator`: ahora la IA la autora **nativamente**, guiada por esta skill. No hay endpoint que llamar; el saber del servicio vive aquí.
+Dado un requerimiento de UI, autorar una **descripción estructurada en Markdown** de las pantallas y sus componentes — descriptiva (qué hay y para qué) y estructurada (regiones → componentes, con vocabulario consistente), agnóstica de framework. **Reemplaza** al servicio single-shot `ui-spec-generator`: ahora la IA la autora **nativamente**, guiada por esta skill. No hay endpoint que llamar; el saber del servicio vive aquí. **Salida en un solo formato: Markdown** (sin representación JSON paralela).
 
 ## Composed by
 
-La carga el **`spec-refine-loop`** (ver `../../loops/spec-refine-loop.md`) cuando el requerimiento involucra UI. El loop aporta lo que el servicio viejo no tenía:
+La carga el **`spec-refine-loop`** (ver `../../loops/spec-refine-loop/SKILL.md`) al resolver el gap **UI sin especificar** (cuando el requerimiento involucra UI). El loop aporta lo que el servicio viejo no tenía:
 
-- **Pregunta al humano** (design-system, tema, ambigüedades de pantalla) vía `AskUserQuestion`.
+- **Pregunta al humano** (design-system, tema, ambigüedades de pantalla) vía *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**.
 - **Itera** gap-driven hasta converger.
 - Ofrece **variantes** y **cura** el resultado.
 
-Cualquier loop podría componerla; el caso primario es SPEC. El `Screen` y su Markdown aterrizan como una sección dentro del documento spec (`docs/specs/NNN-spec.md`) — nunca como artefacto suelto (invariante 3: el spec es un documento).
+Cualquier loop podría componerla; el caso primario es SPEC. La descripción Markdown aterriza como una sección dentro del documento spec (`docs/specs/NNN-spec-<slug>.md`) — nunca como artefacto suelto (invariante 3: el spec es un documento).
 
 ## Knowledge
 
-### Schema (modelo `Screen` — universal, recursivo)
+### Estructura conceptual (universal, recursiva)
 
-```
-Screen {
-  name: string             # nombre de la pantalla
-  purpose: string          # "tipo" semántico: auth, dashboard, form, list, detail, error, ...
-  platform: string         # web (default), mobile, ...
-  description?: string
-  regions?:   Region[]     # pantallas complejas
-  components?: Component[]  # pantallas simples
-}                          # usar regions O components, no ambos
-Region    { type: string, components: Component[] }
-Component { kind: string, role?: string, label?: string, children?: Component[] }  # recursive
-```
+Una **pantalla** tiene: `nombre`, `tipo` (propósito semántico: auth, dashboard, form, list, detail, error, …), `plataforma` (web por default, mobile, …), `descripción` opcional, y **o bien regiones** (pantalla compleja) **o bien componentes** directos (pantalla simple) — **no ambos**.
+
+- Una **región** agrupa componentes y tiene un `type`.
+- Un **componente** tiene un `kind`, y opcionalmente `role`, `label` y `children` (anidables, recursivos).
 
-- `type` (region) ∈ `header · main · footer · sidebar · filters · summary`
-- `kind` (component) por categoría:
+Es un modelo conceptual para guiar la autoría; **no se serializa a JSON** — la única salida es el render Markdown (ver Output).
+
+- `type` (región) ∈ `header · main · footer · sidebar · filters · summary`
+- `kind` (componente) por categoría:
   - **Contenedores**: `card · panel · modal`
   - **Datos**: `table · list · grid`
   - **Visualización**: `chart · metric · badge · image`
@@ -57,8 +51,6 @@ Component { kind: string, role?: string, label?: string, children?: Component[]
   - **Navegación**: `navBar · tabs · breadcrumb`
   - **Feedback**: `alert · progress`
 
-JSON serializado en **camelCase**, **claves null omitidas** (no emitir `"description": null`).
-
 ### Rules
 
 1. **Conciso** — solo lo esencial. Nada de relleno ni componentes especulativos.
@@ -66,11 +58,11 @@ JSON serializado en **camelCase**, **claves null omitidas** (no emitir `"descrip
 3. Pantalla compleja (dashboard, mantenimiento CRUD) → `regions` para organizar.
 4. `role` es **opcional** — solo si aporta claridad (`role:"logo"`, `role:"primary"`).
 5. Límites: **≤100 componentes**, **≤5 niveles** de anidación.
-6. Un solo `Screen` por sección; si el requerimiento son varias pantallas, una sección por pantalla.
+6. Una sola pantalla por bloque `#`; si el requerimiento son varias pantallas, se listan una tras otra (cada una con su `#`).
 
 ### Design options (las pregunta el loop al humano)
 
-Estas opciones **guían contenido/labels**; el modelo `Screen` es **agnóstico** de design-system y NO las lleva como campos. Se **anotan en el spec** (encabezado de la sección), no en el JSON:
+Estas opciones **guían contenido/labels**; la estructura de la pantalla es **agnóstica** de design-system y NO las lleva como parte del modelo. Se **anotan en el spec** (encabezado de la sección):
 
 - **Design system**: `material3 · bootstrap5 · tailwind3 · antDesign · chakraUI · custom`.
 - **Tema**: `light · dark · auto`.
@@ -80,11 +72,11 @@ Estas opciones **guían contenido/labels**; el modelo `Screen` es **agnóstico**
 
 ### Variants
 
-Cuando el requerimiento admite más de un layout razonable (ej. tabla vs. grid de cards; tabs vs. acordeón), ofrecer **2-3 variantes** como `Screen` alternativos y pedir al humano que elija. Una sola variante se cura y queda; las descartadas no se persisten.
+Cuando el requerimiento admite más de un layout razonable (ej. tabla vs. grid de cards; tabs vs. acordeón), ofrecer **2-3 variantes** como pantallas Markdown alternativas y pedir al humano que elija. Una sola variante se cura y queda; las descartadas no se persisten.
 
 ### Disambiguation
 
-Antes de autorar, resolver ambigüedades con `AskUserQuestion` (lo dispara el loop):
+Antes de autorar, resolver ambigüedades con *structured-choice* (lo dispara el loop; ver `../../harness/SKILL.md`):
 
 - Pantalla simple o compleja (¿necesita `regions`?).
 - Qué acciones primarias/secundarias existen.
@@ -95,27 +87,45 @@ Si el humano no responde, asumir el caso más simple coherente con la descripci
 
 ### Examples (few-shot)
 
-```json
-// Simple (sin regions)
-{"name":"Recuperar Contraseña","purpose":"auth","platform":"web","components":[{"kind":"image","role":"logo"},{"kind":"textInput","label":"Correo electrónico"},{"kind":"button","label":"Enviar enlace"},{"kind":"link","label":"Volver al login"}]}
+**Simple (sin regiones)** — "Recuperar Contraseña" (auth, web):
 
-// Complejo (con regions)
-{"name":"Dashboard","purpose":"dashboard","platform":"web","regions":[{"type":"summary","components":[{"kind":"metric","label":"Total"},{"kind":"metric","label":"Pendientes"}]},{"type":"main","components":[{"kind":"table","label":"Registros"}]}]}
+```markdown
+# Recuperar Contraseña
+**Tipo**: auth | **Plataforma**: web
+
+## Componentes
+- **logo** (image)
+- **Correo electrónico** (textInput)
+- **Enviar enlace** (button)
+- **Volver al login** (link)
+```
+
+**Complejo (con regiones)** — "Dashboard" (web):
+
+```markdown
+# Dashboard
+**Tipo**: dashboard | **Plataforma**: web
+
+## Summary
+- **Total** (metric)
+- **Pendientes** (metric)
+
+## Main
+- **Registros** (table)
 ```
 
-## Output — sección `## UI spec` dentro del spec (`docs/specs/NNN-spec.md`)
+## Output — sección `## UI spec` dentro del spec (`docs/specs/NNN-spec-<slug>.md`)
 
-La escribe el loop (no esta skill por sí sola). Encabezar la sección con las opciones de diseño elegidas (design system, tema, idioma) en una línea. Luego dos representaciones:
+**Salida en un solo formato: Markdown.** La escribe el loop (no esta skill por sí sola). Encabezar la sección con las opciones de diseño elegidas (design system, tema, idioma) en una línea. Luego el render Markdown, con estas reglas exactas (recicladas del `MarkdownFormatter`):
 
-1. **`Screen` (JSON)** — camelCase, claves null omitidas, en bloque ```json.
-2. **Markdown** — render legible (reglas exactas, recicladas del `MarkdownFormatter`):
-   - `# {name}`
-   - `**Tipo**: {purpose} | **Plataforma**: {platform}`
-   - `description` como párrafo aparte (solo si existe).
-   - Con `regions`: un `## {Type capitalizado}` por región (capitalizar la primera letra del `type`).
-   - Sin `regions`: un `## Componentes`.
-   - Cada componente: `- **{label || role || kind}**`, seguido de ` ({kind})` **solo si** había `label` o `role`.
-   - `children` indentados **2 espacios por nivel**.
+- `# {nombre}`
+- `**Tipo**: {tipo} | **Plataforma**: {plataforma}`
+- `descripción` como párrafo aparte (solo si existe).
+- Con regiones: un `## {Type capitalizado}` por región (capitalizar la primera letra del `type`).
+- Sin regiones: un único `## Componentes`.
+- Cada componente: `- **{label || role || kind}**`, seguido de ` ({kind})` **solo si** había `label` o `role`.
+- `children` indentados **2 espacios por nivel**.
+- Si hay varias pantallas, se listan una tras otra (cada una con su `#`).
 
 Ejemplo de render para el dashboard de arriba:
 
@@ -133,4 +143,4 @@ Ejemplo de render para el dashboard de arriba:
 
 ## Source
 
-Reciclada de `ui-spec-generator` (Spring Boot/Kotlin). Se **conservan**: el prompt de sistema (vocabulario, kinds, reglas), el esquema `Screen`/`Region`/`Component`, los pocos-shot, el enum de design systems, los constraints (theme/density/maxWidth) y las reglas exactas del `MarkdownFormatter`. Se **descarta**: el transporte HTTP, OpenRouter/Gemini y el modo single-shot — los reemplaza la iteración del `spec-refine-loop`. El endpoint del servicio deja de usarse. También absorbe los principios UX de la vieja skill `standards/frontend-design/` cuando el spec describe mantenimientos CRUD (formularios, listados, modales, navegación, feedback).
+Reciclada de `ui-spec-generator` (Spring Boot/Kotlin). Se **conservan**: el prompt de sistema (vocabulario, kinds, reglas), la estructura conceptual pantalla/región/componente, los pocos-shot (ahora en Markdown), el enum de design systems, los constraints (theme/density/maxWidth) y las reglas exactas del `MarkdownFormatter` (su render era exactamente este). Se **descarta**: la **serialización JSON `Screen`** (segunda representación, ahora innecesaria), el transporte HTTP, OpenRouter/Gemini y el modo single-shot — los reemplaza la iteración del `spec-refine-loop`. El endpoint del servicio deja de usarse. También absorbe los principios UX de la vieja skill `standards/frontend-design/` cuando el spec describe mantenimientos CRUD (formularios, listados, modales, navegación, feedback).