@tacuchi/agent-workflow-cli 14.6.0 → 14.8.0

package/README.md

@@ -16,11 +16,11 @@ The harness has three layers plus a permanent `docs/` zone:
 
 - **Layer 1 · Commands** (`/w:*`) — the only thing the user invokes:
   - **SPEC** — `/w:spec-new` (single-pass draft) → `/w:spec-refine` (gap-driven loop) → `docs/specs/`.
-  - **PLAN** — `/w:plan-new` → `/w:plan-exec` → `docs/plans/`.
+  - **PLAN** — `/w:plan-new` → (`/w:plan-refine` — aux, optional) → `/w:plan-exec` → `docs/plans/`.
   - **QUICK** — `/w:quick` — lightweight shortcut.
   - **EXPORTS** — `/w:export-scripts` · `export-manuals` · `export-diagrams` · `export-reports` (the only path that promotes artifacts to `docs/`).
   - **Bootstrap** — `/w:workspace-init` turns any folder into a workspace (1+ sources; no project/hub distinction).
-- **Layer 2 · Loops** — the AI runs them whole: `spec-refine-loop` (chassis) · `plan-new-loop` · `plan-exec-loop` · `quick-loop`. Each loop is a **persistent goal** that runs until its success criteria are green (verification-first); gap-driven, with **structured-choice** lifecycle control (compact/close — `AskUserQuestion` on Claude Code, numbered markdown elsewhere) and resumable `CHECKPOINT`.
+- **Layer 2 · Loops** — the AI runs them whole: `spec-refine-loop` (chassis) · `plan-new-loop` · `plan-refine-loop` · `plan-exec-loop` · `quick-loop`. Each loop is a **persistent goal** that runs until its success criteria are green (verification-first); gap-driven, with **structured-choice** lifecycle control (compact/close — `AskUserQuestion` on Claude Code, numbered markdown elsewhere) and resumable `CHECKPOINT`.
 - **Layer 3 · Sessions + artifacts** — internal, ephemeral process state under `.workflow/sessions/` (`SESSION` · `CHECKPOINT` · `BACKLOG` · `SCRIPTS.sql` · `ANALYSIS-FILE` · `CONCLUSIONS` · `DECISION` · …). Sessions are slug-named folders, created by loops, never by the user.
 
 **Pluggable capabilities.** Loops compose capability **roles** (`ui-design`, `sql`, `git`, `research`, `diagrams`, `overview`); the concrete skill bound to each role is resolved via `.workflow/skills.toml` (cascade: built-in default → `~/.workflow/skills.toml` → workspace). Inspect bindings with `aw skills` (advisory: it also warns when a bound skill is not installed in the standard skill roots — the binding itself is not auto-validated). Code/testing/writing conventions **and tool authoring** (`creating-tools`) are **not** roles — they're ambient skills the host auto-applies when present, independent of the workflow. Per-source launch scripts live under `.workflow/launch/` (machine-specific, gitignored); created tools live under `docs/tools/`.
@@ -32,7 +32,7 @@ The harness has three layers plus a permanent `docs/` zone:
 The published tarball bundles the universal skill set under `skills/w/`. Install it into your host with `--target` (required):
 
 ```bash
-agent-workflow self install --target claude     # or: codex · warp · oz · agents
+agent-workflow self install --target claude     # or: codex · warp · oz · agents · gemini · opencode · crush
 agent-workflow self install --target all --confirm-all
 agent-workflow self detect-hosts                # which hosts are present + already have it
 agent-workflow self install --target claude --dry-run
@@ -51,6 +51,9 @@ By default the CLI clears the target host's plugin cache before installing (opt
 | `warp` | `~/.warp/skills/w/` | skipped (uses rules/notebooks) | skipped (no hook system) |
 | `oz` | `~/.agents/skills/w/` | skipped | skipped |
 | `agents` | `~/.agents/skills/w/` | skipped | skipped |
+| `gemini` | `~/.gemini/skills/w/` | skipped (native `.toml` commands deferred) | skipped |
+| `opencode` | `~/.opencode/skills/w/` | skipped (deferred) | skipped |
+| `crush` | `~/.crush/skills/w/` | skipped (deferred) | skipped |
 
 For hosts where a layer is skipped, the SKILL is sufficient — the AI reads it and invokes `agent-workflow <subcommand>` directly.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tacuchi/agent-workflow-cli",
-  "version": "14.6.0",
+  "version": "14.8.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

@@ -58,7 +58,7 @@ Run [`/w:workspace-init`](commands/workspace-init.md) once to turn a folder into
 
 1. **No auto-export** — loops never promote artifacts to `docs/`; only `export-*` does, explicitly.
 2. **Folder ownership** — SPEC→`specs`; PLAN→`plans`; QUICK→none; the rest→`export-*`. (`docs/tools` is ambient — written by the `creating-tools` skill, not a flow.)
-3. **spec & plan are documents** (`docs/`), not artifacts.
+3. **spec & plan are documents** (`docs/`), not artifacts. *(Not to be confused with the **design SPECs** `NNN-SPEC-<SLUG>.md`: per-screen UI design artifacts of PLAN sessions — see [`artifacts/artifacts-design/`](artifacts/artifacts-design/).)*
 4. **DB scripts-only** — the AI never executes DML/DDL; migrations land in `SCRIPTS.sql` and ship via `export-scripts`; reads are read-only via MCP.
 5. **Git-safe** — verify the expected branch before editing; propose commits per source; never `push`/`--amend`/`--no-verify`.
 6. **All loops** — gap-driven convergent; one session per run (research inline); **structured-choice** (capability — see [`harness/`](harness/SKILL.md); on Claude Code: `AskUserQuestion`) with ≤3 content questions + 1 always-present `flow` control (`Compactar`/`Cerrar`); a **convergence gate** before saving; compact/resume; artifacts as a live log (`CHECKPOINT` always; `BACKLOG` only when deferring).

package/skills/w/SKILL.md

@@ -112,6 +112,8 @@ Un loop es una skill que enseña a la IA **cómo iterar** hasta un entregable. P
 
 Cada loop tiene un **convergence gate** read-only antes de ofrecer `Guardar`/`done`, que es operacionalmente **"todos los `SESSION.Success criteria` en verde"** (*verification-first*): chequea invariantes propios del entregable y lo que falle vuelve como gap (en `spec-refine-loop` es el *analyze gate*; en `plan-new-loop` —y en `plan-refine-loop`— la coherencia del plan; en `plan-exec-loop`, la validación final; en `quick-loop`, una validación puntual proporcional). El detalle vive en cada loop.
 
+Los loops que **editan código** (`plan-exec-loop` por fase, `quick-loop` proporcional) corren además un **gate de revisión de cierre** ANTES de proponer cada commit: re-lectura **independiente** del diff aplicando las **convenciones ambientes instaladas** (el host las auto-descubre; el workflow crea el momento, no las bindea — no es un rol); los hallazgos se corrigen (re-validando) o se difieren justificados. Nada llega a un commit propuesto sin revisar. Ver `loops/plan-exec-loop/SKILL.md` § *Delta 5*.
+
 `spec-new` no tiene loop (single-pass): **6 comandos / 5 loops**.
 
 ### The `export-*` family (única vía artefacto → `docs/`)
@@ -145,7 +147,7 @@ Catálogo de roles y su default:
 
 | Role | Default | Tier | Composed by |
 |---|---|---|---|
-| `ui-design` | `ui-spec` | must | `spec-refine-loop` (UI) |
+| `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) |
@@ -172,7 +174,7 @@ Las únicas `must` para el ciclo de un loop son **structured-choice** y **compac
 
 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.
