@tacuchi/agent-workflow-cli 6.1.0 → 7.0.0

package/skills/agent-workflow/doctrine/refactor/references/refactor-md-template.md

@@ -0,0 +1,108 @@
+# Template REFACTOR.md — agent-workflow:refactor
+
+Artefacto canónico del skill `refactor`. Vive en `.workflow/sessions/sessionNNN-dev-refactor-<slug>/REFACTOR.md` durante la sesión.
+
+> **Modelo de artefactos (DEC-003)**: REFACTOR.md **no se gradúa con kind dedicado**. Vive en la sesión y se consulta desde ahí. Si el documento amerita preservarse, el usuario lo cura manualmente como `manual` (cómo se reorganiza el módulo) o `especificacion` (contrato del módulo nuevo). El destino al graduar respeta `workspace_mode` (DEC-002): hub mode → `<hub>/docs/<categoria>/`; project mode → `<cwd>/docs/<categoria>/`.
+
+## Estructura mínima
+
+```markdown
+# Refactor — <feature-name>
+
+## Análisis legacy
+
+### Paths involucrados
+- FE: `<repo>/src/<path>`
+- BE: `<repo>/<package-path>`
+- DB: `<schema>.<tabla>`, funciones `fn_*`, SP `sp_*`
+
+### Endpoints actuales
+| Verbo | Path | Acción | DTO request | DTO response |
+|---|---|---|---|---|
+| GET | `/api/<feature>` | listar | — | `<Feature>Response[]` |
+| POST | `/api/<feature>` | crear | `<Feature>CreateRequest` | `<Feature>Response` |
+| PUT | `/api/<feature>/{id}` | editar (full) | `<Feature>UpdateRequest` | `<Feature>Response` |
+| DELETE | `/api/<feature>/{id}` | eliminar | — | 204 |
+
+### DTOs actuales
+- `<Feature>CreateRequest`: <count> campos, todos required
+- `<Feature>UpdateRequest`: <count> campos, casi idénticos a Create
+- `<Feature>Response`: mapeo entidad
+
+### Validaciones / reglas de negocio
+- Regla 1: …
+- Regla 2: …
+
+### Accesos / roles
+- Permite roles: `admin.x`, `comercial.y`
+- Bypass super-admin: sí/no
+
+### Smells detectados (motivación del refactor)
+- DTOs Create/Update duplicados (fix: Sparse DTO unificado)
+- PUT envía toda la entidad (fix: PATCH sparse)
+- `try/catch` que silencia errores (fix: fail-fast)
+- Otros: …
+
+## Diseño nuevo
+
+### Paths nuevos
+- FE: `<repo>/src/<path>` (mismo nombre, después de rename del legacy)
+- BE: `<repo>/<package-path>` (mismo nombre, después de rename del legacy)
+
+### Endpoints nuevos
+| Verbo | Path | Acción | DTO | Cambio vs legacy |
+|---|---|---|---|---|
+| GET | `/api/<feature>` | listar | — / `<Feature>Response[]` | igual |
+| POST | `/api/<feature>` | crear | `<Feature>SaveRequest` | DTO unificado |
+| PATCH | `/api/<feature>/{id}` | editar sparse | `<Feature>SaveRequest` | PUT → PATCH; sparse |
+| DELETE | `/api/<feature>/{id}` | eliminar | — | igual |
+
+### DTOs nuevos (Sparse DTO unificado)
+- `<Feature>SaveRequest`: campos nullable, sirve para create + edit. En edit, null = no tocar.
+- `<Feature>Response`: ajustado si aplica.
+
+### Reglas FE-BE aplicadas (checklist)
+- [ ] Mismo DTO Create/Edit (Sparse).
+- [ ] PATCH para edit, sparse object.
+- [ ] BE no usa fallbacks que oculten errores; valida con Bean Validation y devuelve 400 estructurado.
+- [ ] FE propaga errores HTTP via toast/mensaje (sin `catchError(() => of([]))`).
+- [ ] DB: funciones nuevas arrancan en Phase 0 como stub (devuelven mock); implementación real en Phase 1/2.
+
+## Plan de migración (12 pasos Strangler)
+
+1. [ ] Análisis completo (esta sección + sigs.).
+2. [ ] M7 confirma estrategia de rename (auto/manual/solo-análisis).
+3. [ ] `git mv` FE: `src/.../<feature>/` → `src/.../<feature>-legacy/`.
+4. [ ] `git mv` BE: paquete `<feature>` → `<feature>_legacy` (si aplica al stack).
+5. [ ] Crear nuevo `<feature>/` en FE + BE desde cero (vacío para Phase 0).
+6. [ ] Phase 0 — Contrato: interfaces FE + DTOs BE + endpoints stub + funciones BD mock.
+7. [ ] M6 — phase-gate (Phase 0 → 1). [Nota: S7 design-review ya fue disparado antes de Phase 0 desde planning closure, v2.8+ — reemplazó a M9.]
+8. [ ] Phase 1 — Lecturas: GET, listados, filtros, combos.
+9. [ ] M6 — phase-gate (Phase 1 → 2).
+10. [ ] Phase 2 — Mutaciones: POST + PATCH (sparse) + DELETE + scripts BD reales.
+11. [ ] Validación e2e por usuario.
+12. [ ] M8 — refactor-cleanup: `git rm -r <feature>-legacy/` + REFACTOR.md `legacy_purged: true`.
+
+## Estado
+
+```yaml
+status: discovery | legacy-marked | implementing | validating | completed
+phase: 0 | 1 | 2 | done
+legacy_purged: false | true
+created: 2026-MM-DD
+last_update: 2026-MM-DD
+```
+
+## Refs
+
+- Sesión origen: `.workflow/sessions/sessionNNN-dev-refactor-<slug>/`
+- DECISIONS.md de la sesión: decisiones load-bearing del refactor.
+- `agent-workflow:prompts-catalog` M7/M8.
+- `agent-workflow:coding-standards/references/fe-be-integration.md`.
+```
+
+## Notas de uso
+
+- **Tamaño esperado**: 200-400 líneas para un mantenimiento CRUD típico. Si crece más, dividir en sub-features (cada uno con su propia sesión `## Type: refactor`).
+- **No prescribir lenguaje natural redundante**: las tablas son densas a propósito. REFACTOR.md vive en la sesión y, si amerita preservarse, se cura manualmente como `manual` o `especificacion` (DEC-003).
+- **Cuando standalone (sin sesión)**: el archivo se nombra `REFACTOR-<slug>.md` en el CWD; status queda en `discovery` y no avanza.

