happyskills 0.19.0 → 0.21.0

package/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.21.0] - 2026-03-30
+
+### Changed
+- Upgrade `check` and `refresh` from semver-only to commit-level comparison (`base_commit` vs remote head) for accurate divergence detection — catches divergence even when version strings match (e.g., after force-publish). Falls back to version comparison for old lock files without `base_commit`.
+
+### Added
+- Add `conflicts` status to `check` command — detects unresolved merge conflicts from the lock file's `conflict_files` field without disk I/O. JSON output now includes `conflicts_count`.
+- Add local modification protection to `refresh` — skills with local edits are skipped with a warning and `happyskills pull` suggestion instead of being silently overwritten. JSON output includes `skipped` array with `{ skill, reason, suggestion }` per entry.
+
+## [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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "happyskills",
-	"version": "0.19.0",
+	"version": "0.21.0",
 	"description": "Package manager for AI agent skills",
 	"license": "SEE LICENSE IN LICENSE",
 	"author": "Nicolas Dao <nic@cloudlesslabs.com> (https://cloudlesslabs.com)",

package/src/commands/check.js

@@ -1,7 +1,6 @@
 const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
 const { read_lock, get_all_locked_skills } = require('../lock/reader')
 const repos_api = require('../api/repos')
-const { gt } = require('../utils/semver')
 const { print_help, print_table, print_json, print_info, print_success, print_warn, print_hint, code } = require('../ui/output')
 const { green, yellow, red } = require('../ui/colors')
 const { exit_with_error } = require('../utils/errors')