+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** — **objetivo persistente + verification-first** (persigue `SESSION.Objective` hasta que sus `SESSION.Success criteria` —sembrados al inicio, TDD generalizado— están en verde) · gap-driven convergente · una sola session por run (research inline) · **structured-choice** con ≤3 preguntas de contenido + 1 control `flow` (`Compactar`/`Cerrar`) siempre · compactación/resume · artefactos como log vivo **artifact-first** (sembrar `Pending`/`Next` antes, `Completed` después; `CHECKPOINT` siempre; `BACKLOG` solo si difiere).

package/skills/w/artifacts/README.md

@@ -15,7 +15,7 @@ Central distinction of the model:
 | Location | `.workflow/sessions/NNN-…/` | `docs/<category>/` |
 | Who manages it | a **loop**, through a **session** | produced by a loop/command at "save" time |
 | User-facing | No (internal) | Yes |
-| Examples | `CHECKPOINT`, `ANALYSIS-FILE`, `CONCLUSIONS`, `SCRIPTS.sql`, `TASKS`, `DECISION` | `specs`, `plans`, `manuals`, `scripts`, `diagrams`, `reports` |
+| Examples | `CHECKPOINT`, `ANALYSIS-FILE`, `CONCLUSIONS`, `SCRIPTS.sql`, `TASKS`, `DECISION`, `NNN-SPEC-<SLUG>.md` | `specs`, `plans`, `manuals`, `scripts`, `diagrams`, `reports` |
 
 > An artifact may be **promoted** to a `docs/` document (e.g. `SCRIPTS.sql` → `docs/scripts/`) — but **only via dedicated `export-*` skills**, **never** automatically by the loops. The spec and the plan **are not** artifacts: they are documents.
 
@@ -29,12 +29,14 @@ Sessions are created by the loops as needed — **one session per run**. The ses
 
 | Session type | Created by | Artifacts | Notes |
 |---|---|---|---|
-| **refine** | `spec-refine-loop` · `plan-new-loop` | `SESSION` · `CHECKPOINT` · `BACKLOG` (on close, if any) | Owns the loop run (spec-refine, plan-new). |
+| **refine** | `spec-refine-loop` · `plan-new-loop` · `plan-refine-loop` | `SESSION` · `CHECKPOINT` · `BACKLOG` (on close, if any) · `NNN-SPEC-<SLUG>.md` (PLAN sessions with UI) | Owns the loop run (spec-refine, plan-new, plan-refine). |
 | **exec** | `plan-exec-loop` | `SESSION` · `CHECKPOINT` · `BACKLOG` (on close, if any) · `DECISION` · `SCRIPTS.sql` | A single per-run exec session (**not** one per phase). No `TECHNICAL-NOTE` or own `TASKS` — detail lives in the plan-doc (living). `TASKS` is optional for internal breakdown. |
 | **quick** | `quick-loop` | `SESSION` · `CHECKPOINT` · `BACKLOG` (on close, if any) · `DECISION` · `SCRIPTS.sql` | Single session, single commit. |
 
 > **Inline research (any session):** research is **not** a session type. When any session (`refine`/`exec`/`quick`) needs to investigate, it produces research artifacts **inline**: `ANALYSIS-FILE` (optional scratchpad), `CONCLUSIONS`, and read-only `SCRIPTS.sql` (if DB). These are written into the active session — there is no separate research session.
 
+> **Inline design (PLAN sessions):** when the plan **includes UI**, `plan-new-loop`/`plan-refine-loop` compose the **`ui-design`** capability and produce **design SPECs** — `NNN-SPEC-<SLUG>.md`, one **per screen** (`001-SPEC-MODAL-EXPORT.md`, `002-SPEC-ADMIN-DASHBOARD.md`), numbering local to the session — inside their own session. The plan-doc **references** them (UI Tasks) and `plan-exec-loop` reads them as the design reference. They are **not** the requirement-spec (invariant 3): they are process artifacts. See [`artifacts-design/`](artifacts-design/).
+
 > **PLAN note (rich plan):** the plan-doc (`docs/plans/PPP-plan.md`) absorbs inline the `TECHNICAL-NOTE` level (Solution/Impacted/AS-IS/TO-BE/Validations…) **and** the `Phases`/`Tasks`. Therefore exec sessions do **not** carry a `TECHNICAL-NOTE` or own `TASKS` artifact: the technical detail and progress live in the plan-doc (living). `TASKS` remains as an optional artifact for sessions that need their own internal breakdown.
 
 ---
@@ -51,6 +53,7 @@ Sessions are created by the loops as needed — **one session per run**. The ses
 |---|---|---|
 | [`artifacts-core/`](artifacts-core/) | common to any session | `SESSION` · `TASKS` · `CHECKPOINT` · `BACKLOG` · `SCRIPTS.sql` |
 | [`artifacts-research/`](artifacts-research/) | inline research (any session) | `ANALYSIS-FILE` · `CONCLUSIONS` |
+| [`artifacts-design/`](artifacts-design/) | inline design (PLAN sessions with UI) | `NNN-SPEC-<SLUG>.md` (design SPEC, one per screen) |
 | [`artifacts-exec/`](artifacts-exec/) | `exec` / `quick` session | `DECISION` · `TECHNICAL-NOTE` (schema reference; absorbed by the plan-doc) |
 
 ---
