specweave 0.28.68 → 0.29.0

package/dist/src/core/discrepancy/update-recommender.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Update Recommender
+ *
+ * Generates recommendations for handling discrepancies and creates update patches.
+ *
+ * @module core/discrepancy/update-recommender
+ */
+import { Logger } from '../../utils/logger.js';
+import { Discrepancy, DiscrepancyRecommendation } from './detector.js';
+/**
+ * An update patch for a spec file.
+ */
+export interface UpdatePatch {
+    filePath: string;
+    lineNumber: number;
+    originalText: string;
+    newText: string;
+    reason: string;
+}
+/**
+ * Recommendation with optional patch.
+ */
+export interface RecommendationResult {
+    discrepancyId: string;
+    recommendation: DiscrepancyRecommendation;
+    patch?: UpdatePatch;
+    explanation: string;
+    riskLevel: 'low' | 'medium' | 'high';
+}
+/**
+ * Configuration for the update recommender.
+ */
+export interface UpdateRecommenderConfig {
+    /** Auto-update trivial changes */
+    autoUpdateTrivial?: boolean;
+    /** Generate patches for review-required changes */
+    generatePatches?: boolean;
+}
+/**
+ * Generates recommendations for handling discrepancies.
+ */
+export declare class UpdateRecommender {
+    private readonly logger;
+    private readonly config;
+    constructor(options?: {
+        logger?: Logger;
+        config?: UpdateRecommenderConfig;
+    });
+    /**
+     * Generate recommendations for a list of discrepancies.
+     */
+    recommendAll(discrepancies: Discrepancy[]): RecommendationResult[];
+    /**
+     * Generate a recommendation for a single discrepancy.
+     */
+    recommend(discrepancy: Discrepancy): RecommendationResult;
+    /**
+     * Generate an update patch for a discrepancy.
+     */
+    generatePatch(discrepancy: Discrepancy): UpdatePatch | undefined;
+    private mapSeverityToRecommendation;
+    private generateExplanation;
+    private assessRisk;
+    private shouldGeneratePatch;
+    private generateApiRoutePatch;
+    private generateFunctionPatch;
+    private generateTypePatch;
+    private generateApiDocSection;
+    private generateFunctionDocSection;
+    private generateTypeDocSection;
+    /**
+     * Generate a summary report of recommendations.
+     */
+    generateReport(recommendations: RecommendationResult[]): string;
+    private groupBy;
+}
+//# sourceMappingURL=update-recommender.d.ts.map

package/dist/src/core/discrepancy/update-recommender.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-recommender.d.ts","sourceRoot":"","sources":["../../../../src/core/discrepancy/update-recommender.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,MAAM,EAAiB,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAuB,yBAAyB,EAAE,MAAM,eAAe,CAAC;AAE5F;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,yBAAyB,CAAC;IAC1C,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;CACtC;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,kCAAkC;IAClC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,mDAAmD;IACnD,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;GAEG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoC;gBAE/C,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,uBAAuB,CAAA;KAAO;IAQ/E;;OAEG;IACH,YAAY,CAAC,aAAa,EAAE,WAAW,EAAE,GAAG,oBAAoB,EAAE;IAIlE;;OAEG;IACH,SAAS,CAAC,WAAW,EAAE,WAAW,GAAG,oBAAoB;IAoBzD;;OAEG;IACH,aAAa,CAAC,WAAW,EAAE,WAAW,GAAG,WAAW,GAAG,SAAS;IAkBhE,OAAO,CAAC,2BAA2B;IAanC,OAAO,CAAC,mBAAmB;IAsC3B,OAAO,CAAC,UAAU;IA6BlB,OAAO,CAAC,mBAAmB;IAmB3B,OAAO,CAAC,qBAAqB;IAsC7B,OAAO,CAAC,qBAAqB;IAwB7B,OAAO,CAAC,iBAAiB;IAczB,OAAO,CAAC,qBAAqB;IAgB7B,OAAO,CAAC,0BAA0B;IAgBlC,OAAO,CAAC,sBAAsB;IAY9B;;OAEG;IACH,cAAc,CAAC,eAAe,EAAE,oBAAoB,EAAE,GAAG,MAAM;IA8D/D,OAAO,CAAC,OAAO;CAWhB"}

package/dist/src/core/discrepancy/update-recommender.js

