@eduardbar/drift 1.1.0 → 1.3.0

package/dist/types.d.ts

@@ -92,6 +92,123 @@ export interface AIIssue {
     fix_suggestion: string;
     effort: 'low' | 'medium' | 'high';
 }
+export type MergeRiskLevel = 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
+export interface TrustGatePolicyPreset {
+    branch: string;
+    enabled?: boolean;
+    minTrust?: number;
+    maxRisk?: MergeRiskLevel;
+}
+export interface TrustGatePolicyPack {
+    enabled?: boolean;
+    minTrust?: number;
+    maxRisk?: MergeRiskLevel;
+}
+export interface TrustGatePolicyConfig {
+    enabled?: boolean;
+    minTrust?: number;
+    maxRisk?: MergeRiskLevel;
+    presets?: TrustGatePolicyPreset[];
+    policyPacks?: Record<string, TrustGatePolicyPack>;
+}
+export interface TrustReason {
+    label: string;
+    detail: string;
+    impact: number;
+}
+export interface TrustFixPriority {
+    rank: number;
+    rule: string;
+    severity: DriftIssue['severity'];
+    occurrences: number;
+    estimated_trust_gain: number;
+    effort: 'low' | 'medium' | 'high';
+    suggestion: string;
+    confidence?: 'low' | 'medium' | 'high';
+    explanation?: string;
+    systemic?: boolean;
+}
+export interface TrustAdvancedComparison {
+    source: 'previous-trust-json' | 'snapshot-history';
+    trend: 'improving' | 'regressing' | 'stable';
+    summary: string;
+    trust_delta?: number;
+    previous_trust_score?: number;
+    previous_merge_risk?: MergeRiskLevel;
+    snapshot_score_delta?: number;
+    snapshot_label?: string;
+    snapshot_timestamp?: string;
+}
+export interface TrustAdvancedContext {
+    comparison?: TrustAdvancedComparison;
+    team_guidance: string[];
+}
+export interface TrustDiffContext {
+    baseRef: string;
+    status: 'improved' | 'regressed' | 'neutral';
+    scoreDelta: number;
+    newIssues: number;
+    resolvedIssues: number;
+    filesChanged: number;
+    penalty: number;
+    bonus: number;
+    netImpact: number;
+}
+export interface DriftTrustReport {
+    scannedAt: string;
+    targetPath: string;
+    trust_score: number;
+    merge_risk: MergeRiskLevel;
+    top_reasons: TrustReason[];
+    fix_priorities: TrustFixPriority[];
+    diff_context?: TrustDiffContext;
+    advanced_context?: TrustAdvancedContext;
+}
+export interface TrustKpiDiagnostic {
+    level: 'warning' | 'error';
+    code: 'path-not-found' | 'path-not-supported' | 'read-failed' | 'parse-failed' | 'invalid-shape' | 'invalid-diff-context';
+    message: string;
+    file?: string;
+}
+export interface TrustScoreStats {
+    average: number | null;
+    median: number | null;
+    min: number | null;
+    max: number | null;
+}
+export interface TrustDiffTrendSummary {
+    available: boolean;
+    samples: number;
+    statusDistribution: {
+        improved: number;
+        regressed: number;
+        neutral: number;
+    };
+    scoreDelta: {
+        average: number | null;
+        median: number | null;
+    };
+    issues: {
+        newTotal: number;
+        resolvedTotal: number;
+        netNew: number;
+    };
+}
+export interface TrustKpiReport {
+    generatedAt: string;
+    input: string;
+    files: {
+        matched: number;
+        parsed: number;
+        malformed: number;
+    };
+    prsEvaluated: number;
+    mergeRiskDistribution: Record<MergeRiskLevel, number>;
+    trustScore: TrustScoreStats;
+    highRiskRatio: number | null;
+    diffTrend: TrustDiffTrendSummary;
+    diagnostics: TrustKpiDiagnostic[];
+}
 /**
  * Layer definition for architectural boundary enforcement.
  */
