@tacuchi/agent-workflow-cli 12.7.1 → 12.8.0

package/skills/w/artifacts/artifacts-core/SESSION.md

@@ -21,6 +21,10 @@ Session type, **set by the parent loop** (not the user). Authoritative catalog:
 > `research` is **not** a session type the loops create. Research is an **inline** activity: ANALYSIS-FILE / CONCLUSIONS are written into whatever session is active (`refine`/`exec`/`quick`) when it does investigation.
 
 ## Success criteria
-Present **only for research** activity (investigate/conclude). It is a checklist `[ ]` that, when met, marks the research as concluded.
-If NOT met (e.g. research without evidence, DB unavailable): the research closes as `inconcluso` and reports the reason; the parent loop degrades the gap (asks the human or defers to `Open questions`).
-For `exec` / `quick` / `refine` sessions the closing criteria live in the **plan/spec**, not here — omit this section.
+The run's **done-condition**, seeded when the session is created (**verification-first** — generalized TDD; see [`../../loops/spec-refine-loop/SKILL.md`](../../loops/spec-refine-loop/SKILL.md) § Verification-first): a checklist `[ ]` of **falsifiable** items (that *can* fail) defining "done". The loop **persists until they are all green** (it is the *persistent-objective* condition); `CHECKPOINT.Pending/Completed` tracks the **red→green** progress. Two forms:
+
+- **Executable** (code/script/fix): **runnable** tests/checks (unit, build, lint, bug repro) — literal TDD. May **reference** the repo's tests rather than copy them.
+- **Rubric** (analysis/design and other non-executable deliverables): items checked by **inspection** (e.g. "identifies every affected site with `file:line`"; "each decision: rationale + ≥1 alternative"). For **subjective** deliverables the AI **proposes** the rubric and the **human ratifies** it before pursuing it.
+
+> **Spec/plan** may **reference** the document's acceptance criteria instead of duplicating them. **Research** is the original particular case: its checklist marks the research concluded.
+> **If an item cannot be met** (no evidence, DB unavailable, irresolvable): it closes as `inconcluso` with a reason and the loop **degrades** (asks the human or defers to `Open questions`/`BACKLOG`) — never spinning in place.

package/skills/w/loops/README.md

@@ -12,12 +12,13 @@ Un loop es una **skill** que le enseña a la IA *cómo iterar* hasta producir un
 
 Propiedades comunes a **los 4 loops**:
 
-1. **Gap-driven convergente** — cada ciclo: `detect_gaps` → resolver (humano o research) → integrar → repetir hasta que no queden gaps materiales. Los gaps "agotados" (límite `MAX` de intentos) no se re-disparan → garantiza convergencia.
-2. **Una sola session por run + research inline** — el loop crea **una** session en `.workflow/sessions/` (la dueña del run) y maneja **sus** artefactos. La **investigación es inline**: una actividad dentro de esa misma session que escribe `ANALYSIS-FILE`/`CONCLUSIONS` (+ `SCRIPTS.sql` read-only si consulta BD) en su propia carpeta — ya no es una session aparte. **El usuario nunca crea sessions.** Los artefactos son el **registro vivo** del run — **ciclo artifact-first**: sembrar `CHECKPOINT.Pending/Next` (la intención) antes de ejecutar, llevar a `Completed`/DECISION después; CHECKPOINT actualizado en cada límite de gap/fase, BACKLOG solo si difiere. El spec/plan es la base guía.
-3. **Structured-choice con dos planos** (capacidad del arnés — ver [`../harness/SKILL.md`](../harness/SKILL.md); en **Claude Code** es `AskUserQuestion`, máx 4 preguntas/llamada → **≤3 + 1 control `flow`**; sin elección estructurada degrada a markdown numerado):
+1. **Objetivo persistente + verification-first** — el loop persigue su `SESSION.Objective` y solo finaliza cuando sus `SESSION.Success criteria` están **en verde** (o el humano aborta vía `flow` `Cerrar`). Esos criterios —la condición de término— se **siembran al inicio** (*verification-first*, TDD generalizado: tests ejecutables para código, rúbrica falsable para análisis/diseño), no se improvisan al final. Modelado en el `/goal` de Claude Code pero como **doctrina agnóstica** (sin depender de ningún host) y con registro durable. El "no parar hasta converger" es del loop, no del arnés.
+2. **Gap-driven convergente** — el *cómo* del objetivo persistente: cada ciclo `detect_gaps` → resolver (humano o research) → integrar → repetir hasta que no queden gaps materiales. Los gaps "agotados" (límite `MAX` de intentos) no se re-disparan → garantiza convergencia.
+3. **Una sola session por run + research inline** — el loop crea **una** session en `.workflow/sessions/` (la dueña del run) y maneja **sus** artefactos. La **investigación es inline**: una actividad dentro de esa misma session que escribe `ANALYSIS-FILE`/`CONCLUSIONS` (+ `SCRIPTS.sql` read-only si consulta BD) en su propia carpeta — ya no es una session aparte. **El usuario nunca crea sessions.** Los artefactos son el **registro vivo** del run — **ciclo artifact-first**: sembrar `CHECKPOINT.Pending/Next` (la intención) antes de ejecutar, llevar a `Completed`/DECISION después; CHECKPOINT actualizado en cada límite de gap/fase, BACKLOG solo si difiere. El spec/plan es la base guía.
+4. **Structured-choice con dos planos** (capacidad del arnés — ver [`../harness/SKILL.md`](../harness/SKILL.md); en **Claude Code** es `AskUserQuestion`, máx 4 preguntas/llamada → **≤3 + 1 control `flow`**; sin elección estructurada degrada a markdown numerado):
    - **pregunta(s) de contenido** (≤3) — la(s) pregunta(s) real(es) del momento (resolver una duda, elegir MCP, o en convergencia: `Guardar` / `Preguntar algo más`).
    - **control `flow`** (1, SIEMPRE presente) — control de ciclo de vida por un canal lateral. Así el contenido lo maneja la IA y el ciclo de vida lo dirige el humano.
