happyskills 0.18.0 → 0.19.0

package/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [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
+- Fix `pull` and `diff` recording stale commit SHA from CloudFront-cached clone responses — now clones at the specific head commit from the compare endpoint, ensuring the lock file matches the remote after pull
+
 ## [0.18.0] - 2026-03-29
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "happyskills",
-	"version": "0.18.0",
+	"version": "0.19.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/diff.js

@@ -136,15 +136,18 @@ const run = (args) => catch_errors('Diff failed', async () => {
 	}
 
 	if (mode === 'remote') {
-		// Base vs remote — use classify_changes with base as the "local" side
-		const [remote_err, remote_clone] = await repos_api.clone(owner, repo, null)
+		// Base vs remote — get head commit via compare, clone at that commit
+		const [cmp_err, cmp_data] = await repos_api.compare(owner, repo, lock_entry.base_commit)
+		if (cmp_err) throw e('Compare failed', cmp_err)
+
+		const [remote_err, remote_clone] = await repos_api.clone(owner, repo, null, { commit: cmp_data.head_commit })
 		if (remote_err) throw e('Failed to fetch remote files', remote_err)
 		const remote_files = (remote_clone.files || []).map(f => ({ path: f.path, sha: f.sha }))
 
 		const classified = classify_changes(base_files, base_files, remote_files)
 
 		if (args.flags.json) {
-			const report = build_report(skill_name, lock_entry.version, null, classified)
+			const report = build_report(skill_name, lock_entry.version, cmp_data.head_version, classified)
 			print_json({ data: { mode, report } })
 		} else {
 			print_file_table(classified)
@@ -152,16 +155,19 @@ const run = (args) => catch_errors('Diff failed', async () => {
 		return
 	}
 
-	// Full three-way diff
+	// Full three-way diff — get head commit via compare
+	const [cmp_err, cmp_data] = await repos_api.compare(owner, repo, lock_entry.base_commit)
+	if (cmp_err) throw e('Compare failed', cmp_err)
+
 	const [local_err, local_files] = await build_local_entries(skill_dir)
 	if (local_err) throw e('Failed to read local files', local_err)
 
-	const [remote_err, remote_clone] = await repos_api.clone(owner, repo, null)
+	const [remote_err, remote_clone] = await repos_api.clone(owner, repo, null, { commit: cmp_data.head_commit })
 	if (remote_err) throw e('Failed to fetch remote files', remote_err)
 	const remote_files = (remote_clone.files || []).map(f => ({ path: f.path, sha: f.sha }))
 
 	const classified = classify_changes(base_files, local_files, remote_files)
-	const report = build_report(skill_name, lock_entry.version, null, classified)
+	const report = build_report(skill_name, lock_entry.version, cmp_data.head_version, classified)
 
 	if (args.flags.json) {
 		print_json({ data: { mode, report } })

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

@@ -6,6 +6,9 @@ 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 { 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')
@@ -142,7 +145,8 @@ const run = (args) => catch_errors('Pull failed', async () => {
 	// 5. No local mods → fast-forward
 	if (!det.local_modified || strategy === 'force') {
 		spinner.update('Fast-forwarding...')
-		const [clone_err, clone_data] = await repos_api.clone(owner, repo, null)
+		// Clone at the specific head commit from compare (bypasses CDN cache)
+		const [clone_err, clone_data] = await repos_api.clone(owner, repo, null, { commit: cmp_data.head_commit })
 		if (clone_err) { spinner.fail('Clone failed'); throw clone_err[0] }
 
 		// Remove existing files and write fresh
@@ -159,12 +163,12 @@ const run = (args) => catch_errors('Pull failed', async () => {
 		const [wf_err] = await write_files_from_clone(clone_data, skill_dir)
 		if (wf_err) { spinner.fail('Failed to write files'); throw wf_err[0] }
 
-		// Update lock
+		// Update lock — use head_commit from compare (authoritative, not cached)
 		const [hash_err, new_integrity] = await hash_directory(skill_dir)
 		const updated_entry = {
 			...lock_entry,
-			commit: clone_data.commit,
-			base_commit: clone_data.commit,
+			commit: cmp_data.head_commit,
+			base_commit: cmp_data.head_commit,
 			integrity: new_integrity || lock_entry.integrity,
 			base_integrity: new_integrity || lock_entry.base_integrity,
 			version: cmp_data.head_version || lock_entry.version,
@@ -196,34 +200,75 @@ const run = (args) => catch_errors('Pull failed', async () => {
 	const [local_err, local_files] = await build_local_entries(skill_dir)
 	if (local_err) { spinner.fail('Failed to read local files'); throw local_err[0] }
 
-	// Get remote files (clone latest)
-	const [remote_err, remote_clone] = await repos_api.clone(owner, repo, null)
+	// Get remote files (clone at head commit — bypasses CDN cache)
+	const [remote_err, remote_clone] = await repos_api.clone(owner, repo, null, { commit: cmp_data.head_commit })
 	if (remote_err) { spinner.fail('Failed to fetch remote files'); throw remote_err[0] }
 	const remote_files = (remote_clone.files || []).map(f => ({ path: f.path, sha: f.sha }))
 
 	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] }
+				}
+				// Local modified, remote deleted — keep local as-is
+				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 || '{}')
+				)
+				await fs.promises.writeFile(path.join(skill_dir, entry.path), JSON.stringify(result.merged, null, '\t') + '\n')
+				if (result.conflicts.length > 0) json_conflicts.push(...result.conflicts)
+				if (report_file) report_file.merge_result = { type: 'json', conflicts: result.conflicts }
+			} 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 }
+				}
+			} 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 }
+				}
 			}
-			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)
@@ -262,17 +307,22 @@ const run = (args) => catch_errors('Pull failed', async () => {
 	}
 	// strategy === 'ours' → keep local files as-is (no action needed)
 
-	// Update lock
+	// Update lock — use head_commit from compare (authoritative, not cached)
 	const [hash_err, new_integrity] = await hash_directory(skill_dir)
 	const updated_entry = {
 		...lock_entry,
-		commit: remote_clone.commit,
-		base_commit: remote_clone.commit,
+		commit: cmp_data.head_commit,
+		base_commit: cmp_data.head_commit,
 		integrity: new_integrity || lock_entry.integrity,
 		base_integrity: new_integrity || lock_entry.base_integrity,
 		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] }
@@ -280,15 +330,32 @@ 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'
+		print_json({ data: { status, report, conflict_files, json_conflicts } })
 	} 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]'))
