claude-flow-novice 2.0.0 → 2.0.1

package/.claude-flow-novice/dist/cfn-loop/coordination-validator.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Coordination Validator for CFN Loop Epic Execution
+ *
+ * Validates that coordinators actually used Redis pub/sub during epic execution
+ * by collecting and analyzing coordination messages, events, and patterns.
+ *
+ * @module cfn-loop/coordination-validator
+ */
+import type { Redis } from 'ioredis';
+/**
+ * Coordination event captured during epic execution
+ */
+export interface CoordinationEvent {
+    timestamp: number;
+    channel: string;
+    type: string;
+    coordinatorId: string;
+    data: any;
+}
+/**
+ * Metrics collected from coordination activity
+ */
+export interface CoordinationMetrics {
+    totalMessages: number;
+    coordinators: string[];
+    channelsUsed: string[];
+    timeline: CoordinationEvent[];
+    dependencyWaiting: boolean;
+    interfacePublishing: boolean;
+    agentLifecycleTracking: boolean;
+    testCoordination: boolean;
+}
+/**
+ * Validation issue found during analysis
+ */
+export interface ValidationIssue {
+    severity: 'critical' | 'high' | 'medium' | 'low';
+    issue: string;
+    description: string;
+    recommendation?: string;
+}
+/**
+ * Result of coordination validation
+ */
+export interface ValidationResult {
+    valid: boolean;
+    metrics: CoordinationMetrics;
+    issues: ValidationIssue[];
+    score: number;
+    timestamp: number;
+}
+/**
+ * Configuration for coordination validator
+ */
+export interface CoordinationValidatorConfig {
+    redis: Redis;
+    requiredChannels?: string[];
+    minMessages?: number;
+    checkTimeline?: boolean;
+    checkDependencies?: boolean;
+}
+/**
+ * CoordinationValidator validates Redis pub/sub coordination during epic execution
+ *
+ * Collects coordination messages, validates patterns, and scores epic coordination quality.
+ * Critical for verifying coordinators followed CFN Loop Rule #19 (Redis pub/sub mandatory).
+ *
+ * @example
+ * ```typescript
+ * const validator = new CoordinationValidator({ redis });
+ * const result = await validator.validateEpicCoordination('epic-123');
+ *
+ * if (!result.valid) {
+ *   console.log('Coordination issues:', result.issues);
+ * }
+ *
+ * console.log('Coordination score:', result.score);
+ * ```
+ */
+export declare class CoordinationValidator {
+    private redis;
+    private config;
+    constructor(config: CoordinationValidatorConfig);
+    /**
+     * Validate coordination for an epic execution
+     *
+     * @param epicId - Epic identifier to validate
+     * @returns Validation result with metrics, issues, and score
+     */
+    validateEpicCoordination(epicId: string): Promise<ValidationResult>;
+    /**
+     * Collect coordination metrics from Redis
+     *
+     * @param epicId - Epic identifier
+     * @returns Coordination metrics
+     */
+    private collectMetrics;
+    /**
+     * Validate timeline ordering (claim → spawn → complete)
+     *
+     * @param timeline - Coordination event timeline
+     * @returns True if timeline is valid
+     */
+    private validateTimeline;
+    /**
+     * Calculate coordination score (0.0 to 1.0)
+     *
+     * @param metrics - Coordination metrics
+     * @param issues - Validation issues
+     * @returns Score from 0.0 to 1.0
+     */
+    private calculateScore;
+    /**
+     * Get coordination summary for epic
+     *
+     * @param epicId - Epic identifier
+     * @returns Human-readable summary
+     */
+    getCoordinationSummary(epicId: string): Promise<string>;
+}
+export default CoordinationValidator;

package/.claude-flow-novice/dist/cfn-loop/coordinator-timeout-handler.d.ts

