@tacuchi/agent-workflow-cli 15.2.0 → 16.1.0

package/dist/application/templates/session.js

@@ -45,7 +45,7 @@ ${renderOriginSection(values.origin)}
 ${values.type}
 
 ## Success criteria
-<!-- Verification-first done-condition, seeded BEFORE executing: falsifiable [ ] items (tests for code, a by-inspection rubric for analysis/design). The loop persists until all are green. -->
+<!-- Verification-first done-condition, seeded BEFORE executing: falsifiable [ ] items (tests for code, a by-inspection rubric for analysis/design). The loop persists until all are green and flips each to [x] at the convergence gate; replace this comment when filling. -->
 - [ ]
 `;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tacuchi/agent-workflow-cli",
-  "version": "15.2.0",
+  "version": "16.1.0",
   "description": "Agnostic runtime CLI for AI development workflows — a stages + loops + artifacts harness. Bundles the universal `w` skill set under `skills/w/` (slash commands `/w:*`: spec-new/spec-refine, plan-new/plan-exec, quick, workspace-init, export-*); `self install --target <host>` copies SKILL + commands + hooks into the host. Pluggable capability skills via `.workflow/skills.toml`. Multi-empresa parametrization via `profile.json` cascade. Namespace auto-detected from any `.<ns>/sessions/` dir in CWD; default `workflow`.",
   "type": "module",
   "bin": {

package/skills/w/README.md

@@ -1,26 +1,26 @@
 # w — agent-workflow skill bundle
 
-> El bundle `w` (`w` = *workflow*) empaqueta el arnés agent-workflow como skills de Claude Code + slash commands `/w:`. Runtime: [`@tacuchi/agent-workflow-cli`](../../README.md) (`agent-workflow` / `aw`).
+> The `w` bundle (`w` = *workflow*) packages the agent-workflow harness as Claude Code skills + `/w:` slash commands. Runtime: [`@tacuchi/agent-workflow-cli`](../../README.md) (`agent-workflow` / `aw`).
 
-Implementa el modelo **stages + loops + artifacts**. La fuente de diseño vive en `docs/referencias/` del hub de agent-workflow. Este README es el índice del bundle; la normativa vive en sus docs canónicos:
+It implements the **stages + loops + artifacts** model. The design source lives under `docs/referencias/` in the agent-workflow hub. This README is the bundle index; the normative text lives in its canonical docs:
 
-- **Modelo completo** — 3 capas + zona `docs/`, los 3 flujos (SPEC/PLAN/QUICK), comandos, capacidades componibles y los 6 invariantes duros: [`SKILL.md`](SKILL.md) (la skill de orientación `workflow`).
-- **Motor de los loops** — objetivo persistente + verification-first, gap-driven, sessions, structured-choice, compact/resume, políticas git/BD/gate de revisión: [`loops/CHASSIS.md`](loops/CHASSIS.md) (los 5 loops son heirs).
-- **Binding capacidad→arnés** (Claude Code / Codex / Gemini-Antigravity / OpenCode / Crush / Warp): [`harness/SKILL.md`](harness/SKILL.md).
+- **Full model** — 3 layers + `docs/` zone, the 3 flows (SPEC/PLAN/QUICK), commands, composable capabilities and the 6 hard invariants: [`SKILL.md`](SKILL.md) (the `workflow` orientation skill).
+- **Loop engine** — persistent objective + verification-first, gap-driven, sessions, structured-choice, compact/resume, git/DB/review-gate policies: [`loops/CHASSIS.md`](loops/CHASSIS.md) (the 5 loops are heirs) + [`loops/CODE-POLICIES.md`](loops/CODE-POLICIES.md).
+- **Capability→harness binding** (Claude Code / Codex / Gemini-Antigravity / OpenCode / Crush / Warp): [`harness/SKILL.md`](harness/SKILL.md).
 
 ## Folders
 
 | Folder | Layer | Contains |
 |---|---|---|
-| [`commands/`](commands/) | 1 | Los slash commands `/w:` que invoca el usuario |
-| [`loops/`](loops/) | 2 | [`CHASSIS.md`](loops/CHASSIS.md) (el motor) + los 5 loop heirs que corre la IA |
-| [`exports/`](exports/) | 1 | La familia `export-*` — única vía artefacto→`docs/` |
-| [`roles/`](roles/) | cross-cutting | Capacidades enchufables (defaults built-in; rebindeables vía `.workflow/skills.toml`) |
-| [`harness/`](harness/SKILL.md) | cross-cutting | Binding capacidad→mecanismo por arnés |
-| [`artifacts/`](artifacts/) | 3 | Plantillas de artefactos de session que manejan los loops |
-| [`hooks/`](hooks/) | — | Plantilla de hooks del host (branch-check, sql-mutation-guard, checkpoint, …) |
-| [`SKILL.md`](SKILL.md) | overview | La skill de orientación `workflow` (guía del modelo completo) |
+| [`commands/`](commands/) | 1 | The `/w:` slash commands the user invokes |
+| [`loops/`](loops/) | 2 | [`CHASSIS.md`](loops/CHASSIS.md) (the engine) + the 5 loop heirs the AI runs |
+| [`exports/`](exports/) | 1 | The `export-*` family — the only artifact→`docs/` path |
+| [`roles/`](roles/) | cross-cutting | Pluggable capabilities (built-in defaults; rebindable via `.workflow/skills.toml`) |
+| [`harness/`](harness/SKILL.md) | cross-cutting | Capability→mechanism binding per harness |
+| [`artifacts/`](artifacts/) | 3 | Session artifact templates the loops manage |
+| [`hooks/`](hooks/) | — | Host hook template (branch-check, sql-mutation-guard, checkpoint, …) |
+| [`SKILL.md`](SKILL.md) | overview | The `workflow` orientation skill (guide to the full model) |
 
 ## Bootstrap
 
-Correr [`/w:workspace-init`](commands/workspace-init.md) una vez para convertir una carpeta en workspace (`.workflow/` + taxonomía `docs/` + bloque `WORKSPACE` + `.workflow/skills.toml`). Sin distinción project/hub — un workspace tiene 1+ fuentes.
+Run [`/w:workspace-init`](commands/workspace-init.md) once to turn a folder into a workspace (`.workflow/` + `docs/` taxonomy + `WORKSPACE` block + `.workflow/skills.toml`). No project/hub distinction — a workspace has 1+ sources.

package/skills/w/SKILL.md

@@ -19,116 +19,116 @@ description: >-
 
 ## Purpose
 
-Explicar el **modelo completo** de agent-workflow para que un agente sepa: qué invoca el usuario, qué corre la IA, dónde aterriza cada entregable, y qué reglas no se rompen. Es el mapa; el detalle fino vive en cada loop/command/export/role.
+Explain the **complete model** of agent-workflow so an agent knows: what the user invokes, what the AI runs, where every deliverable lands, and which rules never break. This is the map; the fine detail lives in each loop/command/export/role.
 
 ## Composed by
 
-Cualquiera que necesite orientación — un loop al arrancar, un agente nuevo en el workspace, o el usuario preguntando "¿cómo funciona esto?".
+Anyone needing orientation — a loop at start, a new agent in the workspace, or the user asking "how does this work?".
 
 ## Knowledge
 
-### Workspace (sin modos)
+### Workspace (no modes)
 
-Un solo concepto: **workspace**. No hay project/hub. La carpeta donde arranca el agente se vuelve workspace con `/w:workspace-init` (scaffolding `.workflow/` + `docs/` + bloque `WORKSPACE` en CLAUDE.md + `.workflow/skills.toml`). Tiene 1+ fuentes (repos); "standalone" = una sola fuente.
+A single concept: **workspace**. There is no project/hub split. The folder where the agent starts becomes a workspace with `/w:workspace-init` (scaffolding `.workflow/` + `docs/` + the `WORKSPACE` block in CLAUDE.md + `.workflow/skills.toml`). It has 1+ sources (repos); "standalone" = a single source.
 
 ### The 3-layer architecture + `docs/` zone
 
 ```
