@tacuchi/agent-workflow-cli 15.1.0 → 15.2.0

package/package.json

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

@@ -78,7 +78,16 @@ Antes de cualquier loop, la IA resuelve su **contexto operativo** en **cada prom
 | **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) |
 
-**Regla de continuidad:** el **comando** señala "nueva línea de trabajo" (sesión nueva) — **salvo re-correr el mismo comando sobre la misma entrada** (ej. `/w:spec-refine` sobre el mismo spec), que **no** abre otra línea: `create_or_resume` localiza la sesión de ese flujo (por descriptor + `## Origin`) y la **reanuda o reabre** (quita `.closed`), sin duplicarla; un **prompt sin comando** es "sigo en la misma" → por default continúa/reabre la más reciente (la *última iniciada*); solo si es claramente no-relacionado ofrece elegir (`continuar NNN` | `trabajo nuevo`) o cae a "sin flujo". Convergencia cierra la sesión; un prompt relacionado posterior la **reabre** (el resume quita `.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); ver `loops/quick-loop/SKILL.md` para el caso QUICK. **Excepción consentida:** la **escalación aceptada** dentro de un loop (ej. quick → SPEC) también 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.
+**Regla de continuidad** (fuente única — el chasis y los loops referencian acá):
+
+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`).
+
+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`).
 
 ### The commands (`/w:` namespace)
 
@@ -93,7 +102,7 @@ Antes de cualquier loop, la IA resuelve su **contexto operativo** en **cada prom
 
 ### 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 diseño son su propia categoría —`workflow-skills/`, aparte de los comandos de flow—; en el bundle se empaquetan bajo `commands/` para que `/w:` las invoque.)
+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/`.)*
 
 - `/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`.

package/skills/w/artifacts/README.md

@@ -19,7 +19,7 @@ Central distinction of the model:
 
 > 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.
 