@@ -59,5 +62,5 @@ Sessions are created by the loops as needed — **one session per run**. The ses
 
 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` is ambient — `creating-tools`, not a flow.)
-3. **Spec and plan are documents** (`docs/`), not artifacts — they never live inside a session.
+3. **Spec and plan are documents** (`docs/`), not artifacts — they never live inside a session. *(Do not confuse with the **design SPECs** `NNN-SPEC-<SLUG>.md`: per-screen UI design artifacts of PLAN sessions — see [`artifacts-design/`](artifacts-design/) — which are not the requirement-spec.)*
 4. **DB scripts-only**: the AI **never executes DML/DDL**; migrations stay in `SCRIPTS.sql` (type B) and are delivered via `export-scripts`. Only read-only queries (type A) are executed via MCP.

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

@@ -14,7 +14,7 @@ Who created it and from where:
 
 ## Type
 Session type, **set by the parent loop** (not the user). Authoritative catalog: `../README.md`.
-- `refine` — owns a spec-refine / plan-new loop run (SESSION + CHECKPOINT; + BACKLOG on close)
+- `refine` — owns a spec-refine / plan-new / plan-refine loop run (SESSION + CHECKPOINT; + BACKLOG on close; + `NNN-SPEC-<SLUG>.md` in PLAN sessions with UI — see [`../artifacts-design/`](../artifacts-design/))
 - `exec` — execute work; a single per-run session (PLAN), not one per phase
 - `quick` — lightweight execution (≈ `exec`: single session, single commit) (QUICK)
 

package/skills/w/artifacts/artifacts-design/SPEC.md

@@ -0,0 +1,42 @@
+# NNN-SPEC-<SLUG>.md — design SPEC (UI)
+
+> What it is: the **design specification of ONE screen** (modal, dashboard, form, …), produced by composing the **`ui-design`** capability (built-in default [`ui-spec`](../../roles/ui-spec/SKILL.md)) when the **plan includes UI**. It is a **session artifact** of the PLAN loops (`plan-new-loop` · `plan-refine-loop`) — process-facing, internal — and `plan-exec-loop` reads it as the **design reference** when implementing the UI tasks.
+>
+> **It is NOT the spec.** The requirement-spec (`docs/specs/NNN-spec-<slug>.md`) and the plan remain **documents** (invariant 3). The design SPEC is a different thing: the per-screen UI design detail, ephemeral and process-facing, living inside the session. Spelling disambiguates: `SPEC` (UPPERCASE, artifact) vs `spec` (lowercase, document).
+
+## Naming
+
+`NNN-SPEC-<SLUG>.md`, all UPPERCASE (session-artifact convention):
+
+- `NNN` — sequence **local to the session** (001, 002, … in creation order). Numbered by **the loop**; the CLI is not involved (do not confuse with the global session `NNN` from `aw session-create`, nor with `aw next-number` for `docs/`).
+- `SLUG` — short screen name in UPPER-KEBAB (`[A-Z0-9-]`, ≤ ~4 words).
+- **One screen per file.** Several screens = several SPECs.
+
+Examples: `001-SPEC-MODAL-EXPORT.md` · `002-SPEC-ADMIN-DASHBOARD.md`.
+
+## Schema
+
+Trace header (blockquote) + the [`ui-spec`](../../roles/ui-spec/SKILL.md) Markdown render (same structure, vocabulary and exact render rules; **a single screen**):
+
+```markdown
+> Design SPEC · generated via the ui-design capability
+> Origin: docs/plans/PPP-plan-<slug>.md (· docs/specs/NNN-spec-<slug>.md § UI spec, if present)
+> Design options: material3 · light · es
+> Tasks: T3.2 · T3.3
+
+# Modal Export
+**Tipo**: modal | **Plataforma**: web
+
+## Componentes
+- **Formato** (select)
+- **Rango de fechas** (datePicker)
+- **Exportar** (button)
+- **Cancelar** (link)
+```
+
+## Rules
+
+1. Authored by the **`ui-design`** capability (rebindable via `.workflow/skills.toml`; `off` → the UI gap degrades to human / `Open questions`, like any disabled capability).
+2. The **plan-doc references** the path of the governing SPEC (in its UI Tasks / `Solution`): that reference is the **source of truth** for which SPEC governs each screen. A re-refine that changes a screen produces the updated SPEC **in its own session** (each loop manages the artifacts of ITS session) and re-points the plan reference.
+3. **Derives** from the spec's `## UI spec` section when present: splits it per screen and elevates it to executable detail; a SPEC↔`## UI spec` contradiction is a **gap** (plan↔spec drift). If the spec has no `## UI spec`, it is authored from the `Requirement` via structured-choice (design system, theme, screen ambiguities).
+4. Ephemeral and internal like every artifact: promotion to `docs/` happens **only** via `export-*` (never automatically by the loop).

package/skills/w/commands/README.md

@@ -28,7 +28,7 @@
                             ▼
 ┌─ LAYER 3 · SESSIONS + ARTIFACTS (.workflow/sessions/) ─────────────────┐
 │   Ephemeral, internal. No one invokes this by hand. Process-only.      │
-│   (schema in ../workflow-artifacts/)                                   │
+│   (schema in ../artifacts/)                                            │
 └────────────────────────────────────────────────────────────────────────┘
 
 ╔═ docs/ ZONE — PERMANENT documents, user-facing ════════════════════════╗

package/skills/w/commands/plan-exec.md

@@ -28,6 +28,7 @@ Arranca o retoma `plan-exec-loop` (Layer 2), que ejecuta el trabajo real fase po
 - Lee y actualiza `docs/plans/PPP-plan-<slug>.md` (living doc: estado de fases/tareas).
 - Edita código en las fuentes del workspace (una sola sesión de ejecución para el run; la ejecución sigue siendo fase por fase, solo que no hay sesión por fase).
 - Si crea una herramienta/utilidad, la documenta la skill ambiente `creating-tools` en `docs/tools/` (auto-descubierta; el workflow no la bindea).
+- **Gate de revisión de cierre** en cada límite de fase, **antes de proponer los commits**: re-lee el diff (pasada independiente) aplicando las **convenciones ambientes instaladas** y corrige o difiere hallazgos — nada llega a un commit sin revisar (ver `../loops/plan-exec-loop/SKILL.md` § *Delta 5*).
 - Propone commits por fuente (git-safe: verifica rama, propone, nunca push/--amend/--no-verify).
 - Genera artefactos de sesión (`DECISION`, `SCRIPTS.sql`) en `.workflow/sessions/`.
 - **No exporta** a `docs/scripts`, `docs/manuals`, `docs/diagrams`, `docs/reports` — eso lo hacen los `export-*` como paso aparte.

package/skills/w/commands/plan-new.md

@@ -37,6 +37,10 @@ El skill evalúa `$ARGUMENTS` (los specs viven in place — `docs/specs/NNN-spec
 
 El plan se nombra `docs/plans/PPP-plan-<slug>.md`. El CLI solo devuelve el número `PPP`; el loop arma el nombre completo (slug = kebab-case corto del Requirement: `[a-z0-9-]`, ≤ ~5 palabras / ≤ 40 chars). **No hereda el `NNN` del spec**. El vínculo al spec se establece por referencia (`## Origin` / "Derivado de") en el plan, no por número.
 
+## UI → design SPECs
+
+Si el plan **incluye UI**, el loop compone la capacidad `ui-design` y produce **design SPECs** por pantalla (`NNN-SPEC-<SLUG>.md`) como artefactos de su sesión — las Tasks UI del plan los referencian (ver `../loops/plan-new-loop/SKILL.md` § *Delta 4* y `../artifacts/artifacts-design/SPEC.md`).
+
 ## Plan mode
 
 El skill resuelve el input según las 3 reglas de arriba y describe las acciones del loop que ejecutaría, sin arrancar la iteración.

package/skills/w/commands/plan-refine.md

@@ -43,6 +43,10 @@ El skill detecta el estado previo antes de arrancar, **keyando off el `CHECKPOIN
 3. **Sin avance** (sin CHECKPOINT y el plan **no** tiene `## Refinement decisions`/`## Q&A traceability`) → arranca desde cero leyendo el plan (`PPP-plan-*.md`).
 4. **Ya refinado / re-refine a demanda** (sin CHECKPOINT abierto pero el plan **ya tiene** `## Refinement decisions`/`## Q&A traceability`) → **soportado de primera clase**: mientras el flujo siga en PLAN podés re-correr `/w:plan-refine` sobre el mismo plan **las veces que haga falta** (nuevos requerimientos, cambios de scope, re-lectura). El loop hace `create_or_resume` — localiza la refine session existente (aunque esté cerrada) y la **reabre** en vez de duplicarla — y re-refina leyendo el **plan mismo**; al `Guardar`, edita in place con confirmación.
 
+## UI → design SPECs
+
+Si el refine **toca UI**, el loop compone `ui-design` y produce/actualiza **design SPECs** (`NNN-SPEC-<SLUG>.md`) en su propia sesión — acotado a las pantallas nuevas/cambiadas — y re-apunta las referencias del plan (ver `../loops/plan-refine-loop/SKILL.md` § *Delta 4*).
+
 ## Plan mode
 
 El skill resuelve el estado y describe las acciones que ejecutaría el loop (gaps que cerraría, preguntas que haría), sin arrancar la iteración.

package/skills/w/commands/quick.md

@@ -27,6 +27,7 @@ Para tareas acotadas y directas que no justifican pasar por SPEC ni PLAN. Siempr
 
 - Edita código en las fuentes del workspace.
 - Artefactos mínimos en la sesión (DECISION lazy, commit propuesto).
+- **Gate de revisión de cierre proporcional** antes de proponer el único commit: re-lee el diff aplicando las convenciones ambientes instaladas y corrige o difiere (ver `../loops/quick-loop/SKILL.md` § *Sequence*).
 - **No toca `docs/`** ni exporta nada.
 - **Escala** a SPEC/PLAN si emerge complejidad (muchos archivos, ≥2 fuentes, necesita arquitectura, o el cambio es feature/refactor).
 

package/skills/w/commands/workspace-init.md

@@ -35,5 +35,5 @@ Resuelve las fuentes y describe el scaffolding que crearía, sin escribir archiv
 
 ## Resources
 
-- Design reference: `docs/referencias/workflow-commands/workspace-init.md` (design spec)
+- Design reference: `docs/referencias/workflow-commands/workspace-init.md`
 - Skills config: `docs/referencias/workflow-roles/` (capacidades/roles disponibles y cascada de binding)

package/skills/w/loops/README.md

@@ -91,7 +91,8 @@ spec-refine-loop  ── CHASIS (patrón de referencia: objetivo persistente + v
         ├── plan-refine-loop (heir)  → deltas: refina el plan in place (aux, opcional);
         │                               reusa gap taxonomy + coherence gate de plan-new
         ├── plan-exec-loop   (heir)  → deltas: ejecución real (código/BD/git),
-        │                               una sola session por run, sin auto-export
+        │                               una sola session por run, gate de revisión
+        │                               de cierre pre-commit, sin auto-export
         └── quick-loop       (heir)  → deltas: ceremonia mínima, 1 session,
                                         hereda git/BD/no-export de plan-exec
 ```
@@ -104,7 +105,7 @@ Los loops componen **capacidades por su rol**, no skills concretas; la skill que
 
 | Role | Default built-in | Composed by |
 |---|---|---|
-| `ui-design` | `ui-spec` | `spec-refine-loop` (cuando hay UI) |
+| `ui-design` | `ui-spec` | `spec-refine-loop` (cuando hay 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) |

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

@@ -10,7 +10,10 @@ description: >-
   + CHECKPOINT); git seguro (verifica la rama antes de editar, propone commits por
   fuente, nunca push/--amend/--no-verify); la IA NUNCA ejecuta DML/DDL (las
   migraciones se redactan en SCRIPTS.sql, solo read-only se ejecuta); validación
-  por fase y final (lo dependiente de migración no aplicada se difiere a DBA); y
+  por fase y final (lo dependiente de migración no aplicada se difiere a DBA);
+  gate de revisión de cierre por fase ANTES de proponer commits (re-lectura
+  independiente del diff aplicando las convenciones ambientes instaladas —
+  corrige o difiere; nada llega a un commit sin revisar); y
   SIN auto-export (escribe solo docs/plans; el resto queda como artefacto para
   export-*). Compone git y sql. Lo arranca /w:plan-exec, es reanudable. Invocar
   para implementar un plan ya generado.
@@ -30,7 +33,7 @@ PLAN
 `/w:plan-exec` — **reanudable** (mismo mecanismo del chasis; aquí el resume keya off el checkbox del plan-doc + CHECKPOINT, ver 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.
+`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)).
 
 ## Writes
 - `docs/plans/PPP-plan-<slug>.md` (**read/update**, living doc: estado de fases/tareas, `Open questions`).
