Audit

---
name: quality-audit
description: >
  ISO/IEC 25010 (SQuaRE) quality audit on-demand for onboarded projects.
  Use when the user says "audit project", "quality audit", "ISO 25010",
  "SQuaRE audit", "audita el proyecto", or wants a comprehensive quality
  report across 8 characteristics with PDF + JSON evidence.
context: direct
---

# /audit — ISO/IEC 25010 Quality Audit (on-demand)

> v5.21+ — Módulo Quality Audit v1
> Agente responsable: AG-10 Quality Auditor
> Backend (v6.0.1): el cliente ejecuta los analizadores localmente y envía el `QualityReport` al MCP con `submit_quality_audit` + `attach_audit_evidence`.
>
> **Cambio v6.0.1 (MCP Path Contract)**: el viejo `run_quality_audit` orquestaba los 8 analizadores ISO/IEC 25010 en el host del MCP, lo que rompía en MCP remoto (los analizadores escaneaban el filesystem del VPS, no el del cliente). v6.0.1 mueve la orquestación al cliente: el skill ejecuta los scripts de `.quality/scripts/audit/` (ver README en ese directorio), construye el `QualityReport` dict en memoria y lo envía vía `submit_quality_audit(project, report)`. El nuevo `check_audit_tools_status(stack)` recibe el stack del cliente como parámetro en vez de escanear el filesystem. `run_quality_audit` queda como shim deprecado que retorna un error explicativo si lo llamas sin `report`.

## Uso

```
/audit [project]
```

- Sin argumento: audita el proyecto actual (resuelto desde cwd o registro).
- Con nombre: audita un proyecto onboarded (busca en `STATE_PATH/projects/`).

## Qué hace

1. **Detecta stack localmente** (lee `pubspec.yaml` / `package.json` / `go.mod` / `pyproject.toml`) y llama a `check_audit_tools_status(stack=<detected>)` para ver qué herramientas
   externas están instaladas (semgrep, gitleaks, pip-audit, lizard, jscpd,
   checkov, npm). Si falta alguna, muestra al usuario la lista + comandos de
   instalación y pregunta:
   - **¿Instalar ahora?** → ejecuta `.quality/scripts/install-audit-tools.sh --yes`
   - **¿Continuar sin ellas?** → sigue con degradación (findings incompletos)
   - **¿Cancelar?** → aborta

   Nunca se instalan herramientas sin consentimiento. La instalación es
   perezosa: sólo ocurre cuando el usuario lanza `/audit`, nunca durante
   `install.sh` o `upgrade_project`.

2. Carga el skill `embed-build-brand` para aplicar paleta negro + cyan `#29F3E3`
   al PDF final. Si el skill no está disponible, degrada a defaults y lo
   reporta en `meta.warnings` (la auditoría continúa).
3. **Ejecuta los analizadores localmente** con el orquestador Node de `.quality/scripts/audit/` (v6.0.2+ — los 8 analyzers están portados a `.mjs`, sin dependencia de Python en el cliente). Una sola llamada:

   ```bash
   node .quality/scripts/audit/run-audit.mjs --project <name> --stack <detected> [--scope <char>]
   ```

   Imprime a stdout el `QualityReport` completo (8 `CharacteristicResult` en orden canónico, `global_score`, `global_traffic_light`, `tools_used`, `audit_id`). El skill captura ese JSON y lo envía verbatim con `submit_quality_audit(project, report=<dict>)`. El backend valida el dict (`QualityReport.from_dict`), reetiqueta `audit_tools_status` y devuelve el report canónico que pasa a AG-10. **No uses `run_quality_audit` salvo como fallback** — está deprecado y devuelve error si lo invocas sin `report`.

   Los analyzers escanean el filesystem del **cliente** (no el del MCP host), por eso funcionan en MCP remoto. Las herramientas externas (semgrep, gitleaks, pip-audit, npm, lizard, jscpd, checkov) son opcionales: si faltan, `tools_used` las marca `missing` y el audit continúa con degradación. El scoring (penalties por severidad, mix 60/40 de maintainability, media global) se calcula client-side en `lib/scoring.mjs` (réplica fiel de `server/audit/scoring.py`); el **PDF se renderiza server-side** en `attach_audit_evidence` (ReportLab + brand embed.build).

   El report cubre los 8 analizadores SQuaRE en orden:
   1. Functional Suitability
   2. Performance Efficiency
   3. Compatibility
   4. Usability
   5. Reliability
   6. Security (semgrep + gitleaks + pip-audit/npm audit + checkov si IaC)
   7. Maintainability (mix 60% clásico + 40% SpecBox — documentado en `breakdown`)
   8. Portability
