@tacuchi/agent-workflow-cli 11.0.1 → 12.0.0

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

@@ -1,198 +0,0 @@
-# Verificación de rama de trabajo — Referencia canónica (agent-workflow)
-
-> Documento canónico de la familia agent-workflow para validación y orquestación de ramas. Referenciado por `skills/session/SKILL.md` y el hook PreToolUse (`agent-workflow hook branch-check`). Los workflows especializados (`analyze-workflow`, `design-workflow`, `dev-workflow`) **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

@@ -1,111 +0,0 @@
-# commits-policy — política controlada de commits agent-workflow
-
-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 agent-workflow.
-
-# 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 agent-workflow (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 agent-workflow 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 agent-workflow** (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 agent-workflow) → 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 export-scripts / graduation
-
-Los skills `export-scripts` y `graduate` (agent-workflow) son solo lectura/reporte: nunca commitean ni mergean — 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

@@ -1,50 +0,0 @@
-# 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

@@ -1,88 +0,0 @@
-# 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 agent-workflow. 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

@@ -1,160 +0,0 @@
-# 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 agent-workflow.
-
-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

@@ -1,11 +0,0 @@
-# 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

@@ -1,14 +0,0 @@
-# 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`.