@tacuchi/agent-workflow-cli 15.1.0 → 16.0.0

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)

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

@@ -1,137 +1,134 @@
 ---
 name: plan-exec-loop
 description: >-
-  Ejecuta un plan de implementación (docs/plans/PPP-plan-<slug>.md) como
-  living doc: lo lee y actualiza fase a fase mientras edita el código real,
-  gestiona BD y git. Heir del chasis común de los loops (loops/CHASSIS.md —
-  motor gap-driven, research inline, structured-choice, artefactos como log
-  vivo, y las políticas de loops que editan código); sus deltas viven en el
-  cuerpo: session única reanudable, git seguro (rama verificada,
-  commits propuestos por fuente, nunca push/--amend/--no-verify), BD solo-
-  scripts (la IA nunca ejecuta DML/DDL), validación por fase y final, gate de
-  revisión de cierre pre-commit, y sin auto-export (solo escribe docs/plans).
-  Compone git y sql. Lo arranca /w:plan-exec. Invocar para implementar un plan
-  ya generado.
+  Executes an implementation plan (docs/plans/PPP-plan-<slug>.md) as a living
+  doc: reads and updates it phase by phase while editing the real code and
+  managing DB and git. Heir of the chassis (loops/CHASSIS.md +
+  CODE-POLICIES.md). Deltas: single resumable session, safe git (verified
+  branch, per-source proposed commits, never push/--amend/--no-verify), DB
+  scripts-only (never executes DML/DDL), per-phase and final validation,
+  pre-commit closing review gate, no auto-export. Composes git and sql.
+  Started by /w:plan-exec. Invoke to implement an already generated plan.
 ---
 
 # plan-exec-loop
 
-> **Heir** del chasis común — aquí los **deltas de ejecución**: el trabajo real (código, BD, git). El motor vive en el chasis y las *Políticas de loops que editan código* en `CODE-POLICIES.md` — no se repiten.
+> **Heir** of the common chassis — the **execution deltas** live here: the real work (code, DB, git). The engine lives in the chassis and the *code-editing loop policies* in `CODE-POLICIES.md` — never repeated.
 
 ## Flow
 PLAN
 
 ## Layer
-2 — la IA lo corre entero.
+2 — the AI runs it end to end.
 
 ## Started by
-`/w:plan-exec` — **reanudable** (mismo mecanismo del chasis; aquí el resume keya off el checkbox del plan-doc + CHECKPOINT, ver Delta 1).
+`/w:plan-exec` — **resumable** (same chassis mechanism; here resume keys off the plan-doc checkboxes + CHECKPOINT, see Delta 1).
 
 ## Reads
-`docs/plans/PPP-plan-<slug>.md` (localizar vía glob `docs/plans/PPP-plan-*.md` o la ruta exacta del argumento del comando). Corre **cualquier** plan, haya pasado o no por [`plan-refine-loop`](../plan-refine-loop/SKILL.md) — plan-refine es auxiliar y no obligatorio; no hay gate que lo exija. Si el plan incluye UI, también los **design SPECs** (`NNN-SPEC-<SLUG>.md`) que sus Tasks referencian — artefactos de la sesión de plan-new/plan-refine, leídos **read-only** como referencia de diseño al implementar (ver [`SPEC.md`](../../artifacts/artifacts-design/SPEC.md)).
+`docs/plans/PPP-plan-<slug>.md` (locate via the `docs/plans/PPP-plan-*.md` glob or the exact path from the command argument). It runs **any** plan, whether or not it passed through [`plan-refine-loop`](../plan-refine-loop/SKILL.md) — plan-refine is auxiliary, not mandatory; no gate requires it. If the plan includes UI, it also reads the **design SPECs** (`NNN-SPEC-<SLUG>.md`) its Tasks reference — artifacts of the plan-new/plan-refine session, read **read-only** as the design reference while implementing (see [`SPEC.md`](../../artifacts/artifacts-design/SPEC.md)).
 
 ## Writes
