@tacuchi/agent-workflow-cli 15.1.0 → 16.0.0

package/skills/w/harness/SKILL.md

@@ -1,88 +1,89 @@
 ---
 name: harness
 description: >-
-  Harness-agnostic capability layer for agent-workflow. Read-and-follow doc (no es
-  invocable por nombre): define el contrato que mantiene a la herramienta agnóstica al
-  arnés (Claude Code, Codex, Gemini/Antigravity, OpenCode, Crush, Warp/Oz, genérico) sin renunciar a las
-  capacidades ricas de cada uno. Cataloga las capacidades de las que depende el
-  workflow, las liga al mecanismo concreto de cada arnés (binding matrix), y fija los
-  dos principios (capacidad-no-tool · progressive-enhancement). Referenciado desde
-  SKILL.md (overview) y los loops cuando nombran structured-choice / compaction.
+  Harness-agnostic capability layer for agent-workflow. Read-and-follow doc (not
+  invocable by name): defines the contract that keeps the tool harness-agnostic
+  (Claude Code, Codex, Gemini/Antigravity, OpenCode, Crush, Warp/Oz, generic) without
+  giving up each harness's rich capabilities. Catalogs the capabilities the workflow
+  depends on, binds each to the concrete mechanism of every harness (binding matrix),
+  and fixes the two principles (capability-not-tool · progressive-enhancement).
+  Referenced from SKILL.md (overview) and the loops when they name structured-choice /
+  compaction.
 ---
 
-# harness — capa de capacidades agnóstica al arnés (cross-cutting)
+# harness — harness-agnostic capability layer (cross-cutting)
 
-Doc de **lectura y seguimiento** (no se invoca por nombre). Aquí vive el contrato que mantiene a agent-workflow **agnóstico al arnés** (Claude Code, Codex, opencode, Gemini CLI, …) sin renunciar a las capacidades ricas de cada uno. Referenciado desde `../SKILL.md` (overview) y desde los loops cuando nombran una capacidad (`structured-choice`, `compaction`, …).
+**Read-and-follow** doc (never invoked by name). Here lives the contract that keeps agent-workflow **harness-agnostic** (Claude Code, Codex, opencode, Gemini CLI, …) without giving up each harness's rich capabilities. Referenced from `../SKILL.md` (overview) and from the loops when they name a capability (`structured-choice`, `compaction`, …).
 
-## El problema
+## The problem
 
-La doctrina (comandos + loops + artefactos) describe **qué** hace la IA, no **con qué tool** de un arnés concreto. El vocabulario natural arrastra mecanismos específicos de Claude Code —`AskUserQuestion`, `/compact`, `$ARGUMENTS`, `Task`/`Agent`— como si fueran universales. Este documento los abstrae: la doctrina referencia **capacidades**; aquí se mapea cada capacidad al **mecanismo concreto** de cada arnés.
+The doctrine (commands + loops + artifacts) describes **what** the AI does, never **with which tool** of a concrete harness. Natural vocabulary drags in Claude-Code-specific mechanisms — `AskUserQuestion`, `/compact`, `$ARGUMENTS`, `Task`/`Agent` — as if they were universal. This document abstracts them: the doctrine references **capabilities**; here each capability maps to each harness's **concrete mechanism**.
 
-## Dos principios
+## Two principles
 
-1. **Capacidad, no tool.** Los loops/comandos nombran una **capacidad** abstracta (ej. *structured-choice*, *compaction*). Una sola tabla —esta— la liga al mecanismo de cada arnés. Cambiar de arnés = cambiar de columna, no de doctrina.
-2. **Progressive enhancement.** Usá el mecanismo **más rico** que ofrezca el arnés; **degradá** a un fallback universal cuando no exista. Así se cumple a la vez "agnóstica al arnés" **y** "aprovechar las capacidades de cada uno".
+1. **Capability, not tool.** Loops/commands name an abstract **capability** (e.g. *structured-choice*, *compaction*). A single table — this one — binds it to each harness's mechanism. Switching harness = switching column, never doctrine.
+2. **Progressive enhancement.** Use the **richest** mechanism the harness offers; **degrade** to a universal fallback when it does not exist. That satisfies both "harness-agnostic" **and** "leverage each harness".
 
