happyskills 0.18.1 → 0.20.0

package/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.20.0] - 2026-03-30
+
+### Added
+- Add `--full-report` flag to `pull` command for AI agent semantic review (Layer 2 enablement) — when combined with `--json`, includes inline file content (`base_content`, `local_content`, `remote_content`, `merged_content`) for all changed files and action-typed `resolution_steps` (resolve_conflict_markers, review_json_suggestions, semantic_review, verify)
+- Add `enrich_file_content()` and `build_resolution_steps()` to merge report module — deterministic resolution steps guide the consuming LLM through conflict resolution, JSON suggestion review, cross-file semantic consistency checks, and verification
+
+## [0.19.0] - 2026-03-29
+
+### Added
+- Add three-way auto-merge to `pull` — when both local and remote have changes and no `--theirs`/`--ours` flag is set, `pull` now auto-merges using `node-diff3` for text files, structured JSON merge for `skill.json` (always valid JSON, no conflict markers), and section-aware merge for `CHANGELOG.md` (preserves remote history, prepends local sections)
+- Add `conflict_files` tracking in lock file — `pull` writes an array of files with unresolved conflict markers to the lock entry; `status` shows `conflicts` state when present
+- Add conflict marker validation (`validate_no_conflict_markers`) to `validate` and `publish` — scans all skill files for `<<<<<<< LOCAL` markers and blocks publishing with errors. `--force` does NOT bypass this check (it only bypasses divergence)
+- Add `conflicts` status to `status` command for skills with unresolved merge conflicts
+
+### Changed
+- `pull` without `--theirs`/`--ours` no longer exits with an error on `both_modified` files — it attempts auto-merge and reports any remaining conflicts with marker locations
+
 ## [0.18.1] - 2026-03-29
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "happyskills",
-	"version": "0.18.1",
+	"version": "0.20.0",
 	"description": "Package manager for AI agent skills",
 	"license": "SEE LICENSE IN LICENSE",
 	"author": "Nicolas Dao <nic@cloudlesslabs.com> (https://cloudlesslabs.com)",
@@ -43,6 +43,7 @@
 		"node": ">=22.0.0"
 	},
 	"dependencies": {
+		"node-diff3": "^3.2.0",
 		"puffy-core": "^1.3.1",
 		"semver": "^7.6.0"
 	},

package/src/commands/publish.js

@@ -16,6 +16,7 @@ const { hash_directory } = require('../lock/integrity')
 const { validate_skill_md } = require('../validation/skill_md_rules')
 const { validate_skill_json } = require('../validation/skill_json_rules')
 const { validate_cross } = require('../validation/cross_rules')
+const { validate_no_conflict_markers } = require('../validation/conflict_marker_rules')
 const { create_spinner } = require('../ui/spinner')
 const { print_help, print_success, print_error, print_warn, print_hint, print_json, code } = require('../ui/output')
 const { exit_with_error, UsageError, CliError } = require('../utils/errors')