package/skills/agent-workflow/doctrine/refactor/references/strangler-checklist.md

@@ -0,0 +1,116 @@
+# Strangler Fig — checklist de 12 pasos para refactor
+
+Pasos canónicos del skill `agent-workflow:refactor`. Reflejan Strangler Fig (Fowler) adaptado al stack qtc-* con flujo phased y prompts M7/M8/M6 + S7 (pre-Phase 0). M9 retirado en v2.8+ por DEC-002 de session049 — reemplazado por S7 desde planning closure.
+
+## Discovery (paso 1-2)
+
+### 1. Análisis legacy
+
+Compone con `agent-workflow:analyze-investigate`. Outputs en REFACTOR.md sección "Análisis legacy":
+
+- Paths FE / BE / DB.
+- Endpoints actuales (verbo, path, DTOs).
+- DTOs (counts, redundancias).
+- Validaciones y reglas de negocio detectadas en el código.
+- Accesos / roles.
+- Smells (DTOs duplicados, fallbacks que ocultan errores, PUT en lugar de PATCH, etc.).
+
+### 2. REFACTOR.md draft
+
+AI redacta sección "Análisis legacy" + "Diseño nuevo" + "Plan de migración" (1-12) + "Estado" inicial (`status: discovery`).
+
+Usuario revisa el draft. Si aprueba → paso 3. Si pide cambios, AI itera.
+
+## Marcar legacy (paso 3-5)
+
+### 3. M7 — refactor-legacy-detected
+
+Prompt al usuario con 3 opciones (rename + AI imports / rename + IDE imports / solo análisis). Spec literal en `agent-workflow:prompts-catalog#M7`.
+
+### 4. Rename Strangler
+
+- FE: `git mv <repo>/src/.../<feature>/ <repo>/src/.../<feature>-legacy/`.
+- BE (Spring/Java): renombrar paquete `<feature>` → `<feature>_legacy`, actualizar imports si la opción A fue elegida.
+- BD: **NO** se renombran funciones/SP — la BD es estado, no código. Las funciones nuevas se crean en paralelo durante Phase 0/1/2 con nombres canónicos.
+
+### 5. Crear `<feature>/` vacía
+
+- FE: crear `src/.../<feature>/` con módulo skeleton (NgModule vacío + service stub).
+- BE: crear paquete `<feature>` con controller stub + DTOs vacíos (Sparse DTO).
+
+REFACTOR.md → `status: legacy-marked`.
+
+## Generar TASKS.md phased (paso 6)
+
+### 6. Hand off a `implement`
+
+`refactor` genera TASKS.md con secciones canónicas:
+
+```markdown
+## Phase 0 — Contrato
+- [ ] Interfaces FE: `<Feature>Service` con métodos `list/save/delete` que arrojan "not impl"
+- [ ] DTOs BE: record `<Feature>SaveRequest` (Sparse, campos nullable)
+- [ ] Endpoints BE: `@PatchMapping` que devuelven 501
+- [ ] Funciones BD: `fn_<feature>_listar` que devuelve mock `[]::jsonb`
+- [ ] Cableado: FE llama BE → 501 capturado por handler → toast informativo
+
+## Phase 1 — Lecturas
+- [ ] GET /api/<feature> con paginación + filtros
+- [ ] FE listado con grilla, combos, search
+- [ ] Funciones BD reales para SELECT
+- [ ] Tests unitarios de queries (si aplica)
+
+## Phase 2 — Mutaciones
+- [ ] POST /api/<feature> (create con Sparse DTO)
+- [ ] PATCH /api/<feature>/{id} (edit sparse, null = no tocar)
+- [ ] DELETE /api/<feature>/{id}
+- [ ] FE formularios con validación
+- [ ] Scripts SQL: DDL/DML reales bajo `docs/scripts/`
+- [ ] Tests e2e si aplica
+```
+
+`implement` toma TASKS.md y ejecuta el loop con M6 (phase-gate Phase 1→2). S7 (design-review) fue disparado antes de Phase 0 desde planning closure de `skills/session/SKILL.md` (v2.8+ — reemplazó a M9 que disparaba post-stub).
+
+REFACTOR.md → `status: implementing`, `phase: 0`.
+
+## Validación (paso 7-8)
+
+### 7. Validación e2e
+
+Cuando `implement` cierra Phase 2, REFACTOR.md → `status: validating`.
+
+El usuario:
+- Levanta FE + BE en local.
+- Ejecuta scripts SQL contra cert.
+- Prueba flujos: create, list, filter, edit (sparse), delete.
+- Compara contra el comportamiento legacy si está disponible.
+
+Confirma con la AI: "validado, todo funciona".
+
+REFACTOR.md → `status: completed` (pero `legacy_purged: false` aún).
+
+### 8. M8 — refactor-cleanup
+
+Prompt al usuario con 3 opciones (eliminar / mantener / cancelar). Spec literal en `agent-workflow:prompts-catalog#M8`.
+
+Si elige eliminar:
+- `git rm -r <repo>/src/.../<feature>-legacy/` (FE).
+- `git rm -r <package>_legacy/` (BE) si aplica.
+- BD: si hay funciones legacy paralelas que deben removerse, generar script SQL bajo `.workflow/sessions/<sessionNNN>/scripts/cleanup-<feature>.sql` con `DROP FUNCTION IF EXISTS ...`. El bundle final se arma vía `/agent-workflow:release` (kind=`script`). **El AI NO ejecuta el script** — el usuario lo aplica.
+
+REFACTOR.md → `legacy_purged: true`.
+
+## Closure
+
+REFACTOR.md vive en la sesión (`.workflow/sessions/<folder>/REFACTOR.md`) y **no se gradúa con kind dedicado** (DEC-003). Si el documento amerita preservarse fuera de la sesión, el usuario lo cura como `manual` o `especificacion`. La sesión cierra siguiendo el flujo estándar (commits via M1, compact, session-close).
+
+## Errores y rollback
+
+| Situación | Acción |
+|---|---|
+| Phase 1 falla, lecturas no funcionan | Re-iterar Phase 1 (M6 opción 3) sin tocar legacy. Legacy sigue funcionando como referencia. |
+| Phase 2 falla, mutaciones rompen | Re-iterar Phase 2 con DECISION nueva en DECISIONS.md. Legacy sigue intacto. |
+| Validación e2e descubre regresión grave | Pausar refactor, abrir DECISIÓN documentando, decidir si seguir o rollback. NO disparar M8 cleanup. |
+| Usuario abandona el refactor a mitad de camino | REFACTOR.md mantiene `status: implementing` o `validating`; legacy sigue intacto. La sesión se puede retomar más tarde. |
+
+**Nunca** se borra el legacy hasta que M8 se confirme con `## Estado: completed` + validación e2e explícita del usuario. Esto garantiza que el rollback siempre es posible (Strangler Fig: "transform → coexist → eliminate").