-> **Simetría con la cascada de skills (`.workflow/skills.toml`):** esa categoría liga **roles → skills** por config; esta liga **capacidades → mecanismos del arnés** por detección. Mismo patrón (binding + default), distinto eje: una es *qué saber compone el loop*, la otra es *con qué primitivas del host se ejecuta*.
+> **Symmetry with the skills cascade (`.workflow/skills.toml`):** that category binds **roles → skills** by config; this one binds **capabilities → harness mechanisms** by detection. Same pattern (binding + default), different axis: one is *what knowledge the loop composes*, the other is *which host primitives execute it*.
 
 ## Capability catalog
 
-Las capacidades de las que depende el harness, con su fallback universal (lo que se usa si el arnés no ofrece algo mejor):
+The capabilities the harness layer depends on, with their universal fallback (what is used when the harness offers nothing better):
 
-| Capability | Qué necesita el workflow | Fallback universal (mínimo común) |
+| Capability | What the workflow needs | Universal fallback (lowest common) |
 |---|---|---|
-| **command-invocation** | el usuario dispara un flujo por nombre (`spec-new`, `plan-exec`, …) | el usuario escribe "corré el procedimiento `<cmd>`" y la IA lee su doc |
-| **procedure-loading** | cargar la doctrina de un loop/comando | la IA **lee el `.md`** del loop y lo sigue (read-and-follow) |
-| **structured-choice** | preguntar al humano ≤3 preguntas de contenido **+ siempre** un control `flow` (`Compactar`/`Cerrar`) por un canal lateral | pregunta en **markdown numerado** en el chat; el control `flow` se ofrece como una opción más |
-| **compaction** | encoger el contexto sin perder el hilo | escribir `CHECKPOINT` y pedir al usuario reiniciar el contexto y reanudar (resume keya off `CHECKPOINT`) |
-| **subagent-dispatch** | *(opcional)* paralelizar breadth de research | research **inline secuencial** en la misma session (es el default igual) |
-| **persistent-context** | bloque `WORKSPACE` + convenciones siempre presentes | archivo de contexto del repo (**`AGENTS.md`** estándar; `CLAUDE.md` en Claude Code) |
-| **external-data** | lecturas read-only de BD u otras fuentes para research/validación | **MCP** (ampliamente soportado); si no hay, el gap se degrada a pregunta-al-humano |
-| **dry-run / preview** | previsualizar lo que haría un comando sin escribir | el comando **describe** el cambio en vez de aplicarlo (ej. `spec-new` lista el borrador sin crear el archivo) |
+| **command-invocation** | the user triggers a flow by name (`spec-new`, `plan-exec`, …) | the user writes "run the `<cmd>` procedure" and the AI reads its doc |
+| **procedure-loading** | load a loop's/command's doctrine | the AI **reads the `.md`** of the loop and follows it (read-and-follow) |
+| **structured-choice** | ask the human ≤3 content questions **+ always** a `flow` control (`Compactar`/`Cerrar`) through a side channel | a **numbered markdown** question in chat; the `flow` control is offered as one more option |
+| **compaction** | shrink the context without losing the thread | write `CHECKPOINT` and ask the user to restart the context and resume (resume keys off `CHECKPOINT`) |
+| **subagent-dispatch** | *(optional)* parallelize research breadth | **inline sequential** research in the same session (the default anyway) |
+| **persistent-context** | the `WORKSPACE` block + conventions always present | the repo's context file (standard **`AGENTS.md`**; `CLAUDE.md` on Claude Code) |
+| **external-data** | read-only DB reads or other sources for research/validation | **MCP** (widely supported); without it, the gap degrades to a human question |
+| **dry-run / preview** | preview what a command would do without writing | the command **describes** the change instead of applying it (e.g. `spec-new` lists the draft without creating the file) |
 
-> **Las capacidades `must` para el ciclo de un loop son solo dos**: `structured-choice` y `compaction`. Ambas degradan a un fallback puramente textual → **cualquier** arnés con chat + sistema de archivos corre el modelo completo. El resto (subagents, MCP, slash commands, skills nativas) es *enhancement*.
+> **Only two capabilities are `must` for a loop's cycle**: `structured-choice` and `compaction`. Both degrade to a purely textual fallback → **any** harness with chat + a filesystem runs the full model. The rest (subagents, MCP, slash commands, native skills) is *enhancement*.
 
 ## Harness binding matrix
 
