@tacuchi/agent-workflow-cli 14.10.0 → 14.11.0

package/skills/w/loops/CHASSIS.md

@@ -0,0 +1,159 @@
+# CHASSIS — motor de los loops
+
+Este documento es el **motor común** de los loops de agent-workflow: la doctrina que todo loop corre por debajo de sus deltas. **No es una skill** — es un documento referenciado: cada loop lo manda leer desde su `## Inherits`, **siempre, antes de sus deltas**. Si editás el motor, editálo **acá** — los heirs no lo repiten, solo lo referencian.
+
+## Heirs (lista canónica)
+
+Los **5 loops** corren este motor; cada uno agrega solo sus deltas:
+
+- [`spec-refine-loop`](spec-refine-loop/SKILL.md) — refina el **spec** in place; deltas: gap taxonomy de spec, analyze gate, `## UI spec` vía la capacidad `ui-design`.
+- [`plan-new-loop`](plan-new-loop/SKILL.md) — genera el **plan** desde el spec; deltas: plan rico + gap taxonomy de plan (+ design SPECs por pantalla si hay UI).
+- [`plan-refine-loop`](plan-refine-loop/SKILL.md) — refina el **plan** in place (auxiliar, no obligatorio); reusa la gap taxonomy + coherence gate de `plan-new-loop`. Es a `plan-new` lo que `spec-refine` es a `spec-new`.
+- [`plan-exec-loop`](plan-exec-loop/SKILL.md) — **ejecuta** el plan: código/BD/git, una sola session por run, progreso por fase en el plan-doc, sin auto-export. Aplica las políticas de [`CODE-POLICIES.md`](CODE-POLICIES.md).
+- [`quick-loop`](quick-loop/SKILL.md) — el motor con **ceremonia mínima** (el prompt *es* el objetivo); aplica también [`CODE-POLICIES.md`](CODE-POLICIES.md) (gate en versión proporcional).
+
+## Objetivo persistente
+
+Un loop **es un objetivo persistente**: existe para cumplir el `SESSION.Objective` declarado al arrancar, y **no se considera terminado hasta que el convergence gate confirma que el objetivo se cumplió**. La iteración gap-driven es el *método*; los artefactos son el *registro*; el objetivo persistente es el *frame* que los gobierna.
+
+Está **modelado en cómo se comporta el `/goal` de Claude Code** (declarás un objetivo, el agente no para hasta cumplirlo, auto-completa al cumplirse, con corte explícito para abortar antes) pero como **doctrina agnóstica, no una dependencia del host**: el "no parar hasta converger" lo sostiene el propio loop (su `repeat:` + el convergence gate), no un Stop hook del arnés — ningún host necesita `/goal`. Y, a diferencia del `/goal` pelado, **deja registro durable** (artifact-first) que sobrevive compactación y resume.
+
+| Comportamiento de `/goal` (ejemplo) | Análogo agnóstico en el loop |
+|---|---|
+| declarar el objetivo | `SESSION.Objective` |
+| no parar hasta cumplirlo | `repeat:` gap-driven hasta `gaps == ∅` |
+| objetivo cumplido → auto-clear | **convergence gate** pasa → `finalize` |
+| `/goal clear` (abortar antes) | control `flow` `Cerrar` |
+| la directiva sobrevive el contexto | `CHECKPOINT` + resume (compactación **y próximo prompt**) |
+
+> Cada heir instancia el frame: `spec-refine` persigue el spec y `plan-new`/`plan-refine` el plan hasta su gate; `plan-exec` persigue el plan hasta su validación final; `quick-loop` es la encarnación más directa (el prompt *es* el objetivo) — el "símil a `/goal`" del modelo.
+
+> **Continuidad inter-turno (contexto operativo).** El mismo `CHECKPOINT`+resume que sobrevive la compactación gobierna también el **próximo prompt**: dentro de un workspace, un prompt **sin comando** **continúa/reabre la sesión más reciente** (la *última iniciada*) en vez de arrancar trabajo suelto — el objetivo persiste **entre turnos**, no solo dentro del run. Un **comando de flujo** señala "nueva línea de trabajo" (sesión nueva) — **salvo re-correr el mismo flujo sobre la misma entrada** (mismo spec/plan), que hace `create_or_resume`: reanuda/reabre la session existente en vez de duplicarla (ver *Compact / resume*, caso 3); la convergencia cierra la sesión y un prompt relacionado posterior la **reabre** (resume quita `.closed`). Es la fila 2 de la matriz de contexto operativo (ver [`../SKILL.md`](../SKILL.md) § *Contexto operativo*) — doctrina agnóstica que la IA evalúa en cada turno, no un Stop hook del host.
+
+## Verification-first
+
+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 — plan-new y plan-refine; validación final; validación puntual proporcional) son **instancias** de esto, con los criterios sembrados al inicio.
+
+**Integridad del gate (anti-gaming + verificación independiente).** El gate solo vale si no se hace trampa para pasarlo. El loop **no**:
+
+- modifica el check ni afloja un `Success criterion` para forzar verde;
+- debilita, borra ni saltea tests/validaciones;
+- usa asserts triviales o tautológicos que siempre pasan (el valor esperado sale de una fuente independiente, no del propio output);
+- parchea el test en lugar de arreglar la causa (preferir arreglar producción).
+
+Ante un blocker real **para y lo reporta** (→ `Open questions`/`BACKLOG`) en vez de gamear la métrica. El veredicto cuenta **solo el output del check, no la auto-declaración** del implementador: cuando el deliverable lo justifica, la verificación final la hace una pasada **independiente** (subagente o re-lectura limpia) que no asume correcta la implementación — *only command output counts*.
+
+## Artifacts as a live log — ciclo artifact-first
+
+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**.
+
+## Motor gap-driven convergente
+
+El ciclo común (cada heir lo instancia en su `## Sequence`, con su propia gap taxonomy): `detect_gaps(work)` — menos los gaps *agotados* (ver *Research*) — → si `∅`, **convergence gate** (ver *Convergence / exit*); si hay gaps, tomar un batch (≤3), **sembrar** `CHECKPOINT.Pending/Next` (*artifact-first*), resolver cada gap con su **resolutor** — humano (structured-choice) · research inline · una capacidad compuesta (p. ej. `ui-design`) — según la *ask-vs-research rule*, **integrar** y actualizar `CHECKPOINT` → repetir.
+
+## Internal sessions (managed) — una session por run
+
+El loop crea y maneja su session en `.workflow/sessions/`. **El usuario nunca la crea.** **Una sola session por run**, dueña del run: mantiene el avance vivo (`CHECKPOINT`) y habilita el resume. Artefactos: `SESSION.md` · `CHECKPOINT.md` (· `BACKLOG.md` solo si difiere; los loops que editan código suman `DECISION` y `SCRIPTS.sql`). Cada heir declara su descriptor y su `Type` en su propio `## Internal sessions`.
+
+> **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 doc de entrada del flujo (spec/plan) **nunca** entra en una session; vive en `docs/`.
+
+### Numeración de sessions (regla dura)
+
+El **CLI es dueño del número**: `aw session-create` antepone un `NNN` **global y secuencial** escaneando **todas** las sessions de `.workflow/sessions/` (cualquier tipo). El caller pasa **solo el descriptor** vía `--name` — **nunca** un número. Así la numeración no se reinicia por tipo ni colisiona, y cada folder queda **autodescriptivo** con la forma `NNN-<slug>-<flow>` (ej.: `002-correo-otp-spec-refine`, `003-correo-otp-plan-new`, `004-correo-otp-plan-exec`, `005-validacion-correo-quick`).
+
+> `<run>` = el **descriptor** (sin número) de la session del run, siempre con forma **`<slug>-<flow>`**: `<slug>-spec-refine`, `<slug>-plan-new`, `<slug>-plan-refine`, `<slug>-plan-exec`, `<slug>-quick`. El `<slug>` es **descriptivo** y sale del doc de entrada del flujo — `docs/specs/NNN-spec-<slug>.md` para spec-refine/plan-new; `docs/plans/PPP-plan-<slug>.md` para plan-refine/plan-exec; el prompt para quick — para que el folder diga de un vistazo de qué trata, no solo qué flujo lo creó. Como la investigación es **inline** en esta misma session, ya no hay sessions hijas `*-research-*` que numerar (compat: las viejas son históricas).
+>
+> **Resume**: localiza la session existente **escaneando** `.workflow/sessions/` por descriptor + `## Origin` (qué spec/plan), **no** reconstruyendo el número (que es global, no derivable del artefacto). `aw session-resume --code <NNN | folder>` resuelve ambas formas.
+
+**CLI**:
+- `aw session-create --type <type> --name <slug>-<flow>` → crea `NNN-<slug>-<flow>` / `aw session-resume --code <…>` (detecta `CHECKPOINT`).
+- `aw checkpoint-write` / `aw checkpoint-read` para el resume.
+- `aw session-close` al cerrar (con razón); `aw session-artifacts` para inspeccionar.
+- **Reabrir para continuar** (contexto operativo, fila 2): `aw session-resume --code <NNN> --reopen` reactiva una sesión **cerrada** (quita `.closed` → activa) para seguir trabajando en ella; sin `--reopen`, el resume es read-only. Para detectar cuál es la más reciente cerrada: `aw resume-summary --include-recent-closed` (o `aw sessions --state all`).
+
+## Ask-vs-research rule (el discriminador)
+
+Para cada gap, una sola pregunta decide el resolutor:
+
+> *"¿Puedo responder esto leyendo el repo/datos?"* → **research** (autónomo).
+> *"¿Depende de lo que el usuario quiere?"* → **preguntar al humano** (structured-choice).
+
+## Research: autonomy, scope & failure
+
+La investigación es **inline**: una actividad **dentro de la session actual del run**, no una session aparte. Escribe sus artefactos (`ANALYSIS-FILE` → `CONCLUSIONS`, + `SCRIPTS.sql` read-only si consulta BD) en la **carpeta de la propia session**.
+
+- **Autónomo**: la IA investiga inline y reporta **sin pedir permiso**. El humano se entera al integrarse (en el registro de decisiones del flujo — p. ej. `## Refinement decisions` en los refine loops, `DECISION` en los que editan código) y mantiene control vía el control `flow`.
+- **Alcance**: workspace + repos asociados (fuentes) + MCPs de BD.
+- **Regla BD** (única excepción a la autonomía):
+  1. **Elección de MCP**: si el gap requiere BD y hay **>1 MCP candidato sin default configurado**, la IA pregunta cuál usar. Esa pregunta va por la **misma structured-choice** como una **pregunta de contenido** (cuenta dentro del límite ≤3 + `flow`), **antes** de ejecutar queries. Si hay un único MCP o un default, no pregunta.
+  2. Escribe **primero** las queries en `SCRIPTS.sql` de la session.
+  3. Las ejecuta **read-only** vía MCP (respeta `sql-mutation-guard`: nunca DML/DDL).
+- **Research inconclusa** (BD no disponible, evidencia insuficiente, gap factual irresoluble):
+  - La investigación concluye con estado **`inconcluso`** en `CONCLUSIONS` y reporta el motivo.
+  - El loop **degrada** el gap: lo pasa a **pregunta-al-humano** (próximo batch → el registro de Q&A del flujo: `Q&A traceability` en los refine loops, `DECISION` en los que editan código) o, si tampoco aplica, lo **difiere** a las `## Open questions` del doc del flujo (spec/plan) — o al `BACKLOG` de la session si el flujo no tiene doc (quick).
+  - El gap se marca **"ya intentado vía research"** (`attempts[gap]++`, límite `MAX`) para que `detect_gaps` **no lo re-dispare en bucle** → garantiza convergencia.
+
+## Structured-choice (design & batching)
+
+*structured-choice* (capacidad del arnés — ver [`../harness/SKILL.md`](../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**, la acción de cierre propia del loop — **cada heir la define en su *Convergence / exit*** (p. ej. `Guardar especificación refinada` · `Cerrar tarea`) — | `Preguntar algo más`.
+- **Batching**: agrupar hasta 3 gaps de humano en una sola llamada. Si hay más de 3 pendientes, priorizar (los que desbloquean otros gaps primero) y diferir el resto a la próxima vuelta.
+- **Respuesta recomendada por pregunta**: cada pregunta de contenido lleva **siempre** la respuesta que la IA recomienda — como primera opción (marcada *recomendada*) en `AskUserQuestion`, o señalada en el markdown numerado al degradar. Nunca se pregunta "a secas": el humano ratifica o corrige una propuesta, no parte de cero. La IA recomienda en base a lo investigado (regla ask-vs-research), no por defecto vacío.
+
+## Compact / resume
+
+El resume **keya off el `CHECKPOINT`** de la session del run, no de la existencia de un archivo aparte. Tres casos al ejecutar el comando del flujo sobre una entrada:
+
+1. **En curso** (existe `CHECKPOINT.md` en la session) → reanuda desde el avance (gaps resueltos, Q&A, `attempts`, research inline en curso).
+2. **Sin avance** (no hay CHECKPOINT y el doc de entrada **no** tiene la marca de trabajo previo del flujo) → arranca desde cero leyendo el doc de entrada.
+3. **Ya convergido / re-run on demand** (no hay CHECKPOINT abierto pero el doc **ya tiene** la marca) → **operación de primera clase**: mientras el flujo siga en su etapa, re-correr el comando sobre la misma entrada **cuantas veces haga falta** está soportado. `create_or_resume` detecta la session existente —típicamente **cerrada** tras converger— por descriptor + `## Origin` y la **reabre** (ver *Internal sessions*: detección con `aw sessions --state all` / `aw resume-summary --include-recent-closed`, reapertura con `aw session-resume --code <NNN> --reopen`); trabajo incremental leyendo el **doc mismo**.
+
+> Cada heir define su **marca de trabajo previo**: en los refine loops, la presencia de `## Refinement decisions` + `## Q&A traceability` en el doc; en plan-exec, los checkbox `- [x]` del plan-doc; quick no tiene doc (resume solo por CHECKPOINT).
+
+> **`Compactar`** (control `flow`, transversal a los 3 casos) → escribe `CHECKPOINT.md` en la session (avance en progreso, gaps restantes, Q&A, `attempts`) → dispara la **compactación** del arnés (en Claude Code: `/compact`; ver [`../harness/SKILL.md`](../harness/SKILL.md)) → reanuda leyendo el checkpoint.
+
+## Convergence / exit
+
+- **Sin gaps materiales** → **convergence gate** (read-only) = **`Success criteria` en verde** (*verification-first*). Lo que falle **vuelve como gap**; si pasa → el loop ofrece su acción de cierre. Los heirs son **instancias** del mismo gate: `spec-refine` = analyze gate, `plan-new` y `plan-refine` = coherencia del plan, `plan-exec` = validación final, `quick` = validación puntual proporcional.
+- `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 + lo diferido); cierra la session y reporta. Así sobrevive el avance aunque no se haya `Compactar` antes.
+
+## docs/ boundary — sin auto-export (regla dura)
+
+Un loop escribe en `docs/` **solo** el doc de su propio flujo (spec-refine: `docs/specs` · plan-new/plan-refine/plan-exec: `docs/plans` · quick: **ninguno** — no toca `docs/`). Ningún loop **gradúa/promueve artefactos** a `docs/`: todo lo demás (migraciones → `docs/scripts`, manuales → `docs/manuals`, diagramas → `docs/diagrams`, etc.) lo hacen skills **`export-*`** aparte, como paso explícito posterior. Los artefactos quedan en sus sessions hasta entonces. Si una tarea crea una herramienta/utilidad, la documenta la skill ambiente `creating-tools` en `docs/tools` (auto-descubierta por su `description`; el workflow es **indiferente**, no la bindea).
+
+## Políticas de loops que editan código → `CODE-POLICIES.md`
+
+Los loops que **editan código** (`plan-exec-loop`, `quick-loop`) corren además las políticas de [`CODE-POLICIES.md`](CODE-POLICIES.md) — **git seguro** (rama verificada + commits propuestos) · **BD solo-scripts** · **gate de revisión de cierre** (proporcional en quick). Las mandan leer desde su `## Inherits` **junto con este chasis**; los loops de documento (spec-refine, plan-new, plan-refine) **no** las cargan — por eso viven en un doc aparte.
+
+## Qué NO es el chasis
+
+- **No es una skill**: no tiene frontmatter, no aparece en el system prompt, no se invoca ni se bindea vía `.workflow/skills.toml`. Es un documento **referenciado**: entra al contexto solo porque un loop manda leerlo.
+- **No corre solo**: no define flujo, deliverable ni gap taxonomy — eso es de cada heir. Sin un heir, el chasis no hace nada.
+- **Localización**: los heirs lo referencian como `../CHASSIS.md` (instalación normal, árbol `w/loops/`). En instalaciones **aplanadas** (p. ej. Warp/Oz) puede estar como `CHASSIS.md` **junto al `SKILL.md` del loop** (ídem `CODE-POLICIES.md` para los loops que editan código). En esas copias aplanadas los **links salientes** del chasis (`../SKILL.md`, `../harness/`, `../artifacts/`, `../roles/`) pueden no resolver: son **profundización opcional** — la doctrina del motor es autocontenida.

package/skills/w/loops/CODE-POLICIES.md

@@ -0,0 +1,34 @@
+# CODE-POLICIES — políticas de loops que editan código
+
+Aplican a **`plan-exec-loop`** (por fase del plan) y **`quick-loop`** (la única tarea; gate en versión **proporcional**): cada uno lo manda leer desde su `## Inherits`, **junto con el chasis** ([`CHASSIS.md`](CHASSIS.md)). Los loops de documento (spec-refine, plan-new, plan-refine) no editan código y **no cargan este doc** — por eso vive aparte del chasis. Estas políticas materializan los invariantes **BD solo-scripts** y **git seguro** — que además quedan resumidos **inline** (1-2 líneas) en el `SKILL.md` de cada loop que edita código, porque los hosts advisory no siguen Reads; el texto normativo completo vive acá.
+
+## Git seguro — rama verificada + commits propuestos
+
+- **Antes de editar** archivos de una fuente: verifica rama actual = rama esperada de esa fuente (`aw check-branch --source <alias>`; ver rol `git`). Si no coincide → **pausa y resuelve con el humano**; nunca `stash`/`reset --hard`/`checkout -- .`/`clean` sin confirmación por fuente.
+- **Commits propuestos** (propose-then-execute, aprobar antes): **tras pasar el gate de revisión de cierre** (abajo), propone commits **por fuente** — en plan-exec al cerrar cada fase (o al `Cerrar`); en quick, **un solo commit** al final si hubo cambios de código. Nunca `push`/`--amend`/`--no-verify`. Nada llega a un commit propuesto sin revisar.
+- **Commit rechazado**: los cambios **quedan en el working tree** (no se revierten). Se permite reproponer / editar mensaje. Se registra en `CHECKPOINT` + `BACKLOG` que la fase/tarea quedó **sin commitear** (reanudable).
+- **Precondición entre fases** (plan-exec): `branch-check` valida *identidad* de rama, **no** *limpieza* del working tree. Antes de iniciar la siguiente fase, el working tree de cada fuente debe estar **limpio** (committeado) o explícitamente **reconocido** como "cambios sin commitear de la fase N" — para no co-mezclar dos fases en un mismo commit.
+
+## BD solo-scripts — la IA nunca ejecuta DML/DDL
+
+Distinción por **ejecución**, no por archivo (ver el esquema [`SCRIPTS.sql`](../artifacts/artifacts-core/SCRIPTS.sql)):
+
+- **Consultas read-only** (diagnóstico/validación) → `SCRIPTS.sql` (artefacto de la session); la IA **sí** las ejecuta read-only vía MCP (`sql-mutation-guard`).
+- **Migraciones DDL/DML** (cambios de esquema/datos) → la IA las **redacta en `SCRIPTS.sql`** (artefacto de la session) pero **NUNCA las ejecuta**.
+
+> El SQL mutante **queda en la session**, no se mueve a `docs/`. Su promoción a `docs/scripts/` (forward + rollback) la hace un `export-*` **aparte**, no el loop.
+
+## Gate de revisión de cierre (convenciones, pre-commit)
+
+Tras la validación (de la fase en plan-exec; de la tarea en quick, proporcional) y **antes de proponer sus commits** (también en un `Cerrar` anticipado, antes de proponer los commits pendientes), el diff pasa un **gate de revisión de cierre**:
+
+- **Re-lectura independiente** del diff (subagente o re-lectura limpia — la *verificación independiente* del motor: no asume correcta la implementación; *only command output counts*).
+- **Aplica las convenciones ambientes instaladas** relevantes al stack tocado (estándares de código/stack, seguridad, revisión de diffs, familias propias del workspace) — el host las **auto-descubre por su `description`**. El workflow **no nombra ni bindea** skills concretas: **crea el momento; las skills instaladas lo llenan** (por eso la revisión **no es un rol** — ver [`../roles/README.md`](../roles/README.md)). Sin skills de convenciones instaladas → checklist genérico mínimo: SOLID/early-return, nombres claros, DRY, errores no silenciados, sin secrets/PII, SQL parametrizado, sin código muerto, + las `Validations` del plan (si las hay).
+- **Hallazgos**: se **corrigen** en el working tree y se **re-corre la validación** (el gate no reemplaza los tests: los re-verifica tras corregir), o se **difieren justificados** (→ `Open questions` del plan + `BACKLOG`; en quick, `BACKLOG`); lo no obvio → `DECISION`. Integridad del gate (ver [`CHASSIS.md`](CHASSIS.md) § *Verification-first*): nunca se debilita un check ni se baja una convención para pasar.
+- **Artifact-first + verification-first**: `CHECKPOINT.Next = "review <fase/tarea>"` antes de la pasada; `SESSION.Success criteria` incluye desde el inicio "el diff pasó el gate de revisión antes de sus commits".
+
+Recién con el gate en verde se proponen los commits.
+
+## Localización
+
+Igual que el chasis: los loops que editan código lo referencian como `../CODE-POLICIES.md` (instalación normal, árbol `w/loops/`); en instalaciones **aplanadas** (p. ej. Warp/Oz) puede estar como `CODE-POLICIES.md` **junto al `SKILL.md` del loop**.

package/skills/w/loops/README.md

@@ -8,26 +8,9 @@
 
 ## What a loop is
 
-Un loop es una **skill** que le enseña a la IA *cómo iterar* hasta producir un entregable. **No es invocable por nombre** con el tool `Skill` (no se registra como skill suelta): es el cuerpo de su comando `/w:…`, que lo **carga leyendo `<loop>/SKILL.md`** y lo ejecuta inline. La IA lo corre de punta a punta: detecta huecos, los resuelve (preguntando al humano o investigando), integra y repite hasta converger.
+Un loop es una **skill** que le enseña a la IA *cómo iterar* hasta producir un entregable. **No es invocable por nombre** con el tool `Skill` (no se registra como skill suelta): es el cuerpo de su comando `/w:…`, que lo **carga leyendo `<loop>/SKILL.md`** y lo ejecuta inline.
 
-Propiedades comunes a **los 5 loops**:
-
-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. **Entre turnos**, el mismo `CHECKPOINT`+resume hace que un prompt **sin comando** **continúe/reabra la sesión más reciente** en vez de arrancar trabajo suelto — la cara *inter-turno* del objetivo persistente (ver [`../SKILL.md`](../SKILL.md) § *Contexto operativo*).
-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.
-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
-
-El control `flow` es **fijo**: `Compactar` / `Cerrar`, presente en los 5 loops. Responder la pregunta de contenido **sin tocar `flow`** = seguir iterando ("continuar" es el comportamiento por defecto del loop, no una opción del canal de control).
-
-| Option | What it does |
-|---|---|
-| `Compactar` | Escribe `CHECKPOINT` (session dueña del run) + dispara la **compactación** del arnés (en Claude Code: `/compact`; ver [`../harness/SKILL.md`](../harness/SKILL.md)) y reanuda sin perder el hilo. |
-| `Cerrar` | `finalize`: persiste lo pendiente (`CHECKPOINT` siempre; `BACKLOG` solo si hay algo diferido), cierra la session y termina el loop. |
+Los 5 loops corren el mismo **motor común**, cuyo canon vive en [`CHASSIS.md`](CHASSIS.md): objetivo persistente + verification-first, gap-driven convergente, session única por run con research inline, structured-choice + control `flow` (`Compactar`/`Cerrar`, siempre presente), compact/resume, artefactos como log vivo, convergence gate y el boundary de `docs/`. Cada loop es un **heir**: su `## Inherits` manda leer el chasis antes de sus deltas — nada del motor se repite acá.
 
 ## Loops and their flow
 
@@ -43,25 +26,7 @@ El control `flow` es **fijo**: `Compactar` / `Cerrar`, presente en los 5 loops.
 
 ### `docs/` boundary (regla dura)
 
-Los loops **nunca** graduan/exportan artefactos a `docs/` automáticamente. Cada loop escribe **solo** su(s) carpeta(s):
-
-| Flow | Carpetas `docs/` que escribe |
-|---|---|
-| SPEC | `docs/specs` |
-| PLAN | `docs/plans` (living) |
-| QUICK | ninguna |
-
-Todo lo demás (migraciones → `docs/scripts`, manuales → `docs/manuals`, diagramas → `docs/diagrams`, informes → `docs/reports`) queda como **artefacto de session** hasta que un `export-*` lo promueva, como paso aparte y explícito.
-
-## Loops × flow control
-
-| Loop | pregunta(s) de contenido típicas | control `flow` |
-|---|---|---|
-| `spec-refine-loop` | dudas-de-humano · elección de MCP · convergencia (`Guardar especificación refinada` / `Preguntar algo más`) | `Compactar` / `Cerrar` |
-| `plan-new-loop` | dudas · elección de MCP · convergencia (`Guardar plan` / `Preguntar algo más`) | `Compactar` / `Cerrar` |
-| `plan-refine-loop` | dudas · elección de MCP · convergencia (`Guardar plan refinado` / `Preguntar algo más`) | `Compactar` / `Cerrar` |
-| `plan-exec-loop` | decisiones/dudas no obvias · elección de MCP · cierre (`Marcar plan done` / `Preguntar algo más`) | `Compactar` / `Cerrar` |
-| `quick-loop` | dudas no obvias · escalar a SPEC/PLAN · cierre (`Cerrar tarea` / `Preguntar algo más`) | `Compactar` / `Cerrar` |
+Cada loop escribe **solo** el doc de su propio flujo (SPEC→`docs/specs` · PLAN→`docs/plans` · QUICK→ninguno) y **nunca** gradúa otros artefactos a `docs/` — esa promoción la hacen las skills `export-*`, aparte y explícitas. Canon: [`CHASSIS.md`](CHASSIS.md) § *docs/ boundary*.
 
 ## Schema of each loop file
 
@@ -73,31 +38,14 @@ Todo lo demás (migraciones → `docs/scripts`, manuales → `docs/manuals`, dia
 | `## Reads` | Documento(s) de entrada |
 | `## Writes` | Documento(s) de salida (`generate` / `read-update`) |
 | `## Internal sessions` | Sessions que crea y sus artefactos |
-| `## Sequence` | Pseudocódigo + mermaid del loop |
+| `## Sequence` | Pseudocódigo del loop |
 | `## Convergence / exit` | Cuándo para |
 
-El **chasis** (`spec-refine-loop`) además detalla `## Composes` (capacidades que compone), `## Deliverable schema`, `## Gap taxonomy`, `## Ask-vs-research rule`, `## Research: autonomy, scope & failure`, `## Structured-choice`, `## Compact / resume`, `## Integration`.
-
-Los **heirs** (`plan-new-loop`, `plan-refine-loop`, `plan-exec-loop`, `quick-loop`) usan `## Inherits` (lo que reusan del chasis, sin repetirlo) + `## Delta N` (sus diferencias).
+Los **5 loops** son heirs: usan `## Inherits` (referencia de 1 línea a [`CHASSIS.md`](CHASSIS.md), que se lee **siempre antes** de los deltas) + sus secciones propias. Las secciones del motor viven en el chasis, no en ningún loop.
 
 ## Chassis / heirs
 
-```
-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)
-        ├── plan-new-loop    (heir)  → deltas: plan rico, gap taxonomy de plan
-        ├── plan-refine-loop (heir)  → deltas: refina el plan in place (aux, opcional);
-        │                               reusa gap taxonomy + coherence gate de plan-new
-        ├── plan-exec-loop   (heir)  → deltas: ejecución real (código/BD/git),
-        │                               una sola session por run, gate de revisión
-        │                               de cierre pre-commit, sin auto-export
-        └── quick-loop       (heir)  → deltas: ceremonia mínima, 1 session,
-                                        hereda git/BD/no-export de plan-exec
-```
-
-El chasis **no es una capacidad bindeable**: *es* `spec-refine-loop` y los demás loops lo heredan. Lo enchufable son las **capacidades** que un loop compone (ej. `ui-design`, `sql`, `git`), resueltas por `.workflow/skills.toml`.
+El **motor vive en [`CHASSIS.md`](CHASSIS.md)** (doc referenciado, no una skill); los 5 loops —incluido `spec-refine-loop`— son **heirs** de ese motor. La lista canónica de heirs y sus deltas está en el propio chasis (§ *Heirs*). El chasis **no es una capacidad bindeable**: es el motor de los loops; lo enchufable son las **capacidades** que un loop compone (ej. `ui-design`, `sql`, `git`), resueltas por `.workflow/skills.toml`.
 
 ## Composed capabilities (roles)
 
@@ -117,7 +65,8 @@ Los loops componen **capacidades por su rol**, no skills concretas; la skill que
 
 ## Index
 
-- [`spec-refine-loop/SKILL.md`](spec-refine-loop/SKILL.md) — el chasis
+- [`CHASSIS.md`](CHASSIS.md) — el motor común de los 5 loops (doc referenciado; no es una skill)
+- [`spec-refine-loop/SKILL.md`](spec-refine-loop/SKILL.md)
 - [`plan-new-loop/SKILL.md`](plan-new-loop/SKILL.md)
 - [`plan-refine-loop/SKILL.md`](plan-refine-loop/SKILL.md) — aux, opcional (refina el plan in place)
 - [`plan-exec-loop/SKILL.md`](plan-exec-loop/SKILL.md)

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

@@ -3,9 +3,10 @@ name: plan-exec-loop
 description: >-
   Ejecuta un plan de implementación (docs/plans/PPP-plan-<slug>.md) como
   living doc: lo lee y actualiza fase a fase mientras edita el código real,
-  gestiona BD y git. Heir del chasis spec-refine-loop (motor gap-driven,
-  research inline, structured-choice, artefactos como log vivo); sus deltas
-  viven en el cuerpo: session única reanudable, git seguro (rama verificada,
+  gestiona BD y git. Heir del chasis común de los loops (loops/CHASSIS.md —
+  motor gap-driven, research inline, structured-choice, artefactos como log
+  vivo, y las políticas de loops que editan código); sus deltas viven en el
+  cuerpo: session única reanudable, git seguro (rama verificada,
   commits propuestos por fuente, nunca push/--amend/--no-verify), BD solo-
   scripts (la IA nunca ejecuta DML/DDL), validación por fase y final, gate de
   revisión de cierre pre-commit, y sin auto-export (solo escribe docs/plans).
@@ -15,7 +16,7 @@ description: >-
 
 # plan-exec-loop
 
-> **Heir** del chasis [`spec-refine-loop`](../spec-refine-loop/SKILL.md). Aquí los **deltas de ejecución** — el trabajo real: código, BD, git. El motor (gap-driven, research inline, structured-choice + control `flow`, compact/resume, artefactos como log vivo) vive en el chasis.
+> **Heir** del chasis común — aquí los **deltas de ejecución**: el trabajo real (código, BD, git). El motor vive en el chasis y las *Políticas de loops que editan código* en `CODE-POLICIES.md` — no se repiten.
 
 ## Flow
 PLAN
@@ -36,16 +37,11 @@ PLAN
 
 ## Boundary — sin auto-export (hard rule)
 
-Este loop **nunca gradúa/promueve artefactos** a `docs/`. La única carpeta `docs/` que escribe es **`docs/plans`** (el plan, living). Todo lo demás (migraciones → `docs/scripts`, manuales → `docs/manuals`, diagramas → `docs/diagrams`, etc.) lo hacen skills **`export-*`** aparte, como paso explícito posterior. Los artefactos quedan en sus sessions hasta entonces. Si una tarea crea una herramienta/utilidad, la documenta la skill ambiente `creating-tools` en `docs/tools` (auto-descubierta por su `description`; el workflow es **indiferente**, no la bindea).
+Regla completa en el chasis (§ *docs/ boundary — sin auto-export*). Acá: la única carpeta `docs/` que este loop escribe es **`docs/plans`** (el plan, living); todo lo demás queda en la session hasta un `export-*` explícito y posterior.
 
 ## Inherits
 
-Del chasis [`spec-refine-loop`](../spec-refine-loop/SKILL.md), sin cambios:
-
-- **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).
+Leé **[`../CHASSIS.md`](../CHASSIS.md)** (instalación normal) **o** `CHASSIS.md` junto a este archivo (instalación aplanada) — el motor completo del loop (objetivo persistente + verification-first, gap-driven, session única + research inline, structured-choice + control `flow`, compact/resume, artefactos como log vivo, numeración, convergence gate, docs/ boundary) — **y** **[`../CODE-POLICIES.md`](../CODE-POLICIES.md)** (o `CODE-POLICIES.md` junto a este archivo) — las *Políticas de loops que editan código* (git seguro · BD solo-scripts · gate de revisión de cierre) — **siempre antes** de estos deltas.
 
 ## Composes
 
@@ -68,22 +64,15 @@ Del chasis [`spec-refine-loop`](../spec-refine-loop/SKILL.md), sin cambios:
 - Ejecuta las `Tasks` de la fase; **salta** las ya marcadas `- [x]` en el plan (el plan-doc es la fuente de verdad por tarea). Marca `- [x]` + estado **en el plan** (living doc; no en un `TASKS` aparte).
 - En **cada límite de fase**: valida, corre el **gate de revisión de cierre** (Delta 5), actualiza el `CHECKPOINT` (Completed += Phase N, Next = Phase N+1) y propone commits.
 - Registra `DECISION` solo lo **no obvio**, **a medida que se toma** (los `DECISION` por fase se acumulan en el ÚNICO `DECISION`, etiquetados por fase/tarea — ej. `Origin: T2 (F1)`).
+- El motor **gap-driven** del chasis aplica acá **dentro de una tarea**: ante una decisión/duda no obvia → research inline ó structured-choice.
 
 ## Delta 2 — Git policy: **rama segura + commits propuestos**
 
-- **Antes de editar** archivos de una fuente: verifica rama actual = rama esperada de esa fuente (`aw check-branch --source <alias>`; ver rol `git`). Si no coincide → **pausa y resuelve con el humano**; nunca `stash`/`reset --hard`/`checkout -- .`/`clean` sin confirmación por fuente.
-- **Al cerrar una fase** (o al `Cerrar`): **tras pasar el gate de revisión de cierre** (Delta 5), **propone commits por fuente** (propose-then-execute, aprobar antes); nunca `push`/`--amend`/`--no-verify`. Nada llega a un commit propuesto sin revisar.
-- **Commit rechazado**: los cambios **quedan en el working tree** (no se revierten). Se permite reproponer / editar mensaje. Se registra en `CHECKPOINT` + `BACKLOG` que la fase quedó **sin commitear** (reanudable).
-- **Precondición entre fases**: `branch-check` valida *identidad* de rama, **no** *limpieza* del working tree. Antes de iniciar la siguiente fase, el working tree de cada fuente debe estar **limpio** (committeado) o explícitamente **reconocido** como "cambios sin commitear de la fase N" — para no co-mezclar dos fases en un mismo commit.
+Política completa en [`../CODE-POLICIES.md`](../CODE-POLICIES.md) (§ *Git seguro*: branch-check antes de editar, commit rechazado — los cambios quedan + se registra —, precondición de working tree entre fases). **Inline:** antes de editar, verificar rama esperada por fuente (`aw check-branch --source <alias>`; si no coincide → pausar y resolver con el humano); al cerrar cada fase y **tras el gate de revisión** (Delta 5), **commits propuestos por fuente** (aprobar antes) — nunca `push`/`--amend`/`--no-verify`.
 
 ## Delta 3 — DB policy: **la IA nunca ejecuta DML**
 
-Distinción por **ejecución**, no por archivo (ver el esquema `SCRIPTS.sql`):
-
-- **Consultas read-only** (diagnóstico/validación) → `SCRIPTS.sql` (artefacto de la session); la IA **sí** las ejecuta read-only vía MCP (`sql-mutation-guard`).
-- **Migraciones DDL/DML** (cambios de esquema/datos) → la IA las **redacta en `SCRIPTS.sql`** (artefacto de la session) pero **NUNCA las ejecuta**.
-
-> El SQL mutante **queda en la session**, no se mueve a `docs/`. Su promoción a `docs/scripts/` (forward + rollback) la hace un `export-*` **aparte**, no este loop.
+Política completa en [`../CODE-POLICIES.md`](../CODE-POLICIES.md) (§ *BD solo-scripts*). **Inline:** consultas read-only → `SCRIPTS.sql` de la session y se ejecutan vía MCP (`sql-mutation-guard`); migraciones DDL/DML → la IA las **redacta en `SCRIPTS.sql` pero NUNCA las ejecuta** — su promoción a `docs/scripts/` la hace un `export-*` aparte, no este loop.
 
 ## Delta 4 — Validation
 
@@ -95,14 +84,7 @@ Distinción por **ejecución**, no por archivo (ver el esquema `SCRIPTS.sql`):
 
 ## Delta 5 — Gate de revisión de cierre (convenciones, pre-commit)
 
-Tras la validación de la fase y **antes de proponer sus commits** (también en un `Cerrar` anticipado, antes de proponer los commits pendientes), el diff de la fase pasa un **gate de revisión de cierre**:
-
-- **Re-lectura independiente** del diff (subagente o re-lectura limpia — la *verificación independiente* del chasis: no asume correcta la implementación; *only command output counts*).
-- **Aplica las convenciones ambientes instaladas** relevantes al stack tocado (estándares de código/stack, seguridad, revisión de diffs, familias propias del workspace) — el host las **auto-descubre por su `description`**. El workflow **no nombra ni bindea** skills concretas: **crea el momento; las skills instaladas lo llenan** (por eso la revisión **no es un rol** — ver [`../../roles/README.md`](../../roles/README.md)). Sin skills de convenciones instaladas → checklist genérico mínimo: SOLID/early-return, nombres claros, DRY, errores no silenciados, sin secrets/PII, SQL parametrizado, sin código muerto, + las `Validations` del plan.
-- **Hallazgos**: se **corrigen** en el working tree y se **re-corre la validación de la fase** (el gate no reemplaza los tests: los re-verifica tras corregir), o se **difieren justificados** (→ `Open questions` del plan + `BACKLOG`); lo no obvio → `DECISION`. Integridad del gate (chasis): nunca se debilita un check ni se baja una convención para pasar.
-- **Artifact-first + verification-first**: `CHECKPOINT.Next = "review fase N"` antes de la pasada; `SESSION.Success criteria` incluye desde el inicio "cada fase pasó el gate de revisión antes de sus commits".
-
-Recién con el gate en verde se proponen los commits de la fase (Delta 2).
+Gate completo en [`../CODE-POLICIES.md`](../CODE-POLICIES.md) (§ *Gate de revisión de cierre*): re-lectura **independiente** del diff + convenciones ambientes instaladas; hallazgos → corregir (re-validando la fase) o diferir justificado. Acá solo el cableado exec: corre **entre la validación de la fase (Delta 4) y sus commits (Delta 2)**; recién con el gate en verde se proponen los commits de la fase.
 
 ## Delta 6 — Completitud / cierre
 
@@ -148,27 +130,6 @@ plan-exec-loop(PPP-plan-<slug>.md):
 finalize: CHECKPOINT (+ BACKLOG si difiere) + cerrar session + reportar
 ```
 
-```mermaid
-flowchart TD
-    S["create_or_resume plan-exec session (única)<br/>read PPP-plan-&lt;slug&gt;.md"] --> P{"¿más Phases<br/>(no done)?"}
-    P -->|no| V2["validación final<br/>(dep. de SQL → handoff)"]
-    P -->|sí| T{"¿Task pendiente<br/>(no - [x])?"}
-    T -->|sí| G["branch-check por fuente"]
-    G -->|rama ok| DO["editar código · read-only→SCRIPTS.sql<br/>migración DDL/DML→SCRIPTS.sql (no ejecuta) · DECISION"]
-    G -->|rama ≠| PA["pausar + resolver con humano"]
-    PA --> G
-    DO --> MK["marcar Task - [x] en el PLAN"]
-    MK --> T
-    T -->|no| VP["validación de fase<br/>(falla→tarea · dep. SQL→diferir)"]
-    VP --> RV["gate de revisión de cierre<br/>(diff + convenciones ambientes → corregir/diferir)"]
-    RV --> CK["update CHECKPOINT (Completed/Next)"]
-    CK --> CM["proponer commits por fuente"]
-    CM -->|aprobado| P
-    CM -->|rechazado| RJ["cambios quedan · registrar 'sin commitear'"]
-    RJ --> P
-    V2 --> FIN["structured-choice[Marcar plan done · Preguntar más]<br/>plan done (sin auto-export)"]
-```
-
 ## Convergence / exit
 
 - Plan completo + validación OK (o diferida con handoff) + **cada fase pasó su gate de revisión de cierre** antes de commitear → `Marcar plan done`.

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

@@ -2,9 +2,10 @@
 name: plan-new-loop
 description: >-
   Genera un plan de implementación rico (docs/plans/PPP-plan-<slug>.md) a
-  partir de un spec (docs/specs/NNN-spec-<slug>.md). Heir del chasis spec-
-  refine-loop (motor gap-driven convergente, session única, research inline,
-  structured-choice, artefactos como log vivo); sus deltas viven en el cuerpo:
+  partir de un spec (docs/specs/NNN-spec-<slug>.md). Heir del chasis común de
+  los loops (loops/CHASSIS.md — motor gap-driven convergente, session única
+  con research inline, structured-choice, artefactos como log vivo); sus
+  deltas viven en el cuerpo:
   el plan absorbe el nivel TECHNICAL-NOTE + Phases/Tasks con estado vivo,
   research de mapeo código/impacto, gap taxonomy de planificación, y si el
   plan incluye UI compone ui-design para autorar design SPECs por pantalla
@@ -15,7 +16,7 @@ description: >-
 
 # plan-new-loop
 
-> **Heir** del chasis [`spec-refine-loop`](../spec-refine-loop/SKILL.md). Aquí **solo** los deltas. El motor (gap-driven, sesión única, structured-choice + control `flow`, research inline + regla BD, compact/resume, artefactos como log vivo) vive en el chasis — no se repite.
+> **Heir** del chasis común — aquí **solo** los deltas de PLAN-new. El motor no se repite.
 
 ## Flow
 PLAN
@@ -36,14 +37,15 @@ PLAN
 
 ## Inherits
 
-Del chasis [`spec-refine-loop`](../spec-refine-loop/SKILL.md), sin cambios:
+Leé **[`../CHASSIS.md`](../CHASSIS.md)** (instalación normal) **o** `CHASSIS.md` junto a este archivo (instalación aplanada) — el motor completo del loop (objetivo persistente + verification-first, gap-driven, session única + research inline, structured-choice + control `flow`, compact/resume, artefactos como log vivo, numeración, convergence gate), **siempre antes** de estos deltas.
 
-- **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 `<slug>-plan-new` → `NNN-<slug>-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`).
-- **Compact / resume** y **artefactos como log vivo (ciclo artifact-first)** (`CHECKPOINT` siempre; `BACKLOG` solo si difiere).
-- **Naming + numeración global** del chasis: `<run>` = descriptor `<slug>-plan-new`, donde `<slug>` sale del spec de entrada (`docs/specs/NNN-spec-<slug>.md`) → folder autodescriptivo `NNN-<slug>-plan-new`. El CLI antepone el `NNN` global y secuencial (sin reiniciar por tipo); el caller pasa solo el descriptor.
+## Internal sessions — instancia PLAN-new
+
+Doctrina completa en el chasis (§ *Internal sessions* + *Numeración*). La instancia de este loop:
+
+| Session | When | Artifacts | Role |
+|---|---|---|---|
+| **plan session** `NNN-<slug>-plan-new/` | al arrancar el loop (o se reanuda) | `SESSION.md` · `CHECKPOINT.md` (· `BACKLOG.md` solo si difiere) | Dueña del run. Type = `refine`; descriptor `<slug>-plan-new` (el `<slug>` sale del spec de entrada). |
 
 ## Delta 1 — Deliverable: PLAN RICO (`PPP-plan-<slug>.md`)
 

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

@@ -3,10 +3,11 @@ name: plan-refine-loop
 description: >-
   Refina un plan existente (docs/plans/PPP-plan-<slug>.md) editándolo IN
   PLACE, como paso auxiliar y NO obligatorio del flujo PLAN antes de plan-
-  exec. Es a plan-new lo que spec-refine es a spec-new. Heir del chasis spec-
-  refine-loop (motor gap-driven, session única, research inline, structured-
-  choice, artefactos como log vivo); reusa la gap taxonomy y el coherence gate
-  de plan-new-loop, agrega Refinement decisions/Q&A traceability al plan
+  exec. Es a plan-new lo que spec-refine es a spec-new. Heir del chasis común
+  de los loops (loops/CHASSIS.md — motor gap-driven, session única con
+  research inline, structured-choice, artefactos como log vivo); reusa la gap
+  taxonomy y el coherence gate de plan-new-loop, agrega Refinement
+  decisions/Q&A traceability al plan
   (traza, sin gating), y si el refine toca UI compone ui-design y
   produce/actualiza design SPECs por pantalla. Lo arranca /w:plan-refine;
   reanudable y re-corrible a demanda. Invocar cuando un plan ya generado deba
@@ -15,7 +16,7 @@ description: >-
 
 # plan-refine-loop
 
-> **Heir** del chasis [`spec-refine-loop`](../spec-refine-loop/SKILL.md). Aquí **solo** los deltas. El motor (gap-driven, sesión única, structured-choice + control `flow`, research inline + regla BD, compact/resume, artefactos como log vivo, objetivo persistente + verification-first) vive en el chasis — no se repite.
+> **Heir** del chasis común — aquí **solo** los deltas de PLAN-refine. El motor no se repite.
 
 > **Relación con los otros loops de PLAN:** `plan-new-loop` **genera** el plan desde el spec; `plan-refine-loop` **lo refina in place** (opcional); `plan-exec-loop` **lo ejecuta**. plan-refine es a plan-new lo que spec-refine es a spec-new.
 
@@ -39,17 +40,19 @@ Actualiza `docs/plans/PPP-plan-<slug>.md` **in place** (cuando el usuario elige
 
 ## Inherits
 
-Del chasis [`spec-refine-loop`](../spec-refine-loop/SKILL.md), sin cambios:
+Leé **[`../CHASSIS.md`](../CHASSIS.md)** (instalación normal) **o** `CHASSIS.md` junto a este archivo (instalación aplanada) — el motor completo del loop (objetivo persistente + verification-first, gap-driven, session única + research inline, structured-choice + control `flow`, compact/resume, artefactos como log vivo, numeración, convergence gate), **siempre antes** de estos deltas.
 
-- **Objetivo persistente + verification-first**: persigue su `SESSION.Objective` hasta que sus `SESSION.Success criteria` están **en verde** (sembrados al inicio; acá la rúbrica = **coherencia del plan**, ver *Convergence*). Motor **gap-driven convergente** + **ciclo artifact-first** (sembrar `CHECKPOINT.Pending/Next` ANTES → `detect_gaps` → resolver → integrar → `Pending→Completed` DESPUÉS; gaps agotados con límite `MAX` no se re-disparan).
-- **Una sola session por run**: descriptor `<slug>-plan-refine` → `NNN-<slug>-plan-refine` (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. El CLI antepone el `NNN` global; el caller pasa solo el descriptor.
-- **Structured-choice**: ≤3 preguntas de contenido + 1 control `flow` (`Compactar`/`Cerrar`) siempre (ver [`../../harness/SKILL.md`](../../harness/SKILL.md); en Claude Code es `AskUserQuestion`). Cada pregunta de contenido lleva **respuesta recomendada**.
-- **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`).
-- **Compact / resume** y **artefactos como log vivo (ciclo artifact-first)** (`CHECKPOINT` siempre; `BACKLOG` solo si difiere). **Integridad del gate** (anti-gaming + verificación independiente): *only command output counts*.
+## Internal sessions — instancia PLAN-refine
+
+Doctrina completa en el chasis (§ *Internal sessions* + *Numeración*). La instancia de este loop:
+
+| Session | When | Artifacts | Role |
+|---|---|---|---|
+| **refine session** `NNN-<slug>-plan-refine/` | al arrancar el loop (o se reanuda/reabre) | `SESSION.md` · `CHECKPOINT.md` (· `BACKLOG.md` solo si difiere) | Dueña del run. Type = `refine`; descriptor `<slug>-plan-refine` (el `<slug>` sale del plan de entrada). |
 
 ## Delta 1 — Deliverable: el PLAN, editado in place
 
-El plan usa el **mismo esqueleto** que produce [`plan-new-loop`](../plan-new-loop/SKILL.md) (§ *Delta 1 — PLAN RICO*: `Summary`/`Solution`/`Impacted`/`Phases`/`Tasks`/`Validations`/`Final behavior`/… con secciones `(core)` siempre y `(opt.)` según complejidad). plan-refine **no** cambia el esquema: **completa/ajusta** las secciones existentes **in place** y **agrega** dos de traza:
+El plan usa el **mismo esqueleto** que produce [`plan-new-loop`](../plan-new-loop/SKILL.md) (en instalaciones aplanadas: la copia hermana `w-plan-new-loop/SKILL.md`) (§ *Delta 1 — PLAN RICO*: `Summary`/`Solution`/`Impacted`/`Phases`/`Tasks`/`Validations`/`Final behavior`/… con secciones `(core)` siempre y `(opt.)` según complejidad). plan-refine **no** cambia el esquema: **completa/ajusta** las secciones existentes **in place** y **agrega** dos de traza:
 
 ```markdown
 ## Refinement decisions   ← NEW (se AGREGA)