-4. **Escribe solo en su propia carpeta `docs/`** — y **nunca** gradúa/exporta otros artefactos a `docs/`. Esa promoción la hacen las skills `export-*`, aparte y explícita.
+5. **Escribe solo en su propia carpeta `docs/`** — y **nunca** gradúa/exporta otros artefactos a `docs/`. Esa promoción la hacen las skills `export-*`, aparte y explícita.
 
 ## flow control — options
 
@@ -80,7 +81,7 @@ Los **heirs** (`plan-new-loop`, `plan-exec-loop`, `quick-loop`) usan `## Inherit
 ## Chassis / heirs
 
 ```
-spec-refine-loop  ── CHASIS (patrón de referencia: motor gap-driven, sesión única,
+spec-refine-loop  ── CHASIS (patrón de referencia: objetivo persistente + verification-first, gap-driven, sesión única,
         │            structured-choice + control flow, research autónomo INLINE + regla BD,
         │            compact/resume, artefactos como log vivo: CHECKPOINT siempre,
         │            BACKLOG solo si difiere)

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

@@ -48,7 +48,7 @@ Este loop **nunca gradúa/promueve artefactos** a `docs/`. Las únicas carpetas
 
 Del chasis [`spec-refine-loop`](../spec-refine-loop/SKILL.md), sin cambios:
 
-- Motor **gap-driven** (aplica *dentro de una tarea* ante una decisión/duda no obvia: research inline ó structured-choice).
+- **Objetivo persistente + verification-first** del chasis: persigue su `SESSION.Objective` hasta que sus `SESSION.Success criteria` están **en verde** (sembrados al inicio; acá = los tests/validaciones del plan pasan — TDD literal cuando hay código, rúbrica para migraciones BD no ejecutables). El motor es **gap-driven** (aplica *dentro de una tarea* ante una decisión/duda no obvia: research inline ó structured-choice).
 - **Structured-choice**: ≤3 preguntas de contenido + 1 control `flow` (`Compactar`/`Cerrar`) siempre (capacidad del arnés — ver [`../../harness/SKILL.md`](../../harness/SKILL.md); en Claude Code es `AskUserQuestion`).
 - **Research INLINE** + **regla BD** read-only (pregunta MCP si >1 sin default → `SCRIPTS.sql` → ejecuta read-only) + research **inconclusa** (degrada/difiere, límite `MAX`).
 - **Compact/resume**; **artefactos como log vivo** (`CHECKPOINT` siempre; `BACKLOG` solo si difiere).
@@ -95,7 +95,7 @@ Distinción por **ejecución**, no por archivo (ver el esquema `SCRIPTS.sql`):
 - Validación que **corre y falla** → vuelve a la tarea (gap); no avanza.
 - **Validación dependiente de una migración no aplicada**: como la IA no ejecuta el DML, **no puede correr read-only** → se **difiere** (handoff a DBA), **no bloquea el avance**. Se registra en `Open questions` del plan + `BACKLOG`, marcando "verificación pendiente tras aplicar SQL". (Reusa el patrón degradar/diferir + límite `MAX` del chasis → evita el bucle "vuelve a la tarea".)
 
-> La **validación final** es el **convergence gate** de PLAN-exec (análogo al *analyze gate* de SPEC y al *coherence gate* de `plan-new`): el plan no se marca *done* hasta que pasa o queda explícitamente diferida (handoff de SQL).
+> La **validación final** es el **convergence gate** de PLAN-exec = **`Success criteria` en verde** (*verification-first*; análogo al *analyze gate* de SPEC y al *coherence gate* de `plan-new`): el plan no se marca *done* hasta que pasa o queda explícitamente diferida (handoff de SQL). Para código son **tests ejecutables** (TDD); para migraciones BD no ejecutables, **rúbrica** (SCRIPTS.sql válido + revisado).
 
 ## Delta 5 — Completitud / cierre
 

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

@@ -42,7 +42,7 @@ PLAN
 
 Del chasis [`spec-refine-loop`](../spec-refine-loop/SKILL.md), sin cambios:
 
-- Motor **gap-driven convergente** + **ciclo artifact-first** del chasis (sembrar `CHECKPOINT.Pending/Next` ANTES → `detect_gaps` → resolver → integrar → actualizar `Pending→Completed` DESPUÉS; gaps agotados con límite `MAX` no se re-disparan).
+- **Objetivo persistente + verification-first** del chasis: persigue su `SESSION.Objective` hasta que sus `SESSION.Success criteria` están **en verde** (sembrados al inicio; acá la rúbrica = **coherencia del plan**: cada Task traza a un acceptance criterion del spec). El motor es **gap-driven convergente** + **ciclo artifact-first** (sembrar `CHECKPOINT.Pending/Next` ANTES → `detect_gaps` → resolver → integrar → actualizar `Pending→Completed` DESPUÉS; gaps agotados con límite `MAX` no se re-disparan).
 - **Una sola session por run**: descriptor `plan-new` → `NNN-plan-new` (Type = `refine`): `SESSION` + `CHECKPOINT` (+ `BACKLOG` solo si difiere). La **investigación es inline** dentro de esta session (produce `ANALYSIS-FILE`/`CONCLUSIONS` + `SCRIPTS.sql` read-only en su propia carpeta), no una session aparte.
 - **Structured-choice**: ≤3 preguntas de contenido + 1 control `flow` (`Compactar`/`Cerrar`) siempre (capacidad del arnés — ver [`../../harness/SKILL.md`](../../harness/SKILL.md); en Claude Code es `AskUserQuestion`).
 - **Ask-vs-research rule** + **research autónomo inline** + **regla BD** (pregunta MCP si >1 sin default → queries a `SCRIPTS.sql` → ejecuta read-only, `sql-mutation-guard`) + manejo de research **inconclusa** (degrada a humano / difiere a `Open questions` + límite `MAX`).
@@ -100,4 +100,4 @@ El research **inline** del chasis se especializa: mapear **código/impacto** —
 
 ## Convergence / exit
 
-Sin gaps materiales → **coherence gate** (read-only; es el "convergence gate" del chasis para PLAN-new): cada `acceptance criterion` del spec **traza** a una fase/tarea, `Final behavior` los cubre, fases XS–S / tareas XS, `deps` sin ciclos, `Impacted` consistente con `Solution`. Lo que falle **vuelve como gap** — la trazabilidad criterio→tarea es una **invariante chequeada**, no una sección aparte. Si pasa → *structured-choice* (contenido: `Guardar plan` / `Preguntar algo más`; flow: `Compactar`/`Cerrar`) → al `Guardar`, escribe `docs/plans/PPP-plan-<slug>.md` (con confirmación si existe) → `finalize` (persiste `CHECKPOINT`, y `BACKLOG` solo si difiere; cierra la session, reporta). `Cerrar` en cualquier momento → `finalize` igual.
+Sin gaps materiales → **coherence gate** (read-only) = **`Success criteria` en verde** (*verification-first*; es el "convergence gate" del chasis para PLAN-new): cada `acceptance criterion` del spec **traza** a una fase/tarea, `Final behavior` los cubre, fases XS–S / tareas XS, `deps` sin ciclos, `Impacted` consistente con `Solution`. Lo que falle **vuelve como gap** — la trazabilidad criterio→tarea es una **invariante chequeada**, no una sección aparte. Si pasa → *structured-choice* (contenido: `Guardar plan` / `Preguntar algo más`; flow: `Compactar`/`Cerrar`) → al `Guardar`, escribe `docs/plans/PPP-plan-<slug>.md` (con confirmación si existe) → `finalize` (persiste `CHECKPOINT`, y `BACKLOG` solo si difiere; cierra la session, reporta). `Cerrar` en cualquier momento → `finalize` igual.

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

@@ -33,9 +33,9 @@ QUICK
 — (el prompt del usuario; no hay documento de entrada).
 
 ## Writes
-- Edita código en las fuentes (cambio mínimo).
+- **Deliverable según la tarea:** edita código en las fuentes (cambio mínimo) **o** produce un **análisis/diseño** acotado (deliverable no-código, vive en los artefactos de la session — no en `docs/`).
 - Artefactos de la session en `.workflow/sessions/`.
-- **NO toca `docs/`** (sin doc, sin auto-export).
+- **NO toca `docs/`** (sin doc, sin auto-export). Un análisis/diseño que amerite preservarse se promueve aparte (`export-*`) o se escala a SPEC/PLAN.
 
 ## Internal session
 
@@ -43,17 +43,18 @@ QUICK
 
 ## Inherits
 
-- 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).
+- del **chasis** [`spec-refine-loop`](../spec-refine-loop/SKILL.md): **objetivo persistente** (acá el más directo: el prompt *es* el objetivo) + **verification-first** (`SESSION.Success criteria` proporcional), gap-driven (mínimo), *structured-choice* ≤3 preguntas de contenido + 1 control `flow` (`Compactar`/`Cerrar`) (capacidad del arnés — ver [`../../harness/SKILL.md`](../../harness/SKILL.md); en Claude Code es `AskUserQuestion`), `research` **inline** + regla BD read-only (pregunta MCP si >1 sin default → `SCRIPTS.sql` → ejecuta read-only), compact/resume, **artefactos como log vivo (ciclo artifact-first)** (`CHECKPOINT` siempre; `BACKLOG` solo si difiere).
 - de [`plan-exec-loop`](../plan-exec-loop/SKILL.md): **git** (rama segura antes de editar + commit propuesto; nunca `push`/`--amend`/`--no-verify`), **BD** (la IA nunca ejecuta DML; migraciones → `SCRIPTS.sql` de la session), **sin auto-export** (no toca otras carpetas `docs/`).
 
 ## Composes
 