-Mecanismo concreto por arnés (**jul-2026**, verificado contra docs oficiales; `~` parcial). Antigravity CLI reusa las superficies de Gemini (`~/.gemini/`); Oz reusa las de Warp (comparte columna **Warp / Oz**, con MCP por flag — ver la nota al pie de la matriz).
+Concrete mechanism per harness (**Jul-2026**, verified against official docs; `~` partial). Antigravity CLI reuses Gemini's surfaces (`~/.gemini/`); Oz reuses Warp's (they share the **Warp / Oz** column, with MCP via flag — see the note under the matrix).
 
-| Capability | Claude Code | Codex | Gemini / Antigravity | OpenCode | Crush | Warp / Oz | Genérico |
+| Capability | Claude Code | Codex | Gemini / Antigravity | OpenCode | Crush | Warp / Oz | Generic |
 |---|---|---|---|---|---|---|---|
-| command-invocation | `.claude/commands/` (slash) | slash + skills | `.gemini/commands/*.toml` | `.opencode/command/` | skills user-invocable | Workflows (Drive) | texto |
+| command-invocation | `.claude/commands/` (slash) | slash + skills | `.gemini/commands/*.toml` | `.opencode/command/` | user-invocable skills | Workflows (Drive) | text |
 | procedure-loading (skills) | `SKILL.md` `.claude/skills` | `SKILL.md` `.agents/skills` | `SKILL.md` (agentskills) | `SKILL.md` `.opencode`+`.claude`+`.agents` | `SKILL.md` `.agents`+`.crush`+`.claude` | `SKILL.md` `.agents`+`.warp`+`.claude` | read-and-follow `.md` |
-| structured-choice | `AskUserQuestion` (**solo main-agent**) | — | — | — | — | — | markdown numerado |
+| structured-choice | `AskUserQuestion` (**main-agent only**) | — | — | — | — | — | numbered markdown |
 | compaction | `/compact` | Pre/PostCompact hooks | ~ | `session.compacted` | ~ | ~ | CHECKPOINT + resume |