package/skills/agent-workflow/doctrine/resume/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: resume
+description: Lee CHECKPOINT.md de la sesión activa, sintetiza placeholders si hace falta y presenta resumen de dónde quedó el trabajo. Invocado vía /agent-workflow:resume, NL como retomar/donde quedamos/continuar, o automáticamente desde el PostCompact hook tras /compact. Fallback a session-resume base si no hay checkpoint.
+version: 2.4.0
+---
+
+# Resume — qtc v2.1
+
+Recupera el estado de la sesión activa después de un compact (o al volver al proyecto). Lee `.workflow/sessions/<folder>/CHECKPOINT.md` y lo presenta al usuario.
+
+## Triggers
+
+- **Slash explícito**: `/agent-workflow:resume`.
+- **NL del usuario**: "retomar", "retomemos", "donde quedamos", "continuar", "seguir con la sesión".
+- **Automático en PostCompact hook**: tras un `/compact` el hook lee el resumen y se lo pasa al AI para presentarlo.
+
+## Acción
+
+### 1. Detectar sesión(es) activa(s)
+
+```
+agent-workflow resume-summary
+```
+
+Output:
+```json
+{
+  "active_sessions": ["session046-dev-jobs-async"],
+  "primary_session": "session046-dev-jobs-async",
+  "phase_from_qtc_project": "execution",
+  "branches_from_qtc_project": ["mscore-solicitud-spring=feature/session046"],
+  "checkpoint_present": true,
+  "checkpoint": {
+    "actualizado": "2026-04-25 20:14",
+    "fase": "execution (2/4)",
+    "avance": "60% (3 de 5 tareas en TASKS.md completas)",
+    "proximo": ["Implementar el consumer de la cola DLQ"]
+  }
+}
+```
+
+Si `active_sessions` está vacío → "No hay sesiones activas para retomar." y stop.
+
+### 2. Síntesis post-compact (fill placeholders)
+
+Si la sesión activa tiene `checkpoint_status` en `missing`, `draft` o `stale`, ejecutar antes de presentar:
+
+1. Si `checkpoint_status: missing`: ejecutar `agent-workflow checkpoint-write --code <primary_session_code>` para regenerar el draft. Continuar con el draft recién generado.
+2. Si `checkpoint_status: draft` o `stale` (o el draft recién se regeneró): leer `checkpoint_path` y rellenar cada placeholder `_[AI: ...]_` con la mejor información disponible. Mapeo de campos:
+   - `ultimo` → 1-3 oraciones del último avance, basado en `decisiones recientes` y archivos tocados.
+   - `proximo` → 1-2 oraciones leyendo el primer ítem abierto de TASKS.md de la sesión.
+   - `archivos_proposito` → 1 línea por archivo en la lista.
+   - `contexto` → 2-3 párrafos con info mínima para retomar.
+   - `skills` → lista de skills invocadas (en post-compact suele ser solo `compact`/`resume`).
+3. Si para algún campo no hay información suficiente: escribir `_(sin info — completar al retomar)_` en lugar de inventar. Editar el archivo con la herramienta Edit.
+
+Si `checkpoint_status: complete` (o `needs_ai_action: false`): saltar este paso. Pasar directo a la presentación.
+
+Esta lógica vivía antes en el hook PostCompact (entry prompt). Quedó acá porque (a) es lógica de skill no de hook (boundary clean), y (b) Codex no soporta prompt-type en hooks → en CC se auto-dispara via /agent-workflow:resume; en Codex el usuario lo invoca manualmente.
+
+### 3. Si hay CHECKPOINT.md
+
+Leer el archivo completo:
+
+```
+agent-workflow checkpoint-read --code <CODE>
+```
+
+Presentar al usuario un resumen estructurado:
+
+```markdown
+**Sesión activa**: session046-dev-jobs-async
+**Fase**: execution (2/4) · 60% completa (3/5 tareas)
+**Última actualización**: 2026-04-25 20:14
+
+**Lo último que hicimos**: <campo del checkpoint>
+
+**Próximo paso**: <campo del checkpoint>
+
+**Decisiones recientes**:
+<lista>
+
+**Archivos tocados sin commit**:
+<lista corta>
+
+**Contexto crítico**:
+<párrafos del checkpoint>
+```
+
+Y disparar `AskUserQuestion` con spec de S5 (`../session/references/prompts-catalog.md#S5`). Header `post-compact`, 3 opciones (Retomar misma sesión / Abrir nueva sesión / Solo recapitular, después decido). **Recomendación dinámica**: el AI marca `(Recomendado)` en opción 1 si CHECKPOINT.md indica `tasks_open ≥ 1`; caso contrario marca opción 2. NO narrar la pregunta en texto plano.
+
+Resolución por opción:
+
+- **Retomar misma sesión** → cargar OBJECTIVE.md, TASKS.md, DECISIONS.md como contexto activo; verificar ramas (`agent-workflow sources`); reanudar en la fase indicada.
+- **Abrir nueva sesión** → cerrar la actual como `paused` (graduación postergada) y delegar al skill `session` con prompt de OBJECTIVE.
+- **Solo recapitular** → mantener el resumen presentado; pausar el loop y dejar que el usuario decida en próximo turno.
+- **Other auto** → instrucción custom (ej. "retomá pero salteá a la T5") — interpretar y aplicar; si ambiguo, fallback a "Solo recapitular".
+
+**Si CHECKPOINT.md ausente o ilegible**: skip S5 y fallback a `session-resume` base con soft prompt "¿Continuamos desde acá?".
+
+### 4. Si NO hay CHECKPOINT.md
+
+Fallback a:
+
+```
+agent-workflow session-resume --code <CODE>
+```
+
+Devuelve campos base (objetivo, fase, ramas, tasks counts). Presentar como resumen y preguntar si continúa.
+
+### 5. Si hay múltiples sesiones activas
+
+Listar todas con resumen 1-línea cada una y pedir al usuario seleccionar cuál retomar.
+
+### 6. Si NO hay sesiones activas — detectar cerradas con artefactos (F-E.2)
+
+Cuando `resume-summary` retorna `active_sessions: []`, re-invocar con `--include-recent-closed` para detectar sesiones cerradas en los últimos 7 días que tengan artefactos "completos":
+
+```
+agent-workflow resume-summary --include-recent-closed
+```
+
+Heurística "completos" por flow (definida en G5 de session062):
+
+| Flow | Criterio |
+|---|---|
+| `analyze` | `EVIDENCE.md` + `FINDINGS.md` + `CONCLUSIONS.md` presentes |
+| `dev` | `TASKS.md` con ≥50% closed Y `DECISIONS.md` presente |
+| `design` | `DELIVERY.md` presente |
+
+Si `recent_closed_with_artifacts.length > 0`, disparar `AskUserQuestion` con spec del S-prompt `closed-with-artifacts` (`../session/references/prompts-catalog.md#closed-with-artifacts`):
+
+- Header: `closed-with-artifacts`.
+- 4 opciones:
+  1. **Export plan** — invocar `/agent-workflow:export-plan --sessions <NNN>` con la sesión elegida.
+  2. **Export conclusions** — invocar `/agent-workflow:export-conclusions --sessions <NNN>` (solo si la sesión es analyze con CONCLUSIONS).
+  3. **Abrir nueva sesión** — delegar a `/agent-workflow:session` con prompt OBJECTIVE.
+  4. **Solo recapitular** — leer artefactos y presentar resumen, sin acción derivada.
+
+**Recomendación dinámica**: si hay 1 sola sesión analyze cerrada → opción 2 marcada `(Recomendado)`. Si hay ≥2 sesiones del mismo dominio → opción 1 marcada `(Recomendado)`. Sin ambigüedad: el AI explica brevemente la heurística antes del prompt.
+
+**Other auto** = "Otra acción" → registrar como nota informal y consultar.
+
+Si `recent_closed_with_artifacts.length == 0`: "No hay sesiones activas para retomar." y stop (comportamiento previo).
+
+## Ejemplo
+
+Usuario abre Claude Code después de un compact previo.
+
+PostCompact hook dispara → AI ejecuta `agent-workflow resume-summary` → recibe el JSON.
+
+AI presenta:
+```
+Sesión activa: session046-dev-jobs-async (execution 2/4, 60%).
+
+Última actualización: 2026-04-25 20:14.
+
+**Lo último**: Implementé el publisher de jobs con RabbitMQ — flujo end-to-end de
+encolado funciona, mensajes llegan a `qtc.jobs.priority`.
+
+**Próximo paso**: Implementar el consumer de la cola DLQ con retry exponencial.
+
+**Decisiones recientes**: DEC-003 — Usar RabbitMQ exchange `topic` (no `direct`)
+para soportar wildcards en routing keys.
+
+**Contexto crítico**: La cola principal usa publisher confirms; el consumer DLQ
+debe replicar el patrón. El test de integración corre en `mscore-jobs-test`.
+
+¿Continuamos desde el consumer DLQ?
+```
+
+Usuario: "sí" → AI carga TASKS.md, busca el item del consumer, arranca implementación.
+
+## Sandbox read-only
+
+Reglas universales en `../session/references/sandbox-readonly-rules.md` (canon agent-workflow).
+
+`resume` es read-only por diseño — los sub-comandos que invoca (`resume-summary`, `checkpoint-read`, `session-resume`) están todos en la lista plan-mode-safe. Igual, en plan mode esta skill describe en el plan file:
+
+- Qué sesión activa se detectó (output de `resume-summary`) — lectura ya ejecutada o a ejecutar.
+- Qué presentaría al usuario (resumen estructurado: fase, avance, lo último, próximo paso, decisiones, archivos sin commit, contexto crítico).
+- Qué **NO** hace: cargar OBJECTIVE.md (legacy: OBJETIVO.md) / TASKS.md / DECISIONS.md (legacy: DECISIONES.md) como contexto activo (eso es para post-aprobación del plan), ni invocar `agent-workflow sources` que también es read-only pero forma parte del "flujo activo" post-plan.
+
+## Reglas
+
+- **Una sola sesión por turno**: si hay varias activas, presentar todas pero retomar una a la vez.
+- **No asumir continuación**: siempre preguntar antes de cargar contexto profundo.
+- **CHECKPOINT.md > session-resume base**: si existe checkpoint, es la fuente de verdad. Si no, base.
+- **Branches verification**: antes de editar, correr `agent-workflow sources`.
+
+## Política — sin fallback al CLI
+
+Si `agent-workflow resume-summary`, `checkpoint-read` o `sources` falla (no está en PATH, comando no reconocido, exit code != 0), **cortá la acción y reportá al usuario**: pedile que verifique `npm install -g @tacuchi/agent-workflow-cli`. No hay flujo alternativo Python.
+
+## Recursos
+
+- `agent-workflow checkpoint-read` — lectura programática del último CHECKPOINT.md.
+- shared-contract.md §17 — formato CHECKPOINT.md.
+- **`agent-workflow:redaccion-simple`** — guía de redacción para el resumen que se presenta al retomar. Frases cortas, una idea por línea.

