@tacuchi/agent-workflow-cli 6.1.0 → 7.0.0

package/skills/agent-workflow/standards/sql-script-organizer/references/scripts-sql-format.md

@@ -0,0 +1,140 @@
+# SCRIPTS.sql — spec canónica del archivo
+
+Spec del archivo único `SCRIPTS.sql` que vive en `.workflow/sessions/<folder>/` desde `sql-script-organizer` v1.0.0 (decisión F-D + G1 de session062).
+
+## Path canónico
+
+```
+.workflow/sessions/sessionXXX-<flow>-<slug>/SCRIPTS.sql
+```
+
+- Filename: **SCRIPTS.sql** en mayúsculas (uppercase EN, igual que CHECKPOINT.md, TASKS.md, etc.).
+- Encoding: UTF-8 sin BOM.
+- Line endings: LF.
+
+## Estructura del archivo
+
+```sql
+-- ============================================================================
+-- SCRIPTS.sql — sessionXXX-<flow>-<slug>
+-- ============================================================================
+-- Consolida todas las sentencias SQL aplicadas durante esta sesión.
+-- Markers @category y @stmt los lee /agent-workflow:export-scripts para separar el bundle.
+-- ----------------------------------------------------------------------------
+
+BEGIN;
+
+-- @category: 01-ddl-tablas
+-- @stmt: 001-crear-tabla-usuarios
+CREATE TABLE IF NOT EXISTS esq_credito.tb_usuarios (
+  id          BIGSERIAL PRIMARY KEY,
+  cod_usuario VARCHAR(20) NOT NULL UNIQUE,
+  estado      CHAR(1) NOT NULL DEFAULT 'A'
+);
+
+-- @category: 02-ddl-funciones
+-- @stmt: 002-fn-obtener-usuario
+CREATE OR REPLACE FUNCTION esq_credito.fn_obtener_usuario(p_cod VARCHAR)
+RETURNS TABLE(...)
+LANGUAGE plpgsql AS $$
+BEGIN
+  ...
+END;
+$$;
+
+-- @category: 04-inserts
+-- @stmt: 003-insert-usuarios-seed
+INSERT INTO esq_credito.tb_usuarios (cod_usuario, estado)
+VALUES ('admin', 'A'), ('soporte', 'A')
+ON CONFLICT (cod_usuario) DO NOTHING;
+
+COMMIT;
+```
+
+## Markers
+
+### `@category` — obligatorio
+
+Clasifica la sentencia para la separación post-hoc en el bundle export-scripts:
+
+| Marker | Patrones de detección |
+|---|---|
+| `01-ddl-tablas` | `CREATE TABLE`, `DROP TABLE`, `ALTER TABLE`, `CREATE INDEX`, `CREATE SEQUENCE` |
+| `02-ddl-funciones` | `CREATE [OR REPLACE] FUNCTION`, `CREATE [OR REPLACE] PROCEDURE`, `DROP FUNCTION`, `DROP PROCEDURE` |
+| `03-migracion` | `UPDATE`, `INSERT ... SELECT ...`, `DELETE` sobre datos existentes |
+| `04-inserts` | `INSERT INTO ... VALUES`, seeds de catálogos, datos de configuración inicial |
+
+Valor exacto, lowercase. Una categoría por marker (no listas).
+
+### `@stmt` — obligatorio
+
+Slug determinístico para que `export-scripts` derive el filename del archivo separado:
+
+- Formato: `NNN-verbo-objetivo` (3 dígitos + kebab-case, ≤5 palabras útiles).
+- Único dentro del SCRIPTS.sql.
+- Orden cronológico recomendado pero NO requerido (export-scripts ordena por categoría al separar).
+- Ejemplo: `001-crear-tabla-usuarios`, `015-poblar-catalogo-roles`.
+
+### `@objeto` y `@alcance` — opcionales
+
+Si la sentencia merece doc:
+
+```sql
+-- @category: 01-ddl-tablas
+-- @stmt: 001-crear-tabla-usuarios
+-- @objeto: Tabla central de identidades. UNIQUE en cod_usuario.
+-- @alcance: solo esq_credito; trigger de auditoría en sesión separada.
+CREATE TABLE ...
+```
+
+`export-scripts` usa estos al generar el header canónico del archivo separado.
+
+## Reglas de idempotencia
+
+Cada sentencia debe ser idempotente:
+
+- **DDL**: `CREATE TABLE IF NOT EXISTS`, `DROP ... IF EXISTS`, `CREATE OR REPLACE`.
+- **Inserts**: `ON CONFLICT (...) DO NOTHING` o `ON CONFLICT DO UPDATE`.
+- **Migraciones de datos**: backup en `esq_audit.tb_bkp_<x>_sNNN` antes de UPDATE/DELETE masivo; ver `sql-rollback-generator` para política.
+- **Funciones**: `CREATE OR REPLACE FUNCTION` siempre.
+
+Re-ejecutar el archivo completo no debe fallar.
+
+## Transaccionalidad
+
+`BEGIN;` al inicio del archivo, `COMMIT;` al final. **Una sola transacción** global por sesión.
+
+Si una sentencia requiere transacción aparte (ej. `CREATE INDEX CONCURRENTLY`), comentar con `-- @transaction: none` y mover fuera del BEGIN/COMMIT global. Casos raros; documentar.
+
+## Concatenación con sessions previas
+
+`SCRIPTS.sql` representa **lo que esta sesión cambia**. NO incluye:
+- Scripts heredados de sesiones previas (esos ya viven en sus propios SCRIPTS.sql).
+- Scripts del baseline del workspace.
+
+`export-scripts` con `--sessions NNN,MMM` combina varios SCRIPTS.sql en el bundle final.
+
+## Edición durante la sesión
+
+Permitido:
+- Append de nuevas sentencias al final (antes del COMMIT).
+- Editar sentencias existentes para corregir (preservar `@stmt` del statement; el slug es estable).
+- Eliminar sentencias descartadas (no preservar history en backlog SQL; usar `BACKLOG.md` para anotar lo descartado).
+
+No permitido:
+- Reordenar sentencias por estética (orden = cronológico). Si el orden de ejecución importa, dejarlo al separador post-hoc.
+- Mezclar 2 sentencias en un solo bloque marker (un `@stmt` = una sentencia).
+
+## Verificación pre-cierre
+
+Antes de cerrar la sesión:
+1. `agent-workflow session-artifacts --code NNN` reporta `scripts_sql_present: true` (si esperabas SQL).
+2. El archivo abre con `BEGIN;` y cierra con `COMMIT;`.
+3. Cada sentencia tiene `@category` y `@stmt`.
+4. Re-ejecutar el archivo en cert no falla (manual; el AI nunca ejecuta).
+
+## Migración desde layout legacy
+
+Si la sesión tiene `scripts/01-ddl-tablas/*.sql` etc. (layout pre-v1.0.0), invocar `/agent-workflow:migrate --upgrade-topology`. El skill `migrate` lee los archivos en orden 01→04, concatena en SCRIPTS.sql con markers `@category` derivado de la carpeta y `@stmt` del filename original. Idempotente: si ya existe SCRIPTS.sql, no sobreescribe.
+
+Ver `agent-workflow/skills/migrate/SKILL.md` capability 11.