@@ -68,13 +67,17 @@ const run = (args) => catch_errors('Check failed', async () => {
 	} else {
 		for (const [name, data] of to_check) {
 			const info = batch_data?.results?.[name]
-			if (info?.access_denied) {
+			const has_conflicts = (data.conflict_files || []).length > 0
+			if (has_conflicts) {
+				results.push({ skill: name, installed: data.version, latest: info?.latest_version || '-', status: 'conflicts' })
+			} else if (info?.access_denied) {
 				results.push({ skill: name, installed: data.version, latest: '-', status: 'no-access' })
 			} else if (!info || !info.latest_version) {
 				results.push({ skill: name, installed: data.version, latest: '-', status: 'unknown' })
-			} else if (info.latest_version === data.version) {
-				results.push({ skill: name, installed: data.version, latest: info.latest_version, status: 'up-to-date' })
-			} else if (gt(info.latest_version, data.version)) {
+			} else if (data.base_commit && info.commit && data.base_commit !== info.commit) {
+				results.push({ skill: name, installed: data.version, latest: info.latest_version, status: 'outdated' })
+			} else if (!data.base_commit && info.latest_version !== data.version) {
+				// Fallback to version comparison for old lock files without base_commit
 				results.push({ skill: name, installed: data.version, latest: info.latest_version, status: 'outdated' })
 			} else {
 				results.push({ skill: name, installed: data.version, latest: info.latest_version, status: 'up-to-date' })
@@ -85,13 +88,15 @@ const run = (args) => catch_errors('Check failed', async () => {
 	if (args.flags.json) {
 		const outdated_count = results.filter(r => r.status === 'outdated').length
 		const up_to_date_count = results.filter(r => r.status === 'up-to-date').length
-		print_json({ data: { results, outdated_count, up_to_date_count } })
+		const conflicts_count = results.filter(r => r.status === 'conflicts').length
+		print_json({ data: { results, outdated_count, up_to_date_count, conflicts_count } })
 		return
 	}
 
 	const status_colors = {
 		'up-to-date': green,
 		'outdated': yellow,
+		'conflicts': red,
 		'no-access': yellow,
 		'error': red,
 		'unknown': (s) => s
@@ -107,11 +112,17 @@ const run = (args) => catch_errors('Check failed', async () => {
 	print_table(['Skill', 'Installed', 'Latest', 'Status'], rows)
 
 	const outdated = results.filter(r => r.status === 'outdated')
+	const conflicts = results.filter(r => r.status === 'conflicts')
 	const no_access = results.filter(r => r.status === 'no-access')
+	if (conflicts.length > 0) {
+		console.log()
+		print_warn(`${conflicts.length} skill(s) have unresolved merge conflicts.`)
+		print_hint(`Run ${code('happyskills status')} for details.`)
+	}
 	if (outdated.length > 0) {
 		console.log()
 		print_info(`Run ${code('happyskills update')} to upgrade ${outdated.length} skill(s).`)
-	} else if (results.every(r => r.status === 'up-to-date')) {
+	} else if (conflicts.length === 0 && results.every(r => r.status === 'up-to-date')) {
 		console.log()
 		print_success('All skills are up to date.')
 	}

package/src/commands/pull.js

@@ -5,7 +5,7 @@ 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')
@@ -33,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) => {
@@ -103,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
@@ -229,8 +233,21 @@ const run = (args) => catch_errors('Pull failed', async () => {
 					// 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
+					})
 				}
-				// Local modified, remote deleted — keep local as-is
 				continue
 			}
 
@@ -246,9 +263,13 @@ const run = (args) => catch_errors('Pull failed', async () => {
 					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')
+				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 (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)
@@ -256,6 +277,7 @@ const run = (args) => catch_errors('Pull failed', async () => {
 				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)
@@ -264,6 +286,7 @@ const run = (args) => catch_errors('Pull failed', async () => {
 				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 })
 				}
 			}
 		}
@@ -277,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)
@@ -305,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)
@@ -331,7 +399,9 @@ const run = (args) => catch_errors('Pull failed', async () => {
 
 	if (args.flags.json) {
 		const status = conflict_files.length > 0 ? 'conflicts' : 'merged'
-		print_json({ data: { status, report, conflict_files, json_conflicts } })
+		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) {

package/src/commands/refresh.js

@@ -1,13 +1,13 @@
 const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
 const { install } = require('../engine/installer')
 const { read_lock, get_all_locked_skills } = require('../lock/reader')
+const { detect_status } = require('../merge/detector')
 const repos_api = require('../api/repos')
-const { gt } = require('../utils/semver')
 const { print_help, print_table, print_json, print_info, print_success, print_warn, print_hint, code } = require('../ui/output')
 const { green, yellow, red } = require('../ui/colors')
 const { create_spinner } = require('../ui/spinner')
 const { exit_with_error } = require('../utils/errors')
-const { find_project_root, lock_root } = require('../config/paths')
+const { find_project_root, lock_root, skills_dir, skill_install_dir } = require('../config/paths')
 const { EXIT_CODES } = require('../constants')
 
 const HELP_TEXT = `Usage: happyskills refresh [options]
@@ -78,9 +78,10 @@ const run = (args) => catch_errors('Refresh failed', async () => {
 				results.push({ skill: name, installed: data.version, latest: '-', status: 'no-access' })
 			} else if (!info || !info.latest_version) {
 				results.push({ skill: name, installed: data.version, latest: '-', status: 'unknown' })
-			} else if (info.latest_version === data.version) {
-				results.push({ skill: name, installed: data.version, latest: info.latest_version, status: 'up-to-date' })
-			} else if (gt(info.latest_version, data.version)) {
+			} else if (data.base_commit && info.commit && data.base_commit !== info.commit) {
+				results.push({ skill: name, installed: data.version, latest: info.latest_version, status: 'outdated' })
+			} else if (!data.base_commit && info.latest_version !== data.version) {
+				// Fallback to version comparison for old lock files without base_commit
 				results.push({ skill: name, installed: data.version, latest: info.latest_version, status: 'outdated' })
 			} else {
 				results.push({ skill: name, installed: data.version, latest: info.latest_version, status: 'up-to-date' })
@@ -125,12 +126,29 @@ const run = (args) => catch_errors('Refresh failed', async () => {
 		}
 	}
 
-	// 5. Update outdated skills
+	// 5. Detect local modifications before updating
+	const base_dir = skills_dir(is_global, project_root)
+	const skipped = []
+	const safe_to_update = []
+
+	for (const r of outdated) {
+		const lock_entry = skills[r.skill]
+		const short_name = r.skill.split('/')[1] || r.skill
+		const dir = skill_install_dir(base_dir, short_name)
+		const [, det] = await detect_status(lock_entry, dir)
+		if (det?.local_modified) {
+			skipped.push({ skill: r.skill, reason: 'local_modifications', suggestion: `happyskills pull ${r.skill}` })
+		} else {
+			safe_to_update.push(r)
+		}
+	}
+
+	// 6. Update safe skills
 	const options = { global: is_global, fresh: true, agents: args.flags.agents || undefined, project_root }
 	const updated = []
 	const update_errors = []
 
-	for (const r of outdated) {
+	for (const r of safe_to_update) {
 		const update_spinner = !args.flags.json ? create_spinner(`Updating ${r.skill}…`) : null
 		const [errors, result] = await install(r.skill, options)
 		if (errors) {
@@ -144,7 +162,7 @@ const run = (args) => catch_errors('Refresh failed', async () => {
 		}
 	}
 
-	// 6. Output results
+	// 7. Output results
 	if (args.flags.json) {
 		print_json({
 			data: {
@@ -152,6 +170,7 @@ const run = (args) => catch_errors('Refresh failed', async () => {
 				outdated_count: outdated.length,
 				up_to_date_count: up_to_date.length,
 				updated,
+				skipped,
 				already_up_to_date: up_to_date.map(r => ({ skill: r.skill, version: r.installed })),
 				errors: update_errors
 			}
@@ -159,6 +178,14 @@ const run = (args) => catch_errors('Refresh failed', async () => {
 		return
 	}
 
+	if (skipped.length > 0) {
+		console.log()
+		print_warn(`Skipped ${skipped.length} skill(s) with local modifications:`)
+		for (const s of skipped) {
+			print_info(`  ${s.skill}`)
+		}
+		print_hint(`Use ${code('happyskills pull <skill>')} to merge remote changes.`)
+	}
 	if (updated.length > 0) {
 		console.log()
 		print_success(`Updated ${updated.length} skill(s).`)

package/src/merge/report.js

@@ -4,6 +4,10 @@
  * The report is consumed by both human-readable CLI output and the AI agent
  * semantic review layer (Layer 2). It must include enough data for the agent
  * to reason about conflicts without additional API calls.
+ *
+ * When --full-report is used, file entries include inline content fields
+ * (base_content, local_content, remote_content, merged_content) so the
+ * consuming LLM can perform semantic review in a single pass.
  */
 
 const CLASSIFICATIONS = [
@@ -13,6 +17,12 @@ const CLASSIFICATIONS = [
 	'unchanged'
 ]
 
+const SEMANTIC_REVIEW_CLASSIFICATIONS = new Set([
+	'both_modified',
+	'remote_only_modified', 'local_only_modified',
+	'remote_only_added', 'local_only_added'
+])
+
 const build_report = (skill, base_version, remote_version, classified) => {
 	const files = []
 	let clean = 0
@@ -56,4 +66,79 @@ const build_report = (skill, base_version, remote_version, classified) => {
 	}
 }
 
-module.exports = { build_report, CLASSIFICATIONS }
+/**
+ * Enrich a report file entry with inline content for --full-report mode.
+ * Only sets fields that are provided (non-undefined).
+ *
+ * @param {object} report_file - A file entry from report.files
+ * @param {{ base?: string, local?: string, remote?: string, merged?: string }} content
+ */
+const enrich_file_content = (report_file, content) => {
+	if (content.base !== undefined) report_file.base_content = content.base
+	if (content.local !== undefined) report_file.local_content = content.local
+	if (content.remote !== undefined) report_file.remote_content = content.remote
+	if (content.merged !== undefined) report_file.merged_content = content.merged
+}
+
+/**
+ * Build action-typed resolution steps from the merge report.
+ * Steps are deterministic — computed from classification data and merge results.
+ * The consuming LLM adds intelligence (semantic reasoning, natural language).
+ *
+ * @param {object} report - The merge report from build_report
+ * @param {Array} [json_conflicts] - Conflicts from skill.json merge
+ * @returns {Array} Ordered resolution steps
+ */
+const build_resolution_steps = (report, json_conflicts = []) => {
+	const steps = []
+
+	// 1. Conflict markers — must be resolved before publishing
+	const marker_files = report.files.filter(f => f.conflict_written)
+	if (marker_files.length > 0) {
+		steps.push({
+			action: 'resolve_conflict_markers',
+			files: marker_files.map(f => f.path),
+			description: 'Files with conflict markers that must be manually resolved'
+		})
+	}
+
+	// 2. JSON field suggestions — review auto-applied defaults
+	if (json_conflicts.length > 0) {
+		steps.push({
+			action: 'review_json_suggestions',
+			files: ['skill.json'],
+			suggestions: json_conflicts.map(c => ({
+				field: c.field,
+				value: c.suggestion,
+				reason: suggestion_reason(c.field)
+			}))
+		})
+	}
+
+	// 3. Semantic review — all files where concurrent changes may contradict
+	const semantic_files = report.files.filter(f => SEMANTIC_REVIEW_CLASSIFICATIONS.has(f.classification))
+	if (semantic_files.length > 0) {
+		steps.push({
+			action: 'semantic_review',
+			files: semantic_files.map(f => f.path),
+			description: 'Review these files for logical consistency — changes from both sides may introduce semantic contradictions even without text conflicts'
+		})
+	}
+
+	// 4. Verify — always present as final step
+	steps.push({
+		action: 'verify',
+		command: 'happyskills status',
+		description: 'Verify all conflicts are resolved before publishing'
+	})
+
+	return steps
+}
+
+const suggestion_reason = (field) => {
+	if (field === 'version') return 'Next patch after the higher version'
+	if (field.startsWith('dependencies.')) return 'Published version wins by default'
+	return 'Remote value used as default'
+}
+
+module.exports = { build_report, enrich_file_content, build_resolution_steps, CLASSIFICATIONS }

package/src/merge/report.test.js

@@ -1,19 +1,26 @@
 const { describe, it } = require('node:test')
 const assert = require('node:assert/strict')
-const { build_report, CLASSIFICATIONS } = require('./report')
+const { build_report, enrich_file_content, build_resolution_steps, CLASSIFICATIONS } = require('./report')
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+const make_classified = (overrides = {}) => ({
+	remote_only_modified: [], local_only_modified: [], both_modified: [],
+	remote_only_added: [], local_only_added: [],
+	remote_only_deleted: [], local_only_deleted: [],
+	unchanged: [],
+	...overrides
+})
+
+// ─── build_report ─────────────────────────────────────────────────────────────
 
 describe('build_report', () => {
 	it('produces v1 contract fields', () => {
-		const classified = {
+		const classified = make_classified({
 			remote_only_modified: [{ path: 'a.md', base_sha: '111', remote_sha: '222' }],
-			local_only_modified: [],
 			both_modified: [{ path: 'b.md', base_sha: '333', local_sha: '444', remote_sha: '555' }],
-			remote_only_added: [],
-			local_only_added: [],
-			remote_only_deleted: [],
-			local_only_deleted: [],
 			unchanged: [{ path: 'c.md', sha: '666' }]
-		}
+		})
 		const report = build_report('acme/deploy-aws', '1.15.0', '1.17.0', classified)
 
 		assert.strictEqual(report.skill, 'acme/deploy-aws')
@@ -24,16 +31,13 @@ describe('build_report', () => {
 	})
 
 	it('summary counts match file array', () => {
-		const classified = {
+		const classified = make_classified({
 			remote_only_modified: [{ path: 'a.md', base_sha: '1', remote_sha: '2' }],
 			local_only_modified: [{ path: 'b.md', base_sha: '3', local_sha: '4' }],
-			both_modified: [],
 			remote_only_added: [{ path: 'c.md', remote_sha: '5' }],
-			local_only_added: [],
 			remote_only_deleted: [{ path: 'd.md' }],
-			local_only_deleted: [],
 			unchanged: [{ path: 'e.md', sha: '6' }, { path: 'f.md', sha: '7' }]
-		}
+		})
 		const report = build_report('test/skill', '1.0.0', '2.0.0', classified)
 
 		assert.strictEqual(report.files.length, report.summary.auto_merged + report.summary.conflicted)
@@ -41,16 +45,10 @@ describe('build_report', () => {
 	})
 
 	it('classifications are from the defined vocabulary', () => {
-		const classified = {
+		const classified = make_classified({
 			remote_only_modified: [{ path: 'a.md', base_sha: '1', remote_sha: '2' }],
-			local_only_modified: [],
 			both_modified: [{ path: 'b.md', base_sha: '3', local_sha: '4', remote_sha: '5' }],
-			remote_only_added: [],
-			local_only_added: [],
-			remote_only_deleted: [],
-			local_only_deleted: [],
-			unchanged: []
-		}
+		})
 		const report = build_report('test/skill', '1.0.0', '2.0.0', classified)
 
 		for (const file of report.files) {
@@ -59,12 +57,9 @@ describe('build_report', () => {
 	})
 
 	it('handles null versions gracefully', () => {
-		const classified = {
-			remote_only_modified: [], local_only_modified: [], both_modified: [],
-			remote_only_added: [], local_only_added: [],
-			remote_only_deleted: [], local_only_deleted: [],
+		const classified = make_classified({
 			unchanged: [{ path: 'a.md', sha: '111' }]
-		}
+		})
 		const report = build_report('test/skill', null, null, classified)
 		assert.strictEqual(report.base_version, null)
 		assert.strictEqual(report.remote_version, null)
@@ -72,14 +67,169 @@ describe('build_report', () => {
 	})
 
 	it('unchanged files are not included in files array', () => {
-		const classified = {
-			remote_only_modified: [], local_only_modified: [], both_modified: [],
-			remote_only_added: [], local_only_added: [],
-			remote_only_deleted: [], local_only_deleted: [],
+		const classified = make_classified({
 			unchanged: [{ path: 'a.md', sha: '111' }, { path: 'b.md', sha: '222' }]
-		}
+		})
 		const report = build_report('test/skill', '1.0.0', '1.0.0', classified)
 		assert.strictEqual(report.files.length, 0)
 		assert.strictEqual(report.summary.clean, 2)
 	})
 })
+
+// ─── enrich_file_content ──────────────────────────────────────────────────────
+
+describe('enrich_file_content', () => {
+	it('sets all provided content fields', () => {
+		const file = { path: 'SKILL.md', classification: 'both_modified' }
+		enrich_file_content(file, {
+			base: 'base text',
+			local: 'local text',
+			remote: 'remote text',
+			merged: 'merged text'
+		})
+		assert.strictEqual(file.base_content, 'base text')
+		assert.strictEqual(file.local_content, 'local text')
+		assert.strictEqual(file.remote_content, 'remote text')
+		assert.strictEqual(file.merged_content, 'merged text')
+	})
+
+	it('only sets fields that are provided (non-undefined)', () => {
+		const file = { path: 'a.md', classification: 'remote_only_modified' }
+		enrich_file_content(file, { remote: 'remote text' })
+		assert.strictEqual(file.remote_content, 'remote text')
+		assert.strictEqual(file.base_content, undefined)
+		assert.strictEqual(file.local_content, undefined)
+		assert.strictEqual(file.merged_content, undefined)
+	})
+
+	it('does not set fields for undefined values', () => {
+		const file = { path: 'a.md' }
+		enrich_file_content(file, { base: undefined, local: 'text' })
+		assert.ok(!('base_content' in file))
+		assert.strictEqual(file.local_content, 'text')
+	})
+
+	it('handles empty string content', () => {
+		const file = { path: 'a.md' }
+		enrich_file_content(file, { base: '', remote: '' })
+		assert.strictEqual(file.base_content, '')
+		assert.strictEqual(file.remote_content, '')
+	})
+})
+
+// ─── build_resolution_steps ───────────────────────────────────────────────────
+
+describe('build_resolution_steps', () => {
+	it('always includes verify step as last step', () => {
+		const report = build_report('test/skill', '1.0.0', '2.0.0', make_classified({
+			unchanged: [{ path: 'a.md', sha: '111' }]
+		}))
+		const steps = build_resolution_steps(report)
+		assert.strictEqual(steps.length, 1)
+		assert.strictEqual(steps[0].action, 'verify')
+		assert.strictEqual(steps[0].command, 'happyskills status')
+	})
+
+	it('includes resolve_conflict_markers for files with conflict_written', () => {
+		const report = build_report('test/skill', '1.0.0', '2.0.0', make_classified({
+			both_modified: [
+				{ path: 'SKILL.md', base_sha: '1', local_sha: '2', remote_sha: '3' },
+				{ path: 'ref.md', base_sha: '4', local_sha: '5', remote_sha: '6' }
+			]
+		}))
+		// Simulate pull.js marking conflict_written
+		report.files[0].conflict_written = true
+
+		const steps = build_resolution_steps(report)
+		const marker_step = steps.find(s => s.action === 'resolve_conflict_markers')
+		assert.ok(marker_step)
+		assert.deepStrictEqual(marker_step.files, ['SKILL.md'])
+	})
+
+	it('includes review_json_suggestions when json_conflicts exist', () => {
+		const report = build_report('test/skill', '1.0.0', '2.0.0', make_classified({
+			both_modified: [{ path: 'skill.json', base_sha: '1', local_sha: '2', remote_sha: '3' }]
+		}))
+		const json_conflicts = [
+			{ field: 'version', base_value: '1.0.0', local_value: '1.1.0', remote_value: '1.2.0', suggestion: '1.2.1' },
+			{ field: 'dependencies.acme/utils', base_value: '1.0.0', local_value: '2.0.0', remote_value: '3.0.0', suggestion: '3.0.0' }
+		]
+
+		const steps = build_resolution_steps(report, json_conflicts)
+		const json_step = steps.find(s => s.action === 'review_json_suggestions')
+		assert.ok(json_step)
+		assert.deepStrictEqual(json_step.files, ['skill.json'])
+		assert.strictEqual(json_step.suggestions.length, 2)
+		assert.strictEqual(json_step.suggestions[0].field, 'version')
+		assert.strictEqual(json_step.suggestions[0].value, '1.2.1')
+		assert.strictEqual(json_step.suggestions[0].reason, 'Next patch after the higher version')
+		assert.strictEqual(json_step.suggestions[1].reason, 'Published version wins by default')
+	})
+
+	it('includes semantic_review for all modified/added classifications', () => {
+		const report = build_report('test/skill', '1.0.0', '2.0.0', make_classified({
+			both_modified: [{ path: 'SKILL.md', base_sha: '1', local_sha: '2', remote_sha: '3' }],
+			remote_only_modified: [{ path: 'refs/auth.md', base_sha: '4', remote_sha: '5' }],
+			local_only_modified: [{ path: 'refs/deploy.md', base_sha: '6', local_sha: '7' }],
+			remote_only_added: [{ path: 'refs/new-remote.md', remote_sha: '8' }],
+			local_only_added: [{ path: 'refs/new-local.md', local_sha: '9' }],
+			remote_only_deleted: [{ path: 'old.md', base_sha: '10' }],
+			local_only_deleted: [{ path: 'legacy.md', base_sha: '11' }]
+		}))
+
+		const steps = build_resolution_steps(report)
+		const semantic_step = steps.find(s => s.action === 'semantic_review')
+		assert.ok(semantic_step)
+		// Should include all modified/added but NOT deleted or unchanged
+		assert.deepStrictEqual(semantic_step.files, [
+			'refs/auth.md', 'refs/deploy.md', 'SKILL.md',
+			'refs/new-remote.md', 'refs/new-local.md'
+		])
+	})
+
+	it('excludes semantic_review when only deletions exist', () => {
+		const report = build_report('test/skill', '1.0.0', '2.0.0', make_classified({
+			remote_only_deleted: [{ path: 'old.md', base_sha: '1' }]
+		}))
+
+		const steps = build_resolution_steps(report)
+		assert.ok(!steps.find(s => s.action === 'semantic_review'))
+		assert.strictEqual(steps.length, 1) // only verify
+	})
+
+	it('steps are ordered: markers → json → semantic → verify', () => {
+		const report = build_report('test/skill', '1.0.0', '2.0.0', make_classified({
+			both_modified: [{ path: 'SKILL.md', base_sha: '1', local_sha: '2', remote_sha: '3' }],
+			remote_only_modified: [{ path: 'auth.md', base_sha: '4', remote_sha: '5' }]
+		}))
+		report.files.find(f => f.path === 'SKILL.md').conflict_written = true
+
+		const json_conflicts = [{ field: 'version', suggestion: '2.0.1' }]
+		const steps = build_resolution_steps(report, json_conflicts)
+
+		const actions = steps.map(s => s.action)
+		assert.deepStrictEqual(actions, [
+			'resolve_conflict_markers',
+			'review_json_suggestions',
+			'semantic_review',
+			'verify'
+		])
+	})
+
+	it('handles empty report gracefully', () => {
+		const report = build_report('test/skill', '1.0.0', '1.0.0', make_classified())
+		const steps = build_resolution_steps(report)
+		assert.strictEqual(steps.length, 1)
+		assert.strictEqual(steps[0].action, 'verify')
+	})
+
+	it('suggestion reason for generic scalar field', () => {
+		const report = build_report('test/skill', '1.0.0', '2.0.0', make_classified({
+			both_modified: [{ path: 'skill.json', base_sha: '1', local_sha: '2', remote_sha: '3' }]
+		}))
+		const json_conflicts = [{ field: 'description', suggestion: 'Remote desc' }]
+		const steps = build_resolution_steps(report, json_conflicts)
+		const json_step = steps.find(s => s.action === 'review_json_suggestions')
+		assert.strictEqual(json_step.suggestions[0].reason, 'Remote value used as default')
+	})
+})