-USUARIO invoca
-  LAYER 1 · COMMANDS (lo único que el usuario invoca)
+USER invokes
+  LAYER 1 · COMMANDS (the only thing the user invokes)
     FLOWS:   spec-new · spec-refine · plan-new · plan-refine · plan-exec · quick
     EXPORTS: export-scripts · export-manuals · export-diagrams · export-reports
-        │ arranca / delega
+        │ starts / delegates
         ▼
-  LAYER 2 · LOOPS (los corre la IA, gap-driven; motor: loops/CHASSIS.md)
+  LAYER 2 · LOOPS (the AI runs them, gap-driven; engine: loops/CHASSIS.md)
     spec-refine-loop · plan-new-loop · plan-refine-loop · plan-exec-loop · quick-loop
-        │ crea / lee / escribe
+        │ creates / reads / writes
         ▼
-  LAYER 3 · SESSIONS + ARTIFACTS (.workflow/sessions/ — efímero, interno)
-        │ los export-* leen artefactos
+  LAYER 3 · SESSIONS + ARTIFACTS (.workflow/sessions/ — ephemeral, internal)
+        │ the export-* read the artifacts
         ▼
-  ZONA docs/ — documentos permanentes, cara al usuario
-    specs · plans (flujos) · scripts · manuals · diagrams · reports (export-*) · tools (ambiente)
+  docs/ ZONE — permanent, user-facing documents
+    specs · plans (flows) · scripts · manuals · diagrams · reports (export-*) · tools (ambient)
 ```
 
-- **Layer 1** — alto nivel. Single-pass o arranca un loop. Sin lógica de iteración.
-- **Layer 2** — la IA itera entera hasta converger. Sin invocación humana directa.
-- **Layer 3** — efímero, interno, process-only. Nadie lo invoca a mano.
+- **Layer 1** — high level. Single-pass or starts a loop. No iteration logic.
+- **Layer 2** — the AI iterates end to end until convergence. No direct human invocation.
+- **Layer 3** — ephemeral, internal, process-only. Nobody invokes it by hand.
 
 ### The 3 flows
 
-| Flow | Commands | docs/ propio | Loops |
+| Flow | Commands | Own docs/ | Loops |
 |---|---|---|---|
-| **SPEC** (el *qué*) | `spec-new` *(single-pass)* · `spec-refine` | `docs/specs` | `spec-refine-loop` |
-| **PLAN** (el *cómo* + ejecutar) | `plan-new` · `plan-refine` *(aux, opcional)* · `plan-exec` | `docs/plans` | `plan-new-loop` · `plan-refine-loop` · `plan-exec-loop` |
-| **QUICK** (atajo liviano) | `quick` | — | `quick-loop` |
+| **SPEC** (the *what*) | `spec-new` *(single-pass)* · `spec-refine` | `docs/specs` | `spec-refine-loop` |
+| **PLAN** (the *how* + execute) | `plan-new` · `plan-refine` *(aux, optional)* · `plan-exec` | `docs/plans` | `plan-new-loop` · `plan-refine-loop` · `plan-exec-loop` |
+| **QUICK** (lightweight shortcut) | `quick` | — | `quick-loop` |
 
-Cadena típica: prompt → `spec-new` genera `docs/specs/NNN-spec-<slug>.md` → `spec-refine` corre el loop y refina **ese mismo spec in place** → `plan-new` → `docs/plans/PPP-plan-<slug>.md` → *(opcional)* `plan-refine` ajusta **ese mismo plan in place** si hay cambios antes de ejecutar → `plan-exec` ejecuta y actualiza el plan (living doc) + artefactos en sesiones. La promoción del resto a `docs/` es **siempre** un paso aparte vía `export-*`.
+Typical chain: prompt → `spec-new` generates `docs/specs/NNN-spec-<slug>.md` → `spec-refine` runs the loop and refines **that same spec in place** → `plan-new` → `docs/plans/PPP-plan-<slug>.md` → *(optional)* `plan-refine` adjusts **that same plan in place** if changes arise before executing → `plan-exec` executes and updates the plan (living doc) + artifacts in sessions. Promoting anything else to `docs/` is **always** a separate step via `export-*`.
 
-QUICK puede **escalar en vivo a SPEC** si el objetivo excede un quick (gate de tamaño a la entrada) o la tarea crece mid-loop: con consentimiento vía structured-choice, la línea de trabajo pasa al flujo SPEC (borrador por procedimiento `spec-new` + `spec-refine-loop` directo); a PLAN la escalación queda **diferida** (siembra + puntero). Ver `loops/quick-loop/SKILL.md` § *Delta QUICK*.
+QUICK can **escalate live to SPEC** when the objective exceeds a quick (entry size gate) or the task grows mid-loop: with consent via structured-choice, the work line moves to the SPEC flow (draft via the `spec-new` procedure + `spec-refine-loop` directly); escalation to PLAN stays **deferred** (seed + pointer). See `loops/quick-loop/SKILL.md` § *QUICK delta*.
 
-### Contexto operativo — dónde aterriza cada cosa
+### Operating context — where everything lands
 
-Antes de cualquier loop, la IA resuelve su **contexto operativo** en **cada prompt** con dos detecciones: **¿workspace?** (existe `.<ns>/sessions/`) + **¿sesión a continuar?** (una activa, o una reciente que este prompt continúa). Eso decide el comportamiento y **dónde aterrizan los artefactos** (SQL, scripts, decisiones, …):
+Before any loop, the AI resolves its **operating context** on **every prompt** with two detections: **workspace?** (`.<ns>/sessions/` exists) + **session to continue?** (an active one, or a recent one this prompt continues). That decides the behavior and **where artifacts land** (SQL, scripts, decisions, …):
 
-| ¿Workspace? | Trigger | → Comportamiento + ruteo |
+| Workspace? | Trigger | → Behavior + routing |
 |---|---|---|
-| **Sí** | **comando de flujo** (`quick`·`spec-*`·`plan-*`) | **nueva línea de trabajo** → crea sesión **nueva** (salvo re-run del mismo flujo sobre la misma entrada: `create_or_resume` reabre la existente), arranca el loop → artefactos a **esa** sesión (`SCRIPTS.sql`, …) |
-| **Sí** | **prompt sin comando** (relacionado) | **continúa/reabre la sesión más reciente** → los scripts editan **su** `SCRIPTS.sql` (no crea otra) |
-| **Sí** | **prompt sin comando** (no-relacionado / sin sesión) | **sin flujo**: trabajo directo → escribe en `docs/` por convención + numeración (`aw next-number`) |
-| **No** | cualquiera | **vanilla** — sin workspace ni flujo, la IA es libre (nativo) |
+| **Yes** | **flow command** (`quick`·`spec-*`·`plan-*`) | **new work line** → creates a **new** session (except re-running the same flow over the same input: `create_or_resume` reopens the existing one), starts the loop → artifacts go to **that** session (`SCRIPTS.sql`, …) |
+| **Yes** | **prompt with no command** (related) | **continues/reopens the most recent session** → scripts edit **its** `SCRIPTS.sql` (no new session) |
+| **Yes** | **prompt with no command** (unrelated / no session) | **no flow**: direct work → writes into `docs/` by convention + numbering (`aw next-number`) |
+| **No** | anything | **vanilla** — no workspace, no flow; the AI is free (native) |
 
-**Regla de continuidad** (fuente única — el chasis y los loops referencian acá):
+**Continuity rule** (single source — the chassis and the loops reference here):
 
-1. **Comando de flujo** = **nueva línea de trabajo** → sesión nueva.
-2. **Excepción — re-run:** el mismo comando sobre la **misma entrada** (ej. `/w:spec-refine` sobre el mismo spec) **no** abre otra línea: `create_or_resume` localiza la sesión de ese flujo (descriptor + `## Origin`) y la **reanuda o reabre** (quita `.closed`), sin duplicarla.
-3. **Excepción consentida — escalación:** la **escalación aceptada** dentro de un loop (ej. quick → SPEC) abre una **nueva línea de trabajo sin comando**; la señal es el **consentimiento explícito** del usuario en la structured-choice, equivalente a haber invocado el comando del flujo destino.
-4. **Prompt sin comando** = "sigo en la misma" → continúa/reabre la sesión **más reciente** (la *última iniciada*).
-5. Solo si el prompt es claramente **no-relacionado**: ofrecer elegir (`continuar NNN` | `trabajo nuevo`) o caer a "sin flujo".
-6. La **convergencia cierra** la sesión; un prompt relacionado posterior la **reabre** (el resume quita `.closed`).
+1. **Flow command** = **new work line** → new session.
+2. **Exception — re-run:** the same command over the **same input** (e.g. `/w:spec-refine` over the same spec) does **not** open another line: `create_or_resume` locates that flow's session (descriptor + `## Origin`) and **resumes or reopens** it (removes `.closed`), never duplicating it.
+3. **Consented exception — escalation:** an **accepted escalation** inside a loop (e.g. quick → SPEC) opens a **new work line without a command**; the signal is the user's **explicit consent** in the structured-choice, equivalent to having invoked the destination flow's command.
+4. **Prompt with no command** = "same line" → continue/reopen the **most recent** session (the *last started*).
+5. Only if the prompt is clearly **unrelated**: offer choosing (`continuar NNN` | `trabajo nuevo`) or fall to "no flow".
+6. **Convergence closes** the session; a later related prompt **reopens** it (resume removes `.closed`).
 
