agentic-qe 3.7.22 → 3.8.0

package/dist/cli/commands/audit.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Agentic QE v3 - Audit Command
+ *
+ * Verifies the witness chain audit trail integrity.
+ * Shows chain length, integrity status, and last receipt hash.
+ *
+ * Usage: aqe audit verify [--format json|text]
+ *
+ * @module cli/commands/audit
+ * @see ADR-083-coherence-gated-agent-actions.md
+ */
+import { Command } from 'commander';
+import { type ChainVerificationResult } from '../../governance/witness-chain.js';
+import type { CLIContext } from '../handlers/interfaces.js';
+/**
+ * Verification output for JSON format.
+ */
+export interface AuditVerifyOutput {
+    featureEnabled: boolean;
+    chainLength: number;
+    integrity: boolean;
+    brokenAt: number;
+    lastHash: string;
+    message: string;
+}
+/**
+ * Format verification result as human-readable text.
+ */
+export declare function formatVerificationText(result: ChainVerificationResult, featureEnabled: boolean): string;
+/**
+ * Handle the audit verify command.
+ *
+ * Loads the witness chain from SQLite if available, otherwise creates
+ * a fresh in-memory chain.
+ */
+export declare function handleAuditVerify(options: {
+    format?: 'json' | 'text';
+}): Promise<AuditVerifyOutput>;
+/**
+ * Create the audit command group following the project convention.
+ */
+export declare function createAuditCommand(_context: CLIContext, cleanupAndExit: (code: number) => Promise<never>, _ensureInitialized: () => Promise<boolean>): Command;
+//# sourceMappingURL=audit.d.ts.map

package/dist/cli/commands/audit.js

