specweave 0.23.2 → 0.23.5

package/dist/src/core/increment/desync-detector.d.ts

@@ -0,0 +1,142 @@
+/**
+ * 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 /specweave: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<DesyncResult>;
+    /**
+     * 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<DesyncScanReport>;
+    /**
+     * 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<boolean>;
+    /**
+     * 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<void>;
+    /**
+     * Generate human-readable report for desyncs
+     *
+     * @param report - Scan report
+     * @returns Formatted report string
+     */
+    formatReport(report: DesyncScanReport): string;
+}
+//# sourceMappingURL=desync-detector.d.ts.map

package/dist/src/core/increment/desync-detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"desync-detector.d.ts","sourceRoot":"","sources":["../../../../src/core/increment/desync-detector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACjE,OAAO,EAAE,MAAM,EAAiB,MAAM,uBAAuB,CAAC;AAE9D;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,cAAc,EAAE,eAAe,GAAG,IAAI,CAAC;IACvC,UAAU,EAAE,eAAe,GAAG,IAAI,CAAC;IACnC,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,WAAW,CAAS;gBAEhB,OAAO,GAAE,qBAA0B;IAK/C;;;;;;;;;;;;;OAaG;IACG,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IA4DhE;;;;;;;;;;;;OAYG;IACG,OAAO,IAAI,OAAO,CAAC,gBAAgB,CAAC;IAwC1C;;;;;;;;;;;;;;;;OAgBG;IACG,SAAS,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAyCtD;;;;;;;;;;;;;OAaG;IACG,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBzD;;;;;OAKG;IACH,YAAY,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM;CAoD/C"}

package/dist/src/core/increment/desync-detector.js