@@ -0,0 +1,323 @@
+/**
+ * Update Recommender
+ *
+ * Generates recommendations for handling discrepancies and creates update patches.
+ *
+ * @module core/discrepancy/update-recommender
+ */
+import { consoleLogger } from '../../utils/logger.js';
+/**
+ * Generates recommendations for handling discrepancies.
+ */
+export class UpdateRecommender {
+    constructor(options = {}) {
+        this.logger = options.logger ?? consoleLogger;
+        this.config = {
+            autoUpdateTrivial: options.config?.autoUpdateTrivial ?? false,
+            generatePatches: options.config?.generatePatches ?? true,
+        };
+    }
+    /**
+     * Generate recommendations for a list of discrepancies.
+     */
+    recommendAll(discrepancies) {
+        return discrepancies.map(d => this.recommend(d));
+    }
+    /**
+     * Generate a recommendation for a single discrepancy.
+     */
+    recommend(discrepancy) {
+        const recommendation = this.mapSeverityToRecommendation(discrepancy.severity);
+        const explanation = this.generateExplanation(discrepancy, recommendation);
+        const riskLevel = this.assessRisk(discrepancy);
+        const result = {
+            discrepancyId: discrepancy.id,
+            recommendation,
+            explanation,
+            riskLevel,
+        };
+        // Generate patch if applicable
+        if (this.config.generatePatches && this.shouldGeneratePatch(discrepancy, recommendation)) {
+            result.patch = this.generatePatch(discrepancy);
+        }
+        return result;
+    }
+    /**
+     * Generate an update patch for a discrepancy.
+     */
+    generatePatch(discrepancy) {
+        // Can only generate patches for modifications and additions with spec files
+        if (!discrepancy.specPath && discrepancy.category !== 'added') {
+            return undefined;
+        }
+        switch (discrepancy.type) {
+            case 'api-route':
+                return this.generateApiRoutePatch(discrepancy);
+            case 'function-signature':
+                return this.generateFunctionPatch(discrepancy);
+            case 'type-definition':
+                return this.generateTypePatch(discrepancy);
+            default:
+                return undefined;
+        }
+    }
+    mapSeverityToRecommendation(severity) {
+        switch (severity) {
+            case 'trivial':
+                return 'auto-update';
+            case 'minor':
+                return 'review-required';
+            case 'major':
+                return 'notify';
+            case 'breaking':
+                return 'alert';
+        }
+    }
+    generateExplanation(discrepancy, recommendation) {
+        const parts = [];
+        // Category explanation
+        switch (discrepancy.category) {
+            case 'added':
+                parts.push(`New ${discrepancy.type.replace('-', ' ')} found in code that is not documented.`);
+                break;
+            case 'removed':
+                parts.push(`Documented ${discrepancy.type.replace('-', ' ')} no longer exists in code.`);
+                break;
+            case 'modified':
+                parts.push(`${discrepancy.type.replace('-', ' ')} has changed from documented version.`);
+                break;
+        }
+        // Code is source of truth reminder
+        parts.push('Code is the source of truth - specs should be updated to match.');
+        // Recommendation explanation
+        switch (recommendation) {
+            case 'auto-update':
+                parts.push('This is a trivial change that can be safely auto-updated.');
+                break;
+            case 'review-required':
+                parts.push('Please review the change before updating documentation.');
+                break;
+            case 'notify':
+                parts.push('This is a significant change that should be communicated to stakeholders.');
+                break;
+            case 'alert':
+                parts.push('⚠️ This is a breaking change! Consumers may be affected.');
+                break;
+        }
+        return parts.join(' ');
+    }
+    assessRisk(discrepancy) {
+        // Breaking changes are high risk
+        if (discrepancy.severity === 'breaking') {
+            return 'high';
+        }
+        // Removals are always at least medium risk
+        if (discrepancy.category === 'removed') {
+            return 'medium';
+        }
+        // API route changes are medium risk
+        if (discrepancy.type === 'api-route' && discrepancy.category === 'modified') {
+            return 'medium';
+        }
+        // Additions are low risk (new undocumented functionality)
+        if (discrepancy.category === 'added') {
+            return 'low';
+        }
+        // Minor modifications are low risk
+        if (discrepancy.severity === 'minor' || discrepancy.severity === 'trivial') {
+            return 'low';
+        }
+        return 'medium';
+    }
+    shouldGeneratePatch(discrepancy, recommendation) {
+        // Don't generate patches for alerts (need manual handling)
+        if (recommendation === 'alert') {
+            return false;
+        }
+        // Generate patches for auto-update and review-required
+        if (recommendation === 'auto-update' || recommendation === 'review-required') {
+            return true;
+        }
+        // Generate patches for notify if it's an addition
+        if (recommendation === 'notify' && discrepancy.category === 'added') {
+            return true;
+        }
+        return false;
+    }
+    generateApiRoutePatch(discrepancy) {
+        if (discrepancy.category === 'added') {
+            // Generate new documentation section
+            const method = discrepancy.codeValue.split(' ')[0];
+            const path = discrepancy.codeValue.split(' ')[1] || discrepancy.codeValue;
+            return {
+                filePath: discrepancy.codePath || 'docs/api.md',
+                lineNumber: 0, // Append to end
+                originalText: '',
+                newText: this.generateApiDocSection(method, path),
+                reason: 'Add documentation for new API route',
+            };
+        }
+        if (discrepancy.category === 'modified' && discrepancy.specPath) {
+            return {
+                filePath: discrepancy.specPath,
+                lineNumber: discrepancy.specLineNumber,
+                originalText: discrepancy.specValue,
+                newText: discrepancy.codeValue,
+                reason: discrepancy.description,
+            };
+        }
+        if (discrepancy.category === 'removed' && discrepancy.specPath) {
+            return {
+                filePath: discrepancy.specPath,
+                lineNumber: discrepancy.specLineNumber,
+                originalText: discrepancy.specValue,
+                newText: `~~${discrepancy.specValue}~~ *(DEPRECATED - removed from code)*`,
+                reason: 'Mark removed API route as deprecated',
+            };
+        }
+        return undefined;
+    }
+    generateFunctionPatch(discrepancy) {
+        if (discrepancy.category === 'added') {
+            return {
+                filePath: discrepancy.codePath || 'docs/api.md',
+                lineNumber: 0,
+                originalText: '',
+                newText: this.generateFunctionDocSection(discrepancy.codeValue),
+                reason: 'Add documentation for new function',
+            };
+        }
+        if (discrepancy.category === 'modified' && discrepancy.specPath) {
+            return {
+                filePath: discrepancy.specPath,
+                lineNumber: discrepancy.specLineNumber,
+                originalText: discrepancy.specValue,
+                newText: discrepancy.codeValue,
+                reason: discrepancy.description,
+            };
+        }
+        return undefined;
+    }
+    generateTypePatch(discrepancy) {
+        if (discrepancy.category === 'added') {
+            return {
+                filePath: discrepancy.codePath || 'docs/types.md',
+                lineNumber: 0,
+                originalText: '',
+                newText: this.generateTypeDocSection(discrepancy.codeValue),
+                reason: 'Add documentation for new type',
+            };
+        }
+        return undefined;
+    }
+    generateApiDocSection(method, path) {
+        return `
+## ${method} ${path}
+
+*TODO: Add description*
+
+### Request
+
+*TODO: Document request parameters*
+
+### Response
+
+*TODO: Document response format*
+`.trim();
+    }
+    generateFunctionDocSection(signature) {
+        return `
+### \`${signature}\`
+
+*TODO: Add description*
+
+#### Parameters
+
+*TODO: Document parameters*
+
+#### Returns
+
+*TODO: Document return value*
+`.trim();
+    }
+    generateTypeDocSection(typeValue) {
+        return `
+### ${typeValue}
+
+*TODO: Add type description*
+
+#### Properties
+
+*TODO: Document properties*
+`.trim();
+    }
+    /**
+     * Generate a summary report of recommendations.
+     */
+    generateReport(recommendations) {
+        const lines = ['# Discrepancy Recommendations Report', ''];
+        const byRecommendation = this.groupBy(recommendations, r => r.recommendation);
+        // Summary
+        lines.push('## Summary', '');
+        lines.push(`- Total discrepancies: ${recommendations.length}`);
+        lines.push(`- Auto-update: ${byRecommendation['auto-update']?.length ?? 0}`);
+        lines.push(`- Review required: ${byRecommendation['review-required']?.length ?? 0}`);
+        lines.push(`- Notify: ${byRecommendation['notify']?.length ?? 0}`);
+        lines.push(`- Alert: ${byRecommendation['alert']?.length ?? 0}`);
+        lines.push('');
+        // Alerts first (most important)
+        if (byRecommendation['alert']?.length) {
+            lines.push('## ⚠️ Alerts (Breaking Changes)', '');
+            for (const r of byRecommendation['alert']) {
+                lines.push(`### ${r.discrepancyId}`);
+                lines.push(r.explanation);
+                lines.push('');
+            }
+        }
+        // Notifications
+        if (byRecommendation['notify']?.length) {
+            lines.push('## 📢 Notifications (Major Changes)', '');
+            for (const r of byRecommendation['notify']) {
+                lines.push(`### ${r.discrepancyId}`);
+                lines.push(r.explanation);
+                if (r.patch) {
+                    lines.push('');
+                    lines.push('**Suggested update:**');
+                    lines.push('```');
+                    lines.push(r.patch.newText);
+                    lines.push('```');
+                }
+                lines.push('');
+            }
+        }
+        // Review required
+        if (byRecommendation['review-required']?.length) {
+            lines.push('## 👀 Review Required (Minor Changes)', '');
+            for (const r of byRecommendation['review-required']) {
+                lines.push(`- **${r.discrepancyId}**: ${r.explanation}`);
+            }
+            lines.push('');
+        }
+        // Auto-update
+        if (byRecommendation['auto-update']?.length) {
+            lines.push('## ✅ Auto-Update (Trivial Changes)', '');
+            for (const r of byRecommendation['auto-update']) {
+                lines.push(`- **${r.discrepancyId}**: ${r.explanation}`);
+            }
+            lines.push('');
+        }
+        return lines.join('\n');
+    }
+    groupBy(items, keyFn) {
+        const result = {};
+        for (const item of items) {
+            const key = keyFn(item);
+            if (!result[key]) {
+                result[key] = [];
+            }
+            result[key].push(item);
+        }
+        return result;
+    }
+}
+//# sourceMappingURL=update-recommender.js.map

