@eduardbar/drift 1.2.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,6 +233,7 @@ export interface DriftConfig {
     layers?: LayerDefinition[];
     modules?: ModuleBoundary[];
     plugins?: string[];
+    performance?: DriftPerformanceConfig;
     architectureRules?: {
         controllerNoDb?: boolean;
         serviceNoHttp?: boolean;
@@ -126,7 +244,29 @@ export interface DriftConfig {
         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;
@@ -134,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 {
@@ -149,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,157 +1,235 @@
 # PRD - drift
 
-Version: 1.2.0  
-Estado: Activo  
-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 score por archivo y por repositorio.
+---
 
-Con release `v1.2.0`, el producto entrega comandos operativos, analisis AST, reglas de arquitectura configurables, salida accionable, workflow CI para PR comments, y foundations SaaS (`drift cloud ingest|summary|dashboard`) con politica free-until-7500.
+## 1. Contexto y problema
 
-## 2) Vision de producto
+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.
 
-Ser la herramienta de referencia para equipos que usan IA para programar y necesitan detectar, priorizar y corregir deuda tecnica antes de mergear a produccion.
+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.
 
-## 3) Killer feature
+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.
 
-## AI Code Smell Detector
+---
 
-Detectar patrones de olor tecnico vinculados a codigo IA, estimar probabilidad de origen IA y traducir hallazgos en acciones concretas (fixes, review de PR, reglas de arquitectura y reportes).
+## 2. Reposicionamiento de producto
 
-## 4) Estado de cumplimiento (actualizado)
+### 2.1 Nueva tesis
 
-### Entregado
+`drift` es un **AI Code Audit CLI** orientado a responder una pregunta critica antes de mergear:
 
-- `drift review` en CLI para analizar diff contra base y producir markdown usable en PR.
-- `drift map` basico para generar `architecture.svg`.
-- Senial de IA en salida (`ai_likelihood` y `files_suspected`).
-- Reglas de arquitectura configurables via `drift.config.ts`.
-- Score y breakdown por dimensiones para lectura ejecutiva y tecnica.
-- Metricas de maintenance risk/hotspots.
-- Plugin system MVP (`drift-plugin-*`) con aislamiento de errores.
-- `drift fix` con modos preview/write.
-- Workflow CI para comentario automatico unico y actualizable de `drift review`.
-- `drift map` con marcado de cycle edges y layer violations en el SVG.
-- VSCode quick actions para fixes de bajo riesgo.
-- Confirmacion interactiva para `drift fix --write` (con `--yes` para CI/no-interactive).
-- `drift report` HTML (`drift-report.html`) sin flag extra.
-- Documentacion y tests del release.
+**"Este PR asistido por IA es confiable para merge?"**
 
-### Parcial
+### 2.2 North Star de posicionamiento
 
-- Consolidacion/hardening de API de plugins para ecosistema externo amplio.
+Mover el foco de "contar smells" a "reducir riesgo de merge" con una salida resumida, priorizada y utilizable por developers, reviewers y tech leads.
 
-### Pendiente
+---
 
-- Hardening del contrato de plugins para ecosistema externo amplio.
-- Evolucion del dashboard SaaS foundations a experiencia multi-tenant full (auth, permisos por rol y billing activo post-umbral).
+## 3. Que NO es y que SI es Drift
 
-## 5) Criterios de aceptacion vigentes
+| 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) |
 
-### 5.1 Entregables cerrados en v1.1.0
+---
 
-- `drift review --base <ref>` devuelve score delta de PR, issues nuevos/resueltos y markdown.
-- `drift scan --ai` incluye `ai_likelihood` y ranking `files_suspected`.
-- `drift map <path>` genera `architecture.svg` utilizable sin edicion manual.
-- `drift report [path]` genera HTML self-contained (no requiere `--html`).
-- `drift fix --preview` muestra antes/despues y `drift fix --write` aplica reglas soportadas.
+## 4. Estado real del producto (v1.2.0)
 
-### 5.1.b Entregables cerrados en v1.2 (scope tecnico)
+### 4.1 Capacidades entregadas y activas
 
-- Workflow CI publica/actualiza comentario unico en PR para `drift review`.
-- `drift map` marca visualmente ciclos y violaciones por capa.
-- Extension VSCode expone quick actions para `debug-leftover` y `catch-swallow`.
-- `drift fix --write` pide confirmacion interactiva por defecto y admite `--yes`.
+| 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 |
 
-### 5.2 Objetivos aun abiertos (CI/editor/UX)
+### 4.2 Abiertos actuales
 
-- Hardening del contrato de plugins para compatibilidad de largo plazo (versionado/migraciones).
+- 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.
 
-## 6) Roadmap actualizado
+Nota: este PRD no declara como implementado nada fuera de las capacidades ya reflejadas en v1.2.0.
 
-### v1.1 (completado - release 1.1.0)
+---
 
-Prioridades cerradas:
-- CLI de review para PR, mapa basico, salida AI, reglas configurables, report HTML, fix preview/write, hotspots, plugin MVP.
+## 5. Feature estrella: `drift trust`
 
-Done del bloque:
-- Features documentadas.
-- Tests de paths principales.
-- Salidas CLI/JSON/AI consistentes para uso local y CI.
+### 5.1 Objetivo
 
-### v1.2 (completado - cierre de pendientes tecnicos)
+Introducir `drift trust` como salida de alto nivel para decision de merge en PRs asistidos por IA.
 
-Prioridades cerradas:
-- Comentario automatico actualizable en PR desde workflow CI.
-- Mejora de `drift map` para destacar ciclos y violaciones.
-- UX de seguridad para `drift fix --write` con confirmacion interactiva.
+### 5.2 Output conceptual esperado
 
-Done del bloque:
-- Flujo CI reproducible con comentario unico por PR.
-- Visualizaciones verificables en SVG sobre repos medianos.
-- Confirmacion interactiva implementada para write mode.
+`drift trust` debe sintetizar en un bloque corto y accionable:
 
-### v2 (prioridad: experiencia de editor + extensibilidad)
+| 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 |
 
-Prioridades:
-- Consolidacion de API de plugins y hardening de compatibilidad.
-- Reglas de plugin versionadas y validacion de contrato avanzada.
+### 5.3 Alcance funcional del feature
 
-Criterio de done:
-- Plugins con contrato estable y manejo de errores robusto.
-- Documentacion de versionado para autores de plugins.
+- 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.
 
-### v3 (fundations completadas en v1.2.0)
+Importante: en este documento, `drift trust` se define como **scope de producto**; su implementacion tecnica se planifica por etapas.
 
-Prioridades cerradas:
-- Base de datos local de snapshots para cloud MVP.
-- Ingestion de reportes en storage local SaaS-like.
-- Summary de uso/threshold y dashboard HTML inicial.
-- Guardrails de fase gratuita por workspace + politica free-until-7500.
+---
 
-Siguiente incremento (v3.x):
-- Auth real multi-tenant, permisos por equipo y backend remoto persistente.
-- Activacion de billing cuando el umbral de 7.500 usuarios se cumpla.
+## 6. Scope de producto: Core vs Premium
 
-## 6.1) Estrategia de monetizacion (aprobada)
+### 6.1 Drift Core (base abierta y utilizable)
 
-- Fase gratuita: Drift SaaS gratis hasta alcanzar 7.500 usuarios registrados.
-- Trigger de monetizacion: al alcanzar 7.500 usuarios, activar planes pagos para nuevos usuarios y definir politica de migracion para cohortes gratuitas.
-- Objetivo: priorizar adopcion y proof-of-value temprano sin friccion comercial inicial.
-- Guardrails durante fase gratuita:
-  - Limites tecnicos por workspace (runs/mes, retencion de historial, repositorios activos).
-  - Instrumentacion de uso desde el dia 1 para evitar abuso y medir unit economics.
-  - Feature flags de pricing listas antes del trigger para evitar corte abrupto.
+| 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 |
 
-## 7) Fuera de alcance actual
+### 6.2 Drift Premium (valor para equipos)
 
-- Soporte multi-lenguaje completo fuera de TypeScript/JS.
-- Autofix de reglas de alto riesgo sin confirmacion explicita.
-- Integraciones propietarias cerradas sin API estable.
+| 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 |
 
-## 8) KPIs de exito
+Nota: Premium define direccion comercial; la activacion concreta depende del roadmap de producto y capacidad operativa.
 
-- 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 configurables por equipo.
+---
 
-## 9) Dependencias y riesgos
+## 7. Pricing inicial y propuesta comercial
 
-- Performance en repos grandes (AST + cross-file).
-- Calidad de senial en `ai_likelihood` (falsos positivos/negativos).
-- Variabilidad de entornos CI para publicar comentarios de PR.
-- Evolucion de API de plugins sin romper backward compatibility.
+### 7.1 Planes
 
-## 10) Definition of Done por release
+| 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 |
 
-Checklist minimo por release:
+### 7.2 Hipotesis de monetizacion
 
-- [ ] Scope del release cerrado y trazable a este PRD.
-- [ ] Comandos/flujo documentados con ejemplos reales.
-- [ ] Tests de regresion en paths principales y casos borde.
-- [ ] Salidas CLI/JSON/AI estables para automatizacion.
-- [ ] Criterios de aceptacion del bloque marcados como cumplidos o movidos a pendiente.
-- [ ] Riesgos y tradeoffs explicitados en notas de release.
+- 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.

package/docs/trust-core-release-checklist.md

@@ -0,0 +1,55 @@
+# Trust Core Tonight - Release Checklist
+
+Use this checklist before releasing the trust-core milestone.
+
+## 1) Local validation
+
+- [x] `npm ci`
+- [x] `npm test`
+- [x] `npx --no-install tsx ./src/cli.ts trust . --base origin/master --markdown`
+- [x] `npx --no-install tsx ./src/cli.ts trust . --base origin/master --json-output drift-trust.json`
+- [x] `npx --no-install tsx ./src/cli.ts trust-gate drift-trust.json --min-trust 40 --max-risk HIGH`
+- [x] `npx --no-install tsx ./src/cli.ts review --base origin/master --comment`
+
+## 2) CI workflow validation
+
+- [x] Open or update a non-fork PR and confirm `.github/workflows/review-pr.yml` runs successfully.
+- [x] Confirm sticky PR comment is updated once (marker: `<!-- drift-review -->`).
+- [x] Confirm PR comment includes both sections in this order: `drift trust` then `drift review`.
+- [x] E2E: `trust-gate` runs from generated `drift-trust.json` in `review-pr` workflow.
+- [x] E2E: `kpi` aggregates over generated trust JSON artifact (`drift-trust-kpi.json`).
+- [x] E2E: `drift-trust-json-pr-<PR_NUMBER>-run-<RUN_ATTEMPT>` artifact now bundles:
+  - `drift-trust.json`
+  - `drift-trust-gate.txt`
+  - `drift-trust-kpi.json`
+- [x] Confirm step summary shows trust KPI values: trust score, merge risk, new issues, resolved issues.
+- [x] E2E: step summary includes aggregate KPI block (matched/parsed/malformed, PR samples, avg trust, high-risk ratio).
+
+Smoke PR runbook:
+
+- [x] Create a short-lived branch (for example `chore/trust-ci-smoke`) with a docs-only change.
+- [x] Open a PR against `master` and wait for `review-pr` workflow to complete.
+- [x] Verify gate behavior and comment rendering, then close or merge the PR.
+- [x] Delete the short-lived branch after validation.
+
+## 3) Gate behavior acceptance
+
+Default trust gate for this milestone:
+
+- `--min-trust 40`
+- `--max-risk HIGH`
+
+Checks:
+
+- [x] PR fails when trust score is below 40.
+- [x] PR fails when merge risk is `CRITICAL`.
+- [x] PR passes when trust score is 40+ and merge risk is `LOW`, `MEDIUM`, or `HIGH`.
+
+Calibration evidence from docs-only smoke runs: trust score 49 (PR #11), 46 (PR #12), 41 (PR #13). Gate floor set to 40 to avoid false negatives while still blocking `CRITICAL` risk.
+
+## 4) Narrative and docs acceptance
+
+- [x] `README.md` positions drift as an AI Code Audit CLI for merge trust in AI-assisted PRs.
+- [x] `package.json` description matches the same positioning.
+- [x] `src/cli.ts` program description matches the same positioning.
+- [x] `ROADMAP.md` no longer contradicts PRD on core vs premium direction.