-- `docs/plans/PPP-plan-<slug>.md` (**read/update**, living doc: estado de fases/tareas, `Open questions`).
-- Artefactos de la plan-exec session en `.workflow/sessions/` (`SCRIPTS.sql`, `DECISION`, `ANALYSIS-FILE`/`CONCLUSIONS`, …).
-- **NO** escribe en otras carpetas `docs/` ni **gradúa/exporta** otros artefactos automáticamente (ver *Boundary*).
+- `docs/plans/PPP-plan-<slug>.md` (**read/update**, living doc: phase/task state, `Open questions`).
+- Artifacts of the plan-exec session under `.workflow/sessions/` (`SCRIPTS.sql`, `DECISION`, `ANALYSIS-FILE`/`CONCLUSIONS`, …).
+- It does **NOT** write other `docs/` folders nor **graduate/export** artifacts automatically (see *Boundary*).
 
-## Boundary — sin auto-export (hard rule)
+## Boundary — no auto-export (hard rule)
 
-Regla completa en el chasis (§ *docs/ boundary — sin auto-export*). Acá: la única carpeta `docs/` que este loop escribe es **`docs/plans`** (el plan, living); todo lo demás queda en la session hasta un `export-*` explícito y posterior.
+Full rule in the chassis (§ *docs/ boundary — no auto-export*). Here: the only `docs/` folder this loop writes is **`docs/plans`** (the plan, living); everything else stays in the session until an explicit, later `export-*`.
 
 ## Inherits
 
-Leé **[`../CHASSIS.md`](../CHASSIS.md)** (instalación normal) **o** `CHASSIS.md` junto a este archivo (instalación aplanada) — el motor completo del loop (objetivo persistente + verification-first, gap-driven, session única + research inline, structured-choice + control `flow`, compact/resume, artefactos como log vivo, numeración, convergence gate, docs/ boundary) — **y** **[`../CODE-POLICIES.md`](../CODE-POLICIES.md)** (o `CODE-POLICIES.md` junto a este archivo) — las *Políticas de loops que editan código* (git seguro · BD solo-scripts · gate de revisión de cierre) — **siempre antes** de estos deltas.
+Read **[`../CHASSIS.md`](../CHASSIS.md)** — the loop's **full engine** — **and** **[`../CODE-POLICIES.md`](../CODE-POLICIES.md)** — the *code-editing loop policies* — **always before** these deltas. *(If `../` does not resolve: same names next to this file — global layout rule, chassis § Reference resolution.)*
 
 ## Composes
 
-`git` (rama segura + commits propuestos) · `sql` (regla BD). Ambas resueltas por `.workflow/skills.toml`; `off` → el loop sigue sin la capacidad y, si era necesaria, lo dice o pregunta.
+`git` (safe branch + proposed commits) · `sql` (DB rule). Both resolved via `.workflow/skills.toml`; `off` → the loop continues without the capability and, if it was needed, says so or asks.
 
-> **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).
 
 ## Internal sessions (managed)
 
-- **plan-exec session** descriptor `<slug>-plan-exec` → `NNN-<slug>-plan-exec` (el `<slug>` sale del plan-doc de entrada `docs/plans/PPP-plan-<slug>.md`): **una sola session por run** (Type = `exec`). Dueña del run; posee `SESSION` + `CHECKPOINT` + `DECISION` + `SCRIPTS.sql` (+ `BACKLOG` solo si difiere). La investigación es **inline** dentro de esta session: produce `ANALYSIS-FILE`/`CONCLUSIONS` (+ `SCRIPTS.sql` read-only si consulta BD) en su propia carpeta.
+- **plan-exec session** descriptor `<slug>-plan-exec` → `NNN-<slug>-plan-exec` (the `<slug>` comes from the input plan-doc `docs/plans/PPP-plan-<slug>.md`): **a single session per run** (Type = `exec`). Owns the run; holds `SESSION` + `CHECKPOINT` + `DECISION` + `SCRIPTS.sql` (+ `BACKLOG` only if something is deferred). Research is **inline** inside this session: it produces `ANALYSIS-FILE`/`CONCLUSIONS` (+ read-only `SCRIPTS.sql` if it queries DB) in its own folder.
 
