@tacuchi/agent-workflow-cli 12.4.0 → 12.5.0

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

@@ -4,16 +4,16 @@ description: >-
   El atajo liviano de agent-workflow: resuelve una tarea acotada (un fix, un
   ajuste pequeño) directamente desde el prompt del usuario, editando código con
   ceremonia mínima. Heir del chasis spec-refine-loop (motor gap-driven mínimo,
-  research on-demand con regla BD read-only, AskUserQuestion con ≤3 tabs de
-  contenido + 1 tab flow Compactar/Cerrar siempre, compact/resume con Cerrar que
-  persiste CHECKPOINT + BACKLOG) y de plan-exec-loop (git seguro: rama esperada
-  antes de editar + commit propuesto, nunca push/--amend/--no-verify; la IA
-  nunca ejecuta DML, migraciones a SCRIPTS.sql; sin auto-export). Sus deltas: sin
-  fases ni plan-doc (el prompt ES la tarea), una sola session ligera
-  (<slug>-quick), un solo commit; y escalación con handoff si la tarea crece
-  (propone subir a SPEC/PLAN dejando el código a medias como contexto). NO toca
-  docs/. Lo arranca /w:quick y es reanudable. Invocar para cambios pequeños y
-  directos que no ameritan spec ni plan formal.
+  research INLINE con regla BD read-only, AskUserQuestion con ≤3 tabs de
+  contenido + 1 tab flow Compactar/Cerrar siempre, compact/resume con artefactos
+  como log vivo: CHECKPOINT siempre, BACKLOG solo si difiere) y de plan-exec-loop
+  (git seguro: rama esperada antes de editar + commit propuesto, nunca
+  push/--amend/--no-verify; la IA nunca ejecuta DML, migraciones a SCRIPTS.sql;
+  sin auto-export). Sus deltas: sin fases ni plan-doc (el prompt ES la tarea),
+  una sola session ligera (<slug>-quick), un solo commit; y escalación con
+  handoff si la tarea crece (propone subir a SPEC/PLAN dejando el código a
+  medias como contexto). NO toca docs/. Lo arranca /w:quick y es reanudable.
+  Invocar para cambios pequeños y directos que no ameritan spec ni plan formal.
 ---
 
 # quick-loop
@@ -39,21 +39,21 @@ QUICK
 
 ## Internal session
 
-- **SIEMPRE** crea una session ligera con descriptor `<slug>-quick` → `NNN-<slug>-quick` (Type = `quick`, ≈ `exec`): `SESSION` · `DECISION` · `SCRIPTS.sql` · `CHECKPOINT` (+ `BACKLOG` al cerrar). Una sola session (no exec-por-fase). El caller pasa solo el descriptor; el CLI antepone el `NNN` global y secuencial (ver chasis).
+- **SIEMPRE** crea una session ligera con descriptor `<slug>-quick` → `NNN-<slug>-quick` (Type = `quick`, ≈ `exec`): `SESSION` · `DECISION` · `SCRIPTS.sql` · `CHECKPOINT` (+ `BACKLOG` solo si difiere). Una sola session. La investigación es **inline** dentro de ella (`ANALYSIS-FILE`/`CONCLUSIONS` + `SCRIPTS.sql` read-only en su carpeta). El caller pasa solo el descriptor; el CLI antepone el `NNN` global y secuencial (ver chasis).
 
 ## Inherits
 
-- del **chasis** [`spec-refine-loop`](../spec-refine-loop/SKILL.md): gap-driven (mínimo), `AskUserQuestion` ≤3 + `flow` (`Compactar`/`Cerrar`), `research` on-demand + regla BD read-only (pregunta MCP si >1 sin default → `SCRIPTS.sql` → ejecuta read-only), compact/resume, `Cerrar` persiste `CHECKPOINT`+`BACKLOG`.
+- del **chasis** [`spec-refine-loop`](../spec-refine-loop/SKILL.md): gap-driven (mínimo), `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).
 - de [`plan-exec-loop`](../plan-exec-loop/SKILL.md): **git** (rama segura antes de editar + commit propuesto; nunca `push`/`--amend`/`--no-verify`), **BD** (la IA nunca ejecuta DML; migraciones → `SCRIPTS.sql` de la session), **sin auto-export** (no toca otras carpetas `docs/`).
 
 ## Composes
 
-`git` · `coding-standards` · `testing` (validación puntual) · `sql` (regla BD) · `writing` · `research`. Resueltas por `.workflow/skills.toml`.
+`git` · `coding-standards` · `testing` (validación puntual) · `sql` (regla BD) · `writing` · `research` (inline). Resueltas por `.workflow/skills.toml`.
 
 ## Delta QUICK — minimal ceremony
 
 - **Sin fases, sin plan-doc**: el prompt **es** la tarea (una sola unidad). No hay roadmap.
-- **Una sola session** (no exec-por-fase). **Un solo commit** propuesto al final.
+- **Una sola session**. **Un solo commit** propuesto al final.
 - **Escalación + handoff**: si la tarea crece (muchos archivos / ≥2 fuentes / necesita arquitectura) → propone subir a **SPEC/PLAN**. Si el usuario acepta:
   - el **código ya editado queda** en el working tree (no se revierte) **y se registra** en `CHECKPOINT` + `BACKLOG` ("cambios sin commitear en `<fuente>` — código a medias; decidir commit/descartar al retomar") — reusando **ambas** mitades del patrón "commit rechazado" de plan-exec (no revertir **y** registrar lo sin commitear). Crítico en la rama **SPEC**, que no retoma el working tree;
   - la session quick va a `finalize`, persistiendo `CHECKPOINT` + `BACKLOG` con un **puntero** al spec/plan sembrado (Followups: "escalado a `docs/specs/NNN` o `docs/plans/PPP` — retomar ahí");
@@ -65,25 +65,26 @@ QUICK
 ```
 quick-loop(prompt):
   s = create_or_resume("<slug>-quick")      # CLI antepone NNN global; siempre session ligera
