@tacuchi/agent-workflow-cli 15.2.0 → 16.0.0

package/skills/w/loops/CHASSIS.md

@@ -1,163 +1,166 @@
-# CHASSIS — motor de los loops
+# CHASSIS — the loop engine
 
-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.
+This document is the **common engine** of the agent-workflow loops: the doctrine every loop runs underneath its deltas. **It is not a skill** — it is a referenced document: every loop orders it read from its `## Inherits`, **always, before its deltas**. If you edit the engine, edit it **here** — heirs never repeat it, they only reference it.
 
-## Heirs (lista canónica)
+## Heirs (canonical list)
 
-Los **5 loops** corren este motor; cada uno agrega solo sus deltas:
+The **5 loops** run this engine; each adds only its 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).
+- [`spec-refine-loop`](spec-refine-loop/SKILL.md) — refines the **spec** in place; deltas: spec gap taxonomy, analyze gate, `## UI spec` via the `ui-design` capability.
+- [`plan-new-loop`](plan-new-loop/SKILL.md) — generates the **plan** from the spec; deltas: rich plan + plan gap taxonomy (+ per-screen design SPECs when the plan includes UI).
+- [`plan-refine-loop`](plan-refine-loop/SKILL.md) — refines the **plan** in place (auxiliary, not mandatory); reuses the gap taxonomy + coherence gate of `plan-new-loop`. It is to `plan-new` what `spec-refine` is to `spec-new`.
+- [`plan-exec-loop`](plan-exec-loop/SKILL.md) — **executes** the plan: code/DB/git, a single session per run, per-phase progress in the plan-doc, no auto-export. Applies the policies in [`CODE-POLICIES.md`](CODE-POLICIES.md).
+- [`quick-loop`](quick-loop/SKILL.md) — the engine with **minimal ceremony** (the prompt *is* the objective); also applies [`CODE-POLICIES.md`](CODE-POLICIES.md) (proportional gate).
 
-## Objetivo persistente
+## Persistent objective
 
-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.
+A loop **is a persistent objective**: it exists to fulfill the `SESSION.Objective` declared at start, and **it is not finished until the convergence gate confirms the objective was met**. Gap-driven iteration is the *method*; the artifacts are the *record*; the persistent objective is the *frame* that governs them.
 
-Es **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 hook del arnés — y **deja registro durable** (artifact-first) que sobrevive compactación y resume. *(Racional y análogo con el `/goal` de Claude Code: ver diseño, `workflow-loops/chassis.md`.)*
+This is **harness-agnostic doctrine**, not a host dependency: "don't stop until convergence" is sustained by the loop itself (its `repeat:` + the convergence gate), not by a host hook — and it **leaves a durable record** (artifact-first) that survives compaction and resume. *(Rationale and the `/goal` analogy: see the design, `workflow-loops/chassis.md`.)*
 
-> Cada heir instancia el frame: `spec-refine` persigue el spec; `plan-new`/`plan-refine` el plan hasta su gate; `plan-exec` el plan hasta su validación final; `quick-loop` es la encarnación más directa (el prompt *es* el objetivo).
+> Each heir instantiates the frame: `spec-refine` pursues the spec; `plan-new`/`plan-refine` pursue the plan up to their gate; `plan-exec` pursues the plan up to its final validation; `quick-loop` is the most direct embodiment (the prompt *is* the objective).
 
-> **Continuidad inter-turno.** El mismo `CHECKPOINT`+resume gobierna también el **próximo prompt**: el objetivo persiste **entre turnos**, no solo dentro del run. Las reglas canónicas (comando = línea nueva · re-run = `create_or_resume` · prompt pelado = continuar la más reciente · reapertura de cerradas · escalación consentida) viven en [`../SKILL.md`](../SKILL.md) § *Contexto operativo* — **única fuente**; este motor las ejecuta vía *Compact / resume* (caso 3).
+> **Inter-turn continuity.** The same `CHECKPOINT`+resume also governs the **next prompt**: the objective persists **across turns**, not only within a run. The canonical rules (command = new work line · re-run = `create_or_resume` · bare prompt = continue the most recent session · reopening closed sessions · consented escalation) live in [`../SKILL.md`](../SKILL.md) § *Operating context* — **single source**; this engine executes them via *Compact / resume* (case 3).
 
 ## 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*.
+The persistent objective needs a **checkable done-condition** — otherwise the loop cannot know when it is done (or chases a target it invented). That condition is **seeded BEFORE executing**, never improvised at the end: it is **generalized TDD**. Together with artifact-first (next section) these are the **two seeds** of every gap/phase: *how will I know it worked* + *what am I about to do*.
 
