@tacuchi/agent-workflow-cli 12.4.0 → 12.6.0

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

@@ -2,18 +2,18 @@
 name: spec-refine-loop
 description: >-
   El CHASIS de los loops de agent-workflow. Refina un spec borrador
-  (docs/specs/NNN-spec.md) hasta un spec refinado sin ambigüedad
-  (docs/specs/NNN-spec-refined.md) mediante un motor gap-driven convergente:
-  detecta huecos/ambigüedades, los resuelve preguntando al humano (lo que
-  depende de su intención) o investigando de forma autónoma vía sessions de
-  research (lo que se responde leyendo el repo/datos), integra y repite hasta
-  converger. Compone la capacidad ui-design (built-in ui-spec) cuando el
-  requerimiento involucra UI. Lo arranca el comando /w:spec-refine y es
-  reanudable (4 casos de resume). Usa AskUserQuestion con ≤3 tabs de contenido
-  + 1 tab flow (Compactar/Cerrar) siempre presente; Cerrar persiste CHECKPOINT
-  + BACKLOG. Es el patrón de referencia que heredan plan-new-loop,
-  plan-exec-loop y quick-loop. Invocar cuando haya que refinar/desambiguar una
-  especificación antes de planificar.
+  (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.
 ---
 
 # spec-refine-loop
@@ -24,79 +24,95 @@ 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 y arranca según corresponda (ver *Compact / resume*, 4 casos).
+`/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` (borrador), **o**
-- `docs/specs/NNN-spec-refined.md` si **ya existe** un refinado previo → se re-refina incremental sobre el refined (NO sobre el borrador stale).
+- `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
-`docs/specs/NNN-spec-refined.md` (cuando el usuario elige `Guardar especificación refinada`). Si el archivo **ya existe**, **sobrescribe con confirmación** del usuario.
+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.
 
+## 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).
+
+> 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 (managed)
 
-El loop crea y maneja sus sessions en `.workflow/sessions/`. El usuario nunca las crea.
+El loop crea y maneja su session en `.workflow/sessions/`. El usuario nunca la crea.
 
 | Session | When | Artifacts | Role |
 |---|---|---|---|
-| **refine session** `NNN-spec-refine/` | al arrancar el loop (o se reanuda) | `SESSION.md` · `CHECKPOINT.md` (· `BACKLOG.md` al cerrar) | Dueña del run. Guarda el avance al `Compactar` y al `Cerrar`; habilita el resume. Type = `refine`. |
-| **research session** `MMM-spec-refine-research-*/` | on-demand, por cada gap factual | `SESSION.md` · `ANALYSIS-FILE.md` → `CONCLUSIONS.md` (+ `SCRIPTS.sql` si consulta BD) | Investiga, concluye, **cierra y reporta**. Puede cerrar **inconclusa**. Type = `research`; on-demand, **no reanudable** (run-and-close, sin `CHECKPOINT`/`BACKLOG` propios). |
+| **refine session** `NNN-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/`.
 
+> **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 (ej.: `001-spec-refine`, `002-spec-refine-research-x`, `003-plan-new`, …).
+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 control session que prefija sus sessions hijas: `spec-refine`, `plan-new`, `plan-exec`, `quick`. La research session pasa `--name <run>-research-<gap>` y el CLI le pone su propio `NNN`. **No** embebas el número del padre en el descriptor del hijo (lo agrega el CLI; embeberlo lo duplicaría).
+> `<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 ahora es global, no derivable del artefacto). `aw session-resume --code <NNN | folder>` resuelve ambas formas.
+> **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 spec-refine` → crea `NNN-spec-refine` / `aw session-resume --code <…>` (detecta `CHECKPOINT`).
-- `aw session-create --type research --name <run>-research-<gap>` por cada gap factual → crea `MMM-<run>-research-<gap>`.
 - `aw checkpoint-write` / `aw checkpoint-read` para el resume.
 - `aw session-close` al cerrar (con razón); `aw session-artifacts` para inspeccionar.
 
 ## Composes
 
-Cuando el requerimiento involucra **UI**, compone la capacidad **`ui-design`** (default built-in `ui-spec`; rebindeable vía `.workflow/skills.toml`): autora el UI spec nativamente (esquema `Screen`, vocabulario, formato). El loop aporta la iteración/Q&A que el viejo servicio no tenía (design-system, tema, variantes, desambiguación) y lo integra como sección `## UI spec` del spec.
+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 on-demand), `sql` (regla BD en research), `writing` (redacción del refined). Todas se resuelven por config; `off` → el loop sigue sin la capacidad y, si era necesaria, lo dice o pregunta.
+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.
 