+	})
+})

package/src/merge/json_merge.js

@@ -0,0 +1,152 @@
+/**
+ * Structured three-way merge for skill.json files.
+ *
+ * Always produces valid JSON — no conflict markers.
+ * Conflicts are reported structurally so the CLI can display them
+ * and the user can resolve before publishing.
+ */
+
+const semver = require('semver')
+
+/**
+ * @param {object} base   - Base skill.json (from base_commit)
+ * @param {object} local  - Local skill.json (from disk)
+ * @param {object} remote - Remote skill.json (from head_commit)
+ * @returns {{ merged: object, conflicts: Array<{ field: string, base_value: *, local_value: *, remote_value: *, suggestion: * }> }}
+ */
+const merge_skill_json = (base, local, remote) => {
+	const merged = {}
+	const conflicts = []
+
+	const all_keys = new Set([
+		...Object.keys(base || {}),
+		...Object.keys(local || {}),
+		...Object.keys(remote || {})
+	])
+
+	for (const key of all_keys) {
+		const b = base?.[key]
+		const l = local?.[key]
+		const r = remote?.[key]
+
+		if (key === 'version') {
+			merge_version(b, l, r, merged, conflicts)
+		} else if (key === 'dependencies') {
+			merge_dependencies(b, l, r, merged, conflicts)
+		} else {
+			merge_scalar(key, b, l, r, merged, conflicts)
+		}
+	}
+
+	return { merged, conflicts }
+}
+
+const merge_version = (base_v, local_v, remote_v, merged, conflicts) => {
+	const local_changed = local_v !== base_v
+	const remote_changed = remote_v !== base_v
+
+	if (!local_changed && !remote_changed) {
+		merged.version = base_v
+	} else if (local_changed && !remote_changed) {
+		merged.version = local_v
+	} else if (!local_changed && remote_changed) {
+		merged.version = remote_v
+	} else if (local_v === remote_v) {
+		// Both changed to the same value — no conflict
+		merged.version = local_v
+	} else {
+		// Both changed differently — suggest next patch after the higher version
+		const higher = semver.gt(remote_v || '0.0.0', local_v || '0.0.0') ? remote_v : local_v
+		const suggestion = semver.inc(higher, 'patch')
+		merged.version = suggestion
+		conflicts.push({
+			field: 'version',
+			base_value: base_v,
+			local_value: local_v,
+			remote_value: remote_v,
+			suggestion
+		})
+	}
+}
+
+const merge_dependencies = (base_deps, local_deps, remote_deps, merged, conflicts) => {
+	const b = base_deps || {}
+	const l = local_deps || {}
+	const r = remote_deps || {}
+	const all_dep_keys = new Set([...Object.keys(b), ...Object.keys(l), ...Object.keys(r)])
+	const result = {}
+
+	for (const dep of all_dep_keys) {
+		const bv = b[dep]
+		const lv = l[dep]
+		const rv = r[dep]
+		const local_changed = lv !== bv
+		const remote_changed = rv !== bv
+
+		if (!local_changed && !remote_changed) {
+			if (bv !== undefined) result[dep] = bv
+		} else if (local_changed && !remote_changed) {
+			if (lv !== undefined) result[dep] = lv // local added or modified
+			// lv undefined = local removed
+		} else if (!local_changed && remote_changed) {
+			if (rv !== undefined) result[dep] = rv // remote added or modified
+			// rv undefined = remote removed
+		} else {
+			// Both changed
+			if (lv === rv) {
+				// Same change — no conflict
+				if (lv !== undefined) result[dep] = lv
+			} else {
+				// Conflict — suggest remote constraint (published version wins)
+				const suggestion = rv !== undefined ? rv : lv
+				result[dep] = suggestion
+				conflicts.push({
+					field: `dependencies.${dep}`,
+					base_value: bv || null,
+					local_value: lv || null,
+					remote_value: rv || null,
+					suggestion
+				})
+			}
+		}
+	}
+
+	if (Object.keys(result).length > 0) {
+		merged.dependencies = result
+	}
+}
+
+const merge_scalar = (key, base_val, local_val, remote_val, merged, conflicts) => {
+	const b_json = JSON.stringify(base_val)
+	const l_json = JSON.stringify(local_val)
+	const r_json = JSON.stringify(remote_val)
+
+	const local_changed = l_json !== b_json
+	const remote_changed = r_json !== b_json
+
+	if (!local_changed && !remote_changed) {
+		if (base_val !== undefined) merged[key] = base_val
+	} else if (local_changed && !remote_changed) {
+		if (local_val !== undefined) merged[key] = local_val
+	} else if (!local_changed && remote_changed) {
+		if (remote_val !== undefined) merged[key] = remote_val
+	} else {
+		// Both changed
+		if (l_json === r_json) {
+			if (local_val !== undefined) merged[key] = local_val
+		} else {
+			// Conflict — suggest remote value
+			const suggestion = remote_val !== undefined ? remote_val : local_val
+			if (suggestion !== undefined) merged[key] = suggestion
+			conflicts.push({
+				field: key,
+				base_value: base_val !== undefined ? base_val : null,
+				local_value: local_val !== undefined ? local_val : null,
+				remote_value: remote_val !== undefined ? remote_val : null,
+				suggestion: suggestion !== undefined ? suggestion : null
+			})
+		}
+	}
+}
+
+module.exports = { merge_skill_json }

