@tacuchi/agent-workflow-cli 12.5.0 → 12.7.0

package/skills/w/commands/README.md

@@ -3,7 +3,7 @@
 > This is the **bundle README** for the `/w:` slash-command namespace. Every command listed here is something the **user** invokes directly.
 > Related layers: [`../loops/`](../loops/) (Layer 2, AI-driven) · artifacts live in `.workflow/sessions/` (Layer 3) · permanent deliverables in `docs/`.
 >
-> **Namespace:** all commands are under `w:` (`w` = *workflow*): `/w:spec-new`, `/w:spec-refine`, `/w:plan-new`, `/w:plan-exec`, `/w:quick`, `/w:workspace-init`, `/w:status` (transversal), `/w:export-*`.
+> **Namespace:** all commands are under `w:` (`w` = *workflow*): `/w:spec-new`, `/w:spec-refine`, `/w:plan-new`, `/w:plan-exec`, `/w:quick`, `/w:workspace-init`, `/w:status` (transversal), `/w:fix-git` (transversal), `/w:export-*`.
 
 ---
 
@@ -20,7 +20,7 @@
                             ▼
 ┌─ LAYER 2 · LOOPS (../loops/) — AI runs these end-to-end ───────────────┐
 │   spec-refine-loop · plan-new-loop · plan-exec-loop · quick-loop        │
-│   Gap-driven · AskUserQuestion with ≤3 content tabs + 1 `flow` tab     │
+│   Gap-driven · structured-choice: ≤3 content questions + 1 `flow`     │
 │   (Compactar / Cerrar always present) · compact/resume support.        │
 └───────────────────────────┬────────────────────────────────────────────┘
                             │ creates / reads / writes
@@ -45,12 +45,14 @@
 | Flow | docs/ target | Entry command | Advance command | Loops involved |
 |---|---|---|---|---|
 | **SPEC** | `docs/specs/` | `spec-new` *(single-pass)* | `spec-refine` | `spec-refine-loop` |
-| **PLANIFICATION** | `docs/plans/` + `docs/tools/` | `plan-new` | `plan-exec` | `plan-new-loop`, `plan-exec-loop` |
+| **PLAN** | `docs/plans/` + `docs/tools/` | `plan-new` | `plan-exec` | `plan-new-loop`, `plan-exec-loop` |
 | **QUICK** | — *(no doc)* | `quick` | — | `quick-loop` |
 
-> **Intentional asymmetry:** in SPEC, `spec-new` generates the draft in a **single pass** (no loop) and the loop is in `spec-refine`. In PLANIFICATION, **both** commands start loops. Total: **5 flow commands / 4 loops**.
+> **Intentional asymmetry:** in SPEC, `spec-new` generates the draft in a **single pass** (no loop) and the loop is in `spec-refine`. In PLAN, **both** commands start loops. Total: **5 flow commands / 4 loops**.
 
 > **Transversal (no flow):** [`/w:status`](status.md) is a read-only dashboard of the whole workspace — what's done / pending / discarded, with friendly Spanish dates. It leans on `aw status`, writes nothing, and belongs to no flow.
+>
+> **Transversal (no flow):** [`/w:fix-git`](fix-git.md) resolves an **in-progress merge conflict** for any repo — identify origin↔destination, analyze both sides' intent, resolve (structured-choice on ambiguity), propose the merge commit (git-safe). Leans on `aw merge-state`; writes no `docs/`; works without a workspace. Neither transversal is counted in **5 flow / 4 loops**.
 
 ## Pipeline
 