-> **Numeración**: el caller pasa solo el descriptor; el CLI antepone el `NNN` global y secuencial sobre `.workflow/sessions/` (ver chasis). No reinicia por tipo.
+> **Numbering**: the caller passes only the descriptor; the CLI prepends the global sequential `NNN` over `.workflow/sessions/` (see chassis). It never restarts per type.
 
-> **Compat (legacy):** workspaces viejos pueden tener sessions `plan-exec-phase-*` (una por fase) y `*-research-*` — son históricas y se dejan tal cual; los runs nuevos usan una sola session.
+> **Compat (legacy):** old workspaces may hold `plan-exec-phase-*` sessions (one per phase) and `*-research-*` ones — historical, left as-is; new runs use a single session.
 
 ## Delta 1 — One session per run; per-phase progress in the plan-doc
 
-- Recorre las `Phases` del plan en orden (respeta deps) **dentro de la única session del run** (no hay session-por-fase).
-- El **avance por fase vive en el plan-doc** (`- [x]`) y en el `CHECKPOINT` único (Completed/Pending/Next): **artifact-first** — `CHECKPOINT.Next` se fija a la fase inminente **antes** de iniciarla; el checkbox `- [x]` del plan-doc se voltea **después** de completar la tarea.
-- Ejecuta las `Tasks` de la fase; **salta** las ya marcadas `- [x]` en el plan (el plan-doc es la fuente de verdad por tarea). Marca `- [x]` + estado **en el plan** (living doc; no en un `TASKS` aparte).
-- En **cada límite de fase**: valida, corre el **gate de revisión de cierre** (Delta 5), actualiza el `CHECKPOINT` (Completed += Phase N, Next = Phase N+1) y propone commits.
-- Registra `DECISION` solo lo **no obvio**, **a medida que se toma** (los `DECISION` por fase se acumulan en el ÚNICO `DECISION`, etiquetados por fase/tarea — ej. `Origin: T2 (F1)`).
-- El motor **gap-driven** del chasis aplica acá **dentro de una tarea**: ante una decisión/duda no obvia → research inline ó structured-choice.
+- Walks the plan's `Phases` in order (respecting deps) **inside the run's single session** (no session-per-phase).
+- **Per-phase progress lives in the plan-doc** (`- [x]`) and in the single `CHECKPOINT` (Completed/Pending/Next): **artifact-first** — `CHECKPOINT.Next` is set to the imminent phase **before** starting it; the plan-doc's `- [x]` checkbox is flipped **after** completing the task.
+- Executes the phase's `Tasks`; **skips** the ones already `- [x]` in the plan (the plan-doc is the per-task source of truth). Marks `- [x]` + state **in the plan** (living doc; never in a separate `TASKS`).
+- At **every phase boundary**: validate, run the **closing review gate** (Delta 5), update the `CHECKPOINT` (Completed += Phase N, Next = Phase N+1) and propose commits.
+- Records in `DECISION` only the **non-obvious**, **as it is decided** (per-phase decisions accumulate in the SINGLE `DECISION`, tagged by phase/task — e.g. `Origin: T2 (F1)`).
+- The chassis **gap-driven** engine applies here **inside a task**: facing a non-obvious decision/doubt → inline research OR structured-choice.
 
-## Delta 2 — Git policy: **rama segura + commits propuestos**
+## Delta 2 — Git policy: **safe branch + proposed commits**
 
-Política completa en [`../CODE-POLICIES.md`](../CODE-POLICIES.md) (§ *Git seguro*: branch-check antes de editar, commit rechazado — los cambios quedan + se registra —, precondición de working tree entre fases). **Inline:** antes de editar, verificar rama esperada por fuente (`aw check-branch --source <alias>`; si no coincide → pausar y resolver con el humano); al cerrar cada fase y **tras el gate de revisión** (Delta 5), **commits propuestos por fuente** (aprobar antes) — nunca `push`/`--amend`/`--no-verify`.
+Full policy in [`../CODE-POLICIES.md`](../CODE-POLICIES.md) (§ *Safe git*: branch-check before editing, rejected commit — changes stay + get recorded —, working-tree precondition between phases). **Inline:** before editing, verify each source's expected branch (`aw check-branch --source <alias>`; on mismatch → pause and resolve with the human); at each phase close and **after the review gate** (Delta 5), **proposed commits per source** (approve first) — never `push`/`--amend`/`--no-verify`.
 