-**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:
+**Where it lives:** in `SESSION.Success criteria` (see [`../artifacts/artifacts-core/SESSION.md`](../artifacts/artifacts-core/SESSION.md)) — a `[ ]` checklist of **falsifiable** criteria (that *can* fail). `CHECKPOINT.Pending/Completed` tracks the **red→green** progress. Two forms, by deliverable:
 
-| Deliverable | Criterio = | Ciclo |
+| Deliverable | Criterion = | Cycle |
 |---|---|---|
-| 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 |
+| code / script / fix / feature | **runnable tests** (unit, build, lint, bug repro) | literal TDD: red → green → refactor |
+| DB migration (not executable; invariant 4) | **rubric**: `SCRIPTS.sql` valid + reviewed (never executed) | rubric |
+| spec / plan | **rubric** = the document's acceptance criteria (referenced, not duplicated) | rubric |
+| analysis / design | **rubric falsifiable by inspection** (e.g. "every affected site with `file:line`"; "each decision: rationale + ≥1 alternative") | rubric |
 
-- **Forma y peso escalan** (ceremonia mínima de quick preservada): chore = "tests/build existentes siguen verdes" (una línea); feature = acceptance tests reales. La regla es "**siempre declarar el check antes**", no "siempre escribir tests nuevos".
-- **Deliverable subjetivo** (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` y el loop **degrada** (humano, o difiere a `Open questions`/`BACKLOG`) — **nunca itera en falso**.
+- **Form and weight scale** (quick's minimal ceremony preserved): a chore = "existing tests/build stay green" (one line); a feature = real acceptance tests. The rule is "**always declare the check before**", not "always write new tests".
+- **Subjective deliverable** (analysis/design): the AI **proposes** the rubric and the **human ratifies** it (structured-choice) before pursuing it.
+- **Unresolvable criterion** (no evidence, DB unavailable): closes as `inconclusive` and the loop **degrades** (asks the human, or defers to `Open questions`/`BACKLOG`) — **never iterates against a fake target**.
 
-> 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.
+> The **convergence gate** (section *Convergence / exit*) is, operationally, **"all `Success criteria` green"**. The per-heir gates (analyze gate; plan coherence — plan-new and plan-refine; final validation; proportional spot validation) are **instances** of it, with the criteria seeded at start.
 
-**Integridad del gate (anti-gaming + verificación independiente).** El gate solo vale si no se hace trampa para pasarlo. El loop **no**:
+**Gate integrity (anti-gaming + independent verification).** The gate only counts if it is not gamed to pass. The loop does **not**:
 
-- 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).
+- modify the check or loosen a `Success criterion` to force green;
+- weaken, delete or skip tests/validations;
+- use trivial or tautological asserts that always pass (the expected value comes from an independent source, never from the output itself);
+- patch the test instead of fixing the cause (prefer fixing production code).
 
-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*.
+Facing a real blocker it **stops and reports it** (→ `Open questions`/`BACKLOG`) instead of gaming the metric. The verdict counts **only the check's output, never the implementer's self-declaration**: when the deliverable warrants it, the final verification is an **independent** pass (subagent or clean re-read) that does not assume the implementation is correct — *only command output counts*.
 
-## Artifacts as a live log — ciclo artifact-first
+## Artifacts as a live log — the artifact-first cycle
 
-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**:
+The loop works **artifact-first**: the artifact is **seeded before** executing and **updated after**, not only on close. Every gap/phase/task runs the **3-beat** cycle:
 
-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).
+1. **BEFORE — seed the intent.** Before executing, record in the artifact what is **about to** be done: `CHECKPOINT.Pending`/`Next` = the imminent work (`SESSION.Objective` already fixed the run's what).
+2. **EXECUTE.** Resolve the gap / run the phase / edit the code.
+3. **AFTER — bring to actual state.** `CHECKPOINT.Pending → Completed`; `DECISION` records the non-obvious **as it is decided**; `BACKLOG` **only if** something is deferred/follow-up (`session-close` no longer fabricates an empty BACKLOG).
 
-> 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**.
+> The artifact expresses the **intent** (Pending/Next, before) and then the **result** (Completed/DECISION, after), at **every** gap/phase boundary — not only on `Compactar`/`Cerrar`. Session artifacts are the run's live log; the spec/plan is the **guiding base**.
 
-## Motor gap-driven convergente
+## Gap-driven convergent engine
 
-El ciclo común — cada heir lo instancia en su `## Sequence` con su propia gap taxonomy:
+The common cycle — each heir instantiates it in its `## Sequence` with its own gap taxonomy:
 
-1. `detect_gaps(work)`, menos los gaps *agotados* (ver *Research*).
-2. Si `∅` → **convergence gate** (ver *Convergence / exit*).
-3. Si hay gaps: tomar un batch (≤3) y **sembrar** `CHECKPOINT.Pending/Next` (*artifact-first*).
-4. Resolver cada gap con su **resolutor** según la *ask-vs-research rule*: humano (structured-choice) · research inline · una capacidad compuesta (p. ej. `ui-design`).
-5. **Integrar**, actualizar `CHECKPOINT` → repetir.
+1. `detect_gaps(work)`, minus the *exhausted* gaps (see *Research*).
+2. If `∅` → **convergence gate** (see *Convergence / exit*).
+3. If there are gaps: take a batch (≤3) and **seed** `CHECKPOINT.Pending/Next` (*artifact-first*).
+4. Resolve each gap with its **resolver** per the *ask-vs-research rule*: human (structured-choice) · inline research · a composed capability (e.g. `ui-design`).
+5. **Integrate**, update `CHECKPOINT` → repeat.
 
-## Internal sessions (managed) — una session por run
+## Internal sessions (managed) — one session per 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`.
+The loop creates and manages its session under `.workflow/sessions/`. **The user never creates it.** **A single session per run**, owning the run: it keeps progress live (`CHECKPOINT`) and enables resume. Artifacts: `SESSION.md` · `CHECKPOINT.md` (· `BACKLOG.md` only if something is deferred; code-editing loops add `DECISION` and `SCRIPTS.sql`). Each heir declares its descriptor and `Type` in its own `## 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*.
+> **INLINE research** — investigation is **not** a separate session: it is an activity **inside the current session** that writes its artifacts (`ANALYSIS-FILE`/`CONCLUSIONS`, + read-only `SCRIPTS.sql` if it queries DB) **into the run's own session folder**. See *Research: autonomy, scope & failure*.
 
-> El doc de entrada del flujo (spec/plan) **nunca** entra en una session; vive en `docs/`.
+> The flow's input document (spec/plan) **never** goes inside a session; it lives in `docs/`.
 
-### Numeración de sessions (regla dura)
+### Session numbering (hard rule)
 
-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`).
+The **CLI owns the number**: `aw session-create` prepends a **global, sequential** `NNN` by scanning **all** sessions under `.workflow/sessions/` (any type). The caller passes **only the descriptor** via `--name` — **never** a number. Numbering neither restarts per type nor collides, and every folder is **self-describing**: `NNN-<slug>-<flow>` (e.g. `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).
+> `<run>` = the session's **descriptor** (no number), always shaped **`<slug>-<flow>`**: `<slug>-spec-refine`, `<slug>-plan-new`, `<slug>-plan-refine`, `<slug>-plan-exec`, `<slug>-quick`. The `<slug>` is **descriptive** and comes from the flow's input doc — `docs/specs/NNN-spec-<slug>.md` for spec-refine/plan-new; `docs/plans/PPP-plan-<slug>.md` for plan-refine/plan-exec; the prompt for quick — so the folder says at a glance what it is about, not just which flow created it. Research being **inline** in this same session, there are no child `*-research-*` sessions to number (compat: old ones are historical).
 >
-> **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.
+> **Resume**: locate the existing session by **scanning** `.workflow/sessions/` for descriptor + `## Origin` (which spec/plan), **not** by reconstructing the number (global, not derivable from the artifact). `aw session-resume --code <NNN | folder>` resolves both forms.
 
 **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)
