@rigour-labs/core 4.3.3 → 4.3.5

package/dist/inference/cloud-provider.js

@@ -2,13 +2,13 @@
 const DEFAULT_MODELS = {
     claude: 'claude-opus-4-6',
     anthropic: 'claude-sonnet-4-6',
-    openai: 'gpt-4o-mini',
-    gemini: 'gemini-3-flash',
-    groq: 'llama-3.1-70b-versatile',
+    openai: 'gpt-5-mini',
+    gemini: 'gemini-2.5-flash',
+    groq: 'llama-3.3-70b-versatile',
     mistral: 'mistral-large-latest',
-    together: 'meta-llama/Llama-3.1-70B-Instruct-Turbo',
-    fireworks: 'accounts/fireworks/models/llama-v3p1-70b-instruct',
-    deepseek: 'deepseek-coder',
+    together: 'meta-llama/Llama-4-Maverick-17B-128E-Instruct-FP8',
+    fireworks: 'accounts/fireworks/models/llama-v3p3-70b-instruct',
+    deepseek: 'deepseek-v4',
     perplexity: 'llama-3.1-sonar-large-128k-online',
     ollama: 'qwen2.5-coder:7b',
     lmstudio: 'qwen2.5-coder-7b-instruct',

package/dist/inference/model-manager.d.ts

@@ -13,9 +13,17 @@ export declare function getModelPath(tier: ModelTier): string;
  * Get model info for a tier.
  */
 export declare function getModelInfo(tier: ModelTier): ModelInfo;
+/**
+ * Check HuggingFace for a newer model version (like antivirus signature updates).
+ * Reads latest_version.json from the RLAIF dataset repo. Non-blocking — if the
+ * check fails (offline, HF down), we silently use the cached/bundled version.
+ *
+ * Results are cached locally for 24 hours to avoid hammering HF on every run.
+ */
+export declare function checkForUpdates(onProgress?: (message: string, percent?: number) => void): Promise<string>;
 /**
  * Download a model from HuggingFace CDN.
- * Tries fine-tuned model first, falls back to stock Qwen if unavailable.
+ * Checks for updates first, then tries fine-tuned model, falls back to stock Qwen.
  */
 export declare function downloadModel(tier: ModelTier, onProgress?: (message: string, percent?: number) => void): Promise<string>;
 /**

package/dist/inference/model-manager.js

@@ -6,8 +6,11 @@ import path from 'path';
 import fs from 'fs-extra';
 import { createHash } from 'crypto';
 import { RIGOUR_DIR } from '../storage/db.js';
-import { MODELS, FALLBACK_MODELS } from './types.js';
+import { MODELS, FALLBACK_MODELS, VERSION_CHECK_URL, BUNDLED_MODEL_VERSION, updateModelVersion } from './types.js';
 const MODELS_DIR = path.join(RIGOUR_DIR, 'models');
+const VERSION_CACHE_PATH = path.join(MODELS_DIR, '.latest_version.json');
+const VERSION_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // Check once per day
+const VERSION_CHECK_TIMEOUT_MS = 5000; // 5s timeout — don't block startup
 const SHA256_RE = /^[a-f0-9]{64}$/i;
 function getModelMetadataPath(filename) {
     return path.join(MODELS_DIR, filename + '.meta.json');
@@ -173,12 +176,66 @@ async function downloadFromUrl(tier, model, onProgress) {
         throw error;
     }
 }
+/**
+ * Check HuggingFace for a newer model version (like antivirus signature updates).
+ * Reads latest_version.json from the RLAIF dataset repo. Non-blocking — if the
+ * check fails (offline, HF down), we silently use the cached/bundled version.
+ *
+ * Results are cached locally for 24 hours to avoid hammering HF on every run.
+ */
+export async function checkForUpdates(onProgress) {
+    fs.ensureDirSync(MODELS_DIR);
+    // Check local version cache first — avoid network on every run
+    try {
+        if (await fs.pathExists(VERSION_CACHE_PATH)) {
+            const cached = await fs.readJson(VERSION_CACHE_PATH);
+            const age = Date.now() - new Date(cached.checkedAt).getTime();
+            if (age < VERSION_CHECK_INTERVAL_MS && cached.version) {
+                const v = String(cached.version);
+                updateModelVersion(v);
+                return v;
+            }
+        }
+    }
+    catch {
+        // Corrupted cache — proceed to network check
+    }
+    // Fetch latest version from HuggingFace (with timeout)
+    try {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), VERSION_CHECK_TIMEOUT_MS);
+        const response = await fetch(VERSION_CHECK_URL, { signal: controller.signal });
+        clearTimeout(timeout);
+        if (response.ok) {
+            const data = await response.json();
+            const latestVersion = String(data.version || BUNDLED_MODEL_VERSION);
+            // Cache the result locally
+            await fs.writeJson(VERSION_CACHE_PATH, {
+                version: latestVersion,
+                checkedAt: new Date().toISOString(),
+                source: 'huggingface',
+            }, { spaces: 2 }).catch(() => { });
+            // Update in-memory model definitions
+            updateModelVersion(latestVersion);
+            if (latestVersion !== BUNDLED_MODEL_VERSION) {
+                onProgress?.(`Model update available: v${latestVersion}`, 0);
+            }
+            return latestVersion;
+        }
+    }
+    catch {
+        // Offline / HF down / timeout — use bundled version silently
+    }
+    return BUNDLED_MODEL_VERSION;
+}
 /**
  * Download a model from HuggingFace CDN.
- * Tries fine-tuned model first, falls back to stock Qwen if unavailable.
+ * Checks for updates first, then tries fine-tuned model, falls back to stock Qwen.
  */
 export async function downloadModel(tier, onProgress) {
     fs.ensureDirSync(MODELS_DIR);
+    // Check for newer model version (non-blocking, cached 24h)
+    await checkForUpdates(onProgress);
     if (await isModelCached(tier)) {
         onProgress?.(`Model ${MODELS[tier].name} already cached`, 100);
         return getModelPath(tier);

package/dist/inference/types.d.ts

@@ -62,7 +62,7 @@ export interface DeepAnalysisResult {
  * Available model tiers.
  *
  * - deep: Qwen2.5-Coder-1.5B fine-tuned — full power, company-hosted
- * - lite: Qwen3.5-0.8B fine-tuned — lightweight, ships as default CLI sidecar
+ * - lite: Qwen2.5-Coder-0.5B fine-tuned — lightweight, ships as default CLI sidecar
  * - legacy: Qwen2.5-Coder-0.5B fine-tuned — previous default, reproducibility
  */
 export type ModelTier = 'deep' | 'lite' | 'legacy';
@@ -78,13 +78,24 @@ export interface ModelInfo {
     sizeHuman: string;
 }
 /**
- * Model version — bump when new fine-tuned GGUF is published.
- * The RLAIF pipeline uploads new models to HuggingFace, and
- * model-manager checks this version to auto-update.
+ * Minimum bundled model version — used as fallback when the auto-update
+ * check fails (offline, HF down, first run). The RLAIF training pipeline
+ * publishes new versions to HuggingFace and updates latest_version.json.
+ * At startup, model-manager checks HF for the latest version and downloads
+ * it automatically (like antivirus signature updates).
  */
-export declare const MODEL_VERSION = "1";
-/** All supported model definitions */
+export declare const BUNDLED_MODEL_VERSION = "1";
+/** HuggingFace dataset repo where latest_version.json lives */
+export declare const VERSION_CHECK_URL = "https://huggingface.co/datasets/rigour-labs/rigour-rlaif-data/resolve/main/latest_version.json";
+/** Build model info for a given tier and version */
+export declare function buildModelInfo(tier: ModelTier, version: string): ModelInfo;
+/** Current model definitions — initialized with bundled version, updated at runtime */
 export declare const MODELS: Record<ModelTier, ModelInfo>;
+/**
+ * Update MODELS in-place to point to a newer version.
+ * Called by model-manager after checking latest_version.json.
+ */
+export declare function updateModelVersion(version: string): void;
 /**
  * Fallback stock models — used when fine-tuned model is not yet
  * available on HuggingFace (initial setup / first-time users).

package/dist/inference/types.js

@@ -1,36 +1,46 @@
 /**
- * Model version — bump when new fine-tuned GGUF is published.
- * The RLAIF pipeline uploads new models to HuggingFace, and
- * model-manager checks this version to auto-update.
+ * Minimum bundled model version — used as fallback when the auto-update
+ * check fails (offline, HF down, first run). The RLAIF training pipeline
+ * publishes new versions to HuggingFace and updates latest_version.json.
+ * At startup, model-manager checks HF for the latest version and downloads
+ * it automatically (like antivirus signature updates).
  */
-export const MODEL_VERSION = '1';
-/** All supported model definitions */
+export const BUNDLED_MODEL_VERSION = '1';
+/** HuggingFace dataset repo where latest_version.json lives */
+export const VERSION_CHECK_URL = 'https://huggingface.co/datasets/rigour-labs/rigour-rlaif-data/resolve/main/latest_version.json';
+/** Build model info for a given tier and version */
+export function buildModelInfo(tier, version) {
+    const meta = {
+        deep: { base: 'Qwen2.5-Coder-1.5B', size: 900_000_000, sizeH: '900MB' },
+        lite: { base: 'Qwen2.5-Coder-0.5B', size: 500_000_000, sizeH: '500MB' },
+        legacy: { base: 'Qwen2.5-Coder-0.5B', size: 350_000_000, sizeH: '350MB' },
+    };
+    const m = meta[tier];
+    return {
+        tier,
+        name: `Rigour-${tier[0].toUpperCase() + tier.slice(1)}-v${version} (${m.base} fine-tuned)`,
+        filename: `rigour-${tier}-v${version}-q4_k_m.gguf`,
+        url: `https://huggingface.co/rigour-labs/rigour-${tier}-v${version}-gguf/resolve/main/rigour-${tier}-v${version}-q4_k_m.gguf`,
+        sizeBytes: m.size,
+        sizeHuman: m.sizeH,
+    };
+}
+/** Current model definitions — initialized with bundled version, updated at runtime */
 export const MODELS = {
-    deep: {
-        tier: 'deep',
-        name: 'Rigour-Deep-v1 (Qwen2.5-Coder-1.5B fine-tuned)',
-        filename: `rigour-deep-v${MODEL_VERSION}-q4_k_m.gguf`,
-        url: `https://huggingface.co/rigour-labs/rigour-deep-v1-gguf/resolve/main/rigour-deep-v${MODEL_VERSION}-q4_k_m.gguf`,
-        sizeBytes: 900_000_000,
-        sizeHuman: '900MB',
-    },
-    lite: {
-        tier: 'lite',
-        name: 'Rigour-Lite-v1 (Qwen3.5-0.8B fine-tuned)',
-        filename: `rigour-lite-v${MODEL_VERSION}-q4_k_m.gguf`,
-        url: `https://huggingface.co/rigour-labs/rigour-lite-v1-gguf/resolve/main/rigour-lite-v${MODEL_VERSION}-q4_k_m.gguf`,
-        sizeBytes: 500_000_000,
-        sizeHuman: '500MB',
-    },
-    legacy: {
-        tier: 'legacy',
-        name: 'Rigour-Legacy-v1 (Qwen2.5-Coder-0.5B fine-tuned)',
-        filename: `rigour-legacy-v${MODEL_VERSION}-q4_k_m.gguf`,
-        url: `https://huggingface.co/rigour-labs/rigour-legacy-v1-gguf/resolve/main/rigour-legacy-v${MODEL_VERSION}-q4_k_m.gguf`,
-        sizeBytes: 350_000_000,
-        sizeHuman: '350MB',
-    },
+    deep: buildModelInfo('deep', BUNDLED_MODEL_VERSION),
+    lite: buildModelInfo('lite', BUNDLED_MODEL_VERSION),
+    legacy: buildModelInfo('legacy', BUNDLED_MODEL_VERSION),
 };
+/**
+ * Update MODELS in-place to point to a newer version.
+ * Called by model-manager after checking latest_version.json.
+ */
+export function updateModelVersion(version) {
+    for (const tier of ['deep', 'lite', 'legacy']) {
+        const updated = buildModelInfo(tier, version);
+        MODELS[tier] = updated;
+    }
+}
 /**
  * Fallback stock models — used when fine-tuned model is not yet
  * available on HuggingFace (initial setup / first-time users).
@@ -46,9 +56,9 @@ export const FALLBACK_MODELS = {
     },
     lite: {
         tier: 'lite',
-        name: 'Qwen3.5-0.8B (stock)',
-        filename: 'qwen3.5-0.8b-q4_k_m.gguf',
-        url: 'https://huggingface.co/Qwen/Qwen3.5-0.8B-GGUF/resolve/main/qwen3.5-0.8b-q4_k_m.gguf',
+        name: 'Qwen2.5-Coder-0.5B-Instruct (stock)',
+        filename: 'qwen2.5-coder-0.5b-instruct-q4_k_m.gguf',
+        url: 'https://huggingface.co/Qwen/Qwen2.5-Coder-0.5B-Instruct-GGUF/resolve/main/qwen2.5-coder-0.5b-instruct-q4_k_m.gguf',
         sizeBytes: 500_000_000,
         sizeHuman: '500MB',
     },

package/dist/services/fix-packet-service.js

@@ -1,8 +1,9 @@
 import { FixPacketV2Schema } from '../types/fix-packet.js';
 export class FixPacketService {
     generate(report, config) {
-        // Sort violations: critical first, then high, medium, low, info
         const severityOrder = { critical: 0, high: 1, medium: 2, low: 3, info: 4 };
+        // Deduplicate failed gate IDs
+        const failedGates = [...new Set(report.failures.map(f => f.id))];
         const violations = report.failures
             .map(f => ({
             id: f.id,
@@ -12,19 +13,32 @@ export class FixPacketService {
             title: f.title,
             details: f.details,
             files: f.files,
+            locations: buildLocations(f),
             hint: f.hint,
-            instructions: f.hint ? [f.hint] : [],
+            instructions: buildInstructions(f),
             metrics: f.metrics,
         }))
             .sort((a, b) => (severityOrder[a.severity] ?? 2) - (severityOrder[b.severity] ?? 2));
+        // Build verification commands from config.commands
+        const verification = buildVerification(config);
+        // Build allowed scope from violation files (what the agent should touch)
+        const violationFiles = violations.flatMap(v => v.files || []);
+        const uniqueFiles = [...new Set(violationFiles.map(f => {
+                // Strip metadata like "(600 lines)" from file paths
+                const clean = f.replace(/\s*\(.*?\)\s*$/, '').trim();
+                return clean;
+            }))];
         const packet = {
-            version: 2,
+            version: 3,
             goal: "Achieve PASS state by resolving all listed engineering violations.",
+            failed_gates: failedGates,
             violations,
+            verification,
             constraints: {
                 paradigm: config.paradigm,
                 protected_paths: config.gates.safety?.protected_paths,
                 do_not_touch: config.gates.safety?.protected_paths,
+                allowed_scope: uniqueFiles.length > 0 ? uniqueFiles : undefined,
                 max_files_changed: config.gates.safety?.max_files_changed_per_cycle,
                 no_new_deps: true,
             },
@@ -32,3 +46,86 @@ export class FixPacketService {
         return FixPacketV2Schema.parse(packet);
     }
 }
+/**
+ * Build precise locations from failure's files + line numbers.
+ * If failure has both files[] and line/endLine, create a location per file.
+ * If only files[], locations are file-level (no line numbers).
+ */
+function buildLocations(f) {
+    if (!f.files || f.files.length === 0)
+        return undefined;
+    return f.files.map(file => {
+        const loc = {
+            file: file.replace(/\s*\(.*?\)\s*$/, '').trim(),
+        };
+        // If the failure has line numbers and there's only one file, attach them
+        if (f.files.length === 1) {
+            if (f.line)
+                loc.line = f.line;
+            if (f.endLine)
+                loc.endLine = f.endLine;
+        }
+        return loc;
+    });
+}
+/**
+ * Build step-by-step instructions from the hint and failure context.
+ */
+function buildInstructions(f) {
+    const steps = [];
+    if (f.hint)
+        steps.push(f.hint);
+    // Add gate-specific guidance
+    switch (f.id) {
+        case 'file-size':
+            steps.push('Break the file into smaller modules following Single Responsibility Principle');
+            break;
+        case 'hallucinated-imports':
+            steps.push('Remove or replace the non-existent import with a real package');
+            break;
+        case 'phantom-apis':
+            steps.push('Check the actual API surface of the module and use a real method');
+            break;
+        case 'forbid-todos':
+            steps.push('Resolve the TODO/FIXME comment or remove it if no longer relevant');
+            break;
+        case 'security-patterns':
+            steps.push('Apply the security fix described above. Do NOT suppress the warning.');
+            break;
+        case 'promise-safety':
+            steps.push('Add proper error handling (try/catch or .catch()) to async operations');
+            break;
+        case 'deprecated-apis':
+            steps.push('Replace deprecated API usage with the recommended modern alternative');
+            break;
+        case 'duplication-drift':
+            steps.push('Extract the duplicated logic into a shared utility or module');
+            break;
+        case 'inconsistent-error-handling':
+            steps.push('Align error handling strategy across the module');
+            break;
+    }
+    return steps.length > 0 ? steps : [];
+}
+/**
+ * Build verification block from config.commands.
+ * These are the commands the agent MUST run after fixing to prove the fix works.
+ */
+function buildVerification(config) {
+    const commands = [];
+    if (config.commands?.typecheck) {
+        commands.push({ cmd: config.commands.typecheck, purpose: 'Ensure no type errors after changes' });
+    }
+    if (config.commands?.lint) {
+        commands.push({ cmd: config.commands.lint, purpose: 'Ensure no lint violations' });
+    }
+    if (config.commands?.test) {
+        commands.push({ cmd: config.commands.test, purpose: 'Ensure all tests pass' });
+    }
+    if (config.commands?.format) {
+        commands.push({ cmd: config.commands.format, purpose: 'Ensure code formatting is correct' });
+    }
+    // Always end with rigour check
+    commands.push({ cmd: 'rigour_check', purpose: 'Re-run all quality gates to confirm PASS' });
+    return { commands, gate_command: 'rigour_check' };
+}

package/dist/types/fix-packet.d.ts

@@ -1,11 +1,91 @@
 import { z } from 'zod';
 /**
- * Fix Packet v2 Schema
- * Designed for high-fidelity communication with AI agents during the refinement loop.
+ * Fix Packet v3 Schema
+ *
+ * Designed for high-fidelity, machine-readable communication with AI agents.
+ * Every violation tells the agent exactly: who failed, which files, what rule,
+ * where in the file, and what must pass to verify the fix.
+ *
+ * v3 changes from v2:
+ *   - Violations now include `location` (file + line range) for precise targeting
+ *   - Top-level `verification` block: commands the agent MUST run after fixing
+ *   - `allowed_scope`: explicit list of file globs the agent IS allowed to edit
+ *   - `failed_gates`: summary list of gate IDs that failed (quick machine check)
  */
+declare const ViolationLocationSchema: z.ZodObject<{
+    file: z.ZodString;
+    line: z.ZodOptional<z.ZodNumber>;
+    endLine: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    file: string;
+    line?: number | undefined;
+    endLine?: number | undefined;
+}, {
+    file: string;
+    line?: number | undefined;
+    endLine?: number | undefined;
+}>;
+declare const ViolationSchema: z.ZodObject<{
+    id: z.ZodString;
+    gate: z.ZodString;
+    severity: z.ZodDefault<z.ZodEnum<["info", "low", "medium", "high", "critical"]>>;
+    category: z.ZodOptional<z.ZodString>;
+    title: z.ZodString;
+    details: z.ZodString;
+    files: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    locations: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        file: z.ZodString;
+        line: z.ZodOptional<z.ZodNumber>;
+        endLine: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        file: string;
+        line?: number | undefined;
+        endLine?: number | undefined;
+    }, {
+        file: string;
+        line?: number | undefined;
+        endLine?: number | undefined;
+    }>, "many">>;
+    hint: z.ZodOptional<z.ZodString>;
+    instructions: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    metrics: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    title: string;
+    details: string;
+    severity: "critical" | "high" | "medium" | "low" | "info";
+    gate: string;
+    files?: string[] | undefined;
+    hint?: string | undefined;
+    category?: string | undefined;
+    locations?: {
+        file: string;
+        line?: number | undefined;
+        endLine?: number | undefined;
+    }[] | undefined;
+    instructions?: string[] | undefined;
+    metrics?: Record<string, any> | undefined;
+}, {
+    id: string;
+    title: string;
+    details: string;
+    gate: string;
+    severity?: "critical" | "high" | "medium" | "low" | "info" | undefined;
+    files?: string[] | undefined;
+    hint?: string | undefined;
+    category?: string | undefined;
+    locations?: {
+        file: string;
+        line?: number | undefined;
+        endLine?: number | undefined;
+    }[] | undefined;
+    instructions?: string[] | undefined;
+    metrics?: Record<string, any> | undefined;
+}>;
 export declare const FixPacketV2Schema: z.ZodObject<{
-    version: z.ZodLiteral<2>;
+    version: z.ZodLiteral<3>;
     goal: z.ZodDefault<z.ZodString>;
+    failed_gates: z.ZodArray<z.ZodString, "many">;
     violations: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         gate: z.ZodString;
@@ -14,6 +94,19 @@ export declare const FixPacketV2Schema: z.ZodObject<{
         title: z.ZodString;
         details: z.ZodString;
         files: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        locations: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            file: z.ZodString;
+            line: z.ZodOptional<z.ZodNumber>;
+            endLine: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            file: string;
+            line?: number | undefined;
+            endLine?: number | undefined;
+        }, {
+            file: string;
+            line?: number | undefined;
+            endLine?: number | undefined;
+        }>, "many">>;
         hint: z.ZodOptional<z.ZodString>;
         instructions: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
         metrics: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
@@ -26,6 +119,11 @@ export declare const FixPacketV2Schema: z.ZodObject<{
         files?: string[] | undefined;
         hint?: string | undefined;
         category?: string | undefined;
+        locations?: {
+            file: string;
+            line?: number | undefined;
+            endLine?: number | undefined;
+        }[] | undefined;
         instructions?: string[] | undefined;
         metrics?: Record<string, any> | undefined;
     }, {
@@ -37,12 +135,43 @@ export declare const FixPacketV2Schema: z.ZodObject<{
         files?: string[] | undefined;
         hint?: string | undefined;
         category?: string | undefined;
+        locations?: {
+            file: string;
+            line?: number | undefined;
+            endLine?: number | undefined;
+        }[] | undefined;
         instructions?: string[] | undefined;
         metrics?: Record<string, any> | undefined;
     }>, "many">;
+    verification: z.ZodOptional<z.ZodObject<{
+        commands: z.ZodArray<z.ZodObject<{
+            cmd: z.ZodString;
+            purpose: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            cmd: string;
+            purpose: string;
+        }, {
+            cmd: string;
+            purpose: string;
+        }>, "many">;
+        gate_command: z.ZodDefault<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        commands: {
+            cmd: string;
+            purpose: string;
+        }[];
+        gate_command: string;
+    }, {
+        commands: {
+            cmd: string;
+            purpose: string;
+        }[];
+        gate_command?: string | undefined;
+    }>>;
     constraints: z.ZodDefault<z.ZodOptional<z.ZodObject<{
         protected_paths: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
         do_not_touch: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        allowed_scope: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
         max_files_changed: z.ZodOptional<z.ZodNumber>;
         no_new_deps: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
         allowed_dependencies: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
@@ -52,19 +181,22 @@ export declare const FixPacketV2Schema: z.ZodObject<{
         protected_paths?: string[] | undefined;
         paradigm?: string | undefined;
         do_not_touch?: string[] | undefined;
+        allowed_scope?: string[] | undefined;
         max_files_changed?: number | undefined;
         allowed_dependencies?: string[] | undefined;
     }, {
         protected_paths?: string[] | undefined;
         paradigm?: string | undefined;
         do_not_touch?: string[] | undefined;
+        allowed_scope?: string[] | undefined;
         max_files_changed?: number | undefined;
         no_new_deps?: boolean | undefined;
         allowed_dependencies?: string[] | undefined;
     }>>>;
 }, "strip", z.ZodTypeAny, {
-    version: 2;
+    version: 3;
     goal: string;
+    failed_gates: string[];
     violations: {
         id: string;
         title: string;
@@ -74,6 +206,11 @@ export declare const FixPacketV2Schema: z.ZodObject<{
         files?: string[] | undefined;
         hint?: string | undefined;
         category?: string | undefined;
+        locations?: {
+            file: string;
+            line?: number | undefined;
+            endLine?: number | undefined;
+        }[] | undefined;
         instructions?: string[] | undefined;
         metrics?: Record<string, any> | undefined;
     }[];
@@ -82,11 +219,20 @@ export declare const FixPacketV2Schema: z.ZodObject<{
         protected_paths?: string[] | undefined;
         paradigm?: string | undefined;
         do_not_touch?: string[] | undefined;
+        allowed_scope?: string[] | undefined;
         max_files_changed?: number | undefined;
         allowed_dependencies?: string[] | undefined;
     };
+    verification?: {
+        commands: {
+            cmd: string;
+            purpose: string;
+        }[];
+        gate_command: string;
+    } | undefined;
 }, {
-    version: 2;
+    version: 3;
+    failed_gates: string[];
     violations: {
         id: string;
         title: string;
@@ -96,17 +242,33 @@ export declare const FixPacketV2Schema: z.ZodObject<{
         files?: string[] | undefined;
         hint?: string | undefined;
         category?: string | undefined;
+        locations?: {
+            file: string;
+            line?: number | undefined;
+            endLine?: number | undefined;
+        }[] | undefined;
         instructions?: string[] | undefined;
         metrics?: Record<string, any> | undefined;
     }[];
     goal?: string | undefined;
+    verification?: {
+        commands: {
+            cmd: string;
+            purpose: string;
+        }[];
+        gate_command?: string | undefined;
+    } | undefined;
     constraints?: {
         protected_paths?: string[] | undefined;
         paradigm?: string | undefined;
         do_not_touch?: string[] | undefined;
+        allowed_scope?: string[] | undefined;
         max_files_changed?: number | undefined;
         no_new_deps?: boolean | undefined;
         allowed_dependencies?: string[] | undefined;
     } | undefined;
 }>;
 export type FixPacketV2 = z.infer<typeof FixPacketV2Schema>;
+export type Violation = z.infer<typeof ViolationSchema>;
+export type ViolationLocation = z.infer<typeof ViolationLocationSchema>;
+export {};

package/dist/types/fix-packet.js

@@ -1,29 +1,55 @@
 import { z } from 'zod';
 /**
- * Fix Packet v2 Schema
- * Designed for high-fidelity communication with AI agents during the refinement loop.
+ * Fix Packet v3 Schema
+ *
+ * Designed for high-fidelity, machine-readable communication with AI agents.
+ * Every violation tells the agent exactly: who failed, which files, what rule,
+ * where in the file, and what must pass to verify the fix.
+ *
+ * v3 changes from v2:
+ *   - Violations now include `location` (file + line range) for precise targeting
+ *   - Top-level `verification` block: commands the agent MUST run after fixing
+ *   - `allowed_scope`: explicit list of file globs the agent IS allowed to edit
+ *   - `failed_gates`: summary list of gate IDs that failed (quick machine check)
  */
+const ViolationLocationSchema = z.object({
+    file: z.string(),
+    line: z.number().optional(),
+    endLine: z.number().optional(),
+});
+const ViolationSchema = z.object({
+    id: z.string(), // Gate ID, e.g. "file-size"
+    gate: z.string(), // Same as id (kept for backwards compat)
+    severity: z.enum(['info', 'low', 'medium', 'high', 'critical']).default('medium'),
+    category: z.string().optional(), // Provenance: "traditional", "ai-drift", "security", etc.
+    title: z.string(),
+    details: z.string(),
+    files: z.array(z.string()).optional(),
+    locations: z.array(ViolationLocationSchema).optional(), // Precise file + line targets
+    hint: z.string().optional(),
+    instructions: z.array(z.string()).optional(),
+    metrics: z.record(z.any()).optional(), // e.g. { complexity: 15, threshold: 10 }
+});
+const VerificationSchema = z.object({
+    commands: z.array(z.object({
+        cmd: z.string(), // e.g. "npm run typecheck"
+        purpose: z.string(), // e.g. "Ensure no TypeScript errors"
+    })),
+    gate_command: z.string().default('rigour_check'), // The rigour tool to re-run
+});
 export const FixPacketV2Schema = z.object({
-    version: z.literal(2),
+    version: z.literal(3),
     goal: z.string().default('Achieve PASS state for all quality gates'),
-    violations: z.array(z.object({
-        id: z.string(),
-        gate: z.string(),
-        severity: z.enum(['info', 'low', 'medium', 'high', 'critical']).default('medium'),
-        category: z.string().optional(),
-        title: z.string(),
-        details: z.string(),
-        files: z.array(z.string()).optional(),
-        hint: z.string().optional(),
-        instructions: z.array(z.string()).optional(), // Step-by-step fix instructions
-        metrics: z.record(z.any()).optional(), // e.g., { complexity: 15, max: 10 }
-    })),
+    failed_gates: z.array(z.string()), // Quick list: ["file-size", "hallucinated-imports"]
+    violations: z.array(ViolationSchema),
+    verification: VerificationSchema.optional(),
     constraints: z.object({
         protected_paths: z.array(z.string()).optional(),
-        do_not_touch: z.array(z.string()).optional(), // Alias for protected_paths
+        do_not_touch: z.array(z.string()).optional(),
+        allowed_scope: z.array(z.string()).optional(), // Globs the agent IS allowed to edit
         max_files_changed: z.number().optional(),
         no_new_deps: z.boolean().optional().default(true),
         allowed_dependencies: z.array(z.string()).optional(),
-        paradigm: z.string().optional(), // 'oop', 'functional'
+        paradigm: z.string().optional(),
     }).optional().default({}),
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rigour-labs/core",
-  "version": "4.3.3",
+  "version": "4.3.5",
   "description": "Deterministic quality gate engine for AI-generated code. AST analysis, drift detection, and Fix Packet generation across TypeScript, JavaScript, Python, Go, Ruby, and C#.",
   "license": "MIT",
   "homepage": "https://rigour.run",
@@ -59,11 +59,11 @@
     "@xenova/transformers": "^2.17.2",
     "better-sqlite3": "^11.0.0",
     "openai": "^4.104.0",
-    "@rigour-labs/brain-darwin-arm64": "4.3.3",
-    "@rigour-labs/brain-linux-arm64": "4.3.3",
-    "@rigour-labs/brain-darwin-x64": "4.3.3",
-    "@rigour-labs/brain-win-x64": "4.3.3",
-    "@rigour-labs/brain-linux-x64": "4.3.3"
+    "@rigour-labs/brain-darwin-arm64": "4.3.5",
+    "@rigour-labs/brain-darwin-x64": "4.3.5",
+    "@rigour-labs/brain-win-x64": "4.3.5",
+    "@rigour-labs/brain-linux-x64": "4.3.5",
+    "@rigour-labs/brain-linux-arm64": "4.3.5"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.12",