-## Delta 3 — DB policy: **la IA nunca ejecuta DML**
+## Delta 3 — DB policy: **the AI never executes DML**
 
-Política completa en [`../CODE-POLICIES.md`](../CODE-POLICIES.md) (§ *BD solo-scripts*). **Inline:** consultas read-only → `SCRIPTS.sql` de la session y se ejecutan vía MCP (`sql-mutation-guard`); migraciones DDL/DML → la IA las **redacta en `SCRIPTS.sql` pero NUNCA las ejecuta** — su promoción a `docs/scripts/` la hace un `export-*` aparte, no este loop.
+Full policy in [`../CODE-POLICIES.md`](../CODE-POLICIES.md) (§ *DB scripts-only*). **Inline:** read-only queries → the session's `SCRIPTS.sql`, executed via MCP (`sql-mutation-guard`); DDL/DML migrations → the AI **drafts them in `SCRIPTS.sql` but NEVER executes them** — their promotion to `docs/scripts/` is done by a separate `export-*`, never this loop.
 
 ## Delta 4 — Validation
 
-- Tras ejecutar (por fase y al final): corre tests/checks contra `Validations` + `Final behavior` + acceptance/success criteria del spec.
-- Validación que **corre y falla** → vuelve a la tarea (gap); no avanza.
-- **Validación dependiente de una migración no aplicada**: como la IA no ejecuta el DML, **no puede correr read-only** → se **difiere** (handoff a DBA), **no bloquea el avance**. Se registra en `Open questions` del plan + `BACKLOG`, marcando "verificación pendiente tras aplicar SQL". (Reusa el patrón degradar/diferir + límite `MAX` del chasis → evita el bucle "vuelve a la tarea".)
+- After executing (per phase and at the end): run tests/checks against `Validations` + `Final behavior` + the spec's acceptance/success criteria.
+- A validation that **runs and fails** → back to the task (gap); no advancing.
+- **Validation depending on an unapplied migration**: since the AI never executes the DML, it **cannot run it read-only** → it is **deferred** (handoff to a DBA), it does **not block progress**. Recorded in the plan's `Open questions` + `BACKLOG`, marked "verification pending until the SQL is applied". (Reuses the chassis degrade/defer pattern + `MAX` cap → avoids the "back to the task" loop.)
 
-> La **validación final** es el **convergence gate** de PLAN-exec = **`Success criteria` en verde** (*verification-first*; análogo al *analyze gate* de SPEC y al *coherence gate* de `plan-new`): el plan no se marca *done* hasta que pasa o queda explícitamente diferida (handoff de SQL). Para código son **tests ejecutables** (TDD); para migraciones BD no ejecutables, **rúbrica** (SCRIPTS.sql válido + revisado).
+> The **final validation** is PLAN-exec's **convergence gate** = **`Success criteria` green** (*verification-first*; analogous to SPEC's *analyze gate* and plan-new's *coherence gate*): the plan is not marked *done* until it passes or is explicitly deferred (SQL handoff). For code these are **runnable tests** (TDD); for non-executable DB migrations, a **rubric** (SCRIPTS.sql valid + reviewed).
 
-## Delta 5 — Gate de revisión de cierre (convenciones, pre-commit)
+## Delta 5 — Closing review gate (conventions, pre-commit)
 