package/src/merge/json_merge.test.js

@@ -0,0 +1,148 @@
+const { describe, it } = require('node:test')
+const assert = require('node:assert/strict')
+const { merge_skill_json } = require('./json_merge')
+
+describe('merge_skill_json', () => {
+	it('returns base unchanged when no changes', () => {
+		const base = { name: 'acme/deploy', version: '1.0.0' }
+		const r = merge_skill_json(base, { ...base }, { ...base })
+		assert.deepStrictEqual(r.merged, base)
+		assert.strictEqual(r.conflicts.length, 0)
+	})
+
+	it('takes local-only scalar change', () => {
+		const base = { name: 'acme/deploy', version: '1.0.0', description: 'old' }
+		const local = { ...base, description: 'new local' }
+		const r = merge_skill_json(base, local, { ...base })
+		assert.strictEqual(r.merged.description, 'new local')
+		assert.strictEqual(r.conflicts.length, 0)
+	})
+
+	it('takes remote-only scalar change', () => {
+		const base = { name: 'acme/deploy', version: '1.0.0', description: 'old' }
+		const remote = { ...base, description: 'new remote' }
+		const r = merge_skill_json(base, { ...base }, remote)
+		assert.strictEqual(r.merged.description, 'new remote')
+		assert.strictEqual(r.conflicts.length, 0)
+	})
+
+	it('reports conflict for both-changed scalar', () => {
+		const base = { name: 'acme/deploy', description: 'old' }
+		const local = { name: 'acme/deploy', description: 'local desc' }
+		const remote = { name: 'acme/deploy', description: 'remote desc' }
+		const r = merge_skill_json(base, local, remote)
+		assert.strictEqual(r.conflicts.length, 1)
+		assert.strictEqual(r.conflicts[0].field, 'description')
+		assert.strictEqual(r.conflicts[0].suggestion, 'remote desc')
+	})
+
+	it('reports version conflict with suggested next patch', () => {
+		const base = { version: '1.5.0' }
+		const local = { version: '1.6.0' }
+		const remote = { version: '1.8.0' }
+		const r = merge_skill_json(base, local, remote)
+		assert.strictEqual(r.conflicts.length, 1)
+		assert.strictEqual(r.conflicts[0].field, 'version')
+		assert.strictEqual(r.merged.version, '1.8.1')
+		assert.strictEqual(r.conflicts[0].suggestion, '1.8.1')
+	})
+
+	it('takes local-only version change without conflict', () => {
+		const base = { version: '1.0.0' }
+		const local = { version: '1.1.0' }
+		const r = merge_skill_json(base, local, { ...base })
+		assert.strictEqual(r.merged.version, '1.1.0')
+		assert.strictEqual(r.conflicts.length, 0)
+	})
+
+	it('takes remote-only version change without conflict', () => {
+		const base = { version: '1.0.0' }
+		const remote = { version: '1.2.0' }
+		const r = merge_skill_json(base, { ...base }, remote)
+		assert.strictEqual(r.merged.version, '1.2.0')
+		assert.strictEqual(r.conflicts.length, 0)
+	})
+
+	it('merges dependencies — local-only add', () => {
+		const base = { dependencies: { 'acme/utils': '^2.0.0' } }
+		const local = { dependencies: { 'acme/utils': '^2.0.0', 'acme/logger': '^1.0.0' } }
+		const r = merge_skill_json(base, local, { ...base })
+		assert.strictEqual(r.merged.dependencies['acme/logger'], '^1.0.0')
+		assert.strictEqual(r.merged.dependencies['acme/utils'], '^2.0.0')
+		assert.strictEqual(r.conflicts.length, 0)
+	})
+
+	it('merges dependencies — remote-only add', () => {
+		const base = { dependencies: { 'acme/utils': '^2.0.0' } }
+		const remote = { dependencies: { 'acme/utils': '^2.0.0', 'acme/auth': '^1.0.0' } }
+		const r = merge_skill_json(base, { ...base }, remote)
+		assert.strictEqual(r.merged.dependencies['acme/auth'], '^1.0.0')
+		assert.strictEqual(r.conflicts.length, 0)
+	})
+
+	it('merges dependencies — both add different deps (clean)', () => {
+		const base = { dependencies: {} }
+		const local = { dependencies: { 'acme/logger': '^1.0.0' } }
+		const remote = { dependencies: { 'acme/auth': '^1.0.0' } }
+		const r = merge_skill_json(base, local, remote)
+		assert.strictEqual(r.merged.dependencies['acme/logger'], '^1.0.0')
+		assert.strictEqual(r.merged.dependencies['acme/auth'], '^1.0.0')
+		assert.strictEqual(r.conflicts.length, 0)
+	})
+
+	it('reports conflict for same dep with different constraints', () => {
+		const base = { dependencies: { 'acme/utils': '^2.0.0' } }
+		const local = { dependencies: { 'acme/utils': '^2.5.0' } }
+		const remote = { dependencies: { 'acme/utils': '^3.0.0' } }
+		const r = merge_skill_json(base, local, remote)
+		assert.strictEqual(r.conflicts.length, 1)
+		assert.strictEqual(r.conflicts[0].field, 'dependencies.acme/utils')
+		assert.strictEqual(r.conflicts[0].suggestion, '^3.0.0')
+		assert.strictEqual(r.merged.dependencies['acme/utils'], '^3.0.0')
+	})
+
+	it('handles local dep removal', () => {
+		const base = { dependencies: { 'acme/utils': '^2.0.0', 'acme/logger': '^1.0.0' } }
+		const local = { dependencies: { 'acme/utils': '^2.0.0' } }
+		const r = merge_skill_json(base, local, { ...base })
+		assert.strictEqual(r.merged.dependencies['acme/logger'], undefined)
+		assert.strictEqual(r.merged.dependencies['acme/utils'], '^2.0.0')
+		assert.strictEqual(r.conflicts.length, 0)
+	})
+
+	it('handles null base (no previous skill.json)', () => {
+		const local = { name: 'acme/deploy', version: '1.0.0' }
+		const remote = { name: 'acme/deploy', version: '1.0.0' }
+		const r = merge_skill_json(null, local, remote)
+		assert.strictEqual(r.merged.name, 'acme/deploy')
+		assert.strictEqual(r.conflicts.length, 0)
+	})
+
+	it('always produces valid JSON (no conflict markers)', () => {
+		const base = { version: '1.0.0', name: 'a' }
+		const local = { version: '2.0.0', name: 'b' }
+		const remote = { version: '3.0.0', name: 'c' }
+		const r = merge_skill_json(base, local, remote)
+		const json_str = JSON.stringify(r.merged)
+		assert.doesNotThrow(() => JSON.parse(json_str))
+		assert.ok(!json_str.includes('<<<<<<<'))
+	})
+
+	it('handles the full spec example correctly', () => {
+		const base = { version: '1.5.0', dependencies: { 'acme/utils': '^2.0.0' } }
+		const local = { version: '1.6.0', dependencies: { 'acme/utils': '^2.0.0', 'acme/logger': '^1.0.0' } }
+		const remote = { version: '1.8.0', dependencies: { 'acme/utils': '^3.0.0', 'acme/auth': '^1.0.0' } }
+		const r = merge_skill_json(base, local, remote)
+		// Version: both changed → suggestion = 1.8.1
+		assert.strictEqual(r.merged.version, '1.8.1')
+		// Utils: remote-only change → ^3.0.0
+		assert.strictEqual(r.merged.dependencies['acme/utils'], '^3.0.0')
+		// Logger: local-only add
+		assert.strictEqual(r.merged.dependencies['acme/logger'], '^1.0.0')
+		// Auth: remote-only add
+		assert.strictEqual(r.merged.dependencies['acme/auth'], '^1.0.0')
+		// Only version should be a conflict
+		const version_conflicts = r.conflicts.filter(c => c.field === 'version')
+		assert.strictEqual(version_conflicts.length, 1)
+	})
+})