@@ -116,11 +233,40 @@ export interface DriftConfig {
     layers?: LayerDefinition[];
     modules?: ModuleBoundary[];
     plugins?: string[];
+    performance?: DriftPerformanceConfig;
     architectureRules?: {
         controllerNoDb?: boolean;
         serviceNoHttp?: boolean;
         maxFunctionLines?: number;
     };
+    saas?: {
+        freeUserThreshold?: number;
+        maxRunsPerWorkspacePerMonth?: number;
+        maxReposPerWorkspace?: number;
+        retentionDays?: number;
+        strictActorEnforcement?: boolean;
+        maxWorkspacesPerOrganizationByPlan?: {
+            free?: number;
+            sponsor?: number;
+            team?: number;
+            business?: number;
+        };
+    };
+    trustGate?: TrustGatePolicyConfig;
+}
+export interface DriftPerformanceConfig {
+    lowMemory?: boolean;
+    chunkSize?: number;
+    maxFiles?: number;
+    maxFileSizeKb?: number;
+    includeSemanticDuplication?: boolean;
+}
+export interface DriftAnalysisOptions {
+    lowMemory?: boolean;
+    chunkSize?: number;
+    maxFiles?: number;
+    maxFileSizeKb?: number;
+    includeSemanticDuplication?: boolean;
 }
 export interface PluginRuleContext {
     projectRoot: string;
@@ -128,13 +274,17 @@ export interface PluginRuleContext {
     config?: DriftConfig;
 }
 export interface DriftPluginRule {
+    id?: string;
     name: string;
     severity?: DriftIssue['severity'];
     weight?: number;
     detect: (file: SourceFile, context: PluginRuleContext) => DriftIssue[];
+    fix?: (issue: DriftIssue, file: SourceFile, context: PluginRuleContext) => DriftIssue | void;
 }
 export interface DriftPlugin {
     name: string;
+    apiVersion?: number;
+    capabilities?: Record<string, string | number | boolean>;
     rules: DriftPluginRule[];
 }
 export interface LoadedPlugin {
@@ -143,6 +293,16 @@ export interface LoadedPlugin {
 }
 export interface PluginLoadError {
     pluginId: string;
+    pluginName?: string;
+    ruleId?: string;
+    code?: string;
+    message: string;
+}
+export interface PluginLoadWarning {
+    pluginId: string;
+    pluginName?: string;
+    ruleId?: string;
+    code?: string;
     message: string;
 }
 export interface FileDiff {

package/docs/PRD.md

@@ -1,208 +1,235 @@
 # PRD - drift
 
-Version: 1.1-draft  
-Estado: Draft  
-Producto: `@eduardbar/drift`
+> **AI Code Audit CLI para recuperar confianza de merge en PRs asistidos por IA.**
 
-## 1) Contexto
+**Version del PRD**: 1.3.0-scope-refresh  
+**Version de producto vigente**: 1.2.0  
+**Estado**: Activo  
+**Producto**: `@eduardbar/drift`  
+**Owner**: Eduardo Barba  
+**Fecha**: 2026-03-15
 
-`drift` es un CLI de analisis estatico para TypeScript que detecta deuda tecnica asociada a codigo generado por IA y calcula un score de calidad por archivo y por repositorio.
+---
 
-Hoy el producto ya cubre escaneo AST, score, reportes y comandos operativos (`scan`, `fix`, `report`, `ci`, `diff`, `badge`, `snapshot`, `trend`, `blame`).
+## 1. Contexto y problema
 
-Este PRD define la evolucion para convertir a drift en una plataforma de calidad de codigo AI-first, con foco en revision de PRs, reglas de arquitectura y accionabilidad.
-
-## 2) Vision de Producto
-
-Ser la herramienta de referencia para equipos que usan IA para programar y necesitan detectar, priorizar y corregir deuda tecnica antes de que llegue a produccion.
-
-## 3) Killer Feature
+El uso de IA para programar acelera entregas, pero tambien aumenta ruido tecnico en Pull Requests: cambios grandes, deuda encubierta, reglas de arquitectura rotas y riesgo de merge dificil de evaluar rapido.
 
-## AI Code Smell Detector
-
-El diferencial principal de drift es detectar patrones de olor tecnico vinculados a codigo IA, estimar probabilidad de origen IA y traducir hallazgos en acciones concretas (fixes, comentarios de PR, reglas de arquitectura y reportes).
+Hoy muchos equipos hacen review "a ojo" o dependen de checks incompletos. Resultado: se mergea codigo con riesgo real porque falta una senial consolidada y accionable para decidir si un PR esta listo.
 
-## 4) Objetivos de Negocio y Producto
-
-- Reducir riesgo de mantenimiento en repos con alto volumen de codigo IA.
-- Dar feedback accionable en el punto de trabajo (CLI, PR y editor).
-- Estandarizar calidad arquitectonica con reglas configurables por equipo.
-- Escalar desde CLI local a experiencia organizacional (dashboard SaaS).
+Drift se reposiciona para cerrar ese gap: pasar de "scanner de deuda" a "decision engine de confianza de merge" para repos TypeScript/JavaScript con flujo local y CI.
 
-## 5) Alcance MVP por Feature (sin humo)
+---
 
-Cada feature incluye objetivo, alcance MVP y criterios de aceptacion.
-
-### 5.1 Detector de codigo generado por IA
-
-- Objetivo: estimar `ai_likelihood` por archivo y listar `files_suspected`.
-- Alcance MVP:
-  - Exponer `ai_likelihood` (0-100) dentro de salida JSON/AI.
-  - Agregar lista ordenada de archivos sospechados con score y reglas disparadas.
-  - No hacer afirmaciones absolutas; reportar como probabilidad.
-- Criterios de aceptacion:
-  - `drift scan <path> --ai` incluye `ai_likelihood` por archivo.
-  - Reporte global incluye `files_suspected` y top N archivos.
-  - Tests cubren serializacion y orden de prioridad.
-
-### 5.2 PR reviewer automatico (`drift review` + comentario en PR)
-
-- Objetivo: revisar cambios de PR y publicar feedback tecnico automatico.
-- Alcance MVP:
-  - Nuevo comando `drift review` para analizar diff contra base branch.
-  - Salida markdown apta para comentario de PR.
-  - Integracion base via GitHub CLI (`gh`) en CI.
-- Criterios de aceptacion:
-  - `drift review --base main` devuelve score de PR y top issues.
-  - En workflow CI se publica un comentario unico actualizable.
-  - Si score supera umbral configurable, CI falla.
-
-### 5.3 Reglas de arquitectura configurables
-
-- Objetivo: habilitar reglas de arquitectura de negocio definidas por el equipo.
-- Alcance MVP:
-  - Soporte en `drift.config.ts` para:
-    - `controller-no-db`
-    - `service-no-http`
-    - `max-function-lines`
-  - Mensajes de error claros con ubicacion y recomendacion.
-- Criterios de aceptacion:
-  - Config valida y tipada.
-  - Reglas activas afectan score y aparecen en reporte.
-  - Fixtures de test para casos validos e invalidos.
+## 2. Reposicionamiento de producto
 
-### 5.4 Score de calidad por repo con breakdown
+### 2.1 Nueva tesis
 
-- Objetivo: mostrar salud del repo en forma ejecutiva y tecnica.
-- Alcance MVP:
-  - Score global del repo.
-  - Breakdown por severidad, regla y carpeta.
-  - Tendencia minima (ultimos snapshots locales).
-- Criterios de aceptacion:
-  - `drift scan` muestra score repo + breakdown resumido.
-  - `--json` expone estructura consumible por CI/dashboard.
+`drift` es un **AI Code Audit CLI** orientado a responder una pregunta critica antes de mergear:
 
-### 5.5 Mapa de arquitectura automatico (`drift map` -> `architecture.svg`)
+**"Este PR asistido por IA es confiable para merge?"**
 
-- Objetivo: visualizar dependencias y violaciones de capas.
-- Alcance MVP:
-  - Nuevo comando `drift map`.
-  - Genera `architecture.svg` desde imports y modulos detectados.
-  - Marca ciclos y violaciones de capas.
-- Criterios de aceptacion:
-  - `drift map ./src` crea `architecture.svg` sin edicion manual.
-  - El SVG es legible en repos medianos (ej. <= 300 archivos TS).
+### 2.2 North Star de posicionamiento
 
-### 5.6 VSCode extension con feedback en tiempo real
+Mover el foco de "contar smells" a "reducir riesgo de merge" con una salida resumida, priorizada y utilizable por developers, reviewers y tech leads.
 
-- Objetivo: bajar el tiempo entre error y correccion.
-- Alcance MVP:
-  - Diagnosticos por archivo al guardar.
-  - Score visible por archivo.
-  - Quick actions para sugerencias simples.
-- Criterios de aceptacion:
-  - La extension muestra issues drift en panel Problems.
-  - La latencia por archivo en save se mantiene en nivel usable.
+---
 
-### 5.7 Fix automatico (`drift fix`) con ejemplo antes/despues
+## 3. Que NO es y que SI es Drift
 
-- Objetivo: convertir hallazgos en cambios concretos de bajo riesgo.
-- Alcance MVP:
-  - `drift fix` aplica fixes seguros en reglas seleccionadas.
-  - Modo preview con diff antes/despues.
-  - Modo write con confirmacion.
-- Criterios de aceptacion:
-  - `drift fix --preview` imprime diff legible.
-  - `drift fix --write` modifica solo reglas soportadas.
-  - Tests de no-regresion para no romper sintaxis TS.
+| Categoria | Definicion |
+|---|---|
+| No es | Un code generator ni un copiloto para escribir features |
+| No es | Un SaaS dependiente de backend propio para funcionar |
+| No es | Un reemplazo completo de code review humano |
+| No es | Un quality gate magico multi-lenguaje full stack |
+| Si es | Un CLI local/CI de auditoria tecnica para codigo TypeScript/JavaScript |
+| Si es | Un sistema de scoring y priorizacion de deuda con foco en riesgo de merge |
+| Si es | Una herramienta para PRs asistidos por IA con salida accionable |
+| Si es | Un producto operable sin infraestructura propietaria (user-run) |
 
-Ejemplo (antes/despues):
+---
 
-```ts
-// Antes
-console.log(userData)
-
-// Despues (sugerencia simple)
-// Removed debug leftover; use structured logger if needed.
-```
-
-### 5.8 Reporte tecnico (`drift report` -> `drift-report.html`)
-
-- Objetivo: entregar reporte compartible para devs, tech leads y QA.
-- Alcance MVP:
-  - Salida HTML `drift-report.html` con score, breakdown y top issues.
-  - Secciones por archivo con snippets y sugerencias.
-- Criterios de aceptacion:
-  - `drift report ./src --html` genera archivo navegable.
-  - El reporte puede adjuntarse en CI artifacts.
-
-### 5.9 Metricas de riesgo de mantenimiento (hotspots)
-
-- Objetivo: priorizar deuda por impacto real.
-- Alcance MVP:
-  - Hotspots combinando score + frecuencia de cambios + criticidad.
-  - Ranking de archivos para plan de refactor.
-- Criterios de aceptacion:
-  - `drift trend` o salida dedicada muestra top hotspots.
-  - Metodo de ranking documentado y testeado.
-
-### 5.10 Plugin system (`drift-plugin-*`)
-
-- Objetivo: extender drift sin tocar el core.
-- Alcance MVP:
-  - Carga de plugins por convension `drift-plugin-*`.
-  - API minima para registrar reglas y metadata.
-  - Aislamiento de errores de plugins para no romper scan completo.
-- Criterios de aceptacion:
-  - Plugin de ejemplo funcional en repo de ejemplo.
-  - Si un plugin falla, drift sigue ejecutando y reporta el error.
+## 4. Estado real del producto (v1.2.0)
 
-## 6) Roadmap Realista
-
-### v1.1
-
-- `drift review` para PR comments.
-- Score de PR y score de repo con breakdown minimo.
+### 4.1 Capacidades entregadas y activas
 
-### v1.2
+| Area | Estado | Capacidades vigentes |
+|---|---|---|
+| Analisis AST y scoring | Entregado | Reglas de drift, score por archivo/repositorio, salida CLI/JSON/AI |
+| PR review | Entregado | `drift review` con diff vs base, markdown para PR, delta de issues |
+| Arquitectura | Entregado | `drift map` con `architecture.svg`, cycle edges, layer violations |
+| Fixes | Entregado | `drift fix --preview` y `drift fix --write` con confirmacion (`--yes` para CI) |
+| Reporteria | Entregado | `drift report` HTML self-contained |
+| CI | Entregado | Workflow para comentario unico y actualizable en PR |
+| Editor | Entregado | VSCode quick actions para fixes de bajo riesgo |
+| Extensibilidad | MVP entregado | Plugin system `drift-plugin-*` con aislamiento de errores |
+| Foundations cloud-like | Entregado (base) | `drift cloud ingest|summary|dashboard`, politica free-until-7500 en PRD |
 
-- Reglas de arquitectura configurables.
-- `drift map` y generacion de `architecture.svg`.
+### 4.2 Abiertos actuales
 
-### v2
+- Hardening del contrato de plugins para ecosistema externo de largo plazo.
+- Evolucion de foundations cloud-like hacia experiencia multi-tenant completa (auth, roles, billing) cuando corresponda.
 
-- VSCode extension con feedback en tiempo real.
-- `drift fix` con preview/write y fixes seguros.
+Nota: este PRD no declara como implementado nada fuera de las capacidades ya reflejadas en v1.2.0.
 
-### v3
+---
 
-- SaaS dashboard para historico, equipos y gobierno de calidad.
+## 5. Feature estrella: `drift trust`
 
-## 7) Fuera de Alcance (por ahora)
+### 5.1 Objetivo
 
-- Soporte multi-lenguaje completo fuera de TypeScript/JS.
-- Autofix de reglas de alto riesgo sin confirmacion.
-- Integraciones propietarias cerradas sin API estable.
+Introducir `drift trust` como salida de alto nivel para decision de merge en PRs asistidos por IA.
 
-## 8) KPIs de Exito
+### 5.2 Output conceptual esperado
 
-- Reduccion de score promedio en repos activos.
-- % de PRs con feedback drift resuelto antes de merge.
-- Tiempo medio desde deteccion hasta fix aplicado.
-- Adopcion de reglas de arquitectura por equipo.
+`drift trust` debe sintetizar en un bloque corto y accionable:
 
-## 9) Dependencias y Riesgos
+| Campo | Proposito |
+|---|---|
+| Trust Score | Puntaje de confianza de merge (0-100) |
+| Merge Risk | Clasificacion de riesgo (`LOW`, `MEDIUM`, `HIGH`, `CRITICAL`) |
+| Top Reasons | Principales razones que explican el riesgo |
+| Fix Priorities | Orden recomendado de correcciones para bajar riesgo rapido |
 
-- Performance en repos grandes (AST + analisis cross-file).
-- Calidad de senial en `ai_likelihood` (riesgo de falsos positivos).
-- Compatibilidad de integraciones CI/PR entre plataformas.
-- Diseno de API de plugins sin romper backward compatibility.
+### 5.3 Alcance funcional del feature
 
-## 10) Definicion de Done (global)
+- Usa seniales ya existentes en Drift (reglas, severidad, diff, arquitectura, hotspots) para componer una conclusion ejecutiva.
+- Prioriza interpretabilidad: cada resultado debe explicar por que sube/baja la confianza.
+- Se diseña para uso local y CI sin requerir servicio central.
 
-Una feature del roadmap se considera terminada cuando:
+Importante: en este documento, `drift trust` se define como **scope de producto**; su implementacion tecnica se planifica por etapas.
 
-- Tiene comando/flujo usable y documentado.
-- Tiene tests automatizados de casos base y borde.
-- Tiene salida estable en CLI/JSON para CI.
-- Tiene criterios de aceptacion de esta PRD cumplidos.
+---
+
+## 6. Scope de producto: Core vs Premium
+
+### 6.1 Drift Core (base abierta y utilizable)
+
+| Incluido en Core | Notas |
+|---|---|
+| `scan`, `review`, `fix`, `report`, `map`, `ci`, `diff`, `snapshot`, `trend`, `blame` | Mantiene propuesta actual de CLI tecnico |
+| Reglas de drift y score base | Incluye salida JSON/AI para automatizacion |
+| `drift trust` baseline | Trust Score + Merge Risk + Top Reasons + Fix Priorities en modo esencial |
+| Uso local + CI en runners del usuario | Sin infraestructura Drift obligatoria |
+
+### 6.2 Drift Premium (valor para equipos)
+
+| Incluido en Premium | Propuesta de valor |
+|---|---|
+| `drift trust` avanzado | Mayor contexto historico, comparativas y guidance de remediacion de equipo |
+| Policy packs y controles por equipo | Gates y criterios de merge mas finos |
+| Reportes ejecutivos extendidos | Vistas para liderazgo tecnico y seguimiento de riesgo |
+| Soporte y prioridad | Respuesta mas rapida y acompanamiento de adopcion |
+
+Nota: Premium define direccion comercial; la activacion concreta depende del roadmap de producto y capacidad operativa.
+
+---
+
+## 7. Pricing inicial y propuesta comercial
+
+### 7.1 Planes
+
+| Plan | Precio | Publico objetivo | Valor principal |
+|---|---:|---|---|
+| Free | USD 0 (forever) | Developers individuales + open source | Analisis local ilimitado, output accionable y adopcion sin friccion |
+| Sponsor | USD 8/mes o USD 80/anio | Fans, freelancers y power users | Apoyo al proyecto + rule packs premium ligeros + early access |
+| Team | USD 39/mes por org o USD 390/anio | Equipos pequenos/medianos | Gobernanza inicial: policies, thresholds por branch y suppressions por regla |
+| Business | USD 149/mes por org o USD 1490/anio | Equipos con mayor exigencia | Governance/compliance avanzado, custom rules y soporte prioritario |
+
+### 7.2 Hipotesis de monetizacion
+
+- Inicio con **GitHub Sponsors** como canal principal de conversion (Sponsor plan).
+- Validar willingness-to-pay antes de escalar complejidad comercial.
+- Evolucionar hacia Team/Business conforme se consolide `drift trust` y demanda de gobierno por equipo.
+
+---
+
+## 8. Estrategia operativa (sin infraestructura propia)
+
+### 8.1 Principios
+
+- Drift corre donde ya corre el codigo: laptop del developer, CI existente, runners del usuario.
+- No se requiere backend propietario para la propuesta principal de valor.
+- Costos operativos iniciales bajos para maximizar foco en producto y distribucion.
+
+### 8.2 Modelo operativo
+
+| Dimension | Decision |
+|---|---|
+| Compute | Local/CI del usuario |
+| Storage | Artefactos y reportes en entorno del usuario |
+| Integracion | CLI + GitHub Actions + outputs markdown/JSON/AI |
+| Monetizacion inicial | GitHub Sponsors + futura oferta Team/Business |
+
+---
+
+## 9. Launch strategy por etapas
+
+### Etapa 1 - Reposicionamiento y mensaje (inmediato)
+
+- Actualizar narrativa publica: de "deuda tecnica IA" a "merge trust para PRs asistidos por IA".
+- Publicar docs y ejemplos orientados a decision de merge.
+- CTA principal: probar `drift review` y futura experiencia `drift trust`.
+
+### Etapa 2 - `drift trust` baseline (producto)
+
+- Entregar salida conceptual en CLI/CI con Trust Score, Merge Risk, Top Reasons, Fix Priorities.
+- Incorporar senales de diff/PR de forma deterministica (`--base`) y salida markdown lista para comentarios de PR.
+- Medir adopcion en PR workflows y feedback de interpretabilidad.
+- Ajustar pesos/heuristicas con evidencia de uso real.
+
+### Etapa 3 - Conversion y expansion
+
+- Activar perks para Sponsor y clarificar diferencia Core vs Premium.
+- Formalizar Team plan con policies y reportes de riesgo compartidos.
+- Preparar oferta Business para cuentas con necesidad de governance.
+
+---
+
+## 10. Positioning copy (taglines y one-liners)
+
+### 10.1 Taglines
+
+- "Merge con confianza, incluso cuando el PR vino asistido por IA."
+- "Tu AI Code Audit CLI para decidir merge sin adivinar."
+- "Menos ruido de PR, mas confianza de release."
+
+### 10.2 One-liners
+
+- "Drift convierte senales tecnicas de un PR en una decision clara de merge risk."
+- "Deuda tecnica IA detectada, priorizada y traducida a acciones concretas antes de mergear."
+- "TypeScript AI audit en local y CI, sin depender de infraestructura externa."
+
+---
+
+## 11. KPIs y metricas de exito
+
+| KPI | Objetivo |
+|---|---|
+| % de PRs evaluados con senial de confianza | Medir adopcion de flujo `review/trust` |
+| Reduccion de issues de alto riesgo antes de merge | Medir impacto real en calidad |
+| Tiempo desde deteccion a fix | Medir accionabilidad de la salida |
+| Conversion a Sponsor/Team | Validar monetizacion temprana |
+
+---
+
+## 12. Riesgos y mitigaciones
+
+| Riesgo | Mitigacion |
+|---|---|
+| Falsos positivos en senal de riesgo | Transparencia en Top Reasons + ajuste iterativo de reglas/pesos |
+| Confusion entre "auditoria" y "autofix magico" | Mensaje explicito de que Drift no reemplaza revision humana |
+| Presion por features enterprise tempranas | Enfoque por etapas: Sponsors primero, Team/Business luego |
+| Variabilidad de entornos CI | Mantener salida portable y documentar integraciones recomendadas |
+
+---
+
+## 13. Definition of Done para este refresh de scope
+
+- PRD unificado con posicionamiento "AI Code Audit CLI".
+- `drift trust` definido como feature estrella con output conceptual completo.
+- Delimitacion explicita de que Drift es/no es.
+- Pricing y Core vs Premium documentados de forma consistente.
+- Estrategia operativa sin infraestructura propia y monetizacion via Sponsors declaradas.
+- Launch strategy por etapas y copy de posicionamiento incluidos.

package/docs/plugin-contract.md

@@ -0,0 +1,61 @@
+# Drift Plugin Contract (v2)
+
+This document defines the external plugin contract for `@eduardbar/drift`.
+
+## Minimal plugin shape
+
+```js
+module.exports = {
+  name: 'my-plugin',
+  apiVersion: 1,
+  capabilities: {
+    fixes: true,
+    tags: 'security',
+  },
+  rules: [
+    {
+      id: 'no-debug-leftovers',
+      severity: 'warning',
+      weight: 8,
+      detect(file, context) {
+        return []
+      },
+      fix(issue, file, context) {
+        return issue
+      },
+    },
+  ],
+}
+```
+
+## Contract rules
+
+- `name`: required non-empty string.
+- `apiVersion`: recommended and currently supported value is `1`.
+- `capabilities`: optional object map with primitive values (`string | number | boolean`).
+- `rules`: required array with at least one valid rule.
+- Rule `id` (or legacy `name` fallback):
+  - for `apiVersion: 1` must match `^[a-z][a-z0-9]*(?:[-_/][a-z0-9]+)*$`
+  - must be unique within the plugin.
+- `detect(file, context)`: required function returning `DriftIssue[]`.
+
+## Legacy compatibility
+
+- Plugins without `apiVersion` still load for backward compatibility.
+- Drift emits warning code `plugin-api-version-implicit` and assumes compatibility mode.
+- In compatibility mode, non-standard rule IDs are warnings (`plugin-rule-id-format-legacy`) instead of hard errors.
+
+## Failure isolation
+
+- Invalid plugin contracts are skipped and reported as diagnostics.
+- Runtime errors thrown by one plugin rule are isolated to that rule; scan continues for other rules/files.
+
+## Common diagnostic codes
+
+- `plugin-api-version-implicit`: missing `apiVersion`; plugin loaded in legacy mode.
+- `plugin-api-version-invalid`: `apiVersion` is not a positive integer.
+- `plugin-api-version-unsupported`: plugin version is not supported by current drift runtime.
+- `plugin-rule-id-invalid`: rule ID format invalid for explicit API version.
+- `plugin-rule-id-duplicate`: duplicate rule ID inside the same plugin.
+- `plugin-capabilities-invalid`: `capabilities` is not an object.
+- `plugin-capabilities-value-invalid`: capability value is not a primitive.