@@ -78,7 +80,7 @@ flowchart LR
     q -->|starts| ql(["quick-loop"])
 ```
 
-**Pipeline reading:** SPEC defines *what* (refined spec) → PLANIFICATION defines *how* (plan) and *executes it* → QUICK is a lightweight shortcut for scoped work that does not warrant spec or plan.
+**Pipeline reading:** SPEC defines *what* (refined spec) → PLAN defines *how* (plan) and *executes it* → QUICK is a lightweight shortcut for scoped work that does not warrant spec or plan.
 
 > **`docs/` boundary:** each flow only touches its own folders — **SPEC** → `docs/specs`; **PLAN** → `docs/plans` + `docs/tools`. The rest of `docs/` (`scripts`, `manuals`, `diagrams`, `reports`) is written **only** by `export-*` skills (a separate, never-automatic step). See [`../loops/`](../loops/) and workflow-exports reference.
 
@@ -100,7 +102,7 @@ Each `<command>.md` in this bundle uses this frontmatter + body structure:
 3. **Spec and plan are documents** (`docs/`), not artifacts.
 4. **DB scripts-only**: AI **never executes DML/DDL**; migrations live in `SCRIPTS.sql` (type B) and are delivered via `export-scripts`. Only read-only queries via MCP.
 5. **Git-safe**: verify branch before editing; **propose** commits by source; never `push`/`--amend`/`--no-verify`.
-6. **All loops**: gap-driven convergent · one session per run (research inline) · `AskUserQuestion` with ≤3 content tabs + 1 `flow` tab (`Compactar`/`Cerrar`) always · compact/resume · artifacts as a live log (`CHECKPOINT` always; `BACKLOG` only when deferring).
+6. **All loops**: gap-driven convergent · one session per run (research inline) · *structured-choice* (capacidad del arnés — ver [`../harness/SKILL.md`](../harness/SKILL.md); en **Claude Code** es `AskUserQuestion`) con **≤3 preguntas de contenido + 1 control `flow`** (`Compactar`/`Cerrar`) siempre · compact/resume · artifacts as a live log (`CHECKPOINT` always; `BACKLOG` only when deferring).
 
 ## Index
 
@@ -113,6 +115,7 @@ Each `<command>.md` in this bundle uses this frontmatter + body structure:
 | `plan-exec` | [`plan-exec.md`](plan-exec.md) | starts `plan-exec-loop` |
 | `quick` | [`quick.md`](quick.md) | starts `quick-loop` |
 | `status` | [`status.md`](status.md) | single-pass, read-only (transversal) |
+| `fix-git` | [`fix-git.md`](fix-git.md) | single-pass, read/edit working tree (transversal) |
 | `export-scripts` | [`export-scripts.md`](export-scripts.md) | single-pass, read-only |
 | `export-manuals` | [`export-manuals.md`](export-manuals.md) | single-pass, read-only |
 | `export-diagrams` | [`export-diagrams.md`](export-diagrams.md) | single-pass, read-only |

package/skills/w/commands/fix-git.md

@@ -0,0 +1,33 @@
+---
+description: Resuelve conflictos de un merge en curso para una fuente dada o detectada. Identifica origen (theirs) y destino (ours), analiza la intención de ambos lados y resuelve; pregunta (structured-choice) ante ambigüedad o incoherencia. Git-safe — propone el commit de merge, nunca push/--amend/--no-verify. Transversal (no es flow), sin loop ni session, no toca docs/. Funciona en cualquier repo git, sin workspace inicializado.
+argument-hint: "[<source path | alias>]"
+allowed-tools:
+  [
+    "Bash",
+    "Read",
+    "Edit",
+  ]
+---
+
+# fix-git — resolvedor de conflictos de merge (transversal)
+
+Single-pass, **sin loop ni session**, **no escribe en `docs/`**. Comando **transversal** (no pertenece a SPEC / PLAN / QUICK). **Agnóstico al workspace**: opera sobre cualquier repo git — el `<source>` dado (path o alias), o el cwd — sin requerir `.workflow/`.
+
+## Ejecutar
+
+1. **Detectar + identificar** — corré `aw merge-state [<source>]` (read-only; `--source <alias>` o `--all` si hay workspace; un path directo si no). Del JSON, por repo: `is_merging`, `current_branch` (**destino / ours**), `merge_origin` (**origen / theirs**), `conflicted_files`.
+   - Si **no hay merge en curso** (`is_merging:false`) y el usuario indicó un **target** (p.ej. "merge `<branch>`"): es pedido explícito → `git -C <path> merge <branch>` y seguí. Sin target → informá que no hay merge que resolver y terminá.
+2. **Resolver** — **leé y seguí** la sección ***Resolución de conflictos de merge*** del rol `git` (`../roles/git/SKILL.md`): analizá la intención de cada conflicto (3 versiones `git show :1:/:2:/:3:<file>`, `git log --merge`), resolvé (ours / theirs / combinar / reescribir) y `git add` lo resuelto. Ante **ambigüedad o incoherencia**, preguntá vía *structured-choice* (no inventes la resolución).
+3. **Cerrar** — **proponé** el commit de merge (propose-then-execute, formato canónico, git-safe). Escape: `git merge --abort` tras confirmación del usuario.
+
+> No intentes `Skill: git` — el rol se **lee y se sigue** (es la capacidad que este comando compone). El comando **es** la entrada; la doctrina de conflictos vive en el rol `git`.
+
+## Plan mode
+
+Corré `aw merge-state` (read-only), reportá **origen ↔ destino** y los conflictos por archivo, y describí la **estrategia de resolución** que aplicarías — **sin** editar archivos ni commitear.
+
+## Resources
+
+- Capability: `../roles/git/SKILL.md` (sección *Resolución de conflictos de merge*)
+- CLI: `aw merge-state` (inspector read-only del estado de merge)
+- Design reference: `docs/referencias/workflow-commands/fix-git.md`

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

@@ -12,7 +12,7 @@ allowed-tools:
 
 # plan-new — trampolín al loop de planificación
 
-Puente SPEC → PLANIFICATION. Convierte el "qué" (spec refinado) en el "cómo" (plan). Delega a `plan-new-loop` (Layer 2).
+Puente SPEC → PLAN. Convierte el "qué" (spec refinado) en el "cómo" (plan). Delega a `plan-new-loop` (Layer 2).
 
 ## Resolución de input
 

package/skills/w/commands/quick.md

@@ -12,7 +12,7 @@ allowed-tools:
 
 # quick — trampolín al loop liviano
 
-Para tareas acotadas y directas que no justifican pasar por SPEC ni PLANIFICATION. Siempre crea una sesión ligera (trazabilidad + resume). Delega a `quick-loop` (Layer 2).
+Para tareas acotadas y directas que no justifican pasar por SPEC ni PLAN. Siempre crea una sesión ligera (trazabilidad + resume). Delega a `quick-loop` (Layer 2).
 
 ## Ejecutar el loop
 

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

@@ -17,9 +17,9 @@ Genera `docs/specs/NNN-spec-<slug>.md` en una sola pasada a partir del prompt en
 >
 > Este comando **solo parafrasea** el input del usuario en el esquema de borrador. Es **una única pasada secuencial**: leer `$ARGUMENTS` → llenar las secciones → escribir el archivo. Nada más. Debe tardar **segundos, no minutos**.
 >
-> **PROHIBIDO**, sin excepción: lanzar workflows, subagentes (`Task`/`Agent`), sesiones de research, búsquedas web, o investigación profunda de código. No uses las tools `Workflow`, `Task` ni `Agent` aquí.
+> **PROHIBIDO**, sin excepción: lanzar sub-agentes/workflows (`Task`/`Agent`/`Workflow`), sesiones de research, búsquedas web, o investigación profunda de código — **incluso si el arnés está en un modo de máximo esfuerzo/profundidad** (ej. ultracode/max-effort en Claude Code).
 >
-> Esto **anula** cualquier modo o instrucción de sesión que diga "corre un workflow para toda tarea sustancial" (ultracode, max-effort, etc.). Esos modos **no aplican** a `spec-new`: el comando los pisa. Si una sección queda incierta, **no la investigues** — declarala en `## Open questions` o `## Assumptions` y seguí.
+> Esto **anula** cualquier modo o instrucción de sesión que diga "corre un workflow para toda tarea sustancial". Esos modos **no aplican** a `spec-new`: el comando los pisa. Si una sección queda incierta, **no la investigues** — declarala en `## Open questions` o `## Assumptions` y seguí.
 >
 > La investigación a profundidad (cerrar gaps, mapear código, consultar BD, research autónomo) es trabajo de **`spec-refine`**, no de aquí.
 
@@ -47,21 +47,24 @@ Sistemas / componentes / fuentes involucradas. Restricciones conocidas.
 - Out: qué NO entra
 
 ## Acceptance criteria
-- [ ] criterio verificable 1
+- [ ] criterio verificable 1 (estilo EARS / Given-When-Then recomendado)
 - [ ] criterio verificable 2
 
-## Open questions
-Dudas pendientes. ← el spec-refine-loop las va cerrando.
-
 ## Assumptions       (opt.)
 Supuestos asumidos.
+
+## Open questions
+Dudas pendientes. ← el spec-refine-loop las va cerrando.
 ```
 
+> **`Open questions` va último** — el spec refinado **inserta antes de `Open questions`** `## UI spec` (si hay UI) + `## Refinement decisions` + `## Q&A traceability` (esquema refinado en el [`spec-refine-loop`](../loops/spec-refine-loop/SKILL.md)). Mismo esqueleto: el borrador y el refinado comparten orden.
+
 **Notas de llenado:**
 - Sin campo `Type` — `plan-new` infiere el cómo.
 - `Scope` siempre lleva `Out` (qué queda fuera).
