@tacuchi/agent-workflow-cli 13.0.0 → 13.0.2

package/README.md

@@ -16,14 +16,14 @@ The harness has three layers plus a permanent `docs/` zone:
 
 - **Layer 1 · Commands** (`/w:*`) — the only thing the user invokes:
   - **SPEC** — `/w:spec-new` (single-pass draft) → `/w:spec-refine` (gap-driven loop) → `docs/specs/`.
-  - **PLANIFICATION** — `/w:plan-new` → `/w:plan-exec` → `docs/plans/` + `docs/tools/`.
+  - **PLAN** — `/w:plan-new` → `/w:plan-exec` → `docs/plans/` + `docs/tools/`.
   - **QUICK** — `/w:quick` — lightweight shortcut.
   - **EXPORTS** — `/w:export-scripts` · `export-manuals` · `export-diagrams` · `export-reports` (the only path that promotes artifacts to `docs/`).
   - **Bootstrap** — `/w:workspace-init` turns any folder into a workspace (1+ sources; no project/hub distinction).
-- **Layer 2 · Loops** — the AI runs them whole: `spec-refine-loop` (chassis) · `plan-new-loop` · `plan-exec-loop` · `quick-loop`. Gap-driven, with `AskUserQuestion` lifecycle control (compact/close) and resumable `CHECKPOINT`.
+- **Layer 2 · Loops** — the AI runs them whole: `spec-refine-loop` (chassis) · `plan-new-loop` · `plan-exec-loop` · `quick-loop`. Each loop is a **persistent goal** that runs until its success criteria are green (verification-first); gap-driven, with **structured-choice** lifecycle control (compact/close — `AskUserQuestion` on Claude Code, numbered markdown elsewhere) and resumable `CHECKPOINT`.
 - **Layer 3 · Sessions + artifacts** — internal, ephemeral process state under `.workflow/sessions/` (`SESSION` · `CHECKPOINT` · `BACKLOG` · `SCRIPTS.sql` · `ANALYSIS-FILE` · `CONCLUSIONS` · `DECISION` · …). Sessions are slug-named folders, created by loops, never by the user.
 
-**Pluggable capabilities.** Loops compose capability **roles** (`ui-design`, `sql`, `git`, `coding-standards`, `writing`, `research`, `testing`, `tools`, `diagrams`, `overview`); the concrete skill bound to each role is resolved via `.workflow/skills.toml` (cascade: built-in default → `~/.workflow/skills.toml` → workspace). Inspect bindings with `aw skills`.
+**Pluggable capabilities.** Loops compose capability **roles** (`ui-design`, `sql`, `git`, `research`, `tools`, `diagrams`, `overview`); the concrete skill bound to each role is resolved via `.workflow/skills.toml` (cascade: built-in default → `~/.workflow/skills.toml` → workspace). Inspect bindings with `aw skills`. Code/testing/writing conventions are **not** roles — they're ambient skills the host auto-applies when present, independent of the workflow.
 
 **Invariants.** No auto-export (only `export-*` writes `docs/`); the spec and plan are documents, not artifacts; DB scripts-only (never executes DML/DDL); git-safe (verifies the per-source working branch before edits; proposes commits).
 

package/dist/cli/tui/data/workflow-content.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workflow-content.d.ts","sourceRoot":"","sources":["../../../../src/cli/tui/data/workflow-content.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAEjE,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,eAAe,EAAE,cAAc,EAAE,CAAC;IAClC,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,KAAK,EAAE,SAAS,EAAE,CAAC;CACpB;AAED,eAAO,MAAM,gBAAgB,EAAE,eAiL9B,CAAC"}
+{"version":3,"file":"workflow-content.d.ts","sourceRoot":"","sources":["../../../../src/cli/tui/data/workflow-content.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAEjE,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,eAAe,EAAE,cAAc,EAAE,CAAC;IAClC,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,KAAK,EAAE,SAAS,EAAE,CAAC;CACpB;AAED,eAAO,MAAM,gBAAgB,EAAE,eAsL9B,CAAC"}

package/dist/cli/tui/data/workflow-content.js

@@ -59,9 +59,11 @@ export const WORKFLOW_CONTENT = {
             hook: "—",
         },
     ],