@@ -69,13 +72,13 @@ Del chasis [`spec-refine-loop`](../spec-refine-loop/SKILL.md), sin cambios:
 - 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**: actualiza el `CHECKPOINT` (Completed += Phase N, Next = Phase N+1) y propone commits.
+- 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)`).
 
 ## Delta 2 — Git policy: **rama segura + commits propuestos**
 
 - **Antes de editar** archivos de una fuente: verifica rama actual = rama esperada de esa fuente (estilo `branch-check`). Si no coincide → **pausa y resuelve con el humano**; nunca `stash`/`reset --hard`/`checkout -- .`/`clean` sin confirmación por fuente.
-- **Al cerrar una fase** (o al `Cerrar`): **propone commits por fuente** (propose-then-execute, aprobar antes); nunca `push`/`--amend`/`--no-verify`.
+- **Al cerrar una fase** (o al `Cerrar`): **tras pasar el gate de revisión de cierre** (Delta 5), **propone commits por fuente** (propose-then-execute, aprobar antes); nunca `push`/`--amend`/`--no-verify`. Nada llega a un commit propuesto sin revisar.
 - **Commit rechazado**: los cambios **quedan en el working tree** (no se revierten). Se permite reproponer / editar mensaje. Se registra en `CHECKPOINT` + `BACKLOG` que la fase quedó **sin commitear** (reanudable).
 - **Precondición entre fases**: `branch-check` valida *identidad* de rama, **no** *limpieza* del working tree. Antes de iniciar la siguiente fase, el working tree de cada fuente debe estar **limpio** (committeado) o explícitamente **reconocido** como "cambios sin commitear de la fase N" — para no co-mezclar dos fases en un mismo commit.
 
@@ -96,7 +99,18 @@ Distinción por **ejecución**, no por archivo (ver el esquema `SCRIPTS.sql`):
 
 > 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).
 
-## Delta 5 — Completitud / cierre
+## Delta 5 — Gate de revisión de cierre (convenciones, pre-commit)
+
+Tras la validación de la fase y **antes de proponer sus commits** (también en un `Cerrar` anticipado, antes de proponer los commits pendientes), el diff de la fase pasa un **gate de revisión de cierre**:
+
+- **Re-lectura independiente** del diff (subagente o re-lectura limpia — la *verificación independiente* del chasis: no asume correcta la implementación; *only command output counts*).
+- **Aplica las convenciones ambientes instaladas** relevantes al stack tocado (estándares de código/stack, seguridad, revisión de diffs, familias propias del workspace) — el host las **auto-descubre por su `description`**. El workflow **no nombra ni bindea** skills concretas: **crea el momento; las skills instaladas lo llenan** (por eso la revisión **no es un rol** — ver [`../../roles/README.md`](../../roles/README.md)). Sin skills de convenciones instaladas → checklist genérico mínimo: SOLID/early-return, nombres claros, DRY, errores no silenciados, sin secrets/PII, SQL parametrizado, sin código muerto, + las `Validations` del plan.
+- **Hallazgos**: se **corrigen** en el working tree y se **re-corre la validación de la fase** (el gate no reemplaza los tests: los re-verifica tras corregir), o se **difieren justificados** (→ `Open questions` del plan + `BACKLOG`); lo no obvio → `DECISION`. Integridad del gate (chasis): nunca se debilita un check ni se baja una convención para pasar.
+- **Artifact-first + verification-first**: `CHECKPOINT.Next = "review fase N"` antes de la pasada; `SESSION.Success criteria` incluye desde el inicio "cada fase pasó el gate de revisión antes de sus commits".
+
+Recién con el gate en verde se proponen los commits de la fase (Delta 2).
+
+## Delta 6 — Completitud / cierre
 
 - 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`).
@@ -126,8 +140,11 @@ plan-exec-loop(PPP-plan-<slug>.md):
     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
+    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)
@@ -149,7 +166,8 @@ flowchart TD
     DO --> MK["marcar Task - [x] en el PLAN"]
     MK --> T
     T -->|no| VP["validación de fase<br/>(falla→tarea · dep. SQL→diferir)"]
-    VP --> CK["update CHECKPOINT (Completed/Next)"]
+    VP --> RV["gate de revisión de cierre<br/>(diff + convenciones ambientes → corregir/diferir)"]
+    RV --> CK["update CHECKPOINT (Completed/Next)"]
     CK --> CM["proponer commits por fuente"]
     CM -->|aprobado| P
     CM -->|rechazado| RJ["cambios quedan · registrar 'sin commitear'"]