-Gate completo en [`../CODE-POLICIES.md`](../CODE-POLICIES.md) (§ *Gate de revisión de cierre*): re-lectura **independiente** del diff + convenciones ambientes instaladas; hallazgos → corregir (re-validando la fase) o diferir justificado. Acá solo el cableado exec: corre **entre la validación de la fase (Delta 4) y sus commits (Delta 2)**; recién con el gate en verde se proponen los commits de la fase.
+Full gate in [`../CODE-POLICIES.md`](../CODE-POLICIES.md) (§ *Closing review gate*): **independent** diff re-read + installed ambient conventions; findings → fix (re-validating the phase) or defer justified. Here only the exec wiring: it runs **between the phase validation (Delta 4) and its commits (Delta 2)**; only with the gate green are the phase's commits proposed.
 
-## Delta 6 — Completitud / cierre
+## Delta 6 — Completion / close
 
-- Una fase cierra **done** cuando sus tareas están `- [x]` y su validación pasó **o** quedó diferida (handoff de SQL). Estado posible: **"done — SQL pendiente de aplicar"**.
-- Todas las fases done → *structured-choice* final (contenido: `Marcar plan done` / `Preguntar algo más`; flow: `Compactar`/`Cerrar`).
-- **Sin export automático**: los artefactos (`SCRIPTS.sql`, `DECISION`, …) quedan en la session. Promoverlos a `docs/` (scripts, manuals, …) es un paso aparte vía `export-*`.
+- A phase closes **done** when its tasks are `- [x]` and its validation passed **or** was deferred (SQL handoff). Possible state: **"done — SQL pending application"**.
+- All phases done → final *structured-choice* (content: `Marcar plan done` / `Preguntar algo más`; flow: `Compactar`/`Cerrar`).
+- **No automatic export**: the artifacts (`SCRIPTS.sql`, `DECISION`, …) stay in the session. Promoting them to `docs/` (scripts, manuals, …) is a separate step via `export-*`.
 
 ## Sequence
 
 ```
 plan-exec-loop(PPP-plan-<slug>.md):
-  session = create_or_resume("<slug>-plan-exec")           # <slug> del plan-doc; UNA sola session por run; CLI antepone NNN global; CHECKPOINT, resume
+  session = create_or_resume("<slug>-plan-exec")           # <slug> from the plan-doc; ONE session per run; CLI prepends global NNN; CHECKPOINT, resume
   plan = read(PPP-plan-<slug>.md)
-  para cada Phase en plan (en orden, respeta deps):
-    si Phase done (todas sus Tasks - [x] en el plan): skip # resume vía checkbox del plan-doc
-    seed CHECKPOINT.Next = Phase N (Pending = sus Tasks)   # ANTES de iniciar la fase: sembrar intención (artifact-first)
-    para cada Task de la Phase:
-      si Task - [x] en el plan: skip                       # resume intra-fase por checkbox
-      verificar rama esperada por fuente (branch-check)
-        si no coincide → pausar + resolver con humano
-      ejecutar Task:
-        editar código en las fuentes (cambio mínimo)
-        si crea herramienta/utilidad → la skill ambiente creating-tools la documenta en docs/tools
-        si consulta BD read-only → SCRIPTS.sql + ejecutar read-only
-        si cambio BD (DDL/DML) → redactar en SCRIPTS.sql (artefacto session, NO ejecutar)
-        si decisión no obvia → DECISION (etiquetado por fase/tarea, en el ÚNICO DECISION)
-        si duda/gap → research inline ó structured-choice    # chasis
-      marcar Task - [x] + estado EN EL PLAN                # DESPUÉS de completar la Task (el plan-doc es la fuente de verdad por tarea)
-    validación de la fase:
-        la que corre y falla → volver a la tarea
-        la dependiente de migración no aplicada → diferir (Open questions + BACKLOG)
-    gate de revisión de cierre (pre-commit):               # Delta 5: CHECKPOINT.Next = "review fase N"
-        re-lectura INDEPENDIENTE del diff de la fase + convenciones ambientes instaladas
-        hallazgos → corregir (y re-validar la fase) ó diferir justificado (Open questions + BACKLOG)
-    update CHECKPOINT (Completed += Phase N, Next = Phase N+1) # DESPUÉS: Pending→Completed + Next = fase siguiente (ver ciclo artifact-first)
-    proponer commit(s) por fuente (aprobar antes)          # nunca push/amend/--no-verify; solo tras el gate en verde
-        si rechazado → cambios quedan; registrar "fase sin commitear"
-    precondición siguiente fase: working tree limpio o reconocido
-  validación final (lo que se pueda; lo dependiente de SQL queda como handoff)
-  structured_choice(contenido: [Marcar plan done, Preguntar algo más], flow: [Compactar, Cerrar])
-  marcar plan done (o "done — SQL pendiente de aplicar")
-  # NO export: los artefactos quedan en la session; un export-* los promueve aparte
-finalize: CHECKPOINT (+ BACKLOG si difiere) + cerrar session + reportar
+  for each Phase in plan (in order, respecting deps):
+    if Phase done (all its Tasks - [x] in the plan): skip  # resume via plan-doc checkboxes
+    seed CHECKPOINT.Next = Phase N (Pending = its Tasks)   # BEFORE starting the phase: seed the intent (artifact-first)
+    for each Task of the Phase:
+      if Task - [x] in the plan: skip                      # intra-phase resume by checkbox
+      verify each source's expected branch (branch-check)
+        on mismatch → pause + resolve with the human
+      execute Task:
+        edit code in the sources (minimal change)
+        if it creates a tool/utility → the ambient creating-tools skill documents it in docs/tools
+        if read-only DB query → SCRIPTS.sql + execute read-only
+        if DB change (DDL/DML) → draft in SCRIPTS.sql (session artifact, DO NOT execute)
+        if non-obvious decision → DECISION (tagged by phase/task, in the SINGLE DECISION)
+        if doubt/gap → inline research OR structured-choice    # chassis
+      mark Task - [x] + state IN THE PLAN                  # AFTER completing the Task (the plan-doc is the per-task source of truth)
+    phase validation:
+        what runs and fails → back to the task
+        what depends on an unapplied migration → defer (Open questions + BACKLOG)
+    closing review gate (pre-commit):                      # Delta 5: CHECKPOINT.Next = "review phase N"
+        INDEPENDENT re-read of the phase diff + installed ambient conventions
+        findings → fix (and re-validate the phase) OR defer justified (Open questions + BACKLOG)
+    update CHECKPOINT (Completed += Phase N, Next = Phase N+1) # AFTER: Pending→Completed + Next = next phase (see artifact-first cycle)
+    propose commit(s) per source (approve first)           # never push/amend/--no-verify; only after the gate is green
+        if rejected → changes stay; record "phase uncommitted"
+    next-phase precondition: working tree clean or acknowledged
+  final validation (whatever can run; the SQL-dependent part stays as a handoff)
+  structured_choice(content: [Marcar plan done, Preguntar algo más], flow: [Compactar, Cerrar])
+  mark plan done (or "done — SQL pending application")
+  # NO export: artifacts stay in the session; a separate export-* promotes them
+finalize: CHECKPOINT (+ BACKLOG if something is deferred) + close session + report
 ```
 
 ## Convergence / exit
 
-- Plan completo + validación OK (o diferida con handoff) + **cada fase pasó su gate de revisión de cierre** antes de commitear → `Marcar plan done`.
-- `Cerrar` (control `flow`, en cualquier momento) → `finalize` persiste `CHECKPOINT` (y `BACKLOG` solo si quedó algo sin ejecutar / sin commitear / sin aplicar), cierra la session, reporta.
-- La promoción de artefactos a `docs/` (vía `export-*`) es **siempre** un paso posterior y explícito, fuera de este loop.
+- Plan complete + validation OK (or deferred with a handoff) + **every phase passed its closing review gate** before committing → `Marcar plan done`.
+- `Cerrar` (`flow` control, at any time) → `finalize` persists `CHECKPOINT` (and `BACKLOG` only if something remained unexecuted / uncommitted / unapplied), closes the session, reports.
+- Promoting artifacts to `docs/` (via `export-*`) is **always** a later, explicit step outside this loop.