-## Deliverable schema (`NNN-spec-refined.md`)
+## Deliverable schema (el spec, editado in place)
 
-Más rico que el borrador: mismas secciones **completadas** + dos nuevas (`Refinement decisions`, `Q&A traceability`).
+El spec se completa **in place**: mismas secciones del borrador **completadas** + dos nuevas que se **agregan** (`Refinement decisions`, `Q&A traceability`). NO se crea un archivo aparte.
 
 ```markdown
-# Spec NNN (refined) — <slug>
+# Spec NNN — <slug>
 
-> Derivado de `NNN-spec.md` · refinado por spec-refine-loop
+> 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
-Qué se definió al refinar y por qué. Incluye lo resuelto vía research
-(con referencia a la research session / CONCLUSIONS).
+## Refinement decisions   ← NEW (se AGREGA)
+Qué se definió al refinar y por qué. Incluye lo resuelto vía research inline
+(con referencia a las CONCLUSIONS de la session).
 
-## Q&A traceability       ← NEW
+## Q&A traceability       ← NEW (se AGREGA)
 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:
@@ -110,32 +126,37 @@ 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
 
-- **Autónomo**: la IA crea la research session, investiga y reporta **sin pedir permiso**. El humano se entera al integrarse (en `Refinement decisions`) y mantiene control vía el tab `flow`.
+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 el **mismo `AskUserQuestion`** como un **tab de contenido** (cuenta dentro del límite ≤3 + `flow`), **antes** de ejecutar queries. Si hay un único MCP o un default, no pregunta.
-  2. Escribe **primero** las queries en `SCRIPTS.sql` de la research session.
+  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 research session cierra con estado **`inconcluso`** y reporta el motivo (vía su `Success criteria` no cumplido).
-  - El loop **degrada** el gap: lo pasa a **pregunta-al-humano** (próximo batch → `Q&A traceability`) o, si tampoco aplica, lo **difiere** a `## Open questions` del refined.
+  - 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.
 
-## AskUserQuestion (design & batching)
+## Structured-choice (design & batching)
 
-- Límite del host: **máx 4 preguntas/llamada**. Como el tab `flow` va **siempre** → **≤3 tabs de contenido + 1 tab `flow`**.
-- **tab `flow`** (ciclo de vida, siempre presente): `Compactar` | `Cerrar`. Responder solo los tabs de contenido (sin tocar `flow`) = seguir iterando.
-- **Tabs de contenido** posibles:
+*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`.
@@ -145,84 +166,97 @@ Para cada gap, una sola pregunta decide el resolutor:
 
 ```
 spec-refine-loop(spec):
-  input = exists(NNN-spec-refined.md) ? NNN-spec-refined.md : NNN-spec.md   # (#2 resume)
-  refine_session = create_or_resume("spec-refine")         # CLI antepone NNN global; resume localiza por descriptor/origin
+  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
+  attempts = {}                                         # anti-relanzamiento por gap
   repeat:
     gaps = detect_gaps(work)  menos los gaps "agotados"
     if gaps == ∅: break
     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
-        rs  = create_research_session(gap)
-        res = rs.run_and_close()             # ANALYSIS-FILE → CONCLUSIONS (+SCRIPTS.sql)
+        res = research_inline(gap)           # en la session actual: ANALYSIS-FILE → CONCLUSIONS (+SCRIPTS.sql read-only)
         si res.concluyente: work = integrate(work, res)    # → Refinement decisions
         si no: attempts[gap]++ ; si attempts[gap] >= MAX → pending_human.push(gap)
       si no:
         pending_human.push(gap)