-Es la cara **inter-turno** del *objetivo persistente* (mismo `CHECKPOINT`+resume, aplicado al próximo prompt) — doctrina agnóstica, no un hook del host. Aplica a **todo artefacto** (`SCRIPTS.sql` es el ejemplo trabajado; caso QUICK: `loops/quick-loop/SKILL.md`).
+It is the **inter-turn** face of the *persistent objective* (same `CHECKPOINT`+resume, applied to the next prompt) — agnostic doctrine, not a host hook. It applies to **every artifact** (`SCRIPTS.sql` is the worked example; QUICK case: `loops/quick-loop/SKILL.md`).
 
 ### The commands (`/w:` namespace)
 
-- `/w:workspace-init` — inicializa el workspace.
-- `/w:spec-new` — genera un spec inicial (single-pass, sin loop).
-- `/w:spec-refine` — arranca `spec-refine-loop` para refinar el spec.
-- `/w:plan-new` — arranca `plan-new-loop` para derivar un plan ejecutable del spec refinado.
-- `/w:plan-refine` — arranca `plan-refine-loop` para refinar el plan in place (auxiliar, **no obligatorio**) antes de ejecutar.
-- `/w:plan-exec` — arranca `plan-exec-loop` para ejecutar y mantener el plan.
-- `/w:quick` — arranca `quick-loop` (atajo, sin `docs/`; escala en vivo a SPEC si el objetivo excede un quick).
-- `/w:export-scripts` · `/w:export-manuals` · `/w:export-diagrams` · `/w:export-reports` — promueven artefactos a `docs/`.
+- `/w:workspace-init` — initializes the workspace.
+- `/w:spec-new` — generates an initial spec (single-pass, no loop).
+- `/w:spec-refine` — starts `spec-refine-loop` to refine the spec.
+- `/w:plan-new` — starts `plan-new-loop` to derive an executable plan from the refined spec.
+- `/w:plan-refine` — starts `plan-refine-loop` to refine the plan in place (auxiliary, **not mandatory**) before executing.
+- `/w:plan-exec` — starts `plan-exec-loop` to execute and maintain the plan.
+- `/w:quick` — starts `quick-loop` (shortcut, no `docs/`; escalates live to SPEC when the objective exceeds a quick).
+- `/w:export-scripts` · `/w:export-manuals` · `/w:export-diagrams` · `/w:export-reports` — promote artifacts to `docs/`.
 
 ### Transversal skills (no flow) — `/w:status` · `/w:fix-git`
 