-> **Routing by operating context.** *Where* an artifact is written is decided by the operating context (see [`../SKILL.md`](../SKILL.md) § *Contexto operativo*): **inside a flow** → the **active/continued** session — a prompt with no command edits the `SCRIPTS.sql` (or `DECISION`, …) of the **most recent** session, it does not spawn a new one; **in a workspace but with no flow** → directly into `docs/` by convention + numbering (`aw next-number`), since there is no session to hold it (and it is **not** auto-export); **no workspace** → the AI is free (vanilla). Session→`docs/` promotion is still **only** via `export-*`.
+> **Routing by operating context** (canonical rules: [`../SKILL.md`](../SKILL.md) § *Contexto operativo*): inside a flow → the **active/continued** session (a prompt with no command edits the most recent session's artifacts); workspace without flow → `docs/` by convention + numbering; no workspace → vanilla. Session→`docs/` promotion is still **only** via `export-*`.
 
 ---
 
@@ -58,9 +58,9 @@ Sessions are created by the loops as needed — **one session per run**. The ses
 
 ---
 
-## Invariants (hard rules — do not break)
+## Invariants (hard rules — canonical list: [`../SKILL.md`](../SKILL.md) § *The 6 hard invariants*)
 
-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. *(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.
+1. **No auto-export**: only `export-*` promotes to `docs/`, explicitly.
+2. **Each flow touches only its `docs/` folders**: SPEC→`specs` · PLAN→`plans` · QUICK→none.
+3. **Spec and plan are documents**, never session artifacts. *(Design SPECs `NNN-SPEC-<SLUG>.md` are a different thing: per-screen UI artifacts of PLAN sessions — [`artifacts-design/`](artifacts-design/).)*
+4. **DB scripts-only**: never execute DML/DDL; migrations (type B) stay in `SCRIPTS.sql` and ship via `export-scripts`; only read-only queries (type A) run via MCP.

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

@@ -21,10 +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 when the session is created (**verification-first** — generalized TDD; see [`../../loops/CHASSIS.md`](../../loops/CHASSIS.md) § Verification-first): a checklist `[ ]` of **falsifiable** items (that *can* fail) defining "done". The loop **persists until they are all green** (it is the *persistent-objective* condition); `CHECKPOINT.Pending/Completed` tracks the **red→green** progress. Two forms:
-
-- **Executable** (code/script/fix): **runnable** tests/checks (unit, build, lint, bug repro) — literal TDD. May **reference** the repo's tests rather than copy them.
-- **Rubric** (analysis/design and other non-executable deliverables): items checked by **inspection** (e.g. "identifies every affected site with `file:line`"; "each decision: rationale + ≥1 alternative"). For **subjective** deliverables the AI **proposes** the rubric and the **human ratifies** it before pursuing it.
-
-> **Spec/plan** may **reference** the document's acceptance criteria instead of duplicating them. **Research** is the original particular case: its checklist marks the research concluded.
-> **If an item cannot be met** (no evidence, DB unavailable, irresolvable): it closes as `inconcluso` with a reason and the loop **degrades** (asks the human or defers to `Open questions`/`BACKLOG`) — never spinning in place.
+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*.

package/skills/w/artifacts/artifacts-exec/TECHNICAL-NOTE.md

@@ -1,62 +1,24 @@
 # TECHNICAL-NOTE.md — technical design note (schema reference)
 
-> **Model note:** in PLAN these sections live **inline in the plan-doc** (`docs/plans/PPP-plan.md`, rich plan, in `plan-new-loop`), not as an exec-session artifact. This file is kept as a reference of the technical schema that the plan absorbs — in PLAN **it is not created** as a session artifact (the plan-doc carries it). It remains available only for a `quick` session that needs scoped technical context without a plan-doc.
+> **Model note:** in PLAN these sections live **inline in the plan-doc** (rich plan — `plan-new-loop` § *Delta 1*); this artifact **is not created** in PLAN sessions. It remains only for a `quick` session that needs scoped technical context without a plan-doc.
 
 ## Solution
-Technical/functional explanation of how the solution will be implemented.
+How it will be implemented (technical/functional).
 
 ## Impacted
-Impacted components:
-- Frontend
-- Backend
-- Database (schemas/tables/functions)
-- APIs (controllers/endpoints)
-- Integrations with external systems
+Frontend · Backend · Database (schemas/tables/functions) · APIs · external integrations.
 
 ## Dependencies
-Dependencies: sessions / documents / projects / sources / databases, etc.
+Sessions / documents / sources / databases.
 
 ## Current State
-Simple representation of the wiring or cabling (interfaces and methods) — AS-IS behavior.
-
-Example:
-```
-ContratoEfectivoData.demo()
-        │
-        ▼
-ContratoTemplateRenderer
-   (iface)
-        │ @Service impl
-        ▼
-ThymeleafContratoTemplateRenderer ──── reads ──> templates/contratos/efectivo.html
-        │ (returns String HTML)
-        ▼
-PreviewController.efectivoHtml()  ──> respond TEXT_HTML
-              │
-              └─> efectivoPdf() ─> PdfRenderer (iface @Qualifier("chromePdfRenderer"))
-                                            │ @Service impl
-                                            ▼
-                                       CdpPdfRenderer  ──> Chrome headless via CDP
-                                                              │
-                                                              ▼
-                                                       respond APPLICATION_PDF
-```
+AS-IS wiring (interfaces and methods), brief.
 
 ## Target State
-Simple representation of the wiring or cabling (interfaces and methods) — TO-BE behavior.
+TO-BE wiring, brief.
 
 ## Final Behavior
-How the entire flow should behave at the end (must be aligned with the requirements and acceptance/success criteria in SESSION.md).
-
-Example:
-The user must be able to recover their password via OTP to their mobile number and the mobile number must be saved in the user's data:
-1. [User] Accesses the login screen
-2. [User] Clicks [Forgot Password]
-3. [System] Shows a window to enter mobile number
-4. [User] Enters mobile number
-5. [System] Sends OTP via SMS
-6. [System] Confirms OTP
-7. [System] Saves the mobile number and associates it with the [User]
+How the flow behaves end-to-end — aligned with the acceptance/success criteria in `SESSION.md`.
 
 ## Impact / Risks
 Technical impacts and risks.
@@ -65,17 +27,10 @@ Technical impacts and risks.
 Assumptions.
 
 ## Estimated Time
-Time estimates for [Development] and [Internal Testing].
-The work week has 5 days (Monday–Friday only).
-Size scale XS/S/M/L/XL:
-- XS -> 1 day or less
-- S  -> 1 to 2 days
-- M  -> 3 to 5 days
-- L  -> 6 to 10 days
-- XL -> More than 10 days
+XS–XL sizing (development + internal testing); scale defined in the plan schema (`plan-new-loop` § *Delta 1*).
 
 ## Validations
 Validations, constraints, business-specific logic.
 
 ## Open Questions
-Pending items, doubts, open questions.
+Pending items, doubts.

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

@@ -35,7 +35,7 @@ El skill evalúa `$ARGUMENTS` (los specs viven in place — `docs/specs/NNN-spec
 
 ## Notas de numeración
 
-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.
+El plan se nombra `docs/plans/PPP-plan-<slug>.md`. `aw next-number docs/plans` devuelve JSON (campo `next` = `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
 

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

@@ -23,7 +23,7 @@ Genera `docs/specs/NNN-spec-<slug>.md` en una sola pasada a partir del prompt en
 >
 > La investigación a profundidad (cerrar gaps, mapear código, consultar BD, research autónomo) es trabajo de **`spec-refine`**, no de aquí.
 
-1. Ejecutar `aw next-number docs/specs` para obtener `NNN` (única tool de shell necesaria). El CLI solo devuelve el número; el slug lo arma este comando.
+1. Ejecutar `aw next-number docs/specs` (única tool de shell necesaria): devuelve JSON — usá el campo `next` como `NNN`. El slug lo arma este comando.
 2. Derivar el `<slug>`: kebab-case corto del Requirement — solo `[a-z0-9-]`, ≤ ~5 palabras / ≤ 40 chars.
 3. Crear `docs/specs/NNN-spec-<slug>.md` parafraseando `$ARGUMENTS` en el esquema de borrador (ver abajo). Lectura del repo: opcional y mínima (p. ej. un archivo que el usuario citó) — nunca un barrido ni research.
 4. Mostrar el archivo generado y el próximo paso sugerido (`/w:spec-refine docs/specs/NNN-spec-<slug>.md`).

package/skills/w/loops/CHASSIS.md

@@ -16,19 +16,11 @@ Los **5 loops** corren este motor; cada uno agrega solo sus deltas:
 
 Un loop **es un objetivo persistente**: existe para cumplir el `SESSION.Objective` declarado al arrancar, y **no se considera terminado hasta que el convergence gate confirma que el objetivo se cumplió**. La iteración gap-driven es el *método*; los artefactos son el *registro*; el objetivo persistente es el *frame* que los gobierna.
 
-Está **modelado en cómo se comporta el `/goal` de Claude Code** (declarás un objetivo, el agente no para hasta cumplirlo, auto-completa al cumplirse, con corte explícito para abortar antes) pero como **doctrina agnóstica, no una dependencia del host**: el "no parar hasta converger" lo sostiene el propio loop (su `repeat:` + el convergence gate), no un Stop hook del arnés — ningún host necesita `/goal`. Y, a diferencia del `/goal` pelado, **deja registro durable** (artifact-first) que sobrevive compactación y resume.
+Es **doctrina agnóstica**, no una dependencia del host: el "no parar hasta converger" lo sostiene el propio loop (su `repeat:` + el convergence gate), no un hook del arnés — y **deja registro durable** (artifact-first) que sobrevive compactación y resume. *(Racional y análogo con el `/goal` de Claude Code: ver diseño, `workflow-loops/chassis.md`.)*
 
-| Comportamiento de `/goal` (ejemplo) | Análogo agnóstico en el loop |
-|---|---|
-| declarar el objetivo | `SESSION.Objective` |
-| no parar hasta cumplirlo | `repeat:` gap-driven hasta `gaps == ∅` |
-| objetivo cumplido → auto-clear | **convergence gate** pasa → `finalize` |
-| `/goal clear` (abortar antes) | control `flow` `Cerrar` |
-| la directiva sobrevive el contexto | `CHECKPOINT` + resume (compactación **y próximo prompt**) |
+> Cada heir instancia el frame: `spec-refine` persigue el spec; `plan-new`/`plan-refine` el plan hasta su gate; `plan-exec` el plan hasta su validación final; `quick-loop` es la encarnación más directa (el prompt *es* el objetivo).
 
-> Cada heir instancia el frame: `spec-refine` persigue el spec y `plan-new`/`plan-refine` el plan hasta su gate; `plan-exec` persigue el plan hasta su validación final; `quick-loop` es la encarnación más directa (el prompt *es* el objetivo) — el "símil a `/goal`" del modelo.
-
-> **Continuidad inter-turno (contexto operativo).** El mismo `CHECKPOINT`+resume que sobrevive la compactación gobierna también el **próximo prompt**: dentro de un workspace, un prompt **sin comando** **continúa/reabre la sesión más reciente** (la *última iniciada*) en vez de arrancar trabajo suelto — el objetivo persiste **entre turnos**, no solo dentro del run. Un **comando de flujo** señala "nueva línea de trabajo" (sesión nueva) — **salvo re-correr el mismo flujo sobre la misma entrada** (mismo spec/plan), que hace `create_or_resume`: reanuda/reabre la session existente en vez de duplicarla (ver *Compact / resume*, caso 3); la convergencia cierra la sesión y un prompt relacionado posterior la **reabre** (resume quita `.closed`). Es la fila 2 de la matriz de contexto operativo (ver [`../SKILL.md`](../SKILL.md) § *Contexto operativo*) — doctrina agnóstica que la IA evalúa en cada turno, no un Stop hook del host.
+> **Continuidad inter-turno.** El mismo `CHECKPOINT`+resume gobierna también el **próximo prompt**: el objetivo persiste **entre turnos**, no solo dentro del run. Las reglas canónicas (comando = línea nueva · re-run = `create_or_resume` · prompt pelado = continuar la más reciente · reapertura de cerradas · escalación consentida) viven en [`../SKILL.md`](../SKILL.md) § *Contexto operativo* — **única fuente**; este motor las ejecuta vía *Compact / resume* (caso 3).
 
 ## Verification-first
 
@@ -43,7 +35,9 @@ El objetivo persistente necesita una **condición de término checkable** — si
 | spec / plan | **rúbrica** = los acceptance criteria del documento (referenciados, no duplicados) | rúbrica |
 | análisis / diseño | **rúbrica falsable por inspección** (ej. "todos los afectados con `file:line`"; "cada decisión: rationale + ≥1 alternativa") | rúbrica |
 
-**Forma y peso escalan** (preserva la *ceremonia mínima* de quick): un chore es "tests/build existentes siguen verdes" (una línea); un feature, acceptance tests reales. No es "siempre escribir tests nuevos" — es "**siempre declarar el check antes**". Para deliverables **subjetivos** (análisis/diseño) la IA **propone** la rúbrica y el **humano la ratifica** (structured-choice) antes de perseguirla. **Criterio irresoluble** (sin evidencia, BD no disponible) → cierra `inconcluso` + el loop **degrada** (humano, o difiere a `Open questions`/`BACKLOG`); nunca itera en falso.
+- **Forma y peso escalan** (ceremonia mínima de quick preservada): chore = "tests/build existentes siguen verdes" (una línea); feature = acceptance tests reales. La regla es "**siempre declarar el check antes**", no "siempre escribir tests nuevos".
+- **Deliverable subjetivo** (análisis/diseño): la IA **propone** la rúbrica y el **humano la ratifica** (structured-choice) antes de perseguirla.
+- **Criterio irresoluble** (sin evidencia, BD no disponible): cierra `inconcluso` y el loop **degrada** (humano, o difiere a `Open questions`/`BACKLOG`) — **nunca itera en falso**.
 
 > El **convergence gate** (sección *Convergence / exit*) es, operacionalmente, **"todos los `Success criteria` en verde"**. Los gates por-heir (analyze gate; coherencia del plan — plan-new y plan-refine; validación final; validación puntual proporcional) son **instancias** de esto, con los criterios sembrados al inicio.
 
@@ -68,7 +62,13 @@ El loop trabaja **artifact-first**: el artefacto se **siembra antes** de ejecuta
 
 ## Motor gap-driven convergente
 
-El ciclo común (cada heir lo instancia en su `## Sequence`, con su propia gap taxonomy): `detect_gaps(work)` — menos los gaps *agotados* (ver *Research*) — → si `∅`, **convergence gate** (ver *Convergence / exit*); si hay gaps, tomar un batch (≤3), **sembrar** `CHECKPOINT.Pending/Next` (*artifact-first*), resolver cada gap con su **resolutor** — humano (structured-choice) · research inline · una capacidad compuesta (p. ej. `ui-design`) — según la *ask-vs-research rule*, **integrar** y actualizar `CHECKPOINT` → repetir.
+El ciclo común — cada heir lo instancia en su `## Sequence` con su propia gap taxonomy:
+
+1. `detect_gaps(work)`, menos los gaps *agotados* (ver *Research*).
+2. Si `∅` → **convergence gate** (ver *Convergence / exit*).
+3. Si hay gaps: tomar un batch (≤3) y **sembrar** `CHECKPOINT.Pending/Next` (*artifact-first*).
+4. Resolver cada gap con su **resolutor** según la *ask-vs-research rule*: humano (structured-choice) · research inline · una capacidad compuesta (p. ej. `ui-design`).
+5. **Integrar**, actualizar `CHECKPOINT` → repetir.
 
 ## Internal sessions (managed) — una session por run
 
@@ -116,7 +116,7 @@ La investigación es **inline**: una actividad **dentro de la session actual del
 
 ## Structured-choice (design & batching)
 
-*structured-choice* (capacidad del arnés — ver [`../harness/SKILL.md`](../harness/SKILL.md)). En **Claude Code** es `AskUserQuestion` (máx 4 preguntas/llamada → **≤3 preguntas de contenido + 1 control `flow`**); en un arnés sin elección estructurada, degrada a **markdown numerado**.
+**Regla canónica (única fuente — el resto del corpus solo referencia):** *structured-choice* = **≤3 preguntas de contenido + 1 control `flow`**, siempre. Binding por arnés en [`../harness/SKILL.md`](../harness/SKILL.md) (Claude Code: `AskUserQuestion`, máx 4 preguntas/llamada; sin elección estructurada, degrada a **markdown numerado**).
 
 - Como el control `flow` va **siempre** → **≤3 preguntas de contenido + 1 control `flow`**.
 - **control `flow`** (ciclo de vida, siempre presente): `Compactar` | `Cerrar`. Responder solo las preguntas de contenido (sin tocar `flow`) = seguir iterando.
@@ -152,8 +152,12 @@ Un loop escribe en `docs/` **solo** el doc de su propio flujo (spec-refine: `doc
 
 Los loops que **editan código** (`plan-exec-loop`, `quick-loop`) corren además las políticas de [`CODE-POLICIES.md`](CODE-POLICIES.md) — **git seguro** (rama verificada + commits propuestos) · **BD solo-scripts** · **gate de revisión de cierre** (proporcional en quick). Las mandan leer desde su `## Inherits` **junto con este chasis**; los loops de documento (spec-refine, plan-new, plan-refine) **no** las cargan — por eso viven en un doc aparte.
 
-## Qué NO es el chasis
+## Resolución de referencias (regla global de layout)
+
+Vale para **toda** referencia relativa de la doctrina — no se repite por link:
+
+1. **Instalación normal** (árbol `w/`): la ruta relativa resuelve tal cual (`../CHASSIS.md`, `../../commands/spec-new.md`).
+2. **Instalación aplanada** (p. ej. Warp/Oz): los `.md` compartidos (`CHASSIS.md`, `CODE-POLICIES.md`) están **junto al `SKILL.md` del loop**; otro loop es una skill **hermana** `w-<loop>/` (ej. `../spec-refine-loop/SKILL.md` → `../w-spec-refine-loop/SKILL.md`).
+3. Referencia que no resuelva = **profundización opcional** — la doctrina de este motor es autocontenida.
 
-- **No es una skill**: no tiene frontmatter, no aparece en el system prompt, no se invoca ni se bindea vía `.workflow/skills.toml`. Es un documento **referenciado**: entra al contexto solo porque un loop manda leerlo.
-- **No corre solo**: no define flujo, deliverable ni gap taxonomy — eso es de cada heir. Sin un heir, el chasis no hace nada.
-- **Localización**: los heirs lo referencian como `../CHASSIS.md` (instalación normal, árbol `w/loops/`). En instalaciones **aplanadas** (p. ej. Warp/Oz) puede estar como `CHASSIS.md` **junto al `SKILL.md` del loop** (ídem `CODE-POLICIES.md` para los loops que editan código). En esas copias aplanadas los **links salientes** del chasis (`../SKILL.md`, `../harness/`, `../artifacts/`, `../roles/`) pueden no resolver: son **profundización opcional** — la doctrina del motor es autocontenida.
+El chasis **no es una skill** (sin frontmatter; no se invoca ni se bindea vía `.workflow/skills.toml`): entra al contexto solo porque un loop manda leerlo desde su `## Inherits`. No define flujo, deliverable ni gap taxonomy — eso es de cada heir.

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

@@ -3,15 +3,12 @@ name: plan-exec-loop
 description: >-
   Ejecuta un plan de implementación (docs/plans/PPP-plan-<slug>.md) como
   living doc: lo lee y actualiza fase a fase mientras edita el código real,
-  gestiona BD y git. Heir del chasis común de los loops (loops/CHASSIS.md —
-  motor gap-driven, research inline, structured-choice, artefactos como log
-  vivo, y las políticas de loops que editan código); sus deltas viven en el
-  cuerpo: session única reanudable, git seguro (rama verificada,
-  commits propuestos por fuente, nunca push/--amend/--no-verify), BD solo-
-  scripts (la IA nunca ejecuta DML/DDL), validación por fase y final, gate de
-  revisión de cierre pre-commit, y sin auto-export (solo escribe docs/plans).
-  Compone git y sql. Lo arranca /w:plan-exec. Invocar para implementar un plan
-  ya generado.
+  gestiona BD y git. Heir del chasis (loops/CHASSIS.md + CODE-POLICIES.md).
+  Deltas: session única reanudable, git seguro (rama verificada, commits
+  propuestos por fuente, nunca push/--amend/--no-verify), BD solo-scripts
+  (nunca ejecuta DML/DDL), validación por fase y final, gate de revisión de
+  cierre pre-commit, sin auto-export. Compone git y sql. Lo arranca
+  /w:plan-exec. Invocar para implementar un plan ya generado.
 ---
 
 # plan-exec-loop
@@ -41,7 +38,7 @@ Regla completa en el chasis (§ *docs/ boundary — sin auto-export*). Acá: la
 
 ## Inherits
 
-Leé **[`../CHASSIS.md`](../CHASSIS.md)** (instalación normal) **o** `CHASSIS.md` junto a este archivo (instalación aplanada) — el motor completo del loop (objetivo persistente + verification-first, gap-driven, session única + research inline, structured-choice + control `flow`, compact/resume, artefactos como log vivo, numeración, convergence gate, docs/ boundary) — **y** **[`../CODE-POLICIES.md`](../CODE-POLICIES.md)** (o `CODE-POLICIES.md` junto a este archivo) — las *Políticas de loops que editan código* (git seguro · BD solo-scripts · gate de revisión de cierre) — **siempre antes** de estos deltas.
+Leé **[`../CHASSIS.md`](../CHASSIS.md)** — el **motor completo** del loop — **y** **[`../CODE-POLICIES.md`](../CODE-POLICIES.md)** — las *Políticas de loops que editan código* — **siempre antes** de estos deltas. *(Si `../` no resuelve: mismos nombres junto a este archivo — regla global de layout, chasis § Resolución de referencias.)*
 
 ## Composes
 

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

@@ -2,16 +2,12 @@
 name: plan-new-loop
 description: >-
   Genera un plan de implementación rico (docs/plans/PPP-plan-<slug>.md) a
-  partir de un spec (docs/specs/NNN-spec-<slug>.md). Heir del chasis común de
-  los loops (loops/CHASSIS.md — motor gap-driven convergente, session única
-  con research inline, structured-choice, artefactos como log vivo); sus
-  deltas viven en el cuerpo:
-  el plan absorbe el nivel TECHNICAL-NOTE + Phases/Tasks con estado vivo,
-  research de mapeo código/impacto, gap taxonomy de planificación, y si el
-  plan incluye UI compone ui-design para autorar design SPECs por pantalla
-  (NNN-SPEC-<SLUG>.md). Si el spec no está refinado sugiere spec-refine antes.
-  Lo arranca /w:plan-new y es reanudable. Invocar cuando un spec deba
-  convertirse en un plan ejecutable antes de implementar.
+  partir de un spec. Heir del chasis (loops/CHASSIS.md). Deltas: el plan
+  absorbe el nivel TECHNICAL-NOTE + Phases/Tasks con estado vivo, research de
+  mapeo código/impacto, gap taxonomy de planificación, y design SPECs por
+  pantalla vía ui-design si el plan incluye UI. Si el spec no está refinado
+  sugiere spec-refine antes. Lo arranca /w:plan-new; reanudable. Invocar
+  cuando un spec deba convertirse en un plan ejecutable.
 ---
 
 # plan-new-loop
@@ -33,11 +29,11 @@ PLAN
 ## 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. 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`.
+> **slug**: kebab-case corto derivado del Requirement del spec — solo `[a-z0-9-]`, ≤ ~5 palabras / ≤ 40 chars. `aw next-number docs/plans` devuelve JSON (campo `next` = `PPP`); el loop arma el nombre completo. Para localizar planes, glob `docs/plans/PPP-plan-*.md`.
 
 ## Inherits
 
-Leé **[`../CHASSIS.md`](../CHASSIS.md)** (instalación normal) **o** `CHASSIS.md` junto a este archivo (instalación aplanada) — el motor completo del loop (objetivo persistente + verification-first, gap-driven, session única + research inline, structured-choice + control `flow`, compact/resume, artefactos como log vivo, numeración, convergence gate), **siempre antes** de estos deltas.
+Leé **[`../CHASSIS.md`](../CHASSIS.md)** — el **motor completo** del loop — **siempre antes** de estos deltas. *(Si `../` no resuelve: `CHASSIS.md` junto a este archivo — regla global de layout, chasis § Resolución de referencias.)*
 
 ## Internal sessions — instancia PLAN-new
 
@@ -99,10 +95,44 @@ El research **inline** del chasis se especializa: mapear **código/impacto** —
 
 ## 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*).
+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` (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*).
+
+## Sequence
+
+```
+plan-new-loop(spec):
+  input = glob(docs/specs/NNN-spec-*.md) | ruta del argumento
+  si el spec NO tiene ## Refinement decisions + ## Q&A traceability:
+    soft-suggest /w:spec-refine (el usuario puede proceder igual)
+  session = create_or_resume("<slug>-plan-new")               # CLI antepone NNN global
+  seed SESSION.Success criteria = checklist del coherence gate  # verification-first, ANTES
+  work = esqueleto del plan (Delta 1) derivado del spec (+ avance del checkpoint si reanuda)
+  repeat:                                                      # motor del chasis
+    gaps = detect_gaps(work)  (taxonomy Delta 2)  menos los agotados
+    if gaps == ∅: break
+    batch ≤3 → sembrar CHECKPOINT.Pending/Next → resolver cada gap:
+      research (mapea código/impacto — Delta 3) · humano (structured-choice) · ui-design (Delta 4)
+    integrar + update CHECKPOINT                               # ciclo artifact-first
+  coherence gate (read-only) = Success criteria en verde:
+    - cada acceptance criterion del spec traza a una fase/tarea
+    - Final behavior cubre los criterios
+    - fases XS–S · tareas XS · deps sin ciclos · Impacted consistente con Solution
+    - (UI) cada pantalla/tarea UI traza a su design SPEC y no contradice ## UI spec
+    lo que falle → vuelve como gap
+  structured_choice(contenido: [Guardar plan, Preguntar algo más], flow: [Compactar, Cerrar])
+  Guardar → write docs/plans/PPP-plan-<slug>.md (con confirmación si existe)
+finalize: CHECKPOINT persiste (+ BACKLOG solo si difiere) + cerrar session + reportar
+```
 
 ## 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`; 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.
+- **Sin gaps materiales** → **coherence gate** (checklist del *Sequence*; la instancia PLAN-new del convergence gate del chasis). La trazabilidad criterio→tarea es una **invariante chequeada**, no una sección aparte.
+- Pasa → `Guardar plan` (escribe con confirmación si existe) → `finalize`.
+- `Cerrar` en cualquier momento → `finalize` (persiste `CHECKPOINT`; `BACKLOG` solo si difiere; cierra la session, reporta).
 
 > **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

@@ -2,16 +2,12 @@
 name: plan-refine-loop
 description: >-
   Refina un plan existente (docs/plans/PPP-plan-<slug>.md) editándolo IN
-  PLACE, como paso auxiliar y NO obligatorio del flujo PLAN antes de plan-
-  exec. Es a plan-new lo que spec-refine es a spec-new. Heir del chasis común
-  de los loops (loops/CHASSIS.md — motor gap-driven, session única con
-  research inline, structured-choice, artefactos como log vivo); reusa la gap
-  taxonomy y el coherence gate de plan-new-loop, agrega Refinement
-  decisions/Q&A traceability al plan
-  (traza, sin gating), y si el refine toca UI compone ui-design y
-  produce/actualiza design SPECs por pantalla. Lo arranca /w:plan-refine;
-  reanudable y re-corrible a demanda. Invocar cuando un plan ya generado deba
-  ajustarse antes de ejecutarlo.
+  PLACE — paso auxiliar y NO obligatorio antes de plan-exec. Heir del chasis
+  (loops/CHASSIS.md). Deltas: reusa la gap taxonomy y el coherence gate de
+  plan-new-loop, agrega Refinement decisions / Q&A traceability (traza, sin
+  gating), y produce/actualiza design SPECs vía ui-design si el refine toca
+  UI. Lo arranca /w:plan-refine; reanudable y re-corrible a demanda. Invocar
+  cuando un plan ya generado deba ajustarse antes de ejecutarlo.
 ---
 
 # plan-refine-loop
@@ -40,7 +36,7 @@ Actualiza `docs/plans/PPP-plan-<slug>.md` **in place** (cuando el usuario elige
 
 ## Inherits
 
-Leé **[`../CHASSIS.md`](../CHASSIS.md)** (instalación normal) **o** `CHASSIS.md` junto a este archivo (instalación aplanada) — el motor completo del loop (objetivo persistente + verification-first, gap-driven, session única + research inline, structured-choice + control `flow`, compact/resume, artefactos como log vivo, numeración, convergence gate), **siempre antes** de estos deltas.
+Leé **[`../CHASSIS.md`](../CHASSIS.md)** — el **motor completo** del loop — **siempre antes** de estos deltas. *(Si `../` no resuelve: `CHASSIS.md` junto a este archivo — regla global de layout, chasis § Resolución de referencias.)*
 
 ## Internal sessions — instancia PLAN-refine
 
@@ -90,10 +86,38 @@ El resume **keya off el `CHECKPOINT`** de la refine session, no de un archivo "r
 
 1. **En curso** (existe `CHECKPOINT.md` en la refine session) → reanuda desde el avance (gaps resueltos, Q&A, `attempts`, research inline en curso).
 2. **Sin avance** (no hay CHECKPOINT y el plan **no** tiene `Refinement decisions`/`Q&A traceability`) → arranca desde cero leyendo el plan (`PPP-plan-*.md`).
-3. **Ya refinado / re-refine on demand** (no hay CHECKPOINT abierto pero el plan **ya tiene** `Refinement decisions`/`Q&A traceability`) → **operación de primera clase**: mientras el flujo siga en PLAN, re-correr `/w:plan-refine` sobre el mismo plan **cuantas veces haga falta** está soportado. `create_or_resume` detecta la refine session existente —típicamente **cerrada** tras converger— por descriptor + `## Origin` y la **reabre** (ver chasis § *Internal sessions*: detección con `aw sessions --state all` / `aw resume-summary --include-recent-closed`, reapertura con `aw session-resume --code <NNN> --reopen`); re-refinamiento incremental leyendo el **plan mismo**; al `Guardar`, edita in place con confirmación.
+3. **Ya refinado / re-refine on demand** (sin CHECKPOINT abierto, pero el plan **ya tiene** las 2 secciones) → **operación de primera clase**, cuantas veces haga falta mientras el flujo siga en PLAN:
+   - `create_or_resume` detecta la refine session existente (típicamente **cerrada** tras converger) por descriptor + `## Origin` y la **reabre**: `aw session-resume --code <NNN> --reopen` (detección: `aw sessions --state all`).
+   - Re-refinamiento incremental leyendo el **plan mismo**; al `Guardar`, edita in place con confirmación.
 
 > **Continuidad inter-turno** (chasis, fila 2): un **comando de flujo** abre "nueva línea de trabajo" (sesión nueva) — **salvo re-correr el mismo flujo sobre la misma entrada** (mismo plan), que hace `create_or_resume` (reanuda/reabre en vez de duplicar).
 
+## Sequence
+
+```
+plan-refine-loop(plan):
+  input = glob(docs/plans/PPP-plan-*.md) | ruta del argumento   # siempre el plan mismo (in place)
+  session = create_or_resume("<slug>-plan-refine")              # reabre si existe (ver Compact / resume)
+  seed SESSION.Success criteria = checklist del coherence gate  # verification-first, ANTES
+  work = read(plan) (+ el spec si hay que re-alinear; + avance del checkpoint si reanuda)
+  repeat:                                                       # motor del chasis
+    gaps = detect_gaps(work)  (taxonomy de plan-new + deriva plan↔spec)  menos los agotados
+    if gaps == ∅: break
+    batch ≤3 → sembrar CHECKPOINT.Pending/Next → resolver cada gap:
+      research (acotado al delta — Delta 3) · humano (structured-choice) ·
+      ui-design (Delta 4, solo pantallas nuevas/cambiadas)
+    integrar + update CHECKPOINT                                # ciclo artifact-first
+  coherence gate (read-only) = Success criteria en verde:
+    - checklist de plan-new (criterio→tarea · Final behavior · XS–S/XS · deps · Impacted↔Solution · UI→SPEC vigente)
+    - propio del re-refine: el plan quedó REALINEADO con lo que cambió
+    lo que falle → vuelve como gap
+  structured_choice(contenido: [Guardar plan refinado, Preguntar algo más], flow: [Compactar, Cerrar])
+  Guardar → edit in place (con confirmación) + inserta/actualiza Refinement decisions + Q&A traceability
+finalize: CHECKPOINT persiste (+ BACKLOG solo si difiere) + cerrar session + reportar
+```
+
 ## 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`, 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.
+- **Sin gaps materiales** → **coherence gate** (checklist del *Sequence*; el mismo gate de plan-new + la realineación propia del re-refine).
+- Pasa → `Guardar plan refinado` (edita in place con confirmación) → `finalize`.
+- `Cerrar` en cualquier momento → `finalize` (persiste `CHECKPOINT`; `BACKLOG` solo si difiere; cierra la session, reporta).

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

@@ -2,16 +2,13 @@
 name: quick-loop
 description: >-
   El atajo liviano de agent-workflow: resuelve una tarea acotada (fix, ajuste
-  chico) directamente desde el prompt, editando código con ceremonia mínima.
-  Heir del chasis común de los loops (loops/CHASSIS.md — motor gap-driven con
-  las políticas de loops que editan código: git seguro, BD solo-scripts, gate
-  de revisión de cierre proporcional, sin auto-export); sus deltas viven en
-  el cuerpo: sin fases ni plan-doc (el prompt ES la tarea),
-  session ligera única (<slug>-quick), un solo commit, gate de tamaño a la
-  entrada y escalación EN VIVO a SPEC (handoff + spec-refine directo; a PLAN
-  queda diferida) si el objetivo excede un quick o la tarea crece. NO toca
-  docs/. Lo arranca /w:quick y es reanudable. Invocar para cambios pequeños y
-  directos que no ameritan spec ni plan formal.
+  chico) desde el prompt, con ceremonia mínima y un solo commit. Heir del
+  chasis (loops/CHASSIS.md + CODE-POLICIES.md). Deltas: sin plan-doc (el
+  prompt ES la tarea), session ligera única <slug>-quick, gate de tamaño a la
+  entrada y escalación EN VIVO a SPEC (a PLAN queda diferida) si el objetivo
+  excede un quick o la tarea crece. NO toca docs/. Lo arranca /w:quick;
+  reanudable. Invocar para cambios pequeños y directos que no ameritan spec
+  ni plan formal.
 ---
 
 # quick-loop
@@ -41,7 +38,7 @@ QUICK
 
 ## Inherits
 
-Leé **[`../CHASSIS.md`](../CHASSIS.md)** (instalación normal) **o** `CHASSIS.md` junto a este archivo (instalación aplanada) — el motor completo del loop (objetivo persistente + verification-first, gap-driven, session única + research inline, structured-choice + control `flow`, compact/resume, artefactos como log vivo, numeración, convergence gate, docs/ boundary) — **y** **[`../CODE-POLICIES.md`](../CODE-POLICIES.md)** (o `CODE-POLICIES.md` junto a este archivo) — las *Políticas de loops que editan código* (git seguro · BD solo-scripts · gate de revisión de cierre **proporcional**) — **siempre antes** de estos deltas.
+Leé **[`../CHASSIS.md`](../CHASSIS.md)** — el **motor completo** del loop — **y** **[`../CODE-POLICIES.md`](../CODE-POLICIES.md)** — las *Políticas de loops que editan código* — **siempre antes** de estos deltas. *(Si `../` no resuelve: mismos nombres junto a este archivo — regla global de layout, chasis § Resolución de referencias.)*
 
 ## Composes
 
@@ -60,12 +57,15 @@ Leé **[`../CHASSIS.md`](../CHASSIS.md)** (instalación normal) **o** `CHASSIS.m
   - **Seguir en quick** → continúa normal (`create_or_resume` + loop).
   - **Recortar alcance** → la IA propone la **sub-tarea que SÍ cabe** en un quick; el loop sigue con ella (`SESSION.Objective` = la sub-tarea; el prompt original queda en el `## Origin` de la session) y el resto se difiere al `BACKLOG` ("recortado en el gate — puede ameritar spec aparte, `/w:spec-new`").
   - **Anti-duplicado** (espíritu `create_or_resume`): si ya existe un spec cuyo `## Origin` referencia este mismo objetivo (o una session `*-spec-refine` equivalente), la recomendada pasa a ser **retomar ese spec** (semántica `/w:spec-refine`) — nunca materializar un segundo borrador.
-- **Transición en vivo a SPEC** (compartida por el gate y la escalación mid-loop): al aceptar, la línea de trabajo **deja de ser QUICK y pasa a ser flujo SPEC** — el consentimiento explícito en la structured-choice **equivale a invocar el comando** del flujo destino (excepción consentida a la regla de continuidad; ver [`../../SKILL.md`](../../SKILL.md) § *Contexto operativo*). Ya **del lado SPEC**: (1) materializar el **borrador** siguiendo el procedimiento de [`../../commands/spec-new.md`](../../commands/spec-new.md) — o `commands/spec-new.md` dentro de la skill `w` instalada (instalación aplanada) — `aw next-number docs/specs`, slug, esquema, single-pass **SIN investigación**; `## Origin` = "escalado desde `/w:quick`" + el prompt original (+ la session quick de origen si existe); (2) **cargar y ejecutar** [`../spec-refine-loop/SKILL.md`](../spec-refine-loop/SKILL.md) — o `../w-spec-refine-loop/SKILL.md` (instalación aplanada, skill hermana) — sobre ese spec, mismo patrón "cargalo y ejecutalo" de los comandos trampolín. La session del run es la `NNN-<slug>-spec-refine` **normal** de ese loop (el CLI numera; su `## Origin` registra la escalación). El **invariante 2 queda intacto**: quick, mientras es quick, no escribe `docs/` — el borrador lo escribe el flujo SPEC, post-consentimiento.
+- **Transición en vivo a SPEC** (compartida por el gate y la escalación mid-loop). Al aceptar, la línea de trabajo **pasa al flujo SPEC**: el consentimiento explícito en la structured-choice **equivale a invocar el comando destino** (*excepción consentida* — regla 3 de la *Regla de continuidad*, [`../../SKILL.md`](../../SKILL.md) § *Contexto operativo*). Ya del lado SPEC:
+  1. **Materializar el borrador** por el procedimiento de [`../../commands/spec-new.md`](../../commands/spec-new.md): `aw next-number docs/specs`, slug, esquema, single-pass **SIN investigación**. `## Origin` = "escalado desde `/w:quick`" + el prompt original (+ la session quick de origen si existe).
+  2. **Cargar y ejecutar** [`../spec-refine-loop/SKILL.md`](../spec-refine-loop/SKILL.md) — aplanada: `../w-spec-refine-loop/SKILL.md` — sobre ese spec (patrón trampolín).
+  3. La session del run es la `NNN-<slug>-spec-refine` **normal** de ese loop (el CLI numera; su `## Origin` registra la escalación). **Invariante 2 intacto**: quick, mientras es quick, no escribe `docs/` — el borrador lo escribe el flujo SPEC, post-consentimiento.
 - **Escalación mid-loop + handoff**: si la tarea crece (mismas señales del gate) → propone subir a **SPEC/PLAN** (structured-choice, recomendación primera). 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" ([`../CODE-POLICIES.md`](../CODE-POLICIES.md) § *Git seguro*: 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 el **puntero**: a **PLAN**, "escalado a `docs/plans/PPP` — retomar ahí" (**diferido como hoy**: siembra + puntero, sin entrar en vivo); a **SPEC**, "escalado a `docs/specs/NNN` — **continuado en vivo** (session `NNN-<slug>-spec-refine`)";
-  - los artefactos (`DECISION`, `SCRIPTS.sql`) **quedan en la session quick** como contexto referenciable por la nueva session (no se migran);
-  - **SPEC entra en vivo**: tras el `finalize`, corre la *Transición en vivo a SPEC* (borrador vía procedimiento spec-new **solo si no existe** spec para este objetivo; luego el loop). **Asimetría** intacta: escalar a **PLAN** puede **absorber** el avance (plan-exec retoma el working tree existente); escalar a **SPEC** **reinicia** el ciclo de diseño y trata el código a medias como **contexto/referencia**, no como trabajo ya ingerido.
+  1. El **código ya editado queda** en el working tree (no se revierte) y se **registra** en `CHECKPOINT` + `BACKLOG`: "cambios sin commitear en `<fuente>` — decidir commit/descartar al retomar" (patrón "commit rechazado", [`../CODE-POLICIES.md`](../CODE-POLICIES.md) § *Git seguro*).
+  2. La session quick va a `finalize` con el **puntero** en `BACKLOG`: a **PLAN** → "escalado a `docs/plans/PPP` — retomar ahí" (**diferido como hoy**: siembra + puntero, sin entrar en vivo); a **SPEC** → "escalado a `docs/specs/NNN` — **continuado en vivo** (session `NNN-<slug>-spec-refine`)".
+  3. Los artefactos (`DECISION`, `SCRIPTS.sql`) **quedan en la session quick** como contexto referenciable por la nueva session (no se migran).
+  4. **SPEC entra en vivo**: tras el `finalize` corre la *Transición en vivo a SPEC* (borrador **solo si no existe** spec para este objetivo; luego el loop). **Asimetría** intacta: PLAN puede **absorber** el avance (plan-exec retoma el working tree existente); SPEC **reinicia** el ciclo de diseño y trata el código a medias como contexto/referencia, no como trabajo ya ingerido.
 
 ## Continuidad entre prompts (contexto operativo)
 

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

@@ -2,16 +2,13 @@
 name: spec-refine-loop
 description: >-
   Refina un spec borrador (docs/specs/NNN-spec-<slug>.md) editándolo IN PLACE
-  hasta dejarlo sin ambigüedad. Heir del chasis común de los loops
-  (loops/CHASSIS.md — motor gap-driven convergente: session única con research
-  inline, structured-choice ≤3 preguntas + control flow, artefactos como log
-  vivo, compact/resume, convergence gate); aquí viven solo sus deltas SPEC:
+  hasta dejarlo sin ambigüedad. Heir del chasis (loops/CHASSIS.md). Deltas:
   gap taxonomy de spec, analyze gate, sección ## UI spec vía la capacidad
-  ui-design cuando el requerimiento involucra UI, y agrega Refinement
-  decisions + Q&A traceability al spec — la marca de refinado que plan-new
-  detecta. Lo arranca /w:spec-refine (o la escalación en vivo desde
-  quick-loop); reanudable vía CHECKPOINT y re-corrible a demanda. Invocar cuando haya que refinar/desambiguar una especificación
-  antes de planificar.
+  ui-design, y agrega Refinement decisions + Q&A traceability — la marca de
+  refinado que plan-new detecta. Lo arranca /w:spec-refine (o la escalación
+  en vivo desde quick-loop); reanudable vía CHECKPOINT y re-corrible a
+  demanda. Invocar para refinar/desambiguar una especificación antes de
+  planificar.
 ---
 
 # spec-refine-loop
@@ -20,7 +17,7 @@ description: >-
 
 ## Inherits
 
-Leé **[`../CHASSIS.md`](../CHASSIS.md)** (instalación normal) **o** `CHASSIS.md` junto a este archivo (instalación aplanada) — el motor completo del loop (objetivo persistente + verification-first, gap-driven, session única + research inline, structured-choice + control `flow`, compact/resume, artefactos como log vivo, numeración, convergence gate), **siempre antes** de estos deltas.
+Leé **[`../CHASSIS.md`](../CHASSIS.md)** — el **motor completo** del loop — **siempre antes** de estos deltas. *(Si `../` no resuelve: `CHASSIS.md` junto a este archivo — regla global de layout, chasis § Resolución de referencias.)*
 
 ## Flow
 SPEC
@@ -57,7 +54,7 @@ Doctrina completa en el chasis (§ *Internal sessions* + *Numeración*). La inst
 
 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.
+> **Dos niveles de la misma capacidad:** aquí (SPEC) produce `## UI spec` — el *qué* de la UI, grano grueso; en PLAN, los loops de plan producen **design SPECs por pantalla** derivados de esa sección (ver [`SPEC.md`](../../artifacts/artifacts-design/SPEC.md)).
 
 Otras capacidades transversales que el motor usa siempre: `research` (research **inline** — chasis § *Research*), `sql` (regla BD en research — chasis). 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.
 

package/skills/w/roles/git/SKILL.md

@@ -46,7 +46,7 @@ Y **siempre** prohibido, aún cuando el usuario pida commit: `--no-verify` (resp
 
 ### Operaciones read-only (siempre permitidas, sin preguntar)
 
-`status` · `log` · `diff` · `branch --show-current` · `rev-parse` · `show`. `git checkout` (cambio de rama) **no** es read-only: requiere *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`**; sin elección estructurada degrada a **markdown numerado**) aunque no sea destructivo (ver verificación de rama).
+`status` · `log` · `diff` · `branch --show-current` · `rev-parse` · `show`. `git checkout` (cambio de rama) **no** es read-only: requiere *structured-choice* (regla canónica: `../../loops/CHASSIS.md` § *Structured-choice*; binding por arnés: `../../harness/SKILL.md`) aunque no sea destructivo (ver verificación de rama).
 
 ### Verificación de rama (antes de editar)
 
@@ -68,7 +68,7 @@ Casos:
 Ante cualquier pedido o disparo de commit (cierre de loop, "commitea esto", "guardá los cambios"):
 
 1. Resolver las fuentes y su estado dirty/rama con `aw sources` (inventario con git status enriquecido; fallback: git directo por fuente).
-2. Si hay 1+ fuentes `dirty=true`, invocar **una sola** *structured-choice* con una pregunta de contenido por fuente dirty (máx 4 simultáneas → **≤3 preguntas de contenido + 1 control `flow`**; si N>3, en tandas):
+2. Si hay 1+ fuentes `dirty=true`, invocar **una sola** *structured-choice* con una pregunta de contenido por fuente dirty (≤3 por llamada + control `flow`; si N>3, en tandas):
    - Header de la pregunta: el `alias` de la fuente.
    - Opciones: "Aprobar sugerido (Recomendado)" con el mensaje canónico / "Saltar esta fuente". `Other` = mensaje custom.
 3. Ejecutar `git -C <path> commit -m "<msg>"` solo en las fuentes aprobadas, **una a una**. Respetar hooks (sin `--no-verify`).
@@ -116,4 +116,4 @@ Ninguno en `docs/`. Produce commits **solo** cuando el usuario aprueba, en los r
 
 ## Source
 
-Reciclada de la doctrina vieja: `doctrine/session/references/commits-policy.md` (Reglas 1-5: propose-then-execute, formato canónico, bypass) + `doctrine/session/references/branch-verification.md` (Casos A/B/C, cross-fuente hard gate). La verificación delega lo mecánico al CLI (`aw check-branch`, `aw sources`) — computarlo a mano en cada task pagaba tokens por trabajo que el runtime ya expone; el git read-only directo queda como fallback para repos sin workspace.
+Racional e historia: diseño (`docs/referencias/workflow-roles/git.md`).

package/skills/w/roles/research/SKILL.md

@@ -24,7 +24,7 @@ El discriminador clave:
 | La pregunta... | Acción |
 |---|---|
 | puede responderse leyendo repo / datos (hechos objetivos del sistema) | **investigar** |
-| depende de preferencias, prioridades o decisiones del usuario | **preguntar al humano** 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**. |
+| depende de preferencias, prioridades o decisiones del usuario | **preguntar al humano** vía *structured-choice* (regla canónica: `../../loops/CHASSIS.md` § *Structured-choice*; binding por arnés: `../../harness/SKILL.md`) |
 | está parcialmente en el repo y parcialmente en intención del usuario | investigar primero, luego preguntar solo por la parte incierta |
 
 ## Composed by
@@ -118,4 +118,4 @@ No gradua a `docs/` (invariant #1). El loop que compone esta capacidad consume l
 
 ## Source
 
-Reciclado de `analyze-investigate`, `analyze-synthesize` y `analyze-conclude` del bundle viejo. Se conserva: el modelo de investigacion divergente → sintesis → conclusiones; las reglas read-only; el cost guard de queries; la discriminacion de gaps. Se descarta: la terminología de `flow=analyze`, `EVIDENCE.md`/`FINDINGS.md` como nombres canónicos (ahora `ANALYSIS-FILE.md`/`CONCLUSIONS.md`), el lifecycle de sesiones legacy (la research ahora es **inline**, sin sesión propia), y la modulacion por modalidad (technical/incident/data) — la skill de research es de propósito general.
+Racional e historia: diseño (`docs/referencias/workflow-roles/research.md`).

package/skills/w/roles/sql/SKILL.md

@@ -134,4 +134,4 @@ Nunca escribe a `docs/` desde un loop (invariante 1: solo `export-*` exporta). N
 
 ## Source
 
-Reciclada de `standards/sql-script-organizer/` (staging `SCRIPTS.sql`, markers, 4 categorías, estilo) + `standards/sql-rollback-generator/` (derivación de rollback, irreversibles, Fase 5) + reglas de estilo de `standards/coding-standards/references/database-conventions.md` (esa familia hoy es **ambiente** —extraída del workflow—; las reglas quedan **inlined** arriba, sin dependencia externa). Se moderniza al modelo nuevo: el bundle lo arma `export-scripts`, no la skill; el "release/graduate" viejo se reemplaza por `export-scripts`.
+Reglas autocontenidas (sin dependencia de skills externas). Racional e historia: diseño (`docs/referencias/workflow-roles/sql.md`).

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

@@ -32,7 +32,7 @@ Dos niveles, misma capacidad:
 
 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**.
+- **Pregunta al humano** (design-system, tema, ambigüedades de pantalla) vía *structured-choice* (regla canónica: `../../loops/CHASSIS.md` § *Structured-choice*; binding por arnés: `../../harness/SKILL.md`).
 - **Itera** gap-driven hasta converger.
 - Ofrece **variantes** y **cura** el resultado.