@@ -159,6 +177,6 @@ flowchart TD
 
 ## Convergence / exit
 
-- Plan completo + validación OK (o diferida con handoff) → `Marcar plan done`.
+- 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.

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

@@ -10,7 +10,9 @@ description: >-
   deltas: el plan absorbe inline el nivel TECHNICAL-NOTE
   (Solution/Impacted/AS-IS/TO-BE/Validations…) + Phases/Tasks con estado vivo;
   el research aquí mapea código/impacto (componentes FE/BE/BD, wiring AS-IS,
-  dependencias); y una gap taxonomy propia de planificación. Distingue spec
+  dependencias); una gap taxonomy propia de planificación; y si el plan incluye
+  UI compone la capacidad ui-design para autorar design SPECs por pantalla
+  (NNN-SPEC-<SLUG>.md) como artefactos de su sesión. Distingue spec
   refinado de borrador por la presencia de Refinement decisions/Q&A traceability
   (si faltan → soft-suggest correr spec-refine antes). Lo arranca el comando
   /w:plan-new y es reanudable. Invocar cuando un spec deba convertirse en un plan
@@ -34,7 +36,7 @@ PLAN
 `docs/specs/NNN-spec-*.md` (glob — localiza el spec por número; o la ruta exacta del argumento del comando). **Refinado vs borrador** se distingue por la **presencia** de `## Refinement decisions` / `## Q&A traceability` en el spec: si faltan → **soft-suggest** correr `/w:spec-refine` primero (planificar sobre un spec sólido produce mejores planes), pero el usuario puede proceder.
 
 ## Writes
-`docs/plans/PPP-plan-<slug>.md` (`generate`; **sobrescribe con confirmación** si existe). Solo escribe `docs/plans` — nunca otras carpetas `docs/` ni auto-export.
+`docs/plans/PPP-plan-<slug>.md` (`generate`; **sobrescribe con confirmación** si existe). Solo escribe `docs/plans` — nunca otras carpetas `docs/` ni auto-export. Si el plan **incluye UI**, además produce **design SPECs** (`NNN-SPEC-<SLUG>.md`) como artefactos **de su sesión** (ver *Delta 4* — no son `docs/`, no hay auto-export).
 
 > **slug**: kebab-case corto derivado del Requirement del spec — solo `[a-z0-9-]`, ≤ ~5 palabras / ≤ 40 chars. El CLI solo devuelve el número `PPP`; el loop arma el nombre completo. Para localizar planes, glob `docs/plans/PPP-plan-*.md`.
 
@@ -93,13 +95,18 @@ Reemplaza la gap taxonomy de spec por una orientada a planificación:
 | Deps faltantes | orden no claro | research / humano |
 | Criterios del spec sin cubrir | tareas no trazan a acceptance criteria | la IA deriva + humano confirma |
 | Riesgos sin atender | riesgos técnicos sin mitigar/declarar | humano |
+| UI sin design SPEC *(si aplica)* | el plan incluye UI (FE/pantallas en `Impacted`, `## UI spec` en el spec, o tareas UI) sin `NNN-SPEC-*.md` en la sesión | **capacidad `ui-design`** |
 
 ## Delta 3 — What research investigates here
 
 El research **inline** del chasis se especializa: mapear **código/impacto** — componentes FE/BE/BD afectados, wiring AS-IS, dependencias. Alimenta las secciones `Solution`, `Impacted`, `Current state (AS-IS)`. La regla BD del chasis aplica igual (queries read-only a `SCRIPTS.sql`, MCP elegido vía pregunta de contenido si >1 sin default).
 
+## Delta 4 — Design SPECs (si el plan incluye UI)
+
+El gap **UI sin design SPEC** se resuelve **componiendo** la capacidad **`ui-design`** (default built-in [`ui-spec`](../../roles/ui-spec/SKILL.md); rebindeable vía `.workflow/skills.toml`; `off` → degrada a humano / `Open questions`): autora **un design SPEC por pantalla** como artefacto de la sesión — `NNN-SPEC-<SLUG>.md` (`001-SPEC-MODAL-EXPORT.md`, `002-SPEC-ADMIN-DASHBOARD.md`; numeración local a la sesión, ver [`SPEC.md`](../../artifacts/artifacts-design/SPEC.md)). **Deriva** de la sección `## UI spec` del spec si existe (la parte por pantalla y la eleva a detalle ejecutable); si no, autora desde el `Requirement` (design-system/tema/ambigüedades vía *structured-choice*, cuenta en el batch). Las **Tasks UI del plan referencian** la ruta de su SPEC — esa referencia es la fuente de verdad — y `plan-exec-loop` los lee como referencia de diseño. Es el mismo tercer modo de resolución de gap del chasis (junto a *research* y *humano*).
+
 ## Convergence / exit
 
-Sin gaps materiales → **coherence gate** (read-only) = **`Success criteria` en verde** (*verification-first*; es el "convergence gate" del chasis para PLAN-new): cada `acceptance criterion` del spec **traza** a una fase/tarea, `Final behavior` los cubre, fases XS–S / tareas XS, `deps` sin ciclos, `Impacted` consistente con `Solution`. Lo que falle **vuelve como gap** — la trazabilidad criterio→tarea es una **invariante chequeada**, no una sección aparte. Si pasa → *structured-choice* (contenido: `Guardar plan` / `Preguntar algo más`; flow: `Compactar`/`Cerrar`) → al `Guardar`, escribe `docs/plans/PPP-plan-<slug>.md` (con confirmación si existe) → `finalize` (persiste `CHECKPOINT`, y `BACKLOG` solo si difiere; cierra la session, reporta). `Cerrar` en cualquier momento → `finalize` igual.
+Sin gaps materiales → **coherence gate** (read-only) = **`Success criteria` en verde** (*verification-first*; es el "convergence gate" del chasis para PLAN-new): cada `acceptance criterion` del spec **traza** a una fase/tarea, `Final behavior` los cubre, fases XS–S / tareas XS, `deps` sin ciclos, `Impacted` consistente con `Solution`; y si el plan incluye UI: cada pantalla/tarea UI **traza a su design SPEC** (`NNN-SPEC-*.md`) y los SPECs no contradicen el `## UI spec` del spec (si existe). Lo que falle **vuelve como gap** — la trazabilidad criterio→tarea es una **invariante chequeada**, no una sección aparte. Si pasa → *structured-choice* (contenido: `Guardar plan` / `Preguntar algo más`; flow: `Compactar`/`Cerrar`) → al `Guardar`, escribe `docs/plans/PPP-plan-<slug>.md` (con confirmación si existe) → `finalize` (persiste `CHECKPOINT`, y `BACKLOG` solo si difiere; cierra la session, reporta). `Cerrar` en cualquier momento → `finalize` igual.
 
 > **Después de generar:** el plan puede ir directo a `plan-exec`, o —si surgen cambios antes de ejecutar (nuevos requerimientos, ajustes de alcance)— pasar por [`plan-refine-loop`](../plan-refine-loop/SKILL.md) (`/w:plan-refine`, auxiliar y **no obligatorio**), que lo refina in place.

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

@@ -10,7 +10,9 @@ description: >-
   difiere). Es a plan-new lo que spec-refine es a spec-new: edita el plan-doc in
   place (no genera uno nuevo). Reusa la gap taxonomy y el coherence gate de
   plan-new-loop; agrega Refinement decisions/Q&A traceability al plan (traza, sin
-  contrato de gating: plan-exec corre cualquier plan). Lo arranca /w:plan-refine y
+  contrato de gating: plan-exec corre cualquier plan). Si el refine toca UI,
+  compone la capacidad ui-design y produce/actualiza design SPECs por pantalla
+  (NNN-SPEC-<SLUG>.md) en su propia sesión. Lo arranca /w:plan-refine y
   es reanudable + re-corrible a demanda. Invocar cuando un plan ya generado deba
   ajustarse antes de ejecutarlo.
 ---
