refacil-sdd-ai 4.2.4 → 4.4.0

package/skills/reply/SKILL.md

@@ -1,44 +1,44 @@
----
-name: refacil:reply
-description: Responder la última pregunta dirigida a esta sesión en el bus. El broker autocompleta el correlationId.
-user-invocable: true
----
-
-# refacil:reply — Responder una pregunta del bus
-
-Envía una respuesta a la última pregunta dirigida a esta sesión. **$ARGUMENTS** = texto de la respuesta.
-
-## Instrucciones
-
-### Paso 1: Ejecutar reply
-
-Ejecuta vía `Bash`:
-
-```bash
-refacil-sdd-ai bus reply --text "<respuesta>"
-```
-
-El broker:
-- Busca automáticamente el último `ask` dirigido a esta sesión en la sala
-- Usa su `correlationId` para que el que preguntó (si está en `ask --wait`) reciba la respuesta directo
-- Broadcast a toda la sala como mensaje `kind=reply`
-
-### Paso 2: Confirmar
-
-Reporta al usuario que la respuesta se envió.
-
-## Cuándo usar `reply` vs `say`
-
-- **`reply`**: siempre que estés respondiendo algo que te preguntaron. Esto permite que el otro lado en `ask --wait` desbloquee automáticamente.
-- **`say`**: anuncio general sin relación con una pregunta previa.
-
-## Reglas
-
-- Si acabas de **implementar** un cambio pedido por otro agente y este `reply` es el **cierre** (hecho / PR / bloqueo), incluye ese resumen en el texto; es el canal por defecto para contestar a quien hizo el `ask` original (mismo hilo).
-- Entrecomilla correctamente el texto.
-- Responde solo desde tu conocimiento de ESTE repo. Si la pregunta cae fuera de tu scope, dilo explícitamente: `"fuera de mi alcance, esto lo sabe el repo X"`.
-- Si no hay pregunta pendiente dirigida a ti y no quieres engancharla, usa `/refacil:say` en su lugar.
-- Si te hicieron múltiples preguntas y quieres responder una específica más vieja, pasa `--correlation <id>` explícito:
-  ```bash
-  refacil-sdd-ai bus reply --text "..." --correlation <id>
-  ```
+---
+name: refacil:reply
+description: Reply to the last question directed to this session on the bus. The broker autocompletes the correlationId.
+user-invocable: true
+---
+
+# refacil:reply — Reply to a bus question
+
+Sends a response to the last question directed to this session. **$ARGUMENTS** = response text.
+
+## Instructions
+
+### Step 1: Execute reply
+
+Run via `Bash`:
+
+```bash
+refacil-sdd-ai bus reply --text "<response>"
+```
+
+The broker:
+- Automatically finds the last `ask` directed to this session in the room
+- Uses its `correlationId` so the asker (if in `ask --wait`) receives the response directly
+- Broadcasts to the entire room as a `kind=reply` message
+
+### Step 2: Confirm
+
+Report to the user that the response was sent.
+
+## When to use `reply` vs `say`
+
+- **`reply`**: always when you are responding to something you were asked. This allows the other side in `ask --wait` to unblock automatically.
+- **`say`**: general announcement unrelated to a previous question.
+
+## Rules
+
+- If you just **implemented** a change requested by another agent and this `reply` is the **close** (done / PR / blocked), include that summary in the text; it is the default channel to respond to whoever made the original `ask` (same thread).
+- Correctly quote the text.
+- Respond only from your knowledge of THIS repo. If the question falls outside your scope, say it explicitly: `"out of my scope, repo X knows about this"`.
+- If there is no pending question directed to you and you do not want to link it, use `/refacil:say` instead.
+- If you were asked multiple questions and want to respond to a specific older one, pass `--correlation <id>` explicitly:
+  ```bash
+  refacil-sdd-ai bus reply --text "..." --correlation <id>
+  ```

package/skills/review/SKILL.md

