/** * DesyncDetector - Detect and fix status desyncs between metadata.json and spec.md * * Prevents silent failures by validating source-of-truth consistency. * Critical for maintaining data integrity across increment lifecycle. * * Incident Reference: 2025-11-20 - Silent failure in sw:done caused * increment 0047 to have metadata.json="completed" while spec.md="active", * breaking status line and user trust. * * CLAUDE.md Rule #7: spec.md and metadata.json are BOTH source of truth and MUST stay in sync. */ import { IncrementStatus } from '../types/increment-metadata.js'; import { Logger } from '../../utils/logger.js'; /** * Desync detection result for a single increment */ export interface DesyncResult { incrementId: string; hasDesync: boolean; metadataStatus: IncrementStatus | null; specStatus: IncrementStatus | null; metadataPath: string; specPath: string; error?: string; } /** * Desync scan report for multiple increments */ export interface DesyncScanReport { totalScanned: number; totalDesyncs: number; desyncs: DesyncResult[]; healthy: string[]; errors: string[]; } /** * Options for desync detection */ export interface DesyncDetectorOptions { logger?: Logger; projectRoot?: string; autoFix?: boolean; } /** * DesyncDetector - Validates status consistency between metadata.json and spec.md * * Key Features: * - Detects status desyncs across all increments * - Provides detailed desync reports * - Auto-fix capability (optional) * - Validates before critical operations * * Usage: * ```typescript * // Check single increment * const detector = new DesyncDetector(); * const result = await detector.checkIncrement('0047-us-task-linkage'); * if (result.hasDesync) { * console.error('Desync detected!', result); * } * * // Scan all increments * const report = await detector.scanAll(); * console.log(`Found ${report.totalDesyncs} desyncs`); * ``` */ export declare class DesyncDetector { private logger; private projectRoot; constructor(options?: DesyncDetectorOptions); /** * Check single increment for status desync * * @param incrementId - Increment ID (e.g., "0047-us-task-linkage") * @returns Desync result with detailed status info * * @example * ```typescript * const result = await detector.checkIncrement('0047-us-task-linkage'); * if (result.hasDesync) { * console.error(`Desync: metadata=${result.metadataStatus}, spec=${result.specStatus}`); * } * ``` */ checkIncrement(incrementId: string): Promise; /** * Scan all increments for desyncs * * @returns Comprehensive scan report * * @example * ```typescript * const report = await detector.scanAll(); * console.log(`Scanned ${report.totalScanned} increments`); * console.log(`Found ${report.totalDesyncs} desyncs`); * report.desyncs.forEach(d => console.error(`- ${d.incrementId}`)); * ``` */ scanAll(): Promise; /** * Fix desync by updating spec.md to match metadata.json (source of truth for status) * * IMPORTANT: metadata.json is considered the source of truth because it's updated * atomically and used by the CLI. spec.md should mirror it. * * @param incrementId - Increment ID to fix * @returns true if fixed successfully, false if no desync or fix failed * * @example * ```typescript * const fixed = await detector.fixDesync('0047-us-task-linkage'); * if (fixed) { * console.log('Desync fixed!'); * } * ``` */ fixDesync(incrementId: string): Promise; /** * Validate increment has no desync, throw if found * * Use this before critical operations (e.g., closing increment, archiving) * * @param incrementId - Increment ID to validate * @throws Error if desync detected * * @example * ```typescript * await detector.validateOrThrow('0047-us-task-linkage'); * // Throws if desync found, continues if healthy * ``` */ validateOrThrow(incrementId: string): Promise; /** * Generate human-readable report for desyncs * * @param report - Scan report * @returns Formatted report string */ formatReport(report: DesyncScanReport): string; } //# sourceMappingURL=desync-detector.d.ts.map