@@ -37,7 +39,7 @@ PLAN
 `docs/plans/PPP-plan-*.md` (glob — localiza el plan por número; o la ruta exacta del argumento del comando). **Siempre el plan mismo**: este loop lo edita in place, no hay un archivo "refined" aparte.
 
 ## Writes
-Actualiza `docs/plans/PPP-plan-<slug>.md` **in place** (cuando el usuario elige `Guardar plan refinado`): completa/ajusta secciones y **agrega** `## Refinement decisions` + `## Q&A traceability`. Como sobrescribe un doc existente, **con confirmación** del usuario. Solo escribe `docs/plans` — nunca otras carpetas `docs/` ni auto-export.
+Actualiza `docs/plans/PPP-plan-<slug>.md` **in place** (cuando el usuario elige `Guardar plan refinado`): completa/ajusta secciones y **agrega** `## Refinement decisions` + `## Q&A traceability`. Como sobrescribe un doc existente, **con confirmación** del usuario. Solo escribe `docs/plans` — nunca otras carpetas `docs/` ni auto-export. Si el refine **toca UI**, además produce/actualiza **design SPECs** (`NNN-SPEC-<SLUG>.md`) como artefactos **de su propia sesión** (ver *Delta 4* — no son `docs/`, no hay auto-export).
 
 ## Inherits
 
@@ -69,7 +71,7 @@ Cada duda preguntada al humano + la respuesta elegida.
 
 ## Delta 2 — Gap taxonomy (de "plan")
 
-Reusa **íntegra** la gap taxonomy de [`plan-new-loop`](../plan-new-loop/SKILL.md) (§ *Delta 2*): Approach/Solution vago, componentes sin identificar, wiring AS-IS desconocido, fase muy grande, tarea no atómica, deps faltantes, criterios del spec sin cubrir, riesgos sin atender. **Diferencia de foco:** plan-new **construye** el plan desde cero; plan-refine **detecta qué cambió** respecto del plan ya escrito (o respecto del spec, si el spec se re-refinó) y cierra **esos** gaps — típicamente menos y más localizados. Un gap extra propio del re-refine:
+Reusa **íntegra** la gap taxonomy de [`plan-new-loop`](../plan-new-loop/SKILL.md) (§ *Delta 2*): Approach/Solution vago, componentes sin identificar, wiring AS-IS desconocido, fase muy grande, tarea no atómica, deps faltantes, criterios del spec sin cubrir, riesgos sin atender, UI sin design SPEC. **Diferencia de foco:** plan-new **construye** el plan desde cero; plan-refine **detecta qué cambió** respecto del plan ya escrito (o respecto del spec, si el spec se re-refinó) y cierra **esos** gaps — típicamente menos y más localizados. Un gap extra propio del re-refine:
 
 | Gap | Signal | Resolved by |
 |---|---|---|
@@ -79,6 +81,10 @@ Reusa **íntegra** la gap taxonomy de [`plan-new-loop`](../plan-new-loop/SKILL.m
 
 Igual que plan-new (mapea código/impacto: componentes FE/BE/BD, wiring AS-IS, deps), pero **acotado al delta**: re-verifica solo lo que el cambio toca (no re-mapea todo el plan). Regla BD del chasis igual (read-only a `SCRIPTS.sql`, MCP vía pregunta si >1 sin default).
 
+## Delta 4 — Design SPECs (si el refine toca UI)
+
+Mismo mecanismo que [`plan-new-loop`](../plan-new-loop/SKILL.md) (§ *Delta 4*: capacidad **`ui-design`** → `NNN-SPEC-<SLUG>.md` por pantalla, ver [`SPEC.md`](../../artifacts/artifacts-design/SPEC.md)), **acotado al delta**: solo las pantallas **nuevas o cambiadas** por el refine reciben design SPEC. El SPEC actualizado se escribe en **la sesión propia** del plan-refine (cada loop maneja los artefactos de SU sesión — no edita los de la sesión de plan-new) y el plan **re-apunta** la referencia de la Task UI al SPEC vigente. Pantallas no tocadas conservan su SPEC original.
+
 ## Compact / resume
 
 El resume **keya off el `CHECKPOINT`** de la refine session, no de un archivo "refined". Tres casos al ejecutar `/w:plan-refine` sobre un plan:
@@ -91,4 +97,4 @@ El resume **keya off el `CHECKPOINT`** de la refine session, no de un archivo "r
 
 ## Convergence / exit
 
-Sin gaps materiales → **coherence gate** (read-only) = **`Success criteria` en verde** (*verification-first*; el "convergence gate" del chasis para PLAN, mismo que plan-new): cada `acceptance criterion` del spec **traza** a una fase/tarea, `Final behavior` los cubre, fases XS–S / tareas XS, `deps` sin ciclos, `Impacted` consistente con `Solution`, y —propio del re-refine— **el plan quedó realineado** con lo que cambió. Lo que falle **vuelve como gap**. Si pasa → *structured-choice* (contenido: `Guardar plan refinado` / `Preguntar algo más`; flow: `Compactar`/`Cerrar`) → al `Guardar`, edita `docs/plans/PPP-plan-<slug>.md` in place (con confirmación) + inserta `Refinement decisions`/`Q&A traceability` → `finalize` (persiste `CHECKPOINT`; `BACKLOG` solo si difiere; cierra la session, reporta). `Cerrar` en cualquier momento → `finalize` igual.
+Sin gaps materiales → **coherence gate** (read-only) = **`Success criteria` en verde** (*verification-first*; el "convergence gate" del chasis para PLAN, mismo que plan-new): cada `acceptance criterion` del spec **traza** a una fase/tarea, `Final behavior` los cubre, fases XS–S / tareas XS, `deps` sin ciclos, `Impacted` consistente con `Solution`, si hay UI cada pantalla/tarea UI **traza a su design SPEC vigente**, y —propio del re-refine— **el plan quedó realineado** con lo que cambió. Lo que falle **vuelve como gap**. Si pasa → *structured-choice* (contenido: `Guardar plan refinado` / `Preguntar algo más`; flow: `Compactar`/`Cerrar`) → al `Guardar`, edita `docs/plans/PPP-plan-<slug>.md` in place (con confirmación) + inserta `Refinement decisions`/`Q&A traceability` → `finalize` (persiste `CHECKPOINT`; `BACKLOG` solo si difiere; cierra la session, reporta). `Cerrar` en cualquier momento → `finalize` igual.

package/skills/w/loops/quick-loop/SKILL.md

@@ -9,7 +9,9 @@ description: >-
   como log vivo: CHECKPOINT siempre, BACKLOG solo si difiere) y de plan-exec-loop
   (git seguro: rama esperada antes de editar + commit propuesto, nunca
   push/--amend/--no-verify; la IA nunca ejecuta DML, migraciones a SCRIPTS.sql;
-  sin auto-export). Sus deltas: sin fases ni plan-doc (el prompt ES la tarea),
+  sin auto-export; gate de revisión de cierre proporcional: re-lee el diff con
+  las convenciones ambientes instaladas y corrige antes de proponer el commit).
+  Sus deltas: sin fases ni plan-doc (el prompt ES la tarea),
   una sola session ligera (<slug>-quick), un solo commit; y escalación con
   handoff si la tarea crece (propone subir a SPEC/PLAN dejando el código a
   medias como contexto). NO toca docs/. Lo arranca /w:quick y es reanudable.