package/src/merge/text_merge.js

@@ -0,0 +1,58 @@
+/**
+ * Three-way text merge using node-diff3.
+ *
+ * Wraps the library's output into a structured format with conflict regions.
+ * Conflict markers use: <<<<<<< LOCAL / ======= / >>>>>>> REMOTE
+ */
+
+const { merge, diff3MergeRegions } = require('node-diff3')
+
+const LABELS = { a: 'LOCAL', b: 'REMOTE' }
+
+/**
+ * @param {string} base_text
+ * @param {string} local_text
+ * @param {string} remote_text
+ * @returns {{ merged: string, has_conflicts: boolean, conflict_count: number, conflict_regions: Array }}
+ */
+const three_way_merge = (base_text, local_text, remote_text) => {
+	const base_lines = (base_text || '').split('\n')
+	const local_lines = (local_text || '').split('\n')
+	const remote_lines = (remote_text || '').split('\n')
+
+	// node-diff3 param order: merge(local, base, remote)
+	const result = merge(local_lines, base_lines, remote_lines, { label: LABELS })
+
+	// Extract conflict regions from diff3MergeRegions for structured reporting
+	const conflict_regions = []
+	if (result.conflict) {
+		const regions = diff3MergeRegions(local_lines, base_lines, remote_lines)
+		let line = 1
+		for (const region of regions) {
+			if (region.stable) {
+				line += region.bufferLength
+			} else {
+				// Unstable region: a=local, o=base, b=remote
+				const marker_lines = 2 + (region.aLength || 0) + (region.bLength || 0) // <<<, ===, >>>
+				conflict_regions.push({
+					start_line: line,
+					end_line: line + marker_lines,
+					base_content: (region.oContent || []).join('\n'),
+					local_content: (region.aContent || []).join('\n'),
+					remote_content: (region.bContent || []).join('\n')
+				})
+				// <<<<<<< LOCAL + local lines + ======= + remote lines + >>>>>>> REMOTE
+				line += 3 + (region.aLength || 0) + (region.bLength || 0)
+			}
+		}
+	}
+
+	return {
+		merged: result.result.join('\n'),
+		has_conflicts: result.conflict,
+		conflict_count: conflict_regions.length,
+		conflict_regions
+	}
+}
+
+module.exports = { three_way_merge }