@@ -95,8 +96,10 @@ const run = (args) => catch_errors('Publish failed', async () => {
 	if (json_err) throw json_err
 	const [cross_err, cross_results] = await validate_cross(dir, md_data.frontmatter, json_data.manifest, md_data.content, skill_type)
 	if (cross_err) throw cross_err
+	const [marker_err, marker_results] = await validate_no_conflict_markers(dir)
+	if (marker_err) throw marker_err
 
-	const all_results = [...md_data.results, ...json_data.results, ...cross_results]
+	const all_results = [...md_data.results, ...json_data.results, ...cross_results, ...marker_results]
 	const validation_errors = all_results.filter(r => r.severity === 'error')
 	const validation_warnings = all_results.filter(r => r.severity === 'warning')
 

package/src/commands/pull.js

@@ -5,7 +5,10 @@ const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
 const repos_api = require('../api/repos')
 const { detect_status } = require('../merge/detector')
 const { classify_changes } = require('../merge/comparator')
-const { build_report } = require('../merge/report')
+const { build_report, enrich_file_content, build_resolution_steps } = require('../merge/report')
+const { three_way_merge } = require('../merge/text_merge')
+const { merge_skill_json } = require('../merge/json_merge')
+const { merge_changelog } = require('../merge/changelog_merge')
 const { hash_blob } = require('../utils/git_hash')
 const { read_lock, get_all_locked_skills } = require('../lock/reader')
 const { write_lock, update_lock_skills } = require('../lock/writer')
@@ -30,14 +33,17 @@ Options:
   --force           Discard all local changes, take remote entirely
   -g, --global      Pull globally installed skill
   --json            Output as JSON
+  --full-report     Include inline file content and resolution steps in JSON output (for AI agent review)
 
 Examples:
   happyskills pull acme/deploy-aws
   happyskills pull acme/deploy-aws --theirs
-  happyskills pull acme/deploy-aws --force`
+  happyskills pull acme/deploy-aws --json --full-report`
 
 // ─── Helpers ──────────────────────────────────────────────────────────────────
 
+const decode_b64 = (file) => file ? Buffer.from(file.content, 'base64').toString('utf-8') : undefined
+
 const build_local_entries = (skill_dir) => catch_errors('Failed to build local entries', async () => {
 	const entries = []
 	const walk = async (dir, prefix) => {
@@ -100,6 +106,7 @@ const run = (args) => catch_errors('Pull failed', async () => {
 
 	const is_global = args.flags.global || false
 	const strategy = args.flags.theirs ? 'theirs' : args.flags.ours ? 'ours' : args.flags.force ? 'force' : null
+	const full_report = !!(args.flags.json && args.flags['full-report'])
 	const project_root = find_project_root()
 
 	// 1. Read lock file
@@ -205,26 +212,86 @@ const run = (args) => catch_errors('Pull failed', async () => {
 	const classified = classify_changes(base_files, local_files, remote_files)
 	const report = build_report(skill_name, lock_entry.version, cmp_data.head_version, classified)
 
-	// If both_modified exists and no strategy → exit with report
+	// Apply changes
+	spinner.update('Applying changes...')
+	const base_file_map = new Map((base_clone.files || []).map(f => [f.path, f]))
+	const remote_file_map = new Map((remote_clone.files || []).map(f => [f.path, f]))
+
+	// Auto-merge both_modified files when no strategy is set
+	const conflict_files = []
+	const json_conflicts = []
 	if (classified.both_modified.length > 0 && !strategy) {
-		spinner.stop()
-		if (args.flags.json) {
-			print_json({ data: { status: 'conflicts', report } })
-		} else {
-			print_warn(`${report.summary.conflicted} file(s) modified on both sides:`)
-			for (const f of classified.both_modified) {
-				console.error(`  - ${f.path}`)
+		spinner.update('Auto-merging...')
+		for (const entry of classified.both_modified) {
+			const report_file = report.files.find(f => f.path === entry.path)
+
+			// Delete-vs-modify — cannot auto-merge, keep what exists
+			if (entry.local_sha === null || entry.remote_sha === null) {
+				conflict_files.push(entry.path)
+				if (report_file) report_file.conflict_written = true
+				if (entry.local_sha === null && entry.remote_sha !== null) {
+					// Local deleted, remote modified — write remote version
+					const [af_err] = await apply_remote_file(skill_dir, owner, repo, entry)
+					if (af_err) { spinner.fail(`Failed to apply ${entry.path}`); throw af_err[0] }
+					if (full_report && report_file) {
+						const rf = remote_file_map.get(entry.path)
+						enrich_file_content(report_file, {
+							base: decode_b64(base_file_map.get(entry.path)),
+							remote: decode_b64(rf)
+						})
+					}
+				} else if (full_report && report_file) {
+					// Local modified, remote deleted — capture what exists
+					const local_text = await fs.promises.readFile(path.join(skill_dir, entry.path), 'utf-8')
+					enrich_file_content(report_file, {
+						base: decode_b64(base_file_map.get(entry.path)),
+						local: local_text
+					})
+				}
+				continue
+			}
+
+			const base_file = base_file_map.get(entry.path)
+			const remote_file = remote_file_map.get(entry.path)
+			const base_text = base_file ? Buffer.from(base_file.content, 'base64').toString('utf-8') : ''
+			const local_text = await fs.promises.readFile(path.join(skill_dir, entry.path), 'utf-8')
+			const remote_text = remote_file ? Buffer.from(remote_file.content, 'base64').toString('utf-8') : ''
+
+			if (entry.path === 'skill.json') {
+				const result = merge_skill_json(
+					JSON.parse(base_text || '{}'),
+					JSON.parse(local_text || '{}'),
+					JSON.parse(remote_text || '{}')
+				)
+				const merged_text = JSON.stringify(result.merged, null, '\t') + '\n'
+				await fs.promises.writeFile(path.join(skill_dir, entry.path), merged_text)
+				if (result.conflicts.length > 0) json_conflicts.push(...result.conflicts)
+				if (report_file) {
+					report_file.merge_result = { type: 'json', conflicts: result.conflicts }
+					if (full_report) enrich_file_content(report_file, { base: base_text, local: local_text, remote: remote_text, merged: merged_text })
+				}
+			} else if (entry.path.toLowerCase() === 'changelog.md') {
+				const result = merge_changelog(base_text, local_text, remote_text)
+				await fs.promises.writeFile(path.join(skill_dir, entry.path), result.merged)
+				if (result.has_conflicts) conflict_files.push(entry.path)
+				if (report_file) {
+					report_file.conflict_written = result.has_conflicts
+					report_file.merge_result = { type: 'changelog', has_conflicts: result.has_conflicts, used_fallback: result.used_fallback }
+					if (full_report) enrich_file_content(report_file, { base: base_text, local: local_text, remote: remote_text, merged: result.merged })
+				}
+			} else {
+				const result = three_way_merge(base_text, local_text, remote_text)
+				await fs.promises.writeFile(path.join(skill_dir, entry.path), result.merged)
+				if (result.has_conflicts) conflict_files.push(entry.path)
+				if (report_file) {
+					report_file.conflict_written = result.has_conflicts
+					report_file.merge_result = { type: 'text', conflict_count: result.conflict_count, conflict_regions: result.conflict_regions }
+					if (full_report) enrich_file_content(report_file, { base: base_text, local: local_text, remote: remote_text, merged: result.merged })
+				}
 			}
-			console.error('')
-			print_hint('Auto-merge not yet available. Use --theirs (take remote) or --ours (keep local) for all conflicting files, or manually merge and publish with --force.')
 		}
-		return process.exit(EXIT_CODES.ERROR)
 	}
 
-	// Apply changes
-	spinner.update('Applying changes...')
-	const remote_file_map = new Map((remote_clone.files || []).map(f => [f.path, f]))
-
 	// Remote-only modified/added → write remote version
 	for (const entry of [...classified.remote_only_modified, ...classified.remote_only_added]) {
 		const remote_file = remote_file_map.get(entry.path)
@@ -233,19 +300,53 @@ const run = (args) => catch_errors('Pull failed', async () => {
 			const [dir_err] = await ensure_dir(path.dirname(full))
 			if (dir_err) { spinner.fail(`Failed to create dir for ${entry.path}`); throw dir_err[0] }
 			await fs.promises.writeFile(full, Buffer.from(remote_file.content, 'base64'))
+			if (full_report) {
+				const report_file = report.files.find(f => f.path === entry.path)
+				if (report_file) enrich_file_content(report_file, { remote: decode_b64(remote_file) })
+			}
 		}
 	}
 
 	// Remote-only deleted → remove local
+	if (full_report) {
+		for (const entry of classified.remote_only_deleted) {
+			const report_file = report.files.find(f => f.path === entry.path)
+			if (report_file) enrich_file_content(report_file, { base: decode_b64(base_file_map.get(entry.path)) })
+		}
+	}
 	const [del_err] = await remove_files(skill_dir, classified.remote_only_deleted.map(f => f.path))
 	if (del_err) { spinner.fail('Failed to remove deleted files'); throw del_err[0] }
 
 	// Local-only modified/added → keep (no action needed)
 	// Local-only deleted → keep deleted (no action needed)
+	if (full_report) {
+		for (const entry of [...classified.local_only_modified, ...classified.local_only_added]) {
+			const report_file = report.files.find(f => f.path === entry.path)
+			if (report_file) {
+				const local_text = await fs.promises.readFile(path.join(skill_dir, entry.path), 'utf-8')
+				enrich_file_content(report_file, { local: local_text })
+			}
+		}
+		for (const entry of classified.local_only_deleted) {
+			const report_file = report.files.find(f => f.path === entry.path)
+			if (report_file) enrich_file_content(report_file, { base: decode_b64(base_file_map.get(entry.path)) })
+		}
+	}
 
 	// Both-modified → apply strategy
 	if (strategy === 'theirs') {
 		for (const entry of classified.both_modified) {
+			if (full_report) {
+				const report_file = report.files.find(f => f.path === entry.path)
+				if (report_file) {
+					const content = { base: decode_b64(base_file_map.get(entry.path)), remote: decode_b64(remote_file_map.get(entry.path)) }
+					// Capture local before overwrite
+					if (entry.local_sha !== null) {
+						try { content.local = await fs.promises.readFile(path.join(skill_dir, entry.path), 'utf-8') } catch { /* deleted */ }
+					}
+					enrich_file_content(report_file, content)
+				}
+			}
 			if (entry.remote_sha === null) {
 				// Remote deleted — remove local
 				const full = path.join(skill_dir, entry.path)
@@ -261,7 +362,18 @@ const run = (args) => catch_errors('Pull failed', async () => {
 			}
 		}
 	}
-	// strategy === 'ours' → keep local files as-is (no action needed)
+	if (strategy === 'ours' && full_report) {
+		for (const entry of classified.both_modified) {
+			const report_file = report.files.find(f => f.path === entry.path)
+			if (report_file) {
+				const content = { base: decode_b64(base_file_map.get(entry.path)), remote: decode_b64(remote_file_map.get(entry.path)) }
+				if (entry.local_sha !== null) {
+					try { content.local = await fs.promises.readFile(path.join(skill_dir, entry.path), 'utf-8') } catch { /* deleted */ }
+				}
+				enrich_file_content(report_file, content)
+			}
+		}
+	}
 
 	// Update lock — use head_commit from compare (authoritative, not cached)
 	const [hash_err, new_integrity] = await hash_directory(skill_dir)
@@ -274,6 +386,11 @@ const run = (args) => catch_errors('Pull failed', async () => {
 		version: cmp_data.head_version || lock_entry.version,
 		ref: remote_clone.ref || lock_entry.ref
 	}
+	if (conflict_files.length > 0) {
+		updated_entry.conflict_files = conflict_files
+	} else {
+		delete updated_entry.conflict_files
+	}
 	const merged_skills = update_lock_skills(lock_data, { [skill_name]: updated_entry })
 	const [wl_err] = await write_lock(lock_root(is_global, project_root), merged_skills)
 	if (wl_err) { spinner.fail('Failed to write lock file'); throw wl_err[0] }
@@ -281,15 +398,34 @@ const run = (args) => catch_errors('Pull failed', async () => {
 	spinner.stop()
 
 	if (args.flags.json) {
-		print_json({ data: { status: 'merged', report } })
+		const status = conflict_files.length > 0 ? 'conflicts' : 'merged'
+		const output = { status, report, conflict_files, json_conflicts }
+		if (full_report) output.resolution_steps = build_resolution_steps(report, json_conflicts)
+		print_json({ data: output })
 	} else {
 		print_success(`Pulled ${skill_name} → ${cmp_data.head_version || 'latest'}`)
 		if (report.summary.auto_merged > 0) {
 			print_info(`${report.summary.auto_merged} file(s) auto-applied (non-conflicting changes)`)
 		}
-		if (classified.both_modified.length > 0) {
+		if (classified.both_modified.length > 0 && strategy) {
 			print_info(`${classified.both_modified.length} conflict(s) resolved with --${strategy}`)
 		}
+		const auto_merged_count = classified.both_modified.length - conflict_files.length
+		if (auto_merged_count > 0 && !strategy) {
+			print_info(`${auto_merged_count} file(s) auto-merged`)
+		}
+		if (json_conflicts.length > 0) {
+			print_warn(`skill.json merge suggestions (review before publishing):`)
+			for (const c of json_conflicts) {
+				console.error(`  - ${c.field}: ${JSON.stringify(c.suggestion)}`)
+			}
+		}
+		if (conflict_files.length > 0) {
+			print_warn(`${conflict_files.length} file(s) with conflict markers — resolve before publishing:`)
+			for (const f of conflict_files) {
+				console.error(`  - ${f}`)
+			}
+		}
 	}
 
 	// 7. Dependency reconciliation

package/src/commands/status.js

@@ -25,7 +25,8 @@ Examples:
   happyskills st acme/deploy-aws
   happyskills status --json`
 
-const classify = (local_modified, remote_updated) => {
+const classify = (local_modified, remote_updated, has_conflicts) => {
+	if (has_conflicts) return 'conflicts'
 	if (local_modified && remote_updated) return 'diverged'
 	if (local_modified) return 'modified'
 	if (remote_updated) return 'outdated'
@@ -78,6 +79,7 @@ const run = (args) => catch_errors('Status failed', async () => {
 		const short_name = name.split('/')[1] || name
 		const dir = skill_install_dir(base_dir, short_name)
 		const [, det] = await detect_status(data, dir)
+		const has_conflicts = (data.conflict_files || []).length > 0
 		results.push({
 			skill: name,
 			base_version: data.version || null,
@@ -87,7 +89,8 @@ const run = (args) => catch_errors('Status failed', async () => {
 			remote_updated: false,
 			remote_version: null,
 			remote_commit: null,
-			status: 'clean'
+			conflict_files: data.conflict_files || [],
+			status: has_conflicts ? 'conflicts' : 'clean'
 		})
 	}
 
@@ -112,7 +115,7 @@ const run = (args) => catch_errors('Status failed', async () => {
 	// Classify each result
 	for (const r of results) {
 		if (r.status !== 'not_found') {
-			r.status = classify(r.local_modified, r.remote_updated)
+			r.status = classify(r.local_modified, r.remote_updated, r.conflict_files.length > 0)
 		}
 	}
 
@@ -131,11 +134,12 @@ const run = (args) => catch_errors('Status failed', async () => {
 		skill: r.skill,
 		base: r.base_version || '?',
 		remote: r.remote_version || '?',
-		status: r.status === 'diverged' ? 'diverged (local + remote changes)'
-			: r.status === 'modified' ? 'modified (local changes)'
-				: r.status === 'outdated' ? 'outdated (remote changes)'
-					: r.status === 'not_found' ? 'not found'
-						: 'clean'
+		status: r.status === 'conflicts' ? 'conflicts (unresolved merge conflicts)'
+			: r.status === 'diverged' ? 'diverged (local + remote changes)'
+				: r.status === 'modified' ? 'modified (local changes)'
+					: r.status === 'outdated' ? 'outdated (remote changes)'
+						: r.status === 'not_found' ? 'not found'
+							: 'clean'
 	}))
 
 	const w_skill = Math.max(col_skill.length, ...rows.map(r => r.skill.length))

package/src/commands/validate.js

@@ -3,6 +3,7 @@ const { error: { catch_errors } } = require('puffy-core')
 const { validate_skill_md } = require('../validation/skill_md_rules')
 const { validate_skill_json } = require('../validation/skill_json_rules')
 const { validate_cross } = require('../validation/cross_rules')
+const { validate_no_conflict_markers } = require('../validation/conflict_marker_rules')
 const { file_exists, read_json } = require('../utils/fs')
 const { skills_dir, find_project_root } = require('../config/paths')
 const { print_help, print_json } = require('../ui/output')
@@ -144,8 +145,10 @@ const run = (args) => catch_errors('Validate failed', async () => {
 		skill_type
 	)
 	if (cross_err) throw cross_err
+	const [marker_err, marker_results] = await validate_no_conflict_markers(skill_dir)
+	if (marker_err) throw marker_err
 
-	const all_results = [...md_data.results, ...json_data.results, ...cross_results]
+	const all_results = [...md_data.results, ...json_data.results, ...cross_results, ...marker_results]
 	const type_label = is_kit ? ' [kit]' : ''
 
 	if (args.flags.json) {

package/src/merge/changelog_merge.js

@@ -0,0 +1,117 @@
+/**
+ * Three-way merge for CHANGELOG.md files.
+ *
+ * Strategy:
+ * - Parse into version sections (split on ## headings)
+ * - Take all remote sections (published history is authoritative)
+ * - Prepend local unreleased/new section content
+ * - Fall back to text_merge if structure is too ambiguous
+ */
+
+const { three_way_merge } = require('./text_merge')
+
+const VERSION_HEADING_RE = /^##\s+\[/m
+
+/**
+ * Parse a changelog into header (preamble before first version section) and version sections.
+ * Each section starts with a `## [` heading line.
+ *
+ * @param {string} text
+ * @returns {{ header: string, sections: string[] } | null} null if structure is ambiguous
+ */
+const parse_sections = (text) => {
+	if (!text) return null
+
+	const lines = text.split('\n')
+	let header_end = -1
+	const section_starts = []
+
+	for (let i = 0; i < lines.length; i++) {
+		if (VERSION_HEADING_RE.test(lines[i])) {
+			if (header_end === -1) header_end = i
+			section_starts.push(i)
+		}
+	}
+
+	// Ambiguous — no version headings found
+	if (section_starts.length === 0) return null
+
+	const header = lines.slice(0, header_end).join('\n')
+	const sections = []
+
+	for (let i = 0; i < section_starts.length; i++) {
+		const start = section_starts[i]
+		const end = i + 1 < section_starts.length ? section_starts[i + 1] : lines.length
+		sections.push(lines.slice(start, end).join('\n'))
+	}
+
+	return { header, sections }
+}
+
+/**
+ * Extract the version string from a section heading.
+ * e.g. "## [1.5.0] - 2026-03-29" → "1.5.0"
+ * e.g. "## [Unreleased]" → "Unreleased"
+ */
+const extract_version = (section) => {
+	const match = section.match(/^##\s+\[([^\]]+)\]/)
+	return match ? match[1] : null
+}
+
+/**
+ * @param {string} base_text
+ * @param {string} local_text
+ * @param {string} remote_text
+ * @returns {{ merged: string, has_conflicts: boolean, conflict_count: number, conflict_regions: Array, used_fallback: boolean }}
+ */
+const merge_changelog = (base_text, local_text, remote_text) => {
+	const base_parsed = parse_sections(base_text)
+	const local_parsed = parse_sections(local_text)
+	const remote_parsed = parse_sections(remote_text)
+
+	// Fall back to text merge if any side is too ambiguous to parse
+	if (!base_parsed || !local_parsed || !remote_parsed) {
+		const result = three_way_merge(base_text, local_text, remote_text)
+		return { ...result, used_fallback: true }
+	}
+
+	// Collect remote version strings (published history)
+	const remote_versions = new Set(remote_parsed.sections.map(extract_version).filter(Boolean))
+
+	// Find local-only sections: sections in local that are NOT in base and NOT in remote
+	const base_versions = new Set(base_parsed.sections.map(extract_version).filter(Boolean))
+	const local_new_sections = local_parsed.sections.filter(s => {
+		const v = extract_version(s)
+		if (!v) return false
+		if (v === 'Unreleased') return true
+		return !base_versions.has(v) && !remote_versions.has(v)
+	})
+
+	// Build merged changelog: remote header + local new sections + all remote sections
+	const parts = [remote_parsed.header]
+
+	// Add local new sections (unreleased or new version entries)
+	for (const section of local_new_sections) {
+		parts.push(section)
+	}
+
+	// Add all remote sections (authoritative published history)
+	for (const section of remote_parsed.sections) {
+		const v = extract_version(section)
+		// Skip duplicate unreleased if we already included it from local
+		if (v === 'Unreleased' && local_new_sections.some(s => extract_version(s) === 'Unreleased')) {
+			continue
+		}
+		parts.push(section)
+	}
+
+	return {
+		merged: parts.join('\n'),
+		has_conflicts: false,
+		conflict_count: 0,
+		conflict_regions: [],
+		used_fallback: false
+	}
+}
+
+module.exports = { merge_changelog, parse_sections, extract_version }

package/src/merge/changelog_merge.test.js

@@ -0,0 +1,92 @@
+const { describe, it } = require('node:test')
+const assert = require('node:assert/strict')
+const { merge_changelog, parse_sections, extract_version } = require('./changelog_merge')
+
+describe('parse_sections', () => {
+	it('parses header and version sections', () => {
+		const text = '# Changelog\n\nPreamble\n\n## [1.0.0] - 2026-01-01\n\nFirst release\n\n## [0.9.0] - 2025-12-01\n\nBeta'
+		const r = parse_sections(text)
+		assert.strictEqual(r.sections.length, 2)
+		assert.ok(r.header.includes('Preamble'))
+		assert.ok(r.sections[0].includes('[1.0.0]'))
+		assert.ok(r.sections[1].includes('[0.9.0]'))
+	})
+
+	it('returns null for text without version headings', () => {
+		assert.strictEqual(parse_sections('just some text'), null)
+		assert.strictEqual(parse_sections(null), null)
+	})
+
+	it('handles Unreleased section', () => {
+		const text = '# Changelog\n\n## [Unreleased]\n\nWIP\n\n## [1.0.0]\n\nDone'
+		const r = parse_sections(text)
+		assert.strictEqual(r.sections.length, 2)
+		assert.ok(r.sections[0].includes('Unreleased'))
+	})
+})
+
+describe('extract_version', () => {
+	it('extracts version from heading', () => {
+		assert.strictEqual(extract_version('## [1.5.0] - 2026-03-29'), '1.5.0')
+		assert.strictEqual(extract_version('## [Unreleased]'), 'Unreleased')
+	})
+
+	it('returns null for non-heading text', () => {
+		assert.strictEqual(extract_version('some text'), null)
+	})
+})
+
+describe('merge_changelog', () => {
+	const header = '# Changelog\n\nAll notable changes.\n'
+
+	it('preserves remote history and prepends local new sections', () => {
+		const base = `${header}\n## [1.0.0]\n\nBase release`
+		const local = `${header}\n## [Unreleased]\n\nLocal work\n\n## [1.0.0]\n\nBase release`
+		const remote = `${header}\n## [1.1.0]\n\nRemote release\n\n## [1.0.0]\n\nBase release`
+		const r = merge_changelog(base, local, remote)
+		assert.strictEqual(r.has_conflicts, false)
+		assert.strictEqual(r.used_fallback, false)
+		// Local unreleased should appear before remote versions
+		const unreleased_pos = r.merged.indexOf('[Unreleased]')
+		const v11_pos = r.merged.indexOf('[1.1.0]')
+		const v10_pos = r.merged.indexOf('[1.0.0]')
+		assert.ok(unreleased_pos < v11_pos, 'Unreleased before 1.1.0')
+		assert.ok(v11_pos < v10_pos, '1.1.0 before 1.0.0')
+	})
+
+	it('avoids duplicate Unreleased sections', () => {
+		const base = `${header}\n## [1.0.0]\n\nRelease`
+		const local = `${header}\n## [Unreleased]\n\nLocal\n\n## [1.0.0]\n\nRelease`
+		const remote = `${header}\n## [Unreleased]\n\nRemote\n\n## [1.0.0]\n\nRelease`
+		const r = merge_changelog(base, local, remote)
+		const count = (r.merged.match(/\[Unreleased\]/g) || []).length
+		assert.strictEqual(count, 1, 'Should have exactly one Unreleased section')
+	})
+
+	it('falls back to text_merge for ambiguous structure', () => {
+		const base = 'just text'
+		const local = 'local text'
+		const remote = 'remote text'
+		const r = merge_changelog(base, local, remote)
+		assert.strictEqual(r.used_fallback, true)
+	})
+
+	it('handles no local changes (remote-only update)', () => {
+		const base = `${header}\n## [1.0.0]\n\nRelease`
+		const local = base
+		const remote = `${header}\n## [1.1.0]\n\nNew\n\n## [1.0.0]\n\nRelease`
+		const r = merge_changelog(base, local, remote)
+		assert.strictEqual(r.has_conflicts, false)
+		assert.ok(r.merged.includes('[1.1.0]'))
+	})
+
+	it('preserves all remote sections as authoritative', () => {
+		const base = `${header}\n## [1.0.0]\n\nOriginal`
+		const local = `${header}\n## [1.0.0]\n\nOriginal`
+		const remote = `${header}\n## [1.2.0]\n\nTwo\n\n## [1.1.0]\n\nOne\n\n## [1.0.0]\n\nOriginal`
+		const r = merge_changelog(base, local, remote)
+		assert.ok(r.merged.includes('[1.2.0]'))
+		assert.ok(r.merged.includes('[1.1.0]'))
+		assert.ok(r.merged.includes('[1.0.0]'))
+	})
+})