-Skills **invocables independientes de flujo**: se disparan con `/w:` igual que un comando, pero **no** pertenecen a SPEC/PLAN/QUICK, **no** manejan `docs/`, y **no** entran en el conteo **6 comandos de flow / 5 loops**. *(En el bundle se empaquetan bajo `commands/` para que `/w:` las invoque; en el diseño son la categoría `workflow-skills/`.)*
+**Flow-independent invocable** skills: triggered with `/w:` like any command, but they do **not** belong to SPEC/PLAN/QUICK, do **not** manage `docs/`, and do **not** count in **6 flow commands / 5 loops**. *(In the bundle they are packaged under `commands/` so `/w:` can invoke them; in the design they are the `workflow-skills/` category.)*
 
-- `/w:status` — dashboard read-only del workspace (Hecho/Falta/Descartó, con fechas en español). No escribe nada; se apoya en `aw status`.
-- `/w:fix-git` — resuelve conflictos de un merge en curso en cualquier repo (identifica origen↔destino, analiza intención, *structured-choice* ante ambigüedad). No crea session, no toca `docs/`; git-safe; se apoya en `aw merge-state`.
+- `/w:status` — read-only workspace dashboard (Done/Missing/Discarded, dates humanized in the user's language). Writes nothing; backed by `aw status`.
+- `/w:fix-git` — resolves an in-progress merge's conflicts in any repo (identifies origin↔destination, analyzes intent, *structured-choice* on ambiguity). No session, never touches `docs/`; git-safe; backed by `aw merge-state`.
 
 ### The loops (Layer 2)
 
-Un loop es una skill que enseña a la IA **cómo iterar** hasta un entregable: detecta huecos, los resuelve (humano vía structured-choice, research inline o una capacidad compuesta), integra y repite hasta converger. Los 5 loops corren el mismo **motor común** — objetivo persistente + verification-first, gap-driven convergente, session única por run, structured-choice + control `flow` (`Compactar`/`Cerrar`), compact/resume, artefactos como log vivo, convergence gate — cuyo canon vive en [`loops/CHASSIS.md`](loops/CHASSIS.md); cada loop es un **heir** que agrega solo sus deltas.
+A loop is a skill that teaches the AI **how to iterate** to a deliverable: detect gaps, resolve them (human via structured-choice, inline research or a composed capability), integrate and repeat until convergence. The 5 loops run the same **common engine** — persistent objective + verification-first, gap-driven convergent, single session per run, structured-choice + `flow` control (`Compactar`/`Cerrar`), compact/resume, artifacts as a live log, convergence gate — whose canon lives in [`loops/CHASSIS.md`](loops/CHASSIS.md); each loop is an **heir** adding only its deltas.
 
-Los loops que **editan código** (`plan-exec-loop`, `quick-loop`) aplican además las *Políticas de loops que editan código*: git seguro, BD solo-scripts y el **gate de revisión de cierre** pre-commit (nada llega a un commit propuesto sin revisar) — ver [`loops/CODE-POLICIES.md`](loops/CODE-POLICIES.md) (doc hermano del chasis; los loops de documento no lo cargan).
+The **code-editing** loops (`plan-exec-loop`, `quick-loop`) additionally apply the *code-editing loop policies*: safe git, DB scripts-only and the pre-commit **closing review gate** (nothing reaches a proposed commit unreviewed) — see [`loops/CODE-POLICIES.md`](loops/CODE-POLICIES.md) (the chassis' sibling doc; document loops do not load it).
 
-`spec-new` no tiene loop (single-pass): **6 comandos / 5 loops**.
+`spec-new` has no loop (single-pass): **6 commands / 5 loops**.
 
-### The `export-*` family (única vía artefacto → `docs/`)
+### The `export-*` family (the only artifact → `docs/` path)
 
-| Export | Lee | Produce |
+| Export | Reads | Produces |
 |---|---|---|
-| `export-scripts` | `SCRIPTS.sql` (migraciones) de N sesiones | `docs/scripts/` (forwards numerados + `00-ROLLBACK.sql`) |
-| `export-manuals` | sesiones + decisiones + plan + código | `docs/manuals/` |
-| `export-diagrams` | código de las fuentes + plan (AS-IS/TO-BE) | `docs/diagrams/` (C4 / mermaid) |
-| `export-reports` | corpus de sesiones + plan + `docs/` | `docs/reports/` (informe ejecutivo/funcional) |
+| `export-scripts` | `SCRIPTS.sql` (migrations) from N sessions | `docs/scripts/` (numbered forwards + `00-ROLLBACK.sql`) |
+| `export-manuals` | sessions + decisions + plan + code | `docs/manuals/` |
+| `export-diagrams` | source code + plan (AS-IS/TO-BE) | `docs/diagrams/` (C4 / mermaid) |
+| `export-reports` | session corpus + plan + `docs/` | `docs/reports/` (executive/functional report) |
 
-Comunes: Capa 1, explícitos (los invoca el usuario, nunca un loop) · single-pass, read-only sobre sesiones · cross-session (consolidan N sesiones + `docs/`) · sin loop ni sessions internas (opciones por args).
+Common: Layer 1, explicit (user-invoked, never by a loop) · single-pass, read-only over sessions · cross-session (consolidate N sessions + `docs/`) · no loop, no internal sessions (options via args).
 
 ### Capability skills + `.workflow/skills.toml`
 
-Un loop **no** compone una skill concreta; compone una **capacidad por su rol** (ej. `ui-design`). Qué skill cumple el rol lo decide la config, no el loop. Cambiar de implementación = una línea del config.
+A loop does **not** compose a concrete skill; it composes a **capability by its role** (e.g. `ui-design`). Which skill fulfills the role is decided by config, never by the loop. Swapping implementations = one config line.
 
 ```toml
 [skills]
@@ -136,54 +136,66 @@ ui-design        = "ui-spec"          # built-in default
 sql              = "sql"
 git              = "git"
 research         = "research"
-# diagrams       = "off"              # ← capacidad desactivada
-# ui-design      = "acme/figma-spec"  # ← skill de tercero (vía skills.sh)
+# diagrams       = "off"              # ← capability disabled
+# ui-design      = "acme/figma-spec"  # ← third-party skill (via skills.sh)
 ```
 
-**Cascada de resolución**: built-in default → `~/.workflow/skills.toml` (global, PC) → `.workflow/skills.toml` (workspace). El workspace pisa al global; el global al default. Rol sin binding → built-in default. `off` → desactivada (el loop sigue sin ella; si era necesaria, lo dice o pregunta).
+**Resolution cascade**: built-in default → `~/.workflow/skills.toml` (global, machine) → `.workflow/skills.toml` (workspace). Workspace overrides global; global overrides default. Unbound role → built-in default. `off` → disabled (the loop continues without it; if it was needed, it says so or asks).
 
-Catálogo de roles y su default:
+Role catalog and defaults:
 
 | Role | Default | Tier | Composed by |
 |---|---|---|---|
 | `ui-design` | `ui-spec` | must | `spec-refine-loop` (UI) · `plan-new-loop` / `plan-refine-loop` (design SPECs) |
 | `sql` | `sql` | must | research · `plan-exec-loop` · `quick-loop` · `export-scripts` |
 | `git` | `git` | must | `plan-exec-loop` · `quick-loop` |
-| `research` | `research` | should | todos los loops (capacidad inline) |
+| `research` | `research` | should | every loop (inline capability) |
 | `diagrams` | `diagrams` | should | `export-diagrams` |
-| `overview` | `workflow` | should | cualquiera (orientación) |
+| `overview` | `workflow` | should | 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).
 
-El **chasis del loop** NO se bindea: es el motor común de los 5 loops ([`loops/CHASSIS.md`](loops/CHASSIS.md), un doc referenciado), no una capacidad enchufable.
+The **loop chassis** is NOT bound: it is the common engine of the 5 loops ([`loops/CHASSIS.md`](loops/CHASSIS.md), a referenced doc), not a pluggable capability.
 
-### Harness (agnóstico al arnés)
+### Harness (harness-agnostic)
 
-La doctrina nombra **capacidades** abstractas, no tools concretos de un arnés. Un solo doc —`harness/SKILL.md`— liga cada capacidad al mecanismo de cada arnés (Claude Code, Codex, Gemini/Antigravity, OpenCode, Crush, Warp, genérico). Dos principios: **capacidad-no-tool** (los loops/comandos referencian la capacidad por nombre) y **progressive-enhancement** (usar el mecanismo más rico del arnés; degradar a un fallback universal cuando no exista).
+The doctrine names abstract **capabilities**, never a concrete harness tool. A single doc —`harness/SKILL.md`— binds each capability to each harness's mechanism (Claude Code, Codex, Gemini/Antigravity, OpenCode, Crush, Warp, generic). Two principles: **capability-not-tool** (loops/commands reference the capability by name) and **progressive-enhancement** (use the harness's richest mechanism; degrade to a universal fallback when it does not exist).
 