@@ -1,126 +1,163 @@
----
-name: refacil:review
-description: Review de codigo con el checklist de calidad del equipo — construye un briefing con archivos cambiados y tipo de proyecto, delega al sub-agente refacil-auditor y procesa el veredicto
-user-invocable: true
----
-
-# refacil:review — Entrypoint del Review
-
-Este skill es un **wrapper delgado** que delega el review pesado al sub-agente `refacil-auditor`. Antes de delegar, construye un **briefing estructurado** con los archivos cambiados y el tipo de proyecto ya detectados — el sub-agente arranca evaluando, no descubriendo.
-
-**Prerequisitos**: perfil `agents` de `refacil-prereqs/SKILL.md` + modo de salida de `METHODOLOGY-CONTRACT.md`.
-
-## Flujo
-
-### Paso 0: Resolver alcance
-
-- Determina el alcance del review ANTES de invocar al sub-agente. Prioriza este orden:
-  1) Argumento del usuario (`$ARGUMENTS`)
-  2) Cambio activo en `openspec/changes/`
-  3) Cambios no commiteados (`git diff`)
-- Si hay multiples cambios activos en `openspec/changes/` y no hay `$ARGUMENTS`, **detente** y pide al usuario seleccionar explicitamente cual cambio revisar. **No invoques al sub-agente con scope ambiguo.**
-
-**Review ya aprobado**: Si el cambio objetivo ya tiene `.review-passed`, verifica si hay cambios posteriores al review (existencia del marcador: **`METHODOLOGY-CONTRACT.md` §8**):
-1. Lee la `date` del `.review-passed`.
-2. Compara con `git log --since="[date]" --oneline` y `git status --porcelain`.
-3. **Si hay cambios nuevos**: elimina el `.review-passed` anterior y continua (construye briefing e invoca al sub-agente).
-4. **Si NO hay cambios nuevos**: informa al usuario y termina sin invocar al sub-agente:
-   ```
-   El cambio [nombre] ya tiene review aprobado ([verdict] — [date]) y no hay cambios posteriores.
-   ```
-
-### Paso 0.5: Construir briefing para el sub-agente (reduce tool calls del auditor)
-
-Antes de invocar al sub-agente, extrae el contexto que de otro modo el auditor calcularía por su cuenta:
-
-1. **Archivos cambiados** — ejecuta `git diff --name-only HEAD` y `git status --porcelain`. La union es el scope bloqueante. (Si ya lo corriste en Paso 0 para verificar cambios post-review, reutiliza ese resultado.)
-
-2. **Tipo de proyecto** — lee `package.json` (si existe) e inspecciona las dependencias:
-   - Indicadores backend: `@nestjs/*`, `express`, `fastify`, `koa`, `typeorm`, `prisma`, `pg`, `mongoose`, `bullmq`, `amqplib`
-   - Indicadores frontend: `react`, `vue`, `angular`, `next`, `nuxt`, `svelte`, `vite`, `@tanstack/*`
-   - Si ambos → `fullstack`; si solo backend → `backend`; si solo frontend → `frontend`; si no hay `package.json` o ninguno aplica → lee las primeras 20 lineas de `AGENTS.md` para inferir.
-
-3. **Objetivo del cambio** (solo si hay cambio activo en `openspec/changes/`) — lee la primera seccion de `proposal.md`. Extrae el objetivo en 1-2 oraciones. Si el scope es `git-diff` sin cambio activo → `null`.
-
-Construye el bloque BRIEFING:
-
-```
-BRIEFING:
-scope: <changeName | "git-diff">
-changedFiles: [ruta/archivo-1.ts, ruta/archivo-2.ts, ...]
-projectType: backend | frontend | fullstack | library
-changeObjective: <objetivo en 1-2 oraciones, o null>
-mode: conciso | detailed
-```
-
-### Paso 1: Delegar al sub-agente refacil-auditor
-
-Invoca al sub-agente `refacil-auditor` pasandole el BRIEFING del paso anterior.
-
-El sub-agente:
-- Usa `changedFiles` del briefing como scope bloqueante (sin re-correr git diff).
-- Usa `projectType` para cargar directamente los checklists correctos (sin detection phase).
-- Usa `changeObjective` como contexto de intencion (sin releer proposal.md).
-- Lee los checklists y los archivos del scope bloqueante.
-- Evalua cada item con PASS/FAIL/N/A + severidad en cada FAIL.
-- Retorna UN solo mensaje con el reporte + bloque JSON fenced como ` ```refacil-review-result `.
-
-### Paso 2: Procesar el reporte del sub-agente
-
-Muestra al usuario el **reporte conciso** (todo lo anterior al bloque `refacil-review-result`). No muestres el bloque JSON — es metadata interna.
-
-**Si el sub-agente retorno `SCOPE_ERROR: <razon>`**: propaga el error al usuario y pide clarificacion. No escribas marker.
-
-### Paso 3: Crear marcador `.review-passed` (si aplica)
-
-Parsea el bloque ` ```refacil-review-result ` del sub-agente. Si `verdict` es **APROBADO** o **APROBADO CON OBSERVACIONES** y `changeName` no es null:
-
-**Ruta:** `openspec/changes/<changeName>/.review-passed`
-
-**Contenido (el JSON parseado del bloque, verbatim):**
-```json
-{
-  "verdict": "APROBADO|APROBADO CON OBSERVACIONES",
-  "date": "<ISO>",
-  "changeName": "<nombre-cambio>",
-  "summary": "<resumen 1 linea>",
-  "failCount": <int — solo FAILs en codigo nuevo>,
-  "preexistingCount": <int — FAILs preexistentes, no bloqueantes>,
-  "blockers": false
-}
-```
-
-**No crees el marker si:**
-- `verdict` es `REQUIERE CORRECCIONES`.
-- `changeName` es null.
-- El sub-agente retorno `SCOPE_ERROR`.
-
-### Paso 4: Recomendar siguiente paso
-
-Segun el `verdict` parseado, agrega al final de tu respuesta:
-
-**Si APROBADO o APROBADO CON OBSERVACIONES:**
-```
-El siguiente paso es archivar el cambio.
-Quieres que continue con /refacil:archive?
-```
-
-**Si REQUIERE CORRECCIONES:**
-```
-Una vez aplicadas las correcciones, el siguiente paso es re-verificar la implementacion.
-Quieres que continue con /refacil:verify?
-```
-
-## Reglas
-
-- **Siempre construye el briefing (Paso 0.5) antes de delegar** — es la pieza clave que reduce el costo del sub-agente.
-- **Siempre delega al sub-agente**. No repliques la logica de checklists ni de evaluacion aqui.
-- **El marker lo crea este skill, no el sub-agente**.
-- **No muestres el bloque JSON al usuario**.
-- Si el sub-agente retorno algo fuera de formato (sin bloque JSON parseable y no es `SCOPE_ERROR`), informa al usuario: "El reviewer retorno un reporte no estructurado — no se creo marker. Revisa el reporte manualmente."
-- **Continuidad del flujo**: si el usuario confirma afirmativamente ("si", "ok", "dale", "continua", etc.) la pregunta de continuidad, invocar inmediatamente el **Skill tool** correspondiente: `skill: "refacil:archive"` si el veredicto es APROBADO/APROBADO CON OBSERVACIONES, o `skill: "refacil:verify"` si es REQUIERE CORRECCIONES. (Ver `METHODOLOGY-CONTRACT.md §5`.)
-
-## Ver tambien
-
-- Sub-agente: `.claude/agents/refacil-auditor.md` (fuente: `refacil-sdd-ai/agents/auditor.md`)
-- Checklists: `checklist.md`, `checklist-back.md`, `checklist-front.md` en este mismo directorio.
+---
+name: refacil:review
+description: Code review with the team quality checklist — builds a briefing with changed files and project type, delegates to the refacil-auditor sub-agent, and processes the verdict
+user-invocable: true
+---
+
+# refacil:review — Review Entrypoint
+
+This skill is a **thin wrapper** that delegates the heavy review to the `refacil-auditor` sub-agent. Before delegating, it builds a **structured briefing** with the changed files and detected project type — the sub-agent starts evaluating, not discovering.
+
+**Prerequisites**: `agents` profile from `refacil-prereqs/SKILL.md` + output mode from `METHODOLOGY-CONTRACT.md`.
+
+## Flow
+
+### Step 0: Resolve scope
+
+- Determine the review scope BEFORE invoking the sub-agent. Prioritize in this order:
+  1) User argument (`$ARGUMENTS`)
+  2) Active change in `refacil-sdd/changes/`
+  3) Uncommitted changes (`git diff`)
+- If there are multiple active changes in `refacil-sdd/changes/` and no `$ARGUMENTS`, **stop** and ask the user to explicitly select which change to review. **Do not invoke the sub-agent with ambiguous scope.**
+
+### Step 0.3: Git working tree snapshot (run once)
+
+After scope is unambiguous (you are **not** stopping for multiple active changes), collect git state **exactly once** for this skill invocation:
+
+1. Run `git diff --name-only HEAD` → set `pathsFromDiff`.
+2. Run `git status --porcelain` → parse each line (strip the first two status columns) → set `pathsFromStatus`.
+3. **`changedFilesUnion`** = sorted unique union of `pathsFromDiff` and `pathsFromStatus` (drop empty entries).
+
+**Rules:**
+- Reuse **`changedFilesUnion`** and the **same** `git status --porcelain` interpretation everywhere below — **do not** run `git diff --name-only` or `git status --porcelain` again in this skill.
+- If a later step needs “is the working tree non-empty?”, derive it from the snapshot (e.g. non-empty `changedFilesUnion` or any porcelain line) instead of re-running `git status`.
+
+If you already have a `changeName`, run `refacil-sdd-ai sdd status <changeName> --json` to get the change status (artifacts, tasks, reviewPassed).
+
+**Review already approved**: If `reviewPassed` is `true` in the status JSON (or if the target change already has `.review-passed`), verify if there are changes after the review (marker existence: **`METHODOLOGY-CONTRACT.md` §8**):
+1. Read the `date` from `.review-passed`.
+2. Compare with `git log --since="[date]" --oneline` and **reuse the Step 0.3 snapshot** for working-tree activity (do not run `git status` again).
+3. **If there are new changes** (commits since marker date and/or paths in `changedFilesUnion`): delete the previous `.review-passed` and continue (build briefing and invoke the sub-agent).
+4. **If there are NO new changes**: inform the user and finish without invoking the sub-agent:
+   ```
+   The change [name] already has an approved review ([verdict] — [date]) and there are no subsequent changes.
+   ```
+
+### Step 0.4: Incremental scope (CA-07 — only if re-running after REQUIERE CORRECCIONES)
+
+If `changeName` is not null, check whether `refacil-sdd/changes/<changeName>/.review-last-fails.json` exists (read by explicit path — it is NOT a dotfile but may be hidden in listings):
+
+- **If the file EXISTS**: read `failedFiles` from it. Compute:
+  `incrementalScope = failedFiles ∪ changedFilesUnion`
+  - If `incrementalScope` is empty (CR-02): fall back to `changedFilesUnion` and add a comment in the briefing: `"# warning: incremental scope was empty — using full changedFilesUnion"`.
+  - Use `incrementalScope` as `changedFiles` in the briefing (Step 0.5), instead of the full `changedFilesUnion`.
+- **If the file does NOT exist**: use `changedFilesUnion` as `changedFiles` normally.
+
+### Step 0.5: Build briefing for the sub-agent (reduces auditor tool calls)
+
+Before invoking the sub-agent, extract the context that the auditor would otherwise calculate on its own:
+
+1. **Changed files** — use the scope resolved in Step 0.4 (`incrementalScope` if available, otherwise `changedFilesUnion`). Do not run `git diff` or `git status` again.
+
+2. **Project type** — read `package.json` (if it exists) and inspect the dependencies:
+   - Backend indicators: `@nestjs/*`, `express`, `fastify`, `koa`, `typeorm`, `prisma`, `pg`, `mongoose`, `bullmq`, `amqplib`
+   - Frontend indicators: `react`, `vue`, `angular`, `next`, `nuxt`, `svelte`, `vite`, `@tanstack/*`
+   - If both → `fullstack`; if only backend → `backend`; if only frontend → `frontend`; if no `package.json` or none applies → read the first 20 lines of `AGENTS.md` to infer.
+
+3. **Change objective** (only if there is an active change in `refacil-sdd/changes/`) — read the first section of `proposal.md`. Extract the objective in 1-2 sentences. If the scope is `git-diff` without an active change → `null`.
+
+4. **Cross-skill memory** — if `changeName` is not null and `refacil-sdd/changes/<changeName>/memory.yaml` exists, read it and extract `stackDetected`, `touchedFiles`. Include them in the briefing so the auditor skips re-discovery. If the file does not exist, omit — do not block (CR-04).
+
+5. **Mode** — default `concise`. If re-running after a prior `REQUIERE CORRECCIONES` (i.e., `.review-last-fails.json` was found with non-empty `failedFiles` in Step 0.4): set `mode: focused` — the auditor re-evaluates only the failing checklist items on the `failedFiles` (CR-05: focused mode still reads those files). Otherwise keep `concise`.
+
+Build the BRIEFING block:
+
+```
+BRIEFING:
+scope: <changeName | "git-diff">
+changedFiles: [path/file-1.ts, path/file-2.ts, ...]
+projectType: backend | frontend | fullstack | library
+changeObjective: <objective in 1-2 sentences, or null>
+mode: concise | detailed | focused
+stackDetected: <from memory.yaml, or omit>
+touchedFiles: [...]                   # from memory.yaml — omit if not present
+```
+
+### Step 1: Delegate to the refacil-auditor sub-agent
+
+Invoke the `refacil-auditor` sub-agent passing it the BRIEFING from the previous step.
+
+The sub-agent:
+- Uses `changedFiles` from the briefing as the blocking scope (without re-running git diff).
+- Uses `projectType` to directly load the correct checklists (without a detection phase).
+- Uses `changeObjective` as intent context (without re-reading proposal.md).
+- Reads the checklists and the blocking scope files.
+- Evaluates each item with PASS/FAIL/N/A + severity for each FAIL.
+- Returns ONE single message with the report + JSON block fenced as ` ```refacil-review-result `.
+
+### Step 2: Process the sub-agent report
+
+Show the user the **concise report** (everything before the `refacil-review-result` block). Do not show the JSON block — it is internal metadata.
+
+**If the sub-agent returned `SCOPE_ERROR: <reason>`**: propagate the error to the user and ask for clarification. Do not write a marker.
+
+### Step 2.5: Persist or clean incremental-scope state (CA-06/CA-08/CA-09/CR-01)
+
+Parse the `refacil-review-result` block from the sub-agent.
+
+**If `verdict` is `REQUIERE CORRECCIONES`**:
+- Only if `changeName` is not null (CR-01) AND the block includes a `failedFiles` field (CA-09 backward compat):
+  - Write `refacil-sdd/changes/<changeName>/.review-last-fails.json` with content: `{ "failedFiles": [...] }` using the `failedFiles` array from the JSON block.
+- If `changeName` is null or `failedFiles` is absent: skip silently — existing behavior unchanged.
+
+**If `verdict` is `APROBADO` or `APROBADO CON OBSERVACIONES`**:
+- If `refacil-sdd/changes/<changeName>/.review-last-fails.json` exists: delete it (CA-08) — run `rm -f "refacil-sdd/changes/<changeName>/.review-last-fails.json"`.
+
+### Step 3: Create `.review-passed` marker (if applicable)
+
+Parse the ` ```refacil-review-result ` block from the sub-agent. If `verdict` is **APROBADO** or **APROBADO CON OBSERVACIONES** and `changeName` is not null:
+
+Run the following command to write the marker:
+
+```bash
+refacil-sdd-ai sdd mark-reviewed <changeName> \
+  --verdict "<verdict>" \
+  --summary "<1-line summary>" \
+  --fail-count <failCount> \
+  --preexisting-count <preexistingCount>
+```
+
+Where the values are extracted from the sub-agent's `refacil-review-result` block:
+- `<verdict>`: the value of `verdict` (APROBADO, APROBADO CON OBSERVACIONES, etc.)
+- `<summary>`: the value of `summary`
+- `<failCount>`: FAILs in new code (default 0)
+- `<preexistingCount>`: pre-existing non-blocking FAILs (default 0)
+
+**Do NOT run the command if:**
+- `verdict` is `REQUIERE CORRECCIONES`.
+- `changeName` is null.
+- The sub-agent returned `SCOPE_ERROR`.
+
+### Step 4: Recommend next step
+
+According to the parsed `verdict`, add at the end of your response:
+
+**If APROBADO or APROBADO CON OBSERVACIONES:**
+```
+The next step is to archive the change.
+Do you want me to continue with /refacil:archive?
+```
+
+**If REQUIERE CORRECCIONES:**
+```
+Once the corrections are applied, the next step is to re-verify the implementation.
+Do you want me to continue with /refacil:verify?
+```
+
+## Rules
+
+- **Always build the briefing (Step 0.5) before delegating** — it is the key piece that reduces the sub-agent cost.
+- **Always delegate to the sub-agent**. Do not replicate checklist or evaluation logic here.
+- **The marker is created by this skill, not the sub-agent**.
+- If the sub-agent returned something out of format (no parseable JSON block and not `SCOPE_ERROR`), inform the user: "The reviewer returned an unstructured report — no marker was created. Review the report manually."
+- **Flow continuity**: if the user confirms affirmatively ("yes", "ok", "go", "continue", etc.) the continuity question, immediately invoke the corresponding **Skill tool**: `skill: "refacil:archive"` if the verdict is APROBADO/APROBADO CON OBSERVACIONES, or `skill: "refacil:verify"` if REQUIERE CORRECCIONES. (See `METHODOLOGY-CONTRACT.md §5`.)