-- Los criterios de aceptación deben ser verificables (testeables).
-- Si hay UI involucrada, mencionarlo en `Requirement`/`Context`; el spec UI se autora en `spec-refine` (via capacidad `ui-design`).
+- **Acceptance criteria = criterios testables estáticos** (el "qué"): `plan-exec` los valida pero el avance se trackea en el PLAN (sus Tasks), no marcando estos `- [ ]` en el spec; el spec no muta por ejecución, solo por re-refine.
+- Si hay **UI** involucrada, mencionarlo en `Requirement`/`Context`; el `## UI spec` se autora en `spec-refine` (vía capacidad `ui-design`). "UI sin especificar" es un gap de primera clase del refinamiento.
+- Los **gaps** que detecta el loop = secciones débiles del esquema (Requirement vago, Scope sin `Out`, criterios no testables, Open questions abiertas, supuestos no declarados, contradicciones) **+ UI sin especificar** si el requerimiento involucra UI.
 - Alternativa equivalente: el usuario crea el borrador a mano. Ambos caminos producen el mismo `docs/specs/NNN-spec-<slug>.md`.
 
 ## Plan mode

package/skills/w/exports/README.md

@@ -29,14 +29,14 @@
 | [`export-diagrams`](export-diagrams/SKILL.md) | `diagrams` | source code of the sources + plan-doc (`AS-IS` / `TO-BE`, `Impacted`) | `docs/diagrams/` (C4 / mermaid) |
 | [`export-reports`](export-reports/SKILL.md) | `writing` | corpus of sessions (spec, `CONCLUSIONS`, `DECISION`) + plan-doc state + `docs/` | `docs/reports/` (executive / functional report) |
 
-> **Composition over ownership:** an export does **not** own its authoring logic — it **composes a capability role** from [`../../`workflow-skills](../../) (resolved through `.workflow/skills.toml`): `export-scripts` composes `sql`; `export-manuals` and `export-reports` compose `writing`; `export-diagrams` composes `diagrams`. Swapping the implementation is a one-line config change; it never touches the export.
+> **Composition over ownership:** an export does **not** own its authoring logic — it **composes a capability role** from [`../roles/`](../roles/) (resolved through `.workflow/skills.toml`): `export-scripts` composes `sql`; `export-manuals` and `export-reports` compose `writing`; `export-diagrams` composes `diagrams`. Swapping the implementation is a one-line config change; it never touches the export.
 
 ## Common properties
 
 1. **Layer 1, explicit** — the **user** invokes them (`/w:export-<cat>`). **Never** automatic (no loop fires them).
 2. **Single-pass, read-only over sessions** — they read artifacts/sessions and `docs/`, **synthesize**, and write **only** their own `docs/<category>/` folder. They do **not** mutate sessions and do **not** open/close loops.
 3. **Cross-session** — they consolidate **N** sessions + the `docs/` corpus (dedup, roadmap, continuous numbering).
-4. **No loop, no internal sessions** — options come from **args** (no lifecycle `AskUserQuestion`).
+4. **No loop, no internal sessions** — options come from **args** (no *structured-choice* de ciclo de vida — capacidad del arnés; ver [`../harness/SKILL.md`](../harness/SKILL.md)).
 5. **Git-safe** — they **never** commit, merge, push, `--amend`, or `--no-verify`. The output is a written document the user reviews and commits when ready.
 6. **DB scripts-only** — `export-scripts` ships migration SCRIPTS as a bundle; it **never executes** DDL/DML (a human/DBA applies them).
 

package/skills/w/exports/export-diagrams/SKILL.md

@@ -60,7 +60,7 @@ En plan mode **describe**, no escribe: el motor resuelto, los niveles/secciones
 
 **MCP read-only** (opcional, solo si se pide modelo de datos y está configurado): `\d <tabla>`, `SELECT count(*)`, relaciones FK para el `erDiagram`. Con cost guard.
 
-**Args** (sin lifecycle `AskUserQuestion`):
+**Args** (sin *structured-choice* de ciclo de vida — capacidad del arnés; ver [`../../harness/SKILL.md`](../../harness/SKILL.md)):
 
 ```
 /w:export-diagrams [--sessions NNN[,NNN]] [--since sessionNNN] [--source <alias>]

package/skills/w/exports/export-manuals/SKILL.md

@@ -60,7 +60,7 @@ En plan mode **describe**, no escribe: el modo resuelto, los temas detectados (c
 - `docs/manuals/INDEX.md` — re-generable (sobrescribible) en modo `complement`.
 - Código de las fuentes declaradas — lectura para describir el comportamiento.
 
-**Args** (sin lifecycle `AskUserQuestion`):
+**Args** (sin *structured-choice* de ciclo de vida — capacidad del arnés; ver [`../../harness/SKILL.md`](../../harness/SKILL.md)):
 
 ```
 /w:export-manuals [--sessions NNN[,NNN]] [--since sessionNNN] [--source <alias>]
@@ -123,5 +123,5 @@ Si `--dry-run`: imprimir el reporte; no escribir. Si no: `complement` → `Write
 
 - Design: `docs/referencias/workflow-exports/export-manuals.md` · familia: [`../README.md`](../README.md).
 - Capacidad compuesta: `writing` (built-in default; ver `docs/referencias/workflow-skills/`).
-- Artefactos fuente: `DECISION` + plan-doc (ver `docs/referencias/workflow-artifacts/artifacts-dev/` y `docs/specs`/`docs/plans`).
+- Artefactos fuente: `DECISION` + plan-doc (ver `docs/referencias/workflow-artifacts/artifacts-exec/` y `docs/specs`/`docs/plans`).
 - Siblings: [`../export-scripts/SKILL.md`](../export-scripts/SKILL.md) · [`../export-diagrams/SKILL.md`](../export-diagrams/SKILL.md) · [`../export-reports/SKILL.md`](../export-reports/SKILL.md).

package/skills/w/exports/export-reports/SKILL.md

@@ -57,7 +57,7 @@ En plan mode **describe**, no escribe: la audiencia/longitud resuelta, las sesio
 
 - `docs/specs`, `docs/plans`, `docs/reports/*` — contexto + no colisionar.
 
-**Args** (sin lifecycle `AskUserQuestion`):
+**Args** (sin *structured-choice* de ciclo de vida — capacidad del arnés; ver [`../../harness/SKILL.md`](../../harness/SKILL.md)):
 
 ```
 /w:export-reports [--sessions NNN[,NNN]] [--since sessionNNN] [--source <alias>]

package/skills/w/exports/export-scripts/SKILL.md

@@ -58,7 +58,7 @@ En plan mode **describe**, no escribe: el `NNN` resuelto, las fuentes detectadas
 
 - `docs/scripts/*.sql` standalone (solo top-level), **excluyendo** cualquier `docs/scripts/NNN-export-scripts-*/` (outputs previos de este export).
 
-**Args** (sin lifecycle `AskUserQuestion`):
+**Args** (sin *structured-choice* de ciclo de vida — capacidad del arnés; ver [`../../harness/SKILL.md`](../../harness/SKILL.md)):
 
 ```
 /w:export-scripts [--sessions NNN[,NNN]] [--since sessionNNN] [--source <alias>]