-| subagent-dispatch | `Task` (paralelo) | `SubagentStart` / agents | agents (`.gemini/agents`) | `.opencode/agent/*.md` | ~ | ~ (cloud agents) | inline |
-| persistent-context | `CLAUDE.md` (**no** lee AGENTS.md → symlink) | `AGENTS.md` | `GEMINI.md` + `AGENTS.md` | `AGENTS.md` | `CRUSH.md` + `AGENTS.md` | `AGENTS.md` (auto) | `AGENTS.md` |
-| external-data (MCP) | `.mcp.json` | `.codex/config.toml` `[mcp_servers]` | `settings.json` `mcpServers` | `opencode.json` `mcp` | `crush.json` `mcp` | `.warp/.mcp.json` (+autodescubre `.mcp.json`) · Oz: flag `--mcp` | — |
-| **enforcement (deny tool)** | `PreToolUse` → `permissionDecision:deny` / exit 2 | `PreToolUse` (**≈mismo protocolo**) | `BeforeTool` → `decision:deny` / exit 2 | plugin `tool.execute.before` (`throw`) | `allowed_tools` (+ hooks preliminares) | allow/deny lists (**grueso**) | doctrina (git-safe #5) |
-| plugin / dist | `.claude-plugin` + marketplace | `.codex-plugin` + `/plugins` marketplace | Extension `gemini-extension.json` | plugin JS/TS (npm) | MCP + skills + config | Warp Drive | — |
+| subagent-dispatch | `Task` (parallel) | `SubagentStart` / agents | agents (`.gemini/agents`) | `.opencode/agent/*.md` | ~ | ~ (cloud agents) | inline |
+| persistent-context | `CLAUDE.md` (does **not** read AGENTS.md → symlink) | `AGENTS.md` | `GEMINI.md` + `AGENTS.md` | `AGENTS.md` | `CRUSH.md` + `AGENTS.md` | `AGENTS.md` (auto) | `AGENTS.md` |
+| external-data (MCP) | `.mcp.json` | `.codex/config.toml` `[mcp_servers]` | `settings.json` `mcpServers` | `opencode.json` `mcp` | `crush.json` `mcp` | `.warp/.mcp.json` (+auto-discovers `.mcp.json`) · Oz: `--mcp` flag | — |
+| **enforcement (deny tool)** | `PreToolUse` → `permissionDecision:deny` / exit 2 | `PreToolUse` (**≈same protocol**) | `BeforeTool` → `decision:deny` / exit 2 | plugin `tool.execute.before` (`throw`) | `allowed_tools` (+ preliminary hooks) | allow/deny lists (**coarse**) | doctrine (git-safe #5) |
+| plugin / dist | `.claude-plugin` + marketplace | `.codex-plugin` + `/plugins` marketplace | Extension `gemini-extension.json` | JS/TS plugin (npm) | MCP + skills + config | Warp Drive | — |
 
-> **Notas (investigación de campo jul-2026):** las **skills `SKILL.md`** son la unidad portable **universal** — **los seis** arneses las soportan (Codex las agregó Dic-2025; **`.agents/skills` es el ancla cross-host**, leída por Codex/OpenCode/Crush/Warp). La **elección estructurada** (`AskUserQuestion`) sigue siendo **solo Claude Code / main-agent** → en el resto `structured-choice` degrada a markdown numerado. La **capa de enforcement** (fila nueva) ya **NO es exclusiva de Claude**: Codex + Gemini usan un protocolo casi idéntico (`permissionDecision:deny` / exit 2) y OpenCode bloquea vía `throw` en un plugin JS; Crush/Warp solo ofrecen allow/deny **grueso** (sin lógica custom por comando) → en ellos las convenciones quedan **advisory** + listas allow/deny. El **plan mode** enforced no se confía para safety; el git-safe (invariante #5) es propio. **MCP** es universal (cada host su archivo/clave). El **piso garantizado** (última columna) corre el modelo completo.
+> **Notes (field research Jul-2026):** **`SKILL.md` skills** are the **universal** portable unit — **all six** harnesses support them (Codex added them Dec-2025; **`.agents/skills` is the cross-host anchor**, read by Codex/OpenCode/Crush/Warp). **Structured choice** (`AskUserQuestion`) remains **Claude Code / main-agent only** → elsewhere `structured-choice` degrades to numbered markdown. The **enforcement layer** (new row) is **NO longer Claude-exclusive**: Codex + Gemini use a near-identical protocol (`permissionDecision:deny` / exit 2) and OpenCode blocks via `throw` in a JS plugin; Crush/Warp only offer **coarse** allow/deny (no custom per-command logic) → there, conventions stay **advisory** + allow/deny lists. Enforced **plan mode** is never trusted for safety; git-safe (invariant #5) is our own. **MCP** is universal (each host its file/key). The **guaranteed floor** (last column) runs the full model.
 
-> **Oz (hermano cloud de Warp).** `oz agent run` es un orquestador de agentes en la nube que **reusa las superficies de Warp**: mismas skills (`.agents/skills`, aplanadas a top-level como Warp) y `AGENTS.md`, con `structured-choice` igual degradada a markdown numerado. Difiere en tres puntos: **detección** por `OZ_RUN_ID` (prioritaria sobre Warp si coexisten los marcadores); **MCP sin archivo de config** — emite el JSON por el flag `--mcp` de `oz agent run` (o la env `OZ_MCP_CONFIG`), no escribe `.warp/.mcp.json`; y **sin plugin ni hooks** (enforcement advisory, como Warp). Por eso comparte la columna **Warp / Oz** con esa salvedad de MCP.
+> **Oz (Warp's cloud sibling).** `oz agent run` is a cloud agent orchestrator that **reuses Warp's surfaces**: same skills (`.agents/skills`, flattened to top level like Warp) and `AGENTS.md`, with `structured-choice` equally degraded to numbered markdown. It differs in three points: **detection** via `OZ_RUN_ID` (takes priority over Warp when both markers coexist); **MCP without a config file** — the JSON is passed via the `--mcp` flag of `oz agent run` (or the `OZ_MCP_CONFIG` env), it never writes `.warp/.mcp.json`; and **no plugin or hooks** (advisory enforcement, like Warp). Hence it shares the **Warp / Oz** column with that MCP caveat.
 
 ## Leverage installed skills
 
-"Aprovechar las skills que el arnés tenga instaladas" se resuelve por el **mismo binding** de `.workflow/skills.toml`: un rol puede apuntar a una skill **instalada en el host** (de tercero, vía skills.sh) en vez del built-in. Regla:
+"Leverage whatever skills the harness has installed" resolves through the **same** `.workflow/skills.toml` binding: a role can point at a skill **installed on the host** (third-party, via skills.sh) instead of the built-in. Rule:
 
-- Si el host tiene una skill **mejor** para un rol (ej. un generador de diagramas superior para `diagrams`, o un investigador especializado para `research`), se la **bindea** en `.workflow/skills.toml` y el loop la compone sin cambios.
-- El built-in default es el **piso**, no el techo: garantiza que el rol funcione en cualquier host; el binding lo **enriquece** donde el host puede más.
+- If the host has a **better** skill for a role (e.g. a superior diagram generator for `diagrams`, or a specialized investigator for `research`), **bind it** in `.workflow/skills.toml` and the loop composes it unchanged.
+- The built-in default is the **floor**, not the ceiling: it guarantees the role works on any host; the binding **enriches** it where the host can do more.
 
-## Convención para el resto del corpus
+## Convention for the rest of the corpus
 
-- Los loops/comandos referencian la **capacidad** por nombre (ej. "*structured-choice* (ver `harness/SKILL.md`)"), **no** el tool concreto.
-- El nombre histórico `AskUserQuestion` se conserva **solo** como el binding Claude-Code de `structured-choice` (esta tabla), no como vocabulario de la doctrina.
-- El control de ciclo de vida `flow` (`Compactar`/`Cerrar`) es parte de la capacidad `structured-choice`, no de un tool: en arneses sin elección estructurada se ofrece como una opción textual más.
+- Loops/commands reference the **capability** by name (e.g. "*structured-choice* (see `harness/SKILL.md`)"), **never** the concrete tool.
+- The historical name `AskUserQuestion` survives **only** as the Claude-Code binding of `structured-choice` (this table), never as doctrine vocabulary.
+- The `flow` lifecycle control (`Compactar`/`Cerrar`) belongs to the `structured-choice` capability, not to a tool: on harnesses without structured choice it is offered as one more textual option.
 
 ## Distribution (install-time)
 
-Patrón probado (Spec Kit, 30+ agentes): **una fuente canónica** + generar/symlinkear a los dirs por-arnés en la instalación (`.claude/`, `.codex/`, `.gemini/`, …). agent-workflow ya lo hace vía `aw self install-skill`. Convención recomendada: **`AGENTS.md` canónico + `CLAUDE.md` symlink** (Claude Code no lee `AGENTS.md` nativo; el resto sí).
+Proven pattern (Spec Kit, 30+ agents): **one canonical source** + generate/symlink into the per-harness dirs at install (`.claude/`, `.codex/`, `.gemini/`, …). agent-workflow already does this via `aw self install-skill`. Recommended convention: **canonical `AGENTS.md` + `CLAUDE.md` symlink** (Claude Code does not read `AGENTS.md` natively; the rest do).
 
 ## Command packaging (harness-specific)
 
-El **contrato** de cada comando (Flow, Trigger, Input, Mode, …) es agnóstico. El **archivo** que el arnés ejecuta envuelve ese contrato en su formato nativo: Claude Code = slash-command con frontmatter (`description`, `argument-hint`, `allowed-tools`) + cuerpo que invoca la skill o el `aw` CLI; Codex = slash-command o skill; Gemini/Antigravity = `.gemini/commands/*.toml`; OpenCode = `.opencode/command/*.md`; Crush/Warp = la **skill misma** invocable. El **fallback universal** es *skill-as-command*: como los seis arneses cargan skills, la doctrina siempre corre aunque el host no tenga comandos nativos. El contrato no cambia; el envoltorio sí (otra columna).
+Each command's **contract** (Flow, Trigger, Input, Mode, …) is agnostic. The **file** the harness executes wraps that contract in its native format: Claude Code = slash command with frontmatter (`description`, `argument-hint`, `allowed-tools`) + a body that invokes the skill or the `aw` CLI; Codex = slash command or skill; Gemini/Antigravity = `.gemini/commands/*.toml`; OpenCode = `.opencode/command/*.md`; Crush/Warp = the invocable **skill itself**. The **universal fallback** is *skill-as-command*: since all six harnesses load skills, the doctrine always runs even without native commands. The contract never changes; the wrapper does (another column).
 
 ## Status
 
-Modelo de capacidades + matriz de binding **definidos** y **validados** con investigación de campo (**jul-2026**, contra docs oficiales). Cobertura **6 arneses reales** (familias; Warp/Oz cuenta como una, igual que Gemini/Antigravity): Claude Code, Codex, Gemini/Antigravity, OpenCode, Crush, Warp/Oz — todos soportan `SKILL.md` (ancla `.agents/skills`) + MCP + `AGENTS.md`; enforcement determinista en Claude/Codex/Gemini/OpenCode, advisory + allow/deny grueso en Crush/Warp/Oz. El CLI (`aw`) implementa el registro (`domain/harnesses.ts`), los writers MCP por-host, `detect-hosts` e `install-skill --target <host>`. El piso universal (`AGENTS.md` + texto + archivos + skills) corre el modelo completo hoy.
+Capability model + binding matrix **defined** and **validated** with field research (**Jul-2026**, against official docs). Coverage: **6 real harnesses** (families; Warp/Oz counts as one, like Gemini/Antigravity): Claude Code, Codex, Gemini/Antigravity, OpenCode, Crush, Warp/Oz — all support `SKILL.md` (anchor `.agents/skills`) + MCP + `AGENTS.md`; deterministic enforcement on Claude/Codex/Gemini/OpenCode, advisory + coarse allow/deny on Crush/Warp/Oz. The CLI (`aw`) implements the registry (`domain/harnesses.ts`), the per-host MCP writers, `detect-hosts` and `install-skill --target <host>`. The universal floor (`AGENTS.md` + text + files + skills) runs the full model today.

package/skills/w/loops/CHASSIS.md

@@ -1,159 +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.
 
-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.
+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`.)*
 
-| 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**) |
+> 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).
 
-> 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.
+> **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 |
+
+- **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**.
 
-**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.
+> 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.
 
-> 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.
+**Gate integrity (anti-gaming + independent verification).** The gate only counts if it is not gamed to pass. The loop does **not**:
 
-**Integridad del gate (anti-gaming + verificación independiente).** El gate solo vale si no se hace trampa para pasarlo. El loop **no**:
+- 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).
 
-- 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).
+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*.
 
-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 — the artifact-first cycle
 
-## Artifacts as a live log — ciclo artifact-first
+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:
 
-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. **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).
 
-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).
+> 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**.
 
-> 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**.
+## Gap-driven convergent engine
 
-## Motor gap-driven convergente
+The common cycle — each heir instantiates it in its `## Sequence` with its own gap taxonomy:
 
-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.
+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`).
+
+## Ask-vs-research rule (the discriminator)
 
-Para cada gap, una sola pregunta decide el resolutor:
+For every gap, a single question picks the resolver:
 
-> *"¿Puedo responder esto leyendo el repo/datos?"* → **research** (autónomo).
-> *"¿Depende de lo que el usuario quiere?"* → **preguntar al humano** (structured-choice).
+> *"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)
 
-*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**.
+**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**).
 
-- 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.
+- 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.
+
+> **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 — no auto-export (hard rule)
+
+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).
 
-## docs/ boundary — sin auto-export (regla dura)
+## Code-editing loop policies → CODE-POLICIES.md
 
-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).
+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.
 
-## Políticas de loops que editan código → `CODE-POLICIES.md`
+## Reference resolution (global layout rule) — and what the chassis is NOT
 
-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.
+Applies to **every** relative reference in the doctrine — never repeated per link:
 
-## Qué NO es el chasis
+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.
 
-- **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.
+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.