4. Delega al agente **AG-10 Quality Auditor** la síntesis de justificaciones
   y recomendaciones priorizadas. AG-10 jamás modifica código.
5. Invoca `attach_audit_evidence(project, report=<enriched>)` → persiste:
   - `STATE_PATH/projects/<project>/evidence/audits/audit_<ts>.json`
   - `STATE_PATH/projects/<project>/evidence/audits/audit_<ts>.pdf`
   - Actualiza `project_meta.last_audit` (consumible por specbox_cloud y scripts externos).
6. Muestra un resumen con score global, semáforo por bloque y rutas de
   evidencia.

## Scope parcial

```
/audit <project> security
/audit <project> maintainability
```

Se traduce a `run-audit.mjs --scope <char>`: ejecuta solo ese analizador, los
otros 7 se emiten como `skipped` (no penalizan el `global_score`, que pasa a
ser el del único bloque activo). Útil para re-correr un único bloque tras
arreglar findings concretos.

## Degradación elegante

Las herramientas externas son opcionales — si falta alguna, se reporta en
`tools_used` con `status: "missing"` y la auditoría continúa:

- `semgrep` — SAST multi-lenguaje (OWASP Top 10)
- `gitleaks` — detección de secretos
- `pip-audit` / `npm audit` — vulnerabilidades de dependencias
- `checkov` — IaC (solo si se detectan Dockerfile/Terraform/k8s)
- `lizard` — complejidad ciclomática
- `jscpd` — duplicación de código

## Qué NO hace (v1, explícito)

- NO modifica archivos del proyecto auditado.
- NO introduce hooks automáticos.
- NO bloquea merges ni impone gates de score mínimo.
- NO compara con auditorías anteriores (sin histórico en v1).
- NO se integra con CI/CD externo.

## Flujo del agente

```
/audit mcprofit
  │
  ├─ 1. detectar stack localmente + check_audit_tools_status(stack)
  │     ↓
  │   Si faltan tools → mostrar lista + preguntar (install / continue / cancel)
  │     ├─ install → .quality/scripts/install-audit-tools.sh --yes
  │     ├─ continue → seguir con degradación
  │     └─ cancel → abortar
  │
  ├─ 2. load_skill("embed-build-brand")   (opcional; si falta → warning)
  ├─ 3. node .quality/scripts/audit/run-audit.mjs --project mcprofit --stack <detected>
  │       → captura el QualityReport JSON de stdout
  │       → submit_quality_audit("mcprofit", report=<dict>)
  │     ↓
  │   QualityReport canónico (validado) con 8 CharacteristicResult + audit_tools_status
  │     ↓
  ├─ 4. AG-10 Quality Auditor sintetiza:
  │     - justification por bloque (cita raw_metrics)
  │     - recommendations priorizadas (con finding_ref)
  │     - desglose 60/40 verbalizado en maintainability
  │     ↓
  ├─ 5. attach_audit_evidence("mcprofit", report=<enriched>)
  │     ↓
  │   PDF + JSON bajo evidence/audits/, project_meta.last_audit actualizado
  │
  └─ 6. Resumen final al usuario
```

## Dogfooding

```
/audit specbox-engine
```

Debe funcionar sobre el propio repo como caso de prueba.

## Criterios de aceptación

- Genera PDF + JSON válidos en `evidence/audits/`.
- Los 8 bloques SQuaRE aparecen con scores justificados.
- Security detecta al menos una vulnerabilidad en un proyecto con CVE conocido.
- Maintainability muestra el breakdown 60/40 explícitamente.
- El PDF respeta el brand embed.build (fallback si el skill falta).
- Herramientas ausentes se reportan sin abortar.
- La auditoría no modifica nada del proyecto auditado.