package/dist/src/core/discrepancy/update-recommender.js.map

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

package/dist/src/core/living-docs/living-docs-sync.d.ts

@@ -47,26 +47,23 @@ export declare class LivingDocsSync {
      */
     syncIncrement(incrementId: string, options?: SyncOptions): Promise<SyncResult>;
     /**
-     * Get feature ID for increment (auto-generates for greenfield)
+     * Get feature ID for increment
      *
-     * CRITICAL: Validates feature ID format matches increment type (greenfield vs brownfield)
-     * - Greenfield (SpecWeave-native): FS-XXX (e.g., FS-031, FS-043)
-     * - Brownfield (imported): FS-YY-MM-DD-name (e.g., FS-25-11-14-jira-epic)
-     */
-    private getFeatureIdForIncrement;
-    /**
-     * Update metadata.json with feature_id
+     * SIMPLIFIED (v0.29.0): Feature ID is derived from increment number
+     * No longer reads from metadata.json - derivation is the single source of truth
      *
-     * CRITICAL FIX (2025-11-24): Write back generated feature_id to metadata.json
-     * This ensures:
-     * 1. feature_id persists across sessions
-     * 2. Subsequent syncs reuse the same feature_id
-     * 3. External tools (GitHub, JIRA, ADO) can find the feature
+     * CRITICAL FIX (2025-12-01): Internal features are DETERMINISTIC - no collision check!
+     * - Increment 0060 → ALWAYS FS-060, never anything else
+     * - Increment 0072 → ALWAYS FS-072, never anything else
+     * - Sync is IDEMPOTENT: if FS-060 exists, UPDATE it (don't create FS-061)
      *
-     * @param incrementId - Increment ID
-     * @param featureId - Feature ID to write
+     * Collision detection is ONLY for EXTERNAL features (FS-XXXE) during imports,
+     * NOT for internal features derived from increment numbers.
+     *
+     * @see deriveFeatureId() in src/utils/feature-id-derivation.ts
+     * @see ADR-0140 for rationale
      */
-    private updateMetadataFeatureId;
+    private getFeatureIdForIncrement;
     /**
      * Parse increment spec.md
      */

package/dist/src/core/living-docs/living-docs-sync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"living-docs-sync.d.ts","sourceRoot":"","sources":["../../../../src/core/living-docs/living-docs-sync.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAQH,OAAO,EAAE,MAAM,EAAiB,MAAM,uBAAuB,CAAC;AAK9D,OAAO,KAAK,EACV,WAAW,EACX,UAAU,EACV,UAAU,EACV,aAAa,EACb,uBAAuB,EACxB,MAAM,YAAY,CAAC;AAkBpB,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,EAAE,aAAa,EAAE,uBAAuB,EAAE,CAAC;AAE5F,qBAAa,cAAc;IACzB,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,gBAAgB,CAAmB;IAC3C,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,SAAS,CAAS;gBAEd,WAAW,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO;IAQlE;;;;;;;OAOG;IACH,YAAY,IAAI,MAAM;IAItB;;;;;OAKG;YACW,mBAAmB;IASjC;;OAEG;IACG,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;IA8KxF;;;;;;OAMG;YACW,wBAAwB;IA4DtC;;;;;;;;;;;OAWG;YACW,uBAAuB;IAiCrC;;OAEG;YACW,kBAAkB;IAmHhC;;;;OAIG;YACW,sBAAsB;IAkCpC;;OAEG;YACW,kBAAkB;IAmChC;;;;;;;OAOG;YACW,mBAAmB;IA8CjC;;;;;;OAMG;IACH;;;;;;;;;;;OAWG;YACW,mBAAmB;IA4HjC;;;;;;;;;OASG;YACW,YAAY;IA0F1B;;OAEG;YACW,UAAU;IAKxB;;OAEG;YACW,SAAS;IAKvB;;;;;;;;OAQG;YACW,4BAA4B;CAmB3C"}
+{"version":3,"file":"living-docs-sync.d.ts","sourceRoot":"","sources":["../../../../src/core/living-docs/living-docs-sync.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAQH,OAAO,EAAE,MAAM,EAAiB,MAAM,uBAAuB,CAAC;AAO9D,OAAO,KAAK,EACV,WAAW,EACX,UAAU,EACV,UAAU,EACV,aAAa,EACb,uBAAuB,EACxB,MAAM,YAAY,CAAC;AAkBpB,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,EAAE,aAAa,EAAE,uBAAuB,EAAE,CAAC;AAE5F,qBAAa,cAAc;IACzB,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,gBAAgB,CAAmB;IAC3C,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,SAAS,CAAS;gBAEd,WAAW,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO;IAQlE;;;;;;;OAOG;IACH,YAAY,IAAI,MAAM;IAItB;;;;;OAKG;YACW,mBAAmB;IASjC;;OAEG;IACG,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;IA4JxF;;;;;;;;;;;;;;;;OAgBG;YACW,wBAAwB;IAUtC;;OAEG;YACW,kBAAkB;IAmHhC;;;;OAIG;YACW,sBAAsB;IAkCpC;;OAEG;YACW,kBAAkB;IAmChC;;;;;;;OAOG;YACW,mBAAmB;IA8CjC;;;;;;OAMG;IACH;;;;;;;;;;;OAWG;YACW,mBAAmB;IA4HjC;;;;;;;;;OASG;YACW,YAAY;IA0F1B;;OAEG;YACW,UAAU;IAKxB;;OAEG;YACW,SAAS;IAKvB;;;;;;;;OAQG;YACW,4BAA4B;CAmB3C"}

package/dist/src/core/living-docs/living-docs-sync.js

@@ -23,7 +23,9 @@ import { TaskProjectSpecificGenerator } from './task-project-specific-generator.
 import { consoleLogger } from '../../utils/logger.js';
 import { autoDetectProjectIdSync } from '../../utils/project-detection.js';
 import { getGitHubAuthFromProject } from '../../utils/auth-helpers.js';
-import { findNextAvailableInternalIdSync } from '../../utils/feature-id-collision.js';
+// NOTE (2025-12-01): findNextAvailableInternalIdSync removed - internal features don't need collision check
+// Collision detection is only for EXTERNAL features (FS-XXXE) imported from GitHub/JIRA/ADO
+import { deriveFeatureId } from '../../utils/feature-id-derivation.js';
 // Import extracted helpers
 import { calculateUSStatus, extractUserStories, extractAcceptanceCriteria, generateFeatureFile, generateUserStoryFile, pathExists, readJson, ensureDir, findExistingUserStoryFile, cleanupDuplicateFiles, cleanupTempFiles, } from './sync-helpers/index.js';
 export class LivingDocsSync {
@@ -92,41 +94,22 @@ export class LivingDocsSync {
             }
             // Step 1: Build feature registry (auto-generates IDs for greenfield)
             await this.featureIdManager.buildRegistry();
-            // Step 2: Get/assign feature ID
-            // NEW (v0.23.0): Use explicitFeatureId from spec.md epic field if provided
+            // Step 2: Get feature ID (derived from increment number)
+            // SIMPLIFIED (v0.29.0): Feature ID is now always derived, not stored in metadata
             let featureId;
-            if (options.explicitFeatureId) {
+            if (options.explicitFeatureId && /^FS-\d{3,}E?$/.test(options.explicitFeatureId)) {
+                // Allow explicit override for special cases (e.g., epic linking)
                 featureId = options.explicitFeatureId;
-                this.logger.log(`📎 Using explicit feature ID from spec.md: ${featureId}`);
+                this.logger.log(`📎 Using explicit feature ID: ${featureId}`);
             }
             else {
+                // Derive from increment number (the normal case)
                 featureId = await this.getFeatureIdForIncrement(incrementId);
-                this.logger.log(`🔄 Auto-generated feature ID: ${featureId}`);
-            }
-            // CRITICAL FIX (2025-11-26): Validate featureId to prevent "null" folder bug
-            // If featureId is invalid (null, "null", empty, or not FS-XXX format), auto-generate
-            if (!featureId || featureId === 'null' || !/^FS-\d{3,}E?$/.test(featureId)) {
-                const invalidValue = featureId;
-                // Extract increment number for auto-generation
-                const match = incrementId.match(/^(\d{4})-/);
-                if (match) {
-                    const baseNum = parseInt(match[1], 10);
-                    // CRITICAL FIX (2025-11-26): Check for FS-XXXE collision before using FS-XXX
-                    const specsPath = path.join(this.projectRoot, '.specweave/docs/internal/specs');
-                    const safeNum = findNextAvailableInternalIdSync(baseNum, specsPath, this.projectId, { logger: this.logger });
-                    featureId = `FS-${String(safeNum).padStart(3, '0')}`;
-                    this.logger.warn(`⚠️ Invalid feature ID "${invalidValue}" replaced with auto-generated: ${featureId}`);
-                }
-                else {
-                    throw new Error(`Cannot sync increment ${incrementId}: invalid feature ID "${invalidValue}" and unable to auto-generate`);
-                }
+                this.logger.log(`🔄 Derived feature ID: ${featureId}`);
             }
             result.featureId = featureId;
-            // CRITICAL FIX (2025-11-24): Write feature_id back to metadata.json
-            // This ensures the generated feature_id persists and is reused on subsequent syncs
-            if (!options.dryRun) {
-                await this.updateMetadataFeatureId(incrementId, featureId);
-            }
+            // NOTE (v0.29.0): No longer write feature_id to metadata.json
+            // Feature ID is derived from increment number - see ADR-0140
             this.logger.log(`📚 Syncing ${incrementId} → ${featureId}...`);
             // Step 3: Parse increment spec
             const parsed = await this.parseIncrementSpec(incrementId);
@@ -211,94 +194,30 @@ export class LivingDocsSync {
         }
     }
     /**
-     * Get feature ID for increment (auto-generates for greenfield)
+     * Get feature ID for increment
      *
-     * CRITICAL: Validates feature ID format matches increment type (greenfield vs brownfield)
-     * - Greenfield (SpecWeave-native): FS-XXX (e.g., FS-031, FS-043)
-     * - Brownfield (imported): FS-YY-MM-DD-name (e.g., FS-25-11-14-jira-epic)
-     */
-    async getFeatureIdForIncrement(incrementId) {
-        // Extract increment number (e.g., "0040-name" → 40)
-        const match = incrementId.match(/^(\d{4})-/);
-        if (!match) {
-            throw new Error(`Invalid increment ID format: ${incrementId}`);
-        }
-        const num = parseInt(match[1], 10);
-        // Check if increment has explicit feature ID
-        const metadataPath = path.join(this.projectRoot, '.specweave/increments', incrementId, 'metadata.json');
-        if (await pathExists(metadataPath)) {
-            const metadata = await readJson(metadataPath);
-            // Check if brownfield (imported from external tool)
-            const isBrownfield = metadata.imported === true || metadata.source === 'external';
-            // CRITICAL (v0.26.2): Check for feature_id field (primary) or feature (legacy)
-            // Bug fix: metadata.json uses "feature_id" not "feature"
-            // See: Living docs sync bug report (2025-11-24)
-            const featureId = metadata.feature_id || metadata.feature;
-            if (featureId) {
-                // Validate format matches increment type
-                const isDateFormat = /^FS-\d{2}-\d{2}-\d{2}/.test(featureId);
-                const isIncrementFormat = /^FS-\d{3,}$/.test(featureId);
-                if (isBrownfield && isDateFormat) {
-                    // ✅ Brownfield with correct date format
-                    return featureId;
-                }
-                else if (!isBrownfield && isIncrementFormat) {
-                    // ✅ Greenfield with correct increment format (3+ digits)
-                    return featureId;
-                }
-                else {
-                    // ⚠️ Format mismatch - log warning and auto-generate correct format
-                    this.logger.warn(`⚠️ Feature ID format mismatch for ${incrementId}:`);
-                    this.logger.warn(`   Found: ${featureId}`);
-                    this.logger.warn(`   Expected: ${isBrownfield ? 'FS-YY-MM-DD-name (brownfield)' : 'FS-XXX (greenfield, 3+ digits)'}`);
-                    this.logger.warn(`   Auto-generating correct format...`);
-                    // Fall through to auto-generation
-                }
-            }
-        }
-        // Auto-generate for greenfield: FS-040, FS-041, etc.
-        // CRITICAL FIX (2025-11-26): Check for FS-XXXE collision before using FS-XXX
-        const specsPath = path.join(this.projectRoot, '.specweave/docs/internal/specs');
-        const safeNum = findNextAvailableInternalIdSync(num, specsPath, this.projectId, { logger: this.logger });
-        const autoGenId = `FS-${String(safeNum).padStart(3, '0')}`;
-        this.logger.log(`   📝 Generated feature ID: ${autoGenId}`);
-        return autoGenId;
-    }
-    /**
-     * Update metadata.json with feature_id
+     * SIMPLIFIED (v0.29.0): Feature ID is derived from increment number
+     * No longer reads from metadata.json - derivation is the single source of truth
      *
-     * CRITICAL FIX (2025-11-24): Write back generated feature_id to metadata.json
-     * This ensures:
-     * 1. feature_id persists across sessions
-     * 2. Subsequent syncs reuse the same feature_id
-     * 3. External tools (GitHub, JIRA, ADO) can find the feature
+     * CRITICAL FIX (2025-12-01): Internal features are DETERMINISTIC - no collision check!
+     * - Increment 0060 → ALWAYS FS-060, never anything else
+     * - Increment 0072 → ALWAYS FS-072, never anything else
+     * - Sync is IDEMPOTENT: if FS-060 exists, UPDATE it (don't create FS-061)
      *
-     * @param incrementId - Increment ID
-     * @param featureId - Feature ID to write
+     * Collision detection is ONLY for EXTERNAL features (FS-XXXE) during imports,
+     * NOT for internal features derived from increment numbers.
+     *
+     * @see deriveFeatureId() in src/utils/feature-id-derivation.ts
+     * @see ADR-0140 for rationale
      */
-    async updateMetadataFeatureId(incrementId, featureId) {
-        const metadataPath = path.join(this.projectRoot, '.specweave/increments', incrementId, 'metadata.json');
-        try {
-            if (!await pathExists(metadataPath)) {
-                this.logger.warn(`   ⚠️  metadata.json not found for ${incrementId}, skipping feature_id update`);
-                return;
-            }
-            const metadata = await readJson(metadataPath);
-            // Only update if feature_id is null/undefined or different
-            if (metadata.feature_id !== featureId) {
-                metadata.feature_id = featureId;
-                // Atomic write: temp file → rename
-                const tempPath = `${metadataPath}.tmp`;
-                await fs.writeFile(tempPath, JSON.stringify(metadata, null, 2), 'utf-8');
-                await fs.rename(tempPath, metadataPath);
-                this.logger.log(`   ✅ Updated metadata.json with feature_id: ${featureId}`);
-            }
-        }
-        catch (error) {
-            // Non-fatal - log warning but continue with sync
-            this.logger.warn(`   ⚠️  Failed to update metadata.json with feature_id: ${error}`);
-        }
+    async getFeatureIdForIncrement(incrementId) {
+        // Derive feature ID directly from increment number (e.g., "0081-name" → "FS-081")
+        // NO collision checking - internal feature IDs are deterministic and unique by design
+        return deriveFeatureId(incrementId);
     }
+    // NOTE (v0.29.0): updateMetadataFeatureId() was REMOVED
+    // Feature ID is now derived from increment number, not stored in metadata
+    // See ADR-0140 for rationale
     /**
      * Parse increment spec.md
      */