happyskills 0.18.1 → 0.20.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/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')
+	})
+})