+  seed CHECKPOINT.Pending/Next = la tarea (s)   # ANTES: sembrar intención (artifact-first); SESSION.Objective = el prompt
   trabajar la tarea (loop mínimo):
     verificar rama esperada por fuente (branch-check); si no → pausar + resolver
     editar código (cambio mínimo)
     si consulta BD read-only → SCRIPTS.sql + ejecutar read-only
     si cambio BD (DDL/DML) → SCRIPTS.sql (artefacto session, NO ejecutar)
     si decisión no obvia → DECISION
-    si duda/gap → research session ó AskUserQuestion        # chasis
+    si duda/gap → research inline ó AskUserQuestion         # chasis
     si la tarea CRECE → proponer escalar a SPEC/PLAN
         si acepta → handoff (código queda; BACKLOG→spec/plan sembrado) → goto finalize
   validación puntual (test si aplica)
   proponer commit (aprobar antes)                            # nunca push/amend/--no-verify
   AskUserQuestion(contenido: [Cerrar tarea, Preguntar algo más], flow: [Compactar, Cerrar])
-finalize: CHECKPOINT + BACKLOG (si queda algo) + cerrar session + reportar
+finalize: CHECKPOINT (DESPUÉS: Pending→Completed) + BACKLOG (solo si queda algo diferido) + cerrar session + reportar
 ```
 
 ```mermaid
 flowchart TD
     S["create_or_resume session NNN-&lt;slug&gt;-quick"] --> G["branch-check por fuente"]
-    G -->|ok| DO["editar código · BD→SCRIPTS.sql · DECISION<br/>(duda→research/AskUserQuestion)"]
+    G -->|ok| DO["editar código · BD→SCRIPTS.sql · DECISION<br/>(duda→research inline/AskUserQuestion)"]
     G -->|rama ≠| PA["pausar + resolver"]
     PA --> G
     DO --> GROW{"¿la tarea creció?"}

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 AskUserQuestion con ≤3 tabs de contenido + 1 tab 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
@@ -27,39 +27,50 @@ SPEC
 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`.
 
 ## 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 `$ARGUMENTS`. **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`. 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.
 
@@ -67,16 +78,16 @@ El **CLI es dueño del número**: `aw session-create` antepone un `NNN` **global
 
 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.
 
-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
 
 ## Requirement            (afinado, sin ambigüedad)
 ## Context                (completo)
@@ -87,11 +98,11 @@ Más rico que el borrador: mismas secciones **completadas** + dos nuevas (`Refin
 ## UI spec                (opt. — si involucra UI; vía capacidad ui-design / skill ui-spec)
 Screen (JSON) + render Markdown.
 
-## 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)
@@ -120,15 +131,17 @@ Para cada gap, una sola pregunta decide el resolutor:
 
 ## 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 tab `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.
+  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)
@@ -145,23 +158,24 @@ 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) | $ARGUMENTS path          # 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 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])
       switch(flow):
@@ -171,58 +185,60 @@ spec-refine-loop(spec):
   # convergió:
   ans = AskUserQuestion(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 + agrega 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)?"}
+    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 -->|sí| B["tomar ≤3 gaps"]
     B --> F{"¿factual y<br/>attempts<MAX?"}
-    F -->|sí| RS["research session<br/>ANALYSIS-FILE → CONCLUSIONS (+SCRIPTS.sql)"]
+    F -->|sí| RS["research INLINE en la session<br/>ANALYSIS-FILE → CONCLUSIONS (+SCRIPTS.sql)"]
     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"]
+    I1 --> CK["update CHECKPOINT (Pending→Completed)"]
+    DEG --> CK
+    I2 --> CK
+    CK --> D
+    C -->|Guardar| W["edit IN PLACE con confirmación<br/>completa + agrega 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`** (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.
 
 ## 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.
+- `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.
 
 ## 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.
+- **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

@@ -13,7 +13,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) |
-| `sql` | `sql` | must | research sessions · `plan-exec-loop` · `quick-loop` · `export-scripts` |
+| `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/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
@@ -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.