package/src/merge/text_merge.test.js

@@ -0,0 +1,100 @@
+const { describe, it } = require('node:test')
+const assert = require('node:assert/strict')
+const { three_way_merge } = require('./text_merge')
+
+describe('three_way_merge', () => {
+	it('returns clean merge for non-overlapping edits', () => {
+		const base = 'line1\nline2\nline3'
+		const local = 'LOCAL1\nline2\nline3'
+		const remote = 'line1\nline2\nREMOTE3'
+		const r = three_way_merge(base, local, remote)
+		assert.strictEqual(r.has_conflicts, false)
+		assert.strictEqual(r.conflict_count, 0)
+		assert.strictEqual(r.merged, 'LOCAL1\nline2\nREMOTE3')
+	})
+
+	it('returns conflict markers for overlapping edits', () => {
+		const base = 'line1\nline2\nline3'
+		const local = 'line1\nLOCAL\nline3'
+		const remote = 'line1\nREMOTE\nline3'
+		const r = three_way_merge(base, local, remote)
+		assert.strictEqual(r.has_conflicts, true)
+		assert.strictEqual(r.conflict_count, 1)
+		assert.ok(r.merged.includes('<<<<<<< LOCAL'))
+		assert.ok(r.merged.includes('======='))
+		assert.ok(r.merged.includes('>>>>>>> REMOTE'))
+		assert.ok(r.merged.includes('LOCAL'))
+		assert.ok(r.merged.includes('REMOTE'))
+	})
+
+	it('returns clean merge for identical edits on both sides', () => {
+		const base = 'line1\nline2\nline3'
+		const local = 'line1\nSAME\nline3'
+		const remote = 'line1\nSAME\nline3'
+		const r = three_way_merge(base, local, remote)
+		assert.strictEqual(r.has_conflicts, false)
+		assert.strictEqual(r.merged, 'line1\nSAME\nline3')
+	})
+
+	it('handles add on both sides at different positions', () => {
+		const base = 'line1\nline3'
+		const local = 'line1\nLOCAL_ADD\nline3'
+		const remote = 'line1\nline3\nREMOTE_ADD'
+		const r = three_way_merge(base, local, remote)
+		assert.strictEqual(r.has_conflicts, false)
+		assert.ok(r.merged.includes('LOCAL_ADD'))
+		assert.ok(r.merged.includes('REMOTE_ADD'))
+	})
+
+	it('handles completely disjoint changes', () => {
+		const base = 'aaa\nbbb\nccc\nddd\neee'
+		const local = 'AAA\nbbb\nccc\nddd\neee'
+		const remote = 'aaa\nbbb\nccc\nddd\nEEE'
+		const r = three_way_merge(base, local, remote)
+		assert.strictEqual(r.has_conflicts, false)
+		assert.strictEqual(r.merged, 'AAA\nbbb\nccc\nddd\nEEE')
+	})
+
+	it('handles delete-vs-modify as conflict', () => {
+		const base = 'line1\nline2\nline3'
+		const local = 'line1\nline3'
+		const remote = 'line1\nMODIFIED\nline3'
+		const r = three_way_merge(base, local, remote)
+		assert.strictEqual(r.has_conflicts, true)
+		assert.strictEqual(r.conflict_count, 1)
+	})
+
+	it('provides conflict region details', () => {
+		const base = 'a\nb\nc'
+		const local = 'a\nLOCAL\nc'
+		const remote = 'a\nREMOTE\nc'
+		const r = three_way_merge(base, local, remote)
+		assert.strictEqual(r.conflict_regions.length, 1)
+		const region = r.conflict_regions[0]
+		assert.strictEqual(region.base_content, 'b')
+		assert.strictEqual(region.local_content, 'LOCAL')
+		assert.strictEqual(region.remote_content, 'REMOTE')
+		assert.ok(region.start_line > 0)
+	})
+
+	it('handles multiple conflict regions', () => {
+		const base = 'a\nb\nc\nd\ne'
+		const local = 'a\nL1\nc\nL2\ne'
+		const remote = 'a\nR1\nc\nR2\ne'
+		const r = three_way_merge(base, local, remote)
+		assert.strictEqual(r.has_conflicts, true)
+		assert.strictEqual(r.conflict_count, 2)
+		assert.strictEqual(r.conflict_regions.length, 2)
+	})
+
+	it('handles empty base with local-only change as clean merge', () => {
+		const r = three_way_merge('', 'new content', '')
+		assert.strictEqual(r.has_conflicts, false)
+		assert.ok(r.merged.includes('new content'))
+	})
+
+	it('handles null base (both sides added new file)', () => {
+		const r = three_way_merge(null, 'local stuff', 'remote stuff')
+		assert.strictEqual(r.has_conflicts, true)
+	})
+})