+- `aw session-create --type <type> --name <slug>-<flow>` → creates `NNN-<slug>-<flow>` / `aw session-resume --code <…>` (detects `CHECKPOINT`).
+- `aw checkpoint-write` / `aw checkpoint-read` for resume.
+- `aw session-close` on close (with reason); `aw session-artifacts` to inspect.
+- **Reopen to continue** (operating context, row 2): `aw session-resume --code <NNN> --reopen` reactivates a **closed** session (removes `.closed` → active) to keep working in it; without `--reopen`, resume is read-only. To detect the most recent closed one: `aw resume-summary --include-recent-closed` (or `aw sessions --state all`).
 
-Para cada gap, una sola pregunta decide el resolutor:
+## Ask-vs-research rule (the discriminator)
 
-> *"¿Puedo responder esto leyendo el repo/datos?"* → **research** (autónomo).
-> *"¿Depende de lo que el usuario quiere?"* → **preguntar al humano** (structured-choice).
+For every gap, a single question picks the resolver:
+
+> *"Can I answer this by reading the repo/data?"* → **research** (autonomous).
+> *"Does it depend on what the user wants?"* → **ask the human** (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**.
+Investigation is **inline**: an activity **inside the run's current session**, never a separate session. It writes its artifacts (`ANALYSIS-FILE` → `CONCLUSIONS`, + read-only `SCRIPTS.sql` if it queries DB) into the **session's own folder**.
 
-- **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.
+- **Autonomous**: the AI investigates inline and reports **without asking permission**. The human learns of it at integration time (in the flow's decision record — e.g. `## Refinement decisions` in the refine loops, `DECISION` in the code-editing ones) and keeps control via the `flow` control.
+- **Scope**: workspace + associated repos (sources) + DB MCPs.
+- **DB rule** (the single exception to autonomy):
+  1. **MCP choice**: if the gap needs DB and there is **>1 candidate MCP with no configured default**, the AI asks which one to use. That question goes through the **same structured-choice** as a **content question** (counts inside the ≤3 + `flow` limit), **before** running queries. A single MCP or a default → no question.
+  2. Write the queries **first** into the session's `SCRIPTS.sql`.
+  3. Execute them **read-only** via MCP (respect `sql-mutation-guard`: never DML/DDL).
+- **Inconclusive research** (DB unavailable, insufficient evidence, unresolvable factual gap):
+  - The investigation closes with status **`inconclusive`** in `CONCLUSIONS` and reports why.
+  - The loop **degrades** the gap: to a **human question** (next batch → the flow's Q&A record: `Q&A traceability` in refine loops, `DECISION` in code-editing ones) or, failing that, **defers** it to the flow doc's `## Open questions` (spec/plan) — or the session's `BACKLOG` when the flow has no doc (quick).
+  - The gap is marked **"already tried via research"** (`attempts[gap]++`, `MAX` cap) so `detect_gaps` does **not** re-fire it in a loop → guarantees convergence.
 
 ## Structured-choice (design & batching)
 
-**Regla canónica (única fuente — el resto del corpus solo referencia):** *structured-choice* = **≤3 preguntas de contenido + 1 control `flow`**, siempre. Binding por arnés en [`../harness/SKILL.md`](../harness/SKILL.md) (Claude Code: `AskUserQuestion`, máx 4 preguntas/llamada; sin elección estructurada, degrada a **markdown numerado**).
+**Canonical rule (single source — the rest of the corpus only references it):** *structured-choice* = **≤3 content questions + 1 `flow` control**, always. Per-harness binding in [`../harness/SKILL.md`](../harness/SKILL.md) (Claude Code: `AskUserQuestion`, max 4 questions/call; without structured choice it degrades to **numbered markdown**).
+
+- Since the `flow` control is **always** present → **≤3 content questions + 1 `flow` control**.
+- **`flow` control** (lifecycle, always present): `Compactar` | `Cerrar`. Answering only the content questions (not touching `flow`) = keep iterating.
+- **Content questions** can be:
+  - human doubts (non-factual gaps);
+  - MCP choice (DB rule) — before running queries;
+  - at **convergence**, the loop's own closing action — **each heir defines it in its *Convergence / exit*** (e.g. `Guardar especificación refinada` · `Cerrar tarea`) — | `Preguntar algo más`.
+- **Batching**: group up to 3 human gaps in one call. With more than 3 pending, prioritize (the ones that unblock other gaps first) and defer the rest to the next round.
+- **Recommended answer per question**: every content question **always** carries the AI's recommended answer — as the first option (marked *recommended*) in `AskUserQuestion`, or flagged in the numbered-markdown fallback. Never ask "cold": the human ratifies or corrects a proposal, never starts from zero. The AI recommends based on what it researched (ask-vs-research rule), never on an empty default.
 
-- 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.
+> **Label language:** the literal option labels (`Compactar`, `Cerrar`, `Guardar plan`, …) are **canonical product strings** — present them **verbatim**; they are user-facing, authored in the product's user language (Spanish). All other user-facing output follows [`../SKILL.md`](../SKILL.md) § *Language policy*.
 
 ## 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:
+Resume **keys off the `CHECKPOINT`** of the run's session, not the existence of a separate file. Three cases when the flow's command runs over an input:
 
-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**.
+1. **In progress** (a `CHECKPOINT.md` exists in the session) → resume from the recorded progress (resolved gaps, Q&A, `attempts`, in-flight inline research).
+2. **No progress** (no CHECKPOINT and the input doc does **not** have the flow's prior-work mark) → start from zero reading the input doc.
+3. **Already converged / re-run on demand** (no open CHECKPOINT but the doc **already has** the mark) → **first-class operation**: while the flow stays in its stage, re-running the command over the same input **as many times as needed** is supported. `create_or_resume` finds the existing session — typically **closed** after convergence — by descriptor + `## Origin` and **reopens** it (see *Internal sessions*: detection via `aw sessions --state all` / `aw resume-summary --include-recent-closed`, reopening via `aw session-resume --code <NNN> --reopen`); incremental work reading the **doc itself**.
 
-> 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).
+> Each heir defines its **prior-work mark**: in the refine loops, the presence of `## Refinement decisions` + `## Q&A traceability` in the doc; in plan-exec, the plan-doc's `- [x]` checkboxes; quick has no doc (resume by CHECKPOINT only).
 
-> **`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.
+> **`Compactar`** (the `flow` control, across all 3 cases) → write `CHECKPOINT.md` in the session (in-flight progress, remaining gaps, Q&A, `attempts`) → trigger the harness **compaction** (Claude Code: `/compact`; see [`../harness/SKILL.md`](../harness/SKILL.md)) → resume by reading the 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.
+- **No material gaps** → **convergence gate** (read-only) = **`Success criteria` green** (*verification-first*). Whatever fails **comes back as a gap**; if it passes → the loop offers its closing action. The heirs are **instances** of the same gate: `spec-refine` = analyze gate, `plan-new` and `plan-refine` = plan coherence, `plan-exec` = final validation, `quick` = proportional spot validation.
+- `Cerrar` (the `flow` control, at any time) → `finalize`. **`finalize` always persists `CHECKPOINT.md`** (resumable) and, **only if something was deferred/follow-up**, writes `BACKLOG.md` (close reason + the deferred items); closes the session and reports. Progress survives even without a prior `Compactar`.
 
-## docs/ boundary — sin auto-export (regla dura)
+## docs/ boundary — no auto-export (hard rule)
 
-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).
+A loop writes into `docs/` **only** its own flow's doc (spec-refine: `docs/specs` · plan-new/plan-refine/plan-exec: `docs/plans` · quick: **none** — it never touches `docs/`). No loop **graduates/promotes artifacts** into `docs/`: everything else (migrations → `docs/scripts`, manuals → `docs/manuals`, diagrams → `docs/diagrams`, …) is done by the separate **`export-*`** skills, as an explicit later step. Artifacts stay in their sessions until then. If a task creates a tool/utility, the ambient skill `creating-tools` documents it in `docs/tools` (auto-discovered by its `description`; the workflow is **indifferent** — it does not bind it).
 
-## Políticas de loops que editan código → `CODE-POLICIES.md`
+## Code-editing loop policies → 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.
+The loops that **edit code** (`plan-exec-loop`, `quick-loop`) additionally run the policies in [`CODE-POLICIES.md`](CODE-POLICIES.md) — **safe git** (verified branch + proposed commits) · **DB scripts-only** · **closing review gate** (proportional in quick). They order it read from their `## Inherits` **together with this chassis**; the document loops (spec-refine, plan-new, plan-refine) do **not** load it — that is why it lives in a separate doc.
 
-## Resolución de referencias (regla global de layout)
+## Reference resolution (global layout rule) — and what the chassis is NOT
 
-Vale para **toda** referencia relativa de la doctrina — no se repite por link:
+Applies to **every** relative reference in the doctrine — never repeated per link:
 
-1. **Instalación normal** (árbol `w/`): la ruta relativa resuelve tal cual (`../CHASSIS.md`, `../../commands/spec-new.md`).
-2. **Instalación aplanada** (p. ej. Warp/Oz): los `.md` compartidos (`CHASSIS.md`, `CODE-POLICIES.md`) están **junto al `SKILL.md` del loop**; otro loop es una skill **hermana** `w-<loop>/` (ej. `../spec-refine-loop/SKILL.md` → `../w-spec-refine-loop/SKILL.md`).
-3. Referencia que no resuelva = **profundización opcional** — la doctrina de este motor es autocontenida.
+1. **Normal install** (the `w/` tree): the relative path resolves as-is (`../CHASSIS.md`, `../../commands/spec-new.md`).
+2. **Flattened install** (e.g. Warp/Oz): the shared `.md` files (`CHASSIS.md`, `CODE-POLICIES.md`) sit **next to the loop's `SKILL.md`**; another loop is a **sibling** skill `w-<loop>/` (e.g. `../spec-refine-loop/SKILL.md` → `../w-spec-refine-loop/SKILL.md`).
+3. A reference that does not resolve = **optional deep-dive** — this engine's doctrine is self-contained.
 
-El chasis **no es una skill** (sin frontmatter; no se invoca ni se bindea vía `.workflow/skills.toml`): entra al contexto solo porque un loop manda leerlo desde su `## Inherits`. No define flujo, deliverable ni gap taxonomy — eso es de cada heir.
+The chassis **is not a skill** (no frontmatter; never invoked nor bound via `.workflow/skills.toml`): it enters the context only because a loop orders it read from its `## Inherits`. It does not define flow, deliverable or gap taxonomy — that belongs to each heir.

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

@@ -1,34 +1,34 @@
-# CODE-POLICIES — políticas de loops que editan código
+# CODE-POLICIES — policies for code-editing loops
 
-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á.
+They apply to **`plan-exec-loop`** (per plan phase) and **`quick-loop`** (the single task; **proportional** gate): each orders this doc read from its `## Inherits`, **together with the chassis** ([`CHASSIS.md`](CHASSIS.md)). The document loops (spec-refine, plan-new, plan-refine) edit no code and do **not** load this doc — that is why it lives apart from the chassis. These policies materialize the **DB scripts-only** and **safe git** invariants — which also stay summarized **inline** (1-2 lines) in each code-editing loop's `SKILL.md`, because advisory hosts do not follow Reads; the full normative text lives here.
 
-## Git seguro — rama verificada + commits propuestos
+## Safe git — verified branch + proposed commits
 
-- **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.
+- **Before editing** a source's files: verify current branch = that source's expected branch (`aw check-branch --source <alias>`; see the `git` role). On mismatch → **pause and resolve with the human**; never `stash`/`reset --hard`/`checkout -- .`/`clean` without per-source confirmation.
+- **Proposed commits** (propose-then-execute, approve before): **after the closing review gate passes** (below), propose commits **per source** — in plan-exec at each phase close (or on `Cerrar`); in quick, **a single commit** at the end if there were code changes. Never `push`/`--amend`/`--no-verify`. Nothing reaches a proposed commit without review.
+- **Rejected commit**: the changes **stay in the working tree** (never reverted). Re-proposing / editing the message is allowed. Record in `CHECKPOINT` + `BACKLOG` that the phase/task remained **uncommitted** (resumable).
+- **Between-phase precondition** (plan-exec): `branch-check` validates branch *identity*, **not** working-tree *cleanliness*. Before starting the next phase, each source's working tree must be **clean** (committed) or explicitly **acknowledged** as "uncommitted changes from phase N" — so two phases never co-mingle in one commit.
 
-## BD solo-scripts — la IA nunca ejecuta DML/DDL
+## DB scripts-only — the AI never executes DML/DDL
 
-Distinción por **ejecución**, no por archivo (ver el esquema [`SCRIPTS.sql`](../artifacts/artifacts-core/SCRIPTS.sql)):
+Distinguished by **execution**, not by file (see the [`SCRIPTS.sql`](../artifacts/artifacts-core/SCRIPTS.sql) schema):
 
-- **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**.
+- **Read-only queries** (diagnosis/validation) → `SCRIPTS.sql` (session artifact); the AI **does** execute them read-only via MCP (`sql-mutation-guard`).
+- **DDL/DML migrations** (schema/data changes) → the AI **drafts them in `SCRIPTS.sql`** (session artifact) but **NEVER executes them**.
 
-> 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.
+> Mutating SQL **stays in the session**; it is never moved to `docs/`. Its promotion to `docs/scripts/` (forward + rollback) is done by a separate `export-*`, never by the loop.
 
-## Gate de revisión de cierre (convenciones, pre-commit)
+## Closing review gate (conventions, 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**:
+After validation (of the phase in plan-exec; of the task in quick, proportional) and **before proposing its commits** (also on an early `Cerrar`, before proposing the pending commits), the diff passes a **closing review gate**:
 
-- **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".
+- **Independent re-read** of the diff (subagent or clean re-read — the engine's *independent verification*: it does not assume the implementation is correct; *only command output counts*).
+- **Apply the installed ambient conventions** relevant to the touched stack (code/stack standards, security, diff review, the workspace's own families) — the host **auto-discovers them by `description`**. The workflow **names and binds no** concrete skill: **it creates the moment; the installed skills fill it** (that is why review is **not a role** — see [`../roles/README.md`](../roles/README.md)). With no convention skills installed → minimal generic checklist: SOLID/early-return, clear names, DRY, no silenced errors, no secrets/PII, parametrized SQL, no dead code, + the plan's `Validations` (if any).
+- **Findings**: **fix** them in the working tree and **re-run validation** (the gate does not replace the tests: it re-verifies after fixing), or **defer them justified** (→ the plan's `Open questions` + `BACKLOG`; in quick, `BACKLOG`); the non-obvious → `DECISION`. Gate integrity (see [`CHASSIS.md`](CHASSIS.md) § *Verification-first*): never weaken a check or lower a convention to pass.
+- **Artifact-first + verification-first**: `CHECKPOINT.Next = "review <phase/task>"` before the pass; `SESSION.Success criteria` includes from the start "the diff passed the review gate before its commits".
 
-Recién con el gate en verde se proponen los commits.
+Only with the gate green are the commits proposed.
 
-## Localización
+## Location
 
-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**.
+Same as the chassis: code-editing loops reference it as `../CODE-POLICIES.md` (normal install, `w/loops/` tree); in **flattened** installs it may sit as `CODE-POLICIES.md` **next to the loop's `SKILL.md`** (chassis § *Reference resolution*).

package/skills/w/loops/README.md

@@ -1,73 +1,74 @@
 # w/loops — Loop map (Layer 2)
 
-> Los **loops** son las piezas que la **IA corre enteras** para producir entregables y orquestar el trabajo. Los arranca un comando `/w:…` (Capa 1) y, a partir de ahí, **los conduce la IA**, no el usuario.
+> **Loops** are the pieces the **AI runs whole** to produce deliverables and orchestrate the work. A `/w:…` command (Layer 1) starts them and, from there, **the AI drives them**, not the user.
 >
-> Hermanos: `../commands/` (Capa 1, comandos `/w:…`) · `.workflow/sessions/` (Capa 3, sessions + artefactos internos) · la familia `export-*` (única vía artefacto→`docs/`) · las **capacidades** componibles (roles bindeados en `.workflow/skills.toml`).
+> Siblings: `../commands/` (Layer 1, `/w:…` commands) · `.workflow/sessions/` (Layer 3, sessions + internal artifacts) · the `export-*` family (the only artifact→`docs/` path) · the composable **capabilities** (roles bound in `.workflow/skills.toml`).
 
 ---
 
 ## 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** como skill suelta (no se registra como tal; en Claude Code, la invocación por nombre es el tool `Skill` — su binding, no un universal): es el cuerpo de su comando `/w:…`, que lo **carga leyendo `<loop>/SKILL.md`** y lo ejecuta inline.
+A loop is a **skill** that teaches the AI *how to iterate* until it produces a deliverable. **It is not invocable by name** as a standalone skill (it is not registered as such; in Claude Code, by-name invocation is the `Skill` tool — its binding, not a universal): it is the body of its `/w:…` command, which **loads it by reading `<loop>/SKILL.md`** and executes it inline.
 
-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á.
+The 5 loops run the same **common engine**, whose canon lives in [`CHASSIS.md`](CHASSIS.md): persistent objective + verification-first, gap-driven convergent, single session per run with inline research, structured-choice + `flow` control (`Compactar`/`Cerrar`, always present), compact/resume, artifacts as a live log, convergence gate and the `docs/` boundary. Each loop is an **heir**: its `## Inherits` orders the chassis read before its deltas — nothing of the engine is repeated here.
 
 ## Loops and their flow
 
 | Loop (`name:`) | Flow | Started by | Reads | Writes |
 |---|---|---|---|---|
-| [`spec-refine-loop`](spec-refine-loop/SKILL.md) | SPEC | `/w:spec-refine` | `docs/specs/NNN-spec*.md` (el spec mismo) | `docs/specs/NNN-spec-<slug>.md` (in place) |
+| [`spec-refine-loop`](spec-refine-loop/SKILL.md) | SPEC | `/w:spec-refine` | `docs/specs/NNN-spec*.md` (the spec itself) | `docs/specs/NNN-spec-<slug>.md` (in place) |
 | [`plan-new-loop`](plan-new-loop/SKILL.md) | PLAN | `/w:plan-new` | `docs/specs/NNN-spec-*.md` | `docs/plans/PPP-plan-<slug>.md` |
-| [`plan-refine-loop`](plan-refine-loop/SKILL.md) | PLAN | `/w:plan-refine` *(aux, opcional)* | `docs/plans/PPP-plan-*.md` (el plan mismo) | `docs/plans/PPP-plan-<slug>.md` (in place) |
-| [`plan-exec-loop`](plan-exec-loop/SKILL.md) | PLAN | `/w:plan-exec` | `docs/plans/PPP-plan-*.md` | `docs/plans/PPP-plan-<slug>.md` (update); resto vía `export-*` |
-| [`quick-loop`](quick-loop/SKILL.md) | QUICK | `/w:quick` | — (prompt) | edita código + session ligera; **no** `docs/` |
+| [`plan-refine-loop`](plan-refine-loop/SKILL.md) | PLAN | `/w:plan-refine` *(aux, optional)* | `docs/plans/PPP-plan-*.md` (the plan itself) | `docs/plans/PPP-plan-<slug>.md` (in place) |
+| [`plan-exec-loop`](plan-exec-loop/SKILL.md) | PLAN | `/w:plan-exec` | `docs/plans/PPP-plan-*.md` | `docs/plans/PPP-plan-<slug>.md` (update); the rest via `export-*` |
+| [`quick-loop`](quick-loop/SKILL.md) | QUICK | `/w:quick` | — (prompt) | edits code + light session; **no** `docs/` |
 
-> `/w:spec-new` no tiene loop (es single-pass). Por eso hay **6 comandos / 5 loops**.
+> `/w:spec-new` has no loop (single-pass). Hence **6 commands / 5 loops**.
 
-### `docs/` boundary (regla dura)
+### `docs/` boundary (hard rule)
 
-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*.
+Every loop writes **only** its own flow's doc (SPEC→`docs/specs` · PLAN→`docs/plans` · QUICK→none) and **never** graduates other artifacts to `docs/` — that promotion belongs to the separate, explicit `export-*` skills. Canon: [`CHASSIS.md`](CHASSIS.md) § *docs/ boundary*.
 
 ## Schema of each loop file
 
 | Field | Description |
 |---|---|
-| `## Flow` | A qué flujo pertenece (SPEC · PLAN · QUICK) |
-| `## Layer` | Siempre 2 (la IA lo corre entero) |
-| `## Started by` | Comando `/w:…` que lo arranca (reanudable) |
-| `## Reads` | Documento(s) de entrada |
-| `## Writes` | Documento(s) de salida (`generate` / `read-update`) |
-| `## Internal sessions` | Sessions que crea y sus artefactos |
-| `## Sequence` | Pseudocódigo del loop |
-| `## Convergence / exit` | Cuándo para |
+| `## Flow` | Which flow it belongs to (SPEC · PLAN · QUICK) |
+| `## Layer` | Always 2 (the AI runs it whole) |
+| `## Started by` | The `/w:…` command that starts it (resumable) |
+| `## Reads` | Input document(s) |
+| `## Writes` | Output document(s) (`generate` / `read-update`) |
+| `## Internal sessions` | Sessions it creates and their artifacts |
+| `## Sequence` | The loop's pseudocode |
+| `## Convergence / exit` | When it stops |
 
-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.
+The **5 loops** are heirs: they use `## Inherits` (a one-line reference to [`CHASSIS.md`](CHASSIS.md), read **always before** the deltas) + their own sections. The engine's sections live in the chassis, in no loop.
 
 ## Chassis / heirs
 
-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`.
+The **engine lives in [`CHASSIS.md`](CHASSIS.md)** (a referenced doc, not a skill); the 5 loops — including `spec-refine-loop` — are **heirs** of that engine. The canonical heirs list and their deltas live in the chassis itself (§ *Heirs*). The chassis is **not a bindable capability**: it is the loop engine; what is pluggable are the **capabilities** a loop composes (e.g. `ui-design`, `sql`, `git`), resolved via `.workflow/skills.toml`.
 
 ## Composed capabilities (roles)
 
-Los loops componen **capacidades por su rol**, no skills concretas; la skill que cumple el rol la resuelve `.workflow/skills.toml` (`built-in default → ~/.workflow/skills.toml → .workflow/skills.toml`).
+Loops compose **capabilities by role**, never concrete skills; the skill fulfilling the role is resolved by `.workflow/skills.toml` (`built-in default → ~/.workflow/skills.toml → .workflow/skills.toml`).
 
 | Role | Default built-in | Composed by |
 |---|---|---|
-| `ui-design` | `ui-spec` | `spec-refine-loop` (cuando hay UI) · `plan-new-loop` / `plan-refine-loop` (design SPECs `NNN-SPEC-<SLUG>.md`) |
+| `ui-design` | `ui-spec` | `spec-refine-loop` (when there is UI) · `plan-new-loop` / `plan-refine-loop` (design SPECs `NNN-SPEC-<SLUG>.md`) |
 | `sql` | `sql` | research · `plan-exec-loop` · `quick-loop` |
 | `git` | `git` | `plan-exec-loop` · `quick-loop` |
-| `research` | `research` | todos los loops (research inline) |
-| `overview` | `workflow` | cualquiera (orientación) |
+| `research` | `research` | every loop (inline research) |
+| `overview` | `workflow` | anyone (orientation) |
 
-> **Convenciones ambientes (no roles):** estándares de código/testing/redacción y `creating-tools` son skills standalone que el host auto-descubre por su `description` — el workflow no las bindea ni depende de ellas. Doctrina completa: [../roles/README.md](../roles/README.md).
+> **Ambient conventions (not roles):** code/testing/writing standards and `creating-tools` are standalone skills the host auto-discovers by `description` — the workflow neither binds nor depends on them. Full doctrine: [../roles/README.md](../roles/README.md).
 
-`off` en config → capacidad desactivada: el loop sigue sin ella; si era necesaria, lo dice o pregunta al humano.
+`off` in config → capability disabled: the loop continues without it; if it was needed, it says so or asks the human.
 
 ## Index
 
-- [`CHASSIS.md`](CHASSIS.md) — el motor común de los 5 loops (doc referenciado; no es una skill)
+- [`CHASSIS.md`](CHASSIS.md) — the common engine of the 5 loops (referenced doc; not a skill)
+- [`CODE-POLICIES.md`](CODE-POLICIES.md) — the code-editing loop policies (loaded only by plan-exec and quick)
 - [`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-refine-loop/SKILL.md`](plan-refine-loop/SKILL.md) — aux, optional (refines the plan in place)
 - [`plan-exec-loop/SKILL.md`](plan-exec-loop/SKILL.md)
 - [`quick-loop/SKILL.md`](quick-loop/SKILL.md)