@@ -0,0 +1,195 @@
+/**
+ * Coordinator Timeout Handler - Sprint 1.4: Extended Timeout Testing
+ *
+ * Detects coordinator timeouts and triggers comprehensive state cleanup.
+ * Integrates with HeartbeatWarningSystem's cleanup infrastructure.
+ *
+ * Features:
+ * - Timeout detection based on configurable threshold
+ * - Automatic state cleanup (heartbeat, ACKs, signals, idempotency)
+ * - Event emission for timeout notifications
+ * - Metrics tracking (timeout_events_total)
+ * - Reuses existing cleanup logic from HeartbeatWarningSystem
+ *
+ * Epic: production-blocking-coordination
+ * Sprint: 1.4 - Extended Timeout Testing - State Cleanup
+ *
+ * @module cfn-loop/coordinator-timeout-handler
+ */
+import { EventEmitter } from 'events';
+import type { Redis } from 'ioredis';
+import type { HeartbeatWarningSystem } from './heartbeat-warning-system.js';
+/**
+ * Timeout event data
+ */
+export interface CoordinatorTimeoutEvent {
+    /** Coordinator ID that timed out */
+    coordinatorId: string;
+    /** Duration since last activity (ms) */
+    timeoutDuration: number;
+    /** Timestamp when timeout was detected */
+    timestamp: number;
+    /** Reason for timeout */
+    reason: string;
+    /** Optional metadata */
+    metadata?: {
+        lastHeartbeat?: number;
+        iteration?: number;
+        phase?: string;
+    };
+}
+/**
+ * Configuration for coordinator timeout handler
+ */
+export interface CoordinatorTimeoutConfig {
+    /** Redis client instance (ioredis) */
+    redisClient: Redis;
+    /** Timeout threshold in milliseconds (default: 300000 = 5 minutes) */
+    timeoutThreshold?: number;
+    /** Check interval in milliseconds (default: 30000 = 30s) */
+    checkInterval?: number;
+    /** Optional HeartbeatWarningSystem for cleanup integration */
+    heartbeatSystem?: HeartbeatWarningSystem;
+    /** Enable automatic cleanup on timeout (default: true) */
+    autoCleanup?: boolean;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+/**
+ * Manages coordinator timeout detection and cleanup
+ */
+export declare class CoordinatorTimeoutHandler extends EventEmitter {
+    private logger;
+    private redis;
+    private timeoutThreshold;
+    private checkInterval;
+    private heartbeatSystem?;
+    private autoCleanup;
+    private debug;
+    private checkTimer;
+    private isMonitoring;
+    private metrics;
+    constructor(config: CoordinatorTimeoutConfig);
+    /**
+     * Non-blocking Redis SCAN operation to replace KEYS
+     *
+     * SEC-HIGH-001 FIX: Uses cursor-based iteration instead of blocking KEYS command.
+     * Prevents DoS attacks in production environments with large key sets.
+     *
+     * @param {string} pattern - Redis key pattern to match
+     * @returns {Promise<string[]>} Matching keys
+     */
+    private scanKeys;
+    /**
+     * Start timeout monitoring
+     */
+    startMonitoring(): void;
+    /**
+     * Stop timeout monitoring
+     */
+    stopMonitoring(): void;
+    /**
+     * Manually trigger timeout detection for a specific coordinator
+     *
+     * @param coordinatorId - Coordinator ID to check
+     * @param currentTime - Current timestamp (defaults to Date.now())
+     * @returns True if timeout detected and handled
+     */
+    checkCoordinatorTimeout(coordinatorId: string, currentTime?: number): Promise<boolean>;
+    /**
+     * Handle coordinator timeout
+     *
+     * @param coordinatorId - Coordinator ID that timed out
+     * @param timeoutDuration - Duration since last activity (ms)
+     * @param activity - Coordinator activity record
+     */
+    private handleTimeout;
+    /**
+     * Cleanup state for timed-out coordinator
+     *
+     * Delegates to HeartbeatWarningSystem if available, otherwise performs direct cleanup.
+     * Removes:
+     * - Heartbeat records
+     * - Signal ACKs (blocking:ack:coordinatorId:*)
+     * - Signals (blocking:signal:coordinatorId)
+     * - Idempotency records (blocking:idempotency:*coordinatorId*)
+     * - Activity tracking (coordinator:activity:coordinatorId)
+     *
+     * @param coordinatorId - Coordinator ID to cleanup
+     */
+    cleanupTimeoutCoordinator(coordinatorId: string): Promise<void>;
+    /**
+     * Perform direct cleanup without HeartbeatWarningSystem
+     *
+     * @param coordinatorId - Coordinator ID to cleanup (should already be sanitized)
+     */
+    private performDirectCleanup;
+    /**
+     * Record coordinator activity
+     *
+     * @param coordinatorId - Coordinator ID
+     * @param iteration - Current iteration count
+     * @param phase - Optional phase information
+     */
+    recordActivity(coordinatorId: string, iteration: number, phase?: string): Promise<void>;
+    /**
+     * Get coordinator activity record
+     *
+     * @param coordinatorId - Coordinator ID (should already be sanitized by caller)
+     * @returns Activity record or null if not found
+     */
+    private getCoordinatorActivity;
+    /**
+     * Check for timeouts across all coordinators
+     */
+    private checkForTimeouts;
+    /**
+     * Extract coordinator ID from activity key
+     */
+    private extractCoordinatorId;
+    /**
+     * Escalate dead coordinator to parent or swarm manager
+     *
+     * Sprint 3.2: Auto-Recovery Mechanisms
+     *
+     * When a coordinator is detected as dead (timed out), this method:
+     * 1. Notifies the parent coordinator or swarm manager
+     * 2. Spawns a NEW coordinator to replace the dead one
+     * 3. Transfers incomplete work to the new coordinator
+     * 4. Logs the escalation event to Redis
+     *
+     * @param coordinatorId - Dead coordinator ID
+     * @param swarmId - Swarm ID that the coordinator belonged to
+     * @returns New coordinator ID if spawned, null if escalation failed
+     */
+    escalateDeadCoordinator(coordinatorId: string, swarmId: string): Promise<string | null>;
+    /**
+     * Transfer incomplete work from dead coordinator to new coordinator
+     *
+     * @param deadCoordinatorId - Dead coordinator ID (should be sanitized)
+     * @param newCoordinatorId - New coordinator ID
+     * @param swarmId - Swarm ID (should be sanitized)
+     */
+    private transferIncompleteWork;
+    /**
+     * Get metrics
+     */
+    getMetrics(): {
+        totalChecks: number;
+        timeoutEventsTotal: number;
+        cleanupsPerformed: number;
+        cleanupFailures: number;
+    };
+    /**
+     * Reset metrics
+     */
+    resetMetrics(): void;
+}
+/**
+ * Create a CoordinatorTimeoutHandler instance
+ *
+ * @param config - Configuration for timeout handler
+ * @returns Configured CoordinatorTimeoutHandler
+ */
+export declare function createCoordinatorTimeoutHandler(config: CoordinatorTimeoutConfig): CoordinatorTimeoutHandler;
+export default CoordinatorTimeoutHandler;

package/.claude-flow-novice/dist/cfn-loop/crash-detector.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Crash Detection System - Detect and Analyze Interrupted CFN Loop Executions
+ *
+ * Detects interrupted executions on CLI startup by scanning Redis for:
+ * - Epics with stale heartbeats (>5 minutes without update)
+ * - Sprints in progress vs completed states
+ * - Checkpoint timestamps vs current time
+ * - Estimated work loss and recovery time
+ *
+ * Acceptance Criteria:
+ * - Detect interrupted epics within 5 seconds of CLI start
+ * - Show accurate sprint progress percentages
+ * - Calculate estimated recovery time
+ * - Differentiate between crash and clean shutdown
+ *
+ * @module cfn-loop/crash-detector
+ */
+import { EventEmitter } from 'node:events';
+import { EpicState } from './state-checkpoint-manager.js';
+/**
+ * Interrupted sprint details
+ */
+export interface InterruptedSprint {
+    sprintId: string;
+    name: string;
+    progress: number;
+    filesInProgress: string[];
+    phasesCompleted: number;
+    phasesTotal: number;
+    lastUpdateTime: number;
+}
+/**
+ * Interrupted execution detected
+ */
+export interface InterruptedExecution {
+    epicId: string;
+    epicName: string;
+    lastHeartbeat: number;
+    timeSinceHeartbeat: number;
+    sprintsInProgress: InterruptedSprint[];
+    sprintsCompleted: number;
+    sprintsTotal: number;
+    estimatedWorkLoss: number;
+    recoveryTimeEstimate: number;
+    isCleanShutdown: boolean;
+    checkpointVersion: number;
+    lastCheckpointTime: number;
+}
+/**
+ * Configuration for crash detector
+ */
+export interface CrashDetectorConfig {
+    redisUrl?: string;
+    heartbeatTimeoutMs?: number;
+    scanTimeoutMs?: number;
+    recoveryTimePerPhaseMin?: number;
+}
+/**
+ * Crash detection summary statistics
+ */
+export interface CrashDetectionStats {
+    totalEpicsScanned: number;
+    interruptedEpicsFound: number;
+    cleanShutdownsFound: number;
+    scanDurationMs: number;
+    redisKeysScanned: number;
+}
+/**
+ * Detects interrupted CFN Loop executions on CLI startup
+ *
+ * Features:
+ * - Fast detection (<5 seconds)
+ * - Redis heartbeat analysis
+ * - Sprint progress calculation
+ * - Work loss estimation
+ * - Clean shutdown differentiation
+ *
+ * Usage:
+ * ```typescript
+ * const detector = new CrashDetector({
+ *   heartbeatTimeoutMs: 300000 // 5 minutes
+ * });
+ *
+ * await detector.initialize();
+ * const interrupted = await detector.detectInterruptedExecutions();
+ * ```
+ */
+export declare class CrashDetector extends EventEmitter {
+    private logger;
+    private config;
+    private redis;
+    private stats;
+    constructor(config?: CrashDetectorConfig);
+    /**
+     * Initialize Redis connection
+     */
+    initialize(): Promise<void>;
+    /**
+     * Detect all interrupted executions
+     */
+    detectInterruptedExecutions(): Promise<InterruptedExecution[]>;
+    /**
+     * Scan Redis for running epics without recent heartbeats
+     */
+    scanRedisForStaleHeartbeats(): Promise<string[]>;
+    /**
+     * Analyze a specific interrupted epic
+     */
+    private analyzeInterruptedEpic;
+    /**
+     * Calculate sprint progress percentages
+     */
+    private calculateSprintProgress;
+    /**
+     * Calculate estimated work loss percentage
+     */
+    private calculateWorkLoss;
+    /**
+     * Calculate estimated recovery time in minutes
+     */
+    calculateRecoveryEstimate(epicId: string, epicState: EpicState): Promise<number>;
+    /**
+     * Differentiate between crash and clean shutdown
+     */
+    differentiateCleanShutdown(epicId: string, epicState: EpicState): Promise<boolean>;
+    /**
+     * Get crash detection statistics
+     */
+    getStats(): CrashDetectionStats;
+    /**
+     * Helper to execute promise with timeout
+     */
+    private withTimeout;
+    /**
+     * Shutdown crash detector and close Redis connection
+     */
+    shutdown(): Promise<void>;
+}

package/.claude-flow-novice/dist/cfn-loop/epic-report-generator.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Epic Report Generator with Coordination Validation
+ *
+ * Generates comprehensive epic completion reports including:
+ * - Coordination validation results
+ * - Timeline analysis
+ * - Sprint summaries
+ * - Consensus scores
+ * - Issue tracking
+ *
+ * @module cfn-loop/epic-report-generator
+ */
+import type { Redis } from 'ioredis';
+import { type ValidationResult } from './coordination-validator.js';
+/**
+ * Sprint summary information
+ */
+export interface SprintSummary {
+    sprintId: string;
+    name: string;
+    status: 'completed' | 'failed' | 'in-progress';
+    confidence: number;
+    consensusScore: number;
+    startTime: number;
+    endTime: number;
+    duration: number;
+    agents: string[];
+    deliverables: string[];
+}
+/**
+ * Epic metadata
+ */
+export interface EpicMetadata {
+    epicId: string;
+    name: string;
+    description?: string;
+    startTime: number;
+    endTime: number;
+    totalDuration: number;
+    sprints: SprintSummary[];
+    totalAgents: number;
+    overallConfidence: number;
+    overallConsensus: number;
+}
+/**
+ * Complete epic report
+ */
+export interface EpicReport {
+    metadata: EpicMetadata;
+    validation: ValidationResult;
+    summary: string;
+    markdown: string;
+    timestamp: number;
+}
+/**
+ * Configuration for epic report generator
+ */
+export interface EpicReportGeneratorConfig {
+    redis: Redis;
+    includeTimeline?: boolean;
+    maxTimelineEvents?: number;
+    includeIssues?: boolean;
+    includeRecommendations?: boolean;
+}
+/**
+ * EpicReportGenerator generates comprehensive epic completion reports
+ *
+ * Uses CoordinationValidator to verify Redis pub/sub coordination
+ * and formats results into human-readable markdown reports.
+ *
+ * @example
+ * ```typescript
+ * const generator = new EpicReportGenerator({ redis });
+ * const report = await generator.generateReport('epic-123');
+ *
+ * console.log(report.markdown);
+ * ```
+ */
+export declare class EpicReportGenerator {
+    private redis;
+    private validator;
+    private config;
+    constructor(config: EpicReportGeneratorConfig);
+    /**
+     * Generate complete epic report
+     *
+     * @param epicId - Epic identifier
+     * @returns Complete epic report with validation
+     */
+    generateReport(epicId: string): Promise<EpicReport>;
+    /**
+     * Collect epic metadata from Redis
+     *
+     * @param epicId - Epic identifier
+     * @returns Epic metadata
+     */
+    private collectEpicMetadata;
+    /**
+     * Generate text summary
+     *
+     * @param metadata - Epic metadata
+     * @param validation - Validation result
+     * @returns Text summary
+     */
+    private generateSummary;
+    /**
+     * Generate markdown report
+     *
+     * @param metadata - Epic metadata
+     * @param validation - Validation result
+     * @returns Markdown report
+     */
+    private generateMarkdown;
+    /**
+     * Format duration in human-readable format
+     *
+     * @param ms - Duration in milliseconds
+     * @returns Formatted duration
+     */
+    private formatDuration;
+    /**
+     * Save report to Redis
+     *
+     * @param epicId - Epic identifier
+     * @param report - Epic report
+     */
+    saveReport(epicId: string, report: EpicReport): Promise<void>;
+    /**
+     * Load report from Redis
+     *
+     * @param epicId - Epic identifier
+     * @returns Epic report or null if not found
+     */
+    loadReport(epicId: string): Promise<EpicReport | null>;
+}
+export default EpicReportGenerator;

package/.claude-flow-novice/dist/cfn-loop/git-checkpoint-integration.example.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Git Checkpoint Manager - Integration Example
+ *
+ * Demonstrates how to integrate Git auto-checkpoint with CFN Loop execution:
+ * - Create WIP branches per sprint
+ * - Auto-commit progress every 5 minutes
+ * - Tag commits with confidence scores
+ * - Compare checkpoints for recovery
+ * - Cleanup branches after completion
+ *
+ * @module cfn-loop/git-checkpoint-integration-example
+ */
+export {};