+    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          → write_with_confirm(NNN-spec-refined.md) ; goto finalize   # (#2)
+  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:
-  write CHECKPOINT (refine_session)                        # (#5) persiste siempre
-  write/update BACKLOG (motivo de cierre + Open questions diferidas)   # (#5)
-  cerrar research sessions abiertas ; cerrar refine_session ; reportar
+  write CHECKPOINT (refine_session)                     # persiste siempre
+  si hay diferidos/followup → write/update BACKLOG (motivo + Open questions diferidas)
+  cerrar refine_session ; reportar
 ```
 
 ```mermaid
 flowchart TD
-    S["input = refined si existe, si no borrador<br/>create_or_resume refine session"] --> D{"¿gaps<br/>(no agotados)?"}
-    D -->|no| C["AskUserQuestion<br/>contenido[Guardar refinada · Preguntar más]<br/>flow[Compactar · Cerrar]"]
+    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 --> F{"¿factual y<br/>attempts<MAX?"}
-    F -->|sí| RS["research 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 --> D
-    DEG --> D
-    I2 --> D
-    C -->|Guardar| W["write_with_confirm<br/>NNN-spec-refined.md"]
+    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<br/>+ cerrar sessions + reportar"]
+    W --> FIN["finalize: CHECKPOINT (+ BACKLOG si difiere)<br/>+ cerrar session + reportar"]
 ```
 
 ## Compact / resume
 
-Cuatro casos al ejecutar `/w:spec-refine` sobre un spec:
+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:
+
+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** (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.
 
-1. **En curso** (existe `CHECKPOINT.md` en la refine session) → reanuda desde el avance (gaps resueltos, Q&A, `attempts`, research sessions abiertas).
-2. **Sin avance** (no hay CHECKPOINT ni refined) → arranca desde cero leyendo `NNN-spec.md`.
-3. **Ya completado** (existe `NNN-spec-refined.md`, sin CHECKPOINT) → re-refinamiento incremental: input = el **refined** (no el borrador); al `Guardar`, sobrescribe con confirmación.
-4. **`Compactar`** (tab flow) → escribe `CHECKPOINT.md` en la refine session (spec en progreso, gaps restantes, Q&A, `attempts`, research sessions abiertas) → dispara `/compact` del host → reanuda leyendo el checkpoint.
+> **`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`.
-- `Guardar` → `write_with_confirm(NNN-spec-refined.md)` y `finalize`.
-- `Cerrar` (tab flow, en cualquier momento) → `finalize`. **`finalize` persiste siempre**: escribe `CHECKPOINT.md` (reanudable) **y** `BACKLOG.md` (motivo de cierre + `Open questions` diferidas), cierra sessions y reporta. Así sobrevive el avance aunque no se haya `Compactar` antes.
+- **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` (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** → `## Refinement decisions` del refined (+ ref a la research session / `CONCLUSIONS`).
-- Resuelto vía **humano** → `## Q&A traceability` del refined.
-- **Research inconclusa o sin resolver** → `## Open questions` del refined (diferido) + `BACKLOG.md` de la refine session al cerrar.
+- 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
 
 - `plan-new-loop` — mismo motor; deltas: plan rico + gap taxonomy de plan.
-- `plan-exec-loop` — mismo motor; deltas: ejecución real (código/BD/git), session por fase, sin auto-export.
+- `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`.

package/skills/w/roles/README.md

@@ -12,8 +12,8 @@ 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) |
-| `sql` | `sql` | must | research sessions · `plan-exec-loop` · `quick-loop` · `export-scripts` |
+| `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` |
 | `writing` | `writing` | must | all loops · `export-manuals` · `export-reports` |

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

@@ -2,10 +2,11 @@
 name: research
 description: >
   Capacidad de investigación on-demand que los loops componen cuando necesitan evidencia para avanzar.
-  Crea una sesión de investigación, lee el workspace + repos asociados + MCPs en modo read-only,
-  produce ANALYSIS-FILE → CONCLUSIONS. Cierra INCONCLUSIVE si la pregunta no puede responderse
-  con las fuentes disponibles. Discrimina cuándo investigar ("¿puedo responder leyendo repo/datos?")
-  vs cuándo preguntar al humano ("¿depende de lo que el usuario quiere?").
+  Investiga INLINE dentro de la sesión activa (no crea una sesión aparte): lee el workspace + repos
+  asociados + MCPs en modo read-only, produce ANALYSIS-FILE → CONCLUSIONS dentro de esa sesión.
+  Concluye INCONCLUSIVE si la pregunta no puede responderse con las fuentes disponibles. Discrimina
+  cuándo investigar ("¿puedo responder leyendo repo/datos?") vs cuándo preguntar al humano
+  ("¿depende de lo que el usuario quiere?").
 ---
 
 # research — On-demand investigation capability
@@ -23,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
@@ -42,16 +43,16 @@ Todos los loops la cargan on-demand:
 ### Investigation lifecycle
 
 ```
-[pregunta del loop] → [crear sesión research] → [recolectar evidencia] → [sintetizar] → [CONCLUSIONS]
+[pregunta del loop] → [investigar inline en la sesión activa] → [recolectar evidencia] → [sintetizar] → [CONCLUSIONS]
                                                           ↕
                                                [nueva hipótesis o gap] → [más evidencia o INCONCLUSIVE]
 ```
 
-1. **Crear sesión research** en `.workflow/sessions/<slug>/` con `SESSION.md` (pregunta original + scope).
+1. **Investigar inline** — no se crea una sesión aparte; los artefactos se escriben en la sesión activa del loop (`.workflow/sessions/NNN-<run>/`).
 2. **Recolectar evidencia** — read-only: `Read`, `Grep`, `Glob`, MCP SELECT, `git log`.
-3. **Escribir `ANALYSIS-FILE.md`** con hallazgos crudos.
+3. **Escribir `ANALYSIS-FILE.md`** (scratchpad opcional) con hallazgos crudos.
 4. **Sintetizar** en `CONCLUSIONS.md` con conclusiones evidenciadas.
-5. **Cerrar** la sesión: estado `closed` si converge; `inconclusive` si no hay suficiente material.
+5. **Reportar al loop**: `concluido` si converge; `inconclusive` si no hay material suficiente — el loop degrada/difiere el gap.
 
 ### Ask-vs-research discriminator (examples)
 
@@ -64,73 +65,14 @@ Todos los loops la cargan on-demand:
 "¿el servicio Y ya tiene auth implementado?"    → investigar (leer código)
 ```
 
-### ANALYSIS-FILE.md schema
+### Artifact schemas
 
-```markdown
-# Analysis — <slug>
-
-## Question
-
-[La pregunta exacta que el loop planteó.]
-
-## Sources consulted
-
-- Codigo: <repo/path:lineas>
-- BD (<mcp-name>): queries en queries/
-- Git: <SHAs relevantes>
-- Refs externas: <links si aplica>
-
-## Finding 1: <titulo>
-
-- **Que se observo**: ...
-- **Donde**: <path o link>
-- **Cuando**: <fecha si aplica>
-
-## Finding N: ...
-
-## Tentative hypotheses
-
-- [hipotesis sin compromiso, para revisar en synthesis]
-
-## Gaps
-
-- [lo que no pudo leerse o no esta disponible]
-```
-
-### CONCLUSIONS.md schema
-
-```markdown
-# Conclusions — <slug>
-
-## Summary
-
-[1-2 oraciones: que se investigo y que se concluyó.]
-
-## Conclusions
-
-- **C1**: <conclusion + link a ANALYSIS-FILE#section>
-- **C2**: ...
-
-## Recommendations
-
-- **R1**: <accion concreta para el loop que hizo la pregunta>
-
-## Open (gaps)
-
-- <pregunta sin responder si aplica>
-```
+`ANALYSIS-FILE.md` (scratchpad opcional) y `CONCLUSIONS.md` siguen las **plantillas canónicas** en `artifacts/artifacts-research/` — no se duplican aquí para evitar drift. Para research liviana basta `CONCLUSIONS.md`; `ANALYSIS-FILE.md` es opcional para investigaciones más profundas.
 
 ### DB rule (invariant #4)
 
 - **Solo SELECT** — nunca DML/DDL.
-- **Escribir la query primero** en `.workflow/sessions/<slug>/queries/NNN-<slug>.sql` con header:
-  ```sql
-  -- Query: <proposito>
-  -- MCP: <nombre>
-  -- Fecha: YYYY-MM-DD
-  -- Sesion: <slug>
-  -- Costo estimado: <filas|N/A>
-  ```
+- **Escribir la query primero** en el `SCRIPTS.sql` de la sesión activa (tipo A, read-only; ver la plantilla `artifacts/artifacts-core/SCRIPTS.sql`) con su header de propósito + MCP + origen.
 - **Si hay >1 MCP candidato sin default declarado**: preguntar al humano cuál usar antes de ejecutar.
 - **Cost guard antes de ejecutar**:
   - `COUNT(*) ≤ 1.000` o lookup por PK → ejecutar directo.
@@ -156,26 +98,24 @@ Si tras investigar los gaps persisten y no pueden cerrarse con las fuentes dispo
 - Marcar sesión como `inconclusive`.
 - Reportar al loop: qué se pudo y qué no — el loop decide si pregunta al humano.
 
-### Research session artifacts
+### Inline research artifacts (en la sesión activa)
 
 ```
-.workflow/sessions/<slug>/
-├── SESSION.md          # pregunta original + scope + estado (open|closed|inconclusive)
-├── ANALYSIS-FILE.md    # hallazgos crudos (equivale a EVIDENCE.md del modelo viejo)
-├── CONCLUSIONS.md      # sintesis + recomendaciones para el loop
-└── queries/            # SQL read-only (si se usó MCP)
-    └── 001-<slug>.sql
+.workflow/sessions/NNN-<run>/      # la sesión del loop (refine/exec/quick)
+├── ANALYSIS-FILE.md    # hallazgos crudos (scratchpad opcional)
+├── CONCLUSIONS.md      # síntesis + recomendaciones para el loop
+└── SCRIPTS.sql         # SQL read-only (tipo A), si se usó MCP
 ```
 
 ## Output
 
-Produce en `.workflow/sessions/<slug>/`:
-- `ANALYSIS-FILE.md` — hallazgos crudos sin sintetizar.
+Produce, **inline en la sesión activa del loop** (`.workflow/sessions/NNN-<run>/`):
+- `ANALYSIS-FILE.md` — hallazgos crudos sin sintetizar (opcional).
 - `CONCLUSIONS.md` — conclusiones con evidencia + recomendaciones para el loop.
-- `queries/*.sql` — solo si se usó MCP.
+- `SCRIPTS.sql` — queries read-only (tipo A), solo si se usó MCP.
 
 No gradua a `docs/` (invariant #1). El loop que compone esta capacidad consume las conclusiones y actua en consecuencia.
 
 ## Source
 
-Reciclado de `analyze-investigate`, `analyze-synthesize` y `analyze-conclude` del bundle viejo. Se conserva: el modelo de investigacion divergente → sintesis → conclusiones; las reglas read-only; el cost guard de queries; la discriminacion de gaps. Se descarta: la terminología de `flow=analyze`, `EVIDENCE.md`/`FINDINGS.md` como nombres canónicos (ahora `ANALYSIS-FILE.md`/`CONCLUSIONS.md`), el lifecycle de sesiones legacy, y la modulacion por modalidad (technical/incident/data) — la skill de research es de propósito general.
+Reciclado de `analyze-investigate`, `analyze-synthesize` y `analyze-conclude` del bundle viejo. Se conserva: el modelo de investigacion divergente → sintesis → conclusiones; las reglas read-only; el cost guard de queries; la discriminacion de gaps. Se descarta: la terminología de `flow=analyze`, `EVIDENCE.md`/`FINDINGS.md` como nombres canónicos (ahora `ANALYSIS-FILE.md`/`CONCLUSIONS.md`), el lifecycle de sesiones legacy (la research ahora es **inline**, sin sesión propia), y la modulacion por modalidad (technical/incident/data) — la skill de research es de propósito general.