-`git` · `coding-standards` · `testing` (validación puntual) · `sql` (regla BD) · `writing` · `research` (inline). Resueltas por `.workflow/skills.toml`.
+`git` · `coding-standards` · `testing` (verification-first) · `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**. **Un solo commit** propuesto al final.
+- **Verification-first proporcional** (ceremonia mínima): aun acá se **siembra el check antes**, del tamaño de la tarea. Código: un test (repro del bug → fix) o "build/lint/tests existentes siguen verdes" (chore). **Análisis/diseño**: una **rúbrica falsable corta**, *ratificada por el usuario* antes de perseguirla. Es el `SESSION.Success criteria` del run (ver [chasis § Verification-first](../spec-refine-loop/SKILL.md)).
+- **Una sola session**. **Un solo commit** propuesto al final (solo si hubo cambios de código).
 - **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,41 +66,43 @@ 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
+  seed SESSION.Objective = el prompt
+  seed SESSION.Success criteria = check del deliverable     # verification-first, ANTES: test(s) si código · rúbrica corta RATIFICADA si análisis/diseño
+  seed CHECKPOINT.Pending/Next = la tarea (s)               # ANTES: sembrar intención (artifact-first)
   trabajar la tarea (loop mínimo):
-    verificar rama esperada por fuente (branch-check); si no → pausar + resolver
-    editar código (cambio mínimo)
+    si edita código → verificar rama esperada por fuente (branch-check); si no → pausar + resolver
+    producir el deliverable: editar código (cambio mínimo) Ó autorar el análisis/diseño
     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 ó 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
+        si acepta → handoff (avance queda; BACKLOG→spec/plan sembrado) → goto finalize
+  convergence gate: Success criteria en verde                # tests verdes si código · rúbrica satisfecha si análisis/diseño
+  si hubo cambios de código → proponer commit (aprobar antes)   # nunca push/amend/--no-verify
   structured_choice(contenido: [Cerrar tarea, Preguntar algo más], flow: [Compactar, Cerrar])
 finalize: CHECKPOINT (DESPUÉS: Pending→Completed) + BACKLOG (solo si queda algo diferido) + cerrar session + reportar
 ```
 
 ```mermaid
 flowchart TD
-    S["create_or_resume session NNN-&lt;slug&gt;-quick"] --> G["branch-check por fuente"]
-    G -->|ok| DO["editar código · BD→SCRIPTS.sql · DECISION<br/>(duda→research inline/structured-choice)"]
+    S["create_or_resume NNN-&lt;slug&gt;-quick<br/>seed Objective + Success criteria (verification-first)"] --> G["branch-check (si edita código)"]
+    G -->|ok| DO["producir deliverable: código Ó análisis/diseño<br/>BD→SCRIPTS.sql · DECISION · (duda→research/structured-choice)"]
     G -->|rama ≠| PA["pausar + resolver"]
     PA --> G
     DO --> GROW{"¿la tarea creció?"}
-    GROW -->|sí| ESC["escalar a SPEC/PLAN<br/>código queda · BACKLOG→spec/plan sembrado"]
+    GROW -->|sí| ESC["escalar a SPEC/PLAN<br/>avance queda · BACKLOG→spec/plan sembrado"]
     ESC --> FIN
-    GROW -->|no| V["validación puntual"]
-    V --> CM["proponer commit (aprobar)"]
+    GROW -->|no| V["convergence gate:<br/>Success criteria en verde"]
+    V --> CM["si hubo código → proponer commit (aprobar)"]
     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`.