package/src/validation/conflict_marker_rules.js

@@ -0,0 +1,54 @@
+const fs = require('fs')
+const path = require('path')
+const { error: { catch_errors } } = require('puffy-core')
+
+const MARKER_RE = /^<{7}/
+
+const result = (file, line_numbers, marker_count) => ({
+	file,
+	field: null,
+	rule: 'no_conflict_markers',
+	severity: 'error',
+	message: `Unresolved merge conflict markers (${marker_count} region${marker_count === 1 ? '' : 's'}, line${line_numbers.length === 1 ? '' : 's'} ${line_numbers.join(', ')})`,
+	line_numbers,
+	marker_count
+})
+
+/**
+ * Scans all files in a skill directory for conflict markers (`<<<<<<< LOCAL`).
+ * Returns error results for each file containing markers.
+ * Skips dotfiles (consistent with hash_directory exclusions).
+ *
+ * @param {string} skill_dir - Absolute path to the skill directory
+ * @returns {[errors, results[]]} — results with severity 'error' for each file with markers
+ */
+const validate_no_conflict_markers = (skill_dir) => catch_errors('Failed to check conflict markers', async () => {
+	const results = []
+	const walk = async (dir, prefix) => {
+		let items
+		try { items = await fs.promises.readdir(dir, { withFileTypes: true }) } catch { return }
+		for (const item of items) {
+			if (item.name.startsWith('.')) continue
+			const rel = prefix ? `${prefix}/${item.name}` : item.name
+			const full = path.join(dir, item.name)
+			if (item.isDirectory()) {
+				await walk(full, rel)
+			} else {
+				let content
+				try { content = await fs.promises.readFile(full, 'utf-8') } catch { continue }
+				const lines = content.split('\n')
+				const line_numbers = []
+				for (let i = 0; i < lines.length; i++) {
+					if (MARKER_RE.test(lines[i])) line_numbers.push(i + 1)
+				}
+				if (line_numbers.length > 0) {
+					results.push(result(rel, line_numbers, line_numbers.length))
+				}
+			}
+		}
+	}
+	await walk(skill_dir, '')
+	return results
+})
+
+module.exports = { validate_no_conflict_markers }