@@ -0,0 +1,125 @@
+/**
+ * Agentic QE v3 - Audit Command
+ *
+ * Verifies the witness chain audit trail integrity.
+ * Shows chain length, integrity status, and last receipt hash.
+ *
+ * Usage: aqe audit verify [--format json|text]
+ *
+ * @module cli/commands/audit
+ * @see ADR-083-coherence-gated-agent-actions.md
+ */
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { createWitnessChain, createPersistentWitnessChain, createWitnessChainSQLitePersistence, isWitnessChainFeatureEnabled, } from '../../governance/witness-chain.js';
+import { findProjectRoot } from '../../kernel/unified-memory.js';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+/**
+ * Format verification result as human-readable text.
+ */
+export function formatVerificationText(result, featureEnabled) {
+    const lines = [];
+    lines.push(chalk.bold('Witness Chain Audit Verification'));
+    lines.push('');
+    // Feature flag status
+    const flagStatus = featureEnabled
+        ? chalk.green('ENABLED')
+        : chalk.yellow('DISABLED');
+    lines.push(`  Feature Flag: ${flagStatus}`);
+    // Chain length
+    lines.push(`  Chain Length:  ${result.length} receipts`);
+    // Integrity status
+    const integrityStatus = result.valid
+        ? chalk.green('VALID')
+        : chalk.red('BROKEN');
+    lines.push(`  Integrity:    ${integrityStatus}`);
+    // Last hash
+    if (result.length > 0) {
+        lines.push(`  Last Hash:    ${result.lastHash.slice(0, 16)}...`);
+    }
+    // Details
+    if (!result.valid && result.brokenAt >= 0) {
+        lines.push('');
+        lines.push(chalk.red(`  Break detected at index ${result.brokenAt}`));
+        lines.push(chalk.red(`  ${result.message}`));
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+/**
+ * Try to load a SQLite-backed witness chain from the project's unified database.
+ * Returns null if the database is unavailable.
+ */
+function tryLoadPersistentChain() {
+    try {
+        const root = findProjectRoot();
+        const dbPath = path.join(root, '.agentic-qe', 'memory.db');
+        if (!existsSync(dbPath))
+            return null;
+        // Dynamic import to avoid hard dependency on better-sqlite3 at CLI load time
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const Database = require('better-sqlite3');
+        const db = new Database(dbPath);
+        const persistence = createWitnessChainSQLitePersistence(db);
+        const chain = createPersistentWitnessChain(persistence);
+        // Close the DB handle; chain data is now loaded into memory
+        db.close();
+        return chain;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Handle the audit verify command.
+ *
+ * Loads the witness chain from SQLite if available, otherwise creates
+ * a fresh in-memory chain.
+ */
+export async function handleAuditVerify(options) {
+    const featureEnabled = isWitnessChainFeatureEnabled();
+    // Load persisted chain from SQLite if available, else in-memory
+    const chain = tryLoadPersistentChain() ?? createWitnessChain();
+    const result = chain.verifyChain();
+    const output = {
+        featureEnabled,
+        chainLength: result.length,
+        integrity: result.valid,
+        brokenAt: result.brokenAt,
+        lastHash: result.lastHash,
+        message: result.message,
+    };
+    if (options.format === 'json') {
+        console.log(JSON.stringify(output, null, 2));
+    }
+    else {
+        console.log(formatVerificationText(result, featureEnabled));
+    }
+    return output;
+}
+/**
+ * Create the audit command group following the project convention.
+ */
+export function createAuditCommand(_context, cleanupAndExit, _ensureInitialized) {
+    const audit = new Command('audit')
+        .description('Witness chain audit trail management');
+    audit
+        .command('verify')
+        .description('Verify witness chain integrity')
+        .option('-F, --format <format>', 'Output format (json|text)', 'text')
+        .action(async (options) => {
+        try {
+            await handleAuditVerify({
+                format: options.format,
+            });
+            await cleanupAndExit(0);
+        }
+        catch (error) {
+            console.error('Failed to verify witness chain:', error);
+            await cleanupAndExit(1);
+        }
+    });
+    return audit;
+}
+//# sourceMappingURL=audit.js.map

package/dist/cli/commands/learning.js

@@ -18,9 +18,10 @@ import { safeJsonParse } from '../../shared/safe-json.js';
 import { stat, unlink } from 'node:fs/promises';
 import { QE_DOMAIN_LIST } from '../../learning/qe-patterns.js';
 import { createLearningMetricsTracker, } from '../../learning/metrics-tracker.js';
+import { createRegretTracker, } from '../../learning/regret-tracker.js';
 import { openDatabase } from '../../shared/safe-db.js';
 // Extracted helpers
-import { initializeLearningSystem, printJson, printSuccess, printError, printInfo, displayDashboard, getDbPath, compressFile, decompressFile, verifyDatabaseIntegrity, getSchemaVersion, EXPORT_FORMAT_VERSION, DOMAIN_MAPPING, PATTERN_TYPE_MAPPING, } from './learning-helpers.js';
+import { initializeLearningSystem, printJson, printSuccess, printError, printInfo, displayDashboard, getDbPath, compressFile, decompressFile, verifyDatabaseIntegrity, getSchemaVersion, padRight, EXPORT_FORMAT_VERSION, DOMAIN_MAPPING, PATTERN_TYPE_MAPPING, } from './learning-helpers.js';
 // ============================================================================
 // Learning Command
 // ============================================================================
@@ -63,6 +64,7 @@ Examples:
     registerImportMergeCommand(learning);
     registerDreamCommand(learning);
     registerRepairCommand(learning);
+    registerHealthCommand(learning);
     return learning;
 }
 // ============================================================================
@@ -1288,6 +1290,109 @@ function registerRepairCommand(learning) {
     });
 }
 // ============================================================================
+// Subcommand: health (Task 2.4 - Regret Tracking & Learning Health)
+// ============================================================================
+/**
+ * Get trend arrow and label for a growth rate classification
+ */
+function growthRateDisplay(rate) {
+    switch (rate) {
+        case 'sublinear':
+            return { arrow: '\u25B2', label: 'Sublinear (learning)', color: chalk.green };
+        case 'linear':
+            return { arrow: '\u2192', label: 'Linear (stagnating)', color: chalk.yellow };
+        case 'superlinear':
+            return { arrow: '\u25BC', label: 'Superlinear (degrading)', color: chalk.red };
+        case 'insufficient_data':
+        default:
+            return { arrow: '?', label: 'Insufficient data', color: chalk.dim };
+    }
+}
+function registerHealthCommand(learning) {
+    learning
+        .command('health')
+        .description('Display per-domain learning health based on regret tracking')
+        .option('--json', 'Output as JSON')
+        .option('--domain <domain>', 'Filter to a specific domain')
+        .action(async (options) => {
+        try {
+            const projectRoot = findProjectRoot();
+            const dbPath = path.join(projectRoot, '.agentic-qe', 'memory.db');
+            if (!existsSync(dbPath)) {
+                printError('Database not found. Run "aqe init --auto" first.');
+                process.exit(1);
+            }
+            // Build regret data from captured experiences per domain
+            const tracker = createRegretTracker();
+            const db = openDatabase(dbPath, { readonly: true });
+            // Check for captured_experiences table
+            const tableExists = db.prepare(`SELECT name FROM sqlite_master WHERE type='table' AND name='captured_experiences'`).get();
+            if (tableExists) {
+                // Query experiences grouped by domain, ordered by time
+                const domainFilter = options.domain
+                    ? `AND domain = ?` : '';
+                const params = [];
+                if (options.domain)
+                    params.push(options.domain);
+                const rows = db.prepare(`
+            SELECT domain, quality, success, started_at
+            FROM captured_experiences
+            WHERE agent != 'cli-hook'
+              AND domain IS NOT NULL
+              AND domain != ''
+              ${domainFilter}
+            ORDER BY started_at ASC
+          `).all(...params);
+                for (const row of rows) {
+                    const reward = row.quality ?? (row.success ? 1.0 : 0.0);
+                    const optimalReward = 1.0;
+                    tracker.recordDecision(row.domain, reward, optimalReward);
+                }
+            }
+            db.close();
+            const healthSummary = tracker.getHealthSummary();
+            if (options.json) {
+                printJson(healthSummary);
+                process.exit(0);
+            }
+            // Display health dashboard
+            console.log('');
+            console.log(chalk.bold('Learning Health Dashboard:'));
+            if (healthSummary.length === 0) {
+                console.log(chalk.dim('  No domain data available. Run some QE tasks to generate learning data.'));
+                console.log('');
+                process.exit(0);
+            }
+            // Find the longest domain name for alignment
+            const maxDomainLen = Math.max(...healthSummary.map(s => s.domain.length), 20);
+            for (const summary of healthSummary) {
+                const { arrow, label, color } = growthRateDisplay(summary.growthRate);
+                const domainName = padRight(summary.domain + ':', maxDomainLen + 1);
+                const statusStr = color(`${arrow} ${padRight(label, 26)}`);
+                const regretStr = `regret: ${summary.cumulativeRegret.toFixed(1)}`;
+                const decisionsStr = `decisions: ${summary.totalDecisions}`;
+                console.log(`  ${domainName} ${statusStr} ${regretStr}   ${decisionsStr}`);
+            }
+            // Show summary line
+            const stagnating = healthSummary.filter(s => s.stagnating);
+            if (stagnating.length > 0) {
+                console.log('');
+                console.log(chalk.yellow(`  Warning: ${stagnating.length} domain(s) showing stagnation: ${stagnating.map(s => s.domain).join(', ')}`));
+            }
+            const learning = healthSummary.filter(s => s.growthRate === 'sublinear');
+            if (learning.length > 0) {
+                console.log(chalk.green(`  ${learning.length} domain(s) actively learning`));
+            }
+            console.log('');
+            process.exit(0);
+        }
+        catch (error) {
+            printError(`health check failed: ${error instanceof Error ? error.message : 'unknown'}`);
+            process.exit(1);
+        }
+    });
+}
+// ============================================================================
 // Exports
 // ============================================================================
 export { initializeLearningSystem } from './learning-helpers.js';

package/dist/cli/commands/ruvector-commands.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Agentic QE v3 - RuVector CLI Commands
+ * Manage RuVector feature flags and native package status.
+ *
+ * Subcommands:
+ *   status - Show native package availability and flag status
+ *   flags  - List, set, or apply profiles to feature flags
+ */
+import { Command } from 'commander';
+/**
+ * Create the ruvector command group
+ */
+export declare function createRuVectorCommand(): Command;
+export default createRuVectorCommand;
+//# sourceMappingURL=ruvector-commands.d.ts.map

package/dist/cli/commands/ruvector-commands.js

@@ -0,0 +1,271 @@
+/**
+ * Agentic QE v3 - RuVector CLI Commands
+ * Manage RuVector feature flags and native package status.
+ *
+ * Subcommands:
+ *   status - Show native package availability and flag status
+ *   flags  - List, set, or apply profiles to feature flags
+ */
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { getRuVectorFeatureFlags, setRuVectorFeatureFlags, DEFAULT_FEATURE_FLAGS, } from '../../integrations/ruvector/feature-flags.js';
+// ============================================================================
+// Constants
+// ============================================================================
+const NATIVE_PACKAGES = [
+    {
+        name: '@ruvector/router',
+        flag: 'useNativeHNSW',
+        fallback: 'ProgressiveHnswBackend',
+    },
+    {
+        name: 'prime-radiant-advanced-wasm',
+        flag: 'useCoherenceGate',
+        fallback: 'Word-frequency heuristics',
+    },
+    {
+        name: '@ruvector/sona',
+        flag: 'useSONAThreeLoop',
+        fallback: 'TypeScript MicroLoRA/EWC++',
+    },
+];
+const FLAG_DESCRIPTIONS = {
+    useQESONA: 'Self-Optimizing Neural Architecture',
+    useQEFlashAttention: 'SIMD-accelerated attention computation',
+    useQEGNNIndex: 'Differentiable search and HNSW indexing',
+    logMigrationMetrics: 'Log migration metrics during rollout',
+    useNativeHNSW: 'Rust-based HNSW backend (@ruvector/router VectorDb)',
+    useTemporalCompression: 'Temporal tensor compression (ADR-085)',
+    useMetadataFiltering: 'SIMD-accelerated metadata filtering',
+    useDeterministicDither: 'Cross-platform deterministic dithering',
+    useNeuralRouting: 'Neural model routing via FastGRNN (ADR-082)',
+    useSONAThreeLoop: 'SONA Three-Loop Engine (Task 2.2)',
+    useCrossDomainTransfer: 'Cross-domain transfer learning (ADR-084)',
+    useHnswHealthMonitor: 'HNSW health monitor (Task 3.4)',
+    useRegretTracking: 'Regret tracking & learning health (Task 2.4)',
+    useCoherenceGate: 'Sheaf-gated coherence validation (ADR-083, Task 3.1)',
+    useWitnessChain: 'Blake3 hash-chained witness records (Task 3.1)',
+    useCNNVisualRegression: 'CNN visual regression testing (Task 4.3)',
+    useDAGAttention: 'DAG attention for test scheduling (Task 4.2)',
+    useCoherenceActionGate: 'Coherence-gated agent actions (ADR-083, Task 3.2)',
+    useReasoningQEC: 'Reasoning QEC error correction (Task 4.5)',
+};
+const PROFILES = {
+    performance: {
+        useNativeHNSW: true,
+        useTemporalCompression: true,
+        useDeterministicDither: true,
+    },
+    experimental: {
+        useQESONA: true,
+        useQEFlashAttention: true,
+        useQEGNNIndex: true,
+        logMigrationMetrics: true,
+        useNativeHNSW: true,
+        useTemporalCompression: true,
+        useMetadataFiltering: true,
+        useDeterministicDither: true,
+        useNeuralRouting: true,
+    },
+    safe: {
+        useQESONA: true,
+        useQEFlashAttention: true,
+        useQEGNNIndex: true,
+        logMigrationMetrics: true,
+        useNativeHNSW: false,
+        useTemporalCompression: false,
+        useMetadataFiltering: false,
+        useDeterministicDither: false,
+        useNeuralRouting: false,
+    },
+};
+const VALID_FLAG_NAMES = Object.keys(DEFAULT_FEATURE_FLAGS);
+// ============================================================================
+// Helpers
+// ============================================================================
+/**
+ * Check whether a native package is installed.
+ * Returns true if the package can be resolved, false otherwise.
+ */
+function isNativePackageInstalled(packageName) {
+    try {
+        require.resolve(packageName);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isDefaultValue(flag, value) {
+    return DEFAULT_FEATURE_FLAGS[flag] === value;
+}
+function padRight(str, length) {
+    return str.padEnd(length);
+}
+function isValidFlagName(name) {
+    return VALID_FLAG_NAMES.includes(name);
+}
+function isValidProfile(name) {
+    return name in PROFILES;
+}
+// ============================================================================
+// Command: ruvector status
+// ============================================================================
+function executeStatus() {
+    const flags = getRuVectorFeatureFlags();
+    console.log('');
+    console.log(chalk.bold.blue('RuVector Integration Status:'));
+    // Native packages section
+    console.log(chalk.cyan('  Native Packages:'));
+    for (const pkg of NATIVE_PACKAGES) {
+        const installed = isNativePackageInstalled(pkg.name);
+        const statusText = installed
+            ? chalk.green('installed')
+            : chalk.gray(`not installed (fallback: ${pkg.fallback})`);
+        console.log(`    ${padRight(pkg.name + ':', 30)} ${statusText}`);
+    }
+    // Feature flags section
+    console.log('');
+    console.log(chalk.cyan('  Feature Flags:'));
+    for (const flagName of VALID_FLAG_NAMES) {
+        const value = flags[flagName];
+        const isDefault = isDefaultValue(flagName, value);
+        const valueText = value ? chalk.green('true') : chalk.gray('false');
+        const suffix = isDefault ? chalk.gray(' (default)') : chalk.yellow(' (modified)');
+        console.log(`    ${padRight(flagName + ':', 30)} ${valueText}${suffix}`);
+    }
+    // Memory info when compression is enabled
+    if (flags.useTemporalCompression) {
+        console.log('');
+        console.log(chalk.cyan('  Temporal Compression:'));
+        console.log(chalk.gray('    Hot tier:  8-bit quantization (frequently accessed patterns)'));
+        console.log(chalk.gray('    Warm tier: 5-bit quantization (moderately accessed patterns)'));
+        console.log(chalk.gray('    Cold tier: 3-bit quantization (rarely accessed patterns)'));
+        console.log(chalk.gray('    Estimated memory savings: 40-60% for cold patterns'));
+    }
+    console.log('');
+}
+// ============================================================================
+// Command: ruvector flags
+// ============================================================================
+function executeFlags(options) {
+    // Handle --profile
+    if (options.profile) {
+        if (!isValidProfile(options.profile)) {
+            console.log('');
+            console.log(chalk.red(`  Unknown profile: ${options.profile}`));
+            console.log(chalk.gray(`  Valid profiles: ${Object.keys(PROFILES).join(', ')}`));
+            console.log('');
+            process.exit(1);
+            return;
+        }
+        const profileFlags = PROFILES[options.profile];
+        setRuVectorFeatureFlags(profileFlags);
+        console.log('');
+        console.log(chalk.bold.blue(`Setting ${options.profile} profile:`));
+        for (const [key, value] of Object.entries(profileFlags)) {
+            const valueText = value ? chalk.green('true') : chalk.gray('false');
+            console.log(`  ${padRight(key + ':', 30)} ${valueText}`);
+        }
+        console.log('');
+        return;
+    }
+    // Handle --set
+    if (options.set) {
+        const eqIdx = options.set.indexOf('=');
+        if (eqIdx <= 0) {
+            console.log('');
+            console.log(chalk.red('  Invalid format. Use: --set flagName=true|false'));
+            console.log('');
+            process.exit(1);
+            return;
+        }
+        const flagName = options.set.substring(0, eqIdx);
+        const flagValue = options.set.substring(eqIdx + 1);
+        if (!isValidFlagName(flagName)) {
+            console.log('');
+            console.log(chalk.red(`  Unknown flag: ${flagName}`));
+            console.log(chalk.gray(`  Valid flags: ${VALID_FLAG_NAMES.join(', ')}`));
+            console.log('');
+            process.exit(1);
+            return;
+        }
+        if (flagValue !== 'true' && flagValue !== 'false') {
+            console.log('');
+            console.log(chalk.red(`  Invalid value: ${flagValue}. Use true or false.`));
+            console.log('');
+            process.exit(1);
+            return;
+        }
+        const boolValue = flagValue === 'true';
+        setRuVectorFeatureFlags({ [flagName]: boolValue });
+        const valueText = boolValue ? chalk.green('true') : chalk.gray('false');
+        console.log('');
+        console.log(chalk.green(`  Set ${flagName} = ${valueText}`));
+        console.log('');
+        return;
+    }
+    // Default: list all flags
+    const flags = getRuVectorFeatureFlags();
+    console.log('');
+    console.log(chalk.bold.blue('RuVector Feature Flags:'));
+    console.log('');
+    console.log(chalk.bold('  ' + padRight('Flag', 28) + padRight('Value', 10) + 'Description'));
+    console.log(chalk.gray('  ' + '-'.repeat(78)));
+    for (const flagName of VALID_FLAG_NAMES) {
+        const value = flags[flagName];
+        const isDefault = isDefaultValue(flagName, value);
+        const valueText = value ? chalk.green('true') : chalk.gray('false');
+        const suffix = isDefault ? '' : chalk.yellow(' *');
+        const description = FLAG_DESCRIPTIONS[flagName];
+        console.log('  ' +
+            padRight(flagName, 28) +
+            padRight(String(value), 10) +
+            chalk.gray(description) +
+            suffix);
+    }
+    console.log('');
+    console.log(chalk.gray('  * = modified from default'));
+    console.log('');
+    console.log(chalk.gray('  Profiles: performance, experimental, safe'));
+    console.log(chalk.gray('  Usage:'));
+    console.log(chalk.gray('    aqe ruvector flags --set useNativeHNSW=true'));
+    console.log(chalk.gray('    aqe ruvector flags --profile=performance'));
+    console.log('');
+}
+// ============================================================================
+// Command Factory
+// ============================================================================
+/**
+ * Create the ruvector command group
+ */
+export function createRuVectorCommand() {
+    const ruvectorCmd = new Command('ruvector')
+        .description('RuVector integration management')
+        .addHelpText('after', `
+Examples:
+  $ aqe ruvector status                     Show native packages and flags
+  $ aqe ruvector flags                      List all feature flags
+  $ aqe ruvector flags --set useNativeHNSW=true   Toggle a flag
+  $ aqe ruvector flags --profile=performance      Apply a preset profile
+`);
+    // ruvector status
+    ruvectorCmd
+        .command('status')
+        .description('Show native package availability and feature flag status')
+        .action(() => {
+        executeStatus();
+    });
+    // ruvector flags
+    ruvectorCmd
+        .command('flags')
+        .description('List, set, or apply profiles to feature flags')
+        .option('-s, --set <flag=value>', 'Set a feature flag (e.g., useNativeHNSW=true)')
+        .option('-p, --profile <name>', 'Apply a preset profile (performance|experimental|safe)')
+        .action((options) => {
+        executeFlags(options);
+    });
+    return ruvectorCmd;
+}
+export default createRuVectorCommand;
+//# sourceMappingURL=ruvector-commands.js.map

package/dist/cli/index.js

@@ -819,6 +819,8 @@ import { createLearningCommand } from './commands/learning.js';
 import { createMcpCommand } from './commands/mcp.js';
 import { createPlatformCommand } from './commands/platform.js';
 import { createProveCommand } from './commands/prove.js';
+import { createRuVectorCommand } from './commands/ruvector-commands.js';
+import { createAuditCommand } from './commands/audit.js';
 program.addCommand(createTokenUsageCommand());
 program.addCommand(createLLMRouterCommand());
 program.addCommand(createSyncCommands());
@@ -827,6 +829,8 @@ program.addCommand(createLearningCommand());
 program.addCommand(createMcpCommand());
 program.addCommand(createPlatformCommand());
 program.addCommand(createProveCommand(context, cleanupAndExit, ensureInitialized));
+program.addCommand(createRuVectorCommand());
+program.addCommand(createAuditCommand(context, cleanupAndExit, ensureInitialized));
 // ============================================================================
 // Shutdown Handlers
 // ============================================================================