package/skills/agent-workflow/standards/testing-strategy/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: testing-strategy
+description: Skill de referencia para la estrategia de testing (selección de niveles unit/integración/e2e, comandos de ejecución por stack). Invocado internamente por el skill session durante la Fase 4 (validación). No se activa por lenguaje natural.
+version: 0.1.0
+---
+
+# Testing Strategy
+
+Gestión de niveles de prueba flexibles dentro de sesiones de desarrollo. El usuario elige el nivel en cualquier momento y puede cambiarlo durante la sesión. Los niveles se adaptan al stack detectado del proyecto.
+
+## Regla de ejecución
+
+Por defecto, no ejecutar pruebas automáticamente. Primero preguntar si:
+- el usuario quiere que el plugin las ejecute
+- el usuario las correrá manualmente
+- no hace falta correrlas en esta sesión
+
+(Salvo `Validation mode: auto` en `~/.workflow/user-config.md`.)
+
+## Niveles de prueba — Backend (Spring Boot / Java)
+
+### Nivel a) Unitarios
+- **Framework:** JUnit 5 + Mockito
+- **Alcance:** Lógica de negocio aislada (services, utils, mappers)
+- **Cuándo usarlo:** Fix rápido, cambio puntual, lógica sin dependencias externas
+- **Comando:** `./mvnw test -Dtest=ClaseTest` (Windows: `mvnw.cmd test`)
+
+### Nivel b) Unitarios + API
+- **Framework:** JUnit 5 + Mockito + MockMvc
+- **Alcance:** Nivel a) + Controllers (endpoints REST)
+- **Cuándo usarlo:** Endpoint nuevo o modificado
+- **Comando:** `./mvnw test`
+
+### Nivel c) Completo
+- **Framework:** JUnit 5 + Mockito + MockMvc + @SpringBootTest
+- **Alcance:** Nivel b) + Tests de integración con contexto Spring completo
+- **Cuándo usarlo:** Feature completa, flujo crítico, integración entre capas
+- **Comando:** `./mvnw verify`
+
+## Niveles de prueba — Frontend (Angular)
+
+### Nivel a) Unitarios
+- **Framework:** Jasmine + Karma (o Jest según config)
+- **Alcance:** Services, pipes, utils aislados
+- **Comando:** `ng test --watch=false`
+
+### Nivel b) Unitarios + Componentes
+- **Framework:** Jasmine + TestBed + ComponentFixture
+- **Alcance:** Nivel a) + componentes con template rendering
+- **Comando:** `ng test --watch=false`
+
+### Nivel c) Completo
+- **Framework:** Nivel b) + tests e2e (Cypress/Playwright si está configurado)
+- **Alcance:** Flujos completos de usuario
+- **Comando:** `npm run e2e` o según configuración del proyecto
+
+## Selección de nivel
+
+Preguntar al usuario solo cuando realmente se vaya a validar desde el plugin. Adaptar las opciones al stack:
+
+**Backend:**
+```
+¿Qué nivel de pruebas aplicamos?
+  a) Unitarios — JUnit 5 + Mockito (rápido)
+  b) Unitarios + API — + MockMvc controllers
+  c) Completo — + @SpringBootTest integración
+```
+
+**Frontend:**
+```
+¿Qué nivel de pruebas aplicamos?
+  a) Unitarios — Services y pipes aislados
+  b) Unitarios + Componentes — + TestBed rendering
+  c) Completo — + e2e si está configurado
+```
+
+El usuario puede cambiar de nivel en cualquier momento o decidir no ejecutar pruebas desde el plugin.
+
+## Convenciones de nomenclatura
+
+**Java:** Clase `[Objetivo]Test.java`, método `[metodo]_[escenario]_[resultado]`. Estructura Arrange-Act-Assert.
+**Angular:** Archivo `[nombre].spec.ts`, bloques `describe`/`it`. Usar TestBed para componentes.
+
+Para ejemplos completos de código, consultar `references/test-levels.md`.
+
+## Ejecución y registro
+
+1. Confirmar primero que el usuario quiere ejecución desde el plugin
+2. Ejecutar el comando según stack y nivel
+3. Registrar en `TEST_LOG.md` solo si el usuario pidió registro formal o la ejecución se hizo desde el plugin
+4. Si el usuario ya validó manualmente, no repetir por defecto; anotar una línea breve solo si aporta trazabilidad
+5. Si hay fallos y el usuario quiere continuar, corregir y re-ejecutar
+
+## Detección automática de comando
+
+1. `mvnw`/`mvnw.cmd` → `./mvnw test` (nunca `mvn` directo)
+2. `gradlew` → `./gradlew test`
+3. `angular.json` → `ng test --watch=false`
+4. `package.json` con script test → `npm test`
+5. Si el bloque `AW-PROJECT → Stack` declara un override de build o wrapper distinto, usarlo.
+
+## Sandbox read-only
+
+Canon universal en `../session/references/sandbox-readonly-rules.md`. Esta skill es read-only por diseño — selecciona niveles de test y resuelve comandos por stack, no ejecuta tests ni edita código fuente.
+
+En plan mode: describir en el plan file qué niveles aplicarían (unit / integración / e2e), el comando resuelto (`./mvnw test`, `ng test --watch=false`, `npm test`, etc.) y los refs de ejemplos por stack. NO ejecuta `Bash` con el test runner, NO escribe TEST_LOG.md ni código de tests por sí misma.
+
+Compatible con plan mode sin restricciones adicionales.
+
+## Recursos adicionales
+
+### Archivos de referencia
+- **`references/test-levels.md`** — Ejemplos completos de código por stack y nivel, patrones TestBuilder, resumen de comandos