package/src/validation/conflict_marker_rules.test.js

@@ -0,0 +1,90 @@
+const { describe, it, beforeEach, afterEach } = require('node:test')
+const assert = require('node:assert/strict')
+const fs = require('fs')
+const path = require('path')
+const os = require('os')
+const { validate_no_conflict_markers } = require('./conflict_marker_rules')
+
+const make_temp_dir = () => fs.mkdtempSync(path.join(os.tmpdir(), 'conflict-marker-test-'))
+const clean = (dir) => fs.rmSync(dir, { recursive: true, force: true })
+
+describe('validate_no_conflict_markers', () => {
+	let dir
+
+	beforeEach(() => { dir = make_temp_dir() })
+	afterEach(() => { clean(dir) })
+
+	it('returns error for file with <<<<<<< LOCAL marker', async () => {
+		fs.writeFileSync(path.join(dir, 'SKILL.md'), 'line1\n<<<<<<< LOCAL\nlocal\n=======\nremote\n>>>>>>> REMOTE\nline2')
+		const [err, results] = await validate_no_conflict_markers(dir)
+		assert.strictEqual(err, null)
+		assert.strictEqual(results.length, 1)
+		assert.strictEqual(results[0].severity, 'error')
+		assert.strictEqual(results[0].file, 'SKILL.md')
+		assert.deepStrictEqual(results[0].line_numbers, [2])
+		assert.strictEqual(results[0].marker_count, 1)
+	})
+
+	it('catches partial markers (only <<<<<<< without =======)', async () => {
+		fs.writeFileSync(path.join(dir, 'test.md'), 'some text\n<<<<<<< orphan marker\nmore text')
+		const [err, results] = await validate_no_conflict_markers(dir)
+		assert.strictEqual(err, null)
+		assert.strictEqual(results.length, 1)
+		assert.strictEqual(results[0].file, 'test.md')
+	})
+
+	it('returns empty for clean files', async () => {
+		fs.writeFileSync(path.join(dir, 'clean.md'), '# Clean file\n\nNo conflicts here.')
+		const [err, results] = await validate_no_conflict_markers(dir)
+		assert.strictEqual(err, null)
+		assert.strictEqual(results.length, 0)
+	})
+
+	it('reports multiple conflict regions in one file', async () => {
+		const content = [
+			'line1',
+			'<<<<<<< LOCAL',
+			'a',
+			'=======',
+			'b',
+			'>>>>>>> REMOTE',
+			'middle',
+			'<<<<<<< LOCAL',
+			'c',
+			'=======',
+			'd',
+			'>>>>>>> REMOTE',
+			'end'
+		].join('\n')
+		fs.writeFileSync(path.join(dir, 'multi.md'), content)
+		const [err, results] = await validate_no_conflict_markers(dir)
+		assert.strictEqual(err, null)
+		assert.strictEqual(results.length, 1)
+		assert.deepStrictEqual(results[0].line_numbers, [2, 8])
+		assert.strictEqual(results[0].marker_count, 2)
+	})
+
+	it('scans nested directories recursively', async () => {
+		const sub = path.join(dir, 'references')
+		fs.mkdirSync(sub)
+		fs.writeFileSync(path.join(sub, 'ref.md'), '<<<<<<< LOCAL\nstuff\n=======\nother\n>>>>>>> REMOTE')
+		const [err, results] = await validate_no_conflict_markers(dir)
+		assert.strictEqual(err, null)
+		assert.strictEqual(results.length, 1)
+		assert.strictEqual(results[0].file, 'references/ref.md')
+	})
+
+	it('excludes dotfiles', async () => {
+		fs.writeFileSync(path.join(dir, '.hidden'), '<<<<<<< LOCAL\nstuff')
+		fs.writeFileSync(path.join(dir, 'visible.md'), 'clean')
+		const [err, results] = await validate_no_conflict_markers(dir)
+		assert.strictEqual(err, null)
+		assert.strictEqual(results.length, 0)
+	})
+
+	it('handles empty directory', async () => {
+		const [err, results] = await validate_no_conflict_markers(dir)
+		assert.strictEqual(err, null)
+		assert.strictEqual(results.length, 0)
+	})
+})