package/skills/agent-workflow/doctrine/rules/SKILL.md

@@ -0,0 +1,224 @@
+---
+name: rules
+description: "Bundle invokable de reglas transversales qtc-* — carga los 7 anchors canónicos (commits, sandbox plan-mode, MCP read-only, redacción, coding-standards, graduación, branch verification) en un solo lugar. Invocar antes de un commit ad-hoc fuera de `/agent-workflow:session`, antes de editar código sin sesión activa, durante onboarding de usuario nuevo a qtc-*, o cuando se quiera refrescar el contrato qtc-* en una conversación larga. No requiere sesión activa. v0.2.0: el anchor `agent-workflow:commits-policy` ahora documenta el propose-then-execute universal con AskUserQuestion M1 (cualquier solicitud o mención de commit, en/fuera de sesión, hub/project) + el bypass por mensaje literal."
+version: 0.2.0
+---
+
+> **Profile parametrization**: lee `custom_anchors[]` de `profile.json` (resuelto vía cascade 5 capas). Ver [`references/profile-parametrization.md`](../../references/profile-parametrization.md) para el contrato completo y comportamiento por defecto cuando el profile está vacío.
+
+# Rules — Bundle invokable de reglas transversales qtc-*
+
+Skill agregadora que **carga las reglas transversales del runtime qtc-*** en un solo entry point. No reemplaza al AGENTS.md/CLAUDE.md por fuente (anchor passive de system-prompt); complementa con activación on-demand cuando se necesita refrescar el contrato.
+
+Cada sección abajo cita el canon de su anchor — el AI lee el archivo completo cuando la regla requiere precisión (parámetros, casos edge). Acá quedan los headers, las reglas operativas y "cómo aplicar fuera de sesión".
+
+## Cuándo invocar
+
+- **Antes de un commit ad-hoc fuera de `/agent-workflow:session close`** — para refrescar la política de commits (formato, tag, prohibiciones) si el usuario te pide commitear.
+- **Antes de editar código en una fuente qtc-* sin sesión activa** — para cargar coding-standards y la sandbox plan-mode.
+- **Antes de ejecutar una query vía MCP `<mcp-cert>`/`<mcp-prod>`** — para refrescar el contrato read-only y reconocer cuándo proponer script SQL en lugar de mutación.
+- **Durante onboarding** de un usuario nuevo a qtc-* — bundle único que reemplaza leer 7 archivos sueltos.
+- **En conversaciones largas** donde el contexto qtc se diluyó — refresh rápido.
+- Explícitamente con `Skill(agent-workflow:rules)` o por NL ("qué reglas qtc tengo", "antes de commitear", "refrescá el contrato qtc").
+
+## Anchors canónicos
+
+### 1. Commits — `agent-workflow:commits-policy`
+
+**Canon**: `agent-workflow/skills/session/references/commits-policy.md` (5 reglas, anchor `agent-workflow:commits-policy`).
+
+Resumen:
+- El AI **nunca commitea por iniciativa propia**. Lista cerrada de operaciones git prohibidas sin solicitud explícita: `commit`, `commit --amend`, `push/--force`, `merge`, `rebase`, `cherry-pick`, `tag`, `reset --hard`, `restore .`, `checkout -- .`, `clean`.
+- Cuando el usuario pide commit en sesión activa: 1 línea ≤72 chars, descriptiva, **incluye tag `session<NNN>`**, sin `Co-Authored-By`, sin firmas de modelo, sin `--no-verify`.
+- **Propose-then-execute universal** (Regla 3): ante cualquier solicitud o mención de commit como acción a ejecutar, el AI invoca el prompt M1 (`prompts-catalog.md#M1`) con N questions tab-por-fuente. Aplica en closure (auto), en planning/execution con sesión activa, y sin sesión activa. Hub mode = N tabs; project mode = 1 question.
+- **Bypass por mensaje literal** (Regla 5): si el usuario aporta el mensaje exacto del commit en la solicitud (`"commit con mensaje 'X'"`, `"-m 'X'"`), el AI ejecuta directo sin invocar M1.
+- `release`, `release-scripts`, `graduate` nunca commitean.
+
+Reglas operativas:
+- Conventional Commits opcional (`feat:`, `fix:`, `chore:`, etc.), no obligatorio.
+- Si la fuente tiene `match=false` (rama inesperada): no commitear; alinear primero vía branch-verification.
+
+**Cómo aplicar fuera de sesión**:
+- El tag `session<NNN>` **no aplica** (no hay sesión); el mensaje sugerido lo omite.
+- Mensaje sigue siendo 1 línea, descriptivo, sin co-author/firma/`--no-verify`.
+- **Sí hay propose-then-execute automático**: el AI llama `agent-workflow sources` (sin `--session`) y dispara M1 igual que en closure. Es el mismo prompt, con tag omitido del mensaje sugerido.
+- Workspace no qtc-* (sin `AW-PROJECT`): no hay `sources` disponible. El AI sugiere 1-line msg en chat, espera confirmación, ejecuta. M1 no se invoca en ese contexto.
+
+---
+
+### 2. Sandbox plan-mode — `agent-workflow:sandbox-readonly`
+
+**Canon**: `agent-workflow/skills/session/references/sandbox-readonly-rules.md`.
+
+Resumen:
+- Canon universal qtc-*. Cubre Claude Code (plan mode), Codex (sandbox read-only), Copilot (read-only), Warp y cualquier harness equivalente.
+- Se activa por system-reminder del host (`Plan mode is active`, `EnterPlanMode`, sandbox read-only flag, etc.).
+- En plan mode: el AI **describe en el plan file** qué haría en lugar de ejecutarlo. No crea/edita archivos, no ejecuta git/npm/SQL mutante.
+
+Reglas operativas:
+- Bloquea: `Edit`/`Write`/`MultiEdit`/`NotebookEdit`, `Bash` con efectos colaterales, `git push`, `gh pr create`, `npm publish`, SQL no idempotente.
+- Permite: `Read`, `Grep`, queries CLI read-only (`sessions`, `*-data`, `checkpoint-read`).
+- Matriz por subcomando CLI: ver §"Plan-mode-safe vs NO seguros" en el canon.
+
+**Cómo aplicar fuera de sesión**:
+- Aplica igual — el disparador es el system-reminder del host, no el lifecycle qtc-*.
+- Si la skill se carga fuera de sesión y el host está en plan mode, **describir el output en el plan file** sin ejecutar.
+
+---
+
+### 3. MCP `<mcp-cert>` / `<mcp-prod>` read-only — `agent-workflow:mcp-readonly`
+
+**Canon**: `agent-workflow/docs/shared-contract/plugins.md` §30 (Política BD universal v5.5+).
+
+Resumen:
+- MCPs `<mcp-cert>` y `<mcp-prod>` son **read-only por contrato**. Permitido: `SELECT`, `EXPLAIN`, `\d`, `\df`, `\dt`. Prohibido: `INSERT`/`UPDATE`/`DELETE`/`TRUNCATE`/`MERGE`/`CREATE`/`ALTER`/`DROP`/`GRANT`/`REVOKE`/`COPY`.
+- Mutaciones se materializan como script SQL versionado en `docs/scripts/<bundle>/` o staging de sesión. El usuario ejecuta el script manualmente; el AI nunca lo aplica.
+- Excepción única: usuario explícitamente delega ejecución por bloque ("ejecutalo vos contra cert"). Confirmación por cada bloque, limitar al destino mencionado, re-aplicar regla por default en la siguiente tarea.
+
+Reglas operativas (defensa en profundidad):
+- **Capa 1 (server-side)**: el CLI inyecta `READONLY=true` en `.mcp.json` (`agent-workflow-cli/src/domain/mcp-entry.ts:99`). El servidor `dbhub` rechaza DML/DDL a nivel TCP.
+- **Capa 2 (PreToolUse hook)**: `agent-workflow hook sql-mutation-guard` registrado en `hooks/hooks.json` con matcher `mcp__.*__execute_sql` — bloquea con exit 2 + mensaje si detecta keywords mutantes.
+- **Capa 3 (convención)**: 22 skills repiten la regla en lenguaje natural; memoria del usuario refuerza.
+- Bypass: `AW_SQL_GUARD=off` (desactiva guard), `AW_SQL_GUARD_ALLOW=cert` (permite sólo cert, no prod).
+
+**Cómo aplicar fuera de sesión**:
+- Capas 1 y 2 siguen activas (server READONLY + hook PreToolUse wired) aunque no haya sesión.
+- Si el AI necesita mutar BD: producir script en `docs/scripts/` (o staging temporal) y pedir al usuario que lo aplique — nunca ejecutar mutación vía MCP.
+
+---
+
+### 4. Redacción simple — `agent-workflow:redaccion-simple`
+
+**Canon**: `agent-workflow/skills/redaccion-simple/SKILL.md`.
+
+Resumen:
+- Guía universal de estilo para toda prosa que produzca el AI en contexto qtc-*: artefactos `.md` de sesión, commit messages, descripciones de PR, READMEs ad-hoc, respuestas en chat sobre runtime/skills qtc-*.
+- 6 reglas: frases cortas (≤15 palabras), listas sobre prosa, una idea por línea, "qué + por qué" en una línea, sin jerga inventada, sin relleno ("es importante notar…", "cabe destacar…").
+
+Reglas operativas por artefacto:
+- **OBJECTIVE**: `## Context` arranca con "Lo que NO está en la pregunta".
+- **TASKS**: prohibido código inline.
+- **DECISIONS**: si una DEC es obvia, no se registra.
+- **EVIDENCE**: cada hallazgo 4-8 líneas.
+- **CONCLUSIONS**: cada `**CN**` con link a evidencia; cada `**RN**` con responsable + cuándo.
+
+**Cómo aplicar fuera de sesión**:
+- Aplica igual a commit messages, descripciones de PR, READMEs, respuestas en chat. No requiere sesión activa.
+
+---
+
+### 5. Coding standards — `agent-workflow:coding-standards`
+
+**Canon**: `agent-workflow/skills/coding-standards/SKILL.md`.
+
+Resumen:
+- Estándares de código por stack (Java/Spring, Angular/TypeScript, Node). Principios: SOLID, fail-fast, naming descriptivo, DRY contra `shared/`/`common/`.
+- Seguridad: sin secrets en código, sin logear datos sensibles, SQL parametrizado, MCP `<mcp-cert>`/`<mcp-prod>` READONLY.
+- FE-BE R1-R6: Sparse DTO unificado, PATCH semantics para edit, FE envía sólo cambios, sin fallbacks ocultos, Bean Validation con groups, DB stub-first.
+
+Reglas operativas:
+- Java/Spring: Constructor Injection, `@Transactional(readOnly=true)` por default, records + Jakarta Validation.
+- Angular: Constructor injection, NgModules, async pipe, sin `any`.
+- HTTP: prohibido `catchError(() => of([]))` — propagar el error.
+- Logging por nivel: ERROR (rompe flujo) / WARN (degrada) / INFO (transacción) / DEBUG (interno).
+- Ramas: `feature/` `fix/` `hotfix/` + kebab.
+
+**Cómo aplicar fuera de sesión**:
+- Aplican igual a cualquier edit de código qtc-* o consumer. Sin sesión, la composición desde `dev-workflow`/`implement` no ocurre — depende de que el harness host enganche `coding-standards` por description engaging o de que `agent-workflow:rules` se invoque.
+
+---
+
+### 6. Graduación 6-kinds — `agent-workflow:graduacion-routing`
+
+**Canon**: `agent-workflow/skills/session/references/graduacion-routing.md` (DEC-002, DEC-003).
+
+Resumen:
+- Sólo **6 kinds** graduan al cerrar sesión: `decision`, `manual`, `script`, `especificacion`, `conclusion`, `release`. El resto vive en la sesión.
+- Routing absoluto sin prompt por sesión:
+  - `workspace_mode=hub` → `<hub>/docs/<categoria>/`.
+  - `workspace_mode=project` → `<project>/docs/<categoria>/`.
+- Comando CLI: `agent-workflow graduate --kind <K> --session <CODE> --slug <kebab>`. `script` y `release` se manejan vía `/agent-workflow:release` exclusivamente.
+
+Reglas operativas:
+- `decision` → `docs/decisiones/NNN-<slug>.md`.
+- `manual` → `docs/manuales/NNN-<slug>.md`.
+- `especificacion` → `docs/especificaciones/NNN-<slug>/`.
+- `conclusion` → `docs/conclusiones/NNN-<slug>.md` (opt-in; default = no graduar).
+- `release` → `docs/release/NNN-informe-release.md` (vía `/agent-workflow:release`).
+- `script` → `docs/scripts/NNN-sessionXXX-<slug>/` (vía `/agent-workflow:release`).
+
+**Cómo aplicar fuera de sesión**:
+- El CLI **rechaza** la invocación sin `--session` y `--slug`. Un artefacto graduable producido fuera de sesión queda huérfano.
+- Workaround: crear sesión retroactiva o mover archivos manualmente — no documentado como flujo canónico.
+
+---
+
+### 7. Branch verification — `agent-workflow:branch-verification`
+
+**Canon**: `agent-workflow/skills/session/references/branch-verification.md`.
+
+Resumen:
+- Gate de avance del lifecycle: en crear sesión, retomar y entrada a execution se valida `current_branch == expected_work_branch` por fuente.
+- 3 casos:
+  - **Caso A** (`match=false`, `dirty=false`): `AskUserQuestion` → checkout esperado / mantener current y actualizar sesión / cancelar.
+  - **Caso B** (`match=false`, `dirty=true`): pausar y esperar resolución manual. Listar archivos modificados. **NO ofrecer checkout**.
+  - **Caso C** (analyze session editando código): preguntar nombre de rama, ofrecer `checkout` o `checkout -b` desde `main_branch`, registrar vía `project-md-upsert --update-phase`.
+- Hard gate cross-fuente: si `cross_source_consistent=false` (hub mode con divergencia), bloquear hasta alinear o declarar divergencia explícita.
+
+Reglas operativas:
+- Hook PreToolUse `agent-workflow hook branch-check` registrado en `hooks/hooks.json` con matcher `Edit|Write|MultiEdit|NotebookEdit`.
+- Sin sesión activa pero con `working_branches` en AW-PROJECT.Status: el hook resuelve `expected_work_branch` desde working_branches y sí dispara.
+- Sin sesión y sin `working_branches`: degrada a no-op silencioso.
+
+**Cómo aplicar fuera de sesión**:
+- En hubs con `working_branches` declaradas (como `agent-workflow-last`): hook activo, gate funciona.
+- En workspaces project sin sesión: gate inactivo. El AI debe verificar rama manualmente con `agent-workflow sources` si el contexto lo amerita.
+- Nunca ejecutar `git stash`, `git reset --hard`, `git restore .`, `git clean` sin confirmación explícita del usuario para esa fuente.
+
+---
+
+## Relación con AGENTS.md/CLAUDE.md por fuente
+
+Esta skill es la capa **active (on-demand)** del modelo de aplicación de reglas. Coexiste con la capa **passive (system-prompt)**:
+
+| Capa | Mecanismo | Cuándo carga | Cubre |
+|---|---|---|---|
+| Passive | `AGENTS.md`/`CLAUDE.md` por fuente + bloque transversal en hub | system-prompt automático en cada conversación sobre el repo | "el AI ve los anchors siempre que abre el repo" |
+| Active | `Skill(agent-workflow:rules)` invokable + description engaging | on-demand vía invocación explícita o NL match | "el AI carga los anchors completos cuando los necesita" |
+
+Las 2 capas no se solapan:
+- El AGENTS.md tiene punteros breves a anchors (1 línea por anchor) — load automático.
+- `agent-workflow:rules` expande los anchors completos (5-7 líneas + reglas operativas + cómo aplicar fuera de sesión) — carga on-demand.
+
+Si el AGENTS.md ya está cargado, `agent-workflow:rules` actúa como **refresh verbose** del contrato.
+
+## Cómo aplicar fuera de sesión (resumen cross-anchor)
+
+Tabla rápida para situaciones comunes sin sesión activa:
+
+| Situación | Regla aplicable | Acción |
+|---|---|---|
+| Pedís un commit ad-hoc | commits-policy regla 2 + regla 3 universal | M1 propose-then-execute con `agent-workflow sources` (sin `--session`). Mensaje sugerido sin tag `session<NNN>`, sin co-author, sin `--no-verify`. |
+| Pedís commit con mensaje literal en la solicitud | commits-policy regla 5 | Bypass de M1; el AI ejecuta `git commit -m "<literal>"` directo (validando rama, hooks, Regla 2). |
+| Editás código de fuente qtc-* | coding-standards + branch-verification | Verificar rama (`agent-workflow sources`); aplicar reglas de stack. |
+| Ejecutás query MCP cert/prod | mcp-readonly | Sólo SELECT/EXPLAIN. Mutación → script en `docs/scripts/`. |
+| Escribís prosa qtc-* (PR description, README) | redaccion-simple | 6 reglas (frases cortas, listas, sin jerga). |
+| Producís artefacto curable (decisión, manual) | graduacion-routing | Crear sesión retroactiva o documentar como fuera de scope graduable. |
+| Host en plan mode | sandbox-readonly | Describir en plan file, no ejecutar mutaciones. |
+
+## Sandbox read-only
+
+Canon universal en `../session/references/sandbox-readonly-rules.md`. Esta skill es read-only por diseño — carga reglas, no ejecuta ni edita nada.
+
+En plan mode: describir en el plan file qué anchors se cargarían y para qué se invoca la skill (situación concreta). NO ejecuta `Write`, `Edit`, `MultiEdit`, `Bash` con efectos colaterales ni queries MCP mutantes.
+
+Compatible con plan mode sin restricciones adicionales.
+
+## Referencias
+
+- **session SKILL** (`../session/SKILL.md`) — lifecycle universal donde estas reglas se invocan por composición durante las 4 fases.
+- **shared-contract** (`../../docs/shared-contract.md`) — contrato cross-plugin de la familia qtc-*.
+- **Recomendación de uso conjunto con AGENTS.md/CLAUDE.md**:
+  - El AGENTS.md/CLAUDE.md por fuente (o el bloque transversal en hub) lista 1 línea por anchor con su path canon. Sirve como "tabla de contenidos" siempre cargada.
+  - Esta skill `agent-workflow:rules` carga los 7 anchors expandidos. Sirve cuando se necesita refrescar el contrato o cuando el AGENTS.md no está disponible.
+- **Origen**: session051-analyze-reglas-transversales-fuera-sesion → CONCLUSIONS C7/R7/QW6. Graduado a `docs/conclusiones/006-reglas-transversales-fuera-sesion.md`.