+- **Success criteria en verde** (proporcional) + commit propuesto si hubo código (o aprobado saltarlo) → `Cerrar`.
 - `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.
+> El *convergence gate* de QUICK es **verification-first proporcional**: un `Success criteria` **corto** sembrado al inicio (no la *ausencia* de checklist, sino su versión mínima) — para código, "el cambio hace lo que pedía el prompt + tests/build verdes"; para análisis/diseño, una rúbrica corta ratificada. Mínima ceremonia por diseño, pero **siempre con el check declarado antes**.

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

@@ -37,6 +37,39 @@ Actualiza `docs/specs/NNN-spec-<slug>.md` **in place** (cuando el usuario elige
 
 > **Invariante de boundary:** este loop escribe **solo** en `docs/specs`. Nunca gradúa/exporta otros artefactos a `docs/` — eso es trabajo de `export-*`, aparte.
 
+## Objetivo persistente (chasis — heredado por todos los loops)
+
+Un loop **es un objetivo persistente**: existe para cumplir el `SESSION.Objective` declarado al arrancar, y **no se considera terminado hasta que el convergence gate confirma que el objetivo se cumplió**. La iteración gap-driven es el *método*; los artefactos son el *registro*; el objetivo persistente es el *frame* que los gobierna.
+
+Está **modelado en cómo se comporta el `/goal` de Claude Code** (declarás un objetivo, el agente no para hasta cumplirlo, auto-completa al cumplirse, con corte explícito para abortar antes) pero como **doctrina agnóstica, no una dependencia del host**: el "no parar hasta converger" lo sostiene el propio loop (su `repeat:` + el convergence gate), no un Stop hook del arnés — ningún host necesita `/goal`. Y, a diferencia del `/goal` pelado, **deja registro durable** (artifact-first) que sobrevive compactación y resume.
+
+| Comportamiento de `/goal` (ejemplo) | Análogo agnóstico en el loop |
+|---|---|
+| declarar el objetivo | `SESSION.Objective` |
+| no parar hasta cumplirlo | `repeat:` gap-driven hasta `gaps == ∅` |
+| objetivo cumplido → auto-clear | **convergence gate** pasa → `finalize` |
+| `/goal clear` (abortar antes) | control `flow` `Cerrar` |
+| la directiva sobrevive el contexto | `CHECKPOINT` + resume |
+
+> Los heirs heredan el frame: `plan-new`/`plan-exec` persiguen el plan hasta su gate; `quick-loop` es la encarnación más directa (el prompt *es* el objetivo) — el "símil a `/goal`" del modelo.
+
+## Verification-first (chasis — heredado por todos los loops)
+
+El objetivo persistente necesita una **condición de término checkable** — si no, el loop no sabe cuándo cumplió (o persigue un blanco que inventó). Esa condición se **siembra ANTES de ejecutar**, no se improvisa al final: es **TDD generalizado**. Junto con artifact-first (sección siguiente) son los **dos sembrados** de cada gap/fase: *cómo sabré que funcionó* + *qué voy a hacer*.
+
+**Dónde vive:** en `SESSION.Success criteria` (ver [`../../artifacts/artifacts-core/SESSION.md`](../../artifacts/artifacts-core/SESSION.md)) — checklist `[ ]` de criterios **falsables** (que *pueden* fallar). `CHECKPOINT.Pending/Completed` trackea el avance **red→green**. Dos formas según el deliverable:
+
+| Deliverable | Criterio = | Ciclo |
+|---|---|---|
+| código / script / fix / feature | **tests ejecutables** (unit, build, lint, repro del bug) | TDD literal: red → green → refactor |
+| migración BD (no ejecutable; invariante 4) | **rúbrica**: `SCRIPTS.sql` válido + revisado (no se ejecuta) | rúbrica |
+| spec / plan | **rúbrica** = los acceptance criteria del documento (referenciados, no duplicados) | rúbrica |
+| análisis / diseño | **rúbrica falsable por inspección** (ej. "todos los afectados con `file:line`"; "cada decisión: rationale + ≥1 alternativa") | rúbrica |
+
+**Forma y peso escalan** (preserva la *ceremonia mínima* de quick): un chore es "tests/build existentes siguen verdes" (una línea); un feature, acceptance tests reales. No es "siempre escribir tests nuevos" — es "**siempre declarar el check antes**". Para deliverables **subjetivos** (análisis/diseño) la IA **propone** la rúbrica y el **humano la ratifica** (structured-choice) antes de perseguirla. **Criterio irresoluble** (sin evidencia, BD no disponible) → cierra `inconcluso` + el loop **degrada** (humano, o difiere a `Open questions`/`BACKLOG`); nunca itera en falso.
+
+> El **convergence gate** (sección *Convergence / exit*) es, operacionalmente, **"todos los `Success criteria` en verde"**. Los gates por-heir (analyze gate, coherencia del plan, validación final, validación puntual proporcional) son **instancias** de esto, con los criterios sembrados al inicio.
+
 ## 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**:
@@ -168,6 +201,7 @@ La investigación es **inline**: una actividad **dentro de la session actual del
 spec-refine-loop(spec):
   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
+  seed SESSION.Success criteria = acceptance criteria + checklist del analyze gate   # verification-first: ANTES de iterar
   work = read(input)  (+ aplicar avance del checkpoint si reanuda)
   attempts = {}                                         # anti-relanzamiento por gap
   repeat:
@@ -193,7 +227,7 @@ spec-refine-loop(spec):
         Compactar → write CHECKPOINT (refine_session) ; compactar(arnés) ; continue
         Cerrar    → goto finalize
       work = integrate(work, ans)            # → Q&A traceability / Open questions
-  # sin gaps materiales → analyze gate (read-only) antes de ofrecer Guardar:
+  # sin gaps materiales → analyze gate = Success criteria en verde (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],
@@ -244,7 +278,7 @@ El resume **keya off el `CHECKPOINT`** de la refine session, no de la existencia
 
 ## Convergence / exit
 
-- **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.)*
+- **Sin gaps materiales** → **analyze gate** (read-only) = **`Success criteria` en verde** (*verification-first*): cada acceptance criterion traza al `Requirement`, sin contradicciones internas, `Scope` In/Out coherente, `Open questions` cerradas o explícitamente diferidas. Lo que falle **vuelve como gap**; si pasa → ofrece `Guardar especificación refinada`. *(Es el "convergence gate" del chasis; los heirs son instancias: plan-new = coherencia del plan, plan-exec = validación final, quick = validación puntual proporcional.)*
 - `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.