-Capacidades clave:
+Key capabilities:
 
-- **structured-choice** — preguntar al humano ≤3 preguntas de contenido + 1 control `flow`. Claude Code: `AskUserQuestion`. Fallback: markdown numerado.
-- **compaction** — encoger el contexto sin perder el hilo. Claude Code: `/compact`. Fallback: `CHECKPOINT` + resume.
+- **structured-choice** — ask the human ≤3 content questions + 1 `flow` control. Claude Code: `AskUserQuestion`. Fallback: numbered markdown.
+- **compaction** — shrink the context without losing the thread. Claude Code: `/compact`. Fallback: `CHECKPOINT` + resume.
 - **command-invocation** · **procedure-loading** · **subagent-dispatch** (opt.) · **persistent-context** · **external-data** (MCP) · **dry-run/preview**.
 
-Las únicas `must` para el ciclo de un loop son **structured-choice** y **compaction**, y ambas degradan a texto → cualquier arnés con chat + archivos corre el modelo completo. Detalle, matriz de binding y distribución (`AGENTS.md` canónico + symlink `CLAUDE.md`): ver `harness/SKILL.md`.
+The only `must` capabilities for a loop's cycle are **structured-choice** and **compaction**, and both degrade to text → any harness with chat + files runs the full model. Detail, binding matrix and distribution (canonical `AGENTS.md` + `CLAUDE.md` symlink): see `harness/SKILL.md`.
+
+### Language policy (per surface)
+
+One language per plane — never mix them:
+
+| Surface | Language |
+|---|---|
+| Doctrine (this bundle: chassis, loops, commands, roles, exports, harness) | **English** |
+| **Section headings** of artifacts and docs (`## Requirement`, `## Completed`, …) | **English** (parse contract) |
+| Everything **user-facing**: structured-choice questions, reports, dashboards, the **content** the AI writes into artifacts and `docs/` deliverables, commit messages | **the user's language** (this product: Spanish) |
+| Literal option labels (`Compactar`, `Cerrar`, `Guardar plan`, …) | canonical product strings — use them **verbatim** |
+| Domain terms (class/route/table names, e.g. the QTC fleet) | the domain's ubiquitous language (Spanish) — never translated |
 
 ### The 6 hard invariants
 
