@tacuchi/agent-workflow-cli 6.2.0 → 7.0.1

package/skills/agent-workflow/doctrine/session/references/branch-verification.md

@@ -0,0 +1,198 @@
+# Verificación de rama de trabajo — Referencia canónica (agent-workflow)
+
+> Documento canónico de la familia qtc-* para validación y orquestación de ramas. Referenciado por `skills/session/SKILL.md` y el hook PreToolUse (`agent-workflow hook branch-check`). Los flow plugins (qtc-dev, qtc-design, qtc-analyze) **no duplican** este flujo — apuntan acá.
+
+## Contexto
+
+Las **fuentes del workspace** (alias, path, rama principal) se declaran una sola vez en el bloque `AW-PROJECT` de `CLAUDE.md` y `AGENTS.md` (sección `Fuentes`). Cada sesión activa declara su **rama de trabajo por fuente** en `Status → Sesiones activas`. El sub-comando `agent-workflow sources` resuelve ambas, las contrasta con el git status real y devuelve un payload uniforme.
+
+Campos relevantes por fuente:
+- `alias` — nombre corto (ej: `core`, `dev`, `api`, `web`).
+- `path` — ruta local al repo de esa fuente.
+- `main_branch` — base de la cual sale y hacia la cual vuelve la rama de trabajo (default `certificacion`).
+- `expected_work_branch` — rama esperada según resolución (sesión > working_branches > main_branch para analyze).
+- `current_branch` — rama actual del repo (live).
+- `match` — `current_branch == expected_work_branch`.
+- `dirty` — hay archivos modificados sin commit (`git status --porcelain`).
+
+**Regla fundamental**: la rama esperada **nunca se asume desde la rama actual**. El usuario puede haber cambiado de rama manualmente para revisar otras cosas; el agente verifica antes de cualquier acción.
+
+## Cuándo se ejecuta el check
+
+| Momento | Comando | Quién dispara |
+|---|---|---|
+| 1. Crear sesión | `agent-workflow sources [--session NNN] [--flow F]` | `agent-workflow/skills/session/SKILL.md` paso 6 |
+| 2. Retomar sesión | igual | `skills/session/SKILL.md` paso retomar |
+| 3. Entrar a fase execution | igual | `skills/session/SKILL.md` fase 2 |
+| 4. PreToolUse Edit/Write/MultiEdit/NotebookEdit | `agent-workflow check-branch --file <path> --strict` | `agent-workflow hook branch-check` (hook) |
+
+## Estructura del output de `agent-workflow sources`
+
+```json
+{
+  "workspace_mode": "hub",
+  "is_hub": true,
+  "session_code": "003",
+  "scope": null,
+  "sources": [
+    {
+      "alias": "core",
+      "path": "/Users/x/Git/agent-workflow",
+      "main_branch": "certificacion",
+      "expected_work_branch": "certificacion",
+      "current_branch": "certificacion",
+      "match": true,
+      "dirty": false,
+      "changed_files": [],
+      "is_repo": true,
+      "error": null
+    }
+  ],
+  "session_branches": ["core:certificacion", "dev:certificacion"],
+  "working_branches_from_status": {"core": "certificacion", "dev": "certificacion"},
+  "cross_source_consistent": true,
+  "divergent_sources": []
+}
+```
+
+Interpretación por fuente:
+- `match: true` → todo OK.
+- `match: false` + `dirty: false` → rama distinta, repo limpio. Aplicar **Caso A**.
+- `match: false` + `dirty: true` → rama distinta y cambios sin commit. Aplicar **Caso B**.
+- Para `flow=analyze` con cambios decididos a mitad de sesión → **Caso C** (no se manifiesta en el output; lo dispara el usuario al pedir editar).
+
+Interpretación cross-fuente (hub mode):
+- `cross_source_consistent: false` → hard gate (Cross-fuente abajo).
+
+## Caso A — repo limpio, rama distinta (`match=false, dirty=false`)
+
+El agente informa la divergencia y **pide confirmación** vía `AskUserQuestion`. Spec literal (header `branch:<alias>`, 3 opciones) → `prompts-catalog.md#M2`. Resumen:
+
+```
+La fuente `core` (~/Git/agent-workflow) está en `main` pero la rama
+de trabajo es `certificacion`. ¿Hago `git checkout certificacion`?
+```
+
+Opciones:
+- **Sí, hacer checkout** → ejecutar `git -C <path> checkout <expected>` y reintentar la acción original.
+- **Mantener current y actualizar la sesión** → invocar `agent-workflow project-md-upsert --update-phase <folder> --branches <alias>:<current>` para registrar la nueva expectativa, luego avanzar.
+- **Cancelar** → abortar la acción que disparó el check.
+
+## Caso B — repo dirty, rama distinta (`match=false, dirty=true`)
+
+El agente **pausa y espera resolución manual** del usuario. NO propone checkout porque podría perder trabajo:
+
+```
+La fuente `core` está en `main` (esperada `certificacion`) con cambios sin
+commit en:
+  - skills/session/SKILL.md
+  - hooks/hooks.json
+No voy a cambiar de rama porque podrías perder trabajo.
+Resolvé manualmente (commit / stash / discard) y avisame cuando continúo.
+```
+
+Cuando el usuario indica "listo" / "continúa" / equivalente:
+1. Re-ejecutar `agent-workflow check-branch --source <alias>`.
+2. Si ahora `dirty=false` → aplicar Caso A.
+3. Si sigue `dirty=true` → informar y esperar de nuevo.
+
+**Prohibido sin confirmación explícita del usuario** (bajo ningún atajo):
+- `git stash`
+- `git reset --hard`
+- `git checkout -- .`
+- `git restore .`
+- `git clean -fd`
+
+Estas operaciones son destructivas y no autorizadas por el lifecycle.
+
+## Caso C — flow=analyze + edición decidida
+
+Las sesiones `flow=analyze` resuelven `expected_work_branch = main_branch` (default `certificacion`) cuando no se declaran `--branches` explícitamente al crear la sesión. La intención: **leer producción**, no editarla.
+
+Si durante la investigación el usuario decide hacer cambios en código, ejecutar **2 prompts encadenados**. Spec literal (headers `work-branch` → `checkout` o `branch-new`) → `prompts-catalog.md#M3`. Resumen:
+
+1. El agente avisa: "vamos a salir de modo lectura → necesitamos la rama de trabajo".
+2. **Prompt 1** — pedir nombre de rama de trabajo (sugerencia por defecto: `feature/sessionNNN-<slug>`); el `Other` auto cubre nombres alternativos.
+3. **Prompt 2** — verifica con `git -C <path> rev-parse --verify <work_branch>`:
+   - **Si la rama existe** → `AskUserQuestion`: "¿Hago `git checkout <work_branch>`?" (header `checkout`).
+   - **Si no existe** → `AskUserQuestion`: "Crear `<work_branch>` desde `<main_branch>`? (`git checkout -b <work_branch> <main_branch>`)" (header `branch-new`).
+4. Sólo con confirmación explícita, ejecutar el comando.
+5. Registrar la nueva rama en AW-PROJECT.Status → la sesión vía `project-md-upsert --update-phase <folder> --branches <alias>:<work_branch>`.
+6. Continuar con la edición.
+
+El usuario también puede declarar `--branches alias:rama` al crear la sesión analyze; ese override gana sobre el default `main_branch`. Caso C sólo aplica cuando la sesión arrancó en modo lectura (sin branches declaradas).
+
+## Cross-fuente (hub mode) — hard gate
+
+En workspaces `Mode: hub`, la convención es que **todas las fuentes tocadas por una sesión comparten la misma rama de trabajo** (la "rama de la sesión"). Divergencias deben ser declaradas explícitamente al crear la sesión.
+
+`cmd_sources` consolida y devuelve:
+- `cross_source_consistent: bool` — true si todas las fuentes con `expected_work_branch` declarada apuntan a la misma rama.
+- `divergent_sources: [{alias, current, expected}]` — fuentes que difieren del consenso.
+
+**Si `cross_source_consistent=false`**, el agente bloquea avance con `AskUserQuestion`. Spec literal (header `cross-branch`, 3 opciones, preview ASCII opcional con la matriz divergente) → `prompts-catalog.md#M4`. Resumen:
+
+```
+Las fuentes en este workspace apuntan a ramas distintas:
+  - core:        actual=certificacion   esperada=certificacion
+  - dev:         actual=feature/foo     esperada=certificacion
+  - analyze:     actual=feature/foo     esperada=certificacion
+
+Esperaba que todas compartan rama. ¿Cómo resolvemos?
+```
+
+Opciones:
+- **Alinear todas a una misma rama** → dispara prompt anidado para elegir cuál rama (current consensus / expected / otra vía Other) y aplica Caso A por fuente divergente.
+- **Declarar divergencia explícita** → re-crear la sesión con `--branches alias:rama` distintos; o actualizar la activa con `project-md-upsert --update-phase <folder> --branches "alias1:rama1,alias2:rama2"`.
+- **Cancelar acción** → abortar y dejar al usuario decidir manualmente.
+
+No avanzar a planning/execution hasta que `cross_source_consistent=true` o el usuario haya declarado explícitamente la divergencia.
+
+## Casos especiales
+
+| Situación | Estado | Acción |
+|---|---|---|
+| Fuente fuera de git | `is_repo: false` | Informar al usuario, no bloquear. No participa en cross-fuente. |
+| HEAD detached | `current_branch == "HEAD"` | Tratar como mismatch limpio (Caso A) — proponer checkout a expected. |
+| Path inexistente | `error` poblado | Alertar — fuente desactualizada en AW-PROJECT. Sugerir `agent-workflow:project-init` para corregir. |
+| Archivo fuera de cualquier fuente | hook devuelve `reason: file_not_in_managed_source` | El hook no bloquea; el SKILL no incluye la fuente en validación. |
+| Múltiples sesiones activas | `_resolve_session_branches` toma la primera | Pasar `--session CODE` explícito si se necesita otra. |
+| Sesión sin `--branches` declarada (no-analyze) | `expected_work_branch` cae a `working_branches_from_status` | Si tampoco hay working_branches, `expected_work_branch=null` y no se valida. |
+| Sesión analyze sin `--branches` | `expected_work_branch = main_branch` | Default Caso C-aware; el SKILL trata edición como Caso C. |
+
+## Integración con el hook PreToolUse
+
+`agent-workflow hook branch-check` (invocado desde `hooks/hooks.json` y `codex-hooks/hooks.json`):
+
+1. Lee `tool_input.file_path` del stdin JSON (`Edit | Write | MultiEdit | NotebookEdit`).
+2. Resuelve la fuente dueña validando el path contra `Fuentes` del bloque AW-PROJECT (hub-aware).
+3. Resuelve flow desde la sesión activa.
+4. Calcula `expected_work_branch` combinando session branches + working branches + main_branch.
+5. Si match → exit 0 (allow).
+6. Si mismatch → exit 2 (block) con stderr formateado por Caso A o B.
+
+El stderr siempre apunta acá (`skills/session/references/branch-verification.md`) para que el AI sepa cómo proceder.
+
+## Comandos útiles
+
+```bash
+# Visión global del workspace
+agent-workflow sources
+
+# Foco en una sesión y subset de fuentes
+agent-workflow sources --session 003 --scope core,dev,analyze
+
+# Override flow (ej: probar comportamiento analyze en una sesión dev)
+agent-workflow sources --flow analyze
+
+# Validación atómica de UNA fuente (uso del hook)
+agent-workflow check-branch --source core --strict
+agent-workflow check-branch --file /path/to/file.py --strict
+```
+
+## Referencias
+
+- `agent-workflow/src/lib/sources.ts` — implementación (`checkSourceBranch`, `expectedWorkBranch`, `resolveSessionFlow`, `cmdSources`, `cmdCheckBranch`).
+- `agent-workflow hook branch-check` — comando hook PreToolUse universal.
+- `skills/session/SKILL.md` — orquestación del check en el lifecycle.
+- `docs/shared-contract.md §27` — contrato de promoción del check al agent-workflow.

