@planu/cli 0.63.7 → 0.64.0

package/dist/engine/living-spec/auto-updater.js

@@ -0,0 +1,311 @@
+/**
+ * engine/living-spec/auto-updater.ts — SPEC-170: Auto-update specs from code changes
+ *
+ * Pure functions that analyse a git-style code diff, map changed functions to
+ * acceptance criteria, and propose (or apply) spec updates.
+ *
+ * Design:
+ * - mapDiffToAcs: heuristic matching between diff functions and AC text
+ * - generateSpecUpdate: applies proposals onto existing spec content
+ * - autoUpdateSpecFromCode: orchestrates the full pipeline
+ */
+// ---------------------------------------------------------------------------
+// Diff parsing
+// ---------------------------------------------------------------------------
+/**
+ * Extract function-level changes from a unified diff string.
+ * Detects `+function`, `-function`, `+async function`, `+export function`, etc.
+ */
+export function parseDiffFunctions(diff) {
+    const functions = [];
+    const lines = diff.split('\n');
+    const funcPattern = /^([+-])\s*(?:export\s+)?(?:async\s+)?(?:function\s+(\w+)|(?:const|let|var)\s+(\w+)\s*=\s*(?:async\s+)?\(?)/;
+    for (const line of lines) {
+        const match = funcPattern.exec(line);
+        if (!match) {
+            continue;
+        }
+        const prefix = match[1];
+        const name = match[2] ?? match[3] ?? '';
+        if (!name) {
+            continue;
+        }
+        const changeType = prefix === '+' ? 'added' : 'removed';
+        const snippet = line.slice(1).trim();
+        // Merge with previous entry if same name appears as both removed then added (= modified)
+        const existing = functions.find((f) => f.name === name);
+        if (existing) {
+            existing.changeType = 'modified';
+        }
+        else {
+            functions.push({ name, changeType, snippet });
+        }
+    }
+    return functions;
+}
+// ---------------------------------------------------------------------------
+// AC extraction helpers
+// ---------------------------------------------------------------------------
+/**
+ * Extract acceptance criteria lines from spec markdown content.
+ * Looks for ALL checklist items (`- [ ] ...` or `- [x] ...`) in the document,
+ * regardless of section. Returns them with sequential numeric counters.
+ *
+ * Note: differs from the shared `extractAcceptanceCriteria` (ac-extractor.ts) which
+ * requires an explicit "Acceptance Criteria" section header and is used for diffing.
+ */
+export function extractAcsFromSpec(specContent) {
+    const acs = [];
+    let counter = 0;
+    for (const line of specContent.split('\n')) {
+        const acMatch = /^-\s+\[[ xX]\]\s+(.+)$/.exec(line.trim());
+        if (acMatch) {
+            counter++;
+            acs.push({ number: counter, description: (acMatch[1] ?? '').trim() });
+        }
+    }
+    return acs;
+}
+// ---------------------------------------------------------------------------
+// Keyword-based confidence scoring
+// ---------------------------------------------------------------------------
+/**
+ * Compute a similarity score (0-1) between a function name and an AC description.
+ * Uses word overlap and camelCase decomposition.
+ */
+function scoreSimilarity(funcName, acDescription) {
+    // Decompose camelCase into words
+    const funcWords = funcName
+        .replace(/([A-Z])/g, ' $1')
+        .toLowerCase()
+        .split(/[\s_-]+/)
+        .filter(Boolean);
+    const acWords = acDescription
+        .toLowerCase()
+        .replace(/[^a-z0-9\s]/g, ' ')
+        .split(/\s+/)
+        .filter((w) => w.length > 2);
+    if (funcWords.length === 0 || acWords.length === 0) {
+        return 0;
+    }
+    const funcSet = new Set(funcWords);
+    const matches = acWords.filter((w) => funcSet.has(w)).length;
+    return matches / Math.max(funcWords.length, acWords.length);
+}
+/**
+ * Determine confidence level from a numeric score.
+ */
+function scoreToConfidence(score) {
+    if (score >= 0.4) {
+        return 'high';
+    }
+    if (score >= 0.2) {
+        return 'medium';
+    }
+    return 'low';
+}
+// ---------------------------------------------------------------------------
+// Core mapping
+// ---------------------------------------------------------------------------
+/**
+ * Map diff functions to acceptance criteria using keyword heuristics.
+ *
+ * For each changed function:
+ * - If it matches one or more ACs → emit 'mark-covered' or 'update-progress'
+ * - If removed and matches an AC → emit 'flag-obsolete'
+ * - If no AC matches at all → emit 'suggest-new-ac'
+ */
+export function mapDiffToAcs(functions, acs, config = { minConfidence: 'low', suggestNewAcs: true, flagObsolete: true }) {
+    const mappings = [];
+    const confidenceOrder = { high: 3, medium: 2, low: 1 };
+    const minOrder = confidenceOrder[config.minConfidence];
+    for (const fn of functions) {
+        let bestScore = 0;
+        let bestAc = null;
+        for (const ac of acs) {
+            const score = scoreSimilarity(fn.name, ac.description);
+            if (score > bestScore) {
+                bestScore = score;
+                bestAc = ac;
+            }
+        }
+        const confidence = scoreToConfidence(bestScore);
+        const order = confidenceOrder[confidence];
+        if (bestAc !== null && order >= minOrder) {
+            const updateType = resolveUpdateType(fn.changeType, confidence);
+            if (config.flagObsolete || updateType !== 'flag-obsolete') {
+                mappings.push({
+                    diffFunction: fn,
+                    acNumber: bestAc.number,
+                    acDescription: bestAc.description,
+                    updateType,
+                    confidence,
+                });
+            }
+        }
+        else if (fn.changeType === 'added' && config.suggestNewAcs) {
+            // New function with no matching AC → suggest a new AC
+            mappings.push({
+                diffFunction: fn,
+                acNumber: 0,
+                acDescription: '',
+                updateType: 'suggest-new-ac',
+                confidence: 'low',
+            });
+        }
+    }
+    return mappings;
+}
+/** Determine the update type from change type and confidence. */
+function resolveUpdateType(changeType, confidence) {
+    if (changeType === 'removed') {
+        return 'flag-obsolete';
+    }
+    if (confidence === 'high') {
+        return 'mark-covered';
+    }
+    return 'update-progress';
+}
+// ---------------------------------------------------------------------------
+// Spec content patching
+// ---------------------------------------------------------------------------
+/**
+ * Build SpecUpdateProposals from AcMappings.
+ */
+export function buildProposals(mappings, specId) {
+    const proposals = [];
+    for (const mapping of mappings) {
+        if (mapping.updateType === 'suggest-new-ac') {
+            proposals.push({
+                acNumber: 0,
+                description: `New function "${mapping.diffFunction.name}" has no matching AC — consider adding one`,
+                action: 'suggest-new-ac',
+                patch: `- [ ] [AUTO] Implement \`${mapping.diffFunction.name}\``,
+            });
+            continue;
+        }
+        if (mapping.updateType === 'flag-obsolete') {
+            proposals.push({
+                acNumber: mapping.acNumber,
+                description: `Function "${mapping.diffFunction.name}" was removed — AC-${mapping.acNumber} may be obsolete`,
+                action: 'flag-obsolete',
+                patch: `<!-- POSSIBLY OBSOLETE: AC-${mapping.acNumber} (${mapping.acDescription}) — function "${mapping.diffFunction.name}" was removed. Verify. -->`,
+            });
+            continue;
+        }
+        if (mapping.updateType === 'mark-covered') {
+            proposals.push({
+                acNumber: mapping.acNumber,
+                description: `Function "${mapping.diffFunction.name}" implements AC-${mapping.acNumber} — mark as covered`,
+                action: 'mark-covered',
+                patch: `<!-- AUTO-COVERED by ${specId} via \`${mapping.diffFunction.name}\` -->`,
+            });
+            continue;
+        }
+        // update-progress
+        proposals.push({
+            acNumber: mapping.acNumber,
+            description: `Function "${mapping.diffFunction.name}" modified — AC-${mapping.acNumber} progress updated`,
+            action: 'update-progress',
+            patch: `<!-- PROGRESS UPDATE: AC-${mapping.acNumber} affected by \`${mapping.diffFunction.name}\` change -->`,
+        });
+    }
+    return proposals;
+}
+/**
+ * Apply proposals onto existing spec content and return the updated string.
+ *
+ * Strategy: append a changelog section at the end of the spec with all patches.
+ * Marking individual ACs in-place would require complex line manipulation, so
+ * instead we append a structured "Auto-sync changelog" section.
+ */
+export function generateSpecUpdate(proposals, specContent) {
+    if (proposals.length === 0) {
+        return specContent;
+    }
+    const now = new Date().toISOString();
+    const lines = [
+        '',
+        '<!-- AUTO-SYNC CHANGELOG — generated by auto_update_spec -->',
+        `<!-- ${now} -->`,
+    ];
+    for (const proposal of proposals) {
+        lines.push(`<!-- [${proposal.action.toUpperCase()}] AC-${proposal.acNumber || 'NEW'}: ${proposal.description} -->`);
+        if (proposal.patch) {
+            lines.push(proposal.patch);
+        }
+    }
+    lines.push('<!-- END AUTO-SYNC CHANGELOG -->');
+    return `${specContent}\n${lines.join('\n')}\n`;
+}
+// ---------------------------------------------------------------------------
+// Main orchestrator
+// ---------------------------------------------------------------------------
+/**
+ * Analyse a code diff and produce auto-update proposals for a spec.
+ *
+ * @param specId - The spec to update.
+ * @param codeDiff - Unified diff string. If empty, returns empty result.
+ * @param specContent - Current markdown content of the spec.
+ * @param autoApply - When true, apply proposals and return the updated content.
+ * @param config - Optional configuration overrides.
+ */
+export function autoUpdateSpecFromCode(specId, codeDiff, specContent, autoApply = false, config = { minConfidence: 'low', suggestNewAcs: true, flagObsolete: true }) {
+    const analyzedAt = new Date().toISOString();
+    if (!codeDiff.trim()) {
+        return {
+            specId,
+            mappings: [],
+            proposals: [],
+            updatedSpecContent: null,
+            applied: false,
+            summary: 'No code diff provided — nothing to analyse.',
+            analyzedAt,
+        };
+    }
+    const functions = parseDiffFunctions(codeDiff);
+    const acs = extractAcsFromSpec(specContent);
+    const mappings = mapDiffToAcs(functions, acs, config);
+    const proposals = buildProposals(mappings, specId);
+    let updatedSpecContent = null;
+    let applied = false;
+    if (autoApply && proposals.length > 0) {
+        updatedSpecContent = generateSpecUpdate(proposals, specContent);
+        applied = true;
+    }
+    const summary = buildSummary(functions, mappings, proposals, applied);
+    return {
+        specId,
+        mappings,
+        proposals,
+        updatedSpecContent,
+        applied,
+        summary,
+        analyzedAt,
+    };
+}
+// ---------------------------------------------------------------------------
+// Private helpers
+// ---------------------------------------------------------------------------
+function buildSummary(functions, mappings, proposals, applied) {
+    const added = functions.filter((f) => f.changeType === 'added').length;
+    const modified = functions.filter((f) => f.changeType === 'modified').length;
+    const removed = functions.filter((f) => f.changeType === 'removed').length;
+    const newAcCount = proposals.filter((p) => p.action === 'suggest-new-ac').length;
+    const coveredCount = proposals.filter((p) => p.action === 'mark-covered').length;
+    const obsoleteCount = proposals.filter((p) => p.action === 'flag-obsolete').length;
+    const progressCount = proposals.filter((p) => p.action === 'update-progress').length;
+    const parts = [
+        `Analysed ${functions.length} function change(s): ${added} added, ${modified} modified, ${removed} removed.`,
+        `Mapped to ${mappings.length} AC(s).`,
+        `Proposals: ${coveredCount} mark-covered, ${progressCount} update-progress, ${obsoleteCount} flag-obsolete, ${newAcCount} suggest-new-ac.`,
+    ];
+    if (applied) {
+        parts.push('Changes applied to spec content.');
+    }
+    else if (proposals.length > 0) {
+        parts.push('Use autoApply=true to apply changes.');
+    }
+    return parts.join(' ');
+}
+//# sourceMappingURL=auto-updater.js.map

package/dist/engine/living-spec/auto-updater.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-updater.js","sourceRoot":"","sources":["../../../src/engine/living-spec/auto-updater.ts"],"names":[],"mappings":"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"}

package/dist/engine/living-spec/conflict-resolver.d.ts

@@ -0,0 +1,46 @@
+/**
+ * engine/living-spec/conflict-resolver.ts — SPEC-172: Merge conflict resolution
+ *
+ * Pure functions for detecting and resolving conflicts between spec changes and
+ * code changes that occur simultaneously. Supports configurable resolution policies
+ * and generates git-style conflict markers for unresolved conflicts.
+ */
+import type { ConflictCategory, ConflictItem, MergeConflictResolution, CodeDiff, MergeSpecDiff, ResolvedConflict, ResolutionPolicy } from '../../types/index.js';
+/**
+ * Compute a simple line-level diff between two spec strings.
+ * Delegates to the shared line-diff utility and adds change detection.
+ */
+export declare function computeSpecDiff(originalSpec: string, newSpec: string): MergeSpecDiff;
+/**
+ * Build a CodeDiff from a list of changed file paths.
+ * File paths prefixed with '+' are added, '-' removed, otherwise modified.
+ */
+export declare function buildCodeDiff(codeChanges: string[]): CodeDiff;
+/**
+ * Categorize a conflict item as semantic, structural, or cosmetic.
+ *
+ * - semantic: spec acceptance criteria directly contradict code behavior
+ * - structural: additions/removals that create structural mismatches
+ * - cosmetic: naming differences, whitespace, or formatting changes only
+ */
+export declare function categorizeConflict(conflict: ConflictItem): ConflictCategory;
+/**
+ * Detect conflicts between a spec diff and a code diff.
+ * Returns conflict items representing mismatches that need resolution.
+ */
+export declare function detectConflicts(specDiff: MergeSpecDiff, codeDiff: CodeDiff): ConflictItem[];
+/**
+ * Attempt to auto-resolve a single conflict using the given policy.
+ * Returns null if the policy requires human review (always-ask).
+ */
+export declare function autoResolve(conflict: ConflictItem, policy: ResolutionPolicy): ResolvedConflict | null;
+/**
+ * Resolve spec conflicts between an original spec, a new spec version, and code changes.
+ * Returns a MergeConflictResolution with auto-resolved conflicts and those pending human review.
+ */
+export declare function resolveSpecConflict(originalSpec: string, newSpec: string, codeChanges: string[], specId: string, policy?: ResolutionPolicy): MergeConflictResolution;
+/**
+ * Generate git-style conflict markers for unresolved conflicts.
+ */
+export declare function generateConflictMarkers(pendingConflicts: ConflictItem[], originalSpec: string, newSpec: string): string[];
+//# sourceMappingURL=conflict-resolver.d.ts.map

package/dist/engine/living-spec/conflict-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conflict-resolver.d.ts","sourceRoot":"","sources":["../../../src/engine/living-spec/conflict-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EACV,gBAAgB,EAChB,YAAY,EACZ,uBAAuB,EACvB,QAAQ,EACR,aAAa,EACb,gBAAgB,EAChB,gBAAgB,EACjB,MAAM,sBAAsB,CAAC;AAO9B;;;GAGG;AACH,wBAAgB,eAAe,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,aAAa,CAgBpF;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,QAAQ,CAiB7D;AAMD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,YAAY,GAAG,gBAAgB,CAqB3E;AAMD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,aAAa,EAAE,QAAQ,EAAE,QAAQ,GAAG,YAAY,EAAE,CAoF3F;AAMD;;;GAGG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAE,YAAY,EACtB,MAAM,EAAE,gBAAgB,GACvB,gBAAgB,GAAG,IAAI,CAgDzB;AAMD;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EAAE,EACrB,MAAM,EAAE,MAAM,EACd,MAAM,GAAE,gBAA+B,GACtC,uBAAuB,CA8BzB;AAMD;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,gBAAgB,EAAE,YAAY,EAAE,EAChC,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,MAAM,GACd,MAAM,EAAE,CAwBV"}

package/dist/engine/living-spec/conflict-resolver.js

@@ -0,0 +1,301 @@
+/**
+ * engine/living-spec/conflict-resolver.ts — SPEC-172: Merge conflict resolution
+ *
+ * Pure functions for detecting and resolving conflicts between spec changes and
+ * code changes that occur simultaneously. Supports configurable resolution policies
+ * and generates git-style conflict markers for unresolved conflicts.
+ */
+import { createHash } from 'node:crypto';
+import { computeLineDiff } from '../shared/line-diff.js';
+// ---------------------------------------------------------------------------
+// Diff utilities
+// ---------------------------------------------------------------------------
+/**
+ * Compute a simple line-level diff between two spec strings.
+ * Delegates to the shared line-diff utility and adds change detection.
+ */
+export function computeSpecDiff(originalSpec, newSpec) {
+    const { added, removed } = computeLineDiff(originalSpec, newSpec);
+    const changed = [];
+    // Detect changed lines: lines whose prefix (first word) matches but content differs
+    for (const addedLine of added) {
+        const prefix = addedLine.split(' ')[0] ?? '';
+        if (prefix.length > 3) {
+            const matchingRemoved = removed.find((r) => r.startsWith(prefix));
+            if (matchingRemoved !== undefined) {
+                changed.push(`${matchingRemoved} → ${addedLine}`);
+            }
+        }
+    }
+    return { added, removed, changed };
+}
+/**
+ * Build a CodeDiff from a list of changed file paths.
+ * File paths prefixed with '+' are added, '-' removed, otherwise modified.
+ */
+export function buildCodeDiff(codeChanges) {
+    const addedFiles = [];
+    const removedFiles = [];
+    const modifiedFiles = [];
+    const diffLines = [...codeChanges];
+    for (const change of codeChanges) {
+        if (change.startsWith('+')) {
+            addedFiles.push(change.slice(1).trim());
+        }
+        else if (change.startsWith('-')) {
+            removedFiles.push(change.slice(1).trim());
+        }
+        else {
+            modifiedFiles.push(change.trim());
+        }
+    }
+    return { addedFiles, removedFiles, modifiedFiles, diffLines };
+}
+// ---------------------------------------------------------------------------
+// Conflict categorization
+// ---------------------------------------------------------------------------
+/**
+ * Categorize a conflict item as semantic, structural, or cosmetic.
+ *
+ * - semantic: spec acceptance criteria directly contradict code behavior
+ * - structural: additions/removals that create structural mismatches
+ * - cosmetic: naming differences, whitespace, or formatting changes only
+ */
+export function categorizeConflict(conflict) {
+    const specLower = conflict.specSide.toLowerCase();
+    const codeLower = conflict.codeSide.toLowerCase();
+    // Structural: one side has addition/removal the other lacks
+    const structuralKeywords = ['added', 'removed', 'deleted', 'new function', 'missing'];
+    for (const kw of structuralKeywords) {
+        if (codeLower.includes(kw) || specLower.includes(kw)) {
+            return 'structural';
+        }
+    }
+    // Cosmetic: only naming/casing differences
+    const specNormalized = specLower.replace(/[\s_-]/g, '');
+    const codeNormalized = codeLower.replace(/[\s_-]/g, '');
+    if (specNormalized === codeNormalized) {
+        return 'cosmetic';
+    }
+    // Default: semantic
+    return 'semantic';
+}
+// ---------------------------------------------------------------------------
+// Conflict detection
+// ---------------------------------------------------------------------------
+/**
+ * Detect conflicts between a spec diff and a code diff.
+ * Returns conflict items representing mismatches that need resolution.
+ */
+export function detectConflicts(specDiff, codeDiff) {
+    const conflicts = [];
+    const now = new Date().toISOString();
+    // Structural: spec adds ACs but code removes files
+    if (specDiff.added.length > 0 && codeDiff.removedFiles.length > 0) {
+        for (const addedLine of specDiff.added) {
+            if (isAcceptanceCriterion(addedLine)) {
+                for (const removedFile of codeDiff.removedFiles) {
+                    const id = generateConflictId(addedLine, removedFile);
+                    conflicts.push({
+                        id,
+                        specId: '',
+                        description: `Spec adds AC but code removed file: ${removedFile}`,
+                        specSide: addedLine,
+                        codeSide: `removed file: ${removedFile}`,
+                        category: 'structural',
+                        detectedAt: now,
+                    });
+                }
+            }
+        }
+    }
+    // Structural: spec removes ACs but code adds files implementing them
+    if (specDiff.removed.length > 0 && codeDiff.addedFiles.length > 0) {
+        for (const removedLine of specDiff.removed) {
+            if (isAcceptanceCriterion(removedLine)) {
+                for (const addedFile of codeDiff.addedFiles) {
+                    const id = generateConflictId(removedLine, addedFile);
+                    conflicts.push({
+                        id,
+                        specId: '',
+                        description: `Spec removes AC but code added file: ${addedFile}`,
+                        specSide: `removed: ${removedLine}`,
+                        codeSide: `added file: ${addedFile}`,
+                        category: 'structural',
+                        detectedAt: now,
+                    });
+                }
+            }
+        }
+    }
+    // Semantic: spec changed existing ACs while code also modified files
+    if (specDiff.changed.length > 0 && codeDiff.modifiedFiles.length > 0) {
+        for (const changedLine of specDiff.changed) {
+            const id = generateConflictId(changedLine, codeDiff.modifiedFiles.join(','));
+            conflicts.push({
+                id,
+                specId: '',
+                description: `Spec AC changed while code was also modified`,
+                specSide: changedLine,
+                codeSide: `modified files: ${codeDiff.modifiedFiles.join(', ')}`,
+                category: 'semantic',
+                detectedAt: now,
+            });
+        }
+    }
+    // Cosmetic: spec has renamed items that differ only in casing/format from code
+    for (const addedLine of specDiff.added) {
+        for (const modifiedFile of codeDiff.modifiedFiles) {
+            const baseName = modifiedFile
+                .replace(/\.[^.]+$/, '')
+                .split('/')
+                .pop() ?? '';
+            if (isCosmeticMismatch(addedLine, baseName)) {
+                const id = generateConflictId(addedLine, modifiedFile);
+                conflicts.push({
+                    id,
+                    specId: '',
+                    description: `Cosmetic naming mismatch between spec and code`,
+                    specSide: addedLine,
+                    codeSide: modifiedFile,
+                    category: 'cosmetic',
+                    detectedAt: now,
+                });
+            }
+        }
+    }
+    return conflicts;
+}
+// ---------------------------------------------------------------------------
+// Auto-resolution
+// ---------------------------------------------------------------------------
+/**
+ * Attempt to auto-resolve a single conflict using the given policy.
+ * Returns null if the policy requires human review (always-ask).
+ */
+export function autoResolve(conflict, policy) {
+    if (policy === 'always-ask') {
+        return null;
+    }
+    const now = new Date().toISOString();
+    if (policy === 'code-wins') {
+        // Cosmetic conflicts are always safe to auto-resolve with code-wins
+        // Structural and semantic: code wins for implementation details
+        if (conflict.category === 'semantic' && !isImplementationDetail(conflict)) {
+            return null; // Semantic AC conflicts need human review even with code-wins
+        }
+        return {
+            conflict,
+            appliedPolicy: policy,
+            winner: 'code',
+            explanation: `code-wins policy: code state accepted for ${conflict.category} conflict`,
+            resolvedAt: now,
+        };
+    }
+    if (policy === 'spec-wins') {
+        // Spec wins for acceptance criteria by definition
+        if (conflict.category === 'structural' && conflict.codeSide.startsWith('removed file')) {
+            return null; // Cannot auto-resolve structural removal without human verification
+        }
+        return {
+            conflict,
+            appliedPolicy: policy,
+            winner: 'spec',
+            explanation: `spec-wins policy: spec state accepted for ${conflict.category} conflict`,
+            resolvedAt: now,
+        };
+    }
+    // policy === 'most-recent': cosmetic conflicts resolve to spec; others need human review
+    if (conflict.category === 'cosmetic') {
+        return {
+            conflict,
+            appliedPolicy: policy,
+            winner: 'spec',
+            explanation: `most-recent policy: spec is treated as most recent for cosmetic conflicts`,
+            resolvedAt: now,
+        };
+    }
+    // For semantic/structural, most-recent cannot determine winner without timestamps
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Main orchestrator
+// ---------------------------------------------------------------------------
+/**
+ * Resolve spec conflicts between an original spec, a new spec version, and code changes.
+ * Returns a MergeConflictResolution with auto-resolved conflicts and those pending human review.
+ */
+export function resolveSpecConflict(originalSpec, newSpec, codeChanges, specId, policy = 'always-ask') {
+    const specDiff = computeSpecDiff(originalSpec, newSpec);
+    const codeDiff = buildCodeDiff(codeChanges);
+    const rawConflicts = detectConflicts(specDiff, codeDiff);
+    // Attach specId to all conflicts
+    const conflicts = rawConflicts.map((c) => ({ ...c, specId }));
+    const autoResolved = [];
+    const pendingReview = [];
+    for (const conflict of conflicts) {
+        const resolution = autoResolve(conflict, policy);
+        if (resolution !== null) {
+            autoResolved.push(resolution);
+        }
+        else {
+            pendingReview.push(conflict);
+        }
+    }
+    const conflictMarkers = generateConflictMarkers(pendingReview, originalSpec, newSpec);
+    return {
+        specId,
+        autoResolved,
+        pendingReview,
+        conflictMarkers,
+        resolvedAt: new Date().toISOString(),
+    };
+}
+// ---------------------------------------------------------------------------
+// Conflict marker generation
+// ---------------------------------------------------------------------------
+/**
+ * Generate git-style conflict markers for unresolved conflicts.
+ */
+export function generateConflictMarkers(pendingConflicts, originalSpec, newSpec) {
+    if (pendingConflicts.length === 0) {
+        return [];
+    }
+    const markers = [];
+    for (const conflict of pendingConflicts) {
+        markers.push(`<<<< SPEC (${conflict.id})`, conflict.specSide, `====`, conflict.codeSide, `>>>> CODE`, `# Conflict: ${conflict.description} (category: ${conflict.category})`, '');
+    }
+    // Suppress unused variable warnings — params are available for future context use
+    void originalSpec;
+    void newSpec;
+    return markers;
+}
+// ---------------------------------------------------------------------------
+// Private helpers
+// ---------------------------------------------------------------------------
+function generateConflictId(a, b) {
+    // Content-based hash: same inputs always produce the same conflict ID,
+    // enabling idempotent conflict detection across multiple runs.
+    return createHash('sha256').update(`${a}:${b}`).digest('hex').slice(0, 12);
+}
+function isAcceptanceCriterion(line) {
+    const lower = line.toLowerCase();
+    return (lower.includes('- [ ]') ||
+        lower.includes('- [x]') ||
+        lower.includes('ac-') ||
+        lower.startsWith('acceptance'));
+}
+function isCosmeticMismatch(specLine, codeName) {
+    const specNorm = specLine.toLowerCase().replace(/[\s_-]/g, '');
+    const codeNorm = codeName.toLowerCase().replace(/[\s_-]/g, '');
+    return (specNorm !== codeNorm &&
+        specNorm.length > 3 &&
+        codeNorm.length > 3 &&
+        (specNorm.includes(codeNorm) || codeNorm.includes(specNorm)));
+}
+function isImplementationDetail(conflict) {
+    const implKeywords = ['implementation', 'refactor', 'rename', 'move', 'extract'];
+    const lower = conflict.description.toLowerCase();
+    return implKeywords.some((kw) => lower.includes(kw));
+}
+//# sourceMappingURL=conflict-resolver.js.map