@@ -44,7 +46,7 @@ QUICK
 ## Inherits
 
 - del **chasis** [`spec-refine-loop`](../spec-refine-loop/SKILL.md): **objetivo persistente** (acá el más directo: el prompt *es* el objetivo) + **verification-first** (`SESSION.Success criteria` proporcional), gap-driven (mínimo), *structured-choice* ≤3 preguntas de contenido + 1 control `flow` (`Compactar`/`Cerrar`) (capacidad del arnés — ver [`../../harness/SKILL.md`](../../harness/SKILL.md); en Claude Code es `AskUserQuestion`), `research` **inline** + regla BD read-only (pregunta MCP si >1 sin default → `SCRIPTS.sql` → ejecuta read-only), compact/resume, **artefactos como log vivo (ciclo artifact-first)** (`CHECKPOINT` siempre; `BACKLOG` solo si difiere).
-- de [`plan-exec-loop`](../plan-exec-loop/SKILL.md): **git** (rama segura antes de editar + commit propuesto; nunca `push`/`--amend`/`--no-verify`), **BD** (la IA nunca ejecuta DML; migraciones → `SCRIPTS.sql` de la session), **sin auto-export** (no toca otras carpetas `docs/`).
+- de [`plan-exec-loop`](../plan-exec-loop/SKILL.md): **git** (rama segura antes de editar + commit propuesto; nunca `push`/`--amend`/`--no-verify`), **BD** (la IA nunca ejecuta DML; migraciones → `SCRIPTS.sql` de la session), **sin auto-export** (no toca otras carpetas `docs/`), y el **gate de revisión de cierre** (§ *Delta 5* de plan-exec) en versión **proporcional**: antes de proponer el único commit, re-lectura del diff aplicando las convenciones ambientes instaladas → corregir o diferir justificado.
 
 ## Composes
 
@@ -56,7 +58,7 @@ QUICK
 
 - **Sin fases, sin plan-doc**: el prompt **es** la tarea (una sola unidad). No hay roadmap.
 - **Verification-first proporcional** (ceremonia mínima): aun acá se **siembra el check antes**, del tamaño de la tarea. Código: un test (repro del bug → fix) o "build/lint/tests existentes siguen verdes" (chore). **Análisis/diseño**: una **rúbrica falsable corta**, *ratificada por el usuario* antes de perseguirla. Es el `SESSION.Success criteria` del run (ver [chasis § Verification-first](../spec-refine-loop/SKILL.md)).
-- **Una sola session**. **Un solo commit** propuesto al final (solo si hubo cambios de código).
+- **Una sola session**. **Un solo commit** propuesto al final (solo si hubo cambios de código), **tras el gate de revisión de cierre proporcional** (heredado de plan-exec § *Delta 5*): re-lectura del diff + convenciones ambientes; corregir o diferir; nada llega al commit sin revisar.
 - **Escalación + handoff**: si la tarea crece (muchos archivos / ≥2 fuentes / necesita arquitectura) → propone subir a **SPEC/PLAN**. Si el usuario acepta:
   - el **código ya editado queda** en el working tree (no se revierte) **y se registra** en `CHECKPOINT` + `BACKLOG` ("cambios sin commitear en `<fuente>` — código a medias; decidir commit/descartar al retomar") — reusando **ambas** mitades del patrón "commit rechazado" de plan-exec (no revertir **y** registrar lo sin commitear). Crítico en la rama **SPEC**, que no retoma el working tree;
   - la session quick va a `finalize`, persistiendo `CHECKPOINT` + `BACKLOG` con un **puntero** al spec/plan sembrado (Followups: "escalado a `docs/specs/NNN` o `docs/plans/PPP` — retomar ahí");
@@ -91,7 +93,10 @@ quick-loop(prompt):
     si la tarea CRECE → proponer escalar a SPEC/PLAN
         si acepta → handoff (avance queda; BACKLOG→spec/plan sembrado) → goto finalize
   convergence gate: Success criteria en verde                # tests verdes si código · rúbrica satisfecha si análisis/diseño
-  si hubo cambios de código → proponer commit (aprobar antes)   # nunca push/amend/--no-verify
+  si hubo cambios de código:
+    gate de revisión de cierre (proporcional):               # re-lectura del diff + convenciones ambientes instaladas
+        hallazgos → corregir (re-validar) ó diferir justificado (BACKLOG)
+    proponer commit (aprobar antes)                          # nunca push/amend/--no-verify; solo tras el gate
   structured_choice(contenido: [Cerrar tarea, Preguntar algo más], flow: [Compactar, Cerrar])
 finalize: CHECKPOINT (DESPUÉS: Pending→Completed) + BACKLOG (solo si queda algo diferido) + cerrar session + reportar
 ```
@@ -106,14 +111,15 @@ flowchart TD
     GROW -->|sí| ESC["escalar a SPEC/PLAN<br/>avance queda · BACKLOG→spec/plan sembrado"]
     ESC --> FIN
     GROW -->|no| V["convergence gate:<br/>Success criteria en verde"]
-    V --> CM["si hubo código → proponer commit (aprobar)"]
+    V --> RV["si hubo código → gate de revisión de cierre<br/>(diff + convenciones ambientes → corregir/diferir)"]
+    RV --> CM["proponer commit (aprobar)"]
     CM --> Q["structured-choice[Cerrar · Preguntar más]<br/>flow[Compactar · Cerrar]"]
     Q --> FIN["finalize: CHECKPOINT + BACKLOG + cerrar"]
 ```
 
 ## Convergence / exit
 
-- **Success criteria en verde** (proporcional) + commit propuesto si hubo código (o aprobado saltarlo) → `Cerrar`.
+- **Success criteria en verde** (proporcional) + gate de revisión de cierre pasado y commit propuesto si hubo código (o aprobado saltarlo) → `Cerrar`.
 - `Cerrar`/`Compactar` (control `flow`) → persiste `CHECKPOINT` + `BACKLOG` (reanudable).
 - **Sin export**: nada va a `docs/`. Si algo amerita preservarse → se promueve aparte vía `export-*`, o se escala a SPEC/PLAN.
 

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

@@ -123,6 +123,8 @@ El **CLI es dueño del número**: `aw session-create` antepone un `NNN` **global
 
 El gap **UI sin especificar** (cuando el requerimiento involucra UI; ver *Gap taxonomy*) se resuelve **componiendo** la capacidad **`ui-design`** (default built-in `ui-spec`; rebindeable vía `.workflow/skills.toml`): autora el UI spec nativamente (estructura, vocabulario, formato Markdown). Es un tercer modo de resolución de gap (junto a *research* y *humano*): el loop aporta la iteración/Q&A que el viejo servicio no tenía (design-system, tema, variantes, desambiguación) **vía la misma structured-choice**, y lo integra como sección `## UI spec` del spec.
 
+> **Dos niveles de la misma capacidad:** aquí (SPEC) produce la sección `## UI spec` del spec — el *qué* de la UI, grano grueso. En PLAN, `plan-new-loop`/`plan-refine-loop` componen la **misma** capacidad para producir **design SPECs por pantalla** (`NNN-SPEC-<SLUG>.md`, artefactos de su sesión — ver [`SPEC.md`](../../artifacts/artifacts-design/SPEC.md)), derivados de esta sección si existe.
+
 Otras capacidades transversales que el chasis usa siempre: `research` (research **inline**, ver abajo), `sql` (regla BD en research). Todas se resuelven por config; `off` → el loop sigue sin la capacidad y, si era necesaria, lo dice o pregunta. La **prosa del spec** sigue las convenciones de redacción **ambientes** (el host auto-aplica una skill de writing instalada si está presente), no un rol compuesto.
 
 > **Convenciones ambientes (no roles).** Los estándares de código, testing, redacción **y la creación de herramientas** (`creating-tools`) **no son roles** del workflow ni se bindean: son **skills standalone que el host auto-descubre por su `description`** y aplica cuando son relevantes. El workflow es **indiferente** (no las lee ni las busca). Familias útiles viven en plugins del marketplace (`dev-conventions`, `tool-builder`), pero el workflow **no depende** de ellos.