package/skills/agent-workflow/standards/testing-strategy/references/test-levels.md

@@ -0,0 +1,255 @@
+# Niveles de test — Referencia completa
+
+## Backend (Spring Boot / Java)
+
+### Nivel a) Unitarios — Ejemplo completo
+
+```java
+@ExtendWith(MockitoExtension.class)
+class NotificacionServiceTest {
+
+    @Mock
+    private EmailProvider emailProvider;
+
+    @Mock
+    private NotificacionRepository repository;
+
+    private NotificacionService service;
+
+    @BeforeEach
+    void setUp() {
+        // Constructor Injection (mismo patrón que producción)
+        service = new NotificacionService(emailProvider, repository);
+    }
+
+    @Test
+    void enviar_conEmailValido_retornaExito() {
+        // Arrange — record como DTO
+        var request = new NotificacionRequest("user@example.com", "Aprobación", "aprobacion", Map.of());
+        when(emailProvider.send(any())).thenReturn(true);
+
+        // Act
+        var resultado = service.enviar(request);
+
+        // Assert
+        assertThat(resultado).isTrue();
+        verify(emailProvider).send(any());
+    }
+
+    @Test
+    void enviar_sinDestinatario_lanzaBadRequest() {
+        var request = new NotificacionRequest(null, "Asunto", "template", Map.of());
+
+        assertThatThrownBy(() -> service.enviar(request))
+            .isInstanceOf(BadRequestException.class)
+            .hasMessageContaining("destinatario");
+    }
+
+    @Test
+    void enviar_proveedorFalla_registraError() {
+        var request = new NotificacionRequest("user@example.com", "Asunto", "template", Map.of());
+        when(emailProvider.send(any())).thenThrow(new RuntimeException("SMTP error"));
+
+        var resultado = service.enviar(request);
+
+        assertThat(resultado).isFalse();
+        verify(repository).guardarLog(any());
+    }
+}
+```
+
+Ejecutar con: `./mvnw test -Dtest=NotificacionServiceTest` (Windows: `mvnw.cmd test`)
+
+### Nivel b) Unitarios + API — Ejemplo MockMvc
+
+```java
+@WebMvcTest(NotificacionController.class)
+class NotificacionControllerTest {
+
+    @Autowired
+    private MockMvc mockMvc;
+
+    @MockBean
+    private NotificacionService service;
+
+    @Test
+    void enviar_conDatosValidos_retorna200() throws Exception {
+        when(service.enviar(any())).thenReturn(true);
+
+        // Request body usa record NotificacionRequest
+        mockMvc.perform(post("/api/v1/notificaciones/enviar")
+                .contentType(MediaType.APPLICATION_JSON)
+                .content("{\"destinatario\":\"user@example.com\",\"asunto\":\"Test\",\"templateId\":\"aprobacion\"}"))
+            .andExpect(status().isOk());
+    }
+
+    @Test
+    void enviar_sinBody_retorna400() throws Exception {
+        mockMvc.perform(post("/api/v1/notificaciones/enviar")
+                .contentType(MediaType.APPLICATION_JSON))
+            .andExpect(status().isBadRequest());
+    }
+}
+```
+
+Ejecutar con: `./mvnw test`
+
+### Nivel c) Completo — Ejemplo @SpringBootTest
+
+```java
+@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
+@AutoConfigureMockMvc
+@Transactional
+class NotificacionIntegrationTest {
+
+    @Autowired
+    private MockMvc mockMvc;
+
+    @Autowired
+    private NotificacionRepository repository;
+
+    @Test
+    void flujoCompleto_enviarYRegistrar_persisteLog() throws Exception {
+        mockMvc.perform(post("/api/v1/notificaciones/enviar")
+                .contentType(MediaType.APPLICATION_JSON)
+                .content("{\"destinatario\":\"user@example.com\",\"asunto\":\"Test\"}"))
+            .andExpect(status().isOk());
+
+        var logs = repository.findByDestinatario("user@example.com");
+        assertThat(logs).isNotEmpty();
+    }
+}
+```
+
+Ejecutar con: `./mvnw verify`
+
+## Frontend (Angular)
+
+### Nivel a) Unitarios — Service aislado
+
+```typescript
+describe('AuthService', () => {
+  let service: AuthService;
+  let httpMock: HttpTestingController;
+
+  beforeEach(() => {
+    TestBed.configureTestingModule({
+      imports: [HttpClientTestingModule],
+      providers: [AuthService]
+    });
+    service = TestBed.inject(AuthService);
+    httpMock = TestBed.inject(HttpTestingController);
+  });
+
+  afterEach(() => httpMock.verify());
+
+  it('should return token on login', () => {
+    service.login('admin', 'pass').subscribe(res => {
+      expect(res.token).toBeTruthy();
+    });
+
+    const req = httpMock.expectOne('/api/auth/login');
+    req.flush({ token: 'abc123' });
+  });
+
+  it('should handle login error', () => {
+    service.login('bad', 'creds').subscribe({
+      error: err => expect(err.status).toBe(401)
+    });
+
+    const req = httpMock.expectOne('/api/auth/login');
+    req.flush('Unauthorized', { status: 401, statusText: 'Unauthorized' });
+  });
+});
+```
+
+Ejecutar con: `ng test --watch=false`
+
+### Nivel b) Unitarios + Componentes — TestBed
+
+```typescript
+describe('FiltrosComponent', () => {
+  let component: FiltrosComponent;
+  let fixture: ComponentFixture<FiltrosComponent>;
+
+  beforeEach(async () => {
+    await TestBed.configureTestingModule({
+      imports: [FiltrosComponent, NoopAnimationsModule]
+    }).compileComponents();
+    fixture = TestBed.createComponent(FiltrosComponent);
+    component = fixture.componentInstance;
+    fixture.detectChanges();
+  });
+
+  it('should create', () => {
+    expect(component).toBeTruthy();
+  });
+
+  it('should render date inputs', () => {
+    const compiled = fixture.nativeElement;
+    expect(compiled.querySelector('input[type="date"]')).toBeTruthy();
+  });
+
+  it('should emit on filter apply', () => {
+    spyOn(component.filtroChanged, 'emit');
+    component.filtroForm.patchValue({ estado: 'ACTIVO' });
+    component.aplicarFiltro();
+    expect(component.filtroChanged.emit).toHaveBeenCalledWith(
+      jasmine.objectContaining({ estado: 'ACTIVO' })
+    );
+  });
+});
+```
+
+## TestBuilder — Patrón (Java)
+
+```java
+public class NotificacionTestBuilder {
+    private Long id = 1L;
+    private String destinatario = "test@example.com";
+    private String asunto = "Test";
+    private String estado = "PENDIENTE";
+    private LocalDateTime fechaCreacion = LocalDateTime.now();
+
+    public static NotificacionTestBuilder builder() {
+        return new NotificacionTestBuilder();
+    }
+
+    public NotificacionTestBuilder destinatario(String val) {
+        this.destinatario = val;
+        return this;
+    }
+
+    public NotificacionTestBuilder estado(String val) {
+        this.estado = val;
+        return this;
+    }
+
+    public Notificacion build() {
+        var entity = new Notificacion();
+        entity.setId(id);
+        entity.setDestinatario(destinatario);
+        entity.setAsunto(asunto);
+        entity.setEstado(estado);
+        entity.setFechaCreacion(fechaCreacion);
+        return entity;
+    }
+}
+```
+
+## Resumen de comandos por stack
+
+### Spring Boot (Maven wrapper)
+- Nivel a: `./mvnw test -Dtest=ClaseTest`
+- Nivel b: `./mvnw test`
+- Nivel c: `./mvnw verify`
+- Windows: usar `mvnw.cmd` en lugar de `./mvnw`
+
+### Angular
+- Nivel a/b: `ng test --watch=false`
+- Nivel c: `npm run e2e` (si configurado)
+
+### Gradle
+- Nivel a: `./gradlew test --tests ClaseTest`
+- Nivel b: `./gradlew test`
+- Nivel c: `./gradlew integrationTest` (o `check`)