package/skills/w/harness/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: harness
+description: >-
+  Harness-agnostic capability layer for agent-workflow. Read-and-follow doc (no es
+  invocable por nombre): define el contrato que mantiene a la herramienta agnóstica al
+  arnés (Claude Code, Codex, opencode, Gemini CLI, genérico) sin renunciar a las
+  capacidades ricas de cada uno. Cataloga las capacidades de las que depende el
+  workflow, las liga al mecanismo concreto de cada arnés (binding matrix), y fija los
+  dos principios (capacidad-no-tool · progressive-enhancement). Referenciado desde
+  SKILL.md (overview) y los loops cuando nombran structured-choice / compaction.
+---
+
+# harness — capa de capacidades agnóstica al arnés (cross-cutting)
+
+Doc de **lectura y seguimiento** (no se invoca por nombre). Aquí vive el contrato que mantiene a agent-workflow **agnóstico al arnés** (Claude Code, Codex, opencode, Gemini CLI, …) sin renunciar a las capacidades ricas de cada uno. Referenciado desde `../SKILL.md` (overview) y desde los loops cuando nombran una capacidad (`structured-choice`, `compaction`, …).
+
+## El problema
+
+La doctrina (comandos + loops + artefactos) describe **qué** hace la IA, no **con qué tool** de un arnés concreto. El vocabulario natural arrastra mecanismos específicos de Claude Code —`AskUserQuestion`, `/compact`, `$ARGUMENTS`, `Task`/`Agent`— como si fueran universales. Este documento los abstrae: la doctrina referencia **capacidades**; aquí se mapea cada capacidad al **mecanismo concreto** de cada arnés.
+
+## Dos principios
+
+1. **Capacidad, no tool.** Los loops/comandos nombran una **capacidad** abstracta (ej. *structured-choice*, *compaction*). Una sola tabla —esta— la liga al mecanismo de cada arnés. Cambiar de arnés = cambiar de columna, no de doctrina.
+2. **Progressive enhancement.** Usá el mecanismo **más rico** que ofrezca el arnés; **degradá** a un fallback universal cuando no exista. Así se cumple a la vez "agnóstica al arnés" **y** "aprovechar las capacidades de cada uno".
+
+> **Simetría con la cascada de skills (`.workflow/skills.toml`):** esa categoría liga **roles → skills** por config; esta liga **capacidades → mecanismos del arnés** por detección. Mismo patrón (binding + default), distinto eje: una es *qué saber compone el loop*, la otra es *con qué primitivas del host se ejecuta*.
+
+## Capability catalog
+
+Las capacidades de las que depende el harness, con su fallback universal (lo que se usa si el arnés no ofrece algo mejor):
+
+| Capability | Qué necesita el workflow | Fallback universal (mínimo común) |
+|---|---|---|
+| **command-invocation** | el usuario dispara un flujo por nombre (`spec-new`, `plan-exec`, …) | el usuario escribe "corré el procedimiento `<cmd>`" y la IA lee su doc |
+| **procedure-loading** | cargar la doctrina de un loop/comando | la IA **lee el `.md`** del loop y lo sigue (read-and-follow) |
+| **structured-choice** | preguntar al humano ≤3 preguntas de contenido **+ siempre** un control `flow` (`Compactar`/`Cerrar`) por un canal lateral | pregunta en **markdown numerado** en el chat; el control `flow` se ofrece como una opción más |
+| **compaction** | encoger el contexto sin perder el hilo | escribir `CHECKPOINT` y pedir al usuario reiniciar el contexto y reanudar (resume keya off `CHECKPOINT`) |
+| **subagent-dispatch** | *(opcional)* paralelizar breadth de research | research **inline secuencial** en la misma session (es el default igual) |
+| **persistent-context** | bloque `WORKSPACE` + convenciones siempre presentes | archivo de contexto del repo (**`AGENTS.md`** estándar; `CLAUDE.md` en Claude Code) |
+| **external-data** | lecturas read-only de BD u otras fuentes para research/validación | **MCP** (ampliamente soportado); si no hay, el gap se degrada a pregunta-al-humano |
+| **dry-run / preview** | previsualizar lo que haría un comando sin escribir | el comando **describe** el cambio en vez de aplicarlo (ej. `spec-new` lista el borrador sin crear el archivo) |
+
+> **Las capacidades `must` para el ciclo de un loop son solo dos**: `structured-choice` y `compaction`. Ambas degradan a un fallback puramente textual → **cualquier** arnés con chat + sistema de archivos corre el modelo completo. El resto (subagents, MCP, slash commands, skills nativas) es *enhancement*.
+
+## Harness binding matrix
+
+Mecanismo concreto por arnés (jun-2026; `~` parcial · `?` sin confirmar).
+
+| Capability | Claude Code | Codex CLI | opencode | Gemini CLI | Genérico |
+|---|---|---|---|---|---|
+| command-invocation | `.claude/commands/` (slash) | skills (prompts custom **deprecados**) | `.opencode/commands/` | `.gemini/commands/*.toml` | texto |
+| procedure-loading | skills `SKILL.md` | skills `SKILL.md` | skills `SKILL.md` | skills (extensiones) | read-and-follow `.md` |
+| structured-choice | `AskUserQuestion` (**solo main-agent**) | — | — | — | markdown numerado |
+| compaction | `/compact` | `?` | `?` | `?` | CHECKPOINT + resume |
+| subagent-dispatch | `Task` (paralelo) | agents (depth=1) | Explore/Scout | agents | inline |
+| persistent-context | `CLAUDE.md` (**no** lee AGENTS.md → symlink) | `AGENTS.md` | `AGENTS.md` | `AGENTS.md`/`GEMINI.md` | `AGENTS.md` |
+| external-data | MCP | MCP | MCP | MCP | — |
+| dry-run / plan | plan mode (enforced) | `/plan` (prompt, **no** enforced) | Plan agent | plan mode | describir sin escribir |
+
+> **Notas (investigación de campo jun-2026):** las **skills `SKILL.md`** son la unidad portable **universal** (las cinco las soportan; Codex deprecó los prompts custom) → la doctrina se empaqueta como skill. La **elección estructurada** (`AskUserQuestion`) es **solo de Claude Code y solo del main-agent** → en el resto, `structured-choice` degrada a markdown numerado. El **plan mode** está *enforced* solo en Claude Code/opencode (prompt-level en Codex) → **no se confía para safety**; el git-safe (invariante #5) es propio. **MCP** es universal. El **piso garantizado** (última columna) corre el modelo completo.
+
+## Leverage installed skills
+
+"Aprovechar las skills que el arnés tenga instaladas" se resuelve por el **mismo binding** de `.workflow/skills.toml`: un rol puede apuntar a una skill **instalada en el host** (de tercero, vía skills.sh) en vez del built-in. Regla:
+
+- Si el host tiene una skill **mejor** para un rol (ej. un generador de diagramas superior para `diagrams`, un linter de estándares para `coding-standards`), se la **bindea** en `.workflow/skills.toml` y el loop la compone sin cambios.
+- El built-in default es el **piso**, no el techo: garantiza que el rol funcione en cualquier host; el binding lo **enriquece** donde el host puede más.
+
+## Convención para el resto del corpus
+
+- Los loops/comandos referencian la **capacidad** por nombre (ej. "*structured-choice* (ver `harness/SKILL.md`)"), **no** el tool concreto.
+- El nombre histórico `AskUserQuestion` se conserva **solo** como el binding Claude-Code de `structured-choice` (esta tabla), no como vocabulario de la doctrina.
+- El control de ciclo de vida `flow` (`Compactar`/`Cerrar`) es parte de la capacidad `structured-choice`, no de un tool: en arneses sin elección estructurada se ofrece como una opción textual más.
+
+## Distribution (install-time)
+
+Patrón probado (Spec Kit, 30+ agentes): **una fuente canónica** + generar/symlinkear a los dirs por-arnés en la instalación (`.claude/`, `.codex/`, `.gemini/`, …). agent-workflow ya lo hace vía `aw self install-skill`. Convención recomendada: **`AGENTS.md` canónico + `CLAUDE.md` symlink** (Claude Code no lee `AGENTS.md` nativo; el resto sí).
+
+## Command packaging (harness-specific)
+
+El **contrato** de cada comando (Flow, Trigger, Input, Mode, …) es agnóstico. El **archivo** que el arnés ejecuta envuelve ese contrato en su formato nativo: Claude Code = slash-command con frontmatter (`description`, `argument-hint`, `allowed-tools`) + cuerpo que invoca la skill o el `aw` CLI; Codex = skill (los prompts custom en `~/.codex/prompts/` están deprecados); otros, su equivalente. El contrato no cambia; el envoltorio sí (otra columna). El comportamiento en *dry-run / plan mode* (previsualizar sin escribir) se documenta en el cuerpo del comando cuando aplica.
+
+## Status
+
+Modelo de capacidades + matriz de binding **definidos** y **validados** con investigación de campo (jun-2026). El piso universal (`AGENTS.md` + texto + archivos + skills) corre el modelo completo hoy.

package/skills/w/loops/README.md

@@ -14,18 +14,18 @@ Propiedades comunes a **los 4 loops**:
 
 1. **Gap-driven convergente** — cada ciclo: `detect_gaps` → resolver (humano o research) → integrar → repetir hasta que no queden gaps materiales. Los gaps "agotados" (límite `MAX` de intentos) no se re-disparan → garantiza convergencia.
 2. **Una sola session por run + research inline** — el loop crea **una** session en `.workflow/sessions/` (la dueña del run) y maneja **sus** artefactos. La **investigación es inline**: una actividad dentro de esa misma session que escribe `ANALYSIS-FILE`/`CONCLUSIONS` (+ `SCRIPTS.sql` read-only si consulta BD) en su propia carpeta — ya no es una session aparte. **El usuario nunca crea sessions.** Los artefactos son el **registro vivo** del run — **ciclo artifact-first**: sembrar `CHECKPOINT.Pending/Next` (la intención) antes de ejecutar, llevar a `Completed`/DECISION después; CHECKPOINT actualizado en cada límite de gap/fase, BACKLOG solo si difiere. El spec/plan es la base guía.
-3. **AskUserQuestion con dos tipos de tab** (límite host: 4 preguntas/llamada):
-   - **tab(s) de contenido** (≤3) — la(s) pregunta(s) real(es) del momento (resolver una duda, elegir MCP, o en convergencia: `Guardar` / `Preguntar algo más`).
-   - **tab `flow`** (1, SIEMPRE presente) — control de ciclo de vida por un canal lateral. Así el contenido lo maneja la IA y el ciclo de vida lo dirige el humano.
+3. **Structured-choice con dos planos** (capacidad del arnés — ver [`../harness/SKILL.md`](../harness/SKILL.md); en **Claude Code** es `AskUserQuestion`, máx 4 preguntas/llamada → **≤3 + 1 control `flow`**; sin elección estructurada degrada a markdown numerado):
+   - **pregunta(s) de contenido** (≤3) — la(s) pregunta(s) real(es) del momento (resolver una duda, elegir MCP, o en convergencia: `Guardar` / `Preguntar algo más`).
+   - **control `flow`** (1, SIEMPRE presente) — control de ciclo de vida por un canal lateral. Así el contenido lo maneja la IA y el ciclo de vida lo dirige el humano.
 4. **Escribe solo en su propia carpeta `docs/`** — y **nunca** gradúa/exporta otros artefactos a `docs/`. Esa promoción la hacen las skills `export-*`, aparte y explícita.
 
-## flow tab — options
+## flow control — options
 
-El tab `flow` es **fijo**: `Compactar` / `Cerrar`, presente en los 4 loops. Responder el tab de contenido **sin tocar `flow`** = seguir iterando ("continuar" es el comportamiento por defecto del loop, no una opción del canal de control).
+El control `flow` es **fijo**: `Compactar` / `Cerrar`, presente en los 4 loops. Responder la pregunta de contenido **sin tocar `flow`** = seguir iterando ("continuar" es el comportamiento por defecto del loop, no una opción del canal de control).
 
 | Option | What it does |
 |---|---|
-| `Compactar` | Escribe `CHECKPOINT` (session dueña del run) + dispara `/compact` del host y reanuda sin perder el hilo. |
+| `Compactar` | Escribe `CHECKPOINT` (session dueña del run) + dispara la **compactación** del arnés (en Claude Code: `/compact`; ver [`../harness/SKILL.md`](../harness/SKILL.md)) y reanuda sin perder el hilo. |
 | `Cerrar` | `finalize`: persiste lo pendiente (`CHECKPOINT` siempre; `BACKLOG` solo si hay algo diferido), cierra la session y termina el loop. |
 
 ## Loops and their flow
@@ -33,8 +33,8 @@ El tab `flow` es **fijo**: `Compactar` / `Cerrar`, presente en los 4 loops. Resp
 | Loop (`name:`) | Flow | Started by | Reads | Writes |
 |---|---|---|---|---|
 | [`spec-refine-loop`](spec-refine-loop/SKILL.md) | SPEC | `/w:spec-refine` | `docs/specs/NNN-spec*.md` (el spec mismo) | `docs/specs/NNN-spec-<slug>.md` (in place) |
-| [`plan-new-loop`](plan-new-loop/SKILL.md) | PLANIFICATION | `/w:plan-new` | `docs/specs/NNN-spec-*.md` | `docs/plans/PPP-plan-<slug>.md` |
-| [`plan-exec-loop`](plan-exec-loop/SKILL.md) | PLANIFICATION | `/w:plan-exec` | `docs/plans/PPP-plan-*.md` | `docs/plans/PPP-plan-<slug>.md` (update) + `docs/tools`; resto vía `export-*` |
+| [`plan-new-loop`](plan-new-loop/SKILL.md) | PLAN | `/w:plan-new` | `docs/specs/NNN-spec-*.md` | `docs/plans/PPP-plan-<slug>.md` |
+| [`plan-exec-loop`](plan-exec-loop/SKILL.md) | PLAN | `/w:plan-exec` | `docs/plans/PPP-plan-*.md` | `docs/plans/PPP-plan-<slug>.md` (update) + `docs/tools`; resto vía `export-*` |
 | [`quick-loop`](quick-loop/SKILL.md) | QUICK | `/w:quick` | — (prompt) | edita código + session ligera; **no** `docs/` |
 
 > `/w:spec-new` no tiene loop (es single-pass). Por eso hay **5 comandos / 4 loops**.
@@ -46,14 +46,14 @@ Los loops **nunca** graduan/exportan artefactos a `docs/` automáticamente. Cada
 | Flow | Carpetas `docs/` que escribe |
 |---|---|
 | SPEC | `docs/specs` |
-| PLANIFICATION | `docs/plans` (living) + `docs/tools` (herramientas creadas — salida directa) |
+| PLAN | `docs/plans` (living) + `docs/tools` (herramientas creadas — salida directa) |
 | QUICK | ninguna |
 
 Todo lo demás (migraciones → `docs/scripts`, manuales → `docs/manuals`, diagramas → `docs/diagrams`, informes → `docs/reports`) queda como **artefacto de session** hasta que un `export-*` lo promueva, como paso aparte y explícito.
 
-## Loops × flow tab
+## Loops × flow control
 
-| Loop | tab(s) de contenido típicos | tab `flow` |
+| Loop | pregunta(s) de contenido típicas | control `flow` |
 |---|---|---|
 | `spec-refine-loop` | dudas-de-humano · elección de MCP · convergencia (`Guardar especificación refinada` / `Preguntar algo más`) | `Compactar` / `Cerrar` |
 | `plan-new-loop` | dudas · elección de MCP · convergencia (`Guardar plan` / `Preguntar algo más`) | `Compactar` / `Cerrar` |
@@ -64,7 +64,7 @@ Todo lo demás (migraciones → `docs/scripts`, manuales → `docs/manuals`, dia
 
 | Field | Description |
 |---|---|
-| `## Flow` | A qué flujo pertenece (SPEC · PLANIFICATION · QUICK) |
+| `## Flow` | A qué flujo pertenece (SPEC · PLAN · QUICK) |
 | `## Layer` | Siempre 2 (la IA lo corre entero) |
 | `## Started by` | Comando `/w:…` que lo arranca (reanudable) |
 | `## Reads` | Documento(s) de entrada |
@@ -73,7 +73,7 @@ Todo lo demás (migraciones → `docs/scripts`, manuales → `docs/manuals`, dia
 | `## Sequence` | Pseudocódigo + mermaid del loop |
 | `## Convergence / exit` | Cuándo para |
 
-El **chasis** (`spec-refine-loop`) además detalla `## Composes` (capacidades que compone), `## Deliverable schema`, `## Gap taxonomy`, `## Ask-vs-research rule`, `## Research: autonomy, scope & failure`, `## AskUserQuestion`, `## Compact / resume`, `## Integration`.
+El **chasis** (`spec-refine-loop`) además detalla `## Composes` (capacidades que compone), `## Deliverable schema`, `## Gap taxonomy`, `## Ask-vs-research rule`, `## Research: autonomy, scope & failure`, `## Structured-choice`, `## Compact / resume`, `## Integration`.
 
 Los **heirs** (`plan-new-loop`, `plan-exec-loop`, `quick-loop`) usan `## Inherits` (lo que reusan del chasis, sin repetirlo) + `## Delta N` (sus diferencias).
 
@@ -81,7 +81,7 @@ Los **heirs** (`plan-new-loop`, `plan-exec-loop`, `quick-loop`) usan `## Inherit
 
 ```
 spec-refine-loop  ── CHASIS (patrón de referencia: motor gap-driven, sesión única,
-        │            AskUserQuestion + tab flow, research autónomo INLINE + regla BD,
+        │            structured-choice + control flow, research autónomo INLINE + regla BD,
         │            compact/resume, artefactos como log vivo: CHECKPOINT siempre,
         │            BACKLOG solo si difiere)
         ├── plan-new-loop   (heir)  → deltas: plan rico, gap taxonomy de plan

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

@@ -5,7 +5,7 @@ description: >-
   doc: lo lee y actualiza fase a fase mientras edita el código real, gestiona BD
   y git. Heir del chasis spec-refine-loop: reusa su motor gap-driven (aplicado
   dentro de una tarea ante decisiones/dudas no obvias), research inline con
-  regla BD read-only, AskUserQuestion con ≤3 tabs de contenido + 1 tab flow
+  regla BD read-only, structured-choice con ≤3 preguntas de contenido + 1 control flow
   (Compactar/Cerrar) siempre, y artefactos como log vivo (CHECKPOINT siempre,
   BACKLOG solo si difiere). Sus deltas: una sola session por run (resume vía
   checkbox del plan-doc + CHECKPOINT); git seguro (verifica rama esperada antes
@@ -20,10 +20,10 @@ description: >-
 
 # plan-exec-loop
 
-> **Heir** del chasis [`spec-refine-loop`](../spec-refine-loop/SKILL.md). Aquí los **deltas de ejecución** — el trabajo real: código, BD, git. El motor (gap-driven, research inline, AskUserQuestion + tab `flow`, compact/resume, artefactos como log vivo) vive en el chasis.
+> **Heir** del chasis [`spec-refine-loop`](../spec-refine-loop/SKILL.md). Aquí los **deltas de ejecución** — el trabajo real: código, BD, git. El motor (gap-driven, research inline, structured-choice + control `flow`, compact/resume, artefactos como log vivo) vive en el chasis.
 
 ## Flow
-PLANIFICATION
+PLAN
 
 ## Layer
 2 — la IA lo corre entero.
@@ -32,7 +32,7 @@ PLANIFICATION
 `/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 de `$ARGUMENTS`).
+`docs/plans/PPP-plan-<slug>.md` (localizar vía glob `docs/plans/PPP-plan-*.md` o la ruta exacta del argumento del comando).
 
 ## Writes
 - `docs/plans/PPP-plan-<slug>.md` (**read/update**, living doc: estado de fases/tareas, `Open questions`).
@@ -48,8 +48,8 @@ Este loop **nunca gradúa/promueve artefactos** a `docs/`. Las únicas carpetas
 
 Del chasis [`spec-refine-loop`](../spec-refine-loop/SKILL.md), sin cambios:
 
-- Motor **gap-driven** (aplica *dentro de una tarea* ante una decisión/duda no obvia: research inline ó AskUserQuestion).
-- **AskUserQuestion**: ≤3 contenido + 1 `flow` (`Compactar`/`Cerrar`) siempre.
+- Motor **gap-driven** (aplica *dentro de una tarea* ante una decisión/duda no obvia: research inline ó structured-choice).
+- **Structured-choice**: ≤3 preguntas de contenido + 1 control `flow` (`Compactar`/`Cerrar`) siempre (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) + research **inconclusa** (degrada/difiere, límite `MAX`).
 - **Compact/resume**; **artefactos como log vivo** (`CHECKPOINT` siempre; `BACKLOG` solo si difiere).
 
@@ -95,10 +95,12 @@ Distinción por **ejecución**, no por archivo (ver el esquema `SCRIPTS.sql`):
 - Validación que **corre y falla** → vuelve a la tarea (gap); no avanza.
 - **Validación dependiente de una migración no aplicada**: como la IA no ejecuta el DML, **no puede correr read-only** → se **difiere** (handoff a DBA), **no bloquea el avance**. Se registra en `Open questions` del plan + `BACKLOG`, marcando "verificación pendiente tras aplicar SQL". (Reusa el patrón degradar/diferir + límite `MAX` del chasis → evita el bucle "vuelve a la tarea".)
 
+> La **validación final** es el **convergence gate** de PLAN-exec (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).
+
 ## Delta 5 — 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 → `AskUserQuestion` final (contenido: `Marcar plan done` / `Preguntar algo más`; flow: `Compactar`/`Cerrar`).
+- Todas las fases done → *structured-choice* final (contenido: `Marcar plan done` / `Preguntar algo más`; flow: `Compactar`/`Cerrar`).
 - **Sin export automático**: los artefactos (`SCRIPTS.sql`, `DECISION`, …) quedan en la session. Promoverlos a `docs/` (scripts, manuals, …) es un paso aparte vía `export-*`.
 
 ## Sequence
@@ -120,7 +122,7 @@ plan-exec-loop(PPP-plan-<slug>.md):
         si consulta BD read-only → SCRIPTS.sql + ejecutar read-only
         si cambio BD (DDL/DML) → redactar en SCRIPTS.sql (artefacto session, NO ejecutar)
         si decisión no obvia → DECISION (etiquetado por fase/tarea, en el ÚNICO DECISION)
-        si duda/gap → research inline ó AskUserQuestion    # chasis
+        si duda/gap → research inline ó structured-choice    # chasis
       marcar Task - [x] + estado EN EL PLAN                # DESPUÉS de completar la Task (el plan-doc es la fuente de verdad por tarea)
     validación de la fase:
         la que corre y falla → volver a la tarea
@@ -130,7 +132,7 @@ plan-exec-loop(PPP-plan-<slug>.md):
         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)
-  AskUserQuestion(contenido: [Marcar plan done, Preguntar algo más], flow: [Compactar, Cerrar])
+  structured_choice(contenido: [Marcar plan done, Preguntar algo más], flow: [Compactar, Cerrar])
   marcar plan done (o "done — SQL pendiente de aplicar")
   # NO export: los artefactos quedan en la session; un export-* los promueve aparte
 finalize: CHECKPOINT (+ BACKLOG si difiere) + cerrar session + reportar
@@ -153,11 +155,11 @@ flowchart TD
     CM -->|aprobado| P
     CM -->|rechazado| RJ["cambios quedan · registrar 'sin commitear'"]
     RJ --> P
-    V2 --> FIN["AskUserQuestion[Marcar plan done · Preguntar más]<br/>plan done (sin auto-export)"]
+    V2 --> FIN["structured-choice[Marcar plan done · Preguntar más]<br/>plan done (sin auto-export)"]
 ```
 
 ## Convergence / exit
 
 - Plan completo + validación OK (o diferida con handoff) → `Marcar plan done`.
-- `Cerrar` (tab flow, en cualquier momento) → `finalize` persiste `CHECKPOINT` (y `BACKLOG` solo si quedó algo sin ejecutar / sin commitear / sin aplicar), cierra la session, reporta.
+- `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

@@ -4,7 +4,7 @@ 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 spec-refine-loop:
   reusa íntegro su motor gap-driven convergente, su única session por run,
-  research INLINE, AskUserQuestion con ≤3 tabs de contenido + 1 tab flow
+  research INLINE, structured-choice con ≤3 preguntas de contenido + 1 control flow
   (Compactar/Cerrar) siempre presente, research autónomo con regla BD read-only,
   y artefactos como log vivo (CHECKPOINT siempre, BACKLOG solo si difiere). Sus
   deltas: el plan absorbe inline el nivel TECHNICAL-NOTE
@@ -19,10 +19,10 @@ description: >-
 
 # plan-new-loop
 
-> **Heir** del chasis [`spec-refine-loop`](../spec-refine-loop/SKILL.md). Aquí **solo** los deltas. El motor (gap-driven, sesión única, AskUserQuestion + tab `flow`, research inline + regla BD, compact/resume, artefactos como log vivo) vive en el chasis — no se repite.
+> **Heir** del chasis [`spec-refine-loop`](../spec-refine-loop/SKILL.md). Aquí **solo** los deltas. El motor (gap-driven, sesión única, structured-choice + control `flow`, research inline + regla BD, compact/resume, artefactos como log vivo) vive en el chasis — no se repite.
 
 ## Flow
-PLANIFICATION
+PLAN
 
 ## Layer
 2 — la IA lo corre entero.
@@ -31,7 +31,7 @@ PLANIFICATION
 `/w:plan-new` — **reanudable** (mismo mecanismo del chasis, keyado off CHECKPOINT).
 
 ## Reads
-`docs/specs/NNN-spec-*.md` (glob — localiza el spec por número; o la ruta exacta de `$ARGUMENTS`). **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.
+`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.
@@ -44,7 +44,7 @@ Del chasis [`spec-refine-loop`](../spec-refine-loop/SKILL.md), sin cambios:
 
 - Motor **gap-driven convergente** + **ciclo artifact-first** del chasis (sembrar `CHECKPOINT.Pending/Next` ANTES → `detect_gaps` → resolver → integrar → actualizar `Pending→Completed` DESPUÉS; gaps agotados con límite `MAX` no se re-disparan).
 - **Una sola session por run**: descriptor `plan-new` → `NNN-plan-new` (Type = `refine`): `SESSION` + `CHECKPOINT` (+ `BACKLOG` solo si difiere). La **investigación es inline** dentro de esta session (produce `ANALYSIS-FILE`/`CONCLUSIONS` + `SCRIPTS.sql` read-only en su propia carpeta), no una session aparte.
-- **AskUserQuestion**: ≤3 tabs de contenido + 1 tab `flow` (`Compactar`/`Cerrar`) siempre.
+- **Structured-choice**: ≤3 preguntas de contenido + 1 control `flow` (`Compactar`/`Cerrar`) siempre (capacidad del arnés — ver [`../../harness/SKILL.md`](../../harness/SKILL.md); en Claude Code es `AskUserQuestion`).
 - **Ask-vs-research rule** + **research autónomo inline** + **regla BD** (pregunta MCP si >1 sin default → queries a `SCRIPTS.sql` → ejecuta read-only, `sql-mutation-guard`) + manejo de research **inconclusa** (degrada a humano / difiere a `Open questions` + límite `MAX`).
 - **Compact / resume** y **artefactos como log vivo (ciclo artifact-first)** (`CHECKPOINT` siempre; `BACKLOG` solo si difiere).
 - **Naming + numeración global** del chasis: `<run>` = descriptor `plan-new`. El CLI antepone el `NNN` global y secuencial (sin reiniciar por tipo); el caller pasa solo el descriptor.
@@ -59,22 +59,24 @@ El plan absorbe el nivel `TECHNICAL-NOTE` **inline** (decisión del usuario) + r
 > Derivado de docs/specs/NNN-spec-<slug>.md · generado por plan-new-loop
 
 ## Origin              spec fuente (o prompt, si se bootstrapeó vía spec-new)
-## Summary             el cómo, en 1–2 frases
-## Solution            explicación técnica/funcional de cómo se implementará
-## Impacted            FE · BE · BD (esquemas/tablas/funciones) · APIs · integraciones
-## Dependencies        docs / fuentes / bases / sesiones
-## Current state (AS-IS)   wiring actual (interfaces y métodos), resumido
-## Target state (TO-BE)    wiring objetivo
-## Final behavior      cómo se comporta el flujo al final (alineado con criterios del spec)
-## Phases              fases agrupadoras (complejidad XS–S)
-## Tasks               tareas por fase (≤XS), con deps y estado vivo (- [ ])
-## Validations         validaciones / restricciones / lógica de negocio
-## Risks / impact      riesgos e impactos técnicos
-## Assumptions         supuestos
-## Estimated time      sizing XS–XL (desarrollo + pruebas internas)
-## Open questions      pendientes
+## Summary             el cómo, en 1–2 frases                                   (core)
+## Solution            explicación técnica/funcional de cómo se implementará    (core)
+## Impacted            FE · BE · BD (esquemas/tablas/funciones) · APIs · integr. (core)
+## Dependencies        docs / fuentes / bases / sesiones                        (opt.)
+## Current state (AS-IS)   wiring actual (interfaces y métodos), resumido        (opt.)
+## Target state (TO-BE)    wiring objetivo                                       (opt.)
+## Final behavior      cómo se comporta el flujo al final (alineado con criterios del spec) (core)
+## Phases              fases agrupadoras (complejidad XS–S)                      (core)
+## Tasks               tareas por fase (≤XS), con deps y estado vivo (- [ ])     (core)
+## Validations         validaciones / restricciones / lógica de negocio         (core)
+## Risks / impact      riesgos e impactos técnicos                              (opt.)
+## Assumptions         supuestos                                                (opt.)
+## Estimated time      sizing XS–XL (desarrollo + pruebas internas)             (opt.)
+## Open questions      pendientes                                               (core)
 ```
 
+> **Escala con complejidad:** las `(core)` van **siempre**; las `(opt.)` solo si el plan lo amerita — un plan chico puede omitir `Dependencies`, AS-IS/TO-BE, `Risks`, `Assumptions`, `Estimated time`. Conciso > exhaustivo.
+
 > **Implicación de catálogo:** `TECHNICAL-NOTE` deja de ser artefacto de session y se vuelve **secciones del plan-doc**. Reconciliado en [`plan-exec-loop`](../plan-exec-loop/SKILL.md): la única plan-exec session **no** lleva `TECHNICAL-NOTE` ni `TASKS` propios; el detalle técnico y el progreso viven inline en el plan-doc (living).
 
 ## Delta 2 — Gap taxonomy (de "plan")
@@ -90,12 +92,12 @@ Reemplaza la gap taxonomy de spec por una orientada a planificación:
 | Tarea no atómica | complejidad > XS | la IA re-parte |
 | 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 | — | humano |
+| Riesgos sin atender | riesgos técnicos sin mitigar/declarar | humano |
 
 ## 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 tab de contenido si >1 sin default).
+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).
 
 ## Convergence / exit
 
-Sin gaps materiales → `AskUserQuestion` (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; 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.