package/skills/agent-workflow/doctrine/session/references/commits-policy.md

@@ -0,0 +1,111 @@
+# commits-policy — política controlada de commits qtc-*
+
+Anchor canónico: `agent-workflow:commits-policy`. Referenciable cross-plugin desde cualquier skill via path relativo o nombre.
+
+## Regla 1 — el AI NUNCA commitea por iniciativa propia
+
+Lista cerrada de operaciones git **prohibidas** sin solicitud explícita del usuario:
+
+- `git commit` (incluye `--amend`)
+- `git push` (incluye `--force`)
+- `git merge` / `git rebase` / `git cherry-pick`
+- `git tag` (creación o edición)
+- `git reset --hard` / `git restore .` / `git checkout -- .` / `git clean`
+
+El AI **sí puede** ejecutar git read-only sin pedir permiso: `status`, `log`, `diff`, `branch --show-current`, `rev-parse`, `show`.
+
+Para `git checkout` (cambio de rama) ver `branch-verification.md` — requiere `AskUserQuestion` aunque no sea destructivo.
+
+## Regla 2 — formato canónico cuando el usuario pide commit
+
+Cuando el usuario solicita explícitamente un commit, el mensaje debe ser:
+
+- **Una sola línea**.
+- **Corto** (≤72 chars sugerido; cortar si excede).
+- **Descriptivo y práctico** — qué cambia, no cómo.
+- **Incluye el código de sesión** activa: `session<NNN>` como tag o dentro de un prefijo.
+- Prefijo Conventional Commits **opcional** (`feat:`, `fix:`, `docs:`, `chore:`, `refactor:`, `test:`).
+
+**Prohibido**:
+- Trailers `Co-Authored-By: …`.
+- Firmas de modelo (`🤖 Generated with …`, `Generated by Claude`, etc.).
+- Líneas adicionales (multi-line body, footer).
+- Emojis, salvo que el usuario los pida explícitamente.
+- Flag `--no-verify` (respetar siempre los hooks pre-commit).
+
+### Ejemplos válidos
+
+```
+session007: agrega politica de commits controlados
+feat(session012): nuevo skill release-scripts
+fix(session018): corrige drift en hooks.json del CLI
+docs: actualiza shared-contract con anchor commits-policy
+```
+
+### Ejemplos inválidos
+
+```
+# multilinea (body extra prohibido)
+feat: agrega politica
+Esta política aplica a toda la familia qtc-*.
+
+# co-author trailer (prohibido)
+session007: agrega politica
+Co-Authored-By: Claude <noreply@anthropic.com>
+
+# firma de modelo (prohibida)
+session007: agrega politica
+🤖 Generated with Claude Code
+```
+
+### Caso fuera de sesión activa
+
+Si el usuario pide un commit fuera del contexto de sesión qtc-* (ej. workspace sin AW-PROJECT, o trabajo ad-hoc), el formato se relaja a "1 línea + sin co-author"; el tag `session<NNN>` no aplica. El propose-then-execute de Regla 3 sigue activo — la única diferencia es que el mensaje sugerido omite el tag.
+
+## Regla 3 — propose-then-execute universal con AskUserQuestion
+
+Ante **cualquier** solicitud o mención de commit como acción a ejecutar (closure auto-disparado, solicitud explícita en planning/execution con sesión activa, solicitud explícita sin sesión, workspace hub o project), el AI invoca el prompt M1 (`prompts-catalog.md#M1`) **antes** de ejecutar `git commit`. No es un patrón privado del closure: closure es una de sus aplicaciones.
+
+Disparadores canónicos:
+
+1. **Closure de `/agent-workflow:session`** (auto): antes de `session-close`, el skill `session` ejecuta el flujo M1 sobre las fuentes con `dirty=true`. Documentado en `skills/session/SKILL.md` §"Cerrar sesión — 2. Proponer commits".
+2. **Solicitud explícita del usuario con sesión activa** ("commitea esto", "guardá los cambios", "subí los cambios" sin mensaje literal): el AI llama `agent-workflow sources --session <CODE>` y dispara M1 según el resultado.
+3. **Solicitud explícita del usuario sin sesión activa** (workspace qtc-* hub/project sin sesiones registradas en `AW-PROJECT.Status`): el AI llama `agent-workflow sources` (sin `--session`) y dispara M1. El tag `session<NNN>` del mensaje sugerido se omite (Regla 2).
+4. **Solicitud del usuario en workspace no qtc-*** (sin `AW-PROJECT`): no hay `sources` disponible. El AI cae al flujo simple — sugiere 1-line msg en chat y espera confirmación antes de ejecutar. No invoca `AskUserQuestion`.
+
+Pasos del flujo M1:
+
+1. Llamar a `agent-workflow sources [--session <CODE>?]`. Si la salida es inválida (workspace no qtc-*) → ver disparador 4 arriba.
+2. Si hay 1+ fuentes con `dirty=true`, invocar **una sola** `AskUserQuestion` con N questions tab-por-fuente (N = #fuentes-dirty, máx 4 simultáneas). Spec literal → `prompts-catalog.md#M1`. Resumen:
+   - Header de cada tab: `<alias>` puro.
+   - 2 opciones explícitas: "Aprobar sugerido (Recomendado)" con el mensaje canónico / "Saltar esta fuente".
+   - `Other` auto-inyectado = mensaje de commit custom.
+   - Si N > 4: ejecutar en tandas; registrar parcial en `CHECKPOINT.md` (si hay sesión activa) o en chat al usuario (si no la hay).
+3. Sólo ejecutar `git commit -m "<msg>"` en las fuentes donde el usuario aprobó o escribió Other, una a una (`git -C <path>`). Respetar hooks (sin `--no-verify`).
+4. Si la fuente tiene `match=false` (rama distinta a la esperada), **omitirla del prompt y abortar el commit** en esa fuente; avisar al usuario para que alinee la rama primero.
+5. Si todas las fuentes tienen `dirty=false`, **skip silencioso** — no invocar `AskUserQuestion`. Informar al usuario en chat que no hay nada que commitear.
+
+Excepciones a recordar:
+- Project mode con 1 fuente dirty → N=1 question. Sigue siendo el flujo M1.
+- Hub mode con N>1 fuentes dirty → N questions tab-por-fuente.
+- Workspace marketplace / hub donde el workspace mismo (no las fuentes declaradas) tiene cambios: el AI **no** los commitea por iniciativa; sólo opera sobre las fuentes declaradas en `AW-PROJECT.Fuentes`.
+
+## Regla 4 — interacción con release / release-scripts / graduation
+
+Los skills `release` y `release-scripts` (qtc-dev) son solo lectura/reporte: nunca commitean ni mergean. Lo mismo aplica a `graduate` (agent-workflow) — graduar artefactos crea/mueve archivos, pero el commit del cambio queda para el flujo M1 (Regla 3) o para la solicitud explícita del usuario.
+
+## Regla 5 — bypass por mensaje literal
+
+Si el usuario aporta el mensaje exacto del commit en la solicitud — por ejemplo `"commitea con mensaje 'session075: doc canon'"`, `"commit -m 'fix: X'"`, o `"--message <texto>"` — el AI ejecuta `git commit -m "<literal>"` directamente, sin invocar `AskUserQuestion`. La decisión ya está tomada; preguntar otra vez es redundante.
+
+Reglas operativas:
+
+- La señal que dispara el bypass es **el mensaje literal explícito** (comillas, `-m`/`--message`, o equivalente). Una solicitud genérica ("commitea esto") **no** califica — sigue el flujo M1 de Regla 3.
+- El bypass aplica por fuente. Si el usuario aporta mensaje literal para una fuente concreta ("commitea `core` con mensaje 'X'"), el AI ejecuta solo ahí; las demás fuentes dirty siguen el flujo M1 (Regla 3) o esperan instrucción.
+- El AI sigue validando rama (`match=true`), hooks pre-commit y formato canónico (Regla 2). El bypass no salta esas guardas — sólo evita el prompt interactivo.
+- Si el mensaje literal aportado viola Regla 2 (multi-línea, co-author, etc.), el AI **avisa antes de ejecutar** y pide confirmación. No reescribe silenciosamente.
+
+## Recursos relacionados
+
+- `skills/session/references/branch-verification.md` — el commit prompt requiere ramas consistentes.
+- `agent-workflow:redaccion-simple` — los mensajes de commit siguen las mismas reglas de redacción (frases cortas, sin jerga).

package/skills/agent-workflow/doctrine/session/references/communication-style.md

@@ -0,0 +1,50 @@
+# Communication style — confirm before mutate
+
+> Anchor `agent-workflow:communication-style`. Regla de interacción para skills que producen **artefactos consolidados** (release bundle SQL, release-scripts thematic bundle, project-init full overwrite).
+
+## La regla
+
+**Confirmar antes de mutar archivos consolidados.** Cuando una skill va a generar un artefacto que junta/sobrescribe el trabajo de N sesiones (no un edit puntual), pregunta al usuario antes de escribir.
+
+## Cuándo aplica
+
+| Skill | Artefacto a generar | Confirmar antes |
+|---|---|---|
+| `release` | `docs/releases/NNN-<slug>/REPORT.md` + bundle SQL | Sí |
+| `release-scripts` | `docs/releases/NNN-<slug>/scripts-by-theme/` | Sí |
+| `project-init --force` | Sobrescribir bloque AW-PROJECT existente | Sí |
+| `migrate --apply` | Renombrar `.claude/sessions/` → `.workflow/sessions/` | Sí |
+| `hub-init --apply` | Cambiar `Mode: project` → `Mode: hub` | Sí |
+
+## Cuándo NO aplica
+
+- Edits puntuales a un archivo (skills `implement`, `refactor`, `design-deliver`, etc.).
+- Read-only operations (`/agent-workflow:doctor`, `aw sessions`, `aw checkpoint-read`).
+- `--dry-run` flags — la skill solo describe lo que haría, sin escribir.
+
+## Forma del prompt
+
+```
+Voy a generar:
+- <artefacto 1>: <ruta>
+- <artefacto 2>: <ruta>
+
+Esto sobrescribe/crea N archivos. ¿Procedo?
+- Sí, generar
+- Solo dry-run (mostrá qué haría sin escribir)
+- Cancelar
+```
+
+## Si el usuario declina
+
+- **Solo dry-run**: la skill imprime el contenido que generaría y deja referencias a artefactos previos (no escribe).
+- **Cancelar**: skill aborta, no produce side effects.
+
+## Composición con sandbox-readonly
+
+Cuando la skill se invoca en plan mode (sandbox read-only), este prompt no se dispara — el plan describe lo que escribiría y queda en read-only. La confirmación viene implícita al aprobar el plan.
+
+## Refs
+
+- `sandbox-readonly-rules.md` — reglas universales de plan mode.
+- `prompts-catalog.md` (S5/M*) — otros prompts del lifecycle.

package/skills/agent-workflow/doctrine/session/references/graduacion-routing.md

@@ -0,0 +1,88 @@
+# Graduación: regla hub vs project (DEC-002)
+
+Regla canónica para decidir **dónde** se gradúa un artefacto al cerrar una sesión qtc-*. Reemplaza la regla anterior "hub-vs-fuente con prompt M12".
+
+## Regla absoluta
+
+| `workspace_mode` | Destino de la graduación |
+|---|---|
+| `hub` | **Hub root** — `<hub>/.workflow/sessions/` y `<hub>/docs/<categoria>/`. **Nunca** se gradúa a fuente. |
+| `project` | **CWD del proyecto** — `<cwd>/docs/<categoria>/` (raíz del proyecto único). |
+
+**Sin prompt por sesión.** El destino se decide automáticamente leyendo `workspace_mode` del bloque AW-PROJECT en `CLAUDE.md` / `AGENTS.md`. Eliminado M12 (graduacion-destino).
+
+## Definiciones operativas
+
+- **`workspace_mode=hub`**: workspace con bloque `Mode: hub` en CLAUDE.md/AGENTS.md y `.workflow/` propio que coordina ≥2 fuentes (cada una con su propio repo + branch). Toda graduación va al hub.
+- **`workspace_mode=project`**: workspace single-repo (sin `Mode: hub`). Toda graduación va al cwd.
+
+## Kinds graduables (modelo nuevo, DEC-003)
+
+Sólo 6 kinds graduan vía `agent-workflow graduate`. El resto vive en la sesión y no se gradúa.
+
+| Kind | Destino | Disparado por |
+|---|---|---|
+| `decision` | `docs/decisiones/NNN-<slug>.md` | `agent-workflow graduate --kind decision` (al cerrar) |
+| `manual` | `docs/manuales/NNN-<slug>.md` | `agent-workflow graduate --kind manual` (al cerrar) |
+| `script` | `docs/scripts/NNN-sessionXXX-<slug>/` | **`/agent-workflow:release` exclusivamente** (no `graduate --kind script` directo) |
+| `especificacion` | `docs/especificaciones/NNN-<slug>/` | `agent-workflow graduate --kind especificacion` (al cerrar) |
+| `conclusion` | `docs/conclusiones/NNN-<slug>.md` | `agent-workflow graduate --kind conclusion` (al cerrar; opt-in — default es no graduar) |
+| `release` | `docs/release/NNN-informe-release.md` | **`/agent-workflow:release` exclusivamente** |
+
+Eliminados del modelo nuevo: `plan`, `refactor`, `design`, `design-system`, `propuesta`, `postmortem`, `analysis`. Estos artefactos:
+- Se quedan en `.workflow/sessions/<folder>/` (no se gradúan).
+- O se promueven manualmente a `manual` / `especificacion` si el usuario decide curarlos.
+
+## Árbol de decisión
+
+```
+1. Leer workspace_mode del bloque AW-PROJECT (CLAUDE.md/AGENTS.md).
+2. ¿workspace_mode == "hub"?
+   ├─ SÍ  → destino = <hub>/docs/<categoria>/. Stop.
+   └─ NO  → destino = <cwd>/docs/<categoria>/. Stop.
+```
+
+Sin prompts. Sin override. Sin breadcrumbs entre hub y fuente.
+
+## Por qué se eliminó M12 y la regla hub-vs-fuente
+
+- **Antes (≤v3.x)**: defaults por kind + prompt M12 cuando ambiguo + breadcrumbs en `000-INDEX.md`. Mucha lógica para decidir destino.
+- **Ahora (DEC-002)**: el `workspace_mode` ya declara la intención del usuario al abrir el workspace. Hub mode → hub es deliverable; el usuario armó el hub para coordinar. Project mode → todo va al proyecto.
+- **Consecuencia**: si una fuente quiere documentación propia, el usuario abre un workspace project con esa fuente como cwd. Si quiere documentación cross-fuente, abre el hub.
+
+## `docs/referencias/` — no se gradúa (DEC-004 v2)
+
+Material de referencia del usuario vive en una única carpeta transversal: `<workspace-root>/docs/referencias/` (hub root en hub mode, cwd root en single-repo). Cualquier formato (md, pdf, xlsx, png, txt, etc.). Cualquier sesión activa puede leerla on-demand sin tener que subirla por-sesión.
+
+Reglas:
+- **Único path canónico**: `docs/referencias/`. La carpeta legacy `.workflow/sessions/<folder>/referencias/` (DEC-004 v1) no se lee; queda como histórico inerte en sesiones cerradas. El rescate de contenido pasa por `agent-workflow:migrate` opt-in.
+- **Manual del usuario**: el usuario coloca archivos ahí; el AI sólo lee si existe.
+- **El AI no escribe en `docs/referencias/` salvo solicitud explícita** ("guardá esto en referencias", "agregá este wireframe a referencias").
+- **Lazy**: la carpeta no se crea automáticamente; aparece cuando el usuario la inicializa (puede sembrar `docs/referencias/README.md` describiendo el contrato).
+- **No se gradúa**: queda en `docs/referencias/`, fuera del flujo de graduación de las 6 kinds. Persiste mientras viva el workspace.
+
+## Comando
+
+```
+agent-workflow graduate --kind <kind> --session <CODE> --slug <kebab>
+```
+
+El CLI internamente:
+1. Lee `workspace_mode` desde el bloque AW-PROJECT.
+2. Resuelve `docs_root`:
+   - hub mode → `<hub-cwd>/docs/`.
+   - project mode → `<cwd>/docs/`.
+3. Numera con `next-number <docs_root>/<categoria>/`.
+4. Mueve el artefacto desde `.workflow/sessions/<folder>/` al destino.
+
+No requiere flags adicionales (`--destination`, `--source`, `--breadcrumb`). El destino es función pura de `workspace_mode + kind`.
+
+## Validación posterior (doctor)
+
+`agent-workflow doctor` puede verificar:
+- En hub mode: que ningún `<fuente>/docs/<categoria>/` tenga artefactos graduados desde una sesión del hub (warn si los hay — son legacy).
+- En project mode: que `<cwd>/docs/<categoria>/` tenga la numeración consistente.
+
+---
+
+**Origen**: session006-dev-modelo-artefactos-lifecycle (DEC-002, 2026-05-07). Reemplaza la versión basada en routing hub-vs-fuente con prompt M12.

package/skills/agent-workflow/doctrine/session/references/lifecycle-deep.md

@@ -0,0 +1,160 @@
+# Lifecycle universal — detalles avanzados
+
+Contenido detallado movido desde `SKILL.md` para optimización de tokens (lazy-load).
+
+## Plan subagent nativo (v2.3+ — opcional)
+
+Para descomposiciones `lite` o `full`, agent-workflow puede delegar la estructuración del plan al Plan subagent nativo del cliente (Claude Code expone `Task(subagent_type="Plan")`).
+
+### Detección del harness
+
+```
+agent-workflow harness
+```
+
+Output: `{harness: "claude-code"|"codex"|"unknown", supports_plan_subagent: bool, detected_via: "..."}`.
+
+| Harness | supports_plan_subagent | Acción |
+|---|---|---|
+| `claude-code` | true | `Task(subagent_type="Plan")` con OBJECTIVE + Fuentes + decisión auto-plan. Output → TASKS.md. |
+| `codex` | false | Fallback: redactar TASKS directamente con o sin sugerencias de `specialty-choose`. |
+| `unknown` | false | Fallback igual que codex. No bloquear. |
+
+### Prompt al Plan agent (CC)
+
+```
+Estructurá un plan accionable (TASKS.md) para esta sesión qtc-*.
+
+OBJECTIVE:
+<contenido de .workflow/sessions/<folder>/OBJECTIVE.md>
+
+Fuentes (de AW-PROJECT):
+<tabla de Fuentes con paths y ramas>
+
+Auto-plan decisión: <skip|lite|full> — <reason>
+
+Restricciones:
+- TASKS.md formato: items `- [ ]` con criterio de aceptación + dependencias.
+- `lite` → 1-3 items; `full` → ≥3 items con descomposición explícita.
+- Cada item debe ser ejecutable en una sola tarea (no compuesto).
+- Sugerir orden por dependencias.
+- NO incluir steps de validación (eso va a fase 3).
+
+Devolvé el contenido completo de TASKS.md.
+```
+
+### Trade-offs
+
+- **Contexto aislado**: el Plan subagent no comparte el transcript actual. Recibe sólo el prompt construido.
+- **OBJECTIVE.md sigue siendo la fuente de verdad** persistente — sobrevive `/compact`, accesible al retomar. Plan agent es soporte, no reemplazo.
+- **Re-iteración**: si el plan resultante no satisface, editar TASKS.md directamente; no re-invocar el subagent.
+- **Skip cuando obvio**: para `auto-plan = skip` o tareas atómicas, NO invocar el subagent (latencia sin valor).
+
+### Persistencia del output
+
+1. Capturar el contenido devuelto por Task(Plan).
+2. Escribir a `.workflow/sessions/<folder>/TASKS.md` con `Write`.
+3. Mostrar al usuario el TASKS.md resultante y pedir confirmación antes de avanzar a execution.
+
+## Sub-agente per-flow (v2.4+ — opt-in)
+
+### Detección del opt-in
+
+```
+agent-workflow profiles
+```
+
+Si el output incluye `"delegate_to_subagent": true` y el harness es `claude-code`, **delegar**. Si false, unknown, o harness=Codex, **composición clásica**.
+
+### Modo delegación (opt-in + CC)
+
+```
+Task(
+  subagent_type="<flow>-agent",
+  prompt=<OBJECTIVE + Fuentes + TASKS.md + skills cross-plugin confirmadas + decisión auto-plan>
+)
+```
+
+Donde `<flow>` se lee del campo `flow` de la sesión activa (metadata persistida por `agent-workflow session-create --flow <flow>`):
+- `flow=dev` → `dev-agent` (NUNCA design-agent ni analyze-agent).
+- `flow=design` → `design-agent`.
+- `flow=analyze` → `analyze-agent`.
+
+El comando entry point es único (`/agent-workflow:session`); el flow se resolvió en planning vía heurística + S3 fallback (ver `SKILL.md` paso "Detectar flow").
+
+### Loop con sub-agente
+
+```
+Task(<flow>-agent, prompt) → output JSON con next_action
+                                       │
+                                       ▼
+                  ┌──────────┬──────────┴──────────┬─────────────┐
+              "continue"  "needs_user_input"   "validation"   "ready_for_handoff"
+                  │              │                  │                │
+              Task(...)     pasar pregunta      avanzar phase   sugerir handoff
+              de nuevo      al usuario, esperar  a validation   `/agent-workflow:session --from <flow>:<code>`
+```
+
+El caller hace el bucle hasta que `next_action ∈ {validation, ready_for_handoff}` o el usuario detenga.
+
+### Trade-offs
+
+- **Aislamiento**: el sub-agente NO ve el transcript principal. Recibe sólo el prompt construido.
+- **Latencia**: cada delegación es 1 round-trip extra. Compensa en sesiones largas.
+- **Default off**: opt-in vía `~/.workflow/user-config.md` para no romper sesiones existentes.
+
+Si delegás, **saltar la sección "Composición dinámica de especialidades"** del SKILL.md — el sub-agente la maneja internamente.
+
+## Composición dinámica de especialidades
+
+| Necesidad | Skill a invocar | Flow |
+|---|---|---|
+| Editar código (Java/TS/etc.) | `implement` + `coding-standards` | dev |
+| Migración SQL / scripts BD | `sql-script-organizer` + `sql-rollback-generator` | dev |
+| Producir spec UI | `design-deliver` + `frontend-design` | design |
+| Investigación técnica | `analyze-investigate` | analyze |
+| Cierre de análisis (propuesta / informe / post-mortem) | `analyze-conclude` (modulado por modalidad) | analyze |
+| UI form / list / modal (referencia) | `frontend-design` | design |
+| Test strategy | `testing-strategy` | dev |
+
+> Todos los skills viven en `agent-workflow` (consolidación v2.0.0). La columna "Flow" indica el agrupamiento conceptual de la skill, no el plugin que la hospeda.
+
+**Reglas de activación** (regla cero — v2.1+):
+
+- Skills del **mismo flow**: el AI las invoca por contexto cuando aplican. Composición interna autorizada.
+- Skills **cross-plugin**: el AI las **sugiere al usuario** y espera confirmación explícita. Invocación por namespace (`Skill(agent-workflow:frontend-design)` post-Fase C; legacy `Skill(qtc-design:frontend-design)` válido durante convivencia) o `@`-mención. Nunca auto-invocar por keyword.
+
+## Hub mode (v4.5+)
+
+Si el workspace declara `Mode: hub` (detectado vía `agent-workflow workspace-mode`):
+
+- **Crear sesión**: pedir explícitamente las **ramas de trabajo por fuente** (al menos para las que la sesión va a tocar). Las pre-existentes en AW-PROJECT.Status pueden sugerirse como default.
+- **Verificar rama**: `agent-workflow sources` itera todas las fuentes. Para subset: `--scope alias1,alias2`.
+- **Auto-plan**: si la sesión menciona ≥2 fuentes en OBJECTIVE, peso adicional hacia `full`.
+- **Topic-change**: divergencia entre fuentes-tocadas y fuentes-mencionadas-en-OBJECTIVE es señal adicional.
+- **Composición cross-flow**: igual que en project mode — namespace explícito.
+
+Para `Mode: project` (default), todas las heurísticas hub-aware quedan inactivas.
+
+## Sandbox read-only
+
+Reglas universales en `references/sandbox-readonly-rules.md`. El lifecycle entero queda **en pausa** durante plan mode.
+
+| Fase | Qué describir (no ejecutar) |
+|---|---|
+| **Crear sesión** | Carpeta + archivos OBJECTIVE.md/TASKS.md + filas en HISTORY/AW-PROJECT. |
+| **Phase 1 (planning)** | Output esperado de `auto-plan-decide` y `specialty-choose`. NO invocar skills sugeridas. |
+| **Phase 2 (execution)** | Lista de archivos, scripts SQL, decisiones. Verificación read-only de rama. |
+| **Phase 3 (validation)** | Comandos de test con args. NO ejecutar destructivos. |
+| **Phase 4 (closure)** | Lista de artefactos a graduar + paths destino. |
+
+Sub-comandos plan-mode-safe: `project-md-upsert --read`, `sessions`, `auto-plan-decide`, `specialty-choose`, `topic-change-check`, `session-resume`, `checkpoint-read`, `objetivo-data`, `tasks-data`, `decisiones-list`, `session-artifacts`.
+
+## Compatibilidad legacy
+
+Migrables con `/agent-workflow:migrate`:
+- Sesiones v1.x con fases per-flow → mapeo a 4 fases v2.0.
+- Bloques `<!-- QTC-WORKFLOW -->` (pre-v0.8) → AW-PROJECT.
+- `STATUS.md`, `REQUIREMENTS.md`, etc.
+
+No migrar automáticamente; usuario decide.

package/skills/agent-workflow/doctrine/session/references/prompts/C1-specialty-selection.md

@@ -0,0 +1,11 @@
+# C1 — specialty-selection (planning)
+
+Spec literal del prompt C1. Index: [`../prompts-catalog.md#c1--specialty-selection-planning`](../prompts-catalog.md#c1--specialty-selection-planning).
+
+- **Cuándo**: planning phase, después de `agent-workflow specialty-choose --phase planning`, hay 2+ skills sugeridas.
+- **Forma**: 1 question multi-select.
+  - `header`: `specialty`.
+  - `question`: "¿Qué skills invoco para descomponer el plan?"
+  - `multiSelect`: true.
+  - `options` (≤4): nombres de skills sugeridas con namespace (ej. `agent-workflow:analyze-synthesize`, `agent-workflow:design-brief`, `agent-workflow:implement` post-Fase C; aliases legacy `qtc-analyze:analyze-synthesize` etc. válidos durante convivencia) y descripción de qué hace cada una en planning.
+- **Refina**: prosa en `skills/session/SKILL.md` "Plan agent + Specialty (suggestion-only)".

package/skills/agent-workflow/doctrine/session/references/prompts/C2-cost-guard.md

@@ -0,0 +1,14 @@
+# C2 — cost-guard (queries pesadas en analyze-investigate)
+
+Spec literal del prompt C2. Index: [`../prompts-catalog.md#c2--cost-guard-queries-pesadas-en-analyze-investigate`](../prompts-catalog.md#c2--cost-guard-queries-pesadas-en-analyze-investigate).
+
+- **Cuándo**: `agent-workflow:analyze-investigate` (legacy `qtc-analyze:analyze-investigate`) antes de ejecutar query categorizada como **costosa** (>10k filas o seq scan >100k según `references/cost-guard.md`).
+- **Forma**: 1 question + preview.
+  - `header`: `cost`.
+  - `question`: "Esta query estima `<filas>` filas / `<duración>`s en `<server>`. ¿La ejecuto?"
+  - `multiSelect`: false.
+  - `options`:
+    1. "Proceder (Recomendado si esperás el costo)" — "Ejecuta con cost guard registrado en `EVIDENCE.md`."
+    2. "Cancelar" — "No la ejecuta; podés reformular o usar muestreo."
+  - `preview`: SQL de la query + plan EXPLAIN resumido (5-10 líneas).
+- **Refina**: paso 3 ("aviso al usuario") del procedimiento en `qtc-analyze/skills/analyze-investigate/references/cost-guard.md`.