package/skills/w/roles/README.md

@@ -12,7 +12,7 @@ All 6 roles, their built-in defaults, their tier, and which loops/exports compos
 
 | Role | Default built-in | Tier | Composed by |
 |---|---|---|---|
-| `ui-design` | [`ui-spec`](ui-spec/SKILL.md) | must | `spec-refine-loop` (when requirement involves UI) |
+| `ui-design` | [`ui-spec`](ui-spec/SKILL.md) | must | `spec-refine-loop` (when requirement involves UI) · `plan-new-loop` / `plan-refine-loop` (per-screen design SPECs) |
 | `sql` | `sql` | must | inline research · `plan-exec-loop` · `quick-loop` · `export-scripts` |
 | `git` | `git` | must | `plan-exec-loop` · `quick-loop` |
 | `research` | [`research`](research/SKILL.md) | should | all loops (on-demand investigation) |
@@ -24,6 +24,8 @@ All 6 roles, their built-in defaults, their tier, and which loops/exports compos
 - `should` — loaded on-demand; active by default but lower priority to override.
 
 > **Convenciones ambientes (no roles).** Los estándares de código, testing, redacción **y la creación de herramientas** (`creating-tools`) **no son roles** del workflow ni se bindean: son **skills standalone que el host auto-descubre por su `description`** y aplica cuando son relevantes. El workflow es **indiferente** (no las lee ni las busca). Familias útiles viven en plugins del marketplace (`dev-conventions`, `tool-builder`), pero el workflow **no depende** de ellos.
+>
+> **La revisión de cierre tampoco es un rol** (decisión deliberada — se evaluó y descartó un rol `conventions`/`rules`/`review`): el **gate de revisión de cierre** de `plan-exec-loop`/`quick-loop` (pre-commit) es un **paso del loop**; el loop crea el **momento** y las convenciones ambientes instaladas lo llenan. Un rol que "señale las skills del marketplace" re-acoplaría lo que esta extracción desacopló.
 
 ---
 

package/skills/w/roles/ui-spec/SKILL.md

@@ -5,9 +5,12 @@ description: >-
   requirement, author a structured, framework-agnostic screen specification as
   **Markdown** (single output format). Knows the conceptual screen structure, the
   kind/region vocabulary, the authoring rules, design-system / theme / variant
-  handling, and the exact Markdown render format. Use when a loop is refining a spec
-  that involves screens, forms, dashboards, modals or any UI surface — primarily
-  `spec-refine-loop`. Recycled from the `ui-spec-generator` service.
+  handling, and the exact Markdown render format. Two landing zones, same render:
+  in SPEC (`spec-refine-loop`) it authors the `## UI spec` section of the spec doc;
+  in PLAN (`plan-new-loop`/`plan-refine-loop`) it authors per-screen **design
+  SPECs** (`NNN-SPEC-<SLUG>.md`) as session artifacts. Use when a loop is refining
+  a spec or building/refining a plan that involves screens, forms, dashboards,
+  modals or any UI surface. Recycled from the `ui-spec-generator` service.
 ---
 
 # ui-spec — UI spec authoring
@@ -22,13 +25,18 @@ Dado un requerimiento de UI, autorar una **descripción estructurada en Markdown
 
 ## Composed by
 
-La carga el **`spec-refine-loop`** (ver `../../loops/spec-refine-loop/SKILL.md`) al resolver el gap **UI sin especificar** (cuando el requerimiento involucra UI). El loop aporta lo que el servicio viejo no tenía:
+Dos niveles, misma capacidad:
+
+- **`spec-refine-loop`** (ver `../../loops/spec-refine-loop/SKILL.md`) — al resolver el gap **UI sin especificar** (cuando el requerimiento involucra UI): autora la sección `## UI spec` **del spec** (el *qué* de la UI, pantallas a grano grueso).
+- **`plan-new-loop` · `plan-refine-loop`** (ver `../../loops/plan-new-loop/SKILL.md` § *Delta 4*) — al resolver el gap **UI sin design SPEC** (cuando el **plan incluye UI**): autora **design SPECs** por pantalla (`NNN-SPEC-<SLUG>.md`) como **artefactos de la sesión de PLAN** (ver `../../artifacts/artifacts-design/SPEC.md`); derivan de `## UI spec` si existe.
+
+En ambos, el loop aporta lo que el servicio viejo no tenía:
 
 - **Pregunta al humano** (design-system, tema, ambigüedades de pantalla) vía *structured-choice* (capacidad del arnés — ver `../../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**.
 - **Itera** gap-driven hasta converger.
 - Ofrece **variantes** y **cura** el resultado.
 
-Cualquier loop podría componerla; el caso primario es SPEC. La descripción Markdown aterriza como una sección dentro del documento spec (`docs/specs/NNN-spec-<slug>.md`) — nunca como artefacto suelto (invariante 3: el spec es un documento).
+Cualquier loop podría componerla; los casos primarios son SPEC y PLAN. En SPEC, la descripción aterriza como sección del documento spec (`docs/specs/NNN-spec-<slug>.md`) — el spec sigue siendo un documento (invariante 3). En PLAN aterriza como **design SPECs** (artefactos de sesión) — que **no** son el requirement-spec: son el detalle de diseño por pantalla, de proceso.
 
 ## Knowledge
 
@@ -114,9 +122,16 @@ Si el humano no responde, asumir el caso más simple coherente con la descripci
 - **Registros** (table)
 ```
 
-## Output — sección `## UI spec` dentro del spec (`docs/specs/NNN-spec-<slug>.md`)
+## Output — dos aterrizajes, un solo formato (Markdown)
+
+**Salida en un solo formato: Markdown.** La escribe el loop (no esta skill por sí sola). El **render es el mismo** en ambos niveles; cambia dónde aterriza, según el loop que compone:
+
+| Loop que compone | Aterriza en | Grano |
+|---|---|---|
+| `spec-refine-loop` | sección `## UI spec` **del spec** (`docs/specs/NNN-spec-<slug>.md`) — documento, in place | todas las pantallas del requerimiento, grano grueso |
+| `plan-new-loop` · `plan-refine-loop` | **design SPECs** `NNN-SPEC-<SLUG>.md` — artefactos en la **sesión de PLAN** (uno **por pantalla**, con encabezado de traza; ver `../../artifacts/artifacts-design/SPEC.md`) | una pantalla por archivo, detalle ejecutable |
 
-**Salida en un solo formato: Markdown.** La escribe el loop (no esta skill por sí sola). Encabezar la sección con las opciones de diseño elegidas (design system, tema, idioma) en una línea. Luego el render Markdown, con estas reglas exactas (recicladas del `MarkdownFormatter`):
+Encabezar la sección (o el encabezado de traza del SPEC) con las opciones de diseño elegidas (design system, tema, idioma) en una línea. Luego el render Markdown, con estas reglas exactas (recicladas del `MarkdownFormatter`):
 
 - `# {nombre}`
 - `**Tipo**: {tipo} | **Plataforma**: {plataforma}`