package/skills/agent-workflow/workflows/README.md

@@ -0,0 +1,12 @@
+# workflows/
+
+Flows del lifecycle: cómo se mueve una sesión por sus fases.
+
+Contenido esperado (T2 PR2):
+
+- `dev-workflow.md` — planning → execution → validation → closure; M1 ask antes de commit; gates por fase.
+- `design-workflow.md` — discovery → design → spec → closure; produce DELIVERY.md graduable.
+- `analyze-workflow.md` — discovery → evidence → findings → conclusions; produce CONCLUSIONS.md.
+- `core-workflow.md` — sub-flow agnóstico embebido en los 3 anteriores (artefactos comunes).
+
+Cada workflow declara: phases, artefactos requeridos, prompts (M1/M10/S2/S3/S6/S7) y transitions válidas.

package/skills/agent-workflow/workflows/analyze-workflow/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: analyze-workflow
+description: Workflow especializado analyze (especialidad investigación read-only), antes en qtc-analyze. Consumido por /agent-workflow:session cuando flow=analyze para orquestar el lifecycle universal con composición analyze-específica según modalidad.
+version: 2.1.0
+flow: analyze
+workflow_schema: 1.0
+---
+
+# Analyze Workflow
+
+Workflow declarativo del flow=analyze. Define dos modos:
+
+- **Standalone** (`/agent-workflow:use`): investigación puntual sin sesión.
+- **Orchestrated** (consumido por `/agent-workflow:session` con flow=analyze): orquesta investigación + síntesis + recomendación según modalidad.
+
+## Brief
+
+**flow=analyze** es la especialidad de investigación **read-only** del plugin qtc. No edita código ni muta BD. Produce `CONCLUSIONS.md` consumible por flow=dev vía handoff.
+
+**Política de commits**: ver `agent-workflow:commits-policy` (canónico). El flow=analyze es read-only por construcción; cuando el usuario solicita un commit (típicamente al cierre, pero puede ser en otra fase si edita artefactos), aplica Regla 3 propose-then-execute universal con M1.
+
+**Política sin fallback al CLI (transversal al flow=analyze)**: si `agent-workflow <subcmd>` 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.
+
+### Rama base (canon v3.5+)
+
+Las sesiones `flow=analyze` resuelven la rama esperada de cada fuente como `main_branch` (default `certificacion`) cuando NO se declaran branches en la sesión. Razón: el análisis necesita reflejar producción, no una rama de feature.
+
+- Si el repo de la fuente está en otra rama, el lifecycle dispara el flujo proactivo de verificación (Caso A o B según `dirty`) y bloquea avance hasta resolver.
+- Si durante la investigación el usuario decide **editar** código, se aplica **Caso C** (`agent-workflow/skills/session/references/branch-verification.md`): preguntar nombre de la rama de trabajo, ofrecer `checkout` (existe) o `checkout -b` desde `main_branch` (no existe), y registrar en AW-PROJECT.Status. El skill `analyze-workflow` no edita por sí mismo; la decisión de editar implica un handoff o cambio de flow.
+- Override explícito al crear la sesión: `--branches alias:rama` declarado gana sobre el default `main_branch`. Útil cuando se quiere analizar contra una rama puntual (ej. una feature en validación).
+
+Skills disponibles:
+- **analyze-synthesize**: estructura información en plan/hallazgos (exportada cross-flow, **clave** invocada por agent-workflow:session en planning).
+- **analyze-investigate**: recolección de evidencia divergente con cost guard (exportada).
+- **analyze-conclude**: cierre del análisis con `CONCLUSIONS.md` modulado por `## Modality` (technical/incident/data). Una sola skill, una sola estructura.
+
+Diferencia clave de **modalidad** (embebida como `## Modality` en CONCLUSIONS.md):
+- `technical` (legacy: `tecnica`): pregunta arquitectónica/diseño → cuerpo modulado como propuesta (opciones consideradas + decisión recomendada).
+- `data` (legacy: `datos`): análisis cuantitativo → cuerpo modulado como informe (hallazgos numéricos + interpretación + acciones sugeridas).
+- `incident` (legacy: `incidente`): post-mortem retrospectivo → cuerpo modulado con timeline + causa raíz + impacto + acciones preventivas.
+
+CONCLUSIONS.md vive en la sesión por default. Gradúa opt-in con `kind=conclusion` a `docs/conclusiones/`.
+
+## Standalone (use)
+
+Cuando el usuario invoca `/agent-workflow:use`:
+
+1. **Presentarse**: mostrar este Brief + warning read-only.
+2. **Preguntar modalidad** vía `AskUserQuestion`. Spec literal (header `modality`, 3 opciones technical/data/incident con descripción) → `agent-workflow:prompts-catalog#M5`. La modalidad determina la modulación del cuerpo del CONCLUSIONS.md (estructura única, contenido modulado):
+   - **Technical** → cuerpo modulado como propuesta.
+   - **Data** → cuerpo modulado como informe de análisis.
+   - **Incident** → cuerpo modulado como post-mortem.
+3. **Preguntar scope**:
+   - "¿Sobre qué código/sistema/datos investigar?"
+   - "¿Hay un incidente concreto a clasificar?"
+   - "¿Hay datos previos o BD a consultar?"
+4. **Detectar contexto**:
+   - AW-PROJECT con fuentes (read-only sobre los repos declarados).
+   - MCP servers `<mcp-cert>`/`<mcp-prod>` disponibles para consultas BD (read-only).
+   - Cost guard activo para consultas pesadas.
+5. **Path del artefacto**: `.workflow/sessions/<folder>/CONCLUSIONS.md`. Si el usuario decide graduar al cierre, destino = `docs/conclusiones/NNN-<slug>.md` (kind=`conclusion`, opt-in).
+6. **Cargar skill `analyze-conclude`** independientemente de la modalidad (el skill es único y modula por contenido).
+
+**Reglas standalone**:
+- **Read-only estricto**: no editar código del repo, no mutar BD, no escribir scripts SQL.
+- **NO crear sesión** ni escribir en `.workflow/sessions/`.
+- **NO requiere AW-PROJECT** (si existe, enriquece con fuentes para investigar).
+- **Cost guard**: si el usuario quiere queries pesadas o investigación cross-repo extensa, advertir antes de proceder.
+- **Sugerir sesión** si la investigación es multi-fase (investigate + synthesize + recomendar) — más coherente como sesión.
+
+## Session integration
+
+Cuando agent-workflow:session consume este workflow durante `/agent-workflow:session create` con flow=analyze:
+
+### Args al crear sesión
+
+- modality: technical|data|incident (obligatorio; determina graduación + template). Legacy ES `tecnica|datos|incidente` se acepta y normaliza.
+
+### Artefactos por fase
+
+- planning: OBJECTIVE.md, TASKS.md
+- execution: EVIDENCE.md, FINDINGS.md, queries/, CONCLUSIONS.md
+- validation: review de CONCLUSIONS
+- closure: opt-in graduación de CONCLUSIONS.md a `docs/conclusiones/` (default: queda en sesión)
+
+### Skills por fase
+
+- planning: analyze-synthesize (estructurar plan)
+- execution: analyze-investigate (recolectar evidencia), analyze-synthesize (sintetizar findings)
+- closure: analyze-conclude (produce CONCLUSIONS.md modulado por modalidad)
+
+### Refs HISTORY
+
+- conclusion: docs/conclusiones/{val}.md (cuando se gradúa opt-in)
+
+### Conteos resume
+
+- evidence: EVIDENCE.md presente
+- findings: FINDINGS.md presente
+- conclusions: CONCLUSIONS.md presente
+- queries: queries/*.sql count
+
+## Sandbox read-only
+
+Standalone: en plan mode describir modalidad, scope, paths sugeridos. No ejecutar queries ni leer BD.
+
+Orchestrated: ver `agent-workflow:session` plan mode rules.