-    // Command families — espejo EXACTO de help-groups.ts (post-cleanup), con
-    // los nombres de comandos realmente registrados en main.ts. `workspace-init`
-    // y `set-working-branch` viven bajo Sources / Branches.
+    // Command families — vista del TUI alineada con help-groups.ts (post-cleanup),
+    // con los nombres realmente registrados en main.ts. Algunas familias se
+    // enriquecen con subcomandos (Hooks/MCP/Self) para orientar; `workspace-init`
+    // se surface también aquí (además de su phase card) por descubribilidad. Los
+    // totales se derivan con `.length` — NO hardcodear cantidades en strings.
     commandFamilies: [
         {
             id: "session",
@@ -84,6 +86,9 @@ export const WORKFLOW_CONTENT = {
             items: [
                 "sources",
                 "set-working-branch",
+                "set-qa-branch",
+                "git-flow",
+                "merge-state",
                 "workspace-init",
                 "attach-multiroot",
                 "detach-multiroot",

package/dist/cli/tui/data/workflow-content.js.map

@@ -1 +1 @@
-{"version":3,"file":"workflow-content.js","sourceRoot":"","sources":["../../../../src/cli/tui/data/workflow-content.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"workflow-content.js","sourceRoot":"","sources":["../../../../src/cli/tui/data/workflow-content.ts"],"names":[],"mappings":"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"}

package/package.json

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

@@ -185,4 +185,4 @@ Ninguno. Es orientación pura: no escribe documentos ni artefactos.
 
 ## Source
 
-Autorada del modelo de diseño (`docs/referencias/`): README de arquitectura (3 capas + 6 invariantes), `workflow-commands/`, `workflow-loops/`, `workflow-artifacts/`, `workflow-exports/`, `workflow-skills/`, `workflow-harness/`. Modelo actual, desplegado. (Compat: reemplaza la orientación del bundle legacy `session` + flows dev/design/analyze.)
+Autorada del modelo de diseño (`docs/referencias/`): README de arquitectura (3 capas + 6 invariantes), `workflow-commands/`, `workflow-loops/`, `workflow-artifacts/`, `workflow-exports/`, `workflow-roles/`, `workflow-skills/`, `workflow-harness/`. Modelo actual, desplegado. (Compat: reemplaza la orientación del bundle legacy `session` + flows dev/design/analyze.)

package/skills/w/artifacts/README.md

@@ -60,4 +60,4 @@ Sessions are created by the loops as needed — **one session per run**. The ses
 1. **No auto-export**: loops **never** graduate/export to `docs/`. Only `export-*` does, explicitly.
 2. **Each flow touches only its `docs/` folders**: SPEC→`specs` · PLAN→`plans`+`tools` · QUICK→none · rest→`export-*`.
 3. **Spec and plan are documents** (`docs/`), not artifacts — they never live inside a session.
-4. **DB write-only scripts**: 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.
+4. **DB scripts-only**: the AI **never executes DML/DDL**; migrations stay in `SCRIPTS.sql` (type B) and are delivered via `export-scripts`. Only read-only queries (type A) are executed via MCP.

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

@@ -2,7 +2,7 @@
 
 > What it is: the live resume state of a session — lets the loop resume exactly where it left off.
 > **Live log (artifact-first):** `Pending`/`Next` = the intent (what is about to be done, seeded BEFORE executing); `Completed` = the result (AFTER). Updated at every gap/phase boundary, not only on `Compactar`/`Cerrar`.
-> Owned by: `refine` sessions (and `exec` / `quick` sessions that carry a checkpoint).
+> Owned by: **every session** (`refine` · `exec` · `quick`). Persisted **always** on close/compact (the resume key — invariant #6), unlike `BACKLOG` which is written only when something is deferred.
 
 ## Activity
 Summary of the activity done so far.

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

@@ -1,6 +1,6 @@
 # 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 **only** as a reference of the technical schema that the plan absorbs — **no `TECHNICAL-NOTE` is created in sessions**. Use it standalone only when the plan-doc approach does not apply (e.g. a `quick` session that needs scoped technical context).
+> **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.
 
 ## Solution
 Technical/functional explanation of how the solution will be implemented.

package/skills/w/artifacts/artifacts-research/ANALYSIS-FILE.md

@@ -29,7 +29,9 @@ What do the evidences indicate?
 - E1 shows...
 - E2 confirms...
 
-## Identified Cause
+## Outcome
+What the evidence establishes — a cause (debugging) or a finding (design / feasibility / comparison research):
 - Technical:
 - Data:
+- Finding:
 - Undetermined:

package/skills/w/commands/README.md

@@ -84,7 +84,7 @@ flowchart LR
 
 **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.
+> **`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 [`../exports/`](../exports/).
 
 ## Schema of each command file
 
@@ -94,8 +94,8 @@ Each `<command>.md` in this bundle uses this frontmatter + body structure:
 |---|---|
 | `description:` | One line: what + when (drives discovery in `/`-picker) |
 | `argument-hint:` | Argument signature for the user |
-| `allowed-tools:` | YAML list; always includes `Skill` when a loop/export skill is invoked |
-| Body | 1-3 orienting lines, then the invocation (Skill tool or `aw` CLI), `## Plan mode`, `## Resources` |
+| `allowed-tools:` | YAML list (typically `Bash`/`Read`/`Write`/`Edit`). Loops/exports are **read-and-followed**, not invoked with `Skill:` — so `Skill` is **not** in `allowed-tools`. |
+| Body | 1-3 orienting lines, then the invocation: **read-and-follow** the sibling loop/export `SKILL.md`, or call the `aw` CLI; then `## Plan mode`, `## Resources` |
 
 ## 6 Hard invariants (never violate)
 

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

@@ -30,4 +30,4 @@ Corré `aw merge-state` (read-only), reportá **origen ↔ destino** y los confl
 
 - 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`
+- Design reference: `docs/referencias/workflow-skills/fix-git.md`

package/skills/w/commands/status.md

@@ -47,4 +47,4 @@ Igual que en ejecución: corré `aw status` (read-only) y mostrá el resumen. No
 
 ## Resources
 - CLI: `aw status` (servicio `status-service`; fechas vía `humanize-es`)
-- Design reference: `docs/referencias/workflow-commands/status.md`
+- Design reference: `docs/referencias/workflow-skills/status.md`

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

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

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

@@ -120,6 +120,6 @@ Idempotente funcional: cada invocación toma el siguiente `NNN`; no sobrescribe
 ## Resources
 
 - Design: `docs/referencias/workflow-exports/export-diagrams.md` · familia: [`../README.md`](../README.md).
-- Capacidad compuesta: `diagrams` (built-in default; ver `docs/referencias/workflow-skills/`).
+- Capacidad compuesta: `diagrams` (built-in default; ver `docs/referencias/workflow-roles/`).
 - Insumo: plan-doc `AS-IS`/`TO-BE`/`Impacted` (ver `docs/plans`).
 - Siblings: [`../export-scripts/SKILL.md`](../export-scripts/SKILL.md) · [`../export-manuals/SKILL.md`](../export-manuals/SKILL.md) · [`../export-reports/SKILL.md`](../export-reports/SKILL.md).

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

@@ -1,6 +1,6 @@
 ---
 name: export-manuals
-description: "Sintetiza manuales técnicos del workspace en `docs/manuals/` consolidando N sesiones (`exec`/`quick`) + `docs/`. Lee de cada sesión el `DECISION` y el plan-doc (`Solution`, `Final behavior`, `Validations`) + el código tocado en las fuentes (cómo opera/funciona lo construido). Dos modos: `complement` (default, sobrescribe `INDEX.md` apuntando a los manuales detectados) y `regenerate` (produce dossier `NNN-export-manuals-YYYY-MM-DD/` con 1 manual por tema). Audiencia: operadores / soporte / onboarding. Read-only/reporte: no commitea ni muta sesiones. La prosa sigue las convenciones de redacción ambientes (el host auto-aplica una skill de writing instalada si está presente). Úsalo para 'manual operativo', 'cómo funciona lo entregado', 'paquete de onboarding técnico', 'índice de manuales'. Invocado por el usuario vía `/w:export-manuals`."
+description: "Manuales operativos / de onboarding (audiencia operador/soporte). Sintetiza manuales técnicos del workspace en `docs/manuals/` consolidando N sesiones (`exec`/`quick`) + `docs/`. Lee de cada sesión el `DECISION` y el plan-doc (`Solution`, `Final behavior`, `Validations`) + el código tocado en las fuentes (cómo opera/funciona lo construido). Dos modos: `complement` (default, sobrescribe `INDEX.md` apuntando a los manuales detectados) y `regenerate` (produce dossier `NNN-export-manuals-YYYY-MM-DD/` con 1 manual por tema). Audiencia: operadores / soporte / onboarding. Read-only/reporte: no commitea ni muta sesiones. La prosa sigue las convenciones de redacción ambientes (el host auto-aplica una skill de writing instalada si está presente). Úsalo para 'manual operativo', 'cómo funciona lo entregado', 'paquete de onboarding técnico', 'índice de manuales'. Invocado por el usuario vía `/w:export-manuals`."
 ---
 
 # export-manuals — Manuales técnicos desde sesiones + `docs/`
@@ -28,7 +28,7 @@ La redacción del manual sigue las convenciones de redacción **ambientes**: el
 
 1. Lee el corpus de sesiones (`exec`/`quick`): por sesión, `DECISION` + el plan-doc (`Solution`, `Final behavior`, `Validations`).
 2. Inspecciona el código tocado en las fuentes (cómo opera/funciona lo construido) — solo lectura.
-3. Detecta temas (declarados en el OBJECTIVE/`SESSION`, o inferidos por keywords operativos).
+3. Detecta temas (declarados en `SESSION` — su `## Objective` —, o inferidos por keywords operativos).
 4. Resuelve el modo (`complement` o `regenerate`).
 5. Sintetiza el contenido aplicando las convenciones de redacción ambientes (host).
 6. Escribe: `complement` → sobrescribe `docs/manuals/INDEX.md`; `regenerate` → dossier `docs/manuals/NNN-export-manuals-YYYY-MM-DD/` con 1 manual por tema.
@@ -51,7 +51,7 @@ En plan mode **describe**, no escribe: el modo resuelto, los temas detectados (c
 **CLI `agent-workflow` (alias `aw`)** — no leer paths hardcodeados:
 
 - `aw sessions` / `aw release-data [--since sessionNNN] [--source <alias>]` — enumera el corpus.
-- `aw session-artifacts --code <NNN>` — lee `DECISION`, el plan-doc y el OBJECTIVE/`SESSION` (lazy) por sesión.
+- `aw session-artifacts --code <NNN>` — lee `DECISION`, el plan-doc y `SESSION` (su `## Objective`, lazy) por sesión.
 - `aw next-number docs/manuals` — numeración determinística (solo modo `regenerate`).
 
 **Filesystem**:
@@ -97,7 +97,7 @@ Listar `docs/manuals/*.md` (excluyendo `INDEX.md` y subdirectorios `NNN-export-m
 
 ### Paso 3 — Detectar temas
 
-Por cada sesión del corpus filtrado (`aw session-artifacts --code <NNN>`): leer `DECISION` + plan-doc (`Solution`/`Final behavior`/`Validations`) + el código tocado. Tema **primario**: sección de temas en el OBJECTIVE/`SESSION`. **Secundario**: inferencia por keywords operativos ("configurar", "instalar", "paso a paso", "cómo …"). Filtrar por `--topics` si está presente. Listar (slug, confidence, sesiones de origen).
+Por cada sesión del corpus filtrado (`aw session-artifacts --code <NNN>`): leer `DECISION` + plan-doc (`Solution`/`Final behavior`/`Validations`) + el código tocado. Tema **primario**: la sección de temas en `SESSION` (su `## Objective`). **Secundario**: inferencia por keywords operativos ("configurar", "instalar", "paso a paso", "cómo …"). Filtrar por `--topics` si está presente. Listar (slug, confidence, sesiones de origen).
 
 ### Paso 4 — Sintetizar (prosa: convenciones ambientes)
 

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

@@ -1,6 +1,6 @@
 ---
 name: export-reports
-description: "Consolida N sesiones del workspace en un informe ejecutivo/funcional bajo `docs/reports/NNN-<slug>-YYYY-MM-DD.md`. Lee el corpus: el spec (`docs/specs`), `CONCLUSIONS` (research), `DECISION`, el estado del plan-doc + el resto de `docs/` para contexto. Sintetiza: qué se hizo, decisiones clave, resultados/conclusiones, pendientes/roadmap — con dedup de recomendaciones cross-session. Audiencia ajustable vía `--audience` (gerencia ≈ corto; tecnica ≈ detallado). Funde el espíritu de los viejos export-report (ejecutivo) y export-conclusions (dedup de R-items) en una sola salida a `docs/reports`. Read-only/reporte: no commitea ni muta sesiones. La prosa sigue las convenciones de redacción ambientes (el host auto-aplica una skill de writing instalada si está presente). Úsalo para 'informe ejecutivo', 'qué se hizo este trimestre para gerencia', 'brief con recomendaciones consolidadas'. Invocado por el usuario vía `/w:export-reports`."
+description: "Informe ejecutivo/funcional (audiencia gerencia/comité) que consolida N sesiones del workspace bajo `docs/reports/NNN-<slug>-YYYY-MM-DD.md`. Lee el corpus: el spec (`docs/specs`), `CONCLUSIONS` (research), `DECISION`, el estado del plan-doc + el resto de `docs/` para contexto. Sintetiza: qué se hizo, decisiones clave, resultados/conclusiones, pendientes/roadmap — con dedup de recomendaciones cross-session. Audiencia ajustable vía `--audience` (gerencia ≈ corto; tecnica ≈ detallado). Funde el espíritu de los viejos export-report (ejecutivo) y export-conclusions (dedup de R-items) en una sola salida a `docs/reports`. Read-only/reporte: no commitea ni muta sesiones. La prosa sigue las convenciones de redacción ambientes (el host auto-aplica una skill de writing instalada si está presente). Úsalo para 'informe ejecutivo', 'qué se hizo este trimestre para gerencia', 'brief con recomendaciones consolidadas'. Invocado por el usuario vía `/w:export-reports`."
 ---
 
 # export-reports — Informe ejecutivo/funcional desde el corpus de sesiones + `docs/`

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

@@ -130,6 +130,6 @@ Idempotente funcional: cada invocación toma el siguiente `NNN` y **no sobrescri
 ## Resources
 
 - Design: `docs/referencias/workflow-exports/export-scripts.md` · familia: [`../README.md`](../README.md).
-- Capacidad compuesta: `sql` (built-in default; ver `docs/referencias/workflow-skills/`).
+- Capacidad compuesta: `sql` (built-in default; ver `docs/referencias/workflow-roles/`).
 - Artefacto fuente: `SCRIPTS.sql` (ver `docs/referencias/workflow-artifacts/artifacts-core/`).
 - Siblings: [`../export-manuals/SKILL.md`](../export-manuals/SKILL.md) · [`../export-diagrams/SKILL.md`](../export-diagrams/SKILL.md) · [`../export-reports/SKILL.md`](../export-reports/SKILL.md).

package/skills/w/hooks/README.md

@@ -2,14 +2,18 @@
 
 `hooks.template.json` wires the host (Claude Code) to the `agent-workflow` runtime hooks. Merge it into your host's user-level hook config (e.g. `~/.claude/settings.json`); the installer does this automatically for Claude.
 
+> **Agnostic binding.** Hooks are **inherently host-specific**: they are the *Claude Code binding* of intents the doctrine states agnostically (DB scripts-only, safe branch, CHECKPOINT on compact/close). Another harness would satisfy the same intents with its own mechanisms; the doctrine does **not** depend on these hooks.
+
 | Event | Hook | Purpose |
 |---|---|---|
 | `SessionStart` | namespace pin | Pins the workspace namespace to `workflow` (so `.workflow/` resolves). |
 | `PreToolUse` (Edit/Write) | `hook branch-check` | Verifies the expected work branch before any file edit (git-safe invariant). |
 | `PreToolUse` (`execute_sql`) | `hook sql-mutation-guard` | Blocks DML/DDL over MCP — reads only (DB scripts-only invariant). |
-| `PreToolUse` (Bash) | `hook git-commit-advisor` | Advises on commit policy (propose-then-execute, no `push`/`--amend`/`--no-verify`). |
-| `SessionEnd` | `auto-compact-on-close` | Persists pending state on close. |
+| `PreToolUse` (Bash) | `hook git-commit-advisor` | **Advisory (does not block)**: warns if a `git commit` message lacks the active session's `sessionNNN` tag (traceability). Does **not** inspect `push`/`--amend`/`--no-verify`. |
+| `SessionEnd` | `auto-compact-on-close` | Writes `CHECKPOINT.md` on close — the resume key (*CHECKPOINT always*, invariant #6). |
 | `PreCompact` | `checkpoint-write` | Writes `CHECKPOINT.md` before the host compacts. |
 | `PostCompact` | `resume-summary` | Recovers the active loop state after a compact. |
 
-> These hooks enforce invariants 4 (DB scripts-only) and 5 (git-safe) at the host level, independent of the loop logic. The hook commands are runtime CLI subcommands (`agent-workflow hook …`), unchanged across the bundle namespace.
+> **What they enforce (host-level, blocking):** invariant **#4** (DB scripts-only) via `sql-mutation-guard` (blocks DML/DDL over MCP), and the *expected-branch* clause of **#5** via `branch-check` (blocks edits on the wrong branch). The rest of git-safe (`push`/`--amend`/`--no-verify`/`--force`) is **doctrinal** — `git-commit-advisor` only **warns**, it does not block; a host may add its own deny hook if it wants hard enforcement.
+>
+> **Commands:** the three `PreToolUse` hooks are `agent-workflow hook <branch-check|sql-mutation-guard|git-commit-advisor>` subcommands; the lifecycle hooks (`auto-compact-on-close`, `checkpoint-write`, `resume-summary`) are **top-level** runtime commands (`agent-workflow <cmd>`).

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

@@ -61,7 +61,7 @@ Del chasis [`spec-refine-loop`](../spec-refine-loop/SKILL.md), sin cambios:
 
 ## Internal sessions (managed)
 
-- **plan-exec session** descriptor `plan-exec` → `NNN-plan-exec`: **una sola session por run** (Type = `exec`). Dueña del run; posee `SESSION` + `CHECKPOINT` + `DECISION` + `SCRIPTS.sql` (+ `BACKLOG` solo si difiere). La investigación es **inline** dentro de esta session: produce `ANALYSIS-FILE`/`CONCLUSIONS` (+ `SCRIPTS.sql` read-only si consulta BD) en su propia carpeta.
+- **plan-exec session** descriptor `<slug>-plan-exec` → `NNN-<slug>-plan-exec` (el `<slug>` sale del plan-doc de entrada `docs/plans/PPP-plan-<slug>.md`): **una sola session por run** (Type = `exec`). Dueña del run; posee `SESSION` + `CHECKPOINT` + `DECISION` + `SCRIPTS.sql` (+ `BACKLOG` solo si difiere). La investigación es **inline** dentro de esta session: produce `ANALYSIS-FILE`/`CONCLUSIONS` (+ `SCRIPTS.sql` read-only si consulta BD) en su propia carpeta.
 
 > **Numeración**: el caller pasa solo el descriptor; el CLI antepone el `NNN` global y secuencial sobre `.workflow/sessions/` (ver chasis). No reinicia por tipo.
 
@@ -109,7 +109,7 @@ Distinción por **ejecución**, no por archivo (ver el esquema `SCRIPTS.sql`):
 
 ```
 plan-exec-loop(PPP-plan-<slug>.md):
-  session = create_or_resume("plan-exec")                  # UNA sola session por run; CLI antepone NNN global; CHECKPOINT, resume
+  session = create_or_resume("<slug>-plan-exec")           # <slug> del plan-doc; UNA sola session por run; CLI antepone NNN global; CHECKPOINT, resume
   plan = read(PPP-plan-<slug>.md)
   para cada Phase en plan (en orden, respeta deps):
     si Phase done (todas sus Tasks - [x] en el plan): skip # resume vía checkbox del plan-doc

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

@@ -43,11 +43,11 @@ PLAN
 Del chasis [`spec-refine-loop`](../spec-refine-loop/SKILL.md), sin cambios:
 
 - **Objetivo persistente + verification-first** del chasis: persigue su `SESSION.Objective` hasta que sus `SESSION.Success criteria` están **en verde** (sembrados al inicio; acá la rúbrica = **coherencia del plan**: cada Task traza a un acceptance criterion del spec). El motor es **gap-driven convergente** + **ciclo artifact-first** (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.
+- **Una sola session por run**: descriptor `<slug>-plan-new` → `NNN-<slug>-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.
 - **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.
+- **Naming + numeración global** del chasis: `<run>` = descriptor `<slug>-plan-new`, donde `<slug>` sale del spec de entrada (`docs/specs/NNN-spec-<slug>.md`) → folder autodescriptivo `NNN-<slug>-plan-new`. El CLI antepone el `NNN` global y secuencial (sin reiniciar por tipo); el caller pasa solo el descriptor.
 
 ## Delta 1 — Deliverable: PLAN RICO (`PPP-plan-<slug>.md`)
 

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

@@ -88,7 +88,7 @@ El loop crea y maneja su session en `.workflow/sessions/`. El usuario nunca la c
 
 | Session | When | Artifacts | Role |
 |---|---|---|---|
-| **refine session** `NNN-spec-refine/` | al arrancar el loop (o se reanuda) | `SESSION.md` · `CHECKPOINT.md` (· `BACKLOG.md` solo si difiere) | Dueña del run. Mantiene el avance vivo (CHECKPOINT) y habilita el resume. Type = `refine`. |
+| **refine session** `NNN-<slug>-spec-refine/` | al arrancar el loop (o se reanuda) | `SESSION.md` · `CHECKPOINT.md` (· `BACKLOG.md` solo si difiere) | Dueña del run. Mantiene el avance vivo (CHECKPOINT) y habilita el resume. Type = `refine`. |
 
 > **Research INLINE** — la investigación ya **no** es una session aparte: es una actividad **dentro de la session actual** que escribe sus artefactos (`ANALYSIS-FILE`/`CONCLUSIONS`, + `SCRIPTS.sql` read-only si consulta BD) **en la carpeta de la propia session del run**. Ver *Research: autonomy, scope & failure*.
 
@@ -98,14 +98,14 @@ El loop crea y maneja su session en `.workflow/sessions/`. El usuario nunca la c
 
 ### Numeración de sessions (regla dura, heredada por todos los loops)
 
-El **CLI es dueño del número**: `aw session-create` antepone un `NNN` **global y secuencial** escaneando **todas** las sessions de `.workflow/sessions/` (cualquier tipo). El caller pasa **solo el descriptor** vía `--name` — **nunca** un número. Así la numeración no se reinicia por tipo ni colisiona (ej.: `001-spec-refine`, `002-plan-new`, `003-plan-exec`, …).
+El **CLI es dueño del número**: `aw session-create` antepone un `NNN` **global y secuencial** escaneando **todas** las sessions de `.workflow/sessions/` (cualquier tipo). El caller pasa **solo el descriptor** vía `--name` — **nunca** un número. Así la numeración no se reinicia por tipo ni colisiona, y cada folder queda **autodescriptivo** con la forma `NNN-<slug>-<flow>` (ej.: `002-correo-otp-spec-refine`, `003-correo-otp-plan-new`, `004-correo-otp-plan-exec`, `005-validacion-correo-quick`).
 
-> `<run>` = el **descriptor** (sin número) de la session del run: `spec-refine`, `plan-new`, `plan-exec`; QUICK usa `<slug>-quick` (slug del prompt). Como la investigación es **inline** en esta misma session, ya no hay sessions hijas `*-research-*` que numerar (compat: las viejas son históricas).
+> `<run>` = el **descriptor** (sin número) de la session del run, siempre con forma **`<slug>-<flow>`**: `<slug>-spec-refine`, `<slug>-plan-new`, `<slug>-plan-exec`, `<slug>-quick`. El `<slug>` es **descriptivo** y sale del doc de entrada del flujo — `docs/specs/NNN-spec-<slug>.md` para spec-refine/plan-new; `docs/plans/PPP-plan-<slug>.md` para plan-exec; el prompt para quick — para que el folder diga de un vistazo de qué trata, no solo qué flujo lo creó. Como la investigación es **inline** en esta misma session, ya no hay sessions hijas `*-research-*` que numerar (compat: las viejas son históricas).
 >
 > **Resume**: localiza la session existente **escaneando** `.workflow/sessions/` por descriptor + `## Origin` (qué spec/plan), **no** reconstruyendo el número (que es global, no derivable del artefacto). `aw session-resume --code <NNN | folder>` resuelve ambas formas.
 
 **CLI**:
-- `aw session-create --type refine --name spec-refine` → crea `NNN-spec-refine` / `aw session-resume --code <…>` (detecta `CHECKPOINT`).
+- `aw session-create --type refine --name <slug>-spec-refine` → crea `NNN-<slug>-spec-refine` / `aw session-resume --code <…>` (detecta `CHECKPOINT`).
 - `aw checkpoint-write` / `aw checkpoint-read` para el resume.
 - `aw session-close` al cerrar (con razón); `aw session-artifacts` para inspeccionar.
 - **Reabrir para continuar** (contexto operativo, fila 2): `aw session-resume --code <NNN> --reopen` reactiva una sesión **cerrada** (quita `.closed` → activa) para seguir trabajando en ella; sin `--reopen`, el resume es read-only. Para detectar cuál es la más reciente cerrada: `aw resume-summary --include-recent-closed` (o `aw sessions --state all`).
@@ -205,7 +205,7 @@ La investigación es **inline**: una actividad **dentro de la session actual del
 ```
 spec-refine-loop(spec):
   input = glob(NNN-spec*.md) | argumento (ruta)         # siempre el spec mismo (in place)
-  refine_session = create_or_resume("spec-refine")      # CLI antepone NNN global; resume localiza por descriptor/origin
+  refine_session = create_or_resume("<slug>-spec-refine") # <slug> del spec de entrada; CLI antepone NNN global; resume localiza por descriptor/origin
   seed SESSION.Success criteria = acceptance criteria + checklist del analyze gate   # verification-first: ANTES de iterar
   work = read(input)  (+ aplicar avance del checkpoint si reanuda)
   attempts = {}                                         # anti-relanzamiento por gap

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

@@ -1,11 +1,11 @@
 ---
 name: diagrams
 description: >
-  Autoría de diagramas de arquitectura y sistema: C4 (Context, Container, Component),
-  PlantUML y Structurizr DSL. Compuesta por export-diagrams para producir el contenido
-  de docs/diagrams/. Selecciona el motor de render según el flag --diagrams del export
-  (Structurizr default, Mermaid y PlantUML opt-in). Incluye link mermaid.ink por cada
-  bloque Mermaid para preview sin renderer local.
+  Autoría de diagramas de arquitectura y sistema con notación C4 (Context, Container,
+  Component): Mermaid C4 nativo (default) o Structurizr DSL. Compuesta por export-diagrams
+  para producir el contenido de docs/diagrams/. Selecciona el motor según el flag `--engine`
+  del export (Mermaid default; `c4`/Structurizr DSL opt-in). Incluye link mermaid.ink por
+  cada bloque Mermaid para preview sin renderer local.
 ---
 
 # diagrams — Diagram authoring capability
@@ -16,7 +16,7 @@ description: >
 
 ## Purpose
 
-Autorar diagramas de arquitectura con notación C4 (Levels 1-3) usando el motor que el export configure. Produce source renderizable (DSL, PUML, Mermaid) — **no renderiza visualmente**; el render lo hace el lector con sus herramientas. Cubre el estándar C4 formal (Structurizr DSL), el opt-in embebido (Mermaid nativo) y el opt-in exportable (PlantUML).
+Autorar diagramas de arquitectura con notación C4 (Levels 1-3) usando el motor que el export configure vía `--engine`. Produce source renderizable (Mermaid / DSL) — **no renderiza visualmente**; el render lo hace el lector con sus herramientas. Cubre el motor por defecto (Mermaid C4 nativo, embebido) y el opt-in `c4` (Structurizr DSL, C4 formal).
 
 ## Composed by
 
@@ -30,13 +30,14 @@ Cualquier loop puede componerla también si necesita producir un diagrama inline
 
 ### Engine matrix
 
-| `--diagrams` flag | Motor | Archivos producidos | Cuándo elegirlo |
+El export elige el motor con `--engine mermaid|c4` (default `mermaid`):
+
+| `--engine` | Motor | Archivos producidos | Cuándo elegirlo |
 |---|---|---|---|
-| `structurizr` (default) | Structurizr DSL | `workspace.dsl` + Mermaid auxiliar embebido en `.md` | Dossier técnico formal; soporte de tooling externo (structurizr.com, structurizr-lite) |
-| `mermaid` | Mermaid C4 nativo | solo `.md` con bloques Mermaid | Preferir render embebido sin DSL separado; GitHub/GitLab lo renderizan inline |
-| `plantuml` | PlantUML C4-stdlib | `arquitectura.puml` + nota en `.md` | Equipos con pipeline PlantUML instalado |
+| `mermaid` (default) | Mermaid C4 nativo | solo `.md` con bloques Mermaid | Render embebido sin DSL separado; GitHub/GitLab lo renderizan inline |
+| `c4` | Structurizr DSL | `workspace.dsl` + Mermaid auxiliar embebido en `.md` | Dossier técnico formal; tooling externo (structurizr.com, structurizr-lite) |
 
-**Regla canónica**: `export-diagrams` usa Structurizr DSL por defecto (C4 formal, separa modelo de vistas). Mermaid es opt-in cuando se prefiere render embebido.
+**Regla canónica**: `export-diagrams` usa **Mermaid** por defecto (`--engine mermaid`) — render embebido sin tooling externo. `--engine c4` produce Structurizr DSL (C4 formal, separa modelo de vistas) para el dossier técnico.
 
 ### C4 model — levels
 
@@ -138,7 +139,9 @@ workspace "<PRODUCTO>" "<descripcion>" {
 
 Render online gratuito: [structurizr.com/dsl](https://structurizr.com/dsl) o structurizr-lite (Docker).
 
-### PlantUML C4-stdlib template
+### PlantUML C4-stdlib template (motor extra, fuera del contrato actual)
+
+> El contrato vigente de `export-diagrams` expone solo `--engine mermaid|c4` (no produce `.puml`). Esta plantilla queda como **referencia** para un export rebindeado/custom que quiera emitir PlantUML.
 
 ```plantuml
 @startuml arquitectura
@@ -162,9 +165,9 @@ SHOW_LEGEND()
 
 Render: [plantuml.com](https://plantuml.com) o `plantuml.jar` local.
 
-### Mermaid auxiliar (bajo Structurizr default)
+### Mermaid auxiliar (bajo `--engine c4`)
 
-Cuando `--diagrams structurizr`, el archivo `.md` incluye también un bloque Mermaid derivado del DSL como **fallback offline** (lectores sin acceso a structurizr.com/dsl pueden leerlo directamente):
+Cuando `--engine c4`, el archivo `.md` incluye también un bloque Mermaid derivado del DSL como **fallback offline** (lectores sin acceso a structurizr.com/dsl pueden leerlo directamente):
 
 ```
 ```mermaid
@@ -196,7 +199,7 @@ Solo si aporta claridad real — no agregar sequence diagrams por defecto.
 
 ### Entity-Relationship (modelo de datos)
 
-Cuando `export-diagrams` incluye `--scope datos` y hay MCP configurado:
+Cuando `export-diagrams` incluye `--scope data` y hay MCP configurado:
 
 ```mermaid
 erDiagram
@@ -218,10 +221,9 @@ MCP read-only: `\d <tabla>` + `SELECT count(*)` para magnitud (aplicar cost guar
 
 ```
 docs/diagrams/NNN-export-diagrams-YYYY-MM-DD/
-├── README.md            # indice + how-to-read + motores usados
-├── arquitectura.md      # documento principal con C4 + Mermaid auxiliar
-├── workspace.dsl        # solo con --diagrams structurizr (default)
-└── arquitectura.puml    # solo con --diagrams plantuml
+├── README.md            # índice + how-to-read + motores usados
+├── diagrams.md          # documento principal con C4 + Mermaid (+ links mermaid.ink)
+└── workspace.dsl        # solo con --engine c4 (Structurizr)
 ```
 
 ### Render rules
@@ -237,12 +239,11 @@ docs/diagrams/NNN-export-diagrams-YYYY-MM-DD/
 
 Produce en `docs/diagrams/NNN-export-diagrams-YYYY-MM-DD/`:
 - `README.md`
-- `arquitectura.md` (siempre)
-- `workspace.dsl` (si `--diagrams structurizr`)
-- `arquitectura.puml` (si `--diagrams plantuml`)
+- `diagrams.md` (siempre)
+- `workspace.dsl` (si `--engine c4`)
 
 Escribe solo `docs/diagrams/` (invariant #1 y #2: solo `export-*` gradua a `docs/`; esta skill la compone `export-diagrams`).
 
 ## Source
 
-Reciclado de `agent-workflow/exports/export-arq/` del bundle viejo (v1.3.0). Se conserva: el modelo C4 Levels 1-3, los tres motores (Structurizr default, Mermaid opt-in, PlantUML opt-in), las plantillas DSL y PUML, la regla de link `mermaid.ink` por bloque Mermaid, la estructura de output, el cost guard para MCP. Se descarta: la lógica de lectura de AW-PROJECT legacy, los comandos CLI `agent-workflow next-number`/`history-data`/etc. (son detalles de implementación del CLI, no de la skill), y el scope `--diagrams` como input flag (lo recibe el export que compone esta skill).
+Reciclado de `agent-workflow/exports/export-arq/` del bundle viejo (v1.3.0). Se conserva: el modelo C4 Levels 1-3, las plantillas DSL/PUML, la regla de link `mermaid.ink` por bloque Mermaid, la estructura de output, el cost guard para MCP. Se moderniza al contrato vigente de `export-diagrams`: **Mermaid por defecto** (antes Structurizr), motor elegido por `--engine mermaid|c4` (lo recibe el export que compone esta skill); PlantUML queda como apéndice de referencia, fuera del contrato actual. Se descarta: la lógica de lectura de AW-PROJECT legacy y los comandos CLI `agent-workflow next-number`/`history-data`/etc. (detalles de implementación del CLI, no de la skill).

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

@@ -75,7 +75,7 @@ CREATE TABLE IF NOT EXISTS esq_credito.tb_usuarios (
 
 **Orden de ejecución obligatorio**: 01 → 02 → 03 → 04. El `SCRIPTS.sql` puede mezclar categorías cronológicamente; `export-scripts` ordena el bundle final.
 
-### Estilo SQL (cumple `database-conventions`)
+### Estilo SQL
 
 - **Header canónico de 4 líneas**, entre dos líneas de iguales:
   ```sql
@@ -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`. Se moderniza al modelo nuevo: el bundle lo arma `export-scripts`, no la skill; el "release/graduate" viejo se reemplaza por `export-scripts`.
+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`.

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

@@ -145,4 +145,4 @@ Writes `docs/tools/` (invariant #2: PLAN es el dueño de esta carpeta). No gradu
 
 ## Source
 
-Autoria original (no hay skill equivalente en el bundle viejo). Basado en la descripción del rol en `workflow-skills/README.md` y en el invariant #2 del diseño (`docs/tools/` es del flujo PLAN). Las convenciones de estructura de doc (`## Purpose`, `## Usage`, `## Parameters`, `## Output`, `## Examples`) siguen el patrón de calidad del bundle.
+Autoria original (no hay skill equivalente en el bundle viejo). Basado en la descripción del rol en `workflow-roles/README.md` y en el invariant #2 del diseño (`docs/tools/` es del flujo PLAN). Las convenciones de estructura de doc (`## Purpose`, `## Usage`, `## Parameters`, `## Output`, `## Examples`) siguen el patrón de calidad del bundle.