-1. **Sin auto-export** — los loops nunca graduan/exportan a `docs/`. Solo `export-*` lo hace, explícito.
-2. **Cada flujo toca solo sus carpetas `docs/`** — SPEC→`specs` · PLAN→`plans` · QUICK→ninguna · resto→`export-*`. (`docs/tools` no es de un flujo: lo escribe la skill ambiente `creating-tools`.)
-3. **El spec y el plan son documentos** (`docs/`), no artefactos de sesión. *(No confundir con los **design SPECs** `NNN-SPEC-<SLUG>.md`: artefactos de diseño de UI **por pantalla** que las sesiones de PLAN producen vía la capacidad `ui-design` cuando el plan incluye UI — ver `artifacts/artifacts-design/` — no son el requirement-spec.)*
-4. **BD solo-scripts** — la IA nunca ejecuta DML/DDL; las migraciones quedan en `SCRIPTS.sql` y las aplica el usuario. Solo lecturas read-only vía MCP.
-5. **Git seguro** — rama esperada verificada antes de editar; commits propuestos por fuente; nunca `push`/`--amend`/`--no-verify`.
-6. **Chasis de loops** — los 5 loops corren el mismo **motor común**; cada loop es un heir que agrega solo sus deltas, nada del motor se re-declara. Detalle: `loops/CHASSIS.md`.
+1. **No auto-export** — loops never graduate/export to `docs/`. Only `export-*` does, explicitly.
+2. **Each flow touches only its `docs/` folders** — SPEC→`specs` · PLAN→`plans` · QUICK→none · rest→`export-*`. (`docs/tools` belongs to no flow: the ambient skill `creating-tools` writes it.)
+3. **The spec and the plan are documents** (`docs/`), not session artifacts. *(Not to be confused with the **design SPECs** `NNN-SPEC-<SLUG>.md`: **per-screen** UI design artifacts that PLAN sessions produce via the `ui-design` capability when the plan includes UI — see `artifacts/artifacts-design/` — they are not the requirement-spec.)*
+4. **DB scripts-only** — the AI never executes DML/DDL; migrations stay in `SCRIPTS.sql` and the user applies them. Only read-only reads via MCP.
+5. **Safe git** — expected branch verified before editing; proposed commits per source; never `push`/`--amend`/`--no-verify`.
+6. **Loop chassis** — the 5 loops run the same **common engine**; each loop is an heir adding only its deltas, nothing of the engine is re-declared. Detail: `loops/CHASSIS.md`.
 
-> **Alcance de #1/#2:** gobiernan el plano **sesión → `docs/`** (solo `export-*` lo cruza). El *authoring directo sin flujo* (ver § *Contexto operativo*) es **otro plano**: sin sesión activa, `docs/` es la única superficie gestionada → la IA escribe ahí por convención + numeración. No es auto-export (no hay sesión de la cual graduar).
+> **Scope of #1/#2:** they govern the **session → `docs/`** plane (only `export-*` crosses it). *Direct no-flow authoring* (see § *Operating context*) is **another plane**: with no active session, `docs/` is the only managed surface → the AI writes there by convention + numbering. It is not auto-export (there is no session to graduate from).
 
 ## Output
 
-Ninguno. Es orientación pura: no escribe documentos ni artefactos.
+None. Pure orientation: it writes no documents or artifacts.
 
 ## Source
 
-Autorada del modelo de diseño (`docs/referencias/`): README de arquitectura (3 capas + 6 invariantes), `workflow-commands/`, `workflow-loops/`, `workflow-artifacts/`, `workflow-exports/`, `workflow-roles/`, `workflow-skills/`, `workflow-harness/`. Modelo actual, desplegado. (Compat: reemplaza la orientación del bundle legacy `session` + flows dev/design/analyze.)
+Authored from the design model (`docs/referencias/`): architecture README (3 layers + 6 invariants), `workflow-commands/`, `workflow-loops/`, `workflow-artifacts/`, `workflow-exports/`, `workflow-roles/`, `workflow-skills/`, `workflow-harness/`. Current, deployed model. (Compat: replaces the legacy `session` bundle orientation + dev/design/analyze flows.)

package/skills/w/artifacts/README.md

@@ -43,7 +43,7 @@ Sessions are created by the loops as needed — **one session per run**. The ses
 
 ## Common artifacts (any session)
 
-`SESSION` (descriptor: Objective / Origin / Type / **Success criteria** = verification-first done-condition, formerly research-only) · `CHECKPOINT` (resume) · `SCRIPTS.sql` (read-only queries **executable** + DDL/DML migrations **deliverable**, not executed) · `TASKS` · `BACKLOG` (only when there's something to defer).
+`SESSION` (descriptor: Objective / Origin / Type / **Success criteria** — the verification-first done-condition; the convergence gate flips them green) · `CHECKPOINT` (resume — **fixed headings, updated in place, never duplicated**; see its contract) · `SCRIPTS.sql` (read-only queries **executable** + DDL/DML migrations **deliverable**, not executed) · `TASKS` · `BACKLOG` (only when there's something to defer).
 
 ---
 

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

@@ -1,23 +1,25 @@
 # CHECKPOINT.md — session resume state (common)
 
 > What it is: the live resume state of a session — lets the loop resume exactly where it left off.
-> **Live log (artifact-first):** `Pending`/`Next` = the intent (what is about to be done, seeded BEFORE executing); `Completed` = the result (AFTER). Updated at every gap/phase boundary, not only on `Compactar`/`Cerrar`.
-> Owned by: **every session** (`refine` · `exec` · `quick`). Persisted **always** on close/compact (the resume key — invariant #6), unlike `BACKLOG` which is written only when something is deferred.
+> **Live log (artifact-first):** `Pending / Next` = the intent (what is about to be done, seeded BEFORE executing); `Completed` = the result (AFTER). Updated at every gap/phase boundary, not only on `Compactar`/`Cerrar`.
+> Owned by: **every session** (`refine` · `exec` · `quick`). Persisted **always** on close/compact (the resume key), unlike `BACKLOG`, which is written only when something is deferred.
 
-## Activity
-Summary of the activity done so far.
+## Contract (hard rules)
 
-## Critical context
-Key decisions / references to other artifacts or documents needed to continue.
+1. **Fixed headings, exactly these three**: `## Completed` · `## Pending / Next` · `## Open questions` (plus the optional ones below).
+2. **Update in place — NEVER duplicate a section.** Every update edits the existing section's content; appending a second `## <same heading>` is a contract violation.
+3. New entries go at the top of their section (most recent first) or extend an existing bullet — each section stays a single block.
 
 ## Completed
-Completed phases/tasks (ref: plan-doc `docs/plans/PPP-plan.md`; or `TASKS.md` if the session created its own breakdown).
+What already happened: finished phases/tasks/gaps with their outcome (ref: plan-doc `docs/plans/PPP-plan.md`, the spec's gaps, or `TASKS.md` if the session created its own split). Fold the key context a resume needs (settled decisions, discoveries) into these bullets.
 
-## Excluded
-Excluded phases/tasks (ref: plan-doc; or `TASKS.md`) with reason.
+## Pending / Next
+The intent: what remains and what comes immediately next (seeded BEFORE executing — artifact-first). A resume starts here.
 
-## Pending
-Pending phases/tasks (ref: plan-doc; or `TASKS.md`) still to do.
+## Open questions
+Live doubts not yet resolved (ideally "None"). Deferred ones move to the session's `BACKLOG` or the flow doc's `## Open questions`.
 
-## Next
-Next phase/task (ref: plan-doc; or `TASKS.md`) to continue from on resume.
+### Optional sections
+
+- `## Excluded` — phases/tasks explicitly excluded, with reason (the `aw status` dashboard reads it for the discarded list).
+- The `checkpoint-write` hook (PreCompact/SessionEnd) may write a **machine snapshot** with its own headings (`Last action`, `Next step`, `Files touched`, `Refs`, …) and `_[AI: …]_` placeholders — complete the placeholders; the loop-owned contract above still governs what the loop writes.

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

@@ -21,4 +21,4 @@ Session type, **set by the parent loop** (not the user). Authoritative catalog:
 > `research` is **not** a session type the loops create. Research is an **inline** activity: ANALYSIS-FILE / CONCLUSIONS are written into whatever session is active (`refine`/`exec`/`quick`) when it does investigation.
 
 ## Success criteria
-The run's **done-condition**, seeded at session creation: a checklist `[ ]` of **falsifiable** items. Executable deliverable → runnable tests/checks; non-executable → inspection rubric (the human ratifies it if subjective). Spec/plan sessions may **reference** the doc's acceptance criteria instead of duplicating them. Full doctrine: [`../../loops/CHASSIS.md`](../../loops/CHASSIS.md) § *Verification-first*.
+The run's **done-condition**, seeded at session creation: a checklist `[ ]` of **falsifiable** items. Executable deliverable → runnable tests/checks; non-executable → inspection rubric (the human ratifies it if subjective). Spec/plan sessions may **reference** the doc's acceptance criteria instead of duplicating them. The convergence gate **flips** each criterion to `- [x]` as it turns green — on close the checklist reflects the real final state. Full doctrine: [`../../loops/CHASSIS.md`](../../loops/CHASSIS.md) § *Verification-first*.

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

@@ -1,6 +1,6 @@
 # TASKS.md — internal task breakdown (optional, common)
 
-> What it is: an internal phases/tasks breakdown for sessions that need their own desglose. **Optional artifact** — in the PLAN flow, phases and tasks live in the **plan-doc** (`docs/plans/PPP-plan.md`, living). Use this only when a session needs a breakdown that is not covered by the plan-doc.
+> What it is: an internal phases/tasks breakdown for sessions that need their own split. **Optional artifact** — in the PLAN flow, phases and tasks live in the **plan-doc** (`docs/plans/PPP-plan.md`, living). Use this only when a session needs a breakdown that is not covered by the plan-doc.
 
 ## Phases
 Grouping phases. Phases should have a complexity between XS and S.

package/skills/w/artifacts/artifacts-research/CONCLUSIONS.md

@@ -1,6 +1,6 @@
 # CONCLUSIONS.md — research conclusions
 
-> What it is: the conclusions of an **inline research** activity, written into the active session (`refine`/`exec`/`quick`). Produced when the research concludes (success or `inconcluso`). The parent loop reads this to resolve the gap that triggered the research.
+> What it is: the conclusions of an **inline research** activity, written into the active session (`refine`/`exec`/`quick`). Produced when the research concludes (success or `inconclusive`). The parent loop reads this to resolve the gap that triggered the research.
 
 ## Conclusion
 Direct answer to the initial question.

package/skills/w/commands/README.md

@@ -1,44 +1,44 @@
 # w — Command map (Layer 1)
 
-> README del namespace `/w:` (`w` = *workflow*): todo lo listado acá es lo **único que el usuario invoca** directamente. Los comandos son la **Capa 1** — single-pass o arrancan un loop; sin lógica de iteración.
+> README of the `/w:` namespace (`w` = *workflow*): everything listed here is the **only thing the user invokes** directly. Commands are **Layer 1** — single-pass or they start a loop; no iteration logic.
 >
-> **Canon**: el modelo completo (3 capas + zona `docs/`, los 3 flujos, invariantes duros) vive en [`../SKILL.md`](../SKILL.md); el **motor de los loops** en [`../loops/CHASSIS.md`](../loops/CHASSIS.md). Este README es solo el índice de la carpeta.
+> **Canon**: the full model (3 layers + `docs/` zone, the 3 flows, hard invariants) lives in [`../SKILL.md`](../SKILL.md); the **loop engine** in [`../loops/CHASSIS.md`](../loops/CHASSIS.md). This README is only the folder index.
 
 ---
 
 ## Bootstrap
 
-[`/w:workspace-init`](workspace-init.md) convierte la carpeta actual en un **workspace** (`.workflow/` + `docs/` + bloque `WORKSPACE` + `.workflow/skills.toml`). Sin distinción project/hub; correr una vez antes de cualquier flujo.
+[`/w:workspace-init`](workspace-init.md) turns the current folder into a **workspace** (`.workflow/` + `docs/` + `WORKSPACE` block + `.workflow/skills.toml`). No project/hub distinction; run once before any flow.
 
 ## Index
 
-| Command | Qué hace | Mode |
+| Command | What it does | Mode |
 |---|---|---|
-| [`workspace-init`](workspace-init.md) | Bootstrap del workspace | single-pass, interactivo |
-| [`spec-new`](spec-new.md) | Genera el borrador de spec (`docs/specs/NNN-spec-<slug>.md`) | single-pass, sin loop |
-| [`spec-refine`](spec-refine.md) | Refina el spec **in place** hasta desambiguarlo | arranca `spec-refine-loop` |
-| [`plan-new`](plan-new.md) | Deriva el plan ejecutable (`docs/plans/PPP-plan-<slug>.md`) del spec | arranca `plan-new-loop` |
-| [`plan-refine`](plan-refine.md) | Refina el plan **in place** antes de ejecutar (aux, opcional) | arranca `plan-refine-loop` |
-| [`plan-exec`](plan-exec.md) | Ejecuta el plan (código/BD/git) y lo mantiene como living doc | arranca `plan-exec-loop` |
-| [`quick`](quick.md) | Atajo liviano para trabajo acotado; no toca `docs/` | arranca `quick-loop` |
-| [`status`](status.md) | Dashboard read-only del workspace | single-pass (transversal) |
-| [`fix-git`](fix-git.md) | Resuelve un merge en curso, git-safe | single-pass (transversal) |
-| [`export-scripts`](export-scripts.md) | Promueve migraciones SQL de sesiones a `docs/scripts/` | single-pass, read-only |
-| [`export-manuals`](export-manuals.md) | Genera manuales en `docs/manuals/` | single-pass, read-only |
-| [`export-diagrams`](export-diagrams.md) | Genera diagramas C4/mermaid en `docs/diagrams/` | single-pass, read-only |
-| [`export-reports`](export-reports.md) | Genera informes en `docs/reports/` | single-pass, read-only |
-
-> **Asimetría intencional:** en SPEC, `spec-new` genera el borrador en single-pass (sin loop) y el loop está en `spec-refine`; en PLAN, los 3 comandos arrancan loops. Total: **6 comandos de flow / 5 loops**.
+| [`workspace-init`](workspace-init.md) | Workspace bootstrap | single-pass, interactive |
+| [`spec-new`](spec-new.md) | Generates the spec draft (`docs/specs/NNN-spec-<slug>.md`) | single-pass, no loop |
+| [`spec-refine`](spec-refine.md) | Refines the spec **in place** until unambiguous | starts `spec-refine-loop` |
+| [`plan-new`](plan-new.md) | Derives the executable plan (`docs/plans/PPP-plan-<slug>.md`) from the spec | starts `plan-new-loop` |
+| [`plan-refine`](plan-refine.md) | Refines the plan **in place** before executing (aux, optional) | starts `plan-refine-loop` |
+| [`plan-exec`](plan-exec.md) | Executes the plan (code/DB/git) and maintains it as a living doc | starts `plan-exec-loop` |
+| [`quick`](quick.md) | Lightweight shortcut for scoped work; never touches `docs/` | starts `quick-loop` |
+| [`status`](status.md) | Read-only workspace dashboard | single-pass (transversal) |
+| [`fix-git`](fix-git.md) | Resolves an in-progress merge, git-safe | single-pass (transversal) |
+| [`export-scripts`](export-scripts.md) | Promotes session SQL migrations to `docs/scripts/` | single-pass, read-only |
+| [`export-manuals`](export-manuals.md) | Generates manuals in `docs/manuals/` | single-pass, read-only |
+| [`export-diagrams`](export-diagrams.md) | Generates C4/mermaid diagrams in `docs/diagrams/` | single-pass, read-only |
+| [`export-reports`](export-reports.md) | Generates reports in `docs/reports/` | single-pass, read-only |
+
+> **Intentional asymmetry:** in SPEC, `spec-new` generates the draft single-pass (no loop) and the loop lives in `spec-refine`; in PLAN, all 3 commands start loops. Total: **6 flow commands / 5 loops**.
 >
-> **Transversales (no flow):** `status` y `fix-git` no pertenecen a SPEC/PLAN/QUICK ni cuentan en 6/5. En el diseño son su propia categoría (`workflow-skills/`); acá se empaquetan bajo `commands/` para que `/w:` las invoque — ver [`../harness/SKILL.md`](../harness/SKILL.md) § *Command packaging*.
+> **Transversal (no flow):** `status` and `fix-git` belong to no SPEC/PLAN/QUICK flow and do not count in 6/5. In the design they are their own category (`workflow-skills/`); here they are packaged under `commands/` so `/w:` can invoke them — see [`../harness/SKILL.md`](../harness/SKILL.md) § *Command packaging*.
 
 ## Schema of each command file
 
-Cada `<command>.md` de esta carpeta usa este frontmatter + estructura de cuerpo — el esquema (incluidos `allowed-tools:` y el tool `Skill`) es el **binding Claude Code**; otros arneses envuelven el mismo contrato en su formato (ver [`../harness/SKILL.md`](../harness/SKILL.md) § *Command packaging*):
+Every `<command>.md` in this folder uses this frontmatter + body structure — the schema (including `allowed-tools:` and the `Skill` tool) is the **Claude Code binding**; other harnesses wrap the same contract in their format (see [`../harness/SKILL.md`](../harness/SKILL.md) § *Command packaging*):
 
 | Field | Description |
 |---|---|
-| `description:` | One line: what + when (drives discovery in `/`-picker) |
+| `description:` | One line: what + when (drives discovery in the `/`-picker) |
 | `argument-hint:` | Argument signature for the user |
 | `allowed-tools:` | YAML list (typically `Bash`/`Read`/`Write`/`Edit`). Loops/exports are **read-and-followed**, not invoked with `Skill:` — so `Skill` is **not** in `allowed-tools`. |
 | Body | 1-3 orienting lines, then the invocation: **read-and-follow** the sibling loop/export `SKILL.md`, or call the `aw` CLI; then `## Plan mode`, `## Resources` |