@@ -0,0 +1,270 @@
+/**
+ * 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 /specweave: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 fs from 'fs-extra';
+import path from 'path';
+import matter from 'gray-matter';
+import { consoleLogger } from '../../utils/logger.js';
+/**
+ * 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 class DesyncDetector {
+    constructor(options = {}) {
+        this.logger = options.logger ?? consoleLogger;
+        this.projectRoot = options.projectRoot ?? process.cwd();
+    }
+    /**
+     * 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}`);
+     * }
+     * ```
+     */
+    async checkIncrement(incrementId) {
+        const metadataPath = path.join(this.projectRoot, '.specweave', 'increments', incrementId, 'metadata.json');
+        const specPath = path.join(this.projectRoot, '.specweave', 'increments', incrementId, 'spec.md');
+        try {
+            // Read metadata.json status
+            let metadataStatus = null;
+            if (await fs.pathExists(metadataPath)) {
+                const metadata = await fs.readJson(metadataPath);
+                metadataStatus = metadata.status ?? null;
+            }
+            // Read spec.md status
+            let specStatus = null;
+            if (await fs.pathExists(specPath)) {
+                const content = await fs.readFile(specPath, 'utf-8');
+                const parsed = matter(content);
+                specStatus = parsed.data.status ?? null;
+            }
+            // Detect desync
+            const hasDesync = metadataStatus !== null &&
+                specStatus !== null &&
+                metadataStatus !== specStatus;
+            return {
+                incrementId,
+                hasDesync,
+                metadataStatus,
+                specStatus,
+                metadataPath,
+                specPath,
+            };
+        }
+        catch (error) {
+            return {
+                incrementId,
+                hasDesync: false,
+                metadataStatus: null,
+                specStatus: null,
+                metadataPath,
+                specPath,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    /**
+     * 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}`));
+     * ```
+     */
+    async scanAll() {
+        const incrementsDir = path.join(this.projectRoot, '.specweave', 'increments');
+        const report = {
+            totalScanned: 0,
+            totalDesyncs: 0,
+            desyncs: [],
+            healthy: [],
+            errors: [],
+        };
+        if (!(await fs.pathExists(incrementsDir))) {
+            return report;
+        }
+        // Get all increment directories
+        const entries = await fs.readdir(incrementsDir, { withFileTypes: true });
+        const incrementDirs = entries
+            .filter((entry) => entry.isDirectory() && !entry.name.startsWith('_'))
+            .map((entry) => entry.name);
+        // Check each increment
+        for (const incrementId of incrementDirs) {
+            report.totalScanned++;
+            const result = await this.checkIncrement(incrementId);
+            if (result.error) {
+                report.errors.push(`${incrementId}: ${result.error}`);
+            }
+            else if (result.hasDesync) {
+                report.totalDesyncs++;
+                report.desyncs.push(result);
+            }
+            else {
+                report.healthy.push(incrementId);
+            }
+        }
+        return report;
+    }
+    /**
+     * 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!');
+     * }
+     * ```
+     */
+    async fixDesync(incrementId) {
+        const result = await this.checkIncrement(incrementId);
+        if (!result.hasDesync) {
+            this.logger.log(`No desync detected for ${incrementId}`);
+            return false;
+        }
+        if (result.metadataStatus === null) {
+            this.logger.error(`Cannot fix desync - metadata.json missing for ${incrementId}`);
+            return false;
+        }
+        try {
+            // Read spec.md
+            const content = await fs.readFile(result.specPath, 'utf-8');
+            const parsed = matter(content);
+            // Update status to match metadata.json (source of truth)
+            parsed.data.status = result.metadataStatus;
+            // Write back atomically
+            const updatedContent = matter.stringify(parsed.content, parsed.data);
+            const tempPath = `${result.specPath}.tmp`;
+            await fs.writeFile(tempPath, updatedContent, 'utf-8');
+            await fs.rename(tempPath, result.specPath);
+            this.logger.log(`Fixed desync for ${incrementId}: spec.md updated from "${result.specStatus}" to "${result.metadataStatus}"`);
+            return true;
+        }
+        catch (error) {
+            this.logger.error(`Failed to fix desync for ${incrementId}`, error instanceof Error ? error : new Error(String(error)));
+            return false;
+        }
+    }
+    /**
+     * 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
+     * ```
+     */
+    async validateOrThrow(incrementId) {
+        const result = await this.checkIncrement(incrementId);
+        if (result.error) {
+            throw new Error(`Cannot validate ${incrementId} - error reading status: ${result.error}`);
+        }
+        if (result.hasDesync) {
+            throw new Error(`CRITICAL: Status desync detected for ${incrementId}!\n` +
+                `metadata.json: ${result.metadataStatus}\n` +
+                `spec.md: ${result.specStatus}\n\n` +
+                `This is a source-of-truth violation (CLAUDE.md Rule #7).\n` +
+                `Run: /specweave:sync-status ${incrementId} to fix`);
+        }
+    }
+    /**
+     * Generate human-readable report for desyncs
+     *
+     * @param report - Scan report
+     * @returns Formatted report string
+     */
+    formatReport(report) {
+        const lines = [];
+        lines.push('━'.repeat(80));
+        lines.push('STATUS DESYNC DETECTION REPORT');
+        lines.push('━'.repeat(80));
+        lines.push('');
+        lines.push(`Total Scanned: ${report.totalScanned} increments`);
+        lines.push(`Healthy: ${report.healthy.length}`);
+        lines.push(`Desyncs Found: ${report.totalDesyncs} ⚠️`);
+        lines.push(`Errors: ${report.errors.length}`);
+        lines.push('');
+        if (report.totalDesyncs > 0) {
+            lines.push('━'.repeat(80));
+            lines.push('DESYNCS DETECTED (CRITICAL!)');
+            lines.push('━'.repeat(80));
+            lines.push('');
+            report.desyncs.forEach((desync) => {
+                lines.push(`❌ ${desync.incrementId}`);
+                lines.push(`   metadata.json: ${desync.metadataStatus}`);
+                lines.push(`   spec.md:       ${desync.specStatus}`);
+                lines.push('');
+            });
+            lines.push('Fix command: /specweave:sync-status');
+            lines.push('');
+        }
+        if (report.errors.length > 0) {
+            lines.push('━'.repeat(80));
+            lines.push('ERRORS');
+            lines.push('━'.repeat(80));
+            lines.push('');
+            report.errors.forEach((error) => {
+                lines.push(`⚠️  ${error}`);
+            });
+            lines.push('');
+        }
+        if (report.totalDesyncs === 0 && report.errors.length === 0) {
+            lines.push('✅ All increments healthy - no desyncs detected!');
+            lines.push('');
+        }
+        lines.push('━'.repeat(80));
+        return lines.join('\n');
+    }
+}
+//# sourceMappingURL=desync-detector.js.map

package/dist/src/core/increment/desync-detector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"desync-detector.js","sourceRoot":"","sources":["../../../../src/core/increment/desync-detector.ts"],"names":[],"mappings":"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"}

package/dist/src/core/increment/metadata-manager.d.ts

@@ -41,12 +41,12 @@ export declare class MetadataManager {
     /**
      * Check if metadata file exists
      */
-    static exists(incrementId: string): boolean;
+    static exists(incrementId: string, rootDir?: string): boolean;
     /**
      * Read metadata from file
      * Creates default metadata if file doesn't exist (lazy initialization)
      */
-    static read(incrementId: string): IncrementMetadata;
+    static read(incrementId: string, rootDir?: string): IncrementMetadata;
     /**
      * Reserved increment IDs that cannot be used
      * These are status values, special folders, and state files
@@ -65,12 +65,16 @@ export declare class MetadataManager {
     /**
      * Write metadata to file
      * Uses atomic write (temp file → rename)
+     *
+     * @param incrementId - Increment ID
+     * @param metadata - Metadata to write
+     * @param rootDir - Optional root directory (defaults to process.cwd())
      */
-    static write(incrementId: string, metadata: IncrementMetadata): void;
+    static write(incrementId: string, metadata: IncrementMetadata, rootDir?: string): void;
     /**
      * Delete metadata file
      */
-    static delete(incrementId: string): void;
+    static delete(incrementId: string, rootDir?: string): void;
     /**
      * Update increment status
      * Validates transition and updates timestamps

package/dist/src/core/increment/metadata-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"metadata-manager.d.ts","sourceRoot":"","sources":["../../../../src/core/increment/metadata-manager.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"metadata-manager.d.ts","sourceRoot":"","sources":["../../../../src/core/increment/metadata-manager.ts"],"names":[],"mappings":"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"}

package/dist/src/core/increment/metadata-manager.js

@@ -39,40 +39,40 @@ export class MetadataManager {
     /**
      * Get metadata file path for increment
      */
-    static getMetadataPath(incrementId) {
-        const specweavePath = path.join(process.cwd(), '.specweave');
+    static getMetadataPath(incrementId, rootDir) {
+        const specweavePath = path.join(rootDir || process.cwd(), '.specweave');
         return path.join(specweavePath, 'increments', incrementId, 'metadata.json');
     }
     /**
      * Get increment directory path
      */
-    static getIncrementPath(incrementId) {
-        const specweavePath = path.join(process.cwd(), '.specweave');
+    static getIncrementPath(incrementId, rootDir) {
+        const specweavePath = path.join(rootDir || process.cwd(), '.specweave');
         return path.join(specweavePath, 'increments', incrementId);
     }
     /**
      * Check if metadata file exists
      */
-    static exists(incrementId) {
-        const metadataPath = this.getMetadataPath(incrementId);
+    static exists(incrementId, rootDir) {
+        const metadataPath = this.getMetadataPath(incrementId, rootDir);
         return fs.existsSync(metadataPath);
     }
     /**
      * Read metadata from file
      * Creates default metadata if file doesn't exist (lazy initialization)
      */
-    static read(incrementId) {
-        const metadataPath = this.getMetadataPath(incrementId);
+    static read(incrementId, rootDir) {
+        const metadataPath = this.getMetadataPath(incrementId, rootDir);
         // Lazy initialization: Create metadata if doesn't exist
         if (!fs.existsSync(metadataPath)) {
             // Check if increment folder exists
-            const incrementPath = this.getIncrementPath(incrementId);
+            const incrementPath = this.getIncrementPath(incrementId, rootDir);
             if (!fs.existsSync(incrementPath)) {
                 throw new MetadataError(`Increment not found: ${incrementId}`, incrementId);
             }
             // Create default metadata
             const defaultMetadata = createDefaultMetadata(incrementId);
-            this.write(incrementId, defaultMetadata);
+            this.write(incrementId, defaultMetadata, rootDir);
             // **CRITICAL**: Update active increment state if default status is ACTIVE
             // This ensures that newly created increments are immediately tracked for status line
             // Skip validation to prevent circular dependency during lazy initialization
@@ -148,10 +148,14 @@ export class MetadataManager {
     /**
      * Write metadata to file
      * Uses atomic write (temp file → rename)
+     *
+     * @param incrementId - Increment ID
+     * @param metadata - Metadata to write
+     * @param rootDir - Optional root directory (defaults to process.cwd())
      */
-    static write(incrementId, metadata) {
-        const metadataPath = this.getMetadataPath(incrementId);
-        const incrementPath = this.getIncrementPath(incrementId);
+    static write(incrementId, metadata, rootDir) {
+        const metadataPath = this.getMetadataPath(incrementId, rootDir);
+        const incrementPath = this.getIncrementPath(incrementId, rootDir);
         // Ensure increment directory exists
         if (!fs.existsSync(incrementPath)) {
             throw new MetadataError(`Increment directory not found: ${incrementId}`, incrementId);
@@ -172,8 +176,8 @@ export class MetadataManager {
     /**
      * Delete metadata file
      */
-    static delete(incrementId) {
-        const metadataPath = this.getMetadataPath(incrementId);
+    static delete(incrementId, rootDir) {
+        const metadataPath = this.getMetadataPath(incrementId, rootDir);
         if (!fs.existsSync(metadataPath)) {
             return; // Already deleted
         }
@@ -224,20 +228,40 @@ export class MetadataManager {
             metadata.abandonedReason = reason || 'No reason provided';
             metadata.abandonedAt = new Date().toISOString();
         }
-        this.write(incrementId, metadata);
-        // **NEW (T-005)**: Update spec.md frontmatter to keep in sync with metadata.json
+        // **CRITICAL FIX (2025-11-20)**: Atomic transaction with rollback
+        // Update spec.md FIRST, then metadata.json. If spec.md fails, no desync occurs.
+        // This prevents the silent failure bug that caused increment 0047 desync.
+        //
+        // Previous bug: metadata.json updated, spec.md failed silently → desync
+        // New behavior: spec.md fails → error thrown → metadata.json never written
+        //
         // AC-US2-01: updateStatus() updates both metadata.json AND spec.md frontmatter
         // AC-US2-03: All status transitions update spec.md
         // SYNCHRONOUS call to ensure spec.md is updated before returning
         // This prevents race conditions and ensures data consistency
         try {
-            // Use sync version to avoid race conditions in tests
+            // Step 1: Update spec.md (may throw if spec.md exists but has errors)
             this.updateSpecMdStatusSync(incrementId, newStatus);
+            // Step 2: Update metadata.json (only if spec.md succeeded)
+            this.write(incrementId, metadata);
         }
         catch (error) {
-            // Log error but don't fail the status update
-            // This maintains backward compatibility if spec.md doesn't exist or has issues
-            this.logger.error(`Failed to update spec.md for ${incrementId}`, error);
+            // CRITICAL: spec.md update failed - prevent desync by NOT updating metadata.json
+            this.logger.error(`CRITICAL: Failed to update status for ${incrementId} - aborting to prevent desync`, error);
+            // Throw detailed error with fix instructions
+            throw new MetadataError(`Cannot update increment status - spec.md sync failed.\n` +
+                `\n` +
+                `This prevents source-of-truth violations (CLAUDE.md Rule #7).\n` +
+                `Both metadata.json AND spec.md must update atomically.\n` +
+                `\n` +
+                `Error: ${error instanceof Error ? error.message : String(error)}\n` +
+                `\n` +
+                `If this persists, check:\n` +
+                `1. File permissions for .specweave/increments/${incrementId}/spec.md\n` +
+                `2. YAML frontmatter syntax in spec.md\n` +
+                `3. Disk space availability\n` +
+                `\n` +
+                `To check for desyncs, run: /specweave:sync-status`, incrementId, error instanceof Error ? error : undefined);
         }
         // **CRITICAL